lee-spec-kit 0.6.16 → 0.6.17

package/README.en.md

@@ -40,26 +40,29 @@
 # 1) Initialize docs structure
 npx lee-spec-kit init
 
-# 2) Create a feature
+# 2) Run initial onboarding checks
+npx lee-spec-kit onboard --strict
+
+# 3) Create a feature
 npx lee-spec-kit feature user-auth
 
-# 3) Show next steps (for agents)
+# 4) Show next steps (for agents)
 npx lee-spec-kit context
 
-# 4) Show workflow dashboard
+# 5) Show workflow dashboard
 npx lee-spec-kit view
 
-# 5) Show overall status
+# 6) Show overall status
 npx lee-spec-kit status
 
-# 6) Validate docs / feature metadata
+# 7) Validate docs / feature metadata
 npx lee-spec-kit doctor
 ```
 
 ## New Project Start Order
 
 For a brand-new project, scaffold the **codebase first**, then initialize docs.
-This sequence assumes the default `docsRepo: embedded` mode.
+For most users (default: embedded), running `npx lee-spec-kit init` in project root is enough.
 
 ```bash
 # 0) Create/init the code project first (example: Next.js)
@@ -69,17 +72,32 @@ cd my-app
 # 1) Initialize docs structure
 npx lee-spec-kit init
 
-# 2) Detect project (agent entrypoint)
+# 2) Run initial onboarding checks
+npx lee-spec-kit onboard --strict
+
+# 3) Detect project (agent entrypoint)
 npx lee-spec-kit detect --json
 
-# 3) Create feature and start workflow
+# 4) Create feature and start workflow
 npx lee-spec-kit feature user-auth
-npx lee-spec-kit context --json
+npx lee-spec-kit context --json-compact
 ```
 
 - Apply lee-spec-kit workflow only when `detect --json` returns `isLeeSpecKitProject: true`.
 - If `isLeeSpecKitProject: false`, continue with normal non-lee-spec-kit workflow.
-- If you use `standalone` docs, run commands against the docs repo location (`--dir` or `LEE_SPEC_KIT_DOCS_DIR`).
+
+For teams that keep docs separate from the code repo (standalone), the recommended start point is the **parent workspace folder**.
+
+```bash
+# Recommended layout:
+# workspace/
+#   ├─ docs/      (lee-spec-kit docs)
+#   └─ project/   (actual code repo)
+#
+# Run from workspace root
+npx lee-spec-kit init --docs-repo standalone --dir ./docs --project-root ./project
+npx lee-spec-kit detect --json
+```
 
 ## Agent Kickoff Prompt
 
@@ -88,7 +106,7 @@ You can paste the following as an agent session-start instruction.
 ```text
 Start procedure:
 1) Run npx lee-spec-kit detect --json
-2) If isLeeSpecKitProject === true, run npx lee-spec-kit context --json
+2) If isLeeSpecKitProject === true, run npx lee-spec-kit context --json-compact (use --json only when full detail is needed)
 3) If actionOptions exist, show approvalPrompt and finalPrompt exactly as provided, then wait for user approval (<LABEL> or <LABEL> OK)
 4) Do not execute before approval; execute requiresUserCheck=true actions only after approval
 5) If isLeeSpecKitProject === false, skip lee-spec-kit-specific flow and continue with normal workflow
@@ -99,7 +117,7 @@ Start procedure:
 ### 📁 Project initialization
 
 - Interactive init or CLI options
-- Supports `single` and `multi` (`fullstack` remains as a backward-compatible alias)
+- Default is `multi`; `single` remains supported for simple single-repo and backward-compatibility scenarios (`fullstack` is a backward-compatible alias of `multi`)
 - Korean/English templates
 
 ### 🚀 Feature creation
@@ -178,6 +196,21 @@ npx lee-spec-kit detect --dir /path/to/workspace
 
 The `--json` payload includes `isLeeSpecKitProject`, `reasonCode` (`PROJECT_DETECTED` | `PROJECT_NOT_DETECTED`), `docsDir`, `configPath`, and `detectionSource` (`config` | `heuristic`).
 
+### Onboarding checks
+
+Validate initial setup readiness (Constitution/PRD/git remotes, etc.).
+
+```bash
+# human-readable output
+npx lee-spec-kit onboard
+
+# JSON output for agents/automation
+npx lee-spec-kit onboard --json
+
+# exit code 1 when WARN/BLOCK exists
+npx lee-spec-kit onboard --strict
+```
+
 ### Create a feature
 
 ```bash
@@ -214,6 +247,7 @@ npx lee-spec-kit context
 # recommended: one feature + labels
 npx lee-spec-kit context F001
 npx lee-spec-kit context F001 --json
+npx lee-spec-kit context F001 --json-compact
 
 # approve + execute (common path)
 npx lee-spec-kit context F001 --approve A --execute
@@ -232,6 +266,7 @@ Use advanced selectors (`--component`, `--all`, `--done`) only when you need mul
 | Option         | Description                                     |
 | -------------- | ----------------------------------------------- |
 | `--json`       | JSON output for agents                          |
+| `--json-compact` | Compact JSON for agents (implies `--json`, minimizes duplicated fields) |
 | `--component <id>` | Select target component in multi mode (e.g. `app`, `api`, `worker`) |
 | `--all`        | Include completed features when auto-detecting  |
 | `--done`       | Show completed (workflow-done) features only    |
@@ -246,7 +281,8 @@ Use advanced selectors (`--component`, `--all`, `--done`) only when you need mul
 - `--ticket` is required for `--execute` only when the selected action has `requiresUserCheck=true`.
 - It is short-lived (5 minutes by default) and cannot be reused after one execution.
 
-`context --json` is organized into `actions` (atomic actions), `actionOptions` (label mapping), and top-level metadata.
+`context --json-compact` is the default recommended format, providing a reduced and deduplicated decision state.  
+Use `context --json` only when full-detail debugging fields are required.
 
 **Core fields (recommended for normal agent flows)**
 
@@ -475,8 +511,8 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
 `approval` only affects the following values produced by `context`:
 
 - the `[CHECK required]` tag in text output
-- `actions[].requiresUserCheck` in `context --json`
-- `checkPolicy.token` (`context --json`): approval token format (`<LABEL>`)
+- `actionOptions[].requiresUserCheck` in `context --json-compact` (`actions[].requiresUserCheck` in `--json`)
+- `checkPolicy.token` (`context --json-compact`/`--json`): approval token format (`<LABEL>`)
 - `checkPolicy.acceptedTokens`: accepted reply templates (e.g. `["<LABEL>", "<LABEL> OK", "<LABEL> ...", "... <LABEL> ..."]`)
 - `checkPolicy.tokenPattern`: input validation regex for approval replies
 - `checkPolicy.validLabels`: currently selectable labels (`A`, `B`, `C`...)
@@ -536,7 +572,7 @@ Example:
 #### Modes
 
 - `builtin` (default): keep built-in `requiresUserCheck` in steps/actions
-- `category` (recommended): control CHECK policy by `actions[].category`
+- `category` (recommended): control CHECK policy by `actionOptions[].category` (`actions[].category` in `--json`)
 - `steps`: control by step numbers (not recommended; fragile)
 
 #### Fields
@@ -564,7 +600,7 @@ Example:
 }
 ```
 
-> To discover available `category` values, check `actions[].category` in `context --json`.
+> To discover available `category` values, check `actionOptions[].category` in `context --json-compact` first, and use `actions[].category` in `context --json` when needed.
 
 ### pr (PR artifacts policy)
 

package/README.md

@@ -55,26 +55,29 @@
 # 1. 프로젝트 문서 구조 생성
 npx lee-spec-kit init
 
-# 2. 새 기능 생성
+# 2. 초기 온보딩 점검
+npx lee-spec-kit onboard --strict
+
+# 3. 새 기능 생성
 npx lee-spec-kit feature user-auth
 
-# 3. 진행 상황 및 다음 단계 확인 (AI 에이전트용)
+# 4. 진행 상황 및 다음 단계 확인 (AI 에이전트용)
 npx lee-spec-kit context
 
-# 4. 워크플로우 대시보드 확인
+# 5. 워크플로우 대시보드 확인
 npx lee-spec-kit view
 
-# 5. 전체 상태 확인
+# 6. 전체 상태 확인
 npx lee-spec-kit status
 
-# 6. 문서/Feature 진단
+# 7. 문서/Feature 진단
 npx lee-spec-kit doctor
 ```
 
 ## 신규 프로젝트 시작 순서
 
 신규 프로젝트에서는 **코드 스캐폴딩을 먼저** 하고, 그 다음 docs를 초기화하세요.
-이 순서는 기본값인 `docsRepo: embedded` 기준입니다.
+대부분의 사용자(기본값: embedded)는 프로젝트 루트에서 `npx lee-spec-kit init`만 실행하면 됩니다.
 
 ```bash
 # 0. 코드 프로젝트 생성/초기화 (예: Next.js)
@@ -84,17 +87,32 @@ cd my-app
 # 1. docs 구조 초기화
 npx lee-spec-kit init
 
-# 2. 감지 확인 (에이전트 시작점)
+# 2. 초기 온보딩 점검
+npx lee-spec-kit onboard --strict
+
+# 3. 감지 확인 (에이전트 시작점)
 npx lee-spec-kit detect --json
 
-# 3. Feature 생성 후 작업 시작
+# 4. Feature 생성 후 작업 시작
 npx lee-spec-kit feature user-auth
-npx lee-spec-kit context --json
+npx lee-spec-kit context --json-compact
 ```
 
 - `detect --json` 결과가 `isLeeSpecKitProject: true`일 때 lee-spec-kit 워크플로우를 적용하세요.
 - `isLeeSpecKitProject: false`면 일반 프로젝트 워크플로우로 진행하세요.
-- `standalone`으로 docs를 분리한 경우에는 docs 레포 위치(`--dir` 또는 `LEE_SPEC_KIT_DOCS_DIR`) 기준으로 실행하세요.
+
+docs를 코드 저장소와 분리해 운영하는 팀(standalone)은 **상위 워크스페이스 폴더**를 기준으로 시작하는 것을 권장합니다.
+
+```bash
+# 권장 레이아웃:
+# workspace/
+#   ├─ docs/      (lee-spec-kit 문서)
+#   └─ project/   (실제 코드 저장소)
+#
+# workspace 루트에서 실행
+npx lee-spec-kit init --docs-repo standalone --dir ./docs --project-root ./project
+npx lee-spec-kit detect --json
+```
 
 ## 에이전트 킥오프 프롬프트
 
@@ -103,7 +121,7 @@ npx lee-spec-kit context --json
 ```text
 작업 시작 절차:
 1) npx lee-spec-kit detect --json
-2) isLeeSpecKitProject === true 이면 npx lee-spec-kit context --json 실행
+2) isLeeSpecKitProject === true 이면 npx lee-spec-kit context --json-compact 실행 (필요 시 --json으로 상세 조회)
 3) actionOptions가 있으면 approvalPrompt와 finalPrompt를 그대로 사용자에게 제시하고 승인(<LABEL> 또는 <LABEL> OK) 대기
 4) 승인 전에는 실행하지 말고, requiresUserCheck=true 액션은 승인 후에만 실행
 5) isLeeSpecKitProject === false 이면 lee-spec-kit 전용 절차를 건너뛰고 일반 워크플로우로 진행
@@ -114,7 +132,7 @@ npx lee-spec-kit context --json
 ### 📁 프로젝트 초기화
 
 - 대화형 모드 또는 CLI 옵션으로 프로젝트 설정
-- Single(단일 레포) / Multi(멀티 컴포넌트) 프로젝트 타입 지원 (`fullstack`는 하위호환 alias)
+- 기본값은 Multi이며, Single도 단순 단일 레포/기존 호환 시나리오를 위해 지원합니다. (`fullstack`는 `multi` 하위호환 alias)
 - 한국어/영어 템플릿 선택
 
 ### 🚀 Feature 생성
@@ -196,6 +214,21 @@ npx lee-spec-kit detect --dir /path/to/workspace
 
 `--json` 출력은 `isLeeSpecKitProject`, `reasonCode`(`PROJECT_DETECTED` | `PROJECT_NOT_DETECTED`), `docsDir`, `configPath`, `detectionSource`(`config` | `heuristic`)를 포함합니다.
 
+### 온보딩 점검
+
+초기 설정(Constitution/PRD/Git remote 등) 준비 상태를 점검합니다.
+
+```bash
+# 사람 읽기 쉬운 출력
+npx lee-spec-kit onboard
+
+# 에이전트/자동화용 JSON
+npx lee-spec-kit onboard --json
+
+# WARN/BLOCK이 있으면 종료 코드 1
+npx lee-spec-kit onboard --strict
+```
+
 ### 새 기능 생성
 
 ```bash
@@ -233,6 +266,7 @@ npx lee-spec-kit context
 # 특정 Feature 상태 + 라벨 확인 (에이전트 권장)
 npx lee-spec-kit context F001
 npx lee-spec-kit context F001 --json
+npx lee-spec-kit context F001 --json-compact
 
 # 승인 + 실행 (일반 케이스)
 npx lee-spec-kit context F001 --approve A --execute
@@ -251,6 +285,7 @@ npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET> --execute-
 | 옵션            | 설명                                            |
 | --------------- | ----------------------------------------------- |
 | `--json`        | 에이전트용 JSON 출력                            |
+| `--json-compact` | 에이전트용 압축 JSON 출력 (`--json` 포함, 중복 필드 최소화) |
 | `--component <id>` | multi에서 대상 컴포넌트 지정 (예: `app`, `api`, `worker`) |
 | `--all`         | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
 | `--done`        | 완료(workflow-done) Feature만 표시              |
@@ -265,7 +300,8 @@ npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET> --execute-
 - 선택한 액션이 `requiresUserCheck=true`인 경우에만 `--execute`에서 `--ticket`이 필요합니다.
 - 발급 후 짧은 시간(기본 5분)만 유효하며, 한 번 사용하면 재사용할 수 없습니다.
 
-`context --json` 출력은 크게 `actions`(원자 액션), `actionOptions`(라벨 매핑), 상위 메타데이터로 구성됩니다.
+기본 권장 포맷은 `context --json-compact`이며, 같은 판단 정보를 중복 없이 축약해 전달합니다.  
+`context --json`은 디버깅/세부 필드 확인이 필요할 때만 사용하세요.
 
 **핵심 필드 (실사용 권장)**
 
@@ -526,8 +562,8 @@ npx lee-spec-kit update --force
 `approval`은 `context`가 출력하는 다음 값에만 영향을 줍니다:
 
 - 텍스트 출력의 `[확인 필요]` 표시
-- `context --json`의 `actions[].requiresUserCheck`
-- `checkPolicy.token` (`context --json`): 승인 토큰 형식 (`<LABEL>`)
+- `context --json-compact`의 `actionOptions[].requiresUserCheck` (`--json`에서는 `actions[].requiresUserCheck`)
+- `checkPolicy.token` (`context --json-compact`/`--json`): 승인 토큰 형식 (`<LABEL>`)
 - `checkPolicy.acceptedTokens`: 허용되는 승인 응답 템플릿 (예: `["<LABEL>", "<LABEL> OK", "<LABEL> ...", "... <LABEL> ..."]`)
 - `checkPolicy.tokenPattern`: 승인 응답 검증용 정규식
 - `checkPolicy.validLabels`: 현재 선택 가능한 라벨 목록 (`A`, `B`, `C`...)
@@ -584,7 +620,7 @@ npx lee-spec-kit update --force
 #### 모드
 
 - `builtin` (기본): 코드에 내장된 `requiresUserCheck`를 그대로 사용
-- `category` (권장): `actions[].category` 기준으로 확인 정책을 제어
+- `category` (권장): `actionOptions[].category` 기준으로 확인 정책을 제어 (`--json`에서는 `actions[].category`)
 - `steps`: step 번호 기준(변경에 취약하므로 권장하지 않음)
 
 #### 설정 필드
@@ -612,7 +648,7 @@ npx lee-spec-kit update --force
 }
 ```
 
-> 사용 가능한 `category` 값은 `context --json`의 `actions[].category`로 확인하는 것을 권장합니다.
+> 사용 가능한 `category` 값은 `context --json-compact`의 `actionOptions[].category`에서 우선 확인하고, 필요 시 `context --json`의 `actions[].category`를 참고하세요.
 
 ### pr (PR 결과물 정책)
 

package/dist/index.js

@@ -139,6 +139,7 @@ var I18N = {
       "context.suggestionCommandHint": "\uB77C\uBCA8 \uCC38\uACE0 \uBA85\uB839: {command}",
       "context.suggestionFinalPrompt": "\uD604\uC7AC \uCD94\uCC9C \uB77C\uBCA8: {labels}. \uC751\uB2F5\uC740 \uB77C\uBCA8 \uD1A0\uD070 \uD3EC\uD568 \uD615\uC2DD\uC73C\uB85C \uD574\uC8FC\uC138\uC694. (\uC608: {example}, `A \uC9C4\uD589\uD574`)",
       "context.suggestion.createFeature": "\uC0C8 Feature\uB97C \uC0DD\uC131\uD569\uB2C8\uB2E4",
+      "context.suggestion.runOnboard": "\uCD08\uAE30 \uC124\uC815 \uC810\uAC80(onboard)\uC744 \uC2E4\uD589\uD569\uB2C8\uB2E4",
       "context.suggestion.showDone": "\uC644\uB8CC\uB41C Feature \uBAA9\uB85D\uC744 \uD655\uC778\uD569\uB2C8\uB2E4",
       "context.suggestion.showAll": "\uC804\uCCB4 Feature \uBAA9\uB85D\uC744 \uD655\uC778\uD569\uB2C8\uB2E4",
       "context.suggestion.selectFeature": "\uC9C4\uD589\uD560 Feature\uB97C \uC120\uD0DD\uD574 \uC0C1\uC138 \uCEE8\uD14D\uC2A4\uD2B8\uB97C \uC5FD\uB2C8\uB2E4",
@@ -202,6 +203,7 @@ var I18N = {
       "init.log.nextStepsTitle": "\uB2E4\uC74C \uB2E8\uACC4:",
       "init.log.nextSteps1": "  1. {docsDir}/prd/README.md \uC791\uC131",
       "init.log.nextSteps2": "  2. npx lee-spec-kit feature <name> \uC73C\uB85C \uAE30\uB2A5 \uCD94\uAC00",
+      "init.log.nextSteps3": "  3. npx lee-spec-kit onboard --strict \uB85C \uCD08\uAE30 \uC124\uC815 \uC810\uAC80",
       "init.log.gitRepoDetectedCommit": "\u{1F4E6} Git \uB808\uD3EC\uC9C0\uD1A0\uB9AC \uAC10\uC9C0, docs \uCEE4\uBC0B \uC911...",
       "init.log.gitInit": "\u{1F4E6} Git \uCD08\uAE30\uD654 \uC911...",
       "init.warn.stagedChangesSkip": '\u26A0\uFE0F  \uD604\uC7AC Git index\uC5D0 \uC774\uBBF8 stage\uB41C \uBCC0\uACBD\uC774 \uC788\uC2B5\uB2C8\uB2E4. (--dir "." \uC778 \uACBD\uC6B0 \uCEE4\uBC0B \uBC94\uC704\uB97C \uC548\uC804\uD558\uAC8C \uC81C\uD55C\uD560 \uC218 \uC5C6\uC5B4 \uC790\uB3D9 \uCEE4\uBC0B\uC744 \uAC74\uB108\uB701\uB2C8\uB2E4)',
@@ -589,6 +591,7 @@ var I18N = {
       "context.suggestionCommandHint": "Reference command: {command}",
       "context.suggestionFinalPrompt": "Recommended labels now: {labels}. Please reply with a format that includes a label token. (e.g. {example}, `A proceed`)",
       "context.suggestion.createFeature": "Create a new feature",
+      "context.suggestion.runOnboard": "Run onboarding checks",
       "context.suggestion.showDone": "Show completed features",
       "context.suggestion.showAll": "Show all features",
       "context.suggestion.selectFeature": "Select a feature and open detailed context",
@@ -652,6 +655,7 @@ var I18N = {
       "init.log.nextStepsTitle": "Next steps:",
       "init.log.nextSteps1": "  1. Write {docsDir}/prd/README.md",
       "init.log.nextSteps2": "  2. Add a feature with: npx lee-spec-kit feature <name>",
+      "init.log.nextSteps3": "  3. Run setup checks: npx lee-spec-kit onboard --strict",
       "init.log.gitRepoDetectedCommit": "\u{1F4E6} Git repo detected, committing docs...",
       "init.log.gitInit": "\u{1F4E6} Initializing Git...",
       "init.warn.stagedChangesSkip": '\u26A0\uFE0F  There are already staged changes in the Git index. (With --dir ".", commit scope cannot be safely restricted, so auto-commit is skipped.)',
@@ -2152,6 +2156,7 @@ async function runInit(options) {
         chalk6.gray(tr(lang, "cli", "init.log.nextSteps1", { docsDir: targetDir }))
       );
       console.log(chalk6.gray(tr(lang, "cli", "init.log.nextSteps2")));
+      console.log(chalk6.gray(tr(lang, "cli", "init.log.nextSteps3")));
       console.log();
     },
     { owner: "init" }
@@ -2159,7 +2164,8 @@ async function runInit(options) {
 }
 async function initGit(cwd, targetDir, docsRepo, lang, pushDocs, docsRemote) {
   try {
-    const runGit = (args, workdir) => {
+    const gitWorkdir = docsRepo === "standalone" ? targetDir : cwd;
+    const runGit2 = (args, workdir) => {
       execFileSync("git", args, { cwd: workdir, stdio: "ignore" });
     };
     const getCachedStagedFiles = (workdir) => {
@@ -2205,14 +2211,14 @@ async function initGit(cwd, targetDir, docsRepo, lang, pushDocs, docsRemote) {
       }
     };
     try {
-      runGit(["rev-parse", "--is-inside-work-tree"], cwd);
+      runGit2(["rev-parse", "--is-inside-work-tree"], gitWorkdir);
       console.log(chalk6.blue(tr(lang, "cli", "init.log.gitRepoDetectedCommit")));
     } catch {
       console.log(chalk6.blue(tr(lang, "cli", "init.log.gitInit")));
-      runGit(["init"], cwd);
+      runGit2(["init"], gitWorkdir);
     }
-    const relativePath = path19.relative(cwd, targetDir);
-    const stagedBeforeAdd = getCachedStagedFiles(cwd);
+    const relativePath = docsRepo === "standalone" ? "." : path19.relative(cwd, targetDir);
+    const stagedBeforeAdd = getCachedStagedFiles(gitWorkdir);
     if (relativePath === "." && stagedBeforeAdd && stagedBeforeAdd.length > 0) {
       console.log(
         chalk6.yellow(
@@ -2223,8 +2229,8 @@ async function initGit(cwd, targetDir, docsRepo, lang, pushDocs, docsRemote) {
       console.log();
       return;
     }
-    if (relativePath !== "." && isPathIgnored(cwd, relativePath)) {
-      const repoRelativePath = toRepoRelativePath(cwd, relativePath);
+    if (relativePath !== "." && isPathIgnored(gitWorkdir, relativePath)) {
+      const repoRelativePath = toRepoRelativePath(gitWorkdir, relativePath);
       console.log(
         chalk6.yellow(
           tr(lang, "cli", "init.warn.docsPathIgnoredSkipCommit", {
@@ -2242,14 +2248,14 @@ async function initGit(cwd, targetDir, docsRepo, lang, pushDocs, docsRemote) {
       console.log();
       return;
     }
-    runGit(["add", relativePath], cwd);
-    runGit(
+    runGit2(["add", relativePath], gitWorkdir);
+    runGit2(
       ["commit", "-m", "init: docs \uAD6C\uC870 \uCD08\uAE30\uD654 (lee-spec-kit)", "--", relativePath],
-      cwd
+      gitWorkdir
     );
     if (docsRepo === "standalone" && pushDocs && docsRemote) {
       try {
-        runGit(["remote", "add", "origin", docsRemote], cwd);
+        runGit2(["remote", "add", "origin", docsRemote], gitWorkdir);
         console.log(
           chalk6.green(tr(lang, "cli", "init.log.gitRemoteSet", { remote: docsRemote }))
         );
@@ -6376,9 +6382,14 @@ function buildSuggestionOptions(lang, state, projectType, selectedComponent) {
   const showDoneCommand = `npx lee-spec-kit context --done${componentArg}`;
   const showAllCommand = `npx lee-spec-kit context --all${componentArg}`;
   const showOpenCommand = `npx lee-spec-kit context${componentArg}`;
+  const runOnboardCommand = "npx lee-spec-kit onboard --strict";
   const rawSuggestions = [];
   switch (state.status) {
     case "no_features":
+      rawSuggestions.push({
+        summary: tr(lang, "cli", "context.suggestion.runOnboard"),
+        command: runOnboardCommand
+      });
       rawSuggestions.push({
         summary: tr(lang, "cli", "context.suggestion.createFeature"),
         command: createFeatureCommand
@@ -6487,7 +6498,10 @@ function getCommandExecutionLockPath(action, config) {
   return getProjectExecutionLockPath(action.cwd);
 }
 function contextCommand(program2) {
-  program2.command("context [feature-name]").description("Show current feature context and next actions").option("--json", "Output in JSON format for agents").option("--component <component>", "Component name for multi projects").option("--all", "Include completed features when auto-detecting").option("--done", "Show completed (workflow-done) features only").option(
+  program2.command("context [feature-name]").description("Show current feature context and next actions").option("--json", "Output in JSON format for agents").option(
+    "--json-compact",
+    "Output compact JSON for agents (implies --json, reduced duplication)"
+  ).option("--component <component>", "Component name for multi projects").option("--all", "Include completed features when auto-detecting").option("--done", "Show completed (workflow-done) features only").option(
     "--approve <reply>",
     "Approve one labeled option (examples: A, A OK, A proceed, A \uC9C4\uD589\uD574)"
   ).option(
@@ -6508,7 +6522,7 @@ function contextCommand(program2) {
         const lang = config?.lang ?? DEFAULT_LANG;
         const cliError = toCliError(error);
         const suggestions = getCliErrorSuggestions(cliError.code, lang);
-        if (options.json) {
+        if (options.json || options.jsonCompact) {
           console.log(
             JSON.stringify({
               status: "error",
@@ -6600,6 +6614,111 @@ function getMultipleFeaturesRecommendation(projectType, selectedComponent) {
   }
   return "Multiple features detected across components. Please specify feature name (slug | F001 | F001-slug) or use --component.";
 }
+function getFeatureRef(feature) {
+  return feature.folderName || `${feature.type}:${feature.slug}`;
+}
+function toCompactFeature(feature) {
+  if (!feature) return null;
+  return {
+    ref: getFeatureRef(feature),
+    id: feature.id ?? null,
+    slug: feature.slug,
+    folderName: feature.folderName,
+    type: feature.type,
+    path: feature.path,
+    currentStep: feature.currentStep,
+    nextAction: feature.nextAction,
+    completion: feature.completion,
+    specStatus: feature.specStatus,
+    planStatus: feature.planStatus,
+    tasks: feature.tasks,
+    prePrReview: {
+      status: feature.prePrReview.status,
+      findings: feature.prePrReview.findings,
+      evidenceProvided: feature.prePrReview.evidenceProvided
+    },
+    prReview: {
+      findings: feature.prReview.findings,
+      evidenceProvided: feature.prReview.evidenceProvided
+    },
+    pr: {
+      link: feature.pr.link,
+      status: feature.pr.status,
+      remote: feature.pr.remote
+    },
+    git: {
+      docsBranch: feature.git.docsBranch,
+      projectBranch: feature.git.projectBranch,
+      projectBranchAvailable: feature.git.projectBranchAvailable,
+      onExpectedBranch: feature.git.onExpectedBranch,
+      docsEverCommitted: feature.git.docsEverCommitted,
+      docsHasUncommittedChanges: feature.git.docsHasUncommittedChanges,
+      projectHasUncommittedChanges: feature.git.projectHasUncommittedChanges,
+      docsPathIgnored: feature.git.docsPathIgnored
+    },
+    docs: {
+      specExists: feature.docs.specExists,
+      planExists: feature.docs.planExists,
+      tasksExists: feature.docs.tasksExists,
+      issueDocIssueFieldExists: feature.docs.issueDocIssueFieldExists,
+      prDocPrFieldExists: feature.docs.prDocPrFieldExists,
+      prDocReviewStatusFieldExists: feature.docs.prDocReviewStatusFieldExists,
+      prFieldExists: feature.docs.prFieldExists,
+      prStatusFieldExists: feature.docs.prStatusFieldExists,
+      prePrReviewFieldExists: feature.docs.prePrReviewFieldExists,
+      prePrFindingsFieldExists: feature.docs.prePrFindingsFieldExists,
+      prePrEvidenceFieldExists: feature.docs.prePrEvidenceFieldExists,
+      prReviewFindingsFieldExists: feature.docs.prReviewFindingsFieldExists,
+      prReviewEvidenceFieldExists: feature.docs.prReviewEvidenceFieldExists
+    },
+    warnings: feature.warnings
+  };
+}
+function toCompactActionOption(option) {
+  const base = {
+    label: option.label,
+    summary: option.summary,
+    detail: option.detail,
+    approvalPrompt: option.approvalPrompt,
+    actionType: option.action.type,
+    category: option.action.category,
+    operationType: option.action.operationType,
+    requiresUserCheck: !!option.action.requiresUserCheck
+  };
+  if (option.action.type === "command") {
+    base.scope = option.action.scope;
+    base.cwd = option.action.cwd;
+    base.cmd = option.action.cmd;
+    return base;
+  }
+  base.message = option.action.message;
+  return base;
+}
+function toCompactSuggestionOption(option) {
+  return {
+    label: option.label,
+    summary: option.summary,
+    command: option.command
+  };
+}
+function resolveContextRecommendation(state, projectType, selectedComponent) {
+  if (state.status === "multiple_active") {
+    return getMultipleFeaturesRecommendation(projectType, selectedComponent);
+  }
+  if (state.status === "no_features") {
+    return "No features found. Run onboarding checks first, then create a feature.";
+  }
+  if (state.status === "no_open") {
+    return "No open features found. Use `context --done` to inspect completed features.";
+  }
+  if (state.status === "no_match") {
+    return "No features found.";
+  }
+  if (state.targetFeatures.length === 1) {
+    return state.targetFeatures[0].nextAction;
+  }
+  return "No matched feature.";
+}
 async function runContext(featureName, options) {
   const cwd = process.cwd();
   const config = await getConfig(cwd);
@@ -6659,7 +6778,8 @@ async function runContext(featureName, options) {
     );
     return;
   }
-  if (options.json) {
+  const jsonMode = !!options.json || !!options.jsonCompact;
+  if (jsonMode) {
     const primaryAction = state.actionOptions[0] ?? null;
     const finalApprovalPrompt = buildFinalApprovalPrompt(lang, state.actionOptions);
     const approveCommand = buildApprovalCommand(
@@ -6674,6 +6794,76 @@ async function runContext(featureName, options) {
       selectedComponent,
       true
     );
+    const recommendation = resolveContextRecommendation(
+      state,
+      config.projectType,
+      selectedComponent
+    );
+    if (options.jsonCompact) {
+      const compactResult = {
+        schema: "context.v2.compact",
+        status: state.status,
+        reasonCode: toReasonCode(state.status),
+        selectionMode: state.selectionMode,
+        selectionFallback: state.selectionFallback,
+        branches: state.branches,
+        warnings: state.warnings,
+        contextVersion: state.contextVersion,
+        matchedFeature: toCompactFeature(state.matchedFeature),
+        candidateRefs: state.targetFeatures.length > 1 ? state.targetFeatures.map((feature) => getFeatureRef(feature)) : [],
+        completedCandidateRefs: state.selectionMode === "open" ? state.doneFeatures.map((feature) => getFeatureRef(feature)) : [],
+        openCandidateRefs: state.selectionMode === "open" ? state.openFeatures.map((feature) => getFeatureRef(feature)) : [],
+        inProgressCandidateRefs: state.selectionMode === "open" ? state.inProgressFeatures.map((feature) => getFeatureRef(feature)) : [],
+        readyToCloseCandidateRefs: state.selectionMode === "open" ? state.readyToCloseFeatures.map((feature) => getFeatureRef(feature)) : [],
+        actionOptions: state.actionOptions.map((option) => toCompactActionOption(option)),
+        suggestionOptions: suggestionOptions.map(
+          (option) => toCompactSuggestionOption(option)
+        ),
+        primaryActionLabel: primaryAction?.label ?? null,
+        workflowPolicy,
+        taskCommitGatePolicy,
+        prePrReviewPolicy,
+        checkPolicy: {
+          docPath: "builtin://agents/policy",
+          token: "<LABEL>",
+          acceptedTokens: ["<LABEL>", "<LABEL> OK", "<LABEL> ...", "... <LABEL> ..."],
+          tokenPattern: "^.*\\b([A-Z]+)\\b.*$",
+          validLabels: state.actionOptions.map((o) => o.label),
+          oneApprovalPerAction: true,
+          requireFreshContext: true,
+          contextVersion: state.contextVersion,
+          config: config.approval ?? { mode: "builtin" }
+        },
+        approvalRequest: {
+          finalPrompt: finalApprovalPrompt,
+          userFacingLines: [
+            ...state.actionOptions.map((o) => o.approvalPrompt),
+            finalApprovalPrompt
+          ].filter((line) => line.length > 0),
+          labels: state.actionOptions.map((o) => o.label),
+          approveCommand,
+          executeCommand,
+          executeRequiresTicket: !!state.actionOptions[0]?.action?.requiresUserCheck
+        },
+        suggestionRequest: {
+          finalPrompt: suggestionFinalPrompt,
+          userFacingLines: [
+            ...suggestionOptions.map((o) => `${o.label}: ${o.summary}`),
+            suggestionFinalPrompt
+          ].filter((line) => line.length > 0),
+          labels: suggestionOptions.map((o) => o.label)
+        },
+        prPolicy: {
+          screenshots: {
+            upload: config.pr?.screenshots?.upload ?? false
+          }
+        },
+        requiredDocs,
+        recommendation
+      };
+      console.log(JSON.stringify(compactResult, null, 2));
+      return;
+    }
     const result = {
       status: state.status,
       reasonCode: toReasonCode(state.status),
@@ -6765,24 +6955,8 @@ async function runContext(featureName, options) {
         }
       },
       requiredDocs,
-      recommendation: ""
+      recommendation
     };
-    if (result.status === "multiple_active") {
-      result.recommendation = getMultipleFeaturesRecommendation(
-        config.projectType,
-        selectedComponent
-      );
-    } else if (result.status === "no_features") {
-      result.recommendation = "No features found. Create a feature first.";
-    } else if (result.status === "no_open") {
-      result.recommendation = "No open features found. Use `context --done` to inspect completed features.";
-    } else if (result.status === "no_match") {
-      result.recommendation = "No features found.";
-    } else if (state.targetFeatures.length === 1) {
-      result.recommendation = state.targetFeatures[0].nextAction;
-    } else {
-      result.recommendation = "No matched feature.";
-    }
     console.log(JSON.stringify(result, null, 2));
     return;
   }
@@ -7055,6 +7229,7 @@ async function runContext(featureName, options) {
 async function runApprovedOption(state, config, lang, featureName, selectionOptions, options) {
   const approval = options.approve || "";
   const ticketToken = (options.ticket || "").trim();
+  const jsonMode = !!options.json || !!options.jsonCompact;
   let parsedLabel = null;
   if (state.status !== "single_matched" || !state.matchedFeature) {
     throw createCliError(
@@ -7115,7 +7290,7 @@ async function runApprovedOption(state, config, lang, featureName, selectionOpti
       label: parsedLabel,
       featureRef
     }) : null;
-    if (options.json) {
+    if (jsonMode) {
       console.log(
         JSON.stringify(
           {
@@ -7194,7 +7369,7 @@ async function runApprovedOption(state, config, lang, featureName, selectionOpti
         `Approved label "${parsedLabel}" is instruction-only. Re-run without \`--execute\` or pick a command option.`
       );
     }
-    if (options.json) {
+    if (jsonMode) {
       console.log(
         JSON.stringify(
           {
@@ -7219,7 +7394,7 @@ async function runApprovedOption(state, config, lang, featureName, selectionOpti
     console.log();
     return;
   }
-  if (!options.json) {
+  if (!jsonMode) {
     console.log();
     console.log(chalk6.blue(`\u25B6 Executing option ${parsedLabel}...`));
     console.log(chalk6.gray(`   ${selectedAction.cmd}`));
@@ -7231,12 +7406,12 @@ async function runApprovedOption(state, config, lang, featureName, selectionOpti
       lockPath,
       async () => executeCommandAction(
         selectedAction.cmd,
-        !!options.json,
+        jsonMode,
         selectedAction.cwd
       ),
       { owner: `context-execute:${selectedAction.scope}` }
     );
-    if (options.json) {
+    if (jsonMode) {
       console.log(
         JSON.stringify(
           {
@@ -10054,6 +10229,459 @@ async function runDetect(options) {
   }
   console.log();
 }
+function t(lang, ko, en) {
+  return lang === "ko" ? ko : en;
+}
+function quotePath(value) {
+  return `"${value.replace(/"/g, '\\"')}"`;
+}
+function toSlug(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+}
+function runGit(args, cwd) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }).trim();
+  } catch {
+    return void 0;
+  }
+}
+function isGitRepo(cwd) {
+  return runGit(["rev-parse", "--is-inside-work-tree"], cwd) === "true";
+}
+function hasHeadCommit(cwd) {
+  return !!runGit(["rev-parse", "--verify", "HEAD"], cwd);
+}
+function getOriginUrl(cwd) {
+  const out = runGit(["remote", "get-url", "origin"], cwd);
+  return out || void 0;
+}
+function hasTemplateMarkers(content) {
+  const patterns = [
+    /\{\{projectName\}\}/,
+    /\{\{date\}\}/,
+    /\(Write your project mission here\)/,
+    /\(Write project-specific architecture principles here/i,
+    /\(Write project code quality standards here/i,
+    /\(Write project security principles here/i,
+    /\(Write your project-specific rules here\)/,
+    /\(Override default rules or add additional rules here\)/,
+    /\(Write project-specific workflows here\)/,
+    /\(Write other rules here\)/,
+    /\(프로젝트의 미션을 작성하세요\)/,
+    /\(프로젝트별 아키텍처 원칙을 작성하세요/,
+    /\(프로젝트의 코드 품질 기준을 작성하세요/,
+    /\(프로젝트의 보안 원칙을 작성하세요/,
+    /\(여기에 프로젝트만의 규칙을 작성하세요\)/,
+    /\(기본 규칙을 오버라이드하거나 추가 규칙을 작성하세요\)/,
+    /\(프로젝트만의 워크플로우가 있다면 작성하세요\)/,
+    /\(기타 규칙을 작성하세요\)/
+  ];
+  return patterns.some((pattern) => pattern.test(content));
+}
+async function countFeatureDirs(docsDir, projectType) {
+  const pattern = projectType === "single" ? "features/*/" : "features/*/*/";
+  const dirs = await glob(pattern, {
+    cwd: docsDir,
+    absolute: false,
+    ignore: ["**/feature-base/**"]
+  });
+  return dirs.map((value) => value.replace(/\\/g, "/").replace(/\/+$/, "")).filter((value) => {
+    const base = path19.posix.basename(value);
+    return !!base && base !== "feature-base";
+  }).length;
+}
+async function hasUserPrdFile(prdDir) {
+  if (!await fs15.pathExists(prdDir)) return false;
+  const files = await glob("**/*.md", {
+    cwd: prdDir,
+    nodir: true,
+    absolute: false,
+    ignore: ["**/node_modules/**"]
+  });
+  return files.some((relativePath) => path19.basename(relativePath).toLowerCase() !== "readme.md");
+}
+function finalizeChecks(checks) {
+  const summary = checks.reduce(
+    (acc, check) => {
+      acc[check.status] += 1;
+      return acc;
+    },
+    { ok: 0, warn: 0, block: 0 }
+  );
+  const status = summary.block > 0 ? "blocked" : summary.warn > 0 ? "needs_action" : "ready";
+  return { checks, summary, status };
+}
+function printOnboardResult(lang, result) {
+  console.log();
+  console.log(chalk6.bold(t(lang, "\u{1F9ED} Onboarding \uC810\uAC80", "\u{1F9ED} Onboarding Checks")));
+  for (const check of result.checks) {
+    const mark = check.status === "ok" ? chalk6.green("\u2705") : check.status === "warn" ? chalk6.yellow("\u26A0\uFE0F") : chalk6.red("\u274C");
+    const level = check.status === "ok" ? chalk6.green("OK") : check.status === "warn" ? chalk6.yellow("WARN") : chalk6.red("BLOCK");
+    console.log(`${mark} [${level}] ${check.title}`);
+    console.log(`   ${check.message}`);
+    if (check.path) console.log(chalk6.gray(`   path: ${check.path}`));
+    if (check.suggestedCommand) {
+      console.log(chalk6.gray(`   ${t(lang, "\uB2E4\uC74C \uBA85\uB839", "next")}: ${check.suggestedCommand}`));
+    }
+  }
+  console.log();
+  console.log(
+    chalk6.bold(
+      t(
+        lang,
+        `\uC694\uC57D: OK ${result.summary.ok}, WARN ${result.summary.warn}, BLOCK ${result.summary.block}`,
+        `Summary: OK ${result.summary.ok}, WARN ${result.summary.warn}, BLOCK ${result.summary.block}`
+      )
+    )
+  );
+  if (result.status === "ready") {
+    console.log(chalk6.green(t(lang, "\uC628\uBCF4\uB529 \uC900\uBE44\uAC00 \uC644\uB8CC\uB418\uC5C8\uC2B5\uB2C8\uB2E4.", "Onboarding checks passed.")));
+  } else if (result.status === "needs_action") {
+    console.log(chalk6.yellow(t(lang, "\uCD94\uAC00 \uC815\uB9AC\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.", "Some onboarding actions are required.")));
+  } else {
+    console.log(chalk6.red(t(lang, "\uC628\uBCF4\uB529 \uC120\uD589 \uC791\uC5C5\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.", "Onboarding is blocked by required setup.")));
+  }
+  console.log();
+}
+async function runOnboardChecks(config) {
+  const lang = config.lang;
+  const checks = [];
+  const docsDir = config.docsDir;
+  const docsGitReady = isGitRepo(docsDir);
+  if (!docsGitReady) {
+    checks.push({
+      id: "docs_git_repo",
+      status: "block",
+      title: t(lang, "docs Git \uB808\uD3EC \uCD08\uAE30\uD654", "Docs git repository initialized"),
+      message: t(
+        lang,
+        "docs \uACBD\uB85C\uAC00 Git \uB808\uD3EC\uC9C0\uD1A0\uB9AC\uAC00 \uC544\uB2D9\uB2C8\uB2E4.",
+        "Docs directory is not a git repository."
+      ),
+      path: docsDir,
+      suggestedCommand: `git -C ${quotePath(docsDir)} init`
+    });
+  } else {
+    checks.push({
+      id: "docs_git_repo",
+      status: "ok",
+      title: t(lang, "docs Git \uB808\uD3EC \uCD08\uAE30\uD654", "Docs git repository initialized"),
+      message: t(lang, "docs Git \uB808\uD3EC\uAC00 \uD655\uC778\uB418\uC5C8\uC2B5\uB2C8\uB2E4.", "Docs git repository is available."),
+      path: docsDir
+    });
+    if (!hasHeadCommit(docsDir)) {
+      checks.push({
+        id: "docs_initial_commit",
+        status: "warn",
+        title: t(lang, "docs \uCD08\uAE30 \uCEE4\uBC0B", "Docs initial commit"),
+        message: t(
+          lang,
+          "docs \uCCAB \uCEE4\uBC0B\uC774 \uC5C6\uC2B5\uB2C8\uB2E4. \uCD08\uAE30 \uC124\uC815 \uCEE4\uBC0B\uC744 \uBA3C\uC800 \uC0DD\uC131\uD558\uC138\uC694.",
+          "No initial commit found in docs repo. Create an initial setup commit first."
+        ),
+        path: docsDir,
+        suggestedCommand: `git -C ${quotePath(docsDir)} add . && git -C ${quotePath(docsDir)} commit -m "docs: onboard setup"`
+      });
+    } else {
+      checks.push({
+        id: "docs_initial_commit",
+        status: "ok",
+        title: t(lang, "docs \uCD08\uAE30 \uCEE4\uBC0B", "Docs initial commit"),
+        message: t(lang, "docs \uCD08\uAE30 \uCEE4\uBC0B\uC774 \uC874\uC7AC\uD569\uB2C8\uB2E4.", "Initial commit exists in docs repo."),
+        path: docsDir
+      });
+    }
+    const docsDirty = runGit(["status", "--porcelain=v1"], docsDir);
+    if (docsDirty === void 0) {
+      checks.push({
+        id: "docs_worktree",
+        status: "warn",
+        title: t(lang, "docs \uC791\uC5C5 \uD2B8\uB9AC \uC0C1\uD0DC", "Docs worktree status"),
+        message: t(
+          lang,
+          "docs \uBCC0\uACBD \uC0C1\uD0DC\uB97C \uD655\uC778\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+          "Unable to read docs worktree status."
+        ),
+        path: docsDir
+      });
+    } else if (docsDirty.trim().length > 0) {
+      checks.push({
+        id: "docs_worktree",
+        status: "warn",
+        title: t(lang, "docs \uC791\uC5C5 \uD2B8\uB9AC \uC0C1\uD0DC", "Docs worktree status"),
+        message: t(
+          lang,
+          "\uCEE4\uBC0B\uB418\uC9C0 \uC54A\uC740 docs \uBCC0\uACBD\uC0AC\uD56D\uC774 \uC788\uC2B5\uB2C8\uB2E4.",
+          "Uncommitted docs changes were found."
+        ),
+        path: docsDir,
+        suggestedCommand: `git -C ${quotePath(docsDir)} add . && git -C ${quotePath(docsDir)} commit -m "docs: onboard updates"`
+      });
+    } else {
+      checks.push({
+        id: "docs_worktree",
+        status: "ok",
+        title: t(lang, "docs \uC791\uC5C5 \uD2B8\uB9AC \uC0C1\uD0DC", "Docs worktree status"),
+        message: t(lang, "docs \uC791\uC5C5 \uD2B8\uB9AC\uAC00 \uAE68\uB057\uD569\uB2C8\uB2E4.", "Docs worktree is clean."),
+        path: docsDir
+      });
+    }
+  }
+  const constitutionPath = path19.join(docsDir, "agents", "constitution.md");
+  if (!await fs15.pathExists(constitutionPath)) {
+    checks.push({
+      id: "constitution_exists",
+      status: "block",
+      title: t(lang, "Constitution \uC791\uC131", "Constitution setup"),
+      message: t(
+        lang,
+        "`agents/constitution.md` \uD30C\uC77C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.",
+        "`agents/constitution.md` is missing."
+      ),
+      path: constitutionPath,
+      suggestedCommand: `npx lee-spec-kit update --agents`
+    });
+  } else {
+    const content = await fs15.readFile(constitutionPath, "utf-8");
+    if (hasTemplateMarkers(content)) {
+      checks.push({
+        id: "constitution_filled",
+        status: "block",
+        title: t(lang, "Constitution \uC791\uC131", "Constitution setup"),
+        message: t(
+          lang,
+          "Constitution\uC5D0 \uD15C\uD50C\uB9BF placeholder\uAC00 \uB0A8\uC544 \uC788\uC2B5\uB2C8\uB2E4. \uD504\uB85C\uC81D\uD2B8 \uAE30\uC900\uC73C\uB85C \uBA3C\uC800 \uC791\uC131\uD558\uC138\uC694.",
+          "Constitution still contains template placeholders. Fill project-specific content first."
+        ),
+        path: constitutionPath
+      });
+    } else {
+      checks.push({
+        id: "constitution_filled",
+        status: "ok",
+        title: t(lang, "Constitution \uC791\uC131", "Constitution setup"),
+        message: t(lang, "Constitution\uC774 \uC791\uC131\uB418\uC5C8\uC2B5\uB2C8\uB2E4.", "Constitution looks filled."),
+        path: constitutionPath
+      });
+    }
+  }
+  const customPath = path19.join(docsDir, "agents", "custom.md");
+  if (await fs15.pathExists(customPath)) {
+    const content = await fs15.readFile(customPath, "utf-8");
+    if (hasTemplateMarkers(content)) {
+      checks.push({
+        id: "custom_optional",
+        status: "warn",
+        title: t(lang, "Custom \uADDC\uCE59 \uBB38\uC11C", "Custom rules doc"),
+        message: t(
+          lang,
+          "`agents/custom.md`\uB294 \uC120\uD0DD \uD56D\uBAA9\uC774\uC9C0\uB9CC, \uD604\uC7AC \uD15C\uD50C\uB9BF \uC0C1\uD0DC\uC785\uB2C8\uB2E4. \uD544\uC694\uD558\uBA74 \uADDC\uCE59\uC744 \uC791\uC131\uD558\uC138\uC694.",
+          "`agents/custom.md` is optional, but it still looks like template content. Fill it if your project needs custom rules."
+        ),
+        path: customPath
+      });
+    } else {
+      checks.push({
+        id: "custom_optional",
+        status: "ok",
+        title: t(lang, "Custom \uADDC\uCE59 \uBB38\uC11C", "Custom rules doc"),
+        message: t(lang, "Custom \uADDC\uCE59 \uBB38\uC11C\uAC00 \uAD6C\uC131\uB418\uC5C8\uC2B5\uB2C8\uB2E4.", "Custom rules doc looks configured."),
+        path: customPath
+      });
+    }
+  }
+  const prdDir = path19.join(docsDir, "prd");
+  const featureCount = await countFeatureDirs(docsDir, config.projectType);
+  const prdReady = await hasUserPrdFile(prdDir);
+  if (!prdReady) {
+    checks.push({
+      id: "prd_ready",
+      status: featureCount === 0 ? "block" : "warn",
+      title: t(lang, "PRD \uC900\uBE44 \uC0C1\uD0DC", "PRD readiness"),
+      message: featureCount === 0 ? t(
+        lang,
+        "PRD \uBB38\uC11C\uAC00 \uBE44\uC5B4 \uC788\uC2B5\uB2C8\uB2E4. Feature \uC0DD\uC131 \uC804\uC5D0 PRD\uBD80\uD130 \uC791\uC131\uD558\uC138\uC694.",
+        "PRD is empty. Write PRD first before creating features."
+      ) : t(
+        lang,
+        "PRD \uBB38\uC11C\uAC00 \uBE44\uC5B4 \uC788\uC2B5\uB2C8\uB2E4. \uC774\uBBF8 Feature\uAC00 \uC788\uB2E4\uBA74 PRD\uB97C \uBCF4\uAC15\uD558\uC138\uC694.",
+        "PRD is empty. If features already exist, fill PRD as soon as possible."
+      ),
+      path: prdDir,
+      suggestedCommand: `touch ${quotePath(path19.join(prdDir, `${toSlug(config.projectName || "project")}-prd.md`))}`
+    });
+  } else {
+    checks.push({
+      id: "prd_ready",
+      status: "ok",
+      title: t(lang, "PRD \uC900\uBE44 \uC0C1\uD0DC", "PRD readiness"),
+      message: t(lang, "PRD \uBB38\uC11C\uAC00 \uD655\uC778\uB418\uC5C8\uC2B5\uB2C8\uB2E4.", "PRD document is present."),
+      path: prdDir
+    });
+  }
+  const workflowPolicy = resolveWorkflowPolicy(config.workflow);
+  if (workflowPolicy.mode === "github") {
+    const projectKeys = config.projectType === "multi" ? resolveProjectComponents(config.projectType, config.components) : ["single"];
+    for (const key of projectKeys) {
+      const resolved = resolveProjectGitCwd(config, key, lang);
+      const title = t(
+        lang,
+        config.projectType === "multi" ? `\uD504\uB85C\uC81D\uD2B8 Git \uC5F0\uACB0 (${key})` : "\uD504\uB85C\uC81D\uD2B8 Git \uC5F0\uACB0",
+        config.projectType === "multi" ? `Project git connectivity (${key})` : "Project git connectivity"
+      );
+      if (resolved.warning || !resolved.cwd) {
+        checks.push({
+          id: `project_git_${key}`,
+          status: "block",
+          title,
+          message: resolved.warning || t(
+            lang,
+            "\uD504\uB85C\uC81D\uD2B8 \uB808\uD3EC \uACBD\uB85C\uB97C \uD655\uC778\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+            "Project repository path could not be resolved."
+          )
+        });
+        continue;
+      }
+      if (!isGitRepo(resolved.cwd)) {
+        checks.push({
+          id: `project_git_${key}`,
+          status: "block",
+          title,
+          message: t(
+            lang,
+            "\uD504\uB85C\uC81D\uD2B8 \uACBD\uB85C\uAC00 Git \uB808\uD3EC\uC9C0\uD1A0\uB9AC\uAC00 \uC544\uB2D9\uB2C8\uB2E4.",
+            "Project path is not a git repository."
+          ),
+          path: resolved.cwd,
+          suggestedCommand: `git -C ${quotePath(resolved.cwd)} init`
+        });
+        continue;
+      }
+      const origin = getOriginUrl(resolved.cwd);
+      if (!origin) {
+        checks.push({
+          id: `project_origin_${key}`,
+          status: "block",
+          title: t(
+            lang,
+            config.projectType === "multi" ? `\uD504\uB85C\uC81D\uD2B8 origin \uC124\uC815 (${key})` : "\uD504\uB85C\uC81D\uD2B8 origin \uC124\uC815",
+            config.projectType === "multi" ? `Project origin configured (${key})` : "Project origin configured"
+          ),
+          message: t(
+            lang,
+            "GitHub \uC6CC\uD06C\uD50C\uB85C\uC6B0\uB97C \uC704\uD574 \uD504\uB85C\uC81D\uD2B8 \uB808\uD3EC\uC758 origin remote\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+            "Project repo origin remote is required for github workflow."
+          ),
+          path: resolved.cwd,
+          suggestedCommand: `git -C ${quotePath(resolved.cwd)} remote add origin <git-url>`
+        });
+      } else {
+        checks.push({
+          id: `project_origin_${key}`,
+          status: "ok",
+          title: t(
+            lang,
+            config.projectType === "multi" ? `\uD504\uB85C\uC81D\uD2B8 origin \uC124\uC815 (${key})` : "\uD504\uB85C\uC81D\uD2B8 origin \uC124\uC815",
+            config.projectType === "multi" ? `Project origin configured (${key})` : "Project origin configured"
+          ),
+          message: t(
+            lang,
+            `origin\uC774 \uC124\uC815\uB418\uC5B4 \uC788\uC2B5\uB2C8\uB2E4: ${origin}`,
+            `origin is configured: ${origin}`
+          ),
+          path: resolved.cwd
+        });
+      }
+    }
+  }
+  if (config.docsRepo === "standalone" && config.pushDocs) {
+    const origin = getOriginUrl(docsDir);
+    if (!origin) {
+      checks.push({
+        id: "docs_origin",
+        status: "block",
+        title: t(lang, "docs origin \uC124\uC815", "Docs origin configured"),
+        message: t(
+          lang,
+          "standalone + pushDocs=true \uC124\uC815\uC5D0\uC11C\uB294 docs origin remote\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+          "docs origin remote is required when standalone + pushDocs=true."
+        ),
+        path: docsDir,
+        suggestedCommand: `git -C ${quotePath(docsDir)} remote add origin <docs-git-url>`
+      });
+    } else {
+      checks.push({
+        id: "docs_origin",
+        status: "ok",
+        title: t(lang, "docs origin \uC124\uC815", "Docs origin configured"),
+        message: t(lang, `origin\uC774 \uC124\uC815\uB418\uC5B4 \uC788\uC2B5\uB2C8\uB2E4: ${origin}`, `origin is configured: ${origin}`),
+        path: docsDir
+      });
+    }
+  }
+  return finalizeChecks(checks);
+}
+function onboardCommand(program2) {
+  program2.command("onboard").description("Run onboarding checks for initial setup").option("--json", "Output in JSON format for agents").option("--strict", "Exit with code 1 when WARN/BLOCK exists").action(async (options) => {
+    try {
+      await runOnboard(options);
+    } catch (error) {
+      const config = await getConfig(process.cwd());
+      const lang = config?.lang ?? DEFAULT_LANG;
+      const cliError = toCliError(error);
+      const suggestions = getCliErrorSuggestions(cliError.code, lang);
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            status: "error",
+            reasonCode: cliError.code,
+            error: cliError.message,
+            suggestions
+          })
+        );
+      } else {
+        console.error(
+          chalk6.red(tr(lang, "cli", "common.errorLabel")),
+          chalk6.red(`[${cliError.code}] ${cliError.message}`)
+        );
+        printCliErrorSuggestions(suggestions, lang);
+      }
+      process.exit(1);
+    }
+  });
+}
+async function runOnboard(options) {
+  const config = await getConfig(process.cwd());
+  if (!config) {
+    throw createCliError(
+      "CONFIG_NOT_FOUND",
+      tr(DEFAULT_LANG, "cli", "common.configNotFound")
+    );
+  }
+  const lang = config.lang;
+  const result = await runOnboardChecks(config);
+  if (options.json) {
+    const payload = {
+      status: "ok",
+      reasonCode: result.status === "ready" ? "ONBOARD_READY" : result.status === "needs_action" ? "ONBOARD_NEEDS_ACTION" : "ONBOARD_BLOCKED",
+      docsDir: config.docsDir,
+      docsRepo: config.docsRepo || "embedded",
+      workflow: resolveWorkflowPolicy(config.workflow),
+      summary: result.summary,
+      checks: result.checks
+    };
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    printOnboardResult(lang, result);
+  }
+  if (options.strict && (result.summary.warn > 0 || result.summary.block > 0)) {
+    process.exitCode = 1;
+  }
+}
 function isBannerDisabled() {
   const v = (process.env.LEE_SPEC_KIT_NO_BANNER || "").trim();
   return v === "1";
@@ -10233,4 +10861,5 @@ flowCommand(program);
 githubCommand(program);
 docsCommand(program);
 detectCommand(program);
+onboardCommand(program);
 await program.parseAsync();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lee-spec-kit",
-  "version": "0.6.16",
+  "version": "0.6.17",
   "description": "Project documentation structure generator for AI-assisted development",
   "type": "module",
   "bin": {

package/templates/en/common/README.md

@@ -5,11 +5,14 @@ This documentation is organized by feature to help agents quickly understand the
 ## Agent Session Start Checklist
 
 ```bash
+# (recommended once at start) run onboarding checks
+npx lee-spec-kit onboard --strict
+
 # 1) Detect project
 npx lee-spec-kit detect --json
 
 # 2) If detected, read context first
-npx lee-spec-kit context --json
+npx lee-spec-kit context --json-compact
 ```
 
 - Apply lee-spec-kit workflow only when `isLeeSpecKitProject: true`.
@@ -20,7 +23,8 @@ npx lee-spec-kit context --json
 
 - Scaffold the code project first (for example Next.js/NestJS), then run `lee-spec-kit init`.
 - After that, verify detection with `detect --json`, then continue with `feature` and `context`.
-- This sequence assumes default `docsRepo: embedded`. For `standalone`, run against the docs repo path (`--dir` or `LEE_SPEC_KIT_DOCS_DIR`).
+- In most cases (default: embedded), the steps above are all you need.
+- Choose standalone only when docs are managed separately from the code repo. In that case, prefer running init from a parent workspace folder (for example `workspace/docs`, `workspace/project`) and set both docs/project paths together. (e.g. `npx lee-spec-kit init --docs-repo standalone --dir ./docs --project-root ./project`)
 
 ## Directory Structure
 

package/templates/en/common/agents/agents.md

@@ -33,7 +33,7 @@ Prohibited:
 ## 🧾 Label Response Contract (SSOT)
 
 - End **every user-facing reply** with current status + available labels.
-- Use the latest `npx lee-spec-kit context --json` (or `flow --json`) as source.
+- Use the latest `npx lee-spec-kit context --json-compact` as the default source (fallback: `context --json` or `flow --json` when full detail is required).
 - Use `actionOptions[].detail` or command `cmd` **verbatim**. Do not paraphrase.
 - Even when the user asks something else, append the same label block at the end if executable labels exist.
 - If no executable labels exist, print `Available labels: none` and guide re-check with `npx lee-spec-kit context`.

package/templates/en/common/features/feature-base/issue.md

@@ -22,12 +22,8 @@
 - [ ] (verifiable criterion 1)
 - [ ] (verifiable criterion 2)
 
-## Out of Scope
-
-- (what this issue does not cover)
-
 ## Related Docs
 
-- Spec: `./spec.md`
-- Plan: `./plan.md`
-- Tasks: `./tasks.md`
+- Spec: `docs/.../spec.md`
+- Plan: `docs/.../plan.md`
+- Tasks: `docs/.../tasks.md`

package/templates/en/common/features/feature-base/pr.md

@@ -27,6 +27,6 @@
 
 ## Related Docs
 
-- Spec: `./spec.md`
-- Tasks: `./tasks.md`
-- Decisions: `./decisions.md`
+- Spec: `docs/.../spec.md`
+- Tasks: `docs/.../tasks.md`
+- Decisions: `docs/.../decisions.md`

package/templates/ko/common/README.md

@@ -5,11 +5,14 @@
 ## 에이전트 세션 시작 체크리스트
 
 ```bash
+# (최초 1회 권장) 초기 온보딩 점검
+npx lee-spec-kit onboard --strict
+
 # 1) 프로젝트 감지
 npx lee-spec-kit detect --json
 
 # 2) 감지 성공 시 컨텍스트 조회
-npx lee-spec-kit context --json
+npx lee-spec-kit context --json-compact
 ```
 
 - `isLeeSpecKitProject: true`일 때만 lee-spec-kit 워크플로우를 적용합니다.
@@ -20,7 +23,8 @@ npx lee-spec-kit context --json
 
 - 코드 프로젝트 스캐폴딩(예: Next.js/NestJS) 후 `lee-spec-kit init`을 실행하세요.
 - 그 다음 `detect --json`으로 감지 결과를 확인하고, `feature`/`context` 순서로 진행하세요.
-- 위 순서는 기본값인 `docsRepo: embedded` 기준입니다. `standalone`이면 docs 레포 경로 기준(`--dir` 또는 `LEE_SPEC_KIT_DOCS_DIR`)으로 실행하세요.
+- 대부분의 경우(기본값: embedded) 위 순서만 따르면 됩니다.
+- docs를 코드 저장소와 분리해 운영할 때만 standalone을 선택하세요. 이때는 상위 워크스페이스 폴더(예: `workspace/docs`, `workspace/project`)에서 `init`을 실행해 docs/project 경로를 함께 지정하는 방식을 권장합니다. (예: `npx lee-spec-kit init --docs-repo standalone --dir ./docs --project-root ./project`)
 
 ## 상위 구조 요약
 

package/templates/ko/common/agents/agents.md

@@ -33,7 +33,7 @@
 ## 🧾 라벨 응답 계약 (SSOT)
 
 - 사용자에게 보내는 **모든 응답의 마지막**에 현재 상태 + 선택 가능한 라벨을 표시합니다.
-- 기준 데이터는 최신 `npx lee-spec-kit context --json`(또는 `flow --json`)입니다.
+- 기준 데이터는 최신 `npx lee-spec-kit context --json-compact`를 기본으로 사용하고, 상세 필드가 필요할 때만 `context --json`(또는 `flow --json`)을 사용합니다.
 - 라벨 설명은 `actionOptions[].detail` 또는 command `cmd`를 **원문 그대로** 사용합니다. (요약/의역 금지)
 - 사용자가 다른 질문을 하더라도, 실행 가능한 라벨이 있으면 응답 마지막에 동일 블록을 다시 표시합니다.
 - 실행 가능한 라벨이 없으면 `선택 가능: 없음` + `npx lee-spec-kit context` 재확인을 안내합니다.

package/templates/ko/common/features/feature-base/issue.md

@@ -22,12 +22,8 @@
 - [ ] (검증 가능한 완료 기준 1)
 - [ ] (검증 가능한 완료 기준 2)
 
-## 제외 범위
-
-- (이번 이슈에서 다루지 않는 내용)
-
 ## 관련 문서
 
-- Spec: `./spec.md`
-- Plan: `./plan.md`
-- Tasks: `./tasks.md`
+- Spec: `docs/.../spec.md`
+- Plan: `docs/.../plan.md`
+- Tasks: `docs/.../tasks.md`

package/templates/ko/common/features/feature-base/pr.md

@@ -27,6 +27,6 @@
 
 ## 관련 문서
 
-- Spec: `./spec.md`
-- Tasks: `./tasks.md`
-- Decisions: `./decisions.md`
+- Spec: `docs/.../spec.md`
+- Tasks: `docs/.../tasks.md`
+- Decisions: `docs/.../decisions.md`