tawasuyu/brahman

Para "ver" la administración del init desde el shell que arrancó dentro
del initramfs hacían falta clientes que hablen los 4 sockets Unix. Los
exists como examples de cada crate; los empaquetamos ahora.

build-arje-initrd.sh:
- cargo build --example brahman-status -p brahman-admin
- cargo build --example busctl         -p ente-bus
- cargo build --example brainctl       -p ente-brain
- Copia los 3 a /usr/bin/ del initrd.

docs/arje-boot.md §6b reescrita con:
- Tabla de sockets corregida (defaults a /tmp/ cuando no hay
  XDG_RUNTIME_DIR/TMPDIR, que es el caso en initrd).
- Cookbook de los 3 CLIs con ejemplos de sesión típica dentro de la VM.
- Nota para vendorear socat-static via EXTRA_BINS si querés conectar
  crudo a un socket.

§1 layout actualizado con /usr/bin/{brahman-status,busctl,brainctl}.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

diff --git a/docs/arje-boot.md b/docs/arje-boot.md
index 2d3f301..3a9edb8 100644
--- a/docs/arje-boot.md
+++ b/docs/arje-boot.md
@@ -26,6 +26,9 @@ El initrd es un **CPIO + gzip** (formato `newc`, estándar Linux). Su raíz:
 /usr/sbin/ente-echo
 /usr/sbin/ente-policy-provider
 /usr/sbin/ente-*-compat         13 shims D-Bus (logind, hostnamed, …)
+/usr/bin/brahman-status         CLI: snapshot del broker (sesiones + matches)
+/usr/bin/busctl                 CLI: bus interno (list-entes, announce, …)
+/usr/bin/brainctl               CLI: cerebro (rules, entropy, crystals)
 /ente/seed.card.json            Tarjeta Semilla canónica
 /bin/{sh,ls,mount,…}            busybox-static
 /etc, /dev, /proc, /sys, /run   mountpoints vacíos
@@ -301,15 +304,63 @@ echo 'export RUST_LOG="trace"' >> wrapper
 
 ### 6b. Sockets de introspección (Unix, dentro del initrd)
 
-| socket                       | servicio                                          |
-| ---------------------------- | ------------------------------------------------- |
-| `/run/ente-bus.sock`          | bus interno (postcard, `BusRequest::Invoke/...`) |
-| `/run/brahman-init.sock`      | handshake brahman                                 |
-| `/run/brahman-admin.sock`     | snapshots de sesiones + matches                   |
-| `/run/ente-brain.sock`        | introspección del cerebro                         |
+Sin `XDG_RUNTIME_DIR` ni `TMPDIR` en el env de PID 1 (caso del initrd),
+los sockets caen al fallback `/tmp/`:
+
+| socket                       | env override            | servicio                                  |
+| ---------------------------- | ----------------------- | ----------------------------------------- |
+| `/tmp/ente-bus-*.sock`        | `ENTE_BUS_SOCK`         | bus interno (Announce/Invoke/ListEntes)   |
+| `/tmp/brahman-init.sock`      | `BRAHMAN_INIT_SOCKET`   | handshake brahman                         |
+| `/tmp/brahman-admin.sock`     | `BRAHMAN_ADMIN_SOCKET`  | snapshots de sesiones + matches           |
+| `/tmp/ente-brain.sock`        | `ENTE_BRAIN_SOCK`       | introspección del cerebro (rules, observer) |
+
+El initrd trae 3 CLI clients precompilados en `/usr/bin/`:
+
+```sh
+brahman-status          # snapshot completo: sesiones + matches + WIT + flows
+busctl list-entes       # entes anunciados en el bus
+busctl announce         # smoke test: anuncia una Card desde el shell
+busctl power-off        # apaga el fractal
+brainctl list-rules     # reglas crystallizadas + manuales
+brainctl entropy        # entropía del observer estadístico
+brainctl top 10         # top-10 kinds por frecuencia
+brainctl crystals       # patrones detectados con auto-promote
+brainctl crystal-json 0 # exporta un crystal específico como Rule JSON
+```
+
+Ejemplo de sesión típica dentro de la VM:
+
+```sh
+arje# brahman-status
+Init: server=0.1.0 protocol=0.1.0 attached=true
+Context: (sin set)
+
+Sessions (3):
+  [ente]  01HQ5R2K…  compat-logind     lifecycle=Daemon  priority=High
+  [ente]  01HQ5R2K…  compat-hostnamed  lifecycle=Daemon  priority=Normal
+  [ente]  01HQ5R2K…  echo-smoke        lifecycle=Daemon  priority=Low
+
+Matches (0):
+  (ninguno)
 
-Conectar desde un Ente hijo: `socat - UNIX-CONNECT:/run/brahman-admin.sock`.
-(El initrd debe tener `socat` o equivalente; agregalo con `EXTRA_BINS`.)
+arje# busctl list-entes
+14 entes en el bus:
+  01HQ… compat-logind        provides=[LegacyLogind]
+  01HQ… compat-journald      provides=[Journal]
+  …
+
+arje# brainctl top 5
+spawn 14
+ente_died 0
+…
+```
+
+Si en cambio querés conectar crudo con `socat`/`nc`, agregalo con
+`EXTRA_BINS=/usr/bin/socat-static scripts/build-arje-initrd.sh` y luego:
+
+```sh
+arje# socat - UNIX-CONNECT:/tmp/brahman-admin.sock | jq .
+```
 
 ### 6c. Snapshot / restore
 
diff --git a/scripts/build-arje-initrd.sh b/scripts/build-arje-initrd.sh
index 350a7e7..e0cb350 100755
--- a/scripts/build-arje-initrd.sh
+++ b/scripts/build-arje-initrd.sh
@@ -110,7 +110,16 @@ cargo build --release --target "$TARGET" \
   -p ente-binfmt-compat \
   -p ente-policy-provider
 
+# 1b. Build de las CLI de administración. Son `[[example]]` de sus crates
+#     respectivos — un solo binario cada una, sin estado propio.
+echo "[build-initrd] cargo build --release --target $TARGET de CLIs admin"
+cargo build --release --target "$TARGET" \
+  --example brahman-status -p brahman-admin \
+  --example busctl         -p ente-bus \
+  --example brainctl       -p ente-brain
+
 BIN_DIR="target/$TARGET/release"
+EX_DIR="target/$TARGET/release/examples"
 
 # 2. Validar la seed. validate.sh corre el binario del host (release plain),
 #    sólo verifica el schema — independiente del target.
@@ -140,7 +149,7 @@ fi
 # 4. Stage root del initrd.
 STAGE="$(mktemp -d -t arje-initrd.XXXXXX)"
 trap 'rm -rf "$STAGE"' EXIT
-mkdir -p "$STAGE"/{bin,sbin,usr/sbin,etc,ente,proc,sys,dev,run,tmp,sys/fs/cgroup}
+mkdir -p "$STAGE"/{bin,sbin,usr/bin,usr/sbin,etc,ente,proc,sys,dev,run,tmp,sys/fs/cgroup}
 
 # 5. Copiar binarios arje.
 install -m 0755 "$BIN_DIR/ente-zero" "$STAGE/sbin/ente-zero"
@@ -153,6 +162,11 @@ for b in ente-echo ente-policy-provider \
   install -m 0755 "$BIN_DIR/$b" "$STAGE/usr/sbin/$b"
 done
 
+# 5b. CLIs de administración → /usr/bin (no /usr/sbin: no son services).
+for e in brahman-status busctl brainctl; do
+  install -m 0755 "$EX_DIR/$e" "$STAGE/usr/bin/$e"
+done
+
 # 6. Userspace mínimo. Con binarios musl-static no necesitamos vendorear
 #    libc/ld-linux. Las dos rutas:
 #    (a) busybox-static apuntado por $BUSYBOX_BIN → 1 binario, todo simlink.