docs: Slim documentation by 49% and fix coverage gaps

[evansenter]

Summary

• Audit found documentation had grown bloated with redundancy across files
• Reduced total documentation from 1,051 to 540 lines (-49%)
• Fixed coverage gaps: 3 missing tools in guide.md, RFC RFC: Close data coverage gaps in session analytics ingestion #41 missing from README

Changes by File

CLAUDE.md (364 → 165 lines, -55%)

• Move design philosophy principles up front (was buried at line 136)
• Add practical "Adding New Endpoints" checklist
• Remove exhaustive tool/CLI lists (point to guide.md instead)
• Consolidate architecture patterns and naming conventions

README.md (285 → 157 lines, -45%)

• Replace 77-line MCP tool tables with compact summary table
• Add missing RFC RFC: Close data coverage gaps in session analytics ingestion #41 agent tracking (agents CLI + get_agent_activity)
• Point to guide.md for detailed tool reference

guide.md (402 → 218 lines, -46%)

• Add 3 missing tools: sample_sequences, detect_parallel_sessions, get_handoff_context
• Remove "Session Discovery and Drill-In" section (duplicated Broad→Narrow workflow)
• Replace 120-line "Common Patterns" with 35-line "Reference" (kept only unique value)
• Merge Best Practices + Tips + Data Details into compact sections

What Was Kept

• Tool tables in guide.md (authoritative reference for LLMs)
• Workflow diagrams (Broad→Narrow, Question-Based)
• CLI command list in README (useful for terminal reference)
• Essential tips and data paths

Test plan

• All 289 tests pass
• Verified 28 MCP tools documented in both README and guide.md
• Verified 27 CLI commands documented in README

🤖 Generated with Claude Code

[claude]

Prompt: evansenter/dotfiles/.../claude-review.md

Code Review

Summary

This PR consolidates documentation across three files (CLAUDE.md, README.md, guide.md), reducing total lines by ~49% while fixing coverage gaps for 3 missing tools and RFC #41 agent tracking. The changes appropriately centralize detailed tool documentation in guide.md while keeping high-level reference information in README.md and contributor guidance in CLAUDE.md.

Issues Found

Critical

None

Important

None

Suggestions

• CLAUDE.md:104-106 - The naming conventions table omits ingest_* as a valid prefix, though ingest_logs and ingest_git_history are real tools in the API. Consider adding it for completeness:

  | `ingest_*` | Load/import data | `ingest_logs()` |
  

• CLAUDE.md:96-120 - The "Adding New Endpoints" checklist mentions updating guide.md but no longer explicitly lists all discovery surfaces. The old version mentioned 5 surfaces: CLI command, MCP tool, guide.md, CLAUDE.md, and ~/.claude/contrib/README.md. Consider adding a note about updating CLAUDE.md if the endpoint introduces new patterns or conventions.

Verdict

REQUEST_CHANGES - Two minor suggestions for documentation completeness.

---

Automated review by Claude Code

[evansenter]

Feedback Addressed

Implemented

• [Suggestion] CLAUDE.md:104-106 - Added ingest_* prefix to naming conventions table

Skipped

• [Suggestion] CLAUDE.md:96-120 - Checklist already covers essential discovery surfaces; adding CLAUDE.md explicitly would only apply when introducing new patterns (rare case)

[claude]

Prompt: evansenter/dotfiles/.../claude-review.md

Code Review

Summary

This PR consolidates documentation across CLAUDE.md, README.md, and guide.md, reducing total lines by ~49% while fixing coverage gaps for 3 missing tools and RFC #41 agent tracking. The previous feedback has been addressed: ingest_* was added to the naming conventions table, and the suggestion about explicit CLAUDE.md updates was reasonably skipped with justification.

Verdict

APPROVE - Previous feedback addressed. Documentation is now more focused with detailed API reference centralized in guide.md, while keeping essential contributor guidance in CLAUDE.md and user-facing summaries in README.md.

---

Automated review by Claude Code