@shoalrun/cli 0.1.0-beta.1 → 1.1.0

package/agent-docs/author/components.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Overview
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, footnotes, and autolinks) and the MDX components below. Each component family has a page with syntax, attributes, HTML and Markdown behavior, and limits. Component names and attributes are case-sensitive. Unknown components, dynamic MDX expressions, and exports fail the build because they have no shared HTML and Markdown representation. The build drops `import` lines, so imported components aren't available.
 
@@ -60,6 +60,7 @@ Start with the reader's task, then open the linked reference before choosing syn
 - [Walkthroughs](https://www.shoalrun.com/author/components/walkthroughs.md) — code explained step by step beside a scrolling code pane.
 - [Hero](https://www.shoalrun.com/styling/layouts.md) — a landing page opener with a title, tagline, and action buttons.
 - [Section](https://www.shoalrun.com/styling/layouts.md) — a full-width band on a splash page.
+- [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) — include additional sections in selected builds using configured facets.
 - [ReaderSection, ReaderChoice, and ReaderFilter](https://www.shoalrun.com/author/reader-views.md) — marked sections, choice buttons, and in-page filter controls.
 - [FrontmatterReference](https://www.shoalrun.com/author/frontmatter-reference.md) — publish this project's built-in and declared page fields as a live reference.
 

package/agent-docs/author/reader-views.md

@@ -17,13 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 A reader view changes which pages appear in navigation and search. It also controls document cards and marked sections within pages. The site still publishes one URL for each page. A first-time visitor sees all content; a choice is saved in the browser and added to the URL so it can be shared.
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Try the controls here
 

package/agent-docs/author/reader-views.sections/configure-the-choices.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Configure the choices
 

package/agent-docs/author/reader-views.sections/connect-your-own-control.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Connect your own control
 

package/agent-docs/author/reader-views.sections/how-it-works-for-agents.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## How it works for agents
 

package/agent-docs/author/reader-views.sections/mark-pages.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Mark pages
 

package/agent-docs/author/reader-views.sections/mark-sections-and-add-an-entry-choice.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Mark sections and add an entry choice
 

package/agent-docs/author/reader-views.sections/place-filter-controls.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Place filter controls
 

package/agent-docs/author/reader-views.sections/try-the-controls-here.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Try the controls here
 

package/agent-docs/changelog/code-api-references.md

@@ -0,0 +1,44 @@
+---
+id: change.code-api-references
+title: Shoalrun 1.0 — SDK references and smoother font loading
+summary: Generate code API references from source and docstrings, choose how
+  readers browse them, and load custom fonts earlier.
+type: changelog-entry
+area:
+  - api
+  - appearance
+  - project
+subarea:
+  - api-generation
+  - appearance-themes
+  - project-releases
+canonical: /changelog/code-api-references
+date: 2026-11-06
+releaseVersion: 1.0.0
+---
+
+# Shoalrun 1.0 — SDK references and smoother font loading
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 1.0: SDK references and font loading
+
+**Published: 2026-11-06.**
+
+**Version: 1.0.0.**
+
+Upgrade to CLI `1.0.0` and rebuild to apply these changes. Regenerate a code-reference snapshot whenever its source or docstrings change.
+
+## [Generate SDK references](https://www.shoalrun.com/api-docs/code-references.md)
+
+Turn Python source and docstrings into native reference pages with declarations, linked types, field defaults, parameters, and examples. Other languages can bring a converter using the same JSON format. Choose separate symbol pages, inline class or module references, and an optional complete reference on one page. Publication and customer-profile selection apply to every layout; HTML, Markdown, content delivery, and PDF workflows retain the selected content.
+
+## [Load custom fonts earlier](https://www.shoalrun.com/styling/themes.md)
+
+Local custom body and heading fonts get preload hints and versioned asset URLs for caching. Bundled fonts revalidate instead of remaining stale in a development browser.
+
+## Stable npm release channel
+
+Shoalrun 1.0 uses npm's `latest` channel. Publication verifies distribution tags separately from the upload, so interrupted tagging can resume without uploading the same version again. Future prereleases keep a stable `latest` in place.

package/agent-docs/changelog/facet-typescript.md

@@ -0,0 +1,54 @@
+---
+id: change.facet-typescript
+title: Build selection and TypeScript references
+summary: Select additional sections for each build, generate TypeScript SDK
+  references, and improve search queries written as questions.
+type: changelog-entry
+area:
+  - publishing
+  - api
+  - discovery
+  - project
+subarea:
+  - publishing-builds
+  - api-generation
+  - discovery-search
+  - project-releases
+canonical: /changelog/facet-typescript
+date: 2026-11-07
+releaseVersion: 1.1.0
+---
+
+# Build selection and TypeScript references
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 1.1: Build selection and TypeScript
+
+**Published: 2026-11-07.**
+
+**Version: 1.1.0.**
+
+Upgrade to CLI `1.1.0` and rebuild your site and application exports.
+
+## [Choose sections for each build](https://www.shoalrun.com/author/components/for-facet.md)
+
+Choose which sections each build includes using any configured facet and its choices. `ForFacet` uses your existing `contentFilter` to omit unmatched sections from Markdown, search, and expanded resources. A shared customer page with additional internal notes is one example. It needs no customer profile. The authoring skill covers facet selection and checks for content crossing builds.
+
+## [Generate TypeScript SDK references](https://www.shoalrun.com/api-docs/typescript-references.md)
+
+Extract a public TypeScript entry point and JSDoc into native reference pages with overloads, linked types, optional methods, and readonly properties. Install `typescript@5.9.3` explicitly for extraction; normal site builds use the saved JSON. The authoring skill covers this workflow, and Shoalrun's [content client reference](https://www.shoalrun.com/content-delivery/sdk/all.md) provides a real example.
+
+## [Find docs with questions](https://www.shoalrun.com/author/search.md)
+
+Browser and CLI keyword search give content terms priority over filler words, so a focused page can match a question without repeating every word. Shoalrun's docs also recognize more common search vocabulary through configured synonyms.
+
+## [Check intentional format differences](https://www.shoalrun.com/author/components/only.md)
+
+HTML-only `Only` blocks carry `data-markdown-ignore` for compatible parity checks. Tooltip and info-hint content remains covered by the HTML/Markdown comparison.
+
+## [Load the right agent skill](https://www.shoalrun.com/contribute/agent-skills.md)
+
+Connect complete skill folders to your agent's discovery directory, use explicit loading instructions in the project, and follow a short checklist at the start of each bundled skill. CLI skill listing remains separate from native agent discovery.

package/agent-docs/changelog.md

@@ -16,12 +16,28 @@ Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navi
 
 Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > All changes
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Updates to Shoalrun and its documentation. Each entry identifies the affected versions and any upgrade steps. Earlier entries retain their private-prototype release context.
 
 ## Latest changes
 
+- 2026-11-07
+
+  Version 1.1.0
+
+  [Build selection and TypeScript references](https://www.shoalrun.com/changelog/facet-typescript.md)
+
+  Select additional sections for each build, generate TypeScript SDK references, and improve search queries written as questions.
+
+- 2026-11-06
+
+  Version 1.0.0
+
+  [Shoalrun 1.0 — SDK references and smoother font loading](https://www.shoalrun.com/changelog/code-api-references.md)
+
+  Generate code API references from source and docstrings, choose how readers browse them, and load custom fonts earlier.
+
 - 2026-11-05
 
   Version 0.1.0-alpha.19

package/agent-docs/cli.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 The public `@shoalrun/cli` package supplies the `shoalrun` command. It needs Node.js 22.12 or newer. Follow [Getting started](https://www.shoalrun.com/start.md) to install it from npm, then run commands as `npx --no-install shoalrun <command>`. Framework contributors can build the source checkout and run `node framework/dist/cli.js <command>` from its root.
 
@@ -244,6 +244,16 @@ These commands print configuration and API operation details for inspection.
 
 `operation inspect` compiles the whole project without writing a site. When the operation isn't found in the selected publications, it prints `"status": "missing-variant"` and still exits with code 0. Put flags after the optional config path. An unknown or repeated flag fails before the project is compiled.
 
+## Validate code reference snapshots
+
+`references check` validates a converter's snapshot without invoking Python, running a converter, or building the site:
+
+```sh
+shoalrun references check ./reference/python.json
+```
+
+Success prints JSON with `status: "ok"`, `programmingLanguage`, and the symbol count. Invalid schema fields, duplicate IDs, missing symbol targets, or cyclic parents fail with exit code 1. See [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for extraction and [Code API reference settings](https://www.shoalrun.com/api-docs/code-reference-settings.md) for the snapshot contract.
+
 ## Audit a project and API sources
 
 ### `check`

package/agent-docs/cli.sections/audit-a-project-and-api-sources.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/author-pages.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/build-and-serve.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/inspect-config-and-operations.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/npm-scripts-in-this-repository.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

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

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/search-and-chat.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/start-a-project.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/validate-code-reference-snapshots.md

@@ -0,0 +1,41 @@
+---
+id: reference.cli
+title: CLI reference
+summary: Commands, arguments, defaults, output, and errors.
+type: reference
+area: authoring
+subarea: authoring-command-line
+canonical: /cli
+---
+
+# CLI reference
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
+
+**Updated: 2026-11-07.**
+
+Parent page: [Full Markdown page](/cli.md)
+
+The public `@shoalrun/cli` package supplies the `shoalrun` command. It needs Node.js 22.12 or newer. Follow [Getting started](https://www.shoalrun.com/start.md) to install it from npm, then run commands as `npx --no-install shoalrun <command>`. Framework contributors can build the source checkout and run `node framework/dist/cli.js <command>` from its root.
+
+Commands that return data print JSON to standard output. On an error, the CLI prints `{"status":"error","message":"..."}` to standard error and exits with code 1. A config argument defaults to `docs.config.yaml` in the current directory unless noted.
+
+[Diagrams](https://www.shoalrun.com/author/components/diagrams.md) render without a browser: Pele handles Mermaid syntax, and D2 handles D2 source. Development installs include Puppeteer for browser UI tests; production package installs don't need it.
+
+Since 0.1.0-alpha.18
+
+Product selectors, `dev --profile`, and `get_publications` discovery add product-aware workflows. Existing productless commands keep their publication scope.
+
+## Validate code reference snapshots
+
+`references check` validates a converter's snapshot without invoking Python, running a converter, or building the site:
+
+```sh
+shoalrun references check ./reference/python.json
+```
+
+Success prints JSON with `status: "ok"`, `programmingLanguage`, and the symbol count. Invalid schema fields, duplicate IDs, missing symbol targets, or cyclic parents fail with exit code 1. See [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for extraction and [Code API reference settings](https://www.shoalrun.com/api-docs/code-reference-settings.md) for the snapshot contract.

package/agent-docs/cli.sections/working-tree-authoring-tools.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/config/apis.md

@@ -17,10 +17,14 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > API and audit
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Configure OpenAPI sources, generated references, focused contracts, and local validation. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
 
+## `codeReferences`
+
+Register converter snapshots for code API references independently of OpenAPI sources. Each catalog can choose `layout: symbols`, `classes`, or `modules`, and optionally add a `singlePage` reference. See [Code API reference settings](https://www.shoalrun.com/api-docs/code-reference-settings.md) for source bindings, symbol selection, metadata, and the converter contract.
+
 ## `apis`
 
 A mapping from API ID to its source and operations. See [API references](https://www.shoalrun.com/publish/api-references.md) and [focused contracts](https://www.shoalrun.com/api-docs/focused-contracts.md).

package/agent-docs/config/examples.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 The installed package includes complete projects under `node_modules/@shoalrun/cli/example-configs/`, with their pages and local OpenAPI files. Start with a bundled starter in a new directory:
 
@@ -27,7 +27,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 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 . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
@@ -52,7 +52,7 @@ The `showcase` starter provides 18 connected pages. Its component examples cover
 mkdir my-handbook
 cd my-handbook
 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 . --starter showcase
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/feature-showcase.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 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 . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
@@ -54,7 +54,7 @@ The `showcase` starter provides 18 connected pages. Its component examples cover
 mkdir my-handbook
 cd my-handbook
 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 . --starter showcase
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/minimal-site.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 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 . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/multilingual-help-center.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 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 . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/parcel-api-documentation.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 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 . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 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 . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/shared-company-preset.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 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 . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist