README

Personal dotfiles and workstation bootstrap repo.

This repo is intentionally organized around long-term stable semantics:

• modules/ is the source of truth for curated “meta-config”, reusable configuration modules, and configs that are not naturally dotfiles.
• home/ is a Mackup-managed snapshot tree. It is the materialized output of backup/restore (i.e., copied in/out by Mackup). Treat it as “backed-up artifacts”, not the canonical authoring location.
• generated/ is disposable for items with a regeneration path (completions/functions/plugins/docs).
  • generated/plugins/ contains third-party ZSH plugins (git-ignored).
  • generated/docs/<hostname>/ stores host-specific snapshots (brew/apps/extensions).

If you want to manage Agents / Skills / Prompts inside this repo, start from AGENTS.md.

Quick start

Prerequisites

• macOS (this repo currently contains a lot of macOS app configs: Karabiner, Aerospace, Mos, etc.)
• git
• Tasks assume:
  • mise (task runner)
  • uv (for uvx mackup ...)
  • gum (confirmation prompts)
• Task-specific:
  • init: curl, jq, and op (1Password CLI) for env injection
  • backup / restore: mackup (invoked via uvx, which will install it if missing)
• Optional:
  • brew (package installation; host snapshots live under generated/docs/<hostname>/)

Clone

git clone <your-repo-url> ~/dotfiles
cd ~/dotfiles

Arch Linux note: 1Password CLI beta for openv

modules/zsh/env.zsh contains openv, which uses op environment read.

On some Arch setups:

• /usr/bin/op (stable) may be too old and not include environment commands.
• A manually downloaded beta binary in $HOME may fail desktop integration with errors like connection reset / PipeAuthError(NoCreds).

Use this setup so both app integration and environment read work:

# 1) Download beta package using stable op
mkdir -p ~/.cache/op
PATH=/usr/bin:$PATH op update --channel beta --directory ~/.cache/op

# 2) Extract
zip="$(ls -t ~/.cache/op/op_linux_*_v*.zip | head -n1)"
unzip -o "$zip" -d ~/.cache/op

# 3) Install with correct owner/group/mode (important)
# Use /usr/bin/install explicitly (don't rely on shell alias/function/path shadowing)
sudo /usr/bin/install -o root -g onepassword-cli -m 2755 ~/.cache/op/op /usr/local/bin/op

# 4) Verify
hash -r
op --version
ls -l /usr/local/bin/op
op environment read --help >/dev/null

Expected ls -l shape:

• owner/group: root onepassword-cli
• mode includes setgid: -rwxr-sr-x (2755)

Quick runtime checks:

op signin --account my.1password.com
openv-longbridge
# safer verification: print only variable names, not secret values
env | rg '^LONGPORT_' | cut -d= -f1

Run tasks (preferred)

Tasks live in .mise/tasks/*.sh.

List tasks:

mise tasks

Run a task:

mise run init
mise run restore
mise run backup
mise run sync
mise run zsh-profile

If you do not use mise, you can also run the scripts directly:

./.mise/tasks/init.sh
./.mise/tasks/restore.sh
./.mise/tasks/backup.sh
./.mise/tasks/sync.sh
./.mise/tasks/zsh-profile.sh

Notes:

• Exact behavior is defined by the scripts themselves; this README documents the intended semantics and contract.

Repository contract (the “do not drift” rules)

These are the invariants that keep the repo understandable over time:

1. Authoring happens in modules/

   • Add/edit your curated configs, templates, scripts, and “meta config” there.
   • Things in modules/ should be reviewable, stable, and portable.

2. home/ is not canonical source

   • home/ is a Mackup storage target (a snapshot tree).
   • Prefer not to hand-edit files under home/ unless you explicitly want to change what Mackup will back up/restore.

3. generated/ is safe to delete (when regeneratable)

   • Shell completions/functions belong here and are regenerated by sync.
   • generated/plugins/ contains third-party ZSH plugins (git-ignored, cloned by init).
   • generated/docs/<hostname>/ stores host-specific snapshots.

4. Secrets never enter Git

   • Use *.private.* files that are ignored, or template files like *.tpl.*.
   • Keep machine-local secrets outside the repo whenever possible.

Layout

Top-level

Path	Meaning	Lifecycle
.mise/tasks/	Bootstrap / backup / restore / sync tasks	Source (hand-edited)
modules/	Canonical meta-config modules, reusable configs, non-dotfile configs, helper scripts	Source (hand-edited)
home/	Mackup snapshot tree for dotfiles + app configs (copied by Mackup)	Artifact (managed by tools)
generated/	Generated outputs; docs/ tracked, others (bin/, completions/, functions/, plugins/) ignored	Artifact (mixed)
AGENTS.md	Contract for Agents / Skills / Prompts in this repo	Source
pyproject.toml, uv.lock	Python tooling for scripts/automation in this repo	Source

modules/

Common patterns used in this repo:

• modules/bin/ — personal CLI entrypoints / wrappers (e.g., python scripts and short commands)
• modules/zsh/ — zsh modular config fragments + templates (private env template included)
• modules/mackup/ — Mackup configuration (.mackup.cfg + per-app cfg fragments)
• modules/surfingkeys/ — browser automation config (Surfingkeys)

home/

home/ mirrors real paths under $HOME, including:

• dotfiles: .zshrc, .gitconfig, etc.
• XDG configs: .config/*
• macOS app support paths: Library/Application Support/*, Library/Preferences/*

Because this directory is meant for backup/restore materialization, it may contain:

• files created/updated by apps
• timestamps / backups (which should typically be excluded/ignored)

If you see noise such as .DS_Store or auto-backups inside home/, prefer to ignore/exclude them to keep diffs meaningful.

Workflows

1) Day-to-day edits

• Prefer editing modules/ (source)
• Apply changes to your machine via your own linking mechanism
• sync only regenerates completions/functions today
• Refresh home/ via backup task when you want to record the current machine state into the Mackup snapshot

Typical loop:

# edit source modules
$EDITOR modules/...

# apply/link to live system
mise run sync

# snapshot changes into home/ via Mackup + inventories
mise run backup

2) New machine bootstrap

Typical flow:

mise run init
mise run restore
mise run sync

Where:

• init sets up baseline tooling
• restore pulls the Mackup snapshot into the correct locations
• sync regenerates shell completions/functions (no module linking in repo)

3) Host snapshots

Host snapshots live under:

generated/docs/<hostname>/

Examples:

• brew_dump.txt, brew_installed.txt, brew_leaves.txt
• applications.txt, setapp.txt
• gh_extensions.txt

These are intentionally host-specific and are expected to change over time. They are snapshot artifacts (brew/apps/gh extensions, etc.), not canonical config.

Agents / Skills / Prompts

This repo is designed to host all agent-related assets (agents, skills, prompts, evaluation fixtures) alongside dotfiles, under clear lifecycle boundaries.

See AGENTS.md for conventions and a recommended directory layout.

License

See LICENSE.

ChangeLog

• 2026-01-02 Update README
• 2025-06-24 Updated README with latest tools, structure, and comprehensive documentation
• 2025-06-23 Complete rewrite of README with comprehensive documentation
• 2022-05-25 Update README
• 2022-03-01 Make the repo public