Adom Hydrogen (Linux)
Public Made by Adomby adom
The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.
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)
- Confirm the page exists and is public (
adom-wiki discover search -q <term>). - Dock settings (the gear at the top of the rail) → Add app →
owner/slug. - If the page has no manifest, the card still works: it opens the wiki page.
Tell the user that launch steps need a
dockbar.jsonand 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 (seehydrogen-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) andADOM_DOCK_APPin its environment; once serving, take the tab over withadom-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/slugreads 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.
---
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
```json
{
"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 <url> 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 <url> 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.