fix(codegraph): non-interactive install, PATH/MCP recovery guidance, gitignore .codegraph/

[heman4t]

What & why

Three fixes grounded in a real first-run setup of this kit (Claude Code, global install). After following codegraph-policy.md verbatim, the codegraph_* MCP tools silently failed to load, and one step hung the agent. Each change addresses one of those.

1. codegraph install hangs the agent → recommend codegraph install -y

The decision tree and install table tell the agent to run codegraph install. That command (CodeGraph v0.9.9) opens an interactive "Which agents should CodeGraph configure?" multi-select, which has no TTY in an agent context and blocks session startup (I had to pkill it). -y runs non-interactively (global + auto-detect). Updated in codegraph-policy.md and the message codegraph-session-check.sh emits.

2. MCP server silently never loads (PATH mismatch) → add a verify-after-restart step

The CodeGraph CLI installer links the binary into ~/.local/bin (and warns it isn't on PATH). codegraph install then registers the server as the bare command "codegraph". GUI-launched agents (VS Code / desktop) don't inherit the shell PATH, so the server fails to spawn — no error, no tools, looks like setup just didn't work.

Added a "VERIFY the tools actually loaded" step to the restart reality section + the hook message: if missing, find the real binary, then either add ~/.local/bin to PATH or rewrite the MCP entry's command to the absolute path (the more robust fix, since it doesn't depend on the agent's PATH).

3. Project installs don't gitignore .codegraph/

install.sh already gitignores .primer/ on project installs, but the policy has the agent run codegraph init -i, which writes a per-machine .codegraph/ index at the repo root. CodeGraph drops its own .codegraph/.gitignore that self-ignores the heavy/volatile files (*.db, *.log, cache/) — but not daemon.sock (a unix socket!), daemon.pid, or that internal .gitignore itself, so on a team-shared project install those still get committed. Ignoring the whole .codegraph/ at the repo root is the clean fix. Added codegraph_gitignore() (mirrors primer_gitignore), called on project scope, + a smoke assertion.

Testing

• Regenerated agent-primer.sh via make-portable.sh (the bundle-drift smoke check stays green).
• tests/smoke.sh: 62 passed, 0 failed (incl. the new .codegraph/ gitignore check; primer wiring tests skipped — no Node 22.13/build, as expected).

Notes

• Docs/installer only — no change to the merge/atomic-write/idempotency machinery.
• -y is CodeGraph v0.9.9's flag for non-interactive global+auto install.
• A small Tier-3 follow-up is stacked on this in fix(codegraph): index-db check + safe Gemini fileName cleanup (Tier-3, stacked on #1) #2 (index-db check + safe Gemini fileName cleanup).

🤖 Generated with Claude Code