workspai 0.46.0 → 0.48.0

package/README.md

@@ -1,87 +1,121 @@
 # Workspai CLI
 
-## Open-Source Workspace Intelligence for Software Systems
-
 [![npm version](https://img.shields.io/npm/v/workspai.svg?style=flat-square)](https://www.npmjs.com/package/workspai)
 [![Downloads](https://img.shields.io/npm/dm/workspai.svg?style=flat-square)](https://www.npmjs.com/package/workspai)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
 [![Built by Workspai](https://img.shields.io/badge/Built%20by-Workspai-0f172a?logo=github)](https://workspai.dev)
 
-Not another AI coding assistant.
-Not another agent framework.
-Not another context engine.
+## Workspace Intelligence for software systems
 
 > One workspace. One truth. Humans and AI aligned.
 
-Workspai turns scattered projects into a governed, agent-ready workspace.
+Workspai is an open-source CLI that turns one or many software projects into an
+organized, evidence-backed view of the whole system. Developers, CI, IDEs,
+MCP-compatible tools, and AI agents can use the same current model instead of
+rebuilding a different picture from scattered files.
+
+- **See the system:** projects, runtimes, APIs, dependencies, infrastructure,
+  documentation, policies, and release state in one model.
+- **Ask with proof:** bounded graph answers linked to the files and facts that
+  support them.
+- **Act with confidence:** change impact, health, verification, readiness, and
+  agent context from one defined and versioned intelligence chain.
+
+[Quickstart](#start-in-two-minutes) ·
+[Architecture](#from-code-to-shared-understanding) ·
+[Commands](#core-workflows) ·
+[Outputs](#outputs-and-consumers) ·
+[Documentation](#documentation)
+
+## Understand Workspai in one minute
 
-It gives developers, CI, IDEs, and AI agents the same evidence-backed source of
-truth: workspace model, agent context, impact analysis, verification evidence,
-contracts, and release gates.
+Your software system is more than a repository. It may include several
+applications and services, shared packages, API contracts, deployment files,
+documentation, tests, ownership, and CI evidence. Workspai connects those
+surfaces without making AI the source of truth.
 
-## Start here
+| Term                | Plain-language meaning                                                               |
+| ------------------- | ------------------------------------------------------------------------------------ |
+| **Workspace**       | The managed boundary containing registered projects, policy, contracts, and evidence |
+| **Project**         | An application, service, library, or existing source tree connected to the workspace |
+| **Workspace Model** | The authoritative structured record used to generate the other views and artifacts   |
+| **Knowledge Graph** | A queryable representation derived from the model, with typed relations and proofs   |
+| **Evidence**        | The source, observation, hash, or report that justifies a fact or decision           |
+| **Artifact**        | A durable file under `.workspai/` that another tool can safely consume               |
 
-### Install
+The Workspace Model is the canonical source of truth. The Knowledge Graph is a
+derived, revision-bound representation—not a competing truth and not an
+LLM-generated guess.
+
+The deterministic model, graph, contracts, and verification chain do not
+require an AI API key. Optional AI-backed features declare that dependency
+separately.
+
+## Start in two minutes
+
+### 1. Install or use `npx`
 
 ```bash
 npm install -g workspai
 workspai --help
 ```
 
-For short `npx` workflows, use the separate alias package:
+Global installation is optional. Every example below also works with
+`npx workspai`. The separate `wspai` package is only a short alias:
 
 ```bash
 npx wspai --help
 ```
 
 `workspai` is the canonical npm package and command. `wspai` is an optional
-short alias for `npx` workflows. RapidKit Core is the optional Python engine
-used only by Python/Core-dependent workflows; it is not a replacement CLI.
-This package is the active CLI boundary in the
+short alias for `npx` workflows. This package is the active CLI boundary in the
 [Workspai monorepo](../../README.md).
 
-### CLI help
-
-Browse all commands from the latest release without a global install:
+### 2. Create a lightweight workspace and connect existing source
 
 ```bash
-npx workspai@latest --help
+npx workspai create workspace platform --profile minimal --yes
+npx workspai adopt /absolute/path/to/project \
+  --workspace ~/.workspai/workspaces/platform \
+  --json
+cd ~/.workspai/workspaces/platform
 ```
 
-## Get Workspace Intelligence
-
-Project creation, import, and adoption are entry routes. The core experience
-starts when Workspai builds a durable model of the whole workspace and turns it
-into evidence that different tools can consume.
+`adopt` registers the project without moving or copying it. To create new
+software instead, start with `npx workspai create` or read
+[Creating Workspaces and Projects](docs/creating-workspaces-and-projects.md).
 
-Connect an existing project without moving or copying its source:
-
-```bash
-npx workspai adopt /path/to/project --json
-cd ~/.workspai/workspaces/workspai
-```
-
-Execute the canonical chain and persist the shared model, evidence, and
-agent-ready context:
+### 3. Run the complete Workspace Intelligence chain
 
 ```bash
 npx workspai workspace intelligence run --for-agent codex --strict --json
 ```
 
-You now have a common source of truth for projects, runtimes, dependencies,
-commands, policies, contracts, health, and release evidence. The first durable
-outputs include:
+`codex` selects the generated agent-facing surface; use another supported agent
+identifier when needed. The underlying intelligence chain and evidence remain
+the same.
+
+The run creates durable, discoverable output:
 
 ```text
-.workspai/reports/workspace-model.json
-.workspai/reports/workspace-context-agent.json
-.workspai/reports/INDEX.json
-.workspai/reports/workspace-intelligence-run-last-run.json
+.workspai/
+├── workspace.json
+├── workspace.contract.json
+├── AGENT-GROUNDING.md
+└── reports/
+    ├── workspace-model.json
+    ├── workspace-knowledge-graph.json
+    ├── workspace-impact-last-run.json
+    ├── workspace-verify-last-run.json
+    ├── workspace-context-agent.json
+    ├── workspace-intelligence-run-last-run.json
+    └── INDEX.json
 AGENTS.md
 ```
 
-Already inside a Workspai workspace? Start directly with the canonical
-`workspace intelligence run --for-agent codex --strict --json` runner.
+Exit code `0` means passed, `1` means execution failed, and `2` means the run
+completed but current evidence blocks the requested decision. A blocked result
+is useful evidence, not a crashed command.
 
 The broader governance and release pipeline is a separate gate when you are
 ready; it is not a substitute for the canonical chain:
@@ -98,6 +132,24 @@ npx workspai pipeline --json --strict
 
 Workspai is the deterministic layer between source code and its consumers:
 
+```text
+Code · packages · APIs · infrastructure · docs · CI · policies
+                              │
+                   deterministic providers
+                              │
+                       facts + proofs
+                              │
+                  Canonical Workspace Model
+                       │              │
+                       │              └── Evidence-backed Knowledge Graph
+                       │                         │
+                       └──────────┬──────────────┘
+                                  │
+                diff · impact · verify · context · explain
+                                  │
+               Developers · CI · IDEs · MCP · AI agents
+```
+
 | Capability            | What it answers                                                                             |
 | --------------------- | ------------------------------------------------------------------------------------------- |
 | **Model**             | What projects, runtimes, frameworks, commands, policies, contracts, and dependencies exist? |
@@ -113,6 +165,10 @@ Create, import, and adopt add software to this boundary. Workspace Intelligence
 then models and governs every registered project, whether Workspai created it or
 it already existed.
 
+Unlike repository-only code intelligence, the workspace boundary can connect
+evidence across multiple projects and repositories. A missing relationship
+means **not proven by current evidence**, not "these projects are independent."
+
 ## One Intelligence Chain
 
 The canonical execution order is versioned in
@@ -140,23 +196,81 @@ and enforce this exact contract-backed order. `pipeline --json --strict` remains
 the broader governance/release orchestrator (`sync → doctor → analyze → readiness
 → autopilot`); it is not an alias for the canonical intelligence chain.
 
+## Evidence and measurable context
+
+Without bounded retrieval, a developer or agent often has to search and read a
+large part of the workspace before answering a local question. Workspai can
+return the matching entities, nearby relations, and source proofs first:
+
+```bash
+npx workspai workspace graph search "who implements the login API?" --limit 8 --json
+```
+
+Use the complete graph for interchange and audits; use bounded search for
+normal questions and agent context. Workspai reports unknown or unproven
+relationships instead of inventing an edge.
+
+### Current measured fixture
+
+| Measure                              | Observed value |
+| ------------------------------------ | -------------: |
+| Registered projects                  |             16 |
+| Knowledge Graph entities             |          1,738 |
+| Knowledge Graph relations            |          2,244 |
+| Portable proofs                      |          2,106 |
+| Readable proof-source artifacts      |            392 |
+| Corpus size (`characters / 4`)       | 134,105 tokens |
+| `api endpoint --limit 8` retrieval   |   2,812 tokens |
+| Observed retrieval payload reduction |          97.9% |
+| Observed corpus/retrieval ratio      |         47.69× |
+
+This is a reproducible observation from one 16-project development workspace on
+2026-07-22, not a universal token-cost, answer-quality, or task-success claim.
+See [Graph Benchmark Methodology](docs/graph-benchmark-methodology.md) for the
+source hash, formulas, limitations, and publication gate. Use
+`workspace eval` when measuring provider-reported tokens, latency, cost, and a
+verified execution outcome.
+
 ## Core Workflows
 
-| What you need                              | Command                                                                                  |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| Build and persist the current system model | `npx workspai workspace model --json --write`                                            |
-| Generate agent-ready context               | `npx workspai workspace context --for-agent --json --write`                              |
-| Generate portable agent and IDE surfaces   | `npx workspai workspace agent-sync --write --refresh-context --preset enterprise --json` |
-| Save a model baseline                      | `npx workspai workspace snapshot --json`                                                 |
-| Compare with a baseline or Git state       | `npx workspai workspace diff --from <snapshot-or-git-ref> --json`                        |
-| Calculate transitive blast radius          | `npx workspai workspace impact --from <diff-report> --json`                              |
-| Verify affected projects and evidence      | `npx workspai workspace verify --from-impact <impact-report> --json --strict`            |
-| Explain a blocker                          | `npx workspai workspace explain release-blocked --json --write`                          |
-| Inspect a project in the dependency graph  | `npx workspai workspace graph explain <project> --json`                                  |
-| Run affected project tests                 | `npx workspai workspace run test --affected --blast-radius --json`                       |
-| Run the release/governance gate            | `npx workspai pipeline --json --strict`                                                  |
-| Run the canonical intelligence chain       | `npx workspai workspace intelligence run --for-agent codex --strict --json`              |
-| Expose current evidence to MCP clients     | `npx workspai workspace mcp serve`                                                       |
+Use the complete intelligence runner for the normal end-to-end path. The
+individual commands below are useful for inspection, automation, and targeted
+reruns.
+
+### Model, change, and decisions
+
+| What you need                              | Command                                                                       |
+| ------------------------------------------ | ----------------------------------------------------------------------------- |
+| Build and persist the current system model | `npx workspai workspace model --json --write`                                 |
+| Save a model baseline                      | `npx workspai workspace snapshot --json`                                      |
+| Compare with a baseline or Git state       | `npx workspai workspace diff --from <snapshot-or-git-ref> --json`             |
+| Calculate transitive blast radius          | `npx workspai workspace impact --from <diff-report> --json`                   |
+| Verify affected projects and evidence      | `npx workspai workspace verify --from-impact <impact-report> --json --strict` |
+| Explain a blocker                          | `npx workspai workspace explain release-blocked --json --write`               |
+
+### Graph, agents, and interoperability
+
+| What you need                             | Command                                                                                  |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Inspect a project in the dependency graph | `npx workspai workspace graph explain <project> --json`                                  |
+| Query proof-backed workspace entities     | `npx workspai workspace graph entities endpoint --json`                                  |
+| Retrieve bounded context for an agent     | `npx workspai workspace graph search "authentication endpoint" --limit 12 --json`        |
+| Measure retrieval payload reduction       | `npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json`     |
+| Start a model-usage evaluation            | `npx workspai workspace eval init repair-readiness workspace-intelligence --json`        |
+| Export graph for semantic/visual tools    | `npx workspai workspace graph graphml --output workspace-graph.graphml`                  |
+| Trace a relationship and its evidence     | `npx workspai workspace graph path <from> <to> --json`                                   |
+| Compare two knowledge-graph revisions     | `npx workspai workspace graph overlay --from <graph.json> --json`                        |
+| Generate agent-ready context              | `npx workspai workspace context --for-agent --json --write`                              |
+| Generate portable agent and IDE surfaces  | `npx workspai workspace agent-sync --write --refresh-context --preset enterprise --json` |
+| Expose current evidence to MCP clients    | `npx workspai workspace mcp serve`                                                       |
+
+### Governance and operations
+
+| What you need                        | Command                                                                     |
+| ------------------------------------ | --------------------------------------------------------------------------- |
+| Run affected project tests           | `npx workspai workspace run test --affected --blast-radius --json`          |
+| Run the release/governance gate      | `npx workspai pipeline --json --strict`                                     |
+| Run the canonical intelligence chain | `npx workspai workspace intelligence run --for-agent codex --strict --json` |
 
 `workspace verify` consumes current impact, doctor, contract, analysis, and
 readiness evidence. Use `workspace intelligence run` for the canonical chain,
@@ -211,6 +325,11 @@ including `AGENTS.md`, report indexes, skills, and supported Copilot, Cursor,
 Claude, and Codex surfaces. AI tools begin with the same scope, commands,
 contracts, blockers, and verification evidence used by humans and CI.
 
+For a user-focused graph quickstart, AI output paths, performance boundaries,
+and reproducible token-efficiency methodology, see the
+[Workspace Knowledge Graph guide](docs/workspace-knowledge-graph.md) and
+[Graph Benchmark Methodology](docs/graph-benchmark-methodology.md).
+
 ## Outputs and Consumers
 
 Workspai separates human output, machine output, and durable cross-tool state:
@@ -227,21 +346,39 @@ Workspai separates human output, machine output, and durable cross-tool state:
 
 Important durable outputs:
 
-| Artifact                                                | Producer                       | Used for                              |
-| ------------------------------------------------------- | ------------------------------ | ------------------------------------- |
-| `.workspai/reports/workspace-model.json`                | `workspace model --write`      | Canonical system structure            |
-| `.workspai/reports/workspace-model-diff-last-run.json`  | `workspace diff`               | Structural change evidence            |
-| `.workspai/reports/workspace-impact-last-run.json`      | `workspace impact`             | Blast radius and affected scope       |
-| `.workspai/reports/workspace-verify-last-run.json`      | `workspace verify`             | Structured verification gate          |
-| `.workspai/reports/workspace-context-agent.json`        | `workspace context --write`    | Canonical agent context               |
-| `.workspai/reports/INDEX.json`                          | `workspace agent-sync --write` | Agent read order and report discovery |
-| `.workspai/reports/workspace-explain-last-run.json`     | `workspace explain --write`    | Evidence-backed narrative             |
-| `.workspai/reports/workspace-intelligence-history.json` | Verify and feedback flows      | Trends and audit history              |
-| `.workspai/reports/pipeline-last-run.json`              | `pipeline --json`              | CI and release workflow result        |
+| Artifact                                                            | Producer                       | Used for                                         |
+| ------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------ |
+| `.workspai/reports/workspace-model.json`                            | `workspace model --write`      | Canonical system structure                       |
+| `.workspai/reports/workspace-knowledge-graph.json`                  | `workspace model --write`      | Proof-backed retrieval and MCP                   |
+| `.workspai/reports/workspace-model-diff-last-run.json`              | `workspace diff`               | Structural change evidence                       |
+| `.workspai/reports/workspace-impact-last-run.json`                  | `workspace impact`             | Blast radius and affected scope                  |
+| `.workspai/reports/workspace-verify-last-run.json`                  | `workspace verify`             | Structured verification gate                     |
+| `.workspai/reports/workspace-context-agent.json`                    | `workspace context --write`    | Canonical agent context                          |
+| `.workspai/reports/INDEX.json`                                      | `workspace agent-sync --write` | Agent read order and report discovery            |
+| `.workspai/reports/workspace-explain-last-run.json`                 | `workspace explain --write`    | Evidence-backed narrative                        |
+| `.workspai/reports/workspace-intelligence-history.json`             | Verify and feedback flows      | Trends and audit history                         |
+| `.workspai/reports/workspace-intelligence-evaluation-live.json`     | `workspace eval init/record`   | Live provider/tokenizer usage and activity       |
+| `.workspai/reports/workspace-intelligence-evaluation-last-run.json` | `workspace eval report`        | Final usage, cost, and verified outcome evidence |
+| `.workspai/reports/pipeline-last-run.json`                          | `pipeline --json`              | CI and release workflow result                   |
 
 See the [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md) for the complete
 writer, schema, and consumer map.
 
+### Graph interchange formats
+
+The canonical persisted graph is JSON. Explicit projections make the same
+governed data usable in documentation, semantic systems, and visualization
+tools without changing the source of truth:
+
+| Format  | Typical use                             | Command selector              |
+| ------- | --------------------------------------- | ----------------------------- |
+| JSON    | Canonical artifact and programmatic use | `workspace graph emit --json` |
+| JSON-LD | Semantic-web and linked-data tools      | `workspace graph jsonld`      |
+| Mermaid | Markdown documentation and diagrams     | `workspace graph mermaid`     |
+| DOT     | Graphviz rendering                      | `workspace graph dot`         |
+| GraphML | General graph analysis tools            | `workspace graph graphml`     |
+| GEXF    | Exploration and visualization tools     | `workspace graph gexf`        |
+
 ## Onboard Software
 
 All onboarding routes feed the same Workspace Intelligence model.
@@ -291,20 +428,27 @@ Python is not required for Python-free workspace profiles, npm-owned backend
 generators, frontend generators, or workspaces created with
 `--skip-python-engine`.
 
+RapidKit Core is the optional Python engine used only by Python/Core-dependent
+workflows; it is not a replacement CLI.
+
 ## Documentation
 
-| Documentation                                                                | Purpose                                                  |
-| ---------------------------------------------------------------------------- | -------------------------------------------------------- |
-| [Documentation index](docs/README.md)                                        | All user, operator, contract, and contributor docs       |
-| [Command reference](docs/commands-reference.md)                              | Complete command syntax and flags                        |
-| [Creating workspaces and projects](docs/creating-workspaces-and-projects.md) | Interactive, automated, location, and linking behavior   |
-| [Workspace operations](docs/workspace-operations.md)                         | Adopt, import, snapshots, archives, contracts, and infra |
-| [Workspace run](docs/workspace-run.md)                                       | Polyglot and affected-project execution                  |
-| [Doctor command](docs/doctor-command.md)                                     | Health checks, evidence, fixes, and exit codes           |
-| [CI workflows](docs/ci-workflows.md)                                         | CI examples and repository validation                    |
-| [Configuration](docs/config-file-guide.md)                                   | User configuration and precedence                        |
-| [Open-source scenarios](docs/OPEN_SOURCE_USER_SCENARIOS.md)                  | Role-oriented examples                                   |
-| [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md)                       | Canonical files, writers, schemas, and readers           |
+| Documentation                                                                  | Purpose                                                       |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| [Documentation index](docs/README.md)                                          | All user, operator, contract, and contributor docs            |
+| [Command reference](docs/commands-reference.md)                                | Complete command syntax and flags                             |
+| [Creating workspaces and projects](docs/creating-workspaces-and-projects.md)   | Interactive, automated, location, and linking behavior        |
+| [Workspace operations](docs/workspace-operations.md)                           | Adopt, import, snapshots, archives, contracts, and infra      |
+| [Workspace run](docs/workspace-run.md)                                         | Polyglot and affected-project execution                       |
+| [Workspace Knowledge Graph](docs/workspace-knowledge-graph.md)                 | Proof-backed queries, AI/MCP retrieval, and graph outputs     |
+| [Graph benchmark methodology](docs/graph-benchmark-methodology.md)             | Reproducible payload-reduction measurements and claim limits  |
+| [Workspace Intelligence Evaluation](docs/workspace-intelligence-evaluation.md) | Live token, cost, activity, and verified-outcome measurements |
+| [Glossary](docs/GLOSSARY.md)                                                   | Plain-language meanings for model, graph, evidence, and gates |
+| [Doctor command](docs/doctor-command.md)                                       | Health checks, evidence, fixes, and exit codes                |
+| [CI workflows](docs/ci-workflows.md)                                           | CI examples and repository validation                         |
+| [Configuration](docs/config-file-guide.md)                                     | User configuration and precedence                             |
+| [Open-source scenarios](docs/OPEN_SOURCE_USER_SCENARIOS.md)                    | Role-oriented examples                                        |
+| [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md)                         | Canonical files, writers, schemas, and readers                |
 
 Repository workflows include
 [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml),
@@ -327,7 +471,7 @@ contributor-automation map.
 | Python/Core workflow cannot start  | `python3 --version`                            | Install Python 3.10+ or use a Python-free profile where supported        |
 | Workspace is not detected          | Look for `.workspai-workspace`                 | Run from the workspace or pass `--workspace <path>`                      |
 | Strict policy blocks a command     | `.workspai/policies.yml`                       | Inspect `workspace policy show` before changing policy                   |
-| Reports are stale                  | Report timestamps                              | Re-run `pipeline` or the required chain stages                           |
+| Reports are stale                  | Report timestamps                              | Re-run `workspace intelligence run` or the documented producing command  |
 | AI tools ignore workspace evidence | `AGENTS.md` and `.workspai/reports/INDEX.json` | Run `workspace agent-sync --write --refresh-context`                     |
 | Project generator fails            | Runtime and network output                     | Fix the reported prerequisite, then retry or create officially and adopt |
 

package/contracts/agent-customization-pack.v1.json

@@ -107,7 +107,17 @@
     },
     {
       "path": ".workspai/reports/workspace-model.json",
-      "label": "Workspace model graph",
+      "label": "Workspace model",
+      "required": false
+    },
+    {
+      "path": ".workspai/reports/workspace-knowledge-graph.json",
+      "label": "Workspace knowledge graph",
+      "required": false
+    },
+    {
+      "path": ".workspai/reports/workspace-intelligence-evaluation-last-run.json",
+      "label": "Workspace Intelligence evaluation",
       "required": false
     },
     {

package/contracts/bootstrap-compliance.v1.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/bootstrap-compliance.v1.json",
+  "type": "object",
+  "required": ["schemaVersion", "command", "timestamp", "result", "checks"],
+  "properties": {
+    "schemaVersion": { "const": "bootstrap-compliance.v1" },
+    "command": { "const": "bootstrap" },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "result": { "enum": ["ok", "ok_with_warnings", "blocked", "failed"] },
+    "checks": { "type": "array", "items": { "type": "object" } }
+  },
+  "additionalProperties": true
+}

package/contracts/cli-runtime-command-inventory.v1.snapshot.json

@@ -1200,6 +1200,10 @@
           "flags": "--scan-depth <count>",
           "attributeName": "scanDepth"
         },
+        {
+          "flags": "--limit <count>",
+          "attributeName": "limit"
+        },
         {
           "flags": "--cache",
           "attributeName": "cache"

package/contracts/extension-cli-compatibility.v1.json

@@ -1,8 +1,9 @@
 {
   "schemaVersion": "rapidkit-extension-cli-compatibility.v1",
   "cli": "workspai",
-  "minimumVerifiedCliVersion": "0.46.0",
+  "minimumVerifiedCliVersion": "0.48.0",
   "publishedContractSchemas": {
+    "workspaceContract": 1,
     "runtimeCommandSurface": "rapidkit-runtime-command-surface-v1",
     "cliRuntimeCommandInventory": "workspai-cli-runtime-command-inventory-v1",
     "cliOperationResult": "workspai-cli-operation-result-v1",
@@ -15,6 +16,7 @@
     "workspaceIntelligenceChain": "workspai-workspace-intelligence-chain-v1",
     "workspaceIntelligenceArtifacts": {
       "model": "workspace-model.v1",
+      "knowledgeGraph": "workspace-knowledge-graph.v1",
       "snapshot": "workspace-model-snapshot.v1",
       "diff": "workspace-model-diff.v1",
       "impact": "workspace-impact.v1",
@@ -30,7 +32,9 @@
       "skillsIndex": "workspace-skills-index.v1",
       "agents": null,
       "explain": "workspace-explain.v1",
-      "intelligenceRun": "workspace-intelligence-run.v1"
+      "intelligenceRun": "workspace-intelligence-run.v1",
+      "evaluationLive": "workspace-intelligence-evaluation.v1",
+      "evaluationLastRun": "workspace-intelligence-evaluation.v1"
     },
     "cliLogEvent": "cli-log-event-v1",
     "freshnessMetadata": "rapidkit-freshness-metadata-v1",
@@ -41,6 +45,13 @@
     "workspaceVerify": "workspace-verify.v1",
     "workspaceContext": "workspace-context.v1",
     "workspaceDependencyGraph": "workspace-dependency-graph.v1",
+    "workspaceKnowledgeGraph": "workspace-knowledge-graph.v1",
+    "workspaceKnowledgeGraphChangeOverlay": "workspace-knowledge-graph-change-overlay.v1",
+    "workspaceKnowledgeSearch": "workspace-knowledge-search.v1",
+    "workspaceGraphTokenEfficiency": "workspace-graph-token-efficiency.v1",
+    "modelUsageEvent": "model-usage-event.v1",
+    "workspaceIntelligenceEvaluation": "workspace-intelligence-evaluation.v1",
+    "workspaceIntelligenceEvaluationComparison": "workspace-intelligence-evaluation-comparison.v1",
     "workspaceIntelligenceHistory": "workspace-intelligence-history.v1",
     "agentCustomizationPackCapabilities": "workspai-agent-customization-pack-capabilities.v1",
     "agentCustomizationPackReport": "rapidkit-agent-customization-pack.v1",

package/contracts/mirror-ops.v1.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/mirror-ops.v1.json",
+  "type": "object",
+  "required": ["schemaVersion", "command", "action", "result", "timestamp", "workspacePath", "mirror"],
+  "properties": {
+    "schemaVersion": { "const": "mirror-ops.v1" },
+    "command": { "const": "mirror" },
+    "action": { "enum": ["status", "sync", "verify", "rotate"] },
+    "result": { "enum": ["ok", "failed"] },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "workspacePath": { "type": "string", "minLength": 1 },
+    "mirror": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/contracts/published-contract-catalog.v1.json

@@ -1,6 +1,11 @@
 {
   "schemaVersion": "workspai-published-contract-catalog-v1",
   "contracts": {
+    "workspaceContract": {
+      "schemaVersion": 1,
+      "contractPath": "contracts/workspace-contract.v1.json",
+      "publication": "json-schema"
+    },
     "runtimeCommandSurface": {
       "schemaVersion": "rapidkit-runtime-command-surface-v1",
       "contractPath": "contracts/runtime-command-surface.v1.json",
@@ -54,6 +59,7 @@
     "workspaceIntelligenceArtifacts": {
       "schemaVersion": {
         "model": "workspace-model.v1",
+        "knowledgeGraph": "workspace-knowledge-graph.v1",
         "snapshot": "workspace-model-snapshot.v1",
         "diff": "workspace-model-diff.v1",
         "impact": "workspace-impact.v1",
@@ -69,7 +75,9 @@
         "skillsIndex": "workspace-skills-index.v1",
         "agents": null,
         "explain": "workspace-explain.v1",
-        "intelligenceRun": "workspace-intelligence-run.v1"
+        "intelligenceRun": "workspace-intelligence-run.v1",
+        "evaluationLive": "workspace-intelligence-evaluation.v1",
+        "evaluationLastRun": "workspace-intelligence-evaluation.v1"
       },
       "contractPath": null,
       "publication": "embedded-type",
@@ -79,6 +87,11 @@
           "schemaVersion": "workspace-model.v1",
           "contractPath": "contracts/workspace-intelligence/workspace-model.v1.json"
         },
+        "knowledgeGraph": {
+          "path": ".workspai/reports/workspace-knowledge-graph.json",
+          "schemaVersion": "workspace-knowledge-graph.v1",
+          "contractPath": "contracts/workspace-intelligence/workspace-knowledge-graph.v1.json"
+        },
         "snapshot": {
           "path": ".workspai/reports/workspace-model-snapshot.json",
           "schemaVersion": "workspace-model-snapshot.v1",
@@ -158,6 +171,16 @@
           "path": ".workspai/reports/workspace-intelligence-run-last-run.json",
           "schemaVersion": "workspace-intelligence-run.v1",
           "contractPath": "contracts/workspace-intelligence/workspace-intelligence-run.v1.json"
+        },
+        "evaluationLive": {
+          "path": ".workspai/reports/workspace-intelligence-evaluation-live.json",
+          "schemaVersion": "workspace-intelligence-evaluation.v1",
+          "contractPath": "contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json"
+        },
+        "evaluationLastRun": {
+          "path": ".workspai/reports/workspace-intelligence-evaluation-last-run.json",
+          "schemaVersion": "workspace-intelligence-evaluation.v1",
+          "contractPath": "contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json"
         }
       }
     },
@@ -206,6 +229,41 @@
       "contractPath": "contracts/workspace-intelligence/workspace-dependency-graph.v1.json",
       "publication": "json-schema"
     },
+    "workspaceKnowledgeGraph": {
+      "schemaVersion": "workspace-knowledge-graph.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-knowledge-graph.v1.json",
+      "publication": "json-schema"
+    },
+    "workspaceKnowledgeGraphChangeOverlay": {
+      "schemaVersion": "workspace-knowledge-graph-change-overlay.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-knowledge-graph-change-overlay.v1.json",
+      "publication": "json-schema"
+    },
+    "workspaceKnowledgeSearch": {
+      "schemaVersion": "workspace-knowledge-search.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-knowledge-search.v1.json",
+      "publication": "json-schema"
+    },
+    "workspaceGraphTokenEfficiency": {
+      "schemaVersion": "workspace-graph-token-efficiency.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-graph-token-efficiency.v1.json",
+      "publication": "json-schema"
+    },
+    "modelUsageEvent": {
+      "schemaVersion": "model-usage-event.v1",
+      "contractPath": "contracts/workspace-intelligence/model-usage-event.v1.json",
+      "publication": "json-schema"
+    },
+    "workspaceIntelligenceEvaluation": {
+      "schemaVersion": "workspace-intelligence-evaluation.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json",
+      "publication": "json-schema"
+    },
+    "workspaceIntelligenceEvaluationComparison": {
+      "schemaVersion": "workspace-intelligence-evaluation-comparison.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-intelligence-evaluation-comparison.v1.json",
+      "publication": "json-schema"
+    },
     "workspaceIntelligenceHistory": {
       "schemaVersion": "workspace-intelligence-history.v1",
       "contractPath": "contracts/workspace-intelligence/workspace-intelligence-history.v1.json",