@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.12

package/agent-docs/author/analytics.sections/map-events-to-your-service.md

@@ -0,0 +1,42 @@
+---
+id: guide.analytics
+title: Bring your own analytics
+summary: Send documentation interaction events to your analytics service through
+  an optional browser adapter.
+type: reference
+area: quality
+subarea: quality-analytics
+canonical: /author/analytics
+---
+
+# Bring your own analytics
+
+> 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) > Configure and customize > Analytics
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/analytics.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Measure documentation tool calls separately from browser interactions.
+
+Shoalrun sends documentation interactions to an analytics service through an **adapter**: a browser module you supply to initialize the service and deliver events. Analytics is off by default. Shoalrun includes no service SDK, storage, visitor identity, or delivery queue.
+
+## Map events to your service
+
+Your adapter translates Shoalrun events into the service’s names, properties, and SDK calls. Use these rules when choosing mappings:
+
+- Use the service’s native page-view event or API for its standard traffic reports. Check required properties as well as the name.
+- Choose one source for each measurement. Disable equivalent automatic SDK events when the adapter supplies them.
+- Keep content interactions as custom events unless a native event matches their meaning and required properties.
+- Preserve page and component IDs, publication context, and `schemaVersion`. Check the destination’s limits on names and values.
+- Use the SDK’s separate APIs for identification, grouping, exceptions, or replay; renaming an interaction does not enable these features.
+
+Document each source, destination, property conversion, and automatic SDK feature you enable. Shoalrun has no universal page-exit or scroll-depth event. Verify one page visit and one content interaction in the destination, check they are counted once, and confirm native events populate the intended dashboard.

package/agent-docs/author/analytics.sections/posthog-example.md

@@ -0,0 +1,126 @@
+---
+id: guide.analytics
+title: Bring your own analytics
+summary: Send documentation interaction events to your analytics service through
+  an optional browser adapter.
+type: reference
+area: quality
+subarea: quality-analytics
+canonical: /author/analytics
+---
+
+# Bring your own analytics
+
+> 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) > Configure and customize > Analytics
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/analytics.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Measure documentation tool calls separately from browser interactions.
+
+Shoalrun sends documentation interactions to an analytics service through an **adapter**: a browser module you supply to initialize the service and deliver events. Analytics is off by default. Shoalrun includes no service SDK, storage, visitor identity, or delivery queue.
+
+## PostHog example
+
+This example sends native page views and page leaves to PostHog, with custom events for content interactions. The runnable adapter is `framework/examples/analytics/posthog.js`.
+
+1. ### Install the SDK and bundler
+
+   From your documentation project, install the browser SDK and a bundler:
+
+   ```sh
+   npm install posthog-js
+   npm install --save-dev esbuild
+   ```
+
+2. ### Create the adapter
+
+   Save this as `posthog.js` beside your config. Replace the public project token and ingestion host with values from PostHog’s web setup screen. Never use a personal API key in browser code.
+
+   ```js title="posthog.js"
+   import posthog from 'posthog-js';
+
+   export function init({ page }) {
+     posthog.init('phc_REPLACE_WITH_PUBLIC_PROJECT_TOKEN', {
+       api_host: 'https://us.i.posthog.com', // Use your project's ingestion host.
+       autocapture: false,
+       capture_dead_clicks: false,
+       capture_heatmaps: false,
+       capture_performance: false,
+       capture_exceptions: false,
+       disable_surveys: true,
+       capture_pageview: false,
+       capture_pageleave: true,
+       disable_scroll_properties: false,
+       disable_session_recording: true,
+       person_profiles: 'never',
+     });
+     // Super-properties persist across pages, including pages outside navigation tabs.
+     if (!page.navigationSectionId) posthog.unregister('navigationSectionId');
+     // These properties also accompany SDK-generated page-leave events.
+     posthog.register({
+       ...page,
+       environment: ['localhost', '127.0.0.1', '::1', '[::1]'].includes(location.hostname)
+         ? 'development' : 'production',
+     });
+   }
+
+   export function track(event) {
+     posthog.capture(event.name === 'page_view' ? '$pageview' : event.name, {
+       ...event.properties,
+       shoalrunSchemaVersion: event.schemaVersion,
+       environment: ['localhost', '127.0.0.1', '::1', '[::1]'].includes(location.hostname)
+         ? 'development' : 'production',
+     });
+   }
+   ```
+
+   The adapter maps `page_view` to `$pageview` and keeps other Shoalrun event names. Automatic page views are off to avoid duplicates. PostHog supplies `$pageleave` with scroll depth and duration. Generic click capture, replay, and person profiles are disabled.
+
+   Use custom names in Product Analytics insights and funnels. Do not map them to `$autocapture`, which requires SDK-generated element metadata. PostHog adds properties and manages browser storage; review its [SDK configuration](https://posthog.com/docs/libraries/js/config) for consent and content security policy requirements.
+
+3. ### Bundle and configure the module
+
+   Bundle the adapter and SDK into the file Shoalrun will copy:
+
+   ```sh
+   npx esbuild posthog.js --bundle --format=esm --platform=browser --outfile=analytics.js
+   ```
+
+   Keep your dependency lockfile and rebundle after changing the adapter or SDK. Point your config at the output:
+
+   ```yaml title="docs.config.yaml"
+   analytics:
+     module: ./analytics.js
+   ```
+
+   Build with your usual project command, or run the CLI from the same directory:
+
+   ```sh
+   shoalrun build docs.config.yaml dist
+   ```
+
+4. ### Verify events on localhost
+
+   Serve the built site locally. In PostHog’s live event stream, filter by `environment = development` and include internal or test users. Open a page and look for one `$pageview`; switch a tab or copy code and check for `content_tab_change` or `code_copy`. Page views should also appear in **Web Analytics**.
+
+   Scroll down, then follow a link to another page. Inspect the first page’s `$pageleave` properties:
+
+   | Property                                | Meaning                                                               |
+   | --------------------------------------- | --------------------------------------------------------------------- |
+   | `$prev_pageview_max_scroll_percentage`  | Furthest scroll position, from `0` to `1`; `1` means the bottom.      |
+   | `$prev_pageview_max_content_percentage` | Fraction of document height reached by the viewport, from `0` to `1`. |
+   | `$prev_pageview_duration`               | Seconds the page was open.                                            |
+
+   These measure the document, excluding scrolling within code panes. Time open does not prove active reading, and page-leave delivery is best effort. For visual scrollmaps, configure [PostHog heatmaps](https://posthog.com/docs/toolbar/heatmaps) separately; some engagement metrics require generic autocapture.
+
+   If events are missing, check consent, browser blockers, and network requests. Exclude development traffic from production reports or use a separate development project.

package/agent-docs/author/analytics.sections/related-reading.md

@@ -0,0 +1,42 @@
+---
+id: guide.analytics
+title: Bring your own analytics
+summary: Send documentation interaction events to your analytics service through
+  an optional browser adapter.
+type: reference
+area: quality
+subarea: quality-analytics
+canonical: /author/analytics
+---
+
+# Bring your own analytics
+
+> 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) > Configure and customize > Analytics
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/analytics.md)
+
+Shoalrun sends documentation interactions to an analytics service through an **adapter**: a browser module you supply to initialize the service and deliver events. Analytics is off by default. Shoalrun includes no service SDK, storage, visitor identity, or delivery queue.
+
+## Related reading
+
+### Next steps
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Measure documentation tool calls separately from browser interactions.
+
+### Reference while working
+
+- [Site search](https://www.shoalrun.com/author/search.md) — Configure the search provider whose displayed outcomes analytics records.
+
+- [Reader views](https://www.shoalrun.com/author/reader-views.md) — Define reader facets and understand their browser interactions.
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Find the project-level analytics module setting.
+
+### Related topics
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Collect browser interactions through the separate browser adapter.

package/agent-docs/author/authoring-agent.md

@@ -0,0 +1,102 @@
+---
+id: guide.authoring-agent
+title: Apply a checked edit plan
+summary: Find a page's sources, review an edit, and apply it through Shoalrun checks.
+type: how-to
+area: authoring
+subarea: authoring-agent-workflows
+audiences:
+  - authors
+subjectLifecycle: experimental
+canonical: /author/authoring-agent
+---
+
+# Apply a checked edit plan
+
+> 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) > Write documentation > Write with agents > Advanced workflows > Checked edit plans
+
+**Updated: 2026-10-26.**
+
+**Status: Experimental.**
+
+Use this optional workflow when your agent needs a digest-checked replacement plan before writing files. Your agent gathers evidence and writes the candidate; Shoalrun validates and applies the exact plan. For ordinary working-tree editing, follow [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) instead.
+
+## Prepare and apply an update
+
+1. ## Read the page and its owners
+
+   ```sh
+   shoalrun docs context guide.welcome --config docs.config.yaml
+   ```
+
+   Read the returned source files and the project's writing guide. Capture the source digest before drafting. Give your agent the requested change and supporting sources; those can include other repositories, specifications, or links it can inspect with its own tools.
+
+2. ## Write and review a candidate
+
+   Have the agent save a complete replacement file separately from the source. Preserve stable IDs, routes, publication fields, and access policy. Update the edit date. Ask for a diff, the evidence supporting changed claims, and any unresolved questions. Run the project's Vale rules and verify code examples.
+
+3. ## Create an exact edit plan
+
+   Create `edit-request.json` with full replacement text and the digest of the source used to draft it:
+
+   ```json
+   {
+     "edits": [
+       {
+         "file": "content/welcome.mdx",
+         "baseDigest": "<SHA-256 digest of the original source>",
+         "content": "<complete replacement file>"
+       }
+     ]
+   }
+   ```
+
+   The placeholders above must be replaced with actual values. Paths are relative to the project configuration directory.
+
+   ```sh
+   shoalrun docs plan --request-file edit-request.json --out edit-plan.json --config docs.config.yaml
+   shoalrun docs apply edit-plan.json --config docs.config.yaml --check
+   ```
+
+   The check builds a temporary copy and leaves source files unchanged. A stale source or failed build stops the edit. Plans support existing authored Markdown files and YAML files loaded by the configuration; use scaffolding for new files.
+
+4. ## Apply the reviewed plan
+
+   ```sh
+   shoalrun docs apply edit-plan.json --config docs.config.yaml
+   shoalrun audit docs.config.yaml
+   ```
+
+   Applying repeats freshness and build checks before writing. Inspect the resulting HTML and Markdown. The plan does not run configured audit tests, commit changes, or deploy; those are separate steps.
+
+## What checks establish
+
+Compiler checks catch problems such as broken document links and invalid components. Vale checks the rules your team configures. Neither establishes factual accuracy or whether a procedure works. Ask your agent to explain what it verified and what still needs review.
+
+Ordinary public builds exclude draft pages. Use the separate working-tree `docs validate` interface to render affected drafts in isolation without changing their authored access policy. This does not change the checked plan/apply contract described above.
+
+## Related reading
+
+### Read first
+
+- [Templates](https://www.shoalrun.com/author/templates.md) — Scaffold a draft page before an agent writes its content.
+
+### Reference while working
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md) — Review a drafted API page against its operation and contract.
+
+- [Example writing guide](https://www.shoalrun.com/author/writing-style.md) — Review this site's example editorial guidance.
+
+### Related topics
+
+- [Use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md) — Let an agent run the same draft, check, and apply loop.
+
+- [Write with agents](https://www.shoalrun.com/author/agents.md) — Start with the agent authoring workflow.
+
+- [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Use the checked edit commands with your existing coding agent. (Status: experimental.)
+
+- [Use your coding agent](https://www.shoalrun.com/author/coding-agent.md) — Prepare a checked edit to an existing page.

package/agent-docs/author/coding-agent.md

@@ -0,0 +1,90 @@
+---
+id: guide.coding-agent-authoring
+title: Use your coding agent
+summary: Give your agent project guidance and draft a new documentation page.
+type: how-to
+area: authoring
+subarea: authoring-agent-workflows
+audiences:
+  - authors
+canonical: /author/coding-agent
+---
+
+# Use your coding agent
+
+> 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) > Write documentation > Write with agents > Draft a page
+
+**Updated: 2026-10-26.**
+
+Use an agent that can read project files and run commands. It writes with its own model; Shoalrun requires no additional authoring API key.
+
+## Prepare your agent
+
+Install the [portable authoring skill](https://www.shoalrun.com/contribute/agent-skills.md) using your agent's supported skill setup. If it cannot load skills, give it the same project instructions and commands directly. Tell it where to find `docs.config.yaml`, your writing guide, and reviewed examples. The [example writing guide](https://www.shoalrun.com/author/writing-style.md) is a starting point you can adapt.
+
+The CLI's `docs search` and `docs read` commands read bundled Shoalrun guidance. The [MCP server](https://www.shoalrun.com/cli.md) offers documentation search and reads for agents that support MCP; it does not write project files. Your agent uses its own file tools and the CLI for edits.
+
+## Give a working-tree task
+
+Name the reader outcome and documentation project. Let the agent discover the relevant pages and required supporting changes from project policy. For example:
+
+```text
+Read the installed shoalrun-author/SKILL.md and work in this documentation project.
+Revise the authoring procedure so readers can write titled steps and inspect
+both outputs. Read project policy and supporting evidence first, preserve earlier
+local edits, capture a task baseline, edit files normally, and show the matching
+validation report, preview, and task diff. Do not commit or publish.
+```
+
+This uses the harness's own writer and execution permissions. Required navigation, relationships, and changelog entries come from the project instructions rather than an automatic compiler rule. If evidence is missing or policies conflict, the agent should identify the question for review.
+
+## Draft a new page
+
+1. ## Define the reader's task
+
+   Give your agent the audience, goal, intended page type, and supporting sources. Let it gather and evaluate evidence using its own tools. Ask it to identify missing facts rather than invent examples or behavior.
+
+2. ## Choose and scaffold a template
+
+   Use the project's [templates](https://www.shoalrun.com/author/templates.md). Record the starting state before scaffolding:
+
+   ```sh
+   shoalrun docs baseline --out .shoalrun/task-baseline.json --config docs.config.yaml
+   shoalrun scaffold how-to -n content/publish-a-site.mdx --config docs.config.yaml
+   ```
+
+   The new file is a draft. Replace the prompts, preserve its identity and publication metadata, and add required companions from project policy.
+
+3. ## Check and review the page
+
+   Run the project's style checker and configured checks. Read the draft, verify its examples, and review technical claims against the evidence.
+
+   ```sh
+   shoalrun docs validate --baseline .shoalrun/task-baseline.json --config docs.config.yaml
+   shoalrun docs review /path/from/result/report.json --format markdown
+   shoalrun docs preview /path/from/result/report.json --port 0
+   ```
+
+   Use the actual report path returned by validation. It renders affected drafts in a separate capture while preserving their authored access policy. Review findings, coverage, and skipped checks; use `--run-checks` only for applicable trusted commands under the harness's permissions. A stale, failed, incomplete, or unavailable result is not a pass. After edits, revalidate and restart the preview from the new report. Stop the foreground preview with Ctrl-C when finished.
+
+4. ## Prepare publication
+
+   After the author approves publication, change the page's access policy to public and build to a dedicated output directory. Inspect its HTML, Markdown, navigation, and links before committing or deploying.
+
+   ```sh
+   shoalrun build docs.config.yaml preview-output
+   ```
+
+## Related reading
+
+### Related topics
+
+- [Write with agents](https://www.shoalrun.com/author/agents.md) — Choose the authoring workflow that fits how you work.
+
+- [Use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md) — Give your coding agent the bundled Shoalrun workflow instructions.
+
+- [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md) — Prepare a checked edit to an existing page. (Status: experimental.)

package/agent-docs/author/components/action-link.md

@@ -0,0 +1,47 @@
+---
+id: guide.component.action-link
+title: Action links
+summary: Give a next step a prominent link style while retaining real navigation
+  semantics.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/components/action-link
+---
+
+# Action links
+
+> 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) > Components > Action links
+
+**Updated: 2026-10-27.**
+
+`<ActionLink>` styles a navigation link as a prominent action. `<Button>` is an alias for authors migrating button-like links. Both render a real `<a>` element, so they work with keyboard navigation and without JavaScript.
+
+## Syntax
+
+```mdx
+<ActionLink doc="guide.add-page">Create a page</ActionLink>
+<ActionLink href="https://example.com/download" variant="secondary">Download example</ActionLink>
+```
+
+[Create a page](https://www.shoalrun.com/author/add-page.md)
+[Download example](https://example.com/download)
+
+## Attributes
+
+Use these attributes to configure the component.
+
+| Attribute       | Required | Meaning                                                                    |
+| --------------- | -------- | -------------------------------------------------------------------------- |
+| `doc` or `href` | Yes, one | A stable document ID, site path, fragment, HTTP(S) URL, or `mailto:` link. |
+| `variant`       | No       | `primary` (default) or `secondary`.                                        |
+
+The body is nonempty inline text, with optional emphasis or inline code.
+
+## HTML, Markdown, and agents
+
+HTML renders a real link with a visible focus state. Markdown retains its label and destination, resolving `doc` IDs to the target Markdown page. An agent can follow the destination without interpreting the visual button style.