# Specification: Unified Aether AI Agent (UE-AE-01)

## 1. Vision & Purpose
The **Unified Aether AI Agent** is a single, cohesive AI entity designed to eliminate the friction of multi-agent coordination. It possesses "Total System Awareness," allowing it to understand how a change in the database schema on a remote server impacts the FastAPI backend, the Nginx proxy, and the SvelteKit frontend simultaneously.

---

## 2. System Architecture & Operational Domains

### A. Data Layer (MariaDB)
*   **Location:** Separate Virtual Server (Remote VM).
*   **Role:** Master data storage.
*   **Agent Access Requirements:**
    *   Remote SQL execution capabilities.
    *   SSH access for database maintenance and schema inspection.
    *   Knowledge of cross-server connection strings and security groups.

### B. Caching & Messaging Layer (Redis)
*   **Location:** Docker Container (Main Workstation).
*   **Role:** Session management, ID resolution (Random ID mapping), and real-time messaging.
*   **Agent Access Requirements:**
    *   Ability to execute `redis-cli` commands via Docker.
    *   Direct inspection of key-value pairs for troubleshooting.

### C. API Backend Layer (FastAPI / Python)
*   **Location:** Docker Container (Main Workstation).
*   **Role:** Business logic, CRUD V3 implementation, JWT authentication, and multi-tenant isolation.
*   **Agent Access Requirements:**
    *   Full filesystem access to `osit-api-fastapi/`.
    *   Ability to manage Python environments and dependencies.
    *   Docker container management (logs, restarts, shell execution).

### D. Frontend Layer (SvelteKit / TypeScript)
*   **Location:** Local Filesystem (Main Workstation).
*   **Role:** User Interface, API consumption, and client-side state management.
*   **Agent Access Requirements:**
    *   Full filesystem access to SvelteKit project directories.
    *   Ability to execute build tools (npm, vite) and linting (eslint, prettier).
    *   Browser automation for E2E testing (Playwright).

### E. Routing Layer (Nginx)
*   **Location:** Host System or Docker.
*   **Role:** SSL termination and reverse proxying for the API and Frontend.
*   **Agent Access Requirements:**
    *   Ability to modify and reload Nginx configuration files.
    *   Diagnostic access to Nginx access/error logs.

### F. Storage Layer (Syncthing / Hosted Files)
*   **Location:** `/home/scott/OSIT/hosted_files/` (Main Workstation) and synchronized Remote Servers.
*   **Role:** Extremely important persistent storage for files served via the API (e.g., `hosted_file`, `event_file`).
*   **API-Driven Access:** Files are frequently accessed/downloaded directly via API endpoints. The agent must understand the routing and security logic (JWT validation) governing these downloads.
*   **Synchronization:** Managed via **Syncthing** (similar to the `agents_sync` directory), ensuring real-time mirroring across the Aether ecosystem.
*   **Agent Access Requirements:**
    *   Full filesystem access to the local hosted files directory.
    *   Ability to verify synchronization status and resolve conflicts.
    *   Understanding of the relationship between file metadata in MariaDB and physical assets in this directory.

### G. Workstation Development Environment
*   **Base Path:** `/home/scott/OSIT_dev/`
*   **Project Repositories:**
    *   `aether_container_env/`: Docker Compose and environment configuration.
    *   `aether_api_fastapi/`: The Python/FastAPI backend source.
    *   `ae_app_svelte_tailwind_skeleton/`: The SvelteKit/TypeScript frontend source.
*   **Network & Proxy Path:**
    *   Docker containers on the workstation are proxied via **Nginx on a separate Home Server** (Proxmox VM hosting Home Assistant, Jellyfin, Jitsi, etc.).
    *   **External Access URL:** `https://dev-api.oneskyit.com`
*   **Agent Access Requirements:**
    *   Total awareness of the inter-connected paths between these three main directories.
    *   Knowledge of the home server's proxy logic to debug external connectivity vs. internal container health.

---

## 3. Communication & Context Strategy

### A. Integrated Global Memory
The Unified Agent will move away from separate `GEMINI.md` files in favor of a **Global System Context**. This context tracks:
1.  **Service Map:** Mapping of ports, paths (e.g., `/v3/crud/`), and container IDs.
2.  **Dependency Graph:** Visualizing how modules across different repositories interact.
3.  **Boot Order Logic:** Understanding the fragile initialization requirements of the stack.

### B. Agent Sync Orchestration
The agent acts as the primary orchestrator for the `~/agents_sync/` directory:
-   **Log Aggregation:** Pulling logs from MariaDB, FastAPI, and Nginx into a central diagnostic stream.
-   **Inbound Messaging:** Processing user instructions from the `inbox/` and updating "System Health" status files.

---

## 4. Key Capabilities

1.  **Cross-Stack Debugging:** Tracing a "500 Internal Server Error" from a Svelte fetch call, through the Nginx proxy, into the FastAPI logic, and finally identifying the missing column in the remote MariaDB table.
2.  **Automated Schema Synchronization:** Reading Pydantic models and MariaDB table schemas to automatically generate and update TypeScript interfaces and `.editable_fields.ts` definitions in the Svelte project (`src/lib/ae_core/`).
3.  **Log Stream Aggregation:** Simultaneous monitoring of Svelte console output, Nginx access/error logs, and FastAPI container logs to provide instant root-cause identification for cross-stack failures.
4.  **Automated Lifecycle Management:** Orchestrating the "Change-Restart-Verify" loop. The agent should automatically trigger targeted Docker container restarts whenever backend code is modified to ensure the frontend is always interacting with the latest logic.
5.  **Environment-Aware Refactoring:** Safely breaking up monolithic files (like `lib_general.py`) while knowing exactly which services are impacted and verifying them across the full stack.
6.  **Automated Full-Stack Verification:** Writing a backend migration and a frontend UI component in a single turn, then verifying the integration with an automated test suite.

---

## 5. Security & Safety
-   **Credential Isolation:** Secrets and API keys remain in `.env` files; the agent only manages the logic to use them.
-   **Incremental Deployment:** Changes are applied service-by-service with health checks at every stage.
-   **Sandboxing Awareness:** The agent operates with the knowledge that it is running directly on the user's workstation and remote infrastructure.