alex/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align agent and repo docs with desktop Decman profile

Browse Source
This commit is contained in:
Alex
2026-08-27 15:50:30 +02:00
parent 00781a3607
commit 10c214fc36
4 changed files with 30 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+9 -6
View File
@@ -12,13 +12,16 @@ This directory (`/home/alex`) is the **yadm worktree** for personal, Arch-orient
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 |
| `.setup/` | Legacy/manual setup assets and package lists; it is not a complete installer |
| `system-config/` | Declarative Decman configuration for this Arch laptop |
| `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 |
@@ -29,7 +32,7 @@ Start with the root `README.md` for the dotfile-specific constraints and manual-
## Decman architecture
`system-config/source.py` is the Decman entrypoint. It currently selects the `laptop()` profile from `hosts.py` and applies modules in this order:
`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`
@@ -38,9 +41,9 @@ Start with the root `README.md` for the dotfile-specific constraints and manual-
`hosts.py` composes host profiles from package concerns:
- Shared concerns: `common/core`, `wayland`, `fonts`, `development`, `productivity`, `media`, `research`, `network`, and `services`.
- Laptop-specific concern: `laptop/hardware`.
- Desktop support is intentionally sparse and future-facing.
- 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:
README.md
+9 -22
View File
@@ -6,7 +6,7 @@ Personal, Arch-oriented user dotfiles and support scripts for shells, window man
There is no authoritative root installation, linking, backup, overwrite, or rollback script. Do not infer one: review and apply only the individual files appropriate to a machine. Some filenames use `##class.arch_*` suffixes to distinguish machine classes. The repository also includes a nested README for the custom/vendored `st` terminal under `.config/st/`; it documents that component, not installation of this repository.
Several scripts assume paths below `~/.setup`, Arch tooling, and root access. Some repository scripts contain machine-specific connection details; do not publish, copy, or document such values. Use local, private configuration for hosts, addresses, accounts, and credentials.
Several scripts assume Arch tooling and root access. Some repository scripts contain machine-specific connection details; do not publish, copy, or document such values. Use local, private configuration for hosts, addresses, accounts, and credentials.
## Prerequisites
@@ -15,7 +15,7 @@ Several scripts assume paths below `~/.setup`, Arch tooling, and root access. So
- Desktop/session tools matching the chosen configuration (for example X11/XMonad-related files where applicable).
- Root access only for the system-changing scripts described below.
Package lists in `.setup/packages/` are inputs for a user-managed installation; no repository command defines how to install an entire list. Inspect package names and select lists for the intended machine before installing anything.
Package and service policy lives under `system-config/` and is applied through Decman. Review `system-config/README.md`, the active host profile, and a dry run before changing system state.
## Safe review and user-level configuration
@@ -24,33 +24,20 @@ Start by reviewing the intended files and any machine-class variants. Typical ar
- `.zshrc`, `.bashrc`, `.terminal_aliases`, `.tmux.conf`, and `.p10k.zsh` — shell and terminal setup.
- `.config/` — desktop and application configuration.
- `.scripts/` — optional shell, network, virtual-environment, and update helpers.
- `.setup/packages/` — package lists grouped by purpose.
- `system-config/` — Decman-managed packages, system files, selected user configuration, and service manifests.
Back up existing configuration before manually placing or linking a file. No test suite is provided; validate a change in the relevant shell/session or application and keep a rollback copy of the previous configuration.
## Package updates
## System-changing configuration
`.scripts/updating.sh` defines, but does not invoke, two functions. It expects `~/.setup/packages/exclude_from_updating.list`:
`system-config/` is the source of truth for managed packages, system files, selected user configuration, and enabled services. Use its review-first wrapper:
```sh
source .scripts/updating.sh
update_system
# or
update_pacman_packages
```fish
./system-config/decman verify
./system-config/decman dry-run
```
> **Warning: system-wide, potentially disruptive operation.** `update_system` runs `yay -Syu` and `update_pacman_packages` runs `sudo pacman -Syu`, both non-interactively and with the exclusion list. Review the exclusion list and pending package changes first. These functions update the running system; they are not tests.
## System-changing scripts
The following scripts mutate files outside this repository and must be inspected before use:
- `.setup/config/exclude_from_update.sh` edits `/etc/pacman.conf` with `sudo` based on `~/.setup/packages/exclude_from_updating.list`.
- `.setup/config/dinit_add_logs_to_all_services.sh` edits files in `/etc/dinit.d` and writes log specifications under `/var/log/dinit`; its `-o` option removes existing logfile lines before adding them.
> **Warning: destructive/system-wide operations.** These scripts can alter system package policy, service definitions, or input configuration. They have no repository-provided dry run or rollback. Run only on a machine you control after backups and after checking paths, permissions, and the script contents.
`.setup/config/set_default_programs.sh` sets the default HTTP/HTTPS handler through `xdg-mime`; review the desktop entry before using it.
> **Warning: system-wide, potentially disruptive operation.** `./system-config/decman apply` changes packages, system files, boot artifacts, and services. Run it only after reviewing a dry run. No root-level bootstrap or rollback command exists.
## Custom `st` terminal
system-config/PACKAGE_AUDIT.md
+4 -3
View File
@@ -1,6 +1,6 @@
# Desktop Package Audit
Generated from `pacman -Qen` (official repository, explicitly installed) and `pacman -Qem` (AUR/foreign, explicitly installed). Package versions are included so this is an exact inventory.
Originally generated from `pacman -Qen` and `pacman -Qem` during desktop adoption. Versions record that snapshot; the package lists under `packages/` are authoritative for current policy.
## Decision key
@@ -119,7 +119,7 @@ Generated from `pacman -Qen` (official repository, explicitly installed) and `pa
| `vulkan-mesa-layers` | `1:26.1.5-1` | REVIEW — provisional desktop/local retention candidate |
| `vulkan-radeon` | `1:26.1.5-1` | REVIEW — provisional desktop/local retention candidate |
| `vulkan-tools` | `1.4.350.1-1` | KEEP — declared common desktop concern |
| `waybar` | `0.15.0-2` | KEEP — declared common desktop concern |
| `waybar` | `0.15.0-2` | RETIRE — replaced by Noctalia and no longer declared |
| `wdisplays` | `1.1.3-2` | REVIEW — provisional desktop/local retention candidate |
| `wget` | `1.25.0-6` | REVIEW — provisional desktop/local retention candidate |
| `wine` | `11.14-2` | REVIEW — provisional desktop/local retention candidate |
@@ -150,7 +150,7 @@ Generated from `pacman -Qen` (official repository, explicitly installed) and `pa
| `lutris-git` | `0.5.22.r394.g1b0f116-1` | REVIEW — provisional desktop/local retention candidate |
| `mongodb-compass-bin` | `1.49.11-2` | KEEP — declared common desktop concern |
| `mullvad-vpn-beta-bin` | `2026.3.stable-1` | KEEP — declared common desktop concern |
| `noctalia` | `5.0.0_beta.3-2` | REVIEW — provisional desktop/local retention candidate |
| `noctalia-git` | `5.0.0.r5317.ga4324409f-1` | KEEP — declared common Wayland concern |
| `nomacs-git` | `3.23.2.r0.gccb6ff42-1` | REVIEW — provisional desktop/local retention candidate |
| `pycharm-professional` | `2025.2.2-1` | REVIEW — provisional desktop/local retention candidate |
| `rustrover` | `2026.1.3-1` | REVIEW — provisional desktop/local retention candidate |
@@ -197,6 +197,7 @@ rustrover
ueberzug
vkd3d
vulkan-mesa-layers
waybar
wine
winetricks
xclicker
system-config/README.md
+8 -4
View File
@@ -5,7 +5,8 @@ A small, declarative Arch configuration managed by Decman.
## Design
- **Concerns live in `packages/`**: each concern has a native (`*-repo.txt`)
and AUR (`*-aur.txt`) list.
and AUR (`*-aur.txt`) list, plus an optional global npm (`*-npm.txt`) list
for command packages unavailable through Arch packaging.
- **Hosts live in `hosts.py`**: a host composes package concerns and explicit
system state. `desktop()` owns this desktop's boot, storage, NVIDIA, input,
SDDM, network-policy, and user-session configuration.
@@ -55,7 +56,9 @@ remove those explicitly in a separate reviewed package change.
| Desktop | shared concerns, `common/hardware`, and a reviewable `desktop/local` set; host state is in `config/system/desktop/` |
Every package must have a named purpose. Add a new concern when an existing one
does not explain a package. System and user units use the same naming:
does not explain a package. Missing packages from `*-npm.txt` are installed
globally after the pacman and AUR steps; unrelated global npm packages are not
removed. System and user units use the same naming:
`manifests/common/<concern>-{system,user}.txt` or
`manifests/laptop/<concern>-system.txt`.
@@ -87,8 +90,9 @@ sudo decman --source source.py --no-hooks
```
`verify.py` proves that every currently explicit package appears exactly once
in the active laptop profile. The ignored dependency lists prevent Decman's
orphan cleanup from removing dependencies during adoption.
in the active desktop profile, including global npm command packages. The
ignored dependency lists prevent Decman's orphan cleanup from removing
dependencies during adoption.
After intentional package changes, regenerate and review concern lists: