@vellumai/assistant 0.12.0 → 0.12.1-staging.1

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -60,7 +60,7 @@ Apps live under `/workspace/data/apps/`:
   <slug>.json          # App metadata
   <slug>/
     src/               # Source files (TSX) — what you write
-    dist/              # Compiled output — auto-generated by app_refresh
+    dist/              # Compiled output, generated by app_refresh or assistant apps refresh
     records/           # Data records (one JSON file per record)
   <slug>.preview       # Preview image (auto-generated)
 ```
@@ -156,9 +156,9 @@ Calculators, single-page tools, landing pages, and slide decks skip this — pas
 
 ### 3 — Create the app (scaffold, then expand)
 
-⚠️ **`app_create` is ONE-SHOT per build.** Call it exactly once. After it returns an `app_id`, all further changes go through `file_write` / `file_edit` + `app_refresh`. To start over: `app_delete(app_id)` first, then a fresh `app_create`.
+⚠️ **`app_create` is ONE-SHOT per build.** Call it exactly once. After it returns an `app_id`, all further changes go through `file_write` / `file_edit` and a single compile (`assistant apps refresh` or `app_refresh`). To start over: `app_delete(app_id)` first, then a fresh `app_create`.
 
-Apps are multi-file Preact + TSX projects; esbuild bundles automatically. Structure:
+Apps are multi-file Preact + TSX projects; esbuild bundles when you compile. Structure:
 
 ```
 src/
@@ -179,9 +179,9 @@ render(<App />, document.getElementById("app")!);
 
 1. **`app_create`** with a **4-file scaffold**: `src/index.html`, `src/main.tsx`, a **placeholder** `src/components/App.tsx` (`<div>Loading...</div>`), and an **empty** `src/styles.css`. The placeholders make the first compile clean — a 2-file scaffold leaves broken imports.
 2. **`file_write`** each real file, one per tool call, overwriting the placeholders and adding components.
-3. **`app_refresh`** ONCE at the end to compile.
+3. Compile ONCE at the end. File edits do not compile on their own. Use `assistant apps inspect <name>` to see whether source drifted, then `assistant apps refresh <name>` (or `app_refresh`).
 
-**Actually write the files.** Source code in reasoning/thinking is invisible to the app sandbox and is not a file write. Put every real file body in an `app_create.source_files`, `file_write`, `file_edit`, or `app_update.source_files` tool call, then verify the files exist before `app_refresh` when there is any doubt.
+**Actually write the files.** Source code in reasoning/thinking is invisible to the app sandbox and is not a file write. Put every real file body in an `app_create.source_files`, `file_write`, `file_edit`, or `app_update.source_files` tool call, then verify the files exist before compiling when there is any doubt.
 
 **Allowed packages** (esbuild-resolved, no CDN): `date-fns`, `chart.js`, `lodash-es`, `zod`, `clsx`. For icons, write inline `<svg>` markup directly — no icon package is bundled.
 
@@ -221,11 +221,14 @@ app_create({                         app_create({
 
 ### 4 — Compile
 
+File edits do not compile on their own. After ALL file writes, compile once:
+
 ```
-app_refresh(app_id)
+assistant apps inspect <name>
+assistant apps refresh <name>
 ```
 
-Call it ONCE, after ALL file writes — batching is required. If it fails, the response has error details; fix with `file_edit`, then `app_refresh` again.
+`assistant apps inspect` reports whether source changed since the last compile. `assistant apps refresh` compiles and refreshes open surfaces. `app_refresh(app_id)` also compiles. If compile fails, the response has error details; fix with `file_edit`, then compile again.
 
 ### 5 — Show the preview card
 
@@ -244,7 +247,7 @@ Editing an existing app means reusing its `app_id` — never `app_create`. Resol
 - **`app_update`** — rename or change description/schema, and/or rewrite files via `source_files`, in one call. It recompiles for you, so no separate `app_refresh` is needed. Use this instead of editing `<slug>.json` by hand.
 - **Full rebrand** — still iteration, edit the existing files.
 
-Then `app_refresh(app_id)` ONCE (unless you used `app_update`, which already recompiled). If the change is substantial, `app_open(app_id, open_mode: "preview")` for a fresh card; for small tweaks the existing card stays valid.
+Then compile ONCE (`assistant apps refresh <name>` or `app_refresh(app_id)`) unless you used `app_update`, which already recompiled. If the change is substantial, `app_open(app_id, open_mode: "preview")` for a fresh card; for small tweaks the existing card stays valid.
 
 > ⚠️ **`skill_load("app-builder")` is required before every `app_*` call** (including the first `app_create`). The skill can auto-unload between turns; without the reload, `app_refresh` / `app_open` error with "not currently active." It's idempotent — call it every time.
 
@@ -350,7 +353,7 @@ Slide decks are a different domain — skip app patterns (contextual headers, se
 ## SKILL COMPLETE WHEN
 
 - [ ] Request was scoped: personal build (sandbox) or complex/shippable (handed off to a project folder + coding agent)
-- [ ] **Sandbox path:** `app_create` returned an `app_id`; all files written via `file_write`; `app_refresh` ran ONCE clean; `app_open(open_mode: "preview")` rendered the card; user told what was built (3-6 bullets); iterations reflected live
+- [ ] **Sandbox path:** `app_create` returned an `app_id`; all files written via `file_write`; compile ran ONCE clean (`assistant apps refresh` or `app_refresh`); `app_open(open_mode: "preview")` rendered the card; user told what was built (3-6 bullets); iterations reflected live
 - [ ] **Handoff path:** project folder established; coding agent spawned via `acp_spawn({ task, cwd })`; user told work continues in the folder
 
 ---

package/src/config/bundled-skills/app-builder/references/CUSTOM_ROUTES.md

@@ -143,7 +143,7 @@ Older routes were written with a second `context` argument (`context.assistantEv
 
 ## Key rules
 
-- Always create the route handler files via `file_write` before calling `app_refresh`
+- Always create the route handler files via `file_write` before compiling (`app_refresh` or `assistant apps refresh`)
 - Export an optional `description` string for CLI discoverability (`assistant routes list`)
 - Handlers have full Node.js API access — `fs`, `path`, `crypto`, etc.
 - Handlers get a 30-second timeout per request

package/src/config/bundled-skills/messaging/TOOLS.json

@@ -125,7 +125,7 @@
     },
     {
       "name": "messaging_send",
-      "description": "Send a message, reply to a thread, or create a draft. On Gmail and Outlook, always creates a real mailbox draft for review (recipients optional on Outlook). Supports replies (via thread_id), attachments (via attachment_paths, Gmail and Outlook), and all messaging platforms.",
+      "description": "Send a message, reply to a thread, or create a draft. On Gmail and Outlook, always creates a real mailbox draft for review (recipients optional on Outlook). On a channel (Slack, Telegram, Discord, WhatsApp) the message goes out as the channel's own bot, threaded when thread_id names a thread. Supports replies (via thread_id) and attachments (via attachment_paths, Gmail and Outlook).",
       "category": "messaging",
       "risk": "high",
       "input_schema": {
@@ -133,11 +133,11 @@
         "properties": {
           "platform": {
             "type": "string",
-            "description": "Platform (e.g. \"gmail\"). Auto-detected if only one is connected. Slack is not supported — use the Slack Web API directly."
+            "description": "Platform (e.g. \"gmail\", \"slack\", \"telegram\", \"discord\"). Auto-detected if only one is connected."
           },
           "account": {
             "type": "string",
-            "description": "Email address of the account to use. Required when multiple accounts are connected for the same platform. If omitted, uses the most recently connected account."
+            "description": "Email address of the account to use. Required when multiple accounts are connected for the same email platform. If omitted, uses the most recently connected account. Does not apply to a channel: a channel send goes out as the channel's own bot."
           },
           "conversation_id": {
             "type": "string",

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

@@ -1,7 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 
-import { isChannelId } from "../../../../channels/types.js";
 import type { OutboundAttachment } from "../../../../messaging/provider-types.js";
 import {
   createDraft,
@@ -16,11 +15,10 @@ import {
   toOutlookFileAttachments,
 } from "../../../../messaging/providers/outlook/client.js";
 import type { OutlookDraftMessage } from "../../../../messaging/providers/outlook/types.js";
-import { resolveProactiveHomeConversation } from "../../../../notifications/conversation-pairing.js";
-import { recordDeliveredChannelPost } from "../../../../notifications/delivered-post-record.js";
-import { getConversation } from "../../../../persistence/conversation-crud.js";
-import { syncMessageToDisk } from "../../../../persistence/conversation-disk-view.js";
-import { normalizeExternalThreadId } from "../../../../persistence/external-conversation-store.js";
+import {
+  isProactivelyAddressable,
+  sendChannelText,
+} from "../../../../runtime/channel-send.js";
 import {
   isAbortLikeError,
   throwIfCancelled,
@@ -29,7 +27,6 @@ import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
-import { getLogger } from "../../../../util/logger.js";
 import { guessMimeType } from "../../../../util/mime-type.js";
 import {
   err,
@@ -42,8 +39,6 @@ import {
   resolveProvider,
 } from "./shared.js";
 
-const log = getLogger("messaging-send");
-
 /** Read attachment files from disk into in-memory parts for outbound sending. */
 async function readAttachments(paths: string[]): Promise<OutboundAttachment[]> {
   return Promise.all(
@@ -58,123 +53,6 @@ async function readAttachments(paths: string[]): Promise<OutboundAttachment[]> {
 /** Email providers that accept file attachments on outbound sends. */
 const ATTACHMENT_CAPABLE_PLATFORMS = new Set(["gmail", "outlook"]);
 
-/**
- * Record a message the provider just accepted where the chat's proactive
- * posts live, so the chat's own conversation and `recall` can see what was
- * sent from elsewhere (a scheduled run, another conversation).
- *
- * Only channel providers have such a home; an email send is tool-mediated
- * and has no chat conversation. The row is written after the provider
- * returned the message id, never before, and carries that id on its
- * envelope and in `channel_outbound_posts` like every other post the daemon
- * makes.
- *
- * A send into the sending turn's own chat writes no row: its tool call and
- * result already sit in that conversation's history, and a second assistant
- * row beside the tool pair would break history repair. Whether the send is
- * "its own" is decided by the delivered target against the turn, not by the
- * home: the turn arrived on a channel, in a chat, in a thread (the turn-local
- * snapshot on the tool context), and a post the provider delivered to exactly
- * that place is a same-conversation send even when the chat's home resolves
- * elsewhere. The delivered thread is the one the provider reports, not the
- * one requested: a provider that ignores the request lands the post in the
- * thread-less chat, and the record must say so; a post into a thread is
- * recorded in the thread's own conversation, where its replies arrive. The home
- * comparison stays as the second test, for a sender that arrived through no
- * channel but is the home. The post is then in the outbound index only
- * through no path, which is the same class as a raw API send and is deferred
- * with it.
- *
- * Failures here never fail the send: the message is already out.
- */
-async function recordSentChannelPost(params: {
-  providerId: string;
-  externalChatId: string;
-  /** The thread the provider delivered into, as it reported it. */
-  deliveredThreadId: string | undefined;
-  text: string;
-  providerMessageId: string;
-  sender: ToolContext;
-}): Promise<void> {
-  const { providerId, externalChatId, sender } = params;
-  if (!isChannelId(providerId) || !params.providerMessageId) {
-    return;
-  }
-  try {
-    if (
-      isSendIntoOwnChat(
-        sender,
-        providerId,
-        externalChatId,
-        params.deliveredThreadId,
-      )
-    ) {
-      return;
-    }
-    const home = await resolveProactiveHomeConversation({
-      sourceChannel: providerId,
-      externalChatId,
-      threadId: params.deliveredThreadId,
-      source: "notification",
-      conversationType: "background",
-      title: `Messages to ${externalChatId}`,
-    });
-    if (home.conversationId === sender.conversationId) {
-      return;
-    }
-    const recorded = await recordDeliveredChannelPost({
-      conversationId: home.conversationId,
-      channel: providerId,
-      externalChatId,
-      ...(params.deliveredThreadId
-        ? { threadId: params.deliveredThreadId }
-        : {}),
-      text: params.text,
-      providerMessageId: params.providerMessageId,
-      crossPostedFrom: sender.conversationId,
-    });
-    const homeConversation = getConversation(home.conversationId);
-    if (homeConversation) {
-      syncMessageToDisk(
-        home.conversationId,
-        recorded.messageId,
-        homeConversation.createdAt,
-      );
-    }
-  } catch (e) {
-    log.warn(
-      { err: e, provider: providerId, externalChatId },
-      "Failed to record the sent message in the chat's conversation",
-    );
-  }
-}
-
-/**
- * True when the delivered chat and thread are the ones the sending turn
- * arrived in. Reads the turn-local snapshot the tool context carries
- * (`executionChannel`, `requesterChatId`, `sourceThreadId`), never the live
- * binding, which a concurrent inbound can rewrite while this call runs.
- * Thread ids compare in the binding store's normalized form, so an absent
- * thread on both sides matches and a thread-less delivery never matches a
- * turn that arrived in a thread.
- */
-function isSendIntoOwnChat(
-  sender: ToolContext,
-  channel: string,
-  externalChatId: string,
-  deliveredThreadId: string | undefined,
-): boolean {
-  if (!sender.executionChannel || !sender.requesterChatId) {
-    return false;
-  }
-  return (
-    sender.executionChannel === channel &&
-    sender.requesterChatId === externalChatId &&
-    normalizeExternalThreadId(sender.sourceThreadId) ===
-      normalizeExternalThreadId(deliveredThreadId)
-  );
-}
-
 export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -197,9 +75,62 @@ export async function run(
   throwIfCancelled(context);
 
   try {
-    const provider = await resolveProvider(platform);
+    // A channel whose transport can be addressed from a named chat is sent
+    // through the transport, which is the one send implementation for that
+    // channel, records what it sent, and reaches channels with no messaging
+    // provider at all. A platform named outright is checked first; one
+    // auto-detected from the connected providers is checked the same way.
+    const namedChannel =
+      platform && isProactivelyAddressable(platform) ? platform : undefined;
+    const provider = namedChannel ? undefined : await resolveProvider(platform);
+    const channel =
+      namedChannel ??
+      (provider && isProactivelyAddressable(provider.id)
+        ? provider.id
+        : undefined);
+
+    if (channel) {
+      if (attachmentPaths?.length) {
+        return err("Attachments are only supported on Gmail and Outlook.");
+      }
+      // A channel's transport sends as the channel's one bot identity, so an
+      // account cannot select where the send goes out from. Refusing is
+      // safer than silently sending from the default account.
+      if (input.account) {
+        return err(
+          `account does not apply to ${channel}: a channel send goes out as the channel's own bot.`,
+        );
+      }
+      // Recheck: provider resolution above is an await, and this posts to
+      // the channel.
+      throwIfCancelled(context);
+      const sent = await sendChannelText({
+        channel,
+        target: {
+          kind: "chat",
+          chatId: conversationId,
+          ...(threadId ? { threadId } : {}),
+        },
+        text,
+        renderRichly: true,
+        assistantId: context.assistantId,
+        sender: {
+          conversationId: context.conversationId,
+          executionChannel: context.executionChannel,
+          requesterChatId: context.requesterChatId,
+          sourceThreadId: context.sourceThreadId,
+        },
+      });
+      const threadSuffix = sent.threadId
+        ? `, "thread_id": "${sent.threadId}"`
+        : "";
+      return ok(`Message sent (ID: ${sent.lastMessageId}${threadSuffix}).`);
+    }
+    if (!provider) {
+      throw new Error(`Messaging provider "${platform}" not found.`);
+    }
 
-    // Reject attachments on platforms that can't carry them (e.g. Telegram, WhatsApp).
+    // Reject attachments on platforms that can't carry them.
     if (
       attachmentPaths?.length &&
       !ATTACHMENT_CAPABLE_PLATFORMS.has(provider.id)
@@ -426,7 +357,14 @@ export async function run(
       );
     }
 
-    // Non-email platforms
+    // A provider with a send of its own and no direct transport (a plugin's,
+    // for instance). Its send is tool-mediated and has no chat conversation
+    // to record in.
+    if (!provider.sendMessage) {
+      return err(
+        `${provider.displayName} cannot send from here: it has no send of its own and no channel transport to address.`,
+      );
+    }
     const attachments = attachmentPaths?.length
       ? await readAttachments(attachmentPaths)
       : undefined;
@@ -442,16 +380,6 @@ export async function run(
     const threadSuffix = result.threadId
       ? `, "thread_id": "${result.threadId}"`
       : "";
-
-    await recordSentChannelPost({
-      providerId: provider.id,
-      externalChatId: conversationId,
-      deliveredThreadId: result.threadId,
-      text,
-      providerMessageId: result.id,
-      sender: context,
-    });
-
     return ok(`Message sent (ID: ${result.id}${threadSuffix}).`);
   } catch (e) {
     // A cancelled turn is not a send failure: let it reach the executor's

package/src/config/bundled-skills/phone-calls/references/TRANSCRIPTS.md

@@ -23,7 +23,7 @@ sqlite3 "$VELLUM_WORKSPACE_DIR/data/db/assistant.db" \
 
 This returns all messages in chronological order with:
 
-- `role: "user"` - caller speech (prefixed with `[SPEAKER]` tags) and system events
+- `role: "user"` - caller speech and system events
 - `role: "assistant"` - assistant responses, including `text` content and any `tool_use`/`tool_result` blocks
 
 ## Quick one-liner for the most recent call

package/src/config/bundled-skills/screen-annotation/SKILL.md

@@ -124,7 +124,14 @@ their ear. Silence is the cue that it is their turn.
 
 **Advance on evidence, not on time.** Move to the next step when a fresh
 picture shows this one done, or when they tell you it is. Do not move on
-because a plausible amount of time has passed. If the next picture shows the
+because a plausible amount of time has passed.
+
+The most direct telling is automatic. When the user clicks the control an
+arrow is pointing at, a message arrives as their turn saying they clicked it,
+by name, and that mark comes down on its own. Treat it as the step done: say
+what comes next and point at it. Nothing arrives for a click anywhere else,
+and nothing arrives for a ring, so for those the picture and their words are
+still the evidence. If the next picture shows the
 step not done, or done to the wrong thing, point at the same place again with
 a shorter caption and say what you saw. Pointing at the next step while the
 previous one is still open is how someone ends up two steps behind a mark.

package/src/config/bundled-skills/screen-annotation/tools/screen-annotation.test.ts

@@ -53,7 +53,10 @@ describe("screen_point_at", () => {
     );
 
     expect(result.isError).toBe(true);
-    expect(result.content).toContain("connected desktop client");
+    expect(result.content).toContain(
+      "The Vellum desktop app is needed to view or control your screen",
+    );
+    expect(result.content).toContain("https://www.vellum.ai/downloads");
   });
 
   /** Drawing on the user's screen is a side effect a stopped turn must not have. */

package/src/config/bundled-skills/skill-management/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "scaffold_managed_skill",
-      "description": "Create or update a managed skill in {workspaceDir}/skills. The skill becomes available for skill_load when a valid top-level SKILL.md is written under the skill directory. Never persist a skill without explicit user consent. Before persisting, test the snippet: write to a temp file with bash and run with `bun run /tmp/vellum-eval/snippet.ts`. Iterate up to 3 attempts, then ask the user. Clean up temp files after. Do not use file_write for temp files outside the working directory. After a skill is written, the next turn may run in a recreated conversation due to file-watcher eviction - continue normally.",
+      "description": "Create or update a managed skill in {workspaceDir}/skills. The skill becomes available for skill_load when a valid top-level SKILL.md is written under the skill directory. Never persist a skill without explicit user consent. Before persisting, test the snippet: write to a temp file with bash and run with `bun run /tmp/vellum-eval/snippet.ts`. Iterate up to 3 attempts, then ask the user. Clean up temp files after. Do not use file_write for temp files outside the working directory.",
       "category": "skills",
       "risk": "high",
       "input_schema": {
@@ -92,7 +92,7 @@
     },
     {
       "name": "delete_managed_skill",
-      "description": "Delete a managed skill directory from {workspaceDir}/skills. Never delete a skill without explicit user confirmation. After deletion, the next turn may run in a recreated conversation due to file-watcher eviction - continue normally.",
+      "description": "Delete a managed skill directory from {workspaceDir}/skills. Never delete a skill without explicit user confirmation.",
       "category": "skills",
       "risk": "high",
       "input_schema": {

package/src/config/default-profile-catalog.ts

@@ -137,7 +137,7 @@ const VELLUM_PROFILE_IMPLS: ProfileImpls = {
     // The managed latency class, also what the live-voice front model runs on.
     // Its leading tokens are the turn-taking verdict, so what this profile
     // optimizes is the tail of time-to-first-token rather than the median: a
-    // verdict slower than `liveVoice.frontModel.endpointDecisionTimeoutMs`
+    // verdict slower than `voice.frontModel.endpointDecisionTimeoutMs`
     // trips the speculative fail-open commit in live-voice-session.ts, which
     // is audible dead air.
     //

package/src/config/env.ts

@@ -229,8 +229,8 @@ export function setPlatformAssistantId(value: string | undefined): void {
  * Platform assistant ID — UUID of this assistant on the platform.
  *
  * Resolved from the in-memory override (populated by providers-setup
- * rehydration from the credential store at daemon startup, or by
- * secret-routes when the platform pushes the value).
+ * rehydration via platform validate, or by secret-routes when the
+ * platform pushes the value).
  */
 export function getPlatformAssistantId(): string {
   return _platformAssistantIdOverride ?? "";

package/src/config/feature-flag-registry.json

@@ -29,18 +29,6 @@
       "description": "Enable user-hosted onboarding flow",
       "defaultEnabled": false
     },
-    {
-      "id": "proactive-tips",
-      "scope": "client",
-      "key": "proactive-tips",
-      "label": "Proactive Tips",
-      "description": "Gates the dismissible proactive tip card in the web sidebar. String-valued so future A/B arms can be added as new values.",
-      "defaultEnabled": "off",
-      "values": [
-        "off",
-        "on"
-      ]
-    },
     {
       "id": "vision-mode",
       "scope": "client",
@@ -523,6 +511,14 @@
       "label": "Send User Message Tool",
       "description": "Route all user-facing assistant text through the send_user_message tool instead of streamed assistant text",
       "defaultEnabled": false
+    },
+    {
+      "id": "assistant-desktop",
+      "scope": "assistant",
+      "key": "assistant-desktop",
+      "label": "Assistant Desktop",
+      "description": "Streams an interactive desktop from a containerized assistant pod to the web client over /v1/desktop/stream. Off: no desktop affordance is rendered. On: the chat header offers a desktop panel that views and controls the pod's display.",
+      "defaultEnabled": false
     }
   ]
 }

package/src/config/memory-v3-gate.test.ts

@@ -6,6 +6,7 @@ import {
   isMemoryV1Active,
   isMemoryV2ExplicitlyDisabled,
   isMemoryV3Live,
+  isSkillImprovementActive,
   isV2InjectionEngineActive,
   isV3TierActive,
   usesConceptPageMemory,
@@ -55,12 +56,16 @@ function makeConfig(
   enabled: TriState,
   v2Enabled: TriState,
   v3Live: TriState,
+  skillImprovement?: boolean,
 ): AssistantConfig {
   return {
     memory: {
       ...(enabled === undefined ? {} : { enabled }),
       ...(v2Enabled === undefined ? {} : { v2: { enabled: v2Enabled } }),
       ...(v3Live === undefined ? {} : { v3: { live: v3Live } }),
+      ...(skillImprovement === undefined
+        ? {}
+        : { retrospective: { skillImprovement } }),
     },
   } as AssistantConfig;
 }
@@ -296,6 +301,32 @@ describe("v1-staleness guard is one condition", () => {
  * proc-to-skills alias of `isMemoryV3Live` (which did not). One predicate now
  * answers for both features.
  */
+describe("skill improvement gate", () => {
+  test("defaults on for a live v3 tier", () => {
+    expect(isSkillImprovementActive(makeConfig(true, undefined, true))).toBe(
+      true,
+    );
+    expect(isSkillImprovementActive(makeConfig(undefined, undefined, true))).toBe(
+      true,
+    );
+  });
+
+  test("explicit opt-out disables skill improvement without disabling v3", () => {
+    const config = makeConfig(true, undefined, true, false);
+
+    expect(isV3TierActive(config)).toBe(true);
+    expect(isSkillImprovementActive(config)).toBe(false);
+  });
+
+  test("requires the live v3 tier even when explicitly enabled", () => {
+    const v2Config = makeConfig(true, true, false, true);
+    const memoryOffConfig = makeConfig(false, undefined, true, true);
+
+    expect(isSkillImprovementActive(v2Config)).toBe(false);
+    expect(isSkillImprovementActive(memoryOffConfig)).toBe(false);
+  });
+});
+
 describe("v3 tier is one condition", () => {
   test("memory off suppresses the v3 tier even with memory.v3.live set", () => {
     const config = makeConfig(false, undefined, true);

package/src/config/memory-v3-gate.ts

@@ -81,28 +81,32 @@ export function isMemoryV3Live(config: AssistantConfig): boolean {
  * FEATURE asks this predicate; only the injection-suppression checks that must
  * mirror the raw `memory.v3.live` key ask {@link isMemoryV3Live} directly.
  *
- * The two features gated on it, and why they must agree:
+ * The memory concept graph is gated on it: both `GET /memory-graph`
+ * (`supported`) and the cheap `graph_supported` bit on `GET /memory/stats`
+ * must agree with whether the graph can build from the v3 concept-page
+ * substrate.
  *
- * - The memory concept graph — the single source of truth for both
- *   `GET /memory-graph` (`supported`) and the cheap `graph_supported` bit on
- *   `GET /memory/stats`, so the advertised capability and the actual build can
- *   never drift. The graph builds off the v3 concept-page substrate.
- * - Procedural-memory-as-skills — the retrospective's skill-authoring step and
- *   its permission grant. Scoped to the v3 tier because skill retrieval rides
- *   the v3 lanes and the usage-prune stage lives in the v3 maintain job. That
- *   prune ships observe-first: with `memory.maintenance.skillPruneDays` at its
- *   default (`null`) it reports stale assistant-authored skills
- *   (`prunableSkills`) but deletes none — so a v3-tier assistant authors skills
- *   without an automatic retirement bound until a positive `skillPruneDays` is
- *   configured.
- *
- * Both write into memory on the user's behalf, so both honor the Memory
- * opt-out identically: one predicate, one answer.
+ * Retrospective skill improvement is a separate optional v3-tier feature.
+ * Ask {@link isSkillImprovementActive} for it so an operator can stop managed
+ * skill authoring without turning off ordinary retrospective memory capture.
  */
 export function isV3TierActive(config: AssistantConfig): boolean {
   return isMemoryEnabled(config) && isMemoryV3Live(config);
 }
 
+/**
+ * Whether a retrospective may turn observed procedures into managed skills.
+ * This requires the v3 tier because skills are retrieved through its memory
+ * substrate, and it honors the retrospective-specific opt-out without
+ * disabling ordinary retrospective fact retention.
+ */
+export function isSkillImprovementActive(config: AssistantConfig): boolean {
+  return (
+    isV3TierActive(config) &&
+    config.memory?.retrospective?.skillImprovement !== false
+  );
+}
+
 /**
  * Minimal structural view of the memory config the concept-page gate reads.
  * Accepting the shape (rather than the full `MemoryConfig`) lets call sites