chore: Update CLAUDE.md file.

Author: Eoic

.claude/settings.json

@@ -3,6 +3,7 @@
     "feature-dev@claude-plugins-official": true,
     "agents-specialized-domains@buildwithclaude": true,
     "documentation-generation@claude-code-workflows": true,
-    "agents-design-experience@buildwithclaude": true
+    "agents-design-experience@buildwithclaude": true,
+    "playwright@claude-plugins-official": true
   }
 }

.gitignore

@@ -1,2 +1,3 @@
 docs/site/
-NOTES.md
+NOTES.md
+firebase-debug.log

CLAUDE.md

@@ -42,26 +42,42 @@ flutter test
 
 ### Architecture (`client/lib/`)
 
-- **`main.dart`** - App entry point; initializes Firebase and sets up Provider
-- **`config/`** - App configuration (routing via GoRouter)
-- **`pages/`** - Full-screen views
-- **`providers/`** - State management (ChangeNotifier pattern)
-- **`widgets/`** - Reusable UI components
-- **`forms/`** - Form widgets
-- **`models/`** - Data models
-- **`themes/`** - Color schemes (Material 3 light/dark)
+- **`main.dart`** - Entry point; Firebase init, MultiProvider setup
+- **`config/`** - GoRouter routing (`app_router.dart`)
+- **`pages/`** - 20 full-screen views (auth, library, book management, goals, statistics, profile, settings, developer options)
+- **`providers/`** - 13 ChangeNotifier providers (auth, library, book details/edit, shelves, goals, statistics, dashboard, annotations, bookmarks, notes, display mode, sidebar)
+- **`widgets/`** - 100+ components in 23 feature subdirectories (auth, book, book_details, library, dashboard, shell, goals, statistics, etc.)
+- **`models/`** - 16 data models (book, shelf, tag, annotation, bookmark, note, reading session/goal/streak, series, etc.)
+- **`data/`** - DataStore (single source of truth ChangeNotifier) + SampleData for offline mode
+- **`services/`** - Metadata extraction (`metadata_service.dart`, `file_metadata_service.dart`)
+- **`forms/`** - Login and register form state/validation
+- **`themes/`** - Material 3 themes (light/dark/e-ink) + design tokens (`design_tokens.dart`)
+- **`utils/`** - Responsive layout, color/image utils, search query parser, navigation helpers
 
 ### Key Patterns
 
-**State Management**: Provider with ChangeNotifier classes.
+**State Management**: Provider with ChangeNotifier classes. DataStore in `data/data_store.dart` is the single source of truth, loaded with SampleData on startup for offline mode.
 
 **Navigation**: GoRouter with nested shell routes:
+
 - Bottom nav: Dashboard, Library, Goals, Statistics, Profile
 - Library drawer: Books, Shelves, Topics, Bookmarks, Annotations, Notes
 - Routes in `config/app_router.dart`
 
 **Authentication**: Firebase Auth with Google Sign-In.
 
+**Responsive Design**: `utils/responsive.dart` with breakpoints defined in `themes/design_tokens.dart` — mobile (<600), tablet (600-839), desktop (840+), large desktop (1200+). Grid columns, gutters, and margins adapt per breakpoint.
+
+**Design Tokens**: `themes/design_tokens.dart` defines `Spacing`, `ComponentSizes`, `BorderWidths`, `IconSizes`, `AppRadius`, `AppElevation`, and `Breakpoints`.
+
+**E-ink Mode**: Theme-based approach — `AppTheme.eink` handles grayscale colors; widgets use theme colors, not hardcoded values. No separate widget builds. 4 remaining e-ink-specific widgets for structurally different navigation components.
+
+**Widgets**: Feature-based directory organization under `widgets/` (auth/, book/, library/, dashboard/, shell/, etc.). Reuse shared components from `widgets/shared/`.
+
+### Tests
+
+29 test files covering models, providers, widgets, services, and utils. Run with `flutter test` from `client/`.
+
 ## Server (Python/FastAPI)
 
 ### Commands
@@ -99,8 +115,9 @@ pytest --cov                   # Run with coverage
 ### API Documentation
 
 When the server is running:
-- OpenAPI UI: http://localhost:8000/docs
-- ReDoc: http://localhost:8000/redoc
+
+- OpenAPI UI: <http://localhost:8000/docs>
+- ReDoc: <http://localhost:8000/redoc>
 
 ## Development Setup
 
@@ -114,10 +131,12 @@ lefthook install
 ```
 
 **Pre-commit** (runs in parallel):
+
 - Client: `dart format`, `dart analyze`
 - Server: `ruff format`, `ruff check`
 
 **Pre-push** (runs in parallel):
+
 - Client: `flutter test`
 - Server: `mypy`, `pytest`
 
@@ -126,19 +145,23 @@ To skip hooks temporarily: `git commit --no-verify`
 ### CI/CD Workflows
 
 **Client CI** (`.github/workflows/ci.yml`):
+
 - Triggers on changes to `client/**`
 - Runs format check, analysis, and tests
 
 **Client Release** (`.github/workflows/release.yml`):
+
 - Triggers on `v*` tags (e.g., `v1.0.0`)
 - Builds Android, Web, Linux, Windows artifacts
 - Creates GitHub Release
 
 **Server CI** (`.github/workflows/server-ci.yml`):
+
 - Triggers on changes to `server/**`
 - Runs format, lint, type check, and tests with coverage
 
 **Server Release** (`.github/workflows/server-release.yml`):
+
 - Triggers on `server-v*` tags (e.g., `server-v1.0.0`)
 - Runs quality checks and creates GitHub Release
 
@@ -160,6 +183,20 @@ git push origin server-v1.0.0
 - Examples: "Apply filters" (not "Apply Filters")
 - Exception: Acronyms remain uppercase (PDF, EPUB)
 
+## Visual App Exploration (Chrome MCP)
+
+To visually explore the running Flutter web app using Chrome MCP (`mcp__claude-in-chrome__*`):
+
+1. Start the web server: `flutter run -d web-server --web-port=8080` from `client/`
+2. Navigate to `http://localhost:8080` using `mcp__claude-in-chrome__navigate`
+3. Use `mcp__claude-in-chrome__computer` with `screenshot` action to capture current state
+4. Use `left_click` with coordinates to interact with UI elements
+
+**Notes:**
+
+- Flutter web uses CanvasKit (canvas rendering) — Playwright MCP cannot interact with elements, but Chrome MCP `computer` tool works via coordinate-based clicks
+- Click "Use offline mode" on the welcome page to bypass auth for local testing
+
 ## Project Resources
 
 - **Documentation**: `docs/` directory, run `mkdocs serve` to browse locally