docs: add CLAUDE.md with architecture and command reference

[smartwatermelon]

Summary

• Replaces the bare Headroom-only CLAUDE.md with full onboarding guidance for Claude Code
• Documents wrapper execution flow, module dependency chain, and security model
• Adds test/lint commands and config file locations table

Test plan

• Verify markdownlint passes (npx markdownlint-cli --config ~/.markdownlint.json CLAUDE.md)
• Confirm architecture section matches actual code flow
• Non-blocking review issues tracked in Execution flow steps 5-7 are misordered relative to actual code #30 and github-token.sh description omits 1Password as primary token source #31

🤖 Generated with Claude Code

[claude]

PR Review: docs: add CLAUDE.md with architecture and command reference

This is a documentation-only PR adding CLAUDE.md. No executable code is changed.

Summary

The architecture description, execution flow, module dependency chain, security model, and config table are all accurate and well-organized. The "Commands" section is correct and matches the actual test files.

---

Non-blocking observations

1. Hardcoded local absolute paths in the Headroom section (maintenance impact: medium)

Lines 92 and 101 embed machine-specific absolute paths:

• Line 92: Client repos live at /Users/andrewrich/Developer/clients/
• Line 101: bash /Users/andrewrich/Developer/claude-wrapper/tests/test-wrapper.sh

These paths are useless to any other contributor and will silently mislead any Claude session not running on Andrew's machine. If future Claude sessions follow these paths, they'll get file_not_found errors — exactly the failure mode the Headroom note is trying to prevent. The canonical relative-path version already appears correctly in the Commands section (line 14–16).

Suggestion: Replace the absolute path on line 101 with the relative form bash tests/test-wrapper.sh (consistent with lines 14–16), and rephrase line 92 to omit the machine-specific path (or drop it, since it describes a local client repo structure, not this repo).

2. "Do not edit manually" directive on a committed file (maintenance impact: low)

Lines 83–84: *Auto-generated by headroom learn on 2026-04-03 — do not edit manually*

This instruction made sense when the section lived only in a local AI context file. Now that it's committed in a PR, contributors will reasonably need to update it, and the directive is misleading. Consider changing it to *Last updated by headroom learn on 2026-04-03 — prefer headroom learn for updates* or similar.

3. Minor: table alignment inconsistency in config file locations (maintenance impact: negligible)

Line 70: | ------ | ------- | — the separator row widths don't match the header columns, though this renders correctly in all Markdown parsers. Purely cosmetic.

---

Security, bugs, regressions

None found. This PR adds only documentation.

VERDICT: PASS