merge feature/sse-reads: SSE reactivity + claim flow + platform admin

AGENTS.md

@@ -116,13 +116,29 @@ $effect(() => {
 let items = $state(famStore.initialized ? famStore.items : (data.items || []));
 ```
 
-**Form action callbacks must call `famStore.applyRecord()`:**
-```ts
-// In use:enhance callback:
-famStore.applyRecord('collection_name', record, 'create' | 'update' | 'delete');
+## Update Patterns
+
+Two patterns based on who's acting:
+
+| Pattern | Who | Frequency | Sensitivity | Optimistic? | Auth |
+|---------|-----|-----------|-------------|-------------|------|
+| Direct `fetch` + `memberApi` | Member | High (chore toggles) | None | Yes (instant UI, reconcile on response) | `x-device-token` header |
+| Form action | Admin | Low (CRUD) | High (settings, members) | No — form is server-side, wait for round trip | httpOnly `session` cookie |
+
+**Member direct fetch** — optimistic UI via local state mutation, reconciled on response:
+```svelte
+let completions = $state(data.completions)
+async function toggle(chore) {
+    // optimistic update
+    completions = [...completions, { id: 'optimistic-...', ... }]
+    try {
+        await memberApi.toggleCompletion(token, famId, chore.id, date)
+        // reconcile — remove optimistic, keep server truth
+    } catch { /* revert */ }
+}
 ```
 
-The `famStore` has reactive `$state` properties and an `applyRecord()` method designed for instant UI feedback from form actions. Calling `applyRecord()` mutates the store directly — the UI updates immediately without waiting for PB SSE. The SSE subscription is a backup for multi-user sync only. Do NOT add `$effect` watchers to bridge the gap between form actions and reactive state.
+**Admin form actions** — no optimistic `applyRecord` needed in `use:enhance` callbacks. The form action is a server round trip, and PB SSE pushes the change back through `famStore.handleRealtime()` within milliseconds. The famStore + SSE subscription is the single source of truth for cross-user sync. Do NOT add `$effect` watchers to bridge the gap between form actions and reactive state.
 
 ## UI Component Conventions