gsd-pi 2.75.0 → 2.76.0

package/src/resources/extensions/gsd/bootstrap/memory-tools.ts

@@ -0,0 +1,158 @@
+// GSD2 — Memory tool registration
+//
+// Exposes the memory-layer tools (capture_thought, memory_query, gsd_graph)
+// to the LLM over MCP. All three degrade gracefully when the GSD database
+// is unavailable.
+
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+import { ensureDbOpen } from "./dynamic-tools.js";
+import {
+  executeGsdGraph,
+  executeMemoryCapture,
+  executeMemoryQuery,
+} from "../tools/memory-tools.js";
+
+export function registerMemoryTools(pi: ExtensionAPI): void {
+  // ─── capture_thought ────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "capture_thought",
+    label: "Capture Thought",
+    description:
+      "Record a durable piece of project knowledge (decision, convention, gotcha, pattern, " +
+      "preference, or environment detail) into the GSD memory store. Use sparingly — one memory " +
+      "per genuinely reusable insight, not per task.",
+    promptSnippet:
+      "Capture a durable project insight into the GSD memory store (categories: architecture, convention, gotcha, pattern, preference, environment)",
+    promptGuidelines: [
+      "Use capture_thought for insights that will remain useful across future sessions.",
+      "Do NOT capture one-off bug fixes, temporary state, secrets, or task-specific details.",
+      "Keep content to 1–3 sentences.",
+      "Set confidence: 0.6 tentative, 0.8 solid, 0.95 well-confirmed (default 0.8).",
+    ],
+    parameters: Type.Object({
+      category: Type.Union(
+        [
+          Type.Literal("architecture"),
+          Type.Literal("convention"),
+          Type.Literal("gotcha"),
+          Type.Literal("preference"),
+          Type.Literal("environment"),
+          Type.Literal("pattern"),
+        ],
+        { description: "Memory category" },
+      ),
+      content: Type.String({ description: "The memory text (1–3 sentences, no secrets)" }),
+      confidence: Type.Optional(
+        Type.Number({ description: "0.1–0.99, default 0.8", minimum: 0.1, maximum: 0.99 }),
+      ),
+      tags: Type.Optional(Type.Array(Type.String(), { description: "Free-form tags (reserved for future use)" })),
+      scope: Type.Optional(Type.String({ description: "Scope name (reserved for future use; defaults to project)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const ok = await ensureDbOpen();
+      if (!ok) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot capture memory." }],
+          details: { operation: "memory_capture", error: "db_unavailable" },
+          isError: true,
+        };
+      }
+      return executeMemoryCapture(params as Parameters<typeof executeMemoryCapture>[0]);
+    },
+  });
+
+  // ─── memory_query ───────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "memory_query",
+    label: "Query Memory",
+    description:
+      "Search the GSD memory store for relevant memories. Phase 1 uses keyword matching ranked " +
+      "by confidence and reinforcement; future phases add semantic (embedding) retrieval.",
+    promptSnippet:
+      "Search the GSD memory store by keyword; returns ranked memories with id, category, and content",
+    promptGuidelines: [
+      "Use memory_query when you need durable project context that may not be in the current prompt.",
+      "Provide a short keyword-style query — not a full question.",
+      "Use category to narrow results to gotchas, conventions, architecture notes, etc.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Keyword query (2+ char terms)" }),
+      k: Type.Optional(Type.Number({ description: "Max results (default 10, max 50)", minimum: 1, maximum: 50 })),
+      category: Type.Optional(
+        Type.Union(
+          [
+            Type.Literal("architecture"),
+            Type.Literal("convention"),
+            Type.Literal("gotcha"),
+            Type.Literal("preference"),
+            Type.Literal("environment"),
+            Type.Literal("pattern"),
+          ],
+          { description: "Restrict results to a single category" },
+        ),
+      ),
+      scope: Type.Optional(Type.String({ description: "Only include memories with this scope (e.g. 'project', 'global')" })),
+      tag: Type.Optional(Type.String({ description: "Only include memories tagged with this value" })),
+      include_superseded: Type.Optional(Type.Boolean({ description: "Include superseded memories (default false)" })),
+      reinforce_hits: Type.Optional(
+        Type.Boolean({ description: "Increment hit_count on returned memories (default false)" }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const ok = await ensureDbOpen();
+      if (!ok) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot query memory." }],
+          details: { operation: "memory_query", error: "db_unavailable" },
+          isError: true,
+        };
+      }
+      return executeMemoryQuery(params as Parameters<typeof executeMemoryQuery>[0]);
+    },
+  });
+
+  // ─── gsd_graph ──────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "gsd_graph",
+    label: "GSD Knowledge Graph",
+    description:
+      "Inspect the relationship graph between memories. mode=query walks supersedes edges from a " +
+      "given memoryId; mode=build is a placeholder that future phases will use to rebuild graph " +
+      "edges from milestone LEARNINGS artifacts.",
+    promptSnippet: "Query the memory relationship graph or trigger a rebuild",
+    promptGuidelines: [
+      "Use mode=query with a memoryId when you want to see how a memory relates to others.",
+      "Phase 1 only exposes supersedes edges; additional relation types arrive in later phases.",
+    ],
+    parameters: Type.Object({
+      mode: Type.Union([Type.Literal("build"), Type.Literal("query")], {
+        description: "build = recompute graph (placeholder), query = inspect edges",
+      }),
+      memoryId: Type.Optional(Type.String({ description: "Memory ID (required when mode=query)" })),
+      depth: Type.Optional(Type.Number({ description: "Hops to traverse (0–5, default 1)", minimum: 0, maximum: 5 })),
+      rel: Type.Optional(Type.Union([
+        Type.Literal("related_to"),
+        Type.Literal("depends_on"),
+        Type.Literal("contradicts"),
+        Type.Literal("elaborates"),
+        Type.Literal("supersedes"),
+      ], { description: "Only include edges with this relation type" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const ok = await ensureDbOpen();
+      if (!ok) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available." }],
+          details: { operation: "gsd_graph", error: "db_unavailable" },
+          isError: true,
+        };
+      }
+      return executeGsdGraph(params as Parameters<typeof executeGsdGraph>[0]);
+    },
+  });
+}

package/src/resources/extensions/gsd/bootstrap/query-tools.ts

@@ -4,6 +4,7 @@ import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { ensureDbOpen } from "./dynamic-tools.js";
 import { executeMilestoneStatus } from "../tools/workflow-tool-executors.js";
+import { checkpointDatabase } from "../gsd-db.js";
 
 export function registerQueryTools(pi: ExtensionAPI): void {
   pi.registerTool({
@@ -31,4 +32,34 @@ export function registerQueryTools(pi: ExtensionAPI): void {
       return executeMilestoneStatus(params);
     },
   });
+
+  pi.registerTool({
+    name: "gsd_checkpoint_db",
+    label: "Checkpoint GSD Database",
+    description:
+      "Flush the SQLite WAL (Write-Ahead Log) into the base gsd.db file. " +
+      "Call this before `git add .gsd/gsd.db` to ensure the committed database " +
+      "contains current milestone/slice/task state rather than stale pre-session content. " +
+      "Safe to call at any time while GSD is running.",
+    promptSnippet: "Flush WAL into gsd.db so git add stages current state",
+    promptGuidelines: [
+      "Call gsd_checkpoint_db immediately before staging .gsd/gsd.db with git add.",
+      "Do not use sqlite3 or shell commands to checkpoint — they are blocked. Use this tool instead.",
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      const dbAvailable = await ensureDbOpen();
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text", text: "Error: GSD database is not available. Cannot checkpoint." }],
+          details: { operation: "checkpoint_db", error: "db_unavailable" },
+        };
+      }
+      checkpointDatabase();
+      return {
+        content: [{ type: "text", text: "WAL checkpoint complete. gsd.db is now up to date and safe to stage with git add." }],
+        details: { operation: "checkpoint_db", status: "ok" },
+      };
+    },
+  });
 }

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -9,6 +9,7 @@ import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
+import { registerMemoryTools } from "./memory-tools.js";
 import { registerQueryTools } from "./query-tools.js";
 import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
@@ -85,6 +86,7 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
     ["db-tools", () => registerDbTools(pi)],
     ["journal-tools", () => registerJournalTools(pi)],
     ["query-tools", () => registerQueryTools(pi)],
+    ["memory-tools", () => registerMemoryTools(pi)],
     ["shortcuts", () => registerShortcuts(pi)],
     ["hooks", () => registerHooks(pi, ecosystemHandlers)],
     ["ecosystem", () => {

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -18,6 +18,7 @@ import { loadToolApiKeys } from "../commands-config.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
 import { deriveState } from "../state.js";
 import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto.js";
+import { hideFooter } from "../auto-dashboard.js";
 import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js";
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { saveActivityLog } from "../activity-log.js";
@@ -88,6 +89,9 @@ export function registerHooks(
       } catch { /* non-fatal */ }
     }
     loadToolApiKeys();
+    if (isAutoActive()) {
+      ctx.ui.setFooter(hideFooter);
+    }
   });
 
   pi.on("session_switch", async (_event, ctx) => {
@@ -108,6 +112,9 @@ export function registerHooks(
       prepareWorkflowMcpForProject(ctx, process.cwd());
     }
     loadToolApiKeys();
+    if (isAutoActive()) {
+      ctx.ui.setFooter(hideFooter);
+    }
   });
 
   pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
@@ -325,6 +332,7 @@ export function registerHooks(
   // ── Safety harness: evidence collection + destructive command warnings ──
   pi.on("tool_call", async (event, ctx) => {
     if (!isAutoActive()) return;
+    markToolStart(event.toolCallId, event.toolName);
     safetyRecordToolCall(event.toolCallId, event.toolName, event.input as Record<string, unknown>);
 
     // Destructive command classification (warn only, never block)
@@ -343,6 +351,20 @@ export function registerHooks(
   });
 
   pi.on("tool_result", async (event) => {
+    if (isAutoActive() && typeof event.toolCallId === "string") {
+      markToolEnd(event.toolCallId);
+    }
+    if (isAutoActive() && event.isError && event.toolName.startsWith("gsd_")) {
+      const resultPayload = ("result" in event ? event.result : undefined) as any;
+      const errorText = typeof resultPayload === "string"
+        ? resultPayload
+        : (typeof resultPayload?.content?.[0]?.text === "string"
+            ? resultPayload.content[0].text
+            : (typeof (event as any).content === "string"
+                ? (event as any).content
+                : String(resultPayload ?? "")));
+      recordToolInvocationError(event.toolName, errorText);
+    }
     if (event.toolName !== "ask_user_questions") return;
     const milestoneId = getDiscussionMilestoneId(process.cwd());
     const queueActive = isQueuePhaseActive();

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -113,10 +113,26 @@ export async function buildBeforeAgentStartResult(
 
   let memoryBlock = "";
   try {
-    const { formatMemoriesForPrompt, getActiveMemoriesRanked } = await import("../memory-store.js");
-    const memories = getActiveMemoriesRanked(30);
-    if (memories.length > 0) {
-      const formatted = formatMemoriesForPrompt(memories, 2000);
+    const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
+
+    // Always-on "critical" set — small, stable memories that belong in every
+    // turn (gotchas, environment, conventions). Ranked by the existing score.
+    const CRITICAL_CATEGORIES = new Set(["gotcha", "environment", "convention"]);
+    const allRanked = getActiveMemoriesRanked(60);
+    const critical = allRanked.filter((m) => CRITICAL_CATEGORIES.has(m.category)).slice(0, 5);
+    const criticalIds = new Set(critical.map((m) => m.id));
+
+    // Prompt-relevance set — hybrid FTS5 + (future) semantic retrieval.
+    let relevant: typeof allRanked = [];
+    const userPrompt = (event.prompt ?? "").trim();
+    if (userPrompt) {
+      const hits = queryMemoriesRanked({ query: userPrompt, k: 10 });
+      relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
+    }
+
+    const merged = [...critical, ...relevant];
+    if (merged.length > 0) {
+      const formatted = formatMemoriesForPrompt(merged, 2000);
       if (formatted) {
         memoryBlock = `\n\n${formatted}`;
       }

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|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|ship|do|session-report|backlog|pr-branch|add-tests|language";
+  "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|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -44,7 +44,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { 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" },
+  { cmd: "config", desc: "(deprecated) Set tool API keys — use /gsd keys instead" },
   { cmd: "keys", desc: "API key manager — list, add, remove, test, rotate, doctor" },
   { cmd: "hooks", desc: "Show configured post-unit and pre-dispatch hooks" },
   { cmd: "run-hook", desc: "Manually trigger a specific hook" },
@@ -52,9 +52,11 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "notifications", desc: "View, filter, and clear persistent notification history" },
   { cmd: "doctor", desc: "Runtime health checks with auto-fix" },
   { cmd: "logs", desc: "Browse activity logs, debug logs, and metrics" },
+  { cmd: "debug", desc: "Create and inspect persistent /gsd debug sessions" },
   { cmd: "forensics", desc: "Examine execution logs" },
   { cmd: "init", desc: "Project init wizard — detect, configure, bootstrap .gsd/" },
-  { cmd: "setup", desc: "Global setup status and configuration" },
+  { cmd: "setup", desc: "Configuration hub: status + sub-routes (llm, model, search, remote, keys, prefs, onboarding)" },
+  { cmd: "onboarding", desc: "Re-run the setup wizard  [--resume|--reset|--step <name>]" },
   { cmd: "migrate", desc: "Migrate a v1 .planning directory to .gsd format" },
   { cmd: "remote", desc: "Control remote auto-mode" },
   { cmd: "steer", desc: "Hard-steer plan documents during execution" },
@@ -72,7 +74,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "fast", desc: "Toggle OpenAI service tier (on/off/flex/status)" },
   { cmd: "mcp", desc: "MCP server status, connectivity, and local config bootstrap (status, check, init)" },
   { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
-  { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
+  { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, info, install, uninstall, validate, pause, resume) or run <name> directly" },
   { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
   { cmd: "ship", desc: "Create PR from milestone artifacts and open for review" },
   { cmd: "do", desc: "Route freeform text to the right GSD command" },
@@ -80,6 +82,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "backlog", desc: "Manage backlog items (add, promote, remove, list)" },
   { cmd: "pr-branch", desc: "Create clean PR branch filtering .gsd/ commits" },
   { cmd: "add-tests", desc: "Generate tests for completed slices" },
+  { cmd: "scan", desc: "Rapid codebase assessment — lightweight alternative to full map (--focus tech|arch|quality|concerns|tech+arch)" },
   { cmd: "language", desc: "Set or clear the global response language (e.g. /gsd language Chinese)" },
 ];
 
@@ -113,11 +116,18 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "watch", desc: "Live TUI dashboard monitoring all workers" },
   ],
   setup: [
-    { cmd: "llm", desc: "Configure LLM provider settings" },
+    { cmd: "llm", desc: "Configure LLM provider & auth" },
+    { cmd: "model", desc: "Pick default model for the active provider" },
     { cmd: "search", desc: "Configure web search provider" },
-    { cmd: "remote", desc: "Configure remote integrations" },
-    { cmd: "keys", desc: "Manage API keys" },
-    { cmd: "prefs", desc: "Configure global preferences" },
+    { cmd: "remote", desc: "Configure remote integrations (Discord/Slack/Telegram)" },
+    { cmd: "keys", desc: "Manage API keys (alias for /gsd keys)" },
+    { cmd: "prefs", desc: "Global preferences wizard (alias for /gsd prefs)" },
+    { cmd: "onboarding", desc: "Run the full onboarding wizard (alias for /gsd onboarding)" },
+  ],
+  onboarding: [
+    { cmd: "--resume", desc: "Resume from the last completed step" },
+    { cmd: "--reset", desc: "Reset onboarding state and start over (does not clear API keys)" },
+    { cmd: "--step", desc: "Run a single step: llm|model|search|remote|tool-keys|prefs|skills|doctor|project" },
   ],
   notifications: [
     { cmd: "clear", desc: "Clear all notifications" },
@@ -129,6 +139,12 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "tail", desc: "Show last N activity log summaries" },
     { cmd: "clear", desc: "Remove old activity and debug logs" },
   ],
+  debug: [
+    { cmd: "list", desc: "List persisted debug sessions" },
+    { cmd: "status", desc: "Show status for one debug session slug" },
+    { cmd: "continue", desc: "Resume an existing debug session slug" },
+    { cmd: "--diagnose", desc: "Inspect malformed artifacts and session health" },
+  ],
   keys: [
     { cmd: "list", desc: "Show key status dashboard" },
     { cmd: "add", desc: "Add a key for a provider" },
@@ -235,8 +251,11 @@ const NESTED_COMPLETIONS: CompletionMap = {
   ],
   workflow: [
     { cmd: "new", desc: "Create a new workflow definition (via skill)" },
-    { cmd: "run", desc: "Create a run and start auto-mode" },
+    { cmd: "run", desc: "Create a YAML run and start auto-mode" },
     { cmd: "list", desc: "List workflow runs" },
+    { cmd: "info", desc: "Show plugin details (source, mode, phases)" },
+    { cmd: "install", desc: "Install a plugin from a URL / gist: / gh:" },
+    { cmd: "uninstall", desc: "Remove an installed plugin" },
     { cmd: "validate", desc: "Validate a workflow definition YAML" },
     { cmd: "pause", desc: "Pause custom workflow auto-mode" },
     { cmd: "resume", desc: "Resume paused custom workflow auto-mode" },
@@ -270,6 +289,13 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "--dry-run", desc: "Preview what would be filtered" },
     { cmd: "--name", desc: "Custom branch name" },
   ],
+  scan: [
+    { cmd: "--focus tech", desc: "Technology stack and external integrations" },
+    { cmd: "--focus arch", desc: "Architecture patterns and directory structure" },
+    { cmd: "--focus quality", desc: "Coding conventions and testing patterns" },
+    { cmd: "--focus concerns", desc: "Technical debt and risk areas" },
+    { cmd: "--focus tech+arch", desc: "Tech + Architecture (default)" },
+  ],
   language: [
     { cmd: "off",   desc: "Clear the language preference (revert to default)" },
     { cmd: "clear", desc: "Alias for off — clear the language preference" },
@@ -399,6 +425,45 @@ export function getGsdArgumentCompletions(prefix: string) {
     return [];
   }
 
+  // Completion for `/gsd workflow info <name>` — list all discoverable plugins (project + global).
+  if (command === "workflow" && subcommand === "info" && parts.length <= 3) {
+    const results: GsdCommandDefinition[] = [];
+    const seen = new Set<string>();
+    const scanDir = (dir: string, source: string) => {
+      if (!existsSync(dir)) return;
+      try {
+        for (const f of readdirSync(dir)) {
+          if (!/\.(ya?ml|md)$/i.test(f)) continue;
+          const name = f.replace(/\.(ya?ml|md)$/i, "");
+          if (!name.startsWith(third)) continue;
+          if (seen.has(name)) continue;
+          seen.add(name);
+          results.push({ cmd: name, desc: `Workflow plugin (${source})` });
+        }
+      } catch { /* ignore */ }
+    };
+    try {
+      const base = resolveProjectRoot(process.cwd());
+      scanDir(join(base, ".gsd", "workflows"), "project");
+      scanDir(join(base, ".gsd", "workflow-defs"), "project-legacy");
+      scanDir(join(gsdHome, "workflows"), "global");
+    } catch { /* ignore */ }
+    // Also include bundled template names.
+    try {
+      const registry = loadRegistry();
+      for (const id of Object.keys(registry.templates)) {
+        if (seen.has(id) || !id.startsWith(third)) continue;
+        seen.add(id);
+        results.push({ cmd: id, desc: "Workflow plugin (bundled)" });
+      }
+    } catch { /* ignore */ }
+    return results.map((r) => ({
+      value: `workflow info ${r.cmd}`,
+      label: r.cmd,
+      description: r.desc,
+    }));
+  }
+
   const nested = NESTED_COMPLETIONS[command];
   if (nested && parts.length <= 2) {
     return filterOptions(subcommand, nested, command);

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

@@ -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",
   );
 }
@@ -423,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;