workspai 0.46.0 → 0.47.0

package/docs/README.md

@@ -27,6 +27,7 @@ instructions; see the [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md).
 
 ## Table of contents
 
+- [Choose a guide by goal](#choose-a-guide-by-goal)
 - [User documentation](#user-documentation)
 - [Operations & security](#operations--security)
 - [AI module recommendations](#ai-module-recommendations)
@@ -34,23 +35,44 @@ instructions; see the [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md).
 - [Contributor documentation](#contributor-documentation)
 - [Validation commands](#validation-commands)
 
+## Choose a guide by goal
+
+| I want to…                                     | Start here                                                                | Expected outcome                                                      |
+| ---------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Create a workspace or project                  | [Creating workspaces and projects](./creating-workspaces-and-projects.md) | A registered project with canonical `.workspai` metadata              |
+| Bring an existing repository under governance  | [Workspace operations](./workspace-operations.md#import-and-adoption)     | Source stays in place with `adopt`, or is copied/cloned with `import` |
+| Run the complete intelligence loop             | [Unified runner](./workspace-intelligence-runner.md)                      | One ordered run report with durable stage evidence                    |
+| Ask an architecture or dependency question     | [Workspace Knowledge Graph](./workspace-knowledge-graph.md)               | A bounded answer with proof references rather than the whole graph    |
+| Integrate CI or release gates                  | [CI workflows](./ci-workflows.md)                                         | Machine-readable exit codes and uploadable evidence                   |
+| Find the writer, schema, or path for an output | [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md)                       | One canonical source instead of path guessing                         |
+| Understand Workspai terminology                | [Glossary](./GLOSSARY.md)                                                 | Shared meanings for model, graph, evidence, gate, and artifacts       |
+| Contribute to the CLI                          | [Development](./DEVELOPMENT.md)                                           | Local build, test, contract, and documentation gates                  |
+
+There are two different AI-facing features. Workspace Intelligence is
+deterministic, proof-backed, and does not require an AI API key. The optional
+module recommender uses embeddings to suggest FastAPI or NestJS modules; start
+with [AI Quickstart](./AI_QUICKSTART.md) only when that is your goal.
+
 ## User documentation
 
-| Document | Description |
-| --- | --- |
-| [creating-workspaces-and-projects.md](./creating-workspaces-and-projects.md) | Plain-language guide to every workspace and project creation scenario |
-| [commands-reference.md](./commands-reference.md) | Full CLI syntax, profiles, and policy keys |
-| [workspace-operations.md](./workspace-operations.md) | Import, adopt, snapshots, archives, contracts, infra |
-| [workspace-run.md](./workspace-run.md) | Polyglot fleet orchestration (`workspace run`) |
-| [workspace-intelligence-runner.md](./workspace-intelligence-runner.md) | Canonical unified runner, execution envelope, report schema, exit codes, failure propagation, and CI consumption |
-| [create-planner-capabilities.md](./create-planner-capabilities.md) | Native create, official, and existing lanes |
-| [../contracts/project-entry-capability.v1.json](../contracts/project-entry-capability.v1.json) | Contract: any readable project can enter through adopt/import when it can be registered |
-| [from-code-to-shared-understanding.md](./from-code-to-shared-understanding.md) | GitHub-rendered Workspace Intelligence diagram |
-| [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md) | Role-based workflows (junior → enterprise) |
-| [doctor-command.md](./doctor-command.md) | Doctor scopes, CI exit codes, JSON evidence |
-| [config-file-guide.md](./config-file-guide.md) | User config file (`~/.workspairc.json`, `workspai.config.*`, with legacy fallbacks) |
-| [WORKSPACE_MARKER_SPEC.md](./WORKSPACE_MARKER_SPEC.md) | Workspace marker format |
-| [PACKAGE_MANAGER_POLICY.md](./PACKAGE_MANAGER_POLICY.md) | npm-only policy for this repository |
+| Document                                                                                       | Description                                                                                                        |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| [creating-workspaces-and-projects.md](./creating-workspaces-and-projects.md)                   | Plain-language guide to every workspace and project creation scenario                                              |
+| [commands-reference.md](./commands-reference.md)                                               | Full CLI syntax, profiles, and policy keys                                                                         |
+| [workspace-operations.md](./workspace-operations.md)                                           | Import, adopt, snapshots, archives, contracts, infra                                                               |
+| [workspace-run.md](./workspace-run.md)                                                         | Polyglot fleet orchestration (`workspace run`)                                                                     |
+| [workspace-intelligence-runner.md](./workspace-intelligence-runner.md)                         | Canonical unified runner, execution envelope, report schema, exit codes, failure propagation, and CI consumption   |
+| [workspace-knowledge-graph.md](./workspace-knowledge-graph.md)                                 | Two-minute graph quickstart, proof model, AI/MCP consumption, performance, and honest token-efficiency measurement |
+| [graph-benchmark-methodology.md](./graph-benchmark-methodology.md)                             | Reproducible payload-reduction benchmark, formulas, claim boundaries, and publication rules                        |
+| [GLOSSARY.md](./GLOSSARY.md)                                                                   | Plain-language definitions for workspace, model, graph, evidence, gates, and AI integrations                       |
+| [create-planner-capabilities.md](./create-planner-capabilities.md)                             | Native create, official, and existing lanes                                                                        |
+| [../contracts/project-entry-capability.v1.json](../contracts/project-entry-capability.v1.json) | Contract: any readable project can enter through adopt/import when it can be registered                            |
+| [from-code-to-shared-understanding.md](./from-code-to-shared-understanding.md)                 | GitHub-rendered Workspace Intelligence diagram                                                                     |
+| [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md)                               | Role-based workflows (junior → enterprise)                                                                         |
+| [doctor-command.md](./doctor-command.md)                                                       | Doctor scopes, CI exit codes, JSON evidence                                                                        |
+| [config-file-guide.md](./config-file-guide.md)                                                 | User config file (`~/.workspairc.json`, `workspai.config.*`, with legacy fallbacks)                                |
+| [WORKSPACE_MARKER_SPEC.md](./WORKSPACE_MARKER_SPEC.md)                                         | Workspace marker format                                                                                            |
+| [PACKAGE_MANAGER_POLICY.md](./PACKAGE_MANAGER_POLICY.md)                                       | npm-only policy for this repository                                                                                |
 
 **Common tasks**
 
@@ -63,35 +85,35 @@ instructions; see the [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md).
 
 ## Operations & security
 
-| Document | Description |
-| --- | --- |
-| [SECURITY.md](./SECURITY.md) | Vulnerability reporting and supported versions |
-| [policies.workspace.example.yml](./policies.workspace.example.yml) | Workspace policy template |
-| [governance-policy.enterprise.example.json](./governance-policy.enterprise.example.json) | Sigstore governance allowlist template |
-| [mirror-config.enterprise.example.json](./mirror-config.enterprise.example.json) | Mirror + evidence export template |
+| Document                                                                                 | Description                                    |
+| ---------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| [SECURITY.md](./SECURITY.md)                                                             | Vulnerability reporting and supported versions |
+| [policies.workspace.example.yml](./policies.workspace.example.yml)                       | Workspace policy template                      |
+| [governance-policy.enterprise.example.json](./governance-policy.enterprise.example.json) | Sigstore governance allowlist template         |
+| [mirror-config.enterprise.example.json](./mirror-config.enterprise.example.json)         | Mirror + evidence export template              |
 
 ## AI module recommendations
 
 FastAPI/NestJS module suggestions via OpenAI embeddings (optional).
 
-| Document | Description |
-| --- | --- |
-| [AI_QUICKSTART.md](./AI_QUICKSTART.md) | 60-second setup |
-| [AI_FEATURES.md](./AI_FEATURES.md) | Complete feature reference |
-| [AI_EXAMPLES.md](./AI_EXAMPLES.md) | Use-case examples |
-| [AI_DYNAMIC_INTEGRATION.md](./AI_DYNAMIC_INTEGRATION.md) | Integration architecture |
+| Document                                                 | Description                |
+| -------------------------------------------------------- | -------------------------- |
+| [AI_QUICKSTART.md](./AI_QUICKSTART.md)                   | 60-second setup            |
+| [AI_FEATURES.md](./AI_FEATURES.md)                       | Complete feature reference |
+| [AI_EXAMPLES.md](./AI_EXAMPLES.md)                       | Use-case examples          |
+| [AI_DYNAMIC_INTEGRATION.md](./AI_DYNAMIC_INTEGRATION.md) | Integration architecture   |
 
 ## Technical contracts
 
 JSON schemas and ownership rules for tooling parity.
 
-| Location | Description |
-| --- | --- |
-| [contracts/README.md](./contracts/README.md) | Core CLI JSON contracts + generator scripts |
-| [contracts/COMMAND_OWNERSHIP_MATRIX.md](./contracts/COMMAND_OWNERSHIP_MATRIX.md) | npm wrapper vs Core command ownership |
-| [contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md) | Scaffold/import/lifecycle support tiers |
-| [contracts/RUNTIME_ACCEPTANCE_MATRIX.md](./contracts/RUNTIME_ACCEPTANCE_MATRIX.md) | Runtime acceptance test expectations |
-| [../contracts/](../contracts/) | Canonical JSON schemas (published in npm tarball) |
+| Location                                                                           | Description                                       |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------- |
+| [contracts/README.md](./contracts/README.md)                                       | Core CLI JSON contracts + generator scripts       |
+| [contracts/COMMAND_OWNERSHIP_MATRIX.md](./contracts/COMMAND_OWNERSHIP_MATRIX.md)   | npm wrapper vs Core command ownership             |
+| [contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md)       | Scaffold/import/lifecycle support tiers           |
+| [contracts/RUNTIME_ACCEPTANCE_MATRIX.md](./contracts/RUNTIME_ACCEPTANCE_MATRIX.md) | Runtime acceptance test expectations              |
+| [../contracts/](../contracts/)                                                     | Canonical JSON schemas (published in npm tarball) |
 
 Regenerate and verify:
 
@@ -103,13 +125,13 @@ npm run contracts:validate
 
 ## Contributor documentation
 
-| Document | Description |
-| --- | --- |
-| [DEVELOPMENT.md](./DEVELOPMENT.md) | Local dev, testing, debugging |
-| [SETUP.md](./SETUP.md) | Build gates, smoke flows, release hygiene |
-| [ci-workflows.md](./ci-workflows.md) | GitHub Actions workflow map |
-| [OPTIMIZATION_GUIDE.md](./OPTIMIZATION_GUIDE.md) | Performance and improvement notes |
-| [UTILITIES.md](./UTILITIES.md) | Internal cache and metrics helpers |
+| Document                                         | Description                               |
+| ------------------------------------------------ | ----------------------------------------- |
+| [DEVELOPMENT.md](./DEVELOPMENT.md)               | Local dev, testing, debugging             |
+| [SETUP.md](./SETUP.md)                           | Build gates, smoke flows, release hygiene |
+| [ci-workflows.md](./ci-workflows.md)             | GitHub Actions workflow map               |
+| [OPTIMIZATION_GUIDE.md](./OPTIMIZATION_GUIDE.md) | Performance and improvement notes         |
+| [UTILITIES.md](./UTILITIES.md)                   | Internal cache and metrics helpers        |
 
 Also see [../CONTRIBUTING.md](../CONTRIBUTING.md) and [../CHANGELOG.md](../CHANGELOG.md).
 

package/docs/commands-reference.md

@@ -65,7 +65,7 @@ npx workspai workspace snapshot [--workspace <path>] [--json] [--include-paths]
 npx workspai workspace diff --from <snapshot-or-report|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|dot|mermaid] [key] [--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] [key] [value] [--from <graph.json>] [--limit <1..100>] [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
 npx workspai workspace watch [--workspace <path>] [--json] [--once] [--scan-depth <count>]
 npx workspai workspace explain|why <target> [--workspace <path>] [--json] [--write]
 npx workspai workspace trace --from <workspace-diff-report> [--workspace <path>] [--json] [--write]
@@ -94,6 +94,17 @@ npx workspai infra down [--workspace <path>] [--volumes]
 npx workspai infra status [--workspace <path>] [--json] [--strict]
 ```
 
+The contract graph includes its backward-compatible service projection, the
+canonical `workspace-dependency-graph.v1` project topology, and the portable
+`workspace-knowledge-graph.v1` evidence graph. The knowledge projection covers
+workspace/project structure, packages and dependencies, source files, modules,
+symbols, HTTP endpoints, OpenAPI/GraphQL/Protocol Buffers/AsyncAPI contracts,
+Compose/Kubernetes/Dockerfile/Terraform/Helm infrastructure, CI workflows,
+documentation, ADRs, tests, owners, environments, databases, and queues.
+Every entity and relation has stable identity and portable proof paths; proof
+taxonomy separates authored, extracted, and inferred facts and records trust,
+confidence, and freshness. Environment and secret values are never emitted.
+
 `workspace intelligence run` writes
 `.workspai/reports/workspace-intelligence-run-last-run.json`. Its `preflight`
 contains exactly `sync` and `baseline`, while `stages` contains exactly the 11
@@ -114,9 +125,45 @@ records are appended to
 `.workspai/reports/workspace-intelligence-history.json`; no separate feedback
 artifact is created.
 
-`workspace graph dot` and `workspace graph mermaid` intentionally emit raw DOT
-and Mermaid text for direct piping to renderers. Use `workspace graph emit
---json` or `workspace graph explain <project> --json` for structured JSON.
+`workspace graph emit --json` returns both the compatibility project graph and
+the knowledge graph. Use `workspace graph entities [kind]`, `workspace graph
+evidence <id-or-unique-label>`, and `workspace graph path <from> <to>` for
+indexed queries. `workspace graph overlay --from <prior-graph.json>` produces a
+portable change/PR overlay with additions, removals, changed fields, proof
+artifacts, proof additions/removals/content changes, bounded one-hop impact,
+and a risk summary. Observation timestamps and freshness alone do not create
+false change noise. Query indexes are cached
+per immutable graph object and invalidated automatically when a new graph is
+built. `dot` and `mermaid` intentionally remain project-topology renderers and
+emit raw text for direct piping.
+
+`workspace graph search <query> --limit <n> --json` returns bounded entities,
+one-hop relations, related entity summaries, and portable proofs instead of the
+complete graph. `workspace graph benchmark <query> --limit <n> --json` compares
+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.
+
+`workspace model --write` also materializes the derived, contract-validated
+knowledge graph at `.workspai/reports/workspace-knowledge-graph.json`. The
+unified intelligence runner treats that artifact as a required output of the
+Model step, so CI, IDE adapters, agent grounding, and MCP all observe the same
+revision. Agent contexts carry its reference, quality counts, and bounded query
+commands instead of copying the entire graph into every prompt. MCP exposes
+`getWorkspaceKnowledgeGraph`, `searchWorkspaceGraph`, `queryWorkspaceEntities`,
+`getWorkspaceGraphEvidence`, and `findWorkspaceGraphPath`.
+
+Source extraction is bounded and language-neutral by contract. It recognizes
+the primary source formats for TypeScript/JavaScript, Python, Go, Java/Kotlin,
+.NET/F#, Rust, Ruby, PHP, Swift, Dart, Elixir, Scala, Clojure, Lua, R, C/C++,
+Vue, and Svelte. Package baselines also recognize npm/Deno, Python, Go, Cargo,
+Maven/Gradle, NuGet, Composer, Ruby, Elixir, Dart, SwiftPM, CMake, Bazel, and SBT.
+Regex-backed
+source facts are marked `observed` with medium confidence; authored manifests
+and interface/infrastructure specifications remain authoritative. This avoids
+presenting heuristic symbol discovery as compiler-grade truth while keeping the
+current CLI useful until deeper language providers move into the standalone
+graph package.
 
 See [workspace-run.md](./workspace-run.md) for fleet orchestration semantics.
 

package/docs/config-file-guide.md

@@ -14,7 +14,7 @@ Supported fields include:
 {
   "defaultKit": "fastapi.standard",
   "defaultInstallMethod": "poetry",
-  "pythonVersion": "3.11",
+  "pythonVersion": "3.10",
   "author": "Platform Team",
   "license": "MIT",
   "skipGit": false,
@@ -56,7 +56,7 @@ Example:
 module.exports = {
   workspace: {
     defaultAuthor: 'Platform Team',
-    pythonVersion: '3.11',
+    pythonVersion: '3.10',
     installMethod: 'poetry',
   },
   projects: {
@@ -66,6 +66,10 @@ module.exports = {
 };
 ```
 
+Python-backed workflows require Python 3.10 or newer. `pythonVersion` selects a
+project target; it does not make Python a dependency for Node-only or other
+Python-free Workspai workflows.
+
 ## Command coverage
 
 Directory configuration is currently consumed by the legacy top-level creation

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -72,22 +72,29 @@ 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 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` |
+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`;
@@ -99,6 +106,11 @@ 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
 such as `outputPath`, `status`, or structured errors use
@@ -188,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`)
 
@@ -262,19 +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`                         | `{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` |
+| 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
 
@@ -320,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. **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)      |
@@ -345,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                                           |
@@ -353,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/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,7 +30,7 @@ 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`              | Shared-contract checks and focused 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                                      |
 
@@ -20,19 +38,23 @@ Workflow: change code → `npm run generate:contracts` → `npm run sync:parity-
 
 ## 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
@@ -44,6 +66,10 @@ 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/`):
 
@@ -51,6 +77,10 @@ Workspace intelligence (`../../contracts/workspace-intelligence/`):
 - `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`
@@ -64,6 +94,12 @@ 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 the
 [CLI README](../../README.md#one-intelligence-chain).