Adom Hydrogen (macOS / Lima)

⋯ 1 unchanged line ⋯

@@ -4,9 +4,10 @@   "type": "bootstrap",   "title": "Hydrogen Desktop (macOS / Lima)",   "brief": "The macOS platform layer for Hydrogen Desktop.",-  "version": "0.1.1",+  "version": "0.1.3",   "description": "The macOS platform layer for Hydrogen Desktop, where the workspace runs in a Lima Ubuntu VM hosting the Adom-Workspace systemd-nspawn machine. Depends on adom/hd-bootstrap (the platform-generic HD layer) and adds everything specific to the Lima/nspawn runtime: the container/networking/ports/setup/topology/volume/workspace-lifecycle hd-* skills (the macOS-runtime bucket), the in-machine workspace-updater daemon, and the macOS code-server workbench seed. Sibling layers adom/hd-windows-bootstrap (WSL2) and adom/hd-ubuntu-bootstrap depend on the same adom/hd-bootstrap. This is the package the golden Lima image installs.",   "org": "adom",+  "platform": "linux",   "tags": [     "bootstrap",     "hydrogen-desktop",@@ -35,7 +36,7 @@   ],   "hero": {     "headline": "Hydrogen Desktop for macOS",-    "subhead": "The Lima/nspawn workspace layer — AI-driven electronics design, native on Apple Silicon.",+    "subhead": "The Lima/nspawn workspace layer \u2014 AI-driven electronics design, native on Apple Silicon.",     "screenshot": "docs/hero.png"   } }\ No newline at end of file

@@ -4,7 +4,7 @@   "slug": "hd-mac-bootstrap",   "title": "Hydrogen Desktop (macOS / Lima)",   "brief": "The macOS platform layer for Hydrogen Desktop.",-  "version": "0.1.2",+  "version": "0.1.3",   "license": "proprietary",   "visibility": {     "public": true

@@ -39,4 +39,14 @@ else   log "code-server not found at $WB_DIR yet — skipping workbench seed (non-fatal)" fi +# ── the `shot` helper — token-efficient screenshots for the workspace AI ─────────────────────+# `adom-cli hydrogen screenshot` prints a ~300 KB base64 dataUrl to stdout; raw in an AI+# conversation that's ~85k wasted tokens per capture. `shot` decodes inline and prints only+# the PNG path (the AI then Reads it). See hd-self-screenshot-mac for the doctrine.+if [ -f "$HERE/bin/shot" ]; then+  mkdir -p "$HOME/.local/bin"+  install -m 755 "$HERE/bin/shot" "$HOME/.local/bin/shot"+  log "installed the 'shot' screenshot helper -> ~/.local/bin/shot"+fi+ log "macOS platform layer converged."

⋯ 1 unchanged line ⋯

@@ -30,13 +30,13 @@ You are running inside the **`Adom-Workspace` machine** managed by Hydrogen Desk  If you ever need to confirm: `cat /etc/os-release`, `uname -m` (expect `aarch64` on Apple Silicon), `/usr/lib/code-server/bin/code-server --version`. Don't speculate about alpine — it's Ubuntu 24.04, same distro as the cloud container (the cloud is amd64; this macOS port is arm64 + Rosetta for the x86-64 Adom CLIs). -## Setup is via HD's setup-steps, NOT the legacy bootstrap.sh+## Setup is via HD's setup-steps -HD provisions this machine through its own **setup-steps** flow (Rust code in `hydrogen-desktop/src-tauri/crates/hd-app/src/setup_steps_macos.rs`, with the runtime mechanics in `hydrogen-desktop/src-tauri/crates/hd-app/src/runtime/macos.rs`), shown as the "Install Tools" panel in the HD UI. It is a **different code path** than cloud containers, which run the legacy `scripts/bootstrap.sh`.+HD provisions this machine through its own **setup-steps** flow (Rust code in `hydrogen-desktop/src-tauri/crates/hd-app/src/setup_steps_macos.rs`, with the runtime mechanics in `hydrogen-desktop/src-tauri/crates/hd-app/src/runtime/macos.rs`), shown as the "Install Tools" panel in the HD UI. It is a **different code path** than cloud containers. -The machine cascade is **18 steps** (state file `setup-steps-macos.json`) vs the legacy Docker flow's 24. Most tooling is NOT installed by a step — it's BAKED into `adom-golden.tar.gz` at image-build time (the 8 Adom CLIs, the adompkg skills, the claude CLI + Code extension, code-server, VS Code settings, and all `hd-*` skills). The Docker `pull-image` / `create-container` / `start-container` steps are collapsed into a single step 1, `ensure-workspace`, which runs `machinectl import-tar` of `adom-golden.tar.gz` if the machine isn't already present. The relay is started by the `start-relay` step. See `hd-golden-image`.+The machine cascade is **18 steps** (state file `setup-steps-macos.json`) vs the legacy Docker flow's 24. Most tooling is NOT installed by a step — it's BAKED into `adom-golden.tar.gz` at image-build time (the 8 Adom CLIs, the claude CLI + Code extension, code-server, VS Code settings, and all `hd-*` skills). The Docker `pull-image` / `create-container` / `start-container` steps are collapsed into a single step 1, `ensure-workspace`, which runs `machinectl import-tar` of `adom-golden.tar.gz` if the machine isn't already present. The relay is started by the `start-relay` step. See `hd-golden-image`. -When debugging install issues here, the source of truth is `setup_steps_macos.rs` (and `runtime/macos.rs`) — its step IDs (`ensure-workspace`, `install-adom-vscode`, `set-env-vars`, `inject-api-key`, `start-relay`, `claude-auth`, etc.) map 1:1 to what ran on this machine. There is NO `install-claude-ext` / `install-claude-cli` / `install-skills` / `write-vscode-settings` step anymore — those are baked. Do NOT chase bugs into `bootstrap.sh` first — that script lives in the baked image but HD itself never invokes it. (For the legacy Docker `setup_steps.rs` flow see the docker/ bucket.)+When debugging install issues here, the source of truth is `setup_steps_macos.rs` (and `runtime/macos.rs`) — its step IDs (`ensure-workspace`, `install-adom-vscode`, `set-env-vars`, `inject-api-key`, `start-relay`, `claude-auth`, etc.) map 1:1 to what ran on this machine. There is NO `install-claude-ext` / `install-claude-cli` / `write-vscode-settings` step anymore — those are baked. (For the legacy Docker `setup_steps.rs` flow see the docker/ bucket.)  ## VS Code extension caveats @@ -123,7 +123,6 @@ adom-desktop desktop_open_folder '{"path": "/Users/john/project"}'  - `ADOM_DESKTOP_MODE=local` — indicates HD local mode - `HD_RUNTIME=macos` — indicates the machine runtime (default); `docker` selects the legacy container runtime-- `ADOM_SERVICE=local` — marks this as a local workspace - `VSCODE_PROXY_URI=http://localhost:7380/proxy/{{port}}/` — code-server's proxy  ## Related skills

@@ -2,17 +2,19 @@ name: hd-self-screenshot-mac description: >   macOS platform companion to hd-self-screenshot — the Apple-specific half of HD-  screenshotting its own window. The tool ladder (default `adom-cli hydrogen-  screenshot panel|workspace|screen`), the `POST /screenshot` CDP endpoint, selector-  region-clips, the sharing gate, and the during-a-recording contention matrix live in-  hd-self-screenshot (adom/hd-bootstrap); THIS skill carries only the macOS capture-  internals: the `screencapture` CLI / CoreGraphics window path, the CDP-  `Page.captureScreenshot` content grab, how the per-panel selector crop resolves the-  rect via `dom.measure` (WKWebView has no CDP) and crops with the image crate, and the-  Screen Recording TCC grant. Mirror of hd-self-screenshot-windows (Win32-  PrintWindow/BitBlt). Trigger words — screenshot hd mac, screencapture cli,-  coregraphics screenshot, wkwebview no cdp, dom.measure crop, page.capturescreenshot-  mac, screen recording permission screenshot, tcc screenshot grant.+  screenshotting its own window, PLUS the token-efficient capture flow (`shot` — one+  call, prints a PNG path, never floods context with base64). The tool ladder, the+  `POST /screenshot` CDP endpoint, selector region-clips, the sharing gate, and the+  during-a-recording contention matrix live in hd-self-screenshot (adom/hd-bootstrap);+  THIS skill carries the `shot` helper doctrine and the macOS capture internals: the+  `screencapture` CLI / CoreGraphics window path, the CDP `Page.captureScreenshot`+  content grab, how the per-panel selector crop resolves the rect via `dom.measure`+  (WKWebView has no CDP) and crops with the image crate, and the Screen Recording TCC+  grant. Mirror of hd-self-screenshot-windows (Win32 PrintWindow/BitBlt). Trigger+  words — screenshot hd mac, shot helper, token efficient screenshot, screencapture+  cli, coregraphics screenshot, wkwebview no cdp, dom.measure crop,+  page.capturescreenshot mac, screen recording permission screenshot, tcc screenshot+  grant. ---  # hd-self-screenshot (macOS) — screencapture / CoreGraphics + the CDP content path@@ -22,7 +24,33 @@ hydrogen screenshot panel|workspace|screen` saving a PNG into the container's `screenshots/` to `Read`, the `POST /screenshot {target,selector,b64,silent}` CDP power-path, the sharing gate, and the multi-thread `capture_busy` / coexistence matrix — is cross-platform and lives in the generic **hd-self-screenshot** skill. Read that-first; this skill only documents what's Apple-specific about how the bytes are grabbed.+first; this skill documents the token-efficient capture flow and what's Apple-specific+about how the bytes are grabbed.++## ⭐ ALWAYS capture with `shot` — 2 tool calls, ~20 bytes of output++**Never run `adom-cli hydrogen screenshot ...` bare.** It prints the capture as a+~300 KB base64 `dataUrl` JSON on stdout — that's ~85k tokens of noise in your context+per capture, plus a second decode step you'd have to improvise. This bootstrap installs+a wrapper that does the whole thing in one call and prints ONLY the PNG path:++```bash+shot                        # whole workspace (all panels)  → /tmp/shot-workspace-<ts>.png+shot screen                 # entire screen (desktop, other apps)+shot panel --name "KiCad"   # one panel's content+shot workspace --reason "verify the flow viewer rendered"   # flags pass through+```++Then **Read** the printed path — the Read tool attaches images efficiently. Total flow:+one Bash call + one Read. That's the floor; don't add steps.++- If no image comes back, `shot` exits 1 and prints the CLI's own JSON to stderr —+  usually the **sharing gate** (capture needs the user's sharing approval; pass+  `--reason "…"` so the approval dialog says why). Read the error, don't blind-retry.+- `SHOT_OUT=/path/out.png shot ...` overrides the output path if you need a stable name.+- If `shot` is missing (pre-0.1.3 workspace), re-converge: `adom-wiki pkg install+  adom/hd-mac-bootstrap` — or inline the same pipe:+  `adom-cli hydrogen screenshot workspace 2>/dev/null | python3 -c "import sys,json,base64;d=json.load(sys.stdin);open('/tmp/ws.png','wb').write(base64.b64decode(d['dataUrl'].split(',',1)[1]));print('/tmp/ws.png')"`  ## How HD grabs its own window on macOS 

@@ -1,6 +1,6 @@ --- name: hd-setup-steps-description: What HD's setup steps did to prepare your workspace — the 18-step install sequence that imports the Adom-Workspace golden image, injects your Adom session, wires up the relay, and walks the Claude auth gate. Use this skill when the user asks "what did setup do", "why is X installed", "re-run a setup step", "what's a virgin reset", or "why did step N fail". Trigger words — setup steps, install steps, setup panel, virgin reset, re-run step, Run All, what did setup do, why is X installed, setup failed, install-tools, hd setup, claude code extension install, skills install, hd workspace ready.+description: What HD's setup steps did to prepare your workspace — the 18-step install sequence that imports the Adom-Workspace golden image, injects your Adom session, wires up the relay, and walks the Claude auth gate. Use this skill when the user asks "what did setup do", "why is X installed", "re-run a setup step", "what's a virgin reset", or "why did step N fail". Trigger words — setup steps, install steps, setup panel, virgin reset, re-run step, Run All, what did setup do, why is X installed, setup failed, install-tools, hd setup, claude code extension install, hd workspace ready. ---  # HD Setup Steps — what was done to prepare your workspace@@ -8,7 +8,7 @@ description: What HD's setup steps did to prepare your workspace — the 18-step Machine-runtime version (default). The legacy 24-step Docker cascade (`HD_RUNTIME=docker`) is in the docker/ bucket. -When you first launched Hydrogen Desktop (or after a virgin reset), HD ran a 18-step install sequence to turn a blank workspace into a fully-tooled Adom workspace — the `Adom-Workspace` machine. The heavy tooling (code-server, the 8 Adom CLIs, the adompkg skills, the claude CLI + Code extension, VS Code settings, and all `hd-*` skills) is already BAKED into the golden image; setup just imports that image, injects your Adom session, wires up the relay, and walks the Claude auth gate. This skill explains what each step did so you can help the user understand their environment, re-run failed steps, or wipe and rebuild. See `hd-golden-image` for the baked-image model.+When you first launched Hydrogen Desktop (or after a virgin reset), HD ran a 18-step install sequence to turn a blank workspace into a fully-tooled Adom workspace — the `Adom-Workspace` machine. The heavy tooling (code-server, the 8 Adom CLIs, the claude CLI + Code extension, VS Code settings, and all `hd-*` skills) is already BAKED into the golden image; setup just imports that image, injects your Adom session, wires up the relay, and walks the Claude auth gate. This skill explains what each step did so you can help the user understand their environment, re-run failed steps, or wipe and rebuild. See `hd-golden-image` for the baked-image model.  The cascade is executed by `setup_steps_macos.rs` (`step_defs_machine()` / `run_all_machine()`). `run_all_machine` is halt-on-failure, resume-not-restart, with per-step 3× auto-retry. In-machine work runs via `limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- bash -lc '<cmd>'` (the machine's DEFAULT user is `adom`, UID 1001, home `/home/adom`; under systemd-nspawn there's no wsl.conf — the default user comes from the machine config / nsenter `-S 1001 -G 1001`; root variant drops `-S 1001 -G 1001`). There is NO `docker exec` and NO Docker image anywhere in this flow. @@ -41,7 +41,7 @@ These are NOT setup steps anymore — they are baked at image-build time: `insta  ## Common user questions -**"Why is X installed in my workspace?"** → If X is an adompkg skill, an Adom CLI, the claude CLI, the Claude Code extension, VS Code settings, or an `hd-*` skill, it was **baked into the golden image** — not run as a setup step. The setup steps only import the image, inject your session, wire the relay, and walk Claude auth. The setup panel (HD UI → bottom) lists every step with its current status.+**"Why is X installed in my workspace?"** → If X is an Adom CLI, the claude CLI, the Claude Code extension, VS Code settings, or an `hd-*` skill, it was **baked into the golden image** — not run as a setup step. The setup steps only import the image, inject your session, wire the relay, and walk Claude auth. The setup panel (HD UI → bottom) lists every step with its current status.  **"Setup failed at step N"** → The setup panel shows the error. Most common failures: step 1 (Lima VM `hd-builder` not available / failed to provision, or the `adom-golden.tar.gz` download), step 11 (test-adom-cli — carbon/hydrogen-proxy not reachable yet), step 12 (Claude credentials expired). Each step has a retry button (and the cascade already retried it 3×). 

@@ -18,7 +18,7 @@ Machine-runtime version (default). The legacy 24-step Docker cascade  The HD setup process targets ZERO manual clicks for the user. The heavy lifting is already done at image-build time: the `Adom-Workspace` golden-image ships with code-server, the 8 Adom CLIs, the adompkg skills, the claude CLI + Code+image ships with code-server, the 8 Adom CLIs, the claude CLI + Code extension, VS Code settings, and all `hd-*` skills BAKED IN. Setup just imports that image, injects the user's session, wires up the relay, and walks the single human auth gate. If something is missing, HD downloads it — never@@ -60,7 +60,7 @@ These are NOT setup steps anymore — they are baked at image-build time and must not be listed or "run": `install-hd-skills`, `verify-adom-desktop`, `install-claude-cli`, `install-claude-ext`, `write-vscode-settings`, `set-trusted-domains`, `clean-layout`. The 8-Adom CLIs, the adompkg skills, the claude CLI + Code extension, code-server, settings, and all+Adom CLIs, the claude CLI + Code extension, code-server, settings, and all `hd-*` skills are baked into the `adom-golden.tar.gz` image. See `hd-golden-image`. @@ -185,7 +185,7 @@ a real layout; `welcome` opens Claude Code and sends the first prompt; the final `open-welcome` gate opens welcome.html in HD's right pane and HARD-FAILS if the Welcome tab doesn't appear. -> Note: the Adom CLIs, the adompkg skills, the claude CLI + Code extension, VS Code+> Note: the Adom CLIs, the claude CLI + Code extension, VS Code > settings, and `hd-*` skills are NOT setup steps — they are baked into > `adom-golden.tar.gz`. See `hd-golden-image`.