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:** Launcher Stabilization & Performance.
- **Secondary:** V3 API Migration and System Health Stability.

### 🚧 Active Workstreams
- **[Launcher Stabilization]:** Hardening the native bridge and resolving session selection reactivity issues.
- **[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.
- **[Telemetry]:** Modern dashboard in Launcher Config with visual CPU/RAM gauges.

### 🧠 Recent Learnings & Decisions
- **LiveQuery Reactivity:** `liveQuery` observables require explicit prefixing ($) in templates. Re-assigning them to `$state` variables in effects can lead to `store_invalid_shape` errors if prefixes aren't updated.
- **Global Page State:** Migrating from manual prop-passing (like `data_url`) to the global `$page` state significantly simplifies component trees and avoids "undefined" errors during navigation.
- **Native Handover:** Using `.tmp` files for downloads and only renaming to `.file` after SHA-256 verification ensures cache integrity in the native bridge.

---

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

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

- **Last Action:** Reverted uncommitted reactivity refactors in `launcher/+layout.svelte` and `launcher_session_view.svelte` due to page load failure.

- **Key Learnings:**

    - **Reactivity Race Conditions:** Manual store updates synchronized via URL can clash with layout effects, leading to clobbered states.
    - **Svelte 5 Store Prefixes:** Standardizing on `$lq__obj` for observables is critical; switching to direct state variables requires surgical template updates.

- **Accomplishments:**

    - **'download' Filename Bug Fix:** Explicitly passed filenames to V3 Action endpoints and implemented a safety net in `api_get_object.ts`.
    - **Menu Refactor:** Migrated `menu_session_list.svelte` and `menu_location_list.svelte` to use global `$page.url` state.
    - **Native Caching:** Implemented SHA-256 verification and stale temp purge in the Electron bridge.
    - **UI Initialization:** Ensured `event_session_id` defaults to `null` and added explicit no-session prompts.

- **Current Blocker:** Session Selection Hang (Page fails to load or UI hangs when selecting a session if starting from a path without an initial ID).

- **Immediate Next Step:** Investigate Dexie/Svelte reactivity in the Launcher layout without introducing breaking clobbers.

---

## 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

- [Harden: ID Integrity] Generic object processors MUST use truthy checks when mapping `_random` variants to clean keys.
- [Harden: Event File Loader] Safety Net in `_refresh_file_li_background` to inject missing metadata from query context.
- [Harden: API Safety Net] `api_get_object.ts` fallback-extracts `filename` from `params` if the explicit argument is missing.
- [Native: Cache Reliability] Implemented SHA-256 integrity checks and stale `.tmp` purge in Electron `file_handlers.ts`.
- [Layout: Page State] Use `page` from `$app/state` for layout-level store synchronization to avoid clobbering manual updates.
- The user prefers snake_case or Snake_Case over CamelCase for all naming and identifiers.
- Formatting Standard: Prettier printWidth is set to 80.
- The Aether API V3 search for 'event_exhibit_tracking' has a backend bug injecting 'event_id_random'.