@relvehq/agent-ready 0.0.0-stage → 0.3.0

package/dist/cli/init.js

@@ -0,0 +1,366 @@
+"use strict";
+// `agent-ready init`: set a site up in one command
+// (changes/agent-ready-engine, "easy setup"; changes/agent-ready-onboarding,
+// "universal init").
+//
+// detectStack(fs) picks the path (`--stack` skips it):
+//   next       App Router folder + `next` in package.json (or an app/ folder
+//              and no Node server framework, as before): planInit below
+//   wordpress  wp-config.php or wp-content/: planWordPress copies the plugin
+//              bundled in the package to wp-content/plugins/relve-agent-ready/
+//   node       express, connect, polka, fastify, @nestjs/core, h3 or
+//              nitropack in package.json: nothing written, formatNode prints
+//              the lines to add
+//   null       none of these: formatUnknown, exit 1
+//
+// The Next.js path, unchanged:
+// Two steps, kept apart so each can be tested on its own:
+//   planInit(fs)        look at the project, decide every action (no writes)
+//   applyInit(plan, fs) carry the plan out
+//
+// What it sets up (App Router; `src/` layout or not; TS or JS):
+//   agent-ready.config.ts   createAgentReady() with the defaults
+//   middleware.ts           created when there is none; an existing one is
+//                           NEVER edited: the plan prints the two lines to add
+//   app/%5F%5Fmd/[[...path]]/route.ts   the internal Markdown route
+//   .env.local              AGENT_READY_ENABLED=1 (appended once)
+// Re-running is safe: whatever exists is skipped.
+//
+// NODE ONLY through the FS it is given (the planner itself is pure).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WP_PLUGIN_PATH = exports.DETECTION_RULES = exports.STACKS = exports.ONBOARDING_URL = void 0;
+exports.planInit = planInit;
+exports.applyInit = applyInit;
+exports.formatPlan = formatPlan;
+exports.configTemplate = configTemplate;
+exports.middlewareTemplate = middlewareTemplate;
+exports.middlewarePatch = middlewarePatch;
+exports.routeTemplate = routeTemplate;
+exports.nodeFramework = nodeFramework;
+exports.detectStack = detectStack;
+exports.planWordPress = planWordPress;
+exports.formatWordPress = formatWordPress;
+exports.nodeSnippet = nodeSnippet;
+exports.formatNode = formatNode;
+exports.formatUnknown = formatUnknown;
+const join = (...parts) => parts.filter(Boolean).join("/");
+function planInit(fs, opts = {}) {
+    const pkg = opts.pkg ?? "@relvehq/agent-ready";
+    // Where the App Router lives decides where everything else goes.
+    const base = fs.exists("src/app") ? "src" : fs.exists("app") ? "" : null;
+    if (base === null) {
+        return {
+            ok: false,
+            error: "No App Router folder found (app/ or src/app/). Run this in a Next.js project's root.",
+            actions: [],
+        };
+    }
+    const ext = fs.exists("tsconfig.json") ? "ts" : "js";
+    const configFile = join(base, `agent-ready.config.${ext}`);
+    const routeFile = join(base, "app", "%5F%5Fmd", "[[...path]]", `route.${ext}`);
+    const middlewareFile = [join(base, "middleware.ts"), join(base, "middleware.js")].find((p) => fs.exists(p)) ?? null;
+    const actions = [];
+    // A middleware that already imports the package was set up (by hand or by
+    // an earlier run): its config lives wherever that file says.
+    const wired = middlewareFile !== null && /agent-ready/.test(fs.read(middlewareFile));
+    // 1. The config.
+    actions.push(fs.exists(configFile)
+        ? { kind: "skip", path: configFile, note: "config already there" }
+        : wired
+            ? { kind: "skip", path: configFile, note: "your middleware already has an agent-ready config" }
+            : { kind: "create", path: configFile, content: configTemplate(pkg), note: "settings (smart defaults; add `exclude` if needed)" });
+    // 2. The middleware: create, keep, or tell the person what to add.
+    if (!middlewareFile) {
+        const path = join(base, `middleware.${ext}`);
+        actions.push({ kind: "create", path, content: middlewareTemplate(pkg), note: "middleware that serves Markdown to agents" });
+    }
+    else if (wired) {
+        actions.push({ kind: "skip", path: middlewareFile, note: "middleware already uses agent-ready" });
+    }
+    else {
+        actions.push({ kind: "manual", path: middlewareFile, content: middlewarePatch(pkg), note: "you have a middleware: wrap it (2 lines) and add 2 matcher entries" });
+    }
+    // 3. The internal route.
+    actions.push(fs.exists(routeFile)
+        ? { kind: "skip", path: routeFile, note: "Markdown route already there" }
+        : { kind: "create", path: routeFile, content: routeTemplate(pkg), note: "internal route that builds the Markdown" });
+    // 4. The switch, and the site URL (createAgentReady stays off without one).
+    const envFile = ".env.local";
+    const envText = [".env.local", ".env"].filter((f) => fs.exists(f)).map((f) => fs.read(f)).join("\n");
+    const has = (name) => new RegExp(`^\\s*${name}\\s*=`, "m").test(envText);
+    const lines = [
+        has("AGENT_READY_ENABLED") ? null : "AGENT_READY_ENABLED=1",
+        has("NEXT_PUBLIC_SITE_URL") ? null : "NEXT_PUBLIC_SITE_URL=http://localhost:3000",
+    ].filter((l) => !!l);
+    if (!lines.length) {
+        actions.push({ kind: "skip", path: envFile, note: "AGENT_READY_ENABLED and NEXT_PUBLIC_SITE_URL already set" });
+    }
+    else if (!fs.exists(envFile)) {
+        actions.push({ kind: "create", path: envFile, content: lines.join("\n") + "\n", note: `turns it on locally (${lines.map((l) => l.split("=")[0]).join(", ")})` });
+    }
+    else {
+        const text = fs.read(envFile);
+        actions.push({
+            kind: "append",
+            path: envFile,
+            content: (text.endsWith("\n") || text === "" ? "" : "\n") + lines.join("\n") + "\n",
+            note: `turns it on locally (${lines.map((l) => l.split("=")[0]).join(", ")})`,
+        });
+    }
+    return { ok: true, actions };
+}
+/** Write what the plan says. Manual and skip actions are left to the person. */
+function applyInit(plan, fs) {
+    const done = [];
+    if (!plan.ok)
+        return done;
+    for (const a of plan.actions) {
+        if (a.kind === "create" && a.content !== undefined) {
+            fs.write(a.path, a.content);
+            done.push(a.path);
+        }
+        else if (a.kind === "append" && a.content !== undefined) {
+            fs.append(a.path, a.content);
+            done.push(a.path);
+        }
+        else if (a.kind === "copy" && a.from !== undefined) {
+            if (!fs.copy)
+                throw new Error("agent-ready init: this file system cannot copy files");
+            fs.copy(a.from, a.path);
+            done.push(a.path);
+        }
+    }
+    return done;
+}
+/** A plan as lines for the terminal. */
+function formatPlan(plan, dryRun) {
+    if (!plan.ok)
+        return `agent-ready init: ${plan.error}`;
+    const mark = {
+        create: dryRun ? "would create" : "created",
+        append: dryRun ? "would update" : "updated",
+        skip: "kept",
+        manual: "TODO",
+        copy: dryRun ? "would copy" : "copied",
+    };
+    const lines = plan.actions.map((a) => `  ${mark[a.kind].padEnd(12)} ${a.path}  (${a.note})`);
+    const manual = plan.actions.filter((a) => a.kind === "manual");
+    const out = ["agent-ready init", ...lines];
+    for (const m of manual)
+        out.push("", `Add to ${m.path}:`, "", m.content ?? "");
+    out.push("", "Check it (dev server running):", '  curl -i -H "Accept: text/markdown" http://localhost:3000/', "  curl -i http://localhost:3000/index.md", "  curl -i http://localhost:3000/llms.txt", "", "Production: set AGENT_READY_ENABLED=1 (and NEXT_PUBLIC_SITE_URL) in your host's env.", "Dashboard (optional): AGENT_READY_KEY + AGENT_READY_ENDPOINT.");
+    return out.join("\n");
+}
+/* ── templates ──────────────────────────────────────────────────────── */
+function configTemplate(pkg) {
+    return `// Agent-Ready: a clean Markdown version of every page for AI agents.
+// Defaults: site from NEXT_PUBLIC_SITE_URL, on with AGENT_READY_ENABLED=1,
+// common private pages skipped, /llms.txt built from your sitemap.xml.
+import { createAgentReady } from "${pkg}";
+
+export default createAgentReady({
+  // exclude: ["/members"],   // pages never served as Markdown
+});
+`;
+}
+function middlewareTemplate(pkg) {
+    return `import { withAgentReady } from "${pkg}/next";
+import agentReady from "./agent-ready.config";
+
+// Markdown requests (Accept: text/markdown, .md URLs, /llms.txt) go to the
+// agent-ready route; everything else carries on as normal.
+export default withAgentReady(agentReady);
+
+export const config = {
+  matcher: ["/((?!_next/|.*\\\\..*).*)", "/((?!_next/).+\\\\.md)", "/llms.txt"],
+};
+`;
+}
+function middlewarePatch(pkg) {
+    return `// 1. Wrap your middleware:
+import { withAgentReady } from "${pkg}/next";
+import agentReady from "./agent-ready.config";
+export default withAgentReady(agentReady, yourMiddleware);   // instead of exporting yourMiddleware
+
+// 2. Add these two entries to your matcher:
+//    "/((?!_next/).+\\\\.md)", "/llms.txt"`;
+}
+function routeTemplate(pkg) {
+    return `// The internal route agent-ready rewrites Markdown requests to (/__md/...).
+// "%5F" is "_": a folder starting with "_" is private in the App Router.
+import { createMarkdownRoute } from "${pkg}/next/route";
+import agentReady from "../../../agent-ready.config";
+
+export const { GET, HEAD } = createMarkdownRoute(agentReady);
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+`;
+}
+/* ── universal init: which stack is this? ───────────────────────────── */
+/** Where a venture starts: the onboarding page. */
+exports.ONBOARDING_URL = "https://relvehq.com/agent-ready";
+exports.STACKS = ["next", "node", "wordpress"];
+/** package.json dependency -> framework. First match wins (Nest and Nitro bring express / h3 along). */
+const NODE_DEPS = [
+    ["@nestjs/core", "nest"],
+    ["nitropack", "nitro"],
+    ["h3", "h3"],
+    ["fastify", "fastify"],
+    ["express", "express"],
+    ["polka", "polka"],
+    ["connect", "connect"],
+];
+/** What detection looks for, in order (printed when nothing matches). */
+exports.DETECTION_RULES = [
+    "Next.js: app/ or src/app/ with `next` in package.json",
+    "WordPress: wp-config.php or a wp-content/ folder",
+    "Node server: express, connect, polka, fastify, @nestjs/core, h3 or nitropack in package.json",
+];
+/** dependencies + devDependencies of ./package.json; empty when missing or unreadable. */
+function packageDeps(fs) {
+    if (!fs.exists("package.json"))
+        return new Set();
+    try {
+        const pkg = JSON.parse(fs.read("package.json"));
+        const names = (o) => (o && typeof o === "object" ? Object.keys(o) : []);
+        return new Set([...names(pkg.dependencies), ...names(pkg.devDependencies)]);
+    }
+    catch {
+        return new Set();
+    }
+}
+/** The Node server framework package.json names, or null. */
+function nodeFramework(fs) {
+    const deps = packageDeps(fs);
+    return NODE_DEPS.find(([dep]) => deps.has(dep))?.[1] ?? null;
+}
+function detectStack(fs) {
+    const deps = packageDeps(fs);
+    const appDir = fs.exists("src/app") ? "src/app/" : fs.exists("app") ? "app/" : null;
+    const framework = nodeFramework(fs);
+    if (appDir && deps.has("next"))
+        return { stack: "next", why: `${appDir} and next in package.json` };
+    if (fs.exists("wp-config.php"))
+        return { stack: "wordpress", why: "wp-config.php" };
+    if (fs.exists("wp-content"))
+        return { stack: "wordpress", why: "wp-content/" };
+    if (framework)
+        return { stack: "node", framework, why: `${NODE_DEPS.find(([, f]) => f === framework)[0]} in package.json` };
+    // Before universal init, any app/ folder meant Next.js: keep that.
+    if (appDir)
+        return { stack: "next", why: appDir };
+    // Next.js without an App Router folder: planInit says what is missing.
+    if (deps.has("next"))
+        return { stack: "next", why: "next in package.json" };
+    return { stack: null, why: "nothing recognised" };
+}
+/* ── WordPress: copy the bundled plugin ─────────────────────────────── */
+exports.WP_PLUGIN_PATH = "wp-content/plugins/relve-agent-ready";
+function planWordPress(fs, plugin, opts = {}) {
+    // The plugin's own tests never go to a site.
+    const files = (plugin?.files ?? []).filter((f) => !/^tests(\/|$)/.test(f));
+    if (!plugin || !files.includes("relve-agent-ready.php")) {
+        return {
+            ok: false,
+            error: `the WordPress plugin is missing from this copy of the package. Download the zip from ${exports.ONBOARDING_URL}`,
+            actions: [],
+        };
+    }
+    const installed = fs.exists(exports.WP_PLUGIN_PATH);
+    if (installed && !opts.force) {
+        return {
+            ok: true,
+            actions: [{ kind: "skip", path: exports.WP_PLUGIN_PATH, note: "already there, nothing copied; run with --force to replace it" }],
+        };
+    }
+    const dir = plugin.dir.replace(/\\/g, "/").replace(/\/+$/, "");
+    return {
+        ok: true,
+        actions: files.map((f) => ({
+            kind: "copy",
+            path: `${exports.WP_PLUGIN_PATH}/${f}`,
+            from: `${dir}/${f}`,
+            note: installed ? "replaced (--force)" : "plugin file",
+        })),
+    };
+}
+function formatWordPress(plan, dryRun) {
+    if (!plan.ok)
+        return `agent-ready init (WordPress): ${plan.error}`;
+    const mark = (k) => (k === "copy" ? (dryRun ? "would copy" : "copied") : "kept");
+    const copies = plan.actions.filter((a) => a.kind === "copy").length;
+    const out = ["agent-ready init (WordPress)", ...plan.actions.map((a) => `  ${mark(a.kind).padEnd(12)} ${a.path}  (${a.note})`)];
+    if (copies)
+        out.push("", `${copies} file(s) ${dryRun ? "would be copied (dry run: nothing written)" : "copied"}.`);
+    out.push("", "Then, in WordPress admin:", '  1. Plugins: activate "Relve Agent Ready" (it is installed switched off).', "  2. Settings > Agent Ready: tick Enabled, then Save.", "", "Check it (swap in a real post URL):", '  curl -i -H "Accept: text/markdown" https://your-site.com/your-post/', '  curl -i "https://your-site.com/your-post/?format=md"', "", `Guide: ${exports.ONBOARDING_URL}`);
+    return out.join("\n");
+}
+/* ── Node server: print the lines, write nothing ────────────────────── */
+const FRAMEWORK_NAME = {
+    express: "Express",
+    connect: "Connect",
+    polka: "Polka",
+    fastify: "Fastify",
+    nest: "NestJS",
+    h3: "h3",
+    nitro: "Nitro",
+};
+/** The exact lines to add for a framework (null: the Express form, which also fits Connect, Polka and Nest). */
+function nodeSnippet(framework, pkg = "@relvehq/agent-ready") {
+    const imports = [`import { createAgentReady } from "${pkg}";`, `import { agentReadyNode } from "${pkg}/node";`];
+    const mw = "agentReadyNode(createAgentReady({ site: process.env.SITE_URL }))";
+    switch (framework) {
+        case "fastify":
+            return [
+                'import middie from "@fastify/middie";',
+                ...imports,
+                "",
+                "await fastify.register(middie);",
+                `fastify.use(${mw});`,
+            ].join("\n");
+        case "nitro":
+            return [
+                "// server/middleware/agent-ready.ts",
+                'import { fromNodeMiddleware } from "h3";',
+                ...imports,
+                "",
+                `export default fromNodeMiddleware(${mw});`,
+            ].join("\n");
+        case "h3":
+            return ['import { fromNodeMiddleware } from "h3";', ...imports, "", `app.use(fromNodeMiddleware(${mw}));`].join("\n");
+        case "nest":
+            return [...imports, "", "// main.ts, after NestFactory.create(...) and before app.listen(...):", `app.use(${mw});`].join("\n");
+        default:
+            return [...imports, "", `app.use(${mw});`].join("\n");
+    }
+}
+function formatNode(framework, pkg = "@relvehq/agent-ready") {
+    const name = framework ? FRAMEWORK_NAME[framework] : "Node server";
+    const install = framework === "fastify" ? `npm install ${pkg} @fastify/middie` : `npm install ${pkg}`;
+    const indent = (s) => s.split("\n").map((l) => (l ? "  " + l : l)).join("\n");
+    const out = [
+        `agent-ready init (${name}): nothing written. Add these lines yourself.`,
+        "",
+        "1. Install:",
+        `  ${install}`,
+        "",
+        "2. Mount it before static files and routes:",
+        "",
+        indent(nodeSnippet(framework, pkg)),
+    ];
+    if (!framework) {
+        out.push("", "  Express, Connect, Polka and NestJS use that app.use(...) line.", "  Fastify: register @fastify/middie first, then fastify.use(...) with the same middleware.", '  Nitro / h3: wrap it, fromNodeMiddleware(agentReadyNode(...)) from "h3".');
+    }
+    out.push("", "3. Set these env vars (.env locally, your host's settings in production):", "  AGENT_READY_ENABLED=1", "  SITE_URL=https://your-site.com", "", "Check it (server running; change the port to yours):", '  curl -i -H "Accept: text/markdown" http://localhost:3000/', "  curl -i http://localhost:3000/index.md", "  curl -i http://localhost:3000/llms.txt", "", `Guide: ${exports.ONBOARDING_URL}`);
+    return out.join("\n");
+}
+/* ── nothing recognised ─────────────────────────────────────────────── */
+function formatUnknown() {
+    return [
+        "agent-ready init: no supported stack found in this folder. Looked for:",
+        ...exports.DETECTION_RULES.map((r) => `  - ${r}`),
+        "",
+        "Run it in your project's root, or pick one with --stack next|node|wordpress.",
+        `Other stacks (Hono, Bun, Deno, Workers...): ${exports.ONBOARDING_URL}`,
+    ].join("\n");
+}

package/dist/core/accept.d.ts

@@ -0,0 +1,8 @@
+export type Format = "markdown" | "html";
+export interface MediaRange {
+    type: string;
+    subtype: string;
+    q: number;
+}
+export declare function chooseFormat(accept: string | null | undefined): Format;
+export declare function parseAccept(accept: string): MediaRange[];

package/dist/core/accept.js

@@ -0,0 +1,76 @@
+"use strict";
+// Accept-header negotiation: does this request prefer Markdown over HTML?
+//
+// Ported unchanged in behaviour from the Relve Markdown POC
+// (src/lib/mdPoc/accept.ts, checked by scripts/verify-md-poc-accept.mjs).
+// The POC keeps its own copy so its verify script stays independent; the
+// cases are mirrored in packages/agent-ready/test/detect.test.ts.
+//
+// Rule: serve Markdown only when `text/markdown` is listed explicitly and its
+// q-value is greater than or equal to the q-value that applies to `text/html`.
+// Ties go to Markdown (Claude Code, Copilot CLI and Microsoft Copilot send
+// `text/markdown, text/html, */*` at equal weight). Wildcards never select
+// Markdown on their own, but they do count towards HTML's q-value.
+//
+// The user agent is never an input: choosing the format by user agent is the
+// cloaking pattern search engines warn about.
+//
+// EDGE-SAFE. No Node APIs.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chooseFormat = chooseFormat;
+exports.parseAccept = parseAccept;
+// Longer headers are treated as absent (HTML), so a hostile header can't cost
+// much CPU. Real clients send well under 1 KB.
+const MAX_ACCEPT_LENGTH = 4096;
+function chooseFormat(accept) {
+    if (!accept || accept.length > MAX_ACCEPT_LENGTH)
+        return "html";
+    const ranges = parseAccept(accept);
+    const markdownQ = explicitQ(ranges, "text", "markdown");
+    if (markdownQ === undefined || markdownQ <= 0)
+        return "html";
+    return markdownQ >= htmlQ(ranges) ? "markdown" : "html";
+}
+function parseAccept(accept) {
+    const ranges = [];
+    for (const part of accept.split(",")) {
+        const [mediaType = "", ...params] = part.split(";");
+        const [type, subtype, ...rest] = mediaType.trim().toLowerCase().split("/");
+        if (!type || !subtype || rest.length > 0)
+            continue;
+        let q = 1;
+        for (const param of params) {
+            const [name = "", value = ""] = param.split("=");
+            if (name.trim().toLowerCase() !== "q")
+                continue;
+            q = parseQ(value.trim());
+        }
+        ranges.push({ type, subtype, q });
+    }
+    return ranges;
+}
+// RFC 9110 §12.4.2: qvalue = ( "0" [ "." 0*3DIGIT ] ) / ( "1" [ "." 0*3("0") ] ).
+// A malformed q-value makes the range unacceptable (q=0) rather than
+// preferred, so a broken header can never tip the result towards Markdown.
+function parseQ(value) {
+    if (!/^(0(\.\d{0,3})?|1(\.0{0,3})?)$/.test(value))
+        return 0;
+    return Number(value);
+}
+// The highest q given to exactly type/subtype, or undefined if not listed.
+function explicitQ(ranges, type, subtype) {
+    let best;
+    for (const r of ranges) {
+        if (r.type === type && r.subtype === subtype)
+            best = Math.max(best ?? 0, r.q);
+    }
+    return best;
+}
+// The q that applies to text/html: the most specific matching range wins
+// (text/html, then text/*, then */*). Unlisted means 0.
+function htmlQ(ranges) {
+    return (explicitQ(ranges, "text", "html") ??
+        explicitQ(ranges, "text", "*") ??
+        explicitQ(ranges, "*", "*") ??
+        0);
+}

package/dist/core/config.d.ts

@@ -0,0 +1,145 @@
+export type Awaitable<T> = T | Promise<T>;
+/** A Markdown document plus the facts the front matter is built from. */
+export interface MarkdownDoc {
+    markdown: string;
+    title?: string;
+    description?: string;
+    lang?: string;
+    /** Absolute canonical URL of the HTML page; defaults to site + path. */
+    canonical?: string;
+    /** JSON-LD objects found on the page (convert fills this in). */
+    jsonLd?: unknown[];
+}
+/** What a template or store may return. A plain string is the Markdown body. */
+export type DocResult = string | MarkdownDoc | null | undefined;
+export interface TemplateContext {
+    /** Normalised page path, no `.md`, e.g. "/tool/notion". */
+    path: string;
+    /** Named segments from the pattern, e.g. { slug: "notion" } for "/tool/:slug". */
+    params: Record<string, string>;
+    /** Query string of the original request (without `format`), "" or "?a=b". */
+    search: string;
+    request: Request;
+}
+export type TemplateFn = (ctx: TemplateContext) => Awaitable<DocResult>;
+export interface MarkdownStore {
+    get(path: string, ctx: {
+        request: Request;
+    }): Awaitable<DocResult>;
+}
+export interface LlmsEntry {
+    title: string;
+    /** Absolute, or a path resolved against `site`. */
+    url: string;
+    description?: string;
+    /** H2 section the link is listed under. Defaults to "Pages". */
+    section?: string;
+    /** Listed under "## Optional" (llms.txt convention: skippable context). */
+    optional?: boolean;
+    /** Link the `.md` variant of this same-site page. Default true; false for pages the package doesn't serve. */
+    markdown?: boolean;
+}
+export interface LlmsConfig {
+    /** Path the file is served at. Default "/llms.txt". */
+    path?: string;
+    /** H1 of the file: the site or project name. */
+    title: string;
+    /** Blockquote summary under the H1. */
+    summary?: string;
+    /** Free Markdown paragraphs between the summary and the link lists. */
+    details?: string;
+    entries: (ctx: {
+        request: Request;
+    }) => Awaitable<LlmsEntry[]>;
+}
+export type Via = "accept" | "suffix" | "query" | "llms" | "direct";
+export type Source = "native" | "stored" | "convert" | "llms";
+/** One served (or refused) Markdown request, passed to `onHit`. */
+export interface HitEvent {
+    ts: string;
+    host: string | null;
+    path: string;
+    via: Via;
+    source: Source | null;
+    status: number;
+    tokens: number | null;
+    bytes: number | null;
+    userAgent: string | null;
+    accept: string | null;
+    durationMs: number;
+}
+export interface AgentReadyConfig {
+    /** Public origin of the site, e.g. "https://relvehq.com". Used for canonicals and links. */
+    site: string;
+    /** Extra path prefixes (segment-aware) or RegExps never served as Markdown. */
+    exclude?: Array<string | RegExp>;
+    /** Native templates by route pattern ("/tool/:slug", "/docs/*"). First match wins. */
+    templates?: Record<string, TemplateFn>;
+    /** Stored Markdown lookup, tried after templates. */
+    store?: MarkdownStore | null;
+    /** What to do when no template or stored doc exists. Default "convert". */
+    fallback?: "convert" | "none";
+    /**
+     * Cache-Control for Markdown served at its own URL (`.md`, `?format=md`,
+     * the internal path, llms.txt). Default "public, s-maxage=300, stale-while-revalidate=86400".
+     */
+    cacheControl?: string;
+    /**
+     * Cache-Control for Markdown negotiated by Accept on the page's own URL.
+     * Default "private, max-age=300": most CDNs (CloudFront included) do not
+     * key on Accept, so a shared cache must never store this variant or it
+     * would be served to browsers. See README "Caching".
+     */
+    negotiatedCacheControl?: string;
+    /** llms.txt generation. Null/undefined = the package does not serve one. */
+    llms?: LlmsConfig | null;
+    /** Fire-and-forget logger. Errors are swallowed. */
+    onHit?: (event: HitEvent) => Awaitable<void>;
+    /** Master switch. Default false: nothing happens until a venture opts in. */
+    enabled?: boolean | ((request: Request) => boolean);
+    /** Internal rewrite prefix. Default "/__md". */
+    internalPrefix?: string;
+    /** Header marking the package's own origin fetch. Default "x-agent-ready-internal". */
+    internalHeader?: string;
+    /** Origin the converter fetches HTML from. Default: derived from the request's host. */
+    fetchOrigin?: (request: Request) => string;
+    /** Origin fetch timeout. Default 8000 ms. */
+    fetchTimeoutMs?: number;
+    /** Quality gate: converted Markdown with less plain text than this is discarded. Default 200. */
+    minChars?: number;
+}
+export interface ResolvedAgentReadyConfig {
+    readonly __resolved: true;
+    site: string;
+    exclude: Array<string | RegExp>;
+    templates: Record<string, TemplateFn>;
+    store: MarkdownStore | null;
+    fallback: "convert" | "none";
+    cacheControl: string;
+    negotiatedCacheControl: string;
+    llms: (LlmsConfig & {
+        path: string;
+    }) | null;
+    onHit: ((event: HitEvent) => Awaitable<void>) | null;
+    enabled: boolean | ((request: Request) => boolean);
+    internalPrefix: string;
+    internalHeader: string;
+    fetchOrigin: ((request: Request) => string) | null;
+    fetchTimeoutMs: number;
+    minChars: number;
+}
+/** Never served as Markdown, whatever the venture's config says. */
+export declare const ALWAYS_EXCLUDE: readonly string[];
+export declare const DEFAULT_CACHE_CONTROL = "public, s-maxage=300, stale-while-revalidate=86400";
+export declare const DEFAULT_NEGOTIATED_CACHE_CONTROL = "private, max-age=300";
+export declare const DEFAULT_INTERNAL_PREFIX = "/__md";
+export declare const DEFAULT_INTERNAL_HEADER = "x-agent-ready-internal";
+/** Request header the middleware adapter sets on its rewrite: how Markdown was asked for. */
+export declare const VIA_HEADER = "x-agent-ready-via";
+export declare function defineAgentReady(config: AgentReadyConfig | ResolvedAgentReadyConfig): ResolvedAgentReadyConfig;
+/** The master switch. A throwing `enabled` function counts as off. */
+export declare function isEnabled(cfg: ResolvedAgentReadyConfig, request: Request): boolean;
+/** Segment-aware prefix match: "/admin" excludes "/admin" and "/admin/x", not "/administrator". */
+export declare function isExcluded(cfg: ResolvedAgentReadyConfig, path: string): boolean;
+/** Fire-and-forget: never awaited by callers, never throws. */
+export declare function emitHit(cfg: ResolvedAgentReadyConfig, event: HitEvent): void;