workspai 0.45.0 → 0.47.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm version](https://img.shields.io/npm/v/workspai.svg?style=flat-square)](https://www.npmjs.com/package/workspai)
 [![Downloads](https://img.shields.io/npm/dm/workspai.svg?style=flat-square)](https://www.npmjs.com/package/workspai)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
 [![Built by Workspai](https://img.shields.io/badge/Built%20by-Workspai-0f172a?logo=github)](https://workspai.dev)
 
 Not another AI coding assistant.
@@ -19,623 +19,398 @@ 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
+### What changes for the user?
 
-### Install
+Without Workspai, an agent repeatedly searches files and reconstructs a partial
+picture. With Workspai, it can ask a bounded question and receive the matching
+entities, nearby relations, and source proofs:
 
 ```bash
-npm install -g workspai
+npx workspai workspace graph search "who implements the login API?" --limit 8 --json
 ```
 
-For short `npx` workflows, use the separate alias package:
+Workspai is broader than a repository code graph. It connects projects, source,
+packages, APIs, infrastructure, pipelines, documentation, decisions, tests, and
+ownership inside one workspace model—then uses that same truth for impact,
+verification, CI, IDEs, MCP, and agent grounding.
+
+### Current measured fixture
+
+| Measure                              | Observed value |
+| ------------------------------------ | -------------: |
+| Registered projects                  |             16 |
+| Knowledge Graph entities             |          1,738 |
+| Knowledge Graph relations            |          2,244 |
+| Portable proofs                      |          2,106 |
+| Readable proof-source artifacts      |            392 |
+| Corpus size (`characters / 4`)       | 134,105 tokens |
+| `api endpoint --limit 8` retrieval   |   2,812 tokens |
+| Observed retrieval payload reduction |          97.9% |
+| Observed corpus/retrieval ratio      |         47.69× |
+
+This is a reproducible observation from one 16-project development workspace on
+2026-07-21, not a universal token-cost or answer-quality claim. See
+[Graph Benchmark Methodology](docs/graph-benchmark-methodology.md) for the source
+hash, formulas, limitations, and publication gate.
 
-```bash
-npx wspai --help
-```
-
-### CLI help
-
-Browse all commands without a global install (first run fetches from npm):
-
-```bash
-npx workspai --help
-```
+## Start here
 
-### Create a governed workspace
+### Install
 
 ```bash
-npx workspai my-workspace --yes --profile polyglot
-cd ~/.workspai/workspaces/my-workspace
-
-npx workspai bootstrap --profile polyglot
-npx workspai create project nextjs my-web --yes
-npx workspai create project fastapi.standard my-api --yes
-
-npx workspai workspace model --json
-npx workspai workspace context --for-agent --json --write
-npx workspai pipeline --json --strict
+npm install -g workspai
+workspai --help
 ```
 
-### Adopt an existing project
+For short `npx` workflows, use the separate alias package:
 
 ```bash
-npx workspai adopt /path/to/project
-cd ~/.workspai/workspaces/workspai
-
-npx workspai workspace model --json
-npx workspai workspace context --for-agent --json --write
-npx workspai pipeline --json --strict
+npx wspai --help
 ```
 
-### What you get
-
-- A governed workspace boundary for projects, policies, reports, and contracts
-- Native create for Workspai-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
-
-Workspai 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`   | Workspai owns the scaffold contract                                     | Create the project with a first-class Workspai kit                     |
-| `official` | The ecosystem has an official generator                                 | Run an available official generator and register it, or adopt planned handoffs |
-| `existing` | The project already exists, or no create path is available or necessary | Register, model, verify, and govern the project without scaffolding it |
-
-Native create is reserved for Workspai-owned kits such as FastAPI, NestJS,
-Go, Spring Boot, and .NET. Official generator paths cover frontend frameworks
-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 Workspai 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:
+`workspai` is the canonical npm package and command. `wspai` is an optional
+short alias for `npx` workflows. RapidKit Core is the optional Python engine
+used only by Python/Core-dependent workflows; it is not a replacement CLI.
+This package is the active CLI boundary in the
+[Workspai monorepo](../../README.md).
 
-- Files
-- Functions
-- Repositories
-
-Production systems require understanding:
-
-- Ownership
-- Architecture
-- Dependencies
-- Operational context
-- Verification requirements
-- Change impact
-
-Workspai 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 Workspai, 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 Workspai transforms projects and repositories into workspace intelligence for developers, CI, and AI agents.
-
-![From Code to Shared Understanding](https://raw.githubusercontent.com/rapidkitlabs/workspai/main/packages/cli/docs/From%20Code%20to%20Shared%20Understanding.png)
+### CLI help
 
-Mermaid source for GitHub docs: [from-code-to-shared-understanding.md](docs/from-code-to-shared-understanding.md).
-
-Workspai provides the workspace intelligence engine: model, context, impact, verification, evidence, contracts, governance, and 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)
-- [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)
-
-## Typical workflows
-
-| 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 .workspai/reports/workspace-model-diff-last-run.json`                |
-| Why is release blocked?                       | `workspace explain release-blocked --json --write`                                           |
-| Trace a diff through blast radius and gates?  | `workspace trace --from .workspai/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`                                                                                     |
-
-### Existing project
+Browse all commands from the latest release without a global install:
 
 ```bash
-npx workspai adopt /path/to/project --workspace /path/to/workspace
-npx workspai workspace model --json
+npx workspai@latest --help
 ```
 
-### Agent-ready workspace
+## Get Workspace Intelligence
 
-```bash
-npx workspai workspace context --for-agent --json --write
-npx workspai workspace agent-sync --write --refresh-context --preset enterprise
-npx workspai workspace agent-sync --write --refresh-context --preset enterprise --experimental-hooks
-```
+Project creation, import, and adoption are entry routes. The core experience
+starts when Workspai builds a durable model of the whole workspace and turns it
+into evidence that different tools can consume.
 
-### Release verification
+Connect an existing project without moving or copying its source:
 
 ```bash
-npx workspai pipeline --json --strict
+npx workspai adopt /path/to/project --json
+cd ~/.workspai/workspaces/workspai
 ```
 
-### Adopt in place
+Execute the canonical chain and persist the shared model, evidence, and
+agent-ready context:
 
 ```bash
-npx workspai adopt /path/to/project --workspace /path/to/workspace --json
-npx workspai adopt --json   # from inside the project folder
-```
-
-### Workspace layout
-
-```text
-~/.workspai/workspaces.json
-~/.workspai/workspaces/
-  workspai/          # managed default (standalone, import, and adopt fallback)
-  my-workspace/      # user-created workspaces
+npx workspai workspace intelligence run --for-agent codex --strict --json
 ```
 
-New workspaces go under `~/.workspai/workspaces/<name>`. Legacy `~/rapidkit/workspaces/*` and `~/Workspai/rapidkits/*` paths remain registered. Use `--output <parent-dir>` for a custom parent.
-
-## Mental model
-
-### Two capabilities, one workspace intelligence layer
+You now have a common source of truth for projects, runtimes, dependencies,
+commands, policies, contracts, health, and release evidence. The first durable
+outputs include:
 
 ```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
+.workspai/reports/workspace-model.json
+.workspai/reports/workspace-context-agent.json
+.workspai/reports/INDEX.json
+.workspai/reports/workspace-intelligence-run-last-run.json
+AGENTS.md
 ```
 
-Workspace Intelligence is not limited to a framework lane. It works across
-Workspai-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.
+Already inside a Workspai workspace? Start directly with the canonical
+`workspace intelligence run --for-agent codex --strict --json` runner.
 
-Workspai 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.
+The broader governance and release pipeline is a separate gate when you are
+ready; it is not a substitute for the canonical chain:
 
-```text
-workspace/
-  .workspai-workspace
-  .workspai/workspace.json
-  .workspai/reports/
-    workspace-model.json
-    workspace-context-agent.json
-    INDEX.json
-    agent-customization-pack.json
-    workspace-skills-index.json
-    workspai-mcp-design.json
-  .workspai/skills/
-  .workspai/AGENT-GROUNDING.md
-  services/api/
-    .workspai/project.json
-  AGENTS.md
-  .github/copilot-instructions.md
-  .github/instructions/
-  .github/prompts/
-  .github/skills/
-  .github/agents/
-  .cursor/rules/workspai-grounding.mdc
-  CLAUDE.md
-  .vscode/workspai-agent-hooks.json
-
-external-project/
-  .workspai/project.json
-  .workspai/adopt.json
+```bash
+npx workspai pipeline --json --strict
 ```
 
-`.workspai/workspace.json` is the workspace manifest, not the project list.
-Legacy `.rapidkit/*` metadata is read as a fallback when opening older workspaces,
-but new Workspai CLI writes target `.workspai/*`.
-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
-`.workspai/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 Workspai.
+## From Code to Shared Understanding
 
-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. Workspai adds the workspace layer around it: project registry,
-safe commands, evidence, impact analysis, agent context, verification, and
-release gates.
+![From Code to Shared Understanding](https://raw.githubusercontent.com/rapidkitlabs/workspai/main/packages/cli/docs/From%20Code%20to%20Shared%20Understanding.png)
 
-That means you can move faster without turning the product into a fragile
-prototype:
+[View the Mermaid source and explanation](docs/from-code-to-shared-understanding.md).
 
-- Start new products with governed scaffolds when Workspai 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
+Workspai is the deterministic layer between source code and its consumers:
 
-The result is faster product development with clearer boundaries, safer AI
-assistance, and release decisions backed by evidence instead of guesswork.
+| Capability            | What it answers                                                                             |
+| --------------------- | ------------------------------------------------------------------------------------------- |
+| **Model**             | What projects, runtimes, frameworks, commands, policies, contracts, and dependencies exist? |
+| **Snapshot and diff** | What changed between two known workspace states?                                            |
+| **Impact**            | Which projects and transitive dependents are affected?                                      |
+| **Evidence**          | What do health, analysis, contracts, and readiness reports prove?                           |
+| **Verify**            | Is the affected workspace ready, blocked, stale, or missing evidence?                       |
+| **Context**           | What should developers, IDEs, and AI agents know before acting?                             |
+| **Explain**           | Why is a project, change, or release blocked, and what should happen next?                  |
+| **Sync**              | How do tools stay aligned with the same current workspace truth?                            |
 
-## Workspace Intelligence Commands
+Create, import, and adopt add software to this boundary. Workspace Intelligence
+then models and governs every registered project, whether Workspai created it or
+it already existed.
 
-Workspace Intelligence provides a shared understanding of projects, dependencies, operational context, and release readiness for developers, CI pipelines, and AI agents.
+## One Intelligence Chain
 
 The canonical execution order is versioned in
-[`contracts/workspace-intelligence-chain.v1.json`](contracts/workspace-intelligence-chain.v1.json).
-CLI, IDE, CI, agent grounding, documentation, and diagrams must consume that
-contract instead of maintaining independent command sequences. It currently defines:
+[`workspace-intelligence-chain.v1.json`](contracts/workspace-intelligence-chain.v1.json):
 
 ```text
-Model -> Snapshot -> Diff -> Impact -> Doctor -> Contract Verify -> Readiness
+Model -> Diff -> Impact -> Doctor + Contract Verify + Analyze -> Readiness
       -> Verify -> Context -> Agent Sync -> Explain
 ```
 
-Each contracted step declares its command, dependencies, consumed and produced
-artifacts, and whether a non-zero structured verdict continues or stops the chain.
-
-| 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 `.workspai/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:
+Each step declares what it consumes, what it produces, and whether its verdict
+continues or stops the chain. The CLI, CI, IDE integrations, generated agent
+instructions, and documentation can therefore use the same contract instead of
+inventing separate workflows.
+
+The execution envelope reports `sync` before Model and baseline resolution
+after Model/before Diff as exactly two `preflight` entries. They are not extra
+chain stages. The report always contains exactly 11 ordered `stages`; exit `0`
+means passed, `1` is a hard execution failure, and `2` is an evidence-blocked
+completed run. See [Unified Workspace Intelligence Runner](docs/workspace-intelligence-runner.md)
+for the complete report, baseline, failure-propagation, and CI contract.
+
+Use `workspace intelligence run --for-agent <agent> --strict --json` to execute
+and enforce this exact contract-backed order. `pipeline --json --strict` remains
+the broader governance/release orchestrator (`sync → doctor → analyze → readiness
+→ autopilot`); it is not an alias for the canonical intelligence chain.
+
+## Core Workflows
+
+| What you need                              | Command                                                                                  |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| Build and persist the current system model | `npx workspai workspace model --json --write`                                            |
+| Generate agent-ready context               | `npx workspai workspace context --for-agent --json --write`                              |
+| Generate portable agent and IDE surfaces   | `npx workspai workspace agent-sync --write --refresh-context --preset enterprise --json` |
+| Save a model baseline                      | `npx workspai workspace snapshot --json`                                                 |
+| Compare with a baseline or Git state       | `npx workspai workspace diff --from <snapshot-or-git-ref> --json`                        |
+| Calculate transitive blast radius          | `npx workspai workspace impact --from <diff-report> --json`                              |
+| Verify affected projects and evidence      | `npx workspai workspace verify --from-impact <impact-report> --json --strict`            |
+| Explain a blocker                          | `npx workspai workspace explain release-blocked --json --write`                          |
+| Inspect a project in the dependency graph  | `npx workspai workspace graph explain <project> --json`                                  |
+| Query proof-backed workspace entities      | `npx workspai workspace graph entities endpoint --json`                                  |
+| Retrieve bounded context for an agent      | `npx workspai workspace graph search "authentication endpoint" --limit 12 --json`        |
+| Measure retrieval payload reduction        | `npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json`     |
+| Trace a relationship and its evidence      | `npx workspai workspace graph path <from> <to> --json`                                   |
+| Compare two knowledge-graph revisions      | `npx workspai workspace graph overlay --from <graph.json> --json`                        |
+| Persist model + agent/MCP graph artifact   | `npx workspai workspace model --write --json`                                            |
+| Run affected project tests                 | `npx workspai workspace run test --affected --blast-radius --json`                       |
+| Run the release/governance gate            | `npx workspai pipeline --json --strict`                                                  |
+| Run the canonical intelligence chain       | `npx workspai workspace intelligence run --for-agent codex --strict --json`              |
+| Expose current evidence to MCP clients     | `npx workspai workspace mcp serve`                                                       |
+
+`workspace verify` consumes current impact, doctor, contract, analysis, and
+readiness evidence. Use `workspace intelligence run` for the canonical chain,
+or `pipeline` for the broader governance/release workflow.
+
+Other useful operational commands:
 
 ```bash
-npx workspai workspace explain release-blocked --json --write
-npx workspai workspace trace --from .workspai/reports/workspace-model-diff-last-run.json --json --write
-printf '%s\n' '{"actionId":"fix-api","summary":"API tests passed","outcome":"ok"}' | npx workspai workspace feedback record --json
-npx workspai workspace mcp serve
-```
-
-`workspace feedback record` requires a single JSON object on stdin. Its
-`actionId`, `summary`, and `outcome` fields are validated before the outcome is
-appended to `workspace-intelligence-history.json`.
-
-Fleet runs support scoped execution and result reuse:
-
-```bash
-npx workspai workspace run test --scope project:api --reuse-passed --json
-npx workspai 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
-  `.workspai/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
-
-Workspai 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 workspai workspace agent-sync --write --refresh-context --preset enterprise
-
-# Optional advisory VS Code agent hooks (disabled by default in the generated file)
-npx workspai workspace agent-sync --write --refresh-context --preset enterprise --experimental-hooks
-
-# Context pack write also syncs grounding by default
-npx workspai workspace context --for-agent --json --write
-
-# CI strict gate (fail if required reports missing/stale)
-npx workspai workspace agent-sync --write --strict --json
-
-# CI drift gate after sync
-npm run check:agent-customization-drift -- --workspace <workspace-root>
-```
-
-| Artifact / file                                                         | Purpose                                                     |
-| ----------------------------------------------------------------------- | ----------------------------------------------------------- |
-| `.workspai/reports/agent-customization-pack.json`                       | Versioned output inventory, target matrix, drift state      |
-| `.workspai/reports/workspace-explain-last-run.json`                     | Unified explain / trace narrative for blockers and projects |
-| `.workspai/reports/workspace-skills-index.json`                         | Index of operational playbooks (`.workspai/skills/*.md`)    |
-| `.workspai/skills/workspai-*.md`                                        | Operational playbooks (generated by agent-sync)             |
-| `.workspai/reports/workspai-mcp-design.json`                            | Read-mostly MCP-ready tool design manifest                  |
-| `.workspai/reports/INDEX.json`                                          | Read order, blockers, report timestamps                     |
-| `.workspai/reports/workspace-context-agent.json`                        | Canonical agent context pack                                |
-| `.workspai/reports/artifact-remediation-plan-last-run.json`             | Cross-artifact Studio repair plan                           |
-| `.workspai/reports/doctor-remediation-plan-last-run.json`               | Doctor-specific ordered repair plan                         |
-| `.workspai/reports/doctor-fix-result-last-run.json`                     | Doctor fix/apply execution result                           |
-| `.workspai/AGENT-GROUNDING.md`                                          | Tool-agnostic grounding doc                                 |
-| `AGENTS.md`                                                             | Open standard for all agents (managed Workspai section)     |
-| `.github/copilot-instructions.md`                                       | GitHub Copilot / VS Code Chat always-on rules               |
-| `.github/instructions/workspai-workspace.instructions.md`               | Copilot workspace scope and command discipline              |
-| `.github/instructions/workspai-evidence.instructions.md`                | Copilot scoped evidence rules                               |
-| `.github/prompts/workspai-diagnose.prompt.md`                           | Copilot reusable diagnose prompt                            |
-| `.github/skills/workspai-workspace-intelligence/SKILL.md`               | Workspace Intelligence skill workflow                       |
-| `.github/skills/workspai-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/workspai-grounding.mdc`                                  | Cursor always-on project rule                               |
-| `CLAUDE.md`                                                             | Claude Code entry (`@AGENTS.md` + managed notes)            |
-| `.claude/rules/workspai-evidence.md`                                    | Claude Code scoped evidence rules                           |
-| `.claude/rules/rapidkit-evidence.md`                                    | Legacy Claude Code scoped evidence mirror                   |
-| `.vscode/workspai-agent-hooks.json`                                     | Optional advisory VS Code hooks (`--experimental-hooks`)    |
-
-Legacy `rapidkit-*` agent files may still be read by older consumers, but canonical Workspai grounding is written under `.workspai` and Workspai-named agent surfaces.
-
-The pack also publishes a standard answer contract for agent-facing output:
-
-```text
-Scope -> Evidence -> Diagnosis -> Fix Plan -> Run -> Verify -> Assumptions
-```
-
-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
-
-```bash
-npm install -g workspai
-```
-
-## Project workflows
-
-### I already have a project
-
-```bash
-npx workspai adopt /path/to/project
-npx workspai import ../orders-api
-cd ~/.workspai/workspaces/workspai
-
-npx workspai workspace model --json
-npx workspai doctor workspace --json
-```
-
-### I want a new project
-
-```bash
-npx workspai my-workspace --yes --profile polyglot
-cd ~/.workspai/workspaces/my-workspace
-
-npx workspai bootstrap --profile polyglot
-npx workspai create project          # interactive kit picker
-npx workspai create project nextjs my-web --yes
-npx workspai create project fastapi.standard my-api --yes
-cd <project-name> && npx workspai init && npx workspai dev
+npx workspai doctor workspace
+npx workspai setup <python|node|go|java|dotnet> [--warm-deps]
+npx workspai workspace list
+npx workspai cache <status|clear|prune|repair>
+npx workspai mirror <status|sync|verify|rotate>
 ```
 
-Backend kits: `fastapi.standard`, `nestjs.standard`, `springboot.standard`, `gofiber.standard`, `dotnet.webapi.clean`, and more.
+### Understand a change
 
-Frontend generators: `nextjs`, `remix`, `vite-react`, `nuxt`, `angular`, `astro`, `sveltekit`, and more — same command shape:
+Create a baseline:
 
 ```bash
-npx workspai create project <kit> <name>
+npx workspai workspace model --json --write
+npx workspai workspace snapshot --json
 ```
 
-(`create frontend <id>` remains supported as an alias.)
-
-Shortcut: `npx workspai platform` (interactive workspace wizard).
-
-### I want CI or release gates
+After a change:
 
 ```bash
-npx workspai pipeline --json --strict
+npx workspai workspace model --json --write
+npx workspai workspace diff \
+  --from .workspai/reports/workspace-model-snapshot.json \
+  --json
+npx workspai workspace impact \
+  --from .workspai/reports/workspace-model-diff-last-run.json \
+  --json
 ```
 
-Stages individually: `workspace sync`, `doctor workspace --ci`, `analyze --strict`, `readiness --strict`, `autopilot release`.
-
-## CI & evidence
-
-| Stage     | Report                                              |
-| --------- | --------------------------------------------------- |
-| Pipeline  | `.workspai/reports/pipeline-last-run.json`          |
-| Doctor    | `.workspai/reports/doctor-last-run.json`            |
-| Analyze   | `.workspai/reports/analyze-last-run.json`           |
-| Readiness | `.workspai/reports/release-readiness-last-run.json` |
-| Autopilot | `.workspai/reports/autopilot-release-last-run.json` |
+Impact reports include affected projects and graph paths back to the change, so
+developers, CI, IDEs, and agents reason over the same blast radius.
 
-Common workspace commands:
+### Ground AI tools
 
 ```bash
-npx workspai doctor workspace
-npx workspai workspace agent-sync --write --refresh-context
-npx workspai setup <python|node|go|java|dotnet> [--warm-deps]
-npx workspai workspace list
-npx workspai cache <status|clear|prune|repair>
-npx workspai mirror <status|sync|verify|rotate>
+npx workspai workspace agent-sync \
+  --write \
+  --refresh-context \
+  --preset enterprise \
+  --json
 ```
 
-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`.
+This generates a versioned Agent Customization Pack from workspace evidence,
+including `AGENTS.md`, report indexes, skills, and supported Copilot, Cursor,
+Claude, and Codex surfaces. AI tools begin with the same scope, commands,
+contracts, blockers, and verification evidence used by humans and CI.
+
+For a user-focused graph quickstart, AI output paths, performance boundaries,
+and reproducible token-efficiency methodology, see the
+[Workspace Knowledge Graph guide](docs/workspace-knowledge-graph.md) and
+[Graph Benchmark Methodology](docs/graph-benchmark-methodology.md).
+
+## Outputs and Consumers
+
+Workspai separates human output, machine output, and durable cross-tool state:
+
+| Output                                    | Primary consumers                                  |
+| ----------------------------------------- | -------------------------------------------------- |
+| CLI summaries and next actions            | Developers and operators                           |
+| JSON stdout                               | Scripts, CI jobs, IDE command bridges, and agents  |
+| Exit codes                                | CI and release gates                               |
+| Persisted `.workspai/reports/*` artifacts | Developers, CI, IDEs, dashboards, and agents       |
+| Generated grounding files                 | Copilot, Cursor, Claude, Codex, and other AI tools |
+| MCP stdio tools                           | MCP-compatible clients                             |
+| Workspace watch events                    | Incremental IDE and automation consumers           |
+
+Important durable outputs:
+
+| Artifact                                                | Producer                       | Used for                              |
+| ------------------------------------------------------- | ------------------------------ | ------------------------------------- |
+| `.workspai/reports/workspace-model.json`                | `workspace model --write`      | Canonical system structure            |
+| `.workspai/reports/workspace-knowledge-graph.json`      | `workspace model --write`      | Proof-backed retrieval and MCP        |
+| `.workspai/reports/workspace-model-diff-last-run.json`  | `workspace diff`               | Structural change evidence            |
+| `.workspai/reports/workspace-impact-last-run.json`      | `workspace impact`             | Blast radius and affected scope       |
+| `.workspai/reports/workspace-verify-last-run.json`      | `workspace verify`             | Structured verification gate          |
+| `.workspai/reports/workspace-context-agent.json`        | `workspace context --write`    | Canonical agent context               |
+| `.workspai/reports/INDEX.json`                          | `workspace agent-sync --write` | Agent read order and report discovery |
+| `.workspai/reports/workspace-explain-last-run.json`     | `workspace explain --write`    | Evidence-backed narrative             |
+| `.workspai/reports/workspace-intelligence-history.json` | Verify and feedback flows      | Trends and audit history              |
+| `.workspai/reports/pipeline-last-run.json`              | `pipeline --json`              | CI and release workflow result        |
+
+See the [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md) for the complete
+writer, schema, and consumer map.
+
+## Onboard Software
+
+All onboarding routes feed the same Workspace Intelligence model.
+
+| Route            | Use it when                                       | Example                                                                                                  |
+| ---------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Adopt            | Existing source should stay in place              | `npx workspai adopt /path/to/project --json`                                                             |
+| Import local     | Existing source should be copied into a workspace | `npx workspai import ../orders-api --workspace /path/to/workspace --json`                                |
+| Import Git       | A repository should be cloned into a workspace    | `npx workspai import https://github.com/acme/orders-api.git --git --workspace /path/to/workspace --json` |
+| Create workspace | You need a new governed boundary                  | `npx workspai create workspace platform --profile polyglot --yes`                                        |
+| Create project   | You need a supported new scaffold                 | `npx workspai create project nextjs web --yes`                                                           |
+| Interactive      | You want Workspai to guide the choice             | `npx workspai create`                                                                                    |
+
+Adopt never moves or copies source. Create can use a Workspai-managed kit or an
+available official ecosystem generator. Unsupported native create requests are
+directed toward official tooling followed by adoption.
+
+Detailed onboarding behavior:
+
+- [Creating Workspaces and Projects](docs/creating-workspaces-and-projects.md)
+- [Workspace Operations](docs/workspace-operations.md)
+- [Create Planner Capabilities](docs/create-planner-capabilities.md)
+
+## Integrations
+
+- **AI tools:** Generate context, `AGENTS.md`, instructions, skills, and tool-specific surfaces with `workspace agent-sync`.
+- **CI:** Consume structured reports and exit codes with `pipeline --json --strict`.
+- **IDEs:** Read the same model, impact, verification, contract, and context artifacts used by CI.
+- **MCP:** Expose read-mostly workspace evidence with `workspace mcp serve`.
+- **VS Code:** Use the [Workspai extension](https://marketplace.visualstudio.com/items?itemName=rapidkit.rapidkit-vscode) for dashboards, impact, evidence, guided workflows, and Incident Studio.
+
+The VS Code extension invokes this npm CLI, so command-line and visual workflows
+share the same contracts and artifacts.
+
+The Marketplace listing may temporarily retain legacy `rapidkit` wording. The
+canonical package, command, metadata namespace, and Node.js requirement are the
+`workspai`, `.workspai`, and Node.js `>=20.19.0` contracts documented here.
 
-## Workspai ecosystem
+## Requirements
 
-RapidKit Labs builds Workspai as a single Workspace Intelligence platform.
+- Node.js `>=20.19.0`
+- npm
+- Python `>=3.10` only for Python/Core-dependent workflows
+- Java, Go, or .NET SDK only when operating those project types
 
-Workspai provides the CLI engine and the VS Code surface: model, context, impact, verification, evidence, contracts, governance, dashboard, sidebar, Incident Studio, AI workflows, and developer-facing workspace operations.
+Python is not required for Python-free workspace profiles, npm-owned backend
+generators, frontend generators, or workspaces created with
+`--skip-python-engine`.
 
-| Component | Repository                                                                  | Role                                        |
-| --------- | --------------------------------------------------------------------------- | ------------------------------------------- |
-| CLI       | [workspai](https://github.com/rapidkitlabs/workspai/tree/main/packages/cli) | 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                          |
+## Documentation
 
-## VS Code extension
+| Documentation                                                                | Purpose                                                       |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| [Documentation index](docs/README.md)                                        | All user, operator, contract, and contributor docs            |
+| [Command reference](docs/commands-reference.md)                              | Complete command syntax and flags                             |
+| [Creating workspaces and projects](docs/creating-workspaces-and-projects.md) | Interactive, automated, location, and linking behavior        |
+| [Workspace operations](docs/workspace-operations.md)                         | Adopt, import, snapshots, archives, contracts, and infra      |
+| [Workspace run](docs/workspace-run.md)                                       | Polyglot and affected-project execution                       |
+| [Workspace Knowledge Graph](docs/workspace-knowledge-graph.md)               | Proof-backed queries, AI/MCP retrieval, and graph outputs     |
+| [Graph benchmark methodology](docs/graph-benchmark-methodology.md)           | Reproducible payload-reduction measurements and claim limits  |
+| [Glossary](docs/GLOSSARY.md)                                                 | Plain-language meanings for model, graph, evidence, and gates |
+| [Doctor command](docs/doctor-command.md)                                     | Health checks, evidence, fixes, and exit codes                |
+| [CI workflows](docs/ci-workflows.md)                                         | CI examples and repository validation                         |
+| [Configuration](docs/config-file-guide.md)                                   | User configuration and precedence                             |
+| [Open-source scenarios](docs/OPEN_SOURCE_USER_SCENARIOS.md)                  | Role-oriented examples                                        |
+| [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md)                       | Canonical files, writers, schemas, and readers                |
+
+Repository workflows include
+[`.github/workflows/ci.yml`](../../.github/workflows/ci.yml),
+[`.github/workflows/workspace-e2e-matrix.yml`](../../.github/workflows/workspace-e2e-matrix.yml),
+[`.github/workflows/windows-bridge-e2e.yml`](../../.github/workflows/windows-bridge-e2e.yml),
+[`.github/workflows/e2e-smoke.yml`](../../.github/workflows/e2e-smoke.yml),
+[`.github/workflows/frontend-generator-smoke.yml`](../../.github/workflows/frontend-generator-smoke.yml),
+[`.github/workflows/security.yml`](../../.github/workflows/security.yml), and the
+maintainer-only
+[`.github/workflows/release-npm-manual.yml`](../../.github/workflows/release-npm-manual.yml).
+See [CI Workflows](docs/ci-workflows.md) for the complete validation and
+contributor-automation map.
 
-Workspai is the VS Code and CLI experience for Workspace Intelligence.
+## Troubleshooting
 
-Search **Workspai** in the marketplace or install via:
-`ext install rapidkit.rapidkit-vscode`.
+| Problem                            | What to check                                  | Next step                                                                |
+| ---------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------ |
+| Node version is rejected           | `node --version`                               | Install Node.js `>=20.19.0`                                              |
+| `npx` resolves an old CLI          | `npx workspai --version`                       | Run `npx workspai@latest --version` or update the global package         |
+| Python/Core workflow cannot start  | `python3 --version`                            | Install Python 3.10+ or use a Python-free profile where supported        |
+| Workspace is not detected          | Look for `.workspai-workspace`                 | Run from the workspace or pass `--workspace <path>`                      |
+| Strict policy blocks a command     | `.workspai/policies.yml`                       | Inspect `workspace policy show` before changing policy                   |
+| Reports are stale                  | Report timestamps                              | Re-run `pipeline` or the required chain stages                           |
+| AI tools ignore workspace evidence | `AGENTS.md` and `.workspai/reports/INDEX.json` | Run `workspace agent-sync --write --refresh-context`                     |
+| Project generator fails            | Runtime and network output                     | Fix the reported prerequisite, then retry or create officially and adopt |
 
-| 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 command-specific behavior, use the
+[Command Reference](docs/commands-reference.md) and
+[Documentation Index](docs/README.md).
 
-The extension invokes this npm CLI. For the latest `adopt` and frontend generator features, install matching CLI version: `npm install -g workspai` or `npm link` from this repo ([Development](#development)).
+## Contributing and Support
 
-## Documentation
+Workspai is MIT-licensed and developed in the open. Contributions to runtime
+support, contracts, documentation, tests, and Workspace Intelligence workflows
+are welcome.
 
-| 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
+From a source checkout:
 
 ```bash
-npm ci && npm run build && npm run test
-npm run install:local   # link workspai and wspai globally for manual testing
+npm ci
+npm run build
+npm test
+npm run validate
 ```
 
-Contributors: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md), [docs/ci-workflows.md](docs/ci-workflows.md).
-
-`npm run prepack` validates embeddings and CLI surfaces before `npm pack` / `npm publish`.
-
-## Troubleshooting
+Use the npm version declared by the repository's `packageManager` field. Python,
+Go, Java, and .NET are required only for workflows that exercise those runtimes.
+To validate only this package, run `npm --workspace workspai run validate` from
+the monorepo root.
 
-| 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            | `.workspai/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                   |
+- Read [CONTRIBUTING.md](https://github.com/rapidkitlabs/workspai/blob/main/packages/cli/CONTRIBUTING.md) before submitting changes.
+- Use [GitHub Issues](https://github.com/rapidkitlabs/workspai/issues) for reproducible bugs and feature requests.
+- Use [GitHub Discussions](https://github.com/rapidkitlabs/workspai/discussions) for questions and design conversations.
+- Read the [Development Guide](docs/DEVELOPMENT.md) for local workflows.
+- Report vulnerabilities through the [Security Policy](docs/SECURITY.md), not a public issue.
+- Review the [Changelog](https://github.com/rapidkitlabs/workspai/blob/main/packages/cli/CHANGELOG.md) before upgrading.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).