diff --git a/docs/hardware/reference.md b/docs/hardware/reference.md
new file mode 100644
index 0000000..bd6a65a
--- /dev/null
+++ b/docs/hardware/reference.md
@@ -0,0 +1,52 @@
+# Hardware reference — boma
+
+> Hand-maintained source of truth for **physical** compute + network gear and
+> **workload placement intent**. The two machine-readable tables (Node capacity,
+> Workload placement) are parsed by `scripts/capacity-scan.py` — keep their
+> headers intact. Evaluated by `/capacity-review`. See ADR-012.
+>
+> _Status: skeleton. Replace example rows with real hardware once the cluster is
+> stood up (STATUS.md tracks real-vs-planned)._
+
+## 1. Physical compute
+
+### pve0
+- **Model / form factor:** _TBD (e.g. Minisforum MS-01, mini-PC)_
+- **CPU:** _TBD (e.g. i9-13900H, 14C/20T)_
+- **RAM:** _TBD total; max _; free DIMM slots _
+- **Storage:** _TBD (disks → pools, e.g. 2× 2 TB NVMe → `local-zfs`)_
+- **NICs:** _eno1 trunk (vmbr0), eno2 corosync (vmbr1)_
+- **Notes:** _warranty, quirks_
+
+_(repeat for pve1, pve2, askari)_
+
+## 2. Network gear
+
+| device   | model | ports | poe | throughput | uplinks | notes |
+|----------|-------|-------|-----|------------|---------|-------|
+| opnsense | _TBD_ | _TBD_ | n/a | _TBD_      | WAN+LAN | dedicated hardware |
+| switch   | _TBD_ | _TBD_ | _TBD_ | _TBD_    | trunk   | managed, 802.1q |
+| ap1      | _TBD_ | _TBD_ | _TBD_ | _TBD_    | trunk   | multi-SSID per VLAN |
+
+## 3. Workload placement & intent
+
+The numeric columns (`cores, ram_mb, disk_gb`) feed `capacity-scan.py`; the
+free-text columns feed `/capacity-review`'s judgement.
+
+| workload | node | cores | ram_mb | disk_gb | criticality | ha_intent | profile | constraints | growth |
+|----------|------|-------|--------|---------|-------------|-----------|---------|-------------|--------|
+| dns1     | pve0 | 1     | 512    | 10      | high        | pair/dns2 | tiny/steady | anti-affinity: dns2 on a different node | flat |
+| dns2     | pve1 | 1     | 512    | 10      | high        | pair/dns1 | tiny/steady | anti-affinity: dns1 on a different node | flat |
+
+## 4. Node capacity (machine-readable)
+
+Physical totals per node. Integers; `ram_gb` and `disk_gb` may be decimals.
+
+| node | cores | ram_gb | disk_gb |
+|------|-------|--------|---------|
+| pve0 | 20    | 64     | 4000    |
+| pve1 | 20    | 64     | 4000    |
+
+## 5. Capacity notes
+
+Free-text running notes for the evaluator (trends, planned moves, upgrade ideas).
diff --git a/docs/hardware/reviews/.gitkeep b/docs/hardware/reviews/.gitkeep
new file mode 100644
index 0000000..e69de29