@shoalrun/cli 0.1.0-beta.1 → 1.0.0

package/agent-docs/features.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Shoalrun features
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Shoalrun compiles product and API documentation into a website and agent-readable content from the same source. You own the source files, build output, and deployment. The normal compiler build makes no model calls or network requests.
 
@@ -31,6 +31,7 @@ Follow a topic link for configuration, examples, and limits.
 | [Documentation components](https://www.shoalrun.com/author/components.md)              | Use tabs, callouts, tables, steps, walkthroughs, diagrams, and trusted custom components with defined Markdown representations.                                                                                               |
 | [Code highlighting](https://www.shoalrun.com/author/components/code-blocks.md)         | Highlight built-in languages or register a custom language with a local TextMate JSON grammar and aliases. Preserve the original code in Markdown.                                                                            |
 | [OpenAPI documentation](https://www.shoalrun.com/publish/api-references.md)            | Generate reference pages, embed API examples and schemas, show request samples, and publish focused operation contracts. Review source changes before publishing.                                                             |
+| [Code API references](https://www.shoalrun.com/api-docs/code-references.md)            | Generate SDK references from Python docstrings or a converter snapshot. Show linked types, defaults, and member details on symbol, class, module, or optional complete-reference pages.                                       |
 | [Customer editions](https://www.shoalrun.com/publish/deployment-profiles.md)           | Select exact product releases, SKU revisions, and feature grants. Remove excluded pages and sections during compilation.                                                                                                      |
 | [Independent products and versions](https://www.shoalrun.com/publish/publications.md)  | Give each product its own documentation versions and defaults, with explicit languages and routes.                                                                                                                            |
 | [Search and agent tools](https://www.shoalrun.com/search-and-chat.md)                  | Search the selected publication by keyword or optional semantic retrieval. Read-only Model Context Protocol (MCP) tools discover publications and read pages within token budgets. Optional cited answers use your providers. |
@@ -43,7 +44,7 @@ Follow a topic link for configuration, examples, and limits.
 
 ## Before you choose Shoalrun
 
-Configuration and output contracts can change as Shoalrun develops. OpenAPI and JSON Schema support is partial. Arbitrary executable MDX and a live API request explorer aren't supported.
+Pin releases and review upgrade notes before deploying. OpenAPI and JSON Schema support is partial. Arbitrary executable MDX and a live API request explorer aren't supported.
 
 You supply hosting, reader authentication, authored translations, and any optional model or analytics services. Reader views change browsing convenience; they don't restrict access to published files. The hosted public MCP endpoint serves one configured publication, and profiled Vercel chat builds aren't supported.
 

package/agent-docs/provenance.json

@@ -2,15 +2,15 @@
   "schemaVersion": 1,
   "siteBuild": {
     "schemaVersion": 1,
-    "configDigest": "e3d0124ef8866a0cd2080cd8b3822909d5b4e288ef0c642b1ebcaebe2591c305",
-    "buildId": "30b28d69af454479a90a00f3b015448f97af9be0c46d153441408b899ccaf08f"
+    "configDigest": "29b56e216858565721d2a6773b9e22346061341ae078717ac05c19dd686f2f3b",
+    "buildId": "6b51e1bac3826424f2ec68156866ec40c1761f7765901fc6dfc2f2d4f24a8596"
   },
-  "packageIntegrity": "sha512-uigk3DRE8FClwgyo5kGeyPtB7CXkpLVEAQGhHxMd0exbFThqvvMxPGGVL7rohJdw+o0xSmFNK0U7/TvwLatyZw==",
+  "packageIntegrity": "sha512-TVNgFm5dtSyO7c+njfPC2fta5IWnIVALrTD0CYktEUeuFbKv0pdKg8C7ihBiQ3svOhXNnyjZSDF96N23lVl/Tw==",
   "compilerPackage": {
     "kind": "reviewed-local-artifact",
     "name": "@shoalrun/cli",
-    "version": "0.1.0-beta.1",
-    "integrity": "sha512-uigk3DRE8FClwgyo5kGeyPtB7CXkpLVEAQGhHxMd0exbFThqvvMxPGGVL7rohJdw+o0xSmFNK0U7/TvwLatyZw=="
+    "version": "1.0.0",
+    "integrity": "sha512-TVNgFm5dtSyO7c+njfPC2fta5IWnIVALrTD0CYktEUeuFbKv0pdKg8C7ihBiQ3svOhXNnyjZSDF96N23lVl/Tw=="
   },
-  "manifestDigest": "7337bcec6d88bb4934afff2eb68562244f9391af3d651ead5111fa2bf794c132"
+  "manifestDigest": "2cb3bc1d411d08d4156fb139c6257dd4e56ea79ea1aed38c85eb32986b2a1743"
 }

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

@@ -17,12 +17,14 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Put the spec in your project
 
 Create `apis/notes/openapi.yaml` with this complete fictional API. It documents a response without calling a live service:

package/agent-docs/publish/api-references.sections/author-the-reference-page.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Author the reference page
 
 Create `content/create-note.mdx`:

package/agent-docs/publish/api-references.sections/build-and-verify-the-output.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Build and verify the output
 
 ```sh

package/agent-docs/publish/api-references.sections/inspect-the-machine-readable-contract.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Inspect the machine-readable contract
 
 [Focused contracts](https://www.shoalrun.com/api-docs/focused-contracts.md) retain transitive schemas, examples, and security schemes for one operation. To publish the full source instead, set `source.publish: true`. That also enables focused contracts. A discovery endpoint must use HTTPS and needs `site.origin`; see [configuration](https://www.shoalrun.com/config.md).

package/agent-docs/publish/api-references.sections/next-steps.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Next steps
 
 ### Publish several versions

package/agent-docs/publish/api-references.sections/preview-a-small-api-reference.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Preview a small API reference
 
 Compare the authored [Create a note](https://www.shoalrun.com/example-api/create-note.md) and generated [Get a note](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) with their [fictional source](https://www.shoalrun.com/api/notes/production/current/openapi.yaml), Markdown twins, and focused contracts.

package/agent-docs/publish/api-references.sections/put-the-spec-in-your-project.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Put the spec in your project
 
 Create `apis/notes/openapi.yaml` with this complete fictional API. It documents a response without calling a live service:

package/agent-docs/publish/api-references.sections/register-the-operation.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Register the operation
 
 Add this top-level entry to your existing `docs.config.yaml`:

package/agent-docs/publish/api-references.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -25,6 +25,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Related reading
 
 ### Next steps

package/agent-docs/publish/api-references.sections/review-imported-content-before-publishing.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Review imported content before publishing
 
 Shoalrun requires `publicReview.digest` for every API whose content appears in a public page, embed, or focused contract. A missing or stale digest stops a normal build. Generate a local candidate in a fresh temporary directory:

package/agent-docs/publish/api-references.sections/what-readers-get.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## What readers get
 
 An authored reference adds editorial context to the operation contract. A [generated reference](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) includes the same contract details without an MDX introduction. For tasks spanning several operations, write a linked guide such as [Write a note](https://www.shoalrun.com/example-api/write-note.md). These fictional examples don't imply a live API or tested requests.