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