cue-ai 0.3.0

package/resources/skills/skills/orchestration/codex-fleet-login/codex_fleet_login.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# codex_fleet_login.sh — spawn kitty terminal(s) running `codex login`, capture
+# the OAuth URL from each, and open it in the default browser.
+#
+# Mirrors the gx-cockpit / gx-fleet pattern: prefers Kitty remote control when
+# we are already inside a Kitty session, otherwise spawns a fresh Kitty window.
+#
+# Usage:
+#   codex_fleet_login.sh                 # one terminal
+#   codex_fleet_login.sh --count 3       # three terminals, sequential
+#   codex_fleet_login.sh --no-open       # don't auto-open URL, just print it
+#   codex_fleet_login.sh --label foo     # tag log filenames
+#   codex_fleet_login.sh --hold          # leave the kitty window open after exit
+#
+# Why sequential by default: `codex login` binds localhost:1455, so two logins
+# at once collide. We launch one, wait for it to finish, then launch the next.
+
+set -euo pipefail
+
+COUNT=1
+OPEN_URL=1
+OPEN_MODE="incognito"     # incognito | default | none
+LABEL=""
+HOLD=1
+PORT="${CODEX_LOGIN_PORT:-1455}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --count)         COUNT="$2"; shift 2 ;;
+    --no-open)       OPEN_URL=0; shift ;;
+    --open-default)  OPEN_MODE="default"; shift ;;
+    --open-incognito) OPEN_MODE="incognito"; shift ;;
+    --label)         LABEL="$2"; shift 2 ;;
+    --hold)          HOLD=1; shift ;;
+    --no-hold)       HOLD=0; shift ;;
+    -h|--help)       sed -n '2,18p' "$0"; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+# Pick a browser launcher for the URL.
+# Default: Chrome/Chromium --incognito (bypasses cache, extensions, and stale
+# service workers on auth.openai.com that have been seen to render a blank
+# page when the user's main profile is hot).
+pick_browser_cmd() {
+  case "$OPEN_MODE" in
+    none)    echo ""; return ;;
+    default) command -v xdg-open >/dev/null && echo "xdg-open" && return
+             echo ""; return ;;
+    incognito|*)
+      for c in google-chrome google-chrome-stable chromium chromium-browser brave-browser; do
+        if command -v "$c" >/dev/null; then
+          echo "$c --incognito --new-window"
+          return
+        fi
+      done
+      # firefox private as fallback
+      if command -v firefox >/dev/null; then
+        echo "firefox --private-window"
+        return
+      fi
+      # last resort: default opener (no incognito guarantee)
+      command -v xdg-open >/dev/null && echo "xdg-open"
+      ;;
+  esac
+}
+BROWSER_CMD="$(pick_browser_cmd)"
+
+command -v kitty >/dev/null || { echo "kitty not found on PATH" >&2; exit 1; }
+command -v codex >/dev/null || { echo "codex not found on PATH" >&2; exit 1; }
+
+LOG_DIR="${TMPDIR:-/tmp}/codex-fleet-login"
+mkdir -p "$LOG_DIR"
+
+# Detect Kitty remote-control availability (gx-fleet style).
+KITTY_REMOTE=0
+if [[ -n "${KITTY_LISTEN_ON:-}" ]] && kitty @ ls >/dev/null 2>&1; then
+  KITTY_REMOTE=1
+fi
+
+extract_url() {
+  grep -oE 'https://auth\.openai\.com/oauth/authorize\?[^[:space:]]+' "$1" \
+    | head -n1 || true
+}
+
+spawn_one() {
+  local idx="$1"
+  local stamp
+  stamp="$(date +%Y%m%d-%H%M%S)"
+  local tag="${LABEL:+${LABEL}-}${idx}"
+  local log="$LOG_DIR/codex-login-${stamp}-${tag}.log"
+  local done_marker="${log}.done"
+
+  : > "$log"
+
+  echo "[fleet] window #${idx}  log=${log}"
+
+  local hold_line='echo "[codex-fleet-login] codex login exited (status=$status). Press Enter to close."; read -r _'
+  if (( HOLD == 0 )); then
+    hold_line='exit $status'
+  fi
+
+  # The command that runs inside the kitty window.
+  local inner_cmd
+  # Resolve a non-guarded codex binary in the outer env so the kitty subshell
+  # doesn't depend on its login-shell PATH (e.g. nvm not sourced under bash -lc).
+  local codex_bin=""
+  IFS=':' read -r -a _path_dirs <<< "$PATH"
+  local _self_resolved=""
+  if local _shim="$(command -v codex 2>/dev/null)"; then
+    _self_resolved="$(readlink -f "$_shim" 2>/dev/null || echo "$_shim")"
+  fi
+  for _d in "${_path_dirs[@]}"; do
+    [[ -z "$_d" ]] && continue
+    local _c="$_d/codex"
+    [[ -x "$_c" && ! -d "$_c" ]] || continue
+    local _r
+    _r="$(readlink -f "$_c" 2>/dev/null || echo "$_c")"
+    if [[ "$_r" != "$_self_resolved" ]]; then
+      codex_bin="$_c"
+      break
+    fi
+  done
+  # Fallback: pass through the name and let the inner shell resolve it.
+  [[ -z "$codex_bin" ]] && codex_bin="codex"
+
+  inner_cmd=$(cat <<EOF
+clear
+echo "[codex-fleet-login] account #${idx} — log: ${log}"
+echo "[codex-fleet-login] codex: ${codex_bin}"
+echo "[codex-fleet-login] running: codex login"
+echo
+CODEX_GUARD_BYPASS=1 "${codex_bin}" login 2>&1 | tee "${log}"
+status=\${PIPESTATUS[0]}
+touch "${done_marker}"
+echo
+${hold_line}
+EOF
+)
+
+  if (( KITTY_REMOTE == 1 )); then
+    kitty @ launch \
+      --type=os-window \
+      --title "codex-login-${tag}" \
+      --keep-focus \
+      bash -lc "$inner_cmd" >/dev/null
+  else
+    setsid kitty --title "codex-login-${tag}" \
+      bash -lc "$inner_cmd" </dev/null >/dev/null 2>&1 &
+    disown $! 2>/dev/null || true
+  fi
+
+  # Wait for the OAuth URL to appear in the log (codex prints it within ~1s).
+  local url=""
+  local waited=0
+  while (( waited < 30 )); do
+    url=$(extract_url "$log")
+    [[ -n "$url" ]] && break
+    sleep 1
+    waited=$((waited+1))
+  done
+
+  if [[ -z "$url" ]]; then
+    echo "[fleet] WARNING: no OAuth URL within 30s — check the kitty window" >&2
+  else
+    echo "[fleet] URL: $url"
+    if (( OPEN_URL == 1 )); then
+      if [[ -n "$BROWSER_CMD" ]]; then
+        # shellcheck disable=SC2086
+        ( nohup $BROWSER_CMD "$url" >/dev/null 2>&1 & )
+        echo "[fleet] opened via: $BROWSER_CMD"
+      else
+        echo "[fleet] no browser launcher available — copy the URL manually"
+      fi
+    fi
+  fi
+
+  # Wait for codex login to finish (done marker), so the next iteration
+  # doesn't collide on port ${PORT}.
+  local max_wait=600   # 10 min for user to finish OAuth in browser
+  waited=0
+  while [[ ! -f "$done_marker" ]] && (( waited < max_wait )); do
+    sleep 2
+    waited=$((waited+2))
+  done
+
+  if [[ -f "$done_marker" ]]; then
+    echo "[fleet] window #${idx} finished"
+  else
+    echo "[fleet] window #${idx} still running after ${max_wait}s — moving on" >&2
+  fi
+}
+
+for ((i=1; i<=COUNT; i++)); do
+  spawn_one "$i"
+  if (( i < COUNT )); then
+    echo "[fleet] cooling down 2s before next window..."
+    sleep 2
+  fi
+done
+
+echo "[fleet] done. Logs under ${LOG_DIR}/"

package/resources/skills/skills/orchestration/pipeline/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: pipeline
+description: "[OMX] Configurable pipeline orchestrator for sequencing stages"
+---
+
+# Pipeline Skill
+
+`$pipeline` is the configurable pipeline orchestrator for OMX. It sequences stages
+through a uniform `PipelineStage` interface, with state persistence and resume support.
+
+## Default Autopilot Pipeline
+
+The canonical OMX pipeline sequences:
+
+```
+RALPLAN (consensus planning) -> team-exec (Codex CLI workers) -> ralph-verify (architect verification)
+```
+
+## Configuration
+
+Pipeline parameters are configurable per run:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `maxRalphIterations` | 10 | Ralph verification iteration ceiling |
+| `workerCount` | 2 | Number of Codex CLI team workers |
+| `agentType` | `executor` | Agent type for team workers |
+
+## Stage Interface
+
+Every stage implements the `PipelineStage` interface:
+
+```typescript
+interface PipelineStage {
+  readonly name: string;
+  run(ctx: StageContext): Promise<StageResult>;
+  canSkip?(ctx: StageContext): boolean;
+}
+```
+
+Stages receive a `StageContext` with accumulated artifacts from prior stages and
+return a `StageResult` with status, artifacts, and duration.
+
+## Built-in Stages
+
+- **ralplan**: Consensus planning (planner + architect + critic). Skips only when both `prd-*.md` and `test-spec-*.md` planning artifacts already exist, and carries any `deep-interview-*.md` spec paths forward for traceability.
+- **team-exec**: Team execution via Codex CLI workers. Always the OMX execution backend.
+- **ralph-verify**: Ralph verification loop with configurable iteration count.
+
+## State Management
+
+Pipeline state persists via the ModeState system at `.omx/state/pipeline-state.json`.
+The HUD renders pipeline phase automatically. Resume is supported from the last incomplete stage.
+
+- **On start**: `omx state write --input '{"mode":"pipeline","active":true,"current_phase":"stage:ralplan"}' --json`
+- **On stage transitions**: `omx state write --input '{"mode":"pipeline","current_phase":"stage:<name>"}' --json`
+- **On completion**: `omx state write --input '{"mode":"pipeline","active":false,"current_phase":"complete"}' --json`
+
+## API
+
+```typescript
+import {
+  runPipeline,
+  createAutopilotPipelineConfig,
+  createRalplanStage,
+  createTeamExecStage,
+  createRalphVerifyStage,
+} from './pipeline/index.js';
+
+const config = createAutopilotPipelineConfig('build feature X', {
+  stages: [
+    createRalplanStage(),
+    createTeamExecStage({ workerCount: 3, agentType: 'executor' }),
+    createRalphVerifyStage({ maxIterations: 15 }),
+  ],
+});
+
+const result = await runPipeline(config);
+```
+
+## Relationship to Other Modes
+
+- **autopilot**: Autopilot can use pipeline as its execution engine (v0.8+)
+- **team**: Pipeline delegates execution to team mode (Codex CLI workers)
+- **ralph**: Pipeline delegates verification to ralph (configurable iterations)
+- **ralplan**: Pipeline's first stage runs RALPLAN consensus planning

package/resources/skills/skills/orchestration/visual-ralph/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: visual-ralph
+description: "[OMX] Visual Ralph orchestration for frontend UI from generated references, static references, or live URL targets, using $ralph with built-in visual verdict and pixel-diff evidence until the implementation matches and leaves a reproducible design system."
+---
+
+# Visual Ralph Skill
+
+Use this skill when the user wants Codex to build or restyle frontend UI through a Visual Ralph loop: an approved generated reference, static reference, or live URL-derived baseline becomes the target, Ralph implements, and Visual Verdict drives measured iteration rather than subjective description alone.
+
+## Purpose
+
+Create a measured frontend delivery loop from either a generated reference, a static reference, or a live URL:
+
+`user description / live URL -> approved visual reference -> $ralph implementation -> Visual Ralph verdict + pixel diff -> reproducible design system`.
+
+For live URL cloning requests, Visual Ralph owns the migrated `$web-clone` use case. Do not route new URL-driven website cloning work to `$web-clone`; preserve the URL, viewport, fidelity requirements, and interaction notes inside the Visual Ralph loop.
+
+This is an orchestration skill. It composes existing skills and must not add runtime commands, dependencies, or app-specific assumptions by itself.
+
+## Use when
+
+- The user describes a desired web/app UI and wants implementation, not just design advice.
+- The user provides a live URL and wants a visual implementation or clone through measured Visual Verdict iteration.
+- A generated raster mockup/reference image would make the target clearer.
+- The task needs pixel-level visual iteration with a pass/fail threshold.
+- The final result should leave reusable design tokens/components, not only a one-off screenshot match.
+
+## Do not use when
+
+- The user only wants design critique or general frontend advice; use `$frontend-ui-ux` or a designer lane.
+- The task is a non-visual backend/API implementation with no UI reference target.
+- The user already supplied a final static reference image and only needs comparison/fixes; hand directly to `$ralph` with Visual Ralph verdict guidance.
+- The requested output is a deterministic SVG/vector/code-native asset rather than a raster reference.
+
+## Workflow
+
+### 1. Ground the target repo
+
+Before stack-specific choices, inspect local evidence:
+- package manager and scripts,
+- frontend framework and routing structure,
+- styling system and design-token conventions,
+- screenshot/test tooling,
+- existing components that should be reused.
+
+Do not hardcode React, Vue, Tailwind, Playwright, or any other stack unless the repository evidence supports it.
+
+### 2. Establish the visual reference
+
+For live URL requests, capture or document the URL-derived reference inside the Visual Ralph artifacts and carry forward viewport, content-state, and interaction constraints. Do not invoke `$web-clone`; that standalone skill is hard-deprecated.
+
+Live URL reference artifacts must include:
+- source URL and permission/scope note,
+- viewport(s), route/state, and any seed/login assumptions,
+- captured baseline screenshot path or documented capture command/tool,
+- interaction parity notes for visible controls,
+- known exclusions such as backend/API/auth, personalized data, multi-page crawling, and third-party widget parity.
+
+For generated UI concepts, use `$imagegen` to produce the reference from the user's UI description.
+
+Prompt requirements:
+- classify as `ui-mockup`, unless another imagegen taxonomy is clearly better,
+- include viewport/aspect ratio and intended surface,
+- specify layout, hierarchy, typography direction, color mood, and any exact text,
+- forbid logos/watermarks/unrequested brand marks,
+- ask imagegen to avoid impossible UI details or unreadable text.
+
+When running under OMX CLI/runtime and a generated reference is part of an active Ralph-style loop, queue a continuation checkpoint before invoking the built-in image tool:
+
+```bash
+omx imagegen continuation <session-id> --artifact <slug-or-filename> --generated-dir "$CODEX_HOME/generated_images/<session>" --work-dir ".omx/artifacts/visual-ralph/<slug>"
+```
+
+This helper records `.omx/state/sessions/<session>/imagegen-pending.json` and uses the existing Stop-hook follow-up queue. It exists because built-in image generation may have to end the assistant turn immediately; the next Stop checkpoint should resume artifact recovery, copy the generated image into the workspace, and run the required visual QA/verdict gate instead of relying on a manual `$ralph` re-prompt.
+
+For project-bound implementation, copy the approved reference into the workspace, for example under `.omx/artifacts/visual-ralph/<slug>/reference.png`. Never leave the implementation reference only in `$CODEX_HOME/generated_images/...`.
+
+### 3. Require explicit user approval
+
+Stop after reference generation or URL-derived reference capture and ask the user to approve one reference image/state or request a targeted regeneration/capture adjustment.
+
+Before approval:
+- do not start frontend implementation,
+- do not invoke `$ralph`,
+- do not treat a rough image as final.
+
+After approval, the confirmed image or URL-derived baseline becomes the visual source of truth. Major design pivots, replacing the reference, or changing the design direction require an explicit user request.
+
+### 4. Hand off to `$ralph` for implementation
+
+Invoke `$ralph` with:
+- the approved reference image path or URL-derived baseline artifact,
+- source URL, viewport(s), content state, and interaction parity notes for live URL tasks,
+- the user description,
+- the detected repo/frontend context,
+- exact screenshot command/viewport requirements,
+- the completion checklist below.
+
+Ralph may iterate autonomously after approval. It should edit code, run the app, capture screenshots, and keep improving until the approved reference is matched or a real blocker exists.
+
+### 5. Use Visual Ralph verdict before every next edit
+
+For each visual iteration:
+1. Capture the current generated screenshot with recorded viewport/state.
+2. Run the Visual Ralph verdict step comparing the approved reference and generated screenshot. Use the `vision` agent for image understanding when needed.
+3. Treat the JSON verdict as authoritative.
+4. If `score < 90`, convert `differences[]` and `suggestions[]` into the next edit plan.
+5. Rerun before the next edit.
+
+Required verdict shape: `score`, `verdict`, `category_match`, `differences[]`, `suggestions[]`, and `reasoning`.
+
+### 6. Use pixel diff only as secondary debug evidence
+
+When mismatch diagnosis is hard, generate a pixel diff or pixelmatch overlay to locate hotspots. Pixel diff does not replace the Visual Ralph verdict; it only helps translate visual hotspots into concrete edits.
+
+Record final diff evidence with the reference/screenshot artifacts so the result can be audited.
+
+### 7. Build a reproducible design system
+
+The implementation is incomplete unless the visual match is encoded in repo-native reusable artifacts. Depending on the project, this may mean CSS variables, theme tokens, Tailwind config, component variants, Storybook stories, design docs, or existing equivalents.
+
+Capture at least the applicable:
+- colors,
+- spacing scale,
+- typography scale/weights,
+- radii,
+- shadows/elevation,
+- important component variants and states.
+
+Prefer existing token/component patterns. Do not introduce a new design-system layer if the repo already has one that can be extended.
+
+## Completion checklist
+
+Do not declare done until all are true:
+- Approved reference image or URL-derived reference artifact is saved in the workspace.
+- Screenshot reproduction command, viewport, route, seed/state, and output paths are documented.
+- Visual Ralph verdict final score is `>= 90` against the approved reference.
+- Pixel diff or overlay evidence is recorded as secondary debug evidence.
+- Design-system tokens/components are repo-native and reusable.
+- Build/lint/test or the repo's equivalent verification passes.
+- No unapproved major design pivot occurred after reference approval.
+- Remaining visual differences, if any, are explicitly documented with rationale.
+
+## Handoff template
+
+```text
+$ralph "Implement the approved frontend reference.
+Reference: <workspace-reference-image-or-url-derived-artifact>
+Source URL (if URL-derived): <url and permission/scope note>
+Viewport/content state: <viewport, route/state, seed/login assumptions>
+Interaction parity notes: <visible controls and known exclusions>
+Route/surface: <route or component>
+Screenshot command: <command and viewport>
+Use the Visual Ralph verdict step before every next edit; pass threshold score >= 90.
+Use pixel diff only as secondary debug evidence.
+Extract reusable design tokens/components for colors, spacing, typography, radii, shadows, and key variants.
+Run build/lint/test before completion.
+Do not make major design pivots unless explicitly requested."
+```
+
+Task: {{ARGUMENTS}}

package/resources/skills/skills/orchestration/worker/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: worker
+description: "[OMX] Team worker protocol (ACK, mailbox, task lifecycle) for tmux-based OMX teams"
+---
+
+# Worker Skill
+
+This skill is for a Codex session that was started as an OMX Team worker (a tmux pane spawned by `$team`).
+
+## Identity
+
+You MUST be running with `OMX_TEAM_WORKER` set. It looks like:
+
+`<team-name>/worker-<n>`
+
+Example: `alpha/worker-2`
+
+## Load Worker Skill Path (Claude/Codex)
+
+When a worker inbox tells you to load this skill, resolve the first existing path:
+
+1. `${CODEX_HOME:-~/.codex}/skills/worker/SKILL.md`
+2. `~/.codex/skills/worker/SKILL.md`
+3. `<leader_cwd>/.codex/skills/worker/SKILL.md`
+4. `<leader_cwd>/skills/worker/SKILL.md` (repo fallback)
+
+## Startup Protocol (ACK)
+
+1. Parse `OMX_TEAM_WORKER` into:
+   - `teamName` (before the `/`)
+   - `workerName` (after the `/`, usually `worker-<n>`)
+2. Send a startup ACK to the lead mailbox **before task work**:
+   - Recipient worker id: `leader-fixed`
+   - Body: one short deterministic line (recommended: `ACK: <workerName> initialized`).
+3. After ACK, proceed to your inbox instructions.
+
+The lead will see your message in:
+
+`<team_state_root>/team/<teamName>/mailbox/leader-fixed.json`
+
+Use CLI interop:
+- `omx team api send-message --input <json> --json` with `{team_name, from_worker, to_worker:"leader-fixed", body}`
+
+Copy/paste template:
+
+```bash
+omx team api send-message --input "{\"team_name\":\"<teamName>\",\"from_worker\":\"<workerName>\",\"to_worker\":\"leader-fixed\",\"body\":\"ACK: <workerName> initialized\"}" --json
+```
+
+## Inbox + Tasks
+
+1. Resolve canonical team state root in this order:
+   1) `OMX_TEAM_STATE_ROOT` env
+   2) worker identity `team_state_root`
+   3) team config/manifest `team_state_root`
+   4) local cwd fallback (`.omx/state`)
+2. Read your inbox:
+   `<team_state_root>/team/<teamName>/workers/<workerName>/inbox.md`
+3. Pick the first unblocked task assigned to you.
+4. Read the task file:
+   `<team_state_root>/team/<teamName>/tasks/task-<id>.json` (example: `task-1.json`)
+5. Task id format:
+   - The MCP/state API uses the numeric id (`"1"`), not `"task-1"`.
+   - Never use legacy `tasks/{id}.json` wording.
+6. Claim the task (do NOT start work without a claim) using claim-safe lifecycle CLI interop (`omx team api claim-task --json`).
+7. Do the work.
+8. Complete/fail the task via lifecycle transition CLI interop (`omx team api transition-task-status --json`) from `in_progress` to `completed` or `failed`.
+   - Do NOT directly write lifecycle fields (`status`, `owner`, `result`, `error`) in task files.
+9. Use `omx team api release-task-claim --json` only for rollback/requeue to `pending` (not for completion).
+10. Update your worker status:
+   `<team_state_root>/team/<teamName>/workers/<workerName>/status.json` with `{"state":"idle", ...}`
+
+## Mailbox
+
+Check your mailbox for messages:
+
+`<team_state_root>/team/<teamName>/mailbox/<workerName>.json`
+
+When notified, read messages and follow any instructions. Use short ACK replies when appropriate.
+
+Note: leader dispatch is state-first. The durable queue lives at:
+`<team_state_root>/team/<teamName>/dispatch/requests.json`
+Hooks/watchers may nudge you after mailbox/inbox state is already written.
+
+Use CLI interop:
+- `omx team api mailbox-list --json` to read
+- `omx team api mailbox-mark-delivered --json` to acknowledge delivery
+
+Copy/paste templates:
+
+```bash
+omx team api mailbox-list --input "{\"team_name\":\"<teamName>\",\"worker\":\"<workerName>\"}" --json
+omx team api mailbox-mark-delivered --input "{\"team_name\":\"<teamName>\",\"worker\":\"<workerName>\",\"message_id\":\"<MESSAGE_ID>\"}" --json
+```
+
+## Dispatch Discipline (state-first)
+
+Worker sessions should treat team state + CLI interop as the source of truth.
+
+- Prefer inbox/mailbox/task state and `omx team api ... --json` operations.
+- Do **not** rely on ad-hoc tmux keystrokes as a primary delivery channel.
+- If a manual trigger arrives (for example `tmux send-keys` nudge), treat it only as a prompt to re-check state and continue through the normal claim-safe lifecycle.
+
+## Shutdown
+
+If the lead sends a shutdown request, follow the shutdown inbox instructions exactly, write your shutdown ack file, then exit the Codex session.

package/resources/skills/skills/polymarket/polymarket-predictions-audit/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: polymarket-predictions-audit
+description: >-
+  Use when user says "audit my predictions", "how is the model doing", "show prediction accuracy", "why is the model wrong", or "review my Brier score". Reads the local predictions.jsonl + Brier report via `polymarket-live` MCP and explains where the model agrees/disagrees with reality. NOT for opening or resolving predictions.
+---
+
+# Polymarket predictions audit
+
+Use this skill when the user wants to know how well their paper-trading
+predictions are tracking — accuracy, Brier vs the Polymarket baseline,
+calibration, direction bias, and which recent predictions were the worst
+misses.
+
+## When to use it
+
+- "audit my predictions"
+- "how is the momentum model doing?"
+- "why is the watch panel always saying UP?"
+- "show me where the model is wrong"
+- "is the model beating Polymarket?"
+
+## When NOT to use it
+
+- The user wants to **open or resolve** predictions → run the CLI by
+  hand. The MCP is read-only.
+- The user wants a live BTC market snapshot → use the
+  `polymarket-research` skill instead.
+
+## Recipe
+
+1. **Health-check the store.** Call
+   `mcp__polymarket-live__predictions_list(status="all", limit=1)` first
+   and read `total_in_store` from the result. If 0, tell the user the
+   JSONL store is empty and to run `polymarket predict watch --auto` or
+   `polymarket predict open` to start populating it; stop here.
+
+2. **Get the summary numbers.** Call
+   `mcp__polymarket-live__predictions_stats()` for the all-time roll-up
+   (accuracy, avg confidence, Brier, direction counts, market-baseline
+   accuracy). If the user asked about a recent window, pass
+   `last_n=<N>`.
+
+3. **Get the calibration / Brier-vs-baseline view.** Call
+   `mcp__polymarket-live__predictions_backtest(model="polymarket")` for
+   the Brier score with bootstrap CI, log-loss, and
+   `model_vs_polymarket_brier_delta`. Negative delta = model beats the
+   crowd; positive = model is worse than just trusting Polymarket.
+
+4. **Find the worst misses.** Call
+   `mcp__polymarket-live__predictions_list(status="resolved", limit=50, newest_first=True)`,
+   then locally rank by `|confidence × (1 − resolution.correct)|` (i.e.
+   "high-confidence wrongs"). Show the top 3–5 with: time, direction,
+   confidence, p_open, p_close, slug.
+
+5. **Optional: cross-check with current model thinking.** Call
+   `mcp__polymarket-live__predict_think(models=["polymarket","momentum","blend"])`
+   so the user sees what each model would say *right now* — useful to
+   tell apart "model has changed since the bad call" from "model
+   systematically wrong".
+
+## Reporting style
+
+- Lead with the headline number: e.g. "Accuracy 54% over 87 resolved
+  predictions (Brier 0.241, beating the Polymarket-implied baseline by
+  Δ−0.012)."
+- Then breakdown: UP-call accuracy vs DOWN-call accuracy. A skew
+  (e.g. 70% UP-calls / 30% DOWN-calls) is the smoking gun for "why is
+  it always UP" complaints — when the model name is `polymarket` and
+  the market is trading at 0.505 the loop will always pick UP. Surface
+  that and suggest `--auto-model momentum` or `--auto-model blend`.
+- For the misses, format as a tiny markdown table; do NOT dump raw JSON.
+- If `model_vs_polymarket_brier_delta > 0`, gently note that the user is
+  losing edge vs just trusting the order book.
+
+## Failure modes
+
+- Backtest takes >10s → split the window with `from_iso` / `to_iso` and
+  call it twice; or skip backtest and only show stats.
+- Calibration array is empty → fewer than ~10 resolved predictions; tell
+  the user to come back when the loop has been running longer.
+- MCP not registered → tell user to add `polymarket-live` under
+  `mcpServers` in `~/.claude.json` and restart Claude.