workspai 0.46.0 → 0.48.0

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -72,22 +72,31 @@ 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`    |
+| `workspace eval init` / `workspace eval record` | `workspace-intelligence-evaluation-live.json`                                                                                | `workspace-intelligence-evaluation.v1` | `contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json` |
+| `workspace eval report`                         | `workspace-intelligence-evaluation-last-run.json`                                                                            | `workspace-intelligence-evaluation.v1` | `contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json` |
 
 The unified runner report separates its execution envelope from the canonical
 intelligence chain. `preflight` always contains exactly `sync` and `baseline`;
@@ -99,6 +108,18 @@ 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.
+
+`workspace graph jsonld|graphml|gexf --output <path>` creates explicit interchange
+projections from that bound graph. These files are portable exports, not competing
+canonical or `last-run` artifacts: JSON-LD preserves semantic identifiers,
+GraphML targets general graph tooling, and GEXF targets exploration and
+visualization tools. Mermaid and DOT remain bounded text projections for docs
+and diagrams.
+
 **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 +209,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 +290,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 +348,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 +384,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 +392,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,13 @@ 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
+- `model-usage-event.v1.json` — privacy-bounded model, tool, milestone, and verified-outcome events with explicit measurement provenance
+- `workspace-intelligence-evaluation.v1.json` — live/final token, cost, latency, activity, and verified-outcome evaluation
+- `workspace-intelligence-evaluation-comparison.v1.json` — task-aligned comparison of two completed evaluation strategies
 - `workspace-model-snapshot.v1.json`
 - `workspace-model-diff.v1.json`
 - `workspace-impact.v1.json`
@@ -64,6 +97,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).

package/docs/graph-benchmark-methodology.md

@@ -0,0 +1,121 @@
+# Graph Retrieval Benchmark Methodology
+
+This document defines what Workspai measures when it reports graph retrieval
+payload reduction, how to reproduce a result, and what the result does—and does
+not—prove.
+
+## The question being measured
+
+For one query, how much smaller is the bounded, proof-carrying graph response
+than the readable source corpus that supplied the graph's proofs?
+
+This is useful because AI agents do not need every indexed file for every
+question. It is deliberately narrower than “How many tokens will this model
+bill?” or “Will the model produce an equally good answer?”
+
+## Run it
+
+From a Workspai workspace:
+
+```bash
+npx workspai workspace model --write --json
+npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json
+```
+
+The result conforms to
+[`workspace-graph-token-efficiency.v1.json`](../contracts/workspace-intelligence/workspace-graph-token-efficiency.v1.json).
+It records:
+
+- the query and result limit;
+- the graph schema, entity/relation/proof counts, source artifact, and source
+  model SHA-256;
+- the number and size of readable, deduplicated proof-source artifacts;
+- the bounded retrieval size and match count;
+- unreadable artifacts rather than silently excluding them;
+- the estimate formula, reduction ratio, percentage, and claim boundary.
+
+## Baseline and formula
+
+The current methodology is `indexed-corpus-vs-bounded-retrieval.v1`.
+
+```text
+corpus characters    = sum(unique readable proof-source files)
+retrieval characters = compact JSON length of bounded search response
+estimated tokens     = ceil(characters / 4)
+reduction ratio      = corpus estimated tokens / retrieval estimated tokens
+reduction percent    = (corpus - retrieval) / corpus × 100
+```
+
+`characters / 4` is intentionally labelled as an estimate. It is portable and
+reproducible without downloading a tokenizer, but it is not exact for every
+language, model, or tokenizer.
+
+## Current fixture observation
+
+The 16-project development workspace reproduced the following result on
+2026-07-22 for `api endpoint --limit 8`:
+
+| Measure                         | Observed value |
+| ------------------------------- | -------------: |
+| Graph entities                  |          1,738 |
+| Graph relations                 |          2,244 |
+| Graph proofs                    |          2,106 |
+| Readable proof-source artifacts |            392 |
+| Corpus estimated tokens         |        134,105 |
+| Retrieval estimated tokens      |          2,812 |
+| Returned entities               |              8 |
+| Retrieval ratio                 |         47.69× |
+| Payload reduction               |          97.9% |
+
+Source-model SHA-256:
+`2b8abd415420cc421707c726e6f6c96641554594e84440bf2e539f04ba5836e8`.
+
+This row demonstrates that measurement is possible. It is not a representative
+cross-project benchmark and must not be marketed as a universal Workspai result.
+
+## What can be claimed today
+
+Safe wording:
+
+> Workspai can return bounded, proof-carrying workspace context instead of the
+> complete indexed corpus. On the current 16-project development fixture, one
+> `api endpoint` query reduced the estimated retrieval payload by 97.9%; results
+> vary by workspace and query.
+
+Unsafe wording:
+
+- “Workspai always reduces model tokens by 97.9%.”
+- “Agents are 47.69× cheaper with no quality loss.”
+- “Workspai beats another product” without a shared corpus and evaluation
+  harness.
+
+## Gate for a public headline benchmark
+
+Before publishing a general token-efficiency number, the benchmark suite must:
+
+1. pin public repositories and exact commit SHAs;
+2. publish fixed question sets and graph configuration;
+3. compare at least three baselines:
+   - entire readable corpus;
+   - a realistic grep/top-file retrieval strategy;
+   - bounded Workspai graph retrieval;
+4. count with at least one real, named tokenizer in addition to the portable
+   character estimate;
+5. measure answer relevance or task completion so smaller context is not treated
+   as automatically better context;
+6. repeat runs and publish variance, failures, unreadable files, hardware, and
+   software versions;
+7. publish raw machine-readable results and a one-command reproduction path;
+8. report median and range—not only the best repository.
+
+## Performance is a separate benchmark
+
+Payload size and graph speed answer different questions. Build time, incremental
+update time, peak memory, artifact size, and p50/p95 query latency must be
+measured separately. Do not infer runtime performance from the token-efficiency
+report.
+
+For normal interactive use, prefer `workspace graph search` or the MCP
+`searchWorkspaceGraph` tool. Use the complete graph artifact for interchange,
+offline analysis, audits, and consumers that explicitly require the entire
+workspace representation.

package/docs/workspace-intelligence-evaluation.md

@@ -0,0 +1,147 @@
+# Measure Workspace Intelligence Usage
+
+Workspai can record model usage, tool activity, cost provenance, and the final
+verified outcome of an agent task. The resulting artifact is designed for CLI,
+IDE, CI, and dashboard consumers.
+
+It does not store prompt or response bodies. Optional SHA-256 hashes let a
+consumer correlate calls without copying private content into the report.
+
+## Start a measured task
+
+```bash
+npx workspai workspace eval init repair-readiness workspace-intelligence --json
+```
+
+The optional strategy is one of `full-corpus`, `grep`, `vector`, `graph`,
+`workspace-intelligence`, or `custom`.
+
+The live source of truth is:
+
+```text
+.workspai/reports/workspace-intelligence-evaluation-live.json
+```
+
+## Record events
+
+Providers and IDE integrations append privacy-bounded events through stdin:
+
+```bash
+printf '%s\n' '{
+  "kind": "model-call",
+  "stage": "context",
+  "modelCall": {
+    "provider": "vscode-lm",
+    "model": "selected-model",
+    "source": "provider-reported",
+    "inputTokens": 18420,
+    "outputTokens": 2150,
+    "cachedInputTokens": 6200,
+    "reasoningTokens": null,
+    "latencyMs": 4820
+  }
+}' | npx workspai workspace eval record --json
+```
+
+`source` is mandatory:
+
+| Source              | Meaning                                                        |
+| ------------------- | -------------------------------------------------------------- |
+| `provider-reported` | The provider returned the count                                |
+| `tokenizer-counted` | A named tokenizer counted the exact serialized input or output |
+| `estimated`         | A documented estimate; never presented as provider billing     |
+| `unavailable`       | The provider exposed no usable count                            |
+
+Tool events record progress and repeated work without storing command output:
+
+```json
+{
+  "kind": "tool-call",
+  "stage": "verify",
+  "toolCall": {
+    "tool": "workspace verify",
+    "result": "passed",
+    "changedSource": false,
+    "durationMs": 814,
+    "artifact": ".workspai/reports/workspace-verify-last-run.json"
+  }
+}
+```
+
+Finish with a verified outcome event. Tokens per successful outcome remain
+`null` until `status` is `passed` and `verified` is `true`.
+
+```json
+{
+  "kind": "outcome",
+  "stage": "verify",
+  "outcome": {
+    "status": "passed",
+    "verified": true,
+    "blockersResolved": 1,
+    "summary": "Readiness passed after dependency remediation."
+  }
+}
+```
+
+Event bodies conform to
+[`model-usage-event.v1.json`](../contracts/workspace-intelligence/model-usage-event.v1.json).
+
+## Inspect and finalize
+
+```bash
+npx workspai workspace eval status --json
+npx workspai workspace eval report --json
+```
+
+Finalization writes:
+
+```text
+.workspai/reports/workspace-intelligence-evaluation-last-run.json
+```
+
+Both live and final reports conform to
+[`workspace-intelligence-evaluation.v1.json`](../contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json).
+
+## Compare strategies
+
+Save a completed baseline, run the same fixed task using another strategy, then
+compare:
+
+```bash
+npx workspai workspace eval compare --from .workspai/reports/baselines/full-corpus.json --json
+```
+
+The comparison reports token, model-call, tool-call, latency, and verified
+outcome differences. A smaller prompt is not treated as a better result unless
+the outcomes are task-aligned and independently verified.
+
+Comparison JSON conforms to
+[`workspace-intelligence-evaluation-comparison.v1.json`](../contracts/workspace-intelligence/workspace-intelligence-evaluation-comparison.v1.json),
+so CI, IDE, and dashboard consumers do not need to infer its shape.
+
+## Extension and dashboard contract
+
+The VS Code extension should watch the live artifact and display its values; it
+must not independently estimate or relabel them. At minimum the UI should show:
+
+- run and session identity;
+- live/final status and update time;
+- input, output, cached-input, and reasoning token components;
+- provider-reported, tokenizer-counted, estimated, and unavailable call counts;
+- cost grouped by currency and source;
+- tool calls, repeated artifact reads, and no-progress decisions;
+- verified outcome and blockers resolved.
+
+This makes the CLI artifact the source of truth for terminal, extension, CI,
+and future hosted dashboards. MCP clients can read the same artifact through
+`getWorkspaceEvaluation`; agent-sync also includes the finalized report in the
+governed evidence index when it exists.
+
+## Relationship to the graph benchmark
+
+`workspace graph benchmark` measures **retrieval payload size** using a portable
+character estimate. `workspace eval` measures **observed agent execution** and
+requires outcome evidence. Keep both: the first is deterministic and
+provider-independent; the second is the basis for real token, cost, and task
+efficiency claims.