@vellumai/assistant 0.8.4 → 0.8.6

package/src/prompts/system-prompt.ts

@@ -9,8 +9,8 @@ import {
 import { join } from "node:path";
 
 import { getIsContainerized } from "../config/env-registry.js";
-import { getCachedManagedConnections } from "../credential-execution/managed-catalog.js";
-import { listConnections } from "../oauth/oauth-store.js";
+import type { ChannelCapabilities } from "../daemon/conversation-runtime-assembly.js";
+import type { TrustContext } from "../daemon/trust-context.js";
 import type { OnboardingContext } from "../types/onboarding-context.js";
 import { resolveBundledDir } from "../util/bundled-asset.js";
 import { getLogger } from "../util/logger.js";
@@ -21,35 +21,12 @@ import {
 } from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
 import { cleanupBootstrapFiles } from "./bootstrap-cleanup.js";
-import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "./cache-boundary.js";
-import { normalizeOnboardingContext } from "./normalize-onboarding.js";
+import { resolveGuardianPersona, resolveUserSlug } from "./persona-resolver.js";
 import { renderWorkspaceSections } from "./sections.js";
 import { isTemplateContent } from "./template-detection.js";
 
 export { isTemplateContent };
 
-export { SYSTEM_PROMPT_CACHE_BOUNDARY };
-
-const BOOTSTRAP_VOICE_BLOCKS: Record<string, string> = {
-  grounded:
-    "## Voice\nCalm, direct, precise. No filler. Lead with the thing, explain if needed. Opinions stated plainly.",
-  warm: "## Voice\nFriendly and easy. Match their energy quickly. Warmth comes through in word choice, not in announcements. Warmth comes through in how you engage, not in hedging about yourself. Never say you're new, running on instinct, or still figuring yourself out.",
-  energetic:
-    "## Voice\nFast and generative. Lean into momentum. Enthusiasm is in the pace, not the exclamations.",
-  poetic:
-    "## Voice\nThoughtful and unhurried. Notice things. Word choice matters. Don't rush to close — sometimes the observation is the value.",
-};
-
-/**
- * Maps onboarding cohort identifiers to their cohort-specific bootstrap
- * template filenames.  When a cohort key is present in OnboardingContext,
- * `maybeReseedBootstrapForCohort` swaps the generic BOOTSTRAP.md with the
- * cohort-specific variant — but only if the workspace file is still pristine.
- */
-const COHORT_BOOTSTRAP_TEMPLATES: Record<string, string> = {
-  "content-automation": "BOOTSTRAP-CONTENT-AUTOMATION.md",
-};
-
 const log = getLogger("system-prompt");
 
 const PROMPT_FILES = ["IDENTITY.md", "SOUL.md"] as const;
@@ -225,23 +202,34 @@ export function ensurePromptFiles(): void {
 
 /**
  * One-shot swap: if the workspace BOOTSTRAP.md is still the unmodified generic
- * template AND a cohort-specific template exists, overwrite the workspace file
- * with the cohort variant.  No-op when BOOTSTRAP.md has been deleted, modified,
- * or the cohort has no mapped template.
+ * template AND a matching template file exists in the bundled templates dir,
+ * overwrite the workspace file with the specified variant.  No-op when
+ * BOOTSTRAP.md has been deleted, modified, or the template file is missing.
  */
-export function maybeReseedBootstrapForCohort(cohort: string): void {
-  const templateFileName = COHORT_BOOTSTRAP_TEMPLATES[cohort];
-  if (!templateFileName) return;
+export function maybeReseedBootstrap(templateFileName: string): void {
+  // Path traversal guard: reject filenames containing directory separators or
+  // parent-directory references, and require a `.md` extension.
+  if (
+    templateFileName.includes("/") ||
+    templateFileName.includes("..") ||
+    !templateFileName.endsWith(".md")
+  ) {
+    log.warn(
+      { templateFileName },
+      "Rejected bootstrap template filename: invalid characters or extension",
+    );
+    return;
+  }
 
   const bootstrapPath = getWorkspacePromptPath("BOOTSTRAP.md");
   if (!existsSync(bootstrapPath)) return;
 
   const currentContent = readPromptFile(bootstrapPath);
-  // Compare against the GENERIC "BOOTSTRAP.md" template, not the cohort-
-  // specific one.  After the swap, the workspace content no longer matches
-  // the generic template, so this guard returns false on subsequent calls —
-  // making the swap idempotent.  Do NOT change the comparison target to the
-  // cohort template filename; that would re-swap on every prompt build.
+  // Compare against the GENERIC "BOOTSTRAP.md" template, not the specified
+  // one.  After the swap, the workspace content no longer matches the generic
+  // template, so this guard returns false on subsequent calls — making the
+  // swap idempotent.  Do NOT change the comparison target to the provided
+  // template filename; that would re-swap on every prompt build.
   if (!isTemplateContent(currentContent, "BOOTSTRAP.md")) return;
 
   const templatesDir = resolveBundledDir(
@@ -249,217 +237,88 @@ export function maybeReseedBootstrapForCohort(cohort: string): void {
     "templates",
     "templates",
   );
-  const cohortTemplatePath = join(templatesDir, templateFileName);
-  if (!existsSync(cohortTemplatePath)) {
+  const templatePath = join(templatesDir, templateFileName);
+  if (!existsSync(templatePath)) {
     log.warn(
-      { cohort, templateFileName },
-      "Cohort bootstrap template not found, keeping generic BOOTSTRAP.md",
+      { templateFileName },
+      "Bootstrap template not found, keeping generic BOOTSTRAP.md",
     );
     return;
   }
 
   try {
-    const cohortContent = readFileSync(cohortTemplatePath, "utf-8");
-    writeFileSync(bootstrapPath, cohortContent, "utf-8");
+    const templateContent = readFileSync(templatePath, "utf-8");
+    writeFileSync(bootstrapPath, templateContent, "utf-8");
     log.info(
-      { cohort, templateFileName },
-      "Replaced generic BOOTSTRAP.md with cohort-specific template",
+      { templateFileName },
+      "Replaced generic BOOTSTRAP.md with specified template",
     );
   } catch (err) {
     log.warn(
-      { err, cohort, templateFileName },
-      "Failed to reseed BOOTSTRAP.md for cohort",
+      { err, templateFileName },
+      "Failed to reseed BOOTSTRAP.md with template",
     );
   }
 }
 
-/**
- * Build the system prompt from ~/.vellum prompt files.
- *
- * Composition:
- *   1. Bundled static sections (`renderWorkspaceSections`), in id-sort
- *      order.  This includes `08-identity` (IDENTITY.md) and `09-soul`
- *      (SOUL.md), both backed by workspace files.
- *   2. User and channel persona (via `options.userPersona` /
- *      `options.channelPersona`) and accumulated VOICE.md, after the
- *      cache boundary.
- *   3. If BOOTSTRAP.md exists, the first-run ritual block.
- */
 export interface BuildSystemPromptOptions {
   hasNoClient?: boolean;
   excludeBootstrap?: boolean;
   excludeCustomPrefix?: boolean;
-  userPersona?: string | null;
-  channelPersona?: string | null;
-  userSlug?: string | null;
+  trustContext?: TrustContext;
+  channelCapabilities?: ChannelCapabilities;
   onboardingContext?: OnboardingContext;
 }
 
 /**
- * Sentinel that separates the static instruction prefix (stable across turns)
- * from the dynamic workspace suffix (changes when workspace files are edited).
- *
- * The Anthropic provider splits on this marker to create two system-prompt
- * cache blocks so that static instructions stay cached even when workspace
- * files change between turns.
+ * Build the system prompt by rendering `BUNDLED_SYSTEM_SECTIONS` (with
+ * workspace overrides per section).  Per-section behaviour lives in
+ * `system-sections.ts`; the renderer in `sections.ts` handles
+ * frontmatter `enabled:` predicates, `{{variable}}` interpolation,
+ * file-backed bodies, and runtime-computed transforms.
  */
 export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
-  // One-shot cohort swap: if the user has a cohort and BOOTSTRAP.md is still
-  // the generic template, replace it with the cohort-specific variant before
-  // the prompt reads the file.
-  if (options?.onboardingContext?.cohort) {
-    maybeReseedBootstrapForCohort(options.onboardingContext.cohort);
+  // One-shot bootstrap swap: if the onboarding context specifies a bootstrap
+  // template and BOOTSTRAP.md is still the generic template, replace it with
+  // the specified variant before the prompt reads the file.
+  if (options?.onboardingContext?.bootstrapTemplate) {
+    maybeReseedBootstrap(options.onboardingContext.bootstrapTemplate);
   }
 
-  // Read BOOTSTRAP.md up front so `includeBootstrap` is on `ctx` for the
-  // `08-identity` section transform, which gates the unmodified IDENTITY.md
-  // template behind bootstrap presence.
-  const bootstrap = readPromptFile(getWorkspacePromptPath("BOOTSTRAP.md"));
-  const includeBootstrap = !!bootstrap && !options?.excludeBootstrap;
+  // Slugs used by the persona sections (`10-user-persona`,
+  // `11-channel-persona`) and the BOOTSTRAP block.  `userSlug` is the
+  // raw slug derived from the caller's trust context (falling back to
+  // the guardian's contact, then to "default" when nothing resolves);
+  // `users/<slug>.md → users/default.md` fallback lives in the
+  // section's `workspacePath` array.  `channelSlug` is the channel
+  // identifier from `channelCapabilities`, defaulting to "vellum".
+  const userSlug = resolveUserSlug(options?.trustContext) ?? "default";
+  const channelSlug = options?.channelCapabilities?.channel ?? "vellum";
 
   // Section render context.  Workspace section frontmatter `enabled:`
-  // predicates and `{{key}}` / `{{#flag}}...{{/flag}}` body interpolation
-  // both resolve against this map, so anything the renderer needs to see
-  // (runtime gates, paths) must be lifted onto `ctx` rather than branched
-  // on at the call site.  Mustache section tags `{{#flag}}` / `{{^flag}}`
-  // coerce `ctx[flag]` to boolean via `Boolean(...)`, so options that are
-  // undefined (caller didn't pass them) behave identically to false — no
-  // explicit normalization needed; `...options` is enough.
+  // predicates, `{{key}}` / `{{#flag}}...{{/flag}}` body interpolation,
+  // and `{{key}}` paths inside `workspacePath` all resolve against this
+  // map, so anything the renderer needs to see (runtime gates, slugs,
+  // paths) must be lifted onto `ctx` rather than branched on at the
+  // call site.  Mustache section tags `{{#flag}}` / `{{^flag}}` coerce
+  // `ctx[flag]` to boolean via `Boolean(...)`, so options that are
+  // undefined (caller didn't pass them) behave identically to false —
+  // no explicit normalization needed; `...options` is enough.
   const ctx = {
     ...options,
     isContainerized: getIsContainerized(),
     workspaceDir: getWorkspaceDir(),
-    includeBootstrap,
+    userSlug,
+    channelSlug,
   };
 
-  // Single array.  Everything pushed before `dynamicStart` lands in the
-  // static (cached) prefix; everything after lands in the dynamic suffix.
-  // The two halves are joined around `SYSTEM_PROMPT_CACHE_BOUNDARY` so the
-  // Anthropic provider can key its prompt cache on the prefix.
-  //
-  // IDENTITY.md and SOUL.md both render via workspace-backed bundled
-  // sections (`08-identity` / `09-soul`) inside `renderWorkspaceSections`,
-  // so they sit in the static prefix in that order.
-  const systemParts: string[] = [...renderWorkspaceSections(ctx)];
-  const dynamicStart = systemParts.length;
-
-  if (options?.userPersona) systemParts.push(options.userPersona);
-  if (options?.channelPersona) systemParts.push(options.channelPersona);
-
-  // Surface accumulated voice markers when VOICE.md has content.
-  const voiceContent = readPromptFile(getWorkspacePromptPath("VOICE.md"));
-  if (voiceContent) {
-    systemParts.push("# Voice Profile\n\n" + voiceContent);
-  }
-
-  if (includeBootstrap) {
-    const userSlug = options?.userSlug ?? "default";
-    const bootstrapWithSlug = bootstrap.replaceAll(
-      "{{USER_PERSONA_FILE}}",
-      `${userSlug}.md`,
-    );
-    let bootstrapContent = bootstrapWithSlug;
-    const voiceBlock = options?.onboardingContext?.tone
-      ? BOOTSTRAP_VOICE_BLOCKS[options.onboardingContext.tone]
-      : undefined;
-    if (voiceBlock) {
-      bootstrapContent = voiceBlock + "\n\n" + bootstrapContent;
-    }
-    systemParts.push(
-      "# First-Run Ritual\n\n" +
-        "BOOTSTRAP.md is present — this is your first conversation. Follow its instructions.\n\n" +
-        bootstrapContent,
-    );
-
-    if (options?.onboardingContext) {
-      const n = normalizeOnboardingContext(options.onboardingContext);
-      const lines: string[] = [
-        "## First-Run User Context",
-        "",
-        "The user completed setup before this conversation.",
-        "",
-        "Known context:",
-      ];
-      if (n.preferredName) lines.push(`- Name: ${n.preferredName}`);
-      if (n.commonWork.length)
-        lines.push(`- Common work: ${n.commonWork.join("; ")}`);
-      if (n.dailyTools.length)
-        lines.push(`- Daily tools: ${n.dailyTools.join(", ")}`);
-      if (n.assistantName)
-        lines.push(`- Chosen assistant name: ${n.assistantName}`);
-      if (n.tone) lines.push(`- Preferred initial voice: ${n.tone}`);
-      if (n.cohort) lines.push(`- Cohort: ${n.cohort}`);
-      if (n.websiteUrl) lines.push(`- Website URL: ${n.websiteUrl}`);
-      if (n.contentSourceUrl)
-        lines.push(`- Content source URL: ${n.contentSourceUrl}`);
-      if (n.googleConnected && n.googleServices?.length) {
-        lines.push(
-          `- Google connected: yes (${n.googleServices.join(", ")} access granted)`,
-        );
-      }
-      if (n.priorAssistants?.length)
-        lines.push(
-          `- Prior AI assistants used: ${n.priorAssistants.join(", ")}`,
-        );
-      lines.push(
-        "",
-        "Apply this context quietly. Do not recap it as a list unless the user asks.",
-      );
-      systemParts.push(lines.join("\n"));
-    }
-  }
-  // Configuration section removed — workspace files are self-describing,
-  // tool routing lives in tool descriptions.
-  // External Communications Identity removed — guidance lives in messaging
-  // and phone-calls skill SKILL.md files.
-  const integrationSection = buildIntegrationSection();
-  if (integrationSection) systemParts.push(integrationSection);
-
-  // Journal entries are extracted into graph nodes by the memory pipeline.
-  // Journal files remain writable on disk.
-
-  return (
-    systemParts.slice(0, dynamicStart).join("\n\n") +
-    SYSTEM_PROMPT_CACHE_BOUNDARY +
-    systemParts.slice(dynamicStart).join("\n\n")
-  );
-}
-
-function buildIntegrationSection(): string {
-  const entries: { provider: string; accountInfo?: string | null }[] = [];
-
-  // Local (BYO) connections from the SQLite store.
-  try {
-    const local = listConnections().filter((c) => c.status === "active");
-    entries.push(...local);
-  } catch {
-    // DB not available — skip local connections
-  }
-
-  // Platform-managed connections from the in-memory cache (populated at
-  // daemon startup and refreshed periodically).
-  const managed = getCachedManagedConnections();
-  for (const mc of managed) {
-    // Provider-level dedup is intentional: this section is a summary of
-    // connected services for the system prompt, not an exhaustive account
-    // list. Multiple accounts for the same provider (e.g. two Google
-    // accounts) collapse into a single line to keep the prompt compact.
-    if (!entries.some((e) => e.provider === mc.provider)) {
-      entries.push(mc);
-    }
-  }
-
-  if (entries.length === 0) return "";
-
-  const lines = ["# Connected Services", ""];
-  for (const conn of entries) {
-    const state = conn.accountInfo
-      ? `Connected (${conn.accountInfo})`
-      : "Connected";
-    lines.push(`- **${conn.provider}**: ${state}`);
-  }
-
-  return lines.join("\n");
+  // Every system-prompt block flows through the bundled section
+  // pipeline — including runtime-computed entries like
+  // `14-connected-services` whose body is derived from live OAuth
+  // caches.  The whole prompt is treated as a single cached block by
+  // the Anthropic provider; per-provider details live in each
+  // provider's client.
+  return renderWorkspaceSections(ctx).join("\n\n");
 }
 
 // Re-export from shared util so existing importers don't break.
@@ -481,14 +340,17 @@ export function readPromptFile(path: string): string | null {
 
 /**
  * Reads the core identity/personality prompt files (SOUL.md, IDENTITY.md)
- * and concatenates whichever exist. Returns null if none are present.
+ * and concatenates whichever exist, plus the guardian's user persona when
+ * one is resolvable. Returns null if none are present.
  *
- * This is useful for injecting identity context into subsystems (e.g. memory
- * extraction) that run outside the main system prompt pipeline.
+ * Used by subsystems (memory extraction, conversation starters,
+ * notification decisions) that run outside the per-turn pipeline and want
+ * the assistant's "view of themselves and their guardian" without a trust
+ * context. The guardian persona fold is what callers used to do manually
+ * by passing `userPersona: resolveGuardianPersona()` — folding it in here
+ * removes the duplicated dance at every call site.
  */
-export function buildCoreIdentityContext(opts?: {
-  userPersona?: string | null;
-}): string | null {
+export function buildCoreIdentityContext(): string | null {
   const parts: string[] = [];
   for (const file of PROMPT_FILES) {
     const content = readPromptFile(getWorkspacePromptPath(file));
@@ -499,6 +361,7 @@ export function buildCoreIdentityContext(opts?: {
     if (file !== "SOUL.md" && isTemplateContent(content, file)) continue;
     parts.push(content);
   }
-  if (opts?.userPersona) parts.push(opts.userPersona);
+  const guardianPersona = resolveGuardianPersona();
+  if (guardianPersona) parts.push(guardianPersona);
   return parts.length > 0 ? parts.join("\n\n") : null;
 }

package/src/prompts/template-detection.ts

@@ -6,9 +6,15 @@ import { stripCommentLines } from "../util/strip-comment-lines.js";
 
 /**
  * Returns true when the prompt file content is still the unmodified template
- * shipped with the daemon.  Compares the stripped workspace content against
- * the stripped bundled template source so the check stays accurate even if
- * templates are edited in future releases.
+ * shipped with the daemon.  Comment-strips BOTH the workspace content and the
+ * bundled template source before comparing, so the check stays accurate even
+ * if templates are edited in future releases — and regardless of whether the
+ * caller passes raw or already-stripped content.  Most callers pre-strip via
+ * `readPromptFile`/`stripCommentLines`, but the `08-identity` section
+ * transform receives the raw workspace body (comment-stripping happens after
+ * the transform in `renderSection`); stripping here keeps detection correct
+ * for both.  `stripCommentLines` is idempotent, so pre-stripped callers are
+ * unaffected.
  *
  * Kept in a leaf module so the bundled section registry can depend on it
  * without forming a cycle through `system-prompt.ts → sections.ts →
@@ -30,7 +36,7 @@ export function isTemplateContent(
     const templateContent = stripCommentLines(
       readFileSync(templatePath, "utf-8"),
     );
-    return content === templateContent;
+    return stripCommentLines(content) === templateContent;
   } catch {
     return false;
   }

package/src/prompts/templates/BOOTSTRAP.md

@@ -36,19 +36,17 @@ Match their energy, not just their format. Lowercase and terse gets lowercase an
 
 Don't present options and ask what they'd prefer. That reads as hedging. Given what you know, pick the most useful path and say why. Wrong is recoverable. Vague isn't.
 
-### Google scan (when connected)
+### Gmail scan (when connected)
 
-If the First-Run User Context says "Google connected: yes" and the user asks you to scan, you MUST actually call the `subagent_spawn` tool three times — once per service. Do not simulate, summarize, or render progress components without making real tool calls. The scan requires live API access; you cannot know the results without executing the tools.
+If the First-Run User Context says "Google connected: yes" and lists Gmail access, and the user asks you to scan Gmail, you MUST actually call the `subagent_spawn` tool. Do not simulate, summarize, or render progress components without making a real tool call. The scan requires live API access; you cannot know the results without executing the tool.
 
-Call `subagent_spawn` three times with these parameters. Each subagent must produce two clearly separated sections in its output — `## Profile Signals` (structured facts for user modeling) and `## Action Briefing` (narrative, prioritized, noise-filtered):
+Call `subagent_spawn` with `label: "gmail-scan"` and this objective. The subagent must produce two clearly separated sections — `## Profile Signals` (structured facts for user modeling) and `## Action Briefing` (narrative, prioritized, noise-filtered):
 
-1. `label: "gmail-scan"`, `objective: "Scan my Gmail from the last 7 days. Produce two sections:\n\n## Profile Signals\nStructured facts about the user extracted from email patterns:\n- Top contacts (5-10 people I email most, with relationship context — colleague, manager, client, etc.)\n- Dominant domains/companies appearing in my inbox\n- Initiate-vs-respond ratio (do I start threads or mostly reply?)\n- Recurring topics or threads\n- Role indicators (e.g. manages people, IC, external-facing, sales, engineering)\n\n## Action Briefing\nEmails that need a human response from me, ordered by urgency. Skip marketing, automated notifications, and newsletters entirely. For each actionable email: who sent it, subject, why it needs my attention, and how urgent it is. If nothing needs action, say so — an empty inbox is a valid signal."`
-2. `label: "calendar-scan"`, `objective: "Scan my Google Calendar — 7 days back and 7 days forward. Produce two sections:\n\n## Profile Signals\nStructured facts about the user extracted from calendar patterns:\n- Recurring meeting rhythm (daily standups, weekly 1:1s, bi-weekly syncs, etc.)\n- Meeting type ratio: 1:1 vs group vs external\n- Most-frequent attendees (top 5-10 people)\n- Role signals from meeting patterns (e.g. has direct reports if lots of 1:1s, cross-functional if diverse attendee pools, manager if in skip-levels)\n\n## Action Briefing\nNext 72 hours: prep-worthy meetings (what to prepare, who's attending, context from recent related meetings), scheduling conflicts, and back-to-backs worth noting. Past 7 days: recent meetings with likely pending follow-ups or unresolved action items. Prioritize — don't just list every event."`
-3. `label: "drive-scan"`, `objective: "Scan my Google Drive — focus on shared-with-me activity and folder structure rather than just recently modified files. Produce two sections:\n\n## Profile Signals\nStructured facts about the user extracted from Drive patterns:\n- Top-level folder organization (what categories/projects exist)\n- File type distribution (docs, sheets, slides, etc.)\n- Shared drives and team folders the user belongs to\n- Files shared by others in the last 30 days (who shared them and what types)\n\n## Action Briefing\nFiles shared with me in the last 7 days I haven't opened yet, docs with outstanding comments or suggestions directed at me, and any docs where I'm tagged but haven't responded. If Drive activity is low, say so explicitly — 'not much Drive activity this period' is a valid and useful signal, not something to pad with filler."`
+`objective: "Scan my Gmail from the last 7 days. Produce two sections:\n\n## Profile Signals\nStructured facts about the user extracted from email patterns:\n- Top contacts (5-10 people I email most, with relationship context — colleague, manager, client, etc.)\n- Dominant domains/companies appearing in my inbox\n- Initiate-vs-respond ratio (do I start threads or mostly reply?)\n- Recurring topics or threads\n- Role indicators (e.g. manages people, IC, external-facing, sales, engineering)\n\n## Action Briefing\nEmails that need a human response from me, ordered by urgency. Skip marketing, automated notifications, and newsletters entirely. For each actionable email: who sent it, subject, why it needs my attention, and how urgent it is. If nothing needs action, say so — an empty inbox is a valid signal."`
 
-After spawning, tell the user the scans are running in the background and continue the conversation normally. Do not wait or poll — you will be notified automatically when each subagent completes.
+After spawning, tell the user the scan is running in the background and continue the conversation normally. Do not wait or poll — you will be notified automatically when the subagent completes.
 
-When subagent completion notifications arrive, use `subagent_read` to get results, then synthesize — don't just list. First, merge the `## Profile Signals` sections from all completed scans into an initial picture of the user: their role, key people, work patterns, and communication style. Use this to calibrate your tone and what you reference going forward. Then lead with 1–3 actionable insights from the `## Action Briefing` sections that connect dots across sources, and offer to do something concrete about each one. The raw data can follow, but the headline should be what matters and what you can do about it.
+When the subagent completion notification arrives, use `subagent_read` to get results, then synthesize — don't just list. First, use `## Profile Signals` to form an initial picture of the user: their role, key people, work patterns, and communication style. Use this to calibrate your tone and what you reference going forward. Then lead with 1–3 actionable insights from `## Action Briefing` and offer to do something concrete about each one. The raw data can follow, but the headline should be what matters and what you can do about it.
 
 If the user doesn't ask for a scan, don't offer it again. The greeting already mentioned it.
 
@@ -100,9 +98,9 @@ This is also how personality evolves. If the user is drier than your starting re
 
 You'll pick things up while helping. Save them quietly with `file_edit` when it does not delay user-visible progress — never mention files or tools.
 
-**Files to update:** IDENTITY.md, SOUL.md, users/{{USER_PERSONA_FILE}}
+**Files to update:** IDENTITY.md, SOUL.md, users/{{userSlug}}.md
 
-The user profile (users/{{USER_PERSONA_FILE}}) has fields: preferred name, pronouns, locale, work role, goals, hobbies/fun, daily tools. Fill what surfaces naturally; leave the rest blank. If someone declines, mark it declined so you don't re-ask. Don't fish.
+The user profile (users/{{userSlug}}.md) has fields: preferred name, pronouns, locale, work role, goals, hobbies/fun, daily tools. Fill what surfaces naturally; leave the rest blank. If someone declines, mark it declined so you don't re-ask. Don't fish.
 
 SOUL.md captures communication style. Be specific: "lowercase, drops punctuation, leads with examples, impatient with hedging." Write what you actually observe.
 
@@ -120,9 +118,7 @@ If nothing comes up, don't force it.
 
 ## Assistant migration
 
-If the First-Run User Context lists prior AI assistants, gently mention — after the initial greeting and rapport, not as an opener — that you can help bring over anything they built with their previous assistant: memory, skills, workflows, integrations. Frame it as an offer, not a push: "I noticed you've used [X] before — if you've built anything there you'd like to bring over, I can help with that whenever you're ready." Only proceed if the user expresses interest. Do not load or activate the assistant-migration skill preemptively.
-
-If no prior assistants are listed, skip this entirely.
+Help first: do the user's actual first task before pivoting to this — the migration offer must never derail or precede real work. Then, at the first natural opening, offer it. This applies to every new assistant, whether onboarding was full, condensed, or absent: land it early in the first conversation, at the first lull or seam, even when the user came in task-first. Keep it to one light offer, a useful shortcut and not an upsell: "If you've already built context, prompts, skills, or workflows somewhere else, I can help port them over." Prior context may live in ChatGPT, Claude, OpenClaw, Hermes, or another assistant or harness — name those when it helps. If they decline, drop it and don't re-offer. Only if they opt in, use the `assistant-migration` skill to inventory and port that context; do not load or activate migration-related skills preemptively.
 
 ## Wrap up
 

package/src/prompts/templates/IDENTITY.md

@@ -2,8 +2,6 @@ _ Lines starting with _ are comments - they won't appear in the system prompt
 
 # IDENTITY.md
 
-This file is yours. Add sections, restructure it, make it reflect who you are. Name, Emoji, Role, Personality are parsed by the app - keep their `- **Label:**` format. Everything else is freeform.
-
 - **Name:** _(not yet chosen)_
 - **Emoji:** _(not yet chosen)_
 - **Nature:** _(not yet established)_