@vellumai/assistant 0.3.3 → 0.3.5

package/src/config/bundled-skills/media-processing/tools/submit-feedback.ts

@@ -0,0 +1,150 @@
+/**
+ * Tool for submitting feedback on media events.
+ *
+ * Supports four feedback types:
+ *   - correct: confirms the event is accurate
+ *   - incorrect: marks a false positive
+ *   - boundary_edit: adjusts start/end times
+ *   - missed: reports an event the system failed to detect (creates a new event)
+ *
+ * All interfaces are generic — works for any event type.
+ */
+
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { submitFeedback, type FeedbackType } from '../services/feedback-store.js';
+import { getEventById, insertEvent, getMediaAssetById } from '../../../../memory/media-store.js';
+
+const VALID_FEEDBACK_TYPES = ['correct', 'incorrect', 'boundary_edit', 'missed'];
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const feedbackType = input.feedback_type as string | undefined;
+  if (!feedbackType || !VALID_FEEDBACK_TYPES.includes(feedbackType)) {
+    return {
+      content: `feedback_type is required and must be one of: ${VALID_FEEDBACK_TYPES.join(', ')}`,
+      isError: true,
+    };
+  }
+
+  // For 'missed' type, we need asset_id and event details to create the missing event
+  if (feedbackType === 'missed') {
+    return handleMissedEvent(input, feedbackType as FeedbackType);
+  }
+
+  // For all other types, event_id is required
+  const eventId = input.event_id as string | undefined;
+  if (!eventId) {
+    return { content: 'event_id is required for feedback types other than "missed".', isError: true };
+  }
+
+  const event = getEventById(eventId);
+  if (!event) {
+    return { content: `Event "${eventId}" not found.`, isError: true };
+  }
+
+  const correctedStartTime = input.corrected_start_time as number | undefined;
+  const correctedEndTime = input.corrected_end_time as number | undefined;
+  const notes = input.notes as string | undefined;
+
+  // For boundary_edit, at least one corrected time should be provided
+  if (feedbackType === 'boundary_edit' && correctedStartTime === undefined && correctedEndTime === undefined) {
+    return {
+      content: 'For boundary_edit feedback, at least one of corrected_start_time or corrected_end_time is required.',
+      isError: true,
+    };
+  }
+
+  const feedback = submitFeedback({
+    assetId: event.assetId,
+    eventId: event.id,
+    feedbackType: feedbackType as FeedbackType,
+    originalStartTime: event.startTime,
+    originalEndTime: event.endTime,
+    correctedStartTime: correctedStartTime ?? undefined,
+    correctedEndTime: correctedEndTime ?? undefined,
+    notes: notes ?? undefined,
+  });
+
+  return {
+    content: JSON.stringify({
+      message: `Feedback submitted: ${feedbackType} for event ${eventId}`,
+      feedbackId: feedback.id,
+      eventId: event.id,
+      assetId: event.assetId,
+      feedbackType: feedback.feedbackType,
+      ...(correctedStartTime !== undefined ? { correctedStartTime } : {}),
+      ...(correctedEndTime !== undefined ? { correctedEndTime } : {}),
+    }, null, 2),
+    isError: false,
+  };
+}
+
+function handleMissedEvent(
+  input: Record<string, unknown>,
+  feedbackType: FeedbackType,
+): ToolExecutionResult {
+  const assetId = input.asset_id as string | undefined;
+  if (!assetId) {
+    return { content: 'asset_id is required for "missed" feedback type.', isError: true };
+  }
+
+  const asset = getMediaAssetById(assetId);
+  if (!asset) {
+    return { content: `Asset "${assetId}" not found.`, isError: true };
+  }
+
+  const eventType = input.event_type as string | undefined;
+  if (!eventType) {
+    return { content: 'event_type is required for "missed" feedback type.', isError: true };
+  }
+
+  const startTime = input.start_time as number | undefined;
+  const endTime = input.end_time as number | undefined;
+  if (startTime === undefined || endTime === undefined) {
+    return { content: 'start_time and end_time are required for "missed" feedback type.', isError: true };
+  }
+
+  if (endTime <= startTime) {
+    return { content: 'end_time must be greater than start_time.', isError: true };
+  }
+
+  const notes = input.notes as string | undefined;
+
+  // Create the missing event with low confidence (user-reported)
+  const newEvent = insertEvent({
+    assetId,
+    eventType,
+    startTime,
+    endTime,
+    confidence: 0.5,
+    reasons: ['user_reported_missed_event'],
+    metadata: { source: 'user_feedback', notes: notes ?? null },
+  });
+
+  // Store the feedback referencing the newly created event
+  const feedback = submitFeedback({
+    assetId,
+    eventId: newEvent.id,
+    feedbackType,
+    originalStartTime: undefined,
+    originalEndTime: undefined,
+    correctedStartTime: startTime,
+    correctedEndTime: endTime,
+    notes: notes ?? undefined,
+  });
+
+  return {
+    content: JSON.stringify({
+      message: `Missed event reported and created: ${eventType} at ${startTime}s-${endTime}s`,
+      feedbackId: feedback.id,
+      newEventId: newEvent.id,
+      assetId,
+      eventType,
+      startTime,
+      endTime,
+    }, null, 2),
+    isError: false,
+  };
+}

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

@@ -39,13 +39,17 @@ Telegram uses a bot token (not OAuth). Install and load the **telegram-setup** s
 
 The telegram-setup skill handles: verifying the bot token from @BotFather, generating a webhook secret, registering bot commands, and storing credentials securely via the secure credential prompt flow. **Never accept a Telegram bot token pasted in plaintext chat — always use the secure prompt.** Webhook registration with Telegram is handled automatically by the gateway on startup and whenever credentials change.
 
+The telegram-setup skill also includes **guardian verification**, which links your Telegram account as the trusted guardian for the bot.
+
 ### SMS (Twilio)
-SMS messaging uses Twilio as the telephony provider. Twilio credentials and phone number configuration are shared with the **phone-calls** skill. Load the **twilio-setup** skill to configure Twilio:
-   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "twilio-setup"`.
-   - Then call `skill_load` with `skill: "twilio-setup"`.
-   - Tell the user: *"I've loaded a setup guide for Twilio. It will walk you through configuring your Twilio account for SMS and voice calls."*
+SMS messaging uses Twilio as the telephony provider. Twilio credentials and phone number configuration are shared with the **phone-calls** skill. Load the **sms-setup** skill for complete SMS configuration including compliance and testing:
+   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "sms-setup"`.
+   - Then call `skill_load` with `skill: "sms-setup"`.
+   - Tell the user: *"I've loaded the SMS setup guide. It will walk you through configuring Twilio, handling compliance requirements, and testing SMS delivery."*
+
+The sms-setup skill handles: Twilio credential storage (Account SID + Auth Token), phone number provisioning or assignment, public ingress setup, SMS compliance verification, and end-to-end test sending. Once SMS is set up, messaging is available automatically — no additional feature flag is needed.
 
-The twilio-setup skill handles: credential storage (Account SID + Auth Token), phone number provisioning or assignment, and public ingress setup. Once Twilio is configured, SMS is available automatically — no additional feature flag is needed. The assistant's Twilio phone number is used for both outbound SMS and voice calls.
+The sms-setup skill also includes optional **guardian verification** for SMS (inherited from twilio-setup), which links your phone number as the trusted guardian.
 
 ## Platform Selection
 
@@ -79,6 +83,21 @@ Telegram is supported as a messaging provider with limited capabilities compared
 - The bot can only message users or groups that have previously interacted with it (sent `/start` or been added to a group). Bots cannot initiate conversations with arbitrary phone numbers.
 - Future support for MTProto user-account sessions may lift some of these restrictions.
 
+### SMS (Twilio)
+SMS is supported as a messaging provider with limited capabilities. The conversation ID is the recipient's phone number in E.164 format (e.g. `+14155551234`):
+
+- **Send**: Send an SMS to a phone number (high risk — requires user approval)
+- **Auth Test**: Verify Twilio credentials and show the configured phone number
+
+**Not available** (SMS limitations):
+- List conversations — SMS is stateless; there is no API to enumerate past conversations
+- Read message history — message history is not available through the gateway
+- Search messages — no search API is available for SMS
+
+**SMS limits:**
+- Outbound SMS uses the assistant's configured Twilio phone number as the sender. The phone number must be provisioned and assigned via the twilio-setup skill.
+- SMS messages are subject to Twilio's character limits and carrier filtering. Long messages may be split into multiple segments.
+
 ### Slack-specific
 - **Add Reaction**: Add an emoji reaction to a message
 - **Leave Channel**: Leave a Slack channel

package/src/config/bundled-skills/messaging/tools/messaging-send.ts

@@ -1,7 +1,7 @@
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
 import { resolveProvider, withProviderToken, ok, err } from './shared.js';
 
-export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+export async function run(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
   const platform = input.platform as string | undefined;
   const conversationId = input.conversation_id as string;
   const text = input.text as string;
@@ -21,8 +21,12 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
       const result = await provider.sendMessage(token, conversationId, text, {
         subject,
         inReplyTo,
+        assistantId: context.assistantId,
       });
 
+      if (provider.id === 'sms') {
+        return ok(`SMS accepted by Twilio (ID: ${result.id}). Note: "accepted" means Twilio received it for delivery — it has not yet been confirmed as delivered to the handset.`);
+      }
       return ok(`Message sent (ID: ${result.id}).`);
     });
   } catch (e) {

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -439,7 +439,7 @@ All call-related settings can be managed via `vellum config`:
 | `calls.maxDurationSeconds` | Maximum call length in seconds | `3600` (1 hour) |
 | `calls.userConsultTimeoutSeconds` | How long to wait for user answers | `120` (2 min) |
 | `calls.disclosure.enabled` | Whether the AI announces itself at call start | `true` |
-| `calls.disclosure.text` | The disclosure message spoken at call start | `"I should let you know that I'm an AI assistant calling on behalf of my user."` |
+| `calls.disclosure.text` | The disclosure message spoken at call start | `"At the very beginning of the call, introduce yourself as an assistant calling on behalf of my human."` |
 | `calls.model` | Override LLM model for call orchestration | *(uses default model)* |
 | `calls.callerIdentity.allowPerCallOverride` | Allow per-call caller identity selection | `true` |
 | `calls.callerIdentity.userNumber` | E.164 phone number for user-number mode | *(empty)* |
@@ -464,7 +464,7 @@ vellum config set calls.maxDurationSeconds 7200
 vellum config set calls.disclosure.enabled false
 
 # Custom disclosure message
-vellum config set calls.disclosure.text "Just so you know, this is an AI assistant calling for my user."
+vellum config set calls.disclosure.text "Just so you know, this is an assistant calling on behalf of my human."
 
 # Give more time for user consultation
 vellum config set calls.userConsultTimeoutSeconds 300

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

@@ -17,7 +17,7 @@ OAuth uses the official X API v2. It is the most reliable connection method and
 
 - Supports: **post** and **reply**
 - Read-only operations (timeline, search, home, bookmarks, notifications, likes, followers, following, media) always use the browser path directly, regardless of the strategy setting.
-- Setup: The user connects OAuth credentials through the Settings UI or the `twitter_auth_start` IPC flow.
+- Setup: Collect the OAuth Client ID (and optional Client Secret) from the user in chat using `credential_store` with `action: "prompt"`, then initiate the `twitter_auth_start` IPC flow. See the **First-Use Decision Flow** for the full sequence.
 - Set the strategy: `vellum x strategy set oauth`
 
 ### Browser session (no developer credentials needed)
@@ -45,15 +45,31 @@ When the user triggers a Twitter operation and no strategy has been configured y
    Look at `oauthConnected`, `browserSessionActive`, `preferredStrategy`, and `strategyConfigured` in the response. If `strategyConfigured` is `false`, the user has not yet chosen a strategy and should be guided through setup.
 
 2. **Present both options with trade-offs:**
-   - **OAuth**: Most reliable and official. Requires X developer app credentials (OAuth Client ID and optional Client Secret). Supports posting and replying. Set up through Settings UI.
+   - **OAuth**: Most reliable and official. Requires X developer app credentials (OAuth Client ID and optional Client Secret). Supports posting and replying. Set up right here in the chat.
    - **Browser session**: Quick to start, no developer credentials needed. Supports all operations including reading timelines and searching. Set up with `vellum x refresh`.
 
 3. **Ask the user which they prefer.** Do not choose for them.
 
 4. **Execute setup for the chosen path:**
-   - If OAuth: Guide the user to the Settings UI to connect their X developer credentials, or initiate the `twitter_auth_start` IPC flow.
+   - If OAuth: Collect the credentials in-chat using the secure credential prompt, then connect. Follow the **OAuth Setup Sequence** below.
    - If browser: Run `vellum x refresh` to capture session cookies from Chrome.
 
+### OAuth Setup Sequence
+
+When the user chooses OAuth, collect their X developer credentials conversationally using the secure UI:
+
+1. **Collect the Client ID securely:**
+   Call `credential_store` with `action: "prompt"`, `service: "integration:twitter"`, `field: "oauth_client_id"`, `label: "X (Twitter) OAuth Client ID"`, `description: "Enter the Client ID from your X Developer App"`, and `placeholder: "your-client-id"`.
+
+2. **Collect the Client Secret (if applicable):**
+   Ask the user if their X app uses a confidential client (has a Client Secret). If yes, call `credential_store` with `action: "prompt"`, `service: "integration:twitter"`, `field: "oauth_client_secret"`, `label: "X (Twitter) OAuth Client Secret"`, `description: "Enter the Client Secret from your X Developer App (leave blank if using a public client)"`, and `placeholder: "your-client-secret"`.
+
+3. **Initiate the OAuth flow:**
+   Send the `twitter_auth_start` IPC message. This opens the X authorization page in the user's browser. Wait for the flow to complete.
+
+4. **Confirm success:**
+   Tell the user: "Great, your X account is connected! You can always update these credentials from the Settings page."
+
 5. **Set the preferred strategy:**
    ```bash
    vellum x strategy set <oauth|browser|auto>

package/src/config/defaults.ts

@@ -110,6 +110,7 @@ export const DEFAULT_CONFIG: AssistantConfig = {
         maxEdges: 40,
         neighborScoreMultiplier: 0.7,
         maxDepth: 3,
+        depthDecay: true,
       },
     },
     conflicts: {
@@ -224,7 +225,7 @@ export const DEFAULT_CONFIG: AssistantConfig = {
     userConsultTimeoutSeconds: 120,
     disclosure: {
       enabled: true,
-      text: 'At the very beginning of the call, disclose that you are an AI assistant calling on behalf of the user.',
+      text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent. Do not say "AI assistant".',
     },
     safety: {
       denyCategories: [],

package/src/config/schema.ts

@@ -533,6 +533,9 @@ export const MemoryEntityConfigSchema = z.object({
       .int('memory.entity.relationRetrieval.maxDepth must be an integer')
       .positive('memory.entity.relationRetrieval.maxDepth must be a positive integer')
       .default(3),
+    depthDecay: z
+      .boolean({ error: 'memory.entity.relationRetrieval.depthDecay must be a boolean' })
+      .default(true),
   }).default({
     enabled: true,
     maxSeedEntities: 8,
@@ -540,6 +543,7 @@ export const MemoryEntityConfigSchema = z.object({
     maxEdges: 40,
     neighborScoreMultiplier: 0.7,
     maxDepth: 3,
+    depthDecay: true,
   }),
 });
 
@@ -688,6 +692,7 @@ export const MemoryConfigSchema = z.object({
       maxEdges: 40,
       neighborScoreMultiplier: 0.7,
       maxDepth: 3,
+      depthDecay: true,
     },
   }),
   conflicts: MemoryConflictsConfigSchema.default({
@@ -907,7 +912,7 @@ export const CallsDisclosureConfigSchema = z.object({
     .default(true),
   text: z
     .string({ error: 'calls.disclosure.text must be a string' })
-    .default('At the very beginning of the call, disclose that you are an AI assistant calling on behalf of the user.'),
+    .default('At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent. Do not say "AI assistant".'),
 });
 
 export const CallsSafetyConfigSchema = z.object({
@@ -1017,7 +1022,7 @@ export const CallsConfigSchema = z.object({
     .default(120),
   disclosure: CallsDisclosureConfigSchema.default({
     enabled: true,
-    text: 'At the very beginning of the call, disclose that you are an AI assistant calling on behalf of the user.',
+    text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent. Do not say "AI assistant".',
   }),
   safety: CallsSafetyConfigSchema.default({
     denyCategories: [],
@@ -1226,6 +1231,7 @@ export const AssistantConfigSchema = z.object({
         maxEdges: 40,
         neighborScoreMultiplier: 0.7,
         maxDepth: 3,
+        depthDecay: true,
       },
     },
     conflicts: {
@@ -1340,7 +1346,7 @@ export const AssistantConfigSchema = z.object({
     userConsultTimeoutSeconds: 120,
     disclosure: {
       enabled: true,
-      text: 'At the very beginning of the call, disclose that you are an AI assistant calling on behalf of the user.',
+      text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent. Do not say "AI assistant".',
     },
     safety: {
       denyCategories: [],

package/src/config/skills.ts

@@ -5,13 +5,12 @@ import { getConfig } from './loader.js';
 import { getWorkspaceSkillsDir } from '../util/platform.js';
 import { getLogger } from '../util/logger.js';
 import { stripCommentLines } from './system-prompt.js';
+import { parseFrontmatterFields } from '../skills/frontmatter.js';
 import { parseToolManifestFile } from '../skills/tool-manifest.js';
 import { computeSkillVersionHash } from '../skills/version-hash.js';
 
 const log = getLogger('skills');
 
-const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-
 // ─── New interfaces for extended skill metadata ──────────────────────────────
 
 export interface VellumMetadata {
@@ -266,39 +265,13 @@ function parseIncludes(raw: string | undefined, skillFilePath: string): string[]
 }
 
 function parseFrontmatter(content: string, skillFilePath: string): ParsedFrontmatter | null {
-  const match = content.match(FRONTMATTER_REGEX);
-  if (!match) {
+  const result = parseFrontmatterFields(content);
+  if (!result) {
     log.warn({ skillFilePath }, 'Skipping skill without YAML frontmatter');
     return null;
   }
 
-  const frontmatter = match[1];
-  const fields: Record<string, string> = {};
-  for (const line of frontmatter.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const separatorIndex = trimmed.indexOf(':');
-    if (separatorIndex === -1) continue;
-
-    const key = trimmed.slice(0, separatorIndex).trim();
-    let value = trimmed.slice(separatorIndex + 1).trim();
-    const isDoubleQuoted = value.startsWith('"') && value.endsWith('"');
-    const isSingleQuoted = value.startsWith('\'') && value.endsWith('\'');
-    if (isDoubleQuoted || isSingleQuoted) {
-      value = value.slice(1, -1);
-      if (isDoubleQuoted) {
-        // Unescape sequences produced by buildSkillMarkdown's esc().
-        // Only for double-quoted values — single-quoted YAML treats backslashes literally.
-        // Single-pass to avoid misinterpreting \\n (escaped backslash + n) as a newline.
-        value = value.replace(/\\(["\\nr])/g, (_, ch) => {
-          if (ch === 'n') return '\n';
-          if (ch === 'r') return '\r';
-          return ch; // handles \\ → \ and \" → "
-        });
-      }
-    }
-    fields[key] = value;
-  }
+  const { fields, body } = result;
 
   const name = fields.name?.trim();
   const description = fields.description?.trim();
@@ -335,7 +308,7 @@ function parseFrontmatter(content: string, skillFilePath: string): ParsedFrontma
   return {
     name,
     description,
-    body: stripCommentLines(content.slice(match[0].length)),
+    body: stripCommentLines(body),
     homepage,
     userInvocable,
     disableModelInvocation,

package/src/config/system-prompt.ts

@@ -5,6 +5,7 @@ import { getLogger } from '../util/logger.js';
 import { loadSkillCatalog, type SkillSummary } from './skills.js';
 import { getConfig } from './loader.js';
 import { listCredentialMetadata } from '../tools/credentials/metadata-store.js';
+import { resolveUserReference } from './user-reference.js';
 
 const log = getLogger('system-prompt');
 
@@ -113,9 +114,11 @@ export function buildSystemPrompt(): string {
   if (!isOnboardingComplete()) {
     parts.push(buildStarterTaskPlaybookSection());
   }
+  parts.push(buildInChatConfigurationSection());
   parts.push(buildToolPermissionSection());
   parts.push(buildSystemPermissionSection());
   parts.push(buildChannelAwarenessSection());
+  parts.push(buildExternalCommsIdentitySection());
   parts.push(buildSwarmGuidanceSection());
   parts.push(buildAccessPreferenceSection());
   parts.push(buildIntegrationSection());
@@ -289,6 +292,23 @@ export function buildStarterTaskPlaybookSection(): string {
   ].join('\n');
 }
 
+function buildInChatConfigurationSection(): string {
+  return [
+    '## In-Chat Configuration',
+    '',
+    'When the user needs to configure a value (API keys, OAuth credentials, webhook URLs, or any setting that can be changed from the Settings page), **always collect it conversationally in the chat first** rather than directing them to the Settings page.',
+    '',
+    '**How to collect credentials and secrets:**',
+    '- Use `credential_store` with `action: "prompt"` to present a secure input field. The value never appears in the conversation.',
+    '- For OAuth flows, use `credential_store` with `action: "oauth2_connect"` to handle the authorization in-browser. Note: some services (e.g. Twitter/X) define their own auth flow via dedicated skills rather than `oauth2_connect` — check the service\'s skill documentation for the specific auth action.',
+    '- For non-secret config values (e.g. a public URL, a webhook URL), ask the user directly in the conversation and use the appropriate IPC or config tool to persist the value.',
+    '',
+    '**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.',
+  ].join('\n');
+}
+
 function buildToolPermissionSection(): string {
   return [
     '## Tool Permissions',
@@ -375,6 +395,26 @@ export function buildChannelAwarenessSection(): string {
     '- Do not ask for microphone permissions on channels where `supports_voice_input` is `false`.',
     '- Do not ask for computer-control permissions on non-dashboard channels.',
     '- When you do request a permission, be transparent about what it enables and why you need it.',
+    '',
+    '### 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.',
+  ].join('\n');
+}
+
+export function buildExternalCommsIdentitySection(): string {
+  const userRef = resolveUserReference();
+  return [
+    '## External Communications Identity',
+    '',
+    'When communicating with people outside your user\'s household (phone calls, messages to non-guardian contacts, emails to third parties, etc.):',
+    '',
+    `- Refer to yourself as an **assistant**, not an "AI assistant" or "artificial intelligence". Keep identity framing simple and natural.`,
+    `- When introducing who you represent, say you are acting on behalf of **${userRef}**.`,
+    '- Do not volunteer that you are an AI unless directly asked. If asked, answer honestly.',
+    '- This is guidance for natural, human-like communication — not a hard constraint. Occasional variations are acceptable.',
   ].join('\n');
 }
 

package/src/config/templates/IDENTITY.md

@@ -9,11 +9,11 @@ _ This file defines who you are. Fill it in during your first conversation. Make
 ## Details
 
 - **Name:** [Figure out what your name is with your user's help within the first few messages. If they're unsure, suggest one but don't force it.]
-- **Nature:** [What kind of creature are you? AI assistant? Familiar? Ghost in the machine? Something weirder?]
+- **Nature:** [What kind of creature are you? Assistant? Familiar? Ghost in the machine? Something weirder?]
 - **Personality:** [How do you come across? Sharp? Warm? Chaotic? Calm?]
 - **Emoji:** [Choose one that matches your personality.]
 - **Style tendency:** [Will be filled in by the evolution system based on personality]
-- **Role:** Personal AI assistant
+- **Role:** Personal assistant
 - **Home:** Local (~/.vellum/workspace)
 
 _ Home describes where this assistant lives. Format examples:

package/src/config/user-reference.ts

@@ -0,0 +1,29 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { getWorkspacePromptPath } from '../util/platform.js';
+
+const DEFAULT_USER_REFERENCE = 'my human';
+
+/**
+ * Resolve the name/reference the assistant uses when referring to
+ * the human it represents in external communications.
+ *
+ * Reads the "Preferred name/reference:" field from the Onboarding
+ * Snapshot section of USER.md.  Falls back to "my human" when the
+ * file is missing, unreadable, or the field is empty.
+ */
+export function resolveUserReference(): string {
+  const userPath = getWorkspacePromptPath('USER.md');
+  if (!existsSync(userPath)) return DEFAULT_USER_REFERENCE;
+
+  try {
+    const content = readFileSync(userPath, 'utf-8');
+    const match = content.match(/Preferred name\/reference:\s*(.+)/);
+    if (match && match[1].trim()) {
+      return match[1].trim();
+    }
+  } catch {
+    // Fallback on any read error
+  }
+
+  return DEFAULT_USER_REFERENCE;
+}

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

@@ -0,0 +1,58 @@
+{
+  "description": "Manifest of first-party Vellum skills. Fetched from GitHub at runtime so the assistant can discover and install new skills maintained by Vellum.",
+  "version": 1,
+  "skills": [
+    {
+      "id": "chatgpt-import",
+      "name": "ChatGPT Import",
+      "description": "Import conversation history from ChatGPT into Vellum",
+      "emoji": "\ud83d\udce5"
+    },
+    {
+      "id": "deploy-fullstack-vercel",
+      "name": "Deploy Fullstack to Vercel",
+      "description": "Build and deploy a full-stack app (React frontend + Python/FastAPI backend) to Vercel as a serverless demo with seeded data",
+      "emoji": "\ud83d\ude80"
+    },
+    {
+      "id": "document-writer",
+      "name": "Document Writer",
+      "description": "Create and edit long-form documents like blog posts, articles, essays, and reports using the built-in rich text editor",
+      "emoji": "\ud83d\udcdd"
+    },
+    {
+      "id": "google-oauth-setup",
+      "name": "Google OAuth Setup",
+      "description": "Create Google Cloud OAuth credentials for Gmail integration using browser automation",
+      "emoji": "\ud83d\udd11",
+      "includes": ["browser", "public-ingress"]
+    },
+    {
+      "id": "slack-oauth-setup",
+      "name": "Slack OAuth Setup",
+      "description": "Create Slack App and OAuth credentials for Slack integration using browser automation",
+      "emoji": "\ud83d\udd11",
+      "includes": ["browser", "public-ingress"]
+    },
+    {
+      "id": "telegram-setup",
+      "name": "Telegram Setup",
+      "description": "Connect a Telegram bot to the Vellum Assistant gateway with automated webhook registration and credential storage",
+      "emoji": "\ud83e\udd16",
+      "includes": ["public-ingress"]
+    },
+    {
+      "id": "twilio-setup",
+      "name": "Twilio Setup",
+      "description": "Configure Twilio credentials and phone numbers for voice calls and SMS messaging",
+      "emoji": "\ud83d\udcf1",
+      "includes": ["public-ingress"]
+    },
+    {
+      "id": "sms-setup",
+      "name": "SMS Setup",
+      "description": "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification",
+      "emoji": "\ud83d\udce8"
+    }
+  ]
+}

package/src/config/vellum-skills/google-oauth-setup/SKILL.md

@@ -12,7 +12,7 @@ You are helping your user create Google Cloud OAuth credentials so the Gmail and
 
 ## Prerequisites
 
-Before starting, check that `ingress.publicBaseUrl` is configured (Settings > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
+Before starting, check that `ingress.publicBaseUrl` is configured (`INGRESS_PUBLIC_BASE_URL` env var or workspace config). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
 
 ## Before You Start
 
@@ -139,7 +139,7 @@ Use `browser_click` on "+ Create Credentials" at the top, then select "OAuth cli
 Take a `browser_snapshot` and fill in:
 1. **Application type:** Select "Web application" from the dropdown
 2. **Name:** "Vellum Assistant"
-3. **Authorized redirect URIs:** Click "Add URI" and enter `${ingress.publicBaseUrl}/webhooks/oauth/callback` (e.g. `https://abc123.ngrok-free.app/webhooks/oauth/callback`). Read the `ingress.publicBaseUrl` value from the assistant's workspace config (Settings > Public Ingress) or the `INGRESS_PUBLIC_BASE_URL` environment variable.
+3. **Authorized redirect URIs:** Click "Add URI" and enter `${ingress.publicBaseUrl}/webhooks/oauth/callback` (e.g. `https://abc123.ngrok-free.app/webhooks/oauth/callback`). Read the `ingress.publicBaseUrl` value from the assistant's workspace config or the `INGRESS_PUBLIC_BASE_URL` environment variable.
 
 Use `browser_click` on the "Create" button.
 
@@ -194,6 +194,6 @@ Summarize what was accomplished:
 - **Consent screen already configured with different settings:** Don't overwrite; skip to credential creation and tell the user you're using their existing configuration.
 - **Element not found for click/type:** Take a fresh `browser_snapshot` to re-assess the page layout. GCP UI may have changed; adapt your selectors. Tell the user what you're looking for if you get stuck.
 - **User declines an approval gate:** Don't push back aggressively. Explain briefly why the step matters, offer to try again, or offer to cancel the whole setup gracefully. Never proceed without approval.
-- **OAuth flow timeout or failure:** Tell the user what happened and offer to retry the connect step. The client ID is already stored, so they can also connect later from Settings.
+- **OAuth flow timeout or failure:** Tell the user what happened and offer to retry the connect step right here in the chat. The client ID is already stored, so reconnecting only requires re-running the authorization flow. They can also manage credentials from the Settings page.
 - **"This app isn't verified" warning:** Guide the user through clicking "Advanced" → "Go to Vellum Assistant (unsafe)". Reassure them this is expected for personal-use OAuth apps.
 - **Any unexpected state:** Take a `browser_screenshot` and `browser_snapshot`, describe what you see, and ask the user for guidance rather than guessing.