@tekmidian/pai 0.8.0 → 0.8.1

package/ARCHITECTURE.md

@@ -1,4 +1,4 @@
-# PAI Knowledge OS — Architecture
+# PAI Knowledge OS — Architecture (v0.8.0)
 
 Technical reference for PAI's architecture, database schema, CLI commands, and development setup.
 
@@ -151,7 +151,7 @@ If both commands return healthy output, PAI is running. Open a new Claude Code s
 
 ## MCP Server
 
-PAI exposes 9 tools, 18 on-demand prompts (skills), and 11 reference resources to Claude Code via a daemon-backed MCP shim. The shim speaks stdio (what Claude Code expects) and proxies each request to the background daemon over NDJSON on a Unix socket.
+PAI exposes 9 tools, 19 on-demand prompts (skills), and 11 reference resources to Claude Code via a daemon-backed MCP shim. The shim speaks stdio (what Claude Code expects) and proxies each request to the background daemon over NDJSON on a Unix socket.
 
 ```
 Claude Code (stdio)
@@ -207,6 +207,7 @@ The MCP server registers 18 prompts that Claude can invoke as on-demand skills.
 | `name` | Session and project naming conventions |
 | `observability` | Observation system usage and querying |
 | `plan` | Forward-looking planning from TODOs and recent activity |
+| `reconstruct` | Retroactively create session notes from JSONL transcripts and git history |
 | `research` | Structured research methodology |
 | `review` | Retrospective review of work over a time period |
 | `route` | Session note routing across projects |
@@ -467,6 +468,8 @@ The PAI daemon is a persistent background service that handles indexing, embeddi
 - Proxies all MCP tool calls from the shim to PostgreSQL
 - Re-indexes all active projects on a configurable interval (default: every 5 minutes)
 - Generates text embeddings asynchronously using Snowflake Arctic Embed (768-dim)
+- Processes the persistent work queue: session summaries, topic detection, note updates
+- Spawns headless Claude CLI processes for AI-powered session summarization
 
 ### Configuration
 
@@ -497,6 +500,62 @@ The daemon runs under the label `com.pai.pai-daemon`. The plist is installed to
 
 ---
 
+## Work Queue and Session Summary Pipeline
+
+The daemon owns a persistent work queue (`~/.config/pai/work-queue.json`) that decouples hook triggers from actual work. Hooks push lightweight work items to the queue and exit immediately. The daemon processes items sequentially from a background worker loop.
+
+### Work Item Types
+
+| Type | Who enqueues | Who processes | Description |
+|------|-------------|---------------|-------------|
+| `session-summary` | PreCompact, Stop hooks | `session-summary-worker.ts` | AI-powered summarization of JSONL transcript + git history |
+| `topic-detect` | PreCompact hook | `topic-detect-worker.ts` | BM25-based topic shift detection for note splitting |
+| `session-end` | Stop hook | `work-queue-worker.ts` | General session cleanup coordination |
+| `note-update` | Session summary worker | `work-queue-worker.ts` | Write or update a session note file |
+| `todo-update` | Session summary worker | `work-queue-worker.ts` | Update TODO.md with session state |
+
+Work items are retried with exponential backoff (default max 3 attempts). The queue is written atomically (write temp file, then rename) to prevent corruption on daemon restart.
+
+### Session Summary Pipeline
+
+```
+Stop or PreCompact hook fires
+    │
+    ├── Hook reads minimal data (session_id, transcript_path, cwd)
+    ├── Hook pushes { type: "session-summary", payload: {...} } to work queue
+    └── Hook exits (sub-second)
+
+    ⬇ Daemon worker loop picks up the item
+
+session-summary-worker.ts
+    │
+    ├── Reads JSONL transcript (500K limit for stop, 200K for compact)
+    ├── Reads recent git log (last 20 commits)
+    ├── Strips ANTHROPIC_API_KEY from environment
+    ├── Spawns headless Claude CLI (Opus for stop, Sonnet for compact)
+    ├── Prompt requests: TOPIC: line + Work Done / Key Decisions / Known Issues / Next Steps
+    ├── Compares TOPIC: against existing note title (Jaccard similarity < 30% → new note)
+    └── Writes or updates session note in project's Notes directory
+
+    ⬇ If topic-detect was also enqueued
+
+topic-detect-worker.ts
+    │
+    ├── Extracts recent user messages from JSONL
+    ├── Runs BM25 topic shift detector against PAI memory DB
+    └── Records topic boundary marker (used by next session-summary run)
+```
+
+### Cooldown and Force Flags
+
+A 30-minute cooldown prevents redundant summary updates during active sessions. The Stop hook sets a `force: true` flag to bypass the cooldown, ensuring the final session state is always written. The PreCompact hook respects the cooldown to avoid O(n) summarizations during rapid compaction cycles.
+
+### Claude Binary Discovery
+
+The daemon runs under launchd with a minimal PATH. The `findClaudeBinary()` function checks `~/.local/bin/claude` first, then falls back to standard PATH resolution. This handles the common case where Claude CLI is installed via the npm global prefix, which launchd does not include in its environment PATH.
+
+---
+
 ## Obsidian Bridge
 
 PAI can expose your project memory as an Obsidian vault. The vault contains no actual files — only symlinks into each project's `Notes/` directory, so edits in Obsidian are immediately visible to PAI and vice versa.
@@ -583,21 +642,22 @@ Claude Code Event
 | Hook | Event | Purpose |
 |------|-------|---------|
 | `load-core-context.mjs` | SessionStart | Loads PAI skill system and core configuration |
-| `load-project-context.mjs` | SessionStart | Detects project, loads notes dir, TODO, session note |
+| `load-project-context.mjs` | SessionStart | Detects project, loads notes dir, TODO, session note; auto-registers new projects from .git, package.json, pubspec.yaml, and other signals |
 | `initialize-session.mjs` | SessionStart | Creates numbered session note, registers in PAI registry |
 | `post-compact-inject.mjs` | SessionStart (compact) | Reads saved state and injects into post-compaction context |
 | `security-validator.mjs` | PreToolUse (Bash) | Validates shell commands against security rules |
 | `capture-all-events.mjs` | All events | Observability — logs every hook event to session timeline |
 | `observe.mjs` | PostToolUse | Classifies tool calls into typed observations (decision/bugfix/feature/refactor/discovery/change) |
 | `inject-observations.mjs` | SessionStart | Injects recent observation context (compact index + timeline) |
-| `context-compression-hook.mjs` | PreCompact | Extracts session state, saves checkpoint, writes temp file for relay |
+| `context-compression-hook.mjs` | PreCompact | Extracts session state, saves checkpoint, pushes session-summary work item to daemon |
 | `capture-tool-output.mjs` | PostToolUse | Records tool inputs/outputs for observability dashboard |
 | `update-tab-on-action.mjs` | PostToolUse | Updates terminal tab title based on current activity |
 | `sync-todo-to-md.mjs` | PostToolUse (TodoWrite) | Syncs Claude's internal TODO list to `Notes/TODO.md` |
 | `cleanup-session-files.mjs` | UserPromptSubmit | Cleans up stale temp files between prompts |
 | `update-tab-titles.mjs` | UserPromptSubmit | Sets terminal tab title from session context |
-| `stop-hook.mjs` | Stop | Writes work items to session note, sends notification |
-| `capture-session-summary.mjs` | SessionEnd | Final session summary written to session note |
+| `whisper-rules.mjs` | UserPromptSubmit | Injects critical operating rules on every prompt; rules survive compaction and /clear |
+| `stop-hook.mjs` | Stop | Pushes session-summary work item to daemon queue, sends notification |
+| `capture-session-summary.mjs` | SessionEnd | Pushes session-summary work item to daemon queue |
 | `subagent-stop-hook.mjs` | SubagentStop | Captures sub-agent completion for observability |
 
 ### Context Preservation Relay
@@ -942,8 +1002,14 @@ src/
 │   ├── daemon/             # Daemon server internals
 │   │   ├── dispatcher.ts   # Tool dispatch (zettel, observation, memory)
 │   │   ├── handler.ts      # NDJSON request handler
-│   │   └── server.ts       # Socket server
-│   ├── indexer/            # Background index scheduler
+│   │   ├── scheduler.ts    # Background index scheduler
+│   │   ├── server.ts       # Socket server
+│   │   ├── state.ts        # Shared daemon state
+│   │   └── types.ts        # Shared type definitions
+│   ├── session-summary-worker.ts  # AI-powered session summarization (Opus/Sonnet)
+│   ├── topic-detect-worker.ts     # BM25-based topic shift detection
+│   ├── work-queue-worker.ts       # Generic work item processor
+│   ├── work-queue.ts              # Persistent file-backed work queue
 │   ├── config.ts           # Runtime configuration
 │   └── index.ts            # Daemon entry point
 ├── daemon-mcp/
@@ -954,12 +1020,14 @@ src/
 │   └── index.ts            # MCP shim entry point (stdio → socket)
 ├── hooks/
 │   └── ts/                 # TypeScript hook sources by event
-│       ├── PreCompact/
-│       ├── PreToolUse/
-│       ├── PostToolUse/
-│       ├── SessionStart/
-│       ├── Stop/
-│       └── UserPromptSubmit/
+│       ├── pre-compact/    # context-compression-hook.ts
+│       ├── pre-tool-use/   # security-validator
+│       ├── post-tool-use/  # observe, capture-tool-output, sync-todo-to-md, update-tab-on-action
+│       ├── session-start/  # load-core-context, load-project-context, initialize-session, inject-observations, post-compact-inject
+│       ├── session-end/    # capture-session-summary
+│       ├── stop/           # stop-hook
+│       ├── subagent-stop/  # subagent-stop-hook
+│       └── user-prompt/    # cleanup-session-files, update-tab-titles, whisper-rules
 ├── mcp/
 │   └── tools/              # Shared tool implementations
 │       ├── memory.ts

package/FEATURE.md

@@ -28,14 +28,19 @@ different direction: persistent memory, session continuity, and deep Claude Code
 | **Persistent session memory** | No | Yes — auto-indexed, 449K+ chunks |
 | **Session registry** | No | Yes — SQLite, tracks 77+ projects |
 | **Background daemon** | No | Yes — launchd, IPC via Unix socket |
-| **MCP server** | No | Yes — 9 tools, 18 prompts, 11 resources exposed to Claude Code |
+| **MCP server** | No | Yes — 9 tools, 19 prompts, 11 resources exposed to Claude Code |
 | **Keyword search (BM25)** | No | Yes — GIN full-text index, PostgreSQL |
 | **Semantic search (vector)** | No | Yes — pgvector HNSW, Snowflake Arctic 768-dim |
 | **Multi-backend storage** | No | Yes — SQLite (simple) or PostgreSQL (full) |
 | **Obsidian vault bridge** | No | Yes — symlinks + auto-generated topic pages |
 | **Project lifecycle** | No | Yes — promote, archive, move, detect from cwd |
+| **Auto project registration** | No | Yes — detects .git, package.json, pubspec.yaml, etc. on session start |
 | **Setup wizard** | No | Yes — idempotent 14-step interactive wizard |
-| **Hook system** | No | Yes — pre-compact, session-stop, auto-cleanup |
+| **Hook system** | No | Yes — pre-compact, session-stop, auto-cleanup, whisper rules |
+| **Automatic session notes** | No | Yes — AI-generated via daemon worker (Opus/Sonnet), topic-based splitting |
+| **Topic-based note splitting** | No | Yes — Jaccard similarity detects topic shifts, creates separate notes |
+| **Whisper rules** | No | Yes — injects critical rules on every prompt, survives compaction and /clear |
+| **Session note reconstruction** | No | Yes — /reconstruct skill retroactively creates notes from JSONL + git history |
 | **Backup / restore** | No | Yes — timestamped pg_dump + registry export |
 | **Multi-session concurrency** | n/a | Yes — daemon multiplexes Claude sessions |
 | **Custom statusline** | No | Yes — model, MCPs, context meter, colors |

package/PLUGIN-ARCHITECTURE.md

@@ -6,7 +6,7 @@ Technical reference for PAI's modular plugin system, cross-platform support, use
 
 ## Overview
 
-PAI is structured as a modular plugin system with 8 named modules organized into 3 pricing tiers. The architecture supports Claude Code (full integration), Cursor (MCP only), and Gemini CLI (MCP only).
+PAI is structured as a modular plugin system with 8 named modules organized into 3 pricing tiers. The architecture supports Claude Code (full integration), Cursor (MCP only), and Gemini CLI (MCP only). Current version: 0.8.0.
 
 ```
 PAI Knowledge OS
@@ -54,24 +54,24 @@ Each module has a `plugins/<module>/plugin.json` that declares:
 
 | Module | Tier | Hooks | Skills | Description |
 |--------|------|-------|--------|-------------|
-| `core` | free | 6 | 3 | Memory engine, sessions, projects, security |
-| `productivity` | free | 2 | 6 | Plan, Review, Journal, Research, Share, Createskill |
-| `ui` | free | 2 | 0 | Tab titles, statusline, tab coloring |
+| `core` | free | 6 | 3 | Memory engine, sessions, projects, security, auto-registration |
+| `productivity` | free | 2 | 7 | Plan, Review, Journal, Research, Share, Createskill, Reconstruct |
+| `ui` | free | 3 | 0 | Tab titles, statusline, tab coloring, whisper rules |
 | `context-preservation` | free | 3 | 0 | Context compression and relay |
 | `semantic-search` | pro | 0 | 0 | pgvector, reranking, hybrid search |
-| `observability` | pro | 13 | 2 | Event capture, classification, summaries |
+| `observability` | pro | 13 | 2 | Event capture, classification, AI-powered session summaries, topic detection |
 | `zettelkasten` | enterprise | 0 | 5 | Graph operations, vault intelligence |
 | `creative` | enterprise | 0 | 2 | Art direction, story, voice/prosody |
 
 ### Hook Distribution
 
-Total: 26 hook registrations across 6 modules.
+Total: 27 hook registrations across 6 modules.
 
-**Core (6):** load-core-context, load-project-context, initialize-session, security-validator, stop-hook, pai-session-stop.sh
+**Core (6):** load-core-context, load-project-context (with auto-registration), initialize-session, security-validator, stop-hook, pai-session-stop.sh
 
 **Productivity (2):** sync-todo-to-md, cleanup-session-files
 
-**UI (2):** update-tab-titles, update-tab-on-action
+**UI (3):** update-tab-titles, update-tab-on-action, whisper-rules
 
 **Context Preservation (3):** context-compression-hook, pai-pre-compact.sh, post-compact-inject
 
@@ -79,11 +79,11 @@ Total: 26 hook registrations across 6 modules.
 
 ### Skill Distribution
 
-Total: 18 skills across 5 modules.
+Total: 19 skills across 5 modules.
 
 **Core (3):** Sessions, Route, Name
 
-**Productivity (6):** Plan, Review, Journal, Research, Share, Createskill
+**Productivity (7):** Plan, Review, Journal, Research, Share, Createskill, Reconstruct
 
 **Observability (2):** Observability, SearchHistory
 
@@ -162,9 +162,9 @@ Claude Code gets the complete PAI experience:
 |------------|---------|
 | MCP Tools (9) | Full |
 | MCP Resources (11) | Full |
-| MCP Prompts (18) | Full |
-| Hooks (26 registrations) | Full |
-| Skills (18 SKILL.md stubs) | Full |
+| MCP Prompts (19) | Full |
+| Hooks (27 registrations) | Full |
+| Skills (19 SKILL.md stubs) | Full |
 | Statusline | Full |
 | Tab management | Full |
 
@@ -342,16 +342,31 @@ No migration needed. The plugin architecture is purely additive:
 
 ## Future Roadmap
 
-### Phase 1 (v0.7.0 — Current)
+### Phase 1 (v0.7.0 — Implemented)
 - Module manifest system
 - Cross-platform manifests
 - User extension points
 - Tier annotations (no enforcement)
 
-### Phase 2 (v0.8.0)
+### Phase 2 (v0.8.0 — Implemented)
+- AI-powered session notes via daemon work queue
+- Topic-based note splitting (Jaccard similarity)
+- Whisper rules hook (persistent rule injection)
+- Reconstruct skill (retroactive session note creation)
+- API key stripping for cost-safe headless Claude spawning
+
+### Phase 3 (v0.9.0)
 - `pai plugins list` — show installed modules and tiers
 - `pai plugins enable/disable <module>` — selective module activation
-- Build system reads `pai-plugin.json` to generate platform manifests
+- License validation system
+- `pai license activate <key>` command
+- Graceful tier gating with upgrade prompts
+
+### Phase 4 (v1.0.0)
+- Plugin marketplace integration
+- Third-party plugin support
+- Plugin dependency resolution
+- Community plugin repository
 
 ### Phase 3 (v0.9.0)
 - License validation system

package/README.md

@@ -1,8 +1,27 @@
-# PAI Knowledge OS
+# PAI Knowledge OS — v0.8.0
 
-Claude Code has a memory problem. Every new session starts cold — no idea what you built yesterday, what decisions you made, or where you left off. You re-explain everything, every time. PAI fixes this.
+Claude Code has a memory problem. Every new session starts cold — no idea what you built yesterday, what decisions you made, or where you left off. PAI fixes this.
 
-Install PAI and Claude remembers. Ask it what you were working on. Ask it to find that conversation about the database schema. Ask it to pick up exactly where the last session ended. It knows.
+## Automatic Session Notes — by Topic
+
+PAI's headline feature: **every session is automatically documented.** No manual note-taking, no "pause session" commands, no forgetting to save what you did.
+
+When you work, a background daemon watches your session **continuously**. Every time Claude's context compacts — which happens automatically as the conversation grows — the daemon reads the JSONL transcript, combines it with your git history, and spawns a headless Claude process to write a structured session note. Not just at session end. Midway through your work, while you're still coding. The notes build up in real time as you go — what was built, what decisions were made, what problems were hit, what's left to do.
+
+**When you change topics mid-session, PAI creates a new note.** If you start the day debugging audio, then pivot to a Flutter rewrite, you get two notes — not one giant file mixing unrelated work:
+
+```
+Notes/2026/03/
+  0001 - 2026-03-23 - Phase 1 Research and Architecture.md
+  0002 - 2026-03-24 - Background Audio and iOS Conflicts.md
+  0003 - 2026-03-24 - Flutter Rewrite with Whisper.md     ← auto-split, same day
+```
+
+Topic detection uses Jaccard word similarity between the new summary's topic and the existing note's title. Below 30% overlap = new note.
+
+**Model tiering:** Opus for final session summaries (best quality, runs once). Sonnet for mid-session checkpoints (good quality, runs on compaction). All using your Max plan — no API charges.
+
+This is not a template or a skeleton. These are real notes with build error chronologies, architectural decisions with rationale, code snippets, and "what was tried and failed" sections. The kind of notes you'd write yourself if you had time.
 
 ---
 
@@ -56,6 +75,7 @@ Install PAI and Claude remembers. Ask it what you were working on. Ask it to fin
 - "Go" — reads your TODO.md continuation prompt and picks up exactly where the last session stopped
 - "What was I working on?" — progressive context injection loads recent observations at session start
 - "Continue the daemon refactor" — session summaries give Claude full context without re-explaining
+- "/reconstruct" — retroactively creates session notes from JSONL transcripts and git history when automatic capture missed a session
 
 ### Keeping Things Safe
 
@@ -114,15 +134,59 @@ PAI runs hooks at every stage of a Claude Code session:
 
 | Event | What PAI Does |
 |-------|--------------|
-| **Session Start** | Loads project context, detects which project you're in, creates a session note |
-| **User Prompt** | Cleans up temp files, updates terminal tab titles |
-| **Pre-Compact** | Saves session state checkpoint, sends notification |
+| **Session Start** | Loads project context, detects which project you're in, auto-registers new projects, creates a session note |
+| **User Prompt** | Cleans up temp files, updates terminal tab titles, injects whisper rules on every prompt |
+| **Pre-Compact** | Saves session state checkpoint, pushes `session-summary` work item to daemon, sends notification |
 | **Post-Compact** | Injects preserved state back into Claude's context |
 | **Tool Use** | Classifies tool calls into structured observations (decision/bugfix/feature/refactor/discovery/change) |
-| **Session End** | Summarizes work done, finalizes session note |
-| **Stop** | Writes work items to session note, sends notification |
+| **Session End** | Pushes `session-summary` work item to daemon for AI-powered note generation |
+| **Stop** | Pushes `session-summary` work item to daemon, sends notification |
+
+All hooks are TypeScript compiled to `.mjs` modules. They run as separate processes and communicate via stdin (JSON input from Claude Code) and stdout (context injection back into the conversation). Hooks are thin relays — they capture minimal data and immediately push work items to the daemon queue, which handles all heavy processing asynchronously.
+
+---
+
+## Automatic Session Notes
+
+PAI automatically writes structured session notes after every session ends — no manual journaling required. The daemon spawns a headless Claude CLI process (using your Max plan, not the API) to summarize the JSONL conversation transcript combined with recent git history.
+
+### What Gets Generated
+
+Each session note contains:
+
+- **Work Done** — concrete description of what was accomplished
+- **Key Decisions** — choices made and their rationale
+- **Known Issues** — bugs found, blockers, or open questions
+- **Next Steps** — where to pick up in the next session
+
+The summarizer uses tiered model selection based on the trigger:
+
+| Trigger | Model | Timeout | JSONL Limit |
+|---------|-------|---------|-------------|
+| Session end (Stop hook) | Opus | 5 minutes | 500K bytes |
+| Auto-compaction (PreCompact hook) | Sonnet | 2 minutes | 200K bytes |
+
+### Topic-Based Note Splitting
 
-All hooks are TypeScript compiled to `.mjs` modules. They run as separate processes, communicate via stdin (JSON input from Claude Code) and stdout (context injection back into the conversation).
+When a session covers multiple distinct topics, PAI creates separate notes rather than one long note for the whole session. The summarizer outputs a `TOPIC:` line describing the subject of the current work. PAI compares this against the existing note title using Jaccard word similarity — when similarity falls below 30%, a new note is created automatically.
+
+Notes within the same day are numbered sequentially: `0042 - 2026-03-24 - Session Name.md`, `0043 - 2026-03-24 - Different Topic.md`, and so on.
+
+### One Note Per Session
+
+Each compaction within a session updates the existing note rather than creating a new one. The 30-minute cooldown between summaries prevents redundant updates. Stop hook triggers bypass the cooldown with a force flag to ensure the final state is always captured.
+
+### Garbage Title Filter
+
+Session note titles are validated before creation. Over 20 patterns are rejected, including: task notification strings, `[object Object]`, hex hashes, bare numbers, and other non-descriptive artifacts that can appear in session transcripts. Titles must describe actual work done and are capped at 60 characters.
+
+### Finding the Claude Binary
+
+The daemon runs under launchd with a minimal PATH that does not include `~/.local/bin/`. PAI resolves the Claude CLI binary by checking `~/.local/bin/claude` first, then falling back to PATH lookup, before spawning headless summarization processes.
+
+### Stripping the API Key
+
+When spawning headless Claude CLI processes for summarization, the daemon strips `ANTHROPIC_API_KEY` from the subprocess environment. This forces the spawned process to authenticate via your Max plan (free) rather than using the API key (billable). Without this, every automatic session note would incur API charges.
 
 ---
 
@@ -187,6 +251,27 @@ When a session ends, PAI generates a structured summary capturing what was reque
 
 ---
 
+## Whisper Rules
+
+PAI provides a hook that injects user-defined rules into every prompt via `UserPromptSubmit`. Rules survive compaction, `/clear`, and session restarts — they fire on every single turn, making them the most reliable way to enforce behavioral constraints.
+
+**PAI ships the mechanism. You provide the rules.** The file `~/.claude/whisper-rules.md` does not exist by default. Use the `/whisper` skill to manage your rules:
+
+```
+/whisper                          — show current rules
+/whisper add "NEVER send emails"  — add a rule
+/whisper remove 3                 — remove rule #3
+/whisper list                     — list with line numbers
+```
+
+Or edit `~/.claude/whisper-rules.md` directly — one rule per line, plain text.
+
+**Keep rules focused.** Every rule is injected on every prompt. Too many rules dilute effectiveness and waste tokens. Reserve whisper rules for truly critical constraints that keep getting violated despite being in CLAUDE.md.
+
+The pattern is inspired by [Letta's claude-subconscious](https://github.com/letta-ai/claude-subconscious) approach to persistent context injection.
+
+---
+
 ## Auto-Compact Context Window
 
 Claude Code can automatically compact your context window when it fills up, preventing session interruptions mid-task. PAI's statusline shows you at a glance whether auto-compact is active.

package/dist/hooks/whisper-rules.mjs

@@ -13,11 +13,7 @@ function getWhisperRules() {
     } catch {
     }
   }
-  return [
-    "NEVER suggest pausing, stopping, or ending the session. The user decides when to stop. Not you. Ever.",
-    "NEVER send emails. Always create drafts. No exceptions.",
-    "NEVER add Co-Authored-By or AI attribution to git commits."
-  ].join("\n");
+  return "";
 }
 function main() {
   const rules = getWhisperRules();

package/dist/hooks/whisper-rules.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/hooks/ts/user-prompt/whisper-rules.ts"],
-  "sourcesContent": ["#!/usr/bin/env node\n\n/**\n * whisper-rules.ts\n *\n * UserPromptSubmit hook that injects critical non-negotiable rules into every\n * prompt as a <system-reminder>. This ensures rules survive compaction \u2014 even\n * if CLAUDE.md content is lost during context compression, the whisper\n * re-injects the absolute rules on every single turn.\n *\n * Inspired by Letta's \"claude-subconscious\" whisper pattern.\n *\n * Rules are loaded from ~/.claude/whisper-rules.md if it exists,\n * otherwise falls back to hardcoded critical rules.\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { homedir } from \"node:os\";\n\nconst WHISPER_FILE = join(homedir(), \".claude\", \"whisper-rules.md\");\n\nfunction getWhisperRules(): string {\n  // User-customizable whisper file takes priority\n  if (existsSync(WHISPER_FILE)) {\n    try {\n      const content = readFileSync(WHISPER_FILE, \"utf-8\").trim();\n      if (content) return content;\n    } catch { /* fall through to defaults */ }\n  }\n\n  // Hardcoded critical rules \u2014 the ones that keep getting violated\n  return [\n    \"NEVER suggest pausing, stopping, or ending the session. The user decides when to stop. Not you. Ever.\",\n    \"NEVER send emails. Always create drafts. No exceptions.\",\n    \"NEVER add Co-Authored-By or AI attribution to git commits.\",\n  ].join(\"\\n\");\n}\n\nfunction main() {\n  const rules = getWhisperRules();\n  if (!rules) return;\n\n  // Output as system-reminder \u2014 Claude Code injects this into the conversation\n  console.log(`<system-reminder>\n${rules}\n</system-reminder>`);\n}\n\nmain();\n"],
-  "mappings": ";;;AAgBA,SAAS,YAAY,oBAAoB;AACzC,SAAS,YAAY;AACrB,SAAS,eAAe;AAExB,IAAM,eAAe,KAAK,QAAQ,GAAG,WAAW,kBAAkB;AAElE,SAAS,kBAA0B;AAEjC,MAAI,WAAW,YAAY,GAAG;AAC5B,QAAI;AACF,YAAM,UAAU,aAAa,cAAc,OAAO,EAAE,KAAK;AACzD,UAAI,QAAS,QAAO;AAAA,IACtB,QAAQ;AAAA,IAAiC;AAAA,EAC3C;AAGA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF,EAAE,KAAK,IAAI;AACb;AAEA,SAAS,OAAO;AACd,QAAM,QAAQ,gBAAgB;AAC9B,MAAI,CAAC,MAAO;AAGZ,UAAQ,IAAI;AAAA,EACZ,KAAK;AAAA,mBACY;AACnB;AAEA,KAAK;",
+  "sourcesContent": ["#!/usr/bin/env node\n\n/**\n * whisper-rules.ts\n *\n * UserPromptSubmit hook that injects critical non-negotiable rules into every\n * prompt as a <system-reminder>. This ensures rules survive compaction \u2014 even\n * if CLAUDE.md content is lost during context compression, the whisper\n * re-injects the absolute rules on every single turn.\n *\n * Inspired by Letta's \"claude-subconscious\" whisper pattern.\n *\n * Rules are loaded from ~/.claude/whisper-rules.md if it exists,\n * otherwise falls back to hardcoded critical rules.\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { homedir } from \"node:os\";\n\nconst WHISPER_FILE = join(homedir(), \".claude\", \"whisper-rules.md\");\n\nfunction getWhisperRules(): string {\n  // User-managed whisper file \u2014 PAI provides the hook, user provides the rules\n  // Configure via /whisper skill or edit ~/.claude/whisper-rules.md directly\n  if (existsSync(WHISPER_FILE)) {\n    try {\n      const content = readFileSync(WHISPER_FILE, \"utf-8\").trim();\n      if (content) return content;\n    } catch { /* ignore read errors */ }\n  }\n\n  // No rules configured \u2014 silent (no injection)\n  return \"\";\n}\n\nfunction main() {\n  const rules = getWhisperRules();\n  if (!rules) return;\n\n  // Output as system-reminder \u2014 Claude Code injects this into the conversation\n  console.log(`<system-reminder>\n${rules}\n</system-reminder>`);\n}\n\nmain();\n"],
+  "mappings": ";;;AAgBA,SAAS,YAAY,oBAAoB;AACzC,SAAS,YAAY;AACrB,SAAS,eAAe;AAExB,IAAM,eAAe,KAAK,QAAQ,GAAG,WAAW,kBAAkB;AAElE,SAAS,kBAA0B;AAGjC,MAAI,WAAW,YAAY,GAAG;AAC5B,QAAI;AACF,YAAM,UAAU,aAAa,cAAc,OAAO,EAAE,KAAK;AACzD,UAAI,QAAS,QAAO;AAAA,IACtB,QAAQ;AAAA,IAA2B;AAAA,EACrC;AAGA,SAAO;AACT;AAEA,SAAS,OAAO;AACd,QAAM,QAAQ,gBAAgB;AAC9B,MAAI,CAAC,MAAO;AAGZ,UAAQ,IAAI;AAAA,EACZ,KAAK;AAAA,mBACY;AACnB;AAEA,KAAK;",
   "names": []
 }

package/dist/skills/Whisper/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: Whisper
+description: "Manage whisper rules — persistent behavioral constraints injected on every prompt. USE WHEN user says 'whisper', 'add whisper rule', 'remove whisper rule', 'list whisper rules', 'show whisper rules', '/whisper', OR wants to manage persistent behavioral rules."
+---
+
+## Whisper Rules Management
+
+USE WHEN user says 'whisper', 'add whisper rule', 'remove whisper rule', 'list whisper rules', 'show whisper rules', '/whisper', OR wants to manage persistent behavioral rules.
+
+Manage the rules that PAI injects into every prompt via the whisper-rules hook.
+
+Rules are stored in `~/.claude/whisper-rules.md` — one rule per line, plain text.
+The hook reads this file on every UserPromptSubmit and injects it as a `<system-reminder>`.
+Rules survive compaction, /clear, and session restarts.
+
+### Usage
+
+- `/whisper` — show current rules
+- `/whisper add <rule>` — add a new rule
+- `/whisper remove <number>` — remove rule by line number
+- `/whisper list` — list rules with line numbers
+- `/whisper clear` — remove all rules (with confirmation)
+
+### Workflow
+
+**Show current rules:**
+Read `~/.claude/whisper-rules.md` and display each rule with a line number.
+If the file doesn't exist, say "No whisper rules configured."
+
+**Add a rule:**
+Append the rule as a new line to `~/.claude/whisper-rules.md`.
+Create the file if it doesn't exist.
+Do NOT add duplicate rules — check if a similar rule already exists.
+
+**Remove a rule:**
+Read the file, remove the line at the given number, write the file back.
+Show the removed rule for confirmation.
+
+**Clear all rules:**
+Ask for confirmation first ("This will remove all N rules. Confirm?").
+Only proceed if the user explicitly confirms.
+
+### Important
+
+- Rules should be short, imperative statements (1-2 lines max)
+- Every rule is injected on EVERY prompt — keep the list focused on truly critical rules
+- Too many rules dilute their effectiveness and waste tokens
+- The file does not exist by default — PAI ships the hook, the user adds their own rules
+- Rules are global (shared across all sessions and projects)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",

package/src/hooks/ts/user-prompt/whisper-rules.ts

@@ -21,20 +21,17 @@ import { homedir } from "node:os";
 const WHISPER_FILE = join(homedir(), ".claude", "whisper-rules.md");
 
 function getWhisperRules(): string {
-  // User-customizable whisper file takes priority
+  // User-managed whisper file — PAI provides the hook, user provides the rules
+  // Configure via /whisper skill or edit ~/.claude/whisper-rules.md directly
   if (existsSync(WHISPER_FILE)) {
     try {
       const content = readFileSync(WHISPER_FILE, "utf-8").trim();
       if (content) return content;
-    } catch { /* fall through to defaults */ }
+    } catch { /* ignore read errors */ }
   }
 
-  // Hardcoded critical rules — the ones that keep getting violated
-  return [
-    "NEVER suggest pausing, stopping, or ending the session. The user decides when to stop. Not you. Ever.",
-    "NEVER send emails. Always create drafts. No exceptions.",
-    "NEVER add Co-Authored-By or AI attribution to git commits.",
-  ].join("\n");
+  // No rules configured — silent (no injection)
+  return "";
 }
 
 function main() {