gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

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

@@ -4,7 +4,7 @@ import type { GSDState } from "../../types.js";
 
 import { computeProgressScore, formatProgressLine } from "../../progress-score.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath, getProjectGSDPreferencesPath } from "../../preferences.js";
-import { ensurePreferencesFile, handlePrefs, handlePrefsMode, handlePrefsWizard } from "../../commands-prefs-wizard.js";
+import { ensurePreferencesFile, handlePrefs, handlePrefsMode, handlePrefsWizard, handleLanguage } from "../../commands-prefs-wizard.js";
 import { runEnvironmentChecks } from "../../doctor-environment.js";
 import { deriveState } from "../../state.js";
 import { handleCmux } from "../../commands-cmux.js";
@@ -36,11 +36,17 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd undo           Revert last completed unit  [--force]",
     "  /gsd rethink        Conversational project reorganization",
     "",
+    "OBSERVABILITY",
+    "  /gsd logs           Browse activity and debug logs",
+    "  /gsd debug          Create/list/continue persistent debug sessions",
+    "",
     "SETUP",
+    "  /gsd onboarding     Re-run setup wizard  [--resume|--reset|--step <name>]",
+    "  /gsd setup          Configuration hub  [llm|model|search|remote|keys|prefs|onboarding]",
     "  /gsd init           Project init wizard",
-    "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
     "  /gsd model          Switch active session model",
-    "  /gsd prefs          Manage preferences",
+    "  /gsd prefs          Manage preferences (alias for /gsd setup prefs)",
+    "  /gsd keys           API key manager (LLM + tool keys)",
     "  /gsd doctor         Diagnose and repair .gsd/ state",
     "",
     "Use /gsd help full for the complete command reference.",
@@ -67,6 +73,8 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
     "  /gsd changelog      Show categorized release notes  [version]",
     `  /gsd notifications  View persistent notification history  [clear|tail|filter]  (${formattedShortcutPair("notifications")})`,
+    "  /gsd logs           Browse activity logs, debug logs, and metrics",
+    "  /gsd debug          Create/list/continue persistent debug sessions",
     "",
     "COURSE CORRECTION",
     "  /gsd steer <desc>   Apply user override to active work",
@@ -83,14 +91,15 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd codebase [generate|update|stats]   Manage the CODEBASE.md cache used in prompt context",
     "",
     "SETUP & CONFIGURATION",
+    "  /gsd onboarding     Re-run setup wizard  [--resume|--reset|--step <name>]",
+    "  /gsd setup          Configuration hub  [llm|model|search|remote|keys|prefs|onboarding]",
     "  /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 prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]  (alias for /gsd setup prefs)",
     "  /gsd cmux           Manage cmux integration  [status|on|off|notifications|sidebar|splits|browser]",
-    "  /gsd config         Set API keys for external tools",
-    "  /gsd keys           API key manager  [list|add|remove|test|rotate|doctor]",
+    "  /gsd keys           API key manager (LLM + tool keys)  [list|add|remove|test|rotate|doctor]",
+    "  /gsd config         (deprecated) Set tool API keys — use /gsd keys instead",
     "  /gsd show-config    Show effective configuration (models, routing, toggles)",
     "  /gsd hooks          Show post-unit hook configuration",
     "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
@@ -170,32 +179,39 @@ export async function handleVisualize(ctx: ExtensionCommandContext): Promise<voi
   }
 }
 
-export async function handleSetup(args: string, ctx: ExtensionCommandContext): Promise<void> {
+export async function handleSetup(args: string, ctx: ExtensionCommandContext, pi?: ExtensionAPI): Promise<void> {
   const { detectProjectState, hasGlobalSetup } = await import("../../detection.js");
-
-  const globalConfigured = hasGlobalSetup();
-  const detection = detectProjectState(projectRoot());
-
-  const statusLines = ["GSD Setup Status\n"];
-  statusLines.push(`  Global preferences: ${globalConfigured ? "configured" : "not set"}`);
-  statusLines.push(`  Project state: ${detection.state}`);
-  if (detection.projectSignals.primaryLanguage) {
-    statusLines.push(`  Detected: ${detection.projectSignals.primaryLanguage}`);
+  const { isOnboardingComplete, readOnboardingRecord } = await import("../../onboarding-state.js");
+
+  // Sub-route dispatch — keep redirects but route the canonical work to /gsd
+  // onboarding (single source for wizard steps) and /gsd keys (single source
+  // for credentials).
+  if (args === "onboarding" || args === "wizard") {
+    const { handleOnboarding } = await import("./onboarding.js");
+    await handleOnboarding("", ctx);
+    return;
   }
-
   if (args === "llm" || args === "auth") {
-    ctx.ui.notify("Use /login to configure LLM authentication.", "info");
+    const { handleOnboarding } = await import("./onboarding.js");
+    await handleOnboarding("--step llm", ctx);
     return;
   }
   if (args === "search") {
-    ctx.ui.notify("Use /search-provider to configure web search.", "info");
+    const { handleOnboarding } = await import("./onboarding.js");
+    await handleOnboarding("--step search", ctx);
     return;
   }
   if (args === "remote") {
-    ctx.ui.notify("Use /gsd remote to configure remote questions.", "info");
+    const { handleOnboarding } = await import("./onboarding.js");
+    await handleOnboarding("--step remote", ctx);
+    return;
+  }
+  if (args === "model") {
+    await handleModel("", ctx, pi);
     return;
   }
   if (args === "keys") {
+    ctx.ui.notify("Tip: /gsd keys is the canonical command for API key management.", "info");
     const { handleKeys } = await import("../../key-manager.js");
     await handleKeys("", ctx);
     return;
@@ -206,14 +222,35 @@ export async function handleSetup(args: string, ctx: ExtensionCommandContext): P
     return;
   }
 
+  // Bare /gsd setup — render the hub: status + actions
+  const globalConfigured = hasGlobalSetup();
+  const detection = detectProjectState(projectRoot());
+  const onboardingDone = isOnboardingComplete();
+  const record = readOnboardingRecord();
+
+  const statusLines: string[] = ["GSD Setup\n"];
+  statusLines.push(
+    onboardingDone
+      ? `  Onboarding:         ✓ complete${record.completedAt ? ` (${record.completedAt.slice(0, 10)})` : ""}`
+      : `  Onboarding:         ○ not complete  —  /gsd onboarding to start`,
+  );
+  statusLines.push(`  Global preferences: ${globalConfigured ? "configured" : "not set"}`);
+  statusLines.push(`  Project state:      ${detection.state}`);
+  if (detection.projectSignals.primaryLanguage) {
+    statusLines.push(`  Detected:           ${detection.projectSignals.primaryLanguage}`);
+  }
+
   ctx.ui.notify(statusLines.join("\n"), "info");
   ctx.ui.notify(
-    "Available setup commands:\n" +
-    "  /gsd setup llm     — LLM authentication\n" +
-    "  /gsd setup search  — Web search provider\n" +
-    "  /gsd setup remote  — Remote questions (Discord/Slack/Telegram)\n" +
-    "  /gsd setup keys    — Tool API keys\n" +
-    "  /gsd setup prefs   — Global preferences wizard",
+    "Configuration hub:\n" +
+    "  /gsd setup llm        — LLM provider & auth\n" +
+    "  /gsd setup model      — Default model picker\n" +
+    "  /gsd setup search     — Web search provider\n" +
+    "  /gsd setup remote     — Remote questions (Discord/Slack/Telegram)\n" +
+    "  /gsd setup keys       — API keys (alias for /gsd keys)\n" +
+    "  /gsd setup prefs      — Global preferences (alias for /gsd prefs)\n" +
+    "  /gsd setup onboarding — Full wizard (alias for /gsd onboarding)\n\n" +
+    "Tip: /gsd onboarding --resume to continue an incomplete setup.",
     "info",
   );
 }
@@ -395,6 +432,10 @@ export async function handleCoreCommand(
     await handlePrefs(trimmed.replace(/^prefs\s*/, "").trim(), ctx);
     return true;
   }
+  if (trimmed === "language" || trimmed.startsWith("language ")) {
+    await handleLanguage(trimmed.replace(/^language\s*/, "").trim(), ctx);
+    return true;
+  }
   if (trimmed === "cmux" || trimmed.startsWith("cmux ")) {
     await handleCmux(trimmed.replace(/^cmux\s*/, "").trim(), ctx);
     return true;
@@ -419,7 +460,12 @@ export async function handleCoreCommand(
     return true;
   }
   if (trimmed === "setup" || trimmed.startsWith("setup ")) {
-    await handleSetup(trimmed.replace(/^setup\s*/, "").trim(), ctx);
+    await handleSetup(trimmed.replace(/^setup\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "onboarding" || trimmed.startsWith("onboarding ")) {
+    const { handleOnboarding } = await import("./onboarding.js");
+    await handleOnboarding(trimmed.replace(/^onboarding\s*/, "").trim(), ctx);
     return true;
   }
   return false;

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

@@ -0,0 +1,216 @@
+// GSD Extension — /gsd escalate Command Handler (ADR-011 Phase 2)
+// Surface and resolve mid-execution escalations from the CLI.
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { projectRoot } from "../context.js";
+import { getActiveMilestoneId } from "../../state.js";
+import {
+  readEscalationArtifact,
+  formatEscalationForDisplay,
+  resolveEscalation,
+  listActionableEscalations,
+  listAllEscalations,
+} from "../../escalation.js";
+import { saveDecisionToDb } from "../../db-writer.js";
+import { loadEffectiveGSDPreferences } from "../../preferences.js";
+import { invalidateStateCache } from "../../state.js";
+import { emitUokAuditEvent, buildAuditEnvelope } from "../../uok/audit.js";
+
+function helpMessage(): string {
+  return [
+    "/gsd escalate — manage mid-execution escalations (ADR-011 Phase 2)",
+    "",
+    "Subcommands:",
+    "  list [--all]           show pending escalations (use --all to include resolved)",
+    "  show <taskId>          print the escalation artifact",
+    "  resolve <taskId> <choice> [rationale...]",
+    "                         resolve an escalation — choice is an option id,",
+    "                         `accept` (use recommendation), or `reject-blocker`",
+    "                         (convert to a blocker and trigger slice replan)",
+    "",
+    "Note: disabling `phases.mid_execution_escalation` does NOT clear pending",
+    "escalations. If you need to drain them, re-enable the flag, resolve via",
+    "`/gsd escalate resolve`, then disable.",
+  ].join("\n");
+}
+
+function formatListEntries(
+  rows: ReturnType<typeof listActionableEscalations>,
+  basePath: string,
+): string {
+  if (rows.length === 0) return "No escalations.";
+  return rows.map((t) => {
+    const art = t.escalation_artifact_path ? readEscalationArtifact(t.escalation_artifact_path) : null;
+    const status = t.escalation_pending ? "PENDING (paused)" : t.escalation_awaiting_review ? "awaiting-review" : "resolved";
+    const question = art?.question ?? "(artifact missing)";
+    return `  ${t.slice_id}/${t.id}  [${status}]  ${question}`;
+  }).join("\n");
+}
+
+export async function handleEscalateCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  void pi;
+
+  const trimmed = args.trim();
+  if (trimmed === "" || trimmed === "help") {
+    ctx.ui.notify(helpMessage(), "info");
+    return;
+  }
+
+  const basePath = projectRoot();
+  const prefs = loadEffectiveGSDPreferences()?.preferences;
+  if (prefs?.phases?.mid_execution_escalation !== true) {
+    ctx.ui.notify(
+      "Escalation is off. Enable with `phases: { mid_execution_escalation: true }` in your PREFERENCES.md.",
+      "warning",
+    );
+    return;
+  }
+
+  const milestoneId = await getActiveMilestoneId(basePath);
+  if (!milestoneId) {
+    ctx.ui.notify("No active milestone — cannot list escalations.", "warning");
+    return;
+  }
+
+  // ── list ────────────────────────────────────────────────────────────────
+  if (trimmed === "list" || trimmed === "list --all" || trimmed === "--all") {
+    const includeAll = trimmed.includes("--all");
+    const rows = includeAll ? listAllEscalations(milestoneId) : listActionableEscalations(milestoneId);
+    const body = formatListEntries(rows, basePath);
+    ctx.ui.notify(
+      `${includeAll ? "All escalations" : "Actionable escalations"} for ${milestoneId}:\n${body}`,
+      "info",
+    );
+    return;
+  }
+
+  // Parse a possibly-slice-qualified task id: "Sxx/Tyy" or plain "Tyy".
+  // Returns { sliceId?, taskId }.
+  const parseTaskRef = (ref: string): { sliceId?: string; taskId: string } => {
+    const slash = ref.indexOf("/");
+    if (slash > 0) {
+      return { sliceId: ref.slice(0, slash), taskId: ref.slice(slash + 1) };
+    }
+    return { taskId: ref };
+  };
+
+  // Resolve a task ref to a single row, surfacing ambiguity when a bare task
+  // id matches more than one slice.
+  const locateRow = (ref: string): ReturnType<typeof listAllEscalations>[number] | "ambiguous" | "not-found" => {
+    const { sliceId, taskId } = parseTaskRef(ref);
+    const rows = listAllEscalations(milestoneId).filter(
+      (t) => t.id === taskId && (sliceId === undefined || t.slice_id === sliceId),
+    );
+    if (rows.length === 0) return "not-found";
+    if (rows.length > 1) return "ambiguous";
+    return rows[0]!;
+  };
+
+  // ── show <taskRef> ──────────────────────────────────────────────────────
+  if (trimmed.startsWith("show ")) {
+    const ref = trimmed.slice(5).trim();
+    const row = locateRow(ref);
+    if (row === "ambiguous") {
+      ctx.ui.notify(`Task ${ref} matches multiple slices. Use Sxx/Tyy format.`, "warning");
+      return;
+    }
+    if (row === "not-found" || !row.escalation_artifact_path) {
+      ctx.ui.notify(`No escalation found for ${ref} in ${milestoneId}.`, "warning");
+      return;
+    }
+    const art = readEscalationArtifact(row.escalation_artifact_path);
+    if (!art) {
+      ctx.ui.notify(`Escalation artifact at ${row.escalation_artifact_path} is missing or malformed.`, "error");
+      return;
+    }
+    ctx.ui.notify(formatEscalationForDisplay(art), "info");
+    return;
+  }
+
+  // ── resolve <taskRef> <choice> [rationale...] ───────────────────────────
+  if (trimmed.startsWith("resolve ")) {
+    const parts = trimmed.slice(8).trim().split(/\s+/);
+    const ref = parts[0];
+    const choice = parts[1];
+    const rationale = parts.slice(2).join(" ").trim();
+    if (!ref || !choice) {
+      ctx.ui.notify("Usage: /gsd escalate resolve <taskId|Sxx/Tyy> <choice> [rationale...]", "warning");
+      return;
+    }
+
+    const row = locateRow(ref);
+    if (row === "ambiguous") {
+      ctx.ui.notify(`Task ${ref} matches multiple slices. Use Sxx/Tyy format.`, "warning");
+      return;
+    }
+    if (row === "not-found") {
+      ctx.ui.notify(`No escalation found for ${ref} in ${milestoneId}.`, "warning");
+      return;
+    }
+    const taskId = row.id;
+
+    const result = resolveEscalation(basePath, milestoneId, row.slice_id, taskId, choice, rationale);
+    invalidateStateCache();
+
+    if (result.status !== "resolved" && result.status !== "rejected-to-blocker") {
+      ctx.ui.notify(result.message, result.status === "invalid-choice" ? "warning" : "error");
+      return;
+    }
+
+    // Persist the user's choice as a decision (only for resolved, not reject-blocker).
+    if (result.status === "resolved") {
+      try {
+        const art = row.escalation_artifact_path ? readEscalationArtifact(row.escalation_artifact_path) : null;
+        const scope = `${milestoneId}/${row.slice_id}/${taskId}`;
+        const decisionText = art?.question ?? `escalation on ${taskId}`;
+        const choiceLabel = choice === "accept"
+          ? `${art?.recommendation ?? "accepted"} (recommended)`
+          : (result.chosenOption?.label ?? choice);
+        const { id: decisionId } = await saveDecisionToDb({
+          scope,
+          decision: decisionText,
+          choice: choiceLabel,
+          rationale: rationale || result.chosenOption?.tradeoffs || "User-resolved escalation.",
+          made_by: "human",
+          source: "escalation",
+          when_context: `ADR-011 escalation resolved ${new Date().toISOString()}`,
+        }, basePath);
+
+        emitUokAuditEvent(basePath, buildAuditEnvelope({
+          traceId: `escalation:${milestoneId}:${row.slice_id}:${taskId}`,
+          category: "gate",
+          type: "escalation-decision-persisted",
+          payload: {
+            milestoneId,
+            sliceId: row.slice_id,
+            taskId,
+            decisionId,
+            choice,
+          },
+        }));
+
+        ctx.ui.notify(
+          `${result.message}\nDecision recorded as ${decisionId}. Run /gsd auto to continue.`,
+          "success",
+        );
+      } catch (decErr) {
+        ctx.ui.notify(
+          `${result.message}\nWARN: decision persistence failed: ${(decErr as Error).message}`,
+          "warning",
+        );
+      }
+      return;
+    }
+
+    // rejected-to-blocker path
+    ctx.ui.notify(`${result.message} Run /gsd auto to trigger the replan.`, "success");
+    return;
+  }
+
+  ctx.ui.notify(`Unknown subcommand. ${helpMessage()}`, "warning");
+}

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

@@ -0,0 +1,229 @@
+// GSD — /gsd onboarding command handler (re-entry, --resume, --reset, --step)
+//
+// Provides the discoverable re-entry point for the onboarding wizard. The
+// first-run wizard in src/onboarding.ts is hidden behind shouldRunOnboarding;
+// this handler lets users re-launch it on demand.
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent"
+import { AuthStorage } from "@gsd/pi-coding-agent"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import {
+  ONBOARDING_STEPS,
+  isValidStepId,
+  nearestResumeStep,
+  type OnboardingStepId,
+} from "../../setup-catalog.js"
+import {
+  isOnboardingComplete,
+  readOnboardingRecord,
+  resetOnboarding,
+} from "../../onboarding-state.js"
+
+// Inline auth path (mirrors src/app-paths.ts) — keep this module rootDir-clean
+// for the resources tsconfig. Importing from src/ pulls files outside
+// src/resources and breaks the build.
+const AUTH_FILE_PATH = join(
+  process.env.GSD_CODING_AGENT_DIR ||
+    join(process.env.GSD_HOME || join(homedir(), ".gsd"), "agent"),
+  "auth.json",
+)
+
+/**
+ * Dynamic import shim for the first-run wizard.
+ *
+ * src/onboarding.ts lives outside the resources rootDir, so a static import
+ * pulls it into this tsconfig project and triggers TS6059. We resolve the
+ * specifier through a variable + opaque type so TS can't pull the file at
+ * compile time; the path resolves correctly at runtime via dist/onboarding.js.
+ */
+type FirstRunWizardModule = {
+  runOnboarding: (storage: AuthStorage) => Promise<void>
+  runLlmStep: (...args: unknown[]) => Promise<unknown>
+  runWebSearchStep: (...args: unknown[]) => Promise<unknown>
+  runRemoteQuestionsStep: (...args: unknown[]) => Promise<unknown>
+  runToolKeysStep: (...args: unknown[]) => Promise<unknown>
+}
+async function loadFirstRunWizard(): Promise<FirstRunWizardModule> {
+  const specifier = "../../../../../onboarding.js"
+  return (await import(/* @vite-ignore */ specifier)) as FirstRunWizardModule
+}
+
+interface ParsedArgs {
+  resume: boolean
+  reset: boolean
+  step: string | null
+  stepValid: boolean | null
+}
+
+function parseArgs(raw: string): ParsedArgs {
+  const tokens = raw.split(/\s+/).filter(Boolean)
+  const out: ParsedArgs = { resume: false, reset: false, step: null, stepValid: null }
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i]
+    if (t === "--resume" || t === "resume") out.resume = true
+    else if (t === "--reset" || t === "reset") out.reset = true
+    else if (t === "--step" || t === "step") {
+      const next = tokens[i + 1]
+      if (next) {
+        out.step = next
+        out.stepValid = isValidStepId(next)
+        i++
+      }
+    } else if (t.startsWith("--step=")) {
+      const v = t.slice(7)
+      out.step = v
+      out.stepValid = isValidStepId(v)
+    }
+  }
+  return out
+}
+
+async function getAuthStorage(): Promise<AuthStorage> {
+  return AuthStorage.create(AUTH_FILE_PATH)
+}
+
+async function runWholeWizard(ctx: ExtensionCommandContext, fromStep?: OnboardingStepId): Promise<void> {
+  const authStorage = await getAuthStorage()
+  // The first-run wizard ignores the resume hint today — it always walks the
+  // full sequence with skip prompts. We still mark completion at the end and
+  // record the resume hint for next time. This keeps the wizard linear and
+  // simple; per-step jump support comes via --step.
+  if (fromStep) {
+    ctx.ui.notify(
+      `Resuming from step: ${fromStep}. The wizard runs all remaining steps; press skip on any you've already configured.`,
+      "info",
+    )
+  }
+  const { runOnboarding } = await loadFirstRunWizard()
+  await runOnboarding(authStorage)
+}
+
+async function runSingleStep(ctx: ExtensionCommandContext, stepId: OnboardingStepId): Promise<void> {
+  const authStorage = await getAuthStorage()
+  const ob = await loadFirstRunWizard()
+  // Lazy-load clack + chalk via the same path the wizard uses
+  const p = await import("@clack/prompts")
+  const { default: chalk } = await import("chalk")
+  const pc = {
+    cyan: chalk.cyan, green: chalk.green, yellow: chalk.yellow,
+    dim: chalk.dim, bold: chalk.bold, red: chalk.red, reset: chalk.reset,
+  }
+
+  switch (stepId) {
+    case "llm":
+      await ob.runLlmStep(p as any, pc as any, authStorage)
+      return
+    case "search":
+      await ob.runWebSearchStep(p as any, pc as any, authStorage, false)
+      return
+    case "remote":
+      await ob.runRemoteQuestionsStep(p as any, pc as any, authStorage)
+      return
+    case "tool-keys":
+      await ob.runToolKeysStep(p as any, pc as any, authStorage)
+      return
+    case "model": {
+      // Delegate to /gsd model picker
+      const { handleCoreCommand } = await import("./core.js")
+      await handleCoreCommand("model", ctx)
+      return
+    }
+    case "prefs": {
+      const { ensurePreferencesFile, handlePrefsWizard } = await import("../../commands-prefs-wizard.js")
+      const { getGlobalGSDPreferencesPath } = await import("../../preferences.js")
+      await ensurePreferencesFile(getGlobalGSDPreferencesPath(), ctx, "global")
+      await handlePrefsWizard(ctx, "global")
+      return
+    }
+    case "doctor": {
+      // Best-effort: surface provider doctor results inline
+      try {
+        const { runProviderDoctor } = await import("../../doctor-providers.js") as any
+        if (typeof runProviderDoctor === "function") {
+          await runProviderDoctor(ctx)
+          return
+        }
+      } catch { /* fall through */ }
+      ctx.ui.notify("Run /gsd doctor to validate your setup.", "info")
+      return
+    }
+    case "skills": {
+      ctx.ui.notify("Skill install runs automatically during /gsd init. Use /gsd init or /skill manage.", "info")
+      return
+    }
+    case "project": {
+      const { handleCoreCommand } = await import("./core.js")
+      await handleCoreCommand("init", ctx)
+      return
+    }
+  }
+}
+
+function renderStatus(): string {
+  const r = readOnboardingRecord()
+  const lines: string[] = ["GSD Onboarding\n"]
+  if (r.completedAt) {
+    lines.push(`  Completed: ${r.completedAt}`)
+  } else {
+    lines.push(`  Status: not complete`)
+  }
+  if (r.lastResumePoint) lines.push(`  Last step: ${r.lastResumePoint}`)
+  lines.push("")
+  lines.push("  Steps:")
+  for (const step of ONBOARDING_STEPS) {
+    const mark = r.completedSteps.includes(step.id)
+      ? "✓"
+      : r.skippedSteps.includes(step.id)
+        ? "↷"
+        : "○"
+    const reqTag = step.required ? " (required)" : ""
+    lines.push(`    ${mark} ${step.id.padEnd(10)} — ${step.label}${reqTag}`)
+  }
+  return lines.join("\n")
+}
+
+export async function handleOnboarding(rawArgs: string, ctx: ExtensionCommandContext): Promise<void> {
+  const args = parseArgs(rawArgs.trim())
+
+  if (args.step !== null) {
+    if (!args.stepValid) {
+      const validIds = ONBOARDING_STEPS.map(s => s.id).join(", ")
+      ctx.ui.notify(`Unknown step "${args.step}". Valid: ${validIds}`, "warning")
+      return
+    }
+    await runSingleStep(ctx, args.step as OnboardingStepId)
+    return
+  }
+
+  if (args.reset) {
+    resetOnboarding()
+    ctx.ui.notify(
+      "Onboarding reset. Existing API keys/credentials are unchanged — manage them with /gsd keys.",
+      "info",
+    )
+    await runWholeWizard(ctx)
+    return
+  }
+
+  if (args.resume) {
+    const r = readOnboardingRecord()
+    const next = nearestResumeStep(r.lastResumePoint, r.completedSteps)
+    await runWholeWizard(ctx, next)
+    return
+  }
+
+  // No flags. If already complete, show status + offer choice.
+  if (isOnboardingComplete()) {
+    ctx.ui.notify(renderStatus(), "info")
+    ctx.ui.notify(
+      "Onboarding already complete. Use /gsd onboarding --reset to start over, or --step <name> to redo one section.",
+      "info",
+    )
+    return
+  }
+
+  await runWholeWizard(ctx)
+}
+
+export { renderStatus as renderOnboardingStatus }