feat(plugin): add setup skill — guided watchmen install across agents

README.md

@@ -139,6 +139,18 @@ watchmen statusline install
 
 You then get `/skills brief` (or `$brief`) inside Codex with the same workspace digest behavior as `/watchmen:brief` in Claude Code. Codex has no statusline, so the live skill-suggestion hint is on-demand `brief` instead.
 
+### Guided setup skill
+
+Once the plugin is installed, `/watchmen:setup` (Claude Code) or `$setup` (Codex) walks the whole flow above for you — install check, the `init` wizard hand-off, the `/plugin` steps, statusline, and a closing `watchmen doctor`. Handy for wiring a second agent, repairing, or verifying an install.
+
+To use it on a fresh machine *before* any plugin exists, drop the skill in standalone first, then start a new Claude Code session and run `/setup`:
+
+```bash
+mkdir -p ~/.claude/skills/setup
+curl -fsSL https://raw.githubusercontent.com/firstbatchxyz/watchmen/main/plugin/skills/setup/SKILL.md \
+  -o ~/.claude/skills/setup/SKILL.md
+```
+
 ## Requirements
 
 - macOS, Linux, or Windows 10/11

plugin-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "watchmen",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Skill suggestions + workspace context from your watchmen sessions corpus, surfaced into Codex sessions.",
   "author": {
     "name": "Dria",

plugin-codex/skills/setup/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: setup
+description: Set up watchmen end-to-end for the current machine — install the CLI, run the init wizard, wire the plugin into Codex (and Claude Code), and verify the install with doctor. Use when someone wants to install, onboard, or configure watchmen with their coding agent.
+---
+
+# Set up watchmen
+
+You are guiding the user through installing and wiring watchmen on this machine. watchmen is a local CLI that turns past coding-agent sessions into a curated skills library and surfaces it back into new sessions. This skill is a thin orchestrator: you run the non-interactive shell steps yourself, and for the steps that are interactive (the `init` wizard) or that only the agent UI can do (plugin install), you give the user the exact commands and wait.
+
+Do not touch the user's API keys or credentials directly — the `init` wizard handles provider auth. Never paste a key on the user's behalf.
+
+## Before you start
+
+Check what's already here so you don't redo work:
+
+!`uname -s; command -v uv >/dev/null && echo "uv: $(uv --version)" || echo "uv: MISSING"; command -v watchmen >/dev/null && echo "watchmen: $(watchmen --version 2>/dev/null)" || echo "watchmen: not installed"`
+
+Read that output and branch:
+
+- **`uv: MISSING`** → stop and tell the user to install uv first (`curl -LsSf https://astral.sh/uv/install.sh | sh`, or `brew install uv`), then re-run this skill. uv is the only hard prerequisite besides a provider credential.
+- **watchmen already installed** → skip to step 3 (verify) and only fix what `doctor` flags. Don't reinstall over a working setup.
+- **Fresh machine** → walk steps 1 → 4 in order.
+
+## 1. Install the CLI
+
+watchmen installs as an editable `uv` tool from a clone, so `git pull` + the daemon pick up updates:
+
+```bash
+git clone https://github.com/firstbatchxyz/watchmen.git
+cd watchmen
+uv sync && uv tool install --editable .
+```
+
+Run these for the user (pick a sensible parent dir, or ask where they want the clone). If the clone already exists, `cd` into it and just run the `uv sync && uv tool install --editable .` line.
+
+## 2. Run the init wizard (interactive — hand off)
+
+`watchmen init` is an interactive wizard: it asks which LLM provider to use (OpenRouter / OpenAI / Anthropic, or an OAuth subscription on macOS), prompts for that provider's API key, ingests `~/.claude/projects/` history, lets the user pick projects, previews cost, runs analyze + curate, and installs the daemon + viewer for autostart.
+
+You can't drive an interactive prompt cleanly, so **tell the user to run it themselves** in their terminal:
+
+```bash
+watchmen init
+```
+
+Wait for them to confirm it finished before continuing. If they'd rather skip the wizard and just install the background services with defaults, `watchmen up` is the non-interactive equivalent (no provider/project picking) — but they'll still need a provider credential set via `watchmen settings api-key` or an OAuth login.
+
+## 3. Wire the plugin into the agent (agent UI — hand off)
+
+The plugin (skill suggestions + the `brief` digest) installs through the agent's own plugin system, which you cannot invoke from here. Give the user the exact commands for whichever agent(s) they use and ask them to paste them.
+
+**Codex:**
+
+```
+/plugins marketplace add github:firstbatchxyz/watchmen
+/plugins install watchmen
+```
+
+You then get `/skills brief` (or `$brief`) inside Codex with the workspace digest. Codex has no statusline, so the skill-suggestion hint is on-demand `brief` instead of a live indicator.
+
+**Claude Code:**
+
+```
+/plugin marketplace add firstbatchxyz/watchmen
+/plugin install watchmen@watchmen
+/reload-plugins
+```
+
+Then the statusLine, one-time (Claude Code only): `watchmen statusline install`.
+
+If watchmen was already installed and you're updating it, the refresh path is `/plugins marketplace update watchmen` then reinstall — the plugin only re-caches when its version changes.
+
+## 4. Verify
+
+Run doctor and read it back to the user:
+
+!`watchmen doctor 2>&1 | tail -20`
+
+Walk the ✓/✗/! lines. Common follow-ups:
+
+- **viewer not responding** → `watchmen viewer install`
+- **hooks not wired** → `watchmen hooks install`
+- **API key invalid/missing** → `watchmen settings provider` to check, `watchmen settings api-key --provider <p>` to fix
+- **no corpus / 0 sessions** → they haven't run `watchmen init` (or `watchmen ingest`) yet
+
+Close with a one-line "you're set up" summary and point them at `watchmen status` for the daily view and `watchmen --help` for the full command surface. Keep the whole interaction tight; only dig into a step if it failed.

plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "watchmen",
   "description": "Surface skill suggestions + workspace context from watchmen sessions intelligence into your Claude Code sessions",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "author": {
     "name": "dria",
     "url": "https://github.com/firstbatchxyz/watchmen"

plugin/skills/setup/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: setup
+description: Set up watchmen end-to-end for the current machine — install the CLI, run the init wizard, wire the plugin + statusline into Claude Code (and Codex), and verify the install with doctor. Use when someone wants to install, onboard, or configure watchmen with their coding agent.
+allowed-tools:
+  - Bash(uname*)
+  - Bash(which*)
+  - Bash(command -v*)
+  - Bash(uv*)
+  - Bash(git clone*)
+  - Bash(watchmen*)
+---
+
+# Set up watchmen
+
+You are guiding the user through installing and wiring watchmen on this machine. watchmen is a local CLI that turns past coding-agent sessions into a curated skills library and surfaces it back into new sessions. This skill is a thin orchestrator: you run the non-interactive shell steps yourself, and for the steps that are interactive (the `init` wizard) or that only the agent UI can do (`/plugin`), you give the user the exact commands and wait.
+
+Do not touch the user's API keys or credentials directly — the `init` wizard handles provider auth. Never paste a key on the user's behalf.
+
+## Before you start
+
+Check what's already here so you don't redo work:
+
+!`uname -s; command -v uv >/dev/null && echo "uv: $(uv --version)" || echo "uv: MISSING"; command -v watchmen >/dev/null && echo "watchmen: $(watchmen --version 2>/dev/null)" || echo "watchmen: not installed"`
+
+Read that output and branch:
+
+- **`uv: MISSING`** → stop and tell the user to install uv first (`curl -LsSf https://astral.sh/uv/install.sh | sh`, or `brew install uv`), then re-run this skill. uv is the only hard prerequisite besides a provider credential.
+- **watchmen already installed** → skip to step 3 (verify) and only fix what `doctor` flags. Don't reinstall over a working setup.
+- **Fresh machine** → walk steps 1 → 4 in order.
+
+## 1. Install the CLI
+
+watchmen installs as an editable `uv` tool from a clone, so `git pull` + the daemon pick up updates:
+
+```bash
+git clone https://github.com/firstbatchxyz/watchmen.git
+cd watchmen
+uv sync && uv tool install --editable .
+```
+
+Run these for the user (pick a sensible parent dir, or ask where they want the clone). If the clone already exists, `cd` into it and just run the `uv sync && uv tool install --editable .` line.
+
+## 2. Run the init wizard (interactive — hand off)
+
+`watchmen init` is an interactive wizard: it asks which LLM provider to use (OpenRouter / OpenAI / Anthropic, or an OAuth subscription on macOS), prompts for that provider's API key, ingests `~/.claude/projects/` history, lets the user pick projects, previews cost, runs analyze + curate, and installs the daemon + viewer for autostart.
+
+You can't drive an interactive prompt cleanly, so **tell the user to run it themselves** in their terminal:
+
+```bash
+watchmen init
+```
+
+Wait for them to confirm it finished before continuing. If they'd rather skip the wizard and just install the background services with defaults, `watchmen up` is the non-interactive equivalent (no provider/project picking) — but they'll still need a provider credential set via `watchmen settings api-key` or an OAuth login.
+
+## 3. Wire the plugin into the agent (agent UI — hand off)
+
+The plugin (skill suggestions + the `/watchmen:brief` digest) installs through the agent's own plugin system, which you cannot invoke from here. Give the user the exact commands for whichever agent(s) they use and ask them to paste them.
+
+**Claude Code:**
+
+```
+/plugin marketplace add firstbatchxyz/watchmen
+/plugin install watchmen@watchmen
+/reload-plugins
+```
+
+Then the statusLine (this one you can run for them):
+
+```bash
+watchmen statusline install
+```
+
+**Codex:**
+
+```
+/plugins marketplace add github:firstbatchxyz/watchmen
+/plugins install watchmen
+```
+
+(Codex has no statusline; the digest is on-demand via `brief` / `$brief` instead.)
+
+If watchmen was already installed and you're updating it, the refresh path is `/plugin marketplace update watchmen` then reinstall — the plugin only re-caches when its version changes.
+
+## 4. Verify
+
+Run doctor and read it back to the user:
+
+!`watchmen doctor 2>&1 | tail -20`
+
+Walk the ✓/✗/! lines. Common follow-ups:
+
+- **viewer not responding** → `watchmen viewer install`
+- **hooks not wired** → `watchmen hooks install`
+- **API key invalid/missing** → `watchmen settings provider` to check, `watchmen settings api-key --provider <p>` to fix
+- **no corpus / 0 sessions** → they haven't run `watchmen init` (or `watchmen ingest`) yet
+
+Close with a one-line "you're set up" summary and point them at `watchmen status` for the daily view and `watchmen --help` for the full command surface. Keep the whole interaction tight; only dig into a step if it failed.