rapidkit 0.42.1 → 0.42.3

package/README.md

@@ -1,660 +1,202 @@
-# RapidKit
-
-## Open-Source Workspace Intelligence for Software Systems
+# RapidKit npm compatibility CLI
 
 [![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)
-
-> **Migration notice: RapidKit npm is moving to Workspai**
->
-> The `rapidkit` npm package is now in compatibility mode and is planned for
-> deprecation in a future release. New installs and new workspaces should use
-> the Workspai CLI instead of the legacy `rapidkit` package:
->
-> ```bash
-> npm install -g workspai
-> npx workspai --help
-> ```
->
-> New npm package: [workspai](https://www.npmjs.com/package/workspai)  
-> New repository: [rapidkitlabs/workspai](https://github.com/rapidkitlabs/workspai)
->
-> The `rapidkit` package remains available during the migration window so
-> existing users and scripts can move safely.
-
-Not another AI coding assistant.
-Not another agent framework.
-Not another context engine.
-
-> One workspace. One truth. Humans and AI aligned.
-
-RapidKit turns scattered projects into a governed, agent-ready workspace.
-
-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.
-
-## Start here
-
-### Install
-
-Recommended for new projects:
-
-```bash
-npm install -g workspai
-```
-
-Legacy compatibility package:
-
-```bash
-npm install -g rapidkit
-```
-
-### CLI help
-
-Browse all commands without a global install (first run fetches from npm):
-
-```bash
-npx workspai --help
-npx rapidkit --help
-```
-
-### Create a governed workspace
-
-```bash
-npx rapidkit my-workspace --yes --profile polyglot
-cd ~/rapidkit/workspaces/my-workspace
-
-npx rapidkit bootstrap --profile polyglot
-npx rapidkit create project nextjs my-web --yes
-npx rapidkit create project fastapi.standard my-api --yes
-
-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
-cd ~/rapidkit/workspaces/workspai
-
-npx rapidkit workspace model --json
-npx rapidkit workspace context --for-agent --json --write
-npx rapidkit pipeline --json --strict
-```
-
-### What you get
-
-- 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
-
-## Create planner
-
-RapidKit does not pretend every technology is a native scaffold. It uses a
-create planner contract to choose the safest path:
-
-| 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 |
-
-Native create includes FastAPI, NestJS, Go, Spring Boot, .NET, and official
-frontend generators such as Next.js, Vite, Nuxt, Angular, Astro, Remix, and
-SvelteKit.
-
-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.
-
-Details: [docs/create-planner-capabilities.md](docs/create-planner-capabilities.md).
-
-## Workspace Intelligence
-
-Most AI tools understand:
-
-- Files
-- Functions
-- Repositories
-
-Production systems require understanding:
-
-- Ownership
-- Architecture
-- Dependencies
-- Operational context
-- Verification requirements
-- Change impact
-
-RapidKit adds the missing layer:
-
-**Workspace Intelligence.**
-
-**One workspace. One truth. Humans and AI aligned.**
-
-A shared, evidence-backed understanding of software systems for developers, CI pipelines, IDEs, and AI agents.
-
-In RapidKit, Workspace Intelligence is not a chat feature. It is the deterministic workspace layer behind the CLI:
-
-- **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
-- **Freshness** — which facts are durable, derived, evidence-backed, live, or must be verified before use
-
-## From Code to Shared Understanding
-
-How RapidKit transforms projects and repositories into workspace intelligence for developers, CI, and AI agents.
-
-![From Code to Shared Understanding](https://raw.githubusercontent.com/rapidkitlabs/rapidkit-npm/main/docs/From%20Code%20to%20Shared%20Understanding.png)
-
-Mermaid source for GitHub docs: [from-code-to-shared-understanding.md](docs/from-code-to-shared-understanding.md).
-
-RapidKit provides the workspace intelligence engine: model, context, impact, verification, evidence, contracts, and governance.
-
-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
+[![Organization: Chistiq](https://img.shields.io/badge/Organization-Chistiq-111111?style=flat-square)](https://github.com/chistiq)
 
-- [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)
-- [Why this architecture helps](#why-this-architecture-helps)
-- [Workspace Intelligence Commands](#workspace-intelligence-commands)
-- [Agent Customization Pack](#agent-customization-pack)
-- [Requirements](#requirements)
-- [Install](#install)
-- [Project workflows](#project-workflows)
-- [CI & evidence](#ci--evidence)
-- [Workspai ecosystem](#workspai-ecosystem)
-- [VS Code extension](#vs-code-extension)
-- [Documentation](#documentation)
-- [Development](#development)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
+> [!IMPORTANT]
+> `rapidkit` is the legacy npm compatibility package. It remains available for
+> existing users and automation during the migration window, but it is planned
+> for deprecation in a future release. New projects and new integrations should
+> use [Workspai](https://www.npmjs.com/package/workspai).
 
-## Typical workflows
+RapidKit helped establish the workspace-oriented CLI that now continues in
+Workspai. This repository is maintained for compatibility, security fixes, and
+safe migration—not as the starting point for new Workspace Intelligence work.
 
-| Question                                      | Command                                                                                      |
-| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| What projects exist in this workspace?        | `workspace model --json`                                                                     |
-| What context should AI agents receive?        | `workspace context --for-agent --json --write`                                               |
-| What breaks if I change this?                 | `workspace impact --from <snapshot>`                                                         |
-| Why is release blocked?                       | `workspace explain release-blocked --json --write`                                           |
-| Trace a diff through blast radius and gates?  | `workspace trace --from .rapidkit/reports/workspace-model-diff-last-run.json --json --write` |
-| What should Studio do for blocked artifacts?  | `workspace remediation-plan --ci --json --write`                                             |
-| Can I safely release?                         | `pipeline --json --strict`                                                                   |
-| How do I align AI tools and CI?               | `workspace agent-sync --write`                                                               |
-| Expose workspace evidence to MCP clients?     | `workspace mcp serve`                                                                        |
-| How do I onboard an existing project?         | `adopt`                                                                                      |
-| How do I bring repositories into a workspace? | `import`                                                                                     |
+## Choose the right path
 
-### Existing project
+| If you are… | Use | Start here |
+| --- | --- | --- |
+| Creating a new workspace or integration | `workspai` | [Workspai CLI](https://github.com/chistiq/workspai) |
+| Connecting an existing project for the first time | `workspai adopt` | [Adopt an existing project](#move-an-existing-project-to-workspai) |
+| Maintaining a script that already calls `rapidkit` | `rapidkit` compatibility CLI | [Legacy command access](#legacy-command-access) |
+| Migrating an existing RapidKit workspace | Workspai migration path | [Migration guide](docs/MIGRATING_TO_WORKSPAI.md) |
 
-```bash
-npx rapidkit adopt /path/to/project --workspace /path/to/workspace
-npx rapidkit workspace model --json
-```
-
-### Agent-ready workspace
-
-```bash
-npx rapidkit workspace context --for-agent --json --write
-npx rapidkit workspace agent-sync --write --refresh-context --preset enterprise
-npx rapidkit workspace agent-sync --write --refresh-context --preset enterprise --experimental-hooks
-```
+## Start new work with Workspai
 
-### Release verification
+You do not need to move an existing project or create a workspace by hand.
+From the project directory:
 
 ```bash
-npx rapidkit pipeline --json --strict
-```
-
-### Adopt in place
-
-```bash
-npx rapidkit adopt /path/to/project --workspace /path/to/workspace --json
-npx rapidkit adopt --json   # from inside the project folder
-```
-
-### Workspace layout
-
-```text
-~/.rapidkit/workspaces.json
-~/rapidkit/workspaces/
-  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 capabilities, one workspace intelligence layer
-
-```text
-Workspace Intelligence  →  every project in the workspace
-Native generation       →  first-class scaffolds and stack-specific project creation
-Deep module generation  →  selected backend engine kits such as FastAPI and NestJS
+cd /path/to/your-project
+npx workspai adopt .
 ```
 
-Workspace Intelligence is not limited to a framework lane. It works across
-RapidKit-created projects, frontend apps, Go, Spring Boot, .NET, FastAPI, NestJS,
-and adopted/imported repositories. The difference is generation depth:
-some stacks have first-class scaffolds, some use official ecosystem generators,
-and existing projects can be adopted in place.
-
-RapidKit treats the **workspace** as the operating boundary: policy, registry,
-evidence, contracts, and release readiness. Projects can live inside the
-workspace or be **adopted** from outside.
+Workspai keeps the source in place and creates or reuses the managed minimal
+workspace at:
 
 ```text
-workspace/
-  .rapidkit-workspace
-  .rapidkit/workspace.json
-  .rapidkit/reports/
-    workspace-model.json
-    workspace-context-agent.json
-    INDEX.json
-    agent-customization-pack.json
-    workspace-skills-index.json
-    rapidkit-mcp-design.json
-  .rapidkit/skills/
-  .rapidkit/AGENT-GROUNDING.md
-  services/api/
-    .rapidkit/project.json
-  AGENTS.md
-  .github/copilot-instructions.md
-  .github/instructions/
-  .github/prompts/
-  .github/skills/
-  .github/agents/
-  .cursor/rules/rapidkit-grounding.mdc
-  CLAUDE.md
-  .vscode/rapidkit-agent-hooks.json
-
-external-project/
-  .rapidkit/project.json
-  .rapidkit/adopt.json
+~/.workspai/workspaces/workspai
 ```
 
-`.rapidkit/workspace.json` is the workspace manifest, not the project list.
-Projects are discovered from workspace project metadata, imported/adopted
-records, and workspace intelligence reports.
-
-Agent-facing outputs are generated from the same evidence layer:
-`workspace context --for-agent --write` writes the agent context report, and
-`workspace agent-sync --write --refresh-context --preset enterprise` writes the
-portable `AGENTS.md`, report index, skills, Copilot/Cursor/Claude surfaces, and
-agent handoff files. The exact generated output inventory is recorded in
-`.rapidkit/reports/agent-customization-pack.json` and summarized in the
-[Agent Customization Pack](#agent-customization-pack) section below.
-
-Every tool gets the same answers for every registered project: what projects
-exist, what stack they use, which commands are safe, what evidence exists, what
-changed, what release gates apply, and what context agents should receive.
-
-## Why this architecture helps
-
-You do not have to change frameworks to benefit from RapidKit.
-
-Use the frontend or backend stack that already fits your product: Next.js,
-Vite, FastAPI, NestJS, Go, Spring Boot, .NET, or an existing repository you
-adopt in place. RapidKit adds the workspace layer around it: project registry,
-safe commands, evidence, impact analysis, agent context, verification, and
-release gates.
-
-That means you can move faster without turning the product into a fragile
-prototype:
-
-- Start new products with governed scaffolds when RapidKit owns the create path
-- Adopt existing products without moving source code or rewriting the stack
-- Give humans, CI, IDEs, and AI agents the same workspace truth
-- Know what changed, what is affected, and what must be verified before release
-- Keep framework stability while adding professional product-development
-  workflows around the codebase
-
-The result is faster product development with clearer boundaries, safer AI
-assistance, and release decisions backed by evidence instead of guesswork.
-
-## 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 [--cache\|--incremental] --json`            | Canonical workspace model (graph-aware, incremental rebuilds)                        |
-| `workspace context --for-agent --json --write`               | Agent-ready context pack + auto agent grounding sync                                 |
-| `workspace agent-sync --write`                               | Agent Customization Pack (AGENTS.md, Copilot, Cursor, Claude, INDEX, skills, agents) |
-| `workspace snapshot --json`                                  | Persist model snapshot                                                               |
-| `workspace diff --from <file\|git[:ref]> --json`             | Diff against snapshot or git                                                         |
-| `workspace impact --from <file> --json`                      | Graph-aware transitive blast-radius evidence                                         |
-| `workspace verify [--strict] --json`                         | Definitive verification gate (subgraph + freshness + policy + fleet evidence)        |
-| `workspace remediation-plan [--ci] --json --write`           | Cross-artifact Studio repair plan for blocked governance cards                       |
-| `workspace explain <target> [--write] --json`                | Human narrative for release blockers, projects, or trace slices                      |
-| `workspace why <target>`                                     | Alias of `workspace explain`                                                         |
-| `workspace trace --from <diff> [--write] --json`             | Diff → impact → gates narrative for agents and IDE handoff                           |
-| `workspace feedback record --json`                           | Append structured agent action outcomes to intelligence history                      |
-| `workspace mcp serve`                                        | Read-mostly stdio MCP bridge over workspace evidence                                 |
-| `workspace graph <emit\|explain\|dot\|mermaid>`              | Inspect and visualize the dependency graph                                           |
-| `workspace watch [--json] [--once]`                          | Daemon mode: keep model + graph in memory, stream change events                      |
-| `workspace run <stage> [--scope project:X] [--reuse-passed]` | Fleet init/test/build/start or custom stages from `.rapidkit/context.json`           |
-
-JSON schemas: `contracts/workspace-intelligence/`. Command coexistence and naming:
-[docs/contracts/NAMING_AND_COEXISTENCE.md](docs/contracts/NAMING_AND_COEXISTENCE.md).
-Details: [commands-reference.md](docs/commands-reference.md).
-
-### Operational intelligence (Phase 4)
-
-After model → diff → impact → verify, use **explain** and **trace** for
-human/agent narratives, **feedback** to record outcomes, and **MCP serve** for
-read-only tool access:
+Continue from the workspace path printed by the CLI:
 
 ```bash
-npx rapidkit workspace explain release-blocked --json --write
-npx rapidkit workspace trace --from .rapidkit/reports/workspace-model-diff-last-run.json --json --write
-npx rapidkit workspace feedback record --json
-npx rapidkit workspace mcp serve
-```
-
-Fleet runs support scoped execution and result reuse:
-
-```bash
-npx rapidkit workspace run test --scope project:api --reuse-passed --json
-npx rapidkit workspace run lint --scope project:api   # custom stage from context.json
-```
-
-### Graph-aware intelligence engine
-
-The workspace model carries a deterministic, first-class **dependency graph** that
-`impact`, `verify`, and `graph` all reason over — so the same evidence drives blast
-radius, gating, and visualization:
-
-- **Transitive blast radius** — `workspace impact` reports each affected project's
-  `distance`, `path`, and `via` edge back to the change, plus centrality-weighted
-  **critical-path hotspots**.
-- **Whole-subgraph gate** — `workspace verify` gates the changed projects **and** their
-  transitive dependents, surfaces graph **integrity** issues (cycles, dangling edges,
-  orphans), and emits a structured `gate` (`passed`/`mode`/`exitCode`/`reasons`).
-- **Transitive freshness** — a deterministic `fresh | stale | unknown` verdict chained
-  through the graph: a dependency change makes every dependent stale, not just by
-  timestamp.
-- **Fact freshness contracts** — `workspace model` and agent context packs mark each
-  workspace fact as durable, derived, evidence-backed, live, or verify-before-use so
-  agents do not reuse stale state as if it were structure.
-- **Policy violations** — model/contract violations are surfaced as structured
-  `policyViolations[]` (not just an exit code) so IDEs and CI can render blockers.
-- **Health history** — every verify run appends to a bounded
-  `.rapidkit/reports/workspace-intelligence-history.json` ring buffer for trends.
-- **Fast rebuilds** — `workspace model --cache` / `--incremental` reuse unchanged
-  project models and re-infer only incident edges, keyed by a structural `inputsHash`.
-- **Watch / daemon** — `workspace watch` keeps the model + graph in memory and streams
-  deterministic `workspace-watch-event.v1` change events (changed projects, graph edge
-  deltas, structural hash) via fast incremental rebuilds.
-
-### Agent Customization Pack
-
-RapidKit can generate a versioned **Agent Customization Pack** so AI tools do
-not start from an ungrounded repository scan. They start from the same workspace
-truth developers and CI use: reports, commands, contracts, blockers, scope, and
-verification evidence.
-
-This is CLI-only and does not require the Workspai extension:
-
-```bash
-# Full enterprise pack:
-# context pack + INDEX + AGENTS.md + Copilot/Cursor/Claude/Codex surfaces + MCP-ready design
-npx rapidkit workspace agent-sync --write --refresh-context --preset enterprise
-
-# Optional advisory VS Code agent hooks (disabled by default in the generated file)
-npx rapidkit workspace agent-sync --write --refresh-context --preset enterprise --experimental-hooks
-
-# Context pack write also syncs grounding by default
-npx rapidkit workspace context --for-agent --json --write
-
-# CI strict gate (fail if required reports missing/stale)
-npx rapidkit workspace agent-sync --write --strict --json
-
-# CI drift gate after sync
-npm run check:agent-customization-drift -- --workspace <workspace-root>
-```
-
-| Artifact / file                                                         | Purpose                                                     |
-| ----------------------------------------------------------------------- | ----------------------------------------------------------- |
-| `.rapidkit/reports/agent-customization-pack.json`                       | Versioned output inventory, target matrix, drift state      |
-| `.rapidkit/reports/workspace-explain-last-run.json`                     | Unified explain / trace narrative for blockers and projects |
-| `.rapidkit/reports/workspace-skills-index.json`                         | Index of operational playbooks (`.rapidkit/skills/*.md`)    |
-| `.rapidkit/skills/rapidkit-*.md`                                        | Operational playbooks (generated by agent-sync)             |
-| `.rapidkit/reports/rapidkit-mcp-design.json`                            | Read-mostly MCP-ready tool design manifest                  |
-| `.rapidkit/reports/INDEX.json`                                          | Read order, blockers, report timestamps                     |
-| `.rapidkit/reports/workspace-context-agent.json`                        | Canonical agent context pack                                |
-| `.rapidkit/reports/artifact-remediation-plan-last-run.json`             | Cross-artifact Studio repair plan                           |
-| `.rapidkit/reports/doctor-remediation-plan-last-run.json`               | Doctor-specific ordered repair plan                         |
-| `.rapidkit/reports/doctor-fix-result-last-run.json`                     | Doctor fix/apply execution result                           |
-| `.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-workspace.instructions.md`               | Copilot workspace scope and command discipline              |
-| `.github/instructions/rapidkit-evidence.instructions.md`                | Copilot scoped rules for `.rapidkit/**`                     |
-| `.github/prompts/rapidkit-diagnose.prompt.md`                           | Copilot reusable diagnose prompt                            |
-| `.github/skills/rapidkit-workspace-intelligence/SKILL.md`               | Workspace Intelligence skill workflow                       |
-| `.github/skills/rapidkit-workspace-intelligence/resources/mcp-tools.md` | Future MCP tool design reference                            |
-| `.github/agents/workspai-advisor.agent.md`                              | Read-only workspace advisor agent                           |
-| `.github/agents/workspai-repair.agent.md`                               | Blocker repair agent                                        |
-| `.github/agents/workspai-release.agent.md`                              | Release safety agent                                        |
-| `.github/agents/workspai-project-onboarder.agent.md`                    | Project onboarding agent                                    |
-| `.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                           |
-| `.vscode/rapidkit-agent-hooks.json`                                     | Optional advisory VS Code hooks (`--experimental-hooks`)    |
-
-The pack also publishes a standard answer contract for agent-facing output:
-
-```text
-Scope -> Evidence -> Diagnosis -> Fix Plan -> Run -> Verify -> Assumptions
+cd ~/.workspai/workspaces/workspai
+npx workspai workspace intelligence run \
+  --for-agent generic \
+  --strict \
+  --json
 ```
 
-That contract is what keeps agent responses operational: every recommendation
-should name the workspace/project scope, cite the evidence it used, explain the
-diagnosis, propose the command or file action, and tell the user how to verify
-the result.
-
-Agents cannot be **forced** probabilistically. This stack makes the desired
-behavior explicit, versioned, and easy for IDEs, CI, and Workspai to audit.
-
-Skip auto-sync after context write: `--no-agent-sync`. Target specific ecosystems: `--target copilot,cursor,claude`.
-
-After `pipeline`, grounding syncs automatically (refresh context + INDEX + agent surfaces). Disable with `--no-agent-sync` or `RAPIDKIT_NO_AGENT_SYNC=1`.
-
-Contract: `contracts/agent-customization-pack.v1.json`. Artifact map:
-[docs/contracts/ARTIFACT_CATALOG.md](docs/contracts/ARTIFACT_CATALOG.md).
-
-CI template: [docs/examples/ci-agent-grounding.yml](docs/examples/ci-agent-grounding.yml).
-
-## Requirements
-
-- Node.js `>= 20.19.6`
-- Python `>= 3.10` (for Python/Core workflows)
-- Java 21+, Go, .NET SDK 8+ (optional, per stack)
-
-## Install
+That chain builds the current workspace model and proof-backed graph, checks
+health and contracts, assesses readiness, verifies the evidence, and prepares
+bounded context for agent and IDE consumers.
 
-Recommended for new installs:
+- Workspai documentation: [workspai.dev](https://www.workspai.dev/)
+- Product overview: [workspai.com](https://www.workspai.com/)
+- Source: [chistiq/workspai](https://github.com/chistiq/workspai)
 
-```bash
-npm install -g workspai
-```
+## Move an existing project to Workspai
 
-Legacy compatibility package:
+The shortest safe migration is adoption in place:
 
 ```bash
-npm install -g rapidkit
+cd /path/to/existing-project
+npx workspai adopt .
 ```
 
-## Project workflows
+The project stays where it is. Workspai writes canonical `.workspai` metadata
+and registers the source with a managed workspace. Do not rename `.rapidkit`
+directories to `.workspai` manually; the schemas, ownership, and artifact paths
+are versioned contracts rather than interchangeable folder names.
 
-### I already have a project
+For several related projects, create one named workspace and adopt each project
+into that boundary:
 
 ```bash
-npx rapidkit adopt /path/to/project
-npx rapidkit import ../orders-api
-cd ~/rapidkit/workspaces/workspai
-
-npx rapidkit workspace model --json
-npx rapidkit doctor workspace --json
-```
+npx workspai create workspace my-workspace --profile minimal --yes
 
-### I want a new project
+cd /path/to/frontend
+npx workspai adopt . \
+  --workspace "$HOME/.workspai/workspaces/my-workspace"
 
-```bash
-npx rapidkit my-workspace --yes --profile polyglot
-cd ~/rapidkit/workspaces/my-workspace
-
-npx rapidkit bootstrap --profile polyglot
-npx rapidkit create project          # interactive kit picker
-npx rapidkit create project nextjs my-web --yes
-npx rapidkit create project fastapi.standard my-api --yes
-cd <project-name> && npx rapidkit init && npx rapidkit dev
+cd /path/to/api
+npx workspai adopt . \
+  --workspace "$HOME/.workspai/workspaces/my-workspace"
 ```
 
-Backend kits: `fastapi.standard`, `nestjs.standard`, `springboot.standard`, `gofiber.standard`, `dotnet.webapi.clean`, and more.
-
-Frontend kits: `nextjs`, `remix`, `vite-react`, `nuxt`, `angular`, `astro`, `sveltekit`, and more — same command shape:
+See [Migrating from RapidKit npm to Workspai](docs/MIGRATING_TO_WORKSPAI.md)
+for CI, workspace, project, and rollback guidance.
 
-```bash
-npx rapidkit create project <kit> <name>
-```
+## Legacy command access
 
-(`create frontend <id>` remains supported as an alias.)
-
-Shortcut: `npx rapidkit platform` (interactive workspace wizard).
-
-### I want CI or release gates
+Existing installations and scripts can continue to inspect the compatibility
+surface:
 
 ```bash
-npx rapidkit pipeline --json --strict
+npx rapidkit --help
+npx rapidkit --version
 ```
 
-Stages individually: `workspace sync`, `doctor workspace --ci`, `analyze --strict`, `readiness --strict`, `autopilot release`.
-
-## 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`           |
-| Readiness | `.rapidkit/reports/release-readiness-last-run.json` |
-| Autopilot | `.rapidkit/reports/autopilot-release-last-run.json` |
-
-Common workspace commands:
+Common maintenance commands remain documented for current RapidKit users:
 
 ```bash
 npx rapidkit doctor workspace
-npx rapidkit workspace agent-sync --write --refresh-context
 npx rapidkit setup <python|node|go|java|dotnet> [--warm-deps]
 npx rapidkit workspace list
 npx rapidkit cache <status|clear|prune|repair>
 npx rapidkit mirror <status|sync|verify|rotate>
 ```
 
-Full syntax: [docs/commands-reference.md](docs/commands-reference.md). CI workflows: [docs/ci-workflows.md](docs/ci-workflows.md) — includes `.github/workflows/ci.yml`, `.github/workflows/workspace-e2e-matrix.yml`, `.github/workflows/windows-bridge-e2e.yml`, `.github/workflows/e2e-smoke.yml`, `.github/workflows/security.yml`.
+Do not use these examples as the foundation of a new integration. Their
+canonical Workspai equivalents and newer `.workspai` artifacts live in the
+[Workspai CLI repository](https://github.com/chistiq/workspai).
+
+## Migration map
 
-## Workspai ecosystem
+| Legacy RapidKit | Canonical Workspai |
+| --- | --- |
+| `npx rapidkit adopt .` | `npx workspai adopt .` |
+| `npx rapidkit create workspace my-workspace` | `npx workspai create workspace my-workspace` |
+| `npx rapidkit create project <kit> <name>` | `npx workspai create project <kit> <name>` |
+| `npx rapidkit workspace model --json` | `npx workspai workspace model --write --json` |
+| `npx rapidkit pipeline --json --strict` | `npx workspai pipeline --json --strict` |
+| `.rapidkit/**` | `.workspai/**` generated through Workspai commands |
+| `~/rapidkit/workspaces/**` | `~/.workspai/workspaces/**` for new managed workspaces |
 
-RapidKit and Workspai form a single workspace intelligence platform.
+Command names may look similar, but migration is not a directory rename. Run
+Workspai so it can create and validate the canonical contracts.
 
-Workspai is the new npm CLI and monorepo for workspace intelligence: model,
-context, impact, verification, evidence, contracts, governance, and the short
-alias package.
+## Compatibility and maintenance policy
 
-The legacy `rapidkit` npm package remains available as a compatibility package
-during the migration window, but new installs should use `workspai`.
+During the migration window this repository accepts:
 
-The Workspai VS Code extension provides the dashboard, sidebar, Incident Studio,
-AI workflows, and developer-facing workspace operations.
+- security and dependency updates;
+- critical compatibility and cross-platform fixes;
+- contract-bridge corrections needed by existing consumers;
+- migration documentation and regression tests.
 
-| Component  | Repository                                                             | Role                                        |
-| ---------- | ---------------------------------------------------------------------- | ------------------------------------------- |
-| npm CLI    | [workspai](https://github.com/rapidkitlabs/workspai)                   | Commands, governance, adoption, CI evidence |
-| Legacy npm | [rapidkit-npm](https://github.com/rapidkitlabs/rapidkit-npm)           | Compatibility package during migration      |
-| 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                          |
+New Workspace Intelligence features, new public integrations, and new user
+journeys belong in [chistiq/workspai](https://github.com/chistiq/workspai).
+No final deprecation date is declared here; it will be announced explicitly
+before the npm package is marked deprecated.
 
-## VS Code extension
+## Legacy documentation
 
-Workspai is the VS Code experience for RapidKit workspace intelligence.
+The documentation in this repository describes the existing `rapidkit`
+compatibility surface and `.rapidkit` artifacts. It is retained for users who
+still operate that version:
 
-Search **Workspai** in the marketplace or install via:
-`ext install rapidkit.rapidkit-vscode`.
+- [Legacy documentation index](docs/README.md)
+- [Legacy command reference](docs/commands-reference.md)
+- [Workspace operations](docs/workspace-operations.md)
+- [Runtime support matrix](docs/contracts/RUNTIME_SUPPORT_MATRIX.md)
+- [Artifact catalog](docs/contracts/ARTIFACT_CATALOG.md)
+- [Security policy](docs/SECURITY.md)
 
-| 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                      |
+For current product documentation, use
+[workspai.dev](https://www.workspai.dev/).
 
-The extension invokes the npm CLI. For the latest `adopt` and frontend generator
-features, install the new Workspai CLI: `npm install -g workspai`. Maintainers
-working on this legacy package can still use `npm link` from this repo
-([Development](#development)).
+## Related repositories
 
-## Documentation
+- [chistiq/rapidkit-npm](https://github.com/chistiq/rapidkit-npm) — this legacy
+  npm compatibility package
+- [chistiq/rapidkit-core](https://github.com/chistiq/rapidkit-core) — RapidKit
+  Core and historical engine integration
+- [chistiq/rapidkit-vscode](https://github.com/chistiq/rapidkit-vscode) — the
+  Workspai experience for VS Code
+- [chistiq/workspai](https://github.com/chistiq/workspai) — canonical CLI and
+  active Workspace Intelligence development
 
-| 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                             |
+## Contributors and maintainers
 
-## Development
+This repository is still tested because migration software must remain safe.
 
 ```bash
-npm ci && npm run build && npm run test
-npm run install:local   # link CLI globally for manual testing
+corepack npm ci
+corepack npm run build
+corepack npm run validate
+corepack npm run validate:docs
+corepack npm run validate:contracts
 ```
 
-Contributors: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md), [docs/ci-workflows.md](docs/ci-workflows.md).
+Workflow ownership is documented in
+[docs/ci-workflows.md](docs/ci-workflows.md). Current CI includes the build and
+test matrix, workspace E2E, Windows bridge E2E, package smoke, and security
+audit.
 
-`npm run prepack` validates embeddings and CLI surfaces before `npm pack` / `npm publish`.
+See [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change. Feature work
+that targets the canonical CLI should be opened against
+[chistiq/workspai](https://github.com/chistiq/workspai).
 
-## Troubleshooting
+## Security
 
-| 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                   |
+Please report vulnerabilities through the process in
+[docs/SECURITY.md](docs/SECURITY.md). Do not publish sensitive details in a
+public issue.
 
 ## License