workspai 0.46.0 → 0.47.0

package/README.md

@@ -19,6 +19,40 @@ 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.
 
+### What changes for the user?
+
+Without Workspai, an agent repeatedly searches files and reconstructs a partial
+picture. With Workspai, it can ask a bounded question and receive the matching
+entities, nearby relations, and source proofs:
+
+```bash
+npx workspai workspace graph search "who implements the login API?" --limit 8 --json
+```
+
+Workspai is broader than a repository code graph. It connects projects, source,
+packages, APIs, infrastructure, pipelines, documentation, decisions, tests, and
+ownership inside one workspace model—then uses that same truth for impact,
+verification, CI, IDEs, MCP, and agent grounding.
+
+### 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-21, not a universal token-cost or answer-quality claim. See
+[Graph Benchmark Methodology](docs/graph-benchmark-methodology.md) for the source
+hash, formulas, limitations, and publication gate.
+
 ## Start here
 
 ### Install
@@ -153,6 +187,12 @@ the broader governance/release orchestrator (`sync → doctor → analyze → re
 | 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`                                  |
+| 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`     |
+| 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`                        |
+| Persist model + agent/MCP graph artifact   | `npx workspai workspace model --write --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`              |
@@ -211,6 +251,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:
@@ -230,6 +275,7 @@ Important durable outputs:
 | 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          |
@@ -293,18 +339,21 @@ generators, frontend generators, or workspaces created with
 
 ## 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  |
+| [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),

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

@@ -107,7 +107,12 @@
     },
     {
       "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
     },
     {

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.47.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",
@@ -41,6 +43,10 @@
     "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",
     "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",
@@ -79,6 +85,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",
@@ -206,6 +217,26 @@
       "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"
+    },
     "workspaceIntelligenceHistory": {
       "schemaVersion": "workspace-intelligence-history.v1",
       "contractPath": "contracts/workspace-intelligence/workspace-intelligence-history.v1.json",

package/contracts/runtime-command-surface.v1.json

@@ -495,6 +495,22 @@
         "mirror"
       ]
     },
+    {
+      "invocation": "mirror status",
+      "summary": "Inspect mirror configuration, lock state, and cached artifact inventory.",
+      "canonicalArgv": [
+        "mirror",
+        "status"
+      ]
+    },
+    {
+      "invocation": "mirror sync",
+      "summary": "Synchronize governed mirror artifacts and publish integrity evidence.",
+      "canonicalArgv": [
+        "mirror",
+        "sync"
+      ]
+    },
     {
       "invocation": "modules",
       "summary": "List supported project modules and their runtime-specific capability state.",
@@ -744,6 +760,15 @@
         "agent-sync"
       ]
     },
+    {
+      "invocation": "workspace agent-sync --write",
+      "summary": "Publish the governed agent surface generation as a recoverable workspace transaction.",
+      "canonicalArgv": [
+        "workspace",
+        "agent-sync",
+        "--write"
+      ]
+    },
     {
       "invocation": "workspace agent-sync --write --json --preset enterprise",
       "summary": "Generate the enterprise agent-grounding pack, persist every governed artifact, and emit a structured result.",
@@ -792,6 +817,15 @@
         "contract"
       ]
     },
+    {
+      "invocation": "workspace contract sync",
+      "summary": "Reconcile discovered projects into the canonical workspace contract and registry summary.",
+      "canonicalArgv": [
+        "workspace",
+        "contract",
+        "sync"
+      ]
+    },
     {
       "invocation": "workspace contract verify --strict --json",
       "summary": "Strictly validate workspace contracts and emit a structured evidence artifact that blocks on violations.",
@@ -906,6 +940,16 @@
       "output": {
         "defaultFormat": "human-or-json",
         "modes": [
+          {
+            "selector": "search <query> --limit <count> --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
+          {
+            "selector": "benchmark <query> --limit <count> --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
           {
             "selector": "emit --json",
             "format": "json",
@@ -1137,6 +1181,19 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/reports/workspace-knowledge-graph.json",
+      "schemaVersion": "workspace-knowledge-graph.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-knowledge-graph.v1.json",
+      "producerCommands": [
+        [
+          "workspace",
+          "model",
+          "--json",
+          "--write"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/reports/workspace-model-snapshot.json",
       "schemaVersion": "workspace-model-snapshot.v1",
@@ -1345,6 +1402,22 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/workspace.contract.json",
+      "schemaVersion": 1,
+      "contractPath": "contracts/workspace-contract.v1.json",
+      "producerCommands": [
+        [
+          "workspace",
+          "sync"
+        ],
+        [
+          "workspace",
+          "contract",
+          "sync"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/cache/workspace-model.v1.json",
       "schemaVersion": "workspace-model-cache.v1",
@@ -1367,6 +1440,70 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/compatibility-matrix.json",
+      "schemaVersion": "rapidkit.compatibility-matrix.v1",
+      "contractPath": "contracts/compatibility-matrix.v1.json",
+      "producerCommands": [
+        [
+          "bootstrap"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/reports/doctor-workspace-cache.json",
+      "schemaVersion": "doctor-workspace-cache-v2",
+      "contractPath": "contracts/doctor-workspace-cache.v2.json",
+      "producerCommands": [
+        [
+          "doctor",
+          "workspace"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/reports/bootstrap-compliance.latest.json",
+      "schemaVersion": "bootstrap-compliance.v1",
+      "contractPath": "contracts/bootstrap-compliance.v1.json",
+      "producerCommands": [
+        [
+          "bootstrap"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/reports/mirror-ops.latest.json",
+      "schemaVersion": "mirror-ops.v1",
+      "contractPath": "contracts/mirror-ops.v1.json",
+      "producerCommands": [
+        [
+          "mirror",
+          "status"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/reports/transparency-evidence.latest.json",
+      "schemaVersion": "transparency-evidence.v1",
+      "contractPath": "contracts/transparency-evidence.v1.json",
+      "producerCommands": [
+        [
+          "mirror",
+          "sync"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/reports/share-bundle.json",
+      "schemaVersion": "1.1",
+      "contractPath": "contracts/workspace-share-bundle.v1.json",
+      "producerCommands": [
+        [
+          "workspace",
+          "share"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/reports/doctor-project-last-run.json",
       "schemaVersion": "doctor-project-evidence-v1",
@@ -1458,7 +1595,13 @@
       "artifactPath": ".workspai/reports/workspai-mcp-design.json",
       "schemaVersion": "workspai-mcp-design.v1",
       "contractPath": "contracts/workspace-intelligence/mcp-design.v1.json",
-      "producerCommands": []
+      "producerCommands": [
+        [
+          "workspace",
+          "agent-sync",
+          "--write"
+        ]
+      ]
     },
     {
       "artifactPath": ".workspai/reports/workspace-why-last-run.json",
@@ -1575,6 +1718,11 @@
           "path": ".workspai/reports/workspace-model.json",
           "schemaVersion": "workspace-model.v1",
           "contractPath": "contracts/workspace-intelligence/workspace-model.v1.json"
+        },
+        {
+          "path": ".workspai/reports/workspace-knowledge-graph.json",
+          "schemaVersion": "workspace-knowledge-graph.v1",
+          "contractPath": "contracts/workspace-intelligence/workspace-knowledge-graph.v1.json"
         }
       ]
     },

package/contracts/transparency-evidence.v1.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/transparency-evidence.v1.json",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "records"],
+  "properties": {
+    "schemaVersion": { "const": "transparency-evidence.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "environment": { "type": ["string", "null"] },
+    "records": { "type": "array", "items": { "type": "object" } }
+  },
+  "additionalProperties": true
+}

package/contracts/workspace-contract.v1.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-contract.v1.json",
+  "title": "Workspai Workspace Contract",
+  "type": "object",
+  "required": ["schemaVersion", "kind", "generatedAt", "workspace", "projects"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "rapidkit.workspace.contract" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "workspace": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "profile": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "projects": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["slug", "relativePath", "modules", "ports", "contracts"],
+        "properties": {
+          "slug": { "type": "string", "minLength": 1 },
+          "relativePath": { "type": "string", "minLength": 1 },
+          "source": { "enum": ["workspace", "local-folder", "git-url", "adopted-local"] },
+          "relationship": { "enum": ["imported", "adopted"] },
+          "externalPath": { "type": "string", "minLength": 1 },
+          "runtime": { "type": "string", "minLength": 1 },
+          "framework": { "type": "string", "minLength": 1 },
+          "kit": { "type": "string", "minLength": 1 },
+          "modules": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+          "ports": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name", "port", "protocol"],
+              "properties": {
+                "name": { "type": "string", "minLength": 1 },
+                "port": { "type": "integer", "minimum": 1, "maximum": 65535 },
+                "protocol": { "enum": ["http", "https", "grpc", "tcp", "udp"] }
+              },
+              "additionalProperties": false
+            }
+          },
+          "contracts": {
+            "type": "object",
+            "required": ["owns", "apis", "publishes", "consumes", "dependsOn", "env"],
+            "properties": {
+              "owns": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+              "apis": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["name", "basePath"],
+                  "properties": {
+                    "name": { "type": "string", "minLength": 1 },
+                    "basePath": { "type": "string", "pattern": "^/" }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "publishes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+              "consumes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+              "dependsOn": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+              "env": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" }, "uniqueItems": true }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/workspace-context.v1.json

@@ -9,6 +9,7 @@
     "agent",
     "workspaceSummary",
     "modelRef",
+    "knowledgeGraph",
     "intelligenceChain",
     "workspace",
     "scope",
@@ -29,6 +30,25 @@
     },
     "workspaceSummary": { "type": "string" },
     "modelRef": { "type": "string" },
+    "knowledgeGraph": {
+      "type": "object",
+      "required": ["artifact", "schemaVersion", "available", "queryCommands"],
+      "properties": {
+        "artifact": { "const": ".workspai/reports/workspace-knowledge-graph.json" },
+        "schemaVersion": { "const": "workspace-knowledge-graph.v1" },
+        "available": { "type": "boolean" },
+        "entityCount": { "type": "integer", "minimum": 0 },
+        "relationCount": { "type": "integer", "minimum": 0 },
+        "proofCount": { "type": "integer", "minimum": 0 },
+        "queryCommands": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 3,
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
     "intelligenceChain": {
       "type": "object",
       "required": ["schemaVersion", "contractPath", "currentStep", "canonicalReadOrder"],