Merge branch 'next' into feat/1820-specless-predicate-rail

2026-07-07 07:49:07 -04:00
parent 91998dcbca d2ae7fe391
commit ea4378063f
171 changed files with 5853 additions and 498 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -620,7 +620,8 @@ Equivalent paths for other runtimes:
 │   ├── FEATURES.md
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
-├── codebase/               # Brownfield mapping (from /gsd-map-codebase)
+├── codebase/               # Brownfield mapping (from /gsd-map-codebase or /gsd-onboard)
+├── onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
 │   ├── STACK.md            # YAML frontmatter carries `last_mapped_commit`
 │   ├── ARCHITECTURE.md     # for the post-execute drift gate (#2003)
 │   ├── CONVENTIONS.md
--- a/docs/CLI-TOOLS.md
+++ b/docs/CLI-TOOLS.md
@@ -421,13 +421,14 @@ node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"

 ## Init Commands (Compound Context Loading)

-Load all context needed for a specific workflow in one call. Returns JSON with project info, config, state, and workflow-specific data.
+Load all context needed for a specific workflow in one call. Returns JSON with project info, config, state, and workflow-specific data. `init onboard [--fast] [--text]` reports brownfield signals, planning-doc candidates, codebase-map completeness, fast-map readiness, text-mode routing, partial planning state, and onboarding summary status for `/gsd-onboard`.

 ```bash
 node gsd-tools.cjs init execute-phase <phase>
 node gsd-tools.cjs init plan-phase <phase>
 node gsd-tools.cjs init new-project
 node gsd-tools.cjs init new-milestone
+node gsd-tools.cjs init onboard [--fast] [--text]
 node gsd-tools.cjs init quick <description>
 node gsd-tools.cjs init resume
 node gsd-tools.cjs init verify-work <phase>
--- a/docs/COMMANDS.md
+++ b/docs/COMMANDS.md
@@ -58,6 +58,25 @@ Initialize a new project with deep context gathering.

 ---

+### `/gsd-onboard`
+
+Guide an existing codebase through first-time GSD onboarding. The command checks repo state, routes you through codebase mapping, optional docs ingest, project initialization, and creates an onboarding summary once planning exists.
+
+| Flag | Description |
+|------|-------------|
+| `--fast` | Prefer the lightweight `/gsd-map-codebase --fast` mapping handoff; a complete map is still required before `/gsd-new-project` |
+| `--text` | Use numbered plain-text gates instead of TUI menus |
+
+**Prerequisites:** Existing repo or planning docs. For empty greenfield projects, use `/gsd-new-project`.
+**Produces:** `.planning/codebase/` via map-codebase, `.planning/` via new-project or ingest-docs, and `.planning/onboarding/SUMMARY.md` after project setup.
+
+```bash
+/gsd-onboard           # Guided brownfield onboarding
+/gsd-onboard --fast    # Use lightweight codebase mapping first, then complete the map before project setup
+```
+
+---
+
 ### `/gsd-workspace`

 Manage GSD workspaces — create, list, or remove isolated workspace environments with repo copies and independent `.planning/` directories.
@@ -1183,7 +1202,7 @@ gsd capability remove my-cap --scope project          # Turn the installed overl

 ### `/gsd-map-codebase`

-Analyze existing codebase with parallel mapper agents. Use `--fast` for a quick single-agent scan, or `--query` to search existing intel.
+Analyze existing codebase with parallel mapper agents. Use `--fast` for a quick single-agent scan, or `--query` to search existing intel. First-time brownfield setup should usually start with `/gsd-onboard`, which hands off to this command when a map is missing.

 | Argument | Required | Description |
 |----------|----------|-------------|
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -38,6 +38,7 @@
  - [Model Profiles](#26-model-profiles)
 - [Brownfield Features](#brownfield-features)
  - [Codebase Mapping](#27-codebase-mapping)
+  - [Existing Codebase Onboarding](#27b-existing-codebase-onboarding)
 - [Utility Features](#utility-features)
  - [Debug System](#28-debug-system)
  - [Todo Management](#29-todo-management)
@@ -789,7 +790,7 @@

 **Command:** `/gsd-map-codebase [area]`

-**Purpose:** Analyze an existing codebase before starting a new project, so GSD understands what exists.
+**Purpose:** Analyze an existing codebase before starting a new project or as the mapping handoff from `/gsd-onboard`, so GSD understands what exists.

 **Requirements:**
 - REQ-MAP-01: System MUST spawn parallel mapper agents for each analysis area
@@ -817,6 +818,27 @@ only the subtrees the phase actually changed. Each produced document carries
 `last_mapped_commit` in its YAML frontmatter so drift can be measured
 against the mapping point, not HEAD.

+### 27b. Existing Codebase Onboarding
+
+**Command:** `/gsd-onboard [--fast] [--text]`
+
+**Purpose:** Guide first-time setup for an existing repository by checking brownfield state, routing through codebase mapping and docs ingest, then handing off to project initialization without silently overwriting planning artifacts.
+
+**Requirements:**
+- REQ-ONBOARD-01: System MUST detect existing code, package manifests, planning documents, partial `.planning/` state, and complete or missing codebase-map files.
+- REQ-ONBOARD-02: System MUST hand off to `/gsd-map-codebase` or `/gsd-map-codebase --fast` when brownfield code lacks the required `.planning/codebase/` map files; fast-map readiness is partial and MUST NOT be treated as sufficient for `/gsd-new-project`.
+- REQ-ONBOARD-03: System MUST offer `/gsd-ingest-docs` before `/gsd-new-project` when ADR/PRD/SPEC/RFC candidates exist and no project exists.
+- REQ-ONBOARD-04: System MUST refuse to report onboarding complete until `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist.
+- REQ-ONBOARD-05: System MUST create or confirm `.planning/onboarding/SUMMARY.md` only after project setup exists.
+- REQ-ONBOARD-06: System MUST support `--text` for numbered plain-text gates on runtimes without interactive menus.
+
+**Produces:**
+| Artifact | Description |
+|----------|-------------|
+| `.planning/codebase/` | Codebase map produced by the `/gsd-map-codebase` handoff |
+| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` | Planning setup produced by `/gsd-new-project` or `/gsd-ingest-docs` |
+| `.planning/onboarding/SUMMARY.md` | Onboarding status, artifact index, and next-command summary |
+
 ### 27a. Post-Execute Codebase Drift Detection

 **Introduced by:** #2003
--- a/docs/INVENTORY-MANIFEST.json
+++ b/docs/INVENTORY-MANIFEST.json
@@ -78,6 +78,7 @@
      "/gsd-ns-project",
      "/gsd-ns-review",
      "/gsd-ns-workflow",
+      "/gsd-onboard",
      "/gsd-pause-work",
      "/gsd-phase",
      "/gsd-plan-phase",
@@ -160,6 +161,7 @@
      "next.md",
      "node-repair.md",
      "note.md",
+      "onboard.md",
      "pause-work.md",
      "plan-milestone-gaps.md",
      "plan-phase.md",
@@ -225,6 +227,7 @@
      "gates.md",
      "git-integration.md",
      "git-planning-commit.md",
+      "gsd-run-resolver.md",
      "honest-verifier.md",
      "ios-scaffold.md",
      "loop-hook-dispatch.md",
@@ -307,6 +310,8 @@
      "capability-writer.cjs",
      "check-command-router.cjs",
      "cjs-command-router-adapter.cjs",
+      "claude-orchestration-command-router.cjs",
+      "claude-orchestration.cjs",
      "cli-exit.cjs",
      "cli-skew-check.cjs",
      "clock.cjs",
@@ -368,6 +373,7 @@
      "model-catalog.cjs",
      "model-profiles.cjs",
      "model-resolver.cjs",
+      "onboard-projection.cjs",
      "package-identity.cjs",
      "package-legitimacy.cjs",
      "phase-command-router.cjs",
--- a/docs/INVENTORY.md
+++ b/docs/INVENTORY.md
@@ -79,6 +79,7 @@ These six routers are descriptor-only entries that the model picks first; the bo
 | Command | Role | Source |
 |---------|------|--------|
 | `/gsd-new-project` | Initialize a new project with deep context gathering and PROJECT.md. | [commands/gsd/new-project.md](../commands/gsd/new-project.md) |
+| `/gsd-onboard` | Guide existing codebase onboarding through mapping, docs ingest, project setup, and onboarding summary. | [commands/gsd/onboard.md](../commands/gsd/onboard.md) |
 | `/gsd-workspace` | Manage GSD workspaces — create (`--new`), list (`--list`), or remove (`--remove`) isolated workspace environments. | [commands/gsd/workspace.md](../commands/gsd/workspace.md) |
 | `/gsd-discuss-phase` | Gather phase context through adaptive questioning before planning. | [commands/gsd/discuss-phase.md](../commands/gsd/discuss-phase.md) |
 | `/gsd-mvp-phase` | Plan a phase as a vertical MVP slice — user story, SPIDR splitting, then plan-phase. | [commands/gsd/mvp-phase.md](../commands/gsd/mvp-phase.md) |
@@ -223,6 +224,7 @@ Full roster at `gsd-core/workflows/*.md`. Workflows are thin orchestrators that
 | `milestone-summary.md` | Milestone summary synthesis — onboarding and review artifact from milestone artifacts. | `/gsd-milestone-summary` |
 | `new-milestone.md` | Start a new milestone cycle — load project context, gather goals, update PROJECT.md/STATE.md. | `/gsd-new-milestone` |
 | `new-project.md` | Unified new-project flow — questioning, research (optional), requirements, roadmap. | `/gsd-new-project` |
+| `onboard.md` | Brownfield onboarding orchestration — map codebase, ingest docs, initialize planning, summarize next step. | `/gsd-onboard` |
 | `new-workspace.md` | Create an isolated workspace with repo worktrees/clones and an independent `.planning/`. | `/gsd-workspace --new` |
 | `next.md` | Detect current project state and automatically advance to the next logical step. | `/gsd-progress --next` |
 | `node-repair.md` | Autonomous repair operator for failed task verification; invoked by `execute-plan`. | `execute-plan.md` (recovery) |
--- a/docs/USER-GUIDE.md
+++ b/docs/USER-GUIDE.md
@@ -79,7 +79,7 @@ The core GSD loop is: **discuss → plan → execute → verify → ship**, repe

 See [Your first project](tutorials/your-first-project.md).

-For onboarding an existing codebase before starting a new milestone, see [Onboarding an existing codebase](tutorials/onboarding-an-existing-codebase.md).
+For onboarding an existing codebase before starting a new milestone, run `/gsd-onboard` or see [Onboarding an existing codebase](tutorials/onboarding-an-existing-codebase.md).

 **Relevant flags at a glance:**

@@ -536,11 +536,13 @@ claude --dangerously-skip-permissions
 ### Existing Codebase

 ```bash
-/gsd-map-codebase           # Analyse what exists (parallel agents)
-/gsd-new-project            # Questions focus on what you're ADDING
+/gsd-onboard                # Safely map, ingest docs, and initialize planning
+# Follow the printed top-level handoff commands, then rerun /gsd-onboard
 # (normal phase workflow from here)
 ```

+`/gsd-onboard` routes through `/gsd-map-codebase`, `/gsd-ingest-docs`, and `/gsd-new-project` without nesting interactive workflows or overwriting existing planning files silently.
+
 **Post-execute drift detection (#2003).** After every `/gsd-execute-phase`, GSD checks whether the phase introduced enough structural change to make `.planning/codebase/STRUCTURE.md` stale. Flip the behavior with:

 ```bash
@@ -986,7 +988,8 @@ To disable parallel execution entirely: `/gsd-settings` → set `parallelization
    themes/
      default.css         # Shared CSS variables for all sketches
    MANIFEST.md           # Index of all sketches with winners
-  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
+  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
+  onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Atomic execution plans
--- a/docs/adr/1143-claude-orchestration-capability.md
+++ b/docs/adr/1143-claude-orchestration-capability.md
@@ -86,3 +86,39 @@ These existing multi-model features (`execute-phase` `cross_ai_delegation`, the
 - **Neutral:** no effect on non-Claude runtimes by construction; no behavior change until explicitly enabled.

 > **Governance note:** This ADR is a *draft design* accompanying feature request #1143. Per CONTRIBUTING, it is PR'd only after the issue receives `approved-feature`, and the capability is implemented only after #857 is released.
+
+## Amendment (2026-07-06): BETA v1 implementation landed
+
+#857 is **released** (CLOSED); the capability infrastructure is live. The BETA v1
+of this capability has shipped as `capabilities/claude-orchestration/` with the
+scope agreed in the Decision, refined to the lowest-risk first slice:
+
+- **Detection + emission** live as pure, fail-closed functions in
+  `gsd-core/bin/lib/claude-orchestration.cjs` (source `src/claude-orchestration.cts`):
+  `detectWorkflowBackend` (gate ladder: enabled → Claude runtime →
+  execution_backend ≠ inline → host dispatch nested+background → valid Agent SDK
+  → SDK ≥ `claude_orchestration.min_agent_sdk_version`, default `0.3.149`) and
+  `emitWorkflowScript` (waves → `parallel()` stage barriers, plans →
+  `agent({ agentType: 'gsd-executor', isolation: 'worktree' })`, `files_modified`
+  overlap → separate sequential stages, `resumeFromRunId` wired to the phase run
+  id, shared `budget(tokens)` pool). All interpolated values are validated as
+  script-safe identifiers or JSON-quoted (review Finding 1).
+- **Loop registration** is at the two **wired** points the loop host contract
+  actually renders: `execute:wave:post into:executor` (Workflow-backend guidance)
+  and `plan:post into:planner` (ultraplan ownership declaration). `execute:wave:pre`
+  and `execute:pre` are declared in the contract but **not wired** today, so the
+  capability registers at `wave:post` (the constraint `external-job` also documents).
+- **Config** is federated (`claude_orchestration.enabled` default false /
+  `activationKey`, `execution_backend` enum `auto|workflow|inline` default `auto`,
+  `min_agent_sdk_version`); the keys live only in the registry, so uninstall
+  removes them cleanly.
+- **ultraplan ownership** is declared in the manifest (`plan:post` contribution);
+  full install-profile migration of the `gsd-ultraplan-phase` skill into the
+  capability's `skills[]` is deferred to a follow-up (it triggers the CLUSTERS /
+  profile membership gate and is a heavier, install-machinery change).
+
+Status remains **Proposed** — the BETA is default-off and the end-to-end Workflow
+execution path (actual orchestration via the Workflow tool inside Claude Code) is
+not verifiable outside that runtime. The capability is structurally complete and
+tested at the contract level; flipping to Accepted follows maintainer sign-off on
+the E2E behaviour once exercised on Claude Code with the Workflow tool present.
--- a/docs/adr/1990-existing-code-onboarding.md
+++ b/docs/adr/1990-existing-code-onboarding.md
@@ -0,0 +1,69 @@
+# Existing Code Onboarding Module owns deterministic repo-state detection and onboarding route selection
+
+- **Status:** Proposed
+- **Date:** 2026-07-06
+- **Issue:** #1990
+- **Implementation:** PR #1994
+
+## Context
+
+GSD already ships strong individual primitives for adopting an existing codebase: `/gsd:map-codebase` (parallel codebase analysis), `/gsd:ingest-docs` (classify and consolidate existing ADR/PRD/SPEC/RFC docs), and `/gsd:new-project` (planning initialization). What it lacked was a single guided entry point that inspects a brownfield repository and tells the user *which primitive runs first*.
+
+Left to prose alone, that ordering is ambiguous and unsafe: a user can initialize planning before a codebase map exists, skip relevant design docs, or overwrite/duplicate `.planning/` context instead of reusing it. The ordering is not a matter of taste — it is a **dependency graph** (a map should exist before planning; existing design docs should be ingested before a fresh `/gsd:new-project`; nothing should clobber an in-progress `.planning/`). A dependency graph that decides the next safe action from filesystem state is a *projection*, not something a workflow's natural-language instructions can evaluate reliably or test.
+
+GSD already has the seam for this. The **Init Command Module** (`src/init.cts` → `gsd-core/bin/lib/init.cjs`) owns the `init.*` family of query handlers that compose atomic queries into the flat JSON bundles that init workflows consume, alongside the projection-module precedent set by the **Planning Path Projection Module** (ADR-0006) and the **Shell Command Projection Module** (ADR-0009). Adding `/gsd:onboard` as free-form workflow prose that scans the tree inline would put untested, non-deterministic filesystem logic in markdown — precisely the anti-pattern those projection modules exist to prevent.
+
+## Decision
+
+Introduce the **Existing Code Onboarding Module** (implemented as the `src/onboard-projection.cts` → `gsd-core/bin/lib/onboard-projection.cjs` projection) as the Seam that owns **deterministic detection of brownfield repository state and the selection of the next onboarding action**. It is a pure, side-effect-free projection consumed by the Init Command Module's `initOnboard` handler and rendered by the `/gsd:onboard` workflow. It never writes; detection and route selection are a function of repository state only.
+
+**Detected state (inputs):**
+
+| Signal | Rule / invariant |
+|---|---|
+| Brownfield code present | Depth-capped recursive scan for source files (`hasCodeFilesInternal`) OR a recognized package manifest (`hasPackageFileInternal`). |
+| Generated / vendor exclusion | Scan skips `CODE_SCAN_SKIP_DIRS` (`node_modules`, `dist`, `build`, `.next`, `.nuxt`, `.svelte-kit`, `coverage`, `vendor`, `.venv`, `venv`) so vendored trees never produce a false brownfield positive. |
+| Codebase-map completeness | Whether `.planning/codebase/` holds the canonical map artifacts. |
+| Existing design docs | Presence of ADR/PRD/SPEC/RFC-style candidates (root, nested, and segment-based). |
+| Partial planning state | Whether some but not all of `PROJECT.md` / `REQUIREMENTS.md` / `ROADMAP.md` / `STATE.md` exist. |
+
+**Route selection (output), ordered by dependency, not by convenience:**
+
+1. Brownfield code without a complete `.planning/codebase/` map → hand off to `/gsd:map-codebase` (or `/gsd:map-codebase --fast` in fast mode).
+2. Design-doc candidates present and no project yet → offer `/gsd:ingest-docs` **before** `/gsd:new-project`.
+3. Otherwise → `/gsd:new-project`.
+
+The gate order is load-bearing: **partial-planning and fast-map-completeness are evaluated before the docs-ingest branch**, so a half-mapped or half-initialized repo is never routed past the step it still owes. Handoff commands are runtime-formatted (`buildHandoffCommands` / `formatGsdSlash`) so the projected next command is correct for the installed runtime's slash syntax.
+
+**Safety invariants (the reason this is a Module, not a helper):**
+
+- **Idempotent / no silent overwrite.** Onboarding never mutates existing tracked `.planning/` artifacts; re-running leaves them byte-unchanged.
+- **`SUMMARY.md` is a trailing artifact.** `.planning/onboarding/SUMMARY.md` is written only *after* project setup exists, and only if absent.
+- **"Complete" is a conjunction.** Onboarding does not report complete until `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist — no single-file short-circuit.
+- **Text-mode parity.** `--text` renders the same gate decisions as numbered plain-text prompts, so runtimes without an interactive picker get identical routing.
+
+## What stays OUTSIDE this Module
+
+- **The primitives themselves.** `/gsd:map-codebase`, `/gsd:ingest-docs`, and `/gsd:new-project` retain their own behavior; the Module only *chooses and orders* them. It projects the route; it does not re-implement the destinations.
+- **Writing planning artifacts.** All `.planning/` writes remain owned by the destination commands and the Installer/planning modules. The projection is read-only.
+- **The workflow's rendering.** `gsd-core/workflows/onboard.md` owns menu/gate presentation; the command `commands/gsd/onboard.md` (and its skill mirror) owns delegation. The Module owns only the state→route decision they consume.
+
+## Consequences
+
+- Brownfield onboarding becomes a single, testable entry point with deterministic routing, rather than order-of-operations folklore in prose. The projection is unit-tested (`tests/onboard-command.test.cjs`) for brownfield/greenfield detection, vendor-dir exclusion, gate ordering (partial-planning before docs-ingest), idempotency/no-mutation, and runtime-formatted handoffs.
+- The Init Command Module gains one more heavyweight handler (`initOnboard`) with the same `{ data: <flat JSON> }` contract as its siblings — no new dispatch shape.
+- **New maintenance coupling, now explicit.** The Module's completeness checks must track the canonical `.planning/codebase/` artifact list and the routing targets' identities; if `/gsd:map-codebase` / `/gsd:ingest-docs` / `/gsd:new-project` change their entry contracts, this projection must follow. This ADR records that coupling as the known cost of centralizing the routing decision (the alternative — duplicating the decision across each primitive — is worse).
+- No new runtime dependencies; no change to existing command semantics (additive).
+
+## Open questions
+
+- Should codebase-map completeness be sourced from a single shared predicate (owned by the map module) rather than re-encoded here, so the two cannot drift?
+- The `/gsd:onboard` workflow sources its `gsd_run` bootstrap from a shared `references/gsd-run-resolver.md` snippet rather than inlining it. If that delegation pattern is adopted by other workflows, it likely deserves its own short ADR — noting it here so the precedent is visible rather than silently established.
+
+## References
+
+- ADR-0006 — Planning Path Projection Module (projection-module precedent for `.planning` path resolution).
+- ADR-0009 — Shell Command Projection Module (runtime-aware projection precedent).
+- Init Command Module (`src/init.cts` → `gsd-core/bin/lib/init.cjs`) — owner of the `init.*` handler family that consumes this projection via `initOnboard`.
+- `CONTEXT.md` § Init Command Module — where the onboarding projection is registered.
+- Issue #1990 — feature spec and acceptance criteria.
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -64,6 +64,7 @@ See **[CONTRIBUTING.md — "Proposing an ADR or PRD"](../../CONTRIBUTING.md#prop
 | [1769-state-md-transition-module.md](1769-state-md-transition-module.md) | STATE.md Transition Module — intent-based transitions over scattered RMW callbacks | Proposed |
 | [1817-state-md-rebuild-derivability-contract.md](1817-state-md-rebuild-derivability-contract.md) | STATE.md rebuild — derivability contract (capstone 11th transition) | Accepted |
 | [2008-command-exit-zero-gate.md](2008-command-exit-zero-gate.md) | Generic gate-predicate evaluator with a `command-exit-zero` kind (#2008) | Accepted |
+| [1990-existing-code-onboarding.md](1990-existing-code-onboarding.md) | Existing Code Onboarding Module owns deterministic repo-state detection and onboarding route selection | Proposed |

 ## Seam map

--- a/docs/explanation/claude-orchestration-capability.md
+++ b/docs/explanation/claude-orchestration-capability.md
@@ -0,0 +1,94 @@
+# Claude orchestration capability (BETA)
+
+> **Explanation** — *why this capability exists and how it fits the loop.* For the
+> step-by-step, see the [capability reference](../reference/capability-matrix.md);
+> for the design record, see [ADR-1143](../adr/1143-claude-orchestration-capability.md).
+
+## The problem
+
+GSD's `execute-phase` is wave-based: plans carry a wave number, waves run
+sequentially, and plans *within* a wave run in parallel when their
+`files_modified` sets don't overlap. On most runtimes GSD realizes that by
+fanning out one backgrounded `gsd-executor` agent (in a worktree) per plan.
+
+On **Claude Code** that fan-out degrades. Backgrounded agents on Claude Code have
+no `Agent`/`Task` tool, so they cannot nest subagents ([#853]). The autonomous
+loop therefore falls back to **inline sequential execution** — and with it
+silently drops wave parallelism, the plan-checker, and the verifier — on the one
+runtime most GSD users run.
+
+Claude Code ships an orchestration primitive that sidesteps exactly this: the
+**Workflow tool** (the engine behind `/effort ultracode`, Agent SDK ≥ v0.3.149).
+A Workflow script *is* the orchestrator — it runs from the main loop and spawns
+subagents itself via `agent()`, `parallel()` (barrier), `pipeline()`, and
+`phase()`, with `isolation: 'worktree'`, a shared token `budget`, and
+`resumeFromRunId`.
+
+## The capability
+
+`claude-orchestration` is a **default-off, BETA, claude-only** capability that
+adopts the Workflow tool as an optional, runtime-gated parallel-execution
+backend, and folds the existing `gsd-ultraplan-phase` plan-offload under the same
+gate. It is blocked-on-nothing now that the ADR-857 capability system is released.
+
+- **`role: feature`**, `runtimeCompat.supported: ["claude"]`, `tier: full`.
+- **`activationKey: claude_orchestration.enabled`** — default `false`. Nothing
+  changes until you opt in.
+- Registers at two **wired** loop points: `execute:wave:post` (into the executor)
+  and `plan:post` (into the planner). Both are `onError: skip` and gated by the
+  `enabled` key.
+
+## How it decides whether to activate
+
+Detection is a pure, **fail-closed** function — `detectWorkflowBackend`. The
+Workflow backend activates only when *every* gate passes; any miss degrades to
+`inline` (today's behaviour):
+
+1. `claude_orchestration.enabled` is true.
+2. The runtime is Claude (the Workflow tool is Claude / Agent SDK-specific).
+3. `claude_orchestration.execution_backend` is `auto` or `workflow` (not `inline`).
+4. The host descriptor advertises `dispatch.nested` **and** `dispatch.background`
+   (the nesting-capable Claude-Code shape — a proxy for Workflow-tool presence,
+   meaningful only after gate 2).
+5. The Agent SDK reports a valid semver version.
+6. That version is `>= claude_orchestration.min_agent_sdk_version`
+   (default `0.3.149`). A pre-release of the floor (e.g. `0.3.149-rc.1`) compares
+   *below* the GA release per SemVer, so the preview backend stays off.
+
+## What the executor runs when the backend is active
+
+`emitWorkflowScript` maps the phase's wave/plan model onto Workflow primitives:
+
+| GSD concept | Workflow primitive |
+|---|---|
+| Wave | `parallel()` stage barrier |
+| Plan | `agent(brief, { agentType: 'gsd-executor', isolation: 'worktree' })` |
+| `files_modified` overlap | forces the plans into separate sequential stages |
+| Phase run id | `resumeFromRunId("<id>")` |
+| Phase token cap | `budget(<tokens>)` |
+
+Because the emitted script composes the **same** `gsd-executor` agent and
+**worktree isolation** the inline path uses, it produces the same `SUMMARY.md`
+artifacts and commits — the only difference is the execution vehicle.
+
+## The fallback contract
+
+On any runtime lacking the Workflow tool — or when the capability is disabled,
+the SDK is too old, or detection fails for any reason — execute-phase proceeds
+with the standard inline wave dispatch. This is a release gate, not a nicety: a
+regression test asserts the inline fallback on every non-capable combination, so
+the capability is default-off and low-risk by construction.
+
+## BETA scope (v1)
+
+The first slice ships **detection + emission + declarative ultraplan ownership**.
+The emitter is exercised at the contract level (structure, overlap splitting,
+resume, budget, anti-injection). End-to-end execution through the Workflow tool
+is verifiable only inside Claude Code with the tool present. Full install-profile
+migration of the `gsd-ultraplan-phase` skill into the capability's `skills[]`
+array is a follow-up (it touches the cluster/profile machinery); for v1 the
+manifest *declares* ultraplan ownership at `plan:post` and the existing skill's
+own runtime gate continues to no-op on non-Claude runtimes.
+
+[#853]: https://github.com/open-gsd/gsd-core/issues/853
+[#1143]: https://github.com/open-gsd/gsd-core/issues/1143
--- a/docs/how-to/enable-claude-orchestration-workflow-backend.md
+++ b/docs/how-to/enable-claude-orchestration-workflow-backend.md
@@ -0,0 +1,171 @@
+# How to enable and use the Claude orchestration backend (BETA)
+
+Run GSD's execute-phase waves through Claude Code's Workflow tool (`/effort ultracode`, Agent SDK ≥ v0.3.149) instead of the default one-agent-per-message dispatch, and fold the `gsd-ultraplan-phase` plan-offload under the same gate. On Claude Code this restores the wave parallelism that backgrounded-agent nesting (#853) otherwise forces inline.
+
+> **BETA.** This capability tracks a Claude Code preview surface. It is default-off, fail-closed, and Claude-only. Every detection miss degrades silently to today's inline behaviour — enabling it can never break the loop. See the [explanation doc](../explanation/claude-orchestration-capability.md) for the why, and [ADR-1143](../adr/1143-claude-orchestration-capability.md) for the design.
+
+**What you need:**
+- GSD installed with the `full` profile (the capability is `tier: full`).
+- **Claude Code** with the Workflow tool available (Agent SDK ≥ `0.3.149`). On any other runtime the capability is an explicit no-op — you can flip the switch safely, nothing happens.
+- A GSD project with at least one planned phase (you need a wave/plan manifest to emit a script for).
+
+---
+
+## Step 1 — Enable the capability
+
+The capability ships disabled. Turn on the master switch inside your GSD project:
+
+```bash
+gsd-tools query config-set claude_orchestration.enabled true
+```
+
+That single key gates everything — both the Workflow-backend hook at `execute:wave:post` and the ultraplan ownership declaration at `plan:post`. All other `claude_orchestration.*` keys are optional refinements.
+
+Verify it took:
+
+```bash
+gsd-tools query config-get claude_orchestration.enabled
+# → true
+```
+
+---
+
+## Step 2 — Check whether your runtime qualifies
+
+Detection is fail-closed: the Workflow backend activates only when **every** gate opens. Before relying on it, confirm your runtime reports as capable:
+
+```bash
+gsd-tools claude-orchestration detect-backend \
+  --runtime claude \
+  --agent-sdk-version 1.2.0
+```
+
+You will get one of two results:
+
+| `backend` | `available` | Meaning |
+|-----------|-------------|---------|
+| `workflow` | `true` | Every gate passed — the emitter will produce a Workflow script the orchestrator can run. |
+| `inline` | `false` | A gate failed. The `reason` field tells you which: `capability_disabled`, `runtime_not_claude`, `backend_inline`, `workflow_tool_unavailable`, `agent_sdk_version_unknown`, or `agent_sdk_version_below_floor`. |
+
+> **The CLI is a simulation harness, not a probe.** `detect-backend` assumes a capable host descriptor unless you pass `--no-nested-dispatch`. It exists so you (and the orchestrator) can ask "given these facts, would the backend activate?" The real detection the loop uses is the pure `detectWorkflowBackend` function, called with the live host descriptor.
+
+### If detection returns `inline`
+
+Work through the `reason`:
+
+- **`runtime_not_claude`** — you are on Codex / Cursor / opencode / etc. The Workflow tool is Claude-specific; there is nothing to enable here. Your loop is unchanged.
+- **`agent_sdk_version_below_floor`** — upgrade Claude Code / the Agent SDK to at least `claude_orchestration.min_agent_sdk_version` (default `0.3.149`). A pre-release of the floor (e.g. `0.3.149-rc.1`) compares *below* the GA release and will not activate.
+- **`workflow_tool_unavailable`** — your host descriptor does not advertise nested + background dispatch. This is unusual on Claude Code; if you see it, the Workflow tool is not present in this session.
+- **`agent_sdk_version_unknown`** — the version could not be determined. Supply it explicitly via `--agent-sdk-version`.
+
+### Pin a higher floor (optional)
+
+If you want to gate the BETA behind a newer Agent SDK than the default:
+
+```bash
+gsd-tools query config-set claude_orchestration.min_agent_sdk_version 1.0.0
+```
+
+---
+
+## Step 3 — Choose the execution backend
+
+`claude_orchestration.execution_backend` controls how aggressively the backend is used once detection passes:
+
+| Value | Behaviour |
+|-------|-----------|
+| `auto` (default) | Use the Workflow backend **if** detection passes; otherwise inline. The safe, recommended value. |
+| `workflow` | Force the Workflow backend when the tool is present (still fails closed to inline if the tool is absent or the SDK is too old — the floor applies in both modes). |
+| `inline` | Force today's manual one-agent-per-message dispatch, even on a capable Claude Code runtime. Use this to A/B compare or to temporarily retire the BETA. |
+
+Switch with:
+
+```bash
+gsd-tools query config-set claude_orchestration.execution_backend workflow
+```
+
+---
+
+## Step 4 — Emit a Workflow script for a phase
+
+With the capability enabled and detection passing, generate the Workflow script for a phase's wave/plan manifest. The manifest is the wave/plan model execute-phase already builds:
+
+```json
+{
+  "waves": [
+    {
+      "id": "w1",
+      "plans": [
+        { "id": "p1", "brief": "Implement the foo module", "files_modified": ["src/foo.cts"] },
+        { "id": "p2", "brief": "Wire the bar seam", "files_modified": ["src/bar.cts"] }
+      ]
+    }
+  ]
+}
+```
+
+Emit the script:
+
+```bash
+gsd-tools claude-orchestration emit-workflow \
+  --waves .planning/phases/01-foo/waves.json \
+  --run-id phase-01-foo \
+  --phase-dir .planning/phases/01-foo \
+  --budget 500000
+```
+
+The output is a generated Workflow script that maps GSD's model 1:1 onto Workflow primitives:
+
+- **waves → sequential `parallel()` barriers** (split into separate stages within a wave when `files_modified` overlap),
+- **plans → `agent(brief, { agentType: "gsd-executor", isolation: "worktree" })`** — the **same** executor agent and worktree isolation the inline path uses,
+- **`resumeFromRunId("<run-id>")`** wired to the phase run id,
+- **`budget(<tokens>)`** — a shared token pool across the whole phase (omit `--budget` to skip).
+
+Because the script composes the same `gsd-executor` agent + worktree isolation + `SUMMARY.md` artifact as the inline path, the artifacts and commits it produces are identical — only the execution vehicle differs.
+
+### Run the emitted script
+
+Feed the emitted script to Claude Code's Workflow tool (`/effort ultracode`, or an Agent SDK `Workflow` invocation). The orchestrator runs it; each `agent()` call spawns a `gsd-executor` in its own worktree, waves barrier between each other, and `resumeFromRunId` lets an interrupted phase resume without re-running completed plans.
+
+---
+
+## Step 5 — Ultraplan plan-offload
+
+Enabling the capability also folds `gsd-ultraplan-phase` under the same runtime gate. When the capability is on, the planner may offer the `/gsd-ultraplan-phase` path (offload plan-phase to Claude Code's ultraplan cloud) as an alternative to local `/gsd-plan-phase`. This is advisory — the stable local planner remains the default.
+
+If the capability is off, or the runtime is not Claude Code, ultraplan offload is not surfaced and `/gsd-plan-phase` runs as normal.
+
+---
+
+## Disabling
+
+To turn the capability off and return to byte-identical inline behaviour:
+
+```bash
+gsd-tools query config-set claude_orchestration.enabled false
+```
+
+Or force inline dispatch while leaving the capability otherwise on:
+
+```bash
+gsd-tools query config-set claude_orchestration.execution_backend inline
+```
+
+Either step is sufficient — no uninstall or resurface needed. The federated config keys live only in the capability registry, so they vanish cleanly if the capability is ever removed.
+
+---
+
+## What is and is not wired in BETA v1
+
+**Working today:**
+- Detection (`detectWorkflowBackend` / `gsd-tools claude-orchestration detect-backend`) — fail-closed, tested across every gate.
+- Emission (`emitWorkflowScript` / `gsd-tools claude-orchestration emit-workflow`) — waves→barriers, overlap→stages, resume, budget, anti-injection.
+- The contribution fragments at `execute:wave:post` and `plan:post` (gated, `onError: skip`).
+- Inline fallback on every non-capable combination (regression-tested).
+
+**Not yet wired (follow-ups):**
+- `execute-phase.md` does not yet auto-branch to emit-and-run the Workflow script. Today you emit the script explicitly (Step 4) and run it via the Workflow tool. Automatic dispatch inside the loop is the next milestone.
+- The plan-checker and verifier still run inline — this capability delivers the parallel-execution backend, not those gates.
+- Full install-profile migration of the `gsd-ultraplan-phase` skill into the capability's `skills[]` (it is currently declared in the manifest; the skill's own runtime gate continues to no-op on non-Claude runtimes).
+
+If a preview-API change breaks detection, the capability degrades to inline; it cannot destabilise the core loop.
--- a/docs/how-to/fix-worktree-base-mismatch.md
+++ b/docs/how-to/fix-worktree-base-mismatch.md
@@ -1,16 +1,16 @@
 # How to fix the worktree base-mismatch (exit 42) error

-**Goal:** Understand why `/gsd-execute-phase` halts with `FATAL: worktree base mismatch` / exit 42 when your branch is ahead of the default branch, and choose the right fix to restore normal — or parallel — execution.
+**Goal:** Understand why `/gsd-execute-phase` or `/gsd-quick` halts with `FATAL: worktree base mismatch` / exit 42 when your branch is ahead of the default branch, and choose the right fix to restore normal — or parallel — execution.

-**Prerequisites:** GSD Core is installed and you have an active project. You have run `/gsd-execute-phase` and either seen the exit-42 error or the one-line `⚠ Worktree base mismatch` warning.
+**Prerequisites:** GSD Core is installed and you have an active project. You have run `/gsd-execute-phase` or `/gsd-quick` and either seen the exit-42 error or the one-line `⚠ Worktree base mismatch` warning.

 ---

 ## What you will see

-When you run `/gsd-execute-phase` on a branch that is ahead of the repository's default branch (for example, an unmerged milestone branch, a long-lived feature branch, or a branch with commits not yet in `origin/HEAD`), you may see one of two messages:
+When you run `/gsd-execute-phase` or `/gsd-quick` on a branch that is ahead of the repository's default branch (for example, an unmerged milestone branch, a long-lived feature branch, or a branch with commits not yet in `origin/HEAD`), you may see one of two messages:

-**Automatic-degrade warning (phase still completes):**
+**Automatic-degrade warning (phase or quick task still completes):**

 ```
 ⚠ Worktree base mismatch: HEAD (abc12345) differs from origin/HEAD (def67890).
@@ -19,7 +19,7 @@ To keep parallel worktrees, set worktree.baseRef:"head" in
 .claude/settings.local.json (or run: gsd-tools worktree set-baseref). See #683.
 ```

-The phase runs to completion sequentially; nothing is blocked. This is the runtime mitigation.
+The phase or quick task runs to completion sequentially; nothing is blocked. This is the runtime mitigation (`/gsd-execute-phase`: #683/#1369; `/gsd-quick`: #1941).

 **Exit-42 halt (older installs or misconfigured environments):**

--- a/docs/how-to/install-minimal-and-add-skills.md
+++ b/docs/how-to/install-minimal-and-add-skills.md
@@ -45,7 +45,7 @@ If `core` is too small, pick a wider profile instead. Pass it with `--profile=<n
 | Profile | What you get | Approx. description tokens |
 |---------|--------------|--------------------------|
 | `core` | The eight core-loop skills above. No agents. | ~130 desc tokens |
-| `standard` | Everything in `core` plus common management skills — `review`, `config`, `progress`, `resume-work`, `pause-work`, `workspace` — and the sub-agents those skills need. | ~700 desc tokens |
+| `standard` | Everything in `core` plus brownfield onboarding (`onboard`), common management skills — `review`, `config`, `progress`, `resume-work`, `pause-work`, `workspace` — and the sub-agents those skills need. | ~700 desc tokens |
 | `full` | Every skill and every sub-agent. This is the default when you pass no profile flag. | ~1,200 desc tokens |

 ```bash
--- a/docs/how-to/install-on-your-runtime.md
+++ b/docs/how-to/install-on-your-runtime.md
@@ -465,10 +465,11 @@ npx @opengsd/gsd-core@latest --opencode --global

 ## After install

-Restart your runtime to pick up new commands and agents. Then start your first project:
+Restart your runtime to pick up new commands and agents. Then start a new project or onboard an existing repo:

 ```bash
-/gsd-new-project
+/gsd-new-project   # greenfield project
+/gsd-onboard       # existing codebase
 ```

 If the command is not found after restart, verify the install directory matches the runtime's expected config path. The prerelease-editions section above covers the most common mismatch.
--- a/docs/ja-JP/ARCHITECTURE.md
+++ b/docs/ja-JP/ARCHITECTURE.md
@@ -474,7 +474,8 @@ UI-SPEC.md (per phase) ───────────────────
 │   ├── FEATURES.md
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
-├── codebase/               # ブラウンフィールドマッピング（/gsd-map-codebase から）
+├── codebase/               # ブラウンフィールドマッピング（/gsd-map-codebase または /gsd-onboard から）
+├── onboarding/             # ブラウンフィールドオンボーディング概要（/gsd-onboard から）
 │   ├── STACK.md
 │   ├── ARCHITECTURE.md
 │   ├── CONVENTIONS.md
--- a/docs/ja-JP/CLI-TOOLS.md
+++ b/docs/ja-JP/CLI-TOOLS.md
@@ -288,13 +288,14 @@ node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"

 ## Init コマンド（複合コンテキスト読み込み）

-特定のワークフローに必要なすべてのコンテキストを一度に読み込みます。プロジェクト情報、設定、状態、ワークフロー固有のデータを含む JSON を返します。
+特定のワークフローに必要なすべてのコンテキストを一度に読み込みます。プロジェクト情報、設定、状態、ワークフロー固有のデータを含む JSON を返します。`init onboard [--fast] [--text]` は `/gsd-onboard` 用に、brownfield シグナル、計画ドキュメント候補、コードベースマップの完全性、fast マップの準備状況、テキストモードルーティング、部分的な planning 状態、オンボーディングサマリー状態を返します。

 ```bash
 node gsd-tools.cjs init execute-phase <phase>
 node gsd-tools.cjs init plan-phase <phase>
 node gsd-tools.cjs init new-project
 node gsd-tools.cjs init new-milestone
+node gsd-tools.cjs init onboard [--fast] [--text]
 node gsd-tools.cjs init quick <description>
 node gsd-tools.cjs init resume
 node gsd-tools.cjs init verify-work <phase>
--- a/docs/ja-JP/COMMANDS.md
+++ b/docs/ja-JP/COMMANDS.md
@@ -51,6 +51,25 @@ v1.40 では、最初のステージエントリーポイントとして6つの

 ---

+### `/gsd-onboard`
+
+既存コードベースの初回 GSD オンボーディングを案内します。リポジトリ状態を確認し、コードベースマッピング、任意のドキュメント取り込み、プロジェクト初期化へ安全にハンドオフし、計画が揃った後にオンボーディング summary を作成します。
+
+| フラグ | 説明 |
+|------|-------------|
+| `--fast` | 軽量な `/gsd-map-codebase --fast` マッピングハンドオフを優先。ただし `/gsd-new-project` 前には完全なマップが必要 |
+| `--text` | TUI メニューではなく番号付きプレーンテキストのゲートを使用 |
+
+**前提条件:** 既存リポジトリまたは計画ドキュメント。空のグリーンフィールドプロジェクトには `/gsd-new-project` を使用します。
+**生成物:** map-codebase による `.planning/codebase/`、new-project または ingest-docs による `.planning/`、セットアップ後の `.planning/onboarding/SUMMARY.md`。
+
+```bash
+/gsd-onboard           # ガイド付き brownfield オンボーディング
+/gsd-onboard --fast    # 先に軽量マップを使い、その後プロジェクト設定前に完全マップを作成
+```
+
+---
+
 ### `/gsd-workspace`

 GSD ワークスペースを管理 — リポジトリコピーと独立した `.planning/` ディレクトリを持つ隔離されたワークスペース環境を作成、一覧表示、または削除します。
--- a/docs/ja-JP/FEATURES.md
+++ b/docs/ja-JP/FEATURES.md
@@ -38,6 +38,7 @@
  - [モデルプロファイル](#26-モデルプロファイル)
 - [ブラウンフィールド機能](#ブラウンフィールド機能)
  - [コードベースマッピング](#27-コードベースマッピング)
+  - [既存コードベースオンボーディング](#27b-既存コードベースオンボーディング)
 - [ユーティリティ機能](#ユーティリティ機能)
  - [デバッグシステム](#28-デバッグシステム)
  - [Todo 管理](#29-todo-管理)
@@ -781,7 +782,7 @@

 **コマンド:** `/gsd-map-codebase [area]`

-**目的:** 新しいプロジェクトを開始する前に既存のコードベースを分析し、GSD が既存の構成を理解できるようにします。
+**目的:** 新しいプロジェクトを開始する前、または `/gsd-onboard` からのマッピングハンドオフとして既存のコードベースを分析し、GSD が既存の構成を理解できるようにします。

 **要件:**
 - REQ-MAP-01: システムは各分析領域に対して並列マッパーエージェントを起動しなければならない
@@ -805,6 +806,27 @@
 `--paths <p1,p2,...>` スコープヒントを受け付けます。指定した場合、ツリー全体をスキャンする代わりに、リストされたリポジトリ相対プレフィックスに探索を制限します。
 これはフェーズが実際に変更したサブツリーのみを更新するために、実行後コードベースドリフトゲートが使用するパスウェイです。各生成ドキュメントはその YAML フロントマターに `last_mapped_commit` を持ち、ドリフトを HEAD ではなくマッピング時点と照らし合わせて計測できます。

+### 27b. 既存コードベースオンボーディング
+
+**コマンド:** `/gsd-onboard [--fast] [--text]`
+
+**目的:** 既存リポジトリの初回セットアップを案内し、brownfield 状態を確認してコードベースマッピング、docs 取り込み、プロジェクト初期化へ安全にハンドオフします。
+
+**要件:**
+- REQ-ONBOARD-01: 既存コード、package manifest、計画ドキュメント、部分的な `.planning/`、コードベースマップの不足を検出する。
+- REQ-ONBOARD-02: 必要な `.planning/codebase/` マップファイルがない brownfield では `/gsd-map-codebase` または `/gsd-map-codebase --fast` へハンドオフする。fast マップの readiness は部分的であり、`/gsd-new-project` に十分として扱ってはならない。
+- REQ-ONBOARD-03: ADR/PRD/SPEC/RFC 候補があり project がない場合、`/gsd-new-project` の前に `/gsd-ingest-docs` を提示する。
+- REQ-ONBOARD-04: `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md` が揃うまで完了扱いにしない。
+- REQ-ONBOARD-05: project setup 後にのみ `.planning/onboarding/SUMMARY.md` を作成または確認する。
+- REQ-ONBOARD-06: 対話型メニューがない runtime 向けに、`--text` で番号付きプレーンテキスト gate をサポートする。
+
+**生成物:**
+| Artifact | 説明 |
+|----------|-------------|
+| `.planning/codebase/` | `/gsd-map-codebase` handoff が生成するコードベースマップ |
+| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` | `/gsd-new-project` または `/gsd-ingest-docs` が生成する planning setup |
+| `.planning/onboarding/SUMMARY.md` | Onboarding status、artifact index、next-command summary |
+
 ### 27a. 実行後コードベースドリフト検出

 **導入:** #2003
--- a/docs/ja-JP/INVENTORY.md
+++ b/docs/ja-JP/INVENTORY.md
@@ -78,6 +78,7 @@
 | コマンド | 役割 | ソース |
 |----------|------|--------|
 | `/gsd-new-project` | 深いコンテキスト収集と PROJECT.md で新しいプロジェクトを初期化。 | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
+| `/gsd-onboard` | 既存コードベースをマッピング、ドキュメント取り込み、プロジェクト設定、onboarding summary へ案内。 | [commands/gsd/onboard.md](../../commands/gsd/onboard.md) |
 | `/gsd-workspace` | GSD ワークスペースを管理 — 独立したワークスペース環境を作成（`--new`）、一覧表示（`--list`）、削除（`--remove`）。 | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
 | `/gsd-discuss-phase` | 計画前にアダプティブな質問でフェーズコンテキストを収集。 | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
 | `/gsd-mvp-phase` | フェーズを垂直 MVP スライスとして計画 — ユーザーストーリー、SPIDR 分割、その後 plan-phase。 | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
@@ -218,6 +219,7 @@
 | `milestone-summary.md` | マイルストーンサマリー合成 — マイルストーンアーティファクトからオンボーディングとレビューアーティファクトを作成。 | `/gsd-milestone-summary` |
 | `new-milestone.md` | 新しいマイルストーンサイクルを開始 — プロジェクトコンテキストを読み込み、目標を収集して PROJECT.md/STATE.md を更新。 | `/gsd-new-milestone` |
 | `new-project.md` | 統合新プロジェクトフロー — 質問、調査（任意）、要件、ロードマップ。 | `/gsd-new-project` |
+| `onboard.md` | Brownfield onboarding orchestration — コードベースをマップし、docs を取り込み、planning を初期化し、次のステップを要約。 | `/gsd-onboard` |
 | `new-workspace.md` | リポジトリのワークツリー/クローンと独立した `.planning/` を持つ独立したワークスペースを作成。 | `/gsd-workspace --new` |
 | `next.md` | 現在のプロジェクト状態を検出して次の論理的なステップに自動的に進む。 | `/gsd-progress --next` |
 | `node-repair.md` | タスク検証が失敗した場合の自律修復オペレーター。`execute-plan` から呼び出し。 | `execute-plan.md` (recovery) |
--- a/docs/ja-JP/USER-GUIDE.md
+++ b/docs/ja-JP/USER-GUIDE.md
@@ -474,8 +474,8 @@ claude --dangerously-skip-permissions
 ### 既存のコードベース

 ```bash
-/gsd-map-codebase           # Analyse what exists (parallel agents)
-/gsd-new-project            # Questions focus on what you're ADDING
+/gsd-onboard                # Safely map, ingest docs, and initialize planning
+# Follow printed handoff commands, then rerun /gsd-onboard
 # (normal phase workflow from here)
 ```

@@ -864,7 +864,8 @@ All subagent/executor commits MUST use `--no-verify`.
    themes/
      default.css         # Shared CSS variables for all sketches
    MANIFEST.md           # Index of all sketches with winners
-  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
+  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
+  onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Atomic execution plans
--- a/docs/ja-JP/how-to/install-on-your-runtime.md
+++ b/docs/ja-JP/how-to/install-on-your-runtime.md
@@ -273,10 +273,11 @@ npx @opengsd/gsd-core@latest --opencode --global

 ## インストール後の作業

-新しいコマンドとエージェントを反映するためにランタイムを再起動してください。その後、最初のプロジェクトを開始します。
+新しいコマンドとエージェントを反映するためにランタイムを再起動してください。その後、新規プロジェクトを開始するか既存リポジトリをオンボーディングします。

 ```bash
-/gsd-new-project
+/gsd-new-project   # グリーンフィールドプロジェクト
+/gsd-onboard       # 既存コードベース
 ```

 再起動後もコマンドが見つからない場合は、インストールディレクトリがランタイムの期待する設定パスと一致しているか確認してください。最もよくある不一致については上記のプレリリースエディションのセクションを参照してください。
--- a/docs/ja-JP/reference/planning-artifacts.md
+++ b/docs/ja-JP/reference/planning-artifacts.md
@@ -23,6 +23,8 @@
 │   ├── architecture.md
 │   ├── stack.md
 │   └── ...
+├── onboarding/                         # ブラウンフィールドオンボーディング概要（オプション）
+│   └── SUMMARY.md
 ├── intel/                              # クエリ可能なシンボルインデックス（オプション、intel.enabled）
 │   └── API-SURFACE.md
 └── phases/
@@ -48,7 +50,7 @@
 | | |
 |---|---|
 | **用途** | プロジェクトの正規アイデンティティ: 概要、対象ユーザー、コアバリュー、要件、制約、主要な意思決定。プロダクトの進化に伴いプロジェクトライフサイクル全体を通じて更新されます。 |
-| **生成元** | `/gsd-new-project`（初回作成）; 意思決定が検証されると `/gsd-complete-milestone` によって更新されます。 |
+| **生成元** | `/gsd-new-project`（初回作成、`/gsd-onboard` のハンドオフを含む）; 意思決定が検証されると `/gsd-complete-milestone` によって更新されます。 |
 | **参照先** | すべてのプランニングワークフロー; `gsd-phase-researcher`、`gsd-planner`（コンテキスト）; `discuss-phase`（過去の意思決定）; `gsd-plan-checker`（プロジェクト制約）。 |

 ### `ROADMAP.md`
@@ -56,7 +58,7 @@
 | | |
 |---|---|
 | **用途** | マイルストーンおよびフェーズ一覧。ゴール、要件 ID、成功基準、フェーズごとの正規リファレンスを含みます。プロジェクトが何をどの順序で構築するかに関する唯一の信頼できる情報源です。 |
-| **生成元** | `/gsd-new-project`（初回作成）; `/gsd-phase --insert` および `/gsd-complete-milestone` によって更新されます。 |
+| **生成元** | `/gsd-new-project`（初回作成、`/gsd-onboard` のハンドオフを含む）; `/gsd-phase --insert` および `/gsd-complete-milestone` によって更新されます。 |
 | **参照先** | `/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`; フェーズ情報を必要とするすべてのオーケストレーションコマンド; `gsd-planner`、`gsd-plan-checker`、`gsd-phase-researcher`。 |

 ### `REQUIREMENTS.md`
@@ -64,7 +66,7 @@
 | | |
 |---|---|
 | **用途** | 番号付きのチェック可能な受け入れ基準。各要件はロードマップフェーズにマッピングされる ID（例: `AUTH-01`）を持ちます。フェーズが実行されると要件を完了済みとしてマークします。 |
-| **生成元** | `/gsd-new-project`（初回作成）; `execute-phase` によって要件が完了済みとしてマークされます。 |
+| **生成元** | `/gsd-new-project`（初回作成、`/gsd-onboard` のハンドオフを含む）; `execute-phase` によって要件が完了済みとしてマークされます。 |
 | **参照先** | `gsd-planner`（プランはすべてのフェーズ要件 ID に対処しなければならない）; `gsd-plan-checker` ディメンション1（要件カバレッジ）; `discuss-phase`（過去の要件）。 |

 ### `STATE.md`
@@ -72,7 +74,7 @@
 | | |
 |---|---|
 | **用途** | 現在地を追跡するリビングドキュメント — 現在のフェーズとプラン、進捗指標、蓄積された意思決定、セッション継続性ノート。すべてのワークフロー実行の開始時に読み込まれます。重要なアクションのたびに更新されます。 |
-| **生成元** | `/gsd-new-project`（初回作成）; すべてのフェーズワークフロー、`/gsd-pause-work`、`/gsd-resume-work` によって継続的に更新されます。 |
+| **生成元** | `/gsd-new-project`（初回作成、`/gsd-onboard` のハンドオフを含む）; すべてのフェーズワークフロー、`/gsd-pause-work`、`/gsd-resume-work` によって継続的に更新されます。 |
 | **参照先** | すべてのオーケストレーションワークフロー; `/gsd-progress`; `/gsd-quick` 経由のアドホックタスク実行; `gsd-planner` および `gsd-phase-researcher`（プロジェクトの意思決定）。 |

 完全なフィールドリファレンスは [STATE.md スキーマ](state-md.md) を参照してください。
@@ -87,6 +89,14 @@

 完全なスキーマは [CONFIGURATION](../../CONFIGURATION.md) を参照してください。

+### `onboarding/SUMMARY.md`（オプション）
+
+| | |
+|---|---|
+| **用途** | ブラウンフィールドオンボーディングの索引。アーティファクト状態、コードベースマッピングの完了状況、初回セットアップ後に推奨される次の GSD コマンドを記録します。 |
+| **生成元** | `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md` がすべて存在した後の `/gsd-onboard`。 |
+| **参照先** | 初回セットアップを確認する人間、および既存オンボーディング状態を確認する今後の `/gsd-onboard` 実行。 |
+
 ### `MILESTONES.md`（オプション）

 | | |
--- a/docs/ja-JP/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/ja-JP/tutorials/onboarding-an-existing-codebase.md
@@ -44,15 +44,15 @@ claude --dangerously-skip-permissions

 ---

-## ステップ 3 — コードベースのマッピング
+## ステップ 3 — Brownfield オンボーディングの開始

-プロジェクトを作成する前に、GSD Core に既存のコードを学習させてください。これがブラウンフィールドの計画を正確にするステップです。
+プロジェクトを作成する前に、GSD Core にリポジトリ状態を確認させ、安全な次のトップレベルコマンドを表示させます。これにより、コードベースコンテキストの取りこぼしや既存 planning ファイルの上書きを防げます。

 ```text
-/gsd-map-codebase
+/gsd-onboard
 ```

-GSD Core が4つの並行マッパーサブエージェントを生成します（「Spawning 4 parallel codebase mapper agents…」という通知が表示されます。1〜5分かかりますので中断しないでください）。各エージェントはそれぞれ異なる観点に注目します:
+オンボーディングがコードベースマップ不足を示したら、推奨オプションを選び、表示された `/gsd-map-codebase` ハンドオフを実行してから `/gsd-onboard` を再実行します。`/gsd-onboard --fast` は軽量な初回パスには使えますが、`/gsd-new-project` の前には完全なマップが必要です。`/gsd-map-codebase` が4つの並行マッパーサブエージェントを生成します（「Spawning 4 parallel codebase mapper agents…」という通知が表示されます。1〜5分かかりますので中断しないでください）。各エージェントはそれぞれ異なる観点に注目します:

 | エージェント | 観点 |
 |-------|-------|
@@ -84,7 +84,7 @@ Created .planning/codebase/:

 ---

-## ステップ 4 — コンテキストをクリアしてプロジェクトを作成
+## ステップ 4 — オンボーディングを再実行してプロジェクトを初期化する

 セッションウィンドウをクリアします:

@@ -92,12 +92,14 @@ Created .planning/codebase/:
 /clear
 ```

-プロジェクトを作成します。前のステップで GSD Core が既存のコードを見つけているため、これがブラウンフィールドプロジェクトであることをすでに把握しています。`/gsd-new-project` を実行すると、既存のものを再説明するのではなく、*追加する*内容に焦点を当てた質問がされます:
+`/gsd-onboard` をもう一度実行します。GSD Core が ADR、PRD、spec、RFC、またはルートレベルの要件ドキュメントを検出した場合は、先に推奨される `/gsd-ingest-docs` ハンドオフを実行し、その後 `/gsd-onboard` を再実行してください。コンテキストが整うと、オンボーディングはプロジェクト初期化のハンドオフを表示します:

 ```text
 /gsd-new-project
 ```

+前のステップで GSD Core が既存のコードを見つけているため、`/gsd-new-project` はこれがブラウンフィールドプロジェクトだと分かっています。質問は既存のものを再説明するのではなく、*追加する*内容に焦点を当てます:
+
 GSD Core が何を作りたいかを尋ねます。コードベース全体の説明ではなく、追加する機能で答えてください:

 ```text
@@ -124,6 +126,8 @@ Proposed Roadmap

 ロードマップを承認してください。

+プロジェクト設定が完了したら、もう一度 `/gsd-onboard` を実行します。`PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md` がすべて存在するため、オンボーディングは `.planning/onboarding/SUMMARY.md` を作成または確認します。
+
 **`.planning/` に作成されるファイル:**

 ```text
@@ -133,6 +137,7 @@ Proposed Roadmap
  ROADMAP.md          ← フェーズ 1、ステータス: pending
  STATE.md            ← セッションメモリ
  config.json         ← ワークフロー設定
+  onboarding/SUMMARY.md ← オンボーディング状態と次のコマンド
  codebase/           ← ステップ 3 の7つのマップファイル
 ```

@@ -212,6 +217,7 @@ GSD Core があなたの `CONVENTIONS.md` と `ARCHITECTURE.md` を読み込ん

 ## 学んだこと

+- `/gsd-onboard` が対話型コマンドをネストしたり既存 planning ファイルを上書きしたりせずに、ブラウンフィールド設定を安全に順序付ける仕組み。
 - `/gsd-map-codebase` が4つの並行エージェントを実行して `.planning/codebase/` に `STACK.md`、`ARCHITECTURE.md`、`CONVENTIONS.md`、`CONCERNS.md`、`STRUCTURE.md`、`TESTING.md`、`INTEGRATIONS.md` を生成する仕組み。
 - ブラウンフィールドリポジトリで `/gsd-new-project` を実行すると、*追加する*内容に焦点を当てた質問がされ、既存コードから Validated 要件が自動入力される仕組み。
 - コードベースマップが `/gsd-discuss-phase` のすべての質問を形成する方法 — ファイルパス、パターン、規約が実際のコードから導出される。
--- a/docs/ko-KR/ARCHITECTURE.md
+++ b/docs/ko-KR/ARCHITECTURE.md
@@ -512,7 +512,8 @@ UI-SPEC.md (단계별) ───────────────────
 │   ├── FEATURES.md
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
-├── codebase/               # 브라운필드 매핑 (/gsd-map-codebase에서)
+├── codebase/               # 브라운필드 매핑 (/gsd-map-codebase 또는 /gsd-onboard에서)
+├── onboarding/             # 브라운필드 온보딩 요약 (/gsd-onboard에서)
 │   ├── STACK.md            # YAML 전문에 `last_mapped_commit` 포함
 │   ├── ARCHITECTURE.md     # 실행 후 드리프트 게이트를 위한 (#2003)
 │   ├── CONVENTIONS.md
--- a/docs/ko-KR/CLI-TOOLS.md
+++ b/docs/ko-KR/CLI-TOOLS.md
@@ -288,13 +288,14 @@ node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"

 ## Init 명령 (복합 컨텍스트 로딩)

-하나의 호출로 특정 워크플로우에 필요한 모든 컨텍스트를 로드합니다. 프로젝트 정보, 설정, 상태, 워크플로우별 데이터가 포함된 JSON을 반환합니다.
+하나의 호출로 특정 워크플로우에 필요한 모든 컨텍스트를 로드합니다. 프로젝트 정보, 설정, 상태, 워크플로우별 데이터가 포함된 JSON을 반환합니다. `init onboard [--fast] [--text]`는 `/gsd-onboard`를 위해 brownfield 신호, 계획 문서 후보, 코드베이스 맵 완성도, fast 맵 준비 상태, 텍스트 모드 라우팅, 부분 planning 상태, 온보딩 요약 상태를 반환합니다.

 ```bash
 node gsd-tools.cjs init execute-phase <phase>
 node gsd-tools.cjs init plan-phase <phase>
 node gsd-tools.cjs init new-project
 node gsd-tools.cjs init new-milestone
+node gsd-tools.cjs init onboard [--fast] [--text]
 node gsd-tools.cjs init quick <description>
 node gsd-tools.cjs init resume
 node gsd-tools.cjs init verify-work <phase>
--- a/docs/ko-KR/COMMANDS.md
+++ b/docs/ko-KR/COMMANDS.md
@@ -51,6 +51,25 @@ v1.40에서 여섯 개의 네임스페이스 라우터가 1단계 진입점으

 ---

+### `/gsd-onboard`
+
+기존 코드베이스의 최초 GSD 온보딩을 안내합니다. 저장소 상태를 확인하고 코드베이스 매핑, 선택적 문서 수집, 프로젝트 초기화로 안전하게 넘긴 뒤 계획 파일이 준비되면 onboarding summary를 만듭니다.
+
+| 플래그 | 설명 |
+|------|-------------|
+| `--fast` | 경량 `/gsd-map-codebase --fast` 매핑 handoff 우선 사용. 단, `/gsd-new-project` 전에는 완전한 맵이 필요 |
+| `--text` | TUI 메뉴 대신 번호가 있는 plain-text gate 사용 |
+
+**전제 조건:** 기존 저장소 또는 계획 문서. 빈 greenfield 프로젝트는 `/gsd-new-project`를 사용하세요.
+**생성 결과:** map-codebase의 `.planning/codebase/`, new-project 또는 ingest-docs의 `.planning/`, 설정 후 `.planning/onboarding/SUMMARY.md`.
+
+```bash
+/gsd-onboard           # 안내형 brownfield 온보딩
+/gsd-onboard --fast    # 먼저 경량 맵을 사용하고, 프로젝트 설정 전 완전한 맵 작성
+```
+
+---
+
 ### `/gsd-workspace`

 GSD 워크스페이스 관리 — 리포지토리 복사본과 독립적인 `.planning/` 디렉토리를 갖는 격리된 워크스페이스 환경을 생성, 나열, 또는 삭제합니다.
--- a/docs/ko-KR/FEATURES.md
+++ b/docs/ko-KR/FEATURES.md
@@ -38,6 +38,7 @@
  - [모델 프로파일](#26-model-profiles)
 - [브라운필드 기능](#brownfield-features)
  - [코드베이스 매핑](#27-codebase-mapping)
+  - [기존 코드베이스 온보딩](#27b-existing-codebase-onboarding)
 - [유틸리티 기능](#utility-features)
  - [디버그 시스템](#28-debug-system)
  - [할 일 관리](#29-todo-management)
@@ -716,7 +717,7 @@

 **명령어:** `/gsd-map-codebase [area]`

-**목적:** 새 프로젝트를 시작하기 전에 기존 코드베이스를 분석하여 GSD가 무엇이 존재하는지 이해하도록 합니다.
+**목적:** 새 프로젝트 시작 전 또는 `/gsd-onboard`의 매핑 handoff로 기존 코드베이스를 분석하여 GSD가 무엇이 존재하는지 이해하도록 합니다.

 **요구사항.**
 - REQ-MAP-01: 각 분석 영역에 대한 병렬 매퍼 에이전트를 생성해야 합니다.
@@ -736,6 +737,27 @@
 | `TESTING.md` | 테스트 인프라, 커버리지, 패턴 |
 | `INTEGRATIONS.md` | 외부 서비스, API, 서드파티 의존성 |

+### 27b. Existing Codebase Onboarding
+
+**명령어:** `/gsd-onboard [--fast] [--text]`
+
+**목적:** 기존 저장소의 최초 설정을 안내하고 brownfield 상태를 확인해 코드베이스 매핑, docs 수집, 프로젝트 초기화로 안전하게 handoff합니다.
+
+**요구사항.**
+- REQ-ONBOARD-01: 기존 코드, package manifest, planning 문서, 부분 `.planning/` 상태, 코드베이스 맵 누락을 감지해야 합니다.
+- REQ-ONBOARD-02: 필요한 `.planning/codebase/` 맵 파일이 없는 brownfield에서는 `/gsd-map-codebase` 또는 `/gsd-map-codebase --fast`로 handoff해야 합니다. fast 맵 readiness는 부분 상태이며 `/gsd-new-project`에 충분한 것으로 취급해서는 안 됩니다.
+- REQ-ONBOARD-03: ADR/PRD/SPEC/RFC 후보가 있고 project가 없으면 `/gsd-new-project` 전에 `/gsd-ingest-docs`를 제안해야 합니다.
+- REQ-ONBOARD-04: `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`가 모두 있을 때까지 완료로 보고하지 않아야 합니다.
+- REQ-ONBOARD-05: project setup 후에만 `.planning/onboarding/SUMMARY.md`를 만들거나 확인해야 합니다.
+- REQ-ONBOARD-06: 대화형 메뉴가 없는 runtime을 위해 `--text` 번호형 plain-text gate를 지원해야 합니다.
+
+**생성 산출물.**
+| 산출물 | 설명 |
+|----------|-------------|
+| `.planning/codebase/` | `/gsd-map-codebase` handoff가 생성한 코드베이스 맵 |
+| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` | `/gsd-new-project` 또는 `/gsd-ingest-docs`가 생성한 planning setup |
+| `.planning/onboarding/SUMMARY.md` | Onboarding status, artifact index, next-command summary |
+
 ---

 ## 유틸리티 기능
--- a/docs/ko-KR/INVENTORY.md
+++ b/docs/ko-KR/INVENTORY.md
@@ -78,6 +78,7 @@
 | 명령어 | 역할 | 소스 |
 |---------|------|--------|
 | `/gsd-new-project` | 심층 컨텍스트 수집 및 PROJECT.md로 새 프로젝트 초기화. | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
+| `/gsd-onboard` | 기존 코드베이스를 매핑, 문서 수집, 프로젝트 설정, onboarding summary로 안내합니다. | [commands/gsd/onboard.md](../../commands/gsd/onboard.md) |
 | `/gsd-workspace` | GSD 워크스페이스 관리 — 격리된 워크스페이스 환경을 생성(`--new`), 목록(`--list`), 또는 제거(`--remove`). | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
 | `/gsd-discuss-phase` | 계획 전 적응형 질문을 통한 단계 컨텍스트 수집. | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
 | `/gsd-mvp-phase` | 수직 MVP 슬라이스로 단계 계획 — 사용자 스토리, SPIDR 분할, 이후 plan-phase. | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
@@ -218,6 +219,7 @@
 | `milestone-summary.md` | 마일스톤 아티팩트에서 온보딩 및 검토용 마일스톤 요약 합성. | `/gsd-milestone-summary` |
 | `new-milestone.md` | 새 마일스톤 사이클 시작 — 프로젝트 컨텍스트 로드, 목표 수집, PROJECT.md/STATE.md 업데이트. | `/gsd-new-milestone` |
 | `new-project.md` | 통합 새 프로젝트 플로우 — 질문, 조사(선택), 요구사항, 로드맵. | `/gsd-new-project` |
+| `onboard.md` | Brownfield 온보딩 오케스트레이션 — 코드베이스 매핑, 문서 수집, planning 초기화, 다음 단계 요약. | `/gsd-onboard` |
 | `new-workspace.md` | 저장소 워크트리/클론과 독립적인 `.planning/`이 포함된 격리된 워크스페이스 생성. | `/gsd-workspace --new` |
 | `next.md` | 현재 프로젝트 상태를 감지하고 다음 논리적 단계로 자동 진행. | `/gsd-progress --next` |
 | `node-repair.md` | 실패한 태스크 검증을 위한 자율 수리 오퍼레이터; `execute-plan`에 의해 호출. | `execute-plan.md` (복구) |
--- a/docs/ko-KR/USER-GUIDE.md
+++ b/docs/ko-KR/USER-GUIDE.md
@@ -474,8 +474,8 @@ claude --dangerously-skip-permissions
 ### 기존 코드베이스

 ```bash
-/gsd-map-codebase           # Analyse what exists (parallel agents)
-/gsd-new-project            # Questions focus on what you're ADDING
+/gsd-onboard                # Safely map, ingest docs, and initialize planning
+# Follow printed handoff commands, then rerun /gsd-onboard
 # (normal phase workflow from here)
 ```

@@ -864,7 +864,8 @@ All subagent/executor commits MUST use `--no-verify`.
    themes/
      default.css         # Shared CSS variables for all sketches
    MANIFEST.md           # Index of all sketches with winners
-  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
+  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
+  onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Atomic execution plans
--- a/docs/ko-KR/how-to/install-on-your-runtime.md
+++ b/docs/ko-KR/how-to/install-on-your-runtime.md
@@ -273,10 +273,11 @@ npx @opengsd/gsd-core@latest --opencode --global

 ## 설치 후

-새 명령과 에이전트를 적용하려면 런타임을 재시작하세요. 그런 다음 첫 번째 프로젝트를 시작합니다:
+새 명령과 에이전트를 적용하려면 런타임을 재시작하세요. 그런 다음 새 프로젝트를 시작하거나 기존 저장소를 온보딩합니다:

 ```bash
-/gsd-new-project
+/gsd-new-project   # 그린필드 프로젝트
+/gsd-onboard       # 기존 코드베이스
 ```

 재시작 후 명령을 찾을 수 없다면 설치 디렉터리가 런타임이 기대하는 설정 경로와 일치하는지 확인하세요. 위의 프리릴리스 에디션 섹션에서 가장 흔한 불일치 사례를 다룹니다.
--- a/docs/ko-KR/reference/planning-artifacts.md
+++ b/docs/ko-KR/reference/planning-artifacts.md
@@ -23,6 +23,8 @@
 │   ├── architecture.md
 │   ├── stack.md
 │   └── ...
+├── onboarding/                         # 브라운필드 온보딩 요약 (선택)
+│   └── SUMMARY.md
 ├── intel/                              # 쿼리 가능한 심볼 인덱스 (선택, intel.enabled)
 │   └── API-SURFACE.md
 └── phases/
@@ -48,7 +50,7 @@
 | | |
 |---|---|
 | **목적** | 표준 프로젝트 아이덴티티: 무엇인지, 누구를 위한 것인지, 핵심 가치, 요구사항, 제약 사항, 주요 결정. 제품이 발전함에 따라 프로젝트 생명주기 전반에 걸쳐 업데이트됩니다. |
-| **생성자** | `/gsd-new-project` (최초 생성); 결정이 검증됨에 따라 `/gsd-complete-milestone`에 의해 업데이트됩니다. |
+| **생성자** | `/gsd-new-project` (최초 생성, `/gsd-onboard` handoff 포함); 결정이 검증됨에 따라 `/gsd-complete-milestone`에 의해 업데이트됩니다. |
 | **소비자** | 모든 플래닝 워크플로; `gsd-phase-researcher`, `gsd-planner` (컨텍스트); `discuss-phase` (이전 결정); `gsd-plan-checker` (프로젝트 제약 사항). |

 ### `ROADMAP.md`
@@ -56,7 +58,7 @@
 | | |
 |---|---|
 | **목적** | 목표, 요구사항 ID, 성공 기준, 페이즈별 표준 참조가 있는 마일스톤 및 페이즈 목록. 프로젝트가 무엇을 빌드하고 어떤 순서로 하는지에 대한 단일 진실의 원천. |
-| **생성자** | `/gsd-new-project` (최초 생성); `/gsd-phase --insert`와 `/gsd-complete-milestone`에 의해 업데이트됩니다. |
+| **생성자** | `/gsd-new-project` (최초 생성, `/gsd-onboard` handoff 포함); `/gsd-phase --insert`와 `/gsd-complete-milestone`에 의해 업데이트됩니다. |
 | **소비자** | `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`; 페이즈 정보가 필요한 모든 오케스트레이션 명령; `gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`. |

 ### `REQUIREMENTS.md`
@@ -64,7 +66,7 @@
 | | |
 |---|---|
 | **목적** | 프로젝트의 번호가 매겨진 체크 가능한 인수 기준. 각 요구사항은 로드맵 페이즈에 매핑되는 ID(예: `AUTH-01`)를 가집니다. 페이즈가 실행됨에 따라 요구사항을 완료로 표시합니다. |
-| **생성자** | `/gsd-new-project` (최초 생성); `execute-phase`에 의해 요구사항이 완료로 표시됩니다. |
+| **생성자** | `/gsd-new-project` (최초 생성, `/gsd-onboard` handoff 포함); `execute-phase`에 의해 요구사항이 완료로 표시됩니다. |
 | **소비자** | `gsd-planner` (플랜은 모든 페이즈 요구사항 ID를 처리해야 함); `gsd-plan-checker` Dimension 1 (요구사항 커버리지); `discuss-phase` (이전 요구사항). |

 ### `STATE.md`
@@ -72,7 +74,7 @@
 | | |
 |---|---|
 | **목적** | 살아있는 위치 추적기 — 현재 페이즈와 플랜, 진행 지표, 누적된 결정, 세션 연속성 노트. 모든 워크플로 실행 시작 시 읽힙니다. 중요한 작업 이후 업데이트됩니다. |
-| **생성자** | `/gsd-new-project` (최초 생성); 모든 페이즈 워크플로, `/gsd-pause-work`, `/gsd-resume-work`에 의해 지속적으로 업데이트됩니다. |
+| **생성자** | `/gsd-new-project` (최초 생성, `/gsd-onboard` handoff 포함); 모든 페이즈 워크플로, `/gsd-pause-work`, `/gsd-resume-work`에 의해 지속적으로 업데이트됩니다. |
 | **소비자** | 모든 오케스트레이션 워크플로; `/gsd-progress`; `/gsd-quick`을 통한 임시 태스크 실행; `gsd-planner` 및 `gsd-phase-researcher` (프로젝트 결정). |

 전체 필드 참조는 [STATE.md 스키마](state-md.md)를 참조하세요.
@@ -87,6 +89,14 @@

 전체 스키마는 [CONFIGURATION](../../CONFIGURATION.md)을 참조하세요.

+### `onboarding/SUMMARY.md` (선택)
+
+| | |
+|---|---|
+| **목적** | 브라운필드 온보딩 인덱스. 아티팩트 상태, 코드베이스 매핑 완료 여부, 초기 설정 후 권장되는 다음 GSD 명령을 기록합니다. |
+| **생성자** | `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`가 모두 존재한 뒤 `/gsd-onboard`. |
+| **소비자** | 초기 설정을 검토하는 사람; 기존 온보딩 상태를 확인하는 향후 `/gsd-onboard` 실행. |
+
 ### `MILESTONES.md` (선택)

 | | |
--- a/docs/ko-KR/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/ko-KR/tutorials/onboarding-an-existing-codebase.md
@@ -44,15 +44,15 @@ claude --dangerously-skip-permissions

 ---

-## Step 3 — 코드베이스 매핑
+## Step 3 — 브라운필드 온보딩 시작

-프로젝트를 생성하기 전에 GSD Core가 이미 존재하는 것을 학습하도록 합니다. 이 단계가 브라운필드 계획의 정확도를 높이는 핵심입니다.
+프로젝트를 생성하기 전에 GSD Core가 저장소 상태를 검사하고 안전한 다음 top-level 명령을 알려주게 하세요. 이 단계는 코드베이스 컨텍스트를 건너뛰거나 기존 planning 파일을 덮어쓰는 일을 방지합니다.

 ```text
-/gsd-map-codebase
+/gsd-onboard
 ```

-GSD Core가 4개의 병렬 매퍼 서브 에이전트를 생성합니다("Spawning 4 parallel codebase mapper agents…" 메시지가 표시되며, 1–5분 소요됩니다. 중단하지 마세요). 각 에이전트는 서로 다른 관심사에 집중합니다:
+온보딩이 코드베이스 맵 누락을 보고하면 권장 옵션을 선택하고 출력된 `/gsd-map-codebase` handoff를 실행한 뒤 `/gsd-onboard`를 다시 실행합니다. `/gsd-onboard --fast`는 가벼운 첫 패스에는 충분하지만, `/gsd-new-project` 전에는 완전한 맵이 필요합니다. `/gsd-map-codebase`가 4개의 병렬 매퍼 서브 에이전트를 생성합니다("Spawning 4 parallel codebase mapper agents…" 메시지가 표시되며, 1–5분 소요됩니다. 중단하지 마세요). 각 에이전트는 서로 다른 관심사에 집중합니다:

 | 에이전트 | 집중 영역 |
 |---------|---------|
@@ -84,7 +84,7 @@ Created .planning/codebase/:

 ---

-## Step 4 — 컨텍스트 초기화 후 프로젝트 생성
+## Step 4 — 온보딩 재실행 및 프로젝트 초기화

 세션 창을 초기화합니다:

@@ -92,7 +92,7 @@ Created .planning/codebase/:
 /clear
 ```

-이제 프로젝트를 생성합니다. GSD Core가 이전 단계에서 기존 코드를 발견했으므로, 이미 이것이 브라운필드 프로젝트임을 알고 있습니다. `/gsd-new-project`를 실행하면 기존의 것을 재구성하는 것이 아니라 *추가하는* 것에 집중한 질문을 합니다:
+이제 `/gsd-onboard`를 다시 실행합니다. GSD Core가 ADR, PRD, spec, RFC 또는 루트 요구사항 문서를 감지하면 먼저 권장되는 `/gsd-ingest-docs` handoff를 실행하고 이후 `/gsd-onboard`를 다시 실행하세요. 컨텍스트가 준비되면 온보딩이 프로젝트 초기화 handoff를 출력합니다:

 ```text
 /gsd-new-project
@@ -124,6 +124,8 @@ Proposed Roadmap

 로드맵을 승인합니다.

+프로젝트 설정이 끝난 뒤 `/gsd-onboard`를 한 번 더 실행합니다. 이제 `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`가 모두 있으므로 온보딩은 `.planning/onboarding/SUMMARY.md`를 생성하거나 확인합니다.
+
 **`.planning/`에 생성되는 파일:**

 ```text
@@ -133,6 +135,7 @@ Proposed Roadmap
  ROADMAP.md          ← Phase 1, 상태: pending
  STATE.md            ← 세션 메모리
  config.json         ← 워크플로 설정
+  onboarding/SUMMARY.md ← 온보딩 상태와 다음 명령
  codebase/           ← Step 3에서 생성된 7개의 맵 파일
 ```

@@ -212,6 +215,7 @@ GSD Core가 `CONVENTIONS.md`와 `ARCHITECTURE.md`를 읽었으므로, 질문들

 ## 배운 내용

+- `/gsd-onboard`가 인터랙티브 명령을 중첩하거나 기존 planning 파일을 덮어쓰지 않고 브라운필드 설정을 안전하게 순서화하는 방법.
 - `/gsd-map-codebase`가 4개의 병렬 에이전트를 실행하여 `.planning/codebase/`에 `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md`, `INTEGRATIONS.md`를 생성하는 방법.
 - 브라운필드 저장소에서 `/gsd-new-project`가 *추가하는* 것에 집중한 질문을 하고 기존 코드에서 Validated 요구사항을 채우는 방법.
 - 코드베이스 맵이 `/gsd-discuss-phase`의 모든 질문을 형성하는 방법 — 파일 경로, 패턴, 컨벤션이 실제 코드에서 옵니다.
--- a/docs/pt-BR/ARCHITECTURE.md
+++ b/docs/pt-BR/ARCHITECTURE.md
@@ -527,7 +527,8 @@ Caminhos equivalentes para outros runtimes:
 │   ├── FEATURES.md
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
-├── codebase/               # Mapeamento de brownfield (do /gsd-map-codebase)
+├── codebase/               # Mapeamento de brownfield (do /gsd-map-codebase ou /gsd-onboard)
+├── onboarding/             # Resumo de onboarding brownfield (do /gsd-onboard)
 │   ├── STACK.md            # Frontmatter YAML carrega `last_mapped_commit`
 │   ├── ARCHITECTURE.md     # para o portão de desvio pós-execução (#2003)
 │   ├── CONVENTIONS.md
--- a/docs/pt-BR/CLI-TOOLS.md
+++ b/docs/pt-BR/CLI-TOOLS.md
@@ -290,13 +290,14 @@ node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"

 ## Comandos Init (Carregamento de Contexto Composto)

-Carrega todo o contexto necessário para um fluxo de trabalho específico em uma única chamada. Retorna JSON com informações do projeto, configuração, estado e dados específicos do fluxo de trabalho.
+Carrega todo o contexto necessário para um fluxo de trabalho específico em uma única chamada. Retorna JSON com informações do projeto, configuração, estado e dados específicos do fluxo de trabalho. `init onboard [--fast] [--text]` retorna, para `/gsd-onboard`, sinais de brownfield, candidatos a docs de planning, completude do mapa de código, prontidão do mapa fast, roteamento em modo texto, estado parcial de planning e status do resumo de onboarding.

 ```bash
 node gsd-tools.cjs init execute-phase <phase>
 node gsd-tools.cjs init plan-phase <phase>
 node gsd-tools.cjs init new-project
 node gsd-tools.cjs init new-milestone
+node gsd-tools.cjs init onboard [--fast] [--text]
 node gsd-tools.cjs init quick <description>
 node gsd-tools.cjs init resume
 node gsd-tools.cjs init verify-work <phase>
--- a/docs/pt-BR/COMMANDS.md
+++ b/docs/pt-BR/COMMANDS.md
@@ -51,6 +51,25 @@ Inicializa um novo projeto com coleta aprofundada de contexto.

 ---

+### `/gsd-onboard`
+
+Guia o onboarding inicial de um código existente no GSD. O comando verifica o estado do repositório, encaminha com segurança por mapeamento da base de código, ingestão opcional de documentos, inicialização do projeto e cria um onboarding summary quando o planejamento existe.
+
+| Flag | Descrição |
+|------|-----------|
+| `--fast` | Prefere o handoff leve `/gsd-map-codebase --fast`; um mapa completo ainda é necessário antes de `/gsd-new-project` |
+| `--text` | Usa gates numerados em texto puro em vez de menus TUI |
+
+**Pré-requisitos:** Repositório existente ou documentos de planejamento. Para projetos greenfield vazios, use `/gsd-new-project`.
+**Produz:** `.planning/codebase/` via map-codebase, `.planning/` via new-project ou ingest-docs, e `.planning/onboarding/SUMMARY.md` após a configuração do projeto.
+
+```bash
+/gsd-onboard           # Onboarding brownfield guiado
+/gsd-onboard --fast    # Usa primeiro o mapa leve e depois completa o mapa antes do setup do projeto
+```
+
+---
+
 ### `/gsd-workspace`

 Gerencia workspaces do GSD — cria, lista ou remove ambientes de workspace isolados com cópias de repositório e diretórios `.planning/` independentes.
--- a/docs/pt-BR/FEATURES.md
+++ b/docs/pt-BR/FEATURES.md
@@ -14,7 +14,7 @@ Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em ingl
 - **Commits atômicos por tarefa** para rastreabilidade e rollback
 - **Verificação pós-execução** com foco em objetivos da fase
 - **UAT guiado** via `/gsd-verify-work`
- **Suporte brownfield** com `/gsd-map-codebase`
+- **Suporte brownfield** com `/gsd-onboard` e `/gsd-map-codebase`
 - **Workstreams** para trilhas paralelas sem colisão de estado
 - **Backlog, seeds e threads** para memória de médio/longo prazo

@@ -68,7 +68,7 @@ Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em ingl
 |--------|----------|
 | Projeto novo | `/gsd-new-project` -> `/gsd-discuss-phase` -> `/gsd-plan-phase` -> `/gsd-execute-phase` |
 | Correção rápida | `/gsd-quick` |
-| Código existente | `/gsd-map-codebase` -> `/gsd-new-project` |
+| Código existente | `/gsd-onboard` -> handoffs para `/gsd-map-codebase`, `/gsd-ingest-docs`, `/gsd-new-project` |
 | Fechamento de release | `/gsd-audit-milestone` -> `/gsd-complete-milestone` |

 ---
--- a/docs/pt-BR/INVENTORY.md
+++ b/docs/pt-BR/INVENTORY.md
@@ -78,6 +78,7 @@ Esses seis roteadores são entradas apenas descritivas que o modelo seleciona pr
 | Comando | Função | Fonte |
 |---------|--------|-------|
 | `/gsd-new-project` | Inicializa um novo projeto com coleta profunda de contexto e PROJECT.md. | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
+| `/gsd-onboard` | Guia código existente por mapeamento, ingestão de docs, configuração de projeto e onboarding summary. | [commands/gsd/onboard.md](../../commands/gsd/onboard.md) |
 | `/gsd-workspace` | Gerencia workspaces GSD — criar (`--new`), listar (`--list`) ou remover (`--remove`) ambientes de workspace isolados. | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
 | `/gsd-discuss-phase` | Coleta contexto da fase por meio de perguntas adaptativas antes do planejamento. | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
 | `/gsd-mvp-phase` | Planeja uma fase como uma fatia vertical de MVP — história de usuário, divisão SPIDR, depois plan-phase. | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
@@ -218,6 +219,7 @@ Registro completo em `get-shit-done/workflows/*.md`. Workflows são orquestrador
 | `milestone-summary.md` | Síntese do resumo do milestone — artefato de onboarding e revisão a partir dos artefatos do milestone. | `/gsd-milestone-summary` |
 | `new-milestone.md` | Inicia um novo ciclo de milestone — carregar contexto do projeto, coletar objetivos, atualizar PROJECT.md/STATE.md. | `/gsd-new-milestone` |
 | `new-project.md` | Fluxo unificado de novo projeto — questionamento, pesquisa (opcional), requisitos, roadmap. | `/gsd-new-project` |
+| `onboard.md` | Orquestração de onboarding brownfield — mapear código, ingerir docs, inicializar planning e resumir próximo passo. | `/gsd-onboard` |
 | `new-workspace.md` | Cria um workspace isolado com worktrees/clones do repositório e um `.planning/` independente. | `/gsd-workspace --new` |
 | `next.md` | Detecta o estado atual do projeto e avança automaticamente para o próximo passo lógico. | `/gsd-progress --next` |
 | `node-repair.md` | Operador de reparo autônomo para verificação de tarefa com falha; invocado por `execute-plan`. | `execute-plan.md` (recuperação) |
--- a/docs/pt-BR/USER-GUIDE.md
+++ b/docs/pt-BR/USER-GUIDE.md
@@ -474,8 +474,8 @@ claude --dangerously-skip-permissions
 ### Base de código existente

 ```bash
-/gsd-map-codebase           # Analyse what exists (parallel agents)
-/gsd-new-project            # Questions focus on what you're ADDING
+/gsd-onboard                # Safely map, ingest docs, and initialize planning
+# Follow printed handoff commands, then rerun /gsd-onboard
 # (normal phase workflow from here)
 ```

@@ -864,7 +864,8 @@ Para desativar a execução paralela completamente: `/gsd-settings` → defina `
    themes/
      default.css         # Shared CSS variables for all sketches
    MANIFEST.md           # Index of all sketches with winners
-  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
+  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
+  onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Atomic execution plans
--- a/docs/pt-BR/how-to/install-on-your-runtime.md
+++ b/docs/pt-BR/how-to/install-on-your-runtime.md
@@ -273,10 +273,11 @@ npx @opengsd/gsd-core@latest --opencode --global

 ## Após a instalação

-Reinicie seu ambiente para carregar os novos comandos e agentes. Em seguida, inicie seu primeiro projeto:
+Reinicie seu ambiente para carregar os novos comandos e agentes. Em seguida, inicie um projeto novo ou faça onboarding de um repositório existente:

 ```bash
-/gsd-new-project
+/gsd-new-project   # projeto greenfield
+/gsd-onboard       # base de código existente
 ```

 Se o comando não for encontrado após o reinício, verifique se o diretório de instalação corresponde ao caminho de configuração esperado pelo ambiente. A seção de edições de pré-lançamento acima cobre a incompatibilidade mais comum.
--- a/docs/pt-BR/reference/planning-artifacts.md
+++ b/docs/pt-BR/reference/planning-artifacts.md
@@ -23,6 +23,8 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
 │   ├── architecture.md
 │   ├── stack.md
 │   └── ...
+├── onboarding/                         # Resumo de onboarding brownfield (opcional)
+│   └── SUMMARY.md
 ├── intel/                              # Índice de símbolos consultável (opcional, intel.enabled)
 │   └── API-SURFACE.md
 └── phases/
@@ -48,7 +50,7 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
 | | |
 |---|---|
 | **Finalidade** | Identidade canônica do projeto: o que é, para quem é, valor central, requisitos, restrições e decisões-chave. Atualizado ao longo do ciclo de vida do projeto conforme o produto evolui. |
-| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado por `/gsd-complete-milestone` à medida que as decisões são validadas. |
+| **Produzido por** | `/gsd-new-project` (criação inicial, incluindo handoff do `/gsd-onboard`); atualizado por `/gsd-complete-milestone` à medida que as decisões são validadas. |
 | **Consumido por** | Todos os fluxos de trabalho de planejamento; `gsd-phase-researcher`, `gsd-planner` (contexto); `discuss-phase` (decisões anteriores); `gsd-plan-checker` (restrições do projeto). |

 ### `ROADMAP.md`
@@ -56,7 +58,7 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
 | | |
 |---|---|
 | **Finalidade** | Listagem de marcos e fases com objetivos, IDs de requisitos, critérios de sucesso e referências canônicas por fase. A fonte única de verdade sobre o que o projeto está construindo e em que ordem. |
-| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado por `/gsd-phase --insert` e `/gsd-complete-milestone`. |
+| **Produzido por** | `/gsd-new-project` (criação inicial, incluindo handoff do `/gsd-onboard`); atualizado por `/gsd-phase --insert` e `/gsd-complete-milestone`. |
 | **Consumido por** | `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`; todos os comandos de orquestração que precisam de informações de fase; `gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`. |

 ### `REQUIREMENTS.md`
@@ -64,7 +66,7 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
 | | |
 |---|---|
 | **Finalidade** | Critérios de aceitação numerados e verificáveis para o projeto. Cada requisito possui um ID (ex.: `AUTH-01`) que mapeia para as fases do roadmap. Marca os requisitos como concluídos conforme as fases são executadas. |
-| **Produzido por** | `/gsd-new-project` (criação inicial); requisitos marcados como concluídos por `execute-phase`. |
+| **Produzido por** | `/gsd-new-project` (criação inicial, incluindo handoff do `/gsd-onboard`); requisitos marcados como concluídos por `execute-phase`. |
 | **Consumido por** | `gsd-planner` (os planos devem contemplar todos os IDs de requisitos da fase); `gsd-plan-checker` Dimensão 1 (cobertura de requisitos); `discuss-phase` (requisitos anteriores). |

 ### `STATE.md`
@@ -72,7 +74,7 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
 | | |
 |---|---|
 | **Finalidade** | Rastreador de posição em andamento — fase e plano atuais, métricas de progresso, decisões acumuladas, notas de continuidade de sessão. Lido no início de toda execução de fluxo de trabalho. Atualizado após cada ação significativa. |
-| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado continuamente por todos os fluxos de fase, `/gsd-pause-work`, `/gsd-resume-work`. |
+| **Produzido por** | `/gsd-new-project` (criação inicial, incluindo handoff do `/gsd-onboard`); atualizado continuamente por todos os fluxos de fase, `/gsd-pause-work`, `/gsd-resume-work`. |
 | **Consumido por** | Todos os fluxos de orquestração; `/gsd-progress`; execução de tarefas avulsas via `/gsd-quick`; `gsd-planner` e `gsd-phase-researcher` (decisões do projeto). |

 Consulte o [esquema de STATE.md](state-md.md) para a referência completa de campos.
@@ -87,6 +89,14 @@ Consulte o [esquema de STATE.md](state-md.md) para a referência completa de cam

 Consulte [CONFIGURATION](../CONFIGURATION.md) para o esquema completo.

+### `onboarding/SUMMARY.md` (opcional)
+
+| | |
+|---|---|
+| **Finalidade** | Índice de onboarding brownfield que registra status dos artefatos, se o mapeamento do código-base está completo e o próximo comando GSD recomendado após a configuração inicial. |
+| **Produzido por** | `/gsd-onboard` depois que `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md` e `STATE.md` existem. |
+| **Consumido por** | Humanos revisando a configuração inicial; futuras execuções de `/gsd-onboard` ao confirmar o estado de onboarding existente. |
+
 ### `MILESTONES.md` (opcional)

 | | |
--- a/docs/pt-BR/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/pt-BR/tutorials/onboarding-an-existing-codebase.md
@@ -44,15 +44,15 @@ claude --dangerously-skip-permissions

 ---

-## Passo 3 — Mapear a base de código
+## Passo 3 — Iniciar o onboarding brownfield

-Antes de criar um projeto, deixe o GSD Core aprender o que já existe. Este é o passo que torna o planejamento brownfield preciso.
+Antes de criar um projeto, deixe o GSD Core inspecionar o estado do repositório e indicar o próximo comando de nível superior seguro. Este passo evita pular contexto de código ou sobrescrever arquivos de planning existentes.

 ```text
-/gsd-map-codebase
+/gsd-onboard
 ```

-O GSD Core cria quatro sub-agentes mapeadores paralelos (você verá "Spawning 4 parallel codebase mapper agents…" — isso leva de 1 a 5 minutos; não interrompa). Cada agente foca em uma preocupação diferente:
+Se o onboarding informar que o mapa da base de código está ausente, escolha a opção recomendada e execute o handoff `/gsd-map-codebase` impresso antes de rodar `/gsd-onboard` novamente. `/gsd-onboard --fast` serve para uma primeira passada leve, mas um mapa completo ainda é necessário antes de `/gsd-new-project`. O `/gsd-map-codebase` cria quatro sub-agentes mapeadores paralelos (você verá "Spawning 4 parallel codebase mapper agents…" — isso leva de 1 a 5 minutos; não interrompa). Cada agente foca em uma preocupação diferente:

 | Agente | Foco |
 |--------|------|
@@ -84,7 +84,7 @@ Abra `.planning/codebase/CONCERNS.md`. Este é o arquivo mais útil para ler ant

 ---

-## Passo 4 — Limpar o contexto e criar o projeto
+## Passo 4 — Reexecutar o onboarding e inicializar o projeto

 Limpe a janela de sessão:

@@ -92,12 +92,14 @@ Limpe a janela de sessão:
 /clear
 ```

-Agora crie o projeto. Como o GSD Core encontrou código existente no passo anterior, já sabe que se trata de um projeto brownfield. Quando você executa `/gsd-new-project`, as perguntas focam no que você está *adicionando*, e não em reconstruir o que já existe:
+Agora execute `/gsd-onboard` novamente. Se o GSD Core detectar ADRs, PRDs, specs, RFCs ou requisitos de nível raiz, aceite o handoff recomendado para `/gsd-ingest-docs` primeiro e depois rode `/gsd-onboard` de novo. Quando o contexto estiver pronto, o onboarding imprimirá o handoff de inicialização:

 ```text
 /gsd-new-project
 ```

+Como o GSD Core encontrou código existente no passo anterior, `/gsd-new-project` sabe que é um projeto brownfield. As perguntas focam no que você está *adicionando*, não em reconstruir o que já existe:
+
 O GSD Core pergunta o que você quer construir. Responda com o recurso que está adicionando, e não com uma descrição de toda a base de código:

 ```text
@@ -124,6 +126,8 @@ Proposed Roadmap

 Aprove o roteiro.

+Execute `/gsd-onboard` mais uma vez depois que a configuração do projeto terminar. Agora que `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md` e `STATE.md` existem, o onboarding cria ou confirma `.planning/onboarding/SUMMARY.md`.
+
 **O que é criado em `.planning/`:**

 ```text
@@ -133,6 +137,7 @@ Aprove o roteiro.
  ROADMAP.md          ← Fase 1, status: pending
  STATE.md            ← memória de sessão
  config.json         ← configurações do fluxo de trabalho
+  onboarding/SUMMARY.md ← status do onboarding e próximo comando
  codebase/           ← os sete arquivos de mapa do Passo 3
 ```

@@ -212,6 +217,7 @@ Para cada recurso futuro, execute `/gsd-map-codebase` novamente sempre que a est

 ## O que você aprendeu

+- Como `/gsd-onboard` sequencia com segurança o setup brownfield sem aninhar comandos interativos ou sobrescrever planning existente.
 - Como `/gsd-map-codebase` executa quatro agentes paralelos para produzir `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md` e `INTEGRATIONS.md` em `.planning/codebase/`.
 - Como `/gsd-new-project` em um repositório brownfield concentra as perguntas no que você está *adicionando* e preenche os requisitos Validated a partir do código existente.
 - Como o mapa da base de código orienta cada pergunta em `/gsd-discuss-phase` — caminhos de arquivos, padrões e convenções vêm do seu código real.
--- a/docs/reference/capability-matrix.md
+++ b/docs/reference/capability-matrix.md
@@ -44,7 +44,7 @@ Core package and are stamped with the package version at release (per
 ADR-1244 D6). They are not subject to the consent or integrity-pin flow applied
 to third-party capabilities.

-### Feature capabilities (role: feature) — 18
+### Feature capabilities (role: feature) — 19

 Feature capabilities extend what the loop does — contributing research,
 planning, execution, verification, or ship artefacts at the loop extension
@@ -55,6 +55,7 @@ points.
 | `ai-integration` | feature | full | `>=1.6.0` | `plan:pre` | step | first-party |
 | `assumption-delta` | feature | full | `>=1.6.0` | `plan:pre` | contribution | first-party |
 | `audit` | feature | full | `>=1.6.0` | — | — | first-party |
+| `claude-orchestration` | feature | full | `>=1.7.0` | `plan:post`, `execute:wave:post` | contribution | first-party |
 | `code-review` | feature | full | `>=1.6.0` | `execute:post` | step | first-party |
 | `drift` | feature | full | `>=1.6.0` | `plan:pre`, `execute:wave:post` | gate | first-party |
 | `external-job` | feature | full | `>=1.7.0` | `plan:post`, `execute:wave:post` | contribution | first-party |
--- a/docs/reference/planning-artifacts.md
+++ b/docs/reference/planning-artifacts.md
@@ -23,6 +23,8 @@ The `.planning/` directory is GSD Core's shared memory for a project. Every work
 │   ├── architecture.md
 │   ├── stack.md
 │   └── ...
+├── onboarding/                         # Brownfield onboarding summary (optional)
+│   └── SUMMARY.md
 ├── intel/                              # Queryable symbol index (optional, intel.enabled)
 │   └── API-SURFACE.md
 └── phases/
@@ -48,7 +50,7 @@ The `.planning/` directory is GSD Core's shared memory for a project. Every work
 | | |
 |---|---|
 | **Purpose** | Canonical project identity: what it is, who it is for, core value, requirements, constraints, and key decisions. Updated throughout the project lifecycle as the product evolves. |
-| **Produced by** | `/gsd-new-project` (initial creation); updated by `/gsd-complete-milestone` as decisions are validated. |
+| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); updated by `/gsd-complete-milestone` as decisions are validated. |
 | **Consumed by** | All planning workflows; `gsd-phase-researcher`, `gsd-planner` (context); `discuss-phase` (prior decisions); `gsd-plan-checker` (project constraints). |

 Includes an optional `## Business Context` section (Customer, Revenue model, Success metric, Strategy notes) for monetized or customer-facing projects — four one-line fields that connect business outcomes to requirement prioritization. It is deleted for internal tools, experiments, or meta workspaces, and reviewed at each milestone by `/gsd-complete-milestone` when present.
@@ -58,7 +60,7 @@ Includes an optional `## Business Context` section (Customer, Revenue model, Suc
 | | |
 |---|---|
 | **Purpose** | Milestone and phase listing with goals, requirement IDs, success criteria, and canonical references per phase. The single source of truth for what the project is building and in what order. |
-| **Produced by** | `/gsd-new-project` (initial creation); updated by `/gsd-phase --insert` and `/gsd-complete-milestone`. |
+| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); updated by `/gsd-phase --insert` and `/gsd-complete-milestone`. |
 | **Consumed by** | `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`; all orchestration commands that need phase information; `gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`. |

 ### `REQUIREMENTS.md`
@@ -66,7 +68,7 @@ Includes an optional `## Business Context` section (Customer, Revenue model, Suc
 | | |
 |---|---|
 | **Purpose** | Numbered, checkable acceptance criteria for the project. Each requirement carries an ID (e.g., `AUTH-01`) that maps to roadmap phases. Marks requirements complete as phases are executed. |
-| **Produced by** | `/gsd-new-project` (initial creation); requirements marked complete by `execute-phase`. |
+| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); requirements marked complete by `execute-phase`. |
 | **Consumed by** | `gsd-planner` (plans must address all phase requirement IDs); `gsd-plan-checker` Dimension 1 (requirement coverage); `discuss-phase` (prior requirements). |

 ### `STATE.md`
@@ -74,7 +76,7 @@ Includes an optional `## Business Context` section (Customer, Revenue model, Suc
 | | |
 |---|---|
 | **Purpose** | Living position tracker — current phase and plan, progress metrics, accumulated decisions, session continuity notes. Read at the start of every workflow run. Updated after every significant action. |
-| **Produced by** | `/gsd-new-project` (initial creation); updated continuously by all phase workflows, `/gsd-pause-work`, `/gsd-resume-work`. |
+| **Produced by** | `/gsd-new-project` (initial creation, including `/gsd-onboard` handoff); updated continuously by all phase workflows, `/gsd-pause-work`, `/gsd-resume-work`. |
 | **Consumed by** | All orchestration workflows; `/gsd-progress`; ad-hoc task execution via `/gsd-quick`; `gsd-planner` and `gsd-phase-researcher` (project decisions). |

 See [STATE.md schema](state-md.md) for the full field reference.
@@ -89,6 +91,14 @@ See [STATE.md schema](state-md.md) for the full field reference.

 See [CONFIGURATION](../CONFIGURATION.md) for the complete schema.

+### `onboarding/SUMMARY.md` (optional)
+
+| | |
+|---|---|
+| **Purpose** | Brownfield onboarding index that records artifact status, whether codebase mapping is complete, and the next recommended GSD command after first-time setup. |
+| **Produced by** | `/gsd-onboard` after `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist. |
+| **Consumed by** | Humans reviewing first-time setup; future `/gsd-onboard` runs when confirming existing onboarding state. |
+
 ### `MILESTONES.md` (optional)

 | | |
--- a/docs/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/tutorials/onboarding-an-existing-codebase.md
@@ -44,15 +44,21 @@ claude --dangerously-skip-permissions

 ---

-## Step 3 — Map the codebase
+## Step 3 — Start brownfield onboarding

-Before creating a project, let GSD Core learn what already exists. This is the step that makes brownfield planning accurate.
+Before creating a project, let GSD Core inspect the repo state and tell you the safe next top-level command. This is the step that prevents brownfield setup from skipping codebase context or overwriting existing planning files.
+
+```text
+/gsd-onboard
+```
+
+If code exists and `.planning/codebase/` is missing, GSD Core asks you to map the codebase first. Choose the recommended mapping option, then run the printed handoff command:

 ```text
 /gsd-map-codebase
 ```

-GSD Core spawns four parallel mapper sub-agents (you'll see "Spawning 4 parallel codebase mapper agents…" — this takes 1–5 minutes; do not interrupt). Each agent focuses on a different concern:
+Use `/gsd-onboard --fast` if you want the onboarding gate to prefer `/gsd-map-codebase --fast` for a lighter first pass. Fast mode is only enough for lightweight onboarding; `/gsd-onboard` still sends you back to the full mapper before `/gsd-new-project`. The full mapper spawns four parallel mapper sub-agents (you'll see "Spawning 4 parallel codebase mapper agents…" — this takes 1–5 minutes; do not interrupt). Each agent focuses on a different concern:

 | Agent | Focus |
 |-------|-------|
@@ -84,7 +90,7 @@ Open `.planning/codebase/CONCERNS.md`. This is the most useful file to read befo

 ---

-## Step 4 — Clear context and create the project
+## Step 4 — Rerun onboarding and initialize the project

 Clear the session window:

@@ -92,12 +98,20 @@ Clear the session window:
 /clear
 ```

-Now create the project. Because GSD Core found existing code in the last step, it already knows this is a brownfield project. When you run `/gsd-new-project`, the questions focus on what you are *adding*, not rebuilding what already exists:
+Now rerun onboarding:
+
+```text
+/gsd-onboard
+```
+
+If GSD Core detects ADRs, PRDs, specs, RFCs, or top-level requirements docs, choose the recommended docs-ingest handoff first and rerun `/gsd-onboard` afterward. Once codebase context and any existing docs are handled, onboarding prints the project-initialization handoff:

 ```text
 /gsd-new-project
 ```

+Because GSD Core found existing code in the previous step, `/gsd-new-project` knows this is a brownfield project. The questions focus on what you are *adding*, not rebuilding what already exists:
+
 GSD Core asks what you want to build. Answer with the feature you are adding, not a description of the whole codebase:

 ```text
@@ -138,6 +152,20 @@ Approve the roadmap.

 Notice that `.planning/codebase/` is already there from Step 3. GSD Core read those files when writing `PROJECT.md`, which is why it could populate the Validated requirements without you describing them.

+Run onboarding one more time after project setup completes:
+
+```text
+/gsd-onboard
+```
+
+Now that `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist, onboarding creates or confirms:
+
+```text
+.planning/onboarding/SUMMARY.md
+```
+
+This summary is a lightweight index of the setup artifacts and the next command to run.
+
 ---

 ## Step 5 — Clear context and discuss Phase 1
@@ -206,12 +234,13 @@ You now have a project with a codebase map, a discuss decision record, and verif
 /gsd-ship 1
 ```

-For every future feature, run `/gsd-map-codebase` again whenever the structure changes significantly, so the codebase map stays fresh.
+For every future feature, run `/gsd-map-codebase` again whenever the structure changes significantly, so the codebase map stays fresh. Rerun `/gsd-onboard` only when you want to re-check first-time setup completeness or regenerate the onboarding summary.

 ---

 ## What you've learned

+- How `/gsd-onboard` safely sequences brownfield setup without nesting interactive commands or overwriting existing planning files.
 - How `/gsd-map-codebase` runs four parallel agents to produce `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md`, and `INTEGRATIONS.md` in `.planning/codebase/`.
 - How `/gsd-new-project` in a brownfield repo focuses questions on what you are *adding* and populates Validated requirements from existing code.
 - How the codebase map shapes every question in `/gsd-discuss-phase` — file paths, patterns, and conventions come from your actual code.
@@ -222,5 +251,5 @@ For every future feature, run `/gsd-map-codebase` again whenever the structure c
 ## Related

 - [Your first project](your-first-project.md) — the full greenfield loop from install to PR
- [Map codebase via Commands](../COMMANDS.md) — all `/gsd-map-codebase` flags and subcommands
+- [Commands](../COMMANDS.md) — `/gsd-onboard`, plus all `/gsd-map-codebase` flags and subcommands
 - [Documentation index](../README.md)
--- a/docs/zh-CN/ARCHITECTURE.md
+++ b/docs/zh-CN/ARCHITECTURE.md
@@ -512,7 +512,8 @@ UI-SPEC.md (per phase) ───────────────────
 │   ├── FEATURES.md
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
-├── codebase/               # Brownfield mapping (from /gsd-map-codebase)
+├── codebase/               # Brownfield mapping (from /gsd-map-codebase or /gsd-onboard)
+├── onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
 │   ├── STACK.md            # YAML frontmatter carries `last_mapped_commit`
 │   ├── ARCHITECTURE.md     # for the post-execute drift gate (#2003)
 │   ├── CONVENTIONS.md
--- a/docs/zh-CN/CLI-TOOLS.md
+++ b/docs/zh-CN/CLI-TOOLS.md
@@ -288,13 +288,14 @@ node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"

 ## Init 命令（复合上下文加载）

-通过单次调用加载特定工作流所需的所有上下文。返回包含项目信息、配置、状态和工作流专属数据的 JSON。
+通过单次调用加载特定工作流所需的所有上下文。返回包含项目信息、配置、状态和工作流专属数据的 JSON。`init onboard [--fast] [--text]` 会为 `/gsd-onboard` 返回 brownfield 信号、planning 文档候选、代码库映射完整性、fast 映射就绪状态、文本模式路由、部分 planning 状态和 onboarding summary 状态。

 ```bash
 node gsd-tools.cjs init execute-phase <phase>
 node gsd-tools.cjs init plan-phase <phase>
 node gsd-tools.cjs init new-project
 node gsd-tools.cjs init new-milestone
+node gsd-tools.cjs init onboard [--fast] [--text]
 node gsd-tools.cjs init quick <description>
 node gsd-tools.cjs init resume
 node gsd-tools.cjs init verify-work <phase>
--- a/docs/zh-CN/COMMANDS.md
+++ b/docs/zh-CN/COMMANDS.md
@@ -51,6 +51,25 @@ v1.40 中，六个命名空间路由器作为第一阶段入口点随附发布

 ---

+### `/gsd-onboard`
+
+引导现有代码库完成首次 GSD 接入。该命令检查仓库状态，安全地转到代码库映射、可选文档摄取、项目初始化，并在规划文件齐备后创建 onboarding summary。
+
+| 标志 | 描述 |
+|------|-------------|
+| `--fast` | 优先使用轻量 `/gsd-map-codebase --fast` 映射交接；在 `/gsd-new-project` 前仍需要完整映射 |
+| `--text` | 使用编号纯文本关卡，而不是 TUI 菜单 |
+
+**前提条件：** 现有仓库或规划文档。空的绿地项目请使用 `/gsd-new-project`。
+**产出：** 由 map-codebase 生成的 `.planning/codebase/`，由 new-project 或 ingest-docs 生成的 `.planning/`，以及项目设置后的 `.planning/onboarding/SUMMARY.md`。
+
+```bash
+/gsd-onboard           # 引导式 brownfield 接入
+/gsd-onboard --fast    # 先使用轻量映射，并在项目设置前补全完整映射
+```
+
+---
+
 ### `/gsd-workspace`

 管理 GSD 工作区 — 创建、列出或移除隔离的工作区环境，包含仓库副本和独立的 `.planning/` 目录。
--- a/docs/zh-CN/FEATURES.md
+++ b/docs/zh-CN/FEATURES.md
@@ -38,6 +38,7 @@
  - [模型配置](#26-model-profiles)
 - [棕地功能](#brownfield-features)
  - [代码库映射](#27-codebase-mapping)
+  - [现有代码库接入](#27b-现有代码库接入)
 - [实用功能](#utility-features)
  - [调试系统](#28-debug-system)
  - [待办事项管理](#29-todo-management)
@@ -783,7 +784,7 @@

 **命令：** `/gsd-map-codebase [area]`

-**目的：** 在启动新项目之前分析现有代码库，使 GSD 了解已有内容。
+**目的：** 在启动新项目之前，或作为 `/gsd-onboard` 的映射交接，分析现有代码库，使 GSD 了解已有内容。

 **需求：**
 - REQ-MAP-01：系统必须为每个分析领域派生并行映射智能体
@@ -805,6 +806,27 @@

 **增量重映射 — `--paths` (#2003)：** 映射器接受可选的 `--paths <p1,p2,...>` 范围提示。提供时，它将探索限制在列出的仓库相对前缀，而非扫描整个代码树。这是执行后代码库漂移门控用于仅刷新阶段实际修改的子树的路径。每个生成的文档在其 YAML 前置元数据中携带 `last_mapped_commit`，以便相对于映射点（而非 HEAD）来测量漂移。

+### 27b. 现有代码库接入
+
+**命令：** `/gsd-onboard [--fast] [--text]`
+
+**目的：** 引导现有仓库完成首次设置，检查 brownfield 状态，并安全交接到代码库映射、docs 摄取和项目初始化。
+
+**需求：**
+- REQ-ONBOARD-01：系统必须检测现有代码、package manifest、规划文档、部分 `.planning/` 状态以及缺失的代码库映射文件。
+- REQ-ONBOARD-02：当 brownfield 缺少所需 `.planning/codebase/` 映射文件时，系统必须交接到 `/gsd-map-codebase` 或 `/gsd-map-codebase --fast`。fast 映射 readiness 是部分状态，不得视为足以运行 `/gsd-new-project`。
+- REQ-ONBOARD-03：当存在 ADR/PRD/SPEC/RFC 候选且 project 不存在时，系统必须在 `/gsd-new-project` 前提供 `/gsd-ingest-docs`。
+- REQ-ONBOARD-04：在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md` 全部存在前，系统不得报告 onboarding 完成。
+- REQ-ONBOARD-05：系统必须仅在 project setup 后创建或确认 `.planning/onboarding/SUMMARY.md`。
+- REQ-ONBOARD-06：系统必须为没有交互式菜单的运行时支持 `--text` 编号纯文本关卡。
+
+**产出：**
+| Artifact | 说明 |
+|----------|-------------|
+| `.planning/codebase/` | 由 `/gsd-map-codebase` 交接生成的代码库映射 |
+| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` | 由 `/gsd-new-project` 或 `/gsd-ingest-docs` 生成的规划设置 |
+| `.planning/onboarding/SUMMARY.md` | Onboarding status、artifact index 和 next-command summary |
+
 ### 27a. 执行后代码库漂移检测

 **引入版本：** #2003
--- a/docs/zh-CN/INVENTORY.md
+++ b/docs/zh-CN/INVENTORY.md
@@ -78,6 +78,7 @@
 | 命令 | 角色 | 源文件 |
 |------|------|--------|
 | `/gsd-new-project` | 通过深度上下文收集和 PROJECT.md 初始化新项目。 | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
+| `/gsd-onboard` | 引导现有代码库完成映射、文档摄取、项目设置和 onboarding summary。 | [commands/gsd/onboard.md](../../commands/gsd/onboard.md) |
 | `/gsd-workspace` | 管理 GSD 工作区 — 创建（`--new`）、列出（`--list`）或移除（`--remove`）隔离的工作区环境。 | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
 | `/gsd-discuss-phase` | 在规划前通过自适应提问收集阶段上下文。 | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
 | `/gsd-mvp-phase` | 将阶段规划为垂直 MVP 切片 — 用户故事、SPIDR 拆分，然后进行阶段规划。 | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
@@ -218,6 +219,7 @@
 | `milestone-summary.md` | 里程碑摘要综合 — 从里程碑产物生成的入职和审查产物。 | `/gsd-milestone-summary` |
 | `new-milestone.md` | 启动新里程碑周期 — 加载项目上下文、收集目标、更新 PROJECT.md/STATE.md。 | `/gsd-new-milestone` |
 | `new-project.md` | 统一的新项目流程 — 提问、研究（可选）、需求、路线图。 | `/gsd-new-project` |
+| `onboard.md` | Brownfield 接入编排 — 映射代码库、摄取文档、初始化规划并总结下一步。 | `/gsd-onboard` |
 | `new-workspace.md` | 创建带有仓库 worktree/克隆和独立 `.planning/` 的隔离工作区。 | `/gsd-workspace --new` |
 | `next.md` | 检测当前项目状态并自动推进到下一个逻辑步骤。 | `/gsd-progress --next` |
 | `node-repair.md` | 用于失败任务验证的自主修复算子；由 `execute-plan` 调用。 | `execute-plan.md`（恢复） |
--- a/docs/zh-CN/USER-GUIDE.md
+++ b/docs/zh-CN/USER-GUIDE.md
@@ -473,8 +473,8 @@ claude --dangerously-skip-permissions
 ### 现有代码库

 ```bash
-/gsd-map-codebase           # Analyse what exists (parallel agents)
-/gsd-new-project            # Questions focus on what you're ADDING
+/gsd-onboard                # Safely map, ingest docs, and initialize planning
+# Follow printed handoff commands, then rerun /gsd-onboard
 # (normal phase workflow from here)
 ```

@@ -863,7 +863,8 @@ All subagent/executor commits MUST use `--no-verify`.
    themes/
      default.css         # Shared CSS variables for all sketches
    MANIFEST.md           # Index of all sketches with winners
-  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
+  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
+  onboarding/             # Brownfield onboarding summary (from /gsd-onboard)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Atomic execution plans
--- a/docs/zh-CN/how-to/install-on-your-runtime.md
+++ b/docs/zh-CN/how-to/install-on-your-runtime.md
@@ -273,10 +273,11 @@ npx @opengsd/gsd-core@latest --opencode --global

 ## 安装后

-重启您的运行时以加载新命令和代理。然后启动您的第一个项目：
+重启您的运行时以加载新命令和代理。然后启动新项目或接入现有仓库：

 ```bash
-/gsd-new-project
+/gsd-new-project   # 新建项目
+/gsd-onboard       # 现有代码库
 ```

 如果重启后找不到该命令，请确认安装目录与运行时预期的配置路径匹配。上方的预发布版章节介绍了最常见的路径不匹配情况。
--- a/docs/zh-CN/reference/planning-artifacts.md
+++ b/docs/zh-CN/reference/planning-artifacts.md
@@ -23,6 +23,8 @@
 │   ├── architecture.md
 │   ├── stack.md
 │   └── ...
+├── onboarding/                         # Brownfield onboarding 摘要（可选）
+│   └── SUMMARY.md
 ├── intel/                              # 可查询的符号索引（可选，intel.enabled）
 │   └── API-SURFACE.md
 └── phases/
@@ -48,7 +50,7 @@
 | | |
 |---|---|
 | **用途** | 规范的项目标识：项目内容、目标用户、核心价值、需求、约束和关键决策。随项目演进持续更新。 |
-| **生成者** | `/gsd-new-project`（初始创建）；由 `/gsd-complete-milestone` 在决策验证后更新。 |
+| **生成者** | `/gsd-new-project`（初始创建，包含 `/gsd-onboard` 交接）；由 `/gsd-complete-milestone` 在决策验证后更新。 |
 | **消费者** | 所有规划工作流；`gsd-phase-researcher`、`gsd-planner`（上下文）；`discuss-phase`（历史决策）；`gsd-plan-checker`（项目约束）。 |

 ### `ROADMAP.md`
@@ -56,7 +58,7 @@
 | | |
 |---|---|
 | **用途** | 里程碑与阶段列表，含目标、需求 ID、成功标准以及每个阶段的规范参考。是项目构建内容和顺序的唯一可信来源。 |
-| **生成者** | `/gsd-new-project`（初始创建）；由 `/gsd-phase --insert` 和 `/gsd-complete-milestone` 更新。 |
+| **生成者** | `/gsd-new-project`（初始创建，包含 `/gsd-onboard` 交接）；由 `/gsd-phase --insert` 和 `/gsd-complete-milestone` 更新。 |
 | **消费者** | `/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`；所有需要阶段信息的编排命令；`gsd-planner`、`gsd-plan-checker`、`gsd-phase-researcher`。 |

 ### `REQUIREMENTS.md`
@@ -64,7 +66,7 @@
 | | |
 |---|---|
 | **用途** | 编号化、可勾选的项目验收标准。每条需求带有 ID（如 `AUTH-01`），映射到路线图阶段。随着阶段执行，逐步标记需求为已完成。 |
-| **生成者** | `/gsd-new-project`（初始创建）；需求由 `execute-phase` 标记为已完成。 |
+| **生成者** | `/gsd-new-project`（初始创建，包含 `/gsd-onboard` 交接）；需求由 `execute-phase` 标记为已完成。 |
 | **消费者** | `gsd-planner`（计划必须覆盖所有阶段需求 ID）；`gsd-plan-checker` 维度 1（需求覆盖）；`discuss-phase`（历史需求）。 |

 ### `STATE.md`
@@ -72,7 +74,7 @@
 | | |
 |---|---|
 | **用途** | 实时进度跟踪器——当前阶段与计划、进度指标、积累的决策、会话连续性说明。每次工作流运行时首先读取，每次重要操作后更新。 |
-| **生成者** | `/gsd-new-project`（初始创建）；由所有阶段工作流、`/gsd-pause-work`、`/gsd-resume-work` 持续更新。 |
+| **生成者** | `/gsd-new-project`（初始创建，包含 `/gsd-onboard` 交接）；由所有阶段工作流、`/gsd-pause-work`、`/gsd-resume-work` 持续更新。 |
 | **消费者** | 所有编排工作流；`/gsd-progress`；通过 `/gsd-quick` 执行的临时任务；`gsd-planner` 和 `gsd-phase-researcher`（项目决策）。 |

 完整字段参考请参见 [STATE.md 模式](state-md.md)。
@@ -87,6 +89,14 @@

 完整模式请参见 [CONFIGURATION](../CONFIGURATION.md)。

+### `onboarding/SUMMARY.md`（可选）
+
+| | |
+|---|---|
+| **用途** | Brownfield onboarding 索引，记录产物状态、代码库映射是否完整，以及初次设置后的下一个推荐 GSD 命令。 |
+| **生成者** | `/gsd-onboard`，在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 和 `STATE.md` 全部存在后生成。 |
+| **消费者** | 审查初次设置的人；以后确认现有 onboarding 状态的 `/gsd-onboard` 运行。 |
+
 ### `MILESTONES.md`（可选）

 | | |
--- a/docs/zh-CN/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/zh-CN/tutorials/onboarding-an-existing-codebase.md
@@ -44,15 +44,15 @@ claude --dangerously-skip-permissions

 ---

-## 第 3 步 — 映射代码库
+## 第 3 步 — 开始 brownfield onboarding

-在创建项目之前，先让 GSD Core 了解已有的内容。这是使棕地规划准确的关键步骤。
+在创建项目之前，让 GSD Core 检查仓库状态并告诉您安全的下一个顶层命令。这一步可避免跳过代码库上下文或覆盖现有 planning 文件。

 ```text
-/gsd-map-codebase
+/gsd-onboard
 ```

-GSD Core 会派生四个并行映射子代理（您将看到"Spawning 4 parallel codebase mapper agents…"——这需要 1–5 分钟；请勿中断）。每个代理专注于不同的关注点：
+如果 onboarding 报告缺少代码库映射，请选择推荐选项并运行打印出的 `/gsd-map-codebase` 交接命令，然后重新运行 `/gsd-onboard`。`/gsd-onboard --fast` 只适合轻量首次通过；在 `/gsd-new-project` 前仍需要完整映射。`/gsd-map-codebase` 会派生四个并行映射子代理（您将看到"Spawning 4 parallel codebase mapper agents…"——这需要 1–5 分钟；请勿中断）。每个代理专注于不同的关注点：

 | 代理 | 关注点 |
 |-------|-------|
@@ -84,7 +84,7 @@ Created .planning/codebase/:

 ---

-## 第 4 步 — 清除上下文并创建项目
+## 第 4 步 — 重新运行 onboarding 并初始化项目

 清除会话窗口：

@@ -92,12 +92,14 @@ Created .planning/codebase/:
 /clear
 ```

-现在创建项目。由于 GSD Core 在上一步中发现了现有代码，它已经知道这是一个棕地项目。当您运行 `/gsd-new-project` 时，问题将聚焦于您所*新增*的内容，而非重新描述已有的内容：
+现在再次运行 `/gsd-onboard`。如果 GSD Core 检测到 ADR、PRD、spec、RFC 或根级需求文档，请先接受推荐的 `/gsd-ingest-docs` 交接，然后再运行 `/gsd-onboard`。上下文准备好后，onboarding 会打印项目初始化交接命令：

 ```text
 /gsd-new-project
 ```

+由于 GSD Core 在上一步中发现了现有代码，`/gsd-new-project` 知道这是一个棕地项目。问题将聚焦于您所*新增*的内容，而非重新描述已有的内容：
+
 GSD Core 会询问您想构建什么。请用您正在添加的功能来回答，而不是描述整个代码库：

 ```text
@@ -124,6 +126,8 @@ Proposed Roadmap

 批准路线图。

+项目设置完成后，再运行一次 `/gsd-onboard`。现在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 和 `STATE.md` 都已存在，onboarding 会创建或确认 `.planning/onboarding/SUMMARY.md`。
+
 **在 `.planning/` 中创建的内容：**

 ```text
@@ -133,7 +137,8 @@ Proposed Roadmap
  ROADMAP.md          ← Phase 1, status: pending
  STATE.md            ← session memory
  config.json         ← workflow settings
-  codebase/           ← the seven map files from Step 3
+  onboarding/SUMMARY.md ← onboarding 状态和下一个命令
+  codebase/           ← 第 3 步生成的七个映射文件
 ```

 注意 `.planning/codebase/` 已经从第 3 步存在。GSD Core 在编写 `PROJECT.md` 时读取了这些文件，这就是为什么它无需您描述即可填充已验证的需求。
@@ -212,6 +217,7 @@ Proposed Roadmap

 ## 您学到了什么

+- `/gsd-onboard` 如何安全编排 brownfield 设置，不嵌套交互式命令，也不覆盖现有 planning 文件。
 - `/gsd-map-codebase` 如何运行四个并行代理，在 `.planning/codebase/` 中生成 `STACK.md`、`ARCHITECTURE.md`、`CONVENTIONS.md`、`CONCERNS.md`、`STRUCTURE.md`、`TESTING.md` 和 `INTEGRATIONS.md`。
 - 在棕地仓库中运行 `/gsd-new-project` 如何将问题聚焦于您所*新增*的内容，并从现有代码中填充已验证的需求。
 - 代码库映射如何塑造 `/gsd-discuss-phase` 中的每个问题——文件路径、模式和规范均来自您的实际代码。