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

package/examples/diagrams/gallery.json

@@ -0,0 +1,236 @@
+[
+  {
+    "id": "flowchart",
+    "title": "Flowchart",
+    "summary": "Follow decisions and retry paths.",
+    "source": "flowchart TD\n Draft[Draft page] --> Check{Checks pass?}\n Check -->|Yes| Publish[Publish]\n Check -->|No| Revise[Revise page]\n Revise --> Draft"
+  },
+  {
+    "id": "sequence",
+    "title": "Sequence",
+    "summary": "Trace messages between an agent and documentation tools.",
+    "source": "sequenceDiagram\n participant Agent\n participant Docs\n Agent->>Docs: search_docs\n Docs-->>Agent: Page IDs\n Agent->>Docs: get_page\n Docs-->>Agent: Markdown and citation"
+  },
+  {
+    "id": "class",
+    "title": "Class",
+    "summary": "Describe types, fields, and relationships.",
+    "source": "classDiagram\n class Page {\n +String title\n +String slug\n +render()\n }\n class Section {\n +String heading\n }\n Page \"1\" *-- \"many\" Section"
+  },
+  {
+    "id": "er",
+    "title": "Entity relationship",
+    "summary": "Show entities and relationship cardinality.",
+    "source": "erDiagram\n PROJECT ||--o{ PAGE : contains\n PAGE ||--o{ SECTION : contains\n PAGE {\n string id PK\n string title\n }\n SECTION {\n string heading\n }"
+  },
+  {
+    "id": "state",
+    "title": "State",
+    "summary": "Explain a document lifecycle.",
+    "source": "stateDiagram-v2\n [*] --> Draft\n Draft --> Review\n Review --> Draft : revise\n Review --> Published : approve\n Published --> [*]"
+  },
+  {
+    "id": "gantt",
+    "title": "Gantt",
+    "summary": "Schedule work against explicit dates.",
+    "source": "gantt\n title Documentation release\n dateFormat YYYY-MM-DD\n section Preparation\n Draft guides :a, 2026-10-01, 3d\n Review guides :b, after a, 2d\n section Release\n Publish :after b, 1d"
+  },
+  {
+    "id": "git",
+    "title": "Git graph",
+    "summary": "Illustrate branches, commits, and merges.",
+    "source": "gitGraph\n commit id: \"Start\"\n branch guide\n checkout guide\n commit id: \"Draft\"\n checkout main\n merge guide\n commit id: \"Publish\""
+  },
+  {
+    "id": "pie",
+    "title": "Pie",
+    "summary": "Compare proportions with explicit values.",
+    "source": "pie title Example traffic channels\n \"Direct\" : 45\n \"Search\" : 35\n \"Referral\" : 20"
+  },
+  {
+    "id": "mindmap",
+    "title": "Mindmap",
+    "summary": "Organize related documentation topics.",
+    "source": "mindmap\n root((Documentation))\n  Authoring\n   Pages\n   Components\n  Publishing\n   Builds\n   Hosting"
+  },
+  {
+    "id": "kanban",
+    "title": "Kanban",
+    "summary": "Group tasks by workflow stage.",
+    "source": "kanban\n todo[To do]\n  setup[Configure project]\n review[Review]\n  draft[Review guide]\n done[Done]\n  install[Install tools]"
+  },
+  {
+    "id": "timeline",
+    "title": "Timeline",
+    "summary": "Place milestones in chronological order.",
+    "source": "timeline\n title Documentation rollout\n Week 1 : Draft guides\n Week 2 : Review examples : Test installation\n Week 3 : Publish documentation"
+  },
+  {
+    "id": "journey",
+    "title": "User journey",
+    "summary": "Show the stages and participants in a reader journey.",
+    "source": "journey\n title Find an answer\n section Discover\n  Search docs: 4: Reader\n  Open guide: 5: Reader\n section Apply\n  Try example: 4: Reader\n  Check result: 5: Reader"
+  },
+  {
+    "id": "quadrant",
+    "title": "Quadrant chart",
+    "summary": "Compare work along two dimensions.",
+    "source": "quadrantChart\n title Example priorities\n x-axis Low effort --> High effort\n y-axis Low impact --> High impact\n quadrant-1 Plan\n quadrant-2 Start\n quadrant-3 Defer\n quadrant-4 Reconsider\n Navigation: [0.25, 0.8]\n Rewrite: [0.8, 0.65]\n Cleanup: [0.2, 0.2]"
+  },
+  {
+    "id": "xychart",
+    "title": "XY chart",
+    "summary": "Compare values on labeled axes.",
+    "source": "xychart-beta\n title \"Example weekly builds\"\n x-axis [W1, W2, W3, W4]\n y-axis \"Builds\" 0 --> 50\n bar [12, 24, 32, 41]\n line [10, 20, 28, 35]"
+  },
+  {
+    "id": "requirement",
+    "title": "Requirement",
+    "summary": "Connect an implementation element to a requirement.",
+    "source": "requirementDiagram\n requirement readable {\n id: 1\n text: Preserve essential instructions\n risk: low\n verifymethod: test\n }\n element markdown {\n type: renderer\n }\n markdown - satisfies -> readable"
+  },
+  {
+    "id": "sankey",
+    "title": "Sankey",
+    "summary": "Show how quantities flow between groups.",
+    "source": "sankey-beta\n Sources,Guides,30\n Sources,Reference,20\n Guides,Readers,25\n Guides,Agents,5\n Reference,Readers,10\n Reference,Agents,10"
+  },
+  {
+    "id": "architecture",
+    "title": "Architecture",
+    "summary": "Connect services using built-in symbols.",
+    "source": "architecture-beta\n group docs(cloud)[Documentation]\n service app(server)[Site] in docs\n service store(database)[Content] in docs\n app:R -- L:store"
+  },
+  {
+    "id": "c4",
+    "title": "C4",
+    "summary": "Describe a system and its users at a high level.",
+    "source": "C4Context\n title Documentation context\n Person(reader, \"Reader\", \"Finds instructions\")\n System(docs, \"Documentation\", \"Published guides\")\n Rel(reader, docs, \"Reads\")"
+  },
+  {
+    "id": "block",
+    "title": "Block",
+    "summary": "Arrange connected blocks in explicit columns.",
+    "source": "block-beta\n columns 3\n a[\"Author\"] b[\"Build\"] c[\"Publish\"]\n a --> b\n b --> c"
+  },
+  {
+    "id": "agentflow",
+    "title": "Agentflow",
+    "summary": "Show agent tasks and decisions.",
+    "source": "agentflow-beta TB\n draft[\"Draft guide\"]@{ shape: task }\n check[\"Checks pass?\"]@{ shape: decision }\n publish[\"Publish guide\"]@{ shape: action }\n draft --> check\n check -- yes --> publish\n check -- no --> draft"
+  },
+  {
+    "id": "railroad",
+    "title": "Railroad",
+    "summary": "Describe a small grammar using EBNF.",
+    "source": "railroad-ebnf-beta\n name = \"guide\" | \"reference\" ;\n command = \"read\", name ;"
+  },
+  {
+    "id": "treeview",
+    "title": "Tree view",
+    "summary": "Display a directory hierarchy.",
+    "source": "treeView-beta\n \"docs\"\n  \"content\"\n   \"start.mdx\"\n   \"configuration.mdx\"\n  \"docs.config.yaml\""
+  },
+  {
+    "id": "cynefin",
+    "title": "Cynefin",
+    "summary": "Group decisions by their operating context.",
+    "source": "cynefin-beta\n title Documentation decisions\n complex\n  \"Test new navigation\"\n complicated\n  \"Review API coverage\"\n clear\n  \"Fix broken link\"\n chaotic\n  \"Restore unavailable site\""
+  },
+  {
+    "id": "wardley",
+    "title": "Wardley map",
+    "summary": "Relate a reader need to supporting capabilities.",
+    "source": "wardley-beta\n title Documentation capabilities\n anchor Reader [0.95, 0.80]\n component Guides [0.70, 0.55]\n component Hosting [0.30, 0.90]\n Reader -> Guides\n Guides -> Hosting"
+  },
+  {
+    "id": "eventmodeling",
+    "title": "Event modeling",
+    "summary": "Trace interface actions and resulting events.",
+    "source": "eventmodeling\n tf 01 ui Editor\n tf 02 cmd PublishPage\n tf 03 evt PagePublished"
+  },
+  {
+    "id": "usecase",
+    "title": "Use case",
+    "summary": "Connect an actor to a supported action.",
+    "source": "usecase-beta\n actor Reader\n Browse[Browse documentation]\n Search[Search documentation]\n Reader --> Browse\n Reader --> Search"
+  },
+  {
+    "id": "venn",
+    "title": "Venn",
+    "summary": "Show overlapping sets of requirements.",
+    "source": "venn-beta\n set A[\"Readable\"]\n set B[\"Searchable\"]\n union A,B[\"Useful docs\"]"
+  },
+  {
+    "id": "ishikawa",
+    "title": "Ishikawa",
+    "summary": "Organize possible causes of a problem.",
+    "source": "ishikawa-beta\n Slow documentation build\n Content\n  Large diagrams\n  Duplicate inputs\n Environment\n  Cold cache\n  Missing dependencies"
+  },
+  {
+    "id": "packet",
+    "title": "Packet",
+    "summary": "Describe a small binary record layout.",
+    "source": "packet-beta\n title Example record header\n 0-7: \"Version\"\n 8-15: \"Flags\"\n 16-31: \"Length\""
+  },
+  {
+    "id": "radar",
+    "title": "Radar",
+    "summary": "Compare several dimensions for two example approaches.",
+    "source": "radar-beta\n title Example review scores\n axis a[\"Clarity\"], b[\"Coverage\"], c[\"Speed\"]\n curve x[\"Approach A\"]{4, 3, 5}\n curve y[\"Approach B\"]{3, 5, 3}\n max 5"
+  },
+  {
+    "id": "swimlane",
+    "title": "Swimlane",
+    "summary": "Separate work by team.",
+    "source": "swimlane-beta LR\n subgraph Authors\n  draft[Draft guide]\n end\n subgraph Reviewers\n  review[Review guide]\n end\n draft --> review"
+  },
+  {
+    "id": "treemap",
+    "title": "Treemap",
+    "summary": "Compare the size of nested categories.",
+    "source": "treemap-beta\n \"Documentation\"\n  \"Guides\": 30\n  \"Reference\": 45\n  \"Tutorials\": 25"
+  },
+  {
+    "id": "info",
+    "title": "Renderer information",
+    "summary": "Display the renderer version as an informational diagram.",
+    "source": "info"
+  },
+  {
+    "id": "shapes-1",
+    "title": "Flowchart shapes 1",
+    "summary": "Compare rect, rounded, stadium, fr-rect, cyl, circle, dbl-circ, diam.",
+    "source": "flowchart TB\n n0@{ shape: rect, label: \"rect\" }\n n1@{ shape: rounded, label: \"rounded\" }\n n2@{ shape: stadium, label: \"stadium\" }\n n3@{ shape: fr-rect, label: \"fr-rect\" }\n n4@{ shape: cyl, label: \"cyl\" }\n n5@{ shape: circle, label: \"circle\" }\n n6@{ shape: dbl-circ, label: \"dbl-circ\" }\n n7@{ shape: diam, label: \"diam\" }\n n0 --> n1 --> n2 --> n3\n n4 --> n5 --> n6 --> n7"
+  },
+  {
+    "id": "shapes-2",
+    "title": "Flowchart shapes 2",
+    "summary": "Compare hex, odd, lean-r, lean-l, trap-b, trap-t, text, bow-rect.",
+    "source": "flowchart TB\n n0@{ shape: hex, label: \"hex\" }\n n1@{ shape: odd, label: \"odd\" }\n n2@{ shape: lean-r, label: \"lean-r\" }\n n3@{ shape: lean-l, label: \"lean-l\" }\n n4@{ shape: trap-b, label: \"trap-b\" }\n n5@{ shape: trap-t, label: \"trap-t\" }\n n6@{ shape: text, label: \"text\" }\n n7@{ shape: bow-rect, label: \"bow-rect\" }\n n0 --> n1 --> n2 --> n3\n n4 --> n5 --> n6 --> n7"
+  },
+  {
+    "id": "shapes-3",
+    "title": "Flowchart shapes 3",
+    "summary": "Compare sm-circ, f-circ, fr-circ, fork, notch-rect, lin-rect, div-rect, win-pane.",
+    "source": "flowchart TB\n n0@{ shape: sm-circ, label: \"sm-circ\" }\n n1@{ shape: f-circ, label: \"f-circ\" }\n n2@{ shape: fr-circ, label: \"fr-circ\" }\n n3@{ shape: fork, label: \"fork\" }\n n4@{ shape: notch-rect, label: \"notch-rect\" }\n n5@{ shape: lin-rect, label: \"lin-rect\" }\n n6@{ shape: div-rect, label: \"div-rect\" }\n n7@{ shape: win-pane, label: \"win-pane\" }\n n0 --> n1 --> n2 --> n3\n n4 --> n5 --> n6 --> n7"
+  },
+  {
+    "id": "shapes-4",
+    "title": "Flowchart shapes 4",
+    "summary": "Compare notch-pent, cross-circ, st-rect, datastore, lin-cyl, tag-rect, doc, tri.",
+    "source": "flowchart TB\n n0@{ shape: notch-pent, label: \"notch-pent\" }\n n1@{ shape: cross-circ, label: \"cross-circ\" }\n n2@{ shape: st-rect, label: \"st-rect\" }\n n3@{ shape: datastore, label: \"datastore\" }\n n4@{ shape: lin-cyl, label: \"lin-cyl\" }\n n5@{ shape: tag-rect, label: \"tag-rect\" }\n n6@{ shape: doc, label: \"doc\" }\n n7@{ shape: tri, label: \"tri\" }\n n0 --> n1 --> n2 --> n3\n n4 --> n5 --> n6 --> n7"
+  },
+  {
+    "id": "shapes-5",
+    "title": "Flowchart shapes 5",
+    "summary": "Compare flip-tri, sl-rect, hourglass, delay, h-cyl, curv-trap, docs, flag.",
+    "source": "flowchart TB\n n0@{ shape: flip-tri, label: \"flip-tri\" }\n n1@{ shape: sl-rect, label: \"sl-rect\" }\n n2@{ shape: hourglass, label: \"hourglass\" }\n n3@{ shape: delay, label: \"delay\" }\n n4@{ shape: h-cyl, label: \"h-cyl\" }\n n5@{ shape: curv-trap, label: \"curv-trap\" }\n n6@{ shape: docs, label: \"docs\" }\n n7@{ shape: flag, label: \"flag\" }\n n0 --> n1 --> n2 --> n3\n n4 --> n5 --> n6 --> n7"
+  },
+  {
+    "id": "shapes-6",
+    "title": "Flowchart shapes 6",
+    "summary": "Compare bolt, bang, cloud, brace, brace-r, braces, tag-doc, lin-doc.",
+    "source": "flowchart TB\n n0@{ shape: bolt, label: \"bolt\" }\n n1@{ shape: bang, label: \"bang\" }\n n2@{ shape: cloud, label: \"cloud\" }\n n3@{ shape: brace, label: \"brace\" }\n n4@{ shape: brace-r, label: \"brace-r\" }\n n5@{ shape: braces, label: \"braces\" }\n n6@{ shape: tag-doc, label: \"tag-doc\" }\n n7@{ shape: lin-doc, label: \"lin-doc\" }\n n0 --> n1 --> n2 --> n3\n n4 --> n5 --> n6 --> n7"
+  }
+]

package/examples/help-drawer/README.md

@@ -0,0 +1,44 @@
+# Use exported content in a help drawer
+
+This is a plain JavaScript consumer of Shoalrun's content export. It has no
+Shoalrun runtime dependency. The host app owns the buttons, drawer, and routing.
+
+Copy this directory into your application or documentation project first. With
+Shoalrun installed in that project, run from the copied example directory:
+
+```sh
+shoalrun export docs.config.yaml --target app-help --out public/help
+node preview.mjs
+```
+
+Open `http://127.0.0.1:8774/settings/account`. The included preview server mounts the export at `/help/`. To use another development server, serve `index.html` and `app.js` at your app root and mount `public/help` at
+`/help/`. Your development server should serve `index.html` for app routes such
+as `/settings/account`, without changing the `/help/` mount. Open the key and
+billing help buttons; follow the in-drawer links and inspect the images.
+The full account guide is omitted from the export and links to the configured
+example documentation host; replace that origin for your own project.
+
+`manifest.json` maps stable document IDs to representation files. `app.js`
+fetches the HTML, inserts it into one content container, and intercepts anchors
+marked `data-export-link`. The corresponding manifest link supplies the target
+document ID and original fragment. Other links use their ordinary destinations.
+
+`/help/` is an example path, not a required Shoalrun directory. You can choose
+another root-relative path, such as `/resources/`. Set `publicBase` to that path,
+serve the bundle there, and update the manifest URL in `app.js` to match (for
+example, `/resources/manifest.json`). The included preview server uses `/help/`;
+configure your own server when choosing a different mount. The `--out` directory
+is a filesystem destination and does not have to share the URL path's name.
+
+`publicBase` must match where the bundle is served. Fragment image URLs resolve
+against the app page, so they use this configured root-relative mount rather
+than the directory from which the fragment was fetched. The host app's CSS
+styles the static content; all substantive content is readable without it.
+
+This example inserts trusted output from its own documentation build. It does
+not accept arbitrary remote HTML. Mount a given exported document only once
+per DOM; repeated simultaneous instances require the host to rewrite IDs and
+all corresponding fragment and ARIA references.
+
+The component example imports the installed `@shoalrun/cli/components` authoring
+helpers at build time only. No module from Shoalrun is loaded by the browser.

package/examples/help-drawer/app.js

@@ -0,0 +1,53 @@
+// The application owns presentation and routing. Exported HTML comes from this
+// project's trusted build, not arbitrary user input or a third-party URL.
+const manifest = await fetch('/help/manifest.json').then(response => {
+  if (!response.ok) throw new Error('Build and mount the help export first.');
+  return response.json();
+}).then(manifest => {
+  if (manifest.kind !== 'shoalrun-content-export' || manifest.schemaVersion !== 1) throw new Error('Unsupported help export.');
+  if (manifest.review.status !== 'ok') throw new Error('Approve API content before using this export.');
+  return manifest;
+});
+const drawer = document.querySelector('#drawer');
+const content = document.querySelector('#content');
+let current;
+let request = 0;
+let opener;
+async function openHelp(id, fragment) {
+  const document = manifest.documents.find(document => document.id === id);
+  if (!document?.representations.html) throw new Error(`No HTML help for ${id}`);
+  const ticket = ++request;
+  const response = await fetch(manifest.publicBase + document.representations.html.path);
+  if (!response.ok) throw new Error(`Cannot load help for ${id}`);
+  const html = await response.text();
+  if (ticket !== request) return;
+  current = document;
+  content.innerHTML = html;
+  drawer.hidden = false;
+  let focusTarget = content.querySelector('h1');
+  if (fragment) {
+    const anchor = document.representations.html.anchors.find(anchor => anchor.id === fragment || anchor.exportedId === fragment);
+    if (anchor) focusTarget = content.querySelector(`#${CSS.escape(anchor.exportedId)}`) ?? focusTarget;
+  } else drawer.scrollTop = 0;
+  if (focusTarget) {
+    focusTarget.tabIndex = -1;
+    focusTarget.focus({ preventScroll: true });
+    if (fragment) focusTarget.scrollIntoView();
+  }
+}
+document.querySelectorAll('[data-help]').forEach(button => button.addEventListener('click', () => {
+  opener = button;
+  openHelp(button.dataset.help).catch(showError);
+}));
+content.addEventListener('click', event => {
+  const anchor = event.target.closest('a[data-export-link]');
+  if (!anchor) return;
+  const link = current?.representations.html.links.find(link => link.key === anchor.dataset.exportLink);
+  if (link?.kind !== 'document') return; // Canonical fallbacks open as ordinary links.
+  event.preventDefault();
+  openHelp(link.documentId, link.fragment).catch(showError);
+});
+function closeHelp() { request++; drawer.hidden = true; opener?.focus(); }
+document.querySelector('#close').addEventListener('click', closeHelp);
+drawer.addEventListener('keydown', event => { if (event.key === 'Escape') { event.preventDefault(); closeHelp(); } });
+function showError(error) { content.textContent = error.message; drawer.hidden = false; document.querySelector('#close').focus(); }

package/examples/help-drawer/components/components.json

@@ -0,0 +1 @@
+{"apiVersion":1,"components":{"SupportNote":{"module":"./support.mjs"}}}

package/examples/help-drawer/components/support.mjs

@@ -0,0 +1,10 @@
+import { defineComponent, content } from '@shoalrun/cli/components';
+export default defineComponent({
+  children: 'none',
+  content() {
+    return {
+      content: content.paragraph('Contact the workspace owner if you need additional permissions.'),
+      data: { presentationOnly: 'This browser data must never enter the export.' }
+    };
+  }
+});

package/examples/help-drawer/content/account.md

@@ -0,0 +1,8 @@
+---
+id: guide.account
+title: Account guide
+summary: General account guidance stays on the documentation website.
+slug: /account
+---
+
+Ask the workspace owner before changing account settings.

package/examples/help-drawer/content/billing.mdx

@@ -0,0 +1,29 @@
+---
+id: guide.billing
+title: Billing
+summary: Check usage before changing a plan.
+slug: /billing
+---
+
+## Review usage
+
+[API key help](doc:guide.keys) explains the credentials associated with requests.
+
+<Walkthrough title="Check usage">
+<Step title="Read the total">
+Read the current usage total.
+
+```js
+const usage = 12;
+```
+
+</Step>
+<Step title="Compare the allowance">
+Compare that total with your plan's allowance.
+
+```js
+const remaining = 100 - usage;
+```
+
+</Step>
+</Walkthrough>

package/examples/help-drawer/content/keys.mdx

@@ -0,0 +1,46 @@
+---
+id: guide.keys
+title: API keys
+summary: Create a key and choose its permissions.
+slug: /api-keys
+---
+
+Create a key for each integration. [Billing help](doc:guide.billing) explains usage costs.
+
+## Choose permissions
+
+<ReaderSection audience="developer">
+
+Use a separate key for each application.
+
+</ReaderSection>
+
+<ReaderSection audience="operator">
+
+Review unused keys before your scheduled access audit.
+
+</ReaderSection>
+
+![Key settings](./settings.svg)
+
+<Tabs label="Environment">
+<Tab label="Development">
+Use a key limited to your test workspace.
+</Tab>
+<Tab label="Production">
+Store the key in your deployment's secret store.
+</Tab>
+</Tabs>
+
+<Diagram title="Key setup" summary="Create the key, then send a request." engine="mermaid">
+
+```mermaid
+flowchart LR
+  Create --> Request
+```
+
+</Diagram>
+
+<SupportNote />
+
+[Full account guide](doc:guide.account)

package/examples/help-drawer/content/settings.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="240" height="80" viewBox="0 0 240 80"><rect width="240" height="80" fill="#e8f0ed"/><text x="16" y="44" fill="#193a2d" font-size="18">Key permissions</text></svg>

package/examples/help-drawer/docs.config.yaml

@@ -0,0 +1,30 @@
+schemaVersion: 1
+site:
+  title: Acme documentation
+  origin: https://docs.example.com
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+components:
+  - ./components/components.json
+readerFilters:
+  facets:
+    audience:
+      label: Audience
+      options: { developer: Developers, operator: Operators }
+exports:
+  app-help:
+    formats: [markdown, html]
+    documents: [guide.keys, guide.billing]
+    publicBase: /help/

package/examples/help-drawer/index.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<title>Acme workspace · Help drawer example</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+*{box-sizing:border-box}body{font:15px/1.6 system-ui,sans-serif;margin:0;color:#18382d;background:#f3f6f3}header{display:flex;align-items:center;justify-content:space-between;padding:1rem 2rem;border-bottom:1px solid #dbe4dc;background:#fff}header strong{font-size:1.1rem}header span,.muted{color:#61776b}.workspace{max-width:1060px;margin:3rem auto;padding:0 2rem;display:grid;grid-template-columns:180px 1fr;gap:3rem}nav p{font-size:.8rem;text-transform:uppercase;letter-spacing:.12em;color:#61776b}nav a{display:block;padding:.6rem .8rem;border-radius:.4rem;color:inherit;text-decoration:none}nav a[aria-current]{background:#dfece3;font-weight:600}.eyebrow{font-size:.8rem;text-transform:uppercase;letter-spacing:.12em;color:#61776b}h1{font-size:2rem;line-height:1.2;margin:.5rem 0}h2{font-size:1.15rem;margin:0}button{font:inherit;cursor:pointer;border:1px solid #bed0c3;background:#fff;color:#23583e;padding:.45rem .8rem;border-radius:.4rem}button:hover{background:#eaf2ed}button:focus-visible,a:focus-visible{outline:3px solid #94b79f;outline-offset:2px}.card{background:white;border:1px solid #dbe4dc;border-radius:.75rem;margin-top:1.5rem;padding:1.5rem}.card-head{display:flex;justify-content:space-between;align-items:center;gap:1rem}.key{font-family:monospace;padding:.75rem;background:#f3f6f3;border-radius:.4rem;margin:1rem 0}.row{display:flex;justify-content:space-between;padding:.65rem 0;border-top:1px solid #eef2ee}.pill{background:#e8f2e9;border-radius:1rem;padding:.1rem .6rem;font-size:.8rem}.note{margin-top:2rem;font-size:.85rem;color:#61776b}aside{position:fixed;inset:0 0 0 auto;width:min(36rem,94vw);overflow:auto;padding:1.5rem 2rem;background:#fff;box-shadow:-1rem 0 4rem #15382422;border-left:1px solid #dbe4dc;z-index:2}aside[hidden]{display:none}.drawer-head{display:flex;align-items:center;justify-content:space-between;border-bottom:1px solid #dbe4dc;padding-bottom:1rem;margin-bottom:1.5rem}.drawer-head span{font-size:.8rem;letter-spacing:.12em;text-transform:uppercase;color:#61776b}#content img{max-width:100%;height:auto}#content pre{overflow:auto;background:#f1f5f2;padding:1rem;border-radius:.4rem}#content h1{font-size:1.7rem}#content h2{font-size:1.15rem;margin-top:1.8rem}#content h3{font-size:1rem;margin-top:1.3rem}#content a{color:#286448}#content blockquote{border-left:3px solid #94b79f;margin-left:0;padding-left:1rem}@media(max-width:700px){.workspace{grid-template-columns:1fr;margin:1.5rem auto;gap:1rem}nav{display:none}header{padding:1rem}.card-head{align-items:flex-start}}
+</style>
+<header><strong>Acme <span>workspace</span></strong><span>Example application</span></header>
+<div class="workspace">
+<nav aria-label="Settings"><p>Settings</p><a href="/settings/account" aria-current="page">Account</a><a href="/settings/keys">API keys</a><a href="/settings/billing">Billing</a></nav>
+<main>
+<div class="eyebrow">Workspace settings</div>
+<h1>Your account</h1>
+<p class="muted">Manage the credentials and plan for your workspace.</p>
+<section class="card"><div class="card-head"><h2>API keys</h2><button data-help="guide.keys">Help with API keys</button></div><p class="muted">One key for each integration, with permissions you control.</p><div class="key">acme_test_••••••••••••••••</div><div class="row"><span>Development workspace</span><span class="pill">Active</span></div></section>
+<section class="card"><div class="card-head"><h2>Billing</h2><button data-help="guide.billing">Help with billing</button></div><div class="row"><span>Current plan</span><strong>Team</strong></div><div class="row"><span>Requests this month</span><span>12 / 100</span></div></section>
+<p class="note">The help drawer consumes a portable content export. Your app owns its layout and navigation; the content is authored in the same source as the documentation.</p>
+</main>
+</div>
+<aside id="drawer" aria-label="Help" hidden>
+<div class="drawer-head"><span>Workspace help</span><button id="close">Close help</button></div>
+<div id="content" aria-live="polite"></div>
+</aside>
+<script type="module" src="/app.js"></script>
+</html>

package/examples/help-drawer/preview.mjs

@@ -0,0 +1,33 @@
+import { createServer } from 'node:http';
+import { readFile, realpath } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+const root = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+let port = 8774;
+let directory = path.join(root, 'public/help');
+for (let index = 0; index < args.length; index++) {
+  if (args[index] === '--help') { console.log('Usage: node preview.mjs [--port PORT] [--help-directory DIRECTORY]'); process.exit(0); }
+  if (args[index] === '--port') port = Number(args[++index]);
+  else if (args[index] === '--help-directory') directory = path.resolve(args[++index]);
+  else throw new Error('Unknown preview option');
+}
+if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Invalid port');
+const help = await realpath(directory);
+const server = createServer(async (request, response) => {
+  if (request.method !== 'GET') { response.writeHead(405); response.end(); return; }
+  try {
+    const pathname = decodeURIComponent(new URL(request.url, 'http://localhost').pathname);
+    let file;
+    if (pathname.startsWith('/help/')) {
+      file = await realpath(path.join(help, pathname.slice(6)));
+      if (!file.startsWith(help + path.sep)) throw new Error('Invalid path');
+    } else file = path.join(root, pathname === '/app.js' ? 'app.js' : 'index.html');
+    const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.md': 'text/markdown; charset=utf-8', '.png': 'image/png' };
+    response.writeHead(200, { 'Content-Type': types[path.extname(file)] ?? 'application/octet-stream' });
+    response.end(await readFile(file));
+  } catch { response.writeHead(404); response.end('Not found'); }
+});
+server.listen(port, '127.0.0.1', () => console.log(`Help drawer demo: http://127.0.0.1:${server.address().port}/settings/account`));
+process.on('SIGINT', () => server.close(() => process.exit(0)));
+process.on('SIGTERM', () => server.close(() => process.exit(0)));

package/examples/mcp-analytics/README.md

@@ -0,0 +1,59 @@
+# MCP analytics adapter
+
+This server-only example uses PostHog's native MCP analytics SDK. It emits
+`$mcp_tool_call`, rather than renaming a browser event. Other services can use
+the same `capture(event)` and optional `flush()` exports.
+
+1. Copy `posthog.mjs` into a dedicated `mcp-analytics/` directory in your project.
+2. Install the example's tested dependencies in that project:
+   `npm install --save-exact @posthog/mcp@0.22.3 posthog-node@5.56.2`.
+   This SDK requires Node.js 22.22+ on the Node 22 release line.
+3. Add `analytics: { module: ./mcp-analytics/posthog.mjs }` inside your enabled
+   `mcp` configuration. Add `clientMetadata: true` alongside `module` if you want
+   normalized client/model labels when available. This separate option defaults
+   to `false`. Set `intent: true` and `conversationIds: true` separately to use
+   the SDK instrumentation hook. Both also default off. The top-level browser `analytics` setting is separate.
+4. Set `POSTHOG_PROJECT_TOKEN` and optionally `POSTHOG_HOST` on the serving
+   process or Vercel function. The example does nothing without a token.
+5. Build, connect an MCP client, and call a documentation tool. Look for
+   `$mcp_tool_call` in PostHog's activity feed and MCP analytics views.
+
+Shoalrun packages the module and its dependencies without importing it at build
+time. Keep local imports within the module's directory. Use static imports
+and read credentials from runtime environment variables. Don't put credentials
+or private data in module files: the build copies those files.
+
+The event contains the tool, duration, error flag, build ID, publication,
+and the page/section IDs for successful reads. It excludes arguments, search
+text, result content, raw request headers, IP addresses, and user identity.
+With client metadata enabled, the PostHog example also maps the normalized
+client name/version and supported model label to native MCP properties. Both
+are unverified claims; unknown or unsafe labels are omitted. The adapter adds no person identity. Basic capture leaves tool schemas and
+responses unchanged. Enabling
+intent/grouping uses the native SDK: it adds context, conversation, and (when
+client metadata is enabled) model arguments. Session tokens or echoed
+conversation handles group calls without a shared server session store. It does not count direct Markdown fetches, browser views, or transport errors.
+Basic capture includes error categories but excludes schema-validation failures before the tool handler. Native instrumentation can record rejected tool calls; it currently retains the error flag without an error category.
+
+Shoalrun attempts delivery and flushes before completing each HTTP response,
+with a one-second bound on each adapter operation. Failures log a generic
+warning and don't change the MCP result. Delivery is best effort. Use bounded
+provider timeouts; a timed-out promise isn't cancelled automatically. Removing
+`mcp.analytics` or setting it to `false` disables collection after rebuilding
+and restarting the host. Stdio is not instrumented by this setting.
+
+Intent capture asks for exactly one fixed category: discovery, setup,
+troubleshooting, configuration, reference_lookup, comparison, migration, or other.
+Only these categories can leave the adapter. Empty or invalid context, including
+free text with names or secrets, is replaced with a per-tool fallback marked
+inferred. It does not infer the user's real goal or run a model. Harness names
+are normalized; model names must match the framework's fixed registry. Unknown
+or custom deployment labels are omitted. All client labels remain unverified.
+The adapter disables exception autocapture, GeoIP enrichment, and person profiles.
+Session handles remain pseudonymous identifiers when grouping is enabled; this
+is not a guarantee of anonymous data. Check PostHog's project-level Discard client
+IP data setting too. Infrastructure access logs are outside this adapter.
+An outbound property allowlist excludes raw arguments, results, headers, and
+exception details in SDK mode. SDK mode uses the low-level server with original
+argument names so analytics fields can be removed before strict validation.
+Reconnect clients after changing these options to refresh their tool listing.