docs: add CLAUDE.md

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed, 50 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d26be50
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,50 @@
+# CLAUDE.md — hyprsunset-qt
+
+PyQt6 GUI to edit `~/.config/hypr/hyprsunset.conf`, fetch sunrise/sunset times
+for the user's location, and restart the `hyprsunset` daemon.
+
+## Layout
+
+- `hyprsunset_qt/config.py` — `Profile` dataclass, parse/serialize
+  hyprsunset.conf, read/write, `day_index`/`night_index` detection, field
+  validators. Pure logic, no Qt/network.
+- `hyprsunset_qt/settings.py` — `Settings` (INI at `~/.config/hyprsunset-qt/config`).
+- `hyprsunset_qt/sun.py` — geolocate (ip-api.com), fetch_sun
+  (sunrise-sunset.org), UTC→local `HH:MM`, JSON cache read/write.
+- `hyprsunset_qt/daemon.py` — `is_running`/`restart`/`live_preview`, all
+  subprocess shell-outs (pgrep, pkill, hyprctl).
+- `hyprsunset_qt/ui.py` — `ProfileRow` + `MainWindow`. Only module importing PyQt6.
+- `hyprsunset_qt/__main__.py` — entry point (`python3 -m hyprsunset_qt`).
+- `tests/` — pytest for the pure-logic modules only.
+- `docs/superpowers/` — design spec + implementation plan.
+
+## Key facts
+
+- **Config vs settings are two files.** `hyprsunset.conf` (the daemon's, in
+  `~/.config/hypr/`) is regenerated clean on save — hand comments/whitespace
+  are lost, day/night comments emitted. App settings live separately in
+  `~/.config/hyprsunset-qt/config`.
+- **Cache in `~/.config`, not `~/.cache`** — the user's `~/.cache` is wiped at
+  reboot. Sunset JSON cache refreshes on manual Fetch only.
+- **day/night is inferred, not stored**: day = first profile with
+  `identity=true`, night = first with `temperature` set. Sunrise→day time,
+  sunset→night time.
+- **hyprsunset v0.3.3 has no config reload** — applying config = kill+relaunch
+  (`pkill hyprsunset` then launch). IPC (`hyprctl hyprsunset temperature|gamma|
+  identity`) is live-preview only; gamma float 0–2 maps to integer percent.
+- Deps: PyQt6 + stdlib only. Minimal-deps rule.
+
+## Workflow
+
+- Tests: `python3 -m pytest -q`. Qt/network/daemon layers are thin wrappers,
+  not unit-tested (mocked or manual). TDD for pure logic.
+- Commits: GPG-signed (`git commit -S`). Work on master.
+- License: GPLv2-only, per-file header present.
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.