@vellumai/assistant 0.11.3 → 0.11.4-staging.1

package/src/channels/__tests__/plugin-channel-declarations.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Channels that installed plugins bring.
+ *
+ * `getWorkspacePluginsDir` is mocked to a scratch directory so these read real
+ * files off disk without touching the machine's workspace.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+const workspacePluginsDir = mkdtempSync(join(tmpdir(), "plugin-channels-"));
+
+const realPlatform = await import("../../util/platform.js");
+
+mock.module("../../util/platform.js", () => ({
+  ...realPlatform,
+  getWorkspacePluginsDir: () => workspacePluginsDir,
+}));
+
+const { discoverPluginChannels } = await import(
+  "../plugin-channel-declarations.js"
+);
+
+interface PluginOptions {
+  /** Contents of `channels/ingress.json`; omit for a plugin with no ingress. */
+  ingress?: string;
+  manifest?: Record<string, unknown>;
+}
+
+const INGRESS = JSON.stringify({
+  routes: [{ path: "events", kind: "http", description: "inbound" }],
+});
+
+function writePlugin(name: string, options: PluginOptions = {}): string {
+  const dir = join(workspacePluginsDir, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name, ...options.manifest }),
+  );
+  if (options.ingress !== undefined) {
+    mkdirSync(join(dir, "channels"), { recursive: true });
+    writeFileSync(join(dir, "channels", "ingress.json"), options.ingress);
+  }
+  return dir;
+}
+
+beforeEach(() => {
+  rmSync(workspacePluginsDir, { recursive: true, force: true });
+  mkdirSync(workspacePluginsDir, { recursive: true });
+});
+
+afterAll(() => {
+  rmSync(workspacePluginsDir, { recursive: true, force: true });
+});
+
+describe("discoverPluginChannels", () => {
+  test("a plugin is a channel because it declares ingress", async () => {
+    writePlugin("courier", {
+      ingress: INGRESS,
+      manifest: {
+        displayName: "Courier",
+        description: "Reach the assistant by carrier pigeon.",
+        icon: "send",
+      },
+    });
+
+    expect(await discoverPluginChannels()).toEqual([
+      {
+        id: "courier",
+        source: "plugin:courier",
+        label: "Courier",
+        subtitle: "Reach the assistant by carrier pigeon.",
+        icon: "send",
+        supportsVerification: false,
+        setupMessages: {
+          guardian: "I want to set up Courier. Can you help me?",
+          contact:
+            "I'd like to reach you on Courier. Can you help me get set up?",
+        },
+      },
+    ]);
+  });
+
+  test("ignores a plugin that declares no ingress", async () => {
+    // Presentation alone does not make a channel: reaching the assistant from
+    // outside is what one is, and ingress is where that is declared.
+    writePlugin("notes", { manifest: { displayName: "Notes", icon: "send" } });
+
+    expect(await discoverPluginChannels()).toEqual([]);
+  });
+
+  test("surfaces a channel whose ingress the gateway would reject", async () => {
+    // Validation belongs to the gateway, which owns the schema. A plugin with
+    // a broken declaration is a channel with broken ingress, and saying so
+    // beats dropping it off the page a guardian would look at.
+    writePlugin("courier", {
+      ingress: "{ not json",
+      manifest: { displayName: "Courier" },
+    });
+
+    expect((await discoverPluginChannels())[0]?.label).toBe("Courier");
+  });
+
+  test("skips a disabled plugin", async () => {
+    // Same source of truth the loader uses for hooks, tools and routes: a
+    // disabled plugin would otherwise offer a setup flow that cannot run.
+    const dir = writePlugin("courier", { ingress: INGRESS });
+    writeFileSync(join(dir, ".disabled"), "");
+
+    expect(await discoverPluginChannels()).toEqual([]);
+  });
+
+  test("refuses to let a plugin take a built-in channel's id", async () => {
+    // Two rows sharing an id would be ambiguous to any client keying on one,
+    // and letting the plugin win would let it impersonate a built-in.
+    writePlugin("slack", {
+      ingress: INGRESS,
+      manifest: { displayName: "Slack" },
+    });
+
+    expect(await discoverPluginChannels()).toEqual([]);
+  });
+
+  test("titles a plugin that names no display name", async () => {
+    // Presentation is best-effort, so a bare manifest costs a nicer title and
+    // never the row itself.
+    writePlugin("meeting-bot", { ingress: INGRESS });
+
+    expect(await discoverPluginChannels()).toMatchObject([
+      {
+        id: "meeting-bot",
+        source: "plugin:meeting-bot",
+        label: "Meeting Bot",
+        subtitle: "Provided by the Meeting Bot plugin",
+        icon: "message-square",
+      },
+    ]);
+  });
+
+  test("still lists a channel whose manifest cannot be read", async () => {
+    // The directory is the plugin's identity, so an unparseable manifest
+    // costs its presentation and not its existence.
+    const dir = writePlugin("courier", { ingress: INGRESS });
+    writeFileSync(join(dir, "package.json"), "{ not json");
+
+    expect((await discoverPluginChannels())[0]?.label).toBe("Courier");
+  });
+
+  test("never claims a plugin channel supports verification", async () => {
+    // There is no client-side verification flow for one, so clients render it
+    // display-only rather than pre-warming a status that cannot arrive.
+    writePlugin("courier", { ingress: INGRESS });
+
+    expect((await discoverPluginChannels())[0]?.supportsVerification).toBe(
+      false,
+    );
+  });
+});

package/src/channels/config.ts

@@ -86,6 +86,19 @@ const CHANNEL_POLICIES = {
       conversationStrategy: "continue_existing_conversation",
     },
   },
+  plugin: {
+    notification: {
+      // Every plugin-brought channel shares this row, so the answer has to
+      // hold for all of them. A reply to an inbound plugin message routes by
+      // `replyCallbackUrl` and does not read this flag; proactive notification
+      // does, and it needs a guardian binding plus a destination resolver to
+      // reach. Neither exists per-plugin, and `NotificationChannel` is derived
+      // from this flag, so enabling it would let the decision engine pick a
+      // channel that resolves to nothing for whichever plugin it landed on.
+      deliveryEnabled: false,
+      conversationStrategy: "continue_existing_conversation",
+    },
+  },
 } as const satisfies Record<ChannelId, ChannelNotificationPolicy>;
 
 export type ChannelPolicies = typeof CHANNEL_POLICIES;

package/src/channels/plugin-channel-declarations.ts

@@ -0,0 +1,108 @@
+/**
+ * Channels that installed plugins bring.
+ *
+ * A plugin is a channel because it declares ingress: `channels/ingress.json`
+ * is the list of routes the outside world may reach it on, and reaching the
+ * assistant from outside is what being a channel means. There is no second
+ * file saying so, and nothing a plugin can set to claim the status without
+ * declaring the reach that constitutes it.
+ *
+ * What the gateway does with that file is a separate matter, and stays the
+ * gateway's: validating the routes, digesting them, holding them behind a
+ * guardian's approval. This reads its presence and nothing else, so a
+ * declaration the gateway rejects still surfaces here. That is the honest
+ * report, the plugin is a channel and its ingress is broken, and it keeps a
+ * schema this module does not own from deciding what a settings page lists.
+ *
+ * Presentation comes from the plugin's own manifest, where a plugin's title,
+ * description and icon already belong. All three are optional and none gate
+ * anything: a plugin with ingress and a bare `package.json` still appears,
+ * titled from its directory.
+ */
+
+import { statSync } from "node:fs";
+import { join } from "node:path";
+
+import { isPluginDisabled } from "../plugins/disabled-state.js";
+import { parsePluginPresentation } from "../plugins/external-plugin-loader.js";
+import { listInstalledPluginDirs } from "../plugins/installed-plugin-dirs.js";
+import { type AvailableChannel, isChannelId } from "./types.js";
+
+/**
+ * The declaration that makes a plugin a channel. Owned by the gateway, which
+ * parses it; named here only to test for it.
+ */
+export const PLUGIN_INGRESS_MANIFEST_RELPATH = "channels/ingress.json";
+
+/** Icon for a plugin naming none. The generic "a message arrives here" glyph. */
+const FALLBACK_ICON = "message-square";
+
+/**
+ * Title for a plugin with no `displayName`.
+ *
+ * Derived rather than defaulted to the raw directory name so `meeting-bot`
+ * reads as "Meeting Bot" beside "Slack" and "Telegram". A plugin whose casing
+ * matters sets `displayName` and this never runs.
+ */
+function titleFromDirectory(name: string): string {
+  return name
+    .split(/[-_]/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+/** True when the plugin declares ingress routes. */
+function declaresIngress(pluginDir: string): boolean {
+  return (
+    statSync(join(pluginDir, PLUGIN_INGRESS_MANIFEST_RELPATH), {
+      throwIfNoEntry: false,
+    })?.isFile() === true
+  );
+}
+
+/**
+ * Every channel brought by an installed, enabled plugin.
+ *
+ * A plugin whose directory name is one of the assistant's own channels is
+ * skipped: two rows sharing an id would be ambiguous to any client keying on
+ * one, and the resolution that lets a plugin win would let it impersonate a
+ * built-in channel. The assistant's keep the name.
+ *
+ * Disabled plugins are skipped too, matching the source of truth the loader
+ * uses for hooks, tools and routes: a disabled plugin holds no ingress either,
+ * and one that reappeared here would offer a setup flow that cannot run.
+ *
+ * Order follows the plugins directory, and is stable for a stable install set.
+ */
+export async function discoverPluginChannels(): Promise<AvailableChannel[]> {
+  const channels: AvailableChannel[] = [];
+
+  for (const { name, dir } of listInstalledPluginDirs()) {
+    if (isPluginDisabled(name) || isChannelId(name) || !declaresIngress(dir)) {
+      continue;
+    }
+    const presentation = await parsePluginPresentation(dir);
+    const label = presentation?.displayName ?? titleFromDirectory(name);
+    channels.push({
+      id: name,
+      source: `plugin:${name}`,
+      label,
+      subtitle: presentation?.description ?? `Provided by the ${label} plugin`,
+      icon: presentation?.icon ?? FALLBACK_ICON,
+      // No client-side verification flow exists for a plugin channel, so
+      // clients render it display-only and never pre-warm a status for it.
+      supportsVerification: false,
+      // Openers for a setup conversation, which is what this field is for.
+      // Deliberately not the verification copy the built-ins carry: there is
+      // no identity to verify here, and inventing that wording would send
+      // someone down a flow that does not exist.
+      setupMessages: {
+        guardian: `I want to set up ${label}. Can you help me?`,
+        contact: `I'd like to reach you on ${label}. Can you help me get set up?`,
+      },
+    });
+  }
+
+  return channels;
+}

package/src/channels/types.ts

@@ -51,6 +51,32 @@ export interface ChannelInfo {
   };
 }
 
+/**
+ * Source that contributes a channel, in the `<kind>[:<id>]` form the tool
+ * catalog and process tree already use: `default` for one the assistant ships,
+ * `plugin:<name>` for one an installed plugin brings.
+ *
+ * Composed from the plugin's install directory rather than from anything it
+ * declares, so a manifest cannot claim to be another source or pass itself off
+ * as built in.
+ */
+export type ChannelSource = "default" | `plugin:${string}`;
+
+/**
+ * A channel as `/v1/channels/available` reports it: the display metadata plus
+ * where it came from.
+ *
+ * `id` widens to a string here because a plugin channel's id is its plugin
+ * name, which is not a member of the closed {@link ChannelId} union. The union
+ * still governs everything the assistant routes, verifies and applies
+ * admission policy to; `source` is what tells a client which kind it is
+ * holding, so nothing has to infer it from the id.
+ */
+export interface AvailableChannel extends Omit<ChannelInfo, "id"> {
+  id: string;
+  source: ChannelSource;
+}
+
 /**
  * Per-channel display metadata for the channels the gateway can currently
  * surface to clients. Add an entry here when surfacing a new channel via
@@ -155,6 +181,10 @@ export const INTERFACE_IDS = [
   // device/service callbacks). Non-interactive — permission prompts route
   // through the guardian system, not an interactive client — and non-host-proxy.
   "route",
+  // Turns a plugin-brought channel delivered through the gateway. One id for
+  // every plugin, matching the `plugin` channel; which plugin it was is in
+  // `sourceMetadata.plugin`.
+  "plugin",
 ] as const;
 
 export type InterfaceId = (typeof INTERFACE_IDS)[number];

package/src/cli/AGENTS.md

@@ -123,10 +123,13 @@ registerFooCommand(program);
    _synchronously_ at command registration (so it can't be a lazy
    `import()`) may stay hoisted behind a scoped
    `// eslint-disable-next-line cli/no-daemon-internals` with a comment
-   explaining why. The only current case is `browser/operation-meta`, in
+   explaining why. The current cases are `browser/operation-meta`, in
    `commands/browser.ts` (it drives synchronous subcommand generation and
    deliberately pulls no Playwright graph) and `commands/browser.help.ts`
-   (which derives the declarative help from the same contract).
+   (which derives the declarative help from the same contract); and
+   `providers/speech-to-text/provider-catalog`, in `commands/stt.help.ts`
+   (a literal map behind type-only imports, which the help text reads to
+   name the providers that serve the batch transcription boundary).
 
 2. **Lazy-import daemon functionality inside the action.** Running daemon
    logic in-process is encouraged where it avoids an IPC round-trip (which

package/src/cli/commands/credentials.help.ts

@@ -293,8 +293,8 @@ encrypted vault with the specified metadata.
 Requires the assistant to be running with at least one connected client.
 
 This command BLOCKS until the user answers the prompt, so it returns only once
-the prompt has already closed. Tell the user what to paste BEFORE running it —
-anything said afterwards reaches them after the input is gone, and pointing
+the prompt has already closed. Tell the user what to paste BEFORE running it.
+Anything said afterwards reaches them after the input is gone, and pointing
 them at a closed prompt makes them re-submit a value that was already received.
 The --label and --description text renders inside the prompt itself, so put the
 instructions there rather than in a follow-up message.

package/src/cli/commands/inference-providers.ts

@@ -519,7 +519,7 @@ function attachLoginChatgptSubcommand(providers: Command): void {
             {
               body: {
                 name: connectionName,
-                provider: "openai",
+                provider: "chatgpt",
                 auth: authInput,
               },
             },

package/src/cli/commands/mcp.help.ts

@@ -7,7 +7,8 @@ export const mcpHelp: CliCommandHelp = {
   description: "Manage MCP (Model Context Protocol) servers",
   helpText: `
 MCP servers extend the assistant's capabilities with external tools. Servers
-are configured in the assistant's config.json under the mcp.servers key. Each
+are configured in the assistant's config.json under the mcp.servers key, or
+declared by an installed plugin in its root mcp.json. Each
 server uses one of three transport types:
 
   stdio             Local process communicating over stdin/stdout
@@ -28,13 +29,21 @@ Examples:
       description: "List configured MCP servers and their status",
       options: [{ flags: "--json", description: "Output as JSON" }],
       helpText: `
-Shows each configured MCP server with its current status and configuration:
+Shows each MCP server with its current status and configuration. Servers come
+from two places: the mcp.servers key in config.json, and the root mcp.json of
+any installed plugin that declares one.
 
-  Name         The server identifier used in config.json
-  Status       Health check result:
+  Name         The server identifier
+  Status       Health check result for workspace servers:
                  ✓  Connected and responding
                  ✗  Error or disabled
                  !  Needs authentication (OAuth required)
+               Plugin-declared servers report "declared" instead. They are
+               listed but not connected by the assistant, and they are not
+               health-checked, so no stored credential can reach a URL a
+               plugin chose.
+  Source       Shown only for plugin-declared servers, naming the plugin.
+               Servers from config.json print no Source line.
   Transport    stdio, sse, or streamable-http
   URL/Command  The server URL (sse/streamable-http) or command (stdio)
   Risk         Default risk level: low, medium, or high

package/src/cli/commands/mcp.ts

@@ -24,6 +24,10 @@ interface McpServerEntry {
   defaultRiskLevel: string;
   allowedTools?: string[];
   blockedTools?: string[];
+  /** Workspace `config.json` or a plugin's `mcp.json`. */
+  source?: "workspace" | "plugin";
+  /** Plugin that declared the server, when `source` is `plugin`. */
+  pluginName?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -81,6 +85,11 @@ async function pollMcpAuthStatus(
 function printServerEntry(entry: McpServerEntry): void {
   log.info(`  ${entry.id}`);
   log.info(`    Status:    ${entry.status}`);
+  // Only plugin-declared servers name a source. A workspace server is the
+  // default case and printing "workspace" on every one of them is noise.
+  if (entry.source === "plugin") {
+    log.info(`    Source:    plugin (${entry.pluginName ?? "unknown"})`);
+  }
   log.info(`    Transport: ${entry.transport?.type ?? "unknown"}`);
   if (entry.transport?.type === "stdio") {
     log.info(

package/src/cli/commands/memory/__tests__/memory-v3.test.ts

@@ -2,12 +2,13 @@
  * Tests for the `assistant memory v3` CLI subgroup (section-lane model).
  *
  * Validates:
- *   - Subcommand registration (rebuild-index, backfill-sections) under
- *     `memory v3`.
- *   - Each subcommand maps to the right `cliIpcCall` method.
+ *   - Subcommand registration (rebuild-index, backfill-sections, gate-stats)
+ *     under `memory v3`.
+ *   - `rebuild-index` and `backfill-sections` route through IPC to the daemon.
  *   - `backfill-sections` passes a long IPC timeout (the one-time full-corpus
- *     embed easily outlasts the default 60s), while `rebuild-index` does not.
- *   - IPC error paths return a non-zero exit code without throwing.
+ *     embed easily outlasts the default 60s).
+ *   - `gate-stats` calls handleMemoryV3GateStats directly — no daemon required.
+ *   - Error paths return a non-zero exit code without throwing.
  */
 
 import { beforeEach, describe, expect, mock, test } from "bun:test";
@@ -39,6 +40,47 @@ let mockIpcResult: {
 /** Captured log output for assertion. */
 let logOutput: string[] = [];
 
+/** Shared fake gate-stats payload used across gate-stats tests. */
+const fakeGateStats = {
+  lookbackDays: 30,
+  totalRuns: 10,
+  buckets: [
+    {
+      pageCountRange: "0–9",
+      total: 2,
+      scored: 1,
+      passed: 2,
+      scoredPassRate: 1,
+      reasons: { dense_pass: 1, dense_disabled: 1 },
+    },
+    {
+      pageCountRange: "10–49",
+      total: 5,
+      scored: 4,
+      passed: 3,
+      scoredPassRate: 0.75,
+      reasons: { dense_pass: 3, fail_no_signal: 1 },
+    },
+    {
+      pageCountRange: "50–199",
+      total: 2,
+      scored: 2,
+      passed: 1,
+      scoredPassRate: 0.5,
+      reasons: { dense_pass: 1, fail_no_signal: 1 },
+    },
+    {
+      pageCountRange: "200+",
+      total: 1,
+      scored: 1,
+      passed: 0,
+      scoredPassRate: 0,
+      reasons: { fail_no_signal: 1 },
+    },
+  ],
+  unknownPageCount: { total: 0, passed: 0, reasons: {} },
+};
+
 // ---------------------------------------------------------------------------
 // Mocks
 // ---------------------------------------------------------------------------
@@ -68,6 +110,33 @@ mock.module("../../../../util/logger.js", () => ({
   getCliLogger: () => fakeLogger,
 }));
 
+// ---------------------------------------------------------------------------
+// gate-stats direct-invocation mocks
+// ---------------------------------------------------------------------------
+
+/** Args captured from the last handleMemoryV3GateStats call. */
+let lastGateStatsArgs: { lookbackDays: number; db: unknown } | null = null;
+
+/** What handleMemoryV3GateStats returns, or an error to throw. */
+let gateStatsImpl: (() => unknown) | null = null;
+
+mock.module(
+  "../../../../plugins/defaults/memory/src/memory-v3-routes.js",
+  () => ({
+    handleMemoryV3GateStats: (lookbackDays: number, db: unknown) => {
+      lastGateStatsArgs = { lookbackDays, db };
+      if (gateStatsImpl) {
+        return gateStatsImpl();
+      }
+      return fakeGateStats;
+    },
+  }),
+);
+
+mock.module("../../../../persistence/db-connection.js", () => ({
+  getTelemetrySqlite: () => ({}),
+}));
+
 // ---------------------------------------------------------------------------
 // Import modules under test (after mocks)
 // ---------------------------------------------------------------------------
@@ -135,6 +204,8 @@ beforeEach(() => {
     ok: true,
     result: { articles: 3, sections: 12, failures: 0 },
   };
+  lastGateStatsArgs = null;
+  gateStatsImpl = null;
   logOutput = [];
   process.exitCode = 0;
 });
@@ -155,6 +226,7 @@ describe("subcommand registration", () => {
       "backfill-sections",
       "eval",
       "eval-tally",
+      "gate-stats",
       "rebuild-index",
     ]);
   });
@@ -236,3 +308,54 @@ describe("memory v3 backfill-sections", () => {
     expect(exitCode).toBe(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// gate-stats (direct invocation — no daemon required)
+// ---------------------------------------------------------------------------
+
+describe("memory v3 gate-stats", () => {
+  test("calls handleMemoryV3GateStats directly with default lookback (no IPC)", async () => {
+    const { exitCode } = await runCommand(["memory", "v3", "gate-stats"]);
+
+    expect(exitCode).toBe(0);
+    // Must NOT have gone through IPC.
+    expect(lastIpcCall).toBeNull();
+    // Must have called the handler directly with the default lookback.
+    expect(lastGateStatsArgs!.lookbackDays).toBe(30);
+  });
+
+  test("forwards --lookback-days directly to handleMemoryV3GateStats", async () => {
+    await runCommand(["memory", "v3", "gate-stats", "--lookback-days", "7"]);
+
+    expect(lastIpcCall).toBeNull();
+    expect(lastGateStatsArgs!.lookbackDays).toBe(7);
+  });
+
+  test("prints formatted table on success (no --json)", async () => {
+    await runCommand(["memory", "v3", "gate-stats"]);
+
+    expect(logOutput.some((l) => l.includes("Gate-stats"))).toBe(true);
+    expect(logOutput.some((l) => l.includes("10–49"))).toBe(true);
+    expect(logOutput.some((l) => l.includes("75.0%"))).toBe(true);
+  });
+
+  test("emits raw JSON with --json", async () => {
+    await runCommand(["memory", "v3", "gate-stats", "--json"]);
+
+    const raw = logOutput.join("");
+    const parsed = JSON.parse(raw) as typeof fakeGateStats;
+    expect(parsed.totalRuns).toBe(10);
+    expect(parsed.buckets).toHaveLength(4);
+  });
+
+  test("exits with code 1 when handleMemoryV3GateStats throws", async () => {
+    gateStatsImpl = () => {
+      throw new Error("telemetry DB locked");
+    };
+
+    const { exitCode } = await runCommand(["memory", "v3", "gate-stats"]);
+
+    expect(exitCode).toBe(1);
+    expect(logOutput.some((l) => l.includes("telemetry DB locked"))).toBe(true);
+  });
+});

package/src/cli/commands/memory/index.help.ts

@@ -606,7 +606,9 @@ that live state safely.
 
 Examples:
   $ assistant memory v3 rebuild-index
-  $ assistant memory v3 backfill-sections`,
+  $ assistant memory v3 backfill-sections
+  $ assistant memory v3 gate-stats
+  $ assistant memory v3 gate-stats --lookback-days 7 --json`,
       subcommands: [
         {
           name: "rebuild-index",
@@ -716,6 +718,46 @@ Examples:
   $ assistant memory v3 eval --snapshot .mv3/snapshot/concepts --staging .mv3/staging --out .mv3/eval
   $ assistant memory v3 eval --snapshot .mv3/snapshot/concepts --staging .mv3/staging --out .mv3/eval --turns-file .mv3/eval/key.json
   $ assistant memory v3 eval --snapshot .mv3/snapshot/concepts --staging .mv3/staging --out .mv3/eval --exclude-conversation <migration-conv-id>`,
+        },
+        {
+          name: "gate-stats",
+          description:
+            "Show injection gate pass rates bucketed by corpus size (read-only)",
+          options: [
+            {
+              flags: "--lookback-days <n>",
+              description: "Days of telemetry to aggregate (1–90, default 30)",
+              defaultValue: "30",
+            },
+            {
+              flags: "--json",
+              description: "Emit raw JSON instead of a formatted table",
+            },
+          ],
+          helpText: `
+Reads the memory v3 injection gate telemetry outbox and prints pass rates
+and reason distributions grouped by concept page count bucket
+(0–9 / 10–49 / 50–199 / 200+). Scored runs (dense lane was available and
+actually weighed scores) are reported separately from pass-open shortcuts
+(dense disabled / unavailable / gate threw) so scoredPassRate reflects
+only contested gate decisions — the signal relevant for threshold calibration.
+
+Coverage is limited to runs still pending platform flush. In a healthy system
+the outbox holds only the last few minutes to hours of events, so
+--lookback-days is an upper bound, not a guarantee; long-window aggregation
+lives on the platform side on top of flushed watchdog events.
+
+Reads the telemetry database directly — the assistant does not need to be
+running.
+
+Intended use: verify that gate firing rates shift as expected after a
+config or threshold change, and check whether the bm25-auto-calibration
+flag is worth enabling for large corpora.
+
+Examples:
+  $ assistant memory v3 gate-stats
+  $ assistant memory v3 gate-stats --lookback-days 7
+  $ assistant memory v3 gate-stats --json | jq '.buckets[] | select(.pageCountRange == "200+")'`,
         },
         {
           name: "eval-tally",