ultimate-pi 0.2.3 → 0.2.5

package/.pi/prompts/release.md

@@ -0,0 +1,225 @@
+---
+description: Release a new version — bump version, generate changelog, tag, and push to trigger GitHub Actions CI/CD publish.
+argument-hint: "[patch|minor|major] [--dry-run]"
+---
+
+# release — Version Bump + Changelog + Tag + Push
+
+Releases a new version by bumping `package.json`, generating a `CHANGELOG.md` entry from commits since the last tag, committing, tagging, and pushing the tag. The push triggers `.github/workflows/publish-github-packages.yml` and `.github/workflows/publish-npm.yml`.
+
+## Step 0 — Parse arguments
+
+Read `$ARGUMENTS`. First positional arg is the bump type:
+
+| Arg | Semver | When |
+|-----|--------|------|
+| `patch` | 0.1.X → 0.1.(X+1) | Bug fixes, small changes, chores |
+| `minor` | 0.X.0 → 0.(X+1).0 | New features, dep additions |
+| `major` | X.0.0 → (X+1).0.0 | Breaking changes |
+
+If no bump type given: scan commits since last tag for conventional commit prefixes to infer:
+
+```bash
+git log $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD --format="%s" 2>/dev/null
+```
+
+Inference rules:
+- Any `feat!:` or `BREAKING CHANGE` → **major**
+- Any `feat:` → **minor**
+- Everything else (`fix:`, `chore:`, `docs:`, `refactor:`, etc.) → **patch**
+
+If no commits since last tag, warn: "No commits since last tag. Nothing to release." and stop.
+
+Present the inferred bump type to user. If they passed one explicitly, use that. If `--dry-run`, show what would happen without making changes.
+
+## Step 1 — Read current version
+
+```bash
+node -e "console.log(require('./package.json').version)"
+```
+
+Store as `$CURRENT_VERSION`.
+
+Compute `$NEW_VERSION`:
+
+```bash
+# Pseudo-code — use node for precision
+NEW_VERSION=$(node -e "
+const [maj,min,pat] = '$CURRENT_VERSION'.split('.').map(Number);
+const bump = '$BUMP_TYPE';
+if (bump === 'major') console.log((maj+1)+'.0.0');
+else if (bump === 'minor') console.log(maj+'.'+(min+1)+'.0');
+else console.log(maj+'.'+min+'.'+(pat+1));
+")
+```
+
+## Step 2 — Pre-flight checks
+
+```bash
+# Must be in a git repo
+git rev-parse --is-inside-work-tree || { echo "Not a git repo. Abort."; exit 1; }
+
+# Must have a remote
+git remote -v | grep -q origin || { echo "No origin remote. Abort."; exit 1; }
+
+# Must be on a clean working tree
+git diff --quiet && git diff --cached --quiet || { echo "Working tree is dirty. Commit or stash changes first."; exit 1; }
+
+# Must be on a branch that can push (not detached HEAD)
+git symbolic-ref -q HEAD || { echo "Detached HEAD. Switch to a branch first."; exit 1; }
+```
+
+## Step 3 — Generate changelog
+
+Gather commits since last tag:
+
+```bash
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+if [ -z "$LAST_TAG" ]; then
+  COMMITS=$(git log --oneline --no-merges HEAD)
+else
+  COMMITS=$(git log --oneline --no-merges ${LAST_TAG}..HEAD)
+fi
+```
+
+Parse conventional commit prefixes to group:
+
+| Prefix | Changelog Section |
+|--------|-------------------|
+| `feat!:` | ⚠️ Breaking Changes |
+| `feat:` | ✨ Features |
+| `fix:` | 🐛 Fixes |
+| `perf:` | ⚡ Performance |
+| `refactor:` | ♻️ Refactoring |
+| `docs:` | 📖 Documentation |
+| `style:` | 🎨 Style |
+| `test:` | ✅ Tests |
+| `chore:` | 🔧 Chores |
+| `ci:` | 🔄 CI/CD |
+| `build:` | 📦 Build |
+| everything else | 🔧 Chores |
+
+Generate the changelog entry:
+
+```markdown
+## [v$NEW_VERSION] — $(date +%Y-%m-%d)
+
+### $SECTION_NAME
+
+- $commit_message (no prefix, just the description)
+
+...
+```
+
+If `CHANGELOG.md` exists, prepend the new entry after the `# Changelog` heading. If not, create it:
+
+```markdown
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [v$NEW_VERSION] — $(date +%Y-%m-%d)
+
+### $SECTION
+
+- $entry
+
+...
+```
+
+## Step 4 — Bump version in package.json
+
+```bash
+npm pkg set version="$NEW_VERSION"
+```
+
+Verify:
+```bash
+node -e "const v = require('./package.json').version; console.log(v === '$NEW_VERSION' ? '✓ version bumped to $NEW_VERSION' : '✗ version mismatch')"
+```
+
+## Step 5 — Dry run check
+
+If `--dry-run` flag: print summary and stop. Do NOT commit, tag, or push.
+
+```
+DRY RUN — no changes made.
+  Version: $CURRENT_VERSION → $NEW_VERSION
+  Bump: $BUMP_TYPE
+  Commits since $LAST_TAG: $COMMIT_COUNT
+  Files that would change:
+    - package.json (version)
+    - CHANGELOG.md (new entry)
+  Tag that would be created: v$NEW_VERSION
+```
+
+## Step 6 — Commit version bump + changelog
+
+```bash
+git add package.json CHANGELOG.md
+
+git commit -m "chore(release): bump to v$NEW_VERSION" -m "- Bump version in package.json
+- Add changelog entry for v$NEW_VERSION
+
+Commits included:
+$(echo "$COMMITS" | sed 's/^/- /')" -m "Co-authored-by: pi-mono <261679550+pi-mono@users.noreply.github.com>"
+```
+
+Use the co-author from `.pi/auto-commit.json` if available, otherwise use the default pi-mono co-author.
+
+## Step 7 — Create and push tag
+
+```bash
+git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION — $BUMP_TYPE bump
+
+$(echo "$COMMITS" | sed 's/^/- /')"
+
+git push origin "v$NEW_VERSION"
+```
+
+**Important**: Push only the tag, not the branch. The workflows trigger on `v*` tag push.
+- `publish-github-packages.yml` → publishes `@aryaniyaps/ultimate-pi` to GitHub Packages
+- `publish-npm.yml` → publishes `ultimate-pi` to npm registry
+
+Optionally also push the commit if user wants the branch updated:
+```bash
+git push origin $(git branch --show-current)
+```
+
+Ask user: "Push the version-bump commit to the current branch too? [Y/n]"
+
+## Step 8 — Report
+
+```
+✓ Released v$NEW_VERSION ($BUMP_TYPE)
+  Tag: v$NEW_VERSION — pushed to origin
+  Workflows triggered:
+    - .github/workflows/publish-github-packages.yml
+    - .github/workflows/publish-npm.yml
+  Commit: $(git rev-parse --short HEAD)
+  Changelog: CHANGELOG.md updated
+  Monitor: https://github.com/aryaniyaps/ultimate-pi/actions
+```
+
+## Guard Rails
+
+- **Clean tree required**: Block if uncommitted changes exist.
+- **No duplicate tags**: Block if `v$NEW_VERSION` tag already exists locally or on remote.
+- **No empty releases**: Block if no commits since last tag.
+- **Valid semver only**: Block if current version doesn't parse as `X.Y.Z`.
+- **Dry run safe**: `--dry-run` prints planned changes without modifying anything.
+- **Manual workflow dispatch**: If workflows support `workflow_dispatch`, user can re-trigger manually from GitHub Actions UI if push fails.
+- **Co-author idempotent**: Falls back to default pi-mono if `.pi/auto-commit.json` is missing.
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No commits since last tag | Report, suggest making changes first. Stop. |
+| Dirty working tree | Report dirty files. Suggest `git stash` or commit. Stop. |
+| Tag already exists | Report conflict. User must delete old tag or bump differently. Stop. |
+| No origin remote | Report. Suggest `git remote add origin <url>`. Stop. |
+| Detached HEAD | Report. Suggest `git checkout main`. Stop. |
+| Invalid semver | Report current version string. Stop. |
+| npm pkg set fails | Check Node.js and npm version. Report error. Stop. |
+| git push fails | Check auth. Report error. Suggest manual push. |

package/.pi/scripts/README.md

@@ -0,0 +1,17 @@
+# Harness CLI scripts
+
+These scripts ship inside the `ultimate-pi` npm package under `.pi/scripts/`.
+
+Pi's package manifest (`package.json` → `pi`) only loads **extensions**, **skills**, **prompts**, and **themes** — there is no `scripts` field. Harness scripts are invoked via:
+
+- `npm run harness:*` (see root `package.json`)
+- Extensions resolving paths with `resolveHarnessScript()` in `.pi/extensions/lib/harness-paths.ts`
+
+| Script | npm script |
+|--------|------------|
+| `harness-graphify-bootstrap.sh` | `harness:graphify-bootstrap` |
+| `harness-cli-verify.sh` | `harness:cli-verify` |
+| `harness-verify.mjs` | `harness:verify` |
+| `sentrux-rules-sync.mjs` | `harness:sentrux-sync` |
+
+Repo-root `scripts/` (e.g. `regen_graphify_html.py`) is dev-only and excluded from the npm tarball via `.npmignore`.

package/.pi/scripts/harness-cli-verify.sh

@@ -0,0 +1,294 @@
+#!/usr/bin/env bash
+# harness-cli-verify — install and smoke-test harness global CLI tools; fix common Linux deps.
+# Used by /harness-setup Step 2. Exit 0 only if all required tools pass verification.
+
+set -u
+set -o pipefail
+
+FORCE=false
+for arg in "$@"; do
+	case "$arg" in
+	--force) FORCE=true ;;
+	-h | --help)
+		echo "Usage: $0 [--force]"
+		echo "  Installs missing npm globals, fixes Linux browser libs, runs smoke tests."
+		exit 0
+		;;
+	*)
+		echo "Unknown argument: $arg" >&2
+		exit 2
+		;;
+	esac
+done
+
+export PATH="${HOME}/.local/bin:${PATH}:$(npm prefix -g 2>/dev/null)/bin"
+
+ROOT="$(pwd)"
+FAILURES=0
+WARNINGS=0
+
+log() { printf '%s\n' "$*"; }
+pass() { log "  ✓ $1"; }
+warn() { log "  ! $1"; WARNINGS=$((WARNINGS + 1)); }
+fail() { log "  ✗ $1"; FAILURES=$((FAILURES + 1)); }
+
+have_cmd() { command -v "$1" &>/dev/null; }
+
+npm_global_install() {
+	local pkg="$1"
+	if [ "$FORCE" = true ] || ! have_cmd "$2"; then
+		log "  installing $pkg..."
+		npm install -g "$pkg" || return 1
+	fi
+	return 0
+}
+
+apt_get_cmd() {
+	command -v apt-get 2>/dev/null || command -v apt 2>/dev/null || true
+}
+
+linux_apt_install() {
+	# Install apt packages when available (WSL/Debian/Ubuntu). Best-effort if sudo works.
+	local pkgs=("$@")
+	[ ${#pkgs[@]} -eq 0 ] && return 0
+	local apt_cmd
+	apt_cmd="$(apt_get_cmd)"
+	if [ -z "$apt_cmd" ]; then
+		return 2
+	fi
+	local missing=()
+	for p in "${pkgs[@]}"; do
+		dpkg -s "$p" &>/dev/null 2>&1 || missing+=("$p")
+	done
+	[ ${#missing[@]} -eq 0 ] && return 0
+	log "  installing apt packages: ${missing[*]}"
+	if sudo -n true 2>/dev/null; then
+		sudo DEBIAN_FRONTEND=noninteractive "$apt_cmd" update -qq
+		sudo DEBIAN_FRONTEND=noninteractive "$apt_cmd" install -y "${missing[@]}" || {
+			warn "apt install failed — run: sudo apt-get install -y ${missing[*]}"
+			return 1
+		}
+	else
+		return 2
+	fi
+	return 0
+}
+
+linux_pkg_install() {
+	# Debian/Ubuntu, RHEL/Fedora, or Arch — best-effort system deps for headless Chrome.
+	local pkgs_deb=(
+		libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2
+		libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1
+		libasound2 libpango-1.0-0 libcairo2 libx11-6 libxcb1 libxext6 fonts-liberation
+	)
+	if [ -n "$(apt_get_cmd)" ]; then
+		linux_apt_install "${pkgs_deb[@]}"
+		return $?
+	fi
+	if command -v dnf &>/dev/null && sudo -n true 2>/dev/null; then
+		sudo dnf install -y nss nspr atk at-spi2-atk cups-libs libdrm libxkbcommon \
+			libXcomposite libXdamage libXfixes libXrandr mesa-libgbm alsa-lib \
+			pango cairo libX11 libxcb libXext liberation-fonts 2>/dev/null && return 0
+		return 2
+	fi
+	if command -v pacman &>/dev/null && sudo -n true 2>/dev/null; then
+		sudo pacman -S --noconfirm nss nspr atk at-spi2-atk cups libdrm libxkbcommon \
+			libxcomposite libxdamage libxfixes libxrandr mesa gbm alsa-lib \
+			pango cairo libx11 libxcb libxext ttf-liberation 2>/dev/null && return 0
+		return 2
+	fi
+	return 2
+}
+
+# Playwright / agent-browser Chrome on Linux (libnspr4.so, etc.)
+ensure_linux_browser_deps() {
+	[ "$(uname -s)" != "Linux" ] && return 0
+	local rc=0
+	linux_pkg_install || rc=$?
+	if [ "$rc" -eq 2 ]; then
+		return 2
+	fi
+	return 0
+}
+
+verify_agent_browser() {
+	log "[agent-browser]"
+	npm_global_install "agent-browser" "agent-browser" || { fail "agent-browser npm install"; return; }
+
+	local deps_rc=0
+	ensure_linux_browser_deps || deps_rc=$?
+	if ! agent-browser install 2>/dev/null; then
+		warn "agent-browser install (Chrome binary) failed — may still work with system Chrome"
+	fi
+
+	local out
+	out="$(agent-browser open "about:blank" 2>&1)" || true
+	if echo "$out" | grep -qiE 'shared libraries|libnspr4|cannot open shared object'; then
+		warn "Chrome missing system libs — installing OS packages"
+		if [ "$deps_rc" -eq 2 ] || ! ensure_linux_browser_deps; then
+			warn "Could not auto-install OS packages (need sudo). Debian/Ubuntu: sudo apt-get install -y libnss3 libnspr4 libgbm1 libatk1.0-0 libx11-6"
+		fi
+		if sudo -n true 2>/dev/null; then
+			agent-browser install --with-deps 2>/dev/null || true
+		else
+			warn "Run manually: agent-browser install --with-deps"
+		fi
+		out="$(agent-browser open "about:blank" 2>&1)" || true
+	fi
+
+	if echo "$out" | grep -qiE 'shared libraries|libnspr4|Auto-launch failed'; then
+		if [ "$deps_rc" -eq 2 ]; then
+			warn "agent-browser needs Linux system libs (manual): sudo apt-get install -y libnss3 libnspr4 libgbm1 && agent-browser install --with-deps"
+		else
+			fail "agent-browser runtime failed after dep install — see stderr above"
+		fi
+	else
+		pass "agent-browser $(agent-browser --version 2>/dev/null | head -1)"
+		agent-browser close 2>/dev/null || true
+	fi
+
+	mkdir -p .pi/harness
+	if [ ! -f .pi/harness/browser.json ]; then
+		echo '{"headless": true, "timeout": 30000, "viewport": {"width": 1280, "height": 720}}' >.pi/harness/browser.json
+	fi
+}
+
+verify_firecrawl() {
+	log "[firecrawl-cli]"
+	npm_global_install "firecrawl-cli@latest" "firecrawl" || { fail "firecrawl-cli npm install"; return; }
+	if firecrawl --status &>/dev/null; then
+		pass "firecrawl $(firecrawl --status 2>/dev/null | head -1 || echo ok)"
+	else
+		fail "firecrawl --status failed (run: firecrawl login)"
+	fi
+}
+
+verify_ctx7() {
+	log "[ctx7]"
+	npm_global_install "ctx7@latest" "ctx7" || { fail "ctx7 npm install"; return; }
+	if ctx7 --help &>/dev/null; then
+		pass "ctx7"
+	else
+		fail "ctx7 --help failed"
+	fi
+}
+
+verify_ck() {
+	log "[ck-search]"
+	npm_global_install "@beaconbay/ck-search" "ck" || { fail "ck-search npm install"; return; }
+	if ! ck --version &>/dev/null; then
+		fail "ck --version failed"
+		return
+	fi
+	# Fast grep-mode smoke (no embedding model download)
+	local ck_target="."
+	[ -d .pi ] && ck_target=".pi"
+	if ck -l 1 "export" "$ck_target" 2>/dev/null | head -1 | grep -q .; then
+		pass "ck $(ck --version 2>/dev/null | head -1)"
+	elif ck --status "$ck_target" 2>/dev/null | head -1 | grep -q .; then
+		pass "ck $(ck --version 2>/dev/null | head -1) (index status ok)"
+	else
+		warn "ck installed but smoke search empty"
+	fi
+}
+
+verify_biome() {
+	log "[biome]"
+	npm_global_install "@biomejs/biome" "biome" || { fail "biome npm install"; return; }
+	if biome --version &>/dev/null; then
+		pass "biome $(biome --version 2>/dev/null | head -1)"
+	else
+		fail "biome --version failed"
+	fi
+}
+
+verify_sg() {
+	log "[ast-grep]"
+	npm_global_install "@ast-grep/cli@latest" "sg" || { fail "ast-grep npm install"; return; }
+	if ! sg --version &>/dev/null; then
+		fail "sg --version failed"
+		return
+	fi
+	if sg -p 'export' -l ts .pi 2>/dev/null | head -1 | grep -q .; then
+		pass "ast-grep $(sg --version 2>/dev/null | head -1)"
+	else
+		# Still pass if binary works
+		pass "ast-grep $(sg --version 2>/dev/null | head -1) (pattern scan skipped)"
+	fi
+}
+
+verify_gh() {
+	log "[gh]"
+	if ! have_cmd gh; then
+		if [ -n "$(apt_get_cmd)" ] && sudo -n true 2>/dev/null; then
+			log "  installing gh via apt..."
+			sudo DEBIAN_FRONTEND=noninteractive "$(apt_get_cmd)" update -qq
+			sudo DEBIAN_FRONTEND=noninteractive "$(apt_get_cmd)" install -y gh 2>/dev/null || true
+		fi
+	fi
+	if have_cmd gh && gh --version &>/dev/null; then
+		pass "gh $(gh --version 2>/dev/null | head -1)"
+		if gh auth status &>/dev/null 2>&1; then
+			pass "gh authenticated"
+			if [ -d .git ]; then
+				gh label create "harness" --color "0366d6" --description "Agentic harness managed" 2>/dev/null || true
+				gh label create "harness-spec" --color "0e8a16" --description "Hardened specification" 2>/dev/null || true
+				gh label create "harness-plan" --color "fbca04" --description "Structured plan generated" 2>/dev/null || true
+				gh label create "harness-critic" --color "d73a4a" --description "Adversarial review" 2>/dev/null || true
+			fi
+		else
+			warn "gh not authenticated (run: gh auth login)"
+		fi
+	else
+		warn "gh not installed — https://cli.github.com/ (optional for issue specs)"
+	fi
+}
+
+verify_sentrux() {
+	log "[sentrux]"
+	if ! have_cmd sentrux || [ "$FORCE" = true ]; then
+		if curl -fsSL https://raw.githubusercontent.com/sentrux/sentrux/main/install.sh | sh; then
+			export PATH="${HOME}/.local/bin:${PATH}"
+		else
+			fail "sentrux install script failed"
+			return
+		fi
+	fi
+	if ! sentrux --version &>/dev/null; then
+		fail "sentrux --version failed"
+		return
+	fi
+	sentrux plugin add-standard 2>/dev/null || warn "sentrux plugin add-standard skipped"
+	if [ -f package.json ] && grep -q harness:sentrux-sync package.json 2>/dev/null; then
+		npm run harness:sentrux-sync 2>/dev/null || warn "npm run harness:sentrux-sync failed (needs package.json scripts)"
+	fi
+	if sentrux check . &>/dev/null; then
+		pass "sentrux $(sentrux --version 2>/dev/null | head -1)"
+	else
+		warn "sentrux check . failed (rules may need manifest sync)"
+	fi
+}
+
+log "Harness CLI verification (cwd: $ROOT)"
+log ""
+
+verify_firecrawl
+verify_ctx7
+verify_agent_browser
+verify_ck
+verify_biome
+verify_sg
+verify_gh
+verify_sentrux
+
+log ""
+if [ "$FAILURES" -gt 0 ]; then
+	log "FAILED: $FAILURES required tool(s). Fix errors above and re-run."
+	exit 1
+fi
+if [ "$WARNINGS" -gt 0 ]; then
+	log "OK with $WARNINGS warning(s) (optional tools or auth)."
+else
+	log "All harness CLI tools verified."
+fi
+exit 0

package/.pi/scripts/harness-graphify-bootstrap.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# harness-graphify-bootstrap — install graphify and build graphify-out for the current repo.
+# Used by /harness-setup. Do not use deprecated `graphify . --wiki` (invalid CLI).
+
+set -euo pipefail
+
+FORCE=false
+for arg in "$@"; do
+	case "$arg" in
+	--force) FORCE=true ;;
+	-h | --help)
+		echo "Usage: $0 [--force]"
+		echo "  --force   rebuild even when graphify-out/graph.json already exists"
+		exit 0
+		;;
+	*)
+		echo "Unknown argument: $arg" >&2
+		exit 2
+		;;
+	esac
+done
+
+export PATH="${HOME}/.local/bin:${PATH}"
+
+log() { printf '%s\n' "$*"; }
+die() { printf 'error: %s\n' "$*" >&2; exit 1; }
+
+# Python 3.10+
+if ! python3 --version 2>/dev/null | grep -qE 'Python 3\.(1[0-9]|[2-9][0-9])'; then
+	die "Python 3.10+ required (got: $(python3 --version 2>/dev/null || echo missing))"
+fi
+log "✓ Python 3.10+"
+
+PIP_CMD=""
+command -v pip &>/dev/null && PIP_CMD=pip
+[ -z "$PIP_CMD" ] && command -v pip3 &>/dev/null && PIP_CMD=pip3
+
+graphify_installed() {
+	command -v graphify &>/dev/null && return 0
+	[ -n "$PIP_CMD" ] && $PIP_CMD show graphifyy &>/dev/null 2>&1 && return 0
+	command -v uv &>/dev/null && uv pip show graphifyy &>/dev/null 2>&1 && return 0
+	command -v uv &>/dev/null && uv tool list 2>/dev/null | grep -qE '(^|[[:space:]])graphifyy([[:space:]]|$)' && return 0
+	dpkg -l 2>/dev/null | grep -qE '^ii[[:space:]]+(python3-)?graphify' && return 0
+	apt list --installed 2>/dev/null | grep -qiE '(^|/)python3?-?graphify' && return 0
+	return 1
+}
+
+install_graphify() {
+	if command -v uv &>/dev/null; then
+		uv tool install graphifyy
+	elif [ -n "$PIP_CMD" ]; then
+		$PIP_CMD install --user graphifyy
+	else
+		die "Need uv, pip, or pip3 to install graphifyy"
+	fi
+	export PATH="${HOME}/.local/bin:${PATH}"
+	command -v graphify &>/dev/null || die "graphify not on PATH after install (try: export PATH=\"\$HOME/.local/bin:\$PATH\")"
+}
+
+graphify_platform_install() {
+	graphify install --platform pi 2>/dev/null || graphify pi install 2>/dev/null || true
+	if [ -d .cursor ]; then
+		graphify cursor install 2>/dev/null || true
+	fi
+	if [ -f AGENTS.md ] || [ -d .pi ]; then
+		graphify codex install 2>/dev/null || true
+	fi
+}
+
+graph_is_valid() {
+	python3 - <<'PY'
+import json
+import sys
+from pathlib import Path
+
+root = Path("graphify-out")
+gj = root / "graph.json"
+gr = root / "GRAPH_REPORT.md"
+if not gj.is_file() or not gr.is_file():
+    sys.exit(1)
+data = json.loads(gj.read_text(encoding="utf-8"))
+nodes = data.get("nodes") or []
+if len(nodes) < 1:
+    sys.exit(1)
+edges = data.get("edges") or data.get("links") or []
+print(f"nodes={len(nodes)} edges={len(edges)}")
+PY
+}
+
+has_llm_key() {
+	[ -n "${GEMINI_API_KEY:-}" ] || [ -n "${GOOGLE_API_KEY:-}" ] || \
+		[ -n "${MOONSHOT_API_KEY:-}" ] || [ -n "${ANTHROPIC_API_KEY:-}" ] || \
+		[ -n "${OPENAI_API_KEY:-}" ]
+}
+
+mkdir -p graphify-out ./raw
+
+if ! graphify_installed; then
+	log "Installing graphifyy..."
+	install_graphify
+fi
+
+command -v graphify &>/dev/null || die "graphify CLI not found after install"
+log "✓ graphify ($(command -v graphify))"
+
+graphify_platform_install
+
+NEED_BUILD=true
+if [ "$FORCE" = false ] && graph_is_valid 2>/dev/null; then
+	NEED_BUILD=false
+	log "✓ Existing graphify-out/graph.json ($(graph_is_valid))"
+fi
+
+export GRAPHIFY_VIZ_NODE_LIMIT="${GRAPHIFY_VIZ_NODE_LIMIT:-200000}"
+
+if [ "$NEED_BUILD" = true ] || [ "$FORCE" = true ]; then
+	log "Building knowledge graph for codebase (graphify update .)..."
+	if ! graphify update .; then
+		die "graphify update . failed — graphify-out was not created"
+	fi
+	if ! graph_is_valid 2>/dev/null; then
+		die "graphify update . finished but graphify-out/graph.json is missing or empty"
+	fi
+	log "✓ Code graph built ($(graph_is_valid))"
+	if has_llm_key; then
+		log "LLM API key detected — running full semantic extract (graphify extract .)..."
+		if graphify extract .; then
+			if graph_is_valid 2>/dev/null; then
+				log "✓ Full graph built ($(graph_is_valid))"
+			else
+				log "! graphify extract finished but graph validation failed; code-only graph remains"
+			fi
+		else
+			log "! graphify extract failed; keeping code-only graph from graphify update ."
+		fi
+	else
+		log "No LLM API key — code-only graph (AST). Set GEMINI_API_KEY or OPENAI_API_KEY and re-run with --force for semantic extraction."
+	fi
+else
+	log "Refreshing code graph (graphify update .)..."
+	graphify update . || die "graphify update . failed"
+fi
+
+if [ -d .git ]; then
+	graphify hook install 2>/dev/null && log "✓ graphify git hooks installed" || log "! graphify hook install skipped or failed"
+else
+	log "! Not a git repo — skipped graphify hook install"
+fi
+
+log "Graph output: graphify-out/"
+ls -la graphify-out/ 2>/dev/null | head -20 || true