Content < /div>; / / spaces;
+};
+
+// ✅ CORRECT
+export const Component = () => {
+ return
Content < /div>; / / tabs;
+};
+```
+
+### 2. Using Single Quotes
+
+```typescript
+// ❌ WRONG
+const message = 'Hello World';
+
+// ✅ CORRECT
+const message = 'Hello World';
+```
+
+### 3. Not Using @ Alias
+
+```typescript
+// ❌ WRONG
+import { Task } from '../../contexts/TimeTrackingContext';
+
+// ✅ CORRECT
+import { Task } from '@/contexts/TimeTrackingContext';
+```
+
+### 4. Creating Custom Colors
+
+```typescript
+// ❌ WRONG
+
Content
+
+// ✅ CORRECT
+
Content
+```
+
+### 5. Forgetting to Save Data
+
+```typescript
+// ❌ WRONG — Data not persisted
+setTasks([...tasks, newTask]);
+
+// ✅ CORRECT — Explicitly sync
+setTasks([...tasks, newTask]);
+await forceSyncToDatabase(); // Or wait for critical event
+```
+
+### 6. Bypassing the DataService
+
+```typescript
+// ❌ WRONG — Reads localStorage only; breaks for authenticated users
+// whose data lives in Supabase
+const raw = localStorage.getItem('timetracker_archived_days');
+
+// ✅ CORRECT — Use the context, which routes through the right service
+const { archivedDays } = useTimeTracking();
+```
+
+Any utility that needs archived days must consume the context or accept
+`DayRecord[]` as a parameter. Use `dayRecordsToArchivedDays()` from
+`src/utils/reportUtils.ts` to convert to the `ArchivedDay[]` shape.
+
+---
+
+## Architecture Gotchas
+
+### 1. Manual Sync Required
+
+- **Issue**: Data doesn't auto-save on every change
+- **Solution**: Use `forceSyncToDatabase()` or trigger critical events
+- **Why**: Optimized for single-device usage
+
+### 2. Category Lookup by ID
+
+```typescript
+// ❌ WRONG — Looking up by name
+const category = categories.find(c => c.name === task.category);
+
+// ✅ CORRECT — Looking up by ID
+const category = categories.find(c => c.id === task.category);
+```
+
+### 3. Date Handling
+
+```typescript
+// ❌ WRONG — Date as string
+const startTime = '2024-11-18';
+
+// ✅ CORRECT — Date object
+const startTime = new Date('2024-11-18');
+```
+
+### 4. Supabase User Caching
+
+```typescript
+// ❌ WRONG — Repeated auth calls (slow)
+const {
+ data: { user }
+} = await supabase.auth.getUser();
+
+// ✅ CORRECT — Use cached user helper
+const user = await getCachedUser();
+```
+
+### 5. Gemini API Error Classification
+
+Do **not** surface Gemini's raw `error.message` to the user — it is often vague
+and gives no guidance on whether to wait, fix a key, or switch plans.
+
+Always classify by HTTP status + `error.status` using `classifyGeminiError()`
+in `src/hooks/useReportSummary.ts`:
+
+| Symptom | HTTP | Gemini status | Meaning |
+| ----------------------------- | ---- | ------------------------------ | ------------------------------------ |
+| Multiple consecutive failures | 503 | `UNAVAILABLE` | Server overloaded — retry in seconds |
+| First request of day fails | 429 | `RESOURCE_EXHAUSTED` + "quota" | Daily free-tier limit hit |
+| Rapid retries fail | 429 | `RESOURCE_EXHAUSTED` + "rate" | Per-minute RPM limit — wait 30–60s |
+| Always fails | 403 | `PERMISSION_DENIED` | Bad API key |
+| Always fails in region | 400 | `FAILED_PRECONDITION` | Free tier not available in region |
+
+Also handle `finishReason` on 200 OK responses: a `SAFETY` or `RECITATION`
+block returns HTTP 200 with empty `text` — use `classifyFinishReason()`.
+
+---
+
+## Performance Gotchas
+
+### 1. Avoiding Unnecessary Re-renders
+
+- Use `useCallback` for stable function references
+- Use `useRef` for values that don't need to trigger re-renders
+- Context updates trigger all consumers — keep context lean
+
+### 2. Lazy Loading
+
+- Pages are lazy-loaded — don't preload unnecessarily
+- Always wrap lazy components in `
` with a fallback
+
+---
+
+## AI Self-Check Before Making Changes
+
+- [ ] Did I read the relevant context file first? (`TimeTrackingContext.tsx` or `AuthContext.tsx`)
+- [ ] Did I read `dataService.ts` if touching data persistence?
+- [ ] Did I check existing patterns in similar components?
+- [ ] Am I using tabs and double quotes?
+- [ ] Am I using `@/` import aliases?
+- [ ] Am I using shadcn/ui components (not raw HTML with custom styles)?
+- [ ] Will this work in both guest and authenticated modes?
+- [ ] Did I update the data service if persistence is involved?
+- [ ] Will `npm run lint` and `npm run build` pass?
diff --git a/agents/pull_requests.md b/agents/pull_requests.md
index 82280ea..ce81bfe 100644
--- a/agents/pull_requests.md
+++ b/agents/pull_requests.md
@@ -1,5 +1,15 @@
-# Pull Requests
+# Pull Requests — TimeTracker Pro
-- Always have a title and description that clearly explains the purpose of the PR.
-- Wait until all checks have been completed before suggesting that a PR be merged.
-- Add appropriate Labels to any PR.
+## Title Format
+
+```text
+[TimeTrackerPro]
+```
+
+## Requirements
+
+- Always include a clear title and description explaining the purpose of the PR
+- Keep your branch rebased (not merged) against the base branch
+- Run `npm run lint` and `npm run build` before committing — both must pass
+- Wait until all checks have completed before suggesting a PR be merged
+- Add appropriate labels to every PR
diff --git a/agents/styles.md b/agents/styles.md
index 55f53d4..36d5767 100644
--- a/agents/styles.md
+++ b/agents/styles.md
@@ -1,6 +1,6 @@
-# Styles
+# Styles — TimeTracker Pro
-The following rules are to govern the style choices for Agents. See [Agents.md](../AGENTS.md) for detailed configurations.
+The following rules govern style choices for UI and visual design.
## Library
diff --git a/agents/testing.md b/agents/testing.md
new file mode 100644
index 0000000..fcec05e
--- /dev/null
+++ b/agents/testing.md
@@ -0,0 +1,63 @@
+# Testing & Quality — TimeTracker Pro
+
+## Running Tests
+
+```bash
+# Unit tests
+npm run test
+
+# Linting
+npm run lint
+
+# Type checking (via build)
+npm run build
+```
+
+---
+
+## Manual Testing Checklist
+
+**Before submitting any change:**
+
+- [ ] Test in guest mode (no authentication)
+- [ ] Test in authenticated mode
+- [ ] Test on mobile viewport
+- [ ] Test data persistence (refresh page)
+- [ ] Test export/import functionality if relevant
+- [ ] Verify no console errors
+- [ ] Check responsive design
+
+---
+
+## PWA-Specific Testing
+
+- [ ] Service worker registers successfully (DevTools → Application → Service Workers)
+- [ ] App works offline (DevTools → Network → Offline)
+- [ ] Install prompt appears (wait 30 seconds or test manually)
+- [ ] App installs correctly on desktop (Chrome/Edge)
+- [ ] Bottom navigation visible on mobile viewports
+- [ ] Touch targets are large enough (44×44px minimum)
+- [ ] Manifest loads without errors (DevTools → Application → Manifest)
+- [ ] Update notification works when service worker updates
+
+---
+
+## Code Quality Requirements
+
+1. **All lint errors must be fixed** before committing — run `npm run lint`
+2. **All TypeScript errors must be fixed** before merging — run `npm run build`
+3. **Manual testing** of changed functionality required
+4. **No breaking changes** without documentation
+
+---
+
+## Pre-Commit Checklist
+
+Before every commit, verify:
+
+- [ ] `npm run lint` passes with no errors
+- [ ] `npm run build` passes with no type errors
+- [ ] Tabs (not spaces) used throughout
+- [ ] Double quotes used throughout
+- [ ] `@/` import aliases used (no relative paths)
+- [ ] Changed functionality tested manually
diff --git a/agents/workflow.md b/agents/workflow.md
new file mode 100644
index 0000000..588931b
--- /dev/null
+++ b/agents/workflow.md
@@ -0,0 +1,98 @@
+# Development Workflow — TimeTracker Pro
+
+## Initial Setup
+
+```bash
+# Clone repository
+git clone
+cd TimeTrackerPro
+
+# Install dependencies
+npm install
+
+# Setup environment (optional — for cloud sync)
+cp .env.example .env
+# Edit .env with your Supabase credentials
+
+# Start development server
+npm run dev
+# Opens on http://localhost:8080
+```
+
+## Available Commands
+
+```bash
+# Development
+npm run dev # Start dev server (localhost:8080)
+npm run build # Build for production
+npm run build:dev # Build with development mode
+npm run preview # Preview production build
+
+# Code Quality
+npm run lint # Run ESLint
+npm run test # Run Vitest tests
+
+# Testing Scripts
+npm run test-full-import # Test full CSV import
+npm run test-error-handling # Test CSV error handling
+npm run test-csv-import # Test standard CSV import
+
+# PWA Screenshot Generation
+npm run screenshots:install # Install Playwright browsers (first time only)
+npm run screenshots # Capture PWA screenshots (headless)
+npm run screenshots:headed # Capture screenshots with visible browser
+```
+
+**PWA Screenshot Usage:**
+
+1. `npm run screenshots:install` — Install Playwright browsers (~300MB, one-time)
+2. `npm run dev` — Start dev server (keep running)
+3. `npm run screenshots` — Generate screenshots in new terminal
+4. Screenshots saved to `public/screenshots/`
+
+See `tests/SCREENSHOTS_README.md` for detailed documentation.
+
+---
+
+## Git Workflow
+
+### Branch Naming
+
+- Feature branches: `claude/claude-md--`
+- Always work on designated branch from session instructions
+
+### Commit Messages
+
+```bash
+# Format: :
+# Types: feat, fix, refactor, docs, style, test, chore
+
+git commit -m "feat: add billable category option"
+git commit -m "fix: data recovery issues"
+git commit -m "refactor: improve data service caching"
+```
+
+### Creating Pull Requests
+
+1. **Title Format**: `[TimeTrackerPro] `
+2. **Description**: Clear explanation of changes
+3. **Wait for checks**: Don't merge until all tests pass
+4. **Add labels**: Appropriate PR labels
+5. **See**: `agents/pull_requests.md` for full guidelines
+
+---
+
+## Working with Supabase
+
+### Environment Setup
+
+```bash
+# .env file (never commit this!)
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key
+```
+
+### Database Schema Location
+
+- Schema definitions: `supabase/migrations/`
+- See `docs/SCHEMA_COMPATIBILITY.md` for schema history