@bitcobblers/wod-wiki-tools 0.53.2204 → 0.55.2206

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.