@shoalrun/cli 0.1.0-beta.1 → 1.0.0

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

@@ -0,0 +1,143 @@
+---
+id: guide.code-api-references
+title: Generate code API references
+summary: Turn Python source and docstrings into SDK reference pages, with
+  separate, grouped, or complete-page layouts.
+type: how-to
+area: api
+subarea: api-generation
+canonical: /api-docs/code-references
+---
+
+# Generate code API 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: [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) > Document an API > Generate code API references
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+A code API reference describes a library's classes, functions, methods, fields, parameters, return values, and exceptions. A guide explains how to accomplish a task; the reference explains what a programmer can call, what to pass, and what comes back. [OpenAPI references](https://www.shoalrun.com/publish/api-references.md) describe HTTP endpoints instead.
+
+Shoalrun reads a converter's JSON snapshot and renders native reference pages. The optional Python adapter extracts local source and docstrings with Griffe. Other languages can supply a converter that writes the same [snapshot format](https://www.shoalrun.com/api-docs/code-reference-settings.md). A Kotlin-shaped snapshot is supported; a Kotlin extractor isn't bundled.
+
+## Before you start
+
+Use an existing documentation project with `@shoalrun/cli` installed, as in [Getting started](https://www.shoalrun.com/start.md). Run the commands below from that project's directory. Extraction needs Python 3.11 or newer and an explicit dependency installation. Normal site builds read the snapshot and don't need Python.
+
+The adapter doesn't import the documented package, execute its code, enable Griffe extensions, or inspect installed modules. Review public source declarations and docstrings before publishing: static extraction doesn't establish that their content is safe to disclose.
+
+## Add Python source
+
+Create `src/sample.py`. This fictional example returns a local dictionary and doesn't contact a service:
+
+```python title="src/sample.py"
+class Client:
+    """Retrieve records for an application."""
+
+    def fetch(self, record_id: str) -> dict[str, str]:
+        """Retrieve a record by its stable identifier.
+
+        Args:
+            record_id: Identifier of the record to retrieve.
+
+        Returns:
+            A mapping containing the record identifier.
+        """
+        return {"id": record_id}
+```
+
+Keep the source root limited to the package you're documenting. The adapter rejects symlinks inside that root, including links to files outside it.
+
+## Extract and validate a snapshot
+
+Create an isolated Python environment and install the adapter's pinned requirements:
+
+```sh
+python3.11 -m venv .venv-reference
+.venv-reference/bin/python -m pip install --require-hashes \
+  -r node_modules/@shoalrun/cli/adapters/python/requirements.txt
+mkdir -p reference
+.venv-reference/bin/python node_modules/@shoalrun/cli/adapters/python/shoalrun_reference.py \
+  --root ./src --module sample --style google --out ./reference/python.json
+npx --no-install shoalrun references check ./reference/python.json
+```
+
+Use `--style google`, `numpy`, or `sphinx` to match the docstring convention. The adapter preserves signatures, supported docstring sections, local source locations, and resolved local type references. It skips aliases and underscore-prefixed members except constructors. It doesn't expand inherited members, execute decorators, or resolve external re-exports. Review the JSON before building.
+
+The check reports `status: "ok"`, the programming language, and the symbol count. Duplicate IDs, missing referenced symbols, cyclic ownership, and invalid fields fail validation. A missing Python dependency stops extraction; Shoalrun doesn't install it during a site build.
+
+## Register the catalog and navigation
+
+Add these settings to `docs.config.yaml`, retaining the project's existing site and publication settings:
+
+```yaml title="docs.config.yaml"
+codeReferences:
+  sdk:
+    source: { kind: file, path: ./reference/python.json }
+    layout: classes
+    singlePage:
+      documentId: reference.sdk.complete
+      slug: /reference/sdk/all
+      title: Complete SDK reference
+    symbols:
+      sample.Client:
+        documentId: reference.sdk.client
+        slug: /reference/sdk/client
+navigation:
+  - { id: sdk-client, doc: reference.sdk.client }
+  - { id: sdk-complete, doc: reference.sdk.complete }
+```
+
+If navigation already exists, append those entries to the appropriate group. References use ordinary `doc:` entries. Explicit document IDs and slugs preserve intentional public identities. Generated defaults follow the catalog and symbol IDs. Renaming a source symbol changes its default identity.
+
+## Choose the reading layout
+
+Use `layout` to control how much detail readers see on a parent page. Individual symbol URLs stay available in every layout. Group the class or module pages in navigation when you want fewer menu entries.
+
+| Layout    | What readers see                                                                                            |
+| --------- | ----------------------------------------------------------------------------------------------------------- |
+| `symbols` | Separate symbol pages with linked member tables. This is the default.                                       |
+| `classes` | Class pages include member details inline. Module pages include their direct functions and class overviews. |
+| `modules` | A module page includes details for its classes, functions, and fields. Submodules form separate groups.     |
+
+`singlePage` independently adds a complete reference for the catalog. It works with any layout. Omit it or set `singlePage: false` to disable it. In a grouped or complete page, links to included symbols jump to their sections; other links retain individual symbol URLs. See the [configuration reference](https://www.shoalrun.com/api-docs/code-reference-settings.md) for defaults and metadata options.
+
+## Build and verify
+
+Build the site, then serve the same output:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun serve site-dist --port 8770
+```
+
+Open `http://127.0.0.1:8770/reference/sdk/client/` and `/reference/sdk/all/`. The class page should include `fetch` details. The complete page should include the module, class, and method. Read their Markdown copies at `/reference/sdk/client.md` and `/reference/sdk/all.md` and verify that signatures, parameter descriptions, and return information remain readable.
+
+Regenerate the snapshot after changing source or docstrings, then validate and rebuild. A site build doesn't rerun the converter. The packaged `examples/code-references` project has a larger sample SDK with models, async methods, overloads, pagination, and exceptions.
+
+## Versions, profiles, and delivery
+
+Bind different snapshots to explicit product/channel/version/language publications when releases have different interfaces. `programmingLanguage: python` describes the source language; publication `language: en` describes the documentation language.
+
+Catalog and per-symbol metadata can declare reader filters, `shared`, and `requires`. Use the same profile for build and export. Grouped and complete pages include only symbols eligible in their publication and build selection; they don't grant access to excluded symbols. See [Publications](https://www.shoalrun.com/publish/publications.md), [Customer editions](https://www.shoalrun.com/publish/deployment-profiles.md), and the [reference](https://www.shoalrun.com/api-docs/code-reference-settings.md) for the configuration.
+
+## HTML, Markdown, and agents
+
+HTML uses compact declaration blocks, linked types, field/default tables, and symbol sections. Tables scroll horizontally on narrow screens and can receive keyboard focus. Copy controls use JavaScript; reading the reference, following symbol links, and scrolling a table don't require it. A full reference is an ordinary generated page, so browser Find can search its content.
+
+Markdown retains declarations, descriptions, tables, examples, and symbol links. It doesn't include Copy controls or the website styling. Content exports preserve typed resource links and scope; PDF workflows can select a grouped page or the complete reference by document ID. Generated symbol pages remain independently addressable even when they're also shown inline elsewhere.
+
+Agents can discover and read the generated pages through the site's indexes and read-only tools, or use the normal content-delivery API. They don't need Python or browser scripts to read published references. Source extraction describes declared interfaces; it doesn't execute examples or prove runtime behavior.
+
+## Related reading
+
+### Reference while working
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md) — Generate HTTP endpoint references when an OpenAPI contract describes the interface.
+
+- [Code API reference settings](https://www.shoalrun.com/api-docs/code-reference-settings.md) — Check catalog settings, snapshot fields, and converter limits.

package/agent-docs/author/agent-overview.md

@@ -20,7 +20,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Tools overview
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Status: Experimental.**
 
@@ -40,7 +40,7 @@ Existing checked plan/apply commands remain available for clients that need them
 
 Compiler checks establish structural validity. They don't establish factual accuracy, clear writing, or a successful reader task. Review the diff, supporting evidence, and rendered documentation before using your project's release process.
 
-Local previews serve the exact captured build and show its freshness. Review reports list task scope, affected HTML/Markdown, findings, checks, and dependencies. The portable authoring skill guides this working-tree workflow. Independent author trials remain separate from these checks. Install the beta CLI through [Getting started](https://www.shoalrun.com/start.md).
+Local previews serve the exact captured build and show its freshness. Review reports list task scope, affected HTML/Markdown, findings, checks, and dependencies. The portable authoring skill guides this working-tree workflow. Independent author trials remain separate from these checks. Install the CLI through [Getting started](https://www.shoalrun.com/start.md).
 
 ## Related reading
 

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.md

@@ -16,12 +16,20 @@ 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-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.0.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.0.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.0.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.0.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.0.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.0.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.0.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.0.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.0.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.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Overview
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 A project's configuration starts at `docs.config.yaml`. The CLI looks for that name by default, and `shoalrun scaffold -n` searches parent directories for it. For a guided workflow, start with [Configure your project](https://www.shoalrun.com/configuration.md). For complete working projects, see [Example configs](https://www.shoalrun.com/config/examples.md).
 
@@ -29,7 +29,7 @@ Each reference below contains the field definitions, defaults, validation rules,
 | [Site and theme settings](https://www.shoalrun.com/config/site.md)                 | `site`, `theme`                                                                                                                       |
 | [Publications and routing settings](https://www.shoalrun.com/config/publishing.md) | `publications`, `navigation`, `redirects`                                                                                             |
 | [Authoring and content settings](https://www.shoalrun.com/config/content.md)       | `authoring`, `frontmatter`, `variables`, `snippets`, `templates`, `callouts`, `badges`, `cookbooks`, `relationships`, `readerFilters` |
-| [API and audit settings](https://www.shoalrun.com/config/apis.md)                  | `apis`, `audit`                                                                                                                       |
+| [API and audit settings](https://www.shoalrun.com/config/apis.md)                  | `apis`, `codeReferences`, `audit`                                                                                                     |
 | [Search and integration settings](https://www.shoalrun.com/config/integrations.md) | `search`, `mcp`, `analytics`                                                                                                          |
 | [Output and export settings](https://www.shoalrun.com/config/outputs.md)           | `metadata`, `exports`, `outputs`                                                                                                      |
 

package/agent-docs/configuration.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 > Configure your project
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 `docs.config.yaml` connects your content, presentation, and publication settings. Start with one file, then extract sections or share defaults when several projects need them. This guide explains how those choices interact and how to inspect the result.
 
@@ -59,7 +59,7 @@ CONFIG_DEMO="$(mktemp -d)"
 mkdir "$CONFIG_DEMO/site"
 cd "$CONFIG_DEMO/site"
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-beta.1
+npm install --save-exact @shoalrun/cli@1.0.0
 npx --no-install shoalrun init . --starter minimal
 ```
 

package/agent-docs/configuration.sections/build-several-sites-from-shared-content.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 > Configure your project
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/change-inherited-lists-deliberately.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 > Configure your project
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/extract-a-section-with-include.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 > Configure your project
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/inspect-and-validate-changes.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 > Configure your project
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/configuration.md)