# adom/hydrogen-mac-bootstrap

The **macOS** platform layer for Adom Hydrogen. On a Mac, Hydrogen'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/hydrogen-bootstrap`.

<img src="screenshots/workspace-macos.png" alt="Adom Hydrogen running natively on macOS — VS Code + Claude on the left, an Adom webview on the right, workspace in the local Lima/nspawn machine" width="760">

```
adom-wiki pkg install adom/hydrogen-mac-bootstrap --allow-sudo   # the golden Lima image bakes this;
                                                           # Hydrogen's setup re-converges it every install
```

## The platform-layered bootstrap stack

```
adom/core                         ← Adom ecosystem (generic; shared with web Hydrogen)
  └─ adom/hydrogen-bootstrap            ← Adom Hydrogen, platform-GENERIC
       ├─ adom/hydrogen-windows-bootstrap   ← WSL2 runtime
       ├─ adom/hydrogen-mac-bootstrap       ← THIS — Lima/nspawn runtime
       └─ adom/hydrogen-ubuntu-bootstrap    ← native-Ubuntu runtime
```

Each platform layer depends on `adom/hydrogen-bootstrap`, which depends on `adom/core`,
so `core` stays generic across web + desktop Hydrogen and every host OS.

## What this layer adds

- **Dependencies:** `adom/hydrogen-bootstrap` (generic Hydrogen) + `adom/adom-workspace-updater`
  (the in-machine systemd updater daemon).
- **Bundled skills:** the macOS-runtime `hd-*` skills — `hydrogen-container`,
  `hydrogen-container-stats`, `hydrogen-networking`, `hydrogen-ports`, `hydrogen-port-watcher`, `hydrogen-setup`,
  `hydrogen-setup-steps`, `hydrogen-topology`, `hydrogen-volume`, `hydrogen-workspace-lifecycle`,
  `hydrogen-workspace-monitoring` (sourced from
  `adom-hydrogen/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
  `hydrogen-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 — Hydrogen's setup cascade (0.1.135+) runs the chain's
  deploy scripts explicitly (`core → hd-bootstrap → hydrogen-mac-bootstrap`) so a fresh
  skills release actually reaches an already-baked machine.

## The macOS runtime

The **workspace is always Linux**; on a Mac that Linux runs in a local VM:

| | macOS layer (this) |
|---|---|
| Linux host | Lima VM (`hd-builder`) → nspawn machine (`Adom-Workspace`) |
| Provisioning | `machinectl import-tar` of the golden Lima image |
| Host↔workspace | Lima virtiofs share + `adom-host` gateway |
| Golden image | `hd-lima-image` |

## The mixed-skill split (`<name>-mac` companions)

`adom/hydrogen-bootstrap` carries the **31 platform-generic** `hd-*` skills. **13 mixed**
skills are split per platform: the generic core stays in `hd-bootstrap`, and each
platform layer carries its own half. This layer carries the **macOS halves** in
`skills/<name>-mac/`.

**Companions authored (11):**
- `hydrogen-api-mac` — `adom-host` gateway, `~/.adom/hd-control-url` discovery, vz-no-loopback, `/workspace/*` (nspawn) endpoints.
- `hydrogen-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.
- `hydrogen-notifications-mac` — Notification Center toasts + emergency Dock-bounce + the Notifications grant.
- `hydrogen-recording-mac` — Hydrogen's native recorder does not exist on macOS, so recording is in-app getDisplayMedia / pup / relay; ScreenCaptureKit native recorder **not yet built** (honest gap). Screen Recording TCC.
- `hydrogen-screen-lock-mac` — IOKit `IOPMAssertionCreateWithName`/`PreventUserIdleDisplaySleep`, `pmset -g assertions`, `caffeinate`.
- `hydrogen-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.
- `hydrogen-browser-picker-mac` — WKWebView-over-`localhost` interception + LaunchServices `open -a` native browsers.
- `hydrogen-permissions-mac` — the macOS TCC model (Screen Recording, Accessibility, Automation, Camera/Mic) + preflight/relaunch.
- `hydrogen-open-url-mac` — `open`/`open -a … --new-window` LaunchServices launch + control-URL discovery.
- `hydrogen-ui-mac` — driving the UI via the `hd-ui-command`→`/ui/_result` command bus + `invoke_ui_action` (WKWebView has no CDP).
- `hydrogen-captions-mac` — workspace caption is platform-neutral; the desktop overlay (`desktop_caption`) is not implemented on macOS (honest gap).

> Note: the macOS-runtime skills in `skills/` that are **whole** (the `machine/` bucket
> — `hydrogen-setup`, `hydrogen-container`, …) are platform-clean skills, so they ship
> complete rather than as `-mac` halves. The exact 13-skill mixed set should be
> reconciled against the sibling platform layers' companions.

> NOTE — naming: the canonical slug for this layer is **`hydrogen-mac-bootstrap`**, not
> `hd-macos-bootstrap`.