@pi-unipi/compactor 2.0.3 → 2.0.4

package/README.md

@@ -1,101 +1,318 @@
 # @pi-unipi/compactor
 
-Context engine that keeps sessions lean. Compacts conversations, indexes code, searches history, and runs sandboxed code — all without burning LLM tokens on compaction.
+Deterministic context management for Pi/UniPi. The compactor keeps long coding sessions usable by replacing large conversation history with a structured, zero-LLM summary, while preserving session recall, continuity snapshots, stats, sandbox helpers, and safer tool display.
 
-The zero-LLM pipeline compresses context through 6 stages (normalize, filter, build sections, brief, format, merge) to hit 95%+ token reduction at zero API cost. Session continuity preserves context across compaction boundaries with XML resume snapshots.
+## What it does
 
-## Commands
+- **Zero-LLM compaction:** Pi asks for compaction; UniPi builds the summary locally instead of spending model tokens on a summarization call.
+- **Session continuity:** important goals, changed files, commits, blockers, preferences, and a recent transcript survive compaction.
+- **Optional percentage trigger:** UniPi can compact at a configured context percentage before Pi's fixed reserve-token safety net fires.
+- **Recall:** agents can search the append-only session branch, including messages that no longer fit in live LLM context.
+- **Runtime helpers:** sandbox execution, context budget checks, diagnostics, and stats.
+- **Display guards:** tool output/diff rendering is clamped and summarized to avoid noisy or terminal-breaking output.
 
-| Command | Description |
-|---------|-------------|
-| `/unipi:lossless-compact` | Immediate zero-LLM compaction with structured summary |
-| `/unipi:session-recall` | Search session history (BM25 or regex) |
-| `/unipi:content-index` | Index current project into FTS5 |
-| `/unipi:content-search` | Search indexed content |
-| `/unipi:content-purge` | Wipe all indexed content |
-| `/unipi:compact-stats` | Context savings dashboard |
-| `/unipi:compact-doctor` | Run diagnostics |
-| `/unipi:compact-settings` | TUI settings overlay |
-| `/unipi:compact-preset <name>` | Apply quick preset |
-| `/unipi:compact-help` | Show detailed documentation |
+The compaction pipeline is deterministic and runs locally. It does not call an LLM during compaction.
 
-> **Note:** `/unipi:compact` still works as a deprecated alias for `/unipi:lossless-compact`.
+---
 
-## Special Triggers
+## Quick start
 
-Compactor tools are available to the main agent when installed. All workflow skills can use compactor tools for context management.
+```text
+/unipi:compact-settings
+```
 
-Compactor registers with the info-screen dashboard, showing compaction count, tokens saved, compression ratio, and indexed documents. The footer subscribes to `COMPACTOR_STATSUPDATED` events to display compaction stats in the status bar.
+1. Choose a preset in **Presets**.
+2. Optionally enable **Auto → Percentage Trigger**.
+3. Press **Enter** to save.
+4. Use `/unipi:lossless-compact` when you want to compact immediately.
 
-## Agent Tools
+Config files:
 
-| Tool | Family | Description |
-|------|--------|-------------|
-| `compact` | compaction | Trigger manual compaction (dryRun: true to preview) |
-| `session_recall` | session | BM25 session history search |
-| `sandbox` | sandbox | Run code in sandbox (11 languages) |
-| `sandbox_file` | sandbox | Execute file via FILE_CONTENT |
-| `sandbox_batch` | sandbox | Atomic batch of commands + searches |
-| `content_index` | content | Chunk content to FTS5 index |
-| `content_search` | content | Query indexed content |
-| `content_fetch` | content | Fetch URL and index |
-| `compactor_stats` | compactor | Context savings dashboard |
-| `compactor_doctor` | compactor | Diagnostics checklist |
-| `context_budget` | compactor | Estimate remaining context window |
+| Scope | Path | Notes |
+|---|---|---|
+| Global | `~/.unipi/config/compactor/config.json` | Used by default |
+| Per project | `<project>/.unipi/config/compactor.json` | Enabled from settings with **Project Override** |
 
-## Two-Tier Skills
+Per-project config is merged over global config when the current project directory is known.
 
-- **Tier 1** (`compactor`): ~175 tokens, always loaded. Routing and critical rules.
-- **Tier 2** (`compactor-detail`): On-demand. Full tool reference, anti-patterns, sandbox languages, FTS5 modes, workflows.
+---
 
-## Configurables
+## User-facing slash commands
 
-Config lives at `~/.unipi/config/compactor/config.json`. Per-project overrides at `<project>/.unipi/config/compactor.json`.
+| Command | What it does | Notes |
+|---|---|---|
+| `/unipi:lossless-compact` | Immediately calls Pi compaction with UniPi's zero-LLM sentinel. | Main manual compaction command. |
+| `/unipi:compact` | Deprecated alias for `/unipi:lossless-compact`. | Kept for backward compatibility. |
+| `/unipi:session-recall <query>` | Searches current session history with BM25/regex recall. | Uses the append-only session branch when available, so pre-compaction messages can still be found. |
+| `/unipi:compact-recall <query>` | Deprecated alias for `/unipi:session-recall`. | Kept for backward compatibility. |
+| `/unipi:compact-stats` | Shows session events, compaction count, token savings, sandbox runs, and search counts. | Stats are DB-backed with runtime fallbacks. |
+| `/unipi:compact-doctor` | Runs diagnostics for config, SQLite/session DB, and runtimes. | Useful when stats/recall/sandbox look broken. |
+| `/unipi:compact-settings` | Opens the TUI settings overlay. | Tabs: Presets, Strategies, Auto, Pipeline. |
+| `/unipi:compact-preset <name>` | Applies a preset globally. | Names: `precise`, `balanced`, `thorough`, `lean`. Old names map to new ones: `opencode→precise`, `verbose→thorough`, `minimal→lean`. |
+| `/unipi:compact-help` | Shows compact help inside Pi. | Quick command reference. |
 
-### Presets
+Content/project indexing is handled by `@pi-unipi/cocoindex`, not this package. Use `/unipi:cocoindex-init`, `/unipi:cocoindex-update`, and `cocoindex_search` for indexed project search.
 
-| Preset | Description |
-|--------|-------------|
-| `precise` | Code-heavy, minimal waste — compaction: full, pipeline: 2/6 on |
-| `balanced` | Daily use (default) — all strategies moderate, pipeline: all on |
-| `thorough` | Debug/audit — everything on, full transcript |
-| `lean` | Quick fixes — compaction only, pipeline: all off |
+---
 
-Apply via `/unipi:compact-preset <name>`.
+## User-facing settings
 
-### Pipeline Features
+Open settings with `/unipi:compact-settings`.
 
-| Feature | Description | Context |
-|---------|-------------|---------|
-| TTL Cache | Cache with time-based expiry | On Compaction |
-| Auto Injection | Inject behavioral state after compaction | On Compaction |
-| MMap Pragma | Use mmap for SQLite I/O | On Compaction |
-| Proximity Reranking | Rerank search results by proximity | On Search |
-| Timeline Sort | Sort session events chronologically | On Search |
-| Progressive Throttling | Slow down indexing for large projects | On Index |
+Keyboard:
 
-### TUI
+| Key | Action |
+|---|---|
+| `Tab` | Switch tabs |
+| `↑/↓` | Move selection |
+| `Space` | Cycle/toggle selected value |
+| `/` | Search inside the Strategies tab |
+| `Enter` | Save and close |
+| `Esc` | Cancel |
 
-Tabbed settings interface (Presets / Strategies / Pipeline):
-- `/` key opens search filter in Strategies tab
-- Preset selection shows 3-line preview
-- Per-project override checkbox (`o` key)
-- Keyboard: left/right cycle modes, Space toggle, `s` save, Esc cancel
+### Presets tab
 
-## Architecture
+Presets are profiles that set strategies, pipeline switches, sandbox mode, and display mode.
 
+| Preset | Intended use | Important effects |
+|---|---|---|
+| `precise` | Code-heavy work, minimal waste | Full compaction sections, safe-only sandbox, opencode display, Pipeline: `ttlCache` + `mmapPragma` on. |
+| `balanced` | Daily/default profile | Compact transcript, balanced display, FTS mode auto, sandbox all, Pipeline: all six switches on. |
+| `thorough` | Debug/audit sessions | Full transcript, verbose display, sandbox all, Pipeline: all six switches on. |
+| `lean` | Quick fixes or short sessions | Brief/minimal compaction sections, no sandbox, no session continuity, Pipeline: all off. |
+
+The **Project Override** row controls where settings are saved:
+
+- `disabled` → save global config.
+- `enabled` → save `<project>/.unipi/config/compactor.json` for only this project.
+
+### Strategies tab
+
+These settings control what is extracted into compaction summaries or how related compactor features behave.
+
+| Setting | Values | Meaning |
+|---|---|---|
+| `Verbose Debug` | `on`, `off` | Enables internal debug state. Console debug output is intentionally muted to avoid TUI rendering issues. |
+| `Session Goals` | `full`, `brief`, `off` | Extracts the user's active goals/request history into `[Session Goal]`. |
+| `Files & Changes` | `all`, `modified-only`, `off` | Tracks read, created, edited, and written files in `[Files And Changes]`. |
+| `Commits` | `full`, `brief`, `off` | Captures git commit hashes/messages detected in the conversation. |
+| `Outstanding Context` | `full`, `critical-only`, `off` | Keeps blockers, TODOs, pending decisions, and follow-ups. |
+| `User Preferences` | `all`, `recent-only`, `off` | Preserves user preferences learned during the session. |
+| `Brief Transcript` | `full`, `compact`, `minimal`, `off` | Keeps a rolling recent transcript after the structured sections. |
+| `Session Continuity` | `full`, `essential-only`, `off` | Controls XML-style resume snapshots that help the next turn continue after compaction. |
+| `Sandbox Execution` | `all`, `safe-only`, `off` | Controls agent-facing sandbox availability/intent. Safe-only is intended for less risky execution. |
+| `Tool Display` | `opencode`, `balanced`, `verbose`, `custom` | Controls built-in tool output rendering style and diff display behavior. |
+
+Config-only legacy field: `fts5Index` remains in the schema for compatibility, but project indexing has moved to `@pi-unipi/cocoindex`.
+
+### Auto tab
+
+These settings control UniPi-managed percentage auto-compaction. They are separate from Pi core's own `compaction.reserveTokens` behavior.
+
+| Setting | Default | Meaning |
+|---|---:|---|
+| `Percentage Trigger` | `off` | When on, UniPi checks context usage at `turn_end` and can call compaction when the threshold is reached. Disabled by default for backward compatibility. |
+| `Threshold` | `80%` | Trigger point using Pi's live `ctx.getContextUsage().percent`. |
+| `Cooldown` | `60s` | Minimum time between UniPi-triggered compaction attempts. Prevents loops. |
+| `Repeat Growth` | `4k` | If usage is still above threshold after compaction, require this many new tokens before triggering again. |
+| `Notifications` | `on` | Shows user-visible notifications for UniPi-triggered compaction attempts/results. |
+
+Example config:
+
+```json
+{
+  "autoCompaction": {
+    "enabled": true,
+    "thresholdPercent": 80,
+    "cooldownMs": 60000,
+    "repeatMinGrowthTokens": 4000,
+    "notify": true
+  }
+}
 ```
-┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
-│ Compaction Core │  │ Session Engine  │  │ Display Engine  │
-│ (zero-LLM)      │  │ (SQLite + XML)  │  │ (mode-aware)    │
-└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
-         │                    │                    │
-         └────────────────────┼────────────────────┘
-                              ▼
-                    ┌─────────────────────┐
-                    │   Config Manager    │
-                    └─────────────────────┘
-```
+
+### Pipeline tab
+
+Pipeline switches are low-level feature flags used by presets and advanced users.
+
+| Setting | Preset behavior | Current effect |
+|---|---|---|
+| `TTL Cache` | On in `precise`, `balanced`, `thorough`; off in `lean` | Reserved/compatibility switch for cache behavior. Search has an internal cache, but this toggle is not currently required for it. |
+| `Auto Injection` | On in `balanced`, `thorough`; off in `precise`, `lean` | Active. Adds behavioral/session state to the resume snapshot after compaction. |
+| `MMap Pragma` | On in `precise`, `balanced`, `thorough`; off in `lean` | Reserved/compatibility switch for SQLite mmap tuning. |
+| `Proximity Reranking` | On in `balanced`, `thorough`; off in `precise`, `lean` | Reserved/compatibility switch for future recall/search ranking. |
+| `Timeline Sort` | On in `balanced`, `thorough`; off in `precise`, `lean` | Reserved/compatibility switch for future chronological recall sorting. |
+| `Progressive Throttling` | On in `balanced`, `thorough`; off in `precise`, `lean` | Reserved/compatibility switch for future large-project throttling. |
+
+If all Pipeline values stay `off` after choosing a preset, that means the running version is not applying preset pipeline values correctly. Choose a preset, press **Enter** to save, and verify you are on a version containing the preset pipeline fix.
+
+Config-only pipeline field:
+
+| Field | Meaning |
+|---|---|
+| `customNoisePatterns` | Extra regex/string patterns used by session recall filtering to remove noisy user blocks. |
+
+---
+
+## What the agent gets
+
+### Agent tools
+
+The extension registers tools during `session_start` after the session DB is initialized.
+
+| Tool | Purpose |
+|---|---|
+| `compact` | Agent-facing compaction request; supports `dryRun: true` preview. Slash command `/unipi:lossless-compact` is the user-facing immediate compaction path. |
+| `session_recall` | Search current session history with BM25 or regex. |
+| `vcc_recall` | Deprecated alias for `session_recall`. |
+| `sandbox` | Run code in a sandboxed environment. Languages: JavaScript, TypeScript, Python, shell, Ruby, Go, Rust, PHP, Perl, R, Elixir. |
+| `sandbox_file` | Execute a file with its content injected as `FILE_CONTENT`. |
+| `sandbox_batch` | Run multiple sandbox execution items in one atomic response. |
+| `ctx_execute` | Deprecated alias for `sandbox`. |
+| `ctx_execute_file` | Deprecated alias for `sandbox_file`. |
+| `ctx_batch_execute` | Deprecated alias for `sandbox_batch`. |
+| `compactor_stats` | Agent-readable stats dashboard. |
+| `ctx_stats` | Deprecated alias for `compactor_stats`. |
+| `compactor_doctor` | Agent-readable diagnostics. |
+| `ctx_doctor` | Deprecated alias for `compactor_doctor`. |
+| `context_budget` | Uses live Pi context usage when available and returns compaction guidance. |
+
+### Agent skills
+
+| Skill | Purpose |
+|---|---|
+| `compactor` | Small always-loadable routing skill: when to compact, recall, check budget, or use sandbox. |
+| `compactor-detail` | On-demand full tool reference and workflow guidance. |
+| `compactor-stats` | Help interpreting compactor stats. |
+| `compactor-doctor` | Help diagnosing config/DB/runtime issues. |
+
+---
+
+## How the system works
+
+### Chronological hook flow
+
+Typical session order:
+
+1. **Extension load**
+   - Registers compaction hooks immediately with lazy dependencies.
+   - Creates in-memory runtime counters/state.
+
+2. **`session_start`**
+   - Scaffolds config if needed.
+   - Initializes `SessionDB` and sandbox executor.
+   - Computes the current session ID, including worktree suffix.
+   - Registers agent tools and slash commands.
+   - Registers the info-screen Compactor group.
+   - Emits UniPi `MODULE_READY`.
+
+3. **`before_agent_start`**
+   - Reloads config for the active project.
+   - Applies runtime `autoDetect` behavior, such as disabling commit extraction outside git repos.
+   - Rebuilds cached recall blocks from Pi's append-only session branch.
+   - If a resume snapshot exists from a prior compaction, injects it into session context and marks it consumed.
+
+4. **`input`**
+   - Performs advisory security checks for shell/network/file patterns.
+   - Can block some known-dangerous network shell commands.
+
+5. **Tool execution → `tool_result`**
+   - Extracts file/change/search/sandbox events into the session DB.
+   - Updates runtime byte/tool counters.
+   - Applies display overrides and width-safe diff clamping before output reaches the TUI.
+
+6. **`turn_end`**
+   - If percentage auto-compaction is enabled, reads `ctx.getContextUsage()`.
+   - Runs cooldown/repeat-growth safeguards.
+   - Calls `ctx.compact({ customInstructions: COMPACTOR_INSTRUCTION })` when eligible.
+
+7. **Pi decides to compact**
+   - This can be from `/unipi:lossless-compact`, UniPi percentage auto-compaction, or Pi core's reserve-token fallback.
+
+8. **`session_before_compact`**
+   - Pi provides `preparation`, `branchEntries`, and optional custom instructions.
+   - If compactor should handle it, UniPi:
+     1. chooses the safe cut point (`buildOwnCut`),
+     2. converts messages to LLM-like input,
+     3. runs the zero-LLM compile pipeline,
+     4. persists stats/snapshots,
+     5. returns `{ compaction: { summary, details, tokensBefore, firstKeptEntryId } }` to Pi.
+
+9. **`session_compact`**
+   - Pi commits the compaction entry.
+   - UniPi increments compaction counters and persists token/character savings.
+
+10. **Next `before_agent_start` after compaction**
+    - UniPi injects the resume snapshot so the agent gets continuity without needing the full old transcript in context.
+
+11. **`session_shutdown`**
+    - Cleans old sessions.
+    - Cleans sandbox/background processes.
+    - Closes DB handles.
+
+### Zero-LLM compile pipeline
+
+When UniPi handles `session_before_compact`, it transforms old messages through these deterministic stages:
+
+1. **Normalize** — flatten user/assistant/tool/thinking messages into normalized blocks.
+2. **Filter** — remove noise and apply `customNoisePatterns`.
+3. **Build sections** — extract goals, files, commits, outstanding context, preferences, and transcript entries.
+4. **Brief** — cap and condense transcript lines.
+5. **Format** — emit a structured markdown summary.
+6. **Merge** — merge with the previous summary when Pi provides one.
+
+The resulting summary is optimized for continuity, not for perfect archival fidelity. Use `session_recall` when the agent needs details from the raw session branch.
+
+---
+
+## Benchmarks
+
+Synthetic compile-only benchmark, run on this repository with Node 24 using `compile()` directly. Token counts use the common `chars / 4` estimate. Real compaction also keeps a recent live tail, so final live-context size can be larger than the summary-only number below.
+
+| Synthetic session | Input chars | Approx input tokens | Summary chars | Approx summary tokens | Reduction | Compile time |
+|---:|---:|---:|---:|---:|---:|---:|
+| 100 turns / 400 messages | 356,913 | 89,228 | 36,451 | 9,113 | 89.8% | 12.5 ms |
+| 250 turns / 1,000 messages | 894,063 | 223,516 | 36,585 | 9,146 | 95.9% | 16.6 ms |
+| 500 turns / 2,000 messages | 1,789,313 | 447,328 | 36,605 | 9,151 | 98.0% | 35.8 ms |
+
+Practical interpretation:
+
+- Larger sessions compress better because the structured summary has fixed caps.
+- Runtime is local and usually small relative to model/tool latency.
+- Actual savings reported to users should come from `/unipi:compact-stats`, because Pi supplies real `tokensBefore` during compaction when available.
+
+---
+
+## Troubleshooting
+
+### "Whatever preset I choose, Pipeline is always off"
+
+That means preset application is not updating `config.pipeline`. The intended behavior is:
+
+- `precise`: `ttlCache` + `mmapPragma` on.
+- `balanced`: all six pipeline switches on.
+- `thorough`: all six pipeline switches on.
+- `lean`: all pipeline switches off.
+
+Make sure you are running a version with the preset pipeline fix, select the preset, and press **Enter** to save.
+
+### "Compaction did not happen"
+
+- For immediate user-triggered compaction, use `/unipi:lossless-compact`.
+- For automatic percentage compaction, enable **Auto → Percentage Trigger**.
+- Pi core still has its own reserve-token fallback; UniPi's percentage trigger is optional and disabled by default.
+
+### "Stats show zero"
+
+- Stats only increase after compaction or after tracked sandbox/search events.
+- Run `/unipi:compact-doctor` to check DB/config health.
+- Long sessions may show all-time DB fallbacks if current in-memory counters are zero.
+
+### "Recall cannot find something"
+
+- Use specific terms with `/unipi:session-recall <query>`.
+- The recall path prefers Pi's append-only branch and falls back to cached normalized blocks.
+- Extra noise filtering can be added with `pipeline.customNoisePatterns`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Context engine for Pi — zero-LLM compaction, session continuity, sandbox execution, and tool display optimization",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,9 @@
     "sandbox",
     "fts5"
   ],
+  "scripts": {
+    "test": "bun test tests"
+  },
   "files": [
     "index.ts",
     "src/**/*.ts",

package/skills/compactor/SKILL.md

@@ -11,9 +11,8 @@ description: Context management — compact session, recall history, run code, s
 - `compactor_stats` → check savings. `compactor_doctor` → diagnose.
 
 ## Finding Past Work
-- `session_recall(query)` → search this session (BM25 or regex).
-- `content_search(query)` → search indexed files/docs.
-  → Index first: `content_index` or `content_fetch(url)`.
+- `session_recall(query)` → search this session (BM25 or regex), including raw messages that may no longer be in live context after compaction.
+- For indexed project/file search, use the CocoIndex package (`cocoindex_search`) when installed; content indexing no longer lives in compactor.
 
 ## Running Code
 - `sandbox(lang, code)` → single script. `sandbox_batch(items)` → atomic.

package/skills/compactor-detail/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: compactor-detail
-description: Full compactor reference — tool parameters, anti-patterns, sandbox languages, FTS5 modes, workflows.
+description: Full compactor reference — tool parameters, anti-patterns, sandbox languages, context budget, workflows.
 ---
 
 # Compactor — Full Reference
@@ -9,70 +9,65 @@ description: Full compactor reference — tool parameters, anti-patterns, sandbo
 
 ### compact
 ```
-compact()
+compact(dryRun?: boolean)
 ```
-Trigger manual context compaction. Zero LLM — pure regex/text processing.
-Returns stats after next `session_compact` event.
+Agent-facing compaction request. Use `dryRun: true` to preview estimated message reduction without compacting.
+
+For user-triggered immediate compaction, prefer the slash command `/unipi:lossless-compact`.
 
 ### session_recall
 ```
 session_recall(query: string, mode?: "bm25" | "regex", limit?: number, offset?: number, expand?: boolean)
 ```
-Search session history. BM25 is default (TF-IDF ranked). Regex is fallback.
+Search current session history. BM25 is default; regex is fallback. The recall path prefers Pi's append-only session branch so it can find messages that are no longer present in live LLM context after compaction.
+
+Deprecated alias: `vcc_recall`.
 
 ### sandbox
 ```
 sandbox(language: string, code: string, timeout?: number)
 ```
-Run code in sandboxed env. Only stdout enters context. 100MB output cap. 30s default timeout.
+Run code in a sandboxed environment. Only stdout enters context. 100MB output cap. 30s default timeout.
+
+Deprecated alias: `ctx_execute`.
 
 ### sandbox_file
 ```
 sandbox_file(language: string, path: string, timeout?: number)
 ```
-Execute file. Content injected as `FILE_CONTENT` variable.
+Execute a file. File content is injected as `FILE_CONTENT`.
 
-### sandbox_batch
-```
-sandbox_batch(items: Array<{type: "execute", language, code} | {type: "search", query}>)
-```
-Atomic batch — all items run, results returned together.
+Deprecated alias: `ctx_execute_file`.
 
-### content_index
+### sandbox_batch
 ```
-content_index(label: string, content?: string, filePath?: string, contentType?: "markdown"|"json"|"plain", chunkSize?: number)
+sandbox_batch(items: Array<{ type: "execute", language: string, code: string, timeout?: number }>)
 ```
-Index content into FTS5. Provide either `content` or `filePath`. Auto-chunks by type.
+Run multiple sandbox executions and return a single combined result.
 
-### content_search
-```
-content_search(query: string, limit?: number, offset?: number)
-```
-Search FTS5 index. Returns ranked results with title, content, source, rank.
-
-### content_fetch
-```
-content_fetch(url: string, label?: string, chunkSize?: number)
-```
-Fetch URL → markdown → index. Auto-indexes for later search.
+Deprecated alias: `ctx_batch_execute`.
 
 ### compactor_stats
 ```
 compactor_stats()
 ```
-Dashboard: session events, compactions, tokens saved, indexed docs, sandbox runs, search queries.
+Dashboard: session events, compactions, tokens saved, compression ratio, sandbox runs, and search queries.
+
+Deprecated alias: `ctx_stats`.
 
 ### compactor_doctor
 ```
 compactor_doctor()
 ```
-Diagnostics: config file, session DB, content store, runtimes (node, python3, bash).
+Diagnostics: config file, session DB, and available runtimes (node, python3, bash).
+
+Deprecated alias: `ctx_doctor`.
 
 ### context_budget
 ```
 context_budget()
 ```
-Estimate remaining context tokens and % full. Returns guidance on whether to compact.
+Estimate remaining context tokens and percent full. Uses Pi's live context usage when available and includes percentage auto-compaction guidance when enabled.
 
 ## Sandbox Language Reference
 
@@ -90,44 +85,34 @@ Estimate remaining context tokens and % full. Returns guidance on whether to com
 | r | Rscript | 30s | - |
 | elixir | elixir | 30s | - |
 
-## FTS5 Search Modes
-
-| Mode | When To Use |
-|------|-------------|
-| **porter** | Exact term matching with stemming |
-| **trigram** | Fuzzy/spelling errors, partial matches |
-| **rrf** | Best overall (Reciprocal Rank Fusion of porter+trigram) |
-| **fuzzy** | Auto-correction of misspellings from vocabulary |
-
-Default: `rrf` (best general-purpose).
-
 ## Anti-Patterns
 
-1. **Don't call `compact` in a tight loop.** It triggers the full compaction pipeline. Call once before complex work.
-2. **Don't search without indexing.** `content_search` has nothing to search until you `content_index` or `content_fetch`.
-3. **Don't use `sandbox` for file ops.** Use bash instead. Sandbox is for computation.
-4. **Don't use `session_recall` with empty query.** It needs meaningful search terms.
-5. **Don't index node_modules.** Stick to source files and documentation.
-6. **Don't compact mid-task.** Wait for a natural break point.
+1. **Don't compact in a tight loop.** Use `context_budget` first and compact at natural break points.
+2. **Don't use `session_recall` for project-wide code search.** It searches the conversation/session. Use CocoIndex (`cocoindex_search`) for indexed files when installed.
+3. **Don't use `sandbox` for file operations.** Use normal file tools for reads/writes; sandbox is for computation or quick scripts.
+4. **Don't use empty or vague recall queries.** Search for specific filenames, issue numbers, commands, or decisions.
+5. **Don't compact mid-thought if avoidable.** Finish the current step, then compact.
 
 ## Workflow Patterns
 
-### Research → Index → Search → Test
-1. `content_fetch(url)` — index reference docs
-2. `content_search(query)` — find relevant sections
-3. `sandbox(lang, code)` — test hypotheses
-
-### Diagnose → Fix → Verify
-1. `compactor_doctor` — check system health
-2. Fix issues (install runtimes, rebuild index)
-3. `compactor_stats` — verify metrics
-
 ### Before Complex Work
-1. `compact` — free up context
-2. `content_index` — index relevant files
-3. `session_recall("goals")` — load context
-
-### After Long Session
-1. `compactor_stats` — check savings
-2. `compact` — compact if needed
-3. `session_recall(topic)` — verify recall quality
+1. `context_budget` — check pressure.
+2. `session_recall("goal files decisions")` — recover relevant prior context.
+3. `compact(dryRun: true)` — preview if context is tight.
+4. `/unipi:lossless-compact` or `compact` at a clean boundary.
+
+### Diagnose Compactor Health
+1. `compactor_doctor` — check config, DB, runtimes.
+2. Fix reported issues.
+3. `compactor_stats` — verify counters and savings.
+
+### Long Session Recovery
+1. `session_recall(query)` — find older details hidden by compaction.
+2. `context_budget` — decide whether another compaction is needed.
+3. `compactor_stats` — confirm compactions/savings are recorded.
+
+### Project Search
+Compactor no longer owns project content indexing. Use the CocoIndex package if installed:
+1. `/unipi:cocoindex-init`
+2. `/unipi:cocoindex-update`
+3. `cocoindex_search(query)`