Adom Wiki Skill Pack

--- a/skills/wiki-workspaces/SKILL.md+++ b/skills/wiki-workspaces/SKILL.md@@ -0,0 +1,67 @@+---+name: wiki-workspaces+description: Ship and receive a Hydrogen bench with a wiki project. hydrogen/workspace.json in the page repo is the author's pane layout with apps referenced by wiki page (never by URL); export it from a live Hydrogen with adom-cli, push it with adom-wiki, fork or clone it, and apply it in a container. Covers the file format, the WORKSPACE_* hints, the resolved route, and the apply and export verbs. Trigger words - shared workspace, project workspace, hydrogen/workspace.json, workspace apply, workspace export, ship my layout, author's bench, open in hydrogen, WORKSPACE_INVALID, WORKSPACE_URL_LOCAL, WORKSPACE_APP_UNDECLARED, WORKSPACE_AVAILABLE, dock manifest, dockbar.json.+---++# Shared Hydrogen workspaces++A wiki project can carry its author's Hydrogen bench: which panes, which tabs, which apps, arranged how. The file is `hydrogen/workspace.json` in the page repo. It travels with clone and fork, the wiki validates it on every push and publish, and a container turns it back into a live layout with the apps installed and serving.++Two kinds of knowledge stay apart: the workspace says WHAT goes WHERE; each app's own page says HOW it runs (its `dockbar.json`). Apps are referenced by page (`owner/slug`), never by URL, because a URL only resolves on the machine it was saved on.++## Ship a bench (author)++```bash+# in the container where the bench is open in Hydrogen+adom-cli hydrogen workspace export --out hydrogen/workspace.json+# read the hints: WORKSPACE_URL_DROPPED names tabs that could not travel+adom-wiki repo push <owner>/<slug> -m "bench" --files hydrogen/workspace.json+```++The push answers `WORKSPACE_OK` (with the apply command) or refuses:+- `WORKSPACE_INVALID`: not the format (see below), nothing written.+- `WORKSPACE_URL_LOCAL`: a webview tab names localhost, a private address, a container proxy host (`*.adom.cloud`, `/proxy/`) or a non-https URL. Reference the app by page instead: `{ "panel": "app", "app": "owner/slug" }`.+- `WORKSPACE_APP_UNDECLARED` (warning): an app the project's `page.json` `dependencies` does not declare; add `"owner/slug": "*"` so a fork that installs the project pulls it.+- `WORKSPACE_APP_UNRESOLVED` (warning): an app page that does not exist; it becomes a placeholder tab on apply.++An app is launchable from a workspace when its page carries `dockbar.json` (dock_manifest 1.2.0: `webview.title`, `health.url`, `launch.steps` with one `await: "url"` step; optional `context: { query: [...], env: "ADOM_CONTEXT" }` and `requires: { desktop, bridges }`). The wiki validates it on push (`DOCK_MANIFEST_OK` / `DOCK_MANIFEST_INVALID`) and serves it at `GET /api/pages/<owner>/<slug>/dock-manifest`.++## Receive a bench (reader)++```bash+adom-wiki page workspace <owner>/<slug>      # the pane tree, each app's availability, the apply command+adom-wiki page fork <owner>/<slug> --apply    # fork answers WORKSPACE_AVAILABLE; --apply opens it+adom-cli hydrogen workspace apply <owner>/<slug> [--dry-run]+```++`apply` installs each app (`adom-wiki pkg install`), runs its dock manifest launch steps (a serving app is reused), waits on its health URL, rewrites the served URL through the container proxy, adds the tab's context query, then shapes the panes. It never creates, removes or replaces the VS Code pane: the file's single `editor` tab maps onto the pane you already have. Anything unresolvable (page missing, install failed, needs a desktop bridge that is not connected) becomes a placeholder tab naming the reason; the apply never fails as a whole. `--dry-run` prints the plan and touches nothing.++The project page draws the bench (pane boxes with tab names) and its "Open in Hydrogen" button copies the apply command. `GET /api/pages/<owner>/<slug>/workspace` returns the file resolved: per app `exists`, `declared`, `latest`, `dock_manifest`, `launchable`, `requires`.++## The file++```json+{+  "workspace_manifest": "1.0",+  "name": "Drone build bench",+  "root": {+    "type": "split", "direction": "horizontal", "ratio": 0.62,+    "first": { "type": "leaf", "tabs": [ { "panel": "editor" } ] },+    "second": { "type": "leaf", "activeTabIndex": 0, "tabs": [+      { "panel": "app", "app": "adom/drone-dashboard", "version": "^2", "route": "/board", "displayName": "Drone Dashboard", "args": { "project": "{project}" } },+      { "panel": "3d-viewer", "args": { "layout": "layouts/drone-bench.json" } },+      { "panel": "webview", "url": "https://wiki.adom.inc/adom/drone", "displayName": "Project page" }+    ] }+  },+  "requires": { "desktop": false, "bridges": [] }+}+```++Rules: panels are `editor`, `terminal`, `3d-viewer`, `webview`, `app` (never a catalog uuid); exactly one `editor`; splits carry `ratio` 0.1..0.9, leaves `activeTabIndex`; `app.args` are passed to the app as query parameters and `ADOM_CONTEXT_*` environment, with `{project}` = the owner/slug the bench was opened from and `{repo}` = the checkout path; no ids, tokens or per-user state. One file per project today; named variants (`hydrogen/workspaces/<name>.json`) follow.++## Gotchas++- Export drops tabs that cannot travel and says which (`WORKSPACE_URL_DROPPED`): a proxy URL nobody launched through adom-cli has no page to reference. Give that app a page with a `dockbar.json`, or accept that it stays local.+- The wiki and the CLI must agree on what is local: `*.adom.cloud` hosts and `/proxy/` paths are container-local everywhere.+- Hydrogen Cloud's own "Save" and "Load" entries are personal layouts stored in Carbon, a different thing; the shared file is what travels with the project.+