gsd-pi 2.75.0 → 2.76.0-dev.4100bd590

package/dist/resources/extensions/gsd/bootstrap/memory-tools.js

@@ -0,0 +1,131 @@
+// 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 { ensureDbOpen } from "./dynamic-tools.js";
+import { executeGsdGraph, executeMemoryCapture, executeMemoryQuery, } from "../tools/memory-tools.js";
+export function registerMemoryTools(pi) {
+    // ─── 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)" })),
+            structuredFields: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+                description: "Optional structured payload preserved alongside content (ADR-013). Use for decisions to retain scope/decision/choice/rationale/made_by/revisable. Omit for plain captures.",
+            })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const ok = await ensureDbOpen();
+            if (!ok) {
+                return {
+                    content: [{ type: "text", text: "Error: GSD database is not available. Cannot capture memory." }],
+                    details: { operation: "memory_capture", error: "db_unavailable" },
+                    isError: true,
+                };
+            }
+            return executeMemoryCapture(params);
+        },
+    });
+    // ─── 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", text: "Error: GSD database is not available. Cannot query memory." }],
+                    details: { operation: "memory_query", error: "db_unavailable" },
+                    isError: true,
+                };
+            }
+            return executeMemoryQuery(params);
+        },
+    });
+    // ─── 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", text: "Error: GSD database is not available." }],
+                    details: { operation: "gsd_graph", error: "db_unavailable" },
+                    isError: true,
+                };
+            }
+            return executeGsdGraph(params);
+        },
+    });
+}

package/dist/resources/extensions/gsd/bootstrap/query-tools.js

@@ -2,6 +2,7 @@
 import { Type } from "@sinclair/typebox";
 import { ensureDbOpen } from "./dynamic-tools.js";
 import { executeMilestoneStatus } from "../tools/workflow-tool-executors.js";
+import { checkpointDatabase } from "../gsd-db.js";
 export function registerQueryTools(pi) {
     pi.registerTool({
         name: "gsd_milestone_status",
@@ -27,4 +28,32 @@ export function registerQueryTools(pi) {
             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/dist/resources/extensions/gsd/bootstrap/register-extension.js

@@ -5,6 +5,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";
@@ -57,6 +58,16 @@ export function registerGsdExtension(pi) {
     // so we intentionally skip it here to avoid double-registration.
     registerWorktreeCommand(pi);
     registerExitCommand(pi);
+    // Wire the Layer 2 event emitter bridge so deeply-nested GSD code can emit
+    // extension events (git lifecycle, verify, budget, milestone, unit) without
+    // threading `pi` through every call site.
+    import("../hook-emitter.js")
+        .then(({ setHookEmitter }) => setHookEmitter(pi))
+        .catch((err) => {
+        // Non-fatal — emitters simply become no-ops if this import fails, but
+        // surface the failure so silent bootstrap breakage is debuggable.
+        process.stderr.write(`[gsd] Failed to bootstrap hook-emitter bridge: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    });
     installEpipeGuard();
     // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
     // GSD-owned `before_agent_start` dispatch step (#3338).
@@ -74,6 +85,7 @@ export function registerGsdExtension(pi) {
         ["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/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -13,6 +13,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";
@@ -77,6 +78,9 @@ export function registerHooks(pi, ecosystemHandlers) {
             catch { /* non-fatal */ }
         }
         loadToolApiKeys();
+        if (isAutoActive()) {
+            ctx.ui.setFooter(hideFooter);
+        }
     });
     pi.on("session_switch", async (_event, ctx) => {
         initNotificationStore(process.cwd());
@@ -96,6 +100,9 @@ export function registerHooks(pi, ecosystemHandlers) {
             prepareWorkflowMcpForProject(ctx, process.cwd());
         }
         loadToolApiKeys();
+        if (isAutoActive()) {
+            ctx.ui.setFooter(hideFooter);
+        }
     });
     pi.on("before_agent_start", async (event, ctx) => {
         // Wait for ecosystem loader to finish (no-op after first turn).
@@ -292,6 +299,7 @@ export function registerHooks(pi, ecosystemHandlers) {
     pi.on("tool_call", async (event, ctx) => {
         if (!isAutoActive())
             return;
+        markToolStart(event.toolCallId, event.toolName);
         safetyRecordToolCall(event.toolCallId, event.toolName, event.input);
         // Destructive command classification (warn only, never block)
         if (isToolCallEventType("bash", event)) {
@@ -305,6 +313,20 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
     });
     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);
+            const errorText = typeof resultPayload === "string"
+                ? resultPayload
+                : (typeof resultPayload?.content?.[0]?.text === "string"
+                    ? resultPayload.content[0].text
+                    : (typeof event.content === "string"
+                        ? event.content
+                        : String(resultPayload ?? "")));
+            recordToolInvocationError(event.toolName, errorText);
+        }
         if (event.toolName !== "ask_user_questions")
             return;
         const milestoneId = getDiscussionMilestoneId(process.cwd());

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -24,10 +24,30 @@ const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
  * hardcoding absolute paths in the system prompt template. Only skills
  * that actually exist on disk are included in the table. (#3575)
  */
-const BUNDLED_SKILL_TRIGGERS = [
+export const BUNDLED_SKILL_TRIGGERS = [
     { trigger: "Frontend UI - web components, pages, landing pages, dashboards, React/HTML/CSS, styling", skill: "frontend-design" },
     { trigger: "macOS or iOS apps - SwiftUI, Xcode, App Store", skill: "swiftui" },
     { trigger: "Debugging - complex bugs, failing tests, root-cause investigation after standard approaches fail", skill: "debug-like-expert" },
+    { trigger: "Code review - security, performance, bugs, quality review of staged/unstaged diffs or PRs", skill: "review" },
+    { trigger: "Test generation or execution - auto-detect framework, generate tests, run suite, analyze failures", skill: "test" },
+    { trigger: "Linting/formatting - run the detected linter/formatter with auto-fix, report remaining issues", skill: "lint" },
+    { trigger: "Polishing UI details - animations, hover states, typography, borders, micro-interactions, optical alignment", skill: "make-interfaces-feel-better" },
+    { trigger: "Accessibility audit - WCAG, screen reader, keyboard navigation, a11y review", skill: "accessibility" },
+    { trigger: "Planning interviews - stress-test a plan, grill the user, resolve decision trees one branch at a time", skill: "grill-me" },
+    { trigger: "Interface design - produce 3+ radically different designs for a module/API, compare in prose, synthesize", skill: "design-an-interface" },
+    { trigger: "TDD - red-green-refactor vertical slices, never refactor while red, tests survive refactors", skill: "tdd" },
+    { trigger: "Draft a milestone brief (M###-CONTEXT.md) or PRD from current conversation context", skill: "write-milestone-brief" },
+    { trigger: "Break a plan into vertical-slice roadmap slices (M###-ROADMAP.md) or GitHub issues with dependency ordering", skill: "decompose-into-slices" },
+    { trigger: "Package spike findings into a reusable project-local skill at .claude/skills/", skill: "spike-wrap-up" },
+    { trigger: "Block completion claims until verification evidence has been produced in this message", skill: "verify-before-complete" },
+    { trigger: "Create a Model Context Protocol (MCP) server — tool design, error handling, Inspector testing, evals", skill: "create-mcp-server" },
+    { trigger: "Write documentation, proposals, specs, RFCs, or READMEs for a fresh reader", skill: "write-docs" },
+    { trigger: "Post-mortem a failed GSD auto-mode run using .gsd/activity, .gsd/journal, and .gsd/metrics.json", skill: "forensics" },
+    { trigger: "Prepare a clean cross-session handoff — continue.md + summary updates (pause/resume work)", skill: "handoff" },
+    { trigger: "Security review with STRIDE threat modeling and exploit-scenario reporting", skill: "security-review" },
+    { trigger: "HTTP/REST/GraphQL API design — verbs, status codes, pagination, errors, idempotency, versioning", skill: "api-design" },
+    { trigger: "Dependency upgrades — risk-batched, verified between batches, one major per commit", skill: "dependency-upgrade" },
+    { trigger: "Agent-first observability — structured logs, persisted failure state, health surfaces, explicit failure modes", skill: "observability" },
 ];
 function buildBundledSkillsTable() {
     const cwd = process.cwd();
@@ -87,20 +107,20 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     if (globalSizeKb > 4) {
         ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
     }
-    let memoryBlock = "";
+    // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
+    // and best-effort — first run absorbs the existing decisions table into
+    // the memory store; subsequent runs are a single sentinel SELECT.
     try {
-        const { formatMemoriesForPrompt, getActiveMemoriesRanked } = await import("../memory-store.js");
-        const memories = getActiveMemoriesRanked(30);
-        if (memories.length > 0) {
-            const formatted = formatMemoriesForPrompt(memories, 2000);
-            if (formatted) {
-                memoryBlock = `\n\n${formatted}`;
-            }
+        const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
+        const written = backfillDecisionsToMemories();
+        if (written > 0) {
+            ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store (ADR-013).`, "info");
         }
     }
     catch (e) {
-        logWarning("bootstrap", `memory block fetch failed: ${e.message}`);
+        logWarning("bootstrap", `decisions backfill failed: ${e.message}`);
     }
+    const memoryBlock = await loadMemoryBlock(event.prompt ?? "");
     let newSkillsBlock = "";
     if (hasSkillSnapshot()) {
         const newSkills = detectNewSkills();
@@ -170,6 +190,60 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         ...(contextMessage ? { message: contextMessage } : {}),
     };
 }
+/**
+ * ADR-013 step 4 — auto-injection parity for the memories table.
+ *
+ * Mirrors loadKnowledgeBlock by producing a labeled, deterministic block
+ * combining two memory sets:
+ *
+ * 1. Always-on "critical" set — top-ranked active memories in categories
+ *    that future GSD turns generally want without asking. After ADR-013
+ *    expands this to include "architecture", these memories serve as the
+ *    auto-injected replacement for inlineDecisionsFromDb when the cutover
+ *    in step 6 lands.
+ * 2. Prompt-relevance set — FTS5/semantic hits against the current user
+ *    prompt, deduplicated against the critical set.
+ *
+ * Both sets are ranked, merged, and rendered via formatMemoriesForPrompt
+ * with a token-budget cap. Failures degrade gracefully — the function never
+ * throws and returns "" so the system prompt construction continues.
+ */
+export async function loadMemoryBlock(userPrompt) {
+    try {
+        const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
+        // Categories that belong in every turn. Pre-ADR-013 this was just
+        // {gotcha, environment, convention}. ADR-013 adds "architecture" so
+        // decision-equivalent memories survive the inlineDecisionsFromDb cutover
+        // in step 6.
+        const CRITICAL_CATEGORIES = new Set(["gotcha", "environment", "convention", "architecture"]);
+        const CRITICAL_CAP = 8;
+        const QUERY_K = 10;
+        // ~1 token ≈ 4 chars. 4000 chars ≈ 1000 tokens — comfortably under the
+        // KNOWLEDGE.md 4KB warning threshold and roughly twice the pre-ADR-013
+        // budget so the absorbed DECISIONS surface fits.
+        const CHAR_BUDGET = 4000;
+        const allRanked = getActiveMemoriesRanked(80);
+        const critical = allRanked.filter((m) => CRITICAL_CATEGORIES.has(m.category)).slice(0, CRITICAL_CAP);
+        const criticalIds = new Set(critical.map((m) => m.id));
+        let relevant = [];
+        const trimmed = userPrompt.trim();
+        if (trimmed) {
+            const hits = queryMemoriesRanked({ query: trimmed, k: QUERY_K });
+            relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
+        }
+        const merged = [...critical, ...relevant];
+        if (merged.length === 0)
+            return "";
+        const formatted = formatMemoriesForPrompt(merged, CHAR_BUDGET);
+        if (!formatted)
+            return "";
+        return `\n\n[MEMORY — Critical and prompt-relevant memories from the GSD memory store]\n\n${formatted}`;
+    }
+    catch (e) {
+        logWarning("bootstrap", `memory block fetch failed: ${e.message}`);
+        return "";
+    }
+}
 export function loadKnowledgeBlock(gsdHomeDir, cwd) {
     // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
     let globalKnowledge = "";

package/dist/resources/extensions/gsd/commands/catalog.js

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
 import { resolveProjectRoot } from "../worktree.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-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";
+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|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 = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -32,7 +32,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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" },
@@ -40,9 +40,11 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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" },
@@ -60,7 +62,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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" },
@@ -68,6 +70,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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)" },
 ];
 const NESTED_COMPLETIONS = {
@@ -100,11 +103,18 @@ const NESTED_COMPLETIONS = {
         { 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" },
@@ -116,6 +126,12 @@ const NESTED_COMPLETIONS = {
         { 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" },
@@ -222,8 +238,11 @@ const NESTED_COMPLETIONS = {
     ],
     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" },
@@ -257,6 +276,13 @@ const NESTED_COMPLETIONS = {
         { 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" },
@@ -377,6 +403,52 @@ export function getGsdArgumentCompletions(prefix) {
         }
         return [];
     }
+    // Completion for `/gsd workflow info <name>` — list all discoverable plugins (project + global).
+    if (command === "workflow" && subcommand === "info" && parts.length <= 3) {
+        const results = [];
+        const seen = new Set();
+        const scanDir = (dir, source) => {
+            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);