workspai 0.55.0 → 0.56.0

package/docs/commands-reference.md

@@ -1,6 +1,12 @@
 # Commands Reference
 
-Complete CLI syntax for the Workspai CLI. For behavior and workflows, see [workspace-operations.md](./workspace-operations.md) and [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md).
+Human-readable CLI syntax for the Workspai CLI. The machine-complete command,
+argument, option, alias, ownership, and integrity inventory is available through
+`workspai commands --json` and
+[`runtime-command-surface.v1.json`](../contracts/runtime-command-surface.v1.json).
+For behavior and workflows, see
+[workspace-operations.md](./workspace-operations.md) and
+[OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md).
 
 ## Workspace lifecycle
 
@@ -44,6 +50,7 @@ profile.
 
 ```bash
 npx workspai workspace sync [--json]
+npx workspai workspace registry [--json]
 npx workspai workspace policy show
 npx workspai workspace policy set <key> <value>
 npx workspai doctor
@@ -70,10 +77,11 @@ npx workspai workspace snapshot [--workspace <path>] [--json] [--include-paths]
 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>]
+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>] [--refresh-graph] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
 npx workspai workspace eval [init <task> [strategy]|record|status|report|compare --from <report>] [--workspace <path>] [--output <file>] [--json]
 npx workspai workspace watch [--workspace <path>] [--json] [--graph-stream] [--once] [--scan-depth <count>]
-npx workspai workspace explain|why <target> [--workspace <path>] [--json] [--write]
+npx workspai workspace explain <target> [--workspace <path>] [--json] [--write]
+npx workspai workspace why <target> [--workspace <path>] [--json] [--write]
 npx workspai workspace trace --from <workspace-diff-report> [--workspace <path>] [--json] [--write]
 printf '%s\n' '{"actionId":"fix-api","summary":"API tests passed","outcome":"ok"}' | npx workspai workspace feedback record [--workspace <path>] --json
 npx workspai workspace mcp serve [--workspace <path>] [--json]
@@ -96,7 +104,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|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 workspace run <init|test|build|start|custom-stage> [--workspace <path>] [--scope project:<name>] [--plan] [--runtime <runtime>] [--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]
@@ -183,6 +191,15 @@ that retrieval payload with the readable proof-indexed corpus using a labelled
 `characters / 4` estimate. It measures payload reduction only; it does not
 assert equivalent answer quality or model-specific billing savings.
 
+Add `--scope project:<name>` to retrieve project-owned facts plus
+workspace-level shared entities proven to be connected to that project. The
+agent projection reports explicit omission budgets for relations, related
+entities, proofs, aliases, attributes, and proof references. Read-oriented
+`search`, `entities`, `evidence`, `path`, and `benchmark` modes reuse the
+persisted graph only when its model binding, proofs, project scopes, and live
+Git/Merkle input fingerprint still match. `--refresh-graph` bypasses that
+compatible snapshot and rebuilds from current sources.
+
 `workspace graph jsonld|graphml|gexf` exports the current derived,
 evidence-backed Knowledge Graph for semantic, graph-analysis, and interactive
 2D/3D consumers. All five export modes accept `--output <file>`; Mermaid and
@@ -230,8 +247,11 @@ cross-runtime additions are allowed with a recommendation such as
 blocked before the project is registered. Rust is an extended runtime with
 Axum/Tauri scaffolding and Cargo lifecycle support. PHP is extended through
 Laravel and Composer lifecycle support. Observed runtimes such as C and C++ are
-still counted in the workspace runtime mix even when Workspai does not own a
-native scaffold for them.
+counted in the workspace runtime mix even when Workspai does not own a native
+scaffold for them. Existing CMake and Meson projects can also expose discovered
+lifecycle units to `workspace run`; inspect them without execution using
+`workspace run <stage> --plan`, and select one runtime family with
+`--runtime <runtime>`.
 
 Core module/template commands are intentionally narrower than runtime detection.
 RapidKit Core modules are guaranteed only for RapidKit Core module-enabled kits:
@@ -287,8 +307,17 @@ governance while Core module mutation remains disabled.
 npx workspai cache <status|clear|prune|repair>
 npx workspai mirror <status|sync|verify|rotate>
 npx workspai infra <plan|up|down|status>
+npx workspai ai <info|recommend|generate-embeddings|update-embeddings>
+npx workspai config <show|ai|set-api-key|remove-api-key>
+npx workspai product <manifest|plan>
+npx workspai shell
 ```
 
+These groups are part of the public CLI surface, but availability of an
+operation can still depend on project runtime, optional provider configuration,
+or product metadata. Use the action's `--help` and `workspai commands --json`
+instead of inferring support from this compact synopsis.
+
 See [workspace-operations.md](./workspace-operations.md#workspace-infrastructure-sidecar) for infra discovery rules.
 
 ## Profiles

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -258,6 +258,11 @@ return bounded Knowledge Graph projections with proof references; `benchmark`
 measures corpus-versus-retrieval payload; `overlay --from` compares a proposed
 or earlier graph with the current graph; `emit` returns the complete
 interchange graph; and `dot|mermaid` render deterministic dependency views.
+Read-oriented modes accept a persisted graph only after model binding, proof
+freshness, canonical project scopes, and the live `hybrid-git-content-v2`
+fingerprint pass. `--refresh-graph` bypasses that snapshot. Search and benchmark
+accept `--scope project:<name>` and the agent projection reports explicit
+omission budgets instead of silently expanding its payload.
 Canonical sources are `src/workspace-graph.ts`,
 `src/workspace-knowledge-graph-query.ts`,
 `src/workspace-knowledge-graph-change-overlay.ts`, and
@@ -409,7 +414,7 @@ canonical file. Legacy files remain readable during the compatibility window.
 2. **Workspace Intelligence chain:** run `workspace intelligence run --for-agent generic --strict --json` to preserve Model → Diff → Impact → Doctor + Contract Verify + Analyze → Readiness → Verify → Context → Agent Sync → Explain. `pipeline` is the broader governance/release orchestrator and `autopilot` is a separate release surface; neither redefines the canonical chain. Use `pipeline-last-run.json` only for the pipeline orchestration summary.
 3. **Do not** use `workspace.json.projects` (removed in schema 1.0).
 4. Prefer `schemaVersion` constants in each artifact; legacy `v1` on readiness is accepted when reading old reports.
-5. **Agent retrieval:** start with `AGENTS.md` and `.workspai/reports/INDEX.json`, then use `workspace graph search <query> --limit <n> --json` or MCP `searchWorkspaceGraph` for question-sized facts. Follow returned proof paths to source evidence. Read the full context, model, or graph only when the bounded result is insufficient.
+5. **Agent retrieval:** start with `AGENTS.md` and `.workspai/reports/INDEX.json`, then use `workspace graph search <query> --limit <n> --json` or MCP `searchWorkspaceGraph` for question-sized facts. Use `--scope project:<name>` when the task has one registered project boundary, inspect `budget.omitted` before assuming the result is complete, and follow returned proof paths to source evidence. Read the full context, model, or graph only when the bounded result is insufficient.
 6. **Agent customization state:** use `.workspai/reports/agent-customization-pack.json` to inspect generated surfaces and drift; regenerate with `workspace agent-sync --write --refresh-context --preset enterprise`.
 
 ## Agent customization files (repo hooks)

package/docs/contracts/README.md

@@ -59,6 +59,11 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `release-readiness.v1.json` — release readiness gate evidence
 - `workspace-run-last.v1.json` — multi-stage workspace run evidence
 - `doctor-workspace-evidence.v1.json` / `doctor-project-evidence.v1.json` — doctor evidence
+- `workspace-intelligence/doctor-diagnosis.v1.json` — runtime-neutral causal findings, proof bindings, confidence, unknowns, contradictions, and repair disposition embedded in Doctor evidence
+- `workspace-intelligence/doctor-capabilities.v1.json` — fail-closed runtime/framework ownership, six-domain support levels, platform boundaries, repair modes, and extraction-safe adapter inventory
+- `workspace-intelligence/doctor-validation.v1.json` — versioned disease-corpus results across every registered adapter, with bounded synthetic precision/recall and explicit limitations
+- `workspace-intelligence/doctor-receipt.v1.json` — compact Doctor verdict, unambiguous counts, freshness, affected projects, blockers, and next-action handoff; full evidence remains canonical
+- `workspace-intelligence/doctor-summary.v1.json` — bounded stdout contract emitted by `doctor --json=summary` for system, workspace, and project consumers
 - `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

package/docs/doctor-command.md

@@ -59,6 +59,49 @@ Checks:
 
 > Compatibility note: `npx workspai doctor --project` also works.
 
+### 4) Capability truth and validation
+
+```bash
+# Complete runtime/domain matrix
+npx workspai doctor capabilities --json
+
+# Ask what Doctor can prove for one runtime or framework
+npx workspai doctor capabilities --runtime node --json
+npx workspai doctor capabilities --framework "Spring Boot" --json
+
+# Exercise every registered adapter against the versioned disease corpus
+npx workspai doctor capabilities --validate --json
+
+# Persist both governed artifacts in a workspace
+npx workspai doctor capabilities --validate --write --workspace . --json
+```
+
+Runtime and framework filters narrow only the command response. With `--write`, Doctor persists the
+complete capability registry, never a filtered subset, so downstream consumers cannot mistake a
+query result for canonical capability truth. Conflicting runtime/framework ownership fails closed
+to the unknown adapter and records the conflict as an explicit limitation.
+
+The capability matrix never turns absence into success. Each adapter declares all six diagnostic
+domains as `native`, `portable`, `observable`, or `unsupported`, plus its limitations, platforms,
+repair modes, runtime aliases, and framework ownership. An unknown runtime resolves to the
+fail-closed fallback adapter: unsupported or unobserved evidence stays unknown and cannot produce a
+healthy security claim.
+
+`--validate` runs the same versioned disease classes through every registered runtime adapter. Its
+precision and recall describe that deterministic synthetic corpus only. Real tool execution,
+runtime-native fixtures, and Linux/macOS/Windows acceptance remain separate gates; the report says
+so explicitly instead of presenting synthetic coverage as production accuracy.
+
+With `--write`, consumers can read:
+
+- `.workspai/reports/doctor-capabilities.json`
+- `.workspai/reports/doctor-validation-last-run.json`
+
+Contracts:
+
+- `contracts/workspace-intelligence/doctor-capabilities.v1.json`
+- `contracts/workspace-intelligence/doctor-validation.v1.json`
+
 ## Typical Usage
 
 ```bash
@@ -74,6 +117,9 @@ npx workspai doctor project
 # Machine-readable output
 npx workspai doctor workspace --json
 
+# Compact agent/CI projection; full evidence is still written
+npx workspai doctor workspace --fresh --json=summary
+
 # Attempt safe fixes (interactive)
 npx workspai doctor workspace --fix
 
@@ -87,6 +133,18 @@ npx workspai doctor project --json
 npx workspai doctor workspace --profile enterprise-strict --json
 ```
 
+`--json` remains the complete backward-compatible payload. `--json=summary` returns a bounded
+projection with the verdict, affected projects, explicit count categories, freshness, and artifact
+locations. It never replaces or weakens the full Doctor evidence. `--fresh` bypasses the project
+scan cache; the default cache also expires after five minutes (configurable with
+`WORKSPAI_DOCTOR_CACHE_MAX_AGE_SECONDS`) so live security state cannot be reused indefinitely.
+
+Every project or workspace run also writes
+`.workspai/reports/doctor-receipt-last-run.json`. The receipt is a small governed handoff for IDEs,
+CI, and agents: it distinguishes blocking causes, advisory findings, unknowns, dependency advisory
+subjects, vulnerability findings, not-applicable checks, and the next safe action. The complete
+probe and diagnosis evidence remains in `doctor-last-run.json` or `doctor-project-last-run.json`.
+
 ## One verdict, backed by every probe
 
 Doctor calculates one verdict from the host and every project probe:
@@ -102,6 +160,72 @@ 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.
 
+## Universal diagnosis core
+
+Doctor normalizes every runtime-specific observation through one internal diagnosis boundary
+before CLI, Studio, CI, or an agent consumes it. This boundary is intentionally kept inside the
+CLI until its contracts stabilize; it does not depend on Commander, terminal rendering, or the
+VS Code extension.
+
+Project and workspace evidence publish the result under `project.diagnosis`:
+
+- a stable causal key and typed finding status for every non-passing observation;
+- confidence and diagnosis state (`confirmed`, `candidate`, or `unknown`) rather than fabricated
+  certainty;
+- proof bindings for the originating probe, affected dependency, structured command, and repair
+  targets;
+- repair disposition (`automatic`, `approval-required`, `manual`, or `unavailable`);
+- causal groups that let Repair close one disease family without mixing unrelated guidance;
+- explicit unknowns and contradictions when providers disagree or evidence is stale;
+- diagnosis completeness and repair-coverage counts that cannot silently score empty/unsupported
+  evidence as healthy.
+
+Completeness is measured across six canonical diagnostic domains—runtime, dependency, security,
+configuration, test, and quality. Every domain is explicitly `clean`, `findings`,
+`not-applicable`, `not-run`, or `stale`. An explicit `not-applicable` observation is retained as
+evidence but does not become a warning or inflate passing counts. A provider that did not run, or
+evidence that is no longer fresh, increases unknowns and prevents a 100% completeness claim.
+Readiness and Workspace Verify consume this canonical diagnosis instead of independently
+recounting legacy issue strings.
+
+The same diagnosis contract is used for Node, Python, Go, JVM, Rust, .NET, PHP, Ruby, Elixir,
+Clojure, Deno, Bun, Scala, Kotlin, C, C++, and unknown/custom projects. Runtime adapters gather
+different evidence; the diagnosis, causality, safety, and verification vocabulary stays the same.
+Composite projects publish every detected family under `project.runtimeFamilies`; Doctor keeps a
+primary runtime for compatibility and explicitly warns when secondary runtimes need their own
+project boundary or custom adapter instead of silently claiming full coverage. Every unevaluated
+secondary runtime is also published as a diagnosis unknown and proportionally lowers diagnosis
+completeness; a primary-only polyglot scan can never report 100%.
+
+Workspace project boundaries come from the canonical workspace contract/registry when available.
+A nested solution, test project, or manifest inside a registered project is treated as evidence for
+that project—not silently promoted into another workspace project. Unregistered monorepos remain
+discoverable, while an explicitly registered nested project remains an independent boundary.
+
+Contract: `contracts/workspace-intelligence/doctor-diagnosis.v1.json`.
+
+The internal ownership boundaries are deliberately narrow:
+
+| Boundary            | Owns                                                                            | Must not own                                    |
+| ------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------- |
+| Runtime sensors     | Observable runtime, manifest, tool, source, and audit facts                     | Verdicts or speculative causality               |
+| Universal diagnosis | Causal reconciliation, confidence, proof binding, unknowns, and contradictions  | File mutation or terminal/UI rendering          |
+| Doctor policy       | Blocking/advisory projection, health score, and profile-specific gate semantics | Re-running sensors or inventing repairs         |
+| Remediation planner | Typed operations bound to `diagnosisFindingId` and `causalKey`                  | Reclassifying the disease                       |
+| Repair engine       | Approval, checkpoint, execution, validation, canonical verify, and rollback     | Silently weakening Doctor policy                |
+| Consumers           | Rendering and user/model interaction                                            | Recomputing or overriding diagnosis and verdict |
+
+This keeps Doctor internal today without turning `doctor.ts` into a public dependency boundary. A
+future package extraction can move the diagnosis contract and engine without changing the evidence
+or remediation protocol consumed by the CLI, Studio, CI, and agents.
+
+The extraction seam is enforced in source and tests. `adapter-contract.ts`,
+`capability-registry.ts`, `diagnosis-engine.ts`, and `validation-corpus.ts` are pure core modules:
+they cannot import Commander, terminal styling, workspace discovery, or extension/UI code.
+`capabilities-command.ts` is the CLI adapter that owns workspace resolution, artifact persistence,
+and human rendering. A future `@workspai/doctor` package can therefore take the pure core without
+moving command UX or creating a second source of truth.
+
 ## Graph-aware diagnosis
 
 When the project belongs to a workspace with a current model and Knowledge
@@ -128,6 +252,12 @@ 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 enrichment is deliberately bounded per finding and restricted to the selected project's
+graph neighborhood. Doctor publishes a small set of affected candidates, verification targets,
+source artifacts, and shortest proof paths; consumers can query the canonical graph for deeper
+exploration. This prevents unrelated projects and repeated graph payloads from consuming an
+agent's context budget.
+
 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
@@ -291,12 +421,12 @@ 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                        |
+| `local-environment`   | Repair declared configuration contracts without inventing local secrets               |
 | `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                          |
+| `generic-execution`   | Review-only legacy guidance when no typed operation or invocation 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
@@ -371,9 +501,11 @@ safe `file-create` operation, and a `.gitignore` missing env-file rules can prod
 `file-append` operation. Workspai can render those operations as reviewable file edits before the
 operator approves the fix.
 
-Local environment seeding is also typed. When `.env.example` exists and `.env` is missing, Doctor
-emits a safe `file-copy` operation instead of an opaque shell copy command. The target is never
-overwritten.
+`.env.example`, a config schema, or environment documentation is the portable configuration
+contract. Doctor does **not** create `.env` implicitly: that file can contain operator-owned secrets
+and its absence is not a health defect when a portable contract exists. A product-specific typed
+operation may still create a non-secret local file when its own contract explicitly requires it and
+the user approves the change.
 
 For Node projects without a security audit script, Doctor can emit a guarded
 `package-json-script` operation for `scripts.audit="npm audit --audit-level=moderate"`, giving CI,
@@ -419,6 +551,16 @@ These probes are intentionally evidence-first. Missing optional surfaces are sur
 or manual repair capabilities, while deterministic repairs are promoted into `--fix` only when the
 change is safe enough for Doctor to apply with approval and post-fix verification.
 
+Workspace scans are bounded and cache-safe. Doctor fingerprints manifests plus relevant source,
+test, and module trees, includes content hashes for small files, writes cache artifacts atomically,
+and limits project concurrency (four workers by default; configurable with
+`RAPIDKIT_DOCTOR_SCAN_CONCURRENCY`). Dependency trees and build outputs are represented by bounded
+materialization sensors rather than recursively traversed. Repair/plan/apply always bypass scan
+cache, and Java warm-up uses workspace-local Maven/Gradle cache paths so its postcondition is both
+portable and observable. Dependency-audit cache keys hash the complete governed manifest/lockfile
+inputs and use a bounded in-memory cache, so same-size lockfile changes cannot reuse stale security
+evidence.
+
 Runtime-native probes add a second layer on top of the generic surface checks:
 
 | Runtime family    | Native signals sampled by Doctor                                                 |
@@ -581,7 +723,7 @@ These fields are designed for release gates and extension timeline cards that mu
 
 ## Workspace JSON fields (AI/automation)
 
-`npx workspai doctor workspace --json` includes per-project metadata: `framework`, `frameworkKey`, `importStack`, `runtimeFamily`, `projectKind`, `supportTier`, `frameworkConfidence`, `probes`, and `repairCapabilities`.
+`npx workspai doctor workspace --json` includes per-project metadata: `framework`, `frameworkKey`, `importStack`, `runtimeFamily`, `runtimeFamilies`, `projectKind`, `supportTier`, `frameworkConfidence`, `probes`, and `repairCapabilities`. Passing probes never retain an executable repair capability; only non-passing evidence can enter remediation planning.
 
 ## Project scope behavior
 
@@ -600,7 +742,16 @@ These fields are designed for release gates and extension timeline cards that mu
 - Project evidence: `doctor-project-evidence-v1`
 - Workspace scan cache: `doctor-workspace-cache-v2`
 
-Legacy evidence without `schemaVersion` is still accepted. Unknown versions are treated as invalid evidence. `readiness` and `workspace share` share the same validation path.
+Recognizable legacy evidence without `schemaVersion` remains readable only when it exposes an
+actual workspace/project Doctor shape. Arbitrary JSON objects, unknown versions, contradictory
+score accounting, malformed typed repairs, and semantically invalid canonical diagnosis are
+treated as missing or invalid evidence. Readiness and Workspace Verify enforce the same fail-closed
+semantic boundary.
+
+Typed file repairs resolve existing ancestors through the filesystem before mutation. A lexical
+path under the project is rejected if a symbolic link escapes the governed project/workspace
+boundary. The checkpointed `package-json-script` target is the exact file that is edited; JSON
+pointer prototype segments and hidden multiline env/append values are rejected before execution.
 
 ## Related Workspace Commands
 

package/docs/graph-benchmark-methodology.md

@@ -20,6 +20,7 @@ From a Workspai workspace:
 ```bash
 npx workspai workspace model --write --json
 npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json
+npx workspai workspace graph benchmark "authentication endpoint" --scope project:api --limit 12 --json
 ```
 
 The result conforms to
@@ -34,6 +35,18 @@ It records:
 - unreadable artifacts rather than silently excluding them;
 - the estimate formula, reduction ratio, percentage, and claim boundary.
 
+For linked projects, portable proof artifacts such as
+`external/api/src/server.ts` are resolved through the canonical workspace
+contract's `externalPath`. Resolution remains containment-checked beneath that
+registered project root. A missing or unsafe mapping stays in
+`unreadableArtifacts`; it is never silently dropped from the denominator
+explanation.
+
+The benchmark uses the same bounded agent projection as Graph search. A project
+scope therefore includes facts owned by that project and connected
+workspace-level shared entities, while the response's omission budget makes
+payload caps explicit.
+
 ## Baseline and formula
 
 The current methodology is `indexed-corpus-vs-bounded-retrieval.v1`.

package/docs/workspace-intelligence-runner.md

@@ -185,6 +185,10 @@ Automation must distinguish:
 Do not parse terminal prose. Read `status`, `exitCode`, `preflight`, `stages`,
 and their registered artifacts from the JSON report.
 
+When Verify publishes `resolutionHints`, an evidence-backed step includes its
+exact `sourceCommand` and `sourceArtifact`. Consumers should run that producer
+command instead of substituting a generic Analyze refresh, then re-run Verify.
+
 ## Verified engineering goals
 
 The intelligence runner answers what is true now. A verified goal adds the

package/docs/workspace-knowledge-graph.md

@@ -71,6 +71,7 @@ graph:
 
 ```bash
 npx workspai workspace graph search "billing database" --limit 12 --json
+npx workspai workspace graph search "billing database" --scope project:billing --limit 12 --json
 ```
 
 A simplified response looks like this:
@@ -79,17 +80,21 @@ A simplified response looks like this:
 {
   "schemaVersion": "workspace-knowledge-search.v1",
   "query": "billing database",
+  "projectId": "billing",
   "totalMatches": 23,
   "truncated": true,
   "entities": [{ "kind": "database", "label": "billing-db", "proofIds": ["proof:..."] }],
   "relations": [{ "kind": "reads-from", "from": "service:billing", "to": "database:billing-db" }],
-  "proofs": [{ "provider": "compose", "artifact": "infra/compose.yml", "trust": "authoritative" }]
+  "proofs": [{ "provider": "compose", "artifact": "infra/compose.yml", "trust": "authoritative" }],
+  "budget": { "mode": "agent", "limits": { "proofs": 16 }, "omitted": { "proofs": 4 } }
 }
 ```
 
 The response is intentionally bounded. `totalMatches` tells the consumer more
 results exist, `truncated` prevents silent omission, and every returned claim can
-be traced through `proofIds`.
+be traced through `proofIds`. Use `--scope project:<name>` to keep a query within
+one registered project while retaining workspace-level shared entities that are
+proven to be connected to it.
 
 Search remains deterministic, local, and offline. Natural-language filler words
 are removed before ranking, and the remaining terms are weighted by how rare
@@ -97,6 +102,37 @@ they are in the current graph. Exact labels and identities still win. This keeps
 a common word such as `check` from outranking a rarer term such as `user` merely
 because it appears in more files. No embedding service or model call is involved.
 
+### Fast reads without stale answers
+
+The read-oriented `search`, `entities`, `evidence`, `path`, and `benchmark`
+commands first try the persisted Model and Knowledge Graph. A snapshot is a hit
+only when all of the following remain true:
+
+- both artifacts are structurally readable;
+- the graph's stable model SHA-256 matches the persisted canonical model;
+- no proof is marked stale;
+- the graph fingerprint contains exactly one workspace scope and every
+  canonical project scope with compatible scan limits;
+- a fresh bounded scan produces the same aggregate live-input hash.
+
+Git-backed scopes use `git-worktree-v2`, covering tracked tree state plus
+modified, deleted, renamed, untracked, and relevant ignored files. If Git cannot
+prove the scanned inventory safely—for example because a traversed initialized
+submodule or hidden index flag is present—Workspai falls back to
+`content-merkle-v1`, which hashes each bounded file by portable path and content.
+The graph records the combined strategy as `hybrid-git-content-v2`.
+
+A miss rebuilds from live sources. Use `--refresh-graph` when the caller requires
+an explicit rebuild even if the persisted snapshot is compatible:
+
+```bash
+npx workspai workspace graph search "protobuf ownership" --refresh-graph --json
+```
+
+The fingerprint proves compatibility of the exact bounded provider inventory;
+if a scope reports `truncated: true`, it must not be interpreted as proof about
+files beyond that declared limit.
+
 ## Pick the command by question
 
 | You want to know…                                    | Use                                                     |
@@ -259,6 +295,8 @@ The current CLI uses bounded providers for:
 - workspace/project foundations and service contracts;
 - language-neutral source structure and package manifests;
 - OpenAPI, GraphQL, Protobuf, and AsyncAPI interfaces;
+- C/C++ source, CMake/Meson lifecycle units, Bazel/CMake packages, and
+  cross-language protocol bindings;
 - Docker/Compose, Kubernetes, Terraform, and CI workflows;
 - README/docs, ADRs, tests, and CODEOWNERS.
 
@@ -273,6 +311,13 @@ imports are labelled `unresolved-local` and produce a diagnostic. This prevents
 an unknown local path from being silently presented as a third-party
 dependency.
 
+Protocol Buffers services and messages retain definition-level identity
+variants. Two projects may use the same fully qualified name without being
+silently collapsed; proven cross-project or cross-language equivalence is
+represented as a relation instead. In a C++-primary repository, ambiguous
+`.h` headers inherit the authoritative project language so C/C++ inventories do
+not split solely because the extension is shared.
+
 ### Binding quality, not just graph size
 
 Entity and relation counts do not tell you whether a graph can answer useful
@@ -382,8 +427,10 @@ The recommended read order is:
 Graph construction inventories each project once per build and caps the number
 of scanned files. Providers reuse the same in-memory inventory and content
 hashes. Query indexes are cached per immutable graph object; replacing the graph
-is the invalidation boundary. `workspace model --cache` and `--incremental`
-avoid unnecessary model/project work when inputs are unchanged.
+is the in-memory invalidation boundary. Across CLI processes, compatible
+persisted read queries validate the live Git/Merkle fingerprint before reuse.
+`workspace model --cache` and `--incremental` avoid unnecessary model/project
+work when inputs are unchanged.
 
 Use full graph export for interchange or offline analysis. Use bounded search
 for interactive agents. The latter keeps response size proportional to the
@@ -426,6 +473,8 @@ a general performance claim.
 
 - The CLI graph is intentionally file-backed; a graph database is not required.
 - Text search is deterministic lexical retrieval, not embedding similarity.
+- The live-input fingerprint enables whole-graph snapshot reuse; it is not yet
+  a per-file incremental graph rebuild or a hosted semantic-vector index.
 - Compiler/LSP-grade symbol resolution belongs in deeper language providers.
 - Missing project edges mean “relationship not proven,” not “projects are
   independent.” Author service contracts or provide API/package/runtime

package/docs/workspace-run.md

@@ -6,6 +6,8 @@
 
 ```bash
 npx workspai workspace run test --parallel
+npx workspai workspace run build --plan --json
+npx workspai workspace run test --runtime cpp --scope project:native-core --json
 npx workspai workspace run test --affected --since HEAD~1
 npx workspai workspace run test --affected --blast-radius
 npx workspai workspace run build --json --max-workers 8
@@ -20,9 +22,18 @@ npx workspai workspace run build --json --max-workers 8
 
 `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.
+project metadata. First-class and extended Node.js, Python, Go, Java, .NET, PHP,
+and Rust projects can expose governed lifecycle stages. Existing polyglot
+repositories also publish bounded runtime units discovered from npm, Python,
+Go, Cargo, Maven, Gradle, NuGet, CMake, and Meson manifests. CMake and Meson
+provide explicit native init, test, and build plans; Workspai does not treat
+discovery as permission to execute them.
+
+Use `--plan` to return the selected runtime units and commands without running
+them. Use `--runtime <runtime>` to limit a polyglot project to one runtime
+family. Vendored trees, build outputs, fixtures, and nested test fixture package
+manifests are excluded from lifecycle discovery so orchestration does not turn
+sample inputs into install targets.
 
 The authoritative scaffold/import/lifecycle tiers are in
 [contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workspai",
-  "version": "0.55.0",
+  "version": "0.56.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": [
@@ -83,6 +83,7 @@
     "test:e2e:user-first-install": "bash scripts/e2e-user-first-install.sh",
     "test:prebuild": "tsup",
     "test": "corepack npm run test:prebuild && vitest run",
+    "test:no-build": "vitest run",
     "test:drift": "node scripts/run-drift-guard.mjs",
     "benchmark:intelligence": "vitest run src/__tests__/workspace-intelligence-benchmark.test.ts",
     "sync:shared-contracts": "node scripts/sync-shared-contracts.mjs",
@@ -93,6 +94,7 @@
     "check:generated-contracts": "node scripts/generate-shared-contracts.mjs --check",
     "check:agent-customization-drift": "node scripts/check-agent-customization-drift.mjs",
     "validate:contracts": "corepack npm run check:shared-contracts && vitest run src/__tests__/contracts/",
+    "validate:contracts:tests": "vitest run src/__tests__/contracts/",
     "test:parity-contract": "corepack npm run check:shared-contracts && vitest run src/__tests__/contracts/import-stack-parity.snapshot.test.ts",
     "test:watch": "vitest",
     "test:coverage": "corepack npm run test:prebuild && vitest run --coverage --reporter=default --reporter=json --outputFile.json=test-results/vitest.json",
@@ -103,6 +105,7 @@
     "check:workspace-intelligence-runtime": "node scripts/check-workspace-intelligence-runtime-conformance.mjs",
     "check:workspace-intelligence-adversarial": "node scripts/check-workspace-intelligence-adversarial.mjs",
     "check:windows-registry": "node scripts/check-windows-registry-invariants.mjs",
+    "check:doctor-capabilities": "node --import tsx scripts/check-doctor-capabilities.ts",
     "smoke:enterprise-package": "node scripts/enterprise-package-smoke.mjs",
     "prepack": "node scripts/prepack-enterprise.mjs",
     "test:e2e": "vitest run src/__tests__/e2e.test.ts",
@@ -132,6 +135,7 @@
     "smoke:frontend-generators": "tsup && node scripts/smoke-frontend-generators.mjs",
     "smoke:frontend-generators:network": "tsup && node scripts/smoke-frontend-generators.mjs --execute",
     "smoke:official-generators": "tsup && node scripts/smoke-official-generators.mjs",
+    "smoke:official-generators:no-build": "node scripts/smoke-official-generators.mjs",
     "smoke:official-generators:network": "tsup && node scripts/smoke-official-generators.mjs --execute",
     "check:generator-smoke-coverage": "node scripts/check-generator-smoke-coverage.mjs",
     "sync:contracts": "node scripts/sync-contracts.mjs",
@@ -139,8 +143,10 @@
     "bundle-size": "corepack npm run build && node scripts/report-dist-size.mjs",
     "analyze": "corepack npm run build && node scripts/analyze-dist.mjs",
     "size-check": "corepack npm run build && size-limit",
+    "size-check:no-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 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",
+    "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 check:doctor-capabilities && 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",
+    "quality:push": "corepack npm run check:package-manager && corepack npm run check:windows-registry && corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm run build && corepack npm run test:no-build && corepack npm run size-check:no-build && corepack npm run check:workspace-intelligence-runtime && corepack npm run check:workspace-intelligence-adversarial && corepack npm run check:doctor-capabilities && corepack npm run test:runtime-contract && corepack npm run validate:docs && corepack npm run check:generator-smoke-coverage && corepack npm run smoke:official-generators:no-build && corepack npm run contracts:check:local && corepack npm run validate:contracts:tests",
     "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",
@@ -150,7 +156,8 @@
     "ci": "corepack npm run quality",
     "contracts:sync": "corepack npm run sync:contracts && corepack npm run sync:shared-contracts",
     "contracts:check": "corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:parity-snapshot && corepack npm run check:generated-contracts && corepack npm run check:agent-customization-drift",
-    "contracts:validate": "corepack npm run contracts:check && corepack npm run validate:contracts && corepack npm run build && corepack npm run check:workspace-intelligence-runtime && corepack npm run check:workspace-intelligence-adversarial",
+    "contracts:check:local": "corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:generated-contracts && corepack npm run check:agent-customization-drift",
+    "contracts:validate": "corepack npm run contracts:check && corepack npm run validate:contracts && corepack npm run build && corepack npm run check:workspace-intelligence-runtime && corepack npm run check:workspace-intelligence-adversarial && corepack npm run check:doctor-capabilities",
     "docs:validate": "corepack npm run validate:docs",
     "smoke": "corepack npm run smoke:enterprise-package && corepack npm run smoke:readme && corepack npm run check:generator-smoke-coverage && corepack npm run smoke:official-generators",
     "fix": "corepack npm run lint:fix && corepack npm run format && corepack npm run sync:contracts && corepack npm run sync:shared-contracts && corepack npm run sync-kits"

package/dist/analyze-AAZEJ4FC.js

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

package/dist/autopilot-release-EZXOGAVE.js

@@ -1 +0,0 @@
-export{b as AUTOPILOT_RELEASE_ALIAS_FILENAME,a as AUTOPILOT_RELEASE_LAST_RUN_FILENAME,c as runAutopilotRelease}from'./chunk-KJYLCZRI.js';