chore: final recovery and integration of WIP improvements into ae_app_3x_llm

documentation/CLIENT__IDAA_and_customized_mods.md

@@ -140,6 +140,73 @@ A `novi_verifying` UI state prevents the "Access Denied" screen from flashing du
 }
 ```
 
+## Novi API Integration — How We Use It
+
+This section documents the exact way Aether uses the Novi API for the IDAA integration so future maintainers can recreate the flow.
+
+- **Purpose:** Verify a Novi-provided `uuid` received via iframe URL parameters, obtain a verified name/email from Novi, and upgrade Aether permissions for that session when appropriate.
+
+- **All-or-nothing policy:** If the Novi API key is not configured or the verification call fails, the Novi-based access path is denied. The layout explicitly prevents child routes from rendering while verification is in-flight to avoid flashing "Access Denied".
+
+### Verification Flow (implementation)
+
+1. The IDAA iframe loads Aether pages with a `?uuid=<uuid>&iframe=true` param.
+2. When the `uuid` param is present the IDAA layout performs an authenticated GET against the Novi customers endpoint:
+
+```js
+// simplified
+fetch(`${api_root_url}/customers/${uuid}`, {
+  method: 'GET',
+  headers: { 'Authorization': `Basic ${api_key}` }
+})
+```
+
+3. On success the layout uses the returned JSON to build a display name and normalized email, then writes these values to the IDAA store and marks verification success.
+
+4. The layout then determines a target Novi permission level (`authenticated`, `trusted`, `administrator`) by checking configured UUID lists (`novi_trusted_li`, `novi_admin_li`) and upgrades the Aether session only if the Novi-derived level is higher than the current global level.
+
+5. The layout also resets a few IDAA-specific query defaults (BB filters, etc.) to safe values after verification.
+
+### Key `site_cfg_json` fields and where they are used
+
+- **`novi_idaa_api_key`**: Base64-encoded Basic auth token provided by Novi. Required for the verification request. Accessed in code as `$ae_loc.site_cfg_json.novi_idaa_api_key` and passed in the `Authorization: Basic <key>` header. If missing, Novi-based access is denied.
+
+- **`novi_api_root_url`**: Optional API root (defaults to `https://www.idaa.org/api`). Used to form the verification URL.
+
+- **`novi_admin_li`**: Array of UUIDs treated as administrators for IDAA. Merged into `$idaa_loc.novi_admin_li` during layout initialization and used to set `administrator` level.
+
+- **`novi_trusted_li`**: Array of UUIDs treated as trusted members. Merged into `$idaa_loc.novi_trusted_li` and used to set `trusted` level.
+
+- **`novi_jitsi_mod_li` / `novi_idaa_group_guid_li`**: Lists used to map Jitsi moderator privileges and group GUIDs (where applicable).
+
+- **`novi_bb_base_url`**: (optional) Base URL used to build links for Bulletin Board notification emails.
+
+- **Email config values** (`noreply_email`, `noreply_name`, `admin_email`, `admin_name`): used by functions that send notification emails (BB posts, comments, recovery meetings).
+
+### Stores / runtime fields set by verification
+
+- `$idaa_loc.novi_uuid` — the verified UUID
+- `$idaa_loc.novi_email` — verified email (normalized)
+- `$idaa_loc.novi_full_name` — display name built from Novi fields
+- `$idaa_loc.novi_verified` — boolean flag indicating successful verification
+- `$idaa_loc.novi_admin_li`, `$idaa_loc.novi_trusted_li` — merged lists from site config
+
+These fields are read elsewhere in the IDAA UI to enable flows for verified users (for example: creating meetings, posting comments, or auto-populating contact info in notifications).
+
+### Where in the codebase this runs (examples)
+
+- The Novak UUID verification and permission-upgrade logic is implemented in the IDAA layout: [src/routes/idaa/(idaa)/+layout.svelte](src/routes/idaa/(idaa)/+layout.svelte).
+- UI elements that permit actions for verified Novi users or trusted members check these values. Example: the "Create New Meeting" button allows creation when either the session has `trusted_access` or a `novi_uuid` is present — see [src/routes/idaa/(idaa)/recovery_meetings/ae_idaa_comp__event_obj_qry.svelte](src/routes/idaa/(idaa)/recovery_meetings/ae_idaa_comp__event_obj_qry.svelte).
+
+### Security notes and operational guidance
+
+- The previous implementation leaked `email` and `full_name` via URL params — this was removed because those values are unauthenticated and can be spoofed.
+- The API key is sensitive — keep it only in site config and do not expose it in client-side code or public repositories.
+- The verification request uses Basic auth with the provided `novi_idaa_api_key` (already Base64-encoded by Novi) — treat the token like a password.
+- If Novi changes their customer API shape, update the layout parsing (display name/email normalization) and this documentation.
+
+If you need a compact checklist for re-creating this flow in another integration, ask and I will add a small runbook with exact request/response field mappings.
+
 ### Permission Levels (Ascending)
 | Level | Condition | Access |
 |---|---|---|