@shoalrun/cli 0.1.0-beta.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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,137 @@
+# 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.
+
+## 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.0.0
 ```
 
 ## Create and preview a site
@@ -38,7 +38,8 @@ 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 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. |
 | 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. |
@@ -51,6 +52,8 @@ Local builds and keyword search need no provider credentials. Semantic retrieval
 
 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
@@ -346,14 +349,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.0.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/agent-docs/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt

@@ -28,13 +28,15 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 - [Styled PDFs and custom code languages](https://www.shoalrun.com/changelog/pdf-custom-languages.md) — ID: change.pdf-custom-languages. changelog-entry; 487 tokens. Print branded pages, export a complete PDF manual, and highlight your own code language.
 
+- [Shoalrun 1.0 — SDK references and smoother font loading](https://www.shoalrun.com/changelog/code-api-references.md) — ID: change.code-api-references. changelog-entry; 538 tokens. Generate code API references from source and docstrings, choose how readers browse them, and load custom fonts earlier.
+
 - [Authoring snapshot previews and review reports](https://www.shoalrun.com/changelog/authoring-preview.md) — ID: change.authoring-preview. changelog-entry; 554 tokens. Snapshot previews with coverage and freshness reports.
 
 - [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — ID: change.authoring-search. changelog-entry; 468 tokens. Reviewed agent drafts, search improvements, and answer context.
 
 - [Working-tree authoring tools](https://www.shoalrun.com/changelog/authoring-tools.md) — ID: change.authoring-tools. changelog-entry; 384 tokens. Project discovery and captured working-tree validation.
 
-- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1472 tokens. Compiler, CLI, and reader changes.
+- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1547 tokens. Compiler, CLI, and reader changes.
 
 - [MCP hosting, analytics, and component improvements](https://www.shoalrun.com/changelog/2026-10-17-mcp-hosting.md) — ID: change.mcp-hosting. changelog-entry; 1147 tokens. MCP hosting, analytics, and shared component content.
 
@@ -48,4 +50,4 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 - [Non-goals](https://www.shoalrun.com/non-goals.md) — ID: guide.non-goals. explanation; 821 tokens. Scope limits for skill generation, agent orchestration, and reader-view authorization.
 
-- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1918 tokens. Current capabilities, planned features, and known limits.
+- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1990 tokens. Current capabilities, planned features, and known limits.

package/agent-docs/SNAPSHOT.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "sourceRepository": "https://github.com/shoalrun/docs",
-  "sourceCommit": "01614c57a52c0157fb48fc12f434962f27f704e7",
-  "siteBuildId": "30b28d69af454479a90a00f3b015448f97af9be0c46d153441408b899ccaf08f",
-  "manifestDigest": "7337bcec6d88bb4934afff2eb68562244f9391af3d651ead5111fa2bf794c132",
-  "indexDigest": "090e6b3f4bd7c9968b75b609a695e6ebd6f596a66135db41968c3905258a25d6",
-  "packageIntegrity": "sha512-uigk3DRE8FClwgyo5kGeyPtB7CXkpLVEAQGhHxMd0exbFThqvvMxPGGVL7rohJdw+o0xSmFNK0U7/TvwLatyZw=="
+  "sourceCommit": "0af50d753fc59c1e332d5e710999e3219c3e2443",
+  "siteBuildId": "6b51e1bac3826424f2ec68156866ec40c1761f7765901fc6dfc2f2d4f24a8596",
+  "manifestDigest": "2cb3bc1d411d08d4156fb139c6257dd4e56ea79ea1aed38c85eb32986b2a1743",
+  "indexDigest": "a6c8b514805bfd808949c3d22a01deee1ae9c35b4c6e54009ae3866b21df2c6e",
+  "packageIntegrity": "sha512-TVNgFm5dtSyO7c+njfPC2fta5IWnIVALrTD0CYktEUeuFbKv0pdKg8C7ihBiQ3svOhXNnyjZSDF96N23lVl/Tw=="
 }

package/agent-docs/about.md

@@ -1,7 +1,7 @@
 ---
 id: guide.about
 title: About Shoalrun
-summary: Learn what Shoalrun is exploring and where the beta stands.
+summary: Learn what Shoalrun does and where the project is heading.
 type: overview
 area: project
 subarea: project-overview
@@ -12,7 +12,7 @@ canonical: /about
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 I'm CT Smith, and I'm building Shoalrun cause there's no such thing as a perfect doc tool. I have opinions, undirected rage, and curiosity about doc-building tools. I built my first documentation generator back in 2015. It was based on Jekyll and relied heavily (probably too heavily) on general templating and... you guessed it... *page metadata*.
 
@@ -42,7 +42,7 @@ API content follows the same approach. Local OpenAPI files can supply reference
 
 I'm building Shoalrun for tinkerers like me, who will never be fully satisfied with a mass market docs tool. Docs are never one-size-fits-all, on any level.
 
-You can try the beta CLI from npm: [Getting started](https://www.shoalrun.com/start.md) walks through installation and your first page. The [project status](https://www.shoalrun.com/status.md) describes what works and what still needs work.
+You can try the CLI from npm: [Getting started](https://www.shoalrun.com/start.md) walks through installation and your first page. The [project status](https://www.shoalrun.com/status.md) describes what works and what still needs work.
 
 yee haw forever,