1 files changed, 53 insertions, 0 deletions
diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md
new file mode 100644
index 0000000..45410d3
--- /dev/null
+++ b/AGENT_INSTRUCTIONS.md
@@ -0,0 +1,53 @@
+# AI Agent Instructions & Self-Updating Protocol
+
+This document defines the mandatory operating procedures and **Self-Updating Protocol** for any AI coding or DevOps agent working in this repository.
+
+---
+
+## 1. Core Principles
+
+1. **IaC is the Single Source of Truth:** Never make ad-hoc manual edits on `root@miguelpedro.xyz.br` without codifying them in the corresponding Ansible role under `roles/` or variables in `group_vars/all/`.
+2. **Protect Secrets:** Never write plaintext secrets to tracked files. Store all sensitive variables in `group_vars/all/vault.yml` (encrypted with `ansible-vault` using `.vault_pass`), and reference them in `group_vars/all/vars.yml` as `{{ vault_* }}`.
+3. **Check Before Apply:** Always run `.venv/bin/ansible-playbook site.yml --check --diff` and inspect the diff before applying changes to the live VPS.
+
+---
+
+## 2. Self-Updating Protocol (Mandatory for All Agent Sessions)
+
+Every AI agent session MUST execute this three-stage protocol:
+
+### Stage A: Pre-Flight State Verification (Start of Session)
+1. **Read Context:** Read [`README.md`](file:///home/mpedro/Repos/my-infra/README.md), [`DISCOVERY_REPORT.md`](file:///home/mpedro/Repos/my-infra/DISCOVERY_REPORT.md), and the latest entries in [` AGENT_INSTRUCTIONS.md` Changelog](#3-infrastructure-session-changelog) and [`COMMAND_LOG.md`](file:///home/mpedro/Repos/my-infra/COMMAND_LOG.md).
+2. **Detect Drift:** Run an Ansible dry-run against the VPS to verify whether the live state matches the repository:
+   ```bash
+   .venv/bin/ansible-playbook site.yml --check --diff
+   ```
+3. **Resolve Drift:** If unexpected drift is detected on the VPS (e.g., Certbot updated a file or a manual hotfix was applied), inspect the remote file via SSH, inform the user, and backport the remote change into the Ansible templates before proceeding.
+
+### Stage B: Implementation & Verification (During Session)
+1. **Modify IaC:** Implement requested changes in `group_vars/all/vars.yml`, `group_vars/all/vault.yml` (via `ansible-vault`), or the appropriate role in `roles/<role_name>/`.
+2. **Dry-Run & Apply:**
+   - Test with `.venv/bin/ansible-playbook site.yml --check --diff`.
+   - Apply with `.venv/bin/ansible-playbook site.yml --diff`.
+   - Re-run `.venv/bin/ansible-playbook site.yml --check --diff` to confirm idempotency (`changed=0`).
+3. **Health Check:** Verify service health (`systemctl status nginx uwsgi valkey-server` or `curl -I`) on the VPS.
+
+### Stage C: Documentation & Log Update (Before Closing Session)
+Before ending your session or creating a final commit, you **MUST** update the repository documentation:
+1. **Append to [`COMMAND_LOG.md`](file:///home/mpedro/Repos/my-infra/COMMAND_LOG.md):** Add a dated section logging the key SSH/Ansible commands executed during your session and their outputs.
+2. **Update [`DISCOVERY_REPORT.md`](file:///home/mpedro/Repos/my-infra/DISCOVERY_REPORT.md):** If any new services, ports, paths, certificates, or configuration files were added, modified, or removed on the VPS, update the architecture diagram and Critical State Map table.
+3. **Update [`README.md`](file:///home/mpedro/Repos/my-infra/README.md):** If new roles, tags, or domains were introduced, update the Architecture table and Repository Structure tree.
+4. **Append to the [Infrastructure Session Changelog](#3-infrastructure-session-changelog) below:** Record a concise summary of what changed, why, and the resulting state.
+
+---
+
+## 3. Infrastructure Session Changelog
+
+### [2026-10-29] Initial Reverse-Engineering & Ansible IaC Baseline
+- **Agent Action:**
+  - Reverse-engineered live VPS state (`root@miguelpedro.xyz.br`, Debian 13 `trixie`).
+  - Documented full discovery findings in `DISCOVERY_REPORT.md` and command outputs in `COMMAND_LOG.md`.
+  - Established Ansible IaC baseline (`site.yml`, `inventory/hosts.yml`, `group_vars/all/vars.yml`, and `ansible-vault`-encrypted `group_vars/all/vault.yml`).
+  - Created roles for `common`, `certbot`, `valkey`, `searxng`, `nginx`, and scaffolded `cgit` (`cgit_enabled: false`) for upcoming deployment.
+  - Cleaned up unused Nginx stub symlink (`/etc/nginx/sites-enabled/miguelpedro.xyz.br` which pointed to `example.com`) via `nginx_remove_unused_sites`.
+- **Verification:** Verified playbook against live VPS with `ansible-playbook site.yml --check --diff`.