update documents

.kiro/steering/build-deployment.md

@@ -2,7 +2,7 @@
 
 ## Philosophy
 
-A single Heremetic build system (Meson + Nix flakes) produces all artifacts — C daemons, Go binaries, AppImage. Every build includes debug symbols + ASAN. Tests run as part of the build, not after. Deployment for HA testing uses a scripted local cluster with per-node data directories and cert management.
+A single Heremetic build system (Meson + Nix flakes) produces all artifacts — C daemons, Go binaries, AppImage. Only the `asan` profile (the default for `/xce-build`) includes both debug symbols and ASAN; `debug` builds symbols without ASAN, and `release` builds (including the nix `xcecore` production package) carry neither. Tests run as part of the build, not after. Deployment for HA testing uses a scripted local cluster with per-node data directories and cert management.
 
 ## Build Commands
 
@@ -16,6 +16,7 @@ All builds use `/xce-build` (skill at `.claude/skills/xce-build/`):
 /xce-build worker       # lib + worker (daemon only, no unit tests)
 /xce-build apiserver    # lib + apiserver + xcecli + Go unit tests
 /xce-build xcecli       # xcecli + Go tests
+/xce-build xceadmin     # xceadmin (meson-driven; builds src/xceadmin's venv/tests)
 ```
 
 `controller` always builds `xce_test` alongside `xce_controller` — the driver `/xce-test-ha` needs, in every profile below. There is no separate build step for it.
@@ -23,7 +24,7 @@ All builds use `/xce-build` (skill at `.claude/skills/xce-build/`):
 Each invocation:
 1. `nix develop` into the hermetic shell
 2. `meson setup <dir> --buildtype=<type> -Db_sanitize=<mode>` (fresh clean build)
-3. `ninja -C <dir>` (compile all + test executables)
+3. `meson compile -C <dir> [targets...]` — per-component invocations pass an explicit target list scoped to just that component (e.g. `controller` compiles only `xce_controller controller_unit_test controller/xce_test`); only `/xce-build all` compiles with no target args, building everything
 4. Run registered meson tests (skipped for non-`asan` profiles — see below)
 
 **Three profiles, three build dirs** (`/xce-build [component] [profile]`, second arg optional): `asan` (default, debug+ASAN, `xce.build/`, runs the meson test suite) for everyday development and CI-style verification; `debug` (`-O0 -g3` no sanitizer, `build.dbg/`, build-only) for gdb/core-dump root-causing of heisenbugs that ASAN's allocator perturbs away; `release` (`-O3` no sanitizer, `build.release/`, build-only) for soak/perf runs against production-shaped binaries. Each profile's own dir means the three never clobber each other — a `debug` rebuild doesn't invalidate an `asan` binary already in use.
@@ -41,9 +42,10 @@ src/
 ├── controller/meson.build         # xce_controller daemon + controller_unit_test
 ├── worker/meson.build             # xcecd daemon
 ├── scheduler/meson.build          # scheduler daemon + test
-├── autoscaler/meson.build         # autoscaler daemon
+├── autoscaler/meson.build         # libscaler static lib + provider tools (no daemon binary)
 ├── frontend/apiserver/meson.build # Go apiserver via tools/go_build
-└── frontend/xcecli/meson.build    # Go xcecli via tools/go_build
+├── frontend/xcecli/meson.build    # Go xcecli via tools/go_build
+└── xceadmin/meson.build           # xceadmin config-build tool (used by /xce-deploy-ha)
 ```
 
 **Dependency flow**: `lib → {controller, worker, scheduler, apiserver}`
@@ -51,8 +53,7 @@ src/
 **Test registration**:
 ```python
 # controller/meson.build
-test('controller',
-     controller_unit_test,
+test('controller test', controller_unit_test,
      suite: 'controller',
      timeout: 300,
      env: ['ASAN_OPTIONS=detect_leaks=0'])
@@ -71,7 +72,7 @@ nix build .#xcecore_debug  # default package: debug + ASAN
 nix build .#xcecli    # CLI only
 ```
 
-**AppImage**: The flake produces an AppImage wrapping `xce` (shell entry point) with bundled daemons, haproxy, glow, and less. The entry script reads from `/tools/appimage/entry.sh`.
+**AppImage**: `nix build .#xcecore`/`.#xcecore_debug` do not produce an AppImage — they only install `xce` (a copy of `tools/appimage/entry.sh`, see `src/meson.build`) as a plain shell entry-point binary. The `xce` flake package (`appImageEntryPackage` in `src/flake.nix`) wraps that entry script with bundled daemons, haproxy, glow, and less; the actual `.AppImage` file is produced separately with `nix bundle --bundler github:ralismark/nix-appimage --option sandbox false .#xce` (see README.md, "3.5 build AppImage package").
 
 ## Local HA Cluster Deployment
 
@@ -86,7 +87,7 @@ This creates under `/tmp/xce-deploy/`:
 certs/                          # TLS certs for all peers
 controller/
   ctrl-1/
-    conf/{current, cluster.bin} # primary's config
+    conf/{current, cluster.bin.<tag>} # primary's config (tag = sha256sum prefix)
     data/                        # WAL + checkpoint storage
   ctrl-2/
     conf/                        # receives config via OPCode_replConfigPush
@@ -135,7 +136,7 @@ Go modules are independent — `apiserver` and `xcecli` have separate `go.mod` f
 | Controller daemon | `nix build .#xcecore` | `xce_controller` binary |
 | Worker daemon | same | `xcecd` binary |
 | Scheduler daemon | same | `xce_scheduler` binary |
-| REST API server | same | `apiserver` binary |
+| REST API server | same | `xce_apiserver` binary |
 | CLI tool | `nix build .#xcecli` | `xcecli` binary |
-| AppImage | `nix build .#xcecore` | `xce-x86_64.AppImage` |
+| AppImage | `nix bundle --bundler github:ralismark/nix-appimage --option sandbox false .#xce` | `.AppImage` bundle (see README.md 3.5) |
 | Debug build | `nix build .#xcecore_debug` | full debug + ASAN binaries |