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

package/dist/index-build.js

@@ -164,7 +164,9 @@ export function chunkMarkdown(markdown, document, anchors = [], options = {}) {
     return chunks;
 }
 function makeChunk(document, headingPath, anchor, text, used, part = 0) {
-    const base = `${document.id}#${slug(headingPath.join(' ')) || 'intro'}${part ? `~${part + 1}` : ''}`;
+    // Logical page IDs repeat across releases. Stored passage IDs must not: vector
+    // rows and answer citations are keyed globally within this site's index.
+    const base = `${encodeURIComponent(document.variant)}:${encodeURIComponent(document.id)}#${slug(headingPath.join(' ')) || 'intro'}${part ? `~${part + 1}` : ''}`;
     const seen = used.get(base) ?? 0;
     used.set(base, seen + 1);
     const chunk = { id: seen ? `${base}-${seen + 1}` : base, docId: document.id, title: document.title, type: document.type, variant: document.variant, headingPath, url: anchor ? `${document.url}#${anchor}` : document.url, markdownUrl: document.markdownUrl, text };
@@ -219,8 +221,10 @@ export async function buildChunkIndex(directory, options = {}) {
         const { channel, version, language } = document.variant;
         chunks.push(...chunkMarkdown(markdown, { ...document, variant: `${channel}|${version}|${language}` }, anchors.get(document.url), options));
     }
-    const source = manifest.documents.map(document => `${document.id}:${document.digest}`).sort().join('\n');
-    const index = { schemaVersion: 1, sourceDigest: sha(source + (synonyms.length ? `\n${JSON.stringify(synonyms)}` : '')), chunks, ...(synonyms.length ? { synonyms } : {}) };
+    // Generation identity includes publication membership, routes, reader marks,
+    // and prepared search evidence. Embedding digests remain content-only.
+    const source = chunks.map(({ id, variant, digest, url, markdownUrl, readerFilters, search }) => ({ id, variant, digest, url, markdownUrl, readerFilters: Object.fromEntries(Object.entries(readerFilters ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([facet, values]) => [facet, [...values].sort()])), search })).sort((a, b) => a.id.localeCompare(b.id));
+    const index = { schemaVersion: 1, sourceDigest: sha(JSON.stringify({ identityVersion: 2, source, synonyms })), chunks, ...(synonyms.length ? { synonyms } : {}) };
     const output = path.join(await aiDirectory(root), 'chunks.json');
     await writeFile(output, JSON.stringify(index) + '\n');
     return { index, output, documents: manifest.documents.length };

package/dist/page-materialization.js

@@ -29,6 +29,8 @@ export async function materializePages({ variables, frontmatterConfig, publicati
                 local.set(other.frontmatter.id, other);
         const parsed = parse.parse(doc.body);
         const tree = await resolveApiEmbedTree(transformMdx(parsed, doc, local, snippets, variables, snippetUses, calloutTypes, base, readerFilters, frontmatterConfig, publications, badgeVariants, componentPlugins), api, operationId => sourceForOperation(operationId, doc.variant), apiId => {
+            if (doc.featureContext?.grants)
+                throw new Error('Standalone API schema embeds require an explicitly scoped source and are not supported in profiled builds; select an operation instead');
             const definition = apiPlan.apiDefinitions[apiId];
             if (!definition)
                 throw new Error(`unknown API ${apiId}`);

package/dist/page-renderer.d.ts

@@ -42,6 +42,7 @@ export type PageShell = {
         generated: boolean;
     };
     favicon?: string;
+    logo?: string;
     touchIcon?: boolean;
     origin?: string;
     indexing?: boolean;

package/dist/page-renderer.js

@@ -62,6 +62,8 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
     const audienceLabels = doc.frontmatter.audiences?.filter(label => label.trim()) ?? [];
     const audienceBadges = audienceLabels.length ? `<div class="audience-labels" role="group" aria-label="Intended audience"><span class="audience-label-heading">For</span>${audienceLabels.map(label => `<span class="audience-badge">${esc(readerConfig?.facets.audience?.options[label] ?? label)}</span>`).join('')}</div>` : '';
     const title = doc.frontmatter.seo?.title ?? doc.frontmatter.title;
+    const brand = `${shell.logo ? `<img class="brand-logo" src="${esc(shell.logo)}" alt="">` : ''}${esc(siteTitle)}`;
+    const brandClass = shell.logo ? 'brand brand-custom' : 'brand';
     const pageTitle = String(title).trim();
     const brandedTitle = `${pageTitle} | ${siteTitle.trim()}`;
     const socialTitle = !doc.frontmatter.seo?.title && pageTitle.length < 30 && brandedTitle.length <= 70 ? brandedTitle : pageTitle;
@@ -174,6 +176,6 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
     const menu = side || sectionNavigation ? `<a class="mobile-menu" href="#${side ? 'docs-navigation' : 'docs-sections'}">Menu</a>` : '';
     const rail = toc || panel ? `<aside class="page-rail">${doc.endpoint ? `${panel}${toc}` : `${toc}${panel}`}</aside>` : '';
     const breadcrumbs = (shell.breadcrumbs?.length ?? 0) > 1 && !hero ? `<nav class="doc-breadcrumbs" aria-label="Breadcrumb"><ol>${shell.breadcrumbs.map((item, index) => `<li>${index === shell.breadcrumbs.length - 1 ? `<span aria-current="page">${esc(item.label)}</span>` : item.url ? `<a href="${esc(item.url)}">${esc(item.label)}</a>` : `<span>${esc(item.label)}</span>`}</li>`).join('')}</ol></nav>` : '';
-    const markup = `<!doctype html><html lang="${esc(doc.variant.language)}"${shell.themeCss || shell.paletteCss ? ` data-theme="${esc(shell.preset ?? 'shoal')}" data-palette="${esc(shell.palette ?? '')}"` : ''}${shell.masthead ? ` data-masthead="${esc(shell.masthead)}"` : ''}${layout === 'docs' ? '' : ` data-layout="${layout}"`}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="${shell.mode === 'system' ? 'light dark' : shell.mode ?? 'light'}">${shell.indexing === false || doc.frontmatter.seo?.noindex === true ? '<meta name="robots" content="noindex">' : ''}${shell.origin ? `<link rel="canonical" href="${esc(absolute(doc.route))}">` : ''}${shell.toggle ? '<script src="/assets/mode.js"></script>' : ''}<title>${esc(String(title))}</title>${description ? `<meta name="description" content="${esc(String(description))}">` : ''}${socialDescription ? `<meta property="og:description" content="${esc(socialDescription)}">` : ''}${social}<link rel="alternate" type="text/markdown" href="${esc(markdownUrl)}"><link rel="describedby" href="/llms.min.txt" title="Documentation index">${icons}${shell.preloadFont ? `<link rel="preload" href="/assets/fonts/${esc(shell.preloadFont)}" as="font" type="font/woff2" crossorigin>` : ''}<link rel="stylesheet" href="/assets/site.css">${article.includes('data-theme-preview') ? '<link rel="stylesheet" href="/assets/theme-preview.css">' : ''}${shell.themeCss ? '<link rel="stylesheet" href="/assets/theme.css" data-theme-link="theme">' : ''}${shell.paletteCss ? '<link rel="stylesheet" href="/assets/palette.css" data-theme-link="palette">' : ''}${shell.badgesCss ? '<link rel="stylesheet" href="/assets/badges.css">' : ''}${shell.themeSwitcher ? `<script src="/assets/theme-switcher.js" data-themes="${esc(shell.themeSwitcher)}"></script>` : ''}${shell.fontsCss ? '<link rel="stylesheet" href="/assets/fonts.css">' : ''}${customCss ? '<link rel="stylesheet" href="/assets/project.css">' : ''}</head><body><a class="skip" href="#main">Skip to content</a>${agent.mode === 'disclosure' ? '' : agentBlock}<header class="mast"><div class="mast-inner">${shell.home ? `<a class="brand" href="/">${esc(siteTitle)}</a>` : `<span class="brand">${esc(siteTitle)}</span>`}${editionLabel && (shell.publicationAlternates?.length ?? 0) < 2 ? `<span class="edition">${esc(editionLabel)}</span>` : ''}${menu}${headerTools(shell, doc.variant, esc, readerConfig)}${agent.mode === 'disclosure' ? agentBlock : ''}</div></header>${sectionNavigation}${shortcuts}<div class="layout${layout === 'docs' ? '' : ` layout-${layout}`}${rail ? ' has-rail' : ''}${panel ? ' has-examples' : ''}${doc.endpoint ? ' api-reference' : ''}"><main id="main" class="content" tabindex="-1" data-document-type="${esc(doc.frontmatter.type)}"${readerConfig ? ` data-reader-page="${esc(readerFilterAttribute(doc.readerFilters ?? {}))}"` : ''}>${breadcrumbs}${hero ? '' : `<header class="page-head"><span class="eyebrow">${esc(typeLabel(doc.frontmatter.type))}</span>${doc.endpoint ? '' : badge(doc.frontmatter.subjectLifecycle)}<h1>${esc(doc.frontmatter.title)}${doc.endpoint ? badge(doc.frontmatter.subjectLifecycle) : ''}</h1>${pageHeader && !routeSummary ? `<p class="summary">${esc(pageHeader)}</p>` : ''}${pageDates}${endpoint}${audienceBadges}</header>`}${hero ? '' : `<div class="page-formats"><a class="formats" href="${esc(markdownUrl)}">Read as Markdown</a><button type="button" class="formats" data-copy-markdown hidden>Copy as Markdown</button><span role="status" data-copy-markdown-status></span></div>`}${toc ? '<div class="mobile-outline-slot"></div>' : ''}${jumps}${readerBanner}<article>${article}</article></main>${rail}${side}</div>${footer}${analyticsBootstrap}${readerBootstrap}<script type="module" src="/assets/copy-markdown.js"></script><script type="module" src="/assets/navigation.js"></script><script type="module" src="/assets/reader.js"></script><script type="module" src="/assets/tabs.js"></script>${shell.search ? '<script type="module" src="/assets/search.js"></script>' : ''}${article.includes('data-tooltip') ? '<script type="module" src="/assets/tooltips.js"></script>' : ''}${article.includes('data-component-module') ? '<script type="module" src="/assets/components.js"></script>' : ''}${article.includes('data-file-tree') ? '<script type="module" src="/assets/file-tree.js"></script>' : ''}${article.includes('data-image-expand') ? '<script type="module" src="/assets/image-viewer.js"></script>' : ''}${article.includes('data-table-filter') || article.includes('data-definition-filter') ? '<script type="module" src="/assets/table-filter.js"></script>' : ''}${article.includes('data-walkthrough') ? '<script type="module" src="/assets/walkthrough.js"></script>' : ''}${article.includes('data-cookbook-chooser') ? '<script type="module" src="/assets/cookbook-chooser.js"></script>' : ''}${article.includes('data-theme-preview') ? '<script type="module" src="/assets/theme-preview.js"></script>' : ''}${panel ? '<script type="module" src="/assets/example-panel.js"></script>' : ''}${panel.includes('data-code-samples') ? '<script type="module" src="/assets/code-samples.js"></script>' : ''}</body></html>`;
+    const markup = `<!doctype html><html lang="${esc(doc.variant.language)}"${shell.themeCss || shell.paletteCss ? ` data-theme="${esc(shell.preset ?? 'shoal')}" data-palette="${esc(shell.palette ?? '')}"` : ''}${shell.masthead ? ` data-masthead="${esc(shell.masthead)}"` : ''}${layout === 'docs' ? '' : ` data-layout="${layout}"`}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="${shell.mode === 'system' ? 'light dark' : shell.mode ?? 'light'}">${shell.indexing === false || doc.frontmatter.seo?.noindex === true ? '<meta name="robots" content="noindex">' : ''}${shell.origin ? `<link rel="canonical" href="${esc(absolute(doc.route))}">` : ''}${shell.toggle ? '<script src="/assets/mode.js"></script>' : ''}<title>${esc(String(title))}</title>${description ? `<meta name="description" content="${esc(String(description))}">` : ''}${socialDescription ? `<meta property="og:description" content="${esc(socialDescription)}">` : ''}${social}<link rel="alternate" type="text/markdown" href="${esc(markdownUrl)}"><link rel="describedby" href="/llms.min.txt" title="Documentation index">${icons}${shell.preloadFont ? `<link rel="preload" href="/assets/fonts/${esc(shell.preloadFont)}" as="font" type="font/woff2" crossorigin>` : ''}<link rel="stylesheet" href="/assets/site.css">${article.includes('data-theme-preview') ? '<link rel="stylesheet" href="/assets/theme-preview.css">' : ''}${shell.themeCss ? '<link rel="stylesheet" href="/assets/theme.css" data-theme-link="theme">' : ''}${shell.paletteCss ? '<link rel="stylesheet" href="/assets/palette.css" data-theme-link="palette">' : ''}${shell.badgesCss ? '<link rel="stylesheet" href="/assets/badges.css">' : ''}${shell.themeSwitcher ? `<script src="/assets/theme-switcher.js" data-themes="${esc(shell.themeSwitcher)}"></script>` : ''}${shell.fontsCss ? '<link rel="stylesheet" href="/assets/fonts.css">' : ''}${customCss ? '<link rel="stylesheet" href="/assets/project.css">' : ''}</head><body><a class="skip" href="#main">Skip to content</a>${agent.mode === 'disclosure' ? '' : agentBlock}<header class="mast"><div class="mast-inner">${shell.home ? `<a class="${brandClass}" href="/">${brand}</a>` : `<span class="${brandClass}">${brand}</span>`}${editionLabel && (shell.publicationAlternates?.length ?? 0) < 2 ? `<span class="edition">${esc(editionLabel)}</span>` : ''}${menu}${headerTools(shell, doc.variant, esc, readerConfig)}${agent.mode === 'disclosure' ? agentBlock : ''}</div></header>${sectionNavigation}${shortcuts}<div class="layout${layout === 'docs' ? '' : ` layout-${layout}`}${rail ? ' has-rail' : ''}${panel ? ' has-examples' : ''}${doc.endpoint ? ' api-reference' : ''}"><main id="main" class="content" tabindex="-1" data-document-type="${esc(doc.frontmatter.type)}"${readerConfig ? ` data-reader-page="${esc(readerFilterAttribute(doc.readerFilters ?? {}))}"` : ''}>${breadcrumbs}${hero ? '' : `<header class="page-head"><span class="eyebrow">${esc(typeLabel(doc.frontmatter.type))}</span>${doc.endpoint ? '' : badge(doc.frontmatter.subjectLifecycle)}<h1>${esc(doc.frontmatter.title)}${doc.endpoint ? badge(doc.frontmatter.subjectLifecycle) : ''}</h1>${pageHeader && !routeSummary ? `<p class="summary">${esc(pageHeader)}</p>` : ''}${pageDates}${endpoint}${audienceBadges}</header>`}${hero ? '' : `<div class="page-formats"><a class="formats" href="${esc(markdownUrl)}">Read as Markdown</a><button type="button" class="formats" data-copy-markdown hidden>Copy as Markdown</button><span role="status" data-copy-markdown-status></span></div>`}${toc ? '<div class="mobile-outline-slot"></div>' : ''}${jumps}${readerBanner}<article>${article}</article></main>${rail}${side}</div>${footer}${analyticsBootstrap}${readerBootstrap}<script type="module" src="/assets/copy-markdown.js"></script><script type="module" src="/assets/navigation.js"></script><script type="module" src="/assets/reader.js"></script><script type="module" src="/assets/tabs.js"></script>${shell.search ? '<script type="module" src="/assets/search.js"></script>' : ''}${article.includes('data-tooltip') ? '<script type="module" src="/assets/tooltips.js"></script>' : ''}${article.includes('data-component-module') ? '<script type="module" src="/assets/components.js"></script>' : ''}${article.includes('data-file-tree') ? '<script type="module" src="/assets/file-tree.js"></script>' : ''}${article.includes('data-image-expand') ? '<script type="module" src="/assets/image-viewer.js"></script>' : ''}${article.includes('data-table-filter') || article.includes('data-definition-filter') ? '<script type="module" src="/assets/table-filter.js"></script>' : ''}${article.includes('data-walkthrough') ? '<script type="module" src="/assets/walkthrough.js"></script>' : ''}${article.includes('data-cookbook-chooser') ? '<script type="module" src="/assets/cookbook-chooser.js"></script>' : ''}${article.includes('data-theme-preview') ? '<script type="module" src="/assets/theme-preview.js"></script>' : ''}${panel ? '<script type="module" src="/assets/example-panel.js"></script>' : ''}${panel.includes('data-code-samples') ? '<script type="module" src="/assets/code-samples.js"></script>' : ''}</body></html>`;
     return basePath ? markup.replace(/((?:href|src)=")\/(assets\/|llms(?:\.min)?\.txt|apple-touch-icon\.png)/g, `$1${basePath}/$2`).replace('href="/"', `href="${basePath}/"`) : markup;
 }

package/dist/palettes.d.ts

@@ -1,4 +1,4 @@
-export declare const paletteTokens: readonly ["text", "page", "surface", "link", "link-hover", "focus", "ink", "accent", "accent-contrast", "header-muted", "header-border", "border", "border-soft", "border-nested", "field-surface", "field-border", "field-accent", "presence-bg", "presence-text", "optional-bg", "optional-text", "muted", "nav-heading", "section-heading", "nav-text", "nav-hover", "nav-active", "nav-active-text", "deprecated-bg", "deprecated-text", "beta-bg", "beta-text", "development-bg", "development-text", "experimental-bg", "experimental-text", "emphasis", "summary", "code-bg", "code-text", "code-muted", "code-border", "code-block", "callout-line", "callout-bg", ...("callout-warning-line" | "callout-note-line" | "callout-tip-line" | "callout-important-line" | "callout-caution-line" | "callout-warning-bg" | "callout-note-bg" | "callout-tip-bg" | "callout-important-bg" | "callout-caution-bg" | "callout-warning-text" | "callout-note-text" | "callout-tip-text" | "callout-important-text" | "callout-caution-text")[], "strong-surface", "strong-text"];
+export declare const paletteTokens: readonly ["text", "page", "surface", "link", "link-hover", "focus", "ink", "accent", "accent-contrast", "header-muted", "header-border", "border", "border-soft", "border-nested", "field-surface", "field-border", "field-accent", "presence-bg", "presence-text", "optional-bg", "optional-text", "muted", "nav-heading", "section-heading", "nav-text", "nav-hover", "nav-active", "nav-active-text", "deprecated-bg", "deprecated-text", "beta-bg", "beta-text", "development-bg", "development-text", "experimental-bg", "experimental-text", "emphasis", "summary", "code-bg", "code-text", "code-muted", "code-border", "code-block", "callout-line", "callout-bg", ...("callout-note-line" | "callout-tip-line" | "callout-important-line" | "callout-warning-line" | "callout-caution-line" | "callout-note-bg" | "callout-tip-bg" | "callout-important-bg" | "callout-warning-bg" | "callout-caution-bg" | "callout-note-text" | "callout-tip-text" | "callout-important-text" | "callout-warning-text" | "callout-caution-text")[], "strong-surface", "strong-text"];
 export type Token = typeof paletteTokens[number];
 export type Mode = 'light' | 'dark';
 export type Palette = {

package/dist/project-navigation.d.ts

@@ -38,4 +38,9 @@ export declare function navigationPath(nodes: NavigationNode[], route: string):
     label: string;
     url?: string;
 }>;
+/** Prune only after validating every authored node against known source identities. */
+export declare function profileNavigation(layout: unknown, docs: Map<string, Document>, knownIds: Set<string>, operations: Map<string, {
+    apiId: string;
+    reference: string;
+}>, apiIds: Set<string>): NavSpec[];
 export {};

package/dist/project-navigation.js

@@ -188,3 +188,22 @@ export function navigationPath(nodes, route) {
     }
     return [];
 }
+/** Prune only after validating every authored node against known source identities. */
+export function profileNavigation(layout, docs, knownIds, operations, apiIds) {
+    const known = new Map(docs);
+    for (const id of knownIds)
+        if (![...known.values()].some(doc => doc.frontmatter.id === id))
+            known.set(id, { frontmatter: { id } });
+    const validated = validateProjectNavigation(layout, known, operations, apiIds);
+    const available = new Set([...docs.values()].map(doc => doc.frontmatter.id));
+    const prune = (nodes) => nodes.flatMap(node => {
+        if (node.doc && !available.has(node.doc) || node.operation && !available.has(operations.get(node.operation).reference) || node.tab && !available.has(node.landing))
+            return [];
+        if (node.items) {
+            const items = prune(node.items);
+            return items.length ? [{ ...node, items }] : [];
+        }
+        return [node];
+    });
+    return prune(validated);
+}

package/dist/publication-plan.d.ts

@@ -1,3 +1,4 @@
+import { type FeatureContext } from './deployment-profile.js';
 import { type Document, type Variant } from './content.js';
 import type { PublicationRoutingConfig } from './content-source.js';
 import { type MetadataProvider } from './metadata-provider.js';
@@ -16,7 +17,7 @@ export type AuthoredPublicationPlan = {
     authoredOperationIds: Set<string>;
     routeOwners: Map<string, string>;
 };
-export declare function planAuthoredDocuments({ base, basePath, config, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }: {
+export declare function planAuthoredDocuments({ base, basePath, config, variants, language, readerFilters, contentFilter, featureContext, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }: {
     base: string;
     basePath: string;
     config: AuthoredPublicationConfig;
@@ -24,6 +25,7 @@ export declare function planAuthoredDocuments({ base, basePath, config, variants
     language: string;
     readerFilters?: ReaderFiltersConfig;
     contentFilter?: ReaderSelection;
+    featureContext?: FeatureContext;
     metadataProvider?: {
         provide: MetadataProvider;
     };

package/dist/publication-plan.js

@@ -1,4 +1,5 @@
 import { hasScaffoldPlaceholders } from './scaffold-placeholders.js';
+import { validateFeatureClassification, matchesFeatures } from './deployment-profile.js';
 import { matchesContentFilter } from './content-filter.js';
 import { readdir } from 'node:fs/promises';
 import path from 'node:path';
@@ -13,7 +14,7 @@ async function files(dir) {
     const nested = await Promise.all(entries.map(async (entry) => entry.isDirectory() ? files(path.join(dir, entry.name)) : /\.mdx?$/.test(entry.name) ? [path.join(dir, entry.name)] : []));
     return nested.flat().sort();
 }
-export async function planAuthoredDocuments({ base, basePath, config, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }) {
+export async function planAuthoredDocuments({ base, basePath, config, variants, language, readerFilters, contentFilter, featureContext, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }) {
     const docs = new Map();
     const knownDocumentIds = new Set();
     const knownDocumentTypes = new Map();
@@ -56,13 +57,28 @@ export async function planAuthoredDocuments({ base, basePath, config, variants,
         if (frontmatter.type === 'api-reference')
             for (const operation of frontmatter.operations ?? [])
                 authoredOperationIds.add(operation);
-        if (frontmatter.access?.policy !== 'public' && !authoringFiles?.has(file))
+        const classificationVariants = featureContext?.classificationPublications ?? variants;
+        const classificationEligible = frontmatter.access?.policy === 'public' && classificationVariants.some(variant => (pagePublications ? pagePublications.some(item => item.channel === variant.channel && item.version === variant.version) : frontmatter.channel === variant.channel && frontmatter.version === variant.version) && frontmatter.language === variant.language);
+        if (classificationEligible)
+            validateFeatureClassification(sourceFrontmatter, featureContext, `${file}: ${frontmatter.id}`);
+        const included = matchesFeatures(frontmatter.requires, featureContext, `${file}: ${frontmatter.id}`);
+        const decision = featureContext?.decisions.at(-1);
+        if (!included)
             continue;
+        if (frontmatter.access?.policy !== 'public' && !authoringFiles?.has(file)) {
+            if (decision)
+                decision.included = false;
+            continue;
+        }
         const marks = pageReaderFilters(frontmatter, readerFilters, file);
-        if (!matchesContentFilter(marks, contentFilter))
+        if (!matchesContentFilter(marks, contentFilter)) {
+            if (decision)
+                decision.included = false;
             continue;
+        }
         if (hasScaffoldPlaceholders(body) || /\[\[TODO:[\s\S]*?\]\]/.test(JSON.stringify(frontmatter)) || frontmatter.summary?.startsWith('Draft guide for '))
             throw new Error(`${file}: unresolved scaffold placeholders cannot be published`);
+        let selectedPublication = false;
         for (const variant of variants) {
             if (pagePublications ? !pagePublications.some(item => item.channel === variant.channel && item.version === variant.version) : (frontmatter.channel && frontmatter.channel !== variant.channel || frontmatter.version && frontmatter.version !== variant.version))
                 continue;
@@ -79,8 +95,11 @@ export async function planAuthoredDocuments({ base, basePath, config, variants,
             if (collision && !allowRouteCollisions)
                 throw new Error(`Route collision ${route}: ${collision} and ${key}`);
             routeOwners.set(route.toLowerCase(), key);
-            docs.set(key, { file, frontmatter: publishedFrontmatter, body, tree: null, variant, route, markdownRoute: markdownRoute(route, basePath), readerFilters: marks });
+            selectedPublication = true;
+            docs.set(key, { featureContext, file, frontmatter: publishedFrontmatter, body, tree: null, variant, route, markdownRoute: markdownRoute(route, basePath), readerFilters: marks });
         }
+        if (!selectedPublication && decision)
+            decision.included = false;
     }
     return { contentDir, docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners };
 }

package/dist/publication-render.d.ts

@@ -8,7 +8,7 @@ import type { ReaderFiltersConfig } from './reader-filters.js';
 import type { CodeHighlighter } from './highlight.js';
 import type { MaterializedPage } from './page-materialization.js';
 import type { ResolvedCompilerConfig, CompilerSiteConfig, CompilerPublicationsConfig } from './compiler-config.js';
-export declare function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, shareFor, faviconRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }: {
+export declare function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }: {
     freshness?: Freshness;
     rendered: MaterializedPage[];
     docs: Map<string, Document>;
@@ -47,11 +47,12 @@ export declare function renderPublicationPages({ rendered, docs, relationships,
         file?: string;
     } | undefined;
     faviconRoute: string;
+    logoRoute?: string;
     modeToggle: boolean;
     header: HeaderConfig;
     footer?: FooterConfig;
     search: {
-        provider: 'lexical' | 'custom' | 'none';
+        provider: 'lexical' | 'semantic' | 'custom' | 'none';
     };
     readerFilters?: ReaderFiltersConfig;
     variants: Variant[];

package/dist/publication-render.js

@@ -11,7 +11,7 @@ import { navigationPath, navigationTab, navigationTabRecord, resolveProjectNavig
 import { outputUrl, publicTree, resolveOutputLinks } from './representation-tree.js';
 import { presetCatalog } from './palettes.js';
 const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
-export function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, shareFor, faviconRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }) {
+export function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }) {
     const resolvedNavigation = new Map();
     const scopedRelationships = new Map();
     const hasHome = rendered.some(page => page.doc.route === basePath || page.doc.route === '/');
@@ -86,7 +86,7 @@ export function renderPublicationPages({ rendered, docs, relationships, knownOpe
                 label: `${item.label}${item.label.toLowerCase() === item.variant.channel.toLowerCase() ? '' : ` · ${item.variant.channel}`} · ${item.variant.version}${languageSuffix(item.variant)}`,
                 url: item.url, current: false
             }))];
-        page.html = buildHtmlPage(page.doc, page.htmlTree, page.doc.markdownRoute, config.site.title, navigation, page.pageExamples, page.pageShapes, highlighter, editionLabel(page.doc.variant), !!customStyleFile, { preset: themePreset, palette: palette.name, themeCss: !!themeStyleFile, paletteCss: !!generatedPaletteCss, badgesCss: !!generatedBadgeCss, themeSwitcher: themeSwitcherData, fontsCss: !!generatedFontsCss, preloadFont: fontsPreload, masthead: presetCatalog.find(preset => preset.name === themePreset)?.masthead, share: shareFor(page.doc), favicon: faviconRoute, touchIcon: !faviconRoute.endsWith('.png'), origin: siteOrigin, indexing: config.site.indexing !== false, home: hasHome, mode: colorMode, toggle: modeToggle, header, footer, search: search.provider !== 'none', publicationAlternates, breadcrumbs }, page.pageCurl, page.pageSamples, { ...config, readerFilters });
+        page.html = buildHtmlPage(page.doc, page.htmlTree, page.doc.markdownRoute, config.site.title, navigation, page.pageExamples, page.pageShapes, highlighter, editionLabel(page.doc.variant), !!customStyleFile, { preset: themePreset, palette: palette.name, themeCss: !!themeStyleFile, paletteCss: !!generatedPaletteCss, badgesCss: !!generatedBadgeCss, themeSwitcher: themeSwitcherData, fontsCss: !!generatedFontsCss, preloadFont: fontsPreload, masthead: presetCatalog.find(preset => preset.name === themePreset)?.masthead, share: shareFor(page.doc), favicon: faviconRoute, logo: logoRoute, touchIcon: !faviconRoute.endsWith('.png'), origin: siteOrigin, indexing: config.site.indexing !== false, home: hasHome, mode: colorMode, toggle: modeToggle, header, footer, search: search.provider !== 'none', publicationAlternates, breadcrumbs }, page.pageCurl, page.pageSamples, { ...config, readerFilters });
     }
     return resolvedNavigation;
 }

package/dist/retrieval.d.ts

@@ -21,6 +21,7 @@ export declare class LexicalIndex {
     private readonly average;
     constructor(chunks: Chunk[], synonyms?: SynonymGroups);
     search(query: string, limit?: number, keep?: Keep): Hit[];
+    scan(query: string, keep?: Keep): IterableIterator<Hit>;
 }
 type VectorRow = {
     chunk: Chunk;
@@ -30,7 +31,9 @@ export declare class VectorIndex {
     private readonly rows;
     constructor(rows: VectorRow[]);
     search(query: Float32Array, limit?: number, keep?: Keep): Hit[];
+    scan(query: Float32Array, keep?: Keep): IterableIterator<Hit>;
 }
+export declare const compareHits: (left: Hit, right: Hit) => number;
 export declare function fuse(lists: Hit[][], limit?: number, k?: number): Hit[];
 export type Coverage = {
     total: number;
@@ -53,6 +56,7 @@ export declare class Retriever {
     private variant;
     pageIntroduction(docId: string, options?: LexicalOptions): Chunk | undefined;
     lexical(query: string, options?: LexicalOptions): Hit[];
+    searchPassages(query: string, queryVector: Float32Array | undefined, options?: LexicalOptions): Iterable<Hit>;
     vector(queryVector: Float32Array, options?: LexicalOptions): Hit[];
     hasVectors(options?: LexicalOptions): boolean;
     hybrid(query: string, queryVector: Float32Array | undefined, options?: LexicalOptions): Hit[];

package/dist/retrieval.js

@@ -67,10 +67,12 @@ export class LexicalIndex {
         this.average = this.entries.reduce((sum, entry) => sum + entry.length, 0) / (this.entries.length || 1);
     }
     search(query, limit = 8, keep) {
+        return [...this.scan(query, keep)].sort(compareHits).slice(0, limit);
+    }
+    *scan(query, keep) {
         const terms = [...new Set(tokenize(query))];
         const units = queryUnits(query, this.synonyms).filter(unit => unit.alternatives.length);
         const total = this.entries.length;
-        const hits = [];
         for (const entry of this.entries) {
             if (keep && !keep(entry.chunk))
                 continue;
@@ -93,9 +95,8 @@ export class LexicalIndex {
                 }
             }
             if (score > 0)
-                hits.push({ chunk: entry.chunk, score });
+                yield { chunk: entry.chunk, score };
         }
-        return hits.sort((left, right) => right.score - left.score || left.chunk.id.localeCompare(right.chunk.id)).slice(0, limit);
     }
 }
 function unit(vector) {
@@ -113,8 +114,10 @@ export class VectorIndex {
         this.rows = rows;
     }
     search(query, limit = 8, keep) {
+        return [...this.scan(query, keep)].sort(compareHits).slice(0, limit);
+    }
+    *scan(query, keep) {
         const q = unit(query);
-        const hits = [];
         for (const row of this.rows) {
             if (keep && !keep(row.chunk))
                 continue;
@@ -123,11 +126,11 @@ export class VectorIndex {
             let score = 0;
             for (let at = 0; at < q.length; at++)
                 score += q[at] * row.vector[at];
-            hits.push({ chunk: row.chunk, score });
+            yield { chunk: row.chunk, score };
         }
-        return hits.sort((left, right) => right.score - left.score || left.chunk.id.localeCompare(right.chunk.id)).slice(0, limit);
     }
 }
+export const compareHits = (left, right) => right.score - left.score || left.chunk.id.localeCompare(right.chunk.id);
 // Reciprocal rank fusion. Lexical and vector scores are not comparable, so only ranks are combined.
 export function fuse(lists, limit = 8, k = 60) {
     const scores = new Map();
@@ -149,10 +152,16 @@ export class Retriever {
     constructor(index, embeddings) {
         if (index?.schemaVersion !== 1 || !Array.isArray(index.chunks))
             throw new Error('Unsupported or invalid chunks.json');
+        if (new Set(index.chunks.map(chunk => chunk.id)).size !== index.chunks.length)
+            throw new Error('Ambiguous passage IDs in chunks.json; run shoalrun index <site-directory> to rebuild publication-qualified IDs. Existing passage embeddings can be reused.');
         const synonyms = validateSearchSynonyms(index.synonyms);
         const groups = new Map();
-        for (const chunk of index.chunks)
-            groups.set(chunk.variant, [...(groups.get(chunk.variant) ?? []), chunk]);
+        for (const chunk of index.chunks) {
+            let passages = groups.get(chunk.variant);
+            if (!passages)
+                groups.set(chunk.variant, passages = []);
+            passages.push(chunk);
+        }
         this.counts = { total: index.chunks.length, embedded: 0, stale: 0, ...(embeddings ? { model: embeddings.meta.model, dimension: embeddings.meta.dimension } : {}) };
         const rowOf = new Map((embeddings?.meta.ids ?? []).map((id, row) => [id, row]));
         for (const chunk of index.chunks)
@@ -209,6 +218,17 @@ export class Retriever {
     lexical(query, options = {}) {
         return this.byVariant.get(this.variant(options)).search(query, options.limit, keeping(options));
     }
+    // File-backed search still scans its selected publication, but streams scores
+    // into page selection instead of sorting/materializing every passage first.
+    searchPassages(query, queryVector, options = {}) {
+        const variant = this.variant(options);
+        if (!queryVector)
+            return this.byVariant.get(variant).scan(query, keeping(options));
+        const index = this.vectors.get(variant);
+        if (!index)
+            throw new Error('No current embeddings for this publication; run shoalrun index --embed');
+        return index.scan(queryVector, keeping(options));
+    }
     vector(queryVector, options = {}) {
         const index = this.vectors.get(this.variant(options));
         if (!index)

package/dist/search-handler.js

@@ -1,6 +1,7 @@
+import { compareHits } from './retrieval.js';
 import { validateReaderSelection } from './reader-filters.js';
 import { searchSnippetFromParagraphs } from './search-snippet.js';
-import { identifierRescue, searchIdentifiers } from './search-identifier.js';
+import { identifierMatch } from './search-identifier.js';
 import { createSearchResultSelector } from './search-results.js';
 export function createSearchHandler(options) {
     const selectResults = createSearchResultSelector(options.retriever);
@@ -91,17 +92,16 @@ export function createSearchHandler(options) {
             }
             if (!vector && fallbackReason)
                 options.onFallback?.(fallbackReason);
-            // Rank pages after inspecting their passages. A large gallery can otherwise
-            // consume the entire candidate window before page deduplication happens.
-            const retrievalOptions = { ...searchOptions, limit: Number.MAX_SAFE_INTEGER };
-            let hits = vector
-                ? options.retriever.vector(vector, retrievalOptions)
-                : options.retriever.lexical(query.trim(), retrievalOptions);
-            if (vector && limit >= 3 && searchIdentifiers(query).length) {
-                const lexical = options.retriever.lexical(query.trim(), retrievalOptions);
-                hits = identifierRescue(query.trim(), hits, lexical);
+            let candidate;
+            const matchesIdentifier = identifierMatch(query);
+            if (vector && limit >= 3 && matchesIdentifier) {
+                for (const hit of options.retriever.searchPassages(query.trim(), undefined, searchOptions)) {
+                    if (matchesIdentifier(hit) && (!candidate || compareHits(hit, candidate) < 0))
+                        candidate = hit;
+                }
             }
-            const results = selectResults(hits, query.trim(), searchOptions).map(({ chunk, literalSummary }) => ({ url: chunk.url, title: chunk.title, section: chunk.headingPath.at(-1), summary: literalSummary ?? searchSnippetFromParagraphs(chunk.search.paragraphs, query.trim(), options.pageSummaries?.get(`${chunk.variant}:${chunk.docId}`)) }));
+            const hits = selectResults(options.retriever.searchPassages(query.trim(), vector, searchOptions), query.trim(), searchOptions, candidate);
+            const results = hits.map(({ chunk, literalSummary }) => ({ url: chunk.url, title: chunk.title, section: chunk.headingPath.at(-1), summary: literalSummary ?? searchSnippetFromParagraphs(chunk.search.paragraphs, query.trim(), options.pageSummaries?.get(`${chunk.variant}:${chunk.docId}`)) }));
             return json(200, { results, mode: vector ? 'vector' : 'lexical', ...(!vector ? { fallbackReason } : {}) });
         }
         catch {

package/dist/search-identifier.d.ts

@@ -1,3 +1,4 @@
 import type { Hit } from './retrieval.js';
 export declare function searchIdentifiers(query: string): string[];
-export declare function identifierRescue(query: string, semantic: Hit[], lexical: Hit[]): Hit[];
+export declare function identifierRescue<T extends Hit>(query: string, semantic: T[], lexical: T[]): T[];
+export declare function identifierMatch(query: string): ((hit: Hit) => boolean) | undefined;

package/dist/search-identifier.js

@@ -7,11 +7,10 @@ export function searchIdentifiers(query) {
     return [...new Set(identifiers.filter(id => !/\.(?:txt|json|ya?ml|mdx?|[cm]?js|tsx?|html?|css|svg|png|jpe?g|com|org|net)$/i.test(id)))];
 }
 export function identifierRescue(query, semantic, lexical) {
-    const identifiers = searchIdentifiers(query);
-    if (!identifiers.length)
+    const matches = identifierMatch(query);
+    if (!matches)
         return semantic;
-    const matches = identifiers.map(id => new RegExp(`(?<![\\w$.-])${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w$-]|\\.[\\w$])`, 'i'));
-    const candidate = lexical.find(hit => (hit.chunk.search?.paragraphs ?? searchParagraphs(hit.chunk.text)).some(p => matches.every(re => re.test(p))));
+    const candidate = lexical.find(matches);
     if (!candidate)
         return semantic;
     const pages = [...new Set(semantic.map(h => h.chunk.docId))];
@@ -23,3 +22,10 @@ export function identifierRescue(query, semantic, lexical) {
     const position = at < 0 ? remaining.length : at;
     return [...remaining.slice(0, position), candidate, ...remaining.slice(position)];
 }
+export function identifierMatch(query) {
+    const identifiers = searchIdentifiers(query);
+    if (!identifiers.length)
+        return undefined;
+    const matches = identifiers.map(id => new RegExp(`(?<![\\w$.-])${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w$-]|\\.[\\w$])`, 'i'));
+    return hit => (hit.chunk.search?.paragraphs ?? searchParagraphs(hit.chunk.text)).some(p => matches.every(re => re.test(p)));
+}

package/dist/search-results.d.ts

@@ -2,5 +2,5 @@ import type { Hit, LexicalOptions, Retriever } from './retrieval.js';
 type SearchHit = Hit & {
     literalSummary?: string;
 };
-export declare function createSearchResultSelector(retriever: Retriever): (hits: Hit[], query: string, options: LexicalOptions) => SearchHit[];
+export declare function createSearchResultSelector(retriever: Retriever): (hits: Iterable<Hit>, query: string, options: LexicalOptions, rescue?: Hit) => SearchHit[];
 export {};

package/dist/search-results.js

@@ -1,45 +1,59 @@
-import { tokenize } from './retrieval.js';
+import { compareHits, tokenize } from './retrieval.js';
 import { literalSearch } from './search-literal.js';
+import { identifierRescue } from './search-identifier.js';
 // Select landing passages for the search box, without changing passage retrieval
 // used by Ask. A gallery's repeated examples must not crowd other pages out.
 export function createSearchResultSelector(retriever) {
     retriever.requirePreparedSearch();
     const normalized = (text) => tokenize(text).join(' ');
-    return (hits, query, options) => {
+    return (hits, query, options, rescue) => {
         const pages = new Map();
+        const normalizedQuery = normalized(query);
         const literal = literalSearch(query);
-        const literalPages = new Map();
-        if (literal) {
-            for (const hit of hits) {
-                if (literalPages.has(hit.chunk.docId))
-                    continue;
-                const literalSummary = literal(hit.chunk.search.literalLines);
-                if (literalSummary)
-                    literalPages.set(hit.chunk.docId, { ...hit, literalSummary });
-            }
-        }
+        let exact;
+        // Retain at most three candidates per page, independent of its passage
+        // count. Input scores need not be sorted or collected into an array.
         for (const hit of hits) {
-            if (pages.has(hit.chunk.docId))
+            const page = pages.get(hit.chunk.docId) ?? { exactTitle: normalized(hit.chunk.title) === normalizedQuery };
+            if (!page.first || compareHits(hit, page.first) < 0)
+                page.first = hit;
+            if (hit.chunk.search.paragraphs.length && (!page.prose || compareHits(hit, page.prose) < 0))
+                page.prose = hit;
+            const literalSummary = literal?.(hit.chunk.search.literalLines);
+            if (literalSummary && (!page.literal || compareHits(hit, page.literal) < 0))
+                page.literal = { ...hit, literalSummary };
+            pages.set(hit.chunk.docId, page);
+            if (page.exactTitle && (!exact || compareHits(hit, exact) < 0))
+                exact = hit;
+        }
+        const limit = options.limit ?? 8;
+        const candidates = [];
+        for (const page of pages.values()) {
+            const candidate = page.literal ? { rank: page.first, hit: { ...page.literal, score: page.first.score } } : page.prose ? { rank: page.prose, hit: page.prose } : undefined;
+            if (!candidate)
                 continue;
-            // Keep the page's retrieved position, but land on the passage that actually
-            // contains the literal. A nearby token table must not hide the correct row.
-            const exactPassage = literalPages.get(hit.chunk.docId);
-            if (exactPassage)
-                pages.set(hit.chunk.docId, { ...exactPassage, score: hit.score });
-            else if (hit.chunk.search.paragraphs.length)
-                pages.set(hit.chunk.docId, hit);
+            const at = candidates.findIndex(other => compareHits(candidate.rank, other.rank) < 0);
+            candidates.splice(at < 0 ? candidates.length : at, 0, candidate);
+            if (candidates.length > limit)
+                candidates.pop();
+        }
+        let selected = candidates.map(item => item.hit);
+        if (rescue) {
+            selected = identifierRescue(query, selected, [rescue]);
+            const landing = pages.get(rescue.chunk.docId)?.literal;
+            if (landing)
+                selected = selected.map(hit => hit.chunk.docId === rescue.chunk.docId ? { ...landing, score: hit.score } : hit);
         }
         // An exact page-title query is a request for that topic's entry point.
         // Ordinary semantic queries retain their ranking; incidental words do not qualify.
-        const exact = hits.find(hit => normalized(hit.chunk.title) === normalized(query));
         if (exact) {
             const introduction = retriever.pageIntroduction(exact.chunk.docId, options);
-            const landing = introduction ? { chunk: introduction, score: exact.score } : pages.get(exact.chunk.docId);
+            const page = pages.get(exact.chunk.docId);
+            const landing = introduction ? { chunk: introduction, score: exact.score } : page?.literal ?? page?.prose;
             if (landing) {
-                pages.delete(exact.chunk.docId);
-                return [landing, ...pages.values()].slice(0, options.limit ?? 8);
+                return [landing, ...selected.filter(hit => hit.chunk.docId !== exact.chunk.docId)].slice(0, options.limit ?? 8);
             }
         }
-        return [...pages.values()].slice(0, options.limit ?? 8);
+        return selected.slice(0, limit);
     };
 }

package/dist/site-identity.d.ts

@@ -0,0 +1,3 @@
+import type { HeaderConfig, FooterConfig } from './content.js';
+export declare function validateHeader(value: unknown): HeaderConfig;
+export declare function validateFooter(value: unknown): FooterConfig | undefined;