@shoalrun/cli 0.1.0-alpha.19 → 1.0.0

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

@@ -0,0 +1,143 @@
+---
+id: guide.code-api-references
+title: Generate code API references
+summary: Turn Python source and docstrings into SDK reference pages, with
+  separate, grouped, or complete-page layouts.
+type: how-to
+area: api
+subarea: api-generation
+canonical: /api-docs/code-references
+---
+
+# Generate code API references
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Generate code API references
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+A code API reference describes a library's classes, functions, methods, fields, parameters, return values, and exceptions. A guide explains how to accomplish a task; the reference explains what a programmer can call, what to pass, and what comes back. [OpenAPI references](https://www.shoalrun.com/publish/api-references.md) describe HTTP endpoints instead.
+
+Shoalrun reads a converter's JSON snapshot and renders native reference pages. The optional Python adapter extracts local source and docstrings with Griffe. Other languages can supply a converter that writes the same [snapshot format](https://www.shoalrun.com/api-docs/code-reference-settings.md). A Kotlin-shaped snapshot is supported; a Kotlin extractor isn't bundled.
+
+## Before you start
+
+Use an existing documentation project with `@shoalrun/cli` installed, as in [Getting started](https://www.shoalrun.com/start.md). Run the commands below from that project's directory. Extraction needs Python 3.11 or newer and an explicit dependency installation. Normal site builds read the snapshot and don't need Python.
+
+The adapter doesn't import the documented package, execute its code, enable Griffe extensions, or inspect installed modules. Review public source declarations and docstrings before publishing: static extraction doesn't establish that their content is safe to disclose.
+
+## Add Python source
+
+Create `src/sample.py`. This fictional example returns a local dictionary and doesn't contact a service:
+
+```python title="src/sample.py"
+class Client:
+    """Retrieve records for an application."""
+
+    def fetch(self, record_id: str) -> dict[str, str]:
+        """Retrieve a record by its stable identifier.
+
+        Args:
+            record_id: Identifier of the record to retrieve.
+
+        Returns:
+            A mapping containing the record identifier.
+        """
+        return {"id": record_id}
+```
+
+Keep the source root limited to the package you're documenting. The adapter rejects symlinks inside that root, including links to files outside it.
+
+## Extract and validate a snapshot
+
+Create an isolated Python environment and install the adapter's pinned requirements:
+
+```sh
+python3.11 -m venv .venv-reference
+.venv-reference/bin/python -m pip install --require-hashes \
+  -r node_modules/@shoalrun/cli/adapters/python/requirements.txt
+mkdir -p reference
+.venv-reference/bin/python node_modules/@shoalrun/cli/adapters/python/shoalrun_reference.py \
+  --root ./src --module sample --style google --out ./reference/python.json
+npx --no-install shoalrun references check ./reference/python.json
+```
+
+Use `--style google`, `numpy`, or `sphinx` to match the docstring convention. The adapter preserves signatures, supported docstring sections, local source locations, and resolved local type references. It skips aliases and underscore-prefixed members except constructors. It doesn't expand inherited members, execute decorators, or resolve external re-exports. Review the JSON before building.
+
+The check reports `status: "ok"`, the programming language, and the symbol count. Duplicate IDs, missing referenced symbols, cyclic ownership, and invalid fields fail validation. A missing Python dependency stops extraction; Shoalrun doesn't install it during a site build.
+
+## Register the catalog and navigation
+
+Add these settings to `docs.config.yaml`, retaining the project's existing site and publication settings:
+
+```yaml title="docs.config.yaml"
+codeReferences:
+  sdk:
+    source: { kind: file, path: ./reference/python.json }
+    layout: classes
+    singlePage:
+      documentId: reference.sdk.complete
+      slug: /reference/sdk/all
+      title: Complete SDK reference
+    symbols:
+      sample.Client:
+        documentId: reference.sdk.client
+        slug: /reference/sdk/client
+navigation:
+  - { id: sdk-client, doc: reference.sdk.client }
+  - { id: sdk-complete, doc: reference.sdk.complete }
+```
+
+If navigation already exists, append those entries to the appropriate group. References use ordinary `doc:` entries. Explicit document IDs and slugs preserve intentional public identities. Generated defaults follow the catalog and symbol IDs. Renaming a source symbol changes its default identity.
+
+## Choose the reading layout
+
+Use `layout` to control how much detail readers see on a parent page. Individual symbol URLs stay available in every layout. Group the class or module pages in navigation when you want fewer menu entries.
+
+| Layout    | What readers see                                                                                            |
+| --------- | ----------------------------------------------------------------------------------------------------------- |
+| `symbols` | Separate symbol pages with linked member tables. This is the default.                                       |
+| `classes` | Class pages include member details inline. Module pages include their direct functions and class overviews. |
+| `modules` | A module page includes details for its classes, functions, and fields. Submodules form separate groups.     |
+
+`singlePage` independently adds a complete reference for the catalog. It works with any layout. Omit it or set `singlePage: false` to disable it. In a grouped or complete page, links to included symbols jump to their sections; other links retain individual symbol URLs. See the [configuration reference](https://www.shoalrun.com/api-docs/code-reference-settings.md) for defaults and metadata options.
+
+## Build and verify
+
+Build the site, then serve the same output:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun serve site-dist --port 8770
+```
+
+Open `http://127.0.0.1:8770/reference/sdk/client/` and `/reference/sdk/all/`. The class page should include `fetch` details. The complete page should include the module, class, and method. Read their Markdown copies at `/reference/sdk/client.md` and `/reference/sdk/all.md` and verify that signatures, parameter descriptions, and return information remain readable.
+
+Regenerate the snapshot after changing source or docstrings, then validate and rebuild. A site build doesn't rerun the converter. The packaged `examples/code-references` project has a larger sample SDK with models, async methods, overloads, pagination, and exceptions.
+
+## Versions, profiles, and delivery
+
+Bind different snapshots to explicit product/channel/version/language publications when releases have different interfaces. `programmingLanguage: python` describes the source language; publication `language: en` describes the documentation language.
+
+Catalog and per-symbol metadata can declare reader filters, `shared`, and `requires`. Use the same profile for build and export. Grouped and complete pages include only symbols eligible in their publication and build selection; they don't grant access to excluded symbols. See [Publications](https://www.shoalrun.com/publish/publications.md), [Customer editions](https://www.shoalrun.com/publish/deployment-profiles.md), and the [reference](https://www.shoalrun.com/api-docs/code-reference-settings.md) for the configuration.
+
+## HTML, Markdown, and agents
+
+HTML uses compact declaration blocks, linked types, field/default tables, and symbol sections. Tables scroll horizontally on narrow screens and can receive keyboard focus. Copy controls use JavaScript; reading the reference, following symbol links, and scrolling a table don't require it. A full reference is an ordinary generated page, so browser Find can search its content.
+
+Markdown retains declarations, descriptions, tables, examples, and symbol links. It doesn't include Copy controls or the website styling. Content exports preserve typed resource links and scope; PDF workflows can select a grouped page or the complete reference by document ID. Generated symbol pages remain independently addressable even when they're also shown inline elsewhere.
+
+Agents can discover and read the generated pages through the site's indexes and read-only tools, or use the normal content-delivery API. They don't need Python or browser scripts to read published references. Source extraction describes declared interfaces; it doesn't execute examples or prove runtime behavior.
+
+## Related reading
+
+### 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/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-05.**
+**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 alpha 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/code-blocks.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 > Code blocks
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Fenced code is ordinary Markdown rather than an MDX component. It belongs in the component reference because authors use it beside components to show commands, configuration, and payloads.
 
@@ -70,6 +70,51 @@ To use a theme you know from your editor, set `theme` to a bundled Shiki theme n
 
 The built-in grammars are JSON, YAML, shell, JavaScript, TypeScript, Python, HTML, CSS, MDX, Markdown, HTTP, XML, SQL, Go, Java, Ruby, C#, PHP, and Rust. Shiki also recognizes loaded aliases such as `sh` and `js`. Unknown or unlabeled code stays plain. JSON-compatible API examples use JSON highlighting; text media currently use plain text.
 
+### Add your language's grammar
+
+Since 0.1.0-beta.1
+
+Use `languages` with Shiki to add a custom language without writing a highlighter adapter. Give it an ID, a local TextMate JSON grammar, and optional aliases:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    highlighting:
+      provider: shiki
+      languages:
+        - id: custompy
+          grammar: ./grammars/custompy.tmLanguage.json
+          aliases: [cpy]
+```
+
+For example, this small grammar adds two illustrative keywords before using Python's bundled syntax rules:
+
+```json title="grammars/custompy.tmLanguage.json"
+{
+  "scopeName": "source.custompy",
+  "patterns": [
+    { "name": "keyword.control.custompy", "match": "\\b(?:publish|unless)\\b" },
+    { "include": "source.python" }
+  ]
+}
+```
+
+Use `custompy` or `cpy` as the fence language:
+
+````md
+```custompy
+def welcome(name):
+    unless name is None:
+        publish "Hello, " + name
+```
+````
+
+The grammar path is relative to the config file that declares it, including imported fragments. Use a local JSON file no larger than 4 MiB; XML `.tmLanguage` files aren't supported. The grammar needs a `scopeName` and a `patterns` array. Choose a distinct scope name, and don't reuse a bundled language ID or alias. IDs and aliases use lowercase letters, digits, underscores, or hyphens and start with a letter.
+
+The grammar is a build dependency. `dev` watches it, and isolated authoring validation captures it. Changing the rules rebuilds the colors; a missing or malformed grammar fails the build without replacing valid output. Registrations are isolated between projects built in the same process. Grammar files aren't copied into the browser's assets.
+
+This adds syntax colors to website HTML, not language validation or autocomplete. Filenames remain labels; they don't choose a grammar. The Markdown twin keeps the original code and language ID. Retain applicable license notices when using or adapting an existing grammar.
+
 ### Choose plain code
 
 ```yaml

package/agent-docs/author/frontmatter-reference.md

@@ -87,6 +87,7 @@ By default, `product`, `area`, and `subarea` are optional, nonempty string categ
 | `layout`               | string          | Optional     | HTML page layout: docs (default), wide (no page outline, full content width), landing (no sidebar or outline; a Hero replaces the page header), or splash (full-bleed marketing page built from Hero and Section blocks).                                                   |
 | `showNavigationTabs`   | boolean         | Optional     | Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.                                                                             |
 | `showVerified`         | boolean         | Optional     | Show an authored verified date in the HTML page header. Defaults to true. False hides it only in HTML; Markdown and manifest dates remain unchanged. Does not assign a verification date.                                                                                   |
+| `pdf`                  | boolean         | Optional     | Controls the optional page print/PDF action. False suppresses its control and endpoint inputs; true follows the site setting. Site builds do not generate per-page PDFs.                                                                                                    |
 | `image`                | string          | Optional     | Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.                                                                                                                                   |
 
 Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.

package/agent-docs/author/frontmatter-reference.sections/categorize-connect-and-present-the-page.md

@@ -57,6 +57,7 @@ By default, `product`, `area`, and `subarea` are optional, nonempty string categ
 | `layout`               | string          | Optional     | HTML page layout: docs (default), wide (no page outline, full content width), landing (no sidebar or outline; a Hero replaces the page header), or splash (full-bleed marketing page built from Hero and Section blocks).                                                   |
 | `showNavigationTabs`   | boolean         | Optional     | Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.                                                                             |
 | `showVerified`         | boolean         | Optional     | Show an authored verified date in the HTML page header. Defaults to true. False hides it only in HTML; Markdown and manifest dates remain unchanged. Does not assign a verification date.                                                                                   |
+| `pdf`                  | boolean         | Optional     | Controls the optional page print/PDF action. False suppresses its control and endpoint inputs; true follows the site setting. Site builds do not generate per-page PDFs.                                                                                                    |
 | `image`                | string          | Optional     | Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.                                                                                                                                   |
 
 Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.

package/agent-docs/author/workspace.md

@@ -20,11 +20,11 @@ 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 > Check edits
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 **Status: Experimental.**
 
-Use this procedure from your documentation project directory, containing `docs.config.yaml`, with `@shoalrun/cli` installed. [Getting started](https://www.shoalrun.com/start.md) explains how to install the alpha package from npm. You need Node.js 22.12 or newer; a framework source checkout and a separate authoring provider key aren't required. Your coding agent uses its own model and file tools. Replace the example page path with your project's path.
+Use this procedure from your documentation project directory, containing `docs.config.yaml`, with `@shoalrun/cli` installed. [Getting started](https://www.shoalrun.com/start.md) explains how to install the beta package from npm. You need Node.js 22.12 or newer; a framework source checkout and a separate authoring provider key aren't required. Your coding agent uses its own model and file tools. Replace the example page path with your project's path.
 
 Framework contributors can instead build the source checkout and run `node framework/dist/cli.js <command>` from its root. The examples below use the installed package.
 

package/agent-docs/author/writing-style.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun doesn't automatically apply these rules to other projects.
 
@@ -42,7 +42,7 @@ Choose the page type by the reader's goal and the actual content. Keep one prima
 | Ingredient      | Reuse one task step in several recipes.        | Required inputs and prerequisites, one action with its instructions, named outputs, and an observable check. Keep the step independent of any recipe's position or neighboring wording. |
 | Recipe          | Complete one task from a known starting state. | Outcome, prerequisites, ordered actions, failure guidance, and a final success check. Include everything needed to follow the published page on its own.                                |
 | Cookbook        | Choose between complete recipes.               | Explain who each path is for, what it needs, and what it produces; link to the published recipe pages. State whether choices are alternatives or can be combined.                       |
-| Changelog entry | Understand a dated change.                     | User-visible behavior, scope, migration when needed, and limitations. Say when a change concerns the private prototype; claim a release only with release evidence.                     |
+| Changelog entry | Understand a dated change.                     | A short capability summary, links to the feature guides, and required upgrade or migration actions. Claim a release only with release evidence.                                         |
 
 Use **Before you begin**, **Check the result**, and **Next steps** for recurring task sections when revising a procedure. Keep action headings specific to the task. Existing tutorials can retain established headings when tools or incoming fragments depend on them. A short procedure may put prerequisites in its introduction; omit sections that add no useful information.
 
@@ -54,6 +54,12 @@ Run customer commands from a project with the pinned npm package installed, usin
 
 These are editorial shapes, not a reason to add empty boilerplate. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Don't add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.
 
+## Release notes
+
+Keep release notes short and factual. Name what readers can do, link each feature heading to its guide, and state the exact upgrade or rebuild action. Prefer a brief paragraph per feature; leave configuration examples and detailed behavior in the linked documentation.
+
+Include before/after explanations only when readers upgrading from a published release need them. Omit development history, discarded designs, implementation walkthroughs, test counts, and generic recaps. Expand when a migration or security action needs explanation. Release-note summaries link to feature guides for HTML, Markdown, and agent details instead of repeating those sections.
+
 ## Voice and explanations
 
 Use natural contractions such as “don't,” “can't,” “it's,” and “you're.” Keep expanded forms when emphasis or clarity needs them. Preserve exact commands, configuration values, API fields, error messages, and quotations. Vale's `Shoalrun.Contractions` rule flags common expanded forms for review; contractions themselves are accepted.
@@ -107,7 +113,7 @@ Choose the structure that helps readers use the information or complete the task
 
 Introduce every table with a sentence explaining what readers should use it for. Never place a table directly after a heading. The formatting check enforces this rule with `DocShape.TableIntroduction`.
 
-Don't hide an essential instruction inside decoration. Every page documenting a component or presentation feature needs an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
+Don't hide an essential instruction inside decoration. Component references and guides that explain a presentation feature need an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
 
 A page that merely uses a callout, link, or Steps component needs the section only when that use changes access to information. Avoid generic claims that both formats are identical: explain the actual representation. Cookbook pages must distinguish their recipe links from the complete instructions in the linked recipes or a downloaded selection.
 

package/agent-docs/author/writing-style.sections/adapt-this-example.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/choose-components-by-reader-need.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 
@@ -39,6 +39,6 @@ Choose the structure that helps readers use the information or complete the task
 
 Introduce every table with a sentence explaining what readers should use it for. Never place a table directly after a heading. The formatting check enforces this rule with `DocShape.TableIntroduction`.
 
-Don't hide an essential instruction inside decoration. Every page documenting a component or presentation feature needs an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
+Don't hide an essential instruction inside decoration. Component references and guides that explain a presentation feature need an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
 
 A page that merely uses a callout, link, or Steps component needs the section only when that use changes access to information. Avoid generic claims that both formats are identical: explain the actual representation. Cookbook pages must distinguish their recipe links from the complete instructions in the linked recipes or a downloaded selection.

package/agent-docs/author/writing-style.sections/evidence-and-uncertainty.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/example-audience-and-scope.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/feature-availability.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/ingredients-recipes-and-cookbooks.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/page-purpose-and-structure.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 
@@ -36,7 +36,7 @@ Choose the page type by the reader's goal and the actual content. Keep one prima
 | Ingredient      | Reuse one task step in several recipes.        | Required inputs and prerequisites, one action with its instructions, named outputs, and an observable check. Keep the step independent of any recipe's position or neighboring wording. |
 | Recipe          | Complete one task from a known starting state. | Outcome, prerequisites, ordered actions, failure guidance, and a final success check. Include everything needed to follow the published page on its own.                                |
 | Cookbook        | Choose between complete recipes.               | Explain who each path is for, what it needs, and what it produces; link to the published recipe pages. State whether choices are alternatives or can be combined.                       |
-| Changelog entry | Understand a dated change.                     | User-visible behavior, scope, migration when needed, and limitations. Say when a change concerns the private prototype; claim a release only with release evidence.                     |
+| Changelog entry | Understand a dated change.                     | A short capability summary, links to the feature guides, and required upgrade or migration actions. Claim a release only with release evidence.                                         |
 
 Use **Before you begin**, **Check the result**, and **Next steps** for recurring task sections when revising a procedure. Keep action headings specific to the task. Existing tutorials can retain established headings when tools or incoming fragments depend on them. A short procedure may put prerequisites in its introduction; omit sections that add no useful information.
 

package/agent-docs/author/writing-style.sections/procedures-and-examples.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/release-notes.md

@@ -0,0 +1,30 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing guide
+
+> 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) > Authoring reference > Example writing guide
+
+**Updated: 2026-11-06.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun doesn't automatically apply these rules to other projects.
+
+## Release notes
+
+Keep release notes short and factual. Name what readers can do, link each feature heading to its guide, and state the exact upgrade or rebuild action. Prefer a brief paragraph per feature; leave configuration examples and detailed behavior in the linked documentation.
+
+Include before/after explanations only when readers upgrading from a published release need them. Omit development history, discarded designs, implementation walkthroughs, test counts, and generic recaps. Expand when a migration or security action needs explanation. Release-note summaries link to feature guides for HTML, Markdown, and agent details instead of repeating those sections.

package/agent-docs/author/writing-style.sections/review-a-draft.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/reviewed-writing-examples.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/voice-and-explanations.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/changelog/2026-10-16-navigation-layouts.md

@@ -69,4 +69,4 @@ Repository contributors now have a separate maintainer guide covering architectu
 
 ### Related topics
 
-- [Project status](https://www.shoalrun.com/status.md) — Check the alpha's capabilities and current limits.
+- [Project status](https://www.shoalrun.com/status.md) — Check the current capabilities and limits.

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

@@ -0,0 +1,44 @@
+---
+id: change.code-api-references
+title: Shoalrun 1.0 — SDK references and smoother font loading
+summary: Generate code API references from source and docstrings, choose how
+  readers browse them, and load custom fonts earlier.
+type: changelog-entry
+area:
+  - api
+  - appearance
+  - project
+subarea:
+  - api-generation
+  - appearance-themes
+  - project-releases
+canonical: /changelog/code-api-references
+date: 2026-11-06
+releaseVersion: 1.0.0
+---
+
+# Shoalrun 1.0 — SDK references and smoother font loading
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 1.0: SDK references and font loading
+
+**Published: 2026-11-06.**
+
+**Version: 1.0.0.**
+
+Upgrade to CLI `1.0.0` and rebuild to apply these changes. Regenerate a code-reference snapshot whenever its source or docstrings change.
+
+## [Generate SDK references](https://www.shoalrun.com/api-docs/code-references.md)
+
+Turn Python source and docstrings into native reference pages with declarations, linked types, field defaults, parameters, and examples. Other languages can bring a converter using the same JSON format. Choose separate symbol pages, inline class or module references, and an optional complete reference on one page. Publication and customer-profile selection apply to every layout; HTML, Markdown, content delivery, and PDF workflows retain the selected content.
+
+## [Load custom fonts earlier](https://www.shoalrun.com/styling/themes.md)
+
+Local custom body and heading fonts get preload hints and versioned asset URLs for caching. Bundled fonts revalidate instead of remaining stale in a development browser.
+
+## Stable npm release channel
+
+Shoalrun 1.0 uses npm's `latest` channel. Publication verifies distribution tags separately from the upload, so interrupted tagging can resume without uploading the same version again. Future prereleases keep a stable `latest` in place.

package/agent-docs/changelog/pdf-custom-languages.md

@@ -0,0 +1,48 @@
+---
+id: change.pdf-custom-languages
+title: Styled PDFs and custom code languages
+summary: Print branded pages, export a complete PDF manual, and highlight your
+  own code language.
+type: changelog-entry
+area:
+  - publishing
+  - components
+  - appearance
+  - authoring
+  - project
+subarea:
+  - publishing-builds
+  - components-code
+  - appearance-themes
+  - authoring-agent-workflows
+  - project-releases
+canonical: /changelog/pdf-custom-languages
+date: 2026-11-05
+releaseVersion: 0.1.0-beta.1
+---
+
+# Styled PDFs and custom code languages
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > beta.1: PDFs and code languages
+
+**Published: 2026-11-05.**
+
+**Version: 0.1.0-beta.1.**
+
+Upgrade to CLI `0.1.0-beta.1` and rebuild to use these features.
+
+## [Print a page](https://www.shoalrun.com/publish/pdf.md)
+
+Add an optional, configurable **Print PDF** button with branded styling. Static sites use the reader's browser.
+
+## [Export a styled manual](https://www.shoalrun.com/publish/pdf.md)
+
+Export a page or full publication with custom fonts, covers, contents, and page layouts. CLI exports and optional Node downloads require installed Chrome or Chromium; static printing doesn't. The new `shoalrun-pdf` skill guides agents through print design.
+
+## [Highlight your own code language](https://www.shoalrun.com/author/components/code-blocks.md)
+
+Register a local TextMate JSON grammar containing syntax-coloring rules, then use its language ID or aliases in code fences.

package/agent-docs/changelog.md

@@ -16,12 +16,20 @@ Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navi
 
 Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > All changes
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Updates to Shoalrun and its documentation. Each entry identifies the affected versions and any upgrade steps. Earlier entries retain their private-prototype release context.
 
 ## Latest changes
 
+- 2026-11-06
+
+  Version 1.0.0
+
+  [Shoalrun 1.0 — SDK references and smoother font loading](https://www.shoalrun.com/changelog/code-api-references.md)
+
+  Generate code API references from source and docstrings, choose how readers browse them, and load custom fonts earlier.
+
 - 2026-11-05
 
   Version 0.1.0-alpha.19
@@ -30,6 +38,14 @@ Updates to Shoalrun and its documentation. Each entry identifies the affected ve
 
   Match your documentation to your brand with an agent skill, and bind hosted-chat visitor checks to the intended site.
 
+- 2026-11-05
+
+  Version 0.1.0-beta.1
+
+  [Styled PDFs and custom code languages](https://www.shoalrun.com/changelog/pdf-custom-languages.md)
+
+  Print branded pages, export a complete PDF manual, and highlight your own code language.
+
 - 2026-11-04
 
   Version 0.1.0-alpha.17