From bd4bd360f75e703199e8334c6cdfd1629cc60327 Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Wed, 19 Nov 2025 19:05:06 -0500
Subject: [PATCH] docs: Update project documentation and session notes

- Updates `GEMINI.md` with a detailed summary of the days debugging session for the v3 Badges page.
- Updates `TODO.md` to mark recent bug fixes as complete and adds new tasks for outstanding issues (e.g., `order_by_li` fix).
- Updates `ARCHITECTURE.md` to reflect the current state of the tech stack (Tailwind v4, component library status).
- Creates `README.md` files for the new v3 Badges module and the legacy Lead Retrieval module to clarify their purpose and status.
---
 ARCHITECTURE.md                               |  6 +-
 GEMINI.md                                     | 14 +++++
 TODO.md                                       |  3 +
 .../[event_id]/(badges)/badges/README.md      | 16 ++++++
 src/routes/events_leads/README.md             | 56 +++++--------------
 5 files changed, 49 insertions(+), 46 deletions(-)
 create mode 100644 src/routes/events/[event_id]/(badges)/badges/README.md

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 136e3b86..21702253 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -10,11 +10,11 @@ The Aether project is a Svelte and SvelteKit based application, utilizing Tailwi
 
 - **Frontend Framework:** Svelte 5 and SvelteKit v2
     - **Routing:** SvelteKit's file-system based routing.
-- **Styling:** Tailwind CSS 3.x (with plans to upgrade to 4.x when ShadCN is ready)
+- **Styling:** Tailwind CSS v4
 - **UI Component Libraries:**
-    - Skeleton (Design System, Tailwind Components, Functional Components - with plans to upgrade to v3)
+    - Skeleton (Design System, Tailwind Components, Functional Components - being phased out due to conflicts with Tailwind CSS v4)
     - Flowbite (Tailwind Components)
-    - **Note:** ShadCN is currently used but is planned for removal.
+    - Custom Components (a growing library of `ae_comp__*` and `element_*` components)
 - **Text/Code Editors:**
     - CodeMirror 6.x (primary text and code editor, planned for rich text editing)
     - Edra (TipTap based Rich Text Editor)
diff --git a/GEMINI.md b/GEMINI.md
index 1ddc7de6..daf915f9 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -148,3 +148,17 @@ To address issues with the Aether API's strict handling of `POST` and `PATCH` re
     - The `create_ae_obj__event` and `update_ae_obj__event` functions now use this whitelist to filter the `data_kv` object, ensuring only allowed fields are sent to the API. This provides a more maintainable and less error-prone way to manage which fields are sent to the API.
 - **Component Cleanup:** The temporary pre-cleaning logic from the `handle_save` function in `src/routes/events/[event_id]/settings/+page.svelte` has been removed, as the filtering is now handled centrally in `ae_events__event.ts`.
 - **Future Work:** This pattern of using a whitelist for editable fields will be applied to all other Aether object types to ensure consistent and correct API interactions across the application.
+
+### Badge Search v3 Bug-Fixing Session (2025-11-19)
+
+This session focused on resolving a series of cascading build and runtime errors that prevented the new "Badges v3" feature from loading and functioning correctly.
+
+- **Initial State:** The page was failing with a `Cannot use @variant with unknown variant: md` error, caused by a conflict between Skeleton UI's CSS and the project's Tailwind CSS v4 configuration.
+- **Misguided Fix & Reversal:** An initial attempt to fix this by removing all global Skeleton UI CSS imports from `app.css` resolved the `@variant` error but broke site-wide styling, causing errors like `Cannot apply unknown utility class 'preset-tonal-secondary'`. The Skeleton imports were subsequently restored to stabilize the application.
+- **Svelte v5 Event Syntax:** A significant amount of time was spent incorrectly attempting to "fix" Svelte v5 event handlers. The correct understanding was eventually established:
+    - **DOM Events:** Use the `onevent` prefix (e.g., `onclick`).
+    - **Component Events:** Continue to use the `on:event` directive (e.g., `on:success`).
+- **Invalid Attribute Name Error:** An error (`'onsubmit|preventDefault' is not a valid attribute name`) was discovered in the new badge forms. This was resolved by removing the `|preventDefault` modifier from the `onsubmit` attribute and instead calling `event.preventDefault()` inside the handler function. This appears to be a nuance or bug in how the Svelte v5 compiler handles modifiers with the new `on` prefix.
+- **Svelte 5 Binding Error:** A runtime error, `props_invalid_value: Cannot do bind:prop={undefined}`, was fixed. It was caused by binding a parent component's `undefined` store value to a child component's prop that had a fallback. The fix involved adding a defensive initialization check directly in the parent component's `<script>` block to ensure the store value was not `undefined` before rendering. Using `onMount` was attempted first but proved incorrect as it runs too late in the lifecycle.
+- **API Fetch Error:** The final blocker was a `TypeError: NetworkError` during badge searches. This was traced to the `order_by_li` parameter being sent to the API in a format that was causing the `fetch` request to be aborted by the browser (likely due to a CORS preflight failure). The immediate fix, identified by the user, was to comment out the `order_by_li` parameter in the `search__event_badge` function call within `src/lib/ae_events/ae_events__event_badge.ts`.
+- **Git Issues:** A strange issue was encountered where `git add` commands were not successfully staging files, leading to multiple failed commit attempts. This resolved itself without a clear cause.
diff --git a/TODO.md b/TODO.md
index 1602d1ea..9ec77d67 100644
--- a/TODO.md
+++ b/TODO.md
@@ -6,6 +6,7 @@ This is a list of tasks to be completed before the next event/show/conference.
 
 ## Recent Accomplishments
 
+- [x] **Badges v3:** Resolved a series of cascading build and runtime errors on the new badge search page. This involved restoring Skeleton CSS, fixing Svelte 5 event handler syntax (`onsubmit|preventDefault`), resolving a prop binding error (`props_invalid_value`), and temporarily disabling a problematic `order_by_li` API parameter to fix a network fetch error.
 - [x] **Refactoring:** Standardized data processing in `events`, `archives`, `posts`, and `sponsorships` modules using a new generic pattern.
 - [x] **Bug Fix:** Corrected data fetching logic for session-related presentations and files that were not displaying correctly due to `id` vs `id_random` issues.
 - [x] **Core:** Defined `Account`, `Site`, and `Site_Domain` interfaces in new files under `src/lib/ae_core/`.
@@ -65,6 +66,7 @@ This is a list of tasks to be completed before the next event/show/conference.
 
 ## Priority Tasks (Easy & Quick)
 
+- [ ] **API:** Properly investigate and fix the `order_by_li` parameter in the `search__event_badge` function. The parameter is currently commented out as a temporary workaround to prevent a network fetch error.
 - [ ] **Formatting:** Run `npm run format` to fix code style issues across the project.
 
 ---
@@ -267,6 +269,7 @@ These functions are frequently used and critical to the application's data flow.
     - **Wording:** Standardize the text used in common UI elements (e.g., "Save", "Cancel", "Delete", "Add New").
     - **Scope:** This should be done on a per-module basis to ensure local consistency, with a goal of achieving global consistency where possible.
     - **Note on IDAA:** The `idaa` modules are semi-custom for a client and may have their own specific UI/UX requirements. Their consistency should be evaluated separately, keeping the client's needs in mind.
+- [ ] **Component Migration:** Replace remaining Skeleton UI classes (e.g., `preset-tonal-*`, `variant-filled-*`) with standard Tailwind CSS to avoid CSS conflicts and dependency issues.
 
 ---
 
diff --git a/src/routes/events/[event_id]/(badges)/badges/README.md b/src/routes/events/[event_id]/(badges)/badges/README.md
new file mode 100644
index 00000000..81470c3e
--- /dev/null
+++ b/src/routes/events/[event_id]/(badges)/badges/README.md
@@ -0,0 +1,16 @@
+# Event Badges Module (v3)
+
+This directory contains the Svelte components and pages for the "v3" Badge Printing module for a specific event.
+
+## Key Features
+
+- **Search:** A reactive search page (`+page.svelte` and `ae_comp__badge_search.svelte`) for finding attendee badges.
+- **Printing:** Functionality for printing individual and lists of badges.
+- **CRUD Operations:** Components for creating, viewing, updating, and deleting badges.
+- **Templates:** A system for managing different badge layouts and templates.
+
+## Technical Notes
+
+- This module is built using Svelte 5 (runes) and Flowbite-Svelte for UI components.
+- It relies on the `events_func` and `ae_events__event_badge.ts` for its business logic and API communication.
+- The search functionality was recently debugged to resolve a series of build and runtime errors related to CSS conflicts, Svelte 5 reactivity, and API query parameter issues.
diff --git a/src/routes/events_leads/README.md b/src/routes/events_leads/README.md
index 2be80848..f5026587 100644
--- a/src/routes/events_leads/README.md
+++ b/src/routes/events_leads/README.md
@@ -1,48 +1,18 @@
-# Events - Leads Module
+# Event Lead Retrieval Module
 
-This document describes the **Events - Leads** module, which is a sub-module of the Events module. It provides a lead retrieval solution for exhibitors at an event.
+This directory contains the Svelte components and pages for the exhibitor Lead Retrieval module.
 
-## Overview
+## Key Features
 
-The Leads module allows exhibitors to capture, manage, and export leads from event attendees. It is designed to be used on a variety of devices, including desktops, tablets, and smartphones.
+- **Exhibitor Login:** Allows exhibitors to log in using a shared passcode or an individual license key (email).
+- **Lead Capture:** Provides an interface for adding new leads, either by scanning a badge QR code or by manual entry.
+- **Lead Management:** A list view for exhibitors to see all the leads they have collected.
+- **Lead Qualification:** Exhibitors can rank leads (sort) and mark them as priority (star).
+- **Data Export:** Functionality to export collected leads to an Excel file.
 
-## Data Models
+## Technical Notes
 
-The Leads module is based on two main data models:
-
-- **`EventExhibit`**: Represents an exhibitor at an event. It contains information about the exhibitor, such as their name, description, and booth number. It also includes configuration options for the lead retrieval service, such as custom questions and the number of licenses.
-- **`EventExhibitTracking`**: Represents a lead captured by an exhibitor. It links an exhibitor (`event_exhibit_id`) with an attendee's badge (`event_badge_id`) and includes fields for notes and responses to custom questions.
-
-## Features
-
-- **Authentication:** The module supports two types of authentication for exhibitor staff:
-    - **Shared Passcode:** A shared passcode can be used by all staff members of an exhibitor.
-    - **License-based:** Individual licenses can be assigned to staff members, each with their own email and passcode.
-- **Lead Capture:** Leads can be captured by:
-    - **Scanning QR Codes:** The module includes a QR code scanner that can be used to scan the QR code on an attendee's badge.
-    - **Manual Entry:** The attendee's badge ID can be entered manually.
-- **Lead Management:** The module provides a comprehensive interface for managing leads, including:
-    - Viewing a list of all captured leads.
-    - Viewing the details of a single lead.
-    - Adding notes to a lead.
-    - Answering custom questions for a lead.
-- **Lead Export:** Leads can be exported to a CSV or Excel file for further processing.
-- **License Management:** Exhibitors can manage their licenses, including adding, editing, and removing licenses.
-- **Client-Side Caching:** The module uses Dexie.js for client-side caching in IndexedDB, which improves performance and enables offline access.
-
-## UI Components
-
-The Leads module is composed of the following UI components:
-
-- **`exhibit/[slug]/+page.svelte`:** The main entry point for an exhibitor. It provides a tabbed interface for accessing the different features of the module.
-- **`exhibit/[slug]/leads_add_scan.svelte`:** A component for adding a new lead by scanning a badge or entering the badge ID manually.
-- **`exhibit/[slug]/leads_list.svelte`:** A component for viewing and managing the list of captured leads.
-- **`exhibit/[slug]/leads_manage.svelte`:** A component for managing the exhibitor's settings and exporting leads.
-- **`exhibit/[slug]/leads_view_lead.svelte`:** A component for viewing the details of a single lead.
-
-## How it Works
-
-1.  The exhibitor navigates to the `events_leads/exhibit/[slug]` page, where `[slug]` is their exhibitor ID.
-2.  They authenticate using either the shared staff passcode or their individual license.
-3.  They can then use the different tabs to capture new leads, manage their existing leads, and configure their settings.
-4.  All data is fetched from the API and cached in IndexedDB for offline access and faster loading times.
+- This is considered a legacy module but is still in active use and was recently updated to fix styling issues.
+- The UI was previously dependent on Skeleton UI classes. Recent fixes have replaced these with standard Tailwind CSS to resolve critical rendering errors caused by the removal of global Skeleton CSS.
+- The main entry point is `/events_leads`, which lists available exhibits.
+- Individual exhibitor functionality is handled under the `/events_leads/exhibit/[slug]` dynamic route.
\ No newline at end of file