Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

feat(skills): slim ops-inbox, real triggers, lock hermes/claude/grok versions (#857)

Aurora Capital6f53c9301d88
diff --git a/README.md b/README.md
index 59f79b29..27e9e73d 100644
--- a/README.md
+++ b/README.md
@@ -274,7 +274,7 @@ claude-ops/ ← marketplace root (this repo, this README)
├── telegram-server/ # bundled MCP server (gram.js)
├── templates/ # Shopify Admin + app scaffolding
├── tests/ # bash validation · test-no-secrets.sh
- └── .mcp.json # MCP server declarations
+ └── .mcp.json # empty on purpose — MCP starts on demand, not per session
```
---
diff --git a/claude-ops/CHANGELOG.md b/claude-ops/CHANGELOG.md
index 2535be97..263761b0 100644
--- a/claude-ops/CHANGELOG.md
+++ b/claude-ops/CHANGELOG.md
@@ -1,5 +1,8 @@
## Unreleased
+- Slim `ops-inbox` SKILL.md (~6k → ~2k words): runtime, Workflow JS, and Agent Teams moved to `references/`. Rewrite remaining skill descriptions with real NL triggers (Claude / Grok / Hermes share the same `skills/` tree).
+- Sync harness ports: `hermes-plugin/plugin.yaml` version matches `plugin.json`; installer default ref tracks the latest tag; `ops-release` bumps both. Grok still loads the Claude plugin (no `.grok-plugin`). Docs: `.mcp.json` is empty on purpose.
+
- feat(cliproxy-heal): unattended hub healer puts seats back in rotation as soon as any leftover or reset quota is observed (no hysteresis). A seat sits out only on certain "quota exhausted" plus a parseable reschedule stamp, then re-enters at that stamp. An AI advisor runs on every seat and cannot override those rules. `applied=reauth` only after `CLIPROXY_REAUTH_CMD` (`cliproxy-reauth-one.sh` → hub `bu_reauth_lib.py` / `xai_device_reauth.py`); otherwise the seat is recorded blocked. Hub systemd timer `cliproxy-heal.timer`; Mac stays client-only. `runHealTick` denies healing unless both gates are satisfied: the `CLIPROXY_HUB_HEAL=1` env var, and the presence of the `/opt/crsproxy/.heal-account-optin` marker file that only `install-heal.sh` writes (not the systemd unit's `Environment=` lines), so editing the unit alone cannot satisfy both. Tests in `scripts/account-rotation/__tests__/cliproxy-heal-policy.test.mjs`.
- fix(ops-mac): the application firewall is opt-in. `/ops:mac fix` no longer offers to enable it and no longer lists it as a recommendation; the audit reports its state and stops. Turning the firewall on breaks local listeners (dev servers, MCP proxies, VNC, tunnels) and the user rarely connects the breakage to a `fix` run they asked for other reasons. `socketfilterfw` now runs only when the user asks for the firewall by name in that turn.
- **Removed the CRS relay backend.** claude-relay-service handed every session a
diff --git a/claude-ops/README.md b/claude-ops/README.md
index b411ca1f..7839ceea 100644
--- a/claude-ops/README.md
+++ b/claude-ops/README.md
@@ -406,7 +406,7 @@ Tools:
- `send_message` — send a message to a chat
- `search_messages` — full-text search across all your chats
-See [telegram-server/README.md](telegram-server/README.md) for first-run auth flow and troubleshooting. The plugin's `.mcp.json` wires all four env vars (`TELEGRAM_API_ID`, `TELEGRAM_API_HASH`, `TELEGRAM_PHONE`, `TELEGRAM_SESSION`) from your `user_config` in Claude Code plugin settings — you never paste tokens into files directly.
+See [telegram-server/README.md](telegram-server/README.md) for first-run auth flow and troubleshooting. Register it on demand in host `~/.claude.json` / plugin settings — the plugin `.mcp.json` stays empty so every session does not spawn a Telegram stdio process. Never paste tokens into files.
## Contributing
diff --git a/claude-ops/RELEASE.md b/claude-ops/RELEASE.md
index 9bf83b93..03895e67 100644
--- a/claude-ops/RELEASE.md
+++ b/claude-ops/RELEASE.md
@@ -30,6 +30,8 @@ After the release lands, refresh the local install:
| `claude-ops/.claude-plugin/plugin.json` | `.version` | the plugin's own version |
| `.claude-plugin/marketplace.json` (repo root) | `.plugins[name=="ops"].version` | the **marketplace registry** entry Claude Code reads |
| `claude-ops/package.json` (auto-detected; or repo root) | `.version` | the `claude-ops-bin` npm package (bin-script runtime deps) |
+| `claude-ops/hermes-plugin/plugin.yaml` | `version` | Hermes native plugin (same skill tree as Claude / Grok) |
+| `installer/src/config.mjs` | `DEFAULT_CONFIG.source.ref` | installer pin (`vX.Y.Z`) so new installs match the tag |
| `claude-ops/CHANGELOG.md` | new `## [X.Y.Z] - DATE` section | human-readable history (Keep a Changelog + SemVer) |
`ops-release` keeps all of these in sync — never bump them by hand, or the
@@ -43,7 +45,7 @@ never touched it; it is now bumped in lockstep.)
2. Compute the next version (`--type` bump or `--version`).
3. Create an **isolated worktree** off `origin/main` (the shared main checkout is
never touched — safe while daemons/other agents are live).
-4. Bump `plugin.json` + `marketplace.json` + `package.json` (via `jq`), prepend
+4. Bump `plugin.json` + `marketplace.json` + `package.json` (via `jq`) plus `hermes-plugin/plugin.yaml` and the installer pin, prepend
the CHANGELOG section (notes from `--notes`, else commit subjects since the
last CHANGELOG bump), and validate the JSON.
5. Commit `release: vX.Y.Z`, push the branch, open a PR to `main`.
@@ -60,7 +62,8 @@ contracts; **minor** = new skill/command/agent or backward-compatible feature;
## Manual fallback
If `ops-release` is unavailable, do the same by hand in a worktree off
-`origin/main`: bump the three JSON `version` fields (plugin.json,
-marketplace.json, package.json), add the CHANGELOG section, `commit --no-verify`,
+`origin/main`: bump the JSON `version` fields (plugin.json, marketplace.json,
+package.json), `hermes-plugin/plugin.yaml`, and the installer `source.ref`,
+add the CHANGELOG section, `commit --no-verify`,
push, `gh pr create --base main`, `gh pr merge --squash`, `git tag
vX.Y.Z && git push origin vX.Y.Z`.
diff --git a/claude-ops/bin/ops-release b/claude-ops/bin/ops-release
index b6dc33b2..8d6110bb 100755
--- a/claude-ops/bin/ops-release
+++ b/claude-ops/bin/ops-release
@@ -9,6 +9,8 @@
# 1. claude-ops/.claude-plugin/plugin.json .version
# 2. .claude-plugin/marketplace.json (repo root) .plugins[name==ops].version <- the marketplace registry
# 3. package.json (auto-detected: claude-ops/ or repo root) .version
+# 3b. claude-ops/hermes-plugin/plugin.yaml version
+# 3c. installer/src/config.mjs DEFAULT_CONFIG.source.ref vX.Y.Z
# 4. claude-ops/CHANGELOG.md new "## [X.Y.Z] - DATE" section
# (AI-written from the commit range — see --no-ai)
# 5. docs counts/badges ops-sync-docs reconciles every skill/agent
@@ -300,6 +302,8 @@ if [ "$dry_run" -eq 1 ]; then
echo " $PLUGIN_JSON"
echo " $MARKETPLACE_JSON (.plugins[name==$PLUGIN_NAME].version)"
[ -n "$PACKAGE_REL" ] && echo " $REPO_ROOT/$PACKAGE_REL"
+ echo " $PLUGIN_DIR/hermes-plugin/plugin.yaml"
+ echo " $REPO_ROOT/installer/src/config.mjs (DEFAULT_CONFIG.source.ref)"
echo "--- would prepend to $CHANGELOG:"
printf '%s\n' "$changelog_section"
echo "--- would: branch release/v$NEW -> PR to main$([ "$do_merge" -eq 1 ] && echo ' -> wait for CI -> squash-merge')$([ "$do_tag" -eq 1 ] && echo " -> tag v$NEW")"
@@ -332,6 +336,45 @@ if [ -n "$PACKAGE_REL" ] && [ -f "$WT/$PACKAGE_REL" ]; then
jq empty "$WT/$PACKAGE_REL" || { echo "ops-release: produced invalid $PACKAGE_REL" >&2; exit 1; }
fi
+wHERMES="$WT/claude-ops/hermes-plugin/plugin.yaml"
+if [ -f "$wHERMES" ]; then
+ python3 - "$wHERMES" "$NEW" <<'PY'
+from pathlib import Path
+import re, sys
+p, ver = Path(sys.argv[1]), sys.argv[2]
+text = p.read_text()
+new, n = re.subn(r'^version:\s*.*$', f'version: "{ver}"', text, count=1, flags=re.M)
+if n != 1:
+ raise SystemExit(f"ops-release: failed to bump hermes-plugin/plugin.yaml version")
+p.write_text(new)
+PY
+fi
+wINST="$WT/installer/src/config.mjs"
+if [ -f "$wINST" ]; then
+ python3 - "$wINST" "$NEW" <<'PY'
+from pathlib import Path
+import re, sys
+p, ver = Path(sys.argv[1]), sys.argv[2]
+text = p.read_text()
+new, n = re.subn(r'ref:\s*"v[0-9]+\.[0-9]+\.[0-9]+"', f'ref: "v{ver}"', text, count=1)
+if n != 1:
+ raise SystemExit(f"ops-release: failed to bump installer DEFAULT_CONFIG.source.ref")
+p.write_text(new)
+PY
+fi
+wINST_README="$WT/installer/README.md"
+if [ -f "$wINST_README" ]; then
+ python3 - "$wINST_README" "$NEW" <<'PY'
+from pathlib import Path
+import re, sys
+p, ver = Path(sys.argv[1]), sys.argv[2]
+text = p.read_text()
+new, n = re.subn(r'(ref:\s*)v[0-9]+\.[0-9]+\.[0-9]+', rf'\1v{ver}', text, count=1)
+if n == 1:
+ p.write_text(new)
+PY
+fi
+
# 4. prepend CHANGELOG section before the first existing "## [" entry.
# The section is multi-line; pass it via a temp file (awk -v mangles embedded
# newlines → "awk: newline in string"), reading it with getline at the insert.
@@ -344,7 +387,7 @@ awk -v secfile="$sec_file" '
' "$wCL" >"$wCL.tmp" && mv "$wCL.tmp" "$wCL"
rm -f "$sec_file"
-echo "ops-release: bumped plugin.json + marketplace.json$([ -n "$PACKAGE_REL" ] && echo " + $PACKAGE_REL") + CHANGELOG.md"
+echo "ops-release: bumped plugin.json + marketplace.json$([ -n "$PACKAGE_REL" ] && echo " + $PACKAGE_REL") + hermes-plugin/plugin.yaml + installer ref + CHANGELOG.md"
# 5. reconcile documentation counts/badges to the (now-bumped) tree — deterministic.
if [ "$do_docs" -eq 1 ] && [ -x "$WT/claude-ops/bin/ops-sync-docs" ]; then
diff --git a/claude-ops/hermes-plugin/README.md b/claude-ops/hermes-plugin/README.md
index a6321b1b..bb094d58 100644
--- a/claude-ops/hermes-plugin/README.md
+++ b/claude-ops/hermes-plugin/README.md
@@ -1,7 +1,14 @@
# Hermes plugin (ops)
-Native Hermes package for the claude-ops skill tree. Claude Code still loads
-`.claude-plugin/`. Hermes loads this directory.
+Native Hermes package for the claude-ops skill tree. One skill tree, three harnesses:
+
+| Harness | Loads | Skills |
+|---|---|---|
+| Claude Code | `.claude-plugin/` | `../skills/` |
+| Grok | Claude plugin as-is (no `.grok-plugin`) | same `../skills/` |
+| Hermes | this directory | same `../skills/` |
+
+Versions stay in lockstep with `../.claude-plugin/plugin.json`. Do not fork skills here.
## Install
@@ -32,5 +39,5 @@ and `skill_view("ops:ops-inbox")` become available.
| `RUNTIME.md` | Claude Code → Hermes primitive map |
| `../skills/` | Canonical SKILL.md tree (unchanged) |
-Do not fork skills into this folder. Edit `../skills/` so Claude Code and
-Hermes stay on one source.
+Do not fork skills into this folder. Edit `../skills/` so Claude Code, Grok,
+and Hermes stay on one source.
diff --git a/claude-ops/hermes-plugin/RUNTIME.md b/claude-ops/hermes-plugin/RUNTIME.md
index 1f71551d..672e8c0a 100644
--- a/claude-ops/hermes-plugin/RUNTIME.md
+++ b/claude-ops/hermes-plugin/RUNTIME.md
@@ -2,6 +2,8 @@
Use this when a claude-ops skill names a Claude Code primitive that Hermes does not have. Keep the skill's intent. Swap the primitive. Do not copy Claude-only assumptions into Hermes.
+Grok loads the same Claude plugin (`skills/` + `.claude-plugin/`) — there is no separate `.grok-plugin`. Missing Claude-only tools (`AskUserQuestion`, `Workflow`, `TeamCreate`) use the same fallbacks as this table (numbered options, sequential / native subagents). Rule 6 does not change.
+
| Claude Code | Hermes |
|---|---|
| `AskUserQuestion` | Numbered options in chat, then wait. Telegram/gateway: two turns — full draft as its own message, then the Send / Edit / Skip card. Never put the draft only in a clipped preview. Max 4 options per card. |
diff --git a/claude-ops/hermes-plugin/plugin.yaml b/claude-ops/hermes-plugin/plugin.yaml
index fa0e0e1d..2cfb1990 100644
--- a/claude-ops/hermes-plugin/plugin.yaml
+++ b/claude-ops/hermes-plugin/plugin.yaml
@@ -1,4 +1,4 @@
name: ops
-version: "3.4.4"
+version: "3.6.0"
description: "claude-ops on Hermes — slash commands and skills for inbox, deploy, revenue, and the rest of the ops suite. Enable with plugins.enabled: [ops]."
author: Lifecycle Innovations Limited
diff --git a/claude-ops/scripts/dev/stamp-skill-frontmatter.py b/claude-ops/scripts/dev/stamp-skill-frontmatter.py
index ba64ae33..9fe8fde5 100755
--- a/claude-ops/scripts/dev/stamp-skill-frontmatter.py
+++ b/claude-ops/scripts/dev/stamp-skill-frontmatter.py
@@ -47,6 +47,63 @@ TRIGGERS = {
"ops-rules": (
'"ops rules", "plugin rules", "Rule 6", "send gate", or "harness fallbacks"'
),
+ "flow": '"/ops:flow", "dev lifecycle", or "where am I in the pipeline"',
+ "ledger": '"ops ledger", "what did we handle", or "/ops:ledger"',
+ "ops": '"ops command center", "/ops:ops", or "run the business"',
+ "ops-accounts": '"rotate accounts", "switch Claude/Grok/Codex", or "/ops:accounts"',
+ "ops-ar": '"A&R this track", "demo verdict", or "/ops:ops-ar"',
+ "ops-aws-audit": '"audit AWS", "unused AWS resources", or "/ops:ops-aws-audit"',
+ "ops-comms": '"send a message", "whatsapp/email/slack", or "/ops:ops-comms"',
+ "ops-competitors": '"competitor intel", "what did they ship", or "/ops:ops-competitors"',
+ "ops-credentials": '"which keys are set", "missing credentials", or "/ops:ops-credentials"',
+ "ops-daemon": '"daemon health", "background services stuck", or "/ops:ops-daemon"',
+ "ops-dash": '"ops dashboard", "pixel HQ", or "/ops:ops-dash"',
+ "ops-deploy": '"deploy status", "what is in production", or "/ops:ops-deploy"',
+ "ops-deploy-fix": '"deploy auto-fix", "failed deploy", or "/ops:ops-deploy-fix"',
+ "ops-desk": '"desk sweep", "open decisions", or "/ops:ops-desk"',
+ "ops-desktop": '"control the desktop", "click on screen", or "/ops:ops-desktop"',
+ "ops-doctor": '"plugin broken", "ops doctor", or "/ops:ops-doctor"',
+ "ops-ecom": '"shopify", "orders inventory", or "/ops:ops-ecom"',
+ "ops-feature-dev": '"guided feature", "feature-dev", or "/ops:ops-feature-dev"',
+ "ops-fires": '"production fires", "what is on fire", or "/ops:ops-fires"',
+ "ops-fleet": '"fleet dashboard", "CLIProxy sessions", or "/ops:ops-fleet"',
+ "ops-gtm": '"go to market", "GTM plan", or "/ops:ops-gtm"',
+ "ops-home": '"homey", "smart home", or "/ops:ops-home"',
+ "ops-integrate": '"add an API", "integrate SaaS", or "/ops:ops-integrate"',
+ "ops-leadgen": '"leadgen drafts", "cold email approve", or "/ops:ops-leadgen"',
+ "ops-linear": '"linear sprint", "create a ticket", or "/ops:ops-linear"',
+ "ops-mac": '"mac is slow", "macos fix", or "/ops:ops-mac"',
+ "ops-marketing": '"klaviyo", "ads spend", or "/ops:ops-marketing"',
+ "ops-mcp": '"MCP down", "reconnect MCP", or "/ops:ops-mcp"',
+ "ops-merge": '"merge PRs", "salvage branches", or "/ops:ops-merge"',
+ "ops-monitor": '"datadog", "APM alerts", or "/ops:ops-monitor"',
+ "ops-next": '"what should I do next", "priority stack", or "/ops:ops-next"',
+ "ops-orchestrate": '"orchestrate projects", "dispatch agents", or "/ops:ops-orchestrate"',
+ "ops-package": '"ship a parcel", "print a label", or "/ops:ops-package"',
+ "ops-pocket": '"pocket memos", "voice memo pipeline", or "/ops:ops-pocket"',
+ "ops-projects": '"portfolio dashboard", "gsd projects", or "/ops:ops-projects"',
+ "ops-recap": '"recap daemon", "tmux marquee", or "/ops:ops-recap"',
+ "ops-release": '"release the plugin", "publish ops version", or "/ops:ops-release"',
+ "ops-resume": '"resume sessions", "reopen ghostty tabs", or "/ops:ops-resume"',
+ "ops-revenue": '"burn rate", "runway", or "/ops:ops-revenue"',
+ "ops-rotate": '"rotate Claude", "max seats", or "/ops:ops-rotate"',
+ "ops-rotate-setup": '"rotate setup", "enroll Claude seat", or "/ops:ops-rotate-setup"',
+ "ops-secret-sync": '"doppler github secrets", "secret drift", or "/ops:ops-secret-sync"',
+ "ops-settings": '"update credentials", "ops settings", or "/ops:ops-settings"',
+ "ops-ship": '"ship ops plugin", "merge all PRs and release", or "/ops:ops-ship"',
+ "ops-social-planner": '"content calendar", "what is scheduled", or "/ops:ops-social-planner"',
+ "ops-socials": '"tweet", "post to linkedin", or "/ops:ops-socials"',
+ "ops-speedup": '"speed up this mac", "clean disk", or "/ops:ops-speedup"',
+ "ops-statusline": '"statusline theme", "cockpit", or "/ops:ops-statusline"',
+ "ops-triage": '"sentry issues", "triage github", or "/ops:ops-triage"',
+ "ops-unifi": '"unifi", "cameras", or "/ops:ops-unifi"',
+ "ops-update": '"update ops plugin", "upgrade claude-ops", or "/ops:ops-update"',
+ "ops-voice": '"make a call", "facetime", or "/ops:ops-voice"',
+ "ops-whatsapp-biz": '"whatsapp business", "template message", or "/ops:ops-whatsapp-biz"',
+ "ops-yolo": '"yolo mode", "run the business today", or "/ops:ops-yolo"',
+ "people": '"sync contacts", "people database", or "/ops:people"',
+ "tonight": '"tomorrow brief", "evening wrap", or "/ops:tonight"',
+ "uninstall": '"uninstall ops", "remove claude-ops", or "/ops:uninstall"',
}
PREAMBLE = (
diff --git a/claude-ops/skills/flow/SKILL.md b/claude-ops/skills/flow/SKILL.md
index 550c11a2..332f381d 100644
--- a/claude-ops/skills/flow/SKILL.md
+++ b/claude-ops/skills/flow/SKILL.md
@@ -1,6 +1,6 @@
---
name: flow
-description: "This skill should be used when the user asks to \"/ops:flow\", \"run flow\", or \"use flow\". ONE entrypoint for the whole dev lifecycle — ideate, spec, plan, design, build, review, test, ship, deploy, monitor, retro. Routes to the single canonical command per stage (gstack / GSD / claude-ops) and picks project-mode (GSD phase machine) vs ad-hoc-mode (gstack stateless) from repo `.planning/` state. Bare `/flow` prints the lifecycle map + your current \"you are here\" position."
+description: "This skill should be used when the user asks to \"/ops:flow\", \"dev lifecycle\", or \"where am I in the pipeline\". ONE entrypoint for the whole dev lifecycle — ideate, spec, plan, design, build, review, test, ship, deploy, monitor, retro. Routes to the single canonical command per stage (gstack / GSD / claude-ops) and picks project-mode (GSD phase machine) vs ad-hoc-mode (gstack stateless) from repo `.planning/` state. Bare `/flow` prints the lifecycle map + your current \"you are here\" position."
argument-hint: '[stage|intent] [args]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ledger/SKILL.md b/claude-ops/skills/ledger/SKILL.md
index 0ac1f0c9..60d6965f 100644
--- a/claude-ops/skills/ledger/SKILL.md
+++ b/claude-ops/skills/ledger/SKILL.md
@@ -1,6 +1,6 @@
---
name: ledger
-description: "This skill should be used when the user asks to \"/ops:ledger\", \"run ledger\", or \"use ledger\". Inspect the shared Ops Ledger — what's awaiting owner, what was handled autonomously, what claude-ops or Perplexity did in the last 24h. Always the single source of truth between the two systems."
+description: "This skill should be used when the user asks to \"ops ledger\", \"what did we handle\", or \"/ops:ledger\". Inspect the shared Ops Ledger — what's awaiting owner, what was handled autonomously, what claude-ops or Perplexity did in the last 24h. Always the single source of truth between the two systems."
argument-hint: ''
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-accounts/SKILL.md b/claude-ops/skills/ops-accounts/SKILL.md
index 073576c0..645c5b0f 100644
--- a/claude-ops/skills/ops-accounts/SKILL.md
+++ b/claude-ops/skills/ops-accounts/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-accounts
-description: "This skill should be used when the user asks to \"/ops:ops-accounts\", \"run ops-accounts\", or \"use ops-accounts\". Multi-provider AI account manager (Claude, Grok/xAI, OpenAI/Codex, Factory, Cursor). Status, setup, switch, refresh, reauth, util, and the CLIProxyAPI pool. Canonical replacement for /ops:rotate and /ops:rotate-setup (those remain aliases)."
+description: "This skill should be used when the user asks to \"rotate accounts\", \"switch Claude/Grok/Codex\", or \"/ops:accounts\". Multi-provider AI account manager (Claude, Grok/xAI, OpenAI/Codex, Factory, Cursor). Status, setup, switch, refresh, reauth, util, and the CLIProxyAPI pool. Canonical replacement for /ops:rotate and /ops:rotate-setup (those remain aliases)."
argument-hint: '[status|list|setup|switch|refresh|reauth|util|rotate-now|seats|gateway|help] [provider] [args…]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-ar/SKILL.md b/claude-ops/skills/ops-ar/SKILL.md
index ad08648b..82321d9b 100644
--- a/claude-ops/skills/ops-ar/SKILL.md
+++ b/claude-ops/skills/ops-ar/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-ar
-description: "This skill should be used when the user asks to \"/ops:ops-ar\", \"run ops-ar\", or \"use ops-ar\". A&R any record like a dance-pop label owner + master producer. Single track, batch, or full Gmail-inbox demo sweep — runs the audio-ar analysis stack (BPM/key/loudness/structure, CLAP mood/genre/hit-lean, Whisper lyrics, Cyanite/Music.ai pro layer) and delivers verdict cards. Can email the full verdict with listen links on request."
+description: "This skill should be used when the user asks to \"A&R this track\", \"demo verdict\", or \"/ops:ops-ar\". A&R any record like a dance-pop label owner + master producer. Single track, batch, or full Gmail-inbox demo sweep — runs the audio-ar analysis stack (BPM/key/loudness/structure, CLAP mood/genre/hit-lean, Whisper lyrics, Cyanite/Music.ai pro layer) and delivers verdict cards. Can email the full verdict with listen links on request."
argument-hint: '<audio file | URL/Dropbox | "latest" | <file1> <file2> ... | inbox [from <sender>...]>'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-aws-audit/SKILL.md b/claude-ops/skills/ops-aws-audit/SKILL.md
index 98d2ad31..7cde6089 100644
--- a/claude-ops/skills/ops-aws-audit/SKILL.md
+++ b/claude-ops/skills/ops-aws-audit/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-aws-audit
-description: "This skill should be used when the user asks to \"/ops:ops-aws-audit\", \"run ops-aws-audit\", or \"use ops-aws-audit\". Read-only AWS account hygiene audit — security baseline, unused/orphaned resources, and cost optimization across all configured regions. Produces severity-ranked findings (CRITICAL→LOW) plus a machine-readable findings.json. Cleanup actions are always human-gated, never automatic. Use for cost reviews, security sweeps, recurring account hygiene, or \"audit my AWS\"."
+description: "This skill should be used when the user asks to \"audit AWS\", \"unused AWS resources\", or \"/ops:ops-aws-audit\". Read-only AWS account hygiene audit — security baseline, unused/orphaned resources, and cost optimization across all configured regions. Produces severity-ranked findings (CRITICAL→LOW) plus a machine-readable findings.json. Cleanup actions are always human-gated, never automatic. Use for cost reviews, security sweeps, recurring account hygiene, or \"audit my AWS\"."
argument-hint: '[--quiet] [--schedule] [region,region]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-comms/SKILL.md b/claude-ops/skills/ops-comms/SKILL.md
index e26c4d54..8080ea4e 100644
--- a/claude-ops/skills/ops-comms/SKILL.md
+++ b/claude-ops/skills/ops-comms/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-comms
-description: "This skill should be used when the user asks to \"/ops:ops-comms\", \"run ops-comms\", or \"use ops-comms\". Send and read messages across all channels. Routes based on arguments — whatsapp, email, slack, telegram, discord, notion, or natural language like \"send [msg] to [contact]\". WhatsApp via mcp__whatsapp__* (Baileys bridge)."
+description: "This skill should be used when the user asks to \"send a message\", \"whatsapp/email/slack\", or \"/ops:ops-comms\". Send and read messages across all channels. Routes based on arguments — whatsapp, email, slack, telegram, discord, notion, or natural language like \"send [msg] to [contact]\". WhatsApp via mcp__whatsapp__* (Baileys bridge)."
argument-hint: '[channel] | send [message] to [contact] | read [channel] | notion [search query]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-competitors/SKILL.md b/claude-ops/skills/ops-competitors/SKILL.md
index 801133c3..c808f4fa 100644
--- a/claude-ops/skills/ops-competitors/SKILL.md
+++ b/claude-ops/skills/ops-competitors/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-competitors
-description: "This skill should be used when the user asks to \"/ops:ops-competitors\", \"run ops-competitors\", or \"use ops-competitors\". Competitor-intel dashboard and management UI. Tracks brand signals, page-diff alerts, pricing changes, App Store moves, and weekly synthesis reports. Powered by the competitor-intel cron pipeline."
+description: "This skill should be used when the user asks to \"competitor intel\", \"what did they ship\", or \"/ops:ops-competitors\". Competitor-intel dashboard and management UI. Tracks brand signals, page-diff alerts, pricing changes, App Store moves, and weekly synthesis reports. Powered by the competitor-intel cron pipeline."
argument-hint: '[brand-name|refresh [brand]|add-url <brand> <competitor> <kind> <url>|alerts|help]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-credentials/SKILL.md b/claude-ops/skills/ops-credentials/SKILL.md
index ddfdcee4..7d12d035 100644
--- a/claude-ops/skills/ops-credentials/SKILL.md
+++ b/claude-ops/skills/ops-credentials/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-credentials
-description: "This skill should be used when the user asks to \"/ops:ops-credentials\", \"run ops-credentials\", or \"use ops-credentials\". Audit which integration credentials are configured. Scans shell env, ops preferences.json, Doppler, macOS Keychain, and Dashlane to report a configured-vs-missing table per service. Never displays raw values — always masks as first6•••last4. Use when you want to see which integrations have keys set up and which still need /ops:setup."
+description: "This skill should be used when the user asks to \"which keys are set\", \"missing credentials\", or \"/ops:ops-credentials\". Audit which integration credentials are configured. Scans shell env, ops preferences.json, Doppler, macOS Keychain, and Dashlane to report a configured-vs-missing table per service. Never displays raw values — always masks as first6•••last4. Use when you want to see which integrations have keys set up and which still need /ops:setup."
argument-hint: '[--service <name>] [--json]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-daemon/SKILL.md b/claude-ops/skills/ops-daemon/SKILL.md
index 58cf70a1..a5be4903 100644
--- a/claude-ops/skills/ops-daemon/SKILL.md
+++ b/claude-ops/skills/ops-daemon/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-daemon
-description: "This skill should be used when the user asks to \"/ops:ops-daemon\", \"run ops-daemon\", or \"use ops-daemon\". Check claude-ops background daemon end-to-end and auto-fix common issues. Detects stale plist paths after plugin upgrades, missing service commands, dead processes, corrupt health files, and bash version mismatches."
+description: "This skill should be used when the user asks to \"daemon health\", \"background services stuck\", or \"/ops:ops-daemon\". Check claude-ops background daemon end-to-end and auto-fix common issues. Detects stale plist paths after plugin upgrades, missing service commands, dead processes, corrupt health files, and bash version mismatches."
argument-hint: '[check|fix|restart|status|uninstall]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-dash/SKILL.md b/claude-ops/skills/ops-dash/SKILL.md
index 57fe7d4b..5daa200d 100644
--- a/claude-ops/skills/ops-dash/SKILL.md
+++ b/claude-ops/skills/ops-dash/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-dash
-description: "This skill should be used when the user asks to \"/ops:ops-dash\", \"run ops-dash\", or \"use ops-dash\". Interactive pixel-art command center dashboard. Visual business HQ with instant hotkey navigation to all ops commands, live status indicators, fire alerts, C-suite reports, settings, sharing, and FAQ."
+description: "This skill should be used when the user asks to \"ops dashboard\", \"pixel HQ\", or \"/ops:ops-dash\". Interactive pixel-art command center dashboard. Visual business HQ with instant hotkey navigation to all ops commands, live status indicators, fire alerts, C-suite reports, settings, sharing, and FAQ."
argument-hint: '[back|settings|share|faq]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-deploy-fix/SKILL.md b/claude-ops/skills/ops-deploy-fix/SKILL.md
index 9ad4fc62..78e7119e 100644
--- a/claude-ops/skills/ops-deploy-fix/SKILL.md
+++ b/claude-ops/skills/ops-deploy-fix/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-deploy-fix
-description: "This skill should be used when the user asks to \"/ops:ops-deploy-fix\", \"run ops-deploy-fix\", or \"use ops-deploy-fix\". Inspect and control the deploy/build auto-fix subsystem. Use for `/ops:deploy-fix status` (last monitor runs, fixer dispatches, locks, hourly budget), `/ops:deploy-fix tail` (follow latest fixer log), `/ops:deploy-fix configure` (re-run the wizard), and `/ops:deploy-fix test` (synthetic dry-run through the pipeline). Trigger when the user mentions deploy auto-fix, post-merge monitor, build fixer, fix budget, fix-agent log, or asks why a deploy didn't get auto-fixed."
+description: "This skill should be used when the user asks to \"deploy auto-fix\", \"failed deploy\", or \"/ops:ops-deploy-fix\". Inspect and control the deploy/build auto-fix subsystem. Use for `/ops:deploy-fix status` (last monitor runs, fixer dispatches, locks, hourly budget), `/ops:deploy-fix tail` (follow latest fixer log), `/ops:deploy-fix configure` (re-run the wizard), and `/ops:deploy-fix test` (synthetic dry-run through the pipeline). Trigger when the user mentions deploy auto-fix, post-merge monitor, build fixer, fix budget, fix-agent log, or asks why a deploy didn't get auto-fixed."
argument-hint: '[status|tail|configure|test]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-deploy/SKILL.md b/claude-ops/skills/ops-deploy/SKILL.md
index f384b99d..314ea518 100644
--- a/claude-ops/skills/ops-deploy/SKILL.md
+++ b/claude-ops/skills/ops-deploy/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-deploy
-description: "This skill should be used when the user asks to \"/ops:ops-deploy\", \"run ops-deploy\", or \"use ops-deploy\". Deploy status across all projects. Shows ECS service versions, Vercel deployments, recent deploys, pending deploys, and CI/CD pipeline state."
+description: "This skill should be used when the user asks to \"deploy status\", \"what is in production\", or \"/ops:ops-deploy\". Deploy status across all projects. Shows ECS service versions, Vercel deployments, recent deploys, pending deploys, and CI/CD pipeline state."
argument-hint: '[project-alias|ecs|vercel|all]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-desk/SKILL.md b/claude-ops/skills/ops-desk/SKILL.md
index 33218a17..b5740ec6 100644
--- a/claude-ops/skills/ops-desk/SKILL.md
+++ b/claude-ops/skills/ops-desk/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-desk
-description: "This skill should be used when the user asks to \"/ops:ops-desk\", \"run ops-desk\", or \"use ops-desk\". Desk sweep — turn the owner's backlog of open decisions, staged drafts, payments, sign-offs and chases into a ranked, ready-to-approve action queue. Fans out READ-ONLY context agents (one per item, batched) via the Workflow tool, each returning a structured action package (status + recommendation + full draft in the owner's voice), then walks the queue rapid-fire in the main session under the outbound-approval gate. Complements /ops:ops-inbox (comms triage) — ops-desk handles everything that is NOT a fresh inbound message; decisions, blocked issues, owner-action items."
+description: "This skill should be used when the user asks to \"desk sweep\", \"open decisions\", or \"/ops:ops-desk\". Desk sweep — turn the owner's backlog of open decisions, staged drafts, payments, sign-offs and chases into a ranked, ready-to-approve action queue. Fans out READ-ONLY context agents (one per item, batched) via the Workflow tool, each returning a structured action package (status + recommendation + full draft in the owner's voice), then walks the queue rapid-fire in the main session under the outbound-approval gate. Complements /ops:ops-inbox (comms triage) — ops-desk handles everything that is NOT a fresh inbound message; decisions, blocked issues, owner-action items."
argument-hint: '[scope: all|<board/company>|explicit item list]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-desktop/SKILL.md b/claude-ops/skills/ops-desktop/SKILL.md
index 5c60a0fe..88f33775 100644
--- a/claude-ops/skills/ops-desktop/SKILL.md
+++ b/claude-ops/skills/ops-desktop/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-desktop
-description: "This skill should be used when the user asks to \"/ops:ops-desktop\", \"run ops-desktop\", or \"use ops-desktop\". Autonomous desktop + browser control via the desktop-act MCP companion. Acquires an isolated noVNC desktop session, takes screenshots, clicks, types, scrolls, and runs the optional autonomous act() loop. First run auto-bootstraps the desktop-act server into a per-user cache."
+description: "This skill should be used when the user asks to \"control the desktop\", \"click on screen\", or \"/ops:ops-desktop\". Autonomous desktop + browser control via the desktop-act MCP companion. Acquires an isolated noVNC desktop session, takes screenshots, clicks, types, scrolls, and runs the optional autonomous act() loop. First run auto-bootstraps the desktop-act server into a per-user cache."
argument-hint: "[goal text | 'status' | 'list' | 'release [session_id]']"
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-doctor/SKILL.md b/claude-ops/skills/ops-doctor/SKILL.md
index 96475209..dd6faa54 100644
--- a/claude-ops/skills/ops-doctor/SKILL.md
+++ b/claude-ops/skills/ops-doctor/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-doctor
-description: "This skill should be used when the user asks to \"/ops:ops-doctor\", \"run ops-doctor\", or \"use ops-doctor\". Health check and auto-repair for the ops plugin. Diagnoses manifest errors, broken permissions, invalid configs, stale caches, and missing files — then spawns an agent to fix everything automatically."
+description: "This skill should be used when the user asks to \"plugin broken\", \"ops doctor\", or \"/ops:ops-doctor\". Health check and auto-repair for the ops plugin. Diagnoses manifest errors, broken permissions, invalid configs, stale caches, and missing files — then spawns an agent to fix everything automatically."
argument-hint: '[--check-only|--verbose]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-ecom/SKILL.md b/claude-ops/skills/ops-ecom/SKILL.md
index f016cadd..b3d5ef59 100644
--- a/claude-ops/skills/ops-ecom/SKILL.md
+++ b/claude-ops/skills/ops-ecom/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-ecom
-description: "This skill should be used when the user asks to \"/ops:ops-ecom\", \"run ops-ecom\", or \"use ops-ecom\". Shopify store command center. Orders, inventory, fulfillment, analytics, store health, sales channels, agentic storefronts, and Shop readiness. Works with any Shopify store via Admin API."
+description: "This skill should be used when the user asks to \"shopify\", \"orders inventory\", or \"/ops:ops-ecom\". Shopify store command center. Orders, inventory, fulfillment, analytics, store health, sales channels, agentic storefronts, and Shop readiness. Works with any Shopify store via Admin API."
argument-hint: '[orders|inventory|fulfillment|health|products|customers|analytics|channels|agentic|shop|setup]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-feature-dev/SKILL.md b/claude-ops/skills/ops-feature-dev/SKILL.md
index 62f7ab1a..c7cacb3a 100644
--- a/claude-ops/skills/ops-feature-dev/SKILL.md
+++ b/claude-ops/skills/ops-feature-dev/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-feature-dev
-description: "This skill should be used when the user asks to \"/ops:ops-feature-dev\", \"run ops-feature-dev\", or \"use ops-feature-dev\". Guided feature development — delegates to the feature-dev plugin's 7-phase workflow (explore, architect, implement, review). Use before ad-hoc builds or as pre-work before gsd-execute-phase."
+description: "This skill should be used when the user asks to \"guided feature\", \"feature-dev\", or \"/ops:ops-feature-dev\". Guided feature development — delegates to the feature-dev plugin's 7-phase workflow (explore, architect, implement, review). Use before ad-hoc builds or as pre-work before gsd-execute-phase."
argument-hint: '[feature description]'
allowed-tools:
- Skill
diff --git a/claude-ops/skills/ops-fires/SKILL.md b/claude-ops/skills/ops-fires/SKILL.md
index 60880d7f..fc08a020 100644
--- a/claude-ops/skills/ops-fires/SKILL.md
+++ b/claude-ops/skills/ops-fires/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-fires
-description: "This skill should be used when the user asks to \"/ops:ops-fires\", \"run ops-fires\", or \"use ops-fires\". Production incidents dashboard. Reads ECS health, Sentry errors, CI failures. Offers to dispatch fix agents for active fires."
+description: "This skill should be used when the user asks to \"production fires\", \"what is on fire\", or \"/ops:ops-fires\". Production incidents dashboard. Reads ECS health, Sentry errors, CI failures. Offers to dispatch fix agents for active fires."
argument-hint: '[project-alias|all]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-fleet/SKILL.md b/claude-ops/skills/ops-fleet/SKILL.md
index 7c85a69e..0f905851 100644
--- a/claude-ops/skills/ops-fleet/SKILL.md
+++ b/claude-ops/skills/ops-fleet/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-fleet
-description: "This skill should be used when the user asks to \"/ops:ops-fleet\", \"run ops-fleet\", or \"use ops-fleet\". Read-only Claude + CLIProxyAPI fleet dashboard. Shows sessions, gateway, providers, models, pooled accounts, routing, and traffic."
+description: "This skill should be used when the user asks to \"fleet dashboard\", \"CLIProxy sessions\", or \"/ops:ops-fleet\". Read-only Claude + CLIProxyAPI fleet dashboard. Shows sessions, gateway, providers, models, pooled accounts, routing, and traffic."
argument-hint: '[--once] [--tui] [--all] [--models] [--no-pool] [--no-color]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-gtm/SKILL.md b/claude-ops/skills/ops-gtm/SKILL.md
index f8533f6d..45c62371 100644
--- a/claude-ops/skills/ops-gtm/SKILL.md
+++ b/claude-ops/skills/ops-gtm/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-gtm
-description: "This skill should be used when the user asks to \"/ops:ops-gtm\", \"run ops-gtm\", or \"use ops-gtm\". Go-to-market strategy planner. Generates a complete GTM plan across paid, unpaid, marketing, sales, and AI-automation channels for any project — and hands executable campaigns off to /marketing."
+description: "This skill should be used when the user asks to \"go to market\", \"GTM plan\", or \"/ops:ops-gtm\". Go-to-market strategy planner. Generates a complete GTM plan across paid, unpaid, marketing, sales, and AI-automation channels for any project — and hands executable campaigns off to /marketing."
argument-hint: '[plan|paid|unpaid|sales|automation|launch|brief|setup]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-home/SKILL.md b/claude-ops/skills/ops-home/SKILL.md
index a5847424..a41993e4 100644
--- a/claude-ops/skills/ops-home/SKILL.md
+++ b/claude-ops/skills/ops-home/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-home
-description: "This skill should be used when the user asks to \"/ops:ops-home\", \"run ops-home\", or \"use ops-home\". Smart home command center via Homey Pro. Devices, flows, scenes, energy, climate, presence, alarms. Works via Homey local API (preferred) + Athom cloud API fallback. Configure once via /ops:setup."
+description: "This skill should be used when the user asks to \"homey\", \"smart home\", or \"/ops:ops-home\". Smart home command center via Homey Pro. Devices, flows, scenes, energy, climate, presence, alarms. Works via Homey local API (preferred) + Athom cloud API fallback. Configure once via /ops:setup."
argument-hint: '[status|devices|flow|scene|energy|climate|presence|alarm|setup]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-inbox/SKILL.md b/claude-ops/skills/ops-inbox/SKILL.md
index 9347fc46..1a2a9f8d 100644
--- a/claude-ops/skills/ops-inbox/SKILL.md
+++ b/claude-ops/skills/ops-inbox/SKILL.md
@@ -131,91 +131,17 @@ classification was fine. The account was wrong, and nothing in the run could tel
## Runtime Context
-**Standing default posture — read this first, every run.** Before the offline scan-engine, before any per-channel MCP call, the default mode of this skill is: spin up one agent per available/configured channel (WhatsApp, Email, Slack, Telegram, iMessage, Notion, Discord — whichever are configured; see "Channel availability + fallback" below) via the `Workflow` tool (Agent Teams as the fallback), running in parallel. This is the standing default for the whole skill — you do not wait for triage to discover volume before fanning out; fanning out IS the first move. Each per-channel agent: deep-reads every conversation in its channel, clears the FULL-THREAD AWARENESS GATE, and — for any NEEDS_REPLY candidate — pulls full cross-channel context on that person/topic/thread (gmail search, whatsapp search, the ops-memories contact profile, etc. — per "FULL CONTEXT — NEVER ASSUME" / "FULL-CONTEXT RECALL + CROSS-CHANNEL DEDUP" below) before drafting a reply where one is genuinely needed. It reports back structured recommendations (classification + draft + reasoning, grounded in that cross-channel research) to the orchestrating session. **"READ-ONLY" here means one thing only — never send, archive, mark-read, or mutate anything — it does NOT mean "stay inside your one assigned channel"; agents are granted the cross-channel read/search tools they need for context-gathering.** Every send still goes through the main session's Rule-6 one-draft → one-approval → one-send gate, unchanged (see "Standing behavior: RUN WIDE" and "Workflow fan-out" below for the mechanics and hard constraints). The offline `bin/ops-inbox-scan` step below is a fast pre-filter that FEEDS this fan-out — not a replacement for it, so the per-channel agents aren't blindly scanning everything from scratch. The only exception: skip the fan-out in the genuinely trivial case (script covered everything, ~1-3 candidates left) — that stays the exception, not the default framing.
+Default: fan out one read-only scanner per configured channel after the offline scan. Skip fan-out only in the trivial case (~1–3 candidates). Full freshness / Mac fallback / version-heal / watcher: `references/runtime.md`.
-Before executing, load available context:
+Every run, in order:
-0. **Auto-sync WhatsApp in the background (DEFAULT — every invocation)** — the FIRST thing this skill does, before any scan or menu, is guarantee the store is fresh, then fire a recent-conversation history backfill **and** a contacts-link in the background, non-blocking.
+1. Resolve the WhatsApp account (`ops-wa-accounts` — never hardcode a port).
+2. Freshness: `~/bin/wa-inbox-fresh.sh` (blocking, bounded). Then `bin/ops-inbox-scan`.
+3. `bin/ops-inbox-archive-set` report-only. Present KEEP vs ARCHIVE; `--apply` only after explicit OK.
+4. Deep-read KEEP / NEEDS_REPLY. Fan out if volume (`references/fan-out.md`).
+5. Stage drafts one at a time (Rule 6). Archive after a verified send.
- **0a. Freshness gate (run FIRST, blocking, bounded).** Before classifying anything, run `~/bin/wa-inbox-fresh.sh` (shipped by `scripts/install-whatsapp-bridge-linux.sh`). It probes the bridge with a real **curl connection probe** (`curl -s -m4 http://127.0.0.1:8080/`), forces a backfill, triggers voice-note transcription, and waits (bounded ~32s) for the newest message to settle, then prints a FRESHNESS report (`newest message = … (N min old)`). It **only restarts the bridge if the curl probe genuinely fails twice** — do NOT gate liveness on `ss | grep :8080`, because `ss` renders port 8080 as the service name `webcache`, so the grep never matches and you'd needlessly bounce a healthy bridge. Exit 2 means the bridge is down and unrecoverable → the store is STALE, do not trust last-sender classification.
-
-### Mac WhatsApp.app fallback (bridge-miss recovery)
-
-The whatsmeow bridge can **silently miss inbound messages** when its history/app-state sync lags — most often on `@lid` chats (e.g. 2026-06-11 it missed a reply from a contact that the Mac WhatsApp.app had). The Mac app keeps an **unencrypted** local Core Data store at `~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite`, readable over Tailscale SSH, so it is a reliable ground-truth backstop.
-
-- **When it runs AUTOMATICALLY:** `wa-inbox-fresh.sh` now invokes the Mac cross-check itself whenever the bridge store looks stale — on exit 2 (store unreadable) or when the newest message is >2h old, it prints a `MAC GROUND TRUTH` block (latest 10 messages from the Mac app store) inline in the freshness report. No orchestration needed.
-- **When to use manually:** a contact's _known_ reply is missing from the bridge (common on `@lid` chats) — cross-check before classifying that thread as "no reply".
-- **Command:** `bin/wa-mac-latest.sh --contact <name|number> [N]` (also `--recent [N]`, `--since "YYYY-MM-DD HH:MM"`, add `--json` for machine-readable output). It reads `~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite` over SSH. Schema: `ZWAMESSAGE` (`ZTEXT`, `ZISFROMME`, `ZMESSAGEDATE` = seconds since 2001-01-01) joined to `ZWACHATSESSION` (`ZPARTNERNAME`, `ZCONTACTJID`).
-- **Transport chain (`bin/wa-mac-transport.sh`, shared by all wa-mac-\* scripts):** ① Tailscale/direct SSH (`WA_MAC_SSH=user@host`) → ② Cloudflare-tunnel SSH (`WA_MAC_CF_HOST=ssh-mac.example.com`, via `cloudflared access ssh` ProxyCommand) when Tailscale is down. One-time wiring: `scripts/setup-wa-mac-cf-tunnel.sh` (installs cloudflared locally + the Mac LaunchDaemon from a remotely-managed tunnel token, then verifies end-to-end). Both env vars live in the shell profile, never in the repo.
-- **READ-ONLY ground truth for reads.** The reader never writes and never sends. Sends still go through the whatsmeow bridge (`mcp__whatsapp__send_message`) under the Rule-6 outbound-approval gate — the Mac store is only consulted to confirm what actually arrived. The ONLY write-capable Mac surface is `wa-mac-archive.sh` (archive-only, see Tier 4 of the archive ladder).
-- **Why no Linux-native alternative:** there is no official WhatsApp Linux desktop app; the third-party Flatpak clients (`whatsapp-for-linux`, ZapZap) are Electron WhatsApp-Web wrappers that need a GUI, consume a linked-device slot, and store data in encrypted IndexedDB (not a queryable SQLite) — so the Mac `ChatStorage.sqlite` is the preferred backstop.
-
- **The FULL-THREAD AWARENESS GATE (in "Processing each channel") depends on this step having run first.** That gate's "read both directions incl. `[voice]`" only works once `wa-inbox-fresh.sh` (freshness + backfill) and the voice-note transcription pass (step 0c) have completed and the store has settled — otherwise outbound rows and `[voice]` bodies are still missing and the gate reads an incomplete thread.
-
- **0b. Background backfill + contacts-link** (idempotent, safe every time). The backfill pulls recent messages for the 50 most-active chats; the link populates `messages.db.contacts` from the whatsmeow session store so both `<pn>@s.whatsapp.net` and `<lid>@lid` chat JIDs resolve to names (without it the `contacts` table is empty and LID-format chats show raw phone numbers):
-
- ```bash
- BR="${WHATSAPP_BRIDGE_DIR:-$HOME/.local/share/whatsapp-mcp/whatsapp-bridge}"
- WA_PORT=$("$CLAUDE_PLUGIN_ROOT/bin/ops-wa-accounts" --port) || exit 3 # never assume 8080
- WA_API="http://127.0.0.1:${WA_PORT}"
- if curl -s -o /dev/null -m 4 "$WA_API/" 2>/dev/null; then
- curl -fsS -m 10 -X POST "$WA_API/api/backfill" >/dev/null 2>&1 & # recent-conversation backfill
- [ -f "$BR/link_contacts.py" ] && python3 "$BR/link_contacts.py" >/dev/null 2>&1 & # contacts link (phone + LID aliases)
- fi
- ```
-
- Kick this off, then continue with the steps below while it runs — give the link ~2s before name-resolving chats. `link_contacts.py` resolves names via `whatsmeow_contacts` + `whatsmeow_lid_map` (name preference: full_name → first_name → push_name → business_name). It ships via `scripts/install-whatsapp-bridge-linux.sh` into the bridge dir; recreate it from `whatsmeow_contacts`/`whatsmeow_lid_map` if absent.
-
- **0c. Voice notes are first-class.** Incoming voice notes (`media_type='audio'`, empty `content`) are auto-transcribed into `content` as `[voice] <text>` by the `whatsapp-transcribe.timer` (systemd-user, every 10 min, OpenAI `whisper-1`) — and `wa-inbox-fresh.sh` triggers a transcribe pass on every scan. So a voice note shows up in NEEDS_REPLY / thread scans exactly like a text message; treat a `[voice] …` body as the sender's words. Transcription is idempotent (only ever fills empty audio rows, never clobbers real text) and capped per run, so it never re-bills or stacks.
-
- **0c-bis. ALL media is now first-class, not just voice.** Beyond voice→`[voice]` (transcribe above), incoming **video / image / document** media (empty `content`) is auto-enriched into `content` as `[video] …` / `[image] …` / `[document] …` by `transcriber/enrich_media.py` (vision for stills/video frames + Whisper for any audio track) on the `whatsapp-enrich.timer` (systemd-user, every 10 min) — and `wa-inbox-fresh.sh` queues an enrich pass on every scan. So an image, clip, or PDF shows up in NEEDS_REPLY / thread scans with a real, readable body, exactly like text. Enrichment is idempotent (only fills empty media rows) and capped per run. The bridge also **self-heals media that 403/404/410s** (stale `directPath`, common for larger media) by asking the sender's phone to re-upload via `SendMediaRetryReceipt` (`apply-patches.py` Fix M), so large media never silently drops.
-
- **0d. The scan engine self-refreshes + self-reconciles on EVERY run — this is automatic, you do not orchestrate it.** `bin/ops-inbox-scan` (the primary classifier, step "Scan engine" below) now does the refresh/pull itself, BLOCKING and bounded, before it classifies — so the data is converged by the time you read its JSON, regardless of whether the background `ops-inbox-autosync` hook has finished. On each invocation the scan:
- - **Refreshes (frontfill/backfill):** if this account's bridge is reachable (the port it resolved, not a fixed `:8080`), it fires `POST /api/backfill` + `link_contacts.py`, then **waits (bounded ~18s) for the newest stored message timestamp to stop advancing** so the classify pass reads a settled store. This is the blocking guarantee the background hook alone does NOT give. Skip with `OIS_NO_REFRESH=1` (set automatically on repeat calls in one session to avoid re-waiting).
- - **Reconciles outbound sends (owner directive 2026-06-05 "include all things I sent to all people"):** it reads the bridge's outbound-send journal (`journalctl --user -u whatsapp-bridge.service`, or the bridge log file on non-systemd hosts) into a `{recipient_jid → latest_send_epoch}` map, and **demotes any NEEDS_REPLY thread whose last inbound is older than a send to any of that person's JIDs** (`reconciled` flag set, moved to WAITING). This catches replies that went out via `/api/send` or a phone send that has not yet landed in `messages.db` — the single most common false-NEEDS_REPLY. Only epoch-stamped send lines drive demotion (a send that genuinely predates the inbound never demotes).
-
- Net effect: running `/ops:ops-inbox` autonomously pulls the latest state AND folds in everything the user already sent, with **zero extra orchestration on your part** — just read the scan JSON. A `reconciled` field on a WAITING item means "already answered, reply not yet in the store"; never re-draft it. You still clear the FULL-THREAD AWARENESS GATE on whatever genuine NEEDS_REPLY candidates remain.
-
-1. **Self-heal plugin version pin** — if any `${CLAUDE_PLUGIN_DATA_DIR}` file or `~/.claude/plugins/installed_plugins.json` references a `cache/ops-marketplace/ops/X.Y.Z/` path that no longer exists on disk, downstream hooks (`stop-all.sh`, `ops-post-session-cleanup`) emit `Plugin directory does not exist`. Resolve before scanning:
-
- ```bash
- INSTALLED="$HOME/.claude/plugins/installed_plugins.json"
- CACHE_DIR="$HOME/.claude/plugins/cache/ops-marketplace/ops"
- PINNED=$(python3 -c "import json; d=json.load(open('$INSTALLED')); print(d.get('plugins',{}).get('ops@ops-marketplace',[{}])[0].get('version',''))")
- LATEST=$(ls "$CACHE_DIR" 2>/dev/null | sort -V | tail -1)
- if [ -n "$PINNED" ] && [ -n "$LATEST" ] && [ "$PINNED" != "$LATEST" ] && [ ! -d "$CACHE_DIR/$PINNED" ]; then
- python3 -c "
- import json
- p='$INSTALLED'; d=json.load(open(p))
- for e in d.get('plugins',{}).get('ops@ops-marketplace',[]):
- if e.get('version')=='$PINNED':
- e['version']='$LATEST'
- e['installPath']='$CACHE_DIR/$LATEST'
- json.dump(d, open(p,'w'), indent=2)
- "
- bash "$HOME/.claude/scripts/hooks/ops-plugin-version-heal.sh" # rewrites daemon-services.json + mcp-proxy/servers.json
- fi
- ```
-
- The existing `ops-plugin-version-heal.sh` only rewrites _downstream_ targets from `installed_plugins.json` (the source of truth). When the source itself is stale, the heal hook is a no-op — patch it first, then re-run the hook.
-
-2. **Preferences**: Read `${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json`
- - `default_channels` — which channels to scan by default
- - `secrets_manager` / `doppler` — how to resolve channel credentials if not in env
-
-3. **Daemon health**: Read `${CLAUDE_PLUGIN_DATA_DIR}/daemon-health.json`
- - Check `whatsapp-bridge` status — verify `com.${USER}.whatsapp-bridge` is running (`lsof -i :8080` or `launchctl print "gui/$(id -u)/com.${USER}.whatsapp-bridge"`)
- - Also verify the **ops mcp-proxy** is up on `:8090` (`lsof -i :8090 | grep LISTEN`) — Claude's MCP client connects through the proxy SSE endpoint, not directly to the bridge. If :8080 is up but :8090 is down, `mcp__whatsapp__*` tools will never load.
- - If either layer is down, surface the issue before WhatsApp operations
- - **Do not declare WhatsApp MCP unavailable purely because tools haven't loaded yet** — when both ports are LISTEN, retry `ToolSearch select:mcp__whatsapp__list_chats,...` up to 3× at 5s intervals to let the SSE handshake complete
-
-4. **Ops memories**: Check `${CLAUDE_PLUGIN_DATA_DIR}/memories/` before drafting any reply:
- - `contact_*.md` — load profile for the contact you're about to reply to
- - `preferences.md` — apply user's communication style and language preferences
- - `topics_active.md` — check for active threads or deadlines related to this contact
- - `donts.md` — never violate these restrictions in drafts
-
-5. **Launch the live inbox watcher (background job, every session)** — right after the steps above, start `bin/ops-inbox-live-watch.sh` via Bash with `run_in_background: true`. It polls the Gmail inbox (via `gog`) every ~4 minutes and exits — with a `NEW INBOX MAIL: <from> | <subject> | <date> | id=<id>` summary line — the instant a genuinely new inbound message lands; it also exits (with a `watcher expired` line) after ~6h if nothing new arrives. **The job's exit IS the new-mail ping** — treat it exactly like a direct orchestrator notification: when it fires, re-scan the affected channel and relaunch the watcher (same command) so live coverage never lapses. Pure bash + python3 + `gog`, no systemd/launchd dependency, cross-platform (Linux + macOS).
+Channel processing, FULL-THREAD AWARENESS GATE, and per-channel recipes: `references/details.md`.
## Standing behavior: RUN WIDE — parallel subagents / agent-teams / workflow by DEFAULT
@@ -282,7 +208,7 @@ deterministically, instead of re-deciding a few hundred rows by eye every run:
- It enforces the todo/action-label HARD GUARDRAIL in code, so a labelled mail
cannot be swept even when it looks exactly like a newsletter.
-**ONE-SHOT TRIAGE (Sam 2026-07-21):** `bin/ops-inbox-zero` attempts the inbox-zero
+**ONE-SHOT TRIAGE:** `bin/ops-inbox-zero` attempts the inbox-zero
pipeline (scan → Paperclip SSOT → Slack direct API → dual-JID deep-read → proposed WA/email
archive actions → KEEP report) in one shell call. Gmail, Slack, or Paperclip can be skipped
when authentication or local services are unavailable; the report surfaces each status.
@@ -315,30 +241,14 @@ classification (and _better_ — it merges each person's lid↔phone chats into
conversation and resolves real names from `contacts`) for free. Reserve agent fan-out for
genuine reasoning, not for reading a database.
-`ops-inbox-scan` output (always valid JSON, even on partial failure):
-
-```jsonc
-{
- "generated_at": "…", "window_days": 7,
- "whatsapp": {
- "needs_reply": [ { "who", "jid", "alt_jids", "last_message_at", "age_min",
- "last_from_me", "preview":[{from_me,text}] } ],
- "waiting": [ … ], // you sent last — no action
- "groups": [ … ], // group chats w/ recent activity + preview — YOU scan these
- // for @mentions / a direct question before any NEEDS_REPLY
- "fyi": [ … ] // newsletters / broadcasts
- },
- "email": { "reachable": true, "needs_reply":[…], "waiting":[…], "fyi":[…] },
- "counts": { … }, "notes": [ … ]
-}
-```
+`ops-inbox-scan` JSON always includes `whatsapp` / `email` buckets (`needs_reply`, `waiting`, `groups`, `fyi`) plus `whatsapp_account` and `counts`. Partial failure still emits valid JSON.
**What the script does NOT do — and what you do next, in the MAIN session (no subagents):**
1. **Slack** — one `mcp__slack__conversations_unreads {include_messages:true}` call. One
round-trip; a subagent is pure overhead. Skip entirely if prefs show 0 workspaces.
2. **Telegram** — one `mcp__plugin_ops_telegram__list_dialogs` call (skip the
- `@SamCloudDevBot` / Pocket ops bot dialog — that's automation). Skip if unconfigured.
+ Pocket ops bot dialog — that's automation). Skip if unconfigured.
3. **FULL-THREAD AWARENESS GATE on the few NEEDS_REPLY candidates** — the script's WhatsApp
buckets are merged-thread, last-direction-correct _first passes_; its `groups` entries
are explicitly un-classified. Its email `needs_reply` is an envelope first pass. Before
@@ -348,214 +258,11 @@ genuine reasoning, not for reading a database.
You are now doing deep reads on ~3 threads, not scanning hundreds — that is the whole
point of the split: cheap script-side triage, expensive reasoning only where it pays.
-**When to use the Workflow fan-out below — DEFAULT for real per-thread volume:** the offline
-`ops-inbox-scan` is the cheap first-pass triage and always runs first, but the per-thread
-deep-read/draft work (clearing the FULL-THREAD AWARENESS GATE + cross-channel dedup on every
-candidate) is **reasoning work, and reasoning work fans out in parallel by default.** The
-moment there is real volume — more than a handful of NEEDS_REPLY candidates across channels,
-a Slack/Telegram/iMessage backlog of human threads, or any channel the script can't reach —
-**default to the `Workflow` fan-out**: launch one read-only drafter/scanner agent per
-channel (or per thread-chunk within a channel), run them concurrently, and synthesize. This
-is faster and more token-efficient than serially deep-reading dozens of threads in the main
-session, and it collapses wall-clock to the slowest single channel.
-
-**The only time you skip the fan-out** is the genuinely trivial case: the script already
-covered everything and only ~1–3 threads need a deep read (e.g. WA + email with a couple of
-candidates and a glance at Slack/Telegram). Then the script + a couple of inline MCP calls is
-enough and a fan-out would be pure overhead. For anything with real per-thread volume, the
-fan-out is the default — not a fallback.
-
-**Either way, the fan-out NEVER sends, archives, or mutates.** Scanner/drafter agents are
-strictly read-only and return classifications + draft text; **every outbound send stays in
-the main session under the Rule-6 one-draft → one-approval → one-send gate.** Defaulting to
-parallel fan-out changes only HOW threads are read and drafted, never the outbound-approval
-safety.
-
----
-
-### Workflow fan-out (DEFAULT for real per-thread volume — per the note above)
-
-When there is real per-thread volume to deep-read and draft, use the **`Workflow` tool** as
-the **default** path: fan out one **read-only** scanner/drafter agent per channel (or per
-thread-chunk within a high-volume channel), then synthesize. Channels and chunks are
-processed concurrently and wall-clock collapses to the slowest single unit. **Do not fan out
-for channels the offline script already fully triaged down to ~1–3 trivial candidates** —
-that re-burns the tokens the cheap-triage split exists to save. The rule of thumb: offline
-script triages always; the Workflow fan-out does the deep per-thread reasoning whenever
-volume is more than a glance.
-
-**Hard constraints (these override convenience — they are how this stays Rule-6-safe):**
-
-- **Read-only scanners — Rule 6.** Every scanner agent's prompt MUST state, verbatim in
- spirit: _"You are READ-ONLY. Do NOT send, archive, mark-read, or mutate anything. Only
- read / search and classify. Return structured results."_ **"READ-ONLY" means exactly
- one thing here — never send, archive, mark-read, or mutate. It does NOT mean "stay inside
- your one assigned channel."** Each agent still owns its assigned channel's classification
- pass, but for any NEEDS_REPLY candidate it must pull full cross-channel context on that
- person/topic/thread before drafting — per "FULL CONTEXT — NEVER ASSUME" and "FULL-CONTEXT
- RECALL + CROSS-CHANNEL DEDUP" below (gmail search across the person's email, whatsapp
- search/list_messages for mentions elsewhere, the ops-memories `contact_*.md` profile,
- etc.) — not just read its own channel's thread in isolation. It then returns a
- recommendation AND a pre-written draft (when one is warranted), grounded in that full
- research, not a raw single-channel classification. **All sending stays in the main
- session**, one draft → one approval → one send. The workflow NEVER sends, archives, or
- mutates — it only reads (across whatever channels the candidate needs) and classifies.
-- **Detect availability FIRST.** Only fan out a scanner for a channel that already passed
- the per-channel checks in "Channel availability + fallback". Never spawn a scanner for an
- unconfigured / unreachable channel — it burns a turn and produces a misleading
- "unreachable" row. Build the workflow's channel list from the channels you confirmed up.
-- **No `AskUserQuestion` inside the workflow.** Presentation, reply drafting, approval,
- archive, and the Cron offer all happen back in the main session _after_ the workflow
- returns. Workflow agents cannot gate sends, so they must never try.
-- **Each scanner loads its own channel's MCP tools** via `ToolSearch select:...` before use,
- and honours the documented reconnect handshake (WhatsApp 3× at 5s, iMessage 5s→15s) before
- reporting a channel unreachable. Never fabricate conversations. **Also grant each agent the
- read-only cross-channel search tools it needs for context-gathering** — at minimum gmail
- search/thread-read, whatsapp search/list_messages, and the ops-memories contact registry —
- so it can look up the same person/topic across other channels before drafting, not just
- its own assigned channel's tools.
-
-**Canonical scan workflow.** Pass the available channels in via `args` (the orchestrator
-builds the list from the detected-available channels), so the script body stays stable:
-
-**⚠️ When invoking `Workflow`, you MUST pass the channel task list via the tool call's
-top-level `args` parameter (as shown below) — not just referenced inside the `script` body.
-Omitting it silently produces zero agents and an empty result, not an error.** A real run
-failed this way: `args` was written into the script text but never passed as the tool's
-`args` parameter, so the workflow spawned nothing and returned nothing to synthesize.
-
-```js
-Workflow({
- args: [
- // ONE entry per channel detected as AVAILABLE. Build select/steps from the
- // per-channel reference sections below. Examples:
- {
- key: 'email',
- select: 'select:mcp__gog__gmail_search,mcp__gog__gmail_read_thread,mcp__gog__gmail_labels',
- steps:
- 'gmail_search "in:inbox newer_than:7d"; labels+from on the search envelope are first-pass only — before any NEEDS_REPLY, gog gmail thread get per candidate and clear the FULL-THREAD AWARENESS GATE (full thread both directions, 2-sentence arc, reconcile SENT).',
- },
- {
- key: 'slack',
- select:
- 'select:mcp__slack__conversations_unreads,mcp__slack__channels_list,mcp__slack__conversations_history,mcp__slack__conversations_replies',
- steps: 'conversations_unreads to find unread DMs/channels; read latest via history/replies.',
- },
- {
- key: 'whatsapp',
- select:
- 'select:mcp__whatsapp__list_chats,mcp__whatsapp__list_messages,mcp__whatsapp__search_contacts,mcp__whatsapp__get_chat',
- steps:
- 'list_chats {sort_by:"last_active"}; last_is_from_me is ONLY a first pass. FIRST merge each person lid<->phone chats into one conversation via whatsmeow_lid_map (store/whatsapp.db) so a contact is not double-counted as NEEDS_REPLY on @lid and WAITING on the phone JID. Then, before any NEEDS_REPLY, clear the FULL-THREAD AWARENESS GATE: list_messages {chat_jid, limit: 25} for EACH mapped JID (or the DB union recipe), merge by timestamp, read BOTH directions including is_from_me=1 rows and [voice] transcripts, write the 2-sentence arc summary, and reconcile the user own sends that may be missing from the store. Never classify from the last message alone.',
- },
- {
- key: 'imessage',
- select: 'select:mcp__plugin_imessage_imessage__chat_messages',
- steps:
- 'chat_messages {limit:30} (omit chat_guid); classify each thread by who sent the LAST message. Capture the chat_id GUID from each header.',
- },
- {
- key: 'telegram',
- select:
- 'select:mcp__plugin_ops_telegram__list_dialogs,mcp__plugin_ops_telegram__get_messages,mcp__plugin_ops_telegram__search_messages',
- steps: 'list_dialogs (last 7d); get_messages for dialogs with pending activity.',
- },
- ],
- script: `
-export const meta = {
- name: 'ops-inbox-scan',
- description: 'Read-only parallel scan + classify of all available comms channels',
- phases: [{ title: 'Scan' }, { title: 'Synthesize' }],
-}
-
-const SCAN_SCHEMA = {
- type: 'object', additionalProperties: false,
- required: ['channel', 'reachable', 'conversations'],
- properties: {
- channel: { type: 'string' },
- reachable: { type: 'boolean', description: 'true ONLY if tools were actually called and returned data' },
- note: { type: 'string', description: 'tools called, or the exact error if unreachable' },
- conversations: { type: 'array', items: {
- type: 'object', additionalProperties: false,
- required: ['who', 'summary', 'status'],
- properties: {
- who: { type: 'string' },
- summary: { type: 'string', description: 'one line: what is pending' },
- status: { type: 'string', enum: ['NEEDS_REPLY', 'WAITING', 'HANDLED', 'FYI'] },
- chatId: { type: 'string', description: 'JID / chat GUID / threadId needed to reply — capture it now' },
- lastMessageAt: { type: 'string' },
- },
- }},
- },
-}
-
-phase('Scan')
-// args can arrive as a JSON string (harness serialization) — parse defensively
-// so the fan-out never dies with "args.map is not a function".
-const CHANNELS = (typeof args === 'string' ? JSON.parse(args) : args) || []
-const scans = (await parallel(CHANNELS.map(c => () =>
- agent(
- \`READ-ONLY inbox scanner for the "\${c.key}" channel. You MUST NOT send, archive, \` +
- \`mark-read, or mutate anything — read / search ONLY.\\n\` +
- \`STEP 1: run ToolSearch with query exactly "\${c.select}" to load the tool schemas.\\n\` +
- \`STEP 2: \${c.steps}\\n\` +
- \`Classify each conversation NEEDS_REPLY / WAITING / HANDLED / FYI exactly as STEP 2 \` +
- \`directs (including merged-thread / full-thread rules where specified). Capture chatId \` +
- \`for each (needed later to reply). Cover ~last 7 days plus \` +
- \`anything clearly still open. Retry the documented reconnect handshake before reporting \` +
- \`reachable=false. Never fabricate conversations.\`,
- { label: \`scan:\${c.key}\`, phase: 'Scan', schema: SCAN_SCHEMA }
- )
-))).filter(Boolean)
-
-phase('Synthesize')
-return await agent(
- \`You are READ-ONLY. Do NOT send, archive, mark-read, or mutate anything — only merge \` +
- \`and order the data below.\\n\` +
- \`Per-channel read-only scan results as JSON:\\n\${JSON.stringify(scans, null, 2)}\\n\\n\` +
- \`Return ONLY structured JSON with buckets: needsReply[], waiting[], fyi[], unreachable[]. \` +
- \`Each item: {channel, who, summary, chatId, lastMessageAt}. Order needsReply most-urgent \` +
- \`first. Do NOT draft replies — that happens in the main session under the per-message gate.\`,
- { label: 'synthesize', phase: 'Synthesize',
- schema: { type: 'object', additionalProperties: true } }
-)
-`,
-});
-```
-
-After the workflow returns the synthesized buckets, proceed to **presentation + reply in
-the main session** using the per-channel sections below. Stage every reply one-at-a-time
-under Rule 6 (one draft → `AskUserQuestion` / approval word → send → next). The workflow
-gave you _what_ needs a reply and the `chatId` to reach it; it never sent anything.
+**Fan-out for real per-thread volume.** After the cheap scan, deep-read and draft in parallel (`Workflow` default; Agent Teams / Hermes `delegate_task` fallback). Skip only the trivial case (~1–3 candidates). Mechanics, hard constraints, and the canonical Workflow JS: `references/fan-out.md`. Fan-out never sends, archives, or mutates — Rule 6 stays in the main session.
-### Fallback — Agent Teams support
+### Fallback — Hermes / Grok (`delegate_task`)
-When the `Workflow` tool is unavailable (older harness) but
-`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set, fall back to **Agent Teams** for the
-"all channels" path — same read-only fan-out, just without the Workflow harness. Set up one
-read-only scanner teammate per _available_ channel:
-
-```
-TeamCreate("inbox-channels")
-Agent(team_name="inbox-channels", name="whatsapp-scanner", ...) # READ-ONLY
-Agent(team_name="inbox-channels", name="email-scanner", ...) # READ-ONLY
-Agent(team_name="inbox-channels", name="slack-scanner", ...) # READ-ONLY
-Agent(team_name="inbox-channels", name="telegram-scanner", ...) # READ-ONLY
-```
-
-Each teammate scans its channel and reports classified results back; you can steer
-("focus email first") and process replies as they land. Agent Teams' advantage over the
-Workflow path is mid-flight steering and shared context (one scanner can flag a message
-referencing another channel). If neither `Workflow` nor Agent Teams is available, scan
-channels sequentially in the main session.
-
-**Every fallback keeps the same read-only + Rule 6 constraints** — each scanner teammate's
-prompt MUST say _"You are READ-ONLY. Do NOT send any outbound messages. Return drafts to the
-orchestrator who stages them one-by-one."_ Sending stays in the main session, always.
-
-### Fallback — Hermes (`delegate_task`)
-
-When this skill runs on Hermes (no `Workflow` tool, no `AskUserQuestion`):
+When this skill runs on Hermes or Grok (no `Workflow` tool, no `AskUserQuestion`):
- **Fan-out:** `delegate_task` for one read-only scanner per available channel. If that
tool is missing, scan sequentially in the main session. Same read-only contract.
@@ -566,4 +273,10 @@ When this skill runs on Hermes (no `Workflow` tool, no `AskUserQuestion`):
## Additional resources
-Channel, CLI, and edge-case detail lives in `references/` next to this skill. Read those files before acting on a matching channel or sub-command. Do not skip them.
+Read the matching file before acting. Do not skip.
+
+- `references/cli.md` — WhatsApp MCP + gog CLI
+- `references/details.md` — inbox-zero rules, gates, per-channel processing
+- `references/runtime.md` — freshness, Mac fallback, version-heal, watcher
+- `references/fan-out.md` — Workflow JS, Agent Teams, hard constraints
+- `CHANNELS.md` — channel setup
diff --git a/claude-ops/skills/ops-inbox/references/fan-out.md b/claude-ops/skills/ops-inbox/references/fan-out.md
new file mode 100644
index 00000000..7c634818
--- /dev/null
+++ b/claude-ops/skills/ops-inbox/references/fan-out.md
@@ -0,0 +1,185 @@
+# Inbox fan-out (Workflow / Agent Teams)
+
+Loaded from the parent SKILL.md. Follow `ops-rules`. Scanners are read-only. Sends stay in the main session (Rule 6).
+
+### Workflow fan-out (DEFAULT for real per-thread volume — per the note above)
+
+When there is real per-thread volume to deep-read and draft, use the **`Workflow` tool** as
+the **default** path: fan out one **read-only** scanner/drafter agent per channel (or per
+thread-chunk within a high-volume channel), then synthesize. Channels and chunks are
+processed concurrently and wall-clock collapses to the slowest single unit. **Do not fan out
+for channels the offline script already fully triaged down to ~1–3 trivial candidates** —
+that re-burns the tokens the cheap-triage split exists to save. The rule of thumb: offline
+script triages always; the Workflow fan-out does the deep per-thread reasoning whenever
+volume is more than a glance.
+
+**Hard constraints (these override convenience — they are how this stays Rule-6-safe):**
+
+- **Read-only scanners — Rule 6.** Every scanner agent's prompt MUST state, verbatim in
+ spirit: _"You are READ-ONLY. Do NOT send, archive, mark-read, or mutate anything. Only
+ read / search and classify. Return structured results."_ **"READ-ONLY" means exactly
+ one thing here — never send, archive, mark-read, or mutate. It does NOT mean "stay inside
+ your one assigned channel."** Each agent still owns its assigned channel's classification
+ pass, but for any NEEDS_REPLY candidate it must pull full cross-channel context on that
+ person/topic/thread before drafting — per "FULL CONTEXT — NEVER ASSUME" and "FULL-CONTEXT
+ RECALL + CROSS-CHANNEL DEDUP" below (gmail search across the person's email, whatsapp
+ search/list_messages for mentions elsewhere, the ops-memories `contact_*.md` profile,
+ etc.) — not just read its own channel's thread in isolation. It then returns a
+ recommendation AND a pre-written draft (when one is warranted), grounded in that full
+ research, not a raw single-channel classification. **All sending stays in the main
+ session**, one draft → one approval → one send. The workflow NEVER sends, archives, or
+ mutates — it only reads (across whatever channels the candidate needs) and classifies.
+- **Detect availability FIRST.** Only fan out a scanner for a channel that already passed
+ the per-channel checks in "Channel availability + fallback". Never spawn a scanner for an
+ unconfigured / unreachable channel — it burns a turn and produces a misleading
+ "unreachable" row. Build the workflow's channel list from the channels you confirmed up.
+- **No `AskUserQuestion` inside the workflow.** Presentation, reply drafting, approval,
+ archive, and the Cron offer all happen back in the main session _after_ the workflow
+ returns. Workflow agents cannot gate sends, so they must never try.
+- **Each scanner loads its own channel's MCP tools** via `ToolSearch select:...` before use,
+ and honours the documented reconnect handshake (WhatsApp 3× at 5s, iMessage 5s→15s) before
+ reporting a channel unreachable. Never fabricate conversations. **Also grant each agent the
+ read-only cross-channel search tools it needs for context-gathering** — at minimum gmail
+ search/thread-read, whatsapp search/list_messages, and the ops-memories contact registry —
+ so it can look up the same person/topic across other channels before drafting, not just
+ its own assigned channel's tools.
+
+**Canonical scan workflow.** Pass the available channels in via `args` (the orchestrator
+builds the list from the detected-available channels), so the script body stays stable:
+
+**⚠️ When invoking `Workflow`, you MUST pass the channel task list via the tool call's
+top-level `args` parameter (as shown below) — not just referenced inside the `script` body.
+Omitting it silently produces zero agents and an empty result, not an error.** A real run
+failed this way: `args` was written into the script text but never passed as the tool's
+`args` parameter, so the workflow spawned nothing and returned nothing to synthesize.
+
+```js
+Workflow({
+ args: [
+ // ONE entry per channel detected as AVAILABLE. Build select/steps from the
+ // per-channel reference sections below. Examples:
+ {
+ key: 'email',
+ select: 'select:mcp__gog__gmail_search,mcp__gog__gmail_read_thread,mcp__gog__gmail_labels',
+ steps:
+ 'gmail_search "in:inbox newer_than:7d"; labels+from on the search envelope are first-pass only — before any NEEDS_REPLY, gog gmail thread get per candidate and clear the FULL-THREAD AWARENESS GATE (full thread both directions, 2-sentence arc, reconcile SENT).',
+ },
+ {
+ key: 'slack',
+ select:
+ 'select:mcp__slack__conversations_unreads,mcp__slack__channels_list,mcp__slack__conversations_history,mcp__slack__conversations_replies',
+ steps: 'conversations_unreads to find unread DMs/channels; read latest via history/replies.',
+ },
+ {
+ key: 'whatsapp',
+ select:
+ 'select:mcp__whatsapp__list_chats,mcp__whatsapp__list_messages,mcp__whatsapp__search_contacts,mcp__whatsapp__get_chat',
+ steps:
+ 'list_chats {sort_by:"last_active"}; last_is_from_me is ONLY a first pass. FIRST merge each person lid<->phone chats into one conversation via whatsmeow_lid_map (store/whatsapp.db) so a contact is not double-counted as NEEDS_REPLY on @lid and WAITING on the phone JID. Then, before any NEEDS_REPLY, clear the FULL-THREAD AWARENESS GATE: list_messages {chat_jid, limit: 25} for EACH mapped JID (or the DB union recipe), merge by timestamp, read BOTH directions including is_from_me=1 rows and [voice] transcripts, write the 2-sentence arc summary, and reconcile the user own sends that may be missing from the store. Never classify from the last message alone.',
+ },
+ {
+ key: 'imessage',
+ select: 'select:mcp__plugin_imessage_imessage__chat_messages',
+ steps:
+ 'chat_messages {limit:30} (omit chat_guid); classify each thread by who sent the LAST message. Capture the chat_id GUID from each header.',
+ },
+ {
+ key: 'telegram',
+ select:
+ 'select:mcp__plugin_ops_telegram__list_dialogs,mcp__plugin_ops_telegram__get_messages,mcp__plugin_ops_telegram__search_messages',
+ steps: 'list_dialogs (last 7d); get_messages for dialogs with pending activity.',
+ },
+ ],
+ script: `
+export const meta = {
+ name: 'ops-inbox-scan',
+ description: 'Read-only parallel scan + classify of all available comms channels',
+ phases: [{ title: 'Scan' }, { title: 'Synthesize' }],
+}
+
+const SCAN_SCHEMA = {
+ type: 'object', additionalProperties: false,
+ required: ['channel', 'reachable', 'conversations'],
+ properties: {
+ channel: { type: 'string' },
+ reachable: { type: 'boolean', description: 'true ONLY if tools were actually called and returned data' },
+ note: { type: 'string', description: 'tools called, or the exact error if unreachable' },
+ conversations: { type: 'array', items: {
+ type: 'object', additionalProperties: false,
+ required: ['who', 'summary', 'status'],
+ properties: {
+ who: { type: 'string' },
+ summary: { type: 'string', description: 'one line: what is pending' },
+ status: { type: 'string', enum: ['NEEDS_REPLY', 'WAITING', 'HANDLED', 'FYI'] },
+ chatId: { type: 'string', description: 'JID / chat GUID / threadId needed to reply — capture it now' },
+ lastMessageAt: { type: 'string' },
+ },
+ }},
+ },
+}
+
+phase('Scan')
+// args can arrive as a JSON string (harness serialization) — parse defensively
+// so the fan-out never dies with "args.map is not a function".
+const CHANNELS = (typeof args === 'string' ? JSON.parse(args) : args) || []
+const scans = (await parallel(CHANNELS.map(c => () =>
+ agent(
+ \`READ-ONLY inbox scanner for the "\${c.key}" channel. You MUST NOT send, archive, \` +
+ \`mark-read, or mutate anything — read / search ONLY.\\n\` +
+ \`STEP 1: run ToolSearch with query exactly "\${c.select}" to load the tool schemas.\\n\` +
+ \`STEP 2: \${c.steps}\\n\` +
+ \`Classify each conversation NEEDS_REPLY / WAITING / HANDLED / FYI exactly as STEP 2 \` +
+ \`directs (including merged-thread / full-thread rules where specified). Capture chatId \` +
+ \`for each (needed later to reply). Cover ~last 7 days plus \` +
+ \`anything clearly still open. Retry the documented reconnect handshake before reporting \` +
+ \`reachable=false. Never fabricate conversations.\`,
+ { label: \`scan:\${c.key}\`, phase: 'Scan', schema: SCAN_SCHEMA }
+ )
+))).filter(Boolean)
+
+phase('Synthesize')
+return await agent(
+ \`You are READ-ONLY. Do NOT send, archive, mark-read, or mutate anything — only merge \` +
+ \`and order the data below.\\n\` +
+ \`Per-channel read-only scan results as JSON:\\n\${JSON.stringify(scans, null, 2)}\\n\\n\` +
+ \`Return ONLY structured JSON with buckets: needsReply[], waiting[], fyi[], unreachable[]. \` +
+ \`Each item: {channel, who, summary, chatId, lastMessageAt}. Order needsReply most-urgent \` +
+ \`first. Do NOT draft replies — that happens in the main session under the per-message gate.\`,
+ { label: 'synthesize', phase: 'Synthesize',
+ schema: { type: 'object', additionalProperties: true } }
+)
+`,
+});
+```
+
+After the workflow returns the synthesized buckets, proceed to **presentation + reply in
+the main session** using the per-channel sections below. Stage every reply one-at-a-time
+under Rule 6 (one draft → `AskUserQuestion` / approval word → send → next). The workflow
+gave you _what_ needs a reply and the `chatId` to reach it; it never sent anything.
+
+### Fallback — Agent Teams support
+
+When the `Workflow` tool is unavailable (older harness) but
+`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set, fall back to **Agent Teams** for the
+"all channels" path — same read-only fan-out, just without the Workflow harness. Set up one
+read-only scanner teammate per _available_ channel:
+
+```
+TeamCreate("inbox-channels")
+Agent(team_name="inbox-channels", name="whatsapp-scanner", ...) # READ-ONLY
+Agent(team_name="inbox-channels", name="email-scanner", ...) # READ-ONLY
+Agent(team_name="inbox-channels", name="slack-scanner", ...) # READ-ONLY
+Agent(team_name="inbox-channels", name="telegram-scanner", ...) # READ-ONLY
+```
+
+Each teammate scans its channel and reports classified results back; you can steer
+("focus email first") and process replies as they land. Agent Teams' advantage over the
+Workflow path is mid-flight steering and shared context (one scanner can flag a message
+referencing another channel). If neither `Workflow` nor Agent Teams is available, scan
+channels sequentially in the main session.
+
+**Every fallback keeps the same read-only + Rule 6 constraints** — each scanner teammate's
+prompt MUST say _"You are READ-ONLY. Do NOT send any outbound messages. Return drafts to the
+orchestrator who stages them one-by-one."_ Sending stays in the main session, always.
+
+Hermes fallback: parent SKILL.md + `hermes-plugin/RUNTIME.md` (Rule 10).
diff --git a/claude-ops/skills/ops-inbox/references/runtime.md b/claude-ops/skills/ops-inbox/references/runtime.md
new file mode 100644
index 00000000..dd7b9646
--- /dev/null
+++ b/claude-ops/skills/ops-inbox/references/runtime.md
@@ -0,0 +1,93 @@
+# Inbox runtime context
+
+Loaded from the parent SKILL.md. Follow `ops-rules`. Run these steps every invocation, before classifying.
+
+## Runtime Context
+
+**Standing default posture — read this first, every run.** Before the offline scan-engine, before any per-channel MCP call, the default mode of this skill is: spin up one agent per available/configured channel (WhatsApp, Email, Slack, Telegram, iMessage, Notion, Discord — whichever are configured; see "Channel availability + fallback" below) via the `Workflow` tool (Agent Teams as the fallback), running in parallel. This is the standing default for the whole skill — you do not wait for triage to discover volume before fanning out; fanning out IS the first move. Each per-channel agent: deep-reads every conversation in its channel, clears the FULL-THREAD AWARENESS GATE, and — for any NEEDS_REPLY candidate — pulls full cross-channel context on that person/topic/thread (gmail search, whatsapp search, the ops-memories contact profile, etc. — per "FULL CONTEXT — NEVER ASSUME" / "FULL-CONTEXT RECALL + CROSS-CHANNEL DEDUP" below) before drafting a reply where one is genuinely needed. It reports back structured recommendations (classification + draft + reasoning, grounded in that cross-channel research) to the orchestrating session. **"READ-ONLY" here means one thing only — never send, archive, mark-read, or mutate anything — it does NOT mean "stay inside your one assigned channel"; agents are granted the cross-channel read/search tools they need for context-gathering.** Every send still goes through the main session's Rule-6 one-draft → one-approval → one-send gate, unchanged (see "Standing behavior: RUN WIDE" and "Workflow fan-out" below for the mechanics and hard constraints). The offline `bin/ops-inbox-scan` step below is a fast pre-filter that FEEDS this fan-out — not a replacement for it, so the per-channel agents aren't blindly scanning everything from scratch. The only exception: skip the fan-out in the genuinely trivial case (script covered everything, ~1-3 candidates left) — that stays the exception, not the default framing.
+
+Before executing, load available context:
+
+0. **Auto-sync WhatsApp in the background (DEFAULT — every invocation)** — the FIRST thing this skill does, before any scan or menu, is guarantee the store is fresh, then fire a recent-conversation history backfill **and** a contacts-link in the background, non-blocking.
+
+ **0a. Freshness gate (run FIRST, blocking, bounded).** Before classifying anything, run `~/bin/wa-inbox-fresh.sh` (shipped by `scripts/install-whatsapp-bridge-linux.sh`). It probes the bridge with a real **curl connection probe** (`curl -s -m4 http://127.0.0.1:8080/`), forces a backfill, triggers voice-note transcription, and waits (bounded ~32s) for the newest message to settle, then prints a FRESHNESS report (`newest message = … (N min old)`). It **only restarts the bridge if the curl probe genuinely fails twice** — do NOT gate liveness on `ss | grep :8080`, because `ss` renders port 8080 as the service name `webcache`, so the grep never matches and you'd needlessly bounce a healthy bridge. Exit 2 means the bridge is down and unrecoverable → the store is STALE, do not trust last-sender classification.
+
+### Mac WhatsApp.app fallback (bridge-miss recovery)
+
+The whatsmeow bridge can **silently miss inbound messages** when its history/app-state sync lags — most often on `@lid` chats (e.g. 2026-06-11 it missed a reply from a contact that the Mac WhatsApp.app had). The Mac app keeps an **unencrypted** local Core Data store at `~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite`, readable over Tailscale SSH, so it is a reliable ground-truth backstop.
+
+- **When it runs AUTOMATICALLY:** `wa-inbox-fresh.sh` now invokes the Mac cross-check itself whenever the bridge store looks stale — on exit 2 (store unreadable) or when the newest message is >2h old, it prints a `MAC GROUND TRUTH` block (latest 10 messages from the Mac app store) inline in the freshness report. No orchestration needed.
+- **When to use manually:** a contact's _known_ reply is missing from the bridge (common on `@lid` chats) — cross-check before classifying that thread as "no reply".
+- **Command:** `bin/wa-mac-latest.sh --contact <name|number> [N]` (also `--recent [N]`, `--since "YYYY-MM-DD HH:MM"`, add `--json` for machine-readable output). It reads `~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite` over SSH. Schema: `ZWAMESSAGE` (`ZTEXT`, `ZISFROMME`, `ZMESSAGEDATE` = seconds since 2001-01-01) joined to `ZWACHATSESSION` (`ZPARTNERNAME`, `ZCONTACTJID`).
+- **Transport chain (`bin/wa-mac-transport.sh`, shared by all wa-mac-\* scripts):** ① Tailscale/direct SSH (`WA_MAC_SSH=user@host`) → ② Cloudflare-tunnel SSH (`WA_MAC_CF_HOST=ssh-mac.example.com`, via `cloudflared access ssh` ProxyCommand) when Tailscale is down. One-time wiring: `scripts/setup-wa-mac-cf-tunnel.sh` (installs cloudflared locally + the Mac LaunchDaemon from a remotely-managed tunnel token, then verifies end-to-end). Both env vars live in the shell profile, never in the repo.
+- **READ-ONLY ground truth for reads.** The reader never writes and never sends. Sends still go through the whatsmeow bridge (`mcp__whatsapp__send_message`) under the Rule-6 outbound-approval gate — the Mac store is only consulted to confirm what actually arrived. The ONLY write-capable Mac surface is `wa-mac-archive.sh` (archive-only, see Tier 4 of the archive ladder).
+- **Why no Linux-native alternative:** there is no official WhatsApp Linux desktop app; the third-party Flatpak clients (`whatsapp-for-linux`, ZapZap) are Electron WhatsApp-Web wrappers that need a GUI, consume a linked-device slot, and store data in encrypted IndexedDB (not a queryable SQLite) — so the Mac `ChatStorage.sqlite` is the preferred backstop.
+
+ **The FULL-THREAD AWARENESS GATE (in "Processing each channel") depends on this step having run first.** That gate's "read both directions incl. `[voice]`" only works once `wa-inbox-fresh.sh` (freshness + backfill) and the voice-note transcription pass (step 0c) have completed and the store has settled — otherwise outbound rows and `[voice]` bodies are still missing and the gate reads an incomplete thread.
+
+ **0b. Background backfill + contacts-link** (idempotent, safe every time). The backfill pulls recent messages for the 50 most-active chats; the link populates `messages.db.contacts` from the whatsmeow session store so both `<pn>@s.whatsapp.net` and `<lid>@lid` chat JIDs resolve to names (without it the `contacts` table is empty and LID-format chats show raw phone numbers):
+
+ ```bash
+ BR="${WHATSAPP_BRIDGE_DIR:-$HOME/.local/share/whatsapp-mcp/whatsapp-bridge}"
+ WA_PORT=$("$CLAUDE_PLUGIN_ROOT/bin/ops-wa-accounts" --port) || exit 3 # never assume 8080
+ WA_API="http://127.0.0.1:${WA_PORT}"
+ if curl -s -o /dev/null -m 4 "$WA_API/" 2>/dev/null; then
+ curl -fsS -m 10 -X POST "$WA_API/api/backfill" >/dev/null 2>&1 & # recent-conversation backfill
+ [ -f "$BR/link_contacts.py" ] && python3 "$BR/link_contacts.py" >/dev/null 2>&1 & # contacts link (phone + LID aliases)
+ fi
+ ```
+
+ Kick this off, then continue with the steps below while it runs — give the link ~2s before name-resolving chats. `link_contacts.py` resolves names via `whatsmeow_contacts` + `whatsmeow_lid_map` (name preference: full_name → first_name → push_name → business_name). It ships via `scripts/install-whatsapp-bridge-linux.sh` into the bridge dir; recreate it from `whatsmeow_contacts`/`whatsmeow_lid_map` if absent.
+
+ **0c. Voice notes are first-class.** Incoming voice notes (`media_type='audio'`, empty `content`) are auto-transcribed into `content` as `[voice] <text>` by the `whatsapp-transcribe.timer` (systemd-user, every 10 min, OpenAI `whisper-1`) — and `wa-inbox-fresh.sh` triggers a transcribe pass on every scan. So a voice note shows up in NEEDS_REPLY / thread scans exactly like a text message; treat a `[voice] …` body as the sender's words. Transcription is idempotent (only ever fills empty audio rows, never clobbers real text) and capped per run, so it never re-bills or stacks.
+
+ **0c-bis. ALL media is now first-class, not just voice.** Beyond voice→`[voice]` (transcribe above), incoming **video / image / document** media (empty `content`) is auto-enriched into `content` as `[video] …` / `[image] …` / `[document] …` by `transcriber/enrich_media.py` (vision for stills/video frames + Whisper for any audio track) on the `whatsapp-enrich.timer` (systemd-user, every 10 min) — and `wa-inbox-fresh.sh` queues an enrich pass on every scan. So an image, clip, or PDF shows up in NEEDS_REPLY / thread scans with a real, readable body, exactly like text. Enrichment is idempotent (only fills empty media rows) and capped per run. The bridge also **self-heals media that 403/404/410s** (stale `directPath`, common for larger media) by asking the sender's phone to re-upload via `SendMediaRetryReceipt` (`apply-patches.py` Fix M), so large media never silently drops.
+
+ **0d. The scan engine self-refreshes + self-reconciles on EVERY run — this is automatic, you do not orchestrate it.** `bin/ops-inbox-scan` (the primary classifier, step "Scan engine" below) now does the refresh/pull itself, BLOCKING and bounded, before it classifies — so the data is converged by the time you read its JSON, regardless of whether the background `ops-inbox-autosync` hook has finished. On each invocation the scan:
+ - **Refreshes (frontfill/backfill):** if this account's bridge is reachable (the port it resolved, not a fixed `:8080`), it fires `POST /api/backfill` + `link_contacts.py`, then **waits (bounded ~18s) for the newest stored message timestamp to stop advancing** so the classify pass reads a settled store. This is the blocking guarantee the background hook alone does NOT give. Skip with `OIS_NO_REFRESH=1` (set automatically on repeat calls in one session to avoid re-waiting).
+ - **Reconciles outbound sends (owner directive 2026-06-05 "include all things I sent to all people"):** it reads the bridge's outbound-send journal (`journalctl --user -u whatsapp-bridge.service`, or the bridge log file on non-systemd hosts) into a `{recipient_jid → latest_send_epoch}` map, and **demotes any NEEDS_REPLY thread whose last inbound is older than a send to any of that person's JIDs** (`reconciled` flag set, moved to WAITING). This catches replies that went out via `/api/send` or a phone send that has not yet landed in `messages.db` — the single most common false-NEEDS_REPLY. Only epoch-stamped send lines drive demotion (a send that genuinely predates the inbound never demotes).
+
+ Net effect: running `/ops:ops-inbox` autonomously pulls the latest state AND folds in everything the user already sent, with **zero extra orchestration on your part** — just read the scan JSON. A `reconciled` field on a WAITING item means "already answered, reply not yet in the store"; never re-draft it. You still clear the FULL-THREAD AWARENESS GATE on whatever genuine NEEDS_REPLY candidates remain.
+
+1. **Self-heal plugin version pin** — if any `${CLAUDE_PLUGIN_DATA_DIR}` file or `~/.claude/plugins/installed_plugins.json` references a `cache/ops-marketplace/ops/X.Y.Z/` path that no longer exists on disk, downstream hooks (`stop-all.sh`, `ops-post-session-cleanup`) emit `Plugin directory does not exist`. Resolve before scanning:
+
+ ```bash
+ INSTALLED="$HOME/.claude/plugins/installed_plugins.json"
+ CACHE_DIR="$HOME/.claude/plugins/cache/ops-marketplace/ops"
+ PINNED=$(python3 -c "import json; d=json.load(open('$INSTALLED')); print(d.get('plugins',{}).get('ops@ops-marketplace',[{}])[0].get('version',''))")
+ LATEST=$(ls "$CACHE_DIR" 2>/dev/null | sort -V | tail -1)
+ if [ -n "$PINNED" ] && [ -n "$LATEST" ] && [ "$PINNED" != "$LATEST" ] && [ ! -d "$CACHE_DIR/$PINNED" ]; then
+ python3 -c "
+ import json
+ p='$INSTALLED'; d=json.load(open(p))
+ for e in d.get('plugins',{}).get('ops@ops-marketplace',[]):
+ if e.get('version')=='$PINNED':
+ e['version']='$LATEST'
+ e['installPath']='$CACHE_DIR/$LATEST'
+ json.dump(d, open(p,'w'), indent=2)
+ "
+ bash "$HOME/.claude/scripts/hooks/ops-plugin-version-heal.sh" # rewrites daemon-services.json + mcp-proxy/servers.json
+ fi
+ ```
+
+ The existing `ops-plugin-version-heal.sh` only rewrites _downstream_ targets from `installed_plugins.json` (the source of truth). When the source itself is stale, the heal hook is a no-op — patch it first, then re-run the hook.
+
+2. **Preferences**: Read `${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json`
+ - `default_channels` — which channels to scan by default
+ - `secrets_manager` / `doppler` — how to resolve channel credentials if not in env
+
+3. **Daemon health**: Read `${CLAUDE_PLUGIN_DATA_DIR}/daemon-health.json`
+ - Check `whatsapp-bridge` status — verify `com.${USER}.whatsapp-bridge` is running (`lsof -i :8080` or `launchctl print "gui/$(id -u)/com.${USER}.whatsapp-bridge"`)
+ - Also verify the **ops mcp-proxy** is up on `:8090` (`lsof -i :8090 | grep LISTEN`) — Claude's MCP client connects through the proxy SSE endpoint, not directly to the bridge. If :8080 is up but :8090 is down, `mcp__whatsapp__*` tools will never load.
+ - If either layer is down, surface the issue before WhatsApp operations
+ - **Do not declare WhatsApp MCP unavailable purely because tools haven't loaded yet** — when both ports are LISTEN, retry `ToolSearch select:mcp__whatsapp__list_chats,...` up to 3× at 5s intervals to let the SSE handshake complete
+
+4. **Ops memories**: Check `${CLAUDE_PLUGIN_DATA_DIR}/memories/` before drafting any reply:
+ - `contact_*.md` — load profile for the contact you're about to reply to
+ - `preferences.md` — apply user's communication style and language preferences
+ - `topics_active.md` — check for active threads or deadlines related to this contact
+ - `donts.md` — never violate these restrictions in drafts
+
+5. **Launch the live inbox watcher (background job, every session)** — right after the steps above, start `bin/ops-inbox-live-watch.sh` via Bash with `run_in_background: true`. It polls the Gmail inbox (via `gog`) every ~4 minutes and exits — with a `NEW INBOX MAIL: <from> | <subject> | <date> | id=<id>` summary line — the instant a genuinely new inbound message lands; it also exits (with a `watcher expired` line) after ~6h if nothing new arrives. **The job's exit IS the new-mail ping** — treat it exactly like a direct orchestrator notification: when it fires, re-scan the affected channel and relaunch the watcher (same command) so live coverage never lapses. Pure bash + python3 + `gog`, no systemd/launchd dependency, cross-platform (Linux + macOS).
+
+Channel processing, FULL-THREAD AWARENESS GATE, and per-channel recipes: `details.md`.
diff --git a/claude-ops/skills/ops-integrate/SKILL.md b/claude-ops/skills/ops-integrate/SKILL.md
index a174860a..220c8aed 100644
--- a/claude-ops/skills/ops-integrate/SKILL.md
+++ b/claude-ops/skills/ops-integrate/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-integrate
-description: "This skill should be used when the user asks to \"/ops:ops-integrate\", \"run ops-integrate\", or \"use ops-integrate\". Add any SaaS API as a first-class integration. Provide the service name — ops-integrate discovers auth patterns, tests connectivity, and registers the API in your partner registry so it's available to other skills."
+description: "This skill should be used when the user asks to \"add an API\", \"integrate SaaS\", or \"/ops:ops-integrate\". Add any SaaS API as a first-class integration. Provide the service name — ops-integrate discovers auth patterns, tests connectivity, and registers the API in your partner registry so it's available to other skills."
argument-hint: '<service-name> [--url <base-url>] [--auth bearer|api-key|basic|oauth2] [--list]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-leadgen/SKILL.md b/claude-ops/skills/ops-leadgen/SKILL.md
index 2d2a57e3..f5a18d8a 100644
--- a/claude-ops/skills/ops-leadgen/SKILL.md
+++ b/claude-ops/skills/ops-leadgen/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-leadgen
-description: "This skill should be used when the user asks to \"/ops:ops-leadgen\", \"run ops-leadgen\", or \"use ops-leadgen\". My-Project B2B wholesale leadgen review and send flow. Shows pending cold-email drafts from my-project-b2b-leadgen, lets you approve/skip each one, and fires approved drafts one-at-a-time via Rule-6-gated `my-project-leadgen send`. Never batches sends."
+description: "This skill should be used when the user asks to \"leadgen drafts\", \"cold email approve\", or \"/ops:ops-leadgen\". My-Project B2B wholesale leadgen review and send flow. Shows pending cold-email drafts from my-project-b2b-leadgen, lets you approve/skip each one, and fires approved drafts one-at-a-time via Rule-6-gated `my-project-leadgen send`. Never batches sends."
argument-hint: '[review | send --draft-id N | usage | scrape | draft]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-linear/SKILL.md b/claude-ops/skills/ops-linear/SKILL.md
index 63bedaeb..a98c56b0 100644
--- a/claude-ops/skills/ops-linear/SKILL.md
+++ b/claude-ops/skills/ops-linear/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-linear
-description: "This skill should be used when the user asks to \"/ops:ops-linear\", \"run ops-linear\", or \"use ops-linear\". Linear command center. Shows current sprint, creates/updates issues, manages priorities, syncs with GSD phases."
+description: "This skill should be used when the user asks to \"linear sprint\", \"create a ticket\", or \"/ops:ops-linear\". Linear command center. Shows current sprint, creates/updates issues, manages priorities, syncs with GSD phases."
argument-hint: '[sprint|create|update|sync|backlog|issue-id]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-mac/SKILL.md b/claude-ops/skills/ops-mac/SKILL.md
index 09495cae..17101ca0 100644
--- a/claude-ops/skills/ops-mac/SKILL.md
+++ b/claude-ops/skills/ops-mac/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-mac
-description: "This skill should be used when the user asks to \"/ops:ops-mac\", \"run ops-mac\", or \"use ops-mac\". macOS diagnose-and-fix command center. Wraps the macos-toolkit CLI suite (machealth, netwhiz, pstop, macdog, lanchr, macbroom, macctl, macfig, updater) behind one entrypoint — self-installs the suite on first use, runs a read-only baseline audit (security, launch agents, processes, network, disk, system health), and applies guarded fixes (stale daemons, cache cleanup) with per-action confirmation. The application firewall is reported only and changed solely on an explicit request."
+description: "This skill should be used when the user asks to \"mac is slow\", \"macos fix\", or \"/ops:ops-mac\". macOS diagnose-and-fix command center. Wraps the macos-toolkit CLI suite (machealth, netwhiz, pstop, macdog, lanchr, macbroom, macctl, macfig, updater) behind one entrypoint — self-installs the suite on first use, runs a read-only baseline audit (security, launch agents, processes, network, disk, system health), and applies guarded fixes (stale daemons, cache cleanup) with per-action confirmation. The application firewall is reported only and changed solely on an explicit request."
argument-hint: '[audit|health|net|disk|procs|security|launchd|fix|ensure|update]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-marketing/SKILL.md b/claude-ops/skills/ops-marketing/SKILL.md
index 29c5ca25..84c7b4d7 100644
--- a/claude-ops/skills/ops-marketing/SKILL.md
+++ b/claude-ops/skills/ops-marketing/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-marketing
-description: "This skill should be used when the user asks to \"/ops:ops-marketing\", \"run ops-marketing\", or \"use ops-marketing\". Marketing command center. Email campaigns (Klaviyo), paid ads (Meta/Google), analytics (GA4), SEO, and social media metrics. One dashboard for all marketing channels."
+description: "This skill should be used when the user asks to \"klaviyo\", \"ads spend\", or \"/ops:ops-marketing\". Marketing command center. Email campaigns (Klaviyo), paid ads (Meta/Google), analytics (GA4), SEO, and social media metrics. One dashboard for all marketing channels."
argument-hint: '<project> [email|ads|analytics|seo|social|campaigns|setup|autopilot ...]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-mcp/SKILL.md b/claude-ops/skills/ops-mcp/SKILL.md
index 5aac9357..9ead9db4 100644
--- a/claude-ops/skills/ops-mcp/SKILL.md
+++ b/claude-ops/skills/ops-mcp/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-mcp
-description: "This skill should be used when the user asks to \"/ops:ops-mcp\", \"run ops-mcp\", or \"use ops-mcp\". MCP server health dashboard and reconnect control. Surfaces the watchdog + keepalive + reauth subsystem as a discoverable slash command. Routes — status, servers, reconnect, reauth, logs, restart, test."
+description: "This skill should be used when the user asks to \"MCP down\", \"reconnect MCP\", or \"/ops:ops-mcp\". MCP server health dashboard and reconnect control. Surfaces the watchdog + keepalive + reauth subsystem as a discoverable slash command. Routes — status, servers, reconnect, reauth, logs, restart, test."
argument-hint: '[status|servers|reconnect [server]|reauth [server]|logs [N]|restart|test [server]]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-merge/SKILL.md b/claude-ops/skills/ops-merge/SKILL.md
index 06644c8c..db3e6d11 100644
--- a/claude-ops/skills/ops-merge/SKILL.md
+++ b/claude-ops/skills/ops-merge/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-merge
-description: "This skill should be used when the user asks to \"/ops:ops-merge\", \"run ops-merge\", or \"use ops-merge\". Autonomous salvage + PR merge pipeline. FIRST scans every repo in every org for orphan worktrees, feature branches without PRs, uncommitted/staged/stashed work, and unpushed commits — dispatches subagents to finish/PR all loose local work. THEN scans all open PRs, dispatches fixers for CI/conflicts/reviews, and merges. Use --main to also sync dev↔main branches. Use --no-salvage to skip Phase 0 (PR-only mode). Use --salvage-only to stop after Phase 0."
+description: "This skill should be used when the user asks to \"merge PRs\", \"salvage branches\", or \"/ops:ops-merge\". Autonomous salvage + PR merge pipeline. FIRST scans every repo in every org for orphan worktrees, feature branches without PRs, uncommitted/staged/stashed work, and unpushed commits — dispatches subagents to finish/PR all loose local work. THEN scans all open PRs, dispatches fixers for CI/conflicts/reviews, and merges. Use --main to also sync dev↔main branches. Use --no-salvage to skip Phase 0 (PR-only mode). Use --salvage-only to stop after Phase 0."
argument-hint: '[--main] [--repo org/repo] [--dry-run] [--no-salvage] [--salvage-only]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-monitor/SKILL.md b/claude-ops/skills/ops-monitor/SKILL.md
index 25a0a540..9ea12e5a 100644
--- a/claude-ops/skills/ops-monitor/SKILL.md
+++ b/claude-ops/skills/ops-monitor/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-monitor
-description: "This skill should be used when the user asks to \"/ops:ops-monitor\", \"run ops-monitor\", or \"use ops-monitor\". Unified APM and monitoring surface. Polls Datadog, New Relic, and OpenTelemetry backends for active alerts, error traces, and entity health. Use --watch for live polling every 60 seconds. Use --setup to configure monitoring credentials."
+description: "This skill should be used when the user asks to \"datadog\", \"APM alerts\", or \"/ops:ops-monitor\". Unified APM and monitoring surface. Polls Datadog, New Relic, and OpenTelemetry backends for active alerts, error traces, and entity health. Use --watch for live polling every 60 seconds. Use --setup to configure monitoring credentials."
argument-hint: '[--watch] [--setup] [--backend datadog|newrelic|otel]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-next/SKILL.md b/claude-ops/skills/ops-next/SKILL.md
index 83f449a2..62dc6f06 100644
--- a/claude-ops/skills/ops-next/SKILL.md
+++ b/claude-ops/skills/ops-next/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-next
-description: "This skill should be used when the user asks to \"/ops:ops-next\", \"run ops-next\", or \"use ops-next\". Business-level \"what should I do next\". Priority stack — fires > competitor alerts > unread comms > ready-to-merge PRs > Linear sprint > revenue-generating GSD work. Uses pre-gathered data and routes to the right skill."
+description: "This skill should be used when the user asks to \"what should I do next\", \"priority stack\", or \"/ops:ops-next\". Business-level \"what should I do next\". Priority stack — fires > competitor alerts > unread comms > ready-to-merge PRs > Linear sprint > revenue-generating GSD work. Uses pre-gathered data and routes to the right skill."
argument-hint: '[context]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-orchestrate/SKILL.md b/claude-ops/skills/ops-orchestrate/SKILL.md
index d593a133..46fcba00 100644
--- a/claude-ops/skills/ops-orchestrate/SKILL.md
+++ b/claude-ops/skills/ops-orchestrate/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-orchestrate
-description: "This skill should be used when the user asks to \"/ops:ops-orchestrate\", \"run ops-orchestrate\", or \"use ops-orchestrate\". Autonomous multi-project orchestration engine. Audits all registered projects, structures work into dependency-wired tasks, dispatches parallel agents (subagents or Agent Teams), audits completions, and ships PRs. Registry-driven — works for any user with a configured project registry."
+description: "This skill should be used when the user asks to \"orchestrate projects\", \"dispatch agents\", or \"/ops:ops-orchestrate\". Autonomous multi-project orchestration engine. Audits all registered projects, structures work into dependency-wired tasks, dispatches parallel agents (subagents or Agent Teams), audits completions, and ships PRs. Registry-driven — works for any user with a configured project registry."
argument-hint: '[--teams|--subagents|--hybrid|--dry-run|--project alias|--fires-only|--max-waves N]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-package/SKILL.md b/claude-ops/skills/ops-package/SKILL.md
index e6c96994..7560043a 100644
--- a/claude-ops/skills/ops-package/SKILL.md
+++ b/claude-ops/skills/ops-package/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-package
-description: "This skill should be used when the user asks to \"/ops:ops-package\", \"run ops-package\", or \"use ops-package\". Ship parcels via any configured carrier — MyParcel, Sendcloud, DHL Parcel NL, PostNL, DPD, UPS, FedEx. Auto-selects the first carrier whose credentials are configured, or pass --carrier <name> to override. Verbs: ship, label, track, list, carriers."
+description: "This skill should be used when the user asks to \"ship a parcel\", \"print a label\", or \"/ops:ops-package\". Ship parcels via any configured carrier — MyParcel, Sendcloud, DHL Parcel NL, PostNL, DPD, UPS, FedEx. Auto-selects the first carrier whose credentials are configured, or pass --carrier <name> to override. Verbs: ship, label, track, list, carriers."
argument-hint: '[--carrier <name>] <ship|label|track|list|carriers> [args...]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-pocket/SKILL.md b/claude-ops/skills/ops-pocket/SKILL.md
index 5c132017..ece82612 100644
--- a/claude-ops/skills/ops-pocket/SKILL.md
+++ b/claude-ops/skills/ops-pocket/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-pocket
-description: "This skill should be used when the user asks to \"/ops:ops-pocket\", \"run ops-pocket\", or \"use ops-pocket\". Pocket voice-memo pipeline command center. Surfaces the watcher → triage → executor → notifier → bridges chain that turns Pocket-recorded voice memos into running Claude tasks, with WhatsApp + email notifications. Routes — status, setup, tasks, test, logs, restart, whatsapp on|off, email on|off."
+description: "This skill should be used when the user asks to \"pocket memos\", \"voice memo pipeline\", or \"/ops:ops-pocket\". Pocket voice-memo pipeline command center. Surfaces the watcher → triage → executor → notifier → bridges chain that turns Pocket-recorded voice memos into running Claude tasks, with WhatsApp + email notifications. Routes — status, setup, tasks, test, logs, restart, whatsapp on|off, email on|off."
argument-hint: '[status|setup|tasks|test|logs [N]|restart|whatsapp on|off|email on|off]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-projects/SKILL.md b/claude-ops/skills/ops-projects/SKILL.md
index 8729a8da..e201518f 100644
--- a/claude-ops/skills/ops-projects/SKILL.md
+++ b/claude-ops/skills/ops-projects/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-projects
-description: "This skill should be used when the user asks to \"/ops:ops-projects\", \"run ops-projects\", or \"use ops-projects\". Portfolio dashboard for all GSD-tracked projects. Scans ~/Projects and ~/gsd-workspaces for .planning/ directories, shows phase status, git state, blockers, and next actions for every project. Run /ops projects to see the full portfolio."
+description: "This skill should be used when the user asks to \"portfolio dashboard\", \"gsd projects\", or \"/ops:ops-projects\". Portfolio dashboard for all GSD-tracked projects. Scans ~/Projects and ~/gsd-workspaces for .planning/ directories, shows phase status, git state, blockers, and next actions for every project. Run /ops projects to see the full portfolio."
argument-hint: '[project-alias|--sync|--refresh]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-recap/SKILL.md b/claude-ops/skills/ops-recap/SKILL.md
index dd4045cd..46f9b86d 100644
--- a/claude-ops/skills/ops-recap/SKILL.md
+++ b/claude-ops/skills/ops-recap/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-recap
-description: "This skill should be used when the user asks to \"/ops:ops-recap\", \"run ops-recap\", or \"use ops-recap\". Manage the multi-session recap marquee daemon — a background process that synthesizes a one-line digest across all parallel Claude Code sessions and shell activity, displayed in tmux status-right. Subcommands status/tail/configure/restart."
+description: "This skill should be used when the user asks to \"recap daemon\", \"tmux marquee\", or \"/ops:ops-recap\". Manage the multi-session recap marquee daemon — a background process that synthesizes a one-line digest across all parallel Claude Code sessions and shell activity, displayed in tmux status-right. Subcommands status/tail/configure/restart."
argument-hint: '[status|tail|configure|restart]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-release/SKILL.md b/claude-ops/skills/ops-release/SKILL.md
index 2335a5ad..4ff5ed29 100644
--- a/claude-ops/skills/ops-release/SKILL.md
+++ b/claude-ops/skills/ops-release/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-release
-description: "This skill should be used when the user asks to \"/ops:ops-release\", \"run ops-release\", or \"use ops-release\". Publish a new version of the claude-ops (\"ops\") plugin in one command — bump plugin.json + marketplace.json + package.json, prepend the CHANGELOG, open the release PR, wait for CI, squash-merge it to main, and tag vX.Y.Z. Use when shipping a fix/feature that has already merged to main and you want it published so /ops:ops-update can pull it down. This is the publish side; /ops:ops-update is the consume side."
+description: "This skill should be used when the user asks to \"release the plugin\", \"publish ops version\", or \"/ops:ops-release\". Publish a new version of the claude-ops (\"ops\") plugin in one command — bump plugin.json + marketplace.json + package.json, prepend the CHANGELOG, open the release PR, wait for CI, squash-merge it to main, and tag vX.Y.Z. Use when shipping a fix/feature that has already merged to main and you want it published so /ops:ops-update can pull it down. This is the publish side; /ops:ops-update is the consume side."
argument-hint: '[--type patch|minor|major] [--version X.Y.Z] [--notes "changelog body"] [--no-ai] [--no-docs] [--no-wiki] [--dry-run] [--no-merge] [--no-tag]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-resume/SKILL.md b/claude-ops/skills/ops-resume/SKILL.md
index 6872ca85..395cd089 100644
--- a/claude-ops/skills/ops-resume/SKILL.md
+++ b/claude-ops/skills/ops-resume/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-resume
-description: "This skill should be used when the user asks to \"/ops:ops-resume\", \"run ops-resume\", or \"use ops-resume\". Reopen recently-closed Claude Code sessions, one per Ghostty tab. Finds recent session transcripts in ~/.claude/projects and resumes each in its own new tab via `claude --resume`, from the directory it was running in. macOS + Ghostty only."
+description: "This skill should be used when the user asks to \"resume sessions\", \"reopen ghostty tabs\", or \"/ops:ops-resume\". Reopen recently-closed Claude Code sessions, one per Ghostty tab. Finds recent session transcripts in ~/.claude/projects and resumes each in its own new tab via `claude --resume`, from the directory it was running in. macOS + Ghostty only."
argument-hint: '[-m minutes | -H hours | -n max | --here | --dry-run]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-revenue/SKILL.md b/claude-ops/skills/ops-revenue/SKILL.md
index 922a1bd4..7a81ed5c 100644
--- a/claude-ops/skills/ops-revenue/SKILL.md
+++ b/claude-ops/skills/ops-revenue/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-revenue
-description: "This skill should be used when the user asks to \"/ops:ops-revenue\", \"run ops-revenue\", or \"use ops-revenue\". Revenue and costs tracker. AWS spend via aws ce, credits tracker, project revenue stages. Shows burn rate, runway estimate, credits expiring."
+description: "This skill should be used when the user asks to \"burn rate\", \"runway\", or \"/ops:ops-revenue\". Revenue and costs tracker. AWS spend via aws ce, credits tracker, project revenue stages. Shows burn rate, runway estimate, credits expiring."
argument-hint: '[costs|revenue|credits|runway|all]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-rotate-setup/SKILL.md b/claude-ops/skills/ops-rotate-setup/SKILL.md
index 5409d6d9..41eeb61e 100644
--- a/claude-ops/skills/ops-rotate-setup/SKILL.md
+++ b/claude-ops/skills/ops-rotate-setup/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-rotate-setup
-description: "This skill should be used when the user asks to \"/ops:ops-rotate-setup\", \"run ops-rotate-setup\", or \"use ops-rotate-setup\". Fail-closed legacy Claude setup alias that directs operators to separately approved staged enrollment."
+description: "This skill should be used when the user asks to \"rotate setup\", \"enroll Claude seat\", or \"/ops:ops-rotate-setup\". Fail-closed legacy Claude setup alias that directs operators to separately approved staged enrollment."
argument-hint: ''
allowed-tools:
- Read
diff --git a/claude-ops/skills/ops-rotate/SKILL.md b/claude-ops/skills/ops-rotate/SKILL.md
index 4d86caab..fec07951 100644
--- a/claude-ops/skills/ops-rotate/SKILL.md
+++ b/claude-ops/skills/ops-rotate/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-rotate
-description: "This skill should be used when the user asks to \"/ops:ops-rotate\", \"run ops-rotate\", or \"use ops-rotate\". Alias of /ops:accounts for Claude Max seats (status, rotate-now, list, reauth). Prefer /ops:accounts for multi-provider. Full Claude procedure still in this file's historical detail via ops-accounts router."
+description: "This skill should be used when the user asks to \"rotate Claude\", \"max seats\", or \"/ops:ops-rotate\". Alias of /ops:accounts for Claude Max seats (status, rotate-now, list, reauth). Prefer /ops:accounts for multi-provider. Full Claude procedure still in this file's historical detail via ops-accounts router."
argument-hint: '[status|rotate-now|list|add-account|reauth]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-secret-sync/SKILL.md b/claude-ops/skills/ops-secret-sync/SKILL.md
index 189fd71c..59ac2149 100644
--- a/claude-ops/skills/ops-secret-sync/SKILL.md
+++ b/claude-ops/skills/ops-secret-sync/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-secret-sync
-description: "This skill should be used when the user asks to \"/ops:ops-secret-sync\", \"run ops-secret-sync\", or \"use ops-secret-sync\". Detects and syncs Doppler→GitHub secrets drift. Compares last-updated timestamps between Doppler and GH repo secrets; flags stale GH secrets (>24h behind Doppler); confirms with user before writing any changes. Safe to run in CI or locally."
+description: "This skill should be used when the user asks to \"doppler github secrets\", \"secret drift\", or \"/ops:ops-secret-sync\". Detects and syncs Doppler→GitHub secrets drift. Compares last-updated timestamps between Doppler and GH repo secrets; flags stale GH secrets (>24h behind Doppler); confirms with user before writing any changes. Safe to run in CI or locally."
argument-hint: '[--repo <owner/repo>] [--project <doppler-proj>] [--config <doppler-env>] [--dry-run]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-settings/SKILL.md b/claude-ops/skills/ops-settings/SKILL.md
index d000a4c6..cf491050 100644
--- a/claude-ops/skills/ops-settings/SKILL.md
+++ b/claude-ops/skills/ops-settings/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-settings
-description: "This skill should be used when the user asks to \"/ops:ops-settings\", \"run ops-settings\", or \"use ops-settings\". Post-setup credential manager. Shows current integration status (configured/missing/expired) and lets you update individual credentials without re-running the full setup wizard. Runs a smoke test after each update."
+description: "This skill should be used when the user asks to \"update credentials\", \"ops settings\", or \"/ops:ops-settings\". Post-setup credential manager. Shows current integration status (configured/missing/expired) and lets you update individual credentials without re-running the full setup wizard. Runs a smoke test after each update."
argument-hint: '[integration-name] [--status]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-ship/SKILL.md b/claude-ops/skills/ops-ship/SKILL.md
index 665e6b93..f66d2c1a 100644
--- a/claude-ops/skills/ops-ship/SKILL.md
+++ b/claude-ops/skills/ops-ship/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-ship
-description: "This skill should be used when the user asks to \"/ops:ops-ship\", \"run ops-ship\", or \"use ops-ship\". One-command full release chain for the claude-ops (\"ops\") plugin — sweep and admin-merge every open PR, then publish a new version (bump plugin.json + marketplace.json registry + package.json + CHANGELOG, open release PR, admin-merge, tag), then pull it onto the box. Use when you have one or more merged-ready PRs and want to ship a new published version in a single step instead of merging PRs by hand and then releasing. Combines the PR sweep + /ops:ops-release + /ops:ops-update."
+description: "This skill should be used when the user asks to \"ship ops plugin\", \"merge all PRs and release\", or \"/ops:ops-ship\". One-command full release chain for the claude-ops (\"ops\") plugin — sweep and admin-merge every open PR, then publish a new version (bump plugin.json + marketplace.json registry + package.json + CHANGELOG, open release PR, admin-merge, tag), then pull it onto the box. Use when you have one or more merged-ready PRs and want to ship a new published version in a single step instead of merging PRs by hand and then releasing. Combines the PR sweep + /ops:ops-release + /ops:ops-update."
argument-hint: '[--type patch|minor|major] [--version X.Y.Z] [--notes "changelog body"] [--base BRANCH] [--no-update] [--dry-run]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-social-planner/SKILL.md b/claude-ops/skills/ops-social-planner/SKILL.md
index 4ce658c2..8d6bad63 100644
--- a/claude-ops/skills/ops-social-planner/SKILL.md
+++ b/claude-ops/skills/ops-social-planner/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-social-planner
-description: "This skill should be used when the user asks to \"/ops:ops-social-planner\", \"run ops-social-planner\", or \"use ops-social-planner\". Visual, engine-agnostic planner for all scheduled social posts and ads across every identity and project. Auto-generates the current state of ops-socials + ops-marketing planned content per project, per channel, regardless of posting engine (Typefully, upload-post, Meta, Google Ads), and serves a clean local web UI. Use when the user says social planner, content calendar, what's scheduled, planned posts, show my queue, posting schedule, social dashboard, or runs /ops-social-planner. Read-only — never publishes (mutation stays in /ops-socials + /ops-marketing behind per-message approval)."
+description: "This skill should be used when the user asks to \"content calendar\", \"what is scheduled\", or \"/ops:ops-social-planner\". Visual, engine-agnostic planner for all scheduled social posts and ads across every identity and project. Auto-generates the current state of ops-socials + ops-marketing planned content per project, per channel, regardless of posting engine (Typefully, upload-post, Meta, Google Ads), and serves a clean local web UI. Use when the user says social planner, content calendar, what's scheduled, planned posts, show my queue, posting schedule, social dashboard, or runs /ops-social-planner. Read-only — never publishes (mutation stays in /ops-socials + /ops-marketing behind per-message approval)."
argument-hint: '[--project <id>] [--collect-only] [--port <n>] [--no-open]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-socials/SKILL.md b/claude-ops/skills/ops-socials/SKILL.md
index 4045e5af..02aeac59 100644
--- a/claude-ops/skills/ops-socials/SKILL.md
+++ b/claude-ops/skills/ops-socials/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-socials
-description: "This skill should be used when the user asks to \"/ops:ops-socials\", \"run ops-socials\", or \"use ops-socials\". Public social channels command center — X/Twitter, LinkedIn, Threads, Bluesky, Mastodon. Routes reads via x-research-skill + x-mcp (or mcp__x-mcp__*), posts via Typefully MCP (ban-safe, multi-platform), and LinkedIn voice/craft via linkedin-skills. Stages drafts; never auto-publishes. Use when the user says socials, post, tweet, thread, draft, schedule a post, search X, what is X saying about, AI twitter, AI news, monitor a profile, LinkedIn post, or runs /ops-socials. NOT for private DMs/email/Slack/WhatsApp — those go through /ops-comms."
+description: "This skill should be used when the user asks to \"tweet\", \"post to linkedin\", or \"/ops:ops-socials\". Public social channels command center — X/Twitter, LinkedIn, Threads, Bluesky, Mastodon. Routes reads via x-research-skill + x-mcp (or mcp__x-mcp__*), posts via Typefully MCP (ban-safe, multi-platform), and LinkedIn voice/craft via linkedin-skills. Stages drafts; never auto-publishes. Use when the user says socials, post, tweet, thread, draft, schedule a post, search X, what is X saying about, AI twitter, AI news, monitor a profile, LinkedIn post, or runs /ops-socials. NOT for private DMs/email/Slack/WhatsApp — those go through /ops-comms."
argument-hint: "[intent] | post [text] | thread [hook] --- [body] | search [query] | mentions | what's [@user] saying | analytics [last-7-days] | linkedin [topic]"
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-speedup/SKILL.md b/claude-ops/skills/ops-speedup/SKILL.md
index 60889040..38d99735 100644
--- a/claude-ops/skills/ops-speedup/SKILL.md
+++ b/claude-ops/skills/ops-speedup/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-speedup
-description: "This skill should be used when the user asks to \"/ops:ops-speedup\", \"run ops-speedup\", or \"use ops-speedup\". Cross-platform, hardware-adaptive system optimizer. Auto-detects macOS / Linux / WSL / Windows (MINGW/Cygwin/MSYS2) and CPU/RAM/disk/GPU profile, then picks the right cleanup strategy. Scans reclaimable disk space, memory pressure, runaway processes, startup bloat, network issues. CleanMyMac built into Claude Code."
+description: "This skill should be used when the user asks to \"speed up this mac\", \"clean disk\", or \"/ops:ops-speedup\". Cross-platform, hardware-adaptive system optimizer. Auto-detects macOS / Linux / WSL / Windows (MINGW/Cygwin/MSYS2) and CPU/RAM/disk/GPU profile, then picks the right cleanup strategy. Scans reclaimable disk space, memory pressure, runaway processes, startup bloat, network issues. CleanMyMac built into Claude Code."
argument-hint: '[scan|clean|deep|auto]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-statusline/SKILL.md b/claude-ops/skills/ops-statusline/SKILL.md
index cab2f176..ec3dc56d 100644
--- a/claude-ops/skills/ops-statusline/SKILL.md
+++ b/claude-ops/skills/ops-statusline/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-statusline
-description: "This skill should be used when the user asks to \"/ops:ops-statusline\", \"run ops-statusline\", or \"use ops-statusline\". Statusline command center — preview, configure, switch themes, validate, and reset the Claude Code cockpit statusline. Subcommands: preview, config, theme, doctor, reset."
+description: "This skill should be used when the user asks to \"statusline theme\", \"cockpit\", or \"/ops:ops-statusline\". Statusline command center — preview, configure, switch themes, validate, and reset the Claude Code cockpit statusline. Subcommands: preview, config, theme, doctor, reset."
argument-hint: "[preview|config|theme <name>|doctor|reset]"
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-triage/SKILL.md b/claude-ops/skills/ops-triage/SKILL.md
index eda900ea..c9ebddd0 100644
--- a/claude-ops/skills/ops-triage/SKILL.md
+++ b/claude-ops/skills/ops-triage/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-triage
-description: "This skill should be used when the user asks to \"/ops:ops-triage\", \"run ops-triage\", or \"use ops-triage\". Cross-platform issue triage. Pulls from Sentry (MCP), Linear (MCP), GitHub Issues (gh). Cross-references against code to find already-fixed issues. Auto-resolves fixed ones. Dispatches agents for active issues."
+description: "This skill should be used when the user asks to \"sentry issues\", \"triage github\", or \"/ops:ops-triage\". Cross-platform issue triage. Pulls from Sentry (MCP), Linear (MCP), GitHub Issues (gh). Cross-references against code to find already-fixed issues. Auto-resolves fixed ones. Dispatches agents for active issues."
argument-hint: '[project-alias|sentry|linear|github|all]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-unifi/SKILL.md b/claude-ops/skills/ops-unifi/SKILL.md
index 49dcdf45..95df339f 100644
--- a/claude-ops/skills/ops-unifi/SKILL.md
+++ b/claude-ops/skills/ops-unifi/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-unifi
-description: "This skill should be used when the user asks to \"/ops:ops-unifi\", \"run ops-unifi\", or \"use ops-unifi\". UniFi network command center. Full control across the three official UniFi APIs — Site Manager (cloud multi-site oversight), Network Integration (local per-console device/client control), and Protect Integration (cameras/NVR). Plus a predict mode that flags WAN/AP/client anomalies before they page you. Configure once via /ops:setup."
+description: "This skill should be used when the user asks to \"unifi\", \"cameras\", or \"/ops:ops-unifi\". UniFi network command center. Full control across the three official UniFi APIs — Site Manager (cloud multi-site oversight), Network Integration (local per-console device/client control), and Protect Integration (cameras/NVR). Plus a predict mode that flags WAN/AP/client anomalies before they page you. Configure once via /ops:setup."
argument-hint: '[status|sites|devices|clients|isp|sdwan|protect|snapshot|restart|block|predict|setup]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-update/SKILL.md b/claude-ops/skills/ops-update/SKILL.md
index 69502426..8f6aab65 100644
--- a/claude-ops/skills/ops-update/SKILL.md
+++ b/claude-ops/skills/ops-update/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-update
-description: "This skill should be used when the user asks to \"/ops:ops-update\", \"run ops-update\", or \"use ops-update\". Upgrade the local claude-ops (\"ops\") plugin to the latest published version in one command — refresh the marketplace catalogue, update the installed plugin (with stale-cache force-reinstall fallback), reapply local cache patches, prune every old cache version, rewrite stale version-pinned paths, run per-version migrations, then prompt to reload. Use when the box is on an older plugin version, after a release, or when the cache looks stale."
+description: "This skill should be used when the user asks to \"update ops plugin\", \"upgrade claude-ops\", or \"/ops:ops-update\". Upgrade the local claude-ops (\"ops\") plugin to the latest published version in one command — refresh the marketplace catalogue, update the installed plugin (with stale-cache force-reinstall fallback), reapply local cache patches, prune every old cache version, rewrite stale version-pinned paths, run per-version migrations, then prompt to reload. Use when the box is on an older plugin version, after a release, or when the cache looks stale."
argument-hint: '[--dry-run|--force|--to X.Y.Z|--no-prune|--no-patches|--no-rewrite|--no-localsync]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-voice/SKILL.md b/claude-ops/skills/ops-voice/SKILL.md
index a6225c03..c79e9b21 100644
--- a/claude-ops/skills/ops-voice/SKILL.md
+++ b/claude-ops/skills/ops-voice/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-voice
-description: "This skill should be used when the user asks to \"/ops:ops-voice\", \"run ops-voice\", or \"use ops-voice\". Voice operations — native macOS Phone (Continuity), FaceTime, Zoom, Google Meet, WhatsApp call, Twilio voice + SMS, Bland AI agent calls, ElevenLabs TTS, Whisper transcription. All curl-based, no SDK deps."
+description: "This skill should be used when the user asks to \"make a call\", \"facetime\", or \"/ops:ops-voice\". Voice operations — native macOS Phone (Continuity), FaceTime, Zoom, Google Meet, WhatsApp call, Twilio voice + SMS, Bland AI agent calls, ElevenLabs TTS, Whisper transcription. All curl-based, no SDK deps."
argument-hint: '[phone|facetime|zoom|meet|whatsapp-call|twilio-call|twilio-sms|bland-call|tts|transcribe|setup]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-whatsapp-biz/SKILL.md b/claude-ops/skills/ops-whatsapp-biz/SKILL.md
index e6c69978..5f511739 100644
--- a/claude-ops/skills/ops-whatsapp-biz/SKILL.md
+++ b/claude-ops/skills/ops-whatsapp-biz/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-whatsapp-biz
-description: "This skill should be used when the user asks to \"/ops:ops-whatsapp-biz\", \"run ops-whatsapp-biz\", or \"use ops-whatsapp-biz\". WhatsApp Business Cloud API — send approved template messages at scale, manage templates with approval tracking, and integrate product catalogs. Separate from wacli personal WhatsApp."
+description: "This skill should be used when the user asks to \"whatsapp business\", \"template message\", or \"/ops:ops-whatsapp-biz\". WhatsApp Business Cloud API — send approved template messages at scale, manage templates with approval tracking, and integrate product catalogs. Separate from wacli personal WhatsApp."
argument-hint: '[send-template|list-templates|create-template|check-template|catalog|setup]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops-yolo/SKILL.md b/claude-ops/skills/ops-yolo/SKILL.md
index 5291c449..080e578c 100644
--- a/claude-ops/skills/ops-yolo/SKILL.md
+++ b/claude-ops/skills/ops-yolo/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops-yolo
-description: "This skill should be used when the user asks to \"/ops:ops-yolo\", \"run ops-yolo\", or \"use ops-yolo\". YOLO mode. Spawns 4 parallel C-suite agents (CEO, CTO, CFO, COO). Each analyzes the business from their perspective using ALL available data. Produces unfiltered Hard Truths report. After user types YOLO, autonomously runs the business for a day using /loop."
+description: "This skill should be used when the user asks to \"yolo mode\", \"run the business today\", or \"/ops:ops-yolo\". YOLO mode. Spawns 4 parallel C-suite agents (CEO, CTO, CFO, COO). Each analyzes the business from their perspective using ALL available data. Produces unfiltered Hard Truths report. After user types YOLO, autonomously runs the business for a day using /loop."
argument-hint: '[YOLO|analyze|report]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/ops/SKILL.md b/claude-ops/skills/ops/SKILL.md
index 6355bd6b..9f023d97 100644
--- a/claude-ops/skills/ops/SKILL.md
+++ b/claude-ops/skills/ops/SKILL.md
@@ -1,6 +1,6 @@
---
name: ops
-description: "This skill should be used when the user asks to \"/ops:ops\", \"run ops\", or \"use ops\". Business operations command center. Routes to the right ops command based on what you need — briefing, inbox, fires, projects, comms, triage, linear, revenue, deploy, or yolo mode."
+description: "This skill should be used when the user asks to \"ops command center\", \"/ops:ops\", or \"run the business\". Business operations command center. Routes to the right ops command based on what you need — briefing, inbox, fires, projects, comms, triage, linear, revenue, deploy, or yolo mode."
argument-hint: '[command] [args]'
allowed-tools:
- Bash
diff --git a/claude-ops/skills/people/SKILL.md b/claude-ops/skills/people/SKILL.md
index a798a699..b2bbd919 100644
--- a/claude-ops/skills/people/SKILL.md
+++ b/claude-ops/skills/people/SKILL.md
@@ -1,6 +1,6 @@
---
name: people
-description: "This skill should be used when the user asks to \"/ops:people\", \"run people\", or \"use people\". Sync Apple Contacts to Notion 'People' database. Track last_contacted, relationship_strength, recent_topics, next_nudge_due. Foundation for relationship intelligence — birthdays, anniversaries, overdue-outreach, news-mention nudges."
+description: "This skill should be used when the user asks to \"sync contacts\", \"people database\", or \"/ops:people\". Sync Apple Contacts to Notion 'People' database. Track last_contacted, relationship_strength, recent_topics, next_nudge_due. Foundation for relationship intelligence — birthdays, anniversaries, overdue-outreach, news-mention nudges."
argument-hint: ''
allowed-tools:
- Bash
diff --git a/claude-ops/skills/setup/SKILL.md b/claude-ops/skills/setup/SKILL.md
index 395b5ebb..b58b1f44 100644
--- a/claude-ops/skills/setup/SKILL.md
+++ b/claude-ops/skills/setup/SKILL.md
@@ -56,7 +56,7 @@ Every Bash tool call MUST include a short `description` parameter (5-10 words, e
- All writes go to one of these paths — and nothing else:
- **`$PREFS_PATH`** — per-user preferences + secrets. Resolves to `${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json`. Lives in Claude Code's plugin data dir so it survives plugin reinstalls and version bumps. Never committed to git.
- **`${CLAUDE_PLUGIN_ROOT}/scripts/registry.json`** — per-user project registry (gitignored in the source repo). `mkdir -p` its parent if missing.
- - **`${CLAUDE_PLUGIN_ROOT}/.mcp.json`** — only to add `${user_config.*}` placeholders, never hardcoded tokens.
+ - **`${CLAUDE_PLUGIN_ROOT}/.mcp.json`** — leave empty (`{"mcpServers":{}}`). MCP servers start on demand in host config, not at plugin load. Never hardcoded tokens.
- The user's shell profile (`~/.zshrc` etc.) — append-only, never rewrite.
- At the top of every wizard step, make sure `$PREFS_PATH`'s parent directory exists: `mkdir -p "$(dirname "$PREFS_PATH")"`. Claude Code creates `~/.claude/plugins/data/ops-ops-marketplace/` on plugin install but don't assume.
diff --git a/claude-ops/skills/setup/channels/doppler.md b/claude-ops/skills/setup/channels/doppler.md
index f7e846a0..0018130b 100644
--- a/claude-ops/skills/setup/channels/doppler.md
+++ b/claude-ops/skills/setup/channels/doppler.md
@@ -142,7 +142,7 @@ After the CLI is configured and authenticated, offer to set up the official `@do
[Skip MCP server]
```
-3. **Save token to userConfig**: Write the token to `doppler_token` in the plugin's `userConfig` (this feeds `.mcp.json` at runtime via `${user_config.doppler_token}`). Also save `doppler_project` and `doppler_config` if selected.
+3. **Save token to userConfig**: Write the token to `doppler_token` in the plugin's `userConfig` (and `doppler_project` / `doppler_config` if selected). The plugin `.mcp.json` stays empty — start Doppler MCP on demand (`mcp-toggle` / host `~/.claude.json`), or keep using the Doppler CLI.
4. **Smoke test**: Verify the MCP server can start:
diff --git a/claude-ops/skills/tonight/SKILL.md b/claude-ops/skills/tonight/SKILL.md
index f90858a6..bc7439fc 100644
--- a/claude-ops/skills/tonight/SKILL.md
+++ b/claude-ops/skills/tonight/SKILL.md
@@ -1,6 +1,6 @@
---
name: tonight
-description: "This skill should be used when the user asks to \"/ops:tonight\", \"run tonight\", or \"use tonight\". Evening tomorrow-brief. Reads the Ops Ledger, calendar, and People DB. Surfaces tomorrow's meetings with prep status, birthdays hitting tomorrow, overdue outreach, top 3 priorities, and any unresolved decisions from today. Push notification if anything is genuinely time-sensitive."
+description: "This skill should be used when the user asks to \"tomorrow brief\", \"evening wrap\", or \"/ops:tonight\". Evening tomorrow-brief. Reads the Ops Ledger, calendar, and People DB. Surfaces tomorrow's meetings with prep status, birthdays hitting tomorrow, overdue outreach, top 3 priorities, and any unresolved decisions from today. Push notification if anything is genuinely time-sensitive."
argument-hint: ''
allowed-tools:
- Bash
diff --git a/claude-ops/skills/uninstall/SKILL.md b/claude-ops/skills/uninstall/SKILL.md
index f60173e5..eb23b290 100644
--- a/claude-ops/skills/uninstall/SKILL.md
+++ b/claude-ops/skills/uninstall/SKILL.md
@@ -1,6 +1,6 @@
---
name: uninstall
-description: "This skill should be used when the user asks to \"/ops:uninstall\", \"run uninstall\", or \"use uninstall\". Completely remove claude-ops plugin, all stored credentials, cached files, shell exports, and MCP registrations. Confirms each step before deletion."
+description: "This skill should be used when the user asks to \"uninstall ops\", \"remove claude-ops\", or \"/ops:uninstall\". Completely remove claude-ops plugin, all stored credentials, cached files, shell exports, and MCP registrations. Confirms each step before deletion."
argument-hint: '[--confirm]'
allowed-tools:
- Bash
diff --git a/claude-ops/tests/test-hermes-plugin.sh b/claude-ops/tests/test-hermes-plugin.sh
index 28deafe1..e891296e 100755
--- a/claude-ops/tests/test-hermes-plugin.sh
+++ b/claude-ops/tests/test-hermes-plugin.sh
@@ -25,6 +25,17 @@ else
err "plugin.yaml name must be ops"
fi
+plugin_ver="$(python3 -c "import json; print(json.load(open('$PLUGIN_ROOT/.claude-plugin/plugin.json'))['version'])")"
+hermes_ver="$(awk -F'"' '/^version:/{print $2; exit}' "$HP/plugin.yaml")"
+if [[ -z "$hermes_ver" ]]; then
+ hermes_ver="$(awk '/^version:/{gsub(/[" ]/,""); sub(/^version:/,""); print; exit}' "$HP/plugin.yaml")"
+fi
+if [[ "$plugin_ver" == "$hermes_ver" ]]; then
+ ok "hermes-plugin version matches plugin.json ($plugin_ver)"
+else
+ err "hermes-plugin version '$hermes_ver' != plugin.json '$plugin_ver'"
+fi
+
if [[ -f "$HP/__init__.py" && -f "$HP/RUNTIME.md" ]]; then
ok "__init__.py and RUNTIME.md exist"
else
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 3b8b49a8..9c6345fb 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -96,7 +96,7 @@ claude-ops/
- **`agents/`** — Background worker layer. Agent `.md` files are spawned by skills using the Claude Agent SDK. They have declared resource budgets (model, maxTurns, effort) and memory scopes.
- **`bin/`** — Executable layer. Shell and Node.js scripts that interact with external CLIs (`wacli`, `aws`, `gh`, `doppler`, `gog`) and APIs. Skills and agents call these via Bash tool calls.
- **`scripts/`** — Infrastructure layer. The daemon supervisor, launchd plists, cron scripts, and the project registry live here.
-- **`telegram-server/`** — Bundled MCP server. Provides Telegram access via MTProto (personal account authentication, not bot tokens). Declared in `.mcp.json` and auto-started by Claude Code.
+- **`telegram-server/`** — Bundled Telegram user-auth server (MTProto, not a bot). Not auto-started from `.mcp.json` (that file is empty so sessions do not spawn a stdio MCP each). Started on demand via `/ops:setup` / host config.
- **`hooks/`** — Automation layer. Three lifecycle hooks: SessionStart (welcome + setup check), PreToolUse/Bash (WhatsApp health check), and Stop (cleanup).
- **`tests/`** — Validation layer. Bash scripts that check for committed secrets, skill markdown lint, hook schema validity, and bin script executability. Run via `tests/run-all.sh`.
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 0dad7a44..a28ad499 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -43,46 +43,9 @@ These fields are set through the Claude Code plugin UI (`/plugin` → `ops` →
## MCP Servers (`.mcp.json`)
-Two MCP servers are wired in `.mcp.json` at the plugin root. They read credentials directly from `userConfig` at runtime — no manual file editing is required.
+The plugin root `.mcp.json` is empty on purpose (`{"mcpServers":{}}`). Bundling Telegram / Doppler / desktop-act as per-session stdio servers multiplied processes across every live Claude session. Those servers now start on demand (`mcp-toggle`, `/ops:setup`, host `~/.claude.json`) rather than at plugin load.
-### Telegram MCP Server
-
-```json
-{
- "mcpServers": {
- "telegram": {
- "command": "node",
- "args": ["${CLAUDE_PLUGIN_ROOT}/telegram-server/index.js"],
- "env": {
- "TELEGRAM_API_ID": "${user_config.telegram_api_id}",
- "TELEGRAM_API_HASH": "${user_config.telegram_api_hash}",
- "TELEGRAM_PHONE": "${user_config.telegram_phone}",
- "TELEGRAM_SESSION": "${user_config.telegram_session}"
- }
- }
- }
-}
-```
-
-### Doppler MCP Server
-
-The official `@dopplerhq/mcp-server` provides direct tool access to Doppler secrets. When `doppler_token` is configured in userConfig, Claude can query secrets via `mcp__doppler__*` tools without shelling out to the Doppler CLI.
-
-```json
-{
- "mcpServers": {
- "doppler": {
- "command": "npx",
- "args": ["-y", "@dopplerhq/mcp-server"],
- "env": {
- "DOPPLER_TOKEN": "${user_config.doppler_token}"
- }
- }
- }
-}
-```
-
-The Doppler CLI remains as a fallback for environments where the MCP server is unavailable.
+Telegram user-auth still lives in `claude-ops/telegram-server/`. Doppler uses the Doppler CLI (or an on-demand MCP). desktop-act is the companion plugin. `/ops:ops-mcp` shows what is actually connected.
`CLAUDE_PLUGIN_ROOT` is resolved at runtime to the plugin's installed cache directory. It is also exported into your shell profile by `/ops:setup` so shell scripts can reference it.
diff --git a/installer/README.md b/installer/README.md
index 814d5d3a..cae959de 100644
--- a/installer/README.md
+++ b/installer/README.md
@@ -56,7 +56,7 @@ version: 1
source:
type: git
url: https://github.com/Lifecycle-Innovations-Limited/claude-ops.git
- ref: v3.4.4
+ ref: v3.6.0
agents:
claude: { enabled: true }
diff --git a/installer/src/config.mjs b/installer/src/config.mjs
index 405aa4d6..e209c46a 100644
--- a/installer/src/config.mjs
+++ b/installer/src/config.mjs
@@ -17,7 +17,7 @@ export const DEFAULT_CONFIG = {
source: {
type: "git",
url: "https://github.com/Lifecycle-Innovations-Limited/claude-ops.git",
- ref: "v3.4.4",
+ ref: "v3.6.0",
},
agents: {
claude: { enabled: true, type: "marketplace" },