scene-capability-engine 3.6.60 → 3.6.62

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.62] - 2026-03-21
+
+### Removed
+- Removed the OpenHands-specific `sce studio events --openhands-events <path>` bridge so current SCE no longer exposes a vendor-specific event-ingestion path in the active CLI surface.
+
+## [3.6.61] - 2026-03-20
+
+### Added
+- Added `sce project candidate inspect --root <path> --json` as the canonical single-root inspection contract for workspace-backed roots, local `.sce` candidates, ordinary directory candidates, and invalid roots.
+- Added `sce project onboarding import --root <path> --json` as the canonical root-based onboarding entry, reusing the ordered `register/attach/hydrate/activate/scaffold` step envelope instead of inventing a second import receipt.
+
+### Changed
+- MagicBall-facing multi-project docs, command reference, CLI examples, frontend mapping, and release-time project-contract audit now include `project candidate inspect` and `project onboarding import` alongside the existing portfolio/target/supervision contracts.
+- Root-based onboarding now suppresses internal adoption progress logs in `--json` mode so adapters receive clean machine-readable envelopes.
+
 ## [3.6.60] - 2026-03-19
 
 ### Changed

package/README.md

@@ -155,7 +155,7 @@ SCE is opinionated by default.
 For IDEs, AI shells, or custom frontends, the most important SCE surfaces are:
 
 - `sce studio plan|generate|apply|verify|release`
-- `sce studio events --openhands-events <path>`
+- `sce studio events`
 - `sce task ref|show|rerun`
 - `sce timeline save|list|show|restore`
 - `sce capability inventory`
@@ -174,7 +174,7 @@ MagicBall-specific integration surfaces now also include:
 - `sce app registry status|configure|sync*`
 - `sce app runtime show|releases|install|activate|uninstall`
 - `sce app engineering preview|ownership|open|import|show|attach|hydrate|scaffold|activate`
-- `sce project portfolio show|target resolve|supervision show`
+- `sce project portfolio show|candidate inspect|onboarding import|target resolve|supervision show`
 - `sce mode application|ontology|engineering home`
 - `sce pm requirement|tracking|planning|change|issue ... --json`
 - `sce ontology er|br|dl ... --json`
@@ -230,5 +230,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.60
-**Last Updated**: 2026-03-19
+**Version**: 3.6.62
+**Last Updated**: 2026-03-21

package/README.zh.md

@@ -160,7 +160,7 @@ SCE 默认是强治理的。
 如果你要对接 IDE、AI 助手或前端，优先关注这些接口面：
 
 - `sce studio plan|generate|apply|verify|release`
-- `sce studio events --openhands-events <path>`
+- `sce studio events`
 - `sce task ref|show|rerun`
 - `sce timeline save|list|show|restore`
 - `sce capability inventory`
@@ -179,7 +179,7 @@ SCE 默认是强治理的。
 - `sce app registry status|configure|sync*`
 - `sce app runtime show|releases|install|activate|uninstall`
 - `sce app engineering preview|ownership|open|import|show|attach|hydrate|scaffold|activate`
-- `sce project portfolio show|target resolve|supervision show`
+- `sce project portfolio show|candidate inspect|onboarding import|target resolve|supervision show`
 - `sce mode application|ontology|engineering home`
 - `sce pm requirement|tracking|planning|change|issue ... --json`
 - `sce ontology er|br|dl ... --json`
@@ -235,5 +235,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.60
-**最后更新**：2026-03-19
+**版本**：3.6.62
+**最后更新**：2026-03-21

package/docs/command-reference.md

@@ -744,8 +744,6 @@ sce studio resume --job <job-id> --json
 
 # Inspect recent stage events
 sce studio events --job <job-id> --limit 50 --json
-# Map OpenHands raw events into the same task-stream contract
-sce studio events --job <job-id> --openhands-events ./openhands-events.json --json
 
 # Rollback a job after apply/release
 sce studio rollback --job <job-id> --reason "manual-check-failed" --json
@@ -779,7 +777,6 @@ Studio JSON output now includes a stable UI-oriented task stream contract (in ad
 - `task.evidence[]`: structured evidence references
 - `task.feedback_model`: human-facing task feedback (`problem`, `execution`, `diagnosis`, `evidence`, `next_step`, `mb_status`)
 - `event[]`: raw audit event stream (`studio events` also keeps legacy `events[]` for compatibility)
-- `studio events --openhands-events <path>` switches `source_stream=openhands` and maps OpenHands raw events to the same task contract fields.
 - hierarchical task reference lookup/rerun:
   - `sce task show --ref <SS.PP.TT> --json`
   - `sce task rerun --ref <SS.PP.TT> [--dry-run] --json`
@@ -2660,7 +2657,7 @@ Overall Health: 2 healthy, 1 unhealthy
 
 ---
 
-## Project Portfolio And Supervision
+## Project Portfolio, Candidate Inspection, And Onboarding
 
 #### `sce project portfolio show`
 
@@ -2680,6 +2677,42 @@ sce project portfolio show [options]
 - Marks inaccessible or partial projects explicitly instead of dropping them
 - Reuses project-local session governance signals to summarize active sessions and last activity
 
+#### `sce project candidate inspect`
+
+Inspect one local root through the canonical engine-owned project-candidate contract.
+
+**Usage:**
+```bash
+sce project candidate inspect --root <path> [options]
+```
+
+**Options:**
+- `--root <path>` - Local root directory to inspect
+- `--json` - Output the canonical `LocalProjectCandidateInspection`
+
+**Behavior:**
+- Distinguishes `workspace-backed`, `local-sce-candidate`, `directory-candidate`, and `invalid`
+- Reuses deterministic project/workspace identity when the root already maps to a registered workspace
+- Returns canonical readiness, availability, and reason codes without adapter-side path heuristics
+
+#### `sce project onboarding import`
+
+Import one local root into the canonical project portfolio using root-based onboarding.
+
+**Usage:**
+```bash
+sce project onboarding import --root <path> [options]
+```
+
+**Options:**
+- `--root <path>` - Local root directory to import
+- `--json` - Output the canonical `ProjectOnboardingImportResult`
+
+**Behavior:**
+- Accepts a local root as the primary onboarding target without app-bundle-first indirection
+- Reuses the canonical ordered step envelope (`register`, `attach`, `hydrate`, `activate`, `scaffold`)
+- Registers onboarded roots into the workspace-backed portfolio without inventing a second registry
+
 #### `sce project target resolve`
 
 Resolve one target project for cross-project flows without mutating active workspace selection.

package/docs/magicball-adaptation-task-checklist-v1.md

@@ -68,6 +68,20 @@ Done when:
 - drillback panels use `items[]` directly
 - frontend does not present `cursor` as a raw event-stream offset
 
+### Task 0.5
+Preflight user-picked local roots with the canonical candidate contract, then onboard by root when needed.
+
+Commands:
+```bash
+sce project candidate inspect --root "<path>" --json
+sce project onboarding import --root "<path>" --json
+```
+
+Done when:
+- frontend does not infer project validity from ad hoc `.sce` path heuristics alone
+- existing local `.sce` roots are imported without rebuilding them blindly
+- ordinary directories can be onboarded without pretending to be app-library items first
+
 ## Phase 1: App Entry And Mode Switching
 
 ### Task 1.1

package/docs/magicball-cli-invocation-examples.md

@@ -24,6 +24,8 @@ Assume:
 ### 1.0 Read multi-project portfolio baseline
 ```bash
 sce project portfolio show --json
+sce project candidate inspect --root "C:/workspace/customer-order-demo" --json
+sce project onboarding import --root "C:/workspace/customer-order-demo" --json
 sce project target resolve --request "continue customer-order-demo" --json
 sce project supervision show --project workspace:customer-order-demo --json
 ```

package/docs/magicball-frontend-state-and-command-mapping.md

@@ -65,6 +65,8 @@ Recommended shape:
 ```ts
 interface ProjectWorkspaceShellState {
   projectPortfolio: Record<string, unknown> | null
+  projectCandidate: Record<string, unknown> | null
+  projectOnboarding: Record<string, unknown> | null
   currentProjectId: string | null
   projectTarget: Record<string, unknown> | null
   projectSupervision: Record<string, unknown> | null
@@ -73,11 +75,14 @@ interface ProjectWorkspaceShellState {
 
 Owned commands:
 - `sce project portfolio show --json`
+- `sce project candidate inspect --root <path> --json`
+- `sce project onboarding import --root <path> --json`
 - `sce project target resolve --request <text> --current-project <project-id> --json`
 - `sce project supervision show --project <project-id> --json`
 
 Rule:
 - multi-project shell must consume engine-owned project truth directly
+- manual local-root import must preflight with `candidate inspect` before any onboarding mutation
 - target resolution must be treated as preflight and must not mutate active workspace selection implicitly
 
 ### 2.2 Ontology Page State

package/docs/magicball-integration-issue-tracker.md

@@ -29,7 +29,7 @@ SCE changes completed and now available for MagicBall:
 - `app registry status/configure/sync*`
 - `app runtime show/releases/install/activate/uninstall`
 - `app engineering preview/ownership/open/import/show/attach/hydrate/scaffold/activate`
-- `project portfolio show/target resolve/supervision show`
+- `project portfolio show/candidate inspect/onboarding import/target resolve/supervision show`
 - `pm requirement/tracking/planning/change/issue` data plane
 - `ontology er/br/dl` + `ontology triad summary`
 - `ontology seed list/show/apply`
@@ -41,7 +41,7 @@ SCE changes completed and now available for MagicBall:
 2. consume `device current`, `app collection list/show/apply`, `scene workspace list/show/apply`, and `app install-state list` as the local device/install baseline
 3. consume `pm`, `ontology`, and `assurance` table payloads
 4. wire runtime install/activate/uninstall and engineering attach/hydrate/scaffold/activate actions
-5. treat `project portfolio / target resolve / supervision` as the default multi-project shell truth
+5. treat `project portfolio / candidate inspect / onboarding import / target resolve / supervision` as the default multi-project shell truth
 6. use demo app: `customer-order-demo`
 
 ### Related SCE docs

package/docs/magicball-project-portfolio-contract.md

@@ -6,6 +6,8 @@ Define the stable phase-1 SCE contract for MagicBall multi-project surfaces.
 
 This document covers:
 - project roster projection
+- root candidate inspection
+- root-based onboarding import
 - target-project preflight resolution
 - project-scoped supervision snapshot
 
@@ -22,6 +24,7 @@ Use together with:
 
 Phase-1 is read-first and engine-owned:
 - project visibility comes from registered workspaces plus the current unregistered `.sce` project when applicable
+- local root inspection and onboarding reuse engine-owned identity and reason codes
 - project identity is deterministic and stable for registered workspaces
 - target resolution is preflight-only and does not mutate active workspace selection
 - supervision is a project-scoped snapshot, not a raw cross-project event stream
@@ -36,6 +39,8 @@ Phase-1 does not introduce:
 
 ```bash
 sce project portfolio show --json
+sce project candidate inspect --root <path> --json
+sce project onboarding import --root <path> --json
 sce project target resolve --json
 sce project supervision show --project <project-id> --json
 ```
@@ -105,6 +110,55 @@ interface ProjectPortfolioRecord {
 
 ## 2. Target Resolution
 
+## 1.5 Root Candidate Inspection And Onboarding
+
+### Commands
+
+```bash
+sce project candidate inspect --root <path> --json
+sce project onboarding import --root <path> --json
+```
+
+### Contract shape
+
+```ts
+interface LocalProjectCandidateInspection {
+  inspectedAt: string
+  rootDir: string
+  kind: 'workspace-backed' | 'local-sce-candidate' | 'directory-candidate' | 'invalid'
+  projectId?: string
+  workspaceId?: string
+  projectName?: string
+  readiness: 'ready' | 'partial' | 'pending' | 'blocked' | 'unknown'
+  availability: 'accessible' | 'inaccessible' | 'degraded'
+  localCandidate: boolean
+  reasonCodes: string[]
+}
+
+interface ProjectOnboardingImportResult {
+  mode: 'import'
+  generated_at: string
+  success: boolean
+  preview: LocalProjectCandidateInspection
+  steps: Array<{
+    key: 'register' | 'attach' | 'hydrate' | 'activate' | 'scaffold'
+    status: 'done' | 'skipped' | 'pending' | 'failed'
+    reasonCode?: string
+    detail?: string
+  }>
+}
+```
+
+### MagicBall rules
+
+- Adapter-owned filesystem scanning is allowed, but every chosen root must be normalized through `candidate inspect`.
+- Use `project onboarding import` when the user picks a local root directly; do not fake an app-library item just to enter onboarding.
+- If `kind=workspace-backed`, reuse returned `projectId/workspaceId` directly and avoid synthesizing a second registry identity.
+- If `kind=local-sce-candidate`, present it as a partial local project until onboarding import registers it.
+- Render `reasonCodes` directly in CLI/IDE receipts; do not replace them with frontend-only heuristics.
+
+## 2. Target Resolution
+
 ### Command
 
 ```bash
@@ -201,10 +255,12 @@ interface ProjectSupervisionItem {
 ## 4. Recommended Multi-Project Frontend Flow
 
 1. Load `sce project portfolio show --json` when entering the multi-project shell.
-2. Store `activeProjectId` and render a project switcher from `projects[]`.
-3. When the user enters a cross-project free-text request, preflight with `sce project target resolve --json`.
-4. After project selection or successful resolution, load `sce project supervision show --project <project-id> --json`.
-5. Keep per-project tabs and page layout frontend-owned, but keep project truth engine-owned.
+2. When the user selects a local root manually, preflight it with `sce project candidate inspect --root <path> --json`.
+3. If the root is not yet portfolio-backed, import it through `sce project onboarding import --root <path> --json`.
+4. Store `activeProjectId` and render a project switcher from `projects[]`.
+5. When the user enters a cross-project free-text request, preflight with `sce project target resolve --json`.
+6. After project selection or successful resolution, load `sce project supervision show --project <project-id> --json`.
+7. Keep per-project tabs and page layout frontend-owned, but keep project truth engine-owned.
 
 ## 5. Minimal Acceptance Criteria For MagicBall
 

package/docs/magicball-sce-adaptation-guide.md

@@ -142,6 +142,8 @@ Use `docs/magicball-cli-invocation-examples.md` for copy-ready commands.
 
 ### Multi-project control
 - `sce project portfolio show`
+- `sce project candidate inspect`
+- `sce project onboarding import`
 - `sce project target resolve`
 - `sce project supervision show`
 

package/docs/magicball-task-feedback-timeline-guide.md

@@ -117,7 +117,6 @@ SCE 现在在时间线命令中增加：
 ## 4. 最小接口清单
 
 - `sce studio events --job <job-id> --json`
-- `sce studio events --job <job-id> --openhands-events <path> --json`
 - `sce timeline list --limit 20 --json`
 - `sce timeline show <snapshot-id> --json`
 

package/docs/magicball-ui-surface-checklist.md

@@ -136,11 +136,13 @@ MagicBall can treat the current SCE integration as baseline-ready when:
 
 ### Must render
 - project switcher from `project portfolio show`
+- local-root candidate receipt from `project candidate inspect`
 - current project marker
 - project health summary from `project supervision show`
 - explicit degraded / inaccessible project states
 
 ### Must behave correctly
+- manual root import preflights through `project candidate inspect` before `project onboarding import`
 - cross-project free-text routing preflights through `project target resolve`
 - ambiguous resolution does not auto-select silently
 - target resolution does not implicitly switch active workspace selection

package/docs/release-checklist.md

@@ -94,7 +94,7 @@ rg -n "github.com/scene-capability-engine/sce" README.md README.zh.md docs START
 Additional expectation:
 
 - `audit:magicball-engineering-contract` passes so active MagicBall entry docs stay aligned with `scene delivery`, `engineering preview/ownership`, and `open/import/scaffold` contracts.
-- `audit:magicball-project-contract` passes so active MagicBall entry docs stay aligned with `project portfolio`, `project target resolve`, and `project supervision show` contracts.
+- `audit:magicball-project-contract` passes so active MagicBall entry docs stay aligned with `project portfolio`, `project candidate inspect`, `project onboarding import`, `project target resolve`, and `project supervision show` contracts.
 
 ---
 

package/docs/releases/README.md

@@ -9,6 +9,8 @@ This directory stores release-facing documents:
 ## Archived Versions
 
 - [Release checklist](../release-checklist.md)
+- [v3.6.62 release notes](./v3.6.62.md)
+- [v3.6.61 release notes](./v3.6.61.md)
 - [v3.6.60 release notes](./v3.6.60.md)
 - [v3.6.59 release notes](./v3.6.59.md)
 - [v3.6.58 release notes](./v3.6.58.md)

package/docs/releases/v3.6.61.md

@@ -0,0 +1,21 @@
+# v3.6.61 Release Notes
+
+Release date: 2026-03-20
+
+## Highlights
+
+- Added canonical local-root inspection through `sce project candidate inspect --root <path> --json`, so adapters can classify one chosen directory without inventing their own `.sce` heuristics.
+- Added canonical root-based onboarding through `sce project onboarding import --root <path> --json`, reusing the shared onboarding step envelope and registering imported roots into the project portfolio without a second registry.
+- Extended MagicBall-facing contract docs and release-time doc audit to keep `candidate inspect` and `onboarding import` aligned with `project portfolio / target resolve / supervision`.
+
+## Validation
+
+- `npx jest tests/unit/commands/project.test.js --runInBand`
+- `npx jest tests/unit/scripts/magicball-project-contract-audit.test.js --runInBand`
+- `npx jest tests/integration/project-cli.integration.test.js --runInBand`
+- `node scripts/magicball-project-contract-audit.js --fail-on-violation --json`
+
+## Release Notes
+
+- Use `v3.6.61` when you need the upstream `136-00` local-project candidate inspection and root-based onboarding contract in the published SCE package.
+- This release stays within the existing engine/adapter boundary: adapters still own scan policy, while SCE now owns the canonical semantics for inspecting one root and importing it by root.

package/docs/releases/v3.6.62.md

@@ -0,0 +1,32 @@
+# v3.6.62 Release Notes
+
+Release date: 2026-03-21
+
+## Highlights
+
+- Removed the OpenHands-specific `sce studio events --openhands-events <path>` bridge from the tracked CLI surface so SCE no longer publishes a vendor-specific event-ingestion path as a first-class runtime contract.
+- Removed the corresponding OpenHands mapping test coverage and cleaned the main command reference plus README surfaces to keep shipped documentation aligned with the active product boundary.
+- Kept the broader external-runtime direction vendor-neutral so future IDE embedding can focus on Codex CLI, Claude Code, and similar in-process tool endpoints without carrying a stale OpenHands-first entry point.
+
+## Validation
+
+- `npx jest tests/unit/commands/studio.test.js --runInBand`
+- `npm run test:release`
+- `npm run audit:release-docs`
+- `npm run audit:steering`
+- `npm run test:skip-audit`
+- `npm run test:sce-tracking`
+- `npm run gate:npm-runtime-assets`
+- `npm run test:brand-consistency`
+- `npm run audit:clarification-first`
+- `npm run audit:magicball-engineering-contract`
+- `npm run audit:magicball-project-contract`
+- `npm run gate:collab-governance`
+- `npm run gate:errorbook-registry-health`
+- `npm run gate:errorbook-release`
+- `npm pack --dry-run`
+
+## Release Notes
+
+- Use `v3.6.62` when you need the published SCE package to exclude the old OpenHands-specific `studio events` bridge from the active CLI and doc surface.
+- This patch intentionally does not rewrite user-local draft Specs; it only cleans the tracked engine, tests, and release-facing documentation.

package/docs/zh/release-checklist.md

@@ -79,7 +79,7 @@ rg -n "github.com/scene-capability-engine/sce" README.md README.zh.md docs START
 额外预期：
 
 - `audit:magicball-engineering-contract` 通过，确保活跃的 MagicBall 入口文档与 `scene delivery`、`engineering preview/ownership`、`open/import/scaffold` 契约保持一致。
-- `audit:magicball-project-contract` 通过，确保活跃的 MagicBall 入口文档与 `project portfolio`、`project target resolve`、`project supervision show` 契约保持一致。
+- `audit:magicball-project-contract` 通过，确保活跃的 MagicBall 入口文档与 `project portfolio`、`project candidate inspect`、`project onboarding import`、`project target resolve`、`project supervision show` 契约保持一致。
 
 ---
 

package/docs/zh/releases/README.md

@@ -9,6 +9,8 @@
 ## 历史版本归档
 
 - [发布检查清单](../release-checklist.md)
+- [v3.6.62 发布说明](./v3.6.62.md)
+- [v3.6.61 发布说明](./v3.6.61.md)
 - [v3.6.60 发布说明](./v3.6.60.md)
 - [v3.6.59 发布说明](./v3.6.59.md)
 - [v3.6.58 发布说明](./v3.6.58.md)

package/docs/zh/releases/v3.6.61.md

@@ -0,0 +1,21 @@
+# v3.6.61 发布说明
+
+发布日期：2026-03-20
+
+## 重点变化
+
+- 新增 `sce project candidate inspect --root <path> --json`，把“单个本地目录候选项目检查”正式上收到 engine 契约层，适配器不再需要自造 `.sce` 目录启发式。
+- 新增 `sce project onboarding import --root <path> --json`，把“按根目录导入/onboarding”正式收敛到 canonical step envelope，并把导入结果纳入项目 portfolio，而不是另造第二套 registry。
+- 同步扩展了 MagicBall 多项目合同文档与发布时项目合同审计，确保 `candidate inspect / onboarding import` 与既有 `project portfolio / target resolve / supervision` 保持一致。
+
+## 验证
+
+- `npx jest tests/unit/commands/project.test.js --runInBand`
+- `npx jest tests/unit/scripts/magicball-project-contract-audit.test.js --runInBand`
+- `npx jest tests/integration/project-cli.integration.test.js --runInBand`
+- `node scripts/magicball-project-contract-audit.js --fail-on-violation --json`
+
+## 发布说明
+
+- 需要上游 `136-00` 本地项目候选检查与按根目录 onboarding 契约时，请使用 `v3.6.61`。
+- 该版本继续保持 engine / adapter 边界：扫描策略仍归适配器，SCE 负责“检查一个 root”和“按 root 导入”的正式语义。

package/docs/zh/releases/v3.6.62.md

@@ -0,0 +1,32 @@
+# v3.6.62 发布说明
+
+发布日期：2026-03-21
+
+## 重点变化
+
+- 从已跟踪 CLI 正式接口面移除了 OpenHands 专有的 `sce studio events --openhands-events <path>` 桥接入口，避免 SCE 继续把某个供应商专有事件摄取路径作为一等运行时契约发布。
+- 同步移除了对应的 OpenHands 映射测试，并清理了主命令参考与 README 中的相关说明，保证随包发布的文档与当前正式产品边界一致。
+- 外部 runtime 方向继续保持 vendor-neutral，为后续 IDE 内嵌 Codex CLI、Claude Code 等执行端预留稳定空间，而不是继续背着过时的 OpenHands-first 入口。
+
+## 验证
+
+- `npx jest tests/unit/commands/studio.test.js --runInBand`
+- `npm run test:release`
+- `npm run audit:release-docs`
+- `npm run audit:steering`
+- `npm run test:skip-audit`
+- `npm run test:sce-tracking`
+- `npm run gate:npm-runtime-assets`
+- `npm run test:brand-consistency`
+- `npm run audit:clarification-first`
+- `npm run audit:magicball-engineering-contract`
+- `npm run audit:magicball-project-contract`
+- `npm run gate:collab-governance`
+- `npm run gate:errorbook-registry-health`
+- `npm run gate:errorbook-release`
+- `npm pack --dry-run`
+
+## 发布说明
+
+- 当你需要已发布的 SCE 包不再暴露旧的 OpenHands 专有 `studio events` 桥接入口时，请使用 `v3.6.62`。
+- 本次补丁刻意不去重写用户本地未纳管的草稿 spec，只清理已跟踪的 engine、测试与发布文档面。

package/lib/commands/project.js

@@ -1,5 +1,7 @@
 const chalk = require('chalk');
+const { inspectProjectCandidate } = require('../project/candidate-inspection-service');
 const { buildProjectPortfolioProjection } = require('../project/portfolio-projection-service');
+const { runProjectRootOnboardingImport } = require('../project/root-onboarding-service');
 const { buildProjectSupervisionProjection } = require('../project/supervision-projection-service');
 const { resolveProjectTarget } = require('../project/target-resolution-service');
 
@@ -41,6 +43,32 @@ async function runProjectSupervisionShowCommand(options = {}, dependencies = {})
   return payload;
 }
 
+async function runProjectCandidateInspectCommand(options = {}, dependencies = {}) {
+  const payload = await inspectProjectCandidate(options, dependencies);
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue('Project Candidate Inspection'));
+    console.log(`  Root: ${payload.rootDir}`);
+    console.log(`  Kind: ${payload.kind}`);
+    console.log(`  Readiness: ${payload.readiness}`);
+  }
+  return payload;
+}
+
+async function runProjectOnboardingImportCommand(options = {}, dependencies = {}) {
+  const payload = await runProjectRootOnboardingImport(options, dependencies);
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue('Project Onboarding Import'));
+    console.log(`  Root: ${payload.preview ? payload.preview.rootDir : options.root}`);
+    console.log(`  Success: ${payload.success ? 'yes' : 'no'}`);
+    console.log(`  Workspace: ${payload.result && payload.result.workspaceId ? payload.result.workspaceId : 'none'}`);
+  }
+  return payload;
+}
+
 function safeRun(handler, options = {}, context = 'project command') {
   Promise.resolve(handler(options))
     .catch((error) => {
@@ -84,6 +112,28 @@ function registerProjectCommands(program) {
     .option('--json', 'Print machine-readable JSON output')
     .action((options) => safeRun(runProjectTargetResolveCommand, options, 'project target resolve'));
 
+  const candidate = project
+    .command('candidate')
+    .description('Inspect one local directory as a canonical project candidate');
+
+  candidate
+    .command('inspect')
+    .description('Inspect one local root without inventing adapter-side heuristics')
+    .requiredOption('--root <path>', 'Local root directory to inspect')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runProjectCandidateInspectCommand, options, 'project candidate inspect'));
+
+  const onboarding = project
+    .command('onboarding')
+    .description('Import one local directory into the canonical project portfolio');
+
+  onboarding
+    .command('import')
+    .description('Run root-based onboarding without app-bundle-first indirection')
+    .requiredOption('--root <path>', 'Local root directory to import')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runProjectOnboardingImportCommand, options, 'project onboarding import'));
+
   const supervision = project
     .command('supervision')
     .description('Inspect project-scoped supervision projection');
@@ -98,6 +148,8 @@ function registerProjectCommands(program) {
 }
 
 module.exports = {
+  runProjectCandidateInspectCommand,
+  runProjectOnboardingImportCommand,
   runProjectPortfolioShowCommand,
   runProjectTargetResolveCommand,
   runProjectSupervisionShowCommand,