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
2026-01-10 19:12:45 +01:00
parent 6230c04a61
commit 00b858fbbe
10 changed files with 561 additions and 58 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,7 +27,7 @@ Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev s
 ## WHERE TO LOOK

 | Task                 | Location                           | Notes                                 |
-|------|----------|-------|
+| -------------------- | ---------------------------------- | ------------------------------------- |
 | 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 HM module        | `modules/home-manager/<category>/` | Category: cli, coding, or root        |
@@ -40,11 +40,13 @@ Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev s
 **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 = "...";
@@ -120,7 +124,7 @@ deadnix .                    # Find dead code
 ## ANTI-PATTERNS

 | Don't                     | Do Instead                                                          |
-|-------|------------|
+| ------------------------- | ------------------------------------------------------------------- |
 | `lib.fakeHash` in commits | Get real hash: `nix build`, copy from error                         |
 | Flat module files         | Organize by category (`cli/`, `coding/`)                            |
 | Hardcode ports            | Use `m3ta.ports` module                                             |
@@ -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
-2. **Run quality gates** (if code changed) - Tests, linters, builds
-3. **Update issue status** - Close finished work, update in-progress items
-4. **PUSH TO REMOTE** - This is MANDATORY:
-   ```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
+- `bd ready` - Find unblocked work
+- `bd create "Title" --type task --priority 2` - Create issue
+- `bd close <id>` - Complete work
+- `bd sync` - Sync with git (run at session end)

-**CRITICAL RULES:**
- 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
+For full workflow details: `bd prime`
--- a/docs/guides/getting-started.md
+++ b/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;
  };

--- a/docs/guides/using-modules.md
+++ b/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;
  };
--- a/docs/modules/home-manager/cli/rofi-project-opener.md
+++ b/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
--- a/docs/modules/home-manager/cli/stt-ptt.md
+++ b/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
--- a/docs/modules/home-manager/cli/zellij-ps.md
+++ b/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 {};
 };
--- a/docs/modules/home-manager/overview.md
+++ b/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;
  };
--- a/docs/packages/rofi-project-opener.md
+++ b/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
--- a/docs/packages/zellij-ps.md
+++ b/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.

--- a/docs/reference/patterns.md
+++ b/docs/reference/patterns.md
@@ -169,8 +169,8 @@ nix build .#your-package
  };

  config = mkMerge [
-    (mkIf config.m3ta.cli.tool1.enable {...})
-    (mkIf config.m3ta.cli.tool2.enable {...})
+    (mkIf config.cli.tool1.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