docs: align agent and repo docs with desktop Decman profile

AGENTS.md

@@ -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 desktop |
-| `system-config/` | Declarative Decman configuration for this Arch laptop |
 | `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`.
+- Shared concerns: `common/core`, `common/hardware`, `common/wayland`, `common/fonts`, `common/development`, `common/productivity`, `common/media`, `common/research`, `common/network`, and `common/services`.
-- Laptop-specific concern: `laptop/hardware`.
+- Host-specific concerns: `laptop/hardware` and `desktop/local`.
-- Desktop support is intentionally sparse and future-facing.
+- 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

@@ -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
+```fish
-source .scripts/updating.sh
+./system-config/decman verify
-update_system
+./system-config/decman dry-run
-# or
-update_pacman_packages
 ```
 
-> **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.
+> **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.
-
-## 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.
 
 ## Custom `st` terminal
 

system-config/PACKAGE_AUDIT.md

@@ -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

@@ -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
+in the active desktop profile, including global npm command packages. The
-orphan cleanup from removing dependencies during adoption.
+ignored dependency lists prevent Decman's orphan cleanup from removing
+dependencies during adoption.
 
 After intentional package changes, regenerate and review concern lists: