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

GEMINI.md

@@ -1,110 +1,37 @@
-# Gemini Agent Context: Aether API Orchestrator
+# Aether Backend Agent Context: Gemini CLI Standard
+> **Role:** Aether API Orchestrator (Backend & System Architecture)
+> **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:** Aether API Orchestrator (mcp_agent)
-- **Primary Role:** Backend Development, System Orchestration, and API Stabilization.
-- **Scope:** `/home/scott/OSIT_dev/aether_api_fastapi` and Aether Platform backend infrastructure.
-
-### 👤 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 (Ubuntu/Arch context)
-
-### 🏗️ Aether Architecture (V3)
-- **Concept:** Unified AI-driven platform for business/personal management.
-- **Backend:** FastAPI (v4.9.0) + Pydantic V1 + SQLAlchemy + MariaDB (Remote).
-- **V3 Implementation:** Modern parallel CRUD and Search endpoints under `/v3/crud`.
-- **Core Principle:** "Agent Bridge" - Distributed agents coordinating via file-based messaging (`~/agents_sync`).
-
-### 📜 Core Protocols
-- **RAR Protocol:** Request -> Ack -> Result.
-- **V3 CRUD Paradigm:** JSON metadata via `/v3/crud/`, binary actions (Upload/Download) via `/v3/action/`.
-- **Fail Fast & Transparently:** API returns `500` on hard errors; avoid silent failures (confirmed in `sql_select`).
-- **Bite-Sized Data:** Avoid monolithic files (>1MB).
-- **Source of Truth:** `~/agents_sync` is the shared brain. `~/OSIT_dev` is the local development environment.
-
-### 🛡️ Security & Secrets Guardrails
-- **Secrets:** NEVER read/display content from `.env` files unless explicitly debugging configuration logic.
-- **PII:** Scrub personally identifiable information if sharing logs or data across the bridge.
-- **Hiding Internal Paths:** `subdirectory_path` is hidden from public-facing API responses via Pydantic `Field(exclude=True)`.
-
-### 🧠 Key Technical Learnings (Cumulative)
-- **Modularization Standard**: Proven pattern for shrinking monolithic routers: Registry -> `app/object_definitions/`, Templates/Logic -> `app/methods/`. Reduced `api_crud.py` and `hosted_file.py` by >75%.
-- **Vision ID Persistence**: Pydantic `Field(exclude=True)` strips fields from `.dict()` by default. In methods like `create_hosted_file_obj`, these must be explicitly re-included if they are internal DB fields (like `subdirectory_path`).
-- **Universal ID Resolution**: `GET /v3/action/hosted_file/{id}/download` now intelligently resolves container IDs (`event_file`, `archive_content`) to physical binaries.
-- **Temporary Access Patterns**: Implemented `?key=` and `?site_key=` (using `access_key`) for unauthenticated Read-Only file access to unblock frontend components like `<img>`.
-- **ID Vision Standardization**: Standardized Event and CMS models to clean string IDs. Learned that `root_validator(pre=True)` must be hardened during the "Create" phase to prevent deleting integer IDs resolved by `sanitize_payload`.
-- **Relational View Joins**: Established that account context for child objects (like `post_comment`) should be inherited via SQL `INNER JOIN` in the view (`v_post_comment`) rather than duplicating columns in the physical table.
+## 🚨 MANDATORY PROTOCOL
+You must follow the safety, testing, and coordination standards defined in:
+`documentation/GUIDE__DEVELOPMENT.md`
 
 ---
 
-## 2. 🗓️ Near Term Memory (Strategic Context)
+## 🏗️ Technical Domain: Aether Backend
+### Stack & Infrastructure
+- **API Framework:** FastAPI (v0.95+)
+- **Validation:** Pydantic V1 (Strict)
+- **Database:** MariaDB + SQLAlchemy (v1.4+)
+- **ID Standard:** "ID Vision" - Public String IDs (`id_random`) mapping to hidden Internal Integer IDs.
+- **Communication:** RAR Protocol (Request -> Ack -> Result).
 
-*This section tracks active projects (1-2 weeks scope). It answers "Why are we doing this?"*
+### V3 CRUD Architecture
+- Enforce parallel CRUD and Search under `/v3/crud/`.
+- **Registry Pattern:** Object definitions in `app/object_definitions/`, logic in `app/methods/`.
+- **Visibility:** Use `Field(exclude=True)` in Pydantic to hide internal paths from public output.
 
-### 🎯 Strategic Goals (Current Sprint)
-- **Primary:** OSIT_dev Environment Optimization & Context Stabilization (Template v1.2 Adoption).
-- **Secondary:** ID Vision Phase 2 Migration and V3 API Migration (Contacts/Clients).
-- **Active:** Zoom Events Integration for upcoming Lead Retrieval/Badge Printing demo.
+### Specialized Logic
+- **Universal ID Resolution:** Resolve container IDs (e.g., `event_file`) to physical binaries in actions.
+- **Relational Joins:** Prefer SQL `INNER JOIN` in Views (`v_`) over duplicating columns in tables.
+- **Heal-on-Read:** Standardize fallback resolution for relational IDs during GET operations.
 
-### 🚧 Active Workstreams
-- **[Aether V4]:** Architecture standards formalized in `ARCH__V4_CORE_STANDARDS.md`. Ready for lifecycle field migration (post-V3).
-- **[Zoom Events]:** initial integration complete (OAuth2, Sync logic, Ticket retrieval). Pending real credentials.
-- **[Refactor]:** Reduced monolithic files (>800 lines). `api_crud.py` and `hosted_file.py` COMPLETED. `api_crud_v2.py` and `person_methods.py` PENDING.
-- **[ID Vision]:** Standardized Event and CMS (Post/Comment) models to clean string IDs.
+## 🧠 Technical Learnings
+- **Harden `root_validator`:** Ensure pre-validation logic doesn't delete integer IDs during ID Vision resolution.
+- **Pydantic worker boot failures:** Watch for `ValueError`, `NameError`, and `KeyError` during startup.
+- **Inherited Context:** Account context for child objects should be inherited via View joins.
 
----
-
-## 3. 🧠 Short Term Memory (Session Context)
-
-*This section is the "Scratchpad" for the current interaction. It is cleared or summarized often.*
-
-- **Status:** Operational / Demo Ready (Badges & Leads)
-- **Last Action:** Finalized 'Heal-on-Read' fallback resolution for relational IDs.
-- **Achievements:** 
-    - Verified 100% pass rate on `test_e2e_v3_demo_parity.py`.
-    - Hardened Badge, Exhibit, Tracking, and Event File models against integer leakage.
-    - Implemented `POST /v3/action/event_file/from_hosted_file/{id}` specialized action.
-    - Documented Object Alias and specialized action support in Frontend API Guide.
-    - Fixed Pydantic worker boot failures (`ValueError`, `NameError`, `KeyError`).
-- **Immediate Next Step:** Finalize Audit of remaining models for ID Vision compliance.
-
----
-
-## 4. 📂 Reference: Directory & Whitelist
-*Low-density reference data. Keep at the bottom to avoid cluttering the prompt's "hot zone".*
-
-### 🛡️ File Whitelist
-- `~/tmp`
-- `~/OSIT_dev/aether_api_fastapi`
-- `~/agents_sync`
-
-### 🗺️ Standard Directory Map
-- **`app/methods/`**: Object-specific business logic.
-- **`app/models/`**: Pydantic schemas.
-- **`app/object_definitions/`**: V3 Metadata definitions.
-- **`app/routers/`**: API endpoints.
-
-### 📋 Aether API Development Protocol
-0. **Pre-Flight Check:** Verify `git status`. Ensure all previous working changes are committed.
-1. **Strategic Plan:** Write a concise plan identifying the issue, specific files, and verification steps (curl commands/test scripts).
-2. **Implementation:** Perform atomic code modifications using `replace` or `write_file`.
-3. **Syntax Validation:** Run `python3 -m py_compile <modified_file>` immediately.
-4. **Process Cycle:** Restart the Docker FastAPI service: `docker restart aether_container_env-ae_api-2`.
-5. **Empirical Testing:** Execute `curl` commands and inspect logs: `tail -n 20 ~/OSIT_dev/aether_container_env/logs/ae_api/aether_api.log`.
-6. **Finalize:** Commit changes with a descriptive message and sync documentation.
+## 🤝 Coordination & Continuity
+- **Handshake:** Use the `message` tool to notify the Frontend Agent of API changes.
+- **Active Tasks:** Track your progress in `documentation/AGENT_TODO.md`.
+- **Learning:** Review `ARCH__V3_CORE_STANDARDS.md` for V4 lifecycle field migration planning.

documentation/AGENT_TODO.md

@@ -0,0 +1,19 @@
+# Backend Agent Task List
+> Use this file to track steps for complex features or bug fixes.
+> **Status:** 🔵 Active - ID Vision Phase 2 complete.
+
+## 📋 Active Task: ID Vision Audit & Compliance
+- [ ] **Step 1:** Audit remaining MariaDB models for ID Vision compliance.
+- [ ] **Step 2:** Harden `root_validator(pre=True)` on remaining models to prevent integer leakage.
+- [ ] **Step 3:** Refactor `api_crud_v2.py` and `person_methods.py` (Reduce file size < 800 lines).
+- [ ] **Step 4:** Coordination (Handshake with Frontend regarding "Badge Rendering" corrupted IDs).
+- [ ] **Step 5:** Finalize & Commit.
+
+## 🚧 Upcoming Strategic Goals
+- **Zoom Events Integration:** Implement cron synchronization for OAuth2 ticket retrieval.
+- **Aether V4 Architecture:** Migration to V4 core standards (Lifecycle fields).
+
+## 📝 Session Notes (Feb 11, 2026)
+- **Resolved:** Finalized 'Heal-on-Read' fallback resolution for relational IDs.
+- **Verification:** `test_e2e_v3_demo_parity.py` verified at 100% pass rate.
+- **Optimization:** Refactored `api_crud.py` and `hosted_file.py` to Registry pattern.

documentation/GUIDE__DEVELOPMENT.md

@@ -0,0 +1,35 @@
+# Aether Development SOP (Backend)
+> **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. **Syntax Validation:** `python3 -m py_compile <file_path>`
+2. **Linting/Style:** `flake8 <file_path>`
+3. **Pydantic Validation:** If changing models, verify with `app/models/` scripts.
+4. **Service Health:** Restart the service and check logs:
+   - `docker restart aether_container_env-ae_api-2`
+   - `tail -n 50 ../aether_container_env/logs/ae_api/aether_api.log`
+
+## 2. 📝 Commit & Sync Policy
+- **Atomic Commits:** One feature or one bug 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 Frontend Agent.
+
+### Mandatory Messaging Triggers:
+- **API Changes:** When changing an endpoint signature, payload, or ID format.
+- **Bugs:** When discovering a cross-stack issue.
+- **Status:** Update your shared Journal in `~/agents_sync/aether/journals/` after significant milestones.
+
+**Tool:** Use the `message` tool to communicate with the Frontend 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.