Adom Hydrogen

@@ -36,7 +36,15 @@ A `container_command` launch runs the manifest's steps in order inside the user'  ![The app has taken over the webview](docs/img/dockbar/takeover.png) -When the served URL answers, the dock navigates the same webview from the interstitial to the app: this is `on_ready: "navigate_placeholder"`. The KiCad Dashboard shown here fully replaced its interstitial, and the card LED went green because the dock is now reading the app's own `/api/status`, which reports per-facet LEDs plus a top-level rollup the app controls. How the dock helps the CLI take over: the app does not need to know anything about webviews. It prints one reachable URL (the code-server proxy form, `http://localhost:7380/proxy/<port>/`, is the safe choice) and exits; the dock owns the navigation, the readiness gate, and the failure reporting.+The webview belongs to your CLI. The dock opens the interstitial as a named tab (`webview.title`) and tells every launch step which tab that is: `ADOM_DOCK_WEBVIEW` (the exact tab name) and `ADOM_DOCK_APP` (owner/slug) are set in each step's environment. Once your server is up, take the tab over yourself:++```sh+adom-cli hydrogen webview open-or-refresh --name "$ADOM_DOCK_WEBVIEW" --url "http://127.0.0.1:8931/"+```++From then on the tab is yours: renavigate it after a restart, repaint it on state changes, drive a tour in it. Re-running `open-or-refresh` with the same `--name` just navigates the existing tab, and that idempotence is your ownership handle. Skip the call when `ADOM_DOCK_WEBVIEW` is unset (someone ran your serve by hand). The KiCad Dashboard shown here has replaced its interstitial, and the card LED is green because the dock reads the app's own status endpoint, which reports per-facet LEDs plus a top-level rollup the app controls.++The URL your serve step prints serves a different purpose: it is the dock's readiness gate. The dock polls it (budgeted by that step's `timeout_seconds`) so a dead launch fails loudly instead of showing a dead page, and it navigates the interstitial itself as a fallback for CLIs that have not adopted ownership. Print the DIRECT URL, `http://127.0.0.1:<port>/`: the workspace is local WSL2 with mirrored networking, so a port bound in the distro is a Windows localhost port. Never print the `:7380/proxy/<port>/` form (pure indirection whose path prefix breaks health-URL resolution), and prefer `127.0.0.1` over the name `localhost` (Windows resolves the name IPv6-first while WSL binds IPv4, measured at ~820ms vs 13ms per request).  ## Opening an AI thread @@ -137,7 +145,12 @@ Each of these was learned from a bundled bridge shipping it wrong:  1. **Serve must self-background.** The dock runs steps synchronously and waits for exit; a foreground server is killed at the timeout and its URL is dead before the readiness probe runs. Print the URL, fork, exit 0. 2. **Steps must set PATH.** Wiki CLIs land in `~/.local/bin`, which is not on the exec shell's PATH. This bug's signature is works-for-the-author, fails-for-every-user, because on the dev box the command is already on PATH and `skip_if` lies in your favor.-3. **Serve must be idempotent.** The serve step runs on *every* launch; with an instance already up, detect it, print its URL, exit 0.+3. **Serve must be idempotent.** The serve step runs on *every* launch; with an instance already up, detect it, print its URL, exit 0. Ignore a running instance whose version does not match your own binary (restart it instead): version-blind reuse pinned one bridge's users to a stale server no reinstall could fix.++And the two contracts that ride with the rules:++- **Print the direct URL** (`http://127.0.0.1:<port>/`), never the proxy form, per the takeover section above.+- **Take ownership of your webview** via `ADOM_DOCK_WEBVIEW`, per the takeover section above.  ## The two-layer list