@vellumai/assistant 0.8.2 → 0.8.4

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/consolidation-job.ts

@@ -244,6 +244,20 @@ function readBufferContent(bufferPath: string): string {
   }
 }
 
+/**
+ * Count non-empty lines in `memory/buffer.md`. Used by the scheduler to
+ * implement the size-based consolidation trigger. Missing file → 0.
+ *
+ * Each entry is one line (`- [Mon D, h:mm AM/PM] …\n`), so non-empty-line
+ * count == entry count for a well-formed buffer; blank lines and trailing
+ * newlines don't inflate the count.
+ */
+export function countBufferLines(bufferPath: string): number {
+  const content = readBufferContent(bufferPath);
+  if (content.length === 0) return 0;
+  return content.split("\n").filter((line) => line.trim().length > 0).length;
+}
+
 /**
  * Atomically create the lock file with `wx` (O_CREAT | O_EXCL) flags. Returns
  * `null` on success, or the current holder string (file contents, typically

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-events.ts

@@ -0,0 +1,101 @@
+import { getLogger } from "../../util/logger.js";
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+const log = getLogger("memory-v2-injection-events");
+
+/**
+ * Half-life of the injection-frequency decay, in milliseconds.
+ *
+ * Per the memory router v4 spec: a +1 from 3 days ago contributes 0.5; from
+ * 6 days ago 0.25. Decoupled from turn volume — busy and quiet days decay
+ * at the same wall-clock rate.
+ */
+export const INJECTION_SCORE_HALF_LIFE_MS = 3 * 24 * 60 * 60 * 1000;
+
+export const INJECTION_SCORE_LAMBDA =
+  Math.log(2) / INJECTION_SCORE_HALF_LIFE_MS;
+
+// Events past 6 half-lives contribute <1.6% each. Reads bound the scan to
+// this window so per-slug score computation stays cheap as history grows.
+const READ_WINDOW_MS = 6 * INJECTION_SCORE_HALF_LIFE_MS;
+
+function decayContribution(elapsedMs: number): number {
+  return Math.exp(-INJECTION_SCORE_LAMBDA * elapsedMs);
+}
+
+/**
+ * Append one event per slug. Best-effort — a SQLite write must never abort
+ * the agent turn on top of a successful routing decision the rest of the
+ * caller depends on.
+ */
+export function recordInjectionEvents(
+  database: DrizzleDb,
+  slugs: readonly string[],
+  injectedAt: number,
+): void {
+  if (slugs.length === 0) return;
+  try {
+    const raw = getSqliteFrom(database);
+    const insert = raw.prepare(
+      `INSERT INTO memory_v2_injection_events (slug, injected_at) VALUES (?, ?)`,
+    );
+    const append = raw.transaction((items: readonly string[]) => {
+      for (const slug of items) insert.run(slug, injectedAt);
+    });
+    append(slugs);
+  } catch (err) {
+    log.warn(
+      { err, slugCount: slugs.length },
+      "failed to record injection events; continuing",
+    );
+  }
+}
+
+/** `score(now) = Σᵢ exp(-λ × (now - tᵢ))` over events within READ_WINDOW_MS. */
+export function computeInjectionScore(
+  database: DrizzleDb,
+  slug: string,
+  now: number,
+): number {
+  const cutoff = now - READ_WINDOW_MS;
+  const raw = getSqliteFrom(database);
+  const rows = raw
+    .query(
+      `SELECT injected_at FROM memory_v2_injection_events
+        WHERE slug = ? AND injected_at >= ?`,
+    )
+    .all(slug, cutoff) as Array<{ injected_at: number }>;
+  let score = 0;
+  for (const row of rows) score += decayContribution(now - row.injected_at);
+  return score;
+}
+
+/**
+ * Batch variant of `computeInjectionScore` — single SQL pass scoped to the
+ * requested slugs so tier assignment doesn't issue O(M) queries. Slugs
+ * with no events in the read window are omitted from the result; callers
+ * should treat a missing entry as score 0.
+ */
+export function computeInjectionScores(
+  database: DrizzleDb,
+  slugs: readonly string[],
+  now: number,
+): Map<string, number> {
+  const out = new Map<string, number>();
+  if (slugs.length === 0) return out;
+  const cutoff = now - READ_WINDOW_MS;
+  const raw = getSqliteFrom(database);
+  const placeholders = slugs.map(() => "?").join(",");
+  const rows = raw
+    .query(
+      `SELECT slug, injected_at FROM memory_v2_injection_events
+        WHERE slug IN (${placeholders}) AND injected_at >= ?`,
+    )
+    .all(...slugs, cutoff) as Array<{ slug: string; injected_at: number }>;
+  for (const row of rows) {
+    const prev = out.get(row.slug) ?? 0;
+    out.set(row.slug, prev + decayContribution(now - row.injected_at));
+  }
+  return out;
+}

package/src/memory/v2/injection.ts

@@ -38,7 +38,12 @@ 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 { recordInjectionEvents } from "./injection-events.js";
 import { readPage, renderPageContent } from "./page-store.js";
 import { runRouter } from "./router.js";
 import { getSkillCapability, isSkillSlug } from "./skill-store.js";
@@ -355,20 +360,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,
@@ -546,9 +553,19 @@ async function injectViaRouter(args: {
     nowText,
     priorEverInjected,
     config,
+    database,
     ...(signal ? { signal } : {}),
   });
 
+  // Record router selections to the EMA event log. The router decided these
+  // slugs are relevant THIS turn (regardless of whether they're newly
+  // rendered or re-picked from prior context). The helper swallows its own
+  // errors — a SQLite write must not abort the turn on top of a successful
+  // routing decision the rest of this function depends on.
+  if (routerResult.failureReason === null) {
+    recordInjectionEvents(database, routerResult.selectedSlugs, Date.now());
+  }
+
   if (routerResult.failureReason !== null) {
     log.warn(
       { failureReason: routerResult.failureReason },
@@ -597,12 +614,12 @@ async function injectViaRouter(args: {
 
   // Build minimal telemetry rows for the union of router-selected slugs and
   // prior `everInjected` slugs. Router-mode rows zero out every activation
-  // value (no spreading activation runs). Slugs the router picked this turn
-  // get `source: "router"`; prior-everInjected slugs the router did NOT
-  // re-pick get `source: "carry_over"`. The `status` placeholder is
-  // overwritten by `finalizeInjection`.
-  const routerPicked = new Set(routerResult.selectedSlugs);
-  const telemetrySlugs = new Set<string>(routerPicked);
+  // value (no spreading activation runs). Slugs the router picked carry
+  // their batch's tier tag from `routerResult.sourceBySlug` (e.g. `tier1`,
+  // `tier3:2`); prior-everInjected slugs the router did NOT re-pick get
+  // `source: "carry_over"`. The `status` placeholder is overwritten by
+  // `finalizeInjection`.
+  const telemetrySlugs = new Set<string>(routerResult.selectedSlugs);
   for (const entry of priorEverInjected) telemetrySlugs.add(entry.slug);
   const telemetryRows: MemoryV2ConceptRowRecord[] = [...telemetrySlugs].map(
     (slug) => ({
@@ -617,7 +634,7 @@ async function injectViaRouter(args: {
       simAssistantRerankBoost: 0,
       inRerankPool: false,
       spreadContribution: 0,
-      source: routerPicked.has(slug) ? "router" : "carry_over",
+      source: routerResult.sourceBySlug.get(slug) ?? "carry_over",
       status: "not_injected",
     }),
   );
@@ -706,7 +723,7 @@ interface RenderInjectionBlockResult {
  * the agent into wasted reads.
  */
 const INJECTION_HEADER =
-  "**CRITICAL:** These are page summaries. Read the page file if it looks relevant.";
+  'Use `file_read("memory/concepts/path/to/file.md")` to read the full pages for any of the injected memory summaries you want more information on.';
 
 /**
  * Render the inner content of the `<memory>` block for a list of slugs.
@@ -728,20 +745,20 @@ 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
+ * instruction line tells the agent how to read the block.
  *
- *   **CRITICAL:** These are page summaries. Read the page file if it looks relevant.
+ *   Use `file_read("memory/concepts/path/to/file.md")` to read the full pages for any of the injected memory summaries you want more information on.
  *
  *   # memory/concepts/<concept-slug-1>.md
  *   <summary-1>
@@ -758,13 +775,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)),
@@ -815,6 +843,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 };
   }