From 9f5b1ec087144da7bde537d152a985354dc5eae5 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Fri, 6 Feb 2026 18:03:44 +0700
Subject: [PATCH] docs: document voice provider configuration and local
 defaults

---
 .../website/src/routes/docs/configuration.tsx | 71 ++++++++++++++++++-
 packages/website/src/routes/docs/index.tsx    |  6 +-
 2 files changed, 74 insertions(+), 3 deletions(-)

diff --git a/packages/website/src/routes/docs/configuration.tsx b/packages/website/src/routes/docs/configuration.tsx
index fe7522fc9..96b671c60 100644
--- a/packages/website/src/routes/docs/configuration.tsx
+++ b/packages/website/src/routes/docs/configuration.tsx
@@ -79,6 +79,73 @@ function Configuration() {
         </pre>
       </section>
 
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Voice</h2>
+        <p className="text-white/60 leading-relaxed">
+          Voice is provider-based per feature: dictation STT, realtime voice STT, and voice TTS can each
+          use <code className="font-mono">local</code> or <code className="font-mono">openai</code>.
+          Defaults are local for all three.
+        </p>
+        <pre className="bg-card border border-border rounded-lg p-4 font-mono text-sm overflow-x-auto text-white/80">
+{`{
+  "version": 1,
+  "features": {
+    "dictation": { "stt": { "provider": "local" } },
+    "voiceMode": {
+      "stt": { "provider": "local" },
+      "tts": { "provider": "local" }
+    }
+  },
+  "providers": {
+    "sherpaOnnx": {
+      "modelsDir": "~/.paseo/models/sherpa-onnx",
+      "autoDownload": true,
+      "stt": { "preset": "parakeet-tdt-0.6b-v3-int8" },
+      "tts": { "preset": "pocket-tts-onnx-int8" }
+    }
+  }
+}`}
+        </pre>
+        <p className="text-white/60 leading-relaxed">
+          Local voice uses ONNX models (sherpa-onnx + PocketTTS). Default presets are
+          <code className="font-mono">parakeet-tdt-0.6b-v3-int8</code> for STT and
+          <code className="font-mono">pocket-tts-onnx-int8</code> for TTS.
+        </p>
+        <p className="text-white/60 leading-relaxed">
+          With local provider enabled and auto-download on (default outside tests), missing model files are
+          downloaded at daemon startup into <code className="font-mono">$PASEO_HOME/models/sherpa-onnx</code>.
+          Downloads are only performed for missing files.
+        </p>
+        <p className="text-white/60 leading-relaxed">
+          Local ONNX execution is CPU-first by default. It works without GPU requirements, but performance
+          depends on your machine.
+        </p>
+        <p className="text-white/60 leading-relaxed">
+          To force OpenAI for voice/dictation, configure OpenAI providers explicitly and provide
+          <code className="font-mono">OPENAI_API_KEY</code>. If OpenAI is selected but credentials are
+          missing, daemon startup fails fast.
+        </p>
+        <pre className="bg-card border border-border rounded-lg p-4 font-mono text-sm overflow-x-auto text-white/80">
+{`{
+  "version": 1,
+  "features": {
+    "dictation": { "stt": { "provider": "openai" } },
+    "voiceMode": {
+      "stt": { "provider": "openai" },
+      "tts": { "provider": "openai" }
+    }
+  },
+  "providers": {
+    "openai": { "apiKey": "..." }
+  }
+}`}
+        </pre>
+        <p className="text-white/60 leading-relaxed">
+          Realtime voice can create/manage coding agents. Use clear prompts and explicit paths, because
+          those agents can be launched in arbitrary working directories by request.
+        </p>
+      </section>
+
       <section className="space-y-4">
         <h2 className="text-xl font-medium">Common env vars</h2>
         <ul className="text-white/60 space-y-2 list-disc list-inside">
@@ -86,6 +153,9 @@ function Configuration() {
           <li><code className="font-mono">PASEO_LISTEN</code> — override <code className="font-mono">daemon.listen</code></li>
           <li><code className="font-mono">PASEO_ALLOWED_HOSTS</code> — override/extend <code className="font-mono">daemon.allowedHosts</code></li>
           <li><code className="font-mono">OPENAI_API_KEY</code> and <code className="font-mono">OPENROUTER_API_KEY</code> — override provider keys</li>
+          <li><code className="font-mono">PASEO_DICTATION_STT_PROVIDER</code>, <code className="font-mono">PASEO_VOICE_STT_PROVIDER</code>, <code className="font-mono">PASEO_VOICE_TTS_PROVIDER</code> — override voice provider selection (<code className="font-mono">local</code> or <code className="font-mono">openai</code>)</li>
+          <li><code className="font-mono">PASEO_SHERPA_ONNX_MODELS_DIR</code> and <code className="font-mono">PASEO_SHERPA_ONNX_AUTO_DOWNLOAD</code> — control local model directory and download behavior</li>
+          <li><code className="font-mono">PASEO_SHERPA_STT_PRESET</code> and <code className="font-mono">PASEO_SHERPA_TTS_PRESET</code> — override local STT/TTS model presets</li>
         </ul>
       </section>
 
@@ -101,4 +171,3 @@ function Configuration() {
     </div>
   )
 }
-
diff --git a/packages/website/src/routes/docs/index.tsx b/packages/website/src/routes/docs/index.tsx
index 0ba254e3c..afd9cbbd9 100644
--- a/packages/website/src/routes/docs/index.tsx
+++ b/packages/website/src/routes/docs/index.tsx
@@ -87,14 +87,16 @@ function GettingStarted() {
       <section className="space-y-4">
         <h2 className="text-xl font-medium">Voice Setup</h2>
         <p className="text-white/60">
-          Voice features currently require an OpenAI API key. Set it as an environment variable before running the server:
+          Voice supports two providers: local (default) and OpenAI. Local uses ONNX models and will
+          download missing model files automatically at daemon startup.
         </p>
         <div className="bg-card border border-border rounded-lg p-4 font-mono text-sm">
           <span className="text-muted-foreground select-none">$ </span>
           <span>export OPENAI_API_KEY=your-key-here</span>
         </div>
         <p className="text-white/60">
-          Local voice support is coming soon.
+          Set <code className="font-mono">OPENAI_API_KEY</code> if you want OpenAI speech providers.
+          For local defaults and model presets, see Configuration.
         </p>
       </section>