docs: snapshot v4.3.0

Restore PDF Text Highlights After Viewport Resize (Fixes #119)

.dockerignore

@@ -0,0 +1,8 @@
+.env
+.env.*
+**/*.creds
+README.md
+.next
+node_modules
+**/node_modules
+docstore

.env.example

@@ -1,98 +1,95 @@
 
+# Logging
+# pretty (default): human-readable logs
+# json: structured logs for log platforms
+# LOG_FORMAT=pretty
+# LOG_LEVEL=info
+
 # Local / OpenAI TTS API Configuration (default)
 # Suggest using https://github.com/remsky/Kokoro-FastAPI
 #
 # NOTE: On first boot, the server auto-seeds these values into a "default-openai"
 # admin-managed shared provider (DB-backed, encrypted at rest). After that, the
 # admin UI is authoritative and changing these env vars has no effect. You may
-# remove them once the seed has run. See Settings → Admin → Shared providers.
+# remove them once the seed has run. Auth must be configured for this seed path.
+# See Settings → Admin → Shared providers.
 API_BASE=http://localhost:8880/v1
-API_KEY=api_key_optional
+API_KEY=
 
-# (Optional) TTS request/cache tuning (leave unset to use defaults)
-# TTS_CACHE_MAX_SIZE_BYTES=268435456   # 256MB
-# TTS_CACHE_TTL_MS=1800000             # 30 minutes
-# TTS_MAX_RETRIES=2
-# TTS_RETRY_INITIAL_MS=250
-# TTS_RETRY_MAX_MS=2000
-# TTS_RETRY_BACKOFF=2
-# TTS_UPSTREAM_TIMEOUT_MS=285000       # 285 seconds
-
-# (Optional) Enable TTS character rate limiting (default is `false`)
-# TTS_ENABLE_RATE_LIMIT=true
-# (Optional) TTS per-user daily limits (leave unset to use defaults)
-# TTS_DAILY_LIMIT_ANONYMOUS=50000
-# TTS_DAILY_LIMIT_AUTHENTICATED=500000
-# (Optional) TTS IP backstop daily limits (leave unset to use defaults)
-# TTS_IP_DAILY_LIMIT_ANONYMOUS=100000
-# TTS_IP_DAILY_LIMIT_AUTHENTICATED=1000000
-
-# Auth configuration (recommended for contributors and public instances)
-# (Optional) Auth is only enabled when AUTH_SECRET and BASE_URL are set
+# Auth configuration (required in v4+)
 BASE_URL=http://localhost:3003 # Externally facing URL for this app (set to LAN IP for access from other devices on the network)
-AUTH_SECRET=some_random_secret_key # Generate with `openssl rand -hex 32`
+AUTH_SECRET=some_random_secret_key # Generate with `openssl rand -base64 32`
 AUTH_TRUSTED_ORIGINS=http://localhost:3003,http://127.0.0.1:3003 # Additional trusted origins (BASE_URL is always trusted)
-# (Optional) Allow anonymous auth sessions when auth is enabled (default: `false`)
-USE_ANONYMOUS_AUTH_SESSIONS=
+# (Optional) Allow anonymous auth sessions (default: `false`)
+# USE_ANONYMOUS_AUTH_SESSIONS=false
 # (Optional) Sign in w/ GitHub Configuration
-GITHUB_CLIENT_ID=
-GITHUB_CLIENT_SECRET=
-# (Optional) Disable Better Auth built-in rate limiting (useful for testing)
-DISABLE_AUTH_RATE_LIMIT=
+# GITHUB_CLIENT_ID=
+# GITHUB_CLIENT_SECRET=
 
 # (Optional) Comma-separated list of emails that are auto-promoted to admin.
-# Admins see the "Admin" tab in Settings (TTS shared providers + site features).
-# Demotion is automatic: removing an email here demotes the user on next login.
-# Requires auth to be enabled (AUTH_SECRET + BASE_URL).
 ADMIN_EMAILS=
 
-# (Optional) Backend DB used for server-side metadata (documents/audiobooks) and, when auth is enabled, auth tables.
+# (Required for the Vercel scheduled-task cron route; Vercel sends it as a bearer token.)
+# Self-hosted deployments run scheduled tasks in-process and do not require this.
+# CRON_SECRET=
+
+# (Optional) Backend DB used for server-side metadata (documents/audiobooks) and auth tables.
 # Defaults to SQLite at docstore/sqlite3.db when not set.
-POSTGRES_URL=
+# POSTGRES_URL=
 
 # Embedded SeaweedFS weed mini config
-# (Optional) Enable embedded weed mini for local S3-compatible storage (default: `true`)
-USE_EMBEDDED_WEED_MINI=
-WEED_MINI_DIR=
-WEED_MINI_WAIT_SEC=
+# (Optional) Enable embedded weed mini for local S3-compatible storage (defaults shown below)
+# USE_EMBEDDED_WEED_MINI=true
+# WEED_MINI_DIR=docstore/seaweedfs
+# WEED_MINI_WAIT_SEC=20
 
 # S3 storage config (use with embedded weed mini or external S3-compatible storage)
 # (Optional) For embedded weed mini, set explicit keys if you want stable credentials across restarts.
 S3_ACCESS_KEY_ID=
 S3_SECRET_ACCESS_KEY=
 S3_BUCKET=
-S3_REGION=
+# S3_REGION=
 # (Optional) If empty in embedded mode, OpenReader uses BASE_URL host (when set) or detected LAN host.
-S3_ENDPOINT=
-S3_FORCE_PATH_STYLE=
-S3_PREFIX=
+# S3_ENDPOINT=
+# S3_FORCE_PATH_STYLE=
+# S3_PREFIX=
+
+# (Optional) Library import mode directory (uses /docstore/library by default)
+# IMPORT_LIBRARY_DIR=
+# IMPORT_LIBRARY_DIRS=
+
+# Compute worker configuration
+# (Optional) Embedded compute worker (automatic startup) for local compute tasks (defaults shown below)
+# EMBEDDED_COMPUTE_WORKER_PORT=8081
+# EMBEDDED_NATS_PORT=4222
+# EMBEDDED_NATS_MONITOR_PORT=8222
+# EMBEDDED_NATS_STORE_DIR=docstore/nats/jetstream
+# NATS_URL=nats://127.0.0.1:4222
+# COMPUTE_LOG_LEVEL=info
+# COMPUTE_JOB_CONCURRENCY=1
+# COMPUTE_WHISPER_TIMEOUT_MS=30000
+# COMPUTE_PDF_TIMEOUT_MS=300000
+# COMPUTE_PDF_JOB_ATTEMPTS=1
+# COMPUTE_OP_STALE_MS=1800000
+# WHISPER_MODEL_BASE_URL=https://huggingface.co/onnx-community/whisper-base_timestamped/resolve/main
+# PDF_LAYOUT_MODEL_BASE_URL=https://huggingface.co/Bei0001/PP-DocLayoutV3-ONNX/resolve/main
+# (Optional) External compute worker config (see docs/deploy/compute-worker)
+# COMPUTE_WORKER_URL=http://localhost:8081
+# COMPUTE_WORKER_TOKEN=local-compute-token
+
+# (Optional) Override ffmpeg binary path used for audio processing
+# FFMPEG_BIN=
+
+# (Optional) Test/dev overrides
+# DISABLE_AUTH_RATE_LIMIT=false
+# ENABLE_TEST_NAMESPACE=false
 
-# Migrations configuration
 # (Optional) Skip automatic startup migrations when set to `false` (default: `true`)
-RUN_DRIZZLE_MIGRATIONS=
+# RUN_DRIZZLE_MIGRATIONS=true
 # (Optional) Skip automatic filesystem->S3/DB migration pass when set to `false` (default: `true`)
-RUN_FS_MIGRATIONS=
+# RUN_FS_MIGRATIONS=true
 
-# (Optional) Server library import roots (uses /docstore/library by default)
-IMPORT_LIBRARY_DIR=
-IMPORT_LIBRARY_DIRS=
-
-# (Required without Docker) Path to your local whisper.cpp CLI binary for STT timestamp generation
-WHISPER_CPP_BIN=/whisper.cpp/build/bin/whisper-cli
-
-# (Optional) Override ffmpeg binary path used for audiobook processing
-FFMPEG_BIN=
-
-# (Optional) Client feature flags — seeded into the admin-managed runtime
-# config on first boot, then ignored. Edit values from Settings → Admin →
-# Site features instead of redeploying. SSR-injected so they take effect
-# without rebuilding (unlike the old NEXT_PUBLIC_* build-time pattern).
-# NEXT_PUBLIC_ENABLE_DOCX_CONVERSION=true
-# NEXT_PUBLIC_ENABLE_DESTRUCTIVE_DELETE_ACTIONS=true
-# NEXT_PUBLIC_ENABLE_TTS_PROVIDERS_TAB=true
-# NEXT_PUBLIC_ENABLE_USER_SIGNUPS=true
-# NEXT_PUBLIC_RESTRICT_USER_API_KEYS=true
-# NEXT_PUBLIC_DEFAULT_TTS_PROVIDER=custom-openai
-# NEXT_PUBLIC_CHANGELOG_FEED_URL=https://docs.openreader.richardr.dev/changelog/manifest.json
-# NEXT_PUBLIC_ENABLE_AUDIOBOOK_EXPORT=true
-# NEXT_PUBLIC_ENABLE_WORD_HIGHLIGHT=true
+# (Optional) v4 JSON seed for first-boot runtime config + shared providers.
+# If both are set, RUNTIME_SEED_JSON_PATH is used.
+# RUNTIME_SEED_JSON_PATH=/absolute/path/to/openreader-seed.json
+# RUNTIME_SEED_JSON={"version":1,"runtimeConfig":{"enableUserSignups":true,"restrictUserApiKeys":true,"defaultTtsProvider":"custom-openai","enableTtsProvidersTab":true,"enableAudiobookExport":true,"enableDocxConversion":true,"showAllProviderModels":true,"disableTtsRateLimit":true,"ttsDailyLimitAnonymous":50000,"ttsDailyLimitAuthenticated":500000,"ttsIpDailyLimitAnonymous":100000,"ttsIpDailyLimitAuthenticated":1000000,"ttsCacheMaxSizeBytes":268435456,"ttsCacheTtlMs":1800000,"ttsUpstreamMaxRetries":2,"ttsUpstreamTimeoutMs":285000,"disableComputeRateLimit":true,"computeParseBurstMax":8,"computeParseBurstWindowSec":60,"computeParseSustainedMax":24,"computeParseSustainedWindowSec":600,"maxUploadMb":200,"changelogFeedUrl":"https://docs.openreader.richardr.dev/changelog/manifest.json"},"providers":[{"slug":"default-openai","displayName":"Default (seeded)","providerType":"custom-openai","baseUrl":"http://localhost:8880/v1","defaultModel":"kokoro","enabled":true}]}

.github/workflows/docker-publish.yml

@@ -22,30 +22,17 @@ jobs:
   prepare:
     runs-on: ubuntu-24.04
     outputs:
-      image_name: ${{ steps.image-name.outputs.image_name }}
-      legacy_image_name: ${{ steps.image-name.outputs.legacy_image_name }}
-      tags: ${{ steps.meta.outputs.tags }}
-      labels: ${{ steps.meta.outputs.labels }}
+      web_image_name: ${{ steps.image-name.outputs.web_image_name }}
+      web_legacy_image_name: ${{ steps.image-name.outputs.web_legacy_image_name }}
+      compute_worker_image_name: ${{ steps.image-name.outputs.compute_worker_image_name }}
     steps:
       - name: Compute Docker image names
         id: image-name
         run: |
           owner="${GITHUB_REPOSITORY_OWNER,,}"
-          echo "image_name=${owner}/openreader" >> "$GITHUB_OUTPUT"
-          echo "legacy_image_name=${owner}/openreader-webui" >> "$GITHUB_OUTPUT"
-
-      - name: Extract metadata (tags, labels) for Docker
-        id: meta
-        uses: docker/metadata-action@v6
-        with:
-          images: |
-            ${{ env.REGISTRY }}/${{ steps.image-name.outputs.image_name }}
-            ${{ env.REGISTRY }}/${{ steps.image-name.outputs.legacy_image_name }}
-          tags: |
-            type=raw,value=latest,enable=${{ (github.event_name == 'push' && !contains(github.ref, '-pre')) || (github.event_name == 'workflow_dispatch' && inputs.use_latest_tag == true) }},priority=1000
-            type=semver,pattern={{version}}
-            type=ref,event=tag
-            type=ref,event=branch,enable=${{ github.event_name == 'workflow_dispatch' && inputs.use_latest_tag != true }}
+          echo "web_image_name=${owner}/openreader" >> "$GITHUB_OUTPUT"
+          echo "web_legacy_image_name=${owner}/openreader-webui" >> "$GITHUB_OUTPUT"
+          echo "compute_worker_image_name=${owner}/openreader-compute-worker" >> "$GITHUB_OUTPUT"
 
   build:
     needs: prepare
@@ -58,12 +45,30 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - arch: amd64
+          - image_target: web
+            arch: amd64
             platform: linux/amd64
             runner: ubuntu-24.04
-          - arch: arm64
+            context: .
+            dockerfile: ./Dockerfile
+          - image_target: web
+            arch: arm64
             platform: linux/arm64
             runner: ubuntu-24.04-arm
+            context: .
+            dockerfile: ./Dockerfile
+          - image_target: compute-worker
+            arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-24.04
+            context: .
+            dockerfile: ./packages/compute-worker/Dockerfile
+          - image_target: compute-worker
+            arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            context: .
+            dockerfile: ./packages/compute-worker/Dockerfile
 
     steps:
       - name: Checkout repository
@@ -82,46 +87,63 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Build and push Docker image (${{ matrix.arch }})
+      - name: Select image name
+        id: image
+        run: |
+          if [ "${{ matrix.image_target }}" = "web" ]; then
+            echo "image_name=${{ needs.prepare.outputs.web_image_name }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "image_name=${{ needs.prepare.outputs.compute_worker_image_name }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and push Docker image (${{ matrix.image_target }} / ${{ matrix.arch }})
         id: build
         uses: docker/build-push-action@v7
         with:
-          context: .
+          context: ${{ matrix.context }}
+          file: ${{ matrix.dockerfile }}
           platforms: ${{ matrix.platform }}
-          labels: ${{ needs.prepare.outputs.labels }}
-          cache-from: type=gha,scope=${{ matrix.arch }}
-          cache-to: type=gha,mode=max,scope=${{ matrix.arch }}
+          cache-from: type=gha,scope=${{ matrix.image_target }}-${{ matrix.arch }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.image_target }}-${{ matrix.arch }}
           provenance: false
-          outputs: type=image,name=${{ env.REGISTRY }}/${{ needs.prepare.outputs.image_name }},push-by-digest=true,name-canonical=true,push=true
+          outputs: type=image,name=${{ env.REGISTRY }}/${{ steps.image.outputs.image_name }},push-by-digest=true,name-canonical=true,push=true
 
       - name: Export digest
         run: |
-          mkdir -p /tmp/digests
+          mkdir -p /tmp/digests/${{ matrix.image_target }}
           digest="${{ steps.build.outputs.digest }}"
-          touch "/tmp/digests/${digest#sha256:}"
+          touch "/tmp/digests/${{ matrix.image_target }}/${digest#sha256:}"
 
       - name: Upload digest
         uses: actions/upload-artifact@v7
         with:
-          name: digests-${{ matrix.arch }}
-          path: /tmp/digests
+          name: digests-${{ matrix.image_target }}-${{ matrix.arch }}
+          path: /tmp/digests/${{ matrix.image_target }}
           if-no-files-found: error
           retention-days: 1
 
   merge:
     needs: [prepare, build]
-    runs-on: ubuntu-24.04
+    runs-on: ${{ matrix.runner }}
     permissions:
       actions: read
       contents: read
       packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image_target: web
+            runner: ubuntu-24.04
+          - image_target: compute-worker
+            runner: ubuntu-24.04
 
     steps:
       - name: Download digests
         uses: actions/download-artifact@v8
         with:
-          path: /tmp/digests
-          pattern: digests-*
+          path: /tmp/digests/${{ matrix.image_target }}
+          pattern: digests-${{ matrix.image_target }}-*
           merge-multiple: true
 
       - name: Set up Docker Buildx
@@ -134,20 +156,46 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Select image names
+        id: image
+        run: |
+          if [ "${{ matrix.image_target }}" = "web" ]; then
+            echo "image_name=${{ needs.prepare.outputs.web_image_name }}" >> "$GITHUB_OUTPUT"
+            echo "metadata_images<<EOF" >> "$GITHUB_OUTPUT"
+            echo "${{ env.REGISTRY }}/${{ needs.prepare.outputs.web_image_name }}" >> "$GITHUB_OUTPUT"
+            echo "${{ env.REGISTRY }}/${{ needs.prepare.outputs.web_legacy_image_name }}" >> "$GITHUB_OUTPUT"
+            echo "EOF" >> "$GITHUB_OUTPUT"
+          else
+            echo "image_name=${{ needs.prepare.outputs.compute_worker_image_name }}" >> "$GITHUB_OUTPUT"
+            echo "metadata_images=${{ env.REGISTRY }}/${{ needs.prepare.outputs.compute_worker_image_name }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ steps.image.outputs.metadata_images }}
+          tags: |
+            type=raw,value=latest,enable=${{ (github.event_name == 'push' && !contains(github.ref, '-pre')) || (github.event_name == 'workflow_dispatch' && inputs.use_latest_tag == true) }},priority=1000
+            type=semver,pattern={{version}}
+            type=ref,event=tag
+            type=ref,event=branch,enable=${{ github.event_name == 'workflow_dispatch' && inputs.use_latest_tag != true }}
+
       - name: Create manifest list and push
-        working-directory: /tmp/digests
+        working-directory: /tmp/digests/${{ matrix.image_target }}
         run: |
           docker buildx imagetools create \
             $(echo "$TAGS" | xargs -I {} echo -t {}) \
-            $(printf '${{ env.REGISTRY }}/${{ needs.prepare.outputs.image_name }}@sha256:%s ' *)
+            $(printf '${{ env.REGISTRY }}/${{ steps.image.outputs.image_name }}@sha256:%s ' *)
         env:
-          TAGS: ${{ needs.prepare.outputs.tags }}
+          TAGS: ${{ steps.meta.outputs.tags }}
 
       - name: Output build information
         run: |
-          echo "✅ Docker images built and pushed successfully!"
+          echo "✅ Docker image built and pushed successfully!"
+          echo "🐋 Target: ${{ matrix.image_target }}"
           echo "🐋 Images:"
-          echo '${{ needs.prepare.outputs.tags }}' | sed 's/^/  - /'
+          echo '${{ steps.meta.outputs.tags }}' | sed 's/^/  - /'
           echo "📝 Event: ${{ github.event_name }}"
           if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
             echo "📝 Triggered by manual workflow dispatch on branch: ${{ github.ref_name }}"

.github/workflows/docs-deploy-on-release.yml

@@ -0,0 +1,34 @@
+name: Docs Deploy On Release
+
+on:
+  release:
+    types: [published, edited, deleted]
+
+permissions:
+  actions: write
+  contents: read
+
+concurrency:
+  group: docs-release-relay-${{ github.event.release.tag_name }}
+  cancel-in-progress: true
+
+jobs:
+  relay:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch Docs Deploy on main
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ github.event.release.tag_name }}
+          ACTION: ${{ github.event.action }}
+        run: |
+          set -euo pipefail
+          gh api \
+            -X POST \
+            -H "Accept: application/vnd.github+json" \
+            "repos/${REPO}/actions/workflows/docs-deploy.yml/dispatches" \
+            -f ref=main \
+            -f "inputs[full_reconcile]=false" \
+            -f "inputs[release_tag]=${TAG}" \
+            -f "inputs[release_action]=${ACTION}"

.github/workflows/docs-deploy.yml

@@ -3,11 +3,6 @@ name: Docs Deploy
 on:
   push:
     branches: [main]
-  release:
-    types: [published, edited, deleted]
-  workflow_run:
-    workflows: ["Version Docs on Tag"]
-    types: [completed]
   workflow_dispatch:
     inputs:
       full_reconcile:
@@ -15,6 +10,14 @@ on:
         required: false
         default: false
         type: boolean
+      release_tag:
+        description: 'Optional release tag for incremental changelog sync (for release relay)'
+        required: false
+        type: string
+      release_action:
+        description: 'Optional release action (published, edited, deleted) for incremental sync'
+        required: false
+        type: string
 
 permissions:
   contents: read
@@ -27,7 +30,6 @@ concurrency:
 
 jobs:
   build:
-    if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/playwright.yml

@@ -7,12 +7,14 @@ on:
 
 jobs:
   e2e-testing:
-    timeout-minutes: 60
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     env:
-      FFMPEG_BIN: /usr/bin/ffmpeg
       USE_EMBEDDED_WEED_MINI: true
+      ENABLE_TEST_NAMESPACE: true
       BASE_URL: http://127.0.0.1:3003
+      AUTH_SECRET: ci-auth-secret-change-me
+      USE_ANONYMOUS_AUTH_SESSIONS: true
       S3_ENDPOINT: http://127.0.0.1:8333
     steps:
     - uses: actions/checkout@v5
@@ -34,8 +36,19 @@ jobs:
         sudo install -m 0755 ./weed /usr/local/bin/weed
         rm -f ./weed
         weed version
+    - name: Install NATS server binary
+      run: |
+        curl -fsSL -o /tmp/nats-server.tar.gz \
+          https://github.com/nats-io/nats-server/releases/download/v2.12.1/nats-server-v2.12.1-linux-amd64.tar.gz
+        tar -xzf /tmp/nats-server.tar.gz -C /tmp
+        sudo install -m 0755 /tmp/nats-server-v2.12.1-linux-amd64/nats-server /usr/local/bin/nats-server
+        nats-server -v
     - name: Install dependencies
       run: pnpm install --frozen-lockfile
+    - name: Build app and enforce bundle guard
+      run: |
+        pnpm build
+        pnpm build:bundle-guard
     - name: Verify ffprobe
       run: ffprobe -version
     - name: Install Playwright Browsers
@@ -44,10 +57,12 @@ jobs:
       env:
         API_BASE: https://api.deepinfra.com/v1/openai
         API_KEY: ${{ secrets.DEEPINFRA_API_KEY }}
-      run: pnpm exec playwright test --reporter=list,github,html
+      run: pnpm exec playwright test --max-failures=5 --reporter=list,github,html
     - uses: actions/upload-artifact@v7
-      if: ${{ !cancelled() }}
+      if: ${{ always() }}
       with:
         name: playwright-report
-        path: playwright-report/
+        path: |
+          playwright-report/
+          tests/results/
         retention-days: 30

.github/workflows/vitest.yml

@@ -0,0 +1,29 @@
+name: Vitest Tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  vitest-testing:
+    timeout-minutes: 20
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v5
+        with:
+          node-version: lts/*
+          package-manager-cache: false
+      - uses: pnpm/action-setup@v6
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Apply drizzle migrations (SQLite)
+        run: pnpm migrate
+      - name: Run Vitest suites
+        run: pnpm test:unit
+      - name: Verify compute worker contract and boundary
+        run: pnpm compute:openapi:check && pnpm check:compute-boundary

.gitignore

@@ -32,8 +32,9 @@ yarn-error.log*
 .pnpm-debug.log*
 
 # env files (can opt-in for committing if needed)
-.env
-.dockerignore
+.env*
+!.env.example
+*.creds
 
 # vercel
 .vercel
@@ -55,5 +56,7 @@ node_modules/
 # vscode
 .vscode
 
-# .agents
+# Agents
 .agents
+.codex
+.claude

Dockerfile

@@ -1,36 +1,28 @@
-# Stage 1: build whisper.cpp (no model download – the app handles that)
-FROM alpine:3.23 AS whisper-builder
-
-RUN apk add --no-cache git cmake build-base
-
-WORKDIR /opt
-
-ARG TARGETARCH
-
-RUN git clone --depth 1 https://github.com/ggml-org/whisper.cpp.git && \
-    cd whisper.cpp && \
-    cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DGGML_NATIVE=OFF $( [ "$TARGETARCH" = "arm64" ] && echo "-DGGML_CPU_ARM_ARCH=armv8-a" || true ) && \
-    cmake --build build -j
-
-# Stage 1b: extract seaweedfs weed binary (for optional embedded weed mini)
+# Stage 1: extract seaweedfs weed binary (for optional embedded weed mini)
 # Pin to 4.18 because CI observed upload regressions on 4.19.
 FROM chrislusf/seaweedfs:4.18 AS seaweedfs-builder
 RUN cp "$(command -v weed)" /tmp/weed && \
     (wget -qO /tmp/SeaweedFS-LICENSE.txt "https://raw.githubusercontent.com/seaweedfs/seaweedfs/master/LICENSE" || \
      wget -qO /tmp/SeaweedFS-LICENSE.txt "https://raw.githubusercontent.com/seaweedfs/seaweedfs/main/LICENSE")
 
+# Stage 1b: extract nats-server binary for embedded single-container worker mode.
+FROM nats:2.11-alpine AS nats-builder
+RUN cp "$(command -v nats-server)" /tmp/nats-server
 
 # Stage 2: build the Next.js app
-FROM node:lts-alpine AS app-builder
+FROM node:lts-slim AS app-builder
 
 # Install pnpm globally
-RUN npm install -g pnpm@11.1.2
+RUN npm install -g pnpm@10.33.4
 
 # Create app directory
 WORKDIR /app
 
-# Copy package files
+# Copy workspace manifests needed for dependency installation
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY packages/bootstrap/package.json ./packages/bootstrap/package.json
+COPY packages/compute-worker/package.json ./packages/compute-worker/package.json
+COPY packages/database/package.json ./packages/database/package.json
 
 # Install dependencies
 RUN pnpm install --frozen-lockfile
@@ -40,7 +32,10 @@ COPY . .
 
 # Build the Next.js application
 RUN pnpm exec next telemetry disable
-RUN pnpm build
+RUN AUTH_SECRET=build-placeholder-secret-value-32chars!! BASE_URL=http://localhost:3003 pnpm build
+RUN pnpm --config.inject-workspace-packages=true --filter @openreader/bootstrap deploy /opt/openreader/bootstrap
+RUN pnpm --dir /opt/openreader/bootstrap rebuild better-sqlite3 ffmpeg-static
+RUN pnpm --config.inject-workspace-packages=true --filter @openreader/compute-worker deploy /opt/openreader/embedded-compute-worker
 # Generate third-party dependency license report plus copied license files.
 RUN mkdir -p /app/THIRD_PARTY_LICENSES && \
     pnpm dlx license-checker-rseidelsohn@4.3.0 \
@@ -52,40 +47,50 @@ RUN mkdir -p /app/THIRD_PARTY_LICENSES && \
 
 
 # Stage 3: minimal runtime image
-FROM node:lts-alpine AS runner
+FROM node:lts-slim AS runner
 
 # Add runtime OS dependencies:
 # - libreoffice-writer: required for DOCX → PDF conversion
 # ffmpeg is provided by ffmpeg-static from node_modules.
-RUN apk add --no-cache ca-certificates libreoffice-writer
-
-# Install pnpm globally for running the app
-RUN npm install -g pnpm@11.1.2
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates libreoffice-writer && \
+    rm -rf /var/lib/apt/lists/*
 
 # App runtime directory
 WORKDIR /app
 
-# Copy built app and dependencies from the builder stage
-COPY --from=app-builder /app ./
+# Copy only the standalone Next runtime and assets.
+COPY --from=app-builder /app/.next/standalone ./
+COPY --from=app-builder /app/.next/static ./.next/static
+COPY --from=app-builder /app/public ./public
+
+# Ship startup orchestration and the embedded worker as independent deployed bundles.
+COPY --from=app-builder /opt/openreader/bootstrap /opt/openreader/bootstrap
+COPY --from=app-builder /opt/openreader/embedded-compute-worker /opt/openreader/embedded-compute-worker
 # Include third-party license report and copied license texts at a stable path in the image.
 COPY --from=app-builder /app/THIRD_PARTY_LICENSES /licenses
 # Include SeaweedFS license text for the copied weed binary.
 COPY --from=seaweedfs-builder /tmp/SeaweedFS-LICENSE.txt /licenses/SeaweedFS-LICENSE.txt
+# Include static model notices for runtime-downloaded assets.
+COPY --from=app-builder /app/packages/compute-worker/src/inference/pdf/assets/LICENSE.txt /licenses/pp-doclayoutv3-LICENSE.txt
 
-# Copy the compiled whisper.cpp build output into the runtime image
-# (includes whisper-cli and its shared libraries, e.g. libwhisper.so, libggml.so)
-COPY --from=whisper-builder /opt/whisper.cpp/build /opt/whisper.cpp/build
 # Copy seaweedfs weed binary for optional embedded local S3.
 COPY --from=seaweedfs-builder /tmp/weed /usr/local/bin/weed
 RUN chmod +x /usr/local/bin/weed
+# Copy nats-server binary for embedded local JetStream.
+COPY --from=nats-builder /tmp/nats-server /usr/local/bin/nats-server
+RUN chmod +x /usr/local/bin/nats-server
 
-# Point the app at the compiled whisper-cli binary and ensure its libs are discoverable
-ENV WHISPER_CPP_BIN=/opt/whisper.cpp/build/bin/whisper-cli
-ENV LD_LIBRARY_PATH=/opt/whisper.cpp/build
+# Include OpenAI Whisper license text for runtime-downloaded ONNX artifacts.
+COPY --from=app-builder /app/packages/compute-worker/src/inference/whisper/assets/LICENSE.txt /licenses/openai-whisper-LICENSE.txt
+
+# Match the app's historical container port now that standalone server.js
+# is started directly instead of `next start -p 3003`.
+ENV PORT=3003
 
 # Expose the port the app runs on
 EXPOSE 3003
 
 # Start the application
-ENTRYPOINT ["node", "scripts/openreader-entrypoint.mjs", "--"]
-CMD ["pnpm", "start:raw"]
+ENTRYPOINT ["node", "/opt/openreader/bootstrap/src/cli.mjs", "--"]
+CMD ["node", "server.js"]

README.md

@@ -10,7 +10,7 @@
 
 # 📄🔊 OpenReader
 
-OpenReader is an open source, self-host-friendly text-to-speech document reader built with Next.js for **EPUB, PDF, TXT, MD, and DOCX** with synchronized read-along playback.
+OpenReader is an open-source, self-host-friendly text-to-speech document reader built with Next.js for **EPUB, PDF, TXT, MD, and DOCX** with multilingual, synchronized read-along playback.
 
 > Previously named **OpenReader-WebUI**.
 
@@ -18,13 +18,14 @@ OpenReader is an open source, self-host-friendly text-to-speech document reader
 
 ## ✨ Highlights
 
-- 🎯 **Multi-provider TTS** with OpenAI-compatible endpoints and cloud providers (Kokoro-FastAPI, KittenTTS-FastAPI, Orpheus-FastAPI or OpenAI, Replicate, DeepInfra).
-- 📖 **Read-along playback** for PDF/EPUB with sentence-aware narration.
-- ⏱️ **Word-by-word highlighting** via optional `whisper.cpp` timestamps.
-- 🛜 **Sync + library import** to bring docs across devices and from server-mounted folders.
-- 🗂️ **Flexible storage** with embedded SeaweedFS or external S3-compatible backends.
+- 🧱 **Layout-aware PDF parsing** with PP-DocLayoutV3 (ONNX) — structured block detection, cross-page stitching, and geometry-based highlighting for precise read-along sync.
+- ⏱️ **Word-by-word highlighting** via ONNX Whisper alignment through the compute worker control plane (NATS JetStream-backed).
+- ⚡ **Segment-based read-along** for EPUB, PDF, TXT, MD, and DOCX — sentence-aware TTS with cached audio segments, background preloading, and resumable playback.
+- 🎯 **Multi-provider TTS** — self-hosted OpenAI-compatible servers (Kokoro-FastAPI, KittenTTS-FastAPI, Orpheus-FastAPI) or cloud APIs (OpenAI, Replicate, DeepInfra).
+- 🌐 **Multilingual support** — choose a document language for language-aware narration and highlighting. Available languages depend on the configured TTS provider and voice.
 - 🎧 **Audiobook export** in `m4b`/`mp3` with resumable chapter processing.
-- 🐳 **Self-host friendly** with Docker, optional auth, and automatic startup migrations.
+- 🗂️ **Flexible backend** — embedded SeaweedFS or S3-compatible storage, SQLite or Postgres, server library import, and device sync.
+- 🐳 **Self-host friendly** — Docker (amd64/arm64), built-in auth/session support, and automatic startup migrations.
 
 ## 🚀 Start Here
 
@@ -32,6 +33,7 @@ OpenReader is an open source, self-host-friendly text-to-speech document reader
 | --- | --- |
 | Run with Docker | [Docker Quick Start](https://docs.openreader.richardr.dev/docker-quick-start) |
 | Deploy on Vercel | [Vercel Deployment](https://docs.openreader.richardr.dev/deploy/vercel-deployment) |
+| Deploy external compute worker | [Compute Worker (NATS JetStream)](https://docs.openreader.richardr.dev/deploy/compute-worker) |
 | Develop locally | [Local Development](https://docs.openreader.richardr.dev/deploy/local-development) |
 | Configure auth | [Auth](https://docs.openreader.richardr.dev/configure/auth) |
 | Configure SQL database | [Database and Migrations](https://docs.openreader.richardr.dev/configure/database) |

docker/examples/compose.full.yml

@@ -0,0 +1,124 @@
+name: openreader-full
+
+services:
+  openreader:
+    image: ghcr.io/richardr1126/openreader:latest
+    # Keep localhost:8333 valid for both app requests and browser-facing presigned URLs.
+    network_mode: service:seaweedfs
+    depends_on:
+      kokoro-tts:
+        condition: service_started
+      postgres:
+        condition: service_healthy
+      seaweedfs:
+        condition: service_healthy
+    environment:
+      BASE_URL: ${BASE_URL:-http://localhost:3003}
+      AUTH_SECRET: ${AUTH_SECRET:-local-openreader-auth-secret-change-me}
+      POSTGRES_URL: postgres://openreader:openreader@postgres:5432/openreader
+      COMPUTE_WORKER_URL: http://compute-worker:8081
+      COMPUTE_WORKER_TOKEN: ${COMPUTE_WORKER_TOKEN:-local-compute-token}
+      USE_EMBEDDED_WEED_MINI: "false"
+      S3_ENDPOINT: ${S3_ENDPOINT:-http://localhost:8333} # Used for internal endpoint and public facing presigned URLs.
+      S3_BUCKET: ${S3_BUCKET:-openreader-documents}
+      S3_REGION: ${S3_REGION:-us-east-1}
+      S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-devkey}
+      S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-devsecret}
+      S3_FORCE_PATH_STYLE: "true"
+      S3_PREFIX: ${S3_PREFIX:-openreader}
+      RUNTIME_SEED_JSON: |-
+        {
+          "version": 1,
+          "runtimeConfig": {
+            "defaultTtsProvider": "kokoro"
+          },
+          "providers": [
+            {
+              "slug": "kokoro",
+              "displayName": "Kokoro",
+              "providerType": "custom-openai",
+              "baseUrl": "http://kokoro-tts:8880/v1",
+              "defaultModel": "kokoro",
+              "enabled": true
+            }
+          ]
+        }
+    volumes:
+      - openreader-docstore:/app/docstore
+
+  kokoro-tts:
+    image: ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
+    environment:
+      ONNX_NUM_THREADS: 8
+      ONNX_INTER_OP_THREADS: 4
+      ONNX_EXECUTION_MODE: parallel
+      ONNX_OPTIMIZATION_LEVEL: all
+      ONNX_MEMORY_PATTERN: "true"
+      ONNX_ARENA_EXTEND_STRATEGY: kNextPowerOfTwo
+      API_LOG_LEVEL: DEBUG
+    ports:
+      - "8880:8880"
+
+  seaweedfs:
+    image: chrislusf/seaweedfs:4.18
+    command: ["mini", "-dir=/data"]
+    environment:
+      AWS_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-devkey}
+      AWS_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-devsecret}
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:9333/cluster/status >/dev/null"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+    ports:
+      - "3003:3003"
+      - "8333:8333"
+    volumes:
+      - seaweedfs-data:/data
+
+  nats:
+    image: nats:2.14-alpine
+    command: ["-js", "-sd", "/data"]
+    volumes:
+      - nats-data:/data
+
+  postgres:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_USER: openreader
+      POSTGRES_PASSWORD: openreader
+      POSTGRES_DB: openreader
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U openreader -d openreader"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  compute-worker:
+    image: ghcr.io/richardr1126/openreader-compute-worker:latest
+    depends_on:
+      nats:
+        condition: service_started
+      seaweedfs:
+        condition: service_healthy
+    environment:
+      NATS_URL: nats://nats:4222
+      COMPUTE_WORKER_HOST: 0.0.0.0
+      PORT: 8081
+      COMPUTE_WORKER_TOKEN: ${COMPUTE_WORKER_TOKEN:-local-compute-token}
+      S3_ENDPOINT: http://seaweedfs:8333
+      S3_BUCKET: ${S3_BUCKET:-openreader-documents}
+      S3_REGION: ${S3_REGION:-us-east-1}
+      S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-devkey}
+      S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-devsecret}
+      S3_FORCE_PATH_STYLE: "true"
+      S3_PREFIX: ${S3_PREFIX:-openreader}
+      COMPUTE_PREWARM_MODELS: ${COMPUTE_PREWARM_MODELS:-false}
+
+volumes:
+  openreader-docstore:
+  seaweedfs-data:
+  nats-data:
+  postgres-data:

docker/examples/compose.local-full.yml

@@ -0,0 +1,130 @@
+name: openreader-local-full-build
+
+services:
+  openreader:
+    image: openreader:local
+    build:
+      context: ../..
+      dockerfile: Dockerfile
+    # Keep localhost:8333 valid for both app requests and browser-facing presigned URLs.
+    network_mode: service:seaweedfs
+    depends_on:
+      kokoro-tts:
+        condition: service_started
+      postgres:
+        condition: service_healthy
+      seaweedfs:
+        condition: service_healthy
+    environment:
+      BASE_URL: ${BASE_URL:-http://localhost:3003}
+      AUTH_SECRET: ${AUTH_SECRET:-local-openreader-auth-secret-change-me}
+      POSTGRES_URL: postgres://openreader:openreader@postgres:5432/openreader
+      COMPUTE_WORKER_URL: http://compute-worker:8081
+      COMPUTE_WORKER_TOKEN: ${COMPUTE_WORKER_TOKEN:-local-compute-token}
+      USE_EMBEDDED_WEED_MINI: "false"
+      S3_ENDPOINT: ${S3_ENDPOINT:-http://localhost:8333} # Used for internal endpoint and public facing presigned URLs.
+      S3_BUCKET: ${S3_BUCKET:-openreader-documents}
+      S3_REGION: ${S3_REGION:-us-east-1}
+      S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-devkey}
+      S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-devsecret}
+      S3_FORCE_PATH_STYLE: "true"
+      S3_PREFIX: ${S3_PREFIX:-openreader}
+      RUNTIME_SEED_JSON: |-
+        {
+          "version": 1,
+          "runtimeConfig": {
+            "defaultTtsProvider": "kokoro"
+          },
+          "providers": [
+            {
+              "slug": "kokoro",
+              "displayName": "Kokoro",
+              "providerType": "custom-openai",
+              "baseUrl": "http://kokoro-tts:8880/v1",
+              "defaultModel": "kokoro",
+              "enabled": true
+            }
+          ]
+        }
+    volumes:
+      - openreader-docstore:/app/docstore
+
+  kokoro-tts:
+    image: ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
+    environment:
+      ONNX_NUM_THREADS: 8
+      ONNX_INTER_OP_THREADS: 4
+      ONNX_EXECUTION_MODE: parallel
+      ONNX_OPTIMIZATION_LEVEL: all
+      ONNX_MEMORY_PATTERN: "true"
+      ONNX_ARENA_EXTEND_STRATEGY: kNextPowerOfTwo
+      API_LOG_LEVEL: DEBUG
+    ports:
+      - "8880:8880"
+
+  seaweedfs:
+    image: chrislusf/seaweedfs:4.18
+    command: ["mini", "-dir=/data"]
+    environment:
+      AWS_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-devkey}
+      AWS_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-devsecret}
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:9333/cluster/status >/dev/null"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+    ports:
+      - "3003:3003"
+      - "8333:8333"
+    volumes:
+      - seaweedfs-data:/data
+
+  nats:
+    image: nats:2.14-alpine
+    command: ["-js", "-sd", "/data"]
+    volumes:
+      - nats-data:/data
+
+  postgres:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_USER: openreader
+      POSTGRES_PASSWORD: openreader
+      POSTGRES_DB: openreader
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U openreader -d openreader"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  compute-worker:
+    image: openreader-compute-worker:local
+    build:
+      context: ../..
+      dockerfile: packages/compute-worker/Dockerfile
+    depends_on:
+      nats:
+        condition: service_started
+      seaweedfs:
+        condition: service_healthy
+    environment:
+      NATS_URL: nats://nats:4222
+      COMPUTE_WORKER_HOST: 0.0.0.0
+      PORT: 8081
+      COMPUTE_WORKER_TOKEN: ${COMPUTE_WORKER_TOKEN:-local-compute-token}
+      S3_ENDPOINT: http://seaweedfs:8333
+      S3_BUCKET: ${S3_BUCKET:-openreader-documents}
+      S3_REGION: ${S3_REGION:-us-east-1}
+      S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-devkey}
+      S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-devsecret}
+      S3_FORCE_PATH_STYLE: "true"
+      S3_PREFIX: ${S3_PREFIX:-openreader}
+      COMPUTE_PREWARM_MODELS: ${COMPUTE_PREWARM_MODELS:-false}
+
+volumes:
+  openreader-docstore:
+  seaweedfs-data:
+  nats-data:
+  postgres-data:

docker/examples/compose.local-slim.yml

@@ -0,0 +1,52 @@
+name: openreader-local-slim-build
+
+services:
+  openreader:
+    image: openreader:local
+    build:
+      context: ../..
+      dockerfile: Dockerfile
+    depends_on:
+      kokoro-tts:
+        condition: service_started
+    environment:
+      BASE_URL: ${BASE_URL:-http://localhost:3003}
+      AUTH_SECRET: ${AUTH_SECRET:-local-openreader-auth-secret-change-me}
+      RUNTIME_SEED_JSON: |-
+        {
+          "version": 1,
+          "runtimeConfig": {
+            "defaultTtsProvider": "kokoro"
+          },
+          "providers": [
+            {
+              "slug": "kokoro",
+              "displayName": "Kokoro",
+              "providerType": "custom-openai",
+              "baseUrl": "http://kokoro-tts:8880/v1",
+              "defaultModel": "kokoro",
+              "enabled": true
+            }
+          ]
+        }
+    ports:
+      - "3003:3003"
+      - "8333:8333"
+    volumes:
+      - openreader-docstore:/app/docstore
+
+  kokoro-tts:
+    image: ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
+    environment:
+      ONNX_NUM_THREADS: 8
+      ONNX_INTER_OP_THREADS: 4
+      ONNX_EXECUTION_MODE: parallel
+      ONNX_OPTIMIZATION_LEVEL: all
+      ONNX_MEMORY_PATTERN: "true"
+      ONNX_ARENA_EXTEND_STRATEGY: kNextPowerOfTwo
+      API_LOG_LEVEL: DEBUG
+    ports:
+      - "8880:8880"
+
+volumes:
+  openreader-docstore:

docker/examples/compose.yml

@@ -0,0 +1,49 @@
+name: openreader-slim
+
+services:
+  openreader:
+    image: ghcr.io/richardr1126/openreader:latest
+    depends_on:
+      kokoro-tts:
+        condition: service_started
+    environment:
+      BASE_URL: ${BASE_URL:-http://localhost:3003}
+      AUTH_SECRET: ${AUTH_SECRET:-local-openreader-auth-secret-change-me}
+      RUNTIME_SEED_JSON: |-
+        {
+          "version": 1,
+          "runtimeConfig": {
+            "defaultTtsProvider": "kokoro"
+          },
+          "providers": [
+            {
+              "slug": "kokoro",
+              "displayName": "Kokoro",
+              "providerType": "custom-openai",
+              "baseUrl": "http://kokoro-tts:8880/v1",
+              "defaultModel": "kokoro",
+              "enabled": true
+            }
+          ]
+        }
+    ports:
+      - "3003:3003"
+      - "8333:8333"
+    volumes:
+      - openreader-docstore:/app/docstore
+
+  kokoro-tts:
+    image: ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
+    environment:
+      ONNX_NUM_THREADS: 8
+      ONNX_INTER_OP_THREADS: 4
+      ONNX_EXECUTION_MODE: parallel
+      ONNX_OPTIMIZATION_LEVEL: all
+      ONNX_MEMORY_PATTERN: "true"
+      ONNX_ARENA_EXTEND_STRATEGY: kNextPowerOfTwo
+      API_LOG_LEVEL: DEBUG
+    ports:
+      - "8880:8880"
+
+volumes:
+  openreader-docstore:

docs-site/docs/about/acknowledgements.md

@@ -10,7 +10,7 @@ This project is built with support from the following open-source projects and t
 - [SQLite](https://www.sqlite.org/)
 - [PostgreSQL](https://www.postgresql.org/)
 - [SeaweedFS](https://github.com/seaweedfs/seaweedfs)
-- [whisper.cpp](https://github.com/ggerganov/whisper.cpp)
+- [OpenAI Whisper](https://github.com/openai/whisper)
 - [ffmpeg](https://ffmpeg.org)
 - [react-pdf](https://github.com/wojtekmaj/react-pdf)
 - [react-reader](https://github.com/happyr/react-reader)

docs-site/docs/configure/admin-panel.md

@@ -21,7 +21,7 @@ On every session resolution the server compares the user's email against this li
 When the logged-in user is an admin, an **Admin** tab appears in **Settings → sidebar** with two sub-tabs:
 
 - **Shared providers** — server-side TTS provider instances visible to all users.
-- **Site features** — runtime-editable replacements for what were previously `NEXT_PUBLIC_*` build-time flags.
+- **Site features** — runtime-editable replacements for what were previously build-time public env flags.
 
 ## Shared TTS providers
 
@@ -50,10 +50,10 @@ Whether users can supply their own personal built-in provider keys is controlled
 
 ### Auto-seeded "default-openai"
 
-On first boot, if `admin_providers` is empty and the legacy `API_KEY` env var is set, OpenReader creates a single shared provider with:
+On first boot, if `admin_providers` is empty and `API_BASE` or `API_KEY` is set, OpenReader creates a single shared provider with:
 
 - slug `default-openai`, displayName `Default (from env)`, providerType `custom-openai`
-- baseUrl from `API_BASE`, apiKey from `API_KEY` (encrypted)
+- baseUrl from `API_BASE`, apiKey from `API_KEY` when provided (blank keys are supported)
 - defaultModel set to `kokoro` (you can edit it in Admin → Shared providers)
 
 After this seed runs, the legacy `API_KEY` / `API_BASE` env vars are no longer read by the TTS routes — the DB row is authoritative. You can rename, edit, disable, or delete this row like any other from the admin UI, and remove the env vars from your `.env` when convenient.
@@ -74,33 +74,72 @@ Runtime-editable settings, one row per key:
 | `restrictUserApiKeys` | Restrict user-supplied API keys/base URLs; when `true`, only admin shared providers are allowed. |
 | `enableTtsProvidersTab` | Whether the user-facing TTS Provider tab in Settings is shown. |
 | `showAllProviderModels` | When `false`, users are restricted to each provider's default model (shared provider `defaultModel` or built-in provider default). |
-| `enableWordHighlight` | Enable whisper.cpp word-by-word highlighting during TTS playback. |
 | `enableAudiobookExport` | Show the audiobook export entry points on PDF/EPUB pages. |
 | `enableDocxConversion` | Accept .docx uploads (converted to PDF server-side). |
-| `enableDestructiveDeleteActions` | Show "Delete all data" buttons in the Documents tab (auth-disabled mode). |
+
+Word-by-word highlighting and PDF layout parsing capability are controlled by compute-worker server env configuration, not an admin runtime flag.
 
 Each row shows a source badge:
 
-- **from env** — the value was migrated from the corresponding `NEXT_PUBLIC_*` env var on first boot. Editing it in the UI flips the source to **admin**.
-- **admin** — explicit admin override. Use **Reset** on the row to clear it back to the env-default state.
-- **default** — neither env nor admin set; uses the built-in default.
+- **from seed** — the value was seeded on first boot (from `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH`).
+- **admin** — explicit admin override. Use **Reset** on the row to clear it back to built-in default behavior.
+- **default** — no seed/admin row exists; built-in default is active.
 
 :::warning Security note for `restrictUserApiKeys`
 Turning `restrictUserApiKeys` off allows user-supplied API keys to flow through this server. Use this only for trusted/self-hosted deployments where that tradeoff is acceptable.
 :::
 
+## Rate limiting
+
+A dedicated **Rate limiting** group (within the same admin panel) collects the daily quotas, the PDF parsing throttle, and the upload size cap:
+
+| Key | What it controls |
+| --- | --- |
+| `disableTtsRateLimit` | Disable the per-user/IP daily TTS character limits. When `false`, the daily-limit fields below it apply. |
+| `disableComputeRateLimit` | Disable per-user PDF parsing rate limiting. When `false`, the burst/sustained limit fields below it apply. |
+| `maxUploadMb` | Maximum size (MB) accepted for a single document upload. Enforced server-side and signed into the presigned S3 PUT. |
+
+The **Disable TTS daily rate limiting** and **Disable PDF parsing rate limiting** toggles each reveal a collapsible group of numeric inputs when set to `false`:
+
+- TTS: anonymous/authenticated per-user daily limits and anonymous/authenticated IP daily backstops.
+- PDF parsing: burst limit + window (seconds) and sustained limit + window (seconds). The sustained window doubles as a concurrency cap.
+
+## TTS upstream
+
+At the end of the **Site features** tab, a dedicated **TTS upstream** group controls server-side request and cache tuning (DB-backed runtime settings, not env vars):
+
+| Key | What it controls |
+| --- | --- |
+| `ttsUpstreamMaxRetries` | Maximum retry attempts for upstream TTS 429/5xx responses. |
+| `ttsUpstreamTimeoutMs` | Upstream request timeout for OpenAI-compatible TTS calls. |
+| `ttsCacheMaxSizeBytes` | Maximum size of the in-memory TTS audio cache. |
+| `ttsCacheTtlMs` | Time-to-live for cached TTS audio buffers. |
+
+In v4 these settings are admin-only and are no longer configurable through environment variables.
+
+## Scheduled tasks
+
+The **Scheduled tasks** section controls background maintenance jobs such as expired-upload cleanup, orphaned-blob reaping, and rate-limit ledger pruning.
+
+- Enable or disable each task, adjust its interval, or run it immediately.
+- Runs use database-backed leases so multiple app instances do not normally execute the same task concurrently.
+- A task that exceeds four minutes is aborted and recorded as failed. A crashed run can be reclaimed after its stale lease expires.
+- Failures and the latest successful summary appear on the task card and in server logs.
+
+Self-hosted Node.js deployments tick the scheduler in-process once per minute. Vercel uses the authenticated `/api/admin/tasks/tick` cron route; the checked-in Vercel Hobby schedule runs once daily, so intervals shorter than one day are unavailable there. See [Vercel Deployment](../deploy/vercel-deployment#5-scheduled-maintenance-tasks).
+
 ## Migrating off env vars
 
-The future-direction goal is to remove `NEXT_PUBLIC_*` / `API_KEY` / `API_BASE` from your `.env` entirely. To do that safely:
+In v4, runtime site features are managed by admin settings and optional JSON seed. To minimize env surface area:
 
 1. Deploy this version with your existing env values in place.
 2. Boot the app once. Open Settings → Admin and verify:
-   - Each `NEXT_PUBLIC_*` setting appears as **from env**.
-   - A `default-openai` row exists in **Shared providers** (if you had `API_KEY` set).
-3. Remove the env vars from your `.env`.
+   - Seeded settings appear as **from seed** (if you supplied a runtime JSON seed).
+   - A `default-openai` row exists in **Shared providers** (if you had `API_BASE` or `API_KEY` set).
+3. Remove any bootstrap env vars you no longer need from `.env`.
 4. Redeploy. Behavior is unchanged — the DB is now the source of truth.
 
-You can keep the env vars indefinitely if you prefer; they're only read on the first boot when the corresponding DB row is absent, so there's no harm in leaving them around.
+You can keep `API_BASE` / `API_KEY` if you intentionally want bootstrap fallback behavior on empty provider tables.
 
 ## How keys are protected
 
@@ -117,4 +156,4 @@ Because the encryption key for `admin_providers` is derived from `AUTH_SECRET`,
 
 - [Auth](./auth) — required to use the admin panel.
 - [TTS Providers](./tts-providers) — built-in provider catalog and per-user behavior.
-- [Environment Variables](../reference/environment-variables) — `ADMIN_EMAILS` and the legacy flags that the admin UI replaces.
+- [Environment Variables](../reference/environment-variables) — `ADMIN_EMAILS`, provider bootstrap vars, and runtime JSON seed.

docs-site/docs/configure/auth.md

@@ -6,23 +6,21 @@ This page covers application-level configuration for provider access and authent
 
 ## Auth behavior
 
-- Auth is enabled only when both `BASE_URL` and `AUTH_SECRET` are set.
-- Remove either value to disable auth.
+- `BASE_URL` and `AUTH_SECRET` are required at startup in v4+.
 - Keep `AUTH_TRUSTED_ORIGINS` empty to trust only `BASE_URL`.
 - Anonymous auth sessions are disabled by default.
 - Set `USE_ANONYMOUS_AUTH_SESSIONS=true` to enable anonymous session flows.
 
 ## Runtime modes
 
-OpenReader effectively has three common runtime modes:
+OpenReader has two common runtime modes:
 
-- **Auth disabled** (`BASE_URL` or `AUTH_SECRET` unset): no admin panel. Shared providers can still exist via first-boot seeding (`API_KEY`/`API_BASE`), but you cannot manage them in-app.
 - **Auth enabled, non-admin user**: user account/session features are available, but no admin controls.
 - **Auth enabled, admin user**: full **Settings → Admin** access (shared providers + site features).
 
 ## Admin role
 
-When auth is enabled, you can designate one or more users as admins via the `ADMIN_EMAILS` env var:
+You can designate one or more users as admins via the `ADMIN_EMAILS` env var:
 
 ```env
 ADMIN_EMAILS=alice@example.com,bob@example.com
@@ -31,7 +29,7 @@ ADMIN_EMAILS=alice@example.com,bob@example.com
 Admins see a new **Admin** tab in **Settings** with two sub-tabs:
 
 - **Shared TTS providers** — server-managed TTS provider instances with encrypted keys, visible to all users.
-- **Site features** — runtime overrides for what were previously `NEXT_PUBLIC_*` build-time flags (including account signup availability, default TTS provider/model, word highlighting, audiobook export, etc.).
+- **Site features** — runtime overrides for what were previously build-time public env flags (including account signup availability, default TTS provider, audiobook export, etc.).
 
 Admin assignment is reconciled on every session resolution, so removing an email from `ADMIN_EMAILS` demotes the user on next login without a restart. See [Admin Panel](./admin-panel) for the full reference.
 
@@ -39,7 +37,7 @@ Admin assignment is reconciled on every session resolution, so removing an email
 
 - `/` is a public landing/onboarding page and remains indexable.
 - `/app` is the protected app home (document list and uploader UI).
-- If auth is enabled and a valid session exists (including anonymous), visiting `/` redirects to `/app`.
+- If a valid session exists (including anonymous), visiting `/` redirects to `/app`.
 - Protected app routes continue to require auth; when anonymous sessions are disabled and no session exists, users are redirected to `/signin`.
 
 ## Related docs
@@ -60,11 +58,7 @@ Admin assignment is reconciled on every session resolution, so removing an email
 - Updates are not instant push-based sync; they use normal client polling/refresh behavior.
 - If two devices change the same item around the same time, the newest update wins.
 
-### Auth disabled
-
-- Settings and reading progress stay local in the browser (Dexie/IndexedDB).
-- This avoids no-auth cross-browser conflicts, but there is no cross-device sync.
-
 ## Claim modal note
 
 - You may still see old anonymous settings/progress available to claim from older deployments.
+- Legacy `unclaimed` data is only surfaced through the claim flow; normal authenticated routes are scoped to your current user id.

docs-site/docs/configure/database.md

@@ -54,6 +54,5 @@ For database variable behavior, see [Environment Variables](../reference/environ
 
 ## State sync summary
 
-- With auth enabled, settings and reading progress are stored in SQL and synced from the app.
-- With auth disabled, settings and reading progress remain local in the browser.
+- Settings and reading progress are stored in SQL and synced from the app.
 - Sync is currently request-based (not realtime push invalidation).

docs-site/docs/configure/migrations.md

@@ -7,6 +7,18 @@ import TabItem from '@theme/TabItem';
 
 This page covers migration behavior for both database schema and storage data in OpenReader.
 
+## Runtime ownership
+
+- `@openreader/database` owns database clients, schemas, SQL migration files, and programmatic
+  migration execution for SQLite and PostgreSQL.
+- `@openreader/bootstrap` owns startup orchestration, storage migration, and optional embedded
+  SeaweedFS, NATS, and compute-worker processes.
+- The Next.js app imports `@openreader/database` directly, but does not orchestrate migrations or
+  child processes.
+
+Docker deploys bootstrap as an isolated runtime bundle under `/opt/openreader/bootstrap`; it does
+not merge migration dependencies into the standalone Next.js app under `/app`.
+
 ## Startup migration behavior
 
 By default, the shared entrypoint runs migrations automatically before app startup in:
@@ -53,11 +65,6 @@ In most cases, you do not need manual migration commands because startup runs mi
 - Postgres when `POSTGRES_URL` is set
 - SQLite when `POSTGRES_URL` is unset
 
-You can always override the target explicitly with `--config`.
-
-<Tabs groupId="apply-migration-commands">
-  <TabItem value="project-scripts" label="Project Scripts" default>
-
 ```bash
 # Run pending migrations for one target:
 # - Postgres if POSTGRES_URL is set
@@ -71,26 +78,15 @@ pnpm migrate-fs
 pnpm migrate-fs:dry-run
 ```
 
-  </TabItem>
-  <TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
-
-```bash
-# Migrate SQLite
-pnpm exec drizzle-kit migrate --config drizzle.config.sqlite.ts
-
-# Migrate Postgres
-pnpm exec drizzle-kit migrate --config drizzle.config.pg.ts
-```
-
-  </TabItem>
-</Tabs>
+`pnpm migrate` uses the programmatic Drizzle migrator from `@openreader/database`. Drizzle Kit is
+not a production or startup dependency; it is used only to generate new migration files.
 
 ## Generate migrations
 
 `pnpm generate` is a two-phase script for contributors and schema changes:
 
 1. **Better Auth schema generation** — runs the Better Auth CLI twice (once for SQLite, once for Postgres) to produce auto-generated Drizzle schema files for auth tables (`user`, `session`, `account`, `verification`).
-2. **Drizzle migration generation** — runs `drizzle-kit generate` for both `drizzle.config.sqlite.ts` and `drizzle.config.pg.ts`, producing SQL migration files from all schema files (app + auth).
+2. **Drizzle migration generation** — runs `drizzle-kit generate` for both configs in `packages/database`, producing SQL migration files from all schema files (app + auth).
 
 :::note
 Most users do not need to run `pnpm generate`. Use it when contributing or when you have changed Drizzle schema files and need new migration files.
@@ -100,22 +96,23 @@ Most users do not need to run `pnpm generate`. Use it when contributing or when
 
 Auth tables are owned by Better Auth. Their Drizzle schema definitions are auto-generated and should **not** be hand-edited:
 
-- `src/db/schema_auth_sqlite.ts`
-- `src/db/schema_auth_postgres.ts`
+- `packages/database/src/schema_auth_sqlite.ts`
+- `packages/database/src/schema_auth_postgres.ts`
 
 App-specific tables are manually maintained in the standard Drizzle schema files:
 
-- `src/db/schema_sqlite.ts`
-- `src/db/schema_postgres.ts`
+- `packages/database/src/schema_sqlite.ts`
+- `packages/database/src/schema_postgres.ts`
 
-Both sets of schema files are included in the Drizzle configs, so `drizzle-kit generate` and `drizzle-kit migrate` handle all tables together.
+Both sets of schema files are included in the Drizzle generation configs. Runtime migration
+execution is owned by `@openreader/database`.
 
 When app schema changes (for example `tts_segments`), keep these in sync:
 
-- `src/db/schema_sqlite.ts`
-- `src/db/schema_postgres.ts`
-- `drizzle/sqlite/*.sql` + `drizzle/sqlite/meta/_journal.json`
-- `drizzle/postgres/*.sql` + `drizzle/postgres/meta/_journal.json`
+- `packages/database/src/schema_sqlite.ts`
+- `packages/database/src/schema_postgres.ts`
+- `packages/database/migrations/sqlite/*.sql` + `packages/database/migrations/sqlite/meta/_journal.json`
+- `packages/database/migrations/postgres/*.sql` + `packages/database/migrations/postgres/meta/_journal.json`
 
 <Tabs groupId="generate-migration-commands">
   <TabItem value="project-script" label="Project Script" default>
@@ -130,10 +127,10 @@ pnpm generate
 
 ```bash
 # Generate SQLite migrations only (skips Better Auth CLI)
-pnpm exec drizzle-kit generate --config drizzle.config.sqlite.ts
+pnpm exec drizzle-kit generate --config packages/database/drizzle.config.sqlite.ts
 
 # Generate Postgres migrations only (skips Better Auth CLI)
-pnpm exec drizzle-kit generate --config drizzle.config.pg.ts
+pnpm exec drizzle-kit generate --config packages/database/drizzle.config.pg.ts
 ```
 
 :::warning

docs-site/docs/configure/tts-provider-guides/other.md

@@ -6,12 +6,14 @@ Use any OpenAI-compatible TTS service with OpenReader, including self-hosted ser
 
 ## Requirements
 
-Your service must expose these endpoints:
+Your service only needs an OpenAI-compatible speech endpoint:
 
-- `GET /v1/audio/voices`
-- `POST /v1/audio/speech`
+- `POST /v1/audio/speech` — **required**.
+- Voice listing is **optional** and auto-discovered from `/v1/audio/voices`, `/v1/voices`, or `/v1/styles`. If none respond, OpenReader falls back to default voices — the Kokoro voice set for Kokoro models, otherwise the standard OpenAI voices (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`).
 
-Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS-FastAPI](./kitten-tts-fastapi), [Orpheus-FastAPI](./orpheus-fastapi).
+The endpoint may return `mp3`, `wav`, `ogg`, or `flac` — OpenReader normalizes non-mp3 audio to mp3 automatically. An API key is optional.
+
+Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS-FastAPI](./kitten-tts-fastapi), [Orpheus-FastAPI](./orpheus-fastapi), [Supertonic](./supertonic).
 
 ## Setup
 
@@ -26,7 +28,7 @@ Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS
 
 ```env
 API_BASE=http://your-tts-server/v1
-API_KEY=optional-key-if-required
+# API_KEY=optional-key-if-required
 ```
 
 **Or in-app via Settings → TTS Provider:**
@@ -44,7 +46,7 @@ See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
 
 ## Troubleshooting
 
-If voices don't load, check that `/v1/audio/voices` is reachable from the server and returns a valid response shape.
+If voices don't load, confirm the server is reachable from the Next.js runtime and that at least one of `/v1/audio/voices`, `/v1/voices`, or `/v1/styles` returns a valid response. If none do, OpenReader falls back to default voices — synthesis still works as long as `POST /v1/audio/speech` succeeds.
 
 ## References
 

docs-site/docs/configure/tts-provider-guides/speech-sdk.md

@@ -0,0 +1,63 @@
+---
+title: Speech SDK
+---
+
+Use [speech-sdk](https://github.com/Jellypod-Inc/speech-sdk) (Apache 2.0) to reach additional cloud TTS providers (ElevenLabs, Cartesia, Hume, Deepgram, Google Gemini TTS, Inworld, and more) with your own provider API keys. Requests go from the OpenReader server directly to the provider's API; no extra account or proxy is involved.
+
+Models use the `provider/model` format. The API key you enter belongs to the provider named by the model prefix: for `elevenlabs/eleven_multilingual_v2` enter an ElevenLabs key, for `cartesia/sonic-3.5` a Cartesia key, and so on.
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `speech-sdk`.
+2. Enter the API key for the provider you want to use.
+3. Set default model to a matching `provider/model` (for example `elevenlabs/eleven_multilingual_v2`).
+
+**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
+
+1. Set provider to `Speech SDK`.
+2. Choose a model; enter the API key for that model's provider.
+3. Choose a voice.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Built-in models
+
+- `openai/gpt-4o-mini-tts` (works with your existing OpenAI API key)
+- `elevenlabs/eleven_multilingual_v2`
+- `cartesia/sonic-3.5`
+- `deepgram/aura-2`
+- `google/gemini-2.5-flash-preview-tts`
+- `inworld/inworld-tts-1.5-max`
+
+You can also choose `Other` and enter any `provider/model` the SDK supports. Recognized prefixes: `openai`, `elevenlabs`, `cartesia`, `hume`, `deepgram`, `google`, `inworld`, `minimax`, `fish-audio`, `murf`, `resemble`, `fal-ai`, `mistral`, `xai`, `smallest-ai`.
+
+## Voice IDs
+
+ElevenLabs and Cartesia identify voices by opaque IDs. The built-in lists map to these shared library voices:
+
+| ElevenLabs ID | Name | | Cartesia ID | Name |
+| --- | --- | --- | --- | --- |
+| `JBFqnCBsd6RMkjVDRZzb` | George | | `a0e99841-438c-4a64-b679-ae501e7d6091` | Barbershop Man |
+| `IKne3meq5aSn9XLyUdCD` | Charlie | | `156fb8d2-335b-4950-9cb3-a2d33f0c0c2a` | British Lady |
+| `XB0fDUnXU5powFXDhCwa` | Charlotte | | `694f9389-aac1-45b6-b726-9d9369183238` | California Girl |
+| `Xb7hH8MSUJpSbSDYk0k2` | Alice | | `87748186-23bb-4571-8b8b-a73da9bf9c4f` | Commercial Lady |
+| `iP95p4xoKVk53GoZ742B` | Chris | | `ee7ea9f8-c0c1-498c-9f62-dc2da49a6f98` | Friendly Reading Man |
+| `nPczCjzI2devNBz1zQrb` | Brian | | `248be419-c632-4f23-adf1-5324ed7dbf1d` | Hannah |
+| `onwK4e9ZLuTAKqWW03F9` | Daniel | | | |
+| `pFZP5JQG7iQjIQuC4Bku` | Lily | | | |
+| `pqHfZKP75CvOlQylNhV4` | Bill | | | |
+
+## Notes
+
+- One voice per request; Kokoro-style multi-voice mixing does not apply to this provider.
+- Playback speed is applied client-side, so cached audio segments stay valid when you change speed.
+- Providers without a built-in voice list fall back to a `default` entry, which lets the provider pick its default voice.
+- Word-by-word highlighting works the same as with every other provider (alignment runs in OpenReader, not the provider).
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
+
+## References
+
+- [speech-sdk on GitHub](https://github.com/Jellypod-Inc/speech-sdk)
+- [TTS Providers](../tts-providers)

docs-site/docs/configure/tts-provider-guides/supertonic.md

@@ -0,0 +1,68 @@
+---
+title: Supertonic
+---
+
+Run [Supertonic](https://github.com/supertone-inc/supertonic-py) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider. Supertonic is a fast, on-device TTS engine that ships its own OpenAI-compatible HTTP server.
+
+:::note No Docker image
+Supertonic does not publish a Docker image — it installs as a Python package and runs as a local HTTP server. These instructions assume OpenReader itself runs in Docker (the common case); see [Running OpenReader directly on the host](#running-openreader-directly-on-the-host) if you don't.
+:::
+
+## Run Supertonic
+
+Install with `pip` (or `pipx` for an isolated install) and start the server:
+
+```bash
+pipx install 'supertonic[serve]'   # or: pip install 'supertonic[serve]'
+supertonic serve                   # defaults; loopback only
+```
+
+The first run downloads the model (~400MB). Once it's up, the OpenAI-compatible endpoint is at `http://127.0.0.1:7788/v1/audio/speech` and interactive docs are at `http://127.0.0.1:7788/docs`.
+
+- **Models:** `supertonic-3` (default) or `supertonic-2`.
+- **Voices:** built-ins `M1`–`M5` and `F1`–`F5`, plus any custom voices you import. OpenReader discovers them automatically via the `/v1/styles` endpoint.
+- **Audio format:** Supertonic emits `wav` by default; OpenReader transcodes it to mp3 transparently, so no extra configuration is needed.
+
+## Connect to OpenReader
+
+From a Docker container, your host machine is reachable at `host.docker.internal`, so the base URL is `http://host.docker.internal:7788/v1`. On Docker Desktop (macOS/Windows) this reaches the loopback-bound server above with no extra setup.
+
+:::note Linux (native Docker Engine)
+On native Linux Docker, `host.docker.internal` needs `--add-host=host.docker.internal:host-gateway` on the OpenReader container (or the equivalent `extra_hosts` entry in `docker-compose.yml`), and it routes to the host's bridge interface rather than loopback. Pick one:
+
+- Run the OpenReader container with `--network host` (or `network_mode: host`), keep Supertonic on `--host 127.0.0.1`, and use `http://127.0.0.1:7788/v1` as the base URL.
+- Or start Supertonic with `--host 0.0.0.0` so the bridge can reach it — keep it on a trusted network or behind a firewall.
+:::
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set base URL to `http://host.docker.internal:7788/v1`.
+3. Leave API key blank — `supertonic serve` does not require one.
+4. Set default model to `supertonic-3` (or `supertonic-2`).
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://host.docker.internal:7788/v1
+```
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to `http://host.docker.internal:7788/v1`.
+3. Leave `API_KEY` blank.
+4. Choose model `supertonic-3` (or the model your deployment exposes).
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Running OpenReader directly on the host
+
+If OpenReader runs on the same machine (e.g. `pnpm dev`) rather than in Docker, skip `host.docker.internal` and use `http://127.0.0.1:7788/v1` as the base URL everywhere above.
+
+## References
+
+- [supertone-inc/supertonic-py](https://github.com/supertone-inc/supertonic-py)
+- [Supported Languages](https://github.com/supertone-inc/supertonic-py#supported-languages)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/docs/configure/tts-providers.md

@@ -11,7 +11,7 @@ OpenReader routes all TTS requests through the Next.js server to an OpenAI-compa
 **Environment variables**: `API_KEY` and `API_BASE` exist as a one-shot first-boot seed that auto-creates a `default-openai` admin shared provider. After the first boot they are no longer read by the running app.
 
 :::tip
-If you're running a private/self-hosted instance and want per-user BYOK behavior, turn off **Settings → Admin → Site features → Restrict user API keys**. Legacy first-boot seed via `NEXT_PUBLIC_RESTRICT_USER_API_KEYS=false` is still supported for no-admin bootstrap flows.
+If you're running a private/self-hosted instance and want per-user BYOK behavior, turn off **Settings → Admin → Site features → Restrict user API keys**. For first-boot automation, set `runtimeConfig.restrictUserApiKeys=false` in `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH`.
 :::
 
 ## Providers
@@ -19,6 +19,7 @@ If you're running a private/self-hosted instance and want per-user BYOK behavior
 - **OpenAI**: Cloud. Base URL pre-filled (`https://api.openai.com/v1`). API key required.
 - **Replicate**: Cloud. Base URL managed internally by OpenReader. API key required.
 - **DeepInfra**: Cloud. Base URL pre-filled (`https://api.deepinfra.com/v1/openai`). API key required.
+- **Speech SDK**: Cloud. Reaches additional providers (ElevenLabs, Cartesia, Hume, Deepgram, Google, Inworld, and more) directly with your own provider API keys via [speech-sdk](./tts-provider-guides/speech-sdk). No base URL. API key required (the key for the model's provider).
 - **Custom OpenAI-Like**: Self-hosted or any custom endpoint. `API_BASE` must be set manually (typically ending in `/v1`). API key optional.
 
 For `OpenAI`, `DeepInfra`, and `Replicate` you only need to supply an API key. For `Custom OpenAI-Like` you must also set `API_BASE`.
@@ -28,13 +29,16 @@ For `OpenAI`, `DeepInfra`, and `Replicate` you only need to supply an API key. F
 - **Replicate** models: `alphanumericuser/kokoro-82m`, `google/gemini-3.1-flash-tts`, `minimax/speech-2.8-turbo`, `qwen/qwen3-tts`, `inworld/tts-1.5-mini` (or choose `Other` and enter any Replicate model ID, such as `owner/model` or `owner/model:version`)
 - **OpenAI** models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
 - **DeepInfra** models: includes `hexgrad/Kokoro-82M` and additional hosted models (depending on API key / feature flags)
+- **Speech SDK** models: `openai/gpt-4o-mini-tts`, `elevenlabs/eleven_multilingual_v2`, `cartesia/sonic-3.5`, `deepgram/aura-2`, `google/gemini-2.5-flash-preview-tts`, `inworld/inworld-tts-1.5-max` (or choose `Other` and enter any `provider/model` the SDK supports)
 
 ## Custom provider requirements
 
-Self-hosted or custom providers must expose OpenAI-compatible audio endpoints:
+Self-hosted or custom providers only need an OpenAI-compatible speech endpoint:
 
-- `GET /v1/audio/voices`
-- `POST /v1/audio/speech`
+- `POST /v1/audio/speech` — **required**.
+- Voice listing is **optional** and auto-discovered: OpenReader probes `/v1/audio/voices`, `/v1/voices`, then `/v1/styles`. If none respond, it falls back to default voices — the Kokoro set for Kokoro models, otherwise the standard OpenAI voices (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`).
+
+The speech endpoint may return any common audio format — `mp3`, `wav`, `ogg`, or `flac`. OpenReader detects the format and transcodes non-mp3 audio to mp3 automatically, so your server does not need to honor `response_format: mp3`. An API key is optional; keyless servers work.
 
 :::warning TTS requests are server-side
 TTS requests originate from the **Next.js server**, not the browser. `API_BASE` must be reachable from the server runtime. In Docker, use container names or `host.docker.internal` rather than `localhost`.
@@ -45,9 +49,11 @@ TTS requests originate from the **Next.js server**, not the browser. `API_BASE`
 - [Kokoro-FastAPI](./tts-provider-guides/kokoro-fastapi)
 - [KittenTTS-FastAPI](./tts-provider-guides/kitten-tts-fastapi)
 - [Orpheus-FastAPI](./tts-provider-guides/orpheus-fastapi)
+- [Supertonic](./tts-provider-guides/supertonic)
 - [Replicate](./tts-provider-guides/replicate)
 - [DeepInfra](./tts-provider-guides/deepinfra)
 - [OpenAI](./tts-provider-guides/openai)
+- [Speech SDK](./tts-provider-guides/speech-sdk)
 - [Other](./tts-provider-guides/other)
 
 ## Related

docs-site/docs/configure/tts-rate-limiting.md

@@ -7,7 +7,7 @@ This page explains OpenReader's TTS character rate limiting controls.
 ## Overview
 
 - TTS rate limiting is disabled by default.
-- To enable it, set `TTS_ENABLE_RATE_LIMIT=true`.
+- Primary control is **Settings → Admin → Site features → Disable TTS daily rate limiting**.
 - Limits are enforced per day in UTC.
 - Enforcement applies only when auth is enabled.
 
@@ -28,24 +28,15 @@ If a request exceeds the active limit, the TTS API returns `429` with reset meta
 - `DISABLE_AUTH_RATE_LIMIT` only affects Better Auth's own request throttling.
 - `DISABLE_AUTH_RATE_LIMIT` does not disable TTS character limits.
 
-## Environment variables
+## Runtime config
 
-Enable/disable:
-
-- `TTS_ENABLE_RATE_LIMIT` (default: `false`)
-
-Per-user daily limits:
-
-- `TTS_DAILY_LIMIT_ANONYMOUS` (default: `50000`)
-- `TTS_DAILY_LIMIT_AUTHENTICATED` (default: `500000`)
-
-IP backstop daily limits:
-
-- `TTS_IP_DAILY_LIMIT_ANONYMOUS` (default: `100000`)
-- `TTS_IP_DAILY_LIMIT_AUTHENTICATED` (default: `1000000`)
+- `disableTtsRateLimit` default: `true`
+- Per-user and IP backstop limit values are configured in **Settings → Admin → Site features** and stored in DB runtime settings.
+- Optional first-boot seeding can be done via `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH` (`runtimeConfig.disableTtsRateLimit`).
 
 ## Related docs
 
 - TTS/rate-limit environment variables: [Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
+- PDF parsing rate limiting (separate, compute-side throttle): [Admin Panel → Rate limiting](./admin-panel#rate-limiting)
 - Auth configuration: [Auth](./auth)
 - Provider setup: [TTS Providers](./tts-providers)

docs-site/docs/deploy/compute-worker.md

@@ -0,0 +1,134 @@
+---
+title: Compute Worker
+description: Deploy the standalone worker used for Whisper alignment and PDF layout parsing.
+---
+
+Use this guide when OpenReader runs compute as a separate service. For the default embedded/local flow (`pnpm dev` or `pnpm start` without `COMPUTE_WORKER_URL`), configure the root `.env` instead and see [Local Development](./local-development).
+
+## What the worker does
+
+- Runs Whisper word alignment jobs
+- Runs PDF layout parsing jobs
+- Stores durable job state in NATS JetStream and NATS KV
+
+The app server submits resource-specific operations under `/v1` and listens for updates on
+`GET /v1/operations/:opId/events`.
+
+## When to use it
+
+- Required for Vercel-style deployments where heavy compute must run outside the app server
+- Useful when you want a dedicated compute host
+- Not needed for the default embedded local flow
+
+## Container image
+
+- `ghcr.io/richardr1126/openreader-compute-worker:latest`
+
+## Worker environment
+
+Required worker variables:
+
+```env
+COMPUTE_WORKER_TOKEN=...
+NATS_URL=nats://...
+S3_BUCKET=...
+S3_REGION=...
+S3_ACCESS_KEY_ID=...
+S3_SECRET_ACCESS_KEY=...
+```
+
+:::important
+`compute-worker/.env*` is only for standalone worker deployments.
+
+- Embedded/local mode: configure the root `.env` only.
+- External worker mode: set `COMPUTE_WORKER_URL` and `COMPUTE_WORKER_TOKEN` on the app, and worker runtime values on the worker service.
+- Keep shared values aligned across app and worker: `COMPUTE_WORKER_TOKEN`, `S3_*`, `COMPUTE_WHISPER_TIMEOUT_MS`, `COMPUTE_PDF_TIMEOUT_MS`, `COMPUTE_PDF_JOB_ATTEMPTS`, and `COMPUTE_OP_STALE_MS`.
+:::
+
+Common optional variables:
+
+- `NATS_CREDS` or `NATS_CREDS_FILE`
+- `S3_ENDPOINT`, `S3_FORCE_PATH_STYLE=true`, `S3_PREFIX=openreader`
+- `COMPUTE_WORKER_HOST=0.0.0.0`
+- `PORT=8081` for local/manual runs. Platforms like Railway usually inject `PORT`.
+- `LOG_FORMAT=json` and `COMPUTE_LOG_LEVEL=info`
+- `COMPUTE_PREWARM_MODELS=false` by default. Set it to `true` to pre-download ONNX models during worker startup.
+- `COMPUTE_JOB_CONCURRENCY=1`
+- `COMPUTE_WHISPER_TIMEOUT_MS=30000`
+- `COMPUTE_PDF_TIMEOUT_MS=300000`
+- `COMPUTE_PDF_JOB_ATTEMPTS=1`
+- `COMPUTE_JOBS_STREAM_MAX_BYTES=268435456`
+- `COMPUTE_EVENTS_STREAM_MAX_BYTES=134217728`
+- `COMPUTE_JOB_STATES_MAX_BYTES=67108864`
+- `COMPUTE_NATS_REPLICAS=1`
+- `COMPUTE_OP_STALE_MS=1800000`
+- `WHISPER_MODEL_BASE_URL`
+- `PDF_LAYOUT_MODEL_BASE_URL`
+
+If you need the broader app config reference, see [Environment Variables](../reference/environment-variables).
+
+## App server environment
+
+Set these on the Next.js app server:
+
+```env
+COMPUTE_WORKER_URL=https://worker.example.com
+COMPUTE_WORKER_TOKEN=<same-token-as-worker>
+# Optional shared overrides:
+# COMPUTE_WHISPER_TIMEOUT_MS=30000
+# COMPUTE_PDF_TIMEOUT_MS=300000
+# COMPUTE_PDF_JOB_ATTEMPTS=1
+# COMPUTE_OP_STALE_MS=1800000
+```
+
+Notes:
+
+- Model artifact overrides (`WHISPER_MODEL_BASE_URL`, `PDF_LAYOUT_MODEL_BASE_URL`) belong on the worker service, not the app server.
+- There is no app-local compute fallback once `COMPUTE_WORKER_URL` is set. If the worker is unavailable, worker-backed requests fail.
+
+## Deployment notes
+
+- App and worker must share the same object storage.
+- Embedded `weed mini` is not supported for external worker mode.
+- Protect `COMPUTE_WORKER_TOKEN` and do not expose worker routes without auth.
+- The worker connects to NATS lazily and disconnects after 120 seconds of full idle time. That allows platforms like Railway to sleep the service, but the first request after a cold start will be slower.
+
+## Health endpoints
+
+- `GET /health/live` returns `{ ok: true }`.
+- `GET /health/ready` returns `{ ok: true, natsConnected }` and reflects the current NATS session without forcing a reconnect.
+
+## Railway + Synadia example
+
+Deploy the worker image to Railway and set worker env vars similar to:
+
+```env
+COMPUTE_WORKER_HOST=0.0.0.0
+COMPUTE_WORKER_TOKEN=<shared-token>
+NATS_URL=tls://connect.ngs.global:4222
+NATS_CREDS="-----BEGIN NATS USER JWT-----
+...
+------END USER NKEY SEED------"
+S3_BUCKET=<bucket>
+S3_REGION=<region>
+S3_ACCESS_KEY_ID=<key>
+S3_SECRET_ACCESS_KEY=<secret>
+# Optional:
+# S3_ENDPOINT=https://...
+# S3_FORCE_PATH_STYLE=true
+# S3_PREFIX=openreader
+```
+
+If your platform supports mounted files, you can use `NATS_CREDS_FILE` instead of `NATS_CREDS`.
+
+Set these on the OpenReader app server:
+
+```env
+COMPUTE_WORKER_URL=https://<railway-worker-domain>
+COMPUTE_WORKER_TOKEN=<same-token-as-worker>
+```
+
+Verify the worker after deploy:
+
+- `GET https://<railway-worker-domain>/health/live`
+- `GET https://<railway-worker-domain>/health/ready`

docs-site/docs/deploy/docker-compose.md

@@ -0,0 +1,175 @@
+---
+title: Docker Compose
+description: Run OpenReader with the slim, full, local-slim, or local-full Docker Compose examples.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Use these examples to run OpenReader with Kokoro-FastAPI and persistent storage. Choose the slim
+stack for the simplest deployment, or the full stack when you want PostgreSQL, SeaweedFS, NATS,
+and the compute worker as separate containers. Local build variants are also available for both slim
+and full stacks to build the application from your current checkout.
+
+## Prerequisites
+
+- A recent Docker version with Docker Compose
+- A clone of the OpenReader repository
+
+```bash
+git clone https://github.com/richardr1126/openreader.git
+cd openreader
+```
+
+## Choose a stack
+
+<Tabs groupId="docker-compose-stack">
+<TabItem value="slim" label="Slim" default>
+
+The default slim example runs:
+
+- OpenReader with embedded SeaweedFS, NATS, compute worker, and SQLite
+- Kokoro-FastAPI as a companion container
+
+```bash
+docker compose -f docker/examples/compose.yml up
+# Repository convenience command: pnpm compose
+```
+
+Compose file: [`docker/examples/compose.yml`](https://github.com/richardr1126/openreader/blob/main/docker/examples/compose.yml)
+
+</TabItem>
+<TabItem value="full" label="Full">
+
+The full example runs OpenReader, Kokoro-FastAPI, PostgreSQL, SeaweedFS, NATS, and the compute
+worker as separate containers using published images.
+
+```bash
+docker compose -f docker/examples/compose.full.yml up
+# Repository convenience command: pnpm compose:full
+```
+
+Compose file: [`docker/examples/compose.full.yml`](https://github.com/richardr1126/openreader/blob/main/docker/examples/compose.full.yml)
+
+For details about running the worker separately, see
+[Compute Worker](./compute-worker).
+
+</TabItem>
+<TabItem value="local-slim" label="Local Slim">
+
+The local-slim example runs a slim setup (OpenReader and Kokoro-FastAPI), but builds the OpenReader app image from the current checkout.
+
+```bash
+docker compose -f docker/examples/compose.local-slim.yml up --build
+# Repository convenience command: pnpm compose:local
+```
+
+Compose file: [`docker/examples/compose.local-slim.yml`](https://github.com/richardr1126/openreader/blob/main/docker/examples/compose.local-slim.yml)
+
+</TabItem>
+<TabItem value="local-full" label="Local Full">
+
+The local-full example uses the full multi-container layout, but builds the OpenReader app and compute-worker images from the current checkout.
+
+```bash
+docker compose -f docker/examples/compose.local-full.yml up --build
+# Repository convenience command: pnpm compose:local:full
+```
+
+Compose file: [`docker/examples/compose.local-full.yml`](https://github.com/richardr1126/openreader/blob/main/docker/examples/compose.local-full.yml)
+
+</TabItem>
+</Tabs>
+
+## Included services
+
+| Service | Slim | Full | Local Slim | Local Full |
+| --- | --- | --- | --- | --- |
+| OpenReader | Published image | Published image | Local build | Local build |
+| Kokoro-FastAPI | Container | Container | Container | Container |
+| Database | Embedded SQLite | PostgreSQL container | Embedded SQLite | PostgreSQL container |
+| SeaweedFS | Embedded | Container | Embedded | Container |
+| NATS | Embedded | Container | Embedded | Container |
+| Compute worker | Embedded | Published image | Embedded | Local build |
+
+On first boot, `RUNTIME_SEED_JSON` creates an enabled Kokoro shared provider and selects it as the
+default TTS provider.
+
+## Endpoints
+
+- OpenReader: `http://localhost:3003`
+- SeaweedFS S3: `http://localhost:8333`
+- Kokoro-FastAPI: `http://localhost:8880`
+
+In the full examples, PostgreSQL, the compute worker, and NATS remain internal to the Compose
+network.
+
+## LAN access
+
+Set `BASE_URL` and `S3_ENDPOINT` to the Docker host's LAN IP so browser-facing app and presigned
+S3 URLs are reachable from other devices:
+
+<Tabs groupId="docker-compose-lan-stack">
+<TabItem value="slim" label="Slim" default>
+
+```bash
+BASE_URL=http://192.168.0.XXX:3003 \
+S3_ENDPOINT=http://192.168.0.XXX:8333 \
+docker compose -f docker/examples/compose.yml up
+# Repository convenience command: pnpm compose
+```
+
+</TabItem>
+<TabItem value="full" label="Full">
+
+```bash
+BASE_URL=http://192.168.0.XXX:3003 \
+S3_ENDPOINT=http://192.168.0.XXX:8333 \
+docker compose -f docker/examples/compose.full.yml up
+# Repository convenience command: pnpm compose:full
+```
+
+</TabItem>
+<TabItem value="local-slim" label="Local Slim">
+
+```bash
+BASE_URL=http://192.168.0.XXX:3003 \
+S3_ENDPOINT=http://192.168.0.XXX:8333 \
+docker compose -f docker/examples/compose.local-slim.yml up --build
+# Repository convenience command: pnpm compose:local
+```
+
+</TabItem>
+<TabItem value="local-full" label="Local Full">
+
+```bash
+BASE_URL=http://192.168.0.XXX:3003 \
+S3_ENDPOINT=http://192.168.0.XXX:8333 \
+docker compose -f docker/examples/compose.local-full.yml up --build
+# Repository convenience command: pnpm compose:local:full
+```
+
+</TabItem>
+</Tabs>
+
+Replace `192.168.0.XXX` with your Docker host's LAN IP and allow inbound TCP ports `3003` and
+`8333` through its firewall.
+
+:::info Internal full-stack endpoint
+The full and local-full compute workers continue using `http://seaweedfs:8333` internally.
+`S3_ENDPOINT` configures the app endpoint and browser-facing presigned URLs.
+:::
+
+## Configuration
+
+The examples use local-only default credentials. Override existing `${VARIABLE}` values through
+your shell environment before using them beyond local development.
+
+:::warning Protect public deployments
+Replace the default `AUTH_SECRET`, PostgreSQL credentials, S3 credentials, and compute-worker
+token before exposing a stack outside your trusted local network.
+:::
+
+For the complete configuration reference, see
+[Environment Variables](../reference/environment-variables). See [Database](../configure/database)
+for PostgreSQL and SQLite behavior.

docs-site/docs/deploy/local-development.md

@@ -89,6 +89,41 @@ OpenReader currently pins `4.18` in CI and Docker builds while `4.19` compatibil
 
 </details>
 
+<details>
+<summary><strong>NATS Server <code>nats-server</code> (required for embedded compute mode)</strong></summary>
+
+If `COMPUTE_WORKER_URL` is unset, startup launches embedded compute worker + NATS, so `nats-server` must be available on host PATH.
+
+If you always use an external worker (`COMPUTE_WORKER_URL` set), this is not required.
+
+<Tabs groupId="local-dev-nats-os">
+<TabItem value="macos" label="macOS" default>
+
+```bash
+brew install nats-server
+nats-server -v
+```
+
+</TabItem>
+<TabItem value="linux" label="Linux">
+
+```bash
+# Linux amd64 example
+mkdir -p "$HOME/.local/bin"
+curl -fsSL -o /tmp/nats-server.zip \
+  https://github.com/nats-io/nats-server/releases/latest/download/nats-server-v2.12.1-linux-amd64.zip
+unzip -j /tmp/nats-server.zip '*/nats-server' -d /tmp
+install -m 0755 /tmp/nats-server "$HOME/.local/bin/nats-server"
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+export PATH="$HOME/.local/bin:$PATH"
+nats-server -v
+```
+
+</TabItem>
+</Tabs>
+
+</details>
+
 <details>
 <summary><strong>LibreOffice (optional, for DOCX conversion)</strong></summary>
 
@@ -114,53 +149,21 @@ sudo apt install -y libreoffice
 </details>
 
 <details>
-<summary><strong>whisper.cpp (optional, for word-by-word highlighting)</strong></summary>
+<summary><strong>Word-by-word highlighting (optional)</strong></summary>
 
-Install build dependencies:
+No extra native Whisper CLI build step is required.
 
-<Tabs groupId="local-dev-whisper-deps-os">
-<TabItem value="macos" label="macOS" default>
+Word-by-word highlighting and PDF layout parsing are worker-backed in current releases.
 
-```bash
-brew install cmake
-```
-
-</TabItem>
-<TabItem value="linux" label="Linux">
-
-```bash
-# Debian/Ubuntu example
-sudo apt update
-sudo apt install -y git build-essential cmake
-```
-
-</TabItem>
-</Tabs>
-
-Build whisper.cpp:
-
-```bash
-# clone and build whisper.cpp (no model download needed – OpenReader handles that)
-git clone https://github.com/ggml-org/whisper.cpp.git
-cd whisper.cpp
-cmake -B build
-cmake --build build -j --config Release
-
-# point OpenReader to the compiled whisper-cli binary
-echo WHISPER_CPP_BIN="$(pwd)/build/bin/whisper-cli"
-```
-
-If you are not on Debian/Ubuntu, install equivalent packages with your distro package manager:
-
-- Fedora/RHEL: use `dnf` (`gcc gcc-c++ make cmake curl git tar xz`)
-- Arch: use `pacman` (`base-devel cmake curl git tar xz`)
-
-:::tip
-Set `WHISPER_CPP_BIN` in your `.env` to enable word-by-word highlighting.
-:::
+If you need mirrors or pinned artifact locations, set `WHISPER_MODEL_BASE_URL` in `.env` (current defaults expect q4 Whisper files at that base URL).
 
 </details>
 
+:::tip Docker Compose
+To run OpenReader and Kokoro-FastAPI with Docker Compose, including slim, full, and local-build
+options, see [Docker Compose](./docker-compose).
+:::
+
 ## Steps
 
 ### Required flow
@@ -186,27 +189,33 @@ cp .env.example .env
 
 Then edit `.env`.
 
+Default embedded worker flow (no external worker URL):
+
+```env
+# Leave COMPUTE_WORKER_URL unset.
+# Entry point auto-starts embedded worker+NATS when available.
+```
+
+External worker flow:
+
+```env
+COMPUTE_WORKER_URL=http://localhost:8081
+COMPUTE_WORKER_TOKEN=<same-token-used-by-worker>
+```
+
+Use the same ownership split:
+- root `.env`: app routing/auth (`COMPUTE_WORKER_URL`, `COMPUTE_WORKER_TOKEN`) plus optional shared timeout/stale overrides
+- `compute-worker/.env*` (or worker platform env): worker runtime variables (`NATS_*`, `S3_*`, model base URLs, worker tuning)
+
 Use one of these `.env` mode templates:
 
 <Tabs groupId="local-env-modes">
-  <TabItem value="no-auth" label="No Auth (simple)" default>
+  <TabItem value="auth-enabled" label="Auth Enabled" default>
 
 ```env
 API_BASE=http://host.docker.internal:8880/v1
-API_KEY=none
-# Leave BASE_URL and AUTH_SECRET unset to keep auth disabled.
-# (Admin panel is unavailable without auth.)
-# API_BASE/API_KEY seed a shared default provider if you want shared mode.
-```
-
-  </TabItem>
-  <TabItem value="auth-enabled" label="Auth Enabled">
-
-```env
-API_BASE=http://host.docker.internal:8880/v1
-API_KEY=none
 BASE_URL=http://localhost:3003
-AUTH_SECRET=<generate-with-openssl-rand-hex-32>
+AUTH_SECRET=<generate-with-openssl-rand-base64-32>
 # Optional when you need multiple local origins:
 # AUTH_TRUSTED_ORIGINS=http://localhost:3003,http://127.0.0.1:3003
 ```
@@ -215,12 +224,11 @@ AUTH_SECRET=<generate-with-openssl-rand-hex-32>
   <TabItem value="auth-with-admin" label="Auth + Admin Panel">
 
 ```env
-# API_BASE / API_KEY are seeded into the admin "default-openai" shared provider
+# API_BASE and optional API_KEY are seeded into the admin "default-openai" shared provider
 # on first boot, then no longer read. Manage them in Settings → Admin afterwards.
 API_BASE=http://host.docker.internal:8880/v1
-API_KEY=none
 BASE_URL=http://localhost:3003
-AUTH_SECRET=<generate-with-openssl-rand-hex-32>
+AUTH_SECRET=<generate-with-openssl-rand-base64-32>
 # Comma-separated emails to auto-promote to admin on signin.
 ADMIN_EMAILS=you@example.com
 ```
@@ -230,7 +238,27 @@ ADMIN_EMAILS=you@example.com
 
 ```env
 API_BASE=http://host.docker.internal:8880/v1
-API_KEY=none
+USE_EMBEDDED_WEED_MINI=false
+BASE_URL=http://localhost:3003
+AUTH_SECRET=<generate-with-openssl-rand-base64-32>
+S3_BUCKET=your-bucket
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=your-access-key
+S3_SECRET_ACCESS_KEY=your-secret-key
+# Optional for non-AWS providers:
+# S3_ENDPOINT=https://your-s3-compatible-endpoint
+# S3_FORCE_PATH_STYLE=true
+```
+
+  </TabItem>
+  <TabItem value="worker-mode" label="External Worker Service">
+
+```env
+API_BASE=http://host.docker.internal:8880/v1
+BASE_URL=http://localhost:3003
+AUTH_SECRET=<generate-with-openssl-rand-base64-32>
+COMPUTE_WORKER_URL=http://localhost:8081
+COMPUTE_WORKER_TOKEN=<same-token-used-by-worker>
 USE_EMBEDDED_WEED_MINI=false
 S3_BUCKET=your-bucket
 S3_REGION=us-east-1
@@ -245,11 +273,11 @@ S3_SECRET_ACCESS_KEY=your-secret-key
 </Tabs>
 
 :::note Env vars vs. admin panel
-On first boot, `API_KEY` / `API_BASE` and any `NEXT_PUBLIC_*` flags you've set get auto-seeded into the admin-managed runtime config (DB-backed, keys encrypted at rest). After that, the admin UI is authoritative and editing those env vars no longer changes app behavior. See [Admin Panel](../configure/admin-panel).
+On first boot, `API_KEY` / `API_BASE` can bootstrap `default-openai`, and `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH` can seed runtime config + providers. After that, the admin UI is authoritative and editing bootstrap env vars no longer changes app behavior. See [Admin Panel](../configure/admin-panel).
 :::
 
 :::note User BYOK restriction default
-If you want each user to enter personal provider credentials, set `restrictUserApiKeys=false` (from **Settings → Admin** when auth/admin is enabled, or via legacy first-boot seed `NEXT_PUBLIC_RESTRICT_USER_API_KEYS=false` for no-admin bootstrap flows).
+If you want each user to enter personal provider credentials, set `restrictUserApiKeys=false` (from **Settings → Admin**, or by seeding `runtimeConfig.restrictUserApiKeys=false` in runtime seed JSON).
 :::
 
 :::info
@@ -262,6 +290,10 @@ Storage configuration details are in [Object / Blob Storage](../configure/object
 Refer to [Database](../configure/database) for database modes.
 Learn about migration behavior and commands in [Migrations](../configure/migrations).
 
+:::info Scheduled maintenance tasks
+Local and self-hosted Node.js deployments start the scheduled-task loop in-process and check for due work once per minute. No `CRON_SECRET` is required unless you intentionally invoke the cron HTTP route yourself. Manage task intervals and inspect failures from **Settings → Admin → Scheduled tasks**.
+:::
+
 4. Start the app.
 
 <Tabs groupId="local-run-mode">
@@ -271,6 +303,9 @@ Learn about migration behavior and commands in [Migrations](../configure/migrati
 pnpm dev
 ```
 
+If you use embedded worker startup (no `COMPUTE_WORKER_URL`) and the host is missing `nats-server`,
+install `nats-server` locally or switch to external worker mode.
+
   </TabItem>
   <TabItem value="prod" label="Build + Start">
 

docs-site/docs/deploy/vercel-deployment.md

@@ -8,6 +8,8 @@ This guide covers deploying OpenReader to Vercel with external Postgres and S3-c
 
 - Documents (PDF/EPUB/TXT/MD) work with `POSTGRES_URL` + external S3 storage.
 - Audiobook routes work on Node.js serverless functions using `ffmpeg-static`.
+- Heavy compute features (Whisper alignment + PDF layout parsing) run through an external compute worker service.
+- For worker setup details and worker-specific env vars, see [Compute Worker (NATS JetStream)](./compute-worker).
 
 :::warning DOCX Conversion Limitation
 `docx` conversion requires `soffice` (LibreOffice), which is not available in a standard Vercel runtime.
@@ -34,16 +36,42 @@ S3_PREFIX=openreader
 BASE_URL=https://your-app.vercel.app
 AUTH_SECRET=...
 ADMIN_EMAILS=you@example.com  # comma-separated; admins manage TTS + features in-app
+CRON_SECRET=...               # generate with: openssl rand -base64 32
+
+# Heavy compute (required on Vercel in current releases)
+COMPUTE_WORKER_URL=https://<railway-worker-domain>
+COMPUTE_WORKER_TOKEN=...
+
+# Logging (recommended for Vercel log ingestion)
+LOG_FORMAT=json
+LOG_LEVEL=info
 
 # First-boot seed for the TTS shared provider (optional; manage in-app afterwards)
-API_KEY=your_replicate_key
+# API_KEY=your_replicate_key
 # API_BASE only needed for OpenAI-compatible self-hosted providers
 ```
 
+If you also run an external worker service (for example Railway), set these there too:
+
+- `LOG_FORMAT=json`
+- `COMPUTE_LOG_LEVEL=info`
+
 :::note Env vars vs. admin panel (important for Vercel)
 `API_KEY` / `API_BASE` are one-shot bootstrap seeds on first deploy. After boot, manage providers and site features in **Settings → Admin**. Changes there apply on refresh without a redeploy. See [Admin Panel](../configure/admin-panel).
 :::
 
+## 1a. Railway + Synadia quick start (worker mode)
+
+If your Vercel app uses an external compute worker on Railway with Synadia Cloud (NGS):
+
+1. Deploy a Railway service from:
+   - `ghcr.io/richardr1126/openreader-compute-worker:refactor-ppdoclayoutv3-onnx-layout-parsing`
+2. Enable public networking on that Railway service and set:
+   - `COMPUTE_WORKER_URL=https://<railway-worker-domain>` (in Vercel)
+3. Use the same `COMPUTE_WORKER_TOKEN` value in both Vercel and Railway worker env vars.
+
+For complete Railway worker env vars (`NATS_*`, `S3_*`, health checks, and Synadia `.creds` guidance), see [Compute Worker (NATS JetStream)](./compute-worker).
+
 ## 2. First-run admin configuration (recommended)
 
 After the first successful deploy and admin login, open **Settings → Admin** and configure:
@@ -51,23 +79,21 @@ After the first successful deploy and admin login, open **Settings → Admin** a
 - **Shared providers**: create/edit your provider key(s) here (encrypted at rest).
 - **Site features**:
   - `enableDocxConversion=false` on Vercel (`soffice` unavailable).
-  - `enableDestructiveDeleteActions=false` for safer public deployments.
   - `enableTtsProvidersTab=false` if you want shared-provider-only UX.
   - `enableUserSignups=true` unless you explicitly want an invite-only deployment.
   - `restrictUserApiKeys=true` to block user BYOK through the hosted server.
   - `defaultTtsProvider=replicate` (or your preferred shared slug).
   - `showAllProviderModels=false` if you want users locked to each provider's default model.
   - `enableAudiobookExport=true`.
-  - `enableWordHighlight=false` unless your timestamp stack is configured.
 
-## 3. Legacy first-boot seed (optional)
+## 3. Runtime JSON seed (optional)
 
-If you must pre-seed site features via environment variables, the legacy `NEXT_PUBLIC_*` seeds are still supported on first boot only. Prefer the admin panel for ongoing management.
+If you must pre-seed site features/providers at deploy time, use `RUNTIME_SEED_JSON` or `RUNTIME_SEED_JSON_PATH` (versioned JSON seed document). Prefer the admin panel for ongoing management.
 
-See [Environment Variables](../reference/environment-variables#legacy-first-boot-runtime-seeds-optional) for the complete legacy seed list.
+See [Environment Variables](../reference/environment-variables#runtime-json-seed-v4) for schema and examples.
 
 :::warning Auth recommendation
-For internet-exposed Vercel deployments, set both `BASE_URL` and `AUTH_SECRET` — they are also required for the admin panel and for encrypting admin-stored TTS credentials. Running without auth is possible, but not recommended for public environments.
+Set both `BASE_URL` and `AUTH_SECRET` — they are required in v4+ and also required for the admin panel and for encrypting admin-stored TTS credentials.
 :::
 
 :::warning Rotating AUTH_SECRET invalidates admin-stored keys
@@ -80,19 +106,26 @@ For all variables and defaults, see [Environment Variables](../reference/environ
 
 ## 4. Database and data migrations
 
-Vercel deployments do not run `scripts/openreader-entrypoint.mjs`, so automatic startup migrations do not run there.
+Vercel deployments do not run the `@openreader/bootstrap` process, so automatic startup migrations do not run there.
 
 - Run `pnpm migrate` in a controlled environment to apply Drizzle schema migrations to your Postgres DB.
 - Run `pnpm migrate-fs` only when migrating legacy local filesystem data (`docstore/documents_v1`, `docstore/audiobooks_v1`) into object storage + DB rows. Fresh Vercel deployments usually do not need this.
 
-## 5. FFmpeg packaging in Vercel functions
+## 5. Scheduled maintenance tasks
+
+The repository configures `/api/admin/tasks/tick` as a Vercel Cron route. Set `CRON_SECRET`; requests without the matching bearer token are rejected.
+
+The checked-in Hobby-compatible schedule invokes the route once daily. The admin task panel therefore prevents selecting intervals shorter than one day on Vercel, even though self-hosted deployments can run tasks more frequently.
+
+Each due task is claimed with a database-backed lease, due tasks start independently, and individual runs are aborted and marked failed after four minutes. Review failures and run tasks manually from **Settings → Admin → Scheduled tasks**.
+
+## 6. FFmpeg packaging in Vercel functions
 
 `ffmpeg-static` binaries must be included in function traces. This repo already does that in `next.config.ts` via `outputFileTracingIncludes` for:
 
 - `/api/audiobook`
 - `/api/audiobook/chapter`
-- `/api/audiobook/status`
-- `/api/whisper`
+- `/api/tts/segments/ensure`
 
 :::info
 `serverExternalPackages` should include `ffmpeg-static` so package paths resolve at runtime instead of being bundled into route output.
@@ -100,7 +133,7 @@ Vercel deployments do not run `scripts/openreader-entrypoint.mjs`, so automatic
 
 If you change route paths or split handlers, update `outputFileTracingIncludes` accordingly.
 
-## 6. Function memory sizing
+## 7. Function memory sizing
 
 FFmpeg workloads benefit from more memory/CPU. This repo includes:
 
@@ -109,21 +142,22 @@ FFmpeg workloads benefit from more memory/CPU. This repo includes:
   "$schema": "https://openapi.vercel.sh/vercel.json",
   "functions": {
     "app/api/audiobook/route.ts": { "memory": 3009 },
-    "app/api/whisper/route.ts": { "memory": 3009 }
+    "app/api/tts/segments/ensure/route.ts": { "memory": 3009 }
   }
 }
 ```
 
 Adjust memory per route if your files are larger or your plan differs.
 
-## 7. Runtime expectations and caveats
+## 8. Runtime expectations and caveats
 
 - Audiobook APIs require S3 configuration; otherwise they return `503`.
 - For production Vercel deploys, use `POSTGRES_URL` instead of SQLite.
 
-## 8. Smoke test after deploy
+## 9. Smoke test after deploy
 
 1. Upload and read a PDF/EPUB document.
 2. Confirm sync/blob fetch works across refreshes/devices.
 3. Generate at least one audiobook chapter and play/download it.
-4. If using word highlighting, verify timestamps are produced and rendered.
+4. Verify worker-backed word highlighting and PDF parsing.
+5. Open **Settings → Admin → Scheduled tasks**, run one task manually, and confirm the next daily cron invocation succeeds.

docs-site/docs/docker-quick-start.md

@@ -22,12 +22,18 @@ OpenReader currently pins embedded SeaweedFS to `4.18` in CI and Docker builds.
 `4.19` introduced intermittent `InternalError` responses on S3 `PutObject` in our upload flow.
 :::
 
+## Published images
+
+- App server: `ghcr.io/richardr1126/openreader:latest`
+- Compute worker (Optional): `ghcr.io/richardr1126/openreader-compute-worker:latest`
+- Legacy app alias: `ghcr.io/richardr1126/openreader-webui:latest`
+
 ## 1. Start the Docker container
 
 <Tabs groupId="docker-start-mode">
 <TabItem value="localhost" label="Localhost" default>
 
-Persistent storage, embedded SeaweedFS `weed mini`, optional auth, optional library mount:
+Persistent storage, embedded SeaweedFS `weed mini`, required auth, optional library mount:
 
 ```bash
 docker run --name openreader \
@@ -35,11 +41,9 @@ docker run --name openreader \
   -p 3003:3003 \
   -p 8333:8333 \
   -v openreader_docstore:/app/docstore \
-  -v /path/to/your/library:/app/docstore/library:ro \
   -e API_BASE=http://host.docker.internal:8880/v1 \
-  -e API_KEY=none \
   -e BASE_URL=http://localhost:3003 \
-  -e AUTH_SECRET=$(openssl rand -hex 32) \
+  -e AUTH_SECRET=$(openssl rand -base64 32) \
   -e ADMIN_EMAILS=you@example.com \
   ghcr.io/richardr1126/openreader:latest
 ```
@@ -49,9 +53,8 @@ What this command enables:
 - `-p 3003:3003`: exposes the OpenReader web app/API.
 - `-p 8333:8333`: exposes embedded SeaweedFS S3 endpoint for direct browser presigned upload/download.
 - `-v openreader_docstore:/app/docstore`: persists SQLite metadata, SeaweedFS blob data, and migration/runtime state.
-- `-v /path/to/your/library:/app/docstore/library:ro`: mounts a read-only importable library source.
-- `-e API_BASE=...` / `-e API_KEY=...`: **first-boot seed only.** On the first container start, these are auto-migrated into a `default-openai` admin shared provider stored in the DB (key encrypted at rest). After that, the running app no longer reads them — manage the provider from **Settings → Admin → Shared providers**. See [Admin Panel](./configure/admin-panel).
-- `-e BASE_URL=...` and `-e AUTH_SECRET=...`: together they turn on auth/session mode for local sign-in flows.
+- `-e API_BASE=...` / optional `-e API_KEY=...`: **first-boot seed only.** On the first container start, these are auto-migrated into a `default-openai` admin shared provider stored in the DB (key encrypted at rest when provided). After that, the running app no longer reads them — manage the provider from **Settings → Admin → Shared providers**. See [Admin Panel](./configure/admin-panel).
+- `-e BASE_URL=...` and `-e AUTH_SECRET=...`: required for v4+ auth/session startup.
 - `-e ADMIN_EMAILS=...`: (optional, requires auth) comma-separated emails auto-promoted to admin. Admins see the **Admin** tab in Settings.
 
 </TabItem>
@@ -67,7 +70,7 @@ docker run --name openreader \
   -v openreader_docstore:/app/docstore \
   -e API_BASE=http://host.docker.internal:8880/v1 \
   -e BASE_URL=http://<YOUR_LAN_IP>:3003 \
-  -e AUTH_SECRET=$(openssl rand -hex 32) \
+  -e AUTH_SECRET=$(openssl rand -base64 32) \
   -e AUTH_TRUSTED_ORIGINS=http://localhost:3003,http://127.0.0.1:3003 \
   -e USE_ANONYMOUS_AUTH_SESSIONS=true \
   -e ADMIN_EMAILS=you@example.com \
@@ -83,39 +86,43 @@ What this command enables:
 - `AUTH_TRUSTED_ORIGINS` allows localhost loopback origins in addition to your primary LAN origin.
 - `USE_ANONYMOUS_AUTH_SESSIONS=true` allows guest sessions while auth is enabled.
 - `API_BASE` seeds the default TTS endpoint into the admin-managed `default-openai` shared provider on first boot. Edit it from **Settings → Admin → Shared providers** after that.
+- `API_KEY` optionally seeds the default provider's key (encrypted at rest). Omit it for an upstream that does not require authentication.
 - `ADMIN_EMAILS=...` (optional) auto-promotes the listed email(s) to admin so they can manage shared providers and site feature flags from the UI.
 - `openreader_docstore` volume keeps data persistent across restarts.
 
 </TabItem>
 <TabItem value="minimal" label="Minimal">
 
-Auth disabled, embedded storage ephemeral, no library import:
+Auth required, embedded storage ephemeral, no library import:
 
 ```bash
 docker run --name openreader \
   --restart unless-stopped \
   -p 3003:3003 \
   -p 8333:8333 \
+  -e BASE_URL=http://localhost:3003 \
+  -e AUTH_SECRET=$(openssl rand -base64 32) \
   ghcr.io/richardr1126/openreader:latest
 ```
 
 What this command enables:
 
-- Fastest startup with no extra env vars.
+- Fast startup with only the required auth env vars.
 - No persistent volume (`/app/docstore` stays container-local), so data is ephemeral unless you add a mount.
-- Auth remains disabled because `BASE_URL` and `AUTH_SECRET` are not set. The admin panel requires auth, so it's unavailable in this mode.
-- No TTS provider preset by default. Configure `API_BASE`/`API_KEY` on first boot if you want a seeded shared provider, or run auth+admin mode and manage providers from the admin panel.
+- The app still requires `BASE_URL` + `AUTH_SECRET` in v4+, so include them even in minimal mode.
+- No TTS provider preset by default. Configure `API_BASE` and, when required, `API_KEY` on first boot if you want a seeded shared provider, or run auth+admin mode and manage providers from the admin panel.
 
 </TabItem>
 </Tabs>
 
 :::tip Quick Tips
 - Set `API_BASE` on first boot to a TTS endpoint the container can reach (`host.docker.internal` works for host-local services). After first boot, manage providers in **Settings → Admin → Shared providers**.
-- Auth is enabled only when both `BASE_URL` and `AUTH_SECRET` are set. The admin panel requires auth.
+- `BASE_URL` and `AUTH_SECRET` are required in v4+. The admin panel requires auth.
 - Set `ADMIN_EMAILS` to your email if you want the **Admin** tab in Settings.
-- `restrictUserApiKeys` controls shared-provider-only mode. For per-user BYOK in auth-enabled setups, toggle it off in **Settings → Admin → Site features**. Legacy first-boot seed via `NEXT_PUBLIC_RESTRICT_USER_API_KEYS=false` is still supported.
+- `restrictUserApiKeys` controls shared-provider-only mode. For per-user BYOK, toggle it off in **Settings → Admin → Site features** or seed `runtimeConfig.restrictUserApiKeys=false` via runtime seed JSON.
 - Use a `/app/docstore` mount if you want data to survive container/image replacement.
 - Startup automatically runs DB/storage migrations via the shared entrypoint.
+- Scheduled maintenance tasks run in-process and can be managed from **Settings → Admin → Scheduled tasks**; Docker/self-hosted deployments do not need `CRON_SECRET`.
 :::
 
 :::warning Port `8333` Exposure
@@ -135,6 +142,7 @@ Visit [http://localhost:3003](http://localhost:3003) after startup.
 ## 3. Update Docker image
 
 Legacy image compatibility: `ghcr.io/richardr1126/openreader-webui:latest` remains available as an alias.
+For external compute mode image details, see [Compute Worker (NATS JetStream)](./deploy/compute-worker).
 
 ```bash
 docker stop openreader || true && \

docs-site/docs/introduction.md

@@ -4,7 +4,7 @@ title: Introduction
 slug: /
 ---
 
-OpenReader is an open source text-to-speech document reader built with Next.js. It provides a read-along experience with narration for **EPUB, PDF, TXT, MD, and DOCX documents**.
+OpenReader is an open-source text-to-speech document reader built with Next.js. It provides a multilingual read-along experience with narration for **EPUB, PDF, TXT, MD, and DOCX documents**.
 
 > Previously named **OpenReader-WebUI**.
 
@@ -12,28 +12,22 @@ It supports multiple TTS providers including OpenAI, Replicate, DeepInfra, and c
 
 ## ✨ Highlights
 
+- 🧱 **Layout-aware PDF Parsing**
+  - PP-DocLayoutV3 (ONNX) detects structured blocks with cross-page stitching and geometry-based highlighting for precise read-along sync and clean TTS segmentation
+- ⏱️ **Word-by-word Highlighting** via ONNX Whisper alignment
+  - Powered by the external compute worker control plane (NATS JetStream-backed)
+- ⚡ **Segment-based TTS Playback**
+  - Sentence-aware generation with cached audio segments, background preloading, and resumable playback across EPUB, PDF, TXT, MD, and DOCX
 - 🎯 **Multi-Provider TTS Support**
-  - [**Kokoro-FastAPI**](https://github.com/remsky/Kokoro-FastAPI): supports multi-voice combinations (for example `af_heart+af_bella`)
-  - [**KittenTTS-FastAPI**](https://github.com/richardr1126/KittenTTS-FastAPI): lightweight, CPU-friendly self-hosted TTS
-  - [**Orpheus-FastAPI**](https://github.com/Lex-au/Orpheus-FastAPI)
-  - **Custom OpenAI-compatible**: any TTS API with `/v1/audio/voices` and `/v1/audio/speech` endpoints
-  - **Cloud TTS providers**:
-    - [**Replicate**](https://replicate.com/explore): includes a built-in catalog and supports any Replicate model ID via `Other`
-    - [**DeepInfra**](https://deepinfra.com/models/text-to-speech): Kokoro-82M and other hosted models
-    - [**OpenAI API**](https://platform.openai.com/docs/pricing#transcription-and-speech): `tts-1`, `tts-1-hd`, and `gpt-4o-mini-tts`
-- 📖 **Read Along Experience**
-  - Real-time highlighting for PDF/EPUB, with optional word-level [whisper.cpp](https://github.com/ggml-org/whisper.cpp) timestamps
-- 🛜 **Document Storage**
-  - Documents are persisted in server blob/object storage for consistent access
-- ⚡ **Segment-based TTS Playback** for reusable generation + preloading
-  - Stores segment audio in object storage for fast replay/resume
+  - Self-hosted: [**Kokoro-FastAPI**](https://github.com/remsky/Kokoro-FastAPI) (multi-voice combinations), [**KittenTTS-FastAPI**](https://github.com/richardr1126/KittenTTS-FastAPI), [**Orpheus-FastAPI**](https://github.com/Lex-au/Orpheus-FastAPI), or any custom OpenAI-compatible endpoint
+  - Cloud: [**OpenAI**](https://platform.openai.com/docs/pricing#transcription-and-speech) (`tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`), [**Replicate**](https://replicate.com/explore) (built-in catalog + any model ID), [**DeepInfra**](https://deepinfra.com/models/text-to-speech) (Kokoro-82M and others)
+- 🌐 **Multilingual Support**
+  - Choose a document language for language-aware narration and highlighting
+  - Available languages depend on the configured provider, model, and voice
 - 🎧 **Audiobook Export** in `m4b`/`mp3` with resumable chapter generation
-- 🔐 **Auth Optional by Design**
-  - Run no-auth for local use, or enable auth with user isolation and claim flow
-- 🗂️ **Flexible Storage and Database Modes** with embedded defaults or external S3/Postgres
-- 🚀 **Production-ready Server Behavior** with TTS caching/retries/rate limits and startup migrations
-- 🎨 **Customizable Experience**
-  - 13 built-in themes (light and dark palettes), TTS, and document handling controls
+- 🗂️ **Flexible Backend** — embedded SeaweedFS or S3-compatible storage, SQLite or Postgres, server library import, and device sync
+- 🔐 **Auth and User Isolation** — auth is required in v4+, with optional anonymous auth sessions for guest flows
+- 🎨 **Customizable** — 13 built-in themes (light and dark palettes), per-user TTS settings, and document handling controls
 
 ## 🧭 Key Docs
 

docs-site/docs/reference/environment-variables.md

@@ -3,41 +3,30 @@ title: Environment Variables
 toc_max_heading_level: 3
 ---
 
-This is the single reference page for OpenReader environment variables.
+This page is the source-of-truth reference for OpenReader environment variables.
 
 :::note Recommended configuration path
-For auth-enabled deployments, use **Settings → Admin** as the primary source of truth for shared TTS providers and site features. Legacy env vars (`API_KEY`, `API_BASE`, and `NEXT_PUBLIC_*`) are optional first-boot seeds only.
+Use **Settings → Admin** as the primary source of truth for shared providers and runtime site features.
+`API_BASE` / `API_KEY` are optional one-time provider bootstrap seeds.
+Runtime site features are seeded with `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH`.
 :::
 
 ## Quick Reference Table
 
 | Variable | Area | Default | When to set |
 | --- | --- | --- | --- |
-| `ADMIN_EMAILS` | Auth/Admin | empty | Comma-separated emails auto-promoted to admin (requires auth enabled) |
-| `API_BASE` | Legacy bootstrap seed | none | Optional first-boot seed into `default-openai`; then manage in Settings → Admin → Shared providers |
-| `API_KEY` | Legacy bootstrap seed | none | Optional first-boot seed into `default-openai`; then manage in Settings → Admin → Shared providers |
-| `NEXT_PUBLIC_*` runtime seeds | Legacy bootstrap seed | varies | Optional first-boot seeds for site features; then manage in Settings → Admin → Site features |
-| `NEXT_PUBLIC_CHANGELOG_FEED_URL` | Legacy bootstrap seed | `https://docs.openreader.richardr.dev/changelog/manifest.json` | Optional first-boot seed for changelog feed URL; then manage in Settings → Admin → Site features |
-| `NEXT_PUBLIC_ENABLE_USER_SIGNUPS` | Legacy bootstrap seed | `true` | Optional first-boot seed for whether new accounts can be created; then manage in Settings → Admin → Site features |
-| `TTS_CACHE_MAX_SIZE_BYTES` | TTS caching | `268435456` (256 MB) | Tune in-memory TTS cache size |
-| `TTS_CACHE_TTL_MS` | TTS caching | `1800000` (30 min) | Tune in-memory TTS cache TTL |
-| `TTS_MAX_RETRIES` | TTS retry | `2` | Tune retry attempts for upstream 429/5xx |
-| `TTS_RETRY_INITIAL_MS` | TTS retry | `250` | Tune initial retry delay |
-| `TTS_RETRY_MAX_MS` | TTS retry | `2000` | Tune max retry delay |
-| `TTS_RETRY_BACKOFF` | TTS retry | `2` | Tune exponential backoff factor |
-| `TTS_UPSTREAM_TIMEOUT_MS` | TTS request timeout | `285000` | Set max upstream TTS request duration before fail-fast |
-| `TTS_ENABLE_RATE_LIMIT` | Rate limiting | `false` | Set `true` to enable TTS per-user/IP daily character limits |
-| `TTS_DAILY_LIMIT_ANONYMOUS` | Rate limiting | `50000` | Override anonymous per-user daily character limit |
-| `TTS_DAILY_LIMIT_AUTHENTICATED` | Rate limiting | `500000` | Override authenticated per-user daily character limit |
-| `TTS_IP_DAILY_LIMIT_ANONYMOUS` | Rate limiting | `100000` | Override anonymous IP backstop daily limit |
-| `TTS_IP_DAILY_LIMIT_AUTHENTICATED` | Rate limiting | `1000000` | Override authenticated IP backstop daily limit |
-| `BASE_URL` | Auth | unset | Required (with `AUTH_SECRET`) to enable auth |
-| `AUTH_SECRET` | Auth | unset | Required (with `BASE_URL`) to enable auth |
+| `LOG_FORMAT` | Runtime logging | `pretty` | Set `json` for structured logs |
+| `LOG_LEVEL` | Runtime logging | `info` | Set app server log level |
+| `API_BASE` | TTS provider bootstrap seed | unset | Optional first-boot base URL for `default-openai` |
+| `API_KEY` | TTS provider bootstrap seed | unset | Optional first-boot API key for `default-openai` |
+| `BASE_URL` | Auth | unset | Required at startup |
+| `AUTH_SECRET` | Auth | unset | Required at startup |
 | `AUTH_TRUSTED_ORIGINS` | Auth | empty | Add extra allowed origins |
-| `USE_ANONYMOUS_AUTH_SESSIONS` | Auth | `false` | Set `true` to enable anonymous auth sessions |
+| `USE_ANONYMOUS_AUTH_SESSIONS` | Auth | `false` | Set `true` to allow anonymous auth sessions |
 | `GITHUB_CLIENT_ID` | Auth/OAuth | unset | Set with `GITHUB_CLIENT_SECRET` to enable GitHub sign-in |
 | `GITHUB_CLIENT_SECRET` | Auth/OAuth | unset | Set with `GITHUB_CLIENT_ID` to enable GitHub sign-in |
-| `DISABLE_AUTH_RATE_LIMIT` | Rate limiting | `false` | Set `true` to disable auth-layer rate limiting |
+| `ADMIN_EMAILS` | Admin | empty | Comma-separated emails auto-promoted to admin |
+| `CRON_SECRET` | Scheduled tasks | unset | Required for Vercel cron invocations |
 | `POSTGRES_URL` | Database | unset (SQLite mode) | Set to switch metadata/auth DB to Postgres |
 | `USE_EMBEDDED_WEED_MINI` | Storage | `true` when unset | Set `false` to use external S3-compatible storage only |
 | `WEED_MINI_DIR` | Storage | `docstore/seaweedfs` | Override embedded SeaweedFS data directory |
@@ -49,176 +38,121 @@ For auth-enabled deployments, use **Settings → Admin** as the primary source o
 | `S3_ENDPOINT` | Storage | derived in embedded mode | Set for S3-compatible providers (MinIO/SeaweedFS/R2/etc.) |
 | `S3_FORCE_PATH_STYLE` | Storage | `true` in embedded mode | Set per provider requirement |
 | `S3_PREFIX` | Storage | `openreader` | Customize object key prefix |
-| `RUN_DRIZZLE_MIGRATIONS` | Database migrations | `true` | Set `false` to skip startup Drizzle schema migrations |
-| `RUN_FS_MIGRATIONS` | Storage migrations | `true` | Set `false` to skip startup filesystem -> S3/DB migration pass |
 | `IMPORT_LIBRARY_DIR` | Library import | `docstore/library` fallback | Set a single server library root |
 | `IMPORT_LIBRARY_DIRS` | Library import | unset | Set multiple roots (comma/colon/semicolon separated) |
-| `WHISPER_CPP_BIN` | Word timing | unset | Set to enable `whisper.cpp` timestamps |
+| `EMBEDDED_COMPUTE_WORKER_PORT` | Compute | `8081` | Override embedded worker bind port |
+| `EMBEDDED_NATS_PORT` | Compute | `4222` | Override embedded NATS client port |
+| `EMBEDDED_NATS_MONITOR_PORT` | Compute | `8222` | Override embedded NATS monitor port |
+| `EMBEDDED_NATS_STORE_DIR` | Compute | `docstore/nats/jetstream` | Override embedded JetStream storage directory |
+| `NATS_URL` | Compute | `nats://127.0.0.1:4222` in embedded startup | Override embedded startup or set standalone worker URL |
+| `COMPUTE_LOG_LEVEL` | Compute | `info` | Compute worker log level |
+| `COMPUTE_JOB_CONCURRENCY` | Compute | `1` | Shared compute concurrency cap |
+| `COMPUTE_WHISPER_TIMEOUT_MS` | Compute | `30000` | Whisper alignment timeout budget |
+| `COMPUTE_PDF_TIMEOUT_MS` | Compute | `300000` | PDF parse timeout budget |
+| `COMPUTE_PDF_JOB_ATTEMPTS` | Compute | `1` | Max JetStream deliveries for PDF layout jobs |
+| `COMPUTE_OP_STALE_MS` | Compute | `max(30m, 4x max compute timeout)` | Shared stale window for compute op replacement |
+| `WHISPER_MODEL_BASE_URL` | Compute model source | onnx-community default | Override Whisper ONNX model base URL |
+| `PDF_LAYOUT_MODEL_BASE_URL` | Compute model source | PP-DocLayoutV3 default | Override PDF layout ONNX model base URL |
+| `COMPUTE_WORKER_URL` | External compute mode | unset | Set only for standalone external worker mode |
+| `COMPUTE_WORKER_TOKEN` | External compute mode | unset | Required for standalone external worker auth |
 | `FFMPEG_BIN` | Audio runtime | auto-detected (`ffmpeg-static`) | Override ffmpeg binary path |
+| `DISABLE_AUTH_RATE_LIMIT` | Auth request throttling | `false` | Set `true` to disable Better Auth request rate limiting |
+| `ENABLE_TEST_NAMESPACE` | Testing/CI | unset | Honor `x-openreader-test-namespace` header in production builds |
+| `RUN_DRIZZLE_MIGRATIONS` | DB migrations | `true` | Set `false` to skip startup Drizzle migrations |
+| `RUN_FS_MIGRATIONS` | Storage migrations | `true` | Set `false` to skip startup filesystem -> S3/DB migration pass |
+| `RUNTIME_SEED_JSON_PATH` | Runtime JSON seed | unset | Absolute path to first-boot JSON seed document |
+| `RUNTIME_SEED_JSON` | Runtime JSON seed | unset | Inline first-boot JSON seed document |
 
+## Runtime Logging
 
+### LOG_FORMAT
+
+Controls log output format for server-side Pino loggers.
+
+- Default: `pretty`
+- Allowed values: `pretty`, `json`
+- Applies to app server and compute worker
+
+### LOG_LEVEL
+
+App server log level.
+
+- Default: `info`
 
 ## TTS Provider and Request Behavior
 
 ### API_BASE
 
-Bootstrap base URL for the legacy OpenAI-compatible TTS endpoint.
+Optional first-boot bootstrap base URL for the auto-created `default-openai` shared provider.
 
 - Example: `http://host.docker.internal:8880/v1`
-- **Seeded on first boot** into the auto-created `default-openai` shared provider, then no longer read by the running app. Manage in **Settings → Admin → Shared providers** afterwards.
-- Related docs: [Admin Panel](../configure/admin-panel), [TTS Providers](../configure/tts-providers)
+- Read only for provider bootstrap when shared providers are empty. Setting `API_BASE` is sufficient; `API_KEY` may be blank.
+- After bootstrap, provider configuration is DB-backed and managed in **Settings → Admin → Shared providers**.
 
 ### API_KEY
 
-Bootstrap API key for the legacy OpenAI-compatible TTS endpoint.
+Optional first-boot bootstrap API key for the auto-created `default-openai` shared provider.
 
-- Example: your provider token, or omit if the provider doesn't require auth
-- **Seeded on first boot** into the auto-created `default-openai` shared provider (encrypted at rest), then no longer read by the running app. Manage in **Settings → Admin → Shared providers** afterwards.
-- Related docs: [Admin Panel](../configure/admin-panel), [TTS Providers](../configure/tts-providers)
-
-### TTS_CACHE_MAX_SIZE_BYTES
-
-Maximum in-memory TTS audio cache size in bytes.
-
-- Default: `268435456` (256 MB)
-
-### TTS_CACHE_TTL_MS
-
-In-memory TTS audio cache TTL in milliseconds.
-
-- Default: `1800000` (30 minutes)
-
-### TTS_MAX_RETRIES
-
-Maximum retries for upstream TTS failures (429/5xx).
-
-- Default: `2`
-
-### TTS_RETRY_INITIAL_MS
-
-Initial retry delay in milliseconds for TTS upstream requests.
-
-- Default: `250`
-
-### TTS_RETRY_MAX_MS
-
-Maximum retry delay in milliseconds.
-
-- Default: `2000`
-
-### TTS_RETRY_BACKOFF
-
-Exponential backoff multiplier between retries.
-
-- Default: `2`
-
-### TTS_UPSTREAM_TIMEOUT_MS
-
-Maximum upstream TTS request timeout in milliseconds.
-
-- Default: `285000` (285 seconds)
-- Applies to outbound provider calls from server routes using shared TTS generation
-- Increase for slower providers/models; decrease to fail fast and surface retryable errors sooner
-
-### TTS_ENABLE_RATE_LIMIT
-
-Controls TTS character rate limiting in the TTS API.
-
-- Default: `false` (TTS char limits disabled)
-- Set to `true` to enforce `TTS_DAILY_LIMIT_*` and `TTS_IP_DAILY_LIMIT_*`
-- For behavior details and examples, see [TTS Rate Limiting](../configure/tts-rate-limiting)
-
-### TTS_DAILY_LIMIT_ANONYMOUS
-
-Anonymous per-user daily character limit.
-
-- Default: `50000`
-
-### TTS_DAILY_LIMIT_AUTHENTICATED
-
-Authenticated per-user daily character limit.
-
-- Default: `500000`
-
-### TTS_IP_DAILY_LIMIT_ANONYMOUS
-
-Anonymous IP backstop daily character limit.
-
-- Default: `100000`
-
-### TTS_IP_DAILY_LIMIT_AUTHENTICATED
-
-Authenticated IP backstop daily character limit.
-
-- Default: `1000000`
+- Read only for provider bootstrap when shared providers are empty.
+- Stored encrypted at rest after bootstrap.
+- After bootstrap, provider configuration is DB-backed and managed in **Settings → Admin → Shared providers**.
 
 ## Auth and Identity
 
 ### BASE_URL
 
-External base URL for this OpenReader instance.
+Required external base URL for this OpenReader instance.
 
-- Required with `AUTH_SECRET` to enable auth
+- Required at startup
 - Example: `http://localhost:3003` or `https://reader.example.com`
-- Related docs: [Auth](../configure/auth)
 
 ### AUTH_SECRET
 
-Secret key used by auth/session handling.
+Required secret key used by auth/session handling.
 
-- Required with `BASE_URL` to enable auth
-- Generate with `openssl rand -hex 32`
-- Also used to HMAC-hash server-side TTS segment text fingerprints
-- Related docs: [Auth](../configure/auth)
+- Required at startup
+- Generate with `openssl rand -base64 32`
 
 ### AUTH_TRUSTED_ORIGINS
 
 Additional allowed origins for auth requests.
 
 - Comma-separated list
-- `BASE_URL` origin is always trusted automatically
-- Related docs: [Auth](../configure/auth)
+- `BASE_URL` origin is trusted automatically
 
 ### USE_ANONYMOUS_AUTH_SESSIONS
 
 Controls whether auth-enabled deployments can create/use anonymous sessions.
 
-- Default: `false` (anonymous sessions disabled)
-- Set `true` to allow anonymous sessions and guest-style flows
-- When `false`, users must sign in or sign up with an account
-- Related docs: [Auth](../configure/auth)
+- Default: `false`
 
 ### GITHUB_CLIENT_ID
 
 GitHub OAuth client ID.
 
-- Enable only with `GITHUB_CLIENT_SECRET`
+- Set with `GITHUB_CLIENT_SECRET`
 
 ### GITHUB_CLIENT_SECRET
 
 GitHub OAuth client secret.
 
-- Enable only with `GITHUB_CLIENT_ID`
-
-### DISABLE_AUTH_RATE_LIMIT
-
-Controls Better Auth rate limiting.
-
-- Default behavior: auth-layer rate limiting enabled
-- Set to `true` to disable auth-layer rate limiting
-- This does not affect TTS character rate limiting
-- Related docs: [Auth](../configure/auth)
+- Set with `GITHUB_CLIENT_ID`
 
 ### ADMIN_EMAILS
 
-Comma-separated list of email addresses that are auto-promoted to admin.
+Comma-separated list of email addresses auto-promoted to admin.
 
-- Default: empty (no admins)
-- Requires auth to be enabled (`AUTH_SECRET` + `BASE_URL`).
-- Matched emails get `user.is_admin = true` on every session resolution; removed emails are demoted on the next session resolve.
-- Admins see a new **Admin** tab in Settings exposing shared TTS providers and site-wide feature toggles. Keys for shared providers are stored encrypted in the DB and never returned to the client.
-- Example: `ADMIN_EMAILS=alice@example.com,bob@example.com`
-- Related docs: [Admin Panel](../configure/admin-panel), [Auth](../configure/auth)
+- Requires auth to be enabled
+- Admins can manage shared providers and runtime site features in-app
+
+### CRON_SECRET
+
+Bearer-token secret for `GET /api/admin/tasks/tick`.
+
+- Required on Vercel so scheduled maintenance tasks can run from the configured Vercel Cron.
+- Vercel automatically sends `Authorization: Bearer <CRON_SECRET>` on cron invocations.
+- Generate a strong random value, for example with `openssl rand -base64 32`.
+- Self-hosted Node.js deployments run the scheduler in-process and do not require this variable.
 
 ## Database and Object Blob Storage
 
@@ -228,7 +162,6 @@ Switches metadata/auth storage from SQLite to Postgres.
 
 - Unset: SQLite at `docstore/sqlite3.db`
 - Set: Postgres mode
-- Related docs: [Database](../configure/database)
 
 ### USE_EMBEDDED_WEED_MINI
 
@@ -236,210 +169,280 @@ Controls embedded SeaweedFS startup.
 
 - Default behavior: treated as enabled when unset
 - Set `false` to rely on external S3-compatible storage
-- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
 
 ### WEED_MINI_DIR
 
 Data directory for embedded SeaweedFS (`weed mini`).
 
 - Default: `docstore/seaweedfs`
-- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
 
 ### WEED_MINI_WAIT_SEC
 
-Maximum seconds to wait for embedded SeaweedFS startup.
+Max wait time for embedded SeaweedFS startup.
 
 - Default: `20`
-- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
 
 ### S3_ACCESS_KEY_ID
 
-Access key for S3-compatible storage.
+S3 access key.
 
-- Auto-generated in embedded mode if unset
-- Set explicitly for stable credentials or external providers
-- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+- Optional in embedded mode (auto-generated when unset)
+- Required for external S3 mode
 
 ### S3_SECRET_ACCESS_KEY
 
-Secret key for S3-compatible storage.
+S3 secret key.
 
-- Auto-generated in embedded mode if unset
-- Set explicitly for stable credentials or external providers
-- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+- Optional in embedded mode (auto-generated when unset)
+- Required for external S3 mode
 
 ### S3_BUCKET
 
-Bucket name used for document blobs.
+S3 bucket name.
 
-- Default in embedded mode: `openreader-documents`
-- Required for external S3-compatible storage
-- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+- Embedded default: `openreader-documents`
+- Required for external S3 mode
 
 ### S3_REGION
 
-Region used by the S3 client.
+S3 region.
 
-- Default in embedded mode: `us-east-1`
-- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+- Embedded default: `us-east-1`
+- Required for external S3 mode
 
 ### S3_ENDPOINT
 
-Endpoint URL for S3-compatible storage.
+Custom endpoint for S3-compatible providers.
 
-- In embedded mode, defaults to `http://<BASE_URL host>:8333` (or detected host)
-- For AWS S3, usually leave unset
-- For MinIO/SeaweedFS/R2/B2-style APIs, typically set explicitly
-- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+- Optional for AWS
+- Typical for MinIO/SeaweedFS/R2
 
 ### S3_FORCE_PATH_STYLE
 
-Path-style S3 addressing toggle.
+Force path-style S3 URLs.
 
-- Default in embedded mode: `true`
-- Set according to provider requirements
-- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+- Embedded default: `true`
 
 ### S3_PREFIX
 
-Prefix prepended to stored object keys.
+Object key prefix.
 
 - Default: `openreader`
-- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
-
-## Migration Controls
-
-### RUN_DRIZZLE_MIGRATIONS
-
-Controls startup migration execution in shared entrypoint.
-
-- Default: `true`
-- Set `false` to skip automatic startup Drizzle schema migrations
-- Related docs: [Migrations](../configure/migrations), [Database](../configure/database)
-
-### RUN_FS_MIGRATIONS
-
-Controls startup filesystem-to-object-store migration execution in shared entrypoint.
-
-- Default: `true`
-- Runs `scripts/migrate-fs-v2.mjs` at startup after DB migrations
-- Set `false` to skip automatic storage migration pass
-- Related docs: [Migrations](../configure/migrations), [Database](../configure/database), [Object / Blob Storage](../configure/object-blob-storage)
 
 ## Library Import
 
 ### IMPORT_LIBRARY_DIR
 
-Single directory root for server library import.
-
-- Used when `IMPORT_LIBRARY_DIRS` is unset
-- Default fallback root: `docstore/library`
-- Related docs: [Server Library Import](../configure/server-library-import)
+Single library source directory.
 
 ### IMPORT_LIBRARY_DIRS
 
-Multiple library roots for server library import.
+Multiple library roots.
 
-- Separator: comma, colon, or semicolon
-- Takes precedence over `IMPORT_LIBRARY_DIR`
-- Related docs: [Server Library Import](../configure/server-library-import)
+- Supports comma, colon, or semicolon-separated values
 
-## Audio Tooling and Alignment
+## Compute Worker and Model Configuration
 
-### WHISPER_CPP_BIN
+### EMBEDDED_COMPUTE_WORKER_PORT
 
-Absolute path to compiled `whisper.cpp` binary for word-level timestamps.
+Embedded compute worker port.
 
-- Example: `/whisper.cpp/build/bin/whisper-cli`
-- Required only for optional word-by-word highlighting
+- Default: `8081`
+
+### EMBEDDED_NATS_PORT
+
+Embedded NATS client port.
+
+- Default: `4222`
+
+### EMBEDDED_NATS_MONITOR_PORT
+
+Embedded NATS monitor port.
+
+- Default: `8222`
+
+### EMBEDDED_NATS_STORE_DIR
+
+Embedded NATS JetStream data directory.
+
+- Default: `docstore/nats/jetstream`
+
+### NATS_URL
+
+NATS URL used by compute services.
+
+- Embedded startup default: `nats://127.0.0.1:4222`
+
+### COMPUTE_LOG_LEVEL
+
+Compute worker log level.
+
+- Default: `info`
+
+### COMPUTE_JOB_CONCURRENCY
+
+Max concurrent compute jobs per worker.
+
+- Default: `1`
+
+### COMPUTE_WHISPER_TIMEOUT_MS
+
+Whisper alignment timeout budget.
+
+- Default: `30000`
+
+### COMPUTE_PDF_TIMEOUT_MS
+
+PDF parse timeout budget.
+
+- Default: `300000`
+
+### COMPUTE_PDF_JOB_ATTEMPTS
+
+Max JetStream deliveries for PDF layout jobs.
+
+- Default: `1`
+- In embedded worker mode, set this in the root `.env`
+
+### COMPUTE_OP_STALE_MS
+
+Stale operation window before worker/app cleanup logic can replace an op.
+
+- Default: `max(30m, 4x max compute timeout)`
+
+### WHISPER_MODEL_BASE_URL
+
+Base URL for Whisper ONNX model downloads.
+
+### PDF_LAYOUT_MODEL_BASE_URL
+
+Base URL for PDF layout model downloads.
+
+### COMPUTE_WORKER_URL
+
+External compute worker URL.
+
+- Leave unset for embedded worker mode
+
+### COMPUTE_WORKER_TOKEN
+
+Shared token for app-to-external-worker requests.
+
+## Audio Runtime
 
 ### FFMPEG_BIN
 
-Absolute path or executable name for the ffmpeg binary used by audiobook/processing routes.
+Override ffmpeg binary path used for audio processing.
 
-- Resolution order: `FFMPEG_BIN` -> `ffmpeg-static`
-- Example: `/var/task/node_modules/ffmpeg-static/ffmpeg`
+- Used by audiobook processing routes and compute worker Whisper audio decode.
 
-## Legacy First-Boot Runtime Seeds (optional)
+## Testing and CI
 
-These variables exist only as **first-boot seeds** for the admin-managed runtime config. Prefer changing site features from **Settings → Admin → Site features**. Keep these only when you need bootstrap defaults before the first admin login. See [Admin Panel](../configure/admin-panel) for migration behavior.
+### DISABLE_AUTH_RATE_LIMIT
 
-The values are SSR-injected via `window.__OPENREADER_RUNTIME_CONFIG__`, so admin edits take effect for all users on the next page load — no rebuild required (unlike the old `NEXT_PUBLIC_*` build-time pattern).
+Disables Better Auth request rate limiting.
 
-### NEXT_PUBLIC_ENABLE_DOCX_CONVERSION
+- Default: `false`
 
-Controls whether the experimental DOCX-to-PDF conversion and upload feature is enabled.
+### ENABLE_TEST_NAMESPACE
 
-- Default: `true` (enabled)
-- Runtime key: `enableDocxConversion`
+Enables the `x-openreader-test-namespace` header path in production builds.
 
-### NEXT_PUBLIC_ENABLE_DESTRUCTIVE_DELETE_ACTIONS
+## Migration Controls
 
-Controls whether the "Delete all user docs" and other bulk-delete buttons are shown in Settings.
+### RUN_DRIZZLE_MIGRATIONS
 
-- Default: `true` (enabled)
-- Runtime key: `enableDestructiveDeleteActions`
+Controls startup Drizzle schema migrations.
 
-### NEXT_PUBLIC_ENABLE_TTS_PROVIDERS_TAB
+- Default: `true`
+- Set `false` to skip startup migration run
 
-Controls whether the **TTS Provider** section appears in the user-facing Settings modal.
+### RUN_FS_MIGRATIONS
 
-- Default: `true` (enabled)
-- Set `false` to hide provider/model/API controls in the per-user Settings modal (the admin panel is unaffected).
-- Runtime key: `enableTtsProvidersTab`
+Controls startup filesystem-to-S3/DB migration pass.
 
-### NEXT_PUBLIC_ENABLE_USER_SIGNUPS
+- Default: `true`
+- Set `false` to skip startup storage migration run
 
-Controls whether new user accounts can be created.
+## Runtime JSON Seed (v4)
 
-- Default: `true` (enabled)
-- When `false`, new account creation is blocked for email sign-up, first-time OAuth signup, and anonymous-to-account upgrades.
-- Existing users can still sign in.
-- Runtime key: `enableUserSignups`
+### RUNTIME_SEED_JSON_PATH
 
-### NEXT_PUBLIC_RESTRICT_USER_API_KEYS
+Path-based first-boot seed document.
 
-Controls whether users can supply personal API keys/base URLs for built-in providers.
+- If both `RUNTIME_SEED_JSON_PATH` and `RUNTIME_SEED_JSON` are set, path wins.
+- Value must point to a JSON file readable by the app process.
 
-- Default: runtime-dependent
-- When `true`, server routes only use admin-managed shared providers.
-- When `false`, users can use per-user BYOK credentials for built-in providers.
-- Runtime key: `restrictUserApiKeys`
+### RUNTIME_SEED_JSON
 
-### NEXT_PUBLIC_DEFAULT_TTS_PROVIDER
+Inline first-boot seed document.
 
-Sets the default TTS provider for new users.
+- Used only when `RUNTIME_SEED_JSON_PATH` is unset.
+- Must be a JSON object with `version: 1`.
 
-- Default: `custom-openai`
-- Example values: `replicate`, `deepinfra`, `openai`, `custom-openai`, or an admin-defined shared provider slug (e.g. `kokoro-prod`)
-- Runtime key: `defaultTtsProvider`
+Supported top-level keys:
 
-`showAllProviderModels` is a runtime-only admin setting (no env seed). Configure it in **Settings → Admin → Site features**.
+- `version` (required, must be `1`)
+- `runtimeConfig` (optional object, strict-validated against runtime schema)
+- `providers` (optional array of shared provider seed entries)
 
-### NEXT_PUBLIC_CHANGELOG_FEED_URL
+Example:
 
-Sets the changelog manifest URL used by the Settings modal changelog viewer.
+```json
+{
+  "version": 1,
+  "runtimeConfig": {
+    "enableUserSignups": true,
+    "restrictUserApiKeys": true,
+    "defaultTtsProvider": "custom-openai",
+    "enableTtsProvidersTab": true,
+    "enableAudiobookExport": true,
+    "enableDocxConversion": true,
+    "showAllProviderModels": true,
+    "disableTtsRateLimit": true,
+    "ttsDailyLimitAnonymous": 50000,
+    "ttsDailyLimitAuthenticated": 500000,
+    "ttsIpDailyLimitAnonymous": 100000,
+    "ttsIpDailyLimitAuthenticated": 1000000,
+    "ttsCacheMaxSizeBytes": 268435456,
+    "ttsCacheTtlMs": 1800000,
+    "ttsUpstreamMaxRetries": 2,
+    "ttsUpstreamTimeoutMs": 285000,
+    "disableComputeRateLimit": true,
+    "computeParseBurstMax": 8,
+    "computeParseBurstWindowSec": 60,
+    "computeParseSustainedMax": 24,
+    "computeParseSustainedWindowSec": 600,
+    "maxUploadMb": 200,
+    "changelogFeedUrl": "https://docs.openreader.richardr.dev/changelog/manifest.json"
+  },
+  "providers": [
+    {
+      "slug": "default-openai",
+      "displayName": "Default (seeded)",
+      "providerType": "custom-openai",
+      "baseUrl": "http://localhost:8880/v1",
+      "defaultModel": "kokoro",
+      "enabled": true
+    }
+  ]
+}
+```
 
-- Default: `https://docs.openreader.richardr.dev/changelog/manifest.json`
-- Use this in self-hosted deployments when you publish changelog feeds to a custom docs domain/path.
-- Runtime key: `changelogFeedUrl`
+Provider fallback behavior:
 
+- If the JSON seed includes `providers` (including an empty array), `API_BASE` / `API_KEY` fallback is skipped.
+- If the JSON seed does not include a `providers` key, the legacy `API_BASE` / `API_KEY` bootstrap fallback can still create `default-openai` when provider rows are empty. `API_BASE` alone is sufficient for an upstream that does not require authentication.
 
-### NEXT_PUBLIC_ENABLE_AUDIOBOOK_EXPORT
+Precedence summary:
 
-Controls whether audiobook export UI/actions are shown in the client.
+- Runtime reads: admin DB runtime rows override built-in defaults.
+- Seed input (`RUNTIME_SEED_JSON*`) only populates missing runtime rows on first boot; it does not overwrite existing/admin-edited rows.
+- Provider bootstrap order: JSON `providers` section > `API_BASE`/`API_KEY` fallback > no provider bootstrap.
 
-- Default: `true` (enabled)
-- Affects export entry points in PDF/EPUB pages and document settings UI
-- Runtime key: `enableAudiobookExport`
+## Related
 
-### NEXT_PUBLIC_ENABLE_WORD_HIGHLIGHT
-
-Controls word-by-word highlighting UI and timestamp-alignment behavior.
-
-- Default: `true` (enabled)
-- Requires working timestamp generation (for example `WHISPER_CPP_BIN`)
-- Affects:
-  - Word-highlight toggles in document settings
-  - Alignment requests during TTS playback
-- Runtime key: `enableWordHighlight`
+- [Admin Panel](../configure/admin-panel)
+- [TTS Providers](../configure/tts-providers)
+- [Local Development](../deploy/local-development)
+- [Vercel Deployment](../deploy/vercel-deployment)

docs-site/docs/reference/stack.md

@@ -4,9 +4,10 @@ title: Stack
 
 ## Framework
 
-- [Next.js](https://nextjs.org/) 15 (App Router)
+- [Next.js](https://nextjs.org/) 15 (App Router, Turbopack in dev)
 - [React](https://react.dev/) 19
 - [TypeScript](https://www.typescriptlang.org/)
+- [pnpm](https://pnpm.io/) workspaces monorepo
 
 ## Containerization and runtime
 
@@ -17,24 +18,47 @@ title: Stack
 
 - UI: [Tailwind CSS](https://tailwindcss.com), [Headless UI](https://headlessui.com), [@tailwindcss/typography](https://tailwindcss.com/docs/typography-plugin)
 - Interactions: `react-dnd`, `react-dropzone`
+- Server state: [TanStack Query](https://tanstack.com/query) (React Query v5)
 - Authentication: [Better Auth](https://www.better-auth.com/) client SDK
 - Local storage/cache: [Dexie.js](https://dexie.org/) (IndexedDB)
+- Audio playback: [Howler.js](https://howlerjs.com/)
+- Notifications: `react-hot-toast`
 - Document rendering:
   - PDF: [react-pdf](https://github.com/wojtekmaj/react-pdf), [pdf.js](https://mozilla.github.io/pdf.js/)
   - EPUB: [react-reader](https://github.com/gerhardsletten/react-reader), [epubjs](https://github.com/futurepress/epub.js/)
   - Markdown/Text: [react-markdown](https://github.com/remarkjs/react-markdown), [remark-gfm](https://github.com/remarkjs/remark-gfm)
 - Text preprocessing/matching: [compromise](https://github.com/spencermountain/compromise), [cmpstr](https://github.com/remsky/cmpstr)
+- Analytics: [Vercel Analytics](https://vercel.com/analytics)
 
 ## Next.js server
 
 - APIs: Route Handlers for sync, blob/content access, migrations, audiobook export, TTS/Whisper proxying
 - State sync: request-based today (not realtime push updates)
-- Authentication: [Better Auth](https://www.better-auth.com/) server handlers/adapters
+- Authentication: [Better Auth](https://www.better-auth.com/) server handlers/adapters with anonymous session support
 - Metadata DB: [Drizzle ORM](https://orm.drizzle.team/) with SQLite (`better-sqlite3`) by default and optional Postgres (`pg`)
   - App tables are manually maintained in Drizzle schema files
   - Auth tables are auto-generated by the [Better Auth](https://www.better-auth.com/) CLI and migrated alongside app tables via Drizzle
 - Blob storage: embedded [SeaweedFS](https://github.com/seaweedfs/seaweedfs) (`weed mini`) by default, or external S3-compatible storage via AWS SDK v3
-- Audio/processing pipeline: OpenAI-compatible TTS providers, [ffmpeg](https://ffmpeg.org/) for audiobook assembly, optional [whisper.cpp](https://github.com/ggerganov/whisper.cpp) for word timestamps
+- TTS providers: OpenAI-compatible API (`openai` SDK), [Replicate](https://replicate.com/) (`replicate` client), DeepInfra, and custom OpenAI-compatible endpoints — credentials are encrypted at rest
+- Audio pipeline: [ffmpeg](https://ffmpeg.org/) (`ffmpeg-static`) for audiobook assembly, `archiver` for export packaging
+- Utilities: `lru-cache` for in-process caching, `fast-xml-parser` for EPUB/XML parsing, `uuid` for identifier generation, `zod` for schema validation
+
+## External compute worker (optional)
+
+Standalone worker package:
+
+- **`@openreader/compute-worker`** — standalone Node.js compute service containing its private inference and queue runtime
+  - ONNX runtime: `onnxruntime-node` with `@huggingface/tokenizers`
+  - Whisper alignment: `onnx-community/whisper-base_timestamped` (q4) for word-level timestamps
+  - PDF layout: `Bei0001/PP-DocLayoutV3-ONNX` for document block detection and layout parsing
+  - PDF rendering: `pdfjs-dist`, `@napi-rs/canvas` for server-side page rasterization
+  - Utilities: `jszip`, `ffmpeg-static`
+- HTTP server: [Fastify](https://fastify.dev/) v5 with a versioned OpenAPI contract
+  - Job queue + state: [NATS](https://nats.io/) JetStream WorkQueue pull consumers + NATS KV (`jobs.whisper`, `jobs.layout`)
+  - Storage: AWS SDK v3 S3 client for reading/writing blobs
+  - Logging: [Pino](https://getpino.io/)
+  - Validation: [Zod](https://zod.dev/)
+- The Next.js app communicates with the worker only through the versioned HTTP API generated from OpenAPI.
 
 ## Tooling and testing
 
@@ -42,3 +66,4 @@ title: Stack
 - TypeScript
 - [Playwright](https://playwright.dev/) end-to-end tests
 - Drizzle migration/generation scripts
+- [Docusaurus](https://docusaurus.io/) documentation site (`docs-site/`)

docs-site/sidebars.ts

@@ -23,9 +23,11 @@ const sidebars: SidebarsConfig = {
             'configure/tts-provider-guides/kokoro-fastapi',
             'configure/tts-provider-guides/kitten-tts-fastapi',
             'configure/tts-provider-guides/orpheus-fastapi',
+            'configure/tts-provider-guides/supertonic',
             'configure/tts-provider-guides/replicate',
             'configure/tts-provider-guides/deepinfra',
             'configure/tts-provider-guides/openai',
+            'configure/tts-provider-guides/speech-sdk',
             'configure/tts-provider-guides/other',
           ],
         },
@@ -53,7 +55,12 @@ const sidebars: SidebarsConfig = {
     {
       type: 'category',
       label: '🚀 Deploy',
-      items: ['deploy/local-development', 'deploy/vercel-deployment'],
+      items: [
+        'deploy/local-development',
+        'deploy/docker-compose',
+        'deploy/compute-worker',
+        'deploy/vercel-deployment',
+      ],
     },
     {
       type: 'category',

docs-site/versioned_docs/version-v3.0.0/about/acknowledgements.md

@@ -0,0 +1,16 @@
+---
+title: Acknowledgements
+---
+
+This project is built with support from the following open-source projects and tools:
+
+- [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M)
+- [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI)
+- [Better Auth](https://www.better-auth.com/)
+- [SQLite](https://www.sqlite.org/)
+- [PostgreSQL](https://www.postgresql.org/)
+- [SeaweedFS](https://github.com/seaweedfs/seaweedfs)
+- [whisper.cpp](https://github.com/ggerganov/whisper.cpp)
+- [ffmpeg](https://ffmpeg.org)
+- [react-pdf](https://github.com/wojtekmaj/react-pdf)
+- [react-reader](https://github.com/happyr/react-reader)

docs-site/versioned_docs/version-v3.0.0/about/license.md

@@ -0,0 +1,7 @@
+---
+title: License
+---
+
+OpenReader is licensed under the MIT License.
+
+- Repository license file: [LICENSE](https://github.com/richardr1126/openreader/blob/main/LICENSE)

docs-site/versioned_docs/version-v3.0.0/about/support-and-contributing.md

@@ -0,0 +1,19 @@
+---
+title: Support and Contributing
+---
+
+## Feature requests
+
+Use [GitHub Discussions](https://github.com/richardr1126/openreader/discussions) for feature requests and ideas.
+
+## Issues and support
+
+If you encounter a bug, open an issue in [GitHub Issues](https://github.com/richardr1126/openreader/issues).
+
+## Contributing
+
+Contributions are welcome.
+
+- Fork the repository
+- Create your branch
+- Open a pull request with your changes

docs-site/versioned_docs/version-v3.0.0/configure/admin-panel.md

@@ -0,0 +1,120 @@
+---
+title: Admin Panel
+---
+
+The admin panel lets a designated set of users manage **shared TTS providers** and **site-wide feature flags** directly from the Settings modal — without touching env vars or redeploying.
+
+It is gated behind authentication, so you must have auth enabled to use it ([Auth](./auth)).
+
+## Designating admins
+
+Set `ADMIN_EMAILS` to a comma-separated list of emails:
+
+```env
+AUTH_SECRET=...        # required for auth
+BASE_URL=...           # required for auth
+ADMIN_EMAILS=alice@example.com,bob@example.com
+```
+
+On every session resolution the server compares the user's email against this list and writes `user.is_admin = true` (or `false` for emails removed from the list). No restart is required to demote — the next page load picks it up.
+
+When the logged-in user is an admin, an **Admin** tab appears in **Settings → sidebar** with two sub-tabs:
+
+- **Shared providers** — server-side TTS provider instances visible to all users.
+- **Site features** — runtime-editable replacements for what were previously `NEXT_PUBLIC_*` build-time flags.
+
+## Shared TTS providers
+
+Each shared provider is one named instance bound to one of the four built-in provider types (`custom-openai`, `openai`, `replicate`, `deepinfra`). The admin form has:
+
+| Field | Notes |
+| --- | --- |
+| **Slug** | URL-safe identifier exposed to users (e.g. `kokoro-prod`). Must not collide with a built-in id. Lowercase alphanumeric + hyphens. |
+| **Display name** | Shown in the user's provider dropdown, suffixed with "(shared)". |
+| **Provider type** | One of the four built-ins. Determines voice/model resolution. |
+| **Base URL** | Optional. Falls through to the provider type's default when blank. |
+| **API key** | Encrypted at rest with AES-256-GCM (key derived from `AUTH_SECRET` via scrypt). On edit, leave blank to keep the existing key. |
+| **Default model** | Optional. Used as the initial model when a user selects this provider. |
+| **Enabled** | Toggle to hide the provider from non-admin users without deleting it. |
+
+When a non-admin user picks a shared provider in **Settings → TTS Provider**:
+
+- The API key / base URL fields are hidden — those credentials never leave the server.
+- The TTS request still goes through the user's browser, but the server replaces the slug with the matching admin row's decrypted key and base URL before calling the upstream provider.
+- The user's per-request `x-openai-key` / `x-openai-base-url` headers are ignored for shared slugs.
+
+Whether users can supply their own personal built-in provider keys is controlled by the site feature `restrictUserApiKeys`:
+
+- `true`: users are restricted to shared providers only.
+- `false`: users may also use per-user BYOK credentials for built-in providers.
+
+### Auto-seeded "default-openai"
+
+On first boot, if `admin_providers` is empty and the legacy `API_KEY` env var is set, OpenReader creates a single shared provider with:
+
+- slug `default-openai`, displayName `Default (from env)`, providerType `custom-openai`
+- baseUrl from `API_BASE`, apiKey from `API_KEY` (encrypted)
+- defaultModel set to `kokoro` (you can edit it in Admin → Shared providers)
+
+After this seed runs, the legacy `API_KEY` / `API_BASE` env vars are no longer read by the TTS routes — the DB row is authoritative. You can rename, edit, disable, or delete this row like any other from the admin UI, and remove the env vars from your `.env` when convenient.
+
+:::warning Upgrading from v2.2.0
+In v2.2.0 and earlier, `API_KEY` / `API_BASE` were read live by the TTS routes on every request. As of v3.0.0 they are **one-shot seeds** consumed only on the first boot where `admin_providers` is empty. After upgrading, boot the app once and confirm a `default-openai` row exists in **Settings → Admin → Shared providers** with the correct base URL. If it is missing or wrong (e.g. the env vars were not set on first boot, or the table was already non-empty from a pre-release), create or edit the shared provider manually — TTS will not fall back to the env vars.
+:::
+
+## Site features
+
+Runtime-editable settings, one row per key:
+
+| Key | What it controls |
+| --- | --- |
+| `defaultTtsProvider` | Default provider id new users start with (built-in id or shared slug). |
+| `changelogFeedUrl` | Public changelog manifest URL used by the Settings modal changelog panel. |
+| `enableUserSignups` | Controls whether new accounts can be created. Existing accounts can still sign in when this is `false`. |
+| `restrictUserApiKeys` | Restrict user-supplied API keys/base URLs; when `true`, only admin shared providers are allowed. |
+| `enableTtsProvidersTab` | Whether the user-facing TTS Provider tab in Settings is shown. |
+| `showAllProviderModels` | When `false`, users are restricted to each provider's default model (shared provider `defaultModel` or built-in provider default). |
+| `enableWordHighlight` | Enable whisper.cpp word-by-word highlighting during TTS playback. |
+| `enableAudiobookExport` | Show the audiobook export entry points on PDF/EPUB pages. |
+| `enableDocxConversion` | Accept .docx uploads (converted to PDF server-side). |
+| `enableDestructiveDeleteActions` | Show "Delete all data" buttons in the Documents tab (auth-disabled mode). |
+
+Each row shows a source badge:
+
+- **from env** — the value was migrated from the corresponding `NEXT_PUBLIC_*` env var on first boot. Editing it in the UI flips the source to **admin**.
+- **admin** — explicit admin override. Use **Reset** on the row to clear it back to the env-default state.
+- **default** — neither env nor admin set; uses the built-in default.
+
+:::warning Security note for `restrictUserApiKeys`
+Turning `restrictUserApiKeys` off allows user-supplied API keys to flow through this server. Use this only for trusted/self-hosted deployments where that tradeoff is acceptable.
+:::
+
+## Migrating off env vars
+
+The future-direction goal is to remove `NEXT_PUBLIC_*` / `API_KEY` / `API_BASE` from your `.env` entirely. To do that safely:
+
+1. Deploy this version with your existing env values in place.
+2. Boot the app once. Open Settings → Admin and verify:
+   - Each `NEXT_PUBLIC_*` setting appears as **from env**.
+   - A `default-openai` row exists in **Shared providers** (if you had `API_KEY` set).
+3. Remove the env vars from your `.env`.
+4. Redeploy. Behavior is unchanged — the DB is now the source of truth.
+
+You can keep the env vars indefinitely if you prefer; they're only read on the first boot when the corresponding DB row is absent, so there's no harm in leaving them around.
+
+## How keys are protected
+
+- API keys are encrypted in the `admin_providers` table with AES-256-GCM. The encryption key is derived from `AUTH_SECRET` via `scrypt`.
+- The masked-list view (`GET /api/admin/providers`, used by the admin UI itself) returns `••••` + last-4 only — never plaintext or ciphertext.
+- The public list endpoint (`GET /api/tts/shared-providers`, called by every user's browser) returns only `{ slug, displayName, providerType, defaultModel }`. Keys and base URLs are never exposed to the client.
+- Non-admin users cannot enumerate admin providers' credentials or base URLs through any API.
+
+:::danger Rotating `AUTH_SECRET` invalidates all stored admin provider keys
+Because the encryption key for `admin_providers` is derived from `AUTH_SECRET`, changing `AUTH_SECRET` makes every stored API key undecryptable. After rotating it, shared providers will fail to authenticate upstream until you re-enter each provider's API key in **Settings → Admin → Shared providers** (edit the row and paste the key again). There is no automated re-encryption path. If you must rotate `AUTH_SECRET`, plan to re-enter admin provider keys immediately afterward.
+:::
+
+## Related
+
+- [Auth](./auth) — required to use the admin panel.
+- [TTS Providers](./tts-providers) — built-in provider catalog and per-user behavior.
+- [Environment Variables](../reference/environment-variables) — `ADMIN_EMAILS` and the legacy flags that the admin UI replaces.

docs-site/versioned_docs/version-v3.0.0/configure/auth.md

@@ -0,0 +1,70 @@
+---
+title: Auth
+---
+
+This page covers application-level configuration for provider access and authentication.
+
+## Auth behavior
+
+- Auth is enabled only when both `BASE_URL` and `AUTH_SECRET` are set.
+- Remove either value to disable auth.
+- Keep `AUTH_TRUSTED_ORIGINS` empty to trust only `BASE_URL`.
+- Anonymous auth sessions are disabled by default.
+- Set `USE_ANONYMOUS_AUTH_SESSIONS=true` to enable anonymous session flows.
+
+## Runtime modes
+
+OpenReader effectively has three common runtime modes:
+
+- **Auth disabled** (`BASE_URL` or `AUTH_SECRET` unset): no admin panel. Shared providers can still exist via first-boot seeding (`API_KEY`/`API_BASE`), but you cannot manage them in-app.
+- **Auth enabled, non-admin user**: user account/session features are available, but no admin controls.
+- **Auth enabled, admin user**: full **Settings → Admin** access (shared providers + site features).
+
+## Admin role
+
+When auth is enabled, you can designate one or more users as admins via the `ADMIN_EMAILS` env var:
+
+```env
+ADMIN_EMAILS=alice@example.com,bob@example.com
+```
+
+Admins see a new **Admin** tab in **Settings** with two sub-tabs:
+
+- **Shared TTS providers** — server-managed TTS provider instances with encrypted keys, visible to all users.
+- **Site features** — runtime overrides for what were previously `NEXT_PUBLIC_*` build-time flags (including account signup availability, default TTS provider/model, word highlighting, audiobook export, etc.).
+
+Admin assignment is reconciled on every session resolution, so removing an email from `ADMIN_EMAILS` demotes the user on next login without a restart. See [Admin Panel](./admin-panel) for the full reference.
+
+## Route behavior
+
+- `/` is a public landing/onboarding page and remains indexable.
+- `/app` is the protected app home (document list and uploader UI).
+- If auth is enabled and a valid session exists (including anonymous), visiting `/` redirects to `/app`.
+- Protected app routes continue to require auth; when anonymous sessions are disabled and no session exists, users are redirected to `/signin`.
+
+## Related docs
+
+- For auth environment variables: [Environment Variables](../reference/environment-variables#auth-and-identity)
+- For admin role and shared TTS provider config: [Admin Panel](./admin-panel)
+- For TTS character limits and quota behavior: [TTS Rate Limiting](./tts-rate-limiting)
+- For provider-specific guidance: [TTS Providers](./tts-providers)
+- For storage/S3/SeaweedFS behavior: [Object / Blob Storage](./object-blob-storage)
+- For database mode: [Database](./database)
+- For migration behavior and commands: [Migrations](./migrations)
+
+## Sync notes
+
+### Auth enabled
+
+- Settings and reading progress are saved to the server.
+- Updates are not instant push-based sync; they use normal client polling/refresh behavior.
+- If two devices change the same item around the same time, the newest update wins.
+
+### Auth disabled
+
+- Settings and reading progress stay local in the browser (Dexie/IndexedDB).
+- This avoids no-auth cross-browser conflicts, but there is no cross-device sync.
+
+## Claim modal note
+
+- You may still see old anonymous settings/progress available to claim from older deployments.

docs-site/versioned_docs/version-v3.0.0/configure/database.md

@@ -0,0 +1,59 @@
+---
+title: Database
+---
+
+This page covers database mode selection for OpenReader.
+
+## Scope of this page
+
+- Focus: SQL metadata, state, and relational tables.
+- Not covered here: object key layout and blob transport details (see [Object / Blob Storage](./object-blob-storage)).
+
+## Database mode
+
+- SQLite (default): embedded DB at `docstore/sqlite3.db`; good for local/self-host single-instance setups.
+- Postgres: enabled when `POSTGRES_URL` is set; recommended for production/distributed deployments.
+
+## What the database stores
+
+- Document and audiobook metadata/state used by server routes.
+- Auth/session tables (`user`, `session`, `account`, `verification`) when auth is enabled — schema is auto-generated by Better Auth.
+- TTS character usage counters (`user_tts_chars`) for daily rate limiting (when enabled).
+- User settings preferences (`user_preferences`) when auth is enabled.
+- User reading progress (`user_document_progress`) when auth is enabled.
+- Document preview job/asset metadata (`document_previews`) for server-side PDF/EPUB thumbnails.
+- TTS segment metadata (`tts_segments`) for server-side playback caching:
+  - Segment identity + settings hash
+  - Audio object key and duration
+  - Optional alignment payload for word highlighting
+  - Status/error state
+  - Text fingerprint/hash (plaintext segment text is not stored)
+
+App-specific tables are manually maintained in Drizzle schema files, while auth tables are generated by the Better Auth CLI. Both are migrated together via Drizzle. See [Migrations](./migrations) for details.
+
+## What the database does not store
+
+- Raw document file bytes
+- Audiobook audio bytes
+- TTS segment audio bytes
+- Generated preview image bytes
+
+Those payloads live in object storage. SQL stores the metadata, references, and status.
+
+## Related variables
+
+- `POSTGRES_URL`
+
+For database variable behavior, see [Environment Variables](../reference/environment-variables#database-and-object-blob-storage).
+
+## Related docs
+
+- [Migrations](./migrations)
+- [Object / Blob Storage](./object-blob-storage)
+- [Auth](./auth)
+
+## State sync summary
+
+- With auth enabled, settings and reading progress are stored in SQL and synced from the app.
+- With auth disabled, settings and reading progress remain local in the browser.
+- Sync is currently request-based (not realtime push invalidation).

docs-site/versioned_docs/version-v3.0.0/configure/migrations.md

@@ -0,0 +1,150 @@
+---
+title: Migrations
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This page covers migration behavior for both database schema and storage data in OpenReader.
+
+## Startup migration behavior
+
+By default, the shared entrypoint runs migrations automatically before app startup in:
+
+- Docker container startup
+- `pnpm dev`
+- `pnpm start`
+
+Startup migration phases:
+
+- DB schema migrations (`pnpm migrate`)
+- Storage/data migration (`pnpm migrate-fs`) for legacy filesystem content into S3 + DB rows
+
+:::info
+In most setups, you do not need to run migration commands manually because startup handles this automatically.
+:::
+
+### Schema history
+
+Migrations are applied in order. All of the following ship in v3.0.0; an instance upgrading from v2.2.0 applies `0001`–`0004` in a single startup pass.
+
+| Migration | Dialects | What it does |
+| --- | --- | --- |
+| `0001_tts_segments` | SQLite + Postgres | Creates the original single-table `tts_segments` used by server-side TTS segment caching. |
+| `0002_add_segment_key_to_tts_segments` | SQLite + Postgres | Adds the `segment_key` column to `tts_segments` for stable locator-independent segment identity. |
+| `0003_tts_segments_v2_split` | SQLite + Postgres | Replaces `tts_segments` with a normalized two-table model: `tts_segment_entries` (one row per document segment + locator identity) and `tts_segment_variants` (one row per settings combination, holding the cached audio key, status, and alignment). Drops the original `tts_segments` table — no released build (v2.2.0 or earlier) ever populated it, so there is no production data to migrate. |
+| `0004_admin_panel` | SQLite + Postgres | Creates `admin_providers` (encrypted shared TTS provider rows) and `admin_settings` (runtime site-feature config), and adds the `is_admin` column to the `user` table. Backs the [Admin Panel](./admin-panel). |
+
+To skip automatic startup migrations:
+
+- Set `RUN_DRIZZLE_MIGRATIONS=false`
+- Set `RUN_FS_MIGRATIONS=false`
+
+:::warning
+If you disable startup migrations, ensure your deployment process runs migrations before serving traffic.
+:::
+
+## Apply migrations
+
+In most cases, you do not need manual migration commands because startup runs migrations automatically.
+
+`pnpm migrate` applies migrations for one database target:
+
+- Postgres when `POSTGRES_URL` is set
+- SQLite when `POSTGRES_URL` is unset
+
+You can always override the target explicitly with `--config`.
+
+<Tabs groupId="apply-migration-commands">
+  <TabItem value="project-scripts" label="Project Scripts" default>
+
+```bash
+# Run pending migrations for one target:
+# - Postgres if POSTGRES_URL is set
+# - SQLite if POSTGRES_URL is unset
+pnpm migrate
+
+# Run storage migration (filesystem -> S3 + DB)
+pnpm migrate-fs
+
+# Dry-run storage migration without uploading/deleting
+pnpm migrate-fs:dry-run
+```
+
+  </TabItem>
+  <TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
+
+```bash
+# Migrate SQLite
+pnpm exec drizzle-kit migrate --config drizzle.config.sqlite.ts
+
+# Migrate Postgres
+pnpm exec drizzle-kit migrate --config drizzle.config.pg.ts
+```
+
+  </TabItem>
+</Tabs>
+
+## Generate migrations
+
+`pnpm generate` is a two-phase script for contributors and schema changes:
+
+1. **Better Auth schema generation** — runs the Better Auth CLI twice (once for SQLite, once for Postgres) to produce auto-generated Drizzle schema files for auth tables (`user`, `session`, `account`, `verification`).
+2. **Drizzle migration generation** — runs `drizzle-kit generate` for both `drizzle.config.sqlite.ts` and `drizzle.config.pg.ts`, producing SQL migration files from all schema files (app + auth).
+
+:::note
+Most users do not need to run `pnpm generate`. Use it when contributing or when you have changed Drizzle schema files and need new migration files.
+:::
+
+### Schema ownership
+
+Auth tables are owned by Better Auth. Their Drizzle schema definitions are auto-generated and should **not** be hand-edited:
+
+- `src/db/schema_auth_sqlite.ts`
+- `src/db/schema_auth_postgres.ts`
+
+App-specific tables are manually maintained in the standard Drizzle schema files:
+
+- `src/db/schema_sqlite.ts`
+- `src/db/schema_postgres.ts`
+
+Both sets of schema files are included in the Drizzle configs, so `drizzle-kit generate` and `drizzle-kit migrate` handle all tables together.
+
+When app schema changes (for example `tts_segments`), keep these in sync:
+
+- `src/db/schema_sqlite.ts`
+- `src/db/schema_postgres.ts`
+- `drizzle/sqlite/*.sql` + `drizzle/sqlite/meta/_journal.json`
+- `drizzle/postgres/*.sql` + `drizzle/postgres/meta/_journal.json`
+
+<Tabs groupId="generate-migration-commands">
+  <TabItem value="project-script" label="Project Script" default>
+
+```bash
+# Full pipeline: Better Auth CLI + Drizzle generate (both dialects)
+pnpm generate
+```
+
+  </TabItem>
+  <TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
+
+```bash
+# Generate SQLite migrations only (skips Better Auth CLI)
+pnpm exec drizzle-kit generate --config drizzle.config.sqlite.ts
+
+# Generate Postgres migrations only (skips Better Auth CLI)
+pnpm exec drizzle-kit generate --config drizzle.config.pg.ts
+```
+
+:::warning
+Running `drizzle-kit generate` directly skips the Better Auth CLI step. If auth schema has changed upstream (e.g. after a Better Auth version bump), run `pnpm generate` instead to regenerate the auth schema files first.
+:::
+
+  </TabItem>
+</Tabs>
+
+## Related docs
+
+- [Database](./database)
+- [Object / Blob Storage](./object-blob-storage)
+- [Migration Environment Variables](../reference/environment-variables#migration-controls)

docs-site/versioned_docs/version-v3.0.0/configure/object-blob-storage.md

@@ -0,0 +1,167 @@
+---
+title: Object / Blob Storage
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This page documents storage backends, blob upload routing, and core Docker mount behavior.
+
+## Scope of this page
+
+- Focus: object/blob backends, keyspaces, upload/read paths, and storage debugging.
+- Not covered here: relational metadata tables and SQL state modeling (see [Database](./database)).
+
+## Storage backends
+
+- Embedded (default): embedded SeaweedFS (`weed mini`) blob storage.
+- External: external S3-compatible object storage.
+
+Metadata database mode (SQLite vs Postgres) is configured separately in [Database](./database).
+
+:::warning SeaweedFS Compatibility Note (April 16, 2026)
+OpenReader currently pins embedded SeaweedFS to `4.18` in CI and Docker builds.
+`4.19` introduced intermittent `InternalError` responses on S3 `PutObject` in our upload flow.
+:::
+
+Storage variables are documented in [Environment Variables](../reference/environment-variables#database-and-object-blob-storage).
+
+## Ports
+
+- `3003`: OpenReader app and API routes
+- `8333`: Embedded SeaweedFS S3 endpoint for direct browser blob access
+
+:::info
+`8333` is only needed for direct browser presigned access to embedded SeaweedFS.
+:::
+
+## Upload behavior
+
+- Primary path: browser uploads to presigned URL from `/api/documents/blob/upload/presign`.
+- Fallback path: `/api/documents/blob/upload/fallback` when direct upload fails/unreachable.
+- Read/download path: blob/content serving route `/api/documents/blob` (not the upload fallback route).
+- Preview path: `/api/documents/blob/preview` (returns `202` while a preview is generating; serves/redirects when ready).
+
+## Document previews
+
+- PDF/EPUB previews are generated server-side and stored in object storage under `document_previews_v1`.
+- Preview generation is triggered on upload registration and also backfills on first preview request for older docs.
+- Preview artifacts are temporary-cache friendly and can be regenerated from the source document blob.
+
+## FS / Volume Mounts
+
+### App data mount
+
+- Target: `/app/docstore`
+- Recommended: yes, for persistence
+- Purpose: persists SeaweedFS blob data, SQLite metadata DB, migrations, and local runtime temp state
+- Mount string: `-v openreader_docstore:/app/docstore`
+
+### Library source mount (optional)
+
+- Target: `/app/docstore/library`
+- Recommended: optional, use read-only (`:ro`)
+- Purpose: exposes host files as a source for server library import
+- Mount string: `-v /path/to/your/library:/app/docstore/library:ro`
+- Details: [Server Library Import](./server-library-import)
+
+## Private blob endpoint mode
+
+If `8333` is not published externally:
+
+- Document uploads still work through upload fallback proxy
+- Reads/snippets continue through app API routes
+- Direct presigned browser upload/download to embedded endpoint is unavailable
+
+:::warning
+Without `8333`, expect higher app-server traffic because uploads/downloads go through API routes instead of direct object endpoint access.
+:::
+
+## Audiobook Storage Debug Commands
+
+Audiobook assets are stored in object storage under the `audiobooks_v1` keyspace. Use these commands to inspect and download objects for debugging.
+
+<Tabs groupId="audiobook-storage-access-cli">
+  <TabItem value="aws-s3" label="AWS S3" default>
+
+```bash
+# List all audiobook objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive
+
+# Filter to one book id (replace <book-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive | grep "<book-id>-audiobook/"
+
+# Download one object by full key
+aws s3 cp "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/<path>/<file>.m4b" "./audiobook.m4b"
+```
+
+  </TabItem>
+  <TabItem value="s3-compatible" label="Embedded / MinIO / R2 / etc">
+
+```bash
+# List all audiobook objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive --endpoint-url "$S3_ENDPOINT"
+
+# Filter to one book id (replace <book-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive --endpoint-url "$S3_ENDPOINT" | grep "<book-id>-audiobook/"
+
+# Download one object by full key
+aws s3 cp "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/<path>/<file>.m4b" "./audiobook.m4b" --endpoint-url "$S3_ENDPOINT"
+```
+
+Embedded default example: `S3_ENDPOINT=http://127.0.0.1:8333` (or your mapped host/port).
+
+  </TabItem>
+</Tabs>
+
+## TTS Segment Storage
+
+Server-side TTS segment audio is stored in object storage under the `tts_segments_v1` keyspace.
+
+Typical key layout:
+
+- `${S3_PREFIX}/tts_segments_v1/users/<url-encoded-user-id>/docs/<document-id>/<document-version>/<settings-hash>/<segment-id>.mp3`
+- `${S3_PREFIX}/tts_segments_v1/ns/<test-namespace>/users/<url-encoded-user-id>/docs/...` (test namespace mode)
+
+Notes:
+
+- For the corresponding SQL metadata model (`tts_segments`), see [Database](./database).
+
+## Account Deletion Cleanup
+
+Account deletion performs best-effort object cleanup:
+
+- Document blobs + preview artifacts
+- Audiobook blobs
+- TTS segment blobs under `tts_segments_v1`
+
+If object deletion fails, account deletion still proceeds and orphaned objects may require manual cleanup.
+
+## TTS Segment Storage Debug Commands
+
+Use these commands to inspect segment objects.
+
+<Tabs groupId="tts-segment-storage-access-cli">
+  <TabItem value="aws-s3" label="AWS S3" default>
+
+```bash
+# List all TTS segment objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive
+
+# Filter to one document id (replace <document-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive | grep "/docs/<document-id>/"
+```
+
+  </TabItem>
+  <TabItem value="s3-compatible" label="Embedded / MinIO / R2 / etc">
+
+```bash
+# List all TTS segment objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive --endpoint-url "$S3_ENDPOINT"
+
+# Filter to one document id (replace <document-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive --endpoint-url "$S3_ENDPOINT" | grep "/docs/<document-id>/"
+```
+
+  </TabItem>
+</Tabs>

docs-site/versioned_docs/version-v3.0.0/configure/server-library-import.md

@@ -0,0 +1,68 @@
+---
+title: Server Library Import
+---
+
+This page documents how server library import works and how to configure it.
+
+## What it does
+
+Server library import lets you browse files from one or more server directories and import selected files into OpenReader.
+
+- Import is user-driven via a selection modal
+- Only selected files are imported
+- Imported files become normal OpenReader documents
+
+## FS / Volume Mounts
+
+### App data mount
+
+- Target: `/app/docstore`
+- Recommended: yes, for persistence
+- Purpose: stores app runtime data, metadata DB, and embedded storage state
+- Mount string: `-v openreader_docstore:/app/docstore`
+
+### Library source mount
+
+- Target: `/app/docstore/library`
+- Recommended: yes for this feature, use read-only (`:ro`)
+- Purpose: exposes host files as import candidates in Server Library Import
+- Mount string: `-v /path/to/your/library:/app/docstore/library:ro`
+
+## Import flow
+
+1. Open **Settings -> Documents -> Server Library Import**.
+2. Select files in the modal.
+3. Click **Import**.
+
+Selected files are fetched from the server library endpoint and imported into OpenReader storage.
+
+:::warning Shared Library Roots
+Library roots are configured at the server level (not per-user). Any user who can access Server Library Import can browse/import from the same configured roots.
+
+Imported documents are still saved to the importing user's document scope.
+:::
+
+## Supported file types
+
+- `.pdf`
+- `.epub`
+- `.html`, `.htm`
+- `.txt`
+- `.md`, `.mdown`, `.markdown`
+
+## Optional: Configure Library Roots
+
+You only need this when the default mounted path is not what you want.
+
+By default, OpenReader uses `docstore/library` as the import root. You can override that with environment variables:
+
+- `IMPORT_LIBRARY_DIRS` (takes precedence): multiple roots separated by comma, colon, or semicolon
+- `IMPORT_LIBRARY_DIR`: single root
+
+See [Environment Variables](../reference/environment-variables#library-import) for variable details.
+
+## Notes
+
+- Library listing is capped per request (up to 10,000 files).
+- When auth is enabled, library import endpoints require a valid session.
+- The mounted library is a source; removing it does not delete already imported documents.

docs-site/versioned_docs/version-v3.0.0/configure/tts-provider-guides/deepinfra.md

@@ -0,0 +1,42 @@
+---
+title: DeepInfra
+---
+
+Use DeepInfra's hosted TTS models as your provider.
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `deepinfra`.
+2. Keep base URL as `https://api.deepinfra.com/v1/openai`.
+3. Enter your API key.
+4. Set your preferred default model/voice.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=https://api.deepinfra.com/v1/openai
+API_KEY=your-deepinfra-key
+```
+
+**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
+
+1. Set provider to `Deepinfra`.
+2. The base URL is pre-filled, no changes needed.
+3. Enter your `API_KEY`.
+4. Choose a model and voice.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Notes
+
+- Available models include `hexgrad/Kokoro-82M` and `canopylabs/orpheus-3b-0.1-ft`.
+- Without an API key, only the free-tier model (`hexgrad/Kokoro-82M`) is shown in the dropdown.
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
+
+## References
+
+- [DeepInfra TTS models](https://deepinfra.com/models/text-to-speech)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v3.0.0/configure/tts-provider-guides/kitten-tts-fastapi.md

@@ -0,0 +1,47 @@
+---
+title: KittenTTS-FastAPI
+---
+
+Run [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider. Lightweight and CPU-friendly.
+
+## Run KittenTTS
+
+```bash
+docker run -it --rm \
+  --name kittentts-fastapi \
+  -e KITTEN_MODEL_REPO_ID="KittenML/kitten-tts-nano-0.8-fp32" \
+  -p 8005:8005 \
+  ghcr.io/richardr1126/kittentts-fastapi-cpu
+```
+
+## Connect to OpenReader
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set base URL to your KittenTTS endpoint (e.g. `http://kittentts-fastapi:8005/v1`).
+3. Leave API key blank unless required by your deployment.
+4. Set default model to `kitten-tts` (or your backend model id).
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://kittentts-fastapi:8005/v1
+```
+
+> Use `kittentts-fastapi` if that's the container name, or `host.docker.internal` if not.
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your KittenTTS endpoint (e.g. `http://kittentts-fastapi:8005/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `kitten-tts` (or the model your deployment exposes).
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## References
+
+- [richardr1126/KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v3.0.0/configure/tts-provider-guides/kokoro-fastapi.md

@@ -0,0 +1,75 @@
+---
+title: Kokoro-FastAPI
+---
+
+Run [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
+
+:::warning
+For Kokoro issues and support, use the upstream repository: [remsky/Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI).
+:::
+
+## Run Kokoro
+
+**CPU:**
+
+```bash
+docker run --name kokoro-tts \
+  --restart unless-stopped \
+  -d \
+  -p 8880:8880 \
+  -e ONNX_NUM_THREADS=8 \
+  -e ONNX_INTER_OP_THREADS=4 \
+  -e ONNX_EXECUTION_MODE=parallel \
+  -e ONNX_OPTIMIZATION_LEVEL=all \
+  -e ONNX_MEMORY_PATTERN=true \
+  -e ONNX_ARENA_EXTEND_STRATEGY=kNextPowerOfTwo \
+  -e API_LOG_LEVEL=DEBUG \
+  ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
+```
+
+**GPU (NVIDIA):**
+
+```bash
+docker run --name kokoro-tts \
+  --restart unless-stopped \
+  -d \
+  --gpus all \
+  --user 1001:1001 \
+  -p 8880:8880 \
+  -e USE_GPU=true \
+  -e PYTHONUNBUFFERED=1 \
+  -e API_LOG_LEVEL=DEBUG \
+  ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.4
+```
+
+## Connect to OpenReader
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set base URL to your Kokoro endpoint (e.g. `http://kokoro-tts:8880/v1`).
+3. Leave API key blank unless required by your deployment.
+4. Set default model to `Kokoro`.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://kokoro-tts:8880/v1
+```
+
+> Use `kokoro-tts` if that's the container name, or `host.docker.internal` if not.
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your Kokoro endpoint (e.g. `http://kokoro-tts:8880/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `Kokoro`.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## References
+
+- [remsky/Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v3.0.0/configure/tts-provider-guides/openai.md

@@ -0,0 +1,41 @@
+---
+title: OpenAI
+---
+
+Use the OpenAI TTS API as your provider.
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `openai`.
+2. Keep base URL as `https://api.openai.com/v1`.
+3. Enter your API key.
+4. Set your preferred default model/voice.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=https://api.openai.com/v1
+API_KEY=sk-...
+```
+
+**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
+
+1. Set provider to `OpenAI`.
+2. The base URL is pre-filled, no changes needed.
+3. Enter your `API_KEY`.
+4. Choose a model and voice.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Notes
+
+- Models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
+
+## References
+
+- [OpenAI TTS pricing](https://platform.openai.com/docs/pricing#transcription-and-speech)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v3.0.0/configure/tts-provider-guides/orpheus-fastapi.md

@@ -0,0 +1,41 @@
+---
+title: Orpheus-FastAPI
+---
+
+Run [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
+
+## Run Orpheus
+
+Refer to the upstream repository for Docker instructions: [Lex-au/Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI).
+
+## Connect to OpenReader
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set base URL to your Orpheus endpoint (e.g. `http://orpheus:8000/v1`).
+3. Leave API key blank unless required by your deployment.
+4. Set default model to `Orpheus` (or your backend model id).
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://orpheus:8000/v1
+```
+
+> Use the container name if that's how it's named, or `host.docker.internal` if not.
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your Orpheus endpoint (e.g. `http://orpheus:8000/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `Orpheus` (or the model your deployment exposes).
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## References
+
+- [Lex-au/Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v3.0.0/configure/tts-provider-guides/other.md

@@ -0,0 +1,52 @@
+---
+title: Other
+---
+
+Use any OpenAI-compatible TTS service with OpenReader, including self-hosted servers not covered by a dedicated guide.
+
+## Requirements
+
+Your service must expose these endpoints:
+
+- `GET /v1/audio/voices`
+- `POST /v1/audio/speech`
+
+Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS-FastAPI](./kitten-tts-fastapi), [Orpheus-FastAPI](./orpheus-fastapi).
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set `API_BASE` to your service base URL (typically ending in `/v1`).
+3. Set API key if your service requires authentication.
+4. Set a default model/voice supported by your backend.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://your-tts-server/v1
+API_KEY=optional-key-if-required
+```
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your service's base URL (typically ending in `/v1`).
+3. Set `API_KEY` if your service requires authentication.
+4. Choose a model and voice supported by your backend.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+:::warning TTS requests are server-side
+`API_BASE` must be reachable from the **Next.js server**, not just the browser. In Docker, use container names or `host.docker.internal`.
+:::
+
+## Troubleshooting
+
+If voices don't load, check that `/v1/audio/voices` is reachable from the server and returns a valid response shape.
+
+## References
+
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v3.0.0/configure/tts-provider-guides/replicate.md

@@ -0,0 +1,48 @@
+---
+title: Replicate
+---
+
+Use Replicate's hosted TTS models as your provider.
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `replicate`.
+2. Enter your API key.
+3. Set default model to:
+   `alphanumericuser/kokoro-82m:89b6fa84e4fa2dd6bd3a96be3e1f12827a3516c9fda8fddbac7a0be131c9a6f5` (or your preferred model).
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_KEY=r8_...
+```
+
+Then update the shared provider's **Default model** in **Settings → Admin → Shared providers**.
+
+**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
+
+1. Set provider to `Replicate`.
+2. Enter your `API_KEY`.
+3. Choose a model and voice.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Notes
+
+- Built-in Replicate models:
+  - `alphanumericuser/kokoro-82m:89b6fa84e4fa2dd6bd3a96be3e1f12827a3516c9fda8fddbac7a0be131c9a6f5`
+  - `google/gemini-3.1-flash-tts`
+  - `minimax/speech-2.8-turbo`
+  - `qwen/qwen3-tts`
+  - `inworld/tts-1.5-mini`
+- You can also choose `Other` and enter any Replicate model ID (for example `owner/model-name` or `owner/model-name:version`).
+- Native model speed is not available on all Replicate models; OpenReader hides/disables native speed controls where unsupported.
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
+
+## References
+
+- [Replicate](https://replicate.com/explore)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v3.0.0/configure/tts-providers.md

@@ -0,0 +1,57 @@
+---
+title: TTS Providers
+---
+
+OpenReader routes all TTS requests through the Next.js server to an OpenAI-compatible API. There are three places provider configuration can live:
+
+**Admin-managed shared providers** (Settings > Admin > Shared providers): DB-backed instances configured by an admin and visible to all users. Keys are encrypted at rest and never exposed to the client. Available only when [auth is enabled](./auth) and your account is in `ADMIN_EMAILS`. See [Admin Panel](./admin-panel).
+
+**Per-user Settings modal** (Settings > TTS Provider): provider + API key stored in the user's browser and sent with every TTS request. This path is available only when the admin/runtime setting `restrictUserApiKeys=false`.
+
+**Environment variables**: `API_KEY` and `API_BASE` exist as a one-shot first-boot seed that auto-creates a `default-openai` admin shared provider. After the first boot they are no longer read by the running app.
+
+:::tip
+If you're running a private/self-hosted instance and want per-user BYOK behavior, turn off **Settings → Admin → Site features → Restrict user API keys**. Legacy first-boot seed via `NEXT_PUBLIC_RESTRICT_USER_API_KEYS=false` is still supported for no-admin bootstrap flows.
+:::
+
+## Providers
+
+- **OpenAI**: Cloud. Base URL pre-filled (`https://api.openai.com/v1`). API key required.
+- **Replicate**: Cloud. Base URL managed internally by OpenReader. API key required.
+- **DeepInfra**: Cloud. Base URL pre-filled (`https://api.deepinfra.com/v1/openai`). API key required.
+- **Custom OpenAI-Like**: Self-hosted or any custom endpoint. `API_BASE` must be set manually (typically ending in `/v1`). API key optional.
+
+For `OpenAI`, `DeepInfra`, and `Replicate` you only need to supply an API key. For `Custom OpenAI-Like` you must also set `API_BASE`.
+
+## Built-in model catalogs
+
+- **Replicate** models: `alphanumericuser/kokoro-82m`, `google/gemini-3.1-flash-tts`, `minimax/speech-2.8-turbo`, `qwen/qwen3-tts`, `inworld/tts-1.5-mini` (or choose `Other` and enter any Replicate model ID, such as `owner/model` or `owner/model:version`)
+- **OpenAI** models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
+- **DeepInfra** models: includes `hexgrad/Kokoro-82M` and additional hosted models (depending on API key / feature flags)
+
+## Custom provider requirements
+
+Self-hosted or custom providers must expose OpenAI-compatible audio endpoints:
+
+- `GET /v1/audio/voices`
+- `POST /v1/audio/speech`
+
+:::warning TTS requests are server-side
+TTS requests originate from the **Next.js server**, not the browser. `API_BASE` must be reachable from the server runtime. In Docker, use container names or `host.docker.internal` rather than `localhost`.
+:::
+
+## Provider guides
+
+- [Kokoro-FastAPI](./tts-provider-guides/kokoro-fastapi)
+- [KittenTTS-FastAPI](./tts-provider-guides/kitten-tts-fastapi)
+- [Orpheus-FastAPI](./tts-provider-guides/orpheus-fastapi)
+- [Replicate](./tts-provider-guides/replicate)
+- [DeepInfra](./tts-provider-guides/deepinfra)
+- [OpenAI](./tts-provider-guides/openai)
+- [Other](./tts-provider-guides/other)
+
+## Related
+
+- [Admin Panel](./admin-panel) — DB-backed shared providers with encrypted keys
+- [TTS Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
+- [TTS Rate Limiting](./tts-rate-limiting)

docs-site/versioned_docs/version-v3.0.0/configure/tts-rate-limiting.md

@@ -0,0 +1,51 @@
+---
+title: TTS Rate Limiting
+---
+
+This page explains OpenReader's TTS character rate limiting controls.
+
+## Overview
+
+- TTS rate limiting is disabled by default.
+- To enable it, set `TTS_ENABLE_RATE_LIMIT=true`.
+- Limits are enforced per day in UTC.
+- Enforcement applies only when auth is enabled.
+
+## How enforcement works
+
+When enabled, OpenReader enforces:
+
+- Per-user daily character limits.
+- IP backstop daily character limits.
+- Anonymous device backstop tracking (cookie-based) to reduce limit resets.
+
+If a request exceeds the active limit, the TTS API returns `429` with reset metadata for the next UTC day.
+
+## Required auth behavior
+
+- Auth must be enabled (`BASE_URL` + `AUTH_SECRET`) for TTS char limits to apply.
+- If auth is disabled, TTS character limits are effectively unlimited.
+- `DISABLE_AUTH_RATE_LIMIT` only affects Better Auth's own request throttling.
+- `DISABLE_AUTH_RATE_LIMIT` does not disable TTS character limits.
+
+## Environment variables
+
+Enable/disable:
+
+- `TTS_ENABLE_RATE_LIMIT` (default: `false`)
+
+Per-user daily limits:
+
+- `TTS_DAILY_LIMIT_ANONYMOUS` (default: `50000`)
+- `TTS_DAILY_LIMIT_AUTHENTICATED` (default: `500000`)
+
+IP backstop daily limits:
+
+- `TTS_IP_DAILY_LIMIT_ANONYMOUS` (default: `100000`)
+- `TTS_IP_DAILY_LIMIT_AUTHENTICATED` (default: `1000000`)
+
+## Related docs
+
+- TTS/rate-limit environment variables: [Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
+- Auth configuration: [Auth](./auth)
+- Provider setup: [TTS Providers](./tts-providers)

docs-site/versioned_docs/version-v3.0.0/deploy/local-development.md

@@ -0,0 +1,303 @@
+---
+title: Local Development
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Prerequisites
+
+<details>
+<summary><strong>Node.js + pnpm (required)</strong></summary>
+
+<Tabs groupId="local-dev-node-pnpm-os">
+<TabItem value="macos" label="macOS" default>
+
+```bash
+brew install nvm pnpm
+mkdir -p ~/.nvm
+echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
+echo '[ -s "$(brew --prefix nvm)/nvm.sh" ] && . "$(brew --prefix nvm)/nvm.sh"' >> ~/.zshrc
+source ~/.zshrc
+nvm install --lts
+nvm use --lts
+node -v
+pnpm -v
+```
+
+</TabItem>
+<TabItem value="linux" label="Linux">
+
+```bash
+# Debian/Ubuntu example
+sudo apt update
+sudo apt install -y curl
+curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+nvm install --lts
+nvm use --lts
+corepack enable
+corepack prepare pnpm@latest --activate
+node -v
+pnpm -v
+```
+
+</TabItem>
+</Tabs>
+
+</details>
+
+<details>
+<summary><strong>SeaweedFS <code>weed</code> binary (required unless using external S3)</strong></summary>
+
+<Tabs groupId="local-dev-seaweed-os">
+<TabItem value="macos" label="macOS" default>
+
+```bash
+brew install seaweedfs
+weed version
+```
+
+:::warning SeaweedFS Compatibility Note (April 16, 2026)
+If you see intermittent S3 `InternalError` upload failures with embedded storage, use SeaweedFS `4.18`.
+OpenReader currently pins `4.18` in CI and Docker builds while `4.19` compatibility is investigated.
+:::
+
+</TabItem>
+<TabItem value="linux" label="Linux">
+
+```bash
+# Linux amd64 example (pin 4.18)
+mkdir -p "$HOME/.local/bin"
+curl -fsSL -o /tmp/seaweedfs.tar.gz \
+  https://github.com/seaweedfs/seaweedfs/releases/download/4.18/linux_amd64.tar.gz
+tar -xzf /tmp/seaweedfs.tar.gz -C /tmp weed
+install -m 0755 /tmp/weed "$HOME/.local/bin/weed"
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+export PATH="$HOME/.local/bin:$PATH"
+weed version
+```
+
+:::warning SeaweedFS Compatibility Note (April 16, 2026)
+If you see intermittent S3 `InternalError` upload failures with embedded storage, use SeaweedFS `4.18`.
+OpenReader currently pins `4.18` in CI and Docker builds while `4.19` compatibility is investigated.
+:::
+
+</TabItem>
+</Tabs>
+
+</details>
+
+<details>
+<summary><strong>LibreOffice (optional, for DOCX conversion)</strong></summary>
+
+<Tabs groupId="local-dev-libreoffice-os">
+<TabItem value="macos" label="macOS" default>
+
+```bash
+brew install libreoffice
+```
+
+</TabItem>
+<TabItem value="linux" label="Linux">
+
+```bash
+# Debian/Ubuntu example
+sudo apt update
+sudo apt install -y libreoffice
+```
+
+</TabItem>
+</Tabs>
+
+</details>
+
+<details>
+<summary><strong>whisper.cpp (optional, for word-by-word highlighting)</strong></summary>
+
+Install build dependencies:
+
+<Tabs groupId="local-dev-whisper-deps-os">
+<TabItem value="macos" label="macOS" default>
+
+```bash
+brew install cmake
+```
+
+</TabItem>
+<TabItem value="linux" label="Linux">
+
+```bash
+# Debian/Ubuntu example
+sudo apt update
+sudo apt install -y git build-essential cmake
+```
+
+</TabItem>
+</Tabs>
+
+Build whisper.cpp:
+
+```bash
+# clone and build whisper.cpp (no model download needed – OpenReader handles that)
+git clone https://github.com/ggml-org/whisper.cpp.git
+cd whisper.cpp
+cmake -B build
+cmake --build build -j --config Release
+
+# point OpenReader to the compiled whisper-cli binary
+echo WHISPER_CPP_BIN="$(pwd)/build/bin/whisper-cli"
+```
+
+If you are not on Debian/Ubuntu, install equivalent packages with your distro package manager:
+
+- Fedora/RHEL: use `dnf` (`gcc gcc-c++ make cmake curl git tar xz`)
+- Arch: use `pacman` (`base-devel cmake curl git tar xz`)
+
+:::tip
+Set `WHISPER_CPP_BIN` in your `.env` to enable word-by-word highlighting.
+:::
+
+</details>
+
+## Steps
+
+### Required flow
+
+1. Clone the repository.
+
+```bash
+git clone https://github.com/richardr1126/openreader.git
+cd openreader
+```
+
+2. Install dependencies.
+
+```bash
+pnpm i
+```
+
+3. Configure the environment.
+
+```bash
+cp .env.example .env
+```
+
+Then edit `.env`.
+
+Use one of these `.env` mode templates:
+
+<Tabs groupId="local-env-modes">
+  <TabItem value="no-auth" label="No Auth (simple)" default>
+
+```env
+API_BASE=http://host.docker.internal:8880/v1
+API_KEY=none
+# Leave BASE_URL and AUTH_SECRET unset to keep auth disabled.
+# (Admin panel is unavailable without auth.)
+# API_BASE/API_KEY seed a shared default provider if you want shared mode.
+```
+
+  </TabItem>
+  <TabItem value="auth-enabled" label="Auth Enabled">
+
+```env
+API_BASE=http://host.docker.internal:8880/v1
+API_KEY=none
+BASE_URL=http://localhost:3003
+AUTH_SECRET=<generate-with-openssl-rand-hex-32>
+# Optional when you need multiple local origins:
+# AUTH_TRUSTED_ORIGINS=http://localhost:3003,http://127.0.0.1:3003
+```
+
+  </TabItem>
+  <TabItem value="auth-with-admin" label="Auth + Admin Panel">
+
+```env
+# API_BASE / API_KEY are seeded into the admin "default-openai" shared provider
+# on first boot, then no longer read. Manage them in Settings → Admin afterwards.
+API_BASE=http://host.docker.internal:8880/v1
+API_KEY=none
+BASE_URL=http://localhost:3003
+AUTH_SECRET=<generate-with-openssl-rand-hex-32>
+# Comma-separated emails to auto-promote to admin on signin.
+ADMIN_EMAILS=you@example.com
+```
+
+  </TabItem>
+  <TabItem value="external-s3" label="External S3">
+
+```env
+API_BASE=http://host.docker.internal:8880/v1
+API_KEY=none
+USE_EMBEDDED_WEED_MINI=false
+S3_BUCKET=your-bucket
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=your-access-key
+S3_SECRET_ACCESS_KEY=your-secret-key
+# Optional for non-AWS providers:
+# S3_ENDPOINT=https://your-s3-compatible-endpoint
+# S3_FORCE_PATH_STYLE=true
+```
+
+  </TabItem>
+</Tabs>
+
+:::note Env vars vs. admin panel
+On first boot, `API_KEY` / `API_BASE` and any `NEXT_PUBLIC_*` flags you've set get auto-seeded into the admin-managed runtime config (DB-backed, keys encrypted at rest). After that, the admin UI is authoritative and editing those env vars no longer changes app behavior. See [Admin Panel](../configure/admin-panel).
+:::
+
+:::note User BYOK restriction default
+If you want each user to enter personal provider credentials, set `restrictUserApiKeys=false` (from **Settings → Admin** when auth/admin is enabled, or via legacy first-boot seed `NEXT_PUBLIC_RESTRICT_USER_API_KEYS=false` for no-admin bootstrap flows).
+:::
+
+:::info
+For all environment variables, see [Environment Variables](../reference/environment-variables).
+:::
+
+See [Auth](../configure/auth) for app/auth behavior.
+See [Admin Panel](../configure/admin-panel) for the shared-provider and feature-flag management UI.
+Storage configuration details are in [Object / Blob Storage](../configure/object-blob-storage).
+Refer to [Database](../configure/database) for database modes.
+Learn about migration behavior and commands in [Migrations](../configure/migrations).
+
+4. Start the app.
+
+<Tabs groupId="local-run-mode">
+  <TabItem value="dev" label="Dev (recommended)" default>
+
+```bash
+pnpm dev
+```
+
+  </TabItem>
+  <TabItem value="prod" label="Build + Start">
+
+```bash
+pnpm build
+pnpm start
+```
+
+  </TabItem>
+</Tabs>
+
+:::warning API Base Reachability
+`API_BASE` must be reachable from the Next.js server process, not just your browser.
+:::
+
+Visit [http://localhost:3003](http://localhost:3003).
+
+### Optional workflows
+
+Run manual DB migrations only for troubleshooting or explicit migration workflows:
+
+- Migrations run automatically on startup through the shared entrypoint for both `pnpm dev` and `pnpm start`.
+
+```bash
+pnpm migrate
+```
+
+:::info
+If `POSTGRES_URL` is set, migrations target Postgres; otherwise local SQLite is used. To disable automatic startup migrations, set `RUN_DRIZZLE_MIGRATIONS=false` and/or `RUN_FS_MIGRATIONS=false`. You can run storage migration manually with `pnpm migrate-fs`.
+:::

docs-site/versioned_docs/version-v3.0.0/deploy/vercel-deployment.md

@@ -0,0 +1,129 @@
+---
+title: Vercel Deployment
+---
+
+This guide covers deploying OpenReader to Vercel with external Postgres and S3-compatible object storage.
+
+## What works on Vercel
+
+- Documents (PDF/EPUB/TXT/MD) work with `POSTGRES_URL` + external S3 storage.
+- Audiobook routes work on Node.js serverless functions using `ffmpeg-static`.
+
+:::warning DOCX Conversion Limitation
+`docx` conversion requires `soffice` (LibreOffice), which is not available in a standard Vercel runtime.
+:::
+
+## 1. Environment Variables
+
+Recommended production setup (auth enabled, admin panel enabled):
+
+```bash
+# Infrastructure
+POSTGRES_URL=postgres://...
+USE_EMBEDDED_WEED_MINI=false
+S3_ACCESS_KEY_ID=...
+S3_SECRET_ACCESS_KEY=...
+S3_BUCKET=...
+S3_REGION=us-east-1
+S3_PREFIX=openreader
+# Optional (non-AWS S3-compatible providers):
+# S3_ENDPOINT=https://...
+# S3_FORCE_PATH_STYLE=true
+
+# Auth (required for the admin panel)
+BASE_URL=https://your-app.vercel.app
+AUTH_SECRET=...
+ADMIN_EMAILS=you@example.com  # comma-separated; admins manage TTS + features in-app
+
+# First-boot seed for the TTS shared provider (optional; manage in-app afterwards)
+API_KEY=your_replicate_key
+# API_BASE only needed for OpenAI-compatible self-hosted providers
+```
+
+:::note Env vars vs. admin panel (important for Vercel)
+`API_KEY` / `API_BASE` are one-shot bootstrap seeds on first deploy. After boot, manage providers and site features in **Settings → Admin**. Changes there apply on refresh without a redeploy. See [Admin Panel](../configure/admin-panel).
+:::
+
+## 2. First-run admin configuration (recommended)
+
+After the first successful deploy and admin login, open **Settings → Admin** and configure:
+
+- **Shared providers**: create/edit your provider key(s) here (encrypted at rest).
+- **Site features**:
+  - `enableDocxConversion=false` on Vercel (`soffice` unavailable).
+  - `enableDestructiveDeleteActions=false` for safer public deployments.
+  - `enableTtsProvidersTab=false` if you want shared-provider-only UX.
+  - `enableUserSignups=true` unless you explicitly want an invite-only deployment.
+  - `restrictUserApiKeys=true` to block user BYOK through the hosted server.
+  - `defaultTtsProvider=replicate` (or your preferred shared slug).
+  - `showAllProviderModels=false` if you want users locked to each provider's default model.
+  - `enableAudiobookExport=true`.
+  - `enableWordHighlight=false` unless your timestamp stack is configured.
+
+## 3. Legacy first-boot seed (optional)
+
+If you must pre-seed site features via environment variables, the legacy `NEXT_PUBLIC_*` seeds are still supported on first boot only. Prefer the admin panel for ongoing management.
+
+See [Environment Variables](../reference/environment-variables#legacy-first-boot-runtime-seeds-optional) for the complete legacy seed list.
+
+:::warning Auth recommendation
+For internet-exposed Vercel deployments, set both `BASE_URL` and `AUTH_SECRET` — they are also required for the admin panel and for encrypting admin-stored TTS credentials. Running without auth is possible, but not recommended for public environments.
+:::
+
+:::warning Rotating AUTH_SECRET invalidates admin-stored keys
+Admin-managed TTS provider keys are encrypted with a key derived from `AUTH_SECRET`. If you rotate `AUTH_SECRET` after the first deploy, you must re-enter each admin shared provider's API key from the UI.
+:::
+
+:::tip
+For all variables and defaults, see [Environment Variables](../reference/environment-variables).
+:::
+
+## 4. Database and data migrations
+
+Vercel deployments do not run `scripts/openreader-entrypoint.mjs`, so automatic startup migrations do not run there.
+
+- Run `pnpm migrate` in a controlled environment to apply Drizzle schema migrations to your Postgres DB.
+- Run `pnpm migrate-fs` only when migrating legacy local filesystem data (`docstore/documents_v1`, `docstore/audiobooks_v1`) into object storage + DB rows. Fresh Vercel deployments usually do not need this.
+
+## 5. FFmpeg packaging in Vercel functions
+
+`ffmpeg-static` binaries must be included in function traces. This repo already does that in `next.config.ts` via `outputFileTracingIncludes` for:
+
+- `/api/audiobook`
+- `/api/audiobook/chapter`
+- `/api/audiobook/status`
+- `/api/whisper`
+
+:::info
+`serverExternalPackages` should include `ffmpeg-static` so package paths resolve at runtime instead of being bundled into route output.
+:::
+
+If you change route paths or split handlers, update `outputFileTracingIncludes` accordingly.
+
+## 6. Function memory sizing
+
+FFmpeg workloads benefit from more memory/CPU. This repo includes:
+
+```json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "functions": {
+    "app/api/audiobook/route.ts": { "memory": 3009 },
+    "app/api/whisper/route.ts": { "memory": 3009 }
+  }
+}
+```
+
+Adjust memory per route if your files are larger or your plan differs.
+
+## 7. Runtime expectations and caveats
+
+- Audiobook APIs require S3 configuration; otherwise they return `503`.
+- For production Vercel deploys, use `POSTGRES_URL` instead of SQLite.
+
+## 8. Smoke test after deploy
+
+1. Upload and read a PDF/EPUB document.
+2. Confirm sync/blob fetch works across refreshes/devices.
+3. Generate at least one audiobook chapter and play/download it.
+4. If using word highlighting, verify timestamps are produced and rendered.

docs-site/versioned_docs/version-v3.0.0/docker-quick-start.md

@@ -0,0 +1,157 @@
+---
+title: Docker Quick Start
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Prerequisites
+
+- A recent Docker version installed
+- A TTS API server that OpenReader can reach:
+  - [Kokoro-FastAPI](./configure/tts-provider-guides/kokoro-fastapi)
+  - [KittenTTS-FastAPI](./configure/tts-provider-guides/kitten-tts-fastapi)
+  - [Orpheus-FastAPI](./configure/tts-provider-guides/orpheus-fastapi)
+  - [Replicate](./configure/tts-provider-guides/replicate)
+  - [DeepInfra](./configure/tts-provider-guides/deepinfra)
+  - [OpenAI](./configure/tts-provider-guides/openai)
+  - [Other OpenAI-compatible providers](./configure/tts-provider-guides/other)
+
+:::warning SeaweedFS Compatibility Note (April 16, 2026)
+OpenReader currently pins embedded SeaweedFS to `4.18` in CI and Docker builds.
+`4.19` introduced intermittent `InternalError` responses on S3 `PutObject` in our upload flow.
+:::
+
+## 1. Start the Docker container
+
+<Tabs groupId="docker-start-mode">
+<TabItem value="localhost" label="Localhost" default>
+
+Persistent storage, embedded SeaweedFS `weed mini`, optional auth, optional library mount:
+
+```bash
+docker run --name openreader \
+  --restart unless-stopped \
+  -p 3003:3003 \
+  -p 8333:8333 \
+  -v openreader_docstore:/app/docstore \
+  -v /path/to/your/library:/app/docstore/library:ro \
+  -e API_BASE=http://host.docker.internal:8880/v1 \
+  -e API_KEY=none \
+  -e BASE_URL=http://localhost:3003 \
+  -e AUTH_SECRET=$(openssl rand -hex 32) \
+  -e ADMIN_EMAILS=you@example.com \
+  ghcr.io/richardr1126/openreader:latest
+```
+
+What this command enables:
+
+- `-p 3003:3003`: exposes the OpenReader web app/API.
+- `-p 8333:8333`: exposes embedded SeaweedFS S3 endpoint for direct browser presigned upload/download.
+- `-v openreader_docstore:/app/docstore`: persists SQLite metadata, SeaweedFS blob data, and migration/runtime state.
+- `-v /path/to/your/library:/app/docstore/library:ro`: mounts a read-only importable library source.
+- `-e API_BASE=...` / `-e API_KEY=...`: **first-boot seed only.** On the first container start, these are auto-migrated into a `default-openai` admin shared provider stored in the DB (key encrypted at rest). After that, the running app no longer reads them — manage the provider from **Settings → Admin → Shared providers**. See [Admin Panel](./configure/admin-panel).
+- `-e BASE_URL=...` and `-e AUTH_SECRET=...`: together they turn on auth/session mode for local sign-in flows.
+- `-e ADMIN_EMAILS=...`: (optional, requires auth) comma-separated emails auto-promoted to admin. Admins see the **Admin** tab in Settings.
+
+</TabItem>
+<TabItem value="local-network" label="LAN Host">
+
+Use this when the app should be reachable from other devices on your LAN:
+
+```bash
+docker run --name openreader \
+  --restart unless-stopped \
+  -p 3003:3003 \
+  -p 8333:8333 \
+  -v openreader_docstore:/app/docstore \
+  -e API_BASE=http://host.docker.internal:8880/v1 \
+  -e BASE_URL=http://<YOUR_LAN_IP>:3003 \
+  -e AUTH_SECRET=$(openssl rand -hex 32) \
+  -e AUTH_TRUSTED_ORIGINS=http://localhost:3003,http://127.0.0.1:3003 \
+  -e USE_ANONYMOUS_AUTH_SESSIONS=true \
+  -e ADMIN_EMAILS=you@example.com \
+  ghcr.io/richardr1126/openreader:latest
+```
+
+Replace `YOUR_LAN_IP` with the Docker host IP address on your local network to allow access from other devices.
+
+What this command enables:
+
+- LAN access from phones/tablets/other computers via `http://<YOUR_LAN_IP>:3003`.
+- `BASE_URL` points auth/session cookies and callbacks at your LAN URL.
+- `AUTH_TRUSTED_ORIGINS` allows localhost loopback origins in addition to your primary LAN origin.
+- `USE_ANONYMOUS_AUTH_SESSIONS=true` allows guest sessions while auth is enabled.
+- `API_BASE` seeds the default TTS endpoint into the admin-managed `default-openai` shared provider on first boot. Edit it from **Settings → Admin → Shared providers** after that.
+- `ADMIN_EMAILS=...` (optional) auto-promotes the listed email(s) to admin so they can manage shared providers and site feature flags from the UI.
+- `openreader_docstore` volume keeps data persistent across restarts.
+
+</TabItem>
+<TabItem value="minimal" label="Minimal">
+
+Auth disabled, embedded storage ephemeral, no library import:
+
+```bash
+docker run --name openreader \
+  --restart unless-stopped \
+  -p 3003:3003 \
+  -p 8333:8333 \
+  ghcr.io/richardr1126/openreader:latest
+```
+
+What this command enables:
+
+- Fastest startup with no extra env vars.
+- No persistent volume (`/app/docstore` stays container-local), so data is ephemeral unless you add a mount.
+- Auth remains disabled because `BASE_URL` and `AUTH_SECRET` are not set. The admin panel requires auth, so it's unavailable in this mode.
+- No TTS provider preset by default. Configure `API_BASE`/`API_KEY` on first boot if you want a seeded shared provider, or run auth+admin mode and manage providers from the admin panel.
+
+</TabItem>
+</Tabs>
+
+:::tip Quick Tips
+- Set `API_BASE` on first boot to a TTS endpoint the container can reach (`host.docker.internal` works for host-local services). After first boot, manage providers in **Settings → Admin → Shared providers**.
+- Auth is enabled only when both `BASE_URL` and `AUTH_SECRET` are set. The admin panel requires auth.
+- Set `ADMIN_EMAILS` to your email if you want the **Admin** tab in Settings.
+- `restrictUserApiKeys` controls shared-provider-only mode. For per-user BYOK in auth-enabled setups, toggle it off in **Settings → Admin → Site features**. Legacy first-boot seed via `NEXT_PUBLIC_RESTRICT_USER_API_KEYS=false` is still supported.
+- Use a `/app/docstore` mount if you want data to survive container/image replacement.
+- Startup automatically runs DB/storage migrations via the shared entrypoint.
+:::
+
+:::warning Port `8333` Exposure
+Expose `8333` for direct browser presigned upload/download with embedded SeaweedFS.
+
+If `8333` is not reachable from the browser, direct presigned access is unavailable. Uploads can still fall back to `/api/documents/blob/upload/fallback`, and document reads/downloads continue through `/api/documents/blob`.
+:::
+
+## 2. Configure settings in the app UI
+
+Visit [http://localhost:3003](http://localhost:3003) after startup.
+
+- If you set `ADMIN_EMAILS`, sign in with that email and open **Settings → Admin** to manage shared TTS providers and site feature flags for all users.
+- Per-user: set TTS provider/model in **Settings → TTS Provider**. API key/base URL inputs are shown only when `restrictUserApiKeys=false`.
+- Select the model voice from the voice dropdown.
+
+## 3. Update Docker image
+
+Legacy image compatibility: `ghcr.io/richardr1126/openreader-webui:latest` remains available as an alias.
+
+```bash
+docker stop openreader || true && \
+docker rm openreader || true && \
+docker image rm ghcr.io/richardr1126/openreader:latest || true && \
+docker pull ghcr.io/richardr1126/openreader:latest
+```
+
+:::tip
+If you use a mounted volume for `/app/docstore`, your persisted data remains after image updates.
+:::
+
+:::info Related Docs
+- [Environment Variables](./reference/environment-variables)
+- [Auth](./configure/auth)
+- [Admin Panel](./configure/admin-panel)
+- [Database](./configure/database)
+- [Object / Blob Storage](./configure/object-blob-storage)
+- [Migrations](./configure/migrations)
+:::

docs-site/versioned_docs/version-v3.0.0/introduction.md

@@ -0,0 +1,53 @@
+---
+id: intro
+title: Introduction
+slug: /
+---
+
+OpenReader is an open source text-to-speech document reader built with Next.js. It provides a read-along experience with narration for **EPUB, PDF, TXT, MD, and DOCX documents**.
+
+> Previously named **OpenReader-WebUI**.
+
+It supports multiple TTS providers including OpenAI, Replicate, DeepInfra, and custom OpenAI-compatible endpoints such as [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI), [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI), and [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI).
+
+## ✨ Highlights
+
+- 🎯 **Multi-Provider TTS Support**
+  - [**Kokoro-FastAPI**](https://github.com/remsky/Kokoro-FastAPI): supports multi-voice combinations (for example `af_heart+af_bella`)
+  - [**KittenTTS-FastAPI**](https://github.com/richardr1126/KittenTTS-FastAPI): lightweight, CPU-friendly self-hosted TTS
+  - [**Orpheus-FastAPI**](https://github.com/Lex-au/Orpheus-FastAPI)
+  - **Custom OpenAI-compatible**: any TTS API with `/v1/audio/voices` and `/v1/audio/speech` endpoints
+  - **Cloud TTS providers**:
+    - [**Replicate**](https://replicate.com/explore): includes a built-in catalog and supports any Replicate model ID via `Other`
+    - [**DeepInfra**](https://deepinfra.com/models/text-to-speech): Kokoro-82M and other hosted models
+    - [**OpenAI API**](https://platform.openai.com/docs/pricing#transcription-and-speech): `tts-1`, `tts-1-hd`, and `gpt-4o-mini-tts`
+- 📖 **Read Along Experience**
+  - Real-time highlighting for PDF/EPUB, with optional word-level [whisper.cpp](https://github.com/ggml-org/whisper.cpp) timestamps
+- 🛜 **Document Storage**
+  - Documents are persisted in server blob/object storage for consistent access
+- ⚡ **Segment-based TTS Playback** for reusable generation + preloading
+  - Stores segment audio in object storage for fast replay/resume
+- 🎧 **Audiobook Export** in `m4b`/`mp3` with resumable chapter generation
+- 🔐 **Auth Optional by Design**
+  - Run no-auth for local use, or enable auth with user isolation and claim flow
+- 🗂️ **Flexible Storage and Database Modes** with embedded defaults or external S3/Postgres
+- 🚀 **Production-ready Server Behavior** with TTS caching/retries/rate limits and startup migrations
+- 🎨 **Customizable Experience**
+  - 13 built-in themes (light and dark palettes), TTS, and document handling controls
+
+## 🧭 Key Docs
+
+- [Docker Quick Start](./docker-quick-start)
+- [Local Development](./deploy/local-development)
+- [Vercel Deployment](./deploy/vercel-deployment)
+- [Environment Variables](./reference/environment-variables)
+- [Auth](./configure/auth)
+- [Database](./configure/database)
+- [Object / Blob Storage](./configure/object-blob-storage)
+- [Migrations](./configure/migrations)
+- [Server Library Import](./configure/server-library-import)
+- [TTS Providers](./configure/tts-providers)
+
+## Source Repository
+
+- GitHub: [richardr1126/openreader](https://github.com/richardr1126/openreader)

docs-site/versioned_docs/version-v3.0.0/reference/environment-variables.md

@@ -0,0 +1,445 @@
+---
+title: Environment Variables
+toc_max_heading_level: 3
+---
+
+This is the single reference page for OpenReader environment variables.
+
+:::note Recommended configuration path
+For auth-enabled deployments, use **Settings → Admin** as the primary source of truth for shared TTS providers and site features. Legacy env vars (`API_KEY`, `API_BASE`, and `NEXT_PUBLIC_*`) are optional first-boot seeds only.
+:::
+
+## Quick Reference Table
+
+| Variable | Area | Default | When to set |
+| --- | --- | --- | --- |
+| `ADMIN_EMAILS` | Auth/Admin | empty | Comma-separated emails auto-promoted to admin (requires auth enabled) |
+| `API_BASE` | Legacy bootstrap seed | none | Optional first-boot seed into `default-openai`; then manage in Settings → Admin → Shared providers |
+| `API_KEY` | Legacy bootstrap seed | none | Optional first-boot seed into `default-openai`; then manage in Settings → Admin → Shared providers |
+| `NEXT_PUBLIC_*` runtime seeds | Legacy bootstrap seed | varies | Optional first-boot seeds for site features; then manage in Settings → Admin → Site features |
+| `NEXT_PUBLIC_CHANGELOG_FEED_URL` | Legacy bootstrap seed | `https://docs.openreader.richardr.dev/changelog/manifest.json` | Optional first-boot seed for changelog feed URL; then manage in Settings → Admin → Site features |
+| `NEXT_PUBLIC_ENABLE_USER_SIGNUPS` | Legacy bootstrap seed | `true` | Optional first-boot seed for whether new accounts can be created; then manage in Settings → Admin → Site features |
+| `TTS_CACHE_MAX_SIZE_BYTES` | TTS caching | `268435456` (256 MB) | Tune in-memory TTS cache size |
+| `TTS_CACHE_TTL_MS` | TTS caching | `1800000` (30 min) | Tune in-memory TTS cache TTL |
+| `TTS_MAX_RETRIES` | TTS retry | `2` | Tune retry attempts for upstream 429/5xx |
+| `TTS_RETRY_INITIAL_MS` | TTS retry | `250` | Tune initial retry delay |
+| `TTS_RETRY_MAX_MS` | TTS retry | `2000` | Tune max retry delay |
+| `TTS_RETRY_BACKOFF` | TTS retry | `2` | Tune exponential backoff factor |
+| `TTS_UPSTREAM_TIMEOUT_MS` | TTS request timeout | `285000` | Set max upstream TTS request duration before fail-fast |
+| `TTS_ENABLE_RATE_LIMIT` | Rate limiting | `false` | Set `true` to enable TTS per-user/IP daily character limits |
+| `TTS_DAILY_LIMIT_ANONYMOUS` | Rate limiting | `50000` | Override anonymous per-user daily character limit |
+| `TTS_DAILY_LIMIT_AUTHENTICATED` | Rate limiting | `500000` | Override authenticated per-user daily character limit |
+| `TTS_IP_DAILY_LIMIT_ANONYMOUS` | Rate limiting | `100000` | Override anonymous IP backstop daily limit |
+| `TTS_IP_DAILY_LIMIT_AUTHENTICATED` | Rate limiting | `1000000` | Override authenticated IP backstop daily limit |
+| `BASE_URL` | Auth | unset | Required (with `AUTH_SECRET`) to enable auth |
+| `AUTH_SECRET` | Auth | unset | Required (with `BASE_URL`) to enable auth |
+| `AUTH_TRUSTED_ORIGINS` | Auth | empty | Add extra allowed origins |
+| `USE_ANONYMOUS_AUTH_SESSIONS` | Auth | `false` | Set `true` to enable anonymous auth sessions |
+| `GITHUB_CLIENT_ID` | Auth/OAuth | unset | Set with `GITHUB_CLIENT_SECRET` to enable GitHub sign-in |
+| `GITHUB_CLIENT_SECRET` | Auth/OAuth | unset | Set with `GITHUB_CLIENT_ID` to enable GitHub sign-in |
+| `DISABLE_AUTH_RATE_LIMIT` | Rate limiting | `false` | Set `true` to disable auth-layer rate limiting |
+| `POSTGRES_URL` | Database | unset (SQLite mode) | Set to switch metadata/auth DB to Postgres |
+| `USE_EMBEDDED_WEED_MINI` | Storage | `true` when unset | Set `false` to use external S3-compatible storage only |
+| `WEED_MINI_DIR` | Storage | `docstore/seaweedfs` | Override embedded SeaweedFS data directory |
+| `WEED_MINI_WAIT_SEC` | Storage | `20` | Tune SeaweedFS startup wait timeout |
+| `S3_ACCESS_KEY_ID` | Storage | auto-generated in embedded mode | Set explicitly for stable/external credentials |
+| `S3_SECRET_ACCESS_KEY` | Storage | auto-generated in embedded mode | Set explicitly for stable/external credentials |
+| `S3_BUCKET` | Storage | `openreader-documents` in embedded mode | Required for external S3-compatible storage |
+| `S3_REGION` | Storage | `us-east-1` in embedded mode | Required for external S3-compatible storage |
+| `S3_ENDPOINT` | Storage | derived in embedded mode | Set for S3-compatible providers (MinIO/SeaweedFS/R2/etc.) |
+| `S3_FORCE_PATH_STYLE` | Storage | `true` in embedded mode | Set per provider requirement |
+| `S3_PREFIX` | Storage | `openreader` | Customize object key prefix |
+| `RUN_DRIZZLE_MIGRATIONS` | Database migrations | `true` | Set `false` to skip startup Drizzle schema migrations |
+| `RUN_FS_MIGRATIONS` | Storage migrations | `true` | Set `false` to skip startup filesystem -> S3/DB migration pass |
+| `IMPORT_LIBRARY_DIR` | Library import | `docstore/library` fallback | Set a single server library root |
+| `IMPORT_LIBRARY_DIRS` | Library import | unset | Set multiple roots (comma/colon/semicolon separated) |
+| `WHISPER_CPP_BIN` | Word timing | unset | Set to enable `whisper.cpp` timestamps |
+| `FFMPEG_BIN` | Audio runtime | auto-detected (`ffmpeg-static`) | Override ffmpeg binary path |
+
+
+
+## TTS Provider and Request Behavior
+
+### API_BASE
+
+Bootstrap base URL for the legacy OpenAI-compatible TTS endpoint.
+
+- Example: `http://host.docker.internal:8880/v1`
+- **Seeded on first boot** into the auto-created `default-openai` shared provider, then no longer read by the running app. Manage in **Settings → Admin → Shared providers** afterwards.
+- Related docs: [Admin Panel](../configure/admin-panel), [TTS Providers](../configure/tts-providers)
+
+### API_KEY
+
+Bootstrap API key for the legacy OpenAI-compatible TTS endpoint.
+
+- Example: your provider token, or omit if the provider doesn't require auth
+- **Seeded on first boot** into the auto-created `default-openai` shared provider (encrypted at rest), then no longer read by the running app. Manage in **Settings → Admin → Shared providers** afterwards.
+- Related docs: [Admin Panel](../configure/admin-panel), [TTS Providers](../configure/tts-providers)
+
+### TTS_CACHE_MAX_SIZE_BYTES
+
+Maximum in-memory TTS audio cache size in bytes.
+
+- Default: `268435456` (256 MB)
+
+### TTS_CACHE_TTL_MS
+
+In-memory TTS audio cache TTL in milliseconds.
+
+- Default: `1800000` (30 minutes)
+
+### TTS_MAX_RETRIES
+
+Maximum retries for upstream TTS failures (429/5xx).
+
+- Default: `2`
+
+### TTS_RETRY_INITIAL_MS
+
+Initial retry delay in milliseconds for TTS upstream requests.
+
+- Default: `250`
+
+### TTS_RETRY_MAX_MS
+
+Maximum retry delay in milliseconds.
+
+- Default: `2000`
+
+### TTS_RETRY_BACKOFF
+
+Exponential backoff multiplier between retries.
+
+- Default: `2`
+
+### TTS_UPSTREAM_TIMEOUT_MS
+
+Maximum upstream TTS request timeout in milliseconds.
+
+- Default: `285000` (285 seconds)
+- Applies to outbound provider calls from server routes using shared TTS generation
+- Increase for slower providers/models; decrease to fail fast and surface retryable errors sooner
+
+### TTS_ENABLE_RATE_LIMIT
+
+Controls TTS character rate limiting in the TTS API.
+
+- Default: `false` (TTS char limits disabled)
+- Set to `true` to enforce `TTS_DAILY_LIMIT_*` and `TTS_IP_DAILY_LIMIT_*`
+- For behavior details and examples, see [TTS Rate Limiting](../configure/tts-rate-limiting)
+
+### TTS_DAILY_LIMIT_ANONYMOUS
+
+Anonymous per-user daily character limit.
+
+- Default: `50000`
+
+### TTS_DAILY_LIMIT_AUTHENTICATED
+
+Authenticated per-user daily character limit.
+
+- Default: `500000`
+
+### TTS_IP_DAILY_LIMIT_ANONYMOUS
+
+Anonymous IP backstop daily character limit.
+
+- Default: `100000`
+
+### TTS_IP_DAILY_LIMIT_AUTHENTICATED
+
+Authenticated IP backstop daily character limit.
+
+- Default: `1000000`
+
+## Auth and Identity
+
+### BASE_URL
+
+External base URL for this OpenReader instance.
+
+- Required with `AUTH_SECRET` to enable auth
+- Example: `http://localhost:3003` or `https://reader.example.com`
+- Related docs: [Auth](../configure/auth)
+
+### AUTH_SECRET
+
+Secret key used by auth/session handling.
+
+- Required with `BASE_URL` to enable auth
+- Generate with `openssl rand -hex 32`
+- Also used to HMAC-hash server-side TTS segment text fingerprints
+- Related docs: [Auth](../configure/auth)
+
+### AUTH_TRUSTED_ORIGINS
+
+Additional allowed origins for auth requests.
+
+- Comma-separated list
+- `BASE_URL` origin is always trusted automatically
+- Related docs: [Auth](../configure/auth)
+
+### USE_ANONYMOUS_AUTH_SESSIONS
+
+Controls whether auth-enabled deployments can create/use anonymous sessions.
+
+- Default: `false` (anonymous sessions disabled)
+- Set `true` to allow anonymous sessions and guest-style flows
+- When `false`, users must sign in or sign up with an account
+- Related docs: [Auth](../configure/auth)
+
+### GITHUB_CLIENT_ID
+
+GitHub OAuth client ID.
+
+- Enable only with `GITHUB_CLIENT_SECRET`
+
+### GITHUB_CLIENT_SECRET
+
+GitHub OAuth client secret.
+
+- Enable only with `GITHUB_CLIENT_ID`
+
+### DISABLE_AUTH_RATE_LIMIT
+
+Controls Better Auth rate limiting.
+
+- Default behavior: auth-layer rate limiting enabled
+- Set to `true` to disable auth-layer rate limiting
+- This does not affect TTS character rate limiting
+- Related docs: [Auth](../configure/auth)
+
+### ADMIN_EMAILS
+
+Comma-separated list of email addresses that are auto-promoted to admin.
+
+- Default: empty (no admins)
+- Requires auth to be enabled (`AUTH_SECRET` + `BASE_URL`).
+- Matched emails get `user.is_admin = true` on every session resolution; removed emails are demoted on the next session resolve.
+- Admins see a new **Admin** tab in Settings exposing shared TTS providers and site-wide feature toggles. Keys for shared providers are stored encrypted in the DB and never returned to the client.
+- Example: `ADMIN_EMAILS=alice@example.com,bob@example.com`
+- Related docs: [Admin Panel](../configure/admin-panel), [Auth](../configure/auth)
+
+## Database and Object Blob Storage
+
+### POSTGRES_URL
+
+Switches metadata/auth storage from SQLite to Postgres.
+
+- Unset: SQLite at `docstore/sqlite3.db`
+- Set: Postgres mode
+- Related docs: [Database](../configure/database)
+
+### USE_EMBEDDED_WEED_MINI
+
+Controls embedded SeaweedFS startup.
+
+- Default behavior: treated as enabled when unset
+- Set `false` to rely on external S3-compatible storage
+- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+
+### WEED_MINI_DIR
+
+Data directory for embedded SeaweedFS (`weed mini`).
+
+- Default: `docstore/seaweedfs`
+- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+
+### WEED_MINI_WAIT_SEC
+
+Maximum seconds to wait for embedded SeaweedFS startup.
+
+- Default: `20`
+- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+
+### S3_ACCESS_KEY_ID
+
+Access key for S3-compatible storage.
+
+- Auto-generated in embedded mode if unset
+- Set explicitly for stable credentials or external providers
+- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+
+### S3_SECRET_ACCESS_KEY
+
+Secret key for S3-compatible storage.
+
+- Auto-generated in embedded mode if unset
+- Set explicitly for stable credentials or external providers
+- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+
+### S3_BUCKET
+
+Bucket name used for document blobs.
+
+- Default in embedded mode: `openreader-documents`
+- Required for external S3-compatible storage
+- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+
+### S3_REGION
+
+Region used by the S3 client.
+
+- Default in embedded mode: `us-east-1`
+- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+
+### S3_ENDPOINT
+
+Endpoint URL for S3-compatible storage.
+
+- In embedded mode, defaults to `http://<BASE_URL host>:8333` (or detected host)
+- For AWS S3, usually leave unset
+- For MinIO/SeaweedFS/R2/B2-style APIs, typically set explicitly
+- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+
+### S3_FORCE_PATH_STYLE
+
+Path-style S3 addressing toggle.
+
+- Default in embedded mode: `true`
+- Set according to provider requirements
+- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+
+### S3_PREFIX
+
+Prefix prepended to stored object keys.
+
+- Default: `openreader`
+- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
+
+## Migration Controls
+
+### RUN_DRIZZLE_MIGRATIONS
+
+Controls startup migration execution in shared entrypoint.
+
+- Default: `true`
+- Set `false` to skip automatic startup Drizzle schema migrations
+- Related docs: [Migrations](../configure/migrations), [Database](../configure/database)
+
+### RUN_FS_MIGRATIONS
+
+Controls startup filesystem-to-object-store migration execution in shared entrypoint.
+
+- Default: `true`
+- Runs `scripts/migrate-fs-v2.mjs` at startup after DB migrations
+- Set `false` to skip automatic storage migration pass
+- Related docs: [Migrations](../configure/migrations), [Database](../configure/database), [Object / Blob Storage](../configure/object-blob-storage)
+
+## Library Import
+
+### IMPORT_LIBRARY_DIR
+
+Single directory root for server library import.
+
+- Used when `IMPORT_LIBRARY_DIRS` is unset
+- Default fallback root: `docstore/library`
+- Related docs: [Server Library Import](../configure/server-library-import)
+
+### IMPORT_LIBRARY_DIRS
+
+Multiple library roots for server library import.
+
+- Separator: comma, colon, or semicolon
+- Takes precedence over `IMPORT_LIBRARY_DIR`
+- Related docs: [Server Library Import](../configure/server-library-import)
+
+## Audio Tooling and Alignment
+
+### WHISPER_CPP_BIN
+
+Absolute path to compiled `whisper.cpp` binary for word-level timestamps.
+
+- Example: `/whisper.cpp/build/bin/whisper-cli`
+- Required only for optional word-by-word highlighting
+
+### FFMPEG_BIN
+
+Absolute path or executable name for the ffmpeg binary used by audiobook/processing routes.
+
+- Resolution order: `FFMPEG_BIN` -> `ffmpeg-static`
+- Example: `/var/task/node_modules/ffmpeg-static/ffmpeg`
+
+## Legacy First-Boot Runtime Seeds (optional)
+
+These variables exist only as **first-boot seeds** for the admin-managed runtime config. Prefer changing site features from **Settings → Admin → Site features**. Keep these only when you need bootstrap defaults before the first admin login. See [Admin Panel](../configure/admin-panel) for migration behavior.
+
+The values are SSR-injected via `window.__RUNTIME_CONFIG__`, so admin edits take effect for all users on the next page load — no rebuild required (unlike the old `NEXT_PUBLIC_*` build-time pattern).
+
+### NEXT_PUBLIC_ENABLE_DOCX_CONVERSION
+
+Controls whether the experimental DOCX-to-PDF conversion and upload feature is enabled.
+
+- Default: `true` (enabled)
+- Runtime key: `enableDocxConversion`
+
+### NEXT_PUBLIC_ENABLE_DESTRUCTIVE_DELETE_ACTIONS
+
+Controls whether the "Delete all user docs" and other bulk-delete buttons are shown in Settings.
+
+- Default: `true` (enabled)
+- Runtime key: `enableDestructiveDeleteActions`
+
+### NEXT_PUBLIC_ENABLE_TTS_PROVIDERS_TAB
+
+Controls whether the **TTS Provider** section appears in the user-facing Settings modal.
+
+- Default: `true` (enabled)
+- Set `false` to hide provider/model/API controls in the per-user Settings modal (the admin panel is unaffected).
+- Runtime key: `enableTtsProvidersTab`
+
+### NEXT_PUBLIC_ENABLE_USER_SIGNUPS
+
+Controls whether new user accounts can be created.
+
+- Default: `true` (enabled)
+- When `false`, new account creation is blocked for email sign-up, first-time OAuth signup, and anonymous-to-account upgrades.
+- Existing users can still sign in.
+- Runtime key: `enableUserSignups`
+
+### NEXT_PUBLIC_RESTRICT_USER_API_KEYS
+
+Controls whether users can supply personal API keys/base URLs for built-in providers.
+
+- Default: runtime-dependent
+- When `true`, server routes only use admin-managed shared providers.
+- When `false`, users can use per-user BYOK credentials for built-in providers.
+- Runtime key: `restrictUserApiKeys`
+
+### NEXT_PUBLIC_DEFAULT_TTS_PROVIDER
+
+Sets the default TTS provider for new users.
+
+- Default: `custom-openai`
+- Example values: `replicate`, `deepinfra`, `openai`, `custom-openai`, or an admin-defined shared provider slug (e.g. `kokoro-prod`)
+- Runtime key: `defaultTtsProvider`
+
+`showAllProviderModels` is a runtime-only admin setting (no env seed). Configure it in **Settings → Admin → Site features**.
+
+### NEXT_PUBLIC_CHANGELOG_FEED_URL
+
+Sets the changelog manifest URL used by the Settings modal changelog viewer.
+
+- Default: `https://docs.openreader.richardr.dev/changelog/manifest.json`
+- Use this in self-hosted deployments when you publish changelog feeds to a custom docs domain/path.
+- Runtime key: `changelogFeedUrl`
+
+
+### NEXT_PUBLIC_ENABLE_AUDIOBOOK_EXPORT
+
+Controls whether audiobook export UI/actions are shown in the client.
+
+- Default: `true` (enabled)
+- Affects export entry points in PDF/EPUB pages and document settings UI
+- Runtime key: `enableAudiobookExport`
+
+### NEXT_PUBLIC_ENABLE_WORD_HIGHLIGHT
+
+Controls word-by-word highlighting UI and timestamp-alignment behavior.
+
+- Default: `true` (enabled)
+- Requires working timestamp generation (for example `WHISPER_CPP_BIN`)
+- Affects:
+  - Word-highlight toggles in document settings
+  - Alignment requests during TTS playback
+- Runtime key: `enableWordHighlight`

docs-site/versioned_docs/version-v3.0.0/reference/stack.md

@@ -0,0 +1,44 @@
+---
+title: Stack
+---
+
+## Framework
+
+- [Next.js](https://nextjs.org/) 15 (App Router)
+- [React](https://react.dev/) 19
+- [TypeScript](https://www.typescriptlang.org/)
+
+## Containerization and runtime
+
+- [Docker](https://www.docker.com/) (linux/amd64 and linux/arm64)
+- Shared entrypoint that runs DB migrations by default and can bootstrap embedded SeaweedFS before app startup
+
+## Next.js client
+
+- UI: [Tailwind CSS](https://tailwindcss.com), [Headless UI](https://headlessui.com), [@tailwindcss/typography](https://tailwindcss.com/docs/typography-plugin)
+- Interactions: `react-dnd`, `react-dropzone`
+- Authentication: [Better Auth](https://www.better-auth.com/) client SDK
+- Local storage/cache: [Dexie.js](https://dexie.org/) (IndexedDB)
+- Document rendering:
+  - PDF: [react-pdf](https://github.com/wojtekmaj/react-pdf), [pdf.js](https://mozilla.github.io/pdf.js/)
+  - EPUB: [react-reader](https://github.com/gerhardsletten/react-reader), [epubjs](https://github.com/futurepress/epub.js/)
+  - Markdown/Text: [react-markdown](https://github.com/remarkjs/react-markdown), [remark-gfm](https://github.com/remarkjs/remark-gfm)
+- Text preprocessing/matching: [compromise](https://github.com/spencermountain/compromise), [cmpstr](https://github.com/remsky/cmpstr)
+
+## Next.js server
+
+- APIs: Route Handlers for sync, blob/content access, migrations, audiobook export, TTS/Whisper proxying
+- State sync: request-based today (not realtime push updates)
+- Authentication: [Better Auth](https://www.better-auth.com/) server handlers/adapters
+- Metadata DB: [Drizzle ORM](https://orm.drizzle.team/) with SQLite (`better-sqlite3`) by default and optional Postgres (`pg`)
+  - App tables are manually maintained in Drizzle schema files
+  - Auth tables are auto-generated by the [Better Auth](https://www.better-auth.com/) CLI and migrated alongside app tables via Drizzle
+- Blob storage: embedded [SeaweedFS](https://github.com/seaweedfs/seaweedfs) (`weed mini`) by default, or external S3-compatible storage via AWS SDK v3
+- Audio/processing pipeline: OpenAI-compatible TTS providers, [ffmpeg](https://ffmpeg.org/) for audiobook assembly, optional [whisper.cpp](https://github.com/ggerganov/whisper.cpp) for word timestamps
+
+## Tooling and testing
+
+- ESLint
+- TypeScript
+- [Playwright](https://playwright.dev/) end-to-end tests
+- Drizzle migration/generation scripts

docs-site/versioned_docs/version-v4.0.0/about/acknowledgements.md

@@ -0,0 +1,16 @@
+---
+title: Acknowledgements
+---
+
+This project is built with support from the following open-source projects and tools:
+
+- [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M)
+- [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI)
+- [Better Auth](https://www.better-auth.com/)
+- [SQLite](https://www.sqlite.org/)
+- [PostgreSQL](https://www.postgresql.org/)
+- [SeaweedFS](https://github.com/seaweedfs/seaweedfs)
+- [OpenAI Whisper](https://github.com/openai/whisper)
+- [ffmpeg](https://ffmpeg.org)
+- [react-pdf](https://github.com/wojtekmaj/react-pdf)
+- [react-reader](https://github.com/happyr/react-reader)

docs-site/versioned_docs/version-v4.0.0/about/license.md

@@ -0,0 +1,7 @@
+---
+title: License
+---
+
+OpenReader is licensed under the MIT License.
+
+- Repository license file: [LICENSE](https://github.com/richardr1126/openreader/blob/main/LICENSE)

docs-site/versioned_docs/version-v4.0.0/about/support-and-contributing.md

@@ -0,0 +1,19 @@
+---
+title: Support and Contributing
+---
+
+## Feature requests
+
+Use [GitHub Discussions](https://github.com/richardr1126/openreader/discussions) for feature requests and ideas.
+
+## Issues and support
+
+If you encounter a bug, open an issue in [GitHub Issues](https://github.com/richardr1126/openreader/issues).
+
+## Contributing
+
+Contributions are welcome.
+
+- Fork the repository
+- Create your branch
+- Open a pull request with your changes

docs-site/versioned_docs/version-v4.0.0/configure/admin-panel.md

@@ -0,0 +1,149 @@
+---
+title: Admin Panel
+---
+
+The admin panel lets a designated set of users manage **shared TTS providers** and **site-wide feature flags** directly from the Settings modal — without touching env vars or redeploying.
+
+It is gated behind authentication, so you must have auth enabled to use it ([Auth](./auth)).
+
+## Designating admins
+
+Set `ADMIN_EMAILS` to a comma-separated list of emails:
+
+```env
+AUTH_SECRET=...        # required for auth
+BASE_URL=...           # required for auth
+ADMIN_EMAILS=alice@example.com,bob@example.com
+```
+
+On every session resolution the server compares the user's email against this list and writes `user.is_admin = true` (or `false` for emails removed from the list). No restart is required to demote — the next page load picks it up.
+
+When the logged-in user is an admin, an **Admin** tab appears in **Settings → sidebar** with two sub-tabs:
+
+- **Shared providers** — server-side TTS provider instances visible to all users.
+- **Site features** — runtime-editable replacements for what were previously build-time public env flags.
+
+## Shared TTS providers
+
+Each shared provider is one named instance bound to one of the four built-in provider types (`custom-openai`, `openai`, `replicate`, `deepinfra`). The admin form has:
+
+| Field | Notes |
+| --- | --- |
+| **Slug** | URL-safe identifier exposed to users (e.g. `kokoro-prod`). Must not collide with a built-in id. Lowercase alphanumeric + hyphens. |
+| **Display name** | Shown in the user's provider dropdown, suffixed with "(shared)". |
+| **Provider type** | One of the four built-ins. Determines voice/model resolution. |
+| **Base URL** | Optional. Falls through to the provider type's default when blank. |
+| **API key** | Encrypted at rest with AES-256-GCM (key derived from `AUTH_SECRET` via scrypt). On edit, leave blank to keep the existing key. |
+| **Default model** | Optional. Used as the initial model when a user selects this provider. |
+| **Enabled** | Toggle to hide the provider from non-admin users without deleting it. |
+
+When a non-admin user picks a shared provider in **Settings → TTS Provider**:
+
+- The API key / base URL fields are hidden — those credentials never leave the server.
+- The TTS request still goes through the user's browser, but the server replaces the slug with the matching admin row's decrypted key and base URL before calling the upstream provider.
+- The user's per-request `x-openai-key` / `x-openai-base-url` headers are ignored for shared slugs.
+
+Whether users can supply their own personal built-in provider keys is controlled by the site feature `restrictUserApiKeys`:
+
+- `true`: users are restricted to shared providers only.
+- `false`: users may also use per-user BYOK credentials for built-in providers.
+
+### Auto-seeded "default-openai"
+
+On first boot, if `admin_providers` is empty and the legacy `API_KEY` env var is set, OpenReader creates a single shared provider with:
+
+- slug `default-openai`, displayName `Default (from env)`, providerType `custom-openai`
+- baseUrl from `API_BASE`, apiKey from `API_KEY` (encrypted)
+- defaultModel set to `kokoro` (you can edit it in Admin → Shared providers)
+
+After this seed runs, the legacy `API_KEY` / `API_BASE` env vars are no longer read by the TTS routes — the DB row is authoritative. You can rename, edit, disable, or delete this row like any other from the admin UI, and remove the env vars from your `.env` when convenient.
+
+:::warning Upgrading from v2.2.0
+In v2.2.0 and earlier, `API_KEY` / `API_BASE` were read live by the TTS routes on every request. As of v3.0.0 they are **one-shot seeds** consumed only on the first boot where `admin_providers` is empty. After upgrading, boot the app once and confirm a `default-openai` row exists in **Settings → Admin → Shared providers** with the correct base URL. If it is missing or wrong (e.g. the env vars were not set on first boot, or the table was already non-empty from a pre-release), create or edit the shared provider manually — TTS will not fall back to the env vars.
+:::
+
+## Site features
+
+Runtime-editable settings, one row per key:
+
+| Key | What it controls |
+| --- | --- |
+| `defaultTtsProvider` | Default provider id new users start with (built-in id or shared slug). |
+| `changelogFeedUrl` | Public changelog manifest URL used by the Settings modal changelog panel. |
+| `enableUserSignups` | Controls whether new accounts can be created. Existing accounts can still sign in when this is `false`. |
+| `restrictUserApiKeys` | Restrict user-supplied API keys/base URLs; when `true`, only admin shared providers are allowed. |
+| `enableTtsProvidersTab` | Whether the user-facing TTS Provider tab in Settings is shown. |
+| `showAllProviderModels` | When `false`, users are restricted to each provider's default model (shared provider `defaultModel` or built-in provider default). |
+| `enableAudiobookExport` | Show the audiobook export entry points on PDF/EPUB pages. |
+| `enableDocxConversion` | Accept .docx uploads (converted to PDF server-side). |
+| `enableDestructiveDeleteActions` | Show "Delete all data" buttons in the Documents tab (auth-disabled mode). |
+
+Word-by-word highlighting and PDF layout parsing capability are controlled by compute-worker server env configuration, not an admin runtime flag.
+
+Each row shows a source badge:
+
+- **from seed** — the value was seeded on first boot (from `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH`).
+- **admin** — explicit admin override. Use **Reset** on the row to clear it back to built-in default behavior.
+- **default** — no seed/admin row exists; built-in default is active.
+
+:::warning Security note for `restrictUserApiKeys`
+Turning `restrictUserApiKeys` off allows user-supplied API keys to flow through this server. Use this only for trusted/self-hosted deployments where that tradeoff is acceptable.
+:::
+
+## Rate limiting
+
+A dedicated **Rate limiting** group (within the same admin panel) collects the daily quotas, the PDF parsing throttle, and the upload size cap:
+
+| Key | What it controls |
+| --- | --- |
+| `disableTtsRateLimit` | Disable the per-user/IP daily TTS character limits. When `false`, the daily-limit fields below it apply. |
+| `disableComputeRateLimit` | Disable per-user PDF parsing rate limiting. When `false`, the burst/sustained limit fields below it apply. |
+| `maxUploadMb` | Maximum size (MB) accepted for a single document upload. Enforced server-side and signed into the presigned S3 PUT. |
+
+The **Disable TTS daily rate limiting** and **Disable PDF parsing rate limiting** toggles each reveal a collapsible group of numeric inputs when set to `false`:
+
+- TTS: anonymous/authenticated per-user daily limits and anonymous/authenticated IP daily backstops.
+- PDF parsing: burst limit + window (seconds) and sustained limit + window (seconds). The sustained window doubles as a concurrency cap.
+
+## TTS upstream
+
+At the end of the **Site features** tab, a dedicated **TTS upstream** group controls server-side request and cache tuning (DB-backed runtime settings, not env vars):
+
+| Key | What it controls |
+| --- | --- |
+| `ttsUpstreamMaxRetries` | Maximum retry attempts for upstream TTS 429/5xx responses. |
+| `ttsUpstreamTimeoutMs` | Upstream request timeout for OpenAI-compatible TTS calls. |
+| `ttsCacheMaxSizeBytes` | Maximum size of the in-memory TTS audio cache. |
+| `ttsCacheTtlMs` | Time-to-live for cached TTS audio buffers. |
+
+In v4 these settings are admin-only and are no longer configurable through environment variables.
+
+## Migrating off env vars
+
+In v4, runtime site features are managed by admin settings and optional JSON seed. To minimize env surface area:
+
+1. Deploy this version with your existing env values in place.
+2. Boot the app once. Open Settings → Admin and verify:
+   - Seeded settings appear as **from seed** (if you supplied a runtime JSON seed).
+   - A `default-openai` row exists in **Shared providers** (if you had `API_KEY` set).
+3. Remove any bootstrap env vars you no longer need from `.env`.
+4. Redeploy. Behavior is unchanged — the DB is now the source of truth.
+
+You can keep `API_BASE` / `API_KEY` if you intentionally want bootstrap fallback behavior on empty provider tables.
+
+## How keys are protected
+
+- API keys are encrypted in the `admin_providers` table with AES-256-GCM. The encryption key is derived from `AUTH_SECRET` via `scrypt`.
+- The masked-list view (`GET /api/admin/providers`, used by the admin UI itself) returns `••••` + last-4 only — never plaintext or ciphertext.
+- The public list endpoint (`GET /api/tts/shared-providers`, called by every user's browser) returns only `{ slug, displayName, providerType, defaultModel }`. Keys and base URLs are never exposed to the client.
+- Non-admin users cannot enumerate admin providers' credentials or base URLs through any API.
+
+:::danger Rotating `AUTH_SECRET` invalidates all stored admin provider keys
+Because the encryption key for `admin_providers` is derived from `AUTH_SECRET`, changing `AUTH_SECRET` makes every stored API key undecryptable. After rotating it, shared providers will fail to authenticate upstream until you re-enter each provider's API key in **Settings → Admin → Shared providers** (edit the row and paste the key again). There is no automated re-encryption path. If you must rotate `AUTH_SECRET`, plan to re-enter admin provider keys immediately afterward.
+:::
+
+## Related
+
+- [Auth](./auth) — required to use the admin panel.
+- [TTS Providers](./tts-providers) — built-in provider catalog and per-user behavior.
+- [Environment Variables](../reference/environment-variables) — `ADMIN_EMAILS`, provider bootstrap vars, and runtime JSON seed.

docs-site/versioned_docs/version-v4.0.0/configure/auth.md

@@ -0,0 +1,64 @@
+---
+title: Auth
+---
+
+This page covers application-level configuration for provider access and authentication.
+
+## Auth behavior
+
+- `BASE_URL` and `AUTH_SECRET` are required at startup in v4+.
+- Keep `AUTH_TRUSTED_ORIGINS` empty to trust only `BASE_URL`.
+- Anonymous auth sessions are disabled by default.
+- Set `USE_ANONYMOUS_AUTH_SESSIONS=true` to enable anonymous session flows.
+
+## Runtime modes
+
+OpenReader has two common runtime modes:
+
+- **Auth enabled, non-admin user**: user account/session features are available, but no admin controls.
+- **Auth enabled, admin user**: full **Settings → Admin** access (shared providers + site features).
+
+## Admin role
+
+You can designate one or more users as admins via the `ADMIN_EMAILS` env var:
+
+```env
+ADMIN_EMAILS=alice@example.com,bob@example.com
+```
+
+Admins see a new **Admin** tab in **Settings** with two sub-tabs:
+
+- **Shared TTS providers** — server-managed TTS provider instances with encrypted keys, visible to all users.
+- **Site features** — runtime overrides for what were previously build-time public env flags (including account signup availability, default TTS provider, audiobook export, etc.).
+
+Admin assignment is reconciled on every session resolution, so removing an email from `ADMIN_EMAILS` demotes the user on next login without a restart. See [Admin Panel](./admin-panel) for the full reference.
+
+## Route behavior
+
+- `/` is a public landing/onboarding page and remains indexable.
+- `/app` is the protected app home (document list and uploader UI).
+- If a valid session exists (including anonymous), visiting `/` redirects to `/app`.
+- Protected app routes continue to require auth; when anonymous sessions are disabled and no session exists, users are redirected to `/signin`.
+
+## Related docs
+
+- For auth environment variables: [Environment Variables](../reference/environment-variables#auth-and-identity)
+- For admin role and shared TTS provider config: [Admin Panel](./admin-panel)
+- For TTS character limits and quota behavior: [TTS Rate Limiting](./tts-rate-limiting)
+- For provider-specific guidance: [TTS Providers](./tts-providers)
+- For storage/S3/SeaweedFS behavior: [Object / Blob Storage](./object-blob-storage)
+- For database mode: [Database](./database)
+- For migration behavior and commands: [Migrations](./migrations)
+
+## Sync notes
+
+### Auth enabled
+
+- Settings and reading progress are saved to the server.
+- Updates are not instant push-based sync; they use normal client polling/refresh behavior.
+- If two devices change the same item around the same time, the newest update wins.
+
+## Claim modal note
+
+- You may still see old anonymous settings/progress available to claim from older deployments.
+- Legacy `unclaimed` data is only surfaced through the claim flow; normal authenticated routes are scoped to your current user id.

docs-site/versioned_docs/version-v4.0.0/configure/database.md

@@ -0,0 +1,58 @@
+---
+title: Database
+---
+
+This page covers database mode selection for OpenReader.
+
+## Scope of this page
+
+- Focus: SQL metadata, state, and relational tables.
+- Not covered here: object key layout and blob transport details (see [Object / Blob Storage](./object-blob-storage)).
+
+## Database mode
+
+- SQLite (default): embedded DB at `docstore/sqlite3.db`; good for local/self-host single-instance setups.
+- Postgres: enabled when `POSTGRES_URL` is set; recommended for production/distributed deployments.
+
+## What the database stores
+
+- Document and audiobook metadata/state used by server routes.
+- Auth/session tables (`user`, `session`, `account`, `verification`) when auth is enabled — schema is auto-generated by Better Auth.
+- TTS character usage counters (`user_tts_chars`) for daily rate limiting (when enabled).
+- User settings preferences (`user_preferences`) when auth is enabled.
+- User reading progress (`user_document_progress`) when auth is enabled.
+- Document preview job/asset metadata (`document_previews`) for server-side PDF/EPUB thumbnails.
+- TTS segment metadata (`tts_segments`) for server-side playback caching:
+  - Segment identity + settings hash
+  - Audio object key and duration
+  - Optional alignment payload for word highlighting
+  - Status/error state
+  - Text fingerprint/hash (plaintext segment text is not stored)
+
+App-specific tables are manually maintained in Drizzle schema files, while auth tables are generated by the Better Auth CLI. Both are migrated together via Drizzle. See [Migrations](./migrations) for details.
+
+## What the database does not store
+
+- Raw document file bytes
+- Audiobook audio bytes
+- TTS segment audio bytes
+- Generated preview image bytes
+
+Those payloads live in object storage. SQL stores the metadata, references, and status.
+
+## Related variables
+
+- `POSTGRES_URL`
+
+For database variable behavior, see [Environment Variables](../reference/environment-variables#database-and-object-blob-storage).
+
+## Related docs
+
+- [Migrations](./migrations)
+- [Object / Blob Storage](./object-blob-storage)
+- [Auth](./auth)
+
+## State sync summary
+
+- Settings and reading progress are stored in SQL and synced from the app.
+- Sync is currently request-based (not realtime push invalidation).

docs-site/versioned_docs/version-v4.0.0/configure/migrations.md

@@ -0,0 +1,150 @@
+---
+title: Migrations
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This page covers migration behavior for both database schema and storage data in OpenReader.
+
+## Startup migration behavior
+
+By default, the shared entrypoint runs migrations automatically before app startup in:
+
+- Docker container startup
+- `pnpm dev`
+- `pnpm start`
+
+Startup migration phases:
+
+- DB schema migrations (`pnpm migrate`)
+- Storage/data migration (`pnpm migrate-fs`) for legacy filesystem content into S3 + DB rows
+
+:::info
+In most setups, you do not need to run migration commands manually because startup handles this automatically.
+:::
+
+### Schema history
+
+Migrations are applied in order. All of the following ship in v3.0.0; an instance upgrading from v2.2.0 applies `0001`–`0004` in a single startup pass.
+
+| Migration | Dialects | What it does |
+| --- | --- | --- |
+| `0001_tts_segments` | SQLite + Postgres | Creates the original single-table `tts_segments` used by server-side TTS segment caching. |
+| `0002_add_segment_key_to_tts_segments` | SQLite + Postgres | Adds the `segment_key` column to `tts_segments` for stable locator-independent segment identity. |
+| `0003_tts_segments_v2_split` | SQLite + Postgres | Replaces `tts_segments` with a normalized two-table model: `tts_segment_entries` (one row per document segment + locator identity) and `tts_segment_variants` (one row per settings combination, holding the cached audio key, status, and alignment). Drops the original `tts_segments` table — no released build (v2.2.0 or earlier) ever populated it, so there is no production data to migrate. |
+| `0004_admin_panel` | SQLite + Postgres | Creates `admin_providers` (encrypted shared TTS provider rows) and `admin_settings` (runtime site-feature config), and adds the `is_admin` column to the `user` table. Backs the [Admin Panel](./admin-panel). |
+
+To skip automatic startup migrations:
+
+- Set `RUN_DRIZZLE_MIGRATIONS=false`
+- Set `RUN_FS_MIGRATIONS=false`
+
+:::warning
+If you disable startup migrations, ensure your deployment process runs migrations before serving traffic.
+:::
+
+## Apply migrations
+
+In most cases, you do not need manual migration commands because startup runs migrations automatically.
+
+`pnpm migrate` applies migrations for one database target:
+
+- Postgres when `POSTGRES_URL` is set
+- SQLite when `POSTGRES_URL` is unset
+
+You can always override the target explicitly with `--config`.
+
+<Tabs groupId="apply-migration-commands">
+  <TabItem value="project-scripts" label="Project Scripts" default>
+
+```bash
+# Run pending migrations for one target:
+# - Postgres if POSTGRES_URL is set
+# - SQLite if POSTGRES_URL is unset
+pnpm migrate
+
+# Run storage migration (filesystem -> S3 + DB)
+pnpm migrate-fs
+
+# Dry-run storage migration without uploading/deleting
+pnpm migrate-fs:dry-run
+```
+
+  </TabItem>
+  <TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
+
+```bash
+# Migrate SQLite
+pnpm exec drizzle-kit migrate --config drizzle.config.sqlite.ts
+
+# Migrate Postgres
+pnpm exec drizzle-kit migrate --config drizzle.config.pg.ts
+```
+
+  </TabItem>
+</Tabs>
+
+## Generate migrations
+
+`pnpm generate` is a two-phase script for contributors and schema changes:
+
+1. **Better Auth schema generation** — runs the Better Auth CLI twice (once for SQLite, once for Postgres) to produce auto-generated Drizzle schema files for auth tables (`user`, `session`, `account`, `verification`).
+2. **Drizzle migration generation** — runs `drizzle-kit generate` for both `drizzle.config.sqlite.ts` and `drizzle.config.pg.ts`, producing SQL migration files from all schema files (app + auth).
+
+:::note
+Most users do not need to run `pnpm generate`. Use it when contributing or when you have changed Drizzle schema files and need new migration files.
+:::
+
+### Schema ownership
+
+Auth tables are owned by Better Auth. Their Drizzle schema definitions are auto-generated and should **not** be hand-edited:
+
+- `src/db/schema_auth_sqlite.ts`
+- `src/db/schema_auth_postgres.ts`
+
+App-specific tables are manually maintained in the standard Drizzle schema files:
+
+- `src/db/schema_sqlite.ts`
+- `src/db/schema_postgres.ts`
+
+Both sets of schema files are included in the Drizzle configs, so `drizzle-kit generate` and `drizzle-kit migrate` handle all tables together.
+
+When app schema changes (for example `tts_segments`), keep these in sync:
+
+- `src/db/schema_sqlite.ts`
+- `src/db/schema_postgres.ts`
+- `drizzle/sqlite/*.sql` + `drizzle/sqlite/meta/_journal.json`
+- `drizzle/postgres/*.sql` + `drizzle/postgres/meta/_journal.json`
+
+<Tabs groupId="generate-migration-commands">
+  <TabItem value="project-script" label="Project Script" default>
+
+```bash
+# Full pipeline: Better Auth CLI + Drizzle generate (both dialects)
+pnpm generate
+```
+
+  </TabItem>
+  <TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
+
+```bash
+# Generate SQLite migrations only (skips Better Auth CLI)
+pnpm exec drizzle-kit generate --config drizzle.config.sqlite.ts
+
+# Generate Postgres migrations only (skips Better Auth CLI)
+pnpm exec drizzle-kit generate --config drizzle.config.pg.ts
+```
+
+:::warning
+Running `drizzle-kit generate` directly skips the Better Auth CLI step. If auth schema has changed upstream (e.g. after a Better Auth version bump), run `pnpm generate` instead to regenerate the auth schema files first.
+:::
+
+  </TabItem>
+</Tabs>
+
+## Related docs
+
+- [Database](./database)
+- [Object / Blob Storage](./object-blob-storage)
+- [Migration Environment Variables](../reference/environment-variables#migration-controls)

docs-site/versioned_docs/version-v4.0.0/configure/object-blob-storage.md

@@ -0,0 +1,167 @@
+---
+title: Object / Blob Storage
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This page documents storage backends, blob upload routing, and core Docker mount behavior.
+
+## Scope of this page
+
+- Focus: object/blob backends, keyspaces, upload/read paths, and storage debugging.
+- Not covered here: relational metadata tables and SQL state modeling (see [Database](./database)).
+
+## Storage backends
+
+- Embedded (default): embedded SeaweedFS (`weed mini`) blob storage.
+- External: external S3-compatible object storage.
+
+Metadata database mode (SQLite vs Postgres) is configured separately in [Database](./database).
+
+:::warning SeaweedFS Compatibility Note (April 16, 2026)
+OpenReader currently pins embedded SeaweedFS to `4.18` in CI and Docker builds.
+`4.19` introduced intermittent `InternalError` responses on S3 `PutObject` in our upload flow.
+:::
+
+Storage variables are documented in [Environment Variables](../reference/environment-variables#database-and-object-blob-storage).
+
+## Ports
+
+- `3003`: OpenReader app and API routes
+- `8333`: Embedded SeaweedFS S3 endpoint for direct browser blob access
+
+:::info
+`8333` is only needed for direct browser presigned access to embedded SeaweedFS.
+:::
+
+## Upload behavior
+
+- Primary path: browser uploads to presigned URL from `/api/documents/blob/upload/presign`.
+- Fallback path: `/api/documents/blob/upload/fallback` when direct upload fails/unreachable.
+- Read/download path: blob/content serving route `/api/documents/blob` (not the upload fallback route).
+- Preview path: `/api/documents/blob/preview` (returns `202` while a preview is generating; serves/redirects when ready).
+
+## Document previews
+
+- PDF/EPUB previews are generated server-side and stored in object storage under `document_previews_v1`.
+- Preview generation is triggered on upload registration and also backfills on first preview request for older docs.
+- Preview artifacts are temporary-cache friendly and can be regenerated from the source document blob.
+
+## FS / Volume Mounts
+
+### App data mount
+
+- Target: `/app/docstore`
+- Recommended: yes, for persistence
+- Purpose: persists SeaweedFS blob data, SQLite metadata DB, migrations, and local runtime temp state
+- Mount string: `-v openreader_docstore:/app/docstore`
+
+### Library source mount (optional)
+
+- Target: `/app/docstore/library`
+- Recommended: optional, use read-only (`:ro`)
+- Purpose: exposes host files as a source for server library import
+- Mount string: `-v /path/to/your/library:/app/docstore/library:ro`
+- Details: [Server Library Import](./server-library-import)
+
+## Private blob endpoint mode
+
+If `8333` is not published externally:
+
+- Document uploads still work through upload fallback proxy
+- Reads/snippets continue through app API routes
+- Direct presigned browser upload/download to embedded endpoint is unavailable
+
+:::warning
+Without `8333`, expect higher app-server traffic because uploads/downloads go through API routes instead of direct object endpoint access.
+:::
+
+## Audiobook Storage Debug Commands
+
+Audiobook assets are stored in object storage under the `audiobooks_v1` keyspace. Use these commands to inspect and download objects for debugging.
+
+<Tabs groupId="audiobook-storage-access-cli">
+  <TabItem value="aws-s3" label="AWS S3" default>
+
+```bash
+# List all audiobook objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive
+
+# Filter to one book id (replace <book-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive | grep "<book-id>-audiobook/"
+
+# Download one object by full key
+aws s3 cp "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/<path>/<file>.m4b" "./audiobook.m4b"
+```
+
+  </TabItem>
+  <TabItem value="s3-compatible" label="Embedded / MinIO / R2 / etc">
+
+```bash
+# List all audiobook objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive --endpoint-url "$S3_ENDPOINT"
+
+# Filter to one book id (replace <book-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive --endpoint-url "$S3_ENDPOINT" | grep "<book-id>-audiobook/"
+
+# Download one object by full key
+aws s3 cp "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/<path>/<file>.m4b" "./audiobook.m4b" --endpoint-url "$S3_ENDPOINT"
+```
+
+Embedded default example: `S3_ENDPOINT=http://127.0.0.1:8333` (or your mapped host/port).
+
+  </TabItem>
+</Tabs>
+
+## TTS Segment Storage
+
+Server-side TTS segment audio is stored in object storage under the `tts_segments_v1` keyspace.
+
+Typical key layout:
+
+- `${S3_PREFIX}/tts_segments_v1/users/<url-encoded-user-id>/docs/<document-id>/<document-version>/<settings-hash>/<segment-id>.mp3`
+- `${S3_PREFIX}/tts_segments_v1/ns/<test-namespace>/users/<url-encoded-user-id>/docs/...` (test namespace mode)
+
+Notes:
+
+- For the corresponding SQL metadata model (`tts_segments`), see [Database](./database).
+
+## Account Deletion Cleanup
+
+Account deletion performs best-effort object cleanup:
+
+- Document blobs + preview artifacts
+- Audiobook blobs
+- TTS segment blobs under `tts_segments_v1`
+
+If object deletion fails, account deletion still proceeds and orphaned objects may require manual cleanup.
+
+## TTS Segment Storage Debug Commands
+
+Use these commands to inspect segment objects.
+
+<Tabs groupId="tts-segment-storage-access-cli">
+  <TabItem value="aws-s3" label="AWS S3" default>
+
+```bash
+# List all TTS segment objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive
+
+# Filter to one document id (replace <document-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive | grep "/docs/<document-id>/"
+```
+
+  </TabItem>
+  <TabItem value="s3-compatible" label="Embedded / MinIO / R2 / etc">
+
+```bash
+# List all TTS segment objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive --endpoint-url "$S3_ENDPOINT"
+
+# Filter to one document id (replace <document-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive --endpoint-url "$S3_ENDPOINT" | grep "/docs/<document-id>/"
+```
+
+  </TabItem>
+</Tabs>

docs-site/versioned_docs/version-v4.0.0/configure/server-library-import.md

@@ -0,0 +1,68 @@
+---
+title: Server Library Import
+---
+
+This page documents how server library import works and how to configure it.
+
+## What it does
+
+Server library import lets you browse files from one or more server directories and import selected files into OpenReader.
+
+- Import is user-driven via a selection modal
+- Only selected files are imported
+- Imported files become normal OpenReader documents
+
+## FS / Volume Mounts
+
+### App data mount
+
+- Target: `/app/docstore`
+- Recommended: yes, for persistence
+- Purpose: stores app runtime data, metadata DB, and embedded storage state
+- Mount string: `-v openreader_docstore:/app/docstore`
+
+### Library source mount
+
+- Target: `/app/docstore/library`
+- Recommended: yes for this feature, use read-only (`:ro`)
+- Purpose: exposes host files as import candidates in Server Library Import
+- Mount string: `-v /path/to/your/library:/app/docstore/library:ro`
+
+## Import flow
+
+1. Open **Settings -> Documents -> Server Library Import**.
+2. Select files in the modal.
+3. Click **Import**.
+
+Selected files are fetched from the server library endpoint and imported into OpenReader storage.
+
+:::warning Shared Library Roots
+Library roots are configured at the server level (not per-user). Any user who can access Server Library Import can browse/import from the same configured roots.
+
+Imported documents are still saved to the importing user's document scope.
+:::
+
+## Supported file types
+
+- `.pdf`
+- `.epub`
+- `.html`, `.htm`
+- `.txt`
+- `.md`, `.mdown`, `.markdown`
+
+## Optional: Configure Library Roots
+
+You only need this when the default mounted path is not what you want.
+
+By default, OpenReader uses `docstore/library` as the import root. You can override that with environment variables:
+
+- `IMPORT_LIBRARY_DIRS` (takes precedence): multiple roots separated by comma, colon, or semicolon
+- `IMPORT_LIBRARY_DIR`: single root
+
+See [Environment Variables](../reference/environment-variables#library-import) for variable details.
+
+## Notes
+
+- Library listing is capped per request (up to 10,000 files).
+- When auth is enabled, library import endpoints require a valid session.
+- The mounted library is a source; removing it does not delete already imported documents.

docs-site/versioned_docs/version-v4.0.0/configure/tts-provider-guides/deepinfra.md

@@ -0,0 +1,42 @@
+---
+title: DeepInfra
+---
+
+Use DeepInfra's hosted TTS models as your provider.
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `deepinfra`.
+2. Keep base URL as `https://api.deepinfra.com/v1/openai`.
+3. Enter your API key.
+4. Set your preferred default model/voice.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=https://api.deepinfra.com/v1/openai
+API_KEY=your-deepinfra-key
+```
+
+**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
+
+1. Set provider to `Deepinfra`.
+2. The base URL is pre-filled, no changes needed.
+3. Enter your `API_KEY`.
+4. Choose a model and voice.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Notes
+
+- Available models include `hexgrad/Kokoro-82M` and `canopylabs/orpheus-3b-0.1-ft`.
+- Without an API key, only the free-tier model (`hexgrad/Kokoro-82M`) is shown in the dropdown.
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
+
+## References
+
+- [DeepInfra TTS models](https://deepinfra.com/models/text-to-speech)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.0/configure/tts-provider-guides/kitten-tts-fastapi.md

@@ -0,0 +1,47 @@
+---
+title: KittenTTS-FastAPI
+---
+
+Run [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider. Lightweight and CPU-friendly.
+
+## Run KittenTTS
+
+```bash
+docker run -it --rm \
+  --name kittentts-fastapi \
+  -e KITTEN_MODEL_REPO_ID="KittenML/kitten-tts-nano-0.8-fp32" \
+  -p 8005:8005 \
+  ghcr.io/richardr1126/kittentts-fastapi-cpu
+```
+
+## Connect to OpenReader
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set base URL to your KittenTTS endpoint (e.g. `http://kittentts-fastapi:8005/v1`).
+3. Leave API key blank unless required by your deployment.
+4. Set default model to `kitten-tts` (or your backend model id).
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://kittentts-fastapi:8005/v1
+```
+
+> Use `kittentts-fastapi` if that's the container name, or `host.docker.internal` if not.
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your KittenTTS endpoint (e.g. `http://kittentts-fastapi:8005/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `kitten-tts` (or the model your deployment exposes).
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## References
+
+- [richardr1126/KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.0/configure/tts-provider-guides/kokoro-fastapi.md

@@ -0,0 +1,75 @@
+---
+title: Kokoro-FastAPI
+---
+
+Run [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
+
+:::warning
+For Kokoro issues and support, use the upstream repository: [remsky/Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI).
+:::
+
+## Run Kokoro
+
+**CPU:**
+
+```bash
+docker run --name kokoro-tts \
+  --restart unless-stopped \
+  -d \
+  -p 8880:8880 \
+  -e ONNX_NUM_THREADS=8 \
+  -e ONNX_INTER_OP_THREADS=4 \
+  -e ONNX_EXECUTION_MODE=parallel \
+  -e ONNX_OPTIMIZATION_LEVEL=all \
+  -e ONNX_MEMORY_PATTERN=true \
+  -e ONNX_ARENA_EXTEND_STRATEGY=kNextPowerOfTwo \
+  -e API_LOG_LEVEL=DEBUG \
+  ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
+```
+
+**GPU (NVIDIA):**
+
+```bash
+docker run --name kokoro-tts \
+  --restart unless-stopped \
+  -d \
+  --gpus all \
+  --user 1001:1001 \
+  -p 8880:8880 \
+  -e USE_GPU=true \
+  -e PYTHONUNBUFFERED=1 \
+  -e API_LOG_LEVEL=DEBUG \
+  ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.4
+```
+
+## Connect to OpenReader
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set base URL to your Kokoro endpoint (e.g. `http://kokoro-tts:8880/v1`).
+3. Leave API key blank unless required by your deployment.
+4. Set default model to `Kokoro`.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://kokoro-tts:8880/v1
+```
+
+> Use `kokoro-tts` if that's the container name, or `host.docker.internal` if not.
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your Kokoro endpoint (e.g. `http://kokoro-tts:8880/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `Kokoro`.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## References
+
+- [remsky/Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.0/configure/tts-provider-guides/openai.md

@@ -0,0 +1,41 @@
+---
+title: OpenAI
+---
+
+Use the OpenAI TTS API as your provider.
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `openai`.
+2. Keep base URL as `https://api.openai.com/v1`.
+3. Enter your API key.
+4. Set your preferred default model/voice.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=https://api.openai.com/v1
+API_KEY=sk-...
+```
+
+**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
+
+1. Set provider to `OpenAI`.
+2. The base URL is pre-filled, no changes needed.
+3. Enter your `API_KEY`.
+4. Choose a model and voice.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Notes
+
+- Models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
+
+## References
+
+- [OpenAI TTS pricing](https://platform.openai.com/docs/pricing#transcription-and-speech)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.0/configure/tts-provider-guides/orpheus-fastapi.md

@@ -0,0 +1,41 @@
+---
+title: Orpheus-FastAPI
+---
+
+Run [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
+
+## Run Orpheus
+
+Refer to the upstream repository for Docker instructions: [Lex-au/Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI).
+
+## Connect to OpenReader
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set base URL to your Orpheus endpoint (e.g. `http://orpheus:8000/v1`).
+3. Leave API key blank unless required by your deployment.
+4. Set default model to `Orpheus` (or your backend model id).
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://orpheus:8000/v1
+```
+
+> Use the container name if that's how it's named, or `host.docker.internal` if not.
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your Orpheus endpoint (e.g. `http://orpheus:8000/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `Orpheus` (or the model your deployment exposes).
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## References
+
+- [Lex-au/Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.0/configure/tts-provider-guides/other.md

@@ -0,0 +1,52 @@
+---
+title: Other
+---
+
+Use any OpenAI-compatible TTS service with OpenReader, including self-hosted servers not covered by a dedicated guide.
+
+## Requirements
+
+Your service must expose these endpoints:
+
+- `GET /v1/audio/voices`
+- `POST /v1/audio/speech`
+
+Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS-FastAPI](./kitten-tts-fastapi), [Orpheus-FastAPI](./orpheus-fastapi).
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set `API_BASE` to your service base URL (typically ending in `/v1`).
+3. Set API key if your service requires authentication.
+4. Set a default model/voice supported by your backend.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://your-tts-server/v1
+API_KEY=optional-key-if-required
+```
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your service's base URL (typically ending in `/v1`).
+3. Set `API_KEY` if your service requires authentication.
+4. Choose a model and voice supported by your backend.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+:::warning TTS requests are server-side
+`API_BASE` must be reachable from the **Next.js server**, not just the browser. In Docker, use container names or `host.docker.internal`.
+:::
+
+## Troubleshooting
+
+If voices don't load, check that `/v1/audio/voices` is reachable from the server and returns a valid response shape.
+
+## References
+
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.0/configure/tts-provider-guides/replicate.md

@@ -0,0 +1,48 @@
+---
+title: Replicate
+---
+
+Use Replicate's hosted TTS models as your provider.
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `replicate`.
+2. Enter your API key.
+3. Set default model to:
+   `alphanumericuser/kokoro-82m:89b6fa84e4fa2dd6bd3a96be3e1f12827a3516c9fda8fddbac7a0be131c9a6f5` (or your preferred model).
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_KEY=r8_...
+```
+
+Then update the shared provider's **Default model** in **Settings → Admin → Shared providers**.
+
+**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
+
+1. Set provider to `Replicate`.
+2. Enter your `API_KEY`.
+3. Choose a model and voice.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Notes
+
+- Built-in Replicate models:
+  - `alphanumericuser/kokoro-82m:89b6fa84e4fa2dd6bd3a96be3e1f12827a3516c9fda8fddbac7a0be131c9a6f5`
+  - `google/gemini-3.1-flash-tts`
+  - `minimax/speech-2.8-turbo`
+  - `qwen/qwen3-tts`
+  - `inworld/tts-1.5-mini`
+- You can also choose `Other` and enter any Replicate model ID (for example `owner/model-name` or `owner/model-name:version`).
+- Native model speed is not available on all Replicate models; OpenReader hides/disables native speed controls where unsupported.
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
+
+## References
+
+- [Replicate](https://replicate.com/explore)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.0/configure/tts-providers.md

@@ -0,0 +1,57 @@
+---
+title: TTS Providers
+---
+
+OpenReader routes all TTS requests through the Next.js server to an OpenAI-compatible API. There are three places provider configuration can live:
+
+**Admin-managed shared providers** (Settings > Admin > Shared providers): DB-backed instances configured by an admin and visible to all users. Keys are encrypted at rest and never exposed to the client. Available only when [auth is enabled](./auth) and your account is in `ADMIN_EMAILS`. See [Admin Panel](./admin-panel).
+
+**Per-user Settings modal** (Settings > TTS Provider): provider + API key stored in the user's browser and sent with every TTS request. This path is available only when the admin/runtime setting `restrictUserApiKeys=false`.
+
+**Environment variables**: `API_KEY` and `API_BASE` exist as a one-shot first-boot seed that auto-creates a `default-openai` admin shared provider. After the first boot they are no longer read by the running app.
+
+:::tip
+If you're running a private/self-hosted instance and want per-user BYOK behavior, turn off **Settings → Admin → Site features → Restrict user API keys**. For first-boot automation, set `runtimeConfig.restrictUserApiKeys=false` in `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH`.
+:::
+
+## Providers
+
+- **OpenAI**: Cloud. Base URL pre-filled (`https://api.openai.com/v1`). API key required.
+- **Replicate**: Cloud. Base URL managed internally by OpenReader. API key required.
+- **DeepInfra**: Cloud. Base URL pre-filled (`https://api.deepinfra.com/v1/openai`). API key required.
+- **Custom OpenAI-Like**: Self-hosted or any custom endpoint. `API_BASE` must be set manually (typically ending in `/v1`). API key optional.
+
+For `OpenAI`, `DeepInfra`, and `Replicate` you only need to supply an API key. For `Custom OpenAI-Like` you must also set `API_BASE`.
+
+## Built-in model catalogs
+
+- **Replicate** models: `alphanumericuser/kokoro-82m`, `google/gemini-3.1-flash-tts`, `minimax/speech-2.8-turbo`, `qwen/qwen3-tts`, `inworld/tts-1.5-mini` (or choose `Other` and enter any Replicate model ID, such as `owner/model` or `owner/model:version`)
+- **OpenAI** models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
+- **DeepInfra** models: includes `hexgrad/Kokoro-82M` and additional hosted models (depending on API key / feature flags)
+
+## Custom provider requirements
+
+Self-hosted or custom providers must expose OpenAI-compatible audio endpoints:
+
+- `GET /v1/audio/voices`
+- `POST /v1/audio/speech`
+
+:::warning TTS requests are server-side
+TTS requests originate from the **Next.js server**, not the browser. `API_BASE` must be reachable from the server runtime. In Docker, use container names or `host.docker.internal` rather than `localhost`.
+:::
+
+## Provider guides
+
+- [Kokoro-FastAPI](./tts-provider-guides/kokoro-fastapi)
+- [KittenTTS-FastAPI](./tts-provider-guides/kitten-tts-fastapi)
+- [Orpheus-FastAPI](./tts-provider-guides/orpheus-fastapi)
+- [Replicate](./tts-provider-guides/replicate)
+- [DeepInfra](./tts-provider-guides/deepinfra)
+- [OpenAI](./tts-provider-guides/openai)
+- [Other](./tts-provider-guides/other)
+
+## Related
+
+- [Admin Panel](./admin-panel) — DB-backed shared providers with encrypted keys
+- [TTS Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
+- [TTS Rate Limiting](./tts-rate-limiting)

docs-site/versioned_docs/version-v4.0.0/configure/tts-rate-limiting.md

@@ -0,0 +1,42 @@
+---
+title: TTS Rate Limiting
+---
+
+This page explains OpenReader's TTS character rate limiting controls.
+
+## Overview
+
+- TTS rate limiting is disabled by default.
+- Primary control is **Settings → Admin → Site features → Disable TTS daily rate limiting**.
+- Limits are enforced per day in UTC.
+- Enforcement applies only when auth is enabled.
+
+## How enforcement works
+
+When enabled, OpenReader enforces:
+
+- Per-user daily character limits.
+- IP backstop daily character limits.
+- Anonymous device backstop tracking (cookie-based) to reduce limit resets.
+
+If a request exceeds the active limit, the TTS API returns `429` with reset metadata for the next UTC day.
+
+## Required auth behavior
+
+- Auth must be enabled (`BASE_URL` + `AUTH_SECRET`) for TTS char limits to apply.
+- If auth is disabled, TTS character limits are effectively unlimited.
+- `DISABLE_AUTH_RATE_LIMIT` only affects Better Auth's own request throttling.
+- `DISABLE_AUTH_RATE_LIMIT` does not disable TTS character limits.
+
+## Runtime config
+
+- `disableTtsRateLimit` default: `true`
+- Per-user and IP backstop limit values are configured in **Settings → Admin → Site features** and stored in DB runtime settings.
+- Optional first-boot seeding can be done via `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH` (`runtimeConfig.disableTtsRateLimit`).
+
+## Related docs
+
+- TTS/rate-limit environment variables: [Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
+- PDF parsing rate limiting (separate, compute-side throttle): [Admin Panel → Site features](./admin-panel#site-features) and [Environment Variables](../reference/environment-variables#compute-pdf-parsing-rate-limiting-runtime-settings)
+- Auth configuration: [Auth](./auth)
+- Provider setup: [TTS Providers](./tts-providers)

docs-site/versioned_docs/version-v4.0.0/deploy/compute-worker.md

@@ -0,0 +1,221 @@
+title: Compute Worker (NATS JetStream)
+---
+
+Use this guide when compute-worker runs as a standalone service outside the Next.js app server.
+For embedded/local startup (`pnpm dev` / `pnpm start` without `COMPUTE_WORKER_URL`), use root `.env` instead.
+
+## Overview
+
+The compute worker handles:
+
+- Whisper word alignment operations
+- PDF layout parsing operations
+
+The app server submits operations to `POST /ops`, reuses in-flight work via required `opKey`, and consumes status updates via `GET /ops/:opId/events` (SSE). Queue durability and retries are backed by NATS JetStream WorkQueue consumers and NATS KV.
+
+## Published image
+
+- App server image: `ghcr.io/richardr1126/openreader`
+- Compute worker image: `ghcr.io/richardr1126/openreader-compute-worker`
+- Compute worker image (example pinned tag): `ghcr.io/richardr1126/openreader-compute-worker:refactor-ppdoclayoutv3-onnx-layout-parsing`
+
+## Worker environment variables
+
+Required:
+
+- `COMPUTE_WORKER_TOKEN`: bearer token expected by worker routes
+- `NATS_URL`: NATS server connection string (JetStream enabled)
+- `S3_BUCKET`
+- `S3_REGION`
+- `S3_ACCESS_KEY_ID`
+- `S3_SECRET_ACCESS_KEY`
+
+> [!IMPORTANT]
+> This file (`compute/worker/.env*`) is only for standalone worker deployments.
+> In embedded/local startup, app entrypoint spawns worker with the already-resolved root `.env` values.
+> In standalone external worker mode:
+> - App server env (root `.env` or platform env): `COMPUTE_WORKER_URL`, `COMPUTE_WORKER_TOKEN`, optional shared timeout/stale overrides.
+> - Worker service env (`compute/worker/.env*` or platform env): worker runtime values (`NATS_*`, `S3_*`, model base URLs, worker tuning).
+> For standalone worker deployments, keep shared app/worker values aligned:
+> - `COMPUTE_WORKER_TOKEN`
+> - shared object storage settings (`S3_*`)
+> - shared timeout/stale settings (`COMPUTE_WHISPER_TIMEOUT_MS`, `COMPUTE_PDF_TIMEOUT_MS`, `COMPUTE_OP_STALE_MS`)
+
+Common optional:
+
+- `NATS_CREDS`: raw user credentials file content (JWT + private key), ideal for cloud container environments where mounting files is difficult.
+- `NATS_CREDS_FILE`: path to a `.creds` file on the server.
+- `S3_ENDPOINT` (for non-AWS S3-compatible storage)
+- `S3_FORCE_PATH_STYLE=true` (for many S3-compatible providers)
+- `S3_PREFIX=openreader`
+- `COMPUTE_WORKER_HOST=0.0.0.0`
+- `PORT=8081` (local/manual; on Railway platform injects this)
+- `LOG_FORMAT=pretty` (default) or `json`
+
+Advanced tuning (usually leave unset unless you need overrides):
+
+- `COMPUTE_PREWARM_MODELS=true`
+- `COMPUTE_JOB_CONCURRENCY=1` (shared total compute jobs across whisper + PDF)
+- `COMPUTE_WHISPER_TIMEOUT_MS=30000`
+- `COMPUTE_PDF_TIMEOUT_MS=300000`
+- `WHISPER_MODEL_BASE_URL=https://huggingface.co/onnx-community/whisper-base_timestamped/resolve/main` (optional override, q4 defaults)
+- `PDF_LAYOUT_MODEL_BASE_URL=https://huggingface.co/Bei0001/PP-DocLayoutV3-ONNX/resolve/main` (optional override)
+- `COMPUTE_PDF_JOB_ATTEMPTS=1` (PDF layout retry attempts)
+- `COMPUTE_JOBS_STREAM_MAX_BYTES=268435456` (256MB JetStream jobs stream cap)
+- `COMPUTE_JOB_STATES_MAX_BYTES=67108864` (64MB JetStream KV bucket cap)
+- `COMPUTE_NATS_REPLICAS=1` (JetStream stream + KV replicas; valid: `1`, `3`, `5`)
+- `COMPUTE_OP_STALE_MS=1800000` (stale op replacement window)
+
+## App server environment variables
+
+Set on the Next.js app server:
+
+```env
+# Local worker example:
+# COMPUTE_WORKER_URL=http://localhost:8081
+# Cloud worker example (Railway):
+COMPUTE_WORKER_URL=https://<railway-worker-domain>
+COMPUTE_WORKER_TOKEN=<same-token-as-worker>
+# Optional shared timeout overrides (keep equal to worker service values):
+# COMPUTE_WHISPER_TIMEOUT_MS=30000
+# COMPUTE_PDF_TIMEOUT_MS=300000
+# COMPUTE_OP_STALE_MS=1800000
+```
+
+Model artifact overrides (`WHISPER_MODEL_BASE_URL`, `PDF_LAYOUT_MODEL_BASE_URL`) are worker runtime variables and should be set on the compute worker service environment. Current Whisper defaults expect q4 artifacts (`encoder_model_q4.onnx`, `decoder_model_merged_q4.onnx`, `decoder_with_past_model_q4.onnx`) under that base URL.
+
+`COMPUTE_OP_STALE_MS` is shared by both services in worker mode:
+
+- Worker: opKey stale replacement window in compute op state.
+- App server: stale PDF parse-state healing window (`/api/documents/[id]/parsed*`).
+
+Set the same value on app + worker envs.
+
+There is no app-local compute fallback. If worker is unavailable, affected requests fail.
+
+## Config ownership summary
+
+- Embedded/local startup (`pnpm dev` / `pnpm start`, no `COMPUTE_WORKER_URL`):
+  - Configure root `.env` only.
+  - `compute/worker/.env*` is ignored.
+- Standalone external worker service:
+  - Configure app root `.env` with `COMPUTE_WORKER_URL` + `COMPUTE_WORKER_TOKEN`.
+  - Configure worker service env (`compute/worker/.env*` or platform env).
+  - Keep shared values aligned (`COMPUTE_WORKER_TOKEN`, `S3_*`, timeout/stale values).
+
+## Production notes
+
+- Worker mode assumes shared object storage is reachable by both app server and worker.
+- Non-exposed embedded `weed mini` is not supported with external worker mode.
+- Protect `COMPUTE_WORKER_TOKEN` and avoid exposing worker routes publicly without auth.
+
+## Railway sleep & idle behavior
+
+The worker connects to NATS lazily (on the first request needing the queue/KV) and
+disconnects after **120s** of full idle — no in-flight request, SSE stream, job, or
+queued work. This stops outbound pull polling and keepalive PINGs so Railway can sleep
+it; the next inbound request transparently reconnects, re-ensures the stream/consumers
+and KV (idempotent), and drains anything pending. No separate mode, no extra env vars,
+and the `/ops*` contract is unchanged.
+
+Caveats: inbound HTTP is the wake signal (in OpenReader the app server only enqueues via
+`POST /ops`, so this is always satisfied); a continuous external `/health/*` probe keeps
+it awake and prevents sleep; and the first request after a cold start re-runs model
+prewarm, so it's slower.
+
+## Health endpoints
+
+- `GET /health/live` — liveness; always returns `{ ok: true }`.
+- `GET /health/ready` — returns `{ ok: true, natsConnected }`. It does not probe NATS (that
+  would reconnect and prevent idle sleep); `natsConnected` just reflects the current session.
+
+## Synadia Cloud + Railway Setup (Complete Guide)
+
+Use this end-to-end guide when your queue backend is Synadia Cloud (NGS) and your worker runs on Railway.
+
+### 1. Create Synadia account and credentials
+
+1. Create a Synadia Cloud account and create/select your NGS environment.
+2. Create a user or service account for OpenReader compute worker access.
+3. Download the generated credentials file (usually `<name>.creds`) and keep it secure.
+
+You will use:
+
+- `NATS_URL=tls://connect.ngs.global:4222`
+- The full `.creds` file content
+
+### 2. Deploy compute worker on Railway
+
+Create a Railway service from:
+
+```text
+ghcr.io/richardr1126/openreader-compute-worker:refactor-ppdoclayoutv3-onnx-layout-parsing
+```
+
+Railway injects a dynamic `PORT` env var and routes traffic there.
+Do not hardcode Railway ingress to `8081`; keep service networking enabled and use the public Railway URL.
+
+### 3. Configure Railway worker environment variables
+
+Set these in the Railway worker service:
+
+```env
+COMPUTE_WORKER_HOST=0.0.0.0
+# Local/manual only:
+# PORT=8081
+# Railway: rely on injected PORT
+COMPUTE_WORKER_TOKEN=<long-random-shared-token>
+# Optional advanced tuning overrides (defaults shown):
+# COMPUTE_PREWARM_MODELS=true
+# COMPUTE_JOB_CONCURRENCY=1
+# COMPUTE_WHISPER_TIMEOUT_MS=30000
+# COMPUTE_PDF_TIMEOUT_MS=300000
+# WHISPER_MODEL_BASE_URL=https://huggingface.co/onnx-community/whisper-base_timestamped/resolve/main
+# # Expects q4 files at that base:
+# # - onnx/encoder_model_q4.onnx
+# # - onnx/decoder_model_merged_q4.onnx
+# # - onnx/decoder_with_past_model_q4.onnx
+# PDF_LAYOUT_MODEL_BASE_URL=https://huggingface.co/Bei0001/PP-DocLayoutV3-ONNX/resolve/main
+# COMPUTE_PDF_JOB_ATTEMPTS=1
+# COMPUTE_JOBS_STREAM_MAX_BYTES=268435456
+# COMPUTE_JOB_STATES_MAX_BYTES=67108864
+# COMPUTE_NATS_REPLICAS=1
+
+NATS_URL=tls://connect.ngs.global:4222
+NATS_CREDS="-----BEGIN NATS USER JWT-----
+...
+------END USER NKEY SEED------"
+
+S3_BUCKET=<bucket>
+S3_REGION=<region>
+S3_ACCESS_KEY_ID=<key>
+S3_SECRET_ACCESS_KEY=<secret>
+S3_ENDPOINT=<optional-for-s3-compatible-providers>
+S3_FORCE_PATH_STYLE=true
+S3_PREFIX=openreader
+```
+
+Notes:
+
+- `NATS_CREDS` should be the full Synadia `.creds` file content, including begin/end markers.
+- Keep `COMPUTE_WORKER_TOKEN` identical between app server and worker.
+- On Railway, leave `PORT` managed by the platform.
+- If your platform supports mounted files, you can use `NATS_CREDS_FILE` instead of `NATS_CREDS`.
+- `COMPUTE_JOBS_STREAM_MAX_BYTES` and `COMPUTE_JOB_STATES_MAX_BYTES` are optional; defaults are `268435456` (256MiB) and `67108864` (64MiB).
+- `COMPUTE_NATS_REPLICAS` is optional; default is `1`. Valid values are `1`, `3`, `5`.
+
+### 4. Configure the OpenReader app server
+
+Set these env vars on the app server:
+
+```env
+COMPUTE_WORKER_URL=https://<railway-worker-domain>
+COMPUTE_WORKER_TOKEN=<same-token-as-worker>
+```
+
+### 5. Verify health
+
+After deploy, check:
+
+- `GET https://<railway-worker-domain>/health/live`
+- `GET https://<railway-worker-domain>/health/ready`

docs-site/versioned_docs/version-v4.0.0/deploy/local-development.md

@@ -0,0 +1,371 @@
+---
+title: Local Development
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Prerequisites
+
+<details>
+<summary><strong>Node.js + pnpm (required)</strong></summary>
+
+<Tabs groupId="local-dev-node-pnpm-os">
+<TabItem value="macos" label="macOS" default>
+
+```bash
+brew install nvm pnpm
+mkdir -p ~/.nvm
+echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
+echo '[ -s "$(brew --prefix nvm)/nvm.sh" ] && . "$(brew --prefix nvm)/nvm.sh"' >> ~/.zshrc
+source ~/.zshrc
+nvm install --lts
+nvm use --lts
+node -v
+pnpm -v
+```
+
+</TabItem>
+<TabItem value="linux" label="Linux">
+
+```bash
+# Debian/Ubuntu example
+sudo apt update
+sudo apt install -y curl
+curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+nvm install --lts
+nvm use --lts
+corepack enable
+corepack prepare pnpm@latest --activate
+node -v
+pnpm -v
+```
+
+</TabItem>
+</Tabs>
+
+</details>
+
+<details>
+<summary><strong>SeaweedFS <code>weed</code> binary (required unless using external S3)</strong></summary>
+
+<Tabs groupId="local-dev-seaweed-os">
+<TabItem value="macos" label="macOS" default>
+
+```bash
+brew install seaweedfs
+weed version
+```
+
+:::warning SeaweedFS Compatibility Note (April 16, 2026)
+If you see intermittent S3 `InternalError` upload failures with embedded storage, use SeaweedFS `4.18`.
+OpenReader currently pins `4.18` in CI and Docker builds while `4.19` compatibility is investigated.
+:::
+
+</TabItem>
+<TabItem value="linux" label="Linux">
+
+```bash
+# Linux amd64 example (pin 4.18)
+mkdir -p "$HOME/.local/bin"
+curl -fsSL -o /tmp/seaweedfs.tar.gz \
+  https://github.com/seaweedfs/seaweedfs/releases/download/4.18/linux_amd64.tar.gz
+tar -xzf /tmp/seaweedfs.tar.gz -C /tmp weed
+install -m 0755 /tmp/weed "$HOME/.local/bin/weed"
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+export PATH="$HOME/.local/bin:$PATH"
+weed version
+```
+
+:::warning SeaweedFS Compatibility Note (April 16, 2026)
+If you see intermittent S3 `InternalError` upload failures with embedded storage, use SeaweedFS `4.18`.
+OpenReader currently pins `4.18` in CI and Docker builds while `4.19` compatibility is investigated.
+:::
+
+</TabItem>
+</Tabs>
+
+</details>
+
+<details>
+<summary><strong>NATS Server <code>nats-server</code> (required for embedded compute mode)</strong></summary>
+
+If `COMPUTE_WORKER_URL` is unset, startup launches embedded compute worker + NATS, so `nats-server` must be available on host PATH.
+
+If you always use an external worker (`COMPUTE_WORKER_URL` set), this is not required.
+
+<Tabs groupId="local-dev-nats-os">
+<TabItem value="macos" label="macOS" default>
+
+```bash
+brew install nats-server
+nats-server -v
+```
+
+</TabItem>
+<TabItem value="linux" label="Linux">
+
+```bash
+# Linux amd64 example
+mkdir -p "$HOME/.local/bin"
+curl -fsSL -o /tmp/nats-server.zip \
+  https://github.com/nats-io/nats-server/releases/latest/download/nats-server-v2.12.1-linux-amd64.zip
+unzip -j /tmp/nats-server.zip '*/nats-server' -d /tmp
+install -m 0755 /tmp/nats-server "$HOME/.local/bin/nats-server"
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+export PATH="$HOME/.local/bin:$PATH"
+nats-server -v
+```
+
+</TabItem>
+</Tabs>
+
+</details>
+
+<details>
+<summary><strong>LibreOffice (optional, for DOCX conversion)</strong></summary>
+
+<Tabs groupId="local-dev-libreoffice-os">
+<TabItem value="macos" label="macOS" default>
+
+```bash
+brew install libreoffice
+```
+
+</TabItem>
+<TabItem value="linux" label="Linux">
+
+```bash
+# Debian/Ubuntu example
+sudo apt update
+sudo apt install -y libreoffice
+```
+
+</TabItem>
+</Tabs>
+
+</details>
+
+<details>
+<summary><strong>Word-by-word highlighting (optional)</strong></summary>
+
+No extra native Whisper CLI build step is required.
+
+Word-by-word highlighting and PDF layout parsing are worker-backed in current releases.
+
+If you need mirrors or pinned artifact locations, set `WHISPER_MODEL_BASE_URL` in `.env` (current defaults expect q4 Whisper files at that base URL).
+
+</details>
+
+<details>
+<summary><strong>External compute worker dev stack (optional)</strong></summary>
+
+Use this only when you intentionally run compute-worker as a separate service.
+Default local flow does not need `compute/worker/.env`; embedded worker startup reads root `.env`.
+Full worker deployment details are in [Compute Worker (NATS JetStream)](./compute-worker).
+
+Start only NATS + compute-worker via compose watch:
+
+```bash
+docker compose --env-file compute/worker/.env -f compute/worker/docker-compose.yml up --watch
+# or: pnpm compute:dev:watch
+```
+
+`compute/worker/.env.example` contains a starter config for standalone worker service deployments.
+
+Run the main app separately on the host:
+
+```bash
+pnpm dev
+```
+
+For app -> external worker routing, set in root `.env`:
+
+```env
+COMPUTE_WORKER_URL=http://localhost:8081
+COMPUTE_WORKER_TOKEN=<same-token-used-by-worker>
+```
+
+Ownership in external worker mode:
+- root `.env`: app routing/auth (`COMPUTE_WORKER_URL`, `COMPUTE_WORKER_TOKEN`) plus optional shared timeout/stale overrides
+- `compute/worker/.env*` (or worker platform env): worker runtime variables (`NATS_*`, `S3_*`, model base URLs, worker tuning)
+
+Worker mode requires worker-reachable shared object storage (S3-compatible endpoint).
+For external worker mode, object storage must be shared/reachable by both app and worker services.
+
+</details>
+
+## Steps
+
+### Required flow
+
+1. Clone the repository.
+
+```bash
+git clone https://github.com/richardr1126/openreader.git
+cd openreader
+```
+
+2. Install dependencies.
+
+```bash
+pnpm i
+```
+
+3. Configure the environment.
+
+```bash
+cp .env.example .env
+```
+
+Then edit `.env`.
+
+Default embedded worker flow (no external worker URL):
+
+```env
+# Leave COMPUTE_WORKER_URL unset.
+# Entry point auto-starts embedded worker+NATS when available.
+```
+
+External worker flow:
+
+```env
+COMPUTE_WORKER_URL=http://localhost:8081
+COMPUTE_WORKER_TOKEN=<same-token-used-by-worker>
+```
+
+Use the same ownership split:
+- root `.env`: app routing/auth (`COMPUTE_WORKER_URL`, `COMPUTE_WORKER_TOKEN`) plus optional shared timeout/stale overrides
+- `compute/worker/.env*` (or worker platform env): worker runtime variables (`NATS_*`, `S3_*`, model base URLs, worker tuning)
+
+Use one of these `.env` mode templates:
+
+<Tabs groupId="local-env-modes">
+  <TabItem value="auth-enabled" label="Auth Enabled" default>
+
+```env
+API_BASE=http://host.docker.internal:8880/v1
+API_KEY=none
+BASE_URL=http://localhost:3003
+AUTH_SECRET=<generate-with-openssl-rand-hex-32>
+# Optional when you need multiple local origins:
+# AUTH_TRUSTED_ORIGINS=http://localhost:3003,http://127.0.0.1:3003
+```
+
+  </TabItem>
+  <TabItem value="auth-with-admin" label="Auth + Admin Panel">
+
+```env
+# API_BASE / API_KEY are seeded into the admin "default-openai" shared provider
+# on first boot, then no longer read. Manage them in Settings → Admin afterwards.
+API_BASE=http://host.docker.internal:8880/v1
+API_KEY=none
+BASE_URL=http://localhost:3003
+AUTH_SECRET=<generate-with-openssl-rand-hex-32>
+# Comma-separated emails to auto-promote to admin on signin.
+ADMIN_EMAILS=you@example.com
+```
+
+  </TabItem>
+  <TabItem value="external-s3" label="External S3">
+
+```env
+API_BASE=http://host.docker.internal:8880/v1
+API_KEY=none
+USE_EMBEDDED_WEED_MINI=false
+BASE_URL=http://localhost:3003
+AUTH_SECRET=<generate-with-openssl-rand-hex-32>
+S3_BUCKET=your-bucket
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=your-access-key
+S3_SECRET_ACCESS_KEY=your-secret-key
+# Optional for non-AWS providers:
+# S3_ENDPOINT=https://your-s3-compatible-endpoint
+# S3_FORCE_PATH_STYLE=true
+```
+
+  </TabItem>
+  <TabItem value="worker-mode" label="External Worker Service">
+
+```env
+API_BASE=http://host.docker.internal:8880/v1
+API_KEY=none
+BASE_URL=http://localhost:3003
+AUTH_SECRET=<generate-with-openssl-rand-hex-32>
+COMPUTE_WORKER_URL=http://localhost:8081
+COMPUTE_WORKER_TOKEN=<same-token-used-by-worker>
+USE_EMBEDDED_WEED_MINI=false
+S3_BUCKET=your-bucket
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=your-access-key
+S3_SECRET_ACCESS_KEY=your-secret-key
+# Optional for non-AWS providers:
+# S3_ENDPOINT=https://your-s3-compatible-endpoint
+# S3_FORCE_PATH_STYLE=true
+```
+
+  </TabItem>
+</Tabs>
+
+:::note Env vars vs. admin panel
+On first boot, `API_KEY` / `API_BASE` can bootstrap `default-openai`, and `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH` can seed runtime config + providers. After that, the admin UI is authoritative and editing bootstrap env vars no longer changes app behavior. See [Admin Panel](../configure/admin-panel).
+:::
+
+:::note User BYOK restriction default
+If you want each user to enter personal provider credentials, set `restrictUserApiKeys=false` (from **Settings → Admin**, or by seeding `runtimeConfig.restrictUserApiKeys=false` in runtime seed JSON).
+:::
+
+:::info
+For all environment variables, see [Environment Variables](../reference/environment-variables).
+:::
+
+See [Auth](../configure/auth) for app/auth behavior.
+See [Admin Panel](../configure/admin-panel) for the shared-provider and feature-flag management UI.
+Storage configuration details are in [Object / Blob Storage](../configure/object-blob-storage).
+Refer to [Database](../configure/database) for database modes.
+Learn about migration behavior and commands in [Migrations](../configure/migrations).
+
+4. Start the app.
+
+<Tabs groupId="local-run-mode">
+  <TabItem value="dev" label="Dev (recommended)" default>
+
+```bash
+pnpm dev
+```
+
+If you use embedded worker startup (no `COMPUTE_WORKER_URL`) and the host is missing `nats-server`,
+install `nats-server` locally or switch to external worker mode.
+
+  </TabItem>
+  <TabItem value="prod" label="Build + Start">
+
+```bash
+pnpm build
+pnpm start
+```
+
+  </TabItem>
+</Tabs>
+
+:::warning API Base Reachability
+`API_BASE` must be reachable from the Next.js server process, not just your browser.
+:::
+
+Visit [http://localhost:3003](http://localhost:3003).
+
+### Optional workflows
+
+Run manual DB migrations only for troubleshooting or explicit migration workflows:
+
+- Migrations run automatically on startup through the shared entrypoint for both `pnpm dev` and `pnpm start`.
+
+```bash
+pnpm migrate
+```
+
+:::info
+If `POSTGRES_URL` is set, migrations target Postgres; otherwise local SQLite is used. To disable automatic startup migrations, set `RUN_DRIZZLE_MIGRATIONS=false` and/or `RUN_FS_MIGRATIONS=false`. You can run storage migration manually with `pnpm migrate-fs`.
+:::

docs-site/versioned_docs/version-v4.0.0/deploy/vercel-deployment.md

@@ -0,0 +1,154 @@
+---
+title: Vercel Deployment
+---
+
+This guide covers deploying OpenReader to Vercel with external Postgres and S3-compatible object storage.
+
+## What works on Vercel
+
+- Documents (PDF/EPUB/TXT/MD) work with `POSTGRES_URL` + external S3 storage.
+- Audiobook routes work on Node.js serverless functions using `ffmpeg-static`.
+- Heavy compute features (Whisper alignment + PDF layout parsing) run through an external compute worker service.
+- For worker setup details and worker-specific env vars, see [Compute Worker (NATS JetStream)](./compute-worker).
+
+:::warning DOCX Conversion Limitation
+`docx` conversion requires `soffice` (LibreOffice), which is not available in a standard Vercel runtime.
+:::
+
+## 1. Environment Variables
+
+Recommended production setup (auth enabled, admin panel enabled):
+
+```bash
+# Infrastructure
+POSTGRES_URL=postgres://...
+USE_EMBEDDED_WEED_MINI=false
+S3_ACCESS_KEY_ID=...
+S3_SECRET_ACCESS_KEY=...
+S3_BUCKET=...
+S3_REGION=us-east-1
+S3_PREFIX=openreader
+# Optional (non-AWS S3-compatible providers):
+# S3_ENDPOINT=https://...
+# S3_FORCE_PATH_STYLE=true
+
+# Auth (required for the admin panel)
+BASE_URL=https://your-app.vercel.app
+AUTH_SECRET=...
+ADMIN_EMAILS=you@example.com  # comma-separated; admins manage TTS + features in-app
+
+# Heavy compute (required on Vercel in current releases)
+COMPUTE_WORKER_URL=https://<railway-worker-domain>
+COMPUTE_WORKER_TOKEN=...
+
+# Logging (recommended for Vercel log ingestion)
+LOG_FORMAT=json
+LOG_LEVEL=info
+
+# First-boot seed for the TTS shared provider (optional; manage in-app afterwards)
+# API_KEY=your_replicate_key
+# API_BASE only needed for OpenAI-compatible self-hosted providers
+```
+
+If you also run an external worker service (for example Railway), set these there too:
+
+- `LOG_FORMAT=json`
+- `COMPUTE_LOG_LEVEL=info`
+
+:::note Env vars vs. admin panel (important for Vercel)
+`API_KEY` / `API_BASE` are one-shot bootstrap seeds on first deploy. After boot, manage providers and site features in **Settings → Admin**. Changes there apply on refresh without a redeploy. See [Admin Panel](../configure/admin-panel).
+:::
+
+## 1a. Railway + Synadia quick start (worker mode)
+
+If your Vercel app uses an external compute worker on Railway with Synadia Cloud (NGS):
+
+1. Deploy a Railway service from:
+   - `ghcr.io/richardr1126/openreader-compute-worker:refactor-ppdoclayoutv3-onnx-layout-parsing`
+2. Enable public networking on that Railway service and set:
+   - `COMPUTE_WORKER_URL=https://<railway-worker-domain>` (in Vercel)
+3. Use the same `COMPUTE_WORKER_TOKEN` value in both Vercel and Railway worker env vars.
+
+For complete Railway worker env vars (`NATS_*`, `S3_*`, health checks, and Synadia `.creds` guidance), see [Compute Worker (NATS JetStream)](./compute-worker).
+
+## 2. First-run admin configuration (recommended)
+
+After the first successful deploy and admin login, open **Settings → Admin** and configure:
+
+- **Shared providers**: create/edit your provider key(s) here (encrypted at rest).
+- **Site features**:
+  - `enableDocxConversion=false` on Vercel (`soffice` unavailable).
+  - `enableDestructiveDeleteActions=false` for safer public deployments.
+  - `enableTtsProvidersTab=false` if you want shared-provider-only UX.
+  - `enableUserSignups=true` unless you explicitly want an invite-only deployment.
+  - `restrictUserApiKeys=true` to block user BYOK through the hosted server.
+  - `defaultTtsProvider=replicate` (or your preferred shared slug).
+  - `showAllProviderModels=false` if you want users locked to each provider's default model.
+  - `enableAudiobookExport=true`.
+
+## 3. Runtime JSON seed (optional)
+
+If you must pre-seed site features/providers at deploy time, use `RUNTIME_SEED_JSON` or `RUNTIME_SEED_JSON_PATH` (versioned JSON seed document). Prefer the admin panel for ongoing management.
+
+See [Environment Variables](../reference/environment-variables#runtime-json-seed-v4) for schema and examples.
+
+:::warning Auth recommendation
+Set both `BASE_URL` and `AUTH_SECRET` — they are required in v4+ and also required for the admin panel and for encrypting admin-stored TTS credentials.
+:::
+
+:::warning Rotating AUTH_SECRET invalidates admin-stored keys
+Admin-managed TTS provider keys are encrypted with a key derived from `AUTH_SECRET`. If you rotate `AUTH_SECRET` after the first deploy, you must re-enter each admin shared provider's API key from the UI.
+:::
+
+:::tip
+For all variables and defaults, see [Environment Variables](../reference/environment-variables).
+:::
+
+## 4. Database and data migrations
+
+Vercel deployments do not run `scripts/openreader-entrypoint.mjs`, so automatic startup migrations do not run there.
+
+- Run `pnpm migrate` in a controlled environment to apply Drizzle schema migrations to your Postgres DB.
+- Run `pnpm migrate-fs` only when migrating legacy local filesystem data (`docstore/documents_v1`, `docstore/audiobooks_v1`) into object storage + DB rows. Fresh Vercel deployments usually do not need this.
+
+## 5. FFmpeg packaging in Vercel functions
+
+`ffmpeg-static` binaries must be included in function traces. This repo already does that in `next.config.ts` via `outputFileTracingIncludes` for:
+
+- `/api/audiobook`
+- `/api/audiobook/chapter`
+- `/api/tts/segments/ensure`
+
+:::info
+`serverExternalPackages` should include `ffmpeg-static` so package paths resolve at runtime instead of being bundled into route output.
+:::
+
+If you change route paths or split handlers, update `outputFileTracingIncludes` accordingly.
+
+## 6. Function memory sizing
+
+FFmpeg workloads benefit from more memory/CPU. This repo includes:
+
+```json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "functions": {
+    "app/api/audiobook/route.ts": { "memory": 3009 },
+    "app/api/tts/segments/ensure/route.ts": { "memory": 3009 }
+  }
+}
+```
+
+Adjust memory per route if your files are larger or your plan differs.
+
+## 7. Runtime expectations and caveats
+
+- Audiobook APIs require S3 configuration; otherwise they return `503`.
+- For production Vercel deploys, use `POSTGRES_URL` instead of SQLite.
+
+## 8. Smoke test after deploy
+
+1. Upload and read a PDF/EPUB document.
+2. Confirm sync/blob fetch works across refreshes/devices.
+3. Generate at least one audiobook chapter and play/download it.
+4. Verify worker-backed word highlighting and PDF parsing.

docs-site/versioned_docs/version-v4.0.0/docker-quick-start.md

@@ -0,0 +1,164 @@
+---
+title: Docker Quick Start
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Prerequisites
+
+- A recent Docker version installed
+- A TTS API server that OpenReader can reach:
+  - [Kokoro-FastAPI](./configure/tts-provider-guides/kokoro-fastapi)
+  - [KittenTTS-FastAPI](./configure/tts-provider-guides/kitten-tts-fastapi)
+  - [Orpheus-FastAPI](./configure/tts-provider-guides/orpheus-fastapi)
+  - [Replicate](./configure/tts-provider-guides/replicate)
+  - [DeepInfra](./configure/tts-provider-guides/deepinfra)
+  - [OpenAI](./configure/tts-provider-guides/openai)
+  - [Other OpenAI-compatible providers](./configure/tts-provider-guides/other)
+
+:::warning SeaweedFS Compatibility Note (April 16, 2026)
+OpenReader currently pins embedded SeaweedFS to `4.18` in CI and Docker builds.
+`4.19` introduced intermittent `InternalError` responses on S3 `PutObject` in our upload flow.
+:::
+
+## Published images
+
+- App server: `ghcr.io/richardr1126/openreader:latest`
+- Compute worker (Optional): `ghcr.io/richardr1126/openreader-compute-worker:latest`
+- Legacy app alias: `ghcr.io/richardr1126/openreader-webui:latest`
+
+## 1. Start the Docker container
+
+<Tabs groupId="docker-start-mode">
+<TabItem value="localhost" label="Localhost" default>
+
+Persistent storage, embedded SeaweedFS `weed mini`, required auth, optional library mount:
+
+```bash
+docker run --name openreader \
+  --restart unless-stopped \
+  -p 3003:3003 \
+  -p 8333:8333 \
+  -v openreader_docstore:/app/docstore \
+  -e API_BASE=http://host.docker.internal:8880/v1 \
+  -e API_KEY=none \
+  -e BASE_URL=http://localhost:3003 \
+  -e AUTH_SECRET=$(openssl rand -hex 32) \
+  -e ADMIN_EMAILS=you@example.com \
+  ghcr.io/richardr1126/openreader:latest
+```
+
+What this command enables:
+
+- `-p 3003:3003`: exposes the OpenReader web app/API.
+- `-p 8333:8333`: exposes embedded SeaweedFS S3 endpoint for direct browser presigned upload/download.
+- `-v openreader_docstore:/app/docstore`: persists SQLite metadata, SeaweedFS blob data, and migration/runtime state.
+- `-e API_BASE=...` / `-e API_KEY=...`: **first-boot seed only.** On the first container start, these are auto-migrated into a `default-openai` admin shared provider stored in the DB (key encrypted at rest). After that, the running app no longer reads them — manage the provider from **Settings → Admin → Shared providers**. See [Admin Panel](./configure/admin-panel).
+- `-e BASE_URL=...` and `-e AUTH_SECRET=...`: required for v4+ auth/session startup.
+- `-e ADMIN_EMAILS=...`: (optional, requires auth) comma-separated emails auto-promoted to admin. Admins see the **Admin** tab in Settings.
+
+</TabItem>
+<TabItem value="local-network" label="LAN Host">
+
+Use this when the app should be reachable from other devices on your LAN:
+
+```bash
+docker run --name openreader \
+  --restart unless-stopped \
+  -p 3003:3003 \
+  -p 8333:8333 \
+  -v openreader_docstore:/app/docstore \
+  -e API_BASE=http://host.docker.internal:8880/v1 \
+  -e BASE_URL=http://<YOUR_LAN_IP>:3003 \
+  -e AUTH_SECRET=$(openssl rand -hex 32) \
+  -e AUTH_TRUSTED_ORIGINS=http://localhost:3003,http://127.0.0.1:3003 \
+  -e USE_ANONYMOUS_AUTH_SESSIONS=true \
+  -e ADMIN_EMAILS=you@example.com \
+  ghcr.io/richardr1126/openreader:latest
+```
+
+Replace `YOUR_LAN_IP` with the Docker host IP address on your local network to allow access from other devices.
+
+What this command enables:
+
+- LAN access from phones/tablets/other computers via `http://<YOUR_LAN_IP>:3003`.
+- `BASE_URL` points auth/session cookies and callbacks at your LAN URL.
+- `AUTH_TRUSTED_ORIGINS` allows localhost loopback origins in addition to your primary LAN origin.
+- `USE_ANONYMOUS_AUTH_SESSIONS=true` allows guest sessions while auth is enabled.
+- `API_BASE` seeds the default TTS endpoint into the admin-managed `default-openai` shared provider on first boot. Edit it from **Settings → Admin → Shared providers** after that.
+- `ADMIN_EMAILS=...` (optional) auto-promotes the listed email(s) to admin so they can manage shared providers and site feature flags from the UI.
+- `openreader_docstore` volume keeps data persistent across restarts.
+
+</TabItem>
+<TabItem value="minimal" label="Minimal">
+
+Auth required, embedded storage ephemeral, no library import:
+
+```bash
+docker run --name openreader \
+  --restart unless-stopped \
+  -p 3003:3003 \
+  -p 8333:8333 \
+  -e BASE_URL=http://localhost:3003 \
+  -e AUTH_SECRET=$(openssl rand -hex 32) \
+  ghcr.io/richardr1126/openreader:latest
+```
+
+What this command enables:
+
+- Fast startup with only the required auth env vars.
+- No persistent volume (`/app/docstore` stays container-local), so data is ephemeral unless you add a mount.
+- The app still requires `BASE_URL` + `AUTH_SECRET` in v4+, so include them even in minimal mode.
+- No TTS provider preset by default. Configure `API_BASE`/`API_KEY` on first boot if you want a seeded shared provider, or run auth+admin mode and manage providers from the admin panel.
+
+</TabItem>
+</Tabs>
+
+:::tip Quick Tips
+- Set `API_BASE` on first boot to a TTS endpoint the container can reach (`host.docker.internal` works for host-local services). After first boot, manage providers in **Settings → Admin → Shared providers**.
+- `BASE_URL` and `AUTH_SECRET` are required in v4+. The admin panel requires auth.
+- Set `ADMIN_EMAILS` to your email if you want the **Admin** tab in Settings.
+- `restrictUserApiKeys` controls shared-provider-only mode. For per-user BYOK, toggle it off in **Settings → Admin → Site features** or seed `runtimeConfig.restrictUserApiKeys=false` via runtime seed JSON.
+- Use a `/app/docstore` mount if you want data to survive container/image replacement.
+- Startup automatically runs DB/storage migrations via the shared entrypoint.
+:::
+
+:::warning Port `8333` Exposure
+Expose `8333` for direct browser presigned upload/download with embedded SeaweedFS.
+
+If `8333` is not reachable from the browser, direct presigned access is unavailable. Uploads can still fall back to `/api/documents/blob/upload/fallback`, and document reads/downloads continue through `/api/documents/blob`.
+:::
+
+## 2. Configure settings in the app UI
+
+Visit [http://localhost:3003](http://localhost:3003) after startup.
+
+- If you set `ADMIN_EMAILS`, sign in with that email and open **Settings → Admin** to manage shared TTS providers and site feature flags for all users.
+- Per-user: set TTS provider/model in **Settings → TTS Provider**. API key/base URL inputs are shown only when `restrictUserApiKeys=false`.
+- Select the model voice from the voice dropdown.
+
+## 3. Update Docker image
+
+Legacy image compatibility: `ghcr.io/richardr1126/openreader-webui:latest` remains available as an alias.
+For external compute mode image details, see [Compute Worker (NATS JetStream)](./deploy/compute-worker).
+
+```bash
+docker stop openreader || true && \
+docker rm openreader || true && \
+docker image rm ghcr.io/richardr1126/openreader:latest || true && \
+docker pull ghcr.io/richardr1126/openreader:latest
+```
+
+:::tip
+If you use a mounted volume for `/app/docstore`, your persisted data remains after image updates.
+:::
+
+:::info Related Docs
+- [Environment Variables](./reference/environment-variables)
+- [Auth](./configure/auth)
+- [Admin Panel](./configure/admin-panel)
+- [Database](./configure/database)
+- [Object / Blob Storage](./configure/object-blob-storage)
+- [Migrations](./configure/migrations)
+:::

docs-site/versioned_docs/version-v4.0.0/introduction.md

@@ -0,0 +1,44 @@
+---
+id: intro
+title: Introduction
+slug: /
+---
+
+OpenReader is an open source text-to-speech document reader built with Next.js. It provides a read-along experience with narration for **EPUB, PDF, TXT, MD, and DOCX documents**.
+
+> Previously named **OpenReader-WebUI**.
+
+It supports multiple TTS providers including OpenAI, Replicate, DeepInfra, and custom OpenAI-compatible endpoints such as [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI), [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI), and [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI).
+
+## ✨ Highlights
+
+- 🧱 **Layout-aware PDF Parsing**
+  - PP-DocLayoutV3 (ONNX) detects structured blocks with cross-page stitching and geometry-based highlighting for precise read-along sync and clean TTS segmentation
+- ⏱️ **Word-by-word Highlighting** via ONNX Whisper alignment
+  - Powered by the external compute worker control plane (NATS JetStream-backed)
+- ⚡ **Segment-based TTS Playback**
+  - Sentence-aware generation with cached audio segments, background preloading, and resumable playback across EPUB, PDF, TXT, MD, and DOCX
+- 🎯 **Multi-Provider TTS Support**
+  - Self-hosted: [**Kokoro-FastAPI**](https://github.com/remsky/Kokoro-FastAPI) (multi-voice combinations), [**KittenTTS-FastAPI**](https://github.com/richardr1126/KittenTTS-FastAPI), [**Orpheus-FastAPI**](https://github.com/Lex-au/Orpheus-FastAPI), or any custom OpenAI-compatible endpoint
+  - Cloud: [**OpenAI**](https://platform.openai.com/docs/pricing#transcription-and-speech) (`tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`), [**Replicate**](https://replicate.com/explore) (built-in catalog + any model ID), [**DeepInfra**](https://deepinfra.com/models/text-to-speech) (Kokoro-82M and others)
+- 🎧 **Audiobook Export** in `m4b`/`mp3` with resumable chapter generation
+- 🗂️ **Flexible Backend** — embedded SeaweedFS or S3-compatible storage, SQLite or Postgres, server library import, and device sync
+- 🔐 **Auth and User Isolation** — auth is required in v4+, with optional anonymous auth sessions for guest flows
+- 🎨 **Customizable** — 13 built-in themes (light and dark palettes), per-user TTS settings, and document handling controls
+
+## 🧭 Key Docs
+
+- [Docker Quick Start](./docker-quick-start)
+- [Local Development](./deploy/local-development)
+- [Vercel Deployment](./deploy/vercel-deployment)
+- [Environment Variables](./reference/environment-variables)
+- [Auth](./configure/auth)
+- [Database](./configure/database)
+- [Object / Blob Storage](./configure/object-blob-storage)
+- [Migrations](./configure/migrations)
+- [Server Library Import](./configure/server-library-import)
+- [TTS Providers](./configure/tts-providers)
+
+## Source Repository
+
+- GitHub: [richardr1126/openreader](https://github.com/richardr1126/openreader)

docs-site/versioned_docs/version-v4.0.0/reference/environment-variables.md

@@ -0,0 +1,466 @@
+---
+title: Environment Variables
+toc_max_heading_level: 3
+---
+
+This page is the source-of-truth reference for OpenReader environment variables.
+
+:::note Recommended configuration path
+Use **Settings → Admin** as the primary source of truth for shared providers and runtime site features.
+`API_BASE` / `API_KEY` are optional one-time provider bootstrap seeds.
+Runtime site features are seeded with `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH`.
+:::
+
+## Quick Reference Table
+
+| Variable | Area | Default | When to set |
+| --- | --- | --- | --- |
+| `LOG_FORMAT` | Runtime logging | `pretty` | Set `json` for structured logs |
+| `LOG_LEVEL` | Runtime logging | `info` | Set app server log level |
+| `API_BASE` | TTS provider bootstrap seed | unset | Optional first-boot base URL for `default-openai` |
+| `API_KEY` | TTS provider bootstrap seed | unset | Optional first-boot API key for `default-openai` |
+| `BASE_URL` | Auth | unset | Required at startup |
+| `AUTH_SECRET` | Auth | unset | Required at startup |
+| `AUTH_TRUSTED_ORIGINS` | Auth | empty | Add extra allowed origins |
+| `USE_ANONYMOUS_AUTH_SESSIONS` | Auth | `false` | Set `true` to allow anonymous auth sessions |
+| `GITHUB_CLIENT_ID` | Auth/OAuth | unset | Set with `GITHUB_CLIENT_SECRET` to enable GitHub sign-in |
+| `GITHUB_CLIENT_SECRET` | Auth/OAuth | unset | Set with `GITHUB_CLIENT_ID` to enable GitHub sign-in |
+| `ADMIN_EMAILS` | Admin | empty | Comma-separated emails auto-promoted to admin |
+| `POSTGRES_URL` | Database | unset (SQLite mode) | Set to switch metadata/auth DB to Postgres |
+| `USE_EMBEDDED_WEED_MINI` | Storage | `true` when unset | Set `false` to use external S3-compatible storage only |
+| `WEED_MINI_DIR` | Storage | `docstore/seaweedfs` | Override embedded SeaweedFS data directory |
+| `WEED_MINI_WAIT_SEC` | Storage | `20` | Tune SeaweedFS startup wait timeout |
+| `S3_ACCESS_KEY_ID` | Storage | auto-generated in embedded mode | Set explicitly for stable/external credentials |
+| `S3_SECRET_ACCESS_KEY` | Storage | auto-generated in embedded mode | Set explicitly for stable/external credentials |
+| `S3_BUCKET` | Storage | `openreader-documents` in embedded mode | Required for external S3-compatible storage |
+| `S3_REGION` | Storage | `us-east-1` in embedded mode | Required for external S3-compatible storage |
+| `S3_ENDPOINT` | Storage | derived in embedded mode | Set for S3-compatible providers (MinIO/SeaweedFS/R2/etc.) |
+| `S3_FORCE_PATH_STYLE` | Storage | `true` in embedded mode | Set per provider requirement |
+| `S3_PREFIX` | Storage | `openreader` | Customize object key prefix |
+| `IMPORT_LIBRARY_DIR` | Library import | `docstore/library` fallback | Set a single server library root |
+| `IMPORT_LIBRARY_DIRS` | Library import | unset | Set multiple roots (comma/colon/semicolon separated) |
+| `EMBEDDED_COMPUTE_WORKER_PORT` | Compute | `8081` | Override embedded worker bind port |
+| `EMBEDDED_NATS_PORT` | Compute | `4222` | Override embedded NATS client port |
+| `EMBEDDED_NATS_MONITOR_PORT` | Compute | `8222` | Override embedded NATS monitor port |
+| `EMBEDDED_NATS_STORE_DIR` | Compute | `docstore/nats/jetstream` | Override embedded JetStream storage directory |
+| `NATS_URL` | Compute | `nats://127.0.0.1:4222` in embedded startup | Override embedded startup or set standalone worker URL |
+| `COMPUTE_LOG_LEVEL` | Compute | `info` | Compute worker log level |
+| `COMPUTE_JOB_CONCURRENCY` | Compute | `1` | Shared compute concurrency cap |
+| `COMPUTE_WHISPER_TIMEOUT_MS` | Compute | `30000` | Whisper alignment timeout budget |
+| `COMPUTE_PDF_TIMEOUT_MS` | Compute | `300000` | PDF parse timeout budget |
+| `COMPUTE_OP_STALE_MS` | Compute | `max(30m, 4x max compute timeout)` | Shared stale window for compute op replacement |
+| `WHISPER_MODEL_BASE_URL` | Compute model source | onnx-community default | Override Whisper ONNX model base URL |
+| `PDF_LAYOUT_MODEL_BASE_URL` | Compute model source | PP-DocLayoutV3 default | Override PDF layout ONNX model base URL |
+| `COMPUTE_WORKER_URL` | External compute mode | unset | Set only for standalone external worker mode |
+| `COMPUTE_WORKER_TOKEN` | External compute mode | unset | Required for standalone external worker auth |
+| `FFMPEG_BIN` | Audio runtime | auto-detected (`ffmpeg-static`) | Override ffmpeg binary path |
+| `DISABLE_AUTH_RATE_LIMIT` | Auth request throttling | `false` | Set `true` to disable Better Auth request rate limiting |
+| `ENABLE_TEST_NAMESPACE` | Testing/CI | unset | Honor `x-openreader-test-namespace` header in production builds |
+| `RUN_DRIZZLE_MIGRATIONS` | DB migrations | `true` | Set `false` to skip startup Drizzle migrations |
+| `RUN_FS_MIGRATIONS` | Storage migrations | `true` | Set `false` to skip startup filesystem -> S3/DB migration pass |
+| `RUNTIME_SEED_JSON_PATH` | Runtime JSON seed | unset | Absolute path to first-boot JSON seed document |
+| `RUNTIME_SEED_JSON` | Runtime JSON seed | unset | Inline first-boot JSON seed document |
+
+## Runtime Logging
+
+### LOG_FORMAT
+
+Controls log output format for server-side Pino loggers.
+
+- Default: `pretty`
+- Allowed values: `pretty`, `json`
+- Applies to app server and compute worker
+
+### LOG_LEVEL
+
+App server log level.
+
+- Default: `info`
+
+## TTS Provider and Request Behavior
+
+### API_BASE
+
+Optional first-boot bootstrap base URL for the auto-created `default-openai` shared provider.
+
+- Example: `http://host.docker.internal:8880/v1`
+- Read only for provider bootstrap when shared providers are empty and `API_KEY` is set.
+- After bootstrap, provider configuration is DB-backed and managed in **Settings → Admin → Shared providers**.
+
+### API_KEY
+
+Optional first-boot bootstrap API key for the auto-created `default-openai` shared provider.
+
+- Read only for provider bootstrap when shared providers are empty.
+- Stored encrypted at rest after bootstrap.
+- After bootstrap, provider configuration is DB-backed and managed in **Settings → Admin → Shared providers**.
+
+### TTS Daily Rate Limiting (Runtime Settings)
+
+Managed as runtime config in **Settings → Admin → Site features**.
+
+- `disableTtsRateLimit` default: `true` (daily TTS limits disabled)
+- `ttsDailyLimitAnonymous` default: `50000`
+- `ttsDailyLimitAuthenticated` default: `500000`
+- `ttsIpDailyLimitAnonymous` default: `100000`
+- `ttsIpDailyLimitAuthenticated` default: `1000000`
+
+### TTS Upstream Settings (Runtime Settings)
+
+Managed as runtime config in **Settings → Admin → Site features → TTS upstream**.
+
+- `ttsUpstreamMaxRetries` default: `2`
+- `ttsUpstreamTimeoutMs` default: `285000`
+- `ttsCacheMaxSizeBytes` default: `268435456` (256 MB)
+- `ttsCacheTtlMs` default: `1800000` (30 minutes)
+
+There are no dedicated env vars for these runtime settings.
+
+## Auth and Identity
+
+### BASE_URL
+
+Required external base URL for this OpenReader instance.
+
+- Required at startup
+- Example: `http://localhost:3003` or `https://reader.example.com`
+
+### AUTH_SECRET
+
+Required secret key used by auth/session handling.
+
+- Required at startup
+- Generate with `openssl rand -hex 32`
+
+### AUTH_TRUSTED_ORIGINS
+
+Additional allowed origins for auth requests.
+
+- Comma-separated list
+- `BASE_URL` origin is trusted automatically
+
+### USE_ANONYMOUS_AUTH_SESSIONS
+
+Controls whether auth-enabled deployments can create/use anonymous sessions.
+
+- Default: `false`
+
+### GITHUB_CLIENT_ID
+
+GitHub OAuth client ID.
+
+- Set with `GITHUB_CLIENT_SECRET`
+
+### GITHUB_CLIENT_SECRET
+
+GitHub OAuth client secret.
+
+- Set with `GITHUB_CLIENT_ID`
+
+### ADMIN_EMAILS
+
+Comma-separated list of email addresses auto-promoted to admin.
+
+- Requires auth to be enabled
+- Admins can manage shared providers and runtime site features in-app
+
+## Database and Object Blob Storage
+
+### POSTGRES_URL
+
+Switches metadata/auth storage from SQLite to Postgres.
+
+- Unset: SQLite at `docstore/sqlite3.db`
+- Set: Postgres mode
+
+### USE_EMBEDDED_WEED_MINI
+
+Controls embedded SeaweedFS startup.
+
+- Default behavior: treated as enabled when unset
+- Set `false` to rely on external S3-compatible storage
+
+### WEED_MINI_DIR
+
+Data directory for embedded SeaweedFS (`weed mini`).
+
+- Default: `docstore/seaweedfs`
+
+### WEED_MINI_WAIT_SEC
+
+Max wait time for embedded SeaweedFS startup.
+
+- Default: `20`
+
+### S3_ACCESS_KEY_ID
+
+S3 access key.
+
+- Optional in embedded mode (auto-generated when unset)
+- Required for external S3 mode
+
+### S3_SECRET_ACCESS_KEY
+
+S3 secret key.
+
+- Optional in embedded mode (auto-generated when unset)
+- Required for external S3 mode
+
+### S3_BUCKET
+
+S3 bucket name.
+
+- Embedded default: `openreader-documents`
+- Required for external S3 mode
+
+### S3_REGION
+
+S3 region.
+
+- Embedded default: `us-east-1`
+- Required for external S3 mode
+
+### S3_ENDPOINT
+
+Custom endpoint for S3-compatible providers.
+
+- Optional for AWS
+- Typical for MinIO/SeaweedFS/R2
+
+### S3_FORCE_PATH_STYLE
+
+Force path-style S3 URLs.
+
+- Embedded default: `true`
+
+### S3_PREFIX
+
+Object key prefix.
+
+- Default: `openreader`
+
+## Library Import
+
+### IMPORT_LIBRARY_DIR
+
+Single library source directory.
+
+### IMPORT_LIBRARY_DIRS
+
+Multiple library roots.
+
+- Supports comma, colon, or semicolon-separated values
+
+## Compute Worker and Model Configuration
+
+### EMBEDDED_COMPUTE_WORKER_PORT
+
+Embedded compute worker port.
+
+- Default: `8081`
+
+### EMBEDDED_NATS_PORT
+
+Embedded NATS client port.
+
+- Default: `4222`
+
+### EMBEDDED_NATS_MONITOR_PORT
+
+Embedded NATS monitor port.
+
+- Default: `8222`
+
+### EMBEDDED_NATS_STORE_DIR
+
+Embedded NATS JetStream data directory.
+
+- Default: `docstore/nats/jetstream`
+
+### NATS_URL
+
+NATS URL used by compute services.
+
+- Embedded startup default: `nats://127.0.0.1:4222`
+
+### COMPUTE_LOG_LEVEL
+
+Compute worker log level.
+
+- Default: `info`
+
+### COMPUTE_JOB_CONCURRENCY
+
+Max concurrent compute jobs per worker.
+
+- Default: `1`
+
+### COMPUTE_WHISPER_TIMEOUT_MS
+
+Whisper alignment timeout budget.
+
+- Default: `30000`
+
+### COMPUTE_PDF_TIMEOUT_MS
+
+PDF parse timeout budget.
+
+- Default: `300000`
+
+### COMPUTE_OP_STALE_MS
+
+Stale operation window before worker/app cleanup logic can replace an op.
+
+- Default: `max(30m, 4x max compute timeout)`
+
+### WHISPER_MODEL_BASE_URL
+
+Base URL for Whisper ONNX model downloads.
+
+### PDF_LAYOUT_MODEL_BASE_URL
+
+Base URL for PDF layout model downloads.
+
+### COMPUTE_WORKER_URL
+
+External compute worker URL.
+
+- Leave unset for embedded worker mode
+
+### COMPUTE_WORKER_TOKEN
+
+Shared token for app-to-external-worker requests.
+
+## Compute PDF Parsing Rate Limiting (Runtime Settings)
+
+Managed as runtime config in **Settings → Admin → Site features**.
+
+- `disableComputeRateLimit` default: `true`
+- `computeParseBurstMax` default: `8`
+- `computeParseBurstWindowSec` default: `60`
+- `computeParseSustainedMax` default: `24`
+- `computeParseSustainedWindowSec` default: `600`
+- `maxUploadMb` default: `200`
+
+There are no dedicated env vars for these runtime settings.
+
+## Audio Runtime
+
+### FFMPEG_BIN
+
+Override ffmpeg binary path used for audio processing.
+
+- Used by audiobook processing routes and compute worker Whisper audio decode.
+
+## Testing and CI
+
+### DISABLE_AUTH_RATE_LIMIT
+
+Disables Better Auth request rate limiting.
+
+- Default: `false`
+
+### ENABLE_TEST_NAMESPACE
+
+Enables the `x-openreader-test-namespace` header path in production builds.
+
+## Migration Controls
+
+### RUN_DRIZZLE_MIGRATIONS
+
+Controls startup Drizzle schema migrations.
+
+- Default: `true`
+- Set `false` to skip startup migration run
+
+### RUN_FS_MIGRATIONS
+
+Controls startup filesystem-to-S3/DB migration pass.
+
+- Default: `true`
+- Set `false` to skip startup storage migration run
+
+## Runtime JSON Seed (v4)
+
+### RUNTIME_SEED_JSON_PATH
+
+Path-based first-boot seed document.
+
+- If both `RUNTIME_SEED_JSON_PATH` and `RUNTIME_SEED_JSON` are set, path wins.
+- Value must point to a JSON file readable by the app process.
+
+### RUNTIME_SEED_JSON
+
+Inline first-boot seed document.
+
+- Used only when `RUNTIME_SEED_JSON_PATH` is unset.
+- Must be a JSON object with `version: 1`.
+
+Supported top-level keys:
+
+- `version` (required, must be `1`)
+- `runtimeConfig` (optional object, strict-validated against runtime schema)
+- `providers` (optional array of shared provider seed entries)
+
+Example:
+
+```json
+{
+  "version": 1,
+  "runtimeConfig": {
+    "enableUserSignups": true,
+    "restrictUserApiKeys": true,
+    "defaultTtsProvider": "custom-openai",
+    "enableTtsProvidersTab": true,
+    "enableAudiobookExport": true,
+    "enableDocxConversion": true,
+    "enableDestructiveDeleteActions": true,
+    "showAllProviderModels": true,
+    "disableTtsRateLimit": true,
+    "ttsDailyLimitAnonymous": 50000,
+    "ttsDailyLimitAuthenticated": 500000,
+    "ttsIpDailyLimitAnonymous": 100000,
+    "ttsIpDailyLimitAuthenticated": 1000000,
+    "ttsCacheMaxSizeBytes": 268435456,
+    "ttsCacheTtlMs": 1800000,
+    "ttsUpstreamMaxRetries": 2,
+    "ttsUpstreamTimeoutMs": 285000,
+    "disableComputeRateLimit": true,
+    "computeParseBurstMax": 8,
+    "computeParseBurstWindowSec": 60,
+    "computeParseSustainedMax": 24,
+    "computeParseSustainedWindowSec": 600,
+    "maxUploadMb": 200,
+    "changelogFeedUrl": "https://docs.openreader.richardr.dev/changelog/manifest.json"
+  },
+  "providers": [
+    {
+      "slug": "default-openai",
+      "displayName": "Default (seeded)",
+      "providerType": "custom-openai",
+      "baseUrl": "http://localhost:8880/v1",
+      "apiKey": "api_key_optional",
+      "defaultModel": "kokoro",
+      "enabled": true
+    }
+  ]
+}
+```
+
+Provider fallback behavior:
+
+- If the JSON seed includes `providers` (including an empty array), `API_BASE` / `API_KEY` fallback is skipped.
+- If the JSON seed does not include a `providers` key, the legacy `API_BASE` / `API_KEY` bootstrap fallback can still create `default-openai` when provider rows are empty.
+
+Precedence summary:
+
+- Runtime reads: admin DB runtime rows override built-in defaults.
+- Seed input (`RUNTIME_SEED_JSON*`) only populates missing runtime rows on first boot; it does not overwrite existing/admin-edited rows.
+- Provider bootstrap order: JSON `providers` section > `API_BASE`/`API_KEY` fallback > no provider bootstrap.
+
+## Related
+
+- [Admin Panel](../configure/admin-panel)
+- [TTS Providers](../configure/tts-providers)
+- [Local Development](../deploy/local-development)
+- [Vercel Deployment](../deploy/vercel-deployment)

docs-site/versioned_docs/version-v4.0.0/reference/stack.md

@@ -0,0 +1,70 @@
+---
+title: Stack
+---
+
+## Framework
+
+- [Next.js](https://nextjs.org/) 15 (App Router, Turbopack in dev)
+- [React](https://react.dev/) 19
+- [TypeScript](https://www.typescriptlang.org/)
+- [pnpm](https://pnpm.io/) workspaces monorepo
+
+## Containerization and runtime
+
+- [Docker](https://www.docker.com/) (linux/amd64 and linux/arm64)
+- Shared entrypoint that runs DB migrations by default and can bootstrap embedded SeaweedFS before app startup
+
+## Next.js client
+
+- UI: [Tailwind CSS](https://tailwindcss.com), [Headless UI](https://headlessui.com), [@tailwindcss/typography](https://tailwindcss.com/docs/typography-plugin)
+- Interactions: `react-dnd`, `react-dropzone`
+- Server state: [TanStack Query](https://tanstack.com/query) (React Query v5)
+- Authentication: [Better Auth](https://www.better-auth.com/) client SDK
+- Local storage/cache: [Dexie.js](https://dexie.org/) (IndexedDB)
+- Audio playback: [Howler.js](https://howlerjs.com/)
+- Notifications: `react-hot-toast`
+- Document rendering:
+  - PDF: [react-pdf](https://github.com/wojtekmaj/react-pdf), [pdf.js](https://mozilla.github.io/pdf.js/)
+  - EPUB: [react-reader](https://github.com/gerhardsletten/react-reader), [epubjs](https://github.com/futurepress/epub.js/)
+  - Markdown/Text: [react-markdown](https://github.com/remarkjs/react-markdown), [remark-gfm](https://github.com/remarkjs/remark-gfm)
+- Text preprocessing/matching: [compromise](https://github.com/spencermountain/compromise), [cmpstr](https://github.com/remsky/cmpstr)
+- Analytics: [Vercel Analytics](https://vercel.com/analytics)
+
+## Next.js server
+
+- APIs: Route Handlers for sync, blob/content access, migrations, audiobook export, TTS/Whisper proxying
+- State sync: request-based today (not realtime push updates)
+- Authentication: [Better Auth](https://www.better-auth.com/) server handlers/adapters with anonymous session support
+- Metadata DB: [Drizzle ORM](https://orm.drizzle.team/) with SQLite (`better-sqlite3`) by default and optional Postgres (`pg`)
+  - App tables are manually maintained in Drizzle schema files
+  - Auth tables are auto-generated by the [Better Auth](https://www.better-auth.com/) CLI and migrated alongside app tables via Drizzle
+- Blob storage: embedded [SeaweedFS](https://github.com/seaweedfs/seaweedfs) (`weed mini`) by default, or external S3-compatible storage via AWS SDK v3
+- TTS providers: OpenAI-compatible API (`openai` SDK), [Replicate](https://replicate.com/) (`replicate` client), DeepInfra, and custom OpenAI-compatible endpoints — credentials are encrypted at rest
+- Audio pipeline: [ffmpeg](https://ffmpeg.org/) (`ffmpeg-static`) for audiobook assembly, `archiver` for export packaging
+- Utilities: `lru-cache` for in-process caching, `fast-xml-parser` for EPUB/XML parsing, `uuid` for identifier generation, `zod` for schema validation
+
+## External compute worker (optional)
+
+Monorepo packages under `compute/`:
+
+- **`@openreader/compute-core`** — ONNX runtime lifecycle, model management, and inference logic shared by compute worker runtime + app/worker contracts
+  - ONNX runtime: `onnxruntime-node` with `@huggingface/tokenizers`
+  - Whisper alignment: `onnx-community/whisper-base_timestamped` (q4) for word-level timestamps
+  - PDF layout: `Bei0001/PP-DocLayoutV3-ONNX` for document block detection and layout parsing
+  - PDF rendering: `pdfjs-dist`, `@napi-rs/canvas` for server-side page rasterization
+  - Utilities: `jszip`, `ffmpeg-static`
+- **`@openreader/compute-worker`** — standalone Node.js worker service
+  - HTTP server: [Fastify](https://fastify.dev/) v5
+  - Job queue + state: [NATS](https://nats.io/) JetStream WorkQueue pull consumers + NATS KV (`jobs.whisper`, `jobs.layout`)
+  - Storage: AWS SDK v3 S3 client for reading/writing blobs
+  - Logging: [Pino](https://getpino.io/)
+  - Validation: [Zod](https://zod.dev/)
+- Heavy compute is worker-backed via `COMPUTE_WORKER_URL` + `COMPUTE_WORKER_TOKEN` (remote queue via HTTP + NATS)
+
+## Tooling and testing
+
+- ESLint
+- TypeScript
+- [Playwright](https://playwright.dev/) end-to-end tests
+- Drizzle migration/generation scripts
+- [Docusaurus](https://docusaurus.io/) documentation site (`docs-site/`)

docs-site/versioned_docs/version-v4.0.1/about/acknowledgements.md

@@ -0,0 +1,16 @@
+---
+title: Acknowledgements
+---
+
+This project is built with support from the following open-source projects and tools:
+
+- [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M)
+- [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI)
+- [Better Auth](https://www.better-auth.com/)
+- [SQLite](https://www.sqlite.org/)
+- [PostgreSQL](https://www.postgresql.org/)
+- [SeaweedFS](https://github.com/seaweedfs/seaweedfs)
+- [OpenAI Whisper](https://github.com/openai/whisper)
+- [ffmpeg](https://ffmpeg.org)
+- [react-pdf](https://github.com/wojtekmaj/react-pdf)
+- [react-reader](https://github.com/happyr/react-reader)

docs-site/versioned_docs/version-v4.0.1/about/license.md

@@ -0,0 +1,7 @@
+---
+title: License
+---
+
+OpenReader is licensed under the MIT License.
+
+- Repository license file: [LICENSE](https://github.com/richardr1126/openreader/blob/main/LICENSE)

docs-site/versioned_docs/version-v4.0.1/about/support-and-contributing.md

@@ -0,0 +1,19 @@
+---
+title: Support and Contributing
+---
+
+## Feature requests
+
+Use [GitHub Discussions](https://github.com/richardr1126/openreader/discussions) for feature requests and ideas.
+
+## Issues and support
+
+If you encounter a bug, open an issue in [GitHub Issues](https://github.com/richardr1126/openreader/issues).
+
+## Contributing
+
+Contributions are welcome.
+
+- Fork the repository
+- Create your branch
+- Open a pull request with your changes

docs-site/versioned_docs/version-v4.0.1/configure/admin-panel.md

@@ -0,0 +1,149 @@
+---
+title: Admin Panel
+---
+
+The admin panel lets a designated set of users manage **shared TTS providers** and **site-wide feature flags** directly from the Settings modal — without touching env vars or redeploying.
+
+It is gated behind authentication, so you must have auth enabled to use it ([Auth](./auth)).
+
+## Designating admins
+
+Set `ADMIN_EMAILS` to a comma-separated list of emails:
+
+```env
+AUTH_SECRET=...        # required for auth
+BASE_URL=...           # required for auth
+ADMIN_EMAILS=alice@example.com,bob@example.com
+```
+
+On every session resolution the server compares the user's email against this list and writes `user.is_admin = true` (or `false` for emails removed from the list). No restart is required to demote — the next page load picks it up.
+
+When the logged-in user is an admin, an **Admin** tab appears in **Settings → sidebar** with two sub-tabs:
+
+- **Shared providers** — server-side TTS provider instances visible to all users.
+- **Site features** — runtime-editable replacements for what were previously build-time public env flags.
+
+## Shared TTS providers
+
+Each shared provider is one named instance bound to one of the four built-in provider types (`custom-openai`, `openai`, `replicate`, `deepinfra`). The admin form has:
+
+| Field | Notes |
+| --- | --- |
+| **Slug** | URL-safe identifier exposed to users (e.g. `kokoro-prod`). Must not collide with a built-in id. Lowercase alphanumeric + hyphens. |
+| **Display name** | Shown in the user's provider dropdown, suffixed with "(shared)". |
+| **Provider type** | One of the four built-ins. Determines voice/model resolution. |
+| **Base URL** | Optional. Falls through to the provider type's default when blank. |
+| **API key** | Encrypted at rest with AES-256-GCM (key derived from `AUTH_SECRET` via scrypt). On edit, leave blank to keep the existing key. |
+| **Default model** | Optional. Used as the initial model when a user selects this provider. |
+| **Enabled** | Toggle to hide the provider from non-admin users without deleting it. |
+
+When a non-admin user picks a shared provider in **Settings → TTS Provider**:
+
+- The API key / base URL fields are hidden — those credentials never leave the server.
+- The TTS request still goes through the user's browser, but the server replaces the slug with the matching admin row's decrypted key and base URL before calling the upstream provider.
+- The user's per-request `x-openai-key` / `x-openai-base-url` headers are ignored for shared slugs.
+
+Whether users can supply their own personal built-in provider keys is controlled by the site feature `restrictUserApiKeys`:
+
+- `true`: users are restricted to shared providers only.
+- `false`: users may also use per-user BYOK credentials for built-in providers.
+
+### Auto-seeded "default-openai"
+
+On first boot, if `admin_providers` is empty and the legacy `API_KEY` env var is set, OpenReader creates a single shared provider with:
+
+- slug `default-openai`, displayName `Default (from env)`, providerType `custom-openai`
+- baseUrl from `API_BASE`, apiKey from `API_KEY` (encrypted)
+- defaultModel set to `kokoro` (you can edit it in Admin → Shared providers)
+
+After this seed runs, the legacy `API_KEY` / `API_BASE` env vars are no longer read by the TTS routes — the DB row is authoritative. You can rename, edit, disable, or delete this row like any other from the admin UI, and remove the env vars from your `.env` when convenient.
+
+:::warning Upgrading from v2.2.0
+In v2.2.0 and earlier, `API_KEY` / `API_BASE` were read live by the TTS routes on every request. As of v3.0.0 they are **one-shot seeds** consumed only on the first boot where `admin_providers` is empty. After upgrading, boot the app once and confirm a `default-openai` row exists in **Settings → Admin → Shared providers** with the correct base URL. If it is missing or wrong (e.g. the env vars were not set on first boot, or the table was already non-empty from a pre-release), create or edit the shared provider manually — TTS will not fall back to the env vars.
+:::
+
+## Site features
+
+Runtime-editable settings, one row per key:
+
+| Key | What it controls |
+| --- | --- |
+| `defaultTtsProvider` | Default provider id new users start with (built-in id or shared slug). |
+| `changelogFeedUrl` | Public changelog manifest URL used by the Settings modal changelog panel. |
+| `enableUserSignups` | Controls whether new accounts can be created. Existing accounts can still sign in when this is `false`. |
+| `restrictUserApiKeys` | Restrict user-supplied API keys/base URLs; when `true`, only admin shared providers are allowed. |
+| `enableTtsProvidersTab` | Whether the user-facing TTS Provider tab in Settings is shown. |
+| `showAllProviderModels` | When `false`, users are restricted to each provider's default model (shared provider `defaultModel` or built-in provider default). |
+| `enableAudiobookExport` | Show the audiobook export entry points on PDF/EPUB pages. |
+| `enableDocxConversion` | Accept .docx uploads (converted to PDF server-side). |
+| `enableDestructiveDeleteActions` | Show "Delete all data" buttons in the Documents tab (auth-disabled mode). |
+
+Word-by-word highlighting and PDF layout parsing capability are controlled by compute-worker server env configuration, not an admin runtime flag.
+
+Each row shows a source badge:
+
+- **from seed** — the value was seeded on first boot (from `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH`).
+- **admin** — explicit admin override. Use **Reset** on the row to clear it back to built-in default behavior.
+- **default** — no seed/admin row exists; built-in default is active.
+
+:::warning Security note for `restrictUserApiKeys`
+Turning `restrictUserApiKeys` off allows user-supplied API keys to flow through this server. Use this only for trusted/self-hosted deployments where that tradeoff is acceptable.
+:::
+
+## Rate limiting
+
+A dedicated **Rate limiting** group (within the same admin panel) collects the daily quotas, the PDF parsing throttle, and the upload size cap:
+
+| Key | What it controls |
+| --- | --- |
+| `disableTtsRateLimit` | Disable the per-user/IP daily TTS character limits. When `false`, the daily-limit fields below it apply. |
+| `disableComputeRateLimit` | Disable per-user PDF parsing rate limiting. When `false`, the burst/sustained limit fields below it apply. |
+| `maxUploadMb` | Maximum size (MB) accepted for a single document upload. Enforced server-side and signed into the presigned S3 PUT. |
+
+The **Disable TTS daily rate limiting** and **Disable PDF parsing rate limiting** toggles each reveal a collapsible group of numeric inputs when set to `false`:
+
+- TTS: anonymous/authenticated per-user daily limits and anonymous/authenticated IP daily backstops.
+- PDF parsing: burst limit + window (seconds) and sustained limit + window (seconds). The sustained window doubles as a concurrency cap.
+
+## TTS upstream
+
+At the end of the **Site features** tab, a dedicated **TTS upstream** group controls server-side request and cache tuning (DB-backed runtime settings, not env vars):
+
+| Key | What it controls |
+| --- | --- |
+| `ttsUpstreamMaxRetries` | Maximum retry attempts for upstream TTS 429/5xx responses. |
+| `ttsUpstreamTimeoutMs` | Upstream request timeout for OpenAI-compatible TTS calls. |
+| `ttsCacheMaxSizeBytes` | Maximum size of the in-memory TTS audio cache. |
+| `ttsCacheTtlMs` | Time-to-live for cached TTS audio buffers. |
+
+In v4 these settings are admin-only and are no longer configurable through environment variables.
+
+## Migrating off env vars
+
+In v4, runtime site features are managed by admin settings and optional JSON seed. To minimize env surface area:
+
+1. Deploy this version with your existing env values in place.
+2. Boot the app once. Open Settings → Admin and verify:
+   - Seeded settings appear as **from seed** (if you supplied a runtime JSON seed).
+   - A `default-openai` row exists in **Shared providers** (if you had `API_KEY` set).
+3. Remove any bootstrap env vars you no longer need from `.env`.
+4. Redeploy. Behavior is unchanged — the DB is now the source of truth.
+
+You can keep `API_BASE` / `API_KEY` if you intentionally want bootstrap fallback behavior on empty provider tables.
+
+## How keys are protected
+
+- API keys are encrypted in the `admin_providers` table with AES-256-GCM. The encryption key is derived from `AUTH_SECRET` via `scrypt`.
+- The masked-list view (`GET /api/admin/providers`, used by the admin UI itself) returns `••••` + last-4 only — never plaintext or ciphertext.
+- The public list endpoint (`GET /api/tts/shared-providers`, called by every user's browser) returns only `{ slug, displayName, providerType, defaultModel }`. Keys and base URLs are never exposed to the client.
+- Non-admin users cannot enumerate admin providers' credentials or base URLs through any API.
+
+:::danger Rotating `AUTH_SECRET` invalidates all stored admin provider keys
+Because the encryption key for `admin_providers` is derived from `AUTH_SECRET`, changing `AUTH_SECRET` makes every stored API key undecryptable. After rotating it, shared providers will fail to authenticate upstream until you re-enter each provider's API key in **Settings → Admin → Shared providers** (edit the row and paste the key again). There is no automated re-encryption path. If you must rotate `AUTH_SECRET`, plan to re-enter admin provider keys immediately afterward.
+:::
+
+## Related
+
+- [Auth](./auth) — required to use the admin panel.
+- [TTS Providers](./tts-providers) — built-in provider catalog and per-user behavior.
+- [Environment Variables](../reference/environment-variables) — `ADMIN_EMAILS`, provider bootstrap vars, and runtime JSON seed.

docs-site/versioned_docs/version-v4.0.1/configure/auth.md

@@ -0,0 +1,64 @@
+---
+title: Auth
+---
+
+This page covers application-level configuration for provider access and authentication.
+
+## Auth behavior
+
+- `BASE_URL` and `AUTH_SECRET` are required at startup in v4+.
+- Keep `AUTH_TRUSTED_ORIGINS` empty to trust only `BASE_URL`.
+- Anonymous auth sessions are disabled by default.
+- Set `USE_ANONYMOUS_AUTH_SESSIONS=true` to enable anonymous session flows.
+
+## Runtime modes
+
+OpenReader has two common runtime modes:
+
+- **Auth enabled, non-admin user**: user account/session features are available, but no admin controls.
+- **Auth enabled, admin user**: full **Settings → Admin** access (shared providers + site features).
+
+## Admin role
+
+You can designate one or more users as admins via the `ADMIN_EMAILS` env var:
+
+```env
+ADMIN_EMAILS=alice@example.com,bob@example.com
+```
+
+Admins see a new **Admin** tab in **Settings** with two sub-tabs:
+
+- **Shared TTS providers** — server-managed TTS provider instances with encrypted keys, visible to all users.
+- **Site features** — runtime overrides for what were previously build-time public env flags (including account signup availability, default TTS provider, audiobook export, etc.).
+
+Admin assignment is reconciled on every session resolution, so removing an email from `ADMIN_EMAILS` demotes the user on next login without a restart. See [Admin Panel](./admin-panel) for the full reference.
+
+## Route behavior
+
+- `/` is a public landing/onboarding page and remains indexable.
+- `/app` is the protected app home (document list and uploader UI).
+- If a valid session exists (including anonymous), visiting `/` redirects to `/app`.
+- Protected app routes continue to require auth; when anonymous sessions are disabled and no session exists, users are redirected to `/signin`.
+
+## Related docs
+
+- For auth environment variables: [Environment Variables](../reference/environment-variables#auth-and-identity)
+- For admin role and shared TTS provider config: [Admin Panel](./admin-panel)
+- For TTS character limits and quota behavior: [TTS Rate Limiting](./tts-rate-limiting)
+- For provider-specific guidance: [TTS Providers](./tts-providers)
+- For storage/S3/SeaweedFS behavior: [Object / Blob Storage](./object-blob-storage)
+- For database mode: [Database](./database)
+- For migration behavior and commands: [Migrations](./migrations)
+
+## Sync notes
+
+### Auth enabled
+
+- Settings and reading progress are saved to the server.
+- Updates are not instant push-based sync; they use normal client polling/refresh behavior.
+- If two devices change the same item around the same time, the newest update wins.
+
+## Claim modal note
+
+- You may still see old anonymous settings/progress available to claim from older deployments.
+- Legacy `unclaimed` data is only surfaced through the claim flow; normal authenticated routes are scoped to your current user id.

docs-site/versioned_docs/version-v4.0.1/configure/database.md

@@ -0,0 +1,58 @@
+---
+title: Database
+---
+
+This page covers database mode selection for OpenReader.
+
+## Scope of this page
+
+- Focus: SQL metadata, state, and relational tables.
+- Not covered here: object key layout and blob transport details (see [Object / Blob Storage](./object-blob-storage)).
+
+## Database mode
+
+- SQLite (default): embedded DB at `docstore/sqlite3.db`; good for local/self-host single-instance setups.
+- Postgres: enabled when `POSTGRES_URL` is set; recommended for production/distributed deployments.
+
+## What the database stores
+
+- Document and audiobook metadata/state used by server routes.
+- Auth/session tables (`user`, `session`, `account`, `verification`) when auth is enabled — schema is auto-generated by Better Auth.
+- TTS character usage counters (`user_tts_chars`) for daily rate limiting (when enabled).
+- User settings preferences (`user_preferences`) when auth is enabled.
+- User reading progress (`user_document_progress`) when auth is enabled.
+- Document preview job/asset metadata (`document_previews`) for server-side PDF/EPUB thumbnails.
+- TTS segment metadata (`tts_segments`) for server-side playback caching:
+  - Segment identity + settings hash
+  - Audio object key and duration
+  - Optional alignment payload for word highlighting
+  - Status/error state
+  - Text fingerprint/hash (plaintext segment text is not stored)
+
+App-specific tables are manually maintained in Drizzle schema files, while auth tables are generated by the Better Auth CLI. Both are migrated together via Drizzle. See [Migrations](./migrations) for details.
+
+## What the database does not store
+
+- Raw document file bytes
+- Audiobook audio bytes
+- TTS segment audio bytes
+- Generated preview image bytes
+
+Those payloads live in object storage. SQL stores the metadata, references, and status.
+
+## Related variables
+
+- `POSTGRES_URL`
+
+For database variable behavior, see [Environment Variables](../reference/environment-variables#database-and-object-blob-storage).
+
+## Related docs
+
+- [Migrations](./migrations)
+- [Object / Blob Storage](./object-blob-storage)
+- [Auth](./auth)
+
+## State sync summary
+
+- Settings and reading progress are stored in SQL and synced from the app.
+- Sync is currently request-based (not realtime push invalidation).

docs-site/versioned_docs/version-v4.0.1/configure/migrations.md

@@ -0,0 +1,150 @@
+---
+title: Migrations
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This page covers migration behavior for both database schema and storage data in OpenReader.
+
+## Startup migration behavior
+
+By default, the shared entrypoint runs migrations automatically before app startup in:
+
+- Docker container startup
+- `pnpm dev`
+- `pnpm start`
+
+Startup migration phases:
+
+- DB schema migrations (`pnpm migrate`)
+- Storage/data migration (`pnpm migrate-fs`) for legacy filesystem content into S3 + DB rows
+
+:::info
+In most setups, you do not need to run migration commands manually because startup handles this automatically.
+:::
+
+### Schema history
+
+Migrations are applied in order. All of the following ship in v3.0.0; an instance upgrading from v2.2.0 applies `0001`–`0004` in a single startup pass.
+
+| Migration | Dialects | What it does |
+| --- | --- | --- |
+| `0001_tts_segments` | SQLite + Postgres | Creates the original single-table `tts_segments` used by server-side TTS segment caching. |
+| `0002_add_segment_key_to_tts_segments` | SQLite + Postgres | Adds the `segment_key` column to `tts_segments` for stable locator-independent segment identity. |
+| `0003_tts_segments_v2_split` | SQLite + Postgres | Replaces `tts_segments` with a normalized two-table model: `tts_segment_entries` (one row per document segment + locator identity) and `tts_segment_variants` (one row per settings combination, holding the cached audio key, status, and alignment). Drops the original `tts_segments` table — no released build (v2.2.0 or earlier) ever populated it, so there is no production data to migrate. |
+| `0004_admin_panel` | SQLite + Postgres | Creates `admin_providers` (encrypted shared TTS provider rows) and `admin_settings` (runtime site-feature config), and adds the `is_admin` column to the `user` table. Backs the [Admin Panel](./admin-panel). |
+
+To skip automatic startup migrations:
+
+- Set `RUN_DRIZZLE_MIGRATIONS=false`
+- Set `RUN_FS_MIGRATIONS=false`
+
+:::warning
+If you disable startup migrations, ensure your deployment process runs migrations before serving traffic.
+:::
+
+## Apply migrations
+
+In most cases, you do not need manual migration commands because startup runs migrations automatically.
+
+`pnpm migrate` applies migrations for one database target:
+
+- Postgres when `POSTGRES_URL` is set
+- SQLite when `POSTGRES_URL` is unset
+
+You can always override the target explicitly with `--config`.
+
+<Tabs groupId="apply-migration-commands">
+  <TabItem value="project-scripts" label="Project Scripts" default>
+
+```bash
+# Run pending migrations for one target:
+# - Postgres if POSTGRES_URL is set
+# - SQLite if POSTGRES_URL is unset
+pnpm migrate
+
+# Run storage migration (filesystem -> S3 + DB)
+pnpm migrate-fs
+
+# Dry-run storage migration without uploading/deleting
+pnpm migrate-fs:dry-run
+```
+
+  </TabItem>
+  <TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
+
+```bash
+# Migrate SQLite
+pnpm exec drizzle-kit migrate --config drizzle.config.sqlite.ts
+
+# Migrate Postgres
+pnpm exec drizzle-kit migrate --config drizzle.config.pg.ts
+```
+
+  </TabItem>
+</Tabs>
+
+## Generate migrations
+
+`pnpm generate` is a two-phase script for contributors and schema changes:
+
+1. **Better Auth schema generation** — runs the Better Auth CLI twice (once for SQLite, once for Postgres) to produce auto-generated Drizzle schema files for auth tables (`user`, `session`, `account`, `verification`).
+2. **Drizzle migration generation** — runs `drizzle-kit generate` for both `drizzle.config.sqlite.ts` and `drizzle.config.pg.ts`, producing SQL migration files from all schema files (app + auth).
+
+:::note
+Most users do not need to run `pnpm generate`. Use it when contributing or when you have changed Drizzle schema files and need new migration files.
+:::
+
+### Schema ownership
+
+Auth tables are owned by Better Auth. Their Drizzle schema definitions are auto-generated and should **not** be hand-edited:
+
+- `src/db/schema_auth_sqlite.ts`
+- `src/db/schema_auth_postgres.ts`
+
+App-specific tables are manually maintained in the standard Drizzle schema files:
+
+- `src/db/schema_sqlite.ts`
+- `src/db/schema_postgres.ts`
+
+Both sets of schema files are included in the Drizzle configs, so `drizzle-kit generate` and `drizzle-kit migrate` handle all tables together.
+
+When app schema changes (for example `tts_segments`), keep these in sync:
+
+- `src/db/schema_sqlite.ts`
+- `src/db/schema_postgres.ts`
+- `drizzle/sqlite/*.sql` + `drizzle/sqlite/meta/_journal.json`
+- `drizzle/postgres/*.sql` + `drizzle/postgres/meta/_journal.json`
+
+<Tabs groupId="generate-migration-commands">
+  <TabItem value="project-script" label="Project Script" default>
+
+```bash
+# Full pipeline: Better Auth CLI + Drizzle generate (both dialects)
+pnpm generate
+```
+
+  </TabItem>
+  <TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
+
+```bash
+# Generate SQLite migrations only (skips Better Auth CLI)
+pnpm exec drizzle-kit generate --config drizzle.config.sqlite.ts
+
+# Generate Postgres migrations only (skips Better Auth CLI)
+pnpm exec drizzle-kit generate --config drizzle.config.pg.ts
+```
+
+:::warning
+Running `drizzle-kit generate` directly skips the Better Auth CLI step. If auth schema has changed upstream (e.g. after a Better Auth version bump), run `pnpm generate` instead to regenerate the auth schema files first.
+:::
+
+  </TabItem>
+</Tabs>
+
+## Related docs
+
+- [Database](./database)
+- [Object / Blob Storage](./object-blob-storage)
+- [Migration Environment Variables](../reference/environment-variables#migration-controls)

docs-site/versioned_docs/version-v4.0.1/configure/object-blob-storage.md

@@ -0,0 +1,167 @@
+---
+title: Object / Blob Storage
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This page documents storage backends, blob upload routing, and core Docker mount behavior.
+
+## Scope of this page
+
+- Focus: object/blob backends, keyspaces, upload/read paths, and storage debugging.
+- Not covered here: relational metadata tables and SQL state modeling (see [Database](./database)).
+
+## Storage backends
+
+- Embedded (default): embedded SeaweedFS (`weed mini`) blob storage.
+- External: external S3-compatible object storage.
+
+Metadata database mode (SQLite vs Postgres) is configured separately in [Database](./database).
+
+:::warning SeaweedFS Compatibility Note (April 16, 2026)
+OpenReader currently pins embedded SeaweedFS to `4.18` in CI and Docker builds.
+`4.19` introduced intermittent `InternalError` responses on S3 `PutObject` in our upload flow.
+:::
+
+Storage variables are documented in [Environment Variables](../reference/environment-variables#database-and-object-blob-storage).
+
+## Ports
+
+- `3003`: OpenReader app and API routes
+- `8333`: Embedded SeaweedFS S3 endpoint for direct browser blob access
+
+:::info
+`8333` is only needed for direct browser presigned access to embedded SeaweedFS.
+:::
+
+## Upload behavior
+
+- Primary path: browser uploads to presigned URL from `/api/documents/blob/upload/presign`.
+- Fallback path: `/api/documents/blob/upload/fallback` when direct upload fails/unreachable.
+- Read/download path: blob/content serving route `/api/documents/blob` (not the upload fallback route).
+- Preview path: `/api/documents/blob/preview` (returns `202` while a preview is generating; serves/redirects when ready).
+
+## Document previews
+
+- PDF/EPUB previews are generated server-side and stored in object storage under `document_previews_v1`.
+- Preview generation is triggered on upload registration and also backfills on first preview request for older docs.
+- Preview artifacts are temporary-cache friendly and can be regenerated from the source document blob.
+
+## FS / Volume Mounts
+
+### App data mount
+
+- Target: `/app/docstore`
+- Recommended: yes, for persistence
+- Purpose: persists SeaweedFS blob data, SQLite metadata DB, migrations, and local runtime temp state
+- Mount string: `-v openreader_docstore:/app/docstore`
+
+### Library source mount (optional)
+
+- Target: `/app/docstore/library`
+- Recommended: optional, use read-only (`:ro`)
+- Purpose: exposes host files as a source for server library import
+- Mount string: `-v /path/to/your/library:/app/docstore/library:ro`
+- Details: [Server Library Import](./server-library-import)
+
+## Private blob endpoint mode
+
+If `8333` is not published externally:
+
+- Document uploads still work through upload fallback proxy
+- Reads/snippets continue through app API routes
+- Direct presigned browser upload/download to embedded endpoint is unavailable
+
+:::warning
+Without `8333`, expect higher app-server traffic because uploads/downloads go through API routes instead of direct object endpoint access.
+:::
+
+## Audiobook Storage Debug Commands
+
+Audiobook assets are stored in object storage under the `audiobooks_v1` keyspace. Use these commands to inspect and download objects for debugging.
+
+<Tabs groupId="audiobook-storage-access-cli">
+  <TabItem value="aws-s3" label="AWS S3" default>
+
+```bash
+# List all audiobook objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive
+
+# Filter to one book id (replace <book-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive | grep "<book-id>-audiobook/"
+
+# Download one object by full key
+aws s3 cp "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/<path>/<file>.m4b" "./audiobook.m4b"
+```
+
+  </TabItem>
+  <TabItem value="s3-compatible" label="Embedded / MinIO / R2 / etc">
+
+```bash
+# List all audiobook objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive --endpoint-url "$S3_ENDPOINT"
+
+# Filter to one book id (replace <book-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive --endpoint-url "$S3_ENDPOINT" | grep "<book-id>-audiobook/"
+
+# Download one object by full key
+aws s3 cp "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/<path>/<file>.m4b" "./audiobook.m4b" --endpoint-url "$S3_ENDPOINT"
+```
+
+Embedded default example: `S3_ENDPOINT=http://127.0.0.1:8333` (or your mapped host/port).
+
+  </TabItem>
+</Tabs>
+
+## TTS Segment Storage
+
+Server-side TTS segment audio is stored in object storage under the `tts_segments_v1` keyspace.
+
+Typical key layout:
+
+- `${S3_PREFIX}/tts_segments_v1/users/<url-encoded-user-id>/docs/<document-id>/<document-version>/<settings-hash>/<segment-id>.mp3`
+- `${S3_PREFIX}/tts_segments_v1/ns/<test-namespace>/users/<url-encoded-user-id>/docs/...` (test namespace mode)
+
+Notes:
+
+- For the corresponding SQL metadata model (`tts_segments`), see [Database](./database).
+
+## Account Deletion Cleanup
+
+Account deletion performs best-effort object cleanup:
+
+- Document blobs + preview artifacts
+- Audiobook blobs
+- TTS segment blobs under `tts_segments_v1`
+
+If object deletion fails, account deletion still proceeds and orphaned objects may require manual cleanup.
+
+## TTS Segment Storage Debug Commands
+
+Use these commands to inspect segment objects.
+
+<Tabs groupId="tts-segment-storage-access-cli">
+  <TabItem value="aws-s3" label="AWS S3" default>
+
+```bash
+# List all TTS segment objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive
+
+# Filter to one document id (replace <document-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive | grep "/docs/<document-id>/"
+```
+
+  </TabItem>
+  <TabItem value="s3-compatible" label="Embedded / MinIO / R2 / etc">
+
+```bash
+# List all TTS segment objects
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive --endpoint-url "$S3_ENDPOINT"
+
+# Filter to one document id (replace <document-id>)
+aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive --endpoint-url "$S3_ENDPOINT" | grep "/docs/<document-id>/"
+```
+
+  </TabItem>
+</Tabs>

docs-site/versioned_docs/version-v4.0.1/configure/server-library-import.md

@@ -0,0 +1,68 @@
+---
+title: Server Library Import
+---
+
+This page documents how server library import works and how to configure it.
+
+## What it does
+
+Server library import lets you browse files from one or more server directories and import selected files into OpenReader.
+
+- Import is user-driven via a selection modal
+- Only selected files are imported
+- Imported files become normal OpenReader documents
+
+## FS / Volume Mounts
+
+### App data mount
+
+- Target: `/app/docstore`
+- Recommended: yes, for persistence
+- Purpose: stores app runtime data, metadata DB, and embedded storage state
+- Mount string: `-v openreader_docstore:/app/docstore`
+
+### Library source mount
+
+- Target: `/app/docstore/library`
+- Recommended: yes for this feature, use read-only (`:ro`)
+- Purpose: exposes host files as import candidates in Server Library Import
+- Mount string: `-v /path/to/your/library:/app/docstore/library:ro`
+
+## Import flow
+
+1. Open **Settings -> Documents -> Server Library Import**.
+2. Select files in the modal.
+3. Click **Import**.
+
+Selected files are fetched from the server library endpoint and imported into OpenReader storage.
+
+:::warning Shared Library Roots
+Library roots are configured at the server level (not per-user). Any user who can access Server Library Import can browse/import from the same configured roots.
+
+Imported documents are still saved to the importing user's document scope.
+:::
+
+## Supported file types
+
+- `.pdf`
+- `.epub`
+- `.html`, `.htm`
+- `.txt`
+- `.md`, `.mdown`, `.markdown`
+
+## Optional: Configure Library Roots
+
+You only need this when the default mounted path is not what you want.
+
+By default, OpenReader uses `docstore/library` as the import root. You can override that with environment variables:
+
+- `IMPORT_LIBRARY_DIRS` (takes precedence): multiple roots separated by comma, colon, or semicolon
+- `IMPORT_LIBRARY_DIR`: single root
+
+See [Environment Variables](../reference/environment-variables#library-import) for variable details.
+
+## Notes
+
+- Library listing is capped per request (up to 10,000 files).
+- When auth is enabled, library import endpoints require a valid session.
+- The mounted library is a source; removing it does not delete already imported documents.

docs-site/versioned_docs/version-v4.0.1/configure/tts-provider-guides/deepinfra.md

@@ -0,0 +1,42 @@
+---
+title: DeepInfra
+---
+
+Use DeepInfra's hosted TTS models as your provider.
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `deepinfra`.
+2. Keep base URL as `https://api.deepinfra.com/v1/openai`.
+3. Enter your API key.
+4. Set your preferred default model/voice.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=https://api.deepinfra.com/v1/openai
+API_KEY=your-deepinfra-key
+```
+
+**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
+
+1. Set provider to `Deepinfra`.
+2. The base URL is pre-filled, no changes needed.
+3. Enter your `API_KEY`.
+4. Choose a model and voice.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Notes
+
+- Available models include `hexgrad/Kokoro-82M` and `canopylabs/orpheus-3b-0.1-ft`.
+- Without an API key, only the free-tier model (`hexgrad/Kokoro-82M`) is shown in the dropdown.
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
+
+## References
+
+- [DeepInfra TTS models](https://deepinfra.com/models/text-to-speech)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.1/configure/tts-provider-guides/kitten-tts-fastapi.md

@@ -0,0 +1,47 @@
+---
+title: KittenTTS-FastAPI
+---
+
+Run [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider. Lightweight and CPU-friendly.
+
+## Run KittenTTS
+
+```bash
+docker run -it --rm \
+  --name kittentts-fastapi \
+  -e KITTEN_MODEL_REPO_ID="KittenML/kitten-tts-nano-0.8-fp32" \
+  -p 8005:8005 \
+  ghcr.io/richardr1126/kittentts-fastapi-cpu
+```
+
+## Connect to OpenReader
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set base URL to your KittenTTS endpoint (e.g. `http://kittentts-fastapi:8005/v1`).
+3. Leave API key blank unless required by your deployment.
+4. Set default model to `kitten-tts` (or your backend model id).
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://kittentts-fastapi:8005/v1
+```
+
+> Use `kittentts-fastapi` if that's the container name, or `host.docker.internal` if not.
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your KittenTTS endpoint (e.g. `http://kittentts-fastapi:8005/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `kitten-tts` (or the model your deployment exposes).
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## References
+
+- [richardr1126/KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.1/configure/tts-provider-guides/kokoro-fastapi.md

@@ -0,0 +1,75 @@
+---
+title: Kokoro-FastAPI
+---
+
+Run [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
+
+:::warning
+For Kokoro issues and support, use the upstream repository: [remsky/Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI).
+:::
+
+## Run Kokoro
+
+**CPU:**
+
+```bash
+docker run --name kokoro-tts \
+  --restart unless-stopped \
+  -d \
+  -p 8880:8880 \
+  -e ONNX_NUM_THREADS=8 \
+  -e ONNX_INTER_OP_THREADS=4 \
+  -e ONNX_EXECUTION_MODE=parallel \
+  -e ONNX_OPTIMIZATION_LEVEL=all \
+  -e ONNX_MEMORY_PATTERN=true \
+  -e ONNX_ARENA_EXTEND_STRATEGY=kNextPowerOfTwo \
+  -e API_LOG_LEVEL=DEBUG \
+  ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
+```
+
+**GPU (NVIDIA):**
+
+```bash
+docker run --name kokoro-tts \
+  --restart unless-stopped \
+  -d \
+  --gpus all \
+  --user 1001:1001 \
+  -p 8880:8880 \
+  -e USE_GPU=true \
+  -e PYTHONUNBUFFERED=1 \
+  -e API_LOG_LEVEL=DEBUG \
+  ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.4
+```
+
+## Connect to OpenReader
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set base URL to your Kokoro endpoint (e.g. `http://kokoro-tts:8880/v1`).
+3. Leave API key blank unless required by your deployment.
+4. Set default model to `Kokoro`.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://kokoro-tts:8880/v1
+```
+
+> Use `kokoro-tts` if that's the container name, or `host.docker.internal` if not.
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your Kokoro endpoint (e.g. `http://kokoro-tts:8880/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `Kokoro`.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## References
+
+- [remsky/Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.1/configure/tts-provider-guides/openai.md

@@ -0,0 +1,41 @@
+---
+title: OpenAI
+---
+
+Use the OpenAI TTS API as your provider.
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `openai`.
+2. Keep base URL as `https://api.openai.com/v1`.
+3. Enter your API key.
+4. Set your preferred default model/voice.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=https://api.openai.com/v1
+API_KEY=sk-...
+```
+
+**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
+
+1. Set provider to `OpenAI`.
+2. The base URL is pre-filled, no changes needed.
+3. Enter your `API_KEY`.
+4. Choose a model and voice.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Notes
+
+- Models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
+
+## References
+
+- [OpenAI TTS pricing](https://platform.openai.com/docs/pricing#transcription-and-speech)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.1/configure/tts-provider-guides/orpheus-fastapi.md

@@ -0,0 +1,41 @@
+---
+title: Orpheus-FastAPI
+---
+
+Run [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
+
+## Run Orpheus
+
+Refer to the upstream repository for Docker instructions: [Lex-au/Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI).
+
+## Connect to OpenReader
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set base URL to your Orpheus endpoint (e.g. `http://orpheus:8000/v1`).
+3. Leave API key blank unless required by your deployment.
+4. Set default model to `Orpheus` (or your backend model id).
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://orpheus:8000/v1
+```
+
+> Use the container name if that's how it's named, or `host.docker.internal` if not.
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your Orpheus endpoint (e.g. `http://orpheus:8000/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `Orpheus` (or the model your deployment exposes).
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## References
+
+- [Lex-au/Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.1/configure/tts-provider-guides/other.md

@@ -0,0 +1,52 @@
+---
+title: Other
+---
+
+Use any OpenAI-compatible TTS service with OpenReader, including self-hosted servers not covered by a dedicated guide.
+
+## Requirements
+
+Your service must expose these endpoints:
+
+- `GET /v1/audio/voices`
+- `POST /v1/audio/speech`
+
+Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS-FastAPI](./kitten-tts-fastapi), [Orpheus-FastAPI](./orpheus-fastapi).
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `custom-openai`.
+2. Set `API_BASE` to your service base URL (typically ending in `/v1`).
+3. Set API key if your service requires authentication.
+4. Set a default model/voice supported by your backend.
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_BASE=http://your-tts-server/v1
+API_KEY=optional-key-if-required
+```
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your service's base URL (typically ending in `/v1`).
+3. Set `API_KEY` if your service requires authentication.
+4. Choose a model and voice supported by your backend.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+:::warning TTS requests are server-side
+`API_BASE` must be reachable from the **Next.js server**, not just the browser. In Docker, use container names or `host.docker.internal`.
+:::
+
+## Troubleshooting
+
+If voices don't load, check that `/v1/audio/voices` is reachable from the server and returns a valid response shape.
+
+## References
+
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.1/configure/tts-provider-guides/replicate.md

@@ -0,0 +1,48 @@
+---
+title: Replicate
+---
+
+Use Replicate's hosted TTS models as your provider.
+
+## Setup
+
+**Recommended (auth + admin): Settings → Admin → Shared providers**
+
+1. Add a shared provider with type `replicate`.
+2. Enter your API key.
+3. Set default model to:
+   `alphanumericuser/kokoro-82m:89b6fa84e4fa2dd6bd3a96be3e1f12827a3516c9fda8fddbac7a0be131c9a6f5` (or your preferred model).
+
+**Legacy bootstrap seed (optional, first boot only):**
+
+```env
+API_KEY=r8_...
+```
+
+Then update the shared provider's **Default model** in **Settings → Admin → Shared providers**.
+
+**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
+
+1. Set provider to `Replicate`.
+2. Enter your `API_KEY`.
+3. Choose a model and voice.
+
+See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
+
+## Notes
+
+- Built-in Replicate models:
+  - `alphanumericuser/kokoro-82m:89b6fa84e4fa2dd6bd3a96be3e1f12827a3516c9fda8fddbac7a0be131c9a6f5`
+  - `google/gemini-3.1-flash-tts`
+  - `minimax/speech-2.8-turbo`
+  - `qwen/qwen3-tts`
+  - `inworld/tts-1.5-mini`
+- You can also choose `Other` and enter any Replicate model ID (for example `owner/model-name` or `owner/model-name:version`).
+- Native model speed is not available on all Replicate models; OpenReader hides/disables native speed controls where unsupported.
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
+
+## References
+
+- [Replicate](https://replicate.com/explore)
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/versioned_docs/version-v4.0.1/configure/tts-providers.md

@@ -0,0 +1,57 @@
+---
+title: TTS Providers
+---
+
+OpenReader routes all TTS requests through the Next.js server to an OpenAI-compatible API. There are three places provider configuration can live:
+
+**Admin-managed shared providers** (Settings > Admin > Shared providers): DB-backed instances configured by an admin and visible to all users. Keys are encrypted at rest and never exposed to the client. Available only when [auth is enabled](./auth) and your account is in `ADMIN_EMAILS`. See [Admin Panel](./admin-panel).
+
+**Per-user Settings modal** (Settings > TTS Provider): provider + API key stored in the user's browser and sent with every TTS request. This path is available only when the admin/runtime setting `restrictUserApiKeys=false`.
+
+**Environment variables**: `API_KEY` and `API_BASE` exist as a one-shot first-boot seed that auto-creates a `default-openai` admin shared provider. After the first boot they are no longer read by the running app.
+
+:::tip
+If you're running a private/self-hosted instance and want per-user BYOK behavior, turn off **Settings → Admin → Site features → Restrict user API keys**. For first-boot automation, set `runtimeConfig.restrictUserApiKeys=false` in `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH`.
+:::
+
+## Providers
+
+- **OpenAI**: Cloud. Base URL pre-filled (`https://api.openai.com/v1`). API key required.
+- **Replicate**: Cloud. Base URL managed internally by OpenReader. API key required.
+- **DeepInfra**: Cloud. Base URL pre-filled (`https://api.deepinfra.com/v1/openai`). API key required.
+- **Custom OpenAI-Like**: Self-hosted or any custom endpoint. `API_BASE` must be set manually (typically ending in `/v1`). API key optional.
+
+For `OpenAI`, `DeepInfra`, and `Replicate` you only need to supply an API key. For `Custom OpenAI-Like` you must also set `API_BASE`.
+
+## Built-in model catalogs
+
+- **Replicate** models: `alphanumericuser/kokoro-82m`, `google/gemini-3.1-flash-tts`, `minimax/speech-2.8-turbo`, `qwen/qwen3-tts`, `inworld/tts-1.5-mini` (or choose `Other` and enter any Replicate model ID, such as `owner/model` or `owner/model:version`)
+- **OpenAI** models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
+- **DeepInfra** models: includes `hexgrad/Kokoro-82M` and additional hosted models (depending on API key / feature flags)
+
+## Custom provider requirements
+
+Self-hosted or custom providers must expose OpenAI-compatible audio endpoints:
+
+- `GET /v1/audio/voices`
+- `POST /v1/audio/speech`
+
+:::warning TTS requests are server-side
+TTS requests originate from the **Next.js server**, not the browser. `API_BASE` must be reachable from the server runtime. In Docker, use container names or `host.docker.internal` rather than `localhost`.
+:::
+
+## Provider guides
+
+- [Kokoro-FastAPI](./tts-provider-guides/kokoro-fastapi)
+- [KittenTTS-FastAPI](./tts-provider-guides/kitten-tts-fastapi)
+- [Orpheus-FastAPI](./tts-provider-guides/orpheus-fastapi)
+- [Replicate](./tts-provider-guides/replicate)
+- [DeepInfra](./tts-provider-guides/deepinfra)
+- [OpenAI](./tts-provider-guides/openai)
+- [Other](./tts-provider-guides/other)
+
+## Related
+
+- [Admin Panel](./admin-panel) — DB-backed shared providers with encrypted keys
+- [TTS Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
+- [TTS Rate Limiting](./tts-rate-limiting)

docs-site/versioned_docs/version-v4.0.1/configure/tts-rate-limiting.md

@@ -0,0 +1,42 @@
+---
+title: TTS Rate Limiting
+---
+
+This page explains OpenReader's TTS character rate limiting controls.
+
+## Overview
+
+- TTS rate limiting is disabled by default.
+- Primary control is **Settings → Admin → Site features → Disable TTS daily rate limiting**.
+- Limits are enforced per day in UTC.
+- Enforcement applies only when auth is enabled.
+
+## How enforcement works
+
+When enabled, OpenReader enforces:
+
+- Per-user daily character limits.
+- IP backstop daily character limits.
+- Anonymous device backstop tracking (cookie-based) to reduce limit resets.
+
+If a request exceeds the active limit, the TTS API returns `429` with reset metadata for the next UTC day.
+
+## Required auth behavior
+
+- Auth must be enabled (`BASE_URL` + `AUTH_SECRET`) for TTS char limits to apply.
+- If auth is disabled, TTS character limits are effectively unlimited.
+- `DISABLE_AUTH_RATE_LIMIT` only affects Better Auth's own request throttling.
+- `DISABLE_AUTH_RATE_LIMIT` does not disable TTS character limits.
+
+## Runtime config
+
+- `disableTtsRateLimit` default: `true`
+- Per-user and IP backstop limit values are configured in **Settings → Admin → Site features** and stored in DB runtime settings.
+- Optional first-boot seeding can be done via `RUNTIME_SEED_JSON` / `RUNTIME_SEED_JSON_PATH` (`runtimeConfig.disableTtsRateLimit`).
+
+## Related docs
+
+- TTS/rate-limit environment variables: [Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
+- PDF parsing rate limiting (separate, compute-side throttle): [Admin Panel → Site features](./admin-panel#site-features) and [Environment Variables](../reference/environment-variables#compute-pdf-parsing-rate-limiting-runtime-settings)
+- Auth configuration: [Auth](./auth)
+- Provider setup: [TTS Providers](./tts-providers)