llms.txt

# fak documentation map for agents

`fak` is 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 authorities

- 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)
- New-work defaults — ship the minimal working spine first, 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)
- Contribution contract: [`CONTRIBUTING.md`](CONTRIBUTING.md)
- Claims status (`SHIPPED`, `SIMULATED`, `STUB`): [`CLAIMS.md`](CLAIMS.md)
- External system architecture, interfaces, and trust boundaries: [`docs/architecture.md`](docs/architecture.md)
- Detailed integration architecture and extension seams: [`docs/fak/agent-integration-architecture.md`](docs/fak/agent-integration-architecture.md)
- Managed agent runtime ownership, interfaces, flow, and offline proof: [`docs/explainers/agent-runtime.md`](docs/explainers/agent-runtime.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)
- Claude Code on your own Mac's local model (`fak claude-mac-fak`, pointing Claude Code at a Mac's `fak serve` gateway running Qwen3.6-27B; first local turn is slow and single-stream, but end-to-end and observable via the preflight panel): [`docs/fak/mac-agent-ui.md`](docs/fak/mac-agent-ui.md)
- Shared endpoint with `fak serve`: [`docs/fak/server-quickstart.md`](docs/fak/server-quickstart.md)
- Configuration: [`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)
- 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)
- Client and agent integrations: [`docs/integrations/`](docs/integrations/)
- Scoped benchmark results, tuned baselines, artifacts, and reproduce routes: [`BENCHMARK-AUTHORITY.md`](BENCHMARK-AUTHORITY.md)
- Security floor, policy configuration, evidence, and private reporting: [`SECURITY.md`](SECURITY.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)

## 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) |
| 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 |
| 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.