ultimate-pi 0.1.6 → 0.1.7

package/.pi/prompts/harness-setup.md

@@ -1,6 +1,6 @@
 ---
-description: Full harness bootstrap — obsidian wiki scaffold, CLI tools install, pi extension packages, and verification. Run once per project.
-argument-hint: "[--skip-wiki] [--skip-tools] [--force] [--wiki-path <path>]"
+description: Full harness bootstrap — obsidian wiki scaffold, optional self-hosted firecrawl (Docker), CLI tools install, pi extension packages, and verification. Run once per project.
+argument-hint: "[--skip-wiki] [--skip-tools] [--skip-firecrawl-self] [--force] [--wiki-path <path>]"
 ---
 
 # harness-setup — Full Harness Bootstrap
@@ -110,12 +110,140 @@ Run the `/wiki` prompt flow using the user-confirmed `$WIKI_PATH`:
    ├── meta/             # dashboards, lint reports
    └── components/       # reusable sub-modules
    ```
-4. Create `$WIKI_PATH/../.vault-meta/` with vault metadata (at project root level, not inside wiki).
-5. Create vault `AGENTS.md` in project root with mode, purpose, conventions, operations.
+4. Create `$WIKI_PATH/.vault-meta/` with vault metadata (inside the wiki vault).
+5. Create vault `AGENTS.md` inside `$WIKI_PATH/` with mode, purpose, conventions, operations.
 6. Initialize wiki git tracking if not already present.
 7. Write initial `$WIKI_PATH/hot.md` with setup timestamp.
 8. **Save resolved path** to `.pi/settings.json` (merge `"wiki_path": "<relative-path>"` into settings) for future sessions.
 
+## Step 1.5 — Optional Self-Hosted Firecrawl
+
+Ask: "Use self-hosted Firecrawl (local Docker) or cloud (api.firecrawl.dev)? [cloud/self]"
+Default: **cloud**.
+
+If user chooses **self**:
+
+### 1.5.1 — Docker Engine Install
+
+Check if Docker is already available:
+```bash
+if ! command -v docker &>/dev/null; then
+	# Detect OS and install Docker Engine
+	if [ -f /etc/os-release ]; then
+		. /etc/os-release
+		case "$ID" in
+			ubuntu|debian)
+				curl -fsSL https://get.docker.com | sh
+				;;
+				fedora|rhel|centos)
+				curl -fsSL https://get.docker.com | sh
+				;;
+				arch)
+				pacman -S --noconfirm docker
+				;;
+			*)
+				echo "Unsupported distro: $ID. Install Docker manually: https://docs.docker.com/engine/install/"
+				;;
+		esac
+	elif command -v brew &>/dev/null; then
+		# macOS — install Docker Desktop via brew
+		brew install --cask docker
+	else
+		echo "Cannot detect OS. Install Docker manually: https://docs.docker.com/engine/install/"
+	fi
+
+	# Enable and start Docker
+	sudo systemctl enable --now docker 2>/dev/null || true
+
+	# Add current user to docker group (no sudo needed)
+	sudo usermod -aG docker $USER 2>/dev/null || true
+	newgrp docker 2>/dev/null || echo "Docker group added. Restart terminal or run: newgrp docker"
+fi
+```
+
+Verify:
+```bash
+docker --version
+docker compose version
+```
+
+Block if Docker install fails. Show manual install link.
+
+### 1.5.2 — Set Up Self-Hosted Firecrawl Files
+
+The `firecrawl/` directory in the project root contains all self-hosted config:
+
+```
+firecrawl/
+├── docker-compose.yaml   # Multi-service compose (API, Playwright, Redis, RabbitMQ, Postgres, SearXNG)
+├── README.md             # Self-hosted usage docs
+├── .env.template         # Environment variables template
+└── searxng/
+    ├── searxng.env       # SearXNG-specific env
+    └── settings.yml      # SearXNG engine config
+```
+
+Create `.env` from template if missing:
+```bash
+if [ ! -f firecrawl/.env ]; then
+	if [ -f firecrawl/.env.template ]; then
+		cp firecrawl/.env.template firecrawl/.env
+		echo "Created firecrawl/.env from template."
+	else
+		cat > firecrawl/.env << 'EOF'
+# Firecrawl Self-Hosted Configuration
+PORT=3002
+INTERNAL_PORT=3002
+REDIS_URL=redis://redis:6379
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=postgres
+USE_DB_AUTHENTICATION=false
+NUM_WORKERS_PER_QUEUE=8
+CRAWL_CONCURRENT_REQUESTS=10
+MAX_CONCURRENT_JOBS=5
+BROWSER_POOL_SIZE=5
+BULL_AUTH_KEY=changeme
+SEARXNG_EXTERNAL_PORT=8080
+# Optional AI: uncomment and set
+# OPENAI_API_KEY=
+# OPENAI_BASE_URL=
+# MODEL_NAME=
+# OLLAMA_BASE_URL=
+EOF
+		echo "Created firecrawl/.env with defaults."
+	fi
+fi
+```
+
+### 1.5.3 — Start Services
+
+```bash
+docker compose -f firecrawl/docker-compose.yaml up -d
+```
+
+Wait for health:
+```bash
+echo "Waiting for services to be healthy..."
+for i in $(seq 1 30); do
+	if curl -sf http://localhost:3002/v1/health &>/dev/null; then
+		echo "✓ Firecrawl API is healthy"
+		break
+	fi
+	sleep 2
+done
+```
+
+### 1.5.4 — Verify Self-Hosted Instance
+
+```bash
+curl -sf http://localhost:3002/v1/health && echo "✓ Self-hosted Firecrawl running on :3002" || echo "✗ Firecrawl not healthy yet — check: docker compose -f firecrawl/docker-compose.yaml logs"
+docker compose -f firecrawl/docker-compose.yaml ps
+```
+
+If user chose **cloud**, skip all 1.5.x steps. Just note:
+> "Using cloud Firecrawl. Ensure `FIRECRAWL_API_KEY` is set. Run `firecrawl login` in Step 2.1."
+
 ## Step 2 — Install Global CLI Packages
 
 Check each package first. Install only if missing unless `--force` flag.
@@ -133,7 +261,18 @@ Verify:
 firecrawl --status
 ```
 
-If not authenticated, offer browser login or API key:
+**If self-hosted mode (Step 1.5 was chosen):** skip cloud auth. Point CLI at local instance:
+```bash
+export FIRECRAWL_API_URL=http://localhost:3002
+export FIRECRAWL_API_KEY=""
+```
+Add to shell profile for persistence:
+```bash
+echo 'export FIRECRAWL_API_URL=http://localhost:3002' >> ~/.bashrc 2>/dev/null
+echo 'export FIRECRAWL_API_KEY=""' >> ~/.bashrc 2>/dev/null
+```
+
+**If cloud mode:** authenticate if not already:
 ```bash
 firecrawl login --browser
 # OR
@@ -324,7 +463,7 @@ Ensure `.gitignore` contains:
 
 ### 4.2 — Vault AGENTS.md
 
-If not already created by Step 1, create a minimal `AGENTS.md` in project root:
+If not already created by Step 1, create a minimal `AGENTS.md` inside `$WIKI_PATH/`:
 
 ```markdown
 # ultimate-pi: Agentic Harness Wiki
@@ -337,7 +476,6 @@ Wiki vault path: `$WIKI_PATH`
 
 ## Structure
 
-`$WIKI_PATH/`
 ├── index.md → master catalog
 ├── log.md → chronological operations
 ├── hot.md → recent context cache
@@ -348,21 +486,22 @@ Wiki vault path: `$WIKI_PATH`
 ├── entities/ → tools, platforms, people
 ├── questions/ → filed research answers
 ├── consensus/ → debate verdicts
-└── flows/ → pipeline diagrams
+├── flows/ → pipeline diagrams
+└── .vault-meta/ → vault metadata
 
 ## Conventions
 
 - YAML frontmatter required: type, status, created, updated, tags
 - Wikilinks: [[Page Name]] format
 - .raw/ is immutable source storage
-- $WIKI_PATH/index.md updated on every ingest
-- $WIKI_PATH/log.md is append-only, newest at top
+- index.md updated on every ingest
+- log.md is append-only, newest at top
 
 ## Cross-Project Reference
 
 Other projects can reference this vault:
-1. Read $WIKI_PATH/hot.md (~500 tokens)
-2. Read $WIKI_PATH/index.md if needed
+1. Read hot.md (~500 tokens)
+2. Read index.md if needed
 3. Drill into specific topics as needed
 
 ## Path Resolution
@@ -461,13 +600,16 @@ Output summary table:
 
 | .gitignore | ✓/✗ | 6 entries added |
 | wiki_path in settings | ✓/✗ | Persisted to .pi/settings.json |
+| Firecrawl mode | self/cloud | Self-hosted on :3002 / Cloud (api.firecrawl.dev) |
+| Docker Engine | ✓/✗/N/A | Installed / Not needed (cloud mode) |
 
 Next steps:
 1. If tools missing: re-run with `--force` or install individually
 2. If wiki not scaffolded: run `/wiki` prompt
 3. If gh not authenticated: `gh auth login`
-4. First harness run: `/harness "your task description"`
-5. To change wiki path later: update `VAULT_WIKI_PATH` env var or `.pi/settings.json` → `wiki_path` field
+4. If self-hosted Firecrawl unhealthy: `docker compose -f firecrawl/docker-compose.yaml logs`
+5. First harness run: `/harness "your task description"`
+6. To change wiki path later: update `VAULT_WIKI_PATH` env var or `.pi/settings.json` → `wiki_path` field
 
 ## Guard Rails
 
@@ -475,11 +617,13 @@ Next steps:
 - **Wiki path must be writable**: Check `test -w "$(dirname "$WIKI_PATH")"` before scaffold. Block if not writable.
 - **Wiki path outside project**: Allowed (e.g., `~/vaults/my-project`). Cross-project vault sharing is supported.
 - **Node.js >= 18 required**: Some pi packages use modern Node APIs.
+- **Docker required for self-hosted**: Step 1.5 needs Docker Engine + Compose. Block if install fails.
+- **Sufficient RAM for self-hosted**: Firecrawl stack needs ~8GB+ free (API: 8G, Playwright: 4G, others).
 - **Idempotent**: All checks skip if already installed. `--force` overrides.
 - **No destructive actions**: Creates files only if missing. Never overwrites existing wiki content.
 - **Wiki safety**: Scaffold only creates structure, never modifies existing wiki content.
 - **Partial success**: If some tools fail, report which and continue. User can fix individually.
-- **Rate limits**: ctx7 login is optional. firecrawl auth is required for web operations.
+- **Rate limits**: ctx7 login is optional. firecrawl auth is required for cloud; none needed for self-hosted.
 - **Settings persistence**: The resolved `wiki_path` is saved to `.pi/settings.json` so future sessions auto-detect it.
 
 ## Error Handling
@@ -498,6 +642,10 @@ Next steps:
 | biome.json missing | Create minimal config. |
 | settings.json not writable | Warn. Wiki path won't persist across sessions. |
 | No internet | Block for tool installs. Continue for wiki-only steps if `--skip-tools`. |
+| Docker not running | Start: `sudo systemctl start docker`. Block if cannot start. |
+| Docker install fails | Show manual link: https://docs.docker.com/engine/install/. Block Step 1.5, continue rest. |
+| Port 3002 already in use | Warn. User must free port or change `PORT` in `firecrawl/.env`. |
+| Self-hosted health check timeout | Show logs: `docker compose -f firecrawl/docker-compose.yaml logs`. Continue — may need more time. |
 
 ## Flags
 
@@ -505,5 +653,6 @@ Next steps:
 |------|--------|
 | `--skip-wiki` | Skip Step 1 (wiki scaffold). Use when wiki already exists. |
 | `--skip-tools` | Skip Step 2 (CLI tool installs). Use when tools already set up. |
+| `--skip-firecrawl-self` | Skip Step 1.5 (self-hosted Firecrawl). Always use cloud. |
 | `--force` | Reinstall all tools even if already present. Overwrite existing files. |
 | `--wiki-path <path>` | Override wiki vault path. Absolute or relative to project root. Bypasses env var and settings. |

package/.pi/settings.json

@@ -8,9 +8,9 @@
 	"packages": [
 		"..",
 		"npm:@posthog/pi",
-		"npm:pi-lean-ctx",
+		"npm:context-mode",
 		"npm:@tintinweb/pi-subagents",
 		"npm:@yeliu84/pi-model-router",
-		"npm:pi-smart-voice-notify"
+		"npm:@sting8k/pi-vcc"
 	]
 }

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [v0.1.7] — 2026-05-07
+
+### ✨ Features
+
+- add /release prompt for version bump and CI/CD publish
+- integrate pi-vcc for deterministic auto-compaction
+- replace pi-lean-ctx with context-mode
+- add soundboard extension, update settings and firecrawl env template
+
+### 🔧 Chores
+
+- bump to 0.1.7, move vault AGENTS.md and .vault-meta under VAULT_WIKI_PATH

package/CONTRIBUTING.md

@@ -113,4 +113,4 @@ Configurable via env vars (set before launching pi):
 
 `wiki`, `wiki-save`, `wiki-query`, `wiki-ingest`, `wiki-lint`, `wiki-fold`, `autoresearch`, `canvas`, `obsidian-markdown`, `obsidian-bases`
 
-> `lean-ctx` is installed as a separate pi package (`pi-lean-ctx`) — not bundled as a skill.
+> `context-mode` is installed as a separate pi package (`npm:context-mode`) — not bundled as a skill.

package/firecrawl/.env.template

@@ -1,58 +1,62 @@
-# ===== Required ENVS ======
+# Firecrawl Self-Hosted Configuration Template
+# Copy to .env and adjust values as needed.
+
+# === API Service ===
 PORT=3002
+INTERNAL_PORT=3002
 HOST=0.0.0.0
-USE_DB_AUTHENTICATION=false
+ENV=local
 
-# ===== Optional ENVS ======
-# OpenAI API key for AI features (JSON formatting, /extract API)
-# OPENAI_API_KEY=
+# === Redis ===
+REDIS_URL=redis://redis:6379
 
-# Experimental: Use Ollama
-# OLLAMA_BASE_URL=http://localhost:11434/api
-# MODEL_NAME=deepseek-r1:7b
-# MODEL_EMBEDDING_NAME=nomic-embed-text
+# === PostgreSQL (NUQ) ===
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=postgres
+POSTGRES_HOST=nuq-postgres
+POSTGRES_PORT=5432
+USE_DB_AUTHENTICATION=false
 
-# Experimental: Use any OpenAI-compatible API
-# OPENAI_BASE_URL=https://example.com/v1
+# === Queue / Workers ===
+NUM_WORKERS_PER_QUEUE=8
+CRAWL_CONCURRENT_REQUESTS=10
+MAX_CONCURRENT_JOBS=5
+BROWSER_POOL_SIZE=5
+BULL_AUTH_KEY=changeme
+TEST_API_KEY=
+
+# === Playwright Browser Service ===
+PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/scrape
+BLOCK_MEDIA=false
+ALLOW_LOCAL_WEBHOOKS=true
+MAX_CONCURRENT_PAGES=10
+
+# === AI / LLM (optional) ===
 # OPENAI_API_KEY=
+# OPENAI_BASE_URL=
+# MODEL_NAME=
+# MODEL_EMBEDDING_NAME=
+# OLLAMA_BASE_URL=
 
-# ===== Proxy =====
-# PROXY_SERVER can be a full URL (e.g. http://0.1.2.3:1234) or just an IP:port combo
-# PROXY_SERVER=
-# PROXY_USERNAME=
-# PROXY_PASSWORD=
-
-# ===== /search API =====
-# SearXNG instance running alongside Firecrawl in docker-compose
-SEARXNG_ENDPOINT=http://searxng:8080
-# SEARXNG_ENGINES=
-# SEARXNG_CATEGORIES=
-
-# ===== Authentication / Admin =====
-# Supabase not configured (self-hosted doesn't support it yet)
+# === Integrations ===
+# AUTUMN_SECRET_KEY=
+# SLACK_WEBHOOK_URL=
 # SUPABASE_ANON_TOKEN=
 # SUPABASE_URL=
 # SUPABASE_SERVICE_TOKEN=
+# SELF_HOSTED_WEBHOOK_URL=
 
-# Change this for security in production
-BULL_AUTH_KEY=CHANGEME
-
-# ===== PostgreSQL =====
-POSTGRES_USER=firecrawl
-POSTGRES_PASSWORD=firecrawl_password
-POSTGRES_DB=postgres
-
-# ===== Optional: Telemetry / Logging =====
-# POSTHOG_API_KEY=
-# POSTHOG_HOST=
-# SLACK_WEBHOOK_URL=
-
-# ===== Optional: Local webhooks =====
-# ALLOW_LOCAL_WEBHOOKS=true
+# === Proxy (optional) ===
+# PROXY_SERVER=
+# PROXY_USERNAME=
+# PROXY_PASSWORD=
 
-# ===== Auto-configured by docker-compose (do not change) =====
-# REDIS_URL=redis://redis:6379
-# PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/scrape
+# === Logging ===
+LOGGING_LEVEL=info
 
-# ===== Optional: Block media (images, video, etc.) during scrape =====
-# BLOCK_MEDIA=true
+# === SearXNG ===
+SEARXNG_ENDPOINT=http://searxng:8080
+SEARXNG_ENGINES=google,bing,duckduckgo
+SEARXNG_CATEGORIES=general,science,technology
+SEARXNG_EXTERNAL_PORT=8080

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.1.6",
+	"version": "0.1.7",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -14,7 +14,7 @@
 		"agent-skills",
 		"cursor-sdk",
 		"firecrawl",
-		"lean-ctx",
+		"context-mode",
 		"vcc"
 	],
 	"license": "MIT",
@@ -54,7 +54,6 @@
 	"dependencies": {
 		"@cursor/sdk": "^1.0.12",
 		"@sting8k/pi-vcc": "^0.3.12",
-		"asciify-image": "^0.1.10",
-		"pi-smart-voice-notify": "^0.4.0"
+		"asciify-image": "^0.1.10"
 	}
 }

package/vault/wiki/concepts/vcc-conversation-compaction-for-pi.md

@@ -1,7 +1,8 @@
 ---
 type: concept
-status: developing
+status: active
 created: 2026-05-05
+updated: 2026-05-07
 tags:
   - pi-agent
   - vcc
@@ -11,6 +12,7 @@ related:
   - "[[pi-vcc-github-repo]]"
   - "[[context-continuity]]"
   - "[[structured-compaction]]"
+  - "[[adr-027]]"
 ---
 
 # VCC Conversation Compaction for Pi

package/vault/wiki/decisions/2026-05-07-replace-lean-ctx-with-context-mode.md

@@ -0,0 +1,59 @@
+---
+type: decision
+title: "Replace pi-lean-ctx with context-mode"
+created: 2026-05-07
+updated: 2026-05-07
+tags:
+  - decision
+  - context-optimization
+  - migration
+status: accepted
+related:
+  - "[[context-mode]]"
+  - "[[lean-ctx]]"
+  - "[[agentic-harness-context-enforcement]]"
+
+---
+# Replace pi-lean-ctx with context-mode
+
+## Context
+
+ultimate-pi uses `pi-lean-ctx@3.5.1` for context compression via AST parsing, shell pattern compression, and smart read modes. User requested migration to `context-mode` (11K+ GitHub stars, 48K npm downloads/month) as the primary context optimization layer.
+
+context-mode uses intercept-and-sandbox architecture: raw tool output never enters the agent's context window. Instead, output is indexed into SQLite FTS5 with BM25 ranking, and the agent queries on demand. Claims 98-99.5% token reduction. Has native Pi Coding Agent extension support with session_start, tool_call, tool_result, and session_before_compact hooks.
+
+## Alternatives Considered
+
+1. **Keep pi-lean-ctx** — mature, 48 MCP tools, agent governance (profiles, budgets, SLOs), Apache 2.0. Less community adoption (924 stars vs 11K).
+2. **Run both simultaneously** — wiki research notes they solve complementary halves (lean-ctx: compress input, context-mode: sandbox output). However, potential tool conflicts, complexity, and user explicitly requested removal.
+3. **Replace with context-mode** — stronger community validation, native Pi extension, FTS5 sandbox, "Think in Code" paradigm, session continuity.
+
+## Chosen
+
+Replace pi-lean-ctx with context-mode (`npm:context-mode@^1.0.111`).
+
+## Changes Made
+
+- `.pi/settings.json`: replaced `"npm:pi-lean-ctx"` with `"npm:context-mode"`
+- `.pi/npm/package.json`: replaced `"pi-lean-ctx": "^3.5.1"` with `"context-mode": "^1.0.111"`
+- `package.json`: replaced `"lean-ctx"` keyword with `"context-mode"`
+- `.pi/extensions/ck-enforce.ts`: **deleted** (lean-ctx-specific grep override, no longer needed)
+- `CONTRIBUTING.md`: updated lean-ctx reference to context-mode
+
+## Tradeoffs
+
+| Gained | Lost |
+|--------|------|
+| 11K+ GitHub stars, larger community | 48 MCP tools reduced to 11 |
+| FTS5 sandbox (output never enters context) | AST-based compression (tree-sitter, 18 languages) |
+| Native Pi extension with full hook lifecycle | 90+ shell pattern compression |
+| "Think in Code" paradigm enforcement | Smart read modes (full/map/signatures) |
+| Session continuity (26 events) | Agent governance (profiles, budgets, SLOs) |
+
+## Consequences
+
+- Need to ensure context-mode's `ctx_search` and `ctx_execute` tools are integrated into the search policy
+- ck-enforce.ts was blocking conceptual grep searches and steering to `ck --hybrid` — this enforcement is lost; SYSTEM.md grep policy still applies but relies on agent compliance
+- context-mode uses ELv2 license (vs Apache 2.0) — acceptable for internal use
+- `npm install` in `.pi/npm/` installed 42 new packages, removed pi-lean-ctx
+- Wiki pages referencing `[[lean-ctx]]` should be updated to reference `[[context-mode]]` where appropriate

package/vault/wiki/decisions/adr-027.md

@@ -0,0 +1,94 @@
+---
+type: decision
+title: "ADR-027: pi-vcc Overrides Built-in Auto-Compaction"
+status: accepted
+priority: 1
+date: "2026-05-07"
+tags: [adr, compaction, pi-vcc, vcc, context]
+sources:
+  - "[[pi-vcc-github-repo]]"
+  - "[[vcc-conversation-compaction-for-pi]]"
+  - "https://github.com/sting8k/pi-vcc/issues/3"
+related:
+  - "[[adr-012]]"
+  - "[[adr-015]]"
+created: 2026-05-07
+updated: 2026-05-07
+---
+
+# ADR-027: pi-vcc Overrides Built-in Auto-Compaction
+
+## Context
+
+Pi's default compaction uses LLM-generated summaries. This is:
+- **Non-deterministic** — can hallucinate or lose context
+- **Expensive** — burns tokens on every compaction
+- **Slow** — waits for LLM call (seconds vs milliseconds)
+- **Destructive** — pre-compaction history is permanently lost
+
+[pi-vcc](https://github.com/sting8k/pi-vcc) is an algorithmic compaction extension inspired by lllyasviel's VCC. It provides:
+- **Deterministic** — same input = same output, no LLM
+- **Zero cost** — no API calls, algorithmic extraction
+- **Fast** — 30-470ms per compaction
+- **99% token reduction** on long sessions
+- **Lossless recall** — `vcc_recall` reads raw session JSONL
+
+### Problem: Model Stops After Auto-Compaction
+
+GitHub issue [sting8k/pi-vcc#3](https://github.com/sting8k/pi-vcc/issues/3): when `overrideDefaultCompaction: true`, the AI model stops generating after auto-compaction. The maintainer confirmed it is "by design for now."
+
+**Root cause**: pi-vcc's `buildOwnCut` keeps the last user message and everything after it as the "kept tail." When that tail contains a completed turn (user message + assistant's finished response), the LLM sees a complete conversation after session reload and has no signal to continue working.
+
+## Decision
+
+### 1. Project-level pi-vcc activation (not global)
+
+pi-vcc is registered as a **project-level package** in `.pi/settings.json`, not in `~/.pi/agent/settings.json`. The config lives at `.pi/pi-vcc-config.json`, referenced via `PI_VCC_CONFIG_PATH` in `.env`.
+
+This keeps the VCC override scoped to this project only. Other projects use pi's default LLM compaction.
+
+### 2. Enable `overrideDefaultCompaction: true`
+
+All compaction paths (auto-threshold, `/compact`, `/pi-vcc`) route through pi-vcc's algorithmic compactor.
+
+### 3. Fix "model stops" with continuation directive
+
+For auto-compactions (not manual `/pi-vcc`), append `[Continue]` section to the summary:
+
+```
+[Continue]
+Continue working on the current task. The user's request is not yet complete. Use vcc_recall if you need context from earlier in the session.
+```
+
+This is patched in `node_modules/@sting8k/pi-vcc/src/hooks/before-compact.ts`, applied only when `isPiVcc === false` (auto-compact or `/compact`).
+
+## Alternatives Considered
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **Keep default LLM compaction** | No risk of model stopping | Expensive, non-deterministic, slow |
+| **`overrideDefaultCompaction: false` (manual only)** | Safer, model never stops unexpectedly | User must run `/pi-vcc` manually; auto-compaction still burns LLM tokens |
+| **Fork pi-vcc repo** | Clean patch management | Overhead of maintaining fork, slow to upstream updates |
+| **Patch node_modules directly** (chosen) | Zero overhead, immediate fix | Patch lost on `npm update`; requires re-apply |
+| **Send synthetic "continue" message post-compaction** | Clean separation of concerns | Requires new `session_compact` handler; more invasive |
+| **Append continuation to summary** (chosen) | Simplest fix; minimal code change | Slightly longer summary text |
+
+## Consequences
+
+### Positive
+- **99% context reduction** on auto-compaction (vs ~70-80% with LLM)
+- **Zero compaction cost** — no LLM calls, saves tokens
+- **30-470ms latency** vs 2-10s LLM wait
+- **Deterministic output** — same session = same summary
+- **Lossless recall** via `vcc_recall` — pre-compaction history searchable
+- **Model continues working** after auto-compaction via continuation directive
+
+### Negative
+- Patch in node_modules is fragile — `npm update` removes it
+- Continuation directive may prompt unnecessary continuation if task IS actually complete (minor risk)
+- VCC config is project-scoped only — other projects don't benefit
+
+### Mitigations
+- Document the patch location so it can be re-applied after npm updates
+- Consider upstreaming the fix to pi-vcc repo
+- Continuation directive only fires on auto-compaction, not `/pi-vcc`

package/vault/wiki/log.md

@@ -8,7 +8,11 @@ tags: [meta, log, operations]
 
 # Wiki Operations Log
 
-## [2026-05-05] wiki-autoresearch | pi-vcc (ecosystem expansion + SOTA update)
+## [2026-05-07] replace | pi-lean-ctx → context-mode
+- **Decision**: [[2026-05-07-replace-lean-ctx-with-context-mode]]
+- **Changes**: replaced `npm:pi-lean-ctx` with `npm:context-mode` in `.pi/settings.json`; replaced `pi-lean-ctx` devDependency with `context-mode` in `.pi/npm/package.json`; deleted `.pi/extensions/ck-enforce.ts` (lean-ctx-specific grep override); updated `package.json` keyword and `CONTRIBUTING.md`
+- **Tradeoff**: gained FTS5 sandbox + 11K+ community + native Pi hooks; lost AST compression (tree-sitter 18 langs), 90+ shell pattern compression, smart read modes, agent governance (profiles/budgets/SLOs), 48 MCP tools → 11
+- **Risk**: `ck-enforce.ts` was blocking conceptual grep and steering to `ck --hybrid` — now relies on SYSTEM.md policy compliance alone
 - Rounds: 2 (broad search across 4 angles + targeted gap fill on 3 new extensions + 2 SOTA developments)
 - Searches: 8 | Sources found: 5 new (pi-rtk-optimizer, pi-omni-compact, pi-context-prune, Anthropic Compaction API, Context Folding paper)
 - Pages created: [[pi-rtk-optimizer-github-repo]], [[pi-omni-compact-github-repo]], [[pi-context-prune-github-repo]], [[anthropic-compaction-api]], [[context-folding-paper]] (sources), [[context-folding]] (concept)