aboutsummaryrefslogtreecommitdiff
path: root/AGENTS.md
diff options
context:
space:
mode:
Diffstat (limited to 'AGENTS.md')
-rw-r--r--AGENTS.md77
1 files changed, 77 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9d13b13
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,77 @@
+# 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, lock or
+ lock-state files, `fish_variables` (per-machine session state,
+ regenerates on login), anything under `old_config/` or `__pycache__/`.
+- `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/` is the proof-of-principle package for this layout; as other
+ tools sync in, each gets its own `AGENTS.md` only if it has non-obvious
+ conventions worth recording. Tmux/nvim/alacritty are synced laptop-first
+ (laptop wins on divergence) per the conversation that created this
+ structure.