docs: align local API port examples with current dev flow

CONTRIBUTING.md

@@ -407,7 +407,7 @@ See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for common issues and sol
 
 - **Backend won't start:** Check Python version (3.11+), ensure venv is activated, install dependencies
 - **Tauri build fails:** Ensure Rust is installed, clean build with `cd tauri/src-tauri && cargo clean`
-- **OpenAPI client generation fails:** Ensure backend is running, check `curl http://localhost:8000/openapi.json`
+- **OpenAPI client generation fails:** Ensure backend is running, check `curl http://localhost:17493/openapi.json`
 
 ## Questions?
 

README.md

@@ -147,17 +147,20 @@ Create multi-voice narratives, podcasts, and conversations with a timeline-based
 
 Voicebox exposes a full REST API, so you can integrate voice synthesis into your own apps.
 
+For the current local app and development workflow, the backend is typically available at `http://localhost:17493`.
+If you launch the backend manually with a different host or port, use that address instead.
+
 ```bash
 # Generate speech
-curl -X POST http://localhost:8000/generate \
+curl -X POST http://localhost:17493/generate \
   -H "Content-Type: application/json" \
   -d '{"text": "Hello world", "profile_id": "abc123", "language": "en"}'
 
 # List voice profiles
-curl http://localhost:8000/profiles
+curl http://localhost:17493/profiles
 
 # Create a profile
-curl -X POST http://localhost:8000/profiles \
+curl -X POST http://localhost:17493/profiles \
   -H "Content-Type: application/json" \
   -d '{"name": "My Voice", "language": "en"}'
 ```
@@ -170,7 +173,7 @@ curl -X POST http://localhost:8000/profiles \
 - Voice assistants
 - Content creation automation
 
-Full API documentation available at `http://localhost:8000/docs` when running.
+Full API documentation is available at `http://localhost:17493/docs` in the default local workflow, or at `/docs` on whatever server address you configured.
 
 ---
 

backend/README.md

@@ -334,26 +334,29 @@ python -m backend.main --host 0.0.0.0 --port 8000
 
 ## Usage Examples
 
+The desktop app, web client, and current development workflow use `http://localhost:17493` by default.
+If you launch the backend manually with a different host or port, substitute that address in the examples below.
+
 ### Creating a Voice Profile
 
 ```bash
 # 1. Create profile
-curl -X POST http://localhost:8000/profiles \
+curl -X POST http://localhost:17493/profiles \
   -H "Content-Type: application/json" \
   -d '{"name": "My Voice", "language": "en"}'
 
 # Response: {"id": "abc-123", ...}
 
 # 2. Add sample
-curl -X POST http://localhost:8000/profiles/abc-123/samples \
+curl -X POST http://localhost:17493/profiles/abc-123/samples \
   -F "file=@sample.wav" \
   -F "reference_text=This is my voice sample"
 ```
 
 ### Generating Speech
 
 ```bash
-curl -X POST http://localhost:8000/generate \
+curl -X POST http://localhost:17493/generate \
   -H "Content-Type: application/json" \
   -d '{
     "profile_id": "abc-123",
@@ -365,13 +368,13 @@ curl -X POST http://localhost:8000/generate \
 # Response: {"id": "gen-456", "audio_path": "/path/to/audio.wav", ...}
 
 # Download audio
-curl http://localhost:8000/audio/gen-456 -o output.wav
+curl http://localhost:17493/audio/gen-456 -o output.wav
 ```
 
 ### Transcribing Audio
 
 ```bash
-curl -X POST http://localhost:8000/transcribe \
+curl -X POST http://localhost:17493/transcribe \
   -F "file=@audio.wav" \
   -F "language=en"
 
@@ -386,12 +389,12 @@ Add multiple samples to a profile for better quality:
 
 ```bash
 # Add first sample
-curl -X POST http://localhost:8000/profiles/abc-123/samples \
+curl -X POST http://localhost:17493/profiles/abc-123/samples \
   -F "file=@sample1.wav" \
   -F "reference_text=First sample"
 
 # Add second sample
-curl -X POST http://localhost:8000/profiles/abc-123/samples \
+curl -X POST http://localhost:17493/profiles/abc-123/samples \
   -F "file=@sample2.wav" \
   -F "reference_text=Second sample"
 
@@ -412,10 +415,10 @@ Models are lazy-loaded and can be manually unloaded:
 
 ```bash
 # Unload TTS model
-curl -X POST http://localhost:8000/models/unload
+curl -X POST http://localhost:17493/models/unload
 
 # Load specific model size
-curl -X POST "http://localhost:8000/models/load?model_size=0.6B"
+curl -X POST "http://localhost:17493/models/load?model_size=0.6B"
 ```
 
 ## Error Handling

docs/TROUBLESHOOTING.md

@@ -162,15 +162,15 @@ chmod +x voicebox-*.AppImage
 **Solutions:**
 1. **Check server is running**
    ```bash
-   curl http://localhost:8000/health
+   curl http://localhost:17493/health
    ```
 
 2. **Check remote mode**
    - If connecting remotely, ensure server is started with `--host 0.0.0.0`
    - Check firewall settings
 
 3. **Check port availability**
-   - Default port is 8000
+   - The current local app and dev workflow uses port 17493 by default
    - Ensure no other service is using it
 
 ### CORS errors in browser
@@ -276,7 +276,7 @@ chmod +x voicebox-*.AppImage
 
 2. **Check OpenAPI endpoint**
    ```bash
-   curl http://localhost:8000/openapi.json
+   curl http://localhost:17493/openapi.json
    ```
 
 3. **Regenerate client**

scripts/generate-api.sh

@@ -6,7 +6,7 @@ set -e
 echo "Generating OpenAPI client..."
 
 # Check if backend is running
-if ! curl -s http://localhost:8000/openapi.json > /dev/null 2>&1; then
+if ! curl -s http://localhost:17493/openapi.json > /dev/null 2>&1; then
     echo "Backend not running. Starting backend..."
     cd backend
 
@@ -26,19 +26,19 @@ if ! curl -s http://localhost:8000/openapi.json > /dev/null 2>&1; then
 
     # Start backend in background
     echo "Starting backend server..."
-    uvicorn main:app --port 8000 &
+    uvicorn main:app --port 17493 &
     BACKEND_PID=$!
 
     # Wait for server to be ready
     echo "Waiting for server to start..."
     for i in {1..30}; do
-        if curl -s http://localhost:8000/openapi.json > /dev/null 2>&1; then
+        if curl -s http://localhost:17493/openapi.json > /dev/null 2>&1; then
             break
         fi
         sleep 1
     done
 
-    if ! curl -s http://localhost:8000/openapi.json > /dev/null 2>&1; then
+    if ! curl -s http://localhost:17493/openapi.json > /dev/null 2>&1; then
         echo "Error: Backend failed to start"
         kill $BACKEND_PID 2>/dev/null || true
         exit 1
@@ -52,7 +52,7 @@ fi
 
 # Download OpenAPI schema
 echo "Downloading OpenAPI schema..."
-curl -s http://localhost:8000/openapi.json > app/openapi.json
+curl -s http://localhost:17493/openapi.json > app/openapi.json
 
 # Check if openapi-typescript-codegen is installed
 if ! bunx --bun openapi-typescript-codegen --version > /dev/null 2>&1; then