# 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)
*This section is the "Scratchpad" for the current interaction. It is cleared or summarized often.*

- **Status:** Idle / Task Complete.
- **Last Action:** Logged work for v1.2 template standardization across the ecosystem.
- **Current Blocker:** None.
- **Immediate Next Step:** Await next user instruction.

---

## 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_journals/`**: Journals feature module.
- **`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), 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)