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

package/agent-docs/styling/layouts.md

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -16,9 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
-Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
@@ -33,6 +36,21 @@ layout: wide
 
 An unknown value fails the build. Each preset styles all four layouts, and project CSS can target one through `html[data-layout="wide"]`, `html[data-layout="landing"]`, or `html[data-layout="splash"]`.
 
+## Hide the table of contents or give content more room
+
+To remove the right sidebar labeled “On this page” and widen the content area, set `layout: wide`. It keeps the left navigation and gives interactive tools, large tables, and diagrams more space.
+
+To hide the table of contents without choosing a different layout, set `tocDepth: 0`. To keep an outline with fewer heading levels, use `tocDepth: 2`. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) for the supported depths.
+
+These settings serve different goals:
+
+| Goal                                                         | Page frontmatter                      |
+| ------------------------------------------------------------ | ------------------------------------- |
+| Give interactive content more space while keeping navigation | `layout: wide`                        |
+| Hide “On this page” within the current layout                | `tocDepth: 0`                         |
+| Keep “On this page” but list only main sections              | `tocDepth: 2`                         |
+| Remove navigation and the outline for an entry page          | `layout: landing` or `layout: splash` |
+
 ## Control navigation tabs
 
 The built-in layouts are `docs`, `wide`, `landing`, and `splash`. There is no `custom` layout value; use landing or splash for a custom entry page and style it with project CSS.

package/agent-docs/styling/layouts.sections/build-a-landing-page.md

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -16,11 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 
-Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

package/agent-docs/styling/layouts.sections/build-a-splash-page.md

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -16,11 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 
-Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

package/agent-docs/styling/layouts.sections/control-navigation-tabs.md

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -16,11 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 
-Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

package/agent-docs/styling/layouts.sections/customize-the-hero.md

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -16,11 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 
-Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

package/agent-docs/styling/layouts.sections/hero.md

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -16,11 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 
-Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

package/agent-docs/styling/layouts.sections/hide-the-table-of-contents-or-give-content-more-room.md

@@ -0,0 +1,54 @@
+---
+id: guide.layouts
+title: Page layouts, landing pages, and splash pages
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
+type: reference
+area: appearance
+subarea: appearance-layouts
+canonical: /styling/layouts
+---
+
+# Page layouts, landing pages, and splash pages
+
+> 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)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
+
+**Updated: 2026-10-28.**
+
+Parent page: [Full Markdown page](/styling/layouts.md)
+
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+
+| Layout    | Sidebar | On this page | Use it for                                                                                                               |
+| --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `docs`    | Yes     | Yes          | Guides and reference pages. This is the default.                                                                         |
+| `wide`    | Yes     | No           | Wide tables, diagrams, and API overviews that need the full content width.                                               |
+| `landing` | No      | No           | Home pages and product entry points. A `Hero` replaces the page header.                                                  |
+| `splash`  | No      | No           | Marketing pages built from full-width bands. A `Hero` replaces the page header, and `Section` blocks stack edge to edge. |
+
+```yaml title="Frontmatter"
+layout: wide
+```
+
+An unknown value fails the build. Each preset styles all four layouts, and project CSS can target one through `html[data-layout="wide"]`, `html[data-layout="landing"]`, or `html[data-layout="splash"]`.
+
+## Hide the table of contents or give content more room
+
+To remove the right sidebar labeled “On this page” and widen the content area, set `layout: wide`. It keeps the left navigation and gives interactive tools, large tables, and diagrams more space.
+
+To hide the table of contents without choosing a different layout, set `tocDepth: 0`. To keep an outline with fewer heading levels, use `tocDepth: 2`. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) for the supported depths.
+
+These settings serve different goals:
+
+| Goal                                                         | Page frontmatter                      |
+| ------------------------------------------------------------ | ------------------------------------- |
+| Give interactive content more space while keeping navigation | `layout: wide`                        |
+| Hide “On this page” within the current layout                | `tocDepth: 0`                         |
+| Keep “On this page” but list only main sections              | `tocDepth: 2`                         |
+| Remove navigation and the outline for an entry page          | `layout: landing` or `layout: splash` |

package/agent-docs/styling/layouts.sections/html-markdown-and-agents.md

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -16,11 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 
-Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

package/agent-docs/styling/layouts.sections/related-reading.md

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -16,11 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 
-Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

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)