What the bugs are. The classifier comment above _LINK promises totality ("no link can dodge validation by its spelling"), and unmodeled CommonMark forms are deliberately rejected loudly (_ANGLE_LINK, _REF_DEFINITION). Three residual shapes — all verified empirically against the compiled patterns at HEAD and against python-markdown 3.10.2, the renderer Zensical uses — break that contract in three different ways: a silent dodge, a loud mis-parse, and a silent phantom fence.

1. Whitespace-padded and empty destinations (silent dodge). _LINK requires the target to start immediately after ]( and the closing ) to follow the target/title with no intervening whitespace, and needs at least one target character. CommonMark and python-markdown accept padding and emptiness: [t](servers/tools.md ), [t]( servers/tools.md), [t](servers/tools.md\t), [t](target 'Title' ), [i](img/missing.png ), and [t]() all render as working <a>/<img> elements, yet _LINK.search() returns no match on every one, and neither loud-reject scan fires (_ANGLE_LINK needs the literal ](+< adjacency, so even [t]( `````<a b.md>`````) slips past it). Proof: _rewrite_links('See [diagram](img/missing.png ) here.', ...) returns the page byte-identical with no error, while the unpadded twin raises the designed _BuildError. Consequences: a padded broken asset target ships as a silent 404 through a fully green build (this script is the pipeline's sole guard for non-.md targets — Zensical only validates .md links, and check_crossrefs sees a resolved element with no bracket text), and even a valid padded .md link is never rewritten to an absolute URL, so the published .md rendition and llms-full.txt carry a source-relative link that 404s at the rendition's directory-URL depth while the HTML site looks fine.

2. Balanced-paren destinations (loud mis-parse with a misleading message). CommonMark allows balanced parentheses in a bare destination, and markdown.markdown('[x](foo(1).md)') renders <a href=\"foo(1).md\">. But _LINK's target class [^)\s]+? cannot consume ), so _LINK.search('[x](foo(1).md)').group(2) == 'foo(1' (reproduced) — the (\)) group grabs the inner paren. The truncated 'foo(1' is not an anchor, not scheme-prefixed, not absolute, and (DOCS / 'foo(1') exists as neither dir nor file, so the build aborts with cannot resolve link target 'foo(1' — a missing-file error naming a path that appears nowhere in the author's page. Neither loud-reject scan fires, so the failure bypasses the designed "not supported here; use X" contract. Worse, an existing parenthesized file (diagram(v2).png, a common Windows "copy (1)" export artifact) is unlinkable entirely, since the existence check runs on the truncated path — while Zensical renders the link fine.

3. _FENCE misreads a line-initial multi-backtick code span as a fence opener (silent under-validation). CommonMark — honored by python-markdown and pymdownx.superfences at the locked versions — rejects a backtick fence opener whose info string contains a backtick, so a line like \`\`\`pip install mcp\`\`\` is an inline code span in a paragraph. But _FENCE (^[ \t]*(\{3,}|~{3,})) ignores the rest of the line and treats it as an opener. Reproduced: for 'Intro.\n\n```pip install mcp```\n\nSee Tools and X.', _code_intervalsreturns one phantom interval from the span line to EOF, and_rewrite_linksreturns the page byte-identical — the broken link is never existence-checked (for asset targets this script is the sole guard, so it ships as a silent 404) and the valid link is never rewritten (source-relative 404 in the renditions). With a real fence later in the page, the phantom interval closes at that fence's all-backtick *closer*, exempting the intermediate prose and inverting code/prose parity afterward; the same mechanism defeats_prose_h1`. This directly falsifies the "a stray unpaired backtick cannot swallow the paragraphs (and links) after it" guarantee comment — here a paired triple-backtick span swallows everything. Note the tilde branch is correct: CommonMark permits backticks in a tilde fence's info string, so only the backtick branch diverges.

Why the existing fixes don't cover these. Commit 8acb8dd closed the previously reported classifier holes (extension caps, extensionless targets, single-quoted/paren titles, angle destinations, reference definitions), but every one of those keyed on the target's spelling — none touched the surrounding whitespace grammar, the paren-in-target case, or the fence-opener info-string rule. The documented "known approximations" name only 4-space-indented content and blank-line-bounded span pairing, and the posted _code_intervals review comments cover indented blocks, cross-block span pairing, and HTML comments — different mechanisms with non-overlapping fixes.

Fixes. (1) Allow optional [ \t]* around the destination and after the title in _LINK (re-emitting without the padding), plus either matching empty destinations and failing loud or a third rejected-forms scan for \]\([ \t]*\); (2) extend the target grammar with one level of balanced parens, e.g. (?:[^()\s]|\([^()\s]*\))+?, or loud-reject ( in targets so the failure at least routes through the instructive rejection message; (3) make the backtick fence-opener branch reject backticks in the info string: _FENCE = re.compile(r'^[ \t]*(\{3,}(?[^\n]*`)|~{3,})')` — a one-clause change; the closer logic needs none (closers are all-backtick lines and still match).

Severity. Nit: grep confirms nothing under docs/ trips any of the three today (consistent with the byte-identical-renditions verification), so nothing breaks at merge. The cost lands on future contributors — as a silent broken link/rendition divergence for (1) and (3), and as a loud but misdiagnosed CI abort for (2) — the same latent-classifier-hole family as the findings already confirmed and fixed on this PR.

What's stale. Lines 5–8 of scripts/docs/build.sh describe the recipe as "three steps: materialise the API reference pages and the concrete config, build the site strictly, then generate llms.txt and the per-page markdown renditions" — but the script body now executes four pipeline steps: build_config.py (line 31), zensical build -f mkdocs.gen.yml --strict (line 32), check_crossrefs.py --site-dir site (line 38), and llms_txt.py --site-dir site (line 40).

How it happened. Commit a483385 replaced the old grep -F '[<code>' guard with the standalone check_crossrefs.py checker and inserted it between the strict build and the llms.txt step. That same commit did update the parallel comment in .github/workflows/shared.yml — which now correctly names "the post-build steps [that] fail on unresolved cross-references, inventory download failures, and broken non-markdown link targets" — but the enumeration in this header was never touched, leaving it as the only stale description of the recipe.

Why the omitted step can't be read as part of "build the site strictly". The crossref check exists precisely because zensical build --strict does not cover those failure classes: the inline comment at lines 34–37 of this same file says so explicitly ("Zensical stays green even under --strict when a cross-reference fails to resolve ... or an objects.inv inventory fails to download ... Validate the built site instead"). Per the PR's own guarantees inventory, check_crossrefs.py is the sole owner of two failure classes — unresolved [text][identifier] cross-references rendering as literal bracket text, and failed inventory downloads silently degrading every inventory-driven link — so it is a distinct, load-bearing step, not a detail of the build step.

Why it matters (mildly). The header explicitly claims this script is "the single owner of that recipe", so it is the natural place a maintainer reads to understand or replicate the pipeline (e.g. in another workflow, or when deciding whether a step is "extra"). An enumeration that says the pipeline ends at llms.txt invites exactly the misreading that got the shared.yml comment fixed earlier on this PR — same comment-drift class as that already-confirmed misattribution finding.

Step-by-step proof.

1. Read the header: it promises exactly three steps — config/API materialisation, strict build, llms.txt.
2. Read the body after uv sync: build_config.py → zensical build --strict → check_crossrefs.py → llms_txt.py. Four distinct uv run invocations, four steps.
3. The third step is not subsumable into the second: lines 34–37 document that --strict ships both of its failure classes green, which is the whole reason the step exists.
4. git show a483385 -- .github/workflows/shared.yml shows the sibling comment being updated to name the post-build checks in the same commit that added the step here — confirming drift rather than a deliberate summary.

Why nit. Comment-only, zero runtime effect, and the omitted step carries its own accurate four-line explanatory comment 25 lines below in the same 40-line file — a reader of the script itself can't actually miss it; only someone relying on the header enumeration alone is misled.

How to fix. One-line reword, e.g.: "the build is four steps: materialise the API reference pages and the concrete config, build the site strictly, validate the built site's cross-references and inventories, then generate llms.txt and the per-page markdown renditions" — or drop the count entirely.

What the gap is. This PR replaces MkDocs plugin/hook machinery with four standalone scripts totalling ~830 lines: scripts/docs/llms_txt.py (~347), gen_ref_pages.py (~232), check_crossrefs.py (~164), and build_config.py (~85). They contain dense hand-rolled parsers — a markdown link classifier with code-fence/code-span interval tracking (_LINK, _FENCE, _CODE_SPAN, _code_intervals), a YAML frontmatter splitter (_split_frontmatter), a snippet resolver, an HTMLParser subclass with skip-depth/block-boundary state (_ProseTextExtractor), and a griffe alias-resolution walker (_compact_index). None of this has a single unit test: tests/ contains no directory for scripts (only cli, client, docs_src, examples, interaction, issues, server, shared, transports, types), pyproject.toml's [tool.pyright] include lists src/mcp, src/mcp-types/mcp_types, tests, docs_src and examples/* but not scripts/, and [tool.coverage.run] source omits it too. So the code that now owns the pipeline's advertised guarantees — nav validation, link validation, crossref detection, llms.txt fidelity — is invisible to type checking, to the 100%-coverage gate, and to the test suite, exercised only end-to-end by the docs CI job, which by construction covers only the happy path of the current corpus.\n\nWhy this matters empirically — the proof is this PR's own review history. Across the review rounds on this PR, roughly 20 latent edge-case bugs were confirmed and fixed in exactly this parsing logic: the _ASSET_LINK extension-length cap, the mailto:/scheme-only external-link misclassification, missing frontmatter stripping, cross-block code-span pairing, angle-bracket destinations, the subscript carve-out lookbehind in check_crossrefs.py, docs/ containment escapes in both the link classifier and the nav validator, extensionless/directory-style targets, external nav URLs ending in .md, the H1-fallback scanning into code fences, and more — plus the three residual shapes reported in the latest round. Each fix grew the regexes/state machines further, and each was verified manually (byte-identical output diffs, planted failures) rather than pinned by a regression test. Step by step, that means: (1) a future contributor refactors _code_intervals or _LINK — say, to add the angle-bracket destination support suggested in review; (2) they run ./scripts/test and the full CI matrix — all green, because nothing in tests/ touches these modules; (3) the docs job also passes, because the current corpus under docs/ happens not to contain a mailto: link, a frontmattered page, or a stray backtick; (4) the reintroduced edge case ships silently, exactly as it did the first time, until a review or a contributor trips it. Nothing in the repo prevents step (4) — the ~20 findings above each took an adversarial review pass to surface, and that pass won't re-run on the next refactor.\n\nWhy the "scripts/ is conventionally untested" refutation doesn't hold here. It's true the exclusion predates this PR (update_readme_snippets.py and gen_surface_types.py are also untested), and the deleted docs/hooks/*.py had no tests either. But the old hooks delegated the actual validation to MkDocs strict mode — upstream, tested code — whereas these scripts are the validation layer now: the PR description's own guarantees inventory assigns missing-nav-target, unresolved-crossref, and asset-link detection to them as sole owners. The exclusion was calibrated for trivial helpers; this PR relocates the pipeline's correctness enforcement itself into scripts/, which is the surface-area-increase case the convention never contemplated. Repo precedent also cuts the other way: tests/docs_src/test_shape.py deliberately duplicates a docs-build guarantee inside the ordinary pytest run, CI enforces fail_under = 100 with branch = true, and the repo ships a dedicated test-quality skill — the strongest test culture signal a repo can send.\n\nWhy it's cheap to fix. The flagged functions are pure, string-in/value-out, with no I/O beyond an optional docs/ fixture: _code_intervals(str) -> list[tuple[int,int]], _split_frontmatter(str) -> (dict, str), _dest_md_uri(str) -> str, unresolved_refs(html) -> list[str], _rewrite_links(...) (raises _BuildError on the documented rejection shapes), _nav_pages/_validate_nav. Every confirmed-and-fixed finding in this PR's review threads comes with a ready-made test case — the empirical proofs in those comments are literally executable assertions (unresolved_refs('<p>the <strong>tools</strong>[<code>0</code>] entry</p>') == [...], _LINK.search("[x](<servers/tools.md>)")", the frontmatter/H1 interactions, the containment escapes). A tests/scripts_docs/` (or similar) suite pinning those cases is mostly transcription, and would also let the modules be added to pyright's include list.\n\nImpact and severity. Nothing breaks at merge: CI is green, the scripts work on the current corpus, and this is CI-only tooling, not shipped SDK code — hence a nit, not a blocker. The cost is forward-looking: the substantial verification effort accumulated across this PR's review rounds (each fix confirmed with planted failures and byte-identical diffs) currently lives only in resolved review threads, and the next refactor of any of these state machines can silently undo any of it. Converting that work into a regression suite — even just the ~20 confirmed cases — is the cheapest possible insurance on the pipeline's guarantees, and matches the bar the rest of the repo already holds itself to.