# 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.
> 
>