From 10f7f04fbc9f4d306e2d2828e13d03c12a45bcd8 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Fri, 12 Jun 2026 16:19:52 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20fix=20bootstrap=20=E2=80=94=20remove=20?= =?UTF-8?q?JWT=20Bearer=20claim;=20add=20mistakes=2016-17;=20add=20pres=5F?= =?UTF-8?q?mgmt=20reading=20entry?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Auth row in stack table wrongly said "JWT Bearer is auto-injected" — this project uses custom headers only (x-aether-api-key + x-account-id, NOT Bearer tokens) - Mistake #16: $ sigil on plain prop value → store_invalid_shape at runtime - Mistake #17: *_json / *_kv_json columns start as null — require ?. and ?? {} guards - Renumbered old #16 (service worker) to #18 - Reading order: added Pres Mgmt module doc pointer Co-Authored-By: Claude Sonnet 4.6 --- .../BOOTSTRAP__AI_Agent_Quickstart.md | 37 ++++++++++++++++++- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/documentation/BOOTSTRAP__AI_Agent_Quickstart.md b/documentation/BOOTSTRAP__AI_Agent_Quickstart.md index f5528548..533d0957 100644 --- a/documentation/BOOTSTRAP__AI_Agent_Quickstart.md +++ b/documentation/BOOTSTRAP__AI_Agent_Quickstart.md @@ -29,7 +29,7 @@ running in Docker. The frontend talks to it exclusively via the V3 REST API. | Editors | CodeMirror 6 (primary), Edra/TipTap (secondary) | | Native | Electron app for onsite launcher (`src/lib/electron/electron_relay.ts`) | | Backend | FastAPI + MariaDB, V3 API (`/v3/crud/`, `/v3/lookup/`) | -| Auth | Custom headers: `x-aether-api-key` + `x-account-id`; JWT Bearer is auto-injected when a session exists | +| Auth | Custom headers only: `x-aether-api-key` + `x-account-id` — **NOT** Bearer tokens | --- @@ -474,7 +474,39 @@ These are real incidents — know them before you start. **Exception — legacy `ae_events__event.ts` encoding:** `ae_events__event.ts` (and `ae_events__event_session.ts`) do NOT use `build_tmp_sort`. They use `priority ? 1 : 0` (priority=true→`'1'`), which requires **descending** sort to put priority items first. `ae_events__event_presentation.ts` DOES use `build_tmp_sort` (it overrides the generic encoding in its `specific_processor`). Do not apply the ascending rule to raw event or session sorts until those modules are migrated to `build_tmp_sort`. -16. **Service worker without `skipWaiting()` + `clients.claim()` silently serves stale code to long-lived tabs** — The default SvelteKit service worker template does NOT include these calls. Without them, a new SW installs in the background but waits in a **"waiting"** state until every tab running the old version is closed before it activates. Users who leave a page open all day (especially IDAA members in the Novi iframe on idaa.org) run old buggy JS indefinitely after a fix is deployed. +16. **`$` sigil on a plain prop value → `store_invalid_shape` at runtime** — when a parent passes + `prop={resolved_value}`, the child receives a plain JS value. Using `$prop` inside the child + tries to subscribe to it as a Svelte store and throws `store_invalid_shape: X is not a store + with a subscribe method`. This often happens in files migrated from Svelte 4 where `$lq__*` + usage was correct for the old store-subscription pattern. In Svelte 5, props are plain values: + ```svelte + + {$lq__event_session_obj?.name} + + + {lq__event_session_obj?.name} + ``` + Also note: `PersistedState` stores (events module) use `.current` access, never the `$` sigil. + +17. **`*_json` / `*_kv_json` DB columns start as `null`** — JSON blob columns (`cfg_json`, + `data_json`, `poc_kv_json`, etc.) are `null` in the database until first written. Two failure + modes: + - **Read crash:** `obj.poc_kv_json[poc_type]` throws `TypeError: can't access property "X", + poc_kv_json is null`. Fix: always use optional chaining: `obj.poc_kv_json?.[poc_type]`. + - **Write crash:** spreading `null` — `{ ...obj.poc_kv_json }` throws. Fix: initialize with + `{ ...(obj.poc_kv_json ?? {}) }` before writing any nested keys. + ```ts + // ✅ Safe read + const bio_updated = obj.poc_kv_json?.[poc_type]?.biography_updated_on; + + // ✅ Safe write + const kv = { ...(obj.poc_kv_json ?? {}) }; + if (!kv[poc_type]) kv[poc_type] = {}; + kv[poc_type]['biography'] = new_value; + await update_obj({ data_kv: { poc_kv_json: kv } }); + ``` + +18. **Service worker without `skipWaiting()` + `clients.claim()` silently serves stale code to long-lived tabs** — The default SvelteKit service worker template does NOT include these calls. Without them, a new SW installs in the background but waits in a **"waiting"** state until every tab running the old version is closed before it activates. Users who leave a page open all day (especially IDAA members in the Novi iframe on idaa.org) run old buggy JS indefinitely after a fix is deployed. **Symptom that should trigger this check:** Bug reports from users that developers cannot reproduce. Developers constantly refresh and open/close tabs — the new SW activates immediately for them. End users with persistent tabs never get it. @@ -536,4 +568,5 @@ Start here, then go deeper as needed: | Electron / native launcher | `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` | | Store migration plan | `documentation/PROJECT__Stores_Svelte5_Migration.md` | | Exhibitor Leads module | `documentation/MODULE__AE_Events_Exhibitor_Leads.md` | +| Presentation Management module | `documentation/PROJECT__AE_Events_PressMgmt_Config_Cleanup.md` | | Naming conventions | `documentation/AE__Naming_Conventions.md` |