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

package/dist/ask-runtime.js

@@ -0,0 +1,101 @@
+import { parsePublicationKey } from './publication-identity.js';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { AnswerCache } from './answer-cache.js';
+import { CardIndex, readCards } from './answer-cards.js';
+import { chatProviderConfig, chatRoutes, validateChat } from './chat-config.js';
+import { createChatProvider, fallbackChat } from './chat.js';
+import { validateReaderFilters, validateReaderSelection } from './reader-filters.js';
+import { createProvider, readEmbeddings } from './embeddings.js';
+import { DailyBudget, memoryBudgetStore } from './budget.js';
+import { envBudgetStore } from './budget-store.js';
+import { jevAvailable, jevEndpoint } from './jev.js';
+import { queryProviderConfig, validateRetrieval } from './retrieval-config.js';
+import { Retriever } from './retrieval.js';
+// `--reader-view audience=authors,maintainers`, repeatable for more than one filter.
+export function parseReaderView(specs) {
+    if (!specs.length)
+        return undefined;
+    const selection = {};
+    for (const spec of specs) {
+        const match = /^([a-z][a-z0-9-]*)=(.+)$/.exec(spec);
+        if (!match)
+            throw new Error(`--reader-view needs facet=choice[,choice], such as audience=authors; got ${JSON.stringify(spec)}`);
+        if (selection[match[1]])
+            throw new Error(`--reader-view names ${match[1]} twice`);
+        selection[match[1]] = match[2].split(',').map(choice => choice.trim()).filter(Boolean);
+    }
+    return selection;
+}
+// Everything `shoalrun ask` and the answer eval share: read the project's chat and retrieval settings, load the passages and any
+// vectors, and wire up the optional layers. A layer that isn't configured is left out, and one that is configured but can't run
+// (Jev without a key) is left out with a note.
+export async function prepareAskRuntime(input) {
+    const settings = input.settings;
+    const readerFilters = validateReaderFilters(settings.readerFilters);
+    const chatConfig = validateChat(settings.chat, readerFilters);
+    const retrieval = validateRetrieval(settings.retrieval);
+    // --model replaces the main model only. Fallback and escalation models still inherit the config's settings.
+    const mainConfig = chatProviderConfig(chatConfig, { model: input.model });
+    const routes = chatRoutes(chatConfig, chatProviderConfig(chatConfig));
+    const chat = fallbackChat([createChatProvider(mainConfig), ...routes.fallbacks.map(createChatProvider)]);
+    let chunks;
+    try {
+        chunks = JSON.parse(await readFile(path.join(input.siteDirectory, 'ai', 'chunks.json'), 'utf8'));
+    }
+    catch (error) {
+        throw error.code === 'ENOENT' ? new Error(`No ai/chunks.json in ${input.siteDirectory}; run shoalrun index first`) : error;
+    }
+    const embeddings = await readEmbeddings(input.siteDirectory);
+    const retriever = new Retriever(chunks, embeddings);
+    const variants = retriever.variants();
+    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(`Select one publication from (${matchingVariants.join(', ')}); pass --product where applicable, --channel, --version, and --language`);
+    let embedQuery;
+    let embedTexts;
+    let embedding;
+    if (embeddings) {
+        const queryProvider = createProvider(queryProviderConfig(retrieval, embeddings.meta));
+        if (queryProvider.space !== embeddings.meta.space || (embeddings.meta.backend && queryProvider.backend !== embeddings.meta.backend))
+            throw new Error(`${queryProvider.model} is not in the embedding space or backend of ${embeddings.meta.model}; set retrieval.embeddings.queryModel and baseUrl to compatible values`);
+        embedQuery = async (text, signal) => (await queryProvider.embed([text], 'query', signal))[0];
+        embedTexts = texts => queryProvider.embed(texts, 'query');
+        embedding = { provider: queryProvider.name, model: queryProvider.model, space: queryProvider.space, dimension: queryProvider.dimension };
+    }
+    // A reader view on the command line replaces the config's, so one run can answer for a different audience.
+    if (input.readerView && !readerFilters)
+        throw new Error('--reader-view needs readerFilters.facets in the site config');
+    const readerSelection = input.readerView ? validateReaderSelection(input.readerView, readerFilters, '--reader-view') : chatConfig?.readerView;
+    const notes = [];
+    const rerank = Boolean(chatConfig?.rerank) && !input.noRerank;
+    const scoring = chatConfig?.rerank;
+    const scorer = { ...(scoring?.endpoint ? { endpoint: jevEndpoint(scoring.endpoint) } : {}), ...(scoring?.model ? { model: scoring.model } : {}), ...(scoring?.keyEnv ? { keyEnv: scoring.keyEnv } : {}), ...(scoring?.stateFormat ? { stateFormat: scoring.stateFormat } : {}), ...(input.jevCacheDir ? { cacheDir: input.jevCacheDir } : {}) };
+    const scoringReady = jevAvailable(scoring?.keyEnv);
+    // A scorer that is configured but has no key counts as down, not as absent: it is what keeps off-topic questions from the model.
+    if (rerank && !scoringReady)
+        notes.push(`The relevance scorer has no key: set ${scoring?.keyEnv ?? 'JEV_API_KEY'}. Until then it counts as down, so ${scoring?.onError === 'answer' ? 'the model answers without the gate and the claim check' : 'questions get the closest pages and no model call'}`);
+    // Answer cards need semantic search and Jev. A configured but missing card file is a note, not an error, so the chat still answers.
+    let cards;
+    if (chatConfig?.cards && !input.noCards && rerank && scoringReady) {
+        const file = await readCards(input.siteDirectory);
+        if (!file)
+            notes.push('chat.cards is set but there is no ai/answers.json; run shoalrun answers to make it');
+        else if (!embedding || file.embedding.space !== embedding.space || file.embedding.dimension !== embedding.dimension)
+            notes.push('The answer cards were made with a different embedding model, so they are not used; run shoalrun answers again');
+        else
+            cards = { index: new CardIndex(file), threshold: chatConfig.cards.threshold, confirm: chatConfig.cards.confirm, jev: { ...scorer, maxCalls: 1 } };
+    }
+    // The shared store is for a hosted function. A local run keeps its counters in memory, so it never needs the store's keys.
+    const store = input.sharedStore && chatConfig?.budget?.store ? envBudgetStore(chatConfig.budget.store) : memoryBudgetStore();
+    const reported = new Set();
+    const onBudgetError = (error) => { if (!reported.has(error.message)) {
+        reported.add(error.message);
+        process.stderr.write(`Budget: ${error.message}. Questions get the closest pages, with no model call, until it works.\n`);
+    } };
+    return { ...(chatConfig?.budget ? { budget: new DailyBudget(store, chatConfig.budget, Date.now, onBudgetError), budgetStore: store } : {}), chat, notes, embedTexts, embedding, options: { ...(scoring?.onError ? { onScorerError: scoring.onError } : {}), retriever, chat, variant, readerSelection, embedQuery, passages: input.passages ?? chatConfig?.passages, gate: chatConfig?.gate, ...(input.maxTokens ? { maxTokens: input.maxTokens } : {}), ...(rerank ? { jev: { ...scorer, top: 24, maxCalls: 2 } } : {}), ...(cards ? { cards } : {}), ...(input.cache && chatConfig?.cache ? { cache: new AnswerCache({ maxEntries: chatConfig.cache.maxEntries, ttlMs: chatConfig.cache.ttlMinutes * 60_000 }) } : {}), ...(routes.escalate && !input.noEscalate ? { escalate: { chat: createChatProvider(routes.escalate.config), when: routes.escalate.when } } : {}), ...(rerank && scoringReady && !input.noDirect && (input.direct || chatConfig?.direct) ? { direct: { threshold: input.direct?.threshold ?? chatConfig.direct.threshold, maxChars: input.direct?.maxChars ?? chatConfig?.direct?.maxChars ?? 1200, margin: chatConfig?.direct?.margin ?? 0.1, others: chatConfig?.direct?.others ?? 1, jev: { ...scorer, maxCalls: 2 } } } : {}), ...(rerank && scoringReady && chatConfig?.verify ? { verify: { ...chatConfig.verify, jev: { ...scorer, maxCalls: 3 } } } : {}) } };
+}

package/dist/ask-setup.d.ts

@@ -1,43 +1,4 @@
-import type { AskOptions } from './ask.js';
-import { type ChatProvider } from './chat.js';
-import { type ReaderSelection } from './reader-filters.js';
-import { DailyBudget, type BudgetStore } from './budget.js';
-export declare function parseReaderView(specs: string[]): ReaderSelection | undefined;
-export type AskSetupInput = {
-    sharedStore?: boolean;
-    siteDirectory: string;
-    configFile?: string;
-    settings?: Record<string, unknown>;
-    model?: string;
-    passages?: number;
-    channel?: string;
-    version?: string;
-    language?: string;
-    noRerank?: boolean;
-    noDirect?: boolean;
-    noEscalate?: boolean;
-    noCards?: boolean;
-    cache?: boolean;
-    direct?: {
-        threshold: number;
-        maxChars?: number;
-    };
-    jevCacheDir?: string;
-    readerView?: ReaderSelection;
-    maxTokens?: number;
-};
-export type AskSetup = {
-    budget?: DailyBudget;
-    budgetStore?: BudgetStore;
-    chat: ChatProvider;
-    options: Omit<AskOptions, 'question'>;
-    notes: string[];
-    embedTexts?: (texts: string[]) => Promise<Float32Array[]>;
-    embedding?: {
-        provider: string;
-        model: string;
-        space: string;
-        dimension: number;
-    };
-};
+import { type AskSetup, type AskSetupInput } from './ask-runtime.js';
+export { parseReaderView } from './ask-runtime.js';
+export type { AskSetup, AskSetupInput } from './ask-runtime.js';
 export declare function prepareAsk(input: AskSetupInput): Promise<AskSetup>;

package/dist/ask-setup.js

@@ -1,99 +1,11 @@
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { AnswerCache } from './answer-cache.js';
-import { CardIndex, readCards } from './answer-cards.js';
-import { chatProviderConfig, chatRoutes, validateChat } from './chat-config.js';
-import { createChatProvider, fallbackChat } from './chat.js';
 import { loadConfig } from './config.js';
-import { validateReaderFilters, validateReaderSelection } from './reader-filters.js';
-import { createProvider, readEmbeddings } from './embeddings.js';
-import { DailyBudget, memoryBudgetStore } from './budget.js';
-import { envBudgetStore } from './budget-store.js';
-import { jevAvailable, jevEndpoint } from './jev.js';
-import { queryProviderConfig, validateRetrieval } from './retrieval-config.js';
-import { Retriever } from './retrieval.js';
-// `--reader-view audience=authors,maintainers`, repeatable for more than one filter.
-export function parseReaderView(specs) {
-    if (!specs.length)
-        return undefined;
-    const selection = {};
-    for (const spec of specs) {
-        const match = /^([a-z][a-z0-9-]*)=(.+)$/.exec(spec);
-        if (!match)
-            throw new Error(`--reader-view needs facet=choice[,choice], such as audience=authors; got ${JSON.stringify(spec)}`);
-        if (selection[match[1]])
-            throw new Error(`--reader-view names ${match[1]} twice`);
-        selection[match[1]] = match[2].split(',').map(choice => choice.trim()).filter(Boolean);
-    }
-    return selection;
-}
-// Everything `shoalrun ask` and the answer eval share: read the project's chat and retrieval settings, load the passages and any
-// vectors, and wire up the optional layers. A layer that isn't configured is left out, and one that is configured but can't run
-// (Jev without a key) is left out with a note.
+import { prepareAskRuntime } from './ask-runtime.js';
+export { parseReaderView } from './ask-runtime.js';
+// Local authoring/evaluation accepts a source config. Hosted functions import
+// ask-runtime directly and receive already-resolved settings instead.
 export async function prepareAsk(input) {
     if (!input.settings && !input.configFile)
         throw new Error('prepareAsk needs a config file or settings');
     const settings = input.settings ?? (await loadConfig(input.configFile)).value;
-    const readerFilters = validateReaderFilters(settings.readerFilters);
-    const chatConfig = validateChat(settings.chat, readerFilters);
-    const retrieval = validateRetrieval(settings.retrieval);
-    // --model replaces the main model only. Fallback and escalation models still inherit the config's settings.
-    const mainConfig = chatProviderConfig(chatConfig, { model: input.model });
-    const routes = chatRoutes(chatConfig, chatProviderConfig(chatConfig));
-    const chat = fallbackChat([createChatProvider(mainConfig), ...routes.fallbacks.map(createChatProvider)]);
-    let chunks;
-    try {
-        chunks = JSON.parse(await readFile(path.join(input.siteDirectory, 'ai', 'chunks.json'), 'utf8'));
-    }
-    catch (error) {
-        throw error.code === 'ENOENT' ? new Error(`No ai/chunks.json in ${input.siteDirectory}; run shoalrun index first`) : error;
-    }
-    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;
-    if (!variant)
-        throw new Error(`The site has several publications (${variants.join(', ')}); pass --channel, --version, and --language`);
-    let embedQuery;
-    let embedTexts;
-    let embedding;
-    if (embeddings) {
-        const queryProvider = createProvider(queryProviderConfig(retrieval, embeddings.meta));
-        if (queryProvider.space !== embeddings.meta.space || (embeddings.meta.backend && queryProvider.backend !== embeddings.meta.backend))
-            throw new Error(`${queryProvider.model} is not in the embedding space or backend of ${embeddings.meta.model}; set retrieval.embeddings.queryModel and baseUrl to compatible values`);
-        embedQuery = async (text, signal) => (await queryProvider.embed([text], 'query', signal))[0];
-        embedTexts = texts => queryProvider.embed(texts, 'query');
-        embedding = { provider: queryProvider.name, model: queryProvider.model, space: queryProvider.space, dimension: queryProvider.dimension };
-    }
-    // A reader view on the command line replaces the config's, so one run can answer for a different audience.
-    if (input.readerView && !readerFilters)
-        throw new Error('--reader-view needs readerFilters.facets in the site config');
-    const readerSelection = input.readerView ? validateReaderSelection(input.readerView, readerFilters, '--reader-view') : chatConfig?.readerView;
-    const notes = [];
-    const rerank = Boolean(chatConfig?.rerank) && !input.noRerank;
-    const scoring = chatConfig?.rerank;
-    const scorer = { ...(scoring?.endpoint ? { endpoint: jevEndpoint(scoring.endpoint) } : {}), ...(scoring?.model ? { model: scoring.model } : {}), ...(scoring?.keyEnv ? { keyEnv: scoring.keyEnv } : {}), ...(scoring?.stateFormat ? { stateFormat: scoring.stateFormat } : {}), ...(input.jevCacheDir ? { cacheDir: input.jevCacheDir } : {}) };
-    const scoringReady = jevAvailable(scoring?.keyEnv);
-    // A scorer that is configured but has no key counts as down, not as absent: it is what keeps off-topic questions from the model.
-    if (rerank && !scoringReady)
-        notes.push(`The relevance scorer has no key: set ${scoring?.keyEnv ?? 'JEV_API_KEY'}. Until then it counts as down, so ${scoring?.onError === 'answer' ? 'the model answers without the gate and the claim check' : 'questions get the closest pages and no model call'}`);
-    // Answer cards need semantic search and Jev. A configured but missing card file is a note, not an error, so the chat still answers.
-    let cards;
-    if (chatConfig?.cards && !input.noCards && rerank && scoringReady) {
-        const file = await readCards(input.siteDirectory);
-        if (!file)
-            notes.push('chat.cards is set but there is no ai/answers.json; run shoalrun answers to make it');
-        else if (!embedding || file.embedding.space !== embedding.space || file.embedding.dimension !== embedding.dimension)
-            notes.push('The answer cards were made with a different embedding model, so they are not used; run shoalrun answers again');
-        else
-            cards = { index: new CardIndex(file), threshold: chatConfig.cards.threshold, confirm: chatConfig.cards.confirm, jev: { ...scorer, maxCalls: 1 } };
-    }
-    // The shared store is for a hosted function. A local run keeps its counters in memory, so it never needs the store's keys.
-    const store = input.sharedStore && chatConfig?.budget?.store ? envBudgetStore(chatConfig.budget.store) : memoryBudgetStore();
-    const reported = new Set();
-    const onBudgetError = (error) => { if (!reported.has(error.message)) {
-        reported.add(error.message);
-        process.stderr.write(`Budget: ${error.message}. Questions get the closest pages, with no model call, until it works.\n`);
-    } };
-    return { ...(chatConfig?.budget ? { budget: new DailyBudget(store, chatConfig.budget, Date.now, onBudgetError), budgetStore: store } : {}), chat, notes, embedTexts, embedding, options: { ...(scoring?.onError ? { onScorerError: scoring.onError } : {}), retriever, chat, variant, readerSelection, embedQuery, passages: input.passages ?? chatConfig?.passages, gate: chatConfig?.gate, ...(input.maxTokens ? { maxTokens: input.maxTokens } : {}), ...(rerank ? { jev: { ...scorer, top: 24, maxCalls: 2 } } : {}), ...(cards ? { cards } : {}), ...(input.cache && chatConfig?.cache ? { cache: new AnswerCache({ maxEntries: chatConfig.cache.maxEntries, ttlMs: chatConfig.cache.ttlMinutes * 60_000 }) } : {}), ...(routes.escalate && !input.noEscalate ? { escalate: { chat: createChatProvider(routes.escalate.config), when: routes.escalate.when } } : {}), ...(rerank && scoringReady && !input.noDirect && (input.direct || chatConfig?.direct) ? { direct: { threshold: input.direct?.threshold ?? chatConfig.direct.threshold, maxChars: input.direct?.maxChars ?? chatConfig?.direct?.maxChars ?? 1200, margin: chatConfig?.direct?.margin ?? 0.1, others: chatConfig?.direct?.others ?? 1, jev: { ...scorer, maxCalls: 2 } } } : {}), ...(rerank && scoringReady && chatConfig?.verify ? { verify: { ...chatConfig.verify, jev: { ...scorer, maxCalls: 3 } } } : {}) } };
+    return prepareAskRuntime({ ...input, settings });
 }

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]

package/dist/cli.js

@@ -142,11 +142,19 @@ try {
         const args = [subcommand, ...rest].filter((item) => item !== undefined);
         const positional = [];
         let port = defaultPort();
+        let profile;
         for (let index = 0; index < args.length; index++) {
-            if (args[index] === '--port') {
+            if (args[index] === '--port' || args[index] === '--profile') {
+                const option = args[index];
                 if (!args[index + 1] || args[index + 1].startsWith('--'))
-                    throw new Error('Usage: shoalrun dev [config] [output] [--port PORT]');
-                port = Number(args[++index]);
+                    throw new Error('Usage: shoalrun dev [config] [output] [--port PORT] [--profile FILE]');
+                if (option === '--profile') {
+                    if (profile !== undefined)
+                        throw new Error('Duplicate dev option --profile');
+                    profile = args[++index];
+                }
+                else
+                    port = Number(args[++index]);
             }
             else if (args[index].startsWith('--'))
                 throw new Error(`Unknown dev option ${args[index]}`);
@@ -154,8 +162,8 @@ try {
                 positional.push(args[index]);
         }
         if (positional.length > 2)
-            throw new Error('Usage: shoalrun dev [config] [output] [--port PORT]');
-        await startDev(positional[0] ?? 'docs.config.yaml', positional[1] ?? 'site-dist', '127.0.0.1', port);
+            throw new Error('Usage: shoalrun dev [config] [output] [--port PORT] [--profile FILE]');
+        await startDev(positional[0] ?? 'docs.config.yaml', positional[1] ?? 'site-dist', '127.0.0.1', port, { profile });
     }
     else if (command === 'vercel' && subcommand === 'build') {
         // --chat adds the optional answer function: it needs chat and retrieval settings and the embedding key at build time.
@@ -372,9 +380,9 @@ try {
     }
     else if (command === 'search') {
         if (!subcommand || !rest[0] || rest[0].startsWith('--'))
-            throw new Error('Usage: shoalrun search <site-directory> <query> [--channel C] [--version V] [--language L] [--limit N]');
+            throw new Error('Usage: shoalrun search <site-directory> <query> [--product P] [--channel C] [--version V] [--language L] [--limit N]');
         const options = {};
-        const names = { '--channel': 'channel', '--version': 'version', '--language': 'language', '--limit': 'limit' };
+        const names = { '--product': 'product', '--channel': 'channel', '--version': 'version', '--language': 'language', '--limit': 'limit' };
         for (let index = 1; index < rest.length; index += 2) {
             const flag = rest[index];
             const value = rest[index + 1];
@@ -432,7 +440,7 @@ try {
         process.stdout.write(JSON.stringify({ status: 'ok', documents: result.documents, chunks: result.index.chunks.length, sourceDigest: result.index.sourceDigest, publications, output: result.output, ...(embeddings ? { embeddings } : {}) }, null, 2) + '\n');
     }
     else if (command === 'ask') {
-        const usage = 'Usage: shoalrun ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json]';
+        const usage = 'Usage: shoalrun ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--product P] [--channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json]';
         if (!subcommand || subcommand.startsWith('--') || !rest[0] || rest[0].startsWith('--'))
             throw new Error(usage);
         const values = {};
@@ -449,14 +457,14 @@ try {
                 views.push(value);
                 continue;
             }
-            if (!['--config', '--model', '--passages', '--channel', '--version', '--language'].includes(flag) || !value || value.startsWith('--'))
+            if (!['--config', '--model', '--passages', '--product', '--channel', '--version', '--language'].includes(flag) || !value || value.startsWith('--'))
                 throw new Error(usage);
             if (values[flag] !== undefined)
                 throw new Error(`Duplicate ask option ${flag}`);
             values[flag] = value;
         }
         const configFile = values['--config'] ?? await discoverConfig(process.cwd()).catch(() => { throw new Error('No docs.config.yaml found; pass --config FILE. `ask` reads its chat provider and model from the config'); });
-        const setup = await prepareAsk({ siteDirectory: subcommand, configFile, model: values['--model'], passages: values['--passages'] === undefined ? undefined : Number(values['--passages']), channel: values['--channel'], version: values['--version'], language: values['--language'], noRerank: switches.has('--no-rerank'), noDirect: switches.has('--no-direct'), noEscalate: switches.has('--no-escalate'), noCards: switches.has('--no-cards'), readerView: parseReaderView(views) });
+        const setup = await prepareAsk({ siteDirectory: subcommand, configFile, model: values['--model'], passages: values['--passages'] === undefined ? undefined : Number(values['--passages']), product: values['--product'], channel: values['--channel'], version: values['--version'], language: values['--language'], noRerank: switches.has('--no-rerank'), noDirect: switches.has('--no-direct'), noEscalate: switches.has('--no-escalate'), noCards: switches.has('--no-cards'), readerView: parseReaderView(views) });
         for (const note of setup.notes)
             process.stderr.write(`${note}\n`);
         const chat = setup.chat;
@@ -544,7 +552,7 @@ try {
         }
     }
     else if (command === 'answers') {
-        const usage = 'Usage: shoalrun answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]...';
+        const usage = 'Usage: shoalrun answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--product P --channel C --version V --language L] [--reader-view FACET=CHOICE[,CHOICE]]...';
         if (!subcommand || subcommand.startsWith('--'))
             throw new Error(usage);
         const values = {};
@@ -556,7 +564,7 @@ try {
                 views.push(value);
                 continue;
             }
-            if (!['--questions', '--config', '--model'].includes(flag) || !value || value.startsWith('--'))
+            if (!['--questions', '--config', '--model', '--product', '--channel', '--version', '--language'].includes(flag) || !value || value.startsWith('--'))
                 throw new Error(usage);
             if (values[flag] !== undefined)
                 throw new Error(`Duplicate answers option ${flag}`);
@@ -567,7 +575,7 @@ try {
         const configFile = values['--config'] ?? await discoverConfig(process.cwd()).catch(() => { throw new Error('No docs.config.yaml found; pass --config FILE. `answers` reads its chat provider and model from the config'); });
         const questions = parseCardQuestions(await readFile(values['--questions'], 'utf8'));
         // Cards are polished answers, so they come from the model, not from a direct excerpt, and never from another card.
-        const setup = await prepareAsk({ siteDirectory: subcommand, configFile, model: values['--model'], noCards: true, noDirect: true, readerView: parseReaderView(views) });
+        const setup = await prepareAsk({ siteDirectory: subcommand, configFile, model: values['--model'], product: values['--product'], channel: values['--channel'], version: values['--version'], language: values['--language'], noCards: true, noDirect: true, readerView: parseReaderView(views) });
         for (const note of setup.notes)
             process.stderr.write(`${note}\n`);
         if (!setup.embedTexts || !setup.embedding)
@@ -620,7 +628,7 @@ try {
             if ((!flag?.startsWith('--') && flag !== '-n') || !value || value.startsWith('--'))
                 throw new Error(`Scaffold option ${flag ?? ''} needs a value`);
             const name = flag === '-n' ? 'new' : flag.slice(2);
-            if (!['new', 'config', 'id', 'title', 'summary', 'slug', 'channel', 'version', 'language', 'operation'].includes(name))
+            if (!['new', 'config', 'id', 'title', 'summary', 'slug', 'product', 'channel', 'version', 'language', 'operation'].includes(name))
                 throw new Error(`Unknown scaffold option ${flag}`);
             if (name === 'operation')
                 operations.push(value);
@@ -631,7 +639,7 @@ try {
         }
         if (shortForm && !options.new)
             throw new Error('Scaffold needs -n or --new with a target file');
-        const overrides = { id: options.id, title: options.title, summary: options.summary, slug: options.slug, channel: options.channel, version: options.version, language: options.language, ...(operations.length ? { operations } : {}) };
+        const overrides = { id: options.id, title: options.title, summary: options.summary, slug: options.slug, product: options.product, channel: options.channel, version: options.version, language: options.language, ...(operations.length ? { operations } : {}) };
         const result = shortForm
             ? await scaffoldFromPath(options.config ?? await discoverConfig(process.cwd()), subcommand, options.new, Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined)))
             : await scaffold(rest[0], subcommand, rest[1], overrides);
@@ -691,9 +699,20 @@ try {
             process.exitCode = 1;
     }
     else if (command === 'api' && subcommand === 'select') {
-        if (!rest[0] || !rest[1] || rest[2] !== '--output' || !rest[3] || rest.length !== 4)
-            throw new Error('Usage: shoalrun api select <api-id> <config> --output <selection.yaml>');
-        const result = await selectApiReferences(rest[1], rest[0], rest[3]);
+        const usage = 'Usage: shoalrun api select <api-id> <config> --output FILE [--product P --channel C --version V --language L]';
+        if (!rest[0] || !rest[1])
+            throw new Error(usage);
+        const flags = {};
+        for (let i = 2; i < rest.length; i += 2) {
+            const flag = rest[i];
+            const value = rest[i + 1];
+            if (!['--output', '--product', '--channel', '--version', '--language'].includes(flag) || !value || value.startsWith('--') || flags[flag])
+                throw new Error(usage);
+            flags[flag] = value;
+        }
+        if (!flags['--output'])
+            throw new Error(usage);
+        const result = await selectApiReferences(rest[1], rest[0], flags['--output'], { product: flags['--product'], channel: flags['--channel'], version: flags['--version'], language: flags['--language'] });
         process.stdout.write(JSON.stringify({ status: 'ok', ...result }, null, 2) + '\n');
     }
     else if (command === 'api' && subcommand === 'materialize') {
@@ -710,12 +729,18 @@ try {
                 continue;
             }
             const value = rest[++index];
-            if (!['--operation', '--route', '--output'].includes(flag) || !value || value.startsWith('--'))
+            if (!['--operation', '--route', '--output', '--product', '--channel', '--version', '--language'].includes(flag) || !value || value.startsWith('--'))
                 throw new Error(usage);
             if (flag === '--operation')
                 options.operations.push(value);
             else if (flag === '--route')
                 options.routes.push(value);
+            else if (flag !== '--output') {
+                const key = flag.slice(2);
+                if (options[key])
+                    throw new Error(`Duplicate ${flag}`);
+                options[key] = value;
+            }
             else if (options.output)
                 throw new Error('Duplicate --output');
             else
@@ -725,7 +750,7 @@ try {
         process.stdout.write(JSON.stringify({ status: 'ok', ...result }, null, 2) + '\n');
     }
     else if (command === 'operation' && subcommand === 'inspect') {
-        const usage = 'Usage: shoalrun operation inspect <id> [config] [--channel C] [--version V] [--language L]';
+        const usage = 'Usage: shoalrun operation inspect <id> [config] [--product P] [--channel C] [--version V] [--language L]';
         if (!rest[0] || rest[0].startsWith('--'))
             throw new Error(usage);
         const hasConfig = rest[1] !== undefined && !rest[1].startsWith('--');
@@ -734,7 +759,7 @@ try {
             const flag = rest[index];
             const value = rest[index + 1];
             const name = flag.slice(2);
-            if (!['--channel', '--version', '--language'].includes(flag))
+            if (!['--product', '--channel', '--version', '--language'].includes(flag))
                 throw new Error(`Unknown operation inspect option ${flag}`);
             if (!value || value.startsWith('--'))
                 throw new Error(`Operation inspect option ${flag} needs a value`);
@@ -743,11 +768,11 @@ try {
             filters[name] = value;
         }
         const manifest = await compile(hasConfig ? rest[1] : 'docs.config.yaml');
-        const matches = (manifest.operations[rest[0]] ?? []).filter(item => (!filters.channel || item.channel === filters.channel) && (!filters.version || item.version === filters.version) && (!filters.language || item.language === filters.language));
+        const matches = (manifest.operations[rest[0]] ?? []).filter(item => (!filters.product || item.product === filters.product) && (!filters.channel || item.channel === filters.channel) && (!filters.version || item.version === filters.version) && (!filters.language || item.language === filters.language));
         process.stdout.write(JSON.stringify({ status: matches.length ? 'ok' : 'missing-variant', operationId: rest[0], bindings: matches }, null, 2) + '\n');
     }
     else {
-        throw new Error('Usage: shoalrun init [directory] [--starter minimal|api-docs|showcase] | build [config] [output] [--source-commit SHA] [--release-label LABEL] | check [config] [--json] | audit [config] | vercel build [config] [output] [--source-commit SHA] [--release-label LABEL] [--chat] | serve <site-directory> [--host HOST] [--port PORT] [--search [--config FILE]] [--ask [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]...] | search <site-directory> <query> [--channel C --version V --language L --limit N] | answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]... | chat pause|resume|status --config FILE | ask-log <log-file> [--min-repeats N] [--limit N] [--cards-out FILE] [--json] | ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json] | eval prepare <site-directory> --tasks FILE --out REPORT | eval check <site-directory> --tasks FILE --report REPORT | index <site-directory> [--embed [--config FILE] [--provider voyage|openai] [--model MODEL] [--dimension N] [--base-url URL] [--key-env NAME]] | ingredient draft --spec FILE --out FILE [--config FILE] [--check] | recipe draft --spec FILE --out FILE [--config FILE] [--check] | scaffold <template> -n <target> [--config FILE] [--id ID] [--title TITLE] [--summary SUMMARY] [--slug SLUG] [--channel C] [--version V] [--language L] [--operation ID]... | scaffold <template> <config> <target> --id ID --title TITLE --summary SUMMARY --slug SLUG | config validate|resolve|graph <config> | config explain <key> <config> | operation inspect <id> <config> [--channel C --version V --language L] | api audit <openapi-file> | api focused-audit <site-directory> | api review <config-file> --output <local-directory> | api select <api-id> <config> --output <selection.yaml> | api materialize <api-id> <config> (--all | --operation ID | --route "METHOD /path")... [--output content/subdirectory]');
+        throw new Error('Usage: shoalrun init [directory] [--starter minimal|api-docs|showcase] | build [config] [output] [--source-commit SHA] [--release-label LABEL] | check [config] [--json] | audit [config] | vercel build [config] [output] [--source-commit SHA] [--release-label LABEL] [--chat] | serve <site-directory> [--host HOST] [--port PORT] [--search [--config FILE]] [--ask [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]...] | search <site-directory> <query> [--product P] [--channel C --version V --language L --limit N] | answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]... | chat pause|resume|status --config FILE | ask-log <log-file> [--min-repeats N] [--limit N] [--cards-out FILE] [--json] | ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--product P] [--channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json] | eval prepare <site-directory> --tasks FILE --out REPORT | eval check <site-directory> --tasks FILE --report REPORT | index <site-directory> [--embed [--config FILE] [--provider voyage|openai] [--model MODEL] [--dimension N] [--base-url URL] [--key-env NAME]] | ingredient draft --spec FILE --out FILE [--config FILE] [--check] | recipe draft --spec FILE --out FILE [--config FILE] [--check] | scaffold <template> -n <target> [--config FILE] [--id ID] [--title TITLE] [--summary SUMMARY] [--slug SLUG] [--product P] [--channel C] [--version V] [--language L] [--operation ID]... | scaffold <template> <config> <target> --id ID --title TITLE --summary SUMMARY --slug SLUG | config validate|resolve|graph <config> | config explain <key> <config> | operation inspect <id> <config> [--product P] [--channel C --version V --language L] | api audit <openapi-file> | api focused-audit <site-directory> | api review <config-file> --output <local-directory> | api select <api-id> <config> --output <selection.yaml> | api materialize <api-id> <config> (--all | --operation ID | --route "METHOD /path")... [--output content/subdirectory]');
     }
 }
 catch (error) {

package/dist/compiler-config.d.ts

@@ -39,6 +39,14 @@ export interface CompilerSiteConfig extends ConfigMapping {
     basePath?: unknown;
     contentDir?: string;
 }
+export type ProductPublicationConfig = {
+    label?: string;
+    pathPrefix: string;
+    defaultVersion: string;
+    versions: Record<string, {
+        pathPrefix?: string;
+    }>;
+};
 export interface CompilerPublicationsConfig extends ConfigMapping {
     channels: Record<string, {
         pathPrefix?: string;
@@ -46,7 +54,9 @@ export interface CompilerPublicationsConfig extends ConfigMapping {
     versions: Record<string, {
         pathPrefix?: string;
     }>;
+    products?: Record<string, ProductPublicationConfig>;
     defaults?: {
+        product?: string;
         channel?: string;
         version?: string;
         language?: string;
@@ -66,3 +76,10 @@ export declare function navigationCounts(outputs: unknown): boolean;
  */
 export declare function requireSiteSection(config: ResolvedCompilerConfig): CompilerSiteConfig;
 export declare function requirePublicationsSection(config: ResolvedCompilerConfig): CompilerPublicationsConfig;
+/** Resolve product-local defaults without borrowing another product's catalog. */
+export declare function resolvePublication(publications: CompilerPublicationsConfig, value: Record<string, unknown>, language?: string): {
+    product?: string;
+    channel: string;
+    version: string;
+    language: string;
+};