README.md

Design and contributor documentation

Using AgentFox? The user documentation (install, quickstart, guides, CLI and API reference, self-hosting) lives on the website at useagentfox.com/docs, and its source is in dashboard/app/docs/. This directory holds the material behind the product: how it is built, why it is built that way, and how its numbers were measured.

docs/
├── getting-started.md   a linear first hour, from install to your own agent governed
├── product-tour.md      every integration surface, commands by task, self-hosting
├── status.md            what is built, partial and absent (generated)
├── architecture/        how the system is put together
├── design/              what it must do, and how we know whether it does
├── evaluation/          how the numbers were measured, and how to read them
├── adr/                 architecture decision records: what was decided, and what lost
├── deployment/          running it yourself, beyond the website's self-host page
└── assets/              images used by the top-level README

Start here

Document	What it is	Who it is for
getting-started.md	A linear first hour: install, initialise, scan a repo, run the demo, connect an agent over HTTP, read findings, turn enforcement on. Each step says what it proves.	Anyone new.
status.md	Implementation status, generated by probing the codebase rather than written by hand (python scripts/gen/coverage.py --write). Says what is built, partial and absent.	Anyone deciding whether a capability actually exists yet.
product-tour.md	Each place the policy binds (auto(), the gateway, LangGraph, the OpenAI Agents SDK, TypeScript, MCP, Claude Code hooks), the commands grouped by task, what the demo prints, and self-hosting.	Evaluators who want the whole product on one page.
../ARCHITECTURE.md	The domain model, one tool call traced through the code, the code map, the invariants, and where to start for common changes.	Anyone about to change the code. Read it before the HLD.
../CONTRIBUTING.md	Setup in three commands, the just ci contract, test layout, generated files, the vendored-wheel rule and the conventions.	New contributors.

architecture/

Document	What it is	Who it is for
high-level-design.md	Design rationale: pillars, principles, integration surfaces, tech stack, deployment topology.	Contributors who have read ARCHITECTURE.md and want the why.
low-level-design.md	Subsystem internals: the enforcer, detector pipeline, audit chain, auto().	Contributors changing behaviour.
api-spec.md	The full HTTP API: authentication, the inline enforcement routes, and every control-plane route. Route tables are generated (python scripts/gen/api_routes.py).	Engineers integrating without Python.
data-model.md	The persisted data model.	Contributors touching persistence.
threat-model.md	Threats to the customer's agents, and threats to AgentFox itself.	Security review.
judgment-tiers.md	The optional judgment tiers (Jev, a hosted LLM, a self-hosted LLM): what each may decide, and what the routing table forbids it from deciding.	Anyone deciding which tiers to switch on.
judgment-egress.md	What leaves the boundary when a hosted tier is enabled, and the three-way personal-data choice.	Read before enabling any hosted tier on regulated data.

design/

Document	What it is	Who it is for
PRD.md	The single canonical product requirements document: the argument, the product, the plan, and what has shipped since (including monitoring and live probing, §13). Long, and the source of truth for requirement IDs.	Product and engineering leadership.
failure-modes.md	How deployed agents actually fail: 57 modes in 8 families plus 5 found by an independent audit, grounded in catalogued incidents, with what covers each.	Anyone building a risk case, and anyone checking ours.
coverage-map.md	A second coverage view, built from the architecture of an agentic request rather than from the failure-mode catalogue, so it is not circular. Generated by probe.	Anyone checking for gaps the authors did not think of.
gap-analysis.md	Enterprise readiness and competitive position, audited and severity-ranked, ending with what is still open and what is deferred by decision.	Buyers, and us.
control-catalog.md	43 controls mapped to EU AI Act, NIST AI RMF, ISO 42001, SOC 2, OWASP LLM and Agentic, and MITRE ATLAS, plus what each mapping does not cover.	Compliance and GRC. Mappings are engineering drafts, not legal advice.
traceability.md	Every requirement mapped to the module that implements it and the test that covers it.	Contributors, and audit.
competitor-analysis.md	Market landscape, our niche, and where competitors win. The public /compare page cites it.	Anyone comparing options.
architecture-differentiation.md	Where each competitor sits in the stack and what it decides on, from their docs and code; our architectural primitives mapped to bound benchmark claims; pitch lines, objections, and the head-to-head runs still missing.	Founders and AEs preparing a technical pitch, and the sceptical buyer checking it.
production-readiness-review.md	Gaps found re-checking the HLD and LLD against the live code, what has been fixed since, and the settings a production deployment needs (secrets, cron, webhooks, Slack, the showcase flag).	Anyone deciding whether to run it in production.
structure-proposal.md	The planned code restructure: layers, a harness adapter interface, capability packs, the decisions taken and progress per phase.	Contributors planning a large change.
oss-register.md	Every wrapped open-source project: licence, health, verdict, our exposure, and why some well-known projects are deliberately off the critical path.	Contributors adding a dependency, and licence review.

The documents that began as PRD appendices keep their letters in their titles and section numbers (Appendix A to E, §B.6 and so on), because other documents cite them that way.

evaluation/

Document	What it is	Who it is for
evidence-standards.md	How to read our numbers: what each kind of evidence establishes and the limits that apply first.	Read this before quoting any benchmark result anywhere.
benchmarking-whitepaper.md	The product capability by capability: what it does, how it was measured, every round including the ones that went badly, and how it differs from the market.	Evaluators, and anyone who wants the methodology rather than the headline.
responding-to-the-critique.md	What the strongest public criticism of this category gets right, what it gets wrong, and what we changed because of it.	A reader who has seen the critique and is sceptical, reasonably.
judgment/results.md	The study behind the judgment tiers: where a hosted judgment beats our detectors and where it loses. Its headline numbers are bound in benchmarks/claims.yaml.	Evaluators who want the evidence, not the summary.
judgment/vs-shipping.md, cascade.md, safepyramid.md	Supporting write-ups for that study: against the shipping detectors, the cascade design, and the SafePyramid run.	Evaluators checking a specific result.
dataset-sourcing.md	A working record, kept for provenance: research preceding a round of benchmarks, with candidate datasets, verified licences, and rejected candidates with reasons. Not maintained once that work was done.	Anyone checking where a dataset came from.
../benchmarks/README.md	The benchmark index: every harness, its dataset, its licence and how to re-run it.	Anyone reproducing a result.

Numbers quoted in these documents are bound to result files by benchmarks/claims.yaml; python scripts/check/claims.py --check fails if a quoted figure drifts from its source.

adr/

Document	What it is	Who it is for
adr/README.md	The index of architecture decision records, and how to write one.	Anyone about to make a decision that is expensive to reverse.
adr/0001-repository-structure.md	One package in layers held by import-linter, capabilities/, harnesses, plugins/, packs, the repository outside src/, and what is deferred.	Contributors who want the why behind the layout.
adr/0002-customer-authored-rules.md	Custom rules as data plus a managed policy pack, end-user messages and re-ask, per-workspace detectors, and importers that only plan.	Anyone adding a rule type, a detector switch or an importer.
adr/0003-agent-layers-workspace-file-rule-tests.md	Agent protection layers, the workspace file that never deletes, and rule tests over recorded decisions.	Anyone changing agent setup, policy files or the Tune preview.

deployment/

Document	What it is	Who it is for
systemd.md	Run the Python gateway as a reboot-persistent systemd user service, with separate database, evidence and signing-key storage.	Self-hosters on Linux.
key-rotation.md	Rotate the token encryption key and the audit signing key: the _PREVIOUS settings, agentfox admin keys rotate, the automatic job and how to confirm nothing still needs the old key.	Anyone running a deployment.
../deploy/README-dashboard.md	Deploying the hosted dashboard (Render, Fly, Vercel), its shared secrets and the database migration state.	Anyone running the dashboard.

Elsewhere in the repo

Document	What it is
../plugins/claude-code/README.md	The Claude Code operator plugin: skills, commands, subagents, MCP server and safety hooks for driving the product from a coding agent. Its runtime-neutral parts are in plugins/shared/.
../demo/live-airline/README.md	OpenAI's open-source multi-agent airline app run live through a local gateway with the OpenAI Agents SDK adapter: setup, configuration over the HTTP API, scripted scenarios and a check that asserts what was blocked, held and approved.
../sdk/typescript/README.md	@agentfox/sdk, the dependency-free TypeScript client for the /v1/guard/* routes, and the OpenAI client pointed at the gateway proxy.
../plugins/shared/reference/docs-map.md	Which document an agent should read for which question. Every tracked markdown file must be classified there.