# Repository Guidelines

## Project Structure & Module Organization
This is a chezmoi dotfiles source tree scoped to Waybar. The current directory maps to `~/.config/waybar/` on apply.
- `dot_config/waybar/` contains Waybar config, style, and module files.
- Host-specific variants use `##hostname.<name>` suffixes (e.g., `config##hostname.laptop`).

## Chezmoi Config (chezmoi.toml)
- Source of truth: `~/.config/chezmoi/chezmoi.toml` (not tracked here).
- Data model: `tags` (booleans: `laptop`, `touchscreen`, `pipewire`, `dev`, `bluetooth` — no `desktop`; use `not laptop`), `compositor` (`"hyprland"`/`"niri"` — `config.tmpl` branches the workspace module on this), `apps` (optional programs), `data.monitors` (array; each `name` + optional `primary`/`waybar` + `role`), `data.placement`, `data.microphones`.
- The waybar bar attaches to the monitor whose entry has `waybar = true` (else the `primary` monitor).
- Reference structure (current machine):
  ```toml
  [data]
  tags = { laptop = false, touchscreen = false, pipewire = true, dev = true, bluetooth = false }
  compositor = "hyprland"
  apps = ["steam", "spotify", "jellyfin"]

  # --- Primary Monitor ---
  [[data.monitors]]
  name = "DP-1"
  primary = true
  role = "primary"
  position = "1920x0"
  workspaces = [{ id = 24, name = "4" }, { id = 25, name = "5" }]

  # --- Secondary Monitor (hosts the bar) ---
  [[data.monitors]]
  name = "DP-2"
  role = "right"
  waybar = true
  position = "4480x0"
  workspaces = [{ id = 28, name = "8" }]
  ```

## Build, Test, and Development Commands
There is no build system. Use chezmoi to preview and apply changes:
- `chezmoi diff` preview pending changes.
- `chezmoi apply` render and apply files to `$HOME`.
- `chezmoi status` show managed file status.
After applying, restart Waybar to validate changes.

## Coding Style & Naming Conventions
- Match existing file formatting; avoid reflowing unrelated sections.
- Prefer ASCII unless the file already uses Unicode.
- Use chezmoi naming conventions: `dot_` for dotfiles, `executable_` for executables, `private_` for restricted files, `.tmpl` for Go templates, `symlink_` for symlinks.
- Keep module names descriptive and aligned with Waybar’s config keys.

## Testing Guidelines
No automated tests are defined. Validate by:
- Running `chezmoi diff` and `chezmoi apply`.
- Smoke-testing Waybar (reload or restart) to confirm layout and modules.

## Commit & Pull Request Guidelines
The repository has no established Git history. Use short, imperative commit subjects and include a scope when helpful (e.g., `waybar: tweak clock format`). For pull requests, include:
- A concise summary of changes.
- Affected paths (e.g., `dot_config/waybar/config`).
- Screenshots for visual/UI changes.

## Notes for Contributors
Avoid editing unrelated dotfiles unless requested. If you touch mirrored docs or host-specific files, call it out explicitly in your summary.
