@shoalrun/cli 0.1.0-beta.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.1.0 — 2026-11-07
+
+- Select additional sections with [ForFacet](https://www.shoalrun.com/author/components/for-facet)
+  and existing build facets, without customer profiles. Omit unmatched content
+  before rendering, indexing, and dependency expansion.
+- Generate [TypeScript SDK references](https://www.shoalrun.com/api-docs/typescript-references)
+  from public declarations and JSDoc. Preserve overloads, optional methods,
+  readonly properties, and linked types. The authoring skill covers extraction
+  and build selection; the website includes the generated content client API.
+- Add project skill discovery links, explicit loading instructions, and short
+  task checklists for the bundled agent workflows.
+- Improve browser and CLI keyword ranking for queries written as questions.
+- Mark intentional HTML-only blocks for compatible parity checks while retaining
+  tooltip and info-hint comparison.
+
+Upgrade to CLI `1.1.0` and rebuild the site and application exports. TypeScript
+extraction requires an explicit `typescript@5.9.3` development dependency;
+normal builds consume the saved snapshot without running extraction.
+
+## 1.0.0 — 2026-11-06
+
+- Generate [code API references](https://www.shoalrun.com/api-docs/code-references)
+  from Python source and docstrings, or bring a converter using the shared JSON
+  snapshot format. Choose symbol, class, module, or optional complete-page
+  references with linked types, field defaults, and native content delivery.
+- Preload local custom body and heading fonts, cache custom assets by content,
+  and revalidate bundled fonts. Match the preset's font style and CSS weight
+  selection, including overlapping face registrations.
+- Tighten shared page-header spacing around metadata and page actions.
+- Correct npm distribution tagging and verify it separately from upload.
+  Stable releases use `latest`; later prereleases preserve that stable channel.
+
+Upgrade to CLI `1.0.0` and rebuild. Python extraction is optional and runs
+explicitly; normal site builds consume the saved snapshot without Python.
+
+
 ## 0.1.0-beta.1 — 2026-11-05
 
 - Add custom code-fence highlighting with local TextMate JSON grammars and aliases.

package/CODE-REFERENCES.md

@@ -0,0 +1,156 @@
+# Code API references
+
+Code API references describe a library's classes, functions, methods, fields, parameters, return values, and exceptions. OpenAPI references describe HTTP endpoints. Guides explain how to accomplish tasks; code references explain the interfaces used to accomplish them.
+
+Shoalrun consumes a versioned JSON snapshot and generates native reference pages. The pages participate in navigation, search, publication selection, reader filters, customer-profile pruning, Markdown output, content exports, and PDF exports. They use the site's theme and a compact code-reference layout with signatures and member tables.
+
+## Generate Python references
+
+The optional Python adapter reads local source with Griffe. It doesn't import the documented package or enable runtime inspection, extensions, or external alias resolution. It requires Python 3.11 or newer and the pinned `griffelib` dependency. Normal Shoalrun builds consume the JSON snapshot and don't require Python.
+
+From a checkout of this package:
+
+```sh
+python3.11 -m venv .venv-reference
+.venv-reference/bin/python -m pip install --require-hashes -r adapters/python/requirements.txt
+.venv-reference/bin/python adapters/python/shoalrun_reference.py \
+  --root examples/code-references/python --module orchard \
+  --out examples/code-references/reference.json
+shoalrun references check examples/code-references/reference.json
+shoalrun build examples/code-references/docs.config.yaml site-dist
+```
+
+Use `--style google`, `--style numpy`, or `--style sphinx` for the docstring convention. Review the generated snapshot before publishing it. Public source declarations and their docstrings can contain sensitive information even when extraction doesn't execute code.
+
+The adapter emits locally defined symbols, skips aliases and underscore-prefixed members except constructors, and rejects symlinks in its declared source root. It doesn't expand inherited members, execute decorators, resolve external re-exports, or infer undocumented behavior. Its example SDK stores records in memory and doesn't contact a live service.
+
+## Generate TypeScript references
+
+The optional TypeScript adapter follows the public exports of one entry module, including local re-exports. It reads source or declaration files with the TypeScript compiler API; it doesn't import, execute, or emit documented code. Install `typescript@5.9.3` explicitly in the project that supplies the compiler configuration. The adapter supports TypeScript 5.9.x and rejects other compiler versions.
+
+From that project, run:
+
+```sh
+node node_modules/@shoalrun/cli/adapters/typescript/shoalrun-reference.mjs \
+  --project tsconfig.json --entry src/index.ts --module example.sdk \
+  --out reference.json
+shoalrun references check reference.json
+```
+
+`--entry` resolves relative to the compiler configuration. `--root` defaults to its directory and bounds emitted declarations and relative provenance paths; an entry or exported declaration outside that root fails. The configuration may be outside an explicitly supplied root. `--out` resolves relative to the current working directory. Extraction reports TypeScript errors rather than publishing an incomplete entry point. It doesn't install dependencies, run project plugins, or fetch remote declarations.
+
+Functions, overloads, classes, interfaces, type aliases, enums, and constants retain signatures. Object/interface fields and methods become child symbols. JSDoc descriptions, `@param`, `@returns`, and `@example` supply prose. Private/protected members and `@internal`/`@private` symbols are omitted. Local type references link eligible exports. Inherited members aren't expanded; union alternatives remain in their full alias declaration. Namespace exports and other unsupported declarations fail explicitly. See [the adapter guide](adapters/typescript/README.md) for limits.
+
+Normal site builds still read the saved JSON and don't need TypeScript. Refresh explicitly after changing the public source or JSDoc, then validate and review the generated reference. Type extraction doesn't prove runtime behavior.
+
+## Configure a catalog
+
+```yaml
+codeReferences:
+  sdk:
+    source: { kind: file, path: ./reference.json }
+    pathPrefix: /reference/code
+    symbols:
+      orchard.client.Client:
+        documentId: reference.client
+        slug: /reference/client
+navigation:
+  - { id: client, doc: reference.client }
+```
+
+Paths resolve relative to the file that declares them and must stay inside the project root. Generated pages use `type: code-reference`. The `programmingLanguage` in a snapshot is distinct from a publication's language, such as `en`.
+
+Set `symbols.<symbol-id>.documentId` and `slug` to keep deliberate public identities and URLs. Without these settings, Shoalrun generates deterministic IDs and routes from the catalog and symbol IDs. Moving or renaming a symbol changes those defaults.
+
+Use `include` and `exclude` lists of exact symbol IDs to select public symbols. Private symbols and descendants of private symbols aren't published. `metadata` supplies ordinary page metadata; `symbols.<id>.metadata` overrides it for one symbol. A symbol's explicit `shared` or `requires` classification replaces the catalog's classification. Each symbol's feature requirements are evaluated separately; classification isn't inherited from its parent symbol. Project frontmatter defaults and enforced settings still apply.
+
+For independent product versions, replace `source` with explicit source bindings:
+
+```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 }
+```
+
+Declare those products and versions in `publications` as usual. Each binding uses its own snapshot. Links and member tables include only eligible pages in the same catalog and publication.
+
+## Bring another converter
+
+A converter for Kotlin or another language can emit the same snapshot format. Shoalrun doesn't need to load that converter during compilation. Run it explicitly in your own build workflow, validate its output, and point a catalog at the resulting file.
+
+The contract is [schemas/code-reference.schema.json](schemas/code-reference.schema.json). A minimal snapshot looks like this:
+
+```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": "The greeting." }
+  }]
+}
+```
+
+This illustrates the converter contract; it isn't a bundled Kotlin extractor. Supported symbol kinds are module, namespace, class, interface, enum, type, function, method, constructor, property, attribute, and constant. Optional fields include `parent`, `description`, `raises`, `yields`, `examples`, `seeAlso`, relative source provenance, and a source digest. Symbol IDs must be unique, referenced IDs must exist, and parent ownership must be acyclic. `shoalrun references check` performs these semantic checks as well as schema validation. JavaScript tools can import `validateCodeReference` from `@shoalrun/cli/references`.
+
+Descriptions use inert Markdown, with raw HTML stripped. They don't run MDX or expand project directives. Use `[Record](symbol:orchard.models.Record)` to link a symbol in the same catalog and publication. External links support HTTPS and mailto; relative links and images aren't supported. Use code examples for runnable-looking snippets; extraction doesn't execute or verify those examples.
+
+## Types, fields, and source links
+
+Converters can supply `typeReferences`, mapping the exact type text to a symbol ID in the same snapshot. Shoalrun links those types in parameter, return, yield, base-class, exception, and field descriptions only when the target is published in the same catalog and publication. Excluded targets stay plain text. Signatures retain copyable code. Shoalrun doesn't guess targets from short names.
+
+Field symbols can supply `annotation`, `required`, and `default`. A nullable field can still be required; `required` describes whether a value must be supplied, not whether the type admits null. Unknown requirements stay unmarked. Defaults are source expressions, not evaluated values.
+
+Class symbols can supply `bases` and `constructorSignature`. The Python adapter extracts local constructors and synthesizes simple local dataclass constructors; it leaves unsupported cases unspecified. Dataclass factory defaults appear as `<factory>` in the constructor signature and retain their source expression in the field details.
+
+To show **View source**, configure a catalog's `sourceLink.baseUrl` with an HTTPS repository URL ending at the directory that contains the snapshot's relative source paths. Include the desired immutable commit or release in that URL. For example, a base URL ending in `/blob/<commit>/src` and a source path of `sdk/models.py` produce `/blob/<commit>/src/sdk/models.py#L12` for line 12. Query strings, fragments, and embedded credentials aren't accepted in the base URL. Shoalrun doesn't download source or publish source files automatically. Source links are omitted when no base URL is configured.
+
+## Choose separate or grouped pages
+
+Configure each catalog independently:
+
+```yaml
+codeReferences:
+  sdk:
+    source: { kind: file, path: ./reference.json }
+    layout: classes
+    singlePage:
+      documentId: reference.sdk.complete
+      slug: /reference/sdk/all
+      title: Complete SDK reference
+navigation:
+  - { id: complete-reference, doc: reference.sdk.complete }
+```
+
+`layout` accepts:
+
+| Value | Reading experience |
+| --- | --- |
+| `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` | Module pages include details for the classes, functions, and fields in that module. Submodules have their own grouping. |
+
+Individual symbol pages and URLs remain available in every layout. Choose class or module pages for the main navigation when you want fewer navigation entries. Grouping controls the reading experience; it doesn't remove the underlying symbol pages or change their content-delivery identities.
+
+`singlePage` independently adds a complete reference for the catalog, containing every eligible symbol in the selected publication. It works with any layout. Omit it or set `singlePage: false` to disable it. Within a grouped or complete page, links to symbols included on that page jump to their sections. Links to other symbols retain their individual URLs. Generated heading anchors distinguish repeated headings, such as Parameters and Returns.
+
+The complete page defaults to document ID `reference.<catalog>.complete` and slug `<pathPrefix>/all`. You can configure its `documentId`, `slug`, `title`, `summary`, and `metadata`. Its metadata inherits the catalog's settings; an explicit `shared` or `requires` classification replaces the catalog classification. Strictly classified projects must classify the complete page as well as the symbols.
+
+Each combined page contains only symbols already allowed by its publication, profile grants, visibility, and build audience selection. Enabling a complete page doesn't grant access to excluded content. If no symbols are eligible, no empty complete page is emitted. Complete and grouped pages support the same HTML, Markdown, content export, and PDF workflows as other reference pages. Their default outline depth is two; explicit frontmatter settings can override it.

package/README.md

@@ -2,14 +2,14 @@
 
 Shoalrun builds a documentation website, Markdown pages, and application content from the same Markdown and MDX source. People can browse the site; applications and agents can read stable documents, sections, and snippet instances. Native components keep essential instructions and API details readable in both HTML and Markdown.
 
-This package provides the `shoalrun` CLI, starter projects, agent skills, and offline documentation. It requires Node.js 22.12 or newer. This beta is distributed through the public npm registry. Installation requires no npm account or package token.
+This package provides the `shoalrun` CLI, starter projects, agent skills, and offline documentation. It requires Node.js 22.12 or newer. The package is distributed through the public npm registry. Installation requires no npm account or package token.
 
 ## Install
 
 From the project where you want to keep your documentation:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-beta.1
+npm install --save-dev --save-exact @shoalrun/cli@1.1.0
 ```
 
 ## Create and preview a site
@@ -38,8 +38,10 @@ The [features overview](https://www.shoalrun.com/features) describes the complet
 | --- | --- |
 | A documentation site | Pages, navigation, local preview, themes, palettes, fonts, and project CSS. |
 | Reusable procedures | Recipes, shared ingredients, and cookbooks that help readers choose a complete task. |
-| API reference | OpenAPI operation pages, code examples, focused contracts, and an explicit source-review gate. |
+| HTTP API references | OpenAPI operation pages, code examples, focused contracts, and an explicit source-review gate. |
+| Code API references | [Python docstrings, TypeScript declarations, and converter-supplied symbols](CODE-REFERENCES.md), rendered as native reference pages. |
 | Several product releases | Independent product versions and defaults, publication routes, and a header publication selector. |
+| Build selection | Select pages and `<ForFacet>` sections with configured facets and choices, without customer profiles. |
 | Customer editions | External profiles, SKU revisions, feature grants, and conditional pages or sections. |
 | Application help | HTML and Markdown exports, stable page/section/snippet references, static and REST clients, and instance-safe mounting. |
 | Agent discovery | Markdown twins, compact linked indexes, read-only MCP tools, bundled skills, and offline references. |
@@ -47,10 +49,20 @@ The [features overview](https://www.shoalrun.com/features) describes the complet
 
 Local builds and keyword search need no provider credentials. Semantic retrieval and generated answers use separately configured services; credentials stay server-side. Reader filters are browsing controls, not authorization. Customer profiles select output during compilation; private-edition hosting remains your responsibility.
 
+## Select pages and sections for a build
+
+Declare choices under `readerFilters.facets` and set `site.contentFilter`, for example `{ audience: [customer] }`. Mark shared pages with `audiences: [customer, internal]`, then wrap additional internal instructions in `<ForFacet audience="internal">` blocks. The customer build omits those blocks from HTML, Markdown, search, discovery, and expanded resources. An unfiltered build includes them.
+
+Unmarked sections remain included; pages without a mark for a selected facet are excluded. Every facet attribute must match, with whitespace-separated alternative choices inside each attribute. This is additive information in selected builds, not replacement text. `<ReaderSection>` remains a browser visibility control and its content ships.
+
+Portable export targets need their own `contentFilter`; PDF exports inherit the site's filter unless overridden. Selection reports stay in `.shoalrun/content-selection.json`, outside public output. See the [runnable audience example](example-configs/facet-sections/README.md) and [authoring selection guidance](skills/shoalrun-author/references/facet-selection.md).
+
 ## Match your brand
 
 Use `site.logo`, `site.favicon`, and header settings for site identity. Choose a theme preset and configure `theme.palette`, `theme.mode`, and `theme.fonts`. Use `site.customCss` for changes beyond those settings. Customer profiles can supply deployment-owned branding without storing customer records in the shared source.
 
+Local body and heading fonts registered through `theme.fonts` preload automatically. Custom font URLs include a content digest so browsers can cache them and fetch fresh files after font edits. Preloading starts the download earlier; first-visit layout movement still depends on the font metrics and connection.
+
 Check controls and interactive states as well as article text: a dark header can contain light inputs, menus, and search results. Palette validation doesn't check arbitrary project CSS. See [themes and fonts](https://www.shoalrun.com/styling/themes), the [CSS reference](https://www.shoalrun.com/author/css), and [deployment profiles](DEPLOYMENT-PROFILES.md).
 
 ## Export styled PDFs
@@ -128,7 +140,7 @@ npx --no-install shoalrun skills list
 npx --no-install shoalrun skills read shoalrun-setup
 ```
 
-Ask your agent to read the skill for the task. `skills list` returns names, descriptions, and local instruction-file paths. These commands read the skills; installing the npm package does not automatically install them into your agent.
+Ask your agent to read the skill for the task. `skills list` returns names, descriptions, and local instruction-file paths. These commands read the skills; installing the npm package does not automatically install them into your agent. Expose complete folders through your agent's discovery directory. Copy complete folders into the skill directory supported by your agent, preserving existing skills and reviewing copied versions when upgrading. Give the project's agent instructions an exact path to load before editing, with direct file reading as a fallback. See [skill setup](https://www.shoalrun.com/contribute/agent-skills).
 
 The editing workflow is to capture a baseline, edit source files, validate the changes, then review a local preview. From your documentation project directory:
 
@@ -346,14 +358,14 @@ with a Hero replaces the standard page header and does not display its dates.
 If you previously used the private GitHub Packages alpha, check `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. You can explicitly select the public registry for the upgrade:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-beta.1 --@shoalrun:registry=https://registry.npmjs.org
+npm install --save-dev --save-exact @shoalrun/cli@1.1.0 --@shoalrun:registry=https://registry.npmjs.org
 ```
 
 Commit the updated package manifest and lockfile together. Check that the lockfile resolves `@shoalrun/cli` from `registry.npmjs.org`. Keep any credentials needed by other private dependencies; Shoalrun itself no longer needs a package token.
 
 ## Status and development
 
-This beta may change configuration and output formats between releases. No compatibility promise or maintained older release line is offered yet. Creating and previewing a basic site does not require a model provider or Chrome. Optional provider-backed features require their own configuration.
+Shoalrun 1.0 is the stable release line. Pin exact versions and review release notes for configuration or output-contract changes. Older release lines aren't maintained. Creating and previewing a basic site does not require a model provider or Chrome. Optional provider-backed features require their own configuration.
 
 Shoalrun is maintainer-led and does not accept unsolicited pull requests at this time. The [repository development instructions](https://github.com/shoalrun/shoalrun#develop-the-framework) explain how to build and test your own checkout or fork.
 

package/adapters/python/requirements.txt

@@ -0,0 +1 @@
+griffelib==2.4.1 --hash=sha256:76bc562f936ad1ce198d2cf6d0731bd5c92a7d934b69ef828ef22ee0ffdb62ce

package/adapters/python/shoalrun_reference.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+"""Convert local Python source to Shoalrun code-reference JSON without importing it."""
+import argparse
+import ast
+import hashlib
+import importlib.metadata
+import json
+import os
+from pathlib import Path
+import re
+import sys
+
+VERSION = "1.0.0"
+EXTRACTOR_VERSION = "2.4.1"
+
+
+def convert(root, module, style):
+    if importlib.metadata.version("griffelib") != EXTRACTOR_VERSION:
+        raise ValueError(f"This adapter requires griffelib=={EXTRACTOR_VERSION}")
+    import griffe
+
+    root = root.resolve(strict=True)
+    if not root.is_dir() or not re.fullmatch(r"[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*", module):
+        raise ValueError("Provide a local source directory and a dotted Python module name")
+    # Reject symlinks before the extractor can follow any source outside this root.
+    digest = hashlib.sha256()
+    count = size = 0
+    for directory, dirs, files in os.walk(root, followlinks=False):
+        for name in dirs + files:
+            if (Path(directory) / name).is_symlink():
+                raise ValueError("Python source roots must not contain symlinks")
+        for name in sorted(files):
+            file = Path(directory) / name
+            if file.suffix not in (".py", ".pyi"):
+                continue
+            data = file.read_bytes()
+            size += len(data)
+            count += 1
+            if count > 10000 or size > 32 * 1024 * 1024:
+                raise ValueError("Python source root exceeds 10,000 files or 32 MiB")
+            relative = file.relative_to(root).as_posix().encode()
+            digest.update(len(relative).to_bytes(4, "big") + relative + len(data).to_bytes(8, "big") + data)
+        dirs.sort()
+    target = root.joinpath(*module.split("."))
+    if not target.with_suffix(".py").is_file() and not (target / "__init__.py").is_file():
+        raise ValueError("Requested module must exist as Python source under --root")
+    loaded = griffe.load(module, search_paths=[root], try_relative_path=False,
+                         extensions=griffe.Extensions(), allow_inspection=False,
+                         force_inspection=False, resolve_aliases=False,
+                         resolve_external=False, find_stubs_package=False,
+                         docstring_parser=style)
+    symbols = []
+
+    def field_info(obj):
+        info = {}
+        if obj.annotation is not None:
+            info["annotation"] = str(obj.annotation)
+        if obj.value is not None:
+            info["default"] = str(obj.value)
+        parent = obj.parent
+        if parent and parent.is_class and "dataclass" in parent.labels and "instance-attribute" in obj.labels:
+            if obj.value is None:
+                info["required"] = True
+            elif str(obj.value).startswith("field("):
+                call = ast.parse(str(obj.value), mode="eval").body
+                options = {keyword.arg: keyword.value for keyword in call.keywords}
+                if "init" not in options:
+                    info["required"] = not ("default" in options or "default_factory" in options)
+                elif isinstance(options["init"], ast.Constant) and options["init"].value is False:
+                    info["required"] = False
+            else:
+                info["required"] = False
+        elif parent and parent.is_class and any(str(base) in ("TypedDict", "typing.TypedDict", "typing_extensions.TypedDict") for base in parent.bases):
+            annotation = str(obj.annotation).split("[", 1)[0].rsplit(".", 1)[-1]
+            info["required"] = annotation != "NotRequired" and (annotation == "Required" or str(parent.keywords.get("total", "True")) != "False")
+        return info
+
+    def type_references(obj, expressions):
+        references = {}
+        for expression in expressions:
+            if expression is None:
+                continue
+            if isinstance(expression, str):
+                for token in re.findall(r"[A-Za-z_]\w*(?:\.\w+)*", expression):
+                    try:
+                        references[token] = obj.resolve(token)
+                    except griffe.NameResolutionError:
+                        pass
+            else:
+                for part in [expression, *expression.iterate()]:
+                    if isinstance(part, griffe.Expr) and part.reference_path:
+                        references[str(part)] = part.reference_path
+        return references
+
+    def visit(obj, parent=None):
+        if obj.is_alias or (obj.name.startswith("_") and obj.name != "__init__"):
+            return
+        kind = obj.kind.value
+        if kind == "function" and parent is not None and obj.parent.is_class:
+            kind = "constructor" if obj.name == "__init__" else "method"
+        if obj.is_class and any(str(base) in ("Enum", "IntEnum", "StrEnum", "enum.Enum", "enum.IntEnum", "enum.StrEnum") for base in obj.bases):
+            kind = "enum"
+        if kind == "type alias":
+            kind = "type"
+        symbol = {"id": obj.path, "name": obj.name, "kind": kind, "visibility": "public"}
+        if parent:
+            symbol["parent"] = parent
+        file = obj.filepath.resolve(strict=True)
+        relative = file.relative_to(root).as_posix()
+        symbol["source"] = {"path": relative}
+        if obj.lineno:
+            symbol["source"]["line"] = obj.lineno
+        sections = obj.docstring.parsed if obj.docstring else []
+        prose = []
+        parameter_docs = {}
+        for section in sections:
+            section_kind = section.kind.value
+            if section_kind == "text":
+                prose.append(section.value)
+            elif section_kind == "parameters":
+                parameter_docs.update({p.name: p for p in section.value})
+            elif section_kind == "raises":
+                symbol["raises"] = [{"name": str(p.annotation or p.name or "Exception"), "description": p.description} for p in section.value]
+            elif section_kind in ("returns", "yields") and len(section.value) == 1:
+                item = section.value[0]
+                symbol[section_kind] = {"description": item.description}
+                if item.annotation is not None:
+                    symbol[section_kind]["type"] = str(item.annotation)
+            elif section_kind == "examples":
+                examples = []
+                for example_kind, value in section.value:
+                    if example_kind.value == "text":
+                        prose.append(value)
+                    else:
+                        examples.append({"code": value})
+                if examples:
+                    symbol["examples"] = examples
+            else:
+                # Preserve less-common sections rather than silently losing their prose.
+                if obj.docstring:
+                    prose = [obj.docstring.value]
+                    symbol.pop("returns", None)
+                    symbol.pop("yields", None)
+                    symbol.pop("raises", None)
+                    symbol.pop("examples", None)
+                    break
+        if prose:
+            symbol["description"] = "\n\n".join(prose)
+            symbol["summary"] = prose[0].split("\n", 1)[0][:1000]
+        annotations = []
+        if obj.is_function:
+            annotations.extend([obj.returns, *(p.annotation for p in obj.parameters)])
+            prefix = "async def " if "async" in obj.labels else "def "
+            signatures = obj.overloads or [obj]
+            symbol["signatures"] = [prefix + entry.signature() for entry in signatures]
+            params = []
+            for parameter in obj.parameters:
+                if parameter.name in ("self", "cls") and obj.parent.is_class:
+                    continue
+                detail = {"name": parameter.name}
+                if parameter.annotation is not None:
+                    detail["type"] = str(parameter.annotation)
+                if parameter.default is not None:
+                    detail["default"] = str(parameter.default)
+                if parameter.name in parameter_docs:
+                    detail["description"] = parameter_docs[parameter.name].description
+                params.append(detail)
+            if params:
+                symbol["parameters"] = params
+            if obj.returns is not None:
+                symbol.setdefault("returns", {})["type"] = str(obj.returns)
+        elif obj.is_class:
+            annotations.extend(obj.bases)
+            if obj.bases:
+                symbol["bases"] = [str(base) for base in obj.bases]
+            constructor = obj.members.get("__init__")
+            if constructor is not None and not constructor.is_alias and constructor.is_function:
+                symbol["constructorSignature"] = constructor.signature(name=obj.name, return_type=False)
+                annotations.extend(p.annotation for p in constructor.parameters)
+            elif "dataclass" in obj.labels and not obj.bases and not any("init=" in str(decorator.value) or "kw_only=" in str(decorator.value) for decorator in obj.decorators):
+                # Synthesize only the simple local dataclass case; never execute decorators.
+                fields = [member for member in obj.attributes.values() if "instance-attribute" in member.labels]
+                if all(field_info(member).get("required") is not None and (not str(member.value).startswith("field(") or str(member.value).startswith("field(default_factory=")) for member in fields):
+                    declarations = []
+                    for member in fields:
+                        info = field_info(member)
+                        default = "<factory>" if str(member.value).startswith("field(default_factory=") else info.get("default")
+                        declarations.append(member.name + (": " + info["annotation"] if "annotation" in info else "") + (" = " + default if default is not None else ""))
+                        annotations.append(member.annotation)
+                    symbol["constructorSignature"] = obj.name + "(" + ", ".join(declarations) + ")"
+            symbol["signatures"] = ["class " + obj.name + ("(" + ", ".join(map(str, obj.bases)) + ")" if obj.bases else "")]
+        elif obj.is_attribute:
+            annotations.append(obj.annotation)
+            symbol.update(field_info(obj))
+            annotation = ": " + str(obj.annotation) if obj.annotation is not None else ""
+            symbol["signatures"] = [obj.name + annotation]
+        annotations.extend(item["name"] for item in symbol.get("raises", []))
+        references = type_references(obj, annotations)
+        if references:
+            symbol["typeReferences"] = references
+        symbols.append(symbol)
+        for child in sorted(getattr(obj, "members", {}).values(), key=lambda item: item.name):
+            visit(child, obj.path)
+
+    visit(loaded)
+    known = {symbol["id"] for symbol in symbols}
+    for symbol in symbols:
+        if "typeReferences" in symbol:
+            symbol["typeReferences"] = {name: target for name, target in symbol["typeReferences"].items() if target in known}
+            if not symbol["typeReferences"]:
+                del symbol["typeReferences"]
+    return {"schemaVersion": 1, "kind": "shoalrun-code-reference", "programmingLanguage": "python",
+            "producer": {"name": "shoalrun-python", "version": VERSION, "extractorVersion": EXTRACTOR_VERSION},
+            "sourceDigest": digest.hexdigest(), "symbols": symbols}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, required=True)
+    parser.add_argument("--module", required=True)
+    parser.add_argument("--style", choices=("google", "numpy", "sphinx"), default="google")
+    parser.add_argument("--out", type=Path, required=True)
+    args = parser.parse_args()
+    try:
+        data = convert(args.root, args.module, args.style)
+        args.out.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf8")
+    except (ImportError, importlib.metadata.PackageNotFoundError):
+        parser.exit(1, "Install the adapter's pinned requirements in Python 3.11+ before running it.\n")
+    except (ValueError, OSError) as error:
+        parser.exit(1, f"{error}\n")
+
+
+if __name__ == "__main__":
+    main()

package/adapters/typescript/README.md

@@ -0,0 +1,27 @@
+# TypeScript code-reference adapter
+
+This optional adapter uses the project's installed TypeScript 5.9.x compiler API to extract one public entry point into Shoalrun's version 1 snapshot format. The maintained dependency is `typescript@5.9.3`. TypeScript 6/7 compiler APIs aren't covered by this adapter.
+
+Install the dependency explicitly, then run from your documentation or library project:
+
+```sh
+npm install --save-dev --save-exact typescript@5.9.3
+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
+```
+
+Set `--root DIRECTORY` to bound declarations and provenance to a narrower source tree. Entry paths resolve relative to the project's compiler configuration. The output path resolves relative to the current directory. The module ID is a stable logical prefix for exported symbol IDs; use the same value when refreshing the snapshot.
+
+Public local re-exports are followed. Functions and overloads, classes, interfaces, aliases, enums, constants, declared members, and static members are represented. Private/protected declarations and `@internal` or `@private` symbols are skipped. A structural alias or inferred structural type containing an excluded member stops extraction instead of printing private details in a parent signature; expose a separate public type. Copied initializers and parameter defaults containing excluded declarations also stop extraction rather than publishing those values. Inherited members aren't expanded. Anonymous call/index signatures are retained in interface declarations, and union alternatives remain in their alias declaration. Unsupported declarations, unresolved imports, and exported declarations outside the declared source root stop extraction.
+
+JSDoc descriptions, parameter descriptions, return descriptions, and examples are retained. Other JSDoc tags aren't converted into runtime constraints. Source initializers used as defaults are copied as expressions, never evaluated. Some conditional type expansions stop extraction when their visibility cannot be verified. Type references link known public targets; built-ins and unavailable types remain text. Source locations refer to the actual input, including `.d.ts` files when those are used.
+
+The adapter calls `createProgram` without emitting files. It doesn't execute the documented module or run project transformers/plugins, install dependencies, or fetch remote inputs. The TypeScript compiler package and local configuration remain trusted development inputs. Use a reviewed project and inspect the JSON before publication.
+
+The source digest covers effective compiler options and all compiler source files, including external type dependencies. Graph accounting limits include those dependencies; they are checked after TypeScript loads the graph and are not execution or memory isolation. Run extraction only on trusted local projects. The output cannot overwrite a compiler input, including through symlinks, and is replaced atomically after validation.
+
+A site build needs only the saved JSON. Configure it through `codeReferences` as described in [CODE-REFERENCES.md](../../CODE-REFERENCES.md). This keeps extraction separate from rendering, publication selection, and content delivery.