greprag 5.13.0 → 5.15.0

package/skill/greprag/SKILL.md

@@ -1,720 +1,120 @@
 ---
 name: greprag
 description: |
-  GrepRAG — agentic setup + Odyssey (episodic project memory).
+  GrepRAG — agentic setup + memory (episodic project memory, marketed as Odyssey).
 
   Single entry point. Runs `greprag status` to learn what's configured,
   walks the user through any missing setup (email signup, hooks, project
-  anchor), then surfaces the current project's Odyssey briefing via
-  `greprag odyssey briefing`.
+  anchor), then either searches the project's memory for the operator's
+  topic (`greprag memory search "<query>"`) or surfaces the recap
+  (`greprag memory recap`) for an open-ended catch-up.
 
   Use when: "/greprag", "set up greprag", "greprag status", "configure
-  memory", "memory briefing", "Odyssey briefing", "catch me up", "what
-  did we do last week", "what's been happening in this project",
-  "session context".
+  memory", "memory recap", "memory search", "Odyssey briefing", "catch me
+  up", "what did we do last week", "what's been happening in this
+  project", "find that bug we hit", "search memory for X", "session
+  context".
 metadata:
   author: travsteward
-  version: "3.8.0"
+  version: "3.9.0"
   repository: https://github.com/travsteward/greprag
 license: MIT
 ---
 
 # GrepRAG Advisor
 
-The agent drives all setup and runs the briefing. Single source of truth: `greprag status --json`.
+Single source of truth: `greprag status --json`. Check it → fix any gaps via `docs/setup.md` → search or recap the project's memory.
 
-### OpenCode vs Claude Code
+OpenCode users: see `docs/setup.md § opencode` for plugin install (`greprag init --opencode`).
 
-- **Claude Code**: hooks in `~/.claude/settings.json` + advisor skill — follow steps 1-6 below.
-- **OpenCode**: plugin at `~/.config/opencode/plugins/greprag-memory.ts` runs silently (injects recap via system prompt, stores turns automatically). The `/greprag` skill works on-demand in both. Run `greprag init --opencode` once to install.
-- Both share the same anchor (`.claude/project.json` or `.opencode/project.json`) and the same API key.
-
-## Step 1 — Get the status
+## Step 1 — Status
 
 ```bash
 greprag status --json
 ```
 
-Parse the JSON. The keys to check, in this order:
-
+Parse JSON. Inspect in order:
 1. `auth.api_key_present`
 2. `project.anchor_found`
 3. `project.memory_capture`, `project.session_start_recap`, `project.inbox_notify`
 
-For Claude Code, also check `hooks.session_start_recap`, `hooks.stop_store`, `hooks.post_tool_use_spawn_reminder`. (The legacy `user_prompt_submit_notify` hook was removed in v5.6.1 — live inbox delivery is now the Monitor watcher's job. Don't install it.)
+For Claude Code, also: `hooks.session_start_recap`, `hooks.stop_store`, `hooks.post_tool_use_spawn_reminder`.
 
-Also check the chip-spawn pointer is installed in global CLAUDE.md (Step 3b):
+Chip-spawn convention marker (in `~/.claude/CLAUDE.md`):
 ```bash
-if grep -q "greprag-conventions:start v5" ~/.claude/CLAUDE.md; then echo CONV_V5
-elif grep -q "greprag-conventions:start v4" ~/.claude/CLAUDE.md; then echo CONV_V4_NEEDS_UPGRADE
-elif grep -q "greprag-conventions:start v3" ~/.claude/CLAUDE.md; then echo CONV_V3_NEEDS_UPGRADE
-elif grep -q "greprag-conventions:start v2" ~/.claude/CLAUDE.md; then echo CONV_V2_NEEDS_UPGRADE
-elif grep -q "greprag-conventions:start v1" ~/.claude/CLAUDE.md; then echo CONV_V1_NEEDS_UPGRADE
+if grep -q "greprag-conventions:start v5" ~/.claude/CLAUDE.md; then echo CONV_OK
+elif grep -qE "greprag-conventions:start v[1-4]" ~/.claude/CLAUDE.md; then echo CONV_OUTDATED
 else echo CONV_MISSING; fi
 test -f ~/.claude/docs/chip-spawn.md && echo DOC_OK || echo DOC_MISSING
 ```
 
-Also check the permission allowlist (Step 3c):
+Monitor permission:
 ```bash
 node -e "const s=JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude/settings.json','utf8'));const a=(s.permissions&&s.permissions.allow)||[];console.log(a.includes('Monitor')?'MON_OK':'MON_MISSING')"
 ```
 
-For each gap, walk the user through the fix. When everything is configured, skip to Step 6 (briefing).
-
-## Step 2 — Auth (only if `auth.api_key_present === false`)
-
-The user has no API key yet. Run the email OTP signup:
-
-1. Ask for their email. If `userEmail` is in conversation context (CLAUDE.md, profile), use that and confirm.
-
-2. Request the code:
-   ```bash
-   curl -sf -X POST "https://api.greprag.com/v1/auth/request-code" \
-     -H "Content-Type: application/json" \
-     -d "{\"email\":\"<EMAIL>\"}"
-   ```
-
-3. Read the verification email via the `gmail` skill. Find the most recent message from `noreply@greprag.com` with subject "Your GrepRAG verification code". Extract the 6-digit code. Retry once after 10 seconds if not present.
-
-4. Verify and capture the key:
-   ```bash
-   curl -sf -X POST "https://api.greprag.com/v1/auth/verify-code" \
-     -H "Content-Type: application/json" \
-     -d "{\"email\":\"<EMAIL>\",\"code\":\"<6-DIGIT-CODE>\"}"
-   ```
-   Response: `{"ok":true,"apiKey":"grp_live_...","userId":"...","tenantId":"..."}`.
-
-5. Write the key into `~/.claude/settings.json` under `env.GREPRAG_API_KEY`. Also set `env.MEMORY_HOOK_ENABLED = "true"`. (Read the file, edit the JSON in-place, write it back.)
-
-Re-run `greprag status --json` and continue.
-
-## Step 3 — Hooks (only if either hook is `false`)
-
-Edit `~/.claude/settings.json` to add the missing hook(s):
-
-- **SessionStart recap** (under `hooks.SessionStart`):
-  ```json
-  { "matcher": "", "hooks": [{ "type": "command", "command": "greprag-hook recap", "timeout": 3000 }] }
-  ```
-- **Stop store** (under `hooks.Stop`):
-  ```json
-  { "matcher": "", "hooks": [{ "type": "command", "command": "greprag-hook store", "timeout": 10000 }] }
-  ```
-- **PreToolUse pre-spawn-check** (under `hooks.PreToolUse`):
-  ```json
-  { "matcher": "mcp__ccd_session__spawn_task", "hooks": [{ "type": "command", "command": "greprag-hook pre-spawn-check", "timeout": 3000 }] }
-  ```
-  Fires BEFORE every `spawn_task` chip dispatch and validates the call against three machine-checkable rules from `~/.claude/CLAUDE.md § Chip Spawning`: title prefix `Chip: `, Block 1 (`git worktree add` in prompt), Block 2 (`greprag send` in prompt). Returns `permissionDecision: "deny"` with remediation when any rule fails; the agent re-composes the call.
-
-Append the missing entries to the existing arrays (create the arrays if absent). Don't overwrite existing hooks from other tools.
-
-**Removing the legacy PostToolUse spawn-reminder hook** (only on upgrade from v0.x → v0.12+): if `~/.claude/settings.json` `hooks.PostToolUse` contains an entry with `matcher: "mcp__ccd_session__spawn_task"` and `command: "greprag-hook spawn-reminder"`, delete that entry. The behavior it carried (arming a Monitor watcher) is now ambient — SessionStart auto-arms the watcher in every greprag-enabled session, so the PostToolUse reminder is vestigial and the underlying subcommand was removed in v0.12.
-
-## Step 3b — Convention install (only if marker missing or out-of-date)
-
-Two pieces install together:
-
-1. A single loud pointer line in `~/.claude/CLAUDE.md` — always loaded into every session's context.
-2. The actual chip-spawn protocol at `~/.claude/docs/chip-spawn.md` — read on demand by the agent when about to call `spawn_task`.
-
-The pointer is short by design: the body costs zero tokens per session that never spawns a chip, the agent reads the doc only when about to act. The PreToolUse `pre-spawn-check` hook enforces title + Block 1/2 at the tool boundary, so an agent that skips the doc still can't ship a bad chip.
-
-Detect first:
-```bash
-if grep -q "greprag-conventions:start v5" ~/.claude/CLAUDE.md; then echo V5
-elif grep -q "greprag-conventions:start v4" ~/.claude/CLAUDE.md; then echo V4_UPGRADE
-elif grep -q "greprag-conventions:start v3" ~/.claude/CLAUDE.md; then echo V3_UPGRADE
-elif grep -q "greprag-conventions:start v2" ~/.claude/CLAUDE.md; then echo V2_UPGRADE
-elif grep -q "greprag-conventions:start v1" ~/.claude/CLAUDE.md; then echo V1_UPGRADE
-else echo MISSING; fi
-test -f ~/.claude/docs/chip-spawn.md && echo DOC_OK || echo DOC_MISSING
-```
-
-**If `MISSING`**, insert the v5 block into `~/.claude/CLAUDE.md` immediately after the `## Inbox` section (use the Edit tool, marker comments verbatim):
-
-```markdown
-<!-- greprag-conventions:start v5 -->
-**CHIP SPAWN METHOD** → before calling `spawn_task`, read `~/.claude/docs/chip-spawn.md`. Non-negotiable.
-<!-- greprag-conventions:end v5 -->
-```
-
-**If `V4_UPGRADE`**, replace the entire `<!-- greprag-conventions:start v4 -->` … `<!-- greprag-conventions:end v4 -->` block (inclusive of markers) with the v5 single-line pointer above. Tell the user "Upgrading greprag-conventions v4 → v5 (moves the inline body to ~/.claude/docs/chip-spawn.md; CLAUDE.md now carries only a loud pointer read on demand)."
-
-**If `V3_UPGRADE`, `V2_UPGRADE`, or `V1_UPGRADE`**, same replacement pattern: delete the old block (markers inclusive) and insert the v5 pointer above. Tell the user "Upgrading greprag-conventions v{1|2|3} → v5."
-
-**Also on any upgrade from v1/v2/v3 → v5**, delete the legacy deep doc if it exists (its content lives at the new `chip-spawn.md` path now):
-```bash
-rm -f ~/.claude/docs/agent-coordination.md
-```
-
-**If `DOC_MISSING`**, the chip-spawn protocol doc must be installed at `~/.claude/docs/chip-spawn.md`. `greprag init` copies it from the npm package on install; if it's missing here, re-run `greprag init` (`init` is idempotent and will re-copy the template). The doc is the body the pointer line references — without it the agent has nothing to read.
-
-Re-run the grep to confirm install. Markers must stay verbatim — they're how subsequent `/greprag` runs detect "already installed" and skip this step.
-
-## Step 3c — Permission allowlist (only if `MON_MISSING` from Step 1)
-
-Without `Monitor` in the allowlist, every inbox-watcher firing prompts the user to approve. That breaks the reply-listening convention — chip and parent sessions both arm watchers as background tasks, and a permission dialog mid-task drops the agent out of flow.
-
-Read `~/.claude/settings.json` and confirm `permissions.allow` contains `"Monitor"`. If not, add it. Recommended baseline for greprag users:
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "Bash(*)",
-      "Monitor",
-      "Read", "Edit", "Write", "Grep", "Glob",
-      "WebFetch", "WebSearch", "Skill", "Agent", "Task"
-    ]
-  }
-}
-```
-
-`Bash(*)` already covers `greprag inbox`, `greprag send`, `greprag retract`, `greprag watch` etc. — no per-command allow entries needed once Bash is broadly trusted. `Monitor` is the missing piece, because it's its own tool (not Bash) and prompts independently.
-
-If the user has a tighter Bash policy (no `Bash(*)`), the per-command minimum for greprag is:
-- `Bash(greprag *)` — covers send, inbox, retract, watch, status, discover
-- `Bash(greprag-hook *)` — covers the hook commands installed in Step 3
-- `Monitor` — inbox watchers
-
-Tell the user the change you're proposing before editing settings.json. Don't silently broaden their permission posture.
-
-## Step 3d — Channel plugins (if user has Discord / Telegram / iMessage plugins enabled)
-
-Adjacent gotcha worth surfacing during setup. Check whether any channel plugin is enabled in either global or any project `settings.json`:
-
-```bash
-grep -lE '"(discord|telegram|imessage|fakechat)@claude-plugins-official":\s*true' \
-  ~/.claude/settings.json \
-  $(find . -maxdepth 3 -path '*/.claude/settings.json' 2>/dev/null) 2>/dev/null
-```
-
-If any match: tell the user that channel push delivery requires the `--channels` flag at session launch — being in `settings.json` and `.mcp.json` is not enough. Specifically:
-
-- **Setting enables the MCP server to load** → its tools (e.g. `reply`, `fetch_messages`) become available.
-- **`--channels plugin:<name>@<marketplace>` at launch enables push** → inbound `notifications/claude/channel` events surface as `<channel>` blocks in the session context.
-
-Without `--channels`, the bot can be DM'd and the bun server receives the event, but Claude Code's harness filters it out. Users observe "typing indicator fires, then bot times out without replying."
-
-The flag is hidden from `claude --help` on 2.1.149 (research preview) but accepted on 2.1.80+. **FleetView / Claude Desktop's CCD launcher does not pass `--channels`** — push delivery only works from terminal-launched sessions. Recommend the user launch one terminal-rooted Claude session in the project where the plugin is enabled:
-
-```bash
-cd <project-with-plugin>
-claude --channels plugin:discord@claude-plugins-official
-```
-
-FleetView sessions can still call the plugin's REST tools as a polling workaround, but the realtime path is terminal-only until the launcher catches up.
-
-Also recommend: scope the plugin to a single project's `.claude/settings.json`, not global. Discord allows exactly one gateway connection per bot token; if multiple sessions all have the plugin enabled, the bun servers race for the token and Discord drops all but one.
-
-## Step 4 — Project anchor (only if `project.anchor_found === false`)
-
-The current folder has no `.claude/project.json`. Ask the user:
-
-> "GrepRAG isn't set up for this project yet. Set up memory for this folder? (y/n)"
-
-If yes, ask three preferences:
-- "Capture turns into memory here? (y/n)" → `memory_capture`
-- "Inject the recap briefing at SessionStart here? (y/n)" → `session_start_recap`
-- "How should this project handle inbox notifications? (1) every turn (recommended) / (2) only at session start / (3) off" → `inbox_notify`: `every_turn` | `session_start_only` | `off`
-
-**Path heuristic**: if `project.cwd` contains `AppData/Roaming/Claude/local-agent-mode-sessions/` or starts with `/tmp/` or `/var/tmp/`, the cwd is an ephemeral session path. Tell the user:
-
-> "This looks like an ephemeral Claude session directory. Anchor here (won't persist across sessions) or at the stable parent (persists)? (1=here, 2=stable parent)"
-
-If they pick stable parent, walk up to the nearest stable directory (e.g., `~/AppData/Roaming/Claude/` on Windows, `~` on Unix) and place the anchor there.
-
-If `project.is_deterministic_fallback === true` AND there's existing memory under that UUID (check via `curl -sf "https://api.greprag.com/v1/memory/by-period?projectId=<project_id>&from=2020-01-01T00:00:00Z&to=$(date -u +%Y-%m-%dT%H:%M:%SZ)&limit=1" -H "Authorization: Bearer ${GREPRAG_API_KEY}"` — if `count > 0`), ask:
-
-> "Found existing memory under this folder's implicit UUID. Reuse it to keep continuity? (y/n)"
-
-If yes, use the existing `project_id` in the new anchor file. If no, mint a fresh UUID via `node -e "console.log(crypto.randomUUID())"`.
-
-Write the file:
-```bash
-mkdir -p <cwd>/.claude
-cat > <cwd>/.claude/project.json <<EOF
-{
-  "project_id": "<UUID>",
-  "project_name": "<basename, lowercased>",
-  "memory_capture": <true|false>,
-  "session_start_recap": <true|false>,
-  "inbox_notify": "<every_turn|session_start_only|off>",
-  "created": "<ISO-NOW>"
-}
-EOF
-```
-
-Then register the anchor with the server so inbox addressing (`<email>/<project_name>`) resolves:
-```bash
-curl -sf -X POST "https://api.greprag.com/v1/inbox/projects/register" \
-  -H "Authorization: Bearer ${GREPRAG_API_KEY}" \
-  -H "Content-Type: application/json" \
-  -d "{\"project_id\":\"<UUID>\",\"project_name\":\"<basename>\"}"
-```
-
-If registration returns 409 (project_name conflict with another project under this tenant), ask the user for a unique handle and retry.
-
-## Step 5 — Per-project flags (when the user asks to flip them)
-
-If the user says "turn off recaps here", "stop capturing memory in this folder", or "only notify me of inbox at session start":
-
-1. Read `<anchor_path>` from status
-2. Edit the JSON in-place — flip `memory_capture`, `session_start_recap`, or `inbox_notify`
-3. Write it back
-
-Hooks honor these flags on next fire — no restart needed.
-
-## Step 5b — Inbox operations
-
-When the user asks "check my inbox", "any messages?", or runs `/greprag inbox`:
-
-```bash
-greprag inbox            # list unread (auto-marks read)
-greprag inbox --all      # full history
-greprag inbox keep <id>  # extend a read message's TTL
-greprag inbox delete <id>
-```
-
-To send a plain message:
-```bash
-greprag send "<markdown body>" --to <address>
-```
-
-`send` prints two lines on success — the delivered-to confirmation **and a retract code**:
-```
-Sent to alice@greprag.com/abc12345  (a7f3c5e2)
-Retract: greprag retract K9M2X4P7QV
-```
-The retract code lets the sender pull the message back without layering follow-up "SUPERSEDES" notes on top. See Step 5d.
-
-To send a **rich message** with back-pointers — preferred whenever the message refers to a memory row, a shipped artifact, or specific code lines:
-```bash
-greprag send "Quick heads up — the auth bug I described yesterday repros here." \
-  --to alice@greprag.com/abc12345 \
-  --memory 04f3e0d4-aa12-44ef-9a01-bb3df2c7e911 \
-  --file src/auth/handler.ts:42 \
-  --file src/middleware/check.ts:10-15 \
-  --artifact commit:7a4d35b \
-  --artifact pr:#42
-```
-
-Flags (all repeatable, all optional):
-- `--memory <uuid>` — point to a memory row (turn, ship event, episodic summary)
-- `--artifact <type:id>` — point to a shipped thing. Types: `commit`, `pr`, `deploy`, `release`, `push`, `merge`
-- `--file <path[:lines]>` — point to a code location. Lines are `42` or `10-15`
-- `--ref-json '<json>'` — escape hatch for a fully-formed references object (mutually exclusive with the above)
-- `--from-session <id>` — sender's own session UUID. Denormalized onto the message so the recipient learns your session and can address replies back without re-discovery. Use whenever you expect a reply.
-
-The target lives in the `--to` address itself (see "Address formats" below). The legacy `--session` and `--project` flags were removed in v0.11 — passing them now errors out with a migration hint.
-
-**When to populate references vs. when to leave them off:**
-- Short chat messages ("pinging you", "deploy is up", "ack") — no references, just body.
-- Bug reports, follow-ups, design decisions — always add the specific code lines (`--file`) and any ship event that's relevant (`--artifact`).
-- Cross-referencing prior memory — pull memory IDs from a `greprag inbox` listing or from the recap and pass via `--memory`. The recipient agent can fetch the row directly.
-- Don't hallucinate references. If you can't name a real file path or artifact ID, leave the flag off.
-
-Address formats (v0.11+):
-
-| Form | Use | Behavior |
-|---|---|---|
-| `<handle>@greprag.com` | What you SHARE | Identity-only / receive form. Errors on send — the bare handle has no target. |
-| `<handle>@greprag.com/<session-uuid>` | What you SEND with (normal) | Targets one specific session. UUID or 8-hex short form. Only that session's watcher receives. |
-| `<handle>@greprag.com/<project-name>` | What you SEND with (rare) | Project-wide broadcast — every watcher in that project receives. Reserve for genuine "everyone in this project should know" messages. |
-| `me` / `self` | Shortcut for your own tenant | Receive form only. |
-
-Disambiguation rule: a single segment after `/` is a session if it matches `[0-9a-f]{8}` (8-hex short form) or full UUID, otherwise a project name. Project names that look like UUIDs are rejected at registration time so this is always unambiguous.
-
-`<handle>` is one of:
-- `1834729@greprag.com` — canonical numeric handle. Opaque, leaks nothing. Get yours from `greprag status --json | jq -r .identity.handle` or `greprag whoami`.
-- `alice@greprag.com` — opt-in vanity alias (claim with `greprag identity claim alice`).
-
-**Real emails are NEVER routing addresses.** `users.email` is auth credential only. If you don't know the recipient's numeric handle, ask the user — don't guess from their email. adr: adr/numeric-handles.md
-
-Session targeting is the default and expected form. Project broadcasts are intentional opt-ins for the rare case where everyone in a project should hear something. adr: adr/address-grammar.md
-
-Auto-read semantics: any message returned by `greprag inbox` (without `--all`) is marked read in the same call. Once read, it stops appearing in notifications. TTL deletes read messages after 14 days. Use `keep` to extend before expiry.
-
-## Step 5c — Watching the inbox (push delivery)
-
-When you've spawned chips that will report back via `greprag send`, or you're waiting on any message that needs to land in real time, run a live SSE watcher instead of polling `greprag inbox` on a heartbeat:
-
-```bash
-greprag inbox watch                       # tenant-wide stream
-greprag inbox watch --project <name>      # only messages addressed to this project
-greprag inbox watch --session <id>        # only messages targeting this session (plus broadcasts)
-greprag inbox watch --since <id-or-iso>   # resume from a known cursor
-greprag inbox watch --json                # emit one JSON object per line (preferred under Monitor)
-```
-
-`--project` and `--session` compose — pass both when a session lives inside a specific project's inbox space. `--session` is the strictest filter: only messages with matching `to_session_id` (or `to_session_id IS NULL` for broadcasts) get through. This is what eliminates cross-session noise when several Claude sessions watch the same project's inbox at once.
-
-Each message arrives within ~500ms of the sender's `greprag send` (210ms verified end-to-end). The connection is held open and auto-reconnects with exponential backoff if the server drops; the watcher tracks the last seen message id and uses it as `since=` on reconnect, so nothing is dropped and nothing is duplicated.
-
-**Liveness model (post v0.8.5):** the server emits an SSE `: ping` comment every 15s. The client tracks time since the last byte and treats 60s of total silence (4 missed pings) as a dead stream — aborts the fetch, reconnects with the preserved cursor, and the server's per-tenant InboxDO replays any rows that landed in the gap from its tail buffer (or backfills from the DB for older gaps). After replay, the server emits an `event: replay-complete` SSE event with the row count so the watcher logs `replayed N missed row(s), resuming live tail` to stderr. Disconnects and reconnect attempts also log to stderr with the cursor — debugging silent gaps no longer requires inspecting the running process. Pre-`fix`, a silently half-open TCP socket would hang the watcher indefinitely with no log; that failure mode is gone, but watcher delivery is still opportunistic — the `UserPromptSubmit` hook remains the correctness guarantee, surfacing any unread messages at the next user turn.
-
-**Two canonical patterns:**
-
-### Parent-side: watch for chip reports BEFORE spawning
-
-```bash
-# Parent arms a Monitor scoped to its own session, then spawns the chip
-# (chip prompt's Block 2 sends with --session <parent-session-id>).
-# Each chip's "done" report becomes one Monitor notification, with no cross-talk
-# from other chips or sessions sharing the parent's project inbox.
-# The while-loop wrapper auto-restarts the SSE process if it dies — a bare
-# `greprag inbox watch` would silently end the Monitor task on any inner crash.
-while true; do greprag inbox watch --session <parent-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
-```
-
-If the parent has no session identity (rare — older sessions before session-scope shipped), fall back to `--project <parent-project>`. The chip then sends without `--session` and the message reaches every watcher under the project.
-
-### Post-send: listen for replies after `greprag send`
-
-Any session that sends a message that could draw a directive in response arms the same watcher on its own inbox in the same turn. Without this, the Stop hook is the only path for the reply to surface — and Stop only fires between user prompts. Mid-task replies are invisible until the next stop boundary.
-
-```bash
-# After: greprag send "..." --to <someone>/<their-project>/<their-session> \
-#                          --from-session <own-session-id>
-# Arm under Monitor (persistent: true):
-while true; do greprag inbox watch --session <own-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
-```
-
-The `--from-session` flag on the outgoing message tells the recipient where to address replies; the `--session` filter on the watcher narrows incoming traffic to messages aimed at this exact session (plus general broadcasts). No more sibling-chip cross-talk and no self-echo from tenant-wide sends.
+## Step 2 — Route gaps to `docs/setup.md`
 
-This is also the Block 3 pattern for chips — see `~/.claude/docs/agent-coordination.md`. The same rule applies to main sessions, advisor sessions, and any other context that pings someone and expects a response.
-
-**Run it under the `Monitor` agent tool, `persistent: true`.** Monitor emits one notification per stdout line — the agent reacts the moment a message lands. **Do NOT use `Bash(run_in_background: true)`** — Bash background notifies only on process completion, and a watcher runs forever, so the agent gets zero events until it manually reads the output file. Confirmed bug, learned the hard way. Stop with `TaskStop` on the Monitor task when the watch is truly no longer needed.
-
-The watcher is the right default whenever you'd otherwise loop `greprag inbox` every N seconds — lower latency, cheaper, doesn't burn quota on empty polls.
-
-## Step 5d — Retracting a message you just sent
-
-`send` returns a retract code (printed after `Retract:` on the second line of the success output). Use it when you realize a message was wrong-framed and want to pull it back instead of stacking a follow-up "SUPERSEDES" note on top:
-
-```bash
-greprag retract <code>
-```
-
-Behavior is decided by the server based on whether the recipient has already read the message:
-
-- **Unread** → the row is hard-deleted. Recipient never sees it. Output: `Retracted (status: deleted — recipient had not read it).`
-- **Read** → message body is replaced with `[RETRACTED BY SENDER at <ts>]`. Recipient still sees the row in `inbox --all`, but the original body is gone. Output: `Marked retracted (status: retracted_after_read — recipient had already read; they'll see the retraction notice in place of the original body).`
-- **Already retracted** → no-op, idempotent. Output: `Already retracted (status: already_retracted — no change).`
-- **Unknown code** → no error, just confirms nothing happened. Output: `Not found (status: not_found — code does not match any message you sent, or the message has already expired).`
-
-**When to retract vs. when to send a SUPERSEDES follow-up:**
-- Just sent it, recipient hasn't read yet, and the framing was wrong? → `greprag retract`. Clean inbox state, zero noise.
-- Recipient has already read it? → `greprag retract` still beats a stacked follow-up — they get a placeholder instead of a confusing stale message — and then send a fresh `greprag send "<corrected message>"` with the right framing.
-- Recipient acted on the message already (committed code, made a decision)? → send a follow-up `SUPERSEDES <old-id>: <correction>` so they have full context on what changed and why. Retract still works alongside this to clean the original.
-
-Retract codes are sender-scoped — your code cannot retract a message someone else sent. Codes stay valid until the message expires (14 days unread, longer if `keep`'d).
-
-## Step 5e — Health & repair (when memory looks wrong)
-
-Triggers: user says "memory looks empty", "I'm missing my history", "fix greprag here", "are there orphans", "consolidate my project IDs"; or `greprag status` reports identity drift; or the session-start recap printed a "[GrepRAG memory: identity drift detected ...]" line.
-
-```bash
-greprag doctor
-```
-
-What it does:
-1. Reads the current project's identity (project_id + which cascade level resolved it — file / git-derived / global / path-hash)
-2. Computes what the git-derived UUID *would* be (if in a git repo with commits)
-3. Queries the API for sibling project_ids under the same profile name (these are the orphans — usually from old anchor files lost to gitignore or a hash-fallback period before init)
-4. Presents the findings and offers actions:
-   - **Migrate to git-derived UUID** (recommended when there's drift) — moves current + orphan rows onto the git-derived ID and strips `project_id` from `.claude/project.json` so identity flows from git history going forward
-   - **Consolidate orphans into current UUID** — keeps the current identity but pulls orphan rows in
-   - **Dry-run** — runs the recommended action through the API with `dry_run: true` so the user sees exactly what would change before committing
-
-Flags:
-- `--inspect` — diagnose only, no prompts (good for "tell me what's wrong here")
-- `--yes` / `-y` — non-interactive; picks the recommended action and runs it
-
-Repair is fully tenant-scoped via the API — `greprag doctor` only ever touches rows under the caller's tenant, and the merge runs in a transaction so a partial failure rolls back cleanly.
-
-## Step 5f — Corpus (upload + search arbitrary text)
-
-Odyssey captures the agent's own work (every turn, hourly/daily/weekly compaction). **Corpus** is the other direction: upload a book, a codebase, a reference doc, a writing-sample library — any text — and search it with lexical grep enriched by write-side vocabulary bridging. Same substrate, same retrieval modes; just a different `kind` on the store.
-
-**Design contract (post-v0.8):** GrepRAG does **no LLM work at read time**. The agent (you) formulate the lexical queries. Write-side enrichment makes "insulted" find archaic "wrongeth" passages via tsvector OR. Read-side does pure SQL: combined field-weighted tsvector + ts_rank_cd + websearch_to_tsquery + adjacency-clustered ranking.
-
-Triggers: "load this book into greprag", "upload the docs", "ingest this PDF" (after they convert it), "search the Marcus Aurelius corpus", "what does the codebase say about X", "find the passage about Y in the book I uploaded".
-
-### Upload
-
-```bash
-greprag corpus upload <file-or-url> [--name "Display Name"] [--kind book]
-```
-
-- `--kind` is organizational metadata. Valid: `book`, `codebase`, `voice`, `generic`. Defaults to `book`. Lets you filter `greprag corpus list --kind codebase` later; doesn't change the enrichment prompt.
-- Enrichment is GR5 phrase-aware, applied uniformly to all corpus kinds — the single Narrow C prompt extracts single-word synonyms (graph expansion) and multi-word phrase variants (concept-level bridging). No per-kind prompt forking.
-- `--name` defaults to the filename basename. Prefer an explicit name — the user references the store by name later.
-- File or URL must be plain text or markdown. PDFs: ask the user to convert first.
-- Cost: one round-trip to ingest + N async Gemini Flash-Lite calls (one per substantive node, drained every 2 min). Read-time cost: $0.
-
-### Search — the chain protocol
-
-Searches are **agent-driven**. You decompose the user's intent into 1–3 lexical queries. There is no server-side intent expansion. The cost of formulation comes from your own token budget (you have the user's context; GrepRAG doesn't).
-
-#### Query operator syntax (websearch_to_tsquery)
-
-The query string accepts these operators:
-
-- `term1 term2` — both required (AND).
-- `term1 OR term2` — either suffices.
-- `"quoted phrase"` — exact adjacent words.
-- `-excluded` — must NOT contain.
-- Parenthesize for grouping: `(insulted OR wronged) -metadata`.
-
-Build queries that bridge the user's modern vocabulary to the corpus register. Stale prompts ("how should I respond when insulted") force every word — useless against archaic text. Decomposed queries ("insulted OR reproach OR contempt") win.
-
-#### Chain — probe, narrow, expand, cross-reference
-
-The optimal access pattern for an open-ended user question:
-
-1. **Probe** — `greprag corpus search "<store>" "<2-3 broad-vocab query>"` to find the topic region.
-2. **Narrow** — if results scatter, refine with `--section "Chapter VII"` or pass tighter query operators and search again.
-3. **Expand** — for each promising hit, `greprag corpus walk "<store>" <nodeId>` to read the surrounding ±2 nodes.
-4. **Cross-reference** — re-search with a new angle if the first probe missed something the read-back suggests.
-
-Each call is ~50–150ms. Two to four calls is normal; don't fear chaining.
-
-#### Single-store search
-
-```bash
-greprag corpus search "<store name or UUID>" "<lexical query>" [--limit 5] [--section "Book VII"] [--shape dialogue]
-```
-
-Each result carries: `nodeId` (stable 8-char anchor), `position`, `headingPath`, `score`, `content`.
-
-#### Multistore search (cross-corpus questions)
-
-```bash
-curl -sf -X POST "$GREPRAG_API_URL/v1/search" \
-  -H "Authorization: Bearer $GREPRAG_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-        "queries": ["insulted OR reproach", "wronged OR injustice"],
-        "storeIds": ["..."],
-        "limit": 8,
-        "adjacencyWindow": 3,
-        "adjacencyAlpha": 0.3,
-        "filters": {"section": "Book VII"}
-      }'
-```
-
-Omit `storeIds` to search every store under the calling tenant. RRF fuses across (store × query) pairs; adjacency boosts surface semantic clusters (a node whose neighbors are also hits ranks higher).
-
-### Walk
-
-```bash
-greprag corpus walk "<store>" <nodeId> [--before 2 --after 2]
-```
-
-Surrounding-context fetch. ~50ms, no LLM.
-
-### List / delete / status
-
-```bash
-greprag corpus list [--kind book]
-greprag corpus status "<store>"          # write-side enrichment progress
-greprag corpus delete "<store>" --yes
-```
-
-### When to reach for corpus vs. Odyssey
-
-| Want to … | Use |
+| Gap | Section |
 |---|---|
-| Pull yesterday's daily summary, last week's weekly | `greprag odyssey briefing` (Step 6 flow) |
-| Ask "what shipped on this branch last week?" | `greprag odyssey ships --last 50` or `odyssey daily --last 7` |
-| Backfill a missed compaction window | `greprag odyssey compact <hour\|day\|week>` |
-| Load a book the user paste-bombed into the chat | `corpus upload` then `corpus search` |
-| Search a codebase the user wants the agent to learn | `corpus upload --kind codebase` |
-| Cross-corpus question across multiple uploads | `POST /v1/search` with omitted `storeIds` |
-
-Odyssey is the agent's own past. Corpus is everything else.
+| `auth.api_key_present === false` | `docs/setup.md § auth` |
+| Any hook is false | `docs/setup.md § hooks` |
+| Convention marker missing/outdated, or `DOC_MISSING` | `docs/setup.md § conventions` |
+| `MON_MISSING` | `docs/setup.md § permissions` |
+| `project.anchor_found === false` | `docs/setup.md § anchor` |
+| Channel plugin enabled but no `--channels` flag | `docs/setup.md § channels` |
 
-## Step 5g — Commander (Discord DM bridge — talk to the user from their phone)
+Re-run `greprag status --json` after each fix. When clean, proceed to Step 3.
 
-For the full operator-facing flow see `/commander` (skill at `~/.claude/skills/commander/SKILL.md`). This section is the orchestrator-side summary so a greprag session can drive the same surface without loading the commander skill explicitly.
+Per-project flag flips (turn off recaps here, etc.): `docs/per-project-flags.md`.
 
-When the user wants to step away from the desk and continue the conversation on their phone, route the thread through the greprag Discord bot. There are two surfaces — one-time pairing (identity) and per-session handoff (active routing). Plus an emergency-router fallback: if the user DMs the bot with no handoff active, the bot auto-links to the most-recently-attached session watcher under their tenant. Tag `references.discord.emergency_route` on the inbox row flags the auto-link; reply with self-identification on first response.
+## Step 3 — Memory access (when configured)
 
-### Pairing (one-time per tenant)
-
-`greprag discord pair` generates a 6-char code. The user DMs `@greprag` on Discord with `/pair <code>`. After that, the user's snowflake is bound to their greprag tenant. DMs from that snowflake land as inbox messages on `default_project_id` (the project they paired from).
-
-You don't run this — it's a one-time setup the user does themselves. Detect "I'm paired" via `greprag discord me`: returns `paired: true` and the pairing's project_name.
-
-### Handoff (per-session routing pin)
-
-The pattern the user almost always means by "let's continue on Discord":
-
-```bash
-greprag discord handoff --ttl 60 --json
-```
-
-Run it under `Monitor` (persistent: true). The command pins DMs from the user's snowflake to (this project, this session) for 60 min, fires a confirmation DM to the user's phone, then **blocks** streaming the session's inbox to stdout as JSON. Each line that prints is one Discord DM landing — Monitor delivers them as notifications right back into your turn. The pin slides forward 30+ min on every inbound, so an active thread stays anchored.
-
-Replies go out via:
-
-```bash
-greprag send --to discord:<snowflake> "your message body"
-```
-
-The CLI handles UTF-8, Discord's 2000-char limit, optional `--ref-json '{"discord":{"reply_to_message_id":"..."}}'` for threading. **Do not use curl for this** — bash on Windows mangles em-dashes / curly quotes / emoji into Win-1252 bytes that render as `?` on Discord. Node fetch (which the CLI uses) is UTF-8 native.
-
-For long agent turns where the auto-typing's 10-second window expires, call `greprag discord typing` between work steps to refresh the indicator. Silent on success.
-
-`greprag discord unhandoff` releases the pin early (DMs revert to default project). Pin also expires naturally via the TTL.
-
-### Canonical handoff flow
-
-User says "let's keep going on Discord" / "DM me" / "I'm stepping out":
-
-1. Confirm pairing with `greprag discord me`. If unpaired, tell the user to run `greprag discord pair` and DM `/pair <code>` first.
-2. Resolve current session_id (`CLAUDE_SESSION_ID` env, or the 8-hex from SessionStart context).
-3. Arm: `Monitor` with command `greprag discord handoff --session <8-hex> --project <name> --ttl 60 --json`, persistent.
-4. Tell the user the pin is live; the bot already DMed them. Each reply from Discord will fire as a Monitor notification.
-5. On each notification, parse the JSON body (`body` field = user's message text). Draft your reply. Send via `greprag send --to discord:<snowflake> "..."`. The snowflake is in `references.discord.snowflake`.
-
-## Step 6 — Briefing (when everything is configured)
-
-The Odyssey briefing is the SessionStart-shaped recap — the most recent weekly summary plus the last seven daily summaries. Use the CLI verb:
+Two access patterns — pick by intent.
 
+**A. Search by topic** — when the operator references a past problem, bug, decision, or topic. Reach for this first.
 ```bash
-greprag odyssey briefing
+greprag memory search "<query>"
 ```
+Query syntax is `websearch_to_tsquery`: AND is default, `OR` explicit, `"phrases"` quoted, `-negation` drops terms. Prints ranked hits (top 5) with node IDs, shape tag, score, content. Flags: `--shape daily`, `--limit 10`, `--format json`.
 
-That prints the markdown briefing directly. The agent surfaces it verbatim. To target another project under the same tenant: `--project <name>`. To pull raw JSON for downstream tooling: `--format json`.
-
-Per-shape access (use these when the briefing isn't what's wanted):
-
+**B. Recap by time** — an open-ended "catch me up". Most recent weekly + last seven daily summaries.
 ```bash
-greprag odyssey daily   --last 7         # newest 7 daily summaries
-greprag odyssey weekly  --last 2         # newest 2 weekly summaries
-greprag odyssey hourly  --last 24        # newest 24 hourly summaries (within last 7 days)
-greprag odyssey turns   --last 20        # raw per-turn envelopes (21-day TTL)
-greprag odyssey ships   --last 50        # ship-event rows (commits/PRs/deploys/releases)
-greprag odyssey compact <hour|day|week>  # manual compaction trigger (backfill / admin)
+greprag memory recap
 ```
+Emit the markdown verbatim — the compactor already shaped it. Do not rewrite or summarize. Other projects: `--project <name>`. Raw JSON: `--format json`.
 
-All accept `--project <name>`, `--from ISO --to ISO`, and `--format markdown|json`. See `greprag odyssey help` for the full list.
-
-If the briefing prints `No episodic rows yet for <project> — compaction runs hourly. Check back after the first active session.`, that's the canonical empty-state message.
-
-Otherwise present what the CLI emitted verbatim. Do not rewrite or summarize — the compactor already shaped it.
-
-**Naming note.** The valid `--type` values for the underlying HTTP endpoint `/v1/memory/by-period` are `turn`, `hourly`, `daily`, `weekly`, `ship-event`. Earlier versions of this doc referenced `episodic-daily` / `episodic-weekly` — those values silently return zero rows because no node ever had that shape. The `greprag odyssey` CLI uses the correct values; prefer the CLI over raw curl.
-
-If the agent absolutely needs raw curl (advanced / scripted use):
+Empty-state output (canonical, do not paraphrase):
+> No episodic rows yet for <project> — compaction runs hourly. Check back after the first active session.
 
+Per-shape pulls (when neither search nor recap fits):
 ```bash
-PROJECT_ID=$(greprag project-id)
-TO=$(node -e "console.log(new Date().toISOString())")
-FROM=$(node -e "const d=new Date(); d.setDate(d.getDate()-7); console.log(d.toISOString())")
-curl -sf "https://api.greprag.com/v1/memory/by-period?projectId=${PROJECT_ID}&from=${FROM}&to=${TO}&type=daily&limit=7" \
-  -H "Authorization: Bearer ${GREPRAG_API_KEY}"
+greprag memory daily   --last 7
+greprag memory weekly  --last 2
+greprag memory hourly  --last 24
+greprag memory turns   --last 20
+greprag memory ships   --last 50
+greprag memory compact <hour|day|week>
 ```
+All accept `--project <name>`, `--from ISO --to ISO`, `--format markdown|json`. See `greprag memory help`.
 
-The route name stays `/v1/memory/by-period` — Odyssey is the user-facing brand, the HTTP surface kept its internal name for compatibility.
-
-## Step 6b — Seeding lore (LEARNINGS substrate)
-
-Lore = what was learned. Project-specific emergent knowledge — gotchas, discovered constraints, drift-prone observations. Distinct from static project knowledge (which belongs in CLAUDE.md / docs / code structure). Whenever you waste tokens *discovering* something a future agent shouldn't have to re-discover, seed it as project lore. Discovery is fine the first time — the failure mode is repeating it every time a chip spawns or a new session opens.
-
-### When to seed
-
-Three signatures of discovery waste — if you see one in your own trace, seed the result so the next agent skips the search:
+Aliases (silent back-compat): `greprag memory briefing` → `recap` (renamed v5.16.0); `greprag odyssey ...` still works for v5.8.0-era scripts. Raw curl + `--type` value catalog: `docs/memory-advanced.md`.
 
-- **Search cascade.** ≥3 `Glob` / `Grep` calls to find a path that should be obvious (where do migrations live? where's the inbox table? which file owns the CLI dispatch?). Seed the answer with `scope: chip-startup`.
-- **Schema archaeology.** ≥3 file `Read`s to reconstruct the shape of a data type, a JSONB column, or an API request body. Seed the shape (1–3 lines) with `scope: <subsystem>-touch`.
-- **Trial-and-error env probing.** Multiple `Bash` attempts at the same env operation (different SSL flags, different connection strings, repeated "is this var set?" checks). Seed the working invocation with `scope: env`.
+## Proactive-fire rules
 
-### How to seed
+**ABOUT TO BACKGROUND A `greprag inbox watch`? USE THE `Monitor` AGENT TOOL, NOT `Bash(run_in_background: true)`.** Bash background notifies only on process completion; watchers run forever, so the agent gets zero events until it manually reads the output file. Wrap with `while true; do greprag inbox watch ...; done` so the loop survives inner crashes. Full pattern: `docs/inbox-watch.md`.
 
-```bash
-greprag lore add "<one-sentence learning, optionally with a file path>" --scope <scope> [--project <name>]
-```
-
-Examples:
-```bash
-greprag lore add "Migrations live at repo root: migrations/<NNN>_<name>.sql. Apply with node scripts/apply-migration.cjs migrations/<file>.sql." --scope chip-startup
-
-greprag lore add "Inbox storage uses JSONB metadata on nodes (store kind='inbox'). No inbox_messages table — dropped in migration 035. See packages/core/src/inbox.ts." --scope inbox-touch
-
-greprag lore add "Build everything from repo root: npm run build (Turborepo). Forced rebuild: npm run build -- --force." --scope general
-```
-
-**Scope naming.** Free-form strings — there is no enum. Check what's already in use before inventing a new label:
-
-```bash
-greprag lore scopes [--project <name>]
-```
-
-Conventional scopes:
-- `chip-startup` — what a freshly-spawned chip needs in its first 5 turns. Layout, build commands, test runners, key file paths.
-- `general` — applies to almost any session in this project.
-- `<subsystem>-touch` — lore that matters only when editing a specific subsystem (`inbox-touch`, `episodic-touch`, `enrichment-touch`).
-- `env` — environment / credentials / DB connection gotchas.
-
-Pick the narrowest scope that still applies. A lore entry about migration paths is `chip-startup` (every chip needs it); one about how the hourly compactor's prompt versioning works is `episodic-touch` (only relevant if you're editing that subsystem).
-
-### Reading lore back (pull pattern)
-
-```bash
-greprag lore query --scope chip-startup --limit 10 --format markdown   # for inlining into a chip prompt
-greprag lore query --scope inbox-touch --query "session routing"        # lexical-rank within a scope
-greprag lore query --query "how do migrations apply" --limit 5          # cross-scope, lexical-rank only
-greprag lore list                                                       # human-review every entry, grouped by scope
-greprag lore delete <nodeId>                                            # prune stale entry (nodeId printed in list)
-```
-
-`--format markdown` returns a numbered list with no decoration — drop it straight into a `**Project Lore**` block when spawning a chip.
-
-### Deliberate review (via /lore-advisor)
-
-Lore decays as code moves — paths change, conventions die, "learned that X" stops being true. Run `/lore-advisor` periodically (especially after a refactor or rename) to audit drift, mine episodic memory for newly-emerged learnings, and promote project-agnostic entries to global rules.
-
-### Chip-spawn pull pattern
-
-When you compose a `spawn_task` chip prompt, pull `chip-startup` lore into the prompt before dispatching. Full convention lives in `~/.claude/docs/chip-spawn.md`; the one-liner is: `greprag lore query --scope chip-startup --project <project> --limit 10 --format markdown`, then wrap the output in a `**Project Lore**` block at the top of the prompt. Skip the block when the output is empty.
-
-## Step 7 — Cross-project discovery (for advisor agents)
-
-When the user is in a cross-project advisor context ("content-advisor",
-"business-advisor") and you need to know which projects this tenant has
-memory in, call `discover` — one request returns every project plus
-per-shape row counts and activity ranges. No need to know directory paths
-upfront, no need to page through `/v1/memory/by-period` and risk one
-high-activity project crowding out structured rows from quieter ones.
-
-```bash
-greprag discover --json
-```
-
-Response shape:
-```json
-{
-  "tenant": { "id": "...", "userEmail": "..." },
-  "projects": [
-    { "id": "<uuid>", "name": "openwriter", "anchor": "registered",
-      "row_counts": { "turn": 197, "hourly": 8, "daily": 1, "weekly": 0, "ship-event": 12 },
-      "first_activity": "2026-05-12T08:00:00Z",
-      "last_activity":  "2026-05-25T11:42:00Z" }
-  ],
-  "crystallization_types": ["turn","hourly","daily","weekly","ship-event"],
-  "totals": { "rows": 1234, "projects": 7 }
-}
-```
+**ABOUT TO SEND TO A `@gmail.com` / `@anthropic.com` / REAL EMAIL ADDRESS? STOP — `users.email` IS NEVER A ROUTING ADDRESS.** Use the numeric handle (`1834729@greprag.com`) or claimed vanity alias (`travis@greprag.com`). If you don't know the recipient's handle, ASK — don't guess from their email. adr: adr/numeric-handles.md. Full grammar: `docs/inbox.md § address`.
 
-`anchor: "registered"` means the project was registered via
-`/v1/inbox/projects/register` (has a row in the `projects` table — inbox
-addressing as `<email>/<project_name>` works). `anchor: "fallback"` means
-the project is only known via memory-store metadata — still has memory,
-but no registry entry, so its name may be the path-derived basename and
-inbox-by-name resolution will not find it.
+## Reference index
 
-From there, pick a `projectId` from the list and fetch its briefing via
-the Step 6 queries.
+- `docs/setup.md` — auth · hooks · conventions · permissions · channels · anchor · opencode · bulk-register
+- `docs/per-project-flags.md` — flip `memory_capture` / `session_start_recap` / `inbox_notify`
+- `docs/inbox.md` — `greprag send`, `greprag inbox`, address grammar, retract
+- `docs/inbox-watch.md` — SSE watcher patterns, liveness model, parent-side / post-send patterns
+- `docs/doctor.md` — `greprag doctor` (identity drift, orphan consolidation)
+- `docs/corpus.md` — upload + search arbitrary text (books, codebases, voice samples)
+- `docs/discord-handoff.md` — Commander DM bridge (`greprag discord pair/handoff`)
+- `docs/memory-advanced.md` — raw curl, `/v1/memory/by-period` `--type` values, naming note
+- `docs/lore.md` — seed + query project-specific learnings
+- `docs/discover.md` — cross-project advisor lookup (`greprag discover`)