epic: M2 Home AI Agent Refinement

* test: add E2E tests for critical homeMaker cross-service flows (#64)

Adds Playwright E2E tests covering four critical integration flows:
1. Sensor lifecycle: register → report reading → query history
2. Maintenance completion: create task → complete → verify XP awarded
3. Inventory + sensor: add asset → link sensor → verify readings
4. Gamification milestone: complete task → achievement unlocked

Tests use API-level requests (no UI interaction required) and support
both AUTOMAKER_AUTO_LOGIN dev mode and API key auth for CI environments.
All four tests pass against the live dev server.



* feat: add home research mode agent and research-first board task UX

- Add `createHomeResearchAgent()` to agent-definitions.ts with WebSearch/WebFetch tools;
  produces structured reports (overview, top options, pros/cons, price ranges, recommendation)
  and is explicitly bounded from writing code or modifying files
- Add `getHomeResearcherPrompt()` in libs/prompts/src/agents/home-researcher.ts and
  export it from the agents barrel
- Extend `featureType` union in libs/types/src/feature.ts to include 'research' alongside
  'code' and 'content'
- Update add-feature-dialog to default new tasks to 'research' type with a task type
  selector (Research vs Code) and research-specific description placeholder examples



---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mabry1985

.automaker/actionable-items.json.corrupted.1773621596916

@@ -0,0 +1,55 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "b2ebddbf-6389-49c2-9bf3-2a5f973c0a44",
+      "actionType": "notification",
+      "priority": "low",
+      "title": "Feature Completed",
+      "message": "\"Update all protoLabs Studio UI references to homeMaker\" completed successfully.",
+      "createdAt": "2026-03-15T22:32:03.914Z",
+      "status": "pending",
+      "actionPayload": {
+        "featureId": "feature-1773613295974-iq45l5rgd",
+        "notificationId": "651ad0e4-3ca2-489d-acaa-2370fdd4301b"
+      },
+      "projectPath": "/Users/kj/dev/homeMaker",
+      "read": false,
+      "category": "notifications"
+    },
+    {
+      "id": "9eaf5d52-e056-45a8-94f2-2e5be4c1cbe8",
+      "actionType": "notification",
+      "priority": "low",
+      "title": "Feature Verified",
+      "message": "\"Build vendor view components\" has been verified and is complete.",
+      "createdAt": "2026-03-15T22:47:23.233Z",
+      "status": "pending",
+      "actionPayload": {
+        "featureId": "feature-1773613295979-nly7p4xuc",
+        "notificationId": "ad42cb18-0162-40b9-b519-b00f48694b32"
+      },
+      "projectPath": "/Users/kj/dev/homeMaker",
+      "read": false,
+      "category": "notifications"
+    },
+    {
+      "id": "fa923e3f-58d7-4600-89d1-83e4e7950740",
+      "actionType": "notification",
+      "priority": "low",
+      "title": "Feature Completed",
+      "message": "\"Build HA WebSocket client service\" completed successfully.",
+      "createdAt": "2026-03-15T23:06:20.991Z",
+      "status": "pending",
+      "actionPayload": {
+        "featureId": "feature-1773613295982-6wbdl8mmw",
+        "notificationId": "a94cb203-e0d9-4c1d-8fb6-0f560b5361c1"
+      },
+      "projectPath": "/Users/kj/dev/homeMaker",
+      "read": false,
+      "category": "notifications"
+    }
+  ]
+}   }
+  ]
+}

.automaker/memory/api.md

@@ -0,0 +1,52 @@
+---
+tags: [api]
+summary: api implementation decisions and patterns
+relevantTo: [api]
+importance: 0.7
+relatedFiles: []
+usageStats:
+  loaded: 9
+  referenced: 8
+  successfulFeatures: 8
+---
+# api
+
+#### [Gotcha] HA WebSocket protocol requires strict message ordering: auth handshake must complete (auth_ok received) before subscribe_events or get_states calls. Messages sent before auth_ok are silently ignored. (2026-03-15)
+- **Situation:** Implementing HA WebSocket client connection flow
+- **Root cause:** HA's WebSocket server enforces authentication state before processing subscriptions. This is a protocol constraint, not a performance optimization.
+- **How to avoid:** Requires sequential message sending (simpler correctness logic) vs potential throughput loss (negligible in practice since auth is < 100ms)
+
+#### [Gotcha] get_states must be called after auth_ok to fetch initial entity states. Subscribing to state_changed events alone does not provide initial state of existing entities. (2026-03-15)
+- **Situation:** Newly discovered HA entities have no state value until their first state_changed event after subscription
+- **Root cause:** Event subscriptions only catch future changes. Existing entity state is never pushed; it must be explicitly requested via get_states. Without this, entities registered from HA remain in unknown state until they change.
+- **How to avoid:** Adds one extra message (get_states) per connection, but guarantees complete initial state coverage. Trade-off is negligible (typically < 1KB response)
+
+#### [Pattern] Initial state fetch before event subscription: fetch current state for all selected entities on connect, then subscribe to future changes (2026-03-15)
+- **Problem solved:** Event subscription alone provides only future state changes, missing the current state at connection time
+- **Why this works:** Prevents readings from being undefined/stale between connect and first change event; ensures consistency
+- **Trade-offs:** Slightly larger initial payload, but guarantees complete state picture from start
+
+#### [Pattern] Distinct error handling: auth errors fail permanently without retry; network errors retry with exponential backoff (2026-03-15)
+- **Problem solved:** Invalid token indicates configuration error; network error indicates transient connectivity issue
+- **Why this works:** Prevents log spam and resource waste on unrecoverable auth failures while maintaining resilience to temporary outages
+- **Trade-offs:** More complex error classification code, but appropriate resource usage for different failure types
+
+#### [Gotcha] POST /api/maintenance/:id/complete returns nested structure `{ data: { schedule, completion } }` not flat `{ data: completion }` (2026-03-16)
+- **Situation:** Completion endpoint responds with both the updated schedule and the completion record in data object
+- **Root cause:** API design choice to provide related context (schedule) alongside the completion result in single response
+- **How to avoid:** One request gives more context; clients must dig deeper into response structure
+
+#### [Gotcha] Achievement data uses different field names across endpoints: catalog uses `earned`/`unlockedAt`, profile uses array of `{id, unlockedAt, seen}` (2026-03-16)
+- **Situation:** GET /api/gamification/achievements (catalog) vs data within GET /api/gamification/profile (achievements array) have different structures
+- **Root cause:** Profile endpoint optimized for quick access (array of earned achievements only); catalog endpoint shows full achievement metadata
+- **How to avoid:** Reduces profile payload size but requires tests/clients to understand multiple representations of achievement state
+
+#### [Gotcha] Gamification profile uses `xp` field (not `totalXp`); field naming inconsistency between endpoints requires explicit discovery (2026-03-16)
+- **Situation:** Expected `totalXp` based on common naming pattern; actual API uses abbreviated `xp`
+- **Root cause:** API payload optimization decision; shorter field names reduce response size at cost of less descriptive naming
+- **How to avoid:** Smaller JSON payloads; less self-documenting field names requiring API documentation or discovery
+
+#### [Pattern] Agent factory pattern (createHomeResearchAgent) instantiates with specific tools (WebSearch + WebFetch only) and model (sonnet) rather than parameterizing them (2026-03-16)
+- **Problem solved:** Agent creation follows pattern used by Ava/PM/LE agents; each has fixed toolset and model
+- **Why this works:** Hard-coded tool/model bindings enforce explicit capability boundaries at creation time — prevents accidental capability mixing and makes agent behavior predictable and reviewable
+- **Trade-offs:** Rigid per-agent design makes each agent clear but requires new factory for new capability combinations; parameterization is more flexible but harder to audit