docs: index the user guide and lint internal names

.github/scripts/docs-only.sh

@@ -25,5 +25,8 @@ if [ -n "$base" ] \
     esac
   done <<<"$files"
 fi
+if [ "$result" = true ]; then
+  scripts/check-guide-names.sh
+fi
 echo "docs_only=$result" >>"$out"
 echo "docs-only: $result" >&2

README.md

@@ -171,6 +171,29 @@ graft is early. The design is [docs/design.md](docs/design.md); work lands
 on short-lived branches through the merge queue. See
 [CONTRIBUTING.md](CONTRIBUTING.md).
 
+## Documentation
+
+User guide:
+
+- [Concepts](docs/guide/concepts.md): glossary and the git-to-graft table.
+- [MCP](docs/guide/mcp.md): every MCP tool, with its arguments and results.
+- [Server](docs/guide/server.md): config, tokens, repositories, lines, metrics and upgrades.
+- [Git migration](docs/guide/git-migration.md): import, follow GitHub, batch pull requests and export.
+- [FAQ](docs/guide/faq.md): git compatibility, offline use, lines, CI and the licence.
+- [Benchmarks](docs/guide/benchmarks.md): how the published timings were measured.
+- [Agents](docs/agents.md): how an agent session uses graft.
+
+[The same index](docs/guide/README.md) lives with the guide.
+
+## How it is built
+
+- [Design](docs/design.md)
+- [Plan](docs/plan.md)
+- [Decisions](docs/decisions.md)
+- [Status](docs/status.md)
+- [Trials](docs/trials)
+- [Notes](docs/notes)
+
 ## Licence
 
 [AGPL-3.0-only](LICENSE).

changes/WI-2549.md

@@ -0,0 +1 @@
+- User guide pages are indexed from the README and `docs/guide/README.md`, with the engineering record under "How it is built". Repository CI fails the docs-only path when the guide names an estate host, tracker, trial or internal id.

docs/guide/README.md

@@ -0,0 +1,23 @@
+# User guide
+
+- [Concepts](concepts.md): glossary and the git-to-graft table.
+- [MCP](mcp.md): every MCP tool, with its arguments and results.
+- [Server](server.md): config, tokens, repositories, lines, metrics and upgrades.
+- [Git migration](git-migration.md): import, follow GitHub, batch pull requests and export.
+- [FAQ](faq.md): git compatibility, offline use, lines, CI and the licence.
+- [Benchmarks](benchmarks.md): how the published timings were measured.
+- [Bench chart](bench.svg): the rendered timings the methodology describes.
+- [Agents](../agents.md): how an agent session uses graft.
+
+The same list is in the repository [README](../../README.md#documentation).
+
+## How it is built
+
+Engineering record, not part of the user guide:
+
+- [Design](../design.md)
+- [Plan](../plan.md)
+- [Decisions](../decisions.md)
+- [Status](../status.md)
+- [Trials](../trials)
+- [Notes](../notes)

docs/guide/benchmarks.md

@@ -25,9 +25,9 @@ as a speed change.
 
 ## What is not on the chart
 
-The twelve-run read-path medians recorded by WI-2341 on 2026-10-24 are
-not in any file under `bench/results/`. They are written in
-[docs/status.md](../status.md) and [docs/decisions.md](../decisions.md) (D31):
+The twelve-run read-path medians recorded on 2026-10-24 are
+not in any file under `bench/results/`. They are written in the engineering
+record listed under "How it is built":
 
 | | 1k graft / git | 10k graft / git |
 | --- | ---: | ---: |
@@ -48,17 +48,17 @@ graft is faster on full clone, sparse clone, `log --path` and blame at
 both recorded scales, and faster on concurrent clean lands at 10k
 (238 ms vs 365 ms). It is slower on `log -50`, status and, at 10k, sync.
 
-Read latency is a no-regression floor, not a phase-1 target (D31,
-2026-10-25). No read path may be slower than the WI-2341 medians above,
-and every operation stays O(change). Being 1.3× to 2.4× slower than git
-on log, status and sync in the single-run files is recorded, not a
-defect to close in phase 1. 2× faster than git is a later-phase target.
-WI-2400 is wont_do.
+Read latency is a no-regression floor, not a phase-1 target
+(recorded 2026-10-25). No read path may be slower than the twelve-run
+medians above, and every operation stays O(change). Being 1.3× to 2.4×
+slower than git on log, status and sync in the single-run files is
+recorded, not a defect to close in phase 1. 2× faster than git is a
+later-phase target. Closing that gap is out of scope for phase 1.
 
 ## Real-PR replay
 
 `bench/results/2026-10-24-real-prs/results.json`, 2026-10-24, 115 PRs in
-five cases (rdpapp split and stack, fluent2 registration, rustTorrent
+five cases (rdpapp split and stack, fluent2 registration, the qBittorrent importer
 qBittorrent, graft merge-back). Clean merges and conflicts match git on
 every case: 58 clean, 47 conflicts, graft-only and git-only clean both
 zero. One case (`rdpapp-stack`) has no `agreement` object; its graft and
@@ -73,8 +73,8 @@ The chart uses the agreement block.
 
 `bench/results/2026-10-24-branching/results.json`, seed 2362. The chart
 shows round trips and conflict blocks for trunk, git flow and release
-branches, graft-tracked against git. This file predates merge points
-(WI-2372). [docs/status.md](../status.md) records the later hand-off: with merge points,
+branches, graft-tracked against git. This file predates merge points.
+The engineering record lists the later hand-off: with merge points,
 graft reports the same conflicts as git (18 of 18 blocks) and merges
 `release/1.1` into `main` clean. That later run is not in this file, so
 it is not on the chart. The file will be regenerated; until then the

scripts/check-guide-names.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Fail if the user guide names estate hosts, trackers, or internal ids.
+# Repository CI only. Not part of graft's land path.
+set -euo pipefail
+root=$(cd "$(dirname "$0")/.." && pwd)
+cd "$root"
+shopt -s nullglob
+files=(docs/guide/* docs/agents.md)
+pattern='graft-dev|vogt|trial-[0-9]|rusttorrent|\bWI-[0-9]+|\bD[0-9]{2}\b|\bG[0-9]\.[0-9]+'
+if grep -nEiH "$pattern" "${files[@]}"; then
+  exit 1
+fi