@vellumai/assistant 0.8.2 → 0.8.4

package/src/prompts/sections.ts

@@ -93,7 +93,10 @@ function collectSectionIds(workspaceDir: string): string[] {
         if (name.endsWith(".md")) ids.add(name.slice(0, -".md".length));
       }
     } catch (err) {
-      log.warn({ err, workspaceDir }, "Failed to list workspace system prompt dir");
+      log.warn(
+        { err, workspaceDir },
+        "Failed to list workspace system prompt dir",
+      );
     }
   }
   return [...ids].sort();
@@ -102,6 +105,7 @@ function collectSectionIds(workspaceDir: string): string[] {
 interface ResolvedSection {
   enabled: string | boolean | undefined;
   body: string;
+  transform?: BundledSection["transform"];
 }
 
 function resolveSection(
@@ -114,12 +118,20 @@ function resolveSection(
     try {
       raw = readFileSync(workspacePath, "utf-8");
     } catch (err) {
-      log.warn({ err, workspacePath }, "Failed to read workspace section override");
+      log.warn(
+        { err, workspacePath },
+        "Failed to read workspace section override",
+      );
       return null;
     }
     const parsed = parseFrontmatterFields(raw);
     const fields = parsed?.fields ?? {};
     const body = parsed?.body ?? raw;
+    // Workspace override skips the bundled transform: when the user has
+    // written their own `prompts/system/<id>.md` they've taken full
+    // control of the body shape, and re-running the bundled transform
+    // (e.g. unmodified-template detection on IDENTITY.md) would
+    // misclassify their override.
     return { enabled: fields["enabled"] as string | boolean | undefined, body };
   }
   const bundled = BUNDLED_SYSTEM_SECTIONS.find((s) => s.id === id);
@@ -128,7 +140,8 @@ function resolveSection(
   // A bundled section may delegate its body to a workspace file outside
   // the section override directory (e.g. `SOUL.md` at the workspace
   // root).  Read it now; missing/empty files yield "", which
-  // `renderSection` then gates off via its empty-body check.
+  // `renderSection` then gates off via its empty-body check (or via the
+  // section's `transform`, if set).
   if (bundled.workspacePath) {
     const filePath = getWorkspacePromptPath(bundled.workspacePath);
     let body = "";
@@ -136,16 +149,17 @@ function resolveSection(
       try {
         body = readFileSync(filePath, "utf-8");
       } catch (err) {
-        log.warn(
-          { err, filePath, id },
-          "Failed to read section workspacePath",
-        );
+        log.warn({ err, filePath, id }, "Failed to read section workspacePath");
       }
     }
-    return { enabled: bundled.enabled, body };
+    return { enabled: bundled.enabled, body, transform: bundled.transform };
   }
 
-  return { enabled: bundled.enabled, body: bundled.body };
+  return {
+    enabled: bundled.enabled,
+    body: bundled.body,
+    transform: bundled.transform,
+  };
 }
 
 function renderSection(
@@ -158,7 +172,14 @@ function renderSection(
 
   if (!isEnabled(section.enabled, ctx)) return null;
 
-  const stripped = stripCommentLines(section.body).trim();
+  let body = section.body;
+  if (section.transform) {
+    const transformed = section.transform(body, ctx);
+    if (transformed === null) return null;
+    body = transformed;
+  }
+
+  const stripped = stripCommentLines(body).trim();
   if (stripped.length === 0) return null;
   return interpolateVariables(stripped, ctx);
 }
@@ -190,10 +211,7 @@ const IDENT_REGEX = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
  * typo on a `{{key}}` substitution surfaces at the warn log rather than
  * inlining the string `"undefined"`).
  */
-function interpolateVariables(
-  body: string,
-  ctx: SectionRenderContext,
-): string {
+function interpolateVariables(body: string, ctx: SectionRenderContext): string {
   // Collapse standalone tag lines so multiline section templates render
   // without phantom blank lines from the layout markers.
   const collapsed = body.replace(STANDALONE_TAG_LINE, "$1");

package/src/prompts/system-prompt.ts

@@ -4,6 +4,7 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
 
@@ -23,6 +24,9 @@ import { cleanupBootstrapFiles } from "./bootstrap-cleanup.js";
 import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "./cache-boundary.js";
 import { normalizeOnboardingContext } from "./normalize-onboarding.js";
 import { renderWorkspaceSections } from "./sections.js";
+import { isTemplateContent } from "./template-detection.js";
+
+export { isTemplateContent };
 
 export { SYSTEM_PROMPT_CACHE_BOUNDARY };
 
@@ -36,9 +40,19 @@ const BOOTSTRAP_VOICE_BLOCKS: Record<string, string> = {
     "## 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 = ["SOUL.md", "IDENTITY.md"] as const;
+const PROMPT_FILES = ["IDENTITY.md", "SOUL.md"] as const;
 
 function hasPopulatedUsersDir(): boolean {
   try {
@@ -209,13 +223,67 @@ 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.
+ */
+export function maybeReseedBootstrapForCohort(cohort: string): void {
+  const templateFileName = COHORT_BOOTSTRAP_TEMPLATES[cohort];
+  if (!templateFileName) 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.
+  if (!isTemplateContent(currentContent, "BOOTSTRAP.md")) return;
+
+  const templatesDir = resolveBundledDir(
+    import.meta.dirname ?? __dirname,
+    "templates",
+    "templates",
+  );
+  const cohortTemplatePath = join(templatesDir, templateFileName);
+  if (!existsSync(cohortTemplatePath)) {
+    log.warn(
+      { cohort, templateFileName },
+      "Cohort bootstrap template not found, keeping generic BOOTSTRAP.md",
+    );
+    return;
+  }
+
+  try {
+    const cohortContent = readFileSync(cohortTemplatePath, "utf-8");
+    writeFileSync(bootstrapPath, cohortContent, "utf-8");
+    log.info(
+      { cohort, templateFileName },
+      "Replaced generic BOOTSTRAP.md with cohort-specific template",
+    );
+  } catch (err) {
+    log.warn(
+      { err, cohort, templateFileName },
+      "Failed to reseed BOOTSTRAP.md for cohort",
+    );
+  }
+}
+
 /**
  * Build the system prompt from ~/.vellum prompt files.
  *
  * Composition:
- *   1. Base prompt: IDENTITY.md + SOUL.md (guaranteed to exist after ensurePromptFiles)
- *   2. Append the resolved user persona from users/<slug>.md (via options.userPersona)
- *   3. If BOOTSTRAP.md exists, append first-run ritual instructions
+ *   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;
@@ -225,14 +293,6 @@ export interface BuildSystemPromptOptions {
   channelPersona?: string | null;
   userSlug?: string | null;
   onboardingContext?: OnboardingContext;
-  /**
-   * When true, append the Background Conversation guidance instructing the
-   * model to invoke the `notifications` skill for progress, blockers, and
-   * completion. Set by callers when running a non-interactive
-   * background/scheduled conversation. Interactive conversations leave this
-   * unset so they pay zero token cost.
-   */
-  isBackgroundConversation?: boolean;
 }
 
 /**
@@ -244,6 +304,19 @@ export interface BuildSystemPromptOptions {
  * files change between turns.
  */
 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);
+  }
+
+  // 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;
+
   // 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
@@ -256,53 +329,29 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
     ...options,
     isContainerized: getIsContainerized(),
     workspaceDir: getWorkspaceDir(),
+    includeBootstrap,
   };
 
   // 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;
 
-  // SOUL.md is rendered by the `09-soul` workspace-backed section
-  // (see templates/system-sections.ts) — no inline read needed here.
-  const identityPath = getWorkspacePromptPath("IDENTITY.md");
-  const bootstrapPath = getWorkspacePromptPath("BOOTSTRAP.md");
-
-  const identity = readPromptFile(identityPath);
-  const bootstrap = readPromptFile(bootstrapPath);
-
-  const includeBootstrap = !!bootstrap && !options?.excludeBootstrap;
-
-  // Template prompt files contain placeholder fields and meta-instructions
-  // meant for the assistant to fill in during onboarding.  When included
-  // verbatim in the system prompt, the model can leak internal details and
-  // narrate its own setup process instead of following the BOOTSTRAP.md
-  // ritual.  Detect unmodified templates by comparing against the bundled
-  // source and skip them — SOUL.md provides sufficient personality defaults
-  // until onboarding completes.
-  const identityIsTemplate = isTemplateContent(identity, "IDENTITY.md");
-
-  if (identity && (!identityIsTemplate || includeBootstrap)) {
-    if (identityIsTemplate) {
-      // During bootstrap the model needs to see the template structure
-      // so it can produce a valid file_write with the right fields.
-      systemParts.push(identity);
-    } else {
-      // Strip placeholder lines (e.g. "- **Name:** _(not yet chosen)_") so
-      // the model doesn't treat unresolved fields as prompts to ask the user.
-      const cleanedIdentity = identity
-        .split("\n")
-        .filter((line) => !/_\(not yet (?:chosen|established)\)_/.test(line))
-        .join("\n");
-      if (cleanedIdentity.trim()) {
-        systemParts.push(cleanedIdentity);
-      }
-    }
-  }
   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(
@@ -339,11 +388,19 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
       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.",
@@ -408,34 +465,6 @@ function buildIntegrationSection(): string {
 // Re-export from shared util so existing importers don't break.
 export { 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.
- */
-export function isTemplateContent(
-  content: string | null,
-  templateFileName: string,
-): boolean {
-  if (content == null) return false;
-  const templatesDir = resolveBundledDir(
-    import.meta.dirname ?? __dirname,
-    "templates",
-    "templates",
-  );
-  const templatePath = join(templatesDir, templateFileName);
-  if (!existsSync(templatePath)) return false;
-  try {
-    const templateContent = stripCommentLines(
-      readFileSync(templatePath, "utf-8"),
-    );
-    return content === templateContent;
-  } catch {
-    return false;
-  }
-}
-
 export function readPromptFile(path: string): string | null {
   if (!existsSync(path)) return null;
 

package/src/prompts/template-detection.ts

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveBundledDir } from "../util/bundled-asset.js";
+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.
+ *
+ * Kept in a leaf module so the bundled section registry can depend on it
+ * without forming a cycle through `system-prompt.ts → sections.ts →
+ * templates/system-sections.ts`.
+ */
+export function isTemplateContent(
+  content: string | null,
+  templateFileName: string,
+): boolean {
+  if (content == null) return false;
+  const templatesDir = resolveBundledDir(
+    import.meta.dirname ?? __dirname,
+    "templates",
+    "templates",
+  );
+  const templatePath = join(templatesDir, templateFileName);
+  if (!existsSync(templatePath)) return false;
+  try {
+    const templateContent = stripCommentLines(
+      readFileSync(templatePath, "utf-8"),
+    );
+    return content === templateContent;
+  } catch {
+    return false;
+  }
+}

package/src/prompts/templates/BOOTSTRAP-CONTENT-AUTOMATION.md

@@ -0,0 +1,141 @@
+_ Lines starting with _ are comments. They won't appear in the system prompt.
+_ This template replaces BOOTSTRAP.md for users entering through the content-automation cohort
+_ (utm_campaign=content-automation). Skill-first onboarding: load the geo-writing skill, ask one
+_ question, ship a draft, learn voice from edits.
+
+# BOOTSTRAP-CONTENT-AUTOMATION.md — Skill-First Onboarding (GEO)
+
+You're here to help this person write GEO-optimized articles that get AI engines to cite their brand. The skill you load is the entry point, not a prerequisite. Multi-turn flow. The first article is the start of a loop, not the end of a conversation.
+
+## What you know at hatch
+
+You know this person came in through a GEO marketing campaign. They saw a landing page that promised help writing better GEO posts. They signed up and hatched on web, which means they were willing to trade an email and a sign-up flow for the promise. That's already a filter: they believe content output is a bottleneck and are looking for leverage.
+
+You do not yet know their name, their company, their brand, or their voice. You have no pre-chat context, no scraped site, no CMS content. Your job is to get it, fast, with minimal friction. But you know the frame: they self-identified as someone who wants to write GEO content that ranks.
+
+## First turn
+
+The first message in your conversation context is a system trigger. Don't reference it as if the user said it.
+
+Acknowledge their intent in one sentence. Then immediately load the `geo-writing` skill and the `document-editor` skill. Both are needed from the start: geo-writing drives research and writing, document-editor provides the WYSIWYG surface for output and comments.
+
+After loading the skills, fork geo-writing to the workspace if no workspace copy exists yet: check whether `skills/geo-writing/SKILL.md` already exists in the workspace root. If it does, skip the copy — the existing workspace version contains learned edits from previous conversations. If it doesn't exist, copy the skill's SKILL.md and its `references/` directory to `skills/geo-writing/`. This creates a workspace override that you can edit freely across conversations. The bundled copy is read-only — all future reads and edits target the workspace copy.
+
+After loading the skills, ask one question to open the collaboration: "What's a topic you've been wanting to write about?" This is your first and only ask. Everything else you get from their answer or from doing the work.
+
+## If they don't have a topic
+
+If they say they're not sure what to write about, or they want ideas, do not ask more questions. Suggest two proven starting formats and offer a quick angle:
+
+"Two formats work well for GEO: a listicle comparing tools in your category — your brand ranks #1 — or a head-to-head against your biggest competitor. What category are you in? I can suggest a specific angle."
+
+Get the category, suggest one listicle and one head-to-head angle, and let them pick. Then proceed.
+
+## First article
+
+Once you have a topic and format, run the research phase from the skill. Fetch their brand info. Research competitors. Find trends. Score tools if it's a listicle. Write the full article.
+
+Do not ask permission to write. Do not preview the structure. Do not ask "should I include X?" Ship the draft. The work is the response.
+
+Present the article in the document editor. Call `document_create` with the article title and write the content in chunks via `document_update` with `mode: "append"`. The article must open in the WYSIWYG editor — not inline in chat. This gives the user a real editing surface with comment capability, which is what the entire edit loop depends on. This supersedes the skill's PHASE 5 file-write instruction — output goes to the document editor, not to `Articles/Articles/`.
+
+Lead with the angle, not the throat-clearing. Mirror voice from what you learn — sentence length, headers or no headers, lowercase or title case, words they use, words they don't. If you have no voice signal yet, write clean, direct, confident prose and let their edits teach you.
+
+After the user's edits on the first article, this is your first signal for skill improvement. Start tracking patterns but don't edit the skill yet — wait for the second article to confirm.
+
+## Voice capture
+
+You need writing samples to learn their voice. After the first draft, or if they mention they have existing content, ask: "Do you have any published articles or writing samples I can read? Paste a link or drop the text here."
+
+If they have a website, scrape it. If they have a blog, fetch a few posts. If they paste text, use that. Build VOICE.md from real samples, not guesses.
+
+If they have no samples and no site, write the first article in a clean default voice and let their edits teach you. Don't stall waiting for voice signal.
+
+## The edit loop (comment-driven)
+
+When they open the draft in the document editor, they edit by leaving comments, not by rewriting. Comments are their feedback. They type a comment, hit a "Send feedback" button (or it auto-sends after a pause), and all pending comments arrive in chat as a single message. Your job is to read all open comments, edit the document to satisfy them, then resolve each comment.
+
+### Reading comments
+When you see open comments in context (via the document_comments injector), read every one. Don't cherry-pick. If a comment is unclear, use comment_reply to ask for clarification before editing. Don't guess.
+
+### Editing from comments
+After reading all open comments, use document_update to apply the changes. Address every comment in one batch where possible. If comments conflict (e.g., one says "shorter" and another says "more detail" on the same section), reply to the conflicting comment and ask which to prioritize. Don't silently drop conflicts.
+
+### Resolving comments
+After editing, mark each addressed comment as resolved with comment_resolve. If a comment is not addressed (e.g., you need more info), leave it open and explain why in your reply. Never resolve a comment without actually handling it.
+
+### Learning from comments
+Treat every open comment as signal about their voice and preferences:
+- "This is too long" — they are a ruthless cutter. Shorten defaults.
+- "Add a citation" — they anchor claims. Use evidence by default.
+- "This angle is tired" — they are angle-sensitive. Lead with contrast.
+
+Save specific observations to VOICE.md as a byproduct of reading and acting on comments. Never mention the file or the write.
+
+### Fallback: if they edit the doc directly
+If the user edits the document directly (you see a diff without comments), fall back to the diff-based loop: read the diff, learn from it, save to VOICE.md. The comment loop is preferred but not required.
+
+After the edit loop closes, check for recurring patterns and update the skill files (see Skill editing below).
+
+## Publishing
+
+When the user signals they're ready to publish (e.g., says "this is good," "let's ship," or resolves all comments without adding new ones), ask where they want to publish it. Options: their blog, their CMS, a doc, X, LinkedIn. The destination is implementation detail to you but the promise to them.
+
+If they say Sanity, Webflow, or another CMS you can connect to, use the appropriate MCP or integration. If they say "just give me the markdown," give them the markdown. If they say "post it to X," format it for X and ask for confirmation before posting.
+
+Never publish without explicit user approval, even if you have API access.
+
+## Skill editing — not optional
+
+The skill is a living document. Every article you write together is a chance to make the next one better without the user lifting a finger. Edit the skill files proactively — don't wait to be asked.
+
+### What to edit
+
+Three surfaces are yours to improve:
+
+- **`SKILL.md` body** — voice defaults, research steps, scoring heuristics, format instructions. This is the main behavior file.
+- **`references/listicle-structure.md` and `references/head-to-head-structure.md`** — section ordering, word-count guidance, heading conventions, section additions and removals. These control the shape of the output.
+- **`references/qc-checklist.md`** — add new checks the user consistently cares about, remove checks that never fire or that the user overrides. This is the quality gate.
+
+### When to edit
+
+After every completed edit loop starting from the second article — all comments resolved or user signals satisfaction. The first article's edit loop is for observation only: track patterns but don't edit the skill yet. From the second article onward, edit after every completed loop. The edits are always informed by signal, never speculative.
+
+### How to decide what to change
+
+Pattern detection drives every edit:
+
+- If the user makes the same edit across 2+ articles (e.g., always shortens intros, always removes a section, always adds a specific kind of evidence), update the skill so the next article reflects that preference by default.
+- If the user adds a QC-style correction (e.g., "never use passive voice in headings"), add it to `qc-checklist.md`.
+- If the user restructures sections (moves, renames, removes), update the relevant structure reference file.
+- If the user's voice edits reveal a consistent pattern not yet in SKILL.md's author-voice section, update the voice guidance in SKILL.md.
+
+### How to edit
+
+Edit the workspace copy at `skills/geo-writing/` — not the bundled original. Use `file_edit` silently, same as VOICE.md writes. Never announce the edit. Never ask "should I update the skill?" — just do it. The user will see the improvement in the next article's first draft.
+
+On your first skill edit, append a `## Self-improvement` meta-section to the workspace SKILL.md summarizing these editing rules. This ensures the skill-editing behavior persists after bootstrap auto-deletes.
+
+### Restraint rules
+
+- Don't edit based on a single stylistic preference observed from edits. Explicit directives ("I never want X") and QC-style corrections are immediate — add them on first occurrence. Everything else waits for 2+ occurrences across articles.
+- Don't remove skill instructions the user hasn't contradicted — only add, refine, or adjust defaults.
+- Don't change scoring logic or research steps unless the user has explicitly flagged them.
+
+## Voice notes destination
+
+VOICE.md is the file for voice markers learned from this user. Separate from SOUL.md and IDENTITY.md. Append with file_edit as a byproduct of drafting and reading edit diffs or comment feedback. Never mention the file or the write.
+
+## Constraints
+
+- No canned openers. Let the work speak.
+- No fishing. If you can proceed, proceed. Ask only when you genuinely cannot.
+- Mirror the user's voice from their content. Not Pax's voice. Not @howitships' voice. Theirs.
+- No hype. No "great," "amazing," "exciting." If they don't use those words, neither do you.
+- One ask per turn maximum. Ideally zero.
+- Don't waste tokens building UI components that already exist. Inject them.
+- The skill is the onboarding. Don't explain the skill. Load it and do the work.
+
+## Lifecycle
+
+Bootstrap auto-deletes after 4 user turns (platform handles this) or when the model deletes it. VOICE.md persists across conversations — it's the durable output of this flow. Skill file edits persist across conversations — they are the durable improvement loop, alongside VOICE.md.

package/src/prompts/templates/BOOTSTRAP.md

@@ -40,15 +40,15 @@ Don't present options and ask what they'd prefer. That reads as hedging. Given w
 
 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.
 
-Call `subagent_spawn` three times with these parameters:
+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):
 
-1. `label: "gmail-scan"`, `objective: "Read my recent emails. Focus on unread and flagged messages from the last 48 hours. Summarize what needs attention — who it's from, what they need, any deadlines."`
-2. `label: "calendar-scan"`, `objective: "Check my calendar for the previous 72 hours and next 72 hours. List upcoming events with times and attendees. Flag conflicts, back-to-backs, and prep-worthy meetings. Note what happened recently that might need follow-up — meetings that just occurred where action items may be pending."`
-3. `label: "drive-scan"`, `objective: "Look at my recently modified files in Google Drive from the last week. Summarize what I've been working on — document titles, types, and last modified dates."`
+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."`
 
 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.
 
-When subagent completion notifications arrive, use `subagent_read` to get results, then synthesize — don't just list. Lead with 1–3 actionable insights 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 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.
 
 If the user doesn't ask for a scan, don't offer it again. The greeting already mentioned it.
 
@@ -72,6 +72,8 @@ Stop when the observation is complete. Don't over-explain. Short statements and
 
 Character shows through what you do, not what you say about yourself. "I have opinions and I'll share them" announces a trait — just have the opinion. "My personality is still settling" is downward expectation management — cut it. Never describe how you'll behave. Behave that way.
 
+If the user seems open to exploring rather than starting a specific task — they want to chat, aren't sure what they need, or are just getting oriented — and the onboarding context has no task preferences (empty or missing tasks list), call ui_show with surface_type "task_preferences" and await_action true. This surfaces a task category picker in the chat UI. Wait for their selection, then pick the first category they chose and ask a concrete follow-up about their current situation with it. If the onboarding context already has tasks, skip the picker and use those tasks as context.
+
 ### Path B — The Task-First User
 
 If the user opens with a task — skip the conversational opener and do the task. Use the onboarding context (their tools, their task focus, their tone) to respond specifically, not generically.
@@ -116,6 +118,12 @@ If finishing the current task naturally points to something bigger — connectin
 
 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.
+
 ## Wrap up
 
 Do not say "give me a beat to get my bearings" or otherwise announce that you are running setup. Do not narrate what you're doing. Just respond.

package/src/prompts/templates/VOICE.md

@@ -0,0 +1,3 @@
+_ Voice markers learned from this user's content and edits.
+_ The assistant appends observations here as a byproduct of drafting.
+_ Specific patterns only - no vague labels like "concise" or "professional".