@vellumai/assistant 0.8.1 → 0.8.3

package/src/memory/v2/activation-store.ts

@@ -11,11 +11,7 @@ import { eq } from "drizzle-orm";
 
 import type { DrizzleDb } from "../db-connection.js";
 import { activationState } from "../schema.js";
-import {
-  type ActivationState,
-  ActivationStateSchema,
-  type EverInjectedEntry,
-} from "./types.js";
+import { type ActivationState, ActivationStateSchema } from "./types.js";
 
 /**
  * Load the activation state for a conversation, or `null` if no row exists.
@@ -123,16 +119,18 @@ export function forkActivationState(
 }
 
 /**
- * Drop `everInjected` entries whose `turn` is at or below `upToTurn`.
- * Used after compaction evicts older turns — slugs that lived only on those
- * turns become eligible for re-injection on the next turn.
+ * Clear all `everInjected` entries. Used after compaction: the cached
+ * `<memory>` attachments those slugs lived on are gone, so future turns
+ * should be free to re-inject them.
+ *
+ * Unconditionally empties the list rather than filtering by turn number.
+ * `everInjected` is persisted on every turn while the in-memory tracker's
+ * `currentTurn` is only snapshotted on graceful conversation dispose, so a
+ * non-graceful shutdown (SIGKILL, crash) followed by a reload can leave
+ * `everInjected` entries with `turn` values above the restored tracker's
+ * `currentTurn`. A turn-bounded filter misses those stale entries and they
+ * dedupe forever; a full clear is robust to that drift.
  */
-export function evictCompactedTurns(
-  state: ActivationState,
-  upToTurn: number,
-): ActivationState {
-  const everInjected: EverInjectedEntry[] = state.everInjected.filter(
-    (entry) => entry.turn > upToTurn,
-  );
-  return { ...state, everInjected };
+export function clearEverInjected(state: ActivationState): ActivationState {
+  return { ...state, everInjected: [] };
 }

package/src/memory/v2/cli-command-content.ts

@@ -0,0 +1,19 @@
+/**
+ * Render the prose-style capability statement embedded into the unified
+ * `memory_v2_concept_pages` Qdrant collection (under the `cli-commands/<name>`
+ * slug prefix). Mirrors `buildSkillContent` in shape — a short prose lead-in
+ * followed by the dense capability material — so activation scoring weighs
+ * both natural-language intent and structured help text.
+ *
+ * Intentionally uncapped: CLI `--help` output averages 1–2 KB and the longest
+ * (browser, oauth) hits ~3.4 KB. The embedding backend handles inputs of this
+ * size without trouble, and trimming would drop the very examples and flag
+ * descriptions that make commands semantically findable.
+ */
+export function buildCliCommandContent(
+  name: string,
+  description: string,
+  helpText: string,
+): string {
+  return `The "assistant ${name}" CLI command is available. ${description}.\n\nFull help:\n${helpText}`;
+}

package/src/memory/v2/cli-command-store.ts

@@ -0,0 +1,304 @@
+// ---------------------------------------------------------------------------
+// Memory v2 — `assistant` CLI subcommands → embedded capability entries
+// ---------------------------------------------------------------------------
+//
+// Enumerate the top-level `assistant` CLI subcommands, render each as a prose
+// capability statement that wraps the full `helpInformation()` output, embed
+// dense + sparse, and upsert into `memory_v2_concept_pages` under the slug
+// `cli-commands/<name>`. The router scores these alongside concept pages and
+// skill entries; the injection layer surfaces hits under `### CLI Commands
+// You Can Use` so the model can semantically discover a CLI capability it
+// would not otherwise know to reach for.
+//
+// Mirrors `skill-store.ts` deliberately: same single-flight + generation
+// coalescing, same dense + sparse + corpus-stats-aware sparse encoding, same
+// payload-kind discriminator, same atomic cache replacement. Differences:
+//   - No remote catalog — the source of truth is the local Commander tree.
+//   - No per-entry feature-flag filter — flag gating already happens during
+//     `buildCliProgramTree` (e.g. email/plugins commands are conditionally
+//     registered).
+//   - No MCP-style augmentation — Commander's description is the canonical
+//     summary.
+
+import { getConfig } from "../../config/loader.js";
+import { getLogger } from "../../util/logger.js";
+import { applyCorrectionIfCalibrated } from "../anisotropy.js";
+import {
+  embedWithBackend,
+  generateSparseEmbedding,
+} from "../embedding-backend.js";
+import { buildCliCommandContent } from "./cli-command-content.js";
+import { invalidatePageIndex } from "./page-index.js";
+import {
+  backfillKindOnPointsWithPrefix,
+  pruneSlugsWithPrefixExcept,
+  upsertConceptPageEmbedding,
+} from "./qdrant.js";
+import {
+  generateBm25DocEmbedding,
+  getConceptPageCorpusStats,
+} from "./sparse-bm25.js";
+import type { CliCommandEntry } from "./types.js";
+
+const log = getLogger("memory-v2-cli-command-store");
+
+/**
+ * Slug prefix under which CLI-command embeddings are indexed in
+ * `memory_v2_concept_pages`. Concept-page slugs must match
+ * `[a-z0-9][a-z0-9-]*(/...)*`, and `cli-commands` matches that pattern, so the
+ * prefix coexists with hand-authored concept pages without escape work.
+ */
+export const CLI_COMMAND_SLUG_PREFIX = "cli-commands/";
+
+/**
+ * Payload discriminator written on every CLI-command-seeded Qdrant point.
+ * Keeps CLI rows distinguishable from user-authored concept pages and from
+ * skill rows that happen to live in adjacent namespaces, so prefix pruning
+ * never deletes a hand-authored page sitting under `cli-commands/...`.
+ */
+const CLI_COMMAND_PAYLOAD_KIND = "cli-command";
+
+/** Compose the unified-collection slug for a CLI command name. */
+export function cliCommandSlugFor(name: string): string {
+  return `${CLI_COMMAND_SLUG_PREFIX}${name}`;
+}
+
+/**
+ * Module-level cache of rendered CLI-command entries keyed by command name.
+ * `null` until the first successful seed run completes; replaced atomically
+ * on each successful re-seed so callers always see a consistent snapshot.
+ */
+let entries: Map<string, CliCommandEntry> | null = null;
+let requestedSeedGeneration = 0;
+let processedSeedGeneration = 0;
+let activeSeedDrain: Promise<void> | null = null;
+let lastSeedError: unknown = null;
+const seedWaiters: Array<{ generation: number; resolve: () => void }> = [];
+
+/**
+ * In-process latch for the legacy `kind` backfill. New upserts always write
+ * `kind`, so once the latch is set there is no follow-up work to do this
+ * process.
+ */
+let legacyKindBackfillDone = false;
+
+/**
+ * Seed (or re-seed) CLI-command embeddings into the unified concept-page
+ * collection. Idempotent. Best-effort for background callers (errors are
+ * logged but swallowed); pass `{ throwOnError: true }` from synchronous CLI
+ * paths that want failures surfaced.
+ *
+ * Single-flight + coalesced: at most one seed runs at a time. Requests made
+ * while a seed is in flight advance the requested generation; stale in-flight
+ * snapshots are skipped before they write embeddings or replace the cache.
+ */
+export async function seedV2CliCommandEntries(
+  opts: { throwOnError?: boolean } = {},
+): Promise<void> {
+  const generation = ++requestedSeedGeneration;
+  const waiter = new Promise<void>((resolve) => {
+    seedWaiters.push({ generation, resolve });
+  });
+  startSeedDrainIfNeeded();
+  await waiter;
+  if (opts.throwOnError && lastSeedError) {
+    throw lastSeedError;
+  }
+}
+
+function startSeedDrainIfNeeded(): void {
+  if (activeSeedDrain) return;
+  if (processedSeedGeneration >= requestedSeedGeneration) return;
+
+  activeSeedDrain = drainSeedQueue().finally(() => {
+    activeSeedDrain = null;
+    startSeedDrainIfNeeded();
+  });
+}
+
+async function drainSeedQueue(): Promise<void> {
+  while (processedSeedGeneration < requestedSeedGeneration) {
+    const generationToProcess = requestedSeedGeneration;
+    await runSeedV2CliCommandEntries(generationToProcess);
+    processedSeedGeneration = generationToProcess;
+    resolveSeedWaiters();
+  }
+}
+
+function resolveSeedWaiters(): void {
+  for (let i = seedWaiters.length - 1; i >= 0; i -= 1) {
+    const waiter = seedWaiters[i]!;
+    if (waiter.generation > processedSeedGeneration) continue;
+    seedWaiters.splice(i, 1);
+    waiter.resolve();
+  }
+}
+
+async function runSeedV2CliCommandEntries(generation: number): Promise<void> {
+  try {
+    const config = getConfig();
+    // Dynamic import so callers that only need `getCliCommandCapability` or
+    // `listCliCommandEntries` (e.g. the render path inside `injection.ts` and
+    // the `page-index.ts` dependency loader) never drag the full CLI command
+    // graph into their import tree. The CLI tree pulls in many provider and
+    // workspace modules whose presence has been a recurring source of test-
+    // mock cascades and circular-import surprises.
+    const { buildCliProgramTree } = await import("../../cli/program.js");
+    const program = buildCliProgramTree();
+
+    const seeds: CliCommandEntry[] = [];
+    for (const cmd of program.commands) {
+      const name = cmd.name();
+      // Skip the `help` builtin Commander adds automatically — it carries no
+      // capability information of its own and is uniform across commands.
+      if (name === "help") continue;
+      const description = cmd.description();
+      const content = buildCliCommandContent(
+        name,
+        description,
+        cmd.helpInformation(),
+      );
+      seeds.push({ id: name, description, content });
+    }
+
+    const nextEntries = new Map<string, CliCommandEntry>();
+    let denseVectors: number[][] = [];
+    let encodeSparse: (
+      input: string,
+    ) => ReturnType<typeof generateSparseEmbedding> = generateSparseEmbedding;
+    if (seeds.length > 0) {
+      const embedded = await embedWithBackend(
+        config,
+        seeds.map((s) => s.content),
+      );
+      denseVectors = await Promise.all(
+        embedded.vectors.map((v) =>
+          applyCorrectionIfCalibrated(v, embedded.provider, embedded.model),
+        ),
+      );
+
+      // CLI commands share the concept-page Qdrant collection, so the sparse
+      // vector must use the same stemmed BM25 encoding as the concept-page
+      // documents. Fall back to the legacy TF encoder only during the cold-
+      // start window before corpus stats finish building — same rationale as
+      // the skill-store path.
+      const corpusStats = getConceptPageCorpusStats();
+      encodeSparse = (input: string) =>
+        corpusStats
+          ? generateBm25DocEmbedding(input, corpusStats, {
+              k1: config.memory.v2.bm25_k1,
+              b: config.memory.v2.bm25_b,
+            })
+          : generateSparseEmbedding(input);
+    }
+
+    if (generation !== requestedSeedGeneration) {
+      log.info(
+        { generation, latestGeneration: requestedSeedGeneration },
+        "Skipping stale v2 CLI-command seed result",
+      );
+      lastSeedError = null;
+      return;
+    }
+
+    if (seeds.length > 0) {
+      const now = Date.now();
+      await Promise.all(
+        seeds.map((seed, i) =>
+          upsertConceptPageEmbedding({
+            slug: cliCommandSlugFor(seed.id),
+            dense: denseVectors[i],
+            sparse: encodeSparse(seed.content),
+            updatedAt: now,
+            kind: CLI_COMMAND_PAYLOAD_KIND,
+          }),
+        ),
+      );
+      for (const seed of seeds) {
+        nextEntries.set(seed.id, seed);
+      }
+    }
+
+    // The CLI tree is always available (no remote catalog), so pruning is
+    // unconditional. Run the legacy `kind` backfill once per process so
+    // pre-discriminator rows become prunable.
+    const knownIds = new Set(seeds.map((s) => s.id));
+    if (!legacyKindBackfillDone) {
+      try {
+        await backfillKindOnPointsWithPrefix(
+          CLI_COMMAND_SLUG_PREFIX,
+          CLI_COMMAND_PAYLOAD_KIND,
+          knownIds,
+        );
+        legacyKindBackfillDone = true;
+      } catch (err) {
+        log.warn(
+          { err },
+          "Failed to backfill kind on legacy CLI-command points — pruning may leave orphans this run",
+        );
+      }
+    }
+    await pruneSlugsWithPrefixExcept(
+      CLI_COMMAND_SLUG_PREFIX,
+      seeds.map((s) => s.id),
+      { kind: CLI_COMMAND_PAYLOAD_KIND },
+    );
+
+    // Atomically replace the cache only after every step above succeeds.
+    entries = nextEntries;
+    invalidatePageIndex();
+    lastSeedError = null;
+  } catch (err) {
+    lastSeedError = err;
+    log.warn({ err }, "Failed to seed v2 CLI-command entries");
+  }
+}
+
+/**
+ * Synchronous lookup of a previously-seeded `CliCommandEntry` by command
+ * name. Returns `null` when the cache has not yet been populated, when the
+ * id is unknown, or when a prior seed run dropped the id.
+ *
+ * Accepts either a bare command name (`attachment`) or its unified-collection
+ * slug (`cli-commands/attachment`) so render-side callers can pass through
+ * what they have without a manual prefix strip.
+ *
+ * Returns a frozen copy so callers cannot mutate the underlying cache entry.
+ */
+export function getCliCommandCapability(
+  idOrSlug: string,
+): CliCommandEntry | null {
+  const id = idOrSlug.startsWith(CLI_COMMAND_SLUG_PREFIX)
+    ? idOrSlug.slice(CLI_COMMAND_SLUG_PREFIX.length)
+    : idOrSlug;
+  const entry = entries?.get(id);
+  return entry ? Object.freeze({ ...entry }) : null;
+}
+
+/** True iff the slug refers to a CLI-command entry in the unified collection. */
+export function isCliCommandSlug(slug: string): boolean {
+  return slug.startsWith(CLI_COMMAND_SLUG_PREFIX);
+}
+
+/**
+ * Snapshot of the in-process CLI-command cache, sorted by command name (ASCII
+ * order) for determinism. Returns a freshly allocated array of frozen entry
+ * copies on each call.
+ */
+export function listCliCommandEntries(): CliCommandEntry[] {
+  if (!entries) return [];
+  return [...entries.values()]
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .map((entry) => Object.freeze({ ...entry }));
+}
+
+/** @internal Test-only: clear the module-level cache. */
+export function _resetCliCommandStoreForTests(): void {
+  entries = null;
+  requestedSeedGeneration = 0;
+  processedSeedGeneration = 0;
+  activeSeedDrain = null;
+  seedWaiters.splice(0, seedWaiters.length);
+  lastSeedError = null;
+  legacyKindBackfillDone = false;
+}

package/src/memory/v2/frontmatter-sweep.ts

@@ -22,6 +22,7 @@ import { join } from "node:path";
 
 import { parse as parseYaml } from "yaml";
 
+import type { AssistantConfig } from "../../config/schema.js";
 import { FRONTMATTER_REGEX } from "../../skills/frontmatter.js";
 import { getLogger } from "../../util/logger.js";
 import { listPages } from "./page-store.js";
@@ -32,11 +33,16 @@ const log = getLogger("memory-v2-frontmatter-sweep");
 /**
  * Validate every concept page's frontmatter against the strict schema and
  * emit a `warn` per offender. Never throws — daemon startup must not block
- * on this safety net.
+ * on this safety net. Self-gates on `config.memory.v2.enabled`: when v2
+ * is off, concept pages never enter a retrieval top-K so any warns here
+ * would be pure noise.
  */
 export async function sweepConceptPageFrontmatter(
+  config: AssistantConfig,
   workspaceDir: string,
 ): Promise<void> {
+  if (!config.memory.v2.enabled) return;
+
   let slugs: string[];
   try {
     slugs = await listPages(workspaceDir);

package/src/memory/v2/injection.ts

@@ -38,6 +38,10 @@ import {
   spreadActivation,
 } from "./activation.js";
 import { hydrate, save } from "./activation-store.js";
+import {
+  getCliCommandCapability,
+  isCliCommandSlug,
+} from "./cli-command-store.js";
 import { getEdgeIndex } from "./edge-index.js";
 import { readPage, renderPageContent } from "./page-store.js";
 import { runRouter } from "./router.js";
@@ -144,6 +148,7 @@ export async function injectMemoryV2Block(
   } = params;
 
   const workspaceDir = getWorkspaceDir();
+  const mode: InjectMemoryV2Mode = params.mode ?? "per-turn";
 
   // (1) Hydrate. Missing rows are normal at conversation start — proceed
   // with an effective empty prior state so the first turn can still inject.
@@ -151,10 +156,17 @@ export async function injectMemoryV2Block(
   const priorState = await hydrate(database, conversationId);
 
   // Flag-gated router dispatch: when the LLM router is enabled, route the
-  // per-turn page selection through `runRouter` and reuse `finalizeInjection`
-  // for persistence, render, and telemetry. The activation pipeline below
+  // page selection through `runRouter` and reuse `finalizeInjection` for
+  // persistence, render, and telemetry. The activation pipeline below
   // remains the default (flag-off) behavior — every code path past this
   // branch only runs when the router is disabled.
+  //
+  // Runs on both `per-turn` and `context-load`. The `everInjected` dedupe
+  // concern from earlier doesn't apply post-compaction because
+  // `evictCompactedTurnsV2` in `ConversationGraphMemory.onCompacted`
+  // empties the list before this code runs. Router abstention on
+  // context-load means no v2 pages restored that turn, which is preferable
+  // to letting the activation graph pick something arbitrary.
   if (config.memory.v2.router.enabled) {
     return injectViaRouter({
       workspaceDir,
@@ -214,7 +226,6 @@ export async function injectMemoryV2Block(
   // prior cached attachments don't exist or have been thrown away. The user
   // message gets a complete top-K dump alongside the static
   // essentials/threads/recent block, then per-turn turns just add deltas.
-  const mode: InjectMemoryV2Mode = params.mode ?? "per-turn";
   const priorEverInjected: readonly EverInjectedEntry[] =
     priorState?.everInjected ?? [];
   const { topNow, toInject } = selectInjections({
@@ -310,6 +321,14 @@ async function finalizeInjection(args: {
   telemetryRows: MemoryV2ConceptRowRecord[];
   config: AssistantConfig;
   nextStateMap: Record<string, number>;
+  /**
+   * When true, errors thrown inside the helper (save / render / status
+   * finalization) are logged and swallowed instead of re-thrown. Used by
+   * the router-failure path, which is already a best-effort cleanup: a
+   * transient SQLite write here must not abort the turn on top of the
+   * router failure that already happened. Defaults to throwing.
+   */
+  bestEffort?: boolean;
 }): Promise<InjectMemoryV2BlockResult> {
   const {
     workspaceDir,
@@ -340,20 +359,22 @@ async function finalizeInjection(args: {
   // on that user message and the agent keeps seeing it across subsequent turns
   // until compaction evicts the turn.
   //
-  // Skill slugs whose in-process cache entry is missing (e.g. startup race
-  // between the skill seed and the first turn, or stale Qdrant index pointing
-  // at an uninstalled skill) are excluded from `everInjected` so future
-  // per-turn runs re-attempt attachment once the cache is populated. Without
-  // this, the slug would be marked injected even though `renderInjectionBlock`
-  // silently dropped it.
-  const missingSkillSlugs = new Set(
+  // Synthetic slugs (skills, CLI commands) whose in-process cache entry is
+  // missing (e.g. startup race between the seed and the first turn, or stale
+  // Qdrant index pointing at an uninstalled skill / removed CLI command) are
+  // excluded from `everInjected` so future per-turn runs re-attempt attachment
+  // once the cache is populated. Without this, the slug would be marked
+  // injected even though `renderInjectionBlock` silently dropped it.
+  const missingSyntheticSlugs = new Set(
     slugsToRender.filter(
-      (slug) => isSkillSlug(slug) && !getSkillCapability(slug),
+      (slug) =>
+        (isSkillSlug(slug) && !getSkillCapability(slug)) ||
+        (isCliCommandSlug(slug) && !getCliCommandCapability(slug)),
     ),
   );
   const everInjectedSet = new Set(priorEverInjected.map((entry) => entry.slug));
   const newlyInjected = slugsToRender.filter(
-    (slug) => !everInjectedSet.has(slug) && !missingSkillSlugs.has(slug),
+    (slug) => !everInjectedSet.has(slug) && !missingSyntheticSlugs.has(slug),
   );
   const nextEverInjected: EverInjectedEntry[] = [
     ...priorEverInjected,
@@ -449,9 +470,16 @@ async function finalizeInjection(args: {
   } catch (err) {
     // Stash the error and let `finally` flush a best-effort telemetry row
     // before we re-throw to the caller. `mode = "errored"` flags the row
-    // for observability dashboards / inspector queries.
+    // for observability dashboards / inspector queries. On the best-effort
+    // path the error is logged and swallowed so the trailing return stands.
     caughtErr = err;
     mode = "errored";
+    if (args.bestEffort) {
+      log.warn(
+        { err, conversationId, turn: currentTurn },
+        "Memory v2 finalizeInjection error on best-effort path — swallowing",
+      );
+    }
   } finally {
     try {
       recordMemoryV2ActivationLog({
@@ -469,7 +497,7 @@ async function finalizeInjection(args: {
     }
   }
 
-  if (caughtErr !== undefined) throw caughtErr;
+  if (caughtErr !== undefined && !args.bestEffort) throw caughtErr;
   return { block, toInject: newlyInjected };
 }
 
@@ -537,7 +565,10 @@ async function injectViaRouter(args: {
     // (preserving `priorEverInjected` so future turns still subtract
     // previously-attached slugs) and writes the telemetry row through the
     // same code path as the success branch — no inline duplication of
-    // `save` + `recordMemoryV2ActivationLog`.
+    // `save` + `recordMemoryV2ActivationLog`. `bestEffort: true` matches
+    // the pre-refactor inline behavior of logging and continuing if the
+    // stub-state `save()` throws — we don't want a transient SQLite write
+    // to abort the turn on top of the router failure that already happened.
     return finalizeInjection({
       workspaceDir,
       database,
@@ -550,6 +581,7 @@ async function injectViaRouter(args: {
       telemetryRows: [],
       config,
       nextStateMap: {},
+      bestEffort: true,
     });
   }
 
@@ -702,18 +734,18 @@ const INJECTION_HEADER =
  * distinguish "file vanished" (stale index) from "file is malformed"
  * (data-corruption / programmer error).
  *
- * Skill slugs whose entry the cache no longer knows (e.g. uninstalled
- * mid-run) are silently dropped, mirroring the missing-pages behavior but
- * without entering `missingSlugs` — the skill catalog is the source of
- * truth for skill availability, not on-disk concept pages, so a missing
- * skill is an expected catalog-level outcome rather than a stale-index
- * bug.
+ * Skill and CLI-command slugs whose entry the in-process cache no longer
+ * knows (e.g. uninstalled mid-run, or a CLI command removed between seeds)
+ * are silently dropped, mirroring the missing-pages behavior but without
+ * entering `missingSlugs` — the synthetic catalogs are the source of truth
+ * for those entries, not on-disk concept pages.
  *
  * Each concept-page section is rendered as a path header followed by either
  * the page's `summary` (when present in frontmatter) or the full page (the
- * fallback for pages predating the summary field). Skills sit at the end
- * under `### Skills You Can Use`, unchanged. The leading `**CRITICAL:**`
- * line tells the agent how to read the block.
+ * fallback for pages predating the summary field). Skills sit after the
+ * concept sections under `### Skills You Can Use`, and CLI subcommands sit
+ * after the skills under `### CLI Commands You Can Use`. The leading
+ * `**CRITICAL:**` line tells the agent how to read the block.
  *
  *   **CRITICAL:** These are page summaries. Read the page file if it looks relevant.
  *
@@ -732,13 +764,24 @@ const INJECTION_HEADER =
  *   ### Skills You Can Use
  *   - <skill-1 content>
  *   - <skill-2 content>
+ *
+ *   ### CLI Commands You Can Use
+ *   Run `assistant <command> --help` for full usage.
+ *   - `assistant <name-1>`: <description-1>
+ *   - `assistant <name-2>`: <description-2>
  */
 async function renderInjectionBlock(
   workspaceDir: string,
   slugs: string[],
 ): Promise<RenderInjectionBlockResult> {
-  const conceptSlugs = slugs.filter((s) => !isSkillSlug(s));
-  const skillSlugs = slugs.filter((s) => isSkillSlug(s));
+  const conceptSlugs: string[] = [];
+  const skillSlugs: string[] = [];
+  const cliCommandSlugs: string[] = [];
+  for (const slug of slugs) {
+    if (isSkillSlug(slug)) skillSlugs.push(slug);
+    else if (isCliCommandSlug(slug)) cliCommandSlugs.push(slug);
+    else conceptSlugs.push(slug);
+  }
 
   const settled = await Promise.allSettled(
     conceptSlugs.map((slug) => readPage(workspaceDir, slug)),
@@ -789,6 +832,18 @@ async function renderInjectionBlock(
     sections.push(`### Skills You Can Use\n${skillLines.join("\n")}`);
   }
 
+  const cliCommandLines: string[] = [];
+  for (const slug of cliCommandSlugs) {
+    const entry = getCliCommandCapability(slug);
+    if (!entry) continue;
+    cliCommandLines.push(`- \`assistant ${entry.id}\`: ${entry.description}`);
+  }
+  if (cliCommandLines.length > 0) {
+    sections.push(
+      `### CLI Commands You Can Use\nRun \`assistant <command> --help\` for full usage.\n${cliCommandLines.join("\n")}`,
+    );
+  }
+
   if (sections.length === 0) {
     return { block: null, missingSlugs, corruptSlugs };
   }