greprag 0.8.1 → 0.8.3

package/skill/SKILL.md

@@ -12,7 +12,7 @@ description: |
   "what's been happening in this project", "session context".
 metadata:
   author: travsteward
-  version: "3.4.0"
+  version: "3.5.0"
   repository: https://github.com/travsteward/greprag
 license: MIT
 ---
@@ -168,6 +168,8 @@ 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.
 
 **When to populate references vs. when to leave them off:**
 - Short chat messages ("pinging you", "deploy is up", "ack") — no references, just body.
@@ -178,8 +180,11 @@ Flags (all repeatable, all optional):
 Address formats (all valid):
 - `alice@example.com` — recipient's tenant inbox by real email
 - `alice@example.com/paybot` — recipient's paybot project inbox
+- `alice@example.com/paybot/<session-id>` — only the named session under paybot sees it (plus broadcasts). The trailing UUID is case-sensitive — the parser preserves it verbatim.
 - `alice@greprag.com` — same recipient by their auto-claimed greprag handle (tenant_id alias)
 
+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.
+
 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 — Health & repair (when memory looks wrong)
@@ -343,6 +348,67 @@ Otherwise present verbatim:
 
 Do not rewrite or summarize. Present verbatim — the compactor already shaped it.
 
+## Step 6b — Seeding learnings (project-facts substrate)
+
+Whenever you waste tokens *discovering* something a future agent shouldn't have to re-discover, seed it as a project fact. 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:
+
+- **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`.
+
+### How to seed
+
+```bash
+greprag fact add "<one-sentence fact, optionally with a file path>" --scope <scope> [--project <name>]
+```
+
+Examples:
+```bash
+greprag fact add "Migrations live at repo root: migrations/<NNN>_<name>.sql. Apply with node scripts/apply-migration.cjs migrations/<file>.sql." --scope chip-startup
+
+greprag fact 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 fact 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 fact 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` — facts that matter 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 fact about migration paths is `chip-startup` (every chip needs it); a fact about how the hourly compactor's prompt versioning works is `episodic-touch` (only relevant if you're editing that subsystem).
+
+### Reading facts back (pull pattern)
+
+```bash
+greprag fact query --scope chip-startup --limit 10 --format markdown   # for inlining into a chip prompt
+greprag fact query --scope inbox-touch --query "session routing"        # lexical-rank within a scope
+greprag fact query --query "how do migrations apply" --limit 5          # cross-scope, lexical-rank only
+greprag fact list                                                       # human-review every fact, grouped by scope
+greprag fact delete <nodeId>                                            # prune stale fact (nodeId printed in list)
+```
+
+`--format markdown` returns a numbered list with no decoration — drop it straight into a `**Project Facts**` block when spawning a chip.
+
+### Deliberate review
+
+Periodically run `greprag fact list` against a project, especially after a refactor or a major rename. Facts decay as code moves; prune anything stale via `greprag fact delete <nodeId>`. The substrate trusts the seeding agent — there's no auto-dedup or expiry, so the human (or a periodic `/greprag` audit pass) keeps the signal clean.
+
+### Chip-spawn pull pattern
+
+When you compose a `spawn_task` chip prompt, pull `chip-startup` facts into the prompt before dispatching. Full convention lives in `~/.claude/docs/agent-coordination.md` § Block 0.5; the one-liner is: `greprag fact query --scope chip-startup --project <project> --limit 10 --format markdown`, then wrap the output in a `**Project Facts**` 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",