100 lines
4.9 KiB
Markdown
100 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
./scripts/verify.py
|
|
```
|
|
|
|
3. After an intentional package-list change, regenerate and review the derived lists before applying:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
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.
|