feat(init): manage a flare-docs usage rule + add agentflare doctor

[getappz]

Summary

• Follow-up to feat(flare-docs): index per-item rustdoc docs, not just the crate overview #323 (flare-docs per-item indexing). While dogfeeding that PR live, established that Claude doesn't spontaneously know to use mcp__flare__flare_docs — it's a deferred MCP tool, invisible until ToolSearch'd by name. Fixes this the same way exa.md/git.md/lean-ctx.md already do: a standing rule instruction loaded into every session automatically.
• rule_text.rs: new FLARE_DOCS constant (matches the existing @use/@when/@fallback/@scope vocabulary), wired into rule_targets() for claude-code and opencode explicitly; cursor/codex/windsurf/vscode-copilot/cline pick it up automatically via joined(). The 12 Agent variants with no researched instructions-file convention in this codebase (gemini-cli, github-copilot-cli, aider, cody, goose, amp, kiro, antigravity, grok, kimi, openclaw, droid) are left on the existing "continue"-style empty fallback rather than guessing at 12 unverified config formats.
• New top-level agentflare doctor [--agent <agent>] [--json] — read-only setup/config health check, distinct from agentflare agents doctor (binary/version detection) and agentflare git doctor (worktree hygiene, fix(backend): add LIKE fallback to item search for compound-token substrings #235). Reuses get_components(host).check() exactly as init already does, plus flags stale rule files via init::is_stale_rule. Exits 1 on any violation.
• Fixes two pre-existing clippy errors surfaced while running the full CI gate on Windows (confirmed via git stash to pre-date this work): daemon_autostart.rs's agentflare_binary()/daemon_home_dir() weren't cfg-gated to match their macOS/Linux-only callers; agent_launch.rs's PATH_LOCK import wasn't gated to match its #[cfg(unix)]-only test usage.

Test plan

• TDD throughout — RED confirmed (failing test / compile error) before each implementation
• cargo test --bin agentflare — 771 passed, 0 failed
• cargo clippy --bin agentflare --all-targets --all-features -- -D warnings -A unsafe_code -A clippy::pedantic — clean (previously 2 pre-existing errors, now fixed)
• cargo fmt — clean
• Live end-to-end on this machine: doctor --agent claude-code correctly reported rules: MISSING; init --agent claude-code -y wrote exactly flare-docs.md (left the 3 already-present rule files untouched); re-ran doctor — all green, exit 0; confirmed ~/.claude/rules/flare-docs.md content on disk

Summary by CodeRabbit

• New Features

  • Added an agentflare doctor command to check agent configuration health.
  • Supports checking a specific agent and returning results in human-readable or JSON format.
  • Reports missing components and stale rule files, with a failure status when issues are found.
  • Added shared Flare documentation rules for supported coding agents.

• Bug Fixes

  • Improved cross-platform build compatibility by limiting platform-specific code to supported systems.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4f3d4821-2087-432f-9651-ebc3eee202d8

📥 Commits

Reviewing files that changed from the base of the PR and between fc34887 and 55181f7.

📒 Files selected for processing (9)

• src/agent_launch.rs
• src/cli/doctor.rs
• src/cli/mod.rs
• src/components.rs
• src/daemon_autostart.rs
• src/doctor.rs
• src/init.rs
• src/main.rs
• src/rule_text.rs

---

📝 Walkthrough

Walkthrough

Adds an agentflare doctor command that checks agent components and stale rules, introduces flare-docs rule coverage, and restricts selected code to supported platforms.

Changes

Doctor diagnostics and rule coverage

Layer / File(s)	Summary
Flare-docs rule contracts and targets src/rule_text.rs, src/components.rs	Adds FLARE_DOCS, superseded-rule mapping, host targets, and tests for generated rule content.
Doctor health-check engine src/doctor.rs, src/init.rs	Checks configured components and stale rules, detects hosts, aggregates results, formats JSON or text output, and validates behavior with unit tests.
Doctor CLI integration src/main.rs, src/cli/doctor.rs, src/cli/mod.rs	Registers the doctor module, defines --agent and --json, and dispatches the new subcommand.
Platform-specific compilation src/daemon_autostart.rs, src/agent_launch.rs	Restricts daemon autostart code to macOS/Linux and gates the Unix-only test import.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant Doctor
  participant AgentRegistry
  participant Components
  participant Init
  CLI->>Doctor: run(agent, json)
  Doctor->>AgentRegistry: detect_all()
  Doctor->>Components: check_host(host)
  Doctor->>Init: is_stale_rule(path, current)
  Doctor-->>CLI: print results and exit status

Loading

Possibly related PRs

• getappz/agentflare#60: Introduced the CLI dispatch structure and agent-registry integration used by the doctor command.
• getappz/agentflare#112: Shares the stale-rule detection and superseded-rule mechanisms used by doctor.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and matches the main changes: adding flare-docs rule management and a new doctor command.
Description check	✅ Passed	Includes the required Summary and Test plan sections with specific details; only the Notes for reviewers section is missing.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch task/345

---

_{Comment @coderabbitai help to get the list of available commands.}