dotfiles/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This is a chezmoi dotfiles source tree. Key paths:

• dot_config/ maps to ~/.config/ (e.g., dot_config/hypr/, dot_config/nvim/, dot_config/waybar/).
• dot_local/ maps to ~/.local/ (app data, scripts, etc.).
• dot_profile.tmpl renders to ~/.profile.
• .chezmoiscripts/ contains chezmoi hooks (e.g., run_onchange_* scripts).
• Host-specific variants use ##hostname.<name> (e.g., hyprpaper.conf##hostname.owlenlap01).

Documentation

• Docs live under dot_local/share/docs/ as git submodules and use the external_ attribute so chezmoi does not interpret their contents.
• dot_local/share/docs/external_chezmoi-docs (sparse checkout assets/chezmoi.io) renders to ~/.local/share/docs/chezmoi-docs.
• dot_local/share/docs/external_hyprland.wiki (sparse checkout content) renders to ~/.local/share/docs/hyprland.wiki.
• dot_local/share/docs/external_waybar.wiki renders to ~/.local/share/docs/waybar.wiki.
• Waybar manual pages are not stored in the repo; use man 5 waybar and man 5 waybar-<module> for module docs.
• Ghostty docs are available locally at /usr/share/ghostty.

Chezmoi Config (chezmoi.toml)

• Source of truth: ~/.config/chezmoi/chezmoi.toml (not tracked here).
• The data model splits machine traits from structured config:
  • tags — booleans only: laptop, touchscreen, pipewire, dev, bluetooth. No desktop tag; use not (index $tags "laptop").
  • compositor — "hyprland" | "niri"; branch with eq …data.compositor "hyprland".
  • apps — optional programs present, e.g. ["steam","spotify","jellyfin"]; gate with has "steam" …data.apps.
  • data.monitors — array (varies per machine); each has name, optional primary, and a role ("primary"/"left"/"right").
  • data.placement — app-home workspaces keyed by monitor role (resolves per machine, falls back to primary). See dot_config/hypr/hyprland.d.lua/{workspaces,rules}.lua.tmpl.
  • data.microphones — array, meaningful only when pipewire = true.
• Reference structure (current machine):

  [data]
  tags = { laptop = false, touchscreen = false, pipewire = true, dev = true, bluetooth = false }
  compositor = "hyprland"
  apps = ["steam", "spotify", "jellyfin"]
  
  [[data.placement]]
  id = 4; name = "joplin"; role = "left"; apps = ["joplin-app-desktop"]; silent = true
  [[data.placement]]
  id = 5; name = "steam";  role = "left"; apps = ["steam"]; silent = true; layout = "scrolling"; requires = "steam"
  
  # --- Primary Monitor ---
  [[data.monitors]]
  name = "DP-1"
  primary = true
  role = "primary"
  width = 2560
  height = 1440
  position = "1920x0"
  workspaces = [{ id = 24, name = "4" }, { id = 25, name = "5" }]
  
  # --- Secondary Monitor ---
  [[data.monitors]]
  name = "DP-2"
  role = "right"
  position = "4480x0"
  workspaces = [{ id = 28, name = "8" }, { id = 29, name = "9", layout = "scrolling" }]
  

Build, Test, and Development Commands

There is no build system; apply and verify changes with chezmoi:

• chezmoi diff preview pending changes.
• chezmoi apply render and apply to $HOME.
• chezmoi status show managed file status. After applying, restart the affected app (e.g., reload Hyprland/Waybar) to validate.

Coding Style & Naming Conventions

• Match the existing file’s formatting; don’t reflow unrelated sections.
• Lua configs in dot_config/nvim/ use 2‑space indents and include dot_config/nvim/dot_stylua.toml and dot_config/nvim/selene.toml for format/lint settings.
• Use chezmoi prefixes: dot_ for dotfiles, executable_ for executable files, symlink_ for symlinks, private_ for restricted‑permission files, and .tmpl for Go templates.

Testing Guidelines

No automated tests are defined. Validate by:

• Running chezmoi diff and chezmoi apply.
• Smoke‑testing the specific tool you changed (e.g., open Neovim, restart Waybar, reload Hyprland).

Commit & Pull Request Guidelines

This repository has no commits yet, so there is no established commit message convention. Use short, imperative subjects and include a scope when helpful (e.g., hypr: adjust keybinds). For PRs, include a clear summary, affected paths, and screenshots for visual/UI changes.