feat(iac): establish Ansible baseline for Nginx, SearXNG, Valkey, and Certbot

- Reverse-engineer live Debian 13 (trixie) VPS state at miguelpedro.xyz.br
- Add modular Ansible roles: common, certbot, valkey, searxng, and nginx
- Encrypt SearXNG secret_key using ansible-vault in group_vars/all/vault.yml
- Cleanly remove unused example.com Nginx stub symlink (sites-enabled/miguelpedro.xyz.br)
- Scaffold cgit + fcgiwrap role (cgit_enabled: false) for upcoming deployment
- Add DISCOVERY_REPORT.md, COMMAND_LOG.md, README.md, and AGENT_INSTRUCTIONS.md with Self-Updating Protocol

1 files changed, 96 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..770013d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# `miguelpedro.xyz.br` Infrastructure-as-Code (IaC)
+
+This repository manages the configuration and state of the `miguelpedro.xyz.br` VPS (Debian 13 `trixie`) using **Ansible** and **Ansible Vault**.
+
+---
+
+## 1. Architecture & Managed Services
+
+| Service | Domain / Endpoint | Role | Description |
+| :--- | :--- | :--- | :--- |
+| **Nginx** | `miguelpedro.xyz.br`<br>`searx.miguelpedro.xyz.br` | [`roles/nginx`](file:///home/mpedro/Repos/my-infra/roles/nginx/tasks/main.yml) | Reverse proxy, TLS termination, and static web server |
+| **Certbot** | `/etc/letsencrypt/` | [`roles/certbot`](file:///home/mpedro/Repos/my-infra/roles/certbot/tasks/main.yml) | Automated Let's Encrypt ECDSA certificate management (`certbot.timer`) |
+| **SearXNG** | `https://searx.miguelpedro.xyz.br/` | [`roles/searxng`](file:///home/mpedro/Repos/my-infra/roles/searxng/tasks/main.yml) | Privacy-respecting metasearch engine served via `uwsgi` Unix socket |
+| **Valkey** | `127.0.0.1:6379` | [`roles/valkey`](file:///home/mpedro/Repos/my-infra/roles/valkey/tasks/main.yml) | Local key-value store backing SearXNG's rate limiter and bot detection |
+| **cgit** *(Prepared)* | `git.miguelpedro.xyz.br` | [`roles/cgit`](file:///home/mpedro/Repos/my-infra/roles/cgit/tasks/main.yml) | Ready-to-enable role (`cgit_enabled: false`) for self-hosted Git web UI via `fcgiwrap` |
+
+---
+
+## 2. Repository Structure
+
+```text
+my-infra/
+├── ansible.cfg                 # Ansible configuration (inventory, roles_path, vault_password_file)
+├── site.yml                    # Main playbook entrypoint
+├── inventory/
+│   └── hosts.yml               # Target VPS inventory (root@miguelpedro.xyz.br)
+├── group_vars/
+│   └── all/
+│       ├── vars.yml            # Global non-sensitive variables & feature flags
+│       └── vault.yml           # AES-256 encrypted secrets (ansible-vault)
+├── roles/
+│   ├── common/                 # System packages & build dependencies
+│   ├── certbot/                # Let's Encrypt packages, timer, and cert checks
+│   ├── valkey/                 # Valkey server installation & systemd service
+│   ├── searxng/                # SearXNG user, git checkout, settings.yml, limiter.toml, uwsgi ini
+│   ├── nginx/                  # nginx.conf, vhost templates, clean sites-enabled management
+│   └── cgit/                   # Prepared role for upcoming cgit + fcgiwrap deployment
+├── AGENT_INSTRUCTIONS.md       # Operational guide & Self-Updating Protocol for AI agents
+├── DISCOVERY_REPORT.md         # Reverse-engineered state map of the VPS
+└── COMMAND_LOG.md              # Running log of discovery and verification commands
+```
+
+---
+
+## 3. Usage & Operations
+
+### Prerequisites
+A local Python virtual environment (`.venv`) with `ansible-core` is pre-configured in this repository, along with a git-ignored `.vault_pass` file for automatic decryption of `group_vars/all/vault.yml`.
+
+If setting up on a new machine:
+```bash
+python3 -m venv .venv
+.venv/bin/pip install ansible-core
+# Place your Ansible Vault password in .vault_pass (chmod 600 .vault_pass)
+```
+
+### Dry-Run (Check for Configuration Drift)
+Always run in `--check --diff` mode first to preview changes without modifying the VPS:
+```bash
+.venv/bin/ansible-playbook site.yml --check --diff
+```
+
+### Apply Changes
+```bash
+.venv/bin/ansible-playbook site.yml --diff
+```
+
+### Run Specific Roles via Tags
+```bash
+.venv/bin/ansible-playbook site.yml --tags "nginx" --diff
+.venv/bin/ansible-playbook site.yml --tags "searxng" --diff
+```
+
+### Managing Secrets (`ansible-vault`)
+Sensitive values (such as `vault_searxng_secret_key`) are encrypted in [`group_vars/all/vault.yml`](file:///home/mpedro/Repos/my-infra/group_vars/all/vault.yml).
+- **View encrypted secrets:**
+  ```bash
+  .venv/bin/ansible-vault view group_vars/all/vault.yml
+  ```
+- **Edit encrypted secrets:**
+  ```bash
+  .venv/bin/ansible-vault edit group_vars/all/vault.yml
+  ```
+
+---
+
+## 4. Deploying `cgit` (Upcoming)
+
+The `cgit` role ([`roles/cgit`](file:///home/mpedro/Repos/my-infra/roles/cgit/tasks/main.yml)) is already scaffolded. When ready to deploy:
+1. Ensure DNS for `cgit_domain` (default `git.miguelpedro.xyz.br`) points to the VPS.
+2. In [`group_vars/all/vars.yml`](file:///home/mpedro/Repos/my-infra/group_vars/all/vars.yml), set:
+   ```yaml
+   cgit_enabled: true
+   ```
+3. Run `.venv/bin/ansible-playbook site.yml --tags "cgit" --diff`.
+4. Provision TLS via Certbot (`certbot --nginx -d git.miguelpedro.xyz.br`) and update [`roles/cgit/templates/site-cgit.conf.j2`](file:///home/mpedro/Repos/my-infra/roles/cgit/templates/site-cgit.conf.j2) to include the SSL directives.