fak

# fak documentation map for agents

`fak` is an agent runtime: the operator-controlled boundary for cache and context, model routing, tool authority, memory, observability, and native inference. Its technical architecture is the **Fused Agent Kernel** (an **agent kernel**). Use this map to locate the current authority for a task without reading the human front-door narrative.

**Default:** read [`AGENTS.md`](AGENTS.md) before changing the repository, then open only the authority for your task below.

**Current product focus:** use [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md) for the outcome-first map of token savings, avoided turns, cache/context reuse, model routing, and live session control. Security remains indexed as a supporting floor.

**Canonical problem map:** use [`docs/problems-we-solve.md`](docs/problems-we-solve.md) for
the “don’t make me think” direction, the four stable problem IDs (`P1` context, `P2`
net-true efficiency, `P3` fast adaptation, `P4` integrated operations), and the frame that
connects new work to operator value. Do not turn this direction into a shipped claim; use
[`CLAIMS.md`](CLAIMS.md) for shipped/simulated/stub status.

- [Project orientation](docs/project-orientation.md): current decision record for the agent-kernel center, capability-family classifications, investment boundary, and repeatable portfolio audit

## Audience guides

- [End-to-End Inference, Agent Harness, and Memory](docs/courses/end-to-end-inference-agent-harness-memory.md): the integrated 8-module flagship course across native inference, tool use, policy, context control, durable memory, observability, and proof. Use [`LEARNING-PATH.md`](LEARNING-PATH.md) instead for the full 99-course prerequisite catalog.
- [Less context, less code](https://github.com/anthony-chaudhary/fak/blob/main/docs/explainers/less-context-less-code.md): where fak fits beside concise-output and YAGNI/minimal-code guidance.

## Key facts (for accurate answers)

- **Name:** `fak`; the technical name and architecture are the **Fused Agent Kernel** / *agent kernel*. Repository: `fak`. Language: **Go 1.26+**. License: **Apache-2.0**. Version: **0.45.0** ([`VERSION`](VERSION) is authoritative).
- **Public category:** **agent runtime**. In fak, that means the operator-controlled boundary for cache and context, model routing, tool authority, memory, observability, and native inference. These capabilities are available by operating mode and claim status; the category does not promote roadmap work to shipped behavior.
- **Disambiguated search terms:** `fak agent runtime` (the public category), `fak agent kernel` and `fused agent kernel` (the technical architecture and name), `fak serve` (the gateway verb), `fak guard`, `treat the tool call like a syscall`, `default-deny tool-call gate`, `prompt-injection result quarantine`, `addressable KV cache`, `long-session prompt cache`, `cost-aware model routing for agents`, `managed agent runtime`, `MCP tool poisoning defense`, `AI agent least-privilege tool access`, `tamper-evident agent tool-call audit`. The bare word `fak` is dominated by homophone and F.A.K.-acronym noise, so always pair it with one of these. The full 76-term roster, including localized variants, is the generated feed [`llms-terms.txt`](llms-terms.txt) (source of record: `docs/marketing/disambiguation-terms.json`, written by `fak marketing aeo`).
- **Three adoption rungs:** (1) `fak guard` wraps the agent you already run with one command; (2) `fak serve` fronts any OpenAI-compatible server (Ollama, vLLM, cloud) with routing, policy, quarantine, and audit; (3) the fused kernel runs a local model inside the kernel's address space so the KV cache is a kernel object.
- **Serving boundary:** Proxy/gateway mode may front an explicitly selected tuned engine or hosted provider. That is external inference, not fak-native, and its engine identity stays attached to every result.
- **Native inference invariant:** [`fak-native`](docs/native-inference-goal.md) is the product and performance path for local inference and is intended to beat llama.cpp in matched, quality-constrained envelopes. llama.cpp is permitted only when explicitly selected for benchmarks, parity/reference diagnosis, migration/interoperability, or ego-free borrowing; it is never a silent fallback. A current win still requires the exact scoped row in [`BENCHMARK-AUTHORITY.md`](BENCHMARK-AUTHORITY.md).
- **Operational surface (the single-binary thesis):** the agent gateway and control plane — the OpenAI/Anthropic/MCP wires, routing, capability floor, result quarantine, audit with `X-Trace-Id` correlation, bearer and `x-api-key` auth, and Prometheus `/metrics` — collapsed into one static Go binary (two `golang.org/x` dependencies; no Python and no CUDA toolchain needed to build). Where vLLM and SGLang are multi-process Python/CUDA engines you wrap in a reverse proxy plus policy and audit layers, `fak` is that layer as a single process. The contrast is operational surface, not throughput.
- **Honest scope:** a 29-claim prior-art audit scored **0/29 novel** — every primitive is established; the contribution is the *assembly* into one in-process gate where the tool call is the checkpoint. Per-surface claim status (`SHIPPED`, `SIMULATED`, `STUB`) is tracked in [`CLAIMS.md`](CLAIMS.md); treat anything not marked `SHIPPED` as unproven.

- FAK vs DOS boundary — FAK owns agent execution; DOS owns work admission, leases, truth, liveness, and decisions; FAK workflows compose DOS: [`docs/fak-vs-dos.md`](docs/fak-vs-dos.md)
## Current authorities

- Astra formal-subagent admission, closed formal kinds, fail-closed packet schema, pin precedence, assignment digest, and ranked correctness deployment map: [`docs/astra-formal-subagents.md`](docs/astra-formal-subagents.md)
- Micro-context fabric contract and bounded 100/1k/10k floor (`microcontextdemo`): [`docs/research/micro-context-fabrics.md`](docs/research/micro-context-fabrics.md); captured stage witnesses: [`docs/research/README.md`](docs/research/README.md)
- Product scope and mode choice: [`README.md`](README.md)
- Human role map: [`START-HERE.md`](START-HERE.md)
- Documentation by audience, job, and lifecycle, plus the exhaustive repository map: [`INDEX.md`](INDEX.md)
- Agent workflow, builds, proofs, commits, and shared-tree rules: [`AGENTS.md`](AGENTS.md)
- Default documentation lookup, HEAD-only reachability census, and task-specific build/test witnesses: [`docs/dev-tooling.md`](docs/dev-tooling.md)
- Shift-left task organization — author human-readable outcome, scope, dependencies, acceptance, witness, placement, and lane before dispatch: [`docs/shift-left-task-organization.md`](docs/shift-left-task-organization.md)
- New-work defaults — ship the applied end-to-end spine first, prove its operating envelope, optimize against it, then fan out the hardening backlog with `fak issue fanout` (3 is the floor, not the target): [`docs/spine-first-defaults.md`](docs/spine-first-defaults.md)
- Positive workspace management — positive workspace construction over punitive default-deny, immutable FROZEN safety floor vs permissive convenience surface, avoiding capability laundering and doom-loops: [`docs/positive-workspace-management.md`](docs/positive-workspace-management.md)
- Contribution contract: [`CONTRIBUTING.md`](CONTRIBUTING.md)
- Claims status (`SHIPPED`, `SIMULATED`, `STUB`): [`CLAIMS.md`](CLAIMS.md)
- Fak-native execution-engine doctrine, matched-envelope rule, external-reference boundary, and deterministic docs guard: [`docs/native-inference-goal.md`](docs/native-inference-goal.md)
- Performance-RSI loop doctrine, 16 canonical dimensions, dominant bottleneck derivation, matched-baseline evidence rules, and scorecard CLI: [`docs/notes/PERFORMANCE-RSI-LOOP-DOCTRINE.md`](docs/notes/PERFORMANCE-RSI-LOOP-DOCTRINE.md)
- Memory-concept ranking dossier (superset): [`docs/superset/MEMORY-CONCEPT-RANKINGS.md`](docs/superset/MEMORY-CONCEPT-RANKINGS.md) — 10 memory concepts M1–M10 ranked fak-vs-engines with evidence, per-engine evidence tables, and adopt-or-SKIP verdicts
- [The managed-context glossary and product contract](docs/managed-context-glossary.md): the public glossary for managed context — assumption, resident view, pinned objective, budget envelope, reset transaction, context query, memory promotion, and cache state — each grounded in the shipped mechanism, stating what fak manages automatically, what it asks the user about, and what stays user-controlled. The product-facing companion to [context-is-not-memory](docs/CONTEXT-IS-NOT-MEMORY.md) (#1571, epic #1570).
- External system architecture, interfaces, and trust boundaries: [`docs/architecture.md`](docs/architecture.md)
- Builder stability and ownership ladder (CLI → semantic protocol → public Go API → sidecar → internal leaves): [`docs/builder-contract-ladder.md`](docs/builder-contract-ladder.md)
- Detailed integration architecture and extension seams: [`docs/fak/agent-integration-architecture.md`](docs/fak/agent-integration-architecture.md)
- Agent runtime category, ownership, interfaces, flow, and offline proof: [`docs/explainers/agent-runtime.md`](docs/explainers/agent-runtime.md)
- Canonical identity and nearest-contrast lookup for overloaded terms: [`docs/generated/disambiguation/INDEX.md`](docs/generated/disambiguation/INDEX.md)
- TensorRT-LLM vs SGLang and how fak fronts fleet or local inference: [`docs/explainers/tensorrt-llm-vs-sglang-and-fak.md`](docs/explainers/tensorrt-llm-vs-sglang-and-fak.md)
- One-minute offline proof: [`docs/repro-packet.md`](docs/repro-packet.md)
- One-agent management with `fak guard`: [`README.md#manage-one-local-agent-fak-guard`](README.md#manage-one-local-agent-fak-guard)
- Running that same `fak guard` seam **server-side** — a hosted harness (Claude Code / Codex / a CI runner) governed unattended in a container, with no TTY, a mounted hash-chained audit journal, a cost cap, and a supervised-restart lifecycle; the complement to the local-dev framing above and to [`docs/integrations/embed-in-your-product.md`](docs/integrations/embed-in-your-product.md) (which governs your own direct API call): [`docs/guard-server-side-client.md`](docs/guard-server-side-client.md)
- Claude Code on your own Mac's local model and many-agent cache savings (one command: `fak mac`, long form `fak claude-mac-fak`, pointing Claude Code at a Mac's own `fak serve` gateway; run many agents on your Mac with 88.2% compute reduction, flat 180 ms TTFT, 2.1 agents/GB density via Qwen2.5-7B Q8 shared-prefix KV caching; serving speed #2691/#2723 unblended): [`docs/fak/claude-mac.md`](docs/fak/claude-mac.md) · [`docs/fak/mac-agent-ui.md`](docs/fak/mac-agent-ui.md) · [`docs/cache-value-rollup.md`](docs/cache-value-rollup.md)
- Run local models on Mac (Qwen3.8 with Apple Silicon Metal acceleration, interactive REPL `fak run qwen38`, and gateway chat): [`docs/fak/mac-local-models.md`](docs/fak/mac-local-models.md)
- Run parallel subagents with zero-cold-start cache reuse using `fak up`: [`docs/subagents-guide.md`](docs/subagents-guide.md)
- Shared endpoint with `fak serve`: [`docs/fak/server-quickstart.md`](docs/fak/server-quickstart.md)
- Configuration answers (crawlable human page + inline FAQPage JSON-LD): [`docs/fak/configuration.md`](docs/fak/configuration.md)
- Configuration answers (plain text): [`llms-config.txt`](llms-config.txt)
- Configuration authority (complete flags, environment variables, precedence): [`docs/fak/server-config.md`](docs/fak/server-config.md)
- API: [`docs/fak/api-reference.md`](docs/fak/api-reference.md)
- Deployment: [`docs/fak/deployment-guide.md`](docs/fak/deployment-guide.md)
- Deploying the gateway on a **rented GPU box** (CoreWeave, Lambda, RunPod, Crusoe, Vast.ai, Nebius) — in-kernel on the GPU, or proxy in front of a co-located vLLM/SGLang; every provider row is `not yet` end-to-end witnessed: [`docs/fak/neo-cloud-deploy.md`](docs/fak/neo-cloud-deploy.md). Distinct from **fronting a hosted model API** ([`docs/supported/clouds.md`](docs/supported/clouds.md)) and from the neo-cloud **backend binding layer** ([`docs/vendor/neo-cloud-reference-architecture.md`](docs/vendor/neo-cloud-reference-architecture.md)).
- Adding a new model to the in-kernel engine — the one question that splits a one-line arch alias plus a recognition test from a `fak new-model` scaffold plus a forward pass and an oracle: [`docs/new-model-playbook.md`](docs/new-model-playbook.md)
- Canonical cross-hardware Qwen performance highlights and worker publishing route: [`docs/benchmarks/QWEN-PERFORMANCE-INDEX.md`](docs/benchmarks/QWEN-PERFORMANCE-INDEX.md)
- Detailed Qwen3.8-27B Metal result and the Qwen3.6/llama.cpp delta: [`docs/benchmarks/QWEN38-27B-LATEST.md`](docs/benchmarks/QWEN38-27B-LATEST.md)
- Routing a run difference to loader, quant, or forward when model id, quant mode, and tokens/sec all match — the model-load provenance artifact and its algebra (schema `fak-model-load-provenance/1`): [`docs/model-load-provenance-troubleshooting.md`](docs/model-load-provenance-troubleshooting.md)
- Release readiness, guarded cut/publish, verification, and rollback: [`fak release`](cmd/fak/release.go) and [`.claude/skills/release/SKILL.md`](.claude/skills/release/SKILL.md)
- Daily lock-aware shared-checkout Git hygiene, canonical verb, and proof floor: [`fak git-daily`](docs/releases/issue-5592-daily-lock-aware-git-hygiene-2026-08-08.md)
- Client and agent integrations: [`docs/integrations/`](docs/integrations/)
- Codex `UserPromptSubmit` permissive, guarded-child, and hardened modes; capability floor; `fak sessions codex-hook-install`; and `fak sessions codex-loop-hook --hardened`: [`docs/integrations/openai-codex.md#userpromptsubmit-modes`](docs/integrations/openai-codex.md#userpromptsubmit-modes)
- Scoped benchmark results, tuned baselines, artifacts, and reproduce routes: [`BENCHMARK-AUTHORITY.md`](BENCHMARK-AUTHORITY.md)
- Terminal-Bench 4 reproduction manual and parity envelope specification: [`docs/benchmarks/TERMINAL-BENCH-4-REPRODUCTION.md`](docs/benchmarks/TERMINAL-BENCH-4-REPRODUCTION.md)
- Security floor, policy configuration, evidence, and private reporting: [`SECURITY.md`](SECURITY.md)
- Enterprise-gateway governance parity — what `fak serve` covers today against the redaction, per-key rate-limit, and provider-failover checklist, and the two gaps still open: [`docs/gateway-governance-parity-audit.md`](docs/gateway-governance-parity-audit.md)
- Out-of-band operator control of a RUNNING session — the closed control vocabulary (`steer`/`redirect`/`pause`/`resume`/`cancel`/`terminate`/`throttle`/`budget`/`priority`), each op's capability + boundary + witness-of-applied + closed refusal, the `fak session` / `fak signal` / `fak ps` front door, and why `fak steering` / `fak steer` are an unrelated name collision: [docs/operator-control-plane.md](docs/operator-control-plane.md)
- Managed worker worktrees — detached per-worker build isolation, portable defaults, lifecycle operations (prepare/list/land/reap/gc), and remote crash recovery: [docs/managed-worker-worktrees.md](docs/managed-worker-worktrees.md)
- Steerability controls and appeal-channel scorecard: [docs/STEERABILITY-SCORECARD.md](docs/STEERABILITY-SCORECARD.md)
- Operator-heaviness pressure, budgets, and reduction standard: [docs/OPERATOR-HEAVINESS.md](docs/OPERATOR-HEAVINESS.md)
- Operator-steerability PRs (`fak steer prs`) — the gate/observability separation, the OSP unit, and why the overlay must never become a merge gate: [docs/operator-steerability-prs.md](docs/operator-steerability-prs.md)
- Version-everything (`fak version modules`) — per-module rev+date over the module tree, git-witnessed via the `fak-module-versions/1` ledger rather than asserted: [docs/notes/VERSION-EVERYTHING-SPINE-2026-07-03.md](docs/notes/VERSION-EVERYTHING-SPINE-2026-07-03.md)
- Cross-repo issue velocity (`fak issues-solved`): query issues solved across public and companion checkouts over arbitrary time windows in 1 turn: [docs/cli/verbs.md#fak-issues-solved](docs/cli/verbs.md#fak-issues-solved)
- Cache-value roll-up — is the cache work paying off over time? The front-door story keeping WITNESSED kernel reuse and OBSERVED provider-dollar savings in separate, unblended tracks, with the #1066 marginal-over-warm-KV, WITNESSED-vs-OBSERVED, and net-not-gross fences and the shipped Track-1 reproduce command (`fak nightrun score --json`): [docs/cache-value-rollup.md](docs/cache-value-rollup.md)

## Source authorities

- CLI verbs: [`cmd/fak/`](cmd/fak/)
- Kernel subsystems: [`internal/`](internal/)
- Runnable examples and policies: [`examples/`](examples/)
- Go module and toolchain: [`go.mod`](go.mod)

Runtime behavior is authoritative in code and tests. Documentation describes the current generation unless a page marks itself historical, experimental, simulated, stubbed, or superseded. Dated investigation and decision records live under [`docs/notes/`](docs/notes/); use them for provenance, not as the default current contract.

## Task routing

| Task | Read first | Check next |
|---|---|---|
| Explain or evaluate fak | [`README.md`](README.md) | [`docs/repro-packet.md`](docs/repro-packet.md) |
| Modify code or docs | [`AGENTS.md`](AGENTS.md) | The owning package tests and [`CONTRIBUTING.md`](CONTRIBUTING.md) |
| Run local models on Mac (Apple Silicon) | [`docs/fak/mac-local-models.md`](docs/fak/mac-local-models.md) | Run `fak run qwen38` or `fak serve --metal` |
| Integrate a client or managed runtime | [`docs/explainers/agent-runtime.md`](docs/explainers/agent-runtime.md) | [`docs/integrations/`](docs/integrations/) and the selected mode's quickstart and API/config authority |
| Build a bounded microagent-derived harness | [`docs/notes/microagents-to-harnesses-2026-08-18.md`](docs/notes/microagents-to-harnesses-2026-08-18.md) | Run `go run ./cmd/microharnessdemo -selfcheck`; descendants remain host-admitted and the root receives compact receipts, not child transcripts |
| Deploy or operate | [`docs/fak/deployment-guide.md`](docs/fak/deployment-guide.md) | [`docs/fak/server-config.md`](docs/fak/server-config.md) and [`docs/fak/api-reference.md`](docs/fak/api-reference.md) |
| Assess readiness or cut a release | [`.claude/skills/release/SKILL.md`](.claude/skills/release/SKILL.md) | Run `fak release readiness --json`, then use the skill's guarded ship and verification path |
| Assess a claim | [`CLAIMS.md`](CLAIMS.md) | [`BENCHMARK-AUTHORITY.md`](BENCHMARK-AUTHORITY.md) and the cited witness |
| Research design history | [`docs/notes/`](docs/notes/) | Current code, tests, and architecture before relying on an older decision |

For an unlisted task, start at [`INDEX.md`](INDEX.md) and select the current audience route.

- docs/generated/verb-surface.md — generated source-derived fak verb tree, REFUSES column, and unverified coverage count

- [KV capacity normalization](docs/kv-capacity-normalization.md): normalize block and direct runtime KV metrics across tokens, bytes, and occupancy with typed honesty diagnostics.

- [Frontier infrastructure and workload expectations](docs/research/frontier-infrastructure/README.md) — dated evidence on labs, clouds, datacenters, serving workloads, distributions, releases, startups, and rumors
- [Release branch regime and actionable CI base-red diagnosis](docs/release-branch-regime-status.md): Exact-run CI diagnosis, typed causes, package work units, and operator-owned billing.