From f465af0c0c4b9cd1bf3c59a9b8581948d2d30a00 Mon Sep 17 00:00:00 2001
From: Rongsong Shen <rshen@shenrs.eu>
Date: Fri, 29 May 2026 10:57:09 +0000
Subject: [PATCH] docs(ha-config-bootstrap): add initial cluster config
 installation steps

---
 .../specs/ha-config-bootstrap/manual-tests.md | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/.kiro/specs/ha-config-bootstrap/manual-tests.md b/.kiro/specs/ha-config-bootstrap/manual-tests.md
index 0ce8c517..5f9a58bb 100644
--- a/.kiro/specs/ha-config-bootstrap/manual-tests.md
+++ b/.kiro/specs/ha-config-bootstrap/manual-tests.md
@@ -84,6 +84,36 @@ done
 > All nodes share the same self-signed cert so they mutually trust each other.
 > In production each node has its own cert signed by a shared CA.
 
+### Initial Cluster Configuration (required)
+
+The controller looks for its cluster config at:
+```
+{workdir}/{myname}/conf/current          ← pointer file (contains the config filename)
+{workdir}/{myname}/conf/cluster.bin.<hex_tag>  ← actual capnp config blob
+```
+
+The `<hex_tag>` is the first 8 bytes of the SHA-256 of the config blob, as 16 hex digits.
+
+**Steps (using your existing config file):**
+
+```bash
+# 1. Compute the config tag from your config blob
+TAG=$(sha256sum /path/to/your_config.bin | awk '{print $1}' | cut -c1-16)
+echo "Config tag: $TAG"
+
+# 2. Install config into each node's workdir
+for node in a b c; do
+  NODE_NAME="ctrl-${node}"
+  CONF_DIR="/tmp/xce-${node}/${NODE_NAME}/conf"
+  mkdir -p "$CONF_DIR"
+  cp /path/to/your_config.bin "${CONF_DIR}/cluster.bin.${TAG}"
+  printf "cluster.bin.${TAG}" > "${CONF_DIR}/current"
+done
+```
+
+> The `current` file must contain exactly the filename (no trailing newline,
+> no path separators). `printf` (not `echo`) avoids the trailing newline.
+
 ### Start the 3-node cluster (3 terminals)
 
 **Terminal 1 — Node A (priority 0 = highest):**