aether: Instructions file for Claude Code

Aether — agent notes

Desktop theming app. Wails 2 (Go backend) + Svelte 5 frontend (TypeScript, Tailwind v4). Extracts color palettes from wallpapers and applies cohesive themes across a Linux desktop (Omarchy-friendly, works standalone).

Detailed project docs (outside the repo)

Architecture decisions, design rationale, flow diagrams, ADRs, feature specs, and historical context live at:

~/Documents/bjarne/projects/Aether

Read that folder before making non-trivial changes or when the user asks "how does X work". Write new detailed docs there — the repo's docs/ folder is reserved for user-facing documentation (CLI, installation, custom apps, templates). Content in ~/Documents/bjarne/projects/Aether is deliberately outside git.

See the aether-docs skill (.claude/skills/aether-docs/SKILL.md) for the full convention.

Commands

From repo root (requires Go + wails CLI + Node):

• make dev — live-reload dev build
• make build — production build (build/bin/aether)
• make test — go test ./internal/... ./cli/...
• make install — system install (Linux: copies to /usr/bin/; macOS: /Applications/)

Inside frontend/:

• npm run check — svelte-check type-checking (run before committing frontend code)
• npm test — Vitest/jsdom regression tests with mocked Wails calls
• npm run dev — Vite dev server (usually invoked by wails dev)

Pre-commit hook runs prettier on changed JS/TS/Svelte files and gofmt on Go. Don't bypass it.

Layout

app.go                  # Wails app struct; ALL exported methods auto-bound to frontend
main.go                 # entry point
internal/
├── extraction/         # palette extraction (OKLab median-cut)
├── theme/              # theme state, applier, format classifier (IsImageFile)
├── wallpaper/          # file scanning, image thumbnails
├── blueprint/          # saved theme snapshots
├── color/              # color math (RGB/OKLab/HSL/Adjustments)
├── template/           # per-app template engine
├── wallhaven/          # wallhaven.cc API client
├── batch/              # batch palette generation
├── favorites/, omarchy/, platform/
frontend/
├── src/
│   ├── App.svelte              # top-level router
│   ├── app.css                 # Tailwind + theme tokens (light-mode class flips them)
│   ├── lib/
│   │   ├── components/         # UI (editor/, sidebar/, color-picker/, blueprints/, wallhaven/, ...)
│   │   ├── stores/*.svelte.ts  # reactive state (Svelte 5 runes, .svelte.ts extension required)
│   │   ├── utils/              # color.ts, canvas-filters.ts, keyboard.ts, debounce.ts
│   │   ├── constants/colors.ts # ANSI / extended color labels
│   │   └── types/theme.ts      # shared TS types + DEFAULT_PALETTE / DEFAULT_ADJUSTMENTS
└── wailsjs/go/         # generated bindings — DO NOT HAND-EDIT EXCEPT AS LAST RESORT