feat(setup): one-command first-run flow + agent-narrowing defaults (closes #103)

[liam-ai-reality]

Summary

This PR implements all 4 changes from issue #103, landing in the suggested order (each as a separate commit).

Changes

1. Default [gate].agents to detected agents (feat/adopt: default [gate].agents to detected agents) — new adopt/detect_agents.rs probes ~/.claude/, ~/.codex/, ~/.aider*; write_klasp_toml gains agents: Option<&[String]> param; klasp init --adopt --mode mirror uses the narrowed list.

2. Auto-suffix duplicate check names (feat/adopt: auto-suffix duplicate check names on collision) — when two ProposedChecks collide on the same name, the second gets a gate-type suffix: lint → lint-lefthook. First keeps bare name.

3. klasp install warn-on-narrower (feat/install: warn when --agent <single> is narrower than [gate].agents) — single-agent install against a multi-agent klasp.toml emits a WARN to stderr; install still exits 0.

4. klasp setup orchestrator (feat/setup: one-command first-run orchestrator) — new subcommand runs detect → narrow → write → install → doctor in one command. --interactive adds y/n prompts. --dry-run writes nothing. docs/setup.md added.

Acceptance criteria mapping

AC	Commit	Test
klasp setup exists and runs full sequence	4 (1e4d1c2)	tests/setup.rs::setup_help_exits_successfully, claude_only_home_narrows_agents_to_claude_code
Fresh repo with ~/.claude/ only → agents = ["claude_code"] + doctor exits 0	4 (1e4d1c2)	tests/setup.rs::claude_only_home_narrows_agents_to_claude_code (smoke-tested end-to-end manually)
--interactive prompts before write + install	4 (1e4d1c2)	tests/setup.rs::interactive_n_to_mirror_skips_write, interactive_y_y_writes_file
--dry-run prints plan, writes nothing	4 (1e4d1c2)	tests/setup.rs::dry_run_prints_plan_writes_nothing
Duplicate names → second gets gate suffix; unit test in writer.rs	2 (8687224)	klasp/src/adopt/writer.rs::tests::duplicate_name_suffix_on_collision, first_occurrence_keeps_bare_name
klasp init --adopt --mode mirror with ~/.claude/ only → agents = ["claude_code"]	1 (06103b3)	klasp/src/adopt/writer.rs::tests::agents_some_uses_narrowed_list; klasp/src/adopt/detect_agents.rs::tests::claude_only_home_returns_claude_code
klasp install --agent <single> against multi-agent config emits WARN; install succeeds	3 (5015221)	tests/setup.rs::install_single_agent_warns_about_uncovered, install_all_does_not_warn_narrower
Integration tests: claude-only, all-three, #97 fixtures, dry-run, interactive Y/N	4 (1e4d1c2)	tests/setup.rs (11 tests)
docs/setup.md documents new flow with copy-paste first-run example	4 (1e4d1c2)	docs/setup.md

Test plan

• cargo build --workspace — clean
• cargo fmt --all -- --check — clean
• cargo clippy --all-targets --workspace -- -D warnings — clean
• cargo test --workspace — 693 passed (up from 682 before this PR, +11 new tests)
• Manual smoke test: fresh repo + fake ~/.claude/ only → klasp setup → doctor: all checks passed, agents = ["claude_code"]

Non-goals (not changed)

• Individual surface install logic (codex/aider managed-block / config-merge)
• Adding new agent surfaces
• Replacing init / install / doctor
• Fixing doctor false-positive 'schema drift' on codex hook with managed-block append #102 (doctor codex drift false-positive)

🤖 Generated with Claude Code

[liam-ai-reality]

🟢 Suggestion (cosmetic — AC #6 literal text): narrowed_agents_arg's None branch is unreachable from real callers. detect_installed_agents never returns an empty Vec — when home-dir lookup fails OR no probes match, it returns all_agents_fallback() (the 3-element ["claude_code", "codex", "aider"]). So this None arm only fires from the unit test on line 172.

User-visible effect: the no-detection path correctly writes the 3-agent default, but without the # Comment out any you don't use hint that the writer's None branch emits. AC #6 reads literally as "falls through to today's default with the 'edit me' comment" — the comment is missing.

Fix (smallest delta — keep detect_installed_agents returning a Vec but compare against the fallback at the call site):

use crate::adopt::detect_agents::{detect_installed_agents, ALL_AGENTS};

let detected_agents = detect_installed_agents(home.as_deref());
let agents_arg = if detected_agents.iter().map(String::as_str).eq(ALL_AGENTS.iter().copied()) {
    None
} else {
    Some(detected_agents.as_slice())
};

(Requires making ALL_AGENTS pub(crate) if not already.) Or change detect_installed_agents to return Option<Vec<String>> and have callers map None. Either way, also apply in cmd/setup.rs line 115 which has the same dead Some(...) wrap.

Low severity — functional 3-agent fallback works; just the helper comment is lost.

[liam-ai-reality]

Code review

Summary

Reviewed 5 commits / 1600 LOC across 12 files: 4 feature commits implementing issue #103 (agent-narrowing defaults, duplicate-name suffix, install warn-on-narrower, klasp setup orchestrator + 11 integration tests + docs/setup.md) plus a follow-up simplify pass (b655deb) that deduplicates doctor-check logic, restores dropped actionable hint lines in print_hook_warning, hoists config load out of the install loop, and replaces stringly-typed agent IDs with AGENT_ID constants. Tests 693 → 695, clippy clean.

Critical Issues

File	Line	Issue
—	—	None

Suggestions

File	Line	Issue
klasp/src/cmd/init.rs	139–145	narrowed_agents_arg's None branch is unreachable from production callers. detect_installed_agents never returns an empty Vec — it falls back to all-three on no-detection. Result: AC #6's literal "falls through to today's default with the 'edit me' comment" is missed (3-agent default writes correctly, but without the # Comment out any you don't use hint from writer's None branch). Fix at the init.rs + setup.rs call sites by comparing against ALL_AGENTS and mapping equal → None. See inline comment for diff. Cosmetic; functional behaviour is correct.

What Looks Good

• Doctor-check refactor (b655deb) cleanly extracted pub(crate) per-check fns; setup now reuses them, preventing the divergence the simplify-reviewer flagged (missing ConfigVersion/ConfigParse/Io arms).
• install_one_surface extraction unifies the Codex-vs-non-Codex dispatch path between cmd::install::try_run and cmd::setup::run_install_all — single source of truth for surface dispatch.
• print_hook_warning consolidation also restored 3 actionable hint lines that the original setup copy silently dropped — a quiet correctness win.
• 11 integration tests in klasp/tests/setup.rs cover claude-only, all-three-detected, dry-run, interactive Y/N branches, and the install warn-on-narrower scenario. EOF on stdin returns "no" (correctly matched by the "" arm), confirmed by interactive_n_to_mirror_skips_write.
• Atomic write of klasp.toml reuses the existing fs_util::atomic_write_text (NamedTempFile + persist) — no new TOCTOU surface.
• All 8 issue klasp setup: one-command first-run flow + sensible install/adopt defaults #103 acceptance criteria are exercised by tests; mapping is auditable in the PR body.

Verdict

🟡 One non-blocking suggestion. The flagged narrowed_agents_arg issue is cosmetic (AC #6 literal-text drift, not functional regression). Safe to merge as-is or address in a 2-line follow-up.

---

Reviewed by /agentic-flow step 07-code-review on commit b655deb. 4 parallel reviewers (2 CLAUDE.md compliance, 2 bug-scan), 2 validators. Raw findings: 3 (1 stdin-bound CLAUDE.md flag — INVALID per validator; 1 narrowed_agents bug — VALID-low-severity, posted inline; 1 reviewer reported clean). High-signal validated: 1.

[liam-ai-reality]

Review remediation

Addressed inline in commit d1e5859.

Suggestion: AC #6 literal-text drift on narrowed_agents_arg None branch

Per discussion_r3208525826 — original narrowed_agents_arg checked detected.is_empty(), but detect_installed_agents always returned a non-empty Vec (3-agent fallback on no-detection), so the None arm was unreachable from production callers and the writer's "Comment out any you don't use" hint never fired in real runs.

Fix: disambiguated at the source rather than at the call site. detect_installed_agents now returns (Vec<String>, bool) where the bool flags fell_back. Callers thread this directly into narrowed_agents_arg(detected, fell_back). Side-effect: a user who genuinely has all three agents installed (~/.claude/ + ~/.codex/ + ~/.aider* all present) is no longer mis-classified as "fallback" — they get the narrowed-list-without-edit-me-comment behaviour they deserve.

Touched:

• klasp/src/adopt/detect_agents.rs — signature + 7 tests updated (including new "all-three-detected is NOT fallback" assertion)
• klasp/src/cmd/init.rs — destructure tuple; narrowed_agents_arg takes fell_back flag; 3 tests
• klasp/src/cmd/setup.rs — destructure; agents_arg = None on fallback; print prefix (none — falling back to ...) for visibility

Tests: 695 → 696 (net +1 — three new init.rs assertions replacing two; remaining detect_agents cases now assert the fell_back flag too). cargo clippy --all-targets --workspace -- -D warnings clean. cargo fmt --all -- --check clean.

No deferred follow-ups. Ready to merge.