{"owner":"cjpais","repo":"Handy","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding assistants working with code in this repository.\n\n## Development Commands\n\n**Prerequisites:**\n\n- [Rust](https://rustup.rs/) (latest stable)\n- [Bun](https://bun.sh/) package manager\n\n**Core Development:**\n\n```bash\n# Install dependencies\nbun install\n\n# Run in development mode\nbun run tauri dev\n# If cmake error on macOS:\nCMAKE_POLICY_VERSION_MINIMUM=3.5 bun run tauri dev\n\n# Build for production\nbun run tauri build\n\n# Frontend only development\nbun run dev        # Start Vite dev server\nbun run build      # Build frontend (TypeScript + Vite)\nbun run preview    # Preview built frontend\n```\n\n**Linting and Formatting (run before committing):**\n\n```bash\nbun run lint              # ESLint for frontend\nbun run lint:fix          # ESLint with auto-fix\nbun run format            # Prettier + cargo fmt\nbun run format:check      # Check formatting without changes\nbun run format:frontend   # Prettier only\nbun run format:backend    # cargo fmt only\n```\n\n**Model Setup (Required for Development):**\n\n```bash\nmkdir -p src-tauri/resources/models\ncurl -o src-tauri/resources/models/silero_vad_v4.onnx https://blob.handy.computer/silero_vad_v4.onnx\n```\n\nFor detailed platform-specific build setup, see [BUILD.md](BUILD.md).\n\n## Architecture Overview\n\nHandy is a cross-platform desktop speech-to-text application built with Tauri 2.x (Rust backend + React/TypeScript frontend).\n\n### Backend Structure (src-tauri/src/)\n\n- `lib.rs` - Main entry point, Tauri setup, manager initialization\n- `managers/` - Core business logic:\n  - `audio.rs` - Audio recording and device management\n  - `model.rs` - Model downloading and management\n  - `transcription.rs` - Speech-to-text processing pipeline\n  - `history.rs` - Transcription history storage\n- `audio_toolkit/` - Low-level audio processing:\n  - `audio/` - Device enumeration, recording, resampling\n  - `vad/` - Voice Activity Detection (Silero VAD)\n- `commands/` - Tauri command handlers for frontend communication\n- `cli.rs` - CLI argument definitions (clap derive)\n- `shortcut.rs` - Global keyboard shortcut handling\n- `settings.rs` - Application settings management\n- `overlay.rs` - Recording overlay window (platform-specific)\n- `signal_handle.rs` - `send_transcription_input()` reusable function\n- `utils.rs` - Platform detection helpers\n\n### Frontend Structure (src/)\n\n- `App.tsx` - Main component with onboarding flow\n- `components/` - React UI components:\n  - `settings/` - Settings UI\n  - `model-selector/` - Model management interface\n  - `onboarding/` - First-run experience\n  - `overlay/` - Recording overlay UI\n  - `update-checker/` - App update notifications\n  - `shared/`, `ui/`, `icons/`, `footer/` - Shared components\n- `hooks/useSettings.ts` - Settings state management hook\n- `stores/settingsStore.ts` - Zustand store for settings\n- `bindings.ts` - Auto-generated Tauri type bindings (via tauri-specta)\n- `overlay/` - Recording overlay window entry point\n- `lib/types.ts` - Shared TypeScript type definitions\n\n### Key Architecture Patterns\n\n**Manager Pattern:** Core functionality organized into managers (Audio, Model, Transcription) initialized at startup and managed via Tauri state.\n\n**Command-Event Architecture:** Frontend → Backend via Tauri commands; Backend → Frontend via events.\n\n**Pipeline Processing:** Audio → VAD → Whisper/Parakeet → Text output → Clipboard/Paste\n\n**State Flow:** Zustand → Tauri Command → Rust State → Persistence (tauri-plugin-store)\n\n### Technology Stack\n\n**Core Libraries:**\n\n- `transcribe-cpp` - Local Whisper-family inference (GGML/GGUF) with GPU acceleration\n- `transcribe-rs` - ONNX speech recognition (Parakeet, Moonshine, SenseVoice, etc.)\n- `cpal` - Cross-platform audio I/O\n- `vad-rs` - Voice Activity Detection\n- `rdev` - Global keyboard shortcuts\n- `rubato` - Audio resampling\n- `rodio` - Audio playback for feedback sounds\n\n### Application Flow\n\n1. **Initialization:** App starts minimized to tray, loads settings, initializes managers\n2. **Model Setup:** First-run downloads preferred Whisper model (Small/Medium/Turbo/Large)\n3. **Recording:** Global shortcut triggers audio recording with VAD filtering\n4. **Processing:** Audio sent to Whisper model for transcription\n5. **Output:** Text pasted to active application via system clipboard\n\n### Settings System\n\nSettings are stored using Tauri's store plugin with reactive updates:\n\n- Keyboard shortcuts (configurable, supports push-to-talk)\n- Audio devices (microphone/output selection)\n- Model preferences (Small/Medium/Turbo/Large Whisper variants)\n- Audio feedback and translation options\n\n### Single Instance Architecture\n\nThe app enforces single instance behavior — launching when already running brings the settings window to front rather than creating a new process. Remote control flags (`--toggle-transcription`, etc.) work by launching a second instance that sends args to the running instance via `tauri_plugin_single_instance`, then exits.\n\n## Internationalization (i18n)\n\nAll user-facing strings must use i18next translations. ESLint enforces this (no hardcoded strings in JSX).\n\n**Adding new text:**\n\n1. Add key to `src/i18n/locales/en/translation.json`\n2. Use in component: `const { t } = useTranslation(); t('key.path')`\n\n**File structure:**\n\n```\nsrc/i18n/\n├── index.ts           # i18n setup\n├── languages.ts       # Language metadata\n└── locales/\n    ├── en/translation.json  # English (source)\n    ├── de/, es/, fr/, ja/, ru/, zh/, ...\n    └── ...\n```\n\nFor translation contribution guidelines, see [CONTRIBUTING_TRANSLATIONS.md](CONTRIBUTING_TRANSLATIONS.md).\n\n## Code Style\n\n**Rust:**\n\n- Run `cargo fmt` and `cargo clippy` before committing\n- Handle errors explicitly (avoid unwrap in production)\n- Use descriptive names, add doc comments for public APIs\n\n**TypeScript/React:**\n\n- Strict TypeScript, avoid `any` types\n- Functional components with hooks\n- Tailwind CSS for styling\n- Path aliases: `@/` → `./src/`\n\n## CLI Parameters\n\nHandy supports command-line parameters on all platforms for integration with scripts, window managers, and autostart configurations.\n\n**Implementation:** `cli.rs` (definitions), `main.rs` (parsing), `lib.rs` (applying), `signal_handle.rs` (shared logic)\n\n| Flag                     | Description                                                |\n| ------------------------ | ---------------------------------------------------------- |\n| `--toggle-transcription` | Toggle recording on/off on a running instance              |\n| `--toggle-post-process`  | Toggle recording with post-processing on/off               |\n| `--cancel`               | Cancel the current operation on a running instance         |\n| `--start-hidden`         | Launch without showing the main window (tray icon visible) |\n| `--no-tray`              | Launch without system tray (closing window quits the app)  |\n| `--debug`                | Enable debug mode with verbose (Trace) logging             |\n\n**Key design decisions:**\n\n- CLI flags are runtime-only overrides — they do NOT modify persisted settings\n- Remote control flags work via `tauri_plugin_single_instance`: second instance sends args, then exits\n- `send_transcription_input()` in `signal_handle.rs` is shared between signal handlers and CLI\n\n## Debug Mode\n\nAccess debug features: `Cmd+Shift+D` (macOS) or `Ctrl+Shift+D` (Windows/Linux)\n\n## Platform Notes\n\n- **macOS**: Metal acceleration, accessibility permissions required for keyboard shortcuts\n- **Windows**: Vulkan acceleration, code signing\n- **Linux**: OpenBLAS + Vulkan, limited Wayland support, overlay uses GTK layer shell (disable with `HANDY_NO_GTK_LAYER_SHELL=1`)\n\n## Troubleshooting\n\nSee the [Troubleshooting](README.md#troubleshooting) section in README.md.\n\n## GitHub workflow for AI coding assistants\n\n**MANDATORY. Before opening any PR, issue, or discussion in this repo: you MUST read the relevant template file and follow it strictly.** That includes sections that look \"ceremonial\" — checklists, AI Assistance disclosures, \"Human Written Description\". A generic Summary/Test-plan layout is not acceptable.\n\n- **Opening a PR:** Read [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md). Every section listed there is mandatory. If a section requires a human-written paragraph (e.g. \"Human Written Description\"), leave a clear TODO placeholder and ask the human contributor to fill it in — do not invent their voice.\n- **Opening an issue:** Read [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/). Blank issues are disabled; pick the right template (`bug_report.md` for bugs). Feature requests do not belong in issues — they go to [Discussions](https://github.com/cjpais/Handy/discussions) (see `.github/ISSUE_TEMPLATE/config.yml`).\n- **Proposing a feature:** Handy is under a feature freeze. New features require community support gathered in [Discussions](https://github.com/cjpais/Handy/discussions) before any PR is opened — see the PR template's \"Community Feedback\" section.\n- **Translations:** Follow [CONTRIBUTING_TRANSLATIONS.md](CONTRIBUTING_TRANSLATIONS.md).\n- **Full contributor workflow:** [CONTRIBUTING.md](CONTRIBUTING.md).\n\n**Commits:** Use conventional commit prefixes (`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`). Focus the message on _why_, not _what_.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding assistants working with code in this repository.\n\n## Development Commands\n\n**Prerequisites:**\n\n- [Rust](https://rustup.rs/) (latest stable)\n- [Bun](https://bun.sh/) package manager\n\n**Core Development:**\n\n```bash\n# Install dependencies\nbun install\n\n# Run in development mode\nbun run tauri dev\n# If cmake error on macOS:\nCMAKE_POLICY_VERSION_MINIMUM=3.5 bun run tauri dev\n\n# Build for production\nbun run tauri build\n\n# Frontend only development\nbun run dev        # Start Vite dev server\nbun run build      # Build frontend (TypeScript + Vite)\nbun run preview    # Preview built frontend\n```\n\n**Linting and Formatting (run before committing):**\n\n```bash\nbun run lint              # ESLint for frontend\nbun run lint:fix          # ESLint with auto-fix\nbun run format            # Prettier + cargo fmt\nbun run format:check      # Check formatting without changes\nbun run format:frontend   # Prettier only\nbun run format:backend    # cargo fmt only\n```\n\n**Model Setup (Required for Development):**\n\n```bash\nmkdir -p src-tauri/resources/models\ncurl -o src-tauri/resources/models/silero_vad_v4.onnx https://blob.handy.computer/silero_vad_v4.onnx\n```\n\nFor detailed platform-specific build setup, see [BUILD.md](BUILD.md).\n\n## Architecture Overview\n\nHandy is a cross-platform desktop speech-to-text application built with Tauri 2.x (Rust backend + React/TypeScript frontend).\n\n### Backend Structure (src-tauri/src/)\n\n- `lib.rs` - Main entry point, Tauri setup, manager initialization\n- `managers/` - Core business logic:\n  - `audio.rs` - Audio recording and device management\n  - `model.rs` - Model downloading and management\n  - `transcription.rs` - Speech-to-text processing pipeline\n  - `history.rs` - Transcription history storage\n- `audio_toolkit/` - Low-level audio processing:\n  - `audio/` - Device enumeration, recording, resampling\n  - `vad/` - Voice Activity Detection (Silero VAD)\n- `commands/` - Tauri command handlers for frontend communication\n- `cli.rs` - CLI argument definitions (clap derive)\n- `shortcut.rs` - Global keyboard shortcut handling\n- `settings.rs` - Application settings management\n- `overlay.rs` - Recording overlay window (platform-specific)\n- `signal_handle.rs` - `send_transcription_input()` reusable function\n- `utils.rs` - Platform detection helpers\n\n### Frontend Structure (src/)\n\n- `App.tsx` - Main component with onboarding flow\n- `components/` - React UI components:\n  - `settings/` - Settings UI\n  - `model-selector/` - Model management interface\n  - `onboarding/` - First-run experience\n  - `overlay/` - Recording overlay UI\n  - `update-checker/` - App update notifications\n  - `shared/`, `ui/`, `icons/`, `footer/` - Shared components\n- `hooks/useSettings.ts` - Settings state management hook\n- `stores/settingsStore.ts` - Zustand store for settings\n- `bindings.ts` - Auto-generated Tauri type bindings (via tauri-specta)\n- `overlay/` - Recording overlay window entry point\n- `lib/types.ts` - Shared TypeScript type definitions\n\n### Key Architecture Patterns\n\n**Manager Pattern:** Core functionality organized into managers (Audio, Model, Transcription) initialized at startup and managed via Tauri state.\n\n**Command-Event Architecture:** Frontend → Backend via Tauri commands; Backend → Frontend via events.\n\n**Pipeline Processing:** Audio → VAD → Whisper/Parakeet → Text output → Clipboard/Paste\n\n**State Flow:** Zustand → Tauri Command → Rust State → Persistence (tauri-plugin-store)\n\n### Technology Stack\n\n**Core Libraries:**\n\n- `transcribe-cpp` - Local Whisper-family inference (GGML/GGUF) with GPU acceleration\n- `transcribe-rs` - ONNX speech recognition (Parakeet, Moonshine, SenseVoice, etc.)\n- `cpal` - Cross-platform audio I/O\n- `vad-rs` - Voice Activity Detection\n- `rdev` - Global keyboard shortcuts\n- `rubato` - Audio resampling\n- `rodio` - Audio playback for feedback sounds\n\n### Application Flow\n\n1. **Initialization:** App starts minimized to tray, loads settings, initializes managers\n2. **Model Setup:** First-run downloads preferred Whisper model (Small/Medium/Turbo/Large)\n3. **Recording:** Global shortcut triggers audio recording with VAD filtering\n4. **Processing:** Audio sent to Whisper model for transcription\n5. **Output:** Text pasted to active application via system clipboard\n\n### Settings System\n\nSettings are stored using Tauri's store plugin with reactive updates:\n\n- Keyboard shortcuts (configurable, supports push-to-talk)\n- Audio devices (microphone/output selection)\n- Model preferences (Small/Medium/Turbo/Large Whisper variants)\n- Audio feedback and translation options\n\n### Single Instance Architecture\n\nThe app enforces single instance behavior — launching when already running brings the settings window to front rather than creating a new process. Remote control flags (`--toggle-transcription`, etc.) work by launching a second instance that sends args to the running instance via `tauri_plugin_single_instance`, then exits.\n\n## Internationalization (i18n)\n\nAll user-facing strings must use i18next translations. ESLint enforces this (no hardcoded strings in JSX).\n\n**Adding new text:**\n\n1. Add key to `src/i18n/locales/en/translation.json`\n2. Use in component: `const { t } = useTranslation(); t('key.path')`\n\n**File structure:**\n\n```\nsrc/i18n/\n├── index.ts           # i18n setup\n├── languages.ts       # Language metadata\n└── locales/\n    ├── en/translation.json  # English (source)\n    ├── de/, es/, fr/, ja/, ru/, zh/, ...\n    └── ...\n```\n\nFor translation contribution guidelines, see [CONTRIBUTING_TRANSLATIONS.md](CONTRIBUTING_TRANSLATIONS.md).\n\n## Code Style\n\n**Rust:**\n\n- Run `cargo fmt` and `cargo clippy` before committing\n- Handle errors explicitly (avoid unwrap in production)\n- Use descriptive names, add doc comments for public APIs\n\n**TypeScript/React:**\n\n- Strict TypeScript, avoid `any` types\n- Functional components with hooks\n- Tailwind CSS for styling\n- Path aliases: `@/` → `./src/`\n\n## CLI Parameters\n\nHandy supports command-line parameters on all platforms for integration with scripts, window managers, and autostart configurations.\n\n**Implementation:** `cli.rs` (definitions), `main.rs` (parsing), `lib.rs` (applying), `signal_handle.rs` (shared logic)\n\n| Flag                     | Description                                                |\n| ------------------------ | ---------------------------------------------------------- |\n| `--toggle-transcription` | Toggle recording on/off on a running instance              |\n| `--toggle-post-process`  | Toggle recording with post-processing on/off               |\n| `--cancel`               | Cancel the current operation on a running instance         |\n| `--start-hidden`         | Launch without showing the main window (tray icon visible) |\n| `--no-tray`              | Launch without system tray (closing window quits the app)  |\n| `--debug`                | Enable debug mode with verbose (Trace) logging             |\n\n**Key design decisions:**\n\n- CLI flags are runtime-only overrides — they do NOT modify persisted settings\n- Remote control flags work via `tauri_plugin_single_instance`: second instance sends args, then exits\n- `send_transcription_input()` in `signal_handle.rs` is shared between signal handlers and CLI\n\n## Debug Mode\n\nAccess debug features: `Cmd+Shift+D` (macOS) or `Ctrl+Shift+D` (Windows/Linux)\n\n## Platform Notes\n\n- **macOS**: Metal acceleration, accessibility permissions required for keyboard shortcuts\n- **Windows**: Vulkan acceleration, code signing\n- **Linux**: OpenBLAS + Vulkan, limited Wayland support, overlay uses GTK layer shell (disable with `HANDY_NO_GTK_LAYER_SHELL=1`)\n\n## Troubleshooting\n\nSee the [Troubleshooting](README.md#troubleshooting) section in README.md.\n\n## GitHub workflow for AI coding assistants\n\n**MANDATORY. Before opening any PR, issue, or discussion in this repo: you MUST read the relevant template file and follow it strictly.** That includes sections that look \"ceremonial\" — checklists, AI Assistance disclosures, \"Human Written Description\". A generic Summary/Test-plan layout is not acceptable.\n\n- **Opening a PR:** Read [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md). Every section listed there is mandatory. If a section requires a human-written paragraph (e.g. \"Human Written Description\"), leave a clear TODO placeholder and ask the human contributor to fill it in — do not invent their voice.\n- **Opening an issue:** Read [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/). Blank issues are disabled; pick the right template (`bug_report.md` for bugs). Feature requests do not belong in issues — they go to [Discussions](https://github.com/cjpais/Handy/discussions) (see `.github/ISSUE_TEMPLATE/config.yml`).\n- **Proposing a feature:** Handy is under a feature freeze. New features require community support gathered in [Discussions](https://github.com/cjpais/Handy/discussions) before any PR is opened — see the PR template's \"Community Feedback\" section.\n- **Translations:** Follow [CONTRIBUTING_TRANSLATIONS.md](CONTRIBUTING_TRANSLATIONS.md).\n- **Full contributor workflow:** [CONTRIBUTING.md](CONTRIBUTING.md).\n\n**Commits:** Use conventional commit prefixes (`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`). Focus the message on _why_, not _what_.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThis file provides guidance to AI coding assistants working with code in this repository.\n\n## Development Commands\n\n**Prerequisites:**\n\n- [Rust](https://rustup.rs/) (latest stable)\n- [Bun](https://bun.sh/) package manager\n\n**Core Development:**\n\n```bash\n# Install dependencies\nbun install\n\n# Run in development mode\nbun run tauri dev\n# If cmake error on macOS:\nCMAKE_POLICY_VERSION_MINIMUM=3.5 bun run tauri dev\n\n# Build for production\nbun run tauri build\n\n# Frontend only development\nbun run dev        # Start Vite dev server\nbun run build      # Build frontend (TypeScript + Vite)\nbun run preview    # Preview built frontend\n```\n\n**Linting and Formatting (run before committing):**\n\n```bash\nbun run lint              # ESLint for frontend\nbun run lint:fix          # ESLint with auto-fix\nbun run format            # Prettier + cargo fmt\nbun run format:check      # Check formatting without changes\nbun run format:frontend   # Prettier only\nbun run format:backend    # cargo fmt only\n```\n\n**Model Setup (Required for Development):**\n\n```bash\nmkdir -p src-tauri/resources/models\ncurl -o src-tauri/resources/models/silero_vad_v4.onnx https://blob.handy.computer/silero_vad_v4.onnx\n```\n\nFor detailed platform-specific build setup, see [BUILD.md](BUILD.md).\n\n## Architecture Overview\n\nHandy is a cross-platform desktop speech-to-text application built with Tauri 2.x (Rust backend + React/TypeScript frontend).\n\n### Backend Structure (src-tauri/src/)\n\n- `lib.rs` - Main entry point, Tauri setup, manager initialization\n- `managers/` - Core business logic:\n  - `audio.rs` - Audio recording and device management\n  - `model.rs` - Model downloading and management\n  - `transcription.rs` - Speech-to-text processing pipeline\n  - `history.rs` - Transcription history storage\n- `audio_toolkit/` - Low-level audio processing:\n  - `audio/` - Device enumeration, recording, resampling\n  - `vad/` - Voice Activity Detection (Silero VAD)\n- `commands/` - Tauri command handlers for frontend communication\n- `cli.rs` - CLI argument definitions (clap derive)\n- `shortcut.rs` - Global keyboard shortcut handling\n- `settings.rs` - Application settings management\n- `overlay.rs` - Recording overlay window (platform-specific)\n- `signal_handle.rs` - `send_transcription_input()` reusable function\n- `utils.rs` - Platform detection helpers\n\n### Frontend Structure (src/)\n\n- `App.tsx` - Main component with onboarding flow\n- `components/` - React UI components:\n  - `settings/` - Settings UI\n  - `model-selector/` - Model management interface\n  - `onboarding/` - First-run experience\n  - `overlay/` - Recording overlay UI\n  - `update-checker/` - App update notifications\n  - `shared/`, `ui/`, `icons/`, `footer/` - Shared components\n- `hooks/useSettings.ts` - Settings state management hook\n- `stores/settingsStore.ts` - Zustand store for settings\n- `bindings.ts` - Auto-generated Tauri type bindings (via tauri-specta)\n- `overlay/` - Recording overlay window entry point\n- `lib/types.ts` - Shared TypeScript type definitions\n\n### Key Architecture Patterns\n\n**Manager Pattern:** Core functionality organized into managers (Audio, Model, Transcription) initialized at startup and managed via Tauri state.\n\n**Command-Event Architecture:** Frontend → Backend via Tauri commands; Backend → Frontend via events.\n\n**Pipeline Processing:** Audio → VAD → Whisper/Parakeet → Text output → Clipboard/Paste\n\n**State Flow:** Zustand → Tauri Command → Rust State → Persistence (tauri-plugin-store)\n\n### Technology Stack\n\n**Core Libraries:**\n\n- `transcribe-cpp` - Local Whisper-family inference (GGML/GGUF) with GPU acceleration\n- `transcribe-rs` - ONNX speech recognition (Parakeet, Moonshine, SenseVoice, etc.)\n- `cpal` - Cross-platform audio I/O\n- `vad-rs` - Voice Activity Detection\n- `rdev` - Global keyboard shortcuts\n- `rubato` - Audio resampling\n- `rodio` - Audio playback for feedback sounds\n\n### Application Flow\n\n1. **Initialization:** App starts minimized to tray, loads settings, initializes managers\n2. **Model Setup:** First-run downloads preferred Whisper model (Small/Medium/Turbo/Large)\n3. **Recording:** Global shortcut triggers audio recording with VAD filtering\n4. **Processing:** Audio sent to Whisper model for transcription\n5. **Output:** Text pasted to active application via system clipboard\n\n### Settings System\n\nSettings are stored using Tauri's store plugin with reactive updates:\n\n- Keyboard shortcuts (configurable, supports push-to-talk)\n- Audio devices (microphone/output selection)\n- Model preferences (Small/Medium/Turbo/Large Whisper variants)\n- Audio feedback and translation options\n\n### Single Instance Architecture\n\nThe app enforces single instance behavior — launching when already running brings the settings window to front rather than creating a new process. Remote control flags (`--toggle-transcription`, etc.) work by launching a second instance that sends args to the running instance via `tauri_plugin_single_instance`, then exits.\n\n## Internationalization (i18n)\n\nAll user-facing strings must use i18next translations. ESLint enforces this (no hardcoded strings in JSX).\n\n**Adding new text:**\n\n1. Add key to `src/i18n/locales/en/translation.json`\n2. Use in component: `const { t } = useTranslation(); t('key.path')`\n\n**File structure:**\n\n```\nsrc/i18n/\n├── index.ts           # i18n setup\n├── languages.ts       # Language metadata\n└── locales/\n    ├── en/translation.json  # English (source)\n    ├── de/, es/, fr/, ja/, ru/, zh/, ...\n    └── ...\n```\n\nFor translation contribution guidelines, see [CONTRIBUTING_TRANSLATIONS.md](CONTRIBUTING_TRANSLATIONS.md).\n\n## Code Style\n\n**Rust:**\n\n- Run `cargo fmt` and `cargo clippy` before committing\n- Handle errors explicitly (avoid unwrap in production)\n- Use descriptive names, add doc comments for public APIs\n\n**TypeScript/React:**\n\n- Strict TypeScript, avoid `any` types\n- Functional components with hooks\n- Tailwind CSS for styling\n- Path aliases: `@/` → `./src/`\n\n## CLI Parameters\n\nHandy supports command-line parameters on all platforms for integration with scripts, window managers, and autostart configurations.\n\n**Implementation:** `cli.rs` (definitions), `main.rs` (parsing), `lib.rs` (applying), `signal_handle.rs` (shared logic)\n\n| Flag                     | Description                                                |\n| ------------------------ | ---------------------------------------------------------- |\n| `--toggle-transcription` | Toggle recording on/off on a running instance              |\n| `--toggle-post-process`  | Toggle recording with post-processing on/off               |\n| `--cancel`               | Cancel the current operation on a running instance         |\n| `--start-hidden`         | Launch without showing the main window (tray icon visible) |\n| `--no-tray`              | Launch without system tray (closing window quits the app)  |\n| `--debug`                | Enable debug mode with verbose (Trace) logging             |\n\n**Key design decisions:**\n\n- CLI flags are runtime-only overrides — they do NOT modify persisted settings\n- Remote control flags work via `tauri_plugin_single_instance`: second instance sends args, then exits\n- `send_transcription_input()` in `signal_handle.rs` is shared between signal handlers and CLI\n\n## Debug Mode\n\nAccess debug features: `Cmd+Shift+D` (macOS) or `Ctrl+Shift+D` (Windows/Linux)\n\n## Platform Notes\n\n- **macOS**: Metal acceleration, accessibility permissions required for keyboard shortcuts\n- **Windows**: Vulkan acceleration, code signing\n- **Linux**: OpenBLAS + Vulkan, limited Wayland support, overlay uses GTK layer shell (disable with `HANDY_NO_GTK_LAYER_SHELL=1`)\n\n## Troubleshooting\n\nSee the [Troubleshooting](README.md#troubleshooting) section in README.md.\n\n## GitHub workflow for AI coding assistants\n\n**MANDATORY. Before opening any PR, issue, or discussion in this repo: you MUST read the relevant template file and follow it strictly.** That includes sections that look \"ceremonial\" — checklists, AI Assistance disclosures, \"Human Written Description\". A generic Summary/Test-plan layout is not acceptable.\n\n- **Opening a PR:** Read [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md). Every section listed there is mandatory. If a section requires a human-written paragraph (e.g. \"Human Written Description\"), leave a clear TODO placeholder and ask the human contributor to fill it in — do not invent their voice.\n- **Opening an issue:** Read [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/). Blank issues are disabled; pick the right template (`bug_report.md` for bugs). Feature requests do not belong in issues — they go to [Discussions](https://github.com/cjpais/Handy/discussions) (see `.github/ISSUE_TEMPLATE/config.yml`).\n- **Proposing a feature:** Handy is under a feature freeze. New features require community support gathered in [Discussions](https://github.com/cjpais/Handy/discussions) before any PR is opened — see the PR template's \"Community Feedback\" section.\n- **Translations:** Follow [CONTRIBUTING_TRANSLATIONS.md](CONTRIBUTING_TRANSLATIONS.md).\n- **Full contributor workflow:** [CONTRIBUTING.md](CONTRIBUTING.md).\n\n**Commits:** Use conventional commit prefixes (`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`). Focus the message on _why_, not _what_.\n","category":"root","tokens":2316}]}