# 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 - **[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. - **[Native Bridge]:** Phase 5 AppleScript handlers for macOS (PowerPoint/Keynote). - **[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 - **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. - **CodeMirror Fix:** Resolved line-wrapping issues in editors. --- --- ## 3. 🧠 Short Term Memory (Session Context) - **Status:** Session Concluded / System Stable. - **Last Action:** Hardened Event File processing, implemented loader safety nets, and enabled verbose tracking. - **Key Learnings:** - **ID Clobbering:** The generic processor was blindly overwriting clean IDs with `null` random IDs from the API; truthy checks on `_random` variants are essential to preserve relationship integrity. - **Loader Safety Net:** Implementing minimal, type-aware ID injection in `_refresh_file_li_background` ensures records are correctly indexed in Dexie even when the backend response is partially incomplete. - **Relationship Sync:** Synchronizing `for_id` with specific object IDs (e.g., `event_presenter_id`) in the processor ensures UI components can reliably retrieve files using either the generic or specific keys. - **Accomplishments:** - **Event File Upload Restoration:** Fixed 422 errors in `ae_comp__event_files_upload.svelte` by identifying a backend Pydantic integer vs string mismatch and standardizing on the V3 action endpoint. - **Relationship Integrity:** Resolved missing `event_id` and cross-contaminated IDs in `ae_events_db.file` by hardening `_process_generic_props` and the background loader. - **UI Retrieval Fix:** Reverted `element_manage_event_file_li_direct.svelte` to robust `for_type`/`for_id` filtering and enhanced `li_all` with combined ID filters to ensure linked files show up for all objects. - **Batch Formatting:** Finalized module-wide formatting (printWidth: 80) across Archives, Settings, and root Events components. - **Surgical Debugging:** Enabled verbose tracking in Presenter load functions and the Event File loader to isolate data flow issues. - **Current Blocker:** None. - **Immediate Next Step:** Verify Bulletin Board email notifications and Recovery Meetings Zoom/Jitsi logic. --- ## 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' dependencies. - [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.