diff --git a/ai/plan.md b/ai/plan.md deleted file mode 100644 index ef1cb05..0000000 --- a/ai/plan.md +++ /dev/null @@ -1,114 +0,0 @@ -# AI Agent Infrastructure Strategy: Homelab Management - -This document establishes the architecture, workflow rules, and skill definitions for an AI agent to interface with the self-hosted environment using the Model Context Protocol (MCP) and local system aliases. - ---- - -## 1. Primary AI Workspace and Persistence Directive - -The agent must treat the `/srv/configs/ai` directory as its absolute source of truth for its own configuration, execution memory, and custom skill scripts. - -### Operational Rules - -* **Storage Location:** All agent workflows, system prompts, automated rules, markdown runbooks, and custom skill definitions *must* be stored in `/srv/configs/ai/`. -* **State Management:** Before executing any systemic infrastructure review, the agent must read the current context files in this directory to ensure it is operating under the latest user definitions. -* **No Side Effects:** The agent is strictly prohibited from writing or modifying configuration files outside of this path unless explicitly authorized by the user during an interactive session. - ---- - -## 2. Homelable MCP Server Integration - -The agent leverages the Model Context Protocol to interface directly with the `homelable-mcp` container running locally. This allows the agent to bind physical network topologies to visual infrastructure diagrams. - -### Connection Architecture - -* **Location:** Co-located on the same local host node. -* **Transport Method:** Server-Sent Events (SSE) or local port binding. -* **API Endpoint:** `http://localhost:8001` - -### Capabilities Matrix - -| Permission | Action | Operational Boundaries | -| ---------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | -| **Read** | List all nodes, edges, full canvas, pending devices, scan history. | Executed proactively during an audit cycle. | -| **Write** | Add/update/delete nodes and edges, trigger network scans, approve/hide discovered devices. | **DISABLED BY DEFAULT.** Requires explicit, per-action user confirmation. | - ---- - -## 3. Host System Execution Environment & Aliases - -The agent interacts with the host infrastructure by executing commands directly within the host shell session. It relies on system aliases defined in the central configuration file. - -* **Alias Configuration File:** `/srv/configs/.bash_aliases` - -### Required Core Aliases - -The agent must parse and respect the following explicit wrappers found in the alias file: - -* `docker-service`: Used to query container states, image updates, and running stacks. -* `nginx`: Used to inspect reverse proxy server blocks, active upstreams, and active domain routings. - ---- - -## 4. Skill Definition: Infrastructure Reconciliation & Audit - -### Skill Name - -`review_homelab_infrastructure` - -### Objective - -Cross-reference the active compute and reverse-proxy states against the `homelable` canvas topology and the primary markdown infrastructure log. - -### Source of Truth Inventory Documentation - -* **Target File:** `/srv/docs/public/projects/homelab/homelab_Infra.md` -* **Policy:** The agent must maintain and preserve the existing structural formatting of this file when suggesting updates. - -### Execution Workflow - -``` -[Trigger: Audit Command] - │ - ▼ -┌────────────────────────────────────────────────────────┐ -│ 1. Parse aliases via `/srv/configs/.bash_aliases` │ -│ 2. Read active inventory from `homelab_Infra.md` │ -│ 3. Fetch live container states via `docker-service` │ -│ 4. Fetch proxy mappings via host `nginx` commands │ -│ 5. Pull active topology via Homelable MCP (Port 8001) │ -└─────────────────────────┬──────────────────────────────┘ - │ - ▼ -┌────────────────────────────────────────────────────────┐ -│ Perform 3-Way Reconciliation │ -│ (homelab_Infra.md vs. Live States vs. MCP Canvas) │ -└─────────────────────────┬──────────────────────────────┘ - │ - ▼ -┌────────────────────────────────────────────────────────┐ -│ Generate Diff Report & Proposed Changes (Markdown) │ -└─────────────────────────┬──────────────────────────────┘ - │ - ▼ - { User Explicitly Approves? } - / \ - (Approved) (Denied) - / \ - ▼ ▼ -┌─────────────────────────┐ ┌─────────────────────────┐ -│ - Update MCP Canvas │ │ Abort & Log Audit │ -│ - Append/Modify │ │ Failure in Workspace │ -│ homelab_Infra.md │ │ (/srv/configs/ai/) │ -└─────────────────────────┘ └─────────────────────────┘ - -``` - -### Safety and Guardrails - -> [!IMPORTANT] -> **Strict Read-Only Default:** The agent is explicitly forbidden from making automatic writes or commits. -> * **No silent canvas updates:** Every node change, edge modification, or scan approval on the Homelable MCP requires manual confirmation. -> * **No silent documentation updates:** Under no circumstances should the agent modify `/srv/docs/public/projects/homelab/homelab_Infra.md` without presenting a clear diff block and receiving confirmation first. -> -> \ No newline at end of file