---
name: commands/mod.rs — module roots and prompt builder
type: architecture-map-page
slice: 02-tauri-runtime
last_verified: 2026/05/09
---

# `commands::mod`

> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → mod.rs

**Plain English summary.** `mod.rs` declares all 25 child modules (22 command modules, 3 utility modules) and exports one shared helper: `build_initial_prompt`. The helper is the precedence rule that decides what the Whisper `initial_prompt` actually is when a command receives caller-supplied prompt text plus a profile prompt plus a list of profile vocabulary terms.

## At a glance

- Path: `src-tauri/src/commands/mod.rs`.
- LOC: 114 (60 of those are tests).
- Tauri commands exposed: none.
- Events emitted: none.
- Depends on: nothing crate-external.
- Called from: `commands::transcription` (whisper PCM path and file path), `commands::live::start_live_transcription_session`. Both call `build_initial_prompt(&request_prompt, &profile.initial_prompt, &profile_terms)` to assemble the final Whisper prompt before passing it into `TranscriptionOptions`.

## What's in here

### Module declarations (`src-tauri/src/commands/mod.rs:1`)

```
audio, clipboard, diagnostics, feedback, fs, hardware,
hotkey, intentions, live, llm, meeting, models,
mod (this file), nudges, paste, power, profiles,
rituals, security, tasks, transcription, transcripts,
tts, update, windows
```

All declared `pub mod`, so any sibling module can `use crate::commands::name`.

### `build_initial_prompt(request_prompt, profile_prompt, profile_terms) -> Option<String>` (`src-tauri/src/commands/mod.rs:39`)

Precedence:

1. Caller-supplied `request_prompt` wins outright when non-empty (the caller has already made the decision).
2. Else: profile's stored prompt + profile terms (joined as `"<profile prompt> Vocabulary: term1, term2."`). The vocabulary line is the OpenWhispr pattern: feeding domain terms into Whisper's `initial_prompt` biases the decoder toward the correct spelling at decode time, before any LLM cleanup pass.
3. Else: profile prompt alone, or `"Vocabulary: term1, term2."` alone if only terms are present.
4. Else: `None`.

Whitespace-only terms are skipped. Whitespace-only prompts are treated as empty. The returned `Option<String>` is what every Whisper-side command stuffs into `TranscriptionOptions::initial_prompt`.

### Tests (`src-tauri/src/commands/mod.rs:65`)

Six test cases cover each branch of the precedence rule plus whitespace handling. These are pure-function tests, no DB.

## Data flow

The helper is called *after* the calling command has read the relevant `ProfileRow` and `ProfileTermRow`s from `magnotia_storage`. The DB I/O lives in the calling command (so the tests in this file stay pure).

## Watch-outs

- The helper does not de-duplicate terms. If the same term appears twice in `profile_terms`, it lands twice in the vocabulary sentence. The storage layer's `add_profile_term` is what enforces uniqueness, but if the terms list ever comes from somewhere else, dedup at the call site.
- Vocabulary length is not capped here. A profile with hundreds of terms will produce a very long `initial_prompt`, and Whisper has a context-window limit that depends on the model. If you ever ship a UI that lets users add unlimited terms, add a cap in the calling commands or here.
- The whisper.cpp `initial_prompt` is best-effort only. It biases decoding but does not guarantee a particular word will be produced. Profile-edit-derived corrections (`commands::profiles::learn_profile_terms_from_edit_cmd`) feed back into this path on the next session.

## See also

- [Profiles](profiles.md) — `learn_profile_terms_from_edit_cmd` is what populates the `profile_terms` list this helper consumes.
- [Transcription](transcription.md) — both whisper paths call this helper.
- [Live transcription](live.md) — `start_live_transcription_session` calls this helper once at startup and stashes the result on the config struct.
- [Commands index](README.md) — back to the index.