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>

.claude/commands/adr.md

@@ -2,10 +2,10 @@
 description: Record an architectural decision in six lines
 ---
 
-Append an ADR to `docs/decisions.md` using the exact format at the top of that file.
+Append an ADR to `harness/decisions.md` using the exact format at the top of that file.
 
 First, before writing anything: find the doc that owns this topic via the ownership table in
-`docs/README.md` and read it. If it already carries the rule, do not write an ADR — amend that doc
+`harness/README.md` and read it. If it already carries the rule, do not write an ADR — amend that doc
 and say that is what you did. An ADR that restates an existing doc is a duplicate, not a decision.
 
 Rules:

.claude/commands/audit.md

@@ -16,7 +16,7 @@ Look for:
 - Tests that assert on private helpers, or that need a mock to exist.
 - Dead code, commented-out code, `TODO`s older than the feature that introduced them.
 - Comments that narrate control flow.
-- Anything in `docs/` describing code that no longer exists — excluding `ideas/` and
+- Anything in `harness/` describing code that no longer exists — excluding `ideas/` and
   `reference/`, which are never audited against the code and must not be opened here.
 
 Report as a table: item, location, why it has not earned its place, LOC recovered if deleted,

.claude/commands/invariants.md

@@ -3,7 +3,7 @@ description: Check the architecture invariants against the code, not against the
 ---
 
 `verify.sh` checks what a grep can check. This pass checks the nine invariants in
-`docs/architecture.md`, which need reading the code. Run at arc boundaries, before a freeze, and
+`harness/architecture.md`, which need reading the code. Run at arc boundaries, before a freeze, and
 before the first deploy.
 
 For each invariant, answer **held / violated / not yet applicable**, with a file and line when

.claude/commands/refresh-docs.md

@@ -5,12 +5,12 @@ description: Reconcile the docs against the actual code and report drift
 Reconcile documentation with reality. The code is the truth; the docs are the suspects.
 
 1. Inventory the actual Go files, their line counts, and the non-stdlib dependencies in `go.mod`.
-2. Compare against `docs/state.md`: inventory rows, counters, latent items.
+2. Compare against `harness/state.md`: inventory rows, counters, latent items.
    Recount the counters **from the code** — number of render transforms, routing cases, views,
    output formats, extensions — rather than trusting the recorded numbers.
-3. Check `docs/architecture.md` STATUS lines: has a primitive become real, or is one described
+3. Check `harness/architecture.md` STATUS lines: has a primitive become real, or is one described
    as live when it is not built?
-4. Check `docs/content-model.md` against what the parser actually accepts. It describes today's
+4. Check `harness/content-model.md` against what the parser actually accepts. It describes today's
    behaviour and carries no markers, so every sentence in it is a claim to test. Frontmatter fields
    the code reads but the doc omits are drift; fields the doc promises but the code ignores are worse
    drift. Worst, and the kind that has actually shipped: a subcommand, flag or gate the doc describes