From 260b202d6f8ced1984bda5b544caf6ad61550768 Mon Sep 17 00:00:00 2001 From: Samuel O'Neal Date: Fri, 14 Aug 2026 21:35:27 -0600 Subject: [PATCH] update readme with current packages; add AGENTS.md for AI guidance --- AGENTS.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 150 insertions(+), 10 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bd06444 --- /dev/null +++ b/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 `/.config//`). 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). diff --git a/README.md b/README.md index 4299b66..2898aee 100644 --- a/README.md +++ b/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 -- 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/`).