@vellumai/assistant 0.11.10 → 0.11.11-staging.1

package/src/api/constants/personality-sliders.ts

@@ -0,0 +1,64 @@
+/**
+ * Personality slider sidecar path, the five 0-100 axis ids, and the
+ * hosted-Qwen direction poles those sliders map onto.
+ *
+ * The web writes `data/personality-sliders.json`. The assistant reads the
+ * same path and maps each slider onto one left/right pole. Both import
+ * these constants from `@vellumai/assistant-api` so the ids cannot drift.
+ */
+
+/** Workspace-relative sidecar holding the five 0-100 slider values. */
+export const PERSONALITY_SLIDERS_PATH = "data/personality-sliders.json";
+
+/** Sliders start centered. Center is no steer on the hosted-Qwen route. */
+export const PERSONALITY_SLIDER_DEFAULT = 50;
+
+/**
+ * Axis ids the personality sliders key their values by. Each is 0-100 with
+ * 0 = the left label and 100 = the right label.
+ */
+export const PERSONALITY_AXIS_IDS = {
+  companionCoworker: "companion-coworker",
+  genzBoomer: "genz-boomer",
+  executeCollaborate: "execute-collaborate",
+  playfulSerious: "playful-serious",
+  politeUnfiltered: "polite-unfiltered",
+} as const;
+
+export type PersonalityAxisId =
+  (typeof PERSONALITY_AXIS_IDS)[keyof typeof PERSONALITY_AXIS_IDS];
+
+/**
+ * One-sided direction poles for each slider. Center (50) activates neither.
+ * Values below 50 activate `left`; values above 50 activate `right`.
+ */
+export const PERSONALITY_DIRECTION_AXES = [
+  {
+    sliderId: PERSONALITY_AXIS_IDS.companionCoworker,
+    left: "companion",
+    right: "coworker",
+  },
+  {
+    sliderId: PERSONALITY_AXIS_IDS.genzBoomer,
+    left: "genz",
+    right: "boomer",
+  },
+  {
+    sliderId: PERSONALITY_AXIS_IDS.executeCollaborate,
+    left: "independent",
+    right: "collaborative",
+  },
+  {
+    sliderId: PERSONALITY_AXIS_IDS.playfulSerious,
+    left: "playful",
+    right: "serious",
+  },
+  {
+    sliderId: PERSONALITY_AXIS_IDS.politeUnfiltered,
+    left: "polite",
+    right: "unfiltered",
+  },
+] as const;
+
+export type PersonalityDirectionAxis =
+  (typeof PERSONALITY_DIRECTION_AXES)[number];

package/src/api/index.ts

@@ -153,6 +153,14 @@ export {
   type DocumentMutationTool,
   REOPENABLE_DOCUMENT_MUTATION_TOOL_NAMES,
 } from "./constants/document-tools.js";
+export {
+  PERSONALITY_AXIS_IDS,
+  PERSONALITY_DIRECTION_AXES,
+  PERSONALITY_SLIDER_DEFAULT,
+  PERSONALITY_SLIDERS_PATH,
+  type PersonalityAxisId,
+  type PersonalityDirectionAxis,
+} from "./constants/personality-sliders.js";
 export {
   MIN_INPUT_RESERVE_TOKENS,
   type ProfileConfigIssue,

package/src/archive/ustar-size.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+
+import { MALFORMED_USTAR_SIZE, parseUstarSizeField } from "./ustar-size.js";
+
+function headerWithSize(field: string): Uint8Array {
+  const header = new Uint8Array(512);
+  const bytes = Buffer.from(field, "utf-8");
+  header.set(bytes.subarray(0, 12), 124);
+  return header;
+}
+
+describe("parseUstarSizeField", () => {
+  test("reads a NUL-terminated octal size", () => {
+    expect(parseUstarSizeField(headerWithSize("00000001000\0"))).toBe(512);
+  });
+
+  test("treats an empty field as zero", () => {
+    expect(parseUstarSizeField(headerWithSize("\0".repeat(12)))).toBe(0);
+  });
+
+  test("rejects a negative octal size", () => {
+    expect(() => parseUstarSizeField(headerWithSize("-0000001000\0"))).toThrow(
+      MALFORMED_USTAR_SIZE,
+    );
+  });
+
+  test("rejects a truncated header", () => {
+    expect(() => parseUstarSizeField(new Uint8Array(100))).toThrow(
+      MALFORMED_USTAR_SIZE,
+    );
+  });
+});

package/src/archive/ustar-size.ts

@@ -0,0 +1,23 @@
+export const MALFORMED_USTAR_SIZE = "malformed tar size field";
+
+/**
+ * Parse the ustar `size` field (bytes 124-135, octal, NUL or space
+ * terminated). Rejects non-finite and negative values so a crafted header
+ * cannot walk the archive cursor backwards.
+ */
+export function parseUstarSizeField(header: Uint8Array): number {
+  if (header.length < 136) {
+    throw new Error(MALFORMED_USTAR_SIZE);
+  }
+  const raw = header.subarray(124, 136);
+  let end = 0;
+  while (end < raw.length && raw[end] !== 0) {
+    end++;
+  }
+  const sizeStr = new TextDecoder().decode(raw.subarray(0, end)).trim();
+  const size = sizeStr ? Number.parseInt(sizeStr, 8) : 0;
+  if (!Number.isFinite(size) || size < 0) {
+    throw new Error(MALFORMED_USTAR_SIZE);
+  }
+  return size;
+}

package/src/background-wake/next-wake.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { setConfig } from "../__tests__/helpers/set-config.js";
+import { hasSetConstructs } from "../schedule/recurrence-engine.js";
 
 type MockHeartbeatConfig = {
   enabled: boolean;
@@ -44,6 +45,7 @@ mock.module("../heartbeat/heartbeat-service.js", () => ({
 }));
 
 mock.module("../schedule/recurrence-engine.js", () => ({
+  hasSetConstructs,
   computeNextRunAt: () => computedCronNextRunAt,
 }));
 
@@ -80,6 +82,7 @@ describe("computeNextBackgroundWakeIntent", () => {
     heartbeatConsecutiveRunCapReached = false;
     schedules = [];
     computedCronNextRunAt = NOW + 3_600_000;
+    setConfig("ui", {});
   });
 
   test("returns heartbeat-only interval wake intent", () => {
@@ -109,6 +112,16 @@ describe("computeNextBackgroundWakeIntent", () => {
     expect(intent!.reason).toBe("heartbeat");
   });
 
+  test("resolves heartbeat timezone from the user zone when unset", () => {
+    setConfig("ui", { detectedTimezone: "America/Los_Angeles" });
+    const intent = computeWakeIntent(NOW);
+    expect(intent).not.toBeNull();
+    expect(intent!.sourcePayload.heartbeat!.timezone).toBe(
+      "America/Los_Angeles",
+    );
+    setConfig("ui", {});
+  });
+
   test("returns heartbeat-only cron wake intent", () => {
     heartbeatConfig.cronExpression = "0 9 * * *";
     heartbeatConfig.timezone = "America/New_York";

package/src/background-wake/next-wake.ts

@@ -4,6 +4,7 @@ import { getConfig } from "../config/loader.js";
 import { HeartbeatService } from "../heartbeat/heartbeat-service.js";
 import { computeNextRunAt } from "../schedule/recurrence-engine.js";
 import { listSchedules, type ScheduleJob } from "../schedule/schedule-store.js";
+import { resolveScheduleTimezone } from "../schedule/schedule-timezone.js";
 
 export type BackgroundWakeIntentReason = "heartbeat" | "schedule" | "mixed";
 
@@ -110,6 +111,7 @@ function getHeartbeatWakeSource(now: number): HeartbeatWakeSource | null {
   const serviceNextRunAt = service?.nextRunAt ?? null;
   let nextRunAt = serviceNextRunAt;
   const mode = config.cronExpression != null ? "cron" : "interval";
+  const timezone = resolveScheduleTimezone(config.timezone);
 
   if (nextRunAt == null) {
     if (config.cronExpression != null) {
@@ -118,7 +120,7 @@ function getHeartbeatWakeSource(now: number): HeartbeatWakeSource | null {
           {
             syntax: "cron",
             expression: config.cronExpression,
-            timezone: config.timezone,
+            timezone,
           },
           now,
         );
@@ -139,7 +141,7 @@ function getHeartbeatWakeSource(now: number): HeartbeatWakeSource | null {
     mode,
     intervalMs: config.intervalMs,
     cronExpression: config.cronExpression,
-    timezone: config.timezone,
+    timezone,
     activeHoursStart: config.activeHoursStart,
     activeHoursEnd: config.activeHoursEnd,
     maxConsecutiveRuns: config.maxConsecutiveRuns,

package/src/calls/voice-session-bridge.ts

@@ -29,6 +29,7 @@ import { resolveChannelCapabilities } from "../daemon/conversation-runtime-assem
 import { getOrCreateConversation } from "../daemon/conversation-store.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
 import {
+  newestPersistedSightFrame,
   pendingStandaloneImagePersist,
   SIGHT_FRAME_TURN_HOLD_MS,
 } from "../live-voice/live-voice-photo.js";
@@ -803,6 +804,10 @@ export async function startVoiceTurn(
     conversationReadyAt: 0,
     admissionClearAt: 0,
     sightHoldMs: 0,
+    // The camera frame this turn reads as the current view, and how old it
+    // was when the turn's own message landed. Null when the conversation
+    // carries no frame.
+    newestSightFrame: null as { attachmentId: string; ageMs: number } | null,
     persistDoneAt: 0,
   };
   const eventSink: VoiceRunEventSink = {
@@ -1425,6 +1430,26 @@ export async function startVoiceTurn(
     }
   }
   dispatch.persistDoneAt = Date.now();
+  // Read now, under the flag this turn holds, rather than after the sight
+  // hold: a frame can still land between the hold and the persist, when its
+  // acquire beats this turn's and the turn retries behind it. What the loop
+  // below reads is what the rows hold at this moment, so this is the frame the
+  // answer is about. One indexed row; a log-only read that fails must not
+  // take the turn down with it.
+  try {
+    const newestFrame = newestPersistedSightFrame(opts.conversationId);
+    if (newestFrame) {
+      dispatch.newestSightFrame = {
+        attachmentId: newestFrame.attachmentId,
+        ageMs: dispatch.persistDoneAt - newestFrame.capturedAt,
+      };
+    }
+  } catch (err) {
+    log.warn(
+      { err, turnId, conversationId: opts.conversationId },
+      "Could not read the newest camera frame for the dispatch timing log",
+    );
+  }
   try {
     opts.callbacks?.persisted_user_message_id?.(messageId);
   } catch (err) {
@@ -1851,6 +1876,7 @@ export async function startVoiceTurn(
         admissionWaitMs:
           dispatch.admissionClearAt - dispatch.conversationReadyAt,
         sightHoldMs: dispatch.sightHoldMs,
+        newestSightFrame: dispatch.newestSightFrame,
         persistMs:
           dispatch.persistDoneAt -
           dispatch.admissionClearAt -

package/src/cli/__tests__/catalog-search-help.test.ts

@@ -33,6 +33,7 @@ describe("catalog search help for setup-intent retrieval", () => {
     expect(indexed).toContain("Setup <app> for me");
     expect(indexed.toLowerCase()).toContain("before searching the web");
     expect(indexed).toContain("assistant plugins search");
+    expect(indexed).toContain("assistant plugins install <name>");
     expect(indexed).toContain("assistant skills search");
     expect(indexed.toLowerCase()).toContain("channels");
     expect(pluginsHelp.description).toContain("channels");

package/src/cli/commands/__tests__/plugins-search.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Tests for `assistant plugins search` human vs `--json` output.
+ *
+ * Search results include a `github:owner/repo@ref` PATH column. The model
+ * copies that locator into `plugins install`. The human footer tells it to
+ * install by marketplace name instead.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+
+import { PLUGINS_SEARCH_INSTALL_HINT } from "../plugins.help.js";
+import { runCliCommand } from "./cli-test-harness.js";
+
+const catalog = {
+  ref: "test-ref",
+  matches: [
+    {
+      name: "imessage",
+      path: "github:vellum-ai/imessage@abc123",
+      category: "productivity",
+      source: {
+        kind: "github" as const,
+        repo: "vellum-ai/imessage",
+        ref: "abc123",
+      },
+    },
+  ],
+};
+
+mock.module("../../lib/plugin-catalog-cache.js", () => ({
+  getPluginCatalog: async () => catalog,
+}));
+
+const { registerPluginsCommand } = await import("../plugins.js");
+
+function runSearch(args: string[]): Promise<{
+  stdout: string;
+  exitCode: number;
+}> {
+  return runCliCommand(registerPluginsCommand, ["plugins", ...args]);
+}
+
+describe("plugins search", () => {
+  test("human output ends with the marketplace-name install hint", async () => {
+    const { exitCode, stdout } = await runSearch(["search", "imessage"]);
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("imessage");
+    expect(stdout).toContain("github:vellum-ai/imessage@abc123");
+    expect(stdout).toContain('1 match for "imessage".');
+    expect(stdout.trimEnd().endsWith(PLUGINS_SEARCH_INSTALL_HINT)).toBe(true);
+    expect(PLUGINS_SEARCH_INSTALL_HINT).toContain(
+      "assistant plugins install <name>",
+    );
+  });
+
+  test("empty human result has no install hint", async () => {
+    const { exitCode, stdout } = await runSearch(["search", "nothing-matches"]);
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('No plugins matched "nothing-matches".');
+    expect(stdout).not.toContain(PLUGINS_SEARCH_INSTALL_HINT);
+  });
+
+  test("json output omits the install hint", async () => {
+    const { exitCode, stdout } = await runSearch([
+      "search",
+      "imessage",
+      "--json",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(stdout).not.toContain(PLUGINS_SEARCH_INSTALL_HINT);
+    const parsed = JSON.parse(stdout) as {
+      query: string;
+      matches: Array<{ name: string }>;
+    };
+    expect(parsed.query).toBe("imessage");
+    expect(parsed.matches.map((m) => m.name)).toEqual(["imessage"]);
+  });
+});

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

@@ -51,7 +51,9 @@ API Keys (agent shells refuse inline keys unless --generated is passed).
 
 Examples:
   $ assistant config set llm.defaultProvider.provider anthropic
-  $ assistant config set calls.enabled true`,
+  $ assistant config set calls.enabled true
+  $ assistant config set memory.embeddings.provider custom
+  $ assistant config set memory.embeddings.baseUrl https://gateway.example.com/v1`,
     },
     {
       name: "get",

package/src/cli/commands/memory/worker.ts

@@ -35,7 +35,7 @@ interface StopResponse {
 interface EmbeddingStatus {
   enabled: boolean;
   degraded: boolean;
-  provider: "local" | "openai" | "gemini" | "ollama" | null;
+  provider: "local" | "openai" | "gemini" | "ollama" | "custom" | null;
   model: string | null;
   reason: string | null;
 }

package/src/cli/commands/platform/__tests__/credits-format.test.ts

@@ -18,11 +18,29 @@ const BASE: PlatformCreditsResult = {
   daily_limit_snoozed: false,
   low_balance_threshold: 5,
   low_balance_warning: false,
+  plan_credit_remaining: 9.1,
+  plan_credit_total: 20,
+  plan_credit_used_fraction: 0.545,
+  plan_credits_spent: false,
+  extra_credit_remaining: 33.07,
+  credits_expiring_soon: 9.1,
+  next_credit_expiry_at: "2026-10-01T00:00:00Z",
+};
+
+const NO_GRANTS: PlatformCreditsResult = {
+  ...BASE,
+  plan_credit_remaining: null,
+  plan_credit_total: null,
+  plan_credit_used_fraction: null,
+  plan_credits_spent: null,
+  extra_credit_remaining: null,
+  credits_expiring_soon: null,
+  next_credit_expiry_at: null,
 };
 
 describe("formatCreditsLines", () => {
   test("labels daily spend as counted against the daily limit, never as total spend", () => {
-    const lines = formatCreditsLines(BASE);
+    const lines = formatCreditsLines(NO_GRANTS);
 
     expect(lines[2]).toBe(
       "Today:     $3.25 counted against the $10.00 daily limit",
@@ -31,20 +49,20 @@ describe("formatCreditsLines", () => {
   });
 
   test("says when no daily limit is set and flags a reached or skipped limit", () => {
-    expect(formatCreditsLines({ ...BASE, daily_limit: null })[2]).toBe(
+    expect(formatCreditsLines({ ...NO_GRANTS, daily_limit: null })[2]).toBe(
       "Today:     $3.25 counted against the daily limit (none set)",
     );
     expect(
-      formatCreditsLines({ ...BASE, daily_limit_reached: true })[2],
+      formatCreditsLines({ ...NO_GRANTS, daily_limit_reached: true })[2],
     ).toEndWith(" (limit reached)");
     expect(
-      formatCreditsLines({ ...BASE, daily_limit_snoozed: true })[2],
+      formatCreditsLines({ ...NO_GRANTS, daily_limit_snoozed: true })[2],
     ).toEndWith(" (limit skipped for today)");
   });
 
   test("omits the daily line without daily spend and adds the low-balance warning", () => {
     const lines = formatCreditsLines({
-      ...BASE,
+      ...NO_GRANTS,
       daily_spend: null,
       low_balance_warning: true,
     });
@@ -55,6 +73,77 @@ describe("formatCreditsLines", () => {
     );
   });
 
+  test("reports plan credit left with the meter percentage, extra credit, and expiry", () => {
+    const lines = formatCreditsLines(BASE);
+
+    expect(lines[2]).toBe(
+      "Plan:      $9.10 of $20.00 plan credit left (55% used)",
+    );
+    expect(lines[3]).toBe(
+      "Extra:     $33.07 bought or earned on top of plan credit",
+    );
+    expect(lines[4]).toBe(
+      "Expiring:  $9.10 within 30 days (next expiry 2026-10-01T00:00:00Z)",
+    );
+    expect(lines[5]).toStartWith("Today:     $3.25 counted against");
+  });
+
+  test("says plan credit is used up and skips the expiry line when nothing is scheduled", () => {
+    const spent = {
+      ...BASE,
+      plan_credit_remaining: 0,
+      plan_credit_used_fraction: 1,
+      plan_credits_spent: true,
+      credits_expiring_soon: 0,
+      next_credit_expiry_at: null,
+    };
+    const lines = formatCreditsLines({
+      ...spent,
+      extra_credit_remaining: 42.17,
+    });
+
+    expect(lines[2]).toBe(
+      "Plan:      plan credit used up or expired; managed usage now draws on extra credit",
+    );
+    expect(lines[3]).toBe(
+      "Extra:     $42.17 bought or earned on top of plan credit",
+    );
+    expect(lines[4]).toStartWith("Today:");
+
+    expect(formatCreditsLines({ ...spent, extra_credit_remaining: 0 })[2]).toBe(
+      "Plan:      plan credit used up or expired, and no extra credit remains",
+    );
+  });
+
+  test("reports the spent state with an unknown wallet when the remaining amount is omitted", () => {
+    const lines = formatCreditsLines({
+      ...BASE,
+      plan_credit_remaining: null,
+      plan_credit_total: 0,
+      plan_credit_used_fraction: 1,
+      plan_credits_spent: true,
+      extra_credit_remaining: null,
+    });
+
+    expect(lines[2]).toBe(
+      "Plan:      plan credit used up or expired; whether extra credit remains was not reported",
+    );
+  });
+
+  test("shows the next expiry when it falls beyond the 30-day window", () => {
+    const lines = formatCreditsLines({ ...BASE, credits_expiring_soon: 0 });
+
+    expect(lines[4]).toBe(
+      "Expiry:    next credit expiry 2026-10-01T00:00:00Z (nothing expires within 30 days)",
+    );
+  });
+
+  test("does not claim an empty 30-day window when that figure was not reported", () => {
+    const lines = formatCreditsLines({ ...BASE, credits_expiring_soon: null });
+
+    expect(lines[4]).toBe("Expiry:    next credit expiry 2026-10-01T00:00:00Z");
+  });
+
   test("formats a negative remaining balance with the sign first", () => {
     expect(formatCreditsLines({ ...BASE, remaining: -2.5 })[0]).toStartWith(
       "Remaining: -$2.50 USD",

package/src/cli/commands/platform/__tests__/credits.test.ts

@@ -22,6 +22,13 @@ describe("assistant platform credits", () => {
         daily_limit_snoozed: false,
         low_balance_threshold: 5,
         low_balance_warning: false,
+        plan_credit_remaining: 9.1,
+        plan_credit_total: 20,
+        plan_credit_used_fraction: 0.545,
+        plan_credits_spent: false,
+        extra_credit_remaining: 33.07,
+        credits_expiring_soon: 9.1,
+        next_credit_expiry_at: "2026-10-01T00:00:00Z",
       },
     };
   });
@@ -41,6 +48,9 @@ describe("assistant platform credits", () => {
     expect(parsed.daily_limit).toBe(10);
     expect(parsed.daily_limit_reached).toBe(false);
     expect(parsed.low_balance_warning).toBe(false);
+    expect(parsed.plan_credit_remaining).toBe(9.1);
+    expect(parsed.plan_credit_used_fraction).toBe(0.545);
+    expect(parsed.extra_credit_remaining).toBe(33.07);
   });
 
   test("plain text mode does not emit JSON to stdout", async () => {

package/src/cli/commands/platform/credits-format.ts

@@ -13,6 +13,13 @@ export interface PlatformCreditsResult {
   daily_limit_snoozed: boolean;
   low_balance_threshold: number | null;
   low_balance_warning: boolean;
+  plan_credit_remaining: number | null;
+  plan_credit_total: number | null;
+  plan_credit_used_fraction: number | null;
+  plan_credits_spent: boolean | null;
+  extra_credit_remaining: number | null;
+  credits_expiring_soon: number | null;
+  next_credit_expiry_at: string | null;
 }
 
 /** Human-readable lines for `assistant platform credits`. */
@@ -22,6 +29,56 @@ export function formatCreditsLines(result: PlatformCreditsResult): string[] {
     `Remaining: ${formatCostUsd(result.remaining)} ${result.unit} (as of ${result.as_of})${staleNote}`,
     `Settled:   ${formatCostUsd(result.settled)}   Pending: ${formatCostUsd(result.pending)}`,
   ];
+  if (result.plan_credits_spent === true) {
+    // Mirrors the web usage panel: extra credit is only said to fund usage
+    // once the wallet provably holds some, and an unreported wallet is not
+    // an empty one.
+    const extra = result.extra_credit_remaining;
+    lines.push(
+      extra === null
+        ? "Plan:      plan credit used up or expired; whether extra credit remains was not reported"
+        : extra > 0
+          ? "Plan:      plan credit used up or expired; managed usage now draws on extra credit"
+          : "Plan:      plan credit used up or expired, and no extra credit remains",
+    );
+  } else if (
+    result.plan_credit_remaining !== null &&
+    result.plan_credit_total !== null
+  ) {
+    const pct =
+      result.plan_credit_used_fraction === null
+        ? ""
+        : ` (${Math.round(result.plan_credit_used_fraction * 100)}% used)`;
+    lines.push(
+      `Plan:      ${formatCostUsd(result.plan_credit_remaining)} of ${formatCostUsd(result.plan_credit_total)} plan credit left${pct}`,
+    );
+  }
+  if (result.extra_credit_remaining !== null) {
+    lines.push(
+      `Extra:     ${formatCostUsd(result.extra_credit_remaining)} bought or earned on top of plan credit`,
+    );
+  }
+  if (
+    result.credits_expiring_soon !== null &&
+    result.credits_expiring_soon > 0
+  ) {
+    const when = result.next_credit_expiry_at
+      ? ` (next expiry ${result.next_credit_expiry_at})`
+      : "";
+    lines.push(
+      `Expiring:  ${formatCostUsd(result.credits_expiring_soon)} within 30 days${when}`,
+    );
+  } else if (result.next_credit_expiry_at) {
+    // A null 30-day figure means the platform did not report it, so only an
+    // actual zero earns the "nothing expires within 30 days" claim.
+    const window =
+      result.credits_expiring_soon === null
+        ? ""
+        : " (nothing expires within 30 days)";
+    lines.push(
+      `Expiry:    next credit expiry ${result.next_credit_expiry_at}${window}`,
+    );
+  }
   if (result.daily_spend !== null) {
     const limit =
       result.daily_limit === null

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

@@ -72,10 +72,11 @@ Examples:
     {
       name: "credits",
       description:
-        "Show the organization's remaining credit balance and daily-limit state",
+        "Show the organization's credit balance, plan-credit usage, and daily-limit state",
       helpText: `
-Fetches the org's credit balance, today's spend, and daily-limit state from
-the platform billing summary.
+Fetches the org's credit balance, plan-included credit usage, extra credit,
+upcoming expiry, today's spend, and daily-limit state from the platform
+billing summary.
 
 Fields:
   remaining              Effective balance (settled minus pending charges) in USD
@@ -91,6 +92,21 @@ Fields:
   daily_limit_snoozed    True when the limit is skipped for the rest of today
   low_balance_threshold  Low-balance alert threshold in USD
   low_balance_warning    True when the balance is below the threshold and auto top-up is off
+  plan_credit_remaining  Unused plan-included credit (initial credit, Pro bundle) in USD
+  plan_credit_total      What those plan-included grants were worth in total, in USD
+  plan_credit_used_fraction
+                         Share of plan credit used, 0 to 1 (the in-app usage meter)
+  plan_credits_spent     True when plan credit is used up or expired (extra_credit_remaining
+                         says whether anything still funds usage); null with no reading
+  extra_credit_remaining Credit bought or earned on top of plan credit, in USD
+  credits_expiring_soon  Credit on grants expiring within 30 days, in USD
+  next_credit_expiry_at  Earliest upcoming grant expiry (ISO 8601), or null
+
+Grant fields are null when the platform does not report grant figures. Plan
+credit mixes grants with different lifetimes (only the Pro bundle turns over
+with the billing cycle), so it has no single reset date. next_credit_expiry_at
+is the earliest expiry across all grants, plan-included or not, and
+'assistant platform subscription' gives the billing cycle boundary.
 
 Requires platform credentials (run 'assistant platform connect' first or
 ensure VELLUM_PLATFORM_URL is set and credentials are stored).

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

@@ -8,6 +8,9 @@ import {
   PLUGIN_UPGRADE_STRATEGIES,
 } from "../lib/plugin-constants.js";
 
+export const PLUGINS_SEARCH_INSTALL_HINT =
+  "Install the plugin with `assistant plugins install <name>`.";
+
 export const pluginsHelp: CliCommandHelp = {
   name: "plugins",
   description:
@@ -166,7 +169,7 @@ Arguments:
            user sentence. Use the product or plugin name. Anchors like
            ^example work.
 
-If a match is found, install it with 'assistant plugins install <name>'.
+${PLUGINS_SEARCH_INSTALL_HINT}
 If nothing matches, try 'assistant skills search <query>', then web search.
 
 Examples: