Readme Doctor

Accuracy Rules

• Every CLI example MUST be verified against actual --help output. Run cargo run --offline -- <cmd> --help and compare.
• Flag names, defaults, and descriptions must match what clap actually produces.
• gRPC RPCs must match the proto file exactly.
• REST routes must match the Axum router in rest.rs.
• MCP tools must match the tool definitions in mcp.rs.
• Environment variables must match what the code actually reads (check with grep -r "HAAKE_" src/).
• No aspirational features — only document what actually works.

Style Rules

• Use active voice
• Prefer concrete examples over abstract descriptions
• Keep sentences concise
• Use consistent formatting throughout
• Code blocks must specify the language (bash, rust, yaml, etc.)
• No emojis unless the user requests them
• Use backtick formatting for CLI commands, flags, env vars, file paths

Part 2: CLI Help-Text Audit

What to Check

For every command and subcommand:

1. Run <binary> <cmd> --help and capture the output
2. Verify congruence across all commands:
   • Consistent terminology (e.g., "Agent name" vs "Agent or scope name" — pick one)
   • Consistent flag naming patterns (e.g., -y/--yes for skip confirmation everywhere)
   • Consistent default value formatting
   • No superfluous or confusing syntax in usage lines
3. Verify correctness against code:
   • Every #[arg] attribute matches the help output
   • Default values shown in help match actual defaults in code
   • Descriptions are accurate and not misleading
   • Possible values listed are complete and correct
4. Flag for issues:
   • Missing descriptions
   • Inconsistent capitalization
   • Arguments that exist in code but don't appear in help
   • Help text that references removed features
   • Duplicate or conflicting short flags

Congruence Report Format

CLI Help-Text Audit Report
==========================

Commands scanned: N
Issues found: N

INCONSISTENCIES:
  [WARN] `haake query` uses "Agent name" but `haake memory insert` uses
         "Agent or scope name" — should be consistent
  [FIX]  `haake memory insert --type` should be `--memory-type` to match
         other commands

MISSING:
  [MISS] `haake serve` does not document HAAKE_REST_PORT env var

INCORRECT:
  [ERR]  `haake import --type` default shown as "working" but code
         defaults to "semantic"

SUPERFLUOUS:
  [TRIM] `haake memory insert` shows "-V, --version" which is noise
         for a subcommand

Workflow

Step 1: Gather

• Read current README.md
• Run <binary> --help and all subcommand --help
• Read proto files, rest.rs routes, mcp.rs tool definitions
• Read Cargo.toml for version and metadata
• Grep for env vars: grep -rn "HAAKE_\|SW4RM_" src/

Step 2: Audit Help Text

• Run Part 2 checks
• Produce the congruence report
• Fix any issues found in the clap definitions (with user approval)

Step 3: Write README

• Generate the full README following Part 1 structure
• Every CLI example must use exact flag names from --help output
• Present a diff summary to the user before writing

Step 4: Validate

• Re-run all --help commands and verify README matches
• Check all internal links resolve
• Verify code examples are syntactically valid

Safety

• Always read existing README before overwriting
• Present changes for approval on first use
• Do not modify clap definitions without asking
• Do not add features to README that don't exist in code