docs: update documentation for latest changes

- Add stt-ptt language support documentation
- Add rofi-project-opener module documentation
- Add rofi-project-opener package documentation
- Update zellij-ps documentation
- Update guides and reference patterns
- Update AGENTS.md with latest commands

AGENTS.md

@@ -26,25 +26,27 @@ Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev s
 
 ## WHERE TO LOOK
 
-| Task | Location | Notes |
+| Task                 | Location                           | Notes                                 |
-|------|----------|-------|
+| -------------------- | ---------------------------------- | ------------------------------------- |
-| Add package | `pkgs/<name>/default.nix` | Register in `pkgs/default.nix` |
+| Add package          | `pkgs/<name>/default.nix`          | Register in `pkgs/default.nix`        |
-| Add NixOS module | `modules/nixos/<name>.nix` | Import in `modules/nixos/default.nix` |
+| Add NixOS module     | `modules/nixos/<name>.nix`         | Import in `modules/nixos/default.nix` |
-| Add HM module | `modules/home-manager/<category>/` | Category: cli, coding, or root |
+| Add HM module        | `modules/home-manager/<category>/` | Category: cli, coding, or root        |
-| Override nixpkgs pkg | `overlays/mods/<name>.nix` | Import in `overlays/mods/default.nix` |
+| Override nixpkgs pkg | `overlays/mods/<name>.nix`         | Import in `overlays/mods/default.nix` |
-| Add dev shell | `shells/<name>.nix` | Register in `shells/default.nix` |
+| Add dev shell        | `shells/<name>.nix`                | Register in `shells/default.nix`      |
-| Use port management | `config.m3ta.ports.get "service"` | Host-specific via `hostOverrides` |
+| Use port management  | `config.m3ta.ports.get "service"`  | Host-specific via `hostOverrides`     |
 
 ## CONVENTIONS
 
 **Formatter**: `nix fmt` before commit (alejandra)
 
 **Naming**:
+
 - Packages: `lowercase-hyphen` (e.g., `hyprpaper-random`)
 - Variables: `camelCase` (e.g., `portHelpers`)
 - Module options: `m3ta.*` namespace
 
 **Imports**: Multi-line, trailing commas:
+
 ```nix
 {
   lib,
@@ -54,6 +56,7 @@ Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev s
 ```
 
 **Modules**: Standard pattern:
+
 ```nix
 { config, lib, pkgs, ... }:
 with lib; let
@@ -67,6 +70,7 @@ in {
 ```
 
 **Meta**: Always include all fields:
+
 ```nix
 meta = with lib; {
   description = "...";
@@ -119,13 +123,13 @@ deadnix .                    # Find dead code
 
 ## ANTI-PATTERNS
 
-| Don't | Do Instead |
+| Don't                     | Do Instead                                                          |
-|-------|------------|
+| ------------------------- | ------------------------------------------------------------------- |
-| `lib.fakeHash` in commits | Get real hash: `nix build`, copy from error |
+| `lib.fakeHash` in commits | Get real hash: `nix build`, copy from error                         |
-| Flat module files | Organize by category (`cli/`, `coding/`) |
+| Flat module files         | Organize by category (`cli/`, `coding/`)                            |
-| Hardcode ports | Use `m3ta.ports` module |
+| Hardcode ports            | Use `m3ta.ports` module                                             |
-| Skip meta fields | Include all: description, homepage, license, platforms, mainProgram |
+| Skip meta fields          | Include all: description, homepage, license, platforms, mainProgram |
-| `with pkgs;` in modules | Explicit `pkgs.package` or `with pkgs; [ ... ]` in lists only |
+| `with pkgs;` in modules   | Explicit `pkgs.package` or `with pkgs; [ ... ]` in lists only       |
 
 ## COMMIT FORMAT
 
@@ -143,28 +147,16 @@ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `chore`
 - **Overlays**: `modifications` overlay uses `{prev}:` pattern, not `{final, prev}:`
 - **Dev shell tools**: `statix`, `deadnix` only available inside `nix develop`
 
-## Landing the Plane (Session Completion)
+## Issue Tracking
 
-**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+This project uses **bd (beads)** for issue tracking.
+Run `bd prime` for workflow context, or install hooks (`bd hooks install`) for auto-injection.
 
-**MANDATORY WORKFLOW:**
+**Quick reference:**
 
-1. **File issues for remaining work** - Create issues for anything that needs follow-up
+- `bd ready` - Find unblocked work
-2. **Run quality gates** (if code changed) - Tests, linters, builds
+- `bd create "Title" --type task --priority 2` - Create issue
-3. **Update issue status** - Close finished work, update in-progress items
+- `bd close <id>` - Complete work
-4. **PUSH TO REMOTE** - This is MANDATORY:
+- `bd sync` - Sync with git (run at session end)
-   ```bash
-   git pull --rebase
-   bd sync
-   git push
-   git status  # MUST show "up to date with origin"
-   ```
-5. **Clean up** - Clear stashes, prune remote branches
-6. **Verify** - All changes committed AND pushed
-7. **Hand off** - Provide context for next session
 
-**CRITICAL RULES:**
+For full workflow details: `bd prime`
-- Work is NOT complete until `git push` succeeds
-- NEVER stop before pushing - that leaves work stranded locally
-- NEVER say "ready to push when you are" - YOU must push
-- If push fails, resolve and retry until it succeeds

docs/guides/getting-started.md

@@ -246,7 +246,7 @@ home-manager switch
     m3ta-nixpkgs.homeManagerModules.default
   ];
 
-  m3ta.cli.zellij-ps = {
+  cli.zellij-ps = {
     enable = true;
   };
 

docs/guides/using-modules.md

@@ -170,12 +170,12 @@ m3ta.ports = {
 
 **Documentation**: [Port Management Guide](./port-management.md)
 
-#### `m3ta.cli.zellij-ps`
+#### `cli.zellij-ps`
 
 Zellij project switcher for quickly navigating between project folders.
 
 ```nix
-m3ta.cli.zellij-ps = {
+cli.zellij-ps = {
   enable = true;
   package = pkgs.zellij-ps;
 };
@@ -183,7 +183,7 @@ m3ta.cli.zellij-ps = {
 
 **Documentation**: [zellij-ps Module](../modules/home-manager/cli/zellij-ps.md)
 
-#### `m3ta.coding.editors`
+#### `coding.editors`
 
 Editor configurations.
 
@@ -395,12 +395,12 @@ config = mkIf cfg.enable {
   };
 
   # CLI tools
-  m3ta.cli.zellij-ps = {
+  cli.zellij-ps = {
     enable = true;
   };
 
   # Coding tools
-  m3ta.coding.editors = {
+  coding.editors = {
     enable = true;
     neovim.enable = true;
   };

docs/modules/home-manager/cli/rofi-project-opener.md

@@ -0,0 +1,219 @@
+# rofi-project-opener Module
+
+Home Manager module for configuring the rofi-project-opener package.
+
+## Overview
+
+This module provides declarative configuration for rofi-project-opener, a Rofi-based project launcher. It generates the necessary configuration files and installs the package.
+
+## Quick Start
+
+```nix
+{config, pkgs, ...}: {
+  cli.rofi-project-opener = {
+    enable = true;
+    projectDirs = {
+      dev = { path = "~/dev"; };
+      work = { path = "~/work"; args = "--agent work-assistant"; };
+    };
+  };
+}
+```
+
+## Options
+
+### `cli.rofi-project-opener.enable`
+
+Whether to enable rofi-project-opener.
+
+**Type:** `boolean`
+**Default:** `false`
+
+### `cli.rofi-project-opener.projectDirs`
+
+Attribute set of base directories to scan for project subdirectories.
+
+**Type:** `attrsOf (submodule)`
+
+Each entry is a submodule with:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `path` | `str` | required | Base directory path (supports `~`) |
+| `args` | `str` | `""` | Arguments to pass to command |
+
+**Default:**
+```nix
+{
+  dev = { path = "~/dev"; };
+  projects = { path = "~/projects"; };
+}
+```
+
+**Example:**
+```nix
+projectDirs = {
+  nixpkgs = { path = "~/p/NIX"; args = "--agent nix-expert"; };
+  chat = { path = "~/p/CHAT"; args = "--agent chiron"; };
+  dev = { path = "~/dev"; };
+  work = { path = "~/work"; args = "--profile work"; };
+};
+```
+
+### `cli.rofi-project-opener.terminal`
+
+Terminal emulator to use for launching projects.
+
+**Type:** `either str package`
+**Default:** `"kitty"`
+
+**Examples:**
+```nix
+# Using a package
+terminal = pkgs.kitty;
+terminal = pkgs.alacritty;
+
+# Using a string (must be in PATH)
+terminal = "kitty";
+terminal = "wezterm";
+```
+
+### `cli.rofi-project-opener.terminalCommand`
+
+Command to run in the terminal after navigating to the project directory.
+
+**Type:** `str`
+**Default:** `""` (runs `opencode` with args)
+
+**Placeholders:**
+- `%s` - Project path
+- `%a` - Project args (from `projectDirs.<name>.args`)
+
+**Examples:**
+```nix
+# Default behavior - run opencode with project args
+terminalCommand = "";
+
+# Explicit opencode with args
+terminalCommand = "opencode %a";
+
+# Different editor
+terminalCommand = "nvim";
+
+# VSCode with path
+terminalCommand = "code %s";
+
+# Custom application
+terminalCommand = "my-dev-tool --project %s %a";
+```
+
+### `cli.rofi-project-opener.rofiPrompt`
+
+Prompt text displayed in the Rofi menu.
+
+**Type:** `str`
+**Default:** `"Select project"`
+
+### `cli.rofi-project-opener.rofiArgs`
+
+Arguments to pass to Rofi.
+
+**Type:** `listOf str`
+**Default:** `["-dmenu" "-i"]`
+
+**Example:**
+```nix
+rofiArgs = ["-dmenu" "-i" "-theme" "gruvbox" "-width" "50"];
+```
+
+## Generated Files
+
+The module generates these configuration files:
+
+### `~/.config/rofi-project-opener/projects.json`
+
+JSON file containing project directories:
+
+```json
+{
+  "dev": {"path": "~/dev", "args": ""},
+  "work": {"path": "~/work", "args": "--agent work-assistant"}
+}
+```
+
+### `~/.config/rofi-project-opener/config`
+
+Shell configuration file:
+
+```bash
+TERMINAL="/nix/store/.../bin/kitty"
+TERMINAL_CMD="opencode %a"
+ROFI_PROMPT="Select project"
+ROFI_ARGS="-dmenu -i"
+```
+
+## Full Example
+
+```nix
+{config, pkgs, ...}: {
+  imports = [m3ta-nixpkgs.homeManagerModules.default];
+
+  cli.rofi-project-opener = {
+    enable = true;
+
+    # Project directories with optional args
+    projectDirs = {
+      nixpkgs = {
+        path = "~/p/NIX";
+        args = "";
+      };
+      chat = {
+        path = "~/p/CHAT";
+        args = "--agent chiron";
+      };
+      dev = {
+        path = "~/dev";
+        args = "";
+      };
+    };
+
+    # Terminal configuration
+    terminal = pkgs.kitty;
+    terminalCommand = "opencode %a";
+
+    # Rofi configuration
+    rofiPrompt = "Open Project";
+    rofiArgs = ["-dmenu" "-i" "-theme" "nord"];
+  };
+}
+```
+
+## Usage
+
+After enabling, run:
+
+```bash
+rofi-project-opener
+```
+
+Or bind to a keyboard shortcut in your window manager:
+
+**Hyprland:**
+```nix
+wayland.windowManager.hyprland.settings.bind = [
+  "$mod, P, exec, rofi-project-opener"
+];
+```
+
+**Sway:**
+```nix
+wayland.windowManager.sway.config.keybindings = {
+  "${modifier}+p" = "exec rofi-project-opener";
+};
+```
+
+## Related
+
+- [rofi-project-opener Package](../../../packages/rofi-project-opener.md) - Package documentation
+- [zellij-ps Module](./zellij-ps.md) - Similar project switcher for Zellij
+- [Home Manager Overview](../overview.md) - All Home Manager modules

docs/modules/home-manager/cli/stt-ptt.md

@@ -104,6 +104,42 @@ Notification timeout in milliseconds for the recording indicator.
 - Default: `3000`
 - Example: `5000` (5 seconds), `0` (persistent)
 
+### `cli.stt-ptt.language`
+
+Language for speech recognition. Use "auto" for automatic language detection, or specify a language code for better accuracy.
+
+- Type: `enum ["auto", "en", "es", "fr", "de", "it", "pt", "ru", "zh", "ja", "ko", "ar", "hi", "tr", "pl", "nl", "sv", "da", "fi", "no", "vi", "th", "id", "uk", "cs"]`
+- Default: `"auto"`
+
+**Auto-detection**: When set to "auto", whisper.cpp analyzes the audio to determine the spoken language automatically.
+
+**Language specification**: Specifying a language code improves transcription accuracy if you know the language in advance.
+
+```nix
+# Automatic language detection (default)
+language = "auto";
+
+# Force English transcription
+language = "en";
+
+# Spanish transcription
+language = "es";
+```
+
+**Common language codes:**
+
+| Code | Language |
+|------|----------|
+| `en` | English |
+| `es` | Spanish |
+| `fr` | French |
+| `de` | German |
+| `zh` | Chinese |
+| `ja` | Japanese |
+| `ko` | Korean |
+
+whisper.cpp supports 100+ languages. See whisper.cpp documentation for the full list.
+
 ## Usage
 
 After enabling, bind `stt-ptt start` and `stt-ptt stop` to a key:
@@ -166,6 +202,16 @@ cli.stt-ptt = {
 };
 ```
 
+### Language-Specific Transcription
+
+```nix
+cli.stt-ptt = {
+  enable = true;
+  model = "ggml-large-v3-turbo";
+  language = "es";  # Force Spanish transcription
+};
+```
+
 ### High Quality with NVIDIA GPU
 
 ```nix
@@ -221,6 +267,7 @@ The module sets these automatically:
 | Variable | Value |
 |----------|-------|
 | `STT_MODEL` | `~/.local/share/stt-ptt/models/<model>.bin` |
+| `STT_LANGUAGE` | Configured language ("auto" by default) |
 | `STT_NOTIFY_TIMEOUT` | Configured timeout in ms |
 
 ## Requirements

docs/modules/home-manager/cli/zellij-ps.md

@@ -12,7 +12,7 @@ This module configures the zellij-ps tool, a Fish script that provides a fast, i
 {config, ...}: {
   imports = [m3ta-nixpkgs.homeManagerModules.default];
 
-  m3ta.cli.zellij-ps = {
+  cli.zellij-ps = {
     enable = true;
   };
 }
@@ -20,14 +20,14 @@ This module configures the zellij-ps tool, a Fish script that provides a fast, i
 
 ## Module Options
 
-### `m3ta.cli.zellij-ps.enable`
+### `cli.zellij-ps.enable`
 
 Enable zellij-ps module.
 
 - Type: `boolean`
 - Default: `false`
 
-### `m3ta.cli.zellij-ps.package`
+### `cli.zellij-ps.package`
 
 Custom package to use.
 
@@ -60,7 +60,7 @@ zellij-ps ~/projects/my-project
 Use a custom or modified package:
 
 ```nix
-m3ta.cli.zellij-ps = {
+cli.zellij-ps = {
   enable = true;
   package = pkgs.callPackage ./my-zellij-ps {};
 };

docs/modules/home-manager/overview.md

@@ -62,12 +62,12 @@ m3ta.ports = {
 };
 
 # CLI tools
-m3ta.cli.zellij-ps = {
+cli.zellij-ps = {
   enable = true;
 };
 
 # Coding tools
-m3ta.coding.editors = {
+coding.editors = {
   enable = true;
   neovim.enable = true;
 };
@@ -137,11 +137,11 @@ Development tools and configurations:
     currentHost = "desktop";
   };
 
-  m3ta.cli.zellij-ps = {
+  cli.zellij-ps = {
     enable = true;
   };
 
-  m3ta.coding.editors = {
+  coding.editors = {
     enable = true;
     neovim.enable = true;
   };

docs/packages/rofi-project-opener.md

@@ -0,0 +1,245 @@
+# rofi-project-opener
+
+A Rofi-based project directory launcher for quickly opening projects in your terminal with custom commands.
+
+## Description
+
+rofi-project-opener scans configured base directories for project subdirectories and presents them in a Rofi menu. When a project is selected, it opens a terminal, navigates to the project directory, and runs a configurable command (defaults to `opencode`).
+
+Key features:
+- JSON-based configuration for project directories
+- Per-directory custom arguments (e.g., `--agent chiron` for AI coding assistants)
+- Placeholder support (`%s` for path, `%a` for args) in custom commands
+- Works with any terminal emulator
+
+## Installation
+
+### Via Overlay
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    rofi-project-opener
+  ];
+}
+```
+
+### Direct Reference
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    inputs.m3ta-nixpkgs.packages.${pkgs.system}.rofi-project-opener
+  ];
+}
+```
+
+### Run Directly
+
+```bash
+nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#rofi-project-opener
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Launch rofi project selector
+rofi-project-opener
+```
+
+This will:
+
+1. Read project directories from `~/.config/rofi-project-opener/projects.json`
+2. Scan each directory for subdirectories (non-hidden)
+3. Display projects in Rofi for fuzzy selection
+4. Open terminal, cd to project, and run the configured command
+
+### Configuration Files
+
+The script uses two configuration files in `~/.config/rofi-project-opener/`:
+
+**projects.json** - Project directories with optional args:
+```json
+{
+  "nixpkgs": {"path": "~/p/NIX", "args": ""},
+  "chat": {"path": "~/p/CHAT", "args": "--agent chiron"},
+  "dev": {"path": "~/dev", "args": ""}
+}
+```
+
+**config** - Terminal and Rofi settings:
+```bash
+TERMINAL="/path/to/kitty"
+TERMINAL_CMD="opencode %a"
+ROFI_PROMPT="Select project"
+ROFI_ARGS="-dmenu -i"
+```
+
+### Placeholders
+
+When using `terminalCommand`, these placeholders are available:
+
+| Placeholder | Description |
+|-------------|-------------|
+| `%s` | Full path to selected project |
+| `%a` | Args from projectDirs config |
+
+**Examples:**
+```nix
+terminalCommand = "opencode %a";           # opencode with project args
+terminalCommand = "nvim";                  # just nvim, no args
+terminalCommand = "code %s";               # vscode with explicit path
+terminalCommand = "myapp --dir %s %a";     # custom app with both
+```
+
+## Home Manager Module
+
+### Enable Module
+
+```nix
+{config, pkgs, ...}: {
+  imports = [m3ta-nixpkgs.homeManagerModules.default];
+
+  cli.rofi-project-opener = {
+    enable = true;
+    projectDirs = {
+      nixpkgs = { path = "~/p/NIX"; };
+      chat = { path = "~/p/CHAT"; args = "--agent chiron"; };
+      dev = { path = "~/dev"; };
+    };
+    terminal = pkgs.kitty;
+    terminalCommand = "opencode %a";
+  };
+}
+```
+
+### Module Options
+
+#### `cli.rofi-project-opener.enable`
+
+Enable the rofi-project-opener module.
+
+- Type: `boolean`
+- Default: `false`
+
+#### `cli.rofi-project-opener.projectDirs`
+
+Attribute set of base directories to scan for projects.
+
+- Type: `attrsOf (submodule { path, args })`
+- Default: `{ dev = { path = "~/dev"; }; projects = { path = "~/projects"; }; }`
+
+Each entry supports:
+- `path` (required): Base directory path
+- `args` (optional): Arguments to pass to the command
+
+#### `cli.rofi-project-opener.terminal`
+
+Terminal emulator to use.
+
+- Type: `either str package`
+- Default: `"kitty"`
+
+#### `cli.rofi-project-opener.terminalCommand`
+
+Command to run in the terminal. Supports `%s` (path) and `%a` (args) placeholders.
+
+- Type: `str`
+- Default: `""` (runs `opencode %a`)
+
+#### `cli.rofi-project-opener.rofiPrompt`
+
+Prompt text displayed in Rofi.
+
+- Type: `str`
+- Default: `"Select project"`
+
+#### `cli.rofi-project-opener.rofiArgs`
+
+Arguments to pass to Rofi.
+
+- Type: `listOf str`
+- Default: `["-dmenu" "-i"]`
+
+## Requirements
+
+### System Requirements
+
+- Linux with Rofi installed
+- A terminal emulator (kitty, alacritty, etc.)
+- jq (included as dependency)
+
+### Runtime Dependencies
+
+These are automatically included:
+- rofi
+- jq
+- coreutils
+- gnugrep
+- gnused
+- libnotify
+
+## Platform Support
+
+- Linux (primary)
+- macOS (not tested)
+- Windows (not supported)
+
+## Build Information
+
+- **Type**: Bash script
+- **License**: MIT
+
+## Troubleshooting
+
+### No Projects Found
+
+Check that your project directories exist and contain subdirectories:
+
+```bash
+cat ~/.config/rofi-project-opener/projects.json
+ls ~/p/NIX  # Should show subdirectories
+```
+
+### Args Not Being Passed
+
+Make sure you're using `%a` placeholder in your `terminalCommand`:
+
+```nix
+# Wrong - args not passed
+terminalCommand = "opencode";
+
+# Correct - args passed via placeholder
+terminalCommand = "opencode %a";
+
+# Also correct - empty uses default behavior with args
+terminalCommand = "";
+```
+
+### Rofi Not Showing
+
+Ensure Rofi is installed and working:
+
+```bash
+echo -e "item1\nitem2" | rofi -dmenu
+```
+
+### Terminal Not Opening
+
+Check terminal configuration:
+
+```nix
+# Using package
+terminal = pkgs.kitty;
+
+# Using string (must be in PATH)
+terminal = "kitty";
+```
+
+## Related
+
+- [rofi-project-opener Module](../modules/home-manager/cli/rofi-project-opener.md) - Home Manager module documentation
+- [zellij-ps](./zellij-ps.md) - Similar project switcher for Zellij
+- [Using Modules](../guides/using-modules.md) - How to use modules

docs/packages/zellij-ps.md

@@ -78,7 +78,7 @@ Folders should be delimited by `:` and can include `~` for home directory.
 {config, ...}: {
   imports = [m3ta-nixpkgs.homeManagerModules.default];
 
-  m3ta.cli.zellij-ps = {
+  cli.zellij-ps = {
     enable = true;
   };
 }
@@ -86,14 +86,14 @@ Folders should be delimited by `:` and can include `~` for home directory.
 
 ### Module Options
 
-#### `m3ta.cli.zellij-ps.enable`
+#### `cli.zellij-ps.enable`
 
 Enable the zellij-ps module.
 
 - Type: `boolean`
 - Default: `false`
 
-#### `m3ta.cli.zellij-ps.package`
+#### `cli.zellij-ps.package`
 
 Custom package to use.
 

docs/reference/patterns.md

@@ -169,8 +169,8 @@ nix build .#your-package
   };
 
   config = mkMerge [
-    (mkIf config.m3ta.cli.tool1.enable {...})
+    (mkIf config.cli.tool1.enable {...})
-    (mkIf config.m3ta.cli.tool2.enable {...})
+    (mkIf config.cli.tool2.enable {...})
     # ... many more
   ];
 }
@@ -380,18 +380,18 @@ port-helpers   # Bad
 
 ### Module Options
 
-**Good**: `m3ta.*` namespace
+**Good**: `m3ta.*` namespace for m3ta modules, `cli.*` namespace for CLI modules
 
 ```nix
 m3ta.ports.enable = true;
-m3ta.cli.zellij-ps.enable = true;
+cli.zellij-ps.enable = true;
 ```
 
 **Bad**: Flat namespace
 
 ```nix
 ports.enable = true;  # Potential conflict
-cli.zellij-ps.enable = true;  # Hard to find
+zellij-ps.enable = true;  # Hard to find
 ```
 
 ## Performance