chore: prefer Podman for local act container CI

AGENTS.md

@@ -113,7 +113,7 @@ Adding a cross-boundary feature:
 
 **Key commands:** `pnpm run dev`, `pnpm run lint`, `pnpm run typecheck`, `pnpm run test:run`, `pnpm run update`. Reticulum sidecar: `pnpm run check:reticulum-sidecar` (pre-commit stub), `pnpm run reticulum:sidecar:clippy:full`, `pnpm run reticulum:sidecar:test`.
 
-**Local Linux CI (optional):** Container mode — `act:ci`, `act:tests`, `act:pr`, … (needs Docker + act). Host mode — `act:ci:native`, `act:tests:native`, … (no Docker). See [docs/ci-cd.md](docs/ci-cd.md). macOS/Windows packaging uses native `dist:mac` / `dist:win`. **`dist:mac`** / **`dist:mac:publish`** always run **`scripts/verify-mac-packaging.mjs`** (ZIP + DMG symlink asserts, no raw `.app` CI uploads). macOS signing env (`CSC_LINK`, `CSC_KEY_PASSWORD`, `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`, `CSC_IDENTITY_AUTO_DISCOVERY`) is scoped to **`macos-latest`** jobs in `release.yaml` / `build.yaml`; partial-secret validation fails the release job when `CSC_LINK` is set but notarization secrets are missing.
+**Local Linux CI (optional):** Container mode — `act:ci`, `act:tests`, `act:pr`, … (needs a Docker-compatible engine + act; Podman preferred). Host mode — `act:ci:native`, `act:tests:native`, … (no container engine). See [docs/ci-cd.md](docs/ci-cd.md). macOS/Windows packaging uses native `dist:mac` / `dist:win`. **`dist:mac`** / **`dist:mac:publish`** always run **`scripts/verify-mac-packaging.mjs`** (ZIP + DMG symlink asserts, no raw `.app` CI uploads). macOS signing env (`CSC_LINK`, `CSC_KEY_PASSWORD`, `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`, `CSC_IDENTITY_AUTO_DISCOVERY`) is scoped to **`macos-latest`** jobs in `release.yaml` / `build.yaml`; partial-secret validation fails the release job when `CSC_LINK` is set but notarization secrets are missing.
 
 > **Update script sync:** When adding or removing packages from `patchedDependencies` in `pnpm-workspace.yaml`, keep `WATCH_ENTRIES` in `scripts/update.sh` in sync so the script warns on version changes to every patched dependency. When adding or removing Ratspeak overlays under `reticulum-sidecar/patches/`, keep `RATSPEAK_PATCH_ENTRIES` in `scripts/update.sh` (`check_ratspeak_patches`) in sync — `pnpm run update` queries upstream PRs (rsReticulum / rsLXMF / rsNomad) and warns when a local overlay can be removed. `pnpm run update` also runs `rustup update` (or Homebrew `rust` on macOS without rustup) and `cargo build` in `reticulum-sidecar/` when `cargo` is on `PATH` (full-feature build includes `nomad-core` / rsNomad).
 

docs/ci-cd.md

@@ -140,12 +140,14 @@ Do not use `npm install`; it will create a `package-lock.json` and may not respe
 
 **Optional tooling:** You can run local CI in two ways:
 
-| Mode                    | Command prefix                                  | Requires                                      | What it does                                                        |
-| ----------------------- | ----------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------- |
-| **Container** (default) | `pnpm run act:ci`, `act:tests`, …               | Docker + [act](https://github.com/nektos/act) | Runs GitHub Actions jobs inside Linux containers (closest to CI)    |
-| **Host / native**       | `pnpm run act:ci:native`, `act:tests:native`, … | Node/pnpm only                                | Runs the same pnpm/cargo steps directly on your machine (no Docker) |
+| Mode                    | Command prefix                                           | Requires                                                        | What it does                                                                  |
+| ----------------------- | -------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| **Container** (default) | `pnpm run act:ci`, `pnpm run act:tests`, …               | Docker-compatible engine + [act](https://github.com/nektos/act) | Runs GitHub Actions jobs inside Linux containers (closest to CI)              |
+| **Host / native**       | `pnpm run act:ci:native`, `pnpm run act:tests:native`, … | Node/pnpm only                                                  | Runs the same pnpm/cargo steps directly on your machine (no container engine) |
 
-`pnpm run check:environment` warns if Docker or act is missing but does not block commits. Use **native** scripts when Docker Desktop is unavailable or act cannot reach the daemon.
+Container mode runs GitHub Actions jobs inside Linux containers using a Docker-compatible engine (Podman preferred). Host mode runs the same pnpm/cargo steps directly — use this when no container engine is available or act cannot reach the daemon. `pnpm run check:environment` warns if no container engine or act is missing but does not block commits. Use **native** scripts when no Docker-compatible engine is available or act cannot reach the daemon.
+
+**macOS note:** [Podman Desktop](https://podman.io/) is the preferred Docker-compatible engine for local CI. When Docker compatibility is enabled, Podman exposes a Docker-compatible socket at `/var/run/docker.sock`; pass that path to `act` via `ACT_DOCKER_SOCKET`, or let `act` detect it automatically if Podman created the symlink. If you use Docker Desktop instead, its socket is typically under `~/.docker/run/docker.sock`.
 
 Install act (container mode only):
 
@@ -157,9 +159,9 @@ brew install act
 # https://github.com/nektos/act/releases
 ```
 
-On Windows, use Docker Desktop with the WSL2 backend. On Apple Silicon, act uses `--container-architecture linux/amd64` automatically for x86_64 CI parity.
+On Windows, Podman Desktop with Docker compatibility is preferred. If you use Docker Desktop instead, use the WSL2 backend. On Apple Silicon, `act` uses `--container-architecture linux/amd64` automatically for x86_64 CI parity.
 
-**Docker Desktop:** `scripts/run-act.mjs` passes `--container-daemon-socket` to act (auto-detects `~/.docker/run/docker.sock` on macOS). If act still cannot connect, set `ACT_DOCKER_SOCKET` to your socket path or use native mode.
+**Podman:** `scripts/run-act.mjs` passes `--container-daemon-socket` to `act` (auto-detects `/var/run/docker.sock` on macOS). If `act` still cannot connect, set `ACT_DOCKER_SOCKET` to your socket path or use native mode. If you use Docker Desktop instead, its socket is typically under `~/.docker/run/docker.sock`.
 
 ### Package scripts
 
@@ -170,12 +172,12 @@ pnpm run act:pull-images
 # List targets
 pnpm run act:list
 
-# PR parity — container (act + Docker)
+# PR parity — container (act + Podman/Docker)
 pnpm run act:ci
 pnpm run act:tests
 pnpm run act:pr
 
-# PR parity — host (no Docker)
+# PR parity — host (no container engine)
 pnpm run act:ci:native
 pnpm run act:tests:native
 pnpm run act:pr:native

docs/contributing.md

@@ -23,7 +23,7 @@ pnpm run typecheck
 pnpm run format:check
 ```
 
-To approximate **Linux CI** from any host, use container mode (`pnpm run act:ci`) or host mode without Docker (`pnpm run act:ci:native`). See [CI/CD — Running locally with act](ci-cd.md#running-ci-locally-with-act).
+To approximate **Linux CI** from any host, use container mode (`pnpm run act:ci`) or host mode without a container engine (`pnpm run act:ci:native`). See [CI/CD — Running locally with act](ci-cd.md#running-ci-locally-with-act).
 
 ## Documentation Workflow
 

docs/development-environment.md

@@ -34,7 +34,7 @@ pnpm run dev
 
 **Required** checks (must pass): Git, Node.js, pnpm, `node_modules`, and platform-native build tools (Xcode CLT on macOS, `g++`/`make` on Linux, MSVC `cl` on Windows).
 
-**Optional** checks (warnings only): Python/pip, Rust, actionlint, yamllint, Docker, act, and Linux `dialout` group membership. For local CI you can use **container mode** (`pnpm run act:ci` — act + Docker) or **host mode** (`pnpm run act:ci:native` — no Docker). Fix optional items when you need docs builds, pre-commit hooks, Reticulum sidecar work, local CI parity, or USB serial on Linux.
+**Optional** checks (warnings only): Python/pip, Rust, actionlint, yamllint, a Docker-compatible container engine (Podman preferred), act, and Linux `dialout` group membership. For local CI you can use **container mode** (`pnpm run act:ci` — act + Podman/Docker) or **host mode** (`pnpm run act:ci:native` — no container engine). Fix optional items when you need docs builds, pre-commit hooks, Reticulum sidecar work, local CI parity, or USB serial on Linux.
 
 Use the printed `→` hints and `setup:*` scripts (`setup:build-deps`, `setup:actionlint`, `setup:dialout`) to fix failures. See [Helper scripts (auto-install where possible)](#8-helper-scripts-auto-install-where-possible) below.
 
@@ -410,21 +410,21 @@ flatpak run --command=flatpak-builder-lint org.freedesktop.Sdk \
 
 #### CI (act)
 
-| Script                   | Description                                             |
-| ------------------------ | ------------------------------------------------------- |
-| `act:ci`                 | Run Linux CI workflow via act + Docker (container mode) |
-| `act:ci:native`          | Run CI checks on the host (no Docker)                   |
-| `act:tests`              | Run tests workflow via act + Docker                     |
-| `act:tests:native`       | Run `test:coverage` on the host                         |
-| `act:pr`                 | Run `act:ci` then `act:tests` (container)               |
-| `act:pr:native`          | Run native CI + tests on the host                       |
-| `act:build:linux`        | Run `build.yaml` ubuntu leg via act + Docker            |
-| `act:build:linux:native` | Run `dist:linux` on the host                            |
-| `act:reticulum`          | Reticulum sidecar Linux jobs via act                    |
-| `act:reticulum:native`   | Reticulum sidecar stub `cargo test` / build on the host |
-| `act:flatpak`            | Flatpak x86_64 workflow via act (slow; privileged)      |
-| `act:pull-images`        | Pre-pull Docker images for act (container mode)         |
-| `act:list`               | List container and native act targets                   |
+| Script                   | Description                                                   |
+| ------------------------ | ------------------------------------------------------------- |
+| `act:ci`                 | Run Linux CI workflow via act + containers (Podman preferred) |
+| `act:ci:native`          | Run CI checks on the host (no container engine)               |
+| `act:tests`              | Run tests workflow via act + containers                       |
+| `act:tests:native`       | Run `test:coverage` on the host                               |
+| `act:pr`                 | Run `act:ci` then `act:tests` (container)                     |
+| `act:pr:native`          | Run native CI + tests on the host                             |
+| `act:build:linux`        | Run `build.yaml` ubuntu leg via act + containers              |
+| `act:build:linux:native` | Run `dist:linux` on the host                                  |
+| `act:reticulum`          | Reticulum sidecar Linux jobs via act                          |
+| `act:reticulum:native`   | Reticulum sidecar stub `cargo test` / build on the host       |
+| `act:flatpak`            | Flatpak x86_64 workflow via act (slow; privileged)            |
+| `act:pull-images`        | Pre-pull Docker images for act (container mode)               |
+| `act:list`               | List container and native act targets                         |
 
 #### Setup / helpers
 
@@ -498,7 +498,7 @@ Not installed by pnpm (install separately when needed):
 - `actionlint` (recommended for workflow linting; run `pnpm run setup:actionlint` or install system-wide)
 - `yamllint` (required for YAML linting; install via `pip install yamllint` or `brew install yamllint` on macOS)
 - **Rust / `cargo`** (optional; Reticulum sidecar — see [Reticulum sidecar](#reticulum-sidecar-optional); prefer [rustup](https://rustup.rs/)). `rust-toolchain.toml` installs clippy/rustfmt/llvm-tools-preview on first build in `reticulum-sidecar/`. Optional: `cargo install cargo-llvm-cov` for `pnpm run reticulum:sidecar:coverage`.
-- `docker` and `act` (optional for container CI — `act:*`; host CI uses `act:*:native` without Docker)
+- Podman or Docker (Docker-compatible engine) and `act` (optional for container CI — `act:*`; host CI uses `act:*:native` without a container engine)
 - Python 3 + `venv` + MkDocs Python deps (for docs checks/builds)
 
 #### Vitest projects and worker allocation
@@ -631,20 +631,20 @@ Run any skipped checks manually as soon as possible.
 
 Local CI has two modes:
 
-| Mode              | Scripts                                         | Requires       |
-| ----------------- | ----------------------------------------------- | -------------- |
-| **Container**     | `pnpm run act:ci`, `act:tests`, …               | Docker + act   |
-| **Host / native** | `pnpm run act:ci:native`, `act:tests:native`, … | Node/pnpm only |
+| Mode              | Scripts                                                  | Requires                                          |
+| ----------------- | -------------------------------------------------------- | ------------------------------------------------- |
+| **Container**     | `pnpm run act:ci`, `pnpm run act:tests`, …               | Docker-compatible engine + act (Podman preferred) |
+| **Host / native** | `pnpm run act:ci:native`, `pnpm run act:tests:native`, … | Node/pnpm only                                    |
 
-Container mode runs GitHub Actions jobs inside Docker (closest to CI). Host mode runs the same pnpm/cargo steps directly — use this when Docker Desktop is off or act cannot reach the daemon.
+Container mode runs GitHub Actions jobs inside containers using a Docker-compatible engine (Podman Desktop preferred). Host mode runs the same pnpm/cargo steps directly — use this when no container engine is available or act cannot reach the daemon.
 
 Install (container mode):
 
-| OS      | Docker                                                            | act                                                                           |
-| ------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| macOS   | [Docker Desktop](https://www.docker.com/products/docker-desktop/) | `brew install act`                                                            |
-| Linux   | Docker engine                                                     | [act releases](https://github.com/nektos/act/releases)                        |
-| Windows | Docker Desktop (WSL2 backend)                                     | `choco install act-cli` or [releases](https://github.com/nektos/act/releases) |
+| OS      | Container engine                                                       | act                                                                           |
+| ------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| macOS   | [Podman Desktop](https://podman.io/) with Docker compatibility enabled | `brew install act`                                                            |
+| Linux   | Podman or Docker engine                                                | [act releases](https://github.com/nektos/act/releases)                        |
+| Windows | [Podman Desktop](https://podman.io/) with Docker compatibility enabled | `choco install act-cli` or [releases](https://github.com/nektos/act/releases) |
 
 ```bash
 pnpm run act:pull-images # container mode only
@@ -653,7 +653,7 @@ pnpm run act:ci    # or act:ci:native
 pnpm run act:tests # or act:tests:native
 ```
 
-Docker Desktop on macOS: act auto-uses `~/.docker/run/docker.sock`. Set `ACT_DOCKER_SOCKET` if act still fails.
+On macOS, podman exposes a Docker-compatible socket at `/var/run/docker.sock`; pass that path to `act` via `ACT_DOCKER_SOCKET`, or let it auto-detect if Podman created the socket symlink. If you use Docker Desktop instead of Podman, its socket is typically under `~/.docker/run/docker.sock`.
 
 macOS and Windows **installer** builds still require native `pnpm run dist:mac` / `pnpm run dist:win`. See [ci-cd.md](ci-cd.md#running-ci-locally-with-act).
 
@@ -732,6 +732,10 @@ pnpm install
 pnpm run dev
 ```
 
+### Local CI container engine
+
+[Podman Desktop](https://podman.io/) is the preferred cross-platform Docker-compatible engine for local CI. When Docker compatibility is enabled, Podman exposes a Docker-compatible socket at `/var/run/docker.sock`; pass that path to `act` via `ACT_DOCKER_SOCKET`, or let it auto-detect if Podman Desktop created the socket symlink. If you use Docker Desktop instead, see the socket note above.
+
 ### Bluetooth permissions
 
 On first BLE connection, macOS prompts for Bluetooth access. If denied accidentally: