@shoalrun/cli 1.0.0 → 1.1.0

package/agent-docs/api-docs/code-reference-settings.sections/related-reading.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) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 1.0.0.**
 
 Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
 
-`codeReferences` maps a catalog ID to a local converter snapshot and presentation settings. Start with [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for a complete Python workflow. This setting is separate from `apis`, which registers OpenAPI sources.
+`codeReferences` maps a catalog ID to a local converter snapshot and presentation settings. Start with [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for a complete Python workflow, or use [TypeScript extraction](https://www.shoalrun.com/api-docs/typescript-references.md) for a public source or declaration entry point. This setting is separate from `apis`, which registers OpenAPI sources.
 
 ## Related reading
 

package/agent-docs/api-docs/code-reference-settings.sections/symbol-fields.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) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 1.0.0.**
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
 
 - [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) — Extract a Python snapshot and preview both grouped and complete SDK references.
 
-`codeReferences` maps a catalog ID to a local converter snapshot and presentation settings. Start with [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for a complete Python workflow. This setting is separate from `apis`, which registers OpenAPI sources.
+`codeReferences` maps a catalog ID to a local converter snapshot and presentation settings. Start with [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for a complete Python workflow, or use [TypeScript extraction](https://www.shoalrun.com/api-docs/typescript-references.md) for a public source or declaration entry point. This setting is separate from `apis`, which registers OpenAPI sources.
 
 ## Symbol fields
 

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

@@ -23,7 +23,7 @@ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an
 
 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.
+Shoalrun reads a converter's JSON snapshot and renders native reference pages. The optional Python adapter extracts local source and docstrings with Griffe. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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
 
@@ -134,8 +134,16 @@ Markdown retains declarations, descriptions, tables, examples, and symbol links.
 
 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.
 
+## A real TypeScript example
+
+Shoalrun uses code API references to document its own [public content client](https://www.shoalrun.com/content-delivery/sdk/all.md). Compare the generated [snapshot interface](https://www.shoalrun.com/content-delivery/sdk/content-snapshot.md) with the [integration guide](https://www.shoalrun.com/content-delivery/client.md): the reference follows public TypeScript declarations and JSDoc, while the guide explains the workflow and trust boundaries. The site builds from a saved converter snapshot rather than executing the client or running extraction during every build.
+
 ## Related reading
 
+### Next steps
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
 ### 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.

package/agent-docs/api-docs/code-references.sections/a-real-typescript-example.md

@@ -0,0 +1,38 @@
+---
+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.**
+
+Parent page: [Full Markdown page](/api-docs/code-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
+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. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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.
+
+## A real TypeScript example
+
+Shoalrun uses code API references to document its own [public content client](https://www.shoalrun.com/content-delivery/sdk/all.md). Compare the generated [snapshot interface](https://www.shoalrun.com/content-delivery/sdk/content-snapshot.md) with the [integration guide](https://www.shoalrun.com/content-delivery/client.md): the reference follows public TypeScript declarations and JSDoc, while the guide explains the workflow and trust boundaries. The site builds from a saved converter snapshot rather than executing the client or running extraction during every build.

package/agent-docs/api-docs/code-references.sections/add-python-source.md

@@ -0,0 +1,56 @@
+---
+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.**
+
+Parent page: [Full Markdown page](/api-docs/code-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
+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. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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.
+
+## 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.

package/agent-docs/api-docs/code-references.sections/before-you-start.md

@@ -0,0 +1,40 @@
+---
+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.**
+
+Parent page: [Full Markdown page](/api-docs/code-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
+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. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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.

package/agent-docs/api-docs/code-references.sections/build-and-verify.md

@@ -0,0 +1,47 @@
+---
+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.**
+
+Parent page: [Full Markdown page](/api-docs/code-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
+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. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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.
+
+## 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.

package/agent-docs/api-docs/code-references.sections/choose-the-reading-layout.md

@@ -0,0 +1,46 @@
+---
+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.**
+
+Parent page: [Full Markdown page](/api-docs/code-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
+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. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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.
+
+## 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.

package/agent-docs/api-docs/code-references.sections/extract-and-validate-a-snapshot.md

@@ -0,0 +1,52 @@
+---
+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.**
+
+Parent page: [Full Markdown page](/api-docs/code-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
+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. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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.
+
+## 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.

package/agent-docs/api-docs/code-references.sections/html-markdown-and-agents.md

@@ -0,0 +1,42 @@
+---
+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.**
+
+Parent page: [Full Markdown page](/api-docs/code-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
+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. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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.
+
+## 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.

package/agent-docs/api-docs/code-references.sections/register-the-catalog-and-navigation.md

@@ -0,0 +1,58 @@
+---
+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.**
+
+Parent page: [Full Markdown page](/api-docs/code-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
+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. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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.
+
+## 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.

package/agent-docs/api-docs/code-references.sections/related-reading.md

@@ -0,0 +1,40 @@
+---
+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.**
+
+Parent page: [Full Markdown page](/api-docs/code-references.md)
+
+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. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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.
+
+## Related reading
+
+### Next steps
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
+### 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/api-docs/code-references.sections/versions-profiles-and-delivery.md

@@ -0,0 +1,40 @@
+---
+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.**
+
+Parent page: [Full Markdown page](/api-docs/code-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate TypeScript API references](https://www.shoalrun.com/api-docs/typescript-references.md) — Generate references from public TypeScript declarations and JSDoc.
+
+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. The [TypeScript adapter](https://www.shoalrun.com/api-docs/typescript-references.md) follows a public entry point's declarations and JSDoc. 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.
+
+## 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.

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

@@ -0,0 +1,93 @@
+---
+id: guide.typescript-code-references
+title: Generate TypeScript API references
+summary: Extract a public TypeScript entry point into native SDK reference pages.
+type: how-to
+area: api
+subarea: api-generation
+canonical: /api-docs/typescript-references
+---
+
+# Generate TypeScript 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 TypeScript API references
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.1.0.**
+
+Use the TypeScript adapter to document a library's public functions, interfaces, classes, fields, and methods. It follows one entry module's exports and local re-exports, reads JSDoc, and writes a saved JSON snapshot. Shoalrun renders that snapshot as [code API references](https://www.shoalrun.com/api-docs/code-references.md). Extraction doesn't execute the library or prove its runtime behavior.
+
+## Before you begin
+
+Start with a Shoalrun project and a reviewed TypeScript entry point. The compiler package must include `adapters/typescript/shoalrun-reference.mjs`. Install the maintained compiler API version explicitly in the project that supplies the TypeScript configuration:
+
+```sh
+npm install --save-dev --save-exact typescript@5.9.3
+```
+
+The adapter supports TypeScript 5.9.x. Other compiler versions fail with a dependency message. Use local files, keep the extraction root narrow, and choose a stable module ID before publishing links.
+
+## Extract the public entry point
+
+Run from the project directory. Replace the example entry and module ID with your own:
+
+```sh
+node node_modules/@shoalrun/cli/adapters/typescript/shoalrun-reference.mjs \
+  --project tsconfig.json \
+  --entry src/index.ts \
+  --module example.sdk \
+  --out reference.json
+npx --no-install shoalrun references check reference.json
+```
+
+The entry resolves relative to the TypeScript configuration. The output resolves relative to your current directory. `--root DIRECTORY` optionally narrows the declaration boundary; by default it uses the configuration's directory. Exported declarations outside that root fail extraction. The configuration can remain outside an explicitly selected root.
+
+The adapter accepts source or declaration files, including a built `.d.ts` entry. It retains public overloads, optional methods, readonly properties, merged interface signatures, constructor overloads, type links, and JSDoc descriptions, parameters, returns, and examples. Unknown declarations or unresolved imports fail rather than silently disappearing. Inherited members aren't expanded. Other JSDoc tags aren't converted into runtime constraints.
+
+## Review visibility and defaults
+
+Private, protected, JavaScript private fields, and `@internal` or `@private` declarations are omitted where they can be represented separately. A structural type or copied default containing excluded declarations stops extraction when publishing it would expose those details. Some conditional type expansions also fail because their visibility can't be verified. Expose a named public type or a public value instead of weakening the checks.
+
+Source defaults are copied as expressions, including strings; they aren't evaluated. Review the snapshot for values and prose you don't intend to publish. These are documentation visibility controls, and they don't authenticate a deployment or sanitize arbitrary source text.
+
+Extraction doesn't install dependencies, fetch remote references, run project plugins, or execute documented modules. The local compiler and configuration are trusted inputs. Graph accounting covers compiler options and external type dependency bytes in the source digest. Limits of 10,000 source files and 32 MiB are checked after the compiler loads the graph; they aren't execution or memory isolation.
+
+The output can't overwrite a compiler input, including through symlinks. After successful extraction and validation, the adapter replaces the snapshot atomically. Keep source and snapshots in separate paths.
+
+## Render the snapshot
+
+Add a catalog to the project config:
+
+```yaml
+codeReferences:
+  sdk:
+    source: { kind: file, path: ./reference.json }
+    layout: classes
+    singlePage:
+      documentId: reference.sdk.complete
+      slug: /sdk/all
+      title: Complete SDK reference
+```
+
+Choose `symbols`, `classes`, or `modules` for the grouped presentation. `singlePage` adds an optional complete reference while retaining individual symbol URLs. Configure explicit document IDs and slugs for symbols whose public identities must survive renames. Add the complete reference or selected class/module pages to navigation by document ID. The [catalog settings](https://www.shoalrun.com/api-docs/code-reference-settings.md) describe source bindings, metadata, and routing.
+
+## Check the result
+
+Build the site and review the generated HTML and Markdown. Check overloads, optional and readonly markers, type links, inline members, and copied defaults against the public declarations. Verify that excluded names and values are absent from the snapshot and every grouped or complete page. Refresh the saved snapshot after public source or JSDoc changes; normal site builds don't run extraction.
+
+Shoalrun's own [content client reference](https://www.shoalrun.com/content-delivery/sdk/all.md) is a real example. Its [integration guide](https://www.shoalrun.com/content-delivery/client.md) explains the workflow and trust boundaries alongside the generated declarations.
+
+## HTML, Markdown, and agents
+
+The saved snapshot supplies declarations, descriptions, member tables, examples, and type links to both representations. HTML adds presentation and Copy controls; Markdown retains the reference content without browser scripts. Agents discover the generated pages and keep their product, version, and language scope through the site's normal content delivery. Readers need neither TypeScript nor the source repository to use published references.
+
+## Related reading
+
+### Reference while working
+
+- [Code API reference settings](https://www.shoalrun.com/api-docs/code-reference-settings.md) — Configure snapshot catalogs, grouping, publication scope, and stable routes.