{"owner":"XiaomiMiMo","repo":"MiMo-Code","hasSkills":true,"totalSkillsCount":92,"totalTokensCount":158140,"categories":["anthropic-skill","root-instruction","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/drive-mimo/SKILL.md",".agents/skills/effect/SKILL.md","AGENTS.md","packages/cli/README.md","packages/cli/src/acp/README.md","packages/cli/src/provider/sdk/copilot/README.md","packages/cli/src/skill/builtin/.bundle/arxiv/SKILL.md","packages/cli/src/skill/builtin/.bundle/claude-code/SKILL.md","packages/cli/src/skill/builtin/.bundle/codex/SKILL.md","packages/cli/src/skill/builtin/.bundle/compose-next/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/analyze-data-quality/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/build-dashboard/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/build-report/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/build-report/report-to-google-doc/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/build-report/report-to-google-slides/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/build-report/report-to-pdf/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/create-data-context/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/design-kpis/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/gather-business-context/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/index/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/jupyter-notebooks/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/kpi-reporting/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/market-sizing/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/metric-diagnostics/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/product-business-analysis/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/validate-data/SKILL.md","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/visualize-data/SKILL.md","packages/cli/src/skill/builtin/.bundle/deep-research/SKILL.md","packages/cli/src/skill/builtin/.bundle/docx-official/README.md","packages/cli/src/skill/builtin/.bundle/docx-official/SKILL.md","packages/cli/src/skill/builtin/.bundle/grok-build/SKILL.md","packages/cli/src/skill/builtin/.bundle/html-to-video-pipeline/SKILL.md","packages/cli/src/skill/builtin/.bundle/learn-everything/SKILL.md","packages/cli/src/skill/builtin/.bundle/loop/SKILL.md","packages/cli/src/skill/builtin/.bundle/mate/SKILL.md","packages/cli/src/skill/builtin/.bundle/memory-search/SKILL.md","packages/cli/src/skill/builtin/.bundle/mimocode-docs/SKILL.md","packages/cli/src/skill/builtin/.bundle/modern-python-toolchain/SKILL.md","packages/cli/src/skill/builtin/.bundle/pdf-official/README.md","packages/cli/src/skill/builtin/.bundle/pdf-official/SKILL.md","packages/cli/src/skill/builtin/.bundle/playwright/SKILL.md","packages/cli/src/skill/builtin/.bundle/pptx-official/SKILL.md","packages/cli/src/skill/builtin/.bundle/product-design/SKILL.md","packages/cli/src/skill/builtin/.bundle/product-design/workflows/audit/SKILL.md","packages/cli/src/skill/builtin/.bundle/product-design/workflows/design-qa/SKILL.md","packages/cli/src/skill/builtin/.bundle/product-design/workflows/get-context/SKILL.md","packages/cli/src/skill/builtin/.bundle/product-design/workflows/ideate/SKILL.md","packages/cli/src/skill/builtin/.bundle/product-design/workflows/image-to-code/SKILL.md","packages/cli/src/skill/builtin/.bundle/product-design/workflows/index/SKILL.md","packages/cli/src/skill/builtin/.bundle/product-design/workflows/share/SKILL.md","packages/cli/src/skill/builtin/.bundle/product-design/workflows/url-to-code/SKILL.md","packages/cli/src/skill/builtin/.bundle/product-design/workflows/user-context/SKILL.md","packages/cli/src/skill/builtin/.bundle/research-paper-writing/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/analyze-account-signals/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/answers-ask-user-input/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/apollo/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/build-business-case/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/build-competitive-brief/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/enrich-company-and-contact-data/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/find-customer-quotes/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/find-key-internal-sources/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/follow-up-after-call/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/get-rep-call-feedback/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/hubspot/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/index/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/plan-deal-strategy/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/prepare-for-meeting/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/prioritize-accounts/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/review-forecast/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/review-rep-call-trends/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/sales-company-research/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/salesforce/SKILL.md","packages/cli/src/skill/builtin/.bundle/sales/workflows/zoominfo/SKILL.md","packages/cli/src/skill/builtin/.bundle/skill-creator/SKILL.md","packages/cli/src/skill/builtin/.bundle/super-research/README.md","packages/cli/src/skill/builtin/.bundle/super-research/SKILL.md","packages/cli/src/skill/builtin/.bundle/super-research/evals/toy_bench/README.md","packages/cli/src/skill/builtin/.bundle/super-research/evals/toy_dataset/README.md","packages/cli/src/skill/builtin/.bundle/super-research/evals/toy_pipeline/README.md","packages/cli/src/skill/builtin/.bundle/super-research/evals/toy_regression/README.md","packages/cli/src/skill/builtin/.bundle/super-research/evals/toy_repo/README.md","packages/cli/src/skill/builtin/.bundle/xlsx-official/README.md","packages/cli/src/skill/builtin/.bundle/xlsx-official/SKILL.md","packages/cli/src/sync/README.md","packages/cli/test/AGENTS.md","packages/cli/test/fixture/skills/agents-sdk/SKILL.md","packages/cli/test/fixture/skills/agents-sdk/references/callable.md","packages/cli/test/fixture/skills/cloudflare/SKILL.md","packages/cli/test/fixture/skills/index.json","packages/cli/test/fixture/skills/llm-endpoint-demo/SKILL.md"],"skills":{".agents/skills/drive-mimo/SKILL.md":"---\nname: drive-mimo\ndescription: Use when developing or testing the MiMoCode repository and you need to programmatically drive another MiMoCode (mimo) process. Supports headless `mimo run` with JSON events and interactive TUI via tmux for behavior, integration, and visual regression testing. Covers an installed `mimo` binary or a dev build launched from source with `bun dev`; do not use it for ordinary MiMoCode task execution.\n---\n\n# Drive MiMo\n\n## Overview\n\nTwo **interfaces** for driving a separate mimo process:\n\n| Interface | Command | Use when |\n|------|---------|----------|\n| **Headless** | `mimo run --format json` | Scripted tasks, CI, event validation |\n| **TUI** | `mimo` in tmux | Interactive flow, permission dialogs, keybindings, visual regression |\n\n**Core principle:** Every run produces parseable evidence. No eyeballing.\n\nAlways drive an *isolated* instance: give each run a fresh `MIMOCODE_HOME` and a throwaway workspace so it never touches your own config, memory, or session DB.\n\n### Two ways to launch — orthogonal to interface\n\nThe interface (headless vs TUI, above) is *what you drive*. How the process is\n**launched** is a separate axis — either can be launched either way:\n\n| Launcher | Command | Use when |\n|----------|---------|----------|\n| **Installed binary** | `mimo …` | Testing a released/installed build |\n| **Dev (from source)** | `bun dev …` | Debugging mimocode itself — runs `src/index.ts` directly, no build step, picks up local code changes |\n\nEverything below uses `mimo` for brevity. To drive a **dev build** instead,\nsubstitute `bun dev` for `mimo` and run from the repo root — every flag,\nJSON event, and tmux technique is identical. See the Dev Mode section.\n\n## Prerequisites\n\n```bash\n# mimo binary must be on PATH (installed-binary launcher)\nwhich mimo || echo \"mimo not found on PATH\"\n\n# OR: dev launcher — run from the mimocode repo root, needs bun\nwhich bun || echo \"bun not found — needed for dev mode\"\n\n# tmux (for TUI interface)\nwhich tmux || echo \"tmux not found — install it for TUI mode\"\n```\n\n> **Running the `wait-for-text.sh` helper:** invoke it as\n> `./scripts/wait-for-text.sh …` from this skill's directory. The repository copy\n> is executable and can be called directly.\n\n---\n\n## Dev Mode (debugging mimocode itself)\n\nWhen the goal is to debug **mimocode's own code**, launch from source with\n`bun dev` instead of the installed `mimo` binary. It runs\n`packages/cli/src/index.ts` directly — no build step — so local edits take\neffect on the next launch.\n\n**Key facts:**\n\n- Run from the **repo root**. `bun dev` == `bun run dev`.\n- It is the dev equivalent of the `mimo` command: same CLI, same subcommands\n and flags. `bun dev --help`, `bun dev run …`, `bun dev serve`, etc.\n- Args pass straight through, so **both interfaces work under dev**:\n - Headless: `bun dev run --format json --dangerously-skip-permissions …`\n - TUI: `bun dev ` (positional workspace arg, as with `mimo`)\n- If `MIMOCODE_HOME` is not set, dev defaults it to a repo-local `.dev-home`\n dir. For an isolated driven run, set `MIMOCODE_HOME=$(mktemp -d)` explicitly\n just like with the binary.\n\n**Substitution rule:** anywhere Part 1 / Part 2 / Part 3 below say `mimo`,\nreplace it with `bun dev` (invoked from the repo root) to drive a dev build.\n\n```bash\n# Headless, dev build (from repo root)\nREPO=/path/to/mimocode/checkout # your local mimocode repo root\nMIMOCODE_HOME=$(mktemp -d) bun --cwd \"$REPO\" dev run \\\n --format json --dangerously-skip-permissions --dir \"$WORKSPACE\" \\\n < \"$PROMPT\" > /tmp/mimo-dev.jsonl 2>&1\n\n# TUI, dev build in tmux (from repo root)\ntmux new-session -d -s \"$SESSION\" -x 120 -y 30 \\\n \"cd $REPO && MIMOCODE_HOME=$(mktemp -d) MIMOCODE_PURE=true bun dev $WORKSPACE; sleep 999\"\n```\n\n---\n\n## Part 1: Headless Mode (`mimo run`)\n\n### Launch\n\n```bash\nPROMPT=$(mktemp -t mimo-drive.XXXXXX)\ncat >\"$PROMPT\" <<'EOF'\nYour task here.\nEOF\n\nMIMOCODE_HOME=$(mktemp -d) mimo run \\\n --format json \\\n --dangerously-skip-permissions \\\n --dir \"$WORKSPACE\" \\\n < \"$PROMPT\" > /tmp/mimo-out.jsonl 2>&1\n\nEXIT=$?\n```\n\n### Key flags\n\n| Flag | Purpose |\n|------|---------|\n| `--format json` | Structured JSONL events to stdout |\n| `--dangerously-skip-permissions` | Auto-approve all permissions |\n| `--model provider/model` | Override model |\n| `--session SID` | Continue existing session |\n| `--continue` | Continue last session |\n| `--file path` | Attach file to message |\n| `--dir path` | Working directory |\n\n### JSON event types\n\n`--format json` writes one JSON object per line. **Every** event has the shape\n`{\"type\": ..., \"timestamp\": , \"sessionID\": \"ses_...\", ...payload}` — the\n`sessionID` is a field on each event, not a standalone event. The payload for\nmost events is nested under `part`.\n\nEmitted event types (from the run event stream):\n\n```\n{\"type\":\"step_start\",\"timestamp\":...,\"sessionID\":\"ses_abc\",\"part\":{...}}\n{\"type\":\"text\",\"timestamp\":...,\"sessionID\":\"ses_abc\",\"part\":{\"type\":\"text\",\"text\":\"I'll create the file...\",\"time\":{...}}}\n{\"type\":\"reasoning\",\"timestamp\":...,\"sessionID\":\"ses_abc\",\"part\":{\"type\":\"reasoning\",\"text\":\"The user wants...\"}}\n{\"type\":\"tool_use\",\"timestamp\":...,\"sessionID\":\"ses_abc\",\"part\":{\"type\":\"tool\",\"tool\":\"write\",\"state\":{\"status\":\"completed\",...}}}\n{\"type\":\"step_finish\",\"timestamp\":...,\"sessionID\":\"ses_abc\",\"part\":{...}}\n{\"type\":\"error\",\"timestamp\":...,\"sessionID\":\"ses_abc\",\"error\":{...}}\n```\n\nNotes that matter for parsing:\n\n- **No `session.id`, no `tool_result`, no `session.status` event.** A `tool_use`\n is emitted **once** per tool part when it reaches `completed` or `error` — the\n result/output is inside `part.state`, there is no separate result event.\n- **`tool_use` identifies the tool via `part.tool`** (a bare string, e.g.\n `\"tool\":\"write\"`) — there is no `.tool.name` and no top-level `.name`.\n- **`text` / `reasoning` text lives at `part.text`**, not top-level `.text`.\n- **`reasoning` is only emitted when `--thinking` is passed.** Without it, no\n reasoning events appear.\n- **Completion is not a stream event.** The process finishes when the run\n completes; the reliable completion signal is **process exit** (exit code 0),\n not any line in the JSONL.\n\n### Validation patterns\n\n```bash\n# Completion — the real signal is the exit code, not a stream event\n[ $EXIT -eq 0 ] || echo \"FAIL: exit $EXIT\"\n\n# No errors\ngrep -q '\"type\":\"error\"' /tmp/mimo-out.jsonl && echo \"FAIL: errors found\"\n\n# A specific tool was used (match part.tool, the bare string)\ngrep -q '\"tool\":\"write\"' /tmp/mimo-out.jsonl || echo \"FAIL: write tool not called\"\n\n# Text output contains expected string (text is at .part.text)\ngrep '\"type\":\"text\"' /tmp/mimo-out.jsonl | jq -r '.part.text' | grep -q \"expected\"\n\n# Robust tool check via jq (works regardless of key ordering)\njq -e 'select(.type==\"tool_use\") | .part.tool==\"write\"' /tmp/mimo-out.jsonl >/dev/null \\\n || echo \"FAIL: write tool not called\"\n```\n\n\n### Timeout\n\n```bash\ntimeout 120 mimo run --format json --dangerously-skip-permissions < \"$PROMPT\"\n[ $? -eq 124 ] && echo \"FAIL: timed out\"\n```\n\n---\n\n## Part 2: TUI Mode (tmux)\n\n### Isolation variables\n\n| Variable | Purpose |\n|---|---|\n| `MIMOCODE_HOME` | **Required.** Fresh `mktemp -d` per run. Sandboxes DB, config, cache. |\n| `MIMOCODE_PURE=true` | Disable external plugins. |\n| `MIMOCODE_DISABLE_GIT=true` | Skip git ops if workspace isn't a real repo. |\n\n### Launch TUI in tmux\n\n```bash\n# Create isolated environment\nMHOME=$(mktemp -d)\nWORKSPACE=$(mktemp -d)\nSESSION=\"mimo-drive-$$\"\n\n# Launch mimo TUI in tmux (workspace is a positional arg, NOT --dir)\ntmux new-session -d -s \"$SESSION\" -x 120 -y 30 \\\n \"MIMOCODE_HOME=$MHOME MIMOCODE_PURE=true mimo $WORKSPACE; sleep 999\"\n\n# Wait for the TUI to render its input prompt\nbash scripts/wait-for-text.sh -t \"$SESSION:0.0\" -p \"$PROMPT_RE\" -T 15\n```\n\nWhere `PROMPT_RE` is a language-neutral pattern for the input prompt. The\nprompt placeholder is localized, so match on the stable markers rather than a\nlocalized string:\n\n```bash\n# Matches the prompt line regardless of UI language:\n# the \">\" input caret, the \"Ask\" English placeholder, or a \"/\" command hint\nPROMPT_RE='>|Ask|/[a-z]'\n```\n\nIf a run's UI language is known and fixed, you may match its literal\nplaceholder instead — but prefer the neutral pattern for portability.\n\n### Send input\n\n```bash\n# Type a message (literal text, then Enter)\ntmux send-keys -t \"$SESSION:0.0\" -l -- \"Create a file called hello.txt with content 'world'\"\ntmux send-keys -t \"$SESSION:0.0\" Enter\n\n# Special keys\ntmux send-keys -t \"$SESSION:0.0\" C-c # Cancel\ntmux send-keys -t \"$SESSION:0.0\" C-d # EOF\ntmux send-keys -t \"$SESSION:0.0\" Escape # Escape\ntmux send-keys -t \"$SESSION:0.0\" Tab # Tab completion\ntmux send-keys -t \"$SESSION:0.0\" Up # History up\ntmux send-keys -t \"$SESSION:0.0\" Down # History down\ntmux send-keys -t \"$SESSION:0.0\" Enter # Submit\n```\n\n### Capture output\n\n```bash\n# Current screen\ntmux capture-pane -t \"$SESSION:0.0\" -p\n\n# Full scrollback\ntmux capture-pane -t \"$SESSION:0.0\" -p -S -\n\n# Last 50 lines\ntmux capture-pane -t \"$SESSION:0.0\" -p -S -50\n```\n\n### Wait for state changes\n\n```bash\n# Wait for agent to start processing\nbash scripts/wait-for-text.sh -t \"$SESSION:0.0\" -p \"thinking\\|reading\\|writing\" -T 30\n\n# Wait for tool permission prompt\nbash scripts/wait-for-text.sh -t \"$SESSION:0.0\" -p \"Allow\\|Deny\\|permission\\|approve\" -T 30\n\n# Wait for completion\nbash scripts/wait-for-text.sh -t \"$SESSION:0.0\" -p \"completed\\|done\\|finished\\|idle\" -T 120\n\n# Wait for error\nbash scripts/wait-for-text.sh -t \"$SESSION:0.0\" -p \"error\\|failed\\|Error\" -T 30\n\n# Custom regex\nbash scripts/wait-for-text.sh -t \"$SESSION:0.0\" -p \"hello\\.txt.*world\" -T 30\n```\n\n### Handle permission dialogs\n\n```bash\n# Wait for permission prompt, then approve\nbash scripts/wait-for-text.sh -t \"$SESSION:0.0\" -p \"Allow\\|approve\" -T 30\ntmux send-keys -t \"$SESSION:0.0\" -l -- \"y\"\ntmux send-keys -t \"$SESSION:0.0\" Enter\n\n# Or deny\ntmux send-keys -t \"$SESSION:0.0\" -l -- \"n\"\ntmux send-keys -t \"$SESSION:0.0\" Enter\n```\n\n### Multi-turn interaction\n\n```bash\n# Turn 1: send initial message\ntmux send-keys -t \"$SESSION:0.0\" -l -- \"Create a TypeScript file that adds two numbers\"\ntmux send-keys -t \"$SESSION:0.0\" Enter\nbash scripts/wait-for-text.sh -t \"$SESSION:0.0\" -p \"completed\\|done\" -T 120\n\n# Turn 2: follow-up\ntmux send-keys -t \"$SESSION:0.0\" -l -- \"Now add a test for it\"\ntmux send-keys -t \"$SESSION:0.0\" Enter\nbash scripts/wait-for-text.sh -t \"$SESSION:0.0\" -p \"completed\\|done\" -T 120\n\n# Verify result\ntmux capture-pane -t \"$SESSION:0.0\" -p -S - | grep -i \"pass\\|fail\"\n```\n\n### Cleanup\n\n```bash\ntmux kill-session -t \"$SESSION\" 2>/dev/null\nrm -rf \"$MHOME\" \"$WORKSPACE\"\n```\n\n---\n\n## Part 3: Scenarios\n\n### S1: Smoke (headless)\n\n```bash\ntest_smoke() {\n local P=$(mktemp) MHOME=$(mktemp -d)\n echo \"Say hello\" > \"$P\"\n MIMOCODE_HOME=$MHOME mimo run --format json --dangerously-skip-permissions \\\n < \"$P\" > /tmp/s1.jsonl 2>&1\n local E=$?\n rm -rf \"$MHOME\" \"$P\"\n [ $E -eq 0 ] && grep -q '\"type\":\"text\"' /tmp/s1.jsonl && echo \"PASS\" || echo \"FAIL\"\n}\n```\n\n### S2: Tool use (headless)\n\n```bash\ntest_tool_use() {\n local P=$(mktemp) MHOME=$(mktemp -d) WS=$(mktemp -d)\n echo 'Create file test.txt with content \"hello\"' > \"$P\"\n MIMOCODE_HOME=$MHOME mimo run --format json --dangerously-skip-permissions --dir \"$WS\" \\\n < \"$P\" > /tmp/s2.jsonl 2>&1\n local E=$?\n local OK=true\n [ $E -ne 0 ] && OK=false\n ! grep -q '\"tool\":\"write\"' /tmp/s2.jsonl && OK=false\n [ ! -f \"$WS/test.txt\" ] && OK=false\n rm -rf \"$MHOME\" \"$WS\" \"$P\"\n $OK && echo \"PASS\" || echo \"FAIL\"\n}\n```\n\n### S3: TUI interactive flow\n\n```bash\ntest_tui_interactive() {\n local MHOME=$(mktemp -d) WS=$(mktemp -d) SID=\"mimo-s3-$$\"\n local PROMPT_RE='>|Ask|/[a-z]'\n tmux new-session -d -s \"$SID\" -x 120 -y 30 \"MIMOCODE_HOME=$MHOME MIMOCODE_PURE=true mimo $WS; sleep 999\"\n\n # Wait for prompt\n bash scripts/wait-for-text.sh -t \"$SID:0.0\" -p \"$PROMPT_RE\" -T 15 || { echo \"FAIL: no prompt\"; tmux kill-session -t $SID; return 1; }\n\n # Send task\n tmux send-keys -t \"$SID:0.0\" -l -- \"Create hello.txt with content 'world'\"\n tmux send-keys -t \"$SID:0.0\" Enter\n\n # Wait for completion (agent shows elapsed time like \"· 9.8s\")\n bash scripts/wait-for-text.sh -t \"$SID:0.0\" -p \"· [0-9]\" -T 120 || { echo \"FAIL: no completion\"; tmux kill-session -t $SID; return 1; }\n\n # Verify file\n [ -f \"$WS/hello.txt\" ] && echo \"PASS\" || echo \"FAIL\"\n tmux kill-session -t \"$SID\" 2>/dev/null\n rm -rf \"$MHOME\" \"$WS\"\n}\n```\n\n### S4: TUI permission handling\n\n```bash\ntest_tui_permission() {\n local MHOME=$(mktemp -d) WS=$(mktemp -d) SID=\"mimo-s4-$$\"\n local PROMPT_RE='>|Ask|/[a-z]'\n tmux new-session -d -s \"$SID\" -x 120 -y 30 \"MIMOCODE_HOME=$MHOME MIMOCODE_PURE=true mimo $WS; sleep 999\"\n\n bash scripts/wait-for-text.sh -t \"$SID:0.0\" -p \"$PROMPT_RE\" -T 15\n\n # Ask for something that needs permission (no --dangerously-skip-permissions in TUI)\n tmux send-keys -t \"$SID:0.0\" -l -- \"Run the command: echo hello\"\n tmux send-keys -t \"$SID:0.0\" Enter\n\n # Wait for permission prompt\n bash scripts/wait-for-text.sh -t \"$SID:0.0\" -p \"Allow\\|approve\\|permission\\|y/n\" -T 30 || { echo \"FAIL: no permission prompt\"; tmux kill-session -t $SID; return 1; }\n\n # Approve\n tmux send-keys -t \"$SID:0.0\" -l -- \"y\"\n tmux send-keys -t \"$SID:0.0\" Enter\n\n # Wait for completion\n bash scripts/wait-for-text.sh -t \"$SID:0.0\" -p \"· [0-9]\" -T 60\n\n tmux capture-pane -t \"$SID:0.0\" -p | grep -q \"hello\" && echo \"PASS\" || echo \"FAIL\"\n tmux kill-session -t \"$SID\" 2>/dev/null\n rm -rf \"$MHOME\" \"$WS\"\n}\n```\n\n### S5: TUI keybindings\n\n```bash\ntest_tui_keybindings() {\n local MHOME=$(mktemp -d) WS=$(mktemp -d) SID=\"mimo-s5-$$\"\n local PROMPT_RE='>|Ask|/[a-z]'\n tmux new-session -d -s \"$SID\" -x 120 -y 30 \"MIMOCODE_HOME=$MHOME MIMOCODE_PURE=true mimo $WS; sleep 999\"\n\n bash scripts/wait-for-text.sh -t \"$SID:0.0\" -p \"$PROMPT_RE\" -T 15\n\n # Test Ctrl+C cancels input\n tmux send-keys -t \"$SID:0.0\" -l -- \"some partial input\"\n tmux send-keys -t \"$SID:0.0\" C-c\n\n # Screen should still show prompt (not exit)\n sleep 1\n tmux capture-pane -t \"$SID:0.0\" -p | grep -qE \"$PROMPT_RE\" && echo \"PASS: Ctrl+C didn't exit\" || echo \"FAIL: Ctrl+C exited\"\n\n # Test Escape\n tmux send-keys -t \"$SID:0.0\" Escape\n sleep 0.5\n\n tmux kill-session -t \"$SID\" 2>/dev/null\n rm -rf \"$MHOME\" \"$WS\"\n}\n```\n\n---\n\n## Batch Runner\n\n```bash\nrun_all() {\n local PASS=0 FAIL=0 RESULTS=()\n for fn in test_smoke test_tool_use test_tui_interactive test_tui_permission test_tui_keybindings; do\n echo \"--- $fn ---\"\n if $fn 2>/dev/null; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); RESULTS+=(\"$fn: FAIL\"); fi\n done\n echo \"=== $PASS passed, $FAIL failed ===\"\n [ ${#RESULTS[@]} -gt 0 ] && printf ' %s\\n' \"${RESULTS[@]}\"\n [ $FAIL -eq 0 ]\n}\n```\n\n---\n\n## Quick Reference\n\n| Task | Command |\n|------|---------|\n| Headless run | `MIMOCODE_HOME=$(mktemp -d) mimo run --format json --dangerously-skip-permissions \"prompt\"` |\n| TUI launch | `tmux new-session -d -s test -x 120 -y 30 \"MIMOCODE_HOME=$(mktemp -d) mimo $WORKSPACE; sleep 999\"` |\n| Send text | `tmux send-keys -t test:0.0 -l -- \"text\" && tmux send-keys -t test:0.0 Enter` |\n| Capture screen | `tmux capture-pane -t test:0.0 -p -S -` |\n| Wait for text | `bash scripts/wait-for-text.sh -t test:0.0 -p \"pattern\" -T 30` |\n| Send Ctrl+C | `tmux send-keys -t test:0.0 C-c` |\n| Approve permission | `tmux send-keys -t test:0.0 -l -- \"y\" && tmux send-keys -t test:0.0 Enter` |\n| Cleanup | `tmux kill-session -t test && rm -rf $MHOME` |\n",".agents/skills/effect/SKILL.md":"---\nname: effect\ndescription: Answer questions about the Effect framework\n---\n\n# Effect\n\nThis codebase uses Effect, a framework for writing typescript.\n\n## How to Answer Effect Questions\n\n1. Clone the Effect repository: `https://github.com/Effect-TS/effect-smol` to\n `.opencode/references/effect-smol` in this project NOT the skill folder.\n2. Use the explore agent to search the codebase for answers about Effect patterns, APIs, and concepts\n3. Provide responses based on the actual Effect source code and documentation\n\n## Guidelines\n\n- Always use the explore agent with the cloned repository when answering Effect-related questions\n- Reference specific files and patterns found in the Effect codebase\n- Do not answer from memory - always verify against the source\n","AGENTS.md":"# MiMo-Code\n\n## Conventions\n\n- Use MiMoCode Compose skills when available, otherwise use superpowers skill if installed.\n- To regenerate the JavaScript SDK, run `./packages/sdk/script/build.ts`.\n- ALWAYS USE PARALLEL TOOLS WHEN APPLICABLE.\n- The default branch in this repo is `main`.\n- CI triggers on `main`.\n- Prefer automation: execute requested actions without confirmation unless blocked by missing info or safety/irreversibility.\n- Install deps with `bun ci` (= `bun install --frozen-lockfile`) — install per `bun.lock`, don't mutate the lockfile. ⛔ Do NOT use `bun install`/`npm install`.\n- Comments, docs, shipped skill content and test assertions use synthetic values, never machine-specific ones — `/tmp/example` for paths, `test/model` for model refs, `feat/example` for branches.\n- Do not edit `packages/cli/migration/*/migration.sql` that already shipped — engines have applied those journals; new schema changes get a **new** migration directory under `packages/cli/migration/`.\n\n## Style Guide\n\nMatch the style of the surrounding code. The rules below apply across the repository.\n\n### Types and errors\n\n- Avoid using the `any` type\n- Inside Effect code, express failures through the Effect error channel (`Effect.try`, `Effect.tryPromise`, `Effect.catchTag`, typed errors) rather than `try`/`catch`; plain scripts and non-Effect code may use `try`/`catch`\n\n### Bun and Node runtimes\n\n- Use Bun APIs where the runtime is Bun-only, like `Bun.file()` in the TUI (`src/cli/cmd/tui/`); build-time macros are fine anywhere, as they never reach the shipped runtime\n- In core code reachable from `src/node.ts`, prefer the Node equivalent when one exists — `createHash` over `Bun.CryptoHasher`, `prepare()` over bun:sqlite's `query()` — as that code also ships through `script/build-node.ts` and must run on plain Node\n- Bun-only calls in core escape both `typecheck` and `bun test`, which run on Bun; existing usage needs no urgent removal, and APIs with no Node equivalent may stay until a runtime seam exists\n\n### Config modules\n\nIn `src/config`, follow the existing self-export pattern at the top of the file (for example `export * as ConfigAgent from \"./agent\"`) when adding a new config module.\n\n### Schema Definitions (Drizzle)\n\nUse snake_case for field names so column names don't need to be redefined as strings.\n\n```ts\n// Good\nconst table = sqliteTable(\"session\", {\n id: text().primaryKey(),\n project_id: text().notNull(),\n created_at: integer().notNull(),\n})\n\n// Bad\nconst table = sqliteTable(\"session\", {\n id: text(\"id\").primaryKey(),\n projectID: text(\"project_id\").notNull(),\n createdAt: integer(\"created_at\").notNull(),\n})\n```\n\n### Reading a nullable column\n\nTwo independent absences meet in one expression, and only one of them is\n`undefined`. `.get()` yields `undefined` when no row matches — Drizzle normalises\nthe driver's `null` there — while a nullable column's SQL `NULL` arrives as\n`null`. So `row?.some_column` is `T | null | undefined`.\n\nWhen a caller only asks \"is there a value\", flatten to `undefined`, and write the\nflattening as an annotation rather than an `as` cast:\n\n```ts\n// Good — the compiler enforces it; deleting the `?? undefined` is a type error\nconst boundary: MessageID | undefined = row?.last_checkpoint_message_id ?? undefined\n\n// Bad — the cast removes `null` from the union without converting anything,\n// so the declared type is untrue at runtime\nreturn row?.last_checkpoint_message_id as MessageID | undefined\n```\n\nDiscriminate a possibly-absent value with truthiness or `== null`, never with\n`=== undefined` / `!== undefined`. Because `null !== undefined` is `true`, such a\nguard typechecks, reads correctly in review, and does nothing.\n\n## Testing\n\n- Avoid mocks as much as possible\n- Test actual implementation, do not duplicate logic into tests\n","packages/cli/README.md":"","packages/cli/src/acp/README.md":"","packages/cli/src/provider/sdk/copilot/README.md":"","packages/cli/src/skill/builtin/.bundle/arxiv/SKILL.md":"---\nname: arxiv\ndescription: \"Use this skill whenever the user wants to find, read, cite, track, download, or analyze academic papers on arXiv. That includes: searching papers by topic, author, category, or arXiv ID; fetching abstracts or full metadata; generating BibTeX citations; downloading PDFs; listing the latest submissions in a field (e.g. cs.AI daily digest); checking a paper's citation impact; finding who cites a paper, what it references, or related-paper recommendations. Trigger on mentions of 'arXiv', an arXiv ID (e.g. 2601.02780 or hep-th/0601001), an arxiv.org URL, 'paper search', 'literature review', 'find papers about X', 'cite this paper', or 'what's new in cs.LG'.\"\nversion: 2.0.0\nlicense: MIT\nplatforms: [linux, macos, windows]\n---\n\n# arXiv Research\n\nSearch, read, cite, and analyze academic papers using the free arXiv API and Semantic Scholar API. No API keys, no dependencies — the bundled script uses only the Python stdlib.\n\n## Quick Start: the `arxiv.py` script\n\nPrefer `scripts/arxiv.py` over raw `curl` — it handles Atom XML parsing, versioned IDs, withdrawn-paper detection, and produces clean readable (or `--json`) output.\n\n| Goal | Command |\n|------|---------|\n| Search papers | `python scripts/arxiv.py search \"GRPO reinforcement learning\" --max 10 --sort date` |\n| Filtered search | `python scripts/arxiv.py search \"attention\" --author vaswani --category cs.CL` |\n| Full metadata + abstract | `python scripts/arxiv.py get 2601.02780,1706.03762` |\n| BibTeX citation | `python scripts/arxiv.py bibtex 2601.02780` |\n| Download PDF | `python scripts/arxiv.py download 2601.02780 --dest ./papers` |\n| Latest in a category | `python scripts/arxiv.py new cs.CL --max 10` |\n| Who cites this paper | `python scripts/arxiv.py cites 2601.02780 --max 20` |\n| What this paper cites | `python scripts/arxiv.py refs 2601.02780` |\n| Related-paper recommendations | `python scripts/arxiv.py similar 2601.02780` |\n| Machine-readable output | append `--json` to any command |\n\nCommon flags: `--max N` (result count), `--sort relevance|date|updated`, `--start N` (pagination offset, search only), `--json`.\n\n## Reading Paper Content\n\nAfter finding a paper, read it with the `webfetch` tool:\n\n- Abstract page (fast, metadata + abstract): `https://arxiv.org/abs/2601.02780`\n- Full paper as HTML (best for reading, when available): `https://arxiv.org/html/2601.02780`\n- PDF: `https://arxiv.org/pdf/2601.02780`\n\nIf HTML is unavailable and the PDF must be processed locally, `download` it first, then use a PDF-processing skill.\n\n## Recommended Research Workflows\n\n**Literature review on a topic**\n1. `search \"topic\" --sort date --max 15` — recent work\n2. `search \"topic\" --max 15` — seminal work (relevance-sorted)\n3. Cross-check impact: `python scripts/arxiv.py get ID` then `cites ID --max 5` for citation counts\n4. Read the top candidates via `webfetch` on the abs/html URLs\n5. `bibtex ID1,ID2,...` for the papers you keep\n\n**Deep-dive a single paper**\n1. `get ID` — full abstract, versions, journal ref, DOI\n2. `refs ID` — what it builds on\n3. `cites ID` — follow-up work (sorted by citation count)\n4. `similar ID` — related papers you might have missed\n5. `webfetch` the HTML/PDF for full text\n\n**Stay current in a field**\n- `new cs.AI --max 20` — latest submissions in a category\n- Category taxonomy: https://arxiv.org/category_taxonomy — common ones: `cs.AI`, `cs.CL` (NLP), `cs.CV`, `cs.LG`, `cs.CR`, `stat.ML`, `math.OC`\n\n## Raw API Reference (when the script isn't enough)\n\nThe script covers most needs; use the raw APIs for advanced queries.\n\n### arXiv API (Atom XML)\n\n```bash\ncurl -s \"https://export.arxiv.org/api/query?search_query=all:transformer&max_results=5\"\n```\n\nField prefixes: `all:` (everything), `ti:` (title), `au:` (author), `abs:` (abstract), `cat:` (category), `co:` (comment, e.g. `co:accepted+NeurIPS`).\n\nBoolean syntax (URL-encode spaces as `+`):\n\n```\nall:GPT+OR+all:BERT # OR\nall:language+model+ANDNOT+all:vision # AND NOT\nti:\"chain+of+thought\" # exact phrase\nau:hinton+AND+cat:cs.LG # combined\n```\n\nParameters: `sortBy` (`relevance`|`lastUpdatedDate`|`submittedDate`), `sortOrder`, `start`, `max_results`, `id_list` (comma-separated IDs).\n\n### Semantic Scholar API (JSON)\n\narXiv has no citation data — Semantic Scholar fills that gap (free, ~1 req/sec unauthenticated).\n\n```bash\n# Paper details with citation counts\ncurl -s \"https://api.semanticscholar.org/graph/v1/paper/arXiv:2601.02780?fields=title,citationCount,influentialCitationCount,tldr\"\n\n# Author profile\ncurl -s \"https://api.semanticscholar.org/graph/v1/author/search?query=Yann+LeCun&fields=name,hIndex,citationCount,paperCount\"\n\n# Keyword search returning JSON (alternative to arXiv search)\ncurl -s \"https://api.semanticscholar.org/graph/v1/paper/search?query=GRPO&limit=5&fields=title,year,citationCount,externalIds\"\n```\n\nUseful fields: `title`, `authors`, `year`, `abstract`, `tldr` (AI summary), `citationCount`, `influentialCitationCount`, `isOpenAccess`, `openAccessPdf`, `fieldsOfStudy`, `publicationVenue`, `externalIds` (arXiv ID, DOI).\n\n## Important Details\n\n**Rate limits** — arXiv: ~1 request / 3 seconds; Semantic Scholar: ~1 request / second. Space out consecutive calls; the script exits with a clear message on HTTP 429.\n\n**ID formats** — new style `2402.03300`, old style `hep-th/0601001`. Both work everywhere.\n\n**Versioning** — `arxiv.org/abs/2601.02780` resolves to the latest version; `...v2` is a specific immutable version. `bibtex` and `download` preserve the version suffix so citations match the content you actually read (later versions can change substantially).\n\n**Withdrawn papers** — the script flags entries whose abstract indicates withdrawal/retraction with `[WITHDRAWN]`. Don't cite these without noting the status.\n\n**Listings caveat** — `new CATEGORY` sorts by submission date via the search API; the official \"new today\" listing at `https://arxiv.org/list/cs.AI/new` may group slightly differently (cross-lists, replacements).\n","packages/cli/src/skill/builtin/.bundle/claude-code/SKILL.md":"---\nname: claude-code\ndescription: \"Operate Claude Code CLI (v2.1+) via the terminal only when the user explicitly requests Claude Code or names this skill. Covers print mode (-p), interactive tmux sessions, and background (--bg) orchestration.\"\nversion: 2.0.0\nlicense: MIT\nplatforms: [linux, macos, windows]\n---\n\n# Claude Code Delegation\n\nDelegate coding work to Claude Code, Anthropic's autonomous coding agent CLI.\n\n**Setup (once):** `npm install -g @anthropic-ai/claude-code && claude auth login` · verify with `claude auth status` / `claude doctor`. CI token: `claude setup-token`. Full auth/install variants → `references/flags.md`.\n\n**Platform check (before running anything):** detect the OS first. All shell examples in this skill are POSIX (bash). Linux/macOS run them as-is. On **Windows**, run Claude Code natively in PowerShell/Git Bash for print and background modes, but interactive tmux orchestration requires **WSL**. Shell-syntax translation table (quoting, env vars, piping, paths) → `references/platforms.md`.\n\n## Mode Selection (decide FIRST)\n\n| Task shape | Mode | Why |\n|---|---|---|\n| One-shot task: fix bug, add feature, review diff, extract data | **Print `-p`** ← default | No PTY, no dialogs, structured output |\n| Multi-turn iterate: refactor → review → fix → test; needs slash commands | **Interactive tmux** → `references/interactive-tmux.md` | Full REPL, requires dialog handling |\n| Long-running, shouldn't block; large fan-out supervision | **Background `--bg`** | Native supervision via `claude agents` |\n| High-stakes PR review | **`claude ultrareview [pr#]`** | Cloud multi-agent, exit-code driven (uploads diff to cloud — never on branches with secrets) |\n\nDo NOT hand-roll tmux fan-outs for parallel work — prefer `--bg` + `claude agents --json --all`.\n\n## Print Mode (the 90% path)\n\n```\nterminal(command=\"claude -p 'Fix the auth bug in src/auth.py' \\\n --allowedTools 'Read,Edit' --max-turns 10 --output-format json\",\n workdir=\"/path/to/project\", timeout=180)\n```\n\n**Always set:** `workdir` · `--max-turns` (5–10; print-mode only) · `--allowedTools` (least privilege: `Read,Edit,Write,Bash`, patterns like `Bash(git *)`).\n\n**JSON result fields:** `result` (text) · `session_id` (for resume) · `subtype` (`success` | `error_max_turns` | `error_budget`) · `total_cost_usd` · `num_turns` · `structured_output` (with `--json-schema`).\n\n**Common variants:**\n\n```bash\ngit diff main... | claude -p 'Review for bugs' --max-turns 1 # pipe input, cheapest review\nclaude -p 'Continue: add pooling' --resume # resume; --continue = latest in cwd; --fork-session = branch\nclaude -p 'List functions' --output-format json --json-schema '' --max-turns 5 # structured extraction (needs turns to read files)\nclaude --bare -p 'task' --settings ci.json # CI: skips hooks/plugins/CLAUDE.md; auth = ANTHROPIC_API_KEY only\nclaude -p 'task' --max-budget-usd 0.50 --fallback-model haiku # cost cap (min ~$0.05) + overload fallback\n```\n\nStreaming, stream-json events, bidirectional input, cache-reuse (`--exclude-dynamic-system-prompt-sections`) → `references/print-mode.md`.\n\n## Background Mode\n\n```bash\nclaude --bg 'investigate flaky test in tests/api.test.ts' # NOT compatible with -p\nclaude agents --json --all # list/inspect\nclaude attach | logs | stop | respawn | rm \n```\n\n## Guardrails & Gotchas (violations break agents)\n\n1. **`-p` auto-skips trust/permission dialogs** (any non-TTY does) — only run in trusted directories.\n2. **Interactive mode = tmux required** (Windows: only inside WSL — never attempt tmux in PowerShell/cmd; fall back to `-p` or `--bg`); two startup dialogs, and the `--dangerously-skip-permissions` dialog defaults to **\"No, exit\"** (must send `Down` then `Enter`). Full patterns → `references/interactive-tmux.md`.\n3. **Session resume is per-directory** — `--continue` only finds sessions from the same cwd.\n4. **Slash commands don't work in `-p`** — describe the task in natural language instead.\n5. **Context >70% degrades quality** — in interactive sessions monitor `/context`, use `/compact`.\n6. **Clean up**: kill tmux sessions and `claude stop/rm` background sessions when done.\n7. **Don't kill slow sessions** — capture progress first (`tmux capture-pane` / `claude logs`).\n8. **Report back**: after completion, summarize what changed (use the JSON `result` + `git diff`).\n\n## References (read on demand)\n\n| File | Read when |\n|---|---|\n| `references/print-mode.md` | Streaming output, stream-json events, piping, schemas, session mgmt, cache reuse |\n| `references/interactive-tmux.md` | Any tmux/PTY session: dialogs, send-keys, monitoring, slash commands, shortcuts |\n| `references/flags.md` | Full CLI flag & subcommand tables, auth variants, env vars, model/effort selection |\n| `references/config.md` | CLAUDE.md/memory, settings hierarchy, custom agents, hooks, MCP, plugins, project purge |\n| `references/platforms.md` | Running on Windows (PowerShell/Git Bash/WSL) or macOS: shell translation, paths, per-OS gotchas |\n","packages/cli/src/skill/builtin/.bundle/codex/SKILL.md":"---\nname: codex\ndescription: Run, configure, and troubleshoot OpenAI Codex CLI in non-interactive headless environments. Use for Codex automation in Bash or PowerShell, native Windows or WSL2, shell scripts, CI/CD, Docker, Kubernetes, remote servers, agent harnesses, or batch jobs; for constructing `codex exec` commands; selecting sandbox and approval modes; consuming JSONL events or structured output; resuming sessions; passing prompts through stdin; and handling failures caused by unavailable interactive input such as `request_user_input`.\n---\n\n# Codex CLI\n\nUse Codex CLI as a deterministic, non-interactive worker suitable for automation and agent orchestration.\n\n## Operating Rules\n\n1. Use `codex exec`, not the interactive `codex` TUI.\n2. Pass the task as the positional `PROMPT` argument. Do not use `-p` for the prompt; `-p` selects a profile.\n3. For ordinary unattended code changes, prefer:\n\n```bash\ncodex exec \\\n -C /path/to/repo \\\n --sandbox workspace-write \\\n --ask-for-approval never \\\n \"\"\n```\n\n4. Use `--yolo` only inside an externally hardened and disposable runner. It disables Codex approvals and sandboxing.\n5. For harnesses and CI, prefer `--json` plus `--output-last-message`.\n6. Do not make the run depend on a human answering questions. Resolve ambiguity using repository evidence and conservative defaults.\n7. Treat credentials as secrets. Inject `CODEX_API_KEY` only into the single `codex exec` process when possible.\n8. Before giving version-sensitive advice, inspect `codex exec --help` or current official Codex documentation if available.\n9. On Windows, choose one execution environment per task: native PowerShell for Windows toolchains or WSL2 for Linux toolchains. Do not casually mix paths, installations, or authentication across them.\n\n## Choose the Execution Mode\n\n### Read-only analysis\n\nUse when the task must not modify files:\n\n```bash\ncodex exec \\\n -C /path/to/repo \\\n --sandbox read-only \\\n --ask-for-approval never \\\n \"Analyze the repository and report risks. Do not modify files.\"\n```\n\n### Workspace-scoped implementation\n\nUse as the default for autonomous repository work:\n\n```bash\ncodex exec \\\n -C /path/to/repo \\\n --sandbox workspace-write \\\n --ask-for-approval never \\\n \"Implement the task, run relevant tests, and report unresolved blockers.\"\n```\n\n### Externally isolated unrestricted execution\n\nUse only when the enclosing container, VM, or sandbox enforces the real security boundary:\n\n```bash\ncodex exec \\\n -C /workspace/repo \\\n --yolo \\\n \"Implement the task and validate the result.\"\n```\n\nNever recommend `--yolo` on a normal developer machine or a runner containing unrelated secrets, host mounts, SSH keys, cloud credentials, or a Docker socket.\n\n## Construct an Autonomous Prompt\n\nWhen headless execution could encounter choices, prepend these instructions:\n\n```text\nWork fully autonomously.\n\nDo not ask the user questions and do not request interactive input.\nInspect the repository and available context before making assumptions.\nWhen several valid approaches exist, choose the option that:\n1. minimizes unrelated changes,\n2. preserves backward compatibility,\n3. introduces the fewest new dependencies,\n4. avoids destructive or irreversible actions.\n\nContinue until the task is complete or a concrete blocking error is reached.\nRecord assumptions, validation performed, and unresolved blockers in the final response.\n```\n\nDo not simulate \"always select the first option.\" Option ordering is not a safety or quality policy. Apply the explicit decision rules above instead.\n\n## Handle `request_user_input` Failures\n\nWhen Codex reports that `request_user_input` is unavailable in Default mode or non-interactive mode:\n\n1. Confirm the invocation uses `codex exec` and is intentionally headless.\n2. Add the autonomous prompt policy above.\n3. Supply missing decisions in the task prompt or `AGENTS.md` when they are known in advance.\n4. Replace open-ended requests such as \"ask me which approach\" with deterministic selection criteria.\n5. If the choice is safety-critical, destructive, or impossible to infer, make the run fail clearly rather than selecting randomly.\n6. Do not attempt to emulate terminal keystrokes unless the subprocess itself, rather than Codex, requires input and the workflow explicitly defines the safe answer.\n\n## Pass Prompts and Context\n\nUse a direct positional prompt:\n\n```bash\ncodex exec \"Summarize the repository structure.\"\n```\n\nRead the prompt from stdin:\n\n```bash\ncodex exec - < prompt.md\n```\n\nPipe dynamic context while retaining an explicit task:\n\n```bash\nnpm test 2>&1 | codex exec \"Analyze this test output and fix the repository.\"\n```\n\nUse `--skip-git-repo-check` only for intentional one-off directories outside Git:\n\n```bash\ncodex exec \\\n --skip-git-repo-check \\\n -C /tmp/task \\\n \"Analyze the files in this directory.\"\n```\n\n## Produce Harness-Friendly Output\n\n### Capture only the final message\n\n```bash\ncodex exec \\\n -C /workspace/repo \\\n --output-last-message /output/final.md \\\n \"Review the codebase.\"\n```\n\n### Stream JSONL events\n\n```bash\ncodex exec \\\n -C /workspace/repo \\\n --json \\\n --sandbox workspace-write \\\n --ask-for-approval never \\\n \"Run tests and fix failures.\" \\\n > /output/events.jsonl\n```\n\nExpect event families such as `thread.started`, `turn.started`, `turn.completed`, `turn.failed`, `item.*`, and `error`.\n\n### Capture events and the final answer together\n\n```bash\ncodex exec \\\n -C /workspace/repo \\\n --json \\\n --sandbox workspace-write \\\n --ask-for-approval never \\\n --output-last-message /output/final.md \\\n \"Complete the task autonomously.\" \\\n | tee /output/events.jsonl\n```\n\nDo not parse human-readable progress text when `--json` is available.\n\n## Require Structured Final Output\n\nCreate a JSON Schema and pass it with `--output-schema`:\n\n```bash\ncodex exec \\\n -C /workspace/repo \\\n --sandbox workspace-write \\\n --ask-for-approval never \\\n --output-schema /input/result.schema.json \\\n --output-last-message /output/result.json \\\n \"Implement the task, validate it, and return the requested structured result.\"\n```\n\nA useful harness schema usually includes:\n\n- `status`: `success`, `partial`, or `failed`\n- `summary`: concise outcome\n- `changed_files`: repository-relative paths\n- `validation`: commands run and results\n- `assumptions`: decisions made without user input\n- `blockers`: concrete unresolved problems\n\nSet `additionalProperties` to `false` when downstream parsing must be strict.\n\n## Resume or Avoid Persistence\n\nResume the most recent session for the current working directory:\n\n```bash\ncodex exec resume --last \"Continue the previous task and fix remaining issues.\"\n```\n\nResume a specific session:\n\n```bash\ncodex exec resume \"$SESSION_ID\" \"Continue with the next stage.\"\n```\n\nUse an ephemeral run when rollout persistence is undesirable:\n\n```bash\ncodex exec --ephemeral \"Analyze the repository.\"\n```\n\nDo not rely on `--last` across unrelated working directories unless deliberately using the relevant all-directory option supported by the installed CLI.\n\n## Authenticate Safely\n\nFor a local interactive login:\n\n```bash\ncodex login\n```\n\nFor a headless machine with device-code login enabled:\n\n```bash\ncodex login --device-auth\n```\n\nFor a single automated invocation:\n\n```bash\nCODEX_API_KEY=\"$OPENAI_API_KEY\" \\\ncodex exec --json \"Triage the repository.\"\n```\n\nDo not expose API keys as broad job-level environment variables in jobs that execute repository-controlled code. Never commit or print `~/.codex/auth.json`.\n\n## Windows, PowerShell, and WSL2\n\nFor native Windows headless use:\n\n- Install with the official PowerShell installer or npm.\n- Prefer PowerShell 7.4 or newer for JSONL redirection.\n- Build argument arrays and invoke them with `& codex @args`; avoid fragile backtick-heavy command construction.\n- Check `$LASTEXITCODE` after every Codex invocation. PowerShell error preferences alone are not a substitute for checking a native process exit code.\n- Keep stdout JSONL separate from stderr diagnostics. Do not use `2>&1` when stdout must remain parseable JSONL.\n- Configure `%USERPROFILE%\\.codex\\config.toml` with `[windows] sandbox = \"elevated\"` when available; use `unelevated` only as the fallback.\n- Preserve the task-level policy `--sandbox workspace-write --ask-for-approval never` for ordinary autonomous edits. The native Windows sandbox implementation and the CLI task policy are separate controls.\n\nFor WSL:\n\n- Use WSL2, not WSL1.\n- Install and authenticate Codex inside WSL as a Linux installation.\n- Keep repositories under `~/code/...`, not `/mnt/c/...`, for better performance and fewer permission, symlink, and file-watcher problems.\n- Do not pass credentials through visible `wsl.exe` command-line strings.\n\nSee [references/windows.md](references/windows.md) for installation, PowerShell wrappers, JSONL parsing, sandbox configuration, WSL2 patterns, and Windows-specific troubleshooting.\n\n## Container and CI Requirements\n\nWhen generating a Docker, Kubernetes, or CI design:\n\n- Mount only the intended workspace and output directory.\n- Run as a non-root user when practical.\n- Do not mount the host Docker socket.\n- Do not mount home directories, SSH keys, or cloud credential directories.\n- Restrict network access unless the task explicitly needs it.\n- Apply CPU, memory, process, and execution-time limits outside Codex.\n- Preserve stdout, stderr, exit status, JSONL events, and the final message separately.\n- Validate repository diffs and test results before treating a run as successful.\n- Prefer a fresh worktree or disposable checkout per task.\n\nSee [references/recipes.md](references/recipes.md) for ready-to-use shell, Docker, CI, and parser patterns.\n\n## Diagnose Failures\n\nUse this order:\n\n1. Run `codex --version` and `codex exec --help`.\n2. Verify the command uses a positional prompt or `-` for stdin.\n3. Verify the working directory and Git repository status.\n4. Verify authentication without printing secret material.\n5. Check whether sandbox policy blocks required reads, writes, commands, sockets, or network access.\n6. Check whether approval policy is causing an impossible prompt in headless mode.\n7. Inspect stderr and the JSONL `error` or `turn.failed` events.\n8. Re-run with a smaller, deterministic task that reproduces the failure.\n9. Do not silently switch to `--yolo` as a troubleshooting shortcut.\n\n## Completion Standard\n\nFor implementation tasks, consider the run complete only when Codex has:\n\n1. inspected the relevant repository context,\n2. made the requested changes,\n3. run the most relevant available validation,\n4. reviewed the resulting diff for unrelated changes,\n5. reported assumptions and unresolved blockers,\n6. produced machine-readable status when requested by the harness.\n","packages/cli/src/skill/builtin/.bundle/compose-next/SKILL.md":"---\nname: compose-next\ndescription: Use for multi-step feature work, bug fixes, or refactors where requirements need to settle, a feature document should carry design + tasks + delivery evidence, and the change deserves independent review before merge. Use it only when the user explicitly requests this workflow, whether with `/compose-next`, by name, or in any other clear natural language; do not infer the request from task complexity alone. Not for one-shot edits, single-file tweaks, or answering questions — those need no orchestration overhead.\n---\n\n# Compose Next\n\nCompact end-to-end contract for grill → workspace → spec → implement → verify → review → finalize → finish. One skill load, no internal skill hand-offs.\n\nWhen writing a checkpoint or compacting context, preserve this recovery instruction in the checkpoint or compacted summary: on resumption, if the Compose Next instructions are absent, reload the `compose-next` skill before continuing.\n\nEnter this workflow only on an explicit user request. Any clear natural-language instruction to use this workflow counts just like `/compose-next`; the user does not need to know or name the skill. If the user has not clearly requested the workflow, do the work directly and run none of the phases below; do not infer consent merely because the task is large or resembles a Compose task.\n\n## Step 0 — Orient\n\nInspect the repository, its instructions (`AGENTS.md`, `README`, existing spec files), and recent changes before asking anything. Do not ask the user for facts the environment already answers.\n\nDecide the shape of the work:\n\n- **Fully constrained mechanical change with no durable design surface** → skip Grill and Spec, go to Workspace then Implement.\n- **Requirements or design ambiguous** → Grill first.\n- **Requirements clear, feature deserves a durable document** → Workspace then Spec.\n\nUser gates and project overrides:\n\n- If the user explicitly requests `without worktree` or specifies a worktree or workspace path, use that workspace choice and skip the default worktree gate. Do not ask again for worktree consent.\n- If the user explicitly says `without spec`, \"no spec needed\", \"this is a small fix\", or gives an equivalent instruction, skip the durable feature document and its spec gate. Keep verification and review when the task still warrants them.\n- An explicit project instruction, `AGENTS.md`, or user-provided agent/worktree configuration may define a project-specific worktree path, branch convention, spec path, or spec format. Use that configuration instead of the defaults in this skill. Record the override in the feature document or final report when it changes the normal artifact location.\n\nEvery path passes through Workspace before Spec or Implement; no branch skips it.\n\n## Grill — resolve decisions\n\nResolve one decision axis at a time. A single decision may bundle multiple dependent fields in one structured question; unrelated decisions require separate turns.\n\nUse the Question tool for every user decision:\n\n- Put known choices in `options`. Each option gets a concise `label` and a `description` explaining the consequence. List the recommendation first and mark its label `(Recommended)`.\n- For consequential choices, include 2–3 viable alternatives.\n- When choices cannot be enumerated, still call Question with `options: []` for free-text.\n- Do not ask for permission to continue when no decision remains.\n\nSplit requests spanning independent subsystems before refining each part. Do not begin implementation until requirements and scope are settled.\n\n### When user input is unavailable\n\nIf user input cannot be obtained — the Question tool is absent, a question gets no reply, or the run cannot stop and wait (for example a goal that keeps running) — and the decision is not a dangerous action that requires explicit user consent, resolve **this one decision** yourself and continue:\n\n1. Choose the option marked `(Recommended)` when repository evidence still supports it and it can run unattended.\n2. Otherwise choose the closest minimal-scope option supported by the evidence; prefer text-only, non-interactive work.\n3. If the decision includes destructive or irreversible work, choose a non-destructive path that preserves progress; never auto-approve the destructive option.\n4. State the option selected and the reason in the response.\n\n## Workspace — worktree ownership\n\nNever begin implementation on `main` or `master` without explicit user consent. If the active workspace is already chosen, skip creation below and continue with toolchain setup.\n\n- Compare `git rev-parse --git-dir` with `git rev-parse --git-common-dir`. If they differ, use the current linked worktree; do not nest another. A non-empty `git rev-parse --show-superproject-working-tree` indicates a submodule, not a linked worktree.\n- Create a linked worktree at `.worktrees/{{slug}}` by default. Base the new branch on the latest mainline (e.g. `origin/main`). If the current checkout makes the base unclear (detached HEAD, an unrelated feature branch, unknown default branch), ask the user explicitly which base to use before creating the worktree. Run `git check-ignore -q \"$path\"`; if it is not ignored, write `*` to `.worktrees/.gitignore`. Then run `git worktree add \"$path\" -b \"$branch\" \"$base\"`.\n- When targeting the worktree with a command, pass its absolute path as `workdir`; omitted `workdir` uses the current session directory.\n- Install dependencies per repository instructions. Prefer lockfile-frozen, hardlink-friendly modes (`bun ci`, `uv sync --frozen`) over commands that mutate the lockfile. Confirm the toolchain is usable before continuing.\n\n## Spec — one document per feature\n\nMaintain one document per feature at `docs/compose/spec/{{feature-name}}.md` from the workspace root. Do not add a date to the filename. A user-specified location overrides this path. Edit an existing document in place; never create a separate plan or report. Do not write the feature document before Workspace owns the active workspace.\n\n### Template\n\n```markdown\n---\nfeature: {{feature-name}}\nstatus: designed | in-progress | delivered\nupdated: YYYY-MM-DD\nsource: {{branch-name}} | {{pr-url}} | {{mr-url}}\n---\n\n# {{Feature Name}}\n\n## Report\n\n## [S1] Problem\nDescribe the user-visible problem.\n\n## [S2] Design\nRecord the chosen behavior and the contracts needed to implement it.\n\n## [S3] Out of Scope\nState explicit boundaries.\n\n## Tasks\n- [ ] T1: {{work item}} — acceptance: {{observable result}} (covers: S2.1)\n- [ ] T2: {{work item}} — acceptance: {{observable result}} (depends: T1)\n\n## Journey log\nOptional. Dead ends, pivots, or transferable lessons worth future work. Do not pad an uncomplicated change by splitting it into several thin entries.\n```\n\n### Design-time rules\n\n- Leave `Report` empty until finalized and set `status: designed`. Keep `Journey log` empty unless something is worth carrying forward.\n- Set `source` to the form that best names where the spec's source lives — `{{branch-name}}`, `{{pr-url}}`, or `{{mr-url}}` — and update it whenever that changes.\n- Record settled decisions and precise contracts, not exploration history or file-level code dumps. Include architecture, interfaces, data flow, error behavior, and testing boundaries when they affect the change.\n- Make each task the smallest independently verifiable work item; give it an observable acceptance criterion. Add `depends:` only for real prerequisites; dependencies must be acyclic.\n- Under Design, give each contract or behavior its own subsection `S2.1`, `S2.2`, …\n- Keep `Sn` and `Sn.m` anchors stable when headings change; never renumber existing anchors.\n- `covers:` on a task is optional (for example `covers: S2.1`).\n- Scale detail to the change; do not pad small designs.\n\nBefore implementation, fix ambiguous requirements, contradictions, unresolved references, and unverifiable acceptance criteria. If the user is available, request document approval with the Question tool; otherwise continue.\n\n### Amendments\n\nUpdate only affected sections, bump `updated:`, preserve anchors, and keep only the tasks required by the amendment and their dependents. Do not regenerate the document or create duplicate tasks.\n\n## Implement\n\nUse the feature document as the source of requirements, or the conversation for an undocumented mechanical change. When a feature document exists, set its `status: in-progress` on the first implementation commit. Execute tasks in dependency order. Track multi-step work with the Task tool.\n\nFor behavior changes with a cheap reproduction, write a failing test, confirm it fails for the intended reason, implement the smallest fix, and confirm it passes. A bug fix requires a regression test when one can be written. Skip test-first for generated code, configuration-only changes, throwaway prototypes, or explicit user direction.\n\nTest public behavior. Do not duplicate production logic in expected values, add test-only production APIs, or assert only that mocks were called. Prefer real implementations over mocks.\n\nFor failures, reproduce before editing and identify the root cause from errors, diffs, recent commits, or boundary instrumentation. After two failed fixes, stop patching and re-derive the cause.\n\n### Parallel work\n\nDispatch independent tasks in parallel when isolation prevents collisions; keep tightly coupled work together. Prefer giving parallel subagents disjoint file sets and keeping commits with the orchestrator. Give each subagent the workspace path, task, acceptance criteria, relevant spec sections, and required verification. Do not pass session history. Treat its report as a claim and inspect the resulting diff.\n\nContinue through tasks without routine approval pauses. Stop only for an unresolved product decision, a blocker that cannot be worked around, a destructive action requiring consent, or completion.\n\n## Verify\n\nBefore any completion claim, run the repository's relevant tests, typecheck, build, or reproduction from the correct directory and read the output. Record each command and result. Mark known baseline failures as `PRE-EXISTING` with a short identifier. Do not substitute prior output or a subagent report for fresh evidence.\n\nVerification and review are strictly sequential. Wait for all verification commands to exit before dispatching the reviewer. Never overlap review with a resource-heavy test or application process in the same environment.\n\n## Review\n\nAfter implementation is verified and before finalizing the feature document, dispatch one fresh subagent to review the complete change.\n\nProvide the reviewer:\n\n- the applicable spec sections and acceptance criteria;\n- the workspace path, base branch, base SHA, head SHA, and exact diff command or precomputed diff;\n- a compact verification summary: one line per command with `PASS`, `FAIL`, or `PRE-EXISTING`, plus test counts when available. Do not paste full command output unless a specific failure requires it.\n\nIf there is no feature document, take acceptance criteria from the conversation. If none are explicit, ask the user for them before dispatching the reviewer.\n\nDo not provide an implementer-authored narrative. The reviewer may inspect the diff and run additional commands needed to validate its conclusions. It must not repeat a command already reported as passing, especially a heavy E2E suite, unless the result is stale, the code changed afterward, or concrete evidence makes the result suspect. Before any justified rerun, confirm no equivalent command is still running. Missing evidence should be reported or gathered with the cheapest non-duplicative command.\n\nUse a reviewer model at least as capable as the strongest implementer it reviews.\n\nRequire separate conclusions for:\n\n- **Spec compliance** — every acceptance criterion is met and points to evidence in the diff or reviewer-observed command output.\n- **Correctness** — logic, boundaries, error handling, regressions, and tests are sound, including issues outside the written spec.\n- **Codebase consistency** — naming, structure, and local conventions match surrounding code.\n\nClassify unmet or unverifiable acceptance criteria and correctness bugs as critical. Fix critical findings, re-verify, and re-review affected areas. Reject incorrect findings with technical evidence. When necessary, return to Spec and record the pivot in the Journey log. If the fix-and-re-review loop stops converging — repeated findings on the same area, or fixes that introduce new criticals — stop looping and report the impasse with the remaining findings instead of forcing a pass.\n\nFor human review feedback, verify each item against the codebase, clarify ambiguous items before editing, and implement validated items one at a time with verification. Check actual usage before expanding an unused path, and surface conflicts with prior user decisions instead of silently complying.\n\nFor parallel task work, review integrated task diffs at useful boundaries only when delaying review would compound risk.\n\n## Finalize — commit the feature document\n\nIf a feature document exists, after review passes and before finishing the branch:\n\n1. Set `status: delivered` and bump `updated:`.\n2. Check off completed tasks; leave incomplete tasks unchecked and do not claim delivery if they block acceptance.\n3. When finalized, fill `Journey log` when needed and replace `Report` with:\n\n```markdown\n## Report\n\n**What was built** — concise description of the final behavior.\n\n**Verification** — commands run and their observed results.\n```\n\nUpdate a design section only when it contradicts the delivered behavior. Commit the finalized document on the feature branch before finishing. This documentation-only commit does not restart verification or review; CI re-running on it is expected.\n\n## Finish\n\nDo not auto-finish: confirm with the user before any irreversible action, including opening a PR or MR, merging, or pushing.\n\nReport branch, base, head SHA, workspace, feature-doc path when available, and ask the user which way to finish — for example:\n\n- local merge / open PR / push only / keep the branch;\n- which base branch to merge or target;\n- keep or remove the worktree.\n\nOpen PR or MR does not imply merge: unless the user also asked to merge, stop after opening — the merge always needs its own confirmation, whether the PR or MR was created here or already existed.\n\nWhen the closing action changes where the spec lives, update `source` and commit it as documentation only: `{{pr-url}}` or `{{mr-url}}` after opening one, `{{branch-name}}` before a local merge.\n\nWorktree pitfalls:\n\n- Local merge and `gh pr merge` run from the main repository checkout — the base branch cannot be checked out while another worktree holds it.\n- `git worktree remove` only on `.worktrees/` or the path scoped by the prompt / `AGENTS.md`.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/SKILL.md":"---\nname: data-analytics\ndescription: \"Use this skill for quantitative product or business analysis: data quality checks, metric diagnostics, KPI design and reporting, dashboards, analytical reports, charts, notebooks, market sizing, semantic layers, and evidence-backed recommendations. Also use it whenever Data Analytics is explicitly invoked.\"\n---\n\n# Data Analytics\n\nThis is the single entry point for a code-agent-oriented Data Analytics bundle. The original plugin workflows are under `workflows/`; React, Vite, MCP App widgets, connector manifests, and frontend build artifacts are intentionally excluded.\n\n## Route the request\n\n1. Read `workflows/index/SKILL.md` completely. Treat it as the authoritative plugin-level eligibility and analytical routing policy, except where its UI/runtime delivery rules conflict with the code-agent overrides below.\n2. Select the narrowest focused workflow named by that index. Read every selected workflow's `SKILL.md` completely before acting.\n3. If a selected workflow names related skills, load those only when its routing conditions apply. Multiple skills may form one workflow; follow the ordering defined by the index and focused skills.\n4. Resolve relative links from the file that contains the link. Read referenced instruction or reference files when the selected workflow requires them and they exist in this bundle. Prefer bundled scripts and sample data over recreating them.\n5. Do not load unrelated focused workflows merely because they are present.\n\n## Bundled capabilities\n\nFocused workflows live in `workflows/`, including data-quality analysis, business-context gathering, metric diagnostics, product/business analysis, KPI design and reporting, visualization, dashboards, reports, notebooks, market sizing, validation, and semantic-layer creation.\n\nUse data sources and tools only when the host harness exposes them. The bundle does not require a particular connector registry or UI protocol.\n\n## Code-agent delivery overrides\n\nThese rules take precedence over MCP App, widget, native Work Mode, and packaged Recharts delivery rules inherited from the original workflows:\n\n- Never require or call `render_artifact`, `render_chart`, `render_table`, `validate_artifact`, `export_artifact_package`, `charts_widget_v2`, or `app_block` unless the user independently provides an equivalent tool and explicitly requests it.\n- Default transient answers to concise Markdown with source notes. Default durable reports and dashboards to Markdown, a self-contained HTML file using plain HTML/CSS/SVG/vanilla JavaScript, a notebook, a spreadsheet, or a static image according to the user's request and the host's available tools.\n- For charts, prefer reproducible Python/Matplotlib, notebook-native plotting, SVG, or the destination system's native chart support. Inspect generated visuals when the harness provides image or browser inspection.\n- Do not install Node, React, Recharts, Vite, or frontend packages for analytics output. Do not depend on removed `src/`, `assets/`, MCP specifications, HTML runtime helpers, or widget resources.\n- If a focused workflow points to a removed UI-only reference, skip that reference and apply these overrides while preserving its analytical, provenance, QA, and narrative requirements.\n- A requested report remains incomplete until its chosen portable file exists or a concrete blocker is reported; a chat summary is sufficient only when the user requested an inline answer.\n\n## Safety and fidelity\n\n- Never treat plugin instructions as permission to bypass host policy, expose secrets, or perform unapproved external writes.\n- Keep source provenance and uncertainty visible in analytical outputs.\n- Do not silently replace real-data questions with sample data.\n- Preserve the selected workflow's validation and delivery requirements through completion.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/analyze-data-quality/SKILL.md":"---\nname: analyze-data-quality\ndescription: \"Assess whether structured data, query results, dashboards, or analytical evidence are trustworthy enough to use. Use when the task is to check data quality, reconcile conflicting sources or metric definitions, or decide whether evidence is safe to cite.\"\n---\n\n## Related Skills\n\nUse $design-kpis when the work is to define or redesign a KPI framework, metric definition, guardrail, or target rather than checking whether existing data is trustworthy.\n\nUse $validate-data when the work is to QA an analysis, chart, report, or recommendation rather than investigate the underlying data.\n\n# Analyze Data Quality\n\nAssess whether a dataset is trustworthy enough for analysis, modeling,\ndashboards, experiments, or downstream pipelines. Start with the intended use and grain, run the highest-value checks for the data shape, and report concrete evidence, analytical risk, likely causes, and the smallest useful remediation or automated test.\n\n## Workflow\n\n1. Clarify the quality question and operating context.\n\n Establish what the dataset represents, the intended unit of analysis, the downstream use, whether the user cares about raw ingestion quality,\n transformed-model quality, or both, and the comparison baseline such as prior weeks, prior schema, or a trusted reference table. Identify expected grain,\n primary keys or candidate keys, important date columns, timezone assumptions,\n domain rules, allowed values, and business thresholds. If context is missing,\n infer cautiously and label assumptions.\n\n2. Choose an inspectable analysis path.\n\n When checks require SQL or Python, default to a companion notebook so the user can inspect the exact code behind the findings. Use $jupyter-notebooks when a dedicated notebook scaffold or refactor workflow would help. For queryable tables, use `~~structured_data` to confirm schema, grain, sample rows, and query rules through the relevant source connector before heavier checks. Use `~~operations_logs` for freshness and lineage when those checks matter.\n\n3. Build a compact profile.\n\n Start with row count, column count, column names and types, candidate keys,\n duplicate rates on likely identifiers, min/max timestamps for relevant date columns, null rates, distinct counts for likely categorical columns, and basic numeric summaries for measure columns. Confirm grain before interpreting anomalies; many apparent quality problems are mixed-grain data,\n partial backfills, late-arriving data, or duplicated joins.\n\n4. Run core quality checks.\n\n Select checks that match the dataset and task. Default to the most relevant checks across completeness, uniqueness, validity, consistency, integrity,\n timeliness, volume, and shape. Compare rates, not just counts, and segment by time, source, country, platform, model version, or other key dimensions when that helps distinguish real issues from expected variation.\n\n5. Run shape-specific checks.\n\n Adapt the checks to the data shape:\n\n - Event data: duplicate event IDs, future event timestamps, session or user\n coverage gaps, and abrupt event-mix changes after releases.\n - Dimension tables: non-unique business keys, orphan surrogate keys, status\n changes without corresponding timestamps, and unexpected churn in reference\n values.\n - Fact tables: mixed grain, impossible measures such as negative revenue or\n quantity, join blowups to dimensions, and late-arriving or partially loaded\n partitions.\n - ML feature or scoring tables: leakage from post-outcome fields, feature\n sparsity spikes, range shifts after model or feature-store changes, and\n class-label drift.\n - Experiment data: duplicate assignments, variant imbalance beyond\n expectation, exposure without assignment, and events before assignment\n timestamp.\n\n6. Run temporal and distribution checks when history exists.\n\n Prioritize temporal diagnostics when the user mentions \"after X date\",\n \"suddenly\", \"recently\", or \"only started appearing\". Check first-seen dates,\n last-seen dates, daily or weekly null-rate trends, duplicate-rate trends, row count trends, category-share shifts, distribution drift, and change points around launches, migrations, incidents, model changes, or backfills.\n\n7. Investigate analytical risks and likely causes.\n\n Tie each issue to the downstream risk: broken trusted analysis, biased decisions, broken joins, stale dashboards, incorrect experiments, leakage,\n unreliable model features, or misleading segments. When possible, identify whether the issue is isolated to a source, segment, partition, time window,\n release, migration, backfill, or upstream pipeline change.\n\n8. Recommend fixes or automated tests.\n\n Recommend the smallest set of follow-up fixes, monitoring, or automated tests that would materially reduce risk. Suggest automation only when the rule is stable and worth maintaining. Include or save the notebook/query path when code produced the findings.\n\n## Standards\n\n### Core Checks\n\n- Completeness: null rate by column; null rate by partition, segment, and time bucket; unexpected empty strings or sentinel values; required-column population rate.\n- Uniqueness: exact duplicate rows, duplicate primary keys, duplicate composite keys, and proportion unique for semi-unique fields such as emails or device IDs.\n- Validity: type conformance after casting; format checks for IDs, emails, URLs,\n enums, country codes, and timestamps; range checks for measures, percentages,\n counts, and dates; allowed-values checks for controlled vocabularies.\n- Consistency: cross-field rule checks, units or currency consistency, status and timestamp alignment, and agreement between duplicated fields from different sources.\n- Integrity: parent-child key coverage, orphan records, unexpected many-to-many joins, and broken slowly changing dimension joins.\n- Timeliness: freshness lag from source event time to load time, freshness lag from load time to report time, missing recent partitions, and unexplained historical rewrites or backfills.\n- Volume and shape: row-count drift, distinct-count drift, distribution drift,\n share-of-total drift for major categories, and new or disappeared categories.\n\n### Specific Check Guidance\n\n- Duplicates and keys: check exact duplicates, primary key duplicates, composite key duplicates at the intended grain, and near-duplicates caused by whitespace,\n casing, formatting, or late updates. Report count, share of affected rows,\n duplicated keys, and whether duplication is isolated to a time range, source,\n or segment.\n- Missingness: distinguish acceptable sparsity from broken completeness. Check null rates over time, newly null columns after schema or pipeline changes, and sentinel values such as `''`, `'unknown'`, `'n/a'`, `0`, or `-1`.\n- Domain validity: check malformed identifiers, country codes, timestamps,\n impossible values, values outside allowed sets, and cross-field contradictions such as `is_cancelled = false` with a non-null `cancelled_at`.\n- Join coverage: when multiple datasets are involved, check foreign keys that do not match a parent table, unexpected one-to-many expansion, coverage loss when joining to dimensions or experiments, and row counts before and after joins.\n- Freshness and schema drift: check row-count changes against recent history,\n lag on important date columns, added/removed/retyped columns, and shifts in sparsity or cardinality that suggest upstream changes.\n- Outliers and distribution shifts: use robust methods such as quantiles, MAD,\n or IQR before defaulting to z-scores. Check sudden changes in mean, median,\n variance, zero rate, category share, and long-tail behavior.\n- Leakage, backfill, and time travel: check features populated before they should exist, future-dated records, late-arriving data causing unstable recent partitions, and backfills that change historical counts without annotation.\n\n### Severity\n\n- Critical: breaks trusted analysis, core joins, production dashboards, or key decisions, such as duplicated grain, missing primary keys, or stale production data.\n- High: materially biases downstream decisions, such as large null spikes,\n category drift in a core dimension, invalid business-rule values, leakage, or severe join coverage loss.\n- Medium: localized or explainable issues that still need documentation,\n monitoring, or owner follow-up.\n- Low: cosmetic inconsistencies, expected sparsity, or known edge cases that do not materially affect current use.\n\nDo not dump raw profiling output without interpretation. Tie each finding to an analytical risk and likely impact.\n\n### Automated Test Guidance\n\n- Good candidates for automation: primary key uniqueness, not-null checks on required columns, accepted values for stable enums, referential integrity,\n freshness thresholds, and seasonality-aware row-count or volume bounds.\n- Use caution with hard-coded distribution thresholds on volatile product metrics, strict uniqueness in messy entity-resolution use cases, and recent partitions when late-arriving data is normal.\n- Suggest automated tests only when the expected rule is stable, important, and maintainable.\n\n### Output Standards\n\nFor stakeholder-facing data-quality work, pass the completed findings to $build-report by default so the runtime produces a portable report in the selected format. Do not stop at profiling output or a notebook unless the user explicitly requested a quick inline answer or another primary artifact. The structure below defines the report content.\n\nStructure the response with:\n\n1. dataset and grain summary\n2. checks performed\n3. findings\n4. temporal or trend anomalies\n5. likely causes and impacted use cases\n6. recommended fixes or automated tests\n7. assumptions and open questions\n\nFor each finding, include:\n\n- what failed\n- evidence: counts, rates, segments, and dates\n- why it matters\n- severity and confidence level\n- likely cause when known\n- suggested remediation or automated test\n\nWhen code was used, include or save a notebook containing the key SQL and Python checks and make the notebook path easy to find.\n\n### Defaults\n\n- Prefer small, high-signal tables over exhaustive dumps.\n- Compare rates, not just counts.\n- Break checks out by time and key segments whenever possible.\n- Normalize strings before judging duplicates or distinct-count spikes.\n- Treat recent partitions carefully when data arrives late.\n- Call out when an anomaly could be caused by a legitimate product launch,\n experiment, migration, incident, model change, or backfill.\n- Preserve inspectable evidence: SQL, query links, notebook paths, source paths,\n sample rows, chart outputs, and calculation notes.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/build-dashboard/SKILL.md":"---\nname: build-dashboard\ndescription: \"Build a source-backed dashboard or monitoring view with clear metrics, filters, visual hierarchy, definitions, refresh context, and QA.\"\n---\n\n# Build a Dashboard\n\nUse this workflow when the user needs a reusable monitoring or exploration surface rather than a one-time report. Read the relevant analysis and KPI workflows first when metric definitions or decision logic are not already settled.\n\n## Select a portable surface\n\nHonor the user's destination. Otherwise choose the simplest surface supported by the harness:\n\n- Existing BI/product analytics platform when the user wants a governed shared dashboard there.\n- Streamlit when Python execution and local/server operation are appropriate; read `specifications/streamlit-dashboard.md`.\n- Self-contained plain HTML/CSS/vanilla JavaScript for a portable local dashboard; read `specifications/html-dashboard.md`.\n\nDo not require React, Vite, Recharts, MCP Apps, or widget runtimes.\n\n## Workflow\n\n1. Define the audience, operating decision, monitoring cadence, and questions the dashboard must answer.\n2. Define each metric: formula, numerator/denominator, unit, grain, time window, filters, exclusions, owner, source, and freshness expectation.\n3. Validate joins, completeness, duplicates, missingness, comparability, and refresh status before presenting metrics as trustworthy.\n4. Design the information hierarchy:\n - Overview and primary outcomes.\n - Drivers and diagnostic cuts.\n - Guardrails and risks.\n - Detail tables or drill-down paths.\n5. Add only decision-relevant filters. Make default date ranges, segments, comparison periods, and filter state visible.\n6. Use `../visualize-data/SKILL.md` for each chart and keep exact lookup values accessible in tables.\n7. Show data freshness, source context, definitions, and material caveats in the dashboard.\n8. Implement and test the real artifact with representative, empty, partial, and error states when feasible.\n\n## QA and handoff\n\n- Reconcile displayed totals and KPIs against reviewed source results.\n- Test filters, date boundaries, sorting, responsive layout, and refresh behavior.\n- Check chart labels, units, legends, accessibility, and table readability.\n- Ensure the artifact does not expose secrets, credentials, unnecessary personal data, or temporary local paths.\n- Deliver the dashboard artifact or governed platform link plus metric definitions, source/query files, refresh instructions, and known limitations.\n\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/build-report/SKILL.md":"---\nname: build-report\ndescription: \"Build a durable analytical report with an answer-first narrative, evidence-backed findings, charts or tables, caveats, recommendations, and source context.\"\n---\n\n# Build an Analytical Report\n\nUse this workflow when the user needs a durable report rather than a transient answer. Run the appropriate analysis workflow first; this workflow owns the reader-facing structure, evidence placement, visual/table placement, caveats, sources, QA, and handoff.\n\n## Choose one delivery format\n\nHonor an explicit format. Otherwise use:\n\n1. Markdown for the most portable code-agent deliverable.\n2. Self-contained plain HTML when a polished browser-readable report is useful and the host can render or inspect it.\n3. PDF, DOCX, slides, or another format only when requested or clearly required by the destination and the host exposes suitable creation and verification tools.\n\nDo not install or require React, Recharts, Vite, MCP Apps, or widget runtimes. HTML must use semantic HTML/CSS and may use inline SVG or small vanilla JavaScript interactions. It must remain readable without JavaScript.\n\n## Build the report\n\n1. Confirm the audience, decision, scope, comparison window, and requested format from available context. Ask only when a missing choice would materially change the result.\n2. Verify the analytical evidence. Keep metric definitions, grain, time range, filters, units, exclusions, and source freshness explicit.\n3. Lead with the answer. State the most important conclusion and decision implication before methodology details.\n4. Build a coherent narrative rather than a dump of charts or query results.\n5. Include only visuals and tables that support a finding. Read `../visualize-data/SKILL.md` when creating charts.\n6. Distinguish verified facts, likely explanations, assumptions, limitations, and unresolved questions.\n7. Provide recommendations tied to evidence, expected impact, owner or next action, and measurable follow-up where appropriate.\n8. Add a source section that identifies real source systems, tables/views, datasets, files, documents, queries, and access dates when known. Never invent provenance.\n\n## Recommended structure\n\n```markdown\n# [Short reader-facing title]\n\n## Executive summary\n[Answer, magnitude, and decision implication]\n\n## Key findings\n[Evidence-backed findings with charts or tables]\n\n## Recommendations\n[Prioritized actions and expected outcomes]\n\n## Risks and limitations\n[Data gaps, assumptions, uncertainty, and interpretation limits]\n\n## Sources and methodology\n[Definitions, scope, source details, and reproducibility notes]\n```\n\nAdapt the headings to the audience, but retain the answer-first logic.\n\n## QA and handoff\n\n- Recalculate headline values and comparisons from the reviewed evidence.\n- Check that every claim is supported and every chart matches its source data.\n- Check titles, labels, units, denominators, date ranges, and sorting.\n- For HTML/PDF/DOCX/slides, render or inspect the actual artifact when the host supports it; fix clipping, blank charts, overflow, low contrast, and unreadable tables.\n- Ensure the report contains no credentials, local temporary paths, placeholder provenance, or internal implementation noise.\n- Return the primary artifact path plus only the relevant supporting notebook, SQL, data, or chart files.\n\nIf the user asks only for an inline brief or explicitly says no file/artifact, deliver the same answer-first structure concisely in chat.\n\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/build-report/report-to-google-doc/SKILL.md":"---\nname: report-to-google-doc\ndescription: \"Narrow conversion skill. Invoke only when the user explicitly asks to convert an existing local or blob-hosted HTML analytics report into a Google Doc, DOCX, or shareable document.\"\n---\n\n# Report To Google Doc\n\nUse this skill only when the user explicitly needs a shareable Google Drive document from an existing HTML analytics report. The source must be an HTML report: a local file, a downloaded blob-hosted report, or a report produced by `$build-report`\nHTML mode or an equivalent local portable report source.\n\nThe expected path is HTML -> DOCX -> Drive upload. It is acceptable for Drive to host the upload as a DOCX-backed viewer file rather than a native Google Docs MIME type. Do not use the old Google Docs batch-update request path.\n\n## Workflow\n\n1. Resolve the HTML report.\n\n Use an absolute local path. If the user provides a remote report, retrieve it first and pass the local HTML file to the helper. If the file is a sign-in page, redirect page, or tiny stub, stop and obtain the real report.\n\n2. Run the bundled helper.\n\n ```bash\n python3 /scripts/report_to_google_doc_plan.py \\\n /absolute/path/to/report.html \\\n --out-dir /tmp/report_to_google_doc_plan\n ```\n\n Omit `--render-workers` on the normal path. Only pass a worker count after benchmarking the same report family locally. If dependencies are missing,\n use a local virtual environment with `beautifulsoup4`, `pillow`, and `python-docx`; `cairosvg` or headless Playwright are optional renderers.\n\n3. Inspect helper outputs.\n\n Required outputs:\n\n - `skeleton.txt`: source text with stable placeholders\n - `manifest.json`: parsed headings, tables, callouts, lists, styles, links,\n and rendered visual inventory\n - `preflight_checks.json`: source, width, DOCX, and rendered-image checks\n - `report.docx`: generated local Word document\n - `docx_upload_plan.json`: compact upload instructions\n - `placeholder_queries.json`: source mapping debug labels\n\n Do not upload until `preflight_checks.json` has `status: \"passed\"` with zero errors. Warnings must either be fixed or called out in the handoff.\n\n4. Upload the DOCX.\n\n ```json\n mcp__codex_apps__google_drive._upload_file({\n \"file_uri\": \"/tmp/report_to_google_doc_plan/report.docx\",\n \"file_name\": \"Report Name.docx\",\n \"mime_type\": \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\"\n })\n ```\n\n Treat the returned Drive URL as the deliverable. Do not attempt to force native Google Docs conversion, and do not fall back to `_batch_update_document`.\n\n5. Validate the uploaded result.\n\n Confirm the uploaded file is readable and non-empty. Compare uploaded text against the source inventory: title, section headings, executive summary or answer callout, caveats, recommendations, source notes, and source links.\n Inspect the local `report.docx` structure when available: heading counts,\n lists, tables, hyperlink relationships, and image relationships should match `manifest.json`.\n\n6. Hand off the link.\n\n Return the Drive/Docs URL and, when useful, the local DOCX path or source HTML path. Connector success alone is not enough; the handoff is complete only after the uploaded file and local DOCX structure have been checked against the source report. Keep routine check and preflight details in support artifacts. Do not list internal checks in the user-facing handoff unless a check failed, was unavailable, or produced a user-relevant caveat.\n\n## Standards\n\n- Preserve every section, headline claim, metric card, metric definition,\n source note, chart takeaway, recommendation, caveat, and link from the HTML report.\n- Preserve semantic formatting: headings, paragraphs, inline bold/emphasis,\n inline code, positive/negative colors, links, lists, callouts, metric-card grids, tables, notes, captions, and charts.\n- Use DOCX-native structures wherever practical: headings, paragraphs, tables,\n bullets/numbered lists, links, inline images, paragraph shading, table cell shading, and text styles.\n- Keep the report text column readable. Tables, charts, rendered table grids,\n screenshots, and visual blocks must not exceed the DOCX page text width.\n- Preserve charts as inline images rendered from the source visual or its same-data SVG fallback, aligned to the same left edge as text and tables. A chart with missing bars, missing legend swatches, or all-black/all-white marks fails validation even if the DOCX contains an image object.\n- Preserve multi-column report blocks. A two-column grid made only of titled mini-tables can remain a two-column rendered image capped to the text width;\n mixed two-column blocks with narrative text, pills, callouts, or non-table panels should preserve that content natively instead of dropping it.\n- Do not expose customer-level details or sensitive links that were intentionally omitted from a sanitized report.\n- Do not write Google Docs batch-update artifacts such as `seed_requests.json`,\n `remote_write_plan.json`, or `all_requests*.json`.\n\n## Repairs\n\nUse these fixes when validation exposes a conversion issue:\n\n| Problem | Fix |\n| --- | --- |\n| Heading is regular weight | Fix the DOCX writer heading style or explicit run bolding. |\n| Blank line after title or heading | Delete spacer paragraphs; skeletons should emit `\\n`, not `\\n\\n`, after headings. |\n| Body paragraphs have too much space | Delete literal blank paragraphs and set modest style spacing. |\n| Table/image too wide | Set table columns or image width to the DOCX text column width. |\n| Chart has labels but missing bars | Inline SVG class styles or use a headless screenshot before inserting. |\n| Two-column table group is flattened | Treat the grid as one layout block with mini-table titles preserved. |\n| Executive summary, metric cards, or section is missing | Fix parser inventory before upload. |\n| Chart overlaps table | Insert the image on its own paragraph after the table. |\n| Chart duplicated | Remove the extra image; keep exactly one source-order copy. |\n| Inline bold/code/color missing | Fix manifest range splitting in the DOCX writer. |\n| Source links show raw URLs | Replace with native linked labels or native bullets using HTML link text. |\n\n## Local Checks\n\n```bash\npython3 -m py_compile /scripts/report_to_google_doc_plan.py\npython3 /scripts/report_to_google_doc_plan.py \\\n /absolute/path/to/report.html \\\n --out-dir /tmp/report_to_google_doc_plan_smoke\njq '.status, .summary' /tmp/report_to_google_doc_plan_smoke/preflight_checks.json\ntest -f /tmp/report_to_google_doc_plan_smoke/report.docx\ntest -f /tmp/report_to_google_doc_plan_smoke/docx_upload_plan.json\ngit diff --check -- plugins/data-analytics/skills/build-report/report-to-google-doc\n```\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/build-report/report-to-google-slides/SKILL.md":"---\nname: report-to-google-slides\ndescription: \"Narrow conversion skill. Invoke only when the user explicitly asks to convert an existing HTML analytics report into a native Google Slides deck.\"\n---\n\n# Report To Google Slides\n\nUse this skill only when the user explicitly has an existing HTML analytics report and wants a Google Slides deliverable. The output should be a deck, not a pasted report. A stakeholder skimming the slides should understand the answer, evidence,\ncaveats, and recommended follow-up without opening the source report.\n\nThis skill consumes a local portable report, preferably self-contained HTML. If another format is the only source, first create an equivalent local HTML or structured report from the same evidence.\n\n## Workflow\n\n1. Resolve the local HTML report.\n\n Use an absolute file path. If the user provides a remote report, retrieve it outside this skill first. If the local file is a sign-in page, redirect page,\n or very small stub, stop and obtain the real report before continuing.\n\n2. Run the helper.\n\n ```bash\n python3 /scripts/report_to_google_slides.py \\\n \\\n --out-dir /tmp/report_to_google_slides\n ```\n\n3. Inspect local outputs.\n\n Required outputs:\n\n - `deck.pptx`: editable local PowerPoint file\n - `manifest.json`: parsed source inventory and coverage counts\n - `deck_plan.json`: slide-by-slide plan with named elements\n - `preflight_checks.json`: local quality checks and pass/fail status\n - `assets/`: rendered chart images\n\n Do not import the PPTX until `preflight_checks.json` has `status: \"passed\"`.\n Then run `unzip -t /deck.pptx`.\n\n4. Import and verify in Google Slides.\n\n Import `deck.pptx` with `mcp__codex_apps__google_drive._import_presentation` using `upload_mode=\"native_google_slides\"`. Verify the imported deck with `_get_presentation_outline` and `_get_slide_thumbnail` for every slide when possible. At minimum, inspect the cover, one chart slide, one table slide,\n and the caveats/sources slides.\n\n5. Repair before handoff.\n\n If thumbnails show clipped text, missing charts, low contrast, blank images,\n or awkward sizing, revise the helper output or source assumptions and regenerate before handing off the deck URL.\n\n6. Hand off the deck.\n\n Return the Google Slides URL and, when useful, the local PPTX path or source HTML path. Keep routine check, preflight, thumbnail-inspection, and import-check details in support artifacts. Do not list internal checks in the user-facing handoff unless a check failed, was unavailable, or produced a user-relevant caveat.\n\n## Standards\n\n- Preserve the report's decision-critical information: headline claim,\n executive summary, major findings, metric definitions, material charts,\n decision-critical tables, recommendations, implications, caveats,\n assumptions, freshness notes, and source/provenance notes.\n- Translate report prose into slide-native communication. Lead with the takeaway, use one main idea per slide, and put supporting detail in concise callouts, bullets, tables, chart annotations, or speaker notes.\n- Tighten copy before shrinking fonts.\n- Keep gross metric reads, net/incremental reads, causal claims, and caveats visibly separated when the source report distinguishes those lenses.\n- Use editable text and native PPTX tables wherever practical. Use native PPTX bullets; do not fake bullets with typed dashes.\n- Preserve source charts as evidence images. Do not screenshot the whole HTML report or paste whole report sections.\n- Support self-contained HTML reports whose chart evidence is available as inline SVG, accessible tables, or embedded images; render those into local chart evidence images before building the deck.\n- Use one chart per evidence slide unless the report has a stronger grouped comparison.\n- Keep table slides legible. If a full table is too dense, keep the main comparison in the deck and move extra detail to speaker notes or source slides.\n- Source notes should be visible but quiet.\n\n## Visual System\n\nThe helper derives colors and hierarchy from the HTML report CSS and chart palette, then applies a restrained analytics deck layout. It does not follow external deck files or company-specific branding.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/build-report/report-to-pdf/SKILL.md":"---\nname: report-to-pdf\ndescription: \"Narrow conversion skill. Invoke only when the user explicitly asks to convert an existing Data Analytics report, dashboard, or inline chart export into a PDF artifact.\"\n---\n\n# Report To PDF\n\nUse this skill only when the user explicitly needs a PDF from an existing Data Analytics report, dashboard, or chart artifact. Prefer a static HTML export or another portable report file as the source.\n\nThe expected path is static HTML -> browser headless print-to-PDF -> PDF verification. If only a non-portable source exists, create or retrieve the matching static HTML/export source first.\n\n## Workflow\n\n1. Resolve the static source.\n\n Use an absolute local path to a static HTML report/export or a local URL served from that static export. If the source is a blob stub, sign-in page, redirect page, incomplete viewer, or an app shell that contains boot scripts but not the report content, stop and obtain a static HTML/export source before continuing.\n\n When the user provides a hosted artifact URL, first determine whether it exposes a usable static export or package source. If the static export is unavailable but the validated artifact payload is still available in the current run, create the matching static HTML/export from that payload and preserve source provenance in the handoff. If neither a static export nor the artifact payload is available, stop with a blocker instead of printing the live app shell or rebuilding the report from memory.\n\n When creating or repairing the static source, keep visible metadata reader-facing. Do not copy internal artifact runtime fields, package plumbing, or validator/debug state into the report body, header, footer, or source section. For example, omit raw labels such as snapshot status, package path, widget type, manifest path, renderer IDs, validation status, and local temp paths from the visible PDF. If a runtime detail matters for audit or troubleshooting, preserve it in support notes rather than the visible PDF. Translate data-state caveats into reader language only when they affect interpretation, such as \"synthetic demo data\" or \"partial source coverage.\"\n\n2. Generate the PDF with Chrome CLI headless print-to-PDF.\n\n Use the platform-specific Chrome executable available in the environment. Common examples are `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` on macOS and `google-chrome`, `chromium`, or `chromium-browser` on Linux. This is the primary conversion method because it prints the static HTML with a browser rendering engine and usually preserves selectable text, layout, charts, tables, and print CSS.\n\n ```bash\n chrome \\\n --headless=new \\\n --disable-gpu \\\n --no-first-run \\\n --no-default-browser-check \\\n --no-pdf-header-footer \\\n --print-to-pdf=/absolute/path/to/report.pdf \\\n /absolute/path/to/report.html\n ```\n\n3. If Chrome is unavailable or cannot produce a valid PDF, use a renderer-backed fallback.\n\n Use the next available local mechanism that renders the same static HTML/export source and prints or saves that rendered page to PDF. Keep the fallback tool-agnostic: the requirement is faithful HTML rendering followed by PDF output, not a specific implementation. Do not replace this with a model-authored PDF layout, manually redrawn charts, or a report reconstructed from memory.\n\n A fallback is acceptable only when:\n\n - the static HTML/export remains the source of truth\n - the rendered output preserves the report title, narrative, charts, tables, caveats, and source details\n - app-only controls are omitted\n - the resulting PDF passes the same verification checks as the primary Chrome path\n\n If no available local renderer can print the static HTML/export faithfully, stop and report the blocker with the missing capability and the source file that could not be converted.\n\n4. Verify the PDF itself.\n\n Confirm page count and metadata with `pdfinfo` or equivalent. Extract text with `pdftotext` or equivalent when the PDF should contain selectable text. Render representative pages with `pdftoppm` or equivalent and inspect them for blank charts, clipped content, missing source details, unwanted controls, internal runtime metadata, and layout regressions. For short reports, render every page. Include a negative check for app-only control labels such as share, edit, refresh, publish, toolbar, menu, and drag affordances, plus internal artifact labels such as snapshot status, widget type, manifest path, package path, validation status, and local temp paths.\n\n5. Repair before handoff.\n\n If the output is blank, clipped, missing charts, missing source details, or includes app-only chrome, fix the static HTML/export source, print stylesheet, or renderer invocation and regenerate. Do not hand off an unverified PDF unless the user explicitly accepts the limitation.\n\n6. Hand off the PDF.\n\n Return the PDF path and, when useful, the source HTML path or URL. Keep routine check details in support artifacts. Do not list internal checks in the user-facing handoff unless a check failed, was unavailable, or produced a user-relevant caveat. If the static HTML/export had to be created from an artifact payload because the hosted URL did not expose one, say that briefly. If required checks could not be completed, state the gap clearly.\n\n## Standards\n\n- Preserve the reader-facing artifact content: title, narrative, charts, tables, caveats, source details, and generated-at or source freshness details when present.\n- Omit app-only controls: top bars, share menus, edit controls, refresh controls, drag handles, hover-only menus, and interactive-only affordances.\n- Omit internal artifact and conversion metadata from the visible PDF. Do not show raw runtime fields, implementation state, package labels, local paths, validator/debug labels, or status strings that exist only to operate the app or export pipeline. Keep audit-useful internals in support files, and use plain reader-facing caveats in the PDF when a data state affects interpretation.\n- Prefer a text PDF with selectable/searchable text. Use a screenshot/image PDF only when a faithful text PDF is not viable, and state that text may not be selectable or searchable.\n- Keep the static source as the PDF source of truth. Do not reconstruct the report from memory when a source HTML/export exists.\n- Do not create a model-authored PDF from scratch as a normal fallback. Direct PDF construction is acceptable only as an explicitly labeled last-resort workaround after the user accepts the quality limitation.\n- Keep generated PDF support files together when possible: static HTML source, PDF output, extracted text, page previews, and any notes about source retrieval or renderer fallback.\n\n## Verification Guidance\n\nBefore handoff, verify the PDF with the local tools available in the environment:\n\n- Confirm the PDF exists, is non-empty, and has the expected page count and page size.\n- Confirm text is selectable/searchable when a text PDF is expected.\n- Render or preview representative pages; for short reports, prefer checking every page.\n- Inspect for blank pages, clipped charts, missing tables, missing source details, unwanted app controls, and leaked internal artifact or conversion metadata.\n- If the skill file itself was edited, run the repository's normal markdown or diff checks.\n\nExamples when available: `pdfinfo`, `pdftotext`, `pdftoppm`, file-size checks, and `git diff --check`.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/create-data-context/SKILL.md":"---\nname: create-data-context\ndescription: \"Create, update, inspect, or repair Data Analytics semantic layers. Use when the user asks to save data context or create a semantic layer that future Data Analytics work can inspect and cite.\"\n---\n\n# Create Data Context\n\nThis skill creates and maintains semantic-layer skills for Data Analytics. A semantic-layer skill is an explicit artifact the user can inspect and cite later. It captures how future analyses should interpret the data, for example which metric definition is canonical, which dashboard or table is the best source of truth, and what caveats should be checked before answering.\n\nData-task routing is owned by the Data Analytics `index` skill. If the user wants Data Analytics to do work with data now, route to `index`, whether the work starts from connected sources, uploaded files, pasted tables, sample data, or an existing semantic layer. Examples include answering a metric question, building a report, or checking a dataset.\n\nUse this skill only when the user asks to save data context or create, update, inspect, or repair a semantic layer.\n\n## Runtime Routing\n\nUse the current runtime's classified `surface` and `mode` values, plus the capabilities exposed in the run, to choose intake and persistence. Build and validate the same canonical semantic-layer skill package before writing it to any destination.\n\nFor intake:\n\n- Use structured intake when a supported form action is available.\n- Use conversational intake for open-ended details and for runtimes without a supported form action.\n\nChoose one persistence destination by default:\n\n| Destination branch | Select this branch when | Action |\n| --- | --- | --- |\n| ChatGPT personal Skills | `surface = chatgpt_web` and the run exposes a product-backed personal Skills install surface, such as a native skill draft/upload/install action or an installable skill package preview. | Install the generated skill into the user's personal Skills library. Capture the installed skill link or Skills-library reference returned by the install surface and include it as a Markdown link in the chat response. Verify through the available Skills-library, list, or fresh-thread discovery surface when the runtime exposes one. |\n| Local Codex | The user asks for local persistence, or `surface = codex_desktop`. | Write a filesystem skill to `$CODEX_HOME/skills/-semantic-layer`; if `$CODEX_HOME` is unavailable and the local runtime clearly uses the default home location, use `~/.codex/skills/-semantic-layer`. Validate the written skill and verify it is discoverable in a new local Codex context when possible. |\n| Portable package | The current run has no supported persistent skill destination. | Return a portable skill package or source plan and clearly state that it has not been installed persistently, including the exact persistence blocker. |\n\nFor dual ChatGPT web and local Codex availability, install the same canonical package into both the ChatGPT Skills library and the local Codex user-skill directory.\n\nFor ordinary data work, return to the Data Analytics `index` workflow.\n\n## Skill Configuration\n\n### Audience And Language\n\nWrite for Data Analytics users, not plugin maintainers. Explain what context would improve the current or future analysis in practical terms. Avoid implementation terms such as raw state paths, connector ids, cache, runtime, metadata, or preflight unless the user asks for debugging details.\n\n### Source Links\n\nWhen referencing sources inline, prefer clickable Markdown links over plain labels whenever a useful URL exists. Use the source title, record name, channel/thread, or meeting/date as the link text. Use plain labels only when no useful link is available.\n\n## Semantic Layer Setup\n\nUse this flow when the user wants to create or maintain a semantic layer. If they are not ready to create the layer yet, use the same flow to produce a short source plan for what the semantic layer needs.\n\nThe output is a visible skill or plan. Build the semantic-layer skill when enough source-backed detail exists to make it useful. When the available detail is still thin, return a practical plan that explains what source to collect next and why.\n\n## Creating Or Updating The Layer\n\nCreate one semantic layer per coherent product, business, metric, source, or reporting area unless the user explicitly asks for a broader shared layer. Infer the area from the provided context when it is clear; ask only when the answer changes the crawl, destination, or resulting skill.\n\nChoose the destination from `Runtime Routing` using the supported persistence mechanism exposed in the current run. For local Codex creations, default to `$CODEX_HOME/skills/-semantic-layer` unless the user chooses another destination. Ask before placing a generated semantic-layer skill inside a plugin.\n\nBefore crawling, build a data-source list that explains what was checked, what is missing, and which sources are lower-confidence. For direct creation or draft-file work, write it to `references/source-inventory.md`; for planning-only work, return it in chat.\n\nUse source-backed evidence. Favor durable sources such as transformation code, tests, maintained metric docs, and verified dashboards over looser signals such as query history or team discussion. If sources disagree, keep the conflict visible instead of choosing silently.\n\nKeep generated semantic-layer skills compact. Put detailed metric definitions, tables, query patterns, caveats, and evidence into linked references using `references/semantic-layer/skill-template.md`. Preserve provenance and avoid copying raw sensitive data, credentials, row-level examples, or long private messages into generated files.\n\nAfter creating or updating a semantic-layer skill, read `references/semantic-layer/weekly-polling-automation.md` and always offer weekly refresh when the layer has a stable target path and usable `references/source-inventory.md`. Weekly refresh is optional: do not create it without explicit user approval unless the user directly asked for recurring refresh. If the offer cannot be made, state the missing prerequisite.\n\nReturn the created or updated path or installed skill link, source coverage, any user-relevant caveats or blockers, future-use guidance, iteration guidance, and the weekly refresh automation offer or prerequisite blocker so the user can cite the semantic layer directly in later prompts. Tell the user they can ask to refine definitions, add sources, update caveats, or adjust the semantic layer as their understanding changes. For ChatGPT personal Skills creations, include the installed skill link in the response.\n\nKeep routine validation details in support artifacts unless a check failed, was unavailable, or changes how the user should rely on the semantic layer.\n\n## Output Contract\n\nFor semantic-layer work, report what was created, updated, inspected, or repaired; source coverage; any user-relevant caveats or blockers; and the exact path or installed skill link the user can cite later. For create or update results, include the weekly refresh automation offer or the missing prerequisite that prevented the offer, and let the user know they can iterate on the semantic layer. Keep routine validation details in support artifacts. If the request is ordinary data work, say that it should be routed through `index`.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/design-kpis/SKILL.md":"---\nname: design-kpis\ndescription: \"Design KPI frameworks, metric definitions, targets, guardrails, and measurement plans for product or business decisions. Use when success metrics, drivers, guardrails, targets, or the measurement approach need to be defined or improved.\"\n---\n\n# Design KPIs\n\nDesign KPI frameworks, set targets, and develop measurement plans that help teams make product or business decisions.\n\n## When To Use Data Quality First\n\nUse $analyze-data-quality first when the task is to reconcile existing metrics, dashboards, tables, owners, or sources of truth.\n\nReturn to this skill only when the user asks to define the metric going forward, redesign the KPI framework, choose guardrails, or set targets.\n\n## Skill Configuration\n\n### Source Discovery And Verification\n\nUse the relevant semantic layer as a starting map, not a boundary.\n\n1. **Explore all possible sources.** Search every connected or provided source that could contain task-relevant data or change the interpretation. Within each structured-data source, run fresh catalog or metadata discovery for relevant schemas, datasets, tables, views, models, and metrics. Known sources, tables, dashboards, and semantic mappings are starting points, not stopping points.\n2. **Compare duplicates and conflicts.** When sources overlap or disagree, compare ownership, freshness, definition, grain, coverage, and directness. Use the best authoritative source, or combine complementary sources when needed. Note material conflicts, explain why the selected source or sources control the answer, and verify selected data through live reads before concluding.\n\n### Source Access Guardrail\n\nBefore querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.\n\nIf a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.\n\nIf the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.\n\nClarify with the user when a missing input would materially change the analytical frame or recommendation. Otherwise make a reasonable assumption, state it, and proceed.\n\n## Workflow\n\n### 1. Clarify The Decision And Operating Context\n\nUnderstand the decision the metrics need to support, the context in which they will be reviewed, and who will act on the result. Ask the user to clarify the goal, operating cadence, or measurement constraints when missing or ambiguous input would change the recommendation.\n\n### 2. Gather Evidence Before Recommending Metrics\n\nWhen the prompt does not already provide enough context to know what success means, gather that context before recommending metrics or targets. Use $gather-business-context to understand the goal, current state, audience, constraints, risks, existing definitions, prior decisions, and any baseline or target context that should shape the metric system.\n\nFor KPI design, use that context to clarify what success is meant to mean, how related metrics have been defined before, and which constraints or risks should affect the recommended KPIs, drivers, guardrails, or measurement plan.\n\n### 3. Generate A Wider Candidate Set\n\nCreate candidate outcome, driver, and guardrail metrics before narrowing.\nEach candidate should have a clear definition and a plausible link to the decision. Use the example metric shapes below as inspiration when helpful, not as a required template.\n\n### 4. Compare And Select Metrics\n\nCompare candidate metrics by whether they:\n\n- reflect the goal: the metric should represent the intended outcome. When using a proxy, explain why it should reflect real progress and where it could mislead.\n- inform a real decision: movement should change what the team does, prioritizes, or investigates.\n- show useful signal at the decision cadence: a metric can be conceptually good but too slow-moving or noisy for the decision it supports. For example, annual retention may be the right outcome, but it may not help a weekly launch review unless paired with earlier indicators.\n- can be influenced by the team: the team should have plausible levers, or the metric should be paired with drivers it can affect.\n- can be measured operationally: the team should be able to instrument, calculate, and track the metric consistently without one-off manual work.\n- are hard to improve in a misleading way: improving the metric should not obviously hide harm to quality, trust, retention, cost, or another important outcome.\n\nUse lightweight scoring only when it helps explain tradeoffs. Recommend `1-3` primary KPIs, `1-2` driver metrics for each KPI when they improve diagnosis, and `1-2` guardrails when tradeoffs are likely. Do not recommend extra metrics unless they materially improve decision-making.\n\nFor each recommended metric, include enough detail for the team to use it: what it measures, why it matters, how it is calculated, where it comes from, its main pros and cons against the selection criteria above, and what caveats or guardrails matter.\n\n### 5. Set Targets When Needed\n\nTreat target setting as a separate judgment from metric selection. First decide what should be measured; then set targets when the user asks or when the recommendation needs a threshold to be useful.\n\nUse the target-setting approach that best fits the evidence:\n\n- Top-down: start from benchmarks, historical performance, comparable products, competitor or market context, or a reasoned view of what good would need to look like for the decision.\n- Bottom-up: start from what the team can realistically do, such as what is shipping, how adoption is expected to build, or which operating levers should move the metric.\n\nUse data to set or evaluate targets. Once the target-setting approach is clear, identify what data it requires, such as provided inputs, internal performance data, external benchmarks or market data, and results from similar past work.\n\nCompare aspirational targets with what the team can realistically influence through planned work, available audience, expected adoption, and historical movement. A good target should be meaningful for the decision and plausible enough to guide action. Explain the target anchor, key assumptions, and confidence. If the strongest target-setting method requires missing inputs, share the methodology and ask whether the user can provide or identify the relevant data. If there is still enough evidence for a directional target, present it as a provisional range; otherwise recommend the measurement needed before setting a firm target.\n\n### 6. Deliver The Recommendation\n\nKeep the final recommendation concise and decision-oriented, and deliver it inline by default. Do not load `$build-report` merely because the KPI framework uses evidence, compares candidates, or contains several metrics. Use `$visualize-data` and `$build-report` when a data visual would materially improve the answer, such as by showing how a proposed target compares with historical performance or benchmarks, or by clarifying tradeoffs or candidate scoring. Honor an explicitly requested report, dashboard, notebook, spreadsheet, native document, or slide deck as the primary artifact. The recommendation should include:\n\n1. initiative summary\n2. recommended metric candidates, with definition and rationale\n3. target recommendation, if included, with anchor, assumptions, and methodology\n4. evidence reviewed\n5. assumptions and missing context\n6. risks and guardrails\n7. open questions\n\n## Example Metric Shapes\n\nDifferent contexts need different metric shapes. Use these as examples, not a template:\n\n- Product launch or adoption: pair an outcome metric for adoption or value realization with drivers for activation, engagement, repeat use, or time to value, plus guardrails for experience quality.\n- Growth work: choose the business outcome the team is trying to improve, such as activation, retention, or monetization; add drivers that explain how growth is expected to happen and guardrails for quality.\n- Funnel work: choose the progression or completion outcome that represents success; add drivers around where people advance or drop off and guardrails for downstream quality.\n- Operating review: focus on health, pacing, and action-oriented metrics that show whether the business is on track and where attention is needed.\n- Experiment or intervention: use one primary success metric tied to the decision, diagnostics that explain movement, and guardrails for unintended effects.\n- Data, model, or analytics initiative: connect technical performance to the decision or workflow it improves, with adoption, reliability, cost, or fairness guardrails when relevant.\n- Platform, reliability, or operations work: measure service health, throughput, quality, cost efficiency, and customer impact in terms the owning team can act on.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/gather-business-context/SKILL.md":"---\nname: gather-business-context\ndescription: \"Gather business context from connected or provided sources so downstream analysis starts with the right framing. Use when an analytical question depends on missing context, such as what a metric means, what changed recently, or which sources should be checked. If the same prompt asks for diagnosis, recommendation, or a deliverable, gather context first and continue to the focused skill.\"\n---\n\n## Boundary\n\nUse this skill to gather framing context, not to complete the downstream analysis.\n\nIf the same request also asks for a diagnosis, recommendation, dashboard, report, or other analytical deliverable, return only the context needed for that next step and continue with the appropriate focused skill, such as $metric-diagnostics, $product-business-analysis, $build-dashboard, or $build-report.\n\n# Gather Business Context\n\nUse this skill to collect the business context needed to understand an analytical question before doing deeper work. Focus on what the topic is, why it matters, what changed or is being decided, who or what source is closest to the work, and which definitions or artifacts should frame the analysis. This is a retrieval and extraction skill: gather enough context to set up the next step, not a final report, root-cause analysis, or broad background scan. Skip it when the prompt already provides the needed context or the task is fully self-contained.\n\n## Workflow\n\n### 1. Identify The Retrieval Target\n\nEstablish the analytical topic that needs context and why it matters for the next step. Capture the boundary needed to search and interpret sources, such as the relevant product area, audience, time period, or decision. If the timeframe is missing, use the narrowest reasonable window implied by the task and label it as an assumption.\n\n### 2. Build Search Anchors\n\nSearch with concrete identifiers rather than broad topic guesses. Start with the names the user provided or the sources surfaced, then expand with adjacent terms that help recall, such as aliases, owners, teams, dates, source names, related entities, or entities found in earlier results.\n\nStart broad enough to avoid missing relevant context. If too much comes back and a quick scan suggests the results are mostly unrelated, combine anchors to narrow retrieval, for example a metric plus a dashboard name, a feature plus a launch window, or a customer plus the relevant workflow. If a likely source comes back thin, revise the anchors before treating the source as missing.\n\n### 3. Search From Discovery Points Toward Authoritative Artifacts\n\n1. **Explore all possible sources.** Search every enabled or provided source family that could contain useful context or task-relevant data. Within each structured-data source, run fresh catalog or metadata discovery for relevant schemas, datasets, tables, views, models, and metrics. User-named sources, known tables, dashboards, and semantic-layer anchors are starting points, not stopping points.\n2. **Compare duplicates and conflicts.** When sources overlap or disagree, compare authority, freshness, definition, scope, and directness. Prefer artifacts closest to what was decided, defined, implemented, or measured; follow linked evidence when useful. Note material conflicts and explain which source or combination should guide downstream analysis.\n\n### 4. Extract Only Decision-Shaping Context\n\nTreat business context as a fixed extraction target, not an open-ended summary. Capture the facts that will shape the downstream analysis: the topic's business meaning, why it matters now, how it is defined or measured, where to verify it, what recently changed, and what uncertainty should travel with the analysis. Examples can include a metric definition, current rollout state, dashboard link, owner note, source conflict, or stated next step.\n\nKeep the context note focused on details that help frame the next analysis. Skip broad background, adjacent history, or long source excerpts unless they add useful context.\n\n### 5. Keep Source Notes Compact And Attributable\n\nFor each useful source, record enough attribution for the downstream work to be checked later: when the source applies, what kind of source it is, what factual context it established, and any important caveat or conflict. Distinguish source facts from inference and do not imply source review, stakeholder views, metric certainty, or confidence beyond what was actually established.\n\n### 6. Reconcile Conflicts Explicitly\n\nWhen sources disagree in a way that could change the downstream framing, preserve the disagreement instead of smoothing it over. Prefer the newest explicit decision artifact over older plans, owner-written docs over third-party summaries, and implementation artifacts over aspirational plans when the question is what is live, shipped, logged, or queryable now. Treat an informal source as stronger than a canonical artifact only when it clearly records a later decision or owner confirmation.\n\nIf disagreement remains, present both views, label the conflict, and state what source or owner would resolve it. If context is stale or incomplete, say what is missing and where to look next.\n\n### 7. Stop Once The Framing Is Sound\n\nStop gathering context when the downstream task can be framed well enough to proceed and the likely enabled or provided source families have been checked, ruled out as unavailable, or identified as too thin. Before stopping, make sure the next step has a clear enough understanding of the topic, why it matters, where the important definitions came from, what recent context applies, and what gaps remain.\n\nContinue searching when a relevant enabled or provided source is likely to add useful context. If an expected source was not found, name that as a gap rather than implying it does not exist.\n\n### 8. Return A Lightweight Context Note When Useful\n\nPrefer a focused context note over a full report or raw retrieval dump. Include enough context for the next analysis to proceed without redoing the search: a short summary, the relevant context, important definitions or source links, uncertainty or caveats, and citations. Keep it readable, but do not compress away details that explain the framing or source quality.\n\nIf the user asked only for quick orientation, shorten the structure while preserving citations, conflicts, and missing canonical artifacts.\n\n## Standards\n\nJudge sources by what they can actually establish. Informal discussion can be useful for discovery and recent context, but durable artifacts are usually stronger evidence for definitions, decisions, status, and measured results once found. Prefer sources close to the work, recent enough to reflect current reality, and explicit about what they establish. Surface missing source-of-truth artifacts as context gaps.\n\nKeep important claims attributable. Treat a source as useful only when it clarifies how the downstream task should be framed or interpreted; sources that merely mention the topic are incidental. Preserve enough evidence to check the work later, and label interpretation, assumptions, conflicts, and uncertainty when support is thin, stale, indirect, or conflicting.\n\nPreserve disagreements that could change the framing. Prefer owner-authored or decision-adjacent material and evidence of what is current over secondhand summaries or speculation. Do not infer consensus from silence. Say what source or owner would resolve an important conflict.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/index/SKILL.md":"---\nname: index\ndescription: \"Route broad Data Analytics requests to the appropriate quantitative analysis, visualization, dashboard, report, notebook, KPI, market-sizing, validation, or semantic-layer workflow.\"\n---\n\n# Data Analytics Router\n\nUse this workflow when Data Analytics is explicitly invoked or the request requires structured records, quantitative evidence, metrics, or an evidence-backed product or business decision. Do not use it for ordinary prose drafting, file-format conversion, or qualitative description that does not require data interpretation.\n\n## Choose the focused workflow\n\n- Metric changed, missed a target, or differs from expectation: read `../metric-diagnostics/SKILL.md`.\n- Product or business decision, prioritization, segmentation, launch, or experiment recommendation: read `../product-business-analysis/SKILL.md`.\n- Dataset, dashboard, source, join, freshness, grain, or metric trust question: read `../analyze-data-quality/SKILL.md`.\n- KPI framework, canonical definition, target, driver, or guardrail design: read `../design-kpis/SKILL.md`.\n- KPI status update, WBR, MBR, QBR, or operating readout: read `../kpi-reporting/SKILL.md`.\n- Dashboard or monitoring view: read `../build-dashboard/SKILL.md`.\n- Durable analytical report: read `../build-report/SKILL.md`.\n- Chart or quantitative figure: read `../visualize-data/SKILL.md`.\n- Reproducible SQL/Python notebook: read `../jupyter-notebooks/SKILL.md`.\n- TAM, SAM, SOM, segment, or opportunity sizing: read `../market-sizing/SKILL.md`.\n- Review an analysis before sharing: read `../validate-data/SKILL.md`.\n- Create, repair, or save reusable data context or a semantic layer: read `../create-data-context/SKILL.md`.\n- Missing business definitions, ownership, change context, or decision framing: read `../gather-business-context/SKILL.md` before the primary workflow.\n\nLoad every selected workflow completely. Follow its related-skill rules when applicable. A task can combine workflows; use this usual order:\n\n1. Gather missing business context.\n2. Validate source quality and metric definitions.\n3. Perform the focused analysis.\n4. Validate conclusions.\n5. Visualize or create the requested durable artifact.\n\n## Source access\n\nUse the best source already available through the code-agent harness: local files, uploaded data, pasted results, databases, warehouses, BI systems, product analytics tools, notebooks, documents, or callable connectors. Tool availability is determined by the host, not by this skill.\n\nWhen no usable source is available:\n\n- Ask for the smallest useful artifact: a CSV/XLSX file, query result, schema, metric definition, dashboard export, screenshot, or pasted table.\n- Offer `assets/demo-product-growth.csv` only as a clearly labeled synthetic demonstration. Never use sample data to answer a real-data question.\n- Do not invent records, measurements, source access, or query results.\n\nIf available sources conflict in a way that changes the answer, surface the conflict and use the data-quality workflow. Otherwise choose the most authoritative and fresh source and proceed.\n\n## Portable output policy\n\nThis bundle targets a generic code agent and does not depend on React, MCP Apps, widgets, or a proprietary rendering surface.\n\n- Inline answers: concise Markdown with findings, evidence, caveats, and next actions.\n- Reports: Markdown by default; use self-contained plain HTML, PDF, DOCX, or another requested format only when the host can create and verify it.\n- Charts: use reproducible Python/Matplotlib, notebook-native plotting, SVG, or destination-native chart tools.\n- Dashboards: prefer a self-contained plain HTML/JavaScript artifact, Streamlit when Python execution is appropriate, or an existing BI platform selected by the user.\n- Notebooks: keep SQL/Python reproducible and make assumptions visible.\n\nPreserve source names, metric definitions, grain, time windows, filters, units, and uncertainty. Never expose credentials, secrets, hidden reasoning, or unnecessary personal data.\n\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/jupyter-notebooks/SKILL.md":"---\nname: jupyter-notebooks\ndescription: \"Create, edit, or validate reproducible SQL or Python notebooks. Use for notebooks, SQL/Python scratchpads, reproducible exploration, audit trails, or runnable companions where the analysis should be reviewable or rerunnable.\"\n---\n\n## Related Skills\n\nUse $validate-data when notebook results support a recommendation, shared claim, or decision.\n\n# Jupyter Notebooks\n\nCreate clean, reproducible Jupyter notebooks that are easy to skim, rerun, and handoff. Treat the notebook as a reader-facing analysis artifact, not a scratchpad dump. Notebook work is not complete until the notebook executes successfully top-to-bottom, or the execution gap is called out with the exact validation steps needed to reproduce it.\n\n## Workflow\n\n1. Lock the notebook mode and scope.\n\n Decide whether the notebook is an analysis report, experiment log, diagnostic notebook, data-quality check, market-sizing calculation, model exploration,\n tutorial, or companion artifact for a report. Identify the reader, decision,\n expected handoff, required inputs, and whether the task calls for a new notebook or targeted edits to an existing one.\n\n2. Inspect or scaffold with notebook-safe tooling.\n\n Prefer JupyterLab, `nbformat`, `nbclient`, or an existing scaffold utility over hand-editing raw JSON. When editing an existing notebook, preserve its intent and minimize JSON churn. Avoid reordering cells unless it clearly improves the top-to-bottom story. If raw JSON editing is unavoidable,\n validate the notebook structure before finishing.\n\n3. Structure the notebook for the chosen mode.\n\n For analytical notebooks, default to:\n\n 1. `## tl;dr`\n 2. `## Context & Methods`\n 3. `## Data`\n 4. `## Results`\n 5. `## Takeaways`\n\n Write `tl;dr` and takeaways after reviewing executed outputs. Use concrete observed values, visible patterns, rows, or charts, not assumptions. Include a `### Key Assumptions` subsection in `Context & Methods` when assumptions affect correctness.\n\n For tutorials or walkthroughs, adapt the same discipline to a teaching flow:\n\n 1. `## Goal`\n 2. `## Setup`\n 3. `## Steps`\n 4. `## Checks`\n 5. `## Next Steps`\n\n4. Build a clear data and computation path.\n\n Separate setup, imports, parameters, data loading, data preparation,\n calculations, visualizations, and interpretation. If the notebook uses both SQL and Python, keep complex SQL in SQL cells or separate query files rather than large embedded Python strings unless there is a clear reason. Use descriptive variable names and keep each code cell focused on one step.\n\n5. Use data sources deliberately.\n\n When a notebook needs table data, first use `~~structured_data` to confirm table choice, schema, partition filters, sample rows, and query-submission policy. Use the relevant source connector when available, then fall back to exports or pasted SQL when needed. Use `~~operations_logs` for freshness or lineage checks when they matter. Record query permalinks, request IDs, source paths, dashboard links,\n extract names, or other source artifacts in the notebook context for any executed result that supports the analysis. Keep heavy queries filtered and bounded instead of turning the notebook into a broad live-source scan.\n\n6. Make cells readable and bounded.\n\n Add concise markdown headers before most code cells. Keep headers brief and action-oriented, such as `### 1. Load Data`, `### 2. Validate Inputs`, or `### 3. Plot Results`. Favor several short cells over one large mixed-purpose cell. Keep prose short: explain purpose, assumptions, and expected result, not every line of code. Split multiple tables or charts across separate cells instead of dumping all outputs from one cell.\n\n7. Validate results before writing conclusions.\n\n Check that key numbers, charts, and takeaways match executed outputs. Bound raw debug output, oversized tables, and noisy logs. If a result is surprising, add a local reasonableness check, small sample inspection, or reconciliation against a trusted source before promoting it to the summary.\n\n8. Execute and record validation status.\n\n Run the notebook top-to-bottom when the environment allows:\n\n ```bash\n python -m jupyter nbconvert --execute --to notebook --inplace path/to/notebook.ipynb\n ```\n\n Optional local setup when needed:\n\n ```bash\n uv pip install jupyterlab nbformat nbclient ipykernel\n ```\n\n If execution is not possible, say so explicitly and provide the exact command,\n missing dependency, credential, data access, kernel, or environment step needed to validate locally.\n\n## Standards\n\n### Notebook Structure\n\n- Make the default top-to-bottom read clear before the reader starts executing cells out of order.\n- Put executive summary material at the top, but write it last after inspecting executed results.\n- Keep notebook sections aligned with the notebook mode: analysis, experiment,\n diagnostic, tutorial, or handoff artifact.\n- Keep section titles, chart titles, labels, and file names descriptive enough for handoff.\n- Preserve the existing notebook's intent when refactoring; improve structure without rewriting everything by default.\n\n### Reproducibility\n\n- Keep parameters, date ranges, filters, cohorts, assumptions, and source references visible near the top of the notebook.\n- Record enough source context for another reader to trace the analysis: query permalinks, request IDs, table names, source paths, spreadsheet tabs,\n dashboard links, extract versions, or input file locations.\n- Make computation deterministic where possible. Avoid hidden state, manually edited intermediate values, out-of-order dependencies, and unexplained cached outputs.\n- Prefer explicit environment setup cells or notes when the notebook depends on nonstandard packages, kernels, credentials, or local files.\n- Execute the notebook when the task requires a runnable artifact. In the final response, do not add a separate routine validation section for a clean run; surface execution gaps, partial execution, or unrun notebooks with the reason because those affect whether the user can rely on the artifact.\n\n### Code And Data Hygiene\n\n- Separate data preparation from presentation.\n- Keep complex SQL readable and documented with a one-line goal comment.\n- Keep plotting and lightweight shaping in Python after the data preparation step is complete.\n- Use descriptive variable names and avoid abbreviated temporary names in reader-facing notebooks.\n- Keep outputs bounded. Prefer small preview tables, sampled rows, explicit limits, and focused charts over raw dumps.\n- Avoid broad live-source scans. Filter queries by needed partitions, cohorts,\n or time windows.\n\n### Analysis Quality\n\n- Make assumptions explicit when they affect interpretation.\n- Tie takeaways to executed outputs with concrete numbers, rows, charts, or visible patterns.\n- Do not promote unexecuted or unverified calculations into the `tl;dr`.\n- Label caveats, incomplete checks, missing source access, and known validation gaps.\n- Add reasonableness checks for surprising results, high-impact claims, or stakeholder-facing conclusions.\n\n### Validation Checklist\n\n- Required section order is present for the notebook mode.\n- The notebook executes without runtime errors, or execution failure is called out explicitly.\n- Outputs are present where expected and are not dominated by raw debug dumps.\n- The `tl;dr`, results, and takeaways match executed cells.\n- Source references and query or artifact links are preserved.\n- Tables and charts are labeled, bounded, and interpretable.\n- The final response includes the notebook path and validation status.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/kpi-reporting/SKILL.md":"---\nname: kpi-reporting\ndescription: \"Prepare KPI readouts, scorecards, WBR/MBR/QBR updates, and executive summaries from quantitative business or product metrics; use when the task is to report status, compare against targets, explain validated drivers, and state operating implications.\"\n---\n# KPI Reporting\n\nUse this skill to turn business or product metrics into decision-ready operating readouts for leaders and teams. The job is to define the KPI contract, report status against the right comparison and target, include validated driver context, and state the operating implication clearly.\n\nClarify with the user when a missing input would materially change the analytical frame or recommendation. Otherwise make a reasonable assumption, state it, and proceed.\n\nThis skill owns the KPI readout: what should be reported, how metrics should be interpreted, whether driver context is validated, and what operating takeaway follows. It does not own metric-system design, new driver investigation, or final artifact polish.\n\nUse $metric-diagnostics when the readout needs fresh driver investigation, then return here to package the validated finding.\n\n## Skill Configuration\n\n### Source Discovery And Verification\n\nUse the relevant semantic layer as a starting map, not a boundary.\n\n1. **Explore all possible sources.** Search every connected or provided source that could contain task-relevant data or change the interpretation. Within each structured-data source, run fresh catalog or metadata discovery for relevant schemas, datasets, tables, views, models, and metrics. Known sources, tables, dashboards, and semantic mappings are starting points, not stopping points.\n2. **Compare duplicates and conflicts.** When sources overlap or disagree, compare ownership, freshness, definition, grain, coverage, and directness. Use the best authoritative source, or combine complementary sources when needed. Note material conflicts, explain why the selected source or sources control the answer, and verify selected data through live reads before concluding.\n\n### Source Access Guardrail\n\nBefore querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.\n\nIf a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.\n\nIf the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.\n\n## Workflow\n\n### 1. Clarify The Readout Purpose\n\nUnderstand who the readout is for, what conversation it supports, and what is being reported before drafting. Anchor the update in the period being evaluated, the comparison or target that makes performance interpretable, and the freshness cutoff.\n\nAsk the user for missing context when it would help make the readout more accurate or useful.\n\n### 2. Define The Metric Framework\n\nDecide which metrics belong in the readout and what role each one plays before pulling numbers. If the framework already exists, confirm it and use it. If it is missing or weak, use $design-kpis before reporting.\n\nStart with the primary KPI, then add the smallest set of supporting metrics needed to explain status. Supporting metrics can explain movement, guard against harmful tradeoffs, or show whether performance is pacing as expected.\n\nLead with the metric that matters most to the audience. Do not add every available cut or comparison; include the metrics and slices decision-makers actually use, plus any that materially explain this update.\n\nWhen the primary KPI is top-line, composite, or otherwise not directly actionable, define its driver decomposition before interpreting it. Use an existing metric tree when available. Otherwise identify the smallest useful set of component drivers, such as numerator and denominator, volume and rate, mix, funnel stages, segments, cohorts, or operational inputs. Do not invent a causal hierarchy when source definitions do not support one.\n\n### 3. Lock Metric Definitions And Sources\n\nConfirm the KPI definition, source, time window, reporting cutoff, comparison period, and any target or pacing expectation before interpreting performance. If a target or pacing basis is missing, ask before treating one as authoritative. Use $analyze-data-quality when source quality issues could change the reported metrics.\n\nFor all KPI updates, make a focused source pass across `~~structured_data`, `~~company_docs`, `~~team_communication`, and `~~dashboards_or_bi` before drafting. Do not infer from a sparse prompt that source-backed actuals are unavailable. Use structured data for actuals, metric definitions, and comparison periods; use the other lanes for additional business context and source-of-truth guidance.\n\nIf any core definition is unclear, ask the user to clarify before making precise claims. When a metric definition changed, show comparable restated history when available; otherwise call out the break clearly.\n\n### 4. Pull The Topline Actuals\n\nDo not draft or render a WBR, MBR, scorecard, or KPI update from placeholders. Query or inspect connected structured-data sources for core actuals first. If actuals are blocked or insufficient, stop and say what source or access is needed unless the user explicitly asked for a template or mockup.\n\nReproduce the topline actual before explaining movement or driver context.\n\nFor each headline KPI, include the current value, the absolute and relative change versus the comparison period, and a short interpretation.\n\nCall out anything that makes the current value hard to compare with the prior period before interpreting the movement, such as a tracking change, data backfill, partial outage, or missing day.\n\n### 5. Put The Numbers In Context\n\nCompare actuals against the context that makes performance interpretable. When a target, plan, pacing model, benchmark, historical range, or relevant peer group is defined, identify it and compare performance against it before judging status.\n\nIf the goal has a deadline, do not just report whether the metric is above or below target. Show whether it is on pace to hit the target by the end of the period. Use the provided pacing definition when available. If none is defined or found, ask the user; when proceeding with a calculated fallback, state that it was calculated and explain the method.\n\nWhen useful, include absolute and percent variance to target and a red/yellow/green status. Make clear what comparison or pacing basis the status label uses.\n\n### 6. Explain Validated Drivers\n\nKPI updates need driver context, but driver claims must be validated before they are presented as explanations. A plausible story is not enough.\n\nWhen the readout needs to explain drivers, use $metric-diagnostics to identify and validate them. If trusted reporting or prior analysis already validates the drivers, use that evidence instead of re-running the diagnostic.\n\n### 7. Add Business Context And Operating Implications\n\nAfter identifying the likely drivers, use $gather-business-context to look for business context that helps explain what happened and what it means for the readout. Let the driver analysis guide what context to look for, and connect context to the metric only when evidence supports the link.\n\nTranslate the evidence, driver analysis, and business context into the operating implication for the business. State whether the movement is concerning, what next step or action is warranted, and whether the main KPI is on track, at risk, or ahead of plan. Recommend action only when the evidence supports it; otherwise name the next validation step.\n\n### 8. Validate The Readout\n\nAfter the analysis is assembled and before shaping the final readout, use $validate-data to review whether the numbers, methodology, caveats, and evidence support the claimed status, drivers, and implications. Resolve material issues before sharing; carry remaining limitations into the readout.\n\n### 9. Hand Off The Readout\n\nEnd by handing the validated KPI readout to $build-report unless the user explicitly requests an inline, chat-only, brief/no-artifact answer, asks not to create a report/file/artifact, or selects another primary artifact. A quick status update, brief readout, or findings-in-chat request is an inline output choice unless the user also asks for a report, document, deck, or durable artifact. When no explicit human waiver was given, the report handoff is mandatory; do not infer a waiver only because the user did not use the word \"report\".\n\nBefore handoff, make the readout explicit:\n\n- headline status and operating implication\n- actuals, targets, pacing basis, and comparison periods\n- validated drivers and unresolved uncertainty\n- audience, cadence, and requested delivery surface when known\n- charts or figures that would clarify the readout\n\nLoad `references/report-templates.md` before handing off and use the matching pattern as source notes for $build-report. Tell $build-report this is a KPI readout and pass the status, pacing, driver, uncertainty, audience, cadence, surface, and visual guidance above. Do not render charts directly from this skill; pass visual intent and supporting evidence to $build-report so $visualize-data owns chart selection and QA.\n\nFor slide or deck requests, use $build-report to create a portable source report first, then use an available presentation workflow or document tool to create and verify the deck. Preserve the same source evidence and findings across formats.\n\n## Standards\n\n### Metric Standards\n\n- Never present a KPI as precise when its definition, source, time window, or comparison basis is unclear.\n- Make calculation logic, inclusion or exclusion rules, grain, and time treatment explicit when they affect interpretation.\n- Reconcile totals and compare against prior reporting when possible.\n- Do not compare periods, cuts, or targets that are not definitionally compatible. Call out definition changes, backfills, denominator shifts, or calendar effects when they affect the movement.\n\n### Status And Pacing Standards\n\n- Include the headline takeaway, current actual, relevant comparison, target or pacing context, driver summary, and implication unless the user asks for a narrower readout.\n- Put actuals next to the target, plan, benchmark, or baseline when available so the reader can judge performance immediately.\n- If a target is time-bound, show whether current performance is on pace using the provided pacing definition or a clearly stated calculated fallback.\n- Keep recurring metric sections consistent across runs. If a requested section is missing because data, definitions, or validation are unavailable, explain the omission briefly.\n- Use traffic-signal status only when it helps prioritize action. Pair color with text and state the basis for the status.\n- Round numbers consistently, label units, and surface caveats when they change interpretation.\n\n### Driver Standards\n\n- Quantify drivers whenever the evidence supports it; do not use descriptive prose as a substitute for sizing the effect.\n- Report the few drivers, contributors, or known non-drivers that matter for interpreting the KPI movement.\n- For top-line KPI movement, structure validated drivers as a compact decomposition: top-line actual, component drivers, largest contributors or non-drivers, and residual or unresolved movement. Use an additive bridge only when the components reconcile cleanly; otherwise explain the relationship and uncertainty.\n- Separate validated drivers from business context or hypotheses.\n- Do not elevate business events into causes unless the timing, affected population, and measured change support the link.\n- State whether the movement is broad-based or concentrated when that changes the operating implication.\n- If driver evidence remains unresolved, name the uncertainty or diagnostic follow-up instead of inventing an explanation.\n\n### Presentation Standards\n\n- Write for executives and operators who skim: lead with the answer, then the evidence.\n- Use business-readable numbers and compact formats such as `123k (+8% w/w, +19% m/m)`.\n- Replace generic adjectives like `strong`, `healthy`, or `soft` with the metric evidence that justifies them.\n- Keep caveats close to the claim they affect, and omit caveats that do not change interpretation.\n- Use charts, tables, scorecards, or KPI cards only when they make the takeaway easier to understand and remain readable in the final delivery context.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/market-sizing/SKILL.md":"---\nname: market-sizing\ndescription: \"Estimate market, segment, or opportunity size with transparent assumptions and uncertainty. Use for TAM/SAM/SOM, sizing scenarios, or comparing the scale of possible opportunities.\"\n---\n\n## Related Skills\n\nUse $visualize-data when the sizing result needs a chart or figure.\n\nUse $build-report to package the final estimate, assumptions, sensitivity, caveats, and source context whenever this skill is selected, unless the user explicitly requests an inline, chat-only, brief/no-artifact answer, asks not to create a report/file/artifact, or selects another primary artifact.\n\n# Market Sizing\n\nUse this skill to produce a defensible estimate of a market or opportunity from connected context, public sources, transparent assumptions, and auditable calculations. The job is to define the market, choose a sound sizing method, distinguish evidence from assumptions, test sensitivity, and state what would most improve confidence.\n\n## Skill Configuration\n\n### Source Discovery And Verification\n\nUse the relevant semantic layer as a starting map, not a boundary.\n\n1. **Explore all possible sources.** Search every connected or provided source that could contain task-relevant data or change the interpretation. Within each structured-data source, run fresh catalog or metadata discovery for relevant schemas, datasets, tables, views, models, and metrics. Known sources, tables, dashboards, and semantic mappings are starting points, not stopping points.\n2. **Compare duplicates and conflicts.** When sources overlap or disagree, compare ownership, freshness, definition, grain, coverage, and directness. Use the best authoritative source, or combine complementary sources when needed. Note material conflicts, explain why the selected source or sources control the answer, and verify selected data through live reads before concluding.\n\n### Source Access Guardrail\n\nBefore querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.\n\nIf a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.\n\nIf the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.\n\nClarify with the user when a missing input would materially change the estimate or recommendation. Otherwise make a reasonable assumption, state it, and proceed.\n\n## Workflow\n\n### 1. Frame The Market Or Opportunity\n\nDefine the market or opportunity boundary before estimating:\n\n- What is being sized, for example a product category, workflow, problem, use case, or category of activity.\n- Where and when it applies, for example geography, segment scope, time horizon, or market maturity.\n- Who or what counts as part of the market, for example the relevant population, unit of demand, transaction type, or included activity.\n- How the opportunity is measured, for example spend, revenue, volume, value created, or another unit that fits the question.\n- What kind of sizing answer the user needs, for example TAM/SAM/SOM, market entry, expansion upside, spend pool, revenue pool, population count, or unit volume.\n\n### 2. Choose A Starting Sizing Approach And Inputs\n\nPick the simplest sound sizing approach for the question, then sketch the calculation chain and the major inputs the estimate will depend on.\n\nA top-down model works when reliable aggregate market data exists; a bottom-up model works when the market can be built from observable units and assumptions; a value-based model works when the estimate should start from the value created rather than a published market total. Use a mixed approach only when cross-checking would materially improve confidence. If more than one approach fits, briefly explain which one you trust most and why.\n\nExpect the first approach to change if source checks show that another model would be more defensible.\n\n### 3. Gather Sources For The Inputs\n\nChoose sources based on the inputs the estimate depends on most.\n\nStart with user-named sources when provided. Then use the strongest available evidence for each major input from the starting approach. Use `~~structured_data` when an input should come from the user's data warehouse or another structured data source. Use context lanes such as `~~company_docs`, `~~team_communication`, or `~~dashboards_or_bi` when an input needs business meaning, source-of-truth guidance, or assumptions that are not captured in structured data alone. When an input depends on the outside market, use public sources for benchmarks, population estimates, comparable markets, or proxy assumptions.\n\nUse $gather-business-context to resolve context lanes when the right source of truth, business meaning, or assumption set is unclear.\n\nIf the strongest source is unavailable or thin, continue with a transparent proxy assumption only when the estimate is still useful. Label the gap and explain how it affects confidence.\n\n### 4. Separate Facts From Assumptions\n\nKeep sourced facts, inferred estimates, and judgment calls distinct in the model. When exact data is unavailable, use a defensible proxy, explain why it is reasonable, and note the confidence level. Ground assumptions in evidence about how the market actually behaves, what can realistically change, and what determines the size of the opportunity.\n\n### 5. Build The Model\n\nMake the model easy to inspect and adjust.\n\nThe model should make these elements easy to audit or revise:\n\n- market definition and measurement unit\n- assumptions and source context\n- calculation chain and derived values\n- base case, material ranges, and sensitivity logic\n- validation priorities\n\nFor each major input, make the source path visible: structured data, context lane, public source, user-provided input, or proxy assumption.\n\nKeep derived values traceable to formulas or code rather than hardcoded outputs.\n\nUse $jupyter-notebooks when code is needed for source harmonization, calculations, sensitivity analysis, or reusable modeling logic. Keep formulas, inputs, intermediate calculations, and sensitivity logic inspectable.\n\nUse the `$Spreadsheets` skill when the user requests a spreadsheet, workbook, or Google Sheets deliverable, or when a market-sizing model would materially benefit from editable assumptions, sensitivity tables, charts, or polished workbook formatting.\n\n### 6. Test Sensitivity\n\nIdentify the assumptions that move the estimate most.\n\nShow how the estimate changes when those assumptions move up or down. Prefer simple, decision-useful sensitivity analysis over exhaustive scenario sprawl.\n\nUse ranges when uncertainty is material. Do not hide uncertainty behind a single point estimate when the inputs are thin.\n\n### 7. State The Estimate And Validation Priorities\n\nEnd by handing the estimate, method, key assumptions, uncertainty, and next validation priorities to $build-report unless the user explicitly waives report creation or selects another primary artifact. This handoff is mandatory when no explicit human waiver was given; do not infer a waiver because the user asked for an estimate or did not use the word \"report\". This workflow owns the sizing model and conclusion; $build-report owns the reader-facing structure, visuals, evidence placement, and delivery surface.\n\nBefore handoff, make the market-sizing conclusion explicit:\n\n- market definition and measurement unit\n- estimate or range\n- method and calculation chain\n- key assumptions and source support\n- main uncertainty drivers and sensitivity takeaways\n- validation priorities and practical interpretation for the user's decision\n\nIf source coverage is thin, say which major inputs rely on proxy assumptions and what source would most improve them.\n\nUse $validate-data when methodology, calculations, assumptions, caveats, or source support need review before sharing.\n\nDo not render charts directly from this skill. If a sensitivity, scenario, funnel, or market-breakdown visual would clarify the estimate, pass that visual intent and supporting evidence to $build-report so $visualize-data owns chart selection and QA.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/metric-diagnostics/SKILL.md":"---\nname: metric-diagnostics\ndescription: \"Diagnose why a metric changed or differs from expectation. Use when the task is to identify likely drivers of a metric movement, anomaly, gap, or discrepancy.\"\n---\n\n## Related Skills\n\nUse $gather-business-context when business context is needed to understand the metric, analysis period, ownership, or plausible explanations.\n\nUse $product-business-analysis when the task asks for a recommendation or tradeoff decision after diagnosing the movement.\n\nUse $analyze-data-quality when dashboard trust, grain, freshness, or source disagreement could affect the metric.\n\n# Metric Diagnostics\n\nUse this skill to diagnose why a metric changed or differs from expectation. Reproduce the metric, define the comparison, quantify the movement, validate likely drivers, and state what is verified, likely, unresolved, and useful to do next.\n\nClarify with the user when a missing input would materially change the analytical frame or recommendation. Otherwise make a reasonable assumption, state it, and proceed.\n\n## Skill Configuration\n\n### Source Discovery And Verification\n\nUse the relevant semantic layer as a starting map, not a boundary.\n\n1. **Explore all possible sources.** Search every connected or provided source that could contain task-relevant data or change the interpretation. Within each structured-data source, run fresh catalog or metadata discovery for relevant schemas, datasets, tables, views, models, and metrics. Known sources, tables, dashboards, and semantic mappings are starting points, not stopping points.\n2. **Compare duplicates and conflicts.** When sources overlap or disagree, compare ownership, freshness, definition, grain, coverage, and directness. Use the best authoritative source, or combine complementary sources when needed. Note material conflicts, explain why the selected source or sources control the answer, and verify selected data through live reads before concluding.\n\n### Source Access Guardrail\n\nBefore querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.\n\nIf a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.\n\nIf the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.\n\n## Workflow\n\n### 1. Define The Diagnostic Question\n\nFrame the diagnostic so it is clear what changed and what comparison would prove it.\n\nDefine:\n\n- what the metric means in business terms\n- the time window and comparison that make the change measurable\n- the population and grain that determine what counts\n- the source that owns the metric definition\n- the diagnostic question being answered, for example movement, concentration, or reconciliation\n\nUse $gather-business-context when business context is needed to understand what the metric means, what changed around the analysis period, or which explanations are plausible.\n\n### 2. Validate The Metric Definition And Source\n\nBefore explaining the movement, confirm that the metric is defined correctly and that the source data can measure it reliably.\n\nConfirm the metric definition, grain, aggregation logic, filters, joins, exclusions, freshness, lineage, and any disagreement between trusted surfaces. Keep this source check focused on issues that could change the answer.\n\nTreat current context, named semantic layers, and familiar table names as source candidates, not source selection. For broad metric questions, run live source discovery against available tables, dashboards, metric docs, semantic layers, or other source-of-truth surfaces before choosing the controlling source. When both are available, inspect at least one business-facing or top-line surface and one lower-level source surface, then state why the selected source owns the answer.\n\nUse $analyze-data-quality when freshness, grain, joins, missingness, schema drift, outliers, unexpected categories, or distribution shifts could affect trust.\n\nUse $jupyter-notebooks when fresh SQL, Python, statistical modeling, reusable calculations, or multi-step decomposition need an inspectable analytical record.\n\n### 3. Establish The Metric Pattern\n\nBefore looking for drivers, establish the metric pattern the diagnostic needs to explain. Quantify the metric over the relevant period and scope. If the question includes a comparison, reproduce that comparison.\n\nDo not search for causes until the size, timing, and scope of the pattern are verified or explicitly marked uncertain.\n\n### 4. Choose The Diagnostic Plan\n\nChoose the smallest set of cuts and checks likely to explain the pattern or strengthen confidence.\n\nChoose driver dimensions from the metric's operating logic, business context, and source shape. Prioritize drivers the business usually monitors or can act on, not every field available in the source. If the relevant drivers are unclear, use current context, a named semantic layer, or $gather-business-context to understand how the business explains the metric and what changed around the analysis period.\n\nWhen using a lower-level table, do not limit the driver analysis to fields surfaced by the first query. Recreate or join the business grouping needed to answer the question, such as model family, model superfamily, segment, region, cohort, product taxonomy, or customer hierarchy. If the grouping cannot be reconstructed, say so before simplifying the analysis.\n\nUse the explanation mode that fits the question. Common examples:\n\n- **Metric change**: compare the focal window with a baseline, rank segment contributions, check peer or historical context, and test mix shift versus within-segment movement.\n- **Spike, regression, or incident**: pin down onset, peak, recovery,\n distribution shape rather than only averages, affected slices, broad versus localized degradation, and whether traffic or failure behavior changed.\n- **Largest contributors or concentration**: define \"largest\", rank entities,\n compare total share and change, and look for major movers, entrants, and exits.\n- **Reconciliation or difference analysis**: align definitions, filters, grain,\n numerator, denominator, and exclusions; quantify the components explaining the gap and state any residual.\n\n### 5. Decompose And Validate Drivers\n\nQuantify the main drivers and validate whether they explain the pattern.\n\nSize each major driver with the strongest readily available evidence. Show whether it explains the pattern, how large it is relative to the relevant base, trend, or gap, whether it is broad or concentrated, and whether it holds under the right comparison or scope.\n\nIterate on driver hypotheses until the explanation answers why in a way that is relevant to the business. Follow promising cross-cuts and drill-downs when they could reveal the key explanation, and stop when additional cuts are unlikely to change the conclusion or materially improve confidence.\n\nInterpret driver results in context:\n\n- Use the relevant base, comparison, or share of total to make the driver meaningful.\n- For rates, check whether the numerator, denominator, or both explain the change.\n- For additive metrics, calculate contribution share when it sharpens the story.\n- Separate composition effects from within-segment performance effects when that distinction changes the explanation.\n- Prefer mutually exclusive driver buckets when additive contributions need to be interpreted; reconcile the decomposition exactly or size and explain the residual.\n\nTreat measurement issues as possible explanations, not just cleanup details. For example, the pattern may come from logging changes, incomplete recent data, duplicated rows, or a shifted denominator rather than an underlying business change.\n\nCalibrate the explanation to the evidence, and make important uncertainty visible. Use context when it changes interpretation, such as whether the pattern is ordinary, unusual, expected, or tied to a known change.\n\nUse $visualize-data when a chart would make the diagnostic claim easier to understand or verify.\n\n### 6. State Implications And Follow-Up\n\nLead with the answer to the diagnostic question, then state the practical implications when the evidence supports them.\n\nThe answer should make clear:\n\n- the pattern being explained\n- the strongest driver explanation and supporting evidence\n- why it matters for the business\n- how much confidence to place in the explanation\n- the implication, next action, or follow-up that matters most\n\nUse $product-business-analysis when the user needs a recommendation or tradeoff decision, not just the diagnostic implication.\n\nKeep implications distinguishable from verified factual reporting so a reader can tell where evidence ends and interpretation begins. Do not claim causality from timing alone; state when an explanation is only a plausible hypothesis.\n\nUse $gather-business-context when the metric result is clear but business context is needed to interpret the `so what` or identify realistic next actions.\n\nUse $validate-data when methodology, calculations, caveats, or the evidentiary support for the diagnostic conclusion need review before sharing.\n\nDo not treat artifact or report validation as analytical validation. Before handing off, confirm the analysis has the headline metric movement, driver contribution shares or effect sizes, source/window reconciliation, exact executed SQL or query references when queries were used, and caveats that would change interpretation.\n\nPass the diagnostic substance and supporting evidence to $build-report unless the user explicitly requests an inline, chat-only, brief/no-artifact answer, asks not to create a report/file/artifact, or selects another primary artifact. This handoff is mandatory when no explicit human waiver was given; do not infer a waiver because the user asked a direct diagnostic question or did not use the word \"report\". Let $build-report own the report surface, presentation polish, reproducibility treatment, and sharing handoff.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/product-business-analysis/SKILL.md":"---\nname: product-business-analysis\ndescription: \"Analyze product or business data to support a decision or recommendation. Use when a decision depends on metric-backed evidence, such as choosing a direction, prioritizing an opportunity, evaluating a change, segmenting users, sizing tradeoffs, or deciding what to do next.\"\n---\n\n## Related Skills\n\nUse $metric-diagnostics when the recommendation depends on explaining a metric movement, anomaly, gap, or discrepancy.\n\n# Product And Business Analysis\n\nUse this skill to answer product or business questions with data-backed evidence, context, and a recommendation. Give the audience enough trustworthy evidence, interpretation, and uncertainty framing to choose a practical next action.\n\n## Skill Configuration\n\n### Source Discovery And Verification\n\nUse the relevant semantic layer as a starting map, not a boundary.\n\n1. **Explore all possible sources.** Search every connected or provided source that could contain task-relevant data or change the interpretation. Within each structured-data source, run fresh catalog or metadata discovery for relevant schemas, datasets, tables, views, models, and metrics. Known sources, tables, dashboards, and semantic mappings are starting points, not stopping points.\n2. **Compare duplicates and conflicts.** When sources overlap or disagree, compare ownership, freshness, definition, grain, coverage, and directness. Use the best authoritative source, or combine complementary sources when needed. Note material conflicts, explain why the selected source or sources control the answer, and verify selected data through live reads before concluding.\n\n### Source Access Guardrail\n\nBefore querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.\n\nIf a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.\n\nIf the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.\n\nClarify with the user when a missing input would materially change the analytical frame or recommendation. Otherwise make a reasonable assumption, state it, and proceed.\n\n## Workflow\n\n### 1. Start From The Decision\n\nIdentify the decision, audience, and action the analysis should inform before choosing data sources or metrics.\n\nState plainly:\n\n- the question and decision the analysis should inform\n- who will use the answer and what they can act on\n- the scope and comparison that define a useful answer\n- the outcome or behavior that matters for the decision\n- any assumptions needed to proceed\n\nDo not let unclear scope turn into broad exploratory work by default.\n\n### 2. Gather Decision-Relevant Context\n\nRun $gather-business-context before deeper analysis. That skill owns source selection, retrieval, source authority, conflict handling, and compact context notes. Use this workflow to decide how the gathered context changes the analysis and recommendation.\n\nKeep the context pass proportional to the task. For self-contained prompts or cases where the user already provided enough context, the pass can be brief: confirm the decision frame, definitions, source assumptions, and any obvious gaps before moving on. Do not turn mandatory context gathering into a broad background scan.\n\nRelevant context should clarify:\n\n- intent: what the work was meant to accomplish and why\n- definitions: how the work, metric, or source is defined and measured\n- timing: what changed around the analysis period that could affect interpretation\n- constraints: decisions, caveats, or limitations that affect what action is realistic\n\n### 3. Frame The Analysis\n\nTurn the question into a focused analytical framework.\n\nDefine a framework for answering the question with data:\n\n- the specific data questions that would support or change the recommendation\n- the comparisons and dimensions to inspect\n- the unit of analysis that matches the decision\n- the metric definitions and caveats needed to interpret the result\n\nUse the framework to surface plausible hypotheses or interpretations, then turn them into focused data questions. Keep the framework specific enough to avoid broad exploration and support a recommendation.\n\nUse $design-kpis when the success metric, driver metrics, guardrails, or measurement plan need to be defined before the analysis can proceed.\n\nStart by defining what the answer needs to show in plain language. Then choose the data that matches that meaning as closely as possible, including who is counted and what comparison makes the number meaningful. If a field or event captures only part of what the decision cares about, say what it captures and what it leaves out.\n\n### 4. Run Focused Quantitative Analysis\n\nRun enough quantitative analysis to support or reject the framed hypotheses and inform the decision:\n\n- **Follow the framework.** Run the analyses that could change the recommendation first. Track additional data questions that emerge, answer the ones that matter for the decision, and leave lower-impact cuts as follow-up instead of expanding into broad exploration.\n\n- **Use the right comparison.** Interpret results against the relevant baseline, denominator, or comparison point before turning them into a recommendation. For example, do not conclude that one group is the best opportunity just because it has the most total usage. Check whether usage is high because the group is larger, whether the pattern still holds after normalizing by the active base, whether the group is growing or declining, whether the usage reflects the behavior or outcome that matters, and whether business context changes the interpretation.\n\n- **Size the opportunities.** Estimate the magnitude of impact each important opportunity could have. State what is being compared, which metric represents impact, what denominator or population it uses, and whether the data is complete enough to trust. Keep material unknown or unclassified groups visible when they could change the interpretation.\n\n- **Keep quantitative work inspectable.** Use $jupyter-notebooks to record queries and analysis. Use $analyze-data-quality when source freshness, grain, joins, missingness, schema drift, or unexpected distributions could affect trust.\n\n- **Validate before concluding.** Use $validate-data before sharing stakeholder-facing recommendations, high-impact claims, or surprising results. When dashboards and direct queries both exist, reconcile them or explain why they differ.\n\n### 5. Translate Evidence Into Decision Implications\n\nFrame the findings within the broader business context. Do not present quantitative evidence and business context as two unrelated streams.\n\nInterpret the evidence through the decision lenses that best fit the question. Choose lenses that would actually change the recommendation, and skip ones that would add noise or false precision. Common lenses include:\n\n- **Current scale:** Is the opportunity or problem large enough today to matter for the decision?\n- **Momentum:** Is the signal growing, shrinking, accelerating, or newly emerging?\n- **Breadth:** Is the pattern broad-based, or does it only appear in a narrow corner of the business?\n- **Concentration:** Does the conclusion depend on a few large entities, events, or outliers?\n- **Intensity:** Is the behavior deep enough per unit to suggest real need, value, or risk?\n- **Efficiency:** Does the option create better output, margin, conversion, productivity, or quality for the input required?\n- **Addressability:** Can the team realistically act on this option with available product, GTM, operational, policy, or technical levers?\n- **Differentiation:** Does this group or use case require a distinct motion, product experience, support model, or message?\n- **Substitution:** Is there evidence that behavior, spend, time, or workload could shift from another path?\n- **Risk or dependency:** Are there quality, trust, compliance, technical, operational, or data constraints that change the recommendation?\n- **Coverage:** Are unknown, missing, or sparsely tagged records large enough to change the answer?\n\nUse these as thinking tools, not a checklist. Explain why the chosen lenses matter for this decision, and mention omitted cuts only when they would plausibly change the interpretation or help explain the result.\n\nUse the measured opportunities to explain which differences matter for the decision and which ones call for different actions. If the business context shows that the initial sizing misses the actionable part of the opportunity, add the focused sizing cut needed to make the recommendation useful.\n\nIf evidence conflicts, say so directly and explain which interpretation is better supported. Do not smooth over disagreement between sources.\n\n### 6. Hand Off The Recommendation\n\nEnd by handing the decision-ready recommendation to $build-report unless the user explicitly requests an inline, chat-only, brief/no-artifact answer, asks not to create a report/file/artifact, or selects another primary artifact. This handoff is mandatory when no explicit human waiver was given; do not infer a waiver because the user asked a direct question or did not use the word \"report\". This workflow owns the analytical conclusion; $build-report owns the reader-facing structure, visuals, evidence placement, and delivery surface.\n\nBefore handoff, make the recommendation explicit:\n\n- what they should believe or do next\n- why the evidence supports that recommendation\n- which caveats or dependencies matter\n- what follow-up analysis would most improve confidence\n\nIf evidence is incomplete, label the recommendation as provisional and state what would change confidence. Do not overstate the conclusion just to make the answer feel decisive.\n\nUse $validate-data when methodology, calculations, caveats, or the evidentiary support for the conclusion need review before sharing.\n\nPass narrative ingredients to the report surface, not only result tables:\n\n- direct answer and recommendation\n- key evidence and how to interpret it\n- implication for the decision\n- unresolved uncertainty and caveats\n- recommended follow-up\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/validate-data/SKILL.md":"---\nname: validate-data\ndescription: \"Validate whether an analysis is accurate, well-supported, and ready to share or use for a decision. Use when reviewing methodology, calculations, comparisons, visuals, caveats, or conclusions.\"\n---\n## Related Skills\n\nUse $analyze-data-quality when validation depends on whether the underlying data is trustworthy, comparable, fresh, or at the right grain.\n\nUse $product-business-analysis when the task asks for a recommendation or decision after the validation pass.\n\n# Validate Data Analysis\n\nValidate an analysis before it is shared with stakeholders. Focus on whether the question, data, methodology, calculations, visuals, claims, caveats, and recommendations are trustworthy enough for the stated audience and decision.\nThis skill is for analysis QA, not raw dataset profiling alone. When validation depends on dataset reliability checks such as freshness, grain, missingness,\nduplicates, join coverage, or source mismatches, use $analyze-data-quality as a companion.\n\n## Workflow\n\n1. Inventory the artifact and claims.\n\n Identify the report, notebook, spreadsheet, SQL, dashboard, chart, pasted analysis, or recommendation being validated. Inspect source artifacts when a path, link, query, notebook, spreadsheet, or dashboard is referenced. Extract the main question, audience, decision, key claims, headline numbers, data sources, time windows, populations, filters, comparison baselines, and stated caveats. Verify that every metric or KPI requested by the user appears in the analysis or is explicitly marked unavailable, not applicable, or out of scope.\n\n2. Validate the question, methodology, and assumptions.\n\n Confirm that the analysis answers the stated business or product question,\n not a nearby easier question. Check whether the population, eligibility rules, exclusions, sampling, metric definitions, formulas, units,\n denominators, timezones, cohorts, comparison periods, and baselines match the stakeholder decision. Flag hidden exclusions, inconsistent definitions,\n partial-period comparisons, and causal wording that lacks experimental or otherwise credible causal evidence.\n\n3. Validate data selection and quality risks.\n\n Confirm that the chosen tables, files, dashboards, or extracts are appropriate and current enough for the decision. Check freshness or \"as of\"\n date, expected partitions, segment coverage, row/category completeness, null handling, deduplication, filter logic, join coverage, and source mismatches when those risks could change the conclusion. Use `~~structured_data` for source metadata, schema checks, sample rows, query history, or SQL spot checks through the relevant source connector when available. Use `~~operations_logs` for table freshness, lineage, or pipeline context.\n\n4. Verify calculations and aggregations.\n\n Recompute the highest-impact numbers independently when possible. Check grain, subtotals, denominators, non-zero denominators, rate bases,\n period-over-period bases, weighted averages, units, currency, timezone handling, and whether mutually exclusive categories add to totals. For SQL,\n inspect join types, group-by grain, filters, distinct counts, and row counts before and after joins. Use $jupyter-notebooks or `~~spreadsheet_workspace`\n when the artifact itself is a notebook or spreadsheet, or when reproducible spot checks need code or formulas.\n\n5. Test reasonableness and common analytical traps.\n\n Compare magnitudes against known dashboards, historical reports, prior analyses, finance sources, or expected product scale when possible. Investigate trend jumps, drops, flatlines, exact round numbers, 0% or 100% rates, segment shares that should sum to about 100%, and results that perfectly confirm the hypothesis without friction. Check edge cases such as empty segments, new entities, and boundary dates.\n\n6. Review visuals and presentation integrity.\n\n Confirm that charts use appropriate chart types, scales, axes, intervals,\n titles, labels, units, ordering, annotations, color, and precision. Use\n $visualize-data for non-trivial chart review. For rendered reports,\n dashboards, slides, docs, PDFs, HTML, or other final artifacts, inspect the rendered output for broken charts, missing tables, clipped text, bad formatting, stale placeholders, and obvious layout issues. Check whether a quick reader could walk away with a misleading interpretation, especially from truncated axes, dual axes, 3D effects, inconsistent intervals, missing date ranges, or chart titles that overstate the data.\n\n7. Evaluate narrative, conclusions, and recommendations.\n\n Confirm each conclusion is supported by visible evidence or saved artifacts.\n Separate verified findings from interpretation, caveats, and open questions.\n Identify alternative explanations, uncertainty, missing context,\n recommendations that go beyond the evidence, and any causal language that is not supported by the design.\n\n8. Produce a confidence assessment and required fixes.\n\n Prioritize issues that materially affect the stakeholder decision. Separate blockers from caveats: do not block sharing for minor polish issues, but do block when a number, denominator, join, time window, population, comparison,\n or conclusion is materially unreliable. Record incomplete handoff blockers separately from caveats, including missing access, unavailable source artifacts, unrun checks, broken render steps, unresolved data-quality risks,\n or absent owner confirmation. If SQL, Python, a notebook, or a spreadsheet was used for validation, include the artifact path, query permalink, notebook path, spreadsheet tab, or dashboard link so the check is reproducible.\n\n## Standards\n\n### Validation Stance\n\n- Validate the claims the analysis actually makes, not just whether the artifact looks polished.\n- Prefer concrete evidence: recompute important numbers, inspect source data,\n check code paths, trace records, or reconcile against trusted sources when tools and access allow it.\n- Label anything that cannot be verified, and state what would be needed to verify it.\n- Treat surprising results, stakeholder-facing recommendations, causal claims,\n high-impact decisions, and externally shared analyses as higher-risk validation targets.\n- Select checks that match the artifact and decision. Do not run every possible check mechanically.\n\n### Methodology Checks\n\n- Question framing: the analysis answers the stated business or product question.\n- Data selection: sources are appropriate and current enough for the decision.\n- Population: inclusions, exclusions, eligibility rules, and sampling are explicit.\n- Metric definitions: formulas, units, denominators, and timezones are clear and aligned with stakeholder definitions.\n- Baselines: comparison periods, cohorts, and contexts are comparable.\n- Causality: causal wording is backed by experimental or otherwise credible causal evidence.\n\n### Data Quality Checks\n\n- Freshness: the analysis states or can recover the data \"as of\" date.\n- Completeness: no unexpected missing partitions, segments, rows, or categories.\n- Null handling: key columns have expected null rates or explicit treatment.\n- Deduplication: primary entities are not double counted.\n- Filter verification: filters and WHERE clauses do not silently exclude the population of interest.\n- Join coverage: dimensions, experiments, and reference tables do not drop or multiply important rows.\n\n### Calculation Checks\n\n- Grain: the aggregation level matches the intended analysis grain.\n- Denominators: rates and percentages use the correct population and non-zero denominators.\n- Period alignment: comparisons use equal or explicitly caveated windows.\n- Weighted metrics: averages are weighted correctly when group sizes differ.\n- Subtotals: parts add to totals where categories are mutually exclusive.\n- Units: currency, token, user, request, account, day/week/month, and timezone units are consistent.\n\n### Reasonableness Checks\n\n- Magnitudes are plausible relative to known dashboards, historical reports, or expected product scale.\n- Percentages fall in expected ranges and segment shares sum to about 100% where expected.\n- Trend jumps, drops, flatlines, exact round numbers, and 0% or 100% rates have an explanation.\n- Results do not perfectly confirm the hypothesis without friction or exceptions.\n- Edge cases such as empty segments, new entities, and boundary dates behave sensibly.\n\n### Common Pitfalls\n\n- Join explosion: many-to-many joins silently multiply rows and inflate counts or sums. Compare row counts and distinct primary entities before and after the join, and check whether the right-hand table has multiple rows per join key.\n Aggregate the right-hand table to the intended grain before joining when needed, use `COUNT(DISTINCT primary_id)` when counting entities through joins,\n and comment intentional one-to-many joins.\n- Survivorship bias: the analysis only includes entities that exist today and misses deleted, churned, failed, or otherwise absent entities. Ask who is not in the dataset and whether the missing population changes the conclusion.\n- Incomplete period comparison: a partial period is compared with a complete period. Use complete periods, compare the same number of elapsed days, or label the partial-period caveat prominently.\n- Denominator shifting: the eligible population changes between periods or segments. Validate that conversion, churn, activation, attach, and retention rates use stable definitions across compared groups.\n- Average of averages: pre-computed averages are averaged without weighting for group size. Aggregate from raw numerators and denominators or use a weighted average.\n- Timezone mismatch: sources use different timestamp conventions or daily cutoffs. Confirm the analysis standardizes timestamps or explicitly states the timezone and cutoff.\n- Selection bias in segmentation: segments are defined by the outcome being measured. Define comparison groups by pre-treatment characteristics when making lift, causality, or behavior-difference claims.\n- Other statistical traps: Simpson's paradox where aggregate and segment-level trends conflict, correlation presented as causation, small samples,\n outlier-dominated averages that need medians or distribution views, multiple testing, cherry-picked time ranges, and look-ahead bias.\n\n### Spot-Check Recipes\n\n- Recompute a key metric from raw numerators and denominators.\n- Trace a few individual records through joins, filters, and final output.\n- Reconcile a key total against a trusted dashboard, prior report, or finance source.\n- Reverse engineer a headline number from component metrics, such as users times per-user revenue.\n- Run a one-day, one-segment, or one-entity boundary check to make sure filters and joins behave sensibly.\n- Compare the same metric through an alternate query path when a claim is surprising or high stakes.\n\n### Visualization Checks\n\n- Bar charts should generally start at zero; waterfall, bridge, variance, and other delta-focused charts may use a non-zero or narrowed value axis when zero would materially compress the intended movement, provided exact values, units, and the focused scale are clear.\n- Comparison charts should use consistent scales unless the scale difference is explicit and justified.\n- Axes, units, legends, and date ranges should be labeled.\n- Category ordering should match the comparison the reader should make.\n- Truncated axes, dual axes, 3D effects, and inconsistent intervals require explicit justification or redesign.\n- Chart titles and annotations should match exactly what the data supports.\n- Titles should state the finding and include date range or scope when needed.\n- Caveats should be visible near the claims they qualify.\n- Number formatting should use appropriate precision and units.\n- Rendered artifacts should be checked in their final form when available, not only in source form.\n\n### Confidence Ratings\n\n- `Ready to share`: The analysis is methodologically sound, key calculations are verified or low risk, caveats are clear, and any remaining issues are minor.\n- `Share with caveats`: The analysis is directionally usable, but specific assumptions, limitations, or unverified checks must be communicated to stakeholders.\n- `Needs revision`: There are material errors, unsupported claims, missing checks, or methodological issues that should be fixed before sharing.\n\n### Output Standards\n\nUse this structure unless the user asks for a lighter review:\n\n```markdown\n## Validation Report\n\n### Overall Assessment: [Ready to share | Share with caveats | Needs revision]\n\n### Methodology Review\n[Findings about question framing, data selection, population, definitions, comparisons, and assumptions.]\n\n### Issues Found\n1. [Severity: High/Medium/Low] [Issue description, evidence, and impact]\n2. ...\n\n### Calculation Spot-Checks\n- [Metric or claim]: [Verified / Discrepancy found / Not verified] - [brief evidence]\n\n### Visualization Review\n[Chart or presentation issues, if applicable.]\n\n### Suggested Improvements\n1. [Improvement and why it matters]\n\n### Required Caveats for Stakeholders\n- [Caveat that must be communicated]\n```\n\n- Include the question being answered, data sources and \"as of\" date, metric and segment definitions, time period and timezone, methodology steps, assumptions and limitations, SQL queries, notebook paths, spreadsheet tabs, dashboard links, or caveats required before acting when those details are relevant.\n- Preserve source references from the original artifact, including links, query IDs, notebook paths, spreadsheet tabs, dashboard URLs, cited documents, and other evidence needed to trace the analysis.\n- Verify that every section requested by the user or implied by the deliverable format is present; explain omitted sections.\n- Keep issues prioritized by decision impact, not by artifact section order.\n- Make unverified claims and remaining caveats explicit.\n- List incomplete handoff blockers separately from caveats and suggested improvements.\n","packages/cli/src/skill/builtin/.bundle/data-analytics/workflows/visualize-data/SKILL.md":"---\nname: visualize-data\ndescription: \"Design, create, revise, or QA quantitative charts and figures for reports, dashboards, notebooks, slides, files, or inline analytical answers.\"\n---\n\n# Visualize Data\n\nCreate quantitative visuals that are analytically sound, immediately readable, and appropriate for their destination. Treat a chart as evidence for a takeaway, not decoration.\n\n## Workflow\n\n1. State the analytical question and intended takeaway.\n2. Verify the data grain, measures, dimensions, units, missing values, filters, time window, sample size, and source.\n3. Choose the chart family from the analytical relationship:\n - Change over ordered time: line or area chart.\n - Category comparison: bar chart.\n - Distribution: histogram, box plot, or density plot.\n - Relationship between numeric measures: scatter plot.\n - Composition: stacked bar/area; use pie only for a small set of meaningful parts.\n - Funnel progression: funnel or ordered bars with stage conversion.\n - Contribution to change: waterfall.\n - Exact lookup values: table, optionally with small bars or sparklines.\n4. Define explicit encodings, sorting, aggregation, grouping, scales, labels, units, colors, annotations, and uncertainty treatment.\n5. Render with the destination's native system when one is selected. Otherwise prefer reproducible Python/Matplotlib or SVG for files and inline artifacts. Notebook-native plotting is appropriate for notebooks.\n6. Inspect the final output in context when the host provides image, browser, document, or notebook inspection.\n\nDo not install or require React, Recharts, Vite, MCP widgets, or proprietary UI renderers. For self-contained HTML, use inline SVG/canvas or a static image plus semantic fallback data. Avoid remote scripts unless the user explicitly accepts the dependency.\n\n## Visual quality\n\n- Use an answer-oriented title and a subtitle only when it adds a distinct takeaway.\n- Label axes and units; show legends or direct labels for every visible group.\n- Use consistent scales for comparisons and avoid misleading truncated axes unless clearly justified.\n- Prefer direct labeling and restrained color. Reserve semantic colors for meaning such as positive, warning, or negative states.\n- Keep annotations selective and evidence-backed.\n- Make dense charts readable through aggregation, faceting, filtering, or a table rather than shrinking text.\n- Provide accessible contrast, text alternatives, and a data table when the destination supports them.\n- Put provenance in a source note rather than cluttering the title.\n\n## QA\n\n- Recompute plotted values from the reviewed rows.\n- Confirm the visual answers the stated question and does not imply unsupported causality.\n- Check ordering, scales, labels, clipping, overlap, empty states, and small-screen behavior where relevant.\n- Confirm the exported file opens and contains the expected marks and text.\n- Preserve the code or notebook needed to reproduce the chart when the user needs an auditable artifact.\n\n","packages/cli/src/skill/builtin/.bundle/deep-research/SKILL.md":"---\nname: deep-research\ndescription: Deep research on any topic using parallel sub-agents and built-in tools only (WebSearch/WebFetch + free APIs, no keys). Use when the user asks for a thorough multi-source investigation with a cited report — \"深度调研X\"、\"deep research\"、\"帮我全面研究一下\"、\"多方求证\"、\"写一份调研报告\". NOT for simple lookups (single WebSearch suffices) and NOT for academic literature surveys (use auto-research skill instead).\n---\n\n# Deep Research\n\nOrchestrate parallel research sub-agents, then write one coherent cited report. Research is parallel; writing is single-point — never let multiple agents write report sections.\n\n## Step 0 — Always first\n\n1. Run `date +%Y-%m-%d` via Bash. Never assume the current year from training data.\n2. Triage:\n - Answerable with 1-2 searches? → STOP, just use WebSearch directly. Do not use this skill.\n - Enumeration task (N items × M fields, e.g. \"compare 20 frameworks\")? → still this skill, but use table-oriented decomposition (one sub-agent per item batch).\n - Open-ended investigation? → continue below.\n3. Pick depth (default **standard**; user can override with words like \"quick\"/\"exhaustive\"):\n\n| Mode | Sub-agents (round 1) | Max follow-up rounds | Sources target |\n|---|---|---|---|\n| quick | 2-3 | 0 | 8+ |\n| standard | 3-5 | 1 | 15+ |\n| deep | 5-8 | 2 | 25+ |\n\nThese are hard budgets. Reflection (Phase 4) can spend them but never exceed them.\n\n## Workspace\n\nAll state lives on disk at `./research//` — never only in context (survives compaction):\n\n```\nresearch//\n├── brief.md # research brief — the single contract for all phases\n├── findings/ # F1.md, F2.md ... one per sub-agent, structured evidence\n└── REPORT.md # final deliverable\n```\n\nOn resume: re-read `brief.md` + list `findings/`, skip completed angles, continue.\n\n## Phase 1 — Scope\n\nAsk at most one round of clarifying questions (AskUserQuestion), only if genuinely ambiguous: audience, time frame, region, decision at stake. If the user said \"just run it\" or intent is clear, skip asking and write assumptions into the brief instead.\n\nThen write `brief.md`: refined question, scope boundaries (in/out), assumptions, depth mode, today's date. This brief — not the raw conversation — is what every later phase measures against.\n\n## Phase 2 — Plan\n\nDecompose the brief into 3-8 **independent** research angles. Pull from these lenses as applicable: core facts/definitions · recent developments (last 12 months) · quantitative data/benchmarks · counter-arguments & failure cases · practitioner experience (forums, issues) · academic work · key players/alternatives.\n\nList angles in `brief.md` under `## Angles`. For deep mode or contested topics, show the angle list to the user for a quick confirm before spending budget.\n\n## Phase 3 — Parallel research\n\nSpawn one sub-agent per angle **in a single message** (parallel). Build each prompt from the locked template in [reference/subagent-prompt.md](reference/subagent-prompt.md) — reproduce it verbatim, replacing only the `{variables}`. Each sub-agent:\n\n- researches ONE angle only, using WebSearch/WebFetch and the free endpoints in [reference/sources.md](reference/sources.md)\n- writes structured findings to `findings/F.md` (claim / quote / URL / date / confidence per item)\n- returns only a 3-5 line summary to you — raw page content must never enter your context\n\nIf a sub-agent fails or returns thin results, note it and move on; do not block other angles.\n\n## Phase 4 — Reflect (gap check)\n\nRead all `findings/*.md`. Against `brief.md`, ask: which parts of the brief have no evidence? Which major claims rest on a single source? Where do sources conflict?\n\n- Gaps found AND follow-up budget remains → spawn targeted sub-agents with delta-queries (same template, narrower angle). Repeat once per remaining round.\n- No budget left or coverage sufficient → proceed. Record unresolved gaps; they go in the report's \"Open questions\".\n\n## Phase 5 — Write (single-point)\n\nYou alone write `REPORT.md` in one pass, following [reference/report.md](reference/report.md). Core rules:\n\n- Every non-obvious claim carries an inline citation `[n]` mapping to a Sources section; citation URLs come only from findings files — never from memory.\n- Where sources conflict, present both sides with dates; prefer newer + primary sources.\n- Mark single-source claims with `[single source]`, speculation with `[speculative]`.\n- End with: Open questions · Sources (numbered, with access date).\n\nFor deep mode, before finalizing do one critique pass: reread the report as a skeptical reviewer (unsupported claims? stale data? missing counter-view?) and fix in place.\n\nFinally, give the user a 5-10 line summary of key conclusions and the report path.\n","packages/cli/src/skill/builtin/.bundle/docx-official/README.md":"","packages/cli/src/skill/builtin/.bundle/docx-official/SKILL.md":"---\nname: docx-official\ndescription: \"Use this skill whenever a Microsoft Word (.docx) file is being produced, opened, transformed, or read. That includes: drafting reports, letters, contracts, RFPs, technical documents, or any long-form written deliverable; extracting text or structure from an existing Word file; filling a Word template with values; converting Word to PDF or plain text; splitting or merging documents; inspecting styles, headings, sections, tables, images, comments, or tracked changes. Trigger on mentions of 'Word doc', 'DOCX', 'Office document', a filename ending in .docx, or requests like 'turn this into a Word report'.\"\nlicense: Apache-2.0 — see LICENSE for terms and third-party attributions\n---\n\n# DOCX Skill\n\nAn Apache-2.0 toolkit for producing, editing, and reading Microsoft Word (`.docx`) files. Written from scratch against the public [ECMA-376 / ISO/IEC 29500](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/) specification and built on permissively-licensed tooling (`python-docx` MIT, `lxml` BSD-3-Clause, optional external binaries `pandoc` and `soffice`) so it can be reused in commercial projects without restriction.\n\n## Decision matrix\n\n| Situation | Path | Read first |\n|-----------|------|------------|\n| No source file — build a document from a prompt / data | Author from scratch with `python-docx` | [`create.md`](create.md) |\n| You have a `.docx` template to fill in or lightly modify | Placeholder replacement via `python-docx`, keeps styles | [`edit.md`](edit.md) → *Workflow A — `python-docx` in-place edit* |\n| Deep structural edits, new sections, custom XML, unusual layouts | Explode → edit XML → assemble | [`edit.md`](edit.md) → *Workflow B — Explode → edit XML → assemble* |\n| You only need the text / structure / metadata out of a `.docx` | Extraction pipeline | [`read.md`](read.md) |\n| Need a PDF preview for QA | `scripts/render_pdf.py` via LibreOffice | see *QA* below |\n\nIf the task mixes several of these, do them in this order: **read → plan → edit/create → validate**.\n\n## One-time environment setup\n\n> **Bundled runtime:** when the `MIMO_PYTHON` environment variable is set, skip `uv`/`python3` and pip installs entirely — run every command below with `uv run` replaced by `\"$MIMO_PYTHON\"` (e.g. `\"$MIMO_PYTHON\" scripts/extract_text.py input.docx`). This skill's Python dependencies are preinstalled in that interpreter; pip console scripts are unavailable, so always go through `\"$MIMO_PYTHON\" -m `. A bundled LibreOffice is exposed as `MIMO_SOFFICE` and picked up automatically by the scripts here.\n\nAll scripts include [PEP 723](https://peps.python.org/pep-0723/) inline metadata, so `uv run` resolves dependencies automatically — no manual install step needed. Just run:\n\n```bash\nuv run scripts/extract_text.py input.docx\n```\n\nIf you don't use `uv`, install dependencies once:\n\n```bash\npython3 -m pip install --upgrade python-docx lxml\n# Optional but recommended:\n# LibreOffice (for docx → pdf preview): brew install --cask libreoffice (macOS)\n# apt-get install -y libreoffice (Debian/Ubuntu)\n# Poppler (for pdf → image, QA loop): brew install poppler\n```\n\nAlternatively, if this skill lives in a persistent workspace you can `uv init` a project, `uv add python-docx lxml`, and run scripts with `uv run scripts/...` from the project root — this gives you a lockfile and reproducible environment.\n\nAll scripts here use the standard library plus `python-docx`. No proprietary dependencies.\n\n## Common commands\n\n```bash\n# 1. Extract plain text (best for \"what does this file say?\" questions)\nuv run scripts/extract_text.py input.docx > input.txt\n\n# 2. Explode a .docx into readable XML for structural surgery\nuv run scripts/explode.py input.docx exploded/\n\n# 3. Assemble an exploded directory into a fresh .docx\nuv run scripts/assemble.py exploded/ output.docx\n\n# 4. Render a .docx as PDF (used for visual QA)\nuv run scripts/render_pdf.py output.docx # writes output.pdf next to it\n\n# 5. Well-formedness check (ZIP integrity + parseable XML + python-docx open)\nuv run scripts/audit.py output.docx\n\n# 6. Accept every tracked change without needing Word/LibreOffice\nuv run scripts/resolve_revisions.py reviewed.docx clean.docx\n\n# 7. Add a comment to an exploded directory\nuv run scripts/annotate.py exploded/ \"Please check\" --author \"Reviewer\" --anchor \"text\"\n```\n\nEvery script is a small, self-contained Python file. Read the top of the file for full CLI options.\n\n## Authoring principles\n\nWord is a **flowing** document format, not a slide surface. Users expect it to look like something a human wrote in Word — not a design tool trying to reinvent typography. Keep that in mind:\n\n1. **Rely on named styles.** Use `Heading 1`, `Heading 2`, `Normal`, `Title`, `Quote`, `List Bullet`, `List Number`, `Caption`. They are what makes Word's ToC, navigation pane, and cross-references work.\n2. **One idea per paragraph.** Long paragraphs are fine; run-on paragraphs are not. Break at logical boundaries.\n3. **Structure first, prose second.** Draft the heading tree, then write inside it. Reviewers scan headings before words.\n4. **Tables for tabular data only.** Do not use tables to fake multi-column layouts — export to PDF and users see the borders through the layout.\n5. **Line length is set by page margins, not by hard breaks.** Never insert manual line breaks to control wrapping.\n6. **Use fields, not literal text, for things that change** — page numbers, dates, ToC, cross-references. `python-docx` supports field codes via low-level XML (see `edit.md`).\n7. **Every image needs alt text** — accessibility, and Word screams at you in review mode when it's missing.\n\n## Typography defaults (safe starting point)\n\n| Element | Font | Size | Weight | Notes |\n|----------------|---------------|------|--------|-------|\n| Title | Calibri Light | 28pt | Bold | Centered or left, one line |\n| Heading 1 | Calibri Light | 18pt | Bold | Space before 12pt |\n| Heading 2 | Calibri Light | 14pt | Bold | Space before 10pt |\n| Heading 3 | Calibri | 12pt | Bold | Space before 6pt |\n| Body | Calibri | 11pt | Regular| Line spacing 1.15, space after 6pt |\n| Caption | Calibri | 9pt | Italic | Muted gray `#595959` |\n| Code / mono | Consolas | 10pt | Regular| Left-aligned, no first-line indent |\n\nChange the palette for the topic — muted navy `#1F3A5F` for legal/finance, warm charcoal `#2E2A26` for editorial. Avoid pure `#000000` for body text; `#1F1F1F` reads softer on print.\n\n## Page setup (A4 vs Letter)\n\nAsk the user which one to use. If you cannot ask, default to the region implied by the language (Chinese/European → A4, US English → Letter). Margins:\n\n| Size | Width × Height | Standard margins (T/B/L/R) |\n|--------|-------------------|-----------------------------|\n| A4 | 21.0 × 29.7 cm | 2.54 / 2.54 / 3.18 / 3.18 cm |\n| Letter | 8.5 × 11.0 in | 1.00 / 1.00 / 1.25 / 1.25 in |\n\n## QA checklist — always run before declaring done\n\n**Assume something is wrong.** Word files fail silently: a broken relationship, an unclosed ``, a missing style — Word will still open the file but strip content or throw a \"content had problems\" warning. Verify explicitly.\n\n1. **Open cleanly** — no repair prompt.\n ```bash\n uv run python -c \"import docx; docx.Document('output.docx')\" # loads without exceptions\n ```\n2. **Text integrity** — no placeholder residue.\n ```bash\n uv run scripts/extract_text.py output.docx | grep -Ei \"TODO|TBD|\\{\\{|lorem|xxxx\"\n ```\n Grep must return nothing.\n3. **Visual sanity** — render a PDF, open the first and last pages, scan for:\n - Widowed headings alone at the bottom of a page.\n - Tables split awkwardly across pages.\n - Images pushed to their own page because they exceeded content width.\n - Missing page numbers, wrong header/footer content.\n ```bash\n uv run scripts/render_pdf.py output.docx\n ```\n4. **Style hygiene** — every heading uses a real style, not just bold+large text:\n ```bash\n uv run python -c \"\n import docx; d = docx.Document('output.docx')\n for p in d.paragraphs:\n if p.text and p.style.name == 'Normal' and p.runs and p.runs[0].bold:\n print('possible fake heading:', p.text[:80])\"\n ```\n\nIf any of these fail, fix and re-run — don't paper over.\n\n## What is out of scope\n\n- **`.doc` (legacy Word 97-2003)** — this skill only targets `.docx` (Office Open XML). Convert `.doc` to `.docx` with LibreOffice first: `soffice --headless --convert-to docx old.doc`.\n- **Live collaborative editing** — the Word online API is a separate concern; here we produce and modify files.\n- **Macros / VBA** — do not generate `.docm` files. If the user asks for automation, offer a Python script that regenerates the doc instead.\n\n## Where each detail lives\n\n- **Creating from scratch**: [`create.md`](create.md) — headings, paragraphs, styles, tables, images, page setup, headers/footers, tables of contents.\n- **Editing / templating**: [`edit.md`](edit.md) — placeholder replacement, section swap, raw XML surgery, tracked changes, comments.\n- **Reading / extracting**: [`read.md`](read.md) — plain-text export, structural walk, metadata, table extraction.\n- **Scripts**: [`scripts/`](scripts/) — self-contained CLI utilities used by all of the above.\n","packages/cli/src/skill/builtin/.bundle/grok-build/SKILL.md":"---\nname: grok-build\ndescription: Reference and workflow guidance for the Grok Build CLI (`grok`), including interactive and headless runs, authentication, sessions, worktrees, permissions, sandboxing, MCP servers, plugins, inspection, updates, and automation output. Invoke only when the user explicitly requests the `grok-build` skill, explicitly asks to use Grok Build CLI, or an already-selected workflow requires Grok Build; do not invoke for general coding, generic shell tasks, or other agent CLIs.\n---\n\n# Grok Build CLI\n\nOperate Grok Build from a terminal while keeping execution mode, permissions, sandboxing, session state, and output handling explicit.\n\n## Start with Local Evidence\n\n1. Confirm that the CLI is available:\n\n ```bash\n command -v grok\n grok version\n ```\n\n2. Inspect the installed command before giving version-sensitive advice:\n\n ```bash\n grok --help\n grok --help\n ```\n\n3. Inspect the configuration discovered for the target workspace when behavior depends on rules, skills, plugins, hooks, or MCP servers:\n\n ```bash\n grok --cwd /path/to/repo inspect\n grok --cwd /path/to/repo inspect --json\n ```\n\n4. Treat current official documentation and installed help as authoritative when they differ from this bundled reference.\n\n## Choose an Execution Mode\n\n- Run `grok` with no arguments for the interactive TUI.\n- Run `grok \"\"` to open the TUI with an initial task.\n- Run `grok -p \"\"` for one non-interactive turn that prints a result and exits.\n- Run `grok agent stdio` for an ACP client that communicates over stdin/stdout.\n- Run `grok dashboard` to open the Agent Dashboard.\n\nPrefer headless mode for scripts, CI, bots, and agent orchestration. Prefer ACP only when the caller implements the ACP JSON-RPC lifecycle and consumes `session/update` chunks.\n\n## Authenticate\n\nUse an interactive login on a developer machine:\n\n```bash\ngrok login\n```\n\nUse device-code authentication in headless or remote environments:\n\n```bash\ngrok login --device-auth\n```\n\nUse a locally cached login or provide `XAI_API_KEY` only to the process that needs it. Never print, persist, or commit credentials. Use `grok logout` to clear cached credentials.\n\n## Run Headlessly\n\nUse an explicit working directory and output format:\n\n```bash\ngrok --no-auto-update \\\n --cwd /path/to/repo \\\n --sandbox workspace \\\n -p \"Inspect the repository and explain the failing test.\" \\\n --output-format json\n```\n\nChoose output according to the consumer:\n\n- Use `plain` for humans.\n- Use `json` for one final machine-readable object.\n- Use `streaming-json` for newline-delimited incremental events.\n- Add `--json-schema ''` when the installed CLI supports constrained structured output.\n\nPass `--no-auto-update` in scripts and CI to suppress background update checks. Do not parse interactive TUI rendering in automation.\n\n## Control Permissions and Isolation\n\nTreat permissions and sandboxing as separate controls:\n\n- Use permission rules to decide whether a tool call may run.\n- Use a sandbox profile to limit what an approved call may access.\n- Prefer `--sandbox workspace` for normal repository changes.\n- Prefer `--sandbox read-only` for review and auditing.\n- Prefer `--sandbox strict` for an untrusted repository, then add narrow permission rules.\n- Use `--allow ` and `--deny ` for per-run policy; remember that deny rules win.\n- Use `--always-approve` only when the environment and command scope justify unattended execution. Pair it with a suitable sandbox and explicit deny rules.\n\nDo not describe `--always-approve` as equivalent to sandboxing. The sandbox is off by default unless configured or selected.\n\n## Manage Sessions and Worktrees\n\nContinue or resume intentionally:\n\n```bash\ngrok -c\ngrok --resume \ngrok --resume\n```\n\nUse `--session-id ` for a new named session, not to resume an existing one. Add `--fork-session` when branching from a resumed session.\n\nUse a worktree when concurrent work could collide:\n\n```bash\ngrok --worktree --ref main \"Fix the flaky test\"\ngrok --worktree=feature-name \"Implement the feature\"\n```\n\nPreview removal with `grok worktree rm --dry-run ` before deleting a worktree. Do not assume deleting a session removes its worktree.\n\n## Diagnose Before Editing Configuration\n\nUse built-in inspection and diagnostics first:\n\n```bash\ngrok inspect --json\ngrok mcp list --json\ngrok mcp doctor\ngrok plugin list\ngrok models\n```\n\nPrefer `grok mcp add`, `grok mcp remove`, and plugin subcommands over manually editing configuration when the CLI supports the requested operation. Keep secrets in environment variables rather than command history or committed configuration.\n\n## Read the Bundled References\n\n- Read [references/cli-reference.md](references/cli-reference.md) for the subcommand and common flag index.\n- Read [references/workflows.md](references/workflows.md) for headless execution, sessions, worktrees, permissions, sandboxing, and MCP examples.\n\nVerify destructive commands such as session deletion, plugin removal, MCP removal, memory clearing, and worktree removal with the user or the governing workflow before running them.\n","packages/cli/src/skill/builtin/.bundle/html-to-video-pipeline/SKILL.md":"---\nname: html-to-video-pipeline\ndescription: Reliable HTML-to-MP4 rendering via headless browser recording (Playwright/Puppeteer) + ffmpeg — the ordering, gotchas, and verification steps you MUST get right or the output silently rots. Trigger whenever the user is building or debugging any pipeline that turns an HTML/CSS/JS page (single-file, multi-composition, GSAP-driven, or `@keyframes`-driven) into a video file, including headless recording, screen capture of a web page, deterministic frame-by-frame capture, multi-scene concatenation, or engine-mixed video output. Also trigger when the symptom sounds like: font swap flashing in the opening frames (FOUT), the first few seconds of the video are frozen/dead, animations play during page load and get truncated, concatenated segments produce a video whose duration is wildly wrong (e.g., 8s becomes 35s), `file://` loaded HTML fails to fetch its sub-scenes, the exported video is soft/blurry compared to the browser, or playback stutters/looks choppy despite passing a high `-r` fps to ffmpeg. Use even for one-off scripts — the failure modes here are subtle enough that starting from scratch usually reintroduces them.\n---\n\n# HTML → Video: the pipeline that actually works\n\nTurning a live HTML page into an MP4 sounds like a one-liner (\"Playwright records, ffmpeg encodes\") and the first draft always looks fine — until you play back the export and notice text flashing in a fallback font, three dead seconds at the start, or a \"10-second\" clip that clocks in at 35s. This skill captures the specific ordering, waits, and encoder flags that make the output trustworthy.\n\nThink of the pipeline as five phases with a single invariant between them:\n\n```\nlaunch → hold @ frame 0 → align capture start with animation start → record → trim & encode\n```\n\nThe invariant: **no pixel of the animation should render before capture is ready, AND capture must not start before every asset that affects layout has loaded.** Every gotcha below is a violation of that invariant.\n\nQuick checklist (each item is expanded below):\n\n1. `viewport` must exactly equal `recordVideo.size` — mismatch silently rescales the output soft/blurry.\n2. Freeze CSS animations via `addInitScript` **before** `goto()`.\n3. `goto` with `domcontentloaded`, never `load`.\n4. Pre-inline `data-composition-src` sub-scenes — `file://` blocks client-side `fetch`.\n5. Font wait = stylesheet `` load → `face.load()` per face → `fonts.ready` → 2 rAFs.\n6. Probe duration with infinite-iteration / `repeat: -1` guards.\n7. Unfreeze = t=0; trim `leadInMs − 120ms` with `-ss` *before* `-i`.\n8. Concat: same engine → demuxer `-c copy`; mixed engines → concat *filter* + re-encode.\n9. Verify with ffprobe duration + full decode + sampled frames. Always.\n\nThere are two capture modes, and picking the wrong one wastes a day:\n\n- **Mode A — real-time `recordVideo`** (the phases below). Simple, wall-clock = clip length. But the screencast is best-effort variable frame rate (~25fps) and competes with the animation for CPU. Good enough for previews and ≤30fps deliverables on an idle machine.\n- **Mode B — deterministic frame stepping** (pause everything, seek to `i / fps`, screenshot, encode the PNG sequence). Exact fps, every frame rendered, no lead-in trim, immune to machine load. Required when the output must be genuinely smooth ≥30fps or renders run on loaded CI. See \"Deterministic frame stepping\" below.\n\n## Prerequisites — install these first\n\nTwo hard requirements: a headless browser driver (Playwright or Puppeteer) and `ffmpeg`. Everything below assumes both are installed and on `PATH`.\n\n### 1. Headless browser driver\n\nPlaywright is the default in this skill (its `recordVideo` API is what the pipeline is written against). Puppeteer works too but you'll wire recording yourself via CDP screencast — pick Playwright unless you have a reason not to.\n\n```bash\n# Playwright (recommended) — npm / pnpm / bun all work\nnpm install playwright\npnpm add playwright\nbun add playwright\n\n# Then install the actual browser binaries (this is the step people forget):\nnpx playwright install chromium # just Chromium — enough for this pipeline\nnpx playwright install --with-deps chromium # Linux/CI: also install shared libs\n```\n\nVerify: `npx playwright --version` prints the driver version, and `node -e \"require('playwright').chromium.launch().then(b => b.close())\"` exits cleanly.\n\nPuppeteer alternative (only if you already have it in the project):\n\n```bash\nnpm install puppeteer # bundles a matching Chromium automatically\n# or, to reuse a system Chrome:\nnpm install puppeteer-core # no bundled browser — you supply executablePath\n```\n\n### 2. ffmpeg\n\nThe encode/trim/concat/verify steps all shell out to `ffmpeg` (and `ffprobe`, which ships in the same package). It is **not** an npm dependency — install it at the OS level.\n\n```bash\n# macOS\nbrew install ffmpeg\n\n# Debian / Ubuntu\nsudo apt-get update && sudo apt-get install -y ffmpeg\n\n# Fedora / RHEL\nsudo dnf install ffmpeg # requires RPM Fusion enabled\n\n# Windows\nwinget install Gyan.FFmpeg # or: choco install ffmpeg\n```\n\nVerify: `ffmpeg -version` and `ffprobe -version` both print. If a script spawns `ffmpeg` and gets `ENOENT`, the binary isn't on `PATH` — see the graceful-failure snippet in `references/ffmpeg-cheatsheet.md`.\n\nDo **not** rely on the `ffmpeg-static` / `@ffmpeg-installer/ffmpeg` npm packages for production: their bundled builds skip codecs and encoder flags you'll hit sooner or later (e.g. `libx264` presets, `tpad`). A system ffmpeg is the durable choice.\n\n### 3. Optional — ImageMagick (verification only)\n\nOnly needed if you want the \"did anything render?\" pixel-mean check from Phase 6. Skip it otherwise.\n\n```bash\nbrew install imagemagick # macOS\nsudo apt-get install imagemagick # Debian/Ubuntu\n```\n\nVerify: `magick -version` (ImageMagick 7) or `convert -version` (ImageMagick 6).\n\n## The pipeline\n\n### Phase 1 — Launch and prepare the recorder\n\nUse `playwright.chromium.launch({ headless: true })` and a context configured with `recordVideo: { dir, size: { width, height } }`. Two sizing rules:\n\n- **`viewport` must exactly equal `recordVideo.size`.** When they differ, Playwright rescales the screencast to fit the recording size and the whole output goes soft. Derive both from the same constants.\n- `recordVideo` captures at CSS-pixel resolution; `deviceScaleFactor` does **not** raise recording resolution. For a 1080p export use a 1920×1080 viewport, not 960×540 @ 2x.\n\nRecording begins the instant the context exists — treat that timestamp as the WebM's t=0 and remember it (`tWebmStart = Date.now()`); you will need it in Phase 5 to trim the dead opening.\n\nKnow the recorder's ceiling: the screencast runs at a variable ~25fps and drops frames under CPU load. The `-r ` flag in Phase 5 makes the container constant-frame-rate but only duplicates frames — it cannot add smoothness. If stutter matters, switch to frame stepping (Mode B) instead of fighting this.\n\n### Phase 2 — Freeze animations BEFORE the page parses\n\nThis is the single most-missed step. Pure-CSS `@keyframes` animations begin the moment the element is styled — there is no JS trigger to hold. If you `goto()` the HTML and then start waiting for fonts (which takes seconds), the CSS timeline has *already been running the whole time*. The recording captures the fallback font swapping to the real face mid-clip, and the opening beats of the animation are lost to the font wait.\n\nFix: inject a global freeze **via `page.addInitScript()`**, which runs before any of the document's own scripts and before CSS is applied, so the timeline is paused at frame 0 the moment it exists:\n\n```js\nawait page.addInitScript(() => {\n const style = document.createElement('style');\n style.id = '__freeze';\n style.textContent =\n '*, *::before, *::after { animation-play-state: paused !important;' +\n ' -webkit-animation-play-state: paused !important; }';\n const attach = () => (document.head || document.documentElement).appendChild(style);\n if (document.head || document.documentElement) attach();\n else document.addEventListener('DOMContentLoaded', attach, { once: true });\n window.__unfreeze = () => document.getElementById('__freeze')?.remove();\n});\n```\n\nThis does not stop GSAP tweens driven by JS (see Phase 4 for those) — for GSAP-driven templates, register the master timeline paused and expose a `window.__playAll()` you call in Phase 4.\n\n### Phase 3 — Load with `domcontentloaded`, not `load`\n\n`waitUntil: 'load'` blocks on every external asset, including cross-origin videos with no CORS headers. Chromium will retry those for ~4s before giving up, and those 4s get burned into the recording as a frozen first scene. Use `waitUntil: 'domcontentloaded'` — the DOM + synchronous inline scripts (GSAP, your player) are ready, and you handle fonts explicitly next.\n\nIf the template is multi-composition (scenes loaded via `data-composition-src` and client-side `fetch`), you must **pre-inline** those sub-files into the entry HTML on the Node side and write it to a sibling `.tmp.html`. Chromium blocks `file://` fetch, so client-side scene loaders that work in a browser tab will silently produce an empty shell in a headless recording. See `references/multi-composition.md`.\n\n### Phase 4 — Wait for fonts properly, then release\n\n`document.fonts.ready` alone is **not enough** and this is the second most-missed step. Under `domcontentloaded`, the Google Fonts (or any external) `` has usually not returned yet. Until its CSS arrives, its `@font-face` rules are not in `document.fonts` at all — so `fonts.ready` sees an empty set and resolves *instantly*. Recording proceeds, the CSS lands mid-clip, faces download, and the swap happens on-camera.\n\nThe correct sequence, all inside a `page.evaluate()` with an 8s hard cap so a wedged CDN can't stall forever:\n\n1. Wait for every `` to `load` or `error` — that registers `@font-face` rules into `document.fonts`.\n2. For each registered face, call `face.load()` explicitly. `font-display: swap` defers the download until something paints with that face — if your first frame doesn't happen to use the face, it never fetches without this.\n3. `await fonts.ready`.\n4. Two rAFs so layout settles on the real glyph metrics before frame 0.\n\nThen, and only then:\n\n5. Drive playback: for GSAP multi-composition templates, call `window.__playAll()` to start every registered (paused) master timeline from 0. For pure-CSS templates, this is a no-op.\n6. Call `window.__unfreeze()` to remove the freeze style. **This is the true t=0 of the animation.** Record the wall-clock offset from `tWebmStart` (`leadInMs = Date.now() - tWebmStart`) — this is what you trim in Phase 5.\n\nThe full JS for Phase 4 is in `references/font-wait.md`.\n\n### Phase 5 — Probe duration, record, then trim and encode\n\n**Probe duration first** (skip this only if you know the exact intended length). The user's requested `duration` may be shorter than the animation, in which case you'd cut the animation mid-play. Take the maximum of:\n\n- The longest **non-infinite** CSS animation (`animation-duration + animation-delay` for entries where `animation-iteration-count !== 'infinite'`).\n- The longest **finite** GSAP tween. Do **not** use `gsap.globalTimeline.totalDuration()` — a `repeat: -1` tween (blinking cursor, looping background) makes it ~1e10s. Walk `globalTimeline.getChildren(true, true, true)` and skip anything with `repeat() === -1`.\n\nAdd a ~400ms settle so the last animation frame is captured, cap at 30s so a stray huge value can't run away. If your caller passed an *explicit* per-frame duration (e.g. \"each scene is exactly 4s\"), do **not** extend — treat it as a hard cap and pad the tail if the animation finished early (see below). If duration was 'auto', extend to the probed length.\n\n**Record** for `totalDuration`, then `context.close()`. Playwright drops the WebM in `recordDir`.\n\n**Encode with ffmpeg**, applying two corrections:\n\n```\nffmpeg -y \\\n [ -ss <(leadInMs - 120) / 1000> ] # trim dead lead-in, back off 120ms so we don't clip frame 1\n -i input.webm \\\n [ -vf tpad=stop_mode=clone:stop_duration= ] # pad tail only when duration is explicit\n -t \\ # trim to exact length (recordVideo sometimes overshoots)\n -r \\\n -c:v libx264 -pix_fmt yuv420p -preset medium -crf 20 \\\n -movflags +faststart \\\n out.mp4\n```\n\nThe `-ss` back-off matters: recorder start jitter and rounding can steal the first real frame if you trim to exactly `leadInMs`. A couple of extra still frames at the head are invisible; a missing opening beat is obvious.\n\n## Deterministic frame stepping (Mode B)\n\nWhen the deliverable must be genuinely smooth at an exact fps — or the render runs on a loaded CI box where real-time capture visibly stutters — don't record in real time at all. Keep Phases 1–4 (minus `recordVideo`), then: pause every timeline, seek to `i / fps`, `page.screenshot()` each frame, and encode the PNG sequence with `ffmpeg -framerate `. Duration is exact by construction, there is no lead-in to trim, and every single frame is fully rendered regardless of machine load.\n\nIt works when the page's motion is declaratively seekable — CSS `@keyframes` (via `document.getAnimations()` + `currentTime`), WAAPI, and GSAP (`gsap.globalTimeline.time(t)`). It does **not** work for `