@ctcstack/ctcdocs-core 0.16.2 → 0.18.0

package/README.md

@@ -3,6 +3,8 @@
 The configuration layer shared by the [CTCDocs](https://github.com/ctcstack/ctcdocs)
 packages: the schema of a project's `site.config.json`, the fixed project
 layout, and the allowlist of paths the synchronization pipeline may write.
+Its `published-markdown` entry serializes a page's Markdown version, which
+the site serves and the sync measures.
 
 A project does not install this package directly — `@ctcstack/ctcdocs` and
 `@ctcstack/ctcdocs-sync` depend on it. It is documented because what it

package/dist/corpus-structure.d.ts

@@ -19,6 +19,12 @@ export interface CorpusDocument {
      * on its new chain to be confirmed.
      */
     readonly publishedReaders?: '*' | readonly string[];
+    /** The permanent short ID (ADR-022), the title and Drive's modified time. */
+    readonly shortId?: string;
+    readonly title?: string;
+    readonly modified?: string;
+    /** The Google Doc or PDF in Drive, as the page links it. */
+    readonly source?: string;
 }
 export interface CorpusStructure {
     readonly rootFolderId: string | null;

package/dist/corpus-structure.js

@@ -57,11 +57,23 @@ export function parseCorpusStructure(manifest) {
     const documents = new Map();
     for (const [id, raw] of entries(source.documents, 'documents')) {
         const path = `documents.${id}`;
-        const published = raw.publishedReaders;
+        const record = raw;
+        const published = record.publishedReaders;
+        const optional = (key) => typeof record[key] === 'string' && record[key].length > 0
+            ? record[key]
+            : undefined;
+        const shortId = optional('shortId');
+        const title = optional('displayTitle');
+        const modified = optional('googleModifiedTime');
+        const source = optional('sourceUrl');
         documents.set(id, {
             id,
             parentId: field(raw, 'googleParentId', path, true),
             slug: field(raw, 'stableSlug', path) ?? '',
+            ...(shortId ? { shortId } : {}),
+            ...(title ? { title } : {}),
+            ...(modified ? { modified } : {}),
+            ...(source ? { source } : {}),
             ...(published === '*' ||
                 (Array.isArray(published) &&
                     published.every((group) => typeof group === 'string'))

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { ACCESS_CLASSES_ROUTE, GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, PLATFORM_WORKERS, permanentLinkPath, PROJECT_LAYOUT, RESERVED_SLUGS, SHORT_ID_PATTERN, } from './project-layout.js';
+export { ACCESS_CLASSES_ROUTE, GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, markdownProjectionPath, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, PLATFORM_WORKERS, permanentLinkPath, PROJECT_LAYOUT, RESERVED_SLUGS, resolvePermanentLink, SHORT_ID_PATTERN, } from './project-layout.js';
 export { assertGeneratedPathAllowed, isGeneratedPathAllowed, normalizeRepositoryPath, } from './generated-paths.js';
 export { generatedMarkdownHeader, generatedSourceHeader, } from './ownership-markers.js';
 export { findProjectRoot, ProjectRootError } from './project-root.js';
@@ -10,5 +10,5 @@ export { ADMINS_CLASS, chainReaders, chainRules, classIdentifiers, computeAccess
 export type { AccessClass, AccessModel, ChainReaders, PublishedReaders, Readers, } from './access-classes.js';
 export { accessFindings } from './access-findings.js';
 export type { AccessFinding } from './access-findings.js';
-export { loadSiteConfiguration, parseSiteConfiguration, SiteConfigurationError, } from './site-configuration.js';
-export type { AddressPolicy, BrandConfiguration, DeploymentConfiguration, DeploymentEnvironmentConfiguration, DeploymentEnvironmentConfigurations, DeploymentVisibility, HomeConfiguration, NavigationConfiguration, SignInConfiguration, SiteConfiguration, SyncConfigurationDefaults, } from './site-configuration.js';
+export { fetchCharacterLimit, loadSiteConfiguration, MCP_DEFAULTS, parseSiteConfiguration, SiteConfigurationError, } from './site-configuration.js';
+export type { AddressPolicy, BrandConfiguration, DeploymentConfiguration, DeploymentEnvironmentConfiguration, DeploymentEnvironmentConfigurations, DeploymentVisibility, HomeConfiguration, McpConfiguration, McpSearchConfiguration, NavigationConfiguration, SignInConfiguration, SiteConfiguration, SyncConfigurationDefaults, } from './site-configuration.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { ACCESS_CLASSES_ROUTE, GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, PLATFORM_WORKERS, permanentLinkPath, PROJECT_LAYOUT, RESERVED_SLUGS, SHORT_ID_PATTERN, } from './project-layout.js';
+export { ACCESS_CLASSES_ROUTE, GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, markdownProjectionPath, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, PLATFORM_WORKERS, permanentLinkPath, PROJECT_LAYOUT, RESERVED_SLUGS, resolvePermanentLink, SHORT_ID_PATTERN, } from './project-layout.js';
 export { assertGeneratedPathAllowed, isGeneratedPathAllowed, normalizeRepositoryPath, } from './generated-paths.js';
 export { generatedMarkdownHeader, generatedSourceHeader, } from './ownership-markers.js';
 export { findProjectRoot, ProjectRootError } from './project-root.js';
@@ -6,4 +6,4 @@ export { EVERY_MEMBER, parseAccessConfiguration, } from './access-configuration.
 export { CorpusStructureError, EMPTY_CORPUS, parseCorpusStructure, readCorpusStructure, } from './corpus-structure.js';
 export { ADMINS_CLASS, chainReaders, chainRules, classIdentifiers, computeAccessModel, documentClass, folderChain, folderClass, intersectReaders, MEMBERS_CLASS, nextPublishedReaders, widensReaders, } from './access-classes.js';
 export { accessFindings } from './access-findings.js';
-export { loadSiteConfiguration, parseSiteConfiguration, SiteConfigurationError, } from './site-configuration.js';
+export { fetchCharacterLimit, loadSiteConfiguration, MCP_DEFAULTS, parseSiteConfiguration, SiteConfigurationError, } from './site-configuration.js';

package/dist/project-layout.d.ts

@@ -80,6 +80,16 @@ export declare const PLATFORM_WORKERS: {
     readonly accessMapAlias: "ctcdocs-access-map";
     readonly stateBinding: "KB_STATE";
     readonly directorySchedule: "*/10 * * * *";
+    /** The MCP server's OAuth state; the library requires this name (ADR-041). */
+    readonly oauthBinding: "OAUTH_KV";
+    /** The R2 bucket the Worker publishes each document's Markdown to. */
+    readonly documentsBinding: "KB_DOCUMENTS";
+    /** The AI Search instance that indexes that bucket. */
+    readonly searchBinding: "KB_SEARCH";
+    /** How often the site's Worker checks that the bucket matches its build. */
+    readonly publishSchedule: "*/5 * * * *";
+    /** Lets the OAuth library fetch a client's metadata document safely. */
+    readonly oauthCompatibilityFlag: "global_fetch_strictly_public";
 };
 /**
  * Where the Worker tells a signed-in reader which search bundles, beyond the
@@ -100,5 +110,25 @@ export declare const RESERVED_SLUGS: readonly string[];
 export declare const SHORT_ID_PATTERN: RegExp;
 /** The site-relative permanent link of an item with this short ID. */
 export declare function permanentLinkPath(shortId: string): string;
+/**
+ * Renders a permanent link as the address it currently leads to.
+ *
+ * The sync writes a link between two documents as the target's permanent
+ * link, `/d/<short ID>/`, so the document holding it never changes when the
+ * target is renamed or moved (ADR-022). The redirect map says where each one
+ * leads today. Resolving it while the site builds sends a reader straight to
+ * the page instead of through a redirect page on every click.
+ *
+ * A permanent link the map does not know is left as it is: it is either a
+ * hand-written link to nothing, which the sync already refuses for generated
+ * pages, or one a later build will know.
+ */
+export declare function resolvePermanentLink(value: string, redirects: Readonly<Record<string, string>>): string | undefined;
+/**
+ * The site path of a page's Markdown version, from its route ID (ADR-010):
+ * the one definition, shared by the route that serves it, the pages that link
+ * it and the sync that measures it.
+ */
+export declare function markdownProjectionPath(slug: string): string;
 export declare const GENERATED_DIRECTORY_ALLOWLIST: readonly ["src/content/docs/_generated", "src/assets/generated", "src/generated"];
 export declare const GENERATED_FILE_ALLOWLIST: readonly ["data/sync-manifest.json", "data/docs-index.json", "data/latest-sync-report.json", "data/title-report.json"];

package/dist/project-layout.js

@@ -80,6 +80,16 @@ export const PLATFORM_WORKERS = {
     accessMapAlias: 'ctcdocs-access-map',
     stateBinding: 'KB_STATE',
     directorySchedule: '*/10 * * * *',
+    /** The MCP server's OAuth state; the library requires this name (ADR-041). */
+    oauthBinding: 'OAUTH_KV',
+    /** The R2 bucket the Worker publishes each document's Markdown to. */
+    documentsBinding: 'KB_DOCUMENTS',
+    /** The AI Search instance that indexes that bucket. */
+    searchBinding: 'KB_SEARCH',
+    /** How often the site's Worker checks that the bucket matches its build. */
+    publishSchedule: '*/5 * * * *',
+    /** Lets the OAuth library fetch a client's metadata document safely. */
+    oauthCompatibilityFlag: 'global_fetch_strictly_public',
 };
 /**
  * Where the Worker tells a signed-in reader which search bundles, beyond the
@@ -93,8 +103,10 @@ export const PLATFORM_ROUTE_HREFS = {
 };
 /**
  * Top-level addresses the platform serves beside the corpus: the Worker's
- * sign-in routes (ADR-038), the search bundles, `/pagefind/` and
- * `/pagefind-<class>/` (ADR-039), and the original files under `/assets/`.
+ * sign-in and OAuth routes (ADR-038, ADR-041), the search bundles,
+ * `/pagefind/` and `/pagefind-<class>/` (ADR-039), and the original files
+ * under `/assets/`. The MCP server needs none: it answers `/mcp` exactly
+ * (ADR-041), and a page is always served under its trailing slash.
  */
 const SERVED_ADDRESSES = ['auth', 'pagefind', 'assets'];
 export const RESERVED_SLUGS = Object.freeze([
@@ -111,6 +123,38 @@ export const SHORT_ID_PATTERN = /^[0-9a-f]{6,64}$/u;
 export function permanentLinkPath(shortId) {
     return `/${PLATFORM_ROUTES.permanentLinks}/${shortId}/`;
 }
+/**
+ * Renders a permanent link as the address it currently leads to.
+ *
+ * The sync writes a link between two documents as the target's permanent
+ * link, `/d/<short ID>/`, so the document holding it never changes when the
+ * target is renamed or moved (ADR-022). The redirect map says where each one
+ * leads today. Resolving it while the site builds sends a reader straight to
+ * the page instead of through a redirect page on every click.
+ *
+ * A permanent link the map does not know is left as it is: it is either a
+ * hand-written link to nothing, which the sync already refuses for generated
+ * pages, or one a later build will know.
+ */
+export function resolvePermanentLink(value, redirects) {
+    const prefix = `/${PLATFORM_ROUTES.permanentLinks}/`;
+    if (!value.startsWith(prefix)) {
+        return undefined;
+    }
+    const suffixStart = value.search(/[?#]/u);
+    const path = suffixStart < 0 ? value : value.slice(0, suffixStart);
+    const suffix = suffixStart < 0 ? '' : value.slice(suffixStart);
+    const target = redirects[path.endsWith('/') ? path : `${path}/`];
+    return target === undefined ? undefined : `${target}${suffix}`;
+}
+/**
+ * The site path of a page's Markdown version, from its route ID (ADR-010):
+ * the one definition, shared by the route that serves it, the pages that link
+ * it and the sync that measures it.
+ */
+export function markdownProjectionPath(slug) {
+    return `/${slug}/index.md`;
+}
 export const GENERATED_DIRECTORY_ALLOWLIST = [
     PROJECT_LAYOUT.generatedDocumentsDirectory,
     PROJECT_LAYOUT.generatedAssetsDirectory,

package/dist/published-markdown.d.ts

@@ -0,0 +1,44 @@
+export interface PublishedMarkdownInput {
+    title: string;
+    /**
+     * The ownership marker the generated file opens with, which is stripped from
+     * the published form. It is passed in rather than read from the project so
+     * this stays a pure function of its input.
+     */
+    ownershipHeader: string;
+    sourceUrl: string;
+    /** The published PDF, when the page is one's and the site serves it. */
+    fileUrl?: string;
+    googleModifiedTime: string;
+    syncedAt: string;
+    contentHash: string;
+    body: string;
+    stableSlugs: ReadonlySet<string>;
+    /**
+     * Each permanent link, `/d/<short ID>/`, to the address it leads to. A link
+     * between documents is stored as one (ADR-022); the projection names the
+     * target's own Markdown instead, as it does for any other corpus link.
+     */
+    permanentLinks: Readonly<Record<string, string>>;
+}
+/** Where the site serves a published PDF, as its Markdown version names it. */
+export declare function publishedFileUrl(googleFileId: string, file: string): string;
+/**
+ * One line of inline Markdown that reads as the text it was given: whitespace,
+ * newlines included, collapses to single spaces, and every character that
+ * would open emphasis, code, a link, HTML or a heading is escaped. Used for
+ * titles, which come from Drive names and may contain any of them.
+ */
+export declare function inlineMarkdown(value: string): string;
+/**
+ * The page's Markdown without its front matter: its title as a heading and
+ * its body. It is what the MCP server stores, indexes and returns from
+ * `fetch` (ADR-042), so it is also what the sync measures (ADR-043).
+ */
+export declare function publishedMarkdownBody(input: Pick<PublishedMarkdownInput, 'title' | 'ownershipHeader' | 'body' | 'stableSlugs' | 'permanentLinks'>): string;
+/**
+ * The page's Markdown version (ADR-010): front matter, then
+ * `publishedMarkdownBody`. Each front matter value is one JSON string, so no
+ * value spans a line and the first `---` line after the opening one closes it.
+ */
+export declare function serializePublishedMarkdown(input: PublishedMarkdownInput): string;

package/dist/published-markdown.js

@@ -0,0 +1,132 @@
+import * as cheerio from 'cheerio';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import remarkStringify from 'remark-stringify';
+import { unified } from 'unified';
+import { markdownProjectionPath, resolvePermanentLink, } from './project-layout.js';
+const processor = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkStringify, {
+    bullet: '-',
+    emphasis: '*',
+    fences: true,
+    listItemIndent: 'one',
+    strong: '*',
+});
+function walk(node, visit) {
+    if (node.type !== 'root') {
+        visit(node);
+    }
+    if ('children' in node) {
+        for (const child of node.children) {
+            walk(child, visit);
+        }
+    }
+}
+function markdownUrl(value, stableSlugs, permanentLinks) {
+    const resolved = resolvePermanentLink(value, permanentLinks);
+    const link = resolved ?? value;
+    if (!link.startsWith('/')) {
+        return resolved;
+    }
+    let url;
+    try {
+        url = new URL(link, 'https://wiki.invalid');
+    }
+    catch {
+        return resolved;
+    }
+    const slug = url.pathname.replace(/^\/+|\/+$/gu, '');
+    if (!stableSlugs.has(slug)) {
+        return resolved;
+    }
+    return `${markdownProjectionPath(slug)}${url.search}${url.hash}`;
+}
+function rewriteInternalLinks(body, stableSlugs, permanentLinks) {
+    const tree = processor.parse(body);
+    walk(tree, (node) => {
+        if (node.type === 'link') {
+            node.url = markdownUrl(node.url, stableSlugs, permanentLinks) ?? node.url;
+            return;
+        }
+        if (node.type !== 'html') {
+            return;
+        }
+        const $ = cheerio.load(node.value, null, false);
+        let changed = false;
+        $('a[href]').each((_, anchor) => {
+            const href = $(anchor).attr('href');
+            const rewritten = href
+                ? markdownUrl(href, stableSlugs, permanentLinks)
+                : undefined;
+            if (rewritten) {
+                $(anchor).attr('href', rewritten);
+                changed = true;
+            }
+        });
+        if (changed) {
+            node.value = $.root().html() ?? '';
+        }
+    });
+    return processor.stringify(tree).trimEnd();
+}
+function cleanBody(body, ownershipHeader) {
+    const normalized = body.replace(/\r\n?/gu, '\n');
+    if (normalized !== ownershipHeader &&
+        !normalized.startsWith(`${ownershipHeader}\n`)) {
+        throw new Error('Generated Google document is missing the expected ownership marker.');
+    }
+    return normalized.slice(ownershipHeader.length).trim();
+}
+/** Where the site serves a published PDF, as its Markdown version names it. */
+export function publishedFileUrl(googleFileId, file) {
+    return `/assets/generated/${googleFileId}/${file}`;
+}
+function yamlString(value) {
+    return JSON.stringify(value);
+}
+/**
+ * One line of inline Markdown that reads as the text it was given: whitespace,
+ * newlines included, collapses to single spaces, and every character that
+ * would open emphasis, code, a link, HTML or a heading is escaped. Used for
+ * titles, which come from Drive names and may contain any of them.
+ */
+export function inlineMarkdown(value) {
+    return value
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .replace(/([\\`*_[\]<>#])/gu, '\\$1');
+}
+/**
+ * The page's Markdown without its front matter: its title as a heading and
+ * its body. It is what the MCP server stores, indexes and returns from
+ * `fetch` (ADR-042), so it is also what the sync measures (ADR-043).
+ */
+export function publishedMarkdownBody(input) {
+    const body = rewriteInternalLinks(cleanBody(input.body, input.ownershipHeader), input.stableSlugs, input.permanentLinks);
+    return [
+        `# ${inlineMarkdown(input.title)}`,
+        '',
+        ...(body ? [body, ''] : []),
+    ].join('\n');
+}
+/**
+ * The page's Markdown version (ADR-010): front matter, then
+ * `publishedMarkdownBody`. Each front matter value is one JSON string, so no
+ * value spans a line and the first `---` line after the opening one closes it.
+ */
+export function serializePublishedMarkdown(input) {
+    return [
+        '---',
+        `title: ${yamlString(input.title)}`,
+        `source_url: ${yamlString(input.sourceUrl)}`,
+        ...(input.fileUrl ? [`file_url: ${yamlString(input.fileUrl)}`] : []),
+        `modified_at: ${yamlString(input.googleModifiedTime)}`,
+        `synced_at: ${yamlString(input.syncedAt)}`,
+        `content_hash: ${yamlString(input.contentHash)}`,
+        '---',
+        '',
+        publishedMarkdownBody(input),
+    ].join('\n');
+}

package/dist/site-configuration.d.ts

@@ -94,6 +94,13 @@ export interface SyncConfigurationDefaults {
      * project sets the line it wants numbers for. Defaults to 2.
      */
     readonly largeImageMegabytes: number;
+    /**
+     * The length, in characters of a document's Markdown body, above which the
+     * sync report notes the document as worth splitting (ADR-043). No greater
+     * than the characters an assistant reads of a document; defaults to 40,000,
+     * or to that limit where it is lower.
+     */
+    readonly largeDocumentCharacters: number;
 }
 export interface NavigationConfiguration {
     /**
@@ -135,9 +142,66 @@ export type AddressPolicy = 'stable' | 'follow-names';
 export interface SignInConfiguration {
     readonly workspaceDomains: readonly string[];
 }
+/**
+ * How the MCP server searches and how much a search returns (ADR-042). Every
+ * value has a default, the starting point ADR-042 records, so that a project
+ * tunes it against its own corpus without a new version of the platform.
+ */
+export interface McpSearchConfiguration {
+    /** Chunks asked of AI Search for each query: 1 to 50. */
+    readonly chunks: number;
+    /**
+     * The vector similarity below which AI Search drops a chunk, 0 to 1. It
+     * drops only chunks vector search alone found, and AI Search ignores it
+     * while reranking is on (ADR-042), so it acts only with reranking off.
+     */
+    readonly vectorThreshold: number;
+    /** Whether a keyword match needs every word of the query, or any. */
+    readonly keywordMatch: 'and' | 'or';
+    /**
+     * Neighbouring chunks AI Search joins to each side of a match: 0 to 3. A
+     * chunk of AI Search's default size is already longer than a passage.
+     */
+    readonly contextChunks: number;
+    readonly reranking: {
+        readonly enabled: boolean;
+        /** An AI Search reranking model. */
+        readonly model: string;
+        /** The reranking score below which a chunk is dropped, 0 to 1. */
+        readonly threshold: number;
+    };
+    /** Documents a search returns at most; no more than `chunks`. */
+    readonly results: number;
+    /** Passages each document shows at most. */
+    readonly passagesPerResult: number;
+    /** Characters of passage text one search returns at most, in all. */
+    readonly passageCharacters: number;
+}
+/**
+ * The MCP server through which AI assistants read the site as the person who
+ * connected them (ADR-041). It needs the Worker's sign-in, so it is accepted
+ * only on a deployment whose every environment is private.
+ */
+export interface McpConfiguration {
+    readonly enabled: boolean;
+    readonly search: McpSearchConfiguration;
+    /** Characters `fetch` returns at most; a longer document is cut there. */
+    readonly fetchCharacters: number;
+}
+/** What `mcp` holds when a project sets only `enabled` (ADR-042). */
+export declare const MCP_DEFAULTS: Omit<McpConfiguration, 'enabled'>;
+/**
+ * The characters an assistant reads of a document: the cut `fetch` makes
+ * (ADR-042), or its default while the MCP server is off. The build writes
+ * this value into the access map and the sync measures documents against it
+ * (ADR-043), so the two never derive it apart.
+ */
+export declare function fetchCharacterLimit(mcp: McpConfiguration | undefined): number;
 export interface SiteConfiguration {
     /** Required to serve a private environment through the platform's Worker. */
     readonly signIn?: SignInConfiguration;
+    /** Absent or disabled, the Worker serves no MCP or OAuth route. */
+    readonly mcp?: McpConfiguration;
     /**
      * Who may read which folder (ADR-039). Absent, every document is open to
      * every reader the deployment admits, as before access rules existed.

package/dist/site-configuration.js

@@ -15,6 +15,37 @@ import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { parseAccessConfiguration, } from './access-configuration.js';
 import { PROJECT_LAYOUT } from './project-layout.js';
+/** What `mcp` holds when a project sets only `enabled` (ADR-042). */
+export const MCP_DEFAULTS = Object.freeze({
+    search: Object.freeze({
+        chunks: 50,
+        vectorThreshold: 0.2,
+        keywordMatch: 'or',
+        contextChunks: 0,
+        reranking: Object.freeze({
+            enabled: true,
+            model: '@cf/baai/bge-reranker-base',
+            threshold: 0,
+        }),
+        results: 10,
+        passagesPerResult: 3,
+        passageCharacters: 24_000,
+    }),
+    fetchCharacters: 100_000,
+});
+/**
+ * The characters an assistant reads of a document: the cut `fetch` makes
+ * (ADR-042), or its default while the MCP server is off. The build writes
+ * this value into the access map and the sync measures documents against it
+ * (ADR-043), so the two never derive it apart.
+ */
+export function fetchCharacterLimit(mcp) {
+    return mcp?.enabled ? mcp.fetchCharacters : MCP_DEFAULTS.fetchCharacters;
+}
+/** About 10,000 tokens of English: a starting value, not a measured one. */
+const LARGE_DOCUMENT_CHARACTERS = 40_000;
+/** A passage of fewer characters than this says too little to judge by. */
+const SHORTEST_PASSAGE = 100;
 export class SiteConfigurationError extends Error {
     name = 'SiteConfigurationError';
 }
@@ -136,6 +167,73 @@ function optionalCount(source, key, path, fallback) {
     return value;
 }
 /** A size above zero, in megabytes; a fraction such as 1.5 is allowed. */
+/** A number between `min` and `max`, whole when `whole`, or the fallback. */
+function optionalNumber(source, key, path, fallback, { min, max, whole }) {
+    const value = source[key];
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== 'number' ||
+        !Number.isFinite(value) ||
+        (whole && !Number.isInteger(value)) ||
+        value < min ||
+        (max !== undefined && value > max)) {
+        const kind = whole ? 'a whole number' : 'a number';
+        fail(path, max === undefined
+            ? `must be ${kind} of at least ${min}`
+            : `must be ${kind} from ${min} to ${max}`);
+    }
+    return value;
+}
+/** Fails on a key the section does not define. */
+function knownKeys(source, path, keys) {
+    for (const key of Object.keys(source)) {
+        if (!keys.includes(key)) {
+            fail(`${path}.${key}`, 'is not a known setting');
+        }
+    }
+}
+function mcpSearch(value) {
+    const defaults = MCP_DEFAULTS.search;
+    if (value === undefined) {
+        return defaults;
+    }
+    const source = record(value, 'mcp.search');
+    knownKeys(source, 'mcp.search', Object.keys(defaults));
+    const chunks = optionalNumber(source, 'chunks', 'mcp.search.chunks', defaults.chunks, {
+        min: 1,
+        max: 50,
+        whole: true,
+    });
+    const keywordMatch = source.keywordMatch ?? defaults.keywordMatch;
+    if (keywordMatch !== 'and' && keywordMatch !== 'or') {
+        fail('mcp.search.keywordMatch', 'must be "and" or "or"');
+    }
+    let reranking = defaults.reranking;
+    if (source.reranking !== undefined) {
+        const rerankingSource = record(source.reranking, 'mcp.search.reranking');
+        knownKeys(rerankingSource, 'mcp.search.reranking', Object.keys(reranking));
+        reranking = {
+            enabled: optionalFlag(rerankingSource, 'enabled', 'mcp.search.reranking.enabled', reranking.enabled),
+            model: rerankingSource.model === undefined
+                ? reranking.model
+                : text(rerankingSource, 'model', 'mcp.search.reranking.model'),
+            threshold: optionalNumber(rerankingSource, 'threshold', 'mcp.search.reranking.threshold', reranking.threshold, { min: 0, max: 1, whole: false }),
+        };
+    }
+    // The default, like a set value, is no more than the chunks asked for.
+    const results = optionalNumber(source, 'results', 'mcp.search.results', Math.min(defaults.results, chunks), { min: 1, max: chunks, whole: true });
+    return {
+        chunks,
+        vectorThreshold: optionalNumber(source, 'vectorThreshold', 'mcp.search.vectorThreshold', defaults.vectorThreshold, { min: 0, max: 1, whole: false }),
+        keywordMatch,
+        contextChunks: optionalNumber(source, 'contextChunks', 'mcp.search.contextChunks', defaults.contextChunks, { min: 0, max: 3, whole: true }),
+        reranking,
+        results,
+        passagesPerResult: optionalNumber(source, 'passagesPerResult', 'mcp.search.passagesPerResult', defaults.passagesPerResult, { min: 1, whole: true }),
+        passageCharacters: optionalNumber(source, 'passageCharacters', 'mcp.search.passageCharacters', defaults.passageCharacters, { min: results * SHORTEST_PASSAGE, whole: true }),
+    };
+}
 function optionalMegabytes(source, key, path, fallback) {
     const value = source[key];
     if (value === undefined) {
@@ -215,6 +313,14 @@ export function parseSiteConfiguration(input) {
         fail('deployment.workerName', 'must be lowercase letters, digits, and hyphens');
     }
     const syncSource = record(root.sync, 'sync');
+    // A misspelled optional line would otherwise fall back to its default.
+    knownKeys(syncSource, 'sync', [
+        'generatedBy',
+        'commitBotName',
+        'defaultLocale',
+        'largeImageMegabytes',
+        'largeDocumentCharacters',
+    ]);
     const generatedBy = text(syncSource, 'generatedBy', 'sync.generatedBy');
     // The marker is embedded in an HTML comment in every generated Markdown
     // file. A comment delimiter inside it would terminate that comment early and
@@ -232,6 +338,7 @@ export function parseSiteConfiguration(input) {
         environments: environments(deploymentSource),
         workerName,
     };
+    const publicEnvironment = Object.entries(deployment.environments).find(([, environment]) => environment.visibility === 'public');
     /*
      * Rules close folders to some readers, which a public environment cannot
      * do: everyone may read it. Accepting rules there would promise a boundary
@@ -239,7 +346,6 @@ export function parseSiteConfiguration(input) {
      */
     let access;
     if (root.access !== undefined) {
-        const publicEnvironment = Object.entries(deployment.environments).find(([, environment]) => environment.visibility === 'public');
         if (publicEnvironment) {
             fail('access', `must not be set while the ${publicEnvironment[0]} environment is public`);
         }
@@ -269,8 +375,29 @@ export function parseSiteConfiguration(input) {
         }
         signIn = { workspaceDomains: Object.freeze(parsed) };
     }
+    let mcp;
+    if (root.mcp !== undefined) {
+        const source = record(root.mcp, 'mcp');
+        knownKeys(source, 'mcp', ['enabled', 'search', 'fetchCharacters']);
+        const enabled = flag(source, 'enabled', 'mcp.enabled');
+        if (enabled) {
+            if (!signIn) {
+                fail('mcp', 'needs signIn: assistants sign in as the site does');
+            }
+            if (publicEnvironment) {
+                fail('mcp', `must not be enabled while the ${publicEnvironment[0]} environment is public`);
+            }
+        }
+        mcp = {
+            enabled,
+            search: mcpSearch(source.search),
+            fetchCharacters: optionalNumber(source, 'fetchCharacters', 'mcp.fetchCharacters', MCP_DEFAULTS.fetchCharacters, { min: 1_000, whole: true }),
+        };
+    }
+    const fetchLimit = fetchCharacterLimit(mcp);
     return {
         ...(signIn ? { signIn } : {}),
+        ...(mcp ? { mcp } : {}),
         ...(access ? { access } : {}),
         brand,
         deployment,
@@ -290,6 +417,7 @@ export function parseSiteConfiguration(input) {
             defaultLocale,
             generatedBy,
             largeImageMegabytes: optionalMegabytes(syncSource, 'largeImageMegabytes', 'sync.largeImageMegabytes', 2),
+            largeDocumentCharacters: optionalNumber(syncSource, 'largeDocumentCharacters', 'sync.largeDocumentCharacters', Math.min(LARGE_DOCUMENT_CHARACTERS, fetchLimit), { min: 1, max: fetchLimit, whole: true }),
         },
     };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ctcstack/ctcdocs-core",
-  "version": "0.16.2",
-  "description": "Configuration schema, project layout, and generated-path allowlist shared by the CTCDocs platform packages.",
+  "version": "0.18.0",
+  "description": "Configuration schema, project layout, generated-path allowlist and the published Markdown form shared by the CTCDocs platform packages.",
   "keywords": [
     "ctcdocs",
     "configuration",
@@ -27,6 +27,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./published-markdown": {
+      "types": "./dist/published-markdown.d.ts",
+      "default": "./dist/published-markdown.js"
     }
   },
   "files": [
@@ -37,7 +41,15 @@
   "engines": {
     "node": ">=22.12.0"
   },
+  "dependencies": {
+    "cheerio": "1.2.0",
+    "remark-gfm": "4.0.1",
+    "remark-parse": "11.0.0",
+    "remark-stringify": "11.0.0",
+    "unified": "11.0.5"
+  },
   "devDependencies": {
+    "@types/mdast": "4.0.4",
     "@types/node": "22.20.1",
     "fast-check": "4.10.2",
     "typescript": "6.0.3",

package/src/corpus-structure.ts

@@ -33,6 +33,12 @@ export interface CorpusDocument {
    * on its new chain to be confirmed.
    */
   readonly publishedReaders?: '*' | readonly string[];
+  /** The permanent short ID (ADR-022), the title and Drive's modified time. */
+  readonly shortId?: string;
+  readonly title?: string;
+  readonly modified?: string;
+  /** The Google Doc or PDF in Drive, as the page links it. */
+  readonly source?: string;
 }
 
 export interface CorpusStructure {
@@ -101,11 +107,24 @@ export function parseCorpusStructure(manifest: unknown): CorpusStructure {
   const documents = new Map<string, CorpusDocument>();
   for (const [id, raw] of entries(source.documents, 'documents')) {
     const path = `documents.${id}`;
-    const published = (raw as Record<string, unknown>).publishedReaders;
+    const record = raw as Record<string, unknown>;
+    const published = record.publishedReaders;
+    const optional = (key: string) =>
+      typeof record[key] === 'string' && record[key].length > 0
+        ? record[key]
+        : undefined;
+    const shortId = optional('shortId');
+    const title = optional('displayTitle');
+    const modified = optional('googleModifiedTime');
+    const source = optional('sourceUrl');
     documents.set(id, {
       id,
       parentId: field(raw, 'googleParentId', path, true),
       slug: field(raw, 'stableSlug', path) ?? '',
+      ...(shortId ? { shortId } : {}),
+      ...(title ? { title } : {}),
+      ...(modified ? { modified } : {}),
+      ...(source ? { source } : {}),
       ...(published === '*' ||
       (Array.isArray(published) &&
         published.every((group) => typeof group === 'string'))

package/src/index.ts

@@ -2,12 +2,14 @@ export {
   ACCESS_CLASSES_ROUTE,
   GENERATED_DIRECTORY_ALLOWLIST,
   GENERATED_FILE_ALLOWLIST,
+  markdownProjectionPath,
   PLATFORM_ROUTE_HREFS,
   PLATFORM_ROUTES,
   PLATFORM_WORKERS,
   permanentLinkPath,
   PROJECT_LAYOUT,
   RESERVED_SLUGS,
+  resolvePermanentLink,
   SHORT_ID_PATTERN,
 } from './project-layout.js';
 export {
@@ -63,7 +65,9 @@ export type {
 export { accessFindings } from './access-findings.js';
 export type { AccessFinding } from './access-findings.js';
 export {
+  fetchCharacterLimit,
   loadSiteConfiguration,
+  MCP_DEFAULTS,
   parseSiteConfiguration,
   SiteConfigurationError,
 } from './site-configuration.js';
@@ -75,6 +79,8 @@ export type {
   DeploymentEnvironmentConfigurations,
   DeploymentVisibility,
   HomeConfiguration,
+  McpConfiguration,
+  McpSearchConfiguration,
   NavigationConfiguration,
   SignInConfiguration,
   SiteConfiguration,

package/src/project-layout.ts

@@ -82,6 +82,16 @@ export const PLATFORM_WORKERS = {
   accessMapAlias: 'ctcdocs-access-map',
   stateBinding: 'KB_STATE',
   directorySchedule: '*/10 * * * *',
+  /** The MCP server's OAuth state; the library requires this name (ADR-041). */
+  oauthBinding: 'OAUTH_KV',
+  /** The R2 bucket the Worker publishes each document's Markdown to. */
+  documentsBinding: 'KB_DOCUMENTS',
+  /** The AI Search instance that indexes that bucket. */
+  searchBinding: 'KB_SEARCH',
+  /** How often the site's Worker checks that the bucket matches its build. */
+  publishSchedule: '*/5 * * * *',
+  /** Lets the OAuth library fetch a client's metadata document safely. */
+  oauthCompatibilityFlag: 'global_fetch_strictly_public',
 } as const;
 
 /**
@@ -98,8 +108,10 @@ export const PLATFORM_ROUTE_HREFS = {
 
 /**
  * Top-level addresses the platform serves beside the corpus: the Worker's
- * sign-in routes (ADR-038), the search bundles, `/pagefind/` and
- * `/pagefind-<class>/` (ADR-039), and the original files under `/assets/`.
+ * sign-in and OAuth routes (ADR-038, ADR-041), the search bundles,
+ * `/pagefind/` and `/pagefind-<class>/` (ADR-039), and the original files
+ * under `/assets/`. The MCP server needs none: it answers `/mcp` exactly
+ * (ADR-041), and a page is always served under its trailing slash.
  */
 const SERVED_ADDRESSES = ['auth', 'pagefind', 'assets'] as const;
 
@@ -120,6 +132,43 @@ export function permanentLinkPath(shortId: string): string {
   return `/${PLATFORM_ROUTES.permanentLinks}/${shortId}/`;
 }
 
+/**
+ * Renders a permanent link as the address it currently leads to.
+ *
+ * The sync writes a link between two documents as the target's permanent
+ * link, `/d/<short ID>/`, so the document holding it never changes when the
+ * target is renamed or moved (ADR-022). The redirect map says where each one
+ * leads today. Resolving it while the site builds sends a reader straight to
+ * the page instead of through a redirect page on every click.
+ *
+ * A permanent link the map does not know is left as it is: it is either a
+ * hand-written link to nothing, which the sync already refuses for generated
+ * pages, or one a later build will know.
+ */
+export function resolvePermanentLink(
+  value: string,
+  redirects: Readonly<Record<string, string>>,
+): string | undefined {
+  const prefix = `/${PLATFORM_ROUTES.permanentLinks}/`;
+  if (!value.startsWith(prefix)) {
+    return undefined;
+  }
+  const suffixStart = value.search(/[?#]/u);
+  const path = suffixStart < 0 ? value : value.slice(0, suffixStart);
+  const suffix = suffixStart < 0 ? '' : value.slice(suffixStart);
+  const target = redirects[path.endsWith('/') ? path : `${path}/`];
+  return target === undefined ? undefined : `${target}${suffix}`;
+}
+
+/**
+ * The site path of a page's Markdown version, from its route ID (ADR-010):
+ * the one definition, shared by the route that serves it, the pages that link
+ * it and the sync that measures it.
+ */
+export function markdownProjectionPath(slug: string): string {
+  return `/${slug}/index.md`;
+}
+
 export const GENERATED_DIRECTORY_ALLOWLIST = [
   PROJECT_LAYOUT.generatedDocumentsDirectory,
   PROJECT_LAYOUT.generatedAssetsDirectory,

package/src/published-markdown.ts

@@ -0,0 +1,199 @@
+import type { Root, RootContent } from 'mdast';
+import * as cheerio from 'cheerio';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import remarkStringify from 'remark-stringify';
+import { unified } from 'unified';
+
+import {
+  markdownProjectionPath,
+  resolvePermanentLink,
+} from './project-layout.js';
+
+const processor = unified()
+  .use(remarkParse)
+  .use(remarkGfm)
+  .use(remarkStringify, {
+    bullet: '-',
+    emphasis: '*',
+    fences: true,
+    listItemIndent: 'one',
+    strong: '*',
+  });
+
+export interface PublishedMarkdownInput {
+  title: string;
+  /**
+   * The ownership marker the generated file opens with, which is stripped from
+   * the published form. It is passed in rather than read from the project so
+   * this stays a pure function of its input.
+   */
+  ownershipHeader: string;
+  sourceUrl: string;
+  /** The published PDF, when the page is one's and the site serves it. */
+  fileUrl?: string;
+  googleModifiedTime: string;
+  syncedAt: string;
+  contentHash: string;
+  body: string;
+  stableSlugs: ReadonlySet<string>;
+  /**
+   * Each permanent link, `/d/<short ID>/`, to the address it leads to. A link
+   * between documents is stored as one (ADR-022); the projection names the
+   * target's own Markdown instead, as it does for any other corpus link.
+   */
+  permanentLinks: Readonly<Record<string, string>>;
+}
+
+function walk(
+  node: Root | RootContent,
+  visit: (node: RootContent) => void,
+): void {
+  if (node.type !== 'root') {
+    visit(node);
+  }
+  if ('children' in node) {
+    for (const child of node.children) {
+      walk(child, visit);
+    }
+  }
+}
+
+function markdownUrl(
+  value: string,
+  stableSlugs: ReadonlySet<string>,
+  permanentLinks: Readonly<Record<string, string>>,
+): string | undefined {
+  const resolved = resolvePermanentLink(value, permanentLinks);
+  const link = resolved ?? value;
+  if (!link.startsWith('/')) {
+    return resolved;
+  }
+
+  let url: URL;
+  try {
+    url = new URL(link, 'https://wiki.invalid');
+  } catch {
+    return resolved;
+  }
+  const slug = url.pathname.replace(/^\/+|\/+$/gu, '');
+  if (!stableSlugs.has(slug)) {
+    return resolved;
+  }
+  return `${markdownProjectionPath(slug)}${url.search}${url.hash}`;
+}
+
+function rewriteInternalLinks(
+  body: string,
+  stableSlugs: ReadonlySet<string>,
+  permanentLinks: Readonly<Record<string, string>>,
+): string {
+  const tree = processor.parse(body) as Root;
+  walk(tree, (node) => {
+    if (node.type === 'link') {
+      node.url = markdownUrl(node.url, stableSlugs, permanentLinks) ?? node.url;
+      return;
+    }
+    if (node.type !== 'html') {
+      return;
+    }
+
+    const $ = cheerio.load(node.value, null, false);
+    let changed = false;
+    $('a[href]').each((_, anchor) => {
+      const href = $(anchor).attr('href');
+      const rewritten = href
+        ? markdownUrl(href, stableSlugs, permanentLinks)
+        : undefined;
+      if (rewritten) {
+        $(anchor).attr('href', rewritten);
+        changed = true;
+      }
+    });
+    if (changed) {
+      node.value = $.root().html() ?? '';
+    }
+  });
+
+  return processor.stringify(tree).trimEnd();
+}
+
+function cleanBody(body: string, ownershipHeader: string): string {
+  const normalized = body.replace(/\r\n?/gu, '\n');
+  if (
+    normalized !== ownershipHeader &&
+    !normalized.startsWith(`${ownershipHeader}\n`)
+  ) {
+    throw new Error(
+      'Generated Google document is missing the expected ownership marker.',
+    );
+  }
+  return normalized.slice(ownershipHeader.length).trim();
+}
+
+/** Where the site serves a published PDF, as its Markdown version names it. */
+export function publishedFileUrl(googleFileId: string, file: string): string {
+  return `/assets/generated/${googleFileId}/${file}`;
+}
+
+function yamlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+/**
+ * One line of inline Markdown that reads as the text it was given: whitespace,
+ * newlines included, collapses to single spaces, and every character that
+ * would open emphasis, code, a link, HTML or a heading is escaped. Used for
+ * titles, which come from Drive names and may contain any of them.
+ */
+export function inlineMarkdown(value: string): string {
+  return value
+    .replace(/\s+/gu, ' ')
+    .trim()
+    .replace(/([\\`*_[\]<>#])/gu, '\\$1');
+}
+
+/**
+ * The page's Markdown without its front matter: its title as a heading and
+ * its body. It is what the MCP server stores, indexes and returns from
+ * `fetch` (ADR-042), so it is also what the sync measures (ADR-043).
+ */
+export function publishedMarkdownBody(
+  input: Pick<
+    PublishedMarkdownInput,
+    'title' | 'ownershipHeader' | 'body' | 'stableSlugs' | 'permanentLinks'
+  >,
+): string {
+  const body = rewriteInternalLinks(
+    cleanBody(input.body, input.ownershipHeader),
+    input.stableSlugs,
+    input.permanentLinks,
+  );
+  return [
+    `# ${inlineMarkdown(input.title)}`,
+    '',
+    ...(body ? [body, ''] : []),
+  ].join('\n');
+}
+
+/**
+ * The page's Markdown version (ADR-010): front matter, then
+ * `publishedMarkdownBody`. Each front matter value is one JSON string, so no
+ * value spans a line and the first `---` line after the opening one closes it.
+ */
+export function serializePublishedMarkdown(
+  input: PublishedMarkdownInput,
+): string {
+  return [
+    '---',
+    `title: ${yamlString(input.title)}`,
+    `source_url: ${yamlString(input.sourceUrl)}`,
+    ...(input.fileUrl ? [`file_url: ${yamlString(input.fileUrl)}`] : []),
+    `modified_at: ${yamlString(input.googleModifiedTime)}`,
+    `synced_at: ${yamlString(input.syncedAt)}`,
+    `content_hash: ${yamlString(input.contentHash)}`,
+    '---',
+    '',
+    publishedMarkdownBody(input),
+  ].join('\n');
+}

package/src/site-configuration.ts

@@ -121,6 +121,13 @@ export interface SyncConfigurationDefaults {
    * project sets the line it wants numbers for. Defaults to 2.
    */
   readonly largeImageMegabytes: number;
+  /**
+   * The length, in characters of a document's Markdown body, above which the
+   * sync report notes the document as worth splitting (ADR-043). No greater
+   * than the characters an assistant reads of a document; defaults to 40,000,
+   * or to that limit where it is lower.
+   */
+  readonly largeDocumentCharacters: number;
 }
 
 export interface NavigationConfiguration {
@@ -166,9 +173,94 @@ export interface SignInConfiguration {
   readonly workspaceDomains: readonly string[];
 }
 
+/**
+ * How the MCP server searches and how much a search returns (ADR-042). Every
+ * value has a default, the starting point ADR-042 records, so that a project
+ * tunes it against its own corpus without a new version of the platform.
+ */
+export interface McpSearchConfiguration {
+  /** Chunks asked of AI Search for each query: 1 to 50. */
+  readonly chunks: number;
+  /**
+   * The vector similarity below which AI Search drops a chunk, 0 to 1. It
+   * drops only chunks vector search alone found, and AI Search ignores it
+   * while reranking is on (ADR-042), so it acts only with reranking off.
+   */
+  readonly vectorThreshold: number;
+  /** Whether a keyword match needs every word of the query, or any. */
+  readonly keywordMatch: 'and' | 'or';
+  /**
+   * Neighbouring chunks AI Search joins to each side of a match: 0 to 3. A
+   * chunk of AI Search's default size is already longer than a passage.
+   */
+  readonly contextChunks: number;
+  readonly reranking: {
+    readonly enabled: boolean;
+    /** An AI Search reranking model. */
+    readonly model: string;
+    /** The reranking score below which a chunk is dropped, 0 to 1. */
+    readonly threshold: number;
+  };
+  /** Documents a search returns at most; no more than `chunks`. */
+  readonly results: number;
+  /** Passages each document shows at most. */
+  readonly passagesPerResult: number;
+  /** Characters of passage text one search returns at most, in all. */
+  readonly passageCharacters: number;
+}
+
+/**
+ * The MCP server through which AI assistants read the site as the person who
+ * connected them (ADR-041). It needs the Worker's sign-in, so it is accepted
+ * only on a deployment whose every environment is private.
+ */
+export interface McpConfiguration {
+  readonly enabled: boolean;
+  readonly search: McpSearchConfiguration;
+  /** Characters `fetch` returns at most; a longer document is cut there. */
+  readonly fetchCharacters: number;
+}
+
+/** What `mcp` holds when a project sets only `enabled` (ADR-042). */
+export const MCP_DEFAULTS: Omit<McpConfiguration, 'enabled'> = Object.freeze({
+  search: Object.freeze({
+    chunks: 50,
+    vectorThreshold: 0.2,
+    keywordMatch: 'or',
+    contextChunks: 0,
+    reranking: Object.freeze({
+      enabled: true,
+      model: '@cf/baai/bge-reranker-base',
+      threshold: 0,
+    }),
+    results: 10,
+    passagesPerResult: 3,
+    passageCharacters: 24_000,
+  }),
+  fetchCharacters: 100_000,
+});
+
+/**
+ * The characters an assistant reads of a document: the cut `fetch` makes
+ * (ADR-042), or its default while the MCP server is off. The build writes
+ * this value into the access map and the sync measures documents against it
+ * (ADR-043), so the two never derive it apart.
+ */
+export function fetchCharacterLimit(mcp: McpConfiguration | undefined): number {
+  return mcp?.enabled ? mcp.fetchCharacters : MCP_DEFAULTS.fetchCharacters;
+}
+
+/** About 10,000 tokens of English: a starting value, not a measured one. */
+const LARGE_DOCUMENT_CHARACTERS = 40_000;
+
+/** A passage of fewer characters than this says too little to judge by. */
+const SHORTEST_PASSAGE = 100;
+
 export interface SiteConfiguration {
   /** Required to serve a private environment through the platform's Worker. */
   readonly signIn?: SignInConfiguration;
+  /** Absent or disabled, the Worker serves no MCP or OAuth route. */
+  readonly mcp?: McpConfiguration;
   /**
    * Who may read which folder (ADR-039). Absent, every document is open to
    * every reader the deployment admits, as before access rules existed.
@@ -350,6 +442,139 @@ function optionalCount(
 }
 
 /** A size above zero, in megabytes; a fraction such as 1.5 is allowed. */
+/** A number between `min` and `max`, whole when `whole`, or the fallback. */
+function optionalNumber(
+  source: Record<string, unknown>,
+  key: string,
+  path: string,
+  fallback: number,
+  { min, max, whole }: { min: number; max?: number; whole: boolean },
+): number {
+  const value = source[key];
+  if (value === undefined) {
+    return fallback;
+  }
+  if (
+    typeof value !== 'number' ||
+    !Number.isFinite(value) ||
+    (whole && !Number.isInteger(value)) ||
+    value < min ||
+    (max !== undefined && value > max)
+  ) {
+    const kind = whole ? 'a whole number' : 'a number';
+    fail(
+      path,
+      max === undefined
+        ? `must be ${kind} of at least ${min}`
+        : `must be ${kind} from ${min} to ${max}`,
+    );
+  }
+  return value;
+}
+
+/** Fails on a key the section does not define. */
+function knownKeys(
+  source: Record<string, unknown>,
+  path: string,
+  keys: readonly string[],
+): void {
+  for (const key of Object.keys(source)) {
+    if (!keys.includes(key)) {
+      fail(`${path}.${key}`, 'is not a known setting');
+    }
+  }
+}
+
+function mcpSearch(value: unknown): McpSearchConfiguration {
+  const defaults = MCP_DEFAULTS.search;
+  if (value === undefined) {
+    return defaults;
+  }
+  const source = record(value, 'mcp.search');
+  knownKeys(source, 'mcp.search', Object.keys(defaults));
+  const chunks = optionalNumber(
+    source,
+    'chunks',
+    'mcp.search.chunks',
+    defaults.chunks,
+    {
+      min: 1,
+      max: 50,
+      whole: true,
+    },
+  );
+  const keywordMatch = source.keywordMatch ?? defaults.keywordMatch;
+  if (keywordMatch !== 'and' && keywordMatch !== 'or') {
+    fail('mcp.search.keywordMatch', 'must be "and" or "or"');
+  }
+  let reranking = defaults.reranking;
+  if (source.reranking !== undefined) {
+    const rerankingSource = record(source.reranking, 'mcp.search.reranking');
+    knownKeys(rerankingSource, 'mcp.search.reranking', Object.keys(reranking));
+    reranking = {
+      enabled: optionalFlag(
+        rerankingSource,
+        'enabled',
+        'mcp.search.reranking.enabled',
+        reranking.enabled,
+      ),
+      model:
+        rerankingSource.model === undefined
+          ? reranking.model
+          : text(rerankingSource, 'model', 'mcp.search.reranking.model'),
+      threshold: optionalNumber(
+        rerankingSource,
+        'threshold',
+        'mcp.search.reranking.threshold',
+        reranking.threshold,
+        { min: 0, max: 1, whole: false },
+      ),
+    };
+  }
+  // The default, like a set value, is no more than the chunks asked for.
+  const results = optionalNumber(
+    source,
+    'results',
+    'mcp.search.results',
+    Math.min(defaults.results, chunks),
+    { min: 1, max: chunks, whole: true },
+  );
+  return {
+    chunks,
+    vectorThreshold: optionalNumber(
+      source,
+      'vectorThreshold',
+      'mcp.search.vectorThreshold',
+      defaults.vectorThreshold,
+      { min: 0, max: 1, whole: false },
+    ),
+    keywordMatch,
+    contextChunks: optionalNumber(
+      source,
+      'contextChunks',
+      'mcp.search.contextChunks',
+      defaults.contextChunks,
+      { min: 0, max: 3, whole: true },
+    ),
+    reranking,
+    results,
+    passagesPerResult: optionalNumber(
+      source,
+      'passagesPerResult',
+      'mcp.search.passagesPerResult',
+      defaults.passagesPerResult,
+      { min: 1, whole: true },
+    ),
+    passageCharacters: optionalNumber(
+      source,
+      'passageCharacters',
+      'mcp.search.passageCharacters',
+      defaults.passageCharacters,
+      { min: results * SHORTEST_PASSAGE, whole: true },
+    ),
+  };
+}
+
 function optionalMegabytes(
   source: Record<string, unknown>,
   key: string,
@@ -467,6 +692,14 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
   }
 
   const syncSource = record(root.sync, 'sync');
+  // A misspelled optional line would otherwise fall back to its default.
+  knownKeys(syncSource, 'sync', [
+    'generatedBy',
+    'commitBotName',
+    'defaultLocale',
+    'largeImageMegabytes',
+    'largeDocumentCharacters',
+  ]);
   const generatedBy = text(syncSource, 'generatedBy', 'sync.generatedBy');
   // The marker is embedded in an HTML comment in every generated Markdown
   // file. A comment delimiter inside it would terminate that comment early and
@@ -486,6 +719,10 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
     workerName,
   };
 
+  const publicEnvironment = Object.entries(deployment.environments).find(
+    ([, environment]) => environment.visibility === 'public',
+  );
+
   /*
    * Rules close folders to some readers, which a public environment cannot
    * do: everyone may read it. Accepting rules there would promise a boundary
@@ -493,9 +730,6 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
    */
   let access: AccessConfiguration | undefined;
   if (root.access !== undefined) {
-    const publicEnvironment = Object.entries(deployment.environments).find(
-      ([, environment]) => environment.visibility === 'public',
-    );
     if (publicEnvironment) {
       fail(
         'access',
@@ -538,8 +772,39 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
     signIn = { workspaceDomains: Object.freeze(parsed) };
   }
 
+  let mcp: McpConfiguration | undefined;
+  if (root.mcp !== undefined) {
+    const source = record(root.mcp, 'mcp');
+    knownKeys(source, 'mcp', ['enabled', 'search', 'fetchCharacters']);
+    const enabled = flag(source, 'enabled', 'mcp.enabled');
+    if (enabled) {
+      if (!signIn) {
+        fail('mcp', 'needs signIn: assistants sign in as the site does');
+      }
+      if (publicEnvironment) {
+        fail(
+          'mcp',
+          `must not be enabled while the ${publicEnvironment[0]} environment is public`,
+        );
+      }
+    }
+    mcp = {
+      enabled,
+      search: mcpSearch(source.search),
+      fetchCharacters: optionalNumber(
+        source,
+        'fetchCharacters',
+        'mcp.fetchCharacters',
+        MCP_DEFAULTS.fetchCharacters,
+        { min: 1_000, whole: true },
+      ),
+    };
+  }
+  const fetchLimit = fetchCharacterLimit(mcp);
+
   return {
     ...(signIn ? { signIn } : {}),
+    ...(mcp ? { mcp } : {}),
     ...(access ? { access } : {}),
     brand,
     deployment,
@@ -590,6 +855,13 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
         'sync.largeImageMegabytes',
         2,
       ),
+      largeDocumentCharacters: optionalNumber(
+        syncSource,
+        'largeDocumentCharacters',
+        'sync.largeDocumentCharacters',
+        Math.min(LARGE_DOCUMENT_CHARACTERS, fetchLimit),
+        { min: 1, max: fetchLimit, whole: true },
+      ),
     },
   };
 }