docs: Add schema design documentation

[evansenter]

Summary

• Add docs/SCHEMA.md with comprehensive database schema documentation
• Link from CLAUDE.md and README.md

Contents

The schema docs cover:

• Design principles (don't over-distill, aggregate→drill-down)
• All 8 tables with column definitions
• Complete index list for all tables (events, git_commits, session_commits, bus_events)
• FTS5 full-text search setup
• Migration history (v1-v7)
• Schema evolution guidelines

Re-created after PR #65 was auto-closed when its base branch was deleted.

🤖 Generated with Claude Code

[claude]

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

Code Review

Summary

This PR adds comprehensive database schema documentation in docs/SCHEMA.md, covering all 8 tables, indexes, FTS5 setup, and migration history. It also links this documentation from CLAUDE.md and README.md.

Issues Found

Critical

None

Important

None

Suggestions

• docs/SCHEMA.md:32-156 - The Tables Overview lists ingestion_state and patterns tables but they don't have their own detailed schema sections under "Core Tables" like the other 6 tables. For consistency and completeness, consider adding schema definitions for these two tables:

-- ingestion_state (from storage.py:571-577)
CREATE TABLE ingestion_state (
    file_path TEXT PRIMARY KEY,
    file_size INTEGER,
    last_modified TIMESTAMP,
    entries_processed INTEGER,
    last_processed TIMESTAMP
)

-- patterns (from storage.py:582-591)  
CREATE TABLE patterns (
    id INTEGER PRIMARY KEY,
    pattern_type TEXT NOT NULL,
    pattern_key TEXT NOT NULL,
    count INTEGER DEFAULT 0,
    last_seen TIMESTAMP,
    metadata_json TEXT,
    computed_at TIMESTAMP,
    UNIQUE(pattern_type, pattern_key)
)

• docs/SCHEMA.md:19-30 - The schema_version table (created in storage.py:493-495) is not mentioned in the Tables Overview or documented. While internal, it's part of the schema and documenting it would be thorough.

Verdict

REQUEST_CHANGES - The schema documentation is accurate and well-organized, but two tables mentioned in the overview (ingestion_state, patterns) lack detailed schema definitions that the other tables have, and schema_version is undocumented.

---

Automated review by Claude Code

[claude]

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

Code Review

Summary

This PR adds comprehensive database schema documentation in docs/SCHEMA.md, covering all 8 tables, indexes, FTS5 setup, and migration history. It links this documentation from both CLAUDE.md and README.md.

Issues Found

Critical

None

Important

None

Suggestions

• docs/SCHEMA.md:209-219 - The patterns table schema is missing the UNIQUE(pattern_type, pattern_key) constraint that exists in the actual code (storage.py:590). Add it for accuracy:

  computed_at TIMESTAMP,
  UNIQUE(pattern_type, pattern_key)

• docs/SCHEMA.md:140-149 - The session_commits table schema is missing the FOREIGN KEY constraints that exist in the actual code (storage.py:621-623). Consider adding for completeness:

  PRIMARY KEY (session_id, commit_sha),
  FOREIGN KEY (session_id) REFERENCES sessions(id),
  FOREIGN KEY (commit_sha) REFERENCES git_commits(sha)

Verdict

REQUEST_CHANGES - The schema documentation is well-organized and thorough. The two suggestions above are minor accuracy improvements to ensure the documented schemas match the actual implementation.

---

Automated review by Claude Code

[claude]

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

Code Review

Summary

This PR adds comprehensive database schema documentation in docs/SCHEMA.md, covering all 8 tables, indexes, FTS5 setup, and migration history. It links this documentation from both CLAUDE.md and README.md.

Issues Found

Critical

None

Important

None

Suggestions

• docs/SCHEMA.md:130-137 - The session_commits table schema is missing the FOREIGN KEY constraints that exist in the actual code (storage.py:305-307, 621-623). Consider adding for accuracy:

  PRIMARY KEY (session_id, commit_sha),
  FOREIGN KEY (session_id) REFERENCES sessions(id),
  FOREIGN KEY (commit_sha) REFERENCES git_commits(sha)

• The schema_version table (storage.py:492-495) is not documented. While internal/infrastructural, it's part of the actual schema. Consider adding a note or section about it for completeness.

Verdict

REQUEST_CHANGES - The schema documentation is well-organized and thorough. The two suggestions are minor accuracy improvements to ensure the documented schemas fully match the implementation.

---

Automated review by Claude Code