From 00b858fbbed6d2ad9e9a4303bdbe96dc249c5e22 Mon Sep 17 00:00:00 2001 From: m3tm3re Date: Sat, 10 Jan 2026 19:12:45 +0100 Subject: [PATCH] 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 | 64 ++--- docs/guides/getting-started.md | 2 +- docs/guides/using-modules.md | 10 +- .../home-manager/cli/rofi-project-opener.md | 219 ++++++++++++++++ docs/modules/home-manager/cli/stt-ptt.md | 47 ++++ docs/modules/home-manager/cli/zellij-ps.md | 8 +- docs/modules/home-manager/overview.md | 8 +- docs/packages/rofi-project-opener.md | 245 ++++++++++++++++++ docs/packages/zellij-ps.md | 6 +- docs/reference/patterns.md | 10 +- 10 files changed, 561 insertions(+), 58 deletions(-) create mode 100644 docs/modules/home-manager/cli/rofi-project-opener.md create mode 100644 docs/packages/rofi-project-opener.md diff --git a/AGENTS.md b/AGENTS.md index a8c0bed..0ad1d4e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,25 +26,27 @@ Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev s ## WHERE TO LOOK -| Task | Location | Notes | -|------|----------|-------| -| Add package | `pkgs//default.nix` | Register in `pkgs/default.nix` | -| Add NixOS module | `modules/nixos/.nix` | Import in `modules/nixos/default.nix` | -| Add HM module | `modules/home-manager//` | Category: cli, coding, or root | -| Override nixpkgs pkg | `overlays/mods/.nix` | Import in `overlays/mods/default.nix` | -| Add dev shell | `shells/.nix` | Register in `shells/default.nix` | -| Use port management | `config.m3ta.ports.get "service"` | Host-specific via `hostOverrides` | +| Task | Location | Notes | +| -------------------- | ---------------------------------- | ------------------------------------- | +| Add package | `pkgs//default.nix` | Register in `pkgs/default.nix` | +| Add NixOS module | `modules/nixos/.nix` | Import in `modules/nixos/default.nix` | +| Add HM module | `modules/home-manager//` | Category: cli, coding, or root | +| Override nixpkgs pkg | `overlays/mods/.nix` | Import in `overlays/mods/default.nix` | +| Add dev shell | `shells/.nix` | Register in `shells/default.nix` | +| 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 | -|-------|------------| -| `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 | -| Skip meta fields | Include all: description, homepage, license, platforms, mainProgram | -| `with pkgs;` in modules | Explicit `pkgs.package` or `with pkgs; [ ... ]` in lists only | +| 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 | +| Skip meta fields | Include all: description, homepage, license, platforms, mainProgram | +| `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 -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 ` - 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` diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index a5d327d..08364e4 100644 --- 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; }; diff --git a/docs/guides/using-modules.md b/docs/guides/using-modules.md index 90c3510..3c0ba9a 100644 --- 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; }; diff --git a/docs/modules/home-manager/cli/rofi-project-opener.md b/docs/modules/home-manager/cli/rofi-project-opener.md new file mode 100644 index 0000000..7db07c2 --- /dev/null +++ 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..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 diff --git a/docs/modules/home-manager/cli/stt-ptt.md b/docs/modules/home-manager/cli/stt-ptt.md index 6237d32..02c242e 100644 --- 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/.bin` | +| `STT_LANGUAGE` | Configured language ("auto" by default) | | `STT_NOTIFY_TIMEOUT` | Configured timeout in ms | ## Requirements diff --git a/docs/modules/home-manager/cli/zellij-ps.md b/docs/modules/home-manager/cli/zellij-ps.md index 9f2bee2..e3ffa85 100644 --- 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 {}; }; diff --git a/docs/modules/home-manager/overview.md b/docs/modules/home-manager/overview.md index 1030465..c433acf 100644 --- 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; }; diff --git a/docs/packages/rofi-project-opener.md b/docs/packages/rofi-project-opener.md new file mode 100644 index 0000000..8b7f463 --- /dev/null +++ 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 diff --git a/docs/packages/zellij-ps.md b/docs/packages/zellij-ps.md index 82811ed..43a1fe2 100644 --- 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. diff --git a/docs/reference/patterns.md b/docs/reference/patterns.md index 7aef6ad..324be4a 100644 --- 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