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