feat(onboarding): add natural-language initialization

.agents/mcp_config.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "cladding": {
+      "command": "node",
+      "args": [
+        ".cladding/host/serve.cjs"
+      ]
+    }
+  }
+}

.agents/skills/cladding-init/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: cladding-init
+description: Use only when the user explicitly names Cladding and asks to initialize, adopt, or refresh it; never use for an ordinary project creation or implementation request. Scaffold from an idea, planning document, or existing project through the MCP prepare/apply flow.
+---
+
+# Cladding init
+
+Use this workflow only when the user explicitly asks to initialize, adopt, or refresh Cladding. Opening a repository alone is not consent to initialize it.
+
+## Required host workflow
+
+If the current user message itself matches `APPLY CLADDING XXXXXX`, do not call prepare or stage again. Call `clad_init` once and copy the entire user message, including the `APPLY CLADDING` prefix, into `confirmation`.
+
+1. If a greenfield request has no project intent, ask for one short description.
+2. Call `clad_prepare_init` with exactly one starting mode:
+   - `idea` with the user's description.
+   - `document` with a project-relative planning-document path.
+   - `existing` for an existing codebase; include an optional adoption goal.
+3. Read the returned prompt and observations. Draft the structured object required by `clad_init` using the current host model, then call `clad_stage_init` with the preparation token and that draft. Staging validates the draft and stores only ignored runtime state under `.cladding/host/`; it does not modify authored project files.
+4. Show `plannedChanges`, the staged `confirmationQuestion`, and its one-time `approvalChallenge` to the user, then stop and wait for a separate reply. The original initialization request is not confirmation.
+5. Only when the user's separate reply exactly matches `approvalChallenge`, call `clad_init` with the entire reply verbatim as `confirmation`—never strip the `APPLY CLADDING` prefix. Include the draft and token when the host retained them; process-per-turn hosts may omit both because Cladding resolves the exact staged draft from its short-lived machine-local cache. Questions, paraphrases, and generic acknowledgements are not approval.
+6. If `nextQuestion` is present, show it verbatim and end the assistant turn immediately. Never answer it, infer an answer, or call either clarify tool during the initialization-approval turn. Continue with the Cladding clarify workflow only after a new user message supplies the answer. If no question remains, report that ordinary development can begin.
+
+Do not run `clad init` in a shell from an AI-host onboarding session. Do not use MCP sampling. If the MCP tools are absent, tell the user to run `clad setup`, restart the AI host in the project directory, and stop without writing project files.
+
+`clad_prepare_init` does not modify the workspace, and `clad_stage_init` writes only ignored runtime state. Never call stage and apply in the same assistant turn. Only `clad_init` writes authored artifacts, after explicit user confirmation plus schema and freshness validation. A stale, malformed, or replayed apply request must be prepared again.
+
+The raw CLI remains available for terminal, CI, offline, and explicitly configured SDK automation; it is not the primary host onboarding path.

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "claude-code",
       "source": "./plugins/claude-code",
       "description": "Reference implementation of the Ironclad standard — multi-agent dev harness for Claude Code.",
-      "version": "0.8.3",
+      "version": "0.9.0",
       "author": {
         "name": "qwerfunch"
       },

.claude/skills/cladding-init/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: cladding-init
+description: Use only when the user explicitly names Cladding and asks to initialize, adopt, or refresh it; never use for an ordinary project creation or implementation request. Scaffold from an idea, planning document, or existing project through the MCP prepare/apply flow.
+---
+
+# Cladding init
+
+Use this workflow only when the user explicitly asks to initialize, adopt, or refresh Cladding. Opening a repository alone is not consent to initialize it.
+
+## Required host workflow
+
+If the current user message itself matches `APPLY CLADDING XXXXXX`, do not call prepare or stage again. Call `clad_init` once and copy the entire user message, including the `APPLY CLADDING` prefix, into `confirmation`.
+
+1. If a greenfield request has no project intent, ask for one short description.
+2. Call `clad_prepare_init` with exactly one starting mode:
+   - `idea` with the user's description.
+   - `document` with a project-relative planning-document path.
+   - `existing` for an existing codebase; include an optional adoption goal.
+3. Read the returned prompt and observations. Draft the structured object required by `clad_init` using the current host model, then call `clad_stage_init` with the preparation token and that draft. Staging validates the draft and stores only ignored runtime state under `.cladding/host/`; it does not modify authored project files.
+4. Show `plannedChanges`, the staged `confirmationQuestion`, and its one-time `approvalChallenge` to the user, then stop and wait for a separate reply. The original initialization request is not confirmation.
+5. Only when the user's separate reply exactly matches `approvalChallenge`, call `clad_init` with the entire reply verbatim as `confirmation`—never strip the `APPLY CLADDING` prefix. Include the draft and token when the host retained them; process-per-turn hosts may omit both because Cladding resolves the exact staged draft from its short-lived machine-local cache. Questions, paraphrases, and generic acknowledgements are not approval.
+6. If `nextQuestion` is present, show it verbatim and end the assistant turn immediately. Never answer it, infer an answer, or call either clarify tool during the initialization-approval turn. Continue with the Cladding clarify workflow only after a new user message supplies the answer. If no question remains, report that ordinary development can begin.
+
+Do not run `clad init` in a shell from an AI-host onboarding session. Do not use MCP sampling. If the MCP tools are absent, tell the user to run `clad setup`, restart the AI host in the project directory, and stop without writing project files.
+
+`clad_prepare_init` does not modify the workspace, and `clad_stage_init` writes only ignored runtime state. Never call stage and apply in the same assistant turn. Only `clad_init` writes authored artifacts, after explicit user confirmation plus schema and freshness validation. A stale, malformed, or replayed apply request must be prepared again.
+
+The raw CLI remains available for terminal, CI, offline, and explicitly configured SDK automation; it is not the primary host onboarding path.

.codex/config.toml

@@ -0,0 +1,5 @@
+[mcp_servers.cladding]
+command = "node"
+args = [ ".cladding/host/serve.cjs" ]
+description = "cladding MCP server (project-scoped by `clad setup`)"
+default_tools_approval_mode = "writes"

.cursor/cli.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Mcp(cladding:clad_list_features)",
+      "Mcp(cladding:clad_get_feature)",
+      "Mcp(cladding:clad_run_check)"
+    ],
+    "deny": []
+  }
+}

.cursor/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "cladding": {
+      "command": "node",
+      "args": [
+        ".cladding/host/serve.cjs"
+      ]
+    }
+  }
+}

.cursor/rules/cladding-bootstrap.mdc

@@ -0,0 +1,7 @@
+---
+description: Cladding bootstrap boundary
+alwaysApply: true
+---
+
+Cladding is available only in this project. Do not initialize or invoke Cladding for ordinary work.
+Use the cladding-init skill only when the user explicitly names Cladding and asks to initialize, adopt, or refresh it.

.cursor/skills/cladding-init/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: cladding-init
+description: Use only when the user explicitly names Cladding and asks to initialize, adopt, or refresh it; never use for an ordinary project creation or implementation request. Scaffold from an idea, planning document, or existing project through the MCP prepare/apply flow.
+---
+
+# Cladding init
+
+Use this workflow only when the user explicitly asks to initialize, adopt, or refresh Cladding. Opening a repository alone is not consent to initialize it.
+
+## Required host workflow
+
+If the current user message itself matches `APPLY CLADDING XXXXXX`, do not call prepare or stage again. Call `clad_init` once and copy the entire user message, including the `APPLY CLADDING` prefix, into `confirmation`.
+
+1. If a greenfield request has no project intent, ask for one short description.
+2. Call `clad_prepare_init` with exactly one starting mode:
+   - `idea` with the user's description.
+   - `document` with a project-relative planning-document path.
+   - `existing` for an existing codebase; include an optional adoption goal.
+3. Read the returned prompt and observations. Draft the structured object required by `clad_init` using the current host model, then call `clad_stage_init` with the preparation token and that draft. Staging validates the draft and stores only ignored runtime state under `.cladding/host/`; it does not modify authored project files.
+4. Show `plannedChanges`, the staged `confirmationQuestion`, and its one-time `approvalChallenge` to the user, then stop and wait for a separate reply. The original initialization request is not confirmation.
+5. Only when the user's separate reply exactly matches `approvalChallenge`, call `clad_init` with the entire reply verbatim as `confirmation`—never strip the `APPLY CLADDING` prefix. Include the draft and token when the host retained them; process-per-turn hosts may omit both because Cladding resolves the exact staged draft from its short-lived machine-local cache. Questions, paraphrases, and generic acknowledgements are not approval.
+6. If `nextQuestion` is present, show it verbatim and end the assistant turn immediately. Never answer it, infer an answer, or call either clarify tool during the initialization-approval turn. Continue with the Cladding clarify workflow only after a new user message supplies the answer. If no question remains, report that ordinary development can begin.
+
+Do not run `clad init` in a shell from an AI-host onboarding session. Do not use MCP sampling. If the MCP tools are absent, tell the user to run `clad setup`, restart the AI host in the project directory, and stop without writing project files.
+
+`clad_prepare_init` does not modify the workspace, and `clad_stage_init` writes only ignored runtime state. Never call stage and apply in the same assistant turn. Only `clad_init` writes authored artifacts, after explicit user confirmation plus schema and freshness validation. A stale, malformed, or replayed apply request must be prepared again.
+
+The raw CLI remains available for terminal, CI, offline, and explicitly configured SDK automation; it is not the primary host onboarding path.

.gemini/settings.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "cladding": {
+      "command": "node",
+      "args": [
+        ".cladding/host/serve.cjs"
+      ]
+    }
+  }
+}

.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "cladding": {
+      "command": "node",
+      "args": [
+        ".cladding/host/serve.cjs"
+      ]
+    }
+  }
+}

CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to Cladding are documented here.
 Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/).
 Versioning: [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] — Project-scoped natural-language onboarding (2026-07-16)
+
+**In one line:** apply Cladding from ordinary conversation without a shell command, while project-local discovery, a read-only preview, an exact approval phrase, and atomic recovery keep onboarding bounded.
+
+### MCP host (clad serve)
+
+- **Start from an idea, a complete UTF-8 planning document, or an existing codebase.** The host reuses the CLI onboarding engine, keeps the full document and observed source evidence, and asks at most three material follow-up questions only when decisions remain open.
+- **Preview before any authored file changes.** Initialization requires the exact one-time phrase shown after validation and staging; malformed, stale, replayed, or partially applied drafts leave the project at its pre-apply content.
+- **Resume across host restarts.** Process-per-turn hosts retain the exact staged draft in ignored project runtime state instead of reconstructing intent from an approval code.
+- **Keep activation inside the selected project.** Setup no longer exposes Cladding tools to unrelated projects, removes only provably owned legacy global wiring, and uses the same project runtime for MCP and later shell validation.
+- **Expose only the initialization bootstrap before `spec.yaml` exists.** The ordinary development tool surface becomes available after successful initialization.
+
+### Spec governance (4-tier SSoT)
+
+- **Onboarding now seeds capabilities and user journeys into the governed design.** Early generated links remain informational until the shared maturity threshold, while invalid references and under-bound flows still block.
+- **Completed onboarding hands off to ordinary natural-language development** and distinguishes on-demand checks from opt-in hook or CI enforcement.
+
+### Gate and toolchain fidelity
+
+- **JavaScript projects follow their declared tools.** Custom scripts win; Jest, Vitest, ESLint, Biome, and Oxlint are selected from project evidence, and architecture checks include TSX, JSX, JavaScript, and TypeScript.
+- **A missing runnable deliverable stays honest.** Safe declared entries run, broken entries block, and an early onboarding seed is not forced to invent an unsafe smoke command.
+- **Verification evidence remains non-vacuous.** Done features must execute a passing declared test, spec-conformance oracles preserve full-suite evidence, and unavailable tools remain skips rather than false passes.
+
+### Hardened by the packed-tarball E2E campaign (2026-07-16)
+
+A live campaign installed the packed 0.9.0 tarball in isolation and drove real init scenarios through all five host CLIs (report: `docs/dogfood/e2e-0.9.0-packed-2026-07-16.md`). The consent boundary held on every host that ran; these defects were found and fixed:
+
+- **Setup wires only detected hosts by default.** Previously every project received all five hosts' config files regardless of what was installed; `clad setup --host all` remains the explicit override.
+- **Antigravity actually connects now.** agy reads MCP config machine-wide only (a negative control proved the project file is never loaded), so setup also writes an ownership-guarded `~/.gemini/config/plugins/cladding/` wire — the one stated exception to project-local activation; sessions still resolve the project from their working directory.
+- **`clad update` outside a cladding project writes nothing.** It used to scaffold host wiring into any directory and could reach an account-wide legacy plugin uninstall.
+- **Abandoned onboarding preparations no longer accumulate.** Expired consent-cache envelopes are swept on staging (hundreds had piled up in the shared temp dir), and a tampered staged draft is now re-validated and rejected cleanly instead of surfacing a raw crash.
+- **Legacy cleanup preserves your global config formatting.** The codex `config.toml` entry is now spliced out textually (comments and ordering survive, parse-verified), and cursor cleanup no longer leaves an orphan empty `mcpServers`.
+- **`clad doctor --hosts` probes match the project-local model** (project-MCP approval for the consented Claude probe, project-directory Antigravity probe, Codex approvals bypass, and a realistic gate timeout).
+
+### Also changed
+
+- The deterministic collector found nine onboarding commit subjects that do not name a spec feature. Their user-visible behavior is covered by the spec-backed notes above, but their commit-to-spec linkage remains absent.
+
+### 한국어 요약
+
+**한 줄 요약:** 이제 셸 명령 없이 자연어로 Cladding을 적용할 수 있으며, 프로젝트 로컬 연결·읽기 전용 미리보기·정확한 승인 문구·원자적 복구가 온보딩 변경 범위를 지킵니다.
+
+- 아이디어·전체 UTF-8 기획 문서·기존 코드 중 어디서든 시작하고, 결정이 남은 경우에만 최대 3개의 핵심 질문을 받습니다.
+- 초기화 전에는 준비용 MCP 도구 3개만 노출되며, 정확한 일회용 승인 문구로 적용한 뒤 전체 개발 도구가 열립니다.
+- 실제 5개 호스트 CLI에 패키징된 tarball을 설치해 검증하는 E2E 캠페인을 거쳤습니다 — 설치된 호스트만 배선, Antigravity 연결 수리, 임시 파일 잔존 정리 등 캠페인이 찾은 결함을 모두 수정했습니다.
+- 호스트가 재시작돼도 검토한 초안을 그대로 적용하고, 실패·오래된 요청·재사용 요청은 프로젝트를 부분 변경 상태로 남기지 않습니다.
+
 ## [0.8.3] — Agent loops that stop honestly, a guard against unverified "done", and a faster check (2026-07-12)
 
 This release helps you build AI agent loops that stop when the work is genuinely finished, closes a hole where a feature could look done without its tests ever running, makes the pre-push check faster, and ships native Japanese and Chinese documentation.

CLAUDE.md

@@ -25,7 +25,7 @@ Files `F-082` ~ `F-090` were the *drift period* (authored after v0.3.9 but bypas
 
 ## Version bumps — use the script
 
-Don't hand-edit version strings. There are nine sites (incl. `.claude-plugin/marketplace.json`, the marketplace *catalog* the Claude Code host reads to detect "update available"); missing one breaks `HARNESS_INTEGRITY` (which now also guards the marketplace catalog version). Run:
+Don't hand-edit version strings. There are eleven sites (incl. `.claude-plugin/marketplace.json`, the marketplace *catalog* the Claude Code host reads to detect "update available"); missing one breaks `HARNESS_INTEGRITY` (which now also guards the marketplace catalog version). Run:
 
 ```bash
 npm run version-bump -- 0.3.X
@@ -46,7 +46,7 @@ When you add a drift detector under `src/stages/detectors/`:
 
 A user-explicit instruction ("release vX.Y.Z") triggers the ritual:
 
-1. `npm run version-bump -- X.Y.Z` (all nine sites) + `npm install` (refresh the committed `package-lock.json` to the new version — CI's `npm ci` fails on a stale lock) + `npm run build` + GREEN `npm test` / `clad check --strict`
+1. `npm run version-bump -- X.Y.Z` (all eleven sites) + `npm install` (refresh the committed `package-lock.json` to the new version — CI's `npm ci` fails on a stale lock) + `npm run build` + GREEN `npm test` / `clad check --strict`
 2. open a **PR `develop → main`** and merge it with the GitHub **"Create a merge commit"** button — NEVER squash, NEVER rebase (see the squash-ban below)
 3. `git tag vX.Y.Z` on main's merge commit
 4. push main + tag, then **back-merge `main → develop`** (`git checkout develop && git merge origin/main && git push`) so develop keeps the release commit in its ancestry — skip this and the next release PR phantom-conflicts