167 lines
9.1 KiB
Markdown
167 lines
9.1 KiB
Markdown
# 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:** Session Concluded / System Stable.
|
|
|
|
- **Last Action:** Fully reverted all Launcher module changes to the last known working commit.
|
|
|
|
- **Key Learnings:**
|
|
|
|
- **Reactivity Loops:** Svelte 5 `$derived` runes combined with `liveQuery` observables can trigger infinite loops if the `liveQuery` is recreated on every derivation cycle.
|
|
|
|
- **SvelteKit Navigation:** `goto` options like `noscroll` and `keepfocus` must remain lowercase in SvelteKit 2; camelCase variants may be ignored or cause issues.
|
|
|
|
- **ID Handling:** Initializing store IDs to `''` instead of `null` is generally safer for string-based ID logic in Svelte 5.
|
|
|
|
- **Accomplishments:**
|
|
|
|
- Restored the system to a clean, stable state after an experimental Svelte Rune refactor.
|
|
|
|
- Identified "Bite-Sized" refactoring targets (Large Files > 800 lines).
|
|
|
|
- Captured the requirement for safe `file_count_all` integration in the Kanban board.
|
|
|
|
- **Current Blocker:** None.
|
|
|
|
- **Immediate Next Step:** Await user's next session to tackle modular refactoring.
|
|
|
|
---
|
|
|
|
## 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) |