# Vulpine > Vulpine, a self-hosted voice runtime: how it works, how to run it, and how to extend it. ## Docs - [Vulpine](https://vulpine.voidfab.com/docs): Vulpine, a self-hosted voice runtime: how it works, how to run it, and how to extend it. ## Install and operate - [What Vulpine is](https://vulpine.voidfab.com/docs/install-and-operate/what-vulpine-is): Vulpine gives the agent you already run a voice, and keeps it in your house. You speak, and a Mac in your house hears you. Vulpine answers simple requests itself, at once. - [Install](https://vulpine.voidfab.com/docs/install-and-operate/install): Install Vulpine on a Mac with its two signed apps. Open Vulpine Gateway.app: its setup window does the rest, in order, and ends when the doctor is green. Nothing is built on your Mac and you need no terminal. - [Developer install](https://vulpine.voidfab.com/docs/install-and-operate/install-developer): Install Vulpine from the repository: clone, then just install. Installing with the signed apps instead is Install. It runs the steps below in order and ends with just doctor. - [Run the gateway](https://vulpine.voidfab.com/docs/install-and-operate/voice-gateway): The Rust voice gateway: running it locally, where its config file lives, rolling a new version on the mini (overlay-status, overlay-roll-internal) and its build features. - [Release and rollback](https://vulpine.voidfab.com/docs/install-and-operate/release): How to cut a gateway release, roll it to the gateway host and roll it back. just release folds the changelog, tags, builds and writes a receipt. just rollback prints how to go back. - [What you can say](https://vulpine.voidfab.com/docs/install-and-operate/voice-commands): What you can say to fox9 by voice: start with the callsign "Fox Nine", "niner over" closes a request at once, the verbs the gateway settles itself (cancel, start over, say again, reading controls, the mic, lights on and off, dictation), and everything else goes to the brain (home devices, room speakers, timers, coding agents). - [Key decisions](https://vulpine.voidfab.com/docs/install-and-operate/key-decisions): The design decisions that shape how you install, run and extend Vulpine. Each entry says what was decided, why, and what it means for you. ## The voice path - [Architecture](https://vulpine.voidfab.com/docs/the-voice-path/architecture): One voice turn as the code runs it on the Mac mini: the Rust Voice Gateway as the sole gateway and brain path, with its STT, turn machine, speculative brain dispatch and streamed TTS. - [Glossary](https://vulpine.voidfab.com/docs/the-voice-path/glossary): The glossary: what Vulpine's (fox9's) words mean, from the gateway, brain, skins, Client Core, protocol, agent, persona and loadout to the presentation seams; the decision model, the brain lanes, speech and the install moved to docs/context-runtime-glossary.md on 2026-10-15. - [Glossary: runtime terms](https://vulpine.voidfab.com/docs/the-voice-path/runtime-glossary): The glossary's second half, split from CONTEXT.md on 2026-10-15: the decision model, decision.v1 and its shadow, the injection guard, the two brain lanes, the approval socket and sealed grants, adapters, rooms and home verbs, the tool door, the STT fault rule, the read and turn-close terms, the routing heads, the gateway's answer windows, the first-token budget, the speech lanes, the Meet legs, satellite controls, and the doctor, runtime manifest and language rule. - [The early start](https://vulpine.voidfab.com/docs/the-voice-path/speculation): Speculative brain dispatch: the gateway starts the brain on the stable partial transcript before the operator has finished talking, holding output and tools; it promotes the answer when the final matches, and forks the pi session and re-dispatches the committed text when it differs. - [Loadouts](https://vulpine.voidfab.com/docs/the-voice-path/loadouts): Loadouts, the voice-session configuration under .vulpine/: how to give the brain a tool (the loadout's extensions and its allowed_pi list), the frontend tools it requires, and the Pi model and thinking settings. - [Project memory retrieval](https://vulpine.voidfab.com/docs/the-voice-path/retrieval): How the brain looks up project memory: bounded, citation-bearing project evidence added before a turn from an index built by tools/retrieval/build_retrieval_index.py, marked untrusted, failing closed when the index is missing or malformed, without giving voice input tools, shell access or write authority (ADR 0007). - [Speech recognition](https://vulpine.voidfab.com/docs/the-voice-path/speech-recognition): The speech to text that runs on the Apple Neural Engine: a Rust runner for Parakeet TDT 0.6B v3 through CoreML, the encoder on the Neural Engine and the decode loop on the CPU. - [Echo canceller weights](https://vulpine.voidfab.com/docs/the-voice-path/echo-canceller-weights): The LocalVQE DAF controller weights that crates/aec_daf compiles in, and where they came from. - [Echo canceller worker](https://vulpine.voidfab.com/docs/the-voice-path/echo-canceller-worker): lvq-worker runs LocalVQE v1.3 (s2s.cpp's ggml/Metal port) for the gateway's [wake] lvq_shadow lane. The gateway feeds it the session's 16 kHz mic, with the TTS it is playing as the far end, and runs a second wake worker on its output. - [Ambient sound tags](https://vulpine.voidfab.com/docs/the-voice-path/ambient-sidecar): The gateway can tag what the room sounds like around a turn (speech, music, typing, a door, a beep) with Apple's built-in SoundAnalysis classifier: 303 classes, shipped with the OS, no model to install and no microphone grant, since the… - [Room audio captions](https://vulpine.voidfab.com/docs/the-voice-path/ambient-caption): A small audio language model over the last 30 s of room audio. - [The spoken voice](https://vulpine.voidfab.com/docs/the-voice-path/spoken-voice): Swap Vulpine's spoken voice, add a mood voice, and roll back. just models installs the qwentts.cpp tts-server on :8850 with qwen-talker-0.6b-base-Q8_0 (tools/install/models.toml); the gateway registers its voice there as operator, ICL. ## The brain - [Brain tools](https://vulpine.voidfab.com/docs/the-brain/brain-tools): The bundled pi extension that gives the voice brain its gateway tools: work capture and status, background work, alarms and timers, the self-tools over the Admin socket, and the bounded Herdr tools. - [Speculation tool gate](https://vulpine.voidfab.com/docs/the-brain/speculation-tool-gate): The side-effect gate for speculative brain dispatch. Each client-owner attachment has its own private gate file, in an owner-only directory per owner and generation. - [Tool policy and search](https://vulpine.voidfab.com/docs/the-brain/tool-policy): vulpine-tools (was foxline-tools), the canonical pi extension for the voice brain's policy and tools (local search, the Herdr dispatch tools, the tool-call guard, the bash policy, Exa MCP) and its test runtimes. - [Agent pipelines](https://vulpine.voidfab.com/docs/the-brain/pipelines-rounds): The vulpine-tools pipelines rounds, split from its README on 2026-10-15: the ripwire task map, the fallback kinds and report-now grace (round 9), start_unknown, stage usage and run evidence (round 10), the whole-stage usage, the start re-prompt and the herdr agent pack (round 11), and round 12: a command word held in a variable, the exact fleet usage read, the growth-only stall and the held agent_not_ready start. - [MCP servers](https://vulpine.voidfab.com/docs/the-brain/mcp-servers): Which MCP servers the voice brain can use: moraine (the agent-session index) and fox9docs (the docs site on the mini), declared per loadout profile in catalog/agents//.vulpine/mcp/.json as a secondary path; the brain sees only the tools the loadout's allowed_pi lists. - [Tool manifests](https://vulpine.voidfab.com/docs/the-brain/tool-manifests): Tool manifests (tool.v1 S3): one folder per catalog tool holding its tool.toml, an optional guide.md and golden calls; bun catalog.ts lints them by named rules and compiles the passing ones into catalog/pi/tool-manifests.json, the file the runtime reads; lint-corpus/ is the lint's fixture corpus shared with the conformance kit. - [Todo list for pane agents](https://vulpine.voidfab.com/docs/the-brain/todo-list): The todo_list tool for pi in a herdr pane: pi-todo-list's state machine with the list kept in a file per working directory under ~/.local/state/foxline/todo-list/, so it survives new sessions; how to load it on pi 0.84.x (FOX9_TODO_LIST=1 pi -e ..., or just install-fox9-todo-list-local). Not part of the voice loadout. ## Frontends - [Frontends overview](https://vulpine.voidfab.com/docs/frontends/overview): The Fox9 frontends and their platform shells: the Vigil and Glyph frontend skins, the Fox9 Admin app and the Voice PE satellite bridge; `just apps::vigil-build` builds Vigil with the gateway settings baked in and `just apps::vigil-install host=` ships it to the mini's state folder. - [Vulpine in a browser](https://vulpine.voidfab.com/docs/frontends/web-app): Vulpine in a browser, the web app: what it shows (a call frame, the transcript, the panel), how to build, install, serve and open it on the gateway host at 127.0.0.1:8794, and the showcase that needs no gateway. - [Vulpine.app, the desktop app](https://vulpine.voidfab.com/docs/frontends/desktop-app): Vulpine.app is the desktop app on the Mac (bundle id com.voidfab.vulpine, productName in src-tauri/tauri.conf.json). Glyph is its look: an ambient overlay that sits on screen beside your work. - [Vulpine.app design principles](https://vulpine.voidfab.com/docs/frontends/desktop-app-design): Who Glyph is for, the job it does at the desk, and the product principles its design follows. - [Terminal frontend](https://vulpine.voidfab.com/docs/frontends/tui): The vulpine terminal skin on pi-tui: a client of the gateway over the Client Core bound as vigil / ui (text only), with the shared voice rows, the transcript and the brain's ask-back dialogs answered as text utterances; tested headless against a loopback fake gateway. - [Make your own orb look](https://vulpine.voidfab.com/docs/frontends/make-your-own-orb-look): How to add your own orb style: what a style is, its two files, the WGSL fragment and its settings table, the tests that prove it, the pictures to look at, and the still and lists that put it in the pickers; an agent can follow the make-orb-look skill. - [Vulpine on iPhone](https://vulpine.voidfab.com/docs/frontends/phone): The GPUI-owned iOS app: Talk with hold-to-talk and the voice state chip, Connect by invitation code behind the GatewayLink trait, Settings; the state model, the audio start order (the settle order by default, --audio-legacy) and the reply's rate after a route change, the launch arguments, and how to build, test and screenshot it in the simulator. - [Vulpine Gateway.app](https://vulpine.voidfab.com/docs/frontends/gateway-app): The GPUI Admin (ADR 0060), installed as Vulpine Gateway.app: the Admin's sections in one GPUI window, reading through admin_core in process, the ported sections, how a panel lane adds a panel (one module, two lines of the registry, its own baseline folder), and how to install and open it. - [The Gateway window](https://vulpine.voidfab.com/docs/frontends/admin): Fox9 Admin (shown as Vulpine Admin), the native local operator surface of ADR 0016: the gateway owns its projections and mutation admission, the app reads them over the owner-only Unix socket, the install recipe, and each panel (health, events, presentation, agents, dictation, meetings, plus the shadow pair, satellite, held announcements and adapter rows) with its current mutation boundary. - [Gateway window: string safety](https://vulpine.voidfab.com/docs/frontends/admin-event-string-safety): How strings in Admin events are kept safe: no string from an Admin event crosses admission, storage, the Unix socket, Tauri IPC or export without the canonical sensitive-text policy. - [Gateway window: performance](https://vulpine.voidfab.com/docs/frontends/admin-performance-evidence): The Admin performance projection: the gateway aggregates only milestones its live voice path accepted, in order on one connection (an accepted final, the committed turn, the first admitted brain token and on), never trace files or browser timing. ## Contracts - [Contracts overview](https://vulpine.voidfab.com/docs/contracts/overview): The versioned wire and file shapes, one file per contract; a breaking change is a new file. - [JSON Schemas](https://vulpine.voidfab.com/docs/contracts/json-schemas): One generated JSON Schema per wire (frontend 5, Admin 6, decision.v1) from crates/protocol, drift-tested. - [Frontend WebSocket](https://vulpine.voidfab.com/docs/contracts/frontend.v5): A connection attaches one durable owner, the frontend instance, so a reply, a resume or a dialog answer never goes to the wrong client. - [Gateway owner socket](https://vulpine.voidfab.com/docs/contracts/admin.v6): Each request is tagged by type (snake_case) and each answer by type too. A request that changes something is owner-local: the gateway refuses it owner_local_required unless it arrives on the owner-local control endpoint. - [ACP agents](https://vulpine.voidfab.com/docs/contracts/acp-integration.v1): Accepted design, ADR 0065: independent off-by-default ACP client and agent roles beside the voice path; exact human-owned permission scopes, managed child confinement, herdr-fenced attachment, bounded lifecycle and unknown dispatch retention. Sixty-nine abstract qualification scenarios, including mandatory resource links without implicit fetching; no runtime implementation or activation. - [ACP boundary](https://vulpine.voidfab.com/docs/contracts/acp-boundary): Phase 3 foundation: bounded framing/RPC, permissions, prompt translation and lifecycle effects, plus Unix SQLite admission, durable intents, resolved retention, fenced prompt-write pumps, bounded egress, a durable pre-session connection owner, live direction-policy fencing, pinned SDK method/reply decoding, owned wire initialization, pending session reservation and partial observed-effect corpus replay. Exhaustive fault qualification and runtime interpreter/provider integration remain pending; no gateway linkage. - [ACP terminal attachment](https://vulpine.voidfab.com/docs/contracts/hc-terminal-rpc.v1): An operator starts a program with a dedicated RPC sideband. A terminal without that sideband cannot be attached. The program keeps its terminal and its external profile: hc supplies neither managed confinement nor human approval. - [ACP provider registry](https://vulpine.voidfab.com/docs/contracts/acp-provider-registry.v1): Unshipped declaration codec, not an installed configuration interface or readiness proof. It describes provider bindings for acp-integration.v1, not another tool catalog. - [Decision model](https://vulpine.voidfab.com/docs/contracts/decision.v1): What the decision model returns for a turn: the typed-decision wire, one POST with typed questions in and one typed answer per question out (noul 0..1, choice with probabilities over the criteria keys, score); a choice is accepted only when it is a criteria key, the probabilities sum to 1 and their argmax is the choice. Every front-door router speaks it. - [Turn budget](https://vulpine.voidfab.com/docs/contracts/turn-budget.v1): Each turn leg's millisecond budget (speech end to commit, commit to first text, first text to first audio, first audio to audible, a tool round, a panel's paint, a barge's stop): the p50/p90 table, how a budget is set from a read, the rule that a change adding ms to a leg names the leg that gives them back, and where the Admin's Turn budget row and the offline reader show it. - [Utterance records](https://vulpine.voidfab.com/docs/contracts/utterance.v1): One typed record of numbers per committed spoken utterance (utterance.v1): its timings, levels and prosody, the device key that keeps baselines apart, the ADR 0044 rules (off by default, never audio or words, computed after the commit), the Admin's per-day Utterances row and the fields later slices append. - [Proactive cards](https://vulpine.voidfab.com/docs/contracts/proactive-card.v1): What fox9 may say unprompted (the card), how the announcement governor tiers it, and the answers the operator may give. - [Answer cards](https://vulpine.voidfab.com/docs/contracts/answer-card.v1): Draft: the closed card (list, metric, camera still, approval pointer) Glyph shows beside a spoken answer. - [Panel cards](https://vulpine.voidfab.com/docs/contracts/panel-card.v1): The panel card (card.v1) the brain or a tool fills: one composite of a title, a spoken one-line summary, an optional headline number and one to four typed blocks (stats, list, chart, table, heatmap, timeline, progress, status, compare, breakdown, forecast, text), their bounds, the refusals with the path the brain must fix, the fallback ladder (an undeclared block as text, a table projection), the render frame's appended turn_id, and what the Admin shows. - [Script visuals](https://vulpine.voidfab.com/docs/contracts/visual.v1): A script visual (visual.v1, pi_show_visual): the body (title, summary, script), the Luau ui tree a frontend draws (layout, text, stats, tables, charts, tabs, toggles, sliders, buttons, canvases, 3D scenes, Shadertoy shaders), the sandbox's rules and budgets, the gateway's dry run and its refusal with the line to fix, who gets the visual whole and who its card, and the conversation window's GPU pictures at rest at 0 frames. - [Files in the panel](https://vulpine.voidfab.com/docs/contracts/file.v1): A file the brain shows (file.v1, pi_show_file): the request (path, title, page), the gateway's checks in order (the allowed folders [files] roots after symlinks, no dot-dot, no hidden or secret part, a regular file within [files] max_bytes) and their typed, sayable refusals, the type sniffed from the bytes, the FileSpec body (name, mime, size, sha256, page), who gets the file and who its card, the file_fetch / file_chunk / file_fetch_refused frames and who may fetch, and what the Admin row logs. - [Web pages in the panel](https://vulpine.voidfab.com/docs/contracts/page.v1): A named web page in the render panel (page.v1): the gateway's registry [panels.pages] (a name, an https URL, the words that ask for it; retro-weather is the seed), the show_page verb and pi_show_page {name} (never a URL), the PageSpec body and its bounds, the unknown_page refusal, who frames the page (Vigil, the Glyph) and who gets its card, the frame's sandbox, the gateway.pages Health row and the GPUI page host still to come. - [Link lists](https://vulpine.voidfab.com/docs/contracts/links.v1): Experimental operator-activated link panels: bounded labels and checked web destinations, explicit per-frontend declaration, destination-free owner/observer fallbacks, and native pointer/keyboard activation. Passive card.v1 remains unchanged. - [Captures](https://vulpine.voidfab.com/docs/contracts/capture.v1): A capture (capture.v1): the bundle in the frontend's private store (capture.json: keyframes with their OCR text, marks in keyframe pixels, narration, note; the marked and sent copies; the contact sheet), the one text_utterance { capture } behind capture_attachment, the gateway's bounds and refusal reasons, the prompt images pi gets with the text block beside them, the text-only brain, the user_transcript echo and the Admin row's counts and bytes. - [Avatar actions](https://vulpine.voidfab.com/docs/contracts/avatar-action.v1): The avatar wire: the five verbs (set_expression, play_animation, set_state, focus, clear) with closed, bounded arguments (intensity, hold_ms, onset, queue, a source ladder), the vocabulary a rig publishes at bind (an empty declared set refuses everything), the four refusal reasons, and the routed/refused counts the Admin shows per frontend. No producer yet. - [Avatar rigs](https://vulpine.voidfab.com/docs/contracts/avatar-puppet.v1): The rig side of the avatar wire: how every rig (VRM, Live2D, the 2D fox) draws typed picks, with the VRM 1.0 override table, the gaze split over spine, chest, neck, head and eyes, the VRMA rest-pose retarget, the face director (1.1 s dwell, 0.85 apex cap, per-family onset and release, blinks) and the gated five-question decision.v1 set. - [Dictation](https://vulpine.voidfab.com/docs/contracts/dictation.v1): Hold-to-talk dictation on the ws: the dictation_hold control, the dictation_partial and dictation_text frames and who types them, the client's insert proof (dictation_inserted) and the erase_last_insert the spoken 'scratch that' resolves to, with its spoken refusals. - [Speech adapter failures](https://vulpine.voidfab.com/docs/contracts/adapter-degradation.v1): What one client is told when its own speech adapters fail: the readiness text_only change for TTS and the typed stt_error {reason, recoverable, session_id} for a lost recogniser, sent to the affected connection only, [stt] on_fault (end_session or text_only, with stt_recovered when the recogniser is back), and the Client Core's typed error {code, requestId}, and the adapter tier: [adapters.supervision] restarts homectl on a jittered backoff, answers a home verb in text while it is down, and shows adapter. rows in Admin Health. - [Connectors](https://vulpine.voidfab.com/docs/contracts/connector.v1): Connectors: a third-party account linked on the gateway's host so a brain tool works (WhatsApp, Gmail, the Dot, feeds, Apple Health, OBS); one row in the gateway's registry joins a setup census row (its state) with what it unlocks, its one action and the steps read from its README at build time; the Admin's Setup section draws them as a Connections card (AdminSetupCensus.connections) and the Glyph's welcome window as a Connections page from /connections/connections.json; the menu says Connect accounts while one waits. - [Reading aloud](https://vulpine.voidfab.com/docs/contracts/reading.v1): The read verb on the wire: start_read and reading_control, the reading_progress answers (request_id echo, the optional active:false for a stop with no read open), the read_fetch_cancelled / read_fetch_superseded / read_fetch_failed errors that answer a page fetch by its request_id, their order, the spoken controls open while a fetch is pending, and the Client Core's typed code / requestId / active. - [Room speaker controls](https://vulpine.voidfab.com/docs/contracts/satellite-controls.v1): A satellite's physical controls on the wire: the satellite_control frame (button_press single/double/long, dial delta/value, mute on), what the gateway maps each to by the turn machine's state (over, cancel, start_over, mute_toggle, mute_set, room_volume), the dial's clamp, rate limit and settle, and the satellite_control / satellite_over / room_volume_set rows. Back to the satellite: the satellite_state {volume?, muted?} event (on bind, when a dial settles, when the mute changes), its fan-out to every satellite in the same room (room_peer), the mute and last state carried across an over-and-out rotation, and the Sonos clip taking the gateway's room volume below 5. - [Skills](https://vulpine.voidfab.com/docs/contracts/skill.v1): The skill tier (ADR 0050 S7): a skill is a .vulpine/skills// folder holding SKILL.md (and references/*.md, never code) whose frontmatter names the catalog tools it composes (tools), the memory keys it learns (facts) and its voice-corpus lines (tests); the gateway lints and resolves each at bind (ready, degraded with the missing tools and why, or refused), passes the loaded ones with --skill, counts a SKILL.md read as a skill trigger, shows a Skills row per skill in the setup census, and [brain] skills = false turns it off. - [Tools](https://vulpine.voidfab.com/docs/contracts/tool.v1): tool.v1 (accepted, ADR 0058; S1-S3 built): every catalog tool takes one call shape, {tool, action, args}, with eight shared actions (list, get, search, create, update, delete, act with an op, watch) and answers {ok, data, receipt, ask_back?, error{code, hint}}; a tool is declared by one tool.toml manifest (typed bounded args, capabilities and egress, approval, receipt fields, error codes, a latency budget, provenance, a guide) answered by a native, pi extension, MCP or JSON-in/JSON-out CLI handler; the brain's prefill teaches the envelope once (about 177 tokens) and declares each on tool slim (typed args, a one-line description, the guide on demand through pi_tool_search get); vulpine tool check lints, golden-tests and prices a tool; semver rules per contract and per tool. - [Tool index](https://vulpine.voidfab.com/docs/contracts/tool-index.v1): tool-index.v1 (accepted, ADR 0063; S1 and S2 built): the one list of registered tools, tool-index.json in the vulpine config folder, each with its provenance record (origin, signer, the sha256 and path of what runs, installed_at/by, requires, doors, invocable, last_used, calls_30d); a reader in Rust (vulpine_cli) and in TypeScript (vulpine-tools, Effect) marks a tool unavailable when a pinned file is missing or its sha256 differs; vulpine tool list / why / describe / doctor read it, JSON on a pipe, and list shows vulpine-* PATH programs as found_on_path, not registered, not runnable, never run; brain_* tools are invocable only at the gateway door. - [Tool packs](https://vulpine.voidfab.com/docs/contracts/tool-pack.v1): tool-pack.v1 (proposed, ADR 0064; built): the unit a user downloads, ---.tar.gz, a strict deterministic ustar holding pack.json (kind tool, helper or engine; os, arch, min_gateway, min_client, requires, team_id, entitlements, license, source commit, check report digest, sha256 per file) and its files; tools-index.v1.json lists packs and revoked versions and is signed with ssh-keygen -Y sign -n vulpine-tools-index by the operator's hardware key; vulpine tool pack builds only what vulpine tool check passes, and vulpine tool verify runs every install-time check in order (index signature, archive sha256, per-file sha256, revoked, os and arch, codesign Team ID, lint) with a typed reason per refusal, running nothing from the pack. - [Extension packs](https://vulpine.voidfab.com/docs/contracts/extension-pack.v1): extension-pack.v1 (proposed, ADR 0067; built): one installable unit over the existing carriers (tool-pack archives, inline files by sha256, hashed assets); extension-pack.toml (pending hashes, per-component from) and the extension-pack.json record share one shape; crates/extension_pack holds the one validator the CLI and the gateway call (unknown fields, closed kinds, categories, steps and capabilities, contract ranges, trust rules, inline hashes and sizes) and lists held components with their reasons; vulpine pack check and vulpine pack build run offline, the build is reproducible and prints the tools index packs[] entry. - [Sidecar windows](https://vulpine.voidfab.com/docs/contracts/sidecar-envelope.v1): Draft: the bounded tree a sidecar window draws (the Glyph's conversation window first): thirteen closed node kinds with stable ids, props, roles and stable accessibility labels; one snapshot then patches with a generation and a base revision; 1 MiB, 4,096 nodes and depth 64; resync on a gap; the closed refusals with their paths; checked by crates/sidecar_envelope. - [Voice profiles](https://vulpine.voidfab.com/docs/contracts/voice-profile-manifest.v1): Draft: the manifest a Voice Profile candidate carries before any synthesis (consent record, the four sha256-hashed inputs, a profile id derived from persona, seed and hashes, operator-owned WER and naturalness budgets) and the codes the checker tools/speech/voice_foundry.py refuses it with. - [Meeting events](https://vulpine.voidfab.com/docs/contracts/meeting.v1): Typed meeting events from the Meet adapters into the gateway: meeting_started / meeting_segment / meeting_ended / meeting_forget / meeting_opt_out on the owner-local [meet] socket, the per-line acks and closed refusal reasons, how segments land in the recall-by-clock timeline, retention, tombstones and the spoken forget / stop-recording verbs. - [Hardpoints](https://vulpine.voidfab.com/docs/contracts/hardpoint.v1): Accepted, 1.0 built for stt and tts (ADR 0059): a hardpoint is a typed runtime slot (stt, tts, wake, decision, brain, voice, avatar, render, room, memory, retrieval) with one owner and one effective binding per scope; an implementation is a hardpoint Catalog entry whose hardpoint.toml declares its slot, contract range, provenance, transport, capabilities, memory peak, latency budget and fallback; the loadout binds it under [hardpoints] ([adapters] stays an alias for the deprecation window); the owner qualifies it with the slot's probe (nothing audible) before claiming ready, falls back to the built-in as degraded on failure, and reports it on readiness and the Admin's Hardpoints card. stt and tts open first. - [Hardpoint: speech to text](https://vulpine.voidfab.com/docs/contracts/hardpoint.stt.v1): The stt hardpoint slot 1.0: the built-ins (parakeet-silero, native-parakeet-silero, in-process-parakeet), what a user speech recognizer does (the STT worker wire, a WebSocket on loopback, declared audio_in), its probe (the wire opens within 5 s) and its fallback; the ANE authority lane never replaces a user recognizer. - [Hardpoint: text to speech](https://vulpine.voidfab.com/docs/contracts/hardpoint.tts.v1): The tts hardpoint slot 1.0: the built-in qwen3-worker, what a user speech output does (a Wyoming TTS server on loopback: synthesize in, audio-start, audio-chunk, audio-stop out, 16-bit PCM), its probe (one fixed sentence rendered to bytes, never played, timed to first audio against first_text_to_first_audio's p90) and its fallback; catalog/hardpoints/wyoming-kokoro is the first-party entry, bound with [hardpoints] tts = "wyoming-kokoro". - [Hooks](https://vulpine.voidfab.com/docs/contracts/hooks.v1): Proposed (ADR 0059): lifecycle hooks; a boundary (session.start.after and session.end.after live with the built-in admin_receipt; invocation.arm.after, brain.turn.settled.after and readiness.changed.after proposed) hands a typed event with ids, closed reasons and ms only to consumers the user supplies as hook_consumer Catalog entries (script on stdin, signed webhook; herdr plugin and pi extension later), registered under [lifecycle.observe]; one non-blocking enqueue at the commit, a deadline per delivery, at most once, one receipt per attempt with a closed disposition; Gate and Mutate only after the authority review. - [Reach: pairing](https://vulpine.voidfab.com/docs/contracts/reach-pair.v1): Every reach ALPN rides iroh =1.4.1: QUIC with TLS 1.3 over raw public keys, dialed by EndpointId, through a relay or on a direct path. A client must speak iroh's wire: link iroh at a version wire-compatible with 1.4.1. - [Reach: WebSocket](https://vulpine.voidfab.com/docs/contracts/reach-ws.v1): A key paired by reach-pair.v1 whose row grants ws (every client row by default). The helper's accept rule runs after the TLS handshake and before a byte. - [Reach: voice](https://vulpine.voidfab.com/docs/contracts/reach-voice.v1): A key paired by reach-pair.v1 whose row grants voice. That is a client row: client rows get voice by default, and a row paired without it pairs again to gain it. - [Reach: agent sessions](https://vulpine.voidfab.com/docs/contracts/reach-mcp.v1): No paired row may hold mcp, and the helper closes any paired key on this ALPN with code 4 (role) before a byte, whatever its row says. A session's key is a fresh, throwaway iroh key: ## Adapters and integrations - [Integrations](https://vulpine.voidfab.com/docs/adapters-and-integrations/overview): How a third party plugs into fox9 (ADR 0034): every integration is an adapter outside the gateway on one of two contracts, verbs out (a command and one JSON receipt) or events in (JSON lines), and keeps the upstream's names and credentials to itself. - [Home adapter](https://vulpine.voidfab.com/docs/adapters-and-integrations/home-adapter): homectl, the events-in adapter (ADR 0034) outside the gateway through which fox9 controls the lights and devices in the house: it holds the Home Assistant client, emits the house (lights, speakers, switches, presence) as fox9 subjects in JSON lines, and runs one home verb at a time with homectl act --subject --verb ; subcommands init, list, probe, subjects, run, act. - [Room adapter](https://vulpine.voidfab.com/docs/adapters-and-integrations/room-adapter): How to play fox9 on a room speaker: roomctl, now vulpine-room (the Rust binary ~/.local/state/foxline/bin/vulpine-room, crates/vulpine_room; just install-vulpine-room; roomctl is a link to it for one release) on the mini, e.g. vulpine-room speak --room --text "...", the one room-target interface behind the brain tool pi_room_speak and the gateway's room route (glyphctl speak --room); rooms live in ~/.config/foxline/rooms.json. - [Meet adapter](https://vulpine.voidfab.com/docs/adapters-and-integrations/meet-adapter): How meetctl cuts, closes and sends the Meet far leg: the --far-cut, --turn-close, --provisional and --realtime flags, their defaults and rollbacks, and the fixture numbers behind each (latency, cpWER, labels, replaces). - [Phonon voice hardpoint](https://vulpine.voidfab.com/docs/adapters-and-integrations/phonon-voice): xn-ptts as the tts hardpoint in your own trained Phonon voice file: where the voice file, its pace and the loadout's tts_voice each live, the per-voice pace patch and its build, the launch line (-0.04 for the operator voice), and what the Admin's Hardpoints card shows. - [Room speaker](https://vulpine.voidfab.com/docs/adapters-and-integrations/room-speaker-bridge): The Voice PE puck as a fox9 frontend skin (ADR 0033): one Node bridge per device, ESPHome's native API on one side and the gateway's protocol as an ordinary client on the other; one puck turn from the on-device wake to the playback receipt. - [The Vulpine site](https://vulpine.voidfab.com/docs/adapters-and-integrations/site): Vulpine's landing page: a static Astro page whose three numbers are rebuilt from receipts, its build and naming-lint recipes, the Vercel config, and whether Blume 2.0.3 can deploy the docs to Vercel. The docs' Vercel preview is built by `just docs::docs-site-build-vercel`; both projects are previews only and the orchestrator deploys them. ## Reference - [API surfaces](https://vulpine.voidfab.com/docs/reference/api-surfaces): Every interface something outside one vulpine process can speak to, with its stability label and its auth (the gap analysis is docs/design/developer-experience-gap-analysis-2026-11-08.md). The source is docs/contracts/api-surfaces.toml. - [Brain tools](https://vulpine.voidfab.com/docs/reference/brain-tools): Every tool the voice brain can call, from catalog/pi/tool-catalog.json (itself generated from the extensions' registrations and the loadouts). guarded tools pass the gateway's guard; writes says what a call can change. - [Command lines](https://vulpine.voidfab.com/docs/reference/cli): Every command-line tool in the repo: the ctl adapters and helpers (Python, Swift, TypeScript) and the Rust binaries. The description and usage come from each tool's own header; a Swift one's build: line names the recipe that builds it. - [Components](https://vulpine.voidfab.com/docs/reference/components): Every folder under apps/, runtime/, services/, crates/ and tools/, described by its README or its main module's own header. - [Gateway config](https://vulpine.voidfab.com/docs/reference/config): 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. - [Hook tiers](https://vulpine.voidfab.com/docs/reference/hook-tiers): Every hook step in hk.pkl, by tier. The tier is the // tier: line above the step's definition; tools/repo/hook_tiers.py --check (the pre-commit step hook-tiers) keeps the line, the hooks that run the step and this page in agreement. - [Recipes](https://vulpine.voidfab.com/docs/reference/recipes): Every public recipe, in file order, with the comment written above it: the front page (the root justfile, what just lists) first, then each module (just/.just, run as just ::; just --list shows the same… ## Agent resources - [llms-full.txt](https://vulpine.voidfab.com/docs/llms-full.txt): The full Markdown of every page in one file. - [Page Markdown](https://vulpine.voidfab.com/docs/index.md): Append `.md` to any page URL to fetch that page as raw Markdown. - [JSON API](https://vulpine.voidfab.com/docs/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://vulpine.voidfab.com/docs/openapi.json. - [MCP server](https://vulpine.voidfab.com/docs/mcp): Streamable HTTP Model Context Protocol server with search_docs, get_page, list_pages, and get_navigation tools, plus every page as a resource. Discovery document: https://vulpine.voidfab.com/docs/.well-known/mcp.json - [API catalog](https://vulpine.voidfab.com/docs/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here. - [AI catalog](https://vulpine.voidfab.com/docs/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs). - [agent-readability.json](https://vulpine.voidfab.com/docs/agent-readability.json): Manifest of every agent-facing artifact on this site. - [Sitemap](https://vulpine.voidfab.com/docs/sitemap.xml): Every indexable page URL with its last-modified date.