@shoalrun/cli 0.1.0-beta.1 → 1.1.0

package/agent-docs/api-docs/code-reference-settings.sections/converter-snapshot.md

@@ -0,0 +1,58 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> 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 > Code API reference settings
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [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, 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.
+
+## Converter snapshot
+
+A converter writes JSON with `schemaVersion: 1`, `kind: shoalrun-code-reference`, a `programmingLanguage`, producer identity, and a nonempty `symbols` array. The package ships `schemas/code-reference.schema.json`; `shoalrun references check <snapshot.json>` also checks unique IDs, referenced targets, and acyclic parents.
+
+This Kotlin-shaped example illustrates the shared contract. It doesn't imply a bundled Kotlin extractor:
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "shoalrun-code-reference",
+  "programmingLanguage": "kotlin",
+  "producer": { "name": "example-converter", "version": "1.0.0" },
+  "symbols": [{
+    "id": "example.greet",
+    "name": "greet",
+    "kind": "function",
+    "summary": "Create a greeting.",
+    "signatures": ["fun greet(name: String): String"],
+    "parameters": [{ "name": "name", "type": "String", "description": "Reader name." }],
+    "returns": { "type": "String", "description": "A greeting ready to display." }
+  }]
+}
+```
+
+Run a converter explicitly in your workflow, validate its output, then build. Shoalrun doesn't load executable converter plugins during compilation. JavaScript tools can import `validateCodeReference` from `@shoalrun/cli/references`.

package/agent-docs/api-docs/code-reference-settings.sections/descriptions-type-links-and-source-links.md

@@ -0,0 +1,40 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> 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 > Code API reference settings
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [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, 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.
+
+## Descriptions, type links, and source links
+
+Descriptions don't run MDX or expand project directives. Raw HTML is stripped. Use `[Record](symbol:example.Record)` for a symbol link within the same catalog and publication. External links support HTTPS and mailto; relative links and images aren't supported.
+
+Explicit type references create links in parameter, return, yield, base-class, exception, and field information. Signatures remain copyable code. The Python adapter resolves supported local annotation targets statically and keeps unknown or external targets unlinked.
+
+Set `sourceLink.baseUrl` to a repository URL ending at the directory that contains the relative source paths. Include an immutable commit or release in that URL. A source path `sdk/models.py` with line `12` is appended as `/sdk/models.py#L12`. Shoalrun doesn't fetch or publish source files. Without this setting, source links are omitted.

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

@@ -0,0 +1,38 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> 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 > Code API reference settings
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [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, 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.
+
+## HTML, Markdown, and agents
+
+HTML shows symbol context, declarations, member tables, and detailed sections. The tables use local horizontal scrolling instead of shrinking the text on small screens; keyboard readers can focus the scroll region. Copy controls need JavaScript. Grouped pages and complete references keep their content readable without those controls.
+
+Markdown and content exports retain declarations, descriptions, field facts, examples, and links with their resource identity and publication scope. They omit the site's styling and Copy buttons. Agents can read generated pages through discovery tools or content delivery without running the extractor. A caller can select the complete page for export or PDF preparation by its document ID; enabling that page doesn't prebuild PDFs.

package/agent-docs/api-docs/code-reference-settings.sections/metadata-and-selection.md

@@ -0,0 +1,38 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> 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 > Code API reference settings
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [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, 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.
+
+## Metadata and selection
+
+A symbol's explicit `shared` or `requires` classification replaces the catalog's classification. Requirements are evaluated separately for each symbol; a parent's feature requirements don't automatically apply to its children. Strictly classified projects need an explicit classification for eligible public symbols and the complete page. Inherited frontmatter defaults don't satisfy that source-classification requirement.
+
+Visibility, feature grants, access policy, and build reader-filter selection apply before references are combined. An excluded type is left as plain text rather than linked to unavailable content. Reader views remain browsing controls; build/profile selection determines which content is published.

package/agent-docs/api-docs/code-reference-settings.sections/publication-sources.md

@@ -0,0 +1,54 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> 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 > Code API reference settings
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [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, 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.
+
+## Publication sources
+
+Bind a snapshot to each interface release. This example assumes the `sdk` product and versions already exist in `publications`:
+
+```yaml
+codeReferences:
+  sdk:
+    publications:
+      - product: sdk
+        channel: production
+        version: v1
+        language: en
+        source: { kind: file, path: ./reference/v1.json }
+      - product: sdk
+        channel: production
+        version: v2
+        language: en
+        source: { kind: file, path: ./reference/v2.json }
+```
+
+Links, member tables, inline details, and complete references stay within the selected catalog and publication. A full snapshot isn't automatically published as a downloadable asset.

package/agent-docs/api-docs/code-reference-settings.sections/python-adapter-limits.md

@@ -0,0 +1,38 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> 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 > Code API reference settings
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [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, 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.
+
+## Python adapter limits
+
+The packaged adapter requires Python 3.11 or newer and `griffelib==2.4.1`. Its requirements file pins the dependency and archive hash. The source root must contain the requested local module and can't contain symlinks. Extraction rejects roots exceeding 10,000 Python source files or 32 MiB.
+
+Extraction doesn't enable runtime inspection, extensions, external discovery, or alias resolution. The adapter skips aliases and underscore-prefixed members except constructors. It doesn't expand inherited members or execute decorators. Local constructors and supported simple dataclass constructors supply class signatures; unsupported cases stay unspecified. Factory defaults appear as `<factory>` in constructor signatures and retain the source expression in field details.

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

@@ -0,0 +1,32 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> 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 > Code API reference settings
+
+**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, 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
+
+### Next steps
+
+- [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.

package/agent-docs/api-docs/code-reference-settings.sections/symbol-fields.md

@@ -0,0 +1,56 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> 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 > Code API reference settings
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [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, 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
+
+Each symbol needs `id`, `name`, and `kind`. Supported kinds are `module`, `namespace`, `class`, `interface`, `enum`, `type`, `function`, `method`, `constructor`, `property`, `attribute`, and `constant`.
+
+Use these optional fields to describe the interface without supplying executable markup or an arbitrary syntax tree:
+
+| Field                               | Meaning                                                                                                                                              |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `parent`                            | ID of an existing parent symbol. Cycles aren't allowed.                                                                                              |
+| `visibility`                        | `public` by default, or `private`.                                                                                                                   |
+| `summary`, `description`            | Short page summary and inert Markdown description.                                                                                                   |
+| `signatures`                        | Array of declaration strings, including overloads.                                                                                                   |
+| `parameters`                        | Array of `{ name, type?, description?, default? }`.                                                                                                  |
+| `returns`, `yields`                 | `{ type?, description? }`.                                                                                                                           |
+| `raises`                            | Array of `{ name, type?, description?, default? }`.                                                                                                  |
+| `examples`                          | Array of `{ title?, code }`. Examples aren't executed.                                                                                               |
+| `annotation`, `required`, `default` | Field type, whether a value must be supplied, and its default source expression. Unknown requirements stay unmarked. Nullable doesn't mean optional. |
+| `bases`, `constructorSignature`     | Base-type strings and a constructor declaration for a class.                                                                                         |
+| `typeReferences`                    | Mapping from exact type text to an existing symbol ID. Only eligible targets become links; Shoalrun doesn't guess short-name matches.                |
+| `seeAlso`                           | Existing symbol IDs for related reference links.                                                                                                     |
+| `source`                            | `{ path, line? }` with a relative provenance path and optional positive line number.                                                                 |
+
+The snapshot can also include a SHA-256 `sourceDigest`. Unknown fields are rejected. Snapshots are limited to 10,000 symbols and 32 MiB; individual text fields have schema limits.

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

@@ -0,0 +1,151 @@
+---
+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. 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.
+
+## 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.
+
+## 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.
+
+- [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/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.