ultimate-pi 0.2.3 → 0.2.4

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

@@ -32,70 +32,52 @@ 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 scripts/harness-graphify-bootstrap.sh
+# In ultimate-pi checkout: npm run harness:graphify-bootstrap
+# Or, if scripts/ is not present in the target repo, copy/run ultimate-pi/scripts/harness-graphify-bootstrap.sh
 
-### 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:
+# bash scripts/harness-graphify-bootstrap.sh --force
+```
 
-### Case C: Graphify not installed
-> "Graphify not found. Install: `pip install graphifyy && graphify install`. Install now?"
+If `scripts/harness-graphify-bootstrap.sh` is missing in the target repo, run it from the ultimate-pi harness package path, 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 +207,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`)
 
-Check each package first. Install only if missing unless `--force` flag.
+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.
+
+```bash
+bash scripts/harness-cli-verify.sh
+# ultimate-pi checkout: npm run harness:cli-verify
+# Reinstall everything: bash scripts/harness-cli-verify.sh --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
+bash scripts/harness-cli-verify.sh
+```
+
+**Do not continue** past Step 2 if `harness-cli-verify.sh` exits non-zero.
+
+### Manual reference (if script missing in target repo)
+
+Copy `scripts/harness-cli-verify.sh` from ultimate-pi, or install tools individually:
 
 ### 2.1 — firecrawl-cli (Web Search + Scrape + Crawl + Interact + Download + Parse)
 
@@ -260,9 +269,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 +412,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):
+node "$(node -p "require('path').join(require('path').dirname(require.resolve('ultimate-pi/package.json')),'scripts/sentrux-rules-sync.mjs')")" --force
+# 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 +488,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 +575,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 +639,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 +658,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"
+bash scripts/harness-cli-verify.sh
+```
+
+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 +764,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 `bash scripts/harness-graphify-bootstrap.sh` (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 +774,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 `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 `scripts/harness-graphify-bootstrap.sh`. 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 +794,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 `bash scripts/harness-graphify-bootstrap.sh --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 +818,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. |

package/.pi/settings.json

@@ -1,6 +1,4 @@
 {
-	"defaultProvider": "router",
-	"defaultModel": "auto",
 	"retry": {
 		"enabled": true,
 		"maxRetries": 3

package/.sentrux/.harness-rules-meta.json

@@ -1,5 +1,5 @@
 {
   "manifest_hash": "f386fef6c6281e47",
-  "synced_at": "2026-05-15T10:48:36.716Z",
+  "synced_at": "2026-05-15T11:30:59.026Z",
   "manifest_path": ".pi/harness/sentrux/architecture.manifest.json"
 }

package/AGENTS.md

@@ -31,3 +31,15 @@ Created: 2026-05-14
 - `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
 - Self-hosted Firecrawl at http://localhost:3002 (FIRECRAWL_API_URL)
+
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+When the user types `/graphify`, invoke the `skill` tool with `skill: "graphify"` before doing anything else.
+
+Rules:
+- ALWAYS read graphify-out/GRAPH_REPORT.md before reading any source files, running grep/glob searches, or answering codebase questions. The graph is your primary map of the codebase.
+- IF graphify-out/wiki/index.md EXISTS, navigate it instead of reading raw files
+- For cross-module "how does X relate to Y" questions, prefer `graphify query "<question>"`, `graphify path "<A>" "<B>"`, or `graphify explain "<concept>"` over grep — these traverse the graph's EXTRACTED + INFERRED edges instead of scanning files
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented in this file.
 
+## [v0.2.4] — 2026-05-15
+
+### 🐛 Fixes
+
+- Stop forcing `router/auto` on install (avoids defaulting to `gpt-5.4-pro` when no `.pi/model-router.json`)
+- Bootstrap `model-router.json` from detected providers when missing
+- Load banner and sentrux sync script from the npm package root, not the host project's cwd
+- Remove redundant `firecrawl setup skills` from harness-setup (skills ship with the package)
+
+### 📖 Documentation
+
+- Add `.pi/model-router.example.json` and README note on opt-in model routing
+
 ## [v0.2.3] — 2026-05-15
 
 ### ✨ Features