---
name: command-center-dotfiles-import
description: "Runbook for deploying the command-center repo (dotfiles env layer + OMP harness) to fleet machines via full-replica rsync and deploy.sh, including override-package mechanics and ssh/sshpass transport gotchas; executed end-to-end on blankpad 2026-09-09."
---

# Command-center fleet deployment (repo = deployment)

Repo `~/.omp` is itself the deployment: packages are home-relative trees under `dotfiles/<pkg>/`; `scripts/deploy.sh` symlinks live files into the repo checkout. `git pull` + `deploy.sh` is the whole propagation story.

## Transport decision (agreed with Frank, executed 2026-09-09)
- Ship via **full-replica rsync of `/home/dank/.omp/` including `.git`** to `<user>@<host>:/home/<user>/.omp/`, NOT clone-from-Gitea — `main` can be ahead of `origin/main`; push is a user-only trigger, so clone would ship stale state.
- Deploy runs on-target as the target user: `bash /home/<user>/.omp/scripts/deploy.sh` (resolves repo via `git -C $(dirname $(realpath $0)) rev-parse --show-toplevel`, so `.git` must be present at target path — full-replica transport guarantees this).

## Pre-overwrite audit (MANDATORY before first sync on a non-blank host)
Diff every file that `deploy.sh --check` reports as DRIFT against the repo copy BEFORE letting quarantine-and-replace run. Host-specific divergence belongs in an override package, not in quarantine:
1. Pull divergent live files from target (`ssh ... 'cat <path>' > local-staged-copy`).
2. Secret-audit staged copies (grep token/secret/password/key shapes) before anything enters git.
3. Compose `dotfiles/zz-<hostname>/` on the source machine from those live copies; commit to repo first.
4. Ship package dir via rsync, then run deploy sync — override deploys LAST and wins over base packages.

## deploy.sh mechanics (verified on blankpad)
- `--check` = pure report (ADOPT/LINK/DRIFT lines), writes nothing. Run it first, always.
- Default mode = sync: adopt identicals silently, link new, quarantine-and-replace divergents into `.quarantine/<host>/<ts>/` (gitignored; never rm).
- **Override-target bug (fixed cc2c652):** `zz-<host>` packages nest base-package dirs internally (`zz-blankpad/niri/.config/...`); target derivation must strip the nested package segment, else overrides deploy to phantom `$HOME/niri/.config/...` while real targets keep pointing at canonical copies (visible symptom: check shows 0 actions but `readlink ~/.zshrc` points at base `zsh/.zshrc`).
- systemd units auto-enable only when ExecStart binary resolves on that host; dconf package loads via `dconf load /`, never symlinks.
- `core.hooksPath=.githooks` is armed by deploy.sh per machine — set it once post-transfer even before first sync.

## ssh/sshpass transport gotchas (bit us live)
- Resolve target via mDNS FQDN (`avahi-resolve -4 -n <host>.local`); bare hostname may not resolve. Drop-not-refuse on port 22 = sshd down or firewall default-drop, not auth failure — needs local/console fix on target.
- `SSHPASS='...' sshpass -e ssh ...` inline per invocation; env passed via tool `env` param did not propagate to the sshpass child process.
- Remote login shell may be **fish**: never send bash syntax (`for/do/done`, `$?`) bare through `ssh host 'cmd'`; wrap as `bash /path/script.sh` or `bash -c "..."`.
- File shipping: `ssh 'cat > /remote/path' < localfile` (stdin redirect). A here-doc attached to the ssh command is consumed by `cat` — the intended script body becomes the file content, silently. Verify shipped bytes with md5sum compare on both ends; do NOT compare `/dev/stdin` after `cat` drained it (false DIVERGED).

## Verification of a completed deploy
Re-run `deploy.sh --check` → expect exactly zero actions/quarantined/skipped = idempotent steady state. Spot-check `readlink` on override files points into `dotfiles/zz-<host>/`, not base packages.