@pi-unipi/unipi 2.0.3 → 2.0.5

package/README.md

@@ -15,7 +15,7 @@ pi install npm:@pi-unipi/unipi
 
 **[Memory](./packages/memory/README.md)** — SQLite + vector search stores facts, preferences, and decisions. Project-scoped and global. The agent remembers what you told it last week.
 
-**[Compactor](./packages/compactor/README.md)** — Zero-LLM context engine. 6-stage pipeline hits 95%+ token reduction at zero API cost. Session continuity, sandbox execution, FTS5 search.
+**[Compactor](./packages/compactor/README.md)** — Zero-LLM context engine. 6-stage pipeline hits 95%+ token reduction at zero API cost. Session continuity, percentage auto-compaction, session recall, and sandbox execution.
 
 **[CocoIndex](./packages/cocoindex/README.md)** — Project indexing and semantic code search backed by CocoIndex and LanceDB. Agent tools and slash commands for status, init, update, and search.
 
@@ -25,9 +25,9 @@ pi install npm:@pi-unipi/unipi
 
 **[MCP](./packages/mcp/README.md)** — Browse 7,800+ MCP servers, add them interactively. Tools from servers register automatically as Pi tools.
 
-**[Notify](./packages/notify/README.md)** — Push notifications to native OS, Gotify, Telegram, or ntfy. Per-event platform routing. Configure once, get alerts everywhere.
+**[Notify](./packages/notify/README.md)** — Push notifications to native OS, Gotify, Telegram, or ntfy. Per-event platform routing plus native focus suppression so alerts can stay quiet while Pi is already focused.
 
-**[Footer](./packages/footer/README.md)** — Persistent status bar showing live stats from every package. Responsive layout, presets, per-segment toggling.
+**[Footer](./packages/footer/README.md)** — Persistent status bar showing live stats from every package. Responsive layout, presets, per-segment toggling, and terminal-aware color fallback.
 
 **[BTW](./packages/btw/README.md)** — Side conversations that run in parallel. Ask questions without interrupting the main agent.
 
@@ -45,7 +45,7 @@ pi install npm:@pi-unipi/unipi
 
 **[Input Shortcuts](./packages/input-shortcuts/README.md)** — Keyboard shortcuts via vim-style chord overlay. Stash/restore, undo/redo, clipboard, thinking toggle.
 
-**[Command Enchantment](./packages/autocomplete/README.md)** — Enhanced `/unipi:*` autocomplete with package grouping, descriptions, colors, and registry audits that catch stale command docs before release.
+**[Command Enchantment](./packages/autocomplete/README.md)** — Enhanced `/unipi:*` autocomplete with full command names, package tags, descriptions, colors, and registry audits that catch stale command docs before release.
 
 ## Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,7 @@
   ],
   "scripts": {
     "typecheck": "npx tsc --noEmit --skipLibCheck",
-    "test": "npm test --workspaces",
+    "test": "npm test --workspaces --if-present",
     "publish:all": "npm publish --workspaces --access public"
   },
   "files": [

package/packages/autocomplete/README.md

@@ -9,6 +9,7 @@ Command Enchantment has no user commands. It improves the editor autocomplete ex
 ## What It Does
 
 - Groups `/unipi:*` commands by package so workflow, memory, web, footer, and other commands are visually distinct.
+- Shows full command values like `unipi:brainstorm` while replacing Pi source tags with concise package tags like `[workflow]`.
 - Sorts matches in predictable tiers: exact Unipi matches first, then other Unipi matches, then system commands.
 - Preserves dynamic argument completions from command providers, including workflow document and worktree suggestions.
 - Ships an audit test that checks registered Unipi commands are represented in the autocomplete registry and have descriptions.

package/packages/autocomplete/src/provider.ts

@@ -43,6 +43,18 @@ function fuzzyMatch(text: string, query: string): boolean {
 
 // ─── Namespace detection ─────────────────────────────────────────────
 
+/**
+ * Pi prefixes extension command descriptions with source tags such as
+ * `[u:npm:@pi-unipi/unipi]`. The enchanted provider replaces that with
+ * package tags (`[workflow]`, `[memory]`, …), so strip the source tag from
+ * base descriptions before reusing them.
+ */
+function stripPiSourceTag(description: string): string {
+  return description
+    .replace(/^\[(?:[upt])(?::[^\]]+)?\]\s*/, "")
+    .trimStart();
+}
+
 /**
  * If the query looks like a package namespace (e.g. "workflow", "memory",
  * "utility"), return that package name so its commands sort to the top.
@@ -174,7 +186,7 @@ function getEnhancedUnipiItems(
 
     return {
       value: cmd,
-      label: cmd.replace("unipi:", ""),
+      label: cmd,
       description: desc ? `${tag} ${desc}` : tag,
     };
   });
@@ -261,7 +273,10 @@ export function createEnchantedProvider(
         for (const item of baseSuggestions.items) {
           if (item.value.startsWith("unipi:")) {
             if (item.description) {
-              descriptionOverrides.set(item.value, item.description);
+              const cleanDescription = stripPiSourceTag(item.description);
+              if (cleanDescription) {
+                descriptionOverrides.set(item.value, cleanDescription);
+              }
             }
           } else {
             nonUnipiItems.push(item);

package/packages/compactor/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/packages/compactor/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.