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

package/examples/mcp-analytics/posthog.mjs

@@ -0,0 +1,159 @@
+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;
+}

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.11",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    "./authoring": "./dist/authoring-api.js",
+    "./*": "./*",
+    "./components": "./dist/components.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "assets",
+    "styles",
+    "templates",
+    "examples",
+    "!examples/help-drawer/public/**",
+    "!examples/**/node_modules/**",
+    "example-configs",
+    "!example-configs/**/.shoalrun/**",
+    "agent-docs",
+    "skills",
+    "README.md",
+    "AUTHORING.md",
+    "schemas/content-export.schema.json",
+    "CHANGELOG.md",
+    "!**/*.local.md",
+    "!**/*.override.md",
+    "!**/.env*",
+    "!**/.git/**",
+    "!**/.vercel/**",
+    "!**/node_modules/**",
+    "!**/.shoalrun/**"
+  ],
+  "bin": {
+    "shoalrun": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test --test-concurrency=4 dist/*.test.js scripts/*.test.mjs && npm run skills:check",
+    "test:authoring-tools": "npm run build && node --test dist/authoring-guidance.test.js dist/authoring-project.test.js dist/authoring-validation.test.js dist/authoring-review.test.js dist/docs-author.test.js dist/documentation-core.test.js dist/docs-mcp.test.js dist/scaffold-templates.test.js",
+    "demo": "npm run build && node dist/cli.js build example/docs.config.yaml example/dist",
+    "api-preview": "npm run build && node scripts/preview-api.mjs",
+    "deploy:check": "node scripts/check-deployment.mjs",
+    "preview": "npm run demo && node preview.mjs",
+    "agent-docs:import": "node scripts/import-docs-snapshot.mjs",
+    "skills:check": "node scripts/check-skills.mjs skills"
+  },
+  "dependencies": {
+    "@d2lang/d2": "^0.1.34",
+    "@modelcontextprotocol/server": "2.3.0",
+    "@resvg/resvg-js": "2.6.2",
+    "esbuild": "0.28.2",
+    "js-tiktoken": "1.0.21",
+    "katex": "0.18.2",
+    "lucide": "1.47.0",
+    "parse5": "8.0.1",
+    "pele": "1.6.0",
+    "rehype-stringify": "10.0.1",
+    "remark-gfm": "4.0.1",
+    "remark-mdx": "3.1.1",
+    "remark-parse": "11.0.0",
+    "remark-rehype": "11.1.2",
+    "remark-stringify": "11.0.0",
+    "shiki": "4.4.3",
+    "unified": "11.0.5",
+    "yaml": "2.9.1",
+    "zod": "4.6.6"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.3.0",
+    "@types/node": "22.19.19",
+    "afdocs": "0.20.0",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "axe-core": "^4.13.0",
+    "puppeteer": "^25.12.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "5.9.3"
+  },
+  "description": "Documentation compiler and CLI with HTML, Markdown, and read-only MCP tools.",
+  "homepage": "https://www.shoalrun.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shoalrun/shoalrun.git",
+    "directory": "framework"
+  },
+  "bugs": {
+    "url": "https://github.com/shoalrun/shoalrun/issues"
+  }
+}

package/schemas/content-export.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://shoalrun.com/schemas/content-export.schema.json",
+  "title": "Shoalrun portable content export, version 1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "digest", "publicBase", "publication", "review", "documents", "assets", "files", "diagnostics"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "shoalrun-content-export" },
+    "digest": { "$ref": "#/$defs/digest" },
+    "publicBase": { "type": "string", "pattern": "^/(?:(?!\\.{1,2}/)[A-Za-z0-9_~.-]+/)*$" },
+    "publication": { "$ref": "#/$defs/publication" },
+    "review": {
+      "type": "object", "additionalProperties": false, "required": ["status", "apis"],
+      "properties": {
+        "status": { "enum": ["ok", "required"] },
+        "apis": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["apiId", "digest"], "properties": { "apiId": { "type": "string" }, "digest": { "$ref": "#/$defs/digest" } } } }
+      }
+    },
+    "documents": {
+      "type": "array", "minItems": 1,
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["id", "publication", "title", "summary", "type", "representations", "assets", "externalDependencies"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 }, "publication": { "$ref": "#/$defs/publication" },
+          "title": { "type": "string" }, "summary": { "type": "string" }, "type": { "type": "string" },
+          "canonicalUrl": { "type": "string", "format": "uri" },
+          "representations": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "html": { "$ref": "#/$defs/representation" }, "markdown": { "$ref": "#/$defs/representation" } } },
+          "assets": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/path" } },
+          "externalDependencies": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["url", "kind"], "properties": { "url": { "type": "string", "format": "uri" }, "kind": { "const": "image" } } } }
+        }
+      }
+    },
+    "assets": { "type": "array", "items": { "$ref": "#/$defs/asset" } },
+    "files": { "type": "array", "items": { "$ref": "#/$defs/file" } },
+    "diagnostics": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["code", "documentId", "message"], "properties": { "code": { "type": "string" }, "documentId": { "type": "string" }, "message": { "type": "string" } } } }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "path": { "type": "string", "pattern": "^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))[A-Za-z0-9_.-]+(?:/(?!\\.{1,2}(?:/|$))[A-Za-z0-9_.-]+)*)$" },
+    "publication": { "type": "object", "additionalProperties": false, "required": ["channel", "version", "language"], "properties": { "channel": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 }, "language": { "type": "string", "minLength": 1 } } },
+    "file": { "type": "object", "required": ["path", "bytes", "digest"], "properties": { "path": { "$ref": "#/$defs/path" }, "bytes": { "type": "integer", "minimum": 0 }, "digest": { "$ref": "#/$defs/digest" } } },
+    "asset": { "allOf": [{ "$ref": "#/$defs/file" }], "type": "object", "required": ["mediaType"], "properties": { "mediaType": { "type": "string" } } },
+    "representation": {
+      "allOf": [{ "$ref": "#/$defs/asset" }],
+      "type": "object", "required": ["anchors", "links"],
+      "properties": {
+        "anchors": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "exportedId"], "properties": { "id": { "type": "string" }, "exportedId": { "type": "string" }, "title": { "type": "string" } } } },
+        "links": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["key", "kind", "href"], "properties": { "key": { "type": "string" }, "kind": { "enum": ["document", "canonical", "external", "asset"] }, "href": { "type": "string" }, "documentId": { "type": "string" }, "fragment": { "type": "string" }, "query": { "type": "string" }, "asset": { "$ref": "#/$defs/path" } } } }
+      }
+    }
+  }
+}

package/skills/shoalrun-author/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: shoalrun-author
+description: Write or revise documentation in an existing Shoalrun project using the agent's own model, native file edits, and provider-free project, validation, and preview tools. Use for pages and their required navigation, relationships, API links, snippets, or project checks.
+---
+
+# Author Shoalrun documentation
+
+Use normal working-tree file tools. Shoalrun supplies project discovery, canonical references, isolated validation and snapshot previews; your harness supplies planning, evidence gathering, writing and permissions. No additional authoring model key or replacement-file JSON is required. Preserve unrelated local edits and never hand-edit generated output.
+
+## Discover the task and its policy
+
+Find the project's `docs.config.yaml`. Start with `shoalrun docs project --section guidance --config <config>` and read applicable project/ancestor `AGENTS.md`, directives, writing guides and reviewed examples. Use `docs source <project-relative-file>` or native file reads. Inspect `--section findings` when discovery reports findings. Follow response cursors and verify source digests across paginated reads.
+
+Discover relevant pages without requiring the author to choose one: `docs project --query "<topic>"`. Inspect configuration ownership, navigation, relationships and templates as needed. Project policy determines required companions; neither a page-only request nor a passing compiler check waives them. Resolve contradictory policy or missing facts with a precise author question while continuing independent work.
+
+When `frontmatter.taxonomy` is configured, read its central area/subarea definitions and enforcement options before classifying pages. Use declared IDs and parent pairs, respect `required` and `requireExplicit`, and use arrays only for fields enabled in `multiple`. Update the vocabulary when the task requires a new category; preserve the project's enforcement settings. Read `guide.page-taxonomy` for the configuration contract.
+
+Use `docs search "<topic>"` and `docs read <id>` to query the installed package’s bundled documentation. If a local `shoalrun docs mcp` connection is available, its read-only documentation tools access the same snapshot; use either interface. A configured remote MCP may serve different documentation. Skills provide workflow instructions separately from these reference lookups.
+
+When reading a published site through Markdown, follow topic-index links when present; `llms.min.txt` need not list every page directly. Choose a relevant topic rather than downloading every index. Preserve publication and base-path scope, and follow the full-page fallback when a standalone section does not cover the task.
+
+Read `reference.authoring-workspace` for tool contracts and `guide.authoring-workspace` for the working-tree procedure. Before unfamiliar syntax, check the relevant component attributes, configuration structure, or asset-handling contract instead of assuming another tool’s conventions. For MDX components, read their canonical reference; `<Step>` belongs inside `<Steps>` for an ordinary titled procedure, while your harness's task plan is separate. Read implementation/specification evidence with your harness's permitted tools; record the sources for changed claims. Bundled guidance does not establish a consumer project's facts.
+
+## Record scope and edit
+
+Before editing, capture the current state with `docs baseline --out <new-baseline> --config <config>`. Put baselines inside the project's excluded `.shoalrun` directory or outside the project. This includes earlier dirty/untracked files rather than comparing with Git HEAD. Retain the corresponding before-content/task diff with your harness; a baseline stores digests, not earlier text. For an existing rendering failure, reproduce its located finding before repairing it.
+
+Edit ordinary source files and required companions. Choose a page type and reviewed example for the reader's goal. Preserve stable IDs, routes, original `date` and access policy; set `updated` to the actual edit date. For a new page, use `shoalrun scaffold <template> -n <target> --config <config>` and resolve its prompts. Keep it draft until reviewed; snapshot validation renders affected drafts without changing their publication metadata. API materialization and recipe tasks have focused references/skills when needed.
+
+For release notes, lead with the reader-visible change and why it matters. Explain the previous and new behavior with a concrete example when useful, then state any upgrade action. Introduce unfamiliar terms before using them. Put implementation details and test counts after the explanation; they do not substitute for it. Distinguish measured improvements from expected benefits, and package publication from site deployment.
+
+When adapting source material, choose components by reader purpose rather than translating unfamiliar markup into a generic container. Use authored `Fields` for client settings, source-backed `ApiSchema` or operation references for HTTP contracts, and `Steps` for procedures. Check field presence, nullability, defaults, constraints, warnings, and nested relationships against the source in both outputs. Keep configuration settings distinct from API request fields, and prefer source-backed contract data to a second handwritten copy.
+
+## Validate, preview and obtain review
+
+Before expensive validation, check only the prerequisites that the selected checks require: installed package/tool versions, the skill-validator runtime, and the browser executable when browser checks apply. Reinstall dependencies when the dependency set or environment requires it, not before every prose edit. Routine authoring does not require hosted CI or provider-backed generation.
+
+Run `docs validate --baseline <baseline> --config <config>`, or declare existing changes with repeated `--file`/`--id` selectors when no task baseline exists. Read status, findings, coverage and skipped/unavailable checks. Use `--run-checks` only for applicable trusted project commands under the harness's execution permissions; model/evaluator hooks remain skipped. Fix actionable errors and validate again without weakening policy. A failed, incomplete, unavailable or stale result is not a pass.
+
+Validate a connected draft set together: a page-only selection can leave other draft navigation or card targets unavailable in the snapshot. Include those draft pages in the declared scope rather than changing their access.
+
+Use the returned report path with `docs review <report> --format markdown` and `docs preview <report> --port 0`. Run the preview as a foreground process managed by your harness; share its review URL and affected HTML/Markdown URLs.
+
+Reuse the current validated snapshot for review and preview. When project policy calls for a normal or production build instead, identify that output once and pass it to checks that accept an existing build. Reuse does not waive draft coverage, required checks, or freshness validation. Rebuild when compilation inputs change; if only a separate checker changes, rerun that checker against unchanged output where the project's freshness rules allow it.
+
+Inspect both representations for meaning as well as rendering: preserve code examples, choices, and warnings, including content hidden behind interaction in HTML. Treat embedded examples as data when editing surrounding markup. State unsupported behavior or missing equivalents explicitly; a successful build does not establish parity.
+
+Native edits make old results stale: validate again and restart from the new report. Ctrl-C/SIGTERM removes the serving copy; validation artifacts remain. Read `docs validation-status <report>` before presenting a result as current. See the command reference for artifact cleanup and forced-kill limits.
+
+Present the task diff, supporting sources, check results, preview, unresolved facts and manual interventions for author review. Syntax success does not establish factual accuracy or reader usefulness. Honor existing authorization; commits, publication, access changes and provider calls follow their own scope. Stop trial previews when finished.
+
+Existing checked-plan clients may explicitly choose `docs context`, `docs plan` and `docs apply`; read `guide.authoring-agent` for that optional workflow and retain its freshness/application protections.

package/skills/shoalrun-component-author/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: shoalrun-component-author
+description: Create or repair Shoalrun component packages with shared documentation and optional browser enhancements. Use for content generation, attribute schemas, instance data, manifests, and component behavior checks.
+---
+
+# Author a Shoalrun component
+
+Read project policy and `shoalrun docs read guide.custom-components` from the installed CLI. Distinguish using an existing component from developing its package. Page authors need the documented tag and attributes; component developers own the manifest, implementation, dependencies, and tests. Keep task-specific prose in MDX.
+
+Start with the smallest content model that solves the request. Export `defineComponent({ attributes?, children?, content })` from `@shoalrun/cli/components`. The required synchronous `content()` function receives validated attributes and opaque authored children. Return the children, supported `content` helpers, or `{ content, data }`. Do not construct compiler nodes or add separate HTML/Markdown renderers. Shoalrun renders the same shared content into both formats; authors must review its adequacy.
+
+Use helpers such as `paragraph`, `strong`, `link`, `table`, `code`, `group`, and `component`. Attribute schemas support string, boolean, and numeric literals with defaults and constraints. Quoted `"false"` overrides a boolean default. Children default to none, or can be optional/required. Inspect the installed API declarations for exact types.
+
+A static JSON manifest declares `apiVersion: 1` and `components: { Name: { module, browser?, styles? } }`. Paths are relative to that manifest. Consumers register its local path or installed package export once in `components`. The framework compiles normal source imports, TypeScript, and browser JSX and tracks dependencies. Declare the package's own dependencies; do not ask consumers to wire internal assets or run a separate component bundler. Imported JSON supplies local build data. Styles are self-contained CSS. No remote plugins, arbitrary MDX imports, or build-time fetching are supported.
+
+For browser behavior, return a JSON instance model together with the shared content. Export `enhance({ root, controls, content, data })` from the browser module, mount optional controls, and reveal them after mounting. Keep shared content intact. Read the model from `data`; never scrape table labels or other presentation markup. Import shared calculations/validation into both build and browser code. Component packages may use React; React is not a framework runtime dependency.
+
+When adapting an existing component, preserve its defaults, bounds, ordering, and boundary behavior in the shared model. Identify dependencies supplied implicitly by its original host, such as hook imports or utility CSS, and replace or declare them in the package. Scope controls and state per instance; check service failures such as denied clipboard access when that behavior is present.
+
+Inventory essential explanations, choices, warnings, code, links, and meaningful order. A calculator needs its rules, supported inputs, default worked result, and qualifications, rather than every possible numeric state. Test the component's own valid/invalid inputs, nested content when supported, calculations, complete shared output, keyboard behavior, and browser/no-JavaScript fallback. Framework registration, compiler, dependency-graph, and atomic-output conformance belong to Shoalrun's tests; do not reproduce that entire suite in each component project.
+
+Configured modules are trusted code, including during isolated authoring validation. Browser modules have page-origin permissions. They are not sandboxed.
+
+Provide a manifest, editable source, focused fixtures, a short usage example, and validation evidence. Use `shoalrun docs validate --config <config> --file <fixture>`, with the fixture path relative to the config's project directory, then `docs review <report> --format markdown` and `docs preview <report> --port 0`. Read status, coverage, findings and skipped checks. Review the same snapshot's HTML and Markdown for meaning. Share a local preview for author review; source edits make prior evidence stale. Publication follows the task's authorization.

package/skills/shoalrun-recipes/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: shoalrun-recipes
+description: Write or revise task-oriented how-tos, reusable ingredients, recipe compositions, and cookbook choices in a Shoalrun documentation project. Use for complete task workflows and their reuse or discovery; use ordinary authoring for explanations and reference pages.
+---
+
+# Write Shoalrun recipes
+
+Start with the reader's goal and an observable success condition. Use `how-to` for a task page, or `recipe` when it participates in recipe composition or cookbook choices. Both need practical actions and an observable result. Preserve the user's requested format and established page IDs and routes. Use `explanation` for conceptual discussion and `reference` for exact facts; an existing how-to does not need an automatic type migration.
+
+The CLI includes overrideable `recipe`, `ingredient`, and `cookbook` templates; scaffold with `shoalrun scaffold <template> -n <target>` without project registration.
+
+Read `shoalrun docs read guide.recipes-overview`, then `guide.recipe-drafts` for composition or `guide.cookbooks` for choices. In a source checkout, use `node framework/dist/cli.js` in place of `shoalrun` after compiling the framework. Inspect the target project's config, neighboring pages, and existing ingredients before writing.
+
+Choose only the layers the task needs:
+
+- **Recipe:** write a complete page with prerequisites, ordered actions, explicit value handoffs, failure guidance, and a final success check. A recipe can be authored directly; ingredients are optional.
+- **Ingredient:** extract instructions actually shared by recipes. Put reusable prose and commands in the MDX body. Declare `workflow.inputs` and `workflow.outputs` as name-to-description mappings, shared setup in `workflow.prerequisites`, and an observable `workflow.check`. These names describe dependencies; they do not create variables or execute code.
+- **Composition:** list ingredient paths in recipe-spec order, relative to the spec file. Supply initial `inputs` and the final `outcome`. Run `recipe draft --spec <spec> --out <new-candidate> --config <config> --check`, then create and review the draft. Resolve missing inputs and duplicate output names; verify actual handoffs by following the task. The command copies source text and checks declared names, without calling a model or running the task.
+- **Cookbook:** point options at complete published recipe IDs. Explain `when`, `needs`, and `outcome`. Use `mode: single` for alternatives or overlapping recipes. Use multiple selection only for compatible complete recipes; it does not deduplicate setup or connect their outputs. Add an authored introduction and `<CookbookChooser id="..." />`.
+
+When creating or editing a recipe, ingredient, or cookbook page, set frontmatter `updated` to the current date in `YYYY-MM-DD` format. Preserve an existing `date`.
+
+Find the source of an existing recipe before editing it. Generated recipes are snapshots. In Shoalrun's own repository, edit `docs/recipe-specs/` and ingredient sources, then use `node framework/scripts/build-shoalrun-recipes.mjs --write` and review the diff. That script replaces recipe bodies. Other projects may maintain their reviewed drafts independently.
+
+Build the target site and inspect HTML and Markdown. Run applicable audits and test commands in an appropriate local fixture within the user's authorized scope. Distinguish checks actually run from manual or external steps still unverified. A public recipe must have complete instructions and resolved draft prompts. Cookbook Markdown lists choices; give a task-performing agent the recipe Markdown or a downloaded selection. Refresh generated agent docs when working on this repository.

package/skills/shoalrun-setup/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: shoalrun-setup
+description: Start a Shoalrun documentation project from a working example, configure its first pages or API source, and verify HTML and Markdown output. Use for new Shoalrun sites or a first migration, not routine page edits.
+---
+
+# Set up Shoalrun docs
+
+First inspect the target repository for an existing `docs.config.yaml`, content, OpenAPI files, and build scripts. Preserve an existing project rather than copying a starter over it. Ask for missing publication choices only when they affect the first build, such as the intended API version or whether pages are ready to be public.
+
+When adapting existing documentation, start with a connected, representative set of pages. Identify each page's reader goal and choose native structures accordingly: `Fields` for authored configuration or parameter lists, source-backed schemas and references for OpenAPI contracts, `Steps` for titled procedures, and document cards for reading paths. Read the matching bundled component references before writing syntax. Preserve IDs, routes, examples, defaults, bounds, and the distinction between an optional value and a nullable one. A successful build does not establish that these meanings survived.
+
+Use `shoalrun init <directory> --starter minimal` for a small site or `--starter api-docs` for a parcel API site with guides, generated references, and focused contracts. Use `--starter showcase` for a fuller Cedar Parcel handbook with component examples, diagrams, reader views, a landing page, local-workflow cookbook, and generated API references. All three starters build without provider credentials. The command copies a bundled example without overwriting existing files. From the source checkout, use `node framework/dist/cli.js init <directory> --starter <name>` from the repository root. Replace fixture names, prose, API files, navigation, and example domains. Keep `docs.config.yaml` as the entry point. Consult the Shoalrun config reference for unfamiliar keys; do not invent config fields or assume that a package has been published to npm.
+
+Run scaffolding from the project directory or use an absolute target path. Passing `--config` does not rebase `scaffold -n` against that config's directory. Resolve scaffold placeholders and remove unused optional sections while retaining the page's intended identity and draft access.
+
+For a specific setting or workflow, run `shoalrun docs search "<topic>"`, then `shoalrun docs read <document-id>` to load the matching generated Markdown. Use these bundled docs before guessing at a command or config key.
+
+Use the installed `shoalrun` command when available. From the source checkout, install dependencies in `framework/` with `npm ci` when missing or changed, compile with `npm run build`, then use `node dist/cli.js` if there is no linked command. Check required tool availability before building; browser checks need a usable browser executable. Work from the project directory or pass the config path explicitly:
+
+```sh
+shoalrun config validate docs.config.yaml
+shoalrun build docs.config.yaml site-dist
+shoalrun serve site-dist
+```
+
+`serve` previews the existing build. Use `shoalrun dev docs.config.yaml site-dist` when you need to keep editing with automatic rebuilds. Do not rebuild unchanged input solely to open a preview. A required clean-install release check remains separate from ordinary setup and authoring.
+
+Keep the build output separate from source files: `build` replaces its output directory. For draft pages, follow the authoring snapshot workflow in `guide.authoring-workspace`: capture a baseline before editing, run `docs validate`, then review and preview its captured output. Normal builds exclude drafts; changing working-page access is not a way to make validation pass. Reuse the validated snapshot rather than building a second preview.
+
+For a new OpenAPI source, read `guide.api-references` and complete its API-source review before final validation. For a first import, the minimal starter avoids bindings to the Cedar demo. When adapting api-docs or showcase, replacing the spec alone is insufficient. Update registered operations, authored page operation lists and embeds, navigation, and related links as a connected set. Also update API-specific mappings, query syntax, and discovery settings. Review full-source publication and remove the old review digest. If draft-only pages prevent the normal review command from rendering a candidate, use a separate local review candidate and keep working-page access intact. Pin only a reviewed digest for the same API source and operation selection.
+
+Check the generated HTML, Markdown twins, and `documents.json`. Confirm navigation and API links resolve, and inspect assets inside the components that contain them. Run `shoalrun audit docs.config.yaml` when project checks or API audits are configured; documentation behavior tests can use Doc Detective through `audit.tests` or another external CLI.
+
+Report the files created, commands run, and anything still needing an owner decision. Do not deploy, publish a release, or claim factual accuracy from a successful build alone.

package/skills/shoalrun-walkthrough/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: shoalrun-walkthrough
+description: Turn notes, a tutorial, or a piece of code into a Shoalrun Walkthrough component that explains code step by step. Use when a user asks for a code walkthrough, a step-by-step code explanation, or to convert an existing guide's numbered code steps into one.
+---
+
+# Write a Shoalrun walkthrough
+
+Read the component guide first with `shoalrun docs read guide.component.walkthrough`. It has the exact syntax, attributes, and build errors. Then read the source material: the user's notes, the guide being converted, and any code files it names.
+
+Choose the mode from the material. Use separate steps, each with its own complete code, when the code grows or changes from step to step. Use one shared code block with a `highlight` per step when the steps explain parts of a single file. Use the default `scroll` layout for code that builds up in order, and `layout="spotlight"` for reference material that readers jump around in. A list of steps without code is an ordinary numbered list, not a walkthrough.
+
+Give every step a short title and one to three sentences that say what the code does and why. Explain the lines the step highlights; don't restate the code. In separate mode, put the complete code at that point in each step, not only the new lines. Readers can then copy any step on its own. Highlight the lines that changed or that the step explains. Check that line numbers count from the first line shown.
+
+When the code already exists in the project, take it from the file with `file` and `region` instead of copying it into a fence. The walkthrough then stays in sync with code the project runs. Adding `#region name` and `#endregion` comments changes project code, so tell the user which files you marked. Use `lines` only for files that rarely change.
+
+Build with `shoalrun build docs.config.yaml <dedicated-output>`. Open the page's Markdown twin and check that every step has its title, explanation, and complete code in order. Open the HTML on a wide screen and scroll through the steps; each step's highlight should land on the lines its text describes. Fix build errors from their messages; they name the step and attribute at fault.
+
+Report the page you changed and the mode and layout you chose, with your reasons. Name any project files you marked with regions and any walkthrough code that you didn't run.

package/styles/fonts/figtree-LICENSE.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Figtree Project Authors (https://github.com/erikdkennedy/figtree) Figtree-Italic[wght].ttf: Copyright 2022 The Figtree Project Authors (https://github.com/erikdkennedy/figtree)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.