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

package/agent-docs/publish/manni.sections/how-this-site-uses-manni.md

@@ -0,0 +1,83 @@
+---
+id: guide.manni
+title: Use Manni with Shoalrun
+summary: Use Manni in your documentation project.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/manni
+---
+
+# Use Manni with Shoalrun
+
+> 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) > Publish and maintain > Use Manni with Shoalrun
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/publish/manni.md)
+
+[Manni](https://hawkeyexl.github.io/manni/) is a toolkit for managing and checking documentation. It can validate, query, and help fill page information; manage terminology; track connections between explanations and source code; and build knowledge graphs. It also provides tools for testing documentation and running evaluations.
+
+This guide focuses on its checking tools. You choose the rules, and Manni reports pages that break them. For example:
+
+- A page is missing its title or description.
+- A tutorial gives instructions but never tells readers how to check that they worked.
+- A page refers to a glossary term that no longer exists.
+- Code has changed underneath an explanation, so the explanation needs another look.
+
+Shoalrun builds and delivers your docs. Here, we use Manni to add checks before publishing, while its other tools remain available through the same command. You can use either tool without the other.
+
+This guide shows how to run Manni in a Shoalrun project and add a check to `shoalrun audit`. That command runs the checks you configure and reports whether they passed. Start with one useful rule, then add more when you need them. For a working example, see [how we use Manni on this site](https://www.shoalrun.com/publish/manni.md#how-this-site-uses-manni).
+
+Manni's [documentation site](https://hawkeyexl.github.io/manni/) describes its available tools and rules. Your choices go in `manni.config.yaml`; you do not need a separate Shoalrun setting for each Manni feature.
+
+## How this site uses Manni
+
+Here are some ways we use Manni to check the docs you are reading. You can adopt the examples that suit your project.
+
+**Catch broken glossary references.** Some pages list the glossary terms they discuss, such as “facet” or “reader view.” If an author types “reader veiw” in that list, the check fails because no such term exists. We check those lists against the [glossary](https://www.shoalrun.com/glossary.md), using its existing definitions. This does not check every word in the prose.
+
+**Keep instructions complete.** On this page and the [content export guide](https://www.shoalrun.com/publish/content-export.md), we require prerequisites, named steps with instructions, and a final result check. The [getting-started tutorial](https://www.shoalrun.com/start.md) must cover setup, creating a page, navigation, and checking both outputs. Two common problems in [troubleshooting](https://www.shoalrun.com/publish/troubleshooting.md) must explain their cause and what to do. Removing one of those required sections makes the check fail.
+
+**Try the quickstart commands.** A procedure test creates a disposable project and follows the quickstart's initialization, scaffolding, and build instructions. It uses the completed page and navigation examples from the guide, then checks the promised HTML, Markdown, and links. Manni runs this test through [Doc Detective](https://doc-detective.com/). Registry login, package downloading, and the long-running preview server remain manual steps.
+
+**Check every published HTML page.** Manni opens each page in a browser and checks for problems such as unnamed buttons, missing image descriptions, and insufficient contrast. We use the build's page list, so pages outside navigation are checked too. This scan covers browser pages; Markdown and API downloads are separate resources.
+
+**Find explanations that need another review.** Our metadata guide explains which settings win when a page and its project configuration provide different values. We connect that paragraph to the code that implements the behavior. Manni records both texts and flags a change to either one. A person then reviews whether the explanation still matches the code.
+
+The glossary, structure, and quickstart procedure checks run when we audit our documentation. The accessibility scan runs against an existing build. The code citation check runs separately because it needs a copy of the framework source code. None of these checks are required for your own Shoalrun project.
+
+### Run these checks in this documentation repository
+
+These scripts belong to this site's documentation project:
+
+```sh
+npm run docs:terms
+npm run docs:structure
+npm run docs:procedures
+```
+
+The glossary script reads four definitions from the existing glossary and gives them to Manni. Pages identify their glossary references with `concepts` in their YAML headers. The structure check uses a Manni template that understands Shoalrun's `Steps` and `Step` components.
+
+The procedure check uses the project's installed CLI and pinned Doc Detective dependency. It extracts selected commands and completed examples from the quickstart, runs them in a temporary directory, and removes the directory afterward. Doc Detective's automatic updates and telemetry are disabled for this check.
+
+For accessibility, build once and scan that output:
+
+```sh
+npm run docs:build
+npm run docs:a11y
+```
+
+The scan starts a temporary local server and checks every HTML page named in `documents.json`, including pages without navigation links. It fails on detected violations, skipped pages, or incomplete coverage. It reuses the built files and does not run another build. You can select another built directory with `SHOALRUN_BUILT_SITE`.
+
+To check the connection between our metadata guide and its implementation, provide a framework source checkout. Replace `/path/to/shoalrun` with its location:
+
+```sh
+npm run docs:citations -- --repo framework=/path/to/shoalrun
+```
+
+The citation record is kept outside the published page. Review changes to the explanation and code before updating that record. It identifies the source version reviewed; it does not replace testing the installed Shoalrun package.

package/agent-docs/publish/manni.sections/optional-custom-policies.md

@@ -0,0 +1,42 @@
+---
+id: guide.manni
+title: Use Manni with Shoalrun
+summary: Use Manni in your documentation project.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/manni
+---
+
+# Use Manni with Shoalrun
+
+> 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) > Publish and maintain > Use Manni with Shoalrun
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/publish/manni.md)
+
+[Manni](https://hawkeyexl.github.io/manni/) is a toolkit for managing and checking documentation. It can validate, query, and help fill page information; manage terminology; track connections between explanations and source code; and build knowledge graphs. It also provides tools for testing documentation and running evaluations.
+
+This guide focuses on its checking tools. You choose the rules, and Manni reports pages that break them. For example:
+
+- A page is missing its title or description.
+- A tutorial gives instructions but never tells readers how to check that they worked.
+- A page refers to a glossary term that no longer exists.
+- Code has changed underneath an explanation, so the explanation needs another look.
+
+Shoalrun builds and delivers your docs. Here, we use Manni to add checks before publishing, while its other tools remain available through the same command. You can use either tool without the other.
+
+This guide shows how to run Manni in a Shoalrun project and add a check to `shoalrun audit`. That command runs the checks you configure and reports whether they passed. Start with one useful rule, then add more when you need them. For a working example, see [how we use Manni on this site](https://www.shoalrun.com/publish/manni.md#how-this-site-uses-manni).
+
+Manni's [documentation site](https://hawkeyexl.github.io/manni/) describes its available tools and rules. Your choices go in `manni.config.yaml`; you do not need a separate Shoalrun setting for each Manni feature.
+
+## Optional custom policies
+
+You can add your own rules as a local JSON Schema in `meta.schemas`. For example, if a page records a review date, you might require a note explaining what was reviewed. Those fields and rules belong to your project; Manni does not require them.
+
+Keep simple required-field, type, and enum rules in [Shoalrun's field declarations](https://www.shoalrun.com/author/custom-metadata.md). Add a custom Manni schema when you need conditional rules, and include that schema in the audit's captured inputs. A recorded verification date and note establish a metadata contract; they do not prove accuracy or freshness.

package/agent-docs/publish/manni.sections/prerequisites.md

@@ -0,0 +1,40 @@
+---
+id: guide.manni
+title: Use Manni with Shoalrun
+summary: Use Manni in your documentation project.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/manni
+---
+
+# Use Manni with Shoalrun
+
+> 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) > Publish and maintain > Use Manni with Shoalrun
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/publish/manni.md)
+
+[Manni](https://hawkeyexl.github.io/manni/) is a toolkit for managing and checking documentation. It can validate, query, and help fill page information; manage terminology; track connections between explanations and source code; and build knowledge graphs. It also provides tools for testing documentation and running evaluations.
+
+This guide focuses on its checking tools. You choose the rules, and Manni reports pages that break them. For example:
+
+- A page is missing its title or description.
+- A tutorial gives instructions but never tells readers how to check that they worked.
+- A page refers to a glossary term that no longer exists.
+- Code has changed underneath an explanation, so the explanation needs another look.
+
+Shoalrun builds and delivers your docs. Here, we use Manni to add checks before publishing, while its other tools remain available through the same command. You can use either tool without the other.
+
+This guide shows how to run Manni in a Shoalrun project and add a check to `shoalrun audit`. That command runs the checks you configure and reports whether they passed. Start with one useful rule, then add more when you need them. For a working example, see [how we use Manni on this site](https://www.shoalrun.com/publish/manni.md#how-this-site-uses-manni).
+
+Manni's [documentation site](https://hawkeyexl.github.io/manni/) describes its available tools and rules. Your choices go in `manni.config.yaml`; you do not need a separate Shoalrun setting for each Manni feature.
+
+## Prerequisites
+
+Start in a Shoalrun project's root, with its package manifest and a `docs/` directory containing `docs.config.yaml` and `content/`. Adjust paths for a different layout.

package/agent-docs/publish/mcp-analytics.md

@@ -0,0 +1,356 @@
+---
+id: guide.mcp-analytics
+title: Measure MCP tool usage
+summary: Send optional server events to your analytics service without changing
+  the documentation tools.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp-analytics
+---
+
+# Measure MCP tool usage
+
+> 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) > Search, chat, and agent access > MCP > Measure MCP tool usage
+
+**Updated: 2026-10-26.**
+
+Add a server adapter to measure calls to your [HTTP MCP endpoint](https://www.shoalrun.com/publish/mcp.md). Analytics is off by default. Enabling MCP does not enable tracking, and the browser analytics setting does not count tool calls.
+
+Your adapter chooses the service and sends the events. Shoalrun packages it for Node or the generated Vercel function. This setting does not instrument stdio, direct Markdown requests, or browser page views.
+
+## Enable analytics
+
+Add your server adapter to the MCP configuration. Readers do not need to change their client settings:
+
+```yaml title="docs.config.yaml"
+mcp:
+  enabled: true
+  access: public
+  publication: { channel: production, version: current, language: en }
+  analytics:
+    module: ./mcp-analytics/adapter.mjs
+```
+
+## Adapter exports
+
+Create a local `.js` or `.mjs` server module. Export `capture(event)` and, if your service queues events, `flush()`:
+
+```js title="mcp-analytics/adapter.mjs"
+export async function capture(event) {
+  // Send event to your service using its server SDK or HTTP API.
+}
+
+export async function flush() {
+  // Send queued events before the HTTP response completes.
+}
+```
+
+`capture` runs after each tool call, including failures. `flush` sends queued events before the response completes. Both can be asynchronous. Each has a one-second wait limit; analytics failures leave tool results unchanged. Set network timeouts in your adapter because Shoalrun cannot cancel a timed-out operation.
+
+Module paths resolve relative to the config file. Use static imports and install SDK dependencies in your project. Keep credentials in the server environment, since adapter files are copied into the build.
+
+## Event fields and service mappings
+
+Every event has the following fields. Arguments, search text, returned content, raw request headers, IP addresses, and user identity are excluded:
+
+| Field                 | Meaning                                                                          |
+| --------------------- | -------------------------------------------------------------------------------- |
+| `name`                | Always `mcp_tool_call`.                                                          |
+| `tool`                | `search_docs`, `get_page`, `get_outline`, or `get_section`.                      |
+| `durationMs`          | Tool execution time before analytics delivery.                                   |
+| `isError`             | Whether the documentation tool failed.                                           |
+| `errorCode`           | Error category when the tool failed.                                             |
+| `pageId`, `sectionId` | Published IDs when a successful read returns them.                               |
+| `buildId`             | Identity of the served build.                                                    |
+| `publication`         | Served `channel`, `version`, and `language`.                                     |
+| `client`              | Optional normalized client name, bounded version, source, and `verified: false`. |
+| `model`               | Optional model label, source, and `verified: false`.                             |
+
+Map these fields to your service’s event and property names. A service with native MCP analytics may require its SDK or reserved event names. A general event service can receive `mcp_tool_call` with these properties. The PostHog example below uses its native MCP SDK.
+
+Tool counts show usage, not comprehension. This adapter supplies no user or conversation identifier, so do not treat calls as unique people or agent sessions. Basic event capture leaves tool definitions and results unchanged. The optional SDK features below add analytics arguments and conversation handles.
+
+## Optionally identify the client and model
+
+The harness is the application running the agent, such as Cursor or Claude Code. To collect available client and model labels, explicitly enable `clientMetadata` in your adapter config:
+
+```yaml title="docs.config.yaml"
+mcp:
+  enabled: true
+  access: public
+  publication: { channel: production, version: current, language: en }
+  analytics:
+    module: ./mcp-analytics/adapter.mjs
+    clientMetadata: true
+```
+
+This option defaults to `false`. Shoalrun recognizes a fixed set of client names from MCP identity metadata or product tokens in selected headers. It discards raw headers and unrelated metadata. Client versions must match a bounded numeric version format.
+
+Model capture currently recognizes `model` in Codex’s `x-codex-turn-metadata`. It accepts labels from a fixed model-name registry, normalizes supported provider prefixes, and drops other values. A recognized family prefix alone does not qualify; custom deployment names and unknown models are omitted. Other clients may supply no supported model field; missing labels remain absent. The harness name does not establish which model it uses.
+
+Both labels are unverified client claims. Use them for usage reports, never authentication, access control, or billing. No user fingerprint or cross-request identity cache is added.
+
+OpenCode can also be recognized by the presence of its documented session metadata marker. Shoalrun discards that identifier; it records only the client label. Client-specific markers do not establish the model.
+
+## Optionally collect intent and group calls
+
+Intent describes why an agent called a tool. The PostHog adapter below supports separate `intent` and `conversationIds` switches, both off by default. Enable them alongside its module:
+
+```yaml title="docs.config.yaml"
+mcp:
+  enabled: true
+  access: public
+  publication: { channel: production, version: current, language: en }
+  analytics:
+    module: ./mcp-analytics/posthog.mjs
+    clientMetadata: true
+    intent: true
+    conversationIds: true
+```
+
+With intent enabled, the SDK adds a `context` argument asking for exactly one category: `discovery`, `setup`, `troubleshooting`, `configuration`, `reference_lookup`, `comparison`, `migration`, or `other`. Only these values can reach analytics. The adapter trims whitespace and normalizes case; it never stores an explanation or extracts a category from arbitrary text.
+
+An empty, invalid, or free-text value falls back to `discovery` for `search_docs` or `reference_lookup` for reading tools. PostHog marks the fallback as `inferred`. It describes the tool action, not a verified user goal, and does not invoke a model. Accepted client categories are also unverified claims.
+
+The SDK still accepts a string argument, so an agent might send private text despite the instruction. The outbound allowlist replaces that text before delivery. Raw queries, complete arguments, and returned documentation remain excluded.
+
+The endpoint creates a fresh server for every HTTP request. PostHog’s SDK can carry a stable session token for legacy clients. Conversation IDs also let clients reuse a handle across requests: the SDK adds a `conversation_id` argument and can return a handle for the agent to echo. Grouping depends on the client keeping its SDK token or echoing that handle. Reconnecting or ignoring the handle can split activity.
+
+These are analytics labels, not authentication. Client metadata capture in this SDK mode can also add an `llm_model` argument. It lets clients such as OpenCode report a model when no supported metadata field is available. Reported values remain unverified. Reconnect the client after enabling these options so it refreshes its tool schemas.
+
+An adapter can export `instrument(server, options)` to configure its SDK before serving the request. Return `true` to let that SDK own event capture; return `false` to retain Shoalrun’s `capture(event)` path. The options include these flags, build/publication identity, and helpers for normalized client/model labels and published resource IDs. Delivery still uses the adapter’s `flush()`.
+
+The PostHog example uses the existing low-level SDK server and resolves original tool argument names for stateless requests. Its outbound property allowlist drops raw headers, arguments, responses, and exception bodies. Other services need their own implementation of this optional hook.
+
+## Safeguards and limits
+
+If you need caller opt-in, the optional [`mcp.analytics.consent` header gate](https://www.shoalrun.com/config.md) records only calls with a matching header. Other callers can still use the tools. Leave it omitted for collection without client setup.
+
+The PostHog example builds each outbound event from allowed fields. It includes tool name, duration, outcome, build/publication identity, and validated public page or section IDs. Optional harness labels come from known names; optional model labels must appear in the fixed registry.
+
+The adapter drops raw arguments, search text, responses, headers, IP properties, error messages, and arbitrary event fields. It disables exception autocapture, requests no person profiles, and disables GeoIP enrichment. These controls apply to analytics delivery, not the documentation response or infrastructure access logs.
+
+Conversation and session IDs support grouping when enabled. They are pseudonymous identifiers, not proof that data is anonymous or that a particular person made the call. Leave grouping off when aggregate tool counts are enough. Never use client labels or intent categories for authentication or billing.
+
+Check PostHog’s **Settings → Project → IP data capture configuration → Discard client IP data** setting as an additional storage control. A network service still receives the source IP of its connection; this server adapter must not forward the caller’s IP. Hosting logs and other services need their own review. See [PostHog storage controls](https://posthog.com/docs/privacy/data-storage).
+
+Test the final delivered payload with a local receiver before changing the adapter or upgrading its SDK. Include names, emails, credentials, URLs, and private text in test arguments and metadata; verify they are absent from captured events. Public page IDs remain useful for usage analysis without recording the agent’s search or explanation. These safeguards do not establish a legal basis for collection or guarantee that all infrastructure stores no personal data.
+
+## Example: PostHog MCP analytics
+
+This example sends native `$mcp_tool_call` events through [PostHog’s MCP analytics SDK](https://posthog.com/docs/mcp-analytics/installation/typescript). Use Node.js 22.22 or newer with these tested package versions. No PostHog dependency is required for projects that omit this adapter.
+
+1. ### Install the SDKs
+
+   From your documentation project, install the pinned versions used by this example:
+
+   ```sh
+   npm install --save-exact @posthog/mcp@0.22.3 posthog-node@5.56.2
+   ```
+
+   PostHog’s MCP SDK is in beta. Review its compatibility notes before changing versions.
+
+2. ### Create the server adapter
+
+   Save the complete adapter in your project. It supports basic capture and the optional SDK features described above, with an outbound property allowlist:
+
+   ### Complete PostHog server adapter
+
+   ```js title="mcp-analytics/posthog.mjs"
+   import { PostHogMCP, instrument as instrumentMcp } from '@posthog/mcp';
+
+   // Set these on the Node host or Vercel function, never in a browser module.
+   const token = process.env.POSTHOG_PROJECT_TOKEN;
+   const client = token ? new PostHogMCP(token, {
+     host: process.env.POSTHOG_HOST ?? 'https://us.i.posthog.com',
+     flushInterval: 0,
+     captureModel: false,
+     enableConversationId: false,
+     enableExceptionAutocapture: false,
+     before_send(event) {
+       if (event.event !== '$mcp_tool_call') return null;
+       const { $mcp_error_message, ...properties } = event.properties;
+       return { ...event, properties };
+     },
+   }) : undefined;
+
+   export function capture(event) {
+     client?.captureToolCall({
+       toolName: event.tool,
+       durationMs: event.durationMs,
+       isError: event.isError,
+       errorType: event.errorCode,
+       ...(event.model ? { llmModel: event.model.name, llmModelSource: event.model.source } : {}),
+       properties: {
+         $process_person_profile: false,
+         $geoip_disable: true,
+         ...(event.client ? {
+           $mcp_client_name: event.client.name,
+           ...(event.client.version ? { $mcp_client_version: event.client.version } : {}),
+           client_source: event.client.source,
+           client_identity_verified: false,
+         } : {}),
+         ...(event.model ? { model_identity_verified: false } : {}),
+         $mcp_server_build: event.buildId,
+         channel: event.publication.channel,
+         version: event.publication.version,
+         language: event.publication.language,
+         ...(event.pageId ? { page_id: event.pageId } : {}),
+         ...(event.sectionId ? { section_id: event.sectionId } : {}),
+       },
+     });
+   }
+
+   export async function flush() {
+     await client?.flush();
+   }
+
+   // Optional interactive analytics. Returning true hands event capture to the SDK,
+   // so Shoalrun does not also emit a second tool-call event through capture().
+   export function instrument(server, options) {
+     if (!client || !options.intent && !options.conversationIds) return false;
+     // Fresh HTTP requests have not served tools/list. Supply the original schemas
+     // so the SDK strips only its own analytics arguments before strict validation.
+     const common = ['channel', 'version', 'language', 'maxTokens'];
+     const fields = {
+       search_docs: ['query', 'limit', ...common],
+       get_page: ['id', ...common],
+       get_outline: ['id', ...common],
+       get_section: ['id', 'section', ...common],
+     };
+     instrumentMcp(server.server, client, {
+       resolveOriginalTool: name => fields[name] ? {
+         inputSchema: { type: 'object', properties: Object.fromEntries(fields[name].map(key => [key, {}])) },
+       } : undefined,
+       context: options.intent ? {
+         description: "Choose exactly one documentation intent category: discovery, setup, troubleshooting, configuration, reference_lookup, comparison, migration, or other. Send only the category, never an explanation, names, credentials, or copied queries.",
+       } : false,
+       intentFallback: options.intent ? request => fallbackIntent(request.params?.name) : undefined,
+       captureModel: options.clientMetadata,
+       enableConversationId: options.conversationIds,
+       enableExceptionAutocapture: false,
+       serverBuild: options.buildId,
+       logger: () => {},
+       eventProperties: async (request, extra) => {
+         const metadata = options.metadata(extra);
+         const args = request.params?.arguments ?? {};
+         const resource = await options.resource(args.id, args.section);
+         return {
+           safe_page_id: resource.pageId,
+           safe_section_id: resource.sectionId,
+           ...(metadata.client ? {
+             safe_client_name: metadata.client.name,
+             safe_client_version: metadata.client.version,
+             client_source: metadata.client.source,
+           } : {}),
+         };
+       },
+       beforeSend: event => {
+         // Allowlist properties instead of forwarding SDK arguments, results, or headers.
+         if (event.event !== '$mcp_tool_call') return null;
+         const raw = event.properties;
+         const tool = raw.$mcp_tool_name;
+         if (!['search_docs', 'get_page', 'get_outline', 'get_section'].includes(tool)) return null;
+         const properties = {
+           $mcp_interface: 'mcp',
+           $mcp_source: 'posthog_mcp_analytics',
+           $mcp_tool_name: tool,
+           $mcp_resource_name: tool,
+           $mcp_server_name: 'shoalrun-docs',
+           $mcp_server_build: options.buildId,
+           $process_person_profile: false,
+           $geoip_disable: true,
+           $mcp_is_error: raw.$mcp_is_error === true,
+           ...(Number.isFinite(raw.$mcp_duration_ms) ? { $mcp_duration_ms: Math.max(0, raw.$mcp_duration_ms) } : {}),
+           channel: options.publication.channel,
+           version: options.publication.version,
+           language: options.publication.language,
+         };
+         if (raw.$mcp_is_error !== true) {
+           if (raw.safe_page_id) properties.page_id = raw.safe_page_id;
+           if (raw.safe_section_id) properties.section_id = raw.safe_section_id;
+         }
+         const clientLabel = options.clientMetadata ? options.client(raw.safe_client_name ?? raw.$mcp_client_name, raw.safe_client_version ?? raw.$mcp_client_version) : undefined;
+         if (clientLabel) {
+           properties.$mcp_client_name = clientLabel.name;
+           if (clientLabel.version) properties.$mcp_client_version = clientLabel.version;
+           properties.client_source = raw.client_source ?? clientLabel.source;
+           properties.client_identity_verified = false;
+         }
+         const model = options.clientMetadata ? options.modelName(raw.$mcp_llm_model) : undefined;
+         if (model) {
+           properties.$mcp_llm_model = model;
+           properties.$mcp_llm_model_source = raw.$mcp_llm_model_source === 'client_metadata' ? 'client_metadata' : 'self_reported';
+           properties.model_identity_verified = false;
+         }
+         if (options.intent) {
+           const intent = intentCategory(raw.$mcp_intent);
+           properties.$mcp_intent = intent ?? fallbackIntent(tool);
+           properties.$mcp_intent_source = intent && raw.$mcp_intent_source === 'context_parameter' ? 'context_parameter' : 'inferred';
+         }
+         // Only keep the SDK's validated UUIDv7 handle and derived session identifier.
+         const conversation = raw.$mcp_conversation_id;
+         if (options.conversationIds && typeof conversation === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(conversation)) {
+           properties.$mcp_conversation_id = conversation;
+
+         }
+         // Legacy clients can already carry the SDK's stateless session token.
+         if (options.conversationIds && typeof raw.$session_id === 'string' && /^(?:ses_)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(raw.$session_id)) properties.$session_id = raw.$session_id;
+         return { event: '$mcp_tool_call', distinct_id: properties.$session_id ?? 'anonymous', properties, ...(event.timestamp ? { timestamp: event.timestamp } : {}) };
+       },
+     });
+     return true;
+   }
+
+   const intentCategories = new Set([
+     'discovery', 'setup', 'troubleshooting', 'configuration',
+     'reference_lookup', 'comparison', 'migration', 'other',
+   ]);
+   function fallbackIntent(tool) {
+     return tool === 'search_docs' ? 'discovery'
+       : ['get_page', 'get_outline', 'get_section'].includes(tool) ? 'reference_lookup' : 'other';
+   }
+   function intentCategory(value) {
+     // Exact vocabulary only. Never redact, summarize, or retain arbitrary text.
+     if (typeof value !== 'string' || value.length > 32) return;
+     const category = value.trim().toLowerCase();
+     return intentCategories.has(category) ? category : undefined;
+   }
+   ```
+
+   Set `POSTHOG_PROJECT_TOKEN` on the Node process or Vercel function. Set `POSTHOG_HOST` for a different ingestion region. With no token, the example sends nothing. Keep these settings separate from the browser adapter.
+
+3. ### Enable the adapter and verify an event
+
+   Add `analytics` inside your enabled `mcp` configuration:
+
+   ```yaml title="docs.config.yaml"
+   mcp:
+     enabled: true
+     access: public
+     publication: { channel: production, version: current, language: en }
+     analytics:
+       module: ./mcp-analytics/posthog.mjs
+       clientMetadata: true
+   ```
+
+   Rebuild and serve the site, or generate its Vercel output as described in the [MCP guide](https://www.shoalrun.com/publish/mcp.md). Connect a client and call `get_page` for a known ID. In PostHog’s activity feed, filter for `$mcp_tool_call`; inspect the tool name, duration, outcome, and `page_id`.
+
+   You can test on localhost with a development project or a local ingestion receiver. Without identity or conversation tracking, this example does not correlate requests into agent sessions. With basic capture, no prompts or tools are added. When client metadata is available, inspect `$mcp_client_name` and `$mcp_llm_model`; their source and verification properties identify them as claims.
+
+   To stop collection, remove `mcp.analytics` or set it to `false`, rebuild, and restart the serving process or redeploy.
+
+## Related reading
+
+### Read first
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Enable and verify the HTTP endpoint before adding analytics.
+
+### Related topics
+
+- [Bring your own analytics](https://www.shoalrun.com/author/analytics.md) — Collect browser interactions through the separate browser adapter.

package/agent-docs/publish/mcp-analytics.sections/adapter-exports.md

@@ -0,0 +1,50 @@
+---
+id: guide.mcp-analytics
+title: Measure MCP tool usage
+summary: Send optional server events to your analytics service without changing
+  the documentation tools.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp-analytics
+---
+
+# Measure MCP tool usage
+
+> 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) > Search, chat, and agent access > MCP > Measure MCP tool usage
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/mcp-analytics.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Enable and verify the HTTP endpoint before adding analytics.
+
+Add a server adapter to measure calls to your [HTTP MCP endpoint](https://www.shoalrun.com/publish/mcp.md). Analytics is off by default. Enabling MCP does not enable tracking, and the browser analytics setting does not count tool calls.
+
+Your adapter chooses the service and sends the events. Shoalrun packages it for Node or the generated Vercel function. This setting does not instrument stdio, direct Markdown requests, or browser page views.
+
+## Adapter exports
+
+Create a local `.js` or `.mjs` server module. Export `capture(event)` and, if your service queues events, `flush()`:
+
+```js title="mcp-analytics/adapter.mjs"
+export async function capture(event) {
+  // Send event to your service using its server SDK or HTTP API.
+}
+
+export async function flush() {
+  // Send queued events before the HTTP response completes.
+}
+```
+
+`capture` runs after each tool call, including failures. `flush` sends queued events before the response completes. Both can be asynchronous. Each has a one-second wait limit; analytics failures leave tool results unchanged. Set network timeouts in your adapter because Shoalrun cannot cancel a timed-out operation.
+
+Module paths resolve relative to the config file. Use static imports and install SDK dependencies in your project. Keep credentials in the server environment, since adapter files are copied into the build.

package/agent-docs/publish/mcp-analytics.sections/enable-analytics.md

@@ -0,0 +1,45 @@
+---
+id: guide.mcp-analytics
+title: Measure MCP tool usage
+summary: Send optional server events to your analytics service without changing
+  the documentation tools.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp-analytics
+---
+
+# Measure MCP tool usage
+
+> 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) > Search, chat, and agent access > MCP > Measure MCP tool usage
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/mcp-analytics.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Enable and verify the HTTP endpoint before adding analytics.
+
+Add a server adapter to measure calls to your [HTTP MCP endpoint](https://www.shoalrun.com/publish/mcp.md). Analytics is off by default. Enabling MCP does not enable tracking, and the browser analytics setting does not count tool calls.
+
+Your adapter chooses the service and sends the events. Shoalrun packages it for Node or the generated Vercel function. This setting does not instrument stdio, direct Markdown requests, or browser page views.
+
+## Enable analytics
+
+Add your server adapter to the MCP configuration. Readers do not need to change their client settings:
+
+```yaml title="docs.config.yaml"
+mcp:
+  enabled: true
+  access: public
+  publication: { channel: production, version: current, language: en }
+  analytics:
+    module: ./mcp-analytics/adapter.mjs
+```