Update files

packages/website/src/routeTree.gen.ts

@@ -13,6 +13,7 @@ import { Route as DocsRouteImport } from './routes/docs'
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as DocsIndexRouteImport } from './routes/docs/index'
 import { Route as DocsWorktreesRouteImport } from './routes/docs/worktrees'
+import { Route as DocsVoiceRouteImport } from './routes/docs/voice'
 import { Route as DocsSecurityRouteImport } from './routes/docs/security'
 import { Route as DocsConfigurationRouteImport } from './routes/docs/configuration'
 import { Route as DocsCliRouteImport } from './routes/docs/cli'
@@ -38,6 +39,11 @@ const DocsWorktreesRoute = DocsWorktreesRouteImport.update({
   path: '/worktrees',
   getParentRoute: () => DocsRoute,
 } as any)
+const DocsVoiceRoute = DocsVoiceRouteImport.update({
+  id: '/voice',
+  path: '/voice',
+  getParentRoute: () => DocsRoute,
+} as any)
 const DocsSecurityRoute = DocsSecurityRouteImport.update({
   id: '/security',
   path: '/security',
@@ -66,6 +72,7 @@ export interface FileRoutesByFullPath {
   '/docs/cli': typeof DocsCliRoute
   '/docs/configuration': typeof DocsConfigurationRoute
   '/docs/security': typeof DocsSecurityRoute
+  '/docs/voice': typeof DocsVoiceRoute
   '/docs/worktrees': typeof DocsWorktreesRoute
   '/docs/': typeof DocsIndexRoute
 }
@@ -75,6 +82,7 @@ export interface FileRoutesByTo {
   '/docs/cli': typeof DocsCliRoute
   '/docs/configuration': typeof DocsConfigurationRoute
   '/docs/security': typeof DocsSecurityRoute
+  '/docs/voice': typeof DocsVoiceRoute
   '/docs/worktrees': typeof DocsWorktreesRoute
   '/docs': typeof DocsIndexRoute
 }
@@ -86,6 +94,7 @@ export interface FileRoutesById {
   '/docs/cli': typeof DocsCliRoute
   '/docs/configuration': typeof DocsConfigurationRoute
   '/docs/security': typeof DocsSecurityRoute
+  '/docs/voice': typeof DocsVoiceRoute
   '/docs/worktrees': typeof DocsWorktreesRoute
   '/docs/': typeof DocsIndexRoute
 }
@@ -98,6 +107,7 @@ export interface FileRouteTypes {
     | '/docs/cli'
     | '/docs/configuration'
     | '/docs/security'
+    | '/docs/voice'
     | '/docs/worktrees'
     | '/docs/'
   fileRoutesByTo: FileRoutesByTo
@@ -107,6 +117,7 @@ export interface FileRouteTypes {
     | '/docs/cli'
     | '/docs/configuration'
     | '/docs/security'
+    | '/docs/voice'
     | '/docs/worktrees'
     | '/docs'
   id:
@@ -117,6 +128,7 @@ export interface FileRouteTypes {
     | '/docs/cli'
     | '/docs/configuration'
     | '/docs/security'
+    | '/docs/voice'
     | '/docs/worktrees'
     | '/docs/'
   fileRoutesById: FileRoutesById
@@ -156,6 +168,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof DocsWorktreesRouteImport
       parentRoute: typeof DocsRoute
     }
+    '/docs/voice': {
+      id: '/docs/voice'
+      path: '/voice'
+      fullPath: '/docs/voice'
+      preLoaderRoute: typeof DocsVoiceRouteImport
+      parentRoute: typeof DocsRoute
+    }
     '/docs/security': {
       id: '/docs/security'
       path: '/security'
@@ -192,6 +211,7 @@ interface DocsRouteChildren {
   DocsCliRoute: typeof DocsCliRoute
   DocsConfigurationRoute: typeof DocsConfigurationRoute
   DocsSecurityRoute: typeof DocsSecurityRoute
+  DocsVoiceRoute: typeof DocsVoiceRoute
   DocsWorktreesRoute: typeof DocsWorktreesRoute
   DocsIndexRoute: typeof DocsIndexRoute
 }
@@ -201,6 +221,7 @@ const DocsRouteChildren: DocsRouteChildren = {
   DocsCliRoute: DocsCliRoute,
   DocsConfigurationRoute: DocsConfigurationRoute,
   DocsSecurityRoute: DocsSecurityRoute,
+  DocsVoiceRoute: DocsVoiceRoute,
   DocsWorktreesRoute: DocsWorktreesRoute,
   DocsIndexRoute: DocsIndexRoute,
 }

packages/website/src/routes/docs.tsx

@@ -7,6 +7,7 @@ export const Route = createFileRoute('/docs')({
 
 const navigation = [
   { name: 'Getting started', href: '/docs' },
+  { name: 'Voice', href: '/docs/voice' },
   { name: 'Git worktrees', href: '/docs/worktrees' },
   { name: 'CLI', href: '/docs/cli' },
   { name: 'Configuration', href: '/docs/configuration' },

packages/website/src/routes/docs/configuration.tsx

@@ -81,75 +81,13 @@ function Configuration() {
       <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": {
-      "llm": { "provider": "claude", "model": "haiku" },
-      "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">
-          Voice LLM orchestration is agents-only. Set{' '}
-          <code className="font-mono">features.voiceMode.llm.provider</code> to one of{' '}
-          <code className="font-mono">claude</code>, <code className="font-mono">codex</code>, or{' '}
-          <code className="font-mono">opencode</code>. If set, startup is strict and fails if unavailable.
-          If omitted, Paseo picks the first available voice-enabled agent provider.
+          Voice is configured through <code className="font-mono">features.dictation</code> and{' '}
+          <code className="font-mono">features.voiceMode</code>, with provider credentials under{' '}
+          <code className="font-mono">providers</code>.
         </p>
         <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.
+          For voice philosophy, architecture, and complete local/OpenAI setup examples, see{' '}
+          <a href="/docs/voice" className="underline hover:text-white/80">Voice docs</a>.
         </p>
       </section>
 
@@ -162,8 +100,10 @@ function Configuration() {
           <li><code className="font-mono">OPENAI_API_KEY</code> — override OpenAI provider key</li>
           <li><code className="font-mono">PASEO_VOICE_LLM_PROVIDER</code> — override voice LLM provider (<code className="font-mono">claude</code>, <code className="font-mono">codex</code>, <code className="font-mono">opencode</code>)</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>
+          <li><code className="font-mono">PASEO_LOCAL_MODELS_DIR</code> and <code className="font-mono">PASEO_LOCAL_AUTO_DOWNLOAD</code> — control local model directory and download behavior</li>
+          <li><code className="font-mono">PASEO_DICTATION_LOCAL_STT_MODEL</code> — override local dictation STT model</li>
+          <li><code className="font-mono">PASEO_VOICE_LOCAL_STT_MODEL</code>, <code className="font-mono">PASEO_VOICE_LOCAL_TTS_MODEL</code> — override local voice STT/TTS models</li>
+          <li><code className="font-mono">PASEO_VOICE_LOCAL_TTS_SPEAKER_ID</code>, <code className="font-mono">PASEO_VOICE_LOCAL_TTS_SPEED</code> — optional local voice TTS tuning</li>
         </ul>
       </section>
 

packages/website/src/routes/docs/index.tsx

@@ -87,22 +87,25 @@ function GettingStarted() {
       <section className="space-y-4">
         <h2 className="text-xl font-medium">Voice Setup</h2>
         <p className="text-white/60">
-          Voice supports two providers: local (default) and OpenAI. Local uses ONNX models and will
-          download missing model files automatically at daemon startup.
+          Paseo includes first-class voice support with a local-first architecture and configurable speech
+          providers.
         </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">
-          Set <code className="font-mono">OPENAI_API_KEY</code> if you want OpenAI speech providers.
-          For local defaults and model presets, see Configuration.
+          For architecture, local model behavior, and provider configuration, see the Voice docs page.
         </p>
+        <a href="/docs/voice" className="underline hover:text-white/80">
+          Voice docs
+        </a>
       </section>
 
       <section className="space-y-4">
         <h2 className="text-xl font-medium">Next</h2>
         <ul className="text-white/60 space-y-2 list-disc list-inside">
+          <li>
+            <a href="/docs/voice" className="underline hover:text-white/80">
+              Voice
+            </a>
+          </li>
           <li>
             <a href="/docs/configuration" className="underline hover:text-white/80">
               Configuration

packages/website/src/routes/docs/voice.tsx

@@ -0,0 +1,126 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/docs/voice')({
+  head: () => ({
+    meta: [
+      { title: 'Voice - Paseo Docs' },
+      {
+        name: 'description',
+        content: 'Paseo voice architecture, local-first model execution, and provider configuration.',
+      },
+    ],
+  }),
+  component: VoiceDocs,
+})
+
+function VoiceDocs() {
+  return (
+    <div className="space-y-8">
+      <div>
+        <h1 className="text-3xl font-medium font-title mb-4">Voice</h1>
+        <p className="text-white/60 leading-relaxed">
+          Paseo has first-class voice support for dictation and realtime conversations with your coding
+          environment.
+        </p>
+      </div>
+
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Philosophy</h2>
+        <p className="text-white/60 leading-relaxed">
+          Voice is local-first. You can run speech fully on-device, or choose OpenAI for speech features.
+          For voice reasoning/orchestration, Paseo reuses agent providers already installed and authenticated
+          on your machine.
+        </p>
+        <p className="text-white/60 leading-relaxed">
+          This keeps credentials and execution in your environment and avoids introducing a separate
+          cloud-only voice stack.
+        </p>
+      </section>
+
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Architecture</h2>
+        <ul className="text-white/60 space-y-2 list-disc list-inside">
+          <li>Speech I/O: STT and TTS providers per feature (<code className="font-mono">local</code> or <code className="font-mono">openai</code>)</li>
+          <li>Local speech runtime: ONNX models executed on CPU by default</li>
+          <li>Voice LLM orchestration: hidden agent session using your configured provider (<code className="font-mono">claude</code>, <code className="font-mono">codex</code>, or <code className="font-mono">opencode</code>)</li>
+          <li>Tooling path: MCP stdio bridge for voice tools and agent control</li>
+        </ul>
+      </section>
+
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Local Speech</h2>
+        <p className="text-white/60 leading-relaxed">
+          Local speech defaults to model IDs <code className="font-mono">parakeet-tdt-0.6b-v3-int8</code>{' '}
+          (STT) and <code className="font-mono">pocket-tts-onnx-int8</code> (TTS).
+        </p>
+        <p className="text-white/60 leading-relaxed">
+          Missing models are downloaded at daemon startup into{' '}
+          <code className="font-mono">$PASEO_HOME/models/local-speech</code> when auto-download is enabled.
+          Downloads happen only for missing files.
+        </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", "model": "parakeet-tdt-0.6b-v3-int8" } },
+    "voiceMode": {
+      "llm": { "provider": "claude", "model": "haiku" },
+      "stt": { "provider": "local", "model": "parakeet-tdt-0.6b-v3-int8" },
+      "tts": { "provider": "local", "model": "pocket-tts-onnx-int8" }
+    }
+  },
+  "providers": {
+    "local": {
+      "modelsDir": "~/.paseo/models/local-speech",
+      "autoDownload": true
+    }
+  }
+}`}
+        </pre>
+      </section>
+
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">OpenAI Speech Option</h2>
+        <p className="text-white/60 leading-relaxed">
+          You can switch dictation, voice STT, and voice TTS to OpenAI by setting provider fields to{' '}
+          <code className="font-mono">openai</code> and providing <code className="font-mono">OPENAI_API_KEY</code>.
+        </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>
+      </section>
+
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Environment Variables</h2>
+        <ul className="text-white/60 space-y-2 list-disc list-inside">
+          <li><code className="font-mono">OPENAI_API_KEY</code> — OpenAI speech credentials</li>
+          <li><code className="font-mono">PASEO_VOICE_LLM_PROVIDER</code> — voice agent provider override</li>
+          <li><code className="font-mono">PASEO_LOCAL_MODELS_DIR</code>, <code className="font-mono">PASEO_LOCAL_AUTO_DOWNLOAD</code> — local model storage and download policy</li>
+          <li><code className="font-mono">PASEO_DICTATION_LOCAL_STT_MODEL</code> — local dictation STT model ID</li>
+          <li><code className="font-mono">PASEO_VOICE_LOCAL_STT_MODEL</code>, <code className="font-mono">PASEO_VOICE_LOCAL_TTS_MODEL</code> — local voice STT/TTS model IDs</li>
+          <li><code className="font-mono">PASEO_VOICE_LOCAL_TTS_SPEAKER_ID</code>, <code className="font-mono">PASEO_VOICE_LOCAL_TTS_SPEED</code> — optional local voice TTS tuning</li>
+        </ul>
+      </section>
+
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Operational Notes</h2>
+        <p className="text-white/60 leading-relaxed">
+          Realtime voice can launch and control agents. Treat voice prompts with the same care as direct
+          agent instructions, especially when specifying working directories or destructive operations.
+        </p>
+      </section>
+    </div>
+  )
+}