@bitcobblers/wod-wiki-tools 0.53.2203 → 0.54.2205

package/dist/skills/wod-wiki-testing/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: wod-wiki-testing
+description: Use when writing, debugging, or updating tests in wod-wiki across domain logic, Playground UI, Storybook states and play() scripts, or Markdown specs and Playwright E2E journeys.
+---
+
+# WOD Wiki testing
+
+Pick the lowest tier that exercises the behavior, then compose the existing module for that tier from [`references/catalog.md`](references/catalog.md). Read `docs/development/validation.md` for merge and preview gates.
+
+## 1. Pick the tier
+
+| Behavior under test | Tier | Seam to compose | Runner |
+|---|---|---|---|
+| Parsing, `Metric Shake-Out Queue`, `Scoped Property Override` precedence, `Session` intake, `Note Provenance`, WQL `Entity Scope`, `Feed` and `Seed` round-trips | **Tier 1: Domain scenario** | `DomainScenarioHarness` (`packages/engine/tests/harness/DomainScenarioHarness.ts`) + `@bitcobblers/wod-wiki-core/testing` + `.md` scenario tables | `bun run test:package` |
+| Isolated UI rendering, empty/populated/override/diagnostic/`Feed` states, dialog/sheet/widget interactions | **Tier 2: Storybook state + `play()`** | `parameters.domainState` + `storyActions` (`apps/storybook/src/testing/storyActions.ts`) | `bun run test:storybook` |
+| Playground route/hook integration in memory without a browser | **Tier 2b: Playground host** | `renderWithPlaygroundHost` / `setupPlaygroundTestHost` (`apps/playground/src/testing/host.tsx`) | `bun run test:playground:unit` |
+| Multi-route user journeys, URL survival, persistence across reloads, desktop + 375x812 layout gates | **Tier 3: Markdown journey + Playwright** | `e2e/specs/<domain>/<journey>.md` + `PlaygroundTestActor` (`e2e/fixtures/playgroundActor.ts`) | `bun x playwright test --config playwright.journal.config.ts <spec>` |
+
+## 2. Authoring workflow by tier
+
+### Tier 1: Business-language domain scenarios
+
+1. Add a pure Markdown fixture when testing WQL (`packages/wql/tests/fixtures/scenarios/`) or parser snapshots (`packages/lang/tests/fixtures/`); zero TypeScript changes needed.
+2. For cross-domain flows (`Note` -> `Property Note` -> `Metric Shake-Out Queue` -> `Session` -> WQL -> `Feed`), instantiate `DomainScenarioHarness.create()` in `packages/engine/tests/domain/` and call `afterEach(() => harness.dispose())`.
+3. Build fixtures through `buildTestNote`, `buildPropertyNote`, `buildTestSession`, and `buildDomainWorld` from `@bitcobblers/wod-wiki-core/testing` (`packages/core/src/testing.ts`).
+4. For low-level runtime block or JIT strategy checks inside `packages/engine`, use `BehaviorTestHarness`, `MockBlock`, and `ExecutionContextTestHarness` from `packages/engine/tests/harness/`.
+
+### Tier 2: Storybook states and Playground host tests
+
+1. In `apps/storybook/src/`, set `parameters: { domainState: '<preset>' }` (`empty`, `populatedJournal`, `activeSession`, `scopedPropertyOverride`, `skippedDependencyDiagnostic`, or `readOnlyFeedNote`) or pass a custom `DomainWorldInput` (`apps/storybook/src/testing/domainStates.tsx`). Reserve `parameters: { database: true }` strictly for `apps/storybook/src/database/Database.stories.tsx` and the live IndexedDB workbench pages.
+2. Script isolated interactions in `play({ canvasElement })` using `storyActions` (`apps/storybook/src/testing/storyActions.ts`) and `TEST_IDS` (`apps/playground/src/lib/testIds.ts`).
+3. In `apps/playground`, mount UI and hooks through `renderWithPlaygroundHost` or `setupPlaygroundTestHost` (`apps/playground/src/testing/host.tsx`). Inject optional `deps` or adapter props on external SDKs (`ChromecastBackend`, `AudioProvider`) rather than global module mocks so the warm Vitest worker pool stays clean.
+
+### Tier 3: Two-level Markdown journeys and Playwright
+
+1. Write or update `e2e/specs/<domain>/<journey>.md` first (`journal`, `notebooks`, `runtime`, `properties`, `analytics`, `feeds`): YAML frontmatter (`domain`, `specFile`, `routes`, `personas`, `viewports`, `priority`), `### Scenario N: <title>` headings, `Given <GLOSSARY.md world setup>:`, numbered user steps, and `- expect:` outcome bullets.
+2. Start `e2e/live-app/<journey>.e2e.ts` with `// spec: e2e/specs/<domain>/<journey>.md` and import `{ test, expect, TEST_IDS } from '../fixtures/playgroundActor'`.
+3. Drive all seeding, navigation, editing, timer advancement, WQL queries, and Feed operations through the 8 actor namespaces (`app.seed`, `app.journal`, `app.notebooks`, `app.properties`, `app.editor`, `app.runtime`, `app.wql`, `app.feeds`) backed by `TEST_IDS`.
+4. Verify 1:1 bidirectional spec parity with `bun scripts/check-e2e-specs.ts`.
+
+## 3. Token-lean execution and log watching
+
+- Look up exact builder, state-preset, and actor method signatures in [`references/catalog.md`](references/catalog.md) instead of scanning `e2e/live-app/` or `apps/playground/` for examples.
+- Delegate test suite runs and log inspection to a low-reasoning flash subagent (`sonic`): redirect suite output to `/tmp/<run>.log`, verify exit status, and return only pass/fail totals, warnings, and failing stack excerpts.
+- Always pass `--noEmit` when invoking `tsc` directly.

package/dist/skills/wod-wiki-testing/references/catalog.md

@@ -0,0 +1,81 @@
+# WOD Wiki test module catalog
+
+Copy-ready imports and interfaces across all three tiers.
+
+## 1. Canonical domain builders (`@bitcobblers/wod-wiki-core/testing`)
+
+Source: `packages/core/src/testing.ts`
+
+```ts
+import {
+  buildTestNote,
+  buildPropertyNote,
+  buildTestSession,
+  buildDomainWorld,
+  resetTestingVocabulary,
+} from '@bitcobblers/wod-wiki-core/testing';
+```
+
+- `buildTestNote({ id?, title?, rawContent, type?, date?, tags?, notebookId?, notebookIds?, seedOrigin?, feedOrigin?, feedSourceId?, sourceId?, sourcePath?, provenance?, priorBlocks? })` -> `{ note, revisions, blockIndex, blockEfforts, blockEquipment, tags, noteTags, notebookLinks }`
+- `buildPropertyNote({ id?, kind: 'effort' | 'equipment' | 'tag' | 'tag-type', slug, label, notebookId?, aliases?, metrics?, summaries?, baseAttributes?, body?, asOverride?, feedSourceId? })` -> `{ note, override? }`
+- `buildTestSession({ id?, noteId, blockId?, blockVersion?, startedAt?, completedAt?, durationMs?, origin?, isPublic?, notebookIds?, events? })` -> `{ session, events, notebookLinks }`
+- `buildDomainWorld({ notes?, propertyNotes?, sessions?, pages?, pageNotes? })` -> `DomainWorld`
+
+## 2. Engine domain scenario harness (`packages/engine/tests/harness/DomainScenarioHarness.ts`)
+
+```ts
+import { DomainScenarioHarness } from '../harness/DomainScenarioHarness';
+```
+
+- `await DomainScenarioHarness.create(initialWorld?)` -> live `SqlStorage(':memory:')` + `QueryService`
+- `await harness.authorNote(input)` / `await harness.definePropertyNote(input)` / `await harness.saveScopedOverride(input)` / `await harness.promoteNote({ noteId, notebookIds, sessionIds?, shareSessionsPublicly? })`
+- `await harness.evaluateShakeOut({ metrics, stage?: 'plan' | 'log', elapsedMs?, sources?, scope?, mode?: 'source-first' | 'custom-runtime' })` -> `{ container, result, diagnostics, values }`
+- `await harness.prepareAndRunSession({ noteId, blockId?, sessionId?, journalDate?, startedAt?, advances?, maxNexts? })` -> `{ sessionId, noteId, session, outputs, events, clonedFromReadOnly, provenance, upstream }`
+- `await harness.queryWql(wql, options?)` / `harness.resolveEntityScope(entity)`
+- `await harness.publishFeed(options?)` -> `{ tree, report }` / `await harness.importFeedIntoFreshHarness(tree, sourceId?)`
+- `await harness.dispose()`
+
+## 3. Playground in-memory host (`apps/playground/src/testing/host.tsx`)
+
+```ts
+import {
+  hydratePlaygroundStorage,
+  setupPlaygroundTestHost,
+  renderWithPlaygroundHost,
+  PlaygroundProviderTree,
+} from '@/testing/host';
+```
+
+- `await setupPlaygroundTestHost({ world?, storage?, localStorageEntries? })` -> `{ world, storage, storageService, queryService, notePersistence, notebookService, cleanup }`
+- `await renderWithPlaygroundHost(ui, { world?, route?, routePath?, searchParams?, theme?, panelSize? })` -> `{ rendered, world, storage, storageService, queryService, getLocation, urlUpdates, cleanup }`
+
+## 4. Storybook domain states & actions (`apps/storybook/src/testing/storyActions.ts`)
+
+State presets live in `apps/storybook/src/testing/domainStates.tsx`:
+
+```ts
+import { storyActions } from './testing/storyActions';
+```
+
+- `parameters.domainState`: `'empty'` | `'populatedJournal'` | `'activeSession'` | `'scopedPropertyOverride'` | `'skippedDependencyDiagnostic'` | `'readOnlyFeedNote'` | `DomainWorldInput`
+- `storyActions`: `withinStory(canvasElement)`, `waitForHydrated(canvasElement)`, `selectOverrideScope(canvasOrBody, targetNotebookId)`, `toggleNotebookPromotion(canvasOrBody, notebookId)`, `toggleNotebookPublic(canvasOrBody, slugOrNotebookId?)`, `toggleSessionPublic(canvasOrBody, sessionId)`, `selectSessionRow(canvas, titleOrId)`
+
+## 5. Playwright domain actor (`e2e/fixtures/playgroundActor.ts`)
+
+Canonical `data-testid` contract: `apps/playground/src/lib/testIds.ts` (re-exported at `e2e/contracts/TestIdContract.ts`).
+
+```ts
+// spec: e2e/specs/<domain>/<journey>.md
+import { test, expect, TEST_IDS } from '../fixtures/playgroundActor';
+```
+
+- `await app.goto(path)` (navigates and awaits `waitForFeedReady`)
+- `app.seed`: `world(input)`, `journalNote(date, markdown, opts?)`, `note(noteId, markdown, opts?)`, `notebook(slug, opts?)`, `propertyOverride(input)`, `completedSessions(noteId, sessions)`, `bundledEquipment()`, `bundledEfforts()`, `mockPeerFeed(baseUrl, spec)`
+- `app.journal`: `openStream(query?)`, `openDate(date)`, `clearDate(date)`, `expectNotePersisted(routeId, expectedSubstring)`
+- `app.notebooks`: `openLibrary(query?)`, `openNotebook(slug, target?)`, `create(name, description?)`, `rename(slug, newName)`, `delete(slug)`, `promoteNote(notebookIds)`, `setNotebookPublic(slugOrId, isPublic)`
+- `app.properties`: `openEffort(slug?)`, `openEquipment(slug?)`, `openTags(category?, slug?)`, `saveScopedOverride(targetNotebookId)`
+- `app.editor`: `openNote(noteId)`, `replaceDocument(markdown)`, `readDocument()`, `typeLine(text)`, `readStoredContent(routeId)`
+- `app.runtime`: `useFastClock(speedFactor?)`, `startWorkout()`, `advance(steps?)`, `stopSession()`, `wallClock()`
+- `app.wql`: `openExplorer(query?)`, `openDashboard(slug)`, `queryStream(route, wql)`, `fillStreamQueryBar(wql)`, `setStreamLayout(route, layout)`, `expectStreamContains(text)`, `expectStreamExcludes(text)`
+- `app.feeds`: `waitForReady()`, `openFeeds()`, `syncNow(feedId)`, `openPromotionPopover()`, `closePromotionPopover()`, `setSessionPublic(sessionId, isPublic)`, `expectPublicationVisibility(expected)`, `exportPortable('feed-repo-zip')`
+- `app.assertCleanConsole()`

package/dist/skills/wod-wql/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: wod-wql
+description: 'Write, validate, and execute WQL (Workout Query Language) find and aggregate queries against WOD Wiki notes, workout blocks, sessions, efforts, tags, and time windows.'
+license: MIT
+---
+
+# WQL (Workout Query Language) Agent Guide
+
+## Overview
+
+WQL queries structured workout notes, immutable block revisions, movement efforts, tags, and recorded execution sessions across all three WOD Wiki surfaces:
+- **CLI**: `wod query '<wql>' --format json` (dry-run syntax check: `wod query '<wql>' --validate-only --json`)
+- **MCP / WebMCP**: `wod_query_wql` and `wod_validate_wql`
+- **Browser Stream Views**: `ui_set_stream_query`
+
+---
+
+## Query Families
+
+### 1. Find Queries (`:<target>{...}`)
+Select entities matching structured filters:
+
+| Target | Purpose | Example |
+|---|---|---|
+| `:note` | Workout & journal notes | `:note{notebook:journal time:14d}` |
+| `:block` | Individual `time` / `log` workout blocks | `:block{effort:thrusters}` |
+| `:session` | Completed or logged workout sessions | `:session{time:30d}` |
+| `:effort` | Canonical movement / exercise definitions | `:effort{discipline:weightlifting}` |
+| `:notebook` | Local and subscribed notebooks | `:notebook{}` |
+| `:tag` | Tags across categories | `:tag{}` |
+| `:equipment` | Equipment definitions & tags | `:equipment{}` |
+
+Common filters inside `{...}`:
+- `notebook:<slug>` — filter notes in a notebook (`journal`, `benchmarks`, etc.)
+- `tags:<slug>` — filter by tag
+- `effort:<slug>` — filter notes/blocks/sessions involving a movement
+- `time:<window>` — relative time window (`7d`, `14d`, `30d`, `90d`, `1y`) or ISO date range
+
+### 2. Aggregate Queries (`:<agg>{...} [by {<dim>}]`)
+Roll up recorded workout metrics over time or movement dimensions:
+
+- **Aggregators**: `:sum`, `:count`, `:max`, `:min`, `:avg`
+- **Metric families**: `metric:reps`, `metric:weight`, `metric:distance`, `metric:time`, `metric:rounds`, `metric:volume`
+- **Grouping dimensions (`by {...}`)**: `day`, `week`, `month`, `effort`, `notebook`
+
+Examples:
+```wql
+:sum{metric:reps time:30d} by {week}
+:sum{metric:reps effort:pull-ups time:90d} by {week}
+:max{metric:weight effort:back-squat time:1y}
+:count{metric:rounds time:30d} by {effort}
+```
+
+---
+
+## Best Practices for Agents
+
+1. **Validate Before Running Unfamiliar Filters**:
+   Call `wod_validate_wql` (or `wod query '<wql>' --validate-only --json`) to inspect parsed AST and catch unknown filter keys (exit code `2` on invalid WQL).
+2. **Read Live Capabilities**:
+   Read MCP resource `wod://schema/wql` for the exact list of valid filter keys per target, aggregators, and virtual dimensions compiled into the current engine version.
+3. **Prefer Unbatched Data Tools Over UI Scraping**:
+   In the browser, `wod_query_wql` queries IndexedDB / `ApiStorage` directly without UI pagination limits, whereas `ui_set_stream_query` updates the visible stream for the human user.

package/dist/web/playground/ai-skills/agent-parity.md

@@ -0,0 +1,41 @@
+---
+name: wod-agent-parity
+description: 'Enforce First-Class Agent Readiness & Action Parity whenever adding or modifying WOD Wiki features, routes, UI actions, domain services, or CLI commands across Playground WebMCP, wod server MCP, and the wod CLI.'
+license: MIT
+---
+
+# First-Class Agent Readiness & Action Parity (`wod-agent-parity`)
+
+## Core Mandate
+
+Every user-facing capability in WOD Wiki MUST maintain **Action Parity** between human-driven UI actions and AI-agent-driven actions across all applicable surfaces:
+
+1. **Portable Domain Mutations & Queries (`@bitcobblers/wod-wiki-engine/agent`)**:
+   - Any new domain read or write (Notes, Journal, Notebooks, Sessions, Catalog/Tags, WQL, Feeds, Portability) MUST be defined once as a typed `AgentToolSpec` in `packages/engine/src/agent/tools/` and exported in `packages/engine/src/agent/manifest.ts` (`DOMAIN_AGENT_TOOLS`).
+   - Because `PlaygroundAgentProvider` (`apps/playground/app/agent/PlaygroundAgentProvider.tsx`) and `createWodMcpServer` (`packages/tools/src/mcp/createWodMcpServer.ts`) both consume `DOMAIN_AGENT_TOOLS`, registering a domain tool there automatically exposes it to **Browser WebMCP (`navigator.modelContext`)** and **HTTP/Stdio MCP (`/api/mcp` & `wod mcp`)**.
+   - Wire the matching noun-verb CLI subcommand in `packages/tools/src/cli/agentCommands.ts` and `packages/tools/src/cli/runner.ts` (`--json` + `--server <url>`), and record the exact `cliEquivalent` on the `AgentToolSpec`.
+
+2. **Playground Live UI & Co-Driving Actions (`apps/playground/app/agent/`)**:
+   - Any interactive UI state in `apps/playground` that has no headless equivalent (new routes, view/layout toggles, live editor buffer controls, live workout clock commands, modals/drawers, Cast controls) MUST be exposed to browser agents via `@mcp-b/react-webmcp` (`useWebMCP()`):
+     - **Dynamic Lifecycle**: Register route- or surface-scoped UI tools inside a component that mounts *only* when that UI surface is active (e.g. `StreamAgentTools.tsx`, `EditorAgentTools.tsx`, `LiveClockAgentTools.tsx`) using the zero-dependency bridge in `apps/playground/src/agent/surfaceBridges.ts` so Storybook and the Chromecast receiver bundle (`apps/playground/app/receiver-rpc.tsx`) stay completely free of `@mcp-b/*`.
+     - **Post-Commit Synchronization**: Every UI-mutating WebMCP `execute` handler MUST `await waitForUiCommit()` (`apps/playground/app/agent/uiCommit.ts`) before returning so browser agents never read stale React state.
+     - **Manifest Registration**: Add the schema and `mountScope` entry to `apps/playground/app/agent/uiToolSpecs.ts` (`exportPlaygroundUiToolsManifest()`).
+
+3. **Safety & Risk Tier Discipline**:
+   - **Tier 0 (Read-only)**: Set `tier: 0` and `annotations: { readOnlyHint: true, destructiveHint: false, ... }`. Automatically allowed in `--mcp-readonly` mode.
+   - **Tier 1 (Reversible / Additive)**: Set `tier: 1` and `destructiveHint: false`.
+   - **Tier 2 (Irreversible / Destructive)**: Set `tier: 2` and `destructiveHint: true`, and gate execution with `requireDestructiveConfirmation(ctx, { action, targetId, summary }, args.confirmId)`:
+     - In **Playground WebMCP**, `AgentConfirmHost.tsx` automatically opens the Radix human-in-the-loop confirmation dialog (`data-testid="agent-confirm-dialog"`).
+     - In **CLI**, omitting `--yes <targetId>` automatically exits with code `4` (`CONFIRMATION_REQUIRED`).
+     - In **MCP**, omitting `confirmId` returns a structured confirmation error prompting explicit confirmation.
+
+4. **Deterministic DOM, URL State & Accessibility (Playground Layers 2–4)**:
+   - **Semantic Controls**: Interactive elements MUST be real `<button type="button">` / `<a>` / labeled `<input>` controls (never click-only `<div>`/`<span>` without `role`, `tabIndex`, and `Enter`/`Space` keyboard handlers) and carry `TEST_IDS` (`apps/playground/src/lib/testIds.ts`).
+   - **Loading & View State**: Async routes and streams MUST signal busy transitions via `setSurfaceBusy(loading)` (`apps/playground/src/agent/surfaceBridges.ts`) so `<main data-agent-status="loading|ready" aria-busy>` and `<script id="agent-view-state" type="application/json">` (`apps/playground/app/agent/AgentStateScript.tsx`) stay accurate.
+   - **URL Survival**: New routes go in `apps/playground/src/lib/routes.ts` (`ROUTE_PATTERNS`); meaningful view modes (e.g. `?layout=`, `?q=`, `?note=`) should survive page reload via URL search params.
+   - **Regenerate Discovery Files**: Whenever tools or routes change, run:
+     ```bash
+     bun run sync:agent-manifest
+     bun run sync:skills
+     bun run check:agent-parity
+     ```

package/dist/web/playground/ai-skills/cli.md

@@ -0,0 +1,127 @@
+---
+name: wod-cli
+description: 'Drive WOD Wiki locally or against a running wod server using the wod CLI (--json), wod mcp (stdio), or /api/mcp (HTTP). Covers notes, journal scheduling, notebooks, headless workout sessions, WQL queries, catalog management, and exit code 4 confirmation gates.'
+license: MIT
+---
+
+# WOD CLI & MCP Agent Guide (`wod`)
+
+## Overview
+
+The `wod` CLI exposes every WOD Wiki domain capability with structured `--json` output, deterministic exit codes, and 1:1 parity with the `wod mcp` stdio server and `/api/mcp` HTTP MCP endpoint.
+
+## Quick Diagnostics
+
+```bash
+wod doctor --json
+wod tools list --json
+```
+
+If the local SQLite database is not initialized yet:
+```bash
+wod init --db ./wodwiki.db
+```
+
+To target a running `wod server` instance instead of a local database file, pass `--server <url>` to any noun-verb command:
+```bash
+wod note list --server http://127.0.0.1:3000 --json
+```
+
+---
+
+## Core Workflows
+
+### 1. Parse & Verify Whiteboard Script (Dry Run)
+Always validate authored workout syntax before saving when drafting from unstructured text:
+```bash
+printf "(21-15-9)\n  Thrusters @95lb\n  Pull-ups\n" | wod parse - --no-save --json
+```
+
+### 2. Author, Read, Clone, and Delete Notes
+```bash
+# List notes (optional filters: --notebook, --tag, --search, --limit)
+wod note list --limit 20 --json
+
+# Create a note from inline Markdown or stdin
+wod note create --title "Fran" --tags "benchmark,girl" --markdown $'# Fran\n\n```time\n(21-15-9)\n  Thrusters @95lb\n  Pull-ups\n```' --json
+
+# Read full note Markdown, blocks, and recent sessions
+wod note get <noteId> --json
+
+# Clone a template note onto a calendar date
+wod note clone <sourceNoteId> --date 2026-11-11 --notebook journal --json
+
+# Delete a note (Tier 2 — requires --yes <noteId>, exits 4 if omitted)
+wod note delete <noteId> --yes <noteId> --json
+```
+
+### 3. Schedule & Inspect the Daily Journal
+```bash
+# Read scheduled workouts + logged sessions for a date (YYYY-MM-DD or today)
+wod journal day today --json
+
+# Schedule a new workout or clone a template onto a date
+wod journal add today --source-note <templateNoteId> --json
+wod journal add 2026-11-12 --title "Morning 5K" --markdown $'```time\n5000m Run :?\n```' --json
+```
+
+### 4. Manage Notebooks
+```bash
+wod notebook list --json
+wod notebook save strength-cycle --title "Strength Cycle" --description "8-week squat block" --json
+wod notebook delete strength-cycle --yes strength-cycle --json
+```
+
+### 5. Execute Headless Sessions & Inspect Ledgers
+```bash
+# Run a saved note's workout block headlessly and record session + events
+wod session run --note <noteId> --json
+# Equivalent shorthand on legacy verb:
+wod run --note <noteId> --json
+
+# List and inspect recorded sessions
+wod session list --limit 10 --json
+wod session get <sessionId> --json
+
+# Delete a recorded session (Tier 2 — requires --yes <sessionId>)
+wod session delete <sessionId> --yes <sessionId> --json
+```
+
+### 6. Catalog & Tag Management
+```bash
+wod catalog lookup effort --search thruster --json
+wod catalog upsert effort "Dumbbell Snatch" --category weightlifting --tags dumbbell --json
+wod tag list --type equipment --json
+wod tag upsert kettlebell --type equipment --json
+```
+
+### 7. Feeds & Portability
+```bash
+wod feed list --json
+wod feed status --json
+wod export note <noteId> -o -
+```
+
+---
+
+## Exit Codes & Confirmation Safety
+
+| Exit Code | Meaning | Agent Recovery Action |
+|---|---|---|
+| `0` | Success | Parse JSON stdout (`{ "ok": true, "tool": "...", "data": ... }`). |
+| `1` | Runtime / IO / Missing Target | Inspect `error` field and verify IDs via `list` / `lookup`. |
+| `2` | Syntax Error (Whiteboard Script or WQL) | Fix script or query syntax using `wod parse --no-save` or `wod query --validate-only`. |
+| `3` | Language Pack Load Error | Check `--pack` module specifier. |
+| `4` | Tier 2 Confirmation Required | Destructive command lacked `--yes <targetId>`. Confirm intent with the user before re-running with `--yes <targetId>`. |
+
+---
+
+## Starting the Official MCP Server
+
+- **Stdio (Claude Code / Cursor / Codex)**:
+  ```bash
+  wod mcp --db ./wodwiki.db
+  wod mcp --readonly --db ./wodwiki.db
+  ```
+- **HTTP Streamable MCP**:
+  `wod server` automatically mounts `/api/mcp` (`POST`, `GET`, `DELETE`) and `/.well-known/agent-capabilities.json`. Set `WOD_MCP_READONLY=1` or `--mcp-readonly` to expose only Tier 0 read-only tools, and `WOD_MCP_TOKEN=<secret>` to require `Authorization: Bearer <secret>`.

package/dist/web/playground/ai-skills/wql.md

@@ -0,0 +1,63 @@
+---
+name: wod-wql
+description: 'Write, validate, and execute WQL (Workout Query Language) find and aggregate queries against WOD Wiki notes, workout blocks, sessions, efforts, tags, and time windows.'
+license: MIT
+---
+
+# WQL (Workout Query Language) Agent Guide
+
+## Overview
+
+WQL queries structured workout notes, immutable block revisions, movement efforts, tags, and recorded execution sessions across all three WOD Wiki surfaces:
+- **CLI**: `wod query '<wql>' --format json` (dry-run syntax check: `wod query '<wql>' --validate-only --json`)
+- **MCP / WebMCP**: `wod_query_wql` and `wod_validate_wql`
+- **Browser Stream Views**: `ui_set_stream_query`
+
+---
+
+## Query Families
+
+### 1. Find Queries (`:<target>{...}`)
+Select entities matching structured filters:
+
+| Target | Purpose | Example |
+|---|---|---|
+| `:note` | Workout & journal notes | `:note{notebook:journal time:14d}` |
+| `:block` | Individual `time` / `log` workout blocks | `:block{effort:thrusters}` |
+| `:session` | Completed or logged workout sessions | `:session{time:30d}` |
+| `:effort` | Canonical movement / exercise definitions | `:effort{discipline:weightlifting}` |
+| `:notebook` | Local and subscribed notebooks | `:notebook{}` |
+| `:tag` | Tags across categories | `:tag{}` |
+| `:equipment` | Equipment definitions & tags | `:equipment{}` |
+
+Common filters inside `{...}`:
+- `notebook:<slug>` — filter notes in a notebook (`journal`, `benchmarks`, etc.)
+- `tags:<slug>` — filter by tag
+- `effort:<slug>` — filter notes/blocks/sessions involving a movement
+- `time:<window>` — relative time window (`7d`, `14d`, `30d`, `90d`, `1y`) or ISO date range
+
+### 2. Aggregate Queries (`:<agg>{...} [by {<dim>}]`)
+Roll up recorded workout metrics over time or movement dimensions:
+
+- **Aggregators**: `:sum`, `:count`, `:max`, `:min`, `:avg`
+- **Metric families**: `metric:reps`, `metric:weight`, `metric:distance`, `metric:time`, `metric:rounds`, `metric:volume`
+- **Grouping dimensions (`by {...}`)**: `day`, `week`, `month`, `effort`, `notebook`
+
+Examples:
+```wql
+:sum{metric:reps time:30d} by {week}
+:sum{metric:reps effort:pull-ups time:90d} by {week}
+:max{metric:weight effort:back-squat time:1y}
+:count{metric:rounds time:30d} by {effort}
+```
+
+---
+
+## Best Practices for Agents
+
+1. **Validate Before Running Unfamiliar Filters**:
+   Call `wod_validate_wql` (or `wod query '<wql>' --validate-only --json`) to inspect parsed AST and catch unknown filter keys (exit code `2` on invalid WQL).
+2. **Read Live Capabilities**:
+   Read MCP resource `wod://schema/wql` for the exact list of valid filter keys per target, aggregators, and virtual dimensions compiled into the current engine version.
+3. **Prefer Unbatched Data Tools Over UI Scraping**:
+   In the browser, `wod_query_wql` queries IndexedDB / `ApiStorage` directly without UI pagination limits, whereas `ui_set_stream_query` updates the visible stream for the human user.