fix: pre-launch security, docs accuracy, and README restructure

Lock /api/search behind _require_auth() (was the only unauthenticated
API route), add auth enforcement test, remove false Bazarr auto-rescan
claims from docs, update contributor/test docs to lead with make test,
fix .eng.srt mismatch in test_single_video.py, reframe README as
GUI-first with Known Limitations section, add screenshot placeholders.

Author: tylerbcrawford

.env.example

@@ -90,9 +90,8 @@ DISABLE_AUTH=true
 # Example: ALLOWED_EMAILS=user1@example.com,user2@example.com
 ALLOWED_EMAILS=
 
-# Bazarr Integration (optional)
-# Enable automatic subtitle rescan after batch completion
-# Leave BAZARR_BASE_URL empty to disable integration
+# Bazarr Integration (planned — not yet wired. See roadmap.)
+# These env vars are accepted but auto-rescan on batch completion is not yet active.
 BAZARR_BASE_URL=
 BAZARR_API_KEY=
 

CONTRIBUTING.md

@@ -52,18 +52,21 @@ docker compose logs -f web worker
 ### Testing
 
 ```bash
-# Validate project structure
+# Run the full test suite (preferred — this is what CI runs)
+make test
+
+# Validate project structure (no API key needed)
 python3 scripts/validate_setup.py
 
-# Test a single video (requires DEEPGRAM_API_KEY)
+# Test a single video end-to-end (requires DEEPGRAM_API_KEY)
 python3 tests/test_single_video.py /path/to/video.mkv
 ```
 
 ## Pull Requests
 
 1. **Keep PRs focused** — one feature or fix per PR
 2. **Write a clear description** — explain what changed and why
-3. **Test your changes** — verify with `validate_setup.py` at minimum
+3. **Test your changes** — run `make test` to execute the full test suite
 4. **Update docs** if your change affects configuration, CLI flags, or API endpoints
 
 ### PR Title Format

README.md

@@ -83,25 +83,24 @@ docker compose run --profile cli --rm cli
 
 ### Basic Usage
 
-**Process entire media library (CLI):**
+**Start the Web UI (recommended):**
 ```bash
-docker compose run --profile cli --rm cli
+docker compose up -d
+# Open http://localhost:5000
 ```
 
-**Process specific show/season:**
+**Process via CLI (headless/batch):**
 ```bash
-docker compose run --profile cli --rm -e MEDIA_PATH=/media/tv/ShowName/Season\ 01 cli
-```
+# Process entire media library
+docker compose run --profile cli --rm cli
 
-**Start the Web UI:**
-```bash
-docker compose up -d
-# Open http://localhost:5000
+# Process specific show/season
+docker compose run --profile cli --rm -e MEDIA_PATH=/media/tv/ShowName/Season\ 01 cli
 ```
 
 ---
 
-## Web UI (Optional)
+## Web UI
 
 The Web UI provides a browser-based interface for remote management, batch processing, and AI-powered keyterm generation.
 
@@ -115,13 +114,17 @@ Access at `http://localhost:5000` (or configure reverse proxy for remote access)
 
 > **Security Note:** This app exposes media paths and triggers write operations. `DISABLE_AUTH=true` is the default in the example compose — suitable for local access only. For remote/production deployments, set `DISABLE_AUTH=false` and place a reverse proxy with authentication (OAuth2-Proxy, Authelia, Nginx basic auth) in front of the app.
 
+### Screenshots
+
+<!-- Recommended: main browse page, scan results, transcription progress, settings panel -->
+*Screenshots coming soon.*
+
 ### Web UI Features
 
 - 🌐 **Remote access** from any device
 - 📊 **Real-time progress tracking** with per-file status
 - 🤖 **AI Keyterm Generation** with Claude, GPT, or Gemini (optional)
 - 📁 **Directory browser** with search and file filtering
-- 🔄 **Bazarr integration** for automatic subtitle rescans
 - ⚡ **Batch processing** with parallel workers
 - 🔍 **Find Missing Subtitles** — one-click async library scan with CSV export
 - ⚙️ **Full Nova-3 feature control** — model selection, redaction, dictation, multichannel, Audio Intelligence, and more via collapsible Transcription Settings panel
@@ -257,7 +260,7 @@ After generation, refresh your media library to detect new subtitles.
 1. Download new season via Sonarr/Radarr
 2. Run: `docker compose run --profile cli --rm -e MEDIA_PATH=/media/tv/ShowName/Season\ 01 cli`
 3. Subtitles generated automatically
-4. Bazarr rescan triggers (if Web UI integration enabled)
+4. Refresh your media server library to pick up new subtitles
 
 ### Complete Library Cleanup
 
@@ -308,6 +311,13 @@ id -g  # Get your GID
 
 ---
 
+## Known Limitations
+
+- **Authentication**: `DISABLE_AUTH=true` is the default for local use. For remote access, place a reverse proxy with authentication in front of the app (see Security Note above).
+- **CLI vs Web UI**: The CLI processes files synchronously and does not support AI keyterm generation, library scanning, or progress tracking. The Web UI provides all features including async batch processing, real-time progress, and AI keyterm generation.
+
+---
+
 ## Contributing
 
 Contributions welcome! Please feel free to submit issues or pull requests.

docs/screenshots/.gitkeep

@@ -53,7 +53,7 @@ The Web UI adds asynchronous processing capabilities:
 2. Flask API creates Celery task group
 3. Workers process files in parallel (configurable concurrency)
 4. Progress updates sent via Server-Sent Events (SSE)
-5. Bazarr rescan triggered on completion (if configured)
+5. Results returned to the UI
 
 ---
 

docs/technical.md

@@ -2,6 +2,19 @@
 
 This directory contains comprehensive tests for the Subgeneratorr CLI tool.
 
+## Quick Run (Recommended)
+
+The fastest way to run all unit tests:
+
+```bash
+make test
+# or: pytest tests/ -v
+```
+
+This runs the full pytest suite without needing Docker or API keys. The detailed CLI integration tests described below require Docker and a Deepgram API key.
+
+---
+
 ## Contents
 
 - [`CLI_TEST_PLAN.md`](CLI_TEST_PLAN.md) - Detailed test plan with all test cases

tests/README.md

@@ -103,6 +103,15 @@ def test_scan_export_invalid_task_id():
     assert response.status_code == 400
 
 
+def test_search_requires_auth():
+    """Verify /api/search rejects unauthenticated requests when auth is enabled."""
+    with patch.dict(os.environ, {'DISABLE_AUTH': 'false'}, clear=False):
+        with app.test_client() as client:
+            response = client.get("/api/search?q=test")
+
+    assert response.status_code == 401
+
+
 def test_scan_status_valid_uuid_pending():
     task_result = SimpleNamespace(state="PENDING", info=None)
 

tests/test_library_scan_api.py

@@ -39,7 +39,7 @@ def main():
         print(f"Please provide a valid video file path.")
         sys.exit(1)
 
-    srt_path = video_path.with_suffix('.srt')
+    srt_path = video_path.with_suffix('.eng.srt')
     if srt_path.exists():
         print(f"⚠️  Warning: SRT file already exists at {srt_path}")
         print(f"Delete it first to regenerate, or test with a different video.")
@@ -57,7 +57,7 @@ def main():
         print("="*70)
         print("✅ TEST SUCCESSFUL")
         print("="*70)
-        print(f"Generated subtitle file: {srt_path}")
+        print(f"Generated subtitle file: {video_path.with_suffix('.eng.srt')}")
         print()
         gen.print_summary()
         gen.save_stats()

tests/test_single_video.py

@@ -202,6 +202,7 @@ def api_search():
         JSON with matching directories and files, each including a context path
         showing where the match lives relative to MEDIA_ROOT.
     """
+    _require_auth()
     query = request.args.get("q", "").strip()
     root = request.args.get("path", str(MEDIA_ROOT))