dotfiles/AGENTS.md

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.

Knowledge base

• The knowledge base is an Obsidian vault at ~/cloud/knowledge.
• Search the vault when a task depends on specific existing knowledge.
• Add new knowledge to the vault when it is durable and noteworthy; skip routine or transient details.

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:

1. files
2. pacman
3. aur
4. 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:

1. Edit the source in system-config/, never the generated/deployed target.

2. Run the read-only consistency check from that directory:

   ./scripts/verify.py
   

3. 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
   

4. 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.