diff --git a/README.md b/README.md
index 5963968..1ac72e8 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,115 @@
 # homelab-infra
 
-Shared CI/CD workflow templates, base Dockerfiles, and compose snippets for all homelab projects
\ No newline at end of file
+Shared CI/CD templates, base Dockerfiles, and compose snippets for all
+homelab projects. Change once here, every project picks it up.
+
+## Repo structure
+
+```
+.gitea/workflows/
+  build-and-push.yml        ← reusable workflow (called by project repos)
+
+base-images/
+  python-git-ssh/
+    Dockerfile              ← Python 3.12 + git + openssh (build once)
+
+entrypoints/
+  git-pull-exec.sh          ← pull-before-exec entrypoint for live code updates
+
+compose-snippets/
+  watchtower.yml            ← auto-pull on image update
+  act_runner.yml            ← Gitea Actions self-hosted runner (deploy on Pi)
+```
+
+## How a project uses the shared workflow
+
+In your project repo, create `.gitea/workflows/build.yml`:
+
+```yaml
+name: Build
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    uses: thethreemagi/homelab-infra/.gitea/workflows/build-and-push.yml@main
+    with:
+      image_name: your-project-name
+    secrets:
+      REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+```
+
+Add two secrets to the project repo (Gitea → repo → Settings → Secrets):
+- `REGISTRY_USER` — your Gitea username (`thethreemagi`)
+- `REGISTRY_TOKEN` — a PAT with `write:packages` scope
+
+On push to `main`, the workflow builds a multi-tag image and pushes to
+`git.thewichersfamily.com/thethreemagi/your-project-name:latest`.
+
+## One-time server setup (Gitea + runner)
+
+### 1. Enable Actions in Gitea
+
+Edit your Gitea `app.ini` (check your Gitea compose volume mount for the path):
+
+```ini
+[actions]
+ENABLED = true
+```
+
+Restart Gitea: `docker compose restart gitea`
+
+### 2. Generate runner registration token
+
+Gitea → Site Administration → Actions → Runners → Create Runner → copy token.
+
+### 3. Deploy act_runner on Pi 5
+
+Copy `compose-snippets/act_runner.yml` to `/srv/act-runner/docker-compose.yml`.
+Add to `.env`:
+
+```
+RUNNER_TOKEN=<token from step 2>
+```
+
+```bash
+docker compose up -d
+```
+
+Verify: Gitea → Site Administration → Actions → Runners → `homelab-pi5` online.
+
+### 4. Generate registry PATs
+
+**Runner PAT** (push images):
+- Gitea → Settings → Applications → Generate Token → scope: `write:packages`
+- Set as `REGISTRY_TOKEN` secret in each project repo
+
+**Pi pull PAT** (Watchtower pulls):
+- Gitea → Settings → Applications → Generate Token → scope: `read:packages`
+- On Pi: `docker login git.thewichersfamily.com`
+
+### 5. Deploy Watchtower on Pi
+
+Use `compose-snippets/watchtower.yml`. Polls every 5 min, restarts containers on new image digest.
+
+## Adding a new project
+
+1. Ask Claude to create the repo via MCP (needs `write:user` scope on token)
+2. Claude adds `.gitea/workflows/build.yml` calling this shared workflow
+3. Add `REGISTRY_USER` + `REGISTRY_TOKEN` secrets to repo
+4. Update project `docker-compose.yml`: `image: git.thewichersfamily.com/thethreemagi/<name>:latest`
+5. Push — CI runs automatically
+
+## Runner note: ARM64 vs x86
+
+Runner runs on Pi 5 — native ARM64 builds, no QEMU needed.
+If moved to x86 NAS later, uncomment the QEMU steps in `build-and-push.yml`.
+
+## Requires Gitea 1.21+
+
+Reusable workflows require Gitea 1.21+.
+Check: Site Administration → Configuration → Gitea Version.