diff --git a/CLAUDE.md b/CLAUDE.md
index 2331e59..3b7eb87 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,9 +5,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Build Commands
 
 ```bash
-# Rebuild and switch to new configuration
+# Rebuild and switch to new configuration (desktop x86_64)
 sudo nixos-rebuild switch --flake ~/.config/nixos/#hakase
 
+# Rebuild MacBook configuration (aarch64)
+sudo nixos-rebuild switch --flake ~/.config/nixos/#macbook
+
+# Dry-run build to check for errors without applying
+sudo nixos-rebuild build --flake ~/.config/nixos/#hakase
+
 # Manage SOPS secrets
 nix-shell -p sops --run "sops secrets/secrets.yaml"
 nix-shell -p sops --run "sops updatekeys secrets/secrets.yaml"
@@ -15,65 +21,100 @@ nix-shell -p sops --run "sops updatekeys secrets/secrets.yaml"
 
 ## Architecture Overview
 
-This is a modular, flake-based NixOS configuration for a single host (`hakase`).
+This is a modular, flake-based NixOS configuration supporting two hosts: `hakase` (x86_64 desktop) and `macbook` (aarch64 Apple Silicon).
 
 ### Key Entry Points
 
-- `flake.nix` - Declares inputs and creates NixOS configuration
-- `config.nix` - Central configuration values (username, hostname, paths, theme settings, bookmarks)
-- `hosts/hakase/configuration.nix` - Host-level entry point that imports system modules
+- `flake.nix` - Declares inputs and creates both NixOS configurations (hakase, macbook)
+- `config.nix` - Central configuration values separated by host (hakase, macbook keys)
+- `hosts/{hakase,macbook}/configuration.nix` - Host-level entry points importing system modules
+- `home/hakase.nix` - Home Manager entry point for user environment (referenced from flake)
 
 ### Module Organization
 
-**Two-tier module system:**
-- `modules/nixos/` - NixOS system-level modules (boot, kernel, services, hardware)
-- `modules/home/` - Home Manager user-level modules (imported via `home/hakase.nix`)
+**Three-tier system:**
+1. **System modules** (`modules/nixos/`) - NixOS-level settings (boot, kernel, services, hardware)
+2. **Home Manager modules** (`modules/home/`) - User-level environment and applications
+3. **Application configs** (`apps/`) - Per-application configuration directories with `default.nix` files
 
-**Application configs:** Each application has its own directory in `apps/` with a `default.nix` and optional sub-modules (e.g., `apps/hyprland/hypr/*.nix` for Hyprland settings).
+Examples:
+- `apps/hyprland/default.nix` + `apps/hyprland/hypr/*.nix` - Hyprland compositor config
+- `apps/firefox/default.nix` - Browser with bookmarks and theming
+- `apps/ghostty/default.nix` - Terminal emulator
+- `apps/neovim/default.nix` - Editor (via nixovim external flake)
 
 ### Configuration Flow
 
 ```
-flake.nix
-  └─ nixosConfigurations.hakase
-       ├─ hosts/hakase/configuration.nix
-       │   └─ modules/nixos/default.nix (imports all system modules)
-       └─ home-manager
-           └─ home/hakase.nix
-               └─ modules/home/* → apps/*
+flake.nix (outputs)
+  ├─ hakase (x86_64-linux)
+  │   ├─ hosts/hakase/configuration.nix
+  │   │   └─ modules/nixos/default.nix (imports system modules)
+  │   └─ home-manager
+  │       └─ home/hakase.nix
+  │           └─ modules/home/* (imports Home Manager modules)
+  │               └─ apps/* (application configurations)
+  │
+  └─ macbook (aarch64-linux)
+      ├─ hosts/macbook/configuration.nix
+      │   └─ modules/nixos/default.nix
+      └─ Similar home-manager structure
+
+config.nix provides myConfig via specialArgs to both configurations
 ```
 
+### Configuration Structure (config.nix)
+
+The `config.nix` file defines host-specific configuration under `hakase` and `macbook` keys. Common values include:
+
+```nix
+myConfig = {
+  nixos = { username, hostname, timezone }
+  git = { username, email, defaultBranch }
+  theme = { mode }  # "dark" or "light"
+  terminal = { default, font, aliases }
+  font = { monospace, monospaceScript, sans }
+  hyprland = { monitors, wallpaper, kb_options }
+  firefox = { bookmarks, newtabpage }
+  # ... more app-specific configs
+}
+```
+
+To add a host-specific override, define it in the host's `myConfig` section in `config.nix`. The flake passes `allConfig.{hostname}` as specialArgs, so modules access the correct host configuration.
+
 ### Module Pattern
 
-Modules receive these parameters:
+Modules receive standard NixOS parameters plus custom ones:
 ```nix
-{ pkgs, config, myConfig, inputs, ... }:
+{ pkgs, config, lib, myConfig, inputs, system, ... }:
 ```
 
-Access configuration values via `myConfig`:
-```nix
-myConfig.nixos.username    # "hakase"
-myConfig.nixos.hostname    # "hakase"
-myConfig.terminal.default  # Terminal emulator
-myConfig.hyprland.monitors # Monitor configuration
-```
+**Key patterns:**
+- Access host config: `myConfig.nixos.username`, `myConfig.terminal.default`
+- Use host-specific packages: `pkgs.unstable` (from nixpkgs), `inputs.neovim` (from flake inputs)
+- Reference other modules via `config` (e.g., `config.home.homeDirectory`)
+- Conditional logic: Check `system` or `myConfig` values
 
 ### Secrets Management
 
-Uses SOPS for encrypted secrets. Keys stored at `~/.config/sops/age/keys.txt`.
+SOPS-encrypted secrets stored in `secrets/secrets.yaml`. Age key at `~/.config/sops/age/keys.txt`.
 
-Access secrets in modules:
+In modules, reference secrets via:
 ```nix
 config.sops.secrets.secret_name.path
 ```
 
 ## Key Technologies
 
-- **Hyprland** with UWSM (systemd session management)
-- **Stylix** for system-wide theming from wallpaper colors
-- **Home Manager** for user environment
-- **nixovim** flake for Neovim configuration
+- **Hyprland** with UWSM (systemd user session management)
+- **Matugen** for automatic system-wide theming from wallpaper colors
+- **Home Manager** for user environment and program configuration
+- **nixovim** external flake for Neovim configuration (treesitter disabled due to read-only NixOS constraints)
+- **SOPS-Nix** for secrets encryption
+- **CachyOS kernel** on hakase (x86_64), **Asahi Linux** on macbook (aarch64)
 
 ## Git Commit Convention
 
-Use conventional commits: `feat(scope):`, `fix(scope):`, `refactor:`, `add:`, `remove:`, `cleanup:`
+Use conventional commits with scope: `feat(scope):`, `fix(scope):`, `refactor:`, `add:`, `remove:`, `cleanup:`
+
+Common scopes: `nixos`, `home`, `apps`, `config`, `modules`, `hyprland`, `firefox`, etc.