@vellumai/assistant 0.3.19 → 0.3.21

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

@@ -12,8 +12,9 @@ You are helping your user connect a Telegram bot to the Vellum Assistant gateway
 
 Before beginning setup, verify these conditions are met:
 
-1. **Gateway is running:** Run `curl -sf http://localhost:7830/healthz` — it should return OK. If it fails, tell the user to start the daemon with `vellum daemon start` and wait for it to become healthy before continuing.
+1. **Gateway API base URL is set and reachable:** Use the configured gateway URL in `GATEWAY_BASE_URL` (from Settings "Local Gateway Target"), then run `curl -sf "$GATEWAY_BASE_URL/healthz"` — it should return gateway health JSON (for example `{"status":"ok"}`). If it fails, tell the user to start the daemon with `vellum daemon start` and wait for it to become healthy before continuing.
 2. **Public ingress URL is configured.** The gateway webhook URL is derived from `${ingress.publicBaseUrl}/webhooks/telegram`. If the ingress URL is not configured, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the URL before continuing.
+3. **Use gateway control-plane routes only.** Telegram setup/config actions in this skill must call gateway endpoints under `/v1/integrations/telegram/*` — never call the daemon runtime port directly.
 
 ## What You Need
 
@@ -36,7 +37,7 @@ The token is collected securely via a system-level prompt and is never exposed i
 After the token is collected, call the composite setup endpoint which validates the token, stores credentials, and registers bot commands in a single request:
 
 ```bash
-curl -sf -X POST http://localhost:7830/v1/integrations/telegram/setup \
+curl -sf -X POST "$GATEWAY_BASE_URL/v1/integrations/telegram/setup" \
   -H "Authorization: Bearer $(cat ~/.vellum/http-token)" \
   -H "Content-Type: application/json" \
   -d '{}'
@@ -71,7 +72,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
@@ -97,7 +98,7 @@ If routing is misconfigured, inbound Telegram messages will be rejected and the
 Before reporting success, confirm the guardian binding was actually created. Check the guardian binding status:
 
 ```bash
-curl -sf http://localhost:7830/v1/integrations/guardian/status?channel=telegram \
+curl -sf "$GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=telegram" \
   -H "Authorization: Bearer $(cat ~/.vellum/http-token)"
 ```
 
@@ -116,7 +117,7 @@ Summarize what was done:
 - Guardian identity: {verified | not configured}
 - Guardian verification status: {verified via outbound flow | skipped}
 - Routing configuration validated
-- To re-check guardian status later, use: `curl -sf http://localhost:7830/v1/integrations/guardian/status?channel=telegram -H "Authorization: Bearer $(cat ~/.vellum/http-token)"`
+- To re-check guardian status later, use: `curl -sf "$GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=telegram" -H "Authorization: Bearer $(cat ~/.vellum/http-token)"`
 
 The gateway automatically detects credentials from the vault, reconciles the Telegram webhook registration, and begins accepting Telegram webhooks shortly. In single-assistant mode, routing is automatically configured — no manual environment variable configuration or webhook registration is needed. If the webhook secret changes later, the gateway's credential watcher will automatically re-register the webhook. If the ingress URL changes (e.g., tunnel restart), the assistant daemon triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
 

package/src/config/vellum-skills/trusted-contacts/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: "Trusted Contacts"
-description: "Manage trusted contacts — list, allow, revoke, and block users who can message the assistant through external channels"
+description: "Manage trusted contacts and Telegram invite links — list, allow, revoke, block users, and create/list/revoke invite links for external channels"
 user-invocable: true
 metadata: {"vellum": {"emoji": "\ud83d\udc65"}}
 ---
 
-You are helping your user manage trusted contacts for the Vellum Assistant. Trusted contacts control who is allowed to send messages to the assistant through external channels like Telegram and SMS. All operations go through the gateway HTTP API using `curl` with bearer auth.
+You are helping your user manage trusted contacts and invite links for the Vellum Assistant. Trusted contacts control who is allowed to send messages to the assistant through external channels like Telegram and SMS. Invite links let the guardian share a Telegram deep link that automatically grants access when opened. All operations go through the gateway HTTP API using `curl` with bearer auth.
 
 ## Prerequisites
 
 - The gateway API is available at `http://localhost:7830` (or the configured gateway port).
+- Use gateway control-plane routes only: this skill calls `/v1/ingress/*` and `/v1/integrations/telegram/config` on the gateway, never the daemon runtime port directly.
 - The bearer token is stored at `~/.vellum/http-token`. Read it with: `TOKEN=$(cat ~/.vellum/http-token)`.
 
 ## Concepts
@@ -18,6 +19,7 @@ You are helping your user manage trusted contacts for the Vellum Assistant. Trus
 - **Policy**: Controls what the member can do — `allow` (can message freely) or `deny` (blocked from messaging).
 - **Status**: The member's lifecycle state — `active` (currently effective), `revoked` (access removed), or `blocked` (explicitly denied).
 - **Source channel**: The messaging platform the contact uses (e.g., `telegram`, `sms`).
+- **Invite link**: A shareable Telegram deep link that, when opened by someone, automatically grants them trusted-contact access. Each invite has a token, usage limits, and optional expiration.
 
 ## Available Actions
 
@@ -117,9 +119,101 @@ curl -s -X POST "http://localhost:7830/v1/ingress/members/<member_id>/block" \
   -d '{"reason": "<optional reason>"}'
 ```
 
+### 5. Create a Telegram invite link
+
+Use this when the guardian wants to invite someone to message the assistant on Telegram without needing their user ID upfront. The invite link is a shareable Telegram deep link — when someone opens it, they automatically get trusted-contact access.
+
+```bash
+TOKEN=$(cat ~/.vellum/http-token)
+curl -s -X POST http://localhost:7830/v1/ingress/invites \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{
+    "sourceChannel": "telegram",
+    "maxUses": 1,
+    "note": "<optional note, e.g. the person it is for>"
+  }'
+```
+
+Optional fields:
+- `maxUses` — how many times the link can be used (default: 1). Use a higher number for group invites.
+- `expiresInMs` — expiration time in milliseconds from now (e.g., `86400000` for 24 hours). Defaults to 7 days (`604800000`) if omitted.
+- `note` — a human-readable label for the invite (e.g., "For Mom", "Family group").
+
+The response contains `{ ok: true, invite: { id, token, ... } }`. The `token` field is the raw invite token — it is only returned at creation time and cannot be retrieved later.
+
+**Building the shareable link**: After creating the invite, look up the Telegram bot username so you can build the deep link. Query the Telegram integration config:
+
+```bash
+TOKEN=$(cat ~/.vellum/http-token)
+curl -s http://localhost:7830/v1/integrations/telegram/config \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+The response includes `botUsername`. Use it to construct the deep link:
+
+```
+https://t.me/<botUsername>?start=iv_<token>
+```
+
+**Presenting to the guardian**: Give the guardian the link with clear copy-paste instructions:
+
+> Here's your Telegram invite link:
+>
+> `https://t.me/<botUsername>?start=iv_<token>`
+>
+> Share this link with the person you want to invite. When they open it in Telegram and press "Start", they'll automatically be added as a trusted contact and can message the assistant directly.
+>
+> This link can be used <maxUses> time(s)<and expires in X hours/days if applicable>.
+
+If the Telegram bot username is not available (integration not set up), tell the guardian they need to set up the Telegram integration first using the Telegram Setup skill.
+
+### 6. List invite links
+
+Use this to show the guardian their active (and optionally all) invite links.
+
+```bash
+TOKEN=$(cat ~/.vellum/http-token)
+curl -s "http://localhost:7830/v1/ingress/invites?sourceChannel=telegram" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Optional query parameters:
+- `sourceChannel` — filter by channel (e.g., `telegram`)
+- `status` — filter by status (`active`, `revoked`, `redeemed`, `expired`)
+
+The response contains `{ ok: true, invites: [...] }` where each invite has:
+- `id` — unique invite ID (needed for revoke)
+- `sourceChannel` — the channel
+- `tokenHash` — hashed token (the raw token is only available at creation time)
+- `maxUses` — total allowed uses
+- `useCount` — how many times it has been redeemed
+- `expiresAt` — expiration timestamp (null if no expiration)
+- `status` — current status (`active`, `revoked`, `redeemed`, `expired`)
+- `note` — the label set at creation
+- `createdAt` — when the invite was created
+
+**Presenting results**: Format as a readable list. Show the note (or "unnamed" as fallback), status, uses remaining (`maxUses - useCount`), and expiration. Highlight active invites and note which ones have been fully used or expired.
+
+### 7. Revoke an invite link
+
+Use this when the guardian wants to cancel an active invite link. **Always confirm before revoking.**
+
+Ask the user: *"I'll revoke the invite link [note or ID]. It will no longer be usable. Should I proceed?"*
+
+First, list invites to find the invite's `id`, then revoke:
+
+```bash
+TOKEN=$(cat ~/.vellum/http-token)
+curl -s -X DELETE "http://localhost:7830/v1/ingress/invites/<invite_id>" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Replace `<invite_id>` with the invite's `id` from the list response.
+
 ## Confirmation Requirements
 
-**All mutating actions (allow, revoke, block) require explicit user confirmation before execution.** This is a safety measure — modifying who can access the assistant should always be a deliberate choice.
+**All mutating actions (allow, revoke, block, revoke invite) require explicit user confirmation before execution.** This is a safety measure — modifying who can access the assistant should always be a deliberate choice. Creating an invite link does not require confirmation since it does not grant access until someone opens it.
 
 - Clearly state what action you are about to take and who it affects.
 - Wait for the user to confirm before running the curl command.
@@ -133,6 +227,8 @@ curl -s -X POST "http://localhost:7830/v1/ingress/members/<member_id>/block" \
   - `At least one of externalUserId or externalChatId is required` — ask the user for the contact's channel-specific identifier.
   - `Member not found or cannot be revoked` — the member ID may be invalid or the member is already revoked.
   - `Member not found or already blocked` — the member ID may be invalid or the member is already blocked.
+  - `sourceChannel is required for create` — when creating an invite, always pass `"sourceChannel": "telegram"`.
+  - `Invite not found or already revoked` — the invite ID may be invalid or the invite is already revoked.
 
 ## Typical Workflows
 
@@ -145,3 +241,9 @@ curl -s -X POST "http://localhost:7830/v1/ingress/members/<member_id>/block" \
 **"Block [name]"** — List members to find them, confirm the block, then execute.
 
 **"Show me blocked contacts"** — List with `status=blocked` filter.
+
+**"Create a Telegram invite link"** / **"Invite someone on Telegram"** — Create an invite with `sourceChannel: "telegram"`, look up the bot username, build the deep link, and present it with sharing instructions.
+
+**"Show my invites"** / **"List active invite links"** — List invites filtered by `sourceChannel=telegram`, present active invites with uses remaining and expiration info.
+
+**"Revoke invite"** / **"Cancel invite link"** — List invites to identify the target, confirm, then revoke by ID.

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

@@ -210,7 +210,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 **one channel at a time** (sms, voice, or telegram). Each invocation handles:
 - 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`
+- Starting the outbound verification session via the gateway endpoint `POST /v1/integrations/guardian/outbound/start`
 - For **SMS**: sending a 6-digit code to the phone number that the user must reply with from the SMS channel
 - For **voice**: calling the phone number and providing a code for the user to enter via their phone's keypad
 - Checking guardian status to confirm the binding was created

package/src/daemon/config-watcher.ts

@@ -109,7 +109,6 @@ export class ConfigWatcher {
       'SOUL.md': () => onSessionEvict(),
       'IDENTITY.md': () => { onSessionEvict(); onIdentityChanged?.(); },
       'USER.md': () => onSessionEvict(),
-      'LOOKS.md': () => onSessionEvict(),
       'UPDATES.md': () => onSessionEvict(),
     };
 

package/src/daemon/daemon-control.ts

@@ -106,7 +106,7 @@ function isProcessRunning(pid: number): boolean {
  */
 function isVellumDaemonProcess(pid: number): boolean {
   try {
-    const cmd = execSync(`ps -p ${pid} -o command=`, {
+    const cmd = execSync(`ps -ww -p ${pid} -o command=`, {
       encoding: 'utf-8',
       timeout: 3000,
       stdio: ['ignore', 'pipe', 'ignore'],