Adom Hydrogen

@@ -0,0 +1,80 @@+# Project workspaces++A project can ship its Hydrogen layout. The file is `hydrogen/workspace.json` in the project's page repo: which panes, which tabs, which apps, arranged how. Colby built the platform side (the wiki validates the file, adom-cli applies and exports it, Hydrogen Cloud lists it). This page is about the Hydrogen Desktop side: the **Project workspaces** menu next to the Adom logo, what Apply, Unload and Save do on your machine, and how an AI drives all of it without a mouse.++<video controls preload="metadata" poster="project-workspaces-poster.png" src="project-workspaces.mp4" style="max-width:100%"></video>++*70 seconds, recorded on a laptop: the menu, then three of Colby's example benches applied and unloaded in turn (Lite, KiCad, and the full seven-tab bench), every step sent through ah's control API. [Download the video](project-workspaces.mp4).*++## What you see in ah++The icon right of the Adom logo opens the pulldown.++![The Project workspaces menu with three benches grouped by project](menu.png)++- Benches come from two places and are grouped by project, labelled "project / name": the files in your workspace checkout (`hydrogen/workspace.json` and `hydrogen/workspaces/*.json`, at `~/project` and one clone folder down) and the cloud mirror, for benches the checkout does not have (tagged `mirror`, and `legacy` when they carry no project).+- **Apply** adds the bench's panes and tabs next to what you already have. Merge mode: nothing you had is closed, a tab with the same name is reused, and the VS Code pane is never moved, removed or replaced. Tick **Replace existing tabs on Apply** to close the tabs the bench does not name (VS Code still stays).+- **Unload** removes only what Apply created and stops the apps the bench started. Tabs you opened yourself, and apps the dock or another bench started, stay.+- The copy button puts the exact `adom-cli hydrogen workspace apply ...` command on the clipboard.+- **Save as project workspace** exports your live layout into a project folder as `hydrogen/workspace.json` (or `hydrogen/workspaces/<name>.json`). It asks for the project reference only when the folder has no `page.json`. The file is written and mirrored to the cloud, not committed: commit and push it with the project as usual (`adom-wiki repo push` validates it).++Apply, Unload and Save run `adom-cli` inside your WSL2 workspace, the same binary and the same commands Hydrogen Cloud runs in a container. The command and its output stream into a launch console tab (the one the Dock Bar uses), which closes itself when the command succeeds and stays open with the reason when it fails.++![The KiCad bench applied: five app tabs across two new panes](kicad-bench-applied.png)++## The one-time offer++When a project in your checkout ships a workspace and you have not been asked about it before, ah shows one card at the top: "this project ships a workspace. Apply / Not now". It is keyed on the same preference the cloud uses (`workspace.offered.<owner>.<repo>`), so you are asked once across both. An unanswered card dismisses itself after a minute and counts as Not now on that machine. Nothing is ever applied on its own.++![The offer card](offer-card.png)++## Placeholder tabs and bridges++When adom-cli cannot resolve an app (page missing, install failed, or the app needs a desktop bridge that is not connected), Apply still succeeds and the tab becomes a placeholder named "X (not available)" pointing at the app's wiki page. On the desktop that placeholder shows the Adom Bridge state with a **Connect Adom Bridge** button and a **Re-apply workspace** button; re-applying is idempotent in merge mode, so only the placeholder changes.++## Driving it from an AI (no mouse)++Everything in the menu is reachable on ah's control API (port 47084 by default, the `hydrogen-api` skill lists every route):++| Route | What it does |+|---|---|+| `GET /workspaces/benches` | The list the menu shows, with `identity`, `project`, `path`, `source`, and whether each is applied. |+| `POST /workspaces/refresh` | Rescan the checkout and the mirror. |+| `POST /workspaces/apply` | `{ "identity": "owner/slug#hydrogen/workspace.json", "replace": false }`, or `project`, `path` or `name`. Returns the CLI envelope and the console transcript. |+| `POST /workspaces/unload` | Same selectors. Tries the bench identity, then the path adom-cli recorded. |+| `POST /workspaces/save` | `{ "dir": "/home/adom/project/my-board", "out": "hydrogen/workspace.json", "project": "owner/slug" }` |+| `POST /workspaces/offer` | `{ "action": "apply" }` or `{ "action": "dismiss" }` for the card. |+| `POST /workspaces/menu` | `{ "open": true }` to show the pulldown (also UI-bus `project-workspaces.open` / `.close`). |+| `GET /workspaces/status` | The command in flight, the last outcome with its transcript, the card showing, benches applied this session. |++```bash+curl -s http://127.0.0.1:47084/workspaces/benches | jq '.benches[].identity'+curl -s -X POST http://127.0.0.1:47084/workspaces/apply -H 'content-type: application/json' \+  -d '{"identity":"kcknox/ztest-bench-lite#hydrogen/workspace.json"}' | jq '.summary'+curl -s -X POST http://127.0.0.1:47084/workspaces/unload -H 'content-type: application/json' \+  -d '{"name":"Lite bench (example)"}' | jq '.summary'+```++The workspace API itself is on the local proxy (port 47083, `ADOM_HYDROGEN_URL` inside the workspace), and it is what adom-cli talks to: the granular routes (`/current`, `/tabs`, `/splits`, `/moves`, `/swaps`, `/panels/{id}`), `GET /api/panels/catalog`, the one-transaction `POST .../current/apply`, and `.../shared` forwarded to the cloud mirror. Every change to the tree carries a revision; a write based on an older revision is refused instead of overwriting someone else's change.++## Skills your AI already has++- **wiki-workspaces** and **adom-workspace-control** (adom/core, shipped to every Adom user): the file format, the `WORKSPACE_*` hints, export and apply with adom-cli, and the pane API. These are the same on Hydrogen Cloud and Hydrogen Desktop.+- **hydrogen-api** and **hydrogen-project-workspaces** (ship with Hydrogen Desktop, installed into your workspace at setup): the `/workspaces/*` routes above, the menu, the offer card, and the desktop rules. These exist because the desktop exposes controls the cloud does not.++## Differences from Hydrogen Cloud, on purpose++- A bench the checkout carries is applied as the local file (the copy you are editing); the wiki reference is used only for mirror-only entries.+- The desktop resolves a files-only wiki clone's project from its page slug, since `page.json` names the slug but not the owner.+- The desktop has no 3D editor panel: a `3d-viewer` tab opens as a "not available on Hydrogen Desktop" tab. Open the same bench in Hydrogen Cloud to use it.+- The `hydrogen://...?workspace=` deep link is honoured as a query on the editor page, but ah registers no URL scheme yet, so a link from the wiki cannot open ah on its own.++## Example benches++Colby's throwaway examples, safe to clone and try: `kcknox/ztest-bench-lite` (3 tabs), `kcknox/ztest-bench-kicad` (6 tabs, declares the KiCad bridge), `kcknox/ztest-bench` (7 tabs, three dashboards).++```bash+cd ~/project && adom-wiki repo clone kcknox/ztest-bench-lite+```++Then open the menu (or `POST /workspaces/refresh`) and Apply.