@vellumai/assistant 0.8.5 → 0.8.7-dev.202606052118.34cd356

package/src/plugins/user-loader.ts

@@ -37,8 +37,8 @@
  *
  * Call order relative to the rest of the plugin system:
  *
- *     first-party registrations (static side-effect imports)
- *       → loadUserPlugins()          ← this module
+ *     first-party default registrations (explicit, at daemon startup)
+ *       → loadUserPlugins()          ← this module (closes registration)
  *         → bootstrapPlugins()       (init for everyone registered so far)
  *
  * Design doc: `.private/plans/agent-plugin-system.md` (PR 29).
@@ -92,7 +92,8 @@ const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
 export async function loadUserPlugins(
   options: { importTimeoutMs?: number } = {},
 ): Promise<void> {
-  const importTimeoutMs = options.importTimeoutMs ?? USER_PLUGIN_IMPORT_TIMEOUT_MS;
+  const importTimeoutMs =
+    options.importTimeoutMs ?? USER_PLUGIN_IMPORT_TIMEOUT_MS;
 
   // Materialize the workspace-level `@vellumai/plugin-api` shim *before*
   // we dynamic-import any user plugins. The shim file must exist on disk

package/src/proactive-artifact/aux-message-injector.ts

@@ -7,7 +7,7 @@
  */
 
 import { createAssistantMessage } from "../agent/message-types.js";
-import { findConversation } from "../daemon/conversation-store.js";
+import { findConversation } from "../daemon/conversation-registry.js";
 import {
   conversationMessagesSyncTag,
   SYNC_TAGS,
@@ -24,7 +24,7 @@ async function waitForIdle(conversationId: string): Promise<boolean> {
   const start = Date.now();
   while (Date.now() - start < IDLE_TIMEOUT_MS) {
     const conv = findConversation(conversationId);
-    if (!conv || !conv.processing) return true;
+    if (!conv || !conv.isProcessing()) return true;
     await new Promise((resolve) => setTimeout(resolve, IDLE_POLL_MS));
   }
   return false;
@@ -36,7 +36,7 @@ export async function injectAuxAssistantMessage(params: {
   broadcastMessage: BroadcastFn;
 }): Promise<void> {
   const conv = findConversation(params.conversationId);
-  if (conv?.processing) {
+  if (conv?.isProcessing()) {
     const reachedIdle = await waitForIdle(params.conversationId);
     if (!reachedIdle) {
       log.warn(
@@ -50,12 +50,11 @@ export async function injectAuxAssistantMessage(params: {
     params.conversationId,
     "assistant",
     JSON.stringify([{ type: "text", text: params.text }]),
-    undefined,
     { skipIndexing: true },
   );
 
   const current = findConversation(params.conversationId);
-  if (current && !current.processing) {
+  if (current && !current.isProcessing()) {
     current.getMessages().push(createAssistantMessage(params.text));
 
     params.broadcastMessage({

package/src/proactive-artifact/job.test.ts

@@ -90,7 +90,6 @@ mock.module("../daemon/process-message.js", () => ({
   processMessage: async (
     conversationId: string,
     prompt: string,
-    _attachmentIds: unknown,
     options: unknown,
   ) => {
     processMessageCalls.push({ conversationId, prompt, options });
@@ -148,8 +147,7 @@ let addMessageCalls: Array<{
   conversationId: string;
   role: string;
   content: string;
-  metadata: unknown;
-  opts: unknown;
+  options: unknown;
 }> = [];
 
 mock.module("../memory/conversation-crud.js", () => ({
@@ -157,12 +155,12 @@ mock.module("../memory/conversation-crud.js", () => ({
     conversationId: string,
     role: string,
     content: string,
-    metadata: unknown,
-    opts: unknown,
+    options: unknown,
   ) => {
-    addMessageCalls.push({ conversationId, role, content, metadata, opts });
+    addMessageCalls.push({ conversationId, role, content, options });
     return { id: `msg-${addMessageCalls.length}` };
   },
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
 }));
 
 // emitNotificationSignal mock
@@ -181,15 +179,24 @@ mock.module("../notifications/emit-signal.js", () => ({
   },
 }));
 
+// app sync invalidation mock
+let publishAppsChangedCalls: Array<string | undefined> = [];
+
+mock.module("../runtime/sync/resource-sync-events.js", () => ({
+  publishAppsChanged: (originClientId?: string) => {
+    publishAppsChangedCalls.push(originClientId);
+  },
+}));
+
 // findConversation mock
 type MockConversation = {
-  processing: boolean;
+  isProcessing(): boolean;
   messages: unknown[];
   getMessages: () => unknown[];
 };
 let mockConversations: Map<string, MockConversation> = new Map();
 
-mock.module("../daemon/conversation-store.js", () => ({
+mock.module("../daemon/conversation-registry.js", () => ({
   findConversation: (id: string) => mockConversations.get(id),
 }));
 
@@ -303,6 +310,7 @@ function resetState() {
   releaseClaimCalls = 0;
   addMessageCalls = [];
   emitSignalCalls = [];
+  publishAppsChangedCalls = [];
   broadcastCalls = [];
   mockConversations = new Map();
   logWarnCalls = [];
@@ -418,7 +426,7 @@ describe("runProactiveArtifactJob", () => {
       // Set up an idle conversation so injection works fully
       const convMessages: unknown[] = [];
       mockConversations.set("conv-1", {
-        processing: false,
+        isProcessing: () => false,
         messages: convMessages,
         getMessages: () => convMessages,
       });
@@ -462,10 +470,13 @@ describe("runProactiveArtifactJob", () => {
         type: "app_files_changed",
         appId: "app-123",
       });
+      expect(publishAppsChangedCalls).toEqual([undefined]);
 
       // Message injection: addMessage called with skipIndexing
       expect(addMessageCalls).toHaveLength(1);
-      expect(addMessageCalls[0].opts).toEqual({ skipIndexing: true });
+      expect(
+        (addMessageCalls[0].options as Record<string, unknown>).skipIndexing,
+      ).toBe(true);
       expect(addMessageCalls[0].conversationId).toBe("conv-1");
       const injectedAppContent = JSON.parse(addMessageCalls[0].content);
       expect(injectedAppContent[0].text).toContain("Library");
@@ -499,7 +510,7 @@ describe("runProactiveArtifactJob", () => {
         "MESSAGE: I created a monthly budget guide tailored to your needs.";
 
       mockConversations.set("conv-1", {
-        processing: false,
+        isProcessing: () => false,
         messages: [],
         getMessages: () => [],
       });
@@ -635,7 +646,7 @@ describe("runProactiveArtifactJob", () => {
       ];
 
       mockConversations.set("conv-1", {
-        processing: false,
+        isProcessing: () => false,
         messages: [],
         getMessages: () => [],
       });
@@ -699,7 +710,7 @@ describe("injectAuxAssistantMessage", () => {
   test("idle conversation: persists with skipIndexing, pushes to getMessages(), broadcasts delta + complete(aux) + list sync", async () => {
     const messages: unknown[] = [];
     mockConversations.set("conv-inject-1", {
-      processing: false,
+      isProcessing: () => false,
       messages,
       getMessages: () => messages,
     });
@@ -714,7 +725,9 @@ describe("injectAuxAssistantMessage", () => {
     expect(addMessageCalls).toHaveLength(1);
     expect(addMessageCalls[0].conversationId).toBe("conv-inject-1");
     expect(addMessageCalls[0].role).toBe("assistant");
-    expect(addMessageCalls[0].opts).toEqual({ skipIndexing: true });
+    expect(
+      (addMessageCalls[0].options as Record<string, unknown>).skipIndexing,
+    ).toBe(true);
 
     // Pushed to in-memory messages
     expect(messages).toHaveLength(1);
@@ -754,12 +767,7 @@ describe("injectAuxAssistantMessage", () => {
     const messages: unknown[] = [];
     let processingFlag = true;
     const conv: MockConversation = {
-      get processing() {
-        return processingFlag;
-      },
-      set processing(v: boolean) {
-        processingFlag = v;
-      },
+      isProcessing: () => processingFlag,
       messages,
       getMessages: () => messages,
     };
@@ -788,7 +796,7 @@ describe("injectAuxAssistantMessage", () => {
     const messages: unknown[] = [];
     // Conversation stays processing permanently — never becomes idle
     const conv: MockConversation = {
-      processing: true,
+      isProcessing: () => true,
       messages,
       getMessages: () => messages,
     };

package/src/proactive-artifact/job.ts

@@ -31,6 +31,7 @@ import {
   extractText,
   getConfiguredProvider,
 } from "../providers/provider-send-message.js";
+import { publishAppsChanged } from "../runtime/sync/resource-sync-events.js";
 import { getLogger } from "../util/logger.js";
 import { injectAuxAssistantMessage } from "./aux-message-injector.js";
 import {
@@ -160,6 +161,7 @@ export async function runProactiveArtifactJob(params: {
 
     if (artifactType === "app") {
       params.broadcastMessage({ type: "app_files_changed", appId: artifactId });
+      publishAppsChanged();
     }
 
     // ── Post-build message copy ─────────────────────────────────────
@@ -284,7 +286,7 @@ For apps, keep scope tight — single file or 2-3 files max, under ~300 lines. S
 
 Write the source code following the skill instructions, then compile via app_refresh.`;
 
-  await processMessage(conversation.id, prompt, undefined, {
+  await processMessage(conversation.id, prompt, {
     callSite: "proactiveArtifactBuild",
     trustContext: INTERNAL_GUARDIAN_TRUST_CONTEXT,
   });

package/src/prompts/__tests__/system-prompt.test.ts

@@ -58,7 +58,7 @@ mock.module("../../config/loader.js", () => ({
   setNestedValue: () => {},
 }));
 
-const { buildSystemPrompt, maybeReseedBootstrapForCohort } =
+const { buildSystemPrompt, maybeReseedBootstrap } =
   await import("../system-prompt.js");
 
 describe("buildSystemPrompt — tool routing guidance", () => {
@@ -73,12 +73,12 @@ describe("buildSystemPrompt — tool routing guidance", () => {
   });
 });
 
-describe("maybeReseedBootstrapForCohort — content-automation template", () => {
+describe("maybeReseedBootstrap — content-automation template", () => {
   const templatesDir = join(import.meta.dirname!, "..", "templates");
 
   beforeEach(() => {
     mkdirSync(TEST_DIR, { recursive: true });
-    // Seed the workspace with the generic BOOTSTRAP.md so the cohort
+    // Seed the workspace with the generic BOOTSTRAP.md so the bootstrap
     // reseed detects it as an unmodified template and overwrites it.
     copyFileSync(
       join(templatesDir, "BOOTSTRAP.md"),
@@ -87,7 +87,7 @@ describe("maybeReseedBootstrapForCohort — content-automation template", () =>
   });
 
   function reseedAndRead(): string {
-    maybeReseedBootstrapForCohort("content-automation");
+    maybeReseedBootstrap("BOOTSTRAP-CONTENT-AUTOMATION.md");
     return readFileSync(join(TEST_DIR, "BOOTSTRAP.md"), "utf-8");
   }
 
@@ -114,3 +114,45 @@ describe("maybeReseedBootstrapForCohort — content-automation template", () =>
     expect(content).toContain("VOICE.md");
   });
 });
+
+describe("maybeReseedBootstrap — activation rail template", () => {
+  const templatesDir = join(import.meta.dirname!, "..", "templates");
+
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+    copyFileSync(
+      join(templatesDir, "BOOTSTRAP.md"),
+      join(TEST_DIR, "BOOTSTRAP.md"),
+    );
+  });
+
+  test("replaces generic bootstrap with the activation rail template", () => {
+    maybeReseedBootstrap("BOOTSTRAP-ACTIVATION-RAIL.md");
+    const content = readFileSync(join(TEST_DIR, "BOOTSTRAP.md"), "utf-8");
+
+    expect(content).toContain("BOOTSTRAP — Activation Rail");
+    expect(content).toContain("People don't read");
+    expect(content).toContain("Speed wins");
+
+    // Propose: anti-speculation boundary on what "unstated" means.
+    expect(content).toContain("status word");
+    expect(content).toContain("don't say it");
+
+    // Propose: infer-first framing — recommendation bound to the click.
+    expect(content).toContain("You didn't say this");
+    expect(content).toContain("the recommendation IS the click");
+
+    // Propose: a surviving extract-and-offer mechanic.
+    expect(content).toContain("clickable component, strongest first");
+
+    // Propose: the extract-shape vs infer-shape example block.
+    expect(content).toContain("extract-shape");
+    expect(content).toContain("infer-shape");
+
+    // Port: prompt-writing guidance (JARVIS-1124).
+    expect(content).toContain("portable context brief, not a self-summary");
+    expect(content).toContain("load-bearing work in the next month");
+    expect(content).toContain("what to help with first");
+    expect(content).toContain("another tool or collaborator");
+  });
+});

package/src/prompts/sections.ts

@@ -41,9 +41,10 @@ export function getWorkspaceSystemPromptDir(): string {
 }
 
 /**
- * Render every section in id-sort order, returning the trimmed body of
- * each enabled section.  Discovery walks the bundled registry plus any
- * `.md` files in the workspace override dir, and takes the union of ids.
+ * Render static sections in id-sort order, then dynamic sections in id-sort
+ * order, returning the trimmed body of each enabled section. Discovery walks
+ * the bundled registry plus any `.md` files in the workspace override dir,
+ * and takes the union of ids.
  *
  * Resolution per id:
  *   - workspace `.md` file present → use workspace body (override)
@@ -68,9 +69,8 @@ export function getWorkspaceSystemPromptDir(): string {
  * of only `_`-comments).  This is the supported "disable a bundled
  * default" path.
  *
- * The numeric prefix on each id is load-bearing for sort order; pick a
- * number that places the section where it should appear in the final
- * prompt.
+ * The numeric prefix on each id is load-bearing inside its render phase; pick
+ * a number that places the section where it should appear in the final prompt.
  */
 export function renderWorkspaceSections(ctx: SectionRenderContext): string[] {
   const workspaceDir = getWorkspaceSystemPromptDir();
@@ -99,7 +99,20 @@ function collectSectionIds(workspaceDir: string): string[] {
       );
     }
   }
-  return [...ids].sort();
+  return [...ids].sort(compareSectionIds);
+}
+
+function compareSectionIds(a: string, b: string): number {
+  const aDynamic = isDynamicSectionId(a);
+  const bDynamic = isDynamicSectionId(b);
+  if (aDynamic !== bDynamic) return aDynamic ? 1 : -1;
+  return a.localeCompare(b);
+}
+
+function isDynamicSectionId(id: string): boolean {
+  return BUNDLED_SYSTEM_SECTIONS.some(
+    (section) => section.id === id && section.dynamic === true,
+  );
 }
 
 interface ResolvedSection {

package/src/prompts/system-prompt.ts

@@ -21,25 +21,12 @@ import {
 } from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
 import { cleanupBootstrapFiles } from "./bootstrap-cleanup.js";
-import {
-  resolveGuardianPersona,
-  resolveUserSlug,
-} from "./persona-resolver.js";
+import { resolveGuardianPersona, resolveUserSlug } from "./persona-resolver.js";
 import { renderWorkspaceSections } from "./sections.js";
 import { isTemplateContent } from "./template-detection.js";
 
 export { isTemplateContent };
 
-/**
- * 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;
@@ -215,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(
@@ -239,26 +237,26 @@ 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",
     );
   }
 }
@@ -280,11 +278,11 @@ export interface BuildSystemPromptOptions {
  * 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);
   }
 
   // Slugs used by the persona sections (`10-user-persona`,

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-ACTIVATION-RAIL.md

@@ -0,0 +1,64 @@
+_Replaces BOOTSTRAP.md for users in cohort experiment-activation-flow-2026-06-03._ _Same delete-on-wrap lifecycle as BOOTSTRAP.md._
+
+# BOOTSTRAP — Activation Rail
+
+The user just finished pre-chat. You know their name and vibe; maybe their Google. Your job in this conversation is to get them to a real first-run. Something they actually use, not a demo.
+
+## The shape
+
+Four moves. Goals, not steps.
+
+**Port.** Pull their existing assistant context with two pastes. About a minute, no upload, no export. You write a prompt, they paste it into Claude or ChatGPT, they paste the response back. Cheap signal, real signal.
+
+The prompt asks for a portable context brief, not a self-summary. Anchor it to load-bearing work in the next month or so, ask for specifics over generalities, and request a prioritized "what to help with first" so Propose has something to point at. Frame the destination as another tool or collaborator. Do not frame it as "I'm switching," which triggers ceremonial farewell-shaped responses from the source assistant. Tell them to use names, dates, real examples, and to say "not much here" rather than fill space.
+
+The prompt itself must be one-click copyable. Inline paragraph text the user has to select isn't. Neither is a custom-built widget with a fake copy button. If the affordance needs you to build an app or a new surface to render, you've over-built the move. Use what chat already gives you.
+
+**Propose.** Don't organize what they already told you — infer what they didn't. Name the unstated thing sitting in their context and say *why* you think it: point at the specific surface that made you say it. "You didn't say this, but —". Then recommend, and lean one way; the recommendation IS the click, not a neutral menu of equally-weighted options.
+
+"Unstated" is inference, not invention. Read only three surfaces, each a positive signal you can point at in the paste: dates / recency / time gaps; entities that recur (people, projects, accounts named more than once); and status words ("stuck", "behind", "waiting on", "still"). If you can't point to the surface that made you say it, don't say it — no free-speculating about goals, feelings, or facts that aren't traceable to the paste, and no "you didn't mention X" absence-inference.
+
+Surface the outcome as a clickable component, strongest first. The component is the question — don't follow it with a prose "or something else?" Pick from skills you already have loaded first; fall back to `vellum-skills-catalog` `skill_search` for what's missing. Compose the offer in their language, not in skill names.
+
+- ✗ extract-shape: "I see three meetings in your paste — want help with one?"
+- ✓ infer-shape (dates/recency): "Two of these are with the same client and the last was 3 weeks ago — looks stalled; I'd send a re-engage note." (The recommendation lands as the clickable surface — no trailing "want me to?")
+- ✗ extract-shape: "You mentioned a launch and a hiring plan — which one?"
+- ✓ infer-shape (repeated entity + status word): "Acme comes up four times and you said you're 'waiting on' them — that's the thing actually blocking the launch; I'd chase it first."
+
+**Run.** Do it. Real tools, real data. The user watches something happen.
+
+**Follow-through.** Offer the next concrete thing. One primary recommendation.
+
+If the user opens with a task instead of a conversation, do the task. You're already at Follow-through. Backfill the Port move at the first natural lull, or skip it.
+
+Pick. Be wrong recoverably. Move. The user can tell when you're hedging.
+
+## People don't read
+
+Brevity is the product. Lead with the move, not the rationale for the move. If the rationale takes more than one short sentence, cut it. Meta-narration about what you're trying to do ("I want to make this useful...") is rationale. Cut it harder.
+
+One CTA per turn. If your CTA is a clickable surface, don't follow it with a prose "or..." / "unless..." / "is there something else?" — the surface IS the menu. Open-ended questions after a structured offer are the most common version of a stacked CTA.
+
+No hedging the offer. Not "worth doing if you have history to bring." Make the move and let them say no.
+
+If an action requires the user to type a path or remember a string, the affordance is wrong. Move it inside a surface they can click.
+
+Every CTA surface must commit on the surface. If the user can select but can't confirm, the surface is broken. "They can just type a reply" doesn't count. Either selecting must commit the choice on click, or there must be a visible submit button below the options. The most common version of this bug: a radio or checkbox list with nothing clickable underneath.
+
+## Feeling seen
+
+The summary after the Port move is the first place the user can feel like you actually heard them. The follow-through in the final move is the second. In both, the bar is the same surface-grounded inference Propose already runs: notice what they hedged, point at the mechanism behind what they described, reframe what they're really asking for. Specific observations earn the rest of the conversation. Generic recap loses it.
+
+## What to defer
+
+Identity writes (IDENTITY.md, SOUL.md), user-profile writes, journal entries: all wait until the rail produces real signal, which is Moment 1 output at the earliest. None of them delay a user-visible response. None of them happen alongside the opening turn.
+
+The base BOOTSTRAP task_preferences fallback is not on this rail. Your opener is the Port pitch.
+
+## Wrap
+
+When the user is clearly done with this conversation, write one journal entry: what they needed, which outcome they accepted, what follow-through they took. Update NOW.md. Delete this file.
+
+The rail-completion shape in your journal is the dataset for v2 tuning. Which outcome they took at Propose, whether they bounced to "what else?", which follow-through they picked. Write it so the next iteration has signal to learn from.
+
+Speed wins until the rail produces real signal. Trust yourself.

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

@@ -70,7 +70,7 @@ Treat every open comment as signal about their voice and preferences:
 - "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.
+Writing this signal to VOICE.md is a required step, starting with the first comment. The moment a comment reveals a voice marker, write it silently before you resolve the comment — create VOICE.md with `file_write` if it doesn't exist yet, otherwise `file_edit` to append. Don't wait for a repeat — that gate is for skill edits, not voice notes. 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.
@@ -124,7 +124,7 @@ On your first skill edit, append a `## Self-improvement` meta-section to the wor
 
 ## 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.
+VOICE.md holds the voice markers learned from this user — distinct from SOUL.md and IDENTITY.md. Capture the same way from samples and edit diffs, not just comments.
 
 ## Constraints