greprag 0.5.4 → 0.6.0

package/skill/SKILL.md

@@ -1,41 +1,188 @@
 ---
 name: greprag
 description: |
-  GrepRAG — surface episodic project memory for the current session.
-  Pulls what shipped, what was decided, and what's open from the last 7 days.
+  GrepRAG — agentic setup + episodic project memory.
 
-  Use when: "/greprag", "what did we do last week", "catch me up", "memory briefing",
-  "what's been happening in this project", "session context", "what shipped recently".
+  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 memory briefing.
+
+  Use when: "/greprag", "set up greprag", "greprag status", "configure
+  memory", "memory briefing", "catch me up", "what did we do last week",
+  "what's been happening in this project", "session context".
 metadata:
   author: travsteward
-  version: "1.0.0"
+  version: "3.1.0"
   repository: https://github.com/travsteward/greprag
 license: MIT
 ---
 
 # GrepRAG Advisor
 
-Pull episodic memory for the current project and surface a structured briefing.
+The agent drives all setup and runs the briefing. Single source of truth: `greprag status --json`.
+
+## Step 1 — Get the status
+
+```bash
+greprag status --json
+```
+
+Parse the JSON. The keys to check, in this order:
+
+1. `auth.api_key_present`
+2. `hooks.session_start_recap`, `hooks.stop_store`, `hooks.user_prompt_submit_notify`
+3. `project.anchor_found`
+4. `project.memory_capture`, `project.session_start_recap`, `project.inbox_notify`
+
+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 }] }
+  ```
+
+Append the missing entries to the existing arrays (create the arrays if absent). Don't overwrite existing hooks from other tools.
+
+## 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)"
 
-## Steps
+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`
 
-### 1. Get project ID
+**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
-greprag project-id
+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 the command errors or returns empty: tell the user "GrepRAG not initialized for this project — run `greprag init`" and stop.
+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.
 
-### 2. Check API key
+## 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
-echo $GREPRAG_API_KEY
+greprag send "<markdown body>" --to <address>
 ```
 
-If empty: tell the user "GREPRAG_API_KEY not set — run `greprag init`" and stop.
+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@example.com/paybot \
+  --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
+```
 
-### 3. Fetch episodic context
+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)
+
+**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 (all valid):
+- `alice@example.com` — recipient's tenant inbox by real email
+- `alice@example.com/paybot` — recipient's paybot project inbox
+- `alice@greprag.com` — same recipient by their auto-claimed greprag handle (tenant_id alias)
+
+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 6 — Briefing (when everything is configured)
 
 ```bash
 PROJECT_ID=$(greprag project-id)
@@ -50,21 +197,19 @@ curl -sf "https://api.greprag.com/v1/memory/by-period?projectId=${PROJECT_ID}&fr
   -H "Authorization: Bearer ${GREPRAG_API_KEY}"
 ```
 
-### 4. Present
-
-If both responses have empty `memories` arrays: "No episodic memory yet for this project — compaction runs hourly. Check back after the first active session."
+If both responses have empty `memories`: "No episodic memory yet for this project — compaction runs hourly. Check back after the first active session."
 
-Otherwise format as a briefing:
+Otherwise present verbatim:
 
 ---
 **[project_name] — memory briefing**
 
-**This week** *(omit section if no weekly row)*:
+**This week** *(omit if no weekly row)*:
 [weekly summary verbatim]
 
 **Recent days**:
-[each daily row, newest first, prefixed with its date — "May 21:", "May 20:", etc.]
+[each daily row, newest first, prefixed with its date]
 
 ---
 
-Do not rewrite or summarize the episodic content. Present it verbatim — the compactor already shaped it. The briefing is input to this session's context, not a report to the user.
+Do not rewrite or summarize. Present verbatim — the compactor already shaped it.