Tooling: add docs-reachable check + --docs-graph view to keep the doc tree connected from AGENTS.md

Every CLAUDE.md, DETAILS.md, and `docs/` file should be discoverable by an agent (or human) entering at `AGENTS.md` and walking references. Nothing enforced that before, so docs silently went orphan (14 unlinked guides, 4 subsystem CLAUDE.md). Two tools on one shared graph core (`docs_graph.go`):

- **`docs-reachable`** (`IsFast`, error not warn): fails when an enforced doc can't be reached from `AGENTS.md`. BFS over references, where a reference is any mention (Markdown link, `@import`, backtick path, bare path token) treated equally. A `CLAUDE.md` also counts as reached when a reachable doc names its *directory* (architecture.md lists subsystems as `` `dir/` ``, and Claude Code auto-injects from the dir anyway); every other doc must be named. Matching is generous (relative, root-relative, ≥2-segment suffix) so over-connecting hides a would-be orphan rather than inventing a false CI failure. `docs/specs` + `docs/notes` (self-declared ephemeral scratch) and the repo-root loader `CLAUDE.md` are excluded. Wired into the CI `hygiene` job. Shrink-wrapping allowlist (`docs-reachable-allowlist.json`) for intentional exemptions; goal is an empty list.
- **`pnpm check --docs-graph`**: renders the discoverability tree from `AGENTS.md` in the same box-drawing style as `--graph`, closest-to-root placement, `(dir reference)` tags, and a red orphan list at the bottom. A "show me" tool for spotting deeply-nested or orphaned docs.

Surfaces 18 real orphans today (left untouched here): they're for connecting, not exempting.

Docs: new § "Docs reachable" in `checks/DETAILS.md`, module-map + check-count rows, `--docs-graph` in the runner CLAUDE.md, and the allowlist consent contract extended in the file-length-allowlist rule.

Author: vdavid

.claude/rules/file-length-allowlist.md

@@ -15,6 +15,12 @@ reason and the same consent rule applies to adding one.
 
 The file-length check is warn-only — it doesn't fail the suite — so leaving the warning is always safe.
 
+The same contract also applies to `scripts/check/checks/docs-reachable-allowlist.json` (the `docs-reachable` check): the
+check shrink-wraps entries that are gone or now reachable, and adding/keeping an entry needs explicit consent. Prefer
+connecting the doc from a reachable one (a `CLAUDE.md` counts as reached when a reachable doc names its directory) over
+exempting it. Unlike the length checks, `docs-reachable` is an **error**, so a real orphan fails the suite until it's
+linked or (with consent) allowlisted.
+
 The same contract applies to `scripts/check/checks/claude-md-length-allowlist.json` (the `claude-md-length` check, which
 caps push-tier CLAUDE.md word counts): the check shrink-wraps stale `files` entries on local runs (remove gone /
 under-threshold, ratchet >10% slack down), and adding or raising an entry needs explicit user consent. If a CLAUDE.md

.github/workflows/ci.yml

@@ -577,6 +577,9 @@ jobs:
       - name: Check CHANGELOG commit links
         run: ./scripts/check/check --check changelog-commit-links --ci
 
+      - name: Check docs reachable from AGENTS.md
+        run: ./scripts/check/check --check docs-reachable --ci
+
       - name: Check workflow hardening
         run: ./scripts/check/check --check workflows-hardening --ci
 

scripts/check/CLAUDE.md

@@ -15,7 +15,8 @@ see [DETAILS.md](DETAILS.md).
   and misses before pnpm/SMB; record passes after the run).
 - `checks/inputs.go`: shared `Inputs` building blocks (mined from ci.yml filters).
 - `smb_orchestrator.go` + `smblease/` + `smb-lease/`: runner-level SMB Docker lifecycle behind a machine-wide lease.
-- `freestyle.go`: all freestyle.sh remote-VM execution. `graph.go`: `--graph` renderer. `stats.go`: CSV stats logging.
+- `freestyle.go`: all freestyle.sh remote-VM execution. `graph.go`: `--graph` (check dependency tree) renderer.
+  `docs_graph_render.go`: `--docs-graph` (doc-discoverability tree) renderer. `stats.go`: CSV stats logging.
 
 ## Must-knows
 

scripts/check/checks/CLAUDE.md

@@ -17,7 +17,8 @@ see [`../CLAUDE.md`](../CLAUDE.md).
 - `inputs.go`: shared `Inputs` building blocks. `allowlist.go` / `directives.go`: allowlist shrink-wrap + opt-out
   tracking plumbing.
 - Warn-only scanners with their JSON allowlists: `file-length.go`, `claude-md-length.go`, `e2e-durations.go`,
-  `website-bundle-size.go`.
+  `website-bundle-size.go`. Error-level allowlist scanner: `docs-reachable.go` (+ shared `docs_graph.go`), which fails
+  when a `CLAUDE.md` / `DETAILS.md` / `docs` file isn't reachable from `AGENTS.md`.
 
 ## Must-knows
 

scripts/check/checks/DETAILS.md

@@ -18,6 +18,9 @@ freestyle.sh remote execution), see [`../CLAUDE.md`](../CLAUDE.md).
 | `file-length-allowlist.json`                         | Allowlist for file-length check: `{ "exempt": { "path": reason }, "files": { "path": lineCount } }`. See § File-length allowlist.                                                                                     |
 | `claude-md-length.go`                                | Warn-only push-tier scanner: warns when a `CLAUDE.md` exceeds 600 words (`DETAILS.md` is the unlimited pull tier, not scanned). Allowlist with the same shrink-wrap semantics as file-length. See § CLAUDE.md length. |
 | `claude-md-length-allowlist.json`                    | Allowlist for claude-md-length: `{ "files": { "path": wordCount } }`. Same ratchet/consent rules as file-length.                                                                                                      |
+| `docs_graph.go`                                      | Shared doc-discoverability graph: reachability from `AGENTS.md` over references between docs. Powers both the `docs-reachable` check and the `--docs-graph` renderer. See § Docs reachable.                           |
+| `docs-reachable.go`                                  | Errors (not warn-only) when any `CLAUDE.md` / `DETAILS.md` / `docs/` file can't be reached from `AGENTS.md`. Allowlist with the same shrink-wrap/consent semantics as file-length. See § Docs reachable.              |
+| `docs-reachable-allowlist.json`                      | Allowlist for docs-reachable: `{ "files": { "path": reason } }` of docs intentionally unreachable. Goal is empty. Shrink-wraps gone/now-reachable entries; adding one needs David's OK.                               |
 | `e2e-durations.go`                                   | E2E test duration flagger (warn-only): parses the Playwright JSON reports after each E2E run and flags tests over the 2 s budget. Embedded in both E2E checks, not a registry check. See § E2E test duration flagger. |
 | `e2e-duration-allowlist.json`                        | Per-platform (`macos` / `linux`) allowlist for the duration flagger: `{ "<spec>::<describe chain>::<title>": reason }`. Entries need a reason; new entries need David's OK.                                           |
 | `website-bundle-size.go`                             | Warn-only website `dist/` size budget: warns when the total grows >10% over the committed baseline. Self-skips without `dist/`. See § Website bundle-size baseline.                                                   |
@@ -185,6 +188,33 @@ local runs drop dead/under-threshold entries and ratchet >10%-slack entries down
 change. Adding or raising an entry needs David's OK (`.claude/rules/file-length-allowlist.md`); the fix for an oversized
 `CLAUDE.md` is to move depth into `DETAILS.md`, not bump the number.
 
+## Docs reachable
+
+`docs-reachable` (`IsFast`, an **error** not a warn: the doc tree must stay connected) enforces that every `CLAUDE.md`,
+`DETAILS.md`, and `docs/` file is discoverable from the single root `AGENTS.md` by link-walking, so a reader entering
+there can find every doc. `docs_graph.go` builds the graph (shared with the `--docs-graph` renderer in
+`../docs_graph_render.go`); `docs-reachable.go` is the check shell + allowlist.
+
+How reachability is decided (`BuildDocGraph`):
+
+- **One root, `AGENTS.md`.** A doc is reached when a doc already reached from the root references it. BFS, so each doc
+  is placed under its closest-to-root reference (a cycle just hits an already-reached node and stops).
+- **A reference is any mention, syntax-agnostic:** Markdown link, `@import`, backtick path, or bare path token are all
+  equal. We watch intent, not form. Matching is generous (relative-to-source, repo-root-relative, and ≥2-segment path
+  suffix), because over-connecting only hides a would-be orphan, while a false orphan would be a noisy CI failure.
+- **The CLAUDE.md asymmetry:** a `DETAILS.md` or `docs/` file must be named, but a `CLAUDE.md` also counts as reached
+  when a reachable doc mentions its _directory_ (`architecture.md` lists most subsystems as `` `some/dir/` ``, and
+  Claude Code auto-injects a `CLAUDE.md` from its directory regardless). Such edges are tagged `ViaDir`; the renderer
+  shows "(dir reference)".
+- **Ephemeral dirs are excluded** from the enforced candidate set: `docs/specs` and `docs/notes` self-declare in their
+  READMEs as temporary scratch "wiped periodically", so requiring each to be linked fights their purpose
+  (`ephemeralDocDirs`). The repo-root `CLAUDE.md` (the loader shim that only `@import`s the entry docs) is excluded too.
+
+`docs-reachable-allowlist.json` maps a doc path → the reason it's intentionally unreachable. The goal is an empty list:
+connect docs rather than exempt them. Shrink-wrap drops entries whose file is gone or which became reachable; adding or
+keeping one needs David's OK (`.claude/rules/file-length-allowlist.md`). To inspect the whole tree and spot
+deeply-nested or orphaned docs visually, run `pnpm check --docs-graph`.
+
 ## E2E test duration flagger
 
 The E2E suites were hard-won down to under 2 s per test; `e2e-durations.go` defends that. After a successful E2E run,
@@ -253,16 +283,16 @@ RUSTSEC ignores — that's a quarterly task in `docs/maintenance.md`.
 
 ## Apps and check counts
 
-| App        | Tech     | Checks                                                                                                                                                                                                                                                                    |
-| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Desktop    | Rust     | rustfmt, clippy, cargo-audit, cargo-deny, cargo-machete, cargo-udeps (CI-only), jscpd, log-error-macro, error-string-match, lock-poison, bindings-fresh, ipc-enum-camelcase, tests, integration-tests (Docker SMB), tests-linux (slow)                                    |
-| Desktop    | Svelte   | prettier, eslint, svelte-kit-sync, eslint-typecheck-svelte, eslint-typecheck-typescript, stylelint, css-unused, a11y-contrast, btn-restyle, bare-poll, svelte-check, import-cycles, knip, type-drift, tests, e2e-linux-typecheck, e2e-linux (slow), e2e-playwright (slow) |
-| Website    | Astro    | prettier, eslint, typecheck, build, html-validate, bundle-size (warn-only), e2e                                                                                                                                                                                           |
-| Website    | Docker   | docker-build                                                                                                                                                                                                                                                              |
-| API server | TS       | oxfmt, eslint, typecheck, tests                                                                                                                                                                                                                                           |
-| Scripts    | Go       | gofmt, go-vet, staticcheck, ineffassign, misspell, gocyclo, nilaway, deadcode, go-tests, govulncheck                                                                                                                                                                      |
-| Other      | Metrics  | file-length (warn-only), CLAUDE.md-reminder (warn-only), claude-md-length (warn-only), changelog-commit-links, workflows-rustup (forbids `rustup target/component add` in workflows), ci-coverage (registry-to-workflows contract)                                        |
-| Other      | Security | workflows-hardening (SHA-pinning, no `pull_request_target`, job-scoped `id-token: write`)                                                                                                                                                                                 |
+| App        | Tech     | Checks                                                                                                                                                                                                                                                                                                                           |
+| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Desktop    | Rust     | rustfmt, clippy, cargo-audit, cargo-deny, cargo-machete, cargo-udeps (CI-only), jscpd, log-error-macro, error-string-match, lock-poison, bindings-fresh, ipc-enum-camelcase, tests, integration-tests (Docker SMB), tests-linux (slow)                                                                                           |
+| Desktop    | Svelte   | prettier, eslint, svelte-kit-sync, eslint-typecheck-svelte, eslint-typecheck-typescript, stylelint, css-unused, a11y-contrast, btn-restyle, bare-poll, svelte-check, import-cycles, knip, type-drift, tests, e2e-linux-typecheck, e2e-linux (slow), e2e-playwright (slow)                                                        |
+| Website    | Astro    | prettier, eslint, typecheck, build, html-validate, bundle-size (warn-only), e2e                                                                                                                                                                                                                                                  |
+| Website    | Docker   | docker-build                                                                                                                                                                                                                                                                                                                     |
+| API server | TS       | oxfmt, eslint, typecheck, tests                                                                                                                                                                                                                                                                                                  |
+| Scripts    | Go       | gofmt, go-vet, staticcheck, ineffassign, misspell, gocyclo, nilaway, deadcode, go-tests, govulncheck                                                                                                                                                                                                                             |
+| Other      | Metrics  | file-length (warn-only), CLAUDE.md-reminder (warn-only), claude-md-length (warn-only), docs-reachable (errors when a CLAUDE.md/DETAILS.md/docs file isn't reachable from AGENTS.md), changelog-commit-links, workflows-rustup (forbids `rustup target/component add` in workflows), ci-coverage (registry-to-workflows contract) |
+| Other      | Security | workflows-hardening (SHA-pinning, no `pull_request_target`, job-scoped `id-token: write`)                                                                                                                                                                                                                                        |
 
 ## Key decisions
 

scripts/check/checks/docs-reachable-allowlist.json

@@ -0,0 +1,4 @@
+{
+  "$comment": "Docs intentionally NOT reachable from AGENTS.md, each mapped to its reason. The goal is an empty list: connect docs instead of exempting them. The docs-reachable check shrink-wraps stale entries (file gone or now reachable) on local runs; adding or keeping an entry needs David's explicit consent (see .claude/rules/file-length-allowlist.md).",
+  "files": {}
+}

scripts/check/checks/docs-reachable.go

@@ -0,0 +1,142 @@
+package checks
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// docsReachableAllowlist is the on-disk shape of docs-reachable-allowlist.json.
+// `Files` maps a repo-relative doc path to the reason it's intentionally NOT
+// reachable from AGENTS.md. The goal is an empty allowlist: every doc connected.
+type docsReachableAllowlist struct {
+	Comment string            `json:"$comment,omitempty"`
+	Files   map[string]string `json:"files"`
+}
+
+func docsReachableAllowlistPath(rootDir string) string {
+	return filepath.Join(rootDir, "scripts", "check", "checks", "docs-reachable-allowlist.json")
+}
+
+// loadDocsReachableAllowlist reads the allowlist JSON. A missing or unparsable
+// file yields an empty allowlist (every orphan gets reported).
+func loadDocsReachableAllowlist(rootDir string) docsReachableAllowlist {
+	list := docsReachableAllowlist{Files: map[string]string{}}
+	data, err := os.ReadFile(docsReachableAllowlistPath(rootDir))
+	if err != nil {
+		return list
+	}
+	if err := json.Unmarshal(data, &list); err != nil {
+		return docsReachableAllowlist{Files: map[string]string{}}
+	}
+	if list.Files == nil {
+		list.Files = map[string]string{}
+	}
+	return list
+}
+
+// shrinkwrapDocsReachableAllowlist drops allowlist entries that no longer earn
+// their place: the doc is gone, or it's now reachable (so it needs no exemption).
+// Mutates list in place and returns one human-readable line per change.
+func shrinkwrapDocsReachableAllowlist(rootDir string, list *docsReachableAllowlist, orphanSet map[string]bool) []string {
+	var changes []string
+	for _, docPath := range sortedKeys(list.Files) {
+		switch {
+		case !fileExists(filepath.Join(rootDir, filepath.FromSlash(docPath))):
+			delete(list.Files, docPath)
+			changes = append(changes, fmt.Sprintf("removed %s (file no longer exists)", docPath))
+		case !orphanSet[docPath]:
+			delete(list.Files, docPath)
+			changes = append(changes, fmt.Sprintf("removed %s (now reachable from AGENTS.md)", docPath))
+		}
+	}
+	return changes
+}
+
+// RunDocsReachable fails when any enforced doc (CLAUDE.md, DETAILS.md, or a
+// docs/ file outside the ephemeral scratch dirs) can't be reached from AGENTS.md
+// by walking references between docs. A CLAUDE.md counts as reached when a
+// reachable doc mentions its directory; everything else must be named. Allowlist
+// entries (intentionally-unreachable docs) are suppressed; stale ones shrink-wrap
+// away outside CI. Unlike the length scanners this is an error, not a warning:
+// the doc tree must stay connected.
+func RunDocsReachable(ctx *CheckContext) (CheckResult, error) {
+	g, err := BuildDocGraph(ctx.RootDir)
+	if err != nil {
+		return CheckResult{}, fmt.Errorf("failed to build doc graph: %w", err)
+	}
+
+	orphanSet := make(map[string]bool, len(g.Orphans))
+	for _, o := range g.Orphans {
+		orphanSet[o] = true
+	}
+
+	allowlist := loadDocsReachableAllowlist(ctx.RootDir)
+	staleChanges := shrinkwrapDocsReachableAllowlist(ctx.RootDir, &allowlist, orphanSet)
+	if len(staleChanges) > 0 && !ctx.CI {
+		if err := writeJSONAllowlist(docsReachableAllowlistPath(ctx.RootDir), allowlist); err != nil {
+			return CheckResult{}, err
+		}
+		reformatWithOxfmt(ctx.RootDir, "scripts/check/checks/docs-reachable-allowlist.json")
+	}
+
+	var reported []string
+	for _, o := range g.Orphans {
+		if _, ok := allowlist.Files[o]; !ok {
+			reported = append(reported, o)
+		}
+	}
+
+	staleMsg := formatDocsStaleMsg(ctx.CI, staleChanges)
+	if len(reported) == 0 {
+		okMsg := fmt.Sprintf("All docs reachable from AGENTS.md (%d in graph)", len(g.Reached))
+		if len(allowlist.Files) > 0 {
+			okMsg = fmt.Sprintf("%s (%d allowlisted)", okMsg, len(allowlist.Files))
+		}
+		if staleMsg != "" {
+			if ctx.CI {
+				return CheckResult{Code: ResultWarning, Message: okMsg + "; " + staleMsg, Total: -1, Issues: -1, Changes: -1}, nil
+			}
+			return SuccessWithChanges(okMsg + "; " + staleMsg), nil
+		}
+		return Success(okMsg), nil
+	}
+
+	body := formatOrphans(reported, len(allowlist.Files))
+	if staleMsg != "" {
+		body += "\n" + staleMsg
+	}
+	return CheckResult{}, fmt.Errorf("%s", body)
+}
+
+// formatDocsStaleMsg renders the shrink-wrap note (or the CI-mode equivalent).
+func formatDocsStaleMsg(ci bool, staleChanges []string) string {
+	if len(staleChanges) == 0 {
+		return ""
+	}
+	verb := "Shrink-wrapped allowlist"
+	if ci {
+		verb = "Stale allowlist entries (a local run shrink-wraps them)"
+	}
+	return fmt.Sprintf("%s:\n  - %s", verb, strings.Join(staleChanges, "\n  - "))
+}
+
+// formatOrphans builds the failure body listing the unreachable docs.
+func formatOrphans(orphans []string, allowlisted int) string {
+	suffix := ""
+	if allowlisted > 0 {
+		suffix = fmt.Sprintf(" (%d allowlisted)", allowlisted)
+	}
+	var sb strings.Builder
+	for _, o := range orphans {
+		sb.WriteString("  - ")
+		sb.WriteString(o)
+		sb.WriteString("\n")
+	}
+	return fmt.Sprintf(
+		"%d %s unreachable from AGENTS.md%s. Link each from a doc that's already reachable (a CLAUDE.md also counts as reached when a reachable doc mentions its directory):\n%s",
+		len(orphans), Pluralize(len(orphans), "doc", "docs"), suffix,
+		strings.TrimRight(sb.String(), "\n"))
+}