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: 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: Committed a platform-wide refactor of button types and file operation security (81 files).

• Key Learnings:

  • Multi-Line Attribute Hazards: Bulk regex tools often miss or duplicate attributes in multi-line Svelte tags; surgical manual edits or specialized parsers are required for clean tag handling.

  • V3 Action Pattern: Authenticated file downloads now strictly require the key=${account_id} parameter via the /v3/action/ endpoint path.

  • Svelte 5 Effects: Using $effect to synchronize props to local state requires untrack to prevent circular reactivity loops.

• Accomplishments:

  • Standardized Button Typing: Applied type="button" vs type="submit" across Journals, Events, and IDAA modules to prevent accidental form submissions.

  • Hardened File Operations: Successfully migrated the entire platform to the authenticated V3 Action API for all file downloads and deletes.

  • Compiler Error Sweep: Resolved over 40 critical compiler errors, including duplicate attributes in complex components and missing imports.

  • DX Optimization: Verified the "Safe Workflow Strategy" (Edit -> Lint -> Check) as an effective baseline for large-scale refactoring.

• Current Blocker: None.

• Immediate Next Step: Resolve remaining type mismatches (~160) or begin modular refactoring of large components (>800 lines).

---

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 | Dexie Quick Ref