cd ~/project && adom-wiki repo clone kcknox/ztest-bench-lite      # 3 tabs; -kicad has 6 with app launches; ztest-bench has 7
curl -s -X POST :47084/workspaces/refresh | jq '.benches[].identity'
curl -s -X POST :47084/workspaces/apply -H 'content-type: application/json' -d '{"identity":"kcknox/ztest-bench-lite#hydrogen/workspace.json"}' | jq '{ok,summary}'
curl -s :47084/workspace/tabs | jq '[.tabs[].name]'                # 3D and Hydrogen present, VS Code untouched
curl -s -X POST :47084/workspaces/unload -H 'content-type: application/json' -d '{"identity":"kcknox/ztest-bench-lite#hydrogen/workspace.json"}' | jq '{ok,summary}'

---
name: hydrogen-project-workspaces
description: >-
  Hydrogen's Project workspaces menu (icon right of the Adom logo) and its API:
  apply or unload the bench layout a project ships in hydrogen/workspace.json.
  Use when asked about project workspaces, apply a bench, workspace.json, or the
  workspace offer card.
---

# hydrogen-project-workspaces: the desktop side of shared workspaces

A project can ship its Hydrogen layout as `hydrogen/workspace.json` (or `hydrogen/workspaces/<name>.json`) in its page repo. The platform pieces are shared with Hydrogen Cloud and documented in the **wiki-workspaces** skill (file, hints, `adom-cli hydrogen workspace export|apply|teardown`) and **adom-workspace-control** (the pane routes). Hydrogen (ah) adds a menu, a one-time offer, placeholder tabs that know the bridge state, and a control API for all of it. Use the API; never click for the user.

## The menu

Right of the Adom logo. Benches grouped by project, labelled "project / name", from the checkout (`~/project` root and one clone folder down) plus the cloud mirror (`mirror`, and `legacy` when keyed by repo instead of project). Rows have Apply, Unload and a copy-the-command button; below: "Replace existing tabs on Apply" and "Save as project workspace". Apply/Unload/Save run adom-cli in the WSL2 workspace with the output in a launch console tab (closes itself on success, stays with the reason on failure).

## Control API (ah, port 47084 by default; GET /ports for the real one)

| Route | Body | Notes |
|---|---|---|
| `GET /workspaces/benches` | | `benches[]` with identity, project, name, path, dir, source, legacy, tabs, panels, requires, applied, apply_command, unload_sources. |
| `POST /workspaces/refresh` | | rescan checkout + mirror |
| `POST /workspaces/apply` | `{identity|project|path|name, merge?, dryRun?, timeoutSec?}` | replace by default (the bench is built from scratch, the VS Code pane kept, displaced tabs restored by unload; `merge: true` adds the bench next to what is open); returns `ok`, `summary`, `envelope` (the CLI JSON), `console` |
| `POST /workspaces/unload` | same selectors | tries identity, then the relative and absolute path adom-cli may have recorded |
| `POST /workspaces/save` | `{dir, out?, project?}` | `adom-cli hydrogen workspace export --out <out>` in `dir`; `project` when the folder has no page.json |
| `POST /workspaces/offer` | `{action: "apply"|"dismiss"}` | answers the one-time card |
| `POST /workspaces/menu` | `{open: bool}` | UI-bus: `project-workspaces.open` / `.close` |
| `POST /workspaces/demo` | | the "Show me how it works" walkthrough (ab demo panel `pw-tour`, captions, narration); returns at once |
| `GET /workspaces/status` | | running, walkthrough, last (with transcript), offer, applied this session |
| `POST /ab/verb` | `{command, args?, timeoutMs?}` | any Adom Bridge verb on this machine (ab's own gates still apply) |

A name given to apply/unload resolves to the applied bench first, then a checkout bench, then a mirror copy (a legacy mirror entry can share a name with a checkout bench).

## Rules the desktop follows

- A checkout bench is applied as the local file from its project folder (what the user is editing); a mirror-only entry with a project uses the wiki ref. Identity is `project#hydrogen/...` (path inside the project), the key adom-cli and the cloud use.
- The project for a files-only wiki clone comes from the wiki (page.json has the slug, not the owner).
- The offer card shows once per bench per machine (preference key `workspace.offered.<owner>.<repo>`, the cloud's key), one per app start, and self-dismisses after a minute as Not now. Never auto-apply.
- Placeholder tabs ("X (not available)" / "(not started)", or `panelState.placeholder`) show the Adom Bridge state (GET /ab/health) with Connect and Re-apply; re-apply is idempotent in merge mode.
- The workspace API on the proxy (47083) serves the cloud's granular routes plus `GET /api/panels/catalog`, `POST .../current/apply` (replace mode, keeps the VS Code leaf), and forwards `.../shared[/...]` to Hydrogen Cloud with the desktop session. Every tree mutation bumps a revision; a `PUT /current` whose `_rev` is behind gets 409, so an external apply cannot be erased by the browser's echo.
- `POST /splits` seeds the new pane with the placeholder tab adom-cli sends (`panelType`, `displayName`, `position`, `ratio`); adom-cli deletes it as tabIndex 0 after adding the bench's tabs.
- No 3D panel on the desktop: a `3d-viewer` tab renders as "not available on Hydrogen Desktop" (the UI's own wording).
- `hydrogen://edit?workspace=<ref|identity|path>` is a registered scheme (installer + every start): a second launch forwards the link to the running ah, which applies the bench once the list loads. Test it with `Start-Process "hydrogen://edit?workspace=kcknox/ztest-bench-lite"` on the box.
- The VS Code pane is never created, removed or replaced by any of this.

## Testing a change (the ralph loop)

```bash
cd ~/project && adom-wiki repo clone kcknox/ztest-bench-lite      # 3 tabs; -kicad has 6 with app launches; ztest-bench has 7
curl -s -X POST :47084/workspaces/refresh | jq '.benches[].identity'
curl -s -X POST :47084/workspaces/apply -H 'content-type: application/json' -d '{"identity":"kcknox/ztest-bench-lite#hydrogen/workspace.json"}' | jq '{ok,summary}'
curl -s :47084/workspace/tabs | jq '[.tabs[].name]'                # 3D and Hydrogen present, VS Code untouched
curl -s -X POST :47084/workspaces/unload -H 'content-type: application/json' -d '{"identity":"kcknox/ztest-bench-lite#hydrogen/workspace.json"}' | jq '{ok,summary}'
```

Symptoms: "no recorded apply" from the CLI means the source spelling differs from what apply recorded (the unload route already tries identity, relative and absolute path); an empty mirror in the menu with entries visible to curl means the forward stripped gzip (fixed 1.0.371, the proxy asks for identity encoding); a tab created by apply vanishing within a second means a stale browser write got through (the revision check refuses it since 1.0.364).