workspai 0.52.3 → 0.54.0

package/docs/README.md

@@ -77,6 +77,7 @@ or use `import` to copy or clone one into the workspace.
 | Create a workspace or project                     | [Creating workspaces and projects](./creating-workspaces-and-projects.md)   | A registered project with canonical `.workspai` metadata              |
 | Bring an existing repository under governance     | [Workspace operations](./workspace-operations.md#import-and-adoption)       | Source stays in place with `adopt`, or is copied/cloned with `import` |
 | Run the complete intelligence loop                | [Unified runner](./workspace-intelligence-runner.md)                        | One ordered run report with durable stage evidence                    |
+| Repair a blocker through an approved transaction  | [Workspace Repair Engine](./workspace-repair-engine.md)                     | Checkpointed execution, validation, canonical verify, and safe rollback |
 | Set a release, security, or coverage outcome       | [Verified engineering goals](./workspace-intelligence-runner.md#verified-engineering-goals) | A durable success contract with a current evidence-backed verdict     |
 | Ask an architecture or dependency question        | [Workspace Knowledge Graph](./workspace-knowledge-graph.md)                 | A bounded answer with proof references rather than the whole graph    |
 | Measure agent token, cost, and outcome efficiency | [Workspace Intelligence Evaluation](./workspace-intelligence-evaluation.md) | A live, provenance-aware report suitable for CLI, IDE, and CI         |
@@ -100,6 +101,7 @@ with [AI Quickstart](./AI_QUICKSTART.md) only when that is your goal.
 | [workspace-operations.md](./workspace-operations.md)                                           | Import, adopt, snapshots, archives, contracts, infra                                                               |
 | [workspace-run.md](./workspace-run.md)                                                         | Polyglot fleet orchestration (`workspace run`)                                                                     |
 | [workspace-intelligence-runner.md](./workspace-intelligence-runner.md)                         | Canonical unified runner, execution envelope, report schema, exit codes, failure propagation, and CI consumption   |
+| [workspace-repair-engine.md](./workspace-repair-engine.md)                                     | CLI-owned plan, approval, checkpoint, execution, verification, decision, and rollback state machine                |
 | [workspace-knowledge-graph.md](./workspace-knowledge-graph.md)                                 | Two-minute graph quickstart, proof model, AI/MCP consumption, performance, and honest token-efficiency measurement |
 | [graph-benchmark-methodology.md](./graph-benchmark-methodology.md)                             | Reproducible payload-reduction benchmark, formulas, claim boundaries, and publication rules                        |
 | [workspace-intelligence-evaluation.md](./workspace-intelligence-evaluation.md)                 | Provider usage, cost provenance, verified outcomes, comparison, and extension consumption                          |

package/docs/commands-reference.md

@@ -62,11 +62,12 @@ npx workspai workspace goal plan <release-readiness|dependency-security|test-cov
 npx workspai workspace goal status <goal-id> [--json]
 npx workspai workspace goal verify <goal-id> [--no-run] [--reuse-intelligence] [--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 context --for-agent [generic|codex|claude|cursor|orca] [--workspace <path>] [--scope project:<name>] [--json] [--write] [--agent-sync|--no-agent-sync] [--target <targets>] [--preset minimal|enterprise] [--project-grounding managed|local|off] [--include-evidence] [--scan-depth <count>] [--strict]
 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 repair <capabilities|plan|propose|approve|decide|execute|resume|status|list|rollback|cancel> [--workspace <path>] [--card <id>] [--action-id <id>] [--project <name>] [--proposal <file>] [--transaction <id>] [--approved-by <actor>] [--decision <choice>] [--max-risk safe|guarded|invasive] [--allow-breaking] [--allow-force] [--no-auto-rollback] [--json]
 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]
+npx workspai workspace diff --from <snapshot-or-model|git[:ref]> [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
 npx workspai workspace impact --from <workspace-diff-report> [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
 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>]
@@ -95,7 +96,7 @@ npx workspai project restore <archive> [--name <project-name>] [--force] [--dry-
 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 workspace run <init|test|build|start|custom-stage> [--workspace <path>] [--scope project:<name>] [--affected] [--blast-radius] [--since <ref>] [--parallel] [--max-workers <n>] [--continue-on-error] [--reuse-passed] [--strict] [--no-gates] [--json]
 npx workspai infra plan [--workspace <path>] [--json] [--dry-run] [--verbose]
 npx workspai infra up [--workspace <path>] [--no-plan] [--build]
 npx workspai infra down [--workspace <path>] [--volumes]
@@ -162,8 +163,10 @@ artifacts, proof additions/removals/content changes, bounded one-hop impact,
 and a risk summary. Observation timestamps and freshness alone do not create
 false change noise. Query indexes are cached
 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.
+built. `dot` and `mermaid` intentionally remain project-topology renderers.
+Without `--output` they emit raw text for direct piping. With `--output` they
+write a durable file; adding `--json` returns a structured operation receipt
+with the format, node and edge counts, and resolved output path.
 
 Every integrated `workspace graph` Knowledge Graph is derived from the
 canonical Workspace Model. Its contract fixes the source artifact to
@@ -182,9 +185,8 @@ assert equivalent answer quality or model-specific billing savings.
 
 `workspace graph jsonld|graphml|gexf` exports the current derived,
 evidence-backed Knowledge Graph for semantic, graph-analysis, and interactive
-2D/3D consumers.
-Use `--output <file>` for a durable export; Mermaid and DOT remain the compact
-documentation-oriented renderings.
+2D/3D consumers. All five export modes accept `--output <file>`; Mermaid and
+DOT remain compact documentation-oriented project-topology renderings.
 
 `workspace eval` records provider/tokenizer/estimate provenance, tool activity,
 cost, latency, and verified task outcome. `eval record` accepts a

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -25,12 +25,12 @@ exclude the canonical marker.
 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 |
+| 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
@@ -52,19 +52,21 @@ and model/graph freshness for the selected project.
 
 ## 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`                  |
-| `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`                        |
+| 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`                           |
+| `workspace repair *`                 | `.workspai/reports/workspace-repair-last-run.json`          | `workspai.workspace-repair-transaction.v1`  | `contracts/workspace-intelligence/workspace-repair-transaction.v1.json` |
+| `workspace repair capabilities`      | CLI capability output                                       | `workspai.workspace-repair-capabilities.v1` | `contracts/workspace-repair-capabilities.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`).
 
@@ -146,10 +148,13 @@ graph whose binding does not match the current model.
 projections from that bound graph. These files are portable exports, not competing
 canonical or `last-run` artifacts: JSON-LD preserves semantic identifiers,
 GraphML targets general graph tooling, and GEXF targets exploration and
-visualization tools. Mermaid and DOT remain bounded text projections for docs
-and diagrams.
+visualization tools. `workspace graph dot|mermaid --output <path>` writes the
+bounded project-topology projections used by docs and diagrams. For DOT and
+Mermaid, `--output --json` returns a `cli-operation-result-v1` receipt containing
+the resolved output path; omitting `--output` keeps raw graph text on stdout.
 
-**CLI semantics:** `workspace diff --from` expects a **model or snapshot** baseline. `workspace impact --from` expects a **diff report**.
+**CLI semantics:** `workspace diff --from` expects a **model, snapshot, or explicit
+Git (`git[:ref]`)** baseline. `workspace impact --from` expects a **diff report**.
 Persisted artifacts retain their artifact schema. JSON command projections that add operation metadata
 such as `outputPath`, `status`, or structured errors use
 `contracts/cli-operation-result.v1.json`; the canonical artifact is nested under `artifact`.

package/docs/contracts/README.md

@@ -61,6 +61,9 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `doctor-workspace-evidence.v1.json` / `doctor-project-evidence.v1.json` — doctor evidence
 - `doctor-remediation-plan.v2.json` — canonical persisted Doctor fix/plan Studio handoff contract (`v1` path is a deprecated compatibility alias)
 - `artifact-remediation-plan.v1.json` — cross-artifact Studio handoff for Bootstrap, Analyze, Readiness, Pipeline, Workspace Run, Workspace Verify, and Doctor plan bridging
+- `workspace-intelligence/workspace-repair-proposal.v1.json` — bounded, hash-pinned source changes and optional runtime-native validation proposed by an IDE model; proposals never execute themselves
+- `workspace-intelligence/workspace-repair-transaction.v1.json` — durable CLI-owned repair state from immutable plan and approval through checkpoint, execution, canonical verification, rollback, or an explicit decision
+- `workspace-repair-capabilities.v1.json` — canonical multi-runtime adapter inventory, conditional support boundaries, preflight policy, and fail-closed repair invariants
 - `analyze-last-run.v1.json` — analyze evidence
 - `pipeline-last-run.v1.json` — governance pipeline orchestration
 - `project-entry-capability.v1.json` — open-ended adopt/import contract for readable projects

package/docs/contracts/RUNTIME_ACCEPTANCE_MATRIX.md

@@ -1,6 +1,6 @@
 # Workspai Runtime Acceptance Matrix
 
-Last updated: 2026-06-05
+Last updated: 2026-08-06
 
 This document defines the executable acceptance gate for Workspai workspace
 and project orchestration. It complements
@@ -14,8 +14,9 @@ workspace.
 npm run test:runtime-matrix
 ```
 
-For a stricter prepared-machine run where Go, Java, .NET, Python, and Node
-toolchains are expected to be installed:
+For a stricter prepared-machine run where the supported Go, Java, .NET,
+Python/RapidKit Core, Node, Rust, and PHP/Composer toolchains are healthy and
+dependency registries are reachable (or already cached):
 
 ```bash
 npm run test:runtime-matrix:full
@@ -32,7 +33,7 @@ node scripts/runtime-acceptance-matrix.mjs --report ./runtime-acceptance-report.
 | Mode     | Purpose                                                                 | External runtime requirement |
 | -------- | ----------------------------------------------------------------------- | ---------------------------- |
 | default  | Scaffold, import, contract, doctor, archive, and actionable diagnostics | no                           |
-| `--full` | Everything in default plus lifecycle commands must pass                 | yes                          |
+| `--full` | Supported lifecycle commands pass; unsupported commands reject cleanly  | yes                          |
 
 Default mode is intentionally network-safe. It creates a minimal workspace,
 uses `--skip-install` for scaffolded projects, and accepts missing-runtime
@@ -48,12 +49,12 @@ The matrix verifies:
   `info`, `frameworks`, `modules`, and `license`. The normal
   `workspai --version` path remains wrapper-owned.
 - `create workspace` with a Python-free minimal profile.
-- `create project` for npm-backed Go Fiber, Go Gin, Spring Boot, and ASP.NET
-  Core Clean Web API kits.
+- `create project` for npm-backed Go Fiber, Go Gin, Spring Boot, ASP.NET Core
+  Clean Web API, and Rust Axum kits.
 - `create project` for core-backed FastAPI and NestJS kits through the current
   bridge/fallback path.
-- `import` for observed runtime projects without first-class kits, including
-  Laravel/PHP, Rails/Ruby, Axum/Rust, and generic unknown backends.
+- `import` for existing projects across supported and observed runtime lanes,
+  including Laravel/PHP, Rails/Ruby, Axum/Rust, and generic unknown backends.
 - `workspace sync`, `workspace policy show/set`.
 - Snapshot safety flows: create/list/inspect/restore dry-run.
 - Project safety flows: archive list, archive dry-run, and delete dry-run.
@@ -62,13 +63,20 @@ The matrix verifies:
 - `project commands --json` capability reporting for every generated/imported
   project.
 - Project lifecycle `init`, `help`, `test`, `build`, `lint`, and `format` in
-  default and full modes, with missing runtime/tooling reported as actionable
-  setup diagnostics in default mode.
+  default and full modes. The project capability map is authoritative:
+  supported commands run, unsupported commands must reject cleanly, and
+  missing runtime/tooling must produce actionable setup diagnostics in default
+  mode.
 - `workspace run init/test/build`, including default-mode actionable setup
   failures and full-mode hard pass requirements.
 - Rejection of unsupported fleet stages such as `workspace run dev`.
 - Portable archive export, inspect, strict verify, doctor, and hydrate preview.
 
+The contract-driven official-generator smoke matrix complements this runtime
+matrix for network-backed official scaffolds such as Laravel and the frontend,
+desktop, and extension generator families. Runtime acceptance proves workspace
+orchestration; official-generator smoke proves the upstream scaffold itself.
+
 ## Report Contract
 
 Each run writes a JSON report with:
@@ -93,6 +101,7 @@ For npm releases:
 1. Run `npm run test:runtime-matrix` locally before publishing a release
    candidate.
 2. Run `npm run test:runtime-matrix:full` on at least one prepared release
-   machine with Go, Java, .NET, Python, and Node installed.
+   machine with all extended toolchains used by the matrix installed, a healthy
+   RapidKit Core environment, and dependency registry access or warm caches.
 3. Any newly added first-class or extended runtime must add at least one matrix
    scenario before release.

package/docs/doctor-command.md

@@ -155,6 +155,12 @@ unparseable response, or unsupported zero-configuration workflow is explicit
 evidence—not a zero-vulnerability result. Compatible automatic fixes never use
 force.
 
+When a declared dependency tree has not been installed, Doctor emits a typed
+`dependency-materialization` capability instead of only a human shell hint. The capability
+records the runtime-native executable, project scope, observable installed-tree state, and
+required validation stages. An unchanged manifest or lockfile is valid in this case: successful
+installation plus declared test/build checks and canonical verification are the completion proof.
+
 When a scanner has no direct automatic fix—or advertises a downgrade—Doctor
 does not conclude that the project has no compatible repair. It emits guarded
 `resolutionCandidates` for the affected direct or transitive dependency. Each
@@ -442,7 +448,7 @@ jobs:
         with:
           node-version: '20.19.0'
       - run: npm ci
-      - run: npx workspai doctor
+      - run: npx workspai doctor workspace --ci --json
 ```
 
 ## Exit Codes
@@ -556,15 +562,21 @@ These fields are designed for release gates and extension timeline cards that mu
 
 - `npx workspai doctor workspace --strict` exits `1` when health score reports errors **or** warnings.
 - `npx workspai doctor workspace --ci` exits `1` on errors and `2` on warnings only (errors take precedence).
-- Without `--strict` or `--ci`, doctor reports findings but exits `0` (backward compatible).
+- Without `--strict` or `--ci`, the local profile exits `1` for errors and `0`
+  for passed or warning-only results. Warnings remain advisory; errors never
+  become a successful local result.
 
 ## Workspace fix behavior
 
-- Reuses cached project scans when valid; refreshes `.workspai/reports/doctor-last-run.json`.
+- Reuses cached project scans only when their inputs and Doctor scoring/safety
+  policy still match; stale policy signatures force a rescan. Cached payloads
+  are re-sanitized before they can become current evidence.
 - `--fix` runs interactive remediation; `--plan` prints remediation plan only; `--apply` applies non-interactively.
 - `--plan` cannot be combined with `--fix` or `--apply`.
 - JSON fix/apply output includes the same `doctor-remediation-plan-v2` contract used by Studio.
-- Advisory warnings do not automatically become shell fix commands.
+- Advisory warnings do not automatically become shell fix commands. URLs stay
+  in issue guidance and recommendations; Doctor never exposes a documentation
+  URL as an executable `fixCommand` or repair action.
 - Go `go mod tidy` fixes are skipped when the Go toolchain is unavailable.
 
 ## Workspace JSON fields (AI/automation)

package/docs/workspace-intelligence-runner.md

@@ -7,7 +7,8 @@ Use one command when you want the latest answer to these questions:
 - Is the workspace healthy and ready?
 - What should developers, CI, IDEs, and AI tools read?
 
-Run it from a Workspai workspace root:
+Run it from a Workspai workspace root or any project with a validated workspace
+binding:
 
 ```bash
 npx workspai workspace intelligence run --for-agent generic --strict --json

package/docs/workspace-knowledge-graph.md

@@ -107,6 +107,7 @@ because it appears in more files. No embedding service or model call is involved
 | How are two things connected?                        | `workspace graph path <from> <to> --json`               |
 | What changed between graph revisions?                | `workspace graph overlay --from <graph.json> --json`    |
 | What is the full portable graph?                     | `workspace graph emit --json`                           |
+| How do I render the project topology?                | `workspace graph dot\|mermaid [--output <file>]`       |
 | How do I export to semantic or graph-analysis tools? | `workspace graph jsonld\|graphml\|gexf --output <file>` |
 | How much retrieval payload did one query avoid?      | `workspace graph benchmark <query> --limit <n> --json`  |
 | How should an MCP-compatible agent retrieve context? | `workspace mcp serve` → `searchWorkspaceGraph`          |
@@ -330,12 +331,16 @@ deterministic projections of that same graph revision:
 ```bash
 npx workspai workspace graph mermaid
 npx workspai workspace graph dot
+npx workspai workspace graph mermaid --output workspace-graph.mmd --json
+npx workspai workspace graph dot --output workspace-graph.dot --json
 npx workspai workspace graph jsonld --output workspace-graph.jsonld
 npx workspai workspace graph graphml --output workspace-graph.graphml
 npx workspai workspace graph gexf --output workspace-graph.gexf
 ```
 
-- Mermaid and DOT are suited to documentation and architecture diagrams.
+- Mermaid and DOT are suited to documentation and architecture diagrams. They
+  print raw text when `--output` is omitted. With `--output --json`, the file is
+  written and stdout is a structured operation receipt rather than graph text.
 - JSON-LD carries semantic identities, relations, and proof references.
 - GraphML and GEXF work with graph-analysis and interactive visualization tools.
 - The canonical JSON, JSON-LD, GraphML, and GEXF outputs can drive 2D or 3D

package/docs/workspace-operations.md

@@ -388,7 +388,9 @@ before consuming its report from CI, IDE, or agent integrations.
 presence check. Required project evidence must match the affected project in
 `workspace-run-last.json`, and evidence generated before the current impact
 report is treated as stale and blocking. Re-run the recommended commands from
-`workspace impact --json` before using `workspace verify --strict` in CI.
+`workspace impact --from .workspai/reports/workspace-model-diff-last-run.json --json` before using
+`workspace verify --strict` in CI. Both `diff` and `impact` require an explicit trusted input; the
+CLI never guesses which historical baseline or diff should authorize a release decision.
 
 For doctor CI exit codes and JSON evidence fields, see [doctor-command.md](./doctor-command.md).
 

package/docs/workspace-repair-engine.md

@@ -0,0 +1,122 @@
+# Workspace Repair Engine
+
+The Workspace Repair Engine is the CLI-owned execution boundary for blocker repair. IDEs,
+agents, and CI may request work and render progress, but they do not invent commands or decide
+that a repair is complete.
+
+```text
+canonical evidence
+      ↓
+plan → preconditions → approval → checkpoint → execute
+     → reconcile → audit → test → build → canonical verify
+     → closed | rolled-back | decision-required
+```
+
+## Command flow
+
+```bash
+# Inspect the exact adapter and fail-closed policy contract first.
+npx workspai workspace repair capabilities --json
+
+# 1. Build an immutable plan from current governed evidence.
+npx workspai workspace repair plan --card doctor --project api --json
+
+# Or compile hash-pinned model output into the same CLI-owned transaction.
+npx workspai workspace repair propose \
+  --proposal .workspai/repair/inbox/proposal.json \
+  --json
+
+# 2. Bind approval to the exact plan hash returned above.
+npx workspai workspace repair approve \
+  --transaction <transaction-id> \
+  --approved-by local-user \
+  --json
+
+# 3. Execute or resume the durable transaction.
+npx workspai workspace repair execute --transaction <transaction-id> --json
+npx workspai workspace repair resume --transaction <transaction-id> --json
+
+# Inspect or resolve a terminal decision.
+npx workspai workspace repair status --transaction <transaction-id> --json
+npx workspai workspace repair decide --transaction <transaction-id> --decision <available-option> --json
+npx workspai workspace repair rollback --transaction <transaction-id> --json
+npx workspai workspace repair cancel --transaction <transaction-id> --json
+npx workspai workspace repair list --json
+```
+
+`capabilities` is global discovery and works outside a Workspai workspace. When it is run from
+an attached project or workspace, the same response also includes local adapter inspection. All
+other repair actions require an unambiguous canonical workspace root.
+
+`plan` never mutates source files. `approve` never executes work. `execute` refuses an expired,
+tampered, unapproved, or precondition-stale plan.
+
+`propose` is the dynamic repair boundary for IDE models. A model may provide bounded complete-file
+writes/deletes and optional structured audit/test/build commands. The CLI rejects stale source
+hashes, duplicate targets, workspace evidence edits, Git internals, installed dependency trees,
+secret-bearing files, path/link escapes, and ungoverned commands. Dependency manifest proposals
+still receive CLI-inferred reconcile, audit, test, and build stages before strict verification.
+
+Doctor also publishes a distinct `dependency-materialization` transaction when manifests exist
+but the installed runtime tree is missing. Its install or restore invocation is the repair stage
+itself; it does not require a manifest or lockfile diff and is never run twice. Declared tests and
+builds, followed by canonical verification, prove closure. Dependency-security transactions still
+require manifest/lock reconciliation and a clean focused audit.
+
+## Safety and ownership
+
+- The immutable plan hash covers target, policy, preconditions, structured invocations, risk,
+  and the existence/hash baseline of every checkpointed path.
+- Only typed Doctor operations and allowlisted structured process invocations are executable.
+  Shell evaluation is disabled, secret-like environment variables are removed, and autonomous
+  package fetching through `npx` is rejected.
+- Force and breaking changes require explicit policy approval. A different policy means a new
+  plan and a new approval.
+- Files are bounded to the workspace, regular files only, at most 5 MiB each and 25 MiB per
+  transaction. A source change between planning and execution expires approval.
+- A workspace-level owner lock prevents concurrent repair writers and is not stolen from a live
+  process merely because a long transaction exceeded a wall-clock threshold. Resume skips
+  durable passed stages.
+- Required stage failure triggers bounded rollback by default. Before restoring the first byte,
+  rollback verifies every target and backup hash, rejects path/link conflicts, restores files
+  atomically with their recorded modes, and reconciles installed dependencies with the restored
+  manifests and lockfiles. It reports `decision-required` if any part cannot be proven complete.
+- Strict canonical Workspace Intelligence always runs before closure. The receipt separates
+  `verification.targetStatus` from `verification.workspaceStatus`: a proven selected action may
+  close while unrelated governed findings keep the workspace blocked. Those findings remain the
+  next repair target and never trigger rollback of a valid bounded repair.
+- Required executables are resolved before approval and again immediately before execution. A
+  missing or changed toolchain expires approval instead of starting a partial transaction.
+
+## Runtime adapters
+
+Dependency transactions are package-manager aware. The canonical inventory is published at
+`contracts/workspace-repair-capabilities.v1.json` and exposed through `workspace repair
+capabilities`. It distinguishes full support from conditional support instead of treating “the
+command exists” as proof that the whole repair is executable.
+
+Node, Python, Go, Rust, Composer, Bundler, Elixir, Deno, .NET, Maven, Gradle, Clojure, and sbt
+surfaces are detected independently. A genuinely multi-runtime project receives collision-free
+stages for every applicable adapter. Doctor dependency actions remain bound to the ecosystem
+declared by their evidence so an npm finding cannot accidentally trigger an unrelated Python
+transaction. If a manifest, required executable, isolated environment, project-declared
+validation, or audit surface is unavailable, the engine returns `decision-required`; it never
+hides the gap behind a model fallback.
+
+## Consumer contract
+
+The latest transaction is written to:
+
+```text
+.workspai/reports/workspace-repair-last-run.json
+```
+
+The schema is
+`contracts/workspace-intelligence/workspace-repair-transaction.v1.json`. Full transaction state
+is durable under `.workspai/repair/transactions/<transaction-id>/`. Consumers should discover
+the `workspace repair` action from `runtime-command-surface.v1.json`, render its stages and
+events, and send explicit user decisions back to the CLI. They must not reproduce the executor.
+
+IDE-generated input follows
+`contracts/workspace-intelligence/workspace-repair-proposal.v1.json`. The proposal is evidence,
+not authority: only the approved transaction created by the CLI may mutate the workspace.

package/docs/workspace-run.md

@@ -16,21 +16,18 @@ npx workspai workspace run build --json --max-workers 8
 `.rapidkit/workspace-dependency-graph.json` fallback. It expands direct
 `dependsOn` and publish/consume event relationships.
 
-## Supported runtimes
+## Runtime support
 
-| Runtime | Frameworks | Status |
-| --- | --- | --- |
-| Node | NestJS, Express, Next.js, Nuxt | Built-in |
-| Go | Fiber, Gin, Echo, Chi | Built-in |
-| Java | Spring Boot, Quarkus, Gradle | Built-in |
-| Python | FastAPI, Django, Flask, Poetry | Built-in |
-| PHP | Laravel, Symfony, Slim | Observed |
-| Rust | Actix, Axum, Rocket, Tokio | Observed |
-| .NET | ASP.NET Core, Entity Framework | Built-in |
-| Elixir | Phoenix, Umbrella | Observed |
-| Ruby | Rails, Sinatra, RSpec | Observed |
-
-Public scaffold/import/lifecycle contract: [contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md).
+`workspace run` does not infer support from a hard-coded framework list. It
+reads the effective project capability map produced by the runtime adapters and
+project metadata. First-class and extended Node.js, Python, Go, Java, .NET,
+PHP, and Rust projects can expose governed lifecycle stages; observed runtimes
+run only commands explicitly declared by their project context.
+
+The authoritative scaffold/import/lifecycle tiers are in
+[contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md).
+Inspect one project's effective surface with
+`npx workspai project commands --json` before orchestration.
 
 ## Enterprise configuration
 
@@ -83,6 +80,12 @@ cat test-results.json | jq '.projects[] | {path, status, errorCategory}'
 ```
 
 `errorCategory` values: `setup`, `test-failure`, `runtime`, `dependency`, `timeout`.
+For failures, `reason` and `errorMessage` select the most specific terminal
+failure signal instead of an earlier readiness warning.
+`failureDiagnostic.outputExcerpt` is a bounded head-and-tail excerpt, preserving
+both command context and the final root cause without copying the full log.
+Consumers should render these fields rather than reconstructing a diagnosis
+from arbitrary stdout lines.
 
 ## Command semantics
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workspai",
-  "version": "0.52.3",
+  "version": "0.54.0",
   "type": "module",
   "description": "Open-source workspace intelligence CLI for software systems: create, adopt, govern, verify, and align polyglot workspaces for humans, CI, IDEs, and AI agents.",
   "keywords": [
@@ -110,6 +110,7 @@
     "test:scenarios:full": "node scripts/run-scenario-matrix-local.mjs --full",
     "test:scenarios:docker": "bash scripts/scenario-matrix.sh",
     "test:runtime-matrix": "node scripts/runtime-acceptance-matrix.mjs",
+    "test:runtime-contract": "node scripts/runtime-acceptance-matrix.mjs --contract-only",
     "test:runtime-matrix:full": "node scripts/runtime-acceptance-matrix.mjs --full",
     "lint": "eslint src --ext .ts",
     "lint:fix": "eslint src --ext .ts --fix",
@@ -139,7 +140,7 @@
     "analyze": "corepack npm run build && node scripts/analyze-dist.mjs",
     "size-check": "corepack npm run build && size-limit",
     "bench": "npx tsx scripts/benchmarks.ts",
-    "quality": "corepack npm run check:package-manager && corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm test && corepack npm run size-check && corepack npm run check:workspace-intelligence-runtime && corepack npm run check:workspace-intelligence-adversarial && corepack npm run security && corepack npm run validate:docs && corepack npm run check:generator-smoke-coverage && corepack npm run smoke:official-generators && corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:parity-snapshot && corepack npm run check:agent-customization-drift",
+    "quality": "corepack npm run check:package-manager && corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm test && corepack npm run size-check && corepack npm run check:workspace-intelligence-runtime && corepack npm run check:workspace-intelligence-adversarial && corepack npm run test:runtime-contract && corepack npm run security && corepack npm run validate:docs && corepack npm run check:generator-smoke-coverage && corepack npm run smoke:official-generators && corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:parity-snapshot && corepack npm run check:agent-customization-drift",
     "act-matrix": "act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-22.04 -P macos-latest=ghcr.io/catthehacker/ubuntu:act-22.04 -P windows-latest=ghcr.io/catthehacker/ubuntu:act-22.04 --pull=false -j build-test-matrix",
     "release:dry": "bash scripts/release.sh --no-publish --yes --allow-dirty",
     "release:patch": "bash scripts/release.sh patch",

package/scripts/enterprise-package-smoke.mjs

@@ -201,6 +201,10 @@ const REQUIRED_PACKAGE_FILES = [
   'contracts/project-entry-capability.v1.json',
   'contracts/workspace-intelligence-architecture.v1.json',
   'contracts/workspace-intelligence-chain.v1.json',
+  'contracts/studio-card-repair-capabilities.v1.json',
+  'contracts/workspace-repair-capabilities.v1.json',
+  'contracts/workspace-intelligence/workspace-repair-proposal.v1.json',
+  'contracts/workspace-intelligence/workspace-repair-transaction.v1.json',
   'contracts/extension-cli-compatibility.v1.json',
   'data/modules-embeddings.json',
   'templates/kits/fastapi-standard/README.md.j2',
@@ -380,12 +384,7 @@ function smokeCreateNpmBackedKits() {
       kit: 'rust.axum',
       name: 'enterprise-rust-axum',
       extraArgs: [],
-      expectedFiles: [
-        'Cargo.toml',
-        'src/main.rs',
-        '.workspai/project.json',
-        'rapidkit',
-      ],
+      expectedFiles: ['Cargo.toml', 'src/main.rs', '.workspai/project.json', 'rapidkit'],
     },
   ];
 
@@ -504,6 +503,10 @@ for (const relativePath of [
   'contracts/project-entry-capability.v1.json',
   'contracts/workspace-intelligence-architecture.v1.json',
   'contracts/workspace-intelligence-chain.v1.json',
+  'contracts/studio-card-repair-capabilities.v1.json',
+  'contracts/workspace-repair-capabilities.v1.json',
+  'contracts/workspace-intelligence/workspace-repair-proposal.v1.json',
+  'contracts/workspace-intelligence/workspace-repair-transaction.v1.json',
   'contracts/extension-cli-compatibility.v1.json',
   'data/modules-embeddings.json',
 ]) {

package/dist/analyze-J7VNZMDH.js

@@ -1 +0,0 @@
-export{b as printAnalyzeReport,a as runAnalyze}from'./chunk-HPWLSLMC.js';