# adom/hd-mac-bootstrap
The **macOS** platform layer for Hydrogen Desktop. On a Mac, HD's workspace runs
inside a **Lima Ubuntu VM** (`hd-builder`) that hosts the **`Adom-Workspace`
systemd-nspawn machine**; this package adds everything specific to that runtime on
top of the platform-generic `adom/hd-bootstrap`.
```
adom-wiki pkg install adom/hd-mac-bootstrap --allow-sudo # the golden Lima image bakes this;
# HD's setup re-converges it every install
```
## The platform-layered bootstrap stack
```
adom/core ← Adom ecosystem (generic; shared with web Hydrogen)
└─ adom/hd-bootstrap ← Hydrogen Desktop, platform-GENERIC
├─ adom/hd-windows-bootstrap ← WSL2 runtime
├─ adom/hd-mac-bootstrap ← THIS — Lima/nspawn runtime
└─ adom/hd-ubuntu-bootstrap ← native-Ubuntu runtime
```
Each platform layer depends on `adom/hd-bootstrap`, which depends on `adom/core`,
so `core` stays generic across web + desktop Hydrogen and every host OS.
## What this layer adds
- **Dependencies:** `adom/hd-bootstrap` (generic HD) + `adom/adom-workspace-updater`
(the in-machine systemd updater daemon).
- **Bundled skills:** the macOS-runtime `hd-*` skills — `hd-container`,
`hd-container-stats`, `hd-networking`, `hd-ports`, `hd-port-watcher`, `hd-setup`,
`hd-setup-steps`, `hd-topology`, `hd-volume`, `hd-workspace-lifecycle`,
`hd-workspace-monitoring` (the Lima/nspawn analogs of the Windows layer's WSL2 set,
sourced from `hydrogen-desktop/skills/public-facing/machine/`).
- **install script:** deploys those skills into `~/.claude/skills/` on top of the
generic layer, and installs the **`shot`** helper (`~/.local/bin/shot`) — one-call,
token-efficient workspace screenshots that print only a PNG path (see
`hd-self-screenshot-mac`) — plus the **Adom-branded Claude Code statusline**
(`~/.claude/statusline.sh`: model + context bar + 5h usage; only set when the
user hasn't configured their own). Note `adom-wiki pkg install` does **not** re-run install
scripts for already-baked packages — HD's setup cascade (0.1.135+) runs the chain's
deploy scripts explicitly (`core → hd-bootstrap → hd-mac-bootstrap`) so a fresh
skills release actually reaches an already-baked machine.
## The runtime difference vs. the Windows layer
The **workspace is Linux in both cases** — the layers differ only in *where* that
Linux runs and how the host reaches it:
| | Windows layer | macOS layer (this) |
|---|---|---|
| Linux host | WSL2 Ubuntu distro | Lima VM (`hd-builder`) → nspawn machine (`Adom-Workspace`) |
| Provisioning | `wsl --import` of the golden WSL2 image | `machinectl import-tar` of the golden Lima image |
| Host↔workspace | `\\wsl$` share + WSL networking | Lima virtiofs share + `adom-host` gateway |
| Golden image | `hd-wsl2-image` | `hd-lima-image` |
## The mixed-skill split (`-mac` companions)
`adom/hd-bootstrap` carries the **31 platform-generic** `hd-*` skills. The Windows
layer split **13 mixed** skills into `-windows` companions (e.g.
`hd-api-windows`, `hd-notifications-windows`, `hd-setup-windows`) — the generic core
stays in `hd-bootstrap`, the Windows half drops into `hd-windows-bootstrap`. This
layer carries the parallel **macOS halves** in `skills/-mac/`.
**Companions authored (11):**
- `hd-api-mac` — `adom-host` gateway, `~/.adom/hd-control-url` discovery, vz-no-loopback, `/workspace/*` (nspawn) endpoints (mirror of `hd-api-windows`' `/wsl/*` tables).
- `hd-api-key-mac` — diagnose/repair the injected `/var/run/adom/api-key` session token (adom-cli 401s, tmpfs wipe on machine reboot, pre-0.1.148 post-auth gap): pull via `GET /auth-token`, prompt the user to reauthorize, or trigger the `inject-api-key` setup step.
- `hd-notifications-mac` — Notification Center toasts + emergency Dock-bounce + the Notifications grant (mirror of `hd-notifications-windows`' WinRT/AUMID).
- `hd-recording-mac` — the native recorder is `#[cfg(windows)]`, so on macOS recording is in-app getDisplayMedia / pup / AD relay; ScreenCaptureKit native recorder **not yet built** (honest gap). Screen Recording TCC.
- `hd-screen-lock-mac` — IOKit `IOPMAssertionCreateWithName`/`PreventUserIdleDisplaySleep`, `pmset -g assertions`, `caffeinate` (vs `SetThreadExecutionState`).
- `hd-self-screenshot-mac` — `screencapture`/CoreGraphics + CDP `Page.captureScreenshot`; per-panel crop resolves the rect via the `dom.measure` RPC (no CDP on WKWebView) + `image`-crate crop (vs Win32 `PrintWindow`).
- `hd-browser-picker-mac` — WKWebView-over-`localhost` interception + LaunchServices `open -a` native browsers (vs WebView2/COM 6-layer interception).
- `hd-permissions-mac` — the macOS TCC model (Screen Recording, Accessibility, Automation, Camera/Mic) + preflight/relaunch (vs UAC).
- `hd-open-url-mac` — `open`/`open -a … --new-window` LaunchServices launch + control-URL discovery (vs `chrome.exe`/`msedge.exe`).
- `hd-ui-mac` — driving the UI via the `hd-ui-command`→`/ui/_result` command bus + `invoke_ui_action` (WKWebView has no CDP; raw CDP clicking is Windows-only).
- `hd-captions-mac` — workspace caption is platform-neutral; the desktop overlay (`desktop_caption`) is a **Windows-only** stub on macOS (honest gap).
> Reconcile the exact 13-skill set against `adom/hd-windows-bootstrap`'s companions
> (its source is `--hide-source` sealed; read it from a workspace with org access).
> The machine-bucket skills above ship whole (they map to the Windows layer's *clean*
> skills, not its mixed companions).
> Note: the macOS-runtime skills in `skills/` that are **whole** (the `machine/` bucket
> — `hd-setup`, `hd-container`, …) correspond to the Windows layer's *clean* skills, not
> its mixed companions, so they ship complete rather than as `-mac` halves. The exact
> 13-skill set should be reconciled against `adom/hd-windows-bootstrap`'s companions
> (its source is `--hide-source` sealed; read it from a workspace with org access).
> NOTE — naming: the canonical sibling slug is **`hd-mac-bootstrap`** (as referenced
> by `adom/hd-windows-bootstrap`'s own description and stack diagram), not
> `hd-macos-bootstrap`.