docs: mark IDAA Novi P5 (frontend migration) complete (2026-05-19)

Frontend now calls GET /v3/action/idaa/novi_member/{uuid} instead of making a direct browser-to-Novi call. 503 auto-retry also added same session to match the network-error retry behavior. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
docs: add agent bootstrap quickstart and consolidate documentation
2026-05-19 19:41:10 -04:00 · 2026-05-19 18:56:09 -04:00 · 2026-05-19 18:35:01 -04:00
13 changed files with 981 additions and 2 deletions
--- a/app/methods/idaa_novi_verify_methods.py
+++ b/app/methods/idaa_novi_verify_methods.py
@@ -0,0 +1,154 @@
+import datetime
+import json
+import requests
+from typing import Dict, Optional
+
+from app.lib_general import log, logger_reset
+
+IDAA_SITE_ID_RANDOM = '58_gJESdlUh'
+_CACHE_TTL = datetime.timedelta(hours=4)
+
+
+# ── Config ────────────────────────────────────────────────────────────────
+
+@logger_reset
+def _load_idaa_cfg() -> Optional[Dict]:
+    """Load IDAA site cfg_json. Returns parsed dict or None on failure."""
+    from app.methods.site_methods import load_site_obj
+    site = load_site_obj(site_id=IDAA_SITE_ID_RANDOM, model_as_dict=True)
+    if not site:
+        log.error("Could not load IDAA site record (id_random='%s').", IDAA_SITE_ID_RANDOM)
+        return None
+    cfg = site.get('cfg_json')
+    if isinstance(cfg, str):
+        try:
+            cfg = json.loads(cfg)
+        except Exception as e:
+            log.error("Failed to parse IDAA cfg_json: %s", e)
+            return None
+    if not isinstance(cfg, dict):
+        log.error("IDAA cfg_json is not a dict after parsing.")
+        return None
+    return cfg
+
+
+def _cache_key(uuid: str) -> str:
+    return f'idaa:novi_member:{uuid}'
+
+
+# ── Public API ────────────────────────────────────────────────────────────
+
+@logger_reset
+def verify_novi_member(uuid: str) -> Dict:
+    """
+    Proxy GET /customers/{uuid} to Novi AMS and return normalized member data.
+
+    Returns a dict with one of:
+      {'status': 200, 'verified': True,  'full_name': '...', 'email': '...'}
+      {'status': 404, 'reason': '...'}
+      {'status': 429, 'reason': '...'}
+      {'status': 503, 'reason': '...'}
+
+    Redis cache key: idaa:novi_member:{uuid}, TTL 4 hours.
+    Only 200 (verified) results are cached — 404 is never cached.
+    """
+    from app.lib_redis_helpers import redis_client
+
+    cache_key = _cache_key(uuid)
+
+    # ── Cache hit ─────────────────────────────────────────────────────────
+    cached_raw = redis_client.get(cache_key)
+    if cached_raw:
+        try:
+            cached = json.loads(cached_raw)
+            log.info("Novi verify cache hit: %s", uuid)
+            return cached
+        except Exception:
+            pass  # corrupt cache entry — fall through to Novi
+
+    # ── Load credentials ──────────────────────────────────────────────────
+    cfg = _load_idaa_cfg()
+    if not cfg:
+        return {'status': 503, 'reason': 'IDAA site configuration unavailable.'}
+
+    base_url = cfg.get('novi_api_root_url', '').rstrip('/')
+    api_key  = cfg.get('novi_idaa_api_key', '')
+
+    if not base_url or not api_key:
+        log.error("novi_api_root_url or novi_idaa_api_key missing from IDAA cfg_json.")
+        return {'status': 503, 'reason': 'Novi credentials not configured.'}
+
+    headers = {'Authorization': f'Basic {api_key}', 'Accept': 'application/json'}
+
+    # ── Call Novi ─────────────────────────────────────────────────────────
+    try:
+        resp = requests.get(f'{base_url}/customers/{uuid}', headers=headers, timeout=10)
+    except requests.exceptions.ConnectionError as e:
+        log.error("Novi unreachable: %s", e)
+        return {'status': 503, 'reason': 'Novi API unreachable.'}
+    except requests.exceptions.Timeout:
+        log.error("Novi request timed out for UUID %s", uuid)
+        return {'status': 503, 'reason': 'Novi API timed out.'}
+    except Exception as e:
+        log.exception("Unexpected error calling Novi for UUID %s: %s", uuid, e)
+        return {'status': 503, 'reason': 'Unexpected error contacting Novi.'}
+
+    if resp.status_code == 429:
+        log.warning("Novi rate limit hit for UUID %s", uuid)
+        return {'status': 429, 'reason': 'Novi rate limit exceeded. Try again shortly.'}
+
+    if resp.status_code >= 500:
+        log.error("Novi server error %s for UUID %s", resp.status_code, uuid)
+        return {'status': 503, 'reason': f'Novi server error ({resp.status_code}).'}
+
+    if resp.status_code == 404:
+        log.info("Novi returned 404 for UUID %s", uuid)
+        return {'status': 404, 'reason': 'Member not found in Novi.'}
+
+    if resp.status_code != 200:
+        log.error("Unexpected Novi status %s for UUID %s: %s", resp.status_code, uuid, resp.text[:200])
+        return {'status': 503, 'reason': f'Unexpected Novi response ({resp.status_code}).'}
+
+    # ── Parse response ────────────────────────────────────────────────────
+    try:
+        data = resp.json()
+    except Exception:
+        log.error("Novi returned non-JSON for UUID %s", uuid)
+        return {'status': 503, 'reason': 'Novi returned an unparseable response.'}
+
+    if not isinstance(data, dict):
+        log.warning("Novi returned non-dict body for UUID %s", uuid)
+        return {'status': 404, 'reason': 'Member not found in Novi (empty response).'}
+
+    # Empty-member anti-pattern: Novi 200 with no identity data
+    email_raw = (data.get('Email') or '').strip()
+    if not email_raw:
+        log.info("Novi 200 with no Email for UUID %s — empty-member anti-pattern", uuid)
+        return {'status': 404, 'reason': 'Member not found in Novi (no identity data).'}
+
+    email = email_raw.replace(' ', '+')
+
+    # Build display name: "FirstName LastName[0]." — fall back to Name field
+    first = (data.get('FirstName') or '').strip()
+    last  = (data.get('LastName')  or '').strip()
+    if first and last:
+        full_name = f'{first} {last[0]}.'
+    elif first:
+        full_name = first
+    else:
+        full_name = (data.get('Name') or '').strip() or 'Member'
+
+    result = {
+        'status': 200,
+        'verified': True,
+        'full_name': full_name,
+        'email': email,
+    }
+
+    # ── Cache verified result ─────────────────────────────────────────────
+    try:
+        redis_client.setex(cache_key, _CACHE_TTL, json.dumps(result))
+    except Exception as e:
+        log.warning("Failed to cache Novi verify result for %s: %s", uuid, e)
+
+    return result
--- a/app/routers/api_v3_actions_idaa.py
+++ b/app/routers/api_v3_actions_idaa.py
@@ -0,0 +1,41 @@
+import asyncio
+
+from fastapi import APIRouter, Depends
+
+from app.lib_general_v3 import AccountContext, get_account_context, DelayParams
+from app.models.response_models import Resp_Body_Base, mk_resp
+from app.methods.idaa_novi_verify_methods import verify_novi_member
+
+router = APIRouter()
+
+
+@router.get('/novi_member/{uuid}', response_model=Resp_Body_Base)
+async def get_novi_member_verification(
+        uuid: str,
+        account: AccountContext = Depends(get_account_context),
+        delay: DelayParams = Depends(),
+        ):
+    """
+    Proxy Novi AMS member lookup server-to-server.
+    Returns verified member identity or an appropriate error code.
+    """
+    if delay.sleep_time_s > 0:
+        await asyncio.sleep(delay.sleep_time_s)
+
+    result = verify_novi_member(uuid)
+    status = result.get('status', 503)
+
+    if status == 200:
+        return mk_resp(data={
+            'verified': result['verified'],
+            'full_name': result['full_name'],
+            'email': result['email'],
+        })
+
+    if status == 404:
+        return mk_resp(data=False, status_code=404, status_message=result.get('reason', 'Member not found.'))
+
+    if status == 429:
+        return mk_resp(data=False, status_code=429, status_message=result.get('reason', 'Novi rate limit exceeded.'))
+
+    return mk_resp(data=False, status_code=503, status_message=result.get('reason', 'Novi API unavailable.'))
--- a/app/routers/registry.py
+++ b/app/routers/registry.py
@@ -6,7 +6,7 @@ from app.routers import (
    event_badge_importing,
    event_importing,
    api_v3_actions_email,
-    api_v3_actions_hosted_file, api_v3_actions_event_file, api_v3_actions_event_exhibit, api_v3_actions_e_zoom, api_v3_actions_e_novi_mailman, api_v3_actions_user, lookup_v3,
+    api_v3_actions_hosted_file, api_v3_actions_event_file, api_v3_actions_event_exhibit, api_v3_actions_e_zoom, api_v3_actions_e_novi_mailman, api_v3_actions_idaa, api_v3_actions_user, lookup_v3,
    user,
    util_email, websockets_v3, e_confex, e_cvent, e_impexium, e_stripe
 )
@@ -51,6 +51,7 @@ def setup_routers(app: FastAPI):
    app.include_router(api_v3_actions_event_exhibit.router, prefix='/v3/action/event_exhibit', tags=['Event Exhibit (V3 Actions)'])
    app.include_router(api_v3_actions_e_zoom.router, prefix='/v3/action/e_zoom', tags=['Zoom Events (V3 Actions)'])
    app.include_router(api_v3_actions_e_novi_mailman.router, prefix='/v3/action/e_novi_mailman', tags=['Novi-Mailman Bridge (V3 Actions)'])
+    app.include_router(api_v3_actions_idaa.router, prefix='/v3/action/idaa', tags=['IDAA Actions (V3)'])
    app.include_router(api_v3_actions_user.router, prefix='/v3/action/user', tags=['User (V3 Actions)'])
    app.include_router(api_v3_actions_email.router, prefix='/v3/action/email', tags=['Email (V3 Actions)'])
    # app.include_router(lookup.router, prefix='/lu', tags=['Lookup'])  # LEGACY (disabled) - superseded by /v3/lookup
--- a/documentation/ARCH__V3_DEVELOPMENT_STANDARDS.md
+++ b/documentation/ARCH__V3_DEVELOPMENT_STANDARDS.md
@@ -61,7 +61,47 @@ Some objects have a richer alternate SQL view (`tbl_alt`) that adds JOINed/compu
 -   The nested search router (`api_crud_v3_nested.py`) already supports `?view=<key>` to switch between registered views. `view=default` uses `tbl_default`; `view=alt` uses `tbl_alt`; additional named views can be added to the object registry as `tbl_<name>` / `mdl_<name>`.
 -   Flat search (`api_crud_v3.py`) does not yet support `?view=` — it always uses `tbl_default`.

-## 4. Stability Rules
+## 4. V3 Dependency Injection Reference
+
+All V3 endpoints use granular, composable `Depends()` from `app/lib_general_v3.py`:
+
+| Dependency | Purpose |
+|---|---|
+| `get_account_context` → `AccountContext` | Resolves `account_id` with precedence: Header → Query Token → Bypass Header. Raises 403 on guest/missing context. |
+| `PaginationParams` | Standardizes `limit` and `offset`. |
+| `StatusFilterParams` | Handles `enabled` and `hidden` filtering. |
+| `SerializationParams` | Controls Pydantic serialization (`by_alias`, `exclude_unset`). |
+| `DelayParams` | Optional latency simulation (`?delay=N`) via `await asyncio.sleep()`. |
+
+`AccountContext` also carries `administrator`, `manager`, and `super` flags, populated by a deferred DB lookup when a JWT is present. These flags control whether account isolation is bypassed for support tasks.
+
+## 5. Security and Data Isolation
+
+### Fail-Closed Strategy
+If `account_id` or auth context is missing, the API defaults to a blocking filter (`account_id IS NULL`) — it does NOT fall back to returning all records. Never relax this.
+
+### Multi-Tenant Isolation
+- **Forced account filtering**: `apply_forced_account_filter` injects an `account_id` WHERE clause into every list/search query for non-super users.
+- **Post-retrieval verification**: Single-object GET, PATCH, DELETE include a secondary ownership check (`check_account_access`). A mismatch returns 403.
+- **Hierarchical verification**: Nested endpoints verify parent ownership before allowing operations on children.
+- **Creation guard**: On POST, the user's `account_id` is automatically forced onto the new record.
+
+### IDAA Privacy Baseline
+No IDAA object (Events, Files, Posts, Meetings) is public by default. All routes require `x-account-id` context. The sole exception is `site_domain` (used for site bootstrapping). This is a **Sev-1 class constraint** — violating it has happened before.
+
+### Bypass / Admin Access
+- `x-no-account-id: bypass` → grants super access, resolves to `account_id=1` (One Sky IT Demo). Use only in internal/development utilities; do not expand its use.
+- JWT query parameter (`?jwt=...`) is supported for download links and share URLs where custom headers cannot be provided.
+
+## 6. FastAPI and Pydantic Gotchas
+
+- **`response: Response` injection**: Use it as a direct type hint in function signature. `Depends(Response)` is not valid and causes router initialization failures.
+- **Parameter order**: In function signatures, arguments without defaults must come before `Depends()` arguments.
+- **`asyncio.sleep()` not `time.sleep()`**: Blocking the event loop in an async endpoint causes worker timeouts and `502 Bad Gateway` under load.
+- **Pydantic V1 only**: Do not use V2-only features (`computed_field`, `model_validator`, etc.). The migration is a separate planned project — see strategic goals in `TODO__Agents.md`.
+- **`obj_type_kv_li` in `ae_obj_types_def.py`**: Supports both modern keys (`tbl`, `mdl`) and legacy keys (`table_name`, `base_name`). Legacy V2 endpoints depend on the legacy keys — do not remove them until V1/V2 are fully retired.
+
+## 7. Stability Rules

 1.  **Baby Step Testing**: Restart Docker and verify root health after *every* modular change.
 2.  **Avoid Shadowing**: Never name a module part of the `app.` package the same as a common instance variable (e.g., avoid `app.middleware` package if you use `app = FastAPI()`).
--- a/documentation/BOOTSTRAP__AI_Agent_Quickstart.md
+++ b/documentation/BOOTSTRAP__AI_Agent_Quickstart.md
@@ -0,0 +1,420 @@
+# Aether API — AI Agent Bootstrap / Quickstart
+> **Read this first.** This doc is the fast path to being productive on this project.
+> It covers the rules, patterns, and gotchas that matter most.
+> Deep dives are in the linked docs at the bottom.
+
+---
+
+## 1. What This Project Is
+
+**Aether** is an event management platform built by One Sky IT (Scott Idem).
+This repo is the backend: **FastAPI + MariaDB**, running inside Docker.
+
+The frontend (`aether_app_sveltekit/`) talks to this API exclusively via the V3 REST API.
+There is **no standalone dev server** — the API runs only in Docker.
+
+**Key clients:**
+- **Conference organizers** — Presentation management, badges, sessions
+- **Exhibitors** — Leads capture
+- **IDAA** — International Doctors in Alcoholics Anonymous (strictly private medical/recovery community)
+
+**Stack at a glance:**
+
+| Layer | Technology |
+|---|---|
+| Framework | FastAPI + Pydantic V1 (upgrade deferred) |
+| Database | MariaDB via SQLAlchemy 1.4 (upgrade deferred) |
+| Cache | Redis |
+| Auth | Custom headers: `x-aether-api-key` + `x-account-id` |
+| Container | Docker / Gunicorn — source is volume-mounted (no rebuild for Python changes, but **restart required**) |
+
+---
+
+## 2. Critical Rules — Read Before Touching Any Code
+
+### Privacy (Sev-1 class failures if violated)
+- **IDAA content is ALWAYS private.** All routes under `/idaa/` require authentication.
+  A previous agent accidentally exposed IDAA bulletin board data publicly.
+  This is the single most serious class of mistake on this project.
+  When in doubt — it's private. Always verify with `Depends(get_account_context)`.
+- **Journals** are private personal data. Always authenticated.
+
+### File Safety
+- **Never use `rm`** to delete files. Move to `~/tmp/gemini_trash` instead.
+- **Never commit `.env`** files, API keys, or passwords of any kind.
+- Third-party credentials (Novi API key, Mailman credentials) live in the **MariaDB `site.cfg_json` column**, not in `.env` or code.
+
+### Before Every Commit
+1. `python3 -m py_compile <changed_file>` — syntax check
+2. Restart Docker and verify the API starts clean: `docker compose restart ae_api`
+3. Check logs: `docker compose logs -f ae_api` (look for startup errors or import failures)
+4. Run the relevant E2E or unit test suite
+
+### Before Starting Any Task
+- Read `documentation/TODO__Agents.md` — active tasks, known bugs, and what was recently changed and why.
+- Check `tests/README.md` — which test suite covers the area you're about to touch.
+
+### Docker Restart is Mandatory After Python Changes
+The API source is volume-mounted, so file edits appear instantly inside the container — but
+**Gunicorn does NOT hot-reload**. You MUST run:
+```bash
+docker compose restart ae_api
+```
+after any Python file change before testing. This is the #1 cause of "my change didn't take effect."
+
+---
+
+## 3. Environment & Commands Cheat Sheet
+
+```bash
+# Start full stack
+cd ~/OSIT_dev/aether_container_env && docker compose up -d
+
+# Restart API after any Python change
+docker compose restart ae_api
+
+# Follow API logs
+docker compose logs -f ae_api
+
+# Shell into the container
+docker compose exec ae_api bash
+
+# Run unit tests (from project root)
+./environment/bin/python3 -m pytest tests/unit/ -v
+
+# Run a single E2E test
+./environment/bin/python3 tests/e2e/test_e2e_v3_search_engine.py
+
+# Check a specific Python file compiles
+./environment/bin/python3 -m py_compile app/methods/my_new_methods.py
+```
+
+**Development API:** `https://dev-api.oneskyit.com`
+**Dev API secret key:** `nT0jPeiCfxSifkiDZur9jA`
+**Standard test Agent API key:** `PMM4n50teUCaOMMTN8qOJA`
+
+**Dev DB via phpMyAdmin:** `http://localhost:8081`
+
+---
+
+## 4. V3 Action Router Pattern
+
+When adding a new action endpoint (not CRUD), follow this structure:
+
+### File layout
+```
+app/methods/my_feature_methods.py   ← business logic
+app/routers/api_v3_actions_my_feature.py  ← route handler (thin)
+```
+
+Then register in `app/routers/registry.py`:
+```python
+from app.routers import api_v3_actions_my_feature
+# ...
+app.include_router(api_v3_actions_my_feature.router, prefix='/v3/action/my_feature', tags=['My Feature (V3 Actions)'])
+```
+
+### Standard route handler pattern
+```python
+from fastapi import APIRouter, Depends
+from app.lib_general_v3 import AccountContext, get_account_context, DelayParams
+from app.models.response_models import Resp_Body_Base, mk_resp
+from app.methods.my_feature_methods import my_business_logic
+
+router = APIRouter()
+
+@router.get('/my_endpoint/{obj_id}', response_model=Resp_Body_Base)
+async def get_my_endpoint(
+        obj_id: str,
+        account: AccountContext = Depends(get_account_context),
+        delay: DelayParams = Depends(),
+        ):
+    if delay.sleep_time_s > 0:
+        await asyncio.sleep(delay.sleep_time_s)
+
+    result = my_business_logic(obj_id)
+    status = result.get('status', 503)
+
+    if status == 200:
+        return mk_resp(data=result['data'])
+
+    return mk_resp(data=False, status_code=status, status_message=result.get('reason', 'Error.'))
+```
+
+### Auth dependency
+`Depends(get_account_context)` is the **standard V3 gate**:
+- Requires a valid `x-aether-api-key`
+- Requires `x-account-id` OR a valid JWT session OR bypass mode
+- Raises 403 if `auth_method == 'guest'` or no account context can be resolved
+- For IDAA/private routes: this is the minimum gate. Never relax it.
+
+---
+
+## 5. Loading Site-Based Credentials (the `_load_idaa_cfg` Pattern)
+
+Third-party credentials (Novi API key, Mailman credentials, etc.) are stored in MariaDB
+in the `site.cfg_json` column for the relevant site record. Do NOT store them in `.env`.
+
+The IDAA site record is:
+- `id_random = '58_gJESdlUh'` (site id=17)
+- Fields: `novi_api_root_url`, `novi_idaa_api_key`, `mailman_base_url`, `mailman_username`, `mailman_password`, `novi_mailman_sync`
+
+Pattern to load them (use deferred import to avoid circular deps):
+```python
+IDAA_SITE_ID_RANDOM = '58_gJESdlUh'
+
+def _load_idaa_cfg() -> dict:
+    from app.db_sql import load_site_obj
+    site = load_site_obj(IDAA_SITE_ID_RANDOM)
+    if not site:
+        raise RuntimeError('IDAA site record not found')
+    cfg = site.get('cfg_json') or {}
+    if isinstance(cfg, str):
+        import json
+        cfg = json.loads(cfg)
+    return cfg
+```
+
+---
+
+## 6. Redis Cache Pattern
+
+```python
+import json
+import datetime
+from app.lib_redis_helpers import redis_client
+
+_CACHE_TTL = datetime.timedelta(hours=4)
+
+def _cache_key(uuid: str) -> str:
+    return f'idaa:novi_member:{uuid}'
+
+# Reading
+raw = redis_client.get(_cache_key(uuid))
+if raw:
+    return json.loads(raw)
+
+# Writing (only on success — never cache error states)
+redis_client.setex(_cache_key(uuid), _CACHE_TTL, json.dumps(result))
+```
+
+**Key naming convention:** `{module}:{object_type}:{identifier}` — e.g. `idaa:novi_member:{uuid}`
+
+**Never cache:**
+- 404 responses — the member may have just joined; next call should hit the source
+- 429 / 503 errors — transient failures should not poison future callers
+
+**Cache key scoping:** If the underlying data source is the same regardless of caller
+(e.g. Novi credentials are hardcoded to the IDAA site — same UUID always returns same data),
+drop `account_id` from the key. Per-caller scoping wastes Redis space and halves hit rate.
+
+---
+
+## 7. The `@logger_reset` Decorator — Unit Test Gotcha
+
+Business logic methods use `@logger_reset` from `app.lib_general`:
+
+```python
+from app.lib_general import logger_reset
+
+@logger_reset
+def my_method(arg):
+    ...
+```
+
+**In unit tests, this decorator MUST be mocked as a passthrough.**
+If `app.lib_general` is replaced with a plain `MagicMock()`, the decorator becomes a
+MagicMock, which when applied to a function replaces it with `MagicMock()()` — the decorated
+function is gone and every call returns garbage.
+
+```python
+# WRONG — logger_reset becomes a MagicMock and swallows the function:
+sys.modules['app.lib_general'] = MagicMock()
+
+# CORRECT — make it a passthrough decorator:
+mock_lib_general = MagicMock()
+mock_lib_general.logger_reset = lambda f: f
+sys.modules['app.lib_general'] = mock_lib_general
+```
+
+This is the #1 cause of unit tests returning `<MagicMock name='...'>` instead of real dicts.
+
+---
+
+## 8. Field Evolution Checklist
+
+When a table or view gains, loses, or renames fields — **do all of these in order**:
+
+1. Update the Pydantic model in `app/models/`
+2. Update the SQL view or table projection so GET/SEARCH return the field
+3. Update `searchable_fields` in `app/object_definitions/` (only for searchable fields)
+4. Add virtual/view-only fields to `fields_to_exclude_from_db` if they must not be persisted
+5. Run the relevant schema/search E2E tests
+6. **Restart Docker:** `docker compose restart ae_api`
+
+#### Alt-view fields (in `tbl_alt` only)
+Some objects have a richer alternate SQL view triggered by `?view=alt`. These fields
+**must still be declared in the Pydantic model and `searchable_fields`** even if they only
+appear in the alt view — Pydantic strips undeclared fields silently.
+
+---
+
+## 9. Deferred Imports in Library Modules
+
+To avoid circular dependency traps, **never import from `app.db_sql` or other app modules
+at the top level of a library module**. Use deferred imports inside functions:
+
+```python
+# WRONG — causes circular import at startup:
+from app.db_sql import load_site_obj
+
+def my_func():
+    return load_site_obj('abc')
+
+# CORRECT:
+def my_func():
+    from app.db_sql import load_site_obj
+    return load_site_obj('abc')
+```
+
+---
+
+## 10. Pydantic / SQLAlchemy Version Pins — Do Not Remove
+
+Current intentional pins:
+- `pydantic==1.*`
+- `SQLAlchemy==1.4.52`
+
+A Pydantic V2 and SQLAlchemy 2.0 migration is planned but not started. Until then,
+**do not upgrade these packages** — V2 touches every model definition and the migration
+is a dedicated project.
+
+---
+
+## 11. Mistakes Agents Have Made on This Project
+
+These are real incidents — know them before you start.
+
+1. **IDAA data exposed publicly** — an agent removed an auth guard from the bulletin board
+   router. Consequence: private IDAA recovery community data was publicly accessible.
+   Always verify `Depends(get_account_context)` is present on every IDAA route.
+
+2. **"My code change has no effect"** — Python file was edited but Docker was not restarted.
+   The API runs Gunicorn inside Docker with no hot-reload. `docker compose restart ae_api`
+   is required after every Python change.
+
+3. **`@logger_reset` mock swallows functions in unit tests** — see Section 7 above.
+   Symptom: `assert result['status'] == 200` fails with `TypeError: 'MagicMock' is not subscriptable`.
+
+4. **`pytest` / `pytest-asyncio` not installed after venv rebuild** — these are dev-only
+   dependencies not in `requirements.txt`. After any OS Python update (e.g., Arch Linux
+   upgrading to a new Python minor), rebuild the venv and reinstall:
+   ```bash
+   ./environment/bin/pip install pytest pytest-asyncio
+   ```
+
+5. **Global `db` connection used instead of context manager** — `lib_sql_core.py` has a
+   global `db = engine.connect()` that is a fragile single connection, not a pool.
+   For new methods, prefer `engine.connect()` as a context manager. See `TODO__Agents.md`
+   → "[P3 full]" task for the planned migration.
+
+6. **`bypass` mode hardcodes `account_id=1`** — `x-no-account-id: bypass` resolves to
+   `account_id=1` (One Sky IT Demo). Lookup overrides from the Demo account can leak into
+   bypass sessions. Do not expand bypass usage without documenting the allowlist case.
+
+7. **Caching error states in Redis** — caching 404 or 5xx responses poisons the cache.
+   A member who just joined Novi would be denied for 4 hours if their 404 was cached.
+   Only cache verified success (200) results.
+
+8. **Not running `docker compose restart ae_api` between model changes and E2E tests** —
+   the E2E suite hits the live API, which is still running the old code until restarted.
+   Tests will pass or fail against stale behavior and the results are meaningless.
+
+---
+
+## 12. Test Patterns
+
+### Unit tests (fast, no DB/network)
+```bash
+./environment/bin/python3 -m pytest tests/unit/ -v
+```
+- Mock all DB/Redis/HTTP at the top of the file before importing the module under test
+- `@logger_reset` must be mocked as a passthrough (see Section 7)
+- Always run from the **project root** — scripts use `sys.path.append(os.getcwd())`
+
+### E2E tests (live API at dev-api.oneskyit.com)
+```bash
+./environment/bin/python3 tests/e2e/test_e2e_v3_search_engine.py
+```
+- Require the Docker stack to be running with a working DB connection
+- Use standard output format: `[✅ PASS]` / `[❌ FAIL]`
+- Verify IDs in responses are **strings** (not integers) — ID Vision compliance
+
+### Which tests to run
+| Change type | Required suites |
+|---|---|
+| Model / ID Vision changes | `test_e2e_v3_demo_parity.py`, vision parity tests |
+| Search / filter changes | `test_e2e_v3_search_engine.py` |
+| Auth / account context changes | `test_e2e_v3_security_audit.py`, `test_e2e_v3_auth_security.py` |
+| Any router or registry change | `test_e2e_v3_security_audit.py` |
+| Novi-Mailman bridge changes | `test_e2e_v3_action_novi_mailman.py` |
+| IDAA Novi verify changes | `tests/unit/test_unit_idaa_novi_verify.py` |
+
+---
+
+## 13. Source Layout (Quick Reference)
+
+```
+app/
+  main.py                    — FastAPI app, lifespan, CORS
+  config.py                  — Pydantic Settings (from .env via Docker)
+  routers/
+    registry.py              — All router registrations live here
+    api_crud_v3.py           — Generic V3 CRUD (flat)
+    api_crud_v3_nested.py    — Generic V3 CRUD (nested/parent-owned)
+    api_v3_actions_*.py      — Action endpoints (one file per domain)
+    dependencies_v3.py       — Shared FastAPI Depends() helpers
+  models/                    — Pydantic V1 models (one file per domain)
+  object_definitions/        — Per-object searchable_fields, field metadata
+  ae_obj_types_def.py        — Object type registry (all Aether types defined here)
+  methods/                   — Business logic (one file per feature/domain)
+  lib_api_crud_v3.py         — Generic CRUD handler (all object types share this)
+  lib_schema_v3.py           — Dynamic schema/field resolution per object type
+  lib_general_v3.py          — AccountContext, get_account_context, DelayParams
+  lib_general.py             — logger_reset and general utilities
+  db_sql.py                  — Import facade (always import from here)
+  lib_sql_core.py            — SQLAlchemy engine, global db connection (Source of Truth)
+  lib_sql_crud.py            — sql_insert, sql_select, sql_update, etc.
+  lib_redis_helpers.py       — redis_client global instance
+
+tests/
+  unit/                      — Isolated logic tests (mock everything, no DB)
+  integration/               — Requires local MariaDB/Redis
+  e2e/                       — Network tests against live dev API
+  tools/                     — Admin utilities (stress test, registry generator)
+  mock_config_helper.py      — Mock app.config.settings — use in all unit tests
+  README.md                  — Which tests cover what; when to run them
+
+documentation/
+  TODO__Agents.md            — Active tasks + session notes ← always read first
+  ARCH__V3_DEVELOPMENT_STANDARDS.md — Master V3 standards doc
+  ARCH__V3_CORE.md           — Module architecture (lifespan, DB layers, logging)
+  GUIDE__AE_API_V3_for_Frontend.md  — Frontend integration guide (keep current)
+  GUIDE__DEVELOPMENT.md      — Commit SOP, verification checklist
+```
+
+---
+
+## 14. Reading Order for Deeper Dives
+
+| What you need | Read |
+|---|---|
+| Active tasks + known bugs | `documentation/TODO__Agents.md` ← always first |
+| V3 standards and strategy | `documentation/ARCH__V3_DEVELOPMENT_STANDARDS.md` |
+| Module architecture | `documentation/ARCH__V3_CORE.md` |
+| Frontend API integration guide | `documentation/GUIDE__AE_API_V3_for_Frontend.md` |
+| WebSocket integration | `documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md` |
+| Commit / verification SOP | `documentation/GUIDE__DEVELOPMENT.md` |
+| Which tests to run | `tests/README.md` |
+| Object type registry | `app/ae_obj_types_def.py` |
+| Shared agent docs | `~/agents_sync/aether/docs/UNIFIED_AGENT_ARCH.md` |
--- a/documentation/GUIDE__AE_API_V3_for_Frontend.md
+++ b/documentation/GUIDE__AE_API_V3_for_Frontend.md
@@ -638,6 +638,61 @@ const url = URL.createObjectURL(blob);

 ---

+## 12. IDAA: Server-Side Novi Member Verification
+
+Verifies a Novi AMS member UUID by proxying the Novi API call through the Aether backend. This eliminates false "Access Denied" failures for members on hotel/conference WiFi, VPNs, and Cloudflare-filtered networks — the Novi call originates from the server's IP, not the member's browser IP.
+
+- **Method:** `GET`
+- **Path:** `/v3/action/idaa/novi_member/{uuid}`
+- **Auth:** Standard V3 (`x-aether-api-key` + `x-account-id` or `?jwt=`)
+
+### Request
+
+| Parameter | Location | Required | Description |
+|---|---|---|---|
+| `uuid` | Path | Yes | Novi member UUID (from Novi AMS) |
+
+### Response on success (`200 OK`)
+
+```json
+{
+  "data": {
+    "verified": true,
+    "full_name": "Alice S.",
+    "email": "alice+member@idaa.org"
+  }
+}
+```
+
+- `full_name`: `"{FirstName} {LastName[0]}."` format. Falls back to the Novi `Name` field if first/last are absent.
+- `email`: Novi `Email` field with space → `+` normalization applied (Novi quirk — `alice member@idaa.org` → `alice+member@idaa.org`).
+
+### Error responses
+
+| Status | Meaning | Frontend action |
+|---|---|---|
+| `404` | UUID not found in Novi, or Novi returned 200 with no identity data (empty-member anti-pattern — member may have just joined) | Treat as denied / not a member |
+| `429` | Novi rate limit hit | Surface as `'rate_limited'`; advise retry |
+| `503` | Novi unreachable or Novi 5xx error | Surface as `'api_error'`; advise retry |
+
+### Migration from direct Novi call
+
+The frontend's `+layout.svelte:verify_novi_uuid()` currently calls Novi directly from the browser. Replace that `fetch()` with this endpoint. Response code mapping:
+
+| Direct Novi result | This endpoint returns | Frontend state |
+|---|---|---|
+| `200` with identity data | `200` | `verified` |
+| `200` with no identity data | `404` | `denied` |
+| `404` | `404` | `denied` |
+| `429` | `429` | `'rate_limited'` |
+| Network error / Novi 5xx | `503` | `'api_error'` |
+
+### Caching
+
+Verified results are cached in Redis (`idaa:novi_member:{uuid}`, 4-hour TTL). `404` results are **never** cached so recently-joined members are not incorrectly denied on their next attempt.
+
+---
+
 ## 11. Troubleshooting 403 Forbidden

 If you receive a 403 on a valid ID:
--- a/documentation/TODO__Agents.md
+++ b/documentation/TODO__Agents.md
@@ -39,6 +39,43 @@
 - [ ] **Step 2:** Coordination (Verify Frontend uses `x-account-id` instead of token).
 - [ ] **Step 3:** Frontend V3 WebSocket integration test — queued after IDAA-specific work. Backend is ready (auth wired, heartbeat presence refresh confirmed, unit tests passing). Frontend guide updated at `GUIDE__AE_API_V3_for_Frontend_websockets.md`.

+## 🔌 IDAA: Server-Side Novi Verification (Mini Project)
+> **Status: P1–P4 Complete (May 2026).** Endpoint live at `GET /v3/action/idaa/novi_member/{uuid}`. P5 (frontend migration) is the remaining step.
+> Rationale and frontend integration notes: `aether_app_sveltekit/documentation/CLIENT__IDAA_and_customized_mods.md` → "Planned: Server-Side Novi Verification"
+
+**Goal:** Proxy the Novi member-verification call server-to-server (FastAPI → Novi) so members' browser IPs are no longer in the call path.
+
+- [x] **[P1] New router:** `app/routers/api_v3_actions_idaa.py`
+  - Route: `GET /v3/action/idaa/novi_member/{uuid}`
+  - Required auth: `Depends(get_account_context)` — valid API key + any account context (x-account-id, JWT, or bypass). This is the standard V3 gate.
+  - Reads `novi_idaa_api_key` / `novi_api_root_url` from site `cfg_json` via `_load_idaa_cfg()` (same as Mailman bridge)
+  - Calls Novi: `GET {novi_api_root_url}/customers/{uuid}` with `Authorization: Basic {api_key}`
+  - Normalize email: `.replace(' ', '+')` (Novi quirk — see Novi-Mailman bridge notes)
+  - Build display name: `"{FirstName} {LastName[0]}."` format, fall back to `Name` field
+  - Returns `{ "verified": true, "full_name": "...", "email": "..." }` on success
+  - Returns `404` if Novi 200 with no identity data (empty-member anti-pattern)
+  - Returns `429` if Novi rate limits; `503` if Novi unreachable or 5xx
+  - Business logic in `app/methods/idaa_novi_verify_methods.py`
+
+- [x] **[P2] Redis cache:**
+  - Key: `idaa:novi_member:{uuid}` — TTL 4 hours
+    - Note: `account_id` dropped from key — Novi credentials are hardcoded to the IDAA site; same UUID always returns the same data regardless of caller, so per-caller scoping wastes Redis space and halves hit rate.
+  - Cache only verified (200) results — do NOT cache 404 (member may have just joined)
+  - Uses `redis_client` from `lib_redis_helpers.py` directly
+
+- [x] **[P3] Register in registry:** Added to `routers/registry.py` at `/v3/action/idaa` tag `IDAA Actions (V3)`. Confirmed live — endpoint appears in `/openapi.json`.
+
+- [x] **[P4] Tests:** `tests/unit/test_unit_idaa_novi_verify.py` — 9 tests, all passing.
+  - Mock Novi responses (200/empty-200/404/429/503/unreachable)
+  - Verify Redis cache is set on 200, hit bypasses Novi call
+  - Verify email normalization (space → +)
+  - Verify display name format (5 cases)
+
+- [x] **[P5] Coordinate with Frontend Agent** — **Complete (2026-05-19)**
+  - Frontend replaced direct `fetch()` to Novi in `+layout.svelte:verify_novi_uuid()`
+  - Response codes mapped: 200 → verified, 404 → denied, 429 → `'rate_limited'`, 503 → auto-retried (3s, once) then `'api_error'`
+  - 503 auto-retry added same session to match network-error retry path
+
 ## 🛡️ Security & Privacy Baseline (IDAA)
 - **Status:** **ENFORCED**.
 - **Maintenance:** Run `tests/e2e/test_e2e_v3_security_audit.py` after ANY router or registry change.
--- a/documentation/archive/ARCH__UNIFIED_AGENT.md
+++ b/documentation/archive/ARCH__UNIFIED_AGENT.md
--- a/documentation/archive/ARCH__V3_CRUD_LEARNINGS.md
+++ b/documentation/archive/ARCH__V3_CRUD_LEARNINGS.md
--- a/documentation/archive/FRONTEND_API_SAMPLES.md
+++ b/documentation/archive/FRONTEND_API_SAMPLES.md
--- a/documentation/archive/GUIDE__LOCAL_DEVELOPMENT.md
+++ b/documentation/archive/GUIDE__LOCAL_DEVELOPMENT.md
--- a/tests/README.md
+++ b/tests/README.md
@@ -33,6 +33,7 @@ These consolidated scripts are the primary verification tool for the V3 API.
 | `test_e2e_v3_action_novi_mailman.py` | **Novi-Mailman Bridge — Connections**: Verifies Novi AMS and Mailman 3 API credentials are valid (IDAA). Run first before the lists test. |
 | `test_e2e_v3_action_novi_mailman_lists.py` | **Novi-Mailman Bridge — List Operations**: Full member lifecycle — read roster, subscribe, verify, unsubscribe — against `mm3@idaa.org`, `mm3@dgrzone.com`, `mm3@oneskyit.com`. |
 | `test_e2e_v3_action_event_exhibit_tracking_export.py` | **Exhibit Leads Export**: Auth/permission guards, CSV column structure, XLSX bytes, and `return_file` mode for the V3 tracking export action. |
+| `test_e2e_v3_action_idaa_novi_verify.py` | **IDAA Novi Member Verify**: Auth guard, 200 verified, 404 not-found, 429 rate-limit, 503 unreachable, Redis cache hit, email normalization. (not yet written — add when endpoint is stable) |
 | `test_e2e_v3_accounts.py` | CRUD verification for the core Account object. |
 | `test_e2e_v3_schema.py` | Network verification of the V3 metadata discovery endpoint. |
 | `test_e2e_agent_bridge.py` | Verifies container diagnostics and log streaming routes. |
@@ -81,6 +82,7 @@ Tests exist to be used — run the relevant suite whenever you touch backend cod
 | User action route changes (sign-in, password, magic link) | `test_e2e_v3_user_action_routes.py` |
 | File upload / download changes | `test_e2e_v3_actions_file_lifecycle.py` |
 | Novi-Mailman bridge changes | `test_e2e_v3_action_novi_mailman.py`, `test_e2e_v3_action_novi_mailman_lists.py` |
+| IDAA Novi member verify changes | `tests/unit/test_unit_idaa_novi_verify.py`, `test_e2e_v3_action_idaa_novi_verify.py` (e2e pending) |
 | Event exhibit tracking export changes | `test_e2e_v3_action_event_exhibit_tracking_export.py` |
 | Any backend change before frontend hand-off | All of the above |

@@ -111,6 +113,16 @@ To maintain a "nice" and readable test suite, follow these patterns in all new P
 ./environment/bin/python3 tests/e2e/test_e2e_v3_search_engine.py
 ```

+### Running unit tests with pytest
+```bash
+./environment/bin/python3 -m pytest tests/unit/ -v
+```
+
+`pytest` and `pytest-asyncio` are dev-only dependencies (not in `requirements.txt`). After rebuilding the venv (e.g. following an OS Python update), reinstall them:
+```bash
+./environment/bin/pip install pytest pytest-asyncio
+```
+
 ### Path Requirements
 Always run test scripts from the **project root** directory. Most scripts include `sys.path.append(os.getcwd())` to ensure local imports work correctly.

--- a/tests/unit/test_unit_idaa_novi_verify.py
+++ b/tests/unit/test_unit_idaa_novi_verify.py
@@ -0,0 +1,219 @@
+import sys
+import os
+import json
+from unittest.mock import MagicMock, patch
+
+# Add project root to path
+sys.path.append(os.getcwd())
+
+# Mock low-level deps BEFORE importing the target module.
+# logger_reset must be a passthrough — if it stays a MagicMock the decorator
+# replaces the decorated function with a MagicMock and tests get garbage results.
+mock_lib_general = MagicMock()
+mock_lib_general.logger_reset = lambda f: f
+sys.modules['app.config'] = MagicMock()
+sys.modules['app.lib_general'] = mock_lib_general
+sys.modules['app.db_sql'] = MagicMock()
+sys.modules['app.lib_redis_helpers'] = MagicMock()
+
+from app.methods import idaa_novi_verify_methods as m
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────
+
+def _make_cfg():
+    return {
+        'novi_api_root_url': 'https://www.idaa.org/api',
+        'novi_idaa_api_key': 'dGVzdGtleQ==',
+    }
+
+
+def _novi_resp(email='alice@idaa.org', first='Alice', last='Smith', name=None):
+    d = {'Email': email, 'FirstName': first, 'LastName': last}
+    if name is not None:
+        d['Name'] = name
+    return d
+
+
+def _set_redis(cached_value=None):
+    """Set redis_client on the already-imported module's imported name."""
+    r = MagicMock()
+    r.get.return_value = cached_value
+    sys.modules['app.lib_redis_helpers'].redis_client = r
+    return r
+
+
+# ── Cache hit bypasses Novi ───────────────────────────────────────────────
+
+def test_cache_hit_bypasses_novi():
+    print('--- test_cache_hit_bypasses_novi ---')
+    cached = json.dumps({'status': 200, 'verified': True, 'full_name': 'Bob J.', 'email': 'bob@idaa.org'})
+    redis_mock = _set_redis(cached_value=cached)
+
+    with patch.object(m, '_load_idaa_cfg', return_value=_make_cfg()), \
+         patch('requests.get') as mock_get:
+        result = m.verify_novi_member('some-uuid')
+
+    print('Result:', result)
+    assert result['status'] == 200
+    assert result['full_name'] == 'Bob J.'
+    mock_get.assert_not_called()  # Novi was never contacted
+    print('PASS')
+
+
+# ── Verified 200 ──────────────────────────────────────────────────────────
+
+def test_verified_member_200():
+    print('--- test_verified_member_200 ---')
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.json.return_value = _novi_resp()
+    redis_mock = _set_redis()
+
+    with patch.object(m, '_load_idaa_cfg', return_value=_make_cfg()), \
+         patch('requests.get', return_value=mock_resp):
+        result = m.verify_novi_member('abc-123')
+
+    print('Result:', result)
+    assert result['status'] == 200
+    assert result['verified'] is True
+    assert result['full_name'] == 'Alice S.'
+    assert result['email'] == 'alice@idaa.org'
+    redis_mock.setex.assert_called_once()  # verified result cached
+    print('PASS')
+
+
+# ── Email normalization: space → + ────────────────────────────────────────
+
+def test_email_space_normalization():
+    print('--- test_email_space_normalization ---')
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.json.return_value = _novi_resp(email='alice member@idaa.org')
+    _set_redis()
+
+    with patch.object(m, '_load_idaa_cfg', return_value=_make_cfg()), \
+         patch('requests.get', return_value=mock_resp):
+        result = m.verify_novi_member('abc-123')
+
+    print('Result:', result)
+    assert result['status'] == 200
+    assert result['email'] == 'alice+member@idaa.org'
+    print('PASS')
+
+
+# ── Display name format ───────────────────────────────────────────────────
+
+def test_display_name_format():
+    print('--- test_display_name_format ---')
+    cases = [
+        (_novi_resp(first='Alice', last='Smith'),              'Alice S.'),
+        (_novi_resp(first='Alice', last=''),                   'Alice'),
+        (_novi_resp(first='', last='Smith', name='Dr. Alice'), 'Dr. Alice'),
+        (_novi_resp(first='', last='', name='Dr. Alice'),      'Dr. Alice'),
+        (_novi_resp(first='', last='', name=''),               'Member'),
+    ]
+
+    for novi_data, expected_name in cases:
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = novi_data
+        _set_redis()
+
+        with patch.object(m, '_load_idaa_cfg', return_value=_make_cfg()), \
+             patch('requests.get', return_value=mock_resp):
+            result = m.verify_novi_member('abc-123')
+
+        assert result['status'] == 200
+        assert result['full_name'] == expected_name, \
+            f"Expected '{expected_name}', got '{result['full_name']}' for input {novi_data}"
+
+    print('All display name cases PASS')
+
+
+# ── Empty-member anti-pattern: Novi 200, no Email ─────────────────────────
+
+def test_empty_member_returns_404():
+    print('--- test_empty_member_returns_404 ---')
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.json.return_value = {}  # Novi 200 with no identity data
+    redis_mock = _set_redis()
+
+    with patch.object(m, '_load_idaa_cfg', return_value=_make_cfg()), \
+         patch('requests.get', return_value=mock_resp):
+        result = m.verify_novi_member('ghost-uuid')
+
+    print('Result:', result)
+    assert result['status'] == 404
+    redis_mock.setex.assert_not_called()  # 404 must NOT be cached
+    print('PASS')
+
+
+# ── Novi 404 ──────────────────────────────────────────────────────────────
+
+def test_novi_404_returns_404():
+    print('--- test_novi_404_returns_404 ---')
+    mock_resp = MagicMock()
+    mock_resp.status_code = 404
+    redis_mock = _set_redis()
+
+    with patch.object(m, '_load_idaa_cfg', return_value=_make_cfg()), \
+         patch('requests.get', return_value=mock_resp):
+        result = m.verify_novi_member('missing-uuid')
+
+    print('Result:', result)
+    assert result['status'] == 404
+    redis_mock.setex.assert_not_called()
+    print('PASS')
+
+
+# ── Novi 429 ──────────────────────────────────────────────────────────────
+
+def test_novi_429_returns_429():
+    print('--- test_novi_429_returns_429 ---')
+    mock_resp = MagicMock()
+    mock_resp.status_code = 429
+    redis_mock = _set_redis()
+
+    with patch.object(m, '_load_idaa_cfg', return_value=_make_cfg()), \
+         patch('requests.get', return_value=mock_resp):
+        result = m.verify_novi_member('any-uuid')
+
+    print('Result:', result)
+    assert result['status'] == 429
+    redis_mock.setex.assert_not_called()
+    print('PASS')
+
+
+# ── Novi 5xx → 503 ────────────────────────────────────────────────────────
+
+def test_novi_5xx_returns_503():
+    print('--- test_novi_5xx_returns_503 ---')
+    mock_resp = MagicMock()
+    mock_resp.status_code = 502
+    _set_redis()
+
+    with patch.object(m, '_load_idaa_cfg', return_value=_make_cfg()), \
+         patch('requests.get', return_value=mock_resp):
+        result = m.verify_novi_member('any-uuid')
+
+    print('Result:', result)
+    assert result['status'] == 503
+    print('PASS')
+
+
+# ── Novi unreachable → 503 ────────────────────────────────────────────────
+
+def test_novi_unreachable_returns_503():
+    print('--- test_novi_unreachable_returns_503 ---')
+    import requests as req_lib
+    _set_redis()
+
+    with patch.object(m, '_load_idaa_cfg', return_value=_make_cfg()), \
+         patch('requests.get', side_effect=req_lib.exceptions.ConnectionError('refused')):
+        result = m.verify_novi_member('any-uuid')
+
+    print('Result:', result)
+    assert result['status'] == 503
+    print('PASS')