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

package/assets/ask-widget.js

@@ -114,14 +114,28 @@
       if (current?.item && (indent > current.indent || code && current.item.textContent.replace(/\[\d+\]/g, '').trim().endsWith(':'))) current.item.append(node);
       else { lists.length = 0; parent.append(node); }
     };
-    for (const part of text.split(/((?:^[ \t]*)?```[\s\S]*?```)/m)) {
-      if (!part.trim()) continue;
-      if (part.trimStart().startsWith('```')) {
-        const indent = indentOf(part);
-        let code = part.replace(/^[ \t]*```[^\n]*\n?/, '').replace(/\n?[ \t]*```$/, '');
-        if (indent) code = code.replace(new RegExp('^ {0,' + indent + '}', 'gm'), '');
+    // A shorter fence inside an example is literal code, not its closing fence.
+    const parts = [];
+    const openings = /^([ \t]*)(`{3,}|~{3,})[^\n]*\n/gm;
+    let cursor = 0, opening;
+    while ((opening = openings.exec(text))) {
+      const closing = new RegExp('^[ \\t]*' + opening[2][0] + '{' + opening[2].length + ',}[ \\t]*\\r?$', 'gm');
+      closing.lastIndex = openings.lastIndex;
+      const end = closing.exec(text);
+      parts.push({ text: text.slice(cursor, opening.index) });
+      parts.push({ code: text.slice(openings.lastIndex, end ? end.index : text.length).replace(/\r?\n$/, ''), indent: indentOf(opening[1]) });
+      cursor = end ? closing.lastIndex : text.length;
+      openings.lastIndex = cursor;
+    }
+    parts.push({ text: text.slice(cursor) });
+    for (const blockPart of parts) {
+      if (blockPart.code !== undefined) {
+        const { indent } = blockPart;
+        const code = indent ? blockPart.code.replace(new RegExp('^ {0,' + indent + '}', 'gm'), '') : blockPart.code;
         appendBlock(el('pre', {}, el('code', { text: code })), indent, true); continue;
       }
+      const part = blockPart.text;
+      if (!part.trim()) continue;
       for (const block of part.split(/\n{2,}/)) {
         const heading = /^(#{1,6})\s+(.+)$/.exec(block.trim());
         if (heading && !block.trim().includes('\n')) { const node = el(`h${Math.max(2, heading[1].length)}`); inline(node, heading[2], sources); appendBlock(node, indentOf(block)); continue; }

package/assets/navigation.js

@@ -1,4 +1,9 @@
 const navigation = document.querySelector('.side');
+for (const select of document.querySelectorAll('[data-publication-switcher]')) {
+  select.addEventListener('change', () => {
+    if (select.value) location.assign(select.value);
+  });
+}
 const tree = navigation?.querySelector('.nav-tree');
 const search = navigation?.querySelector('.nav-search');
 const filter = navigation?.querySelector('#nav-filter');

package/dist/api-materialize.d.ts

@@ -1,4 +1,5 @@
-export type MaterializeOptions = {
+import type { Variant } from './content.js';
+export type MaterializeOptions = Partial<Variant> & {
     all?: boolean;
     operations?: string[];
     routes?: string[];

package/dist/api-materialize.js

@@ -1,3 +1,5 @@
+import { resolvePublication } from './compiler-config.js';
+import { samePublication } from './publication-identity.js';
 import { mkdir, readFile, readdir, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import YAML from 'yaml';
@@ -30,7 +32,7 @@ function pageIdentity(source, file) {
     const data = YAML.parse(match[1]);
     if (!data || typeof data !== 'object')
         throw new Error(`${file}: invalid page frontmatter`);
-    return { id: data.id, operation: Array.isArray(data.operations) && data.operations.length === 1 ? data.operations[0] : undefined, channel: data.channel, version: data.version, language: data.language, publications: data.publications };
+    return { id: data.id, operation: Array.isArray(data.operations) && data.operations.length === 1 ? data.operations[0] : undefined, product: data.product, channel: data.channel, version: data.version, language: data.language, publications: data.publications };
 }
 function select(candidates, options) {
     const ids = options.operations ?? [];
@@ -63,16 +65,14 @@ export async function materializeApiPages(configFile, apiId, options) {
     const config = loaded.value;
     const root = path.dirname(path.resolve(configFile));
     const contentDir = await canonical(path.resolve(root, config.site?.contentDir ?? 'content'));
-    const directory = await canonical(options.output ? path.resolve(options.output) : path.join(contentDir, 'api', apiId));
+    const { candidates, publication } = await apiCandidates(configFile, apiId, options);
+    const defaultDirectory = publication.product ? path.join(contentDir, 'api', publication.product, publication.version, apiId) : path.join(contentDir, 'api', apiId);
+    const directory = await canonical(options.output ? path.resolve(options.output) : defaultDirectory);
     const relative = path.relative(contentDir, directory);
     if (relative.startsWith('..') || path.isAbsolute(relative))
         throw new Error(`MDX output must stay inside the content directory ${contentDir}`);
-    const { candidates } = await apiCandidates(configFile, apiId);
     const selected = select(candidates, options);
-    const defaults = config.publications?.defaults;
-    if (!defaults?.channel || !defaults?.version)
-        throw new Error('API page materialization needs publication defaults');
-    const language = defaults.language ?? defaultLanguage(config);
+    const language = publication.language;
     const existing = new Map();
     for (const file of await pageFiles(contentDir)) {
         const identity = pageIdentity(await readFile(file, 'utf8'), file);
@@ -86,7 +86,19 @@ export async function materializeApiPages(configFile, apiId, options) {
     const skipped = [];
     const targets = new Set();
     for (const item of selected) {
-        const matches = (existing.get(item.reference) ?? []).filter(page => (page.publications ? page.publications.some(publication => publication.channel === defaults.channel && publication.version === defaults.version) : (page.channel ?? defaults.channel) === defaults.channel && (page.version ?? defaults.version) === defaults.version) && (page.language ?? language) === language);
+        const matches = (existing.get(item.reference) ?? []).filter(page => {
+            const sourceLanguage = config.frontmatter?.enforced?.language ?? page.language ?? config.frontmatter?.defaults?.language ?? defaultLanguage(config);
+            if (page.publications)
+                return page.publications.some(member => member.product === publication.product && member.channel === publication.channel && member.version === publication.version) && sourceLanguage === language;
+            const product = config.publications.products ? config.frontmatter?.enforced?.product ?? page.product ?? config.frontmatter?.defaults?.product : undefined;
+            const coordinate = resolvePublication(config.publications, {
+                ...(product ? { product } : {}),
+                channel: config.frontmatter?.enforced?.channel ?? page.channel ?? config.frontmatter?.defaults?.channel ?? config.publications?.defaults?.channel,
+                version: config.frontmatter?.enforced?.version ?? page.version ?? (product ? undefined : config.frontmatter?.defaults?.version ?? config.publications?.defaults?.version),
+                language: sourceLanguage
+            }, defaultLanguage(config));
+            return samePublication(coordinate, publication);
+        });
         if (matches.length > 1)
             throw new Error(`Duplicate page ID ${item.reference} in the default publication: ${matches.map(page => page.file).join(', ')}`);
         const prior = matches[0];
@@ -108,7 +120,7 @@ export async function materializeApiPages(configFile, apiId, options) {
         if (atFile !== undefined)
             throw new Error(`${file}: target exists with another page ID; no files written`);
         const summary = item.method === 'WEBHOOK' ? `Webhook event: ${item.route}` : `${item.method} ${item.route}`;
-        const header = YAML.stringify({ id: item.reference, title: item.title, summary, type: 'api-reference', slug: item.slug, channel: defaults.channel, version: defaults.version, language, operations: [item.id], access: { policy: 'draft' } });
+        const header = YAML.stringify({ id: item.reference, title: item.title, summary, type: 'api-reference', slug: item.slug, ...publication, operations: [item.id], access: { policy: 'draft' } });
         const body = 'This draft reference is based on its linked OpenAPI operation.\n\n[[TODO: Explain when to use this endpoint, its prerequisites, and any behavior the OpenAPI contract cannot express. Verify every claim before publishing.]]\n';
         pending.push({ item, file, content: `---\n${header}---\n\n${body}` });
     }

package/dist/api-publication-plan.d.ts

@@ -10,7 +10,9 @@ type ApiDefinition = {
         path: string;
         [key: string]: unknown;
     };
+    product?: string;
     publications?: Array<{
+        product?: string;
         channel: string;
         version: string;
         source: {

package/dist/api-publication-plan.js

@@ -1,3 +1,4 @@
+import { documentKey } from './publication-identity.js';
 import { matchesFeatures, validateFeatureClassification } from './deployment-profile.js';
 import { matchesContentFilter } from './content-filter.js';
 import path from 'node:path';
@@ -10,7 +11,7 @@ import { explain } from './config.js';
 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 keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+const keyFor = documentKey;
 function validatedApiDefinitions(value) {
     if (value === undefined)
         return {};
@@ -24,7 +25,7 @@ function validatedApiDefinitions(value) {
         if (source !== undefined && (!isConfigMapping(source) || typeof source.kind !== 'string' || typeof source.path !== 'string'))
             throw new Error(`apis.${id}.source needs kind and path`);
         const publications = raw.publications;
-        if (publications !== undefined && (!Array.isArray(publications) || publications.some(item => !isConfigMapping(item) || typeof item.channel !== 'string' || typeof item.version !== 'string' || !isConfigMapping(item.source) || typeof item.source.kind !== 'string' || typeof item.source.path !== 'string' || (item.discovery !== undefined && (!isConfigMapping(item.discovery) || (item.discovery.endpoint !== undefined && typeof item.discovery.endpoint !== 'string'))))))
+        if (publications !== undefined && (!Array.isArray(publications) || publications.some(item => !isConfigMapping(item) || (item.product !== undefined && typeof item.product !== 'string') || typeof item.channel !== 'string' || typeof item.version !== 'string' || !isConfigMapping(item.source) || typeof item.source.kind !== 'string' || typeof item.source.path !== 'string' || (item.discovery !== undefined && (!isConfigMapping(item.discovery) || (item.discovery.endpoint !== undefined && typeof item.discovery.endpoint !== 'string'))))))
             throw new Error(`apis.${id}.publications needs entries with channel, version, and a local source`);
         const operations = raw.operations;
         if (operations !== undefined && (!Array.isArray(operations) || operations.some(item => !isConfigMapping(item) || typeof item.id !== 'string' || typeof item.reference !== 'string' || (item.sourceOperationId !== undefined && typeof item.sourceOperationId !== 'string'))))
@@ -39,6 +40,18 @@ function validatedApiDefinitions(value) {
 export async function materializeApiReferences({ config, loaded, variants, docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, basePath, readerFilters, contentFilter, allowRouteCollisions }) {
     const definitions = validatedApiDefinitions(config.apis);
     for (const [id, definition] of Object.entries(definitions)) {
+        if (config.publications.products && definition.product !== undefined && (typeof definition.product !== 'string' || !config.publications.products || !Object.hasOwn(config.publications.products, definition.product)))
+            throw new Error(`API ${id}: unknown product ${definition.product}`);
+        const seenPublications = new Set();
+        for (const publication of definition.publications ?? []) {
+            const catalog = publication.product === undefined ? config.publications.versions : config.publications.products?.[publication.product]?.versions;
+            if (!catalog || !Object.hasOwn(catalog, publication.version) || !Object.hasOwn(config.publications.channels, publication.channel))
+                throw new Error(`API ${id}: unknown product publication`);
+            const key = JSON.stringify([publication.product, publication.channel, publication.version]);
+            if (seenPublications.has(key))
+                throw new Error(`API ${id}: duplicate publication source`);
+            seenPublications.add(key);
+        }
         validateFeatureClassification(definition, loaded.deployment ? { ...loaded.deployment.context, requireClassification: false } : undefined, `API ${id}`);
         for (const operation of definition.operations ?? [])
             validateFeatureClassification(operation, loaded.deployment ? { ...loaded.deployment.context, requireClassification: false } : undefined, `Operation ${operation.id}`);
@@ -62,10 +75,13 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
     }
     const sourceForVariant = (apiId, definition, variant) => {
         const defaults = config.publications.defaults;
-        if (definition.source !== undefined && (!defaults?.channel || !defaults?.version))
+        if (definition.source !== undefined && (!defaults?.channel || (!defaults?.version && !((definition.product ?? defaults?.product) && config.publications.products?.[definition.product ?? defaults.product]?.defaultVersion))))
             throw new Error(`apis.${apiId}.source needs publications.defaults with channel and version to choose its publication`);
-        const isDefault = variant.channel === defaults?.channel && variant.version === defaults?.version;
-        const publicationIndex = definition.publications?.findIndex(item => item.channel === variant.channel && item.version === variant.version) ?? -1;
+        const product = config.publications.products ? definition.product ?? defaults?.product : undefined;
+        const scopedVersion = product && defaults?.product === product && defaults.version && Object.hasOwn(config.publications.products[product].versions, defaults.version) ? defaults.version : undefined;
+        const defaultVersion = product ? scopedVersion ?? config.publications.products?.[product]?.defaultVersion : defaults?.version;
+        const isDefault = variant.product === product && variant.channel === defaults?.channel && variant.version === defaultVersion;
+        const publicationIndex = definition.publications?.findIndex(item => item.product === variant.product && item.channel === variant.channel && item.version === variant.version) ?? -1;
         const source = publicationIndex >= 0 ? definition.publications?.[publicationIndex].source : (isDefault ? definition.source : undefined);
         if (!source)
             return undefined;
@@ -166,7 +182,7 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
                             const classification = requirements !== undefined || shared !== undefined ? { requires: requirements, shared } : definition;
                             validateFeatureClassification(classification, loaded.deployment?.context, `${binding.file}: ${sourceOperationId} (generated reference)`);
                         }
-                        if (!variants.some(item => item.channel === variant.channel && item.version === variant.version && item.language === variant.language))
+                        if (!variants.some(item => item.product === variant.product && item.channel === variant.channel && item.version === variant.version && item.language === variant.language))
                             continue;
                         operationRequirements.set(keyFor(id, variant), requirements);
                         const featureSelected = matchesFeatures(requirements, loaded.deployment?.context, `${binding.file}: ${sourceOperationId}`) && matchesFeatures(definition.requires, loaded.deployment?.context, `API ${apiId}`);
@@ -183,7 +199,7 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
                         knownDocumentTypes.set(reference, page.type);
                         if (!matchesFeatures(page.requires, loaded.deployment?.context, `${binding.file}: ${reference}`))
                             continue;
-                        if (page.access?.policy !== 'public' || page.channel !== variant.channel || page.version !== variant.version || page.language !== variant.language)
+                        if (page.access?.policy !== 'public' || page.channel !== variant.channel || page.version !== variant.version || page.language !== variant.language || (config.publications.products && page.product !== variant.product))
                             continue;
                         const key = keyFor(reference, variant);
                         const authored = docs.get(key);

package/dist/api-publication-review.js

@@ -1,9 +1,10 @@
+import { documentKey, publicationKey } from './publication-identity.js';
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { isConfigMapping } from './compiler-config.js';
 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 reviewApiPublication(configFile, apiPlan, rendered, apiEmbedUses, focusedContracts, apiSources, sourceForOperation, mode) {
     const { api, knownOperations, sourceForVariant } = apiPlan;
     // Pin the source bytes and the API selections exposed by public pages. Authored
@@ -19,7 +20,7 @@ export async function reviewApiPublication(configFile, apiPlan, rendered, apiEmb
             continue;
         const bindings = new Map();
         for (const { doc } of pages) {
-            const key = `${doc.variant.channel}|${doc.variant.version}`;
+            const key = doc.variant.product ? publicationKey(doc.variant) : `${doc.variant.channel}|${doc.variant.version}`;
             if (!bindings.has(key))
                 bindings.set(key, sourceForVariant(apiId, definition, doc.variant));
         }
@@ -35,7 +36,7 @@ export async function reviewApiPublication(configFile, apiPlan, rendered, apiEmb
         }
         const reviewedPages = pages.map(({ doc }) => ({ id: doc.frontmatter.id, url: doc.route, markdownUrl: doc.markdownRoute }));
         const references = pages.filter(({ doc }) => doc.frontmatter.type === 'api-reference').flatMap(({ doc }) => (doc.frontmatter.operations ?? []).filter(id => knownOperations.get(id)?.apiId === apiId).map(id => ({
-            channel: doc.variant.channel, version: doc.variant.version, language: doc.variant.language,
+            ...(doc.variant.product ? { product: doc.variant.product } : {}), channel: doc.variant.channel, version: doc.variant.version, language: doc.variant.language,
             operation: sourceForOperation(id, doc.variant).sourceOperationId
         }))).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
         const embeds = apiEmbedUses.filter(use => use.api === apiId || (use.operation && knownOperations.get(use.operation)?.apiId === apiId))

package/dist/api-selection.d.ts

@@ -1,3 +1,4 @@
+import type { Variant } from './content.js';
 export type ApiCandidate = {
     operationId: string;
     method: string;
@@ -9,12 +10,14 @@ export type ApiCandidate = {
     slug: string;
     filename: string;
 };
-export declare function apiCandidates(configFile: string, apiId: string): Promise<{
+export declare function apiCandidates(configFile: string, apiId: string, selection?: Partial<Variant>): Promise<{
     candidates: ApiCandidate[];
     selected: Set<string>;
     pathPrefix: string;
+    publication: Variant;
+    sourceFile: string;
 }>;
-export declare function selectApiReferences(configFile: string, apiId: string, outputFile: string): Promise<{
+export declare function selectApiReferences(configFile: string, apiId: string, outputFile: string, publication?: Partial<Variant>): Promise<{
     selected: string[];
     total: number;
     file: string;

package/dist/api-selection.js

@@ -1,3 +1,6 @@
+import { resolvePublication } from './compiler-config.js';
+import { defaultLanguage } from './frontmatter.js';
+import { samePublication } from './publication-identity.js';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
@@ -5,23 +8,27 @@ import YAML from 'yaml';
 import { ApiReader } from './api.js';
 import { generatedOperationIdentity } from './api-identity.js';
 import { explain, loadConfig } from './config.js';
-export async function apiCandidates(configFile, apiId) {
+export async function apiCandidates(configFile, apiId, selection = {}) {
     const loaded = await loadConfig(configFile);
     const config = loaded.value;
     const definition = config.apis?.[apiId];
     if (!definition)
         throw new Error(`Unknown API ${apiId}`);
-    const defaults = config.publications?.defaults;
-    if (!defaults?.channel || !defaults?.version)
-        throw new Error('API selection needs publication defaults');
-    const publicationIndex = definition.publications?.findIndex((item) => item.channel === defaults.channel && item.version === defaults.version) ?? -1;
-    const source = publicationIndex >= 0 ? definition.publications[publicationIndex].source : definition.source;
+    const defaults = config.publications?.defaults ?? {};
+    const product = config.publications.products ? selection.product ?? definition.product ?? defaults.product : undefined;
+    const publication = resolvePublication(config.publications, { ...defaults, ...selection, ...(product ? { product, version: selection.version } : {}) }, defaultLanguage(config));
+    if (!config.publications.enabled?.some((item) => samePublication(resolvePublication(config.publications, item, defaultLanguage(config)), publication)))
+        throw new Error('API selection publication is not enabled; select an explicit product and release');
+    const publicationIndex = definition.publications?.findIndex((item) => item.product === publication.product && item.channel === publication.channel && item.version === publication.version) ?? -1;
+    const sourceDefault = definition.source ? resolvePublication(config.publications, { ...defaults, ...(config.publications.products && definition.product ? { product: definition.product, version: undefined } : {}) }, defaultLanguage(config)) : undefined;
+    const source = publicationIndex >= 0 ? definition.publications[publicationIndex].source : sourceDefault && publication.product === sourceDefault.product && publication.channel === sourceDefault.channel && publication.version === sourceDefault.version ? definition.source : undefined;
     if (source?.kind !== 'file')
-        throw new Error(`API ${apiId} needs a local file source in the default publication`);
+        throw new Error(`API ${apiId} needs a local file source in the selected publication`);
     const sourceKey = publicationIndex >= 0 ? `apis.${apiId}.publications.${publicationIndex}.source.path` : `apis.${apiId}.source.path`;
     const origin = explain(loaded, sourceKey).source.file;
     const reader = new ApiReader();
-    const loadedSpec = await reader.load(path.resolve(path.dirname(origin), source.path));
+    const sourceFile = path.resolve(path.dirname(origin), source.path);
+    const loadedSpec = await reader.load(sourceFile);
     const spec = loadedSpec.value;
     const explicit = new Map((definition.operations ?? []).map((entry) => [entry.sourceOperationId, entry]));
     const generate = definition.generateReferences;
@@ -47,10 +54,10 @@ export async function apiCandidates(configFile, apiId) {
             }
         }
     const selected = new Set(generate && generate !== true && Array.isArray(generate.include) ? generate.include : generate && generate !== true && Array.isArray(generate.exclude) ? candidates.filter(item => !generate.exclude.includes(item.operationId)).map(item => item.operationId) : generate ? candidates.map(item => item.operationId) : []);
-    return { candidates, selected, pathPrefix };
+    return { candidates, selected, pathPrefix, publication, sourceFile };
 }
-export async function selectApiReferences(configFile, apiId, outputFile) {
-    const { candidates, selected: current, pathPrefix } = await apiCandidates(configFile, apiId);
+export async function selectApiReferences(configFile, apiId, outputFile, publication = {}) {
+    const { candidates, selected: current, pathPrefix } = await apiCandidates(configFile, apiId, publication);
     const chosen = [];
     const reader = createInterface({ input: process.stdin, output: process.stdout });
     const answers = reader[Symbol.asyncIterator]();

package/dist/artifact-bundle.js

@@ -16,6 +16,7 @@ import { defaultShareSvg, faviconSvg, fillShareTemplate, renderPng, touchIconSvg
 import { paletteCatalog, paletteCss, presetCatalog, resolvePalette } from './palettes.js';
 import { heading, link, list, paragraph, renderMarkdown, root, searchIndex, shareCardText, text } from './content.js';
 import { outputUrl } from './representation-tree.js';
+const publicationLabel = (value) => [...(value.product === undefined ? [] : [value.product]), value.channel, value.version, value.language].join('/');
 export async function assembleArtifacts(input) {
     const { base, basePath, publicPath, canonical, siteOrigin, manifest, provenanceRecord, rendered, sitemaps, diagramAssets, heroImages, focusedContracts, styleFiles, themeStyleFile, generatedPaletteCss, generatedBadgeCss, search, synonyms, config, builtInSearchProvider, customReaderModule, analyticsModule, mcpAnalyticsModule, previewFiles, assetDirectory, themeSwitcher, themeDirectory, palette, colorMode, generatedFontsCss, fontFiles, fonts, shareImages, shareFor, themePreset, shareFontFiles, shareCache, faviconFile, faviconRoute, customStyleFile, scriptFiles, componentAssets, redirects, apiPublications, api, catalog, headers, documentRoutes, readerFilters, apiSources } = input;
     const artifacts = new Map();
@@ -198,7 +199,7 @@ export async function assembleArtifacts(input) {
     const discoveryEntry = ({ doc }, includeType = false) => ({ title: `${fictionalDocument(doc, llms) ? 'Fictional example: ' : ''}${doc.frontmatter.title}`, url: doc.markdownRoute, summary: `${includeType ? `${doc.frontmatter.type} — ` : ''}${fictionalDocument(doc, llms) ? 'Demonstration only; not a live API. ' : ''}${doc.frontmatter.summary}` });
     const tabs = manifest.navigationTabs ?? [];
     const tabLinks = tabs.length ? '\n\n## Navigation sections\n\n' + discoveryLinks(tabs.map(tab => ({
-        title: `${tab.label} (${tab.variant.channel}/${tab.variant.version}/${tab.variant.language})`, url: tab.indexUrl,
+        title: `${tab.label} (${publicationLabel(tab.variant)})`, url: tab.indexUrl,
         summary: `Section ID: ${tab.id}. Scoped page index.`
     }))) : '';
     const groups = new Map();
@@ -237,7 +238,7 @@ export async function assembleArtifacts(input) {
         }))])).trimEnd();
     const discovery = [renderMarkdown(root([heading(1, String(config.site.title))])).trimEnd(), '', '> Documentation and API contracts published by this site.', ...(readerFilters ? ['', 'Reader views affect the interactive HTML only. This index lists every published page, and each Markdown page includes all reader-marked sections with readable labels. The document manifest records configured reader facets and each page’s marks.'] : []), ...(llms.fictionalPrefixes.length ? ['', 'Entries labeled Fictional example demonstrate documentation features. Their operations and API contracts do not describe a live service.'] : []), '', '## Discovery', '', discoveryLinks([{ title: 'Compact documentation index', url: publicPath('/llms.min.txt'), summary: 'Start here: full-page Markdown links and author-declared standalone section links with sizes and full-page fallbacks. No tools or JSON processing required.' }, ...(search.index ? [{ title: 'Compact heading index', url: publicPath('/search-index.min.json'), summary: 'Page summaries, headings, and smaller section Markdown URLs with sizes; no article text.' }] : []), { title: 'Resource response headers', url: publicPath('/resource-headers.json'), summary: 'Published hosting metadata: content types and representation Link headers for host adapters.' }, { title: 'Document sync snapshot', url: publicPath('/documents.sync.json'), summary: 'Save and compare compact page signatures between builds; build-info.json identifies the current build.' }, { title: 'Structured document manifest', url: publicPath('/documents.json'), summary: 'Stable page IDs, HTML and Markdown URLs, and content digests.' }, ...(sitemaps.size ? [{ title: 'XML sitemap', url: publicPath('/sitemap.xml'), summary: 'Canonical URLs for indexable pages.' }] : []), ...(search.index ? [{ title: 'Lexical search index', url: publicPath('/search-index.json'), summary: 'Downloadable page titles, summaries, headings, and bounded HTML article text. It is an index file, not a query endpoint.' }] : []), ...(catalog ? [{ title: 'API catalog', url: publicPath('/.well-known/api-catalog'), summary: '' }] : [])]), ...sections, ...(apiSources.some(item => llms.format === 'flat' || !fictionalApis.has(item.apiId)) ? ['', '## API contracts', '', discoveryLinks(apiSources.filter(item => llms.format === 'flat' || !fictionalApis.has(item.apiId)).map(item => ({ title: `${fictionalApis.has(item.apiId) ? 'Fictional example: ' : ''}${item.apiId} ${item.channel} ${item.version} OpenAPI`, url: item.sourceUrl, summary: `Pinned ${item.mediaType} source used for the reference.` })))] : []), ...(llms.format === 'grouped' && optional.length ? ['', '## Optional', '', optionalList] : [])].join('\n') + '\n';
     addPublicArtifact('/llms.txt', discovery + tabLinks + (tabLinks ? '\n' : ''));
-    const publications = [...new Set(rendered.map(page => `${page.doc.variant.channel}/${page.doc.variant.version}/${page.doc.variant.language}`))].sort();
+    const publications = [...new Set(rendered.map(page => `${publicationLabel(page.doc.variant)}`))].sort();
     const pageSizes = new Map(manifest.documents.map(page => [page.markdownUrl, page]));
     const compactSummary = (page) => {
         const size = pageSizes.get(page.doc.markdownRoute);
@@ -245,21 +246,23 @@ export async function assembleArtifacts(input) {
     };
     const compactEntries = [...rendered].sort((a, b) => a.doc.route.localeCompare(b.doc.route)).map(page => {
         const entry = discoveryEntry(page);
-        const publication = `${page.doc.variant.channel}/${page.doc.variant.version}/${page.doc.variant.language}`;
+        const publication = `${publicationLabel(page.doc.variant)}`;
         const approved = (page.sections ?? []).filter(section => section.standalone === true);
         return [paragraph(link(entry.url, `${page.doc.frontmatter.id} · ${entry.title}${publications.length > 1 ? ` (${publication})` : ''}`), text(`: ${compactSummary(page)}`)),
             ...(approved.length ? [list(approved.map(section => [paragraph(text('Standalone section: '), link(section.markdownUrl, section.title), text(` — ${section.markdownTokens} tokens (${section.markdownTokenEncoding}), ${section.markdownBytes} UTF-8 bytes. `), link(entry.url, 'Full page'), text('.'))]))] : [])];
     });
     const compactList = renderMarkdown(root([list(compactEntries)])).trimEnd();
+    const productGuidance = configField(config.publications, 'products') ? [paragraph(text('Products have independent versions. Discover published product/channel/version/language coordinates with MCP get_publications, or documents.json. Keep the exact publication returned by search when reading pages; cross-product links must name their target explicitly. This edition contains only its selected content.'))] : [];
     const compactIntro = renderMarkdown(root([
         heading(1, String(config.site.title)),
+        ...productGuidance,
         paragraph(text(`Full-page token counts use ${markdownTokenEncoding}. Fetch a matching full Markdown page by default. Use a listed standalone section only for its stated topic; for setup, broader questions, or missing context, follow Full page. Standalone is an author declaration, not proof of completeness.`)),
-        paragraph(text(publications.length === 1 ? `Publication (channel/version/language): ${publications[0]}.` : 'Choose the matching channel/version/language shown on each page; keep that publication when following links.')),
+        paragraph(text(publications.length === 1 ? `Publication (${configField(config.publications, 'products') ? 'product/' : ''}channel/version/language): ${publications[0]}.` : `Choose the matching ${configField(config.publications, 'products') ? 'product/' : ''}channel/version/language shown on each page; keep that publication when following links.`)),
         paragraph(link(publicPath('/llms.txt'), 'Full documentation index'), text('. Full manifests and search indexes are optional. A missing match does not establish that a feature exists or does not exist.')),
     ])).trimEnd();
     const topicEntries = rendered.flatMap(page => {
         const entry = discoveryEntry(page);
-        const publication = `${page.doc.variant.channel}/${page.doc.variant.version}/${page.doc.variant.language}`;
+        const publication = `${publicationLabel(page.doc.variant)}`;
         const area = Array.isArray(page.doc.frontmatter.area) ? page.doc.frontmatter.area[0] : page.doc.frontmatter.area;
         const topic = JSON.stringify([publication, area ?? page.doc.frontmatter.type]);
         const topicLabel = `${(area && manifest.taxonomy?.areas[area]?.label) || area || page.doc.frontmatter.type}${publications.length > 1 ? ` (${publication})` : ''}`;
@@ -283,7 +286,7 @@ export async function assembleArtifacts(input) {
         const members = manifest.documents.filter(doc => doc.navigationTab?.indexUrl === tab.indexUrl);
         const intro = renderMarkdown(root([
             heading(1, tab.label),
-            paragraph(text(`Full-page token counts use ${markdownTokenEncoding}. Navigation section ID: ${tab.id}. Publication: ${tab.variant.channel}/${tab.variant.version}/${tab.variant.language}.`)),
+            paragraph(text(`Full-page token counts use ${markdownTokenEncoding}. Navigation section ID: ${tab.id}. Publication: ${publicationLabel(tab.variant)}.`)),
             paragraph(link(outputUrl(publicPath('/llms.min.txt'), '/', siteOrigin, 'markdown', documentRoutes, basePath), 'All sections and published pages'), text('. This index covers this section only; shared and unlisted pages remain reachable through the global index. Reader views do not remove pages from this index.')),
         ])).trimEnd();
         const memberUrls = new Set(members.flatMap(doc => [doc.markdownUrl, ...doc.sections.filter(section => section.standalone === true).map(section => section.markdownUrl)]));

package/dist/ask-runtime.d.ts

@@ -10,6 +10,7 @@ export type AskSetupInput = {
     settings?: Record<string, unknown>;
     model?: string;
     passages?: number;
+    product?: string;
     channel?: string;
     version?: string;
     language?: string;

package/dist/ask-runtime.js

@@ -1,3 +1,4 @@
+import { parsePublicationKey } from './publication-identity.js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { AnswerCache } from './answer-cache.js';
@@ -48,9 +49,13 @@ export async function prepareAskRuntime(input) {
     const embeddings = await readEmbeddings(input.siteDirectory);
     const retriever = new Retriever(chunks, embeddings);
     const variants = retriever.variants();
-    const variant = input.channel && input.version && input.language ? `${input.channel}|${input.version}|${input.language}` : variants.length === 1 ? variants[0] : undefined;
+    const matchingVariants = variants.filter(key => {
+        const coordinate = parsePublicationKey(key);
+        return ['product', 'channel', 'version', 'language'].every(field => input[field] === undefined || coordinate[field] === input[field]);
+    });
+    const variant = matchingVariants.length === 1 ? matchingVariants[0] : undefined;
     if (!variant)
-        throw new Error(`The site has several publications (${variants.join(', ')}); pass --channel, --version, and --language`);
+        throw new Error(`Select one publication from (${matchingVariants.join(', ')}); pass --product where applicable, --channel, --version, and --language`);
     let embedQuery;
     let embedTexts;
     let embedding;

package/dist/authored-change.js

@@ -1,3 +1,4 @@
+import { documentKey } from './publication-identity.js';
 import { link, list, paragraph, root, text } from './semantic-markdown.js';
 export const changeKinds = ['editorial', 'procedure', 'behavior', 'breaking'];
 const labels = { editorial: 'Editorial correction', procedure: 'Procedure change', behavior: 'Behavior change', breaking: 'Breaking change' };
@@ -26,7 +27,7 @@ export function resolveAuthoredChange(doc, docs) {
     if (!value)
         return;
     const target = (id, field) => {
-        const found = docs.get(`${id}|${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`);
+        const found = docs.get(documentKey(id, doc.variant));
         if (id === doc.frontmatter.id || !found || found.frontmatter.access?.policy !== 'public')
             throw new Error(`${doc.file}: change.${field} must name another public document in the same publication: ${id}`);
         return { id, title: found.frontmatter.title, url: found.route, markdownUrl: found.markdownRoute };

package/dist/authoring-project.js

@@ -119,7 +119,7 @@ export async function inspectAuthoringProject(configFile, options = {}) {
                     const doc = await readDocument(file, value.frontmatter, undefined, raw);
                     const fm = doc.frontmatter;
                     pages.push({ id: fm.id, file: relative(file), digest: digest(raw), title: fm.title, summary: fm.summary, type: fm.type, slug: fm.slug,
-                        publication: { channel: fm.channel ?? value.publications?.defaults?.channel, version: fm.version ?? value.publications?.defaults?.version, language: fm.language ?? defaultLanguage(value), ...(fm.publications ? { publications: fm.publications } : {}) },
+                        publication: { ...(value.publications?.products && fm.product ? { product: fm.product } : {}), channel: fm.channel ?? value.publications?.defaults?.channel, version: value.publications?.products && fm.product && doc.sourceFrontmatter.version === undefined && value.frontmatter?.enforced?.version === undefined ? value.publications.products[fm.product]?.defaultVersion : fm.version ?? value.publications?.defaults?.version, language: fm.language ?? defaultLanguage(value), ...(fm.publications ? { publications: fm.publications } : {}) },
                         access: fm.access ?? null, aliases: [] });
                     bodies.set(relative(file), doc.body);
                     findings.push(...authoringHints(doc.body, relative(file)).map(({ location, ...hint }) => hint));

package/dist/cards.js

@@ -1,3 +1,4 @@
+import { samePublication } from './publication-identity.js';
 import { cardIcon, validateCardIcon } from './icons.js';
 import { surfaceText } from './surface-text.js';
 import { heading, link, list, paragraph, text } from './content.js';
@@ -7,7 +8,7 @@ const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 const relationLabels = { prerequisite: 'Read first', 'next-step': 'Next steps', reference: 'Reference while working', advanced: 'Go deeper', 'see-also': 'Related topics', 'not-confused-with': 'Often confused with' };
 const relationTypes = new Set(Object.keys(relationLabels));
 const symmetric = (type) => type === 'see-also' || type === 'not-confused-with';
-const sameVariant = (a, b) => a.channel === b.channel && a.version === b.version && a.language === b.language;
+const sameVariant = (a, b) => samePublication(a, b);
 export function validateCardMetadata(value, file) {
     if (value === undefined)
         return;

package/dist/cli-discovery.d.ts

@@ -1,4 +1,4 @@
-export declare const docsHelp = "Usage: shoalrun docs <command>\n\nRead bundled references (no project or provider key required):\n  search <query> [--json]\n  read <document-id> [--json]\n\nInspect a project:\n  project [--config FILE] [--profile FILE] [--section pages|guidance|configuration|navigation|relationships|templates|findings]\n  source FILE [--config FILE] [--profile FILE]\n  context <document-id> [--config FILE]\n\nValidate and preview edits:\n  baseline --out FILE [--config FILE] [--profile FILE]\n  validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]\n  validation-status REPORT\n  review REPORT [--format json|markdown]\n  preview REPORT [--port PORT]\n\nOther authoring tools: changes, plan, apply, mcp.\nDiscover packaged agent guidance with shoalrun skills list.\n";
+export declare const docsHelp = "Usage: shoalrun docs <command>\n\nRead bundled references (no project or provider key required):\n  search <query> [--json]\n  read <document-id> [--json]\n  outline <document-id> [--json]\n  section <document-id> <section-id> [--json]\n\nSearch and reads accept --site DIRECTORY, --max-tokens N, and publication\nselectors --product P --channel C --version V --language L.\n\nInspect a project:\n  project [--config FILE] [--profile FILE] [--section pages|guidance|configuration|navigation|relationships|templates|findings]\n  source FILE [--config FILE] [--profile FILE]\n  context <document-id> [--config FILE]\n\nValidate and preview edits:\n  baseline --out FILE [--config FILE] [--profile FILE]\n  validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]\n  validation-status REPORT\n  review REPORT [--format json|markdown]\n  preview REPORT [--port PORT]\n\nOther authoring tools: changes, plan, apply, mcp.\nDiscover packaged agent guidance with shoalrun skills list.\n";
 export declare const skillsHelp = "Usage: shoalrun skills list [--json]\n       shoalrun skills read <name> [--json]\n\nList the names, descriptions and local paths of packaged skills, or read a skill.\nThese commands do not install skills or require a project or provider key.\n";
-export declare const cliHelp = "Usage: shoalrun <command>\n\nStart and build:\n  init [directory] [--starter minimal|api-docs|showcase]\n  build [config] [output] [--profile FILE]\n  export [config] --out DIRECTORY [--target NAME] [--profile FILE]\n  dev [config] [output] [--port PORT]\n  serve <site-directory> [--host HOST] [--port PORT]\n  check [config] [--json]\n  audit [config]\n  scaffold <template> -n <target> [--config FILE]\n\nAgent guidance and offline documentation:\n  skills list [--json]\n  skills read <name> [--json]\n  docs search <query> [--json]\n  docs read <document-id> [--json]\n  docs project [--config FILE] [--profile FILE]\n  docs baseline --out FILE [--config FILE] [--profile FILE]\n  docs validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]\n  docs review REPORT [--format json|markdown]\n  docs preview REPORT [--port PORT]\n\nOther commands: config, api, operation, ingredient, recipe, search, index,\nask, answers, ask-log, chat, eval, vercel.\nRun shoalrun docs --help or shoalrun skills --help for discovery commands.\n";
+export declare const cliHelp = "Usage: shoalrun <command>\n\nStart and build:\n  init [directory] [--starter minimal|api-docs|showcase]\n  build [config] [output] [--profile FILE]\n  export [config] --out DIRECTORY [--target NAME] [--profile FILE]\n  dev [config] [output] [--profile FILE] [--port PORT]\n  serve <site-directory> [--host HOST] [--port PORT]\n  check [config] [--json]\n  audit [config]\n  scaffold <template> -n <target> [--config FILE] [--product P]\n\nAgent guidance and offline documentation:\n  skills list [--json]\n  skills read <name> [--json]\n  docs search <query> [--site DIRECTORY] [--product P] [--json]\n  docs read <document-id> [--site DIRECTORY] [--product P] [--json]\n  docs project [--config FILE] [--profile FILE]\n  docs baseline --out FILE [--config FILE] [--profile FILE]\n  docs validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]\n  docs review REPORT [--format json|markdown]\n  docs preview REPORT [--port PORT]\n\nOther commands: config, api, operation, ingredient, recipe, search, index,\nask, answers, ask-log, chat, eval, vercel.\nRun shoalrun docs --help or shoalrun skills --help for discovery commands.\n";
 export declare function runSkillsCommand(args: string[]): Promise<string>;

package/dist/cli-discovery.js

@@ -7,6 +7,11 @@ export const docsHelp = `Usage: shoalrun docs <command>
 Read bundled references (no project or provider key required):
   search <query> [--json]
   read <document-id> [--json]
+  outline <document-id> [--json]
+  section <document-id> <section-id> [--json]
+
+Search and reads accept --site DIRECTORY, --max-tokens N, and publication
+selectors --product P --channel C --version V --language L.
 
 Inspect a project:
   project [--config FILE] [--profile FILE] [--section pages|guidance|configuration|navigation|relationships|templates|findings]
@@ -35,17 +40,17 @@ Start and build:
   init [directory] [--starter minimal|api-docs|showcase]
   build [config] [output] [--profile FILE]
   export [config] --out DIRECTORY [--target NAME] [--profile FILE]
-  dev [config] [output] [--port PORT]
+  dev [config] [output] [--profile FILE] [--port PORT]
   serve <site-directory> [--host HOST] [--port PORT]
   check [config] [--json]
   audit [config]
-  scaffold <template> -n <target> [--config FILE]
+  scaffold <template> -n <target> [--config FILE] [--product P]
 
 Agent guidance and offline documentation:
   skills list [--json]
   skills read <name> [--json]
-  docs search <query> [--json]
-  docs read <document-id> [--json]
+  docs search <query> [--site DIRECTORY] [--product P] [--json]
+  docs read <document-id> [--site DIRECTORY] [--product P] [--json]
   docs project [--config FILE] [--profile FILE]
   docs baseline --out FILE [--config FILE] [--profile FILE]
   docs validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]