@ctcstack/ctcdocs-core 0.17.0 → 0.19.0

package/dist/corpus-structure.d.ts

@@ -19,10 +19,14 @@ export interface CorpusDocument {
      * on its new chain to be confirmed.
      */
     readonly publishedReaders?: '*' | readonly string[];
+    /** Set while such a move waits, as the manifest's `readersHeld` says. */
+    readonly readersHeld?: true;
     /** 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

@@ -65,6 +65,7 @@ export function parseCorpusStructure(manifest) {
         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),
@@ -72,6 +73,10 @@ export function parseCorpusStructure(manifest) {
             ...(shortId ? { shortId } : {}),
             ...(title ? { title } : {}),
             ...(modified ? { modified } : {}),
+            ...(source ? { source } : {}),
+            ...(typeof record.readersHeld === 'object' && record.readersHeld !== null
+                ? { readersHeld: true }
+                : {}),
             ...(published === '*' ||
                 (Array.isArray(published) &&
                     published.every((group) => typeof group === 'string'))

package/dist/project-layout.d.ts

@@ -26,6 +26,8 @@ export declare const PROJECT_LAYOUT: {
     readonly publicDirectory: "public";
     readonly robotsFile: "public/robots.txt";
     readonly headersFile: "public/_headers";
+    /** The pages a project writes by hand; generated ones sit beneath, apart. */
+    readonly documentsDirectory: "src/content/docs";
     /** Generated Markdown, one directory per Drive folder. */
     readonly generatedDocumentsDirectory: "src/content/docs/_generated";
     /** Original images, one directory per Google file identifier. */
@@ -68,6 +70,11 @@ export declare const PLATFORM_ROUTES: {
      * docs/ADR/024-content-health-page.md.
      */
     readonly contentHealth: "content-health";
+    /**
+     * Who may read each folder, for admins. See
+     * docs/ADR/045-an-access-review-page-shows-admins-who-may-read-each-folder.md.
+     */
+    readonly accessReview: "access-review";
 };
 /**
  * The platform's Workers, as a project's Wrangler configuration names them
@@ -100,6 +107,7 @@ export declare const ACCESS_CLASSES_ROUTE = "/_kb/classes";
 export declare const PLATFORM_ROUTE_HREFS: {
     readonly fullIndex: "/documents/";
     readonly contentHealth: "/content-health/";
+    readonly accessReview: "/access-review/";
 };
 export declare const RESERVED_SLUGS: readonly string[];
 /**

package/dist/project-layout.js

@@ -26,6 +26,8 @@ export const PROJECT_LAYOUT = {
     publicDirectory: 'public',
     robotsFile: 'public/robots.txt',
     headersFile: 'public/_headers',
+    /** The pages a project writes by hand; generated ones sit beneath, apart. */
+    documentsDirectory: 'src/content/docs',
     /** Generated Markdown, one directory per Drive folder. */
     generatedDocumentsDirectory: 'src/content/docs/_generated',
     /** Original images, one directory per Google file identifier. */
@@ -68,6 +70,11 @@ export const PLATFORM_ROUTES = {
      * docs/ADR/024-content-health-page.md.
      */
     contentHealth: 'content-health',
+    /**
+     * Who may read each folder, for admins. See
+     * docs/ADR/045-an-access-review-page-shows-admins-who-may-read-each-folder.md.
+     */
+    accessReview: 'access-review',
 };
 /**
  * The platform's Workers, as a project's Wrangler configuration names them
@@ -100,6 +107,7 @@ export const ACCESS_CLASSES_ROUTE = '/_kb/classes';
 export const PLATFORM_ROUTE_HREFS = {
     fullIndex: `/${PLATFORM_ROUTES.fullIndex}/`,
     contentHealth: `/${PLATFORM_ROUTES.contentHealth}/`,
+    accessReview: `/${PLATFORM_ROUTES.accessReview}/`,
 };
 /**
  * Top-level addresses the platform serves beside the corpus: the Worker's

package/dist/published-markdown.d.ts

@@ -30,4 +30,15 @@ export declare function publishedFileUrl(googleFileId: string, file: string): st
  * 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

@@ -98,8 +98,25 @@ export function inlineMarkdown(value) {
         .trim()
         .replace(/([\\`*_[\]<>#])/gu, '\\$1');
 }
-export function serializePublishedMarkdown(input) {
+/**
+ * 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)}`,
@@ -110,8 +127,6 @@ export function serializePublishedMarkdown(input) {
         `content_hash: ${yamlString(input.contentHash)}`,
         '---',
         '',
-        `# ${inlineMarkdown(input.title)}`,
-        '',
-        ...(body ? [body, ''] : []),
+        publishedMarkdownBody(input),
     ].join('\n');
 }

package/dist/site-configuration.d.ts

@@ -33,6 +33,14 @@ export interface HomeConfiguration {
      * outgrown one page may prefer the home page to stay an entrance.
      */
     readonly corpusIndex: boolean;
+    /**
+     * The address of the hand-authored page the home page sends a newcomer to,
+     * as a slug: `about` for `src/content/docs/about.md`. The link reads that
+     * page's own title, so renaming the page renames the link. Without it the
+     * home page offers no such link: the platform does not know what a
+     * deployment calls its introduction, or whether it has one.
+     */
+    readonly start?: string;
 }
 /**
  * Who a deployment is for.
@@ -152,13 +160,16 @@ export interface McpSearchConfiguration {
     readonly chunks: number;
     /**
      * The vector similarity below which AI Search drops a chunk, 0 to 1. It
-     * applies to vector similarity alone, so a keyword match far from the
-     * question in meaning is dropped too when it is set high.
+     * 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 adds on each side of a match: 0 to 3. */
+    /**
+     * 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;

package/dist/site-configuration.js

@@ -21,7 +21,7 @@ export const MCP_DEFAULTS = Object.freeze({
         chunks: 50,
         vectorThreshold: 0.2,
         keywordMatch: 'or',
-        contextChunks: 1,
+        contextChunks: 0,
         reranking: Object.freeze({
             enabled: true,
             model: '@cf/baai/bge-reranker-base',
@@ -121,6 +121,21 @@ function flag(source, key, path) {
 function optionalFlag(source, key, path, fallback) {
     return source[key] === undefined ? fallback : flag(source, key, path);
 }
+/**
+ * A page's address as Starlight derives it from a file under
+ * `src/content/docs`: lowercase segments joined by `/`, with no leading or
+ * trailing slash, so it is the same string the content collection knows.
+ */
+function optionalPageSlug(source, key, path) {
+    if (source[key] === undefined) {
+        return {};
+    }
+    const value = text(source, key, path);
+    if (!/^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)*$/u.test(value)) {
+        fail(path, 'must be a page address such as "about", without slashes at either end');
+    }
+    return { [key]: value };
+}
 /**
  * A list of distinct Unicode script names, as a `\p{Script=…}` property
  * escape spells them. Each name is proved by compiling that escape, so a typo
@@ -405,6 +420,7 @@ export function parseSiteConfiguration(input) {
             corpusIndex: optionalFlag(homeSource, 'corpusIndex', 'home.corpusIndex', true),
             lede: text(homeSource, 'lede', 'home.lede'),
             recentLimit: optionalCount(homeSource, 'recentLimit', 'home.recentLimit', 6),
+            ...optionalPageSlug(homeSource, 'start', 'home.start'),
         },
         navigation: {
             landingDocumentTitles: titleList(navigationSource, 'landingDocumentTitles', 'navigation.landingDocumentTitles'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctcstack/ctcdocs-core",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Configuration schema, project layout, generated-path allowlist and the published Markdown form shared by the CTCDocs platform packages.",
   "keywords": [
     "ctcdocs",

package/src/corpus-structure.ts

@@ -33,10 +33,14 @@ export interface CorpusDocument {
    * on its new chain to be confirmed.
    */
   readonly publishedReaders?: '*' | readonly string[];
+  /** Set while such a move waits, as the manifest's `readersHeld` says. */
+  readonly readersHeld?: true;
   /** 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 {
@@ -114,6 +118,7 @@ export function parseCorpusStructure(manifest: unknown): CorpusStructure {
     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),
@@ -121,6 +126,10 @@ export function parseCorpusStructure(manifest: unknown): CorpusStructure {
       ...(shortId ? { shortId } : {}),
       ...(title ? { title } : {}),
       ...(modified ? { modified } : {}),
+      ...(source ? { source } : {}),
+      ...(typeof record.readersHeld === 'object' && record.readersHeld !== null
+        ? { readersHeld: true as const }
+        : {}),
       ...(published === '*' ||
       (Array.isArray(published) &&
         published.every((group) => typeof group === 'string'))

package/src/project-layout.ts

@@ -26,6 +26,8 @@ export const PROJECT_LAYOUT = {
   publicDirectory: 'public',
   robotsFile: 'public/robots.txt',
   headersFile: 'public/_headers',
+  /** The pages a project writes by hand; generated ones sit beneath, apart. */
+  documentsDirectory: 'src/content/docs',
   /** Generated Markdown, one directory per Drive folder. */
   generatedDocumentsDirectory: 'src/content/docs/_generated',
   /** Original images, one directory per Google file identifier. */
@@ -69,6 +71,11 @@ export const PLATFORM_ROUTES = {
    * docs/ADR/024-content-health-page.md.
    */
   contentHealth: 'content-health',
+  /**
+   * Who may read each folder, for admins. See
+   * docs/ADR/045-an-access-review-page-shows-admins-who-may-read-each-folder.md.
+   */
+  accessReview: 'access-review',
 } as const;
 
 /**
@@ -104,6 +111,7 @@ export const ACCESS_CLASSES_ROUTE = '/_kb/classes';
 export const PLATFORM_ROUTE_HREFS = {
   fullIndex: `/${PLATFORM_ROUTES.fullIndex}/`,
   contentHealth: `/${PLATFORM_ROUTES.contentHealth}/`,
+  accessReview: `/${PLATFORM_ROUTES.accessReview}/`,
 } as const;
 
 /**

package/src/published-markdown.ts

@@ -153,14 +153,37 @@ export function inlineMarkdown(value: string): string {
     .replace(/([\\`*_[\]<>#])/gu, '\\$1');
 }
 
-export function serializePublishedMarkdown(
-  input: PublishedMarkdownInput,
+/**
+ * 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)}`,
@@ -171,8 +194,6 @@ export function serializePublishedMarkdown(
     `content_hash: ${yamlString(input.contentHash)}`,
     '---',
     '',
-    `# ${inlineMarkdown(input.title)}`,
-    '',
-    ...(body ? [body, ''] : []),
+    publishedMarkdownBody(input),
   ].join('\n');
 }

package/src/site-configuration.ts

@@ -55,6 +55,14 @@ export interface HomeConfiguration {
    * outgrown one page may prefer the home page to stay an entrance.
    */
   readonly corpusIndex: boolean;
+  /**
+   * The address of the hand-authored page the home page sends a newcomer to,
+   * as a slug: `about` for `src/content/docs/about.md`. The link reads that
+   * page's own title, so renaming the page renames the link. Without it the
+   * home page offers no such link: the platform does not know what a
+   * deployment calls its introduction, or whether it has one.
+   */
+  readonly start?: string;
 }
 
 /**
@@ -183,13 +191,16 @@ export interface McpSearchConfiguration {
   readonly chunks: number;
   /**
    * The vector similarity below which AI Search drops a chunk, 0 to 1. It
-   * applies to vector similarity alone, so a keyword match far from the
-   * question in meaning is dropped too when it is set high.
+   * 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 adds on each side of a match: 0 to 3. */
+  /**
+   * 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;
@@ -224,7 +235,7 @@ export const MCP_DEFAULTS: Omit<McpConfiguration, 'enabled'> = Object.freeze({
     chunks: 50,
     vectorThreshold: 0.2,
     keywordMatch: 'or',
-    contextChunks: 1,
+    contextChunks: 0,
     reranking: Object.freeze({
       enabled: true,
       model: '@cf/baai/bge-reranker-base',
@@ -377,6 +388,29 @@ function optionalFlag(
   return source[key] === undefined ? fallback : flag(source, key, path);
 }
 
+/**
+ * A page's address as Starlight derives it from a file under
+ * `src/content/docs`: lowercase segments joined by `/`, with no leading or
+ * trailing slash, so it is the same string the content collection knows.
+ */
+function optionalPageSlug(
+  source: Record<string, unknown>,
+  key: string,
+  path: string,
+): Record<string, string> {
+  if (source[key] === undefined) {
+    return {};
+  }
+  const value = text(source, key, path);
+  if (!/^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)*$/u.test(value)) {
+    fail(
+      path,
+      'must be a page address such as "about", without slashes at either end',
+    );
+  }
+  return { [key]: value };
+}
+
 /**
  * A list of distinct Unicode script names, as a `\p{Script=…}` property
  * escape spells them. Each name is proved by compiling that escape, so a typo
@@ -819,6 +853,7 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
         'home.recentLimit',
         6,
       ),
+      ...optionalPageSlug(homeSource, 'start', 'home.start'),
     },
     navigation: {
       landingDocumentTitles: titleList(