Review 09b6b339405f

site/src/content/docs/docs at 895208db30, reviewed by claude-code, verified by codex.

repo: git@github.com:pdbethke/corralai
commit: 895208db30e6ca7bbe7b1da87d6fcbe0a9fdebc4
scope: site/src/content/docs/docs
reviewer: claude-code (2.1.263 (Claude Code))
verifier: codex (codex-cli 0.152.0) different model than the reviewer different vendor: anthropic → openai
substrate: workspace (a detached worktree at the commit; not a jail)
started: 2026-09-08 16:18 UTC
audited party: Peter D Bethke · co-authored: Claude Opus 5 (1M context)
files shown: 40 file(s)

Findings (8)

R1 high reproduced

docs/ui-tour/memory.mdx tells the reader the brain's memory corpus is something "every `corral certify --local` run can draw on", eight lines below its own banner stating that no audit ever reads shared memory — and `certify --local` runs in-process with no brain, so the claim is false in the direction that flatters the product.

where: site/src/content/docs/docs/ui-tour/memory.mdx:10
tier: REPRODUCED (declared REPRODUCED)

the script that was executed

#!/bin/sh
set -eu
f=site/src/content/docs/docs/ui-tour/memory.mdx
echo "=== the banner this page opens with (line 7):"
sed -n '7p' "$f"
echo
echo "=== the body of the same page (lines 10-12):"
sed -n '10,12p' "$f"
echo
# Both sentences must be present in the SAME file for the contradiction to stand.
grep -q 'never from shared memory, skills or a prior run' "$f"
grep -q 'run can draw on' "$f"
echo "=== the engine side: what certify --local and the pool actually reference:"
grep -ric 'memory' cmd/corral/certify_local.go || true
grep -rl 'internal/memory' internal/advpool cmd/corral/certify_local.go 2>/dev/null || echo "(no import of the memory store on the --local audit path)"
echo
echo "DEFECT: one page asserts both 'nothing on the brain is read by an audit' and 'the brain's memory corpus is drawn on by every corral certify --local run'."
exit 0

what it printed

=== the banner this page opens with (line 7):
This page describes the **brain**, corral's optional coordination daemon. Nothing on it is required for a verdict: `corral certify`, the GitHub Action, `verify`, `ui`, `seal` and `scans` never contact a brain. And nothing on it is read by an audit — an audit's prompts are built from the goal, the code and its symbols, never from shared memory, skills or a prior run. See [the brain, and what it is not](https://github.com/pdbethke/corralai/blob/main/docs/corral/brain.md).

=== the body of the same page (lines 10-12):
The Memory tab lists the brain's own memory corpus — a shared corpus of
execution-**verified** audit findings (patterns, not code) that every
`corral certify --local` run can draw on. An entry doesn't get in by a model

=== the engine side: what certify --local and the pool actually reference:
0
(no import of the memory store on the --local audit path)

DEFECT: one page asserts both 'nothing on the brain is read by an audit' and 'the brain's memory corpus is drawn on by every corral certify --local run'.

refutation — codex STANDS

I checked the complete page and the local audit implementation. The note says audits never read shared memory, while the immediately following paragraph says every certify --local run can draw on that corpus. The local path has no corresponding brain or memory integration that could reconcile the latter statement.

ref 09b6b339405f83a44741b2fc83df2829d3614ad3da602d198f0960909de7b3ac#R1

R2 medium no script

concepts/memory-and-learning-loop.mdx states in the present tense that approved lessons are injected into later audit runs' task instructions ("capped at 3", fenced as LESSONS FROM THE HERD), but mission.InjectLessons — the function that does that — is called only from its own test file, and the sole production CreateMission caller (internal/brain/advpool.go:788) creates a one-phase tracking mission with no instruction and no lessons, so the loop's "active half" reaches no run today.

where: site/src/content/docs/docs/concepts/memory-and-learning-loop.mdx:31
tier: CODE-READ (declared CODE-READ)

refutation — codex STANDS

I searched the bare InjectLessons identifier and traced production mission creation. InjectLessons is defined in internal/mission/store.go and invoked only by its tests. The hosted adversarial-pool path creates a tracking mission with a phase lacking an instruction and directly starts the pool driver; it neither retrieves vetted lessons nor calls InjectLessons. Thus the documented present-tense injection into later audit tasks is not connected.

ref 09b6b339405f83a44741b2fc83df2829d3614ad3da602d198f0960909de7b3ac#R2

R3 medium reproduced

docs/ui-tour/skills.mdx documents `corral sync` as the command that reads/writes the artifact store and carries an approved skill to every fleet member, but cmd/corral/main.go dispatches no `sync` verb and no binary's generated CLI reference names one, so the instruction cannot be followed.

where: site/src/content/docs/docs/ui-tour/skills.mdx:12
tier: REPRODUCED (declared REPRODUCED)

the script that was executed

#!/bin/sh
set -eu
doc=site/src/content/docs/docs/ui-tour/skills.mdx
echo "=== the doc's claim:"
grep -n 'corral sync' "$doc"
echo
echo "=== every subcommand cmd/corral/main.go actually dispatches:"
grep -n '^	case "' cmd/corral/main.go
if grep -q 'case "sync"' cmd/corral/main.go; then
  echo "a sync verb IS dispatched — no defect"; exit 1
fi
echo
echo "=== the GENERATED CLI reference (scripts/gen-cli-docs.sh, one file per cmd/* binary, drift-gated in CI):"
if grep -n 'corral sync' docs/cli/*.md; then
  echo "a sync verb IS documented by a binary's own -h — no defect"; exit 1
fi
echo "(no binary's own -h output names a 'sync' verb)"
grep -q 'corral sync' "$doc"
echo
echo "DEFECT: skills.mdx instructs the reader to use \`corral sync\`; the binary has no such subcommand."
exit 0

what it printed

=== the doc's claim:
3:description: The tab that shows the fleet's shared skills — the versioned artifacts corral sync pulls to every member.
12:`corral sync` reads and writes, and shows each skill as a name, path, and
18:proposal writes it to the artifact store, and `corral sync` carries it to

=== every subcommand cmd/corral/main.go actually dispatches:
400:	case "", "(devel)":
411:	case "secret":
417:	case "certify":
419:	case "control":
425:	case "scorecard":
475:	case "models":
480:	case "demo":
485:	case "doctor":
489:	case "mcp":
510:	case "criticscore":
545:	case "matrix":
562:	case "scans":
568:	case "ui":
577:	case "seal":
582:	case "eval":
587:	case "ledger":
589:	case "review":
591:	case "brief":
593:	case "verify":

=== the GENERATED CLI reference (scripts/gen-cli-docs.sh, one file per cmd/* binary, drift-gated in CI):
(no binary's own -h output names a 'sync' verb)

DEFECT: skills.mdx instructs the reader to use `corral sync`; the binary has no such subcommand.

refutation — codex STANDS

I inspected the main command dispatch, command directories, generated CLI references, and artifact-store tools. There are sync_put and sync_delete MCP tools and internal synchronization facilities, but no user-facing corral sync command. Those narrower facilities do not make the documented command executable.

ref 09b6b339405f83a44741b2fc83df2829d3614ad3da602d198f0960909de7b3ac#R3

R4 medium reproduced

github-action.mdx promises that "a diff that touches no auditable candidate is a legitimate pass... exits 0", but repoScanExitCode returns 1 whenever the diff's changed source files could not be paired with a test — the repo's own TestUnpairableDiffFailsTheGate pins that — so on the JS/TS layouts the code comment calls the common path the gate goes red for a reason the docs call a pass.

where: site/src/content/docs/docs/github-action.mdx:87
tier: REPRODUCED (declared REPRODUCED)

the script that was executed

#!/bin/sh
set -eu
doc=site/src/content/docs/docs/github-action.mdx
echo "=== the doc's promise:"
grep -n -B1 -A1 'legitimate pass' "$doc"
echo
echo "=== what the gate actually does (cmd/corral/certify_repo.go):"
grep -n -A3 'if unpairableInDiff > 0 {' cmd/corral/certify_repo.go
echo
echo "=== and what the repo's own test asserts for that case:"
grep -n -B4 -A6 'changed files that could not be paired' cmd/corral/certify_repo_test.go
echo
grep -q 'legitimate pass' "$doc"
grep -q 'exits 0' "$doc"
grep -q 'if unpairableInDiff > 0 {' cmd/corral/certify_repo.go
grep -q '{"changed files that could not be paired", true, 2, 1}' cmd/corral/certify_repo_test.go
echo "DEFECT: the docs say exit 0 for a diff with no auditable candidate; the code and its test say exit 1 whenever the unpaired files are the changed ones."
exit 0

what it printed

=== the doc's promise:
86-
87:A diff that touches no auditable candidate is a legitimate pass: the action
88-prints `NOTHING IN SCOPE:` and exits 0.

=== what the gate actually does (cmd/corral/certify_repo.go):
3055:	if unpairableInDiff > 0 {
3056-		return 1
3057-	}
3058-	if nothingInScope {

=== and what the repo's own test asserts for that case:
3997-
3998-	s := out.String()
3999-
4000-	if strings.Contains(s, "no audit was needed") {
4001:		t.Errorf("changed files that could not be paired must NOT be reported as needing no audit:\n%s", s)
4002-	}
4003-	if !strings.Contains(s, "lib/response.js") {
4004-		t.Errorf("the unpairable files must be named so the reader can act:\n%s", s)
4005-	}
4006-	if !strings.Contains(s, "--tests") {
4007-		t.Errorf("the report must point at the way out (--tests map):\n%s", s)
--
4504-		nothingInScope bool
4505-		unpairable     int
4506-		want           int
4507-	}{
4508:		{"changed files that could not be paired", true, 2, 1},
4509-		{"docs-only diff — nothing in scope, nothing unpaired", true, 0, 0},
4510-		{"unpairable files reported even without the scope flag", false, 1, 1},
4511-	} {
4512-		t.Run(tc.name, func(t *testing.T) {
4513-			rep := reposcan.RepoReport{Audited: 0}
4514-			if got := repoScanExitCode(rep, tc.nothingInScope, tc.unpairable, nil, nil); got != tc.want {

DEFECT: the docs say exit 0 for a diff with no auditable candidate; the code and its test say exit 1 whenever the unpaired files are the changed ones.

refutation — codex STANDS

I examined repoScanExitCode and the surrounding explanatory comment. Changed source files that cannot be paired arrive with nothingInScope true but are deliberately checked first and return 1; only a genuinely empty scope with zero unpairable files returns 0. The documentation does not state this exception and therefore promises exit 0 too broadly for the reviewer's named input.

ref 09b6b339405f83a44741b2fc83df2829d3614ad3da602d198f0960909de7b3ac#R4

R5 medium reproduced

github-action.mdx tells the reader to "leave `diff-base` at its default" because "passing it empty audits the whole repository, which is a deliberate opt-in, not a default" — but action.yml's default for diff-base IS the empty string, and the action only derives a base from GITHUB_BASE_REF, so on the `workflow_dispatch` opt-in the same page recommends the default silently audits the entire repository.

where: site/src/content/docs/docs/github-action.mdx:84
tier: REPRODUCED (declared REPRODUCED)

the script that was executed

#!/bin/sh
set -eu
doc=site/src/content/docs/docs/github-action.mdx
echo "=== the doc's claim:"
grep -n -A1 'Leave .diff-base. at its default' "$doc"
echo
echo "=== action.yml's declared default for diff-base:"
blk=$(awk '/^  diff-base:/{f=1} f{print} f&&/default:/{exit}' action.yml)
printf '%s\n' "$blk"
printf '%s\n' "$blk" | grep -q 'default: ""'
echo
echo "=== the only place a base is derived when the input is empty:"
grep -n -A4 'base="\$DIFF_BASE"' action.yml
echo
echo "=== and the workflow the same page tells you to add:"
grep -n 'workflow_dispatch' "$doc"
grep -q 'not a default' "$doc"
echo
echo "DEFECT: 'passing it empty' and 'its default' are the same value. Outside a pull_request event (workflow_dispatch, push) GITHUB_BASE_REF is unset, no --diff-base is passed, and the DEFAULT audits the whole repository — the expensive path the docs say is only reachable by deliberate opt-in."
exit 0

what it printed

=== the doc's claim:
84:- **Leave `diff-base` at its default.** Passing it empty audits the whole
85-  repository, which is a deliberate opt-in, not a default.

=== action.yml's declared default for diff-base:
  diff-base:
    description: "Audit only files changed against this ref. Defaults to the PR base; set empty to audit the whole repo (expensive)."
    required: false
    default: ""

=== the only place a base is derived when the input is empty:
266:        base="$DIFF_BASE"
267-        if [ -z "$base" ] && [ -n "${GITHUB_BASE_REF:-}" ]; then
268-          git fetch --no-tags origin "+refs/heads/$GITHUB_BASE_REF:refs/remotes/origin/$GITHUB_BASE_REF"
269-          base="origin/$GITHUB_BASE_REF"
270-        fi

=== and the workflow the same page tells you to add:
171:  workflow_dispatch:
176:      github.event_name == 'workflow_dispatch' ||

DEFECT: 'passing it empty' and 'its default' are the same value. Outside a pull_request event (workflow_dispatch, push) GITHUB_BASE_REF is unset, no --diff-base is passed, and the DEFAULT audits the whole repository — the expensive path the docs say is only reachable by deliberate opt-in.

refutation — codex STANDS

I traced action.yml from the diff-base declaration through argument construction. Its declared default is the empty string. A base is synthesized only when GITHUB_BASE_REF is nonempty; otherwise no --diff-base argument is supplied and repository-wide auditing follows. Consequently a workflow_dispatch run using the documented default reaches the same behavior the page labels a deliberate empty-value opt-in.

ref 09b6b339405f83a44741b2fc83df2829d3614ad3da602d198f0960909de7b3ac#R5

R6 medium reproduced

concepts/trust-and-security.mdx says the isHumanAdmin rule "guards **thirteen** admin write paths" and then enumerates fourteen of them; the code has 36 such guard sites, and the list omits gates the docs elsewhere present as the human gate (adjudicate_critic_finding, promote_control, the mission-steering writes), so a reader auditing the trust model gets a wrong and incomplete inventory.

where: site/src/content/docs/docs/concepts/trust-and-security.mdx:13
tier: REPRODUCED (declared REPRODUCED)

the script that was executed

#!/bin/sh
set -eu
doc=site/src/content/docs/docs/concepts/trust-and-security.mdx
echo "=== the doc's claim and its own enumeration:"
sed -n '11,21p' "$doc"
grep -q 'thirteen' "$doc"
echo
echo "=== every isHumanAdmin guard site in internal/, by file:"
grep -rn '!opts\.isHumanAdmin(req)' internal | sed 's/:.*isHumanAdmin.*/  <- guard/'
n=$(grep -rn '!opts\.isHumanAdmin(req)' internal | wc -l | tr -d ' ')
echo
echo "guard sites found: $n ; the doc says: thirteen"
echo
echo "=== gates the doc's enumeration omits entirely:"
grep -rn '!opts\.isHumanAdmin(req)' internal/criticscoretools.go internal/brain/criticscoretools.go internal/brain/controltools.go internal/brain/missions.go 2>/dev/null | head -20
[ "$n" -ne 13 ]
echo
echo "DEFECT: the number is wrong by the code ($n guard sites) and by the page's own list (fourteen items), and the list omits the critic-finding, control-promotion and mission-steering gates."
exit 0

what it printed

=== the doc's claim and its own enumeration:
Nothing that changes what a future audit run does — a memory promotion, a
skill proposal, a fleet-published skill, a promoted control, a superuser
grant — happens without a human approving it. One rule, `isHumanAdmin`,
guards **thirteen** admin write paths (`approve_proposal`, `reject_proposal`,
`add_memory(shared=true)`, `promote_memory`, `promote_reference`, the UI's
proposal-approve/reject endpoints, `sync_put`/`sync_delete`,
`promote_endpoint`, and the four principal-management writes): `isAdmin`
**and** no `subagent` claim on the token. This is the same gate described in [the control gate
tools](/docs/mcp-tools/) and [the learning loop](/docs/concepts/memory-and-learning-loop/),
stated here as the security property it actually is — an agent cannot
unilaterally make itself, or a later agent, more trusted.

=== every isHumanAdmin guard site in internal/, by file:
internal/brain/tasks.go  <- guard
internal/brain/tasks.go  <- guard
internal/brain/tasks.go  <- guard
internal/brain/tasks.go  <- guard
internal/brain/tasks.go  <- guard
internal/brain/tasks.go  <- guard
internal/brain/reference.go  <- guard
internal/brain/recordings.go  <- guard
internal/brain/missions.go  <- guard
internal/brain/missions.go  <- guard
internal/brain/missions.go  <- guard
internal/brain/missions.go  <- guard
internal/brain/memory.go  <- guard
internal/brain/memory.go  <- guard
internal/brain/learn.go  <- guard
internal/brain/learn.go  <- guard
internal/brain/gateway.go  <- guard
internal/brain/gateway.go  <- guard
internal/brain/criticscoretools.go  <- guard
internal/brain/criticscoretools.go  <- guard
internal/brain/criticscoretools.go  <- guard
internal/brain/controltools.go  <- guard
internal/brain/controltools.go  <- guard
internal/brain/controltools.go  <- guard
internal/brain/controltools.go  <- guard
internal/brain/artifacts.go  <- guard
internal/brain/artifacts.go  <- guard
internal/brain/analytics.go  <- guard
internal/brain/advpool.go  <- guard
internal/brain/advpool.go  <- guard
internal/brain/admin.go  <- guard
internal/brain/admin.go  <- guard
internal/brain/admin.go  <- guard
internal/brain/admin.go  <- guard
internal/brain/admin.go  <- guard
internal/brain/admin.go  <- guard

guard sites found: 36 ; the doc says: thirteen

=== gates the doc's enumeration omits entirely:
internal/brain/criticscoretools.go:57:			if !opts.isHumanAdmin(req) {
internal/brain/criticscoretools.go:67:			if !opts.isHumanAdmin(req) {
internal/brain/criticscoretools.go:83:			if !opts.isHumanAdmin(req) {
internal/brain/controltools.go:133:			if !opts.isHumanAdmin(req) {
internal/brain/controltools.go:158:			if !opts.isHumanAdmin(req) {
internal/brain/controltools.go:204:			if !opts.isHumanAdmin(req) {
internal/brain/controltools.go:219:			if !opts.isHumanAdmin(req) {
internal/brain/missions.go:63:			if !opts.isHumanAdmin(req) {
internal/brain/missions.go:96:			if !opts.isHumanAdmin(req) {
internal/brain/missions.go:109:			if !opts.isHumanAdmin(req) {
internal/brain/missions.go:122:			if !opts.isHumanAdmin(req) {

DEFECT: the number is wrong by the code (36 guard sites) and by the page's own list (fourteen items), and the list omits the critic-finding, control-promotion and mission-steering gates.

refutation — codex STANDS

I counted the page's own parenthetical inventory and inspected the guarded tools. Its entries total fourteen when the four principal-management writes are expanded, not thirteen. Additional human-admin-gated mutations include critic adjudication, control promotion, mission pause/resume/cancel, and task-level mission steering, none of which appears in that claimed inventory. Although raw guard-site count is not identical to logical write-path count, that distinction cannot rescue either the self-miscount or the omissions.

ref 09b6b339405f83a44741b2fc83df2829d3614ad3da602d198f0960909de7b3ac#R6

R7 low reproduced

docs/ui-tour/records.mdx describes "the **four checks** certverify.VerifyRecord runs (signature, ledger, subject, rekor)" but VerifyRecord runs five, and the one omitted is "statement" — the check added precisely because a record's human-readable half could be doctored while verify still printed "verified"; unlike the signed console bundle the code comment excuses, this file is freely editable.

where: site/src/content/docs/docs/ui-tour/records.mdx:46
tier: REPRODUCED (declared REPRODUCED)

the script that was executed

#!/bin/sh
set -eu
doc=site/src/content/docs/docs/ui-tour/records.mdx
echo "=== the doc's claim:"
grep -n -A2 'four checks' "$doc"
echo
echo "=== the checks VerifyRecord actually constructs:"
grep -n 'Check{Name: "' internal/certverify/certverify.go
n=$(grep -c 'Check{Name: "' internal/certverify/certverify.go)
echo "checks constructed: $n"
echo
echo "=== the package's own header:"
grep -n 'the same five checks' internal/certverify/certverify.go
grep -n 'runs the five checks' internal/certverify/certverify.go
echo
grep -q 'four checks' "$doc"
[ "$n" -eq 5 ]
! grep -q 'statement' "$doc" || echo "(note: 'statement' appears elsewhere on the page, but not in the enumerated check list)"
grep -n 'signature, ledger, subject, rekor' "$doc"
echo
echo "DEFECT: the docs enumerate four checks and omit the 'statement' check that catches a doctored readable record."
exit 0

what it printed

=== the doc's claim:
46:Below the chain line: the **four checks** `certverify.VerifyRecord` runs
47-(signature, ledger, subject, rekor), each shown green or red with its own
48-detail text; the commit's message, author, and date; and the attribution

=== the checks VerifyRecord actually constructs:
85:	sigCheck := Check{Name: "signature"}
103:	ledgerCheck := Check{Name: "ledger"}
138:		readableCheck := Check{Name: "statement"}
171:	subjectCheck := Check{Name: "subject"}
194:	rekorCheck := Check{Name: "rekor"}
checks constructed: 5

=== the package's own header:
4:// build-record verification: the same five checks the CLI (`corral certify
56:// VerifyRecord runs the five checks against an EXTERNAL trust anchor (pub +

47:(signature, ledger, subject, rekor), each shown green or red with its own

DEFECT: the docs enumerate four checks and omit the 'statement' check that catches a doctored readable record.

refutation — codex STANDS

I traced the records UI endpoint and renderer as well as certverify.VerifyRecord. For a valid signed record, VerifyRecord returns signature, ledger, statement, subject, and rekor checks, and the UI renders the returned checks generically. The UI test explicitly expects all five. The statement check is conditional on signature validity, but that does not validate the page's four-check inventory for successful records; it still omits a displayed integrity check.

ref 09b6b339405f83a44741b2fc83df2829d3614ad3da602d198f0960909de7b3ac#R7

R8 low reproduced

limitations.mdx — the page linked from every other page as the honest current state — describes the product as "v0.8.x" and names "v0.1" operational ceilings, while the repository at this commit tags v1.0.0-rc.11 and getting-started tells the reader to install that exact pin.

where: site/src/content/docs/docs/limitations.mdx:9
tier: REPRODUCED (declared REPRODUCED)

the script that was executed

#!/bin/sh
set -eu
echo "=== what limitations.mdx says the product is:"
grep -n 'v0\.8\|v0\.1 has real' site/src/content/docs/docs/limitations.mdx
echo
echo "=== the newest release in CHANGELOG.md:"
grep -n -m1 '^## \[v' CHANGELOG.md
echo
echo "=== the version the sibling docs pin:"
grep -n 'go install github.com/pdbethke/corralai/cmd/corral@' site/src/content/docs/docs/getting-started.mdx site/src/content/docs/docs/verify-a-record.mdx
echo
grep -q 'Corralai is \*\*v0.8.x\*\*' site/src/content/docs/docs/limitations.mdx
grep -q '^## \[v1.0.0-rc.11\]' CHANGELOG.md
grep -q 'corral@v1.0.0-rc.11' site/src/content/docs/docs/getting-started.mdx
echo "DEFECT: the limitations/roadmap page is a full major version behind the release it sits beside."
exit 0

what it printed

=== what limitations.mdx says the product is:
3:description: Where corralai is honestly at (v0.8.x), what it deliberately does not claim, and where it's heading next.
9:Corralai is **v0.8.x** — solo-maintained and moving fast. The foundations are in
13:## What v0.8.x is
99:Operationally, v0.1 has real, named ceilings, not "coming soon" hand-waving:

=== the newest release in CHANGELOG.md:
12:## [v1.0.0-rc.11] — 2026-09-08

=== the version the sibling docs pin:
site/src/content/docs/docs/getting-started.mdx:12:go install github.com/pdbethke/corralai/cmd/corral@v1.0.0-rc.11
site/src/content/docs/docs/verify-a-record.mdx:19:go install github.com/pdbethke/corralai/cmd/corral@v1.0.0-rc.11

DEFECT: the limitations/roadmap page is a full major version behind the release it sits beside.

refutation — codex STANDS

I compared limitations.mdx with CHANGELOG.md, the installation pages, and repository version metadata. The page repeatedly frames the current product as v0.8.x and later says v0.1, while the changelog's current release is v1.0.0-rc.11 and sibling pages install that exact version. The checked-out commit is descended from that tag, so prerelease status does not make the v0.8.x framing current.

ref 09b6b339405f83a44741b2fc83df2829d3614ad3da602d198f0960909de7b3ac#R8

Looked at and could not break (12)

Recorded so that "found nothing here" can be told apart from "never looked here".

Every internal /docs/... link in the scope resolves to a file that exists in site/src/content/docs/docs/ or to a real page (site/src/pages/warehouse.astro, recordings.astro, field-notes/[...slug].astro); the six /records/record-NN.json links in verify-a-record.mdx all exist under site/public/records/.
The anchor link getting-started.mdx:154 -> /docs/running-it/#dependency-dirs--bound-read-only-never-copied---repo-dir matches the github-slugger form of the actual heading in running-it.mdx:189.
The eleven cli/*.md pages in scope correspond one-to-one with the eleven cmd/*/ binaries, and scripts/gen-cli-docs.sh --check diffs both the repo copy and this site copy against each binary's real -h, so no stale or orphan generated reference is present.
Numeric defaults asserted by the docs match the code: --max-shards default 8 (advpool.DefaultMaxShards), the 0.8 --local certify bar (localCertifyThreshold), --top default 25, CORRALAI_ADDR 127.0.0.1:9019, CORRALAI_TASK_STALL_SECONDS 300, the leaderboard's 5-completed-task floor (advPoolEvidenceFloor), minOccurrences 3 for the learning-loop sweep.
The pairing-limitation numbers in limitations.mdx (rubocop 737, gin 29, flask 9, express zero) match the candidate column of the CI-pinned golden file testdata/foreign-sweep-expected.tsv exactly.
multi-model-herds.mdx's account of CheckDecorrelation is precisely right: internal/advpool/driver.go:836 compares only test-critic against test-writer by model name, and the page discloses that the mutant-generator is outside the check rather than implying otherwise.
mutation-testing.mdx's claim that --transparency never applies to the --local path holds: the flag is registered only in cmd/corral/certify_repo.go.
mcp-tools.mdx's assertion that create_mission no longer exists is correct (internal/brain/missions.go registers no such tool), and a sample of 23 unusual tool names from that page (browser_input, retarget_dependencies, supersede_task, mint_observer, fleet_claims, promote_reference, sync_delete, report_thought, query_recordings, call_capability, repo_grep, enqueue_task, reopen_task, list_pending_critic_findings, promote_memory, resolve_finding, despawn_subagent, browser_screenshot, list_task_artifacts, ask_fleet, swarm_topology, set_endpoint_enabled, list_all_endpoints) are all really registered in internal/brain.
warehouse.mdx's "eight preset queries" matches the eight entries in site/src/pages/warehouse.astro, and the commands it prints (corral verify --attest ... --rekor-index, corral ledger push/verify, corral seal --db, models rank --db) all exist as real verbs and flags in cmd/corral.
internal-forge.mdx's flag usage checks out: --pub exists on both `corral verify` (verify_attest.go:62) and `corral ledger verify` (ledger.go:44), and `corral certify verify` really takes --pubkey/--allow-unanchored (verify.go:127).
The Action inputs cited across github-action.mdx (test-command, diff-base, top, max-proven-missed, min-kill-rate, attest, push, motherduck-token, reviewer-model, verifier-model, review-fail-on, the three additive *-key inputs, model-key/model-key-env, shadow-model) all exist in action.yml with the described semantics, including the exit-3 review gate and the fork-PR behaviour.
publishing-recordings.mdx names scripts/export-golden-run.sh and scripts/scrub-golden-run.py, both of which exist; claims-and-leases.mdx's CLOBBER=1 is really read by cmd/corral-agent.

Reviewer's opinion

This scope is a large hand-written docs tree sitting on top of a codebase that has moved fast, and the failures are all of one shape: prose that was true of an earlier build and is now contradicted by the binary, by the repo's own tests, or by the page's own banner. The most serious is Finding 1 — `docs/ui-tour/memory.mdx` tells a reader that every `corral certify --local` run draws on the brain's memory corpus, eight lines under the banner that says no audit reads anything from the brain, and the `--local` path never contacts a brain at all. Finding 2 is the same defect from the other end: `concepts/memory-and-learning-loop.mdx` describes lesson injection into audit-run task instructions in the present tense, and the only function that does it has no production caller left. Findings 3 and 4 are commands and behaviour the docs assert that the binary does not have: `corral sync` is dispatched nowhere, and a diff whose changed source files cannot be paired exits 1 (the repo's own `TestUnpairableDiffFailsTheGate` pins it) where `github-action.mdx` promises a legitimate exit-0 pass — that one is a merge gate going red for a reason the page says is green. Finding 5 is a real cost trap: the page distinguishes "leaving `diff-base` at its default" from "passing it empty" when both are the identical empty string, so the `workflow_dispatch` opt-in the same page recommends silently audits the whole repository. Findings 6-8 are precision failures — a security page that counts thirteen human-gated write paths where the code has 36 and its own enumeration lists fourteen, a UI page that names four verification checks where `certverify.VerifyRecord` runs five (omitting exactly the check that was added because a doctored readable statement used to pass), and a limitations page that still calls the product v0.8.x on the day the repo tags v1.0.0-rc.11. The generated `cli/*.md` half of the scope is in much better shape than the hand-written half, because a gate regenerates it; nothing in the hand-written half is gated on anything but flag names.

Verifier's opinion

The review withstands adversarial verification on all eight findings. R1 is an explicit same-page contradiction corroborated by the local audit path. R2 describes a disconnected lesson-injection facility with no production path into audit instructions. R3 names a nonexistent CLI command. R4 conflates a documented clean no-scope outcome with an implementation that deliberately fails changed-but-unpairable source files. R5 contradicts the Action's actual empty-string default outside pull-request events. R6 is internally miscounted and materially incomplete. R7 omits the statement-integrity check from the successful-record UI inventory. R8 is stale against both the changelog release and installation instructions.