rapidkit 0.37.0 → 0.38.0

package/README.md

@@ -2,139 +2,154 @@
 
 ### Open-Source Workspace Intelligence for Software Systems
 
-> AI agents understand files.
-> RapidKit helps developers, CI, and AI agents share the same understanding of the workspace.
+[![npm version](https://img.shields.io/npm/v/rapidkit.svg?style=flat-square)](https://www.npmjs.com/package/rapidkit)
+[![Downloads](https://img.shields.io/npm/dm/rapidkit.svg?style=flat-square)](https://www.npmjs.com/package/rapidkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Built by RapidKit](https://img.shields.io/badge/Built%20by-RapidKit-0f172a?logo=github)](https://www.getrapidkit.com)
 
-RapidKit is an open-source workspace platform that turns scattered projects into a governed, agent-ready workspace.
+> One workspace. One truth. Humans and AI aligned.
 
-Build, adopt, and operate polyglot software systems with a shared understanding for developers, CI pipelines, and AI agents.
+RapidKit turns scattered projects into a governed, agent-ready workspace.
 
-Instead of every tool rebuilding its own understanding of your system, RapidKit provides a shared source of truth.
+It gives developers, CI, IDEs, and AI agents the same evidence-backed source of
+truth: workspace model, agent context, impact analysis, verification evidence,
+contracts, and release gates.
 
-## Quick start in 5 minutes
+## Start here
 
-### Install the CLI
+### Install
 
 ```bash
 npm install -g rapidkit
 ```
 
-### Create a new workspace and project
+or run without installing:
+
+```bash
+npx rapidkit --help
+```
+
+### Create a governed workspace
 
 ```bash
-npx rapidkit create workspace platform --yes --profile polyglot
+mkdir -p ~/rapidkit/workspaces
+cd ~/rapidkit/workspaces
 
+npx rapidkit create workspace platform --yes --profile polyglot --output .
 cd platform
 
 npx rapidkit bootstrap --profile polyglot
-
 npx rapidkit create project
 npx rapidkit create frontend nextjs my-web --yes
 
-npx rapidkit workspace model
-npx rapidkit workspace context --for-agent --write
-npx rapidkit pipeline --strict
+npx rapidkit workspace model --json
+npx rapidkit workspace context --for-agent --json --write
+npx rapidkit pipeline --json --strict
 ```
 
 ### Adopt an existing project
 
 ```bash
-npx rapidkit adopt /path/to/project --workspace /path/to/workspace
+mkdir -p ~/rapidkit/workspaces
+cd ~/rapidkit/workspaces
+
+npx rapidkit create workspace platform --yes --profile polyglot --output .
+npx rapidkit adopt /path/to/project --workspace ~/rapidkit/workspaces/platform
 
-npx rapidkit workspace model
-npx rapidkit workspace context --for-agent --write
-npx rapidkit pipeline --strict
+cd ~/rapidkit/workspaces/platform
+npx rapidkit workspace model --json
+npx rapidkit workspace context --for-agent --json --write
+npx rapidkit pipeline --json --strict
 ```
 
-### What RapidKit gives you
+### What you get
 
-* Adopt existing projects without migration
-* Create and manage polyglot workspaces
-* Generate agent-ready context and workspace models
-* Analyze impact before changes ship
-* Verify release readiness with evidence-backed gates
-* Keep developers, CI, and AI agents aligned
+- A governed workspace boundary for projects, policies, reports, and contracts
+- Native create for RapidKit-owned backend and frontend kits
+- Adopt/import for existing repositories without moving source code
+- Agent-ready context packs for Copilot, Cursor, Claude, Codex, and other tools
+- Impact analysis and release gates backed by workspace evidence
+- One shared truth for developers, CI, IDEs, and AI agents
 
-### Workspace Intelligence
+## Create planner
 
-Most AI tools understand:
+RapidKit does not pretend every technology is a native scaffold. It uses a
+create planner contract to choose the safest path:
 
-* Files
-* Functions
-* Repositories
+| Lane                    | Use when                                                                                        | Result                                                                 |
+| ----------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `native-create`         | RapidKit owns the scaffold contract                                                             | Create the project with a first-class kit                              |
+| `external-create-adopt` | The ecosystem has an official generator, but RapidKit does not own the post-create contract yet | Use the ecosystem generator, then adopt into Workspace Intelligence    |
+| `adopt-only`            | The project already exists or native create is not supported                                    | Register, model, verify, and govern the project without scaffolding it |
 
-Production systems require understanding:
+Native create includes FastAPI, NestJS, Go, Spring Boot, .NET, and official
+frontend generators such as Next.js, Vite, Nuxt, Angular, Astro, Remix, and
+SvelteKit.
 
-* Ownership
-* Architecture
-* Dependencies
-* Operational context
-* Verification requirements
-* Change impact
+External ecosystems such as WordPress, Laravel, Symfony, Rails, and generic PHP
+projects can still enter RapidKit through adopt/import and receive workspace
+model, context, impact, doctor, and release governance.
 
-RapidKit adds the missing layer:
+Details: [docs/create-planner-capabilities.md](docs/create-planner-capabilities.md).
 
-**Workspace Intelligence.**
+## Workspace Intelligence
 
-**One workspace. One truth.**
+Most AI tools understand:
 
-A shared understanding of software systems for developers, CI pipelines, IDEs, and AI agents.
+- Files
+- Functions
+- Repositories
 
-### From Code to Shared Understanding
-How RapidKit transforms projects and repositories into workspace intelligence for developers, CI, and AI agents.
+Production systems require understanding:
 
-```mermaid
-flowchart TB
+- Ownership
+- Architecture
+- Dependencies
+- Operational context
+- Verification requirements
+- Change impact
 
-    Code["Code & Repositories"]
-    Projects["Projects"]
-    Workspace["Workspace"]
+RapidKit adds the missing layer:
 
-    Code --> Projects
-    Projects --> Workspace
+**Workspace Intelligence.**
 
-    subgraph Intelligence["Workspace Intelligence"]
-        Model["Workspace Model"]
-        Context["Agent Context"]
-        Impact["Impact Analysis"]
-        Verify["Verification"]
-    end
+**One workspace. One truth. Humans and AI aligned.**
 
-    Workspace --> Model
-    Workspace --> Context
-    Workspace --> Impact
-    Workspace --> Verify
+A shared, evidence-backed understanding of software systems for developers, CI pipelines, IDEs, and AI agents.
 
-    Model --> Dev["Developers"]
-    Model --> CI["CI"]
-    Model --> Agents["AI Agents"]
+In RapidKit, Workspace Intelligence is not a chat feature. It is the deterministic workspace layer behind the CLI:
 
-    Context --> Agents
+- **Model** — what projects, runtimes, frameworks, commands, policies, contracts, and evidence exist
+- **Context** — what AI agents and IDEs should know before giving advice
+- **Impact** — what changed and which projects, commands, and release gates are affected
+- **Verify** — which evidence proves the workspace is ready, blocked, or needs attention
+- **Sync** — how developers, CI, Workspai, and AI agents stay grounded in the same truth
 
-    Impact --> Dev
-    Impact --> CI
+## From Code to Shared Understanding
 
-    Verify --> CI
-    Verify --> Agents
-```
+How RapidKit transforms projects and repositories into workspace intelligence for developers, CI, and AI agents.
 
-RapidKit provides the workspace engine, governance model, evidence chain, and operational intelligence.
+![From Code to Shared Understanding](https://raw.githubusercontent.com/rapidkitlabs/rapidkit-npm/main/docs/From%20Code%20to%20Shared%20Understanding.png)
 
-Workspai provides the VS Code experience on top of that foundation.
+Mermaid source for GitHub docs: [from-code-to-shared-understanding.md](docs/from-code-to-shared-understanding.md).
 
-For the visual experience, install the [Workspai VS Code extension](https://marketplace.visualstudio.com/items?itemName=rapidkit.rapidkit-vscode). 
+RapidKit provides the workspace intelligence engine: model, context, impact, verification, evidence, contracts, and governance.
 
-[![npm version](https://img.shields.io/npm/v/rapidkit.svg?style=flat-square)](https://www.npmjs.com/package/rapidkit)
-[![Downloads](https://img.shields.io/npm/dm/rapidkit.svg?style=flat-square)](https://www.npmjs.com/package/rapidkit)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Built by RapidKit](https://img.shields.io/badge/Built%20by-RapidKit-0f172a?logo=github)](https://www.getrapidkit.com)
+Workspai provides the VS Code experience on top of that foundation.
+
+For the visual experience, install the [Workspai VS Code extension](https://marketplace.visualstudio.com/items?itemName=rapidkit.rapidkit-vscode).
 
 ## Table of contents
 
+- [Start here](#start-here)
+- [Create planner](#create-planner)
+- [Workspace Intelligence](#workspace-intelligence)
+- [From Code to Shared Understanding](#from-code-to-shared-understanding)
 - [Typical workflows](#typical-workflows)
 - [Mental model](#mental-model)
 - [Workspace Intelligence Commands](#workspace-intelligence-commands)
-- [Requirements & install](#requirements)
+- [Requirements](#requirements)
+- [Install](#install)
 - [Project workflows](#project-workflows)
 - [CI & evidence](#ci--evidence)
 - [Workspai ecosystem](#workspai-ecosystem)
@@ -156,7 +171,6 @@ For the visual experience, install the [Workspai VS Code extension](https://mark
 | How do I onboard an existing project?         | `adopt`                                        |
 | How do I bring repositories into a workspace? | `import`                                       |
 
-
 ### Existing project
 
 ```bash
@@ -177,7 +191,6 @@ npx rapidkit workspace agent-sync --write --refresh-context
 npx rapidkit pipeline --json --strict
 ```
 
-
 ### Adopt in place
 
 ```bash
@@ -190,13 +203,12 @@ npx rapidkit adopt --json   # from inside the project folder
 ```text
 ~/.rapidkit/workspaces.json
 ~/rapidkit/workspaces/
-  workspai/          # managed default (import/adopt fallback)
+  workspai/          # managed default (standalone, import, and adopt fallback)
   my-workspace/      # user-created workspaces
 ```
 
 New workspaces go under `~/rapidkit/workspaces/<name>`. Legacy `~/Workspai/rapidkits/*` paths remain registered. Use `--output <parent-dir>` for a custom parent.
 
-
 ## Mental model
 
 ### Two-layer model
@@ -222,17 +234,18 @@ external-project/
 Every tool gets the same answers: what projects exist, what stack they use, which commands are safe, what evidence exists, and what context agents should receive.
 
 ## Workspace Intelligence Commands
+
 Workspace Intelligence provides a shared understanding of projects, dependencies, operational context, and release readiness for developers, CI pipelines, and AI agents.
 
-| Command | Purpose |
-| --- | --- |
-| `workspace model --json` | Canonical workspace model |
-| `workspace context --for-agent --json --write` | Agent-ready context pack + auto agent grounding sync |
-| `workspace agent-sync --write` | Cross-tool grounding (AGENTS.md, Copilot, Cursor, Claude, INDEX) |
-| `workspace snapshot --json` | Persist model snapshot |
-| `workspace diff --from <file\|git[:ref]> --json` | Diff against snapshot or git |
-| `workspace impact --from <file> --json` | Blast-radius evidence |
-| `workspace verify [--strict] --json` | Impact verification gate |
+| Command                                          | Purpose                                                          |
+| ------------------------------------------------ | ---------------------------------------------------------------- |
+| `workspace model --json`                         | Canonical workspace model                                        |
+| `workspace context --for-agent --json --write`   | Agent-ready context pack + auto agent grounding sync             |
+| `workspace agent-sync --write`                   | Cross-tool grounding (AGENTS.md, Copilot, Cursor, Claude, INDEX) |
+| `workspace snapshot --json`                      | Persist model snapshot                                           |
+| `workspace diff --from <file\|git[:ref]> --json` | Diff against snapshot or git                                     |
+| `workspace impact --from <file> --json`          | Blast-radius evidence                                            |
+| `workspace verify [--strict] --json`             | Impact verification gate                                         |
 
 JSON schemas: `contracts/workspace-intelligence/`. Details: [commands-reference.md](docs/commands-reference.md).
 
@@ -251,19 +264,19 @@ npx rapidkit workspace context --for-agent --json --write
 npx rapidkit workspace agent-sync --write --strict --json
 ```
 
-| Artifact / file | Purpose |
-| --- | --- |
-| `.rapidkit/reports/INDEX.json` | Read order, blockers, report timestamps |
-| `.rapidkit/reports/workspace-context-agent.json` | Canonical agent context pack |
-| `.rapidkit/AGENT-GROUNDING.md` | Tool-agnostic grounding doc |
-| `AGENTS.md` | Open standard for all agents (managed RapidKit section) |
-| `.github/copilot-instructions.md` | GitHub Copilot / VS Code Chat always-on rules |
-| `.github/instructions/rapidkit-evidence.instructions.md` | Copilot scoped rules for `.rapidkit/**` |
-| `.github/prompts/rapidkit-diagnose.prompt.md` | Copilot reusable diagnose prompt |
-| `.github/skills/rapidkit-grounding/SKILL.md` | Copilot agent skill workflow |
-| `.cursor/rules/rapidkit-grounding.mdc` | Cursor always-on project rule |
-| `CLAUDE.md` | Claude Code entry (`@AGENTS.md` + managed notes) |
-| `.claude/rules/rapidkit-evidence.md` | Claude Code scoped evidence rules |
+| Artifact / file                                          | Purpose                                                 |
+| -------------------------------------------------------- | ------------------------------------------------------- |
+| `.rapidkit/reports/INDEX.json`                           | Read order, blockers, report timestamps                 |
+| `.rapidkit/reports/workspace-context-agent.json`         | Canonical agent context pack                            |
+| `.rapidkit/AGENT-GROUNDING.md`                           | Tool-agnostic grounding doc                             |
+| `AGENTS.md`                                              | Open standard for all agents (managed RapidKit section) |
+| `.github/copilot-instructions.md`                        | GitHub Copilot / VS Code Chat always-on rules           |
+| `.github/instructions/rapidkit-evidence.instructions.md` | Copilot scoped rules for `.rapidkit/**`                 |
+| `.github/prompts/rapidkit-diagnose.prompt.md`            | Copilot reusable diagnose prompt                        |
+| `.github/skills/rapidkit-grounding/SKILL.md`             | Copilot agent skill workflow                            |
+| `.cursor/rules/rapidkit-grounding.mdc`                   | Cursor always-on project rule                           |
+| `CLAUDE.md`                                              | Claude Code entry (`@AGENTS.md` + managed notes)        |
+| `.claude/rules/rapidkit-evidence.md`                     | Claude Code scoped evidence rules                       |
 
 Agents cannot be **forced** probabilistically — but this stack maximizes the chance they read reports first, even when the user talks to Copilot directly without Workspai.
 
@@ -301,8 +314,13 @@ npx rapidkit doctor workspace --json
 ### I want a new project
 
 ```bash
-npx rapidkit create workspace platform --yes --profile polyglot
-cd platform && npx rapidkit bootstrap --profile polyglot
+mkdir -p ~/rapidkit/workspaces
+cd ~/rapidkit/workspaces
+
+npx rapidkit create workspace platform --yes --profile polyglot --output .
+cd platform
+
+npx rapidkit bootstrap --profile polyglot
 npx rapidkit create project          # interactive kit picker
 npx rapidkit create frontend nextjs my-web --yes
 cd <project-name> && npx rapidkit init && npx rapidkit dev
@@ -324,11 +342,11 @@ Stages individually: `workspace sync`, `doctor workspace --ci`, `analyze --stric
 
 ## CI & evidence
 
-| Stage | Report |
-| --- | --- |
-| Pipeline | `.rapidkit/reports/pipeline-last-run.json` |
-| Doctor | `.rapidkit/reports/doctor-last-run.json` |
-| Analyze | `.rapidkit/reports/analyze-last-run.json` |
+| Stage     | Report                                              |
+| --------- | --------------------------------------------------- |
+| Pipeline  | `.rapidkit/reports/pipeline-last-run.json`          |
+| Doctor    | `.rapidkit/reports/doctor-last-run.json`            |
+| Analyze   | `.rapidkit/reports/analyze-last-run.json`           |
 | Readiness | `.rapidkit/reports/release-readiness-last-run.json` |
 | Autopilot | `.rapidkit/reports/autopilot-release-last-run.json` |
 
@@ -349,47 +367,48 @@ Full syntax: [docs/commands-reference.md](docs/commands-reference.md). CI workfl
 
 RapidKit and Workspai form a single workspace intelligence platform.
 
-RapidKit provides the workspace engine, governance model, evidence chain, and operational intelligence.
+RapidKit provides the workspace intelligence engine: model, context, impact, verification, evidence, contracts, and governance.
 
-Workspai provides the VS Code experience, dashboards, AI workflows, and developer-facing workspace operations.
+Workspai — Workspace + Intelligence — provides the VS Code surface: dashboard, sidebar, Incident Studio, AI workflows, and developer-facing workspace operations.
 
-| Component | Repository | Role |
-| --- | --- | --- |
-| CLI | [rapidkit-npm](https://github.com/rapidkitlabs/rapidkit-npm) | Commands, governance, adoption, CI evidence |
-| VS Code | [rapidkit-vscode](https://github.com/rapidkitlabs/rapidkit-vscode) | Workspai dashboard, sidebar, AI studio |
-| Core | [rapidkit-core](https://github.com/rapidkitlabs/rapidkit-core) | Python engine, modules, doctor |
-| Examples | [rapidkit-examples](https://github.com/rapidkitlabs/rapidkit-examples) | Starter workspaces |
+| Component | Repository                                                             | Role                                        |
+| --------- | ---------------------------------------------------------------------- | ------------------------------------------- |
+| CLI       | [rapidkit-npm](https://github.com/rapidkitlabs/rapidkit-npm)           | Commands, governance, adoption, CI evidence |
+| VS Code   | [rapidkit-vscode](https://github.com/rapidkitlabs/rapidkit-vscode)     | Workspai dashboard, sidebar, AI studio      |
+| Core      | [rapidkit-core](https://github.com/rapidkitlabs/rapidkit-core)         | Python engine, modules, doctor              |
+| Examples  | [rapidkit-examples](https://github.com/rapidkitlabs/rapidkit-examples) | Starter workspaces                          |
 
 ## VS Code extension
+
 Workspai is the VS Code experience for RapidKit workspace intelligence.
 
 Search **Workspai** in the marketplace or install via:
 `ext install rapidkit.rapidkit-vscode`.
 
-| Feature | CLI | Extension |
-| --- | --- | --- |
-| Create / adopt / import | Yes | Guided wizards |
-| Workspace model / context | Yes | Dashboard + AI scope |
-| Cross-tool agent grounding | Yes (`workspace agent-sync`) | Send-to-Copilot / Ask Studio UX |
-| Enterprise evidence loop | Partial | Full dashboard |
-| Module catalog (FastAPI/NestJS) | Limited | Browser UI |
+| Feature                         | CLI                          | Extension                       |
+| ------------------------------- | ---------------------------- | ------------------------------- |
+| Create / adopt / import         | Yes                          | Guided wizards                  |
+| Workspace model / context       | Yes                          | Dashboard + AI scope            |
+| Cross-tool agent grounding      | Yes (`workspace agent-sync`) | Send-to-Copilot / Ask Studio UX |
+| Enterprise evidence loop        | Partial                      | Full dashboard                  |
+| Module catalog (FastAPI/NestJS) | Limited                      | Browser UI                      |
 
 The extension invokes this npm CLI. For the latest `adopt` and `create frontend` features, install matching CLI version: `npm install -g rapidkit@latest` or `npm link` from this repo ([Development](#development)).
 
 ## Documentation
 
-| Doc | Description |
-| --- | --- |
-| [docs/README.md](docs/README.md) | Documentation index |
-| [docs/commands-reference.md](docs/commands-reference.md) | Full command syntax |
-| [docs/workspace-operations.md](docs/workspace-operations.md) | Import, adopt, snapshots, archives, infra |
-| [docs/workspace-run.md](docs/workspace-run.md) | Polyglot fleet orchestration |
-| [docs/doctor-command.md](docs/doctor-command.md) | Doctor scopes, CI exit codes, JSON evidence |
-| [docs/OPEN_SOURCE_USER_SCENARIOS.md](docs/OPEN_SOURCE_USER_SCENARIOS.md) | Role-based workflows |
-| [docs/SETUP.md](docs/SETUP.md) | Maintainer setup |
-| [docs/SECURITY.md](docs/SECURITY.md) | Security policy |
-| [docs/config-file-guide.md](docs/config-file-guide.md) | User configuration |
-| [CHANGELOG.md](CHANGELOG.md) | Version history |
+| Doc                                                                      | Description                                 |
+| ------------------------------------------------------------------------ | ------------------------------------------- |
+| [docs/README.md](docs/README.md)                                         | Documentation index                         |
+| [docs/commands-reference.md](docs/commands-reference.md)                 | Full command syntax                         |
+| [docs/workspace-operations.md](docs/workspace-operations.md)             | Import, adopt, snapshots, archives, infra   |
+| [docs/workspace-run.md](docs/workspace-run.md)                           | Polyglot fleet orchestration                |
+| [docs/doctor-command.md](docs/doctor-command.md)                         | Doctor scopes, CI exit codes, JSON evidence |
+| [docs/OPEN_SOURCE_USER_SCENARIOS.md](docs/OPEN_SOURCE_USER_SCENARIOS.md) | Role-based workflows                        |
+| [docs/SETUP.md](docs/SETUP.md)                                           | Maintainer setup                            |
+| [docs/SECURITY.md](docs/SECURITY.md)                                     | Security policy                             |
+| [docs/config-file-guide.md](docs/config-file-guide.md)                   | User configuration                          |
+| [CHANGELOG.md](CHANGELOG.md)                                             | Version history                             |
 
 ## Development
 
@@ -404,17 +423,17 @@ Contributors: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md), [docs/ci-workflows.md]
 
 ## Troubleshooting
 
-| Problem | Quick check | Fix |
-| --- | --- | --- |
-| `python3` not found | `python3 --version` | Install Python 3.10+ |
-| `setup --warm-deps` skipped | Project markers in cwd | Run from target project directory |
-| Strict policy blocks command | `.rapidkit/policies.yml` | `workspace policy set …` |
-| `npm audit fix --force` downgrades tsup | `package.json` | Do not use `--force`; keep `tsup@^8.5.1` |
-| Security audit fails on esbuild | `npm audit --audit-level=moderate` | Keep `esbuild` override in `package.json` |
-| Doctor output stale | Report timestamps | Re-run `doctor workspace` or `doctor project` |
-| Copilot ignores workspace evidence | Missing grounding files | `workspace agent-sync --write --refresh-context` |
-| Agent grounding strict CI failed | Stale/missing reports | Run governance chain then re-sync |
-| Affected run scope wrong | Git ref | Use `--since <ref>` explicitly |
+| Problem                                 | Quick check                        | Fix                                              |
+| --------------------------------------- | ---------------------------------- | ------------------------------------------------ |
+| `python3` not found                     | `python3 --version`                | Install Python 3.10+                             |
+| `setup --warm-deps` skipped             | Project markers in cwd             | Run from target project directory                |
+| Strict policy blocks command            | `.rapidkit/policies.yml`           | `workspace policy set …`                         |
+| `npm audit fix --force` downgrades tsup | `package.json`                     | Do not use `--force`; keep `tsup@^8.5.1`         |
+| Security audit fails on esbuild         | `npm audit --audit-level=moderate` | Keep `esbuild` override in `package.json`        |
+| Doctor output stale                     | Report timestamps                  | Re-run `doctor workspace` or `doctor project`    |
+| Copilot ignores workspace evidence      | Missing grounding files            | `workspace agent-sync --write --refresh-context` |
+| Agent grounding strict CI failed        | Stale/missing reports              | Run governance chain then re-sync                |
+| Affected run scope wrong                | Git ref                            | Use `--since <ref>` explicitly                   |
 
 ## License