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

• [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.
• [Service Worker]: Re-enabled registration and implemented robust asset caching.
• [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

• V3 Search Context: POST search for child objects (e.g. event_exhibit_tracking) requires explicit for_obj_type and for_obj_id query parameters to assist the backend in partitioning, otherwise it may inject incorrect legacy filters like event_id_random.
• 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.

---

3. 🧠 Short Term Memory (Session Context)

• Status: Session Concluded / System Stable.

• Last Action: Finalized V3 Leads foundations, fixed dashboard routing, and implemented booth management.

• Key Learnings:

  • Backend API Bug: Identified a 400 Database Schema error in event_exhibit_tracking search caused by the backend incorrectly injecting legacy event_id_random filters. Frontend is verified clean and strictly follows base _id standards.

  • Nested Routing Logic: Lead Detail routes MUST be nested under the Exhibit ID to maintain context and resolve 404 errors in the capturing workflow.

  • Property Processor Hardening: Hardened processors to prioritize base _id mapping to internal id fields, ensuring robust Dexie synchronization for string-only identifiers.

• Accomplishments:

  • V3 Leads Module Foundations: Modularized ae_events__exhibit and ae_events__exhibit_tracking with V3 SWR standards and trace-ready performance logging.

  • String-Only ID Standardization: Standardized all Lead capture and search functions to use base _id keys instead of the _random suffix dependency.

  • Leads Dashboard Orchestration: Implemented a mobile-first, high-contrast dashboard with persistent tab navigation (Add Lead, Lead List, Manage).

  • Lead Detail Profile: Implemented a comprehensive read-only Lead Profile view featuring custom responses and exhibitor notes.

  • Booth Management: Implemented the Manage/Config tab using Element_ae_crud_v2 for live-revalidating booth profile updates.

• Current Blocker: Backend Search Bug for event_exhibit_tracking (injecting event_id_random).

• Immediate Next Step: Verify Staff Sign-in workflow and License assignment logic once the search bug is resolved.

---

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

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' dependency issues.

• [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.

• The Aether API V3 search for 'event_exhibit_tracking' currently has a backend bug where it incorrectly injects a filter for 'event_id_random' instead of 'event_id', causing a 400 Database Schema error (MariaDB code 1054). The frontend is sending the correct V3 payload, but the backend mapping needs to be updated by the API agent.