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


### [2026-10-29] Deploy cgit + fcgiwrap & Dedicated `git` SSH Server
- **Agent Action:**
  - Enabled `cgit_enabled: true` in `group_vars/all/vars.yml`.
  - Expanded `roles/cgit` to install `cgit`, `fcgiwrap`, `python3-pygments`, `python3-markdown`, and `python3-docutils`.
  - Provisioned dedicated `git` system user/group (`999:989`, home `/srv/git`, shell `/usr/bin/git-shell`) with SSH `authorized_keys` and custom `git-shell-commands` (`init` and `list`).
  - Added `www-data` to the `git` group and configured `/var/www/.gitconfig` (`safe.directory = *`) so `cgit`/`fcgiwrap` can read bare repositories in `/srv/git`.
  - Configured `/etc/cgitrc` with HTTP clone support (`enable-http-clone=1`), syntax highlighting, and README rendering.
  - Deployed `/etc/nginx/sites-available/cgit.conf` (and enabled symlink) for `git.miguelpedro.xyz.br`, blocking `git-receive-pack` over HTTP (`403`) and auto-upgrading to TLS once the Certbot certificate for `git.miguelpedro.xyz.br` is present.
- **Verification:** Applied `ansible-playbook site.yml --tags "cgit" --diff`, verified `cgit v1.2.3` HTTP response, CSS delivery, and `ssh git@miguelpedro.xyz.br list`, and confirmed full idempotency (`ok=42 changed=0`).