config

type AgentBridgeConfig struct {
	Enabled bool              `toml:"enabled"`
	Codex   CodexBridgeConfig `toml:"codex"`
}

type AgentBridgeProject struct {
	Alias   string `toml:"alias"`
	Path    string `toml:"path"`
	Sandbox string `toml:"sandbox"` // effective = min(global, project); empty inherits read-only
}

type AssemblyAIProviderConfig struct {
	Enabled          bool   `toml:"enabled"`
	APIKeyEnv        string `toml:"api_key_env"`
	STTModels        string `toml:"stt_models"`
	StreamingModel   string `toml:"streaming_model"`
	StreamingBaseURL string `toml:"streaming_base_url"`
	// SyncBaseURL overrides the synchronous Universal-3.5 Pro endpoint.
	// Empty uses the global https://sync.assemblyai.com; set the regional
	// https://sync.us.assemblyai.com or https://sync.eu.assemblyai.com for
	// data-zone pinning.
	SyncBaseURL string `toml:"sync_base_url"`
	// DisableSync forces every transcription through the classic async
	// upload+poll flow even for short clips the sync endpoint could serve.
	DisableSync bool `toml:"disable_sync"`
	// LLM Gateway is AssemblyAI's OpenAI-compatible chat endpoint. The same
	// ASSEMBLYAI_API_KEY authenticates STT and LLM. Empty base URL uses the
	// public US gateway; set llm_gateway.eu.assemblyai.com for EU residency.
	LLMGatewayBaseURL      string `toml:"llm_gateway_base_url"`
	LLMGatewayUtilityModel string `toml:"llm_gateway_utility_model"`
	LLMGatewayAssistModel  string `toml:"llm_gateway_assist_model"`
	// LLMGatewayAgentModel is the gateway model registered for the Genkit
	// agent flows (tool-capable). It does NOT select the LLM of the AssemblyAI
	// Voice Agent realtime session: the Voice Agents WS API session config has
	// no model/LLM field (only agent_id binds a stored server-side agent) —
	// see assemblyAISessionUpdate in pkg/speechkit/voiceagent/live.
	// Defaulted while AssemblyAI is enabled so the gateway is always available
	// to agent/summary flows (DefaultAssemblyAILLMGatewayAgentModel).
	LLMGatewayAgentModel string `toml:"llm_gateway_agent_model"`
	// StreamingLLM attaches LLM Gateway to Universal-3.5 Pro realtime turns
	// (live cleanup / per-turn rewrite). Forced on while AssemblyAI is
	// enabled so Assist, summaries, and live rewrite never start without a
	// native model.
	StreamingLLM bool `toml:"streaming_llm"`
}

type AssistConfig struct {
	EnabledTools []string `toml:"enabled_tools"`

	// IncludeWindowContext controls whether the Device-Target captures the
	// foreground application name + window title and feeds them to the
	// Assist LLM as context. Window titles can be sensitive (document
	// names, chat partners, URLs), so this is an explicit opt-out. The
	// Server-Target ignores this flag — there the integrating client
	// decides whether to send the `app`/`window_title` request fields.
	// Defaults to true (see config/defaults.go).
	IncludeWindowContext bool `toml:"include_window_context"`

	// HomeAssistant configures the Home Assistant Conversation API boundary
	// used by the Voice-Companion skill catalog. Home Assistant remains the
	// sole semantic authority for recognized smart-home commands. When URL or
	// TokenEnv is missing, those commands fail closed with a terminal local
	// response; they never fall through to the general Assist model.
	HomeAssistant AssistHomeAssistantConfig `toml:"home_assistant"`
}

type AssistHomeAssistantConfig struct {
	// URL is the base URL of the Home Assistant instance, e.g.
	// "https://ha.kombify.io:8123". No trailing slash required —
	// the HA skill trims it.
	URL string `toml:"url"`

	// TokenEnv names the env var (resolved via internal/secrets) that
	// holds a Long-Lived Access Token created via HA → Profile →
	// Long-Lived Access Tokens. The value itself is NEVER stored in
	// the TOML file.
	TokenEnv string `toml:"token_env"`

	// AgentID optionally selects a Home Assistant Conversation agent. Empty
	// delegates to Home Assistant's configured default agent.
	AgentID string `toml:"agent_id"`

	// Language overrides the language sent to HA's Conversation API.
	// When empty, the user's locale is used.
	Language string `toml:"language"`
}

type AudioConfig struct {
	Backend        string `toml:"backend"`
	InputSource    string `toml:"input_source"` // microphone | system_loopback | mic_and_system
	DeviceID       string `toml:"device_id"`
	DeviceName     string `toml:"device_name"`
	OutputDeviceID string `toml:"output_device_id"`
	SampleRate     int    `toml:"sample_rate"`
	Channels       int    `toml:"channels"`
	FrameSizeMs    int    `toml:"frame_size_ms"`
	LatencyHint    string `toml:"latency_hint"`
	// KeepDeviceWarm keeps the microphone device opened between recordings so
	// a recording starts as soon as the hotkey is pressed; opening a WASAPI
	// device otherwise costs most of a second. An opened device without a
	// running stream uses no CPU and does not count as microphone use.
	KeepDeviceWarm bool `toml:"keep_device_warm"`
}

type AuditConfig struct {
	Enabled         bool   `toml:"enabled"`
	RetentionDays   int    `toml:"retention_days"`
	EventLogEnabled bool   `toml:"event_log_enabled"` // wired in P2.1 (cpv.3.1) — Windows Event Log mirror
	OTLPEndpoint    string `toml:"otlp_endpoint"`     // wired in P2.2 (cpv.3.2) — OTLP exporter
	OTLPCertFile    string `toml:"otlp_cert_file"`
	OTLPKeyFile     string `toml:"otlp_key_file"`
	OTLPCAFile      string `toml:"otlp_ca_file"`
}

type CloudflareProviderConfig struct {
	Enabled      bool   `toml:"enabled"`
	AccountID    string `toml:"account_id"`
	AccountIDEnv string `toml:"account_id_env"`
	APITokenEnv  string `toml:"api_token_env"`
	GatewayID    string `toml:"gateway_id"`
	GatewayIDEnv string `toml:"gateway_id_env"`
	UtilityModel string `toml:"utility_model"`
	AssistModel  string `toml:"assist_model"`
	AgentModel   string `toml:"agent_model"`
}

type CodexBridgeConfig struct {
	Enabled            bool                 `toml:"enabled"`
	BinaryPath         string               `toml:"binary_path"`          // empty = PATH lookup
	Mode               string               `toml:"mode"`                 // auto | app_server | exec
	Sandbox            string               `toml:"sandbox"`              // global ceiling: read-only | workspace-write
	ApprovalTimeoutSec int                  `toml:"approval_timeout_sec"` // unanswered approval card => deny
	Narration          string               `toml:"narration"`            // off | summary | verbose
	MaxConcurrentTurns int                  `toml:"max_concurrent_turns"`
	Projects           []AgentBridgeProject `toml:"projects"`
}

type Config struct {
	General        GeneralConfig        `toml:"general"`
	Audio          AudioConfig          `toml:"audio"`
	VAD            VADConfig            `toml:"vad"`
	UI             UIConfig             `toml:"ui"`
	Vocabulary     VocabularyConfig     `toml:"vocabulary"`
	Customization  CustomizationConfig  `toml:"customization"`
	Speech         SpeechDefaultsConfig `toml:"speech"`
	Assist         AssistConfig         `toml:"assist"`
	Shortcuts      ShortcutsConfig      `toml:"shortcuts"`
	ModelSelection ModelSelectionConfig `toml:"model_selection"`

	// Privacy holds the central network-scope policy ("open",
	// "local_network", "device_only") enforced at every outbound network
	// boundary of the Device-Target. See internal/config/privacy.go.
	Privacy PrivacyConfig `toml:"privacy"`

	// Output tunes how the Device-Target injects transcribed text into the
	// focused application (injection strategy, per-app paste overrides).
	// Server- and Local-Target ignore this block.
	Output OutputConfig `toml:"output"`

	// ServerConnection points the device/local-target at a remote SpeechKit
	// Server-Target. Only consulted when at least one mode in ModelSelection
	// has mode_source = "server". Disabled by default; the desktop app runs
	// fully self-contained until a user opts a mode into server-side
	// execution (typically via onboarding or settings).
	ServerConnection ServerConnectionConfig `toml:"server_connection"`

	Local           LocalConfig           `toml:"local"`
	LocalLLM        LocalLLMConfig        `toml:"local_llm"`
	VPS             VPSConfig             `toml:"vps"`
	HuggingFace     HuggingFaceConfig     `toml:"huggingface"`
	Routing         RoutingConfig         `toml:"routing"`
	Update          UpdateConfig          `toml:"update"`
	Performance     PerformanceConfig     `toml:"performance"`
	Logging         LoggingConfig         `toml:"logging"`
	Audit           AuditConfig           `toml:"audit"`
	Telemetry       TelemetryConfig       `toml:"telemetry"`
	Feedback        FeedbackConfig        `toml:"feedback"` // legacy compat; prefer Store
	Store           StoreConfig           `toml:"store"`
	Providers       ProvidersConfig       `toml:"providers"`
	ProviderOptions ProviderOptionsConfig `toml:"provider_options"`
	TTS             TTSConfig             `toml:"tts"`
	VoiceAgent      VoiceAgentConfig      `toml:"voice_agent"`

	// Server configures the standalone Linux server binary (cmd/speechkit-server).
	// All fields are optional; the desktop app (cmd/speechkit) ignores them entirely.
	Server    ServerConfig     `toml:"server"`
	Personas  []PersonaConfig  `toml:"personas"`
	Roles     []RoleConfig     `toml:"roles"`
	Sequences []SequenceConfig `toml:"sequences"`

	// HandsFree is the user-facing activation + optional voice-output layer
	// across the three strict modes. New config writes should prefer this
	// block; Wakeword remains the low-level detector compatibility block.
	HandsFree HandsFreeConfig `toml:"hands_free"`

	// Wakeword configures the always-on "Hey Quby" activation-word listener.
	// Read by cmd/speechkit (Device-Target) and any library embedder; the
	// Server-Target ignores this block in v1.
	Wakeword WakewordConfig `toml:"wakeword"`

	// AgentBridge configures the External Coding Agent Bridge (desktop-only,
	// default off, fail-closed; AI-VOICE-SPEECHKIT-TARGET.md 2026-08-10).
	// The Server-Target ignores this block entirely.
	AgentBridge AgentBridgeConfig `toml:"agent_bridge"`

	// Meeting configures meeting capture and its note write-ups. Desktop-only;
	// the Server-Target ignores this block.
	Meeting MeetingConfig `toml:"meeting"`
	Copilot CopilotConfig `toml:"copilot"`
}

type CopilotConfig struct {
	Enabled bool   `toml:"enabled"`
	Model   string `toml:"model"`
	CLIPath string `toml:"cli_path"`

	TranscriptGrantProvider  string `toml:"transcript_grant_provider"`
	TranscriptGrantVersion   int    `toml:"transcript_grant_version"`
	TranscriptGrantGrantedAt string `toml:"transcript_grant_granted_at"`
}

type CustomizationConfig struct {
	ActiveTemplateIDs []string `toml:"active_template_ids"`
}

type DeepgramAudioSettings struct {
	ListenModel       string
	SpeakModel        string
	SpeakSpeed        float64
	EOTThreshold      float64
	EagerEOTThreshold float64
	EOTTimeoutMs      int
}

type DeepgramProviderConfig struct {
	Enabled                  bool   `toml:"enabled"`
	APIKeyEnv                string `toml:"api_key_env"`
	STTModel                 string `toml:"stt_model"`
	STTLanguage              string `toml:"stt_language"`
	STTSmartFormat           bool   `toml:"stt_smart_format"`
	STTDictation             bool   `toml:"stt_dictation"`
	STTFillerWords           bool   `toml:"stt_filler_words"`
	STTNumerals              bool   `toml:"stt_numerals"`
	STTDetectLanguage        bool   `toml:"stt_detect_language"`
	STTUseVocabularyKeyterms bool   `toml:"stt_use_vocabulary_keyterms"`
	STTKeyterms              string `toml:"stt_keyterms"`
	STTEndpointingMs         int    `toml:"stt_endpointing_ms"`
	DiarizationModel         string `toml:"diarization_model"`
}

type DeepgramThinkSettings struct {
	Provider    string
	Model       string
	EndpointURL string
	APIKey      string
}

type FeedbackConfig struct {
	SaveAudio          bool   `toml:"save_audio"`
	AudioRetentionDays int    `toml:"audio_retention_days"`
	DBPath             string `toml:"db_path"`
	MaxAudioStorageMB  int    `toml:"max_audio_storage_mb"`
}

type FoundryProviderConfig struct {
	Enabled bool `toml:"enabled"`
	// ProjectEndpoint is the Foundry project endpoint from the portal, e.g.
	// https://<account>.services.ai.azure.com/api/projects/<project>.
	// A bare account endpoint (https://<account>.services.ai.azure.com) or an
	// Azure OpenAI resource endpoint (https://<resource>.openai.azure.com) is
	// accepted too — only the host is used for inference.
	ProjectEndpoint string `toml:"project_endpoint"`
	APIKeyEnv       string `toml:"api_key_env"`
	// AuthMode selects the credential the adapters send: "api_key" (the
	// resource key from APIKeyEnv) or "entra" (a short-lived token minted by
	// the signed-in Microsoft identity). Sign-in flips it to "entra"; the key
	// path stays selectable because some resources allow both.
	AuthMode string `toml:"auth_mode"`
	// EntraCredential picks how the token is obtained in "entra" mode:
	// "auto" (an Azure CLI session first, then the browser flow when a client
	// id exists), "azure_cli", "browser" or "device_code".
	EntraCredential string `toml:"entra_credential"`
	// EntraTenantID is the sign-in authority ("" = organizations, "common", or
	// a tenant id); it is also passed to `az login --tenant`.
	EntraTenantID string `toml:"entra_tenant_id"`
	// EntraClientID is a bring-your-own public-client app registration for the
	// browser and device-code flows. Empty falls back to the client id the
	// product build injects; the open-source build has none, so those two
	// flows report themselves unavailable and the Azure CLI path remains.
	EntraClientID string `toml:"entra_client_id"`
	// AzureCLIPath overrides Azure CLI detection with an explicit az.cmd path.
	AzureCLIPath string `toml:"azure_cli_path"`
	// AzureCLIProfile is "shared" (reuse the user's own az session, default)
	// or "isolated" (a SpeechKit-private AZURE_CONFIG_DIR so signing in never
	// changes the user's active az account or subscription).
	AzureCLIProfile string `toml:"azure_cli_profile"`
	// Deployment names per modality (Foundry `model` parameter). MAI speech
	// models are not deployments: an STT deployment starting with
	// "MAI-Transcribe" or a TTS deployment starting with "MAI-Voice" routes
	// the request to the resource's Azure Speech surface instead of the
	// OpenAI-compatible route (see STTEngine / TTSEngine).
	STTDeployment      string `toml:"stt_deployment"`
	UtilityDeployment  string `toml:"utility_deployment"`
	AssistDeployment   string `toml:"assist_deployment"`
	AgentDeployment    string `toml:"agent_deployment"`
	RealtimeDeployment string `toml:"realtime_deployment"`
	TTSDeployment      string `toml:"tts_deployment"`
	TTSVoice           string `toml:"tts_voice"`
	// STTStyle ("clean" or "verbatim") and STTDiarization apply to the
	// MAI-Transcribe fast-transcription path only.
	STTStyle       string `toml:"stt_style"`
	STTDiarization bool   `toml:"stt_diarization"`
	// TTSStyle is an optional mstts:express-as style for MAI voices.
	TTSStyle string `toml:"tts_style"`
	// Voice Live (Microsoft's managed realtime voice agent) settings: the
	// brain model, the Azure Speech voice and the input transcription model.
	// The Voice Live path is selected with [voice_agent] provider =
	// "foundry-voicelive"; the OpenAI-Realtime-on-Foundry path keeps using
	// RealtimeDeployment.
	VoiceLiveModel         string `toml:"voicelive_model"`
	VoiceLiveVoice         string `toml:"voicelive_voice"`
	VoiceLiveTranscription string `toml:"voicelive_transcription"`
}

type GeneralConfig struct {
	Language                       string `toml:"language"`
	Hotkey                         string `toml:"hotkey"` // Deprecated: legacy single-hotkey field kept for config file compat. Use DictateHotkey.
	DictateHotkey                  string `toml:"dictate_hotkey"`
	AssistHotkey                   string `toml:"assist_hotkey"`
	VoiceAgentHotkey               string `toml:"voice_agent_hotkey"`
	DictateHotkeyBehavior          string `toml:"dictate_hotkey_behavior"`
	AssistHotkeyBehavior           string `toml:"assist_hotkey_behavior"`
	VoiceAgentHotkeyBehavior       string `toml:"voice_agent_hotkey_behavior"`
	DictateEnabled                 bool   `toml:"dictate_enabled"`
	AssistEnabled                  bool   `toml:"assist_enabled"`
	VoiceAgentEnabled              bool   `toml:"voice_agent_enabled"`
	AutoStartOnLaunch              bool   `toml:"auto_start_on_launch"`
	StartAtLogin                   bool   `toml:"start_at_login"`
	EagerWarmup                    bool   `toml:"eager_warmup"`
	AgentHotkey                    string `toml:"agent_hotkey"`
	AgentMode                      string `toml:"agent_mode"`  // "assist" or "voice_agent" — determines what agent_hotkey triggers
	ActiveMode                     string `toml:"active_mode"` // legacy compat
	HotkeyMode                     string `toml:"hotkey_mode"` // legacy compat for single behavior setting
	AutoStopSilenceMs              int    `toml:"auto_stop_silence_ms"`
	FastModeSilenceMs              int    `toml:"fast_mode_silence_ms"`              // silence threshold for Quick Capture auto-stop
	DictateSilenceTimeoutSec       int    `toml:"dictate_silence_timeout_sec"`       // total silence in seconds before dictate auto-stops; 0 disables
	DictationIntermediateSegmentMs int    `toml:"dictation_intermediate_segment_ms"` // minimum utterance size before live dictation emits a pause-bounded segment
	DictationProcessingMode        string `toml:"dictation_processing_mode"`         // auto | final_full | segment_batch | provider_stream
	DictationLiveCommit            string `toml:"dictation_live_commit"`             // immediate | phrase | passage. passage waits ~2 sentences before field inject.
	ModelDownloadDir               string `toml:"model_download_dir"`                // Default directory for downloaded local model files
}

type GoogleProviderConfig struct {
	Enabled                   bool   `toml:"enabled"`
	APIKeyEnv                 string `toml:"api_key_env"`
	STTAPIKeyEnv              string `toml:"stt_api_key_env"`
	STTCredentialsJSONEnv     string `toml:"stt_credentials_json_env"`
	ApplicationCredentialsEnv string `toml:"application_credentials_env"`
	STTModel                  string `toml:"stt_model"`
	UtilityModel              string `toml:"utility_model"`
	AssistModel               string `toml:"assist_model"`
	AgentModel                string `toml:"agent_model"`
	// Region is the Google Cloud region the customer's API key / project is
	// pinned to. Default "europe-west3" (Frankfurt) reflects the EU-enterprise
	// compliance posture. US customers should explicitly set "us-central1".
	//
	// IMPORTANT: this field feeds the byok.key_updated audit event and the
	// settings UI. It does NOT redirect API traffic — the Gemini Live endpoint
	// is a single global WebSocket (generativelanguage.googleapis.com). Actual
	// data residency is controlled at the Google Cloud project level. Both the
	// project region AND this field must match for the audit event to be
	// accurate. See docs/compliance/byok-gemini-region-pinning.md.
	Region string `toml:"region"`
}

type GroqProviderConfig struct {
	Enabled      bool   `toml:"enabled"`
	APIKeyEnv    string `toml:"api_key_env"`
	STTModel     string `toml:"stt_model"`
	UtilityModel string `toml:"utility_model"`
	AssistModel  string `toml:"assist_model"`
	AgentModel   string `toml:"agent_model"`
}

type HandsFreeConfig struct {
	// Enabled gates hands-free activation. Default false (opt-in).
	Enabled bool `toml:"enabled"`

	// ActivationPhraseID picks one of wakeword.DefaultCatalog's curated
	// phrases. The low-level detector mirrors this value to Wakeword.PhraseID.
	ActivationPhraseID string `toml:"activation_phrase_id"`

	// TargetMode is one of "assist", "voice_agent", or
	// "dictation_ui_assisted". Dictation hands-free still requires a visible
	// text target or explicit commit surface.
	TargetMode string `toml:"target_mode"`

	// AutoEndSilenceCutoffSec ends wake-triggered sessions after this many
	// seconds of silence. Zero falls back to the framework default.
	AutoEndSilenceCutoffSec int `toml:"auto_end_silence_cutoff_sec"`

	// VoiceOutputEnabled allows Assist/Voice-Agent hands-free experiences to
	// speak. Dictation UI-assisted targets should keep this false.
	VoiceOutputEnabled bool `toml:"voice_output_enabled"`
}

type HuggingFaceConfig struct {
	Enabled      bool   `toml:"enabled"`
	Model        string `toml:"model"`
	UtilityModel string `toml:"utility_model"`
	AssistModel  string `toml:"assist_model"`
	AgentModel   string `toml:"agent_model"`
	TokenEnv     string `toml:"token_env"`
}

type InstallMode string

type InstallState struct {
	Mode      InstallMode `toml:"mode"`
	SetupDone bool        `toml:"setup_done"`
	DeviceID  string      `toml:"device_id"`
	// DismissedHints records one-time UI hints (e.g. the summary-model
	// download banner) the user explicitly dismissed, so they never reappear
	// across app restarts.
	DismissedHints []string `toml:"dismissed_hints,omitempty"`
}

type LocalConfig struct {
	Enabled   bool   `toml:"enabled"`
	Model     string `toml:"model"`
	ModelPath string `toml:"model_path"`
	Port      int    `toml:"port"`
	GPU       string `toml:"gpu"`
}

type LocalLLMConfig struct {
	Enabled      bool   `toml:"enabled"`
	BaseURL      string `toml:"base_url"`
	Model        string `toml:"model"`
	ModelPath    string `toml:"model_path"`
	Port         int    `toml:"port"`
	GPU          string `toml:"gpu"`
	UtilityModel string `toml:"utility_model"`
	AssistModel  string `toml:"assist_model"`
	AgentModel   string `toml:"agent_model"`
	// IdleStopMinutes pauses the bundled model server after this many minutes
	// without a request so its memory is released; the next request wakes it.
	// 0 keeps the server running for the whole session.
	IdleStopMinutes int `toml:"idle_stop_minutes"`
}

type LoggingConfig struct {
	MaxFileSizeMB int    `toml:"max_file_size_mb"`
	MaxFiles      int    `toml:"max_files"`
	Level         string `toml:"level"` // "debug" | "info" | "warn" | "error" | "off"
}

type MeetingConfig struct {
	Enabled bool `toml:"enabled"`
	// AutoDetect offers to take notes when a call starts, which SpeechKit
	// notices by seeing a calling application take the microphone. The check
	// reads process names and nothing else, stores nothing and sends nothing.
	AutoDetect bool `toml:"auto_detect"`
	// AutoDetectApps replaces the built-in list of applications whose
	// microphone use means a call. Empty uses the built-in list, which covers
	// the common clients and browsers.
	AutoDetectApps []string `toml:"auto_detect_apps"`
	// AutoEnhance writes a meeting up as soon as it ends, rather than waiting
	// to be asked.
	AutoEnhance                bool     `toml:"auto_enhance"`
	CompactOnStart             bool     `toml:"compact_on_start"`
	AlwaysOnTop                bool     `toml:"always_on_top"`
	GenerationProvider         string   `toml:"generation_provider"`
	GenerationModel            string   `toml:"generation_model"`
	FallbackPolicy             string   `toml:"fallback_policy"`
	BatchMinutes               int      `toml:"batch_minutes"`
	SummaryLanguage            string   `toml:"summary_language"`
	AdditionalSummaryLanguages []string `toml:"additional_summary_languages"`

	// Screenshot configures the Meeting Mode screenshot quick action and its
	// optional global keyboard shortcut. Captures are taken locally and stay
	// local (recording-session snapshot store): they never enter model prompts
	// and never leave the machine.
	//
	// ScreenshotEnabled toggles the quick action in the meeting UI.
	// ScreenshotHotkey is a combo string (e.g. "ctrl+alt+s"); empty falls back
	// to the default and "none" disables the shortcut.
	// ScreenshotHotkeyEnabled arms the global shortcut while a meeting is live.
	ScreenshotEnabled       bool   `toml:"screenshot_enabled"`
	ScreenshotHotkey        string `toml:"screenshot_hotkey"`
	ScreenshotHotkeyEnabled bool   `toml:"screenshot_hotkey_enabled"`
}

type ModeModelSelection struct {
	PrimaryProfileID  string `toml:"primary_profile_id"`
	FallbackProfileID string `toml:"fallback_profile_id"`

	// ModeSource selects whether this mode runs locally (Framework kernel
	// in-process, default) or against a remote SpeechKit Server-Target
	// configured under [server_connection]. Empty string is treated as
	// ModeSourceLocal so existing configs keep behaving as before.
	ModeSource string `toml:"mode_source"`
}

type ModelSelectionConfig struct {
	Dictate    ModeModelSelection `toml:"dictate"`
	Assist     ModeModelSelection `toml:"assist"`
	VoiceAgent ModeModelSelection `toml:"voice_agent"`
	// TTS pins the Voice-Output provider profile + optional fallback that
	// Assist and Voice-Agent use when speaking back to the user. Same shape
	// as the three product-mode selections so the catalog API stays
	// symmetric. Added in v0.37 alongside the hands-free Voice-Companion
	// flow so Thalia + Companion-Live deployments can pick a stable voice
	// (e.g. Google Studio-O DE) without editing the lower-level
	// [tts.providers.*] blocks.
	TTS ModeModelSelection `toml:"tts"`
}

type OllamaProviderConfig struct {
	Enabled      bool   `toml:"enabled"`
	BaseURL      string `toml:"base_url"`
	STTModel     string `toml:"stt_model"`
	UtilityModel string `toml:"utility_model"`
	AssistModel  string `toml:"assist_model"`
	AgentModel   string `toml:"agent_model"`
}

type OpenAIProviderConfig struct {
	Enabled       bool   `toml:"enabled"`
	APIKeyEnv     string `toml:"api_key_env"`
	STTModel      string `toml:"stt_model"`
	UtilityModel  string `toml:"utility_model"`
	AssistModel   string `toml:"assist_model"`
	AgentModel    string `toml:"agent_model"`
	TTSModel      string `toml:"tts_model"`
	TTSVoice      string `toml:"tts_voice"`
	RealtimeModel string `toml:"realtime_model"`
}

type OpenRouterProviderConfig struct {
	Enabled      bool   `toml:"enabled"`
	APIKeyEnv    string `toml:"api_key_env"`
	STTModel     string `toml:"stt_model"`
	UtilityModel string `toml:"utility_model"`
	AssistModel  string `toml:"assist_model"`
	AgentModel   string `toml:"agent_model"`
}

type OutputAppOverride struct {
	// ProcessName is the executable base name without extension, matched
	// case-insensitively, e.g. "termius".
	ProcessName string `toml:"process_name"`
	// Strategy: "" (inherit), "clipboard", or "type".
	Strategy string `toml:"strategy"`
	// PasteCombo: "" (inherit), "ctrl+v", "ctrl+shift+v", or "shift+insert".
	PasteCombo string `toml:"paste_combo"`
}

type OutputConfig struct {
	// DefaultStrategy: "auto" (per-app paste profiles, recommended),
	// "clipboard" (always plain Ctrl+V paste), or "type" (simulated
	// Unicode typing, bypasses the clipboard).
	DefaultStrategy string `toml:"default_strategy"`
	// ModifierWaitMs bounds how long injection waits for physically held
	// hotkey modifiers to be released before sending the paste chord.
	ModifierWaitMs int `toml:"modifier_wait_ms"`
	// FocusVerifyMs bounds how long injection waits for the target window
	// to reach the foreground.
	FocusVerifyMs int `toml:"focus_verify_ms"`
	// RestoreClipboard restores the previous clipboard content after a
	// clipboard-paste injection.
	RestoreClipboard bool `toml:"restore_clipboard"`
	// RestoreDelayMs is the pause between the paste chord and the clipboard
	// restore, giving the target app time to consume the paste.
	RestoreDelayMs int `toml:"restore_delay_ms"`
	// AppOverrides force a strategy and/or paste chord per process name.
	AppOverrides []OutputAppOverride `toml:"app_overrides"`
}

type OverlayFreePosition struct {
	X int `toml:"x"`
	Y int `toml:"y"`
}

type PerformanceConfig struct {
	// ProcessPriority: "above_normal" (default) raises the desktop
	// process priority class so capture/VAD/hotkeys preempt foreign
	// NORMAL-priority load; "normal" leaves the class untouched.
	ProcessPriority string `toml:"process_priority"`
	// SubprocessPriority: "below_normal" (default) spawns CPU-heavy
	// children (whisper-server, local LLM, wake-word sidecars) at
	// BELOW_NORMAL so they cannot starve live capture; "normal" spawns
	// them unadjusted.
	SubprocessPriority string `toml:"subprocess_priority"`
	// CaptureThreadPriority: "realtime" (default) runs the WASAPI
	// capture thread at TIME_CRITICAL; "highest" keeps malgo's default
	// THREAD_PRIORITY_HIGHEST.
	CaptureThreadPriority string `toml:"capture_thread_priority"`
}

type PersonaConfig struct {
	ID              string            `toml:"id"`
	DisplayName     string            `toml:"display_name"`
	Description     string            `toml:"description"`
	Voice           string            `toml:"voice"`
	Locale          string            `toml:"locale"`
	DefaultRole     string            `toml:"default_role"`
	DefaultSequence string            `toml:"default_sequence"`
	Tags            []string          `toml:"tags"`
	Metadata        map[string]string `toml:"metadata"`
}

type PolicyValues struct {
	UpdateEnabled             *bool
	UpdateManifestURL         string
	TelemetryUpdateCheck      *bool
	ProvidersEnforceLocalOnly *bool
	VoiceAgentAllowCloud      *bool
	AuditRetentionDays        *int
	AuditEventLogEnabled      *bool
	AuditOTLPEndpoint         string

	// Origin describes which registry hive first contributed a value.
	// One of "hklm-policies" | "hklm-defaults" | "hkcu" | "none" | "non-windows".
	Origin string
	// KeysFound counts all registry values that contributed to this overlay
	// (across all hives). Used in the policy.applied audit event.
	KeysFound int
}

type PrivacyConfig struct {
	// NetworkScope is "open" (default), "local_network", or "device_only".
	// Missing/empty means open (backwards compatible); unknown values make
	// config loading fail so a typo can never silently widen or narrow
	// network access.
	NetworkScope string `toml:"network_scope"`

	// AllowSetupTraffic opts setup/maintenance traffic (model downloads,
	// update checks) back in while a restricted scope is active. Ignored in
	// the open scope, where such traffic follows its own existing toggles.
	// Default false: restricted scopes are fully quiet unless the user
	// explicitly consents.
	AllowSetupTraffic bool `toml:"allow_setup_traffic"`

	// RetentionScope is "retain" (default) or "ephemeral". It is orthogonal to
	// NetworkScope: one says where the process may reach, the other what
	// survives the work. Missing/empty means retain (backwards compatible);
	// unknown values make config loading fail rather than being guessed.
	RetentionScope string `toml:"retention_scope"`
}

type ProviderCredentialStatus struct {
	Provider        string
	Target          string
	Label           string
	EnvName         string
	Available       bool
	HasStoredSecret bool
	Source          string
}

type ProviderModalityOptions struct {
	STT        ProviderOptionOverrides `toml:"stt"`
	TTS        ProviderOptionOverrides `toml:"tts"`
	VoiceAgent ProviderOptionOverrides `toml:"voice_agent"`
}

type ProviderOptionOverrides struct {
	Language           string   `toml:"language,omitempty"`
	DetectLanguage     *bool    `toml:"detect_language,omitempty"`
	Punctuation        *bool    `toml:"punctuation,omitempty"`
	SmartFormat        *bool    `toml:"smart_format,omitempty"`
	Dictation          *bool    `toml:"dictation,omitempty"`
	FillerWords        *bool    `toml:"filler_words,omitempty"`
	Numerals           *bool    `toml:"numerals,omitempty"`
	VocabularyBias     *bool    `toml:"vocabulary_bias,omitempty"`
	Keyterms           []string `toml:"keyterms,omitempty"`
	PromptHint         string   `toml:"prompt_hint,omitempty"`
	SpeakerDiarization *bool    `toml:"speaker_diarization,omitempty"`
	Timestamps         *bool    `toml:"timestamps,omitempty"`
	EndpointingMs      *int     `toml:"endpointing_ms,omitempty"`
	TurnDetection      *bool    `toml:"turn_detection,omitempty"`
	Voice              string   `toml:"voice,omitempty"`
	Speed              *float64 `toml:"speed,omitempty"`
	AudioFormat        string   `toml:"audio_format,omitempty"`
}

type ProviderOptionsConfig struct {
	Deepgram    ProviderModalityOptions `toml:"deepgram"`
	OpenAI      ProviderModalityOptions `toml:"openai"`
	Groq        ProviderModalityOptions `toml:"groq"`
	Google      ProviderModalityOptions `toml:"google"`
	AssemblyAI  ProviderModalityOptions `toml:"assemblyai"`
	OpenRouter  ProviderModalityOptions `toml:"openrouter"`
	HuggingFace ProviderModalityOptions `toml:"huggingface"`
	Local       ProviderModalityOptions `toml:"local"`
	Ollama      ProviderModalityOptions `toml:"ollama"`
}

type ProviderRuntime struct {
	Provider           string
	DisplayName        string
	ProviderKind       framework.ProviderKind
	IntegrationKind    string
	CredentialTarget   string
	CredentialRequired bool
	SetupURL           string
	SupportedModes     []framework.Mode
	UserConfigurable   bool
}

type ProvidersConfig struct {
	OpenAI     OpenAIProviderConfig     `toml:"openai"`
	Groq       GroqProviderConfig       `toml:"groq"`
	Google     GoogleProviderConfig     `toml:"google"`
	Deepgram   DeepgramProviderConfig   `toml:"deepgram"`
	AssemblyAI AssemblyAIProviderConfig `toml:"assemblyai"`
	Ollama     OllamaProviderConfig     `toml:"ollama"`
	OpenRouter OpenRouterProviderConfig `toml:"openrouter"`
	Cloudflare CloudflareProviderConfig `toml:"cloudflare"`
	Foundry    FoundryProviderConfig    `toml:"foundry"`
}

type RoleConfig struct {
	ID                          string   `toml:"id"`
	DisplayName                 string   `toml:"display_name"`
	SystemPrompt                string   `toml:"system_prompt"`
	RefinementPrompt            string   `toml:"refinement_prompt"`
	Locale                      string   `toml:"locale"`
	VocabularyHint              string   `toml:"vocabulary_hint"`
	ToolAllowlist               []string `toml:"tool_allowlist"`
	Temperature                 float64  `toml:"temperature"`
	ThinkingEnabled             bool     `toml:"thinking_enabled"`
	ThinkingLevel               string   `toml:"thinking_level"`
	IncludeThoughts             bool     `toml:"include_thoughts"`
	ThinkingBudget              int      `toml:"thinking_budget"`
	AutomaticActivityDetection  bool     `toml:"automatic_activity_detection"`
	VADStartSensitivity         string   `toml:"vad_start_sensitivity"`
	VADEndSensitivity           string   `toml:"vad_end_sensitivity"`
	VADPrefixPaddingMs          int      `toml:"vad_prefix_padding_ms"`
	VADSilenceDurationMs        int      `toml:"vad_silence_duration_ms"`
	ActivityHandling            string   `toml:"activity_handling"`
	TurnCoverage                string   `toml:"turn_coverage"`
	ContextCompressionEnabled   bool     `toml:"context_compression_enabled"`
	ContextCompressionTriggerTk int64    `toml:"context_compression_trigger_tokens"`
	ContextCompressionTargetTk  int64    `toml:"context_compression_target_tokens"`
	EnableAffectiveDialog       bool     `toml:"enable_affective_dialog"`
}

type RoutingConfig struct {
	Strategy                string  `toml:"strategy"`
	PreferLocalUnderSeconds float64 `toml:"prefer_local_under_seconds"`
	ParallelCloud           bool    `toml:"parallel_cloud"`
	ReplaceOnBetter         bool    `toml:"replace_on_better"`
}

type SequenceConfig struct {
	ID          string               `toml:"id"`
	DisplayName string               `toml:"display_name"`
	Description string               `toml:"description"`
	Completion  string               `toml:"completion"` // "all_steps" | "explicit_close" | "max_turns"
	MaxTurns    int                  `toml:"max_turns"`
	Steps       []SequenceStepConfig `toml:"steps"`
}

type SequenceStepConfig struct {
	ID           string   `toml:"id"`
	Instruction  string   `toml:"instruction"`
	ExitCriteria string   `toml:"exit_criteria"`
	RequireTools []string `toml:"require_tools"`
	MaxTurns     int      `toml:"max_turns"`
}

type ServerAdminAuthSettings struct {
	Enabled       *bool  `json:"enabled,omitempty"`
	Username      string `json:"username,omitempty"`
	PasswordHash  string `json:"password_hash,omitempty"`
	PasswordValue string `json:"password,omitempty"`
}

type ServerAssistSettings struct {
	EnabledTools []string `json:"enabled_tools,omitempty"`
}

type ServerAssistantUIConfig struct {
	Variant           string `toml:"variant"`
	Mark              string `toml:"mark"`
	TranscriptDefault bool   `toml:"transcript_default"`
}

type ServerAuthSettings struct {
	Mode           string `json:"mode,omitempty"`
	BearerTokenEnv string `json:"bearer_token_env,omitempty"`
	GenerateToken  *bool  `json:"generate_token,omitempty"`
	TokenValue     string `json:"token_value,omitempty"`
}

type ServerConfig struct {
	ListenAddr        string   `toml:"listen_addr"`          // e.g. ":8080"
	PublicURL         string   `toml:"public_url"`           // external API base URL, e.g. https://speechkit.example.com/api
	Modes             []string `toml:"modes"`                // subset of ["dictation","assist","voiceagent"]; empty = all
	AuthMode          string   `toml:"auth_mode"`            // "none" | "bearer" | "edge_hmac" | "bearer_or_edge" | "oidc" | "bearer_or_oidc"
	BearerTokenEnv    string   `toml:"bearer_token_env"`     // env var name holding the bearer token
	BearerRole        string   `toml:"bearer_role"`          // optional role for static bearer callers, e.g. "admin"
	AdminAuthEnabled  bool     `toml:"admin_auth_enabled"`   // enables setup/admin UI username/password login
	AdminUsername     string   `toml:"admin_username"`       // setup/admin UI username; not used by API clients
	AdminPasswordHash string   `toml:"admin_password_hash"`  // bcrypt hash for setup/admin UI login
	EdgeAuthSecretEnv string   `toml:"edge_auth_secret_env"` // env var name holding the HMAC secret
	// SmokeTokenEnv names an optional env var that holds a public-friendly
	// demo bearer token. When set, the smoke UI on `/` embeds the token in
	// the rendered HTML so visitors can run all three modes without
	// configuring credentials. The smoke identity is tagged Source="smoke"
	// (Plan="demo") so handlers and rate-limiters can distinguish demo
	// traffic. Leave empty to disable smoke-from-page entirely; operators
	// must then paste their bearer token in the UI manually.
	SmokeTokenEnv      string   `toml:"smoke_token_env"`
	PublicBaseURL      string   `toml:"public_base_url"`     // public server URL used for returned client URLs
	TrustedProxyCIDRs  []string `toml:"trusted_proxy_cidrs"` // proxies allowed to supply X-Forwarded-* headers
	CORSAllowedOrigins []string `toml:"cors_allowed_origins"`
	RateLimitRPS       float64  `toml:"rate_limit_rps"`
	RateLimitBurst     int      `toml:"rate_limit_burst"`
	// RateLimitEndpointCosts assigns per-endpoint token costs so
	// expensive handlers (LLM, transcription, voice-agent session
	// create) drain the bucket faster than cheap ones. Keys are
	// either "METHOD PATH" (e.g. "POST /v1/dictation/transcribe")
	// or bare PATH. Missing entries default to 1.0. Audit S-4.
	RateLimitEndpointCosts map[string]float64 `toml:"rate_limit_endpoint_costs"`
	// DemoDailyQuota caps how many requests a Plan="demo" identity
	// (the smoke-token surface) may make per UTC day, keyed by
	// UserID + client IP. Zero disables the quota. Audit S-5.
	DemoDailyQuota         int `toml:"demo_daily_quota"`
	MaxUploadMB            int `toml:"max_upload_mb"`
	ReadHeaderTimeoutSec   int `toml:"read_header_timeout_sec"`
	ReadTimeoutSec         int `toml:"read_timeout_sec"`
	IdleTimeoutSec         int `toml:"idle_timeout_sec"`
	MaxHeaderBytes         int `toml:"max_header_bytes"`
	MaxDecodedAudioSeconds int `toml:"max_decoded_audio_seconds"`
	MaxVoiceAgentSessions  int `toml:"max_voiceagent_sessions"` // global cap
	MaxSessionsPerUser     int `toml:"max_sessions_per_user"`
	TicketTTLSec           int `toml:"ticket_ttl_sec"` // Voice Agent WS ticket TTL
	// VoiceAgentIdleTimeoutSec terminates a Voice Agent WebSocket session
	// after N seconds without any client- or provider-side activity.
	// Defaults to 900 (15 min). Set to 0 to disable the server-side idle
	// timeout (kernel-level idle handling stays in effect either way).
	VoiceAgentIdleTimeoutSec int `toml:"voiceagent_idle_timeout_sec"`
	// VoiceAgentMaxSessionSec hard-caps a single Voice Agent WebSocket
	// session. Zero disables the hard cap for normal self-hosted installs;
	// public beta deployments should set a finite budget because realtime
	// sessions are cost-correlated with wall-clock duration.
	VoiceAgentMaxSessionSec int `toml:"voiceagent_max_session_sec"`
	// WSReadLimitBytes caps the per-frame size the Voice Agent WebSocket
	// will read from a client. Zero or negative defaults to 64 KiB,
	// which leaves ample headroom over real PCM chunk sizes (well under
	// 4 KB) without giving a single frame a 1 MiB memory amplification
	// vector. Bumped only for non-standard payloads.
	WSReadLimitBytes int64 `toml:"ws_read_limit_bytes"`
	// DictationStream configures the streaming Dictation WebSocket
	// (POST /v1/dictation/stream/sessions → ticket → WS with live
	// partial transcripts). Active only while the dictation mode is on.
	DictationStream ServerDictationStreamConfig `toml:"dictation_stream"`
	LiveKit         ServerLiveKitConfig         `toml:"livekit"`
	WhisperBinary   string                      `toml:"whisper_binary"` // absolute path inside container
	WhisperPort     int                         `toml:"whisper_port"`   // loopback port for whisper.cpp server
	ModelDir        string                      `toml:"model_dir"`      // persistent volume, e.g. /var/lib/speechkit/models
	LogFormat       string                      `toml:"log_format"`     // "json" | "text"
	LogLevel        string                      `toml:"log_level"`      // "debug" | "info" | "warn" | "error"
	Features        ServerFeaturesConfig        `toml:"features"`

	// TrainingData configures the server-side wake-word activation
	// collection endpoint. Default OFF so an operator must explicitly
	// accept training-data uploads from clients. See
	// docs/wakeword-training-data.md.
	TrainingData ServerTrainingDataConfig `toml:"training_data"`

	// AssistantUI sets the default appearance of the /assistant web page
	// (the server-hosted Voice Assistant surface). Per-browser overrides
	// stay client-side; this block is the operator default.
	AssistantUI ServerAssistantUIConfig `toml:"assistant_ui"`

	// Security configures the HTTP security-header middleware (CSP,
	// X-Frame-Options, Referrer-Policy, optional HSTS). Headers are on by
	// default; the zero value yields a strict baseline.
	Security ServerSecurityConfig `toml:"security"`

	// Debug gates runtime debugging surfaces (pprof). Off by default.
	Debug ServerDebugConfig `toml:"debug"`

	// Discovery announces this server on the local network via mDNS/DNS-SD
	// (`_speechkit._tcp`) so LAN devices — the Kombify Box, the desktop app,
	// Android — can find a homelab instance without typing an address.
	// Default OFF (fail-closed): a public deployment has no business
	// multicasting its presence; a homelab operator opts in explicitly.
	Discovery ServerDiscoveryConfig `toml:"discovery"`

	// OIDC configures JWT validation against an external identity provider,
	// used when auth_mode is "oidc" or "bearer_or_oidc".
	OIDC ServerOIDCConfig `toml:"oidc"`

	// Wyoming exposes SpeechKit STT + TTS as Wyoming voice services so an
	// ESPHome voice satellite — mediated by Home Assistant's Assist pipeline —
	// can use this server as its speech backend. Default OFF: enabling it opens
	// a separate TCP listener. See docs/server/wyoming.md.
	Wyoming ServerWyomingConfig `toml:"wyoming"`

	// DeviceAgent exposes the credential-minimal, local-only HTTP bridge used
	// by paired microphone/speaker satellites. It is disabled by default and
	// has its own per-device credentials; the general server bearer, OIDC,
	// edge-HMAC, Gateway, and federation identities do not authorize it.
	DeviceAgent ServerDeviceAgentConfig `toml:"device_agent"`

	// VoiceAgent carries Server-Target-only Voice Agent wiring such as the
	// generic tool bridge ([server.voiceagent.tool_bridge]). Session behavior
	// (provider, prompts, VAD) stays in the shared [voice_agent] section.
	VoiceAgent ServerVoiceAgentConfig `toml:"voiceagent"`
}

type ServerConnectionConfig struct {
	// Enabled is a compatibility mirror for clients that still display a
	// top-level server toggle. Runtime routing is determined by each mode's
	// mode_source; do not use Enabled as a second execution gate.
	Enabled bool `toml:"enabled"`

	// URL is the base URL of the speechkit-server, e.g.
	// "https://speechkit.example.com" or "http://localhost:8080".
	URL string `toml:"url"`

	// BearerTokenEnv names the env var that holds the bearer token sent in
	// the Authorization header. Defaults to SPEECHKIT_SERVER_TOKEN. The
	// value is never read from the TOML file itself — only the env var name
	// is configured here.
	BearerTokenEnv string `toml:"bearer_token_env"`

	// AuthMode selects how the resolved token is attached to outbound
	// requests. "bearer" sends Authorization: Bearer <token>. "api_key"
	// sends X-Api-Key: <token> for servers that use header-based API keys.
	// "edge_beta" sends only anonymous per-install beta headers to a managed
	// edge broker; it never reads or sends a shared server/provider token.
	// Empty/missing defaults to "bearer".
	AuthMode string `toml:"auth_mode"`

	// BetaInstallIDEnv and BetaInstallSecretEnv name the local secret slots
	// used only when auth_mode = "edge_beta". The values are generated on
	// first use and stored via the host secret store (DPAPI on Windows). They
	// are anonymous per-install identifiers, not provider/server credentials.
	BetaInstallIDEnv     string `toml:"beta_install_id_env"`
	BetaInstallSecretEnv string `toml:"beta_install_secret_env"`

	// FallbackToLocal makes the device app fall back to the in-process
	// Framework kernel if a server call fails or the server is unreachable.
	// Useful for laptop deployments that may be offline; should be false
	// for kiosks that must never silently downgrade to local processing.
	FallbackToLocal bool `toml:"fallback_to_local"`

	// RequestTimeoutSec caps non-streaming HTTP calls (Dictation, Assist).
	// 0 means no explicit timeout (the underlying http.Client default
	// applies). Voice Agent WebSocket sessions are not affected.
	RequestTimeoutSec int `toml:"request_timeout_sec"`

	// ActiveTargetID selects the registered server target copied into the
	// compatibility fields above. Empty means the top-level URL/env/auth fields
	// are an ad-hoc single target.
	ActiveTargetID string `toml:"active_target_id"`

	// Targets is the optional local registry of SpeechKit server endpoints the
	// device can switch between. These are user/operator configured; product
	// builds must not inject private gateway/origin entries here.
	Targets []ServerConnectionTargetConfig `toml:"targets"`
}

type ServerConnectionTargetConfig struct {
	ID                   string `toml:"id"`
	Label                string `toml:"label"`
	URL                  string `toml:"url"`
	BearerTokenEnv       string `toml:"bearer_token_env"`
	AuthMode             string `toml:"auth_mode"`
	BetaInstallIDEnv     string `toml:"beta_install_id_env"`
	BetaInstallSecretEnv string `toml:"beta_install_secret_env"`
	FallbackToLocal      bool   `toml:"fallback_to_local"`
	RequestTimeoutSec    int    `toml:"request_timeout_sec"`
}

type ServerCredentialSettings struct {
	OpenAI      ServerProviderCredentialSettings `json:"openai,omitempty"`
	Groq        ServerProviderCredentialSettings `json:"groq,omitempty"`
	Google      ServerProviderCredentialSettings `json:"google,omitempty"`
	Deepgram    ServerProviderCredentialSettings `json:"deepgram,omitempty"`
	AssemblyAI  ServerProviderCredentialSettings `json:"assemblyai,omitempty"`
	HuggingFace ServerProviderCredentialSettings `json:"huggingface,omitempty"`
	OpenRouter  ServerProviderCredentialSettings `json:"openrouter,omitempty"`
}

type ServerDebugConfig struct {
	PprofEnabled bool `toml:"pprof_enabled"`
	PprofPublic  bool `toml:"pprof_public"`
}

type ServerDeviceAgentBoxMediaConfig struct {
	Enabled bool `toml:"enabled"`

	ListenAddr      string `toml:"listen_addr"`
	CertificateFile string `toml:"certificate_file"`
	PrivateKeyFile  string `toml:"private_key_file"`
	PinnedCAFile    string `toml:"pinned_ca_file"`
	PinnedCASHA256  string `toml:"pinned_ca_sha256"`
	TokenEnv        string `toml:"token_env"`

	DeviceID   string `toml:"device_id"`
	PairingID  string `toml:"pairing_id"`
	RoomID     string `toml:"room_id"`
	Transcript string `toml:"transcript"`
	CommandID  string `toml:"command_id"`
	Locale     string `toml:"locale"`
}

type ServerDeviceAgentClaimSettings struct {
	MaxRequestAgeSec  int
	FutureSkewSec     int
	ClaimRetentionSec int
	MaxClaims         int
}

type ServerDeviceAgentConfig struct {
	Enabled          bool   `toml:"enabled"`
	ServerInstanceID string `toml:"server_instance_id"`
	ClaimStorePath   string `toml:"claim_store_path"`

	// The replay ledger rejects stale or future-dated action requests and
	// remembers accepted request claims beyond the full acceptance window.
	// Zero selects the conservative exported defaults above.
	MaxRequestAgeSec  int `toml:"max_request_age_sec"`
	FutureSkewSec     int `toml:"future_skew_sec"`
	ClaimRetentionSec int `toml:"claim_retention_sec"`
	MaxClaims         int `toml:"max_claims"`

	Devices  []ServerDeviceAgentDeviceConfig `toml:"devices"`
	BoxMedia ServerDeviceAgentBoxMediaConfig `toml:"box_media"`
}

type ServerDeviceAgentDeviceConfig struct {
	DeviceID           string   `toml:"device_id"`
	PairingID          string   `toml:"pairing_id"`
	RoomID             string   `toml:"room_id"`
	TokenEnv           string   `toml:"token_env"`
	AllowedClientCIDRs []string `toml:"allowed_client_cidrs"`

	// LocalRules are a static, server-owned G0 safety allow-list. They are
	// deliberately not represented as Workbench/cloud standing grants and
	// cannot authorize arbitrary text or safety-critical domains.
	LocalRules []ServerDeviceAgentLocalRuleConfig `toml:"local_rules"`
}

type ServerDeviceAgentLocalRuleConfig struct {
	RuleID      string `toml:"rule_id"`
	TriggerText string `toml:"trigger_text"`
	Locale      string `toml:"locale"`
	Action      string `toml:"action"`    // turn_on | turn_off
	EntityID    string `toml:"entity_id"` // light.* only in the G0 contract
	NotBefore   string `toml:"not_before"`
	ExpiresAt   string `toml:"expires_at"`
}

type ServerDictationSettings struct {
	Dictionary *string `json:"dictionary,omitempty"`
}

type ServerDictationStreamConfig struct {
	// Enabled gates the surface. Default true; the endpoint only exists
	// while the dictation mode itself is enabled.
	Enabled bool `toml:"enabled"`
	// MaxGlobalSessions caps concurrent streaming sessions across all
	// callers. Default 100.
	MaxGlobalSessions int `toml:"max_global_sessions"`
	// MaxPerIdentitySessions caps concurrent streaming sessions per caller.
	// Default 3.
	MaxPerIdentitySessions int `toml:"max_per_identity_sessions"`
	// IdleTimeoutSec terminates a session without any client- or
	// provider-side activity. Default 300 (5 min — deliberately shorter than
	// the Voice Agent's 15 min; a keyboard reconnects cheaply). Negative
	// disables.
	IdleTimeoutSec int `toml:"idle_timeout_sec"`
	// MaxSessionSec hard-caps a single streaming session's wall-clock
	// lifetime. Zero disables (self-hosted default); hosted deployments
	// should set a finite budget.
	MaxSessionSec int `toml:"max_session_sec"`
	// MaxStreamAudioSeconds caps the cumulative uploaded audio duration per
	// session — the streaming analog of max_decoded_audio_seconds. Zero
	// disables.
	MaxStreamAudioSeconds int `toml:"max_stream_audio_seconds"`
	// Emulation is reserved for a future chunked-batch fallback mode when no
	// streaming-capable provider is configured. v1 supports only "off":
	// clients receive capabilities.streaming=false and fall back to
	// POST /v1/dictation/transcribe themselves.
	Emulation string `toml:"emulation"`
}

type ServerDiscoveryConfig struct {
	Enabled bool `toml:"enabled"`
	// InstanceName is the human-readable service instance ("<name>._speechkit._tcp").
	// Empty defaults to the host name.
	InstanceName string `toml:"instance_name"`
	// AdvertiseURL is the base URL clients should use, e.g.
	// "http://192.168.1.20:8080" or "https://speechkit.fritz.box". Empty
	// falls back to public_base_url, then to http://<hostname>:<listen-port>.
	AdvertiseURL string `toml:"advertise_url"`
}

type ServerFeaturesConfig struct {
	Catalog      bool `toml:"catalog"`
	StorageReads bool `toml:"storage_reads"`
	Vocabulary   bool `toml:"vocabulary"`
	TTSDirect    bool `toml:"tts_direct"`
	// WakewordModels serves the public wake-word model catalog
	// (GET /v1/wakeword/models*): openWakeWord ONNX metadata for host
	// consumers and microWakeWord v2 manifests for ESPHome / on-device
	// consumers. Default ON — the payloads are already-public model metadata
	// and redirects to already-public files. Set false to hide the surface.
	WakewordModels bool `toml:"wakeword_models"`
}

type ServerLLMSettings struct {
	Enabled      *bool  `json:"enabled,omitempty"`
	BaseURL      string `json:"base_url,omitempty"`
	UtilityModel string `json:"utility_model,omitempty"`
	AssistModel  string `json:"assist_model,omitempty"`
	AgentModel   string `json:"agent_model,omitempty"`
	HFRepo       string `json:"hf_repo,omitempty"`
}

type ServerLiveKitConfig struct {
	Enabled      bool   `toml:"enabled"`
	URL          string `toml:"url"`            // e.g. wss://livekit.example.com
	APIKeyEnv    string `toml:"api_key_env"`    // env var name holding the LiveKit API key
	APISecretEnv string `toml:"api_secret_env"` // env var name holding the LiveKit API secret
	TokenTTLSec  int    `toml:"token_ttl_sec"`  // join-token TTL
	RoomPrefix   string `toml:"room_prefix"`    // room name prefix for SpeechKit-managed rooms
}

type ServerModeProviderSettings struct {
	Dictation  ServerModeSetting `json:"dictation,omitempty"`
	Assist     ServerModeSetting `json:"assist,omitempty"`
	VoiceAgent ServerModeSetting `json:"voice_agent,omitempty"`
}

type ServerModeSetting struct {
	Enabled      *bool  `json:"enabled,omitempty"`
	ProviderKind string `json:"provider_kind,omitempty"`
	ProfileID    string `json:"profile_id,omitempty"`
	Model        string `json:"model,omitempty"`
}

type ServerModelSettings struct {
	Version            int                        `json:"version,omitempty"`
	OnboardingComplete bool                       `json:"onboarding_complete,omitempty"`
	OnboardingVersion  string                     `json:"onboarding_version,omitempty"`
	ServerAuth         ServerAuthSettings         `json:"server_auth,omitempty"`
	AdminAuth          ServerAdminAuthSettings    `json:"admin_auth,omitempty"`
	Modes              ServerModeProviderSettings `json:"modes,omitempty"`
	Credentials        ServerCredentialSettings   `json:"credentials,omitempty"`
	Dictation          ServerDictationSettings    `json:"dictation,omitempty"`
	Assist             ServerAssistSettings       `json:"assist,omitempty"`
	STT                ServerSTTSettings          `json:"stt,omitempty"`
	LLM                ServerLLMSettings          `json:"llm,omitempty"`
	VoiceAgent         ServerVoiceAgentSettings   `json:"voice_agent,omitempty"`
	TTS                ServerOptionalTTSSettings  `json:"tts,omitempty"`
}

type ServerOIDCConfig struct {
	JWKSURL          string `toml:"jwks_url"`
	Issuer           string `toml:"issuer"`
	Audience         string `toml:"audience"`
	ClockSkewSeconds int    `toml:"clock_skew_seconds"` // tolerated exp/nbf skew; default 60
	OrgClaim         string `toml:"org_claim"`          // claim -> OrgID; default "org_id"
	RoleClaim        string `toml:"role_claim"`         // claim -> Role; default "role"
}

type ServerOptionalTTSSettings struct {
	Enabled *bool `json:"enabled,omitempty"`
}

type ServerProviderCredentialSettings struct {
	Enabled *bool  `json:"enabled,omitempty"`
	Env     string `json:"env,omitempty"`
	Value   string `json:"value,omitempty"`
}

type ServerSTTSettings struct {
	Enabled *bool  `json:"enabled,omitempty"`
	URL     string `json:"url,omitempty"`
	Model   string `json:"model,omitempty"`
}

type ServerSecurityConfig struct {
	Disabled              bool   `toml:"disabled"`                // turn the middleware off entirely (not recommended)
	ContentSecurityPolicy string `toml:"content_security_policy"` // override the default strict API CSP
	FrameOptions          string `toml:"frame_options"`           // override X-Frame-Options (default "DENY")
	ReferrerPolicy        string `toml:"referrer_policy"`         // override Referrer-Policy (default "no-referrer")
	HSTS                  bool   `toml:"hsts"`                    // emit Strict-Transport-Security (only meaningful behind TLS)
	HSTSMaxAgeSeconds     int    `toml:"hsts_max_age_seconds"`    // HSTS max-age; default 63072000 (2y) when HSTS is on
}

type ServerToolBridgeConfig struct {
	// Enabled turns the bridge on. Default false. Deployment env can flip
	// this by setting SPEECHKIT_TOOLBRIDGE_URL (see server_deployment_env.go).
	Enabled bool `toml:"enabled"`
	// ManifestURL is the GET endpoint returning the session tool manifest.
	ManifestURL string `toml:"manifest_url"`
	// InvokeURL is the POST endpoint executing one tool call.
	InvokeURL string `toml:"invoke_url"`
	// TimeoutMs bounds one invoke round-trip. Default 10000.
	TimeoutMs int `toml:"timeout_ms"`
	// MaxCallsPerSession hard-caps bridge tool calls per voice session.
	// Default 20.
	MaxCallsPerSession int `toml:"max_calls_per_session"`
	// CredentialHeader names the request header on POST /v1/voiceagent/sessions
	// that carries the per-session bridge credential. The header is accepted
	// only when edge-HMAC authentication succeeded on the same request.
	// Default "X-Edge-Obo-Subject-Token".
	CredentialHeader string `toml:"credential_header"`
}

type ServerTrainingDataConfig struct {
	// AcceptUploads gates POST /v1/wakeword/activations. When false
	// the endpoint returns 503 with a clear "feature disabled"
	// payload so device-side uploaders back off gracefully. Default
	// false.
	AcceptUploads bool `toml:"accept_uploads"`

	// AudioDir is the filesystem root where uploaded audio files
	// are stored. Empty resolves to <data>/wakeword-activations/ in
	// the container. Files land under <audio_dir>/<org>/<user>/<id>.wav.
	AudioDir string `toml:"audio_dir"`

	// PerUserQuotaBytes caps how many bytes one user can have on
	// disk before the server rejects further uploads with 413. Zero
	// = unlimited. Default 1 GiB (1073741824).
	PerUserQuotaBytes int64 `toml:"per_user_quota_bytes"`

	// RetentionDays auto-deletes uploaded clips older than this
	// many days via the maintenance worker. Zero = no auto-delete.
	// Default 180.
	RetentionDays int `toml:"retention_days"`
}

type ServerVoiceAgentConfig struct {
	ToolBridge ServerToolBridgeConfig `toml:"tool_bridge"`
}

type ServerVoiceAgentSettings struct {
	Provider        string  `json:"provider,omitempty"`
	AgentProfileID  string  `json:"agent_profile_id,omitempty"`
	AgentSequenceID string  `json:"agent_sequence_id,omitempty"`
	PromptTemplate  *string `json:"prompt_template,omitempty"`
}

type ServerWyomingConfig struct {
	Enabled     bool     `toml:"enabled"`      // opt-in; opens a TCP listener
	Addr        string   `toml:"addr"`         // combined asr+tts listener; empty → ":10300"
	ServiceName string   `toml:"service_name"` // Info program/attribution name; empty → "speechkit"
	Languages   []string `toml:"languages"`    // advertised languages; empty → ["en"]
	Voice       string   `toml:"voice"`        // advertised + default TTS voice
	// AllowedClientCIDRs optionally restricts which peers may connect (defense
	// in depth — e.g. ["192.168.1.10/32"] for the HA host). Empty = allow any.
	AllowedClientCIDRs []string `toml:"allowed_client_cidrs"`
}

type ShortcutLocaleConfig struct {
	LeadingFillers []string `toml:"leading_fillers"`
	CopyLast       []string `toml:"copy_last"`
	InsertLast     []string `toml:"insert_last"`
	Summarize      []string `toml:"summarize"`
	QuickNote      []string `toml:"quick_note"`
}

type ShortcutsConfig struct {
	Locale map[string]ShortcutLocaleConfig `toml:"locale"`
}

type SpeechDefaultsConfig struct {
	Language string `toml:"language"`
	// MainLanguage is the user's own locale the overlay language switch
	// rotates back to after English. Distinct from Language, which is the
	// current pin (including the multilanguage sentinel).
	MainLanguage   string  `toml:"main_language"`
	DetectLanguage bool    `toml:"detect_language"`
	Punctuation    bool    `toml:"punctuation"`
	SmartFormat    bool    `toml:"smart_format"`
	VocabularyBias bool    `toml:"vocabulary_bias"`
	Timestamps     bool    `toml:"timestamps"`
	EndpointingMs  int     `toml:"endpointing_ms"`
	TurnDetection  bool    `toml:"turn_detection"`
	Voice          string  `toml:"voice"`
	Speed          float64 `toml:"speed"`
	AudioFormat    string  `toml:"audio_format"`
	// LowConfidenceThreshold flags recognized words whose provider-reported
	// acoustic confidence is below this value (0..1) so the host can surface
	// likely-misrecognized terms. 0 disables the check. Only Deepgram and
	// AssemblyAI expose per-word confidence today.
	LowConfidenceThreshold float64 `toml:"low_confidence_threshold"`
}

type StoreConfig struct {
	Backend            string `toml:"backend"` // "sqlite" | "postgres" | registered name
	SQLitePath         string `toml:"sqlite_path"`
	PostgresDSN        string `toml:"postgres_dsn"`
	SaveAudio          bool   `toml:"save_audio"`
	AudioRetentionDays int    `toml:"audio_retention_days"`
	MaxAudioStorageMB  int    `toml:"max_audio_storage_mb"`
	// MeetingRetentionDays discards finished meetings older than this many
	// days. Zero, the default, keeps them: a meeting is work someone did, not
	// a by-product, so nothing is thrown away unless it is asked for. Pinned
	// meetings are kept either way.
	MeetingRetentionDays int `toml:"meeting_retention_days"`
}

type TTSConfig struct {
	Enabled     bool           `toml:"enabled"`
	Strategy    string         `toml:"strategy"` // "cloud-first", "local-first", "cloud-only", "local-only"
	Voice       string         `toml:"voice"`    // Global default voice override
	Speed       float64        `toml:"speed"`    // Global speed 0.25-4.0, default 1.0
	Format      string         `toml:"format"`   // "mp3", "wav", "opus", "pcm"
	OpenAI      TTSOpenAI      `toml:"openai"`
	Google      TTSGoogle      `toml:"google"`
	Deepgram    TTSDeepgram    `toml:"deepgram"`
	HuggingFace TTSHuggingFace `toml:"huggingface"`
	Foundry     TTSFoundry     `toml:"foundry"`
	Local       TTSLocal       `toml:"local"`
	Piper       TTSPiper       `toml:"piper"`
}

type TTSDeepgram struct {
	Enabled bool   `toml:"enabled"`
	Model   string `toml:"model"` // Aura-2 voice id, e.g. "aura-2-thalia-en"
	Voice   string `toml:"voice"` // optional explicit voice override (alias of Model)
}

type TTSFoundry struct {
	Enabled bool   `toml:"enabled"`
	Model   string `toml:"model"` // deployment name, e.g. "gpt-4o-mini-tts"
	Voice   string `toml:"voice"` // alloy, echo, fable, onyx, nova, shimmer
}

type TTSGoogle struct {
	Enabled bool   `toml:"enabled"`
	Voice   string `toml:"voice"` // e.g. "de-DE-Neural2-B"
}

type TTSHuggingFace struct {
	Enabled bool   `toml:"enabled"`
	Model   string `toml:"model"` // e.g. "Qwen/Qwen3-TTS-12Hz-1.7B-Base"
}

type TTSLocal struct {
	Enabled   bool   `toml:"enabled"`
	Model     string `toml:"model"`
	ModelPath string `toml:"model_path"`
	Port      int    `toml:"port"`
}

type TTSOpenAI struct {
	Enabled bool   `toml:"enabled"`
	Model   string `toml:"model"` // "tts-1" or "tts-1-hd"
	Voice   string `toml:"voice"` // alloy, echo, fable, onyx, nova, shimmer
}

type TTSPiper struct {
	Enabled  bool   `toml:"enabled"`
	Binary   string `toml:"binary"`    // path to piper executable; empty => "piper" on PATH
	VoiceDir string `toml:"voice_dir"` // directory holding *.onnx voice files
	// DefaultVoices maps a locale short-code ("en", "de", ...) to a voice
	// filename inside VoiceDir. Empty entries fall back to the built-in
	// defaults (en_US-amy-medium.onnx, de_DE-thorsten-medium.onnx).
	DefaultVoices map[string]string `toml:"default_voices"`
	TimeoutSec    int               `toml:"timeout_sec"` // subprocess timeout; 0 => 30 s
}

type TelemetryConfig struct {
	UpdateCheck bool `toml:"update_check"`

	// TracesOTLPEndpoint enables exporting the framework's OpenTelemetry spans
	// (STT routing, TTS, Voice Agent, server lifecycle) to a vendor-neutral
	// OTLP/HTTP traces receiver. When empty (the default) the server installs
	// no TracerProvider, so every otel.Tracer span stays a zero-cost no-op and
	// behaviour is unchanged. Point it at any OTLP/HTTP collector; for Sentry's
	// OTLP ingestion use the full URL
	// https://<org>.ingest.<region>.sentry.io/api/<project>/otlp/v1/traces.
	TracesOTLPEndpoint string `toml:"traces_otlp_endpoint"`
	// TracesSampleRate is the head sampling ratio in [0,1]. 0 (or >=1) means
	// always-sample, which is the right default for a low-traffic dogfood
	// deployment where we want to see every trace.
	TracesSampleRate float64 `toml:"traces_sample_rate"`
	// The OTLP auth secret stays out of config files. OTLPAuthHeaderName is the
	// HTTP header to attach (e.g. "x-sentry-auth"); its value is read at startup
	// from the environment variable named by OTLPAuthHeaderEnv (e.g. a
	// Doppler/Render secret holding "sentry sentry_key=<public_key>"). When
	// either is empty no auth header is sent (suitable for a local collector).
	OTLPAuthHeaderName string `toml:"otlp_auth_header_name"`
	OTLPAuthHeaderEnv  string `toml:"otlp_auth_header_env"`
	// ServiceName + Environment tag every exported span's resource so Sentry can
	// separate speechkit-server from other services and staging from prod.
	ServiceName string `toml:"service_name"`
	Environment string `toml:"environment"`
}

type UIConfig struct {
	OverlayEnabled          bool                           `toml:"overlay_enabled"`
	OverlayPosition         string                         `toml:"overlay_position"` // "top", "bottom", "left", "right"
	OverlayMovable          bool                           `toml:"overlay_movable"`
	OverlayFreeX            int                            `toml:"overlay_free_x"`
	OverlayFreeY            int                            `toml:"overlay_free_y"`
	OverlayMonitorPositions map[string]OverlayFreePosition `toml:"overlay_monitor_positions"`
	Visualizer              string                         `toml:"visualizer"`
	Design                  string                         `toml:"design"`
	AssistOverlayMode       string                         `toml:"assist_overlay_mode"`
	VoiceAgentOverlayMode   string                         `toml:"voice_agent_overlay_mode"`
	// Voice Assistant appearance (speechkit-voice-assistant element):
	// "aura" | "waveform", "rosette" | "k" | "none", and whether the live
	// transcript renders by default.
	AssistantVariant    string `toml:"assistant_variant"`
	AssistantMark       string `toml:"assistant_mark"`
	AssistantTranscript bool   `toml:"assistant_transcript"`
	// OverlayActions is the overlay shortcut-function strip (mic, copy,
	// note, language, live, model, meeting). Omitted means the shipped default. The
	// sentinel "none" persists an empty strip.
	OverlayActions []string `toml:"overlay_actions"`
}

type UpdateConfig struct {
	Enabled     bool   `toml:"enabled"`
	ManifestURL string `toml:"manifest_url"`
	// AutoDownload fetches an available update in the background as soon as
	// the check finds one, so installing is a single click instead of a
	// download wait. Installation is never automatic: the user always
	// confirms, and the app never restarts itself. Set false to keep the
	// fully manual flow (check -> download on demand).
	AutoDownload bool `toml:"auto_download"`
	// Channel selects which published releases are eligible: "auto"
	// (default), "stable", or "prerelease". Auto follows the running
	// build's own maturity — a pre-1.0 app accepts prereleases, a 1.0+ app
	// does not. That default exists because the delivery pipeline publishes
	// every pre-1.0 release as a prerelease, and GitHub's /releases/latest
	// skips those, so a stable-only client below 1.0 would never see an
	// update at all. The channel governs discovery only; whether an update
	// may be installed automatically stays with the install-mode rules
	// (unsigned builds still require a matching published digest).
	Channel                string `toml:"channel"`
	CheckIntervalHours     int    `toml:"check_interval_hours"`
	SignaturePinThumbprint string `toml:"signature_pin_thumbprint"` // optional Authenticode SHA-1 thumbprint; if set, installer signature verification additionally checks cert thumbprint matches (defense against compromised signing cert)
}

type VADConfig struct {
	SilenceBelow float64 `toml:"silence_below"` // RMS at/below this is silence
	SpeechAbove  float64 `toml:"speech_above"`  // RMS at/above this is speech
	HangoverMs   int     `toml:"hangover_ms"`   // hold speech verdict this long after the last speech frame
}

type VPSConfig struct {
	Enabled   bool   `toml:"enabled"`
	URL       string `toml:"url"`
	Model     string `toml:"model"`
	APIKeyEnv string `toml:"api_key_env"`
}

type VocabularyConfig struct {
	Dictionary string `toml:"dictionary"`
}

type VoiceAgentConfig struct {
	Enabled bool `toml:"enabled"`
	// Provider selects the backend that drives a Voice Agent session.
	// Supported values:
	//   ""          (default) — same as "gemini"
	//   "gemini"    — Google Gemini Live (cloud, GOOGLE_AI_API_KEY required)
	//   "openai"    — OpenAI Realtime API (cloud, OPENAI_API_KEY required)
	//   "deepgram"  — Deepgram Voice Agent (cloud, DEEPGRAM_API_KEY required)
	//   "assemblyai" — AssemblyAI Voice Agent API (cloud, ASSEMBLYAI_API_KEY required)
	//   "cascaded"  — self-hosted whisper.cpp → Genkit agent LLM → TTS pipeline
	//                 (CPU-capable; no external realtime dependency)
	//   "moshi"     — self-hosted Kyutai Moshi Rust server (GPU required, M9b)
	//
	// The Server-Target reads this field via cmd/speechkit-server. The Device-
	// Target runs "gemini", "openai", "deepgram", and — since v0.58 —
	// "assemblyai" in-process; any other value falls back to Gemini Live (or
	// the pipeline fallback when enabled), and the Device-Target logs and
	// surfaces that fallback at session preparation instead of silently
	// running Gemini.
	Provider      string `toml:"provider"`
	Model         string `toml:"model"`          // Real-time model ID (e.g. "gemini-3.1-flash-live-preview")
	FallbackModel string `toml:"fallback_model"` // Fallback real-time model
	Voice         string `toml:"voice"`          // Voice name for real-time model
	// Deepgram Voice Agent think-LLM overrides. The think leg reasons over the
	// transcript; listen and speak stay Deepgram. When unset, the kernel default
	// (Deepgram-managed open_ai/gpt-4o-mini) applies. Setting
	// DeepgramThinkEndpointURL + DeepgramThinkAPIKeyEnv switches the think leg to
	// a bring-your-own LLM deployment, with the credential resolved from the
	// named env var (env -> Doppler). Read by the Server- and Device-Target
	// Deepgram Voice Agent wiring; ignored by the Gemini/cascaded backends.
	DeepgramThinkProvider    string `toml:"deepgram_think_provider"`
	DeepgramThinkModel       string `toml:"deepgram_think_model"`
	DeepgramThinkEndpointURL string `toml:"deepgram_think_endpoint_url"`
	DeepgramThinkAPIKeyEnv   string `toml:"deepgram_think_api_key_env"`
	// Deepgram Voice Agent listen/speak leg overrides. Empty values fall back to
	// the "listen+speak" composite in [voice_agent].model and then to the kernel
	// defaults (Flux listen, Aura-2 speak).
	//
	// DeepgramSpeakModel accepts an Aura-2 voice or a Flux TTS voice. Flux TTS is
	// English-only, so a Flux voice applies only to English-pinned sessions; every
	// other session falls back to the locale's Aura-2 voice. Aura-2 stays the
	// default on all paths — a Flux voice here is the opt-in.
	DeepgramListenModel string  `toml:"deepgram_listen_model"`
	DeepgramSpeakModel  string  `toml:"deepgram_speak_model"`
	DeepgramSpeakSpeed  float64 `toml:"deepgram_speak_speed"`
	// Flux turn-detection tuning; ignored by the Nova listen models. Ranges are
	// clamped in the kernel: threshold 0.5–0.9, eager threshold 0.3–0.9, timeout
	// 500–60000 ms. 0 keeps Deepgram's defaults.
	DeepgramListenEOTThreshold      float64 `toml:"deepgram_listen_eot_threshold"`
	DeepgramListenEagerEOTThreshold float64 `toml:"deepgram_listen_eager_eot_threshold"`
	DeepgramListenEOTTimeoutMs      int     `toml:"deepgram_listen_eot_timeout_ms"`
	AgentProfileID                  string  `toml:"agent_profile_id"`  // Built-in Voice Agent profile ID; "default" preserves current behavior.
	AgentSequenceID                 string  `toml:"agent_sequence_id"` // Optional workflow sequence ID; empty uses the selected persona default.
	FrameworkPrompt                 string  `toml:"framework_prompt"`  // Durable host/framework instruction that defines the Voice Agent behavior
	RefinementPrompt                string  `toml:"refinement_prompt"` // User-specific refinement appended to the framework prompt
	// AutoStartOnLaunch is legacy: it is kept only so backfillStartupBehavior
	// can migrate an old [voice_agent].auto_start_on_launch into the
	// General.AutoStartOnLaunch app-window preference. It no longer starts a
	// Voice Agent session on launch — launching the app presents the app UI,
	// never a live conversation. See dashboardAutoOpenOnLaunch (Device-Target).
	AutoStartOnLaunch bool   `toml:"auto_start_on_launch"`
	CloseBehavior     string `toml:"close_behavior"` // "continue" keeps the conversation window in the taskbar; "new_chat" ends the current chat on close
	// BargeIn controls whether the microphone stays open while the agent is
	// speaking so the user can interrupt mid-answer:
	//   "auto"   (default) — full duplex when the active output device looks
	//            like a headset (closed acoustic path, no speaker bleed);
	//            half duplex otherwise. Evaluated at session start.
	//   "always" — full duplex on every output device. Only sensible with
	//            hardware/OS echo cancellation; without it the agent hears
	//            itself through the speakers and interrupts itself.
	//   "never"  — half duplex: the mic is muted while the agent speaks and
	//            until the buffered answer finished playing.
	BargeIn                string `toml:"barge_in"`
	ReminderAfterIdleSec   int    `toml:"reminder_after_idle_sec"`
	DeactivateAfterIdleSec int    `toml:"deactivate_after_idle_sec"`
	// HoldReleaseGraceSec controls how long the Voice Agent stays open after
	// the user releases a hold-to-talk shortcut so the model has time to
	// deliver its reply. 0 (or unset) falls back to the kernel default
	// (10 seconds). The Device-Target hard-caps this at 30 seconds; values
	// above that are silently clamped at runtime so a misconfigured profile
	// cannot strand the user in a "still active" session.
	HoldReleaseGraceSec int `toml:"hold_release_grace_sec"`
	// WarmSessionLingerSec keeps the realtime session (and its already-paid
	// WebSocket handshake) open for this many seconds after a hold-to-talk
	// answer finishes, so the next press resumes the warm connection instead
	// of re-dialing the provider (~700 ms handshake measured against Deepgram).
	// A press within the window reuses the connection; the window expiring,
	// an explicit stop, or the idle timeout tears it down. 0 disables the
	// linger (legacy deactivate-immediately behaviour). The session summary
	// and the prompter close only run when the conversation truly ends —
	// never on a release that gets resumed inside the window.
	WarmSessionLingerSec int `toml:"warm_session_linger_sec"`
	// PauseToleranceMs filters short silences out of the outgoing mic stream
	// so the realtime provider's server-side endpointing does not fire during
	// brief thinking pauses: silent frames are dropped until the accumulated
	// pause reaches this tolerance, then silence flows again and the provider
	// answers. Effective answer latency ≈ tolerance + provider threshold.
	// 0 disables the filter (provider default endpointing).
	PauseToleranceMs                int                    `toml:"pause_tolerance_ms"`
	PipelineFallback                bool                   `toml:"pipeline_fallback"` // Use STT -> Agent LLM -> optional TTS when the selected Voice Agent profile is not native realtime.
	ShowPrompter                    bool                   `toml:"show_prompter"`     // Show live transcript prompter window
	EnableSessionSummary            bool                   `toml:"enable_session_summary"`
	EnableInputTranscript           bool                   `toml:"enable_input_transcript"`
	EnableOutputTranscript          bool                   `toml:"enable_output_transcript"`
	EnableAffectiveDialog           bool                   `toml:"enable_affective_dialog"`
	ThinkingEnabled                 bool                   `toml:"thinking_enabled"`
	IncludeThoughts                 bool                   `toml:"include_thoughts"`
	ThinkingBudget                  int                    `toml:"thinking_budget"`
	ThinkingLevel                   string                 `toml:"thinking_level"`
	ContextCompressionEnabled       bool                   `toml:"context_compression_enabled"`
	ContextCompressionTriggerTokens int64                  `toml:"context_compression_trigger_tokens"`
	ContextCompressionTargetTokens  int64                  `toml:"context_compression_target_tokens"`
	AutomaticActivityDetection      bool                   `toml:"automatic_activity_detection"`
	ActivityHandling                string                 `toml:"activity_handling"`
	TurnCoverage                    string                 `toml:"turn_coverage"`
	VADStartSensitivity             string                 `toml:"vad_start_sensitivity"`
	VADEndSensitivity               string                 `toml:"vad_end_sensitivity"`
	VADPrefixPaddingMs              int                    `toml:"vad_prefix_padding_ms"`
	VADSilenceDurationMs            int                    `toml:"vad_silence_duration_ms"`
	Limits                          VoiceAgentLimitsConfig `toml:"limits"`
}

type VoiceAgentLimitsConfig struct {
	MaxGlobalSessions      int `toml:"max_global_sessions"`
	MaxPerIdentitySessions int `toml:"max_per_identity_sessions"`
}

type WakewordAutoEndConfig struct {
	// SilenceCutoffSec is the duration without user audio activity (in
	// whole seconds) after which a wake-word-triggered session ends.
	// Zero falls back to the framework default (10s).
	SilenceCutoffSec int `toml:"silence_cutoff_sec"`

	// ExitPhrases is the case-insensitive substring list checked against
	// each user-transcript snippet. Empty falls back to the framework
	// default (DE+EN common closers: "danke", "tschuess", "ende", "stop",
	// "thanks", "bye", "goodbye", ...).
	ExitPhrases []string `toml:"exit_phrases"`
}

type WakewordConfig struct {
	// Enabled gates the entire feature. Default false (opt-in).
	Enabled bool `toml:"enabled"`

	// Backend selects the local detector implementation. The Windows app
	// ships Sherpa-ONNX KWS, LiveKit/openWakeWord ONNX, and STT phrase-match
	// as explicit selectable paths so test builds can compare detector
	// behaviour without silently falling back to a different implementation.
	Backend string `toml:"backend"`

	// PhraseID picks one of SpeechKit's curated wake phrases from
	// wakeword.DefaultCatalog (e.g. "hey_quby", "hey_computer",
	// "hey_jarvis", "hey_mira"). When set, the corresponding ONNX file is
	// resolved automatically and Phrase/ModelPath below are ignored. When
	// empty, the explicit Phrase + ModelPath fields are used instead
	// (custom phrase mode). Switching via this field is how users pick a
	// different wake phrase in settings without editing paths by hand.
	PhraseID string `toml:"phrase_id"`

	// Phrase is the display label of the trained wake phrase, surfaced in
	// the tray and status feed. It has NO effect on detection — the ONNX
	// model encodes the actual phrase(s). One model can be trained to
	// fire on multiple pronunciation variants (e.g. "Hey Cubi" and
	// "Hey Kubi" for the same brand "Quby") via target_phrases in the
	// training yaml; the display label here remains a single brand string.
	//
	// Ignored when PhraseID matches a catalog entry (the catalog's
	// DisplayName is used instead).
	Phrase string `toml:"phrase"`

	// ModelPath is the path to the trained phrase prediction model (.onnx).
	// Empty resolves to <data_dir>/models/wakeword/hey_quby.onnx at runtime.
	//
	// Ignored when PhraseID matches a catalog entry (the catalog's
	// FileName is resolved inside the wake-word models directory).
	ModelPath string `toml:"model_path"`

	// MelspecModelPath and EmbeddingModelPath point at the shared
	// openWakeWord upstream models. Empty values resolve to the same
	// directory as ModelPath with canonical filenames.
	MelspecModelPath   string `toml:"melspec_model_path"`
	EmbeddingModelPath string `toml:"embedding_model_path"`

	// DefaultMode is the runtime mode triggered when the wake phrase fires.
	// One of "dictate" | "assist" | "voice_agent". Defaults to voice_agent.
	DefaultMode string `toml:"default_mode"`

	// Threshold is the minimum probability to count a frame as a hit.
	// Range (0.0, 1.0]. Backend-specific defaults when this is 0:
	//   - LiveKit/openWakeWord: 0.5 (Wyoming/openWakeWord canonical)
	//   - Sherpa-onnx KWS: 0.25 (sherpa-onnx upstream default)
	//   - STT phrase match: 0 (substring match, no acoustic probability)
	// Use the in-app "Test wake word" self-test in Settings to calibrate
	// for your specific microphone + environment instead of guessing.
	Threshold float64 `toml:"threshold"`

	// MinConsecutiveFrames is the number of consecutive above-threshold
	// frames required before a trigger fires. Higher = fewer false-accepts,
	// more false-rejects. Defaults to 1.
	//
	// openWakeWord scores one frame per 80ms, so this is a duration gate:
	// N frames demands the score hold above Threshold for N*80ms without a
	// single dip. A wake phrase is only ~500ms long and the score spikes
	// rather than plateaus, so values above 3 (240ms) make the phrase
	// effectively undetectable — the counter resets on the first dip and
	// never reaches N. Raise Threshold to cut false-accepts; do not raise
	// this past 3.
	MinConsecutiveFrames int `toml:"min_consecutive_frames"`

	// CooldownMs is the minimum gap between two triggers, in milliseconds.
	// Defaults to 1500ms.
	CooldownMs int `toml:"cooldown_ms"`

	// DebugMode enables verbose detector diagnostics. When true the sidecars
	// emit per-decode score events (openWakeWord) or set the sherpa-onnx
	// ModelConfig.Debug flag (Sherpa KWS), and the host adapter forwards
	// those signals into the user-visible log feed. Default false — only flip
	// on while tuning a wake phrase, the score event stream is high-volume.
	DebugMode bool `toml:"debug_mode"`

	// AutoEnd controls the framework-level auto-end policy applied to any
	// session that the wake-word triggered. Wake-word-origin Voice-Agent
	// activations terminate automatically on silence after this many
	// seconds, or when the user utters one of the configured exit
	// phrases. Empty values fall back to wakeword.DefaultAutoEndConfig
	// (10s silence + DE/EN exit phrases) so a TOML without an [auto_end]
	// block still gets the framework baseline. There is intentionally no
	// hard-cap on session duration — Voice-Agent is designed for
	// multi-hour dialogs and a forced cap would break regular use.
	AutoEnd WakewordAutoEndConfig `toml:"auto_end"`

	// TrainingData controls the optional activation-capture pipeline:
	// the sidecar saves the surrounding audio of each detection to a
	// local directory and, when explicitly opted-in, uploads those
	// clips to a SpeechKit-Server for training-data collection. ALL
	// fields default to OFF — see docs/wakeword-training-data.md.
	TrainingData WakewordTrainingDataConfig `toml:"training_data"`
}

type WakewordTrainingDataConfig struct {
	// LocalCaptureEnabled toggles the sidecar ring-buffer + WAV
	// writer that persists each detection's audio to LocalCaptureDir.
	// Default false. Even when true, no network traffic happens
	// unless UploadEnabled is ALSO true.
	LocalCaptureEnabled bool `toml:"local_capture_enabled"`

	// LocalCaptureDir is the filesystem root that holds the captured
	// WAV + JSON pairs. Empty resolves to
	// %LOCALAPPDATA%/SpeechKit/wakeword-activations on Windows.
	LocalCaptureDir string `toml:"local_capture_dir"`

	// LocalMaxFiles caps how many activation pairs live on disk
	// before the oldest get deleted by the rotation worker. Default
	// 500. Set to 0 for unlimited (the retention_days limit still
	// applies).
	LocalMaxFiles int `toml:"local_max_files"`

	// LocalRetentionDays auto-deletes activation pairs older than
	// this many days at sidecar startup and every hour after. Zero
	// means "do not auto-delete by age" (LocalMaxFiles still
	// applies). Default 30.
	LocalRetentionDays int `toml:"local_retention_days"`

	// PreRollMs is the duration of audio captured BEFORE the
	// detection trigger. The sidecar keeps this many milliseconds
	// of PCM in a ring buffer so the moment the detection fires it
	// can write the leading audio that contains the actual wake
	// phrase. Default 1500 (matches the wake-phrase windows the
	// existing detectors are tuned against).
	PreRollMs int `toml:"pre_roll_ms"`

	// PostRollMs is the duration of audio captured AFTER the
	// detection trigger. Useful for catching the speaker continuing
	// past the wake phrase so a labeler can hear whether the
	// utterance was a true positive or noise. Default 500.
	PostRollMs int `toml:"post_roll_ms"`

	// UploadEnabled toggles the background uploader that pushes
	// captured clips to UploadServerURL. Requires both
	// LocalCaptureEnabled=true and UploadServerURL+UploadTokenEnv
	// to be set. Default false.
	UploadEnabled bool `toml:"upload_enabled"`

	// UploadServerURL is the base URL of the SpeechKit-Server that
	// accepts POST /v1/wakeword/activations. Empty falls back to
	// [server_connection].url when set.
	UploadServerURL string `toml:"upload_server_url"`

	// UploadTokenEnv names the env var (resolved via
	// internal/secrets) that holds the bearer token used by the
	// uploader. Default "SPEECHKIT_TRAINING_TOKEN".
	UploadTokenEnv string `toml:"upload_token_env"`

	// UploadOnlyLabeled limits uploads to clips that the user has
	// labeled (correct / false_positive). When true (default),
	// unlabeled clips stay local — privacy-friendly default that
	// only ships audio after explicit user review.
	UploadOnlyLabeled bool `toml:"upload_only_labeled"`

	// UploadIntervalMinutes is the cadence at which the uploader
	// scans LocalCaptureDir and flushes new clips to the server.
	// Default 60.
	UploadIntervalMinutes int `toml:"upload_interval_minutes"`
}