Update docs, README, and CLAUDE.md for full product vision

.automaker/context/CLAUDE.md

@@ -1,65 +1,61 @@
-# homeMaker — Agent Context
+# homeMaker Agent Context
 
-## What This Is
+## What Exists
 
-A domestic home management hub. The AI agent pipeline, board, and auto-mode are CORE FEATURES — they help manage home projects, research purchases, plan renovations, and track maintenance schedules.
+All modules currently implemented in homeMaker:
 
-## What Agents Do Here
+- **Board** — Kanban task tracking for house projects (backlog -> done)
+- **Calendar** — CRUD event management for household schedules
+- **Sensors** — IoT device registry, real-time readings, history persistence, HA integration
+- **Budget** — Income/expense tracking, categories, monthly summaries
+- **Vault** — AES-256-GCM encrypted secrets storage
+- **Inventory** — Home asset tracking, warranties, valuations, sensor linking
+- **Maintenance** — Recurring obligation scheduling, completion history, vendor linking
+- **Vendors** — Service provider directory, trade categories, ratings
+- **Gamification** — Home Health Score (0-100), XP/levels, 30 achievements, AI quests, streaks
 
-**You are helping manage a household, not building software.** Tasks on the board represent home projects: repairs, renovations, purchases, and maintenance — not code changes.
+## Gamification Awareness
 
-Default mode is **research-and-report**: gather information, summarize findings, make recommendations. Do NOT write code unless the task explicitly says to implement something.
+Your implementation work earns XP for the homemaker and can trigger achievements. The gamification system tracks:
 
-Typical task types:
+- **XP sources**: completing maintenance tasks, adding inventory items, logging budget entries, unlocking vault items, keeping sensors online
+- **Achievements**: first maintenance completed, inventory milestones, budget streaks, sensor uptime awards
+- **Home Health Score**: calculated across 4 pillars — Maintenance (30%), Sensors (25%), Budget (25%), Inventory (20%)
 
-- **Research**: Compare products (smart thermostats, appliances, tools), find contractors, look up how-to guides, estimate costs. Use web search tools for current pricing and reviews.
-- **Plan**: Break down a renovation into phases with dependencies and timelines
-- **Maintenance tracking**: Recurring items — HVAC filter (every 90 days), gutter cleaning (twice/year), lawn care schedule
-- **Organize**: Summarize findings into actionable recommendations with pros/cons
+When you add or modify features that interact with these modules, call `gamificationService.awardXp()` for relevant user actions. Do NOT write XP directly to the database.
 
-When **is** code appropriate:
+## Shared Database Pattern
 
-- The task explicitly says "build", "implement", "add UI for", "create API for", etc.
-- You are adding a new homeMaker feature (new view, new backend service, new sensor integration)
+All services share a single SQLite database (`homemaker.db`) with WAL mode and foreign keys enabled. Services receive the `Database` instance via constructor injection from `ServiceContainer`.
 
-## What Exists (reuse these)
+```typescript
+// Pattern for service constructors
+constructor(private db: Database) {
+  this.db.exec(`CREATE TABLE IF NOT EXISTS my_table (...)`);
+}
+```
 
-- **Board/Kanban** — tracks house projects as tasks with status, priority, dependencies
-- **Auto-mode** — agents pick up tasks from the board and execute them autonomously
-- **Sensor Registry** (`apps/server/src/services/sensor-registry-service.ts`) — IoT device data collection
-- **Context Aggregator** (`apps/server/src/services/context-aggregator.ts`) — presence detection from sensors
-- **Calendar view** (`apps/ui/src/components/views/calendar-view/`) — home schedule events
-- **Todo** (`apps/ui/src/components/views/todo-view/`) — task lists
-- **Notes** (`apps/ui/src/components/views/notes-view/`) — household notes
-- **Chat (Ava)** — conversational AI assistant for the household
-- **Event system** (`apps/server/src/lib/events.ts`) — real-time WebSocket push
-
-## Tech Stack
-
-- **Frontend**: React 19, Vite 7, TanStack Router, Zustand 5, Tailwind CSS 4, Radix UI
-- **Backend**: Express 5, SQLite, WebSocket, Claude Agent SDK
-- **Shared libs**: `@protolabsai/types`, `@protolabsai/utils`, `@protolabsai/ui`, `@protolabsai/prompts`
+Do NOT create standalone SQLite files per service. Always use the shared DB from `ServiceContainer`.
 
 ## Adding New Backend Modules
 
-Follow the sensor registry pattern:
+Follow the sensor registry pattern, using the shared DB:
 
 1. Define types in `libs/types/src/`
-2. Create service in `apps/server/src/services/`
+2. Create service in `apps/server/src/services/` — accept `Database` via constructor
 3. Create routes in `apps/server/src/routes/<module>/`
 4. Wire into `apps/server/src/server/routes.ts`
 5. Add to `ServiceContainer` in `apps/server/src/server/services.ts`
 
 ## Adding New UI Views
 
-1. Create view in `apps/ui/src/components/views/<module>-view/`
-2. Add route file `apps/ui/src/routes/<module>.tsx`
-3. Add nav item in `apps/ui/src/components/layout/sidebar/hooks/use-navigation.ts`
+After creating the view component and route file, add to sidebar navigation (`apps/ui/src/components/layout/sidebar/hooks/use-navigation.ts`). Current nav items include:
+board, calendar, sensors, inventory, vendors, maintenance, budget, vault, profile
 
-## Security Rules
+## Key Invariants
 
-- Secrets are encrypted AES-256-GCM at rest (never store plaintext)
-- Use the existing `apps/server/src/lib/auth.ts` for API key validation
-- Rate limit all write endpoints
-- Never log secret values, only IDs and metadata
-- Tailscale handles network-level auth — no login UI needed
+- Gamification: all XP awards go through `gamificationService.awardXp()` — never direct DB writes
+- Inventory: amounts in cents (integer), never floating point dollars
+- Maintenance: `intervalDays` is always a positive integer, `nextDueAt` auto-calculated
+- Vendors: phone numbers stored as strings (preserve formatting)
+- Home Health Score: always recalculate after data mutations, never cache stale scores

.automaker/context/coding-rules.md

@@ -37,3 +37,33 @@
 - External IoT devices POST to `POST /api/sensors/report` with their registered ID
 - Register on startup via `POST /api/sensors/register`
 - Use WebSocket events (`sensor:data-received`) for real-time UI updates
+
+## Module-Specific Rules
+
+### Gamification
+
+- All XP awards MUST go through `gamificationService.awardXp()` — never write XP directly to the database
+- Always emit `gamification:xp-gained` and `gamification:achievement-unlocked` events via the service
+- Home Health Score must be recalculated after any data mutation in Inventory, Maintenance, Sensors, or Budget modules
+
+### Inventory
+
+- Monetary amounts (purchase price, current value) stored as integers in cents — never floating point dollars
+- Always link sensor IDs by reference; do not embed sensor data in inventory records
+
+### Maintenance
+
+- `intervalDays` must always be a positive integer (>0)
+- `nextDueAt` is auto-calculated from `lastCompletedAt + intervalDays` — never store user-supplied values directly
+- Link to vendors by ID only; do not embed vendor data in maintenance records
+
+### Vendors
+
+- Phone numbers stored as strings to preserve formatting (e.g., "(555) 123-4567")
+- Trade categories use a fixed enum — do not allow free-form category creation
+
+### Shared Database
+
+- All services use the shared `homemaker.db` from `ServiceContainer` — do NOT create standalone SQLite files
+- Use WAL mode pragma in service initialization: `db.exec('PRAGMA journal_mode=WAL')`
+- Enable foreign keys: `db.exec('PRAGMA foreign_keys=ON')`

CLAUDE.md

@@ -18,14 +18,15 @@ The AI agent pipeline (board, auto-mode, Claude Agent SDK, worktrees) is **core
 ## Brand Identity
 
 - **homeMaker** = the product name (always camelCase)
-- **@protolabsai/*** = internal package names (preserved from protoLabs Studio lineage, do NOT rename)
+- **@protolabsai/\*** = internal package names (preserved from protoLabs Studio lineage, do NOT rename)
 - **.automaker/** = internal directory for board data, context files, features (preserved, do NOT rename)
 
 ## Git Workflow
 
 Feature branches PR to `main`. Keep it simple — no staging/promotion pipeline needed for a home app.
 
 **Rules:**
+
 - Never push directly to `main`. Always use a PR.
 - Before committing, run `git status` and verify only intended files are staged.
 - `.automaker/memory/` files are updated by agents. Include memory changes in commits alongside related code changes.
@@ -80,6 +81,10 @@ homeMaker/
     └── ...
 ```
 
+### Shared Database
+
+All server services share a single `homemaker.db` (SQLite, WAL mode, foreign keys enabled). Services receive the DB connection via constructor injection from `ServiceContainer`.
+
 ### Key Technologies
 
 - **Frontend**: React 19, Vite 7, TanStack Router, Zustand 5, Tailwind CSS 4
@@ -90,8 +95,8 @@ homeMaker/
 
 The server (`apps/server/src/`) follows a modular pattern:
 
-- `routes/` - Express route handlers organized by domain (sensors, budget, vault, calendar, etc.)
-- `services/` - Business logic (SensorRegistryService, BudgetService, VaultService, AgentService, AutoModeService, etc.)
+- `routes/` - Express route handlers organized by domain (sensors, budget, vault, calendar, inventory, maintenance, vendors, gamification, etc.)
+- `services/` - Business logic (SensorRegistryService, BudgetService, VaultService, InventoryService, MaintenanceService, VendorService, GamificationService, QuestGeneratorService, WeatherService, AgentService, AutoModeService, etc.)
 - `providers/` - AI provider abstraction (Claude via Agent SDK)
 - `lib/` - Utilities (events, auth, crypto)
 - `server/` - Bootstrap modules (middleware, services, wiring, routes, startup, shutdown)
@@ -101,7 +106,7 @@ The server (`apps/server/src/`) follows a modular pattern:
 The UI (`apps/ui/src/`) uses:
 
 - `routes/` - TanStack Router file-based routing
-- `components/views/` - Main view components (board, calendar, sensors, budget, vault, etc.)
+- `components/views/` - Main view components (board, calendar, sensors, budget, vault, inventory, maintenance, vendors, profile, etc.)
 - `store/` - Zustand stores with persistence
 - `hooks/` - Custom React hooks
 - `lib/` - Utilities and API client
@@ -128,12 +133,45 @@ The UI (`apps/ui/src/`) uses:
 
 The Kanban board from protoLabs Studio, repurposed for tracking house projects. Tasks flow through: backlog -> in_progress -> review -> done (with blocked as an escape state).
 
+### Inventory
+
+`apps/server/src/services/inventory-service.ts` — Tracks home assets, warranties, and valuations with sensor linking. Monetary amounts stored as integers in cents.
+
+- Types: `InventoryItem` in `libs/types/src/inventory.ts`
+- Routes: `apps/server/src/routes/inventory/`
+- Events: `inventory:item-created`, `inventory:item-updated`
+
+### Maintenance
+
+`apps/server/src/services/maintenance-service.ts` — Recurring obligations with auto-calculated due dates, completion history, and vendor linking. `nextDueAt` computed from `lastCompletedAt + intervalDays`.
+
+- Types: `MaintenanceTask` in `libs/types/src/maintenance.ts`
+- Routes: `apps/server/src/routes/maintenance/`
+- Events: `maintenance:task-completed`, `maintenance:task-overdue`
+
+### Vendors
+
+`apps/server/src/services/vendor-service.ts` — Service provider directory with trade categories, ratings, and linked assets. Phone numbers stored as strings to preserve formatting.
+
+- Types: `Vendor` in `libs/types/src/vendor.ts`
+- Routes: `apps/server/src/routes/vendors/`
+
+### Gamification
+
+`apps/server/src/services/gamification-service.ts` — Home Health Score (0--100), XP/levels (10 tiers), 30 achievements across 6 categories, AI quests, and streaks.
+
+- Types: `GamificationProfile`, `Achievement`, `Quest` in `libs/types/src/gamification.ts`
+- Routes: `apps/server/src/routes/gamification/`
+- Quest generation: `apps/server/src/services/quest-generator-service.ts`
+- Events: see "Gamification Events" below
+
 ## Import Conventions
 
 Always import from shared packages:
 
 ```typescript
 import type { Feature, SensorConfig } from '@protolabsai/types';
+import type { GamificationProfile, Achievement, Quest } from '@protolabsai/types';
 import { createLogger } from '@protolabsai/utils';
 import { getFeatureDir } from '@protolabsai/platform';
 ```
@@ -143,6 +181,7 @@ import { getFeatureDir } from '@protolabsai/platform';
 ### Adding a New Backend Module
 
 Follow the sensor registry pattern:
+
 1. Define types in `libs/types/src/`
 2. Create service in `apps/server/src/services/`
 3. Create routes in `apps/server/src/routes/<module>/`
@@ -159,6 +198,17 @@ Follow the sensor registry pattern:
 
 All server operations emit events that stream to the frontend via WebSocket. Events are created using `createEventEmitter()` from `lib/events.ts`.
 
+#### Gamification Events
+
+```
+gamification:xp-gained             — XP awarded (source, amount, total)
+gamification:achievement-unlocked  — Achievement unlocked (achievement definition)
+gamification:level-up              — Level milestone crossed (new level, tier)
+gamification:health-score-updated  — Home Health Score recalculated (score, pillars)
+gamification:quest-generated       — New AI quest available
+gamification:streak-updated        — Streak count changed
+```
+
 ### Feature Status System
 
 5-status system for all board tasks:
@@ -175,31 +225,36 @@ Project-specific rules are stored in `.automaker/context/` and automatically loa
 
 ### Model Hierarchy for Auto-Mode
 
-| Model      | Use Case                        | Triggered By                        |
-| ---------- | ------------------------------- | ----------------------------------- |
-| **Opus**   | Complex research, architecture  | `complexity: 'architectural'`       |
-| **Sonnet** | Standard tasks (default)        | `complexity: 'medium'` or `'large'` |
-| **Haiku**  | Quick lookups, simple tasks     | `complexity: 'small'`               |
+| Model      | Use Case                       | Triggered By                        |
+| ---------- | ------------------------------ | ----------------------------------- |
+| **Opus**   | Complex research, architecture | `complexity: 'architectural'`       |
+| **Sonnet** | Standard tasks (default)       | `complexity: 'medium'` or `'large'` |
+| **Haiku**  | Quick lookups, simple tasks    | `complexity: 'small'`               |
 
 ### Feature Flags
 
 Single source of truth: `DEFAULT_FEATURE_FLAGS` in `libs/types/src/global-settings.ts`. When adding a new flag:
+
 1. Add to `FeatureFlags` interface and set default to `false` in `DEFAULT_FEATURE_FLAGS`
 2. Add label in `developer-section.tsx` `FEATURE_FLAG_LABELS`
 3. Add server-side guard: `featureFlags?.yourFlag ?? false`
 
 ## Environment Variables
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `ANTHROPIC_API_KEY` | Yes | Anthropic API key for AI agents |
-| `HOMEMAKER_VAULT_KEY` | For vault | 64-char hex key for AES-256-GCM secrets encryption |
-| `AUTOMAKER_API_KEY` | Optional | API key for server authentication |
-| `HOST` | No | Host to bind to (default: 0.0.0.0) |
-| `PORT` | No | Server port (default: 3008) |
-| `DATA_DIR` | No | Data storage directory (default: ./data) |
-| `AUTOMAKER_MOCK_AGENT` | No | Enable mock agent mode for CI testing |
-| `GITHUB_TOKEN` | Optional | For GitHub operations |
+| Variable                        | Required  | Description                                        |
+| ------------------------------- | --------- | -------------------------------------------------- |
+| `ANTHROPIC_API_KEY`             | Yes       | Anthropic API key for AI agents                    |
+| `HOMEMAKER_VAULT_KEY`           | For vault | 64-char hex key for AES-256-GCM secrets encryption |
+| `AUTOMAKER_API_KEY`             | Optional  | API key for server authentication                  |
+| `HOST`                          | No        | Host to bind to (default: 0.0.0.0)                 |
+| `PORT`                          | No        | Server port (default: 3008)                        |
+| `DATA_DIR`                      | No        | Data storage directory (default: ./data)           |
+| `AUTOMAKER_MOCK_AGENT`          | No        | Enable mock agent mode for CI testing              |
+| `GITHUB_TOKEN`                  | Optional  | For GitHub operations                              |
+| `OPENWEATHERMAP_API_KEY`        | Optional  | Weather widget API key                             |
+| `OPENWEATHERMAP_LAT`            | No        | Home latitude for weather                          |
+| `OPENWEATHERMAP_LON`            | No        | Home longitude for weather                         |
+| `SENSOR_HISTORY_RETENTION_DAYS` | No        | Days of sensor history (default: 30)               |
 
 ## Important Guidelines