Adom Hydrogen (macOS / Lima)

@@ -1,110 +0,0 @@-----name: hd-volume-description: How HD's machine workspace storage is laid out — what's persistent, what's ephemeral, where your work lives, what survives a workspace restart vs a virgin reset, and how to access your workspace files from your Mac host. Use when the user asks "where are my files", "did I lose my work", "how do I copy a file out of the workspace", or "what happens to my code if I virgin reset". Trigger words — machine filesystem, hd volume, where are my files, workspace files, persistent storage, lost my work, /home/adom/project, machine filesystem, machine export, copy file out of workspace, where is my code, workspace backup, machine remove.------# HD Workspace Storage — what persists, what doesn't--Machine-runtime version (default). Legacy Docker container runtime (`HD_RUNTIME=docker`) is in the docker/ bucket.--Your work lives on the `Adom-Workspace` machine's filesystem at `/home/adom/project` — a systemd-nspawn machine rootfs under the `hd-builder` Lima VM (e.g. `/var/lib/machines/Adom-Workspace`). There is **no Docker named volume** — `/home/adom/project` sits directly in the machine's own ext4 filesystem. ALL your work belongs under that path. It persists for as long as the machine stays registered.--## The filesystem--| Property | Value |-|----------|-------|-| Machine name | `Adom-Workspace` (fixed) |-| Your work path | `/home/adom/project` (plain directory in the machine's ext4 fs) |-| Backing store | The machine's rootfs directory inside the Lima VM (`hd-builder`), e.g. `/var/lib/machines/Adom-Workspace/` on the VM disk |-| On-disk location (Mac) | N/A on macOS — it lives inside the `hd-builder` Lima VM's disk image, not directly on the Mac. Reach it via the relay or `limactl shell hd-builder` + nsenter (see below) |-| Persistence | Survives workspace restart, HD restart, and Mac reboot. Persists as long as the machine stays **registered** (`machinectl`). |--There is **no named volume to delete separately** — the project files and the OS image are one and the same ext4 filesystem. The only thing that wipes `/home/adom/project` is removing the machine.--## What lives WHERE--| Path inside the machine | Persists across a tarball re-import? | Notes |-|------------------------|---------------------------------------|-------|-| `/home/adom/project/` | **Yes** — HD exports `/home/adom` before re-importing the golden image on a version bump, then restores it | This is your code. Put everything important here. |-| `~/.local/share/code-server/extensions/` | **Yes** within the machine — BAKED into the golden image, restored on tarball re-import | Not a setup step; baked at image-build time |-| `~/.local/share/code-server/User/settings.json` | **Yes** within the machine — BAKED into the golden image | Not a setup step; baked at image-build time |-| `~/.claude/` (skills, credentials) | Skills are BAKED into the golden image (restored on re-import); credentials are restored by the `claude-auth` setup step from a host-side backup | HD skills are baked FLAT into `~/.claude/skills/<name>/` |-| `/tmp/` | **No** | Ephemeral |-| `/etc/`, `/usr/`, system stuff | Lives in the same ext4 fs, but is overwritten on a tarball version bump | Treat as part of the workspace image |--**Rule of thumb:** if you want it to survive a workspace rebuild, put it under `/home/adom/project/`.--## What survives each virgin-reset choice--When you open Virgin Reset (HD setup panel), the checkbox toggles control which artifacts get deleted:--| Toggle ON means: | Result |-|------------------|--------|-| Install step state | `setup-steps-macos.json` deleted; next setup re-runs everything. Your project files unaffected. |-| Workspace machine | **`machinectl remove Adom-Workspace`. This wipes the ENTIRE machine including `/home/adom/project/`. This is the destructive option.** No reboot needed; the wipe is immediate. |-| Workspace image | Deletes the cached `adom-golden.tar.gz`, so setup re-downloads it on next run. Your machine (and your code, if still registered) is unaffected. |-| Adom session token | Re-login required next time. Project files unaffected. |-| Claude credentials | Claude Code requires re-auth. Project files unaffected. |--**The only toggle that destroys your work is "Workspace machine" (the `machinectl remove`).** All others are safe for your code. (Note: the "image" reset just deletes the cached `adom-golden.tar.gz` — NOT a 390MB Docker image like the legacy runtime.)--⚠️ The reset only ever targets `Adom-Workspace`. It NEVER touches the Lima VM itself or any other machine registered on the host.--## Accessing workspace files from the Mac--There is **no Finder share** into the machine (no macOS equivalent of the old `\\wsl$` Explorer share). Reach your files via the relay or by shelling into the Lima VM.--### 1. `limactl shell hd-builder` + nsenter + cp-```bash-# Drop into the Lima VM, enter the machine namespace as the adom user, and operate on files-limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- bash -lc \-  'ls -la /home/adom/project'-```-Use `limactl copy` to move files between the Mac and the VM disk, then `nsenter` + `cp` to land them in the machine's `/home/adom/project`.--### 2. From inside the machine, there is no `/mnt/c` drive mount-N/A on macOS — there are no Windows drive mounts. Use the relay instead (see below).--### 3. `adom-desktop send_files` / `pull_file` (from inside the workspace, via the relay)-```bash-# Send a workspace file to your Mac desktop's Downloads folder-adom-desktop send_files '{"filePaths":["/home/adom/project/myfile.txt"],"targetApp":"general","destinationFolder":"."}'--# Pull a Mac file into the workspace's /tmp-adom-desktop pull_file '{"filePaths":["/Users/<you>/Downloads/myfile.txt"],"saveTo":"/tmp"}'-```--### 4. Open the workspace's `/home/adom/project/` in VS Code's File Explorer-Just use the built-in code-server tree — the project folder is what's open, so anything you create/edit there hits the machine fs directly.--## Backing up your workspace--Persistence and backup for the machine is `machinectl export-tar` / `machinectl import-tar` (run inside the `hd-builder` Lima VM) — NOT a Docker volume tar. Before a destructive operation (the workspace-machine virgin-reset / `machinectl remove`):--```bash-# Export the whole machine to a tarball inside the Lima VM-limactl shell hd-builder -- sudo machinectl export-tar Adom-Workspace /tmp/adom-workspace-backup.tar-# (then limactl copy /tmp/adom-workspace-backup.tar back to the Mac if you want it off-VM)--# Restore it later (re-register the machine from the backup)-limactl shell hd-builder -- sudo machinectl import-tar /tmp/adom-workspace-backup.tar Adom-Workspace-```--This is exactly the mechanism HD's own tarball-migration uses: on a tarball version bump it `machinectl export-tar`s `/home/adom` first, then re-imports the new base and restores your work.--Or, for just a few files, copy them out first via the relay or `limactl shell hd-builder` + nsenter + cp.--## Why a machine filesystem (no named volume, no bind mount)?--HD keeps your work directly inside the `Adom-Workspace` ext4 filesystem rather than a Docker named volume or a bind mount of a Mac path. This:-- Gives native Linux ext4 I/O — much faster than crossing the macOS ↔ VM filesystem boundary-- Avoids line-ending and permission issues that bind mounts of host paths often have-- Lets HD wipe + re-import the base image (on a tarball bump) without losing your code — it `machinectl export-tar`s `/home/adom` first--There is no Finder share into the machine on macOS — use the relay (`adom-desktop send_files`/`pull_file`) or `limactl shell hd-builder` + nsenter + cp to move files in and out.--## Related skills--- `hd-container` — the `Adom-Workspace` machine whose filesystem holds your work-- `hd-topology` — the three-tier topology; tier 3 is this Adom-Workspace machine-- `hd-golden-image` — what's baked into `adom-golden.tar.gz` (extensions, settings, skills) vs. what setup does