diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1e42df4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# homelab
+
+Infrastructure-as-Code for a 3-machine homelab running K3s.
+
+## Status
+
+| Phase | Description | Status |
+|---|---|---|
+| 0 | Backup configs, init repo | ✅ Done |
+| 1 | Bootstrap Minisforum — K3s server + Traefik | ✅ Done |
+| 2 | Join Debian as K3s agent, SMB setup | ⏳ Next |
+| 3 | Deploy core infra — Gitea, Pi-hole, DDNS | 🔜 Planned |
+| 4 | Deploy app services — Jellyfin, qBittorrent, etc. | 🔜 Planned |
+| 5 | Networking cutover | 🔜 Planned |
+| 6 | Cleanup legacy Debian services | 🔜 Planned |
+
+## Architecture
+
+| Machine | IP | SSH Port | Role | Status |
+|---|---|---|---|---|
+| Minisforum UM780 XTX | 192.168.7.77 | 430 | K3s server | ✅ Running — K3s + Traefik |
+| Debian Server (HP ProDesk) | TBD | — | K3s agent | ⏳ Phase 2 |
+| Mac Mini M2 | TBD | — | Standalone | ⏳ Phase 3+ |
+
+## Repo Structure
+
+```
+ansible/
+  inventory.yml            # host definitions
+  playbooks/               # top-level playbooks
+  roles/
+    common/                # base OS setup (users, SSH, UFW, packages)
+    k3s-server/            # K3s server install + Helm
+    k3s-agent/             # K3s agent join (Phase 2)
+    smb/                   # Samba on Debian (Phase 2)
+helm/                      # custom Helm charts (if needed; most use upstream charts)
+values/                    # Helm values files per service
+scripts/                   # deploy-all.sh, porkbun-ddns.sh
+old.debian-data/           # gitignored — backup of pre-migration configs
+```
+
+## Prerequisites
+
+- Ansible installed on your workstation: `pip install ansible`
+- Ansible collections: `ansible-galaxy collection install community.general ansible.posix`
+- SSH key at `~/.ssh/id_ed25519-nik-macbookair`
+
+## Connecting
+
+```bash
+# SSH
+ssh minisforum   # port 430, configured via ~/.ssh/config
+
+# Kubectl (after fetching kubeconfig)
+export KUBECONFIG=/tmp/k3s-minisforum.yaml
+kubectl get nodes
+kubectl get pods -A
+```
+
+## Deploying / Re-deploying
+
+```bash
+# Re-run bootstrap (idempotent)
+ansible-playbook -i ansible/inventory.yml ansible/playbooks/bootstrap-minisforum.yml
+
+# Re-run K3s setup (idempotent)
+ansible-playbook -i ansible/inventory.yml ansible/playbooks/setup-k3s.yml
+
+# Upgrade Traefik
+helm upgrade --install traefik traefik/traefik \
+  --namespace traefik --create-namespace \
+  -f values/traefik.yml
+```
+
+## See Also
+
+- [migration-plan.md](migration-plan.md) — full phase-by-phase migration plan
diff --git a/manifests/gitea-pv.yml b/manifests/gitea-pv.yml
new file mode 100644
index 0000000..4646567
--- /dev/null
+++ b/manifests/gitea-pv.yml
@@ -0,0 +1,23 @@
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: gitea-pv
+  labels:
+    app: gitea
+spec:
+  capacity:
+    storage: 10Gi
+  accessModes:
+    - ReadWriteOnce
+  persistentVolumeReclaimPolicy: Retain
+  hostPath:
+    path: /data/gitea
+    type: DirectoryOrCreate
+  nodeAffinity:
+    required:
+      nodeSelectorTerms:
+        - matchExpressions:
+            - key: kubernetes.io/hostname
+              operator: In
+              values:
+                - minisforum
\ No newline at end of file
diff --git a/values/gitea.yml b/values/gitea.yml
new file mode 100644
index 0000000..412dacc
--- /dev/null
+++ b/values/gitea.yml
@@ -0,0 +1,72 @@
+# Gitea Helm values
+# Deploy:
+#   helm upgrade --install gitea gitea-charts/gitea \
+#     --namespace gitea --create-namespace \
+#     -f values/gitea.yml
+
+replicaCount: 1
+
+image:
+  tag: "1.23"
+
+ingress:
+  enabled: true
+  className: traefik
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: websecure
+    traefik.ingress.kubernetes.io/router.tls: "true"
+  hosts:
+    - host: gitea.home.arpa
+      paths:
+        - path: /
+          pathType: Prefix
+
+gitea:
+  admin:
+    username: nik
+    password: changeme123
+    email: nik.afiq98@ymail.com
+
+  config:
+    server:
+      DOMAIN: gitea.home.arpa
+      ROOT_URL: https://gitea.home.arpa
+      SSH_DOMAIN: gitea.home.arpa
+      SSH_PORT: 2222
+    repository:
+      DEFAULT_PRIVATE: true
+    service:
+      DISABLE_REGISTRATION: true
+
+persistence:
+  enabled: true
+  storageClass: ""
+  accessModes:
+    - ReadWriteOnce
+  size: 10Gi
+  volumeName: ""
+  existingClaim: ""
+  annotations:
+    helm.sh/resource-policy: keep
+
+postgresql:
+  enabled: true
+  primary:
+    persistence:
+      annotations:
+        helm.sh/resource-policy: keep
+  global:
+    postgresql:
+      auth:
+        password: gitea-db-password
+        username: gitea
+        database: gitea
+
+service:
+  ssh:
+    type: LoadBalancer
+    port: 2222
+    loadBalancerIP: 192.168.7.77
+
+postgresql-ha:
+  enabled: false
\ No newline at end of file