ultimate-pi 0.2.3 → 0.2.5

package/.pi/harness/runs/019e2732-8651-74e5-9f5d-4d06c3105f25-1778774086096/trace.json

@@ -0,0 +1,42 @@
+{
+	"schema_version": "1.0.0",
+	"contract_version": "1.0.0",
+	"run_id": "019e2732-8651-74e5-9f5d-4d06c3105f25-1778774086096",
+	"plan_id": "plan-unknown",
+	"agent_id": "019e2732-8651-74e5-9f5d-4d06c3105f25",
+	"phase": "plan",
+	"model": "auto",
+	"thinking_level": "off",
+	"tool_spans": [
+		{
+			"tool_call_id": "call_00_7UHDcydTHJHVR2dT5xpb0903",
+			"tool_name": "bash",
+			"started_at": "2026-05-14T15:54:59.108Z",
+			"ended_at": "2026-05-14T15:54:59.108Z"
+		},
+		{
+			"tool_call_id": "call_01_aNsry1whTl5hRf5Ew91t3142",
+			"tool_name": "bash",
+			"started_at": "2026-05-14T15:54:59.136Z",
+			"ended_at": "2026-05-14T15:54:59.136Z"
+		},
+		{
+			"tool_call_id": "call_02_N2e56Q6vKr6cAYzd4Z9q7953",
+			"tool_name": "bash",
+			"started_at": "2026-05-14T15:54:59.139Z",
+			"ended_at": "2026-05-14T15:54:59.139Z"
+		},
+		{
+			"tool_call_id": "call_00_wG71Rv3SKrf6R9K03EeS0264",
+			"tool_name": "ctx_batch_execute",
+			"started_at": "2026-05-14T15:55:11.541Z",
+			"ended_at": "2026-05-14T15:55:11.541Z"
+		}
+	],
+	"artifact_refs": [],
+	"cost": {
+		"input_tokens": 16951,
+		"output_tokens": 1020,
+		"total_tokens": 17971
+	}
+}

package/.pi/harness/runs/019e2732-8651-74e5-9f5d-4d06c3105f25-1778774136101/events.jsonl

@@ -0,0 +1 @@
+{"timestamp":"2026-05-14T15:55:36.107Z","type":"run_start","run_id":"019e2732-8651-74e5-9f5d-4d06c3105f25-1778774136101","plan_id":"plan-unknown","phase":"plan"}

package/.pi/harness/runs/019e2758-b332-771b-ad6f-54d0d8478768-1778776600591/events.jsonl

@@ -0,0 +1,2 @@
+{"timestamp":"2026-05-14T16:36:40.660Z","type":"run_start","run_id":"019e2758-b332-771b-ad6f-54d0d8478768-1778776600591","plan_id":"plan-unknown","phase":"plan"}
+{"timestamp":"2026-05-14T16:36:47.570Z","type":"run_end","run_id":"019e2758-b332-771b-ad6f-54d0d8478768-1778776600591","phase":"plan","tool_span_count":0,"artifact_ref_count":0}

package/.pi/harness/runs/019e2758-b332-771b-ad6f-54d0d8478768-1778776600591/trace.json

@@ -0,0 +1,17 @@
+{
+	"schema_version": "1.0.0",
+	"contract_version": "1.0.0",
+	"run_id": "019e2758-b332-771b-ad6f-54d0d8478768-1778776600591",
+	"plan_id": "plan-unknown",
+	"agent_id": "019e2758-b332-771b-ad6f-54d0d8478768",
+	"phase": "plan",
+	"model": "auto",
+	"thinking_level": "off",
+	"tool_spans": [],
+	"artifact_refs": [],
+	"cost": {
+		"input_tokens": 21,
+		"output_tokens": 32,
+		"total_tokens": 53
+	}
+}

package/.pi/harness/runs/README.md

@@ -0,0 +1,6 @@
+# Harness Runs
+
+Store lightweight run metadata and trace indexes here.
+
+- Primary source of truth for full trace payloads remains external telemetry.
+- Local files should contain run IDs, pointers, and replay metadata only.

package/.pi/harness/runs/budget-events.jsonl

@@ -0,0 +1,4 @@
+{"timestamp":"2026-05-14T15:54:59.134Z","schema_version":"1.0.0","contract_version":"1.0.0","event_type":"budget_exhausted","run_id":"019e2732-8651-74e5-9f5d-4d06c3105f25","debate_id":"plan-budget-guard","round_count":1,"budget_used":16593,"exhaustion_reason":"debate_global_cap_exceeded","caps":{"max_rounds":6,"round_token_cap":2500,"debate_global_cap":35000},"minimum_evidence_confidence":0.6,"default_policy_outcome":"block","human_override_allowed":true}
+{"timestamp":"2026-05-14T15:54:59.138Z","schema_version":"1.0.0","contract_version":"1.0.0","event_type":"budget_exhausted","run_id":"019e2732-8651-74e5-9f5d-4d06c3105f25","debate_id":"plan-budget-guard","round_count":1,"budget_used":16593,"exhaustion_reason":"debate_global_cap_exceeded","caps":{"max_rounds":6,"round_token_cap":2500,"debate_global_cap":35000},"minimum_evidence_confidence":0.6,"default_policy_outcome":"block","human_override_allowed":true}
+{"timestamp":"2026-05-14T15:54:59.140Z","schema_version":"1.0.0","contract_version":"1.0.0","event_type":"budget_exhausted","run_id":"019e2732-8651-74e5-9f5d-4d06c3105f25","debate_id":"plan-budget-guard","round_count":1,"budget_used":16593,"exhaustion_reason":"debate_global_cap_exceeded","caps":{"max_rounds":6,"round_token_cap":2500,"debate_global_cap":35000},"minimum_evidence_confidence":0.6,"default_policy_outcome":"block","human_override_allowed":true}
+{"timestamp":"2026-05-14T15:55:11.581Z","schema_version":"1.0.0","contract_version":"1.0.0","event_type":"budget_exhausted","run_id":"019e2732-8651-74e5-9f5d-4d06c3105f25","debate_id":"plan-budget-guard","round_count":1,"budget_used":17161,"exhaustion_reason":"debate_global_cap_exceeded","caps":{"max_rounds":6,"round_token_cap":2500,"debate_global_cap":35000},"minimum_evidence_confidence":0.6,"default_policy_outcome":"block","human_override_allowed":true}

package/.pi/harness/runs/canary-candidate-router.json

@@ -0,0 +1,72 @@
+{
+	"defaultProfile": "auto",
+	"debug": false,
+	"classifierModel": "opencode-go/qwen3.6-plus",
+	"phaseBias": 0.5,
+	"maxSessionBudget": 1.0,
+	"largeContextThreshold": 100000,
+	"rules": [
+		{
+			"matches": ["deploy", "production", "release"],
+			"tier": "high",
+			"reason": "Safety check for production tasks"
+		},
+		{
+			"matches": "changelog",
+			"tier": "low"
+		}
+	],
+	"profiles": {
+		"auto": {
+			"high": {
+				"model": "opencode-go/deepseek-v4-pro",
+				"thinking": "high",
+				"fallbacks": ["opencode-go/qwen3.6-plus", "opencode-go/kimi-k2.6"]
+			},
+			"medium": {
+				"model": "opencode-go/qwen3.6-plus",
+				"thinking": "medium",
+				"fallbacks": ["opencode-go/deepseek-v4-pro"]
+			},
+			"low": {
+				"model": "opencode-go/deepseek-v4-flash",
+				"thinking": "low",
+				"fallbacks": ["opencode-go/qwen3.5-plus"]
+			}
+		},
+		"cheap": {
+			"high": {
+				"model": "opencode-go/qwen3.6-plus",
+				"thinking": "low",
+				"fallbacks": ["opencode-go/qwen3.5-plus"]
+			},
+			"medium": {
+				"model": "opencode-go/qwen3.5-plus",
+				"thinking": "off",
+				"fallbacks": ["opencode-go/deepseek-v4-flash"]
+			},
+			"low": {
+				"model": "opencode-go/deepseek-v4-flash",
+				"thinking": "off",
+				"fallbacks": ["opencode-go/qwen3.5-plus"]
+			}
+		},
+		"deep": {
+			"high": {
+				"model": "opencode-go/deepseek-v4-pro",
+				"thinking": "xhigh",
+				"fallbacks": ["opencode-go/kimi-k2.6"]
+			},
+			"medium": {
+				"model": "opencode-go/kimi-k2.6",
+				"thinking": "medium",
+				"fallbacks": ["opencode-go/deepseek-v4-pro"]
+			},
+			"low": {
+				"model": "opencode-go/qwen3.6-plus",
+				"thinking": "low",
+				"fallbacks": ["opencode-go/deepseek-v4-flash"]
+			}
+		}
+	}
+}

package/.pi/harness/runs/canary-evidence.json

@@ -0,0 +1,9 @@
+{
+	"sample_count": 24,
+	"min_sample_count": 12,
+	"success_rate_delta": 0.08,
+	"cost_per_task_delta": -0.04,
+	"regression_guard_passed": true,
+	"trace_refs": ["run-canary-001", "run-canary-002"],
+	"notes": "canary validation synthetic evidence"
+}

package/.pi/harness/runs/index.jsonl

@@ -0,0 +1,4 @@
+{"timestamp":"2026-05-14T15:51:38.345Z","run_id":"019e272f-3eef-7107-9712-ce281de55707-1778773891854","plan_id":"plan-unknown","phase":"plan","trace_file":"/home/aryaniyaps/ai-projects/ultimate-pi/.pi/harness/runs/019e272f-3eef-7107-9712-ce281de55707-1778773891854/trace.json"}
+{"timestamp":"2026-05-14T15:52:14.312Z","run_id":"019e272f-3eef-7107-9712-ce281de55707-1778773912057","plan_id":"plan-unknown","phase":"plan","trace_file":"/home/aryaniyaps/ai-projects/ultimate-pi/.pi/harness/runs/019e272f-3eef-7107-9712-ce281de55707-1778773912057/trace.json"}
+{"timestamp":"2026-05-14T15:55:25.166Z","run_id":"019e2732-8651-74e5-9f5d-4d06c3105f25-1778774086096","plan_id":"plan-unknown","phase":"plan","trace_file":"/home/aryaniyaps/ai-projects/ultimate-pi/.pi/harness/runs/019e2732-8651-74e5-9f5d-4d06c3105f25-1778774086096/trace.json"}
+{"timestamp":"2026-05-14T16:36:47.569Z","run_id":"019e2758-b332-771b-ad6f-54d0d8478768-1778776600591","plan_id":"plan-unknown","phase":"plan","trace_file":"/home/aryaniyaps/ai-projects/ultimate-pi/.pi/harness/runs/019e2758-b332-771b-ad6f-54d0d8478768-1778776600591/trace.json"}

package/.pi/harness/sentrux/architecture.manifest.json

@@ -34,9 +34,9 @@
 		},
 		{
 			"name": "tooling",
-			"paths": ["scripts/*", "test/*"],
+			"paths": [".pi/scripts/*", "test/*"],
 			"order": 4,
-			"description": "Deterministic scripts and tests"
+			"description": "Harness CLI scripts and tests"
 		}
 	],
 	"boundaries": [
@@ -61,7 +61,7 @@
 			"reason": "Contracts are data-only JSON schemas; extensions implement behavior"
 		},
 		{
-			"from": "scripts/*",
+			"from": ".pi/scripts/*",
 			"to": ".agents/skills/*",
 			"reason": "CLI scripts stay independent of skill markdown"
 		}

package/.pi/model-router.example.json

@@ -0,0 +1,27 @@
+{
+	"defaultProfile": "auto",
+	"debug": false,
+	"classifierModel": "opencode-go/qwen3.6-plus",
+	"phaseBias": 0.5,
+	"maxSessionBudget": 1.0,
+	"largeContextThreshold": 100000,
+	"rules": [
+		{
+			"matches": ["deploy", "production", "release"],
+			"tier": "high",
+			"reason": "Safety check for production tasks"
+		},
+		{ "matches": "changelog", "tier": "low" }
+	],
+	"profiles": {
+		"auto": {
+			"high": {
+				"model": "opencode-go/deepseek-v4-pro",
+				"thinking": "high",
+				"fallbacks": ["opencode-go/qwen3.6-plus"]
+			},
+			"medium": { "model": "opencode-go/qwen3.6-plus", "thinking": "medium" },
+			"low": { "model": "opencode-go/deepseek-v4-flash", "thinking": "low" }
+		}
+	}
+}

package/.pi/prompts/graphify.md

@@ -5,13 +5,9 @@ argument-hint: "[directory]"
 
 Read the `graphify` skill. Then run the setup workflow:
 
-1. Check if Graphify is installed (`pip show graphifyy`). If not, install it:
-   ```bash
-   pip install graphifyy && graphify install
-   ```
-2. Check if a graph already exists (`graphify-out/graph.json`). If yes, report
-   current graph stats (nodes, edges, communities, last built).
-3. If no graph exists, build one: `graphify ${ARGUMENTS:-.} --wiki`
+1. Check if Graphify is installed (`pip`/`pip3 show graphifyy`, `uv tool list`, or `command -v graphify`). If not, install (`uv tool install graphifyy` preferred) and `graphify install --platform pi`.
+2. Check if a valid graph exists (`graphify-out/graph.json` with ≥1 node and `GRAPH_REPORT.md`). If yes, report stats.
+3. If no valid graph, build: `GRAPHIFY_VIZ_NODE_LIMIT=200000 graphify update ${ARGUMENTS:-.}` (never `graphify . --wiki` — invalid CLI). For full semantic extraction when API keys exist: `graphify extract ${ARGUMENTS:-.}`.
 4. Read and summarize `graphify-out/GRAPH_REPORT.md` — show god nodes,
    surprising connections, and suggested questions.
 5. Tell user: "Graph built. Open `graphify-out/graph.html` for interactive
@@ -19,5 +15,5 @@ Read the `graphify` skill. Then run the setup workflow:
 
 If the graph already exists:
 - Report graph stats from `graph.json`
-- Offer to update: `graphify . --update`
+- Offer to update: `graphify update .`
 - Show recent god nodes from GRAPH_REPORT.md

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

@@ -32,70 +32,51 @@ Block if node < 18, npm < 9, or git missing. Report versions and continue.
 
 Read `.pi/auto-commit.json` for co-author + branch config. Read `.pi/settings.json` for extension packages list.
 
-## Step 0.5 — Graphify Setup
+## Step 0.5 — Graphify (skip if `--skip-graphify`)
 
-Check if Graphify is installed and set up:
+**Critical:** `graphify . --wiki` and `graphify . --update` are **invalid** CLI (error: `unknown command '.'`). Use only:
 
-```bash
-# Check Python 3.10+
-python3 --version | grep -q "3\.1[0-9]" && echo "✓ Python 3.10+" || echo "✗ Need Python 3.10+"
+| Goal | Command |
+|------|---------|
+| Initial / refresh code graph (required, no LLM) | `GRAPHIFY_VIZ_NODE_LIMIT=200000 graphify update .` |
+| Full semantic graph (optional, needs API key) | `graphify extract .` |
 
-# Check if Graphify is installed
-if pip show graphifyy &>/dev/null; then
-  echo "✓ Graphify installed"
-  GRAPHIFY_INSTALLED=true
-else
-  echo "! Graphify not installed"
-  GRAPHIFY_INSTALLED=false
-fi
+On first `/harness-setup` in any project (including external repos), you **must** produce a valid `graphify-out/` with non-empty `graph.json` and `GRAPH_REPORT.md`. Do not ask the user whether to build — run the bootstrap script and **block** if it fails.
 
-# Check if graph already exists
-test -f graphify-out/graph.json && GRAPH_EXISTS=true || GRAPH_EXISTS=false
-```
+Run from the **project root** (the external repo root, not ultimate-pi unless that is the target):
 
-**Present to user:**
+```bash
+mkdir -p ./raw .pi/harness/specs .pi/harness/runs .pi/harness/incidents .pi/harness/debates
 
-### Case A: Graphify installed + graph exists
-> "Graphify ready. Existing graph: `graphify-out/`. Run `graphify . --update` to refresh."
+# Bundled with ultimate-pi harness; copy path if bootstrap runs from a linked harness checkout
+bash "$(node -p "require('path').join(require('path').dirname(require.resolve('ultimate-pi/package.json')),'.pi/scripts/harness-graphify-bootstrap.sh')")"
+# In ultimate-pi checkout: npm run harness:graphify-bootstrap
 
-### Case B: Graphify installed + no graph
-> "Graphify installed but no graph built yet. Build one now?"
+# Pass --force when $ARGUMENTS contains --force to rebuild an existing graph:
+# npm run harness:graphify-bootstrap -- --force
+```
 
-### Case C: Graphify not installed
-> "Graphify not found. Install: `pip install graphifyy && graphify install`. Install now?"
+If the bootstrap script is missing, run it from the installed ultimate-pi package (`.pi/scripts/` inside the npm package), or execute equivalent steps manually:
 
-### Case D: Python too old
-> "Python 3.10+ required for Graphify. Current: `$(python3 --version)`. Install Python 3.10+ before continuing."
+1. Install `graphifyy` (`uv tool install` preferred; else `pip`/`pip3 install --user`)
+2. `graphify install --platform pi` (and `graphify cursor install` if `.cursor/` exists)
+3. `GRAPHIFY_VIZ_NODE_LIMIT=200000 graphify update .` — **required**; exits non-zero on failure
+4. If `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `MOONSHOT_API_KEY` is set: `graphify extract .` for full semantic graph (optional enrichment)
+5. `graphify hook install` only when `.git/` exists
+6. Validate: `graphify-out/graph.json` has ≥1 node and `graphify-out/GRAPH_REPORT.md` exists
 
-## Step 1 — Build Knowledge Graph
+**Do not continue** to Step 2+ until validation passes. Report node/edge counts from the script output.
 
-```bash
-# Install if needed
-if [ "$GRAPHIFY_INSTALLED" != "true" ]; then
-  pip install graphifyy && graphify install
-fi
+Read and summarize `graphify-out/GRAPH_REPORT.md` — god nodes and surprising connections.
 
-# Build the graph (or update existing)
-if [ "$GRAPH_EXISTS" = "true" ]; then
-  graphify . --update --wiki
-else
-  graphify . --wiki
-fi
-
-# Install git hooks — auto-update graph on commit/checkout
-graphify hook install
+### Failure modes (report clearly)
 
-# Quick stats
-echo "Graph built. Output: graphify-out/"
-ls graphify-out/
-```
-
-Read and summarize `graphify-out/GRAPH_REPORT.md` — show god nodes and surprising connections.
-
-Create project directories needed for graphify + harness workflow:
-```bash
-mkdir -p ./raw .pi/harness/specs .pi/harness/runs .pi/harness/incidents .pi/harness/debates
-```
+| Symptom | Likely cause |
+|---------|----------------|
+| `unknown command '.'` | Wrong CLI — use `graphify update .`, never `graphify .` |
+| Empty or missing `graphify-out/` | Build step skipped or failed; re-run bootstrap |
+| `graph.json` exists but 0 nodes | Stale/partial output — re-run with `--force` |
+| `graphify extract` fails | No API key — code graph from `update` is still valid; note in report |
 
 ## Step 1.5 — Optional Self-Hosted Firecrawl
 
@@ -225,9 +206,36 @@ 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
+## Step 2 — Install & Verify Global CLI Tools (skip if `--skip-tools`)
+
+Run the bundled verifier from the **project root**. It installs missing npm globals, fixes common **Linux system dependencies** (Chrome libs for `agent-browser`), runs smoke tests, and exits non-zero if a required tool fails.
 
-Check each package first. Install only if missing unless `--force` flag.
+```bash
+npm run harness:cli-verify
+# ultimate-pi checkout: npm run harness:cli-verify
+# Reinstall everything: npm run harness:cli-verify -- --force
+```
+
+**Required (script must exit 0):** firecrawl-cli, ctx7, biome, ast-grep (`sg`), sentrux (when harness manifest present).
+
+**Warnings allowed:** gh (if not authenticated), agent-browser (if OS libs need manual `sudo apt-get install`), ck (empty corpus on tiny repos).
+
+If the script reports **agent-browser shared library errors** on Linux/WSL, run the fix it prints, then re-verify:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y libnss3 libnspr4 libgbm1 libatk1.0-0 libatk-bridge2.0-0 \
+  libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
+  libasound2 libpango-1.0-0 libcairo2 libx11-6 libxcb1 libxext6 fonts-liberation
+agent-browser install --with-deps
+npm run harness:cli-verify
+```
+
+**Do not continue** past Step 2 if `harness-cli-verify.sh` exits non-zero.
+
+### Manual reference (if script missing in target repo)
+
+Use `npm run harness:cli-verify` from the installed ultimate-pi package, or install tools individually:
 
 ### 2.1 — firecrawl-cli (Web Search + Scrape + Crawl + Interact + Download + Parse)
 
@@ -260,9 +268,8 @@ firecrawl login --browser
 firecrawl login --api-key "<key>"
 ```
 
-Install skills and run quick smoke test:
+Quick smoke test (skills ship with `ultimate-pi` via npm — do **not** run `firecrawl setup skills`):
 ```bash
-firecrawl setup skills
 mkdir -p .firecrawl
 firecrawl scrape "https://firecrawl.dev" -o .firecrawl/install-check.md
 ```
@@ -404,7 +411,11 @@ Configure MCP server in `.pi/mcp.json` (see Step 4.3).
 
 Generate architectural rules from the harness manifest (creates/updates `.sentrux/rules.toml`):
 ```bash
+# From ultimate-pi checkout:
+npm run harness:sentrux-sync
+# From an external project (after pi install npm:ultimate-pi):
 npm run harness:sentrux-sync
+# Or in pi: /harness-sentrux-sync
 ```
 
 Edit layers/boundaries in `.pi/harness/sentrux/architecture.manifest.json` when the repo layout changes, then re-run sync. Custom TOML below the `harness:managed` markers is preserved.
@@ -476,27 +487,38 @@ function model(prefix, name) { return `${prefix}/${name}`; }
 // Best available high-end model per provider
 const highModel = hasOpenCode
   ? model('opencode-go', 'deepseek-v4-pro')
-  : hasOpenAI
-    ? model('openai', 'gpt-5.4-pro')
-    : hasAnthropic
-      ? 'anthropic/claude-3-5-sonnet-20241022'
-      : 'google/gemini-2.5-flash-001';
+  : hasAnthropic
+    ? 'anthropic/claude-sonnet-4-20250514'
+    : hasGoogle
+      ? 'google/gemini-2.5-flash-001'
+      : hasOpenAI
+        ? model('openai', 'gpt-4o')
+        : null;
 
 const mediumModel = hasOpenCode
   ? model('opencode-go', 'qwen3.6-plus')
-  : hasOpenAI
-    ? model('openai', 'gpt-5.4-nano')
-    : hasAnthropic
-      ? 'anthropic/claude-3-5-sonnet-20241022'
-      : 'google/gemini-flash-latest';
+  : hasAnthropic
+    ? 'anthropic/claude-sonnet-4-20250514'
+    : hasGoogle
+      ? 'google/gemini-flash-latest'
+      : hasOpenAI
+        ? model('openai', 'gpt-4o-mini')
+        : null;
 
 const lowModel = hasOpenCode
   ? model('opencode-go', 'deepseek-v4-flash')
-  : hasOpenAI
-    ? model('openai', 'gpt-5.4-nano')
-    : hasAnthropic
-      ? 'anthropic/claude-3-haiku-20240307'
-      : 'google/gemini-flash-lite-latest';
+  : hasAnthropic
+    ? 'anthropic/claude-3-5-haiku-20241022'
+    : hasGoogle
+      ? 'google/gemini-flash-lite-latest'
+      : hasOpenAI
+        ? model('openai', 'gpt-4o-mini')
+        : null;
+
+if (!highModel || !mediumModel || !lowModel) {
+  console.log('✗ No AI provider env detected — skip model-router.json (set OPENAI_API_BASE for opencode, or ANTHROPIC/GOOGLE/OPENAI keys)');
+  process.exit(0);
+}
 
 const fallbacks = [];
 if (hasAnthropic && !highModel.startsWith('anthropic/')) fallbacks.push('anthropic/claude-3-5-sonnet-20241022');
@@ -552,7 +574,7 @@ fi
 
 Do NOT block. If generation fails, warn in report and continue.
 
-**Router activation happens automatically** — the agent should output the following as its next message (this activates the router in the current session):
+**Router is opt-in** — ultimate-pi no longer forces `defaultProvider: router` on install. After generating `model-router.json`, tell the user to enable routing when ready:
 
 > `/router profile auto`
 
@@ -616,16 +638,16 @@ Created: $(date +%Y-%m-%d)
 
 ## Structure
 
-- graphify-out/ → Knowledge graph (run `graphify .` to build)
+- graphify-out/ → Knowledge graph (run `graphify update .` to build)
 - ./raw/ → Source documents for graphify ingestion
 - .pi/harness/specs/ → Harness contracts and schema docs
 - .pi/harness/incidents/ → Incident and override records
-- .pi/skills/ → Agent skills
+- `.agents/skills/` (npm package) → Harness skills (no copy into `.pi/skills/` needed)
 - .pi/agents/ → Specialized agents
 
 ## Graphify-First Workflow
 
-1. Run `graphify . --wiki` to build the knowledge graph
+1. Run `graphify update .` to build/update the knowledge graph (AST, no API cost)
 2. Read `graphify-out/GRAPH_REPORT.md` for god nodes and surprising connections
 3. Query: `graphify query "question"`
 4. Harness contracts and governance records in `.pi/harness/specs/` and `.pi/harness/incidents/`
@@ -635,32 +657,52 @@ Created: $(date +%Y-%m-%d)
 - Graph before grep — always consult the knowledge graph first
 - ./raw/ is source storage for graphify
 - Decisions and incidents in `.pi/harness/` with structured artifacts
-- `graphify . --update` after significant changes
+- `GRAPHIFY_VIZ_NODE_LIMIT=200000 graphify update .` after significant code changes
 - ast-grep (`sg`) is the default code search tool — use `sg -p 'pattern'` for structural search, never grep for code
 - Create `.sg/rules/` for project-wide code quality rules
 ```
 
 ## Step 5 — Verification
 
-Run full verification suite:
+Re-run CLI verification (must pass unless `--skip-tools`):
 
 ```bash
-# CLI tools
-firecrawl --status 2>/dev/null && echo "✓ firecrawl" || echo "✗ firecrawl"
-ctx7 --help 2>/dev/null && echo "✓ ctx7" || echo "✗ ctx7"
-agent-browser --version 2>/dev/null && echo "✓ agent-browser" || echo "✗ agent-browser"
-ck --version 2>/dev/null && echo "✓ ck-search" || echo "✗ ck-search"
-biome --version 2>/dev/null && echo "✓ biome" || echo "✗ biome"
-sg --version 2>/dev/null && echo "✓ ast-grep" || echo "✗ ast-grep"
-gh --version 2>/dev/null && echo "✓ gh" || echo "✗ gh"
-sentrux --version 2>/dev/null && echo "✓ sentrux" || echo "✗ sentrux"
+npm run harness:cli-verify
+```
+
+Then run the remaining checks:
 
+```bash
 # pi extensions
 cd .pi/npm && npm ls 2>/dev/null && echo "✓ pi extensions" || echo "✗ pi extensions"
 
-# graphify knowledge graph
-pip show graphifyy 2>/dev/null && echo "✓ graphify installed" || echo "✗ graphify not installed"
-ls graphify-out/graph.json 2>/dev/null && echo "✓ knowledge graph built" || echo "✗ no graph built yet"
+# graphify knowledge graph (pip/pip3, uv, apt, or PATH)
+PIP_CMD=""
+command -v pip &>/dev/null && PIP_CMD=pip
+[ -z "$PIP_CMD" ] && command -v pip3 &>/dev/null && PIP_CMD=pip3
+
+if command -v graphify &>/dev/null; then
+  echo "✓ graphify ($(command -v graphify))"
+elif [ -n "$PIP_CMD" ] && $PIP_CMD show graphifyy &>/dev/null 2>&1; then
+  echo "✓ graphify ($PIP_CMD)"
+elif command -v uv &>/dev/null && uv pip show graphifyy &>/dev/null 2>&1; then
+  echo "✓ graphify (uv pip)"
+elif command -v uv &>/dev/null && uv tool list 2>/dev/null | grep -qE '(^|[[:space:]])graphifyy([[:space:]]|$)'; then
+  echo "✓ graphify (uv tool)"
+elif dpkg -l 2>/dev/null | grep -qE '^ii[[:space:]]+(python3-)?graphify' || apt list --installed 2>/dev/null | grep -qi graphify; then
+  echo "✓ graphify (apt)"
+else
+  echo "✗ graphify not installed"
+fi
+python3 -c "
+import json, sys
+from pathlib import Path
+gj, gr = Path('graphify-out/graph.json'), Path('graphify-out/GRAPH_REPORT.md')
+if not gj.is_file() or not gr.is_file():
+    print('✗ knowledge graph missing (need graph.json + GRAPH_REPORT.md)'); sys.exit(0)
+n = len(json.loads(gj.read_text()).get('nodes') or [])
+print(f'✓ knowledge graph built ({n} nodes)' if n else '✗ graph.json has 0 nodes — re-run harness-graphify-bootstrap.sh --force')
+" 2>/dev/null || echo "✗ no graph built yet"
 graphify hook status 2>/dev/null && echo "✓ graphify git hooks installed" || echo "✗ graphify git hooks not installed"
 
 # model router
@@ -721,7 +763,7 @@ Output summary table:
 
 Next steps:
 1. If tools missing: re-run with `--force` or install individually
-2. If graph not built: run `graphify . --wiki`
+2. If graph not built: run `npm run harness:graphify-bootstrap` (or `graphify update .` from project root)
 3. If hooks not installed: run `graphify hook install`
 4. If gh not authenticated: `gh auth login`
 5. If self-hosted Firecrawl unhealthy: `docker compose -f firecrawl/docker-compose.yaml logs`
@@ -731,7 +773,10 @@ Next steps:
 ## Guard Rails
 
 - **Internet required**: Several tools need npm registry access. Block if offline.
+- **CLI verify script**: Step 2 and Step 5 use `npm run harness:cli-verify` (`.pi/scripts/harness-cli-verify.sh`) — installs npm globals, Linux Chrome system libs for `agent-browser`, and smoke-tests each tool. Block on non-zero exit.
 - **Graphify requires Python 3.10+**: Check `python3 --version`. Block if too old.
+- **Graphify bootstrap is mandatory** (unless `--skip-graphify`): Run `npm run harness:graphify-bootstrap`. Never use `graphify . --wiki`. Initial setup must run `graphify update .` and verify `graphify-out/graph.json` has nodes.
+- **Python packages (Graphify)**: Before install, detect via PATH, `pip`/`pip3 show graphifyy`, `uv`, or apt. Prefer `uv tool install graphifyy`.
 - **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).
@@ -748,12 +793,17 @@ Next steps:
 | Node < 18 | Block. Report required version. |
 | npm not found | Block. Suggest install method per OS. |
 | Python < 3.10 | Block. Report required Python version for Graphify. |
-| Graphify install fails | Show pip error output. Suggest `pip install --upgrade pip` and retry. |
+| CLI verify script fails | Read per-tool ✗ lines. Re-run with `--force`. Fix agent-browser libs via apt (see Step 2). |
+| agent-browser libnspr4 / shared library | `sudo apt-get install -y libnss3 libnspr4 libgbm1 ...` then `agent-browser install --with-deps`. |
+| Graphify install fails | Show installer output. Retry `uv tool install graphifyy` or `pip3 install --user graphifyy`. Ensure `~/.local/bin` is on PATH. |
+| `graphify update .` fails | Block setup. Corpus may have no code files, or graphify not on PATH. Show stderr. |
+| Invalid `graphify .` usage | Replace with `graphify update .` — the `.` subcommand does not exist. |
+| graphify-out empty / 0 nodes | Re-run `npm run harness:graphify-bootstrap -- --force` from project root. |
 | graphify hook install fails | Hooks need `.git/` directory. Verify inside git repo. Manual: `git config core.hooksPath .pi/git-hooks` |
 | firecrawl auth failed | Show manual login instructions. Continue with other tools. |
 | gh not installed | Show GitHub CLI install link. Skip label creation. |
 | pi packages install fail | Show error output. Check npm permissions. |
-| graph already exists | Report state. Offer `graphify . --update` to refresh. |
+| graph already exists | Report node count. Refresh with `graphify update .` unless user passed `--force`. |
 | biome.json missing | Create minimal config. |
 | settings.json not writable | Warn. Settings won't persist across sessions. |
 | No internet | Block for tool installs. Continue for graphify-only steps if `--skip-tools`. |
@@ -767,7 +817,7 @@ Next steps:
 
 | Flag | Effect |
 |------|--------|
-| `--skip-graphify` | Skip Step 1 (graph build). Use when graph already exists. |
+| `--skip-graphify` | Skip Step 0.5 (graph build). Only when a valid `graphify-out/graph.json` 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. |