zudoku 0.85.0 → 0.86.0

package/dist/cli/cli.js

@@ -53,13 +53,90 @@ var init_joinUrl = __esm({
   }
 });
 
+// src/lib/util/markdown.ts
+var getMarkdownPathname;
+var init_markdown = __esm({
+  "src/lib/util/markdown.ts"() {
+    getMarkdownPathname = (pathname) => pathname === "/" ? "/index" : pathname;
+  }
+});
+
+// src/lib/util/markdown-representation.ts
+var encodePathSegment, encodeDocumentationRoutePath, resolveDocumentationRoutePath, getMarkdownRepresentationPath, getMarkdownAlternateLink, appendLinkHeader, getMarkdownNotFound;
+var init_markdown_representation = __esm({
+  "src/lib/util/markdown-representation.ts"() {
+    init_joinUrl();
+    init_markdown();
+    encodePathSegment = (segment) => {
+      try {
+        return encodeURIComponent(decodeURIComponent(segment));
+      } catch {
+        return encodeURIComponent(segment);
+      }
+    };
+    encodeDocumentationRoutePath = (routePath) => {
+      const encodedPath = routePath.split("/").filter(Boolean).map(encodePathSegment).join("/");
+      return encodedPath ? `/${encodedPath}` : "/";
+    };
+    resolveDocumentationRoutePath = (requestUrl, basePath) => {
+      const pathname = new URL(requestUrl, "http://localhost").pathname;
+      const normalizedBasePath = encodeDocumentationRoutePath(joinUrl(basePath));
+      if (normalizedBasePath !== "/" && pathname !== normalizedBasePath && !pathname.startsWith(`${normalizedBasePath}/`)) {
+        return;
+      }
+      const relativePath = normalizedBasePath === "/" ? pathname : pathname.slice(normalizedBasePath.length) || "/";
+      return encodeDocumentationRoutePath(relativePath);
+    };
+    getMarkdownRepresentationPath = (routePath, basePath) => joinUrl(
+      encodeDocumentationRoutePath(joinUrl(basePath)),
+      `${getMarkdownPathname(encodeDocumentationRoutePath(routePath))}.md`
+    );
+    getMarkdownAlternateLink = (routePath, basePath) => `<${getMarkdownRepresentationPath(routePath, basePath)}>; rel="alternate"; type="text/markdown"`;
+    appendLinkHeader = (currentValue, linkValue) => {
+      const normalizedValue = Array.isArray(currentValue) ? currentValue.join(", ") : currentValue?.toString().trim();
+      return normalizedValue ? `${normalizedValue}, ${linkValue}` : linkValue;
+    };
+    getMarkdownNotFound = ({
+      basePath,
+      includeLlmsTxt,
+      markdownRoutePaths,
+      sitemapOutDir
+    }) => {
+      const encodedBasePath = encodeDocumentationRoutePath(joinUrl(basePath));
+      const markdownEntryRoute = markdownRoutePaths.includes("/") ? "/" : markdownRoutePaths[0];
+      const links = [
+        `[Documentation home](${encodedBasePath})`,
+        ...markdownEntryRoute ? [
+          `[Markdown documentation index](${getMarkdownRepresentationPath(markdownEntryRoute, basePath)})`
+        ] : [],
+        ...includeLlmsTxt ? [`[Agent documentation index](${joinUrl(encodedBasePath, "llms.txt")})`] : [],
+        ...sitemapOutDir !== void 0 ? [
+          `[Sitemap](${joinUrl(
+            encodedBasePath,
+            encodeDocumentationRoutePath(sitemapOutDir),
+            "sitemap.xml"
+          )})`
+        ] : []
+      ];
+      return [
+        "# Page not found",
+        "",
+        "The requested documentation page does not exist. Try one of these entry points:",
+        "",
+        ...links.map((link) => `- ${link}`),
+        ""
+      ].join("\n");
+    };
+  }
+});
+
 // src/vite/llms.ts
 var llms_exports = {};
 __export(llms_exports, {
   generateLlmsTxtFiles: () => generateLlmsTxtFiles
 });
 import { writeFile as writeFile5 } from "node:fs/promises";
-import path21 from "node:path";
+import path22 from "node:path";
 import colors6 from "picocolors";
 async function generateLlmsTxtFiles({
   markdownFileInfos,
@@ -69,32 +146,44 @@ async function generateLlmsTxtFiles({
   siteName,
   llmsTxt,
   llmsTxtFull,
+  title: configuredTitle,
+  description: configuredDescription,
+  instructions,
   redirectUrls
 }) {
   const nonRedirectUrls = outputUrls.filter((url) => !redirectUrls.has(url));
   const baseUrl = basePath ?? "";
-  const title = siteName ?? "Documentation";
+  const title = toSingleLine(configuredTitle ?? siteName ?? DEFAULT_TITLE);
+  const description = toSingleLine(
+    configuredDescription ?? DEFAULT_DESCRIPTION
+  );
+  const formattedInstructions = instructions ? formatInstructions(instructions) : void 0;
   const markdownMap = new Map(
     markdownFileInfos.map((info) => [info.routePath, info])
   );
   if (llmsTxt) {
-    const llmsTxtParts = [];
-    llmsTxtParts.push(`# ${title}
-`);
-    llmsTxtParts.push("> Documentation files for Large Language Models\n");
-    llmsTxtParts.push("## Documentation\n");
+    const documentationLinks = [];
     for (const url of nonRedirectUrls) {
       if (/(400|404|500)$/.test(url)) continue;
       const mdInfo = markdownMap.get(url);
       if (mdInfo) {
-        const mdUrl = joinUrl(baseUrl, `${url}.md`);
-        const linkTitle = mdInfo.title ?? url;
-        const description = mdInfo.description ? `: ${mdInfo.description}` : "";
-        llmsTxtParts.push(`- [${linkTitle}](${mdUrl})${description}`);
+        const mdUrl = getMarkdownRepresentationPath(url, basePath);
+        const linkTitle = escapeMarkdownLinkLabel(mdInfo.title ?? url);
+        const linkDescription = mdInfo.description ? `: ${toSingleLine(mdInfo.description)}` : "";
+        documentationLinks.push(`- [${linkTitle}](${mdUrl})${linkDescription}`);
       }
     }
-    const llmsTxt2 = llmsTxtParts.join("\n");
-    await writeFile5(path21.join(baseOutputDir, "llms.txt"), llmsTxt2, "utf-8");
+    const llmsTxtParts = [
+      `# ${title}`,
+      `> ${description}`,
+      ...formattedInstructions ? [formattedInstructions] : [],
+      ...documentationLinks.length > 0 ? ["## Documentation", documentationLinks.join("\n")] : []
+    ];
+    await writeFile5(
+      path22.join(baseOutputDir, "llms.txt"),
+      llmsTxtParts.join("\n\n"),
+      "utf-8"
+    );
     console.log(colors6.blue("\u2713 generated llms.txt"));
   }
   if (llmsTxtFull) {
@@ -112,24 +201,35 @@ async function generateLlmsTxtFiles({
         llmsFullParts.push(`${info.description}
 `);
       }
-      llmsFullParts.push(`URL: ${joinUrl(baseUrl, info.routePath)}
-`);
+      llmsFullParts.push(
+        `URL: ${joinUrl(baseUrl, encodeDocumentationRoutePath(info.routePath))}
+`
+      );
       llmsFullParts.push(`
 ${info.content}
 `);
     }
     const llmsFull = llmsFullParts.join("\n");
     await writeFile5(
-      path21.join(baseOutputDir, "llms-full.txt"),
+      path22.join(baseOutputDir, "llms-full.txt"),
       llmsFull,
       "utf-8"
     );
     console.log(colors6.blue("\u2713 generated llms-full.txt"));
   }
 }
+var DEFAULT_TITLE, DEFAULT_DESCRIPTION, toSingleLine, escapeMarkdownLinkLabel, formatInstructions;
 var init_llms = __esm({
   "src/vite/llms.ts"() {
     init_joinUrl();
+    init_markdown_representation();
+    DEFAULT_TITLE = "Documentation";
+    DEFAULT_DESCRIPTION = "Documentation files for Large Language Models";
+    toSingleLine = (value) => value.replaceAll(/\s+/g, " ").trim();
+    escapeMarkdownLinkLabel = (value) => toSingleLine(value).replaceAll(/([\\[\]])/g, "\\$1");
+    formatInstructions = (value) => value.trim().replaceAll("\r\n", "\n").split("\n").map(
+      (line) => line.replace(/^( {0,3})(#{1,6})(?=\s|$)/, "$1\\$2").replace(/^( {0,3})([=-]{2,})\s*$/, "$1\\$2")
+    ).join("\n");
   }
 });
 
@@ -138,12 +238,12 @@ import { hideBin } from "yargs/helpers";
 import yargs from "yargs/yargs";
 
 // src/cli/build/handler.ts
-import path26 from "node:path";
+import path27 from "node:path";
 
 // src/vite/build.ts
-import { existsSync as existsSync2 } from "node:fs";
-import { mkdir as mkdir6, readFile as readFile5, rename as rename2, rm as rm3, writeFile as writeFile6 } from "node:fs/promises";
-import path24 from "node:path";
+import { existsSync as existsSync3 } from "node:fs";
+import { mkdir as mkdir6, readFile as readFile5, rename as rename2, rm as rm4, writeFile as writeFile6 } from "node:fs/promises";
+import path25 from "node:path";
 import { build as esbuild } from "esbuild";
 import { createBuilder } from "vite";
 
@@ -320,7 +420,7 @@ var ZudokuError = class extends Error {
 
 // src/config/file-exists.ts
 import { stat } from "node:fs/promises";
-var fileExists = (path31) => stat(path31).then(() => true).catch(() => false);
+var fileExists = (path32) => stat(path32).then(() => true).catch(() => false);
 
 // src/config/plugin-versions.ts
 import { readFile } from "node:fs/promises";
@@ -3067,8 +3167,8 @@ import { createNanoEvents } from "nanoevents";
 
 // src/lib/util/url.ts
 import { matchPath } from "react-router";
-var matchesProtectedPattern = (pattern, path31) => matchPath({ path: pattern, end: true }, path31) != null;
-var matchesAnyProtectedPattern = (patterns, path31) => patterns.some((p) => matchesProtectedPattern(p, path31));
+var matchesProtectedPattern = (pattern, path32) => matchPath({ path: pattern, end: true }, path32) != null;
+var matchesAnyProtectedPattern = (patterns, path32) => patterns.some((p) => matchesProtectedPattern(p, path32));
 
 // src/lib/core/ZudokuContext.ts
 var normalizeProtectedRoutes = (val) => {
@@ -3170,6 +3270,16 @@ var ApiConfigSchema = z7.object({
   categories: z7.array(ApiCatalogCategorySchema),
   options: ApiOptionsSchema
 }).partial();
+var OpenApiPublicationSchema = z7.object({
+  path: z7.string().regex(
+    /^\/(?!\/)(?:[A-Za-z0-9._~-]+\/)*[A-Za-z0-9._~-]+\.(?:json|ya?ml)$/i,
+    "OpenAPI publication path must be a root-relative .json, .yaml, or .yml path without traversal, query, or fragment components"
+  ).refine(
+    (value) => value.split("/").every((segment) => segment !== "." && segment !== ".."),
+    "OpenAPI publication path must not contain traversal segments"
+  ),
+  agentQuality: z7.boolean().optional()
+});
 var VersionConfigSchema = z7.object({
   path: z7.string(),
   input: z7.string(),
@@ -3187,6 +3297,7 @@ var ApiSchema = z7.discriminatedUnion("type", [
       z7.string(),
       z7.array(z7.union([z7.string(), VersionConfigSchema]))
     ]),
+    publish: OpenApiPublicationSchema.optional(),
     ...ApiConfigSchema.shape
   }),
   z7.object({
@@ -3301,6 +3412,13 @@ var LlmsConfigSchema = z7.object({
   ),
   includeProtected: z7.boolean().default(false).describe(
     "When enabled, includes content from protected routes in the generated .md files and llms.txt files. By default, protected routes are excluded."
+  ),
+  title: z7.string().trim().min(1).optional().describe(
+    "The project or site name rendered as the llms.txt H1. Defaults to the configured site title."
+  ),
+  description: z7.string().trim().min(1).optional().describe("A short project summary rendered as the llms.txt blockquote."),
+  instructions: z7.string().trim().min(1).optional().describe(
+    "Guidance for agents, such as when to use the documentation and how to interpret it. Rendered as introductory prose before the link sections."
   )
 }).partial().prefault({});
 var DocsConfigSchema = z7.object({
@@ -3308,6 +3426,9 @@ var DocsConfigSchema = z7.object({
   publishMarkdown: z7.boolean().default(true).describe(
     "When enabled, generates .md files for each document during build. Access documents at their URL path with .md extension (e.g., /foo/hello.md). Markdown files are generated without frontmatter."
   ),
+  contentNegotiation: z7.boolean().optional().describe(
+    "When enabled, serves generated Markdown at canonical document URLs when Accept prefers text/markdown and adds Vary: Accept. Defaults to the value of publishMarkdown."
+  ),
   defaultOptions: z7.object({
     toc: z7.boolean(),
     copyPage: z7.boolean().optional(),
@@ -3321,7 +3442,10 @@ var DocsConfigSchema = z7.object({
     }).optional()
   }).partial().optional(),
   llms: LlmsConfigSchema
-}).prefault({});
+}).transform((docs) => ({
+  ...docs,
+  contentNegotiation: docs.publishMarkdown && (docs.contentNegotiation ?? true)
+})).prefault({});
 var Redirect = z7.object({
   from: z7.string(),
   to: z7.string()
@@ -3956,7 +4080,7 @@ var getIssuer = async (config) => {
 init_joinUrl();
 
 // src/vite/config.ts
-import path17 from "node:path";
+import path18 from "node:path";
 import dotenv from "dotenv";
 import colors4 from "picocolors";
 import {
@@ -4175,8 +4299,8 @@ var viteApiKeysPlugin = () => {
 var plugin_api_keys_default = viteApiKeysPlugin;
 
 // src/vite/plugin-api.ts
-import fs2 from "node:fs/promises";
-import path12 from "node:path";
+import fs3 from "node:fs/promises";
+import path13 from "node:path";
 import { deepEqual as deepEqual2 } from "fast-equals";
 import { runnerImport as runnerImport3 } from "vite";
 import { parse as parseYaml } from "yaml";
@@ -4328,14 +4452,14 @@ var flattenAllOf = (schema2) => {
 };
 
 // src/lib/util/traverse.ts
-var traverse = (specification, transform, path31 = []) => {
-  const transformed = transform(specification, path31);
+var traverse = (specification, transform, path32 = []) => {
+  const transformed = transform(specification, path32);
   if (typeof transformed !== "object" || transformed === null) {
     return transformed;
   }
   const result = Array.isArray(transformed) ? [] : {};
   for (const [key, value] of Object.entries(transformed)) {
-    const currentPath = [...path31, key];
+    const currentPath = [...path32, key];
     if (Array.isArray(value)) {
       result[key] = value.map(
         (item, index) => typeof item === "object" && item != null ? traverse(item, transform, [...currentPath, index.toString()]) : item
@@ -4363,9 +4487,9 @@ var resolveLocalRef = (schema2, ref) => {
   if (schemaCache?.has(ref)) {
     return schemaCache.get(ref);
   }
-  const path31 = ref.split("/").slice(1);
+  const path32 = ref.split("/").slice(1);
   let current = schema2;
-  for (const segment of path31) {
+  for (const segment of path32) {
     if (!current || typeof current !== "object") {
       current = null;
     }
@@ -4384,7 +4508,7 @@ var dereference = async (schema2, resolvers = []) => {
   }
   const cloned = structuredClone(schema2);
   const visited = /* @__PURE__ */ new Set();
-  const resolve = async (current, path31) => {
+  const resolve = async (current, path32) => {
     if (isIndexableObject(current)) {
       if (visited.has(current)) {
         return CIRCULAR_REF;
@@ -4392,7 +4516,7 @@ var dereference = async (schema2, resolvers = []) => {
       visited.add(current);
       if (Array.isArray(current)) {
         for (let index = 0; index < current.length; index++) {
-          current[index] = await resolve(current[index], `${path31}/${index}`);
+          current[index] = await resolve(current[index], `${path32}/${index}`);
         }
       } else {
         if ("$ref" in current && typeof current.$ref === "string") {
@@ -4403,13 +4527,13 @@ var dereference = async (schema2, resolvers = []) => {
           for (const resolver of resolvers) {
             const resolved = await resolver($ref);
             if (resolved) {
-              result2 = await resolve(resolved, path31);
+              result2 = await resolve(resolved, path32);
               break;
             }
           }
           if (result2 === void 0) {
             const resolved = await resolveLocalRef(cloned, $ref);
-            result2 = await resolve(resolved, path31);
+            result2 = await resolve(resolved, path32);
           }
           if (hasSiblings) {
             if (result2 === CIRCULAR_REF) {
@@ -4422,7 +4546,7 @@ var dereference = async (schema2, resolvers = []) => {
           return result2;
         }
         for (const key in current) {
-          current[key] = await resolve(current[key], `${path31}/${key}`);
+          current[key] = await resolve(current[key], `${path32}/${key}`);
         }
       }
       visited.delete(current);
@@ -4461,9 +4585,9 @@ var upgradeSchema = (schema2) => {
     }
     return sub;
   });
-  schema2 = traverse(schema2, (sub, path31) => {
+  schema2 = traverse(schema2, (sub, path32) => {
     if (sub.example !== void 0) {
-      if (isSchemaPath(path31 ?? [])) {
+      if (isSchemaPath(path32 ?? [])) {
         sub.examples = [sub.example];
       } else {
         sub.examples = {
@@ -4476,11 +4600,11 @@ var upgradeSchema = (schema2) => {
     }
     return sub;
   });
-  schema2 = traverse(schema2, (schema3, path31) => {
+  schema2 = traverse(schema2, (schema3, path32) => {
     if (schema3.type === "object" && schema3.properties !== void 0) {
-      const parentPath = path31?.slice(0, -1);
+      const parentPath = path32?.slice(0, -1);
       const isMultipart = parentPath?.some((segment, index) => {
-        return segment === "content" && path31?.[index + 1] === "multipart/form-data";
+        return segment === "content" && path32?.[index + 1] === "multipart/form-data";
       });
       if (isMultipart) {
         const entries = Object.entries(schema3.properties);
@@ -4494,8 +4618,8 @@ var upgradeSchema = (schema2) => {
     }
     return schema3;
   });
-  schema2 = traverse(schema2, (schema3, path31) => {
-    if (path31?.includes("content") && path31.includes("application/octet-stream")) {
+  schema2 = traverse(schema2, (schema3, path32) => {
+    if (path32?.includes("content") && path32.includes("application/octet-stream")) {
       return {};
     }
     if (schema3.type === "string" && schema3.format === "binary") {
@@ -4521,11 +4645,11 @@ var upgradeSchema = (schema2) => {
     }
     return sub;
   });
-  schema2 = traverse(schema2, (schema3, path31) => {
+  schema2 = traverse(schema2, (schema3, path32) => {
     if (schema3.type === "string" && schema3.format === "byte") {
-      const parentPath = path31?.slice(0, -1);
+      const parentPath = path32?.slice(0, -1);
       const contentMediaType = parentPath?.find(
-        (_, index) => path31?.[index - 1] === "content"
+        (_, index) => path32?.[index - 1] === "content"
       );
       return {
         type: "string",
@@ -4537,7 +4661,7 @@ var upgradeSchema = (schema2) => {
   });
   return schema2;
 };
-function isSchemaPath(path31) {
+function isSchemaPath(path32) {
   const schemaLocations = [
     ["components", "schemas"],
     "properties",
@@ -4550,10 +4674,10 @@ function isSchemaPath(path31) {
   ];
   return schemaLocations.some((location) => {
     if (Array.isArray(location)) {
-      return location.every((segment, index) => path31[index] === segment);
+      return location.every((segment, index) => path32[index] === segment);
     }
-    return path31.includes(location);
-  }) || path31.includes("schema") || path31.some((segment) => segment.endsWith("Schema"));
+    return path32.includes(location);
+  }) || path32.includes("schema") || path32.some((segment) => segment.endsWith("Schema"));
 }
 
 // src/lib/oas/parser/index.ts
@@ -4635,13 +4759,13 @@ var OPENAPI_PROPS = /* @__PURE__ */ new Set([
   "anyOf",
   "oneOf"
 ]);
-var handleCircularRefs = (obj, currentPath = /* @__PURE__ */ new WeakSet(), refs = /* @__PURE__ */ new WeakMap(), path31 = [], currentRefPaths = /* @__PURE__ */ new Set()) => {
+var handleCircularRefs = (obj, currentPath = /* @__PURE__ */ new WeakSet(), refs = /* @__PURE__ */ new WeakMap(), path32 = [], currentRefPaths = /* @__PURE__ */ new Set()) => {
   if (obj === null || typeof obj !== "object") return obj;
   const refPath = obj.__$ref;
   const isCircular = currentPath.has(obj) || typeof refPath === "string" && currentRefPaths.has(refPath);
   if (isCircular) {
     if (typeof refPath === "string") return SCHEMA_REF_PREFIX + refPath;
-    const circularProp = path31.find((p) => !OPENAPI_PROPS.has(p)) || path31[0];
+    const circularProp = path32.find((p) => !OPENAPI_PROPS.has(p)) || path32[0];
     return [CIRCULAR_REF, circularProp].filter(Boolean).join(":");
   }
   if (refs.has(obj)) return refs.get(obj);
@@ -4651,7 +4775,7 @@ var handleCircularRefs = (obj, currentPath = /* @__PURE__ */ new WeakSet(), refs
     value,
     currentPath,
     refs,
-    [...path31, key],
+    [...path32, key],
     currentRefPaths
   );
   const result = Array.isArray(obj) ? obj.map((item, i) => recurse(item, i.toString())) : Object.fromEntries(
@@ -4689,7 +4813,7 @@ var resolveExtensions = (obj) => Object.fromEntries(
 var getAllTags = (schema2) => {
   const rootTags = schema2.tags ?? [];
   const operations = Object.values(schema2.paths ?? {}).flatMap(
-    (path31) => HttpMethods.map((k) => path31?.[k]).filter((op) => op != null)
+    (path32) => HttpMethods.map((k) => path32?.[k]).filter((op) => op != null)
   );
   const operationTags = new Set(operations.flatMap((op) => op.tags ?? []));
   const hasUntaggedOperations = operations.some(
@@ -4744,7 +4868,7 @@ var getAllSlugs = (ops, schemaTags = []) => {
 var getOperationSlugKey = (op) => [op.path, op.method, op.operationId, op.summary].filter(Boolean).join("-");
 var getAllOperations = (paths) => {
   const operations = Object.entries(paths ?? {}).flatMap(
-    ([path31, value]) => HttpMethods.flatMap((method) => {
+    ([path32, value]) => HttpMethods.flatMap((method) => {
       if (!value?.[method]) return [];
       const operation = value[method];
       const pathParameters = value.parameters ?? [];
@@ -4764,7 +4888,7 @@ var getAllOperations = (paths) => {
       return {
         ...operation,
         method,
-        path: path31,
+        path: path32,
         parameters,
         servers,
         tags: operation.tags ?? []
@@ -5267,8 +5391,8 @@ var Schema = builder.objectRef("Schema").implement({
     }),
     paths: t.field({
       type: [PathItem],
-      resolve: (root) => Object.entries(root.paths ?? {}).map(([path31, value]) => ({
-        path: path31,
+      resolve: (root) => Object.entries(root.paths ?? {}).map(([path32, value]) => ({
+        path: path32,
         // biome-ignore lint/style/noNonNullAssertion: value is guaranteed to be defined
         methods: Object.keys(value)
       }))
@@ -5398,9 +5522,97 @@ var countMcpServers = (schema2) => operationsOf(schema2).filter(
 // src/lib/util/ensureArray.ts
 var ensureArray = (value) => Array.isArray(value) ? value : [value];
 
-// src/vite/api/SchemaManager.ts
+// src/vite/api/openapi-publication.ts
 import fs from "node:fs/promises";
 import path8 from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+var getExtension = (urlPath) => path8.posix.extname(urlPath).toLowerCase();
+var getOpenApiMediaType = (urlPath) => getExtension(urlPath) === ".json" ? "application/json" : "application/yaml";
+var createOpenApiPublication = ({
+  apiPath,
+  urlPath,
+  schema: schema2
+}) => {
+  const mediaType = getOpenApiMediaType(urlPath);
+  const content = mediaType === "application/json" ? `${JSON.stringify(schema2, null, 2)}
+` : stringifyYaml(schema2);
+  return { apiPath, urlPath, content, mediaType };
+};
+var getRequestPathname = (requestUrl) => {
+  try {
+    return new URL(requestUrl, "http://zudoku.local").pathname;
+  } catch {
+    return void 0;
+  }
+};
+var findOpenApiPublication = (requestUrl, publications) => {
+  const pathname = getRequestPathname(requestUrl);
+  return publications.find((publication) => publication.urlPath === pathname);
+};
+var createOpenApiDevMiddleware = ({
+  getPublications,
+  getDownloadPathMap
+}) => async (req, res, next) => {
+  if (!req.url || req.method !== "GET" && req.method !== "HEAD") {
+    return next();
+  }
+  const publication = findOpenApiPublication(req.url, getPublications());
+  if (publication) {
+    res.setHeader("Content-Type", `${publication.mediaType}; charset=utf-8`);
+    return res.end(req.method === "HEAD" ? void 0 : publication.content);
+  }
+  const requestPathname = getRequestPathname(req.url);
+  if (!requestPathname) return next();
+  if (!requestPathname.toLowerCase().endsWith(".json") && !requestPathname.toLowerCase().endsWith(".yaml") && !requestPathname.toLowerCase().endsWith(".yml")) {
+    return next();
+  }
+  const inputPath = getDownloadPathMap().get(requestPathname);
+  if (!inputPath) return next();
+  const content = await fs.readFile(inputPath, "utf-8");
+  const mediaType = getOpenApiMediaType(inputPath);
+  res.setHeader("Content-Type", `${mediaType}; charset=utf-8`);
+  return res.end(req.method === "HEAD" ? void 0 : content);
+};
+var resolveOutputPath = (outputDir, urlPath) => {
+  const outputRoot = path8.resolve(outputDir);
+  const relativePath = urlPath.replace(/^\/+/, "");
+  const outputPath = path8.resolve(outputRoot, relativePath);
+  if (!relativePath || relativePath.includes("\\") || relativePath.split("/").some((segment) => segment === "..") || !outputPath.startsWith(`${outputRoot}${path8.sep}`) && outputPath !== outputRoot) {
+    throw new Error(`Unsafe OpenAPI publication output path: ${urlPath}`);
+  }
+  return outputPath;
+};
+var writeOpenApiPublications = async (outputDir, publications) => {
+  const outputs = publications.map((publication) => ({
+    publication,
+    outputPath: resolveOutputPath(outputDir, publication.urlPath)
+  }));
+  await Promise.all(
+    outputs.map(async ({ publication, outputPath }) => {
+      try {
+        await fs.lstat(outputPath);
+      } catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+          return;
+        }
+        throw error;
+      }
+      throw new Error(
+        `Cannot publish OpenAPI for API "${publication.apiPath}" at "${publication.urlPath}" because a build artifact already exists at "${outputPath}". Choose another publish.path or remove the conflicting public/build artifact.`
+      );
+    })
+  );
+  await Promise.all(
+    outputs.map(async ({ publication, outputPath }) => {
+      await fs.mkdir(path8.dirname(outputPath), { recursive: true });
+      await fs.writeFile(outputPath, publication.content, "utf-8");
+    })
+  );
+};
+
+// src/vite/api/SchemaManager.ts
+import fs2 from "node:fs/promises";
+import path9 from "node:path";
 import { $RefParser as $RefParser2 } from "@apidevtools/json-schema-ref-parser";
 import { upgrade } from "@scalar/openapi-parser";
 import { deepEqual } from "fast-equals";
@@ -5448,9 +5660,179 @@ var flattenAllOfProcessor = async ({ schema: schema2, file }) => {
 // src/vite/api/SchemaManager.ts
 init_joinUrl();
 
+// src/vite/api/agent-quality.ts
+var HTTP_METHODS2 = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace"
+];
+var REQUEST_BODY_METHODS = /* @__PURE__ */ new Set(["post", "put", "patch"]);
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var resolveLocalRef2 = (document, value) => {
+  if (!isObject(value) || typeof value.$ref !== "string") return value;
+  if (!value.$ref.startsWith("#/")) return void 0;
+  return value.$ref.slice(2).split("/").map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~")).reduce((current, part) => {
+    if (!isObject(current)) return void 0;
+    return current[part];
+  }, document);
+};
+var schemaIsTyped = (document, schema2) => {
+  const resolved = resolveLocalRef2(document, schema2);
+  if (typeof resolved === "boolean") return true;
+  if (!isObject(resolved)) return false;
+  return typeof resolved.type === "string" || Array.isArray(resolved.type) || "enum" in resolved || "const" in resolved || "properties" in resolved || "items" in resolved || "oneOf" in resolved || "anyOf" in resolved || "allOf" in resolved;
+};
+var contentHasTypedSchema = (document, content) => isObject(content) && Object.values(content).some(
+  (mediaType) => isObject(mediaType) && schemaIsTyped(document, mediaType.schema)
+);
+var parameterIsTyped = (document, parameter) => {
+  const resolved = resolveLocalRef2(document, parameter);
+  return isObject(resolved) && (schemaIsTyped(document, resolved.schema) || contentHasTypedSchema(document, resolved.content));
+};
+var responseHasTypedSchema = (document, response) => {
+  const resolved = resolveLocalRef2(document, response);
+  return isObject(resolved) && contentHasTypedSchema(document, resolved.content);
+};
+var requestBodyHasTypedSchema = (document, requestBody) => {
+  const resolved = resolveLocalRef2(document, requestBody);
+  return isObject(resolved) && contentHasTypedSchema(document, resolved.content);
+};
+var getParameterName = (document, parameter) => {
+  const resolved = resolveLocalRef2(document, parameter);
+  return isObject(resolved) && typeof resolved.name === "string" ? resolved.name : "<unknown>";
+};
+var getParameterIdentity = (document, parameter) => {
+  const resolved = resolveLocalRef2(document, parameter);
+  if (!isObject(resolved) || typeof resolved.name !== "string" || typeof resolved.in !== "string") {
+    return void 0;
+  }
+  return JSON.stringify([resolved.name, resolved.in]);
+};
+var mergeParameters = (document, pathParameters, operationParameters) => {
+  const merged = [];
+  const indexes = /* @__PURE__ */ new Map();
+  for (const parameter of [
+    ...Array.isArray(pathParameters) ? pathParameters : [],
+    ...Array.isArray(operationParameters) ? operationParameters : []
+  ]) {
+    const identity = getParameterIdentity(document, parameter);
+    if (identity === void 0) {
+      merged.push(parameter);
+      continue;
+    }
+    const existingIndex = indexes.get(identity);
+    if (existingIndex === void 0) {
+      indexes.set(identity, merged.length);
+      merged.push(parameter);
+    } else {
+      merged[existingIndex] = parameter;
+    }
+  }
+  return merged;
+};
+var responseCannotHaveContent = (method, status) => method === "head" || /^1(?:\d{2}|xx)$/i.test(status) || ["204", "205", "304"].includes(status);
+var auditOpenApiAgentQuality = (document) => {
+  const issues = [];
+  const operationIds = /* @__PURE__ */ new Map();
+  if (!isObject(document.paths)) return issues;
+  for (const [route, rawPathItem] of Object.entries(document.paths)) {
+    const pathItem = resolveLocalRef2(document, rawPathItem);
+    if (!isObject(pathItem)) continue;
+    for (const method of HTTP_METHODS2) {
+      const operation = pathItem[method];
+      if (!isObject(operation)) continue;
+      const location = `${method.toUpperCase()} ${route}`;
+      if (typeof operation.operationId !== "string" || operation.operationId.trim().length === 0) {
+        issues.push({
+          code: "missing-operation-id",
+          location,
+          message: "Operation is missing a unique operationId."
+        });
+      } else {
+        const locations = operationIds.get(operation.operationId) ?? [];
+        locations.push(location);
+        operationIds.set(operation.operationId, locations);
+      }
+      if (typeof operation.description !== "string" || operation.description.trim().length === 0) {
+        issues.push({
+          code: "missing-description",
+          location,
+          message: "Operation is missing a description."
+        });
+      }
+      const parameters = mergeParameters(
+        document,
+        pathItem.parameters,
+        operation.parameters
+      );
+      for (const parameter of parameters) {
+        if (parameterIsTyped(document, parameter)) continue;
+        issues.push({
+          code: "untyped-parameter",
+          location,
+          message: `Parameter "${getParameterName(document, parameter)}" is missing a typed schema.`
+        });
+      }
+      if (operation.requestBody === void 0) {
+        if (REQUEST_BODY_METHODS.has(method)) {
+          issues.push({
+            code: "missing-request-body",
+            location,
+            message: "Write operation is missing a requestBody schema."
+          });
+        }
+      } else if (!requestBodyHasTypedSchema(document, operation.requestBody)) {
+        issues.push({
+          code: "untyped-request-body",
+          location,
+          message: "Request body is missing a typed schema."
+        });
+      }
+      const responses = operation.responses;
+      if (!isObject(responses) || Object.keys(responses).length === 0) {
+        issues.push({
+          code: "missing-response-schema",
+          location,
+          message: "Operation has no response schemas."
+        });
+        continue;
+      }
+      for (const [status, response] of Object.entries(responses)) {
+        if (responseCannotHaveContent(method, status)) continue;
+        if (responseHasTypedSchema(document, response)) continue;
+        issues.push({
+          code: "missing-response-schema",
+          location,
+          message: `Response ${status} is missing a typed schema.`
+        });
+      }
+    }
+  }
+  for (const [operationId, locations] of operationIds) {
+    if (locations.length < 2) continue;
+    issues.push({
+      code: "duplicate-operation-id",
+      location: locations.join(", "),
+      message: `operationId "${operationId}" is used by multiple operations.`
+    });
+  }
+  return issues;
+};
+var formatAgentQualityReport = (apiPath, issues) => [
+  `Agent-quality audit for API "${apiPath}" found ${issues.length} issue${issues.length === 1 ? "" : "s"}:`,
+  ...issues.map(
+    (issue) => `- [${issue.code}] ${issue.location}: ${issue.message}`
+  )
+].join("\n");
+
 // src/vite/api/schema-codegen.ts
 var unescapeJsonPointer = (uri) => decodeURIComponent(uri.replace(/~1/g, "/").replace(/~0/g, "~"));
-var getSegmentsFromPath = (path31) => path31.split("/").slice(1).map(unescapeJsonPointer);
+var getSegmentsFromPath = (path32) => path32.split("/").slice(1).map(unescapeJsonPointer);
 var createLocalRefMap = (obj) => {
   const refMap = /* @__PURE__ */ new Map();
   const siblingsMap = /* @__PURE__ */ new Map();
@@ -5481,16 +5863,16 @@ var replaceMarkers = (code, mergedRefs) => code.replace(/"__refMap:(.*?)"/g, '__
   /"__refMap\+Siblings:(.*?)"/g,
   (_, key) => mergedRefs.get(key) ?? `__refMap["${key}"]`
 );
-var lookup = (schema2, path31, filePath) => {
-  const parts = getSegmentsFromPath(path31);
+var lookup = (schema2, path32, filePath) => {
+  const parts = getSegmentsFromPath(path32);
   let val = schema2;
   for (const part of parts) {
     while (val.$ref?.startsWith("#/")) {
-      val = val.$ref === path31 ? val : lookup(schema2, val.$ref, filePath);
+      val = val.$ref === path32 ? val : lookup(schema2, val.$ref, filePath);
     }
     if (val[part] === void 0) {
       throw new Error(
-        `Error in ${filePath ?? "code generation"}: Could not find path segment ${part} in path: ${path31}`
+        `Error in ${filePath ?? "code generation"}: Could not find path segment ${part} in path: ${path32}`
       );
     }
     val = val[part];
@@ -5573,6 +5955,7 @@ var SchemaManager = class {
   processors;
   processedSchemas = {};
   referencedBy = /* @__PURE__ */ new Map();
+  publishedSchemas;
   config;
   constructor({
     storeDir,
@@ -5594,18 +5977,18 @@ var SchemaManager = class {
     ];
   }
   getPathForFile = (input, params) => {
-    const filePath = path8.resolve(this.config.__meta.rootDir, input);
+    const filePath = path9.resolve(this.config.__meta.rootDir, input);
     const apis = ensureArray(this.config.apis ?? []);
     for (const apiConfig of apis) {
-      if (!apiConfig || apiConfig.type !== "file" || !apiConfig.path) continue;
+      if (apiConfig?.type !== "file" || !apiConfig.path) continue;
       const match = normalizeInputs(apiConfig.input).some(
-        (i) => path8.resolve(this.config.__meta.rootDir, i.input) === filePath && deepEqual(i.params, params)
+        (i) => path9.resolve(this.config.__meta.rootDir, i.input) === filePath && deepEqual(i.params, params)
       );
       if (match) return apiConfig.path;
     }
   };
   processSchema = async (input) => {
-    const filePath = path8.resolve(this.config.__meta.rootDir, input.input);
+    const filePath = path9.resolve(this.config.__meta.rootDir, input.input);
     const params = input.params;
     const configuredPath = this.getPathForFile(input.input, params);
     if (!configuredPath) {
@@ -5640,15 +6023,15 @@ var SchemaManager = class {
     const processedTime = Date.now();
     const code = generateCode(processedSchema, filePath);
     const prefixPath = slugify(configuredPath);
-    const processedFilePath = path8.posix.join(
+    const processedFilePath = path9.posix.join(
       this.storeDir,
-      `${prefixPath}-${path8.basename(filePath)}${paramsSuffix(params)}.js`
+      `${prefixPath}-${path9.basename(filePath)}${paramsSuffix(params)}.js`
     );
     const importKey = processedFilePath;
-    await fs.writeFile(processedFilePath, code);
+    await fs2.writeFile(processedFilePath, code);
     const processedJsonPath = paramsSuffix(params) ? processedFilePath.replace(/\.js$/, ".json") : "";
     if (processedJsonPath) {
-      await fs.writeFile(
+      await fs2.writeFile(
         processedJsonPath,
         JSON.stringify(processedSchema, null, 2)
       );
@@ -5664,7 +6047,7 @@ var SchemaManager = class {
     const schemaVersion = processedSchema.info.version ?? FALLBACK_VERSION;
     const versionPath = existingSchema?.path && existingSchema.path.length > 0 ? existingSchema.path : paramsPath(params) || schemaVersion;
     const config = ensureArray(this.config.apis ?? []).find(
-      (c) => c.path === configuredPath
+      (c) => c.type === "file" && c.path === configuredPath
     );
     const processed = {
       schema: processedSchema,
@@ -5686,16 +6069,25 @@ var SchemaManager = class {
     };
     if (index > -1) {
       schemas[index] = processed;
+      this.publishedSchemas = void 0;
     } else {
       throw new Error(
         `Schema with input path ${filePath} was not pre-initialized for ${configuredPath}.`
       );
     }
+    if (index === 0 && config?.type === "file" && config.publish?.agentQuality) {
+      const issues = auditOpenApiAgentQuality(processedSchema);
+      if (issues.length > 0) {
+        console.warn(
+          `[zudoku] ${formatAgentQualityReport(configuredPath, issues)}`
+        );
+      }
+    }
     return processed;
   };
   getAllTrackedFiles = () => Array.from(this.referencedBy.keys());
   getFilesToReprocess = (changedFile) => {
-    const resolvedPath = path8.resolve(this.config.__meta.rootDir, changedFile);
+    const resolvedPath = path9.resolve(this.config.__meta.rootDir, changedFile);
     const referencedBy = this.referencedBy.get(resolvedPath);
     if (!referencedBy) return [];
     const filesToProcess = referencedBy.size === 0 ? [resolvedPath] : Array.from(referencedBy);
@@ -5714,6 +6106,7 @@ var SchemaManager = class {
   processAllSchemas = async () => {
     this.referencedBy.clear();
     this.processedSchemas = {};
+    this.publishedSchemas = void 0;
     const apis = ensureArray(this.config.apis ?? []);
     for (const apiConfig of apis) {
       if (apiConfig.type !== "file" || !apiConfig.path) continue;
@@ -5724,7 +6117,7 @@ var SchemaManager = class {
         version: "",
         path: input.path ?? "",
         label: input.label,
-        inputPath: path8.resolve(this.config.__meta.rootDir, input.input),
+        inputPath: path9.resolve(this.config.__meta.rootDir, input.input),
         params: input.params,
         importKey: "",
         downloadUrl: "",
@@ -5743,10 +6136,39 @@ var SchemaManager = class {
         );
       }
     }
+    this.getPublishedSchemas();
   };
-  getLatestSchema = (path31) => this.processedSchemas[path31]?.at(0);
-  getSchemasForPath = (path31) => this.processedSchemas[path31];
+  getLatestSchema = (path32) => this.processedSchemas[path32]?.at(0);
+  getSchemasForPath = (path32) => this.processedSchemas[path32];
   getSchemaImports = () => Object.values(this.processedSchemas).flat().filter((s) => s.importKey);
+  getPublishedSchemas = () => {
+    if (this.publishedSchemas) return this.publishedSchemas;
+    const publications = /* @__PURE__ */ new Map();
+    for (const apiConfig of ensureArray(this.config.apis ?? [])) {
+      if (apiConfig.type !== "file" || !apiConfig.path || !apiConfig.publish) {
+        continue;
+      }
+      const primarySchema = this.getLatestSchema(apiConfig.path);
+      if (!primarySchema) continue;
+      const urlPath = joinUrl(this.config.basePath, apiConfig.publish.path);
+      const existing = publications.get(urlPath);
+      if (existing) {
+        throw new Error(
+          `OpenAPI publication path "${urlPath}" is configured by both "${existing.apiPath}" and "${apiConfig.path}". Configure a unique path for each published API.`
+        );
+      }
+      publications.set(
+        urlPath,
+        createOpenApiPublication({
+          apiPath: apiConfig.path,
+          urlPath,
+          schema: primarySchema.schema
+        })
+      );
+    }
+    this.publishedSchemas = Array.from(publications.values());
+    return this.publishedSchemas;
+  };
   getUrlToFilePathMap = () => {
     const map = /* @__PURE__ */ new Map();
     const apis = ensureArray(this.config.apis ?? []);
@@ -5767,7 +6189,7 @@ var SchemaManager = class {
   };
   createSchemaPath = (inputPath, versionPath, apiPath, params, config) => {
     const suffix = paramsSuffix(params);
-    const extension = suffix ? ".json" : path8.extname(inputPath);
+    const extension = suffix ? ".json" : path9.extname(inputPath);
     const fileName = config?.schemaDownload?.fileName ?? this.config.defaults?.apis?.schemaDownload?.fileName ?? "schema";
     return joinUrl(
       this.config.basePath,
@@ -5779,7 +6201,7 @@ var SchemaManager = class {
 };
 
 // src/vite/plugin-config-reload.ts
-import path11 from "node:path";
+import path12 from "node:path";
 import colors3 from "picocolors";
 
 // src/vite/plugin-navigation.ts
@@ -5787,7 +6209,7 @@ import { stringify as stringify3 } from "javascript-stringify";
 import { isElement } from "react-is";
 
 // src/config/validators/NavigationSchema.ts
-import path9 from "node:path";
+import path10 from "node:path";
 import { glob } from "glob";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { mdxFromMarkdown } from "mdast-util-mdx";
@@ -5837,7 +6259,7 @@ var extractRichH1 = (content) => {
   }
 };
 var isNavigationItem = (item) => item !== void 0;
-var toPosixPath = (filePath) => filePath.split(path9.win32.sep).join(path9.posix.sep);
+var toPosixPath = (filePath) => filePath.split(path10.win32.sep).join(path10.posix.sep);
 var NavigationResolver = class {
   rootDir;
   globPatterns;
@@ -5970,13 +6392,13 @@ var NavigationResolver = class {
 
 // src/vite/debug.ts
 import { mkdir, writeFile } from "node:fs/promises";
-import path10 from "node:path";
+import path11 from "node:path";
 async function writePluginDebugCode(rootDir, pluginName, code, extension = "js") {
   if (process.env.ZUDOKU_BUILD_DEBUG) {
-    const debugDir = path10.join(rootDir, "dist", "debug");
+    const debugDir = path11.join(rootDir, "dist", "debug");
     await mkdir(debugDir, { recursive: true });
     await writeFile(
-      path10.join(debugDir, `${pluginName}.${extension}`),
+      path11.join(debugDir, `${pluginName}.${extension}`),
       typeof code === "string" ? code : code.join("\n")
     );
   }
@@ -6087,7 +6509,7 @@ var viteConfigReloadPlugin = () => ({
       });
       logger.info(
         colors3.blue(
-          `Config ${path11.basename(currentConfig.__meta.configPath)} changed. Reloading...`
+          `Config ${path12.basename(currentConfig.__meta.configPath)} changed. Reloading...`
         ),
         { timestamp: true }
       );
@@ -6097,6 +6519,7 @@ var viteConfigReloadPlugin = () => ({
 
 // src/vite/plugin-api.ts
 var PROCESSED_STORE_SUBPATH = "node_modules/.zudoku/processed";
+var schemaConfigurationChanged = (current, next) => current.basePath !== next.basePath || !deepEqual2(current.apis, next.apis);
 var warn = (message) => {
   console.warn(`[zudoku] ${message}`);
 };
@@ -6121,11 +6544,11 @@ var viteApiPlugin = async () => {
   const resolvedVirtualModuleId4 = `\0${virtualModuleId4}`;
   const initialConfig = getCurrentConfig();
   const zuploProcessors = ZuploEnv.isZuplo ? await runnerImport3(
-    path12.resolve(getZudokuRootDir(), "src/zuplo/with-zuplo-processors.ts")
+    path13.resolve(getZudokuRootDir(), "src/zuplo/with-zuplo-processors.ts")
   ).then((m) => m.module.default(initialConfig.__meta.rootDir)) : [];
   const buildConfig = await getBuildConfig();
   const buildProcessors = buildConfig?.processors ?? [];
-  const tmpStoreDir = path12.posix.join(
+  const tmpStoreDir = path13.posix.join(
     initialConfig.__meta.rootDir,
     PROCESSED_STORE_SUBPATH
   );
@@ -6135,8 +6558,8 @@ var viteApiPlugin = async () => {
     config: initialConfig,
     processors
   });
-  await fs2.rm(tmpStoreDir, { recursive: true, force: true });
-  await fs2.mkdir(tmpStoreDir, { recursive: true });
+  await fs3.rm(tmpStoreDir, { recursive: true, force: true });
+  await fs3.mkdir(tmpStoreDir, { recursive: true });
   await schemaManager.processAllSchemas();
   return {
     name: "zudoku-api-plugins",
@@ -6144,19 +6567,12 @@ var viteApiPlugin = async () => {
       schemaManager.getAllTrackedFiles().forEach((file) => this.addWatchFile(file));
     },
     configureServer(server) {
-      server.middlewares.use(async (req, res, next) => {
-        if (req.method !== "GET" || !req.url) return next();
-        if (!req.url.toLowerCase().endsWith(".json") && !req.url.toLowerCase().endsWith(".yaml")) {
-          return next();
-        }
-        const pathMap = schemaManager.getUrlToFilePathMap();
-        const inputPath = pathMap.get(req.url);
-        if (!inputPath) return next();
-        const content = await fs2.readFile(inputPath, "utf-8");
-        const mimeType = path12.extname(inputPath).toLowerCase() === ".json" ? "application/json" : "application/x-yaml";
-        res.setHeader("Content-Type", `${mimeType}; charset=utf-8`);
-        return res.end(content);
-      });
+      server.middlewares.use(
+        createOpenApiDevMiddleware({
+          getPublications: () => schemaManager.getPublishedSchemas(),
+          getDownloadPathMap: () => schemaManager.getUrlToFilePathMap()
+        })
+      );
       server.watcher.on("change", async (id) => {
         const mainFiles = schemaManager.getFilesToReprocess(id);
         if (mainFiles.length === 0) return;
@@ -6193,7 +6609,7 @@ var viteApiPlugin = async () => {
     async load(id) {
       if (id !== resolvedVirtualModuleId4) return;
       const config = getCurrentConfig();
-      if (!deepEqual2(schemaManager.config.apis, config.apis)) {
+      if (schemaConfigurationChanged(schemaManager.config, config)) {
         schemaManager.config = config;
         await schemaManager.processAllSchemas();
         schemaManager.getAllTrackedFiles().forEach((file) => this.addWatchFile(file));
@@ -6382,11 +6798,15 @@ var viteApiPlugin = async () => {
       const pathMap = schemaManager.getUrlToFilePathMap();
       if (process.env.NODE_ENV !== "production") return;
       for (const [urlPath, inputPath] of pathMap) {
-        const content = await fs2.readFile(inputPath, "utf-8");
-        const outputPath = path12.join(config.__meta.rootDir, "dist", urlPath);
-        await fs2.mkdir(path12.dirname(outputPath), { recursive: true });
-        await fs2.writeFile(outputPath, content, "utf-8");
+        const content = await fs3.readFile(inputPath, "utf-8");
+        const outputPath = path13.join(config.__meta.rootDir, "dist", urlPath);
+        await fs3.mkdir(path13.dirname(outputPath), { recursive: true });
+        await fs3.writeFile(outputPath, content, "utf-8");
       }
+      await writeOpenApiPublications(
+        path13.join(config.__meta.rootDir, "dist"),
+        schemaManager.getPublishedSchemas()
+      );
     }
   };
 };
@@ -6549,7 +6969,7 @@ var viteDocMetadataPlugin = () => ({
 });
 
 // src/vite/plugin-docs.ts
-import path13 from "node:path";
+import path14 from "node:path";
 import { glob as glob3 } from "glob";
 import globParent from "glob-parent";
 
@@ -6616,7 +7036,7 @@ var globMarkdownFiles = async (config, options = { absolute: false }) => {
     if (process.env.NODE_ENV !== "development") {
       const draftStatuses = await Promise.all(
         globbedFiles.map(async (file) => {
-          const absolutePath = path13.resolve(config.__meta.rootDir, file);
+          const absolutePath = path14.resolve(config.__meta.rootDir, file);
           const { data } = await readFrontmatter(absolutePath);
           return { file, isDraft: data.draft === true };
         })
@@ -6629,9 +7049,9 @@ var globMarkdownFiles = async (config, options = { absolute: false }) => {
       if (draftFiles.has(file)) {
         continue;
       }
-      const relativePath = path13.posix.relative(parent, file);
+      const relativePath = path14.posix.relative(parent, file);
       const routePath = ensureLeadingSlash(relativePath.replace(/\.mdx?$/, ""));
-      const filePath = options.absolute ? path13.resolve(config.__meta.rootDir, file) : file;
+      const filePath = options.absolute ? path14.resolve(config.__meta.rootDir, file) : file;
       fileMapping[routePath] = filePath;
     }
   }
@@ -6715,8 +7135,168 @@ var plugin_docs_default = viteDocsPlugin;
 
 // src/vite/plugin-markdown-export.ts
 import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
-import path14 from "node:path";
+import path15 from "node:path";
+
+// src/lib/util/contentNegotiation.ts
+var representations = [
+  {
+    contentType: "text/html",
+    type: "text",
+    subtype: "html",
+    parameters: { charset: "utf-8" },
+    serverOrder: 0
+  },
+  {
+    contentType: "text/markdown",
+    type: "text",
+    subtype: "markdown",
+    parameters: { charset: "utf-8" },
+    serverOrder: 1
+  }
+];
+var tokenPattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+var mediaRangePattern = /^([!#$%&'*+\-.^_`|~0-9A-Za-z]+|\*)\/([!#$%&'*+\-.^_`|~0-9A-Za-z]+|\*)$/;
+var qualityPattern = /^(?:0(?:\.[0-9]{0,3})?|1(?:\.0{0,3})?)$/;
+var splitOutsideQuotes = (value, delimiter) => {
+  const parts = [];
+  let start = 0;
+  let quoted = false;
+  let escaped = false;
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (quoted && character === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (character === '"') {
+      quoted = !quoted;
+      continue;
+    }
+    if (!quoted && character === delimiter) {
+      parts.push(value.slice(start, index));
+      start = index + 1;
+    }
+  }
+  parts.push(value.slice(start));
+  return parts;
+};
+var parseParameterValue = (value) => {
+  const trimmedValue = value.trim();
+  if (tokenPattern.test(trimmedValue)) {
+    return trimmedValue.toLowerCase();
+  }
+  if (!trimmedValue.startsWith('"') || !trimmedValue.endsWith('"')) {
+    return void 0;
+  }
+  const innerValue = trimmedValue.slice(1, -1);
+  return innerValue.replace(/\\(.)/g, "$1").toLowerCase();
+};
+var parseMediaRange = (value, order) => {
+  const [rawMediaRange, ...rawParameters] = splitOutsideQuotes(value, ";");
+  const mediaRangeMatch = rawMediaRange?.trim().toLowerCase().match(mediaRangePattern);
+  if (!mediaRangeMatch) {
+    return void 0;
+  }
+  const [, type, subtype] = mediaRangeMatch;
+  if (!type || !subtype || type === "*" && subtype !== "*") {
+    return void 0;
+  }
+  const parameters = /* @__PURE__ */ new Map();
+  let quality = 1;
+  let foundQuality = false;
+  for (const rawParameter of rawParameters) {
+    const separatorIndex = rawParameter.indexOf("=");
+    if (separatorIndex === -1) {
+      return void 0;
+    }
+    const name = rawParameter.slice(0, separatorIndex).trim().toLowerCase();
+    const rawValue = rawParameter.slice(separatorIndex + 1).trim();
+    if (!tokenPattern.test(name)) {
+      return void 0;
+    }
+    if (name === "q") {
+      if (foundQuality || !qualityPattern.test(rawValue)) {
+        return void 0;
+      }
+      quality = Number(rawValue);
+      foundQuality = true;
+      continue;
+    }
+    const parameterValue = parseParameterValue(rawValue);
+    if (parameterValue === void 0 || parameters.has(name)) {
+      return void 0;
+    }
+    parameters.set(name, parameterValue);
+  }
+  return { type, subtype, parameters, quality, order };
+};
+var getSpecificity = (range) => {
+  if (range.type === "*") {
+    return 0;
+  }
+  if (range.subtype === "*") {
+    return 1;
+  }
+  return 2;
+};
+var matchesRepresentation = (range, representation) => {
+  if (range.type !== "*" && range.type !== representation.type) {
+    return false;
+  }
+  if (range.subtype !== "*" && range.subtype !== representation.subtype) {
+    return false;
+  }
+  return [...range.parameters].every(
+    ([name, value]) => representation.parameters[name]?.toLowerCase() === value
+  );
+};
+var compareRangeMatches = (left, right) => right.specificity - left.specificity || right.parameterCount - left.parameterCount || right.quality - left.quality || left.rangeOrder - right.rangeOrder;
+var getRepresentationMatch = (ranges, representation) => ranges.filter((range) => matchesRepresentation(range, representation)).map((range) => ({
+  contentType: representation.contentType,
+  quality: range.quality,
+  specificity: getSpecificity(range),
+  parameterCount: range.parameters.size,
+  rangeOrder: range.order,
+  serverOrder: representation.serverOrder
+})).sort(compareRangeMatches)[0];
+var compareRepresentations = (left, right) => right.quality - left.quality || right.specificity - left.specificity || right.parameterCount - left.parameterCount || left.rangeOrder - right.rangeOrder || left.serverOrder - right.serverOrder;
+var negotiateContentType = (acceptHeader) => {
+  if (!acceptHeader?.trim()) {
+    return "text/html";
+  }
+  const ranges = splitOutsideQuotes(acceptHeader, ",").map((value, order) => parseMediaRange(value.trim(), order)).filter((range) => range !== void 0);
+  const match = representations.map((representation) => getRepresentationMatch(ranges, representation)).filter((result) => result !== void 0).filter((result) => result.quality > 0).sort(compareRepresentations)[0];
+  return match?.contentType ?? null;
+};
+var addAcceptToVary = (varyHeader) => {
+  const fields = (varyHeader ?? "").split(",").map((field) => field.trim()).filter(Boolean);
+  if (fields.some((field) => field === "*")) {
+    return "*";
+  }
+  const seenFields = /* @__PURE__ */ new Set();
+  const uniqueFields = fields.filter((field) => {
+    const normalizedField = field.toLowerCase();
+    if (seenFields.has(normalizedField)) {
+      return false;
+    }
+    seenFields.add(normalizedField);
+    return true;
+  });
+  if (!seenFields.has("accept")) {
+    uniqueFields.push("Accept");
+  }
+  return uniqueFields.join(", ");
+};
+
+// src/vite/plugin-markdown-export.ts
 init_joinUrl();
+init_markdown_representation();
+var MARKDOWN_FILES_MODULE_ID = "virtual:zudoku-markdown-files";
+var RESOLVED_MARKDOWN_FILES_MODULE_ID = `\0${MARKDOWN_FILES_MODULE_ID}`;
 var processMarkdownFile = async (filePath) => {
   const { content: markdownContent, data: frontmatter } = await readFrontmatter(filePath);
   let finalMarkdown = markdownContent;
@@ -6732,19 +7312,97 @@ ${markdownContent}`;
 };
 var getMarkdownOutputPath = (distDir, routePath) => {
   const segments = routePath === "/" ? ["index"] : routePath.split("/").filter(Boolean);
-  return `${path14.join(distDir, ...segments)}.md`;
+  return `${path15.join(distDir, ...segments)}.md`;
 };
-var resolveMarkdownRoutePath = (requestUrl, basePath) => {
-  const pathname = requestUrl.split(/[?#]/)[0] ?? requestUrl;
-  const routePath = joinUrl(
-    pathname.slice(basePath.length).replace(/\.mdx?$/, "")
+var writeMarkdownInfo = async (markdownInfoPath, markdownFileInfos) => {
+  await mkdir2(path15.dirname(markdownInfoPath), { recursive: true });
+  await writeFile2(
+    markdownInfoPath,
+    JSON.stringify(markdownFileInfos, null, 2),
+    "utf-8"
   );
+};
+var resolveMarkdownRoutePath = (requestUrl, basePath) => {
+  const pathname = requestUrl.split(/[?#]/)[0]?.replace(/\.mdx?$/, "");
+  if (!pathname) return;
+  const routePath = resolveDocumentationRoutePath(pathname, basePath);
+  if (!routePath) return;
   if (routePath === "/index") {
     return "/";
   }
   return routePath;
 };
 var needsMdFiles = (config) => config.docs.publishMarkdown || config.docs.llms.llmsTxt || config.docs.llms.llmsTxtFull;
+var isContentNegotiationEnabled = (config) => config.docs.publishMarkdown && config.docs.contentNegotiation;
+var resolveMarkdownFiles = async (config) => {
+  const files = await resolveCustomNavigationPaths(
+    config,
+    await globMarkdownFiles(config, { absolute: true })
+  );
+  if (config.docs.llms.includeProtected || !config.protectedRoutes) {
+    return files;
+  }
+  const patterns = Object.keys(config.protectedRoutes);
+  return Object.fromEntries(
+    Object.entries(files).filter(
+      ([routePath]) => !matchesAnyProtectedPattern(patterns, routePath)
+    )
+  );
+};
+var loadMarkdownContents = async (markdownFiles) => Object.fromEntries(
+  await Promise.all(
+    Object.entries(markdownFiles).map(async ([routePath, filePath]) => [
+      encodeDocumentationRoutePath(routePath),
+      (await processMarkdownFile(filePath)).content
+    ])
+  )
+);
+var createMarkdownDevMiddleware = ({
+  config,
+  getMarkdownFiles
+}) => async (req, res, next) => {
+  if (!req.url || req.method !== "GET" && req.method !== "HEAD") {
+    return next();
+  }
+  const basePath = joinUrl(config.basePath);
+  const pathname = req.url.split(/[?#]/)[0] ?? req.url;
+  const isExplicitMarkdownRequest = pathname.endsWith(".md");
+  const routePath = isExplicitMarkdownRequest ? resolveMarkdownRoutePath(req.url, basePath) : resolveDocumentationRoutePath(req.url, basePath);
+  if (!routePath) return next();
+  const filePath = Object.entries(getMarkdownFiles()).find(
+    ([configuredRoutePath]) => encodeDocumentationRoutePath(configuredRoutePath) === routePath
+  )?.[1];
+  if (!filePath) return next();
+  if (!isExplicitMarkdownRequest && isContentNegotiationEnabled(config)) {
+    const negotiatedType = negotiateContentType(req.headers.accept);
+    res.setHeader("Vary", addAcceptToVary(res.getHeader("Vary")?.toString()));
+    res.setHeader(
+      "Link",
+      appendLinkHeader(
+        res.getHeader("Link"),
+        getMarkdownAlternateLink(routePath, config.basePath)
+      )
+    );
+    if (negotiatedType === null) {
+      res.statusCode = 406;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      return res.end(req.method === "HEAD" ? void 0 : "Not Acceptable");
+    }
+    if (negotiatedType === "text/html") {
+      return next();
+    }
+  } else if (!isExplicitMarkdownRequest) {
+    return next();
+  }
+  try {
+    const { content } = await processMarkdownFile(filePath);
+    res.setHeader("Content-Type", "text/markdown; charset=utf-8");
+    return res.end(req.method === "HEAD" ? void 0 : content);
+  } catch (error) {
+    console.warn(`Failed to serve markdown for ${routePath}:`, error);
+    return next();
+  }
+};
 var viteMarkdownExportPlugin = () => {
   let markdownFiles = {};
   let markdownFileInfos = [];
@@ -6753,58 +7411,40 @@ var viteMarkdownExportPlugin = () => {
     applyToEnvironment(env) {
       return env.name === "ssr";
     },
+    resolveId(id) {
+      if (id === MARKDOWN_FILES_MODULE_ID) {
+        return RESOLVED_MARKDOWN_FILES_MODULE_ID;
+      }
+    },
+    async load(id) {
+      if (id === RESOLVED_MARKDOWN_FILES_MODULE_ID) {
+        return `export default ${JSON.stringify(await loadMarkdownContents(markdownFiles))};`;
+      }
+    },
     async buildStart() {
       const config = getCurrentConfig();
       if (config.__meta.mode === "standalone" || !needsMdFiles(config)) {
         return;
       }
-      markdownFiles = await resolveCustomNavigationPaths(
-        config,
-        await globMarkdownFiles(config, { absolute: true })
-      );
-      if (!config.docs.llms.includeProtected) {
-        const protectedRoutes = config.protectedRoutes;
-        if (protectedRoutes) {
-          const patterns = Object.keys(protectedRoutes);
-          for (const routePath of Object.keys(markdownFiles)) {
-            if (matchesAnyProtectedPattern(patterns, routePath)) {
-              delete markdownFiles[routePath];
-            }
-          }
-        }
-      }
+      markdownFiles = await resolveMarkdownFiles(config);
     },
     async configureServer(server) {
       const config = getCurrentConfig();
       if (!needsMdFiles(config)) return;
-      markdownFiles = await resolveCustomNavigationPaths(
-        config,
-        await globMarkdownFiles(config, { absolute: true })
+      markdownFiles = await resolveMarkdownFiles(config);
+      server.middlewares.use(
+        createMarkdownDevMiddleware({
+          config,
+          getMarkdownFiles: () => markdownFiles
+        })
       );
-      server.middlewares.use(async (req, res, next) => {
-        if (req.method !== "GET" || !req.url?.endsWith(".md")) {
-          return next();
-        }
-        const basePath = joinUrl(config.basePath);
-        const routePath = resolveMarkdownRoutePath(req.url, basePath);
-        const filePath = markdownFiles[routePath];
-        if (!filePath) return next();
-        try {
-          const { content } = await processMarkdownFile(filePath);
-          res.setHeader("Content-Type", "text/markdown; charset=utf-8");
-          res.end(content);
-        } catch (error) {
-          console.warn(`Failed to serve markdown for ${routePath}:`, error);
-          return next();
-        }
-      });
     },
     async closeBundle() {
       const config = getCurrentConfig();
-      if (process.env.NODE_ENV !== "production" || Object.keys(markdownFiles).length === 0 || !needsMdFiles(config)) {
+      if (process.env.NODE_ENV !== "production" || !needsMdFiles(config)) {
         return;
       }
-      const distDir = path14.join(
+      const distDir = path15.join(
         config.__meta.rootDir,
         "dist",
         config.basePath ?? ""
@@ -6825,22 +7465,18 @@ var viteMarkdownExportPlugin = () => {
             content: finalMarkdown
           });
           const outputPath = getMarkdownOutputPath(distDir, routePath);
-          await mkdir2(path14.dirname(outputPath), { recursive: true });
+          await mkdir2(path15.dirname(outputPath), { recursive: true });
           await writeFile2(outputPath, finalMarkdown, "utf-8");
         } catch (error) {
           console.warn(`Failed to export markdown for ${routePath}:`, error);
         }
       }
-      if (config.docs.llms.llmsTxt || config.docs.llms.llmsTxtFull) {
-        const markdownInfoPath = path14.join(
+      if (config.docs.llms.llmsTxt || config.docs.llms.llmsTxtFull || isContentNegotiationEnabled(config)) {
+        const markdownInfoPath = path15.join(
           config.__meta.rootDir,
           "node_modules/.zudoku/markdown-info.json"
         );
-        await writeFile2(
-          markdownInfoPath,
-          JSON.stringify(markdownFileInfos, null, 2),
-          "utf-8"
-        );
+        await writeMarkdownInfo(markdownInfoPath, markdownFileInfos);
       }
     }
   };
@@ -6984,9 +7620,9 @@ var remarkCodeTabs = () => (tree) => {
 };
 
 // src/vite/mdx/remark-inject-filepath.ts
-import path15 from "node:path";
+import path16 from "node:path";
 var remarkInjectFilepath = (rootDir) => (tree, vfile) => {
-  const relativePath = path15.relative(rootDir, vfile.path).split(path15.sep).join(path15.posix.sep);
+  const relativePath = path16.relative(rootDir, vfile.path).split(path16.sep).join(path16.posix.sep);
   tree.children.unshift(exportMdxjsConst("__filepath", relativePath));
 };
 
@@ -7073,7 +7709,7 @@ var remarkLastModified = () => {
 };
 
 // src/vite/mdx/remark-link-rewrite.ts
-import path16 from "node:path";
+import path17 from "node:path";
 import { visit as visit5 } from "unist-util-visit";
 var markdownExtension = /\.mdx?$/;
 var resolveToRoute = (url, filePath, routesByFile) => {
@@ -7081,7 +7717,7 @@ var resolveToRoute = (url, filePath, routesByFile) => {
   if (!markdownExtension.test(pathname) || pathname.startsWith("/")) {
     return void 0;
   }
-  const targetFile = path16.resolve(path16.dirname(filePath), pathname).replace(markdownExtension, "");
+  const targetFile = path17.resolve(path17.dirname(filePath), pathname).replace(markdownExtension, "");
   const route = routesByFile.get(targetFile);
   if (route === void 0) return void 0;
   return `${route}${suffix}`;
@@ -7096,11 +7732,11 @@ var remarkLinkRewrite = (basePath = "", routesByFile = /* @__PURE__ */ new Map()
       node.url = resolved;
       return;
     }
-    const base = path16.posix.join(basePath);
+    const base = path17.posix.join(basePath);
     if (basePath && node.url.startsWith(base)) {
       node.url = node.url.slice(base.length);
     } else if (!node.url.startsWith("/") && !node.url.startsWith("#")) {
-      node.url = path16.posix.join("..", node.url);
+      node.url = path17.posix.join("..", node.url);
     }
     node.url = node.url.replace(/\.mdx?(#.*)?$/, "$1");
   });
@@ -7609,8 +8245,8 @@ var protectedAnnotatorPlugin = () => ({
 });
 
 // src/vite/config.ts
-var getAppClientEntryPath = () => path17.posix.join(getZudokuRootDir(), "src/app/entry.client.tsx");
-var getAppServerEntryPath = () => path17.posix.join(getZudokuRootDir(), "src/app/entry.server.tsx");
+var getAppClientEntryPath = () => path18.posix.join(getZudokuRootDir(), "src/app/entry.client.tsx");
+var getAppServerEntryPath = () => path18.posix.join(getZudokuRootDir(), "src/app/entry.server.tsx");
 var hasLoggedCdnInfo = false;
 var MEDIA_REGEX = /\.(a?png|jpe?g|gif|bmp|svg|webp|tiff|ico|webm|ogg|mp3|wav|m4a|avif|mp4)/i;
 var defineEnvVars = (vars) => Object.fromEntries(
@@ -7644,7 +8280,7 @@ async function getViteConfig(dir, configEnv, options = {}) {
   );
   if (ZuploEnv.isZuplo) {
     dotenv.config({
-      path: path17.resolve(config.__meta.rootDir, "../.env.zuplo"),
+      path: path18.resolve(config.__meta.rootDir, "../.env.zuplo"),
       quiet: true
     });
   }
@@ -7704,7 +8340,7 @@ async function getViteConfig(dir, configEnv, options = {}) {
       sourcemap: true,
       target: "es2022",
       chunkSizeWarningLimit: 1500,
-      outDir: path17.resolve(path17.join(dir, "dist", config.basePath ?? "")),
+      outDir: path18.resolve(path18.join(dir, "dist", config.basePath ?? "")),
       emptyOutDir: false,
       rolldownOptions: {
         external: [joinUrl(config.basePath, "/pagefind/pagefind.js")],
@@ -7734,8 +8370,8 @@ async function getViteConfig(dir, configEnv, options = {}) {
           external: ["@shikijs/themes", "@shikijs/langs"]
         },
         build: {
-          outDir: path17.resolve(
-            path17.join(dir, "dist", config.basePath ?? "", "server")
+          outDir: path18.resolve(
+            path18.join(dir, "dist", config.basePath ?? "", "server")
           ),
           copyPublicDir: false,
           rolldownOptions: {
@@ -7750,7 +8386,7 @@ async function getViteConfig(dir, configEnv, options = {}) {
         if (filename.startsWith(`${PROTECTED_CHUNK_DIR}/`)) {
           return joinUrl(config.basePath, `/${filename}`);
         }
-        if (cdnUrl?.base && [".js", ".css"].includes(path17.extname(filename))) {
+        if (cdnUrl?.base && [".js", ".css"].includes(path18.extname(filename))) {
           return joinUrl(cdnUrl.base, filename);
         }
         if (cdnUrl?.media && MEDIA_REGEX.test(filename)) {
@@ -7760,7 +8396,7 @@ async function getViteConfig(dir, configEnv, options = {}) {
       }
     },
     optimizeDeps: {
-      entries: [path17.posix.join(getZudokuRootDir(), "src/{app,lib}/**")],
+      entries: [path18.posix.join(getZudokuRootDir(), "src/{app,lib}/**")],
       exclude: ["zudoku"],
       include: [
         "@mdx-js/react",
@@ -7857,10 +8493,10 @@ ${cssLinks}
 
 // src/vite/manifest.ts
 import { writeFile as writeFile3 } from "node:fs/promises";
-import path18 from "node:path";
+import path19 from "node:path";
 var writeManifest = async (distDir, config) => {
   await writeFile3(
-    path18.join(distDir, MANIFEST_FILENAME),
+    path19.join(distDir, MANIFEST_FILENAME),
     `${JSON.stringify(buildManifest(config), null, 2)}
 `,
     "utf-8"
@@ -7869,17 +8505,442 @@ var writeManifest = async (distDir, config) => {
 
 // src/vite/output.ts
 import assert from "node:assert";
-import { cp, mkdir as mkdir3, writeFile as writeFile4 } from "node:fs/promises";
-import path19 from "node:path";
+import { existsSync } from "node:fs";
+import { cp, mkdir as mkdir3, readdir, rm, writeFile as writeFile4 } from "node:fs/promises";
+import path20 from "node:path";
 init_joinUrl();
+
+// src/vite/vercel-markdown-middleware.ts
+var normalizePath2 = (value) => {
+  const pathname = value.split("/").filter(Boolean).map((segment) => {
+    try {
+      return encodeURIComponent(decodeURIComponent(segment));
+    } catch {
+      return encodeURIComponent(segment);
+    }
+  }).join("/");
+  return pathname ? `/${pathname}` : "/";
+};
+var resolveRoutePath = (basePath, routePath) => {
+  const normalizedRoutePath = normalizePath2(routePath);
+  if (normalizedRoutePath === "/") {
+    return basePath;
+  }
+  return normalizePath2(`${basePath}/${normalizedRoutePath}`);
+};
+var resolveMarkdownPath = (basePath, routePath) => {
+  const normalizedRoutePath = normalizePath2(routePath);
+  if (normalizedRoutePath === "/") {
+    return normalizePath2(`${basePath}/index.md`);
+  }
+  return `${resolveRoutePath(basePath, routePath)}.md`;
+};
+var generateVercelMarkdownMiddleware = ({
+  basePath = "/",
+  knownCanonicalRoutePaths,
+  markdownCanonicalRoutePaths,
+  markdownNotFoundBody,
+  passthroughPaths = []
+}) => {
+  const normalizedBasePath = normalizePath2(basePath);
+  const knownRoutes = new Set(
+    knownCanonicalRoutePaths.map(
+      (routePath) => resolveRoutePath(normalizedBasePath, routePath)
+    )
+  );
+  const markdownRoutes = new Map(
+    markdownCanonicalRoutePaths.map((routePath) => [
+      resolveRoutePath(normalizedBasePath, routePath),
+      resolveMarkdownPath(normalizedBasePath, routePath)
+    ])
+  );
+  const normalizedPassthroughPaths = passthroughPaths.map(normalizePath2);
+  for (const routePath of markdownRoutes.keys()) {
+    if (!knownRoutes.has(routePath)) {
+      throw new Error(
+        `Markdown route "${routePath}" is not present in knownCanonicalRoutePaths`
+      );
+    }
+  }
+  return `
+const BASE_PATH = ${JSON.stringify(normalizedBasePath)};
+const KNOWN_ROUTES = new Set(${JSON.stringify([...knownRoutes])});
+const MARKDOWN_ROUTES = new Map(${JSON.stringify([...markdownRoutes])});
+const PASSTHROUGH_PATHS = new Set(${JSON.stringify(normalizedPassthroughPaths)});
+const MARKDOWN_NOT_FOUND_BODY = ${JSON.stringify(markdownNotFoundBody)};
+const NEGOTIATED_VARY = "Accept, Accept-Encoding";
+
+const REPRESENTATIONS = [
+  {
+    contentType: "text/html",
+    type: "text",
+    subtype: "html",
+    parameters: { charset: "utf-8" },
+    serverOrder: 0,
+  },
+  {
+    contentType: "text/markdown",
+    type: "text",
+    subtype: "markdown",
+    parameters: { charset: "utf-8" },
+    serverOrder: 1,
+  },
+];
+
+const TOKEN_PATTERN = /^[!#$%&'*+\\-.^_\`|~0-9A-Za-z]+$/;
+const MEDIA_RANGE_PATTERN =
+  /^([!#$%&'*+\\-.^_\`|~0-9A-Za-z]+|\\*)\\/([!#$%&'*+\\-.^_\`|~0-9A-Za-z]+|\\*)$/;
+const QUALITY_PATTERN = /^(?:0(?:\\.[0-9]{0,3})?|1(?:\\.0{0,3})?)$/;
+
+const splitOutsideQuotes = (value, delimiter) => {
+  const parts = [];
+  let start = 0;
+  let quoted = false;
+  let escaped = false;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (quoted && character === "\\\\") {
+      escaped = true;
+      continue;
+    }
+    if (character === '"') {
+      quoted = !quoted;
+      continue;
+    }
+    if (!quoted && character === delimiter) {
+      parts.push(value.slice(start, index));
+      start = index + 1;
+    }
+  }
+
+  parts.push(value.slice(start));
+  return parts;
+};
+
+const parseParameterValue = (value) => {
+  const trimmedValue = value.trim();
+  if (TOKEN_PATTERN.test(trimmedValue)) {
+    return trimmedValue.toLowerCase();
+  }
+  if (!trimmedValue.startsWith('"') || !trimmedValue.endsWith('"')) {
+    return undefined;
+  }
+  return trimmedValue.slice(1, -1).replace(/\\\\(.)/g, "$1").toLowerCase();
+};
+
+const parseMediaRange = (value, order) => {
+  const [rawMediaRange, ...rawParameters] = splitOutsideQuotes(value, ";");
+  const mediaRangeMatch = rawMediaRange
+    ?.trim()
+    .toLowerCase()
+    .match(MEDIA_RANGE_PATTERN);
+  if (!mediaRangeMatch) return undefined;
+
+  const [, type, subtype] = mediaRangeMatch;
+  if (!type || !subtype || (type === "*" && subtype !== "*")) {
+    return undefined;
+  }
+
+  const parameters = new Map();
+  let quality = 1;
+  let foundQuality = false;
+
+  for (const rawParameter of rawParameters) {
+    const separatorIndex = rawParameter.indexOf("=");
+    if (separatorIndex === -1) return undefined;
+
+    const name = rawParameter.slice(0, separatorIndex).trim().toLowerCase();
+    const rawValue = rawParameter.slice(separatorIndex + 1).trim();
+    if (!TOKEN_PATTERN.test(name)) return undefined;
+
+    if (name === "q") {
+      if (foundQuality || !QUALITY_PATTERN.test(rawValue)) return undefined;
+      quality = Number(rawValue);
+      foundQuality = true;
+      continue;
+    }
+
+    // RFC 9110 no longer defines accept extensions. Every non-q parameter is
+    // a media type parameter and participates in representation matching.
+    const parameterValue = parseParameterValue(rawValue);
+    if (parameterValue === undefined || parameters.has(name)) return undefined;
+    parameters.set(name, parameterValue);
+  }
+
+  return { type, subtype, parameters, quality, order };
+};
+
+const getSpecificity = (range) => {
+  if (range.type === "*") return 0;
+  if (range.subtype === "*") return 1;
+  return 2;
+};
+
+const matchesRepresentation = (range, representation) => {
+  if (range.type !== "*" && range.type !== representation.type) return false;
+  if (range.subtype !== "*" && range.subtype !== representation.subtype) {
+    return false;
+  }
+  return [...range.parameters].every(
+    ([name, value]) => representation.parameters[name]?.toLowerCase() === value,
+  );
+};
+
+const compareRangeMatches = (left, right) =>
+  right.specificity - left.specificity ||
+  right.parameterCount - left.parameterCount ||
+  right.quality - left.quality ||
+  left.rangeOrder - right.rangeOrder;
+
+const getRepresentationMatch = (ranges, representation) =>
+  ranges
+    .filter((range) => matchesRepresentation(range, representation))
+    .map((range) => ({
+      contentType: representation.contentType,
+      quality: range.quality,
+      specificity: getSpecificity(range),
+      parameterCount: range.parameters.size,
+      rangeOrder: range.order,
+      serverOrder: representation.serverOrder,
+    }))
+    .sort(compareRangeMatches)[0];
+
+const compareRepresentations = (left, right) =>
+  right.quality - left.quality ||
+  right.specificity - left.specificity ||
+  right.parameterCount - left.parameterCount ||
+  left.rangeOrder - right.rangeOrder ||
+  left.serverOrder - right.serverOrder;
+
+const negotiateContentType = (acceptHeader) => {
+  if (!acceptHeader?.trim()) return "text/html";
+
+  const ranges = splitOutsideQuotes(acceptHeader, ",")
+    .map((value, order) => parseMediaRange(value.trim(), order))
+    .filter((range) => range !== undefined);
+  const match = REPRESENTATIONS
+    .map((representation) => getRepresentationMatch(ranges, representation))
+    .filter((result) => result !== undefined)
+    .filter((result) => result.quality > 0)
+    .sort(compareRepresentations)[0];
+  return match?.contentType ?? null;
+};
+
+const normalizeRequestPath = (pathname) => {
+  const normalized = pathname
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => {
+      try {
+        return encodeURIComponent(decodeURIComponent(segment));
+      } catch {
+        return encodeURIComponent(segment);
+      }
+    })
+    .join("/");
+  return normalized ? "/" + normalized : "/";
+};
+
+const isWithinBasePath = (pathname) =>
+  BASE_PATH === "/" || pathname === BASE_PATH || pathname.startsWith(BASE_PATH + "/");
+
+const isExtensionlessPath = (pathname) => {
+  const lastSegment = pathname.split("/").filter(Boolean).at(-1);
+  return lastSegment === undefined || !lastSegment.includes(".");
+};
+
+const isMarkdownPath = (pathname) =>
+  pathname.endsWith(".md") || pathname.endsWith(".mdx");
+
+const getAlternateLink = (markdownPath) =>
+  "<" + markdownPath + '>; rel="alternate"; type="text/markdown"';
+
+const continueRequest = (headers = undefined) => {
+  const response = new Response(null);
+  response.headers.set("x-middleware-next", "1");
+  if (headers) {
+    for (const [name, value] of Object.entries(headers)) {
+      response.headers.set(name, value);
+    }
+  }
+  return response;
+};
+
+const negotiatedHeaders = (markdownPath) => ({
+  Vary: NEGOTIATED_VARY,
+  Link: getAlternateLink(markdownPath),
+});
+
+export default function middleware(request) {
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    return continueRequest();
+  }
+
+  const requestUrl = new URL(request.url);
+  const pathname = normalizeRequestPath(requestUrl.pathname);
+  const markdownPath = MARKDOWN_ROUTES.get(pathname);
+
+  if (markdownPath) {
+    const negotiatedType = negotiateContentType(request.headers.get("Accept"));
+    const headers = negotiatedHeaders(markdownPath);
+
+    if (negotiatedType === null) {
+      return new Response(request.method === "HEAD" ? null : "Not Acceptable", {
+        status: 406,
+        headers: {
+          ...headers,
+          "Content-Type": "text/plain; charset=utf-8",
+        },
+      });
+    }
+
+    if (negotiatedType === "text/html") {
+      return continueRequest(headers);
+    }
+
+    requestUrl.pathname = markdownPath;
+    return new Response(null, {
+      headers: {
+        ...headers,
+        "Content-Type": "text/markdown; charset=utf-8",
+        "x-middleware-rewrite": requestUrl.toString(),
+      },
+    });
+  }
+
+  if (KNOWN_ROUTES.has(pathname) || PASSTHROUGH_PATHS.has(pathname)) {
+    return continueRequest();
+  }
+
+  if (isWithinBasePath(pathname) && isMarkdownPath(pathname)) {
+    return new Response(
+      request.method === "HEAD" ? null : MARKDOWN_NOT_FOUND_BODY,
+      {
+        status: 404,
+        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+      },
+    );
+  }
+
+  if (!isWithinBasePath(pathname) || !isExtensionlessPath(pathname)) {
+    return continueRequest();
+  }
+
+  const negotiatedType = negotiateContentType(request.headers.get("Accept"));
+  if (negotiatedType === null) {
+    return new Response(request.method === "HEAD" ? null : "Not Acceptable", {
+      status: 406,
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        Vary: NEGOTIATED_VARY,
+      },
+    });
+  }
+
+  if (negotiatedType === "text/html") {
+    return continueRequest({ Vary: NEGOTIATED_VARY });
+  }
+
+  return new Response(
+    request.method === "HEAD" ? null : MARKDOWN_NOT_FOUND_BODY,
+    {
+      status: 404,
+      headers: {
+        "Content-Type": "text/markdown; charset=utf-8",
+        Vary: NEGOTIATED_VARY,
+      },
+    },
+  );
+}
+`.trimStart();
+};
+
+// src/vite/output.ts
 var pkgJson = getZudokuPackageJson();
+var MARKDOWN_MIDDLEWARE_PATH = "zudoku-markdown";
+var HTML_EXTENSION = ".html";
+var CLEAN_URL_ROUTES = [
+  {
+    src: "^/(?:(.+)/)?index(?:\\.html)?/?$",
+    headers: { Location: "/$1" },
+    status: 308
+  },
+  {
+    src: "^/(.*)\\.html/?$",
+    headers: { Location: "/$1" },
+    status: 308
+  }
+];
+var listStaticFiles = async (rootDir, currentDir = rootDir) => {
+  if (!existsSync(currentDir)) return [];
+  const entries = await readdir(currentDir, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = path20.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        return listStaticFiles(rootDir, entryPath);
+      }
+      if (!entry.isFile()) return [];
+      return [path20.relative(rootDir, entryPath).split(path20.sep).join("/")];
+    })
+  );
+  return files.flat().sort();
+};
+var getCleanPath = (filename) => {
+  const pathWithoutExtension = filename.slice(0, -HTML_EXTENSION.length);
+  if (pathWithoutExtension === "index") return "";
+  if (pathWithoutExtension.endsWith("/index")) {
+    return pathWithoutExtension.slice(0, -"/index".length);
+  }
+  return pathWithoutExtension;
+};
+var getCleanUrlOverrides = (staticHtmlFiles) => {
+  const sourceByCleanPath = /* @__PURE__ */ new Map();
+  return Object.fromEntries(
+    staticHtmlFiles.map((filename) => {
+      const cleanPath = getCleanPath(filename);
+      const existingSource = sourceByCleanPath.get(cleanPath);
+      invariant(
+        !existingSource || existingSource === filename,
+        `Cannot generate the Vercel clean URL "${cleanPath}" for both "${existingSource}" and "${filename}"`
+      );
+      sourceByCleanPath.set(cleanPath, filename);
+      return [filename, { path: cleanPath }];
+    })
+  );
+};
+var cleanVercelOutput = async (dir) => {
+  if (!process.env.VERCEL) return;
+  await rm(path20.join(dir, ".vercel/output"), {
+    recursive: true,
+    force: true
+  });
+};
 function generateOutput({
   config,
   redirects,
-  rewrites = []
+  rewrites = [],
+  markdownNegotiation,
+  staticHtmlFiles = []
 }) {
   const routes = [];
-  for (const redirect of redirects) {
+  if (staticHtmlFiles.length > 0) {
+    routes.push(...CLEAN_URL_ROUTES);
+  }
+  const uniqueRedirects = [
+    ...new Map(
+      redirects.map((redirect) => [
+        JSON.stringify([redirect.from, redirect.to]),
+        redirect
+      ])
+    ).values()
+  ];
+  for (const redirect of uniqueRedirects) {
     routes.push({
       src: redirect.from,
       dest: redirect.to,
@@ -7904,6 +8965,19 @@ function generateOutput({
       continue: true
     });
   }
+  if (markdownNegotiation) {
+    const basePath = joinUrl(config.basePath);
+    const escapedBasePath = basePath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    routes.push({
+      // Keep the path matcher broad because valid documentation slugs can end
+      // in dotted versions such as `/api/1.0.0`. The middleware itself
+      // cheaply passes through assets and non-document routes.
+      src: basePath === "/" ? "/(.*)" : `${escapedBasePath}(?:/(.*))?`,
+      methods: ["GET", "HEAD"],
+      middlewarePath: MARKDOWN_MIDDLEWARE_PATH,
+      continue: true
+    });
+  }
   if (rewrites.length > 0) {
     routes.push({ handle: "filesystem" });
     for (const rewrite of rewrites) {
@@ -7913,40 +8987,82 @@ function generateOutput({
       });
     }
   }
+  const overrides = getCleanUrlOverrides(staticHtmlFiles);
   const output = {
     version: 3,
     framework: {
       version: pkgJson.version
     },
-    routes
+    routes,
+    ...Object.keys(overrides).length > 0 && { overrides }
   };
   return output;
 }
 async function writeOutput(dir, {
   config,
   redirects,
-  rewrites
+  rewrites,
+  markdownNegotiation
 }) {
-  const output = generateOutput({ config, redirects, rewrites });
-  const outputDir = process.env.VERCEL ? path19.join(dir, ".vercel/output") : path19.join(dir, "dist/.output");
+  const vercelMarkdownNegotiation = process.env.VERCEL ? markdownNegotiation : void 0;
+  const staticFiles = process.env.VERCEL ? await listStaticFiles(path20.join(dir, ".vercel/output/static")) : [];
+  const staticHtmlFiles = staticFiles.filter(
+    (filename) => filename.endsWith(HTML_EXTENSION)
+  );
+  const staticPassthroughPaths = staticFiles.filter((filename) => {
+    const basename = path20.posix.basename(filename);
+    return !basename.includes(".") || basename.endsWith(".md") || basename.endsWith(".mdx");
+  }).map((filename) => `/${filename}`);
+  const output = generateOutput({
+    config,
+    redirects,
+    rewrites,
+    markdownNegotiation: vercelMarkdownNegotiation,
+    staticHtmlFiles
+  });
+  const outputDir = process.env.VERCEL ? path20.join(dir, ".vercel/output") : path20.join(dir, "dist/.output");
   await mkdir3(outputDir, { recursive: true });
-  const outputFile = path19.join(outputDir, "config.json");
+  const outputFile = path20.join(outputDir, "config.json");
   await writeFile4(outputFile, JSON.stringify(output, null, 2), "utf-8");
   if (process.env.VERCEL) {
+    if (vercelMarkdownNegotiation) {
+      const functionDir = path20.join(
+        outputDir,
+        "functions",
+        `${MARKDOWN_MIDDLEWARE_PATH}.func`
+      );
+      await mkdir3(functionDir, { recursive: true });
+      await Promise.all([
+        writeFile4(
+          path20.join(functionDir, "index.js"),
+          generateVercelMarkdownMiddleware({
+            basePath: config.basePath,
+            ...vercelMarkdownNegotiation,
+            passthroughPaths: staticPassthroughPaths
+          }),
+          "utf-8"
+        ),
+        writeFile4(
+          path20.join(functionDir, ".vc-config.json"),
+          JSON.stringify({ runtime: "edge", entrypoint: "index.js" }, null, 2),
+          "utf-8"
+        )
+      ]);
+    }
     console.log("Wrote Vercel output to", outputDir);
   }
 }
 
 // src/vite/prerender/prerender.ts
 import { readFileSync as readFileSync2 } from "node:fs";
-import { readFile as readFile3, rm } from "node:fs/promises";
+import { readFile as readFile3, rm as rm2 } from "node:fs/promises";
 import os from "node:os";
-import path22 from "node:path";
+import path23 from "node:path";
 import { pathToFileURL } from "node:url";
 import { createIndex } from "pagefind";
 import colors7 from "picocolors";
 import PiscinaImport from "piscina";
-init_joinUrl();
+init_markdown_representation();
 
 // src/vite/reporter.ts
 function writeLine(output) {
@@ -7979,9 +9095,9 @@ function throttle(fn) {
 
 // src/vite/sitemap.ts
 init_joinUrl();
-import { createWriteStream, existsSync } from "node:fs";
+import { createWriteStream, existsSync as existsSync2 } from "node:fs";
 import { mkdir as mkdir4 } from "node:fs/promises";
-import path20 from "node:path";
+import path21 from "node:path";
 import colors5 from "picocolors";
 import { SitemapStream } from "sitemap";
 async function generateSitemap({
@@ -7995,11 +9111,11 @@ async function generateSitemap({
     return;
   }
   const sitemap = new SitemapStream({ hostname: config.siteUrl });
-  const outputDir = path20.resolve(baseOutputDir, config.outDir ?? "");
-  if (!existsSync(outputDir)) {
+  const outputDir = path21.resolve(baseOutputDir, config.outDir ?? "");
+  if (!existsSync2(outputDir)) {
     await mkdir4(outputDir, { recursive: true });
   }
-  const sitemapOutputPath = path20.join(outputDir, "sitemap.xml");
+  const sitemapOutputPath = path21.join(outputDir, "sitemap.xml");
   const writeStream = createWriteStream(sitemapOutputPath);
   sitemap.pipe(writeStream);
   let lastmod;
@@ -8029,17 +9145,17 @@ async function generateSitemap({
 
 // src/vite/prerender/utils.ts
 init_joinUrl();
-var resolveRoutePath = (path31) => {
-  const segments = path31.split("/");
+var resolveRoutePath2 = (path32) => {
+  const segments = path32.split("/");
   if (segments.some((s) => s.startsWith(":") && !s.endsWith("?"))) {
     return void 0;
   }
   return segments.filter((s) => !s.startsWith(":")).join("/") || void 0;
 };
-var isSkipped = (path31) => path31.includes("*") || /^\d+$/.test(path31);
+var isSkipped = (path32) => path32.includes("*") || /^\d+$/.test(path32);
 var resolveRoutes = (routes, parentPath = "") => routes.flatMap((route) => {
   if (route.path && isSkipped(route.path)) return [];
-  const routePath = route.path ? resolveRoutePath(route.path) : void 0;
+  const routePath = route.path ? resolveRoutePath2(route.path) : void 0;
   if (route.path && !routePath) return [];
   const fullPath = routePath ? routePath.startsWith("/") ? routePath : joinUrl(parentPath, routePath) : parentPath;
   const hasStrippedParams = route.path?.split("/").some((s) => s.startsWith(":")) ?? false;
@@ -8065,6 +9181,12 @@ var collectRewrites = (resolved) => resolved.flatMap((r) => [
   ...collectRewrites(r.children)
 ]);
 var routesToPaths = (routes) => collectPaths(resolveRoutes(routes), "");
+var routesToPrerenderPaths = (routes, redirects = []) => Array.from(
+  /* @__PURE__ */ new Set([
+    ...routesToPaths(routes),
+    ...redirects.map(({ from }) => joinUrl(from))
+  ])
+);
 var routesToRewrites = (routes) => collectRewrites(resolveRoutes(routes));
 var selectPagesToIndex = (pages, paths) => {
   const withUrl = pages.flatMap(({ indexStatusCode, html }, i) => {
@@ -8095,12 +9217,12 @@ var prerender = async ({
   serverConfigFilename,
   writeRedirects = true
 }) => {
-  const distDir = path22.join(dir, "dist", basePath);
+  const distDir = path23.join(dir, "dist", basePath);
   const serverConfigPath = pathToFileURL(
-    path22.join(distDir, "server", serverConfigFilename)
+    path23.join(distDir, "server", serverConfigFilename)
   ).href;
   const entryServerPath = pathToFileURL(
-    path22.join(distDir, "server/entry.server.js")
+    path23.join(distDir, "server/entry.server.js")
   ).href;
   const rawConfig = await import(serverConfigPath).then((m) => m.default);
   const config = validateConfig(await runPluginTransformConfig(rawConfig));
@@ -8108,13 +9230,8 @@ var prerender = async ({
   const module = await import(entryServerPath);
   const getRoutes = module.getRoutesByConfig;
   const routes = getRoutes(config);
-  const paths = routesToPaths(routes);
+  const paths = routesToPrerenderPaths(routes, config.redirects);
   const rewrites = routesToRewrites(routes);
-  if (config.redirects) {
-    for (const r of config.redirects) {
-      paths.push(joinUrl(r.from));
-    }
-  }
   const { maxThreads, maxOldGenerationSizeMb } = getWorkerScaling(
     buildConfig?.prerender?.workers
   );
@@ -8219,7 +9336,7 @@ var prerender = async ({
     }
     if (isTTY()) writeLine("");
     const { outputPath } = await pagefindIndex.writeFiles({
-      outputPath: path22.join(distDir, "pagefind")
+      outputPath: path23.join(distDir, "pagefind")
     });
     if (outputPath) {
       const duration = (performance.now() - pagefindStart) / 1e3;
@@ -8239,7 +9356,7 @@ var prerender = async ({
     redirectUrls
   });
   const llmsConfig = config.docs.llms;
-  const markdownInfoPath = path22.join(
+  const markdownInfoPath = path23.join(
     dir,
     "node_modules/.zudoku/markdown-info.json"
   );
@@ -8258,22 +9375,38 @@ var prerender = async ({
       siteName: config.site?.title,
       llmsTxt: llmsConfig.llmsTxt,
       llmsTxtFull: llmsConfig.llmsTxtFull,
+      title: llmsConfig.title,
+      description: llmsConfig.description,
+      instructions: llmsConfig.instructions,
       redirectUrls
     });
   }
+  const contentNegotiationEnabled = config.docs.publishMarkdown && config.docs.contentNegotiation;
+  const markdownNotFound = contentNegotiationEnabled ? getMarkdownNotFound({
+    basePath: config.basePath,
+    includeLlmsTxt: llmsConfig.llmsTxt ?? false,
+    markdownRoutePaths: markdownFileInfos.map((info) => info.routePath),
+    sitemapOutDir: config.sitemap ? config.sitemap.outDir ?? "" : void 0
+  }) : void 0;
   if (!config.docs.publishMarkdown) {
     await Promise.all(
       markdownFileInfos.map((info) => {
         const outputPath = getMarkdownOutputPath(distDir, info.routePath);
-        if (!path22.resolve(outputPath).startsWith(path22.resolve(distDir))) {
+        if (!path23.resolve(outputPath).startsWith(path23.resolve(distDir))) {
           return;
         }
-        return rm(outputPath).catch(() => {
+        return rm2(outputPath).catch(() => {
         });
       })
     );
   }
-  return { workerResults, rewrites };
+  return {
+    workerResults,
+    rewrites,
+    knownRoutes: paths,
+    markdownRoutes: markdownFileInfos.map((info) => info.routePath),
+    markdownNotFound
+  };
 };
 var getWorkerScaling = (workersOverride) => {
   const PER_WORKER_HEAP_LIMIT_MB = 4096;
@@ -8323,8 +9456,8 @@ var getContainerMemoryLimitMb = () => {
 };
 
 // src/vite/protected/build.ts
-import { mkdir as mkdir5, readdir, readFile as readFile4, rename, rm as rm2 } from "node:fs/promises";
-import path23 from "node:path";
+import { mkdir as mkdir5, readdir as readdir2, readFile as readFile4, rename, rm as rm3 } from "node:fs/promises";
+import path24 from "node:path";
 init_joinUrl();
 var assertProtectedPatternsCovered = (config) => {
   const { patterns } = getProtectedSourceMatcher(config);
@@ -8346,11 +9479,11 @@ var findProtectedLeaks = (output) => {
     const visited = /* @__PURE__ */ new Set();
     const stack = [{ fileName: entry.fileName, path: [entry.fileName] }];
     while (stack.length > 0) {
-      const { fileName, path: path31 } = stack.pop();
+      const { fileName, path: path32 } = stack.pop();
       if (visited.has(fileName)) continue;
       visited.add(fileName);
       for (const imp of byFileName.get(fileName)?.imports ?? []) {
-        const next = [...path31, imp];
+        const next = [...path32, imp];
         if (isProtected(imp)) {
           leaks.push(next.join(" -> "));
           continue;
@@ -8381,27 +9514,27 @@ This eagerly pulls gated content into the public bundle. Check that nothing in n
   );
 };
 var moveProtectedChunks = async (clientOutDir, serverOutDir) => {
-  const srcDir = path23.join(clientOutDir, PROTECTED_CHUNK_DIR);
-  const files = await readdir(srcDir).catch((err) => {
+  const srcDir = path24.join(clientOutDir, PROTECTED_CHUNK_DIR);
+  const files = await readdir2(srcDir).catch((err) => {
     if (err.code === "ENOENT") return null;
     throw err;
   });
   if (!files) return;
-  const destDir = path23.join(serverOutDir, PROTECTED_CHUNK_DIR);
+  const destDir = path24.join(serverOutDir, PROTECTED_CHUNK_DIR);
   await mkdir5(destDir, { recursive: true });
   await Promise.all(
     files.map(
-      (file) => rename(path23.join(srcDir, file), path23.join(destDir, file))
+      (file) => rename(path24.join(srcDir, file), path24.join(destDir, file))
     )
   );
-  const leftover = await readdir(srcDir).catch(() => []);
+  const leftover = await readdir2(srcDir).catch(() => []);
   if (leftover.length > 0) {
     throw new Error(
       `moveProtectedChunks left ${leftover.length} file(s) in ${srcDir}: ${leftover.join(", ")}.
 These would be served publicly. Aborting build.`
     );
   }
-  await rm2(srcDir, { recursive: true, force: true });
+  await rm3(srcDir, { recursive: true, force: true });
 };
 var assertCloudflareWranglerGatesProtected = async (dir, config) => {
   const { enabled } = getProtectedSourceMatcher(config);
@@ -8409,7 +9542,7 @@ var assertCloudflareWranglerGatesProtected = async (dir, config) => {
   const protectedPrefix = `${joinUrl(config.basePath, PROTECTED_CHUNK_DIR)}/`;
   const candidates = ["wrangler.toml", "wrangler.jsonc", "wrangler.json"];
   for (const name of candidates) {
-    const file = await readFile4(path23.join(dir, name), "utf-8").catch(
+    const file = await readFile4(path24.join(dir, name), "utf-8").catch(
       () => void 0
     );
     if (file === void 0) continue;
@@ -8437,8 +9570,11 @@ async function runBuild(options) {
   const builder2 = await createBuilder(viteConfig);
   invariant(builder2.environments.client, "Client environment is missing");
   invariant(builder2.environments.ssr, "SSR environment is missing");
-  const distDir = path24.resolve(path24.join(dir, "dist"));
-  await rm3(distDir, { recursive: true, force: true });
+  const distDir = path25.resolve(path25.join(dir, "dist"));
+  await Promise.all([
+    rm4(distDir, { recursive: true, force: true }),
+    cleanVercelOutput(dir)
+  ]);
   const [clientResult, serverResult] = await Promise.all([
     builder2.build(builder2.environments.client),
     builder2.build(builder2.environments.ssr)
@@ -8487,13 +9623,13 @@ async function runBuild(options) {
       await assertCloudflareWranglerGatesProtected(dir, config);
     }
     await writeFile6(
-      path24.join(distDir, "package.json"),
+      path25.join(distDir, "package.json"),
       `${JSON.stringify({ type: "module" }, null, 2)}
 `,
       "utf-8"
     );
     await writeManifest(distDir, config);
-    await rm3(path24.join(clientOutDir, "index.html"), { force: true });
+    await rm4(path25.join(clientOutDir, "index.html"), { force: true });
   } else {
     await runPrerender({
       dir,
@@ -8517,43 +9653,54 @@ var runPrerender = async (options) => {
   const issuer = await getIssuer(config);
   const serverConfigFilename = findServerConfigFilename(serverResult);
   try {
-    const { workerResults, rewrites } = await prerender({
+    const {
+      workerResults,
+      rewrites,
+      knownRoutes,
+      markdownRoutes,
+      markdownNotFound
+    } = await prerender({
       html,
       dir,
       basePath: config.basePath,
       serverConfigFilename,
       writeRedirects: process.env.VERCEL === void 0
     });
-    const indexHtml = path24.join(clientOutDir, "index.html");
+    const indexHtml = path25.join(clientOutDir, "index.html");
     if (!workerResults.find((r) => r.outputPath === indexHtml)) {
       await writeFile6(indexHtml, html, "utf-8");
     }
     const statusPages = workerResults.flatMap(
-      (r) => /^(400|404|500)\.html$/.test(path24.basename(r.outputPath)) ? r.outputPath : []
+      (r) => /^(400|404|500)\.html$/.test(path25.basename(r.outputPath)) ? r.outputPath : []
     );
     for (const statusPage of statusPages) {
       await rename2(
         statusPage,
-        path24.join(dir, DIST_DIR, path24.basename(statusPage))
+        path25.join(dir, DIST_DIR, path25.basename(statusPage))
       );
     }
-    await rm3(serverOutDir, { recursive: true, force: true });
+    await rm4(serverOutDir, { recursive: true, force: true });
     if (process.env.VERCEL) {
-      await mkdir6(path24.join(dir, ".vercel/output/static"), { recursive: true });
+      await mkdir6(path25.join(dir, ".vercel/output/static"), { recursive: true });
       await rename2(
-        path24.join(dir, DIST_DIR),
-        path24.join(dir, ".vercel/output/static")
+        path25.join(dir, DIST_DIR),
+        path25.join(dir, ".vercel/output/static")
       );
     }
     await writeOutput(dir, {
       config,
       redirects: workerResults.flatMap((r) => r.redirect ?? []),
-      rewrites
+      rewrites,
+      markdownNegotiation: markdownNotFound ? {
+        knownCanonicalRoutePaths: knownRoutes,
+        markdownCanonicalRoutePaths: markdownRoutes,
+        markdownNotFoundBody: markdownNotFound
+      } : void 0
     });
     if (ZuploEnv.isZuplo && issuer) {
       const provider = config.authentication?.type;
       await writeFile6(
-        path24.join(dir, DIST_DIR, ".output/zuplo.json"),
+        path25.join(dir, DIST_DIR, ".output/zuplo.json"),
         JSON.stringify({ issuer, provider }, null, 2),
         "utf-8"
       );
@@ -8565,8 +9712,8 @@ var runPrerender = async (options) => {
 };
 var findUserEntry = (dir) => {
   for (const ext of ["ts", "tsx", "js", "mjs"]) {
-    const candidate = path24.join(dir, `zudoku.server.${ext}`);
-    if (existsSync2(candidate)) return candidate;
+    const candidate = path25.join(dir, `zudoku.server.${ext}`);
+    if (existsSync3(candidate)) return candidate;
   }
 };
 var bundleSSREntry = async (options) => {
@@ -8576,15 +9723,15 @@ var bundleSSREntry = async (options) => {
   let entryPoint = userEntry;
   let tempEntryPath;
   if (!entryPoint) {
-    tempEntryPath = path24.join(dir, "__ssr-entry.ts");
+    tempEntryPath = path25.join(dir, "__ssr-entry.ts");
     const templateContent = await readFile5(
-      path24.join(packageRoot, "src/vite/ssr-templates", `${adapter}.ts`),
+      path25.join(packageRoot, "src/vite/ssr-templates", `${adapter}.ts`),
       "utf-8"
     );
     await writeFile6(tempEntryPath, templateContent, "utf-8");
     entryPoint = tempEntryPath;
   }
-  const frameworkPath = path24.join(serverOutDir, "entry.server.js");
+  const frameworkPath = path25.join(serverOutDir, "entry.server.js");
   try {
     await esbuild({
       entryPoints: [entryPoint],
@@ -8592,9 +9739,9 @@ var bundleSSREntry = async (options) => {
       platform: ["node", "lambda"].includes(adapter) ? "node" : "neutral",
       target: "es2022",
       format: "esm",
-      outfile: path24.join(serverOutDir, "entry.js"),
+      outfile: path25.join(serverOutDir, "entry.js"),
       external: ["./zudoku.config.js"],
-      nodePaths: [path24.join(packageRoot, "node_modules")],
+      nodePaths: [path25.join(packageRoot, "node_modules")],
       banner: { js: "// Bundled SSR entry" },
       define: {
         __ZUDOKU_TEMPLATE__: JSON.stringify(html)
@@ -8611,15 +9758,15 @@ var bundleSSREntry = async (options) => {
       ]
     });
     await Promise.all([
-      rm3(frameworkPath, { force: true }),
-      rm3(`${frameworkPath}.map`, { force: true }),
-      rm3(path24.join(serverOutDir, "assets"), {
+      rm4(frameworkPath, { force: true }),
+      rm4(`${frameworkPath}.map`, { force: true }),
+      rm4(path25.join(serverOutDir, "assets"), {
         recursive: true,
         force: true
       })
     ]);
   } finally {
-    if (tempEntryPath) await rm3(tempEntryPath, { force: true });
+    if (tempEntryPath) await rm4(tempEntryPath, { force: true });
   }
 };
 
@@ -8633,11 +9780,11 @@ function printWarningToConsole(message) {
 }
 
 // src/cli/preview/handler.ts
-import path25 from "node:path";
+import path26 from "node:path";
 import { preview as vitePreview } from "vite";
 var DEFAULT_PREVIEW_PORT = 4e3;
 async function preview(argv) {
-  const dir = path25.resolve(process.cwd(), argv.dir);
+  const dir = path26.resolve(process.cwd(), argv.dir);
   const viteConfig = await getViteConfig(dir, {
     command: "serve",
     mode: "production",
@@ -8675,7 +9822,7 @@ async function build(argv) {
   printDiagnosticsToConsole(`Starting Zudoku build v${packageJson2.version}`);
   printDiagnosticsToConsole("");
   printDiagnosticsToConsole("");
-  const dir = path26.resolve(process.cwd(), argv.dir);
+  const dir = path27.resolve(process.cwd(), argv.dir);
   try {
     await runBuild({
       dir,
@@ -8834,13 +9981,13 @@ var build_default = {
 
 // src/cli/dev/handler.ts
 init_joinUrl();
-import path29 from "node:path";
+import path30 from "node:path";
 
 // src/vite/dev-server.ts
-import fs3 from "node:fs/promises";
+import fs4 from "node:fs/promises";
 import http from "node:http";
 import https from "node:https";
-import path28 from "node:path";
+import path29 from "node:path";
 import { stripVTControlCharacters } from "node:util";
 import { createHttpTerminator } from "http-terminator";
 import {
@@ -8872,7 +10019,7 @@ async function findAvailablePort(startPort) {
 init_joinUrl();
 
 // src/vite/pagefind-dev-index.ts
-import path27 from "node:path";
+import path28 from "node:path";
 import { createIndex as createIndex2 } from "pagefind";
 import { isRunnableDevEnvironment } from "vite";
 init_joinUrl();
@@ -8926,7 +10073,7 @@ async function* buildPagefindDevIndex(vite, config) {
       path: urlPath
     };
   }
-  const outputPath = path27.join(vite.config.publicDir, "pagefind");
+  const outputPath = path28.join(vite.config.publicDir, "pagefind");
   await pagefindIndex.writeFiles({ outputPath });
   yield { type: "complete", success: true, indexed };
 }
@@ -8946,9 +10093,9 @@ var DevServer = class {
     this.protocol = "https";
     const { dir } = this.#options;
     const [key, cert, ca] = await Promise.all([
-      fs3.readFile(path28.resolve(dir, config.https.key)),
-      fs3.readFile(path28.resolve(dir, config.https.cert)),
-      config.https.ca ? fs3.readFile(path28.resolve(dir, config.https.ca)) : void 0
+      fs4.readFile(path29.resolve(dir, config.https.key)),
+      fs4.readFile(path29.resolve(dir, config.https.cert)),
+      config.https.ca ? fs4.readFile(path29.resolve(dir, config.https.ca)) : void 0
     ]);
     return https.createServer({ key, cert, ca });
   }
@@ -8976,7 +10123,7 @@ var DevServer = class {
           // built-in transform middleware which would treat the path as a static asset.
           name: "zudoku:entry-client",
           configureServer(server2) {
-            const entryPath = path28.posix.join(
+            const entryPath = path29.posix.join(
               server2.config.base,
               "/__z/entry.client.tsx"
             );
@@ -9088,14 +10235,14 @@ var DevServer = class {
       `Server-side rendering ${this.#options.ssr ? "enabled" : "disabled"}`
     );
     if (config.search?.type === "pagefind") {
-      const pagefindPath = path28.join(
+      const pagefindPath = path29.join(
         vite.config.publicDir,
         "pagefind/pagefind.js"
       );
-      const exists = await fs3.stat(pagefindPath).catch(() => false);
+      const exists = await fs4.stat(pagefindPath).catch(() => false);
       if (!exists) {
-        await fs3.mkdir(path28.dirname(pagefindPath), { recursive: true });
-        await fs3.writeFile(pagefindPath, 'throw new Error("NOT_BUILT_YET");');
+        await fs4.mkdir(path29.dirname(pagefindPath), { recursive: true });
+        await fs4.writeFile(pagefindPath, 'throw new Error("NOT_BUILT_YET");');
       }
     }
     vite.middlewares.use(async (req, res) => {
@@ -9196,7 +10343,7 @@ var DevServer = class {
 async function dev(argv) {
   const packageJson2 = getZudokuPackageJson();
   process.env.NODE_ENV = "development";
-  const dir = path29.resolve(process.cwd(), argv.dir);
+  const dir = path30.resolve(process.cwd(), argv.dir);
   const server = new DevServer({
     dir,
     argPort: argv.port,
@@ -9301,7 +10448,7 @@ var previewCommand = {
 var preview_default = previewCommand;
 
 // src/cli/common/outdated.ts
-import { existsSync as existsSync3, mkdirSync } from "node:fs";
+import { existsSync as existsSync4, mkdirSync } from "node:fs";
 import { readFile as readFile6, writeFile as writeFile7 } from "node:fs/promises";
 import { join } from "node:path";
 import colors10 from "picocolors";
@@ -9352,12 +10499,12 @@ function box(message, {
 
 // src/cli/common/xdg/lib.ts
 import { homedir } from "node:os";
-import path30 from "node:path";
+import path31 from "node:path";
 function defineDirectoryWithFallback(xdgName, fallback) {
   if (process.env[xdgName]) {
     return process.env[xdgName];
   } else {
-    return path30.join(homedir(), fallback);
+    return path31.join(homedir(), fallback);
   }
 }
 var XDG_CONFIG_HOME = defineDirectoryWithFallback(
@@ -9372,15 +10519,15 @@ var XDG_STATE_HOME = defineDirectoryWithFallback(
   "XDG_DATA_HOME",
   ".local/state"
 );
-var ZUDOKU_XDG_CONFIG_HOME = path30.join(
+var ZUDOKU_XDG_CONFIG_HOME = path31.join(
   XDG_CONFIG_HOME,
   CLI_XDG_FOLDER_NAME
 );
-var ZUDOKU_XDG_DATA_HOME = path30.join(
+var ZUDOKU_XDG_DATA_HOME = path31.join(
   XDG_DATA_HOME,
   CLI_XDG_FOLDER_NAME
 );
-var ZUDOKU_XDG_STATE_HOME = path30.join(
+var ZUDOKU_XDG_STATE_HOME = path31.join(
   XDG_STATE_HOME,
   CLI_XDG_FOLDER_NAME
 );
@@ -9422,12 +10569,12 @@ async function getLatestVersion() {
   return void 0;
 }
 async function getVersionCheckInfo() {
-  if (!existsSync3(ZUDOKU_XDG_STATE_HOME)) {
+  if (!existsSync4(ZUDOKU_XDG_STATE_HOME)) {
     mkdirSync(ZUDOKU_XDG_STATE_HOME, { recursive: true });
   }
   const versionCheckPath = join(ZUDOKU_XDG_STATE_HOME, VERSION_CHECK_FILE);
   let versionCheckInfo;
-  if (existsSync3(versionCheckPath)) {
+  if (existsSync4(versionCheckPath)) {
     try {
       versionCheckInfo = await readFile6(versionCheckPath, "utf-8").then(
         JSON.parse