@zvndev/darkmown 2.10.0 → 2.11.0

package/src/compiler/state.js

@@ -174,6 +174,79 @@ function rejectStateSeed(value, raw, directive, ctx, index) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// A SECRET-SHAPED SEED IS A HINT, NEVER AN ERROR.
+//
+// Every `:state`/`:store` seed is stored verbatim and inlined into the public
+// HTML as a JSON script tag — that is the design, and it means a seed that is
+// really an API key or token is published to every reader of the page. The
+// documented pattern is to seed empty and fill from an api/ endpoint at
+// runtime, but nothing stopped an author from pasting the key itself. This
+// check is a heuristic over string seeds (and string values nested in
+// array/object seeds), pushed onto the same `comp.warnings` channel as the
+// other build hints: it can never fail a build, because a false positive must
+// never break one, and it fires at most once per declaration.
+//
+// The shapes are deliberately tight — false positives are the enemy:
+//
+// - Known key prefixes (`sk-`, `ghp_`, `xoxb-`, `AKIA`, …) followed by a real
+//   token body, and the `-----BEGIN` private-key header.
+// - A JWT: three base64url segments joined by dots, opening with `eyJ` (the
+//   base64 of `{"` — requiring it keeps dotted prose quiet).
+// - A long unbroken token: 32+ chars from the base64/base64url alphabet with
+//   no spaces, requiring BOTH cases and a digit. Requiring the case mix keeps
+//   kebab-case slugs, hex hashes, and UUIDs (all lowercase) silent, and the
+//   charset excludes `:`, `.`, and space, so URLs, file paths, and prose
+//   never match.
+// ---------------------------------------------------------------------------
+const SECRET_PREFIX = /^(?:sk-|sk_live_|sk_test_|ghp_|gho_|xoxb-|xoxp-|AKIA)/;
+const SECRET_TOKEN_BODY = /^[A-Za-z0-9_-]{8,}$/;
+const JWT_SHAPE = /^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}$/;
+const LONG_TOKEN_SHAPE = /^[A-Za-z0-9/_+=-]{32,}$/;
+
+/**
+ * Test one string for the secret shapes above.
+ * @param {string} text
+ * @returns {boolean}
+ */
+function looksLikeSecret(text) {
+  if (text.startsWith("-----BEGIN")) return true;
+  const prefixed = text.match(SECRET_PREFIX);
+  if (prefixed && SECRET_TOKEN_BODY.test(text.slice(prefixed[0].length))) return true;
+  if (JWT_SHAPE.test(text)) return true;
+  return LONG_TOKEN_SHAPE.test(text) && /[a-z]/.test(text) && /[A-Z]/.test(text) && /\d/.test(text);
+}
+
+/**
+ * Walk a parsed seed for a secret-shaped string: the seed itself, or any
+ * string value nested in its arrays/objects.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function seedContainsSecret(value) {
+  if (typeof value === "string") return looksLikeSecret(value);
+  if (Array.isArray(value)) return value.some(seedContainsSecret);
+  if (value && typeof value === "object") return Object.values(value).some(seedContainsSecret);
+  return false;
+}
+
+/**
+ * Push the secret-seed hint when a `:state`/`:store` seed carries one.
+ * @param {unknown} value The parsed seed.
+ * @param {string} name The declared name, for the message.
+ * @param {string} directive `:state` or `:store`, for the message.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line`.
+ * @returns {void}
+ */
+function warnSecretSeed(value, name, directive, ctx, index) {
+  if (!seedContainsSecret(value)) return;
+  ctx.comp.warnings.push(
+    `${at(ctx, index)}: ${directive} "${name}" seed looks like a secret — it will be inlined into public HTML. ` +
+      `Seed empty and fill it from an api/ endpoint at runtime.`
+  );
+}
+
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -195,6 +268,7 @@ export function handleState(line, ctx, index) {
   const flags = parseModifiers(match[3], ":state", ctx, index);
   const value = parseStateValue(match[2], at(ctx, index));
   rejectStateSeed(value, match[2], ":state", ctx, index);
+  warnSecretSeed(value, match[1], ":state", ctx, index);
   const key = declareState(match[1], value, ctx);
   recordSymbol(ctx, index, { kind: "state", name: key, detail: `${key} = ${match[2].trim()}` });
   const persistAttr = flags.persist ? ` data-wd-persist="${escapeHtml(key)}"` : "";
@@ -263,6 +337,7 @@ export function handleStore(line, ctx, index) {
   const flags = parseModifiers(match[3], ":store", ctx, index);
   const value = parseStateValue(match[2], at(ctx, index));
   rejectStateSeed(value, match[2], ":store", ctx, index);
+  warnSecretSeed(value, match[1], ":store", ctx, index);
   const name = declareStore(match[1], value, ctx);
   recordSymbol(ctx, index, { kind: "store", name, detail: `${name} = ${match[2].trim()}` });
   const ephemeral = flags.ephemeral ? " data-wd-store-ephemeral" : "";

package/src/compiler.js

@@ -43,7 +43,7 @@ export {
  * a different source (see `compileFromMemory`).
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {import("./config.js").Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string }, site?: import("./compiler/page.js").SiteContext, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader, imageVariants?: Map<string, number[]> | null }} [options]
+ * @param {{ feed?: { href: string, title: string }, mdSource?: { href: string }, site?: import("./compiler/page.js").SiteContext, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader, imageVariants?: Map<string, number[]> | null }} [options]
  * @returns {CompiledPage}
  */
 export function compilePage(file, context, options = {}) {

package/src/errors.js

@@ -76,6 +76,7 @@ import {
   IF_EXAMPLE,
   INCLUDE_EXAMPLE
 } from "./compiler/structure.js";
+import { FONT_FACE_EXAMPLE, KEYFRAMES_EXAMPLE } from "./skin.js";
 
 /**
  * One subsystem block of the numbering scheme.
@@ -94,8 +95,9 @@ import {
  * @property {string} title Short name for the mistake.
  * @property {string} cause What the author wrote that triggers it.
  * @property {string} fix The corrective action, in one line.
- * @property {string} [example] A concrete, compilable line, sourced from the
- *   compiler's own `*_EXAMPLE` constants.
+ * @property {string} [example] A concrete, compilable line (or, for block
+ *   constructs like the `.skin` at-rules, a minimal compilable block), sourced
+ *   from the compiler's own `*_EXAMPLE` constants.
  */
 
 /** The subsystem blocks, in code order. */
@@ -1167,6 +1169,36 @@ const ENTRIES = [
     cause: "A top-level `page`/`body`/`html`/`*`/`::selection` selector escapes the scope.",
     fix: "Move page-level styles to a global (non-scoped) skin."
   },
+  {
+    code: "WD804",
+    title: "Malformed `@font-face` block",
+    cause:
+      "`@font-face` was given a name, holds a nested block, or has no descriptors — it takes plain `prop value` declaration lines only.",
+    fix: "Write a bare `@font-face` line and indent each descriptor beneath it.",
+    example: FONT_FACE_EXAMPLE
+  },
+  {
+    code: "WD805",
+    title: "Invalid `@keyframes` name",
+    cause: "The name after `@keyframes` is missing or is not a plain CSS identifier.",
+    fix: "Name the animation with a plain identifier, e.g. `@keyframes fade-in`.",
+    example: KEYFRAMES_EXAMPLE
+  },
+  {
+    code: "WD806",
+    title: "Invalid keyframe selector",
+    cause: "A child of `@keyframes` is not `from`, `to`, or a percentage.",
+    fix: "Use `from`, `to`, a percentage (`50%`), or a comma list of them (`50%, 75%`).",
+    example: KEYFRAMES_EXAMPLE
+  },
+  {
+    code: "WD807",
+    title: "Malformed `@keyframes` body",
+    cause:
+      "A keyframe's declarations nest deeper, a keyframe selector has no declarations, or the block has no keyframe selectors at all.",
+    fix: "Give each keyframe selector a flat list of declarations indented one level beneath it.",
+    example: KEYFRAMES_EXAMPLE
+  },
 
   // --- WD9xx: project, routing, CLI ----------------------------------------
   {
@@ -1211,6 +1243,13 @@ const ENTRIES = [
     cause: "The home page's `ai_crawlers:` is neither `allow` nor `deny`.",
     fix: "Write `ai_crawlers: allow` or `ai_crawlers: deny` (absent means allow)."
   },
+  {
+    code: "WD908",
+    title: "Unsafe route name",
+    cause:
+      "A page filename produced a route containing whitespace or control characters, which would corrupt generated config files (dist/_headers, llms.txt).",
+    fix: "Rename the file using only letters, digits, dashes, and underscores."
+  },
   {
     code: "WD950",
     title: "Invalid `rss_limit`",
@@ -1296,7 +1335,15 @@ export function errorsMarkdown() {
     out.push("| Code | Error | Cause | Fix | Example |");
     out.push("| --- | --- | --- | --- | --- |");
     for (const row of rows) {
-      const example = row.example ? `\`${escapeCell(row.example)}\`` : "";
+      // A multi-line example (the `.skin` at-rule blocks are block constructs)
+      // becomes one code span per line joined by <br>, keeping the table row
+      // on a single markdown line.
+      const example = row.example
+        ? row.example
+            .split("\n")
+            .map((line) => `\`${escapeCell(line)}\``)
+            .join("<br>")
+        : "";
       out.push(
         `| \`${row.code}\` | ${escapeCell(row.title)} | ${escapeCell(row.cause)} | ${escapeCell(row.fix)} | ${example} |`
       );

package/src/font-subset.js

@@ -36,6 +36,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { fsReader } from "./compiler/fs-reader.js";
+import { isAllowedInclude } from "./compiler/includes.js";
 
 /**
  * @typedef {import("./config.js").Paths} Paths
@@ -287,21 +289,26 @@ export function subsetFonts(paths, options = {}) {
  * build is synchronous; the wasm API is not), communicating through temp JSON
  * files rather than stdio so a large payload never hits a pipe buffer. The
  * worker always writes a results file — a missing or unparsable one means the
- * child itself died, which is reported as `unavailable` (the build then behaves
- * as if the toolchain were absent: a hint, no subsets, no failure).
+ * child itself died (crashed, or killed by the spawn timeout), which is
+ * reported as `unavailable` (the build then behaves as if the toolchain were
+ * absent: a hint, no subsets, no failure).
  * @param {{ charset: number[], jobs: SubsetJob[] }} payload
  * @param {(cmd: string, args: string[], opts: object) => unknown} [spawn]
  *   Injectable for tests; the real one is `spawnSync`.
+ * @param {number} [timeoutMs] The worker is killed after this long (default
+ *   two minutes), so a hung toolchain call cannot stall a build forever. The
+ *   kill lands in the same `unavailable` path as any other dead child.
  * @returns {SubsetResult}
  */
-export function runSubsetJobs(payload, spawn = /** @type {any} */ (spawnSync)) {
+export function runSubsetJobs(payload, spawn = /** @type {any} */ (spawnSync), timeoutMs = 120000) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "wd-font-subset-"));
   try {
     const jobsFile = path.join(dir, "jobs.json");
     const resultsFile = path.join(dir, "results.json");
     fs.writeFileSync(jobsFile, JSON.stringify(payload));
     spawn(process.execPath, [WORKER_PATH, jobsFile, resultsFile], {
-      stdio: ["ignore", "ignore", "inherit"]
+      stdio: ["ignore", "ignore", "inherit"],
+      timeout: timeoutMs
     });
     if (!fs.existsSync(resultsFile)) return { unavailable: true, failed: [] };
     try {
@@ -391,9 +398,10 @@ function fontUrlsInCss(css) {
  * Resolve a url() target from an emitted `@font-face` to the project font file
  * it names, or null when it is not a subset candidate: anything not
  * leading-slash (remote, protocol-relative, `data:`, relative), a non-subsettable
- * extension (already-woff2 included), an un-decodable or escaping path, or a
- * file that does not exist. `/__wd/media/<rel>` maps to the shelf; every other
- * absolute path maps to `site/pages`.
+ * extension (already-woff2 included), an un-decodable or escaping path, a
+ * symlink (whose target could live anywhere on disk, whatever the link's own
+ * path says), or a file that does not exist. `/__wd/media/<rel>` maps to the
+ * shelf; every other absolute path maps to `site/pages`.
  * @param {Paths} paths
  * @param {string} url The raw url() target.
  * @returns {FontRef | null}
@@ -416,6 +424,16 @@ function resolveFontUrl(paths, url) {
   const source = path.normalize(path.join(base, rel));
   if (!source.startsWith(base + path.sep)) return null;
   if (!fs.existsSync(source)) return null;
+  // Symlinks are never subsetted, matching the asset-copy convention
+  // (`emitPageAssets` skips them entirely, and so does the image pre-pass):
+  // the lexical containment check above reads the path as WRITTEN, so a link
+  // sitting inside the project could point anywhere on disk and the target's
+  // bytes would be read and published as a subset. An ancestor directory can
+  // be a symlink with the file itself plain, so the canonical (realpath)
+  // containment check `@include` uses runs too — a font whose real path
+  // escapes site/pages and site/_ is simply "not project-local" here.
+  if (fs.lstatSync(source).isSymbolicLink()) return null;
+  if (!isAllowedInclude(source, paths, fsReader())) return null;
   const subsetUrl = `${clean.slice(0, clean.length - ext.length)}-subset.woff2`;
   return { url, source, subsetUrl, subsetDist: path.join(paths.distRoot, subsetUrl.slice(1)) };
 }

package/src/image-variant-resize.js

@@ -46,7 +46,10 @@ export async function runJobsFile(jobsFile, resultsFile) {
       // loses the EXIF tag with its pixels physically rotated, so it displays
       // exactly like the tag-carrying original. `withoutEnlargement` is belt and
       // braces — the pre-pass only ever queues widths below the intrinsic size.
-      let pipeline = sharp(job.source)
+      // `limitInputPixels` caps the decompression-bomb surface: 100 MP is above
+      // any real photo, and an oversized input fails as a per-job error (a hint
+      // naming the file), never a build failure.
+      let pipeline = sharp(job.source, { limitInputPixels: 1e8 })
         .rotate()
         .resize({ width: job.width, withoutEnlargement: true });
       if (job.format === "webp") pipeline = pipeline.webp({ quality: 82 });

package/src/image-variants.js

@@ -228,21 +228,26 @@ export function generateImageVariants(paths, options = {}) {
  * build is synchronous; sharp is not), communicating through temp JSON files
  * rather than stdio so a large job list never hits a pipe buffer. The worker
  * always writes a results file — a missing or unparsable one means the child
- * itself died, which is reported as `unavailable` (the build then behaves as
- * if sharp were absent: a hint, no variants, no failure).
+ * itself died (crashed, or killed by the spawn timeout), which is reported as
+ * `unavailable` (the build then behaves as if sharp were absent: a hint, no
+ * variants, no failure).
  * @param {ResizeJob[]} jobs
  * @param {(cmd: string, args: string[], opts: object) => unknown} [spawn]
  *   Injectable for tests; the real one is `spawnSync`.
+ * @param {number} [timeoutMs] The worker is killed after this long (default
+ *   two minutes), so a hung sharp call cannot stall a build forever. The kill
+ *   lands in the same `unavailable` path as any other dead child.
  * @returns {ResizeResult}
  */
-export function runResizeJobs(jobs, spawn = /** @type {any} */ (spawnSync)) {
+export function runResizeJobs(jobs, spawn = /** @type {any} */ (spawnSync), timeoutMs = 120000) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "wd-img-variants-"));
   try {
     const jobsFile = path.join(dir, "jobs.json");
     const resultsFile = path.join(dir, "results.json");
     fs.writeFileSync(jobsFile, JSON.stringify(jobs));
     spawn(process.execPath, [WORKER_PATH, jobsFile, resultsFile], {
-      stdio: ["ignore", "ignore", "inherit"]
+      stdio: ["ignore", "ignore", "inherit"],
+      timeout: timeoutMs
     });
     if (!fs.existsSync(resultsFile)) return { unavailable: true, failed: [] };
     try {

package/src/mcp-tools.js

@@ -0,0 +1,354 @@
+// ---------------------------------------------------------------------------
+// The Darkmown MCP server's tools and resources.
+//
+// Nothing here re-implements the framework: every tool is a thin adapter over
+// a surface that already exists and is already drift-guarded by the test
+// suite — the directive catalog (src/catalog.js), the agent grammar slice
+// (src/tools/grammar.js), the GBNF generator (src/grammar.js), the in-memory
+// validator (src/tools/validate.js), and the error-code registry
+// (src/errors.js). An MCP client and the `darkmown` CLI therefore can never
+// disagree about what compiles or what a WD code means.
+//
+// The five tools:
+//
+//   catalog   the machine-readable directive catalog (JSON, llms, llms-full)
+//   grammar   the GBNF grammar, or a category slice of the directive cheatsheet
+//   validate  compile .wd source in memory, answering with WD codes and fixes
+//   error     one WDxxx code's cause, fix, and example (or the valid list)
+//   doc       fuzzy-find a section of README.md / AGENTS.md by topic
+//
+// The resources expose the shipped markdown docs at darkmown://docs/* URIs,
+// read from the installed package files at request time.
+// ---------------------------------------------------------------------------
+
+import fs from "node:fs";
+import { directiveCatalog, llmsFullText, llmsText } from "./catalog.js";
+import { errorCatalog, errorForCode } from "./errors.js";
+import { generateGrammar } from "./grammar.js";
+import { grammar } from "./tools/grammar.js";
+import { validate } from "./tools/validate.js";
+
+/** The installed Darkmown version, read from the shipped package.json. */
+function packageVersion() {
+  const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  return String(pkg.version || "0.0.0");
+}
+
+/** Read a file shipped in the package root (or under it), as UTF-8. */
+function readPackageFile(/** @type {string} */ file) {
+  return fs.readFileSync(new URL(`../${file}`, import.meta.url), "utf8");
+}
+
+// --- catalog ---------------------------------------------------------------
+
+/** @type {string[]} The render modes, mirroring the CLI's catalog flags. */
+const CATALOG_MODES = ["json", "llms", "llms-full"];
+
+/** @type {import("./mcp.js").McpTool} */
+const catalogTool = {
+  name: "catalog",
+  description:
+    "The Darkmown .wd directive catalog: every directive, @loop clause, action op, " +
+    'format pipe, predicate operator, frontmatter key, and WDxxx error code. mode "json" ' +
+    '(default) is the full machine-readable catalog, "llms" the compact cheatsheet, ' +
+    '"llms-full" the complete reference.',
+  inputSchema: {
+    type: "object",
+    properties: {
+      mode: {
+        type: "string",
+        enum: CATALOG_MODES,
+        description: 'Render mode: "json" (default), "llms", or "llms-full".'
+      }
+    }
+  },
+  run(args) {
+    const mode = args.mode ?? "json";
+    if (typeof mode !== "string" || !CATALOG_MODES.includes(mode)) {
+      return {
+        text: `unknown catalog mode ${JSON.stringify(mode)}. Valid modes: ${CATALOG_MODES.join(", ")}`,
+        isError: true
+      };
+    }
+    if (mode === "llms") return { text: llmsText() };
+    if (mode === "llms-full") return { text: llmsFullText() };
+    return { text: JSON.stringify(directiveCatalog(), null, 2) };
+  }
+};
+
+// --- grammar ---------------------------------------------------------------
+
+/** @type {import("./mcp.js").McpTool} */
+const grammarTool = {
+  name: "grammar",
+  description:
+    "The .wd directive syntax. Pass gbnf:true for the full GBNF directive-line grammar " +
+    '(for constrained decoding), or categories like ["state", "actions"] for just the ' +
+    "cheatsheet rows covering those directives. Categories: state, loops, actions, " +
+    "forms, fetch, structure, media. No arguments returns every category.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      gbnf: {
+        type: "boolean",
+        description: "Return the full GBNF grammar instead of a cheatsheet slice."
+      },
+      categories: {
+        type: "array",
+        items: { type: "string" },
+        description:
+          "Directive categories to include: state, loops, actions, forms, fetch, structure, media."
+      }
+    }
+  },
+  run(args) {
+    if (args.gbnf === true) return { text: generateGrammar() };
+    const categories = Array.isArray(args.categories)
+      ? args.categories.filter((c) => typeof c === "string")
+      : undefined;
+    const result = grammar(categories);
+    return { text: result.text, data: result.data, ...(result.ok ? {} : { isError: true }) };
+  }
+};
+
+// --- validate ---------------------------------------------------------------
+
+/** @type {import("./mcp.js").McpTool} */
+const validateTool = {
+  name: "validate",
+  description:
+    "Compile .wd (or .md) source with the real Darkmown compiler, in memory. On success " +
+    "answers whether the page is static or reactive and lists any warnings; on failure " +
+    "answers with the stable WD error code, the file:line, a Use: hint, and a concrete " +
+    "example. Prove a page compiles before writing it.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      source: { type: "string", description: "The full .wd/.md page source." },
+      filename: {
+        type: "string",
+        description: 'Name the source is compiled under (default "index.wd").'
+      }
+    },
+    required: ["source"]
+  },
+  run(args) {
+    if (typeof args.source !== "string") {
+      return { text: 'validate needs a "source" string.', isError: true };
+    }
+    const filename =
+      typeof args.filename === "string" && args.filename.trim()
+        ? args.filename.replace(/^\/+/, "")
+        : "index.wd";
+    const key = filename.startsWith("site/") ? filename : `site/pages/${filename}`;
+    const result = validate({ [key]: args.source }, key);
+    return { text: result.text, data: { ok: result.ok, ...result.data } };
+  }
+};
+
+// --- error -----------------------------------------------------------------
+
+/** @type {import("./mcp.js").McpTool} */
+const errorTool = {
+  name: "error",
+  description:
+    "Look up one Darkmown compile-error code (e.g. WD201): its title, what causes it, " +
+    "how to fix it, and a concrete compilable example. An unknown code answers with " +
+    "the list of valid codes.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      code: { type: "string", description: 'The WDxxx code, e.g. "WD201".' }
+    },
+    required: ["code"]
+  },
+  run(args) {
+    const code = typeof args.code === "string" ? args.code.trim().toUpperCase() : "";
+    const entry = errorForCode(code);
+    if (!entry) {
+      const codes = errorCatalog().map((e) => e.code);
+      return {
+        text:
+          `unknown error code ${JSON.stringify(code || args.code)}. ` +
+          `Valid codes: ${codes.join(", ")}`,
+        data: { codes },
+        isError: true
+      };
+    }
+    const lines = [`${entry.code} ${entry.title}`, `cause: ${entry.cause}`, `fix: ${entry.fix}`];
+    if (entry.example) lines.push(`e.g. ${entry.example}`);
+    return { text: lines.join("\n"), data: entry };
+  }
+};
+
+// --- doc -------------------------------------------------------------------
+
+/** The shipped long-form docs the `doc` tool searches, in search order. */
+const DOC_FILES = ["README.md", "AGENTS.md"];
+
+/**
+ * One searchable section of a shipped doc.
+ * @typedef {object} DocSection
+ * @property {string} topic The heading text, e.g. "Includes & sections".
+ * @property {string} file The doc the section lives in.
+ * @property {string} body The section's markdown, heading excluded.
+ */
+
+/**
+ * Split a doc into sections on `#`/`##`/`###` headings, ignoring heading-shaped
+ * lines inside fenced code blocks (README's example robots.txt and sample pages
+ * carry lines that start with `#`).
+ * @returns {DocSection[]}
+ */
+export function docSections() {
+  /** @type {{ topic: string, file: string, lines: string[] }[]} */
+  const raw = [];
+  for (const file of DOC_FILES) {
+    let fenced = false;
+    /** @type {{ topic: string, file: string, lines: string[] } | null} */
+    let current = null;
+    for (const line of readPackageFile(file).split("\n")) {
+      if (/^(```|~~~)/.test(line.trimStart())) fenced = !fenced;
+      const heading = !fenced && /^#{1,3} (.+)$/.exec(line);
+      if (heading) {
+        current = { topic: heading[1].trim(), file, lines: [] };
+        raw.push(current);
+      } else if (current) {
+        current.lines.push(line);
+      }
+    }
+  }
+  return raw.map(({ topic, file, lines }) => ({ topic, file, body: lines.join("\n").trim() }));
+}
+
+/**
+ * Score a section heading against a query, higher is better. Exact match wins,
+ * then containment either way, then shared-word count. Normalisation folds
+ * case and strips punctuation, so "raw html" matches
+ * "⚠️ Raw HTML is escaped by default (since 2.0.0)".
+ * @param {string} topic
+ * @param {string} query
+ * @returns {number}
+ */
+function scoreSection(topic, query) {
+  const normalize = (/** @type {string} */ s) =>
+    s
+      .toLowerCase()
+      .replace(/[^a-z0-9 ]/g, " ")
+      .replace(/\s+/g, " ")
+      .trim();
+  const heading = normalize(topic);
+  const wanted = normalize(query);
+  if (!wanted) return 0;
+  if (heading === wanted) return 100;
+  if (heading.includes(wanted) || wanted.includes(heading)) return 60;
+  const words = new Set(heading.split(" "));
+  let overlap = 0;
+  for (const word of wanted.split(" ")) if (words.has(word)) overlap++;
+  return overlap;
+}
+
+/** @type {import("./mcp.js").McpTool} */
+const docTool = {
+  name: "doc",
+  description:
+    "Fuzzy-find a section of the shipped Darkmown docs (README.md and AGENTS.md) by " +
+    'topic, e.g. "includes", "forms", "dark mode", and return that section\'s markdown. ' +
+    "Call with no topic to list every available section.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      topic: { type: "string", description: "What to look up, in a word or two." }
+    }
+  },
+  run(args) {
+    const topic = typeof args.topic === "string" ? args.topic.trim() : "";
+    const sections = docSections();
+    const list = sections.map((s) => `- ${s.topic} (${s.file})`).join("\n");
+    if (!topic) {
+      return {
+        text: `Available doc sections:\n${list}`,
+        data: { topics: sections.map((s) => ({ topic: s.topic, file: s.file })) }
+      };
+    }
+    let best = /** @type {DocSection | null} */ (null);
+    let bestScore = 0;
+    for (const section of sections) {
+      const score = scoreSection(section.topic, topic);
+      if (score > bestScore) {
+        best = section;
+        bestScore = score;
+      }
+    }
+    if (!best) {
+      return {
+        text: `no doc section matches ${JSON.stringify(topic)}. Available sections:\n${list}`,
+        isError: true
+      };
+    }
+    return {
+      text: `# ${best.topic} (${best.file})\n\n${best.body}`,
+      data: { topic: best.topic, file: best.file }
+    };
+  }
+};
+
+// --- resources ---------------------------------------------------------------
+
+/**
+ * The shipped docs exposed as MCP resources, read from the installed package
+ * at request time so a long-running server sees the files the user actually
+ * has installed.
+ * @type {{ uri: string, name: string, file: string, description: string }[]}
+ */
+const DOC_RESOURCES = [
+  {
+    uri: "darkmown://docs/readme",
+    name: "README.md",
+    file: "README.md",
+    description: "The Darkmown README: authoring model, directive reference, commands."
+  },
+  {
+    uri: "darkmown://docs/agents",
+    name: "AGENTS.md",
+    file: "AGENTS.md",
+    description: "The agent authoring guide: the complete .wd directive set and the hard rules."
+  },
+  {
+    uri: "darkmown://docs/changelog",
+    name: "CHANGELOG.md",
+    file: "CHANGELOG.md",
+    description: "Darkmown release history."
+  },
+  {
+    uri: "darkmown://docs/errors",
+    name: "docs/errors.md",
+    file: "docs/errors.md",
+    description: "Every stable WDxxx compile-error code with cause, fix, and example."
+  },
+  {
+    uri: "darkmown://docs/cli",
+    name: "docs/cli.md",
+    file: "docs/cli.md",
+    description: "The Darkmown CLI command reference."
+  }
+];
+
+/**
+ * The server configuration: identity, the five tools, and the doc resources.
+ * Built fresh on each call so tests can mutate nothing shared.
+ * @returns {import("./mcp.js").McpConfig}
+ */
+export function mcpConfig() {
+  return {
+    serverInfo: { name: "darkmown", version: packageVersion() },
+    tools: [catalogTool, grammarTool, validateTool, errorTool, docTool],
+    resources: DOC_RESOURCES.map(({ uri, name, file, description }) => ({
+      uri,
+      name,
+      description,
+      mimeType: "text/markdown",
+      read: () => readPackageFile(file)
+    }))
+  };
+}