Skip to main content

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​

FileWhat it is forSite page
README.mdOne-paragraph description; links to the glossary and coding standards; notes the rename from Hawkeye (old docs keep @hawkeye/*)Overview
CODING_STANDARDS.mdEnforced 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), commitsTesting and CI, Writing guide
GLOSSARY.mdDomain vocabulary, relationships and flagged ambiguities; stale where it marks built things as plannedGlossary
secrets.manifest.ymlenv-sync manifest: six services, SSM paths and variable names (as comments)Secrets flow
docker-compose.ymlLocal development Postgres 16 on host port 5433, dev-only credentialsTesting and CI
turbo.jsonTurbo tasks, global env and the package boundary tagsTesting and CI
pnpm-workspace.yamlWorkspace 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.jsonRoot scripts; packageManager pnpm 11.28.11; engines.node >= 24Testing and CI
.github/workflows/ci.ymlJobs build, docker, gitleaksTesting and CI
.github/workflows/docker-release.ymlRelease build and mirror to ECRRelease process
.github/workflows/docs-site.ymlBuilds and checks this documentation siteTesting and CI
website/This Docusaurus site, its own pnpm project outside the workspaceWriting guide

docs/ top level​

FileWhat it is forStatusSite page
docs/deploy-api-coolify.mdAPI 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 CapRoverDeploy runbooks
docs/deploy-gateway-coolify.mdGateway runbook: listeners, policy and registry mounts, env table, limits, startup refusals, audit retention, token rotationSame caveatDeploy runbooks, Gateway
docs/deploy-worker-coolify.mdSession worker runbook: env table, stop grace, first-deploy checksSame caveatDeploy runbooks
docs/deploy-worker-fleet.mdExec workers on laptops and VPSes: queues, env, refused variables, laptop and VPS steps, tailnet requirements, owner-only stepsCode and local tests onlyWorker fleet
docs/deploy-factory.mdFactory runbook: roles, env, GitHub App permissions, sandbox settingsLocal onlyFactory overview
docs/deploy-sandbox.mdPer-job sandbox containers: topology, flags, argv allowlist, sysctlsLocal only; VPS items UNVERIFIEDSandbox
docs/deploy-quality.mdCodeCrucible runbook: roles, env, preconditions PRE-0 to PRE-3, local evidence, rollout order, rollbackBuilt locally, dormantQuality overview
docs/deploy-app02-test.mdThe throwaway app-02 deployment planMarked OUTDATED; test torn downDeployment topology
docs/design-worker-fleet.mdDesign: gateway-routed session turns and the worker fleet; phases FL-1 to FL-4; risks R-1 to R-5BuiltWorker fleet
docs/design-gateway-fleet-exposure.mdDesign: bind the control listener by CIDR so 8787 can be published; as-built notes for step 1Step 1 built, not releasedDeployment topology
docs/p1-findings.mdP1 build status and real-key results (2026-11-10)HistoricalDecisions
docs/p1-findings-0a.mdStep 0a: Claude Agent SDK types and keyless probes (2026-11-09)HistoricalRuntimes and CLI
docs/p1-findings-0b.mdStep 0b: pnpm empirical findingsHistoricalPackages and apps
docs/p1-findings-0c.mdStep 0c: Turborepo empirical findings (turbo 2.11.10)HistoricalTesting and CI
docs/p1-realkey-runbook.mdOne-time user-run real-key checks q1 to q4 and P1-18HistoricalTesting and CI
docs/p2-findings.mdThe evidence log, about 6,300 lines, one section per phase (index below)Livingall sections

Directories under docs/:

PathWhat 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.mjsThrowaway 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.

GroupSections (heading, line)
P2aP2a Step 0 3, P2a build 134, P2a Docker (step 3) 184, P2a real-key (local) 2026-11-10 257
P2b and P2.TP2b 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 gatewayP2.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 sandboxP2.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 factoryP3-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 fleetApp-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
CodeCrucibleCodeCrucible 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.

FolderExtra filesADRs
docs/sessions/2026-11-10-agentforge-p1-p2a-build/ARCHITECTURE.md, BLOG.mdadr/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/nonenone
docs/sessions/2026-11-11-agentforge-p25-to-p3-build/nonenone
docs/sessions/2026-11-13-agentforge-app02-test-and-worker-fleet/BLOG.mdadr/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.mdadr/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.mdadr/0007-codecrucible-v1-shape.md, 0008-gateway-control-bind-cidr.md
docs/sessions/2026-11-16-codecrucible-build/BLOG.mdadr/0009-quality-admission-and-pending-submissions.md

All ADRs are summarized in Decisions.

scripts/​

Image tests​

FileWhat it is for
scripts/api-image.test.shAPI image checks (API-16); runs in CI
scripts/gateway-image.test.shGateway image checks (G-P2G-MP); runs in CI
scripts/gateway-gv3.test.shGateway on two internal networks with a stand-in runtime (GV3, SEC10b, SEC12); runs in CI
scripts/gv3-standin-probe.mjsThe 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.shSession worker image checks (TMP-13)
scripts/exec-image.test.shExec worker image checks (FL-4)
scripts/factory-image.test.shFactory target image checks (P3-3)
scripts/sandbox-image.test.shSandbox image and driver checks (P2.5-1, P2.5-2)
scripts/quality-image.test.shQuality image build and analysis check (CC-2.1)

End-to-end and real-infrastructure scripts​

FileWhat it is for
scripts/sandbox-e2e.test.shP2.5 keyless end to end with the scripted fake model
scripts/sandbox-rk.test.shP2.5 real-key checks, user-run, aborts above 1.00 USD
scripts/session-gateway-e2e.test.shFL-2 session turns through the gateway with the baked policy
scripts/fleet-split-e2e.test.shFL-3 core worker and two exec workers
scripts/exec-container-e2e.test.shFL-E2E2 exec worker as a container over https with a throwaway CA
scripts/factory-e2e.test.shP3-3 keyless factory end to end
scripts/factory-gh.test.shP3-7 live check against real GitHub (G-P3-GH), user-run
scripts/p3/gh-live.mjsUser-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.shCC-2.4 exec activities with the real quality image
scripts/quality-verify.test.shCC-3.2 verify steps 5 to 7
scripts/p25/fake-upstream.mjsThe scripted fake model upstream (RUN<<cmd>>RUN, STALL, BIGUSAGE) used by the e2e scripts

Tooling and deploy​

FileWhat it is for
scripts/cache.test.shProves turbo hashes change on env, lockfile and source edits (P1-2); not in CI
scripts/audit-prt.shAudits workflows for the pwn-request pattern (FX-AUD1)
scripts/deploy/make-app03-secrets.shBuilds the env-sync directories for the core host stack; --check verifies
scripts/deploy/make-app02-secrets.shSuperseded generator for the throwaway test; kept as history
scripts/deploy/make-app02-secrets.test.shTests the superseded generator; runs in CI
scripts/deploy/smoke-app02.shSmoke 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.

FileVersion in the documentsPurpose
platform-roadmap.mdv8.1, not approvedThe platform roadmap (turbo and pnpm monorepo, phases P1 to P3)
p1-foundation.mdP1 plan
p2-rest-api-and-durable-sessions.mdv5P2 and P2.T plan
p2g-governance-gateway.mdv4.1Governance gateway plan
p25-sandbox-spike.mdv4.3Sandbox spike plan
p3-software-factory.mdv2.3Factory plan (section 21 is the same-org fork)
codecrucible-mutant-hunter.mdv5 with closing editsCodeCrucible plan (612 lines)
open-questions.mdOpen questions per plan
agent-api-server.mdsupersededHistory; 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.md and script
  • docs/p2-findings.md (section headings, via grep '^## ')
  • README.md, GLOSSARY.md, CODING_STANDARDS.md, secrets.manifest.yml
  • docs/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