docs: capability-map row + ROADMAP R-23/R-13 + PROMPT-TEMPLATE N.5 for Direction-2 immediate-sync

documentation/PROMPT-TEMPLATE.md

@@ -284,7 +284,19 @@ Decisions made, architectural state, what's next.
 `<repo>/README.md` if architecture/features changed; authoritative architecture/feature docs in
 `felhom.eu/documentation/{architecture,controller}/`. Spikes/audits → `felhom.eu/documentation/audits/`.
 
-### N.5 Website version bump (if controller/hub version is shown on the site).
+### N.5 Capability map + backlog (end-of-session checklist — easy to forget)
+If the task **changed what the platform can do** (new/removed capability, or a capability moved
+status), update in the SAME session:
+- **`architecture/00-capability-map.md`** — add/adjust the affected *scenario* row with the correct
+  **status** (PROVEN-LIVE requires an `audits/`|`tests/` citation; else IMPLEMENTED/PARTIAL) and an
+  evidence citation. A leg not exercised live → PARTIAL/IMPLEMENTED with a note saying which leg and
+  a `→ R-n` pointer, never PROVEN-LIVE.
+- **`backlog/ROADMAP.md`** — add any new open work / deferred legs as an item (next free `R-n`),
+  collapse a now-shipped item to its one-liner + version, and honor the **coupling rule** (every
+  roadmap item names the map row it flips; every map gap row points back by ID). Parked sub-features
+  (e.g. an alternative transport, an agent-plane leg) go as a note under the owning arc's item.
+
+### N.6 Website version bump (if controller/hub version is shown on the site).
 
 ---
 
@@ -403,6 +415,7 @@ AUTHOR CHECKLIST (for Claude.ai — verify before handing to CC)
 | 13| Build/deploy commands correct for each repo (controller golden / agent / hub)?| Failed or wrong deploy |
 | 14| STOP point explicit for risky/supervised; live-validation hits real pipeline?| Destructive op run unsupervised; F9 bypass |
 | 15| Doc routing correct (CHANGELOG cumulative, REPORT overwrite, CONTEXT, README, documentation/)? | Doc drift / cumulative REPORT |
+| 15b| Capability changed → `00-capability-map.md` row + status/evidence updated AND `backlog/ROADMAP.md` item added/collapsed (coupling rule)? | Capability map goes stale; deferred legs lost |
 | 16| UI strings Hungarian + adult tone + minimal emoji specified?                  | English/placeholder UI leaking to customers |
 | 17| §15 report format demanded so the result is validatable against Gitea?       | Unverifiable "done" claims (cardinal rule) |
 

documentation/architecture/00-capability-map.md

@@ -106,6 +106,7 @@
 | Scenario | Components | Status | Evidence | Gap / roadmap |
 |---|---|---|---|---|
 | Customer/host management: 8-tab detail, scoped auto-refresh, safe stale-host deletion, capability chips | hub v0.47–0.53 | **PROVEN-LIVE** | hub v0.53.0 dead-host roll-up live on the Peti cluster (proxmox1 down 23h); `CAMPAIGN-4-2026-07-13` (operator UI driven live); `DRILL-day0-take2` F-16 (offsite/freeze buttons live) | 8-tab render + capability chips are **render-test-validated** (hub UI is password-gated; CC cannot log in). (Cited "daily operator use" was a no-doc citation; `AUDIT-hub-gui-2026-06-30` predates these features at hub v0.25) |
+| Config/state change round-trips in **seconds** (hub↔box immediacy; 15-min cycle stays the backbone): box→hub out-of-cycle report (Dir 1) + hub→box `GET /api/v1/wait` long-poll wake (Dir 2) | controller v0.139/140, hub v0.58 | **PARTIAL** | Transport proven live through the real DNS-only ingress: `SPIKE-immediate-sync-transport-2026-07-16` + hub v0.58.0 / controller v0.140.0 REPORTs — 240 s no-annotation hold (25 s heartbeat defeats nginx's 60 s `proxy_read_timeout`, no ingress change), 0.047 s wake-on-change, hub `rollout restart` = 1 WARN + 0-storm reconnect; Dir-1 2 s box→hub round-trip live in controller v0.139.0 | The operator-UI **save→apply** round-trip is not fired end-to-end live (hub UI password-gated; CC can't log in) → R-23; the wake transport and the ACK→config_version→`ConfigRefresher` delivery chain are each proven, only the UI-triggered bump leg is unexercised. Agent-plane (host-domain desired-state) poke is spiked-not-built → R-13 |
 | Publish train: MinAgent floors, gated auto-Reissue, version channels, floor-field-LAST rules | hub v0.45/0.53, agent | **PARTIAL** | `runbooks/publish-train-rules.md`; demo-fleet updates proven | **Never proven on a real remote customer** — parked trains `RUNBOOK-publish-0.79/0.81/0.85-*` await Peti → R-1 |
 | Agent self-update: A/B slots, crash-loop auto-rollback, operator-signed | agent v0.70+ | **PROVEN-LIVE** (demo) | `SPIKE-agent-selfupdate-2026-07-05` | Remote-customer proof pending → R-1 |
 | Controller self-update: anonymous registry, no credentials in guest | controller v0.112 | **PROVEN-LIVE** (demo) | 07-10 arc | |

documentation/backlog/ROADMAP.md

@@ -41,13 +41,14 @@
 | R-17 | Old-box archive (u629193-sub1) retirement decision — 9/9 byte-identical restores verified | XS | awaiting-decision | Viktor ruling |
 | R-19 | Internet-outage customer-experience drill: pull WAN on demo, verify lan_resolver path, document what the customer actually sees/does | S | idea | Flips map row E "LAN access" IMPLEMENTED→PROVEN-LIVE |
 | R-20 | ~~Verify operator-key pinning is fully in the day-0 install flow~~ | XS | **closed** (2026-07-16) | Confirmed against `scripts/felhom-host-install.sh` source (not changelog): keys resolve at L1181–1219 (script constants `OPERATOR_KEY_*`, populated, `--operator-pubkey-file` override), pinned automatically by `step_agent_config()` "STEP 6/8" (L2044; python builds `authz.signers` L2146–2156, reinstall preserves existing), verified at L2332–2337 ("authz signers: N … operator-signed self-update armed"). No interactive prompt or post-install hand-edit — fully automatic. Doc-drift note: the L193–197 "EMPTY by default" comment is stale vs the now-populated constants (→ R-16 hygiene) |
+| R-23 | **Immediate-sync Direction-2 follow-ups** (hub v0.58 / controller v0.140, shipped 2026-07-16): (a) live-validate the operator-UI **save→apply** round-trip end-to-end — needs an operator login, so fold into a Peti/alpha supervised session (one config save → box wakes in seconds → self-restart → startup report; also demonstrates the restart *single-fire* once a bump has advanced the generation past 0); (b) cosmetic: the controller Waiter's "recovered" INFO logs on the next hold completion (`pollOnce` blocks ~240 s), not at reconnect — surface recovery at connect time | S | idea | Flips the new map row "config/state change round-trips in seconds" PARTIAL→PROVEN-LIVE. Transport + mechanism already proven live (`SPIKE-immediate-sync-transport-2026-07-16`, v0.58/v0.140 REPORTs: 240 s no-annotation hold, 0.047 s wake, restart 1-WARN/0-storm); only the login-gated UI-triggered bump leg is unexercised |
 
 ## P3 — post-alpha
 
 | ID | Item | Size | Status | Notes |
 |----|------|------|--------|-------|
 | R-12 | Cluster mode: agent-follows-guest, bind-mount reconciliation on HA migration | XL | idea | Scoped 07-15; interim = HA-group pin to one node. Driven by Peti's two-node cluster |
-| R-13 | OOB management arc: dual-use existing WireGuard + hub desired-state channel as mutual-repair | L | idea | |
+| R-13 | OOB management arc: dual-use existing WireGuard + hub desired-state channel as mutual-repair | L | idea | **Agent-plane immediate-sync nudge belongs here:** `SPIKE-immediate-sync-transport-2026-07-16` P4 measured the ep0-relayed poke (hub→ep0 forced-cmd→UDP→box, ~0.42 s, **zero** ep0/box infra change, cryptographically peer-confined) — the concrete "sync now" signal that reaches the **agent** (WG terminates host-side) for host-domain desired-state, reserved for this arc. Needs an agent train (UDP listener → immediate heartbeat). The controller-plane Direction-2 wait channel (hub v0.58 / controller v0.140) shipped this leg separately for the config puller |
 | R-14 | Headscale/WireGuard spike: Minecraft/gaming port connectivity (CGNAT-proof, sovereign DERP fallback) | M | idea | |
 | R-15 | Multi-user dashboard accounts (household members, roles) | L | idea | Single password is a stated alpha limitation (R-11) |
 | R-21 | **Bare-metal Felhom ISO** — per-PVE-release auto-install ISO for blank customer hardware → first-boot wrapper (invokes `felhom-host-install.sh`) → claim-code pairing (option C) | XL | **in-progress** (slice A shipped 2026-07-16; physical run 2026-07-16) | **PHYSICAL RUN 2026-07-16 (`tests/VALIDATION-n100-baremetal-2026-07-16.md`):** demo N100 reinstalled clean-slate from a pipeline ISO → chain reached **rc-0 first try on real hardware** (closes slice A's operator-gated boundary), serial-filter safety proven on metal, PBS-DR reconciler self-healed on the reused peer, DMI verdict = key on MAC+UUID. **F1 (HIGH, slice-B input):** this cheap AMI `AN3PLUS 0.01` firmware won't UEFI-boot the ISO's GRUB from USB (`relocation 0x0`) — SB-off/shim-bypass don't help; worked around live with a `grub-mkimage` loader built from the box's own GRUB. Pipeline must ship a firmware-compatible loader / PXE path. Reused-customer edges (F2 claim re-issue, F3 offsite re-issue, F4 non-default-storage-id ACL 403) feed R-1/Peti. UX: F6 drive-init doesn't mount+attach, F5 guest-RAM not configurable, F7 back-route. — **Slice A (build pipeline + first-boot bootstrap) DONE + validated on VM 310:** build gate/red-proof, disk-filter fail-safe, stub→retry-unit→real public-channel host-install fetch+invoke→retry, resume-decision, exactly-once, no-net retry+recovery all GREEN. Operator-gated remainder: host-install rc-0 terminal success (drill customer needs the password-gated create-UI). **Slice B** = physical N100 RUNBOOK (real DMI/firmware/USB/prior-LVM). **Slice C** = claim-pairing so the *distributed* ISO carries no retrieval passphrase (slice-A ISO is secret-bearing, supervised/single-use). Origin spike `audits/SPIKE-baremetal-iso-2026-07-16.md`: every mechanism GREEN on nested virt (VM 310 on felhom-pve). Zero-touch install BIOS **and** UEFI incl. **Secure Boot enforcing** (no MOK/keypress); first-boot hook `fully-up` = root + working pvesh/pct, exactly-once via `pending-first-boot-setup` flag; post-install **webhook** carries SMBIOS-UUID + management-MAC + host SSH keys → the unclaimed-appliance record; disk-filter installs only the target (canary byte-identical) and **fails-safe** on match-nothing / bad disk; `from-url` + `cert-fingerprint` **fails CLOSED**. OPEN (needs ONE real bare-metal run): vendor DMI serials (empty on virt), real firmware/NIC quirks, a pre-existing-LVM wipe step. Pipeline notes: assistant pairs to the ISO by Debian codename, ~11.5 s/ISO on DooPlex, **gate on `validate-answer` output not `$?`** (exit 0 on failure). Would flip a new capability-map MISSING row "customer self-installs on bare hardware" once spec'd. *(brief called this R-22)* |