main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-dock description: >- The Hydrogen dock bar (the app launcher rail on the right edge), how any wiki app becomes a card in it through a dockbar.json manifest, and how to drive it from an AI thread (/dock/* API). Use when asked to add my app to the dock, why my dock card does not work, set launch steps or an AI thread on launch, launch or relaunch a dock app, reset or customize my dock.

hydrogen-dock: the Hydrogen app launcher

The dock is the launcher rail on the right edge of the Hydrogen workspace. Since 1.0.140 it is visible after startup by default (so new users meet it), then auto-collapses after an app launch; "Start with the dock collapsed" and the other visibility behaviors live in Dock settings (the gear at the top of the rail). Every card in it is a wiki app page. Any public wiki app can be a dock card, and users can add one themselves without anybody's permission.

The dock resolves what to SHOW (name, brief, hero) from the page itself, and how to LAUNCH from a dockbar.json manifest at the root of the app's wiki page repo. Display is never duplicated into the manifest; the page is the single source of truth.

THE FULL PUBLISHER CONTRACT IS THE DOCK BAR GUIDE: https://wiki.adom.inc/adom/hydrogen/files/docs/dockbar.md

This skill is the working summary plus the traps. Send anyone writing a manifest to the Dock Bar guide.

Adding an app to a user's dock (the common request)

  1. Confirm the page exists and is public (adom-wiki discover search -q <term>).
  2. Dock settings (the gear at the top of the rail) → Add app → owner/slug.
  3. If the page has no manifest, the card still works: it opens the wiki page. Tell the user that launch steps need a dockbar.json and point the publisher at the Dock Bar guide.

The manifest, in one screen

{
  "dock_manifest": "1.2.0",
  "webview": { "title": "My App", "favicon": "icons/app.svg" },
  "launch": {
    "mode": "container_command",
    "console": "show",
    "steps": [
      { "label": "Installing My App",
        "run": "sh -c 'PATH=\"$HOME/.local/bin:$PATH\"; adom-wiki pkg install me/my-app'",
        "skip_if": "sh -c 'PATH=\"$HOME/.local/bin:$PATH\"; command -v my-app'",
        "timeout_seconds": 180 },
      { "label": "Starting My App",
        "run": "sh -c 'PATH=\"$HOME/.local/bin:$PATH\"; exec my-app serve --print-url'",
        "await": "url",
        "timeout_seconds": 60 }
    ],
    "on_ready": "navigate_placeholder",
    "ai": {
      "prompt": "The user just opened My App from the dock.",
      "thread": "existing",
      "thread_fallback": "new",
      "submit": "staged"
    }
  }
}

Discovery order, first match wins: root dockbar.json only (dock.json support removed), then dockbar.json in a sub-folder (depth 2 max, never node_modules or dot-folders).

mode is container_command (run steps, then show a URL), webview (load webview.url directly, no steps), or ai_thread (no webview at all, the click opens a thread).

⛔ The two rules that break every first attempt

1. A serve verb MUST self-background. Hydrogen runs the step synchronously and waits for it to EXIT before reading stdout. A server that stays in the foreground blocks the exec for the whole timeout_seconds, then the exec times out and KILLS it, so the URL it printed is dead by the time Hydrogen polls it. The launch fails with "started, but never answered".

The tell: the server is healthy when run by hand and dead when the dock runs it.

2. Steps must set PATH. Wiki-installed CLIs land in ~/.local/bin, which is NOT on the PATH of the shell the workspace exec uses. A step calling the app's own CLI by bare name fails with command not found (exit 127) on every machine except the developer's, where it usually happens to be on PATH already. That also makes skip_if report "installed" for the author and "missing" for users.

Both bundled bridges shipped both bugs. Check these two first when a card fails.

Two contracts that ride with the rules (full detail in the Dock Bar guide):

  • Print the DIRECT URL http://127.0.0.1:<port>/. The workspace shares this computer's network, so a workspace port IS a host localhost port (see hydrogen-networking). Never the :7380/proxy/<port>/ form.
  • The webview belongs to your CLI. Every step runs with ADOM_DOCK_WEBVIEW (the tab the dock pre-opened) and ADOM_DOCK_APP in its environment; once serving, take the tab over with adom-cli hydrogen webview open-or-refresh --name "$ADOM_DOCK_WEBVIEW" --url ... and drive it yourself from then on. The printed URL is only the dock's readiness gate.

What a click does

click ─▶ already open? ─▶ YES: close that tab first (re-click = relaunch, below)
          │
          placeholder webview opens instantly (theme bg + orbital animation, free)
          ├─ steps run in order, transcript streaming into the placeholder console
          ├─ await:"url" scrapes the app URL from stdout
          ├─ Hydrogen polls it until it answers (budget = that step's timeout_seconds)
          │    never answers ─▶ the launch FAILS loudly; it does not navigate to a
          │                     dead URL and claim success
          ├─ on_ready: navigate_placeholder (show the URL) | hand_to_ai
          └─ ai block, if present: opens or reuses this app's own named thread

The ai block is its OWN branch, not an alternative to on_ready: an app can show its dashboard AND open a thread about it.

Re-click relaunches (since 1.0.211). A click on an app whose tab is open closes that webview, recreates it and runs the manifest steps again in the container, so what appears is always the current code. This is deliberate: an AI iterating on a dashboard could never tell whether a click showed its latest work or the tab from before its change. The dock finds the tab by webview.title against the live workspace layout, so it holds even after a Hydrogen reload; publishers must keep webview.title stable or the old tab survives next to the new one. A serve step is expected to be idempotent for this (the bridge's version-aware serve retires its old instance).

The ai block

Field Default Meaning
prompt app-naming default The pre-canned prompt
thread "new" "existing" reuses THIS app's own thread, found by the name the dock gave it
thread_fallback "new" When existing finds none: new, or current (whatever is open)
submit "staged" staged waits in the input for the user; auto sends immediately

Threads are opened, named and injected through the AI Threads API, so the thread is named after the app (visible in the AI Threads panel, durable across restarts), and injection is BACKGROUND: relaunching an app never steals focus from whatever the user is typing. ai.typed is accepted and ignored.

The loading screen is free

The instant a launch involves a webview, Hydrogen paints the panel with the theme background and runs the Adom orbital animation until the app URL truly loads. Apps bundle nothing and opt into nothing. launch.console: "hide" mutes the command transcript (never the failures) when the output would be noise.

Driving the dock from an AI thread

The control API presses the dock for you (BASE="$(cat ~/.adom/hydrogen-control-url)"):

call what it does
GET /dock/apps every app: id, wiki_repo, name, mode, running, launching, tab_open, url, health, last_launch
POST /dock/launch {id, relaunch?, timeoutSec?} presses the button (relaunch by default), waits (default 240 s) and returns ok, url, reason, console (the transcript, failing step verbatim)
POST /dock/close {id} removes the app's tab; does not stop its container process
POST /dock/refresh {full?} re-reads the curated apps.json now (full:true also every display, manifest and hero)
POST /dock/reset back to defaults: drops locally added apps, pins, draft manifest URL, rail width and caches; Settings > Dock Bar toggles stay

id is the dock id (kicad, nb, codex), the wiki repo or its slug. Look at the result with POST /screenshot {"target":"tab","title":"<name>","b64":true}: the PNG comes back inline as dataUrl (the whole Hydrogen window on Linux). Without "b64":true you only get a path on the host (~/.config/hydrogen-desktop/shots/), which the workspace cannot open. To keep the picture, decode it: curl -s -X POST "$BASE/screenshot" -d '{"b64":true}' | python3 -c 'import sys,json,base64; open("shot.png","wb").write(base64.b64decode(json.load(sys.stdin)["dataUrl"].split(",",1)[1]))'.

What ok:false means, by reason: a step returned non-zero (its stderr is in console, prefixed stderr:), the serve step printed no URL, the URL never answered within the step's budget, or no webview tab could be opened. A pending:true answer means the launch outran timeoutSec, not that it failed: GET /dock/apps shows it still launching, and a first install of a bridge legitimately takes minutes.

The launch runs the same code path as a click, in the same shell webview, so a launch that works through the API works for the user, and vice versa.

Testing a draft

  • Per-app, instant: Dock settings → Add app → owner/slug reads the live manifest immediately. Fastest loop.
  • Run the steps by hand in the container first, exactly as written, and check the serve step RETURNS instead of blocking.
  • Whole-list draft: Dock settings → Manifest URL (draft) points the dock at any apps.json. A DRAFT badge stays on the rail while active.

Troubleshooting by symptom

Symptom Cause
command not found, exit 127 PATH: ~/.local/bin is not on the exec shell's PATH
"started, but never answered" The serve command did not self-background
"no URL within Ns" Nothing matching https?://\S+ on stdout (printed to stderr?)
Install step runs every launch skip_if missing or probing the wrong name
LED red "not answering" while the server answers curl Health endpoint lacks Access-Control-Allow-Origin: * (the dock probes cross-origin from the shell)
A duplicate tab appears webview.title changed between versions
The ai prompt never fires mode: "webview" has no steps and no ai branch
Works for the author, fails for users Tested where the CLI was already installed

The right-click menu (and Hard Refresh Open)

Right-clicking a dock card opens a per-app menu; right-clicking empty rail space opens the dock-wide one.

Item What it does
Open Same as a left click: relaunch it (close the tab, run the steps again), or launch it.
Hard Refresh Open The from-scratch relaunch for ONE app. Closes that app's webview if open, forgets its running state and health reading, drops its cached manifest AND display entry (name, brief, hero), re-resolves both from the wiki, then launches with a forced adom-wiki pkg update <owner/slug> || pkg install <owner/slug> step ahead of the manifest's own steps, streaming into the launch console like any other step. The app's version-aware serve retires the old instance. Use it when an app just published a fix, when a card shows a stale hero, or when an install looks wedged.
Pin to Dock / Unpin Pin the card to the top of the rail.
(empty rail) Refresh list from wiki Dock-wide: blanks every card, wipes the display and manifest caches, and reloads the curated list, all manifests and all heroes from scratch.
(empty rail) Reset to defaults Dock-wide: drops locally added apps, pins, the draft manifest URL, rail width and caches (POST /dock/reset); Settings > Dock Bar toggles stay.

Hard Refresh Open is deliberately update-then-relaunch rather than uninstall-then-reinstall: it gets the same freshness without discarding the app's installed skills and settings. A genuinely corrupt install is a manual pkg uninstall followed by a normal click.

Publishers: this is how a user picks up your newest release without waiting for a cache to expire, so the install-or-update step pattern matters (never pin a version with skip_if, or the update step no-ops and your fix never lands).

What you can change WITHOUT a new ah build

The dock is three layers and only one of them is compiled into the app. Knowing which is which decides whether a change ships in minutes or waits for a release.

Layer Where it lives To change it
Which apps appear, order, featured apps.json in the hydrogen-bootstrap page repo push to the wiki. Every dock re-polls on poll_seconds (default 6h)
How YOUR app launches, its phrases, hero your app's own dockbar.json push to your page repo. Picked up on the next resolve, or instantly via Hard Refresh Open
The rail itself, the launch screen, the orbital compiled into ah needs an ah build and release

So an app can change everything about its own card, and adom can change the whole list, with no release. Only the dock's own chrome needs a build.

To make a change land NOW rather than on the next poll: right-click the card and use Hard Refresh Open, which drops the cached manifest and display entry and re-resolves from the wiki, or use the dock-wide Refresh list from wiki on empty rail space.

A dock only YOU see

Dock settings > Manifest URL points your dock at any apps.json you like, instead of the adom-curated one. It is per-install and nobody else is affected. A DRAFT badge stays on the rail while it is active, so a personal list is never mistaken for the fleet list.

It was built for testing curation changes before they reach everyone, and a personal dock is the same mechanism: publish your own apps.json anywhere the workspace can fetch it, paste the URL once, and your rail is yours. The AI can then edit that file for you freely without you touching settings again.

⛔ What these things are CALLED, and why you should say the name

A user who does not know a part's name cannot ask for it in a chat window. So use the canonical name in conversation, every time, even when the user used a different word. Say "the dock bar" while doing what they asked, and they learn the term without being corrected.

Say this For Users also say
the dock bar (or the dock) the launcher rail on the right edge app bar, launcher, sidebar, the icons
a card one app's icon in the rail tile, icon, button, app
the launch screen the interstitial with the orbital loading screen, splash, the spinner
the orbital the animation on the launch screen the ball, the sphere, the loader
the launch console the command transcript under it the log, the terminal, the output
Dock settings the gear at the top of the rail preferences, options, config
Hard Refresh Open the right-click from-scratch relaunch force refresh, reinstall, hard reload
a webview tab the workspace tab an app opens into window, panel, the app

Accept every synonym silently and answer in the canonical term. Correcting someone's vocabulary is worse than modelling it: they will pick the name up from your reply, and the next time they will ask for it precisely.

The curated list vs user-added

The global list (https://wiki.adom.inc/blob/bootstrap/hydrogen-bootstrap/dock/apps.json) is adom-curated and is ONLY a list: which apps appear and in what order, plus featured and order. It deliberately carries no launch blocks, because an inline launch there overrides and freezes the manifest the app maintains. Being on it is not required to be dock-ready. To request listing, open an issue on the adom/hydrogen-desktop wiki page.