docs: Update GEMINI.md with session learnings

GEMINI.md

@@ -1,12 +1,86 @@
 # Gemini Added Memories
 
-## Learnings from session (December 3, 2025):
+## My Role and Operating Principles
+
+I am an interactive CLI agent assisting with software engineering tasks for One Sky IT, LLC, primarily on the Aether API project. My core mandates include:
+-   Adhering to project conventions and existing code style.
+-   **Never assuming library/framework availability; always verifying project usage.**
+-   Implementing changes idiomatically and with minimal, high-value comments.
+-   Being proactive, including adding tests for new features/fixes.
+-   **Confirming ambiguity or actions beyond clear scope with the user.**
+-   Prioritizing user control and project conventions.
+-   **Strictly adhering to instructions and utilizing available tools effectively.**
+-   **Awaiting explicit user instructions for significant architectural changes or critical decisions.**
+
+## Project Context - Aether API (FastAPI)
+
+-   **Owner/Developer:** Scott Idem (user).
+-   **System Name:** Aether (AE).
+-   **Purpose:** Events Presentation Management, Events Badge Printing, Leads, Attendee Tracking, Presentation Launcher, Journals, Archives, Posts.
+-   **Started:** Mid-2018.
+-   **Frontend History:** Python Flask -> Svelte (current: SvelteKit). This explains legacy API calls.
+-   **Current API Version (FastAPI):** Roughly v2.5.
+-   **Target API Version:** v3.
+
+### API Versioning & Strategy
+
+-   `/crud` (v1): Legacy, still used by some older frontend parts. Defined in `app/routers/api_crud.py`. **Remains untouched.**
+-   `/v2/crud` (v2.5): Modern, preferred, and mostly functional endpoint. Defined in `app/routers/api_crud_v2.py`. **Remains untouched.**
+-   `/v3/crud`: The goal of this project phase. A new, parallel implementation with a refined structure. **Will run alongside v1 and v2.**
+
+### V3 Architectural Goals
+
+-   **Nested URL Structure:** Enforce hierarchical relationships (e.g., `/v3/crud/{parent_type}/{parent_id}/{child_type}/...`).
+-   **Dedicated Router:** All v3 functionality will reside in `app/routers/api_crud_v3.py`.
+-   **Data-Driven Configuration:** Leverage `obj_type_kv_li` in `app/ae_obj_types_def.py` for object definitions (tables, models).
+
+## Session Learnings & Progress (December 3, 2025)
+
+### Strategy Shift & V3 Development
+
+*   **Initial Plan Shift:** The strategy shifted from *migrating/replacing* existing v1/v2 routes to *building a new, parallel v3 implementation* from scratch. All existing v1/v2 routes will remain untouched.
+*   **V3 Stub Endpoint (Phase 1 Completed):** Successfully created `app/routers/api_crud_v3.py` and mounted it at `/v3/crud` in `app/main.py` with a working `/health` endpoint.
+
+### V3 CRUD Proof-of-Concept (Journal & Journal Entry - Phase 2 & 3 Completed)
+
+Implemented the full CRUD functionality for `journal` (top-level) and `journal_entry` (nested child object), demonstrating the v3 nested URL structure and its underlying logic:
+*   **Top-Level Journal CRUD:**
+    *   `GET /v3/crud/journal/{journal_id}`
+    *   `GET /v3/crud/journal/` (list, with filtering via `for_obj_type`, `for_obj_id`, and `jp`)
+    *   `POST /v3/crud/journal/`
+    *   `PATCH /v3/crud/journal/{journal_id}`
+    *   `DELETE /v3/crud/journal/{journal_id}`
+*   **Nested Journal Entry CRUD:**
+    *   `GET /v3/crud/journal/{journal_id}/journal_entry/` (list)
+    *   `POST /v3/crud/journal/{journal_id}/journal_entry/`
+    *   `GET /v3/crud/journal/{journal_id}/journal_entry/{entry_id}`
+    *   `PATCH /v3/crud/journal/{journal_id}/journal_entry/{entry_id}`
+    *   `DELETE /v3/crud/journal/{journal_id}/journal_entry/{entry_id}`
+
+### V3 CRUD Refinements
+
+*   **Soft-Delete Functionality:** `DELETE` endpoints now support a `method` query parameter (`delete`, `disable`, `hide`) for soft-deleting (setting `enable=False` or `hide=True`) or hard-deleting records, mirroring v2 behavior.
+*   **Optional Delay Parameter:** All v3 CRUD functions include `x_delay_ms` (header) and `delay_ms` (query) parameters for simulating network latency or rate limiting via `time.sleep()`.
+
+### Current Task: Common Parameters Refactoring (Reverted)
+
+*   **Goal:** Refactor the current monolithic `commons: Common_Route_Params` dependency into smaller, more granular FastAPI dependencies.
+*   **Status:** A full-scale refactoring was attempted, introducing a new `app/lib_general_v3.py` file and modifying `api_crud_v3.py`, `main.py`, and `models/response_models.py`. This resulted in persistent "Worker failed to boot" errors that were difficult to debug without direct log access. The changes were reverted to a known working commit (`98b980cf`) to restore application functionality.
+
+### Operational Learnings
 
 *   **File Location:** The `GEMINI.md` file must always be located in the project root directory.
-*   **V2 CRUD Endpoint:** API simplification will be centered around the generic `/v2/crud` endpoint defined in `app/routers/api_crud_v2.py`. This is the modern, preferred implementation over the v1 endpoint in `api_crud.py`.
+*   **Communication for Major Refactoring:** For significant architectural changes, explicit user approval of a detailed proposal is required before implementation begins.
-*   **Data-Driven Configuration:** The v2 endpoint is highly modular and configured via the `obj_type_kv_li` dictionary in `app/ae_obj_types_def.py`. This dictionary acts as a central registry, mapping URL object strings to their corresponding database tables, Pydantic models, and export configurations. New simple CRUD objects can be added just by updating this dictionary.
+*   **Documentation Strategy:** Major proposals will be documented in dedicated Markdown files within the `documentation/` directory to facilitate clear communication and asynchronous feedback.
-*   **Complex Filtering with `jp`:** The generic list handler (`handle_get_obj_li`) supports advanced filtering. While it has basic support for foreign key lookups via `for_obj_type` and `for_obj_id` parameters, more complex queries, such as those involving polymorphic relationships (e.g., filtering `journal` by a `user` using `for_type` and `for_id` columns), must be handled by the client. The client should construct and send a custom query using the powerful `jp` (JSON payload) query parameter.
+*   **Startup Errors & Logging:** The "worker failed to boot" error is highly indicative of an import-time error (e.g., circular dependency, missing module, or misconfiguration). A common cause is the logging configuration in `app/log.py` failing due to an uninitialized setting or file path issue.
-*   **Migration Plan Focus:** The user prefers to remain in a planning and documentation phase. The immediate goal is to update the `API_SIMPLIFICATION_PLAN.md` with detailed migration steps, rather than executing code changes directly.
+*   **Refactoring Strategy - Incremental Approach Required:** The "big bang" approach to refactoring proved difficult to debug. A more incremental strategy is required for the next attempt:
+    1.  **Isolate Logging:** First, refactor all modules (e.g., `main.py`, `models/response_models.py`) to instantiate their own module-level logger (`logger = logging.getLogger(__name__)`) instead of importing a global `log` instance from `app.log`. This will break potential circular dependencies related to logging.
+    2.  **Introduce Dependencies One-by-One:** Introduce new dependencies from `lib_general_v3.py` one at a time.
+    3.  **Apply to One Endpoint:** Apply each new dependency to a single, simple endpoint (like `health_check`) and confirm the application boots.
+    4.  **Verify at Each Step:** This incremental verification is crucial in an environment without direct, real-time log access.
+*   **Preservation of Work:** The attempted refactoring work has been preserved in `.snapshot` files for future reference.
+
+---
 
 ## Learnings from previous session (December 2, 2025):
 
@@ -18,6 +92,4 @@
 *   **Pydantic `BaseModel` Import:** Simple Pydantic `BaseModel` imports can be forgotten, leading to `NameError`. This highlights the need for automated linting or a minimal test harness that can quickly validate new model definitions in isolation.
 *   **Legacy Code vs. New Code:** When encountering errors, it's crucial to distinguish whether the error is in the new code being introduced or in existing legacy code that might have subtle interactions. The `422 Unprocessable Entity` errors were occurring in the legacy `/crud/` endpoints. This indicates that while our new factory code *itself* didn't cause those specific runtime errors, interactions or an underlying pre-existing issue became apparent when the application was loading.
 *   **`parent_table_name` for Nested CRUD:** The implementation detail of passing `parent_table_name` (or similar context) to child CRUD operations is essential for correctly linking nested resources in the database layer. The router factory's child object creation needs to pass this context explicitly.
-*   **API Endpoint Naming Convention:** The user prefers singular nouns for API endpoints (e.g., `/journal`, `/journal_entry`) over plural forms (e.g., `/journals`, `/journal_entries`). This convention will be followed for all new router creations.
+*   **API Endpoint Naming Convention:** The user prefers singular nouns for API endpoints (e.g., `/journal`, `/journal_entry`) over plural forms (e.g., `/journals`, `/journal_entries`). This convention will be followed for all new router creations.
-
----