docs(reference): fix contradictions and document the hooks

[MANVENDRA-github]

Why

docs/reference.md opens by calling itself:

a per-file, per-module, per-flow map of what the codebase does

It documented neither the seven hooks nor the two test files that cover them, and it contradicted the code in three places.

Contradictions

1. "Do not edit" on three files sync deliberately preserves.

DOC:  | `opencode.json` | generated | ... **Do not edit.** |
CODE: sync-harnesses.js  "may hold the user's other OpenCode config" (D20)
HOOK: protect-generated-dirs allows editing it

Three files disagreed about whether you may touch .mcp.json, .cursor/mcp.json, and opencode.json. They are written when MCP sources exist, never deleted, and may carry your own servers.

2. "Wipe the entire .cursor/ directory. Cursor stores no per-user state in this tree."

That sentence is the bug fixed in the previous PR. It deleted .cursor/environment.json on every sync.

3. hooks/<name>.{sh,js} — all seven hooks are .js. There has never been a .sh hook.

Staleness

• Test inventory listed 5 files; the CI section claimed "98 unit tests." Reality: 7 files, 243 cases.
• The .claude/ wipe list omitted .claude/hooks/, which syncClaude does wipe.
• No inventory row for LICENSE, SECURITY.md, CODE_OF_CONDUCT.md, release.yml, dependabot.yml, the PR template, or the issue forms.
• No row for the per-user state each harness keeps at the top of its directory — the distinction that the whole "wipe what you own" rule turns on.

New: a Hook reference section

Seven executable guards, previously absent from the map. Documents the process contract (JSON on stdin, exit 0 allow / 2 block, stderr surfaces to Claude, fail open on malformed input), that sync copies hooks but nothing enables them, that none inspects tool_name because the settings.json matcher does the routing, and a table of what each blocks — including the lines each deliberately does not cross (rm -rf ./build is fine; a feature branch may be force-pushed).

Plus a Release-workflow section recording the two facts that are easy to get wrong: a tag push runs the workflow as it existed at the tagged commit, and only the chore(sync): regenerate harness outputs for X commit is sync-clean — the chore(release): X commit bumps the version before the output is regenerated.

Verification

Every figure checked against the tree, not from memory:

243 tests?             243
7 hook files?          7
protect-generated-dirs 49 cases   (doc says 49)
hooks.test.js          96 cases   (doc says 96)
sync-check perms       {'contents': 'read'}
release perms          {'contents': 'write'}
package private        true

All 7 newly-referenced files exist. The one in-page anchor (#hook-reference) resolves. And all 11 rmGenerated calls were diffed against the four per-adapter wipe lists — they now agree line for line.

$ grep -n 'entire `.cursor/`\|stores no per-user state\|98 unit tests\|{sh,js}' docs/reference.md
(none)

$ npm run lint   # PASS
$ npm test       # 243 pass, 0 fail
$ npm run sync   # clean, no drift

Docs-only — no source or generated output changes.