docs(site): add the documentation site, phases 0-2

[lsimons]

Implements phases 0, 1 and 2 of S06.

What lands

Phase 0 — the site. Astro + Starlight in site/, LSD Warm theme (palette vendored from lsimons-dotfiles, Apache-2.0) with self-hosted Merriweather via @fontsource, so everything the site ships is redistributable by a fork. Nine operator pages in docs/guide/. The deploy workflow is ported from the organisation repository, with fetch-depth: 0 so Starlight's lastUpdated reads real git history rather than showing the deploy date on every page.

Phase 1 — the pipeline. scripts/sync-docs.py copies docs/**.md into the Astro content tree, derives frontmatter from each file's # heading, demotes the design record, rewrites repo-relative links, and fails the build on one that does not resolve. Raw Markdown twins ship at site/public/<slug>.md.

Phase 2 — the articles. An article-synthesis skill, plus four drafts, unpromoted. Promotion is a human's git mv into docs/articles/ and that gate has not been crossed — the Articles sidebar group is empty until someone reviews them.

Decisions worth reviewing

Requirement 7 is scoped to user-facing prose. Running the command checker over everything surfaced 95 mismatches, all correct. About half are commands renamed by S35 — a spec predating it says mdd confluence sync where the command is now sync-space. The rest are rejected or deferred commands named in "Rejected"/"Out of scope" sections. Neither is a defect: rewriting a spec to match today's CLI would falsify the record. The design record gets an advisory run that reports and exits zero.

_drafts/ did not do what the spec said. S06 claimed docsLoader() ignores the underscore prefix. Its glob is **/[^_]*.{md,mdx}, and [^_] matches the filename, so _drafts/foo.md was loaded and broke the build. Drafts are now _drafts/_<slug>.md; the spec is corrected.

llms-full.txt ignores the plugin's exclude option in starlight-llms-txt@0.11.0 — only the llms-small.txt route honours it. A local astro:build:done integration closes the gap, splitting on an explicit page-separator marker rather than guessing at heading boundaries.

Bugs found while documenting, not fixed here

Writing the guide against the code surfaced four things that need their own issues:

1. The Confluence confidentiality blacklist is not enforced. gate_push has zero production call sites; no path under src/mdd/confluence/ references the blacklist at all. The SharePoint half is enforced. S07 §2.4 says otherwise. Independently confirmed by two agents.
2. mdd search --type all returns only .qmd. An inclusive --glob overrides the --type md inclusion, so the widening filter narrows.
3. sharepoint.sync_root in config does nothing through the CLI. resolve_sync_root reads it with getattr against a plain dict, so it is always None. The unit test passes an attribute-shaped mock and passes.
4. The S26 restrictions check fails open — _user_can_update returns True on any exception, so the last cascade layer is advisory.

Plus stale spec text in S07 §2.6, S09, S39 and S14. All documented against the code, not the spec.

Gates

mise run ci is green and stays Node-free. Vale, astro check and the site build run in mise run docs-check and a path-filtered PR workflow. The site builds 64 pages.

Co-Authored-By: lsimons-bot bot@leosimons.com

---

Added after review: a link check over the built site

The sync step resolves each repo-relative link against the working tree, so it
catches a link to a file that does not exist. It cannot catch a link to a file
that does exist but is served at a different URL — which is exactly how a
casing bug reached the deployed site: Starlight lowercases the slug it derives
from a filename, so S07-data-protection.md is published at
.../s07-data-protection/, and every link into the spec and research sections
404'd while satisfying the existing check.

scripts/check-site-links.py crawls site/dist/ after a build and resolves
every internal href and src against the pages and assets Astro emitted. It
runs as mise run docs-links, inside docs-check. Fragments are stripped
rather than verified; anchor checking is a larger job and is not attempted.

It found seven broken links on its first run, from two distinct bugs in the
link rewriter. The commit message for check emitted URLs against the built site attributes all seven to the first cause; that is wrong, and this is the
accurate account.

Two were links wrapped across a newline. CommonMark permits a newline both
inside the link text and before the destination, and the line-by-line rewriter
saw neither — it did not rewrite them and did not report them:

[Configuration and
secrets](05-configuration.md)          docs/guide/07-confluence-first-sync.md

... per [S20](
S20-litellm-ai-client.md))             docs/spec/S21-ai-rewrite-and-index.md

The rewriter now groups contiguous non-code lines into blocks and matches
across them, keeping fence and indented-code exclusion intact.

Five came from a fence-detection bug, which is the more serious of the two.
Line 251 of S30-markdown-ir-conversion.md uses a four-backtick inline code
span to quote a literal triple-backtick fence:

  ```` ```confluence-xml ```` fence around the macro's serialised

The fence detector read those leading four backticks as an opening code
fence. No four-backtick closing fence follows, so every line after 251 was
treated as being inside a code block: passed through untouched, and never
checked, so nothing was reported. Twelve links in that one file were silently
left as relative paths.

This predates this PR — it was in the original rewriter too, hidden behind the
same silent-pass-through symptom. The fix follows CommonMark: a backtick
fence's info string may not contain a backtick, so a backtick run only opens a
fence when no further backtick appears on the line. Tilde fences are
unrestricted and unchanged. It is the only instance in the corpus.

docs-build now clears dist first. Astro leaves orphaned output when a
page's slug changes, and the link check reads whatever is in dist/, so a
stale page would otherwise report failures that no longer exist in the source.