`agent init --all`: installs a CLAUDE.md reference to a skill it skips; `--dry-run` over-reports the plan; assorted doc/UX inaccuracies

[JJB1]

A cluster of small accuracy problems in rafter agent init --all and the docs it installs, found while setting up the Claude Code integration on a clean machine. Grouped because they're all the same kind of defect — the installer and its output describe a state that doesn't match what actually happened.

Environment: macOS 15 (darwin/arm64) · Node v26.0.0 · npm 11.12.1 · @rafter-security/cli 0.10.0 · betterleaks 1.1.2.

---

1. --all skips rafter-skill-review, but the CLAUDE.md it installs references it

• --dry-run lists ~/.claude/skills/rafter-skill-review/SKILL.md as a planned write

• The real run does not install it — rafter skill list reports not installed

• The CLAUDE.md block that is installed instructs agents to invoke it:

  About to install or forward a third-party SKILL.md, MCP manifest, Cursor rule, or agent config → rafter-skill-review (before copying anywhere).

So init writes a global instruction pointing at a skill it declined to install, and the dangling reference sits in the third-party-supply-chain path — the one place you'd least want a silent no-op. The other three skills install fine.

Workaround: rafter skill install rafter-skill-review.

2. --dry-run over-reports the plan

Dry run announces Plan: 11 writes, 1 download. Two of the writes never occur:

• ~/.claude/skills/rafter-skill-review/SKILL.md (see above)
• ~/.mcp.json — also described as "project-scope MCP config" while being pathed at $HOME

Since the point of --dry-run is to let someone approve changes to user-global config before they happen, it should match the real run exactly.

3. A fully healthy install displays as 3/12 core checks passed

$ rafter agent verify
✓ Config: /Users/jb/.rafter/config.json
✓ Betterleaks: 1.1.2 (/Users/jb/.rafter/bin/betterleaks)
✓ Claude Code: Hooks installed
⚠️  OpenClaw: Not detected — run 'rafter agent init --with-openclaw' to enable
… 8 more …
✓ 3/12 core checks passed (9 optional checks not configured)

Everything installed correctly, but it renders as 25%. The 9 "optional" items are integrations for editors that aren't on the machine, so they're counted in the denominator and called "core" in the same sentence that calls them optional. Suggest 3/3 core checks passed with the uninstalled integrations listed separately.

Relatedly, --all prints a warning line for each of those 9 — but --all means "all detected" per its own --help, so these warn about work it was never going to do, and they bury the lines that matter.

4. Docs reference commands that don't exist or are deprecated

• The rafter router skill says rafter audit. There is no such top-level command; it's rafter agent audit. An unknown subcommand prints general help rather than an error.
• agent init --help advertises --with-skill-scanner as "(heavy; audit-skill --deep)", but the CLI marks agent audit-skill deprecated in favour of rafter skill review.

5. The approval hint is unpastable for real commands

On a blocked command the gate emits:

To approve: rafter agent exec --approve "<command>"

with the entire original command echoed inside double quotes. For anything multi-line, or containing a quote, the suggested command doesn't survive a paste. Both blocks I hit in normal use were unpastable.

6. rafter secrets . prints (both) with no explanation

Scanning directory: /path/to/project (both)

Presumably regex + betterleaks, but the term isn't defined in output or --help.

---

Happy to send a PR for any of these if useful — 1 and 2 look like the ones worth fixing first.