@@ -5,7 +5,7 @@ permissions:
 
 on:
   push:
-    branches: [main]
+    branches: [main, feature/audio-v2-cutover]
     paths: ['app/**']
   workflow_dispatch:
     inputs:
@@ -51,9 +51,9 @@ jobs:
         run: |
           npm run test:wearable-activation
           npm run typecheck
-          npm run test:voice-protocol
-          npm run test:phone-duplex
+          npm run test:durable-audio-spool
           npm run check:theme
+          npx --no-install expo-modules-autolinking verify --platform ios --verbose
 
       - name: Write and validate ASC API key
         env:
 
@@ -50,6 +50,25 @@ Do not assume a remote deployment's checkout is clean or matches `origin` — ch
 inspect the live application. Remote deployment, restarts, or other mutations still
 require the user's request to change or deploy the running system.
 
+### Verifying live historical data
+
+Before claiming that captured data was not sent, stored, processed, or added to a
+timeline:
+
+- Anchor the investigation on the exact user-provided URL or ID. Confirm the live
+  database and inspect a real document's field names and BSON types; do not guess that
+  a domain ID is MongoDB `_id` or that a date is stored as a string. Treat an empty
+  query as inconclusive until the same query shape returns a known positive control.
+- Verify each layer separately: ingress/backfill records, canonical `audio_chunks`,
+  `conversations`, timeline days/episodes, and the UI. Promotion between collections
+  can leave an ingress collection empty even though canonical data exists.
+- For timelines, use the stored `local_date` type and user timezone, follow explicit
+  conversation/audio references, check time overlap, and distinguish active/open
+  episodes from provisional or superseded runs.
+- State exactly which claim the evidence supports: sent, stored, processed, linked, or
+  merely visible in one UI route. Report UTC and user-local timestamps when time is
+  relevant.
+
 ### Investigating a slow or unresponsive backend
 
 When *everything* is slow at once — the dashboard hangs, health checks time out, a
@@ -280,7 +299,7 @@ voice evidence and human review assign a real person.
 
 ### Key Components
 - **Audio Pipeline**: Real-time Opus/PCM → Application-level processing → Deepgram transcription → memory extraction
-- **Wyoming Protocol**: WebSocket communication uses Wyoming protocol (JSONL + binary) for structured audio sessions
+- **Audio Protocol V2**: `/ws/audio` uses generated control messages and atomic raw-Opus media envelopes
 - **Unified Pipeline**: Job-based tracking system for all audio processing (WebSocket and file uploads)
 - **Job Tracker**: Tracks pipeline jobs with stage events (audio → transcription → memory) and completion status
 - **Task Management**: BackgroundTaskManager tracks all async tasks to prevent orphaned processes
@@ -310,8 +329,12 @@ Optional:
 
 ## Data Flow Architecture
 
-1. **Audio Ingestion**: OMI devices stream audio via WebSocket using Wyoming protocol with JWT auth
-2. **Wyoming Protocol Session Management**: Clients send audio-start/audio-stop events for session boundaries
+For any capture, streaming, playback, wake-word, transcription, or audio-import
+change, read `docs/backend/audio-interface-map.md`. It is the boundary inventory and
+migration ledger for the generated Chronicle audio contract.
+
+1. **Audio Ingestion**: Devices stream raw Opus through generated audio-v2 envelopes with bearer authentication
+2. **Typed Session Management**: Bound start/stop controls define capture sessions and reject stale sockets
 3. **Application-Level Processing**: Global queues and processors handle all audio/transcription/memory tasks
 4. **Speech-Driven Conversation Creation**: Continuous capture creates no user-facing row until speech is detected; deliberate recordings/uploads are visible immediately
 5. **Audio Evidence and Conversations**: Opus audio documents are persisted in `audio_chunks`; `captured_at` remains stable when chunks are split, merged, or trimmed. A conversation is the current semantic/operational claim over those documents, not their temporal identity.
@@ -460,7 +483,7 @@ SPEAKER_SERVICE_URL=http://speaker-recognition:8085
 ### Common Endpoints
 - **GET /health**: Basic application health check
 - **GET /readiness**: Service dependency validation
-- **WS /ws**: Audio streaming endpoint with codec parameter (Wyoming protocol, supports pcm and opus codecs)
+- **WS /ws/audio**: Audio-v2 WebSocket (generated control JSON plus atomic raw-Opus media)
 - **GET /api/conversations**: User's conversations with transcripts
 - **GET /api/memories/search**: Agentic vault search (retrieval agent over the Markdown vault)
 - **POST /auth/jwt/login**: Email-based login (returns JWT token)
 
@@ -108,26 +108,18 @@ Reference in `AndroidManifest.xml`:
 
 ## Backend Configuration
 
-### Supported Backends
+### Supported Backend
 
-The app connects to any backend that accepts OPUS audio streams:
-
-1. **Simple Backend** (`backends/simple/`)
-   - Basic audio capture and storage
-   - Good for testing and development
-   - WebSocket endpoint: `/ws`
-
-2. **Advanced Backend** (`backends/advanced/`)
-   - Full transcription and memory features
-   - Real-time processing with speaker recognition
-   - WebSocket endpoint: `/ws?codec=pcm`
+The app connects to Chronicle's advanced backend using audio protocol v2 at
+`/ws/audio` with the `chronicle.audio.v2` WebSocket subprotocol. Capture and
+playback media are atomic raw-Opus envelopes generated from the shared contract.
 
 ### Connection Setup
 
 #### Local Development
 ```
-Backend URL: ws://[machine-ip]:8000/ws?codec=pcm
-Example: ws://192.168.1.100:8000/ws?codec=pcm
+Backend URL: ws://[machine-ip]:8000/ws/audio
+Example: ws://192.168.1.100:8000/ws/audio
 ```
 
 #### Public Access (Production)
@@ -138,7 +130,7 @@ Use ngrok or similar tunneling service:
 ngrok http 8000
 
 # Use provided URL in app
-Backend URL: wss://[ngrok-subdomain].ngrok.io/ws?codec=pcm
+Backend URL: wss://[ngrok-subdomain].ngrok.io/ws/audio
 ```
 
 ### Configuration Steps
@@ -147,14 +139,14 @@ Backend URL: wss://[ngrok-subdomain].ngrok.io/ws?codec=pcm
 2. **Open the mobile app**
 3. **Navigate to Settings**
 4. **Enter Backend URL**:
-   - Local: `ws://[your-ip]:8000/ws?codec=pcm`
-   - Public: `wss://[your-domain]/ws?codec=pcm`
+   - Local: `ws://[your-ip]:8000/ws/audio`
+   - Public: `wss://[your-domain]/ws/audio`
 5. **Save configuration**
 
 ## Duplex Phone Voice
 
 ### Overview
-The phone is a protocol-v1 Chronicle voice endpoint. One native engine owns microphone
+The phone is an audio-v2 Chronicle voice endpoint. One native engine owns microphone
 capture and Chronicle response playback while the session is active. The backend binds
 every response to the authenticated socket, audio session, voice session, capture
 epoch, and response generation.
@@ -163,7 +155,7 @@ epoch, and response generation.
 - **Barge-in**: Verified speakerphone AEC and isolated headphone routes capture while Chronicle speaks
 - **Safe fallback**: Unsupported routes report native half duplex instead of claiming simultaneous capture
 - **Native cancellation**: Socket loss, route changes, interruptions, and engine resets flush playback immediately
-- **Session fencing**: Reconnects create new audio and voice sessions and require short-lived resume proof
+- **Session fencing**: Reconnects create an exact physical-connection lease and a new capture binding
 - **Cross-platform replacement**: One `chronicle-duplex-audio` interface backs iOS and Android
 
 ### Setup & Usage
@@ -179,7 +171,7 @@ epoch, and response generation.
 - **iOS**: A native development or release build with microphone permission
 - **Android**: Android API 31+ native build with microphone permission
 - **Network**: Stable connection to Chronicle backend
-- **Backend**: Advanced backend with voice duplex protocol v1 at `/ws?codec=pcm`
+- **Backend**: Advanced backend with audio protocol v2 at `/ws/audio`
 
 #### Switching Audio Sources
 - **Mutual Exclusion**: Cannot use Bluetooth and phone audio simultaneously
@@ -202,7 +194,7 @@ JavaScript layer does not create a second player or gate microphone buffers.
 
 #### Audio Not Streaming
 - **Check Permissions**: Ensure microphone access granted
-- **Verify Backend URL**: Confirm `ws://[ip]:8000/ws?codec=pcm` format
+- **Verify Backend URL**: Confirm `ws://[ip]:8000/ws/audio` format
 - **Network Connection**: Test backend connectivity
 - **Authentication**: Verify JWT token is valid
 
@@ -307,7 +299,7 @@ curl -i -N -H "Connection: Upgrade" \
      -H "Upgrade: websocket" \
      -H "Sec-WebSocket-Key: test" \
      -H "Sec-WebSocket-Version: 13" \
-     http://[backend-ip]:8000/ws?codec=pcm
+     http://[backend-ip]:8000/ws/audio
 ```
 
 ## Development
@@ -353,10 +345,9 @@ npx expo build:android
 ### WebSocket Communication
 ```javascript
 // Connect to backend
-const ws = new WebSocket('ws://backend-url:8000/ws?codec=pcm');
+const ws = new WebSocket('ws://backend-url:8000/ws/audio', 'chronicle.audio.v2');
 
-// Send audio data
-ws.send(audioBuffer);
+// Send generated ClientControl JSON and atomic binary MediaEnvelope packets.
 
 // Handle responses
 ws.onmessage = (event) => {
 
@@ -177,7 +177,7 @@ function ThemeShowcase({ name }: { name: ThemeName }) {
 
       <SectionLabel>Form fields</SectionLabel>
       <Card>
-        <TextField label="Backend URL" value="wss://kraken.parrot-census.ts.net/ws" hint="From the QR on the dashboard." />
+        <TextField label="Backend URL" value="wss://kraken.parrot-census.ts.net/ws/audio" hint="From the QR on the dashboard." />
         <TextField label="Email" placeholder="user@example.com" />
         <TextField label="Password" value="hunter2" secureTextEntry error="Incorrect password." />
         <TextField label="Device name" value="pendant" editable={false} hint="Disabled while streaming." />