workspai 0.49.0 → 0.51.0

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
@@ -245,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

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": {

package/docs/create-planner-capabilities.md

@@ -21,10 +21,15 @@ Native create is reserved for Workspai-owned kits with deterministic contracts:
 - Go Fiber and Go Gin
 - Spring Boot
 - ASP.NET Core Web API
+- Rust / Axum
 
 These kits can be exposed through `workspai create project` because Workspai can
 create the project and immediately produce the expected `.workspai` metadata,
 workspace registry entries, doctor evidence, and workspace model data.
+They use a tested dependency baseline instead of floating to new upstream
+majors during creation. Baseline upgrades ship as reviewed Workspai changes so
+the same Workspai version remains reproducible across developer machines and
+CI.
 
 ## Official generators
 
@@ -35,19 +40,45 @@ by Workspai and then registered in Workspace Intelligence:
 - React Router: `npx create-react-router@latest <name>`
 - React, Vue, Svelte, Solid, and Vite: `npm create vite@latest <name> ...`
 - Nuxt: `npx create-nuxt@latest <name> ...`
-- Angular: `npx @angular/cli@19 new <name>`
-- Astro: `npm create astro@4 <name>`
+- Angular: `npx @angular/cli@latest new <name>`
+- Astro: `npm create astro@latest <name>`
 - SvelteKit: `npx sv@latest create <name>`
+- Tauri: `npm create tauri-app@latest <name> -- --template vanilla-ts`
+- Electron Forge: `npx create-electron-app@latest <name> --template=vite-typescript`
+- VS Code Extension: `npx --package yo@latest --package generator-code@latest -- yo code <name> ...`
+- Laravel: `composer create-project --no-interaction --prefer-dist --stability=stable laravel/laravel <name>`
+
+### Stable version and runtime policy
+
+Available official entries request the ecosystem's current stable release at
+execution time; Workspai does not silently pin an older framework major. npm
+generators use the `latest` distribution tag and Composer is restricted to
+stable packages. npm engine checks run in strict mode, so an upstream generator
+that does not support the operator's Node.js runtime stops before Workspai
+claims the scaffold is usable.
+
+Workspai also checks non-Node prerequisites before invoking a generator:
+
+- Tauri requires Rust and Cargo in addition to its platform-specific system
+  dependencies.
+- Electron Forge requires Git.
+- VS Code Extension generation requires Git unless `--skip-git` is selected.
+- Laravel requires PHP and Composer; Node.js/npm remain recommended for
+  frontend asset workflows.
+
+The official generator remains the authority for exact framework/runtime
+compatibility because its stable requirements can change independently of a
+Workspai release. The selected policy is persisted as `latest-stable` in
+project metadata and create evidence.
 
 Other ecosystems are planned official handoffs but are not automated yet:
 
 - WordPress site: `wp core download`, `wp config create`, `wp db create`, `wp core install`
 - WordPress block/plugin: `npx @wordpress/create-block@latest <slug>`
-- Laravel: `composer create-project laravel/laravel <name>`
 - Symfony: `composer create-project symfony/skeleton <name>`
 - Rails: `rails new <name>`
 
-These are `official` candidates, not active native kits. Until each planned
+The remaining entries are `official` candidates, not active native kits. Until each planned
 post-create contract is implemented end to end, Workspai should guide users to
 create externally and then adopt/import the project.
 
@@ -72,7 +103,7 @@ Adoption still gives the project Workspace Intelligence:
 ## Product rule
 
 Do not convert an unsupported or ambiguous stack request into a different native
-kit. For example, a PHP, WordPress, Laravel, Symfony, or Rails request must not
+kit. For example, a WordPress, Symfony, or Rails request must not
 be translated into FastAPI, NestJS, Go, Java, .NET, or a frontend kit.
 
 If executable create is unavailable, the planner should explain the supported

package/docs/creating-workspaces-and-projects.md

@@ -204,12 +204,29 @@ or update a registry.
 Workspace creation does not merge into or overwrite an existing target. If the
 resolved directory already exists, choose another name or output parent.
 
-To bring an existing repository into Workspai, use `adopt` or `import` instead:
+To bring existing software into Workspai, use the operation that matches who
+owns its location:
 
 ```bash
+# Keep a project where it is.
 npx workspai adopt /path/to/project
+
+# Copy or clone a project into the selected workspace.
+npx workspai import /path/to/project --workspace /path/to/my-workspace
+
+# Register an existing Workspai workspace without moving it.
+npx workspai workspace connect /path/to/existing-workspace
+
+# Restore and register a portable workspace archive.
+npx workspai workspace import team.workspai-archive.zip --output ./team
 ```
 
+Running `npx workspai create` interactively exposes the same choices as
+“Create a project”, “Add existing software”, and—when appropriate—“Create
+another workspace”. Inside a workspace, project and onboarding choices appear
+first; creating another workspace remains an explicit escape hatch rather than
+the default.
+
 ## Main workspace files
 
 A normal workspace includes:
@@ -249,7 +266,7 @@ npx workspai create
 If you choose project creation, the same project flow is used.
 
 When the terminal is interactive and the current directory is not inside a
-workspace, **every supported backend and frontend kit** shows the workspace
+workspace, **every supported backend, frontend, desktop, and extension kit** shows the workspace
 management question before scaffolding:
 
 ```text
@@ -275,7 +292,12 @@ npx workspai create project fastapi.standard api
 npx workspai create project gofiber.standard gateway
 npx workspai create project springboot.standard orders
 npx workspai create project dotnet.webapi.clean billing
+npx workspai create project rust.axum telemetry-api
 npx workspai create project frontend.nextjs dashboard
+npx workspai create project desktop.tauri desktop-app
+npx workspai create project desktop.electron admin-console
+npx workspai create project extension.vscode editor-tools
+npx workspai create project php.laravel customer-api
 ```
 
 The shorter frontend alias remains available:
@@ -295,6 +317,7 @@ npx workspai create frontend nextjs dashboard
 | `gogin.standard`      | Go      | Workspai npm CLI     | No                   |
 | `springboot.standard` | Java    | Workspai npm CLI     | No                   |
 | `dotnet.webapi.clean` | .NET    | Workspai npm CLI     | No                   |
+| `rust.axum`           | Rust    | Workspai npm CLI     | No                   |
 
 NestJS runs on Node.js, but its current scaffold is provided through the
 RapidKit Core bridge.
@@ -320,6 +343,34 @@ Workspai has official-generator paths for:
 The ecosystem's official generator creates the application. Workspai then adds
 project metadata and performs the selected workspace registration.
 
+## Desktop, extension, and additional backend generators
+
+| Category  | Project           | Kit                | Creation owner                         |
+| --------- | ----------------- | ------------------ | -------------------------------------- |
+| Backend   | Axum              | `rust.axum`        | Workspai deterministic Cargo baseline |
+| Backend   | Laravel           | `php.laravel`      | Composer / Laravel                     |
+| Desktop   | Tauri             | `desktop.tauri`    | create-tauri-app                       |
+| Desktop   | Electron Forge    | `desktop.electron` | create-electron-app                    |
+| Extension | VS Code Extension | `extension.vscode` | generator-code                         |
+
+Every generated project receives a canonical `kind` and `category`. The four
+user-facing categories are `backend`, `frontend`, `desktop`, and `extension`;
+they remain visible in the Workspace Model and Knowledge Graph so consumers do
+not have to guess a project’s role from its runtime.
+
+Official generators may download packages and therefore need network access.
+Each available integration requests the upstream latest stable channel rather
+than pinning an old framework major. npm engine compatibility is enforced
+strictly against the Node.js runtime running Workspai, and required ecosystem
+tools such as Rust/Cargo, Git, PHP, or Composer are checked before generation.
+The upstream generator remains authoritative for its exact supported runtime
+range; Workspai records the `latest-stable` policy in the generated project
+metadata and evidence.
+
+`desktop.electron`, `extension.vscode`, and `php.laravel` do not accept
+`--skip-install`, because their official generators do not expose a reliable,
+documented no-install contract.
+
 # Where the project is created
 
 The project path is always:
@@ -441,6 +492,9 @@ npx workspai create project gofiber.standard gateway \
 
 Unlike `create workspace --here`, this turns the current directory itself into
 a workspace. It then creates the project under the requested output parent.
+This registration is foundation-only: it does not probe Python or Poetry,
+create a virtual environment, or install `rapidkit-core`. The selected kit owns
+its runtime prerequisites and installation flow.
 
 For example, from `/home/me/platform`:
 
@@ -449,7 +503,9 @@ Workspace: /home/me/platform
 Project:   /home/me/platform/gateway
 ```
 
-This uses the full current-folder workspace registration flow.
+This uses the full current-folder Workspace Intelligence registration flow
+(contract, model, graph, agent context, and registry) without coupling the
+workspace to the optional Python engine.
 
 ## Choice 3: Create without workspace management
 

package/docs/doctor-command.md

@@ -34,7 +34,8 @@ Checks:
 - all system checks
 - workspace marker resolution
 - project discovery and per-project health
-- dependency/env readiness by project type (Python/Node/Go)
+- dependency, environment, test, quality, security, deployment, and coverage readiness per project
+- runtime-native evidence without treating missing scanners as a clean result
 
 > Compatibility note: `npx workspai doctor --workspace` still works, but `doctor workspace` is the canonical form.
 
@@ -53,6 +54,8 @@ Checks:
 - dependency/env readiness for the selected project
 - enterprise probes (config contract, migration surface, runtime health surface)
 - score explainability breakdown for audit trails
+- normalized dependency-audit and test-coverage evidence for CI, IDEs, and agents
+- graph-aware root, impact-candidate, proof-path, and verification-target context
 
 > Compatibility note: `npx workspai doctor --project` also works.
 
@@ -84,6 +87,108 @@ npx workspai doctor project --json
 npx workspai doctor workspace --profile enterprise-strict --json
 ```
 
+## One verdict, backed by every probe
+
+Doctor calculates one verdict from the host and every project probe:
+
+- **Passed** means no blocking probe failed.
+- **Needs attention** means the current profile found advisory work.
+- **Blocked** means at least one error-level probe failed.
+
+The score and verdict use the same counts. A failed security, coverage, or
+runtime probe cannot be hidden behind a high percentage or a healthy host. New
+evidence includes the host/project score components and per-project probe
+summary; semantic validation rejects contradictory artifacts before they are
+written. Older v1 evidence remains readable so existing workspaces and IDEs do
+not break during migration.
+
+## Graph-aware diagnosis
+
+When the project belongs to a workspace with a current model and Knowledge
+Graph, Doctor enriches every warning or failure with evidence-backed structural
+context:
+
+- the package, file, service, deployment, or other graph entity nearest to the
+  finding;
+- reachable APIs, services, infrastructure, owners, and other affected
+  candidates;
+- connected test suites or CI pipelines that can verify the repair;
+- the exact proof path and source artifacts supporting each connection;
+- explicit unknowns when the graph cannot prove an effect or verification path.
+
+Runtime-native dependency audits preserve the affected package names,
+versions, advisory identifiers, and available severity/directness metadata.
+Doctor uses those subjects to select the corresponding package or module
+entity in the current project's graph neighborhood. If an audit names a
+dependency that the graph cannot resolve, the diagnosis reports it under
+`unresolvedSubjects`; it does not silently attach the finding to an unrelated
+package.
+
+This data is available under `project.graphDiagnosis` in project and workspace
+Doctor JSON evidence. Doctor rejects stale, invalid, or model-unbound graph
+evidence instead of presenting it as current.
+
+Graph reachability is deliberately described as a **structural impact
+candidate**, not runtime causality. It narrows investigation and gives Studio a
+proof-carrying starting point; final verification still comes from the
+runtime-owned checks.
+
+## Multi-runtime dependency evidence
+
+Doctor selects the audit adapter from the detected runtime and lockfile:
+
+| Ecosystem                            | Runtime-native evidence                                            |
+| ------------------------------------ | ------------------------------------------------------------------ |
+| npm                                  | npm, pnpm, Yarn Classic/Berry, Bun, or Deno audit                  |
+| Python                               | `pip-audit` through the project virtual environment when available |
+| Go                                   | `govulncheck`                                                      |
+| Rust                                 | `cargo audit`                                                      |
+| PHP                                  | `composer audit`                                                   |
+| Ruby                                 | `bundler-audit`                                                    |
+| .NET                                 | vulnerable transitive package report                               |
+| Elixir                               | `mix hex.audit`                                                    |
+| Java, Scala, Kotlin, Clojure, C, C++ | project/organization-owned scanner contract                        |
+
+Every result records the exact executable, arguments, ecosystem, severity
+counts, and limitations. A missing tool, timeout, registry failure,
+unparseable response, or unsupported zero-configuration workflow is explicit
+evidence—not a zero-vulnerability result. Compatible automatic fixes never use
+force; unresolved findings move to a targeted upgrade and verification plan.
+
+## Coverage goals that Doctor can verify
+
+Generate a normalized baseline from the current project:
+
+```bash
+npx workspai project coverage --run --target 80 --strict --json
+```
+
+Workspai detects the runtime-owned runner, reads machine-readable coverage, and
+normalizes lines, branches, functions, statements, low-coverage files, source
+hash, and the requested target. It understands Istanbul/LCOV, coverage.py,
+Go coverprofiles, JaCoCo/Cobertura/Clover, scoverage, SimpleCov, and LLVM
+coverage. Runtime plans cover Node/Bun/Deno, Python, Go, JVM, .NET, Rust, PHP,
+Ruby, Elixir, Clojure, Scala, Kotlin, C, and C++; if a project-owned runner does
+not emit one of those portable formats, the result is explicitly `unavailable`
+with setup guidance rather than an invented percentage.
+
+Doctor consumes the resulting
+`.workspai/reports/project-test-coverage-last-run.json`. If it is missing,
+below target, unavailable, or failed, the probe tells Studio what evidence to
+generate or which low-coverage source paths need source-aware tests. The repair
+contract explicitly forbids lowering the target, excluding difficult files,
+skipping tests, or removing assertions to manufacture a pass.
+
+When the project belongs to a workspace, Workspai also writes:
+
+```text
+<workspace>/.workspai/reports/project-test-coverage-last-run.json
+<workspace>/.workspai/reports/projects/<slug>--<hash>/project-test-coverage-last-run.json
+```
+
+The same namespaced layout is used for project Doctor evidence, preventing
+same-name projects from overwriting each other.
+
 ## Enterprise Fix Pipeline
 
 Doctor supports policy profiles so the same evidence can be interpreted correctly in local,
@@ -283,15 +388,17 @@ change is safe enough for Doctor to apply with approval and post-fix verificatio
 
 Runtime-native probes add a second layer on top of the generic surface checks:
 
-| Runtime family | Native signals sampled by Doctor                                      |
-| -------------- | --------------------------------------------------------------------- |
-| Node/Bun/Deno  | test runners, ESLint/Prettier/Biome markers, audit script/tooling     |
-| Python         | pytest/tox/nox, Ruff/Black/Mypy, pip-audit/Safety/Bandit markers      |
-| Go             | `*_test.go`, golangci-lint/Makefile quality, govulncheck/gosec hints  |
-| Java           | Maven/Gradle tests, Checkstyle/Spotless/PMD, OWASP dependency checks  |
-| .NET           | test projects, `.editorconfig`, NuGet audit and vulnerable checks     |
-| Rust           | test/Cargo markers, rustfmt/clippy, cargo-audit hints                 |
-| PHP/Ruby/etc.  | PHPUnit/Pint/PHPStan, RSpec/RuboCop/Bundler-audit and ecosystem hints |
+| Runtime family    | Native signals sampled by Doctor                                                 |
+| ----------------- | -------------------------------------------------------------------------------- |
+| Node/Bun/Deno     | Jest/Vitest/native tests, ESLint/Prettier/Biome, package-manager audit           |
+| Python            | pytest/tox/nox, Ruff/Black/Mypy, pip-audit/Safety/Bandit                         |
+| Go                | `*_test.go`, golangci-lint, govulncheck/gosec                                    |
+| Java/Kotlin/Scala | Maven/Gradle/sbt tests, Checkstyle/Spotless/Detekt/Scalafmt, declared JVM audit  |
+| .NET              | test projects, `.editorconfig`, NuGet audit                                      |
+| Rust              | Cargo tests, rustfmt/clippy, cargo-audit                                         |
+| PHP/Ruby          | PHPUnit/Pest/PHPStan and RSpec/Minitest/RuboCop/Bundler-audit                    |
+| Elixir/Clojure    | ExUnit/Credo/Hex and clojure.test/Kaocha/clj-kondo                               |
+| C/C++             | CTest/native test markers, clang tooling, declared SBOM or vulnerability scanner |
 
 ## CI Example
 
@@ -460,7 +567,7 @@ Legacy evidence without `schemaVersion` is still accepted. Unknown versions are
 
 ```bash
 npx workspai bootstrap [--profile <profile>]
-npx workspai setup <python|node|go|java|dotnet> [--warm-deps]
+npx workspai setup <python|node|go|java|dotnet|rust|php> [--warm-deps]
 npx workspai workspace list
 npx workspai cache <status|clear|prune|repair>
 npx workspai mirror <status|sync|verify|rotate>

package/docs/from-code-to-shared-understanding.md

@@ -32,7 +32,10 @@ flowchart TB
 1. **Connect your software.** Create something new, adopt an existing project
    without moving it, or import a repository.
 2. **Understand the workspace.** Workspai builds one model of the projects and
-   how they relate.
+   how they relate. That Workspace Model is canonical. Workspai then derives a
+   proof-backed Knowledge Graph from the model-owned project inventory so tools
+   can query files, APIs, packages, infrastructure, tests, ownership, and
+   decisions without creating a second source of truth.
 3. **Understand change and verify it.** Workspai shows affected areas and checks
    the evidence needed for a safe decision.
 4. **Share the result.** Developers, CI, IDEs, AI agents, and MCP clients consume

package/docs/graph-benchmark-methodology.md

@@ -27,8 +27,8 @@ The result conforms to
 It records:
 
 - the query and result limit;
-- the graph schema, entity/relation/proof counts, source artifact, and source
-  model SHA-256;
+- the graph schema, entity/relation/proof counts, source artifact, and stable
+  structural model SHA-256;
 - the number and size of readable, deduplicated proof-source artifacts;
 - the bounded retrieval size and match count;
 - unreadable artifacts rather than silently excluding them;

package/docs/workspace-intelligence-evaluation.md

@@ -94,6 +94,7 @@ Event bodies conform to
 ```bash
 npx workspai workspace eval status --json
 npx workspai workspace eval report --json
+npx workspai workspace eval report --output ./evidence/my-evaluation.json --json
 ```
 
 Finalization writes:
@@ -102,6 +103,10 @@ Finalization writes:
 .workspai/reports/workspace-intelligence-evaluation-last-run.json
 ```
 
+`--output` keeps that governed last-run artifact and also copies the finalized
+report to the requested workspace-relative or absolute path. JSON output reports
+the path that was actually requested, so automation does not need to infer it.
+
 Both live and final reports conform to
 [`workspace-intelligence-evaluation.v1.json`](../contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json).