From f785907792f20ec7475b7e6df861ac23dfeecc08 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Wed, 11 Feb 2026 17:59:09 -0500 Subject: [PATCH] Updating the documentation for things. Hopefully improvements to Gemini CLI. --- GEMINI.md | 198 +++--------------- TODO.md | 24 +-- documentation/AGENT_TODO.md | 19 ++ .../GEMINI_Flowbite_upgrade_2025-12.md | 0 .../GEMINI_SkeletonLabs_upgrade_2025-12.md | 0 .../GEMINI_Svelte_and_Me.md | 0 .../GEMINI_debug_notes.md | 0 documentation/GUIDE__DEVELOPMENT.md | 33 +++ 8 files changed, 90 insertions(+), 184 deletions(-) create mode 100644 documentation/AGENT_TODO.md rename GEMINI_Flowbite_upgrade_2025-12.md => documentation/GEMINI_Flowbite_upgrade_2025-12.md (100%) rename GEMINI_SkeletonLabs_upgrade_2025-12.md => documentation/GEMINI_SkeletonLabs_upgrade_2025-12.md (100%) rename GEMINI_Svelte_and_Me.md => documentation/GEMINI_Svelte_and_Me.md (100%) rename GEMINI_debug_notes.md => documentation/GEMINI_debug_notes.md (100%) create mode 100644 documentation/GUIDE__DEVELOPMENT.md diff --git a/GEMINI.md b/GEMINI.md index 72314850..fc1c57c6 100644 --- a/GEMINI.md +++ b/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'. \ No newline at end of file +## 🀝 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. diff --git a/TODO.md b/TODO.md index 999d9c34..75be5956 100644 --- a/TODO.md +++ b/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) diff --git a/documentation/AGENT_TODO.md b/documentation/AGENT_TODO.md new file mode 100644 index 00000000..590685d6 --- /dev/null +++ b/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. diff --git a/GEMINI_Flowbite_upgrade_2025-12.md b/documentation/GEMINI_Flowbite_upgrade_2025-12.md similarity index 100% rename from GEMINI_Flowbite_upgrade_2025-12.md rename to documentation/GEMINI_Flowbite_upgrade_2025-12.md diff --git a/GEMINI_SkeletonLabs_upgrade_2025-12.md b/documentation/GEMINI_SkeletonLabs_upgrade_2025-12.md similarity index 100% rename from GEMINI_SkeletonLabs_upgrade_2025-12.md rename to documentation/GEMINI_SkeletonLabs_upgrade_2025-12.md diff --git a/GEMINI_Svelte_and_Me.md b/documentation/GEMINI_Svelte_and_Me.md similarity index 100% rename from GEMINI_Svelte_and_Me.md rename to documentation/GEMINI_Svelte_and_Me.md diff --git a/GEMINI_debug_notes.md b/documentation/GEMINI_debug_notes.md similarity index 100% rename from GEMINI_debug_notes.md rename to documentation/GEMINI_debug_notes.md diff --git a/documentation/GUIDE__DEVELOPMENT.md b/documentation/GUIDE__DEVELOPMENT.md new file mode 100644 index 00000000..1d256b2f --- /dev/null +++ b/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.