@extentos/mcp-server 0.0.57 → 0.0.59

package/dist/tools/docs/index.js

@@ -154,590 +154,66 @@ export const DOC_INDEX = [
     {
         topic: "getting_started",
         title: "Getting Started with Extentos",
-        content: "Extentos lets agents build Meta Ray-Ban apps from a structured spec. The library carries all hardware logic — developer code is a spec file plus thin generated glue (bootstrap + callback dispatch + optional stream consumer) plus handler bodies. " +
-            "Agents plan composition themselves; there is no planning tool. Read the catalog topics below to see what primitives exist, then assemble the smallest spec your goal needs. " +
-            "Catalog topics: trigger_types, action_types, block_types, stream_types, spec_format, template_syntax, toggles, app_callback_guide, library_api, voice_ux_guide, permissions, connection_ui_placement, host_app_scaffold. Each has inline minimal examples sufficient for most specs. " +
-            "Constraint topics: constraints_and_limitations, audio_video_coexistence, spec_validation_rules. " +
-            "**Prerequisite: host app must already exist.** generateConnectionModule scaffolds Extentos INTO an existing Compose / SwiftUI host app — it does not create the host app itself. CLI agents starting from scratch should fetch `searchDocs(topic: 'host_app_scaffold')` first for a complete copy-pasteable Compose / SwiftUI project template; Android Studio / Xcode users can use the New Project wizard instead (Empty Compose Activity for Android, App for iOS). F-R4-5. " +
-            "Mutation tool sequence (deterministic, in order): " +
-            "(1) getPlatformInfo — one call to fetch capability surface (compact: names + tiers, ~2KB) and library version. Default response is compact; pass expand: ['capabilities.full'] for per-primitive params/payload/requires/constraints, or expand: ['schema'] for the raw JSON Schema (rarely needed — validateSpec handles validation). " +
-            "(2) generateConnectionModule — one-shot scaffold (bootstrap + dependencies + empty spec). Surfaces a developerInstructions.Step 1 prompt to ask the dev about ExtentosConnectionPage placement; do not skip it. " +
-            "(3) initSpec — populate the first real spec from primitives you composed. " +
-            "(4) generateConsumer(kind: 'callback') — stub app_callback handlers if your spec uses any. Use kind: 'stream' for stream consumers. " +
-            "(5) validateIntegration — pre-test correctness gate. Re-run after every mutation. " +
-            "(6) createSimulatorSession — provision a browser simulator session to test end-to-end. " +
-            "(7) getEventLog — primary debug tool when a flow misbehaves. Returns the structured event trace for a session: trigger fires, block completions, callback invocations, template-resolution warnings, protocol violations. Filter by 'errors' to surface only warn/error-severity rows; filter by 'triggers' to follow flow execution. If you ever observe 'nothing happens when I fire the trigger' or a callback being called with empty input, ALWAYS call getEventLog before guessing — it's almost always one of: the block timed out (transport.protocol_violation), a template didn't resolve (TemplateUnresolved), or the handler returned an error (callback.completed errorCode). " +
-            "For changes after step 3: inspectIntegration → updateSpec → generateConsumer (if handlers/streams added) → validateIntegration. " +
-            "**Iteration loop — DO NOT mint a new sim per change.** `createSimulatorSession` is get-or-create: it returns the saved sim for this project (status:'resumed') after the first call, not a new one. Three rates of change with different requirements: (a) SPEC edits → updateSpec live-pushes to the running app via spec_updated frame, no rebuild, no remint, response shows liveSessionUpdate.appNotified:true; (b) APP-CODE edits (Kotlin/Swift handlers, custom UI) → rebuild + reinstall, the library reattaches to the same saved sim, no remint; (c) FORCE-FRESH (clean-slate ID rotation) → createSimulatorSession({ resetFresh: true }) OR click 'Reset' on the dashboard at extentos.com/s — backend archives the existing sim, mints a replacement, pushes session_moved to live device sockets. URL-bake apps rebuild once after force-fresh. For agents that can rebuild app code themselves: do it inline. For agents that can't: hand the dev rebuild + reinstall commands; same auto-attach behavior on the other end. Full mechanics in searchDocs(topic: 'simulator_browser_mode') § Iteration model. " +
-            "**Multi-platform projects (Android + iOS = ONE project).** When a developer has both Android and iOS versions of the same app, the dashboard groups them under one project IF the Android `applicationId` matches the iOS bundle identifier (the standard reverse-DNS convention — `com.example.myapp` on both platforms). When they do, calling createSimulatorSession from each project yields the same `projectInstallId`, so the dashboard auto-groups them. When they don't match (mismatched reverse-DNS, or one project predates the manifest), two separate projects appear — the developer can resolve via the dashboard's Danger Zone → Merge action, which moves all sessions from one project into another. Full guidance: searchDocs(topic: 'multi_platform_projects'). " +
-            "Reference library: getExampleSpec returns 8 worked patterns (voice_assistant, live_translation, etc.). On-demand only — read it when studying a complex composition. The catalog topics cover the simple cases without it.",
-        keywords: ["setup", "start", "first", "begin", "overview", "walkthrough", "tool order", "workflow", "catalog", "debug", "iteration", "iteration loop", "rebuild", "live-push", "remint", "dev loop"],
-        relatedTools: ["getPlatformInfo", "generateConnectionModule", "initSpec", "searchDocs", "validateIntegration", "getEventLog", "updateSpec", "createSimulatorSession"],
-    },
-    {
-        topic: "block_types",
-        title: "Block Types",
-        content: "**Blocks are discrete, bounded media-capture operations.** A block is *declared* in spec.blocks[] (with config) and *invoked* from a trigger's actions[] via a `block_call` action. The result is bound to a save_as variable for use in subsequent actions. 3 block types:\n\n" +
-            "─── capture_photo ───\n" +
-            "One-shot still photo from the glasses camera. Tier: dat_native (high confidence).\n\n" +
-            "When to use: voice-driven photo capture ('take a photo', 'describe what you see'), or capture_button-driven photography.\n" +
-            "When NOT to use: continuous frames for ML — use video_frames stream at low fps. Burst capture — call capture_photo multiple times from a flow with delay between, OR use video_frames at 7-15 fps and consume manually.\n\n" +
-            "Required: type, id\n" +
-            "Optional params: resolution ('LOW' | 'MEDIUM' | 'HIGH'), format ('jpeg' | 'heic')\n" +
-            "Returns: { uri, width, height, format }\n\n" +
-            "Field rules:\n" +
-            "- resolution: HIGH adds ~400ms latency on Gen 1 hardware vs MEDIUM. Use LOW for ML inputs that downscale anyway. MEDIUM is the right default.\n" +
-            "- format: 'heic' is ~50% smaller but Android Bitmap pipelines need conversion. 'jpeg' is the universal default.\n\n" +
-            "Constraints:\n" +
-            "- Requires GlassesState == Active. Calling while not Active fails with NotConnected.\n" +
-            "- Camera exclusivity: blocks while outgoing_video stream is active (unless audio_video_coexistence_policy = prefer_video AND resolution = LOW).\n\n" +
-            "Displaying the photo on-device:\n" +
-            "- The `uri` shape varies by transport (`data:image/...;base64,...` in BrowserSim, `file://...` in RealMeta + LocalSim). Don't pass it directly to Coil's `AsyncImage` / SwiftUI's `AsyncImage` — those URL pipelines silently fail on inlined data URIs from BrowserSim. Use the library helper instead: `photo.loadBitmap()` (Android, suspend → `Bitmap?`) or `await photo.loadImage()` (iOS, async → `UIImage?` / `NSImage?`). The helper branches on scheme internally and runs decode off the main thread.\n\n" +
-            "Consuming the photo from an `app_callback` handler (the AI-vision path):\n" +
-            "- The spec convention `input: { image: \"{{photo.uri}}\" }` passes the URI as a **String** to your handler — `call.input.image` is the URI text, not a `Photo` object. The `photo.loadBitmap()` extension is unreachable on this path because there's no String → Photo conversion API. (Same shape applies to capture_video — see capture_video below for `Videos.copyToFile(uri, dst)` etc.)\n" +
-            "- Use the URI-string helpers on `Photos` (top-level object, library 1.1.13-pair+) instead:\n" +
-            "  - `Photos.loadBase64(uri): String?` — bare base64 payload, ready to drop into Anthropic Claude Vision / OpenAI GPT-4V request bodies. Has a fast path for `data:` URIs that skips the decode + re-encode round trip.\n" +
-            "  - `Photos.loadBytes(uri): ByteArray?` — raw image bytes for multipart upload or custom encoders.\n" +
-            "  - `Photos.loadBitmap(uri): Bitmap?` — same Bitmap shape as `photo.loadBitmap()` but takes a URI string.\n" +
-            "  - `Photos.mediaTypeFromUri(uri): String?` — `\"image/jpeg\"` / `\"image/png\"` / `\"image/webp\"` / etc. Best-effort: reads the embedded MIME type from `data:` URIs, infers from the file extension otherwise. Most AI vision APIs require both base64 + media type.\n" +
-            "  - All loaders are suspend, run decode on `Dispatchers.IO`, and return null on missing file / decode failure / OOM. They never throw.\n" +
-            "  - Anthropic Claude Vision shape: `{ \"type\": \"image\", \"source\": { \"type\": \"base64\", \"media_type\": Photos.mediaTypeFromUri(uri), \"data\": Photos.loadBase64(uri) } }`.\n\n" +
-            "Common mistakes:\n" +
-            "- Calling capture_photo in a tight loop expecting frame-rate semantics — use video_frames stream instead. capture_photo has shutter overhead on every call.\n" +
-            "- Setting resolution = HIGH for ML inputs that you'll downscale — wastes capture time and battery.\n" +
-            "- Writing your own `data:` / `file://` URI decoder in the handler before checking for `Photos.loadBase64(uri)` / `Photos.loadBytes(uri)` — the helpers exist exactly to avoid this branch in every AI-vision handler.\n" +
-            "- Reaching for `photo.loadBitmap()` from an `app_callback` handler — the handler receives a String URI, not a Photo. Use `Photos.loadBitmap(uri)` (top-level) instead.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "capture_photo", "id": "main_camera", "params": { "resolution": "MEDIUM", "format": "jpeg" } }\n` +
-            "Then in a trigger:\n" +
-            `  { "type": "block_call", "block_id": "main_camera", "save_as": "photo" } → result available as {{photo}} or {{photo.uri}}\n\n` +
-            "─── capture_video ───\n" +
-            "Bounded video clip with explicit duration. Tier: phone_side_workaround (degraded confidence).\n\n" +
-            "When to use: short demo / share clips up to 60s. Always-bounded — there's no live-stream video capture in Meta DAT, so this is clip-only.\n" +
-            "When NOT to use: continuous video for AR / ML — use video_frames stream. Live broadcasting — not supported on Meta Ray-Ban.\n\n" +
-            "Required: type, id\n" +
-            "Optional params: resolution ('LOW' | 'MEDIUM' | 'HIGH'), max_duration_seconds (max 60, default 10), format ('mp4_hevc' | 'mp4_h264'), include_audio (default false), stop_conditions (array)\n" +
-            "Returns: { uri, duration_ms, format, width, height }  (snake_case — matches the runtime template variable keys; `{{clip.duration_ms}}`, NOT `clip.durationMs`)\n\n" +
-            "Field rules:\n" +
-            "- format: 'mp4_hevc' is HEVC passthrough — fast, no thermal load. 'mp4_h264' triggers MediaCodec re-encode — drops to <5 fps on Gen 1 hardware (issue #44). Use HEVC unless your downstream consumer can't decode it.\n" +
-            "- include_audio = true: forces HFP audio route, killing high-quality A2DP playback for the duration of capture. Default off.\n" +
-            "- max_duration_seconds: do NOT set higher than 30 on battery-constrained sessions; thermal_warning typically fires at moderate severity around 30s of HEVC. Renamed from `duration_seconds` in 1.1.15-pair to match `record_audio.params.max_duration_seconds`. Old `duration_seconds` is no longer accepted; validateSpec emits an additionalProperty error naming the unknown key.\n" +
-            "- stop_conditions: array of `{ type: 'voice_command', phrase: '...' }` entries that end the capture early. The capture returns the partial clip captured up to the stop. Phase 6 only enforces voice_command at runtime; capture_button / tap / double_tap / ai_vision are accepted by the spec parser but no-ops on real hardware (validateIntegration warns). Combine with max_duration_seconds: whichever fires first wins.\n\n" +
-            "Common mistakes:\n" +
-            "- Choosing h264 because 'it's universal' — the encoder choice causes the FPS cliff. Default to hevc.\n" +
-            "- Long clips (60s) without a thermal_warning trigger to downgrade — expect dropped frames and degraded quality past ~30s.\n" +
-            "- Using `duration_seconds` (the pre-1.1.15-pair name) — the schema now requires `max_duration_seconds`. validateSpec's additionalProperty error names the unknown key.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "capture_video", "id": "main_clip", "params": { "max_duration_seconds": 5, "resolution": "MEDIUM", "format": "mp4_hevc" } }\n\n` +
-            "Voice-stoppable (canonical for 'start recording / stop recording' UX):\n" +
-            `  { "type": "capture_video", "id": "main_clip", "params": { "max_duration_seconds": 60, "resolution": "MEDIUM", "format": "mp4_hevc", "include_audio": true, "stop_conditions": [{ "type": "voice_command", "phrase": "stop recording" }] } }\n\n` +
-            "Consuming the video from an `app_callback` handler (the canonical 'save to gallery' path):\n" +
-            "- Same gotcha as capture_photo: spec convention `input: { uri: \"{{clip.uri}}\" }` passes the URI as a **String** to your handler — `call.input.uri` is the URI text, not a typed VideoClip object.\n" +
-            "- Use the `Videos` URI-string helpers (top-level object, library 1.1.14-pair+):\n" +
-            "  - `Videos.copyToFile(uri: String, dst: File): Boolean` — the canonical save-to-gallery path. Streams from `file://` and bare-path sources via `File.copyTo` (memory-bounded regardless of clip length); decodes `data:` URIs in-memory (BrowserSim caps the payload server-side). Creates parent dirs, overwrites existing dst. Returns true on success, false on any failure (no throw).\n" +
-            "  - `Videos.loadBytes(uri: String): ByteArray?` — raw bytes, for AI APIs that take inline video (Gemini 1.5 Pro vision). Loads the whole video into memory — prefer `copyToFile` for >50 MB clips.\n" +
-            "  - `Videos.loadBase64(uri: String): String?` — base64 payload with the same `data:` URI fast path as `Photos.loadBase64`.\n" +
-            "  - `Videos.mediaTypeFromUri(uri: String): String?` — best-effort MIME from `data:` prefix or file extension. Recognized: `.mp4` (`video/mp4`), `.m4v` (`video/x-m4v`), `.mov` (`video/quicktime`), `.webm` (`video/webm`), `.mkv` (`video/x-matroska`), `.avi` (`video/x-msvideo`), `.3gp` (`video/3gpp`).\n" +
-            "  - All loaders are suspend (run on `Dispatchers.IO`), return null/false on missing file / decode failure / OOM. Never throw.\n" +
-            "- Common shape: `val ok = Videos.copyToFile(call.input.jsonObject[\"uri\"]?.jsonPrimitive?.contentOrNull ?: return Error(...), File(galleryDir, \"\\${System.currentTimeMillis()}.mp4\"))`.\n\n" +
-            "─── record_audio ───\n" +
-            "Bounded mic capture from the glasses, auto-transcribed on completion. Tier: phone_side_workaround (degraded confidence).\n\n" +
-            "When to use: voice-note flows ('take a note'), short dictation. STT runs automatically using the platform's on-device recognizer.\n" +
-            "When NOT to use: continuous transcription — use the transcription_incremental stream. Audio-only recording without STT — not exposed; this block always transcribes.\n\n" +
-            "Required: type, id\n" +
-            "Optional params: max_duration_seconds (max 60, default 15), silence_timeout_seconds (max 10, default 2), quality ('standard' | 'high'), stop_conditions (array)\n" +
-            "Returns: { transcript, audio_duration_ms, raw_audio_uri }  (snake_case — matches the runtime template variable keys; `{{note.audio_duration_ms}}`, NOT `note.audioDurationMs`)\n\n" +
-            "Field rules:\n" +
-            "- silence_timeout_seconds: the recording stops automatically when this much silence is detected. Lower for snappy UX (1-2s); raise to 4-5s if users tend to pause.\n" +
-            "- quality: 'high' is misleading — Meta DAT routes the mic over HFP mono 8 kHz. 'high' is effectively the same as 'standard' until A2DP-grade mic capture lands. Treat them as equivalent for now.\n" +
-            "- stop_conditions: array of `{ type: 'voice_command', phrase: '...' }` entries that end the recording early. Whichever fires first wins (max_duration_seconds, silence_timeout_seconds, or any matching phrase). Returns the partial recording captured up to the stop. Phase 6 only enforces voice_command at runtime; other types are accepted by the parser but no-op on real hardware (validateIntegration warns).\n" +
-            "- STT runs on-device via Android SpeechRecognizer / iOS SFSpeechRecognizer — no cloud cost, no developer config required.\n\n" +
-            "Common mistakes:\n" +
-            "- Expecting raw audio for custom STT — the block always returns a transcript. To do custom STT, use the audio_chunks stream + your own ASR.\n" +
-            "- Setting max_duration_seconds = 60 without thermal awareness — works fine, but if the spec also captures video, you'll hit thermal limits faster.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "record_audio", "id": "note_recorder", "params": { "max_duration_seconds": 30, "silence_timeout_seconds": 3, "quality": "standard" } }\n\n` +
-            "── Block result usage ──\n" +
-            "After a block_call action with save_as: 'photo' (or any name), the result is bound to that variable. Reference fields via dot notation in subsequent actions: {{photo.uri}}, {{photo.width}}, {{note.transcript}}, {{clip.duration_ms}}. **Field names are snake_case** to match the runtime payload (`duration_ms`, `audio_duration_ms`, `raw_audio_uri`) — NOT camelCase. validateSpec rule R13 catches camelCase typos like `{{clip.durationMs}}` at validation time. The bare {{photo}} resolves to the URI for capture_photo and capture_video. See template_syntax topic.",
-        keywords: ["block", "capture_photo", "capture_video", "record_audio", "photo", "video", "audio", "capture", "hevc", "h264", "stt"],
-        relatedTools: ["getPlatformInfo", "initSpec", "updateSpec"],
-    },
-    {
-        topic: "stream_types",
-        title: "Stream Types",
-        content: "**Streams are continuous flows of media or events.** A stream is *declared* in spec.streams[] (with config), *gated by a toggle* at runtime, and *consumed by developer code* in ExtentosStreams.{kt,swift} (generated by `generateConsumer(kind: 'stream')`). Direction matters: video_frames / audio_chunks / transcription_incremental are OUTBOUND from glasses; outgoing_video / outgoing_audio are phone→glasses.\n\n" +
-            "5 stream types. All require `generateConsumer(kind: 'stream')` to scaffold the consumer file. Lifecycle is tied to app foreground; on Android 14+ you need FOREGROUND_SERVICE permission and a foregroundServiceType declaration in AndroidManifest.xml.\n\n" +
-            "─── video_frames ───\n" +
-            "Outbound stream of camera frames from the glasses. Tier: dat_native.\n\n" +
-            "When to use: continuous on-device ML (object detection, scene classification). Live preview UI. Anything needing frames > 1/second.\n" +
-            "When NOT to use: one-shot still capture (use capture_photo block). Bounded clips (use capture_video block). Streaming to a remote server (use outgoing_video_stream — different direction).\n\n" +
-            "Required: type, id, config\n" +
-            "Config: resolution ('LOW' | 'MEDIUM' | 'HIGH'), frame_rate (2 | 7 | 15 | 24 | 30), codec ('hvc1' | 'h264'), backpressure ('drop_oldest' | 'drop_newest' | 'suspend')\n\n" +
-            "Field rules:\n" +
-            "- frame_rate × battery: 2 fps for ML workloads (negligible drain). 7-15 fps for preview UI (~1 hr active). 24-30 fps drains battery fast (~30 min); ALWAYS pair with a thermal_throttle preset trigger to downgrade on warning.\n" +
-            "- resolution × ML: LOW is sufficient for most on-device models that downscale anyway. Don't ask for HIGH if you're going to crop and downscale.\n" +
-            "- codec: hvc1 (HEVC) bypasses the MediaCodec FPS cliff — use it. h264 forces re-encode and drops to <5 fps in practice.\n" +
-            "- backpressure: 'drop_oldest' is correct for preview / latest-frame ML. 'drop_newest' for analyses where the historical frame matters more. 'suspend' blocks the producer until consumer drains — only use if your consumer is guaranteed fast.\n\n" +
-            "Common mistakes:\n" +
-            "- 30 fps + HIGH for ML — wastes battery; downscale to 2 fps + LOW and throttle aggressively.\n" +
-            "- No thermal_throttle trigger — 24-30 fps will hit thermal limits within 5 minutes; without a trigger to downgrade, the user just sees a dead session.\n" +
-            "- Forgetting the FOREGROUND_SERVICE manifest entry on Android 14+ — `validateIntegration` flags this; `getPermissions` returns the manifest snippet.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "video_frames", "id": "frames", "config": { "resolution": "LOW", "frame_rate": 2, "codec": "hvc1", "backpressure": "drop_oldest" } }\n\n` +
-            "─── audio_chunks ───\n" +
-            "Outbound stream of raw audio chunks from the glasses mic. Tier: dat_native.\n\n" +
-            "When to use: custom on-device or cloud STT (your own model, not Meta's). Audio analysis (silence detection, voice activity, custom keyword spotting).\n" +
-            "When NOT to use: phrase recognition (use voice_command trigger — Meta's STT is cheaper). Continuous transcription (use transcription_incremental — already STT'd). Voice notes (use record_audio block — bounded + auto-STT).\n\n" +
-            "Required: type, id, config\n" +
-            "Config: chunk_millis (default 20), backpressure ('drop_oldest' | 'drop_newest' | 'suspend')\n\n" +
-            "Field rules:\n" +
-            "- chunk_millis: 20ms is the canonical opus/CELT frame size. Don't change unless your downstream consumer expects something else.\n" +
-            "- 16-chunk buffer cap; slow consumers will drop. Profile your consumer — anything > ~50ms per chunk processing on average will fall behind.\n" +
-            "- Activating audio_chunks routes audio to HFP, dropping any active A2DP playback to mono 8 kHz. Coexistence is governed by audio_video_coexistence_policy toggle.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "audio_chunks", "id": "mic", "config": { "chunk_millis": 20, "backpressure": "drop_oldest" } }\n\n` +
-            "─── transcription_incremental ───\n" +
-            "STT events from the platform recognizer (partial + final transcripts). Tier: phone_side_workaround.\n\n" +
-            "When to use: continuous live transcription (translation app, dictation). The standard 'live captions' shape.\n" +
-            "When NOT to use: one-shot voice-to-text (use record_audio block). Phrase activation (use voice_command trigger). Custom STT model (use audio_chunks stream + your own engine).\n\n" +
-            "Required: type, id, config\n" +
-            "Config: language (BCP-47 tag, e.g., 'en-US'), min_partial_confidence (default 0.4)\n" +
-            "Gated by toggle: transcription_enabled (default false). Set via set_toggle action to start. Fires Transcript.Final and Transcript.Partial events on the consumer Flow.\n\n" +
-            "Field rules:\n" +
-            "- min_partial_confidence: 0.4 is the platform-recommended floor. Partial events are chatty — debounce in your UI consumer if rendering each one to a Composable / SwiftUI view.\n" +
-            "- language: must be a BCP-47 tag. 'en' alone won't work; use 'en-US' or 'en-GB'.\n" +
-            "- Activating transcription_incremental routes audio to HFP same as audio_chunks — A2DP playback drops to mono.\n" +
-            "- Lifecycle: the library auto-restarts the recognizer after each Final transcript (300ms gap on iOS, 100ms on Android) to keep the stream continuous. Developer-visible behavior: an always-on Flow / AsyncStream that never naturally ends until you cancel it. Each Transcript carries `startMs` / `endMs` relative to the current recognition task — they reset to ~0 on each restart, so don't rely on monotonic-across-restarts timing; anchor against your own clock if you need wall-clock alignment.\n" +
-            "- Engine source per transport: phone STT via SCO mic — Android `SpeechRecognizer` (Google STT online) on RealMeta + LocalSim; iOS `SFSpeechRecognizer` (Apple STT online) on RealMeta + LocalSim; Web Speech API → Whisper fallback in BrowserSim. Surface visible in `getEventLog(filter: \"transport\")` as `transport.transcript_emitted.source` ∈ `apple_stt` / `google_stt` / `web_speech_api` / `whisper_browser`.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "transcription_incremental", "id": "live_transcript", "config": { "language": "en-US" } }\n\n` +
-            "─── outgoing_audio_stream ───\n" +
-            "Phone→glasses audio (TTS, voice call audio, music). Tier: dat_native.\n\n" +
-            "When to use: video-call audio. Custom TTS bypassing platform speak. Streaming music or generated audio.\n" +
-            "When NOT to use: simple TTS prompts (use speak_text action — it handles routing). Bounded earcons (use earcon_beep action).\n\n" +
-            "Config: chunk_millis (default 20), codec ('opus' | 'pcm_s16le')\n" +
-            "Field rules:\n" +
-            "- codec: opus for network-sourced audio (compressed). pcm_s16le only for local on-device generation where compression overhead matters.\n\n" +
-            "─── outgoing_video_stream ───\n" +
-            "Phone→glasses video. Tier: phone_side_workaround.\n\n" +
-            "When to use: video-call rendering on the glasses display. Custom AR overlays (limited — no AR display surface on Ray-Ban Gen 1).\n" +
-            "Config: resolution, frame_rate (2|7|15|24|30), codec ('hvc1' | 'h264')\n" +
-            "Field rules:\n" +
-            "- codec: hvc1 (HEVC) passthrough is mandatory for sustained streaming. h264 requires re-encode; thermal_warning will fire moderate severity within 5 minutes.\n\n" +
-            "── Stream consumption ──\n" +
-            "Stream consumers live in `ExtentosStreams.kt` / `ExtentosStreams.swift`, generated by `generateConsumer({ kind: 'stream', streams: [...] })`. The generated file uses Kotlin `Flow.collect {}` (Android) or Swift `for await … in` (iOS). Lifecycle: scope to `lifecycle` (recommended — auto-cancels on app teardown) or `connection` (only collects while glasses are Active). Toggles gate the actual data flow; set the toggle from a manual_launch trigger or from app code via `glasses.toggles.put(...)`.",
-        keywords: ["stream", "video_frames", "audio_chunks", "transcription", "outgoing_audio", "outgoing_video", "flow", "asyncstream", "backpressure", "continuous", "hevc", "battery"],
-        relatedTools: ["getPlatformInfo", "generateConsumer", "getPermissions"],
-    },
-    {
-        topic: "trigger_types",
-        title: "Trigger Types",
-        content: "**Triggers fire flows.** A spec contains 0+ triggers; each describes a stimulus + an `actions[]` flow that runs on every fire. 13 trigger types grouped by stimulus class:\n\n" +
-            "- VOICE: voice_command, wake_word, push_to_talk, fallback\n" +
-            "- HARDWARE: hinges_closed, thermal_warning, audio_route_changed\n" +
-            "- LIFECYCLE: manual_launch, connection_state_changed, app_lifecycle_changed\n" +
-            "- PHONE: phone_notification_forwarded, incoming_call_detected, location_updated\n\n" +
-            "**Future trigger types — not yet in the schema:** `capture_button`, `tap`, `double_tap` (the glasses' physical capture button + touchpad). Today these exist only as block-level stop conditions (e.g. `stop_conditions: [{ type: \"capture_button\" }]` to end a recording on button press). Validating a spec with `{ \"type\": \"capture_button\", \"actions\": [...] }` as a standalone trigger fails `validateSpec R6` (trigger type not supported). When Meta DAT exposes them as third-party trigger surfaces, Extentos will add them as standalone triggers without spec migration.\n\n" +
-            "Per-primitive reference below. Each entry: when to use → required → optional → field rules → common mistakes → minimal example.\n\n" +
-            "─── voice_command ───\n" +
-            "Fire on a phrase match in STT output. The most common trigger for host-app callbacks ('delete all notes', 'take a photo', 'translate this').\n\n" +
-            "When to use: phone-app integration via a memorable phrase. Most third-party integrations of glasses use this trigger to call back into the host app's existing logic via app_callback.\n" +
-            "When NOT to use: single-word triggers ('start', 'go') — use wake_word with a custom Picovoice model. Continuous transcription — use stream type transcription_incremental fed by a manual_launch.\n\n" +
-            "Required: type, phrase, actions\n" +
-            "Optional: id, match_mode (default 'contains'), min_confidence (default 0.5), mode (default 'single')\n\n" +
-            "Field rules:\n" +
-            "- phrase: 3+ syllables for STT reliability. Avoid digits ('say two' — STT rarely round-trips '2'), homophones (two/to/too, four/for, here/hear, no/know, sea/see, right/write), and Meta wake words ('hey meta', 'ok meta', 'hey facebook' — reserved for Meta AI). Named captures via {{name}} must be the FINAL token in the phrase ('translate {{text}}' not '{{text}} please'). **Apostrophes, trailing punctuation, case, and whitespace runs are normalized automatically** — both `whats my move` and `what's my move` (and the STT output `What's my move?`) collapse to the same key and match identically. Write whichever spec phrase reads naturally; the matcher lowercases, drops anything that is not a letter/digit/whitespace, and collapses whitespace before comparison.\n" +
-            "- match_mode: 'contains' (default) tolerates STT filler words ('um', 'okay') prepended/appended — almost always the right choice. 'exact' requires verbatim match — use only for short single-token phrases. 'starts_with' is brittle because STT prepends filler — prefer 'contains'.\n" +
-            "- min_confidence: 0.5 works for clean speech. Drop to 0.3 in noisy environments (more false positives). Raise to 0.7 for destructive flows ('delete everything').\n" +
-            "- mode: 'single' (default) ignores fires while a flow runs. 'restart' cancels in-flight on new fire (use for 'stop listening'-style toggles). 'queued' buffers up to 3 (use for 'save note' where users may rapid-fire).\n" +
-            "- Recognition source: phone STT via SCO mic, never the glasses DSP. Android SpeechRecognizer (Google STT online); iOS SFSpeechRecognizer (Apple STT online); BrowserSim uses Web Speech API → Whisper fallback. Confidence calibration varies between engines, so a phrase that fires reliably at 0.5 in BrowserSim may need a different threshold on RealMeta — check `getEventLog(filter: 'transport')` for `transport.transcript_emitted` events that show what each recognizer produced before the matcher saw it.\n\n" +
-            "Common mistakes:\n" +
-            "- Single-word phrase ('delete') — STT will mishear; require 3+ syllables.\n" +
-            "- Numeric phrase ('set timer to 5') — write 'set timer to five' and parse the spelled number in your handler.\n" +
-            "- Two triggers whose phrases are homophones ('note' / 'no') — both will fire on either utterance.\n\n" +
-            "Minimal:\n" +
-            `  {\n` +
-            `    "type": "voice_command",\n` +
-            `    "id": "t_my_phrase",\n` +
-            `    "phrase": "do the thing",\n` +
-            `    "match_mode": "contains",\n` +
-            `    "actions": [\n` +
-            `      { "type": "app_callback", "handler": "do_the_thing", "input": {}, "save_as": "result" },\n` +
-            `      { "type": "speak_text", "text": "Done." }\n` +
-            `    ]\n` +
-            `  }\n\n` +
-            "─── wake_word ───\n" +
-            "Fire on a custom on-device wake word (always-listening, low-power).\n\n" +
-            "When to use: short single-word activator that has to work without prior phrase ('hey assistant', 'computer'). Continuous always-listening UX where voice_command's STT cost is too high.\n" +
-            "When NOT to use: phrase-based triggers (use voice_command). Anything Meta's reserved wake words ('hey meta', 'hey facebook', 'ok meta') — those are not exposed to third-party apps.\n\n" +
-            "Required: type, phrase (built-in or path to a custom Picovoice model), actions\n" +
-            "Requires: microphone permission + Picovoice access key for custom models.\n\n" +
-            "─── push_to_talk ───\n" +
-            "Fire when the user holds a host-app button while speaking; commits on release.\n\n" +
-            "When to use: explicit voice capture without keyword cost. The host app provides only the BUTTON; audio source is glasses-side, STT runs at the transport layer (browser-side in BrowserSim, glasses mic in RealMeta). The host app never handles raw audio.\n" +
-            "Required: type, actions. Payload exposes transcript and rawUtterance.\n\n" +
-            "Wiring — recommended path uses `audio.startPushToTalk()`, which wraps the subscribe / accumulate Final / cancel-and-flush lifecycle so the host app only handles press / release:\n\n" +
-            "Android:\n" +
-            `  // onPress (e.g., a Compose pointerInput onPress)\n` +
-            `  val session = glasses.audio.startPushToTalk(scope)\n` +
-            `\n` +
-            `  // onRelease (suspend context — coroutine on the same scope)\n` +
-            `  val text = session.stopAndFlush()\n` +
-            `  glasses.runtime.fireTrigger(\n` +
-            `      triggerId = "<your_trigger_id>",\n` +
-            `      payload = mapOf(\n` +
-            `          "transcript" to JsonPrimitive(text),\n` +
-            `          "rawUtterance" to JsonPrimitive(text),\n` +
-            `      ),\n` +
-            `  )\n\n` +
-            "iOS:\n" +
-            `  // onPress\n` +
-            `  let session = glasses.audio.startPushToTalk()\n` +
-            `\n` +
-            `  // onRelease (Task)\n` +
-            `  let text = await session.stopAndFlush()\n` +
-            `  await glasses.runtime.fireTrigger(\n` +
-            `      triggerId: "<your_trigger_id>",\n` +
-            `      payload: .object([\n` +
-            `          "transcript": .string(text),\n` +
-            `          "rawUtterance": .string(text),\n` +
-            `      ])\n` +
-            `  )\n\n` +
-            "Under the hood the helper subscribes to `audio.transcriptions()` (the same stream the rest of the library uses) and accumulates `Transcript.Final` segments; `stopAndFlush()` cancels the subscription and returns the joined text. Audio source is glasses-side on both platforms — no phone mic permission, no `SpeechRecognizer` / `SFSpeechRecognizer` involvement, works identically on emulator and real hardware. The trigger's `actions[]` flow then runs with `{{trigger_payload.transcript}}` available for app_callback inputs.\n\n" +
-            "Common mistakes:\n" +
-            "- Reaching for Android `SpeechRecognizer` or iOS `SFSpeechRecognizer` directly — bypasses the library, doesn't work in BrowserSim (the emulator mic doesn't deliver audio to platform STT), and rebuilds what `audio.startPushToTalk()` already wraps.\n" +
-            "- Confusing this with the `record_audio` BLOCK — that's silence-timeout-committed (good for record-then-pause), not press-and-hold UX.\n" +
-            "- Manually wiring `audio.transcriptions().collect { ... }` + `cancelAndJoin` + a buffer when the helper exists — the ad-hoc version was the canonical pattern before `startPushToTalk()` shipped, but it's now boilerplate.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "push_to_talk", "id": "t_record_note", "actions": [{ "type": "app_callback", "handler": "save_voice_note", "input": { "transcript": "{{trigger_payload.transcript}}" }, "save_as": "result" }, { "type": "earcon_beep", "sound": "confirmation" }] }\n\n` +
-            "─── fallback ───\n" +
-            "Catches any unrecognized voice utterance that didn't match a voice_command. Max 1 per spec.\n\n" +
-            "When to use: graceful 'sorry, I didn't catch that' UX. Always include if the spec has any voice_command.\n" +
-            "Required: type, actions. No phrase — it matches by exclusion.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "fallback", "id": "t_fallback", "actions": [{ "type": "speak_text", "text": "Sorry, I didn't catch that." }] }\n\n` +
-            "─── manual_launch ───\n" +
-            "Fires when the host app calls `glasses.runtime.fireTrigger(\"<your_trigger_id>\")` — typically from a button or other host-side affordance.\n\n" +
-            "When to use: explicit start of a session-bound flow ('start translation mode', 'begin recording'). Often paired with a set_toggle action to flip transcription_enabled on.\n" +
-            "Required: type, actions. No payload required at the spec level — payload comes from the host app's `fireTrigger` call (optional Map<String, JSONValue>).\n\n" +
-            "Wiring: the host app reaches its ExtentosGlasses instance (same one created in ExtentosBootstrap) and calls `glasses.runtime.fireTrigger(\"t_start\")` from a coroutine context. The actions[] flow runs immediately. Identical API on iOS.\n\n" +
-            "Common mistakes:\n" +
-            "- Looking for `runtime.invokeManualLaunch()` — that method does NOT exist. The unified API for `manual_launch` is `runtime.fireTrigger(triggerId, payload)`. (For `push_to_talk` the recommended path is `audio.startPushToTalk()` + `session.stopAndFlush()`, which wraps the transcript collection then calls `fireTrigger` for you — see the push_to_talk section above.)\n\n" +
-            "Minimal:\n" +
-            `  { "type": "manual_launch", "id": "t_start", "actions": [{ "type": "set_toggle", "key": "transcription_enabled", "value": true }] }\n\n` +
-            "─── hinges_closed ───\n" +
-            "Fires when the glasses' hinges close (user takes them off).\n" +
-            "When to use: pause-on-removal UX, save-state on close. Pair with set_toggle to disable streams.\n\n" +
-            "─── thermal_warning ───\n" +
-            "Fires on device thermal-state escalation. Severity: 'light' | 'moderate' | 'severe' | 'critical'.\n\n" +
-            "When to use: protect battery + extend session — listen for severity 'moderate' or higher and downgrade quality. Most camera/streaming specs include a thermal_warning trigger that flips battery_save_mode on. The `thermal_throttle` preset on initSpec auto-injects this.\n" +
-            "Required: type, severity, actions.\n\n" +
-            "─── connection_state_changed ───\n" +
-            "Fires on glasses-connection-state transitions. Use on_transition.from / on_transition.to to gate on specific transitions.\n\n" +
-            "When to use: announce connect/disconnect, persist state across reconnects. The `disconnect_announce` preset on initSpec auto-injects a sensible default.\n" +
-            "Payload: from, to, cause (all GlassesState bucket strings).\n\n" +
-            "─── audio_route_changed ───\n" +
-            "Fires when audio routing changes (BT pairing/unpairing, A2DP↔HFP swap).\n" +
-            "Payload: from, to. Useful for graceful audio-mode handoff.\n\n" +
-            "─── phone_notification_forwarded ───\n" +
-            "Fires when a phone notification matching the app's filter is forwarded to glasses TTS.\n\n" +
-            "Payload: packageName, title, body.\n" +
-            "Requires: Android BIND_NOTIFICATION_LISTENER_SERVICE (user-granted at runtime); iOS UNUserNotificationCenter delegate (system notifications only — third-party app banners not accessible).\n\n" +
-            "─── incoming_call_detected ───\n" +
-            "Fires when an incoming phone call is detected.\n" +
-            "Payload: callerNumber, callerName.\n" +
-            "Requires: Android READ_PHONE_STATE permission; iOS CallKit observer.\n\n" +
-            "─── location_updated ───\n" +
-            "Fires periodically with current GPS coordinates. Throttle via min_interval_millis + min_displacement_meters to control battery cost.\n\n" +
-            "Required: type, actions.\n" +
-            "Optional: min_interval_millis (default 5000), min_displacement_meters (default 10).\n" +
-            "Payload: latitude, longitude, accuracyMeters.\n" +
-            "Requires: ACCESS_FINE_LOCATION (Android) or NSLocationWhenInUseUsageDescription (iOS).\n\n" +
-            "─── app_lifecycle_changed ───\n" +
-            "Fires when the host app's lifecycle state changes ('foreground' / 'background' / 'destroyed').\n" +
-            "Use to pause streaming or save state when backgrounded.\n\n" +
-            "── Presets ──\n" +
-            "Three canned trigger shapes can be auto-injected via initSpec.presetTriggers: 'fallback_default' (a fallback trigger with sensible 'sorry' speech), 'thermal_throttle' (thermal_warning trigger flipping battery_save_mode), 'disconnect_announce' (connection_state_changed announcer). Pass the preset names to initSpec; do not duplicate the trigger shape manually if you use the preset.",
-        keywords: ["trigger", "voice_command", "tap", "capture_button", "wake_word", "fallback", "notification", "thermal", "preset", "phrase", "match_mode", "homophone"],
-        relatedTools: ["getPlatformInfo", "getVoiceCommandGuidance", "updateSpec"],
-    },
-    {
-        topic: "action_types",
-        title: "Action Types",
-        content: "**Actions are steps inside a trigger's flow.** Each trigger's actions[] runs sequentially when the trigger fires. Actions can be flat or nested via control-flow actions (branch, when_connected, retry_with_backoff). 15 action types grouped by purpose:\n\n" +
-            "- HOST-APP BRIDGE: app_callback (the most important — calls into developer code)\n" +
-            "- MEDIA: block_call, speak_text, earcon_beep\n" +
-            "- STATE: set_toggle, set_variable\n" +
-            "- CONTROL FLOW: branch, when_connected, retry_with_backoff, buffer_and_replay, delay, abort, ask_user\n" +
-            "- DIAGNOSTICS: log\n\n" +
-            "─── app_callback ───\n" +
-            "**The single most important action.** Routes flow control from the spec into the developer's native code. This is how 'voice phrase → my app does the thing' works.\n\n" +
-            "When to use: ANY time the spec needs to invoke domain logic that lives in the host app — DB writes, AI calls, repository ops, navigation, file IO, network requests, anything that's not a stock primitive. Always wrap arbitrary host-app behavior in an app_callback rather than trying to express it as composed primitives.\n" +
-            "When NOT to use: pure spec-side state changes (use set_toggle / set_variable). Stock TTS (use speak_text). Capturing media (use block_call).\n\n" +
-            "Required: type, handler (string — the handler name registered in ExtentosCallbacks)\n" +
-            "Optional: input (object — payload passed to the handler; values support {{template}} substitution from prior save_as variables), save_as (variable name to capture the handler's return value)\n\n" +
-            "Field rules:\n" +
-            "- handler: must match a name passed to generateConsumer(kind: 'callback'). Generated stub lives in `ExtentosCallbacks.kt`/`.swift` with USER-CODE markers; the developer fills in the body.\n" +
-            "- input: keys are arbitrary, values can be literals OR {{template}} references to prior save_as outputs. Example: `{ image: '{{photo.uri}}', prompt: 'Describe this scene.' }`.\n" +
-            "- save_as: the handler's `Success` payload becomes a variable accessible as `{{result}}` (or `{{result.field}}`). The handler's `Error` short-circuits the flow.\n" +
-            "- Timeouts surface as 'callback.timeout' events on the runtime event log.\n\n" +
-            "Common mistakes:\n" +
-            "- Forgetting to call `generateConsumer({ kind: 'callback', handlers: [...] })` after adding a new app_callback — the spec validates fine, but at runtime the handler is missing and the flow errors.\n" +
-            "- Passing `suggestedProvider` to generateConsumer for non-AI handlers — the generated comment will say 'wire your AI provider client here', misleading. Only pass suggestedProvider when the handler actually wraps an AI API.\n" +
-            "- Trying to express sequential domain logic as multiple app_callback calls when one handler with branching logic would be cleaner. The spec is for hardware orchestration; complex business logic belongs inside the handler.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "app_callback", "handler": "clear_notes", "input": {}, "save_as": "result" }\n\n` +
-            "With templated input from a prior block_call:\n" +
-            `  { "type": "app_callback", "handler": "describe_image", "input": { "image": "{{photo.uri}}" }, "save_as": "description" }\n\n` +
-            "─── block_call ───\n" +
-            "Invoke a declared block (capture_photo, capture_video, record_audio).\n\n" +
-            "Required: type, block_id (must reference an id from spec.blocks[])\n" +
-            "Optional: save_as (capture the block's return value as a variable)\n\n" +
-            "Minimal:\n" +
-            `  { "type": "block_call", "block_id": "main_camera", "save_as": "photo" }\n\n` +
-            "─── speak_text ───\n" +
-            "TTS via the platform speech synthesizer. Routes audio output appropriately based on coexistence policy.\n\n" +
-            "Required: type, text (string — supports {{template}} substitution)\n\n" +
-            "Field rules:\n" +
-            "- text: keep under ~140 characters for snappy UX. Long TTS is interrupting and battery-expensive.\n" +
-            "- Calling speak_text while transcription_enabled is on routes audio to HFP — the user briefly loses A2DP music if any.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "speak_text", "text": "Done." }\n` +
-            `  { "type": "speak_text", "text": "Hello {{user.name}}." }\n\n` +
-            "─── earcon_beep ───\n" +
-            "Short audio cue (canned sounds, no synthesis). Cheaper and faster than speak_text for confirmations.\n\n" +
-            "Required: type, sound ('confirmation' | 'error' | 'notification' | 'start' | 'stop')\n" +
-            "Optional: volume (0.0-1.0, default 0.6)\n\n" +
-            "─── set_toggle ───\n" +
-            "Mutate a runtime toggle (transcription_enabled, camera_streaming_enabled, privacy_mode, etc.). See `toggles` topic for the 8 toggle keys.\n\n" +
-            "Required: type, key, value\n\n" +
-            "Common mistakes:\n" +
-            "- Toggling transcription_enabled without first declaring a transcription_incremental stream — the toggle has no effect.\n" +
-            "- Setting privacy_mode true and forgetting to unset it later — privacy_mode suppresses ALL captures until cleared.\n\n" +
-            "Minimal:\n" +
-            `  { "type": "set_toggle", "key": "transcription_enabled", "value": true }\n\n` +
-            "─── set_variable ───\n" +
-            "Write a flow-scoped variable. Use for synthesized values (counters, computed flags) that subsequent actions reference.\n\n" +
-            "Required: type, name, value (literal or {{template}})\n" +
-            "Variables are flow-scoped — they live for the duration of a single trigger fire and don't persist across fires (use set_toggle for cross-fire state).\n\n" +
-            "─── branch ───\n" +
-            "Conditional execution. The single control-flow primitive — there is no `if`/`else` outside branch.\n\n" +
-            "Required: type, condition, then[]\n" +
-            "Optional: else[]\n\n" +
-            "Condition shape: `{ variable: '<dotted.path>', operator: '<op>', value?: <literal> }`\n" +
-            "Operators: 'equals', 'not_equals', 'is_empty', 'not_empty', 'greater_than', 'less_than'\n\n" +
-            "Field rules:\n" +
-            "- variable: dotted path to a save_as'd value or a {{trigger_payload.x}} field. Examples: 'result.description', 'note.transcript', 'toggles.privacy_mode', 'trigger_payload.captures.query'.\n" +
-            "- Branch depth: max 1 — `then` and `else` arms cannot contain another `branch`. validateSpec rejects nested branches with `branch is nested inside another branch; max depth is 1.` (R9 enforcement at validateSpec.ts:336). If you need deeper branching, the logic should move into an app_callback handler that returns a discriminator + a single branch on the discriminator.\n\n" +
-            "Common mistakes:\n" +
-            "- Comparing a typed value with a string literal: `{ variable: 'count', operator: 'equals', value: '5' }` when count is a number — use the numeric literal `value: 5`.\n" +
-            "- Nesting branches more than 1 deep — refactor into an app_callback handler that returns a discriminator + a single branch on the discriminator.\n\n" +
-            "Minimal:\n" +
-            `  {\n` +
-            `    "type": "branch",\n` +
-            `    "condition": { "variable": "result.description", "operator": "is_empty" },\n` +
-            `    "then": [{ "type": "speak_text", "text": "No result." }],\n` +
-            `    "else": [{ "type": "speak_text", "text": "{{result.description}}" }]\n` +
-            `  }\n\n` +
-            "─── when_connected ───\n" +
-            "Wraps an action that should only run while glasses are Active. If not connected, optionally waits with timeout.\n\n" +
-            "Required: type, action (the wrapped action)\n" +
-            "Optional: timeout_seconds\n\n" +
-            "Use when: a flow can be fired by phone-side logic before the glasses are connected (e.g., manual_launch from a phone UI button) and you want graceful deferral.\n\n" +
-            "─── retry_with_backoff ───\n" +
-            "Retries an action (typically app_callback) on failure with exponential backoff.\n\n" +
-            "Required: type, action\n" +
-            "Optional: max_attempts (default 3), initial_delay_seconds (default 1)\n\n" +
-            "Field rules:\n" +
-            "- Succeeds when the wrapped action populates its save_as. Failure paths bubble up to flow termination unless caught by a branch.\n" +
-            "- Use sparingly — most flows should fail fast; only retry idempotent ops (network reads, etc.).\n\n" +
-            "─── buffer_and_replay ───\n" +
-            "Delays action execution until glasses connect, replaying buffered actions in order.\n" +
-            "Niche — use when_connected for the common case.\n\n" +
-            "─── delay ───\n" +
-            "Pause flow execution for N seconds.\n\n" +
-            "Required: type, seconds (number > 0 and ≤ 3600, literal only — not templated)\n\n" +
-            "Two legitimate patterns, with very different sane ranges:\n" +
-            "1. **Response delay** — short pause between actions in a single user-facing flow (e.g., between two speak_text actions). Keep ≤ 5s; users expect glasses to feel instant.\n" +
-            "2. **Session timeout / window** — bound a longer-running mode like auto-stop transcription after 30s, daily reminder window, etc. Up to 3600s is fine here. Common shape: `[set_toggle on, delay 30, branch on toggle state, set_toggle off]` so a stop-trigger can short-circuit by flipping the toggle off mid-window.\n\n" +
-            "Field rules:\n" +
-            "- seconds must be a number literal — `{{some_var}}` is rejected. If you need dynamic delay, compute it in an app_callback handler.\n" +
-            "- A delay action blocks the trigger's flow until it elapses. With trigger.mode='single' (default), other fires of the SAME trigger are ignored during the delay. To allow re-firing mid-window, use mode='restart' (cancels the in-flight flow on re-fire).\n" +
-            "- delay cannot be cancelled by another trigger's flow. If you need a 'stop' trigger to abort an in-flight delay, the canonical pattern is the toggle-gated branch shown above — the long flow's later actions check the toggle state and no-op if the stop trigger flipped it off.\n\n" +
-            "─── abort ───\n" +
-            "Terminates the flow immediately. Use for early-exit on error conditions inside a branch's then[].\n\n" +
-            "─── ask_user ───\n" +
-            "Voice Q&A: speaks the `question` via TTS, captures the user's spoken response into `save_as`. **NOT for LLM calls** — the action's name says what it does (ask the user). For LLM/AI calls, use `app_callback` with a developer-implemented handler (the `prompt` field of that handler's input is the natural-sense LLM prompt).\n" +
-            "Required: type, question, save_as\n" +
-            "Optional: timeout_seconds (default 5, max 30), min_confidence (default 0.4)\n\n" +
-            "─── log ───\n" +
-            "Emit a structured log event into the runtime event log (visible in getEventLog).\n\n" +
-            "Required: type, level ('debug' | 'info' | 'warning' | 'error'), message (supports {{template}})\n" +
-            "Use to mark flow milestones for diagnostics — particularly useful inside branch arms to trace which path executed.\n\n" +
-            "── Composition pattern ──\n" +
-            "The canonical 'voice phrase → host app → response' shape:\n" +
-            `  { "type": "app_callback", "handler": "my_handler", "input": { ... }, "save_as": "result" },\n` +
-            `  { "type": "branch",\n` +
-            `    "condition": { "variable": "result.ok", "operator": "equals", "value": true },\n` +
-            `    "then": [{ "type": "speak_text", "text": "{{result.message}}" }],\n` +
-            `    "else": [{ "type": "speak_text", "text": "Sorry, that failed." }]\n` +
-            `  }\n\n` +
-            "The canonical 'photo + AI → speak result' shape:\n" +
-            `  { "type": "block_call", "block_id": "main_camera", "save_as": "photo" },\n` +
-            `  { "type": "app_callback", "handler": "describe_image", "input": { "image": "{{photo.uri}}" }, "save_as": "description" },\n` +
-            `  { "type": "speak_text", "text": "{{description.text}}" }\n`,
-        keywords: ["action", "block_call", "app_callback", "branch", "retry", "speak", "set_toggle", "set_variable", "delay", "log", "earcon", "ask_user", "prompt", "host-app", "callback"],
-        relatedTools: ["updateSpec", "generateConsumer"],
+        content: "Extentos is a pure Kotlin/Swift SDK for adding Meta Ray-Ban glasses features to an existing mobile app. The customer writes normal app code that calls `glasses.audio.X`, `glasses.camera.X`, etc. directly — no spec language, no DSL, no triggers/actions/blocks, no callback dispatch. The library bridges hardware; the customer's code is the application logic.\n\n" +
+            "**Prerequisite: host app must already exist.** `generateConnectionModule` scaffolds Extentos INTO an existing Compose / SwiftUI host app — it does not create the host app itself. CLI agents starting from scratch should fetch `searchDocs(topic: 'host_app_scaffold')` first for a copy-pasteable Compose / SwiftUI project template; Android Studio / Xcode users can use the New Project wizard.\n\n" +
+            "**Tool sequence (deterministic, in order):**\n\n" +
+            "(1) `getPlatformInfo` — fetch capability surface (compact: feature names + categories + tiers, ~2KB) and library version. The `features` list is the SDK's vocabulary: `capture_photo`, `record_audio`, `transcription_incremental`, `voice_command`, etc. Use these names in subsequent tool calls.\n\n" +
+            "(2) `generateConnectionModule` — one-shot scaffold (bootstrap + dependencies + connection-page wiring). Surfaces a developerInstructions Step 1 prompt to ask the dev about `ExtentosConnectionPage` placement; do not skip it.\n\n" +
+            "(3) Write the handler code in Kotlin/Swift directly. Two tools help you compose against the SDK correctly:\n" +
+            "    - `getCodeExample(pattern)` — full canonical compositions in both languages (voice_qa_assistant for the multi-turn wake+question+LLM+speak flow, barge_in_speak for cancel-TTS-on-interrupt, photo_describe_voice for voice-activated vision, live_transcription_ui for transcripts into UI state, voice_notes for wake+record+save, connection_page_setup for bootstrap wiring). Peel from these; don't copy whole.\n" +
+            "    - `getCapabilityGuide(feature)` — per-feature minimal usage + gotchas. Pair with getPlatformInfo: features tells you what exists, getCapabilityGuide tells you how to call it.\n" +
+            "    Or read `searchDocs(topic: 'custom_handlers')` for the conceptual framing (you write a class that subscribes to SDK Flows and calls SDK methods — no spec runtime, no callback dispatch).\n\n" +
+            "(4) `getPermissions({ capabilities: [...], platform })` — derive Android permissions / iOS Info.plist keys / Meta DAT scopes from the features the app uses. Apply manifestEntries to AndroidManifest.xml or plistKeys to Info.plist. Run again whenever the capability set changes.\n\n" +
+            "(5) `validateIntegration` — pre-test correctness gate. Checks manifest, generated files, dependency, permissions vs declared capabilities, bootstrap wiring, toolchain versions. Re-run after every mutation.\n\n" +
+            "(6) `createSimulatorSession` — provision a browser simulator session to test end-to-end. Get-or-create: same sim resumes on subsequent calls.\n\n" +
+            "(7) `getEventLog` — primary debug tool. Returns the structured event trace for a session: stream lifecycle, toggle changes, connection state transitions, transport errors. Filter by 'errors' for warn/error rows; filter by 'transport' for connection/protocol layer.\n\n" +
+            "**Iteration loop — DO NOT mint a new sim per change.** `createSimulatorSession` is get-or-create: it returns the saved sim for this project (`status:'resumed'`) after the first call. Two rates of change:\n" +
+            "(a) APP-CODE edits (Kotlin/Swift) → rebuild + reinstall, the library reattaches to the same saved sim, no remint.\n" +
+            "(b) FORCE-FRESH (clean-slate ID rotation) → `createSimulatorSession({ resetFresh: true })` OR click 'Reset' on the dashboard at extentos.com/s.\n" +
+            "URL-bake apps rebuild once after force-fresh. For agents that can rebuild app code themselves: do it inline. Otherwise hand the dev rebuild + reinstall commands; same auto-attach behavior on the other end. Full mechanics in `searchDocs(topic: 'simulator_browser_mode')`.\n\n" +
+            "**Multi-platform projects (Android + iOS = ONE project).** When a developer has both Android and iOS versions of the same app, the dashboard groups them under one project IF the Android `applicationId` matches the iOS bundle identifier (standard reverse-DNS convention). When they don't match, two separate projects appear — resolve via dashboard's Danger Zone → Merge. Full guidance: `searchDocs(topic: 'multi_platform_projects')`.\n\n" +
+            "**Production:** `getProductionChecklist({ capabilities, handlers, platform })` for a personalized readiness gate. `getCredentialGuide({ services, platform })` for BYOK provider setup (Anthropic / OpenAI / Gemini / etc.) plus Meta DAT registration.",
+        keywords: ["setup", "start", "first", "begin", "overview", "walkthrough", "tool order", "workflow", "catalog", "debug", "iteration", "rebuild", "remint", "dev loop", "sdk", "pure-sdk"],
+        relatedTools: ["getPlatformInfo", "generateConnectionModule", "searchDocs", "validateIntegration", "getEventLog", "createSimulatorSession", "getPermissions", "getProductionChecklist", "getCredentialGuide"],
     },
     {
         topic: "voice_ux_guide",
         title: "Voice Command UX",
-        content: "Phrases should be 3+ syllables, free of homophones, free of digits (STT rarely round-trips them). Named captures {{query}} must be the final token. Provide 3+ alternates for natural paraphrase. Avoid Meta wake words (hey meta, hey facebook, ok meta) — they conflict with on-device Meta AI. Default match_mode \"contains\" tolerates paraphrase; if you set match_mode: \"exact\", add 3+ alternates.\n\n" +
-            "**Apostrophes, punctuation, case, and whitespace are normalized automatically.** The matcher lowercases both the spec phrase and the STT transcript, drops anything that is not a letter / digit / whitespace (apostrophes, periods, question marks, commas, etc.), and collapses whitespace runs before comparison. So `whats my move`, `what's my move`, and the STT output `What's my move?` all collapse to `whats my move` and match identically. Write whichever spec phrase reads naturally; both forms work, and you don't need to add alternates just to cover the apostrophe form.\n\n" +
-            "Run candidate phrases through `getVoiceCommandGuidance` to surface UX issues (homophones, syllable count, captures-not-at-end, etc.) before adding them.",
-        keywords: ["voice", "phrase", "command", "homophone", "capture", "stt", "disambiguation", "alternate", "contraction", "apostrophe", "normalization", "punctuation"],
-        relatedTools: ["getVoiceCommandGuidance", "updateSpec"],
-    },
-    {
-        topic: "spec_format",
-        title: "Spec Format",
-        content: "Top-level: extentos_version ('1.0'), target.vendor ('meta_rayban'), blocks[], streams[], triggers[]. Each block/stream/trigger has a unique id. Triggers declare a type, optional id, and an actions[] array. Spec file lives at app/src/main/assets/extentos.spec.json (Android) or Resources/extentos.spec.json (iOS), byte-identical across platforms.\n\n" +
-            "Minimal valid spec — voice phrase that calls back into the host app (the smallest useful shape):\n" +
-            `  {\n` +
-            `    "$schema": "extentos://schema/v1",\n` +
-            `    "extentos_version": "1.0",\n` +
-            `    "target": { "vendor": "meta_rayban" },\n` +
-            `    "blocks": [],\n` +
-            `    "streams": [],\n` +
-            `    "triggers": [\n` +
-            `      {\n` +
-            `        "type": "voice_command",\n` +
-            `        "id": "t_my_phrase",\n` +
-            `        "phrase": "do the thing",\n` +
-            `        "match_mode": "contains",\n` +
-            `        "actions": [\n` +
-            `          { "type": "app_callback", "handler": "do_the_thing", "input": {}, "save_as": "result" },\n` +
-            `          { "type": "speak_text", "text": "Done." }\n` +
-            `        ]\n` +
-            `      }\n` +
-            `    ]\n` +
-            `  }\n\n` +
-            "Add blocks[] entries when capturing photo/video/audio. Add streams[] entries for continuous flows (transcription, video frames). See block_types, stream_types, trigger_types, action_types for inline examples of each. To MUTATE an existing spec via updateSpec, see spec_operations for the 13 patch operation shapes.",
-        keywords: ["spec", "format", "structure", "extentos_version", "target", "schema", "top-level"],
-        relatedTools: ["validateSpec", "initSpec", "updateSpec", "inspectIntegration"],
-    },
-    {
-        topic: "spec_operations",
-        title: "Spec Operations (updateSpec patch types)",
-        content: "**updateSpec applies an ordered list of structured patch operations to an existing spec.** Each operation is one mutation; failed ops are reported in `skipped[]` and the rest still apply. **13 operation types** organized by target:\n\n" +
-            "BLOCKS: addBlock, removeBlock, updateBlock\n" +
-            "STREAMS: addStream, removeStream, updateStream\n" +
-            "TRIGGERS: addTrigger, removeTrigger, updateTrigger\n" +
-            "ACTIONS (inside a trigger's flow): addAction, removeAction, updateAction\n" +
-            "METADATA: updateMeta\n\n" +
-            "Common shape: `{ \"op\": \"<name>\", ...fields }`. Per-op field rules + canonical examples below.\n\n" +
-            "─── addBlock / addStream / addTrigger ───\n" +
-            "Append a fully-formed entity to spec.blocks / spec.streams / spec.triggers.\n\n" +
-            "Required: op, value (the full entity object — must include `id` to be addressable later)\n" +
-            "Errors (op skipped): \"id already exists in <collection>\" if value.id collides with an existing entry.\n\n" +
-            "Minimal:\n" +
-            `  { "op": "addTrigger", "value": { "type": "voice_command", "id": "t_save", "phrase": "save it", "match_mode": "contains", "actions": [{ "type": "speak_text", "text": "Saved." }] } }\n` +
-            `  { "op": "addStream", "value": { "type": "transcription_incremental", "id": "live_transcription", "config": { "language": "en-US" } } }\n` +
-            `  { "op": "addBlock", "value": { "type": "capture_photo", "id": "main_camera" } }\n\n` +
-            "─── removeBlock / removeStream / removeTrigger ───\n" +
-            "Remove the entity by id.\n\n" +
-            "Required: op, id (or value.id — both accepted)\n" +
-            "Skipped (not error): \"<collection> id not found\" — safe to retry idempotently.\n\n" +
-            "Minimal:\n" +
-            `  { "op": "removeTrigger", "id": "t_save" }\n\n` +
-            "─── updateBlock / updateStream / updateTrigger ───\n" +
-            "Shallow-merge `value` into the existing entity. The id field is preserved (cannot be renamed via update — to rename, remove + add).\n\n" +
-            "Required: op, id, value (the partial patch — only the fields to change)\n" +
-            "Skipped: id not found.\n\n" +
-            "Minimal — change a phrase:\n" +
-            `  { "op": "updateTrigger", "id": "t_save", "value": { "phrase": "save the note" } }\n\n` +
-            "─── addAction ───\n" +
-            "Insert an action into a trigger's actions[] flow.\n\n" +
-            "Required: op, **triggerId** (NOT id — addresses the parent trigger), value (the action object)\n" +
-            "Optional: actionIndex (0-based insert position; default = end of array)\n" +
-            "Skipped: triggerId not found.\n\n" +
-            "Minimal — append to end:\n" +
-            `  { "op": "addAction", "triggerId": "t_save", "value": { "type": "speak_text", "text": "Saved." } }\n\n` +
-            "Insert at index 1:\n" +
-            `  { "op": "addAction", "triggerId": "t_save", "actionIndex": 1, "value": { "type": "delay", "seconds": 1 } }\n\n` +
-            "─── removeAction ───\n" +
-            "Remove an action by index.\n\n" +
-            "Required: op, triggerId, actionIndex\n" +
-            "Skipped: trigger not found, OR actionIndex out of range.\n\n" +
-            "Minimal:\n" +
-            `  { "op": "removeAction", "triggerId": "t_save", "actionIndex": 1 }\n\n` +
-            "─── updateAction ───\n" +
-            "Shallow-merge `value` into the action at actionIndex.\n\n" +
-            "Required: op, triggerId, actionIndex, value\n" +
-            "Skipped: trigger not found, OR actionIndex out of range.\n\n" +
-            "Minimal — change TTS text without changing action type:\n" +
-            `  { "op": "updateAction", "triggerId": "t_save", "actionIndex": 1, "value": { "text": "Saved successfully." } }\n\n` +
-            "─── updateMeta ───\n" +
-            "Patch top-level spec fields OTHER than blocks/streams/triggers (e.g., `target.vendor`, `extentos_version`).\n\n" +
-            "Required: op, value (top-level patch)\n" +
-            "Skipped: value contains `blocks`, `streams`, or `triggers` (use the dedicated ops for those).\n\n" +
-            "Minimal:\n" +
-            `  { "op": "updateMeta", "value": { "extentos_version": "1.0" } }\n\n` +
-            "── Common patterns ──\n" +
-            "- **Add a trigger and chain its actions in one updateSpec call**: pass [addTrigger, addAction, addAction, ...] in order. Operations run sequentially within a single call — the addTrigger lands first, then subsequent addActions can target it by id.\n" +
-            "- **Idempotent reorder**: removeAction by index, then addAction with the desired actionIndex.\n" +
-            "- **Partial-apply semantics**: each op runs independently; a single bad op fills `skipped[]` while the rest still apply. Use `applied[]` and `skipped[]` from the response to confirm what landed.\n\n" +
-            "── Common mistakes ──\n" +
-            "- Using `id` for action ops where `triggerId` is required — actions are addressed by their parent trigger + array index, never by their own id.\n" +
-            "- Trying to rename via update*: id is preserved through update, never overwritten. To rename, removeBlock/Stream/Trigger + addBlock/Stream/Trigger.\n" +
-            "- updateMeta with blocks/streams/triggers in value — these have dedicated ops; updateMeta refuses.\n" +
-            "- Passing `{op:\"add\", path:\"/triggers/-\", value:...}` (JSON Patch RFC 6902 shape) — NOT supported. Use the domain ops above.",
-        keywords: [
-            "operations",
-            "patch",
-            "addTrigger",
-            "addAction",
-            "addStream",
-            "addBlock",
-            "removeTrigger",
-            "updateTrigger",
-            "updateAction",
-            "triggerId",
-            "actionIndex",
-            "updateMeta",
-            "mutate",
-            "edit spec",
-        ],
-        relatedTools: ["updateSpec", "inspectIntegration", "validateSpec"],
-    },
-    {
-        topic: "spec_validation_rules",
-        title: "Spec Validation Rules",
-        content: "11 rules: R1 extentos_version, R2 target.vendor, R3 block type supported, R4 stream type supported, R5 id pattern ^[a-z][a-z0-9_]{0,31}$ and uniqueness, R6 trigger type supported, R7 action type supported, R8 app_callback handler name, R9 branch depth ≤ 1 (then/else arms cannot contain another branch — refactor deeper logic into an app_callback handler), R10 template variable resolvable, R11 toggle key in allowed set.",
-        keywords: ["validation", "rule", "error", "lint", "r1", "r5", "branch depth", "id regex"],
-        relatedTools: ["validateSpec", "validateIntegration"],
-    },
-    {
-        topic: "template_syntax",
-        title: "Template Variable Syntax",
-        content: "Curly-brace interpolation: {{key}} resolves against trigger payload or variables. Dot paths: {{trigger_payload.captures.query}}, {{toggles.listening_mode}}, {{hardware_state.thermal}}. Special namespaces: trigger_payload (per-trigger fields), toggles (runtime state), hardware_state (thermal/battery/audio route/connected). Unresolvable paths fail R10.",
-        keywords: ["template", "variable", "substitution", "capture", "interpolation", "curly", "{{"],
-        relatedTools: ["validateSpec", "updateSpec"],
+        content: "Voice phrases are plain strings post-pivot — your handler subscribes to `glasses.audio.transcriptions()`, gets a `Transcript` (sealed: Partial / Final), and decides what counts as a match. There is no DSL matcher, no `{{query}}` captures, no `match_mode: \"exact\"` vs `\"contains\"`. The matching policy is yours.\n\n" +
+            "── Phrase-design rules (UX, not matcher behaviour) ──\n\n" +
+            "These are what `getVoiceCommandGuidance` flags. They're UX rules, not parser rules — you'll hit them no matter what string-comparison code you write.\n\n" +
+            "- **3+ syllables.** Single-syllable phrases mis-trigger on background speech.\n" +
+            "- **No homophones with common speech.** \"Right\" matches \"write\" / \"rite\"; STT can't disambiguate from context.\n" +
+            "- **No digits.** STT round-trips digits inconsistently — \"two\" vs \"2\" vs \"to\" vs \"too\". Spell them, or use ordinals (\"first / second / third\").\n" +
+            "- **Avoid Meta hardware wake words** — \"hey meta\", \"hey facebook\", \"ok meta\". These ALSO trigger Meta's on-device assistant, which can intercept the mic before your handler sees the transcript.\n" +
+            "- **3+ alternates per intent.** Natural speech varies; if you only match \"start recording\" you'll miss \"begin recording\" / \"record this\". Iterate from real dogfood transcripts.\n\n" +
+            "── Apostrophe / punctuation handling ──\n\n" +
+            "STT engines emit different casings, punctuations, and apostrophe shapes for the same utterance. The library does NOT normalize for you — `transcript.text` is what the recognizer returned, verbatim. Normalize on the read side in your handler:\n\n" +
+            "  Kotlin:\n" +
+            "    fun normalize(s: String) = s.lowercase()\n" +
+            "        .replace(Regex(\"[^a-z0-9\\\\s]\"), \"\")\n" +
+            "        .replace(Regex(\"\\\\s+\"), \" \").trim()\n\n" +
+            "  Swift:\n" +
+            "    func normalize(_ s: String) -> String {\n" +
+            "        s.lowercased()\n" +
+            "         .components(separatedBy: CharacterSet.alphanumerics.union(.whitespaces).inverted).joined()\n" +
+            "         .components(separatedBy: .whitespaces).filter { !$0.isEmpty }.joined(separator: \" \")\n" +
+            "    }\n\n" +
+            "Match `normalize(transcript.text).contains(normalize(phrase))` to cover apostrophe / punctuation / case variance with one rule.\n\n" +
+            "── When to call getVoiceCommandGuidance ──\n\n" +
+            "Pass the phrases you're about to wire into your handler (one MCP call per batch). The tool surfaces homophones, length issues, digit-usage, Meta wake-word collisions, and ambiguity against existing phrases (pass `existingPhrases` so it can compare). Run it BEFORE shipping the phrase strings — runtime debugging tells you it didn't match, but never why.",
+        keywords: ["voice", "phrase", "command", "homophone", "stt", "disambiguation", "alternate", "contraction", "apostrophe", "normalization", "punctuation", "transcripts", "wake phrase"],
+        relatedTools: ["getVoiceCommandGuidance"],
     },
     {
         topic: "toggles",
         title: "Runtime Toggles",
-        content: "**Toggles are persistent runtime flags that GATE hardware behavior — when implemented.** Unlike spec-side variables (flow-scoped), toggles persist across trigger fires and are written by both spec actions (`set_toggle`) and connection-page UI controls. 8 toggles, each with a defined type / default / *intended* behavior.\n\n" +
-            "**⚠️ Implementation status (1.1.25-pair):** ENFORCED toggles: `transcription_enabled` (Bundle 9), `camera_streaming_enabled` (Bundle 12), `audio_capture_enabled` (Bundle 12), `listening_mode` (Bundle 13 — `off` value enforced library-side), `privacy_mode` (Bundles 14 + 20 — super-toggle gates capture + audio + STT + notification forwarding), `battery_save_mode` (Bundle 15 — video_frames clamp to LOW+2fps), `voice_confirmations` (Bundle 19 — auto-earcons around voice triggers). Still NOT enforced (1 toggle): `audio_video_coexistence_policy`. F-R5-13 (coexistence) tracks the remaining toggle gap; F-R5-13b residual now down to UI-indicator-only (cosmetic — no functional gap); F-R5-16b tracks battery_save_mode's residual gaps (outgoing_video_stream disable, ask_user timeout shortening, speak_text filler suppression). Until they're closed, treat the unimplemented toggle as cooperative state that YOUR app code can read (via `glasses.toggles.get(...)`) but that the library does NOT honor automatically. Each toggle's section below begins with its current status.\n\n" +
-            "Three ways flows interact with toggles:\n" +
-            "1. **WRITE**: `{ \"type\": \"set_toggle\", \"key\": \"<name>\", \"value\": <literal> }` — mutates the toggle. Validation rule R11 rejects unknown keys.\n" +
-            "2. **READ in branch**: `{ \"variable\": \"toggles.<name>\", \"operator\": \"equals\", \"value\": <literal> }` — branch reads the live toggle value at the decision point (never cached).\n" +
-            "3. **READ via template**: `{{toggles.<name>}}` resolves to the current value; usable inside any string field that supports template substitution.\n\n" +
-            "─── listening_mode ───\n**Status (1.1.21-pair): ✅ IMPLEMENTED for `off`; partial for the other enum values.** Library's `DefaultAudioClient.transcriptions(...)` gates the recognizer flow on `listening_mode != \"off\"`. When `off`, no transcripts arrive (transport-side recognizer not started, SCO mic released). The other values (`always_on`, `on_demand`, `wake_word`) all let transcription through library-side — `on_demand`'s 'only while push_to_talk / ask_user is active' semantics require runtime trigger-context integration that's deferred; `wake_word` requires a Meta API the DAT doesn't expose (treat as future-only).\n\nDefault: unset is treated as listening-on for backward compat with apps written before Bundle 13. The connection-page UI's EscapeHatch renders the toggle as OFF when unset, but the library doesn't infer that — set explicit `listening_mode = \"off\"` to actually gate STT.\n\nComposes with `audio_capture_enabled` (Bundle 12) and `transcription_enabled` (Bundle 9). All three must be 'on' for transcripts to flow:\n- `audio_capture_enabled = false` → no audio anywhere (raw chunks, recordings, transcripts).\n- `listening_mode = \"off\"` → audio chunks + recordings still work, but no STT.\n- `transcription_enabled = false` → spec-driven `glasses.streams.transcriptionIncremental(...)` emits nothing; the direct `glasses.audio.transcriptions(config)` API still fires (manual lifecycle).\n\nType: enum\nValues: `off`, `wake_word`, `on_demand`, `always_on`\n- `off`: STT disabled entirely. ✅ ENFORCED.\n- `wake_word`: listen for wake word, switch to always-on after detection. **Not yet wired on Meta Ray-Ban** (DAT 0.5 doesn't expose Meta's wake-word API; library treats as listening-on for now).\n- `on_demand`: intended to enable STT only while push_to_talk or ask_user is active. **Library currently treats as listening-on** (the trigger-context gate is deferred).\n- `always_on`: continuous transcription. ✅ Same effect as wake_word/on_demand at library level.\n\nWhen to use set_toggle for this: usually you don't — it's user-controlled via the connection-page UI. Programmatic flips are valid but consider whether the user actually wanted listening on.\n\nMinimal:\n  { \"type\": \"set_toggle\", \"key\": \"listening_mode\", \"value\": \"always_on\" }\n\n─── camera_streaming_enabled ───\n**Status (1.1.20-pair): ✅ IMPLEMENTED.** Library's `DefaultCameraClient` checks the toggle on every camera primitive: `capture_photo` and `capture_video` fail-fast with `CaptureError.DisabledByUser(\"camera_streaming_enabled\")` when false; `video_frames` stream emits nothing while false (transport-side stream is cancelled, camera released). Default true; toggle unset → camera works. The error surfaces in `getEventLog` as `BlockCompleted result:\"failed:disabled_by_user:camera_streaming_enabled\"` so flows can branch on it via the standard `is_empty` check on the saved photo/video URI.\n\nGlobal kill switch for ALL camera primitives: video_frames stream, capture_photo block, capture_video block, outgoing_video_stream.\n\nType: boolean\nDefault: true\n\nMinimal:\n  { \"type\": \"set_toggle\", \"key\": \"camera_streaming_enabled\", \"value\": false }\n\n─── audio_capture_enabled ───\n**Status (1.1.20-pair): ✅ IMPLEMENTED.** Library's `DefaultAudioClient` gates `recordDiscrete`/`audioChunks`/`transcriptions` on this toggle. record_audio block fails fast with `AudioError.DisabledByUser(\"audio_capture_enabled\")` when false; audio_chunks + transcription_incremental streams emit nothing while false. Composes with `transcription_enabled` from Bundle 9: setting audio_capture_enabled=false while transcription_enabled=true correctly produces no transcripts (audio capture is killed upstream of STT).\n\nGlobal kill switch for ALL audio-capture primitives: audio_chunks stream, record_audio block, outgoing_audio_stream, transcription_incremental.\n\nType: boolean\nDefault: true\n\nDistinct from `transcription_enabled`: this gates raw audio acquisition; transcription_enabled gates STT processing on top of it. Both toggles compose — true on both = transcripts; false on either = no transcripts.\n\n─── transcription_enabled ───\n**Status (1.1.19-pair): ✅ IMPLEMENTED.** The library's spec-driven stream API (`glasses.streams.transcriptionIncremental(streamId)`, added in Bundle 9) observes this toggle and gates the underlying recognizer flow accordingly. Toggle false → no transcripts; toggle true → recognizer running.\n\n*Note:* the gating only applies to consumers using `glasses.streams.transcriptionIncremental(...)` — the direct `glasses.audio.transcriptions(config)` API is intentionally ungated for manual-lifecycle use. `generateConsumer(kind: \"stream\")` emits the gated path by default.\n\nDistinct from `audio_capture_enabled` — you may want raw audio without STT (for custom on-device models via audio_chunks).\n\nType: boolean\nDefault: false\n\n**Required to start a transcription_incremental stream.** Without this true, the stream is declared but produces no data. Common pattern: a `start taking notes` voice trigger flips this true; a `stop taking notes` trigger flips it false.\n\nSide effect: while true, audio routes to HFP — the user briefly loses high-quality A2DP playback if any.\n\nMinimal:\n  { \"type\": \"set_toggle\", \"key\": \"transcription_enabled\", \"value\": true }\n\n─── battery_save_mode ───\n**Status (1.1.23-pair): ✅ IMPLEMENTED for video_frames clamp; partial.** When true, `glasses.camera.videoFrames(...)` is forced to LOW resolution + max 2 fps regardless of the requested config. Apps that called `videoFrames(VideoFrameConfig(frameRate = 30, resolution = HIGH))` get LOW + 2 silently. Battery_save_mode flipping mid-stream restarts the inner transport flow with the clamped config (camera renegotiates capture rate).\n\n**Still NOT implemented (F-R5-16b):** outgoing_video_stream disable, ask_user timeout shortening, speak_text progressive-response-filler suppression. The `thermal_throttle` preset trigger flips this toggle on critical thermal — the video_frames clamp now takes effect, but the other intended behaviors are deferred.\n\n*Intended (full) behavior:* video_frames clamps to LOW resolution + 2 fps (✅ shipped Bundle 15); outgoing_video_stream is disabled (deferred F-R5-16b); ask_user timeouts shorten (deferred F-R5-16b); speak_text suppresses progressive-response filler (deferred F-R5-16b).\n\nType: boolean\nDefault: false\n\nCanonical use: a `thermal_warning` trigger at severity moderate+ flips this true. Pair with the `thermal_throttle` initSpec preset for the canonical shape.\n\nMinimal:\n  { \"type\": \"set_toggle\", \"key\": \"battery_save_mode\", \"value\": true }\n\n─── voice_confirmations ───\n**Status (1.1.24-pair): ✅ IMPLEMENTED.** Library's Interpreter plays an auto-earcon pair around voice triggers (VOICE_COMMAND, WAKE_WORD, PUSH_TO_TALK): `EarconSound.START` BEFORE walking the trigger's actions, `EarconSound.COMPLETE` after successful completion. When `voice_confirmations = false`, both earcons are skipped. Other trigger types (manual_launch, hardware events, fallback) NEVER auto-earcon — they fire silently regardless of the toggle. Aborts and unexpected failures play START but skip COMPLETE — no auto-error earcon (apps that want explicit failure feedback should call `earcon_beep` with `sound: \"error\"` inside their abort branch).\n\nWhen false, voice triggers fire silently. Useful for ambient assistants or accessibility flows where the user prefers quiet operation. The dev still controls per-action TTS via speak_text and per-action beeps via earcon_beep; this toggle only affects the AUTO-played pair around voice trigger flows.\n\nType: boolean\nDefault: true\n\nMalformed (wrong-typed) values default to true (defensive) — a misconfigured spec doesn't accidentally silence voice acks.\n\nMinimal:\n  { \"type\": \"set_toggle\", \"key\": \"voice_confirmations\", \"value\": false }\n\n─── audio_video_coexistence_policy ───\n**Status (1.1.19-pair): NOT IMPLEMENTED.** Value persists but the library does NOT enforce coexistence — concurrent audio + video primitives currently surface platform errors (not policy decisions). F-R5-13.\n\n*Intended behavior (when implemented):* Controls what happens when a flow tries to open an audio primitive while a video primitive is active (or vice versa). DAT 0.5 routes audio over HFP, which suspends A2DP — the lib should enforce this policy to prevent overlapping primitives that conflict.\n\nType: enum\nDefault: `prefer_video`\nValues: `prefer_audio`, `prefer_video`, `strict_reject`\n- `prefer_audio`: pause the active video stream while audio runs; resume video on completion.\n- `prefer_video`: reject the new audio primitive; flow continues without it.\n- `strict_reject`: abort the flow with an error.\n\nSee `audio_video_coexistence` topic for the full coexistence model.\n\n─── privacy_mode ───\n**Status (1.1.22-pair): ✅ IMPLEMENTED for capture + audio + STT. Extended in 1.1.25-pair to also suppress notification forwarding (Bundle 20).** Library's `DefaultCameraClient` and `DefaultAudioClient` check `privacy_mode` FIRST on every primitive — when true, gates camera_streaming and audio_capture regardless of those individual toggles' values. capture_photo / capture_video / record_audio fail-fast with `DisabledByUser(\"privacy_mode\")` (note: error reports `privacy_mode` rather than the underlying gate, signaling the more general user intent). video_frames / audio_chunks / transcriptions emit nothing while privacy_mode is true. **As of 1.1.25-pair (Bundle 20): `phone_notification_forwarded` triggers are also suppressed** at the `HardwareEventRouter` dispatch layer — the trigger never fires while privacy_mode is true. Other hardware alerts (thermal, hinges, audio route, calls, lifecycle) still fire — privacy_mode is specifically about user-data exposure (camera/mic/STT/notifications), not all hardware events.\n\n**Still NOT implemented:** connection-page UI privacy indicator. F-R5-13b residual: the EscapeHatch UI doesn't yet render a clear \"privacy mode active\" badge. Cosmetic-only — no functional gap remaining.\n\n**The one super-toggle.** When true, forces camera + audio capture off, disables STT, and suppresses notification forwarding. Composes with all other gates: ANY of (privacy_mode true, camera_streaming false, audio_capture false, listening_mode \"off\") closes the relevant primitive.\n\nType: boolean\nDefault: false (opt-in — must be flipped on to engage)\n\nLayered semantics: every other toggle is FLAT (effective value = stored value). privacy_mode is the only LAYERED toggle — the library now computes effective gates at the camera/audio decision points. Concretely: when privacy_mode is true, camera + audio + STT all return DisabledByUser(\"privacy_mode\") regardless of their individual toggle values; flipping privacy_mode back to false restores the underlying toggles' effective state.\n\nMalformed (wrong-type) values default to false — a misconfigured spec doesn't silently privacy-mode the app.\n\nCommon pattern: a `set_toggle privacy_mode true` action is the sledgehammer for end-of-session cleanup. Always pair with a means to flip it back off (UI toggle on the connection page is the primary path).\n\nMinimal:\n  { \"type\": \"set_toggle\", \"key\": \"privacy_mode\", \"value\": true }\n\n── Reading toggle state from flows ──\nBranch example — abort a photo flow if privacy is on (works today since the BRANCH read is implemented; the camera kill-switch part is NOT, so this branch is the recommended workaround until F-R5-13 lands):\n  { \"type\": \"branch\",\n    \"condition\": { \"variable\": \"toggles.privacy_mode\", \"operator\": \"equals\", \"value\": true },\n    \"then\": [{ \"type\": \"abort\", \"reason\": \"privacy_mode_active\" }]\n  }\n\nTemplate example — speak the current battery-save state:\n  { \"type\": \"speak_text\", \"text\": \"Battery save is {{toggles.battery_save_mode}}.\" }\n\nWhen-connected predicate (preferred over branch for connection gating):\n  { \"type\": \"when_connected\", \"action\": { ... }, \"predicate\": \"toggle_on:transcription_enabled\" }\n\n── Common mistakes ──\n- **Assuming a toggle's documented gating behavior is enforced by the library.** As of 1.1.24-pair, ENFORCED: `transcription_enabled` (Bundle 9), `camera_streaming_enabled` + `audio_capture_enabled` (Bundle 12), `listening_mode` (Bundle 13 — `off` value), `privacy_mode` (Bundle 14 — super-toggle gates capture + audio + STT), `battery_save_mode` (Bundle 15 — video_frames LOW+2fps clamp), `voice_confirmations` (Bundle 19 — auto-earcons around voice triggers). NOT YET ENFORCED: `audio_video_coexistence_policy`. F-R5-13 (coexistence) tracks the remaining gap; F-R5-13b tracks privacy_mode's residual gaps (notification suppression); F-R5-16b tracks battery_save_mode's residual gaps.\n- **Expecting `voice_confirmations = false` to also silence per-action `earcon_beep` calls or `speak_text`.** It does NOT — only the AUTO-played pair (START before voice trigger walk + COMPLETE after success) is gated. Spec actions remain in your control. To go fully silent, also avoid `earcon_beep` and `speak_text` actions inside voice triggers.\n- **Expecting `battery_save_mode = true` to disable outgoing_video_stream / shorten ask_user timeouts / suppress speak_text filler.** The library currently only clamps video_frames (LOW + 2 fps). The other intended behaviors (F-R5-16b) are deferred. Apps that need them must check `glasses.toggles.get(\"battery_save_mode\")` themselves and adapt.\n- **Expecting `privacy_mode = true` to ALSO render a UI privacy indicator on the connection page.** It does NOT yet — Bundle 20 closed the functional notification-suppression gap, but the EscapeHatch UI doesn't render a \"privacy mode active\" badge yet (F-R5-13b residual; cosmetic only). Apps that need a UI indicator can build their own using `glasses.toggles.state` flow.\n- **Setting `transcription_enabled: true` without declaring a `transcription_incremental` stream** — toggle has no effect; the lib has nothing to gate.\n- **Setting `listening_mode = \"on_demand\"` and expecting STT to only run during push_to_talk / ask_user.** The library currently treats `on_demand` as listening-on (same as `always_on`) — the trigger-context gate is deferred. Use `audio_capture_enabled = false` outside the active window or program your push_to_talk flow to flip `listening_mode` between `always_on` and `off` directly.\n- **Comparing toggle values with the wrong type in branch**: `transcription_enabled` is boolean — use `value: true`, not `value: \"true\"` (string). Validator may not catch type mismatches at spec-load; expect silent always-false branches.\n- **Trying to set toggles not in the 8-key allowlist** — validation rule R11 rejects with the list of valid keys.",
+        content: "Toggles are persistent runtime flags that gate hardware behaviour inside the library. They survive across app restarts (persisted to the user's account by the connection page UI) and are observable from your handler via `glasses.toggles.state` (Android `StateFlow<Toggles>`, iOS `ObservableState<Toggles>`). The user owns the toggle values — they flip them from the connection page; your handler reads them. Programmatic writes are possible (`glasses.toggles.update { it.copy(values = ...) }` / `.put(...)`) but rarely needed in customer code.\n\n" +
+            "**8 toggles.** Each has a defined type / default / library-enforced behaviour. Seven are enforced inside the library — your handler does not need to honor them manually. One is cooperative state.\n\n" +
+            "── listening_mode ── (enforced for `off`)\nType: enum (`off`, `wake_word`, `on_demand`, `always_on`). Default: unset, treated as listening-on.\n\n`DefaultAudioClient.transcriptions(...)` gates the recognizer flow on `listening_mode != \"off\"`. When `off`, no transcripts arrive — transport-side recognizer is not started, SCO mic released. `wake_word` requires a Meta API DAT 0.5 doesn't expose (treated as listening-on); `on_demand`'s intended 'only-during-push-to-talk' semantics are deferred (also treated as listening-on for now).\n\nComposes with `audio_capture_enabled` and `transcription_enabled` — ALL three must be on for transcripts to flow. The user-facing UI on the connection page exposes this as the master mic toggle.\n\n── camera_streaming_enabled ── (enforced)\nType: boolean. Default: true.\n\nGlobal kill switch for every camera primitive: `videoFrames` stream emits nothing while false (transport-side stream cancelled, camera released); `capturePhoto` and `captureVideo` fail-fast with `CaptureError.DisabledByUser(\"camera_streaming_enabled\")`. Surfaces in `getEventLog` as a `camera.capture_failed` event with the toggle name as the reason.\n\n── audio_capture_enabled ── (enforced)\nType: boolean. Default: true.\n\nGlobal kill switch for every audio-capture primitive: `recordDiscrete` fails with `AudioError.DisabledByUser`; `audioChunks` and `transcriptions` emit nothing while false. Composes with `transcription_enabled` — gating the toggle here kills audio upstream of STT, so transcripts disappear too.\n\nDistinct from `transcription_enabled`: this gates raw audio acquisition; `transcription_enabled` gates STT processing on top of it.\n\n── transcription_enabled ── (enforced)\nType: boolean. Default: false.\n\nWhen false, `glasses.audio.transcriptions(...)` returns an empty stream. Common pattern: a handler subscribing for wake-word matching flips this on at startup; a 'pause listening' user-toggle flips it off. The toggle gates only the recognizer — `audio.audioChunks(...)` (raw audio) still flows.\n\nSide effect: while true, audio routes over HFP, which suspends A2DP — the user briefly loses high-quality stereo playback. Flipping this on while music is playing is the most-common UX surprise.\n\n── battery_save_mode ── (enforced for video_frames clamp; partial)\nType: boolean. Default: false.\n\nWhen true, `glasses.camera.videoFrames(...)` is clamped to LOW resolution + 2 fps regardless of the requested config; the camera renegotiates capture rate when the toggle flips mid-stream. Other intended behaviours (disable outgoing_video_stream, shorten ask_user timeouts, suppress speak filler) are deferred — apps that need them must read the toggle directly via `glasses.toggles.state` and adapt their handler.\n\nThermal-warning paths typically flip this on automatically when the device reports critical thermal state.\n\n── voice_confirmations ── (enforced)\nType: boolean. Default: true.\n\nWhen true, the library plays an auto-earcon pair around any handler that the user invokes through the connection page's voice surface: `EarconSound.START` before the handler runs, `EarconSound.COMPLETE` after success. Aborts skip the COMPLETE earcon (no auto-error earcon — call `earcon` directly with `sound: \"error\"` from your handler if you want explicit failure feedback). When false, voice-initiated handlers run silently.\n\nUseful for ambient assistants or accessibility flows where the user prefers quiet operation. Your per-handler `speak()` and `earcon()` calls are NOT affected — only the auto-played pair around voice-initiated handlers.\n\n── audio_video_coexistence_policy ── (NOT enforced — cooperative)\nType: enum (`prefer_audio`, `prefer_video`, `strict_reject`). Default: `prefer_video`.\n\nValue persists but the library does NOT yet enforce coexistence — concurrent audio + video primitives currently surface platform errors rather than policy decisions. Treat as cooperative state your handler can read (`glasses.toggles.state.value.audioVideoCoexistencePolicy`) and respect manually if you care about the ordering. See `audio_video_coexistence` topic.\n\n── privacy_mode ── (enforced — the super-toggle)\nType: boolean. Default: false (opt-in).\n\nThe one LAYERED toggle. When true, gates ALL camera + audio + STT primitives regardless of the underlying per-feature toggles' values: `capturePhoto` / `captureVideo` / `recordDiscrete` fail-fast with `DisabledByUser(\"privacy_mode\")`; `videoFrames` / `audioChunks` / `transcriptions` emit nothing. As of library 1.1.25-pair, also suppresses phone-notification forwarding at the dispatch layer.\n\nOther hardware events (thermal, hinges, audio route, calls, lifecycle) still fire — privacy_mode is specifically about user-data exposure (camera/mic/STT/notifications), not all hardware events.\n\nCanonical use: a 'panic privacy' UI control that flips this true. Always pair with a means to flip it back off — the connection page UI is the primary path.\n\n── Reading toggle state from your handler ──\n\nKotlin (StateFlow):\n  glasses.toggles.state.collect { toggles ->\n      if (toggles.privacyMode) { skipExpensiveWork(); return@collect }\n      if (!toggles.transcriptionEnabled) showStartHint()\n  }\n\nSwift (ObservableState):\n  for await toggles in glasses.toggles.state.stream {\n      if toggles.privacyMode { continue }\n      if !toggles.transcriptionEnabled { showStartHint() }\n  }\n\nOne-shot read:\n  val v = glasses.toggles.state.value\n  let v = await glasses.toggles.state.current\n\n── Writing toggles programmatically ──\n\nThe user owns toggle values via the connection page; programmatic writes are valid but uncommon. The closure form is the canonical API:\n\n  Kotlin: glasses.toggles.update { it.copy(values = it.values + (\"privacy_mode\" to JsonPrimitive(true))) }\n  Swift:  await glasses.toggles.update { old in Toggles(values: old.values.merging([\"privacy_mode\": .bool(true)]) { _, new in new }) }\n\nAndroid additionally exposes a `put(key, value)` convenience method. Source tagging: pass `ToggleSource.UI` for user-initiated writes, `ToggleSource.HOST_APP` for handler-initiated writes — surfaces in `getEventLog` so you can tell who flipped what.\n\n── Common mistakes ──\n\n- **Subscribing to `glasses.audio.transcriptions()` and seeing nothing.** Check `transcription_enabled` AND `audio_capture_enabled` AND `privacy_mode == false` AND `listening_mode != \"off\"`. ANY of those four can silence the stream.\n- **Setting `listening_mode = \"on_demand\"` and expecting STT to only run during push-to-talk.** The library currently treats `on_demand` as listening-on (same as `always_on`). Your handler can implement the gating itself by flipping `audio_capture_enabled` around the active window.\n- **Comparing toggle values with the wrong type.** The values are typed JSON — booleans are `JsonPrimitive(true)`, not `JsonPrimitive(\"true\")`. Pattern-match the JSONValue or use the typed accessors on Toggles.\n- **Trying to set a key not in the 8-toggle allowlist.** Library rejects unknown keys; the canonical list is enforced server-side too (the connection page UI only exposes these 8).\n- **Flipping `battery_save_mode` and assuming the full intended behaviour is in effect.** Only the videoFrames LOW+2fps clamp ships today. Other intended effects (outgoing_video_stream off, ask_user shorter timeouts) are deferred; if your handler depends on them, read the toggle and implement the behaviour yourself.",
         keywords: [
             "toggle",
             "privacy_mode",
-            "set_toggle",
             "listening_mode",
             "transcription_enabled",
             "camera_streaming_enabled",
@@ -748,10 +224,11 @@ export const DOC_INDEX = [
             "state",
             "runtime",
             "super",
-            "branch",
-            "template",
+            "togglesClient",
+            "update",
+            "put",
         ],
-        relatedTools: ["updateSpec", "initSpec", "getVoiceCommandGuidance"],
+        relatedTools: ["getCapabilityGuide"],
     },
     {
         topic: "connection_state_model",
@@ -763,168 +240,188 @@ export const DOC_INDEX = [
     {
         topic: "audio_video_coexistence",
         title: "Audio / Video Coexistence",
-        content: "Bluetooth A2DP (stereo media) and HFP (mic + mono audio) cannot run simultaneously on most Meta Ray-Ban pairings. audio_video_coexistence_policy toggle controls behavior: 'mic_priority' downgrades playback to mono when mic is active; 'stereo_priority' disables mic during stereo playback. Events surface 'degraded' markers when fallback occurs.",
-        keywords: ["audio", "video", "coexistence", "a2dp", "hfp", "bluetooth", "degraded", "priority"],
-        relatedTools: ["updateSpec"],
+        content: "Bluetooth A2DP (stereo media playback) and HFP (mic + mono audio capture) cannot run simultaneously on most Meta Ray-Ban pairings — the link can serve either profile at a time. The `audio_video_coexistence_policy` toggle declares the policy your app prefers when handlers try to use both at once.\n\n" +
+            "**Values** (enum):\n" +
+            "- `prefer_audio` — pause the active video stream while mic capture runs; resume video when the audio operation completes.\n" +
+            "- `prefer_video` (default) — reject the audio operation while video is active; your handler sees `AudioError.Conflict` (or equivalent) and must decide how to proceed.\n" +
+            "- `strict_reject` — abort either operation with an error if the other is already running.\n\n" +
+            "**Enforcement status:** the toggle value persists, but the library does NOT yet enforce the policy automatically — concurrent audio + video primitives currently surface platform-level errors rather than policy-driven decisions. F-R5-13 tracks closing this gap. Until then, treat the policy as cooperative state your handler reads via `glasses.toggles.state` and respects manually.\n\n" +
+            "**Diagnostics:** when the conflict actually fires (A2DP suspending under HFP, or vice versa), the event log surfaces a `transport.audio_route_degraded` event so you can see which profile won. Useful when a user reports 'my music dropped to mono when the glasses started transcribing' — that's the expected HFP pre-emption, not a bug.",
+        keywords: ["audio", "video", "coexistence", "a2dp", "hfp", "bluetooth", "degraded", "policy", "prefer_audio", "prefer_video", "strict_reject"],
+        relatedTools: ["getCapabilityGuide"],
     },
     {
         topic: "library_api",
         title: "Extentos Library API",
-        content: "ExtentosGlasses is the top-level object, carrying 8 consumer-facing sub-clients (identical surface on Android and iOS). Creation: `ExtentosGlasses.create(config)` on Android / `Extentos.create(config)` on iOS. ExtentosConfig controls transport override, debug, telemetryConsent, applicationContext (Android), and metaCredentials.\n\n" +
-            "**Lifecycle / Result types**: every suspending op returns `ExtentosResult.Ok(value)` or `ExtentosResult.Err(error)` — pattern-match both. Do NOT wrap in Kotlin `runCatching` (which only catches thrown exceptions; library ops use the Result channel for failures and never throw).\n\n" +
-            "── glasses.connection ── (`ConnectionClient`)\n" +
-            "- `val state: StateFlow<GlassesState>` — observe Connecting / SessionActive / Disconnected / etc.\n" +
-            "- `val simulatorHint: StateFlow<SimulatorHint?>` — non-null when transport is simulator (BrowserSim/LocalSim) so UI can surface a hint badge.\n" +
-            "- `suspend fun connect(deviceId: DeviceId? = null): ExtentosResult<Unit, ConnectError>` — initiate connection. Bootstrap calls this in onCreate.\n" +
-            "- `suspend fun disconnect()` — graceful tear-down.\n\n" +
-            "── glasses.camera ── (`CameraClient`)\n" +
-            "- `suspend fun capturePhoto(config: PhotoConfig = PhotoConfig()): ExtentosResult<Photo, CaptureError>` — one-shot still. Same path the `capture_photo` block uses.\n" +
-            "- `suspend fun captureVideo(config: VideoConfig = VideoConfig()): ExtentosResult<VideoClip, CaptureError>` — bounded clip.\n" +
-            "- `fun videoFrames(config: VideoFrameConfig = VideoFrameConfig()): Flow<VideoFrame>` — frame stream. Same path the `video_frames` stream uses.\n\n" +
-            "  Photo display helper (extension on `Photo` — for code holding a `Photo` object directly, e.g. from `glasses.camera.capturePhoto()`):\n" +
-            "  - Android: `suspend fun Photo.loadBitmap(): Bitmap?` — runs on `Dispatchers.IO`. Decodes the photo regardless of which transport produced the URI; handles `data:` (BrowserSim base64-inline), `file://` (RealMeta + LocalSim), and bare absolute paths uniformly. Returns null on null URI, unrecognized scheme, missing file, or decode failure.\n" +
-            "  - iOS: `func loadImage() async -> PlatformImage?` (`PlatformImage = UIImage` on iOS targets, `NSImage` on macOS). Same scheme dispatch (`file:` and `data:`); decode runs on a detached high-priority Task. Returns nil on unrecognized scheme, missing file, or decode failure.\n" +
-            "  - Use this instead of writing your own URI decoder — Coil's `AsyncImage` and SwiftUI's `AsyncImage` silently fail on the BrowserSim `data:` shape; this helper exists exactly to close that leaky abstraction.\n\n" +
-            "  Photo URI-string helpers (`object Photos` — top-level, for `app_callback` handlers that receive `call.input.image: String`, library 1.1.13-pair+):\n" +
-            "  - Android: `suspend fun Photos.loadBase64(uri: String): String?` — bare base64 payload, ready for Anthropic Claude Vision / OpenAI GPT-4V request bodies. Fast path: `data:` URIs return the substring after the comma directly (no decode + re-encode round trip).\n" +
-            "  - Android: `suspend fun Photos.loadBytes(uri: String): ByteArray?` — raw image bytes (multipart upload, custom encoders).\n" +
-            "  - Android: `suspend fun Photos.loadBitmap(uri: String): Bitmap?` — same Bitmap result as `photo.loadBitmap()` but takes the URI string the handler actually receives.\n" +
-            "  - Android: `fun Photos.mediaTypeFromUri(uri: String): String?` — `\"image/jpeg\"` / `\"image/png\"` / `\"image/webp\"` / etc. Reads the embedded MIME from `data:` URIs, infers from file extension otherwise. Most AI vision APIs need both base64 + media type.\n" +
-            "  - All loaders run on `Dispatchers.IO`, return null on missing file / decode failure / OOM, never throw. Use `java.util.Base64` (JVM-standard) so the helpers are JVM-unit-testable.\n" +
-            "  - iOS: equivalent `Photos.loadBase64(uri:)`, `Photos.loadBytes(uri:)`, `Photos.loadImage(uri:)`, `Photos.mediaType(forUri:)` are landing in a follow-up library cut. Until then iOS handlers can take the existing `loadImage()` extension if they hold a `Photo` object, or do the URI decode inline.\n\n" +
-            "  Video URI-string helpers (`object Videos` — top-level, library 1.1.14-pair+, mirrors Photos for `capture_video.uri`):\n" +
-            "  - Android: `suspend fun Videos.copyToFile(uri: String, dst: File): Boolean` — the canonical save-to-gallery path. Streams from `file://` / bare-path sources via `File.copyTo`; decodes `data:` URIs in-memory. Creates parent dirs, overwrites dst, returns true/false (no throw).\n" +
-            "  - Android: `suspend fun Videos.loadBytes(uri: String): ByteArray?` — raw bytes (for inline-video AI APIs like Gemini 1.5 Pro). Loads the whole clip in memory — prefer `copyToFile` for clips >50 MB.\n" +
-            "  - Android: `suspend fun Videos.loadBase64(uri: String): String?` — base64 with the same `data:` URI fast path.\n" +
-            "  - Android: `fun Videos.mediaTypeFromUri(uri: String): String?` — `\"video/mp4\"`, `\"video/quicktime\"`, `\"video/webm\"`, `\"video/x-matroska\"`, `\"video/x-msvideo\"`, `\"video/x-m4v\"`, `\"video/3gpp\"`. Reads `data:video/<type>;...` MIME directly; falls back to extension match.\n" +
-            "  - All loaders run on `Dispatchers.IO`, never throw.\n" +
-            "  - iOS parity is queued (handoff at `shared-context/ios-videos-helpers-handoff.md`); until that lands, iOS handlers should hand-roll the `data:` / `file://` branch.\n\n" +
-            "── glasses.audio ── (`AudioClient`)\n" +
-            "- `suspend fun recordDiscrete(config: AudioRecordConfig = AudioRecordConfig()): ExtentosResult<AudioRecording, AudioError>` — bounded clip with auto-STT. Same path the `record_audio` block uses.\n" +
-            "- `fun audioChunks(config: AudioChunkConfig = AudioChunkConfig()): Flow<AudioChunk>` — raw audio chunk stream.\n" +
-            "- `fun transcriptions(config: TranscriptionConfig = TranscriptionConfig()): Flow<Transcript>` — live STT stream (Partial + Final). The same stream the `transcription_incremental` stream type and the `voice_command` matcher consume; also the underlying source for the push-to-talk helper below.\n" +
-            "- `suspend fun speak(text: String, config: SpeakConfig = SpeakConfig()): ExtentosResult<Unit, AudioError>` — TTS.\n" +
-            "- `suspend fun earcon(sound: EarconSound, volume: Double = 1.0)` — short canned tone.\n\n" +
-            "  Push-to-talk helper (extension on `AudioClient`, returns a `PushToTalkSession`):\n" +
-            "  - Android: `fun AudioClient.startPushToTalk(scope: CoroutineScope, config: TranscriptionConfig = TranscriptionConfig(language = \"en-US\", partial = false)): PushToTalkSession` — call on press; subscribes to `transcriptions(config)` in `scope` and accumulates `Transcript.Final` segments. Cancelling `scope` also stops the session.\n" +
-            "  - iOS: `func startPushToTalk(config: TranscriptionConfig = TranscriptionConfig(language: \"en-US\", partial: false)) -> PushToTalkSession` — same shape; uses an internal unstructured Task so no scope parameter.\n" +
-            "  - `suspend fun PushToTalkSession.stopAndFlush(): String` (Android) / `func stopAndFlush() async -> String` (iOS) — call on release; cancels the underlying subscription and returns the joined text of every Final transcript received during the session. Idempotent.\n" +
-            "  - Standard usage: on press, `val session = audio.startPushToTalk(scope)` (or `let session = audio.startPushToTalk()`); on release, `val text = session.stopAndFlush()` then `runtime.fireTrigger(triggerId, mapOf(\"transcript\" to JsonPrimitive(text), \"rawUtterance\" to JsonPrimitive(text)))`. See `searchDocs(topic: 'trigger_types')` push_to_talk section for the full both-platforms snippet.\n\n" +
-            "── glasses.runtime ── (`RuntimeClient`)\n" +
-            "- `val events: Flow<RuntimeEvent>` — every runtime event (TriggerFired, BlockStarted, AppCallbackInvoked, FlowCompleted, Log, HandlerFailure, etc.). Tap from on-device diagnostics or to mirror to your own logger.\n" +
-            "- `suspend fun loadSpec(jsonString: String): ExtentosResult<LoadedSpecInfo, List<SpecValidationError>>` — load/replace the spec. Bootstrap calls this from assets at startup.\n" +
-            "- `fun currentSpec(): ExtentosSpec?` — currently-loaded spec (null until loadSpec succeeds).\n" +
-            "- `suspend fun fireTrigger(triggerId: String, payload: Map<String, JSONValue> = emptyMap()): FlowEndCause` — programmatically fire a trigger. The unified API for host-side trigger firing. There is no `runtime.invokeManualLaunch()`; for `manual_launch`, call `fireTrigger` directly. For `push_to_talk` the recommended path is `audio.startPushToTalk()` + `session.stopAndFlush()` (above), which wraps `transcriptions()` collection and ultimately calls `fireTrigger` for you.\n" +
-            "- `suspend fun snapshotEvents(): List<RuntimeEvent>` — drain the on-device 512-entry ring buffer for export.\n\n" +
-            "── glasses.toggles ── (`ToggleClient`)\n" +
-            "- `val state: StateFlow<Map<String, JSONValue>>` — observe all 8 toggles' current values.\n" +
-            "- `fun put(key: String, value: JSONValue, source: ToggleSource = ToggleSource.UI)` — set a toggle. Same surface a `set_toggle` action drives.\n" +
-            "- `fun get(key: String): JSONValue?` — read one toggle.\n\n" +
-            "── glasses.extensions ── (`ExtensionsClient`)\n" +
-            "- `fun registerAppCallbackHandler(handler: AppCallbackHandler)` — wire the dispatch lambda generated by `generateConsumer(kind: \"callback\")`. Bootstrap registers this once; all `app_callback` actions route through it.\n" +
-            "- `fun registerCustomBlock(type, handler)` — `@ExperimentalExtentosApi`. Define your own block type; the spec's `block_call` resolves it.\n" +
-            "- `fun registerCustomTrigger(type, factory)` — `@ExperimentalExtentosApi`. Same idea for triggers.\n\n" +
-            "── glasses.debug ── (`DebugClient`)\n" +
-            "- `suspend fun injectVoiceCommand(transcript, confidence)` — bypass STT, inject a transcript directly. Useful for unit tests + the bypass-button path in the simulator.\n" +
-            "- `suspend fun injectHardwareAlert(alert)` — fake a thermal/hinges/audio-route event.\n" +
-            "- `suspend fun setConnectionState(state)` — fake a transport state for testing.\n" +
-            "- `suspend fun mockAppCallback(handler, result)` — return canned data from a handler without running its body.\n" +
-            "- `suspend fun clearAllMocks()` — reset all debug overrides.\n" +
-            "- `suspend fun setSimulatorSession(url)` — programmatically swap simulator URL at runtime.\n\n" +
-            "── glasses.telemetry ── (`TelemetryClient`)\n" +
-            "- `val consent: Boolean` — read current telemetry consent state.\n" +
-            "- `fun setUserSegment(segment)` — tag the install for cohort analysis.\n" +
-            "- `fun trackEvent(name, properties)` — emit a custom telemetry event (subject to consent).\n\n" +
-            "── Type guide (commonly-needed) ──\n" +
-            "- `JSONValue` is `kotlinx.serialization.json.JsonElement` (Android) / equivalent on iOS. Build with `JsonPrimitive(...)` / `buildJsonObject { put(\"k\", v) }`.\n" +
-            "- `AppCall` exposes `handler: String`, `input: JSONValue` (always a JsonObject), `flowContext: FlowContext`, and on Android `applicationContext: android.content.Context?` (1.1.16-pair+) — non-null when the bootstrap was created with `ExtentosConfig.applicationContext = this`. Read inputs via `call.input.jsonObject[\"key\"]?.jsonPrimitive?.contentOrNull`. iOS handlers use `FileManager.default` / `UserDefaults.standard` / `Bundle.main` for app-level access — there's no iOS analog field on AppCall.\n" +
-            "- `AppCallbackResult.Success(JsonElement)` populates the flow's `save_as`; `AppCallbackResult.Error(code, message)` short-circuits the flow.",
-        keywords: ["library", "api", "extentosglasses", "config", "subclient", "create", "register", "runtime", "loadSpec", "ExtentosResult", "fireTrigger", "transcriptions", "audioClient", "cameraClient", "extensionsClient", "togglesClient", "debugClient", "manual_launch", "push_to_talk", "loadBitmap", "loadImage", "loadBase64", "loadBytes", "Photos", "mediaTypeFromUri", "startPushToTalk", "PushToTalkSession", "Photo", "Bitmap", "PlatformImage", "UIImage", "vision", "anthropic", "openai"],
-        relatedTools: ["generateConnectionModule", "generateConsumer"],
-    },
-    {
-        topic: "app_callback_guide",
-        title: "App Callback Handlers",
-        content: "app_callback routes flow control from the spec into the developer's native code — for AI calls, domain logic (DB writes, file IO, repository ops), or external service access. Register via glasses.extensions.registerAppCallbackHandler(handler). AppCall carries the handler name, the input map declared in the spec's app_callback action, and caller context (triggerId, flowId). Returning AppCallbackResult.Success(value) populates the flow's save_as variable; returning Error short-circuits the flow. Timeouts surface as 'callback.timeout' events.\n\n" +
-            "── Handler stub generation ──\n" +
-            "Call generateConsumer(kind: 'callback', handlers: [...]) → emits ExtentosCallbacks.{kt,swift} with marker-bounded dispatch and a USER-CODE block per handler for your implementation. The bootstrap dispatch region gets a replace_region patch that wires registration. Pass `suggestedProvider: 'anthropic' | 'openai' | ...` to get an AI-provider-specific TODO comment in the stub body; omit it for a generic implementation TODO suitable for non-AI handlers.\n\n" +
-            "Android handler shape (Kotlin):\n" +
-            "  private suspend fun handleSaveClip(call: AppCall): AppCallbackResult {\n" +
-            "      // USER-CODE-START:save_clip\n" +
-            "      val uri = call.input.jsonObject[\"uri\"]?.jsonPrimitive?.contentOrNull\n" +
-            "          ?: return AppCallbackResult.Error(code = \"missing_uri\", message = \"input.uri was null\")\n" +
-            "      val bytes = Photos.loadBytes(uri)\n" +
-            "          ?: return AppCallbackResult.Error(code = \"decode_failed\", message = \"could not read \\$uri\")\n" +
-            "      val savedAt = MyClipRepository.persist(bytes)\n" +
-            "      return AppCallbackResult.Success(buildJsonObject { put(\"savedAt\", savedAt) })\n" +
-            "      // USER-CODE-END:save_clip\n" +
+        content: "ExtentosGlasses is the top-level handle. Identical-shape sub-clients on Android (Kotlin) and iOS (Swift). Construction:\n\n" +
+            "  Android: `val glasses = ExtentosGlasses.create(ExtentosConfig(applicationContext = this, debug = BuildConfig.DEBUG))`\n" +
+            "  iOS:     `let glasses = Extentos.create(config: ExtentosConfig(debug: isDebugBuild, telemetryConsent: true))`\n\n" +
+            "**Result types.** Android suspending ops return `ExtentosResult<T, E>` (sealed `Ok` / `Err`). Pattern-match — do NOT wrap in Kotlin `runCatching`, which only catches thrown exceptions and would miss `Err` variants. iOS uses the same `ExtentosResult<T, E>` enum (`.success(T)` / `.failure(E)`), so `try? await glasses.audio.speak(...)` is wrong — use `guard case .success = await glasses.audio.speak(...) else { ... }`. The capability guides (`getCapabilityGuide(feature: ...)`) show the per-feature unwrap pattern for every op.\n\n" +
+            "── glasses.connection ── (ConnectionClient)\n\n" +
+            "- `state` — `StateFlow<GlassesState>` (Android) / `ObservableState<GlassesState>` (iOS, iterate via `.stream`). 6 buckets: `notRegistered`, `registered`, `deviceDiscovered(DeviceId)`, `connecting(DeviceId)`, `active(ActiveState)`, `disconnected(DisconnectCause)`.\n" +
+            "- `simulatorHint` — `StateFlow<SimulatorHint?>` / `ObservableState<SimulatorHint?>`. Non-null when the active transport is BrowserSim or LocalSim; UI surfaces a hint badge so users know they're not on real hardware.\n" +
+            "- `connect(deviceId: DeviceId? = null)` — opens the persistent transport. Bootstrap calls this in `onCreate` / on init.\n" +
+            "- `disconnect()` — graceful tear-down. Reverses `connect`; safe to call repeatedly.\n\n" +
+            "── glasses.camera ── (CameraClient)\n\n" +
+            "- `capturePhoto(config: PhotoConfig = ...)` — one-shot still. Returns a `Photo` with `uri` (Android: String) / `url` (iOS: URL), width, height, format.\n" +
+            "- `captureVideo(config: VideoConfig = ...)` — bounded clip (silence-VAD or max duration). Returns a `VideoClip`.\n" +
+            "- `videoFrames(config: VideoFrameConfig = ...)` — continuous frame stream. Kotlin `Flow<VideoFrame>`, iOS `AsyncStream<VideoFrame>`.\n\n" +
+            "**Photo display helpers (extension on `Photo`):**\n" +
+            "  Android: `suspend fun Photo.loadBitmap(): Bitmap?` runs on `Dispatchers.IO`; handles `data:` (BrowserSim base64), `file://` (RealMeta + LocalSim), and bare paths uniformly. Returns null on missing file / decode failure / unrecognized scheme. Use this instead of Coil's `AsyncImage`, which silently fails on `data:` URIs.\n" +
+            "  iOS: `func Photo.loadImage() async -> PlatformImage?` (`UIImage` on iOS, `NSImage` on macOS). Same scheme dispatch; decode runs on a detached high-priority Task.\n\n" +
+            "**Photo URI-string helpers (`object Photos`, Android only — for handler code that already has a URI String):**\n" +
+            "  - `suspend fun Photos.loadBase64(uri: String): String?` — bare base64 ready for Claude Vision / GPT-4V bodies. Fast path on `data:` URIs (no decode + re-encode).\n" +
+            "  - `suspend fun Photos.loadBytes(uri: String): ByteArray?` — raw bytes (multipart upload, custom encoders).\n" +
+            "  - `suspend fun Photos.loadBitmap(uri: String): Bitmap?` — same result as `photo.loadBitmap()` from a URI String.\n" +
+            "  - `fun Photos.mediaTypeFromUri(uri: String): String?` — `image/jpeg` / `image/png` / `image/webp` / etc.\n" +
+            "  - All loaders run on `Dispatchers.IO`, return null on failure, never throw.\n" +
+            "  - iOS parity (`Photos` namespace) is queued; current iOS handlers use `Photo.loadImage()` if they hold a Photo, or hand-roll the `data:` / `file://` branch from a URL.\n\n" +
+            "**Video URI-string helpers (`object Videos`, Android only):**\n" +
+            "  - `suspend fun Videos.copyToFile(uri: String, dst: File): Boolean` — the canonical save-to-gallery path. Streams `file://` / bare-path; decodes `data:` URIs in-memory.\n" +
+            "  - `suspend fun Videos.loadBytes(uri: String): ByteArray?` — raw bytes (inline-video AI APIs like Gemini 1.5 Pro). Prefer `copyToFile` for clips >50 MB.\n" +
+            "  - `suspend fun Videos.loadBase64(uri: String): String?` / `fun Videos.mediaTypeFromUri(uri: String): String?` — mirrors Photos.\n" +
+            "  - iOS parity queued.\n\n" +
+            "── glasses.audio ── (AudioClient)\n\n" +
+            "- `recordDiscrete(config: AudioRecordConfig = ...)` — bounded clip with built-in silence-VAD and auto-transcription. Returns `AudioRecording` with `transcript`, `audioDurationMs`, `rawAudioUri`. The canonical free-form-question-capture primitive.\n" +
+            "- `audioChunks(config: AudioChunkConfig = ...)` — raw audio chunk stream for custom on-device STT / passthrough.\n" +
+            "- `transcriptions(config: TranscriptionConfig = ...)` — continuous Partial + Final transcript stream. The wake-phrase primitive (subscribe + match strings) AND the live-captions primitive.\n" +
+            "- `speak(text: String, config: SpeakConfig = ...)` — TTS via the platform engine (Android TextToSpeech, iOS AVSpeechSynthesizer). Audio bytes route over HFP to the glasses speaker. Blocks until done by default; for parallel listen-and-speak run it in its own coroutine/Task.\n" +
+            "- `cancelSpeak()` — interrupt the currently-speaking utterance immediately (the barge-in primitive). Fire-and-forget; idempotent. See the `barge_in_speak` getCodeExample for the canonical TaskGroup / structured concurrency pattern.\n" +
+            "- `earcon(sound: EarconSound, volume: Double = 1.0)` — short canned tone (START / COMPLETE / ERROR / NOTIFY).\n\n" +
+            "**Push-to-talk helper (extension on `AudioClient`):**\n" +
+            "  Android: `fun AudioClient.startPushToTalk(scope: CoroutineScope, config: TranscriptionConfig = TranscriptionConfig(language = \"en-US\", partial = false)): PushToTalkSession`\n" +
+            "  iOS:     `func startPushToTalk(config: TranscriptionConfig = ...) -> PushToTalkSession`\n" +
+            "  Call on press; subscribes to `transcriptions(config)` and accumulates `Transcript.Final` segments. Call `stopAndFlush()` on release — returns the joined text of every Final transcript received during the session. Idempotent; cancellation-safe.\n\n" +
+            "── glasses.runtime ── (RuntimeClient)\n\n" +
+            "- `events` — `Flow<RuntimeEvent>` (Android) / `AsyncStream<RuntimeEvent>` (iOS). Capability-layer events (toggle changed, connection state changed, capability stream lifecycle, log entries, unrecognized utterances). Tap for in-app diagnostics or to mirror to your own logger / crash reporter.\n" +
+            "- `snapshotEvents()` — drain the on-device 512-entry ring buffer (suspend / async). Useful for one-shot export at app exit.\n\n" +
+            "*Note: pre-pivot RuntimeClient also exposed `loadSpec`, `currentSpec`, `fireTrigger`, and rich `RuntimeEvent` variants like `TriggerFired`/`BlockStarted`/`AppCallbackInvoked`/`FlowCompleted`. Those are gone — the library no longer interprets a spec, and trigger/block/callback events are no longer emitted. The remaining `RuntimeEvent` variants are `ToggleChanged`, `CoexistenceWarning`, `Log`, `UnrecognizedUtterance` plus capability-stream lifecycle events.*\n\n" +
+            "── glasses.toggles ── (ToggleClient)\n\n" +
+            "- `state` — `StateFlow<Toggles>` (Android) / `ObservableState<Toggles>` (iOS). Observe all 8 toggles' current values; see `searchDocs(topic: 'toggles')` for the full list.\n" +
+            "- `update { transform }` — closure form for setting toggles atomically. The canonical API on both platforms.\n" +
+            "- `put(key: String, value: JSONValue, source: ToggleSource = ToggleSource.UI)` — Android only convenience; rarely needed in customer code (the user owns toggle values via the connection page UI).\n" +
+            "- `get(key: String): JSONValue?` — read one toggle without subscribing.\n\n" +
+            "── glasses.debug ── (DebugClient)\n\n" +
+            "- `injectVoiceCommand(transcript, confidence)` — bypass STT, inject a transcript directly. Useful for unit tests + the simulator's bypass-button path.\n" +
+            "- `injectHardwareAlert(alert)` — fake a thermal / hinges / audio-route event.\n" +
+            "- `setConnectionState(state)` — fake a transport state for testing.\n" +
+            "- `clearAllMocks()` — reset all debug overrides.\n" +
+            "- `setSimulatorSession(url)` — programmatically swap simulator URL at runtime.\n\n" +
+            "── glasses.telemetry ── (TelemetryClient)\n\n" +
+            "- `consent: Boolean` — read current consent state.\n" +
+            "- `setUserSegment(segment)` — tag the install for cohort analysis.\n" +
+            "- `trackEvent(name, properties)` — emit a custom telemetry event (subject to consent).\n\n" +
+            "── Type guide ──\n\n" +
+            "- `JSONValue` is `kotlinx.serialization.json.JsonElement` (Android) / sealed enum (iOS). Build via `JsonPrimitive(...)` / `buildJsonObject { put(\"k\", v) }` on Android; `.string(...)` / `.bool(...)` / `.object_(...)` on iOS. Pattern-match to read on both.\n" +
+            "- `Transcript` is a sealed type — Kotlin uses `data class Partial(...)` / `Final(...)`; iOS uses `case partial(text:, confidence:)` / `final(text:, startMs:, endMs:, confidence:)`. Pattern-match to extract the text + finality.\n" +
+            "- `Photo.uri` (Android, String) vs `Photo.url` (iOS, URL) — note the platform difference.\n" +
+            "- `GlassesState.active(ActiveState)` carries an associated value on iOS; pattern-bind to read it. Kotlin uses `is GlassesState.Active` with property access.\n\n" +
+            "── Customer-side handler structure ──\n\n" +
+            "Your code subscribes to these primitives from a Handler class (your own naming) instantiated in your Application / @main App. There is no library-side registration step; nothing to `register`. `searchDocs(topic: 'custom_handlers')` shows the canonical handler shape; `getCodeExample(pattern)` returns full compositions for the 6 common voice-glasses use cases.",
+        keywords: ["library", "api", "extentosglasses", "config", "subclient", "create", "ExtentosResult", "transcriptions", "audioClient", "cameraClient", "togglesClient", "debugClient", "telemetryClient", "connectionClient", "loadBitmap", "loadImage", "loadBase64", "loadBytes", "Photos", "Videos", "mediaTypeFromUri", "startPushToTalk", "PushToTalkSession", "Photo", "Bitmap", "PlatformImage", "UIImage", "vision", "anthropic", "openai", "cancelSpeak", "barge_in"],
+        relatedTools: ["generateConnectionModule", "getCapabilityGuide", "getCodeExample"],
+    },
+    {
+        topic: "custom_handlers",
+        title: "Custom Handlers",
+        content: "Post pure-SDK, there's no spec runtime and no `app_callback` action — handlers are just normal Kotlin/Swift code you write. You subscribe to SDK Flows (transcripts, video frames, hardware events) and call SDK methods (`glasses.audio.speak`, `glasses.camera.capturePhoto`, `glasses.audio.recordDiscrete`) from your handler. No special registration, no dispatch table, no AppCall envelope — your class IS the handler.\n\n" +
+            "── Canonical handler shape (Android, Kotlin) ──\n\n" +
+            "Write a class that takes the `ExtentosGlasses` reference and your domain dependencies. Start it from your Application or a ViewModel:\n\n" +
+            "  class CoachHandler(\n" +
+            "      private val glasses: ExtentosGlasses,\n" +
+            "      private val anthropic: AnthropicClient,\n" +
+            "      private val repo: WorkoutRepository,\n" +
+            "  ) {\n" +
+            "      private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)\n\n" +
+            "      fun start() = scope.launch {\n" +
+            "          // Wake phrase: subscribe to transcripts, match strings yourself.\n" +
+            "          glasses.audio.transcriptions().collect { t ->\n" +
+            "              if (t.isFinal && \"ask my coach\" in t.text.lowercase()) {\n" +
+            "                  glasses.audio.speak(\"What would you like to know?\")\n" +
+            "                  val q = glasses.audio.recordDiscrete(\n" +
+            "                      AudioRecordConfig(silenceTimeoutSeconds = 3.0)\n" +
+            "                  ).getOrNull() ?: return@collect\n" +
+            "                  val answer = anthropic.ask(q.transcript, repo.history())\n" +
+            "                  glasses.audio.speak(answer)\n" +
+            "              }\n" +
+            "          }\n" +
+            "      }\n\n" +
+            "      fun stop() = scope.cancel()\n" +
             "  }\n\n" +
-            "iOS handler shape (Swift):\n" +
-            "  private func handleSaveClip(_ call: AppCall) async -> AppCallbackResult {\n" +
-            "      // USER-CODE-START:save_clip\n" +
-            "      guard let uri = call.input.string(at: \"uri\") else {\n" +
-            "          return .error(code: \"missing_uri\", message: \"input.uri was null\")\n" +
-            "      }\n" +
-            "      ...\n" +
-            "      // USER-CODE-END:save_clip\n" +
+            "── Canonical handler shape (iOS, Swift) ──\n\n" +
+            "  actor CoachHandler {\n" +
+            "      private let glasses: any ExtentosGlasses\n" +
+            "      private let anthropic: AnthropicClient\n" +
+            "      private let repo: WorkoutRepository\n" +
+            "      private var task: Task<Void, Never>?\n\n" +
+            "      func start() {\n" +
+            "          task = Task {\n" +
+            "              for await t in glasses.audio.transcriptions() {\n" +
+            "                  guard t.isFinal,\n" +
+            "                        t.text.lowercased().contains(\"ask my coach\")\n" +
+            "                  else { continue }\n" +
+            "                  try? await glasses.audio.speak(\"What would you like to know?\")\n" +
+            "                  let q = try? await glasses.audio.recordDiscrete(\n" +
+            "                      AudioRecordConfig(silenceTimeoutSeconds: 3.0)\n" +
+            "                  )\n" +
+            "                  guard let q = q else { continue }\n" +
+            "                  let answer = try? await anthropic.ask(q.transcript, history: repo.history())\n" +
+            "                  if let answer { try? await glasses.audio.speak(answer) }\n" +
+            "              }\n" +
+            "          }\n" +
+            "      }\n\n" +
+            "      func stop() { task?.cancel() }\n" +
             "  }\n\n" +
-            "── Reading structured input ──\n" +
-            "`call.input` is always a JsonObject (or its iOS equivalent). Read fields with kotlinx.serialization's accessors:\n" +
-            "  - `call.input.jsonObject[\"key\"]?.jsonPrimitive?.contentOrNull` — String (null if missing or non-string)\n" +
-            "  - `call.input.jsonObject[\"key\"]?.jsonPrimitive?.intOrNull` — Int (works on number primitives)\n" +
-            "  - `call.input.jsonObject[\"key\"]?.jsonPrimitive?.booleanOrNull` — Bool\n" +
-            "  - `call.input.jsonObject[\"key\"]?.jsonObject` — nested object (unwrap recursively)\n" +
-            "  - `call.input.jsonObject[\"key\"]?.jsonArray` — array\n" +
-            "iOS exposes the same shape via `call.input.string(at:)`, `call.input.int(at:)`, etc. Template substitution from the spec (`input: { uri: \"{{photo.uri}}\" }`) resolves before the handler is invoked, so the handler only sees concrete values — never `{{...}}` literals.\n\n" +
-            "── Reading Application Context (Android) ──\n" +
-            "**Android handlers can access the host's Application `Context` via `call.applicationContext` (library 1.1.16-pair+).** Non-null whenever the host app passed `applicationContext = this` from `Application.onCreate` (the canonical bootstrap flow that `generateConnectionModule` emits). Use it for any handler that needs Android system access:\n" +
-            "  - `call.applicationContext?.filesDir` — save-to-gallery / persist-to-disk paths. Canonical for the `voice_command → capture_video → app_callback save_clip` flow that uses `Videos.copyToFile(uri, dst)`.\n" +
-            "  - `call.applicationContext?.contentResolver` — MediaStore inserts so saved clips appear in the system gallery app.\n" +
-            "  - `call.applicationContext?.getSystemService(...)` — system services (PowerManager, NotificationManager, etc.).\n" +
-            "  - `androidx.preference.PreferenceManager.getDefaultSharedPreferences(call.applicationContext)` — shared preferences.\n" +
-            "Always null-check: a few minority configurations build the library with `applicationContext = null` (browser-sim-only test setups, headless harnesses). Return `AppCallbackResult.Error(\"no_context\", \"...\")` if you need it but it's null.\n" +
-            "iOS doesn't have an equivalent — Apple's runtime exposes app-level singletons globally (`FileManager.default`, `UserDefaults.standard`, `Bundle.main`, `NSPersistentContainer.viewContext`), so iOS handlers don't need a Context-bridge field on `AppCall`. Use those singletons directly.\n\n" +
-            "── Returning results ──\n" +
-            "**AppCallbackResult.Success(value)** — populates the flow's `save_as` variable with `value` (a JsonElement). Subsequent actions can reference it via `{{save_as}}` or `{{save_as.field}}`. Use this for normal completion AND for handled-error-as-data cases (e.g. `Success(buildJsonObject { put(\"ok\", false); put(\"reason\", \"empty\") })`) when the spec branches on the result.\n\n" +
-            "**AppCallbackResult.Error(code, message)** — short-circuits the flow. The trigger's `on_failure` policy decides whether subsequent actions run (`continue`) or the entire flow aborts (`abort`, default for app_callback errors). Use this for unhandled errors where the rest of the flow doesn't make sense (e.g. network down, auth failed, decode_failed).\n\n" +
-            "Rule of thumb: if a downstream `branch` action would inspect the result's `ok` field, return `Success({ok: false, ...})`. If the flow has no useful path forward without this handler succeeding, return `Error(code, message)`.\n\n" +
-            "── Timeouts ──\n" +
-            "Handlers have a default 10-second timeout per call. Override per action via `timeout_ms` (e.g. `{ type: \"app_callback\", handler: \"slow_ai\", timeout_ms: 30000, input: {...} }`). On timeout the runtime emits `callback.timeout` to the event log and the trigger's `on_failure` policy fires. Long-running work (AI generation, file IO over a slow network) should set `timeout_ms` generously — this is a hard kill, not a graceful cancel.\n\n" +
-            "── Performance + threading ──\n" +
-            "**Android:** handlers are invoked from a coroutine on `Dispatchers.Default`. Suspend functions can call `withContext(Dispatchers.IO)` for blocking IO — the library does NOT pin the handler to the main thread.\n" +
-            "**iOS:** handlers are `async` functions invoked from a Task at `.userInitiated` priority. Use `Task.detached(priority: .utility)` for CPU-heavy work.\n\n" +
-            "Heavy workloads (LLM calls, large file decodes) run inline in the handler — that's fine, the runtime expects it. Don't `launch` background work and return immediately; the result will be ignored. If you need fire-and-forget, do it after returning Success.\n\n" +
-            "── Multi-handler dispatch ──\n" +
-            "Each spec handler name (the `handler` field of an `app_callback` action) gets its own private function in ExtentosCallbacks.kt / .swift. The generated `handle(call:)` entry point dispatches by `call.handler`:\n" +
-            "  override suspend fun handle(call: AppCall): AppCallbackResult = when (call.handler) {\n" +
-            "      \"save_clip\" -> handleSaveClip(call)\n" +
-            "      \"describe_scene\" -> handleDescribeScene(call)\n" +
-            "      \"send_to_slack\" -> handleSendToSlack(call)\n" +
-            "      else -> AppCallbackResult.Error(code = \"unknown_handler\", message = \"no handler for \\${call.handler}\")\n" +
-            "  }\n" +
-            "Adding a new handler: add the action to the spec via updateSpec, then re-run generateConsumer to emit the new dispatch arm + USER-CODE block. Existing USER-CODE bodies are preserved (server-side merge if you pass projectPath, agent-side otherwise — see file_actions topic).\n\n" +
-            "── Common mistakes ──\n" +
-            "- Returning `Success(JsonNull)` to indicate failure — confuses downstream branches. Use `Error(code, message)` or `Success({ok: false})` consistently.\n" +
-            "- Reading `call.input` as a Map<String, String> directly — JSON values are JsonElement; cast or unwrap explicitly.\n" +
-            "- Doing async work via `launch { ... }` and returning Success immediately — the launched work outlives the handler and its result is discarded. Do all work synchronously (within the suspend function) before returning.\n" +
-            "- Setting `timeout_ms: 1000` for an LLM call — anthropic / openai p95 is 3-8s; pick `timeout_ms: 15000` or higher for streaming, more for non-streaming.\n" +
-            "- Forgetting to register the handler — generateConsumer emits the registration call inside the bootstrap's EXTENTOS-GENERATED-START:dispatch region; if you copy-paste handlers without re-running generateConsumer, registration drifts and handlers never fire.",
-        keywords: ["app_callback", "callback", "handler", "register", "appcall", "timeout", "byok", "user-code", "dispatch", "appcallbackresult", "input", "json", "threading", "dispatcher"],
-        relatedTools: ["generateConsumer", "getCredentialGuide", "updateSpec"],
-    },
-    {
-        topic: "voice_proxy",
-        title: "Simulator Voice Proxy",
-        content: "Simulator-time STT + TTS runs on Extentos infrastructure — automatic inside BrowserSimTransport, no developer code. Rides on the simulator event meter (anonymous or account tier). Production voice is phone-native: Android SpeechRecognizer + TextToSpeech; iOS SFSpeechRecognizer + AVSpeechSynthesizer + AVAudioSession. Zero Extentos runtime path in production.",
-        keywords: ["voice_proxy", "stt", "tts", "simulator", "meter", "proxy", "production voice"],
+            "── Lifecycle ──\n\n" +
+            "Start the handler from your Application onCreate (Android) or AppDelegate / SceneDelegate (iOS), passing in the same `glasses` instance you used for `ExtentosConnectionPage`. Cancel on app teardown. Multiple handlers can coexist — each owns its own scope/task and listens to its own subset of SDK flows.\n\n" +
+            "── Reading Application Context (Android) ──\n\n" +
+            "Your handler class can hold whatever it needs at construction — including the host's `Context`:\n\n" +
+            "  class SavePhotoHandler(\n" +
+            "      private val glasses: ExtentosGlasses,\n" +
+            "      private val context: Context,\n" +
+            "  ) { ... }\n\n" +
+            "Use `context.filesDir` for save-to-gallery paths, `context.contentResolver` for MediaStore inserts, `context.getSystemService(...)` for system services. No special bridge field — it's regular Android code.\n\n" +
+            "── Returning results ──\n\n" +
+            "There's nothing to \"return\" to — your handler runs in your scope; it does what it wants. The library doesn't poll your handler for results. If you need to surface state to your UI, use a `StateFlow` / `@Published` property or your existing state management; if you need to chain SDK operations, call them sequentially in the handler.\n\n" +
+            "── Errors ──\n\n" +
+            "SDK methods return `ExtentosResult<T, E>` (Kotlin) or throw (Swift). Handle them with normal language patterns:\n\n" +
+            "  Kotlin: `val photo = glasses.camera.capturePhoto().getOrNull() ?: return`\n" +
+            "  Swift:  `guard let photo = try? await glasses.camera.capturePhoto() else { return }`\n\n" +
+            "No timeout system — wrap calls in `withTimeoutOrNull` / `Task.withTimeout` if your domain needs a deadline. No global retry policy — write your own. Everything that was implicit in the spec runtime (timeouts, branch-on-result, on_failure) is now explicit in your code.\n\n" +
+            "── Threading ──\n\n" +
+            "**Android:** start handlers on a `CoroutineScope(SupervisorJob() + Dispatchers.Default)`. Use `withContext(Dispatchers.IO)` for blocking IO. SDK methods are `suspend` and safe to call from any dispatcher.\n\n" +
+            "**iOS:** start handlers in a `Task` or actor. SDK methods are `async`; the runtime threads them onto the cooperative pool.\n\n" +
+            "── Common mistakes ──\n\n" +
+            "- Subscribing to `glasses.audio.transcriptions()` multiple times from different scopes — each subscription is independent and they don't share state. Subscribe once per use case.\n" +
+            "- Forgetting to call `scope.cancel()` / `task?.cancel()` on teardown — the handler keeps running forever, holding `glasses` alive. Tie lifecycle to your Application / scene.\n" +
+            "- Doing fire-and-forget background work inside a `.collect { ... }` block without launching a new coroutine — blocks the collector. Wrap in `launch { ... }` if you want concurrent processing of incoming events.\n" +
+            "- Importing the BuildConfig pattern for API keys — kotlinc inlines `BuildConfig.MY_KEY` at compile time and stale keys silently survive rotations. Use `resValue` + `context.getString(R.string.my_key)` instead. See getCredentialGuide for the canonical pattern.",
+        keywords: ["handler", "custom_handlers", "kotlin", "swift", "sdk", "subscribe", "flow", "scope", "lifecycle", "byok"],
+        relatedTools: ["generateConnectionModule", "getCredentialGuide"],
+    },
+    {
+        topic: "voice_integration",
+        title: "Voice Integration",
+        content: "Voice (STT + TTS) is bridged through the SDK: `glasses.audio.transcriptions()` for continuous transcripts, `glasses.audio.recordDiscrete()` for one-shot capture-with-silence-VAD, `glasses.audio.speak()` for TTS. Same API in browser-sim and on real hardware — only the transport underneath differs.\n\n" +
+            "**Simulator transport** routes audio through the browser tab's Web Speech API → Whisper fallback (STT) and Web SpeechSynthesisUtterance (TTS). Runs on Extentos infrastructure; no developer code beyond calling the SDK. Rides the simulator event meter (anonymous or account tier).\n\n" +
+            "**Production transport** routes audio through the phone's native engines: Android `SpeechRecognizer` + `TextToSpeech`; iOS `SFSpeechRecognizer` + `AVSpeechSynthesizer` + `AVAudioSession`. Zero Extentos runtime path — the library opens the phone APIs and surfaces results as the same `Transcript` / `AudioRecording` types your handler already consumes.\n\n" +
+            "Customer doesn't write transport-switching code — the SDK handles routing based on the active connection.",
+        keywords: ["voice", "stt", "tts", "transcriptions", "speak", "recordDiscrete", "voice_integration", "simulator", "proxy", "production voice"],
         relatedTools: ["createSimulatorSession", "getCredentialGuide"],
     },
     {
         topic: "custom_extensions",
-        title: "Custom Extensions",
-        content: "Escape hatches for capabilities beyond the spec: glasses.extensions.registerCustomBlock(name, impl) adds a block type; glasses.extensions.registerCustomTrigger(name, impl) adds a trigger type. Custom registrations live outside the generated /extentos directory in developer-owned code. Spec references the custom name like any built-in type.",
-        keywords: ["custom", "extension", "registerCustomBlock", "registerCustomTrigger", "escape hatch"],
-        relatedTools: ["generateConsumer"],
+        title: "Going Beyond Built-in Capabilities",
+        content: "Post pure-SDK, there is no `registerCustomBlock` / `registerCustomTrigger` escape hatch — there is no spec runtime that would dispatch to them. The library exposes the device's capabilities directly; anything you want to do beyond what `getPlatformInfo` lists, you build in your own handler code using whatever phone / cloud APIs you already use.\n\n" +
+            "**Examples of 'custom' extensions, post-pivot:**\n" +
+            "- Custom on-device STT — subscribe to `glasses.audio.audioChunks(...)` and feed the bytes into your model (e.g. Whisper.cpp, on-device CoreML). The library's built-in transcriptions stream is one consumer; nothing stops you from being another.\n" +
+            "- Custom vision model — subscribe to `glasses.camera.videoFrames(...)` or call `glasses.camera.capturePhoto()` and ship the bytes to your inference path. Nothing about the SDK is opinionated about where vision happens.\n" +
+            "- Custom TTS provider (e.g. ElevenLabs) — fetch the audio bytes yourself, then play them through the phone speaker OR fall back to `glasses.audio.speak(...)` for plain text. Direct routing of arbitrary audio bytes to the glasses speaker is a future SDK feature; for now, premium-voice TTS plays from the phone.\n" +
+            "- New hardware-event listeners — the library surfaces a fixed set of hardware alerts (thermal, hinges, audio route, call state, lifecycle). Anything not on the list isn't reachable from the SDK; ask for it in the Extentos repo / feedback channel.\n\n" +
+            "The SDK keeps a tight, vendor-validated surface intentionally — every primitive is something we can wire to multiple glasses vendors. Adding a primitive here means we commit to maintaining it across the line; custom one-off integrations belong in your handler, not the library.\n\n" +
+            "If you find yourself wishing for a missing primitive, see the feedback flow in `searchDocs(topic: 'getting_started')` — that's the path to getting it into the library.",
+        keywords: ["custom", "extension", "byo", "escape hatch", "missing capability", "stt", "tts", "vision", "audio chunks", "video frames"],
+        relatedTools: ["getPlatformInfo"],
     },
     {
         topic: "simulator_local_mode",
@@ -936,69 +433,84 @@ export const DOC_INDEX = [
     {
         topic: "simulator_browser_mode",
         title: "Simulator Browser Mode",
-        content: "Browser mode provisions a web UI via createSimulatorSession — agent receives sessionUrl, MCP attempts OS-native browser auto-open (best-effort), browser loads the spec and drives simulated hardware. WebSocket hub coordinates app ↔ browser ↔ optional observer. Supports injection (forced events) and replay of recorded sessions. Response includes `sessionUrl` + `autoOpenAttempted: boolean` + `autoOpenPlatform`. When `autoOpenAttempted: true`, the URL was sent to the developer's default browser — surface as a confirmation message (e.g., 'the simulator should be open in your browser'). When `autoOpenAttempted: false` (EXTENTOS_NO_AUTO_OPEN=1, headless/SSH/sandboxed environment, per-call `autoOpenBrowser: false`, or no compatible OS launcher), explicitly print the `sessionUrl` to the developer with copy-paste instructions. The URL is the guaranteed delivery channel — auto-open is a best-effort optimization.\n\n" +
+        content: "Browser mode provisions a web UI via createSimulatorSession — agent receives `sessionUrl`, MCP attempts OS-native browser auto-open (best-effort), the browser loads the simulator and drives a Meta-DAT-shaped transport stub. WebSocket hub coordinates app ↔ browser ↔ optional observer. Supports injecting events (transcripts, photo captures, hardware alerts) and replaying recorded sessions.\n\n" +
+            "Response includes `sessionUrl` + `autoOpenAttempted: boolean` + `autoOpenPlatform`. When `autoOpenAttempted: true`, the URL was sent to the dev's default browser — surface as a confirmation ('the simulator should be open in your browser'). When `autoOpenAttempted: false` (EXTENTOS_NO_AUTO_OPEN=1, headless/SSH/sandboxed environment, per-call `autoOpenBrowser: false`, or no compatible OS launcher), print the `sessionUrl` for the dev to copy. The URL is the guaranteed delivery channel — auto-open is a best-effort optimization.\n\n" +
             "── Persistent-sim model (get-or-create) ──\n\n" +
             "**`createSimulatorSession` is get-or-create, NOT mint-every-time.** A saved sim is keyed on `(account, projectInstallId, platform)` where `projectInstallId` derives from `extentos.manifest.json`'s `appPackage` (with `settings.gradle.kts` `rootProject.name` as fallback for unlabeled Android projects). Two response shapes:\n" +
             "- `status: \"active\"` — first call from this project; new sim minted.\n" +
-            "- `status: \"resumed\"` — saved sim already existed; same `sessionUrl`, no rebuild needed for URL-bake users. Spec is live-pushed if it changed since last resume.\n\n" +
+            "- `status: \"resumed\"` — saved sim already existed; same `sessionUrl`, no rebuild needed for URL-bake users.\n\n" +
             "Saved sims live on the user's dashboard at extentos.com/s. They have NO 24-hour absolute lifetime. After 30 minutes of inactivity (no role connected) a sim flips to `idle` — still listed on the dashboard, still resumable; reconnecting any role transitions it back to `waiting`/`active`. The 90-day cleanup sweep eventually purges abandoned `idle` rows (with a 7-day undo grace via `deleted` state).\n\n" +
             "**Multi-platform note:** Android and iOS versions of the same app share ONE project on the dashboard when the Android `applicationId` matches the iOS bundle identifier (the standard reverse-DNS convention). The platform-keyed slot still keeps them as two separate saved sims (one per platform) — they just appear under one card. When identifiers diverge, the dashboard's Settings → Danger Zone → Merge consolidates them. Full details: searchDocs(topic: 'multi_platform_projects').\n\n" +
-            "── Iteration model — what changes when ──\n\n" +
-            "Three things change independently during a typical dev loop, each at a different rate.\n\n" +
+            "── Iteration model: two things change at different rates ──\n\n" +
             "**1. THE SESSION** (the saved sim row + WebSocket hub)\n" +
             "- Persists indefinitely on the user's account. One per `(account, project, platform)`. No mint-per-iteration.\n" +
             "- Calling `createSimulatorSession` again with the same project returns the saved sim (`status: \"resumed\"`) — no new sessionId, no rebuild, no URL change.\n" +
             "- Need a clean ID/state? Call `createSimulatorSession({ resetFresh: true })` OR click \"Reset\" on the dashboard card. The previous sim is archived; a new sim is minted with the same project key. Live device sockets receive `session_moved` and re-bind automatically; URL-bake apps need one rebuild after force-fresh.\n" +
             "- Need to throw a sim away entirely? Click \"Delete\" on the dashboard card. 7-day undo grace.\n\n" +
-            "**2. THE SPEC** (`extentos.spec.json` content — blocks, streams, triggers, actions)\n" +
-            "- Live-pushed automatically. Every successful `updateSpec` call pushes the new spec over the existing WebSocket to the running app via the `spec_updated` frame. The library's `runtime.loadSpec()` applies it in-place; the app immediately knows about new triggers/blocks without a restart.\n" +
-            "- Response includes `liveSessionUpdate: { status: \"applied\", appNotified: true }` when this fires. **No rebuild, no reinstall, no remint.** Confirm via `getEventLog` (look for `runtime:SpecReloaded`).\n" +
-            "- Works for: changing trigger phrases, adding/removing/updating triggers, changing action sequences, swapping handler names — anything spec-shaped. The dev keeps testing immediately after the call returns.\n\n" +
-            "**3. APP CODE** (Kotlin/Swift handler implementations, custom UI, host-side logic)\n" +
-            "- Requires rebuild + reinstall. New bytecode → new APK → adb install. Spec hot-push doesn't apply — this is binary code, not data.\n" +
-            "- The library re-attaches to the saved sim via auto-bind on cold launch (or BuildConfig URL bake), so the SAME sim picks up where it left off. **No remint needed for code changes either.**\n" +
-            "- If you (the agent) can rebuild + reinstall the app yourself: do it, the dev never sees a pause. If you can't: hand the rebuild + reinstall step to the developer with explicit commands (e.g., `./gradlew :app:assembleDebug && adb install -r app/build/outputs/apk/debug/app-debug.apk && adb shell am start -n <pkg>/.MainActivity`). Same auto-attach behavior on the other end — the dev doesn't need to mint a new session, just rebuild.\n\n" +
+            "**2. APP CODE** (Kotlin/Swift handler implementations, custom UI, host-side logic)\n" +
+            "- Requires rebuild + reinstall. New bytecode → new APK → adb install — this is binary code, not data.\n" +
+            "- The library re-attaches to the saved sim via auto-bind on cold launch (or via the baked BuildConfig URL), so the SAME sim picks up where it left off. **No remint needed for code changes.**\n" +
+            "- If you (the agent) can rebuild + reinstall the app yourself: do it, the dev never sees a pause. If you can't: hand the rebuild + reinstall step to the developer with explicit commands (e.g., `./gradlew :app:assembleDebug && adb install -r app/build/outputs/apk/debug/app-debug.apk && adb shell am start -n <pkg>/.MainActivity`). Same auto-attach behaviour on the other end — the dev doesn't need to mint a new session, just rebuild.\n\n" +
+            "**There is no third \"spec\" axis post-pivot.** Pre-pivot the library interpreted a spec/DSL that could be hot-pushed over the WebSocket as a separate iteration loop. Post-pivot the handler code IS the only authoring surface; behaviour changes mean rebuild + reinstall. The simulator picks up the new APK / IPA automatically thanks to auto-bind, but there is no live-push of behaviour.\n\n" +
             "── How the app finds the session URL on launch ──\n\n" +
             "Three mechanisms in priority order:\n\n" +
-            "1. **Auto-bind via local MCP probe** (preferred — zero URL handling). At startup, the library probes its host MCP server's local-bridge endpoint and learns the `mcpInstallId`. It opens `/ws/pending` announcing that ID + the device's `device_install_id`. When `createSimulatorSession` runs (or when the saved sim is resumed), the backend matches by `(mcpInstallId, deviceInstallId)` and binds the pending socket to the right saved sim. The URL never touches your binary, and multi-project devs route correctly.\n" +
-            "2. **URL-bake fallback** (`BuildConfig.EXTENTOS_SESSION_URL`). Set when the MCP probe path doesn't reach (cellular phone, cloud-hosted agent, sandboxed environments where the emulator can't reach the host MCP). `createSimulatorSession` returns `androidBuildConfigPatch` with the snippet to paste into `app/build.gradle.kts`; rebuild the app once after pasting. The baked URL is stable across resumes — only force-fresh requires another rebuild.\n" +
+            "1. **Auto-bind via local MCP probe** (preferred — zero URL handling). At startup the library probes its host MCP server's local-bridge endpoint (`http://localhost:31337/whoami` via `10.0.2.2` from the Android emulator, or `adb reverse` from USB devices) and learns the `mcpInstallId`. It opens `/ws/pending` announcing that ID + the device's `device_install_id`. When `createSimulatorSession` runs (or when the saved sim is resumed), the backend matches by `(mcpInstallId, deviceInstallId)` and binds the pending socket to the right saved sim. The URL never touches your binary, and multi-project devs route correctly.\n" +
+            "2. **URL-bake fallback** (`BuildConfig.EXTENTOS_SESSION_URL` on Android, `extentos.session.plist` on iOS). Set when the MCP probe path doesn't reach (cellular phone, cloud-hosted agent, sandboxed environments where the emulator can't reach the host MCP). `createSimulatorSession` returns the snippet to paste; rebuild once after pasting. The baked URL is stable across resumes — only force-fresh requires another rebuild.\n" +
             "3. **Typed pairing code** (manual). User types a 5-char code in the simulator UI from another machine. Last resort.\n\n" +
             "── Practical recipes ──\n\n" +
-            "- **Spec-only change** (renamed phrase, added trigger, tweaked action): one `updateSpec` call. Done. No mint, no rebuild.\n" +
-            "- **Handler logic change** (new business logic in your callback): rebuild + reinstall the app. Same saved sim continues.\n" +
-            "- **New handler added to spec**: one `updateSpec` (live-pushes the spec) + one rebuild + reinstall (to ship the new dispatch entry). Same saved sim continues.\n" +
+            "- **Handler logic change** (new business logic in your handler): rebuild + reinstall the app. Same saved sim continues.\n" +
             "- **App force-stopped or emulator restarted**: just relaunch the app. The library re-runs the MCP probe and the backend re-binds it to the saved sim. No mint, no agent intervention.\n" +
             "- **Resuming work the next morning** (sim went `idle` overnight): just launch the app. Auto-bind reconnects, sim transitions `idle → waiting → active` on its own. Dev never thinks about it.\n" +
             "- **Want a clean state slate / rotate the sessionId**: `createSimulatorSession({ resetFresh: true })` OR click \"Reset\" on the dashboard. Backend archives the existing sim, mints a replacement with the same project key, pushes `session_moved` to live sockets. URL-bake apps rebuild once after this.\n" +
-            "- **Backend restarted while app was offline**: next reconnect to the baked URL works — Phase 0 backend recovery clears orphan-roles instead of expiring the row, and the device's normal `session_init` handshake re-attaches as the `app` role on the alive saved sim. No `session_unknown`, no manual remint.",
-        keywords: ["browser", "session", "websocket", "injection", "replay", "simulator", "url", "auto-open", "autoOpenAttempted", "iteration", "rebuild", "live-push", "spec_updated", "auto-bind", "url-bake", "idle", "resumed", "resetFresh", "get-or-create", "dashboard", "persistent", "dev loop"],
-        relatedTools: ["createSimulatorSession", "getSimulatorStatus", "getEventLog", "updateSpec"],
+            "- **Backend restarted while app was offline**: next reconnect to the baked URL works — backend recovery clears orphan-roles instead of expiring the row, and the device's normal `session_init` handshake re-attaches as the `app` role on the alive saved sim. No `session_unknown`, no manual remint.",
+        keywords: ["browser", "session", "websocket", "injection", "replay", "simulator", "url", "auto-open", "autoOpenAttempted", "iteration", "rebuild", "auto-bind", "url-bake", "idle", "resumed", "resetFresh", "get-or-create", "dashboard", "persistent", "dev loop"],
+        relatedTools: ["createSimulatorSession", "getSimulatorStatus", "getEventLog"],
     },
     {
         topic: "event_log_schema",
         title: "Event Log Schema",
-        content: "Event types across 7 layers (transport, trigger, block, callback, toggle, stream, system). flowId correlates events inside one trigger execution. type uses dot notation: trigger.fired, block.completed, callback.timeout, stream.started, spec.loaded, account.meter_exhausted, simulator.session_expired. 10 getEventLog filter values: all, errors, transport, triggers, blocks, callbacks, toggles, streams, system, spec. errors filter is cross-layer severity-based; spec filter is type-prefixed.",
-        keywords: ["event", "log", "flowid", "layer", "filter", "schema", "29", "trigger.fired"],
+        content: "Every event has a `layer`, a `type` (dot notation), a `severity` (info / warn / error), and a `message` + optional `details` object. The layer is the canonical filter axis in `getEventLog({ filter })` — pass the layer name to scope the trace.\n\n" +
+            "── Layers ──\n\n" +
+            "**transport** — the WebSocket / DAT-shaped link between the app, the simulator, and the backend. Connection open/close, frame relays, role bind/unbind, session lifecycle. Surfaces protocol-level surprises (auth failures, frame schema mismatches, backend evictions).\n" +
+            "  Examples: `connection.opened`, `connection.closed`, `frame.relayed`, `session.role_attached`, `session.role_evicted`.\n\n" +
+            "**audio** — every `glasses.audio.*` op. STT subscriptions starting / stopping, recordDiscrete invocations, speak / cancelSpeak, raw audio chunks.\n" +
+            "  Examples: `audio.transcriptions_subscribed`, `audio.transcriptions_unsubscribed`, `audio.record_discrete_started`, `audio.record_discrete_completed`, `audio.speak_started`, `audio.speak_cancelled`, `audio.speak_completed`, `audio.chunks_subscribed`.\n\n" +
+            "**camera** — every `glasses.camera.*` op. Photo / video capture, frame-stream lifecycle, capture failures (toggle gates, exclusivity conflicts).\n" +
+            "  Examples: `camera.capture_photo_started`, `camera.capture_photo_completed`, `camera.video_frames_subscribed`, `camera.capture_failed`.\n\n" +
+            "**speak** — distinct sub-layer under audio specifically for TTS. Carved out so wake-and-listen flows can filter to just the talk-back side when debugging barge-in.\n" +
+            "  Examples: `speak.started`, `speak.cancelled`, `speak.completed`.\n\n" +
+            "**toggles** — the 8 runtime toggles changing value. Carries `key`, `previous`, `next`, `source` (UI / HOST_APP / SYSTEM).\n" +
+            "  Examples: `toggle.changed`.\n\n" +
+            "**streams** — the lifecycle of capability streams (videoFrames, audioChunks, transcriptions). Started, stopped, error.\n" +
+            "  Examples: `stream.started`, `stream.stopped`, `stream.error`.\n\n" +
+            "**system** — the library + host app's own framing. App startup, library init, account state, meter exhaustion, simulator-session expiry.\n" +
+            "  Examples: `app.initialized`, `account.meter_exhausted`, `simulator.session_expired`.\n\n" +
+            "── Special filter values ──\n\n" +
+            "- `all` (default) — every layer.\n" +
+            "- `errors` — every event with severity ≥ error across all layers. The first filter to try when investigating a misbehaviour.\n\n" +
+            "── Retired event types (do not exist post-pivot) ──\n\n" +
+            "Pre-pivot the event log also carried spec-runtime events: `trigger.fired`, `block.executed`, `callback.invoked`, `flow.completed`, `spec.loaded`, `meter.exhausted_reached`. These were retired with the DSL — the library no longer interprets a spec, so the runtime events that described its execution don't exist. The `triggers` / `blocks` / `callbacks` / `spec` filter values are also gone from `getEventLog`'s enum.",
+        keywords: ["event", "log", "layer", "filter", "schema", "transport", "audio", "camera", "speak", "toggle", "stream", "system", "severity"],
         relatedTools: ["getEventLog", "getSimulatorStatus"],
     },
     {
         topic: "permissions",
         title: "Permissions Derivation",
-        content: "Android runtime permissions and iOS Info.plist keys derive from spec contents. Photo/video blocks → CAMERA. Audio-recording blocks, mic streams, voice triggers → RECORD_AUDIO + NSMicrophoneUsageDescription + NSSpeechRecognitionUsageDescription. Always added: BLUETOOTH_CONNECT, BLUETOOTH_SCAN, INTERNET, NSBluetoothAlwaysUsageDescription. Streams require FOREGROUND_SERVICE + foregroundServiceType (Android) or UIBackgroundModes (iOS). Meta DAT scopes derive from same surface: glasses.connection always; glasses.camera.{photo,video,stream}, glasses.audio.{record,stream} conditionally.",
-        keywords: ["permission", "manifest", "info.plist", "camera", "microphone", "bluetooth", "dat", "scope"],
+        content: "Android runtime permissions and iOS Info.plist keys derive from the list of SDK capabilities the app uses — feed `getPermissions({ capabilities: [...] })` the names from `getPlatformInfo.features[].name`. `capture_photo` / `capture_video` / `video_frames` / `outgoing_video_stream` → CAMERA. `record_audio` / `audio_chunks` / `transcription_incremental` / `outgoing_audio_stream` / `voice_command` / `wake_word` / `push_to_talk` → RECORD_AUDIO + NSMicrophoneUsageDescription + NSSpeechRecognitionUsageDescription. `location_updated` → ACCESS_FINE_LOCATION + NSLocationWhenInUseUsageDescription. `phone_notification_forwarded` → BIND_NOTIFICATION_LISTENER_SERVICE plus the lib's `<service>` declaration. Always added: BLUETOOTH_CONNECT, BLUETOOTH_SCAN, INTERNET, NSBluetoothAlwaysUsageDescription. Stream capabilities require FOREGROUND_SERVICE + foregroundServiceType (Android) or UIBackgroundModes (iOS). Meta DAT scopes derive from the same surface: glasses.connection always; glasses.camera.{photo,video,stream}, glasses.audio.{record,stream} conditionally.",
+        keywords: ["permission", "manifest", "info.plist", "camera", "microphone", "bluetooth", "dat", "scope", "capabilities"],
         relatedTools: ["getPermissions", "validateIntegration", "getProductionChecklist"],
     },
     {
         topic: "credentials",
         title: "Credentials",
-        content: "Simulator voice proxy is automatic — no setup. Meta Developer Center registration is required at first real-hardware test (per-developer): create app, enable Wearables DAT, register package name + signing signature (Android) or bundle ID + Team ID (iOS), copy App ID + Client Token into extentos.manifest.json (Android) or Info.plist MWDAT dict (iOS). BYOK provider keys (Anthropic / OpenAI / Google / etc.) live in the developer's secret storage and get consumed inside app_callback handlers — never stored in the manifest.",
-        keywords: ["credential", "meta", "developer", "api key", "byok", "dat", "client token", "registration"],
+        content: "Simulator voice routing is automatic — no setup. Meta Developer Center registration is required at first real-hardware test (per-developer): create app, enable Wearables DAT, register package name + signing signature (Android) or bundle ID + Team ID (iOS), copy App ID + Client Token into extentos.manifest.json (Android) or Info.plist MWDAT dict (iOS). BYOK provider keys (Anthropic / OpenAI / Google / etc.) live in the developer's secret storage and get consumed inside the customer's handler code — never stored in the Extentos manifest. **Android storage:** use `resValue` + `R.string` lookups, NOT `buildConfigField`. BuildConfig String constants are compile-time-inlined by kotlinc and stale keys silently survive rotations. See `getCredentialGuide` for canonical patterns per provider.",
+        keywords: ["credential", "meta", "developer", "api key", "byok", "dat", "client token", "registration", "resValue", "buildConfig"],
         relatedTools: ["getCredentialGuide", "getProductionChecklist"],
     },
     {
         topic: "production_checklist",
         title: "Production Checklist",
-        content: "8 personalized categories: Meta Developer Account, DAT Registration, Credential Swap, API Keys (skipped if no handlers), Permissions Audit, Foreground Service (skipped if no streams), Transport Config, Store Listing. Each step is personalized to the spec — streams add foreground service / background modes; handlers add API key wiring; simulator URL must be stripped from release builds.",
+        content: "9 personalized categories: Meta Developer Account, DAT Registration, Credential Swap, API Keys (skipped if no handlers declared), Permissions Audit, Foreground Service / Background Modes (skipped if no stream capabilities), Transport Config, Real-Hardware Verification (when the app uses voice / video / audio capture), Store Listing. Each step is personalized by the capability list + handler names passed to `getProductionChecklist` — stream capabilities add the foreground service / background modes step; handlers add API key wiring; simulator URL must be stripped from release builds.",
         keywords: ["production", "checklist", "release", "ship", "store", "ready"],
         relatedTools: ["getProductionChecklist", "getCredentialGuide", "getPermissions"],
     },
@@ -1007,14 +519,30 @@ export const DOC_INDEX = [
         title: "Concurrency Modes",
         content: "Trigger-level concurrency: 'restart' cancels any in-flight flow of the same id and runs the new one; 'single' ignores new invocations while one is running; 'queued' enqueues up to N (default 3). Default is 'single' for voice_command, 'restart' for stream-derived triggers. Applies independently per trigger id.",
         keywords: ["concurrency", "restart", "single", "queued", "trigger", "in-flight"],
-        relatedTools: ["updateSpec"],
+        relatedTools: [],
     },
     {
         topic: "manifest_format",
         title: "extentos.manifest.json Format",
-        content: "Manifest version 1. Top-level: platform ('android'|'ios'), glasses ('meta_rayban'), appPackage, extentos { libraryVersion, specVersion, installedAt, lastUpdatedAt }, spec { path, hash }, generatedFiles[], one of gradle { coordinate, buildFile, additionalArtifacts } or spm { package, packageURL, version, projectFile, additionalProducts }, permissions[], integration { blocks, streams, triggers, handlerNames, togglesOverridden }. Tool-managed; hand-edits trigger drift in validateIntegration.",
-        keywords: ["manifest", "json", "extentos.manifest", "spec.hash", "generatedfiles", "gradle", "spm"],
-        relatedTools: ["inspectIntegration", "validateIntegration"],
+        content: "Manifest version 2 (post pure-SDK pivot). Top-level fields:\n\n" +
+            "- `manifestVersion: 2` — bumped from v1 when the spec / integration sub-object dropped.\n" +
+            "- `platform: \"android\" | \"ios\"`\n" +
+            "- `glasses: \"meta_rayban\"` — only one vendor for MVP.\n" +
+            "- `appPackage: string` — Android `applicationId` / iOS bundle identifier. The dashboard groups sims by this value.\n" +
+            "- `extentos: { libraryVersion, installedAt, lastUpdatedAt }` — install metadata.\n" +
+            "- `generatedFiles: [{ path, template, hash, generatedAt, generatedByTool }]` — the bootstrap (and any future tool-managed files). Detected by `inspectIntegration` / `validateIntegration` for drift via the recorded SHA-256.\n" +
+            "- `gradle: { coordinate, buildFile, additionalArtifacts, minimumAgpVersion, minimumGradleVersion }` — Android-only. Mutually exclusive with `spm`.\n" +
+            "- `spm: { package, packageURL, version, projectFile, additionalProducts, minimumXcodeVersion }` — iOS-only. Mutually exclusive with `gradle`.\n" +
+            "- `permissions: string[]` — declared platform permissions. Android: `android.permission.*`. iOS: Info.plist key names. Should equal `getPermissions(capabilities, platform)` modulo any extras the host app needs for non-Extentos reasons.\n" +
+            "- `capabilities: string[]` — the SDK feature names the customer's handler code uses (e.g. `\"transcription_incremental\"`, `\"capture_photo\"`, `\"speak\"`). Drives `getPermissions`, `getProductionChecklist`, and `getCredentialGuide`. Update this when you add a new primitive to your handler.\n" +
+            "- `handlerNames: string[]` — optional informational list of the customer's handler class names (e.g. `[\"VisionHandler\", \"CoachHandler\"]`). Used by `getProductionChecklist` to label per-handler ship-readiness steps. Safe to leave empty.\n\n" +
+            "── Retired fields (v1, do not write) ──\n\n" +
+            "- `extentos.specVersion` — DSL version, retired.\n" +
+            "- `spec: { path, hash }` — pointed at the DSL spec file, retired.\n" +
+            "- `integration: { blocks, streams, triggers, handlerNames, togglesOverridden }` — DSL primitive references, retired (replaced by top-level `capabilities` + `handlerNames`).\n\n" +
+            "The manifest is tool-managed by `generateConnectionModule`. Hand-edits to `permissions`, `capabilities`, or `handlerNames` are expected during normal development (you add a feature to your handler → add the capability name here so getPermissions output stays accurate). Hand-edits to `generatedFiles`, `gradle`, or `spm` will trigger drift warnings in `validateIntegration`.",
+        keywords: ["manifest", "json", "extentos.manifest", "generatedfiles", "gradle", "spm", "capabilities", "handlerNames"],
+        relatedTools: ["inspectIntegration", "validateIntegration", "generateConnectionModule"],
     },
     {
         topic: "multi_platform_projects",
@@ -1075,50 +603,23 @@ export const DOC_INDEX = [
     {
         topic: "file_actions",
         title: "File Actions in Tool Responses",
-        content: "**generateConnectionModule, initSpec, and generateConsumer return a `files[]` array.** Each entry has `{ path, action, content, ... }`. The `action` value tells the agent how to apply the file — five distinct semantics. Apply each correctly or developer code is lost.\n\n" +
+        content: "`generateConnectionModule` returns a `files[]` array. Each entry has `{ path, action, content, ... }`. The `action` value tells the agent how to apply the file — two distinct semantics post-pivot. Apply each correctly or developer code is lost.\n\n" +
             "─── action: \"create\" ───\n" +
-            "Fresh write. The file is fully tool-owned — only `EXTENTOS-GENERATED` markers, no `USER-CODE` blocks. If the file already exists and was previously generated by Extentos, it's safe to overwrite. If it exists and is NOT marked as Extentos-generated (no `EXTENTOS-GENERATED` header), do not overwrite — that's developer-authored code.\n" +
-            "Examples: `ExtentosBootstrap.kt`, `ExtentosBootstrap.swift`.\n" +
-            "Apply: write `content` to `path`.\n\n" +
-            "─── action: \"write\" ───\n" +
-            "Server has already done all merging. Write `content` to `path` verbatim. Used when the agent passed `projectPath` to initSpec / generateConsumer — the action upgrades unconditionally (whether the target file existed or not). When the file existed, the server performed the USER-CODE merge on the agent's behalf; when it didn't, there was nothing to merge but the agent still writes verbatim (a fresh-integration create). The response always carries `mergeReport: { preserved: string[], orphaned: string[], extra: string[], warnings: [...] }` — empty arrays on the fresh-create path, populated on the merge path.\n" +
-            "  - `preserved`: USER-CODE blocks whose existing body was spliced into the new template (the dev's code survived in place).\n" +
-            "  - `orphaned`: blocks whose corresponding HANDLER / STREAM was removed from the spec — body kept at end-of-file with an `// ORPHANED:<name>` annotation. Surface these to the dev so they can review and either delete or re-add the spec entry.\n" +
-            "  - `extra`: blocks present in the existing file that the template didn't generate (developer-created shared utility blocks, e.g., a `// USER-CODE-START:helpers` block holding HTTP clients). Preserved silently at end-of-file with no annotation. Listed for transparency; agents typically don't need to surface these.\n" +
-            "  - `warnings`: soft warnings (corrupt input, duplicate block names). Surface to the dev.\n" +
-            "Apply: write `content` to `path`. Done.\n\n" +
-            "─── action: \"create_or_merge\" ───\n" +
-            "**Legacy / no-projectPath path.** The file contains `USER-CODE-START:<name>` / `USER-CODE-END:<name>` blocks where the developer fills in handler bodies, stream-processing code, imports, etc. On regeneration, those blocks MUST be preserved.\n" +
-            "Examples: `ExtentosCallbacks.kt`, `ExtentosCallbacks.swift`, `ExtentosStreams.kt`, `ExtentosStreams.swift`.\n" +
-            "**Prefer the server-side merge path**: pass `projectPath` to initSpec / generateConsumer and the server returns action: `write` with content already merged — no agent-side merge logic needed.\n" +
-            "Manual-merge apply (when projectPath is unavailable):\n" +
-            "  1. If the file does not exist: write `content` to `path`. Done.\n" +
-            "  2. If the file exists: for every `USER-CODE-START:<name>` … `USER-CODE-END:<name>` block in the existing file, replace the matching block in `content` with the existing block's body verbatim (markers stay; only the body inside is preserved). Then write the merged result to `path`.\n" +
-            "  3. If a USER-CODE block in the existing file has a `<name>` that is not present in `content` (a removed handler), insert it back at end-of-file with a `// ORPHANED:<name>` comment line above its preserved START/END markers — never silently delete developer code.\n" +
-            "Skipping the merge step (always overwriting) silently destroys handler implementations on every regeneration. Strongly prefer the projectPath path so the server handles this correctly.\n\n" +
-            "─── action: \"replace_region\" ───\n" +
-            "Marker-bounded splice into an existing tool-owned file. Carries an extra `marker` field (e.g., `marker: \"dispatch\"`).\n" +
-            "Apply:\n" +
-            "  1. Read the existing file at `path`.\n" +
-            "  2. Find `// EXTENTOS-GENERATED-START:<marker>` and `// EXTENTOS-GENERATED-END:<marker>` (the `//` works for both Kotlin and Swift).\n" +
-            "  3. Replace the body BETWEEN those markers (markers themselves stay) with `content`.\n" +
-            "  4. Write the result back to `path`.\n" +
-            "Example: `generateConsumer(kind: \"callback\")` returns a `replace_region` patch with `marker: \"dispatch\"` to wire the callback handler registration into the bootstrap's dispatch region.\n" +
-            "Apply this programmatically — the content is a code fragment, not English instructions. Never copy `content` to disk verbatim; it must be spliced into the marker block.\n\n" +
+            "Fresh write. The file is fully tool-owned — `EXTENTOS-GENERATED` marker in the header. If the file already exists and was previously generated by Extentos, it's safe to overwrite (regeneration restores the canonical content; any hand-edits between markers are lost by design). If it exists and is NOT marked as Extentos-generated (no `EXTENTOS-GENERATED` header), do not overwrite — that's developer-authored code.\n" +
+            "Examples: `ExtentosBootstrap.kt` (Android), `ExtentosBootstrap.swift` (iOS).\n" +
+            "Apply: write `content` to `path` verbatim.\n\n" +
             "─── action: \"manual_patch\" ───\n" +
-            "English-language instructions for a file the agent does not own (the developer's own app entry point — e.g., iOS `App.swift`). The `content` field is prose with embedded code snippets, not a machine-applyable file body.\n" +
-            "Apply: read the instructions, find the location they describe in the developer's file, hand-apply the change. Surface this to the developer when ambiguous; do not guess.\n" +
+            "English-language instructions for a file the agent does not own (typically the developer's own app entry point — e.g., iOS `App.swift`). The `content` field is prose with embedded code snippets, not a machine-applyable file body.\n" +
+            "Apply: read the instructions, find the location they describe in the developer's file, hand-apply the change. Surface this to the developer when the location is ambiguous; do not guess.\n" +
             "Example: `generateConnectionModule` (iOS) returns a `manual_patch` for `App.swift` adding `.onOpenURL` and `.onChange(of: scenePhase)` modifiers. The agent reads the instructions and applies them to the existing app file.\n\n" +
-            "── Why five actions instead of one ──\n" +
-            "Each value encodes a different file-ownership and merge contract:\n" +
+            "── Retired actions (do not appear post-pivot) ──\n\n" +
+            "Pre-pivot the tools also returned `write` (server-side-merged USER-CODE blocks), `create_or_merge` (agent-applied USER-CODE merge), and `replace_region` (marker-bounded splice into an existing tool-owned file). All three were part of the retired `generateConsumer` / `initSpec` / `updateSpec` toolchain. Post-pivot the only generated artifact is the bootstrap, which the customer never edits — so the merge semantics collapse to plain `create` (regenerate by overwriting) and `manual_patch` (App.swift / Application class wiring the customer owns).\n\n" +
+            "── Why two actions instead of one ──\n\n" +
             "- `create` says 'we own this whole file; safe to overwrite.'\n" +
-            "- `write` says 'we own the structure, the dev owns USER-CODE blocks, AND we already did the merge for you — write verbatim.'\n" +
-            "- `create_or_merge` says 'we own the structure but the dev owns the USER-CODE blocks; YOU (agent) must preserve those — pass projectPath next time and the server does it for you.'\n" +
-            "- `replace_region` says 'we own one block of an existing file; splice into that block only.'\n" +
             "- `manual_patch` says 'we don't own this file; here are instructions, you decide.'\n" +
-            "Conflating them silently destroys developer code (overwriting `create_or_merge` as if it were `create`) or breaks regeneration (treating `replace_region` as a full file write blows away the surrounding code).",
-        keywords: ["files", "action", "create", "write", "create_or_merge", "replace_region", "manual_patch", "user-code", "merge", "regeneration", "marker", "projectPath", "mergeReport", "orphaned", "extra", "helpers"],
-        relatedTools: ["generateConnectionModule", "initSpec", "generateConsumer"],
+            "Conflating them either silently overwrites developer code (treating `manual_patch` as `create`) or fails to wire the App entry point at all (treating `create` as `manual_patch`).",
+        keywords: ["files", "action", "create", "manual_patch", "regeneration", "extentos-generated", "bootstrap", "app.swift"],
+        relatedTools: ["generateConnectionModule"],
     },
     {
         topic: "constraints_and_limitations",
@@ -1130,8 +631,28 @@ export const DOC_INDEX = [
     {
         topic: "connection_ui",
         title: "Connection UI",
-        content: "3-layer customization: (1) drop-in ExtentosConnectionPage with zero config; (2) appearance tokens via ExtentosTheme for colors/typography; (3) @ExtentosEscapeHatch for full replacement (forfeits auto-updates). Placement patterns: dedicated route, settings subscreen, bottom-nav tab, modal sheet, headless. Code snippets for each placement: search topic 'connection_ui_placement'. Auto-grows with spec — new triggers/toggles appear automatically; **voice_command stop_conditions on capture_video / record_audio blocks ALSO auto-surface as nested indented sub-rows under whichever trigger calls that block** (resolved at UI-state-build time by walking trigger.actions → block_call → block.params.stop_conditions). Devs do nothing — drop a stop_condition in the spec and end-users see 'STOP — <phrase>' beneath the trigger that starts the capture. Opt out per-app via ConnectionPageConfig.showStopConditions = false (defaults to true). FAQ: Is it customizable? Yes, 3 layers. Can I hide sections? Yes via ConnectionPageConfig. Can I hide the nested stop sub-rows? Yes — ConnectionPageConfig.showStopConditions = false. Can I reorder? No — structural lock (status always first). Can I bring my own design? Yes via escape hatch, but no auto-updates. Does it auto-update with library? Yes for drop-in / themed; no for escape-hatch.",
-        keywords: ["ui", "connection page", "theme", "escape hatch", "appearance", "auto-grow", "placement", "connectionpageconfig", "stop_conditions", "stopconditiondescriptor", "showstopconditions", "nested stops"],
+        content: "**ExtentosConnectionPage** is the drop-in UI that handles pairing, status, toggles, and developer-facing diagnostics for the glasses connection. Three customization layers:\n\n" +
+            "1. **Drop-in** — `ExtentosConnectionPage(glasses)` (Kotlin) / `ExtentosConnectionPage(glasses: glasses)` (Swift). Zero config; works out of the box. Auto-updates with new library versions.\n" +
+            "2. **Theme** — pass an `ExtentosTheme` to override colors / typography while keeping the structural layout. Auto-updates with new library versions.\n" +
+            "3. **`@ExtentosEscapeHatch`** — full replacement with your own UI. Build against `glasses.connection.state`, `glasses.toggles.state`, and `glasses.connection.simulatorHint` directly. Forfeits structural auto-updates: when the library adds a new connection sub-state or toggle, your UI won't show it until you re-implement.\n\n" +
+            "── Placement patterns ──\n\n" +
+            "Five placements covered by `generateConnectionModule`'s placement gate (`searchDocs(topic: 'connection_ui_placement')` for full code snippets):\n" +
+            "- **dedicated_route** — single-purpose route with a back-arrow scaffold.\n" +
+            "- **settings_subscreen** — pushed onto the back stack from a Settings list row.\n" +
+            "- **bottom_tab** — co-equal nav destination alongside the app's main screens.\n" +
+            "- **modal_sheet** — bottom sheet from a Settings row (Android) or `.sheet(...)` (iOS).\n" +
+            "- **headless** — no UI; bootstrap connects in the background and the app surfaces status from `glasses.connection.state` if it cares.\n\n" +
+            "── Auto-grow ──\n\n" +
+            "ExtentosConnectionPage renders the library's connection-state machine plus the 8 runtime toggles. When the library ships a new toggle or sub-state, drop-in and themed instances pick it up automatically on library bump — that's the auto-update contract for the structural layout. Escape-hatch instances do not; you re-render against `glasses.toggles.state` manually.\n\n" +
+            "── Per-app config ──\n\n" +
+            "`ConnectionPageConfig` (passed to `ExtentosConnectionPage(config:)`) toggles individual sections — e.g. `showDevDiagnostics = false` to suppress the developer-facing telemetry panel in a release build. Structural ordering is locked (status always first, then toggles, then diagnostics).\n\n" +
+            "── FAQ ──\n\n" +
+            "- *Is it customizable?* Yes, 3 layers.\n" +
+            "- *Can I hide sections?* Yes via ConnectionPageConfig.\n" +
+            "- *Can I reorder sections?* No — structural lock (status always first).\n" +
+            "- *Can I bring my own design?* Yes via escape hatch, but no auto-updates.\n" +
+            "- *Does it auto-update with library bumps?* Yes for drop-in / themed; no for escape-hatch.",
+        keywords: ["ui", "connection page", "theme", "escape hatch", "appearance", "auto-grow", "placement", "connectionpageconfig", "headless", "dedicated_route", "settings_subscreen", "bottom_tab", "modal_sheet"],
         relatedTools: ["generateConnectionModule"],
     },
     {