wherefore: standardize cross-links as relative Markdown links

[DustinVK]

Standardizes how wherefore items reference each other inside a body: a standard relative Markdown link to the target file, e.g. [P-004: verified brokers](P-004-slug.md) or [Q-007: token store](../questions/Q-007-slug.md) — never a bare slug and never an Obsidian [[wikilink]]. Link text leads with the target ID.

Why Markdown links (universal compatibility): they render as real links in GitHub, Obsidian, VS Code, and the dashboard. Wikilinks only resolve in the Obsidian family and show as literal text on GitHub — the opposite of the goal. Frontmatter refs (decision_ref, question_ref, supersedes, …) stay bare; this standard is for body prose only. Captured as decision 2026-07-19-markdown-crosslinks.

The standard (docs + skills)

• AGENTS.md gains a canonical Linking section — and packages/wherefore/bin/prepare-package.js propagates it into the scaffolded template, so consuming repos get it.
• capture, slate, supersede, resolve skills + seed.md's embedded plan README + wherefore/plan/README.md + a CLAUDE.md pointer all teach the format.

Dashboard renders the new links

The dashboard serves routes, not .md files, so .md cross-links are rewritten at build time:

• New src/lib/md-links.mjs — config-time filename → route map (basename-keyed; P-*/Q-*/date-slug names are disjoint) + pure rewriteMdHref.
• New rehype plugin covers pipeline-rendered bodies (plan detail, questions, now-view cards); log bodies go through renderInline, which gets the same rewrite and now protects link syntax shown inside code spans (so a `[label](x.md)` example stays literal instead of becoming a stray link).
• Adds @astrojs/markdown-remark (a build-time dependency): Astro 7's default Markdown processor only runs rehypePlugins with it installed — Astro's own prescribed fix. Switches to the well-established unified processor; all prior tests still pass.

Dogfood

• Migrated this repo's 4 - See also: <slug> lines to Markdown links.

Tests & verification

• 54 tests pass — unit (buildMdLinkMap, rewriteMdHref, renderInline map + code-span protection) and integration (both render paths, via fixtures with relative .md links).
• Built against real wherefore/ data: cross-links resolve to /log/… routes; example links render as code; migrated See also lines are clickable.
• claude plugin validate passes; the package regeneration propagates the Linking section.

Notes / out of scope

• Question deep-link anchors (/questions#Q-NNN) deferred — question links resolve to /questions.
• Legacy [[…]] (e.g. in expurge) left as-is: forward-only, no dashboard back-compat.

🤖 Generated with Claude Code