Layout

Layout

The repo has no “what goes where” config. The folder is the configuration.

~/.home/
├── autolink/          linked into $HOME
│   ├── common/        every OS
│   ├── linux/         Linux only
│   └── macos/         macOS only
├── private/           linked too, committed only as *.age
│   ├── common/ linux/ macos/
│   ├── recipients.txt public key (committed)
│   └── identity.age   private key, passphrase-encrypted (committed)
├── manifests/
│   ├── profiles/      base.yml, workstation.yml
│   ├── actions/       your own profile steps (*.sh)
│   ├── common/ linux/ macos/   Brewfile, apt.txt, apt-repos/, flatpak.txt
├── furniture/         fonts/ drivers/ themes/ vaults/ vendor/
├── bin/               personal scripts (zsh-bench, ...)
├── homebot/           the tool
├── docs/              this site
├── agent/reports/     agent write-ups
├── homebot.yml        tool settings
├── decisions.yml      triage answers ("never ask about X")
└── bootstrap.sh       first run on a new machine

Layers

autolink/ and private/ each have three layers: common/, linux/,
macos/. On a given machine homebot merges common/ with the current OS
layer, and private/ with autolink/.

  • Folders merge across layers and trees: common/config/zsh and
    linux/config/zsh both feed ~/.config/zsh.
  • A file lives in exactly one place. The same file in two layers is a
    layout error, not an override.
Why no overrides?

Overrides make you diff two files in your head to know what’s live. One file,
one place: grep finds it, and the per-OS bit goes in a per-OS file
(env.d/10-linux.zsh, wezterm/platform.lua).

The other folders

Folder Rule
manifests/ Read by homebot unpack. Brewfile, apt.txt, apt-repos/, flatpak.txt are generated by homebot export; change what’s installed, don’t hand-edit. See Profiles.
furniture/ Never linked or copied unless a profile step asks (- fonts: [Family]). Files over limits.maxFileMB (50) are refused at commit.
bin/ On $PATH before everything else (set in .zshenv).
agent/ Reports from coding agents, dated YYYY-MM-DD-topic.md.

Config files

Both are .yml. A .yaml file is refused with a rename hint.

File Who writes it
homebot.yml You. See homebot.yml.
decisions.yml homebot triage (hand edits are fine). Globs work.
manifests/profiles/*.yml You.
Previous Start here Next Linking rules