aboutsummaryrefslogtreecommitdiff
path: root/AGENTS.md
blob: fc7e145a780978c1bf2f2e19719f27faae3f3d55 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

dotfiles — Agent Context

Personal configuration repository, deployed as GNU stow packages, public at git.pcola.moorenix.com:git-public/dotfiles.git.

Each top-level directory (except shared docs like this file) is a stow package that mirrors $HOME exactly, e.g. waybar/.config/waybar/. More specific agent context lives one level down — read this file first, then the AGENTS.md inside the package you’re working on (if it has one); machine layers describe per-machine hardware/role facts.

Deploy model

  • Deploy on a machine with GNU stow from the repo root: stow --adopt -t ~ <pkg> ... — --adopt pulls an existing target file into the package and symlinks it, converting a live config into stow-managed without a copy/symlink dance. Dry-run first with -n -v2.
  • Not every package applies to every machine. sway/, foot/, etc. are flagship packages; hypr/, fish/, rofi/, alacritty/ belong to other machines/stacks and are loaded only there.

Layout invariants

  • Always .config/<tool>/... nesting — no flat exceptions.
  • One package per tool/theme unit; don’t nest unrelated tools inside a package just because they install together.
  • Machine-specific content (display config, input quirks, machine roles, machine-hosted scripts like ppd-switch) lives inside a package’s per-machine section — see sway/AGENTS.md once sway/ is tracked — never in shared configs and never by hardcoding into a shared file.

Styling invariant

doom-one palette + Terminess Nerd Font are the system-wide look. Every machine, every tool, same palette:

bg #282c34    fg #bbc2cf    blue #51afef    magenta #c678dd
red #ff6c6b   green #98be65 yellow #ecbe7b  cyan #46d9ff
orange #da8548 violet #a9a1e1 base3 #3f444a  base5 #5b6268

If a tool’s config already carries these values, reuse rather than restate; if it needs additional theming, derive from this palette. Never fork the palette per machine — consistent feel is the whole point.

Portability

Multiple machines share this repo (Gentoo sway laptops/desktops, Hyprland machines, macOS hosts using alacritty, fish shells elsewhere). A change must not break a platform that stows the affected package. When in doubt about whether a value is “this machine” or “every machine,” the answer is: put it in the machine-specific section only if it’s about that machine’s hardware or role; otherwise it’s shared.

Git hygiene

  • This is a public repo. No secrets, ever. Before every commit: review git diff --cached for tokens, API keys, passwords, private hostnames/URLs, high-entropy strings. git diff --cached --check catches whitespace, not secrets — an actual grep review of the diff is required. If in doubt, leave it out and ask.
  • Never commit: *.bak / config.bak.* backups, editor state, session state that regenerates per machine (fish_variables), old_config/, __pycache__/. Plugin lock files (e.g. nvim’s lazy-lock.json, nvim-pack-lock.json) ARE tracked deliberately — they pin plugin versions for reproducibility.
  • git status must be clean or intentionally scoped before commit. If stray files appear, fix the scope (.gitignore or exclude) — never sweep them in, never blanket git add -A without reading what’s staged.
  • Commits: short imperative messages, matching the existing repo style. Keep diffs minimal and focused; match the comment style and formatting of the file you’re editing.

Tool expectancies

  • waybar/ and sway/ + the rigel/ machine-overlay package are live and stowed on rigel; shared-tool syncs (tmux, nvim, alacritty) are landed. Each package gets an AGENTS.md only if it has non-obvious conventions worth recording. foot/, fuzzel/, mako/, swayidle/, swaylock/, kanshi/, veila/, fontconfig/, gtk-*/, btop/ are still pending import. Machine name lists: rigel (Gentoo sway laptop), hypr, fish/, rofi/, alacritty/ for the other stacks.