docs: enhance CLAUDE.md with architecture and commands

[mtskf]

Summary

• Add Claude Code standard prefix for proper recognition
• Add single test file and watch mode commands
• Add extension loading instructions
• Add architecture diagram showing data flow
• Document core files and their responsibilities
• Add safety invariant documentation

🤖 Generated with Claude Code

[claude]

Minor Clarification Needed: The watch mode command syntax could be clearer.

The current documentation shows:

npm test -- --watch

While this is technically correct for vitest, it might be clearer to show it as:

npm test -- --watch

or mention that vitest runs in watch mode by default when using:

npm test

This is not technically incorrect, but adding a brief note about vitest's watch behavior could improve clarity for developers unfamiliar with vitest.

[claude]

The test commands documentation is good, but it's missing coverage-related commands. Consider adding:

| `npm test -- --coverage` | Run tests with coverage report |

The project has @vitest/coverage-v8 installed (as seen in package.json), so developers should know how to generate coverage reports. This is especially important for a Chrome extension where critical safety invariants need thorough testing.

[claude]

The safety invariant "Tabs are NEVER closed before storage write succeeds" is critical and well-documented. However, it would be helpful to add a reference to the test files that verify this invariant:

**Safety invariant:** Tabs are NEVER closed before storage write succeeds.  
(See: `src/background/snoozeLogic.safety.test.ts`)

This helps developers understand where to look for examples of how this critical behavior is tested and ensures they maintain these tests when making changes.

[claude]

The Development Notes section mentions error handling (try-catch + retry) but doesn't mention testing best practices. Consider adding a bullet point about testing:

- Write tests for new features (unit tests for logic, integration tests for Chrome APIs)
- Test error paths and edge cases, especially for storage operations

This would help establish testing as a core development practice and remind developers to test error scenarios, which is particularly important for Chrome extension APIs that can fail in various ways.

[claude]

Documentation Best Practice: Section Organization

The Commands section appears before Architecture, but typically architectural overview comes before operational commands in documentation. This helps readers understand what they're working with before learning how to use it.

Suggestion:
Consider reordering sections as follows:

1. Project Overview
2. Architecture (understand the system)
3. Commands (learn how to use it)
4. Development Notes
5. Documentation

Impact: Improves logical flow and makes documentation easier to navigate for new developers.

[claude]

The documentation references section is helpful, but it should mention testing documentation or patterns. Consider adding:

| File | Content |
|------|---------|
| ARCHITECTURE.md | Full architecture, data model, flows |
| SPEC.md | Feature specifications |
| DECISIONS.md | Design decision records |
| src/test/setup.ts | Test environment configuration and mocks |

This helps developers understand where to find test setup and mocking patterns, especially for Chrome extension APIs which require special mocking.