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

package/dist/authoring-validation-command.js

@@ -21,11 +21,13 @@ export async function runValidationCommand(command, args, discoverConfig) {
                 options.runConfiguredChecks = true;
                 continue;
             }
-            const allowed = command === 'baseline' ? ['--config', '--out'] : command === 'validate' ? ['--config', '--file', '--id', '--baseline', '--artifacts'] : [];
+            const allowed = command === 'baseline' ? ['--config', '--out', '--profile'] : command === 'validate' ? ['--config', '--file', '--id', '--baseline', '--artifacts', '--profile'] : [];
             const value = args[++index];
             if (!allowed.includes(flag) || !value || value.startsWith('--'))
                 throw new SnapshotError('invalid_input', `Unknown option or missing value for ${flag}`);
-            if (flag === '--config')
+            if (flag === '--profile')
+                options.profile = value;
+            else if (flag === '--config')
                 config = value;
             else if (flag === '--out')
                 output = value;
@@ -42,7 +44,7 @@ export async function runValidationCommand(command, args, discoverConfig) {
             throw new SnapshotError('invalid_input', `Unexpected arguments for docs ${command}`);
         if (command === 'baseline' && !output)
             throw new SnapshotError('invalid_input', 'Usage: shoalrun docs baseline --out FILE [--config FILE]');
-        const result = command === 'validation-status' ? await authoringValidationStatus(positional[0]) : command === 'baseline' ? await writeAuthoringBaseline(config ?? await discoverConfig(), output) : await validateAuthoringChanges(config ?? await discoverConfig(), options);
+        const result = command === 'validation-status' ? await authoringValidationStatus(positional[0]) : command === 'baseline' ? await writeAuthoringBaseline(config ?? await discoverConfig(), output, { profile: options.profile }) : await validateAuthoringChanges(config ?? await discoverConfig(), options);
         process.stdout.write(JSON.stringify(result) + '\n');
         if (result.status !== 'ok')
             process.exitCode = 1;

package/dist/authoring-validation.d.ts

@@ -1,6 +1,7 @@
 import { type ValidationFinding } from './authoring-findings.js';
 import { type SnapshotCapture, type SnapshotInput } from './authoring-snapshot.js';
 export type ValidationOptions = {
+    profile?: string;
     files?: string[];
     ids?: string[];
     baselineFile?: string;
@@ -15,6 +16,7 @@ export type ValidationCheck = {
     findings?: number;
 };
 export type ValidationReport = {
+    profile?: SnapshotCapture['profile'];
     schemaVersion: 1;
     kind: 'shoalrun-authoring-validation';
     status: 'ok' | 'failed' | 'incomplete' | 'unavailable' | 'stale';

package/dist/authoring-validation.js

@@ -13,7 +13,7 @@ import { auditReference } from './reference-audit.js';
 import { iconLicenseFile } from './icons.js';
 import { parseAuditSettings, runAuditTest } from './audit.js';
 import { configFindingLocation, validationFinding } from './authoring-findings.js';
-import { authoringArtifactPath, captureSnapshotInputs, collectSnapshotInputs, confirmSnapshotInputs, excludedNames, isWithin, parseAuthoringBaseline, relativeInput, sha256, SnapshotError, validatorInputs } from './authoring-snapshot.js';
+import { authoringArtifactPath, captureSnapshotInputs, collectSnapshotInputs, confirmSnapshotInputs, excludedNames, isWithin, parseAuthoringBaseline, relativeInput, sha256, SnapshotError, validatorInputs, validateProfileCapture, readProfileInput } from './authoring-snapshot.js';
 const framework = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 // Include ordinary hoisted dependency locations in installed npm packages too.
 const checkModulePaths = (createRequire(import.meta.url).resolve.paths('yaml') ?? []).filter(directory => path.basename(directory) === 'node_modules').join(path.delimiter);
@@ -59,7 +59,7 @@ export async function validateAuthoringChanges(configFile, options) {
 // Internal injection boundary for deterministic capture/check race fixtures.
 export async function validateAuthoringChangesWithHooks(configFile, options, hooks = {}) {
     checkedOptions(options);
-    const capture = await captureSnapshotInputs(configFile);
+    const capture = await captureSnapshotInputs(configFile, { profile: options.profile });
     const runtime = await validatorInputs();
     let baseline = { kind: 'explicit-declaration' };
     const previous = new Map();
@@ -67,20 +67,41 @@ export async function validateAuthoringChangesWithHooks(configFile, options, hoo
         const raw = await readFile(options.baselineFile);
         const value = parseAuthoringBaseline(JSON.parse(raw.toString('utf8')), capture.root, capture.config);
         baseline = { kind: 'task-baseline', file: await realpath(options.baselineFile), digest: sha256(raw) };
+        if (value.profile?.file !== capture.profile?.file)
+            throw new SnapshotError('invalid_input', 'Baseline and validation must use the same deployment profile path');
+        // Retain previously declared profile assets just like other baseline
+        // dependencies, even when a profile no longer references an extant file.
+        for (const [file, source] of Object.entries(value.profile?.sources ?? {})) {
+            if (!capture.profile || Object.hasOwn(capture.profile.sources, file))
+                continue;
+            const input = await readProfileInput(source).catch(error => { if (error.code === 'ENOENT')
+                return undefined; throw error; });
+            if (!input)
+                continue;
+            capture.profile.sources[file] = source;
+            capture.inputs.push({ file, digest: input.digest, mode: input.mode });
+            capture.buffers.set(file, input.bytes);
+        }
+        capture.inputs.sort((a, b) => a.file.localeCompare(b.file));
         for (const input of value.inputs)
             previous.set(input.file, input);
         // A dependency removed from config is not necessarily a deleted file. Retain
         // baseline scope for extant sibling inputs so change classification is honest.
         const oldExternal = [];
         for (const input of value.inputs)
-            if ((!isWithin(capture.root, path.resolve(capture.root, input.file)) || input.file.split(path.sep).includes('node_modules')) && await stat(relativeInput(capture.root, input.file)).then(() => true, () => false))
+            if (!Object.hasOwn(capture.profile?.sources ?? {}, input.file) && (!isWithin(capture.root, path.resolve(capture.root, input.file)) || input.file.split(path.sep).includes('node_modules')) && await stat(relativeInput(capture.root, input.file)).then(() => true, () => false))
                 oldExternal.push(input.file);
         const oldDirectories = [];
         for (const directory of value.externalDirectories)
             if (await stat(relativeInput(capture.root, directory)).then(() => true, () => false))
                 oldDirectories.push(directory);
         const combinedDirectories = [...new Set([...capture.externalDirectories, ...oldDirectories])].sort();
-        const combined = await collectSnapshotInputs(capture.root, [...new Set([...oldExternal, ...capture.inputs.filter(input => (!isWithin(capture.root, path.resolve(capture.root, input.file)) || input.file.split(path.sep).includes('node_modules'))).map(input => input.file)])], combinedDirectories);
+        const combined = await collectSnapshotInputs(capture.root, [...new Set([...oldExternal, ...capture.inputs.filter(input => !Object.hasOwn(capture.profile?.sources ?? {}, input.file) && (!isWithin(capture.root, path.resolve(capture.root, input.file)) || input.file.split(path.sep).includes('node_modules'))).map(input => input.file)])], combinedDirectories);
+        for (const input of capture.inputs.filter(input => Object.hasOwn(capture.profile?.sources ?? {}, input.file))) {
+            combined.inputs.push(input);
+            combined.buffers.set(input.file, capture.buffers.get(input.file));
+        }
+        combined.inputs.sort((a, b) => a.file.localeCompare(b.file));
         for (const input of capture.inputs)
             if (combined.inputs.find(current => current.file === input.file)?.digest !== input.digest)
                 throw new SnapshotError('stale_input', `Input changed while comparing the task baseline: ${input.file}`);
@@ -90,7 +111,7 @@ export async function validateAuthoringChangesWithHooks(configFile, options, hoo
     // Loading configuration is read-only. Compilation and executable extensions
     // are never run on the original project.
     try {
-        loaded = await loadConfig(path.join(capture.root, capture.config));
+        loaded = await loadConfig(path.join(capture.root, capture.config), { profile: options.profile });
     }
     catch { /* Snapshot compiler diagnoses invalid YAML/config. */ }
     const contentDir = path.resolve(capture.root, String(loaded?.value.site?.contentDir ?? 'content'));
@@ -147,7 +168,7 @@ export async function validateAuthoringChangesWithHooks(configFile, options, hoo
         await mkdir(directory);
     }
     const tree = path.join(directory, 'tree'), shadow = path.join(tree, path.basename(capture.root)), site = path.join(directory, 'site');
-    const report = { schemaVersion: 1, kind: 'shoalrun-authoring-validation', status: 'incomplete', snapshotId, project: capture.root, config: capture.config, baseline, changed, inputs: capture.inputs, excluded: capture.excluded, externalDirectories: capture.externalDirectories, contentDigest, configDigest: capture.configDigest, validatorDigest: runtime.digest, runtimeDependencies: [], dependencies: [], checks: [], findings: [],
+    const report = { profile: capture.profile, schemaVersion: 1, kind: 'shoalrun-authoring-validation', status: 'incomplete', snapshotId, project: capture.root, config: capture.config, baseline, changed, inputs: capture.inputs, excluded: capture.excluded, externalDirectories: capture.externalDirectories, contentDigest, configDigest: capture.configDigest, validatorDigest: runtime.digest, runtimeDependencies: [], dependencies: [], checks: [], findings: [],
         coverage: { scope: 'complete-captured-project', authored, affected, rendered: [], notRendered: [...affected] },
         artifacts: { directory, project: shadow, site, report: path.join(directory, 'report.json'), digest: null, lifecycle: 'Retained local validation artifacts. Remove this artifact directory when finished; it is separate from working-tree source. No preview service is started.' },
         freshness: { current: true, checkedAt: new Date().toISOString() } };
@@ -175,7 +196,8 @@ export async function validateAuthoringChangesWithHooks(configFile, options, hoo
         if (!await confirmSnapshotInputs(capture) || !await absentInputsUnchanged())
             throw new SnapshotError('stale_input', 'Working tree changed during snapshot capture; retry validation.');
         const stagedConfig = path.join(shadow, capture.config);
-        loaded = await loadConfig(stagedConfig);
+        const stagedProfile = capture.profile ? path.resolve(shadow, capture.profile.file) : undefined;
+        loaded = await loadConfig(stagedConfig, { profile: stagedProfile });
         if (capture.configDigest && loaded.digest !== capture.configDigest)
             throw new SnapshotError('stale_input', 'Captured configuration does not match the inspected configuration; retry.');
         // Local executable metadata/highlighting modules are not a provider-free
@@ -198,7 +220,7 @@ export async function validateAuthoringChangesWithHooks(configFile, options, hoo
                 }
             }
             try {
-                const manifest = await compile(stagedConfig, site, {}, { authoringFiles: new Set(affected.map(file => path.join(shadow, file))) });
+                const manifest = await compile(stagedConfig, site, {}, { profile: stagedProfile, authoringFiles: new Set(affected.map(file => path.join(shadow, file))) });
                 report.dependencies = manifest.dependencies.map(file => isWithin(tree, file) ? path.relative(shadow, file) : file);
                 for (const dependency of manifest.dependencies) {
                     if (isWithin(tree, dependency)) {
@@ -212,8 +234,12 @@ export async function validateAuthoringChangesWithHooks(configFile, options, hoo
                 }
                 report.coverage.rendered = (manifest.authoringSources ?? []).map(doc => ({ id: doc.id, file: path.relative(shadow, doc.file), route: doc.url, markdown: doc.markdownUrl }));
                 report.coverage.notRendered = affected.filter(file => !report.coverage.rendered.some(doc => doc.file === file));
-                for (const file of report.coverage.notRendered)
-                    report.findings.push({ ...finding('validation.excluded-page', 'This affected authored page did not render in any enabled publication.', 'Correct its publication/locale selection or enable an isolated review publication and validate again.'), file });
+                for (const file of report.coverage.notRendered) {
+                    const profileExcluded = manifest.profileSelection?.decisions.some(decision => !decision.included && decision.id.startsWith(path.join(shadow, file) + ': '));
+                    report.findings.push(profileExcluded
+                        ? { ...finding('validation.profile-excluded', 'This affected page is excluded from the selected deployment edition; its rendered content was not checked.', 'Validate a profile/publication that includes this page before accepting changes to its content.', 'warning'), file }
+                        : { ...finding('validation.excluded-page', 'This affected authored page did not render in any enabled publication.', 'Correct its publication/locale selection or enable an isolated review publication and validate again.'), file });
+                }
                 report.checks.push({ id: 'compile', status: 'passed', documents: manifest.documents.length });
                 const settings = parseAuditSettings(config.audit);
                 if (settings.links) {
@@ -324,6 +350,7 @@ export async function readValidationReport(reportFile) {
         throw new SnapshotError('invalid_input', 'Expected a version-1 authoring validation report');
     if (!report.baseline || !report.coverage || !Array.isArray(report.coverage.rendered) || !Array.isArray(report.coverage.affected) || !Array.isArray(report.coverage.notRendered) || !Array.isArray(report.checks) || !Array.isArray(report.findings) || !report.artifacts || !report.freshness || typeof report.project !== 'string' || !path.isAbsolute(report.project) || typeof report.snapshotId !== 'string' || !/^[a-f0-9]{64}$/.test(report.snapshotId))
         throw new SnapshotError('invalid_input', 'Malformed authoring validation report');
+    validateProfileCapture(report.project, report.profile);
     for (const input of report.inputs)
         relativeInput(report.project, input.file);
     return report;
@@ -335,7 +362,7 @@ export async function authoringValidationStatus(reportFile) {
     for (const input of report.changed)
         if (input.digest === null && await stat(relativeInput(report.project, input.file)).then(() => true, () => false))
             missingInputCreated = true;
-    const changed = missingInputCreated || sha256(JSON.stringify(report.inputs)) !== report.contentDigest || !await confirmSnapshotInputs({ root: report.project, inputs: report.inputs, externalDirectories: report.externalDirectories });
+    const changed = missingInputCreated || sha256(JSON.stringify(report.inputs)) !== report.contentDigest || !await confirmSnapshotInputs({ root: report.project, inputs: report.inputs, externalDirectories: report.externalDirectories, profile: report.profile });
     const runtime = await validatorInputs();
     let baselineChanged = false, dependencyChanged = false;
     if (report.baseline.file)

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] [--section pages|guidance|configuration|navigation|relationships|templates|findings]\n  source FILE [--config FILE]\n  context <document-id> [--config FILE]\n\nValidate and preview edits:\n  baseline --out FILE [--config FILE]\n  validate (--baseline FILE | --file FILE | --id ID) [--config 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\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]\n  export [config] --out DIRECTORY [--target NAME]\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]\n  docs baseline --out FILE [--config FILE]\n  docs validate (--baseline FILE | --file FILE | --id ID) [--config 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] [--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 function runSkillsCommand(args: string[]): Promise<string>;

package/dist/cli-discovery.js

@@ -9,13 +9,13 @@ Read bundled references (no project or provider key required):
   read <document-id> [--json]
 
 Inspect a project:
-  project [--config FILE] [--section pages|guidance|configuration|navigation|relationships|templates|findings]
-  source FILE [--config FILE]
+  project [--config FILE] [--profile FILE] [--section pages|guidance|configuration|navigation|relationships|templates|findings]
+  source FILE [--config FILE] [--profile FILE]
   context <document-id> [--config FILE]
 
 Validate and preview edits:
-  baseline --out FILE [--config FILE]
-  validate (--baseline FILE | --file FILE | --id ID) [--config FILE]
+  baseline --out FILE [--config FILE] [--profile FILE]
+  validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]
   validation-status REPORT
   review REPORT [--format json|markdown]
   preview REPORT [--port PORT]
@@ -33,8 +33,8 @@ export const cliHelp = `Usage: shoalrun <command>
 
 Start and build:
   init [directory] [--starter minimal|api-docs|showcase]
-  build [config] [output]
-  export [config] --out DIRECTORY [--target NAME]
+  build [config] [output] [--profile FILE]
+  export [config] --out DIRECTORY [--target NAME] [--profile FILE]
   dev [config] [output] [--port PORT]
   serve <site-directory> [--host HOST] [--port PORT]
   check [config] [--json]
@@ -46,9 +46,9 @@ Agent guidance and offline documentation:
   skills read <name> [--json]
   docs search <query> [--json]
   docs read <document-id> [--json]
-  docs project [--config FILE]
-  docs baseline --out FILE [--config FILE]
-  docs validate (--baseline FILE | --file FILE | --id ID) [--config FILE]
+  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]
   docs review REPORT [--format json|markdown]
   docs preview REPORT [--port PORT]
 

package/dist/cli.js

@@ -73,7 +73,7 @@ function buildArguments(args, defaultOutput) {
             positional.push(value);
             continue;
         }
-        if (!['--source-commit', '--release-label'].includes(value))
+        if (!['--source-commit', '--release-label', '--profile'].includes(value))
             throw new Error(`Unknown build option ${value}`);
         if (flags[value] !== undefined)
             throw new Error(`Duplicate build option ${value}`);
@@ -84,7 +84,7 @@ function buildArguments(args, defaultOutput) {
     }
     if (positional.length > 2)
         throw new Error('Build accepts at most a config and output directory');
-    return { config: positional[0] ?? 'docs.config.yaml', output: positional[1] ?? defaultOutput, provenance: { sourceCommit: flags['--source-commit'], releaseLabel: flags['--release-label'] } };
+    return { profile: flags['--profile'], config: positional[0] ?? 'docs.config.yaml', output: positional[1] ?? defaultOutput, provenance: { sourceCommit: flags['--source-commit'], releaseLabel: flags['--release-label'] } };
 }
 // An unset or empty PORT means the default; serveSite rejects anything else that is not a port number.
 const defaultPort = () => process.env.PORT?.trim() ? Number(process.env.PORT) : 8765;
@@ -134,8 +134,8 @@ try {
         }
     }
     else if (command === 'build') {
-        const { config, output, provenance } = buildArguments([subcommand, ...rest].filter((item) => item !== undefined), 'site-dist');
-        const manifest = await compile(config, output, provenance);
+        const { config, output, provenance, profile } = buildArguments([subcommand, ...rest].filter((item) => item !== undefined), 'site-dist');
+        const manifest = await compile(config, output, provenance, { profile });
         process.stdout.write(JSON.stringify({ status: 'ok', documents: manifest.documents.length, operations: Object.keys(manifest.operations).length }, null, 2) + '\n');
     }
     else if (command === 'dev') {
@@ -160,8 +160,10 @@ try {
     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.
         const chat = rest.includes('--chat');
-        const { config, output, provenance } = buildArguments(rest.filter(item => item !== '--chat'), '.vercel/output');
-        const result = await buildVercel(config, output, provenance, { chat });
+        const { config, output, provenance, profile } = buildArguments(rest.filter(item => item !== '--chat'), '.vercel/output');
+        if (profile && chat)
+            throw new Error('Profiled Vercel builds do not support --chat yet; build the selected static edition without --chat');
+        const result = await buildVercel(config, output, provenance, { chat, profile });
         // Asking for the chat and not getting it must fail the deploy. Otherwise a site would look ready and have no chat.
         if (chat && result.chat && !result.chat.added)
             throw new Error(`The chat was requested but not added: ${result.chat.reason}`);
@@ -236,7 +238,7 @@ try {
                 embedQuery = async (query, signal) => (await provider.embed([query], 'query', signal))[0];
             }
             extras = { search: createSearchHandler({ retriever, embedQuery, hosts, readerFilters: validateReaderFilters(settings.readerFilters), pageSummaries }) };
-            banner = `Search is on: ${embeddings ? 'hybrid retrieval' : 'lexical retrieval; run shoalrun index --embed for semantic results'}.\n`;
+            banner = `Search is on: ${embeddings ? 'semantic retrieval' : 'lexical retrieval; run shoalrun index --embed for semantic results'}.\n`;
         }
         if (ask) {
             // The preview spends your API credits on every question, so it answers only on this machine.
@@ -423,7 +425,11 @@ try {
             const provider = createProvider(embeddingProviderConfig(retrieval, { provider: values['--provider'], model: values['--model'], dimension: values['--dimension'] === undefined ? undefined : Number(values['--dimension']), baseUrl: values['--base-url'], keyEnv: values['--key-env'] }));
             embeddings = await embedChunkIndex(subcommand, result.index, provider, embeddingInput);
         }
-        process.stdout.write(JSON.stringify({ status: 'ok', documents: result.documents, chunks: result.index.chunks.length, output: result.output, ...(embeddings ? { embeddings } : {}) }, null, 2) + '\n');
+        const counts = new Map();
+        for (const chunk of result.index.chunks)
+            counts.set(chunk.variant, (counts.get(chunk.variant) ?? 0) + 1);
+        const publications = [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([variant, passages]) => ({ variant, passages }));
+        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]';

package/dist/compiler.d.ts

@@ -10,6 +10,7 @@ export declare function compile(configFile: string, destination?: string, proven
     apiReview?: 'report';
     sourceOverrides?: ReadonlyMap<string, string>;
     authoringFiles?: ReadonlySet<string>;
+    profile?: string;
 }): Promise<{
     authoringSources?: {
         id: string;
@@ -36,6 +37,18 @@ export declare function compile(configFile: string, destination?: string, proven
             }>;
         }>;
     }[];
+    profileSelection: {
+        schemaVersion: number;
+        profileDigest: string;
+        features: string[];
+        provenance: Record<string, string[]>;
+        decisions: {
+            kind: "page" | "section";
+            id: string;
+            included: boolean;
+            requires?: import("./deployment-profile.js").FeatureRequirements;
+        }[];
+    } | undefined;
     documents: ({
         digest: string;
         markdownBytes: number;

package/dist/compiler.js

@@ -1,3 +1,6 @@
+import { validateHeader, validateFooter } from './site-identity.js';
+import { profileSelection } from './deployment-profile.js';
+import { profileNavigation } from './project-navigation.js';
 import { canonical, checkOutputDirectory } from './output-location.js';
 import { reviewApiPublication } from './api-publication-review.js';
 import { prepareContentWorkspace } from './content-workspace.js';
@@ -63,6 +66,8 @@ function validateSearch(value, declaringFile) {
         return { provider, index: false };
     if (provider === 'lexical')
         return { provider, module: builtInSearchProvider, index: true };
+    if (provider === 'semantic')
+        return { provider, module: path.resolve(path.dirname(builtInSearchProvider), 'search-semantic.js'), index: true };
     if (provider !== 'custom')
         throw new Error(`Unknown search provider ${provider}`);
     if (typeof config.module !== 'string' || !/\.m?js$/.test(config.module))
@@ -74,75 +79,6 @@ function validateSearch(value, declaringFile) {
 const builtInSearchProvider = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../assets/search-lexical.js');
 // Each shape preset has a default palette; palettes live in styles/themes/palettes.
 export const themePresets = Object.fromEntries(presetCatalog.map(preset => [preset.name, preset.palette]));
-function validateHeader(value) {
-    if (value === undefined)
-        return { links: [] };
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        throw new Error('site.header must be a mapping');
-    const { links = [], ...extra } = value;
-    if (Object.keys(extra).length)
-        throw new Error(`site.header does not accept ${Object.keys(extra).join(', ')}`);
-    if (!Array.isArray(links))
-        throw new Error('site.header.links must be a list');
-    return {
-        links: links.map((link, index) => {
-            const where = `site.header.links[${index}]`;
-            const { style = 'link', ...rest } = (link && typeof link === 'object' && !Array.isArray(link) ? link : {});
-            const checked = validateSiteLink(link, where, rest);
-            if (style !== 'link' && style !== 'button' && style !== 'primary')
-                throw new Error(`${where}.style must be link, button, or primary`);
-            return { ...checked, style };
-        })
-    };
-}
-// Header and footer links share one rule: a label and a site path, http(s) URL, or mailto link.
-function validateSiteLink(link, where, fields = link) {
-    if (!link || typeof link !== 'object' || Array.isArray(link))
-        throw new Error(`${where} must be a mapping`);
-    const { label, href, ...rest } = fields;
-    if (Object.keys(rest).length)
-        throw new Error(`${where} does not accept ${Object.keys(rest).join(', ')}`);
-    if (typeof label !== 'string' || !label.trim())
-        throw new Error(`${where}.label is required`);
-    if (typeof href !== 'string' || !/^(\/|https?:\/\/|mailto:)/.test(href))
-        throw new Error(`${where}.href must be a site path, http(s) URL, or mailto link`);
-    return { label, href };
-}
-function validateFooter(value) {
-    if (value === undefined)
-        return undefined;
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        throw new Error('site.footer must be a mapping');
-    const { columns = [], links = [], text, ...extra } = value;
-    if (Object.keys(extra).length)
-        throw new Error(`site.footer does not accept ${Object.keys(extra).join(', ')}`);
-    if (!Array.isArray(columns))
-        throw new Error('site.footer.columns must be a list');
-    if (!Array.isArray(links))
-        throw new Error('site.footer.links must be a list');
-    if (text !== undefined && (typeof text !== 'string' || !text.trim()))
-        throw new Error('site.footer.text must be non-empty text');
-    const footer = {
-        columns: columns.map((column, index) => {
-            const where = `site.footer.columns[${index}]`;
-            if (!column || typeof column !== 'object' || Array.isArray(column))
-                throw new Error(`${where} must be a mapping`);
-            const { title, links: columnLinks, ...rest } = column;
-            if (Object.keys(rest).length)
-                throw new Error(`${where} does not accept ${Object.keys(rest).join(', ')}`);
-            if (typeof title !== 'string' || !title.trim())
-                throw new Error(`${where}.title is required`);
-            if (!Array.isArray(columnLinks) || !columnLinks.length)
-                throw new Error(`${where}.links must list at least one link`);
-            return { title, links: columnLinks.map((link, linkIndex) => validateSiteLink(link, `${where}.links[${linkIndex}]`)) };
-        }),
-        links: links.map((link, index) => validateSiteLink(link, `site.footer.links[${index}]`)),
-        ...(typeof text === 'string' ? { text } : {})
-    };
-    if (!footer.columns.length && !footer.links.length && !footer.text)
-        throw new Error('site.footer needs columns, links, or text');
-    return footer;
-}
 const contrastFailuresFor = (palette, modes, calloutTypes, badgeVariants) => {
     const customTones = new Map([...calloutTypes.values()].flatMap(type => type.colors ? [[type.tone, type.colors]] : []));
     return [...contrastProblems(palette, modes), ...calloutToneProblems(customTones, palette, modes), ...badgeContrastProblems(badgeVariants, palette, modes)];
@@ -165,7 +101,7 @@ export async function checkThemeContrast(configFile) {
     return { modes, palette: palette.name };
 }
 export async function compile(configFile, destination, provenance = {}, options = {}) {
-    const loaded = await loadConfig(configFile);
+    const loaded = await loadConfig(configFile, { profile: options.profile });
     const componentPlugins = await loadComponentPlugins(loaded);
     const provenanceRecord = buildInfo(loaded.digest, provenance);
     const resolvedConfig = resolvedCompilerConfig(loaded.value);
@@ -246,6 +182,10 @@ export async function compile(configFile, destination, provenance = {}, options
     if (faviconFile && !existsSync(faviconFile))
         throw new Error(`site.favicon: file not found: ${faviconFile}`);
     const faviconRoute = publicPath(faviconFile?.toLowerCase().endsWith('.png') ? '/favicon.png' : '/favicon.svg');
+    if (config.site.logo !== undefined && (typeof config.site.logo !== 'string' || !/\.(?:svg|png)$/i.test(config.site.logo)))
+        throw new Error('site.logo must be a local .svg or .png file');
+    const logoFile = config.site.logo === undefined ? undefined : path.resolve(path.dirname(explainSegments(loaded, ['site', 'logo']).source.file), config.site.logo);
+    const logoRoute = logoFile ? publicPath(`/assets/brand-logo${path.extname(logoFile).toLowerCase()}`) : undefined;
     const shareFontFiles = [...bundledShareFonts(), ...shareImages.fonts, ...fonts.faces.map(face => face.file).filter(file => /\.(?:ttf|otf)$/i.test(file))];
     const shareCache = path.join(base, '.shoalrun/cache/share-images');
     const fontDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../styles/fonts');
@@ -353,7 +293,7 @@ export async function compile(configFile, destination, provenance = {}, options
         throw new Error('site.contentFilter matched no published pages; check page facets and enabled publications');
     let navigationSpec;
     try {
-        navigationSpec = validateProjectNavigation(config.navigation ?? [], docs, knownOperations, new Set(Object.keys(config.apis ?? {})));
+        navigationSpec = validateProjectNavigation(loaded.deployment?.context.grants && loaded.deployment.context.pruneNavigation ? profileNavigation(config.navigation ?? [], docs, knownDocumentIds, knownOperations, new Set(Object.keys(config.apis ?? {}))) : config.navigation ?? [], docs, knownOperations, new Set(Object.keys(config.apis ?? {})));
     }
     catch (error) {
         const source = config.navigation === undefined ? configFile : explain(loaded, 'navigation').source.file;
@@ -390,10 +330,20 @@ export async function compile(configFile, destination, provenance = {}, options
     };
     // Local component and Markdown images publish beside their page under /assets/pages.
     const heroImages = new Map();
+    if (logoFile && logoRoute)
+        heroImages.set(logoRoute, logoFile);
     const walkthroughSources = new Set();
+    const usedComponentAssets = new Set();
     const collectPageAssets = (value) => {
         if (!isConfigMapping(value))
             return;
+        if (value.type === 'docComponent' && isConfigMapping(value.browser)) {
+            if (typeof value.browser.moduleUrl === 'string')
+                usedComponentAssets.add(value.browser.moduleUrl);
+            for (const route of Array.isArray(value.browser.styleUrls) ? value.browser.styleUrls : [])
+                if (typeof route === 'string')
+                    usedComponentAssets.add(route);
+        }
         const image = value.image;
         if (value.type === 'docHero' && isConfigMapping(image) && typeof image.url === 'string' && typeof image.file === 'string') {
             const route = publicPath(image.url);
@@ -428,7 +378,7 @@ export async function compile(configFile, destination, provenance = {}, options
         rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes,
         basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette,
         themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload: fonts.preload,
-        shareFor, faviconRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments,
+        shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments,
         externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder
     });
     // The theme previewer and switcher re-theme pages in the browser, so every preset and palette ships only when one is used.
@@ -501,11 +451,12 @@ export async function compile(configFile, destination, provenance = {}, options
     const artifactConfig = options.authoringFiles ? { ...config, mcp: false } : config;
     const { artifacts, buildId } = await assembleArtifacts({
         base, basePath, publicPath, canonical, siteOrigin, manifest, provenanceRecord, rendered, sitemaps,
+        privateDependencies: new Set([...(loaded.deployment?.file ? [loaded.deployment.file] : []), ...(loaded.deployment?.assetFiles ?? [])]),
         diagramAssets, heroImages, focusedContracts, styleFiles, themeStyleFile, generatedPaletteCss,
         generatedBadgeCss, search, synonyms, config: artifactConfig, builtInSearchProvider, customReaderModule, analyticsModule, mcpAnalyticsModule,
         previewFiles, assetDirectory, themeSwitcher, themeDirectory, palette, colorMode, generatedFontsCss,
         fontFiles, fonts, shareImages, shareFor, themePreset, shareFontFiles, shareCache, faviconFile,
-        faviconRoute, customStyleFile, scriptFiles, componentAssets: componentPlugins.assets, redirects, apiPublications, api, catalog, headers,
+        faviconRoute, customStyleFile, scriptFiles, componentAssets: loaded.deployment?.context.grants ? componentPlugins.assets.filter(asset => usedComponentAssets.has(asset.route)) : componentPlugins.assets, redirects, apiPublications, api, catalog, headers,
         documentRoutes, readerFilters, apiSources
     });
     if (destination) {
@@ -516,10 +467,12 @@ export async function compile(configFile, destination, provenance = {}, options
             await mkdir(localGuide, { recursive: true });
             await writeFile(path.join(localGuide, 'frontmatter-reference.md'), frontmatterReference(config.frontmatter));
             await writeFile(path.join(localGuide, 'frontmatter.schema.json'), JSON.stringify(frontmatterSchema(config.frontmatter), null, 2) + '\n');
+            if (loaded.deployment?.context.grants && !options.authoringFiles)
+                await writeFile(path.join(localGuide, 'profile-selection.json'), JSON.stringify({ ...profileSelection(loaded.deployment), buildId, configDigest: loaded.digest }, null, 2) + '\n');
         });
         // Authoring captures resolve revision dates without changing captured inputs.
         if (!options.authoringFiles)
             await freshness?.commit();
     }
-    return { ...manifest, buildId, apiPublicationReview, ...(options.authoringFiles ? { authoringSources: rendered.map(({ doc }) => ({ id: doc.frontmatter.id, file: doc.file, url: doc.route, markdownUrl: doc.markdownRoute })) } : {}) };
+    return { ...manifest, buildId, apiPublicationReview, profileSelection: profileSelection(loaded.deployment), ...(options.authoringFiles ? { authoringSources: rendered.map(({ doc }) => ({ id: doc.frontmatter.id, file: doc.file, url: doc.route, markdownUrl: doc.markdownRoute })) } : {}) };
 }

package/dist/component-names.js

@@ -1 +1 @@
-export const builtinComponentNames = new Set('Anchor FrontmatterReference ForPublication ReaderSection ReaderChoice ReaderFilter Only Badge Kbd Tooltip InfoHint Progress Math ActionLink Button DefinitionList Term Definition Steps Timeline Milestone FileTree Tree Folder File Table CollapsibleGroup Collapsible Section Hero ThemePreview Diagram Image Tabs Walkthrough Step Tab Fields Field CookbookChooser DocCard DocCards DocCollection RelatedReading ApiExample ApiSchema Snippet Var DocLink Callout'.split(' '));
+export const builtinComponentNames = new Set('Anchor FrontmatterReference ForFeature ForPublication ReaderSection ReaderChoice ReaderFilter Only Badge Kbd Tooltip InfoHint Progress Math ActionLink Button DefinitionList Term Definition Steps Timeline Milestone FileTree Tree Folder File Table CollapsibleGroup Collapsible Section Hero ThemePreview Diagram Image Tabs Walkthrough Step Tab Fields Field CookbookChooser DocCard DocCards DocCollection RelatedReading ApiExample ApiSchema Snippet Var DocLink Callout'.split(' '));

package/dist/component-transform.js

@@ -1,3 +1,4 @@
+import { pruneFeatureTree } from './deployment-profile.js';
 import { lowerComponent } from './component-plugins.js';
 import { cardComponent } from './cards.js';
 import { cookbookChooserComponent } from './cookbook-chooser.js';
@@ -59,7 +60,8 @@ function literalAttributes(attributes) {
 export function transformMdx(tree, current, registry, snippets = new Map(), projectValues = {}, uses = [], calloutTypes = resolveCalloutTypes(undefined, current.file), projectRoot, readerConfig, frontmatterConfig = {}, publicationConfig, badgeVariants = resolveBadgeVariants(undefined, current.file), componentPlugins = new Map()) {
     if (!isMdxRoot(tree))
         throw new Error(`${current.file}: parsed content must be a root with children`);
-    tree = lowerSectionMarkers(tree, current.file);
+    tree = lowerSectionMarkers(pruneFeatureTree(tree, current.featureContext, current.file), current.file);
+    snippets = new Map([...snippets].map(([id, definition]) => [id, { ...definition, tree: pruneFeatureTree(definition.tree, current.featureContext, definition.file) }]));
     let pluginDepth = 0;
     let tabsIndex = 0;
     let walkthroughIndex = 0;
@@ -130,6 +132,10 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
                     throw new Error(`${sourceFile}: <FrontmatterReference> must be an empty block`);
                 return childrenOf(parsePlainMarkdown(frontmatterReference(frontmatterConfig, true)), scope, stack, sourceFile);
             }
+            if (node.name === 'ForFeature') {
+                const selected = pruneFeatureTree({ type: 'root', children: [node] }, current.featureContext, sourceFile);
+                return childrenOf(selected.children, scope, stack, sourceFile);
+            }
             if (node.name === 'ForPublication') {
                 const attributes = node.attributes ?? [];
                 const allowed = ['channel', 'version', 'language'];

package/dist/config.d.ts

@@ -8,10 +8,13 @@ type Tree = {
 };
 export declare class ConfigError extends Error {
 }
-export declare function loadConfig(file: string): Promise<{
+export declare function loadConfig(file: string, options?: {
+    profile?: string;
+}): Promise<{
     value: Record<string, unknown>;
     tree: Tree;
     dependencies: string[];
+    deployment: import("./deployment-profile.js").ProfileResolution | undefined;
     digest: string;
 }>;
 export declare function explain(config: Awaited<ReturnType<typeof loadConfig>>, key: string): {

package/dist/config.js

@@ -1,3 +1,4 @@
+import { resolveDeploymentProfile } from './deployment-profile.js';
 import { validateExports } from './content-export-config.js';
 import { validateContentFilter } from './content-filter.js';
 import { validateReaderFilters } from './reader-filters.js';
@@ -8,7 +9,7 @@ import { parseYaml } from './yaml-value.js';
 import { validateSearch } from './search-config.js';
 import { resolveTaxonomy } from './taxonomy.js';
 import { validateCookbooks } from './cookbook-chooser.js';
-const allowed = new Set(['exports', 'schemaVersion', 'site', 'navigation', 'redirects', 'apis', 'relationships', 'variables', 'snippets', 'callouts', 'badges', 'publications', 'outputs', 'templates', 'theme', 'frontmatter', 'metadata', 'audit', 'readerFilters', 'retrieval', 'chat', 'authoring', 'search', 'cookbooks', 'analytics', 'mcp', 'components']);
+const allowed = new Set(['profiles', 'exports', 'schemaVersion', 'site', 'navigation', 'redirects', 'apis', 'relationships', 'variables', 'snippets', 'callouts', 'badges', 'publications', 'outputs', 'templates', 'theme', 'frontmatter', 'metadata', 'audit', 'readerFilters', 'retrieval', 'chat', 'authoring', 'search', 'cookbooks', 'analytics', 'mcp', 'components']);
 const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const treeObject = (v) => object(v) && !('kind' in v && 'items' in v);
 export class ConfigError extends Error {
@@ -59,7 +60,7 @@ function merge(base, overlay) {
         return overlay;
     return { value: overlay.value, source: { file: overlay.source.file, history: [base.source.file, ...base.source.history] } };
 }
-export async function loadConfig(file) {
+export async function loadConfig(file, options = {}) {
     const dependencies = new Set();
     const root = path.resolve(file);
     async function read(current, stack, rootFile = false) {
@@ -113,8 +114,21 @@ export async function loadConfig(file) {
         delete local.extends;
         return merge(result, await resolve(local));
     }
-    const tree = finalize(await read(root, [], true));
-    const value = valueOf(tree);
+    let tree = finalize(await read(root, [], true));
+    let value = valueOf(tree);
+    if (!object(value) || value.schemaVersion !== 1)
+        throw new ConfigError(`${root}: schemaVersion must be 1`);
+    const raw = value;
+    const profileSettings = treeObject(tree.value) ? tree.value.profiles : undefined;
+    const manifestNode = profileSettings && treeObject(profileSettings.value) ? profileSettings.value.manifest : undefined;
+    const deployment = await resolveDeploymentProfile(raw.profiles, raw, manifestNode?.source.file ?? root, options.profile);
+    if (deployment) {
+        for (const file of deployment.dependencies)
+            dependencies.add(file);
+        const node = (value) => ({ source: { file: deployment.file ?? root, history: [] }, value: Array.isArray(value) ? value.map(node) : object(value) ? Object.fromEntries(Object.entries(value).map(([key, child]) => [key, node(child)])) : value });
+        tree = finalize(merge(tree, node(deployment.overlay)));
+        value = valueOf(tree);
+    }
     if (!object(value) || value.schemaVersion !== 1)
         throw new ConfigError(`${root}: schemaVersion must be 1`);
     for (const key of Object.keys(value))
@@ -128,7 +142,7 @@ export async function loadConfig(file) {
     resolveTaxonomy(object(value.frontmatter) ? value.frontmatter.taxonomy : undefined);
     if (object(value.publications) && ((object(value.publications.defaults) && Object.hasOwn(value.publications.defaults, 'locale')) || (Array.isArray(value.publications.enabled) && value.publications.enabled.some(item => object(item) && Object.hasOwn(item, 'locale')))))
         throw new ConfigError(`${root}: publications.locale is now publications.language; page locale is reserved for formatting conventions`);
-    return { value, tree, dependencies: [...dependencies].sort(), digest: createHash('sha256').update(JSON.stringify(value)).digest('hex') };
+    return { value, tree, dependencies: [...dependencies].sort(), deployment, digest: createHash('sha256').update(JSON.stringify(deployment ? [value, deployment.digest] : value)).digest('hex') };
 }
 export function explain(config, key) {
     return explainSegments(config, key.split('.'));