docs: refresh user guide and README for v0.3.2

[RichardHightower]

What this is

The user-facing docs refresh for v0.3.2, covering docs/user_guide/*.md and README.md — the user-guide and readme targets in release.sync_docs. docs/designs/ is handled by a separate agent; index convergence and the wiki publish happen centrally afterwards, so nothing under docs/.index/ is touched here.

Why

v0.3.2 carries exactly one behaviour change, in scripts/okf-graph.py's cmd_validate. Through v0.3.1 the loop opened with:

if rel in ("index.md", "log.md"):
    continue

That continue was meant to excuse the bundle root's two structural files from the type and title warnings — they legitimately carry neither. But it skipped the whole loop body, including the broken-link and out-of-bundle-link checks. The result: a bundle's index.md is its entry point and its most linked-from file, and it was the one file in the bundle where a broken link was never reported.

v0.3.2 narrows the exemption to the two metadata checks it was always meant to cover. The links in those files are now validated like anyone else's.

What changed in the docs

File	Change
README.md	v0.3.2 bullet in the per-release roadmap list; graph engine test count 24 → 25 cases
docs/user_guide/user-guide.md	New paragraph under Validate explaining the narrowed exemption and its severities
docs/user_guide/cli-reference.md	validate table row notes link checks cover the root files; same test count fix

User-visible consequences now documented:

• A broken link in a bundle's root index.md or log.md is an error — validate exits 1 where it previously reported nothing.
• An out-of-bundle link there is a warning, so --strict gates it in CI.
• The default exit-code contract is unchanged: validate still exits 0 on warnings, which the skills and okf-curate.sh depend on.
• The metadata exemption is unchanged and depth-independent for indexes: any index.md is excused at any depth, but only the root log.md is structural — a nested sub/log.md still wants a type and title. This is the invariant test_root_index_and_log_have_their_links_validated locks down.

Deliberately left alone

• docs/user_guide/plugin-guide.md — its only mention of validation is the /okf-validate row in the slash-command table. Nothing there went stale, and an unnecessary edit to a published page costs a wiki republish for nothing.
• The validate warning list in user-guide.md — the four warning kinds are unchanged in v0.3.2; only their reach changed, which is what the new paragraph says.
• The README version row — already stamped 0.3.2 by the release commit.

Correction to the brief

The brief predicted the user-guide pages would still be describing pre-v0.3.1 behaviour. They are not. docs/user_guide/*.md show up in git diff v0.3.1..v0.3.2 --stat with substantial changes, but those are the v0.3.1 docs refresh, which landed after the v0.3.1 tag was cut and so falls inside this range. Ambiguous-concept resolution, off-bundle link reporting, criticality escalation and the bundle-rooted-anywhere curation hook were all already documented and accurate. Only the v0.3.2 change itself was missing.

One staleness the brief did not mention, caught by reading the range rather than the summary: v0.3.2 adds a test, so the # graph engine — 24 cases comment in both README.md and cli-reference.md was off by one. grep -c '^def test_' tests/test_okf_graph.py now returns 25.

Verification

hooks/pre-commit exits 0. Its only output is the pre-existing rendered pages/manifest stale warning, which resolves in the central ia-render pass.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01WMk8bhkMEUWfHi7VYzMzFX