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

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;
     };

package/dist/publication-manifest.js

@@ -1,24 +1,32 @@
+import { documentKey, publicationKey, parsePublicationKey } from './publication-identity.js';
 import { markdownSize } from './markdown-size.js';
 import { createHash } from 'node:crypto';
 import { navigationPath, navigationTab, navigationTabRecord } from './project-navigation.js';
 import { sitemapFiles } from './sitemap.js';
 const digest = (value) => createHash('sha256').update(value).digest('hex');
-const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
-export 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 }) {
+const keyFor = documentKey;
+export 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 }) {
     const indexable = (doc) => siteIndexing && doc.frontmatter.seo?.noindex !== true;
     const updatedFor = (doc) => doc.frontmatter.updated ?? siteUpdated;
     const tabs = [...resolvedNavigation].flatMap(([key, nodes]) => {
-        const [channel, version, language] = key.split('|');
-        return nodes.filter(node => node.tab).map(node => navigationTabRecord(node, { channel, version, language }, basePath));
+        const variant = parsePublicationKey(key);
+        return nodes.filter(node => node.tab).map(node => navigationTabRecord(node, variant, basePath));
     });
     const tabFor = (doc) => {
-        const node = navigationTab(resolvedNavigation.get(`${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`) ?? [], doc.route);
+        const node = navigationTab(resolvedNavigation.get(publicationKey(doc.variant)) ?? [], doc.route);
         return node ? { navigationTab: navigationTabRecord(node, doc.variant, basePath) } : {};
     };
     const sitemaps = siteOrigin && siteIndexing ? sitemapFiles(siteOrigin, rendered.filter(page => indexable(page.doc)).map(page => ({ route: page.doc.route, updated: updatedFor(page.doc) })).concat([{ route: publicPath('/llms.txt'), updated: undefined }]), {}, basePath) : new Map();
+    // Publish one compact catalog, limited to releases present in this edition.
+    const enabled = [...new Map(rendered.map(({ doc }) => [publicationKey(doc.variant), doc.variant])).values()];
+    const products = configPublications.products ? Object.fromEntries(Object.entries(configPublications.products).flatMap(([id, definition]) => {
+        const versions = [...new Set(enabled.filter(variant => variant.product === id).map(variant => variant.version))];
+        return versions.length ? [[id, { ...(definition.label ? { label: definition.label } : {}), ...(versions.includes(definition.defaultVersion) ? { defaultVersion: definition.defaultVersion } : {}), versions }]] : [];
+    })) : undefined;
     const manifest = {
         schemaVersion: 1,
         configDigest: configDigest,
+        ...(products ? { publications: { enabled, products } } : {}),
         ...(synonyms.length ? { searchSynonyms: synonyms } : {}),
         basePath,
         ...(sitemaps.size ? { sitemap: publicPath('/sitemap.xml') } : {}),
@@ -26,7 +34,7 @@ export function buildPublicationManifest({ fictionalDocuments, configDigest, syn
         ...(taxonomy ? { taxonomy } : {}),
         dependencies,
         ...(tabs.length ? { navigationTabs: tabs } : {}),
-        documents: rendered.map(({ doc, markdown, sections }) => ({ id: doc.frontmatter.id, demo: fictionalDocuments.has(doc), type: doc.frontmatter.type, title: doc.frontmatter.title, summary: doc.frontmatter.summary, subjectLifecycle: doc.frontmatter.subjectLifecycle ?? null, ...(doc.change ? { change: doc.change } : {}), ...(doc.subjectDeprecation ? { subjectDeprecation: doc.subjectDeprecation } : {}), variant: doc.variant, url: doc.route, markdownUrl: doc.markdownRoute, ...tabFor(doc), indexable: indexable(doc), ...(updatedFor(doc) ? { updated: updatedFor(doc) } : {}), ...(doc.frontmatter.verified ? { verified: doc.frontmatter.verified } : {}), contentDigest: doc.contentDigest, breadcrumbs: navigationPath(resolvedNavigation.get(`${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`) ?? [], doc.route), ...(doc.frontmatter.product !== undefined ? { product: doc.frontmatter.product } : {}), ...(doc.frontmatter.area !== undefined ? { area: doc.frontmatter.area } : {}), ...(doc.frontmatter.subarea !== undefined ? { subarea: doc.frontmatter.subarea } : {}), ...(readerFilters ? { readerFilters: doc.readerFilters ?? {} } : {}), cardTargets: cardUses.get(doc)?.targets ?? [], cardQueries: cardUses.get(doc)?.queries ?? [], snippets: [...new Set(snippetUses.filter(use => use.documentId === doc.frontmatter.id).map(use => use.id))], apiEmbeds: apiEmbedUses.filter(use => use.documentKey === keyFor(doc.frontmatter.id, doc.variant)).map(({ sourceFile, documentKey, ...request }) => request), focusedContractUrl: doc.focusedContractUrl ?? null, focusedContractBytes: doc.focusedContractUrl ? focusedContracts.get(doc.focusedContractUrl)?.bytes : null, focusedContractDigest: doc.focusedContractUrl ? focusedContracts.get(doc.focusedContractUrl)?.digest : null, sections: (sections ?? []).map(({ content, ...record }) => record), ...markdownSize(markdown), digest: digest(markdown) })),
+        documents: rendered.map(({ doc, markdown, sections }) => ({ id: doc.frontmatter.id, demo: fictionalDocuments.has(doc), type: doc.frontmatter.type, title: doc.frontmatter.title, summary: doc.frontmatter.summary, subjectLifecycle: doc.frontmatter.subjectLifecycle ?? null, ...(doc.change ? { change: doc.change } : {}), ...(doc.subjectDeprecation ? { subjectDeprecation: doc.subjectDeprecation } : {}), variant: doc.variant, url: doc.route, markdownUrl: doc.markdownRoute, ...tabFor(doc), indexable: indexable(doc), ...(updatedFor(doc) ? { updated: updatedFor(doc) } : {}), ...(doc.frontmatter.availability ? { availability: doc.frontmatter.availability } : {}), ...(doc.frontmatter.verified ? { verified: doc.frontmatter.verified } : {}), contentDigest: doc.contentDigest, breadcrumbs: navigationPath(resolvedNavigation.get(publicationKey(doc.variant)) ?? [], doc.route), ...(doc.frontmatter.product !== undefined ? { product: doc.frontmatter.product } : {}), ...(doc.frontmatter.area !== undefined ? { area: doc.frontmatter.area } : {}), ...(doc.frontmatter.subarea !== undefined ? { subarea: doc.frontmatter.subarea } : {}), ...(readerFilters ? { readerFilters: doc.readerFilters ?? {} } : {}), cardTargets: cardUses.get(doc)?.targets ?? [], cardQueries: cardUses.get(doc)?.queries ?? [], snippets: [...new Set(snippetUses.filter(use => use.documentId === doc.frontmatter.id).map(use => use.id))], apiEmbeds: apiEmbedUses.filter(use => use.documentKey === keyFor(doc.frontmatter.id, doc.variant)).map(({ sourceFile, documentKey, ...request }) => request), focusedContractUrl: doc.focusedContractUrl ?? null, focusedContractBytes: doc.focusedContractUrl ? focusedContracts.get(doc.focusedContractUrl)?.bytes : null, focusedContractDigest: doc.focusedContractUrl ? focusedContracts.get(doc.focusedContractUrl)?.digest : null, sections: (sections ?? []).map(({ content, ...record }) => record), ...markdownSize(markdown), digest: digest(markdown) })),
         operations,
         relationships: publishedRelationships,
         redirects,

package/dist/publication-plan.js

@@ -1,3 +1,4 @@
+import { documentKey, samePublication } from './publication-identity.js';
 import { hasScaffoldPlaceholders } from './scaffold-placeholders.js';
 import { validateFeatureClassification, matchesFeatures } from './deployment-profile.js';
 import { matchesContentFilter } from './content-filter.js';
@@ -7,8 +8,8 @@ import { markdownRoute, readDocument, routeFor } from './content.js';
 import { applyFormattingLocale, validateFrontmatter } from './frontmatter.js';
 import { mergeProvidedMetadata } from './metadata-provider.js';
 import { pageReaderFilters } from './reader-filters.js';
-import { configField } from './compiler-config.js';
-const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+import { resolvePublication, configField } from './compiler-config.js';
+const keyFor = documentKey;
 async function files(dir) {
     const entries = await readdir(dir, { withFileTypes: true });
     const nested = await Promise.all(entries.map(async (entry) => entry.isDirectory() ? files(path.join(dir, entry.name)) : /\.mdx?$/.test(entry.name) ? [path.join(dir, entry.name)] : []));
@@ -38,27 +39,38 @@ export async function planAuthoredDocuments({ base, basePath, config, variants,
             return merged.page;
         } : undefined, sourceOverrides?.get(file));
         frontmatter.language ??= language;
+        // A product's release default never comes from the legacy global version.
+        if (config.publications.products && frontmatter.product && !frontmatter.publications) {
+            if (!Object.hasOwn(config.publications.products, frontmatter.product))
+                throw new Error(`${file}: unknown publication product ${frontmatter.product}`);
+            const enforcedVersion = configField(configField(config.frontmatter, 'enforced'), 'version');
+            if (sourceFrontmatter.version === undefined && enforcedVersion === undefined)
+                frontmatter.version = resolvePublication(config.publications, { ...frontmatter, version: undefined }, language).version;
+            resolvePublication(config.publications, frontmatter, language);
+        }
         applyFormattingLocale(frontmatter, config.frontmatter, sourceFrontmatter);
         validateFrontmatter(frontmatter, config.frontmatter, file, sourceFrontmatter);
         const pagePublications = frontmatter.publications;
         if (pagePublications) {
-            if (sourceFrontmatter.channel !== undefined || sourceFrontmatter.version !== undefined)
+            if (sourceFrontmatter.channel !== undefined || sourceFrontmatter.version !== undefined || (config.publications.products && sourceFrontmatter.product !== undefined))
                 throw new Error(`${file}: use publications instead of page-level channel or version`);
             for (const publication of pagePublications) {
-                if (!config.publications.channels[publication.channel] || !config.publications.versions[publication.version])
-                    throw new Error(`${file}: unknown publication ${publication.channel}/${publication.version}`);
+                resolvePublication(config.publications, publication, language);
                 const enforced = configField(config.frontmatter, 'enforced');
-                if (configField(enforced, 'channel') && configField(enforced, 'channel') !== publication.channel || configField(enforced, 'version') && configField(enforced, 'version') !== publication.version)
+                if (configField(enforced, 'channel') && configField(enforced, 'channel') !== publication.channel || configField(enforced, 'version') && configField(enforced, 'version') !== publication.version || config.publications.products && configField(enforced, 'product') && configField(enforced, 'product') !== publication.product)
                     throw new Error(`${file}: publications conflicts with enforced channel or version`);
             }
         }
         knownDocumentIds.add(frontmatter.id);
+        const previousType = knownDocumentTypes.get(frontmatter.id);
+        if (previousType !== undefined && previousType !== frontmatter.type)
+            throw new Error(`${file}: stable document ID ${frontmatter.id} has inconsistent types across publications (${previousType} and ${frontmatter.type})`);
         knownDocumentTypes.set(frontmatter.id, frontmatter.type);
         if (frontmatter.type === 'api-reference')
             for (const operation of frontmatter.operations ?? [])
                 authoredOperationIds.add(operation);
         const classificationVariants = featureContext?.classificationPublications ?? variants;
-        const classificationEligible = frontmatter.access?.policy === 'public' && classificationVariants.some(variant => (pagePublications ? pagePublications.some(item => item.channel === variant.channel && item.version === variant.version) : frontmatter.channel === variant.channel && frontmatter.version === variant.version) && frontmatter.language === variant.language);
+        const classificationEligible = frontmatter.access?.policy === 'public' && classificationVariants.some(variant => (pagePublications ? pagePublications.some(item => samePublication({ ...item, language: frontmatter.language }, variant)) : samePublication({ channel: frontmatter.channel, version: frontmatter.version, language: frontmatter.language, ...(config.publications.products && frontmatter.product ? { product: frontmatter.product } : {}) }, variant)) && frontmatter.language === variant.language);
         if (classificationEligible)
             validateFeatureClassification(sourceFrontmatter, featureContext, `${file}: ${frontmatter.id}`);
         const included = matchesFeatures(frontmatter.requires, featureContext, `${file}: ${frontmatter.id}`);
@@ -80,13 +92,13 @@ export async function planAuthoredDocuments({ base, basePath, config, variants,
             throw new Error(`${file}: unresolved scaffold placeholders cannot be published`);
         let selectedPublication = false;
         for (const variant of variants) {
-            if (pagePublications ? !pagePublications.some(item => item.channel === variant.channel && item.version === variant.version) : (frontmatter.channel && frontmatter.channel !== variant.channel || frontmatter.version && frontmatter.version !== variant.version))
+            if (pagePublications ? !pagePublications.some(item => samePublication({ ...item, language: frontmatter.language }, variant)) : (frontmatter.channel && frontmatter.channel !== variant.channel || frontmatter.version && frontmatter.version !== variant.version || (config.publications.products && frontmatter.product !== variant.product)))
                 continue;
             if (frontmatter.language && frontmatter.language !== variant.language)
                 continue;
             if (!pagePublications && (!frontmatter.channel || !frontmatter.version || !frontmatter.language))
                 throw new Error(`${file}: resolved frontmatter needs publication channel and version`);
-            const publishedFrontmatter = pagePublications ? { ...frontmatter, channel: variant.channel, version: variant.version } : frontmatter;
+            const publishedFrontmatter = pagePublications ? { ...frontmatter, channel: variant.channel, version: variant.version, ...(variant.product ? { product: variant.product } : {}) } : frontmatter;
             const key = keyFor(frontmatter.id, variant);
             if (docs.has(key))
                 throw new Error(`Duplicate document identity ${key}`);