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

package/example-configs/showcase/content/personalization.mdx

@@ -0,0 +1,38 @@
+---
+id: showcase.personalization
+title: Choose your reading view
+summary: Try reader controls and themes while keeping every instruction available in Markdown.
+type: reference
+slug: /handbook/personalization
+---
+
+Reader views tailor what the browser shows. They do not restrict access or remove content from the Markdown output.
+
+## Choose a role
+
+<ReaderFilter facet="audience" display="checks" scope="page" />
+
+<ReaderChoice audience="operator" scope="page" label="I handle dispatches" />
+<ReaderChoice audience="developer" scope="page" label="I build integrations" />
+
+<ReaderSection audience="operator">
+
+### Operations team
+
+Use the [dispatch checklist](doc:showcase.procedures) to review labels, exceptions, and receipts.
+
+</ReaderSection>
+
+<ReaderSection audience="developer">
+
+### Developer
+
+Use the [API quickstart](doc:guide.quickstart) to inspect the request and its receipt. The API host is fictional.
+
+</ReaderSection>
+
+## Compare themes
+
+<ThemePreview />
+
+Check the callouts, code samples, and API reference in light and dark modes. Theme choices change presentation; both outputs retain the same underlying instructions.

package/example-configs/showcase/content/preview.mdx

@@ -0,0 +1,35 @@
+---
+id: showcase.preview
+title: Build and preview in a browser
+summary: Inspect the local site and open a page in Markdown.
+type: recipe
+slug: /handbook/preview
+updated: 2026-10-27
+---
+
+## Before you start
+
+Install the Shoalrun CLI and open a terminal in this starter's directory, beside `docs.config.yaml`. Use `site-dist` only for generated output: the build replaces that directory. The build needs no provider credentials and sends no parcel requests.
+
+## Build the site
+
+```sh
+shoalrun config validate docs.config.yaml
+shoalrun build docs.config.yaml site-dist
+```
+
+Both commands must finish successfully. If either reports an error, correct the named source file and rerun it before treating the output as current.
+
+## Start the preview
+
+```sh
+shoalrun serve site-dist
+```
+
+Open the address printed by the command. If its port is occupied, stop the old preview or choose another port with `--port 8788`.
+
+## Check the reading experience
+
+Open **Prepare a dispatch** from the Handbook navigation. Filter the service table for `Local` and confirm that only the matching row remains. Clear the filter to restore the table. Switch between light and dark modes, then use **Read as Markdown** and confirm the same three services appear.
+
+The task is complete when the site loads, the filter works, and the Markdown link opens the page text. Stop the server with Control+C when finished.

package/example-configs/showcase/content/procedures.mdx

@@ -0,0 +1,88 @@
+---
+id: showcase.procedures
+title: Run a dispatch review
+summary: Guide a reader through steps, milestones, optional detail, and related pages.
+type: how-to
+slug: /handbook/procedures
+---
+
+Use this fictional checklist to review a dispatch before handing it to a courier.
+
+## Review the manifest
+
+<Steps headingLevel="3">
+<Step title="Count the parcels" icon="package">
+
+Compare the manifest with the parcels in the collection area.
+
+</Step>
+<Step title="Review exceptions" icon="clipboard-check">
+
+Resolve missing labels and destination mismatches before continuing.
+
+</Step>
+<Step title="Save the receipt" icon="archive">
+
+Keep the receipt alongside the reviewed manifest.
+
+</Step>
+</Steps>
+
+## Track the review
+
+<Progress label="Dispatch checks complete" value="2" max="3" />
+
+<Timeline current="review">
+<Milestone id="prepare" title="Prepared">
+
+The manifest and parcels are ready.
+
+</Milestone>
+<Milestone id="review" title="Under review">
+
+The operator is checking exceptions.
+
+</Milestone>
+<Milestone id="handoff" title="Handed over">
+
+The courier receives the reviewed dispatch.
+
+</Milestone>
+</Timeline>
+
+## Resolve an exception
+
+<CollapsibleGroup>
+
+
+<Collapsible title="A parcel is missing">
+
+Leave the handoff incomplete until the operator records an explanation and updates the manifest.
+
+</Collapsible>
+<Collapsible title="The destination changed">
+
+Replace the label and compare it with the revised manifest before resuming the review.
+
+</Collapsible>
+
+
+</CollapsibleGroup>
+
+## Organize the files
+
+<FileTree controls>
+<Folder name="dispatch">
+<File name="manifest.csv" />
+<File name="receipt.json" />
+<Folder name="notes" collapsed>
+<File name="review.md" doc="showcase.reading" />
+</Folder>
+</Folder>
+</FileTree>
+
+## Continue
+
+<DocLink doc="guide.quickstart" />
+
+<DocCollection type="reference" limit={3} />

package/example-configs/showcase/content/quickstart.mdx

@@ -0,0 +1,64 @@
+---
+id: guide.quickstart
+title: Enroll your first parcel program
+summary: Prepare a local-shop enrollment and understand the receipt.
+slug: /quickstart
+card: { icon: rocket, eyebrow: Start here }
+---
+
+Enroll a local shop by sending its organization, contact, and pickup windows. This guide uses the same request and response examples as the [enrollment reference](doc:reference.create-enrollment).
+
+<Callout type="note" label="Before you begin">
+The Cedar Parcel hosts are fictional. Replace the sandbox URL with your own server before running the command. Enrollment requires an application key; other operations have their own authentication rules.
+</Callout>
+
+## Request example
+
+<ApiExample operation="cedar.createEnrollment" kind="request" mediaType="application/json" example="localShop" />
+
+## Create an enrollment
+
+<Steps>
+<Step title="Prepare the request">
+
+
+Save the request JSON above as `enrollment.json`. The `local` program requires the organization, contact, and pickup-window fields shown in the example.
+
+
+</Step>
+
+<Step title="Send the enrollment">
+
+
+Set `CEDAR_BASE_URL` to your sandbox's base URL and `CEDAR_APPLICATION_KEY` to its enrollment key. The example source uses `https://sandbox.api.cedar-parcel.example/v1`.
+
+```sh
+curl --request POST "$CEDAR_BASE_URL/Enrollments" \
+  --header "X-Application-Key: $CEDAR_APPLICATION_KEY" \
+  --header 'Content-Type: application/json' \
+  --data @enrollment.json
+```
+
+
+</Step>
+
+<Step title="Inspect the receipt">
+
+
+A successful create request returns HTTP `201`. Save the returned `enrollmentId`. A `pending` status means the enrollment was recorded but review is still pending. `approvedAt` can be null until approval.
+
+
+</Step>
+</Steps>
+
+## Response example
+
+<ApiExample operation="cedar.createEnrollment" kind="response" status="201" mediaType="application/json" example="pending" />
+
+## What next?
+
+Open the [enrollment reference](doc:reference.create-enrollment) to compare local, chilled, bulk, and combined programs. Use [parcel search](doc:reference.cedar.listParcels) to explore record filters and download formats. Inspect the [delivery webhook](doc:reference.cedar.parcelDelivered) to see how an event includes photo or signature proof.
+
+## Related reading
+
+<RelatedReading />

package/example-configs/showcase/content/reading.mdx

@@ -0,0 +1,99 @@
+---
+id: showcase.reading
+title: Prepare a dispatch
+summary: Use callouts, definitions, tables, and field lists to explain a dispatch clearly.
+type: reference
+slug: /handbook/reading
+---
+
+A dispatch groups parcels collected during one pickup window. Check the destination and service before printing a manifest. The examples on this page illustrate documentation components; they are not additional API operations.
+
+## Before you begin
+
+<Callout type="note">All parcel IDs on this site are fictional.</Callout>
+<Callout type="tip">Group parcels by pickup window to make the handoff easier to check.</Callout>
+<Callout type="important">Keep the dispatch receipt until every parcel is reconciled.</Callout>
+<Callout type="warning">Changing a destination after printing a label can produce a mismatch.</Callout>
+<Callout type="caution">Do not put real addresses or credentials in this public example.</Callout>
+
+## Understand the labels
+
+The example workflow is <Badge variant="success" icon="check">Ready to review</Badge>.
+Press <Kbd>Control</Kbd> + <Kbd>K</Kbd> to open search.
+
+<InfoHint label="Pickup window">
+
+The agreed interval during which a courier collects a dispatch.
+
+</InfoHint>
+
+Compare the <Tooltip label="manifest digest">A fingerprint used to detect changes to the manifest file.</Tooltip> before handing over the file.
+
+<DefinitionList filter>
+<Term>Dispatch</Term>
+<Definition>
+
+A group of parcels prepared for one pickup.
+
+</Definition>
+<Term>Receipt</Term>
+<Definition>
+
+The record returned when an enrollment is accepted. Acceptance does not prove delivery.
+
+</Definition>
+<Term>Reconciliation</Term>
+<Definition>
+
+Matching every parcel to its recorded outcome.
+
+</Definition>
+</DefinitionList>
+
+## Choose a service
+
+<Table filter sticky>
+
+| Service | Pickup | Tracking | Best for |
+| --- | --- | --- | --- |
+| Local | Same city | Every handoff | Nearby shops |
+| Regional | Next scheduled run | Depot and delivery | Neighboring cities |
+| Scheduled | Agreed window | Every handoff | Repeat collections |
+
+</Table>
+
+## Prepare the handoff
+
+- Check that each parcel has a readable label and that the destination matches the manifest. If a label is damaged, replace it before moving the parcel into the collection area.
+- Count the parcels against the dispatch record. Investigate missing or extra parcels before confirming the handoff, and record the reason for any correction.
+- Keep the receipt with the dispatch record so the operations team can trace a discrepancy without relying on a conversation or a temporary browser session.
+
+## Describe configuration
+
+These fields describe a fictional local checklist, not the API request schema.
+
+<Fields>
+<Field name="dispatchName" type="string" required minLength="1" maxLength="80" example="Tuesday pickup">
+
+
+A label for the operations team.
+
+
+</Field>
+<Field name="notifications" type="object" optional nullable>
+
+
+Optional local notification settings.
+<Fields>
+<Field name="enabled" type="boolean" optional default="false">
+
+Enable checklist reminders.
+
+</Field>
+</Fields>
+
+
+</Field>
+</Fields>
+
+<ActionLink doc="showcase.procedures">Follow the dispatch checklist</ActionLink>

package/example-configs/showcase/content/verify.mdx

@@ -0,0 +1,27 @@
+---
+id: showcase.verify
+title: Build and inspect both outputs
+summary: Check that a content edit produces HTML and Markdown.
+type: recipe
+slug: /handbook/verify
+updated: 2026-10-27
+---
+
+## Before you start
+
+Install the Shoalrun CLI and open a terminal in this starter's directory, beside `docs.config.yaml`. Use `site-dist` only for generated output: the build replaces that directory. The build needs no provider credentials and sends no parcel requests.
+
+## Build the site
+
+```sh
+shoalrun config validate docs.config.yaml
+shoalrun build docs.config.yaml site-dist
+```
+
+Both commands must finish successfully. If either reports an error, correct the named source file and rerun it before treating the output as current.
+
+## Inspect the result
+
+Open `site-dist/handbook/reading/index.html` and `site-dist/handbook/reading.md`. Confirm both include the five messages under **Before you begin**, the service table, and the handoff checklist. The HTML includes visual icons; the Markdown retains message labels and their text.
+
+The task is complete when the build succeeds and both files contain the expected content. A successful build alone does not establish that the advice is correct.

package/example-configs/showcase/content/visuals.mdx

@@ -0,0 +1,47 @@
+---
+id: showcase.visuals
+title: Follow the parcel journey
+summary: Explain a flow with diagrams, a local image, and a simple equation.
+type: explanation
+slug: /handbook/visuals
+---
+
+A dispatch moves from preparation through review to handoff. Keep the explanation alongside the graphic so it remains useful in Markdown and without JavaScript.
+
+## Review flow
+
+<Diagram engine="mermaid" title="Dispatch review" summary="Prepare the manifest, resolve exceptions, then hand it to the courier." width="720">
+
+```mermaid
+flowchart LR
+  prepare[Prepare manifest] --> review[Review exceptions]
+  review --> handoff[Courier handoff]
+```
+
+</Diagram>
+
+## Data flow
+
+<Diagram title="Dispatch records" summary="The reviewed manifest and courier receipt both feed reconciliation." layout="elk" width="720">
+
+```d2
+manifest: Reviewed manifest
+receipt: Courier receipt
+reconcile: Reconciliation
+manifest -> reconcile
+receipt -> reconcile
+```
+
+</Diagram>
+
+## Collection area
+
+<Image src="./assets/collection.svg" alt="Three labeled parcel boxes inside a marked collection area" caption="Keep reviewed parcels together until the handoff." width="640" expand />
+
+## Reconcile the counts
+
+The unresolved count is <Math expression="u = p - d" />, where p is the number of prepared parcels and d is the number with recorded delivery outcomes.
+
+<Math display expression="p = 3,\quad d = 2,\quad u = 1" />
+
+A count alone does not prove delivery; inspect each parcel's recorded outcome.

package/example-configs/showcase/content/workflows.mdx

@@ -0,0 +1,12 @@
+---
+id: showcase.workflows
+title: Check your changes
+summary: Choose a complete local workflow for reviewing this starter.
+type: cookbook
+slug: /handbook/workflows
+updated: 2026-10-27
+---
+
+Choose one path. Both recipes include the build, so following both would repeat that step. The chooser loads instructions; it does not run commands.
+
+<CookbookChooser id="local-checks" />

package/example-configs/showcase/docs.config.yaml

@@ -0,0 +1,149 @@
+# Cedar Parcel API: guides, generated references, and agent-friendly contracts.
+schemaVersion: 1
+
+site:
+  title: Cedar Parcel
+  origin: https://docs.cedar-parcel.example
+  # Hidden visually until focused; present in HTML for agents and screen readers.
+  agentDiscovery:
+    mode: focus
+    message: Use Markdown for complete examples and the linked focused API contracts.
+  header:
+    links:
+      - { label: Quickstart, href: /quickstart, style: primary }
+  footer:
+    columns:
+      - title: Start building
+        links:
+          - { label: Overview, href: / }
+          - { label: Quickstart, href: /quickstart }
+          - { label: Enrollment reference, href: /reference/create-enrollment }
+    text: Cedar Parcel is a fictional example API.
+
+theme:
+  preset: shoal
+  palette: kelp
+  mode: system
+  toggle: true
+
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current, language: en }
+
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    language: en
+    access: { policy: public }
+
+apis:
+  cedar:
+    source: { kind: file, path: ./apis/cedar-parcel.yaml, publish: true }
+    discovery: { endpoint: https://api.cedar-parcel.example/v1 }
+    publicReview:
+      digest: a7a7e8eb427a7481f1c1f357d03db40319ad2e79bdeea926501da744cbecfd6f
+    mappings:
+      subjectLifecycle:
+        from: x-docs-availability.phase
+        values:
+          limited: beta
+          building: in-development
+          retired: deprecated
+    querySyntax:
+      - parameter: parameters
+        pathPrefixes: [/Search/]
+        style: unwrapped
+        example: declaredValue(gt)=100
+    operations:
+      - id: cedar.createEnrollment
+        sourceOperationId: createEnrollment
+        reference: reference.create-enrollment
+    generateReferences:
+      pathPrefix: /reference
+
+navigation:
+  - { id: features, doc: showcase.features }
+  - { id: overview, doc: guide.overview }
+  - { id: quickstart, doc: guide.quickstart }
+  - id: handbook
+    label: Handbook
+    items:
+      - { id: reading, doc: showcase.reading }
+      - { id: procedures, doc: showcase.procedures }
+      - { id: code, doc: showcase.code }
+      - { id: visuals, doc: showcase.visuals }
+      - { id: personalization, doc: showcase.personalization }
+      - { id: workflows, doc: showcase.workflows }
+      - { id: landing, doc: showcase.landing }
+  - id: reference
+    label: API reference
+    api: cedar
+    items:
+      - { id: create-enrollment, operation: cedar.createEnrollment }
+      - { id: generated, generated: tags }
+
+relationships:
+  - id: overview-to-quickstart
+    from: guide.overview
+    to: guide.quickstart
+    type: next-step
+    reason: Prepare a local-shop enrollment and inspect its receipt.
+  - id: quickstart-to-reference
+    from: guide.quickstart
+    to: reference.create-enrollment
+    type: next-step
+    reason: Compare all four program shapes and their required fields.
+
+outputs:
+  markdown:
+    metadata:
+      format: yaml-frontmatter
+      fields:
+        id: frontmatter.id
+        title: frontmatter.title
+        summary: frontmatter.summary
+        canonical: publication.canonicalUrl
+      byType:
+        api-reference:
+          addFields: { operations: frontmatter.operations }
+
+readerFilters:
+  facets:
+    audience:
+      label: Reader
+      options:
+        operator: Operations team
+        developer: Developer
+  controls:
+    sidebar: false
+
+snippets:
+  cedar.sandbox:
+    file: ./snippets/sandbox.mdx
+    variables:
+      task: { type: string, required: true }
+
+cookbooks:
+  local-checks:
+    title: What do you want to check?
+    mode: single
+    options:
+      - id: artifacts
+        label: Build and inspect both outputs
+        doc: showcase.verify
+        when: You edited content and want to check its HTML and Markdown.
+        needs: This starter and the Shoalrun CLI.
+        outcome: A successful build with both representations present.
+      - id: browser
+        label: Build and preview in a browser
+        doc: showcase.preview
+        when: You want to inspect layout and interactive controls.
+        needs: This starter, the Shoalrun CLI, and a browser.
+        outcome: A local preview with a working page and Markdown link.

package/example-configs/showcase/snippets/sandbox.mdx

@@ -0,0 +1 @@
+<Callout type="note" label="Sandbox example">Use fictional data when practicing <Var name="task" />. Replace the example hosts before making real requests.</Callout>

package/examples/analytics/README.md

@@ -0,0 +1,56 @@
+# Analytics adapters
+
+`inspector.js` shows the latest 100 Shoalrun events in a local panel and in
+`window.shoalrunDebugEvents`. Copy it beside your config and set
+`analytics: { module: ./inspector.js }`. It uses memory only and sends no requests.
+Use it for local previews.
+
+## PostHog
+
+Copy `posthog.js` beside your config. Replace the public project token and
+ingestion host with values from PostHog's web setup screen; never use a personal
+API key. Install and bundle from that directory:
+
+```sh
+npm install posthog-js
+npm install --save-dev esbuild
+npx esbuild posthog.js --bundle --format=esm --platform=browser --outfile=analytics.js
+```
+
+Set `analytics: { module: ./analytics.js }` and rebuild your site. Commit the
+lockfile and rebundle after adapter or SDK changes. The SDK may load additional
+resources; allow them in your content security policy.
+
+The adapter uses these mappings:
+
+| Source | PostHog destination |
+| --- | --- |
+| Shoalrun `page_view` | `$pageview`; automatic SDK page views are disabled to avoid duplicates. |
+| SDK page exit | `$pageleave`, with native scroll depth and duration. |
+| Other Shoalrun and custom events | Original names, for Product Analytics insights and funnels. |
+
+Do not rename interactions to `$autocapture`; it requires SDK-generated element
+metadata. Generic click capture, heatmaps, replay, and person profiles are off.
+PostHog adds its own properties and manages storage. Consent changes must also
+update SDK capture: disabling Shoalrun alone does not stop native page leaves.
+
+Serve your built site locally and filter PostHog's live event stream by
+`environment = development`, including internal/test users. Check one `$pageview`
+and a content interaction such as `code_copy`. Scroll, then follow a page link to
+inspect `$pageleave`. Its `$prev_pageview_max_scroll_percentage` and
+`$prev_pageview_max_content_percentage` range from 0 to 1;
+`$prev_pageview_duration` is seconds open. These measure the document, excluding
+nested code panes. Page-leave delivery is best effort.
+
+If events are missing, check consent, blockers, and network requests. The local
+inspector only shows Shoalrun events before translation; it cannot confirm
+PostHog ingestion or show SDK-generated page leaves. Exclude development traffic
+from production reports, or use a separate project.
+
+Agents that fetch Markdown or call tools without running page JavaScript are
+not counted. Measure those requests at the CDN, host, or tool server, including
+cache hits. Keep request counts separate from browser page views. See the site's
+analytics reference for the adapter contract and request-collection guidance.
+
+See PostHog's [JavaScript SDK](https://posthog.com/docs/libraries/js) and
+[configuration reference](https://posthog.com/docs/libraries/js/config).

package/examples/analytics/inspector.js

@@ -0,0 +1,25 @@
+// Local debugging only: no requests, identifiers, or persistent storage.
+const events = [];
+let panel;
+let output;
+let label;
+export function init() {
+  panel = document.createElement('details');
+  panel.id = 'analytics-inspector';
+  panel.style.cssText = 'position:fixed;bottom:16px;right:16px;z-index:9999;max-width:calc(100vw - 32px);width:440px;background:#101820;color:#e8f0f0;border:1px solid #52636b;border-radius:8px;padding:12px;font:13px/1.5 monospace;box-shadow:0 4px 24px #0006';
+  label = document.createElement('summary');
+  label.style.cursor = 'pointer';
+  output = document.createElement('pre');
+  output.style.cssText = 'max-height:40vh;overflow:auto;white-space:pre-wrap;overflow-wrap:anywhere;margin:12px 0 0';
+  output.setAttribute('aria-label', 'Recent analytics events');
+  panel.append(label, output);
+  document.body.append(panel);
+  globalThis.shoalrunDebugEvents = events;
+}
+export function track(event) {
+  events.push(event);
+  if (events.length > 100) events.shift();
+  label.textContent = `Local events (${events.length})`;
+  output.textContent = events.slice().reverse().map(item => JSON.stringify(item, null, 2)).join('\n\n');
+  console.debug('[Shoalrun analytics]', event);
+}

package/examples/analytics/posthog.js

@@ -0,0 +1,36 @@
+// Bundle before configuring this adapter; see README.md.
+import posthog from 'posthog-js';
+
+export function init({ page }) {
+  posthog.init('phc_REPLACE_WITH_PUBLIC_PROJECT_TOKEN', {
+    api_host: 'https://us.i.posthog.com', // Use your project's ingestion host.
+    autocapture: false,
+    capture_dead_clicks: false,
+    capture_heatmaps: false,
+    capture_performance: false,
+    capture_exceptions: false,
+    disable_surveys: true,
+    capture_pageview: false,
+    capture_pageleave: true,
+    disable_scroll_properties: false,
+    disable_session_recording: true,
+    person_profiles: 'never',
+  });
+  // Super-properties persist across pages, including pages outside navigation tabs.
+  if (!page.navigationSectionId) posthog.unregister('navigationSectionId');
+  // These properties also accompany SDK-generated page-leave events.
+  posthog.register({
+    ...page,
+    environment: ['localhost', '127.0.0.1', '::1', '[::1]'].includes(location.hostname)
+      ? 'development' : 'production',
+  });
+}
+
+export function track(event) {
+  posthog.capture(event.name === 'page_view' ? '$pageview' : event.name, {
+    ...event.properties,
+    shoalrunSchemaVersion: event.schemaVersion,
+    environment: ['localhost', '127.0.0.1', '::1', '[::1]'].includes(location.hostname)
+      ? 'development' : 'production',
+  });
+}