From 5fe83ddc8a4df9519fb6e68e540d9bad6099ec6d Mon Sep 17 00:00:00 2001
From: kenji <kenji@hakase>
Date: Mon, 5 Jan 2026 12:27:19 -0600
Subject: [PATCH] docs: add gemini.md

---
 GEMINI.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 GEMINI.md

diff --git a/GEMINI.md b/GEMINI.md
new file mode 100644
index 0000000..36bde75
--- /dev/null
+++ b/GEMINI.md
@@ -0,0 +1,65 @@
+# HakaseOS - NixOS Configuration
+
+This is a modular, flake-based NixOS configuration for a single host (`hakase`). It features a custom Hyprland desktop environment, automated theming via Matugen, and strict separation of concerns using a custom `myConfig` object.
+
+## Project Structure
+
+*   **`flake.nix`**: The entry point. Defines inputs (Hyprland, Chaotic, Home Manager, etc.) and creates the system configuration.
+*   **`config.nix`**: Central source of truth. Defines global variables (user details, monitor config, theme settings) exposed as `myConfig`.
+*   **`hosts/hakase/`**: Host-specific configuration.
+    *   `configuration.nix`: Main system entry point.
+*   **`modules/`**: Reusable modules.
+    *   `nixos/`: System-level modules (boot, hardware, services).
+    *   `home/`: Home-manager modules (UI, apps, user services).
+*   **`apps/`**: Application-specific configurations. Each app has its own directory (e.g., `hyprland`, `firefox`, `ghostty`) with a `default.nix`.
+*   **`assets/`**: Static assets like wallpapers (`firewatch.png`).
+*   **`secrets/`**: Encrypted secrets managed by SOPS.
+
+## Architecture & Conventions
+
+### 1. The `myConfig` Object
+Global configuration is not hardcoded in modules. Instead, it is defined in `config.nix` and passed to all modules via `specialArgs`.
+**Usage Pattern:**
+```nix
+# In any module
+{ pkgs, config, myConfig, ... }:
+{
+  # Access values
+  home.username = myConfig.nixos.username;
+}
+```
+
+### 2. Module Hierarchy
+*   **System**: `flake.nix` -> `hosts/hakase/configuration.nix` -> `modules/nixos/default.nix` -> `modules/nixos/*.nix`
+*   **User**: `modules/nixos/user.nix` (or similar) -> `home-manager` -> `home/hakase.nix` -> `modules/home/*.nix` -> `apps/*/default.nix`
+
+### 3. Application Configuration
+Do not dump config into one large file. Create a dedicated folder in `apps/<app_name>/` with a `default.nix`.
+*   Example: `apps/ghostty/default.nix`
+
+## Key Commands
+
+### System Management
+*   **Rebuild & Switch**:
+    ```bash
+    sudo nixos-rebuild switch --flake ~/.config/nixos/#hakase
+    # or alias:
+    update
+    ```
+
+### Secrets (SOPS)
+*   **Edit Secrets**:
+    ```bash
+    nix-shell -p sops --run "sops secrets/secrets.yaml"
+    ```
+*   **Update Keys**:
+    ```bash
+    nix-shell -p sops --run "sops updatekeys secrets/secrets.yaml"
+    ```
+
+## Development Guidelines
+
+*   **Matugen**: used for theming. Templates are located in `apps/matugen/templates/`.
+*   **Hyprland**: Config is split into `apps/hyprland/hypr/*.nix`.
+*   **Formatting**: Follow existing indentation (2 spaces usually).
+*   **Commits**: Use Conventional Commits (e.g., `feat(hyprland): add new bind`).