# Aether (AE) SvelteKit Application

This project is the frontend UI/UX for the Aether (AE) system, built with Svelte 5 (SvelteKit), Tailwind CSS, and Skeleton. It interfaces with a Python FastAPI backend.

## 🎯 Core Mandates (Safety & Efficiency)
- **Fast is slow. Slow is fast.** Deliberate, careful progress is better than rushed, error-prone actions.
- **Fail fast.** If a change breaks the system, revert immediately to the last known working version before attempting a new fix.
- **Commit early and often.** Working changes MUST be committed before starting major new modifications. Always test before committing.
- **Verify.** Perform syntax checks and basic compile verification before finalizing any code change.
- **Trust but verify.** Always verify tool outputs, assumptions, and system state before proceeding.

## 🏗️ Architecture & 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. Failure to do so will result in accessing the observable object instead of its 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 to prevent infinite loops.

### 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 the 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 the 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` function handles data shaping, parent ID injection, and computed fields.
3. **Cache:** Save cleaned data to IndexedDB via `db_save_ae_obj_li__ae_obj`.

---

## 🛠️ Tooling & Orchestration

### Aether Ops (MCP Extension)
- **`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.
- **UE-AE-01 Vision:** Moving towards a unified agent with total system awareness across MariaDB, FastAPI, SvelteKit, and Nginx.

---

## 📂 Modules Overview

### Core Modules
- **Identity:** `accounts`, `people`, `users`.
- **Infrastructure:** `sites`, `site_domains`.
- **Storage:** `hosted_files`.

### Feature Modules
- **Events:** Presentation management, Badge printing, QR tracking.
- **Journals:** Documentation, notes, and AI-assisted summarization.
- **IDAA:** Client-specific logistics and video conferencing (Jitsi).

---

## 📝 Development History (Consolidated)

### Hardening & V3 Stabilization (2026-01-20)
- **IDAA Search Hardening:** Isolated IDAA Recovery Meetings to a specialized `qry_ae_obj_li__event_v2` function. Restored full 154-result capacity and implemented "Inclusive OR" location logic (Virtual/In-person).
- **System Lookups Restoration:** Fixed a `TypeError` by correctly exporting `get_ae_obj_li_for_lu` in `api.ts`. Reverted lookup endpoints to stable V2 paths to resolve V3 "Configuration error" 500s. Added Country Subdivisions card to the lookups page.
- **V3 Search Refinement:** Updated general `qry_ae_obj_li__event` to use the standardized `q` property for full-text search and robust "Body + Header" context injection.
- **Git State Resolution:** Resolved a complex 12-commit rebase conflict involving `manifest.webmanifest` and `ae_events__event.ts`. Pushed a clean, branded, and stable state to the remote repository.
- **Crash Prevention:** Hardened meeting detail views with null-checks for `contact_li_json` to handle legacy/incomplete data.

### Hardening & V3 Stabilization (2026-01-19)
- **Structured Error Handling:** Updated `api_get`, `api_post`, and `api_patch` helpers to extract rich metadata (`meta.details`) from V3 API 400/500 responses. Standard FastAPI `detail` fields are automatically wrapped for consistency.
- **JWT Race Condition Fix:** Implemented "Early Injection" in `+layout.ts`. The JWT is now read directly from `localStorage` during bootstrap, ensuring the first requests of a page load are correctly authenticated.
- **Archives Stability:** Resolved a critical async race condition in `load_ae_obj_li__archive` and hardened `_process_generic_props` to handle non-array API responses.
- **Fail-Fast Hardening:** Added HTTP `400` and `422` to the Fail-Fast protocol to prevent unnecessary retries on invalid requests.
- **V3 Hardening Tests:** Enhanced the `/testing` dashboard with "Live V3 Header Inspection" and automated audits for Permissive Mode and Structured Errors.
- **Status:** Main AE Events module verified working with V3 Search; IDAA isolated to V2 for stability.

### Hardening & Svelte 5 Modernization (2026-01-16)
- **Hardening:** Improved resilience for Journals and IDAA modules against API downtime and "ghost" account fallback.
- **Commit:** Atomic refactor of 15 files focusing for type safety, Svelte 5 runes, and API robustness.
- **Fixes:** Resolved download progress crashes in `api_get_object_v1` and corrected event handling in several Svelte 5 components.
- **Status:** Investigating Badge Rendering issues where `badge_template_obj` fails to load despite `badge_obj` being available.

### Config & Stability Sprint (2026-01-14)
- **Standardization:** Refactored Module, Journal, and Entry modals into a unified "Config" pattern with consistent iconography (Wrench/Gear/Zap).
- **Auto-Save:** Implemented background persistence for Status & Security fields using non-blocking API calls.
- **Payload Hardening:** Established a strict whitelisting pattern for update payloads to eliminate HTTP 400 "Unknown column" errors.
- **UX Refinement:** Replaced complex Journal menus with a streamlined "Config" button and dedicated "Quick Actions" tabs.

### Journals Module Refactor (2026-01-08)
- **Modularization:** Extracted `JournalEntry_AITools` and `JournalEntry_Metadata` from the 3000+ line main view.
- **UI/UX:** Standardized on Lucide icons. Implemented 3-state header toggle (View/Eye/Save).
- **CodeMirror:** Migrated to CM6 with `updateListener` pattern for Svelte 5 compatibility.

### Jitsi God Mode (2025-12-15)
- **Architecture:** Hybrid XMPP bot for server-side stats collection, pushing real-time meeting metadata to MariaDB.

### Build & Library Health (2025-12-08)
- **Upgrades:** Successfully updated to SkeletonLabs v4.7.4 and Flowbite-Svelte v4.0.1.
- **Staging:** `npm run build:staging` verified and clean of import/export errors.

---

## 🔗 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)