---
name: hd-dock
description: The Hydrogen Desktop dock (the app launcher rail on the right edge of the workspace) and how apps get into it. Covers the two-layer list (the adom-curated global manifest plus user-added wiki apps), the dock block an app declares in its wiki package.json so the dock knows how to launch it, the container_command step contract (--print-url, skip_if, await url, timeouts), the free orbital loading screen, and how a user or an AI adds any wiki app to the dock locally. Read this when a user says: add an app to the dock, add my app to the dock, put this wiki page in the dock, dock settings, make my app dock-ready, dock block, dock manifest, launch steps, how do dock apps launch, app launcher, featured apps, pin an app, hover zoom, alt-pin.
---

# hd-dock: the Hydrogen Desktop app launcher

The dock is the launcher rail on the right edge of the HD workspace. Every card
in it is a wiki app page. The dock resolves what to SHOW (name, brief, hero)
from the page itself and how to LAUNCH from a `dock` block the app declares.
Display is never duplicated into the dock; the page is the single source of truth.

## The list has two layers

1. **The global manifest (adom-curated).** HD fetches a public manifest and
   renders its apps. Only the adom team edits it; `featured` and `order` exist
   only here. It is world-readable at:

   `https://wiki.adom.inc/blob/bootstrap/hd-bootstrap/dock/apps.json`

   HD refreshes it on launch and then on the poll cadence the manifest itself
   declares (`poll_seconds`, currently 6 hours), so curation changes never wait
   for an HD release. Want your app on the global list? Make it dock-ready
   (below), then open an issue on the adom/hydrogen-desktop wiki page asking
   for listing; the adom team vets and merges.

2. **User-added apps (self-serve, local).** Any user adds any public wiki app
   from Dock settings (the gear at the top of the rail) with `owner/slug`, or
   by asking their AI ("add adom/orbital-lab to my dock"). These render in All
   apps, are pinnable, and persist locally. They never affect other users.

## The `dock` block (what an app declares)

In the app's wiki `package.json`:

```json
"dock": {
  "webview": { "title": "Adom TSCi", "favicon": "icons/tsci.svg" },
  "launch": {
    "mode": "container_command",
    "steps": [
      { "label": "Installing Adom TSCi",
        "run": "adom-wiki pkg install adom/adom-tsci",
        "skip_if": "command -v adom-tsci",
        "timeout_seconds": 180 },
      { "label": "Starting the board viewer",
        "run": "adom-tsci serve --print-url",
        "await": "url",
        "timeout_seconds": 60 }
    ],
    "on_ready": "navigate_placeholder"
  }
}
```

### webview

| Field | Required | Meaning |
|---|---|---|
| `title` | yes | Webview tab title while the app is loaded |
| `favicon` | no | Tab icon, a path in the app's page repo |
| `url` | for `mode: "webview"` | Page to load directly (hosted app, or the wiki page itself) |

### launch

- `mode: "webview"`: nothing to install; the dock loads `webview.url` directly.
- `mode: "container_command"`: run `steps` in order in the user's workspace
  container, then `on_ready: "navigate_placeholder"` navigates the pre-loaded
  webview to the URL a step produced.

| Step field | Required | Meaning |
|---|---|---|
| `label` | yes | Shown in the launch toast while the step runs |
| `run` | yes | The command |
| `skip_if` | no | Probe command; exit 0 skips the step (idempotent installs) |
| `await` | no | `url`: scrape the first URL the command prints, hold for on_ready |
| `url_pattern` | no | Scrape regex, default `https?://\S+` |
| `timeout_seconds` | no | Per-step budget; timing out fails the launch with this label |

**The `--print-url` convention** is the whole integration contract: a dock-ready
server verb prints its own reachable URL to stdout and keeps serving.

## The loading screen is free

The instant a launch involves a webview, HD paints the panel with the workspace
theme background token and runs the Adom orbital loading animation (transparent,
so it reflects any theme) until the app URL has truly loaded, then fades it out.
Install steps stay behind the mark with their labels ticking in the launch toast.
Apps bundle nothing and opt into nothing. Details and the embeddable single-file
animation: the adom/orbital-lab wiki page.

## Publisher checklist (make your app dock-ready)

1. Public wiki page with a hero and a billboard-quality one-line brief; the
   dock shows exactly these.
2. Install step is `adom-wiki pkg install <owner>/<slug>` with a `skip_if`
   probe so relaunches skip it.
3. Server verb takes `--print-url`; that step gets `await: "url"`.
4. Sane `timeout_seconds` (180 install / 60 serve are good defaults).
5. Add the `dock` block to package.json, publish the page.
6. Test from your own dock: Dock settings, Add app, `owner/slug`, click it,
   watch the steps run behind the loading mark.

## Adding an app for a user (AI recipe)

When the user asks you to add a wiki app to their dock:

1. Confirm the page exists and is public (`adom-wiki discover search`).
2. Open Dock settings (gear at the top of the rail), Add app, enter
   `owner/slug`; or drive the equivalent HD API if you are automating.
3. If the page has no `dock` block, it still loads as a plain webview of its
   wiki page; tell the user launch steps need the block and point the
   publisher at this skill.