@shoalrun/cli 0.1.0-beta.1 → 1.1.0

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.

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/author/components/for-facet.md

@@ -0,0 +1,127 @@
+---
+id: guide.component.for-facet
+title: ForFacet
+summary: Include additional sections in selected builds using configured reader facets.
+type: reference
+area: components
+subarea: components-prose
+canonical: /author/components/for-facet
+---
+
+# ForFacet
+
+> 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) > Components > ForFacet
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.1.0.**
+
+`ForFacet` selects sections during a build using the same facets as `contentFilter`. It matches any facet declared in `readerFilters.facets` and its configured choices. A shared customer page with additional internal instructions is one example. You don't need a customer profile or feature manifest. **Unmarked sections remain included. Pages without a mark for a selected facet are excluded.** A section guard can't restore an excluded page.
+
+## Syntax
+
+Declare the choices in your project config:
+
+```yaml
+readerFilters:
+  facets:
+    audience:
+      label: Audience
+      options: { customer: Customers, internal: Internal, partner: Partners }
+    region:
+      label: Region
+      options: { eu: Europe, us: United States }
+site:
+  contentFilter: { audience: [customer] }
+```
+
+Give a shared page all applicable page-level marks, then wrap only the additional content:
+
+```mdx
+---
+id: guide.billing
+title: Billing
+summary: Understand billing and operational checks.
+type: guide
+slug: /billing
+audiences: [customer, internal]
+---
+
+Everyone receives these billing instructions.
+
+<ForFacet audience="internal">
+
+## Operational checks
+
+Check whether the original request completed before replaying a failed job.
+
+</ForFacet>
+
+Everyone receives these support instructions.
+```
+
+The customer build omits **Operational checks** and its instructions. A build with `audience: [internal]` includes them. A build without `contentFilter` includes all valid blocks and all otherwise eligible pages.
+
+## Attributes
+
+Each attribute names a facet declared in `readerFilters.facets`. Its required value is a nonempty literal string of configured choice IDs separated by whitespace. The block needs at least one facet attribute and body content. Unknown facets or choices, duplicate attributes or choices, empty values, expressions, and spread attributes fail validation, even inside an excluded ancestor.
+
+| Rule                          | Example                                            | Result                          |
+| ----------------------------- | -------------------------------------------------- | ------------------------------- |
+| Alternatives within one facet | `audience="internal partner"`                      | Either selected choice matches. |
+| Every facet must match        | `audience="internal" region="eu"`                  | Both conditions must pass.      |
+| Unselected facet              | `region="eu"` when the build only selects audience | The region condition passes.    |
+| No build filter               | Any valid block                                    | The block is included.          |
+| Nested guards                 | A ForFacet inside another ForFacet or ForFeature   | Every ancestor must pass.       |
+
+A build selecting `audience: [customer, internal]` includes either audience's blocks. This feature adds information to selected builds; it doesn't replace one version with another. An unfiltered build includes both a customer block and an internal block. Exclusion attributes and arbitrary expressions aren't supported.
+
+## Choose the right section component
+
+Choose according to whether the content must be omitted from the build or hidden in a browser view.
+
+| Component       | Purpose                                   | Content in published files                       |
+| --------------- | ----------------------------------------- | ------------------------------------------------ |
+| `ForFacet`      | Build-time selection by configured facets | Unmatched blocks are omitted.                    |
+| `ReaderSection` | Browser reader-view convenience           | All blocks remain published, including Markdown. |
+| `ForFeature`    | Feature grants from a customer profile    | Unmatched blocks are omitted under that profile. |
+
+`ForFacet` uses whitespace-separated choices. `ReaderSection` uses comma-separated choices. A retained ReaderSection that mentions a build-selected facet produces the warning `reader-section-build-facet`. Review that warning when content should be omitted from the artifact.
+
+## Exports and private selection reports
+
+A portable [content export](https://www.shoalrun.com/publish/content-export.md) uses its own target's `contentFilter`, independently of the website. Set that filter explicitly when an application export must omit internal sections. When section filters differ, canonical fragment fallback fails. The export tree can't prove that the website publishes the same anchor. Include the target resource in the export or link to its page URL without a fragment. [PDF exports](https://www.shoalrun.com/publish/pdf.md) use the target's filter or inherit the site's filter when the target doesn't specify one.
+
+After a successful build or export, `.shoalrun/content-selection.json` identifies the artifact, effective selection, section decisions, and warnings. Its `receipt` field points to the artifact-specific copy in `.shoalrun/content-selection/`. A later build replaces the latest receipt, including when it has no filter. These reports contain source locations and conditions, not section prose; keep them outside served output.
+
+## HTML, Markdown, and agents
+
+Selection happens before headings, anchors, tables of contents, dependency expansion, and rendering. An excluded block contributes no body, heading, snippet expansion, API embed, or referenced image to that artifact. Its text doesn't appear in the site's HTML, Markdown twins, search and passage indexes, or discovery content. Retained content renders normally; ForFacet adds no browser control or JavaScript requirement. Application clients receive the selected export's rendered content.
+
+Globally configured snippet files and component plugins still load and validate. Facet choice catalogs remain public configuration. A separately published OpenAPI contract isn't redacted by removing an API embed. Protect a private deployment with host authentication, and review each separately generated artifact's selection before distributing it.
+
+## Check both builds
+
+Build filtered and unfiltered outputs into separate directories. Check HTML and Markdown for the added instructions, and search the customer output for a distinctive phrase from the excluded section. Check application exports separately. The packaged `example-configs/facet-sections` example provides a complete page and two entry configs for this comparison.
+
+### Test for content crossing builds
+
+Use a small fixture with unique text, heading, snippet, image, and API-example markers inside guarded sections. Confirm each marker appears in a build that includes it, then scan every file in the excluded output for it. Checking both presence and absence prevents a broken fixture from producing a false pass.
+
+Cover the outputs you distribute: HTML and Markdown, search and discovery data, MCP runtime copies, application exports, and PDF preparation. Decode base64 asset payloads and extract text from generated PDFs; a plain text scan can't inspect compressed or encoded content. Check each export target's own selection explicitly.
+
+Interleave builds for different audiences and products in one process. Rebuild a previously broader output with a narrower filter in a temporary directory to check stale-file removal. Confirm sibling output directories remain unchanged and shared document/snippet IDs retain the correct publication scope. Keep production output directories separate, and stop deployment when any build or isolation check fails.
+
+## Related reading
+
+### Next steps
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Build separate sites with page and section selection from shared source.
+
+### Reference while working
+
+- [Reader views](https://www.shoalrun.com/author/reader-views.md) — Compare build-time omission with browser visibility controls.

package/agent-docs/author/components/only.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Content for one format
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Use `<Only>` to author content for one output format. Shared material stays outside the blocks; a block can contain an instruction, explanation, example, or link that serves only one version:
 
@@ -56,6 +56,8 @@ An agent that fetches the direct `.md` URL, or requests this page with `Accept:
 This sentence appears only in the Markdown twin.
 ```
 
+HTML-only blocks are wrapped in an element marked `data-markdown-ignore`. Agent-parity checks can use that marker to tell intentional format-specific content from content that is missing by mistake.
+
 Keep facts, warnings, and task steps that both readers need outside `<Only>`, or provide suitable versions in both formats. You can add or suppress content in either output when that helps its intended reader. Check that each version remains accurate and usable for its task; see [Shoalrun's position on shared and format-specific content](https://www.shoalrun.com/publish/agent-friendliness.md). The browser search index uses the HTML output, so Markdown-only text isn't included in that search. See [publishing and agent representations](https://www.shoalrun.com/publish/output.md) for the full output contract.
 
 ## Related reading