workspai 0.45.0 → 0.47.0

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -72,21 +72,44 @@ the same evidence without losing the workspace source of truth.
 
 ## Workspace intelligence
 
-| Command                                        | Artifact                                                                                                                                                                                                                                                     | Schema                                 | Contract file                                                             |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- |
-| `workspace model --write`                      | `workspace-model.json`                                                                                                                                                                                                                                       | `workspace-model.v1`                   | `contracts/workspace-intelligence/workspace-model.v1.json`                |
-| `workspace snapshot`                           | `workspace-model-snapshot.json`                                                                                                                                                                                                                              | `workspace-model-snapshot.v1`          | `contracts/workspace-intelligence/workspace-model-snapshot.v1.json`       |
-| `workspace diff`                               | `workspace-model-diff-last-run.json`                                                                                                                                                                                                                         | `workspace-model-diff.v1`              | `contracts/workspace-intelligence/workspace-model-diff.v1.json`           |
-| `workspace impact --from <diff>`               | `workspace-impact-last-run.json`                                                                                                                                                                                                                             | `workspace-impact.v1`                  | `contracts/workspace-intelligence/workspace-impact.v1.json`               |
-| `analyze --json`                               | `analyze-last-run.json`                                                                                                                                                                                                                                      | `rapidkit-analyze-v1`                  | `contracts/analyze-last-run.v1.json`                                      |
-| `workspace verify`                             | `workspace-verify-last-run.json`                                                                                                                                                                                                                             | `workspace-verify.v1`                  | `contracts/workspace-intelligence/workspace-verify.v1.json`               |
-| `workspace context --write`                    | `workspace-context-agent.json`                                                                                                                                                                                                                               | `workspace-context.v1`                 | `contracts/workspace-intelligence/workspace-context.v1.json`              |
-| `workspace agent-sync --write`                 | `reports/agent-customization-pack.json`                                                                                                                                                                                                                       | `rapidkit-agent-customization-pack.v1` | `contracts/workspace-intelligence/agent-customization-pack-report.v1.json` |
-| `workspace agent-sync --write`                 | `reports/INDEX.json`                                                                                                                                                                                                                                          | `rapidkit-agent-reports-index.v1`      | `contracts/workspace-intelligence/agent-reports-index.v1.json`            |
-| `workspace agent-sync --write`                 | `reports/workspace-skills-index.json`                                                                                                                                                                                                                          | `workspace-skills-index.v1`            | `contracts/workspace-intelligence/workspace-skills-index.v1.json`         |
-| `workspace agent-sync --write`                 | `reports/workspai-mcp-design.json`, `.workspai/skills/*.md`, `.workspai/AGENT-GROUNDING.md`, `AGENTS.md`, IDE agent surfaces                                                                                                                                 | Mixed generated surfaces               | See customization pack output inventory                                  |
-| `workspace explain --write`                    | `workspace-explain-last-run.json`                                                                                                                                                                                                                            | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`              |
-| `workspace feedback record` / `doctor * --fix` | `workspace-intelligence-history.json` (`kind: agent-action`, `doctor-fix`)                                                                                                                                                                                   | `workspace-intelligence-history.v1`    | `contracts/workspace-intelligence/workspace-intelligence-history.v1.json` |
+Bare artifact names in this table are relative to `.workspai/reports/`.
+Entries beginning with `reports/` are relative to `.workspai/`; paths such as
+`AGENTS.md` are relative to the workspace root.
+
+| Command                                        | Artifact                                                                                                                     | Schema                                 | Contract file                                                              |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------- |
+| `workspace model --write`                      | `workspace-model.json`                                                                                                       | `workspace-model.v1`                   | `contracts/workspace-intelligence/workspace-model.v1.json`                 |
+| `workspace model --write`                      | `workspace-knowledge-graph.json`                                                                                             | `workspace-knowledge-graph.v1`         | `contracts/workspace-intelligence/workspace-knowledge-graph.v1.json`       |
+| `workspace snapshot`                           | `workspace-model-snapshot.json`                                                                                              | `workspace-model-snapshot.v1`          | `contracts/workspace-intelligence/workspace-model-snapshot.v1.json`        |
+| `workspace diff`                               | `workspace-model-diff-last-run.json`                                                                                         | `workspace-model-diff.v1`              | `contracts/workspace-intelligence/workspace-model-diff.v1.json`            |
+| `workspace impact --from <diff>`               | `workspace-impact-last-run.json`                                                                                             | `workspace-impact.v1`                  | `contracts/workspace-intelligence/workspace-impact.v1.json`                |
+| `analyze --json`                               | `analyze-last-run.json`                                                                                                      | `rapidkit-analyze-v1`                  | `contracts/analyze-last-run.v1.json`                                       |
+| `workspace verify`                             | `workspace-verify-last-run.json`                                                                                             | `workspace-verify.v1`                  | `contracts/workspace-intelligence/workspace-verify.v1.json`                |
+| `workspace context --write`                    | `workspace-context-agent.json`                                                                                               | `workspace-context.v1`                 | `contracts/workspace-intelligence/workspace-context.v1.json`               |
+| `workspace agent-sync --write`                 | `reports/agent-customization-pack.json`                                                                                      | `rapidkit-agent-customization-pack.v1` | `contracts/workspace-intelligence/agent-customization-pack-report.v1.json` |
+| `workspace agent-sync --write`                 | `reports/INDEX.json`                                                                                                         | `rapidkit-agent-reports-index.v1`      | `contracts/workspace-intelligence/agent-reports-index.v1.json`             |
+| `workspace agent-sync --write`                 | `reports/workspace-skills-index.json`                                                                                        | `workspace-skills-index.v1`            | `contracts/workspace-intelligence/workspace-skills-index.v1.json`          |
+| `workspace agent-sync --write`                 | `reports/workspai-mcp-design.json`, `.workspai/skills/*.md`, `.workspai/AGENT-GROUNDING.md`, `AGENTS.md`, IDE agent surfaces | Mixed generated surfaces               | See customization pack output inventory                                    |
+| `workspace explain --write`                    | `workspace-explain-last-run.json`                                                                                            | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`               |
+| `workspace why --write`                        | `workspace-why-last-run.json`                                                                                                | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`               |
+| `workspace trace --write`                      | `workspace-trace-last-run.json`                                                                                              | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`               |
+| `workspace intelligence run`                   | `workspace-intelligence-run-last-run.json`                                                                                   | `workspace-intelligence-run.v1`        | `contracts/workspace-intelligence/workspace-intelligence-run.v1.json`      |
+| `workspace feedback record` / `doctor * --fix` | `workspace-intelligence-history.json` (`kind: agent-action`, `doctor-fix`)                                                   | `workspace-intelligence-history.v1`    | `contracts/workspace-intelligence/workspace-intelligence-history.v1.json`  |
+
+The unified runner report separates its execution envelope from the canonical
+intelligence chain. `preflight` always contains exactly `sync` and `baseline`;
+baseline resolution runs after `model` and before `diff`, recording `created` or
+`reused`. `stages` always contains exactly the 11 ordered steps declared by
+`workspace-intelligence-chain.v1`. JSON Schema enforces the transport shape and
+the runtime semantic validator additionally enforces artifact parity,
+status/exit coherence, hard-failure skip propagation, and the aggregate verdict.
+See [Unified Workspace Intelligence Runner](../workspace-intelligence-runner.md)
+for the normative user and integration semantics.
+
+`workspace-model.json` and `workspace-knowledge-graph.json` are published as one
+recoverable artifact transaction. The graph carries a SHA-256 `source` binding
+to the canonical model, so consumers must reject a graph whose source hash does
+not equal the current structural model hash.
 
 **CLI semantics:** `workspace diff --from` expects a **model or snapshot** baseline. `workspace impact --from` expects a **diff report**.
 Persisted artifacts retain their artifact schema. JSON command projections that add operation metadata
@@ -177,11 +200,18 @@ block, in `warn` mode they escalate to needs-attention.
 a dependency change makes every dependent stale deterministically. The verdict compares against
 the previously written verify report. Canonical source: `src/workspace-graph-freshness.ts`.
 
-**Graph command surface.** `workspace graph` emits the graph plus integrity + hotspots;
-`workspace graph explain <project>` returns centrality and direct/transitive relationships;
-`workspace graph dot|mermaid` render deterministic visualizations. Canonical source:
-`src/workspace-graph.ts`. The `graph` subcommand is part of `WORKSPACE_SUBCOMMANDS` and is
-published via `runtime-command-surface.v1` for IDE/CI capability detection.
+**Graph command surface.** `workspace graph` emits the dependency graph plus
+integrity and hotspots. `explain <project>` returns centrality and
+direct/transitive relationships. `search`, `entities`, `evidence`, and `path`
+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.
+Canonical sources are `src/workspace-graph.ts`,
+`src/workspace-knowledge-graph-query.ts`,
+`src/workspace-knowledge-graph-change-overlay.ts`, and
+`src/workspace-graph-token-efficiency.ts`. These command surfaces are published
+through `runtime-command-surface.v1` for IDE/CI capability detection.
 
 ### Model cache (`workspace-model-cache.v1`)
 
@@ -251,18 +281,19 @@ Canonical source: `src/observability/run-correlation.ts` (`attachRunCorrelation`
 
 ## Operational / platform
 
-| Command                          | Artifact                                                               | Notes                                                                                        | Contract                                                             |
-| -------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `workspace run`                  | `workspace-run-last.json`                                              | `workspace-run-v1` (multi-stage: `stages.test`, `stages.build`, …)                           | `contracts/workspace-run-last.v1.json`                               |
-| `autopilot release` (run stages) | same `workspace-run-last.json`                                         | Autopilot publishes test/build into aggregate (no separate `autopilot-workspace-run-*.json`) | —                                                                    |
-| `bootstrap`                      | `bootstrap-compliance-{ts}.json`, `bootstrap-compliance.latest.json`   |                                                                                              | —                                                                    |
-| `mirror status`                  | `mirror-ops-{ts}.json`, `mirror-ops.latest.json`                       |                                                                                              | —                                                                    |
-| `mirror` (transparency)          | `transparency-evidence-{ts}.json`, `transparency-evidence.latest.json` |                                                                                              | —                                                                    |
-| `infra plan`                     | `infra-plan.json`                                                      | `rapidkit.infra-plan.v1`                                                                     | —                                                                    |
-| `workspace archive`              | `.workspai/archive-manifest.json` inside ZIP/ZIP64                     | Streaming handoff; workspace payload is unlimited by default and safety budgets are opt-in   | `contracts/workspace-archive-manifest.v1.json`                       |
-| `workspace share`                | `reports/share-bundle.json` (default)                                  | Aggregation bundle                                                                           | —                                                                    |
-| `import` / `adopt`               | `{project}/.workspai/import-readiness.json`                            | Per project                                                                                  | —                                                                    |
-| `workspace contract verify`      | `workspace-contract-verify-last-run.json`                              | CLI verify cache                                                                             | `contracts/workspace-intelligence/workspace-contract-verify.v1.json` |
+| Command                          | Artifact                                                                       | Notes                                                                                        | Contract                                                             |
+| -------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `workspace run`                  | `workspace-run-last.json`                                                      | `workspace-run-v1` (multi-stage: `stages.test`, `stages.build`, …)                           | `contracts/workspace-run-last.v1.json`                               |
+| `autopilot release` (run stages) | same `workspace-run-last.json`                                                 | Autopilot publishes test/build into aggregate (no separate `autopilot-workspace-run-*.json`) | —                                                                    |
+| `bootstrap`                      | `bootstrap-compliance-{ts}.json`, `bootstrap-compliance.latest.json`           | `bootstrap-compliance.v1`                                                                    | `contracts/bootstrap-compliance.v1.json`                             |
+| `mirror status`                  | `mirror-ops-{ts}.json`, `mirror-ops.latest.json`                               | `mirror-ops.v1`                                                                              | `contracts/mirror-ops.v1.json`                                       |
+| `mirror` (transparency)          | `transparency-evidence-{ts}.json`, `transparency-evidence.latest.json`         | `transparency-evidence.v1`                                                                   | `contracts/transparency-evidence.v1.json`                            |
+| `infra plan`                     | `infra-plan.json`                                                              | `rapidkit.infra-plan.v1`                                                                     | —                                                                    |
+| `workspace archive`              | `.workspai/archive-manifest.json` inside ZIP/ZIP64                             | Streaming handoff; workspace payload is unlimited by default and safety budgets are opt-in   | `contracts/workspace-archive-manifest.v1.json`                       |
+| `workspace share`                | `reports/share-bundle.json` (default)                                          | Aggregation bundle (`1.1`)                                                                   | `contracts/workspace-share-bundle.v1.json`                           |
+| `import`                         | `{project}/.workspai/import.json`, `{project}/.workspai/import-readiness.json` | Copied/cloned project metadata and readiness                                                 | —                                                                    |
+| `adopt`                          | `{project}/.workspai/adopt.json`, `{project}/.workspai/adopt-readiness.json`   | In-place project metadata and readiness                                                      | —                                                                    |
+| `workspace contract verify`      | `workspace-contract-verify-last-run.json`                                      | CLI verify cache                                                                             | `contracts/workspace-intelligence/workspace-contract-verify.v1.json` |
 
 ## Static capability contracts
 
@@ -308,18 +339,29 @@ them as portable repository contracts. The portable source is
 
 Under `{project}/.workspai/reports/` when commands run at project scope (e.g. project doctor). Workspace-level reports stay under `{workspace}/.workspai/reports/`.
 
+After a Python Core bridge creates a project, Workspai validates and mirrors
+legacy `.rapidkit/project.json`, `context.json`, and `file-hashes.json` into the
+canonical project `.workspai/` directory without overwriting an existing
+canonical file. Legacy files remain readable during the compatibility window.
+
 ## Consumer rules
 
 1. **Project count:** read `workspace-registry.v1.json` (or run `workspace registry status --json`).
-2. **Release gates:** follow chain doctor → analyze → readiness → verify → autopilot; use `pipeline-last-run.json` for orchestration summary.
+2. **Workspace Intelligence chain:** run `workspace intelligence run --for-agent codex --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 customization:** read `.workspai/reports/agent-customization-pack.json` first for generated surfaces, then `.workspai/reports/INDEX.json` and `workspace-context-agent.json`; regenerate with `workspace agent-sync --write --refresh-context --preset enterprise`.
+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.
+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)
 
 Written by `workspace agent-sync --write --refresh-context --preset enterprise` (and by default after `workspace context --for-agent --write`):
 
+The generated output inventory is committed as one journaled transaction. On
+failure, all touched files are restored; an interrupted transaction is recovered
+before the next agent-sync. `agent-customization-pack.json` is written last and
+serves as the completed-generation marker.
+
 | Path                                                                    | Consumer                                                       |
 | ----------------------------------------------------------------------- | -------------------------------------------------------------- |
 | `AGENTS.md`                                                             | Copilot, Cursor, Claude Code, Codex, Grok (open standard)      |
@@ -333,7 +375,7 @@ Written by `workspace agent-sync --write --refresh-context --preset enterprise`
 | `.github/prompts/workspai-adopt-project.prompt.md`                      | Copilot adopt/import workflow prompt                           |
 | `.github/skills/workspai-grounding/SKILL.md`                            | Copilot skills                                                 |
 | `.github/skills/workspai-workspace-intelligence/SKILL.md`               | Enterprise Workspace Intelligence skill                        |
-| `.github/skills/workspai-workspace-intelligence/resources/mcp-tools.md` | Future MCP tool design reference                               |
+| `.github/skills/workspai-workspace-intelligence/resources/mcp-tools.md` | MCP tool and evidence-retrieval reference                      |
 | `.github/agents/workspai-advisor.agent.md`                              | Read-only workspace advisor agent                              |
 | `.github/agents/workspai-repair.agent.md`                               | Blocker repair agent                                           |
 | `.github/agents/workspai-release.agent.md`                              | Release safety agent                                           |
@@ -341,7 +383,7 @@ Written by `workspace agent-sync --write --refresh-context --preset enterprise`
 | `.cursor/rules/workspai-grounding.mdc`                                  | Cursor always-on rule                                          |
 | `CLAUDE.md`                                                             | Claude Code (imports `@AGENTS.md`)                             |
 | `.claude/rules/workspai-evidence.md`                                    | Claude Code scoped evidence rule                               |
-| `.claude/rules/rapidkit-evidence.md`                                    | Legacy Claude Code scoped evidence mirror                      |
+| `.claude/rules/rapidkit-evidence.md`                                    | Legacy compatibility alias pointing to the canonical rule      |
 | `.workspai/AGENT-GROUNDING.md`                                          | Tool-agnostic operator doc                                     |
 | `.workspai/reports/agent-customization-pack.json`                       | Versioned output inventory, target matrix, drift state         |
 | `.workspai/reports/workspai-mcp-design.json`                            | Read-mostly MCP-ready design manifest                          |

package/docs/contracts/CLI_LOG_EVENT_STREAM.md

@@ -75,7 +75,7 @@ Each stderr line is a single JSON object:
   "component": "cli",
   "message": "CLI run started",
   "command": ["workspace", "model"],
-  "metadata": { "cwd": "/path/to/workspace", "rapidkitVersion": "0.38.0" }
+  "metadata": { "cwd": "/path/to/workspace", "rapidkitVersion": "<workspai-version>" }
 }
 ```
 

package/docs/contracts/README.md

@@ -2,6 +2,24 @@
 
 Contract documentation for JSON payloads, support matrices, and cross-repo parity.
 
+## Complete contract discovery
+
+The complete machine-readable inventory is
+[`../../contracts/published-contract-catalog.v1.json`](../../contracts/published-contract-catalog.v1.json).
+It is the source of truth for every published schema/capability path; the lists
+below are grouped entry points, not a substitute for that catalog.
+
+Installed consumers can discover the active package version and contract map
+without scraping Markdown:
+
+```bash
+npx workspai --version --json
+```
+
+Resolve contract files from the installed `workspai/contracts/` directory and
+validate payloads against the exact catalog revision shipped with that CLI.
+Do not copy a schema from `main` and assume it matches an older installed CLI.
+
 ## Monorepo workflow
 
 Canonical JSON lives in **`../../contracts/`** (CLI package root, published in the tarball).
@@ -12,26 +30,31 @@ Canonical JSON lives in **`../../contracts/`** (CLI package root, published in t
 | `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`              | Generate check + mirror check + contract tests                                                                        |
+| `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                                      |
 
 Workflow: change code → `npm run generate:contracts` → `npm run sync:parity-snapshot` → commit npm + vscode `contracts/`.
 
 ## Documents in this folder
 
-| File                                                           | Purpose                                                     |
-| -------------------------------------------------------------- | ----------------------------------------------------------- |
-| [ARTIFACT_CATALOG.md](./ARTIFACT_CATALOG.md)                   | On-disk artifact paths, schema versions, and consumer rules |
-| [COMMAND_OWNERSHIP_MATRIX.md](./COMMAND_OWNERSHIP_MATRIX.md)   | Which commands the npm wrapper owns vs Python Core          |
+| File                                                           | Purpose                                                           |
+| -------------------------------------------------------------- | ----------------------------------------------------------------- |
+| [ARTIFACT_CATALOG.md](./ARTIFACT_CATALOG.md)                   | On-disk artifact paths, schema versions, and consumer rules       |
+| [COMMAND_OWNERSHIP_MATRIX.md](./COMMAND_OWNERSHIP_MATRIX.md)   | Which commands the npm wrapper owns vs Python Core                |
 | [NAMING_AND_COEXISTENCE.md](./NAMING_AND_COEXISTENCE.md)       | Workspace Intelligence command naming and generated surface rules |
-| [RUNTIME_SUPPORT_MATRIX.md](./RUNTIME_SUPPORT_MATRIX.md)       | Scaffold, import, lifecycle, and module support tiers       |
-| [RUNTIME_ACCEPTANCE_MATRIX.md](./RUNTIME_ACCEPTANCE_MATRIX.md) | Runtime acceptance matrix expectations                      |
-| [rapidkit-cli-contracts.json](./rapidkit-cli-contracts.json)   | Core CLI JSON schema fragments                              |
+| [RUNTIME_SUPPORT_MATRIX.md](./RUNTIME_SUPPORT_MATRIX.md)       | Scaffold, import, lifecycle, and module support tiers             |
+| [RUNTIME_ACCEPTANCE_MATRIX.md](./RUNTIME_ACCEPTANCE_MATRIX.md) | Runtime acceptance matrix expectations                            |
+| [rapidkit-cli-contracts.json](./rapidkit-cli-contracts.json)   | Core CLI JSON schema fragments                                    |
 
 ## Workspace intelligence schemas
 
 Published under `../../contracts/` (not duplicated in this folder):
 
+- `published-contract-catalog.v1.json` — complete machine-readable contract inventory
+- `workspace-contract.v1.json` — canonical workspace project/relationship contract
+- `runtime-command-surface.v1.json` and `cli-runtime-command-inventory.v1.snapshot.json` — supported command/capability discovery
+- `workspace-intelligence-architecture.v1.json` and `workspace-intelligence-chain.v1.json` — architecture boundaries and ordered loop
 - `workspace-registry.v1.json` — canonical project registry summary (see [ARTIFACT_CATALOG.md](./ARTIFACT_CATALOG.md))
 - `release-readiness.v1.json` — release readiness gate evidence
 - `workspace-run-last.v1.json` — multi-stage workspace run evidence
@@ -43,12 +66,21 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `project-entry-capability.v1.json` — open-ended adopt/import contract for readable projects
 - `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
+- `project-archive.v1.json`, `workspace-snapshot.v1.json`, and `workspace-snapshot.v2.json` — recoverable lifecycle records
+- `infra-plan.v1.json`, `private-product-manifest.v1.json`, and `product-factory-plan.v1.json` — infrastructure and product planning payloads
+- `workspace-model-cache.v1.json`, `workspace-watch-event.v1.json`, `doctor-project-scan.v2.json`, and `doctor-workspace-cache.v2.json` — cache/watch/diagnostic support contracts
 
 Workspace intelligence (`../../contracts/workspace-intelligence/`):
 
+- `workspace-intelligence-run.v1.json` — authoritative full-chain result, stage outcomes, verdict, exit code, and durable artifact path
 - `workspace-model.v1.json`
 - `workspace-context.v1.json`
 - `workspace-dependency-graph.v1.json`
+- `workspace-knowledge-graph.v1.json` — proof-backed entities, relations, evidence, providers, and model binding
+- `workspace-knowledge-graph-change-overlay.v1.json` — proposed/change-set facts and relations without mutating the base graph
+- `workspace-knowledge-search.v1.json` — bounded ranked retrieval for CLI, MCP, IDE, and agent consumers
+- `workspace-graph-token-efficiency.v1.json` — reproducible corpus-versus-retrieval payload measurement
 - `workspace-model-snapshot.v1.json`
 - `workspace-model-diff.v1.json`
 - `workspace-impact.v1.json`
@@ -62,8 +94,15 @@ Workspace intelligence (`../../contracts/workspace-intelligence/`):
 - `blocker-resolution.v1.json`
 - `doctor-fix-result.v1.json`
 - `studio-blocker-handoff.v1.json`
+- `mcp-design.v1.json` and `agent-hooks.v1.json` — generated MCP/IDE integration surfaces
+
+These schemas describe durable artifacts or bounded query results. A command's
+stdout may wrap an artifact with operation metadata such as `status`,
+`outputPath`, or a structured error; that envelope follows
+`cli-operation-result.v1.json` and does not change the nested artifact contract.
 
-CLI commands: see [commands-reference.md](../commands-reference.md) and [../README.md](../README.md#workspace-intelligence).
+CLI commands: see [commands-reference.md](../commands-reference.md) and the
+[CLI README](../../README.md#one-intelligence-chain).
 
 ## Core CLI JSON payloads
 

package/docs/contracts/RUNTIME_ACCEPTANCE_MATRIX.md

@@ -43,10 +43,10 @@ lifecycle failures only when the CLI prints actionable diagnostics such as
 
 The matrix verifies:
 
-- npm-owned global entrypoints: `--version` and `-v`.
-- global command ownership contract via `commands --json`, plus core-owned
-  catalog commands in default/full modes: `version`, `commands`, `list`,
-  `info`, `frameworks`, `modules`, and `license`.
+- npm-owned global entrypoints: `--version`, `-v`, and `commands --json`.
+- delegated Core catalog surfaces in default/full modes: `version`, `list`,
+  `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.

package/docs/contracts/RUNTIME_SUPPORT_MATRIX.md

@@ -1,11 +1,11 @@
 # Workspai Runtime Support Matrix
 
-Last updated: 2026-06-15
+Last updated: 2026-07-18
 
 This document defines the public support contract for Workspai workspace projects.
 It separates three concerns:
 
-- **First-class**: curated RapidKit kit/framework with scaffold/import/govern/lifecycle support. Module mutation still follows the runtime row below.
+- **First-class**: curated kit/framework with scaffold/import/govern/lifecycle support. Core module mutation additionally requires metadata for a module-enabled kit.
 - **Extended**: scaffold/import/govern/lifecycle or import/govern workflows are supported, but Core module mutation is disabled unless explicitly added later.
 - **Observed**: import/govern/contract visibility is supported; lifecycle commands may require manual project scripts or future adapters.
 
@@ -13,8 +13,8 @@ It separates three concerns:
 
 | Runtime             | Tier        | Scaffold | Import | Lifecycle Commands                                | Module Commands | Doctor    |
 | ------------------- | ----------- | -------: | -----: | ------------------------------------------------- | --------------: | --------- |
-| Python              | first-class |      yes |    yes | init, dev, start, build, test, lint, format, help |             yes | full      |
-| Node.js             | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |             yes | full      |
+| Python              | first-class |      yes |    yes | init, dev, start, build, test, lint, format, help | kit-dependent | full      |
+| Node.js             | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help | kit-dependent | full      |
 | Go                  | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
 | Java / Spring Boot  | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
 | .NET / ASP.NET Core | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
@@ -31,13 +31,17 @@ It separates three concerns:
 
 ## Framework Tiers
 
-> **Runtime vs framework:** Python **runtime** stays first-class (Core-backed modules). Node.js **runtime** is extended; **NestJS** is the first-class Node framework. Frontend stacks (Next.js, Remix, Vite variants, Nuxt, Angular, Astro, SvelteKit) are extended frameworks on the Node runtime.
+> **Runtime vs framework:** Python remains a first-class runtime and Node.js is
+> extended. Core module mutation is guaranteed only when project metadata names
+> a module-enabled kit: `fastapi.standard`, `fastapi.ddd`, or
+> `nestjs.standard`. Arbitrary FastAPI, NestJS, Python, Node.js, and frontend
+> projects remain governable without gaining module mutation.
 
-| Tier        | Frameworks                                                                                                                                                  |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| first-class | FastAPI, NestJS                                                                                                                                              |
+| Tier        | Frameworks                                                                                                                                                                                                                          |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| first-class | FastAPI, NestJS                                                                                                                                                                                                                     |
 | extended    | Go/Fiber, Go/Gin, Spring Boot, ASP.NET Core, Django, Flask, Express, Fastify, Koa, Echo, Laravel, Symfony, Rails, Sinatra, Actix, Axum, Rocket, Phoenix, Next.js, Remix, React, Vue, Svelte, Solid, Nuxt, Angular, Astro, SvelteKit |
-| observed    | Python, Node.js, Go, Java, PHP, Ruby, Rust, Elixir, Unknown/generic projects                                                                                |
+| observed    | Python, Node.js, Go, Java, PHP, Ruby, Rust, Elixir, Unknown/generic projects                                                                                                                                                        |
 
 ## Import Policy
 
@@ -45,7 +49,7 @@ Imported projects are **observed and governed by default**:
 
 - Workspai writes `.workspai/project.json` so workspace contract, graph, doctor, and sharing flows can discover the project.
 - Workspai writes canonical project metadata to `.workspai/project.json` and reads legacy `.rapidkit/project.json` as fallback for older projects.
-- Workspai writes `.workspai/import.json` and `.workspai/import-readiness.json` for auditability, with legacy mirrors when needed.
+- Workspai writes `.workspai/import.json` and `.workspai/import-readiness.json` for auditability while preserving existing Python Core or legacy `.rapidkit` project state.
 - Secrets and dependency/build caches are not copied during local-folder import.
 - `module_support` defaults to `false` for imported projects unless existing RapidKit metadata explicitly opts in.