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); generated/bin/ currently contains non-regenerated artifacts.
• vendor/ is local third-party payload (plugins/binaries) cached on disk and git-ignored.

If you want to manage Agents / Skills / Prompts inside this repo, start from AGENTS.md (currently a placeholder).

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 inventory snapshots live under inventory/)

Clone

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

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/bin/ currently contains artifacts that are not regenerated by repo scripts.

4. vendor/ is where third-party payload lives (local cache)

   • vendor/ is ignored by git; plugins/binaries are cloned/downloaded locally.
   • vendor/bin/ is specifically for third-party binaries cached on disk.
   • init currently clones latest HEAD rather than pinned versions.
   • vendor/ should not contain personal secrets.

5. 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 (completions/functions) + non-regenerated local bins	Artifact (partially regen)
vendor/	Local third-party binaries/plugins (git-ignored cache)	Managed (local, explicit)
inventory/hosts/	Host-specific inventories / dumps (brew, apps, extensions, etc.)	Artifact (periodic refresh)
AGENTS.md	Contract for Agents / Skills / Prompts in this repo	Source
pyproject.toml, uv.lock, .python-version	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 inventories

Host snapshots live under:

inventory/hosts/<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 (currently TBD).

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