Adom Hydrogen (platform base)

@@ -1,53 +0,0 @@-----name: hydrogen-project-workspaces-description: The Project workspaces menu in Hydrogen Desktop (the icon right of the Adom logo) and its control API, the desktop side of shared workspaces (hydrogen/workspace.json benches a project ships). Read this when a user says - project workspaces, shared workspace, apply a bench, unload a bench, workspace.json, hydrogen/workspace.json, save as project workspace, the layout a project ships, this project ships a workspace, apply / not now card, workspace offer, the icon next to the Adom logo, /workspaces/apply, /workspaces/benches, ztest-bench, bench placeholder, connect adom bridge for a bench, open the same layout as Colby. For the file format, the WORKSPACE_* hints and adom-cli export/apply use the wiki-workspaces skill; for the pane API (tabs, splits, moves) use adom-workspace-control; this skill covers only what Hydrogen Desktop adds.------# 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 Desktop (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".-- `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).