dotfiles/AGENTS.md

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 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).