QA baseline v1.1 + README cleanup

QA Baseline:
- Added Section 9: Natural Cadence System (all functions, config, test cases)
- Added Section 10: Response Modes System (13 modes, loader API, AI variables)
- All 7 new files verified: syntax PASS

README:
- Removed setup services section
- Fixed badbread.com -> it.badbread.com

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: badbread

README.md

@@ -645,17 +645,6 @@ radio_effect:
 
 ---
 
-## Need Help Setting This Up?
-
-If you want VoxWatch running without the hassle, I offer setup services:
-
-- **Remote Setup ($200)** — You already have Frigate running. I connect remotely, install VoxWatch, configure everything, and test audio.
-- **Full System Setup ($600+)** — I set up Frigate + VoxWatch end-to-end on your hardware.
-
-If you're interested, reach out: jason@voxwatch.dev
-
----
-
 ## Built in the Open (AI-Assisted)
 
 VoxWatch was built using a heavily **AI-assisted workflow** (primarily Claude), with a focus on making the codebase:
@@ -716,7 +705,7 @@ Call it out.
 I tend to build fast and refine in public.
 
 If you're curious how I approach stuff like this:
-https://badbread.com
+https://it.badbread.com
 
 ---
 

tests/QA_BASELINE.md

@@ -1,5 +1,5 @@
 # VoxWatch QA Baseline Manifest
-# Version: 1.0 | Date: 2026-03-24 | Coverage: All endpoints, components, and behaviors
+# Version: 1.1 | Date: 2026-03-25 | Coverage: All endpoints, components, and behaviors
 
 This manifest maps EVERY testable element in the VoxWatch system. If something
 is not listed here, it is not covered in QA. Update this document whenever the
@@ -227,7 +227,221 @@ gemini (video+images) → openai (images) → anthropic (images) → grok (image
 10. SPA catch-all has path traversal guard
 11. Dispatch preview requires VoxWatch on port 8892
 12. Config validators run in order (cameras → enabled)
+13. Natural cadence falls back to flat-string TTS if any ffmpeg step fails
 
 ---
 
-*Generated: 2026-03-24 | Update on any API, component, or config change*
+## Section 9: Natural Cadence System
+
+### Module: voxwatch/speech/natural_cadence.py
+
+| Item | Detail |
+| ------ | -------- |
+| Entry point | `generate_natural_speech(phrases, audio_pipeline, output_path, config, cadence_config=None) -> bool` |
+| Config dataclass | `CadenceConfig` -- 11 fields, built via `CadenceConfig.from_config(config)` |
+| AI response parser | `parse_ai_response(response: str) -> list[str]` |
+| Pause calculator | `determine_pause_duration(phrase, cadence_config) -> float` |
+| Silence generator | `generate_silence(duration, sample_rate, output_path) -> bool` (async, ffmpeg lavfi anullsrc) |
+| Speed variation | `apply_speed_variation(input_path, output_path, speed) -> bool` (async, ffmpeg atempo) |
+| Segment concat | `concatenate_segments(segment_paths, output_path) -> bool` (async, ffmpeg concat demuxer) |
+| Format normalise | `_convert_to_work_format(input_path, output_path) -> bool` (internal, 44.1 kHz 16-bit mono) |
+| Working format | PCM 16-bit signed, 44100 Hz, mono -- all intermediate files |
+| ffmpeg timeout | 30 seconds per subprocess call |
+| Fallback | Returns False; caller falls back to `audio_pipeline.generate_tts` flat string |
+| Temp cleanup | `TemporaryDirectory` always cleaned in `finally` block |
+
+### parse_ai_response() -- Input Format Priority
+
+| Priority | Format | Detection |
+| ---------- | -------- | ----------- |
+| 1 | JSON array inside markdown code block | regex inside code fences, re.DOTALL |
+| 2 | Bare JSON array anywhere in string | regex match, re.DOTALL |
+| 3 | Plain text sentence split | re.split on sentence-ending punctuation |
+| Fallback | Entire response as single phrase | When all strategies yield empty |
+
+### CadenceConfig -- 11 Parameters (config section: speech.natural_cadence)
+
+| Parameter | Type | Default | Config key |
+| --------- | ---- | ------- | ---------- |
+| `min_pause` | float | 0.2s | `speech.natural_cadence.min_pause` |
+| `max_pause` | float | 0.6s | `speech.natural_cadence.max_pause` |
+| `period_pause` | float | 0.5s | `speech.natural_cadence.period_pause` |
+| `ellipsis_pause` | float | 0.7s | `speech.natural_cadence.ellipsis_pause` |
+| `comma_pause` | float | 0.2s | `speech.natural_cadence.comma_pause` |
+| `min_speed` | float | 0.92 | `speech.natural_cadence.min_speed` |
+| `max_speed` | float | 1.08 | `speech.natural_cadence.max_speed` |
+| `speed_variation_enabled` | bool | True | `speech.natural_cadence.speed_variation` |
+| `leading_pause` | float | 0.3s | `speech.natural_cadence.leading_pause` |
+| `trailing_pause` | float | 0.2s | `speech.natural_cadence.trailing_pause` |
+| `postprocess` | bool | True | `speech.natural_cadence.postprocess` |
+
+### Pause Duration Rules (determine_pause_duration)
+
+| Trailing punctuation | Pause used |
+| --------------------- | ---------- |
+| `...` (ellipsis) | `ellipsis_pause` (0.7s default) |
+| `.` `!` `?` | `period_pause` (0.5s default) |
+| `,` `;` `:` | `comma_pause` (0.2s default) |
+| None / other | random uniform in [min_pause, max_pause] |
+
+### Module: voxwatch/speech/postprocess.py
+
+| Item | Detail |
+| ------ | -------- |
+| Entry point | `apply_natural_postprocess(input_path, output_path) -> bool` (async) |
+| Filter chain | `silenceremove` -> `acompressor` (3:1 ratio, -18 dB threshold) -> `loudnorm` (-16 LUFS) |
+| Silence threshold | -50 dB, 0.1s minimum duration (prevents trimming inter-phrase gaps) |
+| Target loudness | -16 LUFS integrated (EBU R128 / ITU-R BS.1770), TP=-1.5, LRA=11 |
+| Output format | PCM 16-bit, 44100 Hz, mono |
+| Invocation | Called lazily from `generate_natural_speech` when `CadenceConfig.postprocess=True` |
+| Failure mode | Non-fatal -- `generate_natural_speech` logs warning and uses unprocessed audio |
+
+### AudioPipeline Integration
+
+| Method | Description |
+| ------- | ----------- |
+| `AudioPipeline.generate_natural_tts(phrases, output_path)` | Calls `generate_natural_speech`; on False return falls back to standard `generate_tts` |
+
+### Config Section: speech.natural_cadence
+
+Sits under the top-level `speech` key in config.yaml. All 11 parameters from CadenceConfig are read here. Missing keys use dataclass defaults -- the section is entirely optional.
+
+### Test Coverage: tests/test_natural_cadence.py
+
+| Test step | What is verified |
+| --------- | ---------------- |
+| 1 -- parse_ai_response | JSON array, JSON code block, plain text sentence split -- all return correct phrase list |
+| 2 -- determine_pause_duration | `.` period_pause, `...` ellipsis_pause, `,` comma_pause, no-punct in [min, max] |
+| 3 -- generate_silence | 0.5s lavfi silence WAV exists and >= 200 bytes |
+| 4 -- apply_speed_variation | atempo 1.05x output exists and >= 200 bytes |
+| 5 -- apply_natural_postprocess | compression + loudnorm output exists and >= 200 bytes |
+| 6 -- Full A/B pipeline | cadence WAV vs flat espeak WAV both generated for listening comparison |
+
+---
+
+## Section 10: Response Modes System
+
+### Modules
+
+| Module | Exports |
+| ------- | -------- |
+| `voxwatch/modes/mode.py` | `ResponseMode`, `ToneConfig`, `VoiceConfig`, `BehaviorConfig`, `StageConfig` |
+| `voxwatch/modes/loader.py` | `load_modes`, `get_active_mode`, `get_mode_prompt`, `get_mode_template`, `build_ai_vars`, `extract_ai_vars_from_dispatch_json` |
+| `voxwatch/modes/__init__.py` | Re-exports all of the above as the public API |
+
+### ResponseMode Dataclass Hierarchy
+
+```
+ResponseMode
++-- id: str
++-- category: str  (core | advanced | novelty | custom)
++-- name: str
++-- description: str
++-- effect: str
++-- tone: ToneConfig
+|     +-- mood: str (default neutral)
+|     +-- speed_multiplier: float (default 1.0)
+|     +-- radio_effect: bool (default False)
++-- voice: VoiceConfig
+|     +-- kokoro_voice: Optional[str]
+|     +-- openai_voice: Optional[str]
+|     +-- elevenlabs_voice: Optional[str]
+|     +-- piper_model: Optional[str]
++-- behavior: BehaviorConfig
+|     +-- is_dispatch: bool (default False)
+|     +-- use_radio_effect: bool (default False)
+|     +-- officer_response: bool (default True)
+|     +-- json_ai_output: bool (default False)
+|     +-- scene_context_prefix: bool (default True)
++-- stages: dict[str, StageConfig]
+      +-- StageConfig
+            +-- prompt_modifier: str
+            +-- templates: list[str]
+```
+
+### Built-in Modes (13 total)
+
+| ID | Category | Name |
+| ---- | --------- | ------ |
+| `police_dispatch` | core | Police Dispatch |
+| `live_operator` | core | Live Operator |
+| `private_security` | core | Private Security |
+| `homeowner` | core | Homeowner |
+| `evidence_collection` | core | Evidence Collection |
+| `standard` | core | Standard (fallback) |
+| `silent_pressure` | advanced | Silent Pressure |
+| `neighborhood_alert` | advanced | Neighborhood Alert |
+| `automated_surveillance` | advanced | Automated Surveillance |
+| `mafioso` | novelty | Mafioso |
+| `disappointed_parent` | novelty | Disappointed Parent |
+| `pirate_captain` | novelty | Pirate Captain |
+| `tony_montana` | novelty | Tony Montana |
+
+### loader.py Public API
+
+| Function | Signature | Description |
+| ---------- | ----------- | ------------- |
+| `load_modes` | `(config) -> dict[str, ResponseMode]` | Loads built-ins, merges user-defined modes from `response_modes.modes` |
+| `get_active_mode` | `(config, camera_name=None) -> ResponseMode` | Resolves active mode; honours per-camera overrides; falls back to standard |
+| `get_mode_prompt` | `(mode_def, stage, ai_vars) -> str` | Returns AI system prompt with mode prompt_modifier applied and vars substituted |
+| `get_mode_template` | `(mode_def, stage, ai_vars, index=0) -> str` | Renders fallback template string with {variable} substitution |
+| `build_ai_vars` | `(config, camera_name, ...) -> dict` | Assembles all 8 AI description variables with neutral fallbacks |
+| `extract_ai_vars_from_dispatch_json` | `(ai_json_str) -> dict` | Parses dispatch-mode JSON AI response into AI vars dict |
+
+### Mode Resolution Order (get_active_mode)
+
+1. `response_modes.camera_overrides[camera_name]` -- per-camera override (highest priority)
+2. `response_modes.active_mode` -- global active mode
+3. `response_mode.name` or `persona.name` -- legacy single-key format
+4. standard -- final fallback if mode ID not found in loaded library
+
+### AI Description Variables (8 total)
+
+| Variable | Source | Neutral fallback |
+| --------- | -------- | ---------------- |
+| `{clothing_description}` | AI vision response | "the individual" |
+| `{location_on_property}` | AI vision response | "the property" |
+| `{behavior_description}` | AI vision response | "their current actions" |
+| `{suspect_count}` | AI vision response | "one" |
+| `{address_street}` | `config.property.street` | "this address" |
+| `{address_full}` | `config.property.full_address` | "this address" |
+| `{time_of_day}` | datetime.now().hour at call time | "this hour" |
+| `{camera_name}` | Frigate detection event | "the camera" |
+
+Time-of-day labels: early morning (hours 5-8), morning (9-11), afternoon (12-16), evening (17-20), night (all other hours).
+
+### Per-Camera Mode Overrides (config.yaml)
+
+```yaml
+response_modes:
+  active_mode: police_dispatch
+  camera_overrides:
+    backyard_cam: homeowner
+    front_door: police_dispatch
+```
+
+Override lookup uses exact camera name string match against `camera_overrides` dict keys.
+
+### Custom Mode Support
+
+User-defined modes in config.yaml under `response_modes.modes` are parsed via `_parse_mode_from_dict`.
+Required field: `id`. Optional: `category` (default custom), name, description, effect, tone.*, voice.*, behavior.*, stage templates.
+Invalid entries are logged and skipped without crashing the service.
+
+### Variable Substitution Safety
+
+`_substitute_vars` uses `_SafeFormatMap` (dict subclass). Unknown {placeholder} tokens returned as-is. Malformed format strings returned unchanged.
+
+### extract_ai_vars_from_dispatch_json
+
+Parses a JSON object string from dispatch-mode AI responses. Field mapping:
+- `description` -> `clothing_description`
+- `location` -> `location_on_property`
+- `suspect_count` -> `suspect_count`
+- `behavior` or `movement` -> `behavior_description`
+
+On JSON parse failure: returns dict with all empty-string values (non-fatal).
+
+---
+
+*Generated: 2026-03-25 | Update on any API, component, or config change*