greprag 5.13.0 → 5.15.0

package/skill/greprag/docs/setup.md

@@ -0,0 +1,208 @@
+# Setup
+
+Routes for each gap surfaced by `greprag status --json`. Re-run status after each fix and continue down the list.
+
+## opencode
+
+OpenCode users install once:
+
+```bash
+greprag init --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. Both surfaces share the same anchor (`.claude/project.json` or `.opencode/project.json`) and API key.
+
+## bulk-register
+
+When several repos exist but only one is inbox-addressable:
+
+```bash
+greprag init --all
+```
+
+Runs standard init for cwd, then registers every sibling git repo at depth 1 (default scan root: parent of the current repo).
+
+## auth
+
+Trigger: `auth.api_key_present === false`.
+
+1. Ask for 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.
+
+## hooks
+
+Trigger: any of `hooks.session_start_recap`, `hooks.stop_store`, `hooks.post_tool_use_spawn_reminder` is false.
+
+Append missing entries to the existing arrays in `~/.claude/settings.json` (create the arrays if absent). Don't overwrite hooks from other tools.
+
+- **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. Validates against `~/.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 on failure; the agent re-composes.
+
+The legacy `user_prompt_submit_notify` hook was removed in v5.6.1 — live inbox delivery is now the Monitor watcher's job. Do not install it.
+
+**Removing the legacy PostToolUse spawn-reminder hook** (only on upgrade from v0.x → v0.12+): if `hooks.PostToolUse` contains an entry with `matcher: "mcp__ccd_session__spawn_task"` and `command: "greprag-hook spawn-reminder"`, delete it. The behavior is now ambient — SessionStart auto-arms the watcher in every greprag-enabled session.
+
+## conventions
+
+Two pieces install together: a loud pointer in `~/.claude/CLAUDE.md` and the protocol body at `~/.claude/docs/chip-spawn.md`. 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:
+```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 -qE "greprag-conventions:start v[1-3]" ~/.claude/CLAUDE.md; then echo OLD_UPGRADE
+else echo MISSING; fi
+test -f ~/.claude/docs/chip-spawn.md && echo DOC_OK || echo DOC_MISSING
+```
+
+**If `MISSING`**, insert into `~/.claude/CLAUDE.md` immediately after the `## Inbox` section (use Edit, 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 pointer above. Tell the user "Upgrading v4 → v5 (moves inline body to ~/.claude/docs/chip-spawn.md)."
+
+**If `OLD_UPGRADE`** (v1/v2/v3), same replacement pattern: delete the old block (markers inclusive) and insert v5. Also delete the legacy deep doc:
+```bash
+rm -f ~/.claude/docs/agent-coordination.md
+```
+
+**If `DOC_MISSING`**, re-run `greprag init` — it's idempotent and re-copies `chip-spawn.md` from the npm package.
+
+Re-run the grep to confirm. Markers must stay verbatim — they're how subsequent `/greprag` runs detect "already installed."
+
+## permissions
+
+Trigger: `Monitor` not in `~/.claude/settings.json` `permissions.allow`.
+
+Without it, every inbox-watcher firing prompts for approval, breaking the reply-listening convention. Recommended baseline:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "Monitor",
+      "Read", "Edit", "Write", "Grep", "Glob",
+      "WebFetch", "WebSearch", "Skill", "Agent", "Task"
+    ]
+  }
+}
+```
+
+`Bash(*)` covers `greprag *` and `greprag-hook *`. `Monitor` is its own tool and prompts independently.
+
+Per-command minimum for tighter Bash policies:
+- `Bash(greprag *)`
+- `Bash(greprag-hook *)`
+- `Monitor`
+
+Tell the user the proposed change before editing. Don't silently broaden their permission posture.
+
+## channels
+
+Trigger: any channel plugin (`discord`, `telegram`, `imessage`, `fakechat`) enabled in 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
+```
+
+Tell the user: channel push delivery requires the `--channels` flag at session launch — being in `settings.json` and `.mcp.json` is not enough.
+
+- **Setting enables the MCP server to load** → 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 session context.
+
+Without `--channels`, the bot can be DM'd and the bun server receives the event, but Claude Code's harness filters it. Observed symptom: "typing indicator fires, then bot times out without replying."
+
+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 works only from terminal-launched sessions:
+
+```bash
+cd <project-with-plugin>
+claude --channels plugin:discord@claude-plugins-official
+```
+
+FleetView sessions can poll the plugin's REST tools as a workaround; realtime path is terminal-only.
+
+Scope the plugin to a single project's `.claude/settings.json`, not global. Discord allows one gateway connection per bot token; multiple sessions with the plugin enabled race for the token and Discord drops all but one.
+
+## anchor
+
+Trigger: `project.anchor_found === false`.
+
+Ask: "GrepRAG isn't set up for this project yet. Set up memory for this folder? (y/n)"
+
+If yes, 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/`, it's ephemeral. Ask:
+
+> "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 stable parent, walk up to nearest stable dir (`~/AppData/Roaming/Claude/` on Windows, `~` on Unix).
+
+If `project.is_deterministic_fallback === true` AND 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. If no, mint fresh: `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
+```
+
+Register 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>\"}"
+```
+
+On 409 (project_name conflict under this tenant), ask the user for a unique handle and retry.