greprag 5.13.0 → 5.15.0

package/skill/greprag/docs/corpus.md

@@ -0,0 +1,98 @@
+# Corpus
+
+Upload arbitrary text (book, codebase, reference doc, writing-sample library), search it with lexical grep enriched by write-side vocabulary bridging. Distinct from memory (the agent's own captured work, marketed as Odyssey).
+
+**Design contract (post-v0.8):** GrepRAG does no LLM work at read time. The agent formulates lexical queries. Write-side enrichment bridges modern vocabulary to archaic registers (e.g. "insulted" finds "wrongeth" via tsvector OR). Read-side is pure SQL: 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 — 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 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 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 — chain protocol
+
+Searches are agent-driven. You decompose the user's intent into 1–3 lexical queries.
+
+### Query operator syntax (websearch_to_tsquery)
+
+- `term1 term2` — both required (AND)
+- `term1 OR term2` — either suffices
+- `"quoted phrase"` — exact adjacent words
+- `-excluded` — must NOT contain
+- Parenthesize: `(insulted OR wronged) -metadata`
+
+Build queries that bridge user's modern vocabulary to 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
+
+1. **Probe** — `greprag corpus search "<store>" "<2-3 broad-vocab query>"` to find topic region.
+2. **Narrow** — if results scatter, refine with `--section "Chapter VII"` or tighter operators and re-search.
+3. **Expand** — for each promising hit, `greprag corpus walk "<store>" <nodeId>` to read 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.
+
+### 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
+
+```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.
+
+## 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
+```
+
+## Corpus vs memory
+
+| Want to … | Use |
+|---|---|
+| Look up a specific problem, bug, or topic in past sessions | `greprag memory search "<query>"` |
+| Pull yesterday's daily, last week's weekly | `greprag memory recap` |
+| "What shipped on this branch last week?" | `greprag memory ships --last 50` or `memory daily --last 7` |
+| Backfill a missed compaction window | `greprag memory compact <hour\|day\|week>` |
+| Load a book the user paste-bombed | `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` |
+
+Memory is the agent's own past (marketed as Odyssey). Corpus is everything else.

package/skill/greprag/docs/discord-handoff.md

@@ -0,0 +1,47 @@
+# Discord Handoff (Commander)
+
+Discord DM bridge — user steps away from desk, conversation continues on phone. Orchestrator-side summary; operator-facing flow lives at `~/.claude/skills/commander/SKILL.md`.
+
+Two surfaces: one-time pairing (identity) + per-session handoff (active routing). 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.
+
+## Pairing (one-time per tenant)
+
+```bash
+greprag discord pair
+```
+
+Generates a 6-char code. 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 — 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 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, then **blocks** streaming the session's inbox to stdout as JSON. Each line that prints is one Discord DM — Monitor delivers them as notifications back into your turn. Pin slides forward 30+ min on every inbound; an active thread stays anchored.
+
+Replies go out via:
+
+```bash
+greprag send --to discord:<snowflake> "your message body"
+```
+
+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 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 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 fires 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> "..."`. Snowflake is in `references.discord.snowflake`.

package/skill/greprag/docs/discover.md

@@ -0,0 +1,28 @@
+# Discover (Cross-Project)
+
+For advisor agents (`content-advisor`, `business-advisor`) that need to know which projects a tenant has memory in. 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 }
+}
+```
+
+`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. Its name may be the path-derived basename and inbox-by-name resolution will not find it.
+
+From there, pick a `projectId` and fetch its recap via the standard CLI verbs (`greprag memory recap --project <name>` etc.).

package/skill/greprag/docs/doctor.md

@@ -0,0 +1,22 @@
+# Doctor (Health & Repair)
+
+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 session-start recap printed `[GrepRAG memory: identity drift detected ...]`.
+
+```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 (orphans — usually from old anchor files lost to gitignore or a hash-fallback period before init)
+4. Presents findings and offers actions:
+   - **Migrate to git-derived UUID** (recommended on 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 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 ("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 — only touches rows under the caller's tenant. Merge runs in a transaction so a partial failure rolls back cleanly.

package/skill/greprag/docs/inbox-watch.md

@@ -0,0 +1,57 @@
+# Inbox Watch (SSE)
+
+Live push delivery via SSE. Use whenever you'd otherwise loop `greprag inbox` on a heartbeat — lower latency, cheaper, doesn't burn quota on empty polls.
+
+## Commands
+
+```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                # one JSON object per line (preferred under Monitor)
+```
+
+`--project` and `--session` compose. `--session` is the strictest filter: only messages with matching `to_session_id` (or `to_session_id IS NULL` for broadcasts) get through. This 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). Connection auto-reconnects with exponential backoff; the watcher tracks last seen message id and uses it as `since=` on reconnect — nothing dropped, nothing duplicated.
+
+## Liveness model (post v0.8.5)
+
+Server emits an SSE `: ping` comment every 15s. Client tracks time since last byte; 60s of silence (4 missed pings) = dead stream. Watcher aborts the fetch, reconnects with preserved cursor, server's per-tenant InboxDO replays any rows from the gap from its tail buffer (or backfills from DB for older gaps). After replay, server emits `event: replay-complete` with the row count — watcher logs `replayed N missed row(s), resuming live tail` to stderr.
+
+Disconnects and reconnect attempts also log to stderr with the cursor. Pre-fix, a silently half-open TCP socket would hang the watcher indefinitely with no log; that failure mode is gone, but delivery is still opportunistic — the `UserPromptSubmit` hook remains the correctness guarantee.
+
+## Pattern: parent watches for chip reports
+
+Parent arms a Monitor scoped to its own session, then spawns the chip (chip's Block 2 sends with `--session <parent-session-id>`):
+
+```bash
+while true; do greprag inbox watch --session <parent-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
+```
+
+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.
+
+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.
+
+## Pattern: post-send listens for replies
+
+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 fires only between user prompts. Mid-task replies are invisible until the next stop boundary.
+
+```bash
+# After: greprag send "..." --to <someone> --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 broadcasts).
+
+## Why Monitor, not Bash background
+
+Run watchers under the `Monitor` agent tool with `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. A watcher runs forever, so the agent gets zero events until it manually reads the output file. Stop with `TaskStop` on the Monitor task when the watch is truly no longer needed.
+
+## Why not the Stop hook for replies
+
+The greprag Stop hook ingests inbox messages between user prompts. A Mode B chip running autonomously may never hit a stop boundary; a Mode A chip waiting on a reply mid-task gets the reply only on the next manual interaction. Monitor delivers the reply as an in-session event the moment it lands — no hook lag, no missed directive.

package/skill/greprag/docs/inbox.md

@@ -0,0 +1,100 @@
+# Inbox
+
+Send and read messages across sessions/projects/tenants. Plus the retract path for messages sent in error.
+
+## Read
+
+```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>
+```
+
+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.
+
+## Send
+
+```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. See § retract.
+
+## Rich messages (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 can address replies back without re-discovery. Use whenever you expect a reply.
+
+When to populate references:
+- Short chat ("pinging you", "deploy is up", "ack") → no references, just body.
+- Bug reports, follow-ups, design decisions → always add `--file` and any `--artifact`.
+- Cross-referencing prior memory → pull memory IDs from `greprag inbox` or the recap, pass via `--memory`.
+- Don't hallucinate references. If you can't name a real file path or artifact ID, leave the flag off.
+
+The legacy `--session` and `--project` flags were removed in v0.11 — passing them errors out with a migration hint. The target lives in the `--to` address itself.
+
+## address
+
+v0.11+ grammar:
+
+| 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." |
+| `me` / `self` | Shortcut for your own tenant | Receive form only. |
+
+Disambiguation: 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.
+
+`<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. adr: adr/address-grammar.md
+
+## retract
+
+`send` returns a retract code (printed after `Retract:` on the second line of success output). Use when you realize a message was wrong-framed and want to pull it back instead of stacking a follow-up note:
+
+```bash
+greprag retract <code>
+```
+
+Server-decided behavior based on whether the recipient has read:
+
+- **Unread** → row hard-deleted. Output: `Retracted (status: deleted — recipient had not read it).`
+- **Read** → body replaced with `[RETRACTED BY SENDER at <ts>]`. 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. Output: `Already retracted (status: already_retracted — no change).`
+- **Unknown code** → no error. Output: `Not found (status: not_found — code does not match any message you sent, or the message has already expired).`
+
+When to retract vs. SUPERSEDES follow-up:
+- Just sent, recipient hasn't read, framing was wrong → `greprag retract`.
+- Recipient has already read → `greprag retract` still beats stacked follow-up (placeholder vs. stale message), then send a fresh `greprag send` with corrected framing.
+- Recipient already acted on the message (committed code, made a decision) → send `SUPERSEDES <old-id>: <correction>` so they have full context. Retract still cleans the original.
+
+Retract codes are sender-scoped — your code cannot retract someone else's message. Codes stay valid until the message expires (14 days unread, longer if `keep`'d).

package/skill/greprag/docs/lore.md

@@ -0,0 +1,70 @@
+# 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:
+
+- **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 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`.
+
+## How to seed
+
+```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 — no enum. Check what's already in use first:
+
+```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
+
+```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
+```
+
+`--format markdown` returns a numbered list with no decoration — drop straight into a `**Project Lore**` block when spawning a chip.
+
+## Deliberate review
+
+Lore decays as code moves — paths change, conventions die. 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 composing a `spawn_task` chip prompt, pull `chip-startup` lore into the prompt before dispatching. Full convention: `~/.claude/docs/chip-spawn.md`. One-liner:
+
+```bash
+greprag lore query --scope chip-startup --project <project> --limit 10 --format markdown
+```
+
+Wrap the output in a `**Project Lore**` block at the top of the prompt. Skip the block when the output is empty.

package/skill/greprag/docs/memory-advanced.md

@@ -0,0 +1,23 @@
+# Memory — Advanced
+
+Raw curl recipes and the HTTP surface beneath `greprag memory`. Use only when the CLI verbs in SKILL.md don't cover the case (scripted use, automation, debugging).
+
+## Raw curl
+
+```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}"
+```
+
+## `/v1/memory/by-period` `--type` values
+
+Valid: `turn`, `hourly`, `daily`, `weekly`, `ship-event`.
+
+Earlier doc versions referenced `episodic-daily` / `episodic-weekly` — those values silently return zero rows because no node ever had that shape. The `greprag memory` CLI uses the correct values; prefer the CLI over raw curl.
+
+## Naming note
+
+The HTTP route stayed `/v1/memory/by-period`. The marketing brand for the product line is still "Odyssey" (see /odyssey/ on the website); the CLI verb is the literal noun `memory`. The `greprag odyssey ...` verb still works as a silent back-compat alias.

package/skill/greprag/docs/per-project-flags.md

@@ -0,0 +1,14 @@
+# Per-Project Flags
+
+Triggered when 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 `greprag status --json`
+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.
+
+Valid values:
+- `memory_capture`: `true | false`
+- `session_start_recap`: `true | false`
+- `inbox_notify`: `"every_turn" | "session_start_only" | "off"`