@shoalrun/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/skills/shoalrun-author/SKILL.md

@@ -29,6 +29,8 @@ Edit ordinary source files and required companions. Choose a page type and revie
 
 For release notes, lead with the reader-visible change and why it matters. Explain the previous and new behavior with a concrete example when useful, then state any upgrade action. Introduce unfamiliar terms before using them. Put implementation details and test counts after the explanation; they do not substitute for it. Distinguish measured improvements from expected benefits, and package publication from site deployment.
 
+When importing a related-reading or related-material section, inspect native relationships and `RelatedReading` before translating it to manual links. Choose the purpose and reason for each connection; an authoring hint is a suggestion, not authorization to create relationships automatically.
+
 When adapting source material, choose components by reader purpose rather than translating unfamiliar markup into a generic container. Use authored `Fields` for client settings, source-backed `ApiSchema` or operation references for HTTP contracts, and `Steps` for procedures. Check field presence, nullability, defaults, constraints, warnings, and nested relationships against the source in both outputs. Keep configuration settings distinct from API request fields, and prefer source-backed contract data to a second handwritten copy.
 
 ## Validate, preview and obtain review

package/styles/site.css

@@ -46,7 +46,10 @@ button{cursor:pointer}
 .navigation-dialog .section-disclosure{padding:.75rem 1rem}
 .navigation-dialog .section-nav-links{display:flex;flex-direction:column;gap:0}
 .navigation-dialog .section-nav-links a{overflow-wrap:anywhere}
-:is(#main,#docs-navigation,#page-outline):focus{outline:2px solid var(--color-accent);outline-offset:4px}
+/* Article focus is a reading destination, not a page-sized interactive control. */
+#main:focus{outline:none}
+#main:focus-visible h1{text-decoration-line:underline;text-decoration-color:var(--color-focus);text-decoration-thickness:3px;text-underline-offset:.2em}
+:is(#docs-navigation,#page-outline):focus{outline:2px solid var(--color-accent);outline-offset:4px}
 /* The masthead is its own stacking context (view-transition-name), so it needs a layer above sticky page parts for the search results to show over them; the expanded examples panel (30) still covers it. */
 .mast{position:relative;z-index:25;background:var(--color-surface);border-bottom:1px solid var(--color-border)}
 .mast-inner{max-width:var(--width-reference);margin:auto;min-height:4.5rem;padding:1rem 2rem;display:flex;gap:1rem;align-items:center;justify-content:space-between;flex-wrap:wrap}

package/agent-docs/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt

@@ -1,33 +0,0 @@
-# Changelog
-
-Full-page token counts use cl100k_base. Navigation section ID: changelog-tab. Publication: production/current/en.
-
-[All sections and published pages](https://www.shoalrun.com/llms.min.txt). This index covers this section only; shared and unlisted pages remain reachable through the global index. Reader views do not remove pages from this index.
-
-- [Agent discovery, verified Markdown, and incremental sync](https://www.shoalrun.com/changelog/2026-10-14-agent-readiness.md) — ID: change.agent-readiness. changelog-entry; 549 tokens. Compact discovery, content verification, and incremental fetching.
-
-- [Agent reading and evaluation](https://www.shoalrun.com/changelog/2026-10-15-evaluation-builds.md) — ID: change.evaluation-builds. changelog-entry; 1699 tokens. Smaller reads, lifecycle guidance, and reproducible evaluations.
-
-- [Content exports and documentation checks](https://www.shoalrun.com/changelog/2026-10-25.md) — ID: change.2026-10-25. changelog-entry; 671 tokens. Content exports and documentation checks.
-
-- [Safer exports and easier discovery for AI assistants](https://www.shoalrun.com/changelog/2026-10-26.md) — ID: change.2026-10-26. changelog-entry; 1291 tokens. Keep exported images and links with their pages, and help AI assistants find docs by topic.
-
-- [Clearer defaults, a feature showcase, and easier navigation](https://www.shoalrun.com/changelog/2026-10-27.md) — ID: change.2026-10-27. changelog-entry; 1226 tokens. Explore a complete starter, read clearer controls, and find focused configuration references alongside the new mobile navigation.
-
-- [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; 469 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; 381 tokens. Project discovery and captured working-tree validation.
-
-- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1002 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; 1148 tokens. MCP hosting, analytics, and shared component content.
-
-- [Navigation, page layouts, and browser analytics](https://www.shoalrun.com/changelog/2026-10-16-navigation-layouts.md) — ID: change.navigation-layouts. changelog-entry; 1095 tokens. Navigation sections, reader controls, layouts, and browser analytics.
-
-- [Search results and tooltips](https://www.shoalrun.com/changelog/2026-10-18-search-and-tooltips.md) — ID: change.search-and-tooltips. changelog-entry; 671 tokens. Indexed search and hover and focus tooltips.
-
-- [Experimental visual navigation and taxonomy enforcement](https://www.shoalrun.com/changelog/2026-10-19-visual-navigation.md) — ID: change.visual-navigation. changelog-entry; 749 tokens. Visual navigation and taxonomy validation.
-
-- [Portable working-tree authoring workflow](https://www.shoalrun.com/changelog/working-tree-skill.md) — ID: change.working-tree-skill. changelog-entry; 481 tokens. Agent discovery, native editing, validation, and snapshot review.

package/agent-docs/publish/api-references.sections/add-useful-examples.md

@@ -1,36 +0,0 @@
----
-id: guide.api-references
-title: Add an OpenAPI API
-summary: Import a local OpenAPI file, author an operation page, review its
-  public content, and build HTML and Markdown.
-type: how-to
-area: api
-subarea: api-contracts
-canonical: /publish/api-references
----
-
-# Add an OpenAPI API
-
-> 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 > Add an OpenAPI API
-
-**Updated: 2026-10-26.**
-
-Parent page: [Full Markdown page](/publish/api-references.md)
-
-**Page reading path** — these links apply to the full page.
-
-**Next steps**
-
-- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
-
-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 will 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.
-
-## Add useful examples
-
-[Named examples and generated commands](https://www.shoalrun.com/api-docs/generate.md) explains example selection, JSON shapes, and cURL behavior.

package/agent-docs/publish/api-references.sections/describe-filters-that-do-not-use-their-openapi-parameter-name.md

@@ -1,36 +0,0 @@
----
-id: guide.api-references
-title: Add an OpenAPI API
-summary: Import a local OpenAPI file, author an operation page, review its
-  public content, and build HTML and Markdown.
-type: how-to
-area: api
-subarea: api-contracts
-canonical: /publish/api-references
----
-
-# Add an OpenAPI API
-
-> 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 > Add an OpenAPI API
-
-**Updated: 2026-10-26.**
-
-Parent page: [Full Markdown page](/publish/api-references.md)
-
-**Page reading path** — these links apply to the full page.
-
-**Next steps**
-
-- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
-
-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 will 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.
-
-## Describe filters that do not use their OpenAPI parameter name
-
-The [query syntax example](https://www.shoalrun.com/api-docs/generate.md) configures direct query expressions and generated cURL.

package/agent-docs/publish/api-references.sections/link-guides-to-api-references.md

@@ -1,36 +0,0 @@
----
-id: guide.api-references
-title: Add an OpenAPI API
-summary: Import a local OpenAPI file, author an operation page, review its
-  public content, and build HTML and Markdown.
-type: how-to
-area: api
-subarea: api-contracts
-canonical: /publish/api-references
----
-
-# Add an OpenAPI API
-
-> 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 > Add an OpenAPI API
-
-**Updated: 2026-10-26.**
-
-Parent page: [Full Markdown page](/publish/api-references.md)
-
-**Page reading path** — these links apply to the full page.
-
-**Next steps**
-
-- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
-
-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 will 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.
-
-## Link guides to API references
-
-[Related API references](https://www.shoalrun.com/api-docs/generate.md) connects guides and references in both directions using stable page IDs.

package/agent-docs/publish/api-references.sections/map-extension-values-to-shoalrun-status.md

@@ -1,36 +0,0 @@
----
-id: guide.api-references
-title: Add an OpenAPI API
-summary: Import a local OpenAPI file, author an operation page, review its
-  public content, and build HTML and Markdown.
-type: how-to
-area: api
-subarea: api-contracts
-canonical: /publish/api-references
----
-
-# Add an OpenAPI API
-
-> 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 > Add an OpenAPI API
-
-**Updated: 2026-10-26.**
-
-Parent page: [Full Markdown page](/publish/api-references.md)
-
-**Page reading path** — these links apply to the full page.
-
-**Next steps**
-
-- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
-
-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 will 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.
-
-## Map extension values to Shoalrun status
-
-Use the [extension mappings reference](https://www.shoalrun.com/publish/openapi-extension-mappings.md) to map vendor `x-*` values to status badges.

package/agent-docs/publish/api-references.sections/publish-several-versions.md

@@ -1,36 +0,0 @@
----
-id: guide.api-references
-title: Add an OpenAPI API
-summary: Import a local OpenAPI file, author an operation page, review its
-  public content, and build HTML and Markdown.
-type: how-to
-area: api
-subarea: api-contracts
-canonical: /publish/api-references
----
-
-# Add an OpenAPI API
-
-> 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 > Add an OpenAPI API
-
-**Updated: 2026-10-26.**
-
-Parent page: [Full Markdown page](/publish/api-references.md)
-
-**Page reading path** — these links apply to the full page.
-
-**Next steps**
-
-- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
-
-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 will 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.
-
-## Publish several versions
-
-[Put multiple versions on one site](https://www.shoalrun.com/publish/publications.md) explains sources for each publication and stable operation bindings across versions.

package/agent-docs/publish/api-references.sections/use-a-template-for-editorial-context.md

@@ -1,36 +0,0 @@
----
-id: guide.api-references
-title: Add an OpenAPI API
-summary: Import a local OpenAPI file, author an operation page, review its
-  public content, and build HTML and Markdown.
-type: how-to
-area: api
-subarea: api-contracts
-canonical: /publish/api-references
----
-
-# Add an OpenAPI API
-
-> 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 > Add an OpenAPI API
-
-**Updated: 2026-10-26.**
-
-Parent page: [Full Markdown page](/publish/api-references.md)
-
-**Page reading path** — these links apply to the full page.
-
-**Next steps**
-
-- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
-
-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 will 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.
-
-## Use a template for editorial context
-
-[API reference templates](https://www.shoalrun.com/api-docs/generate.md) add editorial prompts without duplicating contract fields.