OSIT-AE-App-Svelte/GEMINI.md

# Gemini Agent Context: Aether (AE) SvelteKit Application

> **Template Version:** 1.2 (2026-01-26)
> **Purpose:** Standardized memory structure for all Aether Agents.
> **Structure:** Inverted Pyramid (Foundational -> Strategic -> Tactical -> Reference).

## 1. 💾 Long Term Memory (System & Facts)
*This section contains the "Universal Truths" that rarely change. It grounds the agent in the user's reality.*

### 🤖 Agent Identity & Role
- **Agent Name:** mcp_agent (SvelteKit Frontend)
- **Primary Role:** Frontend UI/UX Development & Svelte 5 Migration.
- **Scope:** `aether_app_sveltekit/`, Svelte components, Dexie stores, and V3 API integration.

### 👤 User Profile
- **User:** Scott Idem (`scott`)
- **Organizations:**
    - **One Sky IT (OSIT):** Professional/Business context.
    - **Danger Zone (DgrZone):** Personal/Home context.
    - **Aether Platform (AE):** Scott's (One Sky IT) platform developed for OSIT.
- **Preferences:**
    - **Editor:** `vim` (Terminal), VS Code (GUI).
    - **Communication:** Direct, concise, professional CLI tone.
    - **Safety:** "Recycle Bin" (`~/tmp/gemini_trash`) instead of `rm`. Explain destructive actions first.
- **Hardware/OS:**
    - **Host:** Linux System
    - **OS:** Linux

### 🏗️ Aether Architecture (V3)
- **Concept:** Unified AI-driven platform for business/personal management.
- **Frontend:** SvelteKit + Tailwind 4 + Skeleton UI + Dexie.js (Local-first).
- **Backend:** FastAPI + Pydantic V1 + SQLAlchemy + MariaDB (Remote).
- **Orchestration:** Docker Compose (via `aether-ops` extension).
- **Core Principle:** "Agent Bridge" - Distributed agents coordinating via file-based messaging.

#### 🎨 Frontend Standards
- **Reactivity & Stores:**
    - **Svelte 5 Runes:** Use `$state`, `$derived`, and `$effect` for component-level reactivity.
    - **Dexie LiveQuery:** Results from `liveQuery` are observables. You **MUST** use the `$` prefix (e.g., `$lq__obj`) in templates and logic to subscribe to the live data.
    - **Persistence:** Use `svelte-persisted-store` for data that must survive page refreshes (e.g., `ae_loc`, `journals_loc`).
    - **Initialization:** Always initialize reactive state (`$state`) outside of `$props()` destructuring. Use `untrack` inside `$effect` when synchronizing props to local state.
- **Performance (Non-Blocking Loads):**
    - **Stale-While-Revalidate:** Never block SvelteKit `load` functions with API calls for data already tracked by `liveQuery`.
    - **Fire & Forget:** Initiate API refreshes in `load` without `await`. Let the UI render instantly from IndexedDB cache and update reactively.
    - **Documentation:** See `documentation/PERFORMANCE_GUIDELINES.md` for detailed patterns.
- **ID Convention (Triple-ID Pattern):**
    - **Standard:** Use `id`, `[obj_type]_id`, and `[obj_type]_id_random` consistently.
    - **Primary Key:** Always use `_id_random` (string) for routing, data fetching, and local storage.
    - **Local Storage:** Alias `id_random` to both `id` (PK) and `[obj_type]_id` when saving to Dexie.
- **API V3 Implementation:**
    - **Robustness:** Use standardized primary helpers (`get`, `post`, `patch`, `delete`) in `src/lib/ae_api/`.
    - **SSR Parity:** Helpers support custom `fetch` injection for SvelteKit server-side execution.
    - **Bootstrap Paradox:** Use unauthenticated bypass (`x-no-account-id: "Nothing to See Here"`) for site/domain lookups.
    - **Envelopes:** Helpers automatically handle the `{data: ...}` envelope returned by the backend.
- **Data Pattern:**
    1. **Fetch:** API Function calls the V3 endpoint.
    2. **Process:** Dedicated `process_ae_obj__*_props` handles data shaping and computed fields.
    3. **Cache:** Save cleaned data to IndexedDB via `db_save_ae_obj_li__ae_obj`.

### 📜 Core Protocols
- **RAR Protocol:** Request -> Ack -> Result (for inter-agent tasks).
- **Bite-Sized Data:** Avoid monolithic files (>1MB). Split data into atomic chunks (e.g., `objects/*.json`).
- **Fail Fast & Transparently:** Revert immediately if a change breaks the system. API returns 500 on hard errors.
- **V3 CRUD Paradigm:** JSON metadata via `/v3/crud/`, binary actions via `/v3/action/`.
- **Project Mandates:**
    - **Fast is slow. Slow is fast.** Deliberate, careful progress.
    - **Commit early and often.** Test before committing.
    - **Trust but verify.** Verify tool outputs and assumptions.

### 🛡️ Security & Secrets Guardrails
- **Secrets:** NEVER read or display content from `.env` files unless explicitly debugging configuration logic.
- **Logging:** Do not include MariaDB passwords, API keys, or personal tokens in `ae_log_work` or commit messages.
- **PII:** Scrub personally identifiable information if sharing logs or data across the bridge.

### 🧪 Verification & Quality
- **Pre-Flight:** Verify `git status` before modification.
- **Compile Check:** Perform syntax checks and basic compile verification before finalizing any code change.
- **Tooling:**
    - `verify_api_integrity`: Headless verification of the FastAPI stack.
    - `schema_sync`: Syncs Pydantic models to TypeScript interfaces in `src/lib/types/ae_types.ts`.
    - `ae_obj_info`: Metadata lookup for Aether objects.

### 📝 Git & Coordination
- **Atomic Commits:** Stage related changes; avoid "megacommit" bloat.
- **Intent-Based Messages:** Focus on "Why" and "Strategic Intent".
- **UE-AE-01 Vision:** Unified agent with total system awareness across MariaDB, FastAPI, SvelteKit, and Nginx.

---

## 2. 🗓️ Near Term Memory (Strategic Context)
*This section tracks active projects (1-2 weeks scope). It answers "Why are we doing this?"*

### 📩 In-Flight RAR Requests
*Track active inter-agent tasks here to ensure follow-up.*
- [ ] **[Recipient Agent]**: [Description of request] (Sent: [YYYY-MM-DD])

### 🎯 Strategic Goals (Current Sprint)
- **Primary:** Performance Sprint & Journals Standardization.
- **Secondary:** V3 API Migration and System Health Stability.

### 🚧 Active Workstreams
- **[Leads Module V3]:** Transitioning Exhibitor Leads to V3 API and mobile-first dashboard.
- **[Hydration Optimization]:** Implemented SWR pattern and non-blocking layouts to eliminate "white page" delays.
- **[Search Hardening]:** Standardized debounced reactive search logic across Recovery Meetings, Badge Search, and Journals modules.
- **[Service Worker]:** Re-enabled registration and implemented robust asset caching.
- **[Telemetry]:** Modern dashboard in Launcher Config with visual CPU/RAM gauges.
- **[Journals Module]:** Standardized naming (`ae_comp__*`), normalized props to snake_case, and unified icons.

### 🧠 Recent Learnings & Decisions
- **V3 Search Context:** POST search for child objects (e.g. `event_exhibit_tracking`) requires explicit `for_obj_type` and `for_obj_id` query parameters to assist the backend in partitioning, otherwise it may inject incorrect legacy filters like `event_id_random`.
- **SWR Pattern:** Crucial for eliminating page load delays in Sites, Events, and Journals.
- **Debounced Search:** Replacing manual triggers and loops (like setInterval) with reactive debounced effects significantly improves UX and reduces API noise.
- **Quiet Logs:** Silenced noisy `AbortError` and `NetworkError` in background fetches to reduce noise.
- **Details Toggle:** Optimized Event Session list by deferring expensive sub-components.

---

## 3. 🧠 Short Term Memory (Session Context)

- **Status:** Session Concluded / System Stable.

- **Last Action:** Finalized V3 Leads foundations, fixed dashboard routing, and implemented booth management.

- **Key Learnings:**

    - **Backend API Bug:** Identified a 400 Database Schema error in `event_exhibit_tracking` search caused by the backend incorrectly injecting legacy `event_id_random` filters. Frontend is verified clean and strictly follows base `_id` standards.

    - **Nested Routing Logic:** Lead Detail routes MUST be nested under the Exhibit ID to maintain context and resolve 404 errors in the capturing workflow.

    - **Property Processor Hardening:** Hardened processors to prioritize base `_id` mapping to internal `id` fields, ensuring robust Dexie synchronization for string-only identifiers.

- **Accomplishments:**

    - **V3 Leads Module Foundations:** Modularized `ae_events__exhibit` and `ae_events__exhibit_tracking` with V3 SWR standards and trace-ready performance logging.

    - **String-Only ID Standardization:** Standardized all Lead capture and search functions to use base `_id` keys instead of the `_random` suffix dependency.

    - **Leads Dashboard Orchestration:** Implemented a mobile-first, high-contrast dashboard with persistent tab navigation (Add Lead, Lead List, Manage).

    - **Lead Detail Profile:** Implemented a comprehensive read-only Lead Profile view featuring custom responses and exhibitor notes.

    - **Booth Management:** Implemented the Manage/Config tab using `Element_ae_crud_v2` for live-revalidating booth profile updates.

- **Current Blocker:** Backend Search Bug for `event_exhibit_tracking` (injecting `event_id_random`).

- **Immediate Next Step:** Verify Staff Sign-in workflow and License assignment logic once the search bug is resolved.

---

## 4. 📂 Reference: Directory & Whitelist

*Low-density reference data. Keep at the bottom to avoid cluttering the prompt's "hot zone".*

### 🛡️ File Whitelist

- `~/tmp`, `~/Downloads`, `~/temp`, `~/agents_sync`

### 🗺️ Standard Directory Map

- **`src/lib/ae_api/`**: API V3 standard helpers.

- **`src/lib/ae_events/`**: Core event library and Dexie store.

- **`src/lib/types/ae_types.ts`**: Unified TypeScript interfaces.

### 📦 Modules Overview

- **Core:** Identity (`accounts`, `people`, `users`), Infrastructure (`sites`, `site_domains`), Storage (`hosted_files`).

- **Feature:** Events (Badge printing, QR, Pres Mgmt), Journals (Notes, AI), IDAA (Logistics, Jitsi).

### 🔗 Resources

- **Reference Stubs:** `agents_sync/technical/references/` (Svelte 5, Dexie, FastAPI).

- **Official Docs:** [Svelte Runes](https://svelte.dev/blog/runes) | [Dexie Quick Ref](https://dexie.org/docs/API-Reference#quick-reference)

## Gemini Added Memories

- The Aether Docker environment now has a robust physical database management suite: restore_db.sh, check_and_import.sh, and export_db.sh. Password escaping issues resolved using single quotes in .env.

- Standalone DB tests in API project: Use virtual environment at 'environment/bin/python3', extract credentials from container env, and manually construct SQLAlchemy URI to bypass 'app.config' dependency issues.

- [Harden: ID Integrity] Generic object processors MUST use truthy checks when mapping `_random` variants to clean keys to prevent `null` or `undefined` values from clobbering valid linking IDs received from V3 API responses.

- [Harden: Event File Loader] Implemented a "Safety Net" in `_refresh_file_li_background` to inject missing `for_id` and `for_type` from the query context before saving to Dexie, ensuring robust indexing even with partial API responses.

- Centralized 'public_read' flag in object definitions (core.py, cms.py, etc.) controls guest access in V3 API.

- V3 API 'view' parameter rollout complete across core event library modules.

- Presentation Management reports utilize the 'alt' view for file data shapes.

- The user prefers snake_case or Snake_Case over CamelCase for all naming and identifiers.

- Formatting Standard: Prettier printWidth is set to 80 to force multi-line expansion for attributes and calls.

- The Aether API V3 search for 'event_exhibit_tracking' currently has a backend bug where it incorrectly injects a filter for 'event_id_random' instead of 'event_id', causing a 400 Database Schema error (MariaDB code 1054). The frontend is sending the correct V3 payload, but the backend mapping needs to be updated by the API agent.