omarchycn/plans/dots.md

# Plan: Dots — preserve and sync user configs out of the box

Revision 3. Rev 2 incorporated adversarial review by codex (xhigh) and grok;
rev 3 names the feature **dots** (`omarchy dots ...`) and adds the
multi-machine sync design.

## Problem

Omarchy declares `~/.config` "your files" but does little to preserve them:

- `omarchy-refresh-config` litters `*.bak.<timestamp>` files next to originals.
- `omarchy-reinstall-configs` clobbers everything back to `/etc/skel` defaults.
- Snapper only snapshots the `root` config; recovering one config file from a
  root snapshot is not a workflow, and `/home` may not be covered at all.
- The manual punts to a YouTube video about Stow.

There is no way to answer "what did the last update change about my configs?",
"restore my bindings from last week," or "make my new laptop feel like my
desktop."

## Rejected approaches

- **`git init ~/.config`**: dumping ground — Chromium profile, fcitx5 state,
  app tokens, machine churn. A `.git` there gets discovered by editors and
  prompts. Can't cover `~/.bashrc` or `~/.XCompose`.
- **`~/.config/omarchy` only**: too narrow; misses hypr, terminals, `.bashrc`.
- **Stow**: inverted model requiring file migration; organization, not history.
- **chezmoi / yadm**: third-party DSLs we'd be wrapping; overkill.
- **Raw git passthrough / lazygit over `$HOME`** (rejected in review):
  `git clean -fd`, `reset --hard`, or "stage all" against a `$HOME` work tree
  is a home-directory-eraser; `git add -A` can ingest `~/.ssh` and the object
  store into itself (`status.showUntrackedFiles no` only affects `status`);
  `remote add` + `push` silently defeats local-only. Experts can construct the
  raw invocation themselves; Omarchy will not bless it.
- **Distributed git across machines**: two machines auto-committing timer and
  update snapshots into a shared branch conflict constantly. History and sync
  are different products (see Sync below).

## Chosen design: bare repo over `$HOME`, driven only by constrained commands

```bash
git init --bare ~/.local/share/omarchy/dots.git   # mode 0700
```

No `.git` in any directory tools walk; files stay plain files in place. All
access goes through one internal helper that runs git **hermetically**:

- Repo-local config only: synthetic identity (`Omarchy <omarchy@localhost>`),
  `commit.gpgsign=false`, `core.hooksPath` disabled, `--no-verify`,
  `GIT_CONFIG_GLOBAL=/dev/null` so user signing/hooks/templates/excludes and a
  `$HOME/.gitignore` can never break or intercept an automatic commit.
- Never export `GIT_DIR`/`GIT_WORK_TREE` (would leak into `omarchy-plugin-*`,
  `omarchy-theme-update`, `omarchy-update-dev`, user hooks).
- Serialized via a lock; concurrent refresh/update/manual snapshots queue.
- **Best-effort everywhere**: a failed snapshot warns and continues. History
  is optional; updates are not. Never on the failure path of
  `omarchy-update`/`omarchy-migrate` (`set -e` there must not see git errors).

### Audited manifest, not a derived whitelist

Tracking is `git add -f --pathspec-from-file=<manifest>` only. The manifest is
a hand-audited file shipped with Omarchy — explicitly **not** derived from
`$OMARCHY_PATH/config` (which ships Chromium Preferences, fcitx5,
`opencode/opencode.json` where users put API keys, etc.):

- Include: `.config/hypr/*.{lua,conf}`, `.config/omarchy/shell.json`,
  `.config/omarchy/extensions/**`, `.config/omarchy/hooks/**`,
  terminal configs (alacritty/foot/ghostty/kitty), `.config/btop/btop.conf`,
  `.config/starship.toml`, `.bashrc`, `.XCompose`.
- Exclude (deliberately): `.config/omarchy/plugins/**` and
  `.config/omarchy/themes/**` (nested git clones managed by
  `omarchy-plugin-*` / `omarchy-theme-update`), backgrounds (multi-MB
  binaries), `.config/btop/themes/` (symlink into `~/.local/state`), anything
  Chromium/fcitx5/opencode/xournalpp.
- **Two tiers**: every manifest path is history-tracked, but some are marked
  `local` — machine-specific files that sync must never touch. At minimum
  `monitors.lua`; likely hardware quirks like `dell-haptic.conf`. This is the
  lightweight answer to chezmoi's hostname templates: exclude, no DSL.
- Once committed, a secret lives in the object store forever; "no remote" is
  not a secrets story. The manifest is the deny line — nothing outside it is
  ever staged, and there is no command that stages more.

### Dotfile-manager detection: stand down, don't fight

`manual/31-dotfiles.md` sends users to Stow today, and migrations deliberately
write *through* symlinks. For those users git records an unchanged symlink, so
snapshots would be silent no-ops — and `restore` could stomp a symlink with a
regular file. Therefore:

- At seed time and before each snapshot: if manifest paths are symlinks or a
  known manager (yadm, chezmoi, existing bare-repo alias, `~/.git`) is
  detected, mark the repo dormant and say so in `omarchy dots status`.
- `restore` refuses type changes (symlink↔file) and paths outside the
  manifest.
- These users keep `.bak` behavior, which genuinely works for them (copies
  content, not links).

### Snapshot points: batch boundaries, before *and* after

The unit is a labeled snapshot pair around each *batch* mutation, via an
internal `omarchy-dots-snapshot "<label>"`:

1. **`omarchy-provision-user`**: seed repo + initial commit, after `git.sh`
   and `.XCompose` are in place. Idempotent; `--force` must not re-init.
2. **`omarchy-migrate`**: before/after pair labeled with version. Covers both
   `omarchy-update` *and* the login-time migration path, and separates
   migration changes from prior user dirt — the "before" commit captures user
   edits, the "after" commit is purely what migrations did.
3. **Batch refresh commands** (`omarchy-refresh-hyprland` etc.): one pair per
   command, not one commit per `omarchy-refresh-config` call (hyprland calls
   it seven times).
4. **`omarchy-reinstall-configs`**: a "before" snapshot — honestly labeled.
   This operation replays all of `/etc/skel`; a manifest repo does **not**
   make it reversible and we don't claim it does.
5. **Timer**: an hourly-ish systemd user timer committing only if dirty, so
   hand edits are captured — without it, "restore my bindings from last week"
   fails for any edit not followed by an Omarchy operation.

`.bak` files **stay** in v1. They serve symlink users, they're documented
(manual, agent skill, `refresh-config-test.sh` asserts them), and git history
is invisible until the menu surface exists. Removal is a later, separate
decision once restore is on *Update > Config* and proven.

## Sync across machines: publish/pull of state, not history

The local snapshot history is machine-generated noise (timer commits,
before/after pairs) and stays private. Sync happens on a shared `sync` branch
in the same repo that only two operations touch:

- **`omarchy dots push`** — *squash-publishes* the current manifest state
  (minus `local`-tier files) as one commit: "Published from <hostname>". Only
  present-state files leave the machine — a token the timer captured last
  month and you since deleted is not in any published commit.
- **`omarchy dots pull [url]`** — fetches `sync`, takes a local pre-pull
  snapshot (so pull is undoable via `restore`), then applies the files.
  Never touches `local`-tier files. With a URL argument on a fresh machine,
  it configures the remote first — the second-machine straight shot is one
  command.

Conflict story stays simple because publishes are whole-state: push refuses
when the remote moved since your last pull ("pull first"); pull attempts a
per-file three-way merge and falls back to taking remote — your version is
one `omarchy dots restore` away.

Remote setup UX:

- `omarchy dots push` with no remote runs setup inline: paste a git URL, or
  create a **private** GitHub repo via `gh` when authenticated. Verify the
  repo is private; warn loudly if not.
- Manual by default. Push is an intentional "my setup is good" moment — no
  auto-push ever (publishing half-finished experiments is an anti-feature).
  Opt-in *pull on login* later for people with one canonical machine; safe
  because every pull is snapshot-guarded.
- Dormant mode (dotfile-manager users) disables sync too — they have their
  own.
- v2 candidate: `omarchy-provision-first-run` asks "Got a dots repo?" so a
  new machine is yours before first login completes. Held back from v1 —
  drags SSH/auth bootstrapping into first-run.

## User-facing surface (v1)

Constrained commands only — a new `dots` group in `GROUP_DESCRIPTIONS`,
invoked as `omarchy dots <verb>`:

- `omarchy dots snapshot [label]` — take a snapshot now
- `omarchy dots log` — history with labels
- `omarchy dots diff [ref]` — default range: the last before/after pair
- `omarchy dots restore <file> [--at <ref>]` — accepts `~/.config/...`,
  `.config/...`, or manifest-relative paths; takes a pre-restore snapshot
  first so restore is itself undoable; refuses untracked paths and type
  changes; confirms over dirty files
- `omarchy dots push` / `omarchy dots pull [url]` — sync (above)
- `omarchy dots status` — repo state, dormant/active, remote, last
  snapshot/publish

No raw git surface. No lazygit integration.

## Rollout

- New users: seeded by `omarchy-provision-user`.
- Existing users: migration inits the repo + initial commit — **skippable and
  bounded**: no-op if repo path exists, another manager is detected, or
  identity can't be synthesized; never adds beyond the manifest; never fails
  `omarchy update`.
- Docs/tests alignment: manual `31-dotfiles.md` gets the built-in story
  (honest framing: local event history + sync of published states, *not* a
  backup — the local repo dies with the disk); a `docs/dots.md` reference doc
  per the documentation layout; `default/agents/skills/omarchy/SKILL.md`
  updated; CLI routing/metadata tests extended; new tests for identity-less
  commit, batch snapshot pairing, restore round-trip, dormant-mode detection,
  push/pull round-trip against a local bare remote, `local`-tier exclusion,
  and "git failure must not fail update".

## Open questions

1. Manifest location: `default/omarchy/dots-manifest` vs alongside the
   helper; and whether users may extend it via
   `~/.config/omarchy/dots-manifest.d/`.
2. Whether `.config/omarchy/hooks/**` belongs in the manifest at all (small
   scripts, but the likeliest place for a pasted token).
3. Harden `omarchy-refresh-config` against `..` path escape (documented today
   in AGENTS.md) as part of this work or separately.
4. Timer cadence (hourly vs daily) and whether the dirty-check should debounce
   against an active editing session.
5. Whether `input.lua` is `local`-tier (keyboard layouts travel, trackpad
   quirks don't).