greprag 5.21.0 → 5.22.1

package/scripts/postinstall.js

@@ -1,30 +1,16 @@
 #!/usr/bin/env node
 // Runs automatically after `npm install -g greprag`.
 //
-// Sync model (v5.10.3):
+// Public UX contract:
+//   * `greprag/` — the package's front-door skill. Always installed/refreshed
+//     for detected Claude Code and Codex homes so users can type `/greprag`
+//     immediately after installing the npm package.
+//   * Other bundled skills — refresh-only. If the operator opted in earlier,
+//     keep them current; otherwise leave their skill registry alone.
+//   * Claude chip-spawn doc — refresh-only, because it is Claude-specific.
 //
-//   * `greprag/` — the package's front-door skill. ALWAYS installed +
-//     refreshed. This is the operator's manual for the CLI; without it
-//     the agent has no idea how to drive `greprag` verbs. Treated as
-//     part of the package's identity, not an opt-in advisor.
-//
-//   * Every other bundled skill (`discord/`, `content-advisor/`,
-//     `lore-advisor/`, future advisors) — REFRESH-ONLY. If the operator
-//     opted in (via `greprag skill install <name>` or by accepting the
-//     hint in `greprag init`'s closing summary), the dir exists locally
-//     and we keep it current with the bundle. If they never opted in,
-//     postinstall leaves it alone. Auto-installing every bundled advisor
-//     on upgrade was a design defect — extra skills crowd the agent's
-//     skill registry and should be consensual.
-//
-//   * `chip-spawn.md` doc — refresh-only, same logic as opt-in skills.
-//
-// Closes the staleness gap where `npm i -g greprag@<new>` updated the
-// CLI binary but left `~/.claude/skills/greprag/` files pointing at the
-// old version's expected CLI surface. Without this, the agent's mental
-// model of the CLI drifts away from what the installed binary actually
-// does — see CHANGELOG v5.10.0 (odyssey verb shipped, but local skill
-// stayed at 3.7.0 with no odyssey refs).
+// OpenCode has no slash-skill directory in this package; `greprag init
+// --opencode` installs the plugin.
 
 const fs = require('fs');
 const path = require('path');
@@ -32,8 +18,23 @@ const os = require('os');
 
 const home = os.homedir();
 const skillRoot = path.join(__dirname, '..', 'skill');
-const skillsTarget = path.join(home, '.claude', 'skills');
-const docsTarget = path.join(home, '.claude', 'docs');
+
+const platformTargets = [
+  {
+    name: 'Claude Code',
+    agentDir: path.join(home, '.claude'),
+    skillsTarget: path.join(home, '.claude', 'skills'),
+    docsTarget: path.join(home, '.claude', 'docs'),
+    refreshClaudeDocs: true,
+  },
+  {
+    name: 'Codex',
+    agentDir: path.join(home, '.codex'),
+    skillsTarget: path.join(home, '.codex', 'skills'),
+    docsTarget: path.join(home, '.codex', 'docs'),
+    refreshClaudeDocs: false,
+  },
+];
 
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
@@ -45,39 +46,45 @@ function copyDir(src, dest) {
   }
 }
 
-// `greprag/` always syncs; everything else is opt-in (refresh-only).
 const CORE_SKILL = 'greprag';
-
 const refreshed = [];
 const installed = [];
+const detected = [];
 
 try {
-  if (fs.existsSync(skillRoot) && fs.existsSync(skillsTarget)) {
-    for (const entry of fs.readdirSync(skillRoot, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      if (entry.name === 'templates') continue; // not a skill dir
-      const dest = path.join(skillsTarget, entry.name);
-      const existed = fs.existsSync(dest);
-      const isCore = entry.name === CORE_SKILL;
-      // Core skill: always sync. Opt-in skills: only refresh if already installed.
-      if (!existed && !isCore) continue;
-      copyDir(path.join(skillRoot, entry.name), dest);
-      if (existed) refreshed.push('skills/' + entry.name);
-      else installed.push('skills/' + entry.name);
+  if (fs.existsSync(skillRoot)) {
+    for (const target of platformTargets) {
+      if (!fs.existsSync(target.agentDir)) continue;
+      detected.push(target.name);
+      for (const entry of fs.readdirSync(skillRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name === 'templates') continue;
+
+        const dest = path.join(target.skillsTarget, entry.name);
+        const existed = fs.existsSync(dest);
+        const isCore = entry.name === CORE_SKILL;
+        if (!isCore && !existed) continue;
+
+        copyDir(path.join(skillRoot, entry.name), dest);
+        const label = `${target.name} skills/${entry.name}`;
+        if (existed) refreshed.push(label);
+        else installed.push(label);
+      }
     }
   }
 } catch (err) {
-  // Postinstall must never break the install. Log and continue.
   console.error('  greprag postinstall: skill sync skipped (' + err.message + ')');
 }
 
-// Refresh chip-spawn template doc if installed.
 const chipSpawnSrc = path.join(skillRoot, 'templates', 'chip-spawn.md');
-const chipSpawnDest = path.join(docsTarget, 'chip-spawn.md');
 try {
-  if (fs.existsSync(chipSpawnSrc) && fs.existsSync(chipSpawnDest)) {
-    fs.copyFileSync(chipSpawnSrc, chipSpawnDest);
-    refreshed.push('docs/chip-spawn.md');
+  for (const target of platformTargets) {
+    if (!target.refreshClaudeDocs) continue;
+    const chipSpawnDest = path.join(target.docsTarget, 'chip-spawn.md');
+    if (fs.existsSync(chipSpawnSrc) && fs.existsSync(chipSpawnDest)) {
+      fs.copyFileSync(chipSpawnSrc, chipSpawnDest);
+      refreshed.push(`${target.name} docs/chip-spawn.md`);
+    }
   }
 } catch (err) {
   console.error('  greprag postinstall: chip-spawn refresh skipped (' + err.message + ')');
@@ -88,5 +95,13 @@ if (changes.length > 0) {
   const verb = installed.length > 0 ? 'Synced' : 'Refreshed';
   console.log('\n  greprag installed. ' + verb + ': ' + changes.join(', ') + '\n');
 } else {
-  console.log('\n  greprag installed. Run `greprag init` to connect Claude Code memory.\n');
+  console.log('\n  greprag installed. Run `greprag init` to connect Claude Code, Codex, or OpenCode memory.\n');
+}
+
+if (detected.includes('Codex')) {
+  console.log('  Detected Codex. Next:');
+  console.log('    greprag init --codex --tenant-id <your-handle> --install-watcher');
+  console.log('  Example:');
+  console.log('    greprag init --codex --tenant-id tanya --install-watcher');
+  console.log('  Then open Codex Desktop Settings -> Settings -> Hooks and trust the 6 GrepRAG hooks.\n');
 }

package/skill/greprag/SKILL.md

@@ -25,7 +25,10 @@ license: MIT
 
 Single source of truth: `greprag status --json`. Check it → fix any gaps via `docs/setup.md` → search or recap the project's memory.
 
-OpenCode users: see `docs/setup.md § opencode` for plugin install (`greprag init --opencode`).
+Platform setup is progressive:
+- **Codex**: see `docs/setup.md § codex` after install (`greprag init --codex --tenant-id <handle> --install-watcher`, then Codex Desktop Settings -> Settings -> Hooks trust review).
+- **Claude Code**: see `docs/setup.md § claude-code` for the default hook/Monitor/conventions path (`greprag init --claude` or detected `greprag init`).
+- **OpenCode**: see `docs/setup.md § opencode` for plugin install (`greprag init --opencode`).
 
 ## Step 1 — Status
 
@@ -38,7 +41,16 @@ Parse JSON. Inspect in order:
 2. `project.anchor_found`
 3. `project.memory_capture`, `project.session_start_recap`, `project.inbox_notify`
 
-For Claude Code, also: `hooks.session_start_recap`, `hooks.stop_store`, `hooks.post_tool_use_spawn_reminder`.
+For Claude Code, also: `platforms.claude.configured`, `platforms.claude.hooks.session_start_recap`, `platforms.claude.hooks.stop_store`, `platforms.claude.hooks.pre_tool_use_spawn_check`.
+
+For OpenCode, also: `platforms.opencode.configured`, `platforms.opencode.plugin_installed`.
+
+For Codex, also inspect:
+```bash
+node -e "const fs=require('fs'),os=require('os'),p=require('path');const hp=p.join(os.homedir(),'.codex','hooks.json');const envp=p.join(os.homedir(),'.greprag','.env');let h={};try{h=JSON.parse(fs.readFileSync(hp,'utf8'))}catch{};const has=(evt,cmd)=>((h.hooks&&h.hooks[evt])||[]).some(e=>(e.hooks||[]).some(x=>(x.command||'').includes(cmd)));console.log(fs.existsSync(envp)?'CODEX_ENV_OK':'CODEX_ENV_MISSING');console.log(has('UserPromptSubmit','codex-notify')?'CODEX_NOTIFY_OK':'CODEX_NOTIFY_MISSING');console.log(has('PostToolUse','codex-inbox')?'CODEX_INBOX_OK':'CODEX_INBOX_MISSING');console.log(has('Stop','codex-store')?'CODEX_STORE_OK':'CODEX_STORE_MISSING');console.log(has('SessionStart','recap')?'CODEX_RECAP_OK':'CODEX_RECAP_MISSING');"
+```
+
+If any Codex check is missing, route to `docs/setup.md § codex`. If hooks exist but memory is not being captured, remind the user to open Codex Desktop Settings -> Settings -> Hooks, trust the 6 GrepRAG commands, and start a fresh session.
 
 Chip-spawn convention marker (in `~/.claude/CLAUDE.md`):
 ```bash
@@ -59,6 +71,7 @@ node -e "const s=JSON.parse(require('fs').readFileSync(require('os').homedir()+'
 |---|---|
 | `auth.api_key_present === false` | `docs/setup.md § auth` |
 | Any hook is false | `docs/setup.md § hooks` |
+| Any Codex check is missing, or hooks installed but not firing | `docs/setup.md § codex` |
 | Convention marker missing/outdated, or `DOC_MISSING` | `docs/setup.md § conventions` |
 | `MON_MISSING` | `docs/setup.md § permissions` |
 | `project.anchor_found === false` | `docs/setup.md § anchor` |
@@ -106,13 +119,18 @@ Aliases (silent back-compat): `greprag memory briefing` → `recap` (renamed v5.
 
 ## Proactive-fire rules
 
-**ABOUT TO BACKGROUND A `greprag inbox watch`? USE THE `Monitor` AGENT TOOL, NOT `Bash(run_in_background: true)`.** Bash background notifies only on process completion; watchers run forever, so the agent gets zero events until it manually reads the output file. Wrap with `while true; do greprag inbox watch ...; done` so the loop survives inner crashes. Full pattern: `docs/inbox-watch.md`.
+**Claude Code: ABOUT TO BACKGROUND A `greprag inbox watch`? USE THE `Monitor` AGENT TOOL, NOT `Bash(run_in_background: true)`.** Bash background notifies only on process completion; watchers run forever, so the agent gets zero events until it manually reads the output file. Wrap with `while true; do greprag inbox watch ...; done` so the loop survives inner crashes. Full pattern: `docs/inbox-watch.md`.
+
+**Codex: DO NOT CLAIM HOOKS ARE ACTIVE JUST BECAUSE `~/.codex/hooks.json` EXISTS.** Codex Desktop requires Settings -> Settings -> Hooks trust review before command hooks run automatically. If turn capture is missing after `greprag init --codex`, tell the user: open Codex Desktop Settings -> Settings -> Hooks, trust the 6 GrepRAG hooks, then start a fresh Codex session.
+
+**Codex live inbox push requires the startup watcher.** Hooks only fire at Codex turn/tool/session boundaries. Public installs should use `greprag init --codex --tenant-id <handle> --install-watcher`; run `greprag codex doctor` to inspect state, and use `greprag codex watch --session <id>` only for foreground testing. The sidecar listens to GrepRAG inbox SSE and wakes Codex via `codex exec resume`. Without it, messages are stored but idle Codex is not woken.
 
 **ABOUT TO SEND TO A `@gmail.com` / `@anthropic.com` / REAL EMAIL ADDRESS? STOP — `users.email` IS NEVER A ROUTING ADDRESS.** Use the numeric handle (`1834729@greprag.com`) or claimed vanity alias (`travis@greprag.com`). If you don't know the recipient's handle, ASK — don't guess from their email. adr: adr/numeric-handles.md. Full grammar: `docs/inbox.md § address`.
 
 ## Reference index
 
-- `docs/setup.md` — auth · hooks · conventions · permissions · channels · anchor · opencode · bulk-register
+- `docs/setup.md` — codex · claude-code · opencode · auth · hooks · conventions · permissions · channels · anchor · bulk-register
+- `docs/platforms.md` — exact platform paths for Claude Code · Codex · OpenCode
 - `docs/per-project-flags.md` — flip `memory_capture` / `session_start_recap` / `inbox_notify`
 - `docs/inbox.md` — `greprag send`, `greprag inbox`, address grammar, retract
 - `docs/inbox-watch.md` — SSE watcher patterns, liveness model, parent-side / post-send patterns

package/skill/greprag/docs/doctor.md

@@ -11,7 +11,7 @@ What it does:
 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
+   - **Migrate to git-derived UUID** (recommended on drift) — moves current + orphan rows onto the git-derived ID and strips `project_id` from the project anchor 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
 

package/skill/greprag/docs/setup.md

@@ -2,6 +2,87 @@
 
 Routes for each gap surfaced by `greprag status --json`. Re-run status after each fix and continue down the list.
 
+## codex
+
+Codex users install once:
+
+```bash
+greprag init --codex --tenant-id <your-handle> --install-watcher
+```
+
+Example: `greprag init --codex --tenant-id tanya --install-watcher`.
+The handle is public identity: `tanya` becomes `tanya@greprag.com`.
+
+This writes `~/.greprag/.env` plus `~/.codex/hooks.json`. The Codex hooks are:
+
+- `SessionStart` → `greprag-hook recap`
+- `SessionStart` → `greprag-hook session-id`
+- `UserPromptSubmit` → `greprag-hook codex-notify`
+- `PostToolUse` → `greprag-hook codex-inbox`
+- `Stop` → `greprag-hook codex-store`
+- `PostCompact` → `greprag-hook session-id`
+
+It also installs the bundled `/greprag` skill at
+`~/.codex/skills/greprag` and refreshes the shared identity cache at
+`~/.greprag/identity.json`.
+
+Interactive init offers to install the live inbox watcher at login. In
+non-interactive contexts, pass `--install-watcher` or run it explicitly:
+
+```bash
+greprag codex startup install
+```
+
+After install, Codex still requires trust review. Tell the user:
+
+> Open Codex Desktop Settings -> Settings -> Hooks, trust the 6 GrepRAG hooks,
+> then start a fresh Codex session.
+
+Do not try to approve hooks on the user's behalf. This is Codex Desktop's trust
+gate for local command execution.
+
+Codex-specific diagnostics:
+
+```bash
+greprag codex doctor
+test -f ~/.greprag/.env && echo CODEX_ENV_OK || echo CODEX_ENV_MISSING
+test -f ~/.codex/hooks.json && echo CODEX_HOOKS_FILE_OK || echo CODEX_HOOKS_FILE_MISSING
+node -e "const fs=require('fs'),os=require('os'),p=require('path');const hp=p.join(os.homedir(),'.codex','hooks.json');let h={};try{h=JSON.parse(fs.readFileSync(hp,'utf8'))}catch{};const has=(evt,cmd)=>((h.hooks&&h.hooks[evt])||[]).some(e=>(e.hooks||[]).some(x=>(x.command||'').includes(cmd)));console.log(has('UserPromptSubmit','codex-notify')?'CODEX_NOTIFY_OK':'CODEX_NOTIFY_MISSING');console.log(has('PostToolUse','codex-inbox')?'CODEX_INBOX_OK':'CODEX_INBOX_MISSING');console.log(has('Stop','codex-store')?'CODEX_STORE_OK':'CODEX_STORE_MISSING');console.log(has('SessionStart','recap')?'CODEX_RECAP_OK':'CODEX_RECAP_MISSING');console.log(has('PostCompact','session-id')?'CODEX_POSTCOMPACT_OK':'CODEX_POSTCOMPACT_MISSING');"
+```
+
+If hook entries are missing, re-run `greprag init --codex`. If entries exist
+but turns are not saving, the most likely cause is untrusted hooks or an old
+session that started before trust. Tell the user to open Codex Desktop Settings
+-> Settings -> Hooks, trust the 6 GrepRAG commands, and restart Codex.
+
+Codex live inbox delivery requires the sidecar. Public installs should use the
+startup helper above. For foreground/manual testing:
+
+```bash
+greprag codex watch --session <8hex-or-full-codex-session-id>
+```
+
+If `--session` is omitted, it uses the latest Codex session recorded in
+`~/.codex/session_index.jsonl`. The sidecar stays attached to GrepRAG inbox SSE
+and wakes Codex with `codex exec resume <session> -` whenever a message arrives.
+Use `greprag codex startup status` to inspect the login entry and
+`greprag codex startup remove` to uninstall it.
+
+`codex-notify` and `codex-inbox` remain fallback steering. If the sidecar is not
+running, messages are stored and can surface on the next user prompt or after a
+later tool call, but they do not wake idle Codex.
+
+## claude-code
+
+Claude Code users install once:
+
+```bash
+greprag init --claude
+```
+
+Bare `greprag init` may auto-detect Claude Code or ask which platform to
+configure. The explicit flag is best for docs and scripts.
+
 ## opencode
 
 OpenCode users install once:
@@ -10,7 +91,12 @@ OpenCode users install once:
 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.
+Plugin at `~/.config/opencode/plugins/greprag-memory.js` runs silently:
+injects recap via system prompt and stores turns automatically. It reads
+`~/.greprag/.env` first and falls back to `~/.claude/settings.json` for older
+installs. All platforms share the same anchor (`.greprag/project.json` or
+git-derived identity). Legacy `.claude/project.json` anchors still read and
+migrate on init.
 
 ## bulk-register
 
@@ -45,11 +131,17 @@ Trigger: `auth.api_key_present === false`.
    ```
    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.
+5. Write the key into the platform's config:
+   - Claude Code: `~/.claude/settings.json` under `env.GREPRAG_API_KEY`; also set `env.MEMORY_HOOK_ENABLED = "true"`.
+   - Codex/OpenCode: `~/.greprag/.env` with `GREPRAG_API_KEY=<key>` and `MEMORY_HOOK_ENABLED=true`.
+
+Prefer re-running the platform init command (`greprag init --claude`, `--codex`, or `--opencode`) because it writes the right files and refreshes identity/platform assets.
 
 ## hooks
 
-Trigger: any of `hooks.session_start_recap`, `hooks.stop_store`, `hooks.post_tool_use_spawn_reminder` is false.
+Trigger: any of `platforms.claude.hooks.session_start_recap`,
+`platforms.claude.hooks.stop_store`, or
+`platforms.claude.hooks.pre_tool_use_spawn_check` 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.
 
@@ -69,7 +161,7 @@ Append missing entries to the existing arrays in `~/.claude/settings.json` (crea
 
 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.
+**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 handled by `UserPromptSubmit` watcher steering plus the PreToolUse validator.
 
 ## conventions
 
@@ -184,8 +276,8 @@ If yes, use the existing `project_id` in the new anchor. If no, mint fresh: `nod
 
 Write the file:
 ```bash
-mkdir -p <cwd>/.claude
-cat > <cwd>/.claude/project.json <<EOF
+mkdir -p <cwd>/.greprag
+cat > <cwd>/.greprag/project.json <<EOF
 {
   "project_id": "<UUID>",
   "project_name": "<basename, lowercased>",

package/skill/lore-advisor/SKILL.md

@@ -1,37 +1,56 @@
 ---
 name: lore-advisor
 description: |
-  Audit project lore for drift, mine episodic memory for emergent learnings,
-  promote project-agnostic lore to global. One-at-a-time conversational
+  Digest the smell queue (raw field signals → fix the broken mechanism + instantiate
+  durable lore), audit project lore for drift, mine episodic memory for emergent
+  learnings, promote project-agnostic lore to global. One-at-a-time conversational
   review — never bulk-prune.
 
-  Trigger phrases: "/lore-advisor", "/lore", "review my lore", "audit lore",
-  "lore is stale", "prune lore", "mine episodic for lore".
+  Trigger phrases: "/lore-advisor", "/lore", "digest smells", "drain the smell queue",
+  "any smells", "review my lore", "audit lore", "lore is stale", "prune lore",
+  "mine episodic for lore".
 metadata:
   author: travsteward
-  version: "1.0.0"
+  version: "1.2.0"
   repository: https://github.com/travsteward/greprag
 license: MIT
 ---
 
 # Lore Advisor
 
-Project lore = LEARNINGS (emergent, drift-prone observations seeded via `greprag lore add`). Distinct from static project knowledge (CLAUDE.md, docs, code structure). Lore decays — paths change, conventions die, "learned that X" stops being true. This skill keeps the substrate healthy.
+Project lore = durable LEARNINGS — reusable system properties, constraints, and gotchas worth re-surfacing in a future session. Seeded via `greprag lore add`, mined from episodic memory's `learned` / `ruled_out` claims. Distinct from static project knowledge (CLAUDE.md, docs, code) AND from session narration / transient run-state. Lore decays — paths change, conventions die, "learned that X" stops being true. This skill keeps the substrate healthy.
 
-The skill is **conversational**, not autonomous. Every prune / promote / edit decision goes through the operator one at a time. Bulk actions are forbidden.
+**The advisor's core skill is one judgment: durable lore vs ephemeral noise.** Episodic memory is a firehose — only ~1 claim in 10 is durable lore; the rest is session narration, run-state, or docs material. No regex finds the keepers; the advisor's read does. The durability gate below makes that judgment explicit.
+
+Lore is moving from a passive list toward **event-bound / semantic injection** — pushed at the agent when relevant, not browsed (greprag design: `docs/lore-triggers.md`). Until PUSH ships, add lore durable-first so it is injection-ready.
+
+The skill is **conversational**, not autonomous. Every prune / promote / edit / add decision goes through the operator one at a time. Bulk actions are forbidden.
+
+**Two feeds, one digestion.** Lore now has two supplies: the *deliberate* smell queue (`greprag lore smell`, raw field signals — `docs/lore-smell.md`) and the *automatic* episodic `learned` / `ruled_out` claims. Phase 0 drains the smell queue first; Phase B mines episodic. Both pass through the same durability gate — but a smell additionally asks whether a broken **mechanism** in the harness needs fixing (the fix ladder in Phase 0), not just whether a durable truth needs recording.
 
 ## Trigger phrases
 
-`/lore-advisor`, `/lore`, "review my lore", "audit lore", "lore is stale", "prune lore", "mine episodic for lore".
+`/lore-advisor`, `/lore`, "digest smells", "drain the smell queue", "any smells", "review my lore", "audit lore", "lore is stale", "prune lore", "mine episodic for lore".
 
 ## What it does
 
-Three phases, run in order. Operator may skip any phase. Each phase walks one entry at a time — never bulk-prune.
+Four phases, run in order (Phase 0 first). Operator may skip any phase. Each phase walks one entry at a time — never bulk-prune.
 
-- **Phase A — Drift check.** Heuristic scan of current lore for stale file paths, references to killed conventions, age-based decay.
-- **Phase B — Episodic mining.** Scan recent daily summaries for sentences signalling new learnings; offer to promote to lore.
+- **Phase 0 — Smell digestion.** Drain the raw smell queue (`greprag lore smells`): per smell, fix the broken mechanism (hooks first, code second) and/or instantiate the durable truth, then retire it. Deliberate field signals outrank auto-mined claims, so this runs first.
+- **Phase A — Drift check.** Scan current lore for rot: stale file paths, conventions the codebase no longer follows (derived live, NOT from a static list), misfiled static-knowledge, age-based decay.
+- **Phase B — Episodic mining.** Mine episodic memory's `learned` / `ruled_out` claims; surface only candidates that pass the durability gate; offer to add.
 - **Phase C — Global promotion.** Identify project-agnostic lore that belongs in `~/.claude/docs/chip-spawn.md` as a universal rule.
 
+## The durability gate (core discipline)
+
+Before lore is kept (Phase A), added (Phase B), or promoted (Phase C), it must pass three tests. Fail ANY → it is not lore.
+
+1. **DURABLE** — a standing property, rule, constraint, or gotcha true beyond one session. NOT point-in-time state. ✗ "no watcher was running", "the id was still e582edf0", "the corpus is proven end-to-end".
+2. **REUSABLE** — would help a FUTURE session understand the system or avoid a mistake. NOT narration of work done. ✗ "Chip C split corpus.ts into eight modules", "the CLI was bumped to v5.16.0". Abstract instances to rules: "sub 3006's price is archived" → "an inactive Stripe price blocks dunning-recovery".
+3. **NON-OBVIOUS** — a property you could not read off the surface. ✓ "Postgres caps a statement at 65,535 bind parameters". ✗ "the API runs on Cloudflare Workers" (ambient project knowledge → belongs in docs, not lore).
+
+This is the same gate the hourly compactor applies at write-time (greprag, 2026-06-01) — advisor and compactor converge on one filter.
+
 ## Forbidden practices (HARD RULES)
 
 - **Never delete lore without explicit operator confirmation.** Each delete is its own y/n.
@@ -41,6 +60,54 @@ Three phases, run in order. Operator may skip any phase. Each phase walks one en
 
 ## Phases
 
+### Phase 0 — Smell digestion
+
+Smells are the *deliberate* lore feed: raw, undigested signals dropped from the field via `greprag lore smell` (`docs/lore-smell.md`). Unlike an episodic claim, a smell often names a **broken mechanism in the harness**, not just a fact. Digestion does two jobs per smell — **fix** the mechanism and **instantiate** the durable truth — and runs FIRST, because a deliberate signal outranks auto-mined claims.
+
+1. Pull the queue:
+   ```bash
+   greprag lore smells --format json
+   ```
+   Parse `smells[]` (`nodeId`, `text`, `createdAt`). Empty → say "No smells awaiting digestion." and move to Phase A.
+
+2. Walk one smell at a time. First **untangle** it — a single drop often conflates several mechanisms and truths (e.g. a dead-mailbox bug AND a "re-task ≠ launch a chip" insight). Separate them before triaging.
+
+3. For each, **investigate** (reproduce / read the relevant code or hooks to confirm it's real), then ask the two questions:
+
+   - **Is there a broken MECHANISM?** Fix it via the **fix ladder** — lowest rung that holds the fix:
+     1. **First pass — fix it in the hooks.** A PreToolUse guard, a UserPromptSubmit injection, a notification. Cheapest, reversible, and the same machinery as lore-triggers — ships as DATA, no deploy. Most mechanism smells resolve here.
+     2. **Second pass — fancier coding.** Only when a hook can't express the fix: server-side logic, a bounce, a schema or CLI change. The advisor does NOT implement code-tier fixes inline — spawn a chip (`spawn_task`, per `~/.claude/docs/chip-spawn.md`) or hand to the operator.
+
+     If the fix is architectural (a recurring failure class), route through `/root-cause` — fix the pattern that makes the bug possible, never slap a guard on today's trigger.
+
+   - **Is there a durable TRUTH?** Apply the durability gate (below). If it passes, instantiate as durable lore — and, once triggers ship, attach its injection rule (`docs/lore-triggers.md`):
+     ```bash
+     greprag lore add "<clean standing rule>" --scope <scope>
+     ```
+
+4. **Summarize + confirm before ANY action** — a smell is a brief, and the hard rule is the advisor never auto-acts on a brief. Present:
+   ```
+   SMELL [<nodeId>] (<date>)
+     "<text>"
+   Triage:
+     • mechanism: <...>  → fix: [hook|code|root-cause] <proposal>
+     • truth:     <...>  → lore: "<rule>"  scope=<s>
+   Action? (f)ix / (i)nstantiate / (b)oth / (s)kip / (n)oise
+   ```
+   - **fix** → apply the hook-tier fix (after confirm), or spawn the chip for a code-tier fix.
+   - **instantiate** → `greprag lore add "<rule>" --scope <scope>` with the durability-gated rule.
+   - **both** → fix and instantiate.
+   - **skip** → leave the smell in the queue for a later pass (no retire).
+   - **noise** → already-handled or not real; retire without action.
+
+5. **Retire** only once the smell's content is preserved — the fix landed, a durable lore entry captures the constraint, OR a chip/TODO owns the code-tier fix. Never retire a smell whose fix is merely *planned*. Retire = delete (interim, until a real `status` field exists):
+   ```bash
+   greprag lore delete <nodeId>
+   ```
+   Confirm by printing `Retired smell [<nodeId>].`
+
+6. Phase summary: `Phase 0: N smells. Fixed F (H hooks, C chips). Instantiated I. Skipped S. Noise X.`
+
 ### Phase A — Drift check
 
 1. Pull the current project's lore as JSON:
@@ -57,17 +124,13 @@ Three phases, run in order. Operator may skip any phase. Each phase walks one en
      ```
      If MISSING → flag with `reason: "file-not-found:<path>"`.
 
-   - **Killed-convention check.** Match the lore text against this drift list:
-     - `Block 3` / `Block-3` (the old 3-block chip protocol)
-     - `<email>/<project>/<session-id>` or `/<email>/<project>/<session>` (legacy 3-segment address grammar — replaced by 1-segment in v0.11)
-     - `spawn-reminder` (PostToolUse hook removed in v0.12)
-     - `cp $main_root/.env` or `cp .env` from main into worktree (replaced by inline `set -a; source`)
-     - `agent-coordination.md` (deep doc deleted in v5.6.0; replaced by `chip-spawn.md`)
-     - `inline-conventions` / `greprag-conventions:start v1`, `v2`, `v3`, `v4` (superseded by v5 pointer)
-     - `MEMORY_HOOK_ENABLED` legacy boolean (now ambient)
-     - `greprag fact` (renamed to `greprag lore` in v5.7.0 — the alias is removed in v5.8.0)
+   - **Killed-convention check.** A convention can die — a renamed command, a replaced address grammar, a removed hook. The drift signal is NOT a hardcoded list: a static list of dead conventions rots like any other frozen artifact (it has no provenance and no one maintains it — the exact failure this skill exists to fight). Derive it live instead. Cross-reference the lore text against recent `ruled_out` claims and the project CHANGELOG / releases:
+     ```bash
+     greprag memory search "<key term> renamed OR removed OR replaced OR deprecated"
+     ```
+     If the lore asserts a convention the codebase no longer follows → flag `reason: "dead-convention"`.
 
-     Any match → flag with `reason: "dead-convention:<which>"`.
+   - **Misfiled-convention check.** Flag lore that is really *static project knowledge* — a build/deploy command, a file-path map, an architecture rule, a coding standard — which belongs in CLAUDE.md / `docs/`, not in decay-prone lore. This is the most common rot: a bulk seed of conventions poured into lore that then drifts out of sync with the docs (it fails the durability gate's REUSABLE/NON-OBVIOUS tests — it is ambient knowledge, usually already documented elsewhere). Flag `reason: "misfiled-convention"`.
 
    - **Age check.** If `createdAt` is older than 90 days from today AND no other heuristic fired, flag with `reason: "age-90d:<days>"`. Not automatically stale — just worth re-verifying.
 
@@ -90,45 +153,38 @@ Three phases, run in order. Operator may skip any phase. Each phase walks one en
 
 ### Phase B — Episodic mining
 
+The richest lore source is the compactor's structured `learned` / `ruled_out` claims (tagged nodes, one per durable learning). As of greprag 2026-06-01 the hourly compactor applies the durability gate at write-time, so these claims are already durable-first — but the advisor's read is still what separates lore-grade from the rest.
+
 1. Resolve the current project's `projectId`:
    ```bash
    greprag project-id
    ```
 
-2. Pull the last 30 days of daily summaries:
+2. Pull recent episodic memory (last 30 days). Claims are not yet exposed via a dedicated CLI surface, so mine the daily/hourly summaries — which now carry the compactor's durable claims:
    ```bash
    FROM=$(date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-30d +%Y-%m-%dT%H:%M:%SZ)
    TO=$(date -u +%Y-%m-%dT%H:%M:%SZ)
    curl -sf "https://api.greprag.com/v1/memory/by-period?projectId=<projectId>&type=daily&from=$FROM&to=$TO&limit=30" \
      -H "Authorization: Bearer $GREPRAG_API_KEY"
    ```
-   Parse `rows[]`. Each row has `created_at`, `body`.
-
-3. For each daily summary, scan the body for sentences containing any of these marker phrases (case-insensitive):
-   - `learned that`
-   - `the gotcha is`
-   - `won't work because`
-   - `had to`
-   - `discovered that`
-   - `turns out`
-   - `surprised that`
+   Parse `rows[]` (`created_at`, `body`). *(When a `greprag memory claims --tag learned,ruled_out` surface exists, prefer it — it returns the structured claims directly, no prose scan.)*
 
-   Extract the full sentence containing the marker (sentence boundary = `. ` / `! ` / `? ` or newline). Skip sentences shorter than 30 chars or longer than 300 chars.
+3. Find candidate learnings — sentences signalling a durable property. Markers: `learned that`, `the gotcha is`, `won't work because`, `turns out`, `requires`, `only … if`, `caps at`, `blocks`. Skip < 30 or > 300 chars.
 
-4. Present candidates one at a time:
+4. **Apply the durability gate to every candidate.** Most fail — that is correct and expected (~90% of raw learnings are not lore). Surface ONLY candidates that pass all three tests, one at a time:
    ```
-   Daily summary from <YYYY-MM-DD> contains:
+   Candidate (durable · reusable · non-obvious):
      "<sentence>"
-   Promote to lore? (k)eep / (e)dit / (s)kip
+   Add to lore? (a)dd / (e)dit / (s)kip
    ```
-   - **keep** → ask for the scope (suggest `chip-startup` if the sentence mentions paths/build/test; `general` otherwise; `env` if it mentions env vars / credentials). Then:
+   - **add** → ask for scope (`general`; `env` for credentials/vars; or a `<subsystem>-touch` tag naming the moment it would be injected). Then:
      ```bash
      greprag lore add "<sentence>" --scope <scope>
      ```
-   - **edit** → ask for the polished text, then add with chosen scope.
+   - **edit** → polish to a clean standing rule (abstract any instance → rule), then add.
    - **skip** → no-op.
 
-5. Phase summary: `Phase B: scanned N daily summaries, found M candidates. Added A to lore. Skipped S.`
+5. Phase summary: `Phase B: scanned N summaries, M passed the durability gate. Added A. Skipped S.`
 
 ### Phase C — Global promotion
 
@@ -165,19 +221,21 @@ Three phases, run in order. Operator may skip any phase. Each phase walks one en
 After all three phases, print one combined line:
 
 ```
-Reviewed N lore. Pruned X. Edited Y. Added Z from episodic. Promoted W to global.
+Digested D smells (fixed F, instantiated I). Reviewed N lore. Pruned X. Edited Y. Added Z from episodic. Promoted W to global.
 ```
 
 If any phase was skipped (operator pressed q / Ctrl-C / typed "skip phase"), include `(phase <X> skipped)` per skipped phase.
 
 ## When this skill should be invoked
 
-- Operator types `/lore-advisor` or `/lore`.
+- Operator types `/lore-advisor` or `/lore`, or says "digest smells," "drain the smell queue," "any smells."
+- The `⚠ N smells awaiting digestion` footer fires on a greprag command — the smell-queue nudge. Offer to run Phase 0.
 - Operator says "audit my lore," "lore is stale," "prune lore," "mine episodic for lore," "any new learnings worth saving?"
-- Proactively offer the skill at the end of a `/greprag` briefing if `greprag lore list` shows entries older than 90 days OR if the operator just finished a refactor / rename and lore drift is likely.
+- Proactively offer the skill at the end of a `/greprag` briefing if `greprag lore smells` is non-empty, if `greprag lore list` shows entries older than 90 days, OR if the operator just finished a refactor / rename and lore drift is likely.
 
 ## Notes
 
 - This skill is operator-driven. Each phase pauses for input. Don't batch decisions — that defeats the purpose.
-- For new lore added in Phase B, prefer the original sentence verbatim unless it's awkward. The compactor already polished it.
+- For new lore added in Phase B, prefer the compactor's phrasing — but rewrite to a clean standing rule when it embeds an instance ("sub 3006…") or transient framing.
 - For Phase C promotions, prefer the original phrasing too — but rewrite if the lore embeds a project-specific noun that needs generalizing.
+- **Convergence:** the compactor's write-time durability gate (greprag `docs/episodic-memory-changelog.md`, 2026-06-01) and this skill's gate are the same filter. As the compactor tightens, Phase B's yield rises and this skill shifts from "find lore" toward "wire lore to its injection trigger" (`docs/lore-triggers.md`).