75 lines
4.0 KiB
Markdown
75 lines
4.0 KiB
Markdown
# 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).
|