From bc2aaff089f50ab7a6ddb5d9d216fb8cac0caa7a Mon Sep 17 00:00:00 2001
From: Rongsong Shen <rshen@shenrs.eu>
Date: Fri, 29 May 2026 10:59:51 +0000
Subject: [PATCH] =?UTF-8?q?docs(ha-config-bootstrap):=20only=20primary=20n?=
 =?UTF-8?q?eeds=20initial=20config=20=E2=80=94=20standbys=20get=20it=20via?=
 =?UTF-8?q?=20replication?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../specs/ha-config-bootstrap/manual-tests.md | 37 ++++++++++---------
 1 file changed, 20 insertions(+), 17 deletions(-)

diff --git a/.kiro/specs/ha-config-bootstrap/manual-tests.md b/.kiro/specs/ha-config-bootstrap/manual-tests.md
index 5f9a58bb..da349139 100644
--- a/.kiro/specs/ha-config-bootstrap/manual-tests.md
+++ b/.kiro/specs/ha-config-bootstrap/manual-tests.md
@@ -84,35 +84,38 @@ 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)
+### Initial Cluster Configuration (primary node only)
 
-The controller looks for its cluster config at:
+Thanks to config replication, **only the primary node (ctrl-a) needs the initial
+config file.** Nodes B and C start with `config_tag=0`, defer the config fetch,
+yield the election to the primary, and automatically receive the config via
+`push_config_to_standbys()` after catch-up.
+
+The controller looks for config at:
 ```
-{workdir}/{myname}/conf/current          ← pointer file (contains the config filename)
-{workdir}/{myname}/conf/cluster.bin.<hex_tag>  ← actual capnp config blob
+{workdir}/{myname}/conf/current                    ← pointer file
+{workdir}/{myname}/conf/cluster.bin.<hex_tag>      ← capnp config blob
 ```
 
-The `<hex_tag>` is the first 8 bytes of the SHA-256 of the config blob, as 16 hex digits.
+The `<hex_tag>` is the first 16 hex chars of the SHA-256 of the config blob
+(= first 8 bytes).
 
-**Steps (using your existing config file):**
+**Install config on Node A only:**
 
 ```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
+CONF_DIR="/tmp/xce-a/ctrl-a/conf"
+mkdir -p "$CONF_DIR"
+cp /path/to/your_config.bin "${CONF_DIR}/cluster.bin.${TAG}"
+printf "cluster.bin.${TAG}" > "${CONF_DIR}/current"
 ```
 
-> The `current` file must contain exactly the filename (no trailing newline,
-> no path separators). `printf` (not `echo`) avoids the trailing newline.
+> `printf` (not `echo`) avoids a trailing newline that would corrupt the pointer.
+>
+> Nodes B and C need **no** config pre-installed — they will receive it from
+> the primary automatically after election completes.
 
 ### Start the 3-node cluster (3 terminals)