@caprail-dev/agent-pages 0.2.0

package/README.md

@@ -0,0 +1,141 @@
+# @caprail-dev/agent-pages
+
+Markdown-first pages for AI agents in Next.js: co-locate a `page.md` next to
+each `page.tsx` and serve it to AI crawlers and fetchers automatically —
+plus generated `/llms.txt` and `/llms-full.txt`.
+
+Real agent traffic (ClaudeBot, GPTBot, Claude Code, …) mostly does **not**
+send `Accept: text/markdown`, so Accept-header-only negotiation misses it.
+This package decides per request, in order:
+
+1. **Accept q-values** — `text/markdown` listed with `q > 0` and ≥ HTML;
+2. **User-agent classification** (via [`@caprail-dev/analytics`](https://www.npmjs.com/package/@caprail-dev/analytics)) — AI
+   crawlers/fetchers get markdown; search bots and agentic browsers keep
+   HTML (serving indexers different content is cloaking);
+3. **`Signature-Agent` header** (RFC 9421) — signed agents get markdown even
+   with a browser-like UA;
+4. **Heuristic fallback** — no `sec-fetch-mode` (real browsers always send
+   it) + a bot-like UA, except search/link-preview bots that need the HTML.
+
+## Install
+
+```bash
+npm i @caprail-dev/agent-pages   # or bun add / pnpm add / yarn add
+```
+
+## Setup
+
+**1. Wrap your `next.config.js`** — runs codegen on every `next dev` /
+`next build` (and watches `page.md` files in dev):
+
+```js
+import { withAgentPages } from "@caprail-dev/agent-pages/config";
+
+export default withAgentPages(nextConfig, {
+  siteUrl: "https://example.com",
+});
+```
+
+**2. Co-locate `page.md` twins** next to the pages you want agent-readable:
+
+```
+src/app/page.tsx        →  src/app/page.md        (served at /index.md)
+src/app/terms/page.tsx  →  src/app/terms/page.md  (served at /terms.md)
+```
+
+Optional frontmatter feeds the `/llms.txt` link list:
+
+```markdown
+---
+title: Example
+description: One-liner shown in /llms.txt.
+---
+
+# Example — the markdown twin
+```
+
+**3. Add the middleware:**
+
+```ts
+// middleware.ts
+import { createAgentPagesMiddleware } from "@caprail-dev/agent-pages/next";
+import { MD_REWRITES } from "@/app/_agent-pages/rewrites";
+
+export const middleware = createAgentPagesMiddleware({ rewrites: MD_REWRITES });
+export const config = {
+  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+Apps with existing middleware compose via the decision object instead:
+
+```ts
+import { decideAgentPages } from "@caprail-dev/agent-pages/next";
+import { MD_REWRITES } from "@/app/_agent-pages/rewrites";
+
+export function middleware(req: NextRequest) {
+  const d = decideAgentPages(req, MD_REWRITES);
+  // d.kind is "rewrite" or "html"; d.response has Vary set correctly.
+  return d.response;
+}
+```
+
+## What gets generated
+
+Inside your app dir (commit these — deterministic output keeps diffs
+meaningful and shows exactly what agents will read):
+
+- `_agent-pages/rewrites.ts` — HTML path → markdown twin record. Edge-safe
+  strings only; the **only** file the middleware imports.
+- `_agent-pages/manifest.ts` — full doc registry (content inlined). Imported
+  only by route handlers; never reaches the edge bundle.
+- `<path>.md/route.ts` per `page.md` — `force-static` markdown routes.
+- `llms.txt/route.ts` + `llms-full.txt/route.ts` (disable with
+  `llms: { enabled: false }`).
+
+Every generated file is marker-headed; the codegen **refuses to overwrite**
+files without the marker and cleans up generated files whose `page.md` was
+deleted.
+
+## Options
+
+```ts
+withAgentPages(nextConfig, {
+  siteUrl: "https://example.com",
+  appDir: "src/app", // default: src/app, else app
+  llms: {
+    enabled: true, // default
+    intro: "# Example\n\n> …", // /llms.txt preamble before "## Docs"
+  },
+  extraDocs: [
+    // Docs whose markdown lives in app code (route stays hand-written);
+    // included in /llms.txt + /llms-full.txt via an emitted import.
+    {
+      mdPath: "/install.md",
+      title: "Install guide",
+      description: "Agent-readable install instructions.",
+      source: { module: "@/lib/install-doc", export: "INSTALL_DOC" },
+    },
+  ],
+});
+```
+
+## Notes & limitations
+
+- Dynamic segments (`[slug]/page.md`) are unsupported in v1 — skipped with a
+  warning.
+- Interpolations are not supported in `page.md` — flatten values to literals
+  and guard them with a test (e.g. assert the file contains your
+  `TERMS_VERSION` constant).
+- The dev watcher uses `fs.watch(…, { recursive: true })` (Node ≥ 20 on
+  Linux). Deleting a whole directory may not fire the `page.md` filter —
+  restart `next dev` to clean up (a restart with no changes writes nothing).
+- `next.config.js` consumes the compiled `dist/config.js` — in monorepos,
+  build this package before `next dev` / `next build`.
+- A blanket `/* eslint-disable */` heads every generated file; with
+  `reportUnusedDisableDirectives` enabled you may see warnings on clean
+  files — harmless.
+
+## License
+
+MIT

package/dist/codegen.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Codegen: scan `appDir/**\/page.md` and emit a single `_agent-pages/manifest`
+ * module holding every doc's content + the site/llms metadata. There are no
+ * per-page `.md` route handlers — the middleware (`decideAgentPages`) serves
+ * markdown inline from this manifest. Runs in plain Node (no bundler hooks —
+ * Turbopack-safe); invoked from `withAgentPages` at config evaluation and from
+ * the dev watcher.
+ *
+ * Safety rails: the manifest is marker-headed; an existing file without the
+ * marker is never overwritten (throw); stale marker-bearing files we used to
+ * generate (old per-doc routes, the rewrites module) are cleaned up;
+ * write-if-changed keeps mtimes stable so watchers don't feed back.
+ */
+/** A standalone doc whose markdown lives in app code, not a `page.md`. */
+export type ExtraDoc = {
+    /** Where the markdown is served — its route handler stays hand-written. */
+    mdPath: string;
+    title: string;
+    description: string;
+    /** Emitted as `import { <export> } from "<module>"` in the manifest. */
+    source: {
+        module: string;
+        export: string;
+    };
+    /** HTML page to rewrite from, or (default) null for markdown-only docs. */
+    htmlPath?: string | null;
+};
+export type GenerateOptions = {
+    siteUrl: string;
+    /** App Router directory to scan (absolute or cwd-relative). */
+    appDir: string;
+    /** `/llms.txt` preamble (before the `## Docs` list). The middleware serves
+     * `/llms.txt` + `/llms-full.txt` from the manifest — codegen only records
+     * this intro for it to use. */
+    llms?: {
+        intro?: string;
+    };
+    extraDocs?: ExtraDoc[];
+};
+export type GenerateResult = {
+    /** Every registered doc (markdown content omitted — it lives in the manifest). */
+    docs: Array<{
+        htmlPath: string | null;
+        mdPath: string;
+        title: string;
+        description: string;
+    }>;
+    /** Files (re)written this run, cwd-relative. */
+    written: string[];
+    /** Stale generated files deleted this run, cwd-relative. */
+    removed: string[];
+    /** `page.md` files skipped (dynamic segments), cwd-relative. */
+    skipped: string[];
+};
+export declare function generateAgentPages(opts: GenerateOptions): GenerateResult;
+//# sourceMappingURL=codegen.d.ts.map

package/dist/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../src/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAaH,0EAA0E;AAC1E,MAAM,MAAM,QAAQ,GAAG;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf;;mCAE+B;IAC/B,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,kFAAkF;IAClF,IAAI,EAAE,KAAK,CAAC;QACV,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,gDAAgD;IAChD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gEAAgE;IAChE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AA6KF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,cAAc,CAgGxE"}

package/dist/codegen.js

@@ -0,0 +1,235 @@
+/**
+ * Codegen: scan `appDir/**\/page.md` and emit a single `_agent-pages/manifest`
+ * module holding every doc's content + the site/llms metadata. There are no
+ * per-page `.md` route handlers — the middleware (`decideAgentPages`) serves
+ * markdown inline from this manifest. Runs in plain Node (no bundler hooks —
+ * Turbopack-safe); invoked from `withAgentPages` at config evaluation and from
+ * the dev watcher.
+ *
+ * Safety rails: the manifest is marker-headed; an existing file without the
+ * marker is never overwritten (throw); stale marker-bearing files we used to
+ * generate (old per-doc routes, the rewrites module) are cleaned up;
+ * write-if-changed keeps mtimes stable so watchers don't feed back.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+/** First line of every generated file — the overwrite/cleanup sentinel. */
+const MARKER = "// @generated by @caprail-dev/agent-pages";
+const HEADER = `${MARKER} — do not edit; regenerated on every \`next dev\`/\`next build\`.
+/* eslint-disable */
+`;
+const rel = (abs) => path.relative(process.cwd(), abs);
+/**
+ * Walk `appDir` collecting `page.md` docs and cleanup candidates (existing
+ * `route.ts` files in `*.md` / llms route dirs, and everything inside
+ * `_agent-pages/`). Skips `_*`/`@*`/dot dirs; descends `(group)` dirs
+ * without adding a URL segment; skips dynamic `[…]` subtrees with a warning.
+ */
+function scan(appDir) {
+    const docs = [];
+    const candidates = [];
+    const skipped = [];
+    const walk = (dir, segments) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name.includes("[")) {
+                    const pageMd = path.join(abs, "page.md");
+                    if (fs.existsSync(pageMd)) {
+                        console.warn(`[agent-pages] skipping ${rel(pageMd)}: dynamic segments are unsupported in v1`);
+                        skipped.push(rel(pageMd));
+                    }
+                    continue;
+                }
+                if (entry.name.startsWith("_") ||
+                    entry.name.startsWith("@") ||
+                    entry.name.startsWith(".")) {
+                    continue;
+                }
+                if (entry.name.startsWith("(") && entry.name.endsWith(")")) {
+                    walk(abs, segments); // route group — no URL segment
+                    continue;
+                }
+                walk(abs, [...segments, entry.name]);
+                continue;
+            }
+            if (entry.name === "route.ts" &&
+                (dir.endsWith(".md") ||
+                    path.basename(dir) === "llms.txt" ||
+                    path.basename(dir) === "llms-full.txt")) {
+                candidates.push(abs);
+            }
+            if (entry.name !== "page.md")
+                continue;
+            const htmlPath = "/" + segments.join("/");
+            const mdPath = htmlPath === "/" ? "/index.md" : `${htmlPath}.md`;
+            const raw = fs.readFileSync(abs, "utf8");
+            const fm = parseFrontmatter(raw, rel(abs));
+            docs.push({
+                htmlPath,
+                mdPath,
+                title: fm.title || mdPath,
+                description: fm.description,
+                markdown: fm.body,
+            });
+        }
+    };
+    walk(appDir, []);
+    // `_agent-pages/` is skipped by the `_*` rule above but is entirely ours —
+    // every `.ts` inside it is a cleanup candidate.
+    const registryDir = path.join(appDir, "_agent-pages");
+    if (fs.existsSync(registryDir)) {
+        for (const name of fs.readdirSync(registryDir)) {
+            if (name.endsWith(".ts"))
+                candidates.push(path.join(registryDir, name));
+        }
+    }
+    return { docs, candidates, skipped };
+}
+/**
+ * Emit `line = value;` / `key: value,` with prettier's break-after-operator
+ * shape when the one-liner would exceed the 80-column print width, so the
+ * generated files are prettier-canonical as written.
+ */
+function fit(indent, prefix, value, suffix) {
+    const oneLine = `${indent}${prefix} ${value}${suffix}`;
+    if (oneLine.length <= 80)
+        return oneLine;
+    return `${indent}${prefix}\n${indent}  ${value}${suffix}`;
+}
+/**
+ * String literal with prettier's quote choice: double quotes unless the
+ * content holds more `"` than `'` (then single quotes need fewer escapes) —
+ * markdown bodies embedding code snippets routinely trip this.
+ */
+function quote(value) {
+    const json = JSON.stringify(value);
+    const doubles = (value.match(/"/g) ?? []).length;
+    const singles = (value.match(/'/g) ?? []).length;
+    if (doubles <= singles)
+        return json;
+    return `'${json.slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'")}'`;
+}
+function manifestModule(siteUrl, intro, docs) {
+    const imports = docs
+        .filter((d) => d.importedAs !== null)
+        .map((d) => `import { ${d.source.export} as ${d.importedAs} } from ${JSON.stringify(d.source.module)};`)
+        .join("\n");
+    const entries = docs
+        .map((d) => {
+        const lines = [
+            "  {",
+            fit("    ", "htmlPath:", d.htmlPath === null ? "null" : JSON.stringify(d.htmlPath), ","),
+            fit("    ", "mdPath:", JSON.stringify(d.mdPath), ","),
+            fit("    ", "title:", quote(d.title), ","),
+            fit("    ", "description:", quote(d.description), ","),
+            fit("    ", "markdown:", d.importedAs ?? quote(d.body ?? ""), ","),
+            "  },",
+        ];
+        return lines.join("\n");
+    })
+        .join("\n");
+    return `${HEADER}import type { AgentDoc } from "@caprail-dev/agent-pages";
+${imports ? "\n" + imports + "\n" : ""}
+export const SITE_URL = ${JSON.stringify(siteUrl)};
+
+${fit("", "export const LLMS_INTRO =", quote(intro), ";")}
+
+export const AGENT_DOCS: AgentDoc[] = [
+${entries}
+];
+`;
+}
+export function generateAgentPages(opts) {
+    const appDir = path.resolve(opts.appDir);
+    if (!fs.existsSync(appDir)) {
+        throw new Error(`[agent-pages] appDir not found: ${opts.appDir}`);
+    }
+    const { docs: scanned, candidates, skipped } = scan(appDir);
+    let extraIdx = 0;
+    const docs = [
+        ...scanned.map((d) => ({ ...d, body: d.markdown, importedAs: null })),
+        ...(opts.extraDocs ?? []).map((d) => ({
+            htmlPath: d.htmlPath ?? null,
+            mdPath: d.mdPath,
+            title: d.title,
+            description: d.description,
+            body: null,
+            importedAs: `extraDoc${extraIdx++}`,
+            source: d.source,
+        })),
+    ].sort((a, b) => (a.mdPath < b.mdPath ? -1 : 1));
+    for (let i = 1; i < docs.length; i++) {
+        if (docs[i].mdPath === docs[i - 1].mdPath) {
+            throw new Error(`[agent-pages] duplicate mdPath ${docs[i].mdPath} — a page.md and an extraDoc collide`);
+        }
+    }
+    // The manifest is the single emitted artifact — the middleware serves every
+    // doc inline from it; there are no per-page route files anymore.
+    const intro = opts.llms?.intro ??
+        `# ${opts.siteUrl}\n\nEvery doc below is served as markdown.`;
+    const emits = new Map([
+        [
+            path.join(appDir, "_agent-pages", "manifest.ts"),
+            manifestModule(opts.siteUrl, intro, docs),
+        ],
+    ]);
+    // Write-if-changed; refuse to overwrite anything we did not generate.
+    const written = [];
+    for (const [abs, content] of emits) {
+        let existing = null;
+        try {
+            existing = fs.readFileSync(abs, "utf8");
+        }
+        catch {
+            // new file
+        }
+        if (existing !== null) {
+            if (!existing.startsWith(MARKER)) {
+                throw new Error(`[agent-pages] refusing to overwrite ${rel(abs)}: file exists and has no @generated marker. Delete or move it first.`);
+            }
+            if (existing === content)
+                continue;
+        }
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, content);
+        written.push(rel(abs));
+    }
+    // Clean up generated files whose source is gone (deleted page.md, llms
+    // disabled, …). Unmarked files — e.g. hand-written routes — are left alone.
+    const removed = [];
+    for (const abs of candidates) {
+        if (emits.has(abs))
+            continue;
+        let existing;
+        try {
+            existing = fs.readFileSync(abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!existing.startsWith(MARKER))
+            continue;
+        fs.rmSync(abs);
+        removed.push(rel(abs));
+        try {
+            fs.rmdirSync(path.dirname(abs)); // only succeeds when empty
+        }
+        catch {
+            // dir not empty — leave it
+        }
+    }
+    return {
+        docs: docs.map(({ htmlPath, mdPath, title, description }) => ({
+            htmlPath,
+            mdPath,
+            title,
+            description,
+        })),
+        written,
+        removed,
+        skipped,
+    };
+}
+//# sourceMappingURL=codegen.js.map

package/dist/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.js","sourceRoot":"","sources":["../src/codegen.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `next.config.js` wrapper: runs codegen when the config is evaluated (every
+ * `next dev` start and `next build` — plain Node, no bundler hooks, so it is
+ * Turbopack-safe by construction) and, in dev, watches for `page.md` changes.
+ *
+ * Note for fresh clones: this module is consumed from the package's compiled
+ * `dist/` — build the package before running bare `next dev`/`next build`.
+ */
+import { type ExtraDoc } from "./codegen.js";
+export type AgentPagesOptions = {
+    /** Canonical origin, e.g. `"https://example.com"` — used in `/llms.txt` links. */
+    siteUrl: string;
+    /** App Router directory; defaults to `src/app` when it exists, else `app`. */
+    appDir?: string;
+    /** `/llms.txt` preamble (before the `## Docs` list); the middleware serves
+     * `/llms.txt` + `/llms-full.txt` from the manifest. */
+    llms?: {
+        intro?: string;
+    };
+    extraDocs?: ExtraDoc[];
+};
+/**
+ * Wrap a Next.js config with agent-pages codegen. Codegen errors (bad
+ * frontmatter, refusal to overwrite an unmarked file) propagate, aborting
+ * `next dev` / `next build` with the message. Returns the config unchanged.
+ */
+export declare function withAgentPages<C extends object>(nextConfig: C, opts: AgentPagesOptions): C;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAEL,KAAK,QAAQ,EAEd,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;2DACuD;IACvD,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;CACxB,CAAC;AAYF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAC7C,UAAU,EAAE,CAAC,EACb,IAAI,EAAE,iBAAiB,GACtB,CAAC,CAuCH"}

package/dist/config.js

@@ -0,0 +1,61 @@
+/**
+ * `next.config.js` wrapper: runs codegen when the config is evaluated (every
+ * `next dev` start and `next build` — plain Node, no bundler hooks, so it is
+ * Turbopack-safe by construction) and, in dev, watches for `page.md` changes.
+ *
+ * Note for fresh clones: this module is consumed from the package's compiled
+ * `dist/` — build the package before running bare `next dev`/`next build`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { clearTimeout, setTimeout } from "node:timers";
+import { generateAgentPages, } from "./codegen.js";
+/** One watcher per process, even though Next evaluates the config repeatedly. */
+const WATCHER_KEY = Symbol.for("@caprail-dev/agent-pages.watcher");
+function report(result) {
+    for (const file of result.written)
+        console.log(`[agent-pages] wrote ${file}`);
+    for (const file of result.removed) {
+        console.log(`[agent-pages] removed ${file}`);
+    }
+}
+/**
+ * Wrap a Next.js config with agent-pages codegen. Codegen errors (bad
+ * frontmatter, refusal to overwrite an unmarked file) propagate, aborting
+ * `next dev` / `next build` with the message. Returns the config unchanged.
+ */
+export function withAgentPages(nextConfig, opts) {
+    const appDir = opts.appDir ?? (fs.existsSync("src/app") ? "src/app" : "app");
+    const run = () => generateAgentPages({
+        siteUrl: opts.siteUrl,
+        appDir,
+        llms: opts.llms,
+        extraDocs: opts.extraDocs,
+    });
+    report(run());
+    if (process.env.NODE_ENV === "development") {
+        const slots = globalThis;
+        if (!slots[WATCHER_KEY]) {
+            slots[WATCHER_KEY] = true;
+            let timer;
+            const watcher = fs.watch(appDir, { recursive: true }, (_event, filename) => {
+                if (!filename || path.basename(filename) !== "page.md")
+                    return;
+                clearTimeout(timer);
+                timer = setTimeout(() => {
+                    try {
+                        report(run());
+                    }
+                    catch (err) {
+                        // A bad edit must not crash the dev server — log and keep watching.
+                        console.error("[agent-pages] codegen failed:", err);
+                    }
+                }, 150);
+                timer.unref();
+            });
+            watcher.unref();
+        }
+    }
+    return nextConfig;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EACL,kBAAkB,GAGnB,MAAM,cAAc,CAAC;AAatB,iFAAiF;AACjF,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;AAEnE,SAAS,MAAM,CAAC,MAAsB;IACpC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC;IAC9E,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAa,EACb,IAAuB;IAEvB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAG,GAAG,EAAE,CACf,kBAAkB,CAAC;QACjB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM;QACN,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;IAEL,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAEd,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,UAAqC,CAAC;QACpD,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;YACxB,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;YAC1B,IAAI,KAAiC,CAAC;YACtC,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CACtB,MAAM,EACN,EAAE,SAAS,EAAE,IAAI,EAAE,EACnB,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE;gBACnB,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,SAAS;oBAAE,OAAO;gBAC/D,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;oBACtB,IAAI,CAAC;wBACH,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;oBAChB,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,oEAAoE;wBACpE,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,GAAG,CAAC,CAAC;oBACtD,CAAC;gBACH,CAAC,EAAE,GAAG,CAAC,CAAC;gBACR,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,CAAC,CACF,CAAC;YACF,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Markdown-first serving core: should a request for an HTML page be served
+ * its markdown twin instead, plus the doc registry shapes that drive the
+ * generated `/llms.txt`, `/llms-full.txt`, and per-doc markdown routes.
+ *
+ * Pure and edge-safe — no request objects, no Node APIs, just primitives —
+ * so it is unit-testable and runs unchanged in the Edge runtime.
+ */
+/** HTML page path → markdown twin path (e.g. `"/" → "/index.md"`). */
+export type MarkdownRewrites = Record<string, string>;
+/**
+ * Whether the `Accept` header asks for markdown at least as strongly as HTML.
+ * Minimal q-value parse: `text/markdown` must be listed explicitly (a bare
+ * `*\/*` is not a markdown preference — browsers send it) with q > 0 and
+ * q(markdown) >= q(html).
+ */
+export declare function prefersMarkdown(accept: string | null): boolean;
+/** The request facts the markdown decision keys off — runtime-agnostic. */
+export type MarkdownRequest = {
+    method: string;
+    accept: string | null;
+    userAgent: string | null;
+    signatureAgent?: string | null;
+    secFetchMode?: string | null;
+};
+/**
+ * Whether this client should be served markdown instead of HTML (path-agnostic
+ * — the caller decides the page has a markdown twin). Markdown wins when, in
+ * order:
+ *
+ * 1. the client asks for it (`Accept: text/markdown`);
+ * 2. the UA classifies as an AI crawler/fetcher — the consumers that want
+ *    markdown. `search` engines (Googlebot, Bingbot, OAI-SearchBot, …) are
+ *    excluded on purpose: serving indexers different content than humans is
+ *    cloaking. `browser` agents (ChatGPT Agent / Atlas) render real pages,
+ *    so they get HTML too — both verdicts are final and skip the heuristics;
+ * 3. the request carries a `Signature-Agent` header (RFC 9421) — AI agents
+ *    that sign their requests (e.g. ChatGPT's) identify themselves this way
+ *    even when their UA looks like a plain browser;
+ * 4. heuristic fallback for agents our classifier doesn't know yet: no
+ *    `sec-fetch-mode` header (real browsers always send it) and a bot-like
+ *    UA — except search/preview bots that need the HTML (see NEEDS_HTML).
+ */
+export declare function clientWantsMarkdown(input: MarkdownRequest): boolean;
+/**
+ * Resolve the markdown rewrite target for a request, or null to serve the page
+ * as-is — the rewrite-style helper for consumers that map an HTML path to a
+ * separate `.md` route. (Caprail's own proxy now serves markdown inline from
+ * the manifest via `decideAgentPages`; this stays for external rewrite setups.)
+ */
+export declare function resolveMarkdownRewrite(input: MarkdownRequest & {
+    pathname: string;
+}, rewrites: MarkdownRewrites): string | null;
+/**
+ * The negotiation headers every markdown-negotiated response varies on —
+ * set on both the rewritten and the HTML branch of a negotiated path so
+ * non-Vercel intermediaries cache them separately.
+ */
+export declare const AGENT_PAGES_VARY = "Accept, User-Agent, Signature-Agent, Sec-Fetch-Mode";
+/** One agent-readable doc — drives the rewrite map, llms.txt, and routes. */
+export type AgentDoc = {
+    /** The HTML page this doc twins, or null when the doc is markdown-only. */
+    htmlPath: string | null;
+    /** Where the markdown is served. */
+    mdPath: string;
+    title: string;
+    /** One-liner for the `/llms.txt` link list ("" when none was provided). */
+    description: string;
+    markdown: string;
+};
+/** `/llms.txt` index per the llmstxt.org convention. */
+export declare function llmsTxt(opts: {
+    siteUrl: string;
+    /** Everything before the `## Docs` section — heading, blockquote, prose. */
+    intro: string;
+    docs: readonly AgentDoc[];
+}): string;
+/** `/llms-full.txt` — every doc's full content in one response. */
+export declare function llmsFullTxt(docs: readonly AgentDoc[]): string;
+/** Shared response shape for all markdown/llms routes. */
+export declare function markdownResponse(body: string): Response;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CA4B9D;AAmBD,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAkBnE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,eAAe,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC7C,QAAQ,EAAE,gBAAgB,GACzB,MAAM,GAAG,IAAI,CAQf;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,wDAC0B,CAAC;AAExD,6EAA6E;AAC7E,MAAM,MAAM,QAAQ,GAAG;IACrB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wDAAwD;AACxD,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC3B,GAAG,MAAM,CAQT;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAE7D;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAOvD"}

package/dist/core.js

@@ -0,0 +1,134 @@
+/**
+ * Markdown-first serving core: should a request for an HTML page be served
+ * its markdown twin instead, plus the doc registry shapes that drive the
+ * generated `/llms.txt`, `/llms-full.txt`, and per-doc markdown routes.
+ *
+ * Pure and edge-safe — no request objects, no Node APIs, just primitives —
+ * so it is unit-testable and runs unchanged in the Edge runtime.
+ */
+import { classify } from "@caprail-dev/analytics";
+/**
+ * Whether the `Accept` header asks for markdown at least as strongly as HTML.
+ * Minimal q-value parse: `text/markdown` must be listed explicitly (a bare
+ * `*\/*` is not a markdown preference — browsers send it) with q > 0 and
+ * q(markdown) >= q(html).
+ */
+export function prefersMarkdown(accept) {
+    if (!accept)
+        return false;
+    let qMd = null;
+    let qHtml = 0;
+    for (const part of accept.toLowerCase().split(",")) {
+        const [type, ...params] = part.split(";");
+        const mediaType = type?.trim();
+        if (!mediaType)
+            continue;
+        let q = 1;
+        for (const param of params) {
+            const [key, value] = param.split("=");
+            if (key?.trim() === "q") {
+                const parsed = Number(value?.trim());
+                if (Number.isFinite(parsed))
+                    q = parsed;
+            }
+        }
+        if (mediaType === "text/markdown") {
+            qMd = Math.max(qMd ?? 0, q);
+        }
+        else if (mediaType === "text/html" ||
+            mediaType === "application/xhtml+xml") {
+            qHtml = Math.max(qHtml, q);
+        }
+    }
+    return qMd !== null && qMd > 0 && qMd >= qHtml;
+}
+/**
+ * Bot-like UA pattern for the heuristic fallback: generic bot vocabulary plus
+ * the HTTP client libraries agent frameworks ride on. Deliberately loose —
+ * it only fires when `sec-fetch-mode` is also absent, and serving markdown
+ * to a misjudged non-AI bot is low-harm.
+ */
+const BOT_LIKE = /bot|crawler|spider|scraper|python-requests|python-httpx|aiohttp|go-http-client|node-fetch|axios|libwww/i;
+/**
+ * Bot-like UAs that must keep getting HTML: search indexers our classifier
+ * doesn't know (serving them markdown is cloaking) and link-preview bots
+ * that read OpenGraph tags from the HTML head.
+ */
+const NEEDS_HTML = /yandex|baidu|duckduckbot|applebot|seznambot|naver|sogou|petalbot|msnbot|slackbot|twitterbot|facebookexternalhit|facebot|discordbot|linkedinbot|whatsapp|telegrambot|pinterest|skypeuripreview|embedly|redditbot/i;
+/**
+ * Whether this client should be served markdown instead of HTML (path-agnostic
+ * — the caller decides the page has a markdown twin). Markdown wins when, in
+ * order:
+ *
+ * 1. the client asks for it (`Accept: text/markdown`);
+ * 2. the UA classifies as an AI crawler/fetcher — the consumers that want
+ *    markdown. `search` engines (Googlebot, Bingbot, OAI-SearchBot, …) are
+ *    excluded on purpose: serving indexers different content than humans is
+ *    cloaking. `browser` agents (ChatGPT Agent / Atlas) render real pages,
+ *    so they get HTML too — both verdicts are final and skip the heuristics;
+ * 3. the request carries a `Signature-Agent` header (RFC 9421) — AI agents
+ *    that sign their requests (e.g. ChatGPT's) identify themselves this way
+ *    even when their UA looks like a plain browser;
+ * 4. heuristic fallback for agents our classifier doesn't know yet: no
+ *    `sec-fetch-mode` header (real browsers always send it) and a bot-like
+ *    UA — except search/preview bots that need the HTML (see NEEDS_HTML).
+ */
+export function clientWantsMarkdown(input) {
+    if (input.method !== "GET" && input.method !== "HEAD")
+        return false;
+    if (prefersMarkdown(input.accept))
+        return true;
+    const agent = classify(input.userAgent);
+    if (agent.isAgent) {
+        return agent.type === "fetcher" || agent.type === "crawler";
+    }
+    if (input.signatureAgent)
+        return true;
+    return (!input.secFetchMode &&
+        !!input.userAgent &&
+        BOT_LIKE.test(input.userAgent) &&
+        !NEEDS_HTML.test(input.userAgent));
+}
+/**
+ * Resolve the markdown rewrite target for a request, or null to serve the page
+ * as-is — the rewrite-style helper for consumers that map an HTML path to a
+ * separate `.md` route. (Caprail's own proxy now serves markdown inline from
+ * the manifest via `decideAgentPages`; this stays for external rewrite setups.)
+ */
+export function resolveMarkdownRewrite(input, rewrites) {
+    // Keys are extensionless page paths only, so a rewritten request (`/index.md`)
+    // can never match again — no rewrite loop. `hasOwn` guards prototype keys.
+    const target = Object.hasOwn(rewrites, input.pathname)
+        ? rewrites[input.pathname]
+        : undefined;
+    if (!target)
+        return null;
+    return clientWantsMarkdown(input) ? target : null;
+}
+/**
+ * The negotiation headers every markdown-negotiated response varies on —
+ * set on both the rewritten and the HTML branch of a negotiated path so
+ * non-Vercel intermediaries cache them separately.
+ */
+export const AGENT_PAGES_VARY = "Accept, User-Agent, Signature-Agent, Sec-Fetch-Mode";
+/** `/llms.txt` index per the llmstxt.org convention. */
+export function llmsTxt(opts) {
+    const links = opts.docs
+        .map((d) => `- [${d.title}](${opts.siteUrl}${d.mdPath})${d.description ? `: ${d.description}` : ""}`)
+        .join("\n");
+    return `${opts.intro.trimEnd()}\n\n## Docs\n\n${links}\n`;
+}
+/** `/llms-full.txt` — every doc's full content in one response. */
+export function llmsFullTxt(docs) {
+    return docs.map((d) => d.markdown.trimEnd()).join("\n\n---\n\n") + "\n";
+}
+/** Shared response shape for all markdown/llms routes. */
+export function markdownResponse(body) {
+    return new Response(body, {
+        headers: {
+            "content-type": "text/markdown; charset=utf-8",
+            "cache-control": "public, max-age=3600, s-maxage=86400",
+        },
+    });
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}

package/dist/frontmatter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Minimal frontmatter for `page.md` files: only `title` and `description`,
+ * `key: value` lines between `---` delimiters. Deliberately not YAML — no
+ * lists, nesting, or multiline values — so there is no dependency and no
+ * surprise parses.
+ */
+export type Frontmatter = {
+    title: string;
+    description: string;
+    /** The markdown with the frontmatter block (and leading blank lines) stripped. */
+    body: string;
+};
+/**
+ * Parse a `page.md` file. Frontmatter is only recognized when the first line
+ * is exactly `---`; the block ends at the next such line. Missing `title`
+ * falls back to the first `# ` heading in the body (warns when even that is
+ * absent); missing `description` warns and yields `""` — its `/llms.txt`
+ * entry will have no summary.
+ */
+export declare function parseFrontmatter(raw: string, sourcePath: string): Frontmatter;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAcF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,CAwC7E"}

package/dist/frontmatter.js

@@ -0,0 +1,58 @@
+/**
+ * Minimal frontmatter for `page.md` files: only `title` and `description`,
+ * `key: value` lines between `---` delimiters. Deliberately not YAML — no
+ * lists, nesting, or multiline values — so there is no dependency and no
+ * surprise parses.
+ */
+/** Strip one layer of matching surrounding quotes from a frontmatter value. */
+function unquote(value) {
+    if (value.length >= 2 &&
+        (value.startsWith('"') || value.startsWith("'")) &&
+        value.endsWith(value[0])) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Parse a `page.md` file. Frontmatter is only recognized when the first line
+ * is exactly `---`; the block ends at the next such line. Missing `title`
+ * falls back to the first `# ` heading in the body (warns when even that is
+ * absent); missing `description` warns and yields `""` — its `/llms.txt`
+ * entry will have no summary.
+ */
+export function parseFrontmatter(raw, sourcePath) {
+    const lines = raw.split(/\r?\n/);
+    const fields = {};
+    let body = raw;
+    if (lines[0]?.trim() === "---") {
+        const end = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+        if (end > 0) {
+            for (const line of lines.slice(1, end)) {
+                const colon = line.indexOf(":");
+                if (colon === -1)
+                    continue;
+                const key = line.slice(0, colon).trim();
+                const value = unquote(line.slice(colon + 1).trim());
+                if (key)
+                    fields[key] = value;
+            }
+            body = lines
+                .slice(end + 1)
+                .join("\n")
+                .replace(/^\n+/, "");
+        }
+    }
+    let title = fields.title ?? "";
+    if (!title) {
+        title = /^# (.+)$/m.exec(body)?.[1]?.trim() ?? "";
+        if (!title) {
+            console.warn(`[agent-pages] ${sourcePath}: no "title" frontmatter and no "# " heading — using the path as title`);
+        }
+    }
+    const description = fields.description ?? "";
+    if (!description) {
+        console.warn(`[agent-pages] ${sourcePath}: no "description" frontmatter — its /llms.txt entry will have no summary`);
+    }
+    return { title, description, body };
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,+EAA+E;AAC/E,SAAS,OAAO,CAAC,KAAa;IAC5B,IACE,KAAK,CAAC,MAAM,IAAI,CAAC;QACjB,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAChD,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,EACzB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,UAAkB;IAC9D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,IAAI,IAAI,GAAG,GAAG,CAAC;IAEf,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,CAAC;QACzE,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACZ,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;gBACvC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAChC,IAAI,KAAK,KAAK,CAAC,CAAC;oBAAE,SAAS;gBAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;gBACxC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBACpD,IAAI,GAAG;oBAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAC/B,CAAC;YACD,IAAI,GAAG,KAAK;iBACT,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC;iBACd,IAAI,CAAC,IAAI,CAAC;iBACV,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAClD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CACV,iBAAiB,UAAU,wEAAwE,CACpG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;IAC7C,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CACV,iBAAiB,UAAU,2EAA2E,CACvG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AACtC,CAAC"}

package/dist/next.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Next.js middleware adapter. `decideAgentPages` returns a decision object
+ * instead of a sealed middleware so apps can compose it with their own
+ * middleware work (e.g. beaconing the served path to analytics);
+ * `createAgentPagesMiddleware` is the batteries-included form.
+ *
+ * The decision serves markdown *inline* from the generated manifest — there
+ * are no per-page `.md` route handlers. A request for an HTML page's markdown
+ * twin (`/terms` from an agent, or a direct `/terms.md`) resolves straight to
+ * the `page.md` content; `/llms.txt` + `/llms-full.txt` are assembled on the
+ * fly. The middleware therefore imports the manifest content; keep doc sets
+ * reasonable (this is the trade for "author only `page.md`, no route files").
+ */
+import { NextResponse, type NextRequest } from "next/server";
+import { type AgentDoc } from "./core.js";
+export type AgentPagesDecision = {
+    kind: "markdown";
+    /** The markdown path being served (`/index.md`, `/terms.md`, …). */
+    mdPath: string;
+    /** The markdown body — hand to `markdownResponse` / `serveAgentPages`. */
+    body: string;
+    /** True when this came from negotiating an HTML page (Vary applies). */
+    negotiated: boolean;
+} | {
+    kind: "html";
+    /** True when the path has a markdown twin (set Vary on the response). */
+    negotiated: boolean;
+};
+/** `/llms.txt` + `/llms-full.txt` config; `false` disables those routes. */
+export type LlmsOption = {
+    siteUrl: string;
+    intro: string;
+} | false;
+/**
+ * Decide what to serve for a request, sourcing content from the manifest docs:
+ *
+ * - `/llms.txt` / `/llms-full.txt` → assembled markdown (unless `llms: false`);
+ * - a direct markdown path (`/terms.md`) → that doc's markdown;
+ * - an HTML page whose twin the client wants as markdown → the twin's markdown;
+ * - anything else → HTML (with `negotiated` set when a twin exists, so the
+ *   caller can add `Vary`).
+ */
+export declare function decideAgentPages(req: NextRequest, docs: readonly AgentDoc[], opts?: {
+    llms?: LlmsOption;
+}): AgentPagesDecision;
+/**
+ * Build the markdown `Response` for a `kind: "markdown"` decision, with `Vary`
+ * set when it came from content negotiation.
+ */
+export declare function serveAgentPages(decision: Extract<AgentPagesDecision, {
+    kind: "markdown";
+}>): Response;
+/** Batteries-included middleware for apps with no other middleware work. */
+export declare function createAgentPagesMiddleware(opts: {
+    docs: readonly AgentDoc[];
+    llms?: LlmsOption;
+}): (req: NextRequest) => Response | NextResponse;
+//# sourceMappingURL=next.d.ts.map

package/dist/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAML,KAAK,QAAQ,EACd,MAAM,WAAW,CAAC;AAEnB,MAAM,MAAM,kBAAkB,GAC1B;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,UAAU,EAAE,OAAO,CAAC;CACrB,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAEN,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAAC;AAEpE;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,SAAS,QAAQ,EAAE,EACzB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,UAAU,CAAA;CAAE,GAC3B,kBAAkB,CAyDpB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,CAAC,kBAAkB,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,GAC1D,QAAQ,CAIV;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB,IACS,KAAK,WAAW,KAAG,QAAQ,GAAG,YAAY,CAOnD"}

package/dist/next.js

@@ -0,0 +1,101 @@
+/**
+ * Next.js middleware adapter. `decideAgentPages` returns a decision object
+ * instead of a sealed middleware so apps can compose it with their own
+ * middleware work (e.g. beaconing the served path to analytics);
+ * `createAgentPagesMiddleware` is the batteries-included form.
+ *
+ * The decision serves markdown *inline* from the generated manifest — there
+ * are no per-page `.md` route handlers. A request for an HTML page's markdown
+ * twin (`/terms` from an agent, or a direct `/terms.md`) resolves straight to
+ * the `page.md` content; `/llms.txt` + `/llms-full.txt` are assembled on the
+ * fly. The middleware therefore imports the manifest content; keep doc sets
+ * reasonable (this is the trade for "author only `page.md`, no route files").
+ */
+import { NextResponse } from "next/server";
+import { AGENT_PAGES_VARY, clientWantsMarkdown, llmsFullTxt, llmsTxt, markdownResponse, } from "./core.js";
+/**
+ * Decide what to serve for a request, sourcing content from the manifest docs:
+ *
+ * - `/llms.txt` / `/llms-full.txt` → assembled markdown (unless `llms: false`);
+ * - a direct markdown path (`/terms.md`) → that doc's markdown;
+ * - an HTML page whose twin the client wants as markdown → the twin's markdown;
+ * - anything else → HTML (with `negotiated` set when a twin exists, so the
+ *   caller can add `Vary`).
+ */
+export function decideAgentPages(req, docs, opts) {
+    const path = req.nextUrl.pathname;
+    const llms = opts?.llms;
+    if (llms && (req.method === "GET" || req.method === "HEAD")) {
+        if (path === "/llms.txt") {
+            return {
+                kind: "markdown",
+                mdPath: path,
+                negotiated: false,
+                body: llmsTxt({ siteUrl: llms.siteUrl, intro: llms.intro, docs }),
+            };
+        }
+        if (path === "/llms-full.txt") {
+            return {
+                kind: "markdown",
+                mdPath: path,
+                negotiated: false,
+                body: llmsFullTxt(docs),
+            };
+        }
+    }
+    // Direct `.md` URL — served regardless of negotiation (agents fetch these
+    // straight from `/llms.txt` links).
+    const direct = docs.find((d) => d.mdPath === path);
+    if (direct) {
+        return {
+            kind: "markdown",
+            mdPath: path,
+            negotiated: false,
+            body: direct.markdown,
+        };
+    }
+    // HTML page with a markdown twin — negotiate.
+    const twin = docs.find((d) => d.htmlPath === path);
+    if (twin) {
+        const wantsMarkdown = clientWantsMarkdown({
+            method: req.method,
+            accept: req.headers.get("accept"),
+            userAgent: req.headers.get("user-agent"),
+            signatureAgent: req.headers.get("signature-agent"),
+            secFetchMode: req.headers.get("sec-fetch-mode"),
+        });
+        if (wantsMarkdown) {
+            return {
+                kind: "markdown",
+                mdPath: twin.mdPath,
+                negotiated: true,
+                body: twin.markdown,
+            };
+        }
+        return { kind: "html", negotiated: true };
+    }
+    return { kind: "html", negotiated: false };
+}
+/**
+ * Build the markdown `Response` for a `kind: "markdown"` decision, with `Vary`
+ * set when it came from content negotiation.
+ */
+export function serveAgentPages(decision) {
+    const res = markdownResponse(decision.body);
+    if (decision.negotiated)
+        res.headers.set("vary", AGENT_PAGES_VARY);
+    return res;
+}
+/** Batteries-included middleware for apps with no other middleware work. */
+export function createAgentPagesMiddleware(opts) {
+    return (req) => {
+        const decision = decideAgentPages(req, opts.docs, { llms: opts.llms });
+        if (decision.kind === "markdown")
+            return serveAgentPages(decision);
+        const res = NextResponse.next();
+        if (decision.negotiated)
+            res.headers.set("vary", AGENT_PAGES_VARY);
+        return res;
+    };
+}
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@caprail-dev/agent-pages",
+  "version": "0.2.0",
+  "description": "Markdown-first pages for AI agents — co-located page.md twins served inline via UA-based content negotiation for Next.js.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/core.js",
+  "types": "./dist/core.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "bun run build",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@caprail-dev/analytics": "^0.5.0"
+  }
+}