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

package/agent-docs/author/add-page.md

@@ -0,0 +1,124 @@
+---
+id: guide.add-page
+title: Create a page
+summary: Create a page from a template, complete its scaffolded draft, and
+  publish it in navigation.
+type: how-to
+area: authoring
+subarea: authoring-pages
+canonical: /author/add-page
+---
+
+# Create a page
+
+> 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 > Create a page
+
+**Updated: 2026-10-26.**
+
+Create a page from a template with `scaffold`. Templates prompt you for the page's frontmatter, an introduction, the main content, and related pages before you publish. This is the recommended authoring workflow for new pages.
+
+This guide assumes you have completed [getting started](https://www.shoalrun.com/start.md) and are working in `my-docs/`. Keep `SHOALRUN_CLI` pointing to the checkout's `framework/dist/cli.js`.
+
+## Choose a template
+
+Choose the template that matches what the reader needs to accomplish.
+
+| Template        | Use it for                                                                            |
+| --------------- | ------------------------------------------------------------------------------------- |
+| `tutorial`      | A reliable guided exercise for learning by doing.                                     |
+| `how-to`        | A specific task, with practical actions and a success check.                          |
+| `reference`     | Exact syntax, fields, options, examples, errors, and limits.                          |
+| `explanation`   | Concepts, context, reasons, and tradeoffs.                                            |
+| `api-reference` | Editorial context above generated operation details; requires one known operation ID. |
+| `recipe`        | A complete task used by recipe and cookbook workflows.                                |
+| `ingredient`    | One reusable action or check used in recipes.                                         |
+| `cookbook`      | A page that helps readers choose complete recipes.                                    |
+
+These templates ship with the CLI. `guide` and `troubleshooting` remain available for compatibility. Projects can register additional templates or override built-ins.
+
+The CLI includes a [`recipe` template](https://www.shoalrun.com/author/recipe-drafts.md) for a complete customer task, written directly or assembled from ingredients. Built-in `ingredient` and `cookbook` templates support reusable steps and workflow selection. The `ingredient draft` command can start one ingredient from an API example; `recipe draft` assembles an ordered set of ingredient files for review.
+
+Use the project's template for the document type when one exists. Project templates can also override the built-in names. See [templates](https://www.shoalrun.com/author/templates.md) to register or change one.
+
+## Scaffold the draft
+
+From the project directory:
+
+```sh
+node "$SHOALRUN_CLI" scaffold how-to -n content/track-parcel.mdx \
+  --id how-to.track-parcel --title 'Track a parcel'
+```
+
+The command finds `docs.config.yaml`, creates the file, and adds the template body and draft frontmatter. It refuses to overwrite an existing file. This example sets the stable ID and title explicitly; the CLI derives the slug `/track-parcel` from the target path.
+
+Without overrides, this path would produce ID `how-to.track-parcel` and title `Track Parcel`. The generated summary starts with `Draft guide for ` and must be replaced before publication. Publication fields come from your project configuration.
+
+## Complete the template
+
+Open `content/track-parcel.mdx` and work through its prompts:
+
+1. Read the comments in the frontmatter, fill in the placeholder fields, and delete the comment lines.
+2. Set `updated` to today's date in `YYYY-MM-DD` format. Write an introduction of 150 words or fewer and remove irrelevant optional sections.
+3. Follow the chosen shape. Write a guided exercise, practical task actions, organized reference facts, or conceptual discussion. For this how-to, write actions and checks.
+4. Keep the **HTML, Markdown, and agents** section when the page uses a component or behavior that changes either output or what an agent reads. Otherwise delete it.
+5. Add relationships for the page, or delete Related reading. Verify technical claims before you publish.
+
+Replace every TODO prompt enclosed in double square brackets. Adapt the sections to the task rather than leaving irrelevant prompts behind. Templates provide a starting structure; editing a template later does not rewrite this page. The [quickstart](https://www.shoalrun.com/start.md) shows a completed example.
+
+Keep the generated `access.policy: draft` while writing. Drafts are validated but omitted from the published site, even if the starter defaults to public access. Headings in the body begin at level 2 because Shoalrun renders the page title separately.
+
+## Publish the page
+
+After reviewing the content, change the generated access value to:
+
+```yaml
+access: { policy: public }
+```
+
+Keep the ID `how-to.track-parcel` and slug `/track-parcel` for this example. Check the channel, version, and language match an enabled publication. The build rejects public pages with unresolved template prompts or the generated draft summary. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) for shared defaults and publication rules. The [generated frontmatter reference](https://www.shoalrun.com/author/frontmatter-reference.md) lists native fields and this site's project declarations.
+
+## Put it in navigation
+
+Append this item to the existing `navigation` list in `docs.config.yaml`:
+
+```yaml
+  - id: track-parcel
+    doc: how-to.track-parcel
+```
+
+Use the page's frontmatter ID for `doc`; the navigation item's own `id` identifies that menu entry. You can nest the item under a group's `items` list instead. Navigation uses the page title as its label unless you supply `label`.
+
+A public page can have a working URL without appearing in the sidebar. Adding this entry makes it discoverable there. See [organize navigation](https://www.shoalrun.com/author/navigation.md) for groups, includes, and links.
+
+## Verify HTML and Markdown
+
+From the project directory:
+
+```sh
+node "$SHOALRUN_CLI" build docs.config.yaml site-dist
+node "$SHOALRUN_CLI" serve site-dist --port 8765
+```
+
+Open `http://127.0.0.1:8765/track-parcel` and confirm that the page appears in navigation and that its links work. Then open `http://127.0.0.1:8765/track-parcel.md` and confirm that the same prose is available and internal links point to Markdown pages. Press **Ctrl+C** to stop the server.
+
+If you use another publication or a language prefix, inspect the built `documents.json` for the resolved URLs. To preview edits continuously, use `node "$SHOALRUN_CLI" dev docs.config.yaml site-dist --port 8765`.
+
+Next, [organize your navigation](https://www.shoalrun.com/author/navigation.md) as the site grows.
+
+## Related reading
+
+### Next steps
+
+- [Templates](https://www.shoalrun.com/author/templates.md) — Adapt the starting template for your team's next pages.
+
+### Reference while working
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md) — Check the scaffolded page's publication and metadata fields.
+
+### Related topics
+
+- [Troubleshooting](https://www.shoalrun.com/publish/troubleshooting.md) — Find why a page is missing or a build fails.

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

@@ -0,0 +1,59 @@
+---
+id: guide.authoring-agent-overview
+title: Authoring tools for your coding agent
+summary: Understand project discovery, working-tree editing, snapshot
+  validation, and human review.
+type: explanation
+area: authoring
+subarea: authoring-agent-workflows
+audiences:
+  - authors
+subjectLifecycle: experimental
+canonical: /author/agent-overview
+---
+
+# Authoring tools for 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 > Project tools > Tools overview
+
+**Updated: 2026-10-27.**
+
+**Status: Experimental.**
+
+Shoalrun supplies documentation tools for existing coding agents. Your agent supplies its model, file editing, repository exploration, and execution permissions. Shoalrun supplies canonical writing guidance, templates, project discovery, and checks. The tools make no authoring provider calls.
+
+## Discover before editing
+
+Project discovery works without selecting a page. It lists pages, configured guidance, templates, navigation, relationships, and findings. Topic searches help your agent find candidates across the project. Source reads return bounded passages and file digests. Bundled documentation search and reads explain framework behavior; your project's guidance governs local conventions.
+
+## Edit and check
+
+The default is to edit ordinary working-tree files using your agent's file tools. A baseline records the current files, including earlier local changes. Snapshot validation captures those files and compiles a separate copy, so checking a draft does not rewrite the project. Results identify affected pages, findings, skipped checks, and retained artifacts. A freshness check tells you whether those results still apply after further edits.
+
+Existing checked plan/apply commands remain available for clients that need them. Their digest checks and application protections are preserved.
+
+## Review and release
+
+Compiler checks establish structural validity. They do not 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).
+
+## Related reading
+
+### Next steps
+
+- [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Discover the project and check a working-tree edit. (Status: experimental.)
+
+### Reference while working
+
+- [Authoring tools commands](https://www.shoalrun.com/author/workspace/commands.md) — Look up discovery, baseline, validation, and freshness commands. (Status: experimental.)
+
+- [Design a writing guide](https://www.shoalrun.com/author/design-writing-guides.md) — Give both people and models useful project writing guidance.
+
+### Go deeper
+
+- [How snapshot validation works](https://www.shoalrun.com/author/agent-workflow.md) — Understand capture coverage, checks, artifacts, and freshness. (Status: experimental.)

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

@@ -0,0 +1,65 @@
+---
+id: guide.authoring-agent-workflow
+title: How snapshot validation works
+summary: Understand captured files, affected-page coverage, freshness, and
+  validation limits.
+type: explanation
+area: authoring
+subarea: authoring-agent-workflows
+audiences:
+  - authors
+subjectLifecycle: experimental
+canonical: /author/agent-workflow
+---
+
+# How snapshot validation works
+
+> 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 > Project tools > Snapshot validation
+
+**Updated: 2026-10-26.**
+
+**Status: Experimental.**
+
+Snapshot validation checks a captured working tree. Your existing coding agent edits files; Shoalrun records and checks the resulting state.
+
+## Baselines and captures
+
+A baseline records source paths, modes, and digests before a task. It includes preexisting dirty and untracked files. Validation compares with that baseline, or uses explicit file and page selectors, to identify affected pages. Configuration, dependency, and deletion changes can expand coverage to all authored pages.
+
+The capture excludes generated output, dependencies, repository metadata, credentials, and private archives. Files must fit capture limits. Symlinks and absolute dependency references are rejected. Declared sibling dependencies can be captured within the project's parent directory. Capture races produce a failure rather than an apparently current result.
+
+## Checks and artifacts
+
+The compiler renders affected drafts in the captured project while preserving their publication access metadata. It checks metadata, identities, routes, components, navigation, relationships, and document links. Local HTML and Markdown links and configured API contracts are checked in the captured output. External URLs are not requested.
+
+Configured shell checks are skipped by default. With `--run-checks`, trusted project commands run inside the capture under the harness's permissions. This is not an operating-system sandbox; scripts can still access absolute paths or services. Model evaluators are skipped. Executable metadata and highlighting extensions are currently unavailable to snapshot validation.
+
+The result retains the captured project, built site, and JSON report. Remove the reported artifact directory when finished. Compiler success does not replace factual and editorial review.
+
+## Freshness and scope
+
+The report identifies the snapshot and source digests. `docs validation-status` compares current inputs with the report and returns stale when they differ. A report only applies to its recorded coverage and checks. Review skipped and unavailable checks before accepting a result.
+
+Snapshot validation does not apply edits, start a preview server, commit, or publish. Existing checked plan/apply clients retain their own review and freshness protections.
+
+## Matching previews and review reports
+
+`docs review` reads a retained validation report as JSON or Markdown. It associates changed-file operations and digests with the declared baseline and exposes findings, check status, affected routes, dependencies, and artifacts. Baselines retain digests rather than earlier contents, so your harness must retain the task diff. Evidence, semantic review, and author decisions are not inferred by these tools.
+
+`docs preview` makes a separate private copy of the validated site and starts a foreground loopback server. Every affected rendered page has HTML and Markdown URLs. HTML pages link to a browser review and display freshness; the original Markdown output remains unchanged. Replacing source files does not replace the preview's content. Replacing the report makes its pinned preview stale. Artifact changes prevent startup or stop page serving.
+
+After editing, validate again and restart from the new report. Ctrl-C or SIGTERM closes the server and removes only its serving copy. Retained validation artifacts have a separate lifecycle. The preview starts no source watcher or provider requests.
+
+## Related reading
+
+### Next steps
+
+- [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Capture a baseline and validate a working-tree edit. (Status: experimental.)
+
+### Reference while working
+
+- [Authoring tools commands](https://www.shoalrun.com/author/workspace/commands.md) — Find commands for discovery and snapshot validation. (Status: experimental.)

package/agent-docs/author/agents.md

@@ -0,0 +1,53 @@
+---
+id: guide.write-with-agents
+title: Write with agents
+summary: Use your existing coding agent with project guidance, templates, and
+  provider-free documentation tools.
+type: explanation
+area: authoring
+subarea: authoring-writing
+audiences:
+  - authors
+canonical: /author/agents
+---
+
+# Write with agents
+
+> 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 > Overview
+
+**Updated: 2026-10-26.**
+
+Use your existing coding agent to write and revise Shoalrun documentation. Start with the workflow that matches your task.
+
+## Choose a writing task
+
+Each guide below describes a different starting point:
+
+| Task                                              | Start here                                                                             |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Draft a new page                                  | [Use your coding agent](https://www.shoalrun.com/author/coding-agent.md)               |
+| Check edits in your working tree                  | [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) |
+| Apply a plan from an existing checked-plan client | [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md)        |
+| Give your agent the bundled workflow instructions | [Use agent skills](https://www.shoalrun.com/contribute/agent-skills.md)                |
+
+[Authoring tools for your coding agent](https://www.shoalrun.com/author/agent-overview.md) explains project discovery, isolated validation, and the division of work between Shoalrun and your agent. No additional authoring provider key is required.
+
+## Review the result
+
+Review the diff, supporting sources, and built HTML and Markdown before accepting an edit. For coverage, skipped checks, and result freshness, follow [snapshot validation](https://www.shoalrun.com/author/agent-workflow.md). You decide when the result is ready to publish.
+
+## Shared writing guidance
+
+[Design templates](https://www.shoalrun.com/author/design-templates.md) and [Design a writing guide](https://www.shoalrun.com/author/design-writing-guides.md) explain how to give your agent useful project conventions. The [example writing guide](https://www.shoalrun.com/author/writing-style.md) is a starting point to adapt.
+
+## Related reading
+
+### Related topics
+
+- [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md) — Start with the agent authoring workflow. (Status: experimental.)
+
+- [Use your coding agent](https://www.shoalrun.com/author/coding-agent.md) — Choose the authoring workflow that fits how you work.

package/agent-docs/author/analytics.md

@@ -0,0 +1,286 @@
+---
+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) > Customize > Analytics
+
+**Updated: 2026-10-26.**
+
+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.
+
+## Configure an adapter
+
+Point `analytics.module` at a local `.js` or `.mjs` file:
+
+```yaml title="docs.config.yaml"
+analytics:
+  module: ./analytics.js
+```
+
+Paths resolve relative to the declaring config file, including included files. The build copies the module to `/assets/analytics-adapter.js` without executing or bundling it. Supply a self-contained module or use browser-resolvable imports; relative imports resolve from the copied asset directory. The file becomes public browser code.
+
+For example, if your page already initializes a client named `myAnalytics`, forward events to its `capture` method:
+
+```js title="analytics.js"
+export function track(event) {
+  globalThis.myAnalytics.capture(event.name, event.properties);
+}
+```
+
+Replace the client and method with your service’s API. Set `analytics: false`, or omit the setting, to exclude the runtime, adapter, and page context. Unknown settings, unsupported extensions, and missing files fail the build.
+
+## Adapter exports and consent
+
+Implement these exports in your browser module:
+
+| Export          | Required | Contract                                                                                                              |
+| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `track(event)`  | Yes      | Receive an event; may return a promise. The adapter owns delivery, batching, retries, and flushing before navigation. |
+| `init(context)` | No       | Initialize the service or await consent; may return a promise. Events start after it resolves.                        |
+
+The read-only context provides `page` properties, `setEnabled(boolean)`, and `track(name, properties, element?)`. Import or initialization failures disable analytics for the page. Thrown or rejected `track` calls are caught without interrupting controls or navigation; Shoalrun does not retry them.
+
+Events are discarded while initialization is pending or delivery is disabled. After initialization, Shoalrun sends `page_view` if enabled. To delay collection, await consent in `init`, or call `setEnabled(false)` and enable delivery from your consent callback. In the latter case, call `track('page_view')` after enabling to count the current page.
+
+You can also disable delivery through the public hook:
+
+```js
+globalThis.shoalrunAnalytics?.setEnabled(false);
+```
+
+Connect consent changes to your SDK too. Disabling Shoalrun does not stop SDK-generated events, unload the SDK, or revoke data already sent.
+
+## Event format
+
+Each event has `schemaVersion`, `name`, and `properties`. For example:
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "content_tab_change",
+  "properties": {
+    "pageId": "guide.example",
+    "pageUrl": "/example",
+    "documentType": "reference",
+    "channel": "production",
+    "version": "current",
+    "language": "en",
+    "navigationSectionId": "docs",
+    "componentId": "clients:tabs:1",
+    "componentType": "tabs",
+    "headingId": "clients",
+    "tabIndex": 1,
+    "tabId": "clients-2"
+  }
+}
+```
+
+Every event includes page identity and publication properties; `navigationSectionId` appears only for pages in a navigation tab. `pageUrl` is the published path without query or fragment. Custom properties cannot replace page identity.
+
+Events associated with an element add component context. `componentId` uses `data-analytics-id`, then the element’s HTML ID, then its heading, kind, and position. Generated IDs can change when content moves. `componentType` is `tabs`, `walkthrough`, `disclosure`, `code`, or `control`; `headingId` identifies the preceding article heading when available.
+
+## Built-in events
+
+Use these events to measure browser interactions. Each includes the page properties above.
+
+| Event                     | Additional properties                         | Trigger                                                                                                                                                                          |
+| ------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `page_view`               | None                                          | Once after adapter initialization, when delivery is enabled.                                                                                                                     |
+| `navigation_click`        | `region`, `targetPath`, `external`            | A section, sidebar, outline, breadcrumb, related-reading, card, hero, footer, header, article, or Markdown-action link is activated.                                             |
+| `content_tab_change`      | `tabIndex`, `tabId`                           | A different content tab is selected by click or keyboard. Initial selection and hash reveals are excluded.                                                                       |
+| `disclosure_toggle`       | `open`                                        | A reader opens or closes a Collapsible or article InfoHint through its summary. Programmatic initialization is excluded.                                                         |
+| `walkthrough_step_change` | `stepIndex`, `stepCount`, `layout`, `trigger` | A different walkthrough step becomes active through click, keyboard, or step scrolling. Initial selection and layout changes are excluded.                                       |
+| `code_copy`               | `language`, optional `stepIndex`              | A code example or walkthrough pane is successfully written to the clipboard.                                                                                                     |
+| `markdown_copy`           | None                                          | The full Markdown twin is successfully written to the clipboard.                                                                                                                 |
+| `section_link_copy`       | `targetHeadingId`                             | A heading's link is successfully written to the clipboard.                                                                                                                       |
+| `search_results`          | `queryLength`, `resultCount`, `status`        | A completed search settles for 300 ms. Status is `results`, `empty`, or `error`; the count is the displayed result count.                                                        |
+| `search_result_click`     | `queryLength`, `resultIndex`, `targetPath`    | A search result is activated, including through the keyboard.                                                                                                                    |
+| `reader_filter_change`    | `scope`, `filter_<facet>`, optional `inherit` | A site or page reader selection changes through the controls or reader-view API. Initialization does not emit it. Facet hyphens become underscores; values are choice-ID arrays. |
+
+Indexes start at zero. Navigation regions are `sections`, `sidebar`, `toc`, `breadcrumbs`, `related`, `card`, `hero`, `footer`, `header`, `content`, and `formats`; only HTTP(S) links qualify. Target paths omit queries and fragments. Built-in payloads exclude raw search queries, copied text, article text, reader identifiers, and referrers. A service SDK may add its own properties.
+
+Changing component attributes from a script does not necessarily emit an event. Browser page loads emit page views; back-forward cache restoration has no separate built-in event.
+
+## 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.
+
+## Custom interactions
+
+Site scripts can emit events from existing controls. For example, this site’s table-of-contents toggle calls the hook after hiding the panel:
+
+```js
+globalThis.shoalrunAnalytics?.track(
+  'toc_visibility_change',
+  { visible: false },
+  document.querySelector('.toc-visibility-toggle')
+);
+```
+
+The arguments are the event name, properties, and optional element for component context. Page properties are added automatically. The optional chain skips the call when analytics is unconfigured.
+
+This hook does not register MDX components: unknown components fail the build. Use the [supported components](https://www.shoalrun.com/author/components.md) or register a [trusted component plugin](https://www.shoalrun.com/author/components/custom.md) with shared HTML and Markdown content.
+
+Event names start with a lowercase letter and contain at most 64 lowercase letters, digits, or underscores.
+
+Custom properties have these limits:
+
+- Names start with a letter and contain at most 64 letters, digits, or underscores. `constructor` and `prototype` are reserved.
+- Each call accepts up to 32 properties.
+- Values can be strings of up to 256 characters, finite numbers, booleans, or arrays of up to 32 such values.
+- Objects, nulls, and unsupported values are omitted.
+
+`track` returns `true` when the adapter is invoked, not when delivery succeeds. It returns `false` if disabled, pending, invalid, or synchronously failed. Asynchronous failures are caught. The hook’s `enabled` property reports readiness and delivery state.
+
+## Inspect events locally
+
+Copy `framework/examples/analytics/inspector.js` beside your config and set `analytics.module` to `./inspector.js`. Its **Local events** panel and `window.shoalrunDebugEvents` show the latest 100 events in memory without sending requests. Use it only in local previews.
+
+The inspector shows Shoalrun events before translation, so confirm service delivery separately. It cannot show events generated by a provider SDK.
+
+## 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.
+
+## HTML, Markdown, and agents
+
+Instrumentation runs only in the browser and leaves Markdown and discovery artifacts unchanged. Agents that fetch Markdown or call tools without running page JavaScript are not counted.
+
+To measure those requests, collect CDN or hosting logs, add a server request hook, or enable the separate [MCP analytics adapter](https://www.shoalrun.com/publish/mcp-analytics.md). Include cache hits: origin logs alone miss responses served by a CDN. Shoalrun does not install a request collector.
+
+Measure discovery indexes, Markdown pages and sections, negotiated responses, and tool calls. Record the actual response representation because HTML and Markdown can share a URL. Keep health checks, `HEAD`, failures, and cache revalidation separate from successful body responses.
+
+Send a separate server event such as `documentation_request` with path, representation, status, cache status, page ID when known, and a request ID for deduplication. Keep these counts separate from browser page views. Avoid raw headers, IP addresses, query strings, and page bodies by default.
+
+A user agent is a claimed identity, not a verified one. People can fetch Markdown, and agents can use ordinary browsers; classify representation and claimed client separately. Requests do not prove reading, comprehension, or citation. Correlating them into sessions requires an explicit client or integration identifier; timing and IP address are unreliable.
+
+## 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/analytics.sections/adapter-exports-and-consent.md

@@ -0,0 +1,51 @@
+---
+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) > 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.
+
+## Adapter exports and consent
+
+Implement these exports in your browser module:
+
+| Export          | Required | Contract                                                                                                              |
+| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `track(event)`  | Yes      | Receive an event; may return a promise. The adapter owns delivery, batching, retries, and flushing before navigation. |
+| `init(context)` | No       | Initialize the service or await consent; may return a promise. Events start after it resolves.                        |
+
+The read-only context provides `page` properties, `setEnabled(boolean)`, and `track(name, properties, element?)`. Import or initialization failures disable analytics for the page. Thrown or rejected `track` calls are caught without interrupting controls or navigation; Shoalrun does not retry them.
+
+Events are discarded while initialization is pending or delivery is disabled. After initialization, Shoalrun sends `page_view` if enabled. To delay collection, await consent in `init`, or call `setEnabled(false)` and enable delivery from your consent callback. In the latter case, call `track('page_view')` after enabling to count the current page.
+
+You can also disable delivery through the public hook:
+
+```js
+globalThis.shoalrunAnalytics?.setEnabled(false);
+```
+
+Connect consent changes to your SDK too. Disabling Shoalrun does not stop SDK-generated events, unload the SDK, or revoke data already sent.