workspai 0.48.0 → 0.50.0

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

@@ -1,16 +1,20 @@
 # Creating Workspaces and Projects
 
-This guide explains, in plain language, what Workspai does when you create a
-workspace or a project. It covers interactive commands, automation, project
-locations, workspace linking, supported kits, and the most important flags.
+Use this guide when you want to start a new software system or add a new
+application to an existing one. Workspai creates the files, records where the
+project belongs, and makes it visible to the same checks and tools as the rest
+of the workspace.
+
+The sections below explain project locations, supported starters, interactive
+commands, automation, and the most useful options.
 
 For a compact list of command syntax, see
 [commands-reference.md](./commands-reference.md).
 
 ## The two things you can create
 
-A **workspace** is the governed boundary that holds project registrations,
-policies, contracts, and Workspace Intelligence reports.
+A **workspace** is the shared home for related projects, rules, and saved
+Workspai reports.
 
 A **project** is an application or service, such as a FastAPI API, Go service,
 Spring Boot service, .NET API, or frontend application.
@@ -200,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:
@@ -245,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
@@ -271,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:
@@ -291,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.
@@ -316,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:
@@ -437,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`:
 
@@ -445,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
 
@@ -588,13 +648,13 @@ native, official, and existing-project lanes.
 
 # Failure and cleanup behavior
 
-| Situation                                                | Result                                 |
-| -------------------------------------------------------- | -------------------------------------- |
-| Invalid name                                             | Stops before normal scaffold writes    |
-| Target directory already exists                          | Stops without merging or overwriting   |
-| Project scaffold fails                                   | Workspace linking does not run         |
-| Git initialization fails                                 | Usually warns and keeps the scaffold   |
-| Go or Maven dependency warm-up fails                     | Warns and keeps the scaffold           |
+| Situation                                                | Result                                                                      |
+| -------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Invalid name                                             | Stops before normal scaffold writes                                         |
+| Target directory already exists                          | Stops without merging or overwriting                                        |
+| Project scaffold fails                                   | Workspace linking does not run                                              |
+| Git initialization fails                                 | Usually warns and keeps the scaffold                                        |
+| Go or Maven dependency warm-up fails                     | Warns and keeps the scaffold                                                |
 | Workspace registration/finalization fails after scaffold | Lifecycle rollback restores metadata and removes a newly owned project tree |
 
 Create finalization uses a durable lifecycle transaction. On failure it restores

package/docs/doctor-command.md

@@ -1,6 +1,8 @@
 # Workspai Doctor Command
 
-`doctor` checks health for the npm wrapper environment in system, workspace, or project scope.
+Use `doctor` to find setup and dependency problems before they interrupt
+development or block a release. It can check the computer, an entire workspace,
+or one project, and reports what is wrong and which fixes are available.
 
 **Related:** [workspace-operations.md](./workspace-operations.md) · [commands-reference.md](./commands-reference.md) · [Documentation index](./README.md)
 
@@ -20,7 +22,7 @@ Checks host prerequisites:
 - RapidKit Core availability
 - Go (optional)
 
-### 2) Workspace Check (Canonical)
+### 2) Workspace Check
 
 ```bash
 cd my-workspace
@@ -32,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.
 
@@ -51,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.
 
@@ -82,16 +87,118 @@ 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,
 CI, release, and enterprise gates:
 
-| Profile             | Use when                         | Warning behavior                         |
-| ------------------- | -------------------------------- | ---------------------------------------- |
-| `local`             | Developer diagnostics             | Report warnings, do not block            |
-| `ci`                | CI feedback loop                  | Exit `2` on warnings, `1` on errors      |
-| `release`           | Release readiness gate            | Exit `1` on warnings or errors           |
+| Profile             | Use when                          | Warning behavior                                          |
+| ------------------- | --------------------------------- | --------------------------------------------------------- |
+| `local`             | Developer diagnostics             | Report warnings, do not block                             |
+| `ci`                | CI feedback loop                  | Exit `2` on warnings, `1` on errors                       |
+| `release`           | Release readiness gate            | Exit `1` on warnings or errors                            |
 | `enterprise-strict` | Enterprise/studio repair workflow | Exit `1`; every warning needs evidence or repair guidance |
 
 `--strict` maps to the `release` profile and `--ci` maps to the `ci` profile for backward
@@ -101,11 +208,11 @@ card is advisory locally but blocking for release.
 Doctor also attaches a **freshness contract** to evidence so tools do not treat live state as
 durable structure:
 
-| Freshness category | Meaning                                      | Default TTL |
-| ------------------ | -------------------------------------------- | ----------- |
-| `structure`        | Durable project/workspace shape and markers  | 7 days      |
+| Freshness category | Meaning                                       | Default TTL |
+| ------------------ | --------------------------------------------- | ----------- |
+| `structure`        | Durable project/workspace shape and markers   | 7 days      |
 | `verification`     | Test, script, lint, quality, and probe checks | 24 hours    |
-| `state`            | Live dependency/security state               | 5 minutes   |
+| `state`            | Live dependency/security state                | 5 minutes   |
 
 Each probe can include `freshness`, and each JSON artifact includes `evidenceFreshness`.
 Workspai and CI should refresh stale or `verifyBeforeUse` evidence before claiming a project is
@@ -113,10 +220,10 @@ ready, repaired, or release-safe.
 
 Doctor probes also include an **issue taxonomy** and **repair intent** for Studio-driven repair:
 
-| Field               | Purpose                                                                 |
-| ------------------- | ----------------------------------------------------------------------- |
-| `issueClass`        | Stable category such as `security`, `test`, `container`, or `dependency` |
-| `operationalImpact` | Product impact such as `ci-risk`, `release-risk`, or `security-risk`    |
+| Field               | Purpose                                                                                                       |
+| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `issueClass`        | Stable category such as `security`, `test`, `container`, or `dependency`                                      |
+| `operationalImpact` | Product impact such as `ci-risk`, `release-risk`, or `security-risk`                                          |
 | `repairIntent.mode` | Studio action mode: `edit-file`, `run-command`, `review-required`, `verify-before-fix`, or `refresh-evidence` |
 
 This lets Workspai distinguish "show guidance" from "apply an approved file edit", "run a command",
@@ -164,15 +271,15 @@ same repair evidence without guessing the workspace root.
 
 The remediation plan is intentionally ordered for Studio execution:
 
-| Phase | Purpose |
-| --- | --- |
-| `dependency-baseline` | Restore package/runtime dependency baselines before other fixes |
-| `local-environment` | Seed local env files without overwriting operator-owned values |
-| `source-hygiene` | Apply safe project-scoped hygiene files such as `.dockerignore` or `.gitignore` rules |
-| `command-contract` | Add missing test, quality, audit, or runtime command contracts |
-| `runtime-governance` | Run RapidKit/workspace initializers that may touch multiple project surfaces |
-| `manual-review` | Surface guidance that requires a human decision |
-| `generic-execution` | Last-resort shell remediation when no typed operation exists |
+| Phase                 | Purpose                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------- |
+| `dependency-baseline` | Restore package/runtime dependency baselines before other fixes                       |
+| `local-environment`   | Seed local env files without overwriting operator-owned values                        |
+| `source-hygiene`      | Apply safe project-scoped hygiene files such as `.dockerignore` or `.gitignore` rules |
+| `command-contract`    | Add missing test, quality, audit, or runtime command contracts                        |
+| `runtime-governance`  | Run RapidKit/workspace initializers that may touch multiple project surfaces          |
+| `manual-review`       | Surface guidance that requires a human decision                                       |
+| `generic-execution`   | Last-resort shell remediation when no typed operation exists                          |
 
 `dependsOn` lets Workspai avoid false loops: for example, a missing test script repair can depend on
 the project dependency baseline step, so Studio can run or ask for approval in the same order Doctor
@@ -281,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
 
@@ -311,11 +420,11 @@ jobs:
 
 ## Exit Codes
 
-| Code | Meaning                        |
-| ---- | ------------------------------ |
-| `0`  | Passed; local-profile warnings remain advisory |
+| Code | Meaning                                                            |
+| ---- | ------------------------------------------------------------------ |
+| `0`  | Passed; local-profile warnings remain advisory                     |
 | `1`  | Errors, or warnings under `release`/`enterprise-strict`/`--strict` |
-| `2`  | Warning-only result under the `ci` profile or `--ci` |
+| `2`  | Warning-only result under the `ci` profile or `--ci`               |
 
 ## Enterprise Probe Extensions
 
@@ -458,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/examples/ci-agent-grounding.yml

@@ -39,7 +39,7 @@ jobs:
         # Exit 1 = hard execution failure; exit 2 = completed but evidence-blocked.
         # Continue here only so the durable run report and blocker evidence can
         # always be uploaded; the final step below still fails either outcome.
-        run: npx workspai workspace intelligence run --for-agent codex --strict --json
+        run: npx workspai workspace intelligence run --for-agent generic --strict --json
         continue-on-error: true
         id: intelligence
 

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
@@ -62,14 +65,14 @@ render Mermaid. When this source changes, regenerate
 Run the complete canonical chain in its versioned order:
 
 ```bash
-npx workspai workspace intelligence run --for-agent codex --json
+npx workspai workspace intelligence run --for-agent generic --json
 ```
 
 For enterprise CI and release enforcement, add `--strict`. A warning or
 needs-attention verdict then produces a blocked report and exit code `2`:
 
 ```bash
-npx workspai workspace intelligence run --for-agent codex --strict --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
 `pipeline` is the broader governance/release orchestrator. It does not replace

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

@@ -1,11 +1,13 @@
 # Measure Workspace Intelligence Usage
 
-Workspai can record model usage, tool activity, cost provenance, and the final
-verified outcome of an agent task. The resulting artifact is designed for CLI,
-IDE, CI, and dashboard consumers.
+Use this feature to answer a practical question: did focused workspace context
+help an AI task use fewer tokens, cost less, or reach a verified result?
 
-It does not store prompt or response bodies. Optional SHA-256 hashes let a
-consumer correlate calls without copying private content into the report.
+Workspai records model usage, tool activity, reported cost, and the final
+verified outcome in one report that the CLI, IDE, CI, and dashboards can read.
+
+It does not store prompt or response text. Optional SHA-256 hashes can connect
+related calls without copying private content into the report.
 
 ## Start a measured task
 
@@ -50,7 +52,7 @@ printf '%s\n' '{
 | `provider-reported` | The provider returned the count                                |
 | `tokenizer-counted` | A named tokenizer counted the exact serialized input or output |
 | `estimated`         | A documented estimate; never presented as provider billing     |
-| `unavailable`       | The provider exposed no usable count                            |
+| `unavailable`       | The provider exposed no usable count                           |
 
 Tool events record progress and repeated work without storing command output:
 
@@ -92,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:
@@ -100,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).
 

package/docs/workspace-intelligence-runner.md

@@ -1,14 +1,25 @@
 # Unified Workspace Intelligence Runner
 
-`workspace intelligence run` is the canonical contract-backed entrypoint for
-refreshing Workspace Intelligence evidence in one deterministic execution. Use
-it from a Workspai workspace root:
+Use one command when you want the latest answer to these questions:
+
+- What projects and relationships exist now?
+- What changed, and what may be affected?
+- Is the workspace healthy and ready?
+- What should developers, CI, IDEs, and AI tools read?
+
+Run it from a Workspai workspace root:
 
 ```bash
-npx workspai workspace intelligence run --for-agent codex --strict --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
-The authoritative result is written atomically to
+`generic` is the vendor-neutral context surface. Replace it with `codex`,
+`claude`, `cursor`, or `orca` for agent-specific context. The `agent-sync`
+stage also publishes shared grounding for GitHub Copilot, VS Code, and
+`AGENTS.md` consumers.
+
+Workspai runs the required steps in a fixed order and saves one final report.
+The technical contract writes that report atomically to
 `.workspai/reports/workspace-intelligence-run-last-run.json` with schema
 `workspace-intelligence-run.v1`. JSON stdout returns the same report payload.
 Consumers should read the persisted report when they need durable evidence and
@@ -154,7 +165,7 @@ publish it without applying the relevant redaction policy.
 The simplest hard gate is:
 
 ```bash
-npx workspai workspace intelligence run --for-agent codex --strict --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
 Both exit `1` and exit `2` fail a normal CI step. If artifacts must be uploaded