@vellumai/assistant 0.3.19 → 0.3.20

package/src/config/assistant-feature-flags.ts

@@ -0,0 +1,162 @@
+/**
+ * Canonical assistant feature-flag resolver.
+ *
+ * Loads default flag values from the unified registry at
+ * `meta/feature-flags/feature-flag-registry.json` and resolves the effective
+ * enabled/disabled state for each declared assistant-scope flag by consulting
+ * (in priority order):
+ *   1. `config.assistantFeatureFlagValues[key]`  (explicit override)
+ *   2. defaults registry `defaultEnabled`         (for declared keys)
+ *   3. `true`                                     (for undeclared keys)
+ *
+ * Key format:
+ *   Canonical:  `feature_flags.<id>.enabled`
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import type { AssistantConfig } from './schema.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FeatureFlagDefault {
+  defaultEnabled: boolean;
+  description: string;
+  label: string;
+}
+
+export type FeatureFlagDefaultsRegistry = Record<string, FeatureFlagDefault>;
+
+// ---------------------------------------------------------------------------
+// Registry loading (singleton, loaded once)
+// ---------------------------------------------------------------------------
+
+let cachedDefaults: FeatureFlagDefaultsRegistry | undefined;
+
+const REGISTRY_FILENAME = 'feature-flag-registry.json';
+
+function loadDefaultsRegistry(): FeatureFlagDefaultsRegistry {
+  if (cachedDefaults) return cachedDefaults;
+
+  const thisDir = import.meta.dirname ?? __dirname;
+  const envPath = process.env.FEATURE_FLAG_DEFAULTS_PATH?.trim();
+  const candidates = [
+    // Explicit override (primarily for tests / controlled environments)
+    ...(envPath ? [envPath] : []),
+    // Bundled: co-located copy in the same directory as this source file.
+    // Works in Docker / packaged builds where the repo-root `meta/` dir
+    // is not available.
+    join(thisDir, REGISTRY_FILENAME),
+    // Packaged macOS app layout: the daemon binary lives at
+    // <App>.app/Contents/MacOS/vellum-daemon and the registry is copied
+    // to <App>.app/Contents/Resources/ by build.sh. In bun --compile
+    // binaries, import.meta.dirname resolves to /$bunfs/root (virtual),
+    // so we need to resolve relative to the real executable path.
+    join(dirname(process.execPath), '..', 'Resources', REGISTRY_FILENAME),
+    // Development: relative to this source file's directory, walking up
+    // to the repo root to reach `meta/feature-flags/`.
+    join(thisDir, '..', '..', '..', 'meta', 'feature-flags', REGISTRY_FILENAME),
+    // Alternate: from repo root via cwd
+    join(process.cwd(), 'meta', 'feature-flags', REGISTRY_FILENAME),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      try {
+        const raw = readFileSync(candidate, 'utf-8');
+        const parsed = JSON.parse(raw);
+        cachedDefaults = parseRegistryToDefaults(parsed);
+        return cachedDefaults;
+      } catch {
+        // Malformed file — fall through to next candidate
+      }
+    }
+  }
+
+  cachedDefaults = {};
+  return cachedDefaults;
+}
+
+/**
+ * Parse the unified registry JSON into a flat key -> default map,
+ * filtering to assistant-scope flags only.
+ */
+function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+
+  const registry = parsed as { version?: number; flags?: unknown[] };
+  if (!Array.isArray(registry.flags)) return {};
+
+  const result: FeatureFlagDefaultsRegistry = {};
+  for (const flag of registry.flags) {
+    if (!flag || typeof flag !== 'object' || Array.isArray(flag)) continue;
+    const entry = flag as Record<string, unknown>;
+    if (entry.scope !== 'assistant') continue;
+    if (typeof entry.key !== 'string') continue;
+    if (typeof entry.defaultEnabled !== 'boolean') continue;
+
+    result[entry.key as string] = {
+      defaultEnabled: entry.defaultEnabled,
+      description: typeof entry.description === 'string' ? entry.description : '',
+      label: typeof entry.label === 'string' ? entry.label : '',
+    };
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve whether an assistant feature flag is enabled.
+ *
+ * Resolution order:
+ *   1. `config.assistantFeatureFlagValues[key]`  (explicit override)
+ *   2. defaults registry `defaultEnabled`         (for declared assistant-scope keys)
+ *   3. `true`                                     (for undeclared keys with no override)
+ */
+export function isAssistantFeatureFlagEnabled(key: string, config: AssistantConfig): boolean {
+  const defaults = loadDefaultsRegistry();
+  const declared = defaults[key];
+
+  // 1. Check canonical section
+  const newValues = (config as AssistantConfigWithFeatureFlags).assistantFeatureFlagValues;
+  if (newValues) {
+    const explicit = newValues[key];
+    if (typeof explicit === 'boolean') return explicit;
+  }
+
+  // 2. For declared keys, use the registry default
+  if (declared) {
+    return declared.defaultEnabled;
+  }
+
+  // 3. Undeclared keys with no persisted override default to enabled
+  return true;
+}
+
+/**
+ * Return the loaded defaults registry (for introspection/tooling).
+ */
+export function getAssistantFeatureFlagDefaults(): FeatureFlagDefaultsRegistry {
+  return loadDefaultsRegistry();
+}
+
+/**
+ * Reset the cached defaults registry. Intended for tests only.
+ */
+export function _resetDefaultsCache(): void {
+  cachedDefaults = undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Internal type augmentation for the new config field
+// ---------------------------------------------------------------------------
+
+interface AssistantConfigWithFeatureFlags extends AssistantConfig {
+  assistantFeatureFlagValues?: Record<string, boolean>;
+}

package/src/config/bundled-skills/api-mapping/icon.svg

@@ -0,0 +1,18 @@
+<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+  <rect width="16" height="16" fill="#0f172a"/>
+  <rect x="2" y="2" width="12" height="12" fill="#1e293b"/>
+  <rect x="3" y="3" width="10" height="10" fill="#0f172a" stroke="#3b82f6" stroke-width="1"/>
+  <rect x="4" y="4" width="2" height="2" fill="#3b82f6"/>
+  <rect x="10" y="4" width="2" height="2" fill="#3b82f6"/>
+  <rect x="4" y="10" width="2" height="2" fill="#3b82f6"/>
+  <rect x="10" y="10" width="2" height="2" fill="#3b82f6"/>
+  <line x1="5" y1="5" x2="11" y2="5" stroke="#10b981" stroke-width="1"/>
+  <line x1="5" y1="5" x2="5" y2="11" stroke="#10b981" stroke-width="1"/>
+  <line x1="11" y1="5" x2="11" y2="11" stroke="#10b981" stroke-width="1"/>
+  <line x1="5" y1="11" x2="11" y2="11" stroke="#10b981" stroke-width="1"/>
+  <rect x="7" y="7" width="2" height="2" fill="#f59e0b"/>
+  <line x1="5" y1="8" x2="7" y2="8" stroke="#60a5fa" stroke-width="1"/>
+  <line x1="9" y1="8" x2="11" y2="8" stroke="#60a5fa" stroke-width="1"/>
+  <line x1="8" y1="5" x2="8" y2="7" stroke="#60a5fa" stroke-width="1"/>
+  <line x1="8" y1="9" x2="8" y2="11" stroke="#60a5fa" stroke-width="1"/>
+</svg>

package/src/config/bundled-skills/messaging/TOOLS.json

@@ -256,6 +256,36 @@
       "executor": "tools/slack-add-reaction.ts",
       "execution_target": "host"
     },
+    {
+      "name": "slack_delete_message",
+      "description": "Delete a Slack message posted by the bot. Include a confidence score (0-1).",
+      "category": "messaging",
+      "risk": "high",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "channel": {
+            "type": "string",
+            "description": "Slack channel ID"
+          },
+          "timestamp": {
+            "type": "string",
+            "description": "Message timestamp (ts) to delete"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          }
+        },
+        "required": [
+          "channel",
+          "timestamp",
+          "confidence"
+        ]
+      },
+      "executor": "tools/slack-delete-message.ts",
+      "execution_target": "host"
+    },
     {
       "name": "slack_leave_channel",
       "description": "Leave a Slack channel. Include a confidence score (0-1).",

package/src/config/bundled-skills/messaging/tools/slack-delete-message.ts

@@ -0,0 +1,24 @@
+import { deleteMessage } from '../../../../messaging/providers/slack/client.js';
+import { getMessagingProvider } from '../../../../messaging/registry.js';
+import { withValidToken } from '../../../../security/token-manager.js';
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { err, ok } from './shared.js';
+
+export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+  const channel = input.channel as string;
+  const timestamp = input.timestamp as string;
+
+  if (!channel || !timestamp) {
+    return err('channel and timestamp are both required.');
+  }
+
+  try {
+    const provider = getMessagingProvider('slack');
+    return withValidToken(provider.credentialService, async (token) => {
+      await deleteMessage(token, channel, timestamp);
+      return ok(`Message deleted.`);
+    });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}

package/src/config/bundled-skills/notifications/SKILL.md

@@ -14,7 +14,7 @@ Use `send_notification` for user-facing alerts and notifications. This tool rout
 
 ## Deduplication (`dedupe_key`)
 
-- `dedupe_key` suppresses duplicate signals. A second notification with the same key is **dropped entirely** within a **1-hour window**. After the window expires, the same key is accepted again.
+- `dedupe_key` suppresses duplicate signals **permanently**. A second notification with the same key is **dropped entirely** for the lifetime of the assistant's event store. Once a key has been used, it cannot be reused — any future notification with the same key will be silently discarded.
 - Never reuse a `dedupe_key` across logically distinct notifications, even if they are related. The key means "this exact event already fired," not "these events are in the same category."
 - If you omit `dedupe_key`, the LLM decision engine may generate one automatically based on signal context. This means even keyless signals can be deduplicated if the engine considers them duplicates of a recent event.
 

package/src/config/bundled-skills/reminder/SKILL.md

@@ -15,12 +15,34 @@ Create, list, and cancel one-time reminders. Reminders fire at a specific future
 
 Control how the reminder is delivered at trigger time with `routing_intent`:
 
-- **single_channel** (default) — deliver to one best channel
+- **single_channel** — deliver to one best channel
 - **multi_channel** — deliver to a subset of channels
-- **all_channels** — deliver to every available channel
+- **all_channels** (default) — deliver to every available channel
 
 Optionally pass `routing_hints` (a JSON object) to influence routing decisions (e.g. preferred channels, exclusions). When omitted, defaults to `{}`.
 
+### Routing Defaults
+
+Use the following heuristics to pick `routing_intent`:
+
+- **Default to `all_channels`** for most reminders. Users setting reminders usually want to be notified wherever they are, and redundant notifications are less harmful than missed ones.
+- **Use `single_channel`** only when the user explicitly specifies a single channel (e.g. "remind me on Telegram") or the reminder is low-stakes and noise reduction matters.
+- **Check `user_message_channel`** from the turn context. If the user is currently active on a specific channel (e.g. `vellum`), always include that channel. Pass it as a routing hint:
+  ```
+  routing_hints: { preferred_channels: ["vellum"] }
+  routing_intent: "all_channels"
+  ```
+- **Never use `single_channel` as a passive default.** If you haven't thought about which channel to use, use `all_channels`.
+
+### Examples
+
+| Scenario | routing_intent | routing_hints |
+|---|---|---|
+| User sets reminder from desktop app | `all_channels` | `{ preferred_channels: ["vellum"] }` |
+| User says "remind me on Telegram" | `single_channel` | `{ preferred_channels: ["telegram"] }` |
+| User sets reminder from Telegram | `all_channels` | `{ preferred_channels: ["telegram"] }` |
+| No channel preference expressed | `all_channels` | `{}` |
+
 ## Usage Notes
 
 - Use reminders ONLY for time-triggered notifications (e.g. "remind me at 3pm", "remind me in 2 hours").
@@ -28,3 +50,28 @@ Optionally pass `routing_hints` (a JSON object) to influence routing decisions (
 - For task tracking ("add to my tasks", "add to my queue"), use task_list_add instead.
 - `fire_at` must be a strict ISO 8601 timestamp with timezone offset or Z (e.g. `2025-03-15T09:00:00-05:00` or `2025-03-15T09:00:00Z`). Ambiguous timestamps without timezone info will be rejected.
 - `label` is a short human-readable summary shown in the notification.
+
+### Anchored & Ambiguous Relative Time
+
+Phrases like "at the 45 minute mark", "at the top of the hour", "on the half-hour", "at noon", "20 minutes in", or "when I hit an hour" are **clock-position or anchored relative time** expressions. Do NOT treat them as offsets from now.
+
+**Resolution rules (in priority order):**
+
+1. **Clock-position expressions** — map directly to a wall-clock time:
+   - "top of the hour" / "on the hour" → next :00 (e.g. 10:00 AM)
+   - "the X minute mark" / "at :XX" → current hour's :XX; if already past, advance one hour
+   - "the half-hour mark" / "half past" → nearest upcoming :30
+   - "noon" / "midnight" → 12:00 PM or 12:00 AM today; if past, tomorrow
+   - "quarter past" / "quarter to" → :15 or :45 of current or next hour
+
+2. **Session-anchored expressions** — if the user mentioned a start time earlier in conversation ("I got here at 9", "meeting started at 2pm"), compute `start_time + offset`.
+
+3. **Ask only if truly ambiguous** — if neither rule 1 nor rule 2 resolves, ask: "Do you mean [clock time] or [X minutes from now]?" Never silently default to "from now."
+
+**Examples:**
+- "at the 45 min mark" (now: 9:39) → 9:45 AM
+- "at the 45 min mark" (now: 9:50) → 10:45 AM
+- "top of the hour" (now: 9:39) → 10:00 AM
+- "at noon" → 12:00 PM today
+- "20 minutes in, I started at 2pm" → 2:20 PM
+- "at the hour mark" with no start time → ask for clarification

package/src/config/bundled-skills/time-based-actions/SKILL.md

@@ -55,6 +55,31 @@ When the user says "in X minutes/hours", compute the ISO 8601 timestamp yourself
 - Format as ISO 8601 with timezone: `2025-03-15T09:05:00-05:00`
 - Pass to `reminder_create` as `fire_at`
 
+### Anchored & Ambiguous Relative Time
+
+Phrases like "at the 45 minute mark", "at the top of the hour", "on the half-hour", "at noon", "20 minutes in", or "when I hit an hour" are **clock-position or anchored relative time** expressions. Do NOT treat them as offsets from now.
+
+**Resolution rules (in priority order):**
+
+1. **Clock-position expressions** — map directly to a wall-clock time:
+   - "top of the hour" / "on the hour" → next :00 (e.g. 10:00 AM)
+   - "the X minute mark" / "at :XX" → current hour's :XX; if already past, advance one hour
+   - "the half-hour mark" / "half past" → nearest upcoming :30
+   - "noon" / "midnight" → 12:00 PM or 12:00 AM today; if past, tomorrow
+   - "quarter past" / "quarter to" → :15 or :45 of current or next hour
+
+2. **Session-anchored expressions** — if the user mentioned a start time earlier in conversation ("I got here at 9", "meeting started at 2pm"), compute `start_time + offset`.
+
+3. **Ask only if truly ambiguous** — if neither rule 1 nor rule 2 resolves, ask: "Do you mean [clock time] or [X minutes from now]?" Never silently default to "from now."
+
+**Examples:**
+- "at the 45 min mark" (now: 9:39) → 9:45 AM
+- "at the 45 min mark" (now: 9:50) → 10:45 AM
+- "top of the hour" (now: 9:39) → 10:00 AM
+- "at noon" → 12:00 PM today
+- "20 minutes in, I started at 2pm" → 2:20 PM
+- "at the hour mark" with no start time → ask for clarification
+
 ## "Remind me to X" Disambiguation
 
 The word "remind" is ambiguous. Route based on whether a time is specified:
@@ -77,12 +102,34 @@ Use `notify` for simple alerts. Use `execute` when the reminder should trigger t
 ## Reminder Routing
 
 `reminder_create` supports a `routing_intent` parameter that controls how the reminder is delivered at trigger time:
-- **`single_channel`** (default) — deliver to one best channel
+- **`single_channel`** — deliver to one best channel
 - **`multi_channel`** — deliver to a subset of channels
-- **`all_channels`** — deliver to every available channel
+- **`all_channels`** (default) — deliver to every available channel
 
 You can also pass `routing_hints` (a JSON object) to influence routing decisions (e.g. preferred channels, exclusions).
 
+### Routing Defaults
+
+Use the following heuristics to pick `routing_intent`:
+
+- **Default to `all_channels`** for most reminders. Users setting reminders usually want to be notified wherever they are, and redundant notifications are less harmful than missed ones.
+- **Use `single_channel`** only when the user explicitly specifies a single channel (e.g. "remind me on Telegram") or the reminder is low-stakes and noise reduction matters.
+- **Check `user_message_channel`** from the turn context. If the user is currently active on a specific channel (e.g. `vellum`), always include that channel. Pass it as a routing hint:
+  ```
+  routing_hints: { preferred_channels: ["vellum"] }
+  routing_intent: "all_channels"
+  ```
+- **Never use `single_channel` as a passive default.** If you haven't thought about which channel to use, use `all_channels`.
+
+### Examples
+
+| Scenario | routing_intent | routing_hints |
+|---|---|---|
+| User sets reminder from desktop app | `all_channels` | `{ preferred_channels: ["vellum"] }` |
+| User says "remind me on Telegram" | `single_channel` | `{ preferred_channels: ["telegram"] }` |
+| User sets reminder from Telegram | `all_channels` | `{ preferred_channels: ["telegram"] }` |
+| No channel preference expressed | `all_channels` | `{}` |
+
 ## Tool Summary
 
 | Tool | Timing | Recurrence | Purpose |

package/src/config/bundled-skills/voice-setup/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: "Voice Setup"
+description: "Complete voice configuration in chat — PTT key, wake word, microphone permissions, ElevenLabs TTS, and troubleshooting"
+user-invocable: true
+metadata: {"vellum": {"emoji": "🎙️", "os": ["darwin"]}}
+---
+
+You are helping the user set up and troubleshoot voice features (push-to-talk, wake word, text-to-speech) entirely within this conversation. Do NOT direct the user to the Settings page for initial setup — handle everything in-chat using the tools below.
+
+## Available Tools
+
+- `voice_config_update` — Change any voice setting (PTT key, wake word enabled/keyword/timeout)
+- `open_system_settings` — Open macOS System Settings to a specific privacy pane
+- `navigate_settings_tab` — Open the Vellum settings panel to the Voice tab
+- `credential_store` — Collect API keys securely (for ElevenLabs TTS)
+
+## Setup Flow
+
+Walk the user through each section in order. Skip sections they don't need. Ask before proceeding to the next section.
+
+### 1. Microphone Permission
+
+Check `<channel_capabilities>` for `microphone_permission_granted`.
+
+**If `false` or missing:**
+1. Explain that macOS requires microphone permission for voice features.
+2. Use `open_system_settings` with `pane: "microphone"` to open the right System Settings pane.
+3. Tell the user: "I've opened System Settings to the Microphone section. Please toggle **Vellum Assistant** on, then come back here."
+4. After they confirm, verify by checking capabilities on the next turn.
+
+**If `true`:** Tell them microphone is already granted and move on.
+
+### 2. Push-to-Talk Activation Key
+
+Present common PTT key options:
+- **Right Option (⌥)** — Default, good general choice
+- **Fn** — Dedicated key on most Mac keyboards
+- **Right Command (⌘)** — Easy to reach
+- **Right Control (⌃)** — Familiar from gaming
+
+Ask which key they prefer, then use `voice_config_update` with `setting: "activation_key"` and the chosen value.
+
+**Common issues to mention:**
+- If they pick a key that conflicts with their emoji picker (Fn or Globe on newer Macs), warn them and suggest an alternative.
+- If they use a terminal app heavily, warn that some keys may be captured by the terminal.
+
+### 3. Wake Word (Optional)
+
+Ask if they want to enable wake word detection (hands-free activation by saying a keyword).
+
+**If yes:**
+1. Use `voice_config_update` with `setting: "wake_word_enabled"`, `value: true`.
+2. Ask what wake word they want. Common choices: "Hey Vellum", "Computer", "Jarvis", their assistant's name.
+3. Use `voice_config_update` with `setting: "wake_word_keyword"` and their chosen word.
+4. Ask about timeout (how long the mic stays active after wake word). Options: 5s, 10s (default), 15s, 30s, 60s.
+5. Use `voice_config_update` with `setting: "wake_word_timeout"` and their chosen value.
+
+**Speech Recognition permission:** Wake word requires Speech Recognition access. Check capabilities — if not granted, use `open_system_settings` with `pane: "speech_recognition"`.
+
+### 4. Text-to-Speech / ElevenLabs (Optional)
+
+Ask if they want high-quality text-to-speech voices via ElevenLabs (optional — standard TTS works without it).
+
+**If yes:**
+1. Tell them they need an ElevenLabs API key. They can get one at https://elevenlabs.io (free tier available).
+2. Use `credential_store` with `action: "prompt"`, `service: "elevenlabs"`, `field: "api_key"` to show a secure input dialog.
+3. After the key is stored, confirm success.
+
+### 5. Verification
+
+After setup is complete:
+1. Summarize what was configured.
+2. Suggest they test by pressing their PTT key (or saying their wake word) and speaking.
+3. Offer to open the Voice settings tab if they want to review: use `navigate_settings_tab` with `tab: "Voice"`.
+
+## Troubleshooting Decision Trees
+
+When the user reports a problem, follow the appropriate decision tree:
+
+### "PTT isn't working" / "Can't record"
+1. **Microphone permission** — Check `microphone_permission_granted` in capabilities. If false, guide through granting it.
+2. **Key check** — Ask what key they're using. Confirm it matches their configured PTT key.
+3. **Emoji picker conflict** — On newer Macs, Fn/Globe opens the emoji picker. If they're using Fn, suggest switching to Right Option or Right Command.
+4. **Speech Recognition permission** — Some voice features need this. Use `open_system_settings` with `pane: "speech_recognition"`.
+5. **App focus** — PTT may not work when Vellum is not the frontmost app or if another app has captured the key.
+
+### "Recording but no text" / "Transcription not working"
+1. **Speech Recognition permission** — Must be granted for transcription.
+2. **Microphone input** — Ask if they see the recording indicator. If yes, the mic works but transcription is failing.
+3. **Locale/language** — Speech recognition works best with the system language. Ask if they're speaking in a different language.
+4. **Background noise** — Excessive noise can prevent transcription. Suggest a quieter environment or a closer microphone.
+
+### "Wake word not detecting"
+1. **Enabled check** — Confirm wake word is enabled in their settings.
+2. **Keyword** — Confirm what keyword they're using. Shorter or common words may have lower accuracy.
+3. **Ambient noise** — Wake word detection is sensitive to background noise.
+4. **Permissions** — Both Microphone and Speech Recognition permissions are required.
+5. **Timeout** — If wake word activates but cuts off too quickly, increase the timeout.
+
+### "Changed a setting but it didn't work"
+1. **IPC broadcast** — The setting should take effect immediately. If it didn't, suggest restarting the assistant.
+2. **Verify** — Open the Voice settings tab with `navigate_settings_tab` to confirm the setting was persisted.
+
+## Deep Debugging
+
+For persistent issues, suggest checking system logs:
+
+```bash
+log stream --predicate 'subsystem == "com.vellum.assistant"' --level debug
+```
+
+Key log categories:
+- `voice` — PTT activation, recording state
+- `wake-word` — Wake word detection events
+- `speech` — Speech recognition results
+
+## Rules
+
+- Always handle setup conversationally in-chat. Do NOT tell the user to go to Settings for initial configuration.
+- Use `navigate_settings_tab` only for review/verification after in-chat setup, not as the primary setup method.
+- Be concise. Don't explain every option exhaustively — present the most common choices and let the user ask for more.
+- If a permission is denied, acknowledge it gracefully and explain what features won't work without it.

package/src/config/core-schema.ts

@@ -124,7 +124,7 @@ export const ContextWindowConfigSchema = z.object({
     .number({ error: 'contextWindow.maxInputTokens must be a number' })
     .int('contextWindow.maxInputTokens must be an integer')
     .positive('contextWindow.maxInputTokens must be a positive integer')
-    .default(180000),
+    .default(200000),
   targetInputTokens: z
     .number({ error: 'contextWindow.targetInputTokens must be a number' })
     .int('contextWindow.targetInputTokens must be an integer')

package/src/config/env-registry.ts

@@ -124,6 +124,16 @@ export function getEnableMonitoring(): boolean {
   return flag('VELLUM_ENABLE_MONITORING');
 }
 
+/**
+ * IS_CONTAINERIZED — boolean, default: false
+ * When true, indicates the assistant is running inside a container (e.g. Docker).
+ * Any new data that needs to survive restarts must be written to BASE_DATA_DIR,
+ * which is mapped to a persistent volume.
+ */
+export function getIsContainerized(): boolean {
+  return flag('IS_CONTAINERIZED');
+}
+
 // ── Known env var names ──────────────────────────────────────────────────────
 
 /**

package/src/config/feature-flag-registry.json

@@ -0,0 +1,61 @@
+{
+  "version": 1,
+  "flags": [
+    {
+      "id": "sms",
+      "scope": "assistant",
+      "key": "feature_flags.sms.enabled",
+      "label": "SMS",
+      "description": "Show SMS setup in Settings > Connect and enable the SMS setup skill",
+      "defaultEnabled": true
+    },
+    {
+      "id": "hatch-new-assistant",
+      "scope": "assistant",
+      "key": "feature_flags.hatch-new-assistant.enabled",
+      "label": "Hatch New Assistant",
+      "description": "Show Hatch New Assistant action in Settings > Account",
+      "defaultEnabled": true
+    },
+    {
+      "id": "guardian-verify-setup",
+      "scope": "assistant",
+      "key": "feature_flags.guardian-verify-setup.enabled",
+      "label": "Guardian Verification Setup",
+      "description": "Enable guardian verification routing in the system prompt",
+      "defaultEnabled": true
+    },
+    {
+      "id": "browser",
+      "scope": "assistant",
+      "key": "feature_flags.browser.enabled",
+      "label": "Browser",
+      "description": "Enable browser skill prerequisites section in the system prompt",
+      "defaultEnabled": true
+    },
+    {
+      "id": "twitter",
+      "scope": "assistant",
+      "key": "feature_flags.twitter.enabled",
+      "label": "Twitter",
+      "description": "Enable X (Twitter) skill section in the system prompt",
+      "defaultEnabled": true
+    },
+    {
+      "id": "user-hosted-enabled",
+      "scope": "macos",
+      "key": "user_hosted_enabled",
+      "label": "User Hosted Enabled",
+      "description": "Enable user-hosted onboarding flow",
+      "defaultEnabled": false
+    },
+    {
+      "id": "local-http-enabled",
+      "scope": "macos",
+      "key": "local_http_enabled",
+      "label": "Local HTTP Enabled",
+      "description": "Enable local HTTP transport mode in macOS app",
+      "defaultEnabled": false
+    }
+  ]
+}

package/src/config/loader.ts

@@ -1,4 +1,5 @@
-import { existsSync, readFileSync, statSync,writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
 
 import { deleteSecureKey,getSecureKey, setSecureKey } from '../security/secure-keys.js';
 import { ConfigError } from '../util/errors.js';
@@ -113,6 +114,7 @@ export function loadConfig(): AssistantConfig {
     const configPath = getConfigPath();
 
     let fileConfig: Record<string, unknown> = {};
+    let configFileExisted = true;
     if (existsSync(configPath)) {
       const mode = statSync(configPath).mode;
       if (mode & 0o077) {
@@ -127,6 +129,8 @@ export function loadConfig(): AssistantConfig {
       } catch (err) {
         throw new ConfigError(`Failed to parse config at ${configPath}: ${err}`);
       }
+    } else {
+      configFileExisted = false;
     }
 
     // Pre-validate apiKeys shape before migration (must be a plain object)
@@ -182,6 +186,23 @@ export function loadConfig(): AssistantConfig {
     // Validate and apply defaults via Zod schema
     const config = validateWithSchema(fileConfig);
 
+    // If the config file didn't exist, write the full defaults to disk so
+    // users can discover and edit all available options.
+    if (!configFileExisted) {
+      try {
+        const dir = dirname(configPath);
+        if (!existsSync(dir)) {
+          mkdirSync(dir, { recursive: true });
+        }
+        // Strip apiKeys (managed in secure storage) and dataDir (runtime-derived)
+        const { apiKeys: _, dataDir: _d, ...persistable } = config;
+        writeFileSync(configPath, JSON.stringify(persistable, null, 2) + '\n');
+        log.info('Wrote default config to %s', configPath);
+      } catch (err) {
+        log.warn({ err }, 'Failed to write default config file');
+      }
+    }
+
     // Set cached before secure-key/env overrides so re-entrant calls
     // return the in-flight config instead of bare defaults.
     cached = config;