docs: fix broken cross-refs and stale names across how-it-works/roadmap/bff/README

[feffef]

Scope

Bundles all non-conflicting documentation fixes from the recent review into a single PR to minimize churn. Intentionally excludes two lines that overlap with the parallel NavigationError PR (docs/how-it-works.md:254 and docs/roadmap.md §8 TypeError wording).

Finding (primary)

FINDING-03 | WARNING | Style / Documentation
Location: docs/how-it-works.md:380, docs/how-it-works.md:400, heading sequence

Three broken pointers in how-it-works.md:

1. Line 380 referenced a parameter named apiRoot — linkTo has no such parameter; the option is named resource.
2. Line 400 referenced "Section 7.3 for best practices" — §7 has no subsections. Readers following the pointer get lost.
3. Section numbering jumps from §7 directly to §9, leaving §8 missing and any other "see §N" references suspect.

Concrete impact: a reader learning the library from how-it-works.md chases pointers that lead nowhere, losing trust in the doc.

Approach chosen: B — fix + preserve intent

For the broken §7.3 reference, the doc's intent was to caution against caching hrefs. The fix inlines that guidance rather than silently deleting the parenthetical — the reader still gets the HATEOAS warning without a dangling pointer.

Alternatives considered

• A — minimal patch: just delete the broken pointer text. Rejected because the surrounding sentence reads incomplete without the caution.
• C — A/B + fill the §8 gap with a new FetchFactory section: rejected as out of scope — authoring new long-form prose is a separate doc task.

Other fixes bundled (all docs, non-conflicting)

• Quick Fix 1: docs/roadmap.md §1 stale navigableOwner/MetadataStore → actual runtime-metadata map names.
• Quick Fix 7: README.md let restocked → const restocked (consistency).
• Quick Fix 8: docs/hateoas-bff-example.md §4 "Triggered by" column uses the path-based /bff/<view> routing matching §2 and the Fastify routes.
• Quick Fixes 4/5/6: rolled into the FINDING-03 remediation (same lines).

Excluded (handled in parallel PR)

• Quick Fix 2 (docs/roadmap.md §8 link-extraction.ts reference) — touched by the NavigationError PR.
• Quick Fix 12 (docs/how-it-works.md:254 TypeError claim) — the NavigationError PR rewrites this line to reflect the new class.

Test plan

• npx jest — all tests pass (doc-only change).
• Verified no remaining "§9", "§10", "§11", "Section 9", "Section 10", "Section 11" references inside how-it-works.md after renumbering.

Review checklist

• Dedicated opus peer review: approved

[feffef]

Opus Reviewer (on behalf of @feffef): LGTM (would approve if GitHub allowed self-approval). Verified every fix against the source of truth:

• Fix 1 (roadmap §1): apiClientByNavigable and linksByNavigable match the WeakMap names in src/runtime-metadata.ts:19,24. Stale navigableOwner/MetadataStore names are gone.
• Fix 4 (apiRoot → resource): how-it-works.md:380 now says resource, consistent with ConnectOptions.resource at src/type-system.ts:144.
• Fix 5 (§9/10/11 → §8/9/10): Heading sequence in how-it-works.md is now contiguous (1–10, no gap). Grep across the repo for §9, §10, §11, Section 9/10/11 turns up only the self-reference see §9 TODO in hateoas-bff-example.md:183, which predates this PR (the TODO section there is §8 within that file — pre-existing drift unrelated to FINDING-03's scope). The cross-doc reference at hateoas-bff-example.md:44 was correctly updated from §9 to §8.
• Fix 6 (broken 7.3 pointer): Replaced with a short inline HATEOAS caching caution — standalone and appropriate for the bullet's intent.
• Fix 7 (let → const): README.md:85 uses const as intended.
• Fix 8 (bff-example §4 table): All eight rows use path-based GET /bff/<view> syntax matching the actual Fastify routes at examples/hateoas-bff/bff-routes.ts:986,991,996,1025,1030,1047,1052,1057. Spot-checked home/category/product/search/cart — all correct.

Scope discipline: how-it-works.md:254 (TypeError claim, owned by PR #4) and roadmap.md §8 (Standardized Error Class Hierarchy, owned by PR #4) both untouched. Diff stat confirms: 4 files, 16 insertions, 16 deletions — no scope creep.

Minor observation (not blocking, not in scope for this PR): docs/hateoas-bff-example.md:183 contains a pre-existing stale see §9 TODO reference — should point to §8 within that same file. Worth a separate small fix some time, but has nothing to do with this PR.

Ship it.