From cdef2163c1948f613a9d03347e91a9061a69b7d6 Mon Sep 17 00:00:00 2001
From: pandego <7780875+pandego@users.noreply.github.com>
Date: Thu, 12 Mar 2026 12:17:50 +0100
Subject: [PATCH 1/2] docs: align local API port examples with current dev flow

---
 CONTRIBUTING.md         |  2 +-
 README.md               | 11 +++++++----
 backend/README.md       | 21 ++++++++++++---------
 docs/TROUBLESHOOTING.md |  6 +++---
 scripts/generate-api.sh | 10 +++++-----
 5 files changed, 28 insertions(+), 22 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 765da827..bc3552b8 100644
--- a/CONTRIBUTING.md
+++ b/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?
 
diff --git a/README.md b/README.md
index f0ea11f8..3274db6a 100644
--- a/README.md
+++ b/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.
 
 ---
 
diff --git a/backend/README.md b/backend/README.md
index 57163467..88f872b1 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -334,18 +334,21 @@ 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"
 ```
@@ -353,7 +356,7 @@ curl -X POST http://localhost:8000/profiles/abc-123/samples \
 ### 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
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 6f0317a0..78749f96 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -162,7 +162,7 @@ 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**
@@ -170,7 +170,7 @@ chmod +x voicebox-*.AppImage
    - 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**
diff --git a/scripts/generate-api.sh b/scripts/generate-api.sh
index f2f057e5..b6239981 100755
--- a/scripts/generate-api.sh
+++ b/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

From 3d2506767d73acbf3c3cabb45ad270255ecf3a30 Mon Sep 17 00:00:00 2001
From: pandego <7780875+pandego@users.noreply.github.com>
Date: Fri, 13 Mar 2026 05:08:25 +0100
Subject: [PATCH 2/2] docs: address review nits for API generator

---
 CHANGELOG.md            | 1 +
 scripts/generate-api.sh | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b7116d39..141977c9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -55,6 +55,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 - Audio export failing when Tauri save dialog returns object instead of string path
+- OpenAPI client generator script now documents the local backend port and avoids an unused loop variable warning
 
 ### Added
 - **Makefile** - Comprehensive development workflow automation with commands for setup, development, building, testing, and code quality checks
diff --git a/scripts/generate-api.sh b/scripts/generate-api.sh
index b6239981..c2de5293 100755
--- a/scripts/generate-api.sh
+++ b/scripts/generate-api.sh
@@ -26,12 +26,12 @@ if ! curl -s http://localhost:17493/openapi.json > /dev/null 2>&1; then
     
     # Start backend in background
     echo "Starting backend server..."
-    uvicorn main:app --port 17493 &
+    uvicorn main:app --port 17493 &  # Keep the generator on the app's documented local backend port.
     BACKEND_PID=$!
     
     # Wait for server to be ready
     echo "Waiting for server to start..."
-    for i in {1..30}; do
+    for _ in {1..30}; do
         if curl -s http://localhost:17493/openapi.json > /dev/null 2>&1; then
             break
         fi