greprag 0.10.0 → 5.0.0

package/skill/content-advisor/docs/setup.md

@@ -0,0 +1,125 @@
+# Setup — First-Run Gateway
+
+The advisor's first invocation enters bootstrap. Setup runs once, written to a config file, then subsequent invocations skip directly to the standard protocol.
+
+## Portfolio root resolution
+
+Resolution order:
+
+1. Env var `CONTENT_ADVISOR_ROOT`
+2. Config file `~/.claude/content-advisor.json` with `{ "portfolio_root": "/abs/path" }`
+3. Marker file scan up the cwd tree — looks for `docs/ventures.md` and `docs/strategy/focus.md`
+4. Fallback default: `C:/orchestrator`
+5. None applicable → ask user, save to config
+
+The advisor never operates against an unresolved portfolio root.
+
+## Setup flow
+
+```
+/content-advisor (no config detected)
+  ↓
+[Step 1] Locate portfolio root
+  → default C:/orchestrator; confirm or override
+  → save to ~/.claude/content-advisor.json
+  ↓
+[Step 2] Check GrepRAG
+  → command -v greprag → exits 0?
+  → test -n "$GREPRAG_API_KEY"? (source ~/.env if missing)
+  → greprag discover --json → returns ≥1 project?
+  → any failure → walk user through /greprag setup
+  ↓
+[Step 3] Verify writer skills present
+  → ~/.claude/skills/x-writer/SKILL.md exists?
+  → ~/.claude/skills/blog-writer/SKILL.md exists?
+  → ~/.claude/skills/newsletter-writer/SKILL.md exists?
+  → any missing → "Run /skill-publish from C:/openwriter to install the writer masters."
+  ↓
+[Step 4] Read WRITER-CONVENTION.md
+  → C:/openwriter/skills/WRITER-CONVENTION.md (source of truth for handoff brief shape)
+  → if absent, advisor still works but warns the contract is unverified
+  ↓
+[Step 4.5] Per-venture ICP (Ideal Customer Profile) derivation
+  → For each venture in `project_to_venture`:
+    a) Search for an existing avatar / audience doc:
+       - OpenWriter workspaces with titles like "Audience", "Audience & Reader Journey", "Avatar", "ICP"
+       - The venture's marketing-site repo for `content/audience.md` or similar
+       - If found → store pointer in config under `icp_per_venture[venture]` as
+         `"openwriter:<docId>"` or `"file:<absolute-path>"`
+    b) If no doc exists, conduct a short interview (5-7 questions max):
+       - Who is the buyer? (one sentence)
+       - What's their current state? (the pain that brings them in)
+       - What do they pick up your content hoping for?
+       - What's the recognition shock they want? (their life mirrored back)
+       - What do they walk away with that's actionable this week?
+       - What's the failure mode of content that doesn't land?
+       - Optional: who do they trust today that you're competing with?
+    c) Write the interview output to `docs/icp/<venture>.md` in the portfolio
+       root and store the pointer in config.
+  → Per-venture ICP is the demand-side spec the advisor reads at rank time
+    (see Rule 5 in `decision-rules.md`).
+  ↓
+[Step 5] Verify portfolio docs
+  → docs/ventures.md, docs/strategy/focus.md present?
+  → each missing → "Run /business-advisor to scaffold portfolio docs."
+  ↓
+[Step 6] Project ↔ venture mapping
+  → greprag discover --json lists project names
+  → match each to a venture umbrella (often 1:1; some ventures span multiple repos)
+  → save to ~/.claude/content-advisor.json under `project_to_venture`
+  ↓
+[Step 7] Optional: per-venture cadence overrides
+  → defaults in docs/decision-rules.md (X daily, newsletter weekly, blog 2×/mo)
+  → user can override per venture in config under `cadence_overrides`
+  ↓
+[Step 8] Lock in
+  → run one full pass, present opportunity list as the first output
+  → confirm config persisted
+```
+
+## Config file format
+
+`~/.claude/content-advisor.json`:
+
+```json
+{
+  "portfolio_root": "C:/orchestrator",
+  "greprag_api_url": "https://api.greprag.com",
+  "project_to_venture": {
+    "openwriter": "openwriter",
+    "openwriter-site": "openwriter",
+    "openwriter-publish": "openwriter",
+    "paybot": "paybot",
+    "paybot-portal": "paybot",
+    "tournamentmale": "tournament-male",
+    "tm-book": "tournament-male",
+    "orchestrator": "personal"
+  },
+  "cadence_overrides": {
+    "openwriter": { "blog": "weekly" }
+  },
+  "icp_per_venture": {
+    "your-venture-here": "openwriter:doc_abc123",
+    "another-venture": "file:C:/path/to/portfolio/docs/icp/another-venture.md"
+  },
+  "channels_per_venture": {
+    "tournament-male": ["x", "newsletter", "blog"],
+    "paybot": ["x", "blog"],
+    "openwriter": ["x", "blog"],
+    "personal": ["x", "newsletter"]
+  }
+}
+```
+
+`channels_per_venture` is the gate that prevents the advisor from proposing a blog post for a venture that has no blog. Default behavior when a venture is missing from this map: assume all three channels eligible.
+
+## Re-running setup
+
+Delete `~/.claude/content-advisor.json` and re-invoke. Or invoke with "redo setup step N" to re-enter one sub-flow.
+
+## Failure modes
+
+- **GrepRAG unreachable** → advisor cannot run. Setup blocks. Source-farmer rule needs ship-events; nothing else compensates.
+- **Writer skills missing** → advisor still produces the list but flags handoff commands as unverified.
+- **Portfolio docs missing** → tier prioritization disabled (all opportunities treated equal). Surface a warning.
+- **No projects in greprag discover** → no source material. Advisor exits with "no episodic memory yet — write code, ship something, then check back."

package/skill/content-advisor/docs/writing-activity.md

@@ -0,0 +1,89 @@
+# Writing Activity
+
+The "what have we already written" stream. Pairs with episodic memory to drive the anti-duplication and cadence-floor rules.
+
+## What we want to know per channel per venture
+
+| Channel | The question | Source |
+|---|---|---|
+| X | When was the last post? What topics in last 7d? | x-strategy cache, or fxtwitter recent timeline |
+| Blog | When was the last post? What topics in last 30d? | git log on the venture's marketing-site repo + frontmatter scan |
+| Newsletter | When was the last issue sent? What was its through-line? | `mcp__openwriter__list_newsletter_issues` |
+| OpenWriter drafts | What's in flight right now (un-shipped drafts touched in last 14d)? | `mcp__openwriter__list_documents` filtered by recency |
+
+## Per-source procedure
+
+### OpenWriter drafts (in-flight)
+
+```
+list_workspaces → for each workspace:
+  list_documents → filter where updatedAt > now-14d AND not in trash
+  → for each doc: extract { id, title, workspace_name, updatedAt, tags }
+  → infer channel from workspace name conventions (blog/newsletter/x/scratch)
+    OR from tags if present
+  → infer venture from workspace name OR explicit metadata
+```
+
+These are CRUCIAL — an in-flight draft on topic X means "don't propose another piece on X." Surface them as "in progress" markers, not opportunities.
+
+### Newsletter sends
+
+```
+list_newsletter_issues → sort desc by sentAt → take top 4
+  → for each: { id, subject, sentAt, doc_id }
+  → most recent sentAt → "newsletter last sent N days ago"
+  → if N > cadence floor (default 7d): cadence-floor opportunity for newsletter
+```
+
+### Blog history
+
+For each venture with a marketing-site repo (path resolved via `project_to_venture` config + scanning `ventures.md` for repo paths):
+
+```
+git -C <repo> log --since="30 days ago" --name-only --pretty=format:'%h|%ci|%s'
+  → filter file changes to blog content paths (src/content/blog/**, content/posts/**, etc.)
+  → group commits by post file → { post_file, first_commit_date, latest_commit_date }
+  → most recent → "blog last shipped N days ago"
+```
+
+The blog-content path convention varies per site; try common patterns:
+- `src/content/blog/**` (Astro)
+- `content/posts/**` (Hugo)
+- `_posts/**` (Jekyll)
+- `app/blog/**/page.mdx` (Next.js)
+
+If no match, fall back to scanning frontmatter (`---\npubDate:`) in any `.md`/`.mdx` file modified in window.
+
+### X activity
+
+Three options, in preference order:
+
+1. **`/x-strategy` cache** — if present at a known path, parse the latest cached export.
+2. **`mcp__x__*` tools** — if the X MCP is connected, query recent tweets for @Meta_Trav.
+3. **fxtwitter timeline** — public, free; parse the user's recent posts.
+
+What we want: list of `{ posted_at, text, type: thread|single|article|comic, topic_inferred }`. Topic inference is best-effort — a 30-word excerpt is enough to dedupe against memory rows.
+
+## Output of this stream
+
+A per-venture-per-channel activity map:
+
+```json
+{
+  "tournament-male": {
+    "x":          { "last_at": "2026-05-24T...", "topics_7d": ["six-week challenge", "kettlebell program"] },
+    "newsletter": { "last_at": "2026-05-19T...", "subject": "Week of May 19" },
+    "blog":       { "last_at": "2026-04-30T...", "recent_topics": ["bible study cohort"] }
+  },
+  "paybot": {
+    "x":          { "last_at": "2026-05-23T...", "topics_7d": ["upgrade flow ship"] },
+    "blog":       { "last_at": "2026-05-10T...", "recent_topics": ["new pricing"] }
+  }
+}
+```
+
+Plus a separate "in-flight drafts" list across all ventures (the OpenWriter list_documents output, filtered by recency).
+
+## Failure tolerance
+
+Any one of these sources can be down without breaking the advisor — they're enrichment. The minimum viable run is: greprag memory + ventures.md + focus.md. Everything else just sharpens ranking.

package/skill/{SKILL.md → greprag/SKILL.md}

@@ -133,9 +133,15 @@ Delegating work — `spawn_task` chip vs `Agent` tool, two chip modes, the workt
 
 **Non-negotiables for every `spawn_task` chip prompt:** (0.5) project facts pulled from `greprag fact`, (1) worktree-first setup, (2) `greprag send` report-back, (3) `Monitor` on own inbox for follow-ups. Without them the chip pollutes the main checkout, has no return channel, or dies after one report. Copy the boilerplate verbatim from the deep doc.
 
-**Reply listening (any session, not just chips).** Any time you `greprag send` a message that could draw a directive in response, arm a `Monitor` watcher on your own inbox in the same turn — `greprag inbox watch --session <own-session-id> --json` with `persistent: true` (or `--project <own-project>` as a project-wide fallback when no session identity is available). The Stop hook only fires between user prompts; without Monitor, mid-task replies are invisible until the next stop boundary.
+**Reply listening (any session, not just chips).** Any time you `greprag send` a message that could draw a directive in response, arm a `Monitor` watcher on your own inbox in the same turn. Use the bash-wrapper form so the watcher auto-restarts if the inner SSE process dies (network blip, supervisor bug, Cygwin fork failure):
 
-For real-time chip reports, the parent runs `greprag inbox watch --session <parent-session-id>` (preferred) or `--project <parent-project>` under `Monitor` BEFORE spawning. Each stdout line = one notification. Do NOT use `Bash(run_in_background)` — it only fires on process completion, not per line; a watcher never exits, so the parent gets zero events.
+```bash
+while true; do greprag inbox watch --session <own-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
+```
+
+Run under `Monitor` with `persistent: true`. Fall back to `--project <own-project>` instead of `--session` when no session identity is available. The Stop hook only fires between user prompts; without Monitor, mid-task replies are invisible until the next stop boundary.
+
+For real-time chip reports, the parent arms the same wrapped watcher (`--session <parent-session-id>` preferred, `--project <parent-project>` for multi-chip campaigns) under `Monitor` BEFORE spawning. Each stdout line = one notification. Do NOT use `Bash(run_in_background)` — it only fires on process completion, not per line; a watcher never exits, so the parent gets zero events. Do NOT use the bare `greprag inbox watch` without the `while true` wrapper — if the inner watcher dies you go silently deaf with no restart.
 <!-- greprag-conventions:end v3 -->
 ```
 
@@ -289,7 +295,7 @@ greprag send "<markdown body>" --to <address>
 
 `send` prints two lines on success — the delivered-to confirmation **and a retract code**:
 ```
-Sent to alice@example.com/paybot  (a7f3c5e2)
+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.
@@ -297,7 +303,7 @@ The retract code lets the sender pull the message back without layering follow-u
 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 \
+  --to alice@greprag.com/abc12345 \
   --memory 04f3e0d4-aa12-44ef-9a01-bb3df2c7e911 \
   --file src/auth/handler.ts:42 \
   --file src/middleware/check.ts:10-15 \
@@ -310,8 +316,9 @@ Flags (all repeatable, all optional):
 - `--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)
-- `--session <id>` — target a specific session under the project. Only the session's `inbox watch --session <id>` sees it; broadcasts (no `--session`) still reach every session-scoped watcher. Equivalent to suffixing the address with `/<id>`.
-- `--from-session <id>` — sender's own session UUID. Denormalized onto the message so the recipient learns your session and can address replies back via `--session <your-id>` without re-discovery. Use whenever you expect a reply.
+- `--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.
@@ -319,16 +326,24 @@ Flags (all repeatable, all optional):
 - 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):
-- `1834729@greprag.com` — canonical numeric handle. Every account has one; opaque, leaks nothing. Get yours from `greprag status --json | jq -r .identity.handle` or `greprag whoami`.
-- `1834729@greprag.com/paybot` — recipient's paybot project inbox.
-- `1834729@greprag.com/paybot/<session-id>` — only the named session sees it (plus broadcasts). Trailing UUID is case-sensitive.
+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`).
-- `me` / `self` — shortcut for your own tenant inbox (server resolves).
 
 **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
 
-Project-level addressing is the fallback whenever no specific session is in mind. Session-level is for precise routing — chip ↔ parent reply isolation, or any case where multiple sessions on the same project would otherwise share an inbox.
+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.
 
@@ -359,7 +374,9 @@ Each message arrives within ~500ms of the sender's `greprag send` (210ms verifie
 # (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.
-greprag inbox watch --session <parent-session-id> --json
+# 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.
@@ -371,7 +388,8 @@ Any session that sends a message that could draw a directive in response arms th
 ```bash
 # After: greprag send "..." --to <someone>/<their-project>/<their-session> \
 #                          --from-session <own-session-id>
-# Arm:   greprag inbox watch --session <own-session-id> --json   (Monitor, persistent: true)
+# 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.
@@ -438,11 +456,11 @@ Triggers: "load this book into greprag", "upload the docs", "ingest this PDF" (a
 ### Upload
 
 ```bash
-greprag corpus upload <file-or-url> [--name "Display Name"] [--kind book] [--enrichment-style book]
+greprag corpus upload <file-or-url> [--name "Display Name"] [--kind book]
 ```
 
-- `--kind` defaults to `book`. Valid: `book`, `codebase`, `voice`, `generic`.
-- `--enrichment-style` picks the write-side prompt template. Valid: `book` (narrative/philosophy, default), `codebase` (source code), `transcript` (dialogue/interview), `reference` (technical docs), `generic` (mixed/unknown). If omitted, auto-derived from `--kind`. Pass it explicitly when the content shape differs from the default — e.g. a transcript uploaded as `--kind generic --enrichment-style transcript`.
+- `--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.
@@ -523,7 +541,7 @@ greprag corpus delete "<store>" --yes
 | Pull yesterday's daily summary, last week's weekly | `/v1/memory/by-period` (Step 6 briefing flow) |
 | Ask "what did I work on with the auth migration?" | `/v1/memory/by-period` filtered by keywords |
 | 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 --enrichment-style codebase` |
+| 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` |
 
 Episodic memory is the agent's own past. Corpus is everything else.

package/skill/templates/agent-coordination.md

@@ -59,7 +59,7 @@ All edits, tests, and commits happen in the worktree. The main checkout stays un
 **Your parent's session id is `<parent-session-id>`** — record it; you'll need it in Block 2 to address the report-back so only the parent sees it, not every sibling chip watching the same project inbox.
 ```
 
-Fill `<parent-session-id>` from your own (parent) session UUID when composing the spawn_task prompt. If you don't know your session UUID, fall back to project-level addressing throughout Block 2/3 — the chip then sends to `--to <email>/<parent-project>` (no session suffix) and the parent watches `--project <parent-project>` (no `--session`). Less precise, still correct.
+Fill `<parent-session-id>` from your own (parent) session UUID when composing the spawn_task prompt. If you don't know your session UUID, fall back to project-level addressing throughout Block 2/3 — the chip then sends to `--to <handle>@greprag.com/<parent-project>` (project broadcast, intentional) and the parent watches `--project <parent-project>` (no `--session`). Less precise, still correct — both sides have to be project-scoped for the loop to close.
 
 Path convention: `<project>/.claude/worktrees/<slug>/` — same parent directory Claude Code Desktop uses for IDE-checkbox worktrees. One place to look for any active Claude worktree. Branch prefix `chip/` distinguishes agent-spawned from IDE-spawned (`claude/<auto-name>`), so `git branch` output shows provenance at a glance. `/clean-worktrees` skill cleans both.
 
@@ -67,6 +67,8 @@ Path convention: `<project>/.claude/worktrees/<slug>/` — same parent directory
 
 **Chip cleanup discipline (HARD RULE — every chip prompt must enforce this).** Chips **commit and exit**. They do NOT run `git clean -fd`, `git reset --hard`, `git worktree remove` (any target), `git checkout <other-branch>`, raw `rm -rf` of directories, or any destructive shell command outside their own worktree's tracked files. If a chip needs to delete a file it created, use `git rm` and commit the deletion — never raw `rm`. The parent session owns post-merge worktree cleanup; chips never reach for it themselves. This rule exists because parallel worktrees share `.git`, a poorly-scoped cleanup command can wipe another worktree's working tree, and the main checkout has been observed to lose `packages/*/src/` files in this exact pattern. Spawning agents: include "Chip cleanup discipline" verbatim in Block 1 of every chip prompt.
 
+**`npm link` discipline.** If a chip needs to smoke-test a CLI build globally, run `npm link` from the main checkout's package dir (`cd <main>/packages/<pkg> && npm link`), NOT from the worktree. Linking from the worktree registers a global symlink that points INTO the worktree; after `git worktree remove` runs in /commit's Phase 4, the symlink dangles and the CLI breaks system-wide until reinstalled. The /commit skill's `guard-npm-links.sh` auto-recovers (re-points at main or unlinks), but the cleanest path is to never create the worktree-pointed symlink in the first place.
+
 ### Block 2 — Report back via greprag inbox (append to prompt)
 
 ```
@@ -74,21 +76,20 @@ Path convention: `<project>/.claude/worktrees/<slug>/` — same parent directory
 
 ```bash
 greprag send "<status>: <commit hash> on chip/<slug> — <one-line>" \
-  --to <your-tenant-email>/<parent-project> \
-  --session <parent-session-id> \
+  --to <your-tenant-handle>@greprag.com/<parent-session-id> \
   --from-session <own-session-id> \
   --artifact commit:<hash> \
   --file <key-file-path>
 ```
 
 - `<status>`: `done` | `blocked` | `partial`
-- `<parent-project>`: the project_name of the session that spawned you (it's in this prompt's metadata if unknown)
-- `<parent-session-id>`: filled in by the spawning session in Block 1 of this prompt.
+- `<your-tenant-handle>`: parent's `@greprag.com` handle (e.g. `1834729` or a claimed alias like `travis`).
+- `<parent-session-id>`: filled in by the spawning session in Block 1 of this prompt. The full UUID or 8-hex short form both work. This trailing segment IS the target — only the parent's session-scoped watcher receives the message.
 - `<own-session-id>`: this chip's own session UUID. Denormalized onto the message so the parent can address replies back without re-discovering the chip's identity.
 - Body ≤280 chars where possible. If blocked, name the blocker explicitly.
 - Use `--artifact` and `--file` flags to back-reference the actual work (see `/greprag` skill).
 
-If `<parent-session-id>` is unknown (parent didn't pass one), drop both `--session` and `--from-session` — the message falls back to project-wide delivery and reaches every watcher under `<parent-project>`, including the parent.
+If `<parent-session-id>` is unknown (parent didn't pass one), send to the parent's project instead: `--to <handle>@greprag.com/<parent-project>` (no session suffix). That's an intentional project broadcast — every watcher in `<parent-project>` receives it, including the parent. Use sparingly; session-targeting is the default. adr: adr/address-grammar.md
 
 Send the report BEFORE exiting. The parent agent reads `greprag inbox` on its next turn and picks it up — no polling, no manual chasing.
 ```
@@ -98,33 +99,38 @@ Send the report BEFORE exiting. The parent agent reads `greprag inbox` on its ne
 ```
 **After sending the done report, stay reachable for follow-ups:**
 
-Arm a `Monitor` on your own inbox so any directive from main lands as an in-session event. Run this under the **`Monitor`** tool with `persistent: true`:
+Arm a `Monitor` on your own inbox so any directive from main lands as an in-session event. Use the bash-wrapper form — the `while` loop auto-restarts the watcher if the inner SSE process dies (network blip, crash, fork failure). Run this under the **`Monitor`** tool with `persistent: true`:
 
 ```bash
-greprag inbox watch --session <own-session-id> --json
+while true; do greprag inbox watch --session <own-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
 ```
 
 - `<own-session-id>` is the chip's own session UUID — same one passed as `--from-session` in Block 2. The filter narrows the stream to messages aimed at this exact session plus broadcasts; sibling chips watching the same project no longer pollute this feed.
-- If you don't have a session id (older sessions), fall back to `--project <own-project> --json` — wider net but still correct.
+- If you don't have a session id (older sessions), substitute `--project <own-project>` instead of `--session <id>` — wider net but still correct.
 - The chip then idles between events — no token burn, no polling. Each new inbox line = one notification.
+- Restart events go to stderr as `[wrapper] watcher exited…` — visible in the Monitor output file but not as a Monitor notification.
 - When the work is truly done and no follow-up is expected, call `TaskStop` on the Monitor task. Otherwise leave it armed until the session closes.
+- Do NOT drop the `while … done` wrapper. A bare `greprag inbox watch …` will silently end the Monitor task on any inner crash, and any directive sent in the gap is lost until the next user prompt.
 ```
 
 **Why not the Stop hook?** 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.
 
 ## Reply listening (any session, not just chips)
 
-The chip Block 3 pattern generalizes. Any session that sends a message expecting a directive in response should arm a Monitor on its own inbox in the same turn — before the send if you can, so a fast reply doesn't slip past. Use `greprag inbox watch --session <own-session-id> --json`, `persistent: true` (or `--project <own-project>` when no session identity is available). Same reasoning: the Stop hook is best-effort for session-end ingestion; Monitor is the only path that catches mid-task replies.
+The chip Block 3 pattern generalizes. Any session that sends a message expecting a directive in response should arm a Monitor on its own inbox in the same turn — before the send if you can, so a fast reply doesn't slip past. Use the same bash-wrapper form shown in Block 3 (substitute `--project <own-project>` when no session identity is available), `persistent: true`. Same reasoning: the Stop hook is best-effort for session-end ingestion; Monitor is the only path that catches mid-task replies.
 
-**Session scoping replaces the old self-echo workaround.** A `--session` watcher filters incoming traffic to messages whose `to_session_id` matches this session OR is null (broadcasts). A `greprag send --to <own-tenant-email>` (no project, no session) still echoes back as a broadcast and reaches every watcher — but the noise of sibling chips and unrelated project mail is gone. Old guidance: "expect echoes, ignore silently." New guidance: pass `--session <own-session-id>` on the watcher and the only echoes left are genuine broadcasts you actually want to see. To avoid even those, use `--to <email>/<project>/<their-session>` with `--from-session <own-session-id>` and the message lands in exactly one inbox.
+**Session scoping is the default in v0.11.** The send-side address grammar — `<handle>@greprag.com/<session-uuid>` — makes the session the only segment, so messages land in exactly one inbox. Project-name addresses (`<handle>@greprag.com/<project>`) are intentional broadcasts, used only when the sender genuinely means "everyone in this project should hear this." A `--session` watcher still passes broadcasts through (by design, so tenant-wide announcements aren't lost), but with session-targeting as the dominant pattern those broadcasts are now rare and recognizable.
 
 ## Parent-side: watch for the report
 
 If you want the chip's report the instant it lands (not on next turn), start an SSE watcher in the background BEFORE spawning the chip:
 
 ```bash
-greprag inbox watch --session <parent-session-id> --json    # preferred — single chip
-greprag inbox watch --project <parent-project>              # fallback / multi-chip campaigns
+# preferred — single chip (bash wrapper auto-restarts on inner death)
+while true; do greprag inbox watch --session <parent-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
+
+# fallback / multi-chip campaigns
+while true; do greprag inbox watch --project <parent-project>; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
 ```
 
 `--session` is the right default when the chip's Block 2 sends with `--session <parent-session-id>` — exactly one report lands in this watcher per chip. Use `--project` when you've spawned several chips at once and want all their reports on one stream (each chip still tags `--from-session <own-id>`, so the parent reads provenance per message).
@@ -183,7 +189,7 @@ Chip continues
 
 **Communication channels:**
 
-- Main ↔ chip: greprag inbox (`<email>/<parent-project>` ↔ `<email>/<chip-project>`).
+- Main ↔ chip: greprag inbox (`<handle>@greprag.com/<parent-session-id>` ↔ `<handle>@greprag.com/<chip-session-id>`, falling back to `/<project>` only when a session id is unknown).
 - Chip ↔ subagent: direct return value from the `Agent` tool (no inbox needed — same session).
 
 Skip the layering when one Agent call would do — direct dispatch from main is simpler.
@@ -216,9 +222,10 @@ The chip lands NOT to ship code, but to be a context-rich conversation partner f
 
 **Why this beats arguing in main:** orchestrator runs on what it can grep + read in-context. Anything beyond that is plausible-sounding extrapolation. A chip with the repo loaded catches "this coupling exists" / "this billing dependency is non-obvious" / "you missed a callsite" — corrections the orchestrator can't surface itself.
 
-### Picking the slug, model, and subagent_type
+### Picking the title, slug, model, and subagent_type
 
-- **Slug** — kebab-case, short, matches the chip's title. Becomes the worktree branch name (`chip/<slug>`) and the worktree directory (`<project>/.claude/worktrees/<slug>/`).
+- **Title** — ALWAYS prefix with `Chip: ` then the imperative action phrase. Format: `Chip: <verb-phrase>` (e.g. `Chip: Fix stale README badge`, `Chip: Wire Narrow C into core`, `Chip: GR5 collapse style prompts`). The `Chip: ` prefix is non-negotiable — it makes chip-spawned sessions instantly recognizable in the FleetView UI vs. IDE-checkbox-spawned `claude/` sessions and human-driven sessions. The verb phrase MUST NOT itself repeat "chip" — the prefix already marks it as one. Imperative verb phrase under ~50 chars after the prefix.
+- **Slug** — kebab-case, short, matches the post-prefix portion of the title. Becomes the worktree branch name (`chip/<slug>`) and the worktree directory (`<project>/.claude/worktrees/<slug>/`).
 - **Model at the chip layer** — defaults to whatever the FleetView/CCD runtime assigns (currently Opus). `spawn_task` has no model param.
 - **Model at the subagent layer** — pass `model: "sonnet"`/`"haiku"`/`"opus"` to the `Agent` tool. Default to the cheapest that fits the task.
 - **subagent_type** — `Explore` for read-only search, `Plan` for design work, `general-purpose` for execution, `code-reviewer` (if installed) for second opinion. Full list in the `Agent` tool description.
@@ -238,7 +245,7 @@ The chip lands NOT to ship code, but to be a context-rich conversation partner f
 
 - **Block 0 — Pre-spawn checklist.** Auto-fill parent-project name, generate slug from title, dry-run the worktree path for collisions. Reduces the boilerplate the spawning agent has to compose by hand.
 
-**Shipped:** session-scoped routing (`--session` / `--from-session` on `greprag send`, `--session` on `greprag inbox watch`, 3-segment `<email>/<project>/<session-id>` address grammar) — the cleaner-routing solution previously planned as "ephemeral chip-inbox addresses." Lives directly on the canonical session UUID instead of synthesizing a chip-id, so no new address types or registry rows.
+**Shipped:** session-scoped routing via the single-segment address grammar `<handle>@greprag.com/<target>` where `<target>` is a session UUID (normal) or a project name (intentional broadcast). v0.11 dropped the legacy `--session`/`--project` send flags and the 3-segment `email/project/session` address — the address itself now carries the target, so missing-target sends error loudly instead of silently broadcasting. adr: adr/address-grammar.md
 
 ## See also