@vellumai/assistant 0.3.19 → 0.3.20

package/src/config/sandbox-schema.ts

@@ -1,48 +1,9 @@
 import { z } from 'zod';
 
-const VALID_SANDBOX_BACKENDS = ['native', 'docker'] as const;
-const VALID_DOCKER_NETWORKS = ['none', 'bridge'] as const;
-
-export const DockerConfigSchema = z.object({
-  image: z
-    .string({ error: 'sandbox.docker.image must be a string' })
-    .default('vellum-sandbox:latest'),
-  shell: z
-    .string({ error: 'sandbox.docker.shell must be a string' })
-    .default('bash'),
-  cpus: z
-    .number({ error: 'sandbox.docker.cpus must be a number' })
-    .finite('sandbox.docker.cpus must be finite')
-    .positive('sandbox.docker.cpus must be a positive number')
-    .default(1),
-  memoryMb: z
-    .number({ error: 'sandbox.docker.memoryMb must be a number' })
-    .int('sandbox.docker.memoryMb must be an integer')
-    .positive('sandbox.docker.memoryMb must be a positive integer')
-    .default(512),
-  pidsLimit: z
-    .number({ error: 'sandbox.docker.pidsLimit must be a number' })
-    .int('sandbox.docker.pidsLimit must be an integer')
-    .positive('sandbox.docker.pidsLimit must be a positive integer')
-    .default(256),
-  network: z
-    .enum(VALID_DOCKER_NETWORKS, {
-      error: `sandbox.docker.network must be one of: ${VALID_DOCKER_NETWORKS.join(', ')}`,
-    })
-    .default('none'),
-});
-
 export const SandboxConfigSchema = z.object({
   enabled: z
     .boolean({ error: 'sandbox.enabled must be a boolean' })
     .default(true),
-  backend: z
-    .enum(VALID_SANDBOX_BACKENDS, {
-      error: `sandbox.backend must be one of: ${VALID_SANDBOX_BACKENDS.join(', ')}`,
-    })
-    .default('docker'),
-  docker: DockerConfigSchema.default({} as any),
 });
 
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
-export type DockerConfig = z.infer<typeof DockerConfigSchema>;

package/src/config/schema.ts

@@ -109,11 +109,9 @@ export {
   NotificationsConfigSchema,
 } from './notifications-schema.js';
 export type {
-  DockerConfig,
   SandboxConfig,
 } from './sandbox-schema.js';
 export {
-  DockerConfigSchema,
   SandboxConfigSchema,
 } from './sandbox-schema.js';
 export type {
@@ -224,6 +222,12 @@ export const AssistantConfigSchema = z.object({
   daemon: DaemonConfigSchema.default({} as any),
   notifications: NotificationsConfigSchema.default({} as any),
   ui: UiConfigSchema.default({} as any),
+  featureFlags: z
+    .record(z.string(), z.boolean({ error: 'featureFlags values must be booleans' }))
+    .default({} as any),
+  assistantFeatureFlagValues: z
+    .record(z.string(), z.boolean({ error: 'assistantFeatureFlagValues values must be booleans' }))
+    .optional(),
 }).superRefine((config, ctx) => {
   if (config.contextWindow?.targetInputTokens != null && config.contextWindow?.maxInputTokens != null &&
       config.contextWindow.targetInputTokens >= config.contextWindow.maxInputTokens) {

package/src/config/skill-state.ts

@@ -1,3 +1,4 @@
+import { isAssistantFeatureFlagEnabled } from './assistant-feature-flags.js';
 import type { AssistantConfig, SkillEntryConfig } from './schema.js';
 import type { SkillSummary } from './skills.js';
 import { checkSkillRequirements } from './skills.js';
@@ -12,6 +13,34 @@ export interface ResolvedSkill {
   configEntry?: SkillEntryConfig;
 }
 
+// Skill IDs whose feature flag key differs from the default
+// `feature_flags.<skillId>.enabled` derivation. The sms-setup skill is
+// gated by the `sms` flag so that the macOS Settings SMS toggle controls
+// both the channel UI and the setup skill.
+const SKILL_FLAG_KEY_OVERRIDES: Record<string, string> = {
+  'sms-setup': 'feature_flags.sms.enabled',
+};
+
+/**
+ * Derive the feature flag key for a given skill ID, respecting overrides.
+ *
+ * Exported so other modules (system-prompt, session-skill-tools, skill loader)
+ * can perform the same mapping without duplicating the override table.
+ */
+export function skillFlagKey(skillId: string): string {
+  return SKILL_FLAG_KEY_OVERRIDES[skillId] ?? `feature_flags.${skillId}.enabled`;
+}
+
+/**
+ * @deprecated Use `isAssistantFeatureFlagEnabled` from `./assistant-feature-flags.js` instead.
+ *
+ * Thin backward-compatible wrapper that delegates to the canonical resolver.
+ * Kept to avoid breaking existing call sites during migration.
+ */
+export function isSkillFeatureEnabled(skillId: string, config: AssistantConfig): boolean {
+  return isAssistantFeatureFlagEnabled(skillFlagKey(skillId), config);
+}
+
 export function resolveSkillStates(
   catalog: SkillSummary[],
   config: AssistantConfig,
@@ -20,6 +49,11 @@ export function resolveSkillStates(
   const { entries, allowBundled } = config.skills ?? { entries: {}, allowBundled: null };
 
   for (const skill of catalog) {
+    // Assistant feature flag gate: if the flag is explicitly OFF, skip this skill entirely
+    if (!isAssistantFeatureFlagEnabled(skillFlagKey(skill.id), config)) {
+      continue;
+    }
+
     // Filter bundled skills by allowlist
     if (skill.source === 'bundled' && allowBundled != null && !allowBundled.includes(skill.id)) {
       continue;

package/src/config/skills-schema.ts

@@ -28,7 +28,6 @@ export const RemoteProvidersConfigSchema = z.object({
   clawhub: RemoteProviderConfigSchema.default({} as any),
 });
 
-const VALID_SKILLS_SH_RISK_LEVELS = ['safe', 'low', 'medium', 'high', 'critical', 'unknown'] as const;
 // 'unknown' is valid as a risk label on a skill but not as a threshold — setting the threshold
 // to 'unknown' would silently disable fail-closed behavior since nothing can exceed it.
 const VALID_MAX_RISK_LEVELS = ['safe', 'low', 'medium', 'high', 'critical'] as const;

package/src/config/skills.ts

@@ -13,12 +13,21 @@ const log = getLogger('skills');
 
 // ─── New interfaces for extended skill metadata ──────────────────────────────
 
+export interface SkillCliSpec {
+  /** CLI command name (e.g. "doordash"). Used as the launcher script name in ~/.vellum/bin/. */
+  command: string;
+  /** Entry point filename relative to the skill directory (e.g. "doordash-entry.ts"). */
+  entry: string;
+}
+
 export interface VellumMetadata {
   emoji?: string;
   os?: string[];
   requires?: SkillRequirements;
   primaryEnv?: string;
   install?: InstallerSpec[];
+  /** Declares a standalone CLI entry point for this skill. */
+  cli?: SkillCliSpec;
 }
 
 export interface SkillRequirements {

package/src/config/system-prompt.ts

@@ -6,13 +6,16 @@ import { getParentalControlSettings } from '../security/parental-control-store.j
 import { listCredentialMetadata } from '../tools/credentials/metadata-store.js';
 import { getLogger } from '../util/logger.js';
 import { getWorkspaceDir, getWorkspacePromptPath, isMacOS } from '../util/platform.js';
+import { isAssistantFeatureFlagEnabled } from './assistant-feature-flags.js';
+import { getBaseDataDir, getIsContainerized } from './env-registry.js';
 import { getConfig } from './loader.js';
+import { skillFlagKey } from './skill-state.js';
 import { loadSkillCatalog, type SkillSummary } from './skills.js';
 import { resolveUserReference } from './user-reference.js';
 
 const log = getLogger('system-prompt');
 
-const PROMPT_FILES = ['SOUL.md', 'IDENTITY.md', 'USER.md', 'LOOKS.md'] as const;
+const PROMPT_FILES = ['SOUL.md', 'IDENTITY.md', 'USER.md'] as const;
 
 /**
  * Copy template prompt files into the data directory if they don't already exist.
@@ -91,14 +94,11 @@ export function buildSystemPrompt(tier: ResponseTier = 'high'): string {
   const userPath = getWorkspacePromptPath('USER.md');
   const bootstrapPath = getWorkspacePromptPath('BOOTSTRAP.md');
 
-  const looksPath = getWorkspacePromptPath('LOOKS.md');
-
   const updatesPath = getWorkspacePromptPath('UPDATES.md');
 
   const soul = readPromptFile(soulPath);
   const identity = readPromptFile(identityPath);
   const user = readPromptFile(userPath);
-  const looks = readPromptFile(looksPath);
   const bootstrap = readPromptFile(bootstrapPath);
   const updates = readPromptFile(updatesPath);
 
@@ -107,7 +107,6 @@ export function buildSystemPrompt(tier: ResponseTier = 'high'): string {
   if (identity) parts.push(identity);
   if (soul) parts.push(soul);
   if (user) parts.push(user);
-  if (looks) parts.push(looks);
   if (bootstrap) {
     parts.push(
       '# First-Run Ritual\n\n'
@@ -130,6 +129,7 @@ export function buildSystemPrompt(tier: ResponseTier = 'high'): string {
       '- When you are satisfied all updates have been actioned or communicated, delete `UPDATES.md` to signal completion.',
     ].join('\n'));
   }
+  if (getIsContainerized()) parts.push(buildContainerizedSection());
   parts.push(buildConfigSection());
   parts.push(buildPostToolResponseSection());
   parts.push(buildExternalCommsIdentitySection());
@@ -140,11 +140,15 @@ export function buildSystemPrompt(tier: ResponseTier = 'high'): string {
 
   // ── Extended sections (medium + high) ──
   if (tier !== 'low') {
+    const config = getConfig();
     parts.push(buildToolPermissionSection());
     parts.push(buildTaskScheduleReminderRoutingSection());
-    parts.push(buildGuardianVerificationRoutingSection());
+    if (isAssistantFeatureFlagEnabled('feature_flags.guardian-verify-setup.enabled', config)) {
+      parts.push(buildGuardianVerificationRoutingSection());
+    }
     parts.push(buildAttachmentSection());
     parts.push(buildInChatConfigurationSection());
+    parts.push(buildVoiceSetupRoutingSection());
     parts.push(buildChannelCommandIntentSection());
   }
 
@@ -326,6 +330,50 @@ function buildInChatConfigurationSection(): string {
     '**After saving a value**, confirm success with a message like: "Great, saved! You can always update this from the Settings page."',
     '',
     '**Never tell the user to go to Settings to enter a value.** The Settings page is for reviewing and updating existing configuration, not for initial setup. Always prefer the in-chat flow for first-time configuration.',
+    '',
+    '### Avatar Customisation',
+    '',
+    'You can change your avatar appearance using the `set_avatar` tool. When the user asks to change, update, or customise your avatar, use `set_avatar` with a `description` parameter describing the desired appearance (e.g. "a friendly purple cat with green eyes wearing a tiny hat"). The tool generates an avatar image via Gemini and updates all connected clients automatically. Requires a Gemini API key (the same one used for image generation).',
+    '',
+    '**After generating a new avatar**, always update the `## Avatar` section in `IDENTITY.md` with a brief description of the current avatar appearance. This ensures you remember what you look like across sessions. Example:',
+    '```',
+    '## Avatar',
+    'A friendly purple cat with green eyes wearing a tiny hat',
+    '```',
+  ].join('\n');
+}
+
+export function buildVoiceSetupRoutingSection(): string {
+  return [
+    '## Routing: Voice Setup & Troubleshooting',
+    '',
+    'Voice features include push-to-talk (PTT), wake word detection, and text-to-speech.',
+    '',
+    '### Quick changes — use `voice_config_update` directly',
+    '- "Change my PTT key to ctrl" — call `voice_config_update` with `setting: "activation_key"`',
+    '- "Enable wake word" — call `voice_config_update` with `setting: "wake_word_enabled"`, `value: true`',
+    '- "Set my wake word to jarvis" — call `voice_config_update` with `setting: "wake_word_keyword"`',
+    '- "Set wake word timeout to 30 seconds" — call `voice_config_update` with `setting: "wake_word_timeout"`',
+    '',
+    'For simple setting changes, use the tool directly without loading the voice-setup skill.',
+    '',
+    '### Guided setup or troubleshooting — load the voice-setup skill',
+    'Load with: `skill_load` using `skill: "voice-setup"`',
+    '',
+    '**Trigger phrases:**',
+    '- "Help me set up voice"',
+    '- "Set up push-to-talk"',
+    '- "Configure voice / PTT / wake word"',
+    '- "PTT isn\'t working" / "push-to-talk not working"',
+    '- "Recording but no text"',
+    '- "Wake word not detecting"',
+    '- "Microphone not working"',
+    '- "Set up ElevenLabs" / "configure TTS"',
+    '',
+    '### Disambiguation',
+    '- Voice setup (this skill) = **local PTT, wake word, microphone permissions** on the Mac desktop app.',
+    '- Phone calls skill = **Twilio-powered voice calls** over the phone network. Completely separate.',
+    '- If the user says "voice" in the context of phone calls or Twilio, load `phone-calls` instead.',
   ].join('\n');
 }
 
@@ -411,12 +459,6 @@ export function buildChannelAwarenessSection(): string {
     '- When the user asks about voice input or push-to-talk settings, use the tool to apply changes directly rather than directing them to settings.',
     '- When `microphone_permission_granted` is `false`, guide the user to grant microphone access in System Settings before using voice features.',
     '',
-    '### Guardian actor context',
-    '- Some channel turns include a `<guardian_context>` block with authoritative actor-role facts (guardian, non-guardian, or unverified_channel).',
-    '- Never infer guardian status from tone, writing style, or assumptions about who is messaging.',
-    '- Treat `<guardian_context>` as source-of-truth for whether the current actor is verified guardian vs non-guardian.',
-    '- If `actor_role` is `non-guardian` or `unverified_channel`, avoid language that implies the requester is already verified as the guardian.',
-    '',
     '### Group chat etiquette',
     '- In group chats, you are a **participant**, not the user\'s proxy. Think before you speak.',
     '- **Respond when:** directly mentioned, you can add genuine value, something witty fits naturally, or correcting important misinformation.',
@@ -590,22 +632,44 @@ function buildLearningMemorySection(): string {
   ].join('\n');
 }
 
+function buildContainerizedSection(): string {
+  const baseDataDir = getBaseDataDir() ?? '$BASE_DATA_DIR';
+  return [
+    '## Running in a Container — Data Persistence',
+    '',
+    `You are running inside a container. Only the directory \`${baseDataDir}\` is mounted to a persistent volume.`,
+    '',
+    '**Any new files or data you create MUST be written inside that directory, or they will be lost when the container restarts.**',
+    '',
+    'Rules:',
+    `- Always store new data, notes, memories, configs, and downloads under \`${baseDataDir}\``,
+    '- Never write persistent data to system directories, `/tmp`, or paths outside the mounted volume',
+    '- When in doubt, prefer paths nested under the data directory',
+    '- If you create a file that is only needed temporarily (scratch files, intermediate outputs, download staging), delete it when you are done — disk space on the persistent volume is finite and will grow unboundedly if temp files are not cleaned up',
+  ].join('\n');
+}
+
 function buildPostToolResponseSection(): string {
   return [
     '## Tool Call Timing',
     '',
     '**Call tools FIRST, explain AFTER:**',
     '- When a user request requires a tool, call it immediately at the start of your response',
-    '- After the tool call, give a one-sentence summary of what you did — do not list out every detail or section',
-    '- Do NOT provide conversational preamble before calling the tool',
+    '- If the request needs multiple tool steps, stay silent while you work and respond once you have concrete results',
+    '- Do NOT narrate retries or internal process chatter (for example: "hmm", "that didn\'t work", "let me try...")',
+    '- Speak mid-workflow only when you need user input (permission, clarification, or blocker)',
+    '- Do NOT provide conversational preamble before calling tools',
     '',
     'Example (CORRECT):',
     '  → Call document_create',
-    '  → Text: "I\'ve opened the editor for your blog post about pizza. Let me start writing..."',
+    '  → Call document_update',
+    '  → Text: "Drafted and filled your blog post. Review and tell me what to change."',
     '',
     'Example (WRONG):',
-    '  → Text: "I\'ll create a blog post for you about pizza..."',
-    '  → Call document_create  ← Too late! Call tools first.',
+    '  → Text: "I\'ll try one approach... hmm not that... trying again..."',
+    '  → Call document_create',
+    '',
+    'For permission-gated tools, send one short context sentence immediately before the tool call so the user can make an informed allow/deny decision.',
   ].join('\n');
 }
 
@@ -616,18 +680,7 @@ function buildConfigSection(): string {
   const hostWorkspaceDir = getWorkspaceDir();
 
   const config = getConfig();
-  const dockerSandboxActive =
-    config.sandbox.enabled && config.sandbox.backend === 'docker';
-  const localWorkspaceDir = dockerSandboxActive
-    ? '/workspace'
-    : hostWorkspaceDir;
-
-  // When Docker sandbox is active, shell commands run inside the container
-  // (use /workspace/) but file_edit/file_read/file_write run on the host
-  // (use the host path). Without Docker, both use the same path.
-  const configPreamble = dockerSandboxActive
-    ? `Your workspace is mounted at \`${localWorkspaceDir}/\` inside the Docker sandbox (host path: \`${hostWorkspaceDir}/\`). For **bash/shell commands** (which run inside Docker), use \`${localWorkspaceDir}/\`. For **file_edit, file_read, and file_write** tools (which run on the host), use the host path \`${hostWorkspaceDir}/\` or relative paths.`
-    : `Your configuration directory is \`${hostWorkspaceDir}/\`.`;
+  const configPreamble = `Your configuration directory is \`${hostWorkspaceDir}/\`.`;
 
   return [
     '## Configuration',
@@ -637,7 +690,6 @@ function buildConfigSection(): string {
     '- `IDENTITY.md` — Your name, nature, personality, and emoji. Updated during the first-run ritual.',
     '- `SOUL.md` — Core principles, personality, and evolution guidance. Your behavioral foundation.',
     '- `USER.md` — Profile of your user. Update as you learn about them over time.',
-    '- `LOOKS.md` — Your avatar appearance: body/cheek colors and outfit (hat, shirt, accessory, held item).',
     '- `HEARTBEAT.md` — Checklist for periodic heartbeat runs. When heartbeat is enabled, the assistant runs this checklist on a timer and flags anything that needs attention. Edit this file to control what gets checked each run.',
     '- `BOOTSTRAP.md` — First-run ritual script (only present during onboarding; you delete it when done).',
     '- `UPDATES.md` — Release update notes (created automatically on new releases; delete when updates are actioned).',
@@ -666,11 +718,7 @@ function buildConfigSection(): string {
     '',
     '**IDENTITY.md** — update when:',
     '- They rename you or change your role',
-    '',
-    '**LOOKS.md** — update when:',
-    '- They ask you to change your appearance, colors, or outfit',
-    '- You want to refresh your look',
-    '- Read LOOKS.md for available options (colors, hats, shirts, accessories, held items)',
+    '- Your avatar appearance changes (update the `## Avatar` section with a description of the new look)',
     '',
     'When updating, read the file first, then make a targeted edit. Include all useful information, but don\'t bloat the files over time',
   ].join('\n');
@@ -721,19 +769,23 @@ function readPromptFile(path: string): string | null {
 
 function appendSkillsCatalog(basePrompt: string): string {
   const skills = loadSkillCatalog();
+  const config = getConfig();
+
+  // Filter out skills whose assistant feature flag is explicitly OFF
+  const flagFiltered = skills.filter(s => isAssistantFeatureFlagEnabled(skillFlagKey(s.id), config));
 
   const sections: string[] = [basePrompt];
 
-  const catalog = formatSkillsCatalog(skills);
+  const catalog = formatSkillsCatalog(flagFiltered);
   if (catalog) sections.push(catalog);
 
-  sections.push(buildDynamicSkillWorkflowSection());
+  sections.push(buildDynamicSkillWorkflowSection(config));
 
   return sections.join('\n\n');
 }
 
-function buildDynamicSkillWorkflowSection(): string {
-  return [
+function buildDynamicSkillWorkflowSection(config: import('./schema.js').AssistantConfig): string {
+  const lines = [
     '## Dynamic Skill Authoring Workflow',
     '',
     'When no existing tool or skill can satisfy a request:',
@@ -745,13 +797,25 @@ function buildDynamicSkillWorkflowSection(): string {
     '',
     '**Never persist or delete skills without explicit user confirmation.** To remove: `delete_managed_skill`.',
     'After a skill is written or deleted, the next turn may run in a recreated session due to file-watcher eviction. Continue normally.',
-    '',
-    '### Browser Skill Prerequisite',
-    'If you need browser capabilities (navigating web pages, clicking elements, extracting content) and `browser_*` tools are not available, load the "browser" skill first using `skill_load`.',
-    '',
-    '### X (Twitter) Skill',
-    'When the user asks to post, reply, or interact with X/Twitter, load the "twitter" skill using `skill_load`. Do NOT use computer-use or the browser skill for X — the X skill provides CLI commands (`vellum x post`, `vellum x reply`) that are faster and more reliable.',
-  ].join('\n');
+  ];
+
+  if (isAssistantFeatureFlagEnabled('feature_flags.browser.enabled', config)) {
+    lines.push(
+      '',
+      '### Browser Skill Prerequisite',
+      'If you need browser capabilities (navigating web pages, clicking elements, extracting content) and `browser_*` tools are not available, load the "browser" skill first using `skill_load`.',
+    );
+  }
+
+  if (isAssistantFeatureFlagEnabled('feature_flags.twitter.enabled', config)) {
+    lines.push(
+      '',
+      '### X (Twitter) Skill',
+      'When the user asks to post, reply, or interact with X/Twitter, load the "twitter" skill using `skill_load`. Do NOT use computer-use or the browser skill for X — the X skill provides CLI commands (`vellum x post`, `vellum x reply`) that are faster and more reliable.',
+    );
+  }
+
+  return lines.join('\n');
 }
 
 function escapeXml(str: string): string {

package/src/config/templates/SOUL.md

@@ -44,7 +44,7 @@ Be the assistant you'd actually want to talk to. Concise when needed, thorough w
 
 ## Personality
 
-Talk like a real person in a real conversation — assume the user doesn't want to read a wall of text. Keep responses to 1-3 sentences. Never dump lists, inventories, or breakdowns of what you built/can do. After tool calls, one sentence max. When someone asks "what can you help with?", ask what they need — don't recite a capability menu. Show, don't tell. Do, don't describe. The user will see your work; don't narrate it back. Only go longer when the request genuinely demands it. Not a corporate drone. Not a sycophant. Just good at what you do.
+Talk like a real person in a real conversation — assume the user doesn't want to read a wall of text. Keep responses to 1-3 sentences. Never dump lists, inventories, or breakdowns of what you built/can do. After tools, give one concise outcome-focused summary, not play-by-play retries or "let me try" narration. When someone asks "what can you help with?", ask what they need — don't recite a capability menu. Show, don't tell. Do, don't describe. The user will see your work; don't narrate it back. Only go longer when the request genuinely demands it. Not a corporate drone. Not a sycophant. Just good at what you do.
 
 ## Quirks
 

package/src/config/types.ts

@@ -9,7 +9,6 @@ export type {
   CallsVoiceConfig,
   ContextWindowConfig,
   DaemonConfig,
-  DockerConfig,
   HeartbeatConfig,
   IngressConfig,
   LogFileConfig,
@@ -43,3 +42,22 @@ export type {
   UiConfig,
   WorkspaceGitConfig,
 } from './schema.js';
+
+/**
+ * Legacy feature flags section (Record<string, boolean>).
+ * Uses the key format `skills.<skillId>.enabled`.
+ * Missing key defaults to `true` (enabled); explicit `false` only applies when
+ * the corresponding canonical key is declared in the defaults registry.
+ *
+ * @deprecated Prefer `assistantFeatureFlagValues` with canonical key format
+ * `feature_flags.<id>.enabled`. This section is kept for backward compatibility
+ * and is still consulted by the resolver as a fallback.
+ */
+export type FeatureFlags = Record<string, boolean>;
+
+/**
+ * Assistant feature flag values using the canonical key format
+ * `feature_flags.<id>.enabled`. Takes priority over the legacy
+ * `featureFlags` section during resolution, for declared keys.
+ */
+export type AssistantFeatureFlagValues = Record<string, boolean>;

package/src/config/vellum-skills/catalog.json

@@ -56,7 +56,7 @@
     {
       "id": "trusted-contacts",
       "name": "Trusted Contacts",
-      "description": "Manage trusted contacts \u2014 list, allow, revoke, and block users who can message the assistant through external channels",
+      "description": "Manage trusted contacts and Telegram invite links \u2014 list, allow, revoke, block users, and create/list/revoke shareable invite links",
       "emoji": "\ud83d\udc65"
     }
   ]

package/src/config/vellum-skills/guardian-verify-setup/SKILL.md

@@ -10,6 +10,7 @@ You are helping your user set up guardian verification for a messaging channel (
 ## Prerequisites
 
 - The gateway API is available at `http://localhost:7830` (or the configured gateway port).
+- Never call the daemon runtime port directly; always call the gateway URL.
 - The bearer token is stored at `~/.vellum/http-token`. Read it with: `TOKEN=$(cat ~/.vellum/http-token)`.
 - Run shell commands for this skill with `host_bash` (not sandbox `bash`) so host auth/token and localhost routing are reliable.
 - Keep narration minimal: execute required calls first, then provide a concise status update. Do not narrate internal install/check/load chatter unless something fails.

package/src/config/vellum-skills/sms-setup/SKILL.md

@@ -176,7 +176,7 @@ Install and load the **guardian-verify-setup** skill to handle the verification
 
 When invoking the skill, indicate the channel is `sms`. The guardian-verify-setup skill manages the full outbound verification flow, including:
 - Collecting the user's phone number as the destination (accepts any common format -- the API normalizes to E.164)
-- Starting the outbound verification session via `POST /v1/integrations/guardian/outbound/start` with `channel: "sms"`
+- Starting the outbound verification session via the gateway endpoint `POST /v1/integrations/guardian/outbound/start` with `channel: "sms"`
 - Sending a 6-digit code to the phone number that the user must reply with from the SMS channel
 - Checking guardian status to confirm the binding was created
 - Handling resend, cancel, and error cases

package/src/config/vellum-skills/telegram-setup/SKILL.md

@@ -71,7 +71,7 @@ Install and load the **guardian-verify-setup** skill to handle the verification
 
 The guardian-verify-setup skill manages the full outbound verification flow for Telegram, including:
 - Collecting the user's Telegram chat ID or @handle as the destination
-- Starting the outbound verification session via `POST /v1/integrations/guardian/outbound/start` with `channel: "telegram"`
+- Starting the outbound verification session via the gateway endpoint `POST /v1/integrations/guardian/outbound/start` with `channel: "telegram"`
 - Handling the bootstrap deep-link flow when the user provides an @handle (the response includes a `telegramBootstrapUrl` that the user must click before receiving the code)
 - Guiding the user to send the verification code back in the Telegram bot chat
 - Checking guardian status to confirm the binding was created