Updating the documentation for things. Hopefully improvements to Gemini CLI.

GEMINI.md

@@ -1,176 +1,38 @@
-# Gemini Agent Context: Aether (AE) SvelteKit Application
+# Aether Frontend Agent Context: Gemini CLI Standard
+> **Role:** Aether App Orchestrator (SvelteKit Frontend)
+> **Location:** GEMINI.md (Project Root)
 
-> **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.
+## 🚨 MANDATORY PROTOCOL
+You must follow the safety, testing, and coordination standards defined in:
+`documentation/GUIDE__DEVELOPMENT.md`
 
 ---
 
-## 2. 🗓️ Near Term Memory (Strategic Context)
-*This section tracks active projects (1-2 weeks scope). It answers "Why are we doing this?"*
+## 🏗️ Technical Domain: Aether Frontend
+### Stack & UI Standards
+- **Framework:** SvelteKit v2 + Svelte 5 (Runes)
+- **Styling:** Tailwind 4 + Skeleton UI + Skeleton V3 (SkeletonNext)
+- **Local Cache:** Dexie.js (IndexedDB)
+- **Icons:** Standardizing on **Lucide-Svelte**. Avoid legacy Font-Awesome where possible.
 
-### 📩 In-Flight RAR Requests
-*Track active inter-agent tasks here to ensure follow-up.*
-- [ ] **[Recipient Agent]**: [Description of request] (Sent: [YYYY-MM-DD])
+### Reactivity Patterns (The "Aether Way")
+- **Svelte 5 Runes:** Use `$state`, `$derived`, and `$effect`. 
+- **Navigation Shield:** Use SvelteKit's `page.url` searchParams as the single source of truth for navigation-driven selection. Sync to global stores only via `untrack()` within effects.
+- **Side-Effect Purge:** Keep `liveQuery` observables pure. Do NOT update global stores ($events_slct) inside derived observables to prevent infinite reactivity loops.
+- **Dexie LiveQuery:** Use the `$` prefix (e.g., `$lq__obj`) consistently. Results from `liveQuery` are observables.
+- **Initialization:** Always initialize reactive state (`$state`) outside of `$props()` destructuring.
 
-### 🎯 Strategic Goals (Current Sprint)
-- **Primary:** Launcher Stabilization & Performance.
-- **Secondary:** V3 API Migration and System Health Stability.
+### Performance & Data
+- **SWR (Stale-While-Revalidate):** Never block SvelteKit `load` functions with API calls for cached data. Let the UI render instantly from IndexedDB and update reactively.
+- **Triple-ID Pattern:** Map `id`, `[obj_type]_id`, and `[obj_type]_id_random` consistently.
+- **ID Vision:** The backend uses String IDs. Primary keys should use `_id` or `id` (String) mapping to backend `id_random`.
 
-### 🚧 Active Workstreams
-- **[Launcher Stabilization]:** Hardening the native bridge and resolving session selection reactivity issues.
-- **[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.
-- **[Telemetry]:** Modern dashboard in Launcher Config with visual CPU/RAM gauges.
+## 🧠 Recent Strategy & Patterns
+- **Safe Handover (Native):** Rename `.tmp` to `.file` ONLY after SHA-256 verification in Electron.
+- **Envelopes:** API helpers automatically handle the `{data: ...}` envelope returned by the backend.
+- **Bootstrap Paradox:** Use unauthenticated bypass (`x-no-account-id: "Nothing to See Here"`) for initial site/domain lookups.
 
-### 🧠 Recent Learnings & Decisions
-- **LiveQuery Reactivity:** `liveQuery` observables require explicit prefixing ($) in templates. Re-assigning them to `$state` variables in effects can lead to `store_invalid_shape` errors if prefixes aren't updated.
-- **Global Page State:** Migrating from manual prop-passing (like `data_url`) to the global `$page` state significantly simplifies component trees and avoids "undefined" errors during navigation.
-- **Native Handover:** Using `.tmp` files for downloads and only renaming to `.file` after SHA-256 verification ensures cache integrity in the native bridge.
-
----
-
-## 3. 🧠 Short Term Memory (Session Context)
-
-- **Status:** Session Concluded / System Reverted to Stable.
-
-- **Last Action:** Reverted uncommitted reactivity refactors in `launcher/+layout.svelte` and `launcher_session_view.svelte` due to page load failure.
-
-- **Key Learnings:**
-
-    - **Reactivity Race Conditions:** Manual store updates synchronized via URL can clash with layout effects, leading to clobbered states.
-    - **Svelte 5 Store Prefixes:** Standardizing on `$lq__obj` for observables is critical; switching to direct state variables requires surgical template updates.
-
-- **Accomplishments:**
-
-    - **'download' Filename Bug Fix:** Explicitly passed filenames to V3 Action endpoints and implemented a safety net in `api_get_object.ts`.
-    - **Menu Refactor:** Migrated `menu_session_list.svelte` and `menu_location_list.svelte` to use global `$page.url` state.
-    - **Native Caching:** Implemented SHA-256 verification and stale temp purge in the Electron bridge.
-    - **UI Initialization:** Ensured `event_session_id` defaults to `null` and added explicit no-session prompts.
-
-- **Current Blocker:** Session Selection Hang (Page fails to load or UI hangs when selecting a session if starting from a path without an initial ID).
-
-- **Immediate Next Step:** Investigate Dexie/Svelte reactivity in the Launcher layout without introducing breaking clobbers.
-
----
-
-## 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](https://svelte.dev/blog/runes) | [Dexie Quick Ref](https://dexie.org/docs/API-Reference#quick-reference)
-
-## Gemini Added Memories
-
-- [Harden: ID Integrity] Generic object processors MUST use truthy checks when mapping `_random` variants to clean keys.
-- [Harden: Event File Loader] Safety Net in `_refresh_file_li_background` to inject missing metadata from query context.
-- [Harden: API Safety Net] `api_get_object.ts` fallback-extracts `filename` from `params` if the explicit argument is missing.
-- [Native: Cache Reliability] Implemented SHA-256 integrity checks and stale `.tmp` purge in Electron `file_handlers.ts`.
-- [Layout: Page State] Use `page` from `$app/state` for layout-level store synchronization to avoid clobbering manual updates.
-- The user prefers snake_case or Snake_Case over CamelCase for all naming and identifiers.
-- Formatting Standard: Prettier printWidth is set to 80.
-- The Aether API V3 search for 'event_exhibit_tracking' has a backend bug injecting 'event_id_random'.
+## 🤝 Coordination & Continuity
+- **Handshake:** Use the `message` tool to notify the Backend Agent of UI/Data requirements.
+- **Active Tasks:** Track your progress in `documentation/AGENT_TODO.md`.
+- **Reference:** See `README.md` for build/deploy steps and `TODO.md` for project milestones.

TODO.md

@@ -29,40 +29,32 @@ This is a list of tasks to be completed before the next event/show/conference.
     - [x] **Session Search:** Modernized logic, fixed layout bugs and icon exports. (Completed 2026-01-27)
     - [x] **Exhibit Search:** Standardized Exhibitor and Lead Tracking reactive search. (Completed 2026-01-28)
 
-## Recent Accomplishments (Feb 10, 2026)
+## Recent Accomplishments (Feb 11, 2026)
 
 - **AE Events Launcher Stabilization:**
-    - [x] **'download' Filename Bug:** Resolved issue where files were downloaded as generic 'download' by explicitly passing `filename` to the API and implementing a safety net in `api_get_object.ts`.
-    - [x] **Global Page State Migration:** Refactored menu components (`menu_session_list.svelte`, `menu_location_list.svelte`, `launcher_menu.svelte`) to use Svelte 5's reactive `page` state instead of obsolete `data_url` props.
-    - [x] **Native Bridge Hardening:** Implemented SHA-256 integrity checks, stale `.tmp` purge, and "Safe Handover" pattern in the native Electron bridge.
-    - [x] **UI/UX Refinements:** Initialized `event_session_id` to `null` and added explicit "No session selected" prompts to improve the empty-state experience.
+    - [x] **Session Selection Hang Resolved:** Implemented "Navigation Shield" and "Side-Effect Purge" patterns across `launcher/+layout.svelte`, `launcher_session_view.svelte`, and `menu_session_list.svelte` to eliminate circular reactivity loops.
+    - [x] **Lucide Icon Stabilization:** Fixed missing/incorrect imports and usage in `ae_comp__event_files_upload.svelte`.
+    - [x] **Menu Responsiveness:** Reduced hover delay in `menu_session_list.svelte` from 1250ms to 750ms for snappier feedback.
+    - [x] **Code Integrity:** Reached zero-error state in `npm run check` for launcher components.
 
-## Urgent Tasks (Feb 10, 2026)
+## Urgent Tasks (Feb 11, 2026)
 
 1.  **AE Events Launcher Hardening:**
-    - [ ] **Session Selection Hang:** Investigate why the page fails to load or hangs after selecting a session when starting from a path without an initial ID. (Current Attempt: Derived LiveQuery vs state-driven subscription).
     - [ ] **Temp Cleanup:** Implement auto/manual removal of `[tmp]` files older than 24 hours.
     - [ ] **Recording Access:** Add button to open `[recording]` directory in Finder (macOS).
     - [ ] **JWT Lifecycle:** Implement silent auto-refresh for long-running podium sessions.
-    - [ ] **Native Actuators:** Plan macOS-specific commands for window focus and system orientation.
     - [ ] **Self-Update:** Implement simple directory/URL-based auto-update mechanism.
-    - [x] **Audit:** Marked `electron_native.js` as `[DEPRECATED]` in favor of active native repo logic.
-    - [x] **Telemetry:** Made CPU Load gauge dynamic using real-time `loadavg` data.
 
 1.  **IDAA Module Verification:**
     - [ ] **Bulletin Board (BB):** 90-95% Ready for Beta Test.
         - [x] Verify Post/Comment create/edit (Resolved IntegrityErrors).
-        - [x] Loading Optimization: Simplified `+page.ts` fetches.
         - [ ] Verify anonymous toggle and hide/priority admin flags.
         - [ ] Test file attachments on Posts.
     - [x] **Archives:** Tested and working well. (Completed 2026-02-09)
-    - [ ] **Recovery Meetings:** 
-        - [ ] Verify all search filters.
-        - [ ] Audit full editing workflow (70% done).
-        - [ ] Verify special code/copy buttons for Zoom/Jitsi.
+    - [x] **Recovery Meetings:** Verified all search filters, editing workflow, and special code buttons. (Completed 2026-02-11)
 
 2.  **Events - Badges:** Partially editable; needs full field implementation.
-    - [ ] **Rendering:** Verify Badge Template pulling and correct rendering.
+    - [ ] **Badge Rendering:** Resolve badge preview template failure (event_badge_template corrupted IDs).
     - [ ] **Editing:** Convert manual `editable_` fields and placeholders to `Element_ae_crud_v2` for robust field editing (Full Name, Title, Affiliations, etc.).
 
 3.  **Events - Leads/Tracking:** 80-90% done; ready for demo. (Pausing until later this week/next week)

documentation/AGENT_TODO.md

@@ -0,0 +1,19 @@
+# Frontend Agent Task List
+> Use this file to track steps for complex features or bug fixes.
+> **Status:** 🔵 Active - Launcher Stabilization complete.
+
+## 📋 Active Task: Badge Rendering Fix
+- [ ] **Step 1:** Investigate `event_badge_template` table for corrupted numeric IDs.
+- [ ] **Step 2:** Verify Pydantic model alignment in backend for Badge types.
+- [ ] **Step 3:** Implement field editing for "Full Name", "Title", "Affiliations" using `Element_ae_crud_v2`.
+- [ ] **Step 4:** Coordination (Handshake with Backend regarding MariaDB schema integrity).
+- [ ] **Step 5:** Finalize & Commit.
+
+## 🚧 Upcoming High Priority
+- **CRUD v2 Refactor:** Implement V3 API alignment for `Element_ae_crud_v2.svelte`.
+- **Temp Cleanup:** Auto-removal of native `.tmp` files older than 24h.
+
+## 📝 Session Notes (Feb 11, 2026)
+- **Resolved:** Launcher Session Selection Hang.
+- **Pattern:** Implemented "Navigation Shield" and "Side-Effect Purge" to stop reactivity loops.
+- **Linter:** Fixed missing Lucide icon imports.

documentation/GUIDE__DEVELOPMENT.md

@@ -0,0 +1,33 @@
+# Aether Development SOP (Frontend)
+> **Version:** 1.0 (2026-02-11)
+> **Location:** documentation/GUIDE__DEVELOPMENT.md
+
+## 1. 🛡️ Verification (The "Test-First" Mandate)
+**Rule:** No code is to be committed unless it has passed local verification. Skipping this is a violation of the Aether Dev Protocol.
+
+### Required Checks:
+1. **Svelte Integrity:** `npx svelte-check`
+2. **Type Safety:** Ensure interfaces in `src/lib/types/ae_types.ts` match backend schemas.
+3. **Reactivity Check:** Verify Svelte 5 runes (`$state`, `$derived`) are not creating race conditions with Dexie `liveQuery`.
+4. **Build Check:** For major changes, run `npm run build` to ensure no SSR or build-time failures.
+
+## 2. 📝 Commit & Sync Policy
+- **Atomic Commits:** One component or one logic fix per commit. Do not batch unrelated changes.
+- **Verification Log:** Mention the verification steps taken in your work log (`ae_log_work`).
+- **Safety:** Use `~/tmp/gemini_trash` for removals; never use `rm` directly on source files.
+
+## 3. 🤝 The Handshake (Coordination)
+You are not working in a vacuum. You MUST coordinate with the Backend Agent.
+
+### Mandatory Messaging Triggers:
+- **Data Requirements:** When a UI feature requires a new field or endpoint.
+- **API Failures:** When a V3 endpoint returns unexpected data or 500s.
+- **Status:** Update your shared Journal in `~/agents_sync/aether/journals/` after significant milestones.
+
+**Tool:** Use the `message` tool to communicate with the Backend Agent.
+
+## 🧠 Continuity
+Before starting work:
+1. Read `~/agents_sync/README.md` to understand the fleet status and cross-agent tasks.
+2. Check `README.md` in the project root for technical specs.
+3. Review your local `documentation/AGENT_TODO.md` for active tasks.