gsd-pi 2.67.0-dev.46f9884 → 2.67.0-dev.4fb8afe

package/src/resources/extensions/gsd/codebase-generator.ts

@@ -8,6 +8,7 @@
  * Maintenance: agent updates descriptions as it works; incremental update preserves them.
  */
 
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname, extname } from "node:path";
 
@@ -22,6 +23,28 @@ export interface CodebaseMapOptions {
   collapseThreshold?: number;
 }
 
+export interface CodebaseMapMetadata {
+  generatedAt: string;
+  fingerprint: string;
+  fileCount: number;
+  truncated: boolean;
+}
+
+export interface EnsureCodebaseMapOptions {
+  ttlMs?: number;
+  maxAgeMs?: number;
+  force?: boolean;
+}
+
+export interface EnsureCodebaseMapResult {
+  status: "generated" | "updated" | "fresh" | "empty";
+  fileCount: number;
+  truncated: boolean;
+  generatedAt: string | null;
+  fingerprint: string | null;
+  reason?: string;
+}
+
 interface FileEntry {
   path: string;
   description: string;
@@ -33,6 +56,18 @@ interface DirectoryGroup {
   collapsed: boolean;
 }
 
+interface ResolvedCodebaseMapOptions {
+  excludes: string[];
+  maxFiles: number;
+  collapseThreshold: number;
+  optionSignature: string;
+}
+
+interface EnumeratedFiles {
+  files: string[];
+  truncated: boolean;
+}
+
 // ─── Defaults ────────────────────────────────────────────────────────────────
 
 const DEFAULT_EXCLUDES = [
@@ -55,6 +90,11 @@ const DEFAULT_EXCLUDES = [
 
 const DEFAULT_MAX_FILES = 500;
 const DEFAULT_COLLAPSE_THRESHOLD = 20;
+const DEFAULT_REFRESH_TTL_MS = 30_000;
+const DEFAULT_MAX_AGE_MS = 15 * 60_000;
+const CODEBASE_METADATA_PREFIX = "<!-- gsd:codebase-meta ";
+
+const freshnessCache = new Map<string, { checkedAt: number; result: EnsureCodebaseMapResult }>();
 
 // ─── Parsing ─────────────────────────────────────────────────────────────────
 
@@ -96,6 +136,33 @@ export function parseCodebaseMap(content: string): Map<string, string> {
   return descriptions;
 }
 
+export function parseCodebaseMapMetadata(content: string): CodebaseMapMetadata | null {
+  const metaLine = content
+    .split("\n")
+    .find((line) => line.trimStart().startsWith(CODEBASE_METADATA_PREFIX));
+  if (!metaLine) return null;
+
+  const trimmed = metaLine.trim();
+  const jsonStart = CODEBASE_METADATA_PREFIX.length;
+  const jsonEnd = trimmed.lastIndexOf(" -->");
+  if (jsonEnd <= jsonStart) return null;
+
+  try {
+    const parsed = JSON.parse(trimmed.slice(jsonStart, jsonEnd));
+    if (
+      typeof parsed?.generatedAt === "string"
+      && typeof parsed?.fingerprint === "string"
+      && typeof parsed?.fileCount === "number"
+      && typeof parsed?.truncated === "boolean"
+    ) {
+      return parsed as CodebaseMapMetadata;
+    }
+  } catch {
+    // Ignore malformed metadata and treat the map as stale.
+  }
+  return null;
+}
+
 // ─── File Enumeration ────────────────────────────────────────────────────────
 
 function shouldExclude(filePath: string, excludes: string[]): boolean {
@@ -134,6 +201,36 @@ function enumerateFiles(basePath: string, excludes: string[], maxFiles: number):
   return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated };
 }
 
+function resolveGeneratorOptions(options?: CodebaseMapOptions): ResolvedCodebaseMapOptions {
+  const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
+  const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
+  const collapseThreshold = options?.collapseThreshold ?? DEFAULT_COLLAPSE_THRESHOLD;
+  return {
+    excludes,
+    maxFiles,
+    collapseThreshold,
+    optionSignature: JSON.stringify({
+      excludes,
+      maxFiles,
+      collapseThreshold,
+    }),
+  };
+}
+
+function computeCodebaseFingerprint(
+  files: string[],
+  resolved: ResolvedCodebaseMapOptions,
+  truncated: boolean,
+): string {
+  return createHash("sha1")
+    .update(JSON.stringify({
+      files,
+      truncated,
+      optionSignature: resolved.optionSignature,
+    }))
+    .digest("hex");
+}
+
 // ─── Grouping ────────────────────────────────────────────────────────────────
 
 function groupByDirectory(
@@ -174,14 +271,19 @@ function groupByDirectory(
 
 // ─── Rendering ───────────────────────────────────────────────────────────────
 
-function renderCodebaseMap(groups: DirectoryGroup[], totalFiles: number, truncated: boolean): string {
+function renderCodebaseMap(
+  groups: DirectoryGroup[],
+  totalFiles: number,
+  truncated: boolean,
+  metadata: CodebaseMapMetadata,
+): string {
   const lines: string[] = [];
-  const now = new Date().toISOString().split(".")[0] + "Z";
   const described = groups.reduce((sum, g) => sum + g.files.filter((f) => f.description).length, 0);
 
   lines.push("# Codebase Map");
   lines.push("");
-  lines.push(`Generated: ${now} | Files: ${totalFiles} | Described: ${described}/${totalFiles}`);
+  lines.push(`Generated: ${metadata.generatedAt} | Files: ${totalFiles} | Described: ${described}/${totalFiles}`);
+  lines.push(`${CODEBASE_METADATA_PREFIX}${JSON.stringify(metadata)} -->`);
   if (truncated) {
     lines.push(`Note: Truncated to first ${totalFiles} files. Run with higher --max-files to include all.`);
   }
@@ -229,6 +331,41 @@ function renderCodebaseMap(groups: DirectoryGroup[], totalFiles: number, truncat
   return lines.join("\n");
 }
 
+function buildCodebaseMap(
+  basePath: string,
+  resolved: ResolvedCodebaseMapOptions,
+  existingDescriptions?: Map<string, string>,
+  enumerated?: EnumeratedFiles,
+): {
+  content: string;
+  fileCount: number;
+  truncated: boolean;
+  files: string[];
+  fingerprint: string;
+  generatedAt: string;
+} {
+  const listed = enumerated ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+  const descriptions = existingDescriptions ?? new Map<string, string>();
+  const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold);
+  const generatedAt = new Date().toISOString().split(".")[0] + "Z";
+  const metadata: CodebaseMapMetadata = {
+    generatedAt,
+    fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated),
+    fileCount: listed.files.length,
+    truncated: listed.truncated,
+  };
+  const content = renderCodebaseMap(groups, listed.files.length, listed.truncated, metadata);
+
+  return {
+    content,
+    fileCount: listed.files.length,
+    truncated: listed.truncated,
+    files: listed.files,
+    fingerprint: metadata.fingerprint,
+    generatedAt,
+  };
+}
+
 // ─── Public API ──────────────────────────────────────────────────────────────
 
 /**
@@ -239,17 +376,9 @@ export function generateCodebaseMap(
   basePath: string,
   options?: CodebaseMapOptions,
   existingDescriptions?: Map<string, string>,
-): { content: string; fileCount: number; truncated: boolean; files: string[] } {
-  const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
-  const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
-  const collapseThreshold = options?.collapseThreshold ?? DEFAULT_COLLAPSE_THRESHOLD;
-
-  const { files, truncated } = enumerateFiles(basePath, excludes, maxFiles);
-  const descriptions = existingDescriptions ?? new Map<string, string>();
-  const groups = groupByDirectory(files, descriptions, collapseThreshold);
-  const content = renderCodebaseMap(groups, files.length, truncated);
-
-  return { content, fileCount: files.length, truncated, files };
+): { content: string; fileCount: number; truncated: boolean; files: string[]; fingerprint: string; generatedAt: string } {
+  const resolved = resolveGeneratorOptions(options);
+  return buildCodebaseMap(basePath, resolved, existingDescriptions);
 }
 
 /**
@@ -259,8 +388,18 @@ export function generateCodebaseMap(
 export function updateCodebaseMap(
   basePath: string,
   options?: CodebaseMapOptions,
-): { content: string; added: number; removed: number; unchanged: number; fileCount: number; truncated: boolean } {
+): {
+  content: string;
+  added: number;
+  removed: number;
+  unchanged: number;
+  fileCount: number;
+  truncated: boolean;
+  fingerprint: string;
+  generatedAt: string;
+} {
   const codebasePath = join(gsdRoot(basePath), "CODEBASE.md");
+  const resolved = resolveGeneratorOptions(options);
 
   // Load existing descriptions
   let existingDescriptions = new Map<string, string>();
@@ -273,7 +412,7 @@ export function updateCodebaseMap(
 
   // Generate new map preserving descriptions — reuse the returned file list
   // to avoid a second enumeration (prevents race between content and stats).
-  const result = generateCodebaseMap(basePath, options, existingDescriptions);
+  const result = buildCodebaseMap(basePath, resolved, existingDescriptions);
   const currentSet = new Set(result.files);
 
   // Count changes
@@ -294,9 +433,114 @@ export function updateCodebaseMap(
     unchanged: result.files.length - added,
     fileCount: result.fileCount,
     truncated: result.truncated,
+    fingerprint: result.fingerprint,
+    generatedAt: result.generatedAt,
   };
 }
 
+function clearFreshnessCache(basePath: string): void {
+  for (const key of freshnessCache.keys()) {
+    if (key === basePath || key.startsWith(`${basePath}::`)) {
+      freshnessCache.delete(key);
+    }
+  }
+}
+
+export function ensureCodebaseMapFresh(
+  basePath: string,
+  options?: CodebaseMapOptions,
+  ensureOptions?: EnsureCodebaseMapOptions,
+): EnsureCodebaseMapResult {
+  const resolved = resolveGeneratorOptions(options);
+  const cacheKey = `${basePath}::${resolved.optionSignature}`;
+  const ttlMs = ensureOptions?.ttlMs ?? DEFAULT_REFRESH_TTL_MS;
+  const maxAgeMs = ensureOptions?.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+  const force = ensureOptions?.force === true;
+  const now = Date.now();
+
+  if (!force && ttlMs > 0) {
+    const cached = freshnessCache.get(cacheKey);
+    if (cached && now - cached.checkedAt < ttlMs) {
+      return cached.result;
+    }
+  }
+
+  const existing = readCodebaseMap(basePath);
+  const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+  const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
+
+  const cacheAndReturn = (result: EnsureCodebaseMapResult): EnsureCodebaseMapResult => {
+    freshnessCache.set(cacheKey, { checkedAt: now, result });
+    return result;
+  };
+
+  if (!existing) {
+    const generated = buildCodebaseMap(basePath, resolved, undefined, listed);
+    if (generated.fileCount > 0) {
+      writeCodebaseMap(basePath, generated.content);
+      return cacheAndReturn({
+        status: "generated",
+        fileCount: generated.fileCount,
+        truncated: generated.truncated,
+        generatedAt: generated.generatedAt,
+        fingerprint: generated.fingerprint,
+        reason: "missing",
+      });
+    }
+    return cacheAndReturn({
+      status: "empty",
+      fileCount: 0,
+      truncated: false,
+      generatedAt: null,
+      fingerprint,
+      reason: "no-tracked-files",
+    });
+  }
+
+  const metadata = parseCodebaseMapMetadata(existing);
+  const existingDescriptions = parseCodebaseMap(existing);
+  const ageMs = metadata ? now - Date.parse(metadata.generatedAt) : Number.POSITIVE_INFINITY;
+  const staleReason =
+    !metadata ? "missing-metadata"
+    : metadata.fingerprint !== fingerprint ? "files-changed"
+    : metadata.fileCount !== listed.files.length ? "file-count-changed"
+    : metadata.truncated !== listed.truncated ? "truncation-changed"
+    : maxAgeMs > 0 && Number.isFinite(ageMs) && ageMs > maxAgeMs ? "expired"
+    : undefined;
+
+  if (!staleReason) {
+    return cacheAndReturn({
+      status: "fresh",
+      fileCount: metadata?.fileCount ?? listed.files.length,
+      truncated: metadata?.truncated ?? listed.truncated,
+      generatedAt: metadata?.generatedAt ?? null,
+      fingerprint: metadata?.fingerprint ?? fingerprint,
+    });
+  }
+
+  const updated = buildCodebaseMap(basePath, resolved, existingDescriptions, listed);
+  if (updated.fileCount > 0) {
+    writeCodebaseMap(basePath, updated.content);
+    return cacheAndReturn({
+      status: "updated",
+      fileCount: updated.fileCount,
+      truncated: updated.truncated,
+      generatedAt: updated.generatedAt,
+      fingerprint: updated.fingerprint,
+      reason: staleReason,
+    });
+  }
+
+  return cacheAndReturn({
+    status: "empty",
+    fileCount: 0,
+    truncated: false,
+    generatedAt: null,
+    fingerprint,
+    reason: staleReason,
+  });
+}
+
 /**
  * Write CODEBASE.md to .gsd/ directory.
  */
@@ -305,6 +549,7 @@ export function writeCodebaseMap(basePath: string, content: string): string {
   mkdirSync(root, { recursive: true });
   const outPath = join(root, "CODEBASE.md");
   writeFileSync(outPath, content, "utf-8");
+  clearFreshnessCache(basePath);
   return outPath;
 }
 

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -15,7 +15,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -41,6 +41,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
   { cmd: "export", desc: "Export milestone/slice results" },
   { cmd: "cleanup", desc: "Remove merged branches or snapshots" },
+  { cmd: "model", desc: "Switch the active session model or open a picker" },
   { cmd: "mode", desc: "Switch workflow mode (solo/team)" },
   { cmd: "prefs", desc: "Manage preferences (model selection, timeouts, etc.)" },
   { cmd: "config", desc: "Set API keys for external tools" },
@@ -72,7 +73,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "mcp", desc: "MCP server status and connectivity check (status, check <server>)" },
   { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
   { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
-  { cmd: "codebase", desc: "Generate and manage codebase map (.gsd/CODEBASE.md)" },
+  { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
@@ -236,7 +237,7 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" },
     { cmd: "generate --max-files", desc: "Generate with custom file limit (default: 500)" },
     { cmd: "generate --collapse-threshold", desc: "Generate with custom collapse threshold (default: 20)" },
-    { cmd: "update", desc: "Incremental update (preserves descriptions)" },
+    { cmd: "update", desc: "Refresh the CODEBASE.md cache immediately (preserves descriptions)" },
     { cmd: "update --max-files", desc: "Update with custom file limit" },
     { cmd: "update --collapse-threshold", desc: "Update with custom collapse threshold" },
     { cmd: "stats", desc: "Show file count, description coverage, and generation time" },

package/src/resources/extensions/gsd/commands/dispatcher.ts

@@ -14,7 +14,7 @@ export async function handleGSDCommand(
   const trimmed = (typeof args === "string" ? args : "").trim();
 
   const handlers = [
-    () => handleCoreCommand(trimmed, ctx),
+    () => handleCoreCommand(trimmed, ctx, pi),
     () => handleAutoCommand(trimmed, ctx, pi),
     () => handleParallelCommand(trimmed, ctx, pi),
     () => handleWorkflowCommand(trimmed, ctx, pi),
@@ -29,4 +29,3 @@ export async function handleGSDCommand(
 
   ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning");
 }
-

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -1,4 +1,5 @@
-import type { ExtensionCommandContext, ExtensionContext } from "@gsd/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@gsd/pi-coding-agent";
+import type { Model } from "@gsd/pi-ai";
 import type { GSDState } from "../../types.js";
 
 import { computeProgressScore, formatProgressLine } from "../../progress-score.js";
@@ -44,10 +45,12 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "",
     "PROJECT KNOWLEDGE",
     "  /gsd knowledge <type> <text>   Add rule, pattern, or lesson to KNOWLEDGE.md",
+    "  /gsd codebase [generate|update|stats]   Manage the CODEBASE.md cache used in prompt context",
     "",
     "SETUP & CONFIGURATION",
     "  /gsd init           Project init wizard — detect, configure, bootstrap .gsd/",
     "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
+    "  /gsd model          Switch active session model  [provider/model|model-id]",
     "  /gsd mode           Set workflow mode (solo/team)  [global|project]",
     "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]",
     "  /gsd cmux           Manage cmux integration  [status|on|off|notifications|sidebar|splits|browser]",
@@ -179,7 +182,106 @@ export async function handleSetup(args: string, ctx: ExtensionCommandContext): P
   );
 }
 
-export async function handleCoreCommand(trimmed: string, ctx: ExtensionCommandContext): Promise<boolean> {
+function sortModelsForSelection(models: Model<any>[], currentModel: Model<any> | undefined): Model<any>[] {
+  return [...models].sort((a, b) => {
+    const aCurrent = currentModel && a.provider === currentModel.provider && a.id === currentModel.id;
+    const bCurrent = currentModel && b.provider === currentModel.provider && b.id === currentModel.id;
+    if (aCurrent && !bCurrent) return -1;
+    if (!aCurrent && bCurrent) return 1;
+    const providerCmp = a.provider.localeCompare(b.provider);
+    if (providerCmp !== 0) return providerCmp;
+    return a.id.localeCompare(b.id);
+  });
+}
+
+async function resolveRequestedModel(
+  query: string,
+  ctx: ExtensionCommandContext,
+): Promise<Model<any> | undefined> {
+  const { resolveModelId } = await import("../../auto-model-selection.js");
+  const models = ctx.modelRegistry.getAvailable();
+  const exact = resolveModelId(query, models, ctx.model?.provider);
+  if (exact) return exact;
+
+  const lowerQuery = query.toLowerCase();
+  const partialMatches = models.filter((model) =>
+    model.id.toLowerCase().includes(lowerQuery)
+      || `${model.provider}/${model.id}`.toLowerCase().includes(lowerQuery),
+  );
+
+  if (partialMatches.length === 1) return partialMatches[0];
+  if (partialMatches.length === 0 || !ctx.hasUI) return undefined;
+
+  const sorted = sortModelsForSelection(partialMatches, ctx.model);
+  const optionToModel = new Map<string, Model<any>>();
+  const options = sorted.map((model) => {
+    const label = `${model.provider}/${model.id}`;
+    optionToModel.set(label, model);
+    return label;
+  });
+  options.push("(cancel)");
+
+  const choice = await ctx.ui.select(`Multiple models match "${query}" — choose one:`, options);
+  if (!choice || typeof choice !== "string" || choice === "(cancel)") return undefined;
+  return optionToModel.get(choice);
+}
+
+async function handleModel(trimmedArgs: string, ctx: ExtensionCommandContext, pi: ExtensionAPI | undefined): Promise<void> {
+  const availableModels = ctx.modelRegistry.getAvailable();
+  if (availableModels.length === 0) {
+    ctx.ui.notify("No available models found. Check provider auth and model discovery.", "warning");
+    return;
+  }
+  if (!pi) {
+    ctx.ui.notify("Model switching is unavailable in this context.", "warning");
+    return;
+  }
+
+  const trimmed = trimmedArgs.trim();
+  let targetModel: Model<any> | undefined;
+
+  if (!trimmed) {
+    if (!ctx.hasUI) {
+      const current = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "(none)";
+      ctx.ui.notify(`Current model: ${current}\nUsage: /gsd model <provider/model|model-id>`, "info");
+      return;
+    }
+
+    const optionToModel = new Map<string, Model<any>>();
+    const options = sortModelsForSelection(availableModels, ctx.model).map((model) => {
+      const isCurrent = ctx.model && model.provider === ctx.model.provider && model.id === ctx.model.id;
+      const label = `${isCurrent ? "* " : ""}${model.provider}/${model.id}`;
+      optionToModel.set(label, model);
+      return label;
+    });
+    options.push("(cancel)");
+
+    const choice = await ctx.ui.select("Select session model:", options);
+    if (!choice || typeof choice !== "string" || choice === "(cancel)") return;
+    targetModel = optionToModel.get(choice);
+  } else {
+    targetModel = await resolveRequestedModel(trimmed, ctx);
+  }
+
+  if (!targetModel) {
+    ctx.ui.notify(`Model "${trimmed}" not found. Use /gsd model with an exact provider/model or a unique model ID.`, "warning");
+    return;
+  }
+
+  const ok = await pi.setModel(targetModel);
+  if (!ok) {
+    ctx.ui.notify(`No API key for ${targetModel.provider}/${targetModel.id}`, "warning");
+    return;
+  }
+
+  ctx.ui.notify(`Model: ${targetModel.provider}/${targetModel.id}`, "info");
+}
+
+export async function handleCoreCommand(
+  trimmed: string,
+  ctx: ExtensionCommandContext,
+  pi?: ExtensionAPI,
+): Promise<boolean> {
   if (trimmed === "help" || trimmed === "h" || trimmed === "?") {
     showHelp(ctx);
     return true;
@@ -203,6 +305,10 @@ export async function handleCoreCommand(trimmed: string, ctx: ExtensionCommandCo
     ctx.ui.notify(`Widget: ${getWidgetMode()}`, "info");
     return true;
   }
+  if (trimmed === "model" || trimmed.startsWith("model ")) {
+    await handleModel(trimmed.replace(/^model\s*/, "").trim(), ctx, pi);
+    return true;
+  }
   if (trimmed === "mode" || trimmed.startsWith("mode ")) {
     const modeArgs = trimmed.replace(/^mode\s*/, "").trim();
     const scope = modeArgs === "project" ? "project" : "global";

package/src/resources/extensions/gsd/commands-bootstrap.ts

@@ -45,6 +45,7 @@ const TOP_LEVEL_SUBCOMMANDS = [
   { cmd: "start", desc: "Start a workflow template" },
   { cmd: "templates", desc: "List available workflow templates" },
   { cmd: "extensions", desc: "Manage extensions" },
+  { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache" },
 ] as const;
 
 function filterStartsWith(
@@ -218,6 +219,15 @@ function getGsdArgumentCompletions(prefix: string) {
     ], "extensions");
   }
 
+  if (parts[0] === "codebase" && parts.length <= 2) {
+    return filterStartsWith(partial, [
+      { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" },
+      { cmd: "update", desc: "Refresh the CODEBASE.md cache immediately" },
+      { cmd: "stats", desc: "Show codebase-map coverage and generation time" },
+      { cmd: "help", desc: "Show usage and subcommands" },
+    ], "codebase");
+  }
+
   if (parts[0] === "doctor" && parts.length <= 2) {
     return filterStartsWith(partial, [
       { cmd: "fix", desc: "Auto-fix detected issues" },

package/src/resources/extensions/gsd/commands-codebase.ts

@@ -20,10 +20,11 @@ import type { CodebaseMapOptions } from "./codebase-generator.js";
 const USAGE =
   "Usage: /gsd codebase [generate|update|stats]\n\n" +
   "  generate [--max-files N] [--collapse-threshold N]  — Generate or regenerate CODEBASE.md\n" +
-  "  update [--max-files N] [--collapse-threshold N]    — Incremental update (preserves descriptions)\n" +
+  "  update [--max-files N] [--collapse-threshold N]    — Refresh the CODEBASE.md cache immediately\n" +
   "  stats                                              — Show file count, coverage, and generation time\n" +
   "  help                                               — Show this help\n\n" +
-  "With no subcommand, shows stats if a map exists or help if not.\n\n" +
+  "With no subcommand, shows stats if a map exists or help if not.\n" +
+  "GSD also refreshes CODEBASE.md automatically before prompt injection and after completed units when tracked files change.\n\n" +
   "Configure defaults via preferences.md:\n" +
   "  codebase:\n" +
   "    exclude_patterns: [\"docs/\", \"fixtures/\"]\n" +
@@ -141,7 +142,7 @@ function showStats(basePath: string, ctx: ExtensionCommandContext): void {
     `  Undescribed: ${stats.undescribedCount}\n` +
     `  Generated: ${stats.generatedAt ?? "unknown"}\n\n` +
     (stats.undescribedCount > 0
-      ? `Tip: Run /gsd codebase update to refresh after file changes.`
+      ? `Tip: Auto-refresh keeps the cache current, but /gsd codebase update forces an immediate refresh.`
       : `Coverage is complete.`),
     "info",
   );