# CLAUDE.md

## Purpose

This repository defines a complete Wayland desktop environment built around **Niri**, with a focus on:

* Simplicity
* Reproducibility
* Fast startup
* Low cognitive overhead
* Clean separation of concerns

Claude should act as a **systems engineer**, not just a script generator.

---

## Core Principles

### 1. Single Source of Truth

* All configuration lives in `~/.config` via symlinks
* No duplication across tools
* Shared values (theme, fonts, gaps, etc.) should be centralized

### 2. Idempotent Setup

* `install.sh` must be safe to re-run
* No destructive operations without explicit flags
* Detect and skip existing correct state

### 3. Composability

* Each tool (waybar, mako, wofi, etc.) is independent
* No hidden coupling unless explicitly documented

### 4. Declarative > Imperative

* Prefer static config over runtime scripts
* Avoid background daemons unless required

---

## Expected Claude Behavior

When modifying this repo, Claude should:

### Configuration Changes

* Keep configs minimal and readable
* Avoid introducing magic or implicit behavior
* Prefer explicit keybindings and comments

### Adding Features

* Justify *why* the feature exists
* Ensure it fits Wayland + Niri workflow
* Avoid X11 dependencies unless unavoidable

### Refactoring

* Reduce duplication across configs
* Extract shared values (colors, fonts, spacing)
* Keep file structure intuitive

---

## Directory Expectations

```
dotfiles/
├── config/
│   ├── niri/
│   ├── waybar/
│   ├── alacritty/
│   ├── fish/
│   ├── starship/
│   ├── wofi/
│   ├── mako/
│   ├── gtklock/
│   └── ...
├── install.sh
├── packages.txt
└── README.md
```

---

## Tooling Rules

### Niri

* All keybindings must be defined here
* Window rules must be deterministic
* Avoid runtime scripting where possible

### Waybar

* Keep modules minimal
* Prefer JSON config over scripts
* Avoid polling when event-based is possible

### Fish + Starship

* Fast startup is critical
* No blocking operations
* Avoid heavy plugins

### Wofi

* Keep styling consistent with GTK theme
* Avoid unnecessary wrappers

### Mako

* Notifications should be minimal and non-intrusive
* Timeout defaults should be short

---

## Theming

Theme: **Tomorrow Night**

Ensure consistency across:

* GTK (Materia-dark)
* Icons (Papirus)
* Terminal (Alacritty)
* Waybar
* Wofi

Claude should:

* Reuse the same color palette everywhere
* Avoid hardcoding colors in multiple places

---

## Install Script Expectations

`install.sh` must:

1. Symlink configs into `~/.config`
2. Install packages from `packages.txt`
3. Detect distro (Arch-based assumed unless specified)
4. Fail fast on errors
5. Print clear status messages

---

## Anti-Patterns (DO NOT DO)

* ❌ Duplicate configs across tools
* ❌ Add large frameworks or dependencies
* ❌ Introduce race conditions in startup
* ❌ Use sleep-based timing hacks
* ❌ Hardcode machine-specific paths

---

## Safe Enhancements

Claude may suggest:

* Shared theme variables
* Config generation (if simple and transparent)
* Modular config structure
* Performance improvements (startup, memory)

---

## Testing Expectations

After changes:

* Niri starts without errors
* Waybar loads correctly
* No missing fonts/icons
* No broken keybindings
* No noticeable startup delay

---

## Output Style

When generating code:

* Provide complete files (not fragments)
* Keep formatting clean
* Avoid unnecessary comments
* Prefer clarity over cleverness

---

## Summary

This is a **minimal, fast, reproducible Wayland environment**.

Claude’s role is to:

* Maintain clarity
* Prevent bloat
* Improve consistency
* Keep everything predictable