Agent-driven install runbooks (Claude Desktop + Codex)

[MrBenJ]

Summary

• Adds two agent-targeted install runbooks under agents/install/ — one for Claude Desktop, one for Codex CLI. Both walk a non-technical user through GCP project setup, OAuth client creation, uv tool install, account auth, and harness config wiring with patient one-step-at-a-time pacing.
• Sub-phase 1h's "locate the downloaded client_secret" step has an explicit zero/one/many decision tree so a user with prior GCP downloads in ~/Downloads doesn't get bitten by a blind glob, and uses find ... -print0 | xargs -0 ls -lt to stay clean under zsh's NOMATCH default.
• README gets a new "Quick install (let an agent do it)" section pointing at the runbooks; the existing manual instructions are preserved under a new "Manual install" H2 parent.

Test plan

• ruff check . — passes
• mypy — no issues in 14 source files
• pytest — 88 passed
• Phase 0 detection commands run cleanly in zsh (this machine) — no NOMATCH errors
• Phase 1h find ... -print0 | xargs -0 ls -lt returns cleanly with zero matches
• Phase 5 Claude Desktop jq merge preserves pre-existing mcpServers entries (verified against a scratch JSON)
• Phase 5 Codex TOML append preserves pre-existing sections (verified against a scratch TOML)
• README links resolve to both runbook files
• No fabricated GCP deep-link URLs — same URL set in both runbooks
• End-to-end smoke test in a fresh Claude Desktop install (manual — pending)
• End-to-end smoke test in a fresh Codex CLI session (manual — pending)

🤖 Generated with Claude Code

[aria-teknal-studio]

Findings:

1. [P1] Treat failed check lookup as a merge blocker — docs/superpowers/plans/2026-05-18-code-task.md:666

   The --merge path captures gh pr checks "$PR_URL" 2>&1 and only blocks when the output text contains fail or pending. If the checks lookup itself fails, is rate-limited, cannot reach GitHub, returns an auth error, or reports another non-green state such as cancelled/timed out/skipped, this grep can miss it and proceed to gh pr merge. In repositories without branch protection, that turns a CI verification failure into an auto-merge. Please check the gh pr checks exit status and/or consume structured JSON, and require every relevant check conclusion/status to be explicitly green before merging. Unknown/error/no-checks should fail closed.

2. [P2] Pytest detection example skips pytest for the common pyproject case — docs/superpowers/plans/2026-05-18-code-task.md:447

   The command [ -f pyproject.toml ] || [ -f pytest.ini ] && pytest is parsed as [ -f pyproject.toml ] || ( [ -f pytest.ini ] && pytest ), so repositories with a pyproject.toml do not run pytest at all. This conflicts with the detection table immediately above and can let the generated /code-task skill push or merge Python changes without running tests. Wrap the condition, for example ([ -f pyproject.toml ] || [ -f pytest.ini ]) && pytest.

Summary:
The install runbook additions look generally careful, and local verification of the current Python gate passed (uv run ruff check . && uv run mypy && uv run pytest). CI is green for the existing Python package, but it does not exercise the new runbook/automation shell snippets. The blocking risk is in the added automation docs that can become a user-level code-changing skill.

[MrBenJ]

Thanks Aria — addressed both findings:

P1 (gh pr checks failure modes) — fixed in 9f31896. You're right. The string-grep approach silently passed on auth errors, rate limits, and cancelled/skipped/action_required states. The plan doc was lagging the live /code-task skill on this — it now uses the exit code, which fails closed on anything other than a clean pass.

P2 (pytest detection precedence) — respectfully disagree, leaving as-is. The diagnosis cites the parsing as [ -f pyproject.toml ] || ([ -f pytest.ini ] && pytest), but bash || and && have equal precedence and are left-associative (per the bash manual), so A || B && C parses as (A || B) && C. Empirical test in a scratch dir with only pyproject.toml present:

$ touch pyproject.toml
$ [ -f pyproject.toml ] || [ -f pytest.ini ] && echo "would run pytest"
would run pytest

The snippet does the intended thing. If you have evidence to the contrary (a specific bash version where this parses differently, or a POSIX-strict shell), happy to take another look — but on standard bash 3+/4+/5+ this isn't a bug. Leaving Step 3.1's example unchanged.

[aria-teknal-studio]

Findings:

1. High - Account verification prints Google refresh tokens to stdout.
   Files: agents/install/claude-desktop.md:497 and agents/install/codex.md:496
   Both runbooks verify account setup with jq -e '.refresh_token' ~/.config/multi-google-mcp/accounts/<label>.json. Without >/dev/null, jq prints the actual refresh token into the terminal, agent transcript, debug logs, or any command-output capture. These tokens grant long-lived Gmail/Calendar/Drive access, so this turns a verification step into a credential disclosure. Use a non-printing predicate instead, for example:
   jq -e '(.refresh_token | type == "string" and length > 0)' ... >/dev/null.
   Also update any copied guidance in the design/spec docs if those are intended to be followed by agents.

2. Medium - Claude Desktop wiring uses a bare command that often fails from GUI-launched apps on macOS.
   File: agents/install/claude-desktop.md:540 and agents/install/claude-desktop.md:558
   The runbook installs via uv tool install ., then writes {"command": "multi-google-mcp"} to Claude Desktop config. When Claude Desktop is launched from Finder/Dock, it commonly does not inherit the interactive shell PATH where uv places tool shims (often ~/.local/bin). The runbook can pass its own command -v multi-google-mcp detection in the terminal but still produce a Claude config that cannot start the server after restart. Capture the absolute path from command -v multi-google-mcp after install and write that path into the Claude config, or include an explicit env.PATH entry and verify it matches the actual uv tool location. The Codex runbook is less exposed because Codex is normally launched from a shell, but Claude Desktop needs the stronger path handling.

Verification:

• uv run ruff check . passed.
• uv run mypy passed.
• uv run pytest passed: 88 tests.
• GitHub PR check "pytest + ruff + mypy" is passing.

Summary:
The docs/runbooks are thorough and CI is green, but these two install-flow issues are user-facing and security/compatibility relevant. I would not merge until the token-printing verification commands are fixed and Claude Desktop uses a launch-safe server path.

[MrBenJ]

Round 2 addressed in 69c3862:

• P1 (refresh-token leak) — fixed in both runbooks. Verification now uses jq -e '.refresh_token != null' … >/dev/null (boolean predicate, stdout suppressed) and an explicit NEVER rule forbidding the unredirected form.
• P2 (bare-name command in config) — fixed in both runbooks. Phase 5 now resolves MGM_BIN="$(command -v multi-google-mcp)" at write time and stores the absolute path. Detection also verifies [ -x "$STORED_CMD" ] so a stale bare-name entry from a prior install is detected and overwritten on rerun. The Codex TOML write gained an awk-based in-place replace branch (which preserves blank lines between sections — verified on a scratch file).

[aria-teknal-studio]

Findings:

1. High - The copied install-plan guidance still prints OAuth refresh tokens.
   File: docs/superpowers/plans/2026-05-19-agent-install-runbook.md:656
   The primary runbooks were fixed, but this PR still adds a plan document that tells agents to verify account setup with jq -e '.refresh_token' ~/.config/multi-google-mcp/accounts/<label>.json. If an agent follows or copies this plan, jq prints the live Google refresh token into terminal output/transcripts/logs. Since this PR is explicitly adding agent-facing install guidance, the unsafe duplicate needs the same non-printing predicate used in the runbooks, e.g. jq -e '(.refresh_token | type == "string" and length > 0)' ... >/dev/null. Please update or clearly mark the stale plan snippet as superseded so future agents do not reintroduce the credential leak.

2. Medium - The supporting design/plan docs still encode the old bare-command harness wiring.
   Files: docs/superpowers/specs/2026-05-19-agent-install-runbook-design.md:383 and docs/superpowers/plans/2026-05-19-agent-install-runbook.md:755
   The active Claude/Codex runbooks now correctly resolve and store an absolute multi-google-mcp path, but these newly-added support docs still prescribe "command": "multi-google-mcp" / command = "multi-google-mcp". That leaves the design record contradicting the fixed runbooks and makes it easy for the next agent to regenerate or patch the runbook back to the GUI PATH bug. Please bring the spec/plan docs in sync with the absolute-path approach or mark the old snippets as obsolete.

Verification:

• uv run ruff check . passed.
• uv run mypy passed.
• uv run pytest passed: 88 tests.
• GitHub PR check "pytest + ruff + mypy" is passing.

Summary:
The active runbooks now address the previous findings, but the PR still adds stale copied guidance with the same token-disclosure and launch-path problems. Because these are agent-facing docs, I would not merge until the duplicates are corrected or explicitly deprecated.

[MrBenJ]

Round 3 addressed in b66085d:

• High (refresh_token in spec/plan) — verification examples in both docs/superpowers/specs/2026-05-19-agent-install-runbook-design.md and docs/superpowers/plans/2026-05-19-agent-install-runbook.md now use the same jq -e '.refresh_token != null' … >/dev/null pattern as the runbooks, with explicit rationale.
• Medium (bare-name commands in spec/plan) — config-edit examples updated throughout both supporting docs to introduce a <MGM_BIN> placeholder, resolve via command -v at write time, and use the awk-based in-place replace for the Codex case (matching the runbook implementation). The two remaining \"command\": \"multi-google-mcp\" strings are inside cautionary prose explaining why the bare form is wrong — intentionally kept.
• Both supporting docs gained a "canonical source" banner at the top noting the runbooks are authoritative when prose drifts.

[aria-teknal-studio]

No findings.\n\nThe current head resolves the prior review issues:\n- The active Claude Desktop and Codex runbooks no longer print refresh tokens during account verification; the remaining matches are cautionary text explaining why the unredirected form is unsafe.\n- The active runbooks now resolve with and write an executable absolute path into harness config.\n- The supporting spec/plan docs were brought into alignment with those safety fixes and now clearly defer to the shipped runbooks as canonical.\n\nVerification:\n- All checks passed! passed.\n- Success: no issues found in 14 source files passed.\n- ........................................................................ [ 81%]
................ [100%]
88 passed in 0.28s passed: 88 tests.\n- GitHub PR check is passing.\n\nResidual risk:\nThis is documentation-only, so CI does not exercise the runbooks end-to-end in a real Claude Desktop/Codex installation. Manual install smoke testing is still the meaningful final gate for these docs.\n

[aria-teknal-studio]

No findings.

The current head resolves the prior review issues:

• The active Claude Desktop and Codex runbooks no longer print refresh tokens during account verification; the remaining .refresh_token matches are cautionary text explaining why the unredirected form is unsafe.
• The active runbooks now resolve multi-google-mcp with command -v and write an executable absolute path into harness config.
• The supporting spec/plan docs were brought into alignment with those safety fixes and now clearly defer to the shipped runbooks as canonical.

Verification:

• uv run ruff check . passed.
• uv run mypy passed.
• uv run pytest passed: 88 tests.
• GitHub PR check pytest + ruff + mypy is passing.

Residual risk:
This is documentation-only, so CI does not exercise the runbooks end-to-end in a real Claude Desktop/Codex installation. Manual install smoke testing is still the meaningful final gate for these docs.