Repository docs map
A map of every file in the repository docs/ folder, the session dossiers, the scripts and the other documentation-bearing files, with what each is for and which page of this site covers it. Repository paths are plain code spans; none are links.
How the layers relate: plans say what to build and which criteria prove it; docs/p2-findings.md records the evidence per phase; the runbooks and designs say how to deploy and expose it; the dossiers wrap each session with a resume pointer and ADRs.
Repository root
| File | What it is for | Site page |
|---|---|---|
README.md | One-paragraph description; links to the glossary and coding standards; notes the rename from Hawkeye (old docs keep @hawkeye/*) | Overview |
CODING_STANDARDS.md | Enforced conventions in 17 sections: style, naming, modules, fail-closed behavior, package boundaries, the guarded runtime, secrets, stores and fakes, database and money, configuration, tests (section 13), commits | Testing and CI, Writing guide |
GLOSSARY.md | Domain vocabulary, relationships and flagged ambiguities; stale where it marks built things as planned | Glossary |
secrets.manifest.yml | env-sync manifest: six services, SSM paths and variable names (as comments) | Secrets flow |
docker-compose.yml | Local development Postgres 16 on host port 5433, dev-only credentials | Testing and CI |
turbo.json | Turbo tasks, global env and the package boundary tags | Testing and CI |
pnpm-workspace.yaml | Workspace globs and the exact-pin catalog (Claude Agent SDK 0.3.322, Temporal 1.25.0, Hono 4.13.17, and others) | Packages and apps |
package.json | Root scripts; packageManager pnpm 11.28.11; engines.node >= 24 | Testing and CI |
.github/workflows/ci.yml | Jobs build, docker, gitleaks | Testing and CI |
.github/workflows/docker-release.yml | Release build and mirror to ECR | Release process |
.github/workflows/docs-site.yml | Builds and checks this documentation site | Testing and CI |
website/ | This Docusaurus site, its own pnpm project outside the workspace | Writing guide |
docs/ top level
| File | What it is for | Status | Site page |
|---|---|---|---|
docs/deploy-api-coolify.md | API runbook: app resource, full env table, TRUST_PROXY_HOPS, health, workspace, migrations, Postgres backup and restore drill (OPS-1) | Items marked UNVERIFIED; written for Coolify, production is CapRover | Deploy runbooks |
docs/deploy-gateway-coolify.md | Gateway runbook: listeners, policy and registry mounts, env table, limits, startup refusals, audit retention, token rotation | Same caveat | Deploy runbooks, Gateway |
docs/deploy-worker-coolify.md | Session worker runbook: env table, stop grace, first-deploy checks | Same caveat | Deploy runbooks |
docs/deploy-worker-fleet.md | Exec workers on laptops and VPSes: queues, env, refused variables, laptop and VPS steps, tailnet requirements, owner-only steps | Code and local tests only | Worker fleet |
docs/deploy-factory.md | Factory runbook: roles, env, GitHub App permissions, sandbox settings | Local only | Factory overview |
docs/deploy-sandbox.md | Per-job sandbox containers: topology, flags, argv allowlist, sysctls | Local only; VPS items UNVERIFIED | Sandbox |
docs/deploy-quality.md | CodeCrucible runbook: roles, env, preconditions PRE-0 to PRE-3, local evidence, rollout order, rollback | Built locally, dormant | Quality overview |
docs/deploy-app02-test.md | The throwaway app-02 deployment plan | Marked OUTDATED; test torn down | Deployment topology |
docs/design-worker-fleet.md | Design: gateway-routed session turns and the worker fleet; phases FL-1 to FL-4; risks R-1 to R-5 | Built | Worker fleet |
docs/design-gateway-fleet-exposure.md | Design: bind the control listener by CIDR so 8787 can be published; as-built notes for step 1 | Step 1 built, not released | Deployment topology |
docs/p1-findings.md | P1 build status and real-key results (2026-11-10) | Historical | Decisions |
docs/p1-findings-0a.md | Step 0a: Claude Agent SDK types and keyless probes (2026-11-09) | Historical | Runtimes and CLI |
docs/p1-findings-0b.md | Step 0b: pnpm empirical findings | Historical | Packages and apps |
docs/p1-findings-0c.md | Step 0c: Turborepo empirical findings (turbo 2.11.10) | Historical | Testing and CI |
docs/p1-realkey-runbook.md | One-time user-run real-key checks q1 to q4 and P1-18 | Historical | Testing and CI |
docs/p2-findings.md | The evidence log, about 6,300 lines, one section per phase (index below) | Living | all sections |
Directories under docs/:
| Path | What it is for |
|---|---|
docs/sessions/ | Seven session dossiers (below) |
docs/step0a/ | Four Step 0a scripts that need a real key: q1-allowedtools-outside-paths.mjs, q2-canusetool-under-dontask.mjs, q3-pretooluse-hook-path-deny.mjs, q4-minimal-env.mjs, shared _common.mjs, keyless helpers in keyless/ (canned-stream.mjs, query-type-stub.ts, spawn-capture.mjs), and a README.md with the safety rules |
docs/spikes/hono-spike.mjs, docs/spikes/sse-spike.mjs | Throwaway spikes behind ADR p1 0004 (Hono, SSE, abort, body limits) |
docs/spikes/temporal/ | P2.T Step 0 spikes T0a to T0f: t0a.mjs, t0b.mjs, t0c-link.mjs, t0d-semantics.mjs, t0d-shutdown.mjs, t0d-throttle.mjs, t0e.mjs, t0f.mjs, helpers lib.mjs, codec.mjs, decode.mjs, activities.mjs, workflows.mjs, failure-converter.mjs, proxy.mjs, replay fixtures in replay/, a self-host stack in selfhost/ (docker-compose.yml, gen-certs.sh, dynamicconfig/), its own pnpm root. Evidence: docs/p2-findings.md "P2.T Step 0 (local Temporal)" |
docs/spikes/quality/ | CodeCrucible Phase 0 spikes S1, S2, S4, S5: Stryker configs (stryker.*.conf.json), cheat.fixture.test.ts, empty.test.ts, vitest.list.config.ts, rekill.mjs, Dockerfile.s5, a README.md and an out/ folder of run artifacts; not part of the workspace. Evidence: "CodeCrucible Phase 0 spikes" |
docs/p2-findings.md section index
Approximate line numbers at the time of writing.
| Group | Sections (heading, line) |
|---|---|
| P2a | P2a Step 0 3, P2a build 134, P2a Docker (step 3) 184, P2a real-key (local) 2026-11-10 257 |
| P2b and P2.T | P2b 462, P2.T Step 0 (local Temporal) 542, P2.T T2 851, P2.T T3 950, P2.T T4 1054, P2.T T5 CI 1163, P2.T real-key (local) RK-S 1180, P2c 1257, Post-P2 fixes 1350 |
| P2.G governance gateway | P2.G S0b 1408, P2.G S2 and S0a 1485, P2.G S1 prep 1609, P2.G S0f 1626, P2.G S0c (partial) 1738, P2.G S1 1779, P2.G S1 security fixes 1981, P2.G real-key (local) 2017, P2.G S3 2159, P2.G S4 2299, P2.G S3 security fixes 2370, P2.G S5 2453 |
| P2.5 sandbox | P2.5-0 (local) 2580, P2.5-G 3093, P2.5 freeze inputs 3201, P2.5-F 3512, P2.5-1 3581, P2.5-2 3639, P2.5 security fixes and P2.5-3 3747, P2.5 real-key (local) 3907, P2.5 G2-local gap closure 4030, P2.5 Gate G2 4225, P2.5 sign-off fixes 4697 |
| P3 factory | P3-0 4416, P3-1 4538, P3-2 4606, P3-3 4811, P3-4 4952, P3-5 5058, P3-3 security conditions 5133, P3-3 gaps 5274, P3-6 5350, P3-6 follow-up 5388, P3 security review (independent) 5439, P3-7 GitHub setup 5483, P3-7 live check 5535, P3-7 same-org fork 5752 |
| Deploy and fleet | App-02 test deployment 5839, Production deploy: answers from the fleet sessions 5876, Gateway default policy 5907, FL-1 and FL-2 5942, FL-3 and FL-4 (worker fleet) 6052, FL follow-up 6156, FL-E2E2 (exec container, https test CA) 6190, App-03 production deploy and smoke test 6230 |
| CodeCrucible | CodeCrucible Phase 0 spikes 6250 (including S1, S2, S4, the Postgres volume restart proof and nightly pg_dump, and S5) |
Session dossiers
Each of the seven folders contains README.md, SUMMARY.md, LESSONS.md and FOLLOWUPS.md; extras are listed. Details: Session dossiers.
| Folder | Extra files | ADRs |
|---|---|---|
docs/sessions/2026-11-10-agentforge-p1-p2a-build/ | ARCHITECTURE.md, BLOG.md | adr/0001-single-table-spend-ledger.md, 0002-hook-enforced-file-tool-containment.md, 0003-provider-agnostic-runtime-port.md, 0004-hono-for-api.md, 0005-temporal-sessions-in-p2.md |
docs/sessions/2026-11-10-agentforge-p2b-to-p2g-s4/ | none | none |
docs/sessions/2026-11-11-agentforge-p25-to-p3-build/ | none | none |
docs/sessions/2026-11-13-agentforge-app02-test-and-worker-fleet/ | BLOG.md | adr/0001-all-model-calls-through-the-gateway.md, 0002-same-org-fork-for-private-targets.md, 0003-temporal-acl-only-and-baked-gateway-policy.md |
docs/sessions/2026-11-15-app03-deploy-and-smoke/ | ARCHITECTURE.md, BLOG.md | adr/0004-app03-dedicated-agentforge-host.md, 0005-gateway-publishes-no-port-at-launch.md, 0006-postgres-persistent-volume.md |
docs/sessions/2026-11-16-codecrucible-and-gateway-cidr/ | BLOG.md | adr/0007-codecrucible-v1-shape.md, 0008-gateway-control-bind-cidr.md |
docs/sessions/2026-11-16-codecrucible-build/ | BLOG.md | adr/0009-quality-admission-and-pending-submissions.md |
All ADRs are summarized in Decisions.
scripts/
Image tests
| File | What it is for |
|---|---|
scripts/api-image.test.sh | API image checks (API-16); runs in CI |
scripts/gateway-image.test.sh | Gateway image checks (G-P2G-MP); runs in CI |
scripts/gateway-gv3.test.sh | Gateway on two internal networks with a stand-in runtime (GV3, SEC10b, SEC12); runs in CI |
scripts/gv3-standin-probe.mjs | The stand-in runtime's probe program for GV3 (node probe.mjs a ... for every 4xx and 5xx path, b for the kill switch) |
scripts/worker-image.test.sh | Session worker image checks (TMP-13) |
scripts/exec-image.test.sh | Exec worker image checks (FL-4) |
scripts/factory-image.test.sh | Factory target image checks (P3-3) |
scripts/sandbox-image.test.sh | Sandbox image and driver checks (P2.5-1, P2.5-2) |
scripts/quality-image.test.sh | Quality image build and analysis check (CC-2.1) |
End-to-end and real-infrastructure scripts
| File | What it is for |
|---|---|
scripts/sandbox-e2e.test.sh | P2.5 keyless end to end with the scripted fake model |
scripts/sandbox-rk.test.sh | P2.5 real-key checks, user-run, aborts above 1.00 USD |
scripts/session-gateway-e2e.test.sh | FL-2 session turns through the gateway with the baked policy |
scripts/fleet-split-e2e.test.sh | FL-3 core worker and two exec workers |
scripts/exec-container-e2e.test.sh | FL-E2E2 exec worker as a container over https with a throwaway CA |
scripts/factory-e2e.test.sh | P3-3 keyless factory end to end |
scripts/factory-gh.test.sh | P3-7 live check against real GitHub (G-P3-GH), user-run |
scripts/p3/gh-live.mjs | User-run live GitHub checks using the factory's built code with the two real Apps (fork admin step, preflight, and more); prints ids, statuses and counts only |
scripts/quality-exec.test.sh | CC-2.4 exec activities with the real quality image |
scripts/quality-verify.test.sh | CC-3.2 verify steps 5 to 7 |
scripts/p25/fake-upstream.mjs | The scripted fake model upstream (RUN<<cmd>>RUN, STALL, BIGUSAGE) used by the e2e scripts |
Tooling and deploy
| File | What it is for |
|---|---|
scripts/cache.test.sh | Proves turbo hashes change on env, lockfile and source edits (P1-2); not in CI |
scripts/audit-prt.sh | Audits workflows for the pwn-request pattern (FX-AUD1) |
scripts/deploy/make-app03-secrets.sh | Builds the env-sync directories for the core host stack; --check verifies |
scripts/deploy/make-app02-secrets.sh | Superseded generator for the throwaway test; kept as history |
scripts/deploy/make-app02-secrets.test.sh | Tests the superseded generator; runs in CI |
scripts/deploy/smoke-app02.sh | Smoke test for the throwaway deployment; env API_URL, API_KEY, optional MODEL, MAX_COST_USD, TIMEOUT_SEC, EXPECT_DISABLED |
Pages for these: Testing and CI, Secrets flow, Deploy runbooks.
Plans (.omc/plans/, git-ignored)
The plans exist only in the owner's checkout (excluded via .git/info/exclude; bead hawkeye-81e.17 tracks the risk of not having them in git). Dossiers and docs/p2-findings.md cite them by section.
| File | Version in the documents | Purpose |
|---|---|---|
platform-roadmap.md | v8.1, not approved | The platform roadmap (turbo and pnpm monorepo, phases P1 to P3) |
p1-foundation.md | P1 plan | |
p2-rest-api-and-durable-sessions.md | v5 | P2 and P2.T plan |
p2g-governance-gateway.md | v4.1 | Governance gateway plan |
p25-sandbox-spike.md | v4.3 | Sandbox spike plan |
p3-software-factory.md | v2.3 | Factory plan (section 21 is the same-org fork) |
codecrucible-mutant-hunter.md | v5 with closing edits | CodeCrucible plan (612 lines) |
open-questions.md | Open questions per plan | |
agent-api-server.md | superseded | History; superseded by the P2 plan |
Package and app READMEs
Only two packages carry a README: packages/agent-core/README.md (controls, spend alerts) and packages/quality-core/README.md (function discovery, complexity rules, coverage and CRAP, report and trusted-list join). Everything else is documented through the files above and, on this site, through the architecture, runtime and security sections.
Sources
- Directory listings of
docs/,docs/sessions/,docs/spikes/,docs/step0a/,scripts/,.github/workflows/and.omc/plans/ - The first lines and headers of each
docs/*.md,docs/spikes/*/README.md,docs/step0a/README.mdand script docs/p2-findings.md(section headings, viagrep '^## ')README.md,GLOSSARY.md,CODING_STANDARDS.md,secrets.manifest.ymldocs/sessions/*/README.md.omc/plans/agent-api-server.md,open-questions.md,platform-roadmap.md(header lines).github/workflows/*.yml,turbo.json,package.json,pnpm-workspace.yaml