@shoalrun/cli 0.1.0-beta.1 → 1.1.0

package/agent-docs/start.md

@@ -16,11 +16,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Prerequisites
 
@@ -36,7 +36,7 @@ Install an exact version of the beta and initialize the minimal starter:
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-beta.1
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init .
 ```
 

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

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Add the page to navigation
 

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

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Build and check both outputs
 

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

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Build this site
 

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

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Check writing style
 

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

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Create a page
 

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

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Make it yours
 

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

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Migrating from GitHub Packages
 

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

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Prerequisites
 

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

@@ -16,13 +16,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Related reading
 

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

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/start.md)
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You'll scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
-> **Beta:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between beta releases.
+> **Upgrades:** Pin an exact version and review release notes before upgrading. Rebuild and check HTML, Markdown, and any application content consumers before deploying.
 
 ## Start your own project
 
@@ -38,7 +38,7 @@ Install an exact version of the beta and initialize the minimal starter:
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-beta.1
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init .
 ```
 

package/agent-docs/status.md

@@ -16,11 +16,11 @@ Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navi
 
 Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Project > Project status
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
-Shoalrun is in beta for publishing documentation for people and agents from the same source. This site is built with it. Install the public `@shoalrun/cli` npm package through [Getting started](https://www.shoalrun.com/start.md). No account or package token is needed.
+Shoalrun 1.0 publishes documentation for people and agents from the same source. This site is built with it. Install the public `@shoalrun/cli` npm package through [Getting started](https://www.shoalrun.com/start.md). No account or package token is needed.
 
-The [features overview](https://www.shoalrun.com/features.md) summarizes the platform on one page. The capabilities below include `0.1.0-beta.1`.
+The [features overview](https://www.shoalrun.com/features.md) summarizes the platform on one page. The capabilities below describe `1.0.0`.
 
 ## What works today
 
@@ -38,6 +38,8 @@ The [features overview](https://www.shoalrun.com/features.md) summarizes the pla
 
 - **API documentation.** [OpenAPI sources](https://www.shoalrun.com/publish/api-references.md) supply reference pages, named examples, request samples, and contracts for individual operations. Authors can combine generated references with guides and review imported API content before publishing it.
 
+- **SDK references.** [Code API references](https://www.shoalrun.com/api-docs/code-references.md) use Python source and docstrings or a converter snapshot. Choose separate symbols, inline class/module pages, and an optional complete reference, with linked types and field defaults.
+
 - **Search and documentation tools.** Built-in search works in the browser without a model key. Optional [semantic search and cited answers](https://www.shoalrun.com/search-and-chat.md) use your configured providers. Read-only [Model Context Protocol (MCP) tools](https://www.shoalrun.com/publish/mcp.md) let agents search and read pages or sections. They run through a local stdio process or a public HTTP endpoint on Node or Vercel.
 
 - **Publishing and measurement.** Local previews and checks support static publishing, with Node and Vercel serving options. Optional [browser analytics](https://www.shoalrun.com/author/analytics.md) and [HTTP MCP analytics](https://www.shoalrun.com/publish/mcp-analytics.md) send events through adapters to your chosen service. Both are off by default; their guides describe the event fields, filtering, and configuration.
@@ -62,7 +64,7 @@ These are intended additions, without a promised release date.
 
 ## Current limits
 
-- **Beta stability.** Configuration, extension points, and output formats can still change. There is no stable release or compatibility promise yet.
+- **Upgrade checks.** Pin exact versions and review release notes before upgrading. Rebuild and verify the site and application content consumers before deploying. Older release lines aren't maintained; experimental features keep their lifecycle labels.
 - **Component extensibility.** [Trusted custom components](https://www.shoalrun.com/author/components/custom.md) lower into shared content, with a portable authoring skill. Arbitrary executable MDX remains unsupported. Project CSS, browser modules, and configured build extensions are trusted project code.
 - **API coverage.** OpenAPI and JSON Schema support is partial; check the [support reference](https://www.shoalrun.com/api-docs/support.md) against your source. Request examples are copyable, but Shoalrun doesn't provide a live API explorer that sends requests.
 - **Private content.** Reader views don't restrict access to published files. Shoalrun has no built-in reader authentication, and its HTTP MCP endpoint currently serves one selected public publication. Host-level authorization is a separate responsibility.

package/agent-docs/styling/themes.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Themes
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 The `theme` setting controls how the HTML site looks. It has five keys, and each has a default:
 
@@ -60,7 +60,7 @@ Each preset ships its own fonts, so the site looks the same on every operating s
 | `ledger` | Source Serif 4 | JetBrains Mono | JetBrains Mono   |
 | `vice`   | Figtree        | Jost           | System monospace |
 
-The fonts are Latin variable fonts under the SIL Open Font License. The build copies them to `/assets/fonts/` with their license files. A browser downloads only the faces a page uses, and the page preloads its body font. Characters outside the Latin set use the system fallback. Until a font arrives, the page uses a local font resized to match it. Text doesn't shift when the bundled font loads. Agents read the Markdown twins, which load no fonts.
+The fonts are Latin variable fonts under the SIL Open Font License. The build copies them to `/assets/fonts/` with their license files. A browser downloads the faces a page uses; preload hints can start key font downloads earlier. Characters outside the Latin set use the system fallback. Until a font arrives, the page uses a local font resized to match it. A fallback can still look different from the final font, especially when a custom face has different metrics. Agents read the Markdown twins, which load no fonts.
 
 To use system fonts only, set `fonts: system`. Each preset then falls back to its system font stack.
 
@@ -84,9 +84,13 @@ theme:
 ```
 
 - `family` is the name CSS uses. A plain string, such as `headings: Acme Display`, names a font without shipping files. Use it for a font that [project CSS](https://www.shoalrun.com/author/css.md) loads, or one installed on readers' machines.
-- `files` lists local `.woff2`, `.woff`, `.ttf`, or `.otf` files, relative to the config file that declares them. The build copies them to `/assets/fonts/project/`. File names can use letters, numbers, dots, dashes, and underscores, and two files can't share a name.
+- `files` lists local `.woff2`, `.woff`, `.ttf`, or `.otf` files, relative to the config file that declares them. The build copies them to content-versioned URLs under `/assets/fonts/project/`. File names can use letters, numbers, dots, dashes, and underscores, and two files can't share a name.
 - Each file can set `style` (`normal` or `italic`) and `weight`, such as `400` or `"100 900"`. The default weight, `"100 900"`, suits variable fonts; give each static file its own weight.
 
+Since 1.0.0
+
+Local custom body and heading faces are preloaded to start their downloads earlier. Versioned custom-font URLs support long-lived caching; changing a font's bytes changes its URL. Bundled font URLs revalidate so a development browser doesn't keep an older file indefinitely. These settings reduce late font loading, but don't guarantee that every custom font matches its fallback without a visible change. Family names supplied without local files don't create a preload.
+
 A missing file, an unsupported format, or an unknown key fails the build. Check that your font license allows web embedding.
 
 Fonts set here become the `--font-body`, `--font-heading`, and `--font-code` [CSS tokens](https://www.shoalrun.com/author/css.md), each followed by a system fallback.

package/agent-docs/what-is-shoalrun.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > What is Shoalrun?
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Shoalrun is a documentation compiler for product and API docs. It reads project configuration, Markdown and supported MDX pages, and optional local OpenAPI files. From those sources, it builds a site for people and readable Markdown pages for agents. The normal build is deterministic: it makes no model calls or network requests.
 
@@ -43,7 +43,7 @@ Optional ingredients, recipes, and cookbooks extend the same idea to tasks. An i
 
 ## Where it stands
 
-The public documentation site shows output built by Shoalrun. Install the beta CLI from npm using [Getting started](https://www.shoalrun.com/start.md). The [project status](https://www.shoalrun.com/status.md) lists implemented capabilities and current limits.
+The public documentation site shows output built by Shoalrun. Install the CLI from npm using [Getting started](https://www.shoalrun.com/start.md). The [project status](https://www.shoalrun.com/status.md) lists implemented capabilities and current limits.
 
 ## Related reading
 

package/assets/search-lexical.js

@@ -57,10 +57,21 @@ export async function search(query, context) {
     const matched = terms.filter(term => match(title, term) || match(summary, term) || match(text, term) || headings.some(heading => match(heading, term)));
     if (!matched.length) continue;
     let score = 0;
-    for (const term of terms) score += weight(title, term, title.startsWith(term.term) ? 12 : 8) || weight(summary, term, 4) || (headings.some(heading => match(heading, term)) ? 3 : 0) || weight(text, term, 1);
+    let contentScore = 0;
+    for (const term of terms) {
+      const termScore = weight(title, term, title.startsWith(term.term) ? 12 : 8) || weight(summary, term, 4) || (headings.some(heading => match(heading, term)) ? 3 : 0) || weight(text, term, 1);
+      score += termScore;
+      if (!fallbackStopWords.has(term.term)) contentScore += termScore;
+    }
     const section = filtered || terms.every(term => match(title, term)) ? undefined : doc.headings.find((heading, index) => terms.every(term => match(headings[index], term)));
-    hits.push({ score, matched: matched.length, partialMatched: matched.filter(term => !fallbackStopWords.has(term.term)).length, result: { url: section ? `${doc.url}#${section.id}` : doc.url, title: doc.title, summary: doc.summary, section: section?.title } });
+    hits.push({ score, contentScore, matched: matched.length, partialMatched: matched.filter(term => !fallbackStopWords.has(term.term)).length, result: { url: section ? `${doc.url}#${section.id}` : doc.url, title: doc.title, summary: doc.summary, section: section?.title } });
   }
-  const complete = hits.filter(hit => hit.matched === terms.length);
-  return (complete.length ? complete : hits.filter(hit => hit.partialMatched > 0)).sort((a, b) => (complete.length ? b.matched - a.matched : b.partialMatched - a.partialMatched) || b.score - a.score || a.result.title.localeCompare(b.result.title)).slice(0, context.limit).map(hit => hit.result);
+  const contentTerms = terms.filter(term => !fallbackStopWords.has(term.term)).length;
+  // Filler words shape the sentence, not the subject. A page that covers every
+  // content term is complete even when it omits "how", "do", or "the"; otherwise
+  // a page that happens to repeat filler words can hide the focused result.
+  const complete = contentTerms === 0
+    ? hits.filter(hit => hit.matched === terms.length)
+    : hits.filter(hit => hit.partialMatched === contentTerms);
+  return (complete.length ? complete : hits.filter(hit => hit.partialMatched > 0)).sort((a, b) => (complete.length ? b.contentScore - a.contentScore : b.partialMatched - a.partialMatched) || b.score - a.score || a.result.title.localeCompare(b.result.title)).slice(0, context.limit).map(hit => hit.result);
 }

package/dist/artifact-bundle.d.ts

@@ -59,6 +59,7 @@ export type ArtifactAssemblyInput = {
     colorMode: 'light' | 'dark' | 'system';
     generatedFontsCss?: string;
     fontFiles: string[];
+    projectFontAssets: Map<string, Buffer>;
     fonts: SiteFonts;
     shareImages: ShareSettings;
     shareFor: (doc: Document) => {

package/dist/artifact-bundle.js

@@ -12,6 +12,8 @@ import { fictionalDocument, optionalDocument, resolveLlmsDiscovery } from './llm
 import { boundedDiscovery } from './compact-discovery.js';
 import { iconLicenseFile } from './icons.js';
 import { peleLicenseFile } from './diagrams.js';
+import { fontMediaType } from './fonts.js';
+import { createHash } from 'node:crypto';
 import { defaultShareSvg, faviconSvg, fillShareTemplate, renderPng, touchIconSvg } from './share-images.js';
 import { paletteCatalog, paletteCss, presetCatalog, resolvePalette } from './palettes.js';
 import { heading, link, list, paragraph, renderMarkdown, root, searchIndex, shareCardText, text } from './content.js';
@@ -148,10 +150,16 @@ export async function assembleArtifacts(input) {
     }
     if (generatedFontsCss)
         addPublicArtifact('/assets/fonts.css', generatedFontsCss.replaceAll('url("/assets/', `url("${basePath}/assets/`));
+    const addFont = (route, bytes, immutable) => {
+        addPublicArtifact(route, bytes);
+        const type = fontMediaType(route);
+        if (type)
+            headers[publicPath(route)] = { 'Content-Type': type, 'Cache-Control': immutable ? 'public, max-age=31536000, immutable' : 'public, max-age=0, must-revalidate', ETag: `"${createHash('sha256').update(bytes).digest('hex')}"` };
+    };
     for (const file of fontFiles)
-        addPublicArtifact(`/assets/fonts/${path.basename(file)}`, await readFile(file));
-    for (const route of new Set(fonts.faces.map(face => face.route)))
-        addPublicArtifact(route, await readFile(fonts.faces.find(face => face.route === route).file));
+        addFont(`/assets/fonts/${path.basename(file)}`, await readFile(file), false);
+    for (const [route, bytes] of input.projectFontAssets)
+        addFont(route, bytes, true);
     const shareTemplate = shareImages.template ? await readFile(shareImages.template, 'utf8') : undefined;
     for (const page of rendered) {
         const share = shareFor(page.doc);

package/dist/cli-discovery.d.ts

@@ -1,4 +1,4 @@
 export declare const docsHelp = "Usage: shoalrun docs <command>\n\nRead bundled references (no project or provider key required):\n  search <query> [--json]\n  read <document-id> [--json]\n  outline <document-id> [--json]\n  section <document-id> <section-id> [--json]\n\nSearch and reads accept --site DIRECTORY, --max-tokens N, and publication\nselectors --product P --channel C --version V --language L.\n\nInspect a project:\n  project [--config FILE] [--profile FILE] [--section pages|guidance|configuration|navigation|relationships|templates|findings]\n  source FILE [--config FILE] [--profile FILE]\n  context <document-id> [--config FILE]\n\nValidate and preview edits:\n  baseline --out FILE [--config FILE] [--profile FILE]\n  validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]\n  validation-status REPORT\n  review REPORT [--format json|markdown]\n  preview REPORT [--port PORT]\n\nOther authoring tools: changes, plan, apply, mcp.\nDiscover packaged agent guidance with shoalrun skills list.\n";
 export declare const skillsHelp = "Usage: shoalrun skills list [--json]\n       shoalrun skills read <name> [--json]\n\nList the names, descriptions and local paths of packaged skills, or read a skill.\nThese commands do not install skills or require a project or provider key.\n";
-export declare const cliHelp = "Usage: shoalrun <command>\n\nStart and build:\n  init [directory] [--starter minimal|api-docs|showcase]\n  build [config] [output] [--profile FILE]\n  export [config] --out DIRECTORY [--target NAME] [--profile FILE]\n  dev [config] [output] [--profile FILE] [--port PORT]\n  serve <site-directory> [--host HOST] [--port PORT]\n  check [config] [--json]\n  audit [config]\n  scaffold <template> -n <target> [--config FILE] [--product P]\n\nAgent guidance and offline documentation:\n  skills list [--json]\n  skills read <name> [--json]\n  docs search <query> [--site DIRECTORY] [--product P] [--json]\n  docs read <document-id> [--site DIRECTORY] [--product P] [--json]\n  docs project [--config FILE] [--profile FILE]\n  docs baseline --out FILE [--config FILE] [--profile FILE]\n  docs validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]\n  docs review REPORT [--format json|markdown]\n  docs preview REPORT [--port PORT]\n\nOther commands: config, api, operation, ingredient, recipe, search, index,\nask, answers, ask-log, chat, eval, vercel.\nRun shoalrun docs --help or shoalrun skills --help for discovery commands.\n";
+export declare const cliHelp = "Usage: shoalrun <command>\n\nStart and build:\n  init [directory] [--starter minimal|api-docs|showcase]\n  build [config] [output] [--profile FILE]\n  export [config] --out DIRECTORY [--target NAME] [--profile FILE]\n  dev [config] [output] [--profile FILE] [--port PORT]\n  serve <site-directory> [--host HOST] [--port PORT]\n  check [config] [--json]\n  references check <snapshot.json>\n  audit [config]\n  scaffold <template> -n <target> [--config FILE] [--product P]\n\nAgent guidance and offline documentation:\n  skills list [--json]\n  skills read <name> [--json]\n  docs search <query> [--site DIRECTORY] [--product P] [--json]\n  docs read <document-id> [--site DIRECTORY] [--product P] [--json]\n  docs project [--config FILE] [--profile FILE]\n  docs baseline --out FILE [--config FILE] [--profile FILE]\n  docs validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]\n  docs review REPORT [--format json|markdown]\n  docs preview REPORT [--port PORT]\n\nOther commands: config, api, operation, ingredient, recipe, search, index,\nask, answers, ask-log, chat, eval, vercel.\nRun shoalrun docs --help or shoalrun skills --help for discovery commands.\n";
 export declare function runSkillsCommand(args: string[]): Promise<string>;

package/dist/cli-discovery.js

@@ -43,6 +43,7 @@ Start and build:
   dev [config] [output] [--profile FILE] [--port PORT]
   serve <site-directory> [--host HOST] [--port PORT]
   check [config] [--json]
+  references check <snapshot.json>
   audit [config]
   scaffold <template> -n <target> [--config FILE] [--product P]
 

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readCodeReference } from './code-reference-model.js';
 import { runExportCommand, exportHelp } from './content-export-command.js';
 import { cliHelp, docsHelp, skillsHelp, runSkillsCommand } from './cli-discovery.js';
 import { compareDocumentSnapshots } from './document-sync.js';
@@ -99,6 +100,12 @@ try {
     else if (command === 'skills') {
         process.stdout.write(await runSkillsCommand([subcommand, ...rest].filter((value) => value !== undefined)));
     }
+    else if (command === 'references') {
+        if (subcommand !== 'check' || rest.length !== 1)
+            throw new Error('Usage: shoalrun references check <snapshot.json>');
+        const snapshot = await readCodeReference(path.resolve(rest[0]));
+        process.stdout.write(JSON.stringify({ status: 'ok', programmingLanguage: snapshot.programmingLanguage, symbols: snapshot.symbols.length }) + '\n');
+    }
     else if (command === 'init') {
         const args = [subcommand, ...rest].filter((item) => item !== undefined);
         let directory = '.';

package/dist/code-reference-model.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+export declare const codeReferenceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"shoalrun-code-reference">;
+    programmingLanguage: z.ZodString;
+    producer: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        extractorVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    sourceDigest: z.ZodOptional<z.ZodString>;
+    symbols: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            function: "function";
+            constructor: "constructor";
+            module: "module";
+            type: "type";
+            namespace: "namespace";
+            class: "class";
+            interface: "interface";
+            enum: "enum";
+            method: "method";
+            property: "property";
+            attribute: "attribute";
+            constant: "constant";
+        }>;
+        parent: z.ZodOptional<z.ZodString>;
+        visibility: z.ZodDefault<z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>>;
+        summary: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        annotation: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        bases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        constructorSignature: z.ZodOptional<z.ZodString>;
+        typeReferences: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        signatures: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            default: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        returns: z.ZodOptional<z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        yields: z.ZodOptional<z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        raises: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            default: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            code: z.ZodString;
+        }, z.core.$strict>>>;
+        seeAlso: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        source: z.ZodOptional<z.ZodObject<{
+            path: z.ZodString;
+            line: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CodeReferenceSnapshot = z.infer<typeof codeReferenceSchema>;
+export type CodeSymbol = CodeReferenceSnapshot['symbols'][number];
+export type CodeReference = {
+    catalog: string;
+    programmingLanguage: string;
+    symbol: CodeSymbol;
+    sourceUrl?: string;
+    layout?: 'symbols' | 'classes' | 'modules';
+    complete?: boolean;
+};
+export declare function validateCodeReference(value: unknown): CodeReferenceSnapshot;
+export declare function readCodeReference(file: string, root?: string): Promise<CodeReferenceSnapshot>;

package/dist/code-reference-model.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+const text = z.string().max(100_000);
+const id = z.string().min(1).max(512).regex(/^[^\s\x00-\x1f]+$/, 'Symbol IDs cannot contain whitespace or control characters');
+const detail = z.object({ name: z.string().min(1).max(512), type: text.optional(), description: text.optional(), default: text.optional() }).strict();
+export const codeReferenceSchema = z.object({
+    schemaVersion: z.literal(1),
+    kind: z.literal('shoalrun-code-reference'),
+    programmingLanguage: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+    producer: z.object({ name: z.string().min(1).max(100), version: z.string().min(1).max(100), extractorVersion: z.string().max(100).optional() }).strict(),
+    sourceDigest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    symbols: z.array(z.object({
+        id, name: z.string().min(1).max(512),
+        kind: z.enum(['module', 'namespace', 'class', 'interface', 'enum', 'type', 'function', 'method', 'constructor', 'property', 'attribute', 'constant']),
+        parent: id.optional(), visibility: z.enum(['public', 'private']).default('public'),
+        summary: z.string().max(1000).optional(), description: text.optional(),
+        annotation: text.optional(), default: text.optional(), required: z.boolean().optional(),
+        bases: z.array(text).max(100).optional(), constructorSignature: text.optional(),
+        typeReferences: z.record(z.string().min(1).max(512), id).optional(),
+        signatures: z.array(text).max(100).optional(),
+        parameters: z.array(detail).max(1000).optional(),
+        returns: z.object({ type: text.optional(), description: text.optional() }).strict().optional(),
+        yields: z.object({ type: text.optional(), description: text.optional() }).strict().optional(),
+        raises: z.array(detail).max(1000).optional(),
+        examples: z.array(z.object({ title: z.string().max(512).optional(), code: text }).strict()).max(100).optional(),
+        seeAlso: z.array(id).max(1000).optional(),
+        source: z.object({ path: z.string().min(1).max(1000).regex(/^(?!\/)(?!.*(?:^|\/)\.{1,2}(?:\/|$))[^/\\\x00:]+(?:\/[^/\\\x00:]+)*$/), line: z.number().int().positive().optional() }).strict().optional()
+    }).strict()).min(1).max(10_000)
+}).strict();
+export function validateCodeReference(value) {
+    const result = codeReferenceSchema.parse(value);
+    const symbols = new Map();
+    for (const symbol of result.symbols) {
+        if (symbols.has(symbol.id))
+            throw new Error(`Duplicate code symbol ${symbol.id}`);
+        symbols.set(symbol.id, symbol);
+    }
+    const complete = new Set();
+    for (const symbol of result.symbols) {
+        for (const target of [symbol.parent, ...symbol.seeAlso ?? [], ...Object.values(symbol.typeReferences ?? {})])
+            if (target && !symbols.has(target))
+                throw new Error(`${symbol.id}: unknown code symbol ${target}`);
+        const seen = new Set([symbol.id]);
+        let parent = symbol.parent;
+        while (parent && !complete.has(parent)) {
+            if (seen.has(parent))
+                throw new Error(`${symbol.id}: cyclic symbol ownership`);
+            seen.add(parent);
+            parent = symbols.get(parent)?.parent;
+        }
+        for (const id of seen)
+            complete.add(id);
+    }
+    return result;
+}
+export async function readCodeReference(file, root) {
+    const canonical = await realpath(file);
+    if (root) {
+        const base = await realpath(root);
+        if (canonical !== base && !canonical.startsWith(base + path.sep))
+            throw new Error('Code reference source escapes the project root');
+    }
+    if (canonical.split(path.sep).some(part => /^\.env(?:\.|$)|^\.git$|\.(?:local|override)\.md$/i.test(part)))
+        throw new Error('Private local files cannot be code reference sources');
+    const info = await stat(canonical);
+    if (!info.isFile() || info.size > 32 * 1024 * 1024)
+        throw new Error('Code reference source must be a regular JSON file at most 32 MiB');
+    const bytes = await readFile(canonical);
+    if (bytes.length > 32 * 1024 * 1024)
+        throw new Error('Code reference source exceeds 32 MiB');
+    return validateCodeReference(JSON.parse(bytes.toString('utf8')));
+}

package/dist/code-references.d.ts

@@ -0,0 +1,23 @@
+import { type CodeReference } from './code-reference-model.js';
+import { type loadConfig } from './config.js';
+import { type ReaderFiltersConfig, type ReaderSelection } from './reader-filters.js';
+import { type Document, type Variant } from './content-source.js';
+import type { AuthoredPublicationConfig, AuthoredPublicationPlan } from './publication-plan.js';
+export declare function codeDocumentId(catalog: string, symbol: string): string;
+export declare function materializeCodeReferences(input: {
+    config: AuthoredPublicationConfig & {
+        codeReferences?: unknown;
+    };
+    loaded: Awaited<ReturnType<typeof loadConfig>>;
+    plan: AuthoredPublicationPlan;
+    base: string;
+    basePath: string;
+    variants: Variant[];
+    language: string;
+    readerFilters?: ReaderFiltersConfig;
+    contentFilter?: ReaderSelection;
+    dependencies: Set<string>;
+    allowRouteCollisions?: boolean;
+}): Promise<void>;
+/** Imported prose is inert Markdown; it never enters MDX or project directive expansion. */
+export declare function renderCodeReference(reference: CodeReference, doc: Document, documents: Map<string, Document>): any;