workspai 0.55.1 → 0.57.0

package/docs/README_CONTENT_CONTRACT.md

@@ -18,21 +18,23 @@ versioned contracts and focused guides.
 
 The root README keeps this order:
 
-1. product category, slogan, and three outcomes;
-2. one copyable path for existing software and one guided path for new software;
-3. a short outcome-oriented view of what Workspai provides;
-4. the canonical Model → derived Graph boundary and intelligence chain;
-5. consumer surfaces and goal-based documentation links;
-6. package, contributor, community, and license routes.
+1. a problem-first product promise, slogan, and copyable first run;
+2. product category and three durable outcomes;
+3. one copyable path for existing software and one guided path for new software;
+4. a short outcome-oriented view of what Workspai provides;
+5. the canonical Model → derived Graph boundary and intelligence chain;
+6. consumer surfaces and goal-based documentation links;
+7. package, contributor, community, and license routes.
 
 The CLI README keeps this order:
 
-1. product category, slogan, and value;
-2. a two-minute existing-project path and the guided create path;
-3. the small set of durable outputs a user should recognize;
-4. the canonical Model → derived Graph boundary and intelligence chain;
-5. everyday workflows grouped by goal;
-6. outputs, requirements, documentation, troubleshooting, and contribution.
+1. a problem-first product promise, slogan, and copyable first run;
+2. product category and durable value;
+3. a two-minute existing-project path and the guided create path;
+4. the small set of durable outputs a user should recognize;
+5. the canonical Model → derived Graph boundary and intelligence chain;
+6. everyday workflows grouped by goal;
+7. outputs, requirements, documentation, troubleshooting, and contribution.
 
 ## What does not belong in a main README
 
@@ -110,6 +112,17 @@ task-success claim.
 - Link to deeper guidance instead of duplicating it.
 - Do not add a README section for every feature or release.
 
+## Media policy
+
+- Keep videos outside the npm package tarball; use a stable website, CDN, or
+  GitHub Release asset.
+- npm READMEs may use a lightweight poster or a bounded, silent GIF instead of
+  relying on an embedded video player. Link to the hosted MP4 when full
+  resolution or audio matters.
+- Keep the poster or first GIF frame meaningful without playback and give it
+  useful alternative text.
+- Do not commit generated social-video masters under `packages/cli/docs/`.
+
 ## Validation
 
 Run from `packages/cli`:

package/docs/ci-workflows.md

@@ -46,7 +46,7 @@ Validate or preview the current CLI announcement locally:
 npm --workspace workspai run check:release-announcement
 npm --workspace workspai run release:announcement -- \
   --product workspai-cli \
-  --tag v0.55.0 \
+  --tag v0.57.0 \
   --markdown-output /tmp/workspai-discord-announcement.md
 ```
 
@@ -93,6 +93,14 @@ the exact preflight, 11-stage, artifact, and exit contract.
 | Docs drift guard              | `npm run check:docs-drift`                                                |
 | README command smoke          | `npm run smoke:readme`                                                    |
 | Agent customization drift     | `npm run check:agent-customization-drift -- --workspace <workspace-root>` |
+| Cross-platform lockfile       | `npm run check:cross-platform-lockfile`                                   |
+
+The root `postinstall` lifecycle runs the lockfile check before build or test
+jobs can start. This prevents a lockfile regenerated from a platform-pruned
+`node_modules` tree from reaching native Vitest/Rolldown startup on another
+operating system. Restore an accidentally deleted lockfile from Git; perform a
+deliberate full regeneration only with both the lockfile and `node_modules`
+absent.
 
 ## Recommended pre-release checks
 

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
@@ -56,7 +63,7 @@ npx workspai workspace share [--output <file>] [--include-paths] [--no-doctor]
 npx workspai workspace contract init [--force] [--json]
 npx workspai workspace contract inspect [--json]
 npx workspai workspace contract verify [--strict] [--json]
-npx workspai workspace contract graph [--json]
+npx workspai workspace contract graph [--output <graph.json>] [--json]
 npx workspai workspace intelligence run [--workspace <path>] [--for-agent <agent>] [--strict] [--json]
 npx workspai workspace goal plan <release-readiness|dependency-security|test-coverage> [--scope project:<name>] [--target <0-100>] [--allow-breaking] [--allow-force] [--no-build] [--no-tests] [--json]
 npx workspai workspace goal status <goal-id> [--json]
@@ -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

@@ -24,15 +24,17 @@ Do not copy a schema from `main` and assume it matches an older installed CLI.
 
 Canonical JSON lives in **`../../contracts/`** (CLI package root, published in the tarball).
 
-| Script                                    | Purpose                                                                                                               |
-| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `npm run generate:contracts`              | Regenerate runtime surface, create planner, agent customization pack, import-stack parity, module-layout, infra-stack |
-| `npm run check:generated-contracts`       | Verify committed JSON matches generators                                                                              |
-| `npm run sync:parity-snapshot`            | Copy canonical → vscode `contracts/` mirror                                                                           |
-| `npm run check:parity-snapshot`           | Verify mirrors match canonical                                                                                        |
-| `npm run validate:contracts`              | Shared-contract checks and focused contract tests                                                                     |
-| `npm run contracts:validate`              | Comprehensive generated/shared contract, parity, runtime-conformance, and adversarial gate                            |
-| `npm run check:agent-customization-drift` | Verify generated agent customization files are committed in a consumer workspace                                      |
+| Script                                      | Purpose                                                                                                               |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `npm run generate:contracts`                | Regenerate runtime surface, create planner, agent customization pack, import-stack parity, module-layout, infra-stack |
+| `npm run check:generated-contracts`         | Verify committed JSON matches generators                                                                              |
+| `npm run sync:parity-snapshot`              | Copy canonical → vscode `contracts/` mirror                                                                           |
+| `npm run check:parity-snapshot`             | Verify mirrors match canonical                                                                                        |
+| `npm run validate:contracts`                | Shared-contract checks and focused contract tests                                                                     |
+| `npm run contracts:validate`                | Comprehensive generated/shared contract, parity, runtime-conformance, and adversarial gate                            |
+| `npm run check:agent-customization-drift`   | Verify generated agent customization files are committed in a consumer workspace                                      |
+| `npm run test:real-world -- ...`            | Qualify explicitly selected linked repositories in isolated or cumulative workspaces                                  |
+| `npm run test:real-world:enterprise -- ...` | Exercise the read-mostly, export, archive, agent dry-run, snapshot, and destructive dry-run command surface           |
 
 Workflow: change code → `npm run generate:contracts` → `npm run sync:parity-snapshot` → commit npm + vscode `contracts/`.
 
@@ -59,6 +61,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
@@ -67,6 +74,7 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `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
+- `adopt-effects.v1.json` — dry-run disclosure of project metadata, conditional repository-control reconciliation, and workspace operations before adoption
 - `create-planner-capabilities.v1.json` — native, official, and existing capability lanes
 - `agent-customization-pack.v1.json` — generated instructions, prompts, skills, agents, optional hooks, MCP-ready design metadata, target matrix, and drift state for AI agent surfaces
 - `workspace-list.v1.json`, `workspace-sync.v1.json`, and `compatibility-matrix.v1.json` — workspace discovery, synchronization, and platform compatibility
@@ -114,10 +122,10 @@ CLI commands: see [commands-reference.md](../commands-reference.md) and the
 
 `rapidkit-cli-contracts.json` describes:
 
-- `VersionResponse` — `rapidkit version --json`
+- `VersionResponse` — `workspai version --json`
 - `CommandsResponse` — `workspai commands --json`
-- `ProjectDetectResponse` — `rapidkit project detect --json`
-- `ModulesListResponseV1` — `rapidkit modules list --json-schema 1`
+- `ProjectDetectResponse` — `workspai project detect --json`
+- `ModulesListResponseV1` — `workspai modules list --json-schema 1`
 
 ## Versioning
 
@@ -130,3 +138,4 @@ CLI commands: see [commands-reference.md](../commands-reference.md) and the
 - [Documentation index](../README.md)
 - [commands-reference.md](../commands-reference.md)
 - [workspace-operations.md](../workspace-operations.md)
+- [real-world-qualification.md](../real-world-qualification.md)

package/docs/doctor-command.md

@@ -39,6 +39,10 @@ Checks:
 
 > Compatibility note: `npx workspai doctor --workspace` still works, but `doctor workspace` is the canonical form.
 
+Both workspace forms use the canonical project-to-workspace resolver. After a
+project is adopted, imported, or relinked, they can be launched from that
+project directory and resolve its validated machine-local workspace binding.
+
 ### 3) Project Check (Canonical)
 
 ```bash
@@ -59,6 +63,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
@@ -68,12 +115,21 @@ npx workspai doctor
 # Full check inside a workspace
 npx workspai doctor workspace
 
+# Expand every probe and lifecycle capability (default output is summary-first)
+npx workspai doctor workspace --verbose
+
 # Focus only on current project
 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
+
+# Review the governed plan before mutation
+npx workspai doctor workspace --plan
+
 # Attempt safe fixes (interactive)
 npx workspai doctor workspace --fix
 
@@ -87,7 +143,19 @@ npx workspai doctor project --json
 npx workspai doctor workspace --profile enterprise-strict --json
 ```
 
-## One verdict, backed by every probe
+`--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, multi-axis accounting
 
 Doctor calculates one verdict from the host and every project probe:
 
@@ -95,12 +163,92 @@ Doctor calculates one verdict from the host and every project probe:
 - **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.
+The verdict is authoritative. Human output presents blocking, advisory,
+unknown, contradictory, and not-applicable counts separately; it never calls a
+single percentage “health.” The additive `healthScore.presentation` contract
+labels its percentage as a diagnostic pass rate for accounting only. A failed
+security, coverage, or runtime probe therefore cannot be hidden behind a high
+percentage or a healthy host. Existing score fields remain readable for older
+IDEs, while updated consumers prefer the multi-axis projection.
+
+Doctor also publishes `projectArchetype` independently from `projectKind`.
+`projectKind` describes the technical surface (backend, frontend, extension,
+and so on); the archetype describes the product role (service, application,
+library, SDK, platform, plugin, or monorepo). Service-only checks such as a
+runtime health endpoint, database migrations, or an executable boot entrypoint
+are retained as explicit `not-applicable` evidence for non-deployable
+archetypes instead of becoming false warnings.
+
+The default terminal view is summary-first and uses portable boundaries such
+as `$WORKSPACE`, `$PROJECT`, and `external/<project>`. `--verbose` expands all
+probes and lifecycle capabilities. JSON continues to retain canonical absolute
+paths because local machine consumers need them for governed operations.
+
+## 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. A detected cross-language platform is evaluated through primary
+and portable evidence, and asks for explicit custom adapters only for runtime-specific checks the
+portable contract cannot represent. Every unevaluated secondary runtime remains a diagnosis unknown
+and proportionally lowers 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
 
@@ -128,6 +276,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 +445,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 +525,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 +575,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 +747,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 +766,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/from-code-to-shared-understanding.md

@@ -5,26 +5,28 @@ you to replace your frameworks or move existing source code.
 
 ```mermaid
 flowchart TB
-    Code["Your projects and repositories"]
+    Sources["Projects · APIs · packages<br/>infrastructure · docs · CI"]
 
-    Routes["Create a project<br/>Adopt it in place<br/>or Import a repository"]
+    Connect["Create · Adopt in place · Import"]
 
-    Workspace["Workspai builds one model of<br/>projects, dependencies, rules, and commands"]
+    Model["Canonical Workspace Model<br/>identity · inventory · boundaries"]
 
-    Change["What changed?<br/>What is affected?<br/>Is the evidence ready?"]
+    Graph["Derived Knowledge Graph<br/>relationships · facts · canonical proof"]
 
-    Outputs["Context, impact, verification,<br/>explanations, and release evidence"]
+    Decide["Diff · Impact · Evidence gates<br/>Readiness · Verify"]
 
-    Code --> Routes
-    Routes --> Workspace
-    Workspace --> Change
-    Change --> Outputs
+    Ground["Reports · bounded context<br/>Agent sync · Explain"]
 
-    Outputs --> Developers["Developers"]
-    Outputs --> CI["CI and releases"]
-    Outputs --> IDEs["IDEs"]
-    Outputs --> Agents["AI agents"]
-    Outputs --> MCP["MCP clients"]
+    Sources --> Connect
+    Connect --> Model
+    Model -->|derives, revision-bound| Graph
+    Model --> Decide
+    Graph --> Decide
+    Decide --> Ground
+
+    Ground --> Humans["Developers"]
+    Ground --> Automation["CI · releases"]
+    Ground --> Tools["IDEs · MCP · AI agents"]
 ```
 
 ## What This Means
@@ -40,8 +42,8 @@ flowchart TB
    the evidence needed for a safe decision.
 4. **Share the result.** Developers, CI, IDEs, AI agents, and MCP clients consume
    the same workspace truth instead of building separate assumptions. The
-   current CLI exposes a read-mostly `workspace mcp serve` bridge; a dedicated
-   `packages/mcp` boundary is planned.
+   current CLI exposes the governed evidence through its reports, agent context,
+   graph queries, and read-mostly `workspace mcp serve` bridge.
 
 This is the user-facing view. The implementation uses a versioned chain of
 model, change, evidence, verification, context, grounding, and explanation
@@ -57,7 +59,10 @@ baseline lifecycle, exit codes, and failure propagation are specified in
 [Unified Workspace Intelligence Runner](./workspace-intelligence-runner.md).
 
 The npm README uses a PNG rendering because npm package pages do not reliably
-render Mermaid. When this source changes, regenerate
+render Mermaid. npm also does not provide a dependable embedded-video player
+for package READMEs. Keep the full MP4 outside the published package. For inline
+motion, use a bounded, silent GIF hosted as a public asset; retain a linked MP4
+for full-resolution playback and audio. When this source changes, regenerate
 `From Code to Shared Understanding.png` before publishing.
 
 ## Execute the Contract