diff --git a/README.md b/README.md
index e69de29..44bbd31 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,98 @@
+kpr-genesis — Git‑Driven KPR Proxmox Automation
+===================================================
+
+**kpr-genesis** is both the runner and the repository that keep your Arch‑based Proxmox homelab declarative. A push to the `main` branch triggers:
+
+1.  **Terraform** – provisions / reconciles LXCs on Proxmox.
+2.  **Ansible** – installs Docker, then deploys services in those LXCs.
+
+The first wired‑in service is the Rust paste‑bin [w4/bin](https://github.com/w4/bin).
+
+Repository Layout
+-----------------
+
+kpr-genesis/
+├─ scripts/
+│   └─ run\_pipeline.sh        # git‑pull → terraform apply → ansible
+├─ terraform/                 # infra layer (Proxmox provider)
+│   ├─ main.tf
+│   ├─ variables.tf
+│   ├─ versions.tf
+│   └─ (no outputs – DHCP IP comes from Ansible)
+└─ ansible/
+    ├─ inventory.proxmox.yml  # dynamic inventory (Proxmox API)
+    ├─ ansible.cfg            # points to the inventory above
+    ├─ requirements.yml       # galaxy roles / collections
+    ├─ site.yml               # top‑level playbook
+    ├─ group\_vars/
+    │   └─ all.yml
+    └─ roles/
+        ├─ docker/
+        │   └─ tasks/main.yml
+        └─ bin/
+            ├─ tasks/main.yml
+            └─ templates/docker-compose.yml.j2
+
+Prerequisites
+-------------
+
+*   Proxmox VE 8.x with an API token that has at least **PVEAdmin** on `/` (`root@pam!kpr-genesis` in the samples).
+*   Arch Linux LXC named `kpr-genesis` with `terraform`, `ansible-core`, `python-proxmoxer`, and `python-requests` installed.
+*   Public SSH key committed as `id_ed25519.pub` (Terraform injects it into each new container).
+*   Webhook from your Gitea server hitting `http://kpr-genesis.<lan>:9000/hook`.
+
+First‑Time Setup
+----------------
+
+\# clone the repo as the 'infra' user
+```
+git clone https://tetera.kernelpanic.lol/ozymandias/kpr-genesis
+cd kpr-genesis
+```
+
+# install Ansible roles / collections
+`ansible-galaxy install -r ansible/requirements.yml`
+
+# export the Proxmox token
+`export PROXMOX\_TOKEN=<PROXMOX TOKEN HERE>``
+
+# run the pipeline once
+```
+export TF_VAR_pm_api_url=https://<PROXMOX IP HERE>:8006/api2/json
+export TF_VAR_pm_user=root@pam
+export TF_VAR_pm_token=<PROXMOX TOKEN HERE>
+export TF_VAR_node=pacifica
+export TF_VAR_bin_lxc_password='<PASSWORD HERE>'
+export PROXMOX_TOKEN=<PROXMOX TOKEN HERE>
+
+./scripts/run_pipeline.sh
+```
+
+
+Terraform creates a DHCP LXC named **bin**; Ansible installs Docker inside it and starts the `w4/bin` container on port 8000.
+
+Workflow
+--------
+
+1.  Edit Terraform or Ansible files.
+2.  Commit and push to `main`.
+3.  Webhook triggers pipeline; infrastructure converges.
+
+Adding a Service
+----------------
+
+1.  Add a `proxmox_lxc` block in `terraform/main.tf`.
+2.  Create a role under `ansible/roles/` and reference it in `site.yml`.
+3.  Commit & push — pipeline handles the rest.
+
+Secrets
+-------
+
+Only public keys live in Git. The Proxmox token is supplied via the `PROXMOX_TOKEN` environment variable (or through Ansible Vault if preferred).
+
+Troubleshooting
+---------------
+
+*   `ansible-inventory -i ansible/inventory.proxmox.yml --graph`
+*   `journalctl -u infra-hook` for pipeline logs
+*   `terraform state list` to inspect tracked resources