---
title: "Gateway config"
description: "The sections of the Voice Gateway's config.toml (on macOS ~/Library/Application Support/foxline/config.toml), from the doc comments in crates/voice_gateway/src/config.rs. Each section lists its keys with the key's own comment."
type: "generated"
source: "docs/reference/config.md"
---

> **Generated** from the code

## `bind`

`host:port` the gateway's WebSocket listens on (default `127.0.0.1:8780`; `--bind` / `VULPINE_GATEWAY_BIND` override it).

## `trace_dir`

Directory the session trace files are written to (default `vulpine/traces/rust-gateway` under the user state dir, the foxline root's for one release; `--trace-dir` overrides it).

## `debug_traces`

Write extra debug trace rows, such as `tts_segment_queued` with each TTS segment's raw and normalised text, `text` on each `stt_partial` row and on each `decision_shadow` row (the partial it was asked on), and a `shadow_stt_partial` row (text and segment timing) per shadow-lane partial, and both transcripts on each `shadow_bundle_compare` row. Session trace only. Off by default; `--debug-traces` overrides it.

## `[admin]`

`[admin]`: the owner-local Admin socket the Admin app talks to. Off by default.

| key | meaning |
|---|---|
| `enabled` | Open the Admin socket. Off by default. |
| `socket_name` | File name of the socket under `<state>/admin/` (default `admin.sock`). |
| `issue_grouping` | Append one `issue.<cause>.<subject>` Health row per cause (a host down, a full disk, memory pressure, CPU saturation) with the checks it explains folded under it, so `brain_gateway_health` says one cause once. Read-only. On by default; `false` is the rollback. |
| `config_writes` | ADR 0065: the Admin may apply its plans to `<state>/admin-config-overlay.json`, merged over this file at start. Off by default; off also ignores (and keeps) the overlay, so `false` and a restart roll it back. |
| `controls` | AR5 (ADR 0016 addendum 2026-11-07): which gateway ops the Admin may apply. `safe` (the default) allows the R0 and R1 ops (an adapter's restart or backoff reset, a brain reconnect); `all` also allows R2 (a gateway restart, a hardpoint switch, retiring a pooled pi). Plans are always answered. |

## `[hardpoints]`

`[hardpoints]` in the gateway's config: the implementation the Admin's hardpoint switch picked for an open slot, over every loadout's own choice, from the next session on. Written by the Admin's apply to the config overlay (ADR 0065) as `hardpoints.<slot>`; absent (the default) leaves each loadout's choice alone.

| key | meaning |
|---|---|
| `stt` | The `stt` slot's implementation for every session (a built-in or a Catalog entry's id); absent: the loadout's. |
| `tts` | The `tts` slot's implementation for every session; absent: the loadout's. |
| `tts_voice` | AR7 (plan slice 16, the design's "TTS voice" row): the voice every session's `tts` Catalog implementation speaks in, over the loadout's `[hardpoints] tts_voice` (a name, 1 to 64 of `[A-Za-z0-9_.-]`, never a path). A session whose `tts` is a built-in ignores it (the built-in takes its voice from the persona); absent: the loadout's. |

## `[reach]`

(ADR 0065 addendum 2026-11-07): `[reach]` in the gateway's config holds only the Admin's reach switch. The gateway never acts on it: the Admin's apply writes `reach.enabled` to the config overlay, and the reach helper (`crates/reach_iroh`) reads the overlay's value over fox9.toml's `[reach] enabled` when it next starts. Unknown keys are ignored, so a helper table pasted here by mistake still loads (the install runbook's E21).

| key | meaning |
|---|---|
| `enabled` | Whether the reach helper serves, as the Admin last set it; the helper reads it at its next start. Off. |

## `[brain]`

`[brain]`: how the gateway launches the pi brain over RPC.

| key | meaning |
|---|---|
| `pi_command` | The pi command the brain is launched with (default `pi`). |
| `background_command` | Compact background lane: when set, this command (`runtime/fm-brain`, Apple's on-device Foundation Models speaking pi's RPC lines) serves background attempts whose OBJECTIVE SHAPE is pure writing/explaining, tool-free, with the same pi-shaped arguments; |
| `idle_timeout_ms` | A brain unused for this long, in milliseconds, counts as idle-expired (default 300000). |
| `prewarm` | Start the brain before the first turn (a loadout can also ask for this). Off by default. |
| `no_extensions` | Launch pi with `--no-extensions`. On by default. |
| `no_context_files` | Launch pi with `--no-context-files`. On by default. |
| `no_skills` | Pi discovers skills (`~/.pi/agent/skills/`, `.pi/skills/`) and prompt templates (`~/.pi/agent/prompts/`, `.pi/prompts/`) from the brain's cwd and folds the skills into the system prompt. The voice brain's prompt surface is the loadout's, so discovery is off unless a config says otherwise (explicit `--skill` paths would still load). |
| `no_prompt_templates` | Launch pi with `--no-prompt-templates`. On by default. |
| `tool_door_timeout_secs` | Seconds the typed tool door (`glyphctl tool`, `glyphctl meet minutes`, `glyphctl recall`) lets one runner live before it is killed and the receipt says `timeout` (default 60): a pi_herdr_dispatch card waits this less 3 s. Must outlast `minutes_deadline_secs` by at least 10 s, so a slow minutes model reads as the tool's own answer, not the door's; at most 300. |
| `minutes_deadline_secs` | Seconds the minutes model (`pi_meeting_minutes`, one tool-free brain-lane prompt) may think before the call answers `timeout` (default 45, at most 50). The gateway allows a further 5 s for the brain's launch, which must stay inside the mutation connection's 58 s. |
| `ask_back_budget` | The ask-back budget. When on, a second consecutive ask-back (a pi `extension_ui_request` select) on the same subject is not spoken: the gateway answers it with the top-ranked option and says "<option>, say no if that is wrong" (`ask_back_budget.rs`). A confirm, a yes/no select or an input is always asked. Off by default. |
| `ask_back_budget_window_secs` | Seconds within which a repeated ask-back counts as consecutive (default 120, between 1 and 3600). |
| `retry_hold_ms` | Milliseconds a brain turn may stay held while pi retries or compacts it itself (`brain_turn_held`) before the gateway closes it with `brain_turn_closed {reason: retry_hold_expired}` and the provider line (default 20000, between 100 and 110000 — under the 120 s brain operation timeout). |
| `tool_door_timeout_max_secs` | The most seconds one typed door call may ask to run (`glyphctl tool --timeout <s>`, the `invoke_tool` frame's `timeout_secs`) — a `pi_herdr_report {wait_s}` long-poll outlasts `tool_door_timeout_secs`. A call asking for more is refused with a receipt naming this max. Default 300; at least `tool_door_timeout_secs` and at most 600. |
| `thinking` | The thinking level every brain launch passes pi (`off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`), in place of the loadout's `[pi] thinking`. Unset keeps the loadout's. |
| `cache_warming` | Let pi keep the brain's prompt cache and connection warm between turns (`VULPINE_CACHE_WARMING=warm` for the vulpine-tools hook; needs pi's `cacheWarming = "idle"` and a model cache lifetime). On. |
| `tool_form` | tool.v1 S2 (ADR 0058 §3): how the brain's tools are declared. `full` (default since the 2026-11-01 A/B): every description. `slim`: the envelope text once, each tool's typed params and one line, guides on demand (about 13.6k fewer prompt tokens; it chose the wrong tool in 4 of 39 eval scenarios). |
| `feature_requests` | Keep the brain's feature requests (`pi_feature_request`, an ask vulpine cannot do yet) in the state dir for `just feedback::harvest`; off refuses them. On. |
| `memory` | CJ4 (ADR 0050 S6): the memory core tool (`pi_memory_recall`, `pi_memory_propose`): facts the operator said are kept in the state dir at once, a page's or a tool's wait for the operator's yes; off refuses both. On. |
| `watches` | Keep the brain's watches (`brain_watch_set`, "tell me when X") in the state dir and speak a watch's line through the governor when its condition happens; off refuses the tools and reads nothing. On. |
| `house_now` | The house now (`pi_house_now`): rooms, presence, devices on and the latest camera events read from this gateway's own home stores in one call, with a status card; off refuses it. On. |
| `context_alert_pct` | CL17: the percent of a pooled brain's context window at which the gateway notifies once (CJ24's notify) that the brain is running out of context; it re-arms after the context drops 10 points below (pi compacted, or a fresh session) and says it at most every 30 minutes per session. The Admin's `gateway.brain_context` Health row shows every pooled session's use. Default 80; |
| `skills` | (ADR 0050 §4): pass the workspace's skills (`.vulpine/skills/`) to pi with `--skill`; off, the folder is inert. On. |
| `reach_link` | Plan slice 5 (ADR 0053 K2): the reach helper's loopback `helper_brain` port (`"127.0.0.1:PORT"`). Set, every `pi_command` launch is spawned as `vulpine-reach brain dial --link PORT -- <pi args>` and the brain turn rides `vulpine/brain/1` to `vulpine-reach brain serve` (the brain's own key). Unset (the default): pi is spawned locally as before. The rollback is unsetting it. |
| `reach_shim` | The `vulpine-reach` binary the link spawns as the shim (absolute); unset: `.local/state/foxline/bin/vulpine-reach` under the home folder. |

## `[background_work]`

`[background_work]`: the store behind background work (objectives and their attempts).

| key | meaning |
|---|---|
| `state_path` | The background-work store file (default `background-work.redb` under the gateway state dir). |

## `[alarm]`

The gateway-owned alarm book (one per gateway, rebuilt at start; a due alarm fires late rather than never).

| key | meaning |
|---|---|
| `state_path` | The alarm book file (default `alarms.redb` under the gateway state dir). |

## `[frontend]`

`[frontend]`: limits and defaults for the frontends that connect over WebSocket.

| key | meaning |
|---|---|
| `max_audio_frame_bytes` | Largest audio frame a frontend may send, in bytes (default 32768); a bigger frame is refused with `audio_frame_too_large`. |
| `allowed_origins` | Extra browser origins allowed to open the gateway WebSocket, as `scheme://host[:port]`. Native clients (no Origin header), Glyph's Tauri webview and loopback http(s) dev servers are always allowed; every other page is refused at the handshake (browser_origin.rs). |
| `default_persona` | Deployment-owned default persona for sessions that do not select one explicitly (2026-09-02): the ONE place the voice identity is named — frontends may leave persona unset/empty. Unset falls back to the agent name, preserving the historical contract. |
| `default_workspace` | The Brain workspace on this host for a session whose `start_session` names none (an empty workspace, or `~`): a phone or another remote client never needs to know the gateway's filesystem. Unset keeps today's refusal. A session with no agent takes the workspace folder's name (`catalog/agents/<agent>`). |
| `render_gateway_events` | (render frame): send a frontend that declared `bar.v1` a bar graph of the gateway's own Admin event timeline (rows per component over the last `render_gateway_events_minutes`) when it binds and on every `get_state`. Off by default; never changes what is spoken. |
| `render_gateway_events_minutes` | The window of that bar graph, in minutes (default 15, clamped to 1..=1440). |
| `render_preview` | BF10 (ledger row 532): answer the `render_preview` door (`glyphctl render <kind> --file data.json`): one checked render goes on the gateway's preview board, and every frontend that declared its kind draws it at its next bind or `get_state`. A developer hook, off by default; never changes what is spoken. |
| `visual_scripts` | Take script visuals (`pi_show_visual`), each dry-run first; off refuses them (`visual_off`). On. |
| `heartbeat_interval_ms` | How often the gateway pings each frontend's WebSocket, in ms (default 30000; 0 turns the heartbeat off; else 1000 to 600000). A half-open link (a relay or ssh leg that died without a close) is then noticed within this plus `pong_deadline_ms` instead of at the next failed write. The Admin's Live sessions row shows the last pong's age. |
| `pong_deadline_ms` | CN1: how long after a gateway ping some frame (the pong, or anything else) must come back, in ms (default 10000; 1000 to 120000). Past it the gateway closes the link with close code 4408 `heartbeat_timeout`; the owner is detached as for a dropped link, so the client resumes it. |
| `write_deadline_ms` | CN1: the longest one frame write to a frontend may wait, in ms (default 5000; 1000 to 60000). A frontend that stopped reading is dropped (traced `write_stalled`, an Admin timeline row) instead of holding its session's loop; the writes in between are bounded by the WebSocket's own write buffer. |
| `card_number_grounding` | The brain's `pi_show_render` card shows only numbers a recent tool result returned; any other is refused `unsupported_number` (the spoken reply is unchanged). On; false turns the check off. |

## `[turn]`

`[turn]`: turn-taking timings and the tiered verb resolver.

| key | meaning |
|---|---|
| `max_utterance_duration_ms` | Longest user utterance, in milliseconds; past it the turn machine cancels the utterance and goes back to listening (default 30000). |
| `barge_in_confirmation_window_ms` | How recent a frontend speech hint must be, in milliseconds, to confirm a barge-in (default 450). |
| `verb_tier_shadow` | Write a `verb_tier` row on every commit saying what the tiered resolver chose (tier 1 and 2 route, tier 3 is evidence only). |
| `verb_tier_route_relaxed` |, the operator's ruling 2026-09-20: when the closed grammars miss, re-run them on the relaxed form (fillers and one polite lead removed) and route the hit exactly as tier 1 would — every closed verb except dictation, whose payload the relaxed form would lowercase and strip. Tier 3 (scored) stays shadow until its corpus precision earns routing. |
| `verb_confirm_band` | The "Did you mean …?" band. A tier-3 pick whose margin sits in `[verb_confirm_floor, verb_confirm_ceiling)` is asked about in one line instead of becoming a brain turn; a yes routes the verb, a no sends the original words to the brain. OFF by default — every would-confirm pick is traced (`verb_confirm_band`) either way. |
| `verb_confirm_floor` | Lower margin bound of the "Did you mean …?" band (inclusive). |
| `verb_confirm_ceiling` | Upper margin bound of the band (exclusive). |
| `verb_confirm_timeout_ms` | How long the question waits for its yes or no. |
| `commit_guards` | The commit guards. Re-delivery: a commit whose words equal the last acted-on commit's, or extend them by one word, within 2.5 s on the same session. Repeat: the same closed verb within 1.5 s, unless the words say again / once more / one more time. `shadow` (the default) writes a `commit_guard` row for what the guards would consume and changes no turn; `off` writes nothing. |
| `arbitrate_duplicate_commits` | One sentence, one answer. When two bound sessions commit the same spoken request inside `arbitration_window_ms`, only one answers: the earlier commit, and a Glyph over a wake-owning satellite (the puck waits for an armed Glyph's commit). The other traces `turn_arbitrated_away`. On by default; |
| `arbitration_window_ms` | The arbitration window, in milliseconds (default 1500). |
| `arbitration_takeover_ms` | The operator's ruling 2026-09-30: a LATER claim for the same request from a higher-ranked session (a Glyph over the puck) inside this many milliseconds of the current winner's commit takes over, provided the winner has not started speaking; the winner's turn is cancelled quietly (`turn_arbitration_preempted`). 0 disables takeover; 0..=10000, default 3000. |
| `arbitration_cohorts` | Trusted deployment enrollment: disjoint cohorts of durable server-issued owner UUIDs. Empty by default: every owner is one implicit cohort, so distinct owners' duplicate commits are arbitrated. When set, only the listed cohorts arbitrate and any other owner is independent. Hello client names/room hints cannot grant membership. At most 32 owners total. |
| `armed_hold_release` | TP1: release the settling armed hold on the closed partial's `complete` answer (at or over the threshold). `shadow` (default) only traces `armed_hold_would_release {ms_saved, complete_p}`; `on` releases; `off` asks nothing. |
| `armed_hold_release_threshold` | TP1: the `complete` answer that qualifies for the early release (default 0.9; 0.5 to 1). |
| `learned_endpoint` | EP1: each speaker's own end-of-turn pause, learned (EMA 0.9 of in-turn pauses, 500 to 3000 ms). `shadow` (default) writes `endpoint_learned {speaker, learned_ms, static_ms, would_cut}` per settled turn and moves no wait; `on` settles the armed hold on the last speaker's learned delay; `off` learns nothing. |

## `[loadouts]`

`[loadouts]`: loadout selection.

| key | meaning |
|---|---|
| `default_name` | The loadout a session binds when it names none (default `default`): the workspace's `.vulpine/loadouts/<name>.toml`, or `.vulpine/loadout.toml` for `default`. |
| `bundled_extensions_dir` | Where the bundled pi extensions live. Not read from the config file; set at runtime. |

## `[retrieval]`

`[retrieval]`: retrieved context for brain turns (`RetrievalConfig`, in `retrieval.rs`).

| key | meaning |
|---|---|
| `enabled` | Add citation-bearing project evidence to a Brain turn (`docs/retrieval.md`); off by default. |
| `index_path` | The offline index `tools/retrieval/build_retrieval_index.py` writes (default `retrieval-index.json`). |
| `top_k` | Most evidence records added to one turn (default 4); 0 turns retrieval off. |
| `max_context_bytes` | Byte budget for the evidence block in one turn (default 8 KiB); 0 turns retrieval off. |
| `allowed_visibilities` | Record visibilities a turn may see (default `private` only); anything else is filtered out. |
| `operator_memory_dir` | Corpus-host operator-memory store (proposals/ + promoted/ + episodes-index.json). Only read for the Admin health projection — unset leaves the gateway.operator-memory component unknown. |
| `store_path` | ADR 0031 §3/§5: the gateway-owned SQLite FTS5 store (`retrieval_store.rs`). When set, the gateway opens it ONCE at startup and serves every turn from it (`retrieval_end.engine = "sqlite"`); a missing or unreadable file, or a failing query, falls back to `index_path` for that turn with a `retrieval_store_fallback` trace. Unset = the JSON index serves exactly as before (rollback). |
| `timeline_path` | The gateway's own WRITABLE recall-by-clock timeline (`retrieval_store::RetrievalStore::open_timeline`), a separate file beside the read-only `store_path`, created owner-only (0600 in a 0700 directory) on first use. Room lines wait in memory until "keep that"; only the verb writes here, and `pi_recall_window` reads it. |

## `[invocation]`

`[invocation]`: the wake-word (invocation) detector and the armed-request rules around it.

| key | meaning |
|---|---|
| `mode` | `off` (default), `shadow` (wakes are traced, never acted on) or `cancel_assistant` (a wake can interrupt the assistant). |
| `url` | Loopback WebSocket of an external detector, used when `worker_bin` is empty (default `ws://127.0.0.1:8802/ws`). |
| `connect_timeout_ms` | Connect timeout for the detector WebSocket, in milliseconds (1–30000, default 1000). |
| `send_timeout_ms` | Timeout on one send to the detector, in milliseconds (1–5000, default 50). |
| `event_queue_capacity` | Capacity of the detector's event queue (1–4096, default 128). |
| `max_reconnect_attempts` | Reconnect attempts after the first detector connect fails (at most 10, default 3). |
| `reconnect_backoff_ms` | Wait between detector connect attempts, in milliseconds (at most 30000, default 250). |
| `max_event_bytes` | Largest detector message or frame accepted, in bytes (64–262144, default 16384). |
| `canonical_id` | The canonical wake id; must be `fox9`. |
| `aliases` | The wake aliases; must equal the qualified Fox9 alias set (the default). |
| `worker_bin` | The stdio wake worker binary; when set it is used instead of `url`, and `model_path` is required. Empty by default. |
| `model_path` | The model the stdio wake worker loads. |
| `worker_sharing` | `per_session` (default: a worker per wake runtime, two per session with `[wake] lvq_shadow`) or `shared` (one worker, a decoder stream per runtime; needs a worker that speaks `--mux`, else per-session). |
| `armed_commit_floor_db` | Route-calibrated near-field floor (dBFS) for armed radio commits. `None` keeps the floor shadow-only (evidence traces, no refusal). When set, an armed commit whose trailing peak sits below the floor is refused before brain dispatch; absent audio evidence fails open. Authority bounds per ADR 0017. |
| `degenerate_request_ms` | ADR 0019 degenerate-capture bound (ms): a sub-floor armed commit is refused only when its measured request span sits under this bound. Trailing-evidence commits always fail open. |
| `fanout_admit_rms_db` | Fanout admit floor (dBFS RMS per chunk): microphone audio quieter than this never reaches the invocation wake detector. Route-tunable; too high starves the detector at distance (smoke c8416dc2: -40 suppressed 99.8% of chunks at \~3 feet). |
| `fanout_preroll_ms` | How much suppressed lead-in (ms) the fanout gate replays to the wake detector when it opens. The sidecar's streaming decoder sees the wake word cold after every reset and mis-decodes the onset without it ("fox and i"); 256 ms took the corpus alias hit rate from 24/41 to 36/41. 0 = the pre-v207 behaviour. |
| `fanout_reset_gap_ms` | (v208): a fanout gate re-opening after at least this much silence (ms) resets the wake worker's stream first, so the wake is decoded from the replayed lead-in and not on top of stale context (room noise, the reply's echo — both seen on the v207 laptop read). 0 = never reset on silence. |
| `echo_ref_refuses_armed_commits` | When true, an armed commit whose trailing mic window the echo reference explains (coverage >= 0.9, no collapse: the mic still tracks the reply's own playback) is refused like a nearfield miss. Off = shadow only: every commit under the playback tail traces `armed_commit_echo_ref {would_refuse}` and nothing changes. |
| `echo_ref_collapse_corroborates_barge` | (v252): when true, a wake detected during playback whose echo reference reports a coherence collapse (coverage ≥ 0.9, the mic has decoupled from the playback) is corroborated operator speech even when its near-field excess sits under the margin. Off = shadow: the verdict stays in `barge_nearfield_hint.echo_ref.promoted_collapse` and the level gate decides alone. |
| `fanout_aec` | ADR 0026 stage 2c: echo cancellation on the wake-worker fanout feed. `off` (default) = the raw normalised mic; `daf` = the LocalVQE DAF front-end (`aec_daf`) subtracts the reply's playback, with the far-end reference built from the sent TTS bytes and the client's playout stamps (unstamped clients get a silent reference = a pass-through). STT is untouched. |
| `fanout_aec_seed_lag_ms` | The route's reference-to-mic bulk delay (ms) the DAF is seeded with (echo_ref measures 110–165 ms on the laptop route); re-seeded live from a trusted echo_ref lag when it moves by more than a block. |
| `operator_gate_reference` | ADR 0020: which floor references the operator gate that extends the armed hold. `adaptive` (default) uses the ADR 0019 estimator with a static fallback until it has evidence; `static` restores the pre-0020 gate verbatim. The commit-refusal path always uses the static floor. |
| `lexicon_enabled` | per-session kill switch for the configured lexicon — the only lexicon control on the admin surface (paths never are). |
| `lexicon_path` | Admitted project-lexicon manifest (JSON) whose entries rescore committed request text before brain dispatch. `None` disables the lexicon entirely. Selection refuses a manifest that fails the compiler's deterministic checks, and the session then runs unboosted. Deployment-owned; not admin-editable. |
| `lexicon_model_digest` | The sha256 of the exact STT model artifact this deployment runs; a configured lexicon authored against any other model digest is refused at selection. Required whenever `lexicon_path` is set. |
| `house_lexicon` | Also correct committed request text toward the house's own names — areas, devices and aliases read from `[home_bridge] map_file` and the `home-aliases.json` beside it — with a length-banded edit budget (≤ 6 chars 1 edit, 7–11 2, ≥ 12 3) and no rewrite when two names tie. |
| `barge_requires_corroboration` | ADR 0021: a wake detected during assistant playback barges only when the frontend's echo-aware VAD corroborates operator speech over the playback. `false` restores the pre-0021 branch — the escape hatch for a route whose client cannot produce speech hints. |
| `barge_corroboration_excess_db` | ADR 0021 amendment: near-field operator excess over the adaptive playback-bleed floor (dB) that corroborates a barge from the gateway's own audio, alongside the frontend hint. Default +24 dB: real barges sit ≥+28 (corpus + v77), while the assistant's own content-reads bleed up to ~+18 on a loud route and must gate. |
| `barge_corroboration_excess_relaxed_db` | Content prior: the relaxed near-field excess margin (dB) applied when no wake-phrase-bearing TTS text is in the echo window — the assistant cannot echo-decode a wake her synthesized text never contained, so only spurious room-noise decodes (corpus tail <+10 dB) need gating and real barges regain sensitivity. |
| `follow_up_window_ms` | The follow-up window. After the reply to an operator request finishes playing, the next utterance commits without the wake word for this long (ms) — "now make that answer half as long" right after the reply was dropped every time on 2026-09-05 (`alias_tail_suppressed`). 0 = off (the wake-word rules); |
| `armed_release_after_speech_ms` | How long after the segmenter hears the request end (ms) the live armed hold releases, once the operator's speech has been heard under the hold. Baseline c50cf6b8 (v340, 14 requests): every held request released at 4.0 s after the wake — the 4 s pre-speech grace applied as a flat floor — 1.4–3.7 s after the last word. |
| `bare_over_closer` | A bare terminal "over" closes the armed request the moment its segment closes. (the operator 2026-11-04): on by default, with the content guards of over_closer.rs ("is the game over", "it's over", "hand it over"); `false` (or a loadout's) is the off switch. |
| `bare_fox_closer` | The name as a second closing word: an armed request that ends on a bare "fox" ("turn that down, fox") commits when its segment closes, as "over" does, with over_closer.rs's guards ("the quick brown fox", "hey fox", a lone word before it). It rides `bare_over_closer` (off there, off here); `false` is the off switch for "fox" alone. Gateway-wide: no loadout override. |
| `trailing_alias_commits` | The name said LAST. A final with no wake before it that ends on the full alias ("turn that down, fox nine") commits the words before the alias, once the alias has passed every guard an alias arm passes (playback, echo and the media level rule). It needs two words before the alias; `false` restores the old behaviour (the alias arms an empty request and waits for the next utterance). |
| `over_quiet_ms` | The word-timing seam: an open partial whose last word is the closer commits once this much audio follows it (150..=300, default 240; 0 = off, the segment's own close still commits). |
| `call_control` | Whether a client's `call` control (Vigil's CALL key) opens the call window on a call loadout's session, so the line reopens after HANGUP without the wake. On by default; `false` is the rollback: the control is ignored (a `call_refused {reason: disabled}` row, nothing on the wire) and only a bind opens a call. |
| `echo_text_gate` | The text-level echo gate on brain-bound commits made while the assistant is audible. `shadow` (default) scores and traces every such commit as `echo_text_gate` and changes nothing; `drop` applies the irreversible cut on a `suppress` verdict; `off` scores nothing. |
| `echo_text_min_real_words` | The run of consecutive non-echo words that proves real speech and withholds the cut (the replay's N; 2 lost none of the seven barges the live system heard). |
| `heard_echo_cursor` | At a barge-in cut, align what the mic heard of the reply's own playback (the echo transcript) against the shipped reply with a forward-only cursor, and let it decide how much of the reply the operator heard (`heard_cut` row: `estimator: echo_cursor`). With no echo words, or none that align, the time-proportional split decides (`estimator: time`), as it always did. |
| `alias_level_margin_db` | The alias-over-media level rule's margin (dB). An embedded (non-head) text-alias arm with no sidecar wake, inside a media run (≥ 15 s, above `alias_level_floor_dbfs`), whose own near-field peak sits within this margin of the run's level would be refused (`would_refuse_level` on the `stt_alias_arm` row). MacMeet's 2.5× mic-over-system ratio = 8 dB. Refuses only with the flag on. |
| `alias_level_floor_dbfs` | The run level (dBFS, room-mic peaks) under which a run is a quiet room, not media, and the level rule does not apply. First fit −45 (`benchmarks/results/alias-arm-level-20261003.md`). |
| `refuse_embedded_alias_by_level` | Act on the level rule. On, an embedded alias at the level of the media run around it does not arm (`refused: level_consistent` on the `stt_alias_arm` row); a head alias, a sidecar wake in the run and a voice raised over the TV still arm. Default `true` since CG5: the FLIP verdict (2026-10-20) turned it on at v561; `false` turns it off. |
| `speaker_verify_rows` | Write a `speaker_verify` row beside every committed turn (`enrolled`, `score`, `verified`, `threshold`, `window_ms`) from the wake path's speaker verifier. Evidence only. With a profile loaded it costs one embed (≤ 150 ms) on the commit path; `false` turns the row (and that embed) off. Default `true`. |
| `enrolled_pcm_gate` | A different-gender filter relative to the wake; not identity (the operator's G2 ruling 2026-10-11). The gate compares the request with the WAKE, not with the operator. Default `false`; the operator's call to turn it on. |
| `enrolled_gate_decision` | How the enrolled-PCM gate decides, when it is on. `request` (default) passes every frame and decides once per armed request, at its commit: the request is refused when at least `enrolled_gate_reject_share` of its scored speech windows fall under `enrolled_gate_threshold`. `frame` is the rollback: each speech frame under the threshold becomes silence. |
| `enrolled_gate_threshold` | The cosine to the arm's enrollment clip under which a 300 ms speech window counts as another voice (-1 to 1, default 0.35). |
| `enrolled_gate_reject_share` | The share of a request's scored speech windows under `enrolled_gate_threshold` at which the `request` decision refuses it (above 0, at most 1; default 0.7). The QA impostor run on v523 measured the enrolled voice at most 0.48 and a second voice at least 0.89. |

## `[mic_control]`

ADR 0025 mic-control plane. Unset backend = plane disabled; the Admin component reports unknown rather than invented green.

| key | meaning |
|---|---|
| `backend` | The mixer backend (`dlz-creator`); unset disables the plane. |
| `host` | The mixer's LAN host name or address. |
| `port` | The mixer's port (default 80). |
| `operator_channel` | Zero-based input strip carrying the operator microphone. |
| `expected_gain_floor_db` | Below this observed preamp gain the Admin component warns that the operator mic likely needs recalibration (dB). |

## `[speculation]`

Speculative brain dispatch: at `trigger_silence_ms` of user silence the current interim transcript is dispatched to the Brain speculatively (TTS and side effects withheld); a continuation aborts the generation and reforks the session at the speculative user message with the merged text; the turn promotes at the final commit. Disabled by default — the live turn loop is authoritative until this ships end-to-end.

| key | meaning |
|---|---|
| `enabled` | Dispatch speculatively. Off by default. |
| `trigger_silence_ms` | User silence, in milliseconds, that dispatches the interim transcript (default 500). |
| `max_reforks_per_turn` | Bound on refork churn within one turn; past it the turn falls back to the non-speculative path. |

## `[ambient]`

`[ambient]`: the ambient-sound sidecar. Shadow-only evidence.

| key | meaning |
|---|---|
| `mode` | `off` (default) or `shadow`. |
| `worker_bin` | The `fox9-ambient-sidecar` binary (runtime/ambient-sidecar, built with `just build-ambient-sidecar`). Speaks `fox9-pcm-f32le-v1` over stdio like the EOU worker; required when `mode` is not `off`. |
| `window_s` | Classification window length in seconds (SoundAnalysis accepts 0.5..15). 1.5 s tags a room state faster than a turn changes it. |
| `overlap` | Fraction of consecutive windows that overlap, `[0, 0.9]`. 0.5 with a 1.5 s window yields one window every 0.75 s. |
| `top_k` | Labels per window kept in traces and the admin surface (1..10). |
| `min_score` | Labels scoring under this confidence are dropped from `top`. The `speech` score is always carried regardless. |
| `queue_capacity` | Bounded PCM fan-out queue between the mic path and the sidecar task; a saturated queue drops the chunk and counts it, never blocks audio. |
| `inform_brain` | (ambient room note N3): the master switch that lets a committed turn carry the `VULPINE_ROOM_NOTE` line. Read only with `mode = "shadow"` (inert under `off`), and only for sessions whose loadout sets `[ambient] room_note = true`; both default off. Off, the `ambient_note` row still traces with `carried: false`. |

## `[shadow_stt]`

`[shadow_stt]`: a second recogniser beside the authoritative one.

| key | meaning |
|---|---|
| `mode` | `off` (default), `shadow` or `authority`. |
| `backend` | `in-process-parakeet` (the existing ONNX seam) or `coreml-parakeet-v3` (the clean-room ANE path once built). |
| `bundle_dir` | Model bundle for the backend; empty = the backend's own env default. |
| `queue_capacity` | Bounded PCM fan-out queue; a saturated queue drops the chunk and counts it, never blocks the authoritative path. |
| `agreement_window_ms` | How recent a shadow final must be to be scored against a commit. |
| `authority_eou_hold_ms` | Authority mode only: silence after a speech segment before it closes as a final (the end-of-utterance hold). Earshot's own merge gap is 300 ms, tuned for VAD parity; a request with a thinking pause needs more before the turn machine sees a final, or it fragments (class). Shadow mode keeps 0 so its measured behaviour does not move. |
| `authority_partial_interval_ms` | Authority mode only: while a speech segment is open, recognise the audio so far every this many ms on the shared ANE recogniser and emit the stable-word prefix as a partial (same cohort as the final). 0 = no partials (the v166–v182 behaviour). |
| `authority_partial_stable_tail_ms` | A word is committed to a partial only if it ends this far before the end of the audio recognised so far (asr-api's stable-stride rule); the tail of a growing hypothesis is unstable. |
| `authority_partial_min_word_prob` | (franken_whisper's hold-when-unsure rule as a per-word holdback): a word inside the stable part whose mean piece probability (the TDT joint's `token_prob`) is under this stays in the partial's mutable tail one more window before it commits (`WordCommitter`'s `min_word_prob`). 0.0..=1.0; 0.0 (the default) = today's rule, word position alone. The final is never held. |
| `authority_hold_feed_live` | Authority mode only (trace read 2026-09-05): feed the mic to the segmenting adapter LIVE during the armed request hold instead of as one burst at release, so a cold wake request gets partials (and speculation) too. |
| `authority_relay_shadow` | Authority mode only: build the loadout's relay STT as the shadow scorer (`shadow_stt_agreement`). Off = the relay is never connected, so the relay-side worker never spawns; agreement evidence stops. The operator ruled it off on the mini on 2026-09-06 after the parakeet-cpp worker paged the host out twice. |
| `authority_stall_close` | Authority mode only: close a held or still-open speech segment on WALL time when the mic feed stalls. The segmenter's end-of-utterance hold expires on stream time, which only advances when PCM arrives, so an injected clip that ends, a capture drop mid-request or a satellite that stops streaming left the request open for ever with no final. |
| `authority_stall_close_margin_ms` | Wall time past the end-of-utterance hold before the stalled feed is treated as silence (100..=5000). |
| `authority_warm_on_arm` | Authority mode only (pladder's ANE wake cost): when the wake arms the request hold, queue one throwaway 0.5 s silent window on the shared ANE recogniser so the first real partial does not pay the Neural Engine's cold dispatch after an idle room. Skipped while a recognition is already running (the engine is awake). |
| `second_opinion_command` | Path of an external decoder run on each committed utterance's window of the per-session PCM dump (speechctl's `transcribe --pcm-f32le` contract), scored into one `stt_second_opinion` trace row. Replay-only: never authority, never spoken, no text in the trace. Empty = off. Needs `VULPINE_INVOCATION_PCM_DIR` (the dump) to have anything to read. |
| `second_opinion_timeout_ms` | Wall-time bound on one second-opinion decode (500..=30000). |
| `shadow_bundle_dir` | A SECOND in-process CoreML Parakeet bundle (same `crates/coreml_stt` contract as `bundle_dir`, e.g. Parakeet Ultra) decoded on each spoken commit's utterance window, off the hot path: one decode in flight, a commit that finds it busy is dropped and counted, never queued behind it. |
| `vad_highpass_hz` | high-pass the copy of the mic the earshot speech detector hears (two cascaded one-pole sections, this value in each section's `RC = 1/(2π·hz)`; 250 is the measured setting). The ring the recogniser, pre-roll, partials and PCM dumps read keeps the raw samples. 0 = off (default): the bare detector, today's path. 0 or 50..=1000. |

## `[herdr]`

`[herdr]`: Herdr prompt attention and how spoken approvals are committed (ADR 0028).

| key | meaning |
|---|---|
| `prompt_attention_scope` | Which panes are watched for permission prompts: `session` (default), `owned` or `off`. |
| `approvals` | How a bound approval is committed: `held` (default, nothing is sent) or `plugin`. |
| `plugin_choices` | Which spoken choices the plugin path accepts: `deny` (default) or `all`. |
| `plugin_id` | Herdr plugin id the Gateway invokes; must be linked and enabled on the Herdr host or every commit settles `held`. |
| `verify_timeout_ms` | Plugin post-send verification budget (0–10000 ms). |
| `relay_prompt` | Speak the bounded, redacted prompt and its options (ADR 0028 §5). `false` keeps the fixed "Agent needs attention." notice. |
| `witness_window_ms` | How long after a relay was spoken a closed-grammar reply ("deny", "option two") is honoured as its answer instead of a Brain turn. |
| `room_courier` | The room courier, run when an owned agent is observed idle or done, hands it the room notes held for it while it worked: vulpine-herdr (`courier deliver`; herdrctl before). courier.py is retired: a `.py` reports helper_missing. None = off. |
| `courier_python` | Inert since courier.py was retired: accepted for one release, warned once when set. |
| `courier_timeout_ms` | Whole courier run; a prompt send without a wait is well under a second. |
| `backend` | ADR 0055 §1: the herdr runtime, `hc` (herdr-core, the default since) or `herdr09` (the rollback switch). The brain's tools and fleetctl follow it through `VULPINE_HERDR_BACKEND`, set only for `hc`. |
| `hc_socket` | With `backend = "hc"`: hc's client socket, absolute. Unset: `HC_SOCKET`, else hc's default session's socket (`$XDG_RUNTIME_DIR/herdr-core/default.sock`, else `~/.local/state/herdr-core/default/default.sock`). |
| `approve_bin` | ADR 0055 §4: with `backend = "hc"` and `approvals = "exec"`, the absolute path of `vulpine-hc-approve` on EVERY hc machine (the program `machine.exec` runs; the argv is fixed in code). Unset: `~/.local/state/foxline/bin/vulpine-hc-approve` under the gateway's home. |
| `hc_claude_permission_mode` | With `backend = "hc"`, the permission mode a gateway-started Claude Code names: `default` (asks before every tool it has not been granted), `acceptEdits` or `plan`. No mode that skips its own asks can be named. |
| `desk_alerts` | `[herdr.desk_alerts]`, a desk agent spoken while the operator is away (on by default). |

## `[presence]`

/ ADR 0032: presence projection switches. The projection has no authority, so `enabled` only decides whether the store exists and the trace event is written.

| key | meaning |
|---|---|
| `enabled` | Keep the presence store and write its trace. On by default. |
| `frontend_room_default` | The room a frontend that declares none is taken to be in when a request arms on it (the desk Glyph: "office"). Empty = such frontends contribute no room. |
| `room_explicit_ttl_ms` | How long each room observation stays fresh (ms). |
| `room_frontend_ttl_ms` | Freshness of a frontend's room, in milliseconds (default 1200000). |
| `room_occupancy_ttl_ms` | Freshness of an occupancy reading, in milliseconds (default 600000). |
| `room_media_ttl_ms` | Freshness of a media-playback reading, in milliseconds (default 1800000). |
| `room_ble_ttl_ms` | CH6: freshness of a BLE room (a puck heard the operator's phone or watch), in milliseconds (default 180000). |
| `room_ble_dwell_ms` | CH6: how long a fresh BLE room holds against another scanner's room, in milliseconds (default 60000). |

## `[persona_vars]`

Load-time template variables for persona prompts (2026-09-02): `{{key}}` / `{{ key }}` in a persona SYSTEM.md is replaced with the value here when the session binds. Personalization (callsigns, wake word, home location, timezone, standing notes) lives in this ONE deployment-config table — edits need a gateway restart, never a rebuild. Unknown placeholders are left literal and logged, never fatal: a missing var must not block audio.

| key | meaning |
|---|---|

## `[room_speakers]`

room-speaker route. Since roomctl is the Rust binary, vulpine-room since (`just install-vulpine-room`; an old roomctl there answers for one release); a `.py` path still runs under `python`, the rollback to the retired script. `rooms_file` overrides roomctl's default `~/.config/vulpine/rooms.json`.

| key | meaning |
|---|---|
| `enabled` | Route `speak { room }` to room speakers. Off by default. |
| `python` | The interpreter, used only when `roomctl` is a `.py` script; unset by default (a `.py` with none configured reports `helper_missing`, never spawns `/usr/bin/python3`). |
| `roomctl` | roomctl (default `~/.local/state/foxline/bin/vulpine-room`, the Rust binary `just install-vulpine-room` installs); a path ending in `.py` runs under `python` instead (the rollback: `retired/roomctl/roomctl.py`). |
| `rooms_file` | Overrides roomctl's rooms file; unset = `~/.config/vulpine/rooms.json`. |
| `timeout_ms` | Whole roomctl run: render + fetch + ack wait. |
| `settle_ms` | Passed as `--settle-s`: how long roomctl waits past the estimated audible end for the driver's ack. |

## `[home_bridge]`

Home bridge. The token comes from `token_file` (a `KEY=value` file carrying `HA_LONG_LIVED_TOKEN`, or a bare token), never from here. `watch` = entity-id prefixes; empty = everything.

| key | meaning |
|---|---|
| `enabled` | Run the home bridge. Off by default. |
| `python` | The interpreter for the `.py` rollbacks of homectl and visionctl; unset by default: `helper_missing`. |
| `homectl` | The adapter: `~/.local/state/foxline/bin/vulpine-home` by default (`just setup::install-vulpine-home`); a path ending in `.py` runs under `python` instead (the rollback for one release: `retired/homectl/homectl.py`). |
| `map_file` | The adapter's subject map: fox9 subjects (`kitchen/player`) to whatever the upstream calls them. The upstream's address and token file live in there too, never here. |
| `occupancy_hold_ms` | Occupancy `off` is held this long and dropped if the subject flaps back on (the camera's car sensor cycled six times in an hour). |
| `occupancy_hold_ms_car` | The same hold, for a CAR. A car is not a person — it does not step out of frame and back. Measured over 136 hours of the driveway camera (2026-09-17): of 84 gaps between the car sensor dropping and picking up again, **51% were under two minutes** and a quarter were under 31 seconds, while genuine departures sat at 37 minutes (p75). The flat 30 s hold absorbed only 23% of them; |
| `restart_ms` | Backoff base when the adapter process exits. |
| `describe_camera_events` | Ask the local vision model what a camera event actually shows, and attach its sentence to the announcement before it is spoken. Off leaves the detector's own line ("A person at the backyard camera."), which is also what a failed or late description falls back to — the feature can never hold a line up or empty it. |
| `visionctl` | The vision adapter (ADR 0034): `~/.local/state/foxline/bin/vulpine-vision` by default (`just setup::install-vulpine-vision`); a `.py` runs under `python` (the rollback: `runtime/vision/visionctl.py`). |
| `describe_question` | What to ask about an event's frame. One short sentence is the whole budget: this is spoken aloud, after a clause the detector already said. |
| `describe_timeout_ms` | How long the description may take before the line goes out plain. The model answers a 240-px event frame in 1-4 s on the Air. |
| `quiet_alert_hours` | An MQTT bridge (Ring, Frigate) with no live message for this many hours reads `quiet` on its `home_bridge:<source>` Health row and is told once, then hourly; 0 turns the watch off. |

## `[screen]`

What is on the operator's screen, as TYPED text. Off by default — this route reads a screen, and a screen is the most personal surface the house touches. It is armed per machine, and it only ever runs when the operator asked about their screen in so many words.

| key | meaning |
|---|---|
| `enabled` | Allow screen reads on this machine. Off by default. |
| `screenctl` | The screen tool. Unset: VulpineGrants.app's fox9grants, run as `fox9grants screen`, else runtime/screen/vulpine-screen, else the screenctl beside it. Over `host`: the far side's path, as `~/Applications/VulpineGrants.app/Contents/MacOS/fox9grants`. No display over ssh: `ask` the agent. |
| `mode` | `window` (the frontmost ordinary window) or `display` (everything). `window` is the one that works: a whole retina display is either an enormous prompt or an unreadable one. |
| `max_chars` | Characters of screen text allowed into a prompt. |
| `timeout_ms` | Bound on one screen read, in milliseconds (default 6000). |
| `exclude_bundle_id` | A bundle id to keep out of its own frame — the asking app. A capture that takes focus first photographs itself. |
| `host` | The machine the operator SITS at, when it is not this one. Empty = read this machine's own screen. Set to an ssh alias and the gateway asks that host's screen agent instead: `ssh <host> <screenctl> ask --socket <agent_socket>`. The ssh'd client needs no display of its own — the agent on the far side holds the grant and the window server. |
| `agent_socket` | The agent's owner-only socket ON THE HOST. Only read when `host` is set. |
| `selection_max_chars` | Characters of the operator's SELECTION allowed into a prompt (`turn::selection_phrase`). Read through the same agent, by Accessibility rather than OCR: exact characters, the caret, and a secure field refused by subrole. Never a picture, never a keystroke. |
| `selection_write_max_chars` | Characters one `write_selection` may put into the focused element (Admin socket → screen agent → AX `AXSelectedText` setValue, verified by reading the value back). Never a keystroke, never the pasteboard; a secure field, a foreign secure-input holder and a denied app refuse before the first character moves. |
| `dictation_cleanup` | Tidy dictated words ("type this: …") before they are typed — fillers (um, uh), immediate repeats ("the the"), spoken self-corrections ("Tuesday — scratch that, Wednesday"), a capital and end punctuation, "at three" → "at 3". A guard refuses any tidy that adds, substitutes or reorders a word, and the raw words are typed instead. On by default; |
| `ssh` | Absolute, because a launchd-spawned adapter has no PATH (memory `gateway-spawned-adapters-have-no-path`). |
| `ssh_connect_timeout_ms` | ssh's per-ADDRESS connect timeout, which is the bound on what one unreachable address costs — not the bound on the call. Measured 2026-09-17: the laptop's `.local` name answers with a link-local and two global IPv6 addresses ahead of its IPv4 LAN address, and the IPv6 ones do not accept connections. |
| `ssh_address_family` | `inet` (the default) keeps this hop on IPv4. The screen agent is on the LAN, reached by an mDNS name whose IPv6 answers are the dead ones above; empty lets ssh try every address the name resolves to. |
| `ssh_control_persist_s` | Seconds an idle multiplexed ssh connection to the screen host is kept open. The first screen turn pays the handshake (\~300 ms healthy); the ones behind it reuse the master. 0 turns multiplexing off. |
| `ssh_control_dir` | Owner-only directory (0700) for the multiplex control socket. |

## `[calls]`

Is the operator in a call. `runtime/calls/vulpine-call status` (callctl before) on the operator's machine (over `[screen] host`'s ssh hop when that names another machine) — who holds the mic (CoreAudio process objects) and whether a camera runs anywhere (CoreMediaIO); fox9's own Glyph never counts. Off by default. While `in_call` the announcement governor holds proactive speech, the session-context line names the call and presence carries it.

| key | meaning |
|---|---|
| `enabled` | Poll the operator's call state. Off by default. |
| `callctl` | The signed adapter ON THE OPERATOR'S MACHINE (absolute); a missing local `vulpine-call` runs `callctl`. |
| `poll_ms` | Milliseconds between call probes (default 5000, clamped to 1000–600000). |
| `timeout_ms` | Bound on one call probe, in milliseconds (default 4000, clamped to 500–30000). |

## `[meet]`

/ ADR 0039: the meeting inlet. An adapter (`meetctl`) writes typed `meeting_*` events (`docs/contracts/meeting.v1.md`) as JSON lines on an owner-local unix socket; the segments land in the recall-by-clock timeline (`[retrieval] timeline_path`), so `pi_recall_window` answers from a meeting. Off by default, and off whenever the timeline is unset.

| key | meaning |
|---|---|
| `enabled` | Listen for meeting events. Off by default. |
| `events_socket` | The owner-local socket (`~` is the operator's home). Its directory is made 0700 and the socket 0600. |
| `segment_retention_days` | Days a transcript segment is kept (default and maximum 90; a larger value is clamped — lengthening retention is the operator's call, not a key's). |

## `[calendar]`

The operator's calendar, read on demand through the grant holder (`runtime/grants/VulpineGrants.app`, the LSUIElement bundle that owns the Calendars grant) on the operator's machine — `[screen] host` when that is another machine, the same ssh hop the screen and call reads take. Off by default. Titles and times go to the brain and the owner-local Admin socket only; the gateway keeps counts.

| key | meaning |
|---|---|
| `enabled` | Allow calendar reads. Off by default. |
| `bundle_id` | The holder's bundle id on the operator's machine. It is LAUNCHED (`open -n -W -b`), never executed by path: TCC attributes a grant to the responsible process, and only LaunchServices makes the bundle that. |
| `timeout_ms` | Bound on one calendar read, in milliseconds (default 8000, clamped to 1000–60000). |

## `[audio_output]`

Watch THIS machine's default audio output. `runtime/audioctl/vulpine-audio watch` (vulpine-audio, audioctl before; CoreAudio property listeners, no grant) prints a line per change; the gateway traces `output_device_changed{from, to, transport}` and raises an Admin event, so a reply that came out of the wrong speaker is explainable. Off by default.

| key | meaning |
|---|---|
| `enabled` | Watch the default audio output. Off by default. |
| `audioctl` | The signed adapter (absolute on the mini: the laptop-built copy; a missing vulpine-audio runs its audioctl). |
| `restart_ms` | Backoff base when the watcher exits. |

## `[pi_spend]`

Pi spend from the session files (`~/.pi/agent/sessions/`), every session of the last `window_days`, scanned every `scan_interval_s`, projected to the Admin app as microdollars per day / model / session and tool-call counts. On by default: it only reads files pi already writes.

| key | meaning |
|---|---|
| `enabled` | Scan the pi session files. On by default. |
| `sessions_dir` | pi's session directory (default `~/.pi/agent/sessions`). |
| `scan_interval_s` | Seconds between scans (default 60). |
| `window_days` | How many days of sessions are counted (default 7). |

## `[providers]`

(d): is an upstream provider degraded. `providerctl status` reads the public Statuspage feeds (OpenAI, Anthropic; xAI has none) every `poll_s`; every change is a trace row and an Admin event, and a degraded provider is one clause on the session-context line. Off by default. Since the adapter is the Rust binary, `vulpine-provider` since (`just install-vulpine-provider`; an old `providerctl` there answers for one release); a `.py` path still runs under `python`, the rollback to the retired script.

| key | meaning |
|---|---|
| `enabled` | Poll the provider status feeds. Off by default. |
| `python` | The interpreter, used only when `providerctl` is a `.py` script; unset by default (a `.py` with none configured reports `helper_missing`, never spawns `/usr/bin/python3`). |
| `providerctl` | The adapter (default `~/.local/state/vulpine/bin/vulpine-provider`, the Rust binary `just install-vulpine-provider` installs); a path ending in `.py` runs under `python` instead (the rollback: `retired/providerctl/providerctl.py`). |
| `poll_s` | Seconds between status reads (default 300, clamped to 30–3600). |
| `timeout_s` | Per-feed timeout passed to the adapter, in seconds (default 6, clamped to 2–30); the whole run is bounded at four times this. |

## `[announcements]`

/ ADR 0030: the announcement governor's knobs and what a camera label is worth. `enabled = false` keeps the board but never speaks (decisions still trace and project).

| key | meaning |
|---|---|
| `enabled` | Speak admitted announcements. On by default; off still traces every decision. |
| `budget_per_hour` | Spoken announcements allowed per hour before the rest go to the digest (default 6). |
| `quiet_after_operator_ms` | After operator activity, announcements wait this long, in milliseconds (default 5000). |
| `idle_window_ms` | The room counts as idle once the last operator request is this old, in milliseconds (default 60000); only an idle room can be interrupted. |
| `camera_labels` | Camera labels that are announced at all (default `person`, `car`, `package`, `ding`; `ding` is a doorbell press). |
| `camera_person_score` | Score of a `person` event, 0–1 (default 0.8). |
| `camera_car_score` | Score of a `car` event, 0–1 (default 0.4). |
| `camera_other_score` | Score of any other listed label, 0–1 (default 0.5). |
| `camera_motion_score` | Score of opted-in `motion` events, 0–1 (default: `camera_other_score`). |
| `camera_ding_score` | Score of a doorbell press (`ding`), 0–1 (default 0.9: it interrupts an idle room and is said as "Someone's at the front door."). |
| `camera_ttl_ms` | How long a camera line stays worth speaking. A person seen nine minutes ago is old news in a house ("we were all already inside"): older than this it becomes a notify record, never a spoken line. Kept equal to `camera_repeat_ms` by default. |
| `camera_repeat_ms` | One line per camera and label per this long (Frigate opens a new event every time a tracked object re-enters the frame). |
| `backoff_base_ms` | ADR 0030 §6: after a spoken line the operator ignores or rejects, the SOURCE (camera events, agent notices, background work) waits this long before its next line, doubling per consecutive ignore up to `backoff_max_ms`; one answered line resets it. |
| `backoff_max_ms` | Cap on the per-source backoff, in milliseconds (default 600000). |
| `route_to_room` | Speak an admitted line (camera, doorbell, background work, agent notices) through the room verb in the room presence puts the operator in, instead of on the session's own frontend — only on FRESH `occupancy`, `explicit` or `media` evidence for a room roomctl can reach that is not the frontend's own room. A failed room speak falls back to the frontend. |
| `quiet_hours` | (the operator 2026-09-29): quiet hours, local time `"HH:MM-HH:MM"` (may wrap midnight; the mini sets `"22:00-06:00"`, the lockdown period). Inside it a line that is not critical is held — recorded for the frontend and Admin, never spoken in a room or on a frontend. A critical line (a doorbell press, a person on an outdoor camera) is spoken as at any other hour; |
| `outdoor_places` | A `person` on a camera whose name, subject or room contains one of these words is critical (it pushes through quiet hours). |
| `room_asleep_defer` | Hold a line meant for a room whose area states hold `sleep` (a magic-areas room through homectl's occupancy row) until the room wakes; alarms are never held (default true; false is the rollback). |
| `room_asleep_max_hold_ms` | How long a sleeping room holds a line before it goes to the surface only, never spoken there (default 1800000, 30 minutes). |
| `progress` | (ADR 0050 S9): progress lines for long work. A brain turn whose tool runs quietly for 10 s gets one short line ("Still working on it."), then at most one per 20 s and three per turn; a background job gets one line at 2 and at 10 minutes through the governor; "how's it going" is answered from the gateway's own record (default true; false is the rollback). |
| `progress_card` | A tool that reports stages also gets a `card.v1` progress card on a frontend that draws cards (the stages done and active, the newest count, closed as done or failed), updated in place. Shown beside the spoken stage line, never in place of it: the gateway has no signal yet that the frontend is visible (default false; false is the rollback). |
| `roll` | FXH (the operator 2026-11-07 "announce that we're rolling the gateway and then announce when everything is 100%"): a roll's two lines on an idle session, through the governor's `roll` source. Before the swap the live gateway says "Updating myself, back in a minute."; |
| `roll_ready_timeout_ms` | FXH: how long the new gateway waits for its health rows to turn green after a roll before it gives up and says nothing (the log and the Admin's events name the rows that were not ready), in milliseconds (default 180000). |

## `[home_actions]`

/ ADR 0034 contract 3: verbs on home subjects. The adapter, interpreter and map come from `[home_bridge]`; this is the policy the gateway hands the adapter on every call — the kinds that act without asking and the subjects that must never act unconfirmed — plus the timing. Default-deny: a kind not listed is refused by the adapter.

| key | meaning |
|---|---|
| `enabled` | Allow verbs on home subjects. Off by default. |
| `allow_kinds` | Kinds whose verbs run at tier `auto` (lights, scenes, switches and players are all reversible). |
| `confirm_subjects` | Subjects refused with `confirmation_required` until the spoken approval capability can ask. |
| `timeout_ms` | Whole adapter run: the service call plus the state read-back. |
| `settle_ms` | Passed as `--settle-s`: how long the adapter waits for the state to read back before calling the verb ineffective. |
| `ask_back_on_ambiguous` | A spoken home verb the adapter refuses as `ambiguous_subject` is asked back ("Which one: A or B?") and the next utterance naming one candidate runs the verb on it. Off: the old refusal line, no answer window. On by default. |

## `[approvals]`

The spoken-approval product — the operator's policy file and the learned-trust store (the operator 2026-09-13: vajren's 3× rule, the file beside rooms.json).

| key | meaning |
|---|---|
| `policy_file` | `~/.config/vulpine/approval-policy.toml`; human-only edit; absent = default-deny defaults (template: tools/approvals/approval-policy.example.toml).: an `auto` line `agent:dispatch:the <folder> checkout on <host>` approves that checkout's dispatch prepare and pipeline at once (`by: policy`); a remove always asks.: re-read within 30 s of an edit (polled; |
| `trust_file` | `~/.local/state/vulpine/learned-trust.json` (0600). |
| `learned_trust` | Master switch for learning; the policy file can only narrow it. |
| `agent_requests` | The owner-local approval socket for typed agent requests (opskat shape): `<state>/approvals/<socket_name>` with the client key beside it. Off = no socket; agents fall back to their own prompts. |
| `socket_name` | File name of the approval socket in `socket_dir`. |
| `socket_dir` | Where the socket and key live; absent = `<state>/approvals`. |
| `annotate` | Say the decision band on a spoken card ("It looks like what you asked for." / "It looks like more than you asked for."). Off by default, and nothing fills the band yet, so the card is unchanged until both are true. Never decides anything. |
| `repo_policy` | AZ3 (ledger row 180): `false` ignores every checkout's `.vulpine/policy.toml` (a writable checkout could otherwise pre-authorize its own dispatches); the gateway logs `repo policy files disabled by the operator` and the Admin's Approvals section says so. The operator's approval-policy.toml can say the same in its own `[approvals]` table (re-read on change); either one switches the files off. |
| `never_repo` | AZ3: `true` is the same as `repo_policy = false`. |

## `[camera_frames]`

Camera frames for the Admin app. The vision adapter (`visionctl frames`, the same script `pi_who_is_there` looks through) pulls each mapped camera's latest frame from the camera platform into the Admin socket's own directory; the socket hands the Admin app names and capture times, never pixels. The camera platform's address and login live in the adapter's env file, never here. Active only with `[home_bridge]`.

| key | meaning |
|---|---|
| `enabled` | Fetch camera frames for the Admin app. On by default. |
| `visionctl` | The adapter; unset = `[home_bridge] visionctl` (vulpine-vision by default). |
| `height` | Frame height asked of the camera platform (240 ≈ 8–20 KB a frame). |
| `min_interval_ms` | The Admin app polls every 2 s; the platform is asked at most this often. |
| `timeout_ms` | One adapter run, every camera. |

## `[fleet]`

Fleet projection. The manifest (`~/.config/vulpine/fleet.json`) names the hosts, their ssh users and addresses and the probe key; nothing here is a secret. Since the adapter is the Rust binary, `vulpine-fleet` since (`just install-vulpine-fleet`; `fleetctl` before); a `.py` path still runs under `python`, the rollback to the retired script.

| key | meaning |
|---|---|
| `enabled` | Run the fleet adapter. Off by default. |
| `python` | The interpreter, used only when `fleetctl` is a `.py` script; unset by default (a `.py` with none configured reports `helper_missing`, never spawns `/usr/bin/python3`). |
| `fleetctl` | The adapter (default `~/.local/state/vulpine/bin/vulpine-fleet`, the Rust binary `just install-vulpine-fleet` installs; an old `fleetctl` there answers for one release); a path ending in `.py` runs under `python` instead (the rollback: `retired/fleetctl/fleetctl.py`). The key keeps its name. |
| `manifest` | The fleet manifest (hosts, users, addresses, probe key path). |
| `restart_ms` | Backoff base when the adapter process exits. |
| `announce_agents` | ADR 0030's third source, for real: an agent on a fleet host that stops working (`working -> idle\|done`, or `-> blocked\|waiting\|error`) is offered to the announcement board as a herdr lifecycle notice. |
| `agent_notice_cooldown_ms` | One notice per agent pane per this window; a chatty session that idles every minute is not spoken every minute. |
| `dispatch_quota_refuse_pct` | A herdr agent start of kind `claude` / `codex` on this gateway's host is refused (the reason is spoken) when the host's reading for that CLI is at or over this percent of a window that has not reset since — or the CLI says the window is reached. `0` turns the check off. Fails open with no reading. |
| `link_census` | ADR 0053 S1 (CL20): the link census from this host's side (`fleetctl links --json`, every minute beside the host routes), the Fleet panel's shadow Links card; nothing alerts on it. On; false stops the census. |
| `herdr_census` | ADR 0054 S2 (CM8): each declared herdr host's machine state and ssh reach (`fleetctl herdr-hosts census --json`, every minute beside the link census), the Fleet panel's Herdr hosts card. On; false stops it. |
| `link_alerts` | ADR 0053 §6 (CM10): severed-link alerts from the census, through notify: a peer severed in two censuses in a row, its return, ten minutes degraded, flapping, or most hosts lost at once. Per host, fleet.json's `link_alerts` (`urgent`, `notice`, `off`; a console defaults to `notice`). On; false stops every alert. |

## `[decision_shadow]`

follow-up: the flag-off gateway shadow over `decidectl`. The cascade is asked in order — kev.serve's LoRA on loopback first, the frozen-encoder head as the fallback — under ONE deadline, the session's follow-up window (`fallback_deadline_ms` when the window is off). `/ready` is read when the gateway builds the shadow, then again every 30 s and after a helper fault.

| key | meaning |
|---|---|
| `enabled` | Run the decision shadow. Off by default. |
| `pack_path` | The question pack (`benchmarks/verbs/questions-v2.json`). The gateway resolves a relative path against its own working directory, so give the mini an absolute one. |
| `questions` | The pack questions asked on a partial; empty = every question the state leaves open. The two nouls are the cheap reads (r4: 136 ms). |
| `entries` | The cascade, asked in order (default: `lora` on port 8871, then `head` on 8872).: the ANE helper (`runtime/systemone-ane`, kev r6 build J) is one more row, `{ name = "ane", url = "http://127.0.0.1:8873/v1/systemone", model = "r6-ane-j" }`; not in the default until it runs on the mini. |
| `attempt_timeout_ms` | A cap on one model's attempt so a hung model leaves time for the next. |
| `breaker_cooldown_s` | How long a faulted (or not-ready) model is skipped before one probe. |
| `ready_timeout_ms` | Each `/ready` read's budget per model (the start-up read and the re-reads). |
| `fallback_deadline_ms` | The deadline when the session's follow-up window is 0 (off). |
| `home_stage` | On a station with home verbs, put up to five devices in view and the speaker's room in the request and ask the pack's home stage beside `questions`. The answer is traced (the `homectl act` it would run, an ask-back line, an approval annotation); nothing runs. |
| `home_subjects_path` | A `homectl subjects` capture (`benchmarks/verbs/home/subjects-*.json` shape: `{subjects: [{subject, label}]}`) whose labels name the devices; without one a label is derived from the subject id. |
| `partials` | How many distinct partials of one utterance are asked (the first non-empty one, then each that grows, up to this many) so the stable verdict can see two in a row. `1` asks the first partial only, as before. |
| `stable_arm` | The stable verdict's hysteresis on `is_command` — it arms at or over this and disarms only under `stable_disarm`. |
| `stable_disarm` | The hysteresis band's lower edge (see `stable_arm`). |
| `stable_alone` | A raw "would route" whose top probability (the routing choice's, else `is_command`'s) is at or over this is stable on its own, without a second agreeing partial. |
| `state_assistant_last_said` | Send `assistant_last_said` (fox9's own last spoken line) in the request's state. Off by default: no served model was trained on the key yet, so it would move their inputs off the distribution the receipts measured. The trace carries its length and age either way. |
| `warm_on_arm` | When the wake arms a request, send one cheap front-door ask (`is_command`, `complete`, no home stage) so a cold model pages its weights in before the first real partial. Traced as `decision_shadow_warm`, never as `decision_shadow`. |
| `warm_deadline_ms` | The warm ask's own deadline, long enough that a cold page-in finishes instead of being abandoned at the turn's budget. |
| `warm_skip_recent_s` | No warm ask when the last ask (or warm) ended less than this long ago; the model is warm inside a conversation. `0` warms on every arm. |
| `home_stage_gate` | When the home stage joins an ask. `is_command_or_device` (default): only when this utterance's previous front-door answer had `is_command` >= 0.5 or the partial's words name a device in view — otherwise the ask is the 2-question front door (\~200 ms against \~1 s). `always`: every ask on a home station carries the stage, as before. |
| `injection_guard` | Write an `injection_guard` row beside each committed turn's `speaker_verify` / `echo_acoustic` rows: the source guard's verdict (`held`, `reasons`) over the echo share, an active call, the speaker verdict and live playback. Shadow only, independent of `enabled`: the flag gates the ROW; nothing is held, refused or routed. |
| `mirror` | Entries (by `name`, from `entries`) asked on EVERY shadow ask beside the cascade, at the same time and under the same `request_id`, so two models answer one partial and the answers pair (`tools/telemetry/shadow_pair.py`). Each answer is a `decision_shadow_mirror` row (`mirror: true`); it never changes the cascade's answer or the turn. |
| `mirror_timeout_ms` | One mirror ask's own timeout (not the turn's budget); running out of it is a fault that opens the entry's breaker. |
| `mirror_max_load_per_core` | No mirror ask while the host's 1-minute load per core is at or over this (the 0.35 bar a turn's latency verdict uses); the row says `mirror_skipped` with `reason = "host_load"`. `0` turns the bar off. |
| `motion_plan` | (docs/contracts/avatar-action.v1.md): when a reply is done and the bound frontend declared avatar verbs with closed arguments, ask the cascade the `motion_plan` question over them (under `fallback_deadline_ms`, off the spoken path) and route the pick as `avatar_action` (`source: llm_directive`); |
| `motion_plan_min_margin` | The margin (decision.v1's one confidence) a `motion_plan` answer needs to act; under it the lexicon picks. BH2: the committed lock's margin (benchmarks/verbs/motion-plan.v1.lock.json, compiled by tools/verbs/motion_plan_score.py; provisional while its scorer is the fixture cue model, until a served model's answers recompile it). |
| `context` | Every `decision_shadow` row, and every turn-outcome record (`[training] outcomes`), carries the utterance's `decision_context` block: numbers and labels only (the speech span, the ambient windows over it on the sidecar's feed clock, the level over the 60 s floor, playback overlap, the enrolled speaker score of every utterance, wake, the hashed room, presence, armed). |
| `cuelight` | CJ39: the block's `cuelight` part: CueLight-Nano's speech probability over the span (mean, max, the frames under fox9's playback and the mean without them), read after the wake fan-out's canceller when `[invocation] fanout_aec = "daf"`, else from the raw mic. In-process ONNX on one thread per session, about 0.5 ms per 20 ms of audio; a busy worker skips audio and counts it. |
| `cuelight_model` | CJ39: CueLight-Nano's streaming ONNX (the export its browser demo runs, Apache-2.0; never in git). A missing file leaves the part `absent: no_model` and the gateway runs on. |
| `cuelight_veto` | The shadow CueLight veto. Each turn-outcome record carries `cuelight_veto` at settle: a frozen score over the router's is_command logit, the span's length and CueLight's speech mean and max (`benchmarks/verbs/cuelight-veto-weights.v1.json`, fitted once through 2026-11-07), its 0.90-recall threshold and `would_veto`. Shadow only: nothing routes on it. Default true; |

## `[stt]`

`[stt]`: the authority lane's recogniser rules. `longform = { enabled, silence_aligned_starts, preroll_ms, rehear_ms, hard_cap_s }` (off; 200 ms / 600 ms / 14 s when on).: `on_fault = "end_session" | "text_only"` (default `end_session`).: `fault_injection = true` admits the owner-local Admin request `stt_fault_inject` (default `false`; needs `[admin] enabled = true`).

| key | meaning |
|---|---|
| `longform` | The long-form window rules for a segment that outgrows the encoder window (`benchmarks/results/longform-window-rules-20261003.md`). |
| `on_fault` | What a session does when its recogniser is lost, `end_session` (the default) or `text_only` (`docs/contracts/adapter-degradation.v1.md`). `end_session` sends `stt_error {recoverable: false}` and the next microphone frame ends the session. |
| `fault_injection` | Admit the owner-local Admin request `stt_fault_inject`, which makes one session's STT reader report a terminal error once (traced `stt_fault_injected`), so a QA read can exercise `on_fault` on purpose (`benchmarks/qa/sections/26-stt-fault.toml`). Off by default: the request is refused `stt_fault_injection_disabled`, so a live gateway never exposes it. |

## `[media]`

`[media]`. Every wake arm and hold-to-talk press leaves one `media_pause` row (is media playing, by the ambient sidecar's share or the home bridge's player state; would it pause; which roomctl room) whatever this says.

| key | meaning |
|---|---|
| `pause_for_request` | Pause the room's media through roomctl (`[room_speakers]`) for the request and resume it at the reply's end, a disarm, the hold's settle or 20 s. Off by default: off, nothing calls roomctl. |

## `[echo]`

`[echo]`, reference texts for the bigram echo gate beside the reply the gateway spoke (`[invocation] echo_text_gate`).

| key | meaning |
|---|---|
| `lyrics` | While `spotify-cli playback status` says a track is playing, fetch its synced lyrics from lrclib.net (title, artist and duration leave the machine, once per track; 3 s bound) and hold a commit that matches the lines sung within 8 s of the playback position (`echo_lyrics` trace row, drop reason `song_lyrics`). Off by default: off, nothing polls or fetches. |

## `[wake]`

`[wake]`. `lvq_shadow = true` runs an echo canceller (`runtime/localvqe-worker`) on the session's mic with the TTS it plays as the far end, and a second wake worker on its output; that worker's wakes are `wake_lvq` trace rows and never arm anything. Off by default.

| key | meaning |
|---|---|
| `lvq_shadow` | Run the canceller shadow (needs `[invocation]` on: the second wake worker is the same detector). |
| `lvq_worker_bin` | The canceller worker: one JSON status line, then `hop` mic + `hop` far-end f32le in, `hop` enhanced f32le out. |
| `lvq_worker_args` | Its arguments, e.g. `["--model", "<path to localvqe-v1.3-F32.gguf>"]`. |
| `lvq_gate_source` | Which stream's level opens, closes and resets the second wake worker's fan-out gate. `raw` (default): the raw mic's, the decisions the live gate makes on the same samples, while the audio admitted is the canceller's output; the canceller's own near-silence never resets the stream (`aec-canceller-comparator-20261003` (b): P2 lost to a reset on it). |
| `p_operator_model` | A personal-VAD ONNX export (nomo-pvad's shape: 2.4 s of 16 kHz audio and an enrolled-speaker embedding in, P(enrolled) per 160 ms frame out); when set, every session runs the window every hop and stamps `p_operator` on its wake rows. It never arms or refuses anything. Unset = off. (`~` is the operator's home.) |
| `p_operator_enrolment` | An f32le enrolled-speaker embedding, used when the speaker-sim gate's profile (`VULPINE_SPEAKER_PROFILE`) does not match the model's embedding width. |

## `[operator_affect]`

`[operator_affect]`, the Admin's operator-affect panel; ADR 0044: affect may shape how fox9 drives a turn, and the voice never states a diagnosis (the diagnosis guard). A revocable opt-in (off by default): while off, the Admin shows only "off", the receipt file is never read and nothing below runs. The panel projects a receipt the replay tool (`tools/eval/operator_prosody_replay.py`) wrote, aggregates only. The opt-in's logged timestamp is the config file's mtime; the panel shows "paused" while the operator channel is muted at the mixer.

| key | meaning |
|---|---|
| `opt_in` | Show the panel's numbers (default false). Turning it off hides everything again on the next gateway start. |
| `receipt_path` | The replay receipt (JSON, the `operator-prosody-baseline-*.json` shape) to project, e.g. one under `~/.local/state/foxline/`. Never shown on the Admin socket. |
| `retention_days` | Days the replay's PRIVATE per-turn rows (`--per-turn-dir`, refused inside the repo) and the friction records are kept (default 7). Opted in, the gateway removes `operator-prosody-turns-*.jsonl` and `friction-<YYYYMMDD>.jsonl` files older than this from the receipt's own directory at start and daily (`operator_affect_purged` rows); nothing else, nowhere else. Between 1 and 365. |
| `live` | The live estimator (default false). On (with `opt_in`), each session keeps a 12 s mic ring in memory and every committed spoken turn gets an `operator_affect_turn` trace row: prosody numbers, cue names and a score, never text or audio. Off, no ring is allocated and no row is written. |
| `friction_records` | ADR 0044: write private friction records beside the receipt (default false; needs `opt_in` and `live`).: when a turn's cue score reaches `friction_threshold` (at most once a minute) one `fox9.friction/v1` line, holding the window's words and the reply as spoken, goes to `friction-<YYYYMMDD>.jsonl`; the trace gets an `operator_friction` row of counts and the Admin a friction count. |
| `inform_brain` | ADR 0044: send the brain the operator style hint (default false; needs `opt_in` and `live`). |
| `friction_threshold` | ADR 0044: the cue score at which an exchange becomes a friction record (default 3). Between 1 and 100. |
| `config_mtime_ms` | The config file's mtime (Unix ms), set by the loader; not a key. |

## `[tts]`

`[tts]`, switches on the text the gateway hands its TTS. Read once at gateway start (`tts_text::install_diagnosis_guard`).

| key | meaning |
|---|---|
| `diagnosis_guard` | The diagnosis guard (default true): a sentence that diagnoses the operator ("you sound stressed") is dropped before speech and counted as `tts_diagnosis_dropped`. false = the kill switch; every sentence is spoken as written. |
| `read_continuation` | Read continuation (default false). On, a read's segment after the first is planned with the previous segment's last \~4 s of audio and its words as the ICL reference instead of the voice clip (a mood change, a seek or a re-read resets to the clip), traced as `tts_read_continuation`. The continuation is sent (worker frame 4) only to a worker that advertised it; |
| `leaked_call_guard` | The leaked-call guard (default true): a tool call the brain writes as prose (a `<pi_show_render />` tag, `pi_house_now: {...}`, a starred name over a JSON fence, `<tool_call>...</tool_call>`) is dropped before speech and counted as `tts_leaked_call_dropped`; the transcript keeps it. false = the kill switch; every character is spoken. |

## `[adapters]`

`[adapters]`, the adapter tier as the gateway runs it (ADR 0034).

| key | meaning |
|---|---|
| `supervision` | `[adapters.supervision]`: restart with backoff, degrade to text. |

## `[music]`

`[music]`, the duck window. While the assistant's reply is sounding (the `assistant_playback` lease: the client's first `audio_playback_observed{active}` to its stop, the reply's finish, the session's end or `duck_cap_ms`), the gateway runs `tapctl duck --pid <app> --until-stdin-eof` and closes its stdin when the lease ends; tapctl ramps the app back up and exits. One `music_duck` row per start and end (`pid`, `gain`, `ms`).

| key | meaning |
|---|---|
| `duck` | Lower the playing app's sound while a reply sounds. Off by default: off, nothing spawns tapctl. |
| `duck_app` | The app to duck, by its exact process name (`pgrep -x`); default `Spotify`. Not running: no duck, one `music_duck` row says so. |
| `tapctl` | Absolute path of the signed tapctl (`just build-tapctl` builds and signs it beside `tapctl.swift`; the gateway never builds or installs it). Unset or relative: no duck. |
| `duck_gain` | The app's gain while ducked, 0–1 (default 0.2). |
| `duck_ramp_ms` | The ramp down and back up, in milliseconds (default 150). |
| `duck_cap_ms` | A duck window closes after this long even if the lease has not ended, in milliseconds (default 30000); it reopens at the next reply. |

## `[speaker]`

(enrolled gate S7, docs/design/enrolled-gate-next-signal-2026-10-11.md section 3b, the operator's G7 (a)): `[speaker]`. `glyphctl enroll start --seconds <n>` captures the bound Glyph's mic for n seconds of audio (only while that connection is the operator's voice owner, never inside an inject span), embeds each 1.5 s speech window with the resident profile embedder (the enrolled gate's;

| key | meaning |
|---|---|
| `enrollment_from_mic` | Allow `glyphctl enroll start` (default false: every start is refused `switch_off`, and the Admin's Enrollment row says so). The operator turns it on for the sitting and off after it. |
| `enrollment_dir` | Where the enrollment writes its profile, `speaker-profile-glyph-<unix ms>.f32le` (created mode 0700 when missing). Unset: `speaker/` under the gateway's state folder. |

## `[retention]`

AU8 (the mini's disk audit, benchmarks/results/mini-disk-audit-20261011.md): `[retention]`. Once a day (and once at start) the gateway MOVES its own trace files (`trace_dir`, not recursive) older than `traces_days` and the render receipts (the folder `VULPINE_RENDER_RECEIPT_DIR` names) older than `render_receipts_days` into `retired/<UTC date>/traces/` and `retired/<UTC date>/render-receipts/` under the gateway's state folder.

| key | meaning |
|---|---|
| `traces_days` | Days a trace file is kept by its modification time (default 14); 0 turns the trace rule off. Between 1 and 365 otherwise. |
| `render_receipts_days` | Days a render receipt (its JSON and WAV) is kept by modification time (default 7); 0 turns the receipt rule off. Between 1 and 365 otherwise. |
| `retired_days` | AV10: days a `retired/<UTC date>/` folder stays under the state folder, by the date in its name (default 0 = off). When set (1 to 365), each pass moves an older dated folder whole into `retired_holding`; never deletes. |
| `retired_holding` | AV10: the existing absolute folder `retired_days` moves dated folders into (a path on an archive volume, one per host). No default: `retired_days` without it is refused at load. A folder that is missing at pass time (the volume not mounted) is never created: the pass moves nothing and the Health row warns. |

## `[panels]`

(ADR 0045): `[panels]`, curated panel templates (`catalog/panels/<name>/`): a card's `template.v1` block, its data checked against the template's schema and compiled to SVG in a sandbox (`crates/panel_templates`). Off by default: a template block is then refused at `blocks.N.type` and no catalog loads.

| key | meaning |
|---|---|
| `templates` | Compile `template.v1` card blocks for frontends that declared them. Off by default. |
| `templates_dir` | The template catalog folder. Empty = `catalog/panels` under the runtime root (`VULPINE_RUNTIME_ROOT`, else the checkout the gateway was built from). |
| `compile_deadline_ms` | Bound on one template compile, in milliseconds (default 1500, held to 50..=10000). A template that misses it is refused until the gateway restarts. |
| `pages` | (docs/contracts/page.v1.md): `[panels.pages]`, the web pages a panel may show, by name: each an `https` URL and the words that ask for it (`[panels.pages.retro-weather] url = "https://weather.com/retro/"`, `aliases = ["retro weather", "retrocast"]`). The default holds retro-weather; a config that sets the table names the whole list. |

## `[unaddressed_words]`

BV15 (the operator's ruling 2026-10-20 19:58): `[unaddressed_words]`. The words of every final the turn machine drops `not_armed` (unaddressed room and TV speech, already decoded, until now kept as a length only) are written under `root`, one `<UTC date>/<session>.jsonl` file per session and day, a row `{session, t, text, chars, wake}` each; folders 0700, files 0600. They are the decision router's real negative pool (`tools/verbs/negative_pool.py traces --store`).

| key | meaning |
|---|---|
| `keep` | Keep the words (default false). Household speech: the operator's call, made 2026-10-20 for the router's D5 pool. |
| `root` | The absolute folder the dated folders go under (on the mini, the external drive). No default: `keep` without it is refused at load. |
| `retention_days` | Days a dated folder is kept, today included (default 14), between 1 and 365; older folders are deleted at start and once a day. |
| `context` | Each kept row also carries the utterance's `decision_context` block (numbers and labels only: span, ambient, level, playback, speaker score, wake, hashed room, presence, armed), written once the block settles (a few seconds). Default true; false keeps the old row shape. |

## `[catalog]`

`[catalog]`: the Catalog as the gateway checks it at bind.

| key | meaning |
|---|---|
| `bind_check` | What the bind-time Catalog check refuses: `drift` (default) refuses a bind whose Catalog package no longer matches the digest its index records; `strict` also refuses a package, loadout or extension that no index names (anything outside `catalog/` needs an `external.toml` manifest) and a tree with no index; `observe` refuses nothing. |

## `[spans]`

`[spans]`, the span layer: guard-bound timings of the turn's stages and of each recognition (crates/vulpine_spans on fastrace), one row per finished span in `spans-<UTC date>.jsonl` in the trace folder (`{ts, t_ms, event: "span", data: {trace_id, span_id, parent_id, name, begin_unix_ns, duration_ns, properties}}`; `ts` is the span's begin). The Admin's `gateway.spans` Health row shows the switch, the counts and the latest duration of each stage. On by default (the operator 2026-10-22: features ship on);

| key | meaning |
|---|---|
| `enabled` | Report spans (default true). False installs no reporter: every span is a no-op and no file is written; the Health row says off. Read at start. |
| `sample_one_in` | One root span (a turn, a recognition) in this many is recorded with its children (default 1: every one; 0 reads as 1). |
| `max_mib_per_day` | A day's span file stops growing at this many MiB (default 32, held to 1..=1024); the rows past it that day are counted on the Health row, not written. |

## `[capture]`

`[capture]`: captures on typed turns (docs/contracts/capture.v1.md).

| key | meaning |
|---|---|
| `enabled` | Accept a capture on a `text_utterance` (default true). False refuses each one with `capture_disabled`. |
| `brain_images` | The brain takes images (default true: pi does). False sends a capture's text alone, and the prompt asks the brain to say the images were not sent. |
| `clip_transcription` | CD4: answer the `transcribe_clip` door, a recording's narration through the authority STT lane (default true). False refuses each clip with `clip_disabled`, and the recorder uses Apple's SpeechAnalyzer. |

## `[files]`

`[files]`: what the brain may show from this gateway's disk (docs/contracts/file.v1.md).

| key | meaning |
|---|---|
| `enabled` | Show files (`pi_show_file`; default true). False refuses each one with `file_off`. |
| `roots` | The folders a shown file must sit in (after symlinks are followed); `~/` is the gateway user's home. The default is the home folders a person keeps their own files in: Desktop, Documents, Downloads, Pictures and Movies. Never the home itself (its dot folders hold keys and tokens) and never the state folders. |
| `max_bytes` | The most bytes a shown file may have (default 32 MiB; at most 256 MiB). |
| `find` | Find a file by description (`pi_show_file {describe}`) on this disk (default true). False refuses each one with `find_off`; a path is shown as before. |
| `find_min_margin` | The decision model's pick of a close find is taken at or above this margin (0..=1; default 0.5). |

## `[door]`

`[door]`: the headless door. On by default.

| key | meaning |
|---|---|
| `enabled` | Serve the headless door (default true). False binds no socket. |
| `socket_dir` | Where the socket and its key live; absent = `<state>/door`. |

## `[usage]`

`[usage]`: the usage ledger (ADR 0050 §5). On by default.

| key | meaning |
|---|---|
| `enabled` | Count every tool call, verb and door call per day in `<state>/usage-ledger.redb` (default true). Off counts nothing and leaves the store as it is. |

## `[notify]`

`[notify]`: notify that reaches the operator off the session (`NotifyConfig`, in `notify.rs`). On by default; each transport is on once it is configured.

| key | meaning |
|---|---|
| `enabled` | Accept notify lines from the brain (`pi_notify`) and the gateway's producers (default true). False refuses each with `notify_off` and pushes nothing. |
| `ha_service` | The Home Assistant companion app's notify service, without `notify.` (like `mobile_app_<phone>`); homectl calls it through the home bridge's map and token. Empty (the default) leaves the transport unconfigured. |
| `ntfy_url` | The ntfy topic URL (`http://<host>:<port>/<topic>` on the home server). Empty (the default) leaves the transport unconfigured. |
| `ntfy_token_env` | The environment variable holding the ntfy access token (set in the overlay's `gateway.env`). Empty, or unset in the environment, sends without a token. |
| `fleet_ntfy_url` | ADR 0053 §6 (CM10): the fleet topic on the control server's ntfy, outside the house (`https://ntfy.fleet.voidfab.com/vulpine-fleet`): a third transport, so an urgent line (a severed fleet link) also reaches the phone when the house's own ntfy is down with it. Empty (the default) leaves it unconfigured. |
| `fleet_ntfy_token_env` | The environment variable holding the fleet topic's ntfy token (the publisher's `tk_` token, set in the overlay's `gateway.env` with `just ops::env-set`; default `VULPINE_NTFY_FLEET_TOKEN`). Empty, or unset in the environment, sends without a token (the server refuses it). |
| `curl` | The curl that publishes to ntfy (the request, token included, goes on its stdin). |
| `per_hour` | Notify lines accepted in any trailing hour, every producer together (default 10); one more is refused `rate_limited`. |
| `dedupe_window_ms` | The same words again within this window are `deduped`: no new line and no new push (default 10 minutes). |
| `board_ttl_ms` | How long a normal line waits on the board to be spoken before it goes to a transport (default 10 minutes). |
| `push_timeout_ms` | One transport call's budget (default 10 s). |

## `[training]`

`[training]`: training data from use. Signal 1, the turn outcomes, is on by default.

| key | meaning |
|---|---|
| `outcomes` | Keep one record per settled router decision with what happened next, in `<state>/training/turn-outcomes/` (default true; owner-only, never the words). False writes nothing and leaves the folder as it is. |
| `outcome_window_s` | Seconds after a decision settles that its outcome is watched (default 20, 2..=120). |
| `outcome_retention_days` | Days of records kept (default 30); older dated files are deleted at start and once a day. |
| `false_fire` | The false-fire label (default true): "I wasn't talking to you" (a closed gateway verb, no brain turn) labels the turn fox9 last acted on `false_fire`, and the Admin's Recent turns card has a "Wasn't for me" button. False: the phrases go to the brain and nothing is labeled. |
| `missed_address` | The missed-address label (default true): "I was talking to you" labels the final the turn machine last dropped `not_armed` as meant for fox9, and the card has a "Missed" button. False: the phrases go to the brain and nothing is labeled. |
| `source_veto` | The shadow source veto (default true): each record carries `source_veto`, the frozen 4-weight score and whether it would have vetoed; nothing routes on it. False writes no block. |
| `label_words` | LQ2 (the operator's request of 2026-11-04): keep each settled utterance's words for the Admin's Label queue (default true), beside the records in `<state>/training/label-words/`, owner-only, eight dated files. False writes nothing and leaves the folder as it is. |
| `label_queue_echo` | FXI (the operator 2026-11-07: "most of the captured items is vulpine speaking actually"): the Admin's Label queue holds out the turns that were fox9's own voice heard back (default true): fox9 audible over at least half the span and the loudest voice not the enrolled operator's, or the words fox9's own. False lists them as before. |
| `label_queue_wakeless_slots` | Of a Label queue sitting's 12 turns, the slots reserved for wake-less turns (the wake word not in the words, the served build's, fox9's own voice held out), so the route bar's live wake-less block gets its 30 verified turns of each class (default 6; 0 turns the quota off and the page is the teach order). |
| `label_queue_uniform_slots` | LQ1b: of those, the slots drawn uniformly (teach value ignored), so the queue's selection bias can be measured (default 3; at most the wake-less slots). The rest go to the class the block is short of first. |

## `[sound]`

`[sound]`: sound watches and rules over the ambient sidecar (`SoundConfig`, in `sound_watch.rs`). On by default.

| key | meaning |
|---|---|
| `enabled` | Track the sidecar's windows per room, answer `sound` watches and run the operator's sound rules (default true). False: the hook reads nothing, a `sound` watch is refused `sound_unsupported` and a rule `sound_off`. |
| `rooms` | Rooms that have a mic before one is heard (kebab case, like `front-room`); heard rooms are added on their own. |
| `on_score` | A run starts when its class scores at or above this (default 0.35). |
| `off_score` | A run is held while its class scores at or above this (default 0.15). |
| `release_ms` | A run ends after its class stays under `off_score` this long (default 5000 ms). |
| `detector` | Engine 2, the 54-class sound-event detector, beside SoundAnalysis (default true): CK17's CoreML sidecar (`fox9-sound-detector`, runtime/sound-detector) runs per session with a mic once its sidecar and its model (`detector_model`) are on the host; missing either, the `gateway.sound` row says which. False: never spawned. |
| `detector_bin` | The detector's sidecar binary, speaking `fox9-pcm-f32le-v1` like the ambient sidecar. Empty (the default): `fox9-sound-detector` beside `[ambient] worker_bin`. |
| `capture` | Keep a ring of each session's sidecar audio in memory and capture clips from it into the owner-only labeling inbox (a labeling class firing, "tag that as ...", the Admin's Capture now). Default true. False: no ring is kept and nothing is captured; the inbox and the heads stay readable. |
| `ring_seconds` | CJ38: seconds of audio the ring holds (default 20, 10..=30); memory only, never written unless captured. |
| `capture_before_s` | CJ38: seconds of the ring a capture keeps before its moment (default 7). |
| `capture_after_s` | CJ38: seconds a capture waits for and keeps after its moment (default 3). |
| `inbox_max_clips` | CJ38: clips the inbox holds at most (default 200, 10..=1000); the oldest unlabeled go first. |
| `inbox_days` | CJ38: days a clip is kept (default 30, 1..=365). |
| `trainer_bin` | CJ38: the sound-head trainer (`fox9-sound-head-trainer`, Create ML). Empty (the default): the one beside `[ambient] worker_bin`. |
| `detector_model` | The detector's CoreML program (`.mlpackage` or `.mlmodelc`; never in git, staged by sha256 with `just ops::models-stage sound-detector-<part> <host>`). Missing, engine 2 is not spawned and the `gateway.sound` row says "detector model not installed". |

## `[webhooks]`

`[webhooks]`: signed events from other services (`WebhooksConfig`, in `webhook_intake.rs`). On by default; no listener until a source is listed with its secret set.

| key | meaning |
|---|---|
| `enabled` | Take signed events from the listed sources (default true). False runs no listener whatever is listed. |
| `bind` | The listener's address: loopback only (a Cloudflare tunnel route reaches it from outside, ADR 0051). |
| `max_body_bytes` | The largest body taken (default 64 KiB, at most 1 MiB); a larger one is refused before it is read. |
| `tolerance_s` | How far the signed moment may sit from now, either way (default 300 s, 30..=900). |
| `per_minute` | Accepted events per source in any trailing minute (default 30); one more is refused 429. |
| `classify_deadline_ms` | The decision model's budget for one event (default 2 s, 100..=15000 ms). |
| `min_margin` | The margin (top minus second probability) under which the model's route is not taken (default 0.2). |
| `sources` | The senders the operator allowed (none by default). |

## `[utterance]`

`[utterance]`: the utterance.v1 record.

| key | meaning |
|---|---|
| `rows` | Write one `utterance` trace row (schema `utterance.v1`) per committed spoken utterance (default false): its timings, levels and prosody numbers, never audio or words, computed on the blocking pool after the commit. On, each session keeps a 12 s mic ring in memory and the Admin's Performance section gets today's records per device. Off, no ring is allocated and no row is written. |

## `[endpoint]`

`[endpoint]`: adaptive endpointing.

| key | meaning |
|---|---|
| `adaptive` | `"off"` (default) or `"shadow"`: shadow scores each authority-mode endpoint on its finality cues and adds the hold it would have used to the `stt_endpoint_decided` trace row; nothing commits earlier. `"live"` is refused. |
| `min_hold_ms` | The shortest hold the scorer may propose, for the most final-sounding ending (100..=700, default 300). |
| `max_hold_ms` | The longest hold it may propose, for a filled pause or a rising trail (700..=3000, default 1200). |

## `[agent_link]`

`[agent_link]`: the agent door. On by default; with no agent linked, no call ever arrives.

| key | meaning |
|---|---|
| `enabled` | Admit frontier agents' calls (default true). False refuses every call `agent_link_off`; the socket stays bound so the connector can say so. |
| `dir` | The folder the socket, its key, the connector's view and the gateway's revocations share; absent = `<state>/agent_link` (the connector's default state folder). |
| `spoken_answers` | An agent's question with options takes a spoken answer ("Say main, release, or skip.") inside `[herdr] witness_window_ms` after it was spoken (default true). False: the question is spoken without the invitation and only the Admin's typed answer reaches the agent; the approval socket's `ask` op refuses. |

## `[mood_pick]`

`[mood_pick]`: the mood picker's shadow. On by default (the operator 2026-10-22: features ship on, a switch turns them off).

| key | meaning |
|---|---|
| `enabled` | Pick a mood for each brain reply's first segment and write one `mood_pick` trace row (default true). False writes nothing and the Admin row says off. The pick is never sent to the TTS worker in this version. |

## `[hooks]`

`[hooks]` in the gateway config.

| key | meaning |
|---|---|
| `user_consumers` | Catalog Observe consumers (`catalog:<id>` in a loadout's `[lifecycle.observe]`) run. On by default; nothing fires until a loadout registers one. `false` admits none and fires none (the rollback). |
| `webhook_hosts` | Host names or addresses a `webhook` consumer may post to beside loopback (`homeassistant.local`). Empty: loopback only. |

## `[decision_gate]`

`[decision_gate]`: the decision gate (ADR 0062). On by default; it routes only while the served build is the lock's.

| key | meaning |
|---|---|
| `enabled` | Drop a follow-up-window final whose front-door `is_command` is under the lock's threshold (default true). False is the rollback: every follow-up final takes today's path and the Admin row says off. |
| `lock_path` | The lock `tools/verbs/route_bar.py lock` wrote (identity, temperature, threshold). A relative path is read against the gateway's working directory, so give the mini an absolute one. Missing or invalid: the gate abstains everywhere and the Admin row says why. |
| `late_shadow` | The late gate's shadow (default true). Each final the follow-up window takes is asked again on its own text, off the turn path, and a `late_gate_would_cancel` row times the answer against the reply's first audio. It cancels nothing. False stops the extra ask. |
| `quiet` | QAC2 (ADR 0068 stage 0): quiet accept, `"off"`, `"shadow"` (default) or `"on"`. Shadow judges each final dropped `not_armed` whose gate read was answered on the lock's identity and writes one `quiet_would_accept` trace row (and a `quiet` block on its turn-outcome record); nothing routes. `"on"` routes nothing yet: it behaves as `"shadow"` until stage 1. |
| `quiet_p_min` | ADR 0068: the lower bar on the lock identity's `is_command` p for a quiet verdict (default 0.5, 0 to 1). |
| `quiet_recent_ms` | ADR 0068: the engagement term: fox9's last playback ended, or a wake was detected, at most this many ms before the final (default 10000). |
| `quiet_speaker_min` | ADR 0068: the speaker term: the span's enrolled-speaker cosine is at or over this (default 0.35). |
| `quiet_ttl_ms` | ADR 0068: how long a quiet card stays before it fades (default 60000, 5000 to 600000). Read from stage 1 on. |
| `quiet_max_per_hour` | ADR 0068: at most this many would-be-quiet verdicts per session per rolling hour (default 12); past it the verdict is a drop with reason `rate`. |

## `[packs]`

`[packs]`: extension packs (design §7's rollback switch). Off by default; off, the Admin's Packs section reads "packs off" and no loader reads the installed catalog root.

| key | meaning |
|---|---|
| `enabled` | Serve the pack manager (install, enable, update and remove extension packs from the Admin), and read an enabled pack's hardpoints, hook consumers and skills from the installed catalog root. Off by default. The loaders read the switch when the gateway starts. |

## `[push]`

`[push]`: the phone's wake pushes. Off by default; the sender stays off until the key exists.

| key | meaning |
|---|---|
| `apns` | Send `pushtotalk` wakes straight to Apple (default false). Needs `bundle_id`, `team_id`, `key_id` and the key in the login keychain under `keychain_service` / `key_id`. |
| `environment` | `sandbox` (api.sandbox.push.apple.com: development-signed builds) or `production` (api.push.apple.com: TestFlight and the App Store). Default `sandbox`. |
| `bundle_id` | The phone app's bundle id; the topic is `<bundle_id>.voip-ptt`. Empty (the default) leaves the sender off. |
| `team_id` | The Apple developer team that owns the key (the provider token's `iss`). Set on the gateway host only. |
| `key_id` | The key's 10-character id (the provider token's `kid`, and the keychain item's account). |
| `keychain_service` | The login-keychain generic-password service the key is stored under (default `vulpine-apns`). |
| `send_timeout_ms` | One wake's whole budget: connect, TLS, the request and its answer (default 5 s). |
