@shoalrun/cli 0.1.0-alpha.13 → 0.1.0-alpha.15

package/agent-docs/start.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
@@ -36,7 +36,7 @@ Install an exact version of the alpha and initialize the minimal starter:
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.14
 npx --no-install shoalrun init .
 ```
 

package/agent-docs/start.sections/add-the-page-to-navigation.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/build-and-check-both-outputs.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/build-this-site.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/check-writing-style.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/create-a-page.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/make-it-yours.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/migrating-from-github-packages.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/prerequisites.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/related-reading.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/start-your-own-project.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -38,7 +38,7 @@ Install an exact version of the alpha and initialize the minimal starter:
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.14
 npx --no-install shoalrun init .
 ```
 

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

@@ -30,6 +30,8 @@ type ApiDefinition = {
         id: string;
         reference: string;
         sourceOperationId?: string;
+        shared?: unknown;
+        requires?: unknown;
     }>;
     generateReferences?: boolean | {
         pathPrefix?: string;
@@ -60,6 +62,7 @@ export declare function materializeApiReferences({ config, loaded, variants, doc
     allowRouteCollisions?: boolean;
 }): Promise<{
     api: ApiReader;
+    operationRequirements: Map<string, unknown>;
     queryRules: Map<string, import("./api.js").QuerySyntaxRule[]>;
     lifecycleMappings: Map<string, {
         from: string;

package/dist/api-publication-plan.js

@@ -1,3 +1,4 @@
+import { matchesFeatures, validateFeatureClassification } from './deployment-profile.js';
 import { matchesContentFilter } from './content-filter.js';
 import path from 'node:path';
 import { ApiReader, querySyntaxRules } from './api.js';
@@ -37,6 +38,14 @@ function validatedApiDefinitions(value) {
 }
 export async function materializeApiReferences({ config, loaded, variants, docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, basePath, readerFilters, contentFilter, allowRouteCollisions }) {
     const definitions = validatedApiDefinitions(config.apis);
+    for (const [id, definition] of Object.entries(definitions)) {
+        validateFeatureClassification(definition, loaded.deployment ? { ...loaded.deployment.context, requireClassification: false } : undefined, `API ${id}`);
+        for (const operation of definition.operations ?? [])
+            validateFeatureClassification(operation, loaded.deployment ? { ...loaded.deployment.context, requireClassification: false } : undefined, `Operation ${operation.id}`);
+        if (loaded.deployment?.context.grants && [definition.source, ...(definition.publications ?? []).map(entry => entry.source)].some(source => source?.publish === true))
+            throw new Error(`API ${id}: profiled builds cannot publish a full OpenAPI source; use focused contracts (source.publish: false, source.focused: true)`);
+    }
+    const operationRequirements = new Map();
     const api = new ApiReader();
     const queryRules = new Map(Object.entries(definitions).map(([id, definition]) => [id, querySyntaxRules(definition.querySyntax)]));
     const lifecycleMappings = new Map();
@@ -108,7 +117,7 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
             explicit.add(operation.sourceOperationId);
         }
         definition.operations ??= [];
-        for (const variant of variants) {
+        for (const variant of loaded.deployment?.context.classificationPublications ?? variants) {
             const binding = sourceForVariant(apiId, definition, variant);
             if (!binding)
                 continue;
@@ -147,7 +156,21 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
                             knownOperations.set(id, { apiId, reference });
                             definition.operations.push({ id, sourceOperationId, reference });
                         }
-                        if (!selected)
+                        if (selected) {
+                            knownDocumentIds.add(reference);
+                            knownDocumentTypes.set(reference, 'api-reference');
+                        }
+                        const requirements = isConfigMapping(operation) ? operation['x-shoalrun-requires'] : undefined;
+                        const shared = isConfigMapping(operation) ? operation['x-shoalrun-shared'] : undefined;
+                        if (selected) {
+                            const classification = requirements !== undefined || shared !== undefined ? { requires: requirements, shared } : definition;
+                            validateFeatureClassification(classification, loaded.deployment?.context, `${binding.file}: ${sourceOperationId} (generated reference)`);
+                        }
+                        if (!variants.some(item => item.channel === variant.channel && item.version === variant.version && item.language === variant.language))
+                            continue;
+                        operationRequirements.set(keyFor(id, variant), requirements);
+                        const featureSelected = matchesFeatures(requirements, loaded.deployment?.context, `${binding.file}: ${sourceOperationId}`) && matchesFeatures(definition.requires, loaded.deployment?.context, `API ${apiId}`);
+                        if (!selected || !featureSelected)
                             continue;
                         const page = resolveFrontmatter({
                             id: reference, title: String(isConfigMapping(operation) && operation.summary || `${webhook ? 'Webhook' : method.toUpperCase()} ${route}`),
@@ -158,6 +181,8 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
                         validateFrontmatter(page, config.frontmatter, binding.file);
                         knownDocumentIds.add(reference);
                         knownDocumentTypes.set(reference, page.type);
+                        if (!matchesFeatures(page.requires, loaded.deployment?.context, `${binding.file}: ${reference}`))
+                            continue;
                         if (page.access?.policy !== 'public' || page.channel !== variant.channel || page.version !== variant.version || page.language !== variant.language)
                             continue;
                         const key = keyFor(reference, variant);
@@ -167,6 +192,8 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
                                 throw new Error(`Generated API reference ${reference} conflicts with an authored page`);
                             continue;
                         }
+                        if (loaded.deployment?.context.grants && authoredOperationIds.has(id))
+                            continue;
                         const marks = pageReaderFilters(page, readerFilters, binding.file);
                         if (!matchesContentFilter(marks, contentFilter))
                             continue;
@@ -183,5 +210,5 @@ export async function materializeApiReferences({ config, loaded, variants, docs,
             if (!available.has(id))
                 throw new Error(`apis.${apiId}.generateReferences names unknown source operationId ${id}`);
     }
-    return { api, queryRules, lifecycleMappings, extensionValue, sourceForVariant, knownOperations, apiDefinitions: definitions };
+    return { api, operationRequirements, queryRules, lifecycleMappings, extensionValue, sourceForVariant, knownOperations, apiDefinitions: definitions };
 }

package/dist/artifact-bundle.d.ts

@@ -51,6 +51,7 @@ export type ArtifactAssemblyInput = {
     mcpAnalyticsModule?: string;
     previewFiles: string[];
     assetDirectory: string;
+    privateDependencies?: ReadonlySet<string>;
     themeSwitcher: boolean;
     themeDirectory: string;
     palette: Palette;

package/dist/artifact-bundle.js

@@ -98,7 +98,7 @@ export async function assembleArtifacts(input) {
             return `shoalrun:${framework}`;
         return `external:${path.basename(resolved)}`;
     };
-    addMetadataArtifact('/documents.json', JSON.stringify({ ...manifest, dependencies: [...new Set(manifest.dependencies.map(publicDependency))].sort() }, null, 2) + '\n');
+    addMetadataArtifact('/documents.json', JSON.stringify({ ...manifest, dependencies: [...new Set(manifest.dependencies.filter(file => !input.privateDependencies?.has(file)).map(publicDependency))].sort() }, null, 2) + '\n');
     addMetadataArtifact('/build-info.json', JSON.stringify(provenanceRecord, null, 2) + '\n');
     for (const styleFile of styleFiles)
         addPublicArtifact(`/assets/${path.basename(styleFile)}`, await readFile(styleFile, 'utf8'));

package/dist/authoring-api.d.ts

@@ -15,4 +15,4 @@ export { authoringReview, authoringReviewMarkdown } from './authoring-review.js'
 export type { AuthoringReview } from './authoring-review.js';
 export { startAuthoringPreview } from './authoring-preview.js';
 export type { AuthoringPreview, AuthoringPreviewOptions } from './authoring-preview.js';
-export declare const authoringCapabilities: readonly ["create-page", "complete-bundle-validation", "project-discovery", "project-source-read", "documentation-search-read", "working-tree-validation", "task-baseline", "validation-freshness", "snapshot-preview", "authoring-review-report"];
+export declare const authoringCapabilities: readonly ["create-page", "complete-bundle-validation", "project-discovery", "project-source-read", "documentation-search-read", "working-tree-validation", "task-baseline", "validation-freshness", "snapshot-preview", "authoring-review-report", "deployment-profiles"];

package/dist/authoring-api.js

@@ -12,4 +12,4 @@ export { authoringReview, authoringReviewMarkdown } from './authoring-review.js'
 export { startAuthoringPreview } from './authoring-preview.js';
 // Optional capabilities let private authoring clients reject an older package
 // before spending provider budget. Existing version-1 update clients still work.
-export const authoringCapabilities = ['create-page', 'complete-bundle-validation', 'project-discovery', 'project-source-read', 'documentation-search-read', 'working-tree-validation', 'task-baseline', 'validation-freshness', 'snapshot-preview', 'authoring-review-report'];
+export const authoringCapabilities = ['create-page', 'complete-bundle-validation', 'project-discovery', 'project-source-read', 'documentation-search-read', 'working-tree-validation', 'task-baseline', 'validation-freshness', 'snapshot-preview', 'authoring-review-report', 'deployment-profiles'];

package/dist/authoring-project-command.js

@@ -15,11 +15,13 @@ export function parseProjectOptions(command, args) {
         seen.add(flag);
         if (flag === '--json')
             continue;
-        const allowed = command === 'project' ? ['--config', '--section', '--id', '--file', '--query', '--offset', '--limit', '--max-tokens'] : ['--config', '--offset', '--max-tokens'];
+        const allowed = command === 'project' ? ['--profile', '--config', '--section', '--id', '--file', '--query', '--offset', '--limit', '--max-tokens'] : ['--profile', '--config', '--offset', '--max-tokens'];
         const value = args[++i];
         if (!allowed.includes(flag) || !value || value.startsWith('--'))
             throw new ProjectToolError('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 (['--offset', '--limit', '--max-tokens'].includes(flag)) {
             if (!/^\d+$/.test(value))

package/dist/authoring-project.d.ts

@@ -2,6 +2,7 @@ export declare const projectToolSchemaVersion = 1;
 export declare const projectSections: readonly ["pages", "guidance", "configuration", "navigation", "relationships", "templates", "findings"];
 export type ProjectSection = typeof projectSections[number];
 export type ProjectOptions = {
+    profile?: string;
     section?: ProjectSection;
     id?: string;
     file?: string;
@@ -78,6 +79,7 @@ export declare function inspectAuthoringProject(configFile: string, options?: Pr
 }>;
 /** Exact project-relative passage; role is context, not evidence approval. */
 export declare function readAuthoringSource(configFile: string, file: string, options?: {
+    profile?: string;
     offset?: number;
     maxTokens?: number;
 }): Promise<{

package/dist/authoring-project.js

@@ -61,11 +61,11 @@ async function safeFile(root, file) {
         throw new ProjectToolError('unsafe_path', `Source escapes project: ${file}`);
     return actual;
 }
-async function openProject(configFile) {
+async function openProject(configFile, profile) {
     try {
         const config = await realpath(path.resolve(configFile));
         const root = path.dirname(config);
-        const loaded = await loadConfig(config);
+        const loaded = await loadConfig(config, { profile });
         const guidance = validateAuthoringGuidance(loaded.value.authoring);
         return { config, root, loaded, guidance };
     }
@@ -88,7 +88,7 @@ export async function inspectAuthoringProject(configFile, options = {}) {
     const offset = integer(options.offset, 0, 0, Number.MAX_SAFE_INTEGER, 'offset');
     const limit = integer(options.limit, 20, 1, 100, 'limit');
     const maxTokens = integer(options.maxTokens, 8192, 1024, 100000, 'maxTokens');
-    const { root, config, loaded, guidance } = await openProject(configFile);
+    const { root, config, loaded, guidance } = await openProject(configFile, options.profile);
     const value = loaded.value;
     const relative = (file) => path.relative(root, file);
     const digests = new Map();
@@ -263,7 +263,7 @@ export async function inspectAuthoringProject(configFile, options = {}) {
 export async function readAuthoringSource(configFile, file, options = {}) {
     const offset = integer(options.offset, 0, 0, Number.MAX_SAFE_INTEGER, 'offset');
     const maxTokens = integer(options.maxTokens, 4096, 1024, 100000, 'maxTokens');
-    const { root, loaded, guidance } = await openProject(configFile);
+    const { root, loaded, guidance } = await openProject(configFile, options.profile);
     const actual = await safeFile(root, file);
     const raw = await readFile(actual, 'utf8');
     const chars = [...raw];

package/dist/authoring-snapshot.d.ts

@@ -11,7 +11,12 @@ export type SnapshotInput = {
     digest: string;
     mode: number;
 };
+export type ProfileCapture = {
+    file: string;
+    sources: Record<string, string>;
+};
 export type SnapshotCapture = {
+    profile?: ProfileCapture;
     root: string;
     config: string;
     inputs: SnapshotInput[];
@@ -24,6 +29,7 @@ export type SnapshotCapture = {
     configDigest?: string;
 };
 export type AuthoringBaseline = {
+    profile?: ProfileCapture;
     schemaVersion: 1;
     kind: 'shoalrun-authoring-baseline';
     project: string;
@@ -33,7 +39,14 @@ export type AuthoringBaseline = {
     externalDirectories: string[];
     excluded: SnapshotCapture['excluded'];
 };
+export declare function validateProfileCapture(root: string, profile?: ProfileCapture): void;
 export declare function relativeInput(root: string, file: string): string;
+/** Read only the named mounted file, including assets retained by a baseline. */
+export declare function readProfileInput(source: string): Promise<{
+    bytes: NonSharedBuffer;
+    digest: string;
+    mode: number;
+}>;
 export declare function collectSnapshotInputs(root: string, externalFiles?: string[], externalDirectories?: string[]): Promise<{
     inputs: SnapshotInput[];
     buffers: Map<string, Buffer<ArrayBufferLike>>;
@@ -43,9 +56,13 @@ export declare function collectSnapshotInputs(root: string, externalFiles?: stri
     }[];
 }>;
 /** Capture static, project-owned inputs without running compiler/plugins/checks. */
-export declare function captureSnapshotInputs(configFile: string): Promise<SnapshotCapture>;
-export declare function confirmSnapshotInputs(capture: Pick<SnapshotCapture, 'root' | 'inputs' | 'externalDirectories'>): Promise<boolean>;
-export declare function captureAuthoringBaseline(configFile: string): Promise<AuthoringBaseline>;
+export declare function captureSnapshotInputs(configFile: string, options?: {
+    profile?: string;
+}): Promise<SnapshotCapture>;
+export declare function confirmSnapshotInputs(capture: Pick<SnapshotCapture, 'root' | 'inputs' | 'externalDirectories' | 'profile'>): Promise<boolean>;
+export declare function captureAuthoringBaseline(configFile: string, options?: {
+    profile?: string;
+}): Promise<AuthoringBaseline>;
 export declare function parseAuthoringBaseline(value: unknown, root: string, config: string): AuthoringBaseline;
 export declare function validatorInputs(): Promise<{
     digest: string;
@@ -53,7 +70,9 @@ export declare function validatorInputs(): Promise<{
 }>;
 /** Artifact destinations are exclusive and cannot collide with source inputs. */
 export declare function authoringArtifactPath(root: string, destination: string): Promise<string>;
-export declare function writeAuthoringBaseline(configFile: string, output: string): Promise<{
+export declare function writeAuthoringBaseline(configFile: string, output: string, options?: {
+    profile?: string;
+}): Promise<{
     schemaVersion: number;
     status: string;
     baseline: string;

package/dist/authoring-snapshot.js

@@ -1,6 +1,7 @@
 import { componentPluginFiles } from './component-manifest.js';
 import { createHash } from 'node:crypto';
-import { lstat, mkdir, readFile, readdir, realpath, stat, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, open, readFile, readdir, realpath, stat, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { explainSegments, loadConfig } from './config.js';
@@ -16,10 +17,28 @@ export class SnapshotError extends Error {
     }
 }
 export const sha256 = (value) => createHash('sha256').update(value).digest('hex');
-export const isWithin = (root, file) => file === root || file.startsWith(root + path.sep);
+export const isWithin = (root, file) => file === root || file.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
 export const excludedNames = new Set(['.git', 'node_modules', 'dist', 'site-dist', '.vercel', '.shoalrun', '.private-archives', '.private-evals', '.aws', '.ssh', '.codex', '.npmrc']);
 const excluded = (name) => excludedNames.has(name) || name === '.env' || name.startsWith('.env.');
 const framework = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export function validateProfileCapture(root, profile) {
+    if (profile === undefined)
+        return;
+    if (!profile || typeof profile.file !== 'string' || !profile.sources || typeof profile.sources !== 'object' || Array.isArray(profile.sources))
+        throw new SnapshotError('invalid_input', 'Invalid captured deployment profile');
+    const source = profile.sources[profile.file];
+    if (typeof source !== 'string' || !path.isAbsolute(source))
+        throw new SnapshotError('invalid_input', 'Captured profile needs its explicit source file');
+    const directory = `../.shoalrun-profile-${sha256(source).slice(0, 16)}`;
+    if (profile.file !== `${directory}/${path.basename(source)}`)
+        throw new SnapshotError('unsafe_path', 'Captured profile identity does not match its source');
+    for (const [file, original] of Object.entries(profile.sources)) {
+        relativeInput(root, file);
+        const relative = path.relative(directory, file);
+        if (!relative || path.isAbsolute(relative) || relative.startsWith('..') || typeof original !== 'string' || original !== path.resolve(path.dirname(source), relative))
+            throw new SnapshotError('unsafe_path', 'Captured profile asset escapes its declared directory');
+    }
+}
 export function relativeInput(root, file) {
     if (typeof file !== 'string' || !file || path.isAbsolute(file) || /[\\\0\r\n]/.test(file))
         throw new SnapshotError('unsafe_path', 'Input paths must be project-relative');
@@ -40,6 +59,29 @@ async function noSymlinks(file, boundary) {
         current = path.dirname(current);
     }
 }
+/** Read only the named mounted file, including assets retained by a baseline. */
+export async function readProfileInput(source) {
+    const boundary = path.parse(source).root;
+    await noSymlinks(source, boundary);
+    const handle = await open(source, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const before = await handle.stat();
+        if (!before.isFile())
+            throw new SnapshotError('unsafe_path', 'Profile inputs must be regular files');
+        if (before.size > 16 * 1024 * 1024)
+            throw new SnapshotError('capture_limit', 'Profile input exceeds 16 MiB');
+        const bytes = await handle.readFile();
+        const after = await handle.stat();
+        await noSymlinks(source, boundary);
+        const current = await lstat(source);
+        if (bytes.length > 16 * 1024 * 1024 || before.ino !== current.ino || before.dev !== current.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.mode !== after.mode)
+            throw new SnapshotError('stale_input', 'Profile input changed while reading; retry validation');
+        return { bytes, digest: sha256(bytes), mode: before.mode & 0o777 };
+    }
+    finally {
+        await handle.close();
+    }
+}
 export async function collectSnapshotInputs(root, externalFiles = [], externalDirectories = []) {
     const buffers = new Map();
     const inputs = [];
@@ -89,18 +131,31 @@ export async function collectSnapshotInputs(root, externalFiles = [], externalDi
     return { inputs, buffers, excluded: exclusions };
 }
 /** Capture static, project-owned inputs without running compiler/plugins/checks. */
-export async function captureSnapshotInputs(configFile) {
+export async function captureSnapshotInputs(configFile, options = {}) {
     const config = await realpath(path.resolve(configFile));
     const root = path.dirname(config);
     const externalFiles = new Set(), externalDirectories = new Set();
+    const profileFile = options.profile ? await realpath(path.resolve(options.profile)) : undefined;
+    let profile;
+    const profileDependencies = new Set();
     let configDigest;
     let loaded;
     try {
-        loaded = await loadConfig(config);
+        loaded = await loadConfig(config, { profile: profileFile });
         configDigest = loaded.digest;
     }
     catch { /* Invalid configuration must still be captured and diagnosed in isolation. */ }
+    if (profileFile) {
+        const directory = `../.shoalrun-profile-${sha256(profileFile).slice(0, 16)}`;
+        profile = { file: `${directory}/${path.basename(profileFile)}`, sources: {} };
+        for (const source of [profileFile, ...(loaded?.deployment?.assetFiles ?? [])]) {
+            profileDependencies.add(source);
+            profile.sources[`${directory}/${path.relative(path.dirname(profileFile), source)}`] = source;
+        }
+    }
     const addExternal = async (absolute) => {
+        if (profileDependencies.has(absolute))
+            return;
         if (isWithin(root, absolute))
             return;
         const name = path.relative(root, absolute);
@@ -138,7 +193,7 @@ export async function captureSnapshotInputs(configFile) {
                 for (const key of Object.keys(value))
                     await visit(value[key], [...segments, key]);
             }
-            else if (typeof value === 'string' && (['file', 'path', 'module', 'manifest', 'customCss', 'customReaderModule', 'body', 'template', 'favicon'].includes(segments.at(-1)) || segments.at(-2) === 'files') && !/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(value)) {
+            else if (typeof value === 'string' && (['file', 'path', 'module', 'manifest', 'customCss', 'customReaderModule', 'body', 'template', 'favicon', 'logo'].includes(segments.at(-1)) || segments.at(-2) === 'files') && !/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(value)) {
                 if (path.isAbsolute(value))
                     throw new SnapshotError('unsupported_dependency', `Absolute dependency at ${segments.join('.')} cannot be isolated; use a relative path.`);
                 if (segments[0] === 'components' && segments.at(-1) === 'module' && !value.startsWith('.'))
@@ -199,28 +254,45 @@ export async function captureSnapshotInputs(configFile) {
     for (const input of captured.inputs)
         if (complete.inputs.find(item => item.file === input.file)?.digest !== input.digest)
             throw new SnapshotError('stale_input', `Input changed during dependency discovery: ${input.file}`);
-    return { root, config: path.basename(config), ...complete, externalDirectories: [...externalDirectories].sort(), configDigest };
+    for (const [file, source] of Object.entries(profile?.sources ?? {})) {
+        relativeInput(root, file);
+        const input = await readProfileInput(source);
+        complete.buffers.set(file, input.bytes);
+        complete.inputs.push({ file, digest: input.digest, mode: input.mode });
+    }
+    complete.inputs.sort((a, b) => a.file.localeCompare(b.file));
+    return { root, config: path.basename(config), ...complete, externalDirectories: [...externalDirectories].sort(), configDigest, ...(profile ? { profile } : {}) };
 }
 export async function confirmSnapshotInputs(capture) {
-    const external = capture.inputs.filter(input => (!isWithin(capture.root, path.resolve(capture.root, input.file)) || input.file.split(path.sep).some(excluded))).map(input => input.file);
+    const sources = capture.profile?.sources ?? {};
+    const ordinary = capture.inputs.filter(input => !Object.hasOwn(sources, input.file));
+    const external = ordinary.filter(input => (!isWithin(capture.root, path.resolve(capture.root, input.file)) || input.file.split(path.sep).some(excluded))).map(input => input.file);
     try {
+        validateProfileCapture(capture.root, capture.profile);
         const now = await collectSnapshotInputs(capture.root, external, capture.externalDirectories);
+        for (const [file, source] of Object.entries(sources)) {
+            relativeInput(capture.root, file);
+            const input = await readProfileInput(source);
+            now.inputs.push({ file, digest: input.digest, mode: input.mode });
+        }
+        now.inputs.sort((a, b) => a.file.localeCompare(b.file));
         return JSON.stringify(now.inputs) === JSON.stringify(capture.inputs);
     }
     catch {
         return false;
     }
 }
-export async function captureAuthoringBaseline(configFile) {
-    const capture = await captureSnapshotInputs(configFile);
+export async function captureAuthoringBaseline(configFile, options = {}) {
+    const capture = await captureSnapshotInputs(configFile, options);
     if (!await confirmSnapshotInputs(capture))
         throw new SnapshotError('stale_input', 'Working tree changed while capturing the task baseline; retry.');
-    return { schemaVersion: 1, kind: 'shoalrun-authoring-baseline', project: capture.root, config: capture.config, inputs: capture.inputs, externalDirectories: capture.externalDirectories, excluded: capture.excluded, digest: sha256(JSON.stringify(capture.inputs)) };
+    return { profile: capture.profile, schemaVersion: 1, kind: 'shoalrun-authoring-baseline', project: capture.root, config: capture.config, inputs: capture.inputs, externalDirectories: capture.externalDirectories, excluded: capture.excluded, digest: sha256(JSON.stringify(capture.inputs)) };
 }
 export function parseAuthoringBaseline(value, root, config) {
     const baseline = value;
     if (!baseline || baseline.schemaVersion !== 1 || baseline.kind !== 'shoalrun-authoring-baseline' || baseline.project !== root || baseline.config !== config || !Array.isArray(baseline.inputs) || !Array.isArray(baseline.externalDirectories) || !Array.isArray(baseline.excluded))
         throw new SnapshotError('invalid_input', 'Baseline must be a version-1 task baseline for this project/configuration.');
+    validateProfileCapture(root, baseline.profile);
     const seen = new Set();
     for (const directory of baseline.externalDirectories)
         relativeInput(root, directory);
@@ -284,8 +356,8 @@ export async function authoringArtifactPath(root, destination) {
     await noSymlinks(target, path.parse(target).root);
     return target;
 }
-export async function writeAuthoringBaseline(configFile, output) {
-    const baseline = await captureAuthoringBaseline(configFile);
+export async function writeAuthoringBaseline(configFile, output, options = {}) {
+    const baseline = await captureAuthoringBaseline(configFile, options);
     const target = await authoringArtifactPath(baseline.project, output);
     await mkdir(path.dirname(target), { recursive: true });
     await writeFile(target, JSON.stringify(baseline, null, 2) + '\n', { flag: 'wx' });

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