How FACE works

FACE — Framework for AI Context in Enterprise — is a structured methodology for giving AI tools organizational context, so they produce output that reflects how your organization actually works. FACE creates a layered knowledge base, stored in a Git repository, that any AI tool can read. It's tool-agnostic, version-controlled, and works for teams of five to enterprises with hundreds of repositories.

Without FACE, AI tools start every session from zero — they don't know your coding standards, your brand voice, your architecture decisions. With FACE, they load the right context layers for the task and deliver output specific to how you operate.

FACE organizes knowledge into four numbered folders, each with a focused purpose:

• 1-company — who you are: identity, team, structure, brand, policies.
• 2-departments — how each team works: engineering standards, legal templates, marketing voice rules, finance rhythms.
• 3-products — what you build: per-product overview, architecture, pricing, roadmap.
• 4-projects — what you're working on now: per-project brief, decisions, retros.

The numbering enforces a navigation order so things stay in a predictable place. Folder names can be customized per organization; the numbers can't.

An owner is the human accountable for the quality and accuracy of a specific FACE layer. Their name lives in 0-meta/kb-config.yaml under that layer. Every pull request that touches files in their layer routes to them for review — they merge the good changes and push back on the rest. This keeps content quality high without requiring everyone to know every layer; ownership is distributed but explicit.

FACE requires at least one human owner per layer. A layer with no owner is a layer no one is accountable for, which means quality drifts.

Contributors are everyone else — the engineers, designers, analysts, and operators who notice that something in the KB is wrong, outdated, or missing. They open pull requests with the fix or addition. The layer's owner reviews. Contributors don't need permission to suggest a change, only to merge one.

Aria isn't tied to a single model vendor. Each org picks a provider — Anthropic, OpenAI, or Google Gemini — and pastes its own API key. From that moment on, every chat turn Aria makes goes from this app straight to that provider using your org's key.

What that means in practice:

• The provider sees your prompts directly. ABQ doesn't proxy the content; we just route the request. Your AI vendor's privacy policy applies to the prompts and the responses.
• The key is stored encrypted at rest on this app's database, scoped to your org. Members can't read its value. The decryption key only the running app holds — ABQ operators can't pull tokens out of the database.
• Rotate or switch any time. Change provider, paste a new key, pick a new model — the dock's reconnect flow handles it without leaving the conversation.
• No ABQ-pooled inference. We don't bundle calls from multiple customers through a shared key. Your usage shows up on your provider bill against your key.

FACE Studio is the orchestration layer between your knowledge base (in GitHub) and your AI assistant (Aria). The KB content — the actual files — sits in your own GitHub repository the whole time:

• Reads are live. When Aria, the file viewer, or the search needs a file, it's fetched from your GitHub repo using your token at request time. We don't snapshot or cache the bytes.
• Writes go through pull requests. When Aria proposes a change, the change is committed to a branch in your repo and opened as a PR for review — there's no "ABQ database of edits" intermediating that flow. Approve in the app or in GitHub; either path merges into your repo.
• Your GitHub token is encrypted per user. Used only to read/write the repos you've authorised. Sign out and back in (or revoke from your GitHub settings) to invalidate it.

If you stopped using ABQ tomorrow, your KB would still be a fully-functional Git repo. Nothing's locked inside our servers.

A complete map of where each kind of data sits:

• KB content (your documents) — in your GitHub repo. Not replicated on ABQ servers. See Your KB content stays on GitHub.
• AI provider API keys — encrypted at rest on ABQ, scoped to your org. ABQ operators can't decrypt them; only the running app can, and only to forward a request you initiated. See Your AI provider, your keys.
• Prompts + AI responses — flow between the app, your AI provider, and your GitHub repo. ABQ doesn't store the content of either; we store the transcript metadata so you can come back to a chat (see next bullet).
• Conversation transcripts — stored so the chat picker can resurface your past chats. Scoped to your org by row-level security; deletable from the chat picker.
• GitHub tokens — encrypted per user.
• Routing metadata (which org, which KB, which model, message timestamps) — visible to ABQ so the app can render the right surfaces and the right org gets billed for the right usage.

The short version: ABQ is the conductor, not the warehouse. The substantive data — your documents, your AI tokens in cleartext, the content of the prompts you send your provider — flows past ABQ rather than resting on it.

AGENTS_BOOT.md is the single source of truth for how an AI agent should approach this knowledge base. It declares: which identity file to load (telling the agent what role to play), which context layers to load (in what order), and what the working agreements are (e.g. all changes via pull request). Boot adapters for each AI tool — CLAUDE.md, AGENTS.md (OpenAI Codex), GEMINI.md, .cursor/rules/agent-boot.md — exist purely to redirect the tool to AGENTS_BOOT.md.

The upshot: every AI tool in your team reads the same instructions, and editing AGENTS_BOOT.md updates the behavior of all of them at once.

Different AI tools look for their boot instructions in different filenames at different paths. Claude Code reads CLAUDE.md; OpenAI Codex reads AGENTS.md; Gemini CLI reads GEMINI.md; Cursor reads .cursor/rules/agent-boot.md. A boot adapter is the per-tool file that satisfies the tool's expected location and immediately redirects to AGENTS_BOOT.md. Adding a new AI tool to your KB is one adapter file — no other changes needed.

0-meta/kb-config.yaml is the FACE-level metadata file for your KB. It records which user is the owner of each layer (used for PR review routing), which optional extensions are enabled, and other framework-level configuration. FACE Studio reads and writes it; humans can edit it directly via Git when needed.

Aria is ABQ's general-purpose assistant for working inside a FACE knowledge base. She has read the entire KB and knows the FACE framework: which layer a new piece of content belongs in, how layer ownership works, what the boot adapters do.

Things to ask Aria:

• Draft a new page (e.g. "Set up our company identity").
• Restructure existing content (e.g. "Move the pricing doc out of 3-products").
• Import from a connected source (e.g. "Pull in our Notion product roadmap").

Things Aria won't do unprompted: change ownership, merge pull requests, or modify 5-agents/ config. Those are deliberate human decisions.

For where the prompts you send, the keys she uses, and her replies actually live, see Data flow & privacy below.