rapidkit 0.37.0 → 0.38.0

package/docs/commands-reference.md

@@ -0,0 +1,136 @@
+# Commands Reference
+
+Complete CLI syntax for the RapidKit npm wrapper. For behavior and workflows, see [workspace-operations.md](./workspace-operations.md) and [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md).
+
+## Workspace lifecycle
+
+```bash
+npx rapidkit create # Prompts: workspace | project
+npx rapidkit create workspace <name> [--profile <profile>] [--author <name>] [--yes]
+npx rapidkit bootstrap [--profile <profile>] [--json] [--compliance-only]
+npx rapidkit setup <python|node|go|java|dotnet> [--warm-deps]
+npx rapidkit pipeline [--json] [--strict] [--skip-verify] [--skip-analyze] [--skip-autopilot] [--autopilot-mode <audit|safe-fix|enforce>]
+npx rapidkit analyze [--workspace <path>] [--json] [--strict] [--output <file>]
+npx rapidkit readiness [--json] [--strict] [--skip-verify]
+npx rapidkit autopilot release [--mode <audit|safe-fix|enforce>] [--json] [--output <file>] [--since <ref>] [--parallel] [--max-workers <n>]
+```
+
+Recommended CI:
+
+```bash
+npx rapidkit pipeline --json --strict
+npx rapidkit autopilot release --mode enforce --json --output .rapidkit/reports/autopilot-release.json
+```
+
+`bootstrap --json --compliance-only` runs compliance checks only (skips init). Default `bootstrap --json` still runs init after compliance checks.
+
+```bash
+npx rapidkit workspace sync [--json]
+npx rapidkit workspace policy show
+npx rapidkit workspace policy set <key> <value>
+npx rapidkit doctor
+npx rapidkit doctor workspace [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
+npx rapidkit doctor project [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
+npx rapidkit workspace list
+npx rapidkit workspace foundation ensure [--force] [--json]
+npx rapidkit workspace share [--output <file>] [--include-paths] [--no-doctor]
+npx rapidkit workspace contract init [--force] [--json]
+npx rapidkit workspace contract inspect [--json]
+npx rapidkit workspace contract verify [--strict] [--json]
+npx rapidkit workspace contract graph [--json]
+npx rapidkit workspace model [--json] [--write] [--strict]
+npx rapidkit workspace context --for-agent [codex|claude|cursor|orca] [--json] [--write] [--no-agent-sync]
+npx rapidkit workspace agent-sync [--write] [--refresh-context] [--strict] [--json] [--target all|copilot,cursor,claude]
+npx rapidkit workspace snapshot [--json]
+npx rapidkit workspace diff --from <snapshot-or-report|git[:ref]> [--json]
+npx rapidkit workspace impact --from <snapshot-or-report> [--scope project:<name>] [--json]
+npx rapidkit workspace verify [--from-impact <file>] [--scope project:<name>] [--strict] [--json]
+npx rapidkit workspace export --output team-workspace.rapidkit-archive.zip
+npx rapidkit workspace archive inspect team-workspace.rapidkit-archive.zip [--json]
+npx rapidkit workspace archive verify team-workspace.rapidkit-archive.zip [--strict] [--json]
+npx rapidkit workspace archive doctor team-workspace.rapidkit-archive.zip [--strict] [--json]
+npx rapidkit workspace hydrate team-workspace.rapidkit-archive.zip --output ./team-workspace
+npx rapidkit import <path|git-url> [--workspace <path>] [--name <project-name>] [--git] [--json]
+npx rapidkit adopt [path] [--workspace <path>] [--name <project-name>] [--dry-run] [--json]
+npx rapidkit snapshot create [name] [--include-projects] [--reason <text>] [--json]
+npx rapidkit snapshot list [--json]
+npx rapidkit snapshot inspect <name> [--json]
+npx rapidkit snapshot restore <name> [--dry-run] [--force] [--json]
+npx rapidkit project archive <name> [--reason <text>] [--dry-run] [--json]
+npx rapidkit project archives [--json]
+npx rapidkit project restore <archive> [--name <project-name>] [--force] [--dry-run] [--json]
+npx rapidkit project delete <name> [--permanent --confirm <name>] [--dry-run] [--json]
+npx rapidkit workspace init
+npx rapidkit workspace run <init|test|build|start> [--affected] [--blast-radius] [--since <ref>] [--parallel] [--max-workers <n>] [--strict] [--json]
+npx rapidkit infra plan [--workspace <path>] [--json] [--dry-run] [--verbose]
+npx rapidkit infra up [--workspace <path>] [--no-plan] [--build]
+npx rapidkit infra down [--workspace <path>] [--volumes]
+npx rapidkit infra status [--workspace <path>] [--json] [--strict]
+```
+
+See [workspace-run.md](./workspace-run.md) for fleet orchestration semantics.
+
+## Project lifecycle
+
+```bash
+npx rapidkit create project <kit> <name> [--yes] [--skip-install]
+npx rapidkit create frontend <id> <name> [--output <dir>] [--yes] [--skip-install] [--skip-git]
+npx rapidkit project commands [--json]
+npx rapidkit commands --scope project [--json]
+npx rapidkit init
+npx rapidkit dev
+npx rapidkit test
+npx rapidkit build
+npx rapidkit start
+```
+
+`project commands` shows the effective command contract for the current project. Core-backed FastAPI/NestJS projects can use module commands such as `add` and `modules`. Frontend apps, Go, Spring Boot, .NET, and adopted/imported repositories use runtime lifecycle commands and workspace governance while Core module mutation remains disabled.
+
+## Operations
+
+```bash
+npx rapidkit cache <status|clear|prune|repair>
+npx rapidkit mirror <status|sync|verify|rotate>
+npx rapidkit infra <plan|up|down|status>
+```
+
+See [workspace-operations.md](./workspace-operations.md#workspace-infrastructure-sidecar) for infra discovery rules.
+
+## Profiles
+
+- `minimal` — baseline workspace scaffolding
+- `java-only` — Java-focused workspace
+- `python-only` — Python-focused workspace
+- `node-only` — Node.js-focused workspace
+- `go-only` — Go-focused workspace
+- `polyglot` — Python + Node.js + Go + Java
+- `enterprise` — polyglot + governance-oriented checks
+
+## Policy modes
+
+`mode` in `.rapidkit/policies.yml`:
+
+- `warn` (default): report violations, continue
+- `strict`: block incompatible operations
+
+```bash
+npx rapidkit workspace policy show
+npx rapidkit workspace policy set mode strict
+npx rapidkit workspace policy set dependency_sharing_mode shared-runtime-caches
+npx rapidkit workspace policy set rules.enforce_toolchain_lock true
+```
+
+Supported keys: `mode`, `dependency_sharing_mode`, `rules.enforce_workspace_marker`, `rules.enforce_toolchain_lock`, `rules.disallow_untrusted_tool_sources`, `rules.enforce_compatibility_matrix`, `rules.require_mirror_lock_for_offline`.
+
+## Setup and warm dependencies
+
+`setup <runtime>` validates toolchain and updates `.rapidkit/toolchain.lock`.
+
+`--warm-deps` adds optional dependency warm-up (Node lock/deps, Go modules). Warm-deps is non-fatal and reports `completed` / `failed` / `skipped`.
+
+## See also
+
+- [Documentation index](./README.md)
+- [workspace-operations.md](./workspace-operations.md)
+- [workspace-run.md](./workspace-run.md)
+- [contracts/COMMAND_OWNERSHIP_MATRIX.md](./contracts/COMMAND_OWNERSHIP_MATRIX.md)

package/docs/config-file-guide.md

@@ -0,0 +1,295 @@
+# 📖 RapidKit Config File Guide
+
+## 🎯 Purpose of `rapidkit.config.js`
+
+The `rapidkit.config.js` file is an **optional configuration file** that allows you to define default settings for creating workspaces and projects.
+
+---
+
+## 📍 File Location
+
+```
+📁 Your Project Directory (where you run npx rapidkit)
+├── rapidkit.config.js       ← Config file (create manually)
+├── package.json
+└── ...
+```
+
+**Important Note**: This file is **not automatically created**. You must create it manually.
+
+---
+
+## 🔍 When to Use
+
+### 1️⃣ **Team Development**
+
+```javascript
+// rapidkit.config.js
+export default {
+  workspace: {
+    defaultAuthor: 'Your Team Name',
+    pythonVersion: '3.10',
+    installMethod: 'poetry'
+  }
+}
+```
+
+**Result**: All team members create workspaces with identical settings.
+
+---
+
+### 2️⃣ **CI/CD Automation**
+
+```javascript
+// rapidkit.config.js for CI/CD
+export default {
+  workspace: {
+    defaultAuthor: 'CI Bot',
+    pythonVersion: '3.11',
+    installMethod: 'venv'
+  },
+  projects: {
+    skipGit: true,        // No git init needed in CI
+    skipInstall: false
+  }
+}
+```
+
+**Usage**:
+```bash
+# In CI/CD pipeline
+npx rapidkit my-workspace --yes
+# Uses config without prompts
+```
+
+---
+
+### 3️⃣ **Personal Projects**
+
+```javascript
+// rapidkit.config.js
+export default {
+  workspace: {
+    defaultAuthor: 'John Doe',
+    pythonVersion: '3.12'
+  },
+  projects: {
+    defaultKit: 'fastapi.standard',     // Always use FastAPI standard template
+    addDefaultModules: [
+      'prisma',
+      'redis', 
+      'auth-jwt',
+      'monitoring'
+    ]
+  }
+}
+```
+
+**Result**: Every new project comes with these modules pre-configured.
+
+---
+
+## 📝 Supported File Formats
+
+| File | Description |
+|------|-------------|
+| `rapidkit.config.js` | ES Module (export default) |
+| `rapidkit.config.mjs` | Explicit ES Module |
+| `rapidkit.config.cjs` | CommonJS (module.exports) |
+
+---
+
+## ⚙️ Available Configuration Options
+
+### **workspace** (Workspace Settings)
+
+```typescript
+workspace: {
+  defaultAuthor?: string;        // Author/team name
+  pythonVersion?: '3.10' | '3.11' | '3.12';  // Python version
+  installMethod?: 'poetry' | 'venv' | 'pipx';  // Core installation method
+}
+```
+
+### **projects** (Project Settings)
+
+```typescript
+projects: {
+  defaultKit?: string;           // Default template
+  addDefaultModules?: string[];  // Default modules to install
+  skipGit?: boolean;             // Skip git initialization
+  skipInstall?: boolean;         // Skip npm install
+}
+```
+
+---
+
+## 🔄 Configuration Priority
+
+```
+CLI Arguments > rapidkit.config.js > .rapidkitrc.json > Defaults
+```
+
+**Example**:
+```bash
+# Config file: author='Team A'
+npx rapidkit my-workspace --author "Team B"
+# Result: author='Team B' (CLI overrides config)
+```
+
+---
+
+## 📋 Complete Example
+
+```javascript
+/**
+ * RapidKit Configuration
+ * Place in project root before running `npx rapidkit`
+ */
+export default {
+  // Workspace settings
+  workspace: {
+    defaultAuthor: 'RapidKit Dev Team',
+    pythonVersion: '3.10',
+    installMethod: 'poetry',
+  },
+  
+  // Project settings
+  projects: {
+    defaultKit: 'fastapi.standard',
+    
+    // Auto-add these modules to new projects
+    addDefaultModules: [
+      'prisma',          // Database ORM
+      'redis',           // Caching
+      'auth-jwt',        // Authentication
+      'monitoring',      // Observability
+    ],
+    
+    skipGit: false,
+    skipInstall: false,
+  },
+};
+```
+
+---
+
+## 🚀 Usage Examples
+
+### Without Config File (Interactive):
+```bash
+npx rapidkit my-workspace
+# ❓ Prompts:
+#   - Author name?
+#   - Python version?
+#   - Install method?
+```
+
+### With Config File (Automated):
+```bash
+# 1. Create config
+cat > rapidkit.config.js << 'EOF'
+export default {
+  workspace: {
+    defaultAuthor: 'My Team',
+    pythonVersion: '3.10',
+    installMethod: 'poetry'
+  }
+}
+EOF
+
+# 2. Run rapidkit
+npx rapidkit my-workspace --yes
+# ✅ No prompts, uses config defaults
+```
+
+---
+
+## 🔍 Debugging Configuration
+
+```bash
+# Enable debug mode to see loaded config
+npx rapidkit my-workspace --debug
+```
+
+Output:
+```
+[DEBUG] User config loaded {}
+[DEBUG] RapidKit config loaded { workspace: { defaultAuthor: 'Team' } }
+[DEBUG] Merged config { author: 'Team', pythonVersion: '3.10' }
+```
+
+---
+
+## 🎯 Common Use Cases
+
+### ✅ Recommended Uses:
+
+1. **Large Teams**: Standardize settings across developers
+2. **CI/CD**: Automate workspace creation
+3. **Personal Templates**: Always start with specific modules
+4. **Training/Workshops**: Ensure all participants have identical settings
+
+### ❌ Not Recommended:
+
+1. **One-time Use**: If you're only creating one workspace
+2. **Variable Settings**: If you need different settings each time
+3. **Quick Development**: For rapid testing, interactive prompts are faster
+
+---
+
+## Additional resources
+
+- [Example config](../rapidkit.config.example.js)
+- [commands-reference.md](./commands-reference.md) — CLI syntax
+- [Documentation](https://getrapidkit.com/docs/config) (external)
+
+---
+
+## 💡 Tips
+
+1. **Config is Optional**: You don't need to create this file
+2. **CLI Overrides**: You can always override config with command-line flags
+3. **Auto-detection**: CLI automatically discovers config files
+4. **Type Safety**: Use TypeScript types for IntelliSense support
+
+---
+
+## 🔗 Related Commands
+
+```bash
+# Create workspace with config
+npx rapidkit my-workspace --yes
+
+# Override config author
+npx rapidkit my-workspace --author "Different Author"
+
+# Check environment
+npx rapidkit doctor
+
+# Inspect/set workspace policy (recommended over manual YAML edits)
+npx rapidkit workspace policy show
+npx rapidkit workspace policy set mode strict
+npx rapidkit workspace policy set dependency_sharing_mode shared-runtime-caches
+npx rapidkit workspace policy set rules.enforce_toolchain_lock true
+
+# List available kits
+npx rapidkit list
+```
+
+---
+
+## 🛡️ Workspace Policy vs `rapidkit.config.*`
+
+- `rapidkit.config.js|mjs|cjs` defines creation defaults and prompt behavior.
+- `.rapidkit/policies.yml` defines runtime governance and enforcement behavior after workspace creation.
+- Preferred policy management path:
+
+```bash
+npx rapidkit workspace policy show
+npx rapidkit workspace policy set <key> <value>
+```
+
+---
+
+**Last updated:** June 2026 · **CLI version:** 0.35.x

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -0,0 +1,111 @@
+# RapidKit CLI Artifact Catalog
+
+Canonical map of **on-disk artifacts** produced by `rapidkit-npm` commands. Dashboards, VS Code extension, and CI should read paths listed here — not infer from legacy fields (e.g. `workspace.json.projects`).
+
+## Authority layers (identity)
+
+| Artifact           | Path                                   | Writer                                                         | Reader purpose                                             |
+| ------------------ | -------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------- |
+| Workspace manifest | `.rapidkit/workspace.json`             | `create workspace`, `foundation ensure`, `bootstrap` (profile) | Profile, engine, bootstrap metadata — **not** project list |
+| Workspace contract | `.rapidkit/workspace.contract.json`    | `workspace sync`, `workspace contract *`, import/adopt         | Operational project registry (ports, contracts)            |
+| Registry summary   | `.rapidkit/workspace-registry.v1.json` | `workspace sync`, contract sync, `registry status --refresh`   | **Canonical** project count + authority for UI/CI          |
+| Workspace marker   | `.rapidkit-workspace`                  | `create workspace`, `foundation ensure`                        | Root detection                                             |
+
+## Naming conventions
+
+| Pattern           | Meaning                                | Examples                                                     |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------ |
+| `*-last-run.json` | Latest gate/run evidence               | `doctor-last-run.json`, `pipeline-last-run.json`             |
+| `*.latest.json`   | Rolling alias + timestamped siblings   | `bootstrap-compliance.latest.json`, `mirror-ops.latest.json` |
+| Static state      | Current model/state (not a single run) | `workspace-model.json`, `workspace.contract.json`            |
+
+## Governance evidence loop
+
+| Command             | Primary artifact                                    | Schema version                                              | JSON Schema                                   |
+| ------------------- | --------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------- | ------------------------------------- |
+| `doctor workspace`  | `.rapidkit/reports/doctor-last-run.json`            | `doctor-workspace-evidence-v1`                              | `contracts/doctor-workspace-evidence.v1.json` |
+| `doctor project`    | `.rapidkit/reports/doctor-project-last-run.json`    | `doctor-project-evidence-v1`                                | `contracts/doctor-project-evidence.v1.json`   |
+| `analyze`           | `.rapidkit/reports/analyze-last-run.json`           | `rapidkit-analyze-v1`                                       | `contracts/analyze-last-run.v1.json`          |
+| `readiness`         | `.rapidkit/reports/release-readiness-last-run.json` | `release-readiness-v1`                                      | `contracts/release-readiness.v1.json`         |
+| `pipeline`          | `.rapidkit/reports/pipeline-last-run.json`          | Also triggers agent grounding sync unless `--no-agent-sync` | `rapidkit-pipeline-v1`                        | `contracts/pipeline-last-run.v1.json` |
+| `autopilot release` | `.rapidkit/reports/autopilot-release-last-run.json` | `autopilot-release-v1`                                      | —                                             |
+|                     | `.rapidkit/reports/autopilot-release.json`          | (alias, same payload)                                       | —                                             |
+
+Side/cache (not gates): `.rapidkit/reports/doctor-workspace-cache.json` (`doctor-workspace-cache-v2`).
+
+## Workspace intelligence
+
+| Command                          | Artifact                                                                             | Schema                            | Contract file                                              |
+| -------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------- | ---------------------------------------------------------- |
+| `workspace model --write`        | `workspace-model.json`                                                               | `workspace-model.v1`              | `contracts/workspace-intelligence/workspace-model.v1.json` |
+| `workspace snapshot`             | `workspace-model-snapshot.json`                                                      | `workspace-model-snapshot.v1`     | `workspace-model-snapshot.v1.json`                         |
+| `workspace diff`                 | `workspace-model-diff-last-run.json`                                                 | `workspace-model-diff.v1`         | `workspace-model-diff.v1.json`                             |
+| `workspace impact --from <diff>` | `workspace-impact-last-run.json`                                                     | `workspace-impact.v1`             | `workspace-impact.v1.json`                                 |
+| `workspace verify`               | `workspace-verify-last-run.json`                                                     | `workspace-verify.v1`             | `workspace-verify.v1.json`                                 |
+| `workspace context --write`      | `workspace-context-agent.json`                                                       | `workspace-context.v1`            | `workspace-context.v1.json`                                |
+| `workspace agent-sync --write`   | `reports/INDEX.json`, `AGENT-GROUNDING.md`, `AGENTS.md`, Copilot/Cursor/Claude hooks | `rapidkit-agent-reports-index.v1` | —                                                          |
+
+**CLI semantics:** `workspace diff --from` expects a **model or snapshot** baseline. `workspace impact --from` expects a **diff report**.
+
+## Operational / platform
+
+| Command                          | Artifact                                                               | Notes                                                                                        |
+| -------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------- |
+| `workspace run`                  | `workspace-run-last.json`                                              | `workspace-run-v1` (multi-stage: `stages.test`, `stages.build`, …)                           | `contracts/workspace-run-last.v1.json` |
+| `autopilot release` (run stages) | same `workspace-run-last.json`                                         | Autopilot publishes test/build into aggregate (no separate `autopilot-workspace-run-*.json`) | —                                      |
+| `bootstrap`                      | `bootstrap-compliance-{ts}.json`, `bootstrap-compliance.latest.json`   |                                                                                              |
+| `mirror status`                  | `mirror-ops-{ts}.json`, `mirror-ops.latest.json`                       |                                                                                              |
+| `mirror` (transparency)          | `transparency-evidence-{ts}.json`, `transparency-evidence.latest.json` |                                                                                              |
+| `infra plan`                     | `infra-plan.json`                                                      | `rapidkit.infra-plan.v1`                                                                     |
+| `workspace archive`              | `archive-manifest.json`                                                | Root `.rapidkit/`, handoff                                                                   |
+| `workspace share`                | `reports/share-bundle.json` (default)                                  | Aggregation bundle                                                                           |
+| `import` / `adopt`               | `{project}/.rapidkit/import-readiness.json`                            | Per project                                                                                  |
+| `workspace contract verify`      | `workspace-contract-verify-last-run.json`                              | CLI verify cache                                                                             |
+
+## Static capability contracts
+
+| Contract                                        | Schema version                            | Consumer purpose                                                                                 |
+| ----------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `contracts/runtime-command-surface.v1.json`     | `rapidkit-runtime-command-surface-v1`     | Runtime commands, scaffold kits, and create planner summary                                      |
+| `contracts/create-planner-capabilities.v1.json` | `rapidkit-create-planner-capabilities-v1` | Native create, external-create-adopt, and adopt-only lanes for CLI, CI, VS Code, and AI planners |
+
+## Registry commands
+
+| Command                                          | Output                                                                           |
+| ------------------------------------------------ | -------------------------------------------------------------------------------- |
+| `workspace sync [--json]`                        | Updates contract + `workspace-registry.v1.json`; JSON includes `registrySummary` |
+| `workspace registry status [--refresh] [--json]` | Reads or publishes registry summary                                              |
+
+## Project-scoped reports
+
+Under `{project}/.rapidkit/reports/` when commands run at project scope (e.g. project doctor). Workspace-level reports stay under `{workspace}/.rapidkit/reports/`.
+
+## Consumer rules
+
+1. **Project count:** read `workspace-registry.v1.json` (or run `workspace registry status --json`).
+2. **Release gates:** follow chain doctor → analyze → readiness → verify → autopilot; use `pipeline-last-run.json` for orchestration summary.
+3. **Do not** use `workspace.json.projects` (removed in schema 1.0).
+4. Prefer `schemaVersion` constants in each artifact; legacy `v1` on readiness is accepted when reading old reports.
+5. **Agent grounding:** read `.rapidkit/reports/INDEX.json` first, then `workspace-context-agent.json`; regenerate with `workspace agent-sync --write`.
+
+## Agent grounding files (repo hooks)
+
+Written by `workspace agent-sync --write` (and by default after `workspace context --for-agent --write`):
+
+| Path                                                     | Consumer                                                  |
+| -------------------------------------------------------- | --------------------------------------------------------- |
+| `AGENTS.md`                                              | Copilot, Cursor, Claude Code, Codex, Grok (open standard) |
+| `.github/copilot-instructions.md`                        | GitHub Copilot / VS Code Chat                             |
+| `.github/instructions/rapidkit-evidence.instructions.md` | Copilot scoped `.rapidkit/**` rules                       |
+| `.github/prompts/rapidkit-diagnose.prompt.md`            | Copilot prompt library                                    |
+| `.github/skills/rapidkit-grounding/SKILL.md`             | Copilot skills                                            |
+| `.cursor/rules/rapidkit-grounding.mdc`                   | Cursor always-on rule                                     |
+| `CLAUDE.md`                                              | Claude Code (imports `@AGENTS.md`)                        |
+| `.claude/rules/rapidkit-evidence.md`                     | Claude Code scoped evidence rule                          |
+| `.rapidkit/AGENT-GROUNDING.md`                           | Tool-agnostic operator doc                                |
+
+## See also
+
+- [README.md](./README.md)
+- [COMMAND_OWNERSHIP_MATRIX.md](./COMMAND_OWNERSHIP_MATRIX.md)
+- [commands-reference.md](../commands-reference.md)

package/docs/contracts/COMMAND_OWNERSHIP_MATRIX.md

@@ -0,0 +1,138 @@
+# Command Ownership Matrix
+
+This document defines which layer owns command execution in RapidKit npm CLI (`rapidkit-npm`) versus RapidKit Core (`rapidkit-core`) to prevent runtime conflicts.
+
+## Goals
+
+- Keep project bootstrapping reliable across Python / Node / Go projects.
+- Avoid conflicting behavior between wrapper and core CLIs.
+- Make delegation behavior explicit and testable.
+
+## Ownership Rules
+
+### 1) Wrapper-owned commands (never forward to core)
+
+These commands are implemented and orchestrated by `rapidkit-npm`:
+
+- `readiness`
+- `autopilot`
+- `pipeline`
+- `doctor`
+- `import`
+- `adopt`
+- `snapshot`
+- `workspace`
+- `bootstrap`
+- `setup`
+- `cache`
+- `mirror`
+- `ai`
+- `analyze`
+- `config`
+- `product`
+- `infra`
+- `commands`
+- `shell activate`
+
+Reason: workspace-level policy, registry, and platform orchestration live in npm wrapper.
+
+### 1.1) Wrapper-owned scoped commands
+
+These scoped commands are implemented and orchestrated by `rapidkit-npm`:
+
+- `project commands`
+- `project archives`
+- `project archive`
+- `project restore`
+- `project delete`
+
+Reason: these are workspace project lifecycle and capability operations with
+archive manifests, safety snapshots, workspace registry side effects, and
+runtime-aware command discovery.
+
+`project detect` remains Core-owned because it is the stable machine-readable
+contract used by wrappers to detect Python RapidKit projects.
+
+`commands --scope project` is also wrapper-owned. It reports the effective
+project command capability matrix for the currently selected project without
+delegating to Core.
+
+### 2) Wrapper-orchestrated project commands
+
+These commands are handled by npm wrapper first (runtime-aware + fallback-aware)
+when the project capability matrix marks them as runtime-supported:
+
+- `init`
+- `dev`
+- `start`
+- `build`
+- `test`
+- `lint`
+- `format`
+- `help`
+
+Reason: generated projects can be Python, Node/NestJS, Go/Fiber, Go/Gin, or
+Spring Boot. Runtime commands must run through the selected project's adapter,
+not through a hard-coded global assumption.
+
+### 3) Core module/template commands
+
+These commands are supported only when the selected project is Core-backed
+and has module/template support:
+
+- `add`
+- `modules`
+- `upgrade`
+- `diff`
+- `merge`
+- `reconcile`
+- `rollback`
+- `uninstall`
+- `checkpoint`
+- `snapshot`
+- `optimize`
+
+Dispatch policy:
+
+- FastAPI / NestJS Core-backed project → supported and delegated to Core.
+- Go / Spring Boot / ASP.NET Core npm-owned project → blocked with a capability explanation.
+- Unknown project → blocked until project metadata is present.
+
+### 4) Global engine/catalog commands
+
+These commands are not project-specific even when run inside a project:
+
+- `create`
+- `list`
+- `info`
+- `frameworks`
+- `license`
+
+`create` remains npm-owned so the wrapper can orchestrate multi-language
+workspace/project generation. The other commands may delegate to Core as engine
+catalog operations.
+
+## Dynamic Project Capability Model
+
+A pure-core or pure-wrapper model causes regressions in mixed-language workspaces. Hybrid ownership keeps Python compatibility while letting npm wrapper enforce workspace policy and resilient cross-platform fallback behavior.
+
+The npm wrapper resolves project capabilities from `.rapidkit/project.json`,
+`.rapidkit/context.json`, and framework/runtime markers. Users and tools can
+inspect the effective command surface with:
+
+- `rapidkit project commands`
+- `rapidkit project commands --json`
+- `rapidkit commands --scope project --json`
+
+This capability model is the canonical bridge between npm-owned kits and
+Core-backed kits. Adding a future language or framework should update the
+project metadata and runtime detector first, then the capability matrix follows
+without widening the Core/global command surface.
+
+## Guard Rails
+
+- `shouldForwardToCore()` must return `false` for wrapper-owned and wrapper-orchestrated project commands.
+- `project commands` and `commands --scope project` must never forward to Core.
+- Core module/template commands must be blocked for npm-owned projects that set `module_support: false`.
+- Tests must assert forwarding boundary rules.
+- Changes to ownership should update this file and tests together.