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

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-runtime.d.ts

@@ -3,6 +3,7 @@ export type FunctionRuntime = {
     schemaVersion: 1;
     settings: Record<string, unknown>;
     variant?: {
+        product?: string;
         channel: string;
         version: string;
         language: string;

package/dist/index-build.d.ts

@@ -36,6 +36,7 @@ type ManifestDocument = {
     digest: string;
     readerFilters?: Record<string, string[]>;
     variant: {
+        product?: string;
         channel: string;
         version: string;
         language: string;

package/dist/index-build.js

@@ -1,3 +1,4 @@
+import { publicationKey } from './publication-identity.js';
 import { aiDirectory } from './ai-directory.js';
 export { aiDirectory } from './ai-directory.js';
 import { createHash } from 'node:crypto';
@@ -210,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;

package/dist/mcp-artifacts.js

@@ -1,3 +1,4 @@
+import { publicationKey, samePublication } from './publication-identity.js';
 import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -10,8 +11,8 @@ export async function addMcpArtifacts(artifacts, config, manifest, rendered, hea
     if (!mcp)
         return;
     const endpoint = `${manifest.basePath}${mcp.path}`;
-    const variant = ['channel', 'version', 'language'].map(key => mcp.publication[key]).join('|');
-    const selected = rendered.filter(page => ['channel', 'version', 'language'].every(key => page.doc.variant[key] === mcp.publication[key]));
+    const variant = publicationKey(mcp.publication);
+    const selected = rendered.filter(page => samePublication(page.doc.variant, mcp.publication));
     if (!selected.length || selected.some(page => page.doc.frontmatter.access?.policy !== 'public'))
         throw new Error('mcp.publication must select nonempty, normally published public documentation');
     for (const artifact of artifacts.keys()) {
@@ -24,7 +25,7 @@ export async function addMcpArtifacts(artifacts, config, manifest, rendered, hea
     }
     if (manifest.redirects.some((r) => r.from === endpoint || r.markdownFrom === endpoint))
         throw new Error('MCP endpoint conflicts with a redirect');
-    const docs = manifest.documents.filter((doc) => ['channel', 'version', 'language'].every(key => doc.variant[key] === mcp.publication[key]));
+    const docs = manifest.documents.filter((doc) => samePublication(doc.variant, mcp.publication));
     const inventory = {};
     const put = (file, value) => {
         artifacts.set(`${mcpDataPath}/${file}`, value);
@@ -38,7 +39,15 @@ export async function addMcpArtifacts(artifacts, config, manifest, rendered, hea
         }) };
     if (search.documents.some(doc => doc.variant !== variant))
         throw new Error('MCP search publication mismatch');
-    put('documents.json', JSON.stringify({ schemaVersion: 1, documents: docs }));
+    const catalog = mcp.publication.product === undefined ? undefined : manifest.publications?.products?.[mcp.publication.product];
+    const scopedProducts = catalog && mcp.publication.product ? { [mcp.publication.product]: {
+            ...(typeof catalog.label === 'string' ? { label: catalog.label } : {}),
+            ...(catalog.defaultVersion === mcp.publication.version ? { defaultVersion: catalog.defaultVersion } : {}),
+            versions: [mcp.publication.version],
+        } } : undefined;
+    put('documents.json', JSON.stringify({ schemaVersion: 1, documents: docs,
+        ...(manifest.publications ? { publications: { enabled: [{ ...mcp.publication }], ...(scopedProducts ? { products: scopedProducts } : {}) } } : {}),
+    }));
     put('search-index.json', JSON.stringify(search));
     for (const doc of docs)
         for (const resource of [doc, ...doc.sections]) {

package/dist/mcp-config.d.ts

@@ -3,6 +3,7 @@ export type McpConfig = {
     access: 'public';
     path: string;
     publication: {
+        product?: string;
         channel: string;
         version: string;
         language: string;

package/dist/mcp-config.js

@@ -15,8 +15,10 @@ export function resolveMcp(value) {
     if (typeof route !== 'string' || !/^\/[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)*$/.test(route) || route.startsWith('/__shoalrun'))
         throw new Error('mcp.path must be a non-reserved absolute path without a trailing slash');
     const publication = configMappingAt(config.publication, 'mcp.publication');
-    if (Object.keys(publication).some(key => !['channel', 'version', 'language'].includes(key)) || ['channel', 'version', 'language'].some(key => typeof publication[key] !== 'string' || !/^[a-zA-Z0-9._-]{1,128}$/.test(publication[key])))
+    if (Object.keys(publication).some(key => !['product', 'channel', 'version', 'language'].includes(key)) || ['channel', 'version', 'language'].some(key => typeof publication[key] !== 'string' || !/^[a-zA-Z0-9._-]{1,128}$/.test(publication[key])))
         throw new Error('mcp.publication needs channel, version, and language');
+    if (publication.product !== undefined && (typeof publication.product !== 'string' || !/^[a-zA-Z0-9._-]{1,128}$/.test(publication.product)))
+        throw new Error('mcp.publication.product must be a product ID');
     const strings = (key) => {
         const values = config[key] ?? [];
         if (!Array.isArray(values) || values.length > 32 || values.some(v => typeof v !== 'string' || !v || v.length > 253))

package/dist/mcp-http.js

@@ -18,7 +18,7 @@ export async function loadMcpRuntime(directory) {
         throw error;
     }
     const runtime = JSON.parse(raw);
-    if (runtime.schemaVersion !== 1 || runtime.access !== 'public' || runtime.enabled !== true || runtime.dataDirectory !== mcpDataPath.slice(1) || !hex(runtime.buildId) || !hex(runtime.corpusDigest) || !runtime.inventory || Array.isArray(runtime.inventory) || fingerprint(JSON.stringify(runtime.inventory)) !== runtime.corpusDigest || !runtime.publication || ['channel', 'version', 'language'].some(key => typeof runtime.publication[key] !== 'string') || !Array.isArray(runtime.allowedHosts) || !Array.isArray(runtime.allowedOrigins) || typeof runtime.path !== 'string' || !/^\/[a-zA-Z0-9_/-]+$/.test(runtime.path))
+    if (runtime.schemaVersion !== 1 || runtime.access !== 'public' || runtime.enabled !== true || runtime.dataDirectory !== mcpDataPath.slice(1) || !hex(runtime.buildId) || !hex(runtime.corpusDigest) || !runtime.inventory || Array.isArray(runtime.inventory) || fingerprint(JSON.stringify(runtime.inventory)) !== runtime.corpusDigest || !runtime.publication || (runtime.publication.product !== undefined && (typeof runtime.publication.product !== 'string' || !runtime.publication.product)) || ['channel', 'version', 'language'].some(key => typeof runtime.publication[key] !== 'string') || !Array.isArray(runtime.allowedHosts) || !Array.isArray(runtime.allowedOrigins) || typeof runtime.path !== 'string' || !/^\/[a-zA-Z0-9_/-]+$/.test(runtime.path))
         throw new Error('Invalid MCP runtime metadata; rebuild the public site');
     if (runtime.analytics?.consent)
         resolveMcp({ enabled: true, access: 'public', publication: runtime.publication, analytics: { ...runtime.analytics, module: './adapter.mjs' } });

package/dist/page-materialization.d.ts

@@ -9,6 +9,7 @@ import type { SnippetDefinition, SnippetUse } from './snippets.js';
 import type { ReaderFiltersConfig } from './reader-filters.js';
 import type { resolveCalloutTypes } from './callouts.js';
 import type { resolveBadgeVariants } from './badges.js';
+import type { CompilerPublicationsConfig } from './compiler-config.js';
 type ApiPlan = Awaited<ReturnType<typeof materializeApiReferences>>;
 type SourceBinding = NonNullable<ReturnType<ApiPlan['sourceForVariant']>>;
 export type MaterializedPage = {
@@ -25,10 +26,7 @@ export type MaterializedPage = {
 export declare function materializePages({ variables, frontmatterConfig, publications, docs, linkDocuments, apiPlan, sourceForOperation, snippets, calloutTypes, badgeVariants, componentPlugins, readerFilters, base, publicPath, relatedApiTargets, guidesByApi }: {
     variables: Record<string, unknown>;
     frontmatterConfig: unknown;
-    publications: {
-        channels: Record<string, unknown>;
-        versions: Record<string, unknown>;
-    };
+    publications: CompilerPublicationsConfig;
     docs: Map<string, Document>;
     linkDocuments?: Map<string, Document>;
     apiPlan: ApiPlan;
@@ -67,6 +65,7 @@ export declare function materializePages({ variables, frontmatterConfig, publica
     operations: Record<string, {
         id: string;
         type: string;
+        product?: string;
         channel: string;
         version: string;
         language: string;

package/dist/page-materialization.js

@@ -1,3 +1,4 @@
+import { documentKey, publicationKey } from './publication-identity.js';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { resolveApiEmbedTree } from './api-embeds.js';
@@ -7,7 +8,7 @@ import { isConfigMapping } from './compiler-config.js';
 const generatedReferenceBody = 'This reference is generated from the OpenAPI description. It shows the operation contract; follow any related guides below for task steps and context.\n';
 const generatedWebhookBody = 'This webhook reference is generated from the OpenAPI description. The provider sends this event to the receiver.\n';
 const digest = (value) => createHash('sha256').update(value).digest('hex');
-const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+const keyFor = documentKey;
 export async function materializePages({ variables, frontmatterConfig, publications, docs, linkDocuments = docs, apiPlan, sourceForOperation, snippets, calloutTypes, badgeVariants, componentPlugins, readerFilters, base, publicPath, relatedApiTargets, guidesByApi }) {
     const { api, queryRules, lifecycleMappings, extensionValue, sourceForVariant, knownOperations } = apiPlan;
     const apiPublications = new Map();
@@ -28,7 +29,7 @@ export async function materializePages({ variables, frontmatterConfig, publicati
             if (keyFor(other.frontmatter.id, doc.variant) === keyFor(other.frontmatter.id, other.variant))
                 local.set(other.frontmatter.id, other);
         const parsed = parse.parse(doc.body);
-        const tree = await resolveApiEmbedTree(transformMdx(parsed, doc, local, snippets, variables, snippetUses, calloutTypes, base, readerFilters, frontmatterConfig, publications, badgeVariants, componentPlugins), api, operationId => sourceForOperation(operationId, doc.variant), apiId => {
+        const tree = await resolveApiEmbedTree(transformMdx(parsed, doc, local, snippets, variables, snippetUses, calloutTypes, base, readerFilters, frontmatterConfig, publications, badgeVariants, componentPlugins, linkDocuments), api, operationId => sourceForOperation(operationId, doc.variant), apiId => {
             if (doc.featureContext?.grants)
                 throw new Error('Standalone API schema embeds require an explicitly scoped source and are not supported in profiled builds; select an operation instead');
             const definition = apiPlan.apiDefinitions[apiId];
@@ -63,7 +64,7 @@ export async function materializePages({ variables, frontmatterConfig, publicati
             const mapped = mapping && (typeof rawLifecycle === 'string' || typeof rawLifecycle === 'number' || typeof rawLifecycle === 'boolean') && Object.hasOwn(mapping.values, String(rawLifecycle)) ? mapping.values[String(rawLifecycle)] : undefined;
             if (mapped && !generated.deprecated && !doc.frontmatter.subjectLifecycle)
                 doc.frontmatter.subjectLifecycle = mapped;
-            const navVariant = `${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`;
+            const navVariant = publicationKey(doc.variant);
             const entries = navigationEntries.get(navVariant) ?? [];
             entries.push({ id: operationId, apiId: binding.apiId, documentId: doc.frontmatter.id, title: doc.frontmatter.title, tag: generated.tags[0] ?? (generated.webhook ? 'Webhooks' : 'Other'), search: `${generated.webhook ? 'webhook' : generated.method.toUpperCase()} ${generated.route} ${binding.sourceOperationId} ${operationId}` });
             navigationEntries.set(navVariant, entries);
@@ -84,7 +85,7 @@ export async function materializePages({ variables, frontmatterConfig, publicati
             pageCurl = generated.curl;
             pageSamples = generated.samples;
             if (source.focused === true || source.publish === true) {
-                const coordinates = [doc.variant.channel, doc.variant.version, doc.variant.language];
+                const coordinates = [...(doc.variant.product ? [doc.variant.product] : []), doc.variant.channel, doc.variant.version, doc.variant.language];
                 if (coordinates.some(value => !/^[A-Za-z0-9._-]+$/.test(value)))
                     throw new Error(`${doc.file}: unsafe publication coordinate for focused contract`);
                 const name = operationId.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 70) || 'operation';
@@ -105,11 +106,17 @@ export async function materializePages({ variables, frontmatterConfig, publicati
                 const extension = path.extname(sourceFile).toLowerCase();
                 if (!['.yaml', '.yml', '.json'].includes(extension))
                     throw new Error(`Published API source needs YAML or JSON extension: ${sourceFile}`);
-                const sourceUrl = publicPath(`/api/${id}/${doc.variant.channel}/${doc.variant.version}/${path.basename(sourceFile)}`);
+                const sourceUrl = publicPath(`/api/${id}/${doc.variant.product ? `${doc.variant.product}/` : ''}${doc.variant.channel}/${doc.variant.version}/${path.basename(sourceFile)}`);
                 const endpoint = (publicationIndex >= 0 ? binding.definition.publications?.[publicationIndex].discovery?.endpoint : undefined) ?? binding.definition.discovery?.endpoint;
-                const recordKey = `${id}|${doc.variant.channel}|${doc.variant.version}`;
-                if (!apiPublications.has(recordKey))
-                    apiPublications.set(recordKey, { apiId: id, variant: doc.variant, sourceFile, endpoint, referenceUrl: doc.route, sourceUrl, mediaType: extension === '.json' ? 'application/json' : 'application/yaml' });
+                // Source contracts are shared across documentation languages. Keep the
+                // legacy productless identity and publish each source URL only once.
+                const recordKey = `${id}|${doc.variant.channel}|${doc.variant.version}${doc.variant.product ? `|${doc.variant.product}` : ''}`;
+                const mediaType = extension === '.json' ? 'application/json' : 'application/yaml';
+                const previous = apiPublications.get(recordKey);
+                if (previous && (previous.sourceFile !== sourceFile || previous.sourceUrl !== sourceUrl || previous.endpoint !== endpoint || previous.mediaType !== mediaType))
+                    throw new Error(`Conflicting published OpenAPI source for ${recordKey}`);
+                if (!previous)
+                    apiPublications.set(recordKey, { apiId: id, variant: doc.variant, sourceFile, endpoint, referenceUrl: doc.route, sourceUrl, mediaType });
             }
         }
         for (const operationId of doc.frontmatter.operations ?? []) {

package/dist/page-renderer.d.ts

@@ -52,6 +52,12 @@ export type PageShell = {
     header?: HeaderConfig;
     footer?: FooterConfig;
     search?: boolean;
+    publicationChoices?: Array<{
+        label: string;
+        group: string;
+        url: string;
+        current: boolean;
+    }>;
     publicationAlternates?: Array<{
         label: string;
         url: string;

package/dist/page-renderer.js

@@ -1,3 +1,4 @@
+import { publicationKey } from './publication-identity.js';
 import { resolveAgentDiscovery } from './agent-discovery.js';
 import { navigationCounts, navigationHeading } from './compiler-config.js';
 import { navigationTab } from './project-navigation.js';
@@ -6,7 +7,14 @@ import { readerFilterAttribute } from './reader-filters.js';
 import { surfaceText } from './surface-text.js';
 import { normalizeBasePath, sitePath } from './site-path.js';
 import { renderHtmlWithHeadings } from './html-renderer.js';
-const variantKey = (variant) => `${variant.channel}|${variant.version}|${variant.language}`;
+const variantKey = publicationKey;
+function publicationPicker(shell, esc) {
+    const choices = shell.publicationChoices ?? [];
+    if (!choices.length)
+        return '';
+    const groups = [...new Set(choices.map(item => item.group))];
+    return `<select class="publication-picker" data-publication-switcher aria-label="Publication">${groups.map(group => `<optgroup label="${esc(group)}">${choices.filter(item => item.group === group).map(item => `<option value="${esc(item.url)}"${item.current ? ' selected' : ''}>${esc(item.label)}</option>`).join('')}</optgroup>`).join('')}</select><noscript><nav aria-label="Publications">${choices.map(item => `<a href="${esc(item.url)}">${esc(item.label)}</a>`).join(' ')}</nav></noscript>`;
+}
 // Header search is revealed by search.js; without scripts the sidebar filter still works.
 function readerFilterSlot(control, esc) {
     return `<div class="reader-filter-slot" data-reader-filter="${esc(JSON.stringify(control))}"></div>`;
@@ -14,7 +22,7 @@ function readerFilterSlot(control, esc) {
 function headerTools(shell, variant, esc, readerConfig) {
     const header = shell.header ?? { links: [] };
     const alternates = shell.publicationAlternates ?? [];
-    const switcher = alternates.length > 1 ? `<nav class="publication-switcher" aria-label="Switch documentation version"><details><summary><span>Version</span><strong>${esc(alternates.find(item => item.current)?.label ?? '')}</strong></summary><ul>${alternates.map(item => `<li><a href="${esc(item.url)}"${item.current ? ' aria-current="page"' : ''}>${esc(item.label)}</a></li>`).join('')}</ul></details></nav>` : '';
+    const switcher = !shell.publicationChoices?.length && alternates.length > 1 ? `<nav class="publication-switcher" aria-label="Switch documentation version"><details><summary><span>Version</span><strong>${esc(alternates.find(item => item.current)?.label ?? '')}</strong></summary><ul>${alternates.map(item => `<li><a href="${esc(item.url)}"${item.current ? ' aria-current="page"' : ''}>${esc(item.label)}</a></li>`).join('')}</ul></details></nav>` : '';
     const search = shell.search ? `<div class="site-search" data-variant="${esc(variantKey(variant))}" hidden><label class="site-search-label" for="site-search-input">Search documentation</label><input id="site-search-input" type="search" role="combobox" autocomplete="off" spellcheck="false" aria-autocomplete="list" aria-expanded="false" aria-controls="site-search-results"><kbd class="site-search-key" aria-hidden="true">/</kbd><ul id="site-search-results" class="site-search-results" role="listbox" aria-label="Search results" hidden></ul><p class="site-search-status" role="status"></p></div>` : '';
     const links = header.links.length ? `<nav class="header-actions" aria-label="Site links">${header.links.map(link => `<a class="header-${link.style}" href="${esc(link.href)}"${/^https?:/.test(link.href) ? ' rel="noopener"' : ''}>${esc(link.label)}</a>`).join('')}</nav>` : '';
     const toggle = shell.toggle ? `<button type="button" class="mode-toggle" aria-pressed="false" hidden><span class="mode-toggle-label">Dark mode</span><svg class="mode-icon-light" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg><svg class="mode-icon-dark" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401"/></svg></button>` : '';
@@ -85,10 +93,13 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
     const updated = doc.frontmatter.updated && !(changelogEntry && doc.frontmatter.date) ? `<span class="page-date">Updated <time datetime="${esc(doc.frontmatter.updated)}">${esc(doc.frontmatter.updated.slice(0, 10))}</time></span>` : '';
     const verified = doc.frontmatter.verified && doc.frontmatter.showVerified !== false ? `<span class="page-date">Verified <time datetime="${esc(doc.frontmatter.verified)}">${esc(doc.frontmatter.verified)}</time></span>` : '';
     const releaseVersion = doc.frontmatter.releaseVersion ? `<span class="page-version">Version ${esc(doc.frontmatter.releaseVersion)}</span>` : '';
-    const pageDates = changelogEntry ? `<div class="page-meta">${date}${updated}${verified}${releaseVersion}</div>` : `${date}${updated}${verified}${releaseVersion}`;
+    const availability = doc.frontmatter.availability;
+    const availabilityLabels = availability ? `${availability.since ? `<span class="page-version" data-availability="since">Since ${esc(availability.since)}</span>` : ''}${availability.through ? `<span class="page-version" data-availability="through">Through ${esc(availability.through)}</span>` : ''}` : '';
+    const metadata = `${date}${updated}${verified}${releaseVersion}${availabilityLabels}`;
+    const pageDates = metadata ? `<div class="page-meta">${metadata}</div>` : '';
     const containsCurrent = (item) => item.route === doc.route || !!item.items?.some(containsCurrent);
     const activeTab = navigationTab(navigation, doc.route);
-    const analyticsBootstrap = config.analytics ? `<script type="application/json" id="analytics-config">${JSON.stringify({ pageId: doc.frontmatter.id, pageUrl: doc.route, documentType: doc.frontmatter.type, channel: doc.variant.channel, version: doc.variant.version, language: doc.variant.language, ...(activeTab ? { navigationSectionId: activeTab.id } : {}) }).replaceAll('<', '\\u003c')}</script><script type="module" src="/assets/analytics.js"></script>` : '';
+    const analyticsBootstrap = config.analytics ? `<script type="application/json" id="analytics-config">${JSON.stringify({ pageId: doc.frontmatter.id, pageUrl: doc.route, documentType: doc.frontmatter.type, ...doc.variant, ...(activeTab ? { navigationSectionId: activeTab.id } : {}) }).replaceAll('<', '\\u003c')}</script><script type="module" src="/assets/analytics.js"></script>` : '';
     const pageLayout = doc.frontmatter.layout ?? 'docs';
     const showNavigationTabs = doc.frontmatter.showNavigationTabs ?? (pageLayout === 'docs' || pageLayout === 'wide');
     const sectionLinks = navigation.filter(node => node.tab).map(node => `<a href="${esc(node.route)}"${node === activeTab ? ' aria-current="true"' : ''}>${esc(node.label)}</a>`).join('');
@@ -176,6 +187,6 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
     const menu = side || sectionNavigation ? `<a class="mobile-menu" href="#${side ? 'docs-navigation' : 'docs-sections'}">Menu</a>` : '';
     const rail = toc || panel ? `<aside class="page-rail">${doc.endpoint ? `${panel}${toc}` : `${toc}${panel}`}</aside>` : '';
     const breadcrumbs = (shell.breadcrumbs?.length ?? 0) > 1 && !hero ? `<nav class="doc-breadcrumbs" aria-label="Breadcrumb"><ol>${shell.breadcrumbs.map((item, index) => `<li>${index === shell.breadcrumbs.length - 1 ? `<span aria-current="page">${esc(item.label)}</span>` : item.url ? `<a href="${esc(item.url)}">${esc(item.label)}</a>` : `<span>${esc(item.label)}</span>`}</li>`).join('')}</ol></nav>` : '';
-    const markup = `<!doctype html><html lang="${esc(doc.variant.language)}"${shell.themeCss || shell.paletteCss ? ` data-theme="${esc(shell.preset ?? 'shoal')}" data-palette="${esc(shell.palette ?? '')}"` : ''}${shell.masthead ? ` data-masthead="${esc(shell.masthead)}"` : ''}${layout === 'docs' ? '' : ` data-layout="${layout}"`}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="${shell.mode === 'system' ? 'light dark' : shell.mode ?? 'light'}">${shell.indexing === false || doc.frontmatter.seo?.noindex === true ? '<meta name="robots" content="noindex">' : ''}${shell.origin ? `<link rel="canonical" href="${esc(absolute(doc.route))}">` : ''}${shell.toggle ? '<script src="/assets/mode.js"></script>' : ''}<title>${esc(String(title))}</title>${description ? `<meta name="description" content="${esc(String(description))}">` : ''}${socialDescription ? `<meta property="og:description" content="${esc(socialDescription)}">` : ''}${social}<link rel="alternate" type="text/markdown" href="${esc(markdownUrl)}"><link rel="describedby" href="/llms.min.txt" title="Documentation index">${icons}${shell.preloadFont ? `<link rel="preload" href="/assets/fonts/${esc(shell.preloadFont)}" as="font" type="font/woff2" crossorigin>` : ''}<link rel="stylesheet" href="/assets/site.css">${article.includes('data-theme-preview') ? '<link rel="stylesheet" href="/assets/theme-preview.css">' : ''}${shell.themeCss ? '<link rel="stylesheet" href="/assets/theme.css" data-theme-link="theme">' : ''}${shell.paletteCss ? '<link rel="stylesheet" href="/assets/palette.css" data-theme-link="palette">' : ''}${shell.badgesCss ? '<link rel="stylesheet" href="/assets/badges.css">' : ''}${shell.themeSwitcher ? `<script src="/assets/theme-switcher.js" data-themes="${esc(shell.themeSwitcher)}"></script>` : ''}${shell.fontsCss ? '<link rel="stylesheet" href="/assets/fonts.css">' : ''}${customCss ? '<link rel="stylesheet" href="/assets/project.css">' : ''}</head><body><a class="skip" href="#main">Skip to content</a>${agent.mode === 'disclosure' ? '' : agentBlock}<header class="mast"><div class="mast-inner">${shell.home ? `<a class="${brandClass}" href="/">${brand}</a>` : `<span class="${brandClass}">${brand}</span>`}${editionLabel && (shell.publicationAlternates?.length ?? 0) < 2 ? `<span class="edition">${esc(editionLabel)}</span>` : ''}${menu}${headerTools(shell, doc.variant, esc, readerConfig)}${agent.mode === 'disclosure' ? agentBlock : ''}</div></header>${sectionNavigation}${shortcuts}<div class="layout${layout === 'docs' ? '' : ` layout-${layout}`}${rail ? ' has-rail' : ''}${panel ? ' has-examples' : ''}${doc.endpoint ? ' api-reference' : ''}"><main id="main" class="content" tabindex="-1" data-document-type="${esc(doc.frontmatter.type)}"${readerConfig ? ` data-reader-page="${esc(readerFilterAttribute(doc.readerFilters ?? {}))}"` : ''}>${breadcrumbs}${hero ? '' : `<header class="page-head"><span class="eyebrow">${esc(typeLabel(doc.frontmatter.type))}</span>${doc.endpoint ? '' : badge(doc.frontmatter.subjectLifecycle)}<h1>${esc(doc.frontmatter.title)}${doc.endpoint ? badge(doc.frontmatter.subjectLifecycle) : ''}</h1>${pageHeader && !routeSummary ? `<p class="summary">${esc(pageHeader)}</p>` : ''}${pageDates}${endpoint}${audienceBadges}</header>`}${hero ? '' : `<div class="page-formats"><a class="formats" href="${esc(markdownUrl)}">Read as Markdown</a><button type="button" class="formats" data-copy-markdown hidden>Copy as Markdown</button><span role="status" data-copy-markdown-status></span></div>`}${toc ? '<div class="mobile-outline-slot"></div>' : ''}${jumps}${readerBanner}<article>${article}</article></main>${rail}${side}</div>${footer}${analyticsBootstrap}${readerBootstrap}<script type="module" src="/assets/copy-markdown.js"></script><script type="module" src="/assets/navigation.js"></script><script type="module" src="/assets/reader.js"></script><script type="module" src="/assets/tabs.js"></script>${shell.search ? '<script type="module" src="/assets/search.js"></script>' : ''}${article.includes('data-tooltip') ? '<script type="module" src="/assets/tooltips.js"></script>' : ''}${article.includes('data-component-module') ? '<script type="module" src="/assets/components.js"></script>' : ''}${article.includes('data-file-tree') ? '<script type="module" src="/assets/file-tree.js"></script>' : ''}${article.includes('data-image-expand') ? '<script type="module" src="/assets/image-viewer.js"></script>' : ''}${article.includes('data-table-filter') || article.includes('data-definition-filter') ? '<script type="module" src="/assets/table-filter.js"></script>' : ''}${article.includes('data-walkthrough') ? '<script type="module" src="/assets/walkthrough.js"></script>' : ''}${article.includes('data-cookbook-chooser') ? '<script type="module" src="/assets/cookbook-chooser.js"></script>' : ''}${article.includes('data-theme-preview') ? '<script type="module" src="/assets/theme-preview.js"></script>' : ''}${panel ? '<script type="module" src="/assets/example-panel.js"></script>' : ''}${panel.includes('data-code-samples') ? '<script type="module" src="/assets/code-samples.js"></script>' : ''}</body></html>`;
+    const markup = `<!doctype html><html lang="${esc(doc.variant.language)}"${shell.themeCss || shell.paletteCss ? ` data-theme="${esc(shell.preset ?? 'shoal')}" data-palette="${esc(shell.palette ?? '')}"` : ''}${shell.masthead ? ` data-masthead="${esc(shell.masthead)}"` : ''}${layout === 'docs' ? '' : ` data-layout="${layout}"`}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="${shell.mode === 'system' ? 'light dark' : shell.mode ?? 'light'}">${shell.indexing === false || doc.frontmatter.seo?.noindex === true ? '<meta name="robots" content="noindex">' : ''}${shell.origin ? `<link rel="canonical" href="${esc(absolute(doc.route))}">` : ''}${shell.toggle ? '<script src="/assets/mode.js"></script>' : ''}<title>${esc(String(title))}</title>${description ? `<meta name="description" content="${esc(String(description))}">` : ''}${socialDescription ? `<meta property="og:description" content="${esc(socialDescription)}">` : ''}${social}<link rel="alternate" type="text/markdown" href="${esc(markdownUrl)}"><link rel="describedby" href="/llms.min.txt" title="Documentation index">${icons}${shell.preloadFont ? `<link rel="preload" href="/assets/fonts/${esc(shell.preloadFont)}" as="font" type="font/woff2" crossorigin>` : ''}<link rel="stylesheet" href="/assets/site.css">${article.includes('data-theme-preview') ? '<link rel="stylesheet" href="/assets/theme-preview.css">' : ''}${shell.themeCss ? '<link rel="stylesheet" href="/assets/theme.css" data-theme-link="theme">' : ''}${shell.paletteCss ? '<link rel="stylesheet" href="/assets/palette.css" data-theme-link="palette">' : ''}${shell.badgesCss ? '<link rel="stylesheet" href="/assets/badges.css">' : ''}${shell.themeSwitcher ? `<script src="/assets/theme-switcher.js" data-themes="${esc(shell.themeSwitcher)}"></script>` : ''}${shell.fontsCss ? '<link rel="stylesheet" href="/assets/fonts.css">' : ''}${customCss ? '<link rel="stylesheet" href="/assets/project.css">' : ''}</head><body><a class="skip" href="#main">Skip to content</a>${agent.mode === 'disclosure' ? '' : agentBlock}<header class="mast"><div class="mast-inner">${shell.home ? `<a class="${brandClass}" href="/">${brand}</a>` : `<span class="${brandClass}">${brand}</span>`}${publicationPicker(shell, esc)}${editionLabel && !shell.publicationChoices?.length && (shell.publicationAlternates?.length ?? 0) < 2 ? `<span class="edition">${esc(editionLabel)}</span>` : ''}${menu}${headerTools(shell, doc.variant, esc, readerConfig)}${agent.mode === 'disclosure' ? agentBlock : ''}</div></header>${sectionNavigation}${shortcuts}<div class="layout${layout === 'docs' ? '' : ` layout-${layout}`}${rail ? ' has-rail' : ''}${panel ? ' has-examples' : ''}${doc.endpoint ? ' api-reference' : ''}"><main id="main" class="content" tabindex="-1" data-document-type="${esc(doc.frontmatter.type)}"${readerConfig ? ` data-reader-page="${esc(readerFilterAttribute(doc.readerFilters ?? {}))}"` : ''}>${breadcrumbs}${hero ? '' : `<header class="page-head"><span class="eyebrow">${esc(typeLabel(doc.frontmatter.type))}</span>${doc.endpoint ? '' : badge(doc.frontmatter.subjectLifecycle)}<h1>${esc(doc.frontmatter.title)}${doc.endpoint ? badge(doc.frontmatter.subjectLifecycle) : ''}</h1>${pageHeader && !routeSummary ? `<p class="summary">${esc(pageHeader)}</p>` : ''}${pageDates}${endpoint}${audienceBadges}</header>`}${hero ? '' : `<div class="page-formats"><a class="formats" href="${esc(markdownUrl)}">Read as Markdown</a><button type="button" class="formats" data-copy-markdown hidden>Copy as Markdown</button><span role="status" data-copy-markdown-status></span></div>`}${toc ? '<div class="mobile-outline-slot"></div>' : ''}${jumps}${readerBanner}<article>${article}</article></main>${rail}${side}</div>${footer}${analyticsBootstrap}${readerBootstrap}<script type="module" src="/assets/copy-markdown.js"></script><script type="module" src="/assets/navigation.js"></script><script type="module" src="/assets/reader.js"></script><script type="module" src="/assets/tabs.js"></script>${shell.search ? '<script type="module" src="/assets/search.js"></script>' : ''}${article.includes('data-tooltip') ? '<script type="module" src="/assets/tooltips.js"></script>' : ''}${article.includes('data-component-module') ? '<script type="module" src="/assets/components.js"></script>' : ''}${article.includes('data-file-tree') ? '<script type="module" src="/assets/file-tree.js"></script>' : ''}${article.includes('data-image-expand') ? '<script type="module" src="/assets/image-viewer.js"></script>' : ''}${article.includes('data-table-filter') || article.includes('data-definition-filter') ? '<script type="module" src="/assets/table-filter.js"></script>' : ''}${article.includes('data-walkthrough') ? '<script type="module" src="/assets/walkthrough.js"></script>' : ''}${article.includes('data-cookbook-chooser') ? '<script type="module" src="/assets/cookbook-chooser.js"></script>' : ''}${article.includes('data-theme-preview') ? '<script type="module" src="/assets/theme-preview.js"></script>' : ''}${panel ? '<script type="module" src="/assets/example-panel.js"></script>' : ''}${panel.includes('data-code-samples') ? '<script type="module" src="/assets/code-samples.js"></script>' : ''}</body></html>`;
     return basePath ? markup.replace(/((?:href|src)=")\/(assets\/|llms(?:\.min)?\.txt|apple-touch-icon\.png)/g, `$1${basePath}/$2`).replace('href="/"', `href="${basePath}/"`) : markup;
 }

package/dist/project-navigation.js

@@ -1,6 +1,7 @@
+import { publicationKey } from './publication-identity.js';
 import { createHash } from 'node:crypto';
 import { markdownRoute } from './content-source.js';
-const variantKey = (variant) => `${variant.channel}|${variant.version}|${variant.language}`;
+const variantKey = publicationKey;
 const docKey = (id, variant) => `${id}|${variantKey(variant)}`;
 const tagId = (placeholder, tag) => `${placeholder}-tag-${createHash('sha256').update(tag).digest('hex').slice(0, 8)}`;
 export function validateProjectNavigation(layout, docs, operations, apiIds) {

package/dist/publication-identity.d.ts

@@ -0,0 +1,12 @@
+/** Publication identity shared by compiler, retrieval and delivery runtimes. */
+export type PublicationCoordinate = {
+    product?: string;
+    channel: string;
+    version: string;
+    language: string;
+};
+/** Productless keys deliberately retain the original serialized identity. */
+export declare function publicationKey(value: PublicationCoordinate): string;
+export declare function documentKey(id: string, value: PublicationCoordinate): string;
+export declare function samePublication(left: PublicationCoordinate, right: PublicationCoordinate): boolean;
+export declare function parsePublicationKey(value: string): PublicationCoordinate;

package/dist/publication-identity.js

@@ -0,0 +1,17 @@
+/** Productless keys deliberately retain the original serialized identity. */
+export function publicationKey(value) {
+    return [value.channel, value.version, value.language, ...(value.product === undefined ? [] : [value.product])].join('|');
+}
+export function documentKey(id, value) {
+    return `${id}|${publicationKey(value)}`;
+}
+export function samePublication(left, right) {
+    return left.product === right.product && left.channel === right.channel && left.version === right.version && left.language === right.language;
+}
+export function parsePublicationKey(value) {
+    const parts = value.split('|');
+    if ((parts.length !== 3 && parts.length !== 4) || parts.some(part => !part))
+        throw new Error(`Invalid publication identity ${value}`);
+    const [channel, version, language, product] = parts;
+    return { channel, version, language, ...(product === undefined ? {} : { product }) };
+}

package/dist/publication-manifest.d.ts

@@ -1,3 +1,4 @@
+import type { CompilerPublicationsConfig } from './compiler-config.js';
 import type { ApiEmbedUse } from './api-embeds.js';
 import type { CardUse, validateRelationships } from './cards.js';
 import type { Document, Variant } from './content.js';
@@ -7,7 +8,8 @@ import { type resolveProjectNavigation } from './project-navigation.js';
 import type { ReaderFiltersConfig } from './reader-filters.js';
 import type { Taxonomy } from './taxonomy.js';
 import type { SnippetUse } from './snippets.js';
-export declare function buildPublicationManifest({ fictionalDocuments, configDigest, synonyms, basePath, publicPath, readerFilters, taxonomy, dependencies, rendered, resolvedNavigation, cardUses, snippetUses, apiEmbedUses, focusedContracts, operations, publishedRelationships, redirects, apiSources, siteOrigin, siteIndexing, siteUpdated, diagramAssets, heroImages, faviconRoute, catalog }: {
+export declare function buildPublicationManifest({ configPublications, fictionalDocuments, configDigest, synonyms, basePath, publicPath, readerFilters, taxonomy, dependencies, rendered, resolvedNavigation, cardUses, snippetUses, apiEmbedUses, focusedContracts, operations, publishedRelationships, redirects, apiSources, siteOrigin, siteIndexing, siteUpdated, diagramAssets, heroImages, faviconRoute, catalog }: {
+    configPublications: CompilerPublicationsConfig;
     fictionalDocuments: Set<Document>;
     configDigest: string;
     synonyms: unknown[];
@@ -38,6 +40,7 @@ export declare function buildPublicationManifest({ fictionalDocuments, configDig
     }>;
     apiSources: Array<{
         apiId: string;
+        product?: string;
         channel: string;
         version: string;
         endpoint: string | null;
@@ -98,6 +101,10 @@ export declare function buildPublicationManifest({ fictionalDocuments, configDig
                 url?: string;
             }[];
             verified?: string | undefined;
+            availability?: {
+                since?: string;
+                through?: string;
+            } | undefined;
             updated?: string | undefined;
             indexable: boolean;
             navigationTab: {
@@ -163,6 +170,10 @@ export declare function buildPublicationManifest({ fictionalDocuments, configDig
                 url?: string;
             }[];
             verified?: string | undefined;
+            availability?: {
+                since?: string;
+                through?: string;
+            } | undefined;
             updated?: string | undefined;
             indexable: boolean;
             navigationTab?: undefined;
@@ -181,6 +192,7 @@ export declare function buildPublicationManifest({ fictionalDocuments, configDig
         operations: Record<string, {
             id: string;
             type: string;
+            product?: string;
             channel: string;
             version: string;
             language: string;
@@ -200,6 +212,7 @@ export declare function buildPublicationManifest({ fictionalDocuments, configDig
         }[];
         apiSources: {
             apiId: string;
+            product?: string;
             channel: string;
             version: string;
             endpoint: string | null;
@@ -221,6 +234,16 @@ export declare function buildPublicationManifest({ fictionalDocuments, configDig
         sitemap?: string | undefined;
         basePath: string;
         searchSynonyms?: unknown[] | undefined;
+        publications?: {
+            enabled: Variant[];
+            products: {
+                [k: string]: {
+                    versions: string[];
+                    defaultVersion?: string | undefined;
+                    label?: string | undefined;
+                };
+            };
+        } | undefined;
         schemaVersion: number;
         configDigest: string;
     };