rename docs/ to harness/, and reserve docs/ for the reader

docs/content-model.md opens with "Engine specification". It is also where the
rule lives that a leading underscore makes a file unaddressable — and the human
who owns this site did not know that rule, because nothing in this repository is
addressed to an author. Twelve documents named docs/ while being exclusively
about building the parser is a signpost pointing at the wrong room.

Naming the directory for its audience makes the gap visible instead of hiding it.
docs/ is now reserved and deliberately absent: an empty docs/ is an honest
statement that end-user documentation does not exist, where docs/ full of parser
specs was a claim that it did.

HARNESS.md stays at the root. Root holds the three entry points — README.md for a
human, CLAUDE.md for an agent, HARNESS.md for whoever maintains the machine — and
harness/README.md is the map of the directory, so moving the guide inside would
have collided with it for nothing.

Mechanical and wide: 100 path references across 24 files. Every verify.sh gate
that names a doc by path, the directory lists the dangling-path and ADR-number
gates scan, surface.sh's output target, the Makefile, CLAUDE.md's read order, the
skill, four commands, and two Go package comments. A first pass with a shell loop
silently edited only four files and the rest still said docs/; the fix was to
write the file list out and check the remaining count was zero rather than trust
the loop's exit status.

No rule, threshold, gate or obligation moved — this is a rename, and the gates
demonstrated it twice: they stayed green on the new paths, and the ADR-number gate
caught ADR-0082 before the entry existed.

Deferred, both on the human's call: the end-user documentation site itself, which
wants its own decision about where it lives and whether its claims are gated; and
moving examples/ under docs/, since demo-site is a live site root that verify.sh,
the coverage test and make demo all point at, and moving it would couple a rename
to a design nobody has made.

31 files, +146/-106.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

harness/toolchain.md

@@ -0,0 +1,48 @@
+# Toolchain and external contracts
+
+What this harness was built against, and which of those are contracts it depends on rather than
+incidentals. Recorded because a failure long after the fact is otherwise indistinguishable from a bug in
+the harness itself. Update the version line when you deliberately move; leave the rest alone.
+
+**Verified working:** 2026-07-28
+
+| Thing | Version then | Harness depends on |
+|---|---|---|
+| Go | 1.26.1 (darwin/arm64) | `go list -f`, `go vet`, `go build`, `go test -race`, `gofmt -l`. All stable since 1.11 |
+| git | 2.53.0 | `status --porcelain -uall`, `rev-list <sha>..HEAD -- '*.go'`, `rev-parse --verify`, `core.hooksPath` (2.9+) |
+| Claude Code | 2.1.119 | the four formats below |
+| bash | macOS default (3.2-era) + BSD userland | `verify.sh` avoids bashisms and GNU-only flags; `grep -L`, `wc -l`, `xargs`, `awk` are POSIX use |
+
+## The four agent-tooling contracts
+
+These are the ones most likely to move, and the ones whose breakage looks like a harness bug:
+
+1. **`CLAUDE.md` is loaded automatically** from the repo root on every request. If that stops being true,
+   nothing enforces the constitution and the agent will behave like a stock assistant.
+2. **`.claude/skills/<name>/SKILL.md`** — a Markdown file in a directory named for the skill, which fires
+   on request content matching its description. The feature loop depends on firing *without* being
+   invoked; if skills come to need explicit invocation, the loop silently stops applying.
+3. **`.claude/commands/<name>.md`** — Markdown with a YAML frontmatter `description:`, invoked as
+   `/<name>`, `$ARGUMENTS` substituted. Used by `/verify`, `/audit`, `/leaf`, `/refresh-docs`, `/adr`,
+   `/invariants`.
+4. **`.claude/settings.json`** — a `permissions` object with `allow` / `ask` / `deny` arrays of
+   `Tool(pattern)` strings. Only a convenience: if the schema changes, the harness still works, you just
+   get more prompts.
+
+## Not depended on
+
+No CI service, no container registry, no language server, no linter binary, no package manager beyond
+`go mod`. The `Makefile` is a convenience wrapper only: every target is one `go` or `verify.sh` command,
+and the gate never invokes `make`, so a machine without it loses nothing but typing.
+
+`verify.sh` runs offline with nothing but Go and git on `PATH`, which is deliberate — the gate must work
+on a machine you have not configured for two years.
+
+`VERIFY_DOCKER=1` adds a container build step and needs `docker`; it is opt-in and off by default.
+
+## If something breaks after a long absence
+
+Check in this order, cheapest first: `go version` and `git --version` against the table above; then
+whether `verify.sh` fails in the `documentation` block (a harness-internal problem) or the `go` block (a
+toolchain or code problem); then whether the agent is still reading `CLAUDE.md` at all — ask it to quote
+a hard rule, and if it cannot, the problem is contract 1 and nothing downstream will behave.