update readme with current packages; add AGENTS.md for AI guidance

AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md
+
+Guidance for AI agents (and humans) working on this repo. This file documents
+how AI assistance has been used on this project and the expectations for future
+sessions.
+
+## What this repo is
+
+A set of GNU-stow packages containing the user's machine configuration
+(Hyprland desktop, terminal, shell, systemd units, scripts, wallpapers). Each
+top-level directory is a stow package rooted at `$HOME` (or `/` for system
+dirs like `etc`). See `README.md` for the full package table and quick start.
+
+## How AI has been used here
+
+All prior work is captured in session transcripts under
+`resources/ai/sessions/`. The main efforts so far:
+
+- **Hyprland migration to Lua** (`session-ses_ffd7.md`): converted the
+  hyprlang `.conf` configs to Lua configs for Hyprland 0.56.2, migrated
+  plugins and themes (Catppuccin Mocha palette lives in `hyprmocha/`).
+- **uwsm/sddm sign-in debugging** (`session-ses_ffd3.md`): diagnosed why the
+  uwsm Hyprland session would not allow sign-in; added a `sudo-askpass.sh`
+  (zenity prompt via `SUDO_ASKPASS`) and disabled linger.
+- **Performance work** (`session-ses_ffcb.md`): profiled Hyprland CPU usage,
+  identified the animated `borderangle` loop as the culprit; added mako
+  notifications and waybar modules.
+- **Monitor management** (`session-ses_ffc9.md`): adopted
+  [monique](https://github.com/notwidow/monique) for arranging multiple
+  monitors, including clamshell mode and the `hypr-lid-power` service
+  (`hyprland/.config/systemd/user/hypr-lid-power.service`).
+- **Cloudflare tunnel + secrets** (`session-ses_0098.md`): wired the
+  `cloudflared-k8s` service to pull the Cloudflare Access service token from
+  the Homelab 1Password vault at runtime via `op run` — it is never written to
+  disk.
+
+## Rules for agents
+
+1. **Never commit secrets.** No API keys, tokens, passwords, or private keys
+   may be committed. Use 1Password references (`op://Vault/Item/...`) and
+   inject at runtime with `op run -- ...`. `.secrets.baseline` + `detect-secrets`
+   (via pre-commit) is the guardrail; keep it updated (`detect-secrets scan`
+   and re-baseline if a benign false positive is added).
+2. **Fit every change into the stow layout.** Config files must live under a
+   package directory mirroring their destination (e.g. a new app config goes
+   under `<pkg>/.config/<app>/`). After changes, the package must be
+   committable and stowable (`make link` / `make unlink` must keep working).
+3. **`resources/` is untracked and must stay untracked.** Session transcripts
+   under `resources/ai/sessions/` can contain sensitive values (e.g. a
+   Cloudflare client secret shown during a session). Do not stage, add, or
+   commit anything under `resources/`. Note `wluma/` is likewise local-only.
+4. **Hyprland config is Lua, not hyprlang.** All `hyprland/.config/hypr/`
+   configs are `.lua` files driven by `hyprland.lua`. Do not reintroduce
+   `.conf`/hyprlang syntax.
+5. **`nvim/` is a private submodule** pointing at a self-hosted Gitea/GitLab
+   repo; never replace it with a public fork and don't commit submodule state
+   changes unless intended. Pull with `make pull-updates`.
+6. **Behave like the user's own assistant on this machine.** These dotfiles
+   reference real hosts (`sams_laptop`, `k8s.samoneal.io`, `git-ssh.samoneal.io`)
+   and real 1Password vaults — work with them, but keep the repo portable by
+   leaving secrets and machine-specific absolute paths in comments rather than
+   committed values where practical.
+7. **Verify before finishing.** Run `git status`/`git diff` to confirm only
+   intended files changed and nothing sensitive is staged. If unsure whether a
+   value is a secret, treat it as one.
+
+## Workflow
+
+- Pre-commit hooks: `pre-commit install` (runs trailing-whitespace +
+  detect-secrets).
+- Lint/typecheck: this repo is plain config + shell; shell scripts should stay
+  `sh`/`bash`-compatible and pass `shellcheck` if available.
+- Record substantial AI sessions: if a session materially changes this repo,
+  save the transcript under `resources/ai/sessions/` (keep it untracked).

README.md

@@ -1,14 +1,80 @@
 # Dotfiles
 
-All the configuration files for my current machine setup.
+All the configuration files for my current machine setup. Managed with GNU
+stow so every package maps directly onto the relevant `~/.config`, `~/.local`,
+`/etc`, etc. paths.
 
-## Configurations
+## Requirements
 
-- Ghostty
+- [GNU stow](https://www.gnu.org/software/stow/)
-- Hyprland
+- `make`
-- Local
+- [op (1Password CLI)](https://developer.1password.com/docs/cli/) for anything
-- Monique
+  that needs a secret
-- NVIM
+
-- SSH
+## Quick start
-- SystemD
+
-- ZSH
+```sh
+# Install stow if missing (auto-detects Arch/Debian/macOS)
+make check-stow
+
+# Link every package into $HOME (system dirs like /etc are stowed with sudo)
+make link
+
+# Unlink everything again
+make unlink
+
+# Pull main plus submodules
+make pull-updates
+```
+
+## Packages
+
+| Package     | Path           | Description                                             |
+| ----------- | -------------- | ------------------------------------------------------- |
+| `backgrounds` | `~/.config/backgrounds` | Wallpaper collection (incl. Dynamic-Wallpapers) |
+| `ghostty`   | `~/.config/ghostty`    | Ghostty terminal config                            |
+| `hosts`     | `~/.config/hosts`      | Custom `HOSTALIASES` file (`HOSTALIASES=~/.config/hosts`) |
+| `hyprland`  | `~/.config/hypr`, `~/.local/bin` | Hyprland config (Lua), scripts, `hypr-lid-power` service |
+| `hyprlock`  | `~/.config/hypr`       | Lockscreen config                                  |
+| `hyprmocha` | `~/.config/hypr`       | Catppuccin Mocha palette as Lua                    |
+| `hyprpaper` | `~/.config/hypr`       | Wallpaper daemon config                            |
+| `hyprshell` | `~/.config/hyprshell`  | Launcher/overview (Rust, RON config + CSS)         |
+| `local`     | `~/.local/bin`         | Local scripts (e.g. `fetch-nas-credentials.sh`)    |
+| `mako`      | `~/.config/mako`       | Notifications                                      |
+| `monique`   | `~/.config/monique`    | Monitor/clamshell arrangement                      |
+| `nvim`      | `~/.config/nvim`       | Git submodule (private repo)                       |
+| `rofi`      | `~/.config/rofi`       | Launcher (Catppuccin Mocha)                        |
+| `ssh`       | `~/.ssh/config`        | SSH config (1Password agent + cloudflared proxy)   |
+| `sunsetr`   | `~/.config/sunsetr`    | Screen color temperature (`geo.toml` is gitignored) |
+| `systemd`   | `~/.config/systemd/user`, `/etc/systemd` | User + system units (cloudflared, rclone/GDrive, NAS mounts, 1Password sign-in) |
+| `waybar`    | `~/.config/waybar`     | Top bar                                            |
+| `wofi`      | `~/.config/wofi`       | App menu                                           |
+| `yay`       | `~/.config/yay`        | AUR helper config                                  |
+| `zsh`       | `~/.zshrc`             | Zsh config                                         |
+
+`wluma/` and `resources/` exist locally but are **not** committed (see
+`AGENTS.md`).
+
+## Secrets management
+
+No secrets are committed to this repo. Anything secret goes through
+[1Password](https://1password.com):
+
+- References look like `op://Vault/Item/field[/section]` (e.g. the Cloudflare
+  service token in `systemd/.config/systemd/user/cloudflared-k8s.service`).
+- Services inject secrets at runtime with `op run -- ...`, so values never hit
+  disk or git.
+- `fetch-nas-credentials.sh` writes fetched NAS credentials to
+  `~/.nas/.smbcredentials` (chmod 600) at boot.
+- `detect-secrets` runs via `pre-commit` against `.secrets.baseline`.
+
+## Submodules
+
+- `nvim/.config/nvim` → `git@git-ssh.samoneal.io:2222/sam_oneal/nvim-config.git`
+  (private). Pull with `make pull-updates`.
+
+## AI assistance
+
+This repo is developed with AI assistance. See `AGENTS.md` for how AI has been
+used, the conventions it must follow, and where session transcripts are kept
+(`resources/ai/sessions/`).