docs: restructure bootstrap, add module references, and normalize docs

documentation/REFERENCE__Common_Agent_Mistakes.md

@@ -0,0 +1,171 @@
+# Aether SvelteKit — Common Agent Mistakes (Reference)
+
+This is the detailed mistake catalog referenced by `BOOTSTRAP__AI_Agent_Quickstart.md`.
+Use it as a troubleshooting and prevention guide, not as first-pass onboarding.
+
+Review policy: balanced curation.
+- Keep: high-impact or recurring mistakes.
+- Archive: one-off or lower-signal historical incidents.
+
+---
+
+## Active Mistakes (Curated)
+
+### 1) IDAA content exposed publicly
+**Impact:** Sev-1 privacy breach.
+
+**What happened:** A route guard was removed on an IDAA BB route.
+
+**Rule:** All `/idaa/` content is private. Never remove auth guards on IDAA routes.
+
+**Verify:** Confirm route/layout auth checks still gate all IDAA pages before data load.
+
+### 2) Object ID included in PATCH body (`data_kv`)
+**Impact:** 400 errors (`Unknown column in SET`).
+
+**What happened:** Object ID (for URL path) was also sent in `data_kv`.
+
+**Rule:** Keep object ID in the URL only; `data_kv` contains changed fields only.
+
+**Verify:** In `update_ae_obj__*` calls, confirm `data_kv` excludes `*_id` fields.
+
+### 3) Coarse-store `$effect` reactivity loops
+**Impact:** repeated fetches, duplicate side effects, noisy state churn.
+
+**What happened:** `$effect` read fields from `svelte-persisted-store` stores (`$ae_loc`, `$idaa_loc`), subscribing to entire store.
+
+**Rule:** Be minimal about coarse-store reads in `$effect`; move transient triggers to session state and keep duplicate guards in executor paths.
+
+**Verify:** Check effect dependencies and ensure unrelated writes do not retrigger critical effects.
+
+### 4) Dexie `.get()` used with string object ID
+**Impact:** false misses (`undefined`) despite cached data.
+
+**What happened:** `.get()` queried primary key `id`, but V3 records rely on object string IDs (e.g. `person_id`).
+
+**Rule:** Use `.where('<obj_id>').equals(value).first()` for object lookups.
+
+**Verify:** Search for `.get(` against object IDs and replace with indexed `where` query.
+
+### 5) Misunderstanding `$effect` and auth gates
+**Impact:** security confusion and wrong mitigations.
+
+**What happened:** Child-component `$effect` blocks were treated as possible bypass vectors.
+
+**Rule:** Child effects cannot bypass parent layout auth gates; pre-gate risk is in universal `+page.ts` / `+layout.ts` loads and prefetch.
+
+**Verify:** Keep private-module data loads out of universal load files unless explicitly authenticated.
+
+### 6) Using query `key` like `x-no-account-id: bypass`
+**Impact:** dropped `x-account-id`, unexpected 403 on scoped requests.
+
+**What happened:** `key` was treated as bypass intent and account context was stripped.
+
+**Rule:** `key` is business data, not bypass intent. Only explicit `x-no-account-id: bypass` drops account context.
+
+**Verify:** Check request headers for account-scoped calls and preserve `x-account-id` unless bypass is explicitly required.
+
+### 7) Pre-stringifying `*_json` before API wrappers
+**Impact:** double encoding risk and inconsistent payloads.
+
+**What happened:** Callers stringified JSON fields manually before wrapper serialization.
+
+**Rule:** Pass plain objects for `*_json` fields; wrappers handle serialization.
+
+**Verify:** Remove `JSON.stringify(...)` around `cfg_json`, `data_json`, and related fields before wrapper calls.
+
+### 8) Broad Dexie result windows silently clipped
+**Impact:** “All” views show fewer rows than narrower filters.
+
+**What happened:** page limits or API revalidation replaced local broad result sets.
+
+**Rule:** For empty text search, local IDB result set should drive visible results; server refresh updates cache without shrinking display.
+
+**Verify:** Compare empty-search “All” view vs narrower filter counts and inspect revalidation merge behavior.
+
+### 9) Missing `IDB_CONTENT_VERSIONS` bump after `properties_to_save` changes
+**Impact:** long-lived stale cache bugs (e.g. IDAA “no meetings found”).
+
+**What happened:** shape persisted in IDB changed, but table content version was not bumped.
+
+**Rule:** When persisted object shape/behavior changes, bump matching `IDB_CONTENT_VERSIONS` entry in `src/lib/stores/store_versions.ts`.
+
+**Verify:** For relevant object changes, confirm both version increment and table-wiring path are in the same change set.
+
+### 10) API retry loop broken by returning transient errors
+**Impact:** no retries on common WiFi/network blips.
+
+**What happened:** transient error paths returned `false` instead of throwing, bypassing retry loop.
+
+**Rule:** Keep retry classification strict:
+- transient `TypeError` and timeout aborts -> `throw`
+- navigation abort -> `return false`
+- deterministic 4xx -> `return false`
+- 5xx -> `throw`
+
+**Verify:** Simulate transient network failure and confirm retry/backoff attempts occur.
+
+### 11) Account-scoped trigger fired before bootstrap account is ready
+**Impact:** wrong-account API fetch and cached cross-account data.
+
+**What happened:** trigger effects ran before account bootstrap settled, reading stale context.
+
+**Rule:** Gate account-scoped load triggers on `$slct.account_id` readiness, not persisted `$ae_loc.account_id`.
+
+**Verify:** Ensure trigger effects require browser + account_id + api readiness before fetch trigger assignment.
+
+### 12) `tmp_sort_*` comparator direction inverted
+**Impact:** priority ordering reversed.
+
+**What happened:** descending comparator used with `build_tmp_sort` encoding (which expects ascending).
+
+**Rule:** Use ascending compare for `build_tmp_sort` outputs, with documented exceptions for legacy encodings.
+
+**Verify:** Confirm comparator direction per module encoding and avoid `collection.reverse().sortBy(...)` assumptions.
+
+### 13) `$` sigil used on plain prop values
+**Impact:** runtime `store_invalid_shape` errors.
+
+**What happened:** child component treated normal prop values as Svelte stores.
+
+**Rule:** In Svelte 5, props passed as values are plain values. Do not use `$prop` unless prop is an actual store.
+
+**Verify:** In migrated components, replace `$lq__...` prop reads with plain `lq__...` prop access.
+
+### 14) Null JSON blob fields not guarded
+**Impact:** read/write crashes (`cannot access property of null`).
+
+**What happened:** `*_json` / `*_kv_json` DB columns were null before first write.
+
+**Rule:** Use optional chaining for reads and `?? {}` initialization before object spread writes.
+
+**Verify:** Audit reads/writes for `cfg_json`, `data_json`, `poc_kv_json`, and similar nullable blob fields.
+
+### 15) Service worker stale-tab behavior misunderstood
+**Impact:** users run old code longer than expected, “can’t reproduce” bug reports.
+
+**What happened:** deployment assumptions ignored SW activation lifecycle.
+
+**Rule:** Keep SW activation behavior explicit (`skipWaiting`, `clients.claim`) and evaluate trade-offs for session-heavy flows.
+
+**Verify:** After deploy, validate that long-lived tabs pick up new SW behavior as intended.
+
+---
+
+## Archived Historical Items (Pruned)
+
+These are retained as project memory but removed from the active mistake list because they are lower-signal or one-off.
+
+1. **Bad `.d.ts` module declaration masking errors** (important incident, low recurrence recently).
+2. **Launcher `file_purpose == 'admin'` filtering gap** (specific historical enum-audit miss).
+3. **Deleting files with `rm`** (still a workflow rule, now maintained in bootstrap File Safety section rather than as a mistake entry).
+
+---
+
+## Related Docs
+
+- `documentation/BOOTSTRAP__AI_Agent_Quickstart.md`
+- `documentation/TODO__Agents.md`
+- `documentation/GUIDE__SvelteKit2_Svelte5_DexieJS.md`
+- `documentation/GUIDE__AE_API_V3_for_Frontend.md`
+- `documentation/PROJECT__Stores_Svelte5_Migration.md`