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

2026-08-14 21:35:27 -06:00
parent 804ec54090
commit 260b202d6f
2 changed files with 150 additions and 10 deletions
@@ -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
- Hyprland
- Local
- Monique
- NVIM
- SSH
- SystemD
- ZSH
+- [GNU stow](https://www.gnu.org/software/stow/)
+- `make`
+- [op (1Password CLI)](https://developer.1password.com/docs/cli/) for anything
+  that needs a secret
+
+## Quick start
+
+```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/`).