Agent Guide: Alex's Dotfiles

Repository and safety model

This directory (/home/alex) is the yadm worktree for personal, Arch-oriented dotfiles. Use yadm (rather than assuming a conventional clone) for status, diff, and tracked-file operations.

This is machine-specific configuration, not a bootstrap installer. There is no authoritative root install, link, overwrite, backup, or rollback command.
Preserve ##class.* filename variants; they are yadm alternatives for machine classes.
Do not expose, copy, or add private hostnames, IP addresses, account names, tokens, or credentials. Keep machine-specific secrets in local/private configuration.
Scope changes narrowly. Do not reformat unrelated dotfiles or overwrite existing user changes.
Treat scripts that use sudo, modify /etc, install packages, rebuild boot artifacts, or alter services as potentially disruptive. Inspect them first; do not run them merely to validate an edit.

Start with the root README.md for the dotfile-specific constraints and manual-validation guidance.

Shell

Treat Fish (fish) as the default interactive shell. Write user-facing shell commands using Fish-compatible syntax unless another shell is explicitly requested or required.

Ownership map

Path	Owns
Root dotfiles (`.zshrc`, `.config/`, `.scripts/`, etc.)	Ordinary yadm-managed user configuration and helpers
`system-config/`	Declarative Decman configuration for this Arch desktop
`system-config/config/system/`	Files deployed into system locations; do not edit deployed `/etc` targets
`system-config/config/user/`	Selected user dotfiles deployed by Decman; do not edit deployed copies
`system-config/packages/`	Native and AUR package lists organized by concern
`system-config/manifests/`	Enabled system and user unit manifests
`system-config/modules/`	Thin Decman deployment/loading adapters only

system-config/ belongs to this yadm worktree; it is not a nested Git repository.

Decman architecture

system-config/source.py is the Decman entrypoint. It currently selects the desktop() profile from hosts.py and applies modules in this order:

files
pacman
aur
systemd

hosts.py composes host profiles from package concerns:

Shared concerns: common/core, common/hardware, common/wayland, common/fonts, common/development, common/productivity, common/media, common/research, common/network, and common/services.
Host-specific concerns: laptop/hardware and desktop/local.
The active desktop profile combines the shared concerns, desktop/local, and desktop system/user configuration.

Keep policy in the declared data directories, not in Python glue:

Add a package to the narrowest explanatory packages/<scope>/<concern>-repo.txt or -aur.txt file. A package must be owned exactly once.
Put shared versus host-specific system policy in config/system/common/ or the applicable host directory.
Put selected user configuration in config/user/{common,laptop,desktop}/.
Put service enablement in matching manifests/{common,laptop,desktop}/ concern files.
Keep modules/ reusable and thin; it adapts package lists, file trees, and manifests to Decman.

The ignored dependency lists are adoption guards that prevent Decman orphan cleanup from removing dependencies. Do not delete or regenerate them casually.

Change and validation workflow

For any change, first identify the owning layer above. For Decman changes:

Edit the source in system-config/, never the generated/deployed target.
Run the read-only consistency check from that directory:
```
./scripts/verify.py
```

After an intentional package-list change, regenerate and review the derived lists before applying:

./scripts/split_packages.py
./scripts/refresh_orphan_guards.py
./scripts/verify.py
yadm diff -- system-config

Require explicit human approval before applying system state. The review-first commands are:
```
sudo decman --source source.py --dry-run --no-hooks
sudo decman --source source.py --no-hooks
```
The second command mutates system files, packages, and services; do not run it as routine validation.

For ordinary dotfiles, use the smallest relevant validation: shell syntax/source checks for shell files, application/session testing for desktop configuration, or an explicit manual review. Preserve a rollback path when changing active configuration.

Before finishing

Review with yadm diff --check and yadm diff.
Confirm that unrelated working-tree changes were not modified.
State which validation was run and which system-changing operations were intentionally not run.

4.7 KiB Raw Blame History