@zvndev/darkmown 2.10.0 → 2.11.0

package/src/api-runner.js

@@ -78,13 +78,17 @@ function dynamicCount(segments) {
 /**
  * Match a request pathname against discovered routes. The pathname is expected
  * to start with `/api`; anything else returns `null` (caller serves static).
+ * A dynamic segment whose percent-encoding is malformed (`%E0%A4%A`) makes
+ * `decodeURIComponent` throw — that is reported as `{ malformed: true }` so the
+ * caller answers a clean 400 instead of crashing the request handler.
  * @param {ApiRoute[]} routes
  * @param {string} pathname Request pathname (no query string).
- * @returns {{ file: string, params: Record<string, string> } | null}
+ * @returns {{ file: string, params: Record<string, string> } | { malformed: true } | null}
  */
 export function matchApiRoute(routes, pathname) {
   if (pathname !== "/api" && !pathname.startsWith("/api/")) return null;
   const parts = pathname.split("/").filter(Boolean).slice(1); // drop leading "api"
+  let sawMalformed = false;
   for (const route of routes) {
     if (route.segments.length !== parts.length) continue;
     /** @type {Record<string, string>} */
@@ -93,7 +97,15 @@ export function matchApiRoute(routes, pathname) {
     for (let i = 0; i < parts.length; i++) {
       const seg = route.segments[i];
       if (seg.startsWith("[") && seg.endsWith("]")) {
-        params[seg.slice(1, -1)] = decodeURIComponent(parts[i]);
+        try {
+          params[seg.slice(1, -1)] = decodeURIComponent(parts[i]);
+        } catch {
+          // Malformed here does not preclude a static match on a later route,
+          // so keep scanning and report only if nothing else claimed the path.
+          sawMalformed = true;
+          ok = false;
+          break;
+        }
       } else if (seg !== parts[i]) {
         ok = false;
         break;
@@ -101,13 +113,15 @@ export function matchApiRoute(routes, pathname) {
     }
     if (ok) return { file: route.file, params };
   }
-  return null;
+  return sawMalformed ? { malformed: true } : null;
 }
 
 /**
  * Build a Web-standard `Request` from a Node `IncomingMessage`. The body (for
- * methods that carry one) is buffered fully — dev endpoints are small and this
- * avoids the `duplex: "half"` streaming dance.
+ * methods that carry one) is buffered up to {@link MAX_BODY_BYTES} — dev and
+ * preview endpoints are small and this avoids the `duplex: "half"` streaming
+ * dance. A larger body rejects with {@link BodyTooLargeError}, which
+ * `handleApiRequest` answers as a 413.
  * @param {import("node:http").IncomingMessage} req
  * @returns {Promise<Request>}
  */
@@ -125,6 +139,15 @@ export async function nodeRequestToWeb(req) {
   return new Request(url, init);
 }
 
+/** Bodies larger than this are rejected with a 413 rather than buffered without bound. */
+const MAX_BODY_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Rejection marker for an over-cap request body, so `handleApiRequest` answers
+ * 413 (a client error) instead of a generic 500.
+ */
+class BodyTooLargeError extends Error {}
+
 /**
  * @param {import("node:http").IncomingMessage} req
  * @returns {Promise<Buffer>}
@@ -133,7 +156,22 @@ function readBody(req) {
   return new Promise((resolve, reject) => {
     /** @type {Buffer[]} */
     const chunks = [];
-    req.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+    let received = 0;
+    let over = false;
+    req.on("data", (chunk) => {
+      received += chunk.length;
+      if (received > MAX_BODY_BYTES) {
+        // Stop accumulating, but keep draining the socket: destroying the
+        // request here would kill the connection before the 413 answer can
+        // reach the client (verified: `req.destroy()` mid-upload → EPIPE).
+        if (!over) {
+          over = true;
+          reject(new BodyTooLargeError(`Request body too large (over ${MAX_BODY_BYTES} bytes)`));
+        }
+        return;
+      }
+      chunks.push(Buffer.from(chunk));
+    });
     req.on("end", () => resolve(Buffer.concat(chunks)));
     req.on("error", reject);
   });
@@ -189,18 +227,41 @@ export async function writeWebResponse(response, res, acceptEncoding) {
  * the handler succeeded or threw), `false` when nothing matched so the caller
  * should fall through to static serving.
  *
+ * Error disclosure: a handler throw is answered as JSON either way, but the
+ * `error` field carries the real message only when `discloseErrors` is set
+ * (the dev server's default — a documented dev convenience). The preview
+ * server passes `false` and the client gets the generic "Internal error",
+ * matching the shape the generated Cloudflare worker ships.
+ *
  * @param {object} io
  * @param {string} io.apiDir Absolute path to the project's `api/` directory.
  * @param {import("node:http").IncomingMessage} io.req
  * @param {import("node:http").ServerResponse} io.res
  * @param {string | string[] | undefined} [io.acceptEncoding] The request's
  *   Accept-Encoding header, when the caller negotiates compression (preview).
+ * @param {boolean} [io.discloseErrors] Echo the thrown message to the client
+ *   (default true, the dev behavior). Pass false on any production-shaped path.
  * @returns {Promise<boolean>}
  */
-export async function handleApiRequest({ apiDir, req, res, acceptEncoding }) {
+export async function handleApiRequest({
+  apiDir,
+  req,
+  res,
+  acceptEncoding,
+  discloseErrors = true
+}) {
   const pathname = new URL(req.url || "/", "http://localhost").pathname;
   const match = matchApiRoute(discoverApiRoutes(apiDir), pathname);
   if (!match) return false;
+  if ("malformed" in match) {
+    // A malformed percent-encoded dynamic segment: the URL itself is at fault,
+    // so this is a 400, not a 500 — and it must never reach the caller's catch.
+    await writeWebResponse(
+      Response.json({ ok: false, error: "Malformed URL encoding" }, { status: 400 }),
+      res
+    );
+    return true;
+  }
 
   try {
     const handler = await importHandler(match.file);
@@ -215,7 +276,18 @@ export async function handleApiRequest({ apiDir, req, res, acceptEncoding }) {
     }
     await writeWebResponse(response, res, acceptEncoding);
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof BodyTooLargeError) {
+      await writeWebResponse(
+        Response.json({ ok: false, error: "Request body too large" }, { status: 413 }),
+        res
+      );
+      return true;
+    }
+    const message = discloseErrors
+      ? err instanceof Error
+        ? err.message
+        : String(err)
+      : "Internal error";
     await writeWebResponse(Response.json({ ok: false, error: message }, { status: 500 }), res);
   }
   return true;

package/src/builder.js

@@ -66,8 +66,9 @@ export const DEP_MAP_FILE = ".wd-dev-deps.json";
 // Bumped whenever the map's shape changes, so a stale map from an older
 // Darkmown falls back to a full rebuild instead of being misread. (3: manifest
 // entries gained `assets.embedHosts` — a v2 map's entries would silently drop
-// them from a reassembled `_headers`/`routes.json`.)
-const DEP_MAP_VERSION = 3;
+// them from a reassembled `_headers`/`routes.json`. 4: the site record gained
+// `mdSource` — a v3 map has no answer for the incremental md_source check.)
+const DEP_MAP_VERSION = 4;
 
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 
@@ -290,6 +291,16 @@ function buildIncremental(cwd, paths, options, changed) {
       "site_url changed, and every page's canonical URL is built from it"
     );
   }
+  // The home page's `md_source` flag is the same kind of whole-site value: it
+  // decides every page's markdown alternate link AND which `<route>.md` files
+  // dist holds, so flipping it can never be a partial rebuild (a full rebuild
+  // also wipes the now-unwanted source copies).
+  if (Boolean(map.site.mdSource) !== identity.mdSource) {
+    return fullFallback(
+      changed,
+      "md_source changed, and every page's markdown alternate link is built from it"
+    );
+  }
 
   /** @type {Set<string>} */
   const affected = new Set();
@@ -351,11 +362,13 @@ function buildIncremental(cwd, paths, options, changed) {
       images.variants
     );
     // A shrunk pagination leaves stale `/page/N/` outputs behind — remove any
-    // previously-emitted page this rebuild no longer produces.
+    // previously-emitted page this rebuild no longer produces, along with its
+    // markdown-source copy when the site publishes those.
     const kept = new Set(built.mapEntry.pages.map((entry) => entry.route));
     for (const page of map.routes[routePath].pages) {
       if (!kept.has(page.route)) {
         fs.rmSync(outputPathForRoute(paths.distRoot, page.route), { force: true });
+        fs.rmSync(mdSourcePathForRoute(paths.distRoot, page.route), { force: true });
       }
     }
     if (built.notFoundHtml !== undefined) {
@@ -425,6 +438,9 @@ function buildRoute(
   titles,
   imageVariants
 ) {
+  // Markdown-source publishing (2.11): gated site-wide by the home page's
+  // `md_source: true`, opted out per page with `md_source: false`.
+  const mdSource = identity.mdSource && !mdSourceOptOut(route.meta);
   const compiled = compileRoutePages(
     route,
     paths,
@@ -432,7 +448,8 @@ function buildRoute(
     feedLink,
     identity,
     titles,
-    imageVariants
+    imageVariants,
+    mdSource
   );
   /** @type {RouteManifestEntry[]} */
   const entries = [];
@@ -447,6 +464,7 @@ function buildRoute(
     const outFile = outputPathForRoute(paths.distRoot, page.route);
     fs.mkdirSync(path.dirname(outFile), { recursive: true });
     fs.writeFileSync(outFile, page.html);
+    emitMdSource(route, page.route, paths, mdSource);
     if (page.route === "/404/") notFoundHtml = page.html;
     emitAssets(page.assets, paths, page.html, warned);
     if (page.assets.runtime) emitRuntime(paths);
@@ -624,7 +642,7 @@ function relPosix(cwd, file) {
  * unreadable, or from an incompatible version — every one of which means the
  * incremental build cannot trust its picture of the site and must go full.
  * @param {Paths} paths
- * @returns {{ version: number, feed: { href: string, title: string } | null, site: { url: string, titles: Record<string, string> }, routes: Record<string, DepMapEntry> } | null}
+ * @returns {{ version: number, feed: { href: string, title: string } | null, site: { url: string, titles: Record<string, string>, mdSource: boolean }, routes: Record<string, DepMapEntry> } | null}
  */
 function readDepMap(paths) {
   try {
@@ -640,7 +658,7 @@ function readDepMap(paths) {
  * Persist the dependency map for the next incremental build.
  * @param {Paths} paths
  * @param {{ href: string, title: string } | undefined} feedLink
- * @param {{ url: string, titles: Record<string, string> }} site {@link siteInputs}.
+ * @param {{ url: string, titles: Record<string, string>, mdSource: boolean }} site {@link siteInputs}.
  * @param {Record<string, DepMapEntry>} mapRoutes
  * @returns {void}
  */
@@ -657,15 +675,17 @@ function writeDepMap(paths, feedLink, site, mapRoutes) {
  * never appear in `routesAffectedBy`.
  *
  * `url` is `site_url` (every page's canonical + `og:url`); `titles` is every
- * route's title, because a nested page's breadcrumb JSON-LD names its ANCESTORS.
+ * route's title, because a nested page's breadcrumb JSON-LD names its ANCESTORS;
+ * `mdSource` is the home page's source-publishing flag, baked into every page's
+ * head as the `<link rel="alternate" type="text/markdown">`.
  * The next incremental build diffs both against the site it discovers, which is
  * the only way it can know that editing page A invalidated page B.
  * @param {SiteIdentity} identity
  * @param {Map<string, string>} titles
- * @returns {{ url: string, titles: Record<string, string> }}
+ * @returns {{ url: string, titles: Record<string, string>, mdSource: boolean }}
  */
 function siteInputs(identity, titles) {
-  return { url: identity.siteUrl, titles: Object.fromEntries(titles) };
+  return { url: identity.siteUrl, titles: Object.fromEntries(titles), mdSource: identity.mdSource };
 }
 
 /**
@@ -792,9 +812,21 @@ function copyChangedAsset(file, cwd, paths) {
  * @param {Map<string, string>} titles Route path → page title, for breadcrumbs.
  * @param {Map<string, number[]>} imageVariants Generated responsive variants
  *   (original's absolute source path → widths) for the srcset wiring.
+ * @param {boolean} mdSource Whether this route publishes its markdown source
+ *   (site opted in AND the page did not opt out) — every emitted page then
+ *   advertises `<route>.md` with a `<link rel="alternate" type="text/markdown">`.
  * @returns {{ pages: EmittedPage[], deps: Set<string>, collections: Set<string> }}
  */
-function compileRoutePages(route, paths, collections, feedLink, identity, titles, imageVariants) {
+function compileRoutePages(
+  route,
+  paths,
+  collections,
+  feedLink,
+  identity,
+  titles,
+  imageVariants,
+  mdSource
+) {
   /** @type {Set<string>} */
   const deps = new Set();
   /** @type {Set<string>} */
@@ -813,10 +845,15 @@ function compileRoutePages(route, paths, collections, feedLink, identity, titles
     route: routePath,
     breadcrumbs: breadcrumbTrail(routePath, titles, identity.siteUrl)
   });
+  // The markdown-source alternate every emitted page of this route advertises
+  // when publishing is on: `<route>.md`, where buildRoute copies the source.
+  const mdFor = (/** @type {string} */ routePath) =>
+    mdSource ? { href: mdSourceHrefFor(routePath) } : undefined;
   // First compile (discovery): page 1 with a placeholder pager. If the page has
   // no `paginate`, this is the only compile and we emit it as-is.
   const first = compilePage(route.file, paths, {
     feed: feedLink,
+    mdSource: mdFor(route.route),
     site: siteFor(route.route),
     collections,
     vars: { page: pagerVars(route.route, 1, 1) },
@@ -843,6 +880,7 @@ function compileRoutePages(route, paths, collections, feedLink, identity, titles
     // would ask Google to drop pages 2..N from the index entirely.
     const page = compilePage(route.file, paths, {
       feed: feedLink,
+      mdSource: mdFor(pageRoute(route.route, n)),
       site: siteFor(pageRoute(route.route, n)),
       collections,
       vars: { page: pagerVars(route.route, n, total) },
@@ -889,6 +927,69 @@ function pageRoute(baseRoute, n) {
   return n === 1 ? baseRoute : `${baseRoute}page/${n}/`;
 }
 
+/**
+ * Whether a page opts OUT of markdown-source publishing (`md_source: false`).
+ * Mirrors the router's `isDraft`: the scalar parser yields a boolean or the
+ * string `"false"`, and only those opt out. Any other value — including a
+ * page-level `md_source: true` — is not an opt-out; publishing is gated
+ * site-wide by the HOME page's `md_source: true`, never per page.
+ * @param {Meta} meta
+ * @returns {boolean}
+ */
+function mdSourceOptOut(meta) {
+  return meta.md_source === false || meta.md_source === "false";
+}
+
+/**
+ * The dist path a route's markdown source publishes to: `/` → `dist/index.md`,
+ * `/docs/` → `dist/docs.md`, `/blog/post/` → `dist/blog/post.md`. The file sits
+ * at the folder level next to the route's `<route>/index.html`, so by
+ * construction it can never collide with a route output — and being dist-side
+ * only, route discovery (which reads `site/pages`) never mistakes it for a page.
+ * @param {string} distRoot Absolute path to the build output directory.
+ * @param {string} route Public route path (trailing-slashed).
+ * @returns {string}
+ */
+function mdSourcePathForRoute(distRoot, route) {
+  const clean = route === "/" ? "index" : route.replace(/^\/|\/$/g, "");
+  return path.join(distRoot, `${clean}.md`);
+}
+
+/**
+ * The public URL a route's markdown source serves at: `/` → `/index.md`,
+ * `/docs/` → `/docs.md`. Matches {@link mdSourcePathForRoute} exactly.
+ * @param {string} route Public route path (trailing-slashed).
+ * @returns {string}
+ */
+function mdSourceHrefFor(route) {
+  return route === "/" ? "/index.md" : `${route.slice(0, -1)}.md`;
+}
+
+/**
+ * Publish (or withdraw) one route's markdown source beside its HTML output.
+ * The copy is BYTE-EXACT — `fs.copyFileSync`, no transformation, no header
+ * injection — so the file an agent fetches is the file the author wrote,
+ * frontmatter and line endings included. When publishing is off for the route
+ * (site flag unset, or the page opted out) any previously emitted copy is
+ * removed instead: an incremental rebuild does not wipe dist, so a stale file
+ * would otherwise keep serving after the opt-out.
+ * @param {Route} route The source route (its `file` is what gets copied).
+ * @param {string} routePath The emitted page's public route (a paginated page
+ *   publishes the same source under its own `<route>.md`).
+ * @param {Paths} paths
+ * @param {boolean} enabled
+ * @returns {void}
+ */
+function emitMdSource(route, routePath, paths, enabled) {
+  const out = mdSourcePathForRoute(paths.distRoot, routePath);
+  if (!enabled) {
+    fs.rmSync(out, { force: true });
+    return;
+  }
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.copyFileSync(route.file, out);
+}
+
 /**
  * Build the `{ page.* }` pager exposed to the template scope of a paginated
  * listing: `current`/`total` numbers and `prev`/`next` URLs (empty string at the
@@ -916,6 +1017,8 @@ function pagerVars(baseRoute, current, total) {
  * @property {string} description Site description (also the RSS channel description).
  * @property {string} aiCrawlers `"allow"` or `"deny"`, from `ai_crawlers:`.
  * @property {number} rssLimit Most-recent-first RSS item cap, from `rss_limit:`.
+ * @property {boolean} mdSource Publish every page's markdown source at
+ *   `<route>.md`, from the home page's `md_source: true` (2.11).
  */
 
 /**
@@ -940,7 +1043,11 @@ function siteIdentity(routes) {
     title: read("title") || "Darkmown",
     description: read("description"),
     aiCrawlers: aiCrawlerPolicy(meta, home ? home.file : undefined),
-    rssLimit: rssItemLimit(meta, home ? home.file : undefined)
+    rssLimit: rssItemLimit(meta, home ? home.file : undefined),
+    // `md_source: true` opts the whole site into publishing sources; a page
+    // opts back out with `md_source: false` (see mdSourceOptOut). Accepts the
+    // boolean and the string, like `isDraft`/`isNoindex`.
+    mdSource: meta.md_source === true || meta.md_source === "true"
   };
 }
 
@@ -1464,15 +1571,17 @@ function emitAssets(assets, paths, pageHtml, warned) {
     fs.mkdirSync(path.dirname(out), { recursive: true });
     if (source.endsWith(".skin")) {
       const src = fs.readFileSync(source, "utf8");
+      // `file` threads the source path into compileSkin so a skin authoring
+      // error reports `file:line` like every other compile error.
       if (assets.scopedSkins.has(source)) {
         const rel = path.relative(paths.cwd, source).replaceAll(path.sep, "/");
         const scope = scopeIdFor(rel);
         /** @type {Set<string>} */
         const subjects = new Set();
-        fs.writeFileSync(out, compileSkin(src, { scope, subjects }));
+        fs.writeFileSync(out, compileSkin(src, { scope, subjects, file: source }));
         warnUnusedScoped(subjects, scope, pageHtml, path.basename(source), warned);
       } else {
-        fs.writeFileSync(out, compileSkin(src));
+        fs.writeFileSync(out, compileSkin(src, { file: source }));
       }
     } else {
       fs.copyFileSync(source, out);

package/src/catalog.js

@@ -581,6 +581,12 @@ const FRONTMATTER_KEYS = [
     description: "HOME PAGE ONLY: how many newest posts rss.xml carries (default 20).",
     example: "rss_limit: 50"
   },
+  {
+    name: "md_source",
+    description:
+      'HOME PAGE ONLY: publish every page\'s markdown source at <route>.md, advertised with a <link rel="alternate" type="text/markdown"> in the head. A page opts out with md_source: false.',
+    example: "md_source: true"
+  },
   {
     name: "date",
     description: "Marks the page a post: RSS item, sitemap lastmod, og:type=article.",

package/src/cli.js

@@ -18,6 +18,8 @@ import {
   devEventsPath,
   injectDevClient
 } from "./dev.js";
+import { createDispatcher, serveMcp } from "./mcp.js";
+import { mcpConfig } from "./mcp-tools.js";
 import { discoverRoutes, isDraft, outputPathForRoute } from "./router.js";
 import { availableTemplates, initProject } from "./scaffold.js";
 import { contentType, isServableFile, pipeFile, resolvePublicFile, serve } from "./statics.js";
@@ -109,6 +111,9 @@ export async function run(argv, env = {}) {
     const target = argv.slice(1).find((arg) => !arg.startsWith("-"));
     return runValidate({ cwd, target, log, error });
   }
+  if (command === "mcp") {
+    return runMcpCommand({ argv, error });
+  }
   if (command === "dev") {
     return startDevServer({ cwd, log, warn, error });
   }
@@ -301,6 +306,35 @@ function plural(n, word) {
   return n === 1 ? word : `${word}s`;
 }
 
+/**
+ * `darkmown mcp`: run the Model Context Protocol server on stdio, so an agent
+ * (Claude Code, Codex, Cursor, …) can query the directive catalog, grammar,
+ * error codes, and docs, and validate `.wd` source, with zero extra
+ * dependencies. stdout carries ONLY protocol frames; the startup line and any
+ * diagnostics go to stderr (the `error` sink), because one stray byte on
+ * stdout corrupts the JSON-RPC stream. Resolves when the host closes stdin.
+ * @param {{ argv: string[], error: typeof console.error }} io
+ * @returns {Promise<{ command: "mcp" }>}
+ */
+function runMcpCommand({ argv, error }) {
+  const extra = argv.slice(1);
+  if (extra.length > 0) {
+    error(`Unknown argument for mcp: ${extra[0]}`);
+    error("Usage: darkmown mcp   (speaks MCP over stdio; takes no arguments)");
+    throw new CliError(`Unknown argument: ${extra[0]}`, { silent: true });
+  }
+  const config = mcpConfig();
+  error(
+    `Darkmown MCP server v${config.serverInfo.version} on stdio. ` +
+      "Point your agent's MCP config at this command; stop with Ctrl-C or by closing stdin."
+  );
+  return serveMcp({
+    input: process.stdin,
+    output: process.stdout,
+    dispatcher: createDispatcher(config)
+  });
+}
+
 /**
  * Start the live-compiler dev server. Builds once (recording, not crashing on, a
  * broken initial build), watches `site/` and `src/`, and serves dist with the
@@ -413,7 +447,10 @@ function startDevServer({ cwd, log, warn, error }) {
     }
     // Serverless parity: run a project `api/*.js` function if the path matches,
     // exactly as Vercel/Cloudflare would in production; otherwise serve static. A
-    // throw on either path (e.g. a stat/read error) becomes a clean 500.
+    // throw on either path (e.g. a stat/read error) becomes a clean 500. Dev
+    // DELIBERATELY echoes the stack and the api runner keeps real error messages
+    // (the `discloseErrors` default) — this is the author's own machine; `serve`
+    // is the production-shaped path and discloses nothing.
     handleApiRequest({ apiDir, req, res })
       .then((handled) => {
         if (!handled) serveDev(distRoot, url, res, draftRoutes(cwd), () => lastBuildError);
@@ -473,15 +510,20 @@ function startPreviewServer({ cwd, log, error }) {
   const server = http.createServer((req, res) => {
     const acceptEncoding = req.headers["accept-encoding"];
     // Serverless parity, exactly as in dev: run a project api/*.js function when
-    // the path matches; otherwise serve static (compressed when negotiated). A
-    // throw on either path (e.g. a malformed dynamic segment) becomes a clean 500.
-    handleApiRequest({ apiDir, req, res, acceptEncoding })
+    // the path matches; otherwise serve static (compressed when negotiated).
+    // Unlike dev, serve mirrors PRODUCTION disclosure rules: the api runner gets
+    // `discloseErrors: false` (the client sees "Internal error", same shape as
+    // the generated Cloudflare worker), a malformed dynamic segment is a clean
+    // 400 inside the runner, and an unexpected throw here is logged server-side
+    // but never echoed — a stack trace leaks paths and internals to the client.
+    handleApiRequest({ apiDir, req, res, acceptEncoding, discloseErrors: false })
       .then((handled) => {
         if (!handled) serve(distRoot, req.url || "/", res, { acceptEncoding });
       })
       .catch((err) => {
+        error(err instanceof Error && err.stack ? err.stack : String(err));
         res.writeHead(500, { "content-type": "text/plain" });
-        res.end((err instanceof Error && err.stack) || String(err));
+        res.end("Internal Server Error");
       });
   });
   return new Promise((resolve) => {
@@ -580,6 +622,7 @@ Usage:
   darkmown validate [path]                  Compile-check pages without building (exit 1 on errors)
   darkmown deploy <${DEPLOY_TARGETS.join("|")}> [--prod]    Build + deploy to a platform
   darkmown serve                            Preview the built dist locally
+  darkmown mcp                              Run the MCP server on stdio (catalog, grammar, validate, error codes, docs)
   darkmown catalog [--llms|--llms-full]     Print the .wd directive catalog (JSON, --llms cheatsheet, or --llms-full reference)
   darkmown version                          Print the installed Darkmown version
   darkmown help                             Show this help

package/src/compiler/page.js

@@ -46,10 +46,13 @@ const SKIP_LINK_STYLE =
  * Compile a page source file into a full HTML document plus its assets.
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string }, site?: SiteContext, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./reader.js").Reader, imageVariants?: Map<string, number[]> | null }} [options]
+ * @param {{ feed?: { href: string, title: string }, mdSource?: { href: string }, site?: SiteContext, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./reader.js").Reader, imageVariants?: Map<string, number[]> | null }} [options]
  *   When a site-wide RSS feed is emitted (the home page set `site_url` and the
  *   site has dated posts), `feed` carries its absolute href + title so every page
- *   links it. `site` carries the origin + this page's own route (and its resolved
+ *   links it. When the site publishes markdown sources (the home page set
+ *   `md_source: true` and this page did not opt out), `mdSource` carries the
+ *   page's own `<route>.md` href for the alternate link. `site` carries the
+ *   origin + this page's own route (and its resolved
  *   breadcrumb trail) so the shell can state a canonical URL. `collections` is the
  *   build-time collection index a bare-name `@loop` resolves against; `vars` seeds
  *   the document scope (the pager `page` object on a paginated route). `reader` is
@@ -154,6 +157,14 @@ export function compilePage(file, context, options = {}) {
   const feedLink = options.feed
     ? `\n  <link rel="alternate" type="application/rss+xml" title="${escapeHtml(options.feed.title)}" href="${escapeHtml(options.feed.href)}">`
     : "";
+  // Markdown-source discovery (2.11): when the site publishes its sources (home
+  // `md_source: true`, and this page did not opt out), the builder copies the
+  // page's source to `<route>.md` and the page advertises it here, so an agent
+  // can autodiscover and fetch the plain markdown instead of the HTML.
+  // Build-time only — no client JS.
+  const mdSourceLink = options.mdSource
+    ? `\n  <link rel="alternate" type="text/markdown" href="${escapeHtml(options.mdSource.href)}" title="Markdown source">`
+    : "";
   // Pay-for-what-you-use behavior modules (slider is compile-time and never here;
   // sortable/carousel each emit one) load after the runtime — sortable depends on
   // `window.wd` — and before any colocated page script.
@@ -239,7 +250,7 @@ export function compilePage(file, context, options = {}) {
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${escapeHtml(title)}</title>${descriptionTag}
-  <link rel="icon" href="${icon.href}"${icon.type ? ` type="${icon.type}"` : ""}>${feedLink}
+  <link rel="icon" href="${icon.href}"${icon.type ? ` type="${icon.type}"` : ""}>${feedLink}${mdSourceLink}
   ${SKIP_LINK_STYLE}
   ${cssLinks}${transitions}${speculation}
 </head>
@@ -735,7 +746,7 @@ function foldBuildBindingsLine(line, values) {
  * @param {Record<string, string> | Map<string, string>} files Project-relative
  *   path → source content.
  * @param {string} entryPath Project-relative path of the page to compile.
- * @param {{ feed?: { href: string, title: string }, site?: SiteContext, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, cwd?: string }} [options]
+ * @param {{ feed?: { href: string, title: string }, mdSource?: { href: string }, site?: SiteContext, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, cwd?: string }} [options]
  *   Same shell options as {@link compilePage}; `cwd` overrides the virtual
  *   project root the relative keys resolve against (defaults to `/`).
  * @returns {CompiledPage}
@@ -747,6 +758,7 @@ export function compileFromMemory(files, entryPath, options = {}) {
   const abs = path.resolve(cwd, entryPath);
   return compilePage(abs, context, {
     feed: options.feed,
+    mdSource: options.mdSource,
     site: options.site,
     collections: options.collections,
     vars: options.vars,