@shoalrun/cli 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/docs-mcp.js

@@ -3,20 +3,20 @@ import { attemptAnalytics } from './mcp-analytics.js';
 import { McpServer } from '@modelcontextprotocol/server';
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
-import { bundledDocumentation, DocumentationError, documentationFailure, getDocumentationOutline, getDocumentationSection, getDocumentationPage, searchDocumentation } from './documentation-core.js';
+import { bundledDocumentation, DocumentationError, documentationFailure, getDocumentationOutline, getDocumentationSection, getDocumentationPage, listDocumentationPublications, searchDocumentation } from './documentation-core.js';
 export function createDocsMcpServer(directory = bundledDocumentation, publication, analytics, discardAnalyticsArguments = false) {
     const server = new McpServer({ name: 'shoalrun-docs', version: '0.0.0' }, { maxToolInputElements: 1024 });
     const scope = (filters) => {
         if (!publication)
             return filters;
-        for (const key of ['channel', 'version', 'language'])
+        for (const key of ['product', 'channel', 'version', 'language'])
             if (filters[key] !== undefined && filters[key] !== publication[key])
                 throw new DocumentationError('invalid_input', 'This MCP endpoint serves a different publication');
         return { ...filters, ...publication };
     };
     const coordinate = (key) => z.string().optional().describe(publication ? `This endpoint serves ${key}=${publication[key]}; omit this argument or pass that exact value.` : `Select the documentation ${key}.`);
     const options = {
-        channel: coordinate('channel'), version: coordinate('version'), language: coordinate('language'),
+        product: coordinate('product'), channel: coordinate('channel'), version: coordinate('version'), language: coordinate('language'),
         maxTokens: z.number().int().min(256).max(100_000).default(4096).describe('Maximum serialized result tokens, counted with cl100k_base, including metadata.'),
     };
     // A client may cache the instrumented schema after withdrawing consent.
@@ -57,13 +57,18 @@ export function createDocsMcpServer(directory = bundledDocumentation, publicatio
                 await attemptAnalytics(() => analytics.capture({ name: 'mcp_tool_call', ...(analytics.clientMetadata ? mcpClientMetadata(context, server.server.getClientVersion()) : {}), tool, durationMs: Math.max(0, performance.now() - start), isError, ...(errorCode ? { errorCode } : {}), ...(pageId ? { pageId } : {}), ...(sectionId ? { sectionId } : {}), buildId: analytics.buildId, publication: { ...publication } }));
         }
     };
+    server.registerTool('get_publications', {
+        description: 'Discover available product/channel/version/language coordinates before searching. Returns one compact page and concise product defaults; follow nextOffset for more. Products have independent versions. Preserve the selected product and publication coordinates in subsequent search and read calls. This endpoint lists only its published scope.',
+        inputSchema: schema(z.object({ ...options, maxTokens: z.number().int().min(256).max(100_000).default(2048), limit: z.number().int().min(1).max(100).default(20), offset: z.number().int().min(0).default(0) }).strict()),
+        annotations,
+    }, (filters, context) => respond('get_publications', context, () => listDocumentationPublications(directory, { ...scope(filters), ...(publication ? { publication } : {}) })));
     server.registerTool('search_docs', {
-        description: 'Search the documentation by keyword. Partial fallback favors field relevance among results within one meaningful term of the best coverage (at least two matched). Complete lexical matches normally precede partial fallback; stronger near-complete matches can outrank body-only complete matches (matchMode: mixed). Search covers titles, summaries, headings, and bounded article text. For each chosen result, call read.tool with read.arguments exactly. Section recommendations require an author declaration of self-contained content. The result markdownUrl fetches the recommended section or full page; pageMarkdownUrl is always the full-page fallback. Do not guess a section ID or request an outline first.',
+        description: 'Search the documentation by keyword. Use get_publications to discover product/version scope when unknown. Partial fallback favors field relevance among results within one meaningful term of the best coverage (at least two matched). Complete lexical matches normally precede partial fallback; stronger near-complete matches can outrank body-only complete matches (matchMode: mixed). Search covers titles, summaries, headings, and bounded article text. For each chosen result, call read.tool with read.arguments exactly, retaining product and all publication coordinates. Section recommendations require an author declaration of self-contained content. The result markdownUrl fetches the recommended section or full page; pageMarkdownUrl is always the full-page fallback. Do not guess a section ID or request an outline first.',
         inputSchema: schema(z.object({ query: z.string(), limit: z.number().int().min(1).max(100).default(8), ...options }).strict()),
         annotations,
     }, ({ query, ...filters }, context) => respond('search_docs', context, () => searchDocumentation(directory, query, scope(filters))));
     server.registerTool('get_page', {
-        description: 'Read a published Markdown page by the stable document ID returned from search_docs. Includes all reader-marked sections. Check budget.truncated; increase maxTokens if needed.',
+        description: 'Read a published Markdown page by the stable document ID returned from search_docs. Retain its product/channel/version/language coordinates; IDs can repeat across products. Includes all reader-marked sections. Check budget.truncated; increase maxTokens if needed.',
         inputSchema: schema(z.object({ id: z.string(), ...options }).strict()),
         annotations,
     }, ({ id, ...filters }, context) => respond('get_page', context, () => getDocumentationPage(directory, id, scope(filters))));

package/dist/docs-tool.d.ts

@@ -20,6 +20,7 @@ export declare function searchShoalrunDocs(query: string): Promise<({
                 channel: string;
                 version: string;
                 language: string;
+                product?: string | undefined;
                 section?: string | undefined;
                 id: string;
             };
@@ -27,11 +28,7 @@ export declare function searchShoalrunDocs(query: string): Promise<({
     }[];
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: import("./publication-identity.js").PublicationCoordinate;
     total: number;
     matchMode?: undefined;
 } | {
@@ -56,6 +53,7 @@ export declare function searchShoalrunDocs(query: string): Promise<({
                 channel: string;
                 version: string;
                 language: string;
+                product?: string | undefined;
                 section?: string | undefined;
                 id: string;
             };
@@ -63,11 +61,7 @@ export declare function searchShoalrunDocs(query: string): Promise<({
     }[];
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: import("./publication-identity.js").PublicationCoordinate;
     total: number;
     matchMode: string;
 }) & {

package/dist/document-sync.d.ts

@@ -2,6 +2,7 @@ export declare function canonicalJson(value: unknown): string;
 export type SyncDocument = {
     id: string;
     variant: {
+        product?: string;
         channel: string;
         version: string;
         language: string;

package/dist/document-sync.js

@@ -5,7 +5,7 @@ export function canonicalJson(value) {
     return JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
         ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
 }
-const key = (doc) => JSON.stringify([doc.id, doc.variant.channel, doc.variant.version, doc.variant.language]);
+const key = (doc) => JSON.stringify([doc.id, doc.variant.channel, doc.variant.version, doc.variant.language, ...(doc.variant.product === undefined ? [] : [doc.variant.product])]);
 export function documentSnapshot(manifest, buildId) {
     const { documents, dependencies, buildId: _buildId, ...metadata } = manifest;
     const records = documents.map(doc => ({ id: doc.id, variant: doc.variant, url: doc.url, markdownUrl: doc.markdownUrl,
@@ -32,7 +32,7 @@ export function parseDocumentSnapshot(value) {
     const seen = new Set();
     for (const doc of value.documents) {
         const variant = object(doc) && object(doc.variant) ? doc.variant : {};
-        if (!object(doc) || typeof doc.id !== 'string' || !doc.id.trim() || !object(doc.variant) || ['channel', 'version', 'language'].some(field => typeof variant[field] !== 'string' || !variant[field].trim()) || !route(doc.url) || !route(doc.markdownUrl) || !doc.markdownUrl.endsWith('.md') || !hex(doc.digest) || !hex(doc.contentDigest) || !hex(doc.recordDigest))
+        if (!object(doc) || typeof doc.id !== 'string' || !doc.id.trim() || !object(doc.variant) || (variant.product !== undefined && (typeof variant.product !== 'string' || !variant.product.trim())) || ['channel', 'version', 'language'].some(field => typeof variant[field] !== 'string' || !variant[field].trim()) || !route(doc.url) || !route(doc.markdownUrl) || !doc.markdownUrl.endsWith('.md') || !hex(doc.digest) || !hex(doc.contentDigest) || !hex(doc.recordDigest))
             throw new Error('Invalid document sync record');
         const identity = key(doc);
         if (seen.has(identity))

package/dist/documentation-core.d.ts

@@ -1,4 +1,5 @@
 import { type SearchOptions } from './search-query.js';
+import { type PublicationCoordinate } from './publication-identity.js';
 export declare const bundledDocumentation: string;
 export type DocumentationErrorCode = 'invalid_input' | 'unknown_page' | 'unknown_section' | 'missing_index' | 'internal_error';
 export declare class DocumentationError extends Error {
@@ -16,6 +17,29 @@ export type DocumentationOptions = SearchOptions & {
     maxTokens?: number;
 };
 export declare const documentationTokens: (value: string) => number;
+/** Compact discovery of published coordinates, without returning page inventories. */
+export declare function listDocumentationPublications(directory: string, options?: DocumentationOptions & {
+    offset?: number;
+    publication?: PublicationCoordinate;
+}): Promise<{
+    nextOffset?: number | undefined;
+    products?: {
+        defaultVersion?: any;
+        label?: any;
+        id: string;
+    }[] | undefined;
+    status: "ok";
+    total: number;
+    offset: number;
+    publications: PublicationCoordinate[];
+} & {
+    budget: {
+        maxTokens: number;
+        encoding: string;
+        tokens: number;
+        truncated: boolean;
+    };
+}>;
 export declare function searchDocumentation(directory: string, query: string, options?: DocumentationOptions): Promise<({
     results: never[] | {
         snippet: string;
@@ -38,6 +62,7 @@ export declare function searchDocumentation(directory: string, query: string, op
                 channel: string;
                 version: string;
                 language: string;
+                product?: string | undefined;
                 section?: string | undefined;
                 id: string;
             };
@@ -45,11 +70,7 @@ export declare function searchDocumentation(directory: string, query: string, op
     }[];
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: PublicationCoordinate;
     total: number;
     matchMode?: undefined;
 } | {
@@ -74,6 +95,7 @@ export declare function searchDocumentation(directory: string, query: string, op
                 channel: string;
                 version: string;
                 language: string;
+                product?: string | undefined;
                 section?: string | undefined;
                 id: string;
             };
@@ -81,11 +103,7 @@ export declare function searchDocumentation(directory: string, query: string, op
     }[];
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: PublicationCoordinate;
     total: number;
     matchMode: string;
 }) & {
@@ -104,6 +122,7 @@ export declare function getDocumentationPage(directory: string, id: string, opti
     url: string;
     markdownUrl: string;
     publication: {
+        product?: string;
         channel: string;
         version: string;
         language: string;

package/dist/documentation-core.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { markdownTokens } from './markdown-size.js';
 import { queryBuiltSite } from './search-query.js';
+import { publicationKey, samePublication } from './publication-identity.js';
 export const bundledDocumentation = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../agent-docs');
 export class DocumentationError extends Error {
     code;
@@ -18,7 +19,7 @@ function validate(options) {
     const maxTokens = options.maxTokens ?? 4096;
     if (!Number.isSafeInteger(maxTokens) || maxTokens < 256 || maxTokens > 100_000)
         throw new DocumentationError('invalid_input', 'maxTokens must be an integer from 256 to 100000');
-    for (const key of ['channel', 'version', 'language'])
+    for (const key of ['product', 'channel', 'version', 'language'])
         if (options[key] !== undefined && (typeof options[key] !== 'string' || !options[key]?.trim() || options[key].length > 128))
             throw new DocumentationError('invalid_input', `${key} must be nonempty text of at most 128 characters`);
     return maxTokens;
@@ -45,6 +46,39 @@ async function loadJson(directory, name) {
         throw new DocumentationError('internal_error', `Cannot read valid ${name}. Rebuild the documentation.`);
     }
 }
+/** Compact discovery of published coordinates, without returning page inventories. */
+export async function listDocumentationPublications(directory, options = {}) {
+    const maxTokens = validate({ ...options, maxTokens: options.maxTokens ?? 2048 });
+    const limit = options.limit ?? 20;
+    const offset = options.offset ?? 0;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(offset) || offset < 0)
+        throw new DocumentationError('invalid_input', 'limit must be from 1 to 100 and offset must be a nonnegative safe integer');
+    const manifest = await loadJson(directory, 'documents.json');
+    const source = manifest?.publications?.enabled ?? manifest?.documents?.map((doc) => doc.variant);
+    const valid = (item) => item && typeof item === 'object' && !Array.isArray(item) && ['channel', 'version', 'language'].every(key => typeof item[key] === 'string' && item[key].length > 0 && item[key].length <= 128) && (item.product === undefined || typeof item.product === 'string' && item.product.length > 0 && item.product.length <= 128);
+    if (manifest?.schemaVersion !== 1 || !Array.isArray(source) || source.some(item => !valid(item)))
+        throw new DocumentationError('internal_error', 'Invalid publication metadata. Rebuild the documentation.');
+    const coordinates = source.map((item) => ({ channel: item.channel, version: item.version, language: item.language, ...(item.product === undefined ? {} : { product: item.product }) }));
+    const available = [...new Map(coordinates.map((item) => [publicationKey(item), item])).values()]
+        .filter(item => (!options.publication || samePublication(item, options.publication)) && ['product', 'channel', 'version', 'language'].every(key => !options[key] || item[key] === options[key]))
+        .sort((a, b) => publicationKey(a).localeCompare(publicationKey(b)));
+    const total = available.length;
+    let publications = available.slice(offset, offset + limit);
+    while (true) {
+        const products = [...new Set(publications.flatMap(item => item.product === undefined ? [] : [item.product]))].map(id => {
+            const catalog = manifest.publications?.products?.[id];
+            const defaultVersion = typeof catalog?.defaultVersion === 'string' && available.some(item => item.product === id && item.version === catalog.defaultVersion) ? catalog.defaultVersion : undefined;
+            return { id, ...(typeof catalog?.label === 'string' ? { label: catalog.label.slice(0, 160) } : {}), ...(defaultVersion === undefined ? {} : { defaultVersion }) };
+        });
+        const nextOffset = offset + publications.length < total ? offset + publications.length : undefined;
+        const result = budget({ status: 'ok', total, offset, publications, ...(products.length ? { products } : {}), ...(nextOffset === undefined ? {} : { nextOffset }) }, maxTokens, nextOffset !== undefined);
+        if (result.fits)
+            return result.result;
+        if (!publications.length || publications.length === 1)
+            throw new DocumentationError('invalid_input', 'maxTokens is too small for publication metadata. Increase the budget.');
+        publications = publications.slice(0, -1);
+    }
+}
 export async function searchDocumentation(directory, query, options = {}) {
     const maxTokens = validate(options);
     if (typeof query !== 'string' || !query.trim() || query.length > 512)
@@ -76,14 +110,14 @@ async function selectDocument(directory, id, options) {
     if (typeof id !== 'string' || !id.trim() || id.length > 256)
         throw new DocumentationError('invalid_input', 'id must be nonempty text of at most 256 characters');
     const manifest = await loadJson(directory, 'documents.json');
-    if (manifest?.schemaVersion !== 1 || !Array.isArray(manifest.documents) || manifest.documents.some((doc) => !doc || typeof doc.id !== 'string' || typeof doc.title !== 'string' || typeof doc.url !== 'string' || typeof doc.markdownUrl !== 'string' || !doc.variant || ['channel', 'version', 'language'].some(key => typeof doc.variant[key] !== 'string')))
+    if (manifest?.schemaVersion !== 1 || !Array.isArray(manifest.documents) || manifest.documents.some((doc) => !doc || typeof doc.id !== 'string' || typeof doc.title !== 'string' || typeof doc.url !== 'string' || typeof doc.markdownUrl !== 'string' || !doc.variant || (doc.variant.product !== undefined && (typeof doc.variant.product !== 'string' || !doc.variant.product)) || ['channel', 'version', 'language'].some(key => typeof doc.variant[key] !== 'string')))
         throw new DocumentationError('internal_error', 'Invalid documents.json. Rebuild the documentation.');
     const matching = manifest.documents.filter((doc) => doc.id === id);
     if (!matching.length)
         throw new DocumentationError('unknown_page', `No document with ID ${id}; search the documentation first.`);
-    const selected = matching.filter((doc) => ['channel', 'version', 'language'].every(key => !options[key] || doc.variant[key] === options[key]));
+    const selected = matching.filter((doc) => ['product', 'channel', 'version', 'language'].every(key => !options[key] || doc.variant[key] === options[key]));
     if (selected.length !== 1)
-        throw new DocumentationError('invalid_input', selected.length ? 'Page has multiple publications; select channel, version, and language.' : 'Page does not match the selected publication.');
+        throw new DocumentationError('invalid_input', selected.length ? 'Page has multiple publications; select product where applicable, channel, version, and language.' : 'Page does not match the selected publication.');
     return selected[0];
 }
 async function readMarkdown(directory, markdownUrl) {

package/dist/embeddings.d.ts

@@ -1,4 +1,4 @@
-import { type Chunk, type ChunkIndex } from './index-build.js';
+import type { Chunk, ChunkIndex } from './index-build.js';
 import { type Transport } from './provider-http.js';
 export type EmbedInputType = 'document' | 'query';
 export type EmbeddingProvider = {

package/dist/embeddings.js

@@ -1,7 +1,7 @@
 import { readFile, realpath, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
-import { aiDirectory } from './index-build.js';
+import { aiDirectory } from './ai-directory.js';
 import { postJson, throwIfCancelled } from './provider-http.js';
 const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 function normalize(vector) {

package/dist/freshness.js

@@ -10,7 +10,7 @@ function stable(value) {
     return value;
 }
 export function contentDigest(doc, htmlTree, markdownTree) {
-    const fields = ['id', 'title', 'summary', 'description', 'type', 'slug', 'date', 'releaseVersion', 'subjectLifecycle', 'audiences', 'readerFilters', 'product', 'area', 'subarea', 'operations', 'displayText'];
+    const fields = ['id', 'title', 'summary', 'description', 'type', 'slug', 'date', 'releaseVersion', 'availability', 'subjectLifecycle', 'audiences', 'readerFilters', 'product', 'area', 'subarea', 'operations', 'displayText'];
     return createHash('sha256').update(JSON.stringify(stable({ metadata: Object.fromEntries(fields.map(key => [key, doc.frontmatter[key]])), html: htmlTree, markdown: markdownTree }))).digest('hex');
 }
 export async function loadFreshness(value, base, today = new Date().toISOString().slice(0, 10)) {
@@ -40,7 +40,7 @@ export async function loadFreshness(value, base, today = new Date().toISOString(
     const current = {};
     return {
         resolve(doc, digest, fallback) {
-            const key = JSON.stringify([doc.frontmatter.id, doc.variant.channel, doc.variant.version, doc.variant.language]);
+            const key = JSON.stringify([doc.frontmatter.id, doc.variant.channel, doc.variant.version, doc.variant.language, ...(doc.variant.product === undefined ? [] : [doc.variant.product])]);
             const previous = history.documents[key];
             const updated = previous ? previous.contentDigest === digest ? previous.updated : today : doc.frontmatter.updated ?? fallback ?? today;
             current[key] = { contentDigest: digest, updated };

package/dist/frontmatter.js

@@ -3,7 +3,7 @@ import { validateSubjectDeprecation } from './subject-deprecation.js';
 import { validateCardMetadata } from './cards.js';
 import { resolveTaxonomy, validateTaxonomy, taxonomySchema } from './taxonomy.js';
 import { validateStandaloneSectionDeclarations } from './section-identity.js';
-export const nativePublicFields = new Set(['id', 'title', 'type', 'summary', 'description', 'language', 'locale', 'date', 'updated', 'verified', 'releaseVersion', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'audiences', 'readerFilters', 'tags', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle']);
+export const nativePublicFields = new Set(['id', 'title', 'type', 'summary', 'description', 'language', 'locale', 'date', 'updated', 'verified', 'releaseVersion', 'availability', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'audiences', 'readerFilters', 'tags', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle']);
 export const protectedMetadataRoots = new Set(['shared', 'requires', 'standaloneSections', 'access', 'seo', 'markdownMetadata', 'variables', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image', 'private', 'internal', 'card', 'displayText', 'publications']);
 const fieldTypes = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array']);
 const safePath = (value) => /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)*$/.test(value);
@@ -33,7 +33,7 @@ export function frontmatterLayers(config = {}) {
         const layer = config[name] === undefined ? {} : config[name];
         if (!object(layer))
             throw new Error(`frontmatter.${name} must be a mapping`);
-        for (const field of ['id', 'slug', 'shared', 'publications', 'standaloneSections', 'subjectDeprecation', 'change'])
+        for (const field of ['id', 'slug', 'shared', 'publications', 'standaloneSections', 'subjectDeprecation', 'change', 'availability'])
             if (Object.hasOwn(layer, field))
                 throw new Error(`frontmatter.${name}.${field} must stay page-specific`);
         layers[name] = mergeMetadata({}, layer);
@@ -126,6 +126,11 @@ export function validateFrontmatter(frontmatter, config, file, source) {
     if (frontmatter.type === 'changelog-entry' &&
         (mode === 'date' && frontmatter.date === undefined || mode === 'version' && frontmatter.releaseVersion === undefined || mode === 'either' && frontmatter.date === undefined && frontmatter.releaseVersion === undefined))
         throw new Error(`${file}: changelog-entry pages need ${mode === 'either' ? 'date or releaseVersion' : mode === 'version' ? 'releaseVersion' : 'date'}`);
+    if (frontmatter.availability !== undefined) {
+        const value = frontmatter.availability;
+        if (!object(value) || !Object.keys(value).length || Object.keys(value).some(key => !['since', 'through'].includes(key)) || Object.values(value).some(label => typeof label !== 'string' || !label.trim()))
+            throw new Error(`${file}: availability must contain nonempty since and/or through version labels`);
+    }
     if (frontmatter.releaseVersion !== undefined && (typeof frontmatter.releaseVersion !== 'string' || !frontmatter.releaseVersion.trim()))
         throw new Error(`${file}: releaseVersion must be nonempty text`);
     for (const field of ['date', 'verified'])
@@ -151,10 +156,10 @@ export function validateFrontmatter(frontmatter, config, file, source) {
     }
     if (frontmatter.publications !== undefined) {
         const publications = frontmatter.publications;
-        if (!Array.isArray(publications) || !publications.length || publications.some(item => !object(item) || Object.keys(item).some(key => !['channel', 'version'].includes(key)) || typeof item.channel !== 'string' || !item.channel.trim() || typeof item.version !== 'string' || !item.version.trim())) {
+        if (!Array.isArray(publications) || !publications.length || publications.some(item => !object(item) || Object.keys(item).some(key => !['product', 'channel', 'version'].includes(key)) || (item.product !== undefined && (typeof item.product !== 'string' || !item.product.trim())) || typeof item.channel !== 'string' || !item.channel.trim() || typeof item.version !== 'string' || !item.version.trim())) {
             throw new Error(`${file}: publications must list channel and version pairs`);
         }
-        const keys = publications.map(item => `${item.channel}|${item.version}`);
+        const keys = publications.map(item => `${item.product ?? ''}|${item.channel}|${item.version}`);
         if (new Set(keys).size !== keys.length)
             throw new Error(`${file}: publications has duplicate channel/version pairs`);
     }
@@ -230,14 +235,15 @@ export function frontmatterSchema(config) {
         date: { type: 'string', format: 'date', description: 'Publication date in YYYY-MM-DD format; optional for release notes and one possible changelog identifier.' },
         updated: { type: 'string', description: 'Date of the last meaningful page update: YYYY-MM-DD or a timezone-qualified ISO timestamp. Used as sitemap lastmod.' },
         verified: { type: 'string', format: 'date', description: 'Date someone verified the technical claims; independent of content revision and never assigned by the build.' },
+        availability: { type: 'object', minProperties: 1, additionalProperties: false, properties: { since: { type: 'string', minLength: 1, pattern: '\\S' }, through: { type: 'string', minLength: 1, pattern: '\\S' } }, description: 'Inclusive feature availability labels shown beside page dates and retained in Markdown and the document manifest. Does not select or hide publications; labels are not compared or inferred.' },
         releaseVersion: { type: 'string', minLength: 1, description: 'Release label for a note or changelog entry; separate from the documentation publication version.' },
         slug: { type: 'string', description: 'Page URL path before channel, version, and language prefixes.' },
         channel: { type: 'string', description: 'Publication environment, such as sandbox or production; selects an enabled publication and API source.' },
         version: { type: 'string', description: 'API or documentation edition, such as v1; selects an enabled publication and API source.' },
-        publications: { type: 'array', minItems: 1, items: { type: 'object', properties: { channel: { type: 'string' }, version: { type: 'string' } }, required: ['channel', 'version'], additionalProperties: false }, description: 'Publish this one page file in each listed channel/version pair. Use instead of page-level channel and version; language stays the same.' },
+        publications: { type: 'array', minItems: 1, items: { type: 'object', properties: { product: { type: 'string', minLength: 1 }, channel: { type: 'string' }, version: { type: 'string' } }, required: ['channel', 'version'], additionalProperties: false }, description: 'Publish this one page file in each listed product/channel/version coordinate. Use instead of page-level channel and version; language stays the same.' },
         language: { type: 'string', description: 'Content language; uses frontmatter defaults/enforced values, then publications.defaults.language, then en.' },
         locale: { type: 'string', description: 'Formatting conventions used in the content; can inherit a project locale for the page language and can be overridden per page.' },
-        product: { type: 'string', minLength: 1, description: 'Optional product category. Also selects the product reader facet when that facet is configured.' },
+        product: { type: 'string', minLength: 1, description: 'Product publication ID when publications.products is configured; otherwise an optional category and reader facet.' },
         area: { type: 'string', minLength: 1, description: 'Optional area category. Also selects the area reader facet when that facet is configured.' },
         subarea: { type: 'string', minLength: 1, description: 'Optional finer category. Also selects the subarea reader facet when that facet is configured.' },
         operations: { type: 'array', items: { type: 'string' }, description: 'Stable API operation IDs that connect this page to endpoint references and related documents.' },
@@ -326,7 +332,7 @@ export function frontmatterReference(config, sectionsOnly = false) {
         'Language is the content language and selects a publication. Locale describes formatting conventions in the content and does not select a publication. `frontmatter.locales` can set a project locale for each language; pages may override it.', '',
         '## Categorize, connect, and present the page', '',
         'By default, `product`, `area`, and `subarea` are optional, nonempty string categories. They can come from project defaults and appear in the document manifest and search index. A matching configured reader facet makes each category a page filter; without that facet it remains taxonomy only. `operations` links a guide or reference to stable API operation IDs. On a guide or how-to page, `relatedApiReferences` names API reference page IDs to add cross links in both directions within the same publication. Tags help document collections find the page. Card settings change its preview when another page links to it; they do not change the destination. `subjectLifecycle` displays the status of the documented API or feature; `lifecycle` is available for the document\'s editorial state. `tocDepth` limits the HTML page table of contents; use 0 to hide it. `layout` picks the HTML page layout: `docs`, `wide`, `landing`, or `splash`. `showNavigationTabs` overrides the navigation tab bar for this page; landing and splash pages hide it by default. `image` replaces the generated link-preview image. `date` and `releaseVersion` can identify a changelog entry under the project\'s `frontmatter.changelogIdentifier` rule.', '',
-        ...table, ...nativeRows(['product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'tags', 'date', 'releaseVersion', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle', 'card', 'standaloneSections', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image']), '',
+        ...table, ...nativeRows(['availability', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'tags', 'date', 'releaseVersion', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle', 'card', 'standaloneSections', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image']), '',
         'Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.', '',
         'With `profiles.requireClassification: true`, every public source page in the shared enabled publications needs an explicit `shared: true` or `requires` declaration before customer selection. Defaults do not count. Shared pages may contain feature-specific sections wrapped in `<ForFeature>`; unwrapped text remains shared.', '',
         '## Control output details', '',

package/dist/function-package.js

@@ -55,4 +55,9 @@ export async function copyFunctionRuntime(dist, entry, target) {
     const done = new Set();
     for (const name of packages)
         await copyPackage(name, dist, target, done);
+    // Preserve the runtime author's license as well as the licenses retained in
+    // copied dependency packages. Custom runtime directories may have no parent license.
+    const license = path.join(dist, '..', 'LICENSE');
+    if (await stat(license).then(info => info.isFile(), () => false))
+        await cp(license, path.join(target, 'LICENSE.shoalrun'));
 }

package/dist/function-runtime.d.ts

@@ -0,0 +1,24 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export type FunctionRuntime = {
+    schemaVersion: 1;
+    settings: Record<string, unknown>;
+    variant?: {
+        product?: string;
+        channel: string;
+        version: string;
+        language: string;
+    };
+    hosts?: string[];
+    callerHeader?: string;
+    maxRequestsPerMinute?: number;
+    searchStore?: {
+        provider: 'upstash';
+        urlEnv: string;
+        tokenEnv: string;
+    };
+};
+export type AskFunction = (request: Request) => Promise<Response>;
+export declare function allowedHosts(runtime: FunctionRuntime, env: NodeJS.ProcessEnv): string[];
+export declare function nodeAdapter(load: () => Promise<AskFunction>, limits?: {
+    bodyBytes: number;
+}): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/dist/function-runtime.js

@@ -0,0 +1,45 @@
+export function allowedHosts(runtime, env) {
+    return [...new Set([...(runtime.hosts ?? []), env.VERCEL_URL, env.VERCEL_BRANCH_URL, env.VERCEL_PROJECT_PRODUCTION_URL, ...(env.SHOALRUN_ASK_HOSTS?.split(',') ?? [])].map(host => host?.trim().toLowerCase()).filter((host) => Boolean(host)))];
+}
+const failure = (status, message) => new Response(JSON.stringify({ error: message }), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' } });
+// Vercel's Node runtime calls `(req, res)`. This turns that into a Web request and back. Starting up happens on the first request, and a
+// failed start is tried again on the next one. The reader never sees why it failed; the reason goes to the function log.
+export function nodeAdapter(load, limits = { bodyBytes: 32_768 }) {
+    let ready;
+    const write = async (res, response) => {
+        res.statusCode = response.status;
+        response.headers.forEach((value, name) => { if (name !== 'set-cookie')
+            res.setHeader(name, value); });
+        const cookies = response.headers.getSetCookie();
+        if (cookies.length)
+            res.setHeader('set-cookie', cookies);
+        res.end(Buffer.from(await response.arrayBuffer()));
+    };
+    return async (req, res) => {
+        try {
+            const handler = await (ready ??= load().catch(error => { ready = undefined; throw error; }));
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of req) {
+                size += chunk.length;
+                if (size > limits.bodyBytes) {
+                    await write(res, failure(413, 'The request is too large.'));
+                    return;
+                }
+                chunks.push(chunk);
+            }
+            const headers = new Headers();
+            for (const [name, value] of Object.entries(req.headers))
+                for (const item of Array.isArray(value) ? value : value === undefined ? [] : [value])
+                    headers.append(name, item);
+            const method = req.method ?? 'GET';
+            const request = new Request(`https://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, { method, headers, ...(method === 'GET' || method === 'HEAD' ? {} : { body: Buffer.concat(chunks) }) });
+            await write(res, await handler(request));
+        }
+        catch (error) {
+            console.error(`The answer function failed: ${error.message}`);
+            if (!res.headersSent)
+                await write(res, failure(503, 'The chat is unavailable right now.'));
+        }
+    };
+}

package/dist/index-build.d.ts

@@ -1,3 +1,4 @@
+export { aiDirectory } from './ai-directory.js';
 import { type PreparedSearchPassage } from './search-snippet.js';
 export type Chunk = {
     id: string;
@@ -35,6 +36,7 @@ type ManifestDocument = {
     digest: string;
     readerFilters?: Record<string, string[]>;
     variant: {
+        product?: string;
         channel: string;
         version: string;
         language: string;
@@ -46,10 +48,8 @@ export declare function chunkMarkdown(markdown: string, document: ChunkSource, a
     id: string;
     title: string;
 }>, options?: ChunkOptions): Chunk[];
-export declare function aiDirectory(directory: string): Promise<string>;
 export declare function buildChunkIndex(directory: string, options?: ChunkOptions): Promise<{
     index: ChunkIndex;
     output: string;
     documents: number;
 }>;
-export {};

package/dist/index-build.js

@@ -1,5 +1,8 @@
+import { publicationKey } from './publication-identity.js';
+import { aiDirectory } from './ai-directory.js';
+export { aiDirectory } from './ai-directory.js';
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { readFile, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { validateSearchSynonyms } from './search-synonyms.js';
 import { prepareSearchPassage } from './search-snippet.js';
@@ -187,16 +190,6 @@ async function readJson(file) {
 }
 // The directory that holds the passage and vector files. It is created on demand, and it must stay inside the site even if
 // `ai` is a symlink.
-export async function aiDirectory(directory) {
-    const root = path.resolve(directory);
-    const target = path.join(root, 'ai');
-    await mkdir(target, { recursive: true });
-    const real = await realpath(root);
-    const inside = await realpath(target);
-    if (inside !== real && !inside.startsWith(real + path.sep))
-        throw new Error('The ai directory leaves the site directory');
-    return target;
-}
 export async function buildChunkIndex(directory, options = {}) {
     const root = path.resolve(directory);
     const manifest = await readJson(path.join(root, 'documents.json'));
@@ -218,8 +211,7 @@ export async function buildChunkIndex(directory, options = {}) {
         if (!inside(await realpath(file)))
             throw new Error(`Markdown path for ${document.id} leaves the site directory`);
         const markdown = await readFile(file, 'utf8');
-        const { channel, version, language } = document.variant;
-        chunks.push(...chunkMarkdown(markdown, { ...document, variant: `${channel}|${version}|${language}` }, anchors.get(document.url), options));
+        chunks.push(...chunkMarkdown(markdown, { ...document, variant: publicationKey(document.variant) }, anchors.get(document.url), options));
     }
     // Generation identity includes publication membership, routes, reader marks,
     // and prepared search evidence. Embedding digests remain content-only.

package/dist/ingredient-draft.js

@@ -1,3 +1,5 @@
+import { samePublication } from './publication-identity.js';
+import { resolvePublication } from './compiler-config.js';
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -10,13 +12,15 @@ const object = (value) => !!value && typeof value === 'object' && !Array.isArray
 const digest = (value) => createHash('sha256').update(value).digest('hex');
 function parseSpec(value) {
     const fields = ['schemaVersion', 'id', 'title', 'summary', 'slug', 'operation', 'requestExample'];
-    if (!object(value) || value.schemaVersion !== 1 || Object.keys(value).some(key => ![...fields, 'workflow'].includes(key)))
+    if (!object(value) || value.schemaVersion !== 1 || Object.keys(value).some(key => ![...fields, 'workflow', 'publication'].includes(key)))
         throw new Error('Ingredient spec needs schemaVersion: 1 and only supported fields');
     for (const field of fields.slice(1))
         if (typeof value[field] !== 'string' || !value[field].trim())
             throw new Error(`Ingredient spec needs ${field}`);
     if (!/^\/[a-z0-9/-]+$/.test(value.slug) || value.slug.includes('//') || value.slug.split('/').includes('..'))
         throw new Error('Ingredient slug must be a lowercase absolute path');
+    if (value.publication !== undefined && (!object(value.publication) || Object.keys(value.publication).some(key => !['product', 'channel', 'version', 'language'].includes(key)) || Object.values(value.publication).some(item => typeof item !== 'string' || !item)))
+        throw new Error('Ingredient publication must declare product/channel/version/language strings');
     const workflow = ingredientWorkflow(value.workflow, 'Ingredient workflow');
     return { ...value, ...(workflow ? { workflow } : {}) };
 }
@@ -39,10 +43,20 @@ export async function renderIngredientDraft(configFile, specFile) {
     if (matching.length !== 1)
         throw new Error(`Ingredient operation ${spec.operation} must name one explicitly configured API operation`);
     const { apiId, api, operation } = matching[0];
-    if (api.source?.kind !== 'file' || typeof api.source.path !== 'string')
-        throw new Error(`Ingredient operation ${spec.operation} needs a local OpenAPI source in the default publication`);
-    const origin = explain(loaded, `apis.${apiId}.source.path`).source.file;
-    const source = path.resolve(path.dirname(origin), api.source.path);
+    const defaults = config.publications?.defaults ?? {};
+    const product = config.publications.products ? spec.publication?.product ?? api.product ?? defaults.product : undefined;
+    const publication = resolvePublication(config.publications, { ...defaults, ...spec.publication, ...(product ? { product, version: spec.publication?.version } : {}) }, defaultLanguage(config));
+    const publicationIndex = api.publications?.findIndex((item) => item.product === publication.product && item.channel === publication.channel && item.version === publication.version) ?? -1;
+    const defaultSourcePublication = api.source ? resolvePublication(config.publications, { ...defaults, ...(config.publications.products && api.product ? { product: api.product, version: undefined } : {}) }, defaultLanguage(config)) : undefined;
+    const binding = publicationIndex >= 0 ? api.publications[publicationIndex].source : defaultSourcePublication && publication.product === defaultSourcePublication.product && publication.channel === defaultSourcePublication.channel && publication.version === defaultSourcePublication.version ? api.source : undefined;
+    if (!config.publications.enabled?.some((item) => samePublication(resolvePublication(config.publications, item, defaultLanguage(config)), publication)))
+        throw new Error('Ingredient publication is not enabled');
+    if (publicationIndex < 0 && config.publications.products && publication.product !== (api.product ?? defaults.product))
+        throw new Error('Ingredient needs an OpenAPI source for its selected product');
+    if (binding?.kind !== 'file' || typeof binding.path !== 'string')
+        throw new Error(`Ingredient operation ${spec.operation} needs a local OpenAPI source in the selected publication`);
+    const origin = explain(loaded, publicationIndex >= 0 ? `apis.${apiId}.publications.${publicationIndex}.source.path` : `apis.${apiId}.source.path`).source.file;
+    const source = path.resolve(path.dirname(origin), binding.path);
     const reader = new ApiReader(root);
     const details = await reader.operation(source, operation.sourceOperationId, spec.operation);
     const sourceDigest = digest((await Promise.all([...reader.dependencies].sort().map(async (file) => `${path.relative(root, file)}\n${await readFile(file, 'utf8')}`))).join('\n'));
@@ -52,13 +66,9 @@ export async function renderIngredientDraft(configFile, specFile) {
     if (requests.length !== 1 || !requests[0].curl)
         throw new Error(`Request example ${spec.requestExample} needs one inline example with a generated cURL command`);
     const response = details.examples.find(example => example.location === 'response' && /^2\d\d$/.test(example.status ?? '') && example.value !== undefined);
-    const defaults = config.publications?.defaults ?? {};
-    if (!defaults.channel || !defaults.version)
-        throw new Error('Ingredient draft needs a default channel and version');
-    const language = defaults.language ?? defaultLanguage(config);
     const header = {
         id: spec.id, title: spec.title, summary: spec.summary, type: 'ingredient', slug: spec.slug,
-        channel: defaults.channel, version: defaults.version, language,
+        ...publication,
         operations: [spec.operation], access: { policy: 'draft' }, ...(spec.workflow ? { workflow: spec.workflow } : {})
     };
     const reference = operation.reference ? `[${details.method.toUpperCase()} ${details.route}](doc:${operation.reference})` : `\`${details.method.toUpperCase()} ${details.route}\``;

package/dist/mcp-analytics.d.ts

@@ -10,6 +10,7 @@ export type McpAnalyticsEvent = McpClientMetadata & {
     sectionId?: string;
     buildId: string;
     publication: {
+        product?: string;
         channel: string;
         version: string;
         language: string;