cleanup

docs/architecture.md

@@ -0,0 +1,65 @@
+# Architecture
+
+## Goal
+
+This repo should read like a steady-state machine configuration, not a diary of
+whatever was necessary to survive the first migration.
+
+The structure is intentionally split into three layers:
+
+- `modules/`: host-wide `nix-darwin` policy
+- `home/`: user-facing Home Manager config
+- `config/`: raw config payloads consumed by Home Manager
+
+## Host Layer
+
+- [modules/base.nix](/Users/rathi/Documents/GitHub/nix/modules/base.nix) owns
+  baseline Nix settings, shells, and common packages
+- [modules/packages.nix](/Users/rathi/Documents/GitHub/nix/modules/packages.nix)
+  owns the heavier developer tooling and fonts
+- [modules/homebrew.nix](/Users/rathi/Documents/GitHub/nix/modules/homebrew.nix)
+  is the explicitly narrow Brew escape hatch for GUI casks
+- [modules/macos.nix](/Users/rathi/Documents/GitHub/nix/modules/macos.nix)
+  owns system defaults and macOS-specific integration
+
+## Home Layer
+
+- each app/tool gets its own module under `home/`
+- raw config trees live under `config/` and are linked by Home Manager
+- [home/migration.nix](/Users/rathi/Documents/GitHub/nix/home/migration.nix)
+  is the only place where takeover logic for old `~/dots` symlinks lives
+
+That separation matters. Steady-state modules should describe how the machine
+works today. Migration-only ownership cleanup belongs in one place and should be
+easy to delete later.
+
+## Package Sources
+
+Default rule:
+
+- use `nixpkgs` for stable everyday tooling
+
+Exceptions:
+
+- use dedicated flake inputs for fast-moving product CLIs whose release cadence
+  matters to the machine owner
+
+Current dedicated inputs:
+
+- `googleworkspace-cli`
+- `codex`
+- `claudeCode`
+
+## Intentional Pragmatism
+
+Some pieces are still pragmatic compatibility shims rather than ideal upstream
+state:
+
+- [modules/macos.nix](/Users/rathi/Documents/GitHub/nix/modules/macos.nix)
+  carries a Karabiner launch-agent override because current nix-darwin still
+  points at the older Karabiner bundle layout
+- [home/claude.nix](/Users/rathi/Documents/GitHub/nix/home/claude.nix) manages
+  `~/.local/bin/claude` so the Nix package cleanly replaces the old manual path
+  that was already first in shell PATH
+
+Those are acceptable as long as they are explicit and documented.