Adom Hydrogen (macOS / Lima)

@@ -1,134 +0,0 @@-----name: hd-topology-description: >-  MUST READ before ANY HD work. Explains the three-layer topology: cloud-  Docker (where Claude runs), the user's Mac (where HD + Adom Desktop run),-  and the HD local workspace (the Adom-Workspace machine). Every command-  you run goes through the relay to the Mac. You CANNOT directly access the-  workspace machine — you must shell through the Mac. Trigger words — HD topology,-  cloud vs local, machine exec, nsenter, where am I, which workspace, adom-desktop-  relay, test from container, three tiers, architecture, mac machine.------# Hydrogen Desktop — Topology (READ FIRST)--Machine-runtime version (default). Legacy Docker container runtime (`HD_RUNTIME=docker`) is in the docker/ bucket.--## You are NOT on the user's machine--You (Claude) run inside an **Adom cloud Docker container**. The user's-Mac is a remote target you reach through the `adom-desktop`-CLI relay. There are THREE separate environments:--### 1. Cloud Docker (where you run)-- Your shell, your filesystem, your git repos-- `adom-desktop` CLI connects to Adom Desktop on the Mac via relay-- This container has NOTHING to do with HD's local workspace-- Restarting the workspace machine on the Mac does NOT affect you-- You can freely `git push`, edit code, run builds here--### 2. The user's Mac (user's desktop)-- **Adom Desktop** — relay client app, listens on port 8770 (direct connect)-- **Hydrogen Desktop** — the Tauri app you're building-- **Lima VM (`hd-builder`)** — hosts the `Adom-Workspace` machine-- You reach this via `adom-desktop shell_execute '{"command":"..."}'`-- Commands run in a shell on the Mac (zsh/bash)--### 3. HD Local Workspace (machine) (the `Adom-Workspace` machine)-- Machine name: `Adom-Workspace` (fixed — no random suffix, no container name)-- Runs code-server, adom-desktop CLI, relay server-- You reach this via: `adom-desktop shell_execute '{"command":"limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- <cmd>"}'`-- This is TWO hops: cloud → relay → Mac → nsenter into the machine--## Command Patterns--### Run something on the Mac-```bash-adom-desktop shell_execute '{"command":"ls ~/adom"}'-```--### Run something in the HD local workspace machine-```bash-adom-desktop shell_execute '{"command":"limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- ls /home/adom"}'-```--### Test adom-desktop CLI inside the workspace machine-```bash-adom-desktop shell_execute '{"command":"limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- adom-desktop ping"}'-```-This tests the FULL chain: machine → local relay → Adom Desktop on the Mac.--### Screenshot HD window-```bash-adom-desktop desktop_screenshot_window '{"hwnd":HWND}'-```--### Pull file from the Mac to cloud-```bash-adom-desktop pull_file '{"filePaths":["/Users/.../file"],"saveTo":"/tmp"}'-```--## The workspace machine ≠ Your Container--- If the `Adom-Workspace` machine on the Mac goes down, YOUR cloud container is fine-- You can still talk to Adom Desktop, screenshot windows, run shell commands-- You just can't `nsenter` into the workspace machine until it's back-- Starting/stopping the machine on the Mac is done via shell_execute. Only ever-  touch `Adom-Workspace` (`machinectl terminate Adom-Workspace`) — NEVER tear down-  the shared Lima VM `hd-builder` wholesale or run a global `machinectl` teardown,-  which would knock out any other Lima VM / machine the user has.--## The Relay Chain--```-Cloud adom-desktop CLI-  → WS relay (cloud :8765)-    → internet-      → Adom Desktop on the Mac (relay client)-        → executes command locally-          → returns result-            → back through relay to your CLI-```--For the HD local workspace machine, there's a SECOND relay:-```-Workspace's adom-desktop CLI-  → local relay (machine :8765)-    → code-server proxy (:7380/proxy/8765/)-      → Adom Desktop on the Mac (connected as WS client)-        → executes command-          → returns through same chain-```--## Critical Setup Steps for the HD Local Workspace (machine)--The HD install flow MUST verify this chain works:--1. **Verify Adom Desktop running on the Mac** — probe port 8770-   If not running: tell user to install from wiki and launch it-2. **Install adom-desktop CLI into the workspace** — download binary-3. **Start relay inside the workspace** — `adom-desktop serve`-4. **Register relay with Adom Desktop** — `server_add` via direct connect-   URL: `ws://127.0.0.1:{code_server}/proxy/8765/`-5. **Test round-trip** — `limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- adom-desktop ping`-   Must return `pong` — proves the full chain works--## NEVER Do These--1. **NEVER confuse your cloud Docker with the HD local workspace machine.**-   `curl http://127.0.0.1:8766/health` hits YOUR relay, not the workspace's.-2. **NEVER try to enter the machine from your cloud shell.**-   The machine lives in the Lima VM on the Mac, not here.-3. **NEVER assume the workspace's status affects your container.**-   They're completely independent.-4. **NEVER tear down the shared Lima VM `hd-builder` wholesale or run a global-   `machinectl` teardown of anything other than `Adom-Workspace`.** Scope to the-   `Adom-Workspace` machine only (`machinectl terminate Adom-Workspace`) so the-   user's other Lima VMs / machines stay safe.-5. **NEVER skip the adom-desktop round-trip test.**-   The relay chain has many links — test end-to-end, not individual parts.--## Related skills--- `hd-container` — facts about the `Adom-Workspace` machine you run inside-- `hd-volume` — where your files live and how to back up / copy out the machine