workspai 0.48.0 → 0.50.0

package/docs/OPEN_SOURCE_USER_SCENARIOS.md

@@ -1,11 +1,14 @@
 # Workspai Practical User Scenarios (Open Source Edition)
 
-Practical workflows for OSS teams using the npm CLI. Command syntax: [commands-reference.md](./commands-reference.md). Import/adopt details: [workspace-operations.md](./workspace-operations.md).
+This guide shows complete, copyable ways to use Workspai on real projects:
+connect existing code, create new applications, prepare AI context, check
+changes, and use the same results in CI.
 
-All scenarios use the same [Unified Workspace Intelligence Runner](./workspace-intelligence-runner.md):
-`sync` and baseline resolution are reported separately from the exact 11-stage
-chain. Treat exit `1` as an execution failure and exit `2` as an evidence-blocked
-completed run that requires remediation before release.
+Command syntax: [commands-reference.md](./commands-reference.md). Import and
+adopt behavior: [workspace-operations.md](./workspace-operations.md). All
+scenarios use the same
+[Workspace Intelligence runner](./workspace-intelligence-runner.md), so the
+system map, checks, and saved reports stay consistent.
 
 ## Scenario 0 — Existing project (adopt or import)
 
@@ -14,10 +17,10 @@ Goal: connect code you already have without reshuffling repositories.
 ### Adopt in place (keep source where it is)
 
 ```bash
-npx workspai adopt /path/to/existing-app --workspace /path/to/workspace --json
-cd /path/to/workspace
-npx workspai workspace intelligence run --for-agent codex --strict --json
 cd /path/to/existing-app
+npx workspai adopt . --workspace /path/to/workspace --json
+npx workspai project workspace status --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 npx workspai doctor project --json
 ```
 
@@ -78,7 +81,7 @@ release or agent input:
 
 ```bash
 cd ..
-npx workspai workspace intelligence run --for-agent codex --strict --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
 The canonical durable outputs are `.workspai/reports/workspace-model.json`,
@@ -88,6 +91,11 @@ The canonical durable outputs are `.workspai/reports/workspace-model.json`,
 Use `npx workspai pipeline --json --strict` separately as the broader governance
 and release gate.
 
+The model is the canonical workspace boundary. The Knowledge Graph is generated
+from that model-owned inventory, structurally hash-bound to it, and enriched
+with provider facts and proofs. Consumers must not treat the graph as a second
+source of truth.
+
 Success check: the application starts locally, project Doctor reports the
 expected runtime, and the unified run report contains all 11 ordered stages.
 
@@ -197,7 +205,7 @@ loading every source file or the complete graph into a model prompt.
 
 ```bash
 cd my-workspace
-npx workspai workspace intelligence run --for-agent codex --strict --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 npx workspai workspace graph search "authentication endpoint" --limit 12 --json
 npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json
 npx workspai workspace mcp serve

package/docs/README.md

@@ -1,29 +1,64 @@
 # Workspai NPM — Documentation Index
 
-Hub for user and contributor documentation. Start with the [main README](../README.md) for install and quickstarts.
+Workspai helps people and tools understand the same software system. Use these
+guides to connect existing projects, create new ones, map their relationships,
+check changes, prepare AI context, and automate release checks.
 
-`workspai` is the canonical package and command; `wspai` is only an optional
-short `npx` alias. Install with `npm install -g workspai`, or run the current
-release with `npx workspai@latest --help`.
+Start with the [main README](../README.md) for the product overview, or use the
+quickstart below. `workspai` is the main package and command; `wspai` is only a
+shorter optional name.
 
-## Canonical quickstart
+## Quickstart: connect an existing project
+
+Connect an existing project without moving it, then create one saved,
+checkable view for developers, CI, IDEs, MCP clients, and AI agents:
+
+```bash
+cd /absolute/path/to/project
+npx workspai adopt .
+```
+
+`adopt` keeps the project in place and creates or reuses the minimal default
+workspace. Continue from the same project terminal:
 
 ```bash
-npx workspai adopt /path/to/project --json
-cd ~/.workspai/workspaces/workspai
-npx workspai workspace intelligence run --for-agent codex --strict --json
+npx workspai project workspace status --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
-The broader governance/release pipeline is a separate gate:
+The first command proves which canonical workspace owns the project. Workspai
+uses a gitignored machine-local binding and portable project grounding, so
+workspace commands and compatible agents do not need a manual `cd`.
+
+Use `generic` for a vendor-neutral context pack, or select `codex`, `claude`,
+`cursor`, or `orca`. Agent Sync also publishes shared files for GitHub Copilot,
+VS Code, and `AGENTS.md` consumers.
+
+Use the release pipeline when you need the broader release workflow:
 
 ```bash
 npx workspai pipeline --json --strict
 ```
 
-Adoption keeps source in place. The runner preserves contract order and writes
-the authoritative `.workspai/reports/workspace-intelligence-run-last-run.json`
-result alongside the model, agent context, report index, and generated
-instructions; see the [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md).
+Adoption keeps source in place. The command maps the system and its
+connections, checks what changes may affect, runs health and release checks,
+and prepares focused AI context under `.workspai/`. When the workspace is not
+ready, the report shows the reason and points to the files or reports behind
+it. Automation details and supported AI tools are documented in the
+[Unified runner](./workspace-intelligence-runner.md). See the
+[Artifact Catalog](./contracts/ARTIFACT_CATALOG.md) for exact paths, writers,
+schemas, and consumers.
+
+To start with a new workspace instead:
+
+```bash
+npx workspai create workspace my-workspace --profile minimal --yes
+cd ~/.workspai/workspaces/my-workspace
+npx workspai create project nextjs web --yes
+```
+
+From the workspace terminal, create a project, use `adopt` to link one in place,
+or use `import` to copy or clone one into the workspace.
 
 ## Table of contents
 
@@ -83,7 +118,7 @@ with [AI Quickstart](./AI_QUICKSTART.md) only when that is your goal.
 - Create a workspace or project: [creating-workspaces-and-projects.md](./creating-workspaces-and-projects.md)
 - Adopt an existing repo: [workspace-operations.md#import-and-adoption](./workspace-operations.md#import-and-adoption)
 - Scaffold a frontend app: [commands-reference.md](./commands-reference.md) (`create project nextjs <name>`)
-- Canonical intelligence gate: `workspace intelligence run --for-agent codex --strict --json`
+- Canonical intelligence gate: `workspace intelligence run --for-agent generic --strict --json`
 - Broader CI release gate: [commands-reference.md](./commands-reference.md) (`pipeline`, `readiness`)
 - Targeted model/context inspection — schemas in [contracts/workspace-intelligence/](../contracts/workspace-intelligence/)
 

package/docs/README_CONTENT_CONTRACT.md

@@ -58,14 +58,22 @@ as one undifferentiated command wall.
 ## Architectural statements that must remain true
 
 - The **Workspace Model is the canonical source of truth**.
-- The Knowledge Graph is a **derived, revision-bound representation** of
-  governed workspace knowledge.
+- The Knowledge Graph is a **derived, structurally bound representation** of
+  governed workspace knowledge. Its source kind and source artifact are fixed
+  to the canonical Workspace Model contract.
 - Providers emit facts and proofs; they do not independently own the canonical
   graph.
+- Graph enrichment must not mutate the authorizing model during the same run.
+- The canonical project inventory must reconcile discovered, imported,
+  adopted, and contract-declared projects. A missing contract-declared path is
+  a validation warning, not a silently deleted project.
+- Persisted current-state consumers must reject a graph whose structural model
+  hash, workspace identity, or project topology no longer matches the current
+  model.
 - Missing relationships mean **not proven**, not independent.
 - The graph is broader than a code graph, but it is not the entire product.
 - The canonical runner is
-  `npx workspai workspace intelligence run --for-agent codex --strict --json`.
+  `npx workspai workspace intelligence run --for-agent generic --strict --json`.
 - `pipeline` is a broader governance/release orchestrator and must not be taught
   as a replacement for the intelligence chain.
 - The integrated CLI already exposes current capabilities. Future standalone
@@ -74,13 +82,14 @@ as one undifferentiated command wall.
 
 Normative machine sources:
 
-| Statement                      | Source of truth                                         |
-| ------------------------------ | ------------------------------------------------------- |
-| Ordered intelligence chain     | `contracts/workspace-intelligence-chain.v1.json`        |
-| Runtime commands and flags     | `contracts/runtime-command-surface.v1.json`             |
-| Published schemas and paths    | `contracts/published-contract-catalog.v1.json`          |
-| Architecture boundaries        | `contracts/workspace-intelligence-architecture.v1.json` |
-| Artifact writers and consumers | `docs/contracts/ARTIFACT_CATALOG.md`                    |
+| Statement                      | Source of truth                                                      |
+| ------------------------------ | -------------------------------------------------------------------- |
+| Ordered intelligence chain     | `contracts/workspace-intelligence-chain.v1.json`                     |
+| Runtime commands and flags     | `contracts/runtime-command-surface.v1.json`                          |
+| Published schemas and paths    | `contracts/published-contract-catalog.v1.json`                       |
+| Architecture boundaries        | `contracts/workspace-intelligence-architecture.v1.json`              |
+| Model → Graph source binding   | `contracts/workspace-intelligence/workspace-knowledge-graph.v1.json` |
+| Artifact writers and consumers | `docs/contracts/ARTIFACT_CATALOG.md`                                 |
 
 Markdown summarizes these contracts; it does not redefine them.
 

package/docs/ci-workflows.md

@@ -12,9 +12,9 @@ Map of GitHub Actions workflows in this repository. Use this when editing CI to
 | E2E smoke                | `.github/workflows/e2e-smoke.yml`                | Focused bridge regression smoke                                           |
 | Frontend generator smoke | `.github/workflows/frontend-generator-smoke.yml` | Official frontend generator drift gate                                    |
 | Security                 | `.github/workflows/security.yml`                 | Security scanning and policy checks                                       |
-| Manual npm release       | `.github/workflows/release-npm-manual.yml`       | Maintainer-only release gate and publish workflow                          |
+| Manual npm release       | `.github/workflows/release-npm-manual.yml`       | Maintainer-only release gate and publish workflow                         |
 | Contributor onboarding   | `.github/workflows/contributor-onboarding.yml`   | Accepted-contributor onboarding automation                                |
-| Welcome                  | `.github/workflows/welcome.yml`                  | First-issue and first-contribution messages                                |
+| Welcome                  | `.github/workflows/welcome.yml`                  | First-issue and first-contribution messages                               |
 
 The release workflow requires `Frontend Generator Smoke` for the exact release
 SHA. Maintainers must dispatch that workflow against the intended release ref
@@ -29,7 +29,7 @@ For Workspai **consumer workspaces** (not this CLI repo), use the copy-paste tem
 Minimal job:
 
 ```yaml
-- run: npx workspai workspace intelligence run --for-agent codex --strict --json
+- run: npx workspai workspace intelligence run --for-agent generic --strict --json
 - run: npx workspai pipeline --json --strict --no-agent-sync
 - run: node ./node_modules/workspai/scripts/check-agent-customization-drift.mjs --workspace .
 ```

package/docs/commands-reference.md

@@ -8,7 +8,7 @@ Complete CLI syntax for the Workspai CLI. For behavior and workflows, see [works
 npx workspai create # Prompts: workspace | project
 npx workspai create workspace <name> [--profile <profile>] [--yes] [--here|--output <parent-dir>] [--skip-python-engine] [--skip-git] [--dry-run] [--install-method <poetry|venv|pipx>]
 npx workspai bootstrap [--profile <profile>] [--ci] [--json] [--compliance-only]
-npx workspai setup <python|node|go|java|dotnet> [--warm-deps]
+npx workspai setup <python|node|go|java|dotnet|rust|php> [--warm-deps]
 npx workspai pipeline [--json] [--strict] [--skip-verify] [--skip-analyze] [--skip-autopilot] [--autopilot-mode <audit|safe-fix|enforce>] [--agent-sync|--no-agent-sync]
 npx workspai analyze [--workspace <path>] [--json] [--strict] [--output <file>]
 npx workspai readiness [--workspace <path>] [--json] [--strict] [--skip-verify]
@@ -18,7 +18,7 @@ npx workspai autopilot release [--mode <audit|safe-fix|enforce>] [--json] [--out
 Recommended CI:
 
 ```bash
-npx workspai workspace intelligence run --for-agent codex --strict --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
 Run the broader governance and release orchestrators as separate gates; they
@@ -49,6 +49,7 @@ npx workspai workspace policy set <key> <value>
 npx workspai doctor
 npx workspai doctor workspace [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
 npx workspai doctor project [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
+npx workspai project coverage [--project <path>] [--target <0-100>] [--run] [--strict] [--json]
 npx workspai workspace list
 npx workspai workspace foundation ensure [--force] [--json]
 npx workspai workspace share [--output <file>] [--include-paths] [--no-doctor]
@@ -59,7 +60,7 @@ npx workspai workspace contract graph [--json]
 npx workspai workspace intelligence run [--workspace <path>] [--for-agent <agent>] [--strict] [--json]
 npx workspai workspace model [--workspace <path>] [--json] [--write] [--strict] [--cache] [--incremental] [--include-paths] [--include-evidence] [--scan-depth <count>]
 npx workspai workspace context --for-agent [codex|claude|cursor|orca] [--workspace <path>] [--json] [--write] [--agent-sync|--no-agent-sync] [--target <targets>] [--preset minimal|enterprise] [--include-evidence] [--scan-depth <count>]
-npx workspai workspace agent-sync [--workspace <path>] [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|agents,copilot,cursor,claude,codex,orca] [--experimental-hooks] [--hydrate-prompts]
+npx workspai workspace agent-sync [--workspace <path>] [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|agents,copilot,cursor,claude,codex,orca] [--project-grounding managed|local|off] [--experimental-hooks] [--hydrate-prompts]
 npx workspai workspace remediation-plan [--json] [--write] [--ci] [--include-paths]
 npx workspai workspace snapshot [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
 npx workspai workspace diff --from <snapshot-or-report|git[:ref]> [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
@@ -67,7 +68,7 @@ npx workspai workspace impact --from <workspace-diff-report> [--workspace <path>
 npx workspai workspace verify [--from-impact <file>] [--workspace <path>] [--scope project:<name>] [--strict] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
 npx workspai workspace graph [emit|explain|search|benchmark|entities|evidence|path|overlay|dot|mermaid|jsonld|graphml|gexf] [key] [value] [--from <graph.json>] [--output <file>] [--limit <1..100>] [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
 npx workspai workspace eval [init <task> [strategy]|record|status|report|compare --from <report>] [--workspace <path>] [--output <file>] [--json]
-npx workspai workspace watch [--workspace <path>] [--json] [--once] [--scan-depth <count>]
+npx workspai workspace watch [--workspace <path>] [--json] [--graph-stream] [--once] [--scan-depth <count>]
 npx workspai workspace explain|why <target> [--workspace <path>] [--json] [--write]
 npx workspai workspace trace --from <workspace-diff-report> [--workspace <path>] [--json] [--write]
 printf '%s\n' '{"actionId":"fix-api","summary":"API tests passed","outcome":"ok"}' | npx workspai workspace feedback record [--workspace <path>] --json
@@ -77,8 +78,10 @@ npx workspai workspace archive inspect team-workspace.workspai-archive.zip [--ma
 npx workspai workspace archive verify team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network] [--strict] [--json]
 npx workspai workspace archive doctor team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network] [--strict] [--json]
 npx workspai workspace hydrate team-workspace.workspai-archive.zip --output ./team-workspace [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network]
-npx workspai import <path|git-url> [--workspace <path>] [--name <project-name>] [--git] [--enable-modules] [--json]
-npx workspai adopt [path] [--workspace <path>] [--name <project-name>] [--enable-modules] [--dry-run] [--json]
+npx workspai workspace import team-workspace.workspai-archive.zip --output ./team-workspace [--project-grounding managed|local|off] [--dry-run] [--strict] [--json]
+npx workspai workspace connect [directory] [--project-grounding managed|local|off] [--dry-run] [--json]
+npx workspai import <path|git-url> [--workspace <path>] [--name <project-name>] [--git] [--enable-modules] [--project-grounding managed|local|off] [--json]
+npx workspai adopt [path] [--workspace <path>] [--name <project-name>] [--enable-modules] [--project-grounding managed|local|off] [--dry-run] [--json]
 npx workspai snapshot create [name] [--include-projects] [--reason <text>] [--json]
 npx workspai snapshot list [--json]
 npx workspai snapshot inspect <name> [--json]
@@ -87,6 +90,7 @@ npx workspai project archive <name> [--reason <text>] [--dry-run] [--json]
 npx workspai project archives [--json]
 npx workspai project restore <archive> [--name <project-name>] [--force] [--dry-run] [--json]
 npx workspai project delete <name> [--permanent --confirm <name>] [--dry-run] [--json]
+npx workspai project workspace [status|relink] [--workspace <path>] [--project <path>] [--json]
 npx workspai workspace init
 npx workspai workspace run <init|test|build|start> [--affected] [--blast-radius] [--since <ref>] [--parallel] [--max-workers <n>] [--strict] [--json]
 npx workspai infra plan [--workspace <path>] [--json] [--dry-run] [--verbose]
@@ -95,6 +99,17 @@ npx workspai infra down [--workspace <path>] [--volumes]
 npx workspai infra status [--workspace <path>] [--json] [--strict]
 ```
 
+Every workspace action has action-scoped help generated from the same contract
+that governs its accepted flags. For example:
+
+```bash
+npx workspai workspace impact --help
+npx workspai workspace graph search --help
+```
+
+This avoids guessing whether an option such as `--write`, `--from`, or
+`--output` belongs to a particular action.
+
 The contract graph includes its backward-compatible service projection, the
 canonical `workspace-dependency-graph.v1` project topology, and the portable
 `workspace-knowledge-graph.v1` evidence graph. The knowledge projection covers
@@ -138,6 +153,12 @@ per immutable graph object and invalidated automatically when a new graph is
 built. `dot` and `mermaid` intentionally remain project-topology renderers and
 emit raw text for direct piping.
 
+Every integrated `workspace graph` Knowledge Graph is derived from the
+canonical Workspace Model. Its contract fixes the source artifact to
+`.workspai/reports/workspace-model.json` and binds the graph to the model's
+stable structural SHA-256. Graph providers enrich that model-owned inventory;
+they never write facts back into the authorizing model during the same run.
+
 `workspace graph search <query> --limit <n> --json` returns bounded entities,
 one-hop relations, related entity summaries, and portable proofs instead of the
 complete graph. `workspace graph benchmark <query> --limit <n> --json` compares
@@ -190,9 +211,11 @@ Workspace profile compatibility is enforced consistently across `create project`
 `import`, `adopt`, and `bootstrap` compliance. In default `warn` policy mode,
 cross-runtime additions are allowed with a recommendation such as
 `npx workspai bootstrap --profile polyglot`; in `strict` mode, mismatches are
-blocked before the project is registered. Observed runtimes such as Rust, C,
-and C++ are counted in the workspace runtime mix even when Workspai does not own
-a native scaffold for them.
+blocked before the project is registered. Rust is an extended runtime with
+Axum/Tauri scaffolding and Cargo lifecycle support. PHP is extended through
+Laravel and Composer lifecycle support. Observed runtimes such as C and C++ are
+still counted in the workspace runtime mix even when Workspai does not own a
+native scaffold for them.
 
 Core module/template commands are intentionally narrower than runtime detection.
 RapidKit Core modules are guaranteed only for RapidKit Core module-enabled kits:
@@ -223,6 +246,10 @@ Examples:
 ```bash
 npx workspai create project fastapi.standard my-api --yes
 npx workspai create project nextjs my-web --yes
+npx workspai create project rust.axum my-rust-api --yes
+npx workspai create project desktop.tauri my-desktop-app --yes
+npx workspai create project extension.vscode my-extension --yes
+npx workspai create project php.laravel my-laravel-api --yes
 ```
 
 Generator-specific options include `--port`, Spring Boot
@@ -232,7 +259,11 @@ and .NET `--dotnet-version`/`--target-framework`/`--nullable`. Use
 
 `create frontend <id> <name>` is still accepted and routes to the same generators.
 
-`project commands` shows the effective command contract for the current project. Core-backed FastAPI/NestJS projects can use module commands such as `add` and `modules`. Frontend apps, Go, Spring Boot, .NET, and adopted/imported repositories use runtime lifecycle commands and workspace governance while Core module mutation remains disabled.
+`project commands` shows the effective command contract for the current project.
+Core-backed FastAPI/NestJS projects can use module commands such as `add` and
+`modules`. Frontend, desktop, extension, Go, Spring Boot, .NET, Rust, PHP, and
+adopted/imported projects use runtime lifecycle commands and workspace
+governance while Core module mutation remains disabled.
 
 ## Operations
 

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -20,6 +20,28 @@ The canonical `.workspai-workspace` marker must remain trackable. Generated
 workspace `.gitignore` files exclude legacy/local engine state but do not
 exclude the canonical marker.
 
+## Project entry and grounding
+
+These paths are relative to each registered project root, not the workspace
+root:
+
+| Artifact | Writer | Schema / format | Portability and reader purpose |
+| --- | --- | --- | --- |
+| `.workspai/workspace-link.local.json` | `adopt`, `import`, project creation, `workspace sync`, `project workspace relink` | `project-workspace-link.v1` | Machine-local absolute binding; always gitignored and never an agent evidence payload |
+| `.workspai/reports/project-context-agent.json` | Project lens reconciliation and `workspace agent-sync --write` | `project-context-agent.v1` | Portable bounded model/graph/proof projection for project-local agents |
+| `.workspai/PROJECT-GROUNDING.md` | Project lens reconciliation | Markdown | Portable human/agent entry guide with path-free workspace references |
+| `AGENTS.md` managed section | Project lens reconciliation in `managed` mode | Managed Markdown block | Preserves user content and routes compatible agents to project/workspace evidence |
+
+The project link is validated against the canonical workspace contract and a
+SHA-256 binding over workspace identity, project identity, portable relative
+path, machine paths, and relationship. Project context generation rejects
+absolute paths before writing. `managed`, `local`, and `off` grounding modes
+control portable project surfaces and converge by removing stale managed
+sections and ignore rules during transitions; they never make the
+machine-local link publishable. The context is bounded but not count-only: it
+includes topology, API/deployment/test surfaces, blockers, portable proofs,
+and model/graph freshness for the selected project.
+
 ## Naming conventions
 
 | Pattern           | Meaning                                | Examples                                                     |
@@ -30,18 +52,19 @@ exclude the canonical marker.
 
 ## Governance evidence loop
 
-| Command                              | Primary artifact                                            | Schema version                  | JSON Schema                                                  |
-| ------------------------------------ | ----------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ |
-| `doctor workspace`                   | `.workspai/reports/doctor-last-run.json`                    | `doctor-workspace-evidence-v1`  | `contracts/doctor-workspace-evidence.v1.json`                |
-| `doctor project`                     | `.workspai/reports/doctor-project-last-run.json`            | `doctor-project-evidence-v1`    | `contracts/doctor-project-evidence.v1.json`                  |
-| `doctor * --plan`                    | `.workspai/reports/doctor-remediation-plan-last-run.json`   | `doctor-remediation-plan-v2`    | `contracts/doctor-remediation-plan.v2.json`                  |
-| `doctor * --fix/--apply`             | `.workspai/reports/doctor-fix-result-last-run.json`         | `rapidkit-doctor-fix-result-v1` | `contracts/workspace-intelligence/doctor-fix-result.v1.json` |
-| `workspace remediation-plan --write` | `.workspai/reports/artifact-remediation-plan-last-run.json` | `artifact-remediation-plan-v1`  | `contracts/artifact-remediation-plan.v1.json`                |
-| `analyze`                            | `.workspai/reports/analyze-last-run.json`                   | `rapidkit-analyze-v1`           | `contracts/analyze-last-run.v1.json`                         |
-| `readiness`                          | `.workspai/reports/release-readiness-last-run.json`         | `release-readiness-v1`          | `contracts/release-readiness.v1.json`                        |
-| `pipeline`                           | `.workspai/reports/pipeline-last-run.json`                  | `rapidkit-pipeline-v1`          | `contracts/pipeline-last-run.v1.json`                        |
-| `autopilot release`                  | `.workspai/reports/autopilot-release-last-run.json`         | `autopilot-release-v1`          | `contracts/autopilot-release.v1.json`                        |
-|                                      | `.workspai/reports/autopilot-release.json`                  | (alias, same payload)           | `contracts/autopilot-release.v1.json`                        |
+| Command                              | Primary artifact                                            | Schema version                      | JSON Schema                                                  |
+| ------------------------------------ | ----------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------ |
+| `doctor workspace`                   | `.workspai/reports/doctor-last-run.json`                    | `doctor-workspace-evidence-v1`      | `contracts/doctor-workspace-evidence.v1.json`                |
+| `doctor project`                     | `.workspai/reports/doctor-project-last-run.json`            | `doctor-project-evidence-v1`        | `contracts/doctor-project-evidence.v1.json`                  |
+| `project coverage`                   | `.workspai/reports/project-test-coverage-last-run.json`     | `workspai.project-test-coverage.v1` | `contracts/project-test-coverage.v1.json`                    |
+| `doctor * --plan`                    | `.workspai/reports/doctor-remediation-plan-last-run.json`   | `doctor-remediation-plan-v2`        | `contracts/doctor-remediation-plan.v2.json`                  |
+| `doctor * --fix/--apply`             | `.workspai/reports/doctor-fix-result-last-run.json`         | `rapidkit-doctor-fix-result-v1`     | `contracts/workspace-intelligence/doctor-fix-result.v1.json` |
+| `workspace remediation-plan --write` | `.workspai/reports/artifact-remediation-plan-last-run.json` | `artifact-remediation-plan-v1`      | `contracts/artifact-remediation-plan.v1.json`                |
+| `analyze`                            | `.workspai/reports/analyze-last-run.json`                   | `rapidkit-analyze-v1`               | `contracts/analyze-last-run.v1.json`                         |
+| `readiness`                          | `.workspai/reports/release-readiness-last-run.json`         | `release-readiness-v1`              | `contracts/release-readiness.v1.json`                        |
+| `pipeline`                           | `.workspai/reports/pipeline-last-run.json`                  | `rapidkit-pipeline-v1`              | `contracts/pipeline-last-run.v1.json`                        |
+| `autopilot release`                  | `.workspai/reports/autopilot-release-last-run.json`         | `autopilot-release-v1`              | `contracts/autopilot-release.v1.json`                        |
+|                                      | `.workspai/reports/autopilot-release.json`                  | (alias, same payload)               | `contracts/autopilot-release.v1.json`                        |
 
 Side/cache (not gates): `.workspai/reports/doctor-workspace-cache.json` (`doctor-workspace-cache-v2`).
 
@@ -64,11 +87,13 @@ this plan before inventing per-card repair logic. The plan carries ordered actio
 operations where deterministic, refresh/verify commands, risk, approval state, and rollback
 strategy.
 
-When `doctor project` runs inside a workspace, the workspace report remains the canonical
-governance artifact and Doctor mirrors `doctor-project-last-run.json`,
-`doctor-remediation-plan-last-run.json`, and `doctor-fix-result-last-run.json` into the scoped
-project's `.workspai/reports/` directory. This keeps Studio, agents, and project-local operators on
-the same evidence without losing the workspace source of truth.
+When `doctor project` runs inside a workspace, the project-local report is written beside the
+project and the workspace receives both a latest alias and a collision-safe project copy under
+`.workspai/reports/projects/<project-slug>--<identity-hash>/`. Coverage evidence follows the same
+three-location rule. The hash is derived from workspace-relative identity, so projects with the
+same folder name cannot overwrite each other. Remediation plans and fix results are also mirrored
+into the scoped project. Studio, CI, and project-local tools can therefore use the same evidence
+without guessing which project produced a latest alias.
 
 ## Workspace intelligence
 
@@ -108,10 +133,14 @@ status/exit coherence, hard-failure skip propagation, and the aggregate verdict.
 See [Unified Workspace Intelligence Runner](../workspace-intelligence-runner.md)
 for the normative user and integration semantics.
 
-`workspace-model.json` and `workspace-knowledge-graph.json` are published as one
-recoverable artifact transaction. The graph carries a SHA-256 `source` binding
-to the canonical model, so consumers must reject a graph whose source hash does
-not equal the current structural model hash.
+`workspace-model.json` and `workspace-knowledge-graph.json` are published under
+one workspace lock as a rollback-capable artifact transaction. Individual file
+replacement is atomic, and a partial set failure restores both preimages. The
+model is canonical; the graph is derived and cannot mutate it during the run.
+The graph contract fixes `source.kind` to `workspace-model`,
+`source.artifact` to `.workspai/reports/workspace-model.json`, and `source.hash`
+to the model's stable structural SHA-256. Current-state consumers must reject a
+graph whose binding does not match the current model.
 
 `workspace graph jsonld|graphml|gexf --output <path>` creates explicit interchange
 projections from that bound graph. These files are portable exports, not competing
@@ -150,11 +179,13 @@ sources: package manifests (`package.json` deps, `pyproject.toml` path deps, `go
 replace → `package-dep`), cross-boundary JS/TS source imports (`code-import`), the
 workspace contract (`dependsOn` → `service-dependsOn`, matched `publishes`/`consumes`
 → `event-pub-sub`, env↔port references → `shared-resource`), and an optional manual
-override file. Node/edge ordering and `hashDependencyGraph` are stable, so the graph is
-embedded as a first-class field of `workspace-model.v1` (`model.graph`) on every
-`buildWorkspaceModel` run; `hashModel` normalizes the embedded `graph.generatedAt` so the
-structural graph participates in the model hash without causing timestamp drift.
-(`model.graph` is additive/optional for pre-graph readers.)
+override file. Node/edge ordering and `hashDependencyGraph` are stable, so the compact
+topology is embedded as the canonical `workspace-model.v1.projectTopology` field on every
+`buildWorkspaceModel` run. `hashWorkspaceModel` normalizes
+`projectTopology.generatedAt`, so the structural topology participates in the model hash
+without causing timestamp drift. During the v1 migration window the CLI also emits the
+deprecated `graph` compatibility alias. Consumers must read `projectTopology`; when both
+fields exist, validation requires them to be structurally identical.
 
 **Manual overrides.** `.workspai/workspace-graph.overrides.json` (`{ "edges": [{ "from",
 "to", "kind", "evidence" }] }`) declares authoritative edges that win over inference for
@@ -191,6 +222,12 @@ on each settled change, driven by graph-aware incremental rebuilds. Events carry
 removed projects, graph edge deltas, structural `modelHash`, and `mode`/`durationMs`. Canonical
 source: `src/workspace-watch.ts`.
 
+Use `workspace watch --graph-stream --json` for the transport-neutral
+`workspace-graph-stream.v1` feed consumed by IDEs. The first line is an
+authoritative snapshot; subsequent lines are hash-linked, revisioned deltas.
+Consumers must request a new snapshot after any revision, identity, generation,
+schema, validation, or hash-continuity failure.
+
 **Health/impact history.** Each `workspace verify` run appends a compact record to
 `.workspai/reports/workspace-intelligence-history.json` (`workspace-intelligence-history.v1`),
 a ring buffer capped at the 50 most-recent entries (verdict, risk, freshness, gate, counts).
@@ -239,6 +276,14 @@ reused and the dependency graph re-infers only edges incident to changed project
 changes or project renames, and rescans code-imports fully when the node set changes. Reported
 modes: `full` / `incremental` / `unchanged`.
 
+The model command adds a non-structural `build` object to its JSON output and,
+when `--write` is used, to the persisted model result. `mode`, `outcome`, and
+`engineStatus` tell IDE/CI consumers
+whether the result was rebuilt, partially reused, or fully reused. This
+provenance is deliberately excluded from the canonical workspace-model hash,
+so switching between full, cached, and incremental execution cannot make the
+paired knowledge graph appear stale.
+
 ### Freshness metadata (`rapidkit-freshness-metadata-v1`)
 
 Intelligence reports carry a shared freshness envelope so any consumer (CLI
@@ -356,7 +401,7 @@ canonical file. Legacy files remain readable during the compatibility window.
 ## Consumer rules
 
 1. **Project count:** read `workspace-registry.v1.json` (or run `workspace registry status --json`).
-2. **Workspace Intelligence chain:** run `workspace intelligence run --for-agent codex --strict --json` to preserve Model → Diff → Impact → Doctor + Contract Verify + Analyze → Readiness → Verify → Context → Agent Sync → Explain. `pipeline` is the broader governance/release orchestrator and `autopilot` is a separate release surface; neither redefines the canonical chain. Use `pipeline-last-run.json` only for the pipeline orchestration summary.
+2. **Workspace Intelligence chain:** run `workspace intelligence run --for-agent generic --strict --json` to preserve Model → Diff → Impact → Doctor + Contract Verify + Analyze → Readiness → Verify → Context → Agent Sync → Explain. `pipeline` is the broader governance/release orchestrator and `autopilot` is a separate release surface; neither redefines the canonical chain. Use `pipeline-last-run.json` only for the pipeline orchestration summary.
 3. **Do not** use `workspace.json.projects` (removed in schema 1.0).
 4. Prefer `schemaVersion` constants in each artifact; legacy `v1` on readiness is accepted when reading old reports.
 5. **Agent retrieval:** start with `AGENTS.md` and `.workspai/reports/INDEX.json`, then use `workspace graph search <query> --limit <n> --json` or MCP `searchWorkspaceGraph` for question-sized facts. Follow returned proof paths to source evidence. Read the full context, model, or graph only when the bounded result is insufficient.

package/docs/contracts/COMMAND_OWNERSHIP_MATRIX.md

@@ -58,10 +58,12 @@ These nested Commander commands are implemented and orchestrated by Workspai CLI
 - `product manifest create`
 - `product plan`
 - `project commands`
+- `project coverage`
 - `project archives`
 - `project archive`
 - `project restore`
 - `project delete`
+- `project workspace`
 - `snapshot create`
 - `snapshot inspect`
 - `snapshot list`

package/docs/contracts/RUNTIME_SUPPORT_MATRIX.md

@@ -18,9 +18,9 @@ It separates three concerns:
 | Go                  | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
 | Java / Spring Boot  | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
 | .NET / ASP.NET Core | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
-| PHP                 | observed    |       no |    yes | help                                              |              no | observed  |
+| PHP                 | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
 | Ruby                | observed    |       no |    yes | help                                              |              no | observed  |
-| Rust                | observed    |       no |    yes | help                                              |              no | observed  |
+| Rust                | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
 | Elixir              | observed    |       no |    yes | help                                              |              no | observed  |
 | Clojure             | observed    |       no |    yes | help                                              |              no | observed  |
 | Scala               | observed    |       no |    yes | help                                              |              no | observed  |
@@ -40,7 +40,7 @@ It separates three concerns:
 | Tier        | Frameworks                                                                                                                                                                                                                          |
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | first-class | FastAPI, NestJS                                                                                                                                                                                                                     |
-| extended    | Go/Fiber, Go/Gin, Spring Boot, ASP.NET Core, Django, Flask, Express, Fastify, Koa, Echo, Laravel, Symfony, Rails, Sinatra, Actix, Axum, Rocket, Phoenix, Next.js, Remix, React, Vue, Svelte, Solid, Nuxt, Angular, Astro, SvelteKit |
+| extended    | Go/Fiber, Go/Gin, Spring Boot, ASP.NET Core, Django, Flask, Express, Fastify, Koa, Echo, Laravel, Symfony, Rails, Sinatra, Actix, Axum, Rocket, Phoenix, Next.js, Remix, React, Vue, Svelte, Solid, Nuxt, Angular, Astro, SvelteKit, Tauri, Electron, VS Code Extension |
 | observed    | Python, Node.js, Go, Java, PHP, Ruby, Rust, Elixir, Unknown/generic projects                                                                                                                                                        |
 
 ## Import Policy

package/docs/contracts/rapidkit-cli-contracts.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://getrapidkit.com/schemas/rapidkit-cli-contracts.json",
-    "title": "RapidKit Core CLI Contracts",
+    "$id": "https://workspai.dev/schemas/rapidkit-cli-contracts.json",
+    "title": "Workspai CLI Contracts (RapidKit Core Compatibility)",
     "type": "object",
     "definitions": {
         "VersionResponse": {