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

package/agent-docs/styling/themes.md

@@ -15,9 +15,9 @@ canonical: /styling/themes
 
 Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Themes
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Themes
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 The `theme` setting controls how the HTML site looks. It has five keys, and each has a default:
 
@@ -96,7 +96,6 @@ Fonts set here become the `--font-body`, `--font-heading`, and `--font-code` [CS
 The HTML page links stylesheets in this order. Later files override earlier ones.
 
 1. `/assets/site.css`, which imports the base tokens and header styles.
-   - `/assets/theme-preview.css` follows it, on pages that use the [theme previewer](https://www.shoalrun.com/styling/try.md).
 2. `/assets/theme.css`, for a preset other than `shoal`.
 3. `/assets/palette.css`, generated for any palette or mode other than `kelp` in light mode.
 4. `/assets/fonts.css`, generated from `theme.fonts`, unless it's `system` and sets nothing.
@@ -108,6 +107,10 @@ When a site uses a non-default preset, palette, or mode, the `html` element carr
 [data-theme="ledger"] .page-head h1 { letter-spacing: 0; }
 ```
 
+## HTML, Markdown, and agents
+
+Presets and fonts style the HTML page through generated stylesheets. They do not change its Markdown text or add font and layout instructions to the Markdown twin. An agent reading Markdown receives the authored content without needing the theme assets. Keep labels, hierarchy, and instructions meaningful without relying on typography or position alone.
+
 ## Related reading
 
 ### Next steps

package/agent-docs/styling/try.md

@@ -13,11 +13,11 @@ canonical: /styling/try
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Try a theme
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Try a theme
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Pick a shape, a palette, and a mode. This page restyles itself as you choose. Scroll down to see how each option styles the sample content, then copy the config into `docs.config.yaml`.
 
@@ -87,18 +87,6 @@ Readers always see the dark set.
 
 The site follows each reader's system setting, with an optional toggle.
 
-## Add the previewer to a page
-
-Place the component on its own line in any MDX page:
-
-```mdx
-<ThemePreview />
-```
-
-The component takes no attributes. The build then publishes every preset and palette under `/assets/themes/`, so the previewer works on a static host. Sites that don't use the component don't publish those files.
-
-Without JavaScript, and in the Markdown twin, the component shows the preset and palette tables and an example config.
-
 ## Related reading
 
 ### Related topics

package/dist/api.js

@@ -224,7 +224,7 @@ export class ApiReader {
                     if (entries.length === 1 && /^[^?&#\s=]+$/.test(entries[0][0]) && ['string', 'number', 'boolean'].includes(typeof entries[0][1]))
                         queryExpression = `${entries[0][0]}=${encodeURIComponent(String(entries[0][1]))}`;
                 }
-                if (location.startsWith('parameter:')) {
+                if (location.startsWith('parameter:') || location.startsWith('response-header:')) {
                     const value = example.externalValue ? link(example.externalValue, 'Open external example') : inline(queryRule && location === `parameter:query:${queryRule.parameter}` ? queryExpression ?? JSON.stringify(example.value) : JSON.stringify(example.value));
                     const sample = paragraph({ type: 'strong', children: [text(example.title)] }, text(': '), value, ...(example.description ? [text(` — ${example.description}`)] : []));
                     sample.data = { hProperties: { className: ['api-parameter-example'] } };
@@ -465,8 +465,8 @@ export class ApiReader {
         blocks.push(heading(3, 'Responses'));
         for (const [status, initial] of Object.entries(op.responses ?? {})) {
             const { value: response, source: responseSource } = await this.deref(pathSource, initial);
-            if (response.headers || response.links)
-                throw new Error(`Response headers or links need an adapter: ${status}`);
+            if (response.links)
+                throw new Error(`Response links need an adapter: ${status}`);
             const description = String(response.description ?? '').trim();
             const mediaEntries = Object.entries(response.content ?? {});
             const responseBlocks = [];
@@ -474,6 +474,73 @@ export class ApiReader {
             responseBlocks.push({ type: 'docApiResponseHeader', data: { hName: 'div', hProperties: { className: ['api-response-header'] } }, children: [responseHeading, ...mediaEntries.map(([mediaType]) => ({ ...paragraph(inline(mediaType)), data: { hProperties: { className: ['api-response-media'] } } }))] });
             if (description)
                 responseBlocks.push(...parsePlainMarkdown(description));
+            if (response.headers !== undefined && (!response.headers || typeof response.headers !== 'object' || Array.isArray(response.headers)))
+                throw new Error(`Response headers must be a mapping: ${status}`);
+            const headerNames = new Set();
+            const headers = [];
+            for (const [name, initialHeader] of Object.entries(response.headers ?? {})) {
+                // OpenAPI explicitly excludes Content-Type: response.content describes it.
+                if (name.toLowerCase() === 'content-type')
+                    continue;
+                if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name))
+                    throw new Error(`Invalid response header name: ${name}`);
+                if (headerNames.has(name.toLowerCase()))
+                    throw new Error(`Duplicate response header name (case-insensitive): ${name}`);
+                headerNames.add(name.toLowerCase());
+                let header = initialHeader, headerSource = responseSource;
+                let overrideDescription;
+                const seen = new Set();
+                while (header?.$ref) {
+                    if (typeof header.$ref !== 'string')
+                        throw new Error(`Response header reference must be a string: ${name}`);
+                    const allowed = schemaVersion === '3.1' ? ['$ref', 'description', 'summary'] : ['$ref'];
+                    if (Object.keys(header).some(key => !allowed.includes(key)))
+                        throw new Error(`Response header reference ${name} has unsupported siblings`);
+                    for (const field of ['description', 'summary'])
+                        if (header[field] !== undefined && typeof header[field] !== 'string')
+                            throw new Error(`Invalid response header reference ${field}: ${name}`);
+                    // Reference summary has no Header Object counterpart; OAS ignores it.
+                    if (overrideDescription === undefined && header.description !== undefined)
+                        overrideDescription = header.description;
+                    const resolved = await this.ref(headerSource, header.$ref);
+                    if (seen.has(resolved.identity))
+                        throw new Error(`Recursive response header reference: ${name}`);
+                    seen.add(resolved.identity);
+                    header = resolved.value;
+                    headerSource = resolved.source;
+                }
+                if (!header || typeof header !== 'object' || Array.isArray(header))
+                    throw new Error(`Invalid response Header Object: ${name}`);
+                if (header.content !== undefined)
+                    throw new Error(`Response header content needs an adapter: ${name}`);
+                const fields = new Set(['description', 'required', 'deprecated', 'schema', 'style', 'explode', 'example', 'examples']);
+                for (const field of Object.keys(header))
+                    if (!fields.has(field) && !field.startsWith('x-'))
+                        throw new Error(`Unsupported response header field ${field}: ${name}`);
+                for (const field of ['required', 'deprecated', 'explode'])
+                    if (header[field] !== undefined && typeof header[field] !== 'boolean')
+                        throw new Error(`Response header ${field} must be boolean: ${name}`);
+                if (header.description !== undefined && typeof header.description !== 'string')
+                    throw new Error(`Response header description must be a string: ${name}`);
+                if (header.style !== undefined && header.style !== 'simple')
+                    throw new Error(`Response header style must be simple: ${name}`);
+                if (header.schema === undefined)
+                    throw new Error(`Response header requires a schema: ${name}`);
+                if (header.examples !== undefined && (!header.examples || typeof header.examples !== 'object' || Array.isArray(header.examples)))
+                    throw new Error(`Response header examples must be a mapping: ${name}`);
+                const headerDescription = overrideDescription ?? header.description;
+                const detail = [heading(6, name), tagged(paragraph(text(header.required ? 'Required' : 'Optional')), 'api-parameter-presence', { 'data-required': header.required ? 'true' : 'false' })];
+                if (header.deprecated)
+                    detail.push(tagged(paragraph(text('Deprecated response header.')), 'api-deprecated-note'));
+                if (headerDescription)
+                    detail.push(...parsePlainMarkdown(headerDescription));
+                detail.push(paragraph(text(`Serialization: simple; explode: ${header.explode ?? false}.`)));
+                detail.push(...await this.schemaBlocks(headerSource, header.schema, schemaVersion, 6, new Set(), ['response', status, 'header', name], [], headerDescription));
+                await addExamples(headerSource, header, `response-header:${name}`, null, status, detail);
+                headers.push({ type: 'docApiParameter', data: { hName: 'section', hProperties: { className: ['api-parameter', 'api-response-header-field'] } }, children: detail });
+            }
+            if (headers.length)
+                responseBlocks.push(heading(5, 'Response headers'), ...headers);
             for (const [mediaType, media] of mediaEntries) {
                 if (mediaEntries.length > 1)
                     responseBlocks.push(tagged(heading(5, mediaType), 'api-media-heading'));

package/dist/authoring-hints.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationFinding } from './authoring-findings.js';
+/** Suggestions only: the author decides whether native relationships fit the links. */
+export declare function authoringHints(body: string, file: string): ValidationFinding[];

package/dist/authoring-hints.js

@@ -0,0 +1,35 @@
+import { parse } from './semantic-markdown.js';
+const text = (node) => typeof node.value === 'string' ? node.value : (node.children ?? []).map(text).join('');
+const contains = (node, predicate) => predicate(node) || (node.children ?? []).some((child) => contains(child, predicate));
+/** Suggestions only: the author decides whether native relationships fit the links. */
+export function authoringHints(body, file) {
+    let tree;
+    try {
+        tree = parse.parse(body);
+    }
+    catch {
+        return [];
+    } // Compilation reports syntax errors.
+    if (contains(tree, node => node.name === 'RelatedReading'))
+        return [];
+    const nodes = tree.children ?? [];
+    const definitions = new Map();
+    contains(tree, node => { if (node.type === 'definition')
+        definitions.set(node.identifier, node.url); return false; });
+    const documentLink = (node) => node.type === 'link' && node.url?.startsWith('doc:') || node.type === 'linkReference' && definitions.get(node.identifier)?.startsWith('doc:');
+    for (let index = 0; index < nodes.length; index++) {
+        const heading = nodes[index];
+        if (heading.type !== 'heading' || !/^related (reading|materials?)$/i.test(text(heading).trim()))
+            continue;
+        let end = index + 1;
+        while (end < nodes.length && !(nodes[end].type === 'heading' && nodes[end].depth <= heading.depth))
+            end++;
+        if (!nodes.slice(index + 1, end).some((node) => contains(node, documentLink)))
+            continue;
+        return [{ code: 'authoring.related-reading', severity: 'warning', file,
+                explanation: 'This page has a related-reading or related-material section with document links. Native relationships and RelatedReading may suit these connections.',
+                reference: 'guide.related-reading',
+                nextAction: 'Read guide.related-reading and guide.component.related-reading. Inspect the purpose and reason for each connection before choosing native relationships; keep manual links when they better fit the page.' }];
+    }
+    return [];
+}

package/dist/authoring-project.d.ts

@@ -27,7 +27,7 @@ export declare const projectToolFailure: (error: unknown) => {
     schemaVersion: number;
     status: "error";
     error: {
-        code: "invalid_input" | "internal_error" | "unknown_source" | "unsafe_path" | "invalid_project";
+        code: "invalid_input" | "internal_error" | "unsafe_path" | "unknown_source" | "invalid_project";
         message: string;
     };
 };

package/dist/authoring-project.js

@@ -1,3 +1,4 @@
+import { authoringHints } from './authoring-hints.js';
 import { createHash } from 'node:crypto';
 import { readFile, readdir, realpath } from 'node:fs/promises';
 import path from 'node:path';
@@ -121,6 +122,7 @@ export async function inspectAuthoringProject(configFile, options = {}) {
                         publication: { channel: fm.channel ?? value.publications?.defaults?.channel, version: fm.version ?? value.publications?.defaults?.version, language: fm.language ?? defaultLanguage(value), ...(fm.publications ? { publications: fm.publications } : {}) },
                         access: fm.access ?? null, aliases: [] });
                     bodies.set(relative(file), doc.body);
+                    findings.push(...authoringHints(doc.body, relative(file)).map(({ location, ...hint }) => hint));
                 }
                 catch (error) {
                     findings.push({ code: 'project.invalid-page', severity: 'error', file: relative(file), explanation: error.message, nextAction: 'Repair the page metadata and inspect again.', reference: 'guide.frontmatter' });

package/dist/authoring-validation.js

@@ -1,3 +1,4 @@
+import { authoringHints } from './authoring-hints.js';
 import { chmod, mkdir, mkdtemp, readFile, readdir, realpath, stat, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -188,6 +189,7 @@ export async function validateAuthoringChangesWithHooks(configFile, options, hoo
             for (const file of affected) {
                 try {
                     const doc = await readDocument(path.join(shadow, file), loaded.value.frontmatter, undefined, capture.buffers.get(file).toString('utf8'));
+                    report.findings.push(...authoringHints(doc.body, file));
                     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(doc.frontmatter.id))
                         report.findings.push({ ...finding('validation.identity', 'Page IDs must begin with a letter/digit and contain only letters, digits, dots, underscores or hyphens.', 'Choose a stable ID and update its references.'), file, reference: 'guide.frontmatter-reference' });
                 }

package/dist/code-samples.js

@@ -37,9 +37,10 @@ function resolve(sample) {
         headers.push(['Content-Type', sample.contentType]);
     return { headers, notes };
 }
+const isHead = (sample) => sample.method.toUpperCase() === 'HEAD';
 const hasBody = (sample) => !!sample.body && !sample.body.formFields.length;
 function curl(sample) {
-    const parts = [`curl --request ${sample.method.toUpperCase()}`, `--url ${shellQuote(sample.url)}`];
+    const parts = [isHead(sample) ? 'curl --head' : `curl --request ${sample.method.toUpperCase()}`, `--url ${shellQuote(sample.url)}`];
     for (const auth of sample.auth) {
         if (auth.kind === 'header')
             parts.push(`--header ${shellQuote(`${auth.name}: ${auth.value}`)}`);
@@ -76,7 +77,11 @@ function javascript(sample, node) {
     const lines = notes.map(note => `// ${note}`);
     if (node)
         lines.push('// Node.js 18 or newer provides a global fetch.');
-    lines.push(`const response = await fetch(${JSON.stringify(sample.url)}, {`, options.join(',\n'), '});', '', 'const data = await response.json();', 'console.log(data);');
+    lines.push(`const response = await fetch(${JSON.stringify(sample.url)}, {`, options.join(',\n'), '});', '');
+    if (isHead(sample))
+        lines.push('console.log(response.status, Object.fromEntries(response.headers));');
+    else
+        lines.push('const body = await response.text();', "const mediaType = (response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();", "const data = body && (mediaType === 'application/json' || mediaType.endsWith('+json')) ? JSON.parse(body) : body;", 'console.log(data);');
     return lines.join('\n');
 }
 function python(sample) {
@@ -87,12 +92,16 @@ function python(sample) {
     if (hasBody(sample))
         lines.push(`data = ${JSON.stringify(sample.body.text)}`);
     const args = ['url', ...(headers.length ? ['headers=headers'] : []), ...(hasBody(sample) ? ['data=data'] : [])];
-    lines.push('', `response = requests.${sample.method.toLowerCase()}(${args.join(', ')})`, 'print(response.json())');
+    lines.push('', `response = requests.${sample.method.toLowerCase()}(${args.join(', ')})`);
+    if (isHead(sample))
+        lines.push('print(response.status_code, dict(response.headers))');
+    else
+        lines.push('body = response.text', "media_type = response.headers.get('Content-Type', '').split(';')[0].strip().lower()", "data = response.json() if body and (media_type == 'application/json' or media_type.endswith('+json')) else body", 'print(data)');
     return lines.join('\n');
 }
 function go(sample) {
     const { headers, notes } = resolve(sample);
-    const imports = ['"fmt"', '"io"', '"net/http"', ...(hasBody(sample) ? ['"strings"'] : [])].sort();
+    const imports = ['"fmt"', ...(isHead(sample) ? [] : ['"io"']), '"net/http"', ...(hasBody(sample) ? ['"strings"'] : [])].sort();
     const bodyVar = hasBody(sample) ? [`body := strings.NewReader(${goString(sample.body.text)})`, ''] : [];
     const bodyArg = hasBody(sample) ? 'body' : 'nil';
     const lines = [
@@ -103,8 +112,7 @@ function go(sample) {
         '\tif err != nil {', '\t\tpanic(err)', '\t}',
         ...headers.map(([name, value]) => `\treq.Header.Set(${JSON.stringify(name)}, ${JSON.stringify(value)})`),
         '\tres, err := http.DefaultClient.Do(req)', '\tif err != nil {', '\t\tpanic(err)', '\t}',
-        '\tdefer res.Body.Close()', '\tdata, err := io.ReadAll(res.Body)', '\tif err != nil {', '\t\tpanic(err)', '\t}',
-        '\tfmt.Println(string(data))', '}'
+        '\tdefer res.Body.Close()', ...(isHead(sample) ? ['\tfmt.Println(res.StatusCode, res.Header)'] : ['\tdata, err := io.ReadAll(res.Body)', '\tif err != nil {', '\t\tpanic(err)', '\t}', '\tfmt.Println(string(data))']), '}'
     ];
     return lines.join('\n');
 }
@@ -117,12 +125,14 @@ function java(sample) {
         'import java.net.URI;', 'import java.net.http.HttpClient;', 'import java.net.http.HttpRequest;', 'import java.net.http.HttpResponse;', '',
         'public class Main {', '    public static void main(String[] args) throws Exception {', '        HttpClient client = HttpClient.newHttpClient();',
         '        HttpRequest request = HttpRequest.newBuilder()', `            .uri(URI.create(${JSON.stringify(sample.url)}))`, ...builder, bodyMethod, '            .build();',
-        '        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());', '        System.out.println(response.body());', '    }', '}'
+        '        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());', ...(isHead(sample) ? ['        System.out.println(response.statusCode());', '        System.out.println(response.headers().map());'] : ['        System.out.println(response.body());']), '    }', '}'
     ].join('\n');
 }
 function php(sample) {
     const { headers, notes } = resolve(sample);
     const array = ['    CURLOPT_URL => ' + phpString(sample.url), `    CURLOPT_CUSTOMREQUEST => ${phpString(sample.method.toUpperCase())}`, '    CURLOPT_RETURNTRANSFER => true'];
+    if (isHead(sample))
+        array.push('    CURLOPT_NOBODY => true', '    CURLOPT_HEADER => true');
     if (headers.length)
         array.push(`    CURLOPT_HTTPHEADER => [\n${headers.map(([name, value]) => `        ${phpString(`${name}: ${value}`)}`).join(',\n')}\n    ]`);
     if (hasBody(sample))
@@ -136,15 +146,16 @@ function php(sample) {
 }
 function ruby(sample) {
     const { headers, notes } = resolve(sample);
-    const klass = sample.method.toLowerCase() === 'get' ? 'Get' : sample.method[0].toUpperCase() + sample.method.slice(1);
+    const method = sample.method.toLowerCase();
+    const klass = method[0].toUpperCase() + method.slice(1);
     const lines = [
         ...notes.map(note => `# ${note}`),
         "require 'net/http'", "require 'uri'", '',
-        `uri = URI(${rubyString(sample.url)})`, 'http = Net::HTTP.new(uri.host, uri.port)', 'http.use_ssl = true', '',
+        `uri = URI(${rubyString(sample.url)})`, 'http = Net::HTTP.new(uri.host, uri.port)', 'http.use_ssl = uri.scheme == \'https\'', '',
         `request = Net::HTTP::${klass}.new(uri)`,
         ...headers.map(([name, value]) => `request[${rubyString(name)}] = ${rubyString(value)}`),
         ...(hasBody(sample) ? [`request.body = ${rubyString(sample.body.text)}`] : []),
-        '', 'response = http.request(request)', 'puts response.body'
+        '', 'response = http.request(request)', ...(isHead(sample) ? ['puts response.code', 'puts response.to_hash'] : ['puts response.body'])
     ];
     return lines.join('\n');
 }
@@ -159,7 +170,7 @@ function csharp(sample) {
         `        var request = new HttpRequestMessage(new HttpMethod(${JSON.stringify(sample.method.toUpperCase())}), ${JSON.stringify(sample.url)});`,
         ...contentHeaders.map(([name, value]) => `        request.Headers.TryAddWithoutValidation(${JSON.stringify(name)}, ${JSON.stringify(value)});`),
         ...(hasBody(sample) ? [`        request.Content = new StringContent(${csharpString(sample.body.text)}, Encoding.UTF8, ${JSON.stringify(contentType)});`] : []),
-        '        var response = await client.SendAsync(request);', '        Console.WriteLine(await response.Content.ReadAsStringAsync());', '    }', '}'
+        '        var response = await client.SendAsync(request);', ...(isHead(sample) ? ['        Console.WriteLine((int)response.StatusCode);', '        Console.WriteLine(response.Headers);', '        Console.WriteLine(response.Content.Headers);'] : ['        Console.WriteLine(await response.Content.ReadAsStringAsync());']), '    }', '}'
     ].join('\n');
 }
 // cURL comes first: the Markdown twin and agent bundle keep only that one.

package/dist/compiler-config.d.ts

@@ -58,6 +58,7 @@ export declare function configField(value: unknown, key: string): unknown;
 export declare function resolvedCompilerConfig(value: unknown): ResolvedCompilerConfig;
 /** A section-level mapping guard for validators that accept arbitrary YAML. */
 export declare function configMappingAt(value: unknown, setting: string): ConfigMapping;
+export declare function navigationHeading(outputs: unknown): string | false;
 export declare function navigationCounts(outputs: unknown): boolean;
 /**
  * Apply the compiler's existing required-section checks at their original

package/dist/compiler-config.js

@@ -18,6 +18,19 @@ export function configMappingAt(value, setting) {
         throw new Error(`${setting} must be a mapping`);
     return value;
 }
+export function navigationHeading(outputs) {
+    const navigation = configField(configField(outputs, 'html'), 'navigation');
+    if (navigation === undefined)
+        return 'Explore';
+    const heading = configMappingAt(navigation, 'outputs.html.navigation').heading;
+    if (heading === undefined)
+        return 'Explore';
+    if (heading === false)
+        return false;
+    if (typeof heading !== 'string' || !heading.trim())
+        throw new Error('outputs.html.navigation.heading must be nonempty text or false');
+    return heading.trim();
+}
 export function navigationCounts(outputs) {
     const navigation = configField(configField(outputs, 'html'), 'navigation');
     if (navigation === undefined)

package/dist/compiler.js

@@ -7,7 +7,7 @@ import { resolveTaxonomy } from './taxonomy.js';
 import { resolveMcp } from './mcp-config.js';
 import { fictionalDocument, resolveLlmsDiscovery } from './llms-discovery.js';
 import { resolveAnalytics } from './analytics.js';
-import { navigationCounts } from './compiler-config.js';
+import { navigationCounts, navigationHeading } from './compiler-config.js';
 import { validateAuthoringGuidance } from './authoring-guidance.js';
 import { loadFreshness } from './freshness.js';
 import { resolveAgentDiscovery } from './agent-discovery.js';
@@ -226,6 +226,7 @@ export async function compile(configFile, destination, provenance = {}, options
     // `demo` ships it hidden until a page is opened with ?theme-switcher.
     const themeSwitcherSetting = configField(htmlOptions, 'themeSwitcher') ?? false;
     navigationCounts(config.outputs);
+    navigationHeading(config.outputs);
     if (typeof themeSwitcherSetting !== 'boolean' && themeSwitcherSetting !== 'demo')
         throw new Error('outputs.html.themeSwitcher must be true, false, or demo');
     const themeSwitcher = themeSwitcherSetting !== false;

package/dist/component-names.js

@@ -1 +1 @@
-export const builtinComponentNames = new Set('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 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

@@ -15,6 +15,7 @@ import { validateReaderFilterControl, validateReaderSelection } from './reader-f
 import { walkthroughComponent } from './walkthrough.js';
 import { procedureComponent } from './procedure-components.js';
 import { parsePlainMarkdown, paragraph, link, text } from './semantic-markdown.js';
+import { lowerSectionMarkers, sectionIdentities } from './section-identity.js';
 function isMdxRoot(tree) {
     return !!tree && typeof tree === 'object'
         && tree.type === 'root'
@@ -58,6 +59,7 @@ 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);
     let pluginDepth = 0;
     let tabsIndex = 0;
     let walkthroughIndex = 0;
@@ -98,6 +100,8 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
         if (node.type === 'heading' && stack.length)
             throw new Error(`${sourceFile}: snippet headings need an anchor adapter; put headings in the page`);
         if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+            if (node.name === 'Anchor')
+                throw new Error(`${sourceFile}: <Anchor> must be the single trailing marker of an authored root level-two heading`);
             if (node.name && componentPlugins.has(node.name)) {
                 const start = node.position?.start;
                 const location = `${sourceFile}${start ? `:${start.line}:${start.column}` : ''}: <${node.name}>`;
@@ -693,5 +697,7 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
         }
         return node;
     }
-    return walk(tree, {}, [], current.file);
+    const transformed = walk(tree, {}, [], current.file);
+    sectionIdentities(transformed, current.file);
+    return transformed;
 }

package/dist/content-delivery-contract.d.ts

@@ -0,0 +1,108 @@
+/** Browser-safe delivery contracts. These types do not import the compiler. */
+export type ContentPublication = {
+    channel: string;
+    version: string;
+    language: string;
+};
+export type ContentFormat = 'html' | 'markdown';
+export type ContentRef = {
+    kind: 'page';
+    documentId: string;
+} | {
+    kind: 'section';
+    documentId: string;
+    sectionId: string;
+} | {
+    kind: 'snippet';
+    id: string;
+};
+export type ContentFile = {
+    path: string;
+    bytes: number;
+    digest: string;
+};
+export type ContentAsset = ContentFile & {
+    mediaType: string;
+};
+export type ContentAnchor = {
+    id: string;
+    exportedId: string;
+    title?: string;
+};
+export type ContentLink = {
+    key: string;
+    kind: 'resource' | 'canonical' | 'external' | 'asset';
+    href: string;
+    ref?: ContentRef;
+    fragment?: string;
+    query?: string;
+    asset?: string;
+};
+export type ContentRepresentation = ContentAsset & {
+    anchors: ContentAnchor[];
+    links: ContentLink[];
+};
+export type ContentResource = {
+    ref: ContentRef;
+    publication: ContentPublication;
+    title: string;
+    summary: string;
+    type: string;
+    canonicalUrl?: string;
+    source?: {
+        documentId?: string;
+        snippetId?: string;
+        valuesDigest?: string;
+    };
+    representations: Partial<Record<ContentFormat, ContentRepresentation>>;
+    assets: string[];
+    externalDependencies: Array<{
+        url: string;
+        kind: 'image';
+    }>;
+};
+export type ContentManifest = {
+    schemaVersion: 1;
+    kind: 'shoalrun-content-export';
+    digest: string;
+    publicBase: string;
+    publication: ContentPublication;
+    review: {
+        status: 'ok' | 'required';
+        apis: Array<{
+            apiId: string;
+            digest: string;
+        }>;
+    };
+    resources: ContentResource[];
+    assets: ContentAsset[];
+    files: ContentFile[];
+    diagnostics: Array<{
+        code: string;
+        documentId?: string;
+        message: string;
+    }>;
+};
+export type ContentResult = {
+    resource: Readonly<ContentResource>;
+    representation: Readonly<ContentRepresentation>;
+    format: ContentFormat;
+    content: string;
+    revision: string;
+};
+export interface ContentSnapshot {
+    readonly revision: string;
+    readonly publication: Readonly<ContentPublication>;
+    list(): readonly Readonly<ContentResource>[];
+    get(ref: ContentRef, options: {
+        format: ContentFormat;
+        signal?: AbortSignal;
+    }): Promise<ContentResult>;
+    dispose(): void;
+}
+export type ContentErrorCode = 'invalid_manifest' | 'not_found' | 'unsupported_format' | 'stale_revision' | 'network_error' | 'invalid_content' | 'disposed';
+export declare class ContentDeliveryError extends Error {
+    readonly code: ContentErrorCode;
+    constructor(code: ContentErrorCode, message: string);
+}
+export declare function contentRefKey(ref: ContentRef): string;

package/dist/content-delivery-contract.js

@@ -0,0 +1,15 @@
+export class ContentDeliveryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ContentDeliveryError';
+    }
+}
+export function contentRefKey(ref) {
+    switch (ref.kind) {
+        case 'page': return JSON.stringify(['page', ref.documentId]);
+        case 'section': return JSON.stringify(['section', ref.documentId, ref.sectionId]);
+        case 'snippet': return JSON.stringify(['snippet', ref.id]);
+    }
+}

package/dist/content-delivery-transport.d.ts

@@ -0,0 +1,3 @@
+export declare function freeze<T>(value: T): T;
+export declare function sha256(bytes: Uint8Array): Promise<string>;
+export declare function readBounded(response: Response, limit: number, signal: AbortSignal): Promise<Uint8Array>;

package/dist/content-delivery-transport.js

@@ -0,0 +1,47 @@
+import { ContentDeliveryError } from './content-delivery-contract.js';
+export function freeze(value) { if (value && typeof value === 'object') {
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        freeze(child);
+} return value; }
+export async function sha256(bytes) { return [...new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes))].map(byte => byte.toString(16).padStart(2, '0')).join(''); }
+export async function readBounded(response, limit, signal) {
+    const declared = response.headers.get('content-length');
+    if (declared && (!/^\d+$/.test(declared) || Number(declared) > limit)) {
+        await response.body?.cancel().catch(() => { });
+        throw new ContentDeliveryError('invalid_content', 'Response exceeds the content size limit.');
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        return new Uint8Array();
+    const abort = () => { void reader.cancel(signal.reason).catch(() => { }); };
+    signal.addEventListener('abort', abort, { once: true });
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const next = await reader.read();
+            signal.throwIfAborted();
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (size > limit) {
+                await reader.cancel();
+                throw new ContentDeliveryError('invalid_content', 'Response exceeds the content size limit.');
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return bytes;
+}

package/dist/content-delivery-validation.d.ts

@@ -0,0 +1,7 @@
+import type { ContentManifest, ContentRef } from './content-delivery-contract.js';
+export declare const safeContentPath: (value: any) => value is string;
+export declare const validContentPublication: (value: any) => boolean;
+export declare function validContentRef(value: any): value is ContentRef;
+export declare function validateContentManifest(value: any, maxResources?: number, maxResourceBytes?: number): asserts value is ContentManifest;
+/** Shared metadata validation; transport supplies its file/asset inventory policy. */
+export declare function validateContentResources(resources: any[], expectedPublication: unknown, assets: Set<string>, checkRepresentation: (value: any) => boolean, publicBase?: string): void;