docs: trim generated prose

scripts/verify-md-links.ts

@@ -1,35 +1,7 @@
 /**
- * Doc-sync gate: verify that every relative Markdown cross-link resolves to a
- * file that exists. Docs in this repo link to each other by relative path
- * (`[topic](../implemented/2026-…-….md)`, `[the cookbook](adding-a-tool.md)`);
- * a rename or a move silently breaks those links, and nothing caught it before
- * review. The RFC tree reorganization (one `docs/rfc/` with proposed/
- * implemented/ rejected/ subfolders, every file renamed to a dated slug) is the
- * motivating case: ~40 inter-doc links were rewritten by hand, and a single
- * fat-fingered path would have shipped a dead link.
- *
- * Detection is AST-based, mirroring verify-md-wrap: parse each file with
- * mdast-util-from-markdown + GFM, then walk every `link`, `image`, and
- * `definition` node. A target is checked when it is a RELATIVE path; these are
- * skipped because they are not ours to verify:
- *   - absolute URLs with a scheme (`https:`, `http:`, `mailto:`, …),
- *   - protocol-relative URLs (`//host/path`),
- *   - root-absolute paths (`/foo` — no stable base in a repo checkout),
- *   - pure in-page anchors (`#section`).
- * For a relative target the `#fragment` and `?query` are stripped, the path is
- * resolved against the linking file's directory, and the result must exist on
- * disk. This is checker, not fixer: it reports and never rewrites.
- *
- * Scope is the other doc-sync gates' set plus example Markdown, AGENTS.md
- * files in those checked trees, AND the repo-authored agent-skill Markdown under
- * `.agents/skills/` — those skill files cross-link into the docs tree (e.g. the
- * dsh-code-review skill cites the RFC index), so a rename must not silently
- * break them either: README.md, docs/** /*.md, packages/* /README.md,
- * examples/** /*.md, AGENTS.md, packages/AGENTS.md, .agents/skills/** /*.md.
- * The root, packages/, and examples/ CLAUDE.md files are symlinks to the
- * AGENTS.md files, so they are deduped by real path.
- *
- * Run: `tsx scripts/verify-md-links.ts`.
+ * Verify that relative Markdown links, images, and definitions resolve. URL,
+ * root-absolute, and in-page targets are excluded; query strings and fragments
+ * do not affect the filesystem check. Symlinked instruction files are deduped.
  */
 
 import { existsSync, globSync, readFileSync, realpathSync } from 'node:fs'
@@ -41,10 +13,7 @@ import type { Nodes } from 'mdast'
 
 const root = resolve(import.meta.dirname, '..')
 
-/**
- * Files to check: doc-typecheck's scope, example Markdown, the AGENTS.md pair,
- * and repo-authored agent-skill Markdown.
- */
+/** Repo-authored Markdown checked for relative links. */
 const PATTERNS = [
   'README.md',
   'README.zh.md',