@opengsd/gsd-core 1.7.0-rc.3 → 1.7.0-rc.4

package/gsd-core/workflows/help/modes/brief.md

@@ -7,7 +7,8 @@ One-liner refresher for returning users. Output ONLY the `<reference>` content b
 
 ```text
 /gsd:new-project           Initialize a project (greenfield)
-/gsd:map-codebase          Map an existing codebase (brownfield)
+/gsd:onboard               Onboard an existing codebase (brownfield)
+/gsd:map-codebase          Refresh/map codebase intelligence
 /gsd:plan-phase <N>        Create a phase plan
 /gsd:execute-phase <N>     Execute a phase
 /gsd:progress              Where am I, what's next

package/gsd-core/workflows/help/modes/default.md

@@ -11,11 +11,12 @@ Plan-driven development for solo agentic work with Claude Code. GSD Core turns a
 
 ```text
 /gsd:new-project        # Greenfield: questioning → research → requirements → roadmap
+/gsd:onboard            # Existing codebase: map → ingest docs → initialize planning
 /gsd:plan-phase 1       # Create a detailed plan for phase 1
 /gsd:execute-phase 1    # Execute all plans in the phase
 ```
 
-Existing codebase? Run `/gsd:map-codebase` first to ground GSD in your code.
+Existing codebase? Run `/gsd:onboard` to map the repo, ingest existing docs, and initialize planning safely.
 
 ## Common commands
 

package/gsd-core/workflows/help/modes/full.md

@@ -62,6 +62,16 @@ Creates all `.planning/` artifacts:
 
 Usage: `/gsd:new-project`
 
+**`/gsd:onboard [--fast] [--text]`**
+Guide first-time onboarding for an existing codebase.
+
+- Detects brownfield code, existing planning docs, and partial `.planning/` state
+- Routes through `/gsd:map-codebase`, `/gsd:ingest-docs`, and `/gsd:new-project` in the safe order
+- Creates `.planning/onboarding/SUMMARY.md` after project setup
+- Idempotent: confirms existing artifacts and does not overwrite planning silently
+
+Usage: `/gsd:onboard`
+
 **`/gsd:map-codebase [--fast] [--focus <area>] [--query <term>]`**
 Map an existing codebase for brownfield projects.
 
@@ -72,7 +82,7 @@ Map an existing codebase for brownfield projects.
 - Analyzes codebase with parallel Explore agents
 - Creates `.planning/codebase/` with 7 focused documents
 - Covers stack, architecture, structure, conventions, testing, integrations, concerns
-- Use before `/gsd:new-project` on existing codebases
+- Usually reached through `/gsd:onboard` for first-time existing-codebase setup; run directly to refresh or focus a map
 
 Usage: `/gsd:map-codebase`
 

package/gsd-core/workflows/help/modes/topic.md

@@ -9,7 +9,7 @@ Emit a section from the full reference for the topic in `$ARGUMENTS`. Read `work
 |---|---|
 | `next`, `smart-entry` | `### Smart Entry` |
 | `workflow`, `core`, `core-workflow` | `## Core Workflow` (entire section through end of `### Quick Mode`) |
-| `init`, `new-project` | `### Project Initialization` |
+| `init`, `new-project`, `onboard`, `onboarding`, `brownfield` | `### Project Initialization` |
 | `map`, `map-codebase` | The `/gsd:map-codebase` block under `### Project Initialization` |
 | `discuss`, `discuss-phase` | The `/gsd:discuss-phase` block under `### Phase Planning` |
 | `plan`, `planning`, `plan-phase` | `### Phase Planning` |

package/gsd-core/workflows/onboard.md

@@ -0,0 +1,277 @@
+# /gsd:onboard Workflow
+
+One-command onboarding for an existing or unknown repo. This workflow is a thin
+renderer around `init onboard`; deterministic routing lives in the CLI projection.
+
+@~/.claude/gsd-core/references/gsd-run-resolver.md
+
+## 1. Render the Onboarding Projection
+
+Parse `$ARGUMENTS`:
+- `--fast` passes `--fast` to `init onboard`. Fast mode accepts the fast map for lightweight onboarding only; `next_action` still decides whether complete map work is required before project setup.
+- `--text` forces text-mode choices for runtimes without `AskUserQuestion`.
+
+Run the standard `gsd_run` resolver from the reference above, then run the projection from the runtime root:
+
+```bash
+# If --fast was parsed from $ARGUMENTS:
+INIT=$(gsd_run --cwd "$_GSD_RUNTIME_ROOT" init onboard --fast --raw)
+# Otherwise:
+INIT=$(gsd_run --cwd "$_GSD_RUNTIME_ROOT" init onboard --raw)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON fields from `INIT`:
+
+- `next_action.kind`, `next_action.command`, `next_action.reason`, `next_action.missing`, `next_action.summary_path`
+- `handoff_commands.ingest_docs`, `handoff_commands.manager`, `handoff_commands.new_project`, `handoff_commands.onboard`
+- `map_readiness`, `codebase_map_summary_status`, `codebase_map_final_status`
+- `planning_exists`, `project_exists`, `requirements_exists`, `roadmap_exists`, `state_exists`
+- `is_brownfield`, `fast_mode`, `has_codebase_map`, `has_fast_codebase_map`
+- `missing_codebase_map_files`, `missing_fast_codebase_map_files`
+- `has_docs_candidates`, `doc_candidate_count`, `onboarding_summary_exists`
+- `commit_docs`, `text_mode`, `has_git`, `git_worktree_root`, `in_nested_subdir`
+
+Set:
+- `TEXT_MODE=true` if `--text` is present or `text_mode` is true. When `TEXT_MODE` is active, replace every `AskUserQuestion` call below with a plain-text numbered list and ask the user to type their choice number — required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+- `ONBOARDING_ROOT={git_worktree_root || _GSD_RUNTIME_ROOT}`.
+
+If `has_git` and `in_nested_subdir` are true, warn that onboarding artifacts belong to the outer worktree at `git_worktree_root`. Do not run `git init`.
+
+## 2. Execute `next_action`
+
+### `map-codebase`
+
+If `next_action.kind == "map-codebase"`:
+
+- If `TEXT_MODE=true`, print:
+
+```text
+{next_action.reason}
+Missing map files: {fast_mode ? missing_fast_codebase_map_files : missing_codebase_map_files}
+
+1. Map codebase first — run {next_action.command} from worktree root {ONBOARDING_ROOT} (Recommended)
+2. Skip mapping — continue with weaker onboarding context
+
+Enter number:
+```
+
+- Otherwise use AskUserQuestion:
+  - header: "Codebase"
+  - question: "{next_action.reason} Map it first?"
+  - options:
+    - "Map codebase first" — Run `{next_action.command}` from worktree root `{ONBOARDING_ROOT}` (Recommended)
+    - "Skip mapping" — Continue with weaker onboarding context
+
+If the user chooses mapping, do not nest the interactive workflow. Print:
+
+```text
+Run from worktree root {ONBOARDING_ROOT}:
+
+{next_action.command}
+
+Then rerun {handoff_commands.onboard} from the same worktree root.
+```
+
+Exit. If the user skips mapping:
+
+- If `(project_exists || requirements_exists || roadmap_exists || state_exists) && (!project_exists || !requirements_exists || !roadmap_exists || !state_exists)`, route the skip to the partial planning guard instead:
+
+```text
+Skipping codebase mapping may give downstream steps weaker context, but project planning exists and is incomplete.
+
+PROJECT.md: {project_exists ? "present" : "missing"}
+REQUIREMENTS.md: {requirements_exists ? "present" : "missing"}
+ROADMAP.md: {roadmap_exists ? "present" : "missing"}
+STATE.md: {state_exists ? "present" : "missing"}
+
+Run the appropriate lower-level command to fill the missing planning artifact(s), then rerun {handoff_commands.onboard}.
+```
+
+Exit.
+
+- If `has_docs_candidates && !project_exists`, route the skip to docs ingest instead:
+
+```text
+Skipping codebase mapping may give downstream steps weaker context, but existing ADR/PRD/SPEC/RFC documents should still be ingested before {handoff_commands.new_project}.
+
+Run from worktree root {ONBOARDING_ROOT}:
+
+{handoff_commands.ingest_docs}
+
+Then rerun {handoff_commands.onboard} from the same worktree root.
+```
+
+Exit.
+
+- Otherwise print:
+
+```text
+Skipping codebase mapping may give {handoff_commands.new_project} weaker context.
+
+Run from worktree root {ONBOARDING_ROOT}:
+
+{handoff_commands.new_project}
+
+Then rerun {handoff_commands.onboard} from the same worktree root.
+```
+
+Exit.
+
+### `ingest-docs`
+
+If `next_action.kind == "ingest-docs"`:
+
+- If `TEXT_MODE=true`, print:
+
+```text
+{next_action.reason}
+Detected {doc_candidate_count} possible ADR/PRD/SPEC/RFC document(s).
+
+1. Ingest docs first — run {next_action.command} from worktree root {ONBOARDING_ROOT} (Recommended)
+2. Skip docs ingest — continue to {handoff_commands.new_project}
+
+Enter number:
+```
+
+- Otherwise use AskUserQuestion:
+  - header: "Docs"
+  - question: "Detected {doc_candidate_count} possible ADR/PRD/SPEC/RFC document(s). Ingest them first?"
+  - options:
+    - "Ingest docs first" — Run `{next_action.command}` from worktree root `{ONBOARDING_ROOT}` (Recommended)
+    - "Skip docs ingest" — Continue to `{handoff_commands.new_project}`
+
+If the user chooses ingest, print:
+
+```text
+Run from worktree root {ONBOARDING_ROOT}:
+
+{next_action.command}
+
+Then rerun {handoff_commands.onboard} from the same worktree root.
+```
+
+Exit. If the user skips docs ingest, print:
+
+```text
+Skipping docs ingest may omit existing ADR/PRD/SPEC/RFC context from {handoff_commands.new_project}.
+
+Run from worktree root {ONBOARDING_ROOT}:
+
+{handoff_commands.new_project}
+
+Then rerun {handoff_commands.onboard} from the same worktree root.
+```
+
+Exit.
+
+### `complete-map-before-new-project`
+
+If `next_action.kind == "complete-map-before-new-project"`, print:
+
+```text
+{next_action.reason}
+
+Run from worktree root {ONBOARDING_ROOT}:
+
+{next_action.command}
+
+Then rerun {handoff_commands.onboard} from the same worktree root.
+```
+
+Exit.
+
+### `new-project`
+
+If `next_action.kind == "new-project"`, print:
+
+```text
+{next_action.reason}
+
+Run from worktree root {ONBOARDING_ROOT}:
+
+{next_action.command}
+
+Then rerun {handoff_commands.onboard} from the same worktree root.
+```
+
+Exit.
+
+### `partial-planning`
+
+If `next_action.kind == "partial-planning"`, print:
+
+```text
+Project planning exists but is incomplete.
+
+Missing files: {next_action.missing}
+REQUIREMENTS.md: {requirements_exists ? "present" : "missing"}
+ROADMAP.md: {roadmap_exists ? "present" : "missing"}
+STATE.md: {state_exists ? "present" : "missing"}
+
+Run the appropriate lower-level command to fill the missing planning artifact(s), then rerun {handoff_commands.onboard}.
+```
+
+Exit.
+
+### `ready`
+
+If `next_action.kind == "ready"`, print the final status section and exit.
+
+### `write-summary`
+
+If `next_action.kind == "write-summary"`, continue to summary creation.
+
+## 3. Create Onboarding Summary
+
+Create `{ONBOARDING_ROOT}/{next_action.summary_path}`. Do not overwrite an existing summary; the projection should only route here when the summary is missing.
+
+Summary template:
+
+```markdown
+# Onboarding Summary
+
+## Project State
+- PROJECT.md: {project_exists ? "present" : "missing"}
+- REQUIREMENTS.md: {requirements_exists ? "present" : "missing"}
+- ROADMAP.md: {roadmap_exists ? "present" : "missing"}
+- STATE.md: {state_exists ? "present" : "missing"}
+
+## Codebase Context
+- Brownfield repo: {is_brownfield ? "yes" : "no"}
+- Map readiness: {map_readiness}
+- Codebase map: {codebase_map_summary_status}
+- Fast map available: {has_fast_codebase_map ? "yes" : "no"}
+
+## Docs Context
+- Existing ADR/PRD/SPEC/RFC candidates: {has_docs_candidates ? doc_candidate_count : 0}
+
+## Recommended Next Step
+- {handoff_commands.manager}
+```
+
+If `commit_docs` is true, commit only the summary path from the onboarding root:
+
+```bash
+gsd_run --cwd "$ONBOARDING_ROOT" query commit "docs: create onboarding summary" --files .planning/onboarding/SUMMARY.md
+```
+
+Continue to final status.
+
+## 4. Final Status
+
+Print:
+
+```text
+Onboarding status:
+- PROJECT.md: {project_exists ? "present" : "missing"}
+- REQUIREMENTS.md: {requirements_exists ? "present" : "missing"}
+- ROADMAP.md: {roadmap_exists ? "present" : "missing"}
+- STATE.md: {state_exists ? "present" : "missing"}
+- Codebase map: {codebase_map_final_status}
+- Onboarding summary: present
+
+Next recommended command: {handoff_commands.manager}
+```
+
+Do not run implementation execution or shipping from onboarding.

package/gsd-core/workflows/quick.md

@@ -671,6 +671,26 @@ fi
 
 **Step 6: Spawn executor**
 
+Auto-degrade to sequential if HEAD has diverged from the worktree fork base (#1941, mirrors
+execute-phase's #683/#1369 guard). Claude Code's `isolation="worktree"` forks new worktrees from
+`origin/HEAD`, not the live local HEAD. If a prior quick task in this session (or the Step 5.6
+pre-dispatch plan commit above) advanced local HEAD without an intervening `git push`,
+`origin/HEAD` stays pinned to a stale ancestor and the executor's `worktree_branch_check` guard
+halts with a base-mismatch fatal — potentially many commits behind, not just one. Run this check
+immediately before capturing `EXPECTED_BASE` so it reflects the most current local state.
+
+```bash
+if [ "$RUNTIME" = "claude" ] && [ "${USE_WORKTREES:-true}" != "false" ]; then
+  _QUICK_SHOULD_DEGRADE=$(gsd_run query worktree.base-check --pick shouldDegrade 2>/dev/null || true)
+  if [ "$_QUICK_SHOULD_DEGRADE" = "true" ]; then
+    _QUICK_DEGRADE_MSG=$(gsd_run query worktree.base-check --pick message 2>/dev/null || true)
+    [ -n "$_QUICK_DEGRADE_MSG" ] && printf '%s\n' "$_QUICK_DEGRADE_MSG" >&2
+    echo "⚠ [#1941] Worktree fork base diverged from orchestrator HEAD — auto-degrading to sequential mode for this quick task to avoid a base-mismatch halt." >&2
+    USE_WORKTREES=false
+  fi
+fi
+```
+
 Capture current HEAD before spawning (used for worktree branch check):
 ```bash
 EXPECTED_BASE=$(git rev-parse HEAD)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "main": ".opencode/plugins/gsd-core.js",
   "bin": {

package/scripts/gen-golden-install-parity-zcode.cjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Standalone golden-fixture generator for tests/golden-install-parity.
+ *
+ * This is a BUILD-TIME generation script — NOT a test run. It replicates the
+ * buildParityManifest logic from tests/golden-install-parity.test.cjs and
+ * captures the zcode fixture so the parity test (which the gsd-test gate runs)
+ * has a committed artifact to compare against. The authoritative test gate
+ * remains `gsd-test run`, never a local `node --test`.
+ *
+ * Usage: node scripts/gen-golden-install-parity-zcode.cjs
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const ROOT = path.resolve(__dirname, '..');
+const { walk, runMinimalInstall, RUNTIME_META } = require(path.join(ROOT, 'tests', 'helpers', 'install-shared.cjs'));
+const PKG_VERSION = require(path.join(ROOT, 'package.json')).version;
+const FIXTURE_DIR = path.join(ROOT, 'tests', 'fixtures', 'golden-install-parity');
+
+const VOLATILE_FILES = new Set([
+  'gsd-file-manifest.json',
+  'gsd-install-state.json',
+  '.gsd-source',
+  'gsd-core/CHANGELOG.md',
+]);
+const HOOK_CONFIG_FILES = new Set(['settings.json', 'hooks.json']);
+const EXCLUDED_PREFIXES = ['gsd-core/bin/lib/'];
+
+function buildParityManifest(configDir, root) {
+  const allFiles = walk(configDir);
+  const unsorted = {};
+  for (const full of allFiles) {
+    const rel = path.relative(configDir, full).split(path.sep).join('/');
+    if (VOLATILE_FILES.has(rel)) continue;
+    if (HOOK_CONFIG_FILES.has(path.basename(rel))) continue;
+    if (EXCLUDED_PREFIXES.some((p) => rel.startsWith(p))) continue;
+    const content = fs.readFileSync(full);
+    const normalized = content.toString('utf8').split(root).join('<HOME>').split(PKG_VERSION).join('<VERSION>');
+    const hash = crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+    unsorted[rel] = hash;
+  }
+  const sorted = {};
+  for (const key of Object.keys(unsorted).sort()) sorted[key] = unsorted[key];
+  return sorted;
+}
+
+function cleanup(root) {
+  try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+
+// Regenerate the fixture for every runtime in RUNTIME_META. Needed when a
+// SHARED gsd-core payload file (e.g. model-catalog.json, capability-registry)
+// changes content — its hash appears in every runtime's manifest, so all
+// fixtures must be recaptured together. Usage:
+//   node scripts/gen-golden-install-parity-zcode.cjs [runtime ...]
+// With no args, regenerates ALL runtimes. With args, only the named runtimes.
+const targets = process.argv.slice(2).length > 0 ? process.argv.slice(2) : Object.keys(RUNTIME_META);
+fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+for (const runtime of targets) {
+  if (!Object.prototype.hasOwnProperty.call(RUNTIME_META, runtime)) {
+    process.stderr.write(`[gen] unknown runtime '${runtime}' (not in RUNTIME_META) — skipping\n`);
+    continue;
+  }
+  const { configDir, root } = runMinimalInstall({ runtime, scope: 'global' });
+  let actual;
+  try {
+    actual = buildParityManifest(configDir, root);
+  } finally {
+    cleanup(root);
+  }
+  const fixturePath = path.join(FIXTURE_DIR, `${runtime}.json`);
+  fs.writeFileSync(fixturePath, JSON.stringify(actual, null, 2) + '\n', 'utf8');
+  process.stdout.write(`[gen] ${runtime}: wrote ${Object.keys(actual).length} file hashes -> ${fixturePath}\n`);
+}

package/scripts/run-tests.cjs

@@ -570,11 +570,13 @@ function main() {
   // progress (verified: no leaked handle / hang; --test-force-exit exits leaks
   // cleanly, so the timeout was pure slowness, NOT the leak the kill message guesses).
   // The per-chunk timeout is sized for a "healthy chunk (~4-5 min)"; keep chunks at
-  // roughly half a shard so each gets its own fresh 600s budget and a fresh node
-  // process (also relieving per-process memory pressure from 170+ files at once).
+  // roughly a third of a shard so each gets its own fresh 600s budget and a fresh
+  // node process (also relieving per-process memory pressure from 170+ files at once).
+  // Lowered from 90 to 60 after #1575 — macOS Node 22 shard 2/3 chunk 2 (~80 files
+  // including state.test.cjs, perf-*, worktree-cleanup) exceeded 600s with 90.
   const MAX_FILES_PER_CHUNK = process.env.RUN_TESTS_MAX_FILES_PER_CHUNK
     ? Number(process.env.RUN_TESTS_MAX_FILES_PER_CHUNK)
-    : 90;
+    : 60;
 
   // node:test does not exit until the event loop drains. A unit test that leaks
   // an open handle (un-terminated Worker, un-killed child_process, ref'd timer)

package/scripts/sync-runtime-launcher.cjs

@@ -343,9 +343,12 @@ function transformFile(content, preamble) {
     }
   }
 
-  // Insert preamble into the first gsd_run block only
+  // Insert preamble into the first gsd_run block only — UNLESS this file
+  // delegates to the shared resolver reference (@-include). Delegating files keep
+  // the stripped blocks (any inline preamble removed) but never get one inserted.
+  const delegates = delegatesToResolverReference(content);
   const finalBlocks = strippedBlocks.map((stripped, bi) => {
-    if (bi === firstGsdRunBlockIdx) {
+    if (!delegates && bi === firstGsdRunBlockIdx) {
       return insertPreamble(stripped, preamble);
     }
     return stripped;
@@ -374,6 +377,21 @@ function escapeRegExp(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * A file "delegates to the shared resolver" when it pulls the canonical gsd_run
+ * preamble in from gsd-core/references/gsd-run-resolver.md via an @-include
+ * instead of inlining the snippet (see onboard.md / issue #1990).
+ *
+ * These files must NOT carry an inline preamble: the resolver reference ships the
+ * one canonical copy, and onboard-command.test.cjs asserts the inline form is
+ * absent. transformFile still STRIPS any inline preamble from them (so a stray
+ * copy is removed) but never re-inserts one — mirroring the exemption in
+ * runtime-launcher-parity.test.cjs (subtest B / B2).
+ */
+function delegatesToResolverReference(content) {
+  return content.includes('references/gsd-run-resolver.md');
+}
+
 // Main
 function main() {
   const preamble = loadPreamble();

package/skills/gsd-map-codebase/SKILL.md

@@ -42,7 +42,7 @@ Parse the first token of $ARGUMENTS:
 Check for .planning/STATE.md - loads context if project already initialized
 
 **This command can run:**
-- Before /gsd-new-project (brownfield codebases) - creates codebase map first
+- Via /gsd-onboard for first-time brownfield setup - creates codebase map first
 - After /gsd-new-project (greenfield codebases) - updates codebase map as code evolves
 - Anytime to refresh codebase understanding
 </context>
@@ -51,7 +51,7 @@ Check for .planning/STATE.md - loads context if project already initialized
 **Use map-codebase for:**
 - Brownfield projects before initialization (understand existing code first)
 - Refreshing codebase map after significant changes
-- Onboarding to an unfamiliar codebase
+- Refreshing or deepening an onboarded codebase map
 - Before major refactoring (understand current state)
 - When STATE.md references outdated codebase info
 
@@ -71,7 +71,7 @@ Check for .planning/STATE.md - loads context if project already initialized
 4. Wait for agents to complete, collect confirmations (NOT document contents)
 5. Verify all 7 documents exist with line counts
 6. Commit codebase map
-7. Offer next steps (typically: /gsd-new-project or /gsd-plan-phase)
+7. Offer next steps (typically: /gsd-onboard, /gsd-new-project, or /gsd-plan-phase)
 </process>
 
 <success_criteria>

package/skills/gsd-ns-project/SKILL.md

@@ -14,6 +14,7 @@ inline as part of `gsd-audit-milestone`'s output.
 | User wants | Invoke |
 |---|---|
 | Start a new project | gsd-new-project |
+| Onboard an existing codebase | gsd-onboard |
 | Create a new milestone | gsd-new-milestone |
 | Complete the current milestone | gsd-complete-milestone |
 | Audit a milestone for issues | gsd-audit-milestone |

package/skills/gsd-onboard/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: gsd-onboard
+description: "Guide existing codebase onboarding through mapping, doc ingest, and planning setup"
+argument-hint: "[--fast] [--text]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
+<objective>
+Guide brownfield onboarding for an existing codebase by routing through the existing GSD primitives in the safe order: codebase map → docs ingest → project initialization → onboarding summary.
+
+**Creates or confirms:**
+- `.planning/codebase/` — evidence-backed codebase map from `/gsd-map-codebase`
+- `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` — project setup from `/gsd-new-project` or `/gsd-ingest-docs`
+- `.planning/onboarding/SUMMARY.md` — lightweight index of what was learned and the next command
+
+**Non-goals:** This command does not execute phases, ship work, or overwrite existing planning artifacts without an explicit gate.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/onboard.md
+@~/.claude/gsd-core/references/ui-brand.md
+@~/.claude/gsd-core/references/gate-prompts.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Flags:
+- `--fast` — prefer `/gsd-map-codebase --fast` for the mapping handoff; the complete map is still required before `/gsd-new-project`.
+- `--text` — use plain-text numbered lists instead of TUI menus.
+</context>
+
+<process>
+Execute the onboard workflow end-to-end. Preserve all safety gates, text-mode fallbacks, idempotency checks, and top-level handoff rules for nested interactive commands.
+</process>