workspai 0.63.0 → 0.65.0

package/README.md

@@ -18,28 +18,28 @@ npx workspai adopt .
 npx workspai workspace intelligence run --for-agent generic
 ```
 
-Two commands. Your project becomes a fully understood workspace:
+Two commands. Your project gains a bounded, evidence-backed system view:
 
 ### Before vs After
 
 | Before Workspai | After Workspai |
 | --- | --- |
-| Agent scans thousands of files for context | Agent reads one bounded context document |
+| Agent scans thousands of files for context | Agent starts from bounded entry and context artifacts |
 | No dependency map between services | Searchable graph with source-level proof |
-| Broken test blocks release, no one knows why | Doctor names the failing project and fix path |
+| Broken test blocks release, no one knows why | Doctor localizes the blocker and next target |
 | Every AI session starts from scratch | Sessions resume from durable evidence |
 
 Here is what you get:
 
 | What it produces | Why it matters |
 | --- | --- |
-| **Workspace Model** | A canonical inventory of every project, runtime, framework, and dependency |
+| **Workspace Model** | A canonical inventory of registered projects, detected runtimes, frameworks, and proven dependencies |
 | **Knowledge Graph** | Searchable relationships between projects, backed by source-level proof |
 | **Health & Readiness** | Doctor checks, verification gates, and release posture based on evidence, not guesses |
 | **Agent Context** | Bounded, focused instructions so AI tools read what they need, not the entire repo |
 | **Agent Rules** | Ready-to-use grounding for Cursor, Copilot, Claude, Codex, Gemini, and more |
 | **Agent Skills** | Runtime-, polyglot-, test-, and delivery-aware operational playbooks, with portable `SKILL.md` projections where the host supports Agent Skills |
-| **MCP Server** | 14 read-oriented tools so MCP clients can query evidence, graph, blockers, and context live |
+| **MCP Server** | Versioned read-oriented tools for querying evidence, graph, blockers, and context live |
 
 `generic` is the safe default when you do not yet know which agent will use the
 project: Workspai builds one portable context and prepares discovery adapters
@@ -47,46 +47,28 @@ for every supported host, without duplicating the Model or Graph.
 
 ### What the output looks like
 
-After a single run, `.workspai/` contains everything agents and CI need:
+After a single run, the canonical workspace stores governed artifacts under
+`.workspai/`. Each linked project keeps only its local entry contract, scoped
+lens, and workspace binding under its own `.workspai/` directory:
 
 ```text
-your-workspace/                              # ── Workspace level ──
+your-workspace/                         # canonical system boundary
 ├── .workspai/
-│   ├── workspace.json                       # workspace identity & profile
-│   ├── workspace.contract.json              # project registry, ports, APIs
-│   ├── reports/                             # intelligence artifacts
-│   │   ├── workspace-model.json             # projects, runtimes, deps
-│   │   ├── workspace-knowledge-graph.json   # proof-backed relationships
-│   │   ├── workspace-context-agent.json     # bounded context for AI agents
-│   │   ├── workspace-skills-index.json      # operational skills inventory
-│   │   ├── workspace-verify-last-run.json   # pass/fail with evidence
-│   │   ├── INDEX.json                       # evidence inventory & read order
-│   │   └── ...                              # impact, doctor, analyze, explain, etc.
-│   └── skills/                              # generated operational skills
-│       ├── workspai-release-readiness.md     # always available
-│       ├── workspai-node-runtime-validation.md  # only when Node is detected
-│       └── workspai-polyglot-change-validation.md # only for multi-runtime workspaces
-│
-│  # Workspace-level agent grounding (per host):
+│   ├── workspace.contract.json         # registered projects and declarations
+│   ├── reports/
+│   │   ├── workspace-model.json        # canonical system model
+│   │   ├── workspace-knowledge-graph.json # derived proof-backed graph
+│   │   ├── workspace-context-agent.json   # bounded consumer context
+│   │   └── INDEX.json                  # evidence inventory and read order
+│   └── skills/                         # detected operational playbooks
 ├── AGENTS.md · CLAUDE.md · GEMINI.md · QWEN.md
-├── .cursor/rules/workspai-*.mdc             # 5 rules + skill
-├── .claude/rules/workspai-*.md              # workspace + evidence
-├── .grok/rules/ · .windsurf/rules/          # grounding + evidence
-├── .amazonq/rules/ · .github/               # Copilot, prompts, agents, skills
-│
-│  # ── Project level (repeated per project) ──
+├── .cursor/ · .claude/ · .github/ · .agents/ # host-native projections
 ├── nova-api/
-│   ├── .workspai/
-│   │   ├── project.json                     # project identity & metadata
-│   │   ├── workspace-link.local.json        # machine-local workspace binding
-│   │   ├── agent-entry.v1.json              # canonical agent entry point
-│   │   ├── PROJECT-GROUNDING.md             # project-level grounding
-│   │   └── reports/
-│   │       └── project-context-agent.json   # scoped project context
-│   ├── AGENTS.md · CLAUDE.md · GEMINI.md · QWEN.md
-│   └── .amazonq/rules/workspai-agent-entry.md
-│
-└── summit-web/                              # (same structure per project)
+│   └── .workspai/
+│       ├── agent-entry.v1.json         # canonical project entry
+│       ├── workspace-link.local.json   # machine-local binding
+│       └── reports/project-context-agent.json
+└── summit-web/                         # same project-level boundary
 ```
 
 Your agent starts with `agent-entry.v1.json`, compact workspace context, and the Skills
@@ -105,8 +87,8 @@ scan or complete Graph load is needed for ordinary work.
 Workspai is an open-source CLI that brings related software projects together,
 so people and AI tools can understand and work with the same system.
 
-- **See the whole system:** every project, service, and dependency in one model.
-- **Ask with proof:** trace any answer back to the exact file and line.
+- **See the whole system:** registered projects and proven relationships in one model.
+- **Ask with proof:** trace answers back to their evidence record and source location.
 - **Change safely:** know impact before you commit, verify after, and give AI agents
   only the context they need.
 
@@ -202,7 +184,7 @@ generated in one run. The key files for each audience:
 | **AI agent** | `agent-entry.v1.json` (project) → `workspace-context-agent.json` (workspace) |
 | **Developer** | Terminal summary, or `workspace-explain-last-run.json` for diagnosis |
 | **CI / automation** | `workspace-verify-last-run.json` (exit code 0 = pass, 2 = blocked) |
-| **MCP client** | `workspace mcp serve` (14 read-oriented tools over JSON-RPC) |
+| **MCP client** | `workspace mcp serve` (versioned read-oriented tools over JSON-RPC) |
 | **IDE extension** | Same artifacts + watch events |
 
 An agent can prove that it entered through governed evidence before scanning
@@ -264,6 +246,17 @@ complements this chain; it does not replace it.
 
 The deterministic model, graph, and checks do not require an AI API key.
 
+### See the evidence-backed graph
+
+The graph connects projects, APIs, packages, tests, infrastructure, ownership,
+and runtime topology only when current evidence supports the relationship.
+Every visible relationship can retain proof, while missing relationships stay
+explicitly unproven.
+
+![Interactive 3D view of a real Workspai workspace graph](https://raw.githubusercontent.com/chistiq/workspai/main/packages/cli/docs/workspace-graph.gif)
+
+[Query, explain, and export the graph](docs/workspace-knowledge-graph.md)
+
 ## Everyday workflows
 
 | Goal                                       | Command                                                                          |
@@ -294,7 +287,7 @@ Workspai exposes the same governed data through several stable surfaces:
 - JSON output for scripts and CI;
 - versioned artifacts under `.workspai/reports/`;
 - focused context and instructions for AI agents;
-- MCP server with 14 read-oriented workspace tools (`workspace mcp serve`);
+- MCP server with versioned read-oriented workspace tools (`workspace mcp serve`);
 - watch events and reports for IDEs and dashboards;
 - JSON, JSON-LD, Mermaid, DOT, GraphML, and GEXF graph exports.
 

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

@@ -1473,6 +1473,10 @@
           "flags": "--limit <count>",
           "attributeName": "limit"
         },
+        {
+          "flags": "--kind <kind>",
+          "attributeName": "kind"
+        },
         {
           "flags": "--refresh-graph",
           "attributeName": "refreshGraph"

package/contracts/create-planner-capabilities.v1.json

@@ -19,81 +19,97 @@
       "id": "fastapi.standard",
       "runtime": "python",
       "framework": "fastapi",
+      "plannerFramework": "fastapi",
       "category": "backend",
       "owner": "core",
       "stability": "stable",
       "versionPolicy": "tested-baseline",
-      "moduleSupport": true
+      "moduleSupport": true,
+      "workspacePythonEngine": "required"
     },
     {
       "id": "fastapi.ddd",
       "runtime": "python",
       "framework": "fastapi",
+      "plannerFramework": "fastapi",
       "category": "backend",
       "owner": "core",
       "stability": "stable",
       "versionPolicy": "tested-baseline",
-      "moduleSupport": true
+      "moduleSupport": true,
+      "workspacePythonEngine": "required"
     },
     {
       "id": "nestjs.standard",
       "runtime": "node",
       "framework": "nestjs",
+      "plannerFramework": "nestjs",
       "category": "backend",
       "owner": "core",
       "stability": "stable",
       "versionPolicy": "tested-baseline",
-      "moduleSupport": true
+      "moduleSupport": true,
+      "workspacePythonEngine": "optional"
     },
     {
       "id": "springboot.standard",
       "runtime": "java",
       "framework": "springboot",
+      "plannerFramework": "springboot",
       "category": "backend",
       "owner": "npm",
       "stability": "stable",
       "versionPolicy": "tested-baseline",
-      "moduleSupport": false
+      "moduleSupport": false,
+      "workspacePythonEngine": "none"
     },
     {
       "id": "gofiber.standard",
       "runtime": "go",
       "framework": "gofiber",
+      "plannerFramework": "go",
       "category": "backend",
       "owner": "npm",
       "stability": "stable",
       "versionPolicy": "tested-baseline",
-      "moduleSupport": false
+      "moduleSupport": false,
+      "workspacePythonEngine": "none"
     },
     {
       "id": "gogin.standard",
       "runtime": "go",
       "framework": "gogin",
+      "plannerFramework": "go",
       "category": "backend",
       "owner": "npm",
       "stability": "stable",
       "versionPolicy": "tested-baseline",
-      "moduleSupport": false
+      "moduleSupport": false,
+      "workspacePythonEngine": "none"
     },
     {
       "id": "dotnet.webapi.clean",
       "runtime": "dotnet",
       "framework": "dotnet",
+      "plannerFramework": "dotnet",
       "category": "backend",
       "owner": "npm",
       "stability": "preview",
       "versionPolicy": "tested-baseline",
-      "moduleSupport": false
+      "moduleSupport": false,
+      "workspacePythonEngine": "none"
     },
     {
       "id": "rust.axum",
       "runtime": "rust",
       "framework": "axum",
+      "plannerFramework": "rust",
       "category": "backend",
       "owner": "npm",
       "stability": "preview",
       "versionPolicy": "tested-baseline",
-      "moduleSupport": false
+      "moduleSupport": false,
+      "workspacePythonEngine": "none"
     }
   ],
   "officialCreate": [
@@ -106,6 +122,12 @@
         "next.js"
       ],
       "ecosystem": "nextjs",
+      "plannerFramework": "nextjs",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -124,6 +146,12 @@
         "react-router"
       ],
       "ecosystem": "remix",
+      "plannerFramework": "remix",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -145,6 +173,12 @@
         "vite.react"
       ],
       "ecosystem": "react",
+      "plannerFramework": "vite-react",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -163,6 +197,12 @@
         "vite.vue"
       ],
       "ecosystem": "vue",
+      "plannerFramework": "vite-vue",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -181,6 +221,12 @@
         "vite.svelte"
       ],
       "ecosystem": "svelte",
+      "plannerFramework": "vite-svelte",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -200,6 +246,12 @@
         "vite.solid"
       ],
       "ecosystem": "solid",
+      "plannerFramework": "vite-solid",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -218,6 +270,12 @@
         "vite-vanilla"
       ],
       "ecosystem": "vite",
+      "plannerFramework": "vite-vanilla",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -236,6 +294,12 @@
         "nuxt.js"
       ],
       "ecosystem": "nuxt",
+      "plannerFramework": "nuxt",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -253,6 +317,12 @@
         "ng"
       ],
       "ecosystem": "angular",
+      "plannerFramework": "angular",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -272,6 +342,12 @@
         "astro"
       ],
       "ecosystem": "astro",
+      "plannerFramework": "astro",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -289,6 +365,12 @@
         "svelte-kit"
       ],
       "ecosystem": "sveltekit",
+      "plannerFramework": "sveltekit",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -306,6 +388,13 @@
         "tauri-app"
       ],
       "ecosystem": "tauri",
+      "plannerFramework": "tauri",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node",
+        "rust"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -323,6 +412,12 @@
         "electron-forge"
       ],
       "ecosystem": "electron",
+      "plannerFramework": "electron",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -341,6 +436,12 @@
         "visual-studio-code-extension"
       ],
       "ecosystem": "vscode-extension",
+      "plannerFramework": "vscode-extension",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -361,6 +462,13 @@
         "php-laravel"
       ],
       "ecosystem": "laravel",
+      "plannerFramework": "laravel",
+      "runtime": "php",
+      "runtimeCandidates": [
+        "php",
+        "node"
+      ],
+      "workspacePythonEngine": "none",
       "status": "available",
       "canExecuteCreate": true,
       "versionPolicy": "latest-stable",
@@ -379,6 +487,12 @@
         "wp-site"
       ],
       "ecosystem": "wordpress",
+      "plannerFramework": "wordpress",
+      "runtime": "php",
+      "runtimeCandidates": [
+        "php"
+      ],
+      "workspacePythonEngine": "none",
       "status": "planned",
       "canExecuteCreate": false,
       "versionPolicy": "planned",
@@ -399,6 +513,13 @@
         "gutenberg-block"
       ],
       "ecosystem": "wordpress",
+      "plannerFramework": "wordpress",
+      "runtime": "node",
+      "runtimeCandidates": [
+        "node",
+        "php"
+      ],
+      "workspacePythonEngine": "none",
       "status": "planned",
       "canExecuteCreate": false,
       "versionPolicy": "planned",
@@ -415,6 +536,12 @@
         "php-symfony"
       ],
       "ecosystem": "php",
+      "plannerFramework": "symfony",
+      "runtime": "php",
+      "runtimeCandidates": [
+        "php"
+      ],
+      "workspacePythonEngine": "none",
       "status": "planned",
       "canExecuteCreate": false,
       "versionPolicy": "planned",
@@ -432,6 +559,12 @@
         "ruby-rails"
       ],
       "ecosystem": "ruby",
+      "plannerFramework": "rails",
+      "runtime": "ruby",
+      "runtimeCandidates": [
+        "ruby"
+      ],
+      "workspacePythonEngine": "none",
       "status": "planned",
       "canExecuteCreate": false,
       "versionPolicy": "planned",
@@ -451,6 +584,116 @@
     "scala",
     "kotlin"
   ],
+  "workspaceProfiles": [
+    {
+      "id": "minimal",
+      "runtimePolicy": "single-detected",
+      "runtimeFamilies": [],
+      "setupRuntimeFamilies": [],
+      "pythonEngineAtCreate": "skipped",
+      "pythonEngineAtBootstrap": "on-demand"
+    },
+    {
+      "id": "python-only",
+      "runtimePolicy": "bounded",
+      "runtimeFamilies": [
+        "python"
+      ],
+      "setupRuntimeFamilies": [
+        "python"
+      ],
+      "pythonEngineAtCreate": "optional-default-install",
+      "pythonEngineAtBootstrap": "on-demand"
+    },
+    {
+      "id": "node-only",
+      "runtimePolicy": "bounded",
+      "runtimeFamilies": [
+        "node"
+      ],
+      "setupRuntimeFamilies": [
+        "node"
+      ],
+      "pythonEngineAtCreate": "skipped",
+      "pythonEngineAtBootstrap": "disabled"
+    },
+    {
+      "id": "go-only",
+      "runtimePolicy": "bounded",
+      "runtimeFamilies": [
+        "go"
+      ],
+      "setupRuntimeFamilies": [
+        "go"
+      ],
+      "pythonEngineAtCreate": "skipped",
+      "pythonEngineAtBootstrap": "disabled"
+    },
+    {
+      "id": "java-only",
+      "runtimePolicy": "bounded",
+      "runtimeFamilies": [
+        "java"
+      ],
+      "setupRuntimeFamilies": [
+        "java"
+      ],
+      "pythonEngineAtCreate": "skipped",
+      "pythonEngineAtBootstrap": "disabled"
+    },
+    {
+      "id": "dotnet-only",
+      "runtimePolicy": "bounded",
+      "runtimeFamilies": [
+        "dotnet"
+      ],
+      "setupRuntimeFamilies": [
+        "dotnet"
+      ],
+      "pythonEngineAtCreate": "skipped",
+      "pythonEngineAtBootstrap": "disabled"
+    },
+    {
+      "id": "polyglot",
+      "runtimePolicy": "multi-runtime",
+      "runtimeFamilies": [],
+      "setupRuntimeFamilies": [
+        "python",
+        "node",
+        "go",
+        "java",
+        "dotnet"
+      ],
+      "pythonEngineAtCreate": "optional-default-install",
+      "pythonEngineAtBootstrap": "on-demand"
+    },
+    {
+      "id": "enterprise",
+      "runtimePolicy": "multi-runtime",
+      "runtimeFamilies": [],
+      "setupRuntimeFamilies": [
+        "python",
+        "node",
+        "go",
+        "java",
+        "dotnet"
+      ],
+      "pythonEngineAtCreate": "optional-default-install",
+      "pythonEngineAtBootstrap": "on-demand"
+    }
+  ],
+  "lifecycle": {
+    "automatic": [
+      "Create the workspace foundation without installing an optional workspace Python engine unless the user explicitly selected that engine in CLI workspace creation.",
+      "Run the selected native or official project generator and let that generator own project dependency installation unless --skip-install is set.",
+      "Register every created project and refresh the canonical contract, model, proof-backed graph, diff, impact, agent context, grounding, and evidence index."
+    ],
+    "explicit": [
+      "Run workspai bootstrap only when the user requests profile and project dependency initialization or a required kit reports a missing workspace engine.",
+      "Run workspai workspace intelligence run --for-agent <agent> --strict for a complete evidence and verification loop.",
+      "Run doctor, analyze, readiness, verify, run, Goal, and repair operations when requested by the user or the governed workflow; Create does not silently claim those gates passed."
+    ]
+  },
   "productRules": [
     "Do not translate unsupported stack requests into unrelated native kits.",
     "If native create is unavailable, explain the lane and guide to adopt/import.",

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

@@ -2694,6 +2694,10 @@
           "flag": "--limit",
           "description": "Bound graph query results (1–100)."
         },
+        {
+          "flag": "--kind",
+          "description": "Limit graph entity search to one canonical entity kind."
+        },
         {
           "flag": "--refresh-graph",
           "description": "Bypass the compatible persisted graph and rebuild from live sources."
@@ -2732,7 +2736,7 @@
       ],
       "artifact": null,
       "examples": [
-        "workspai workspace graph search \"authentication endpoint\" --limit 12 --json",
+        "workspai workspace graph search \"authentication endpoint\" --kind endpoint --limit 12 --json",
         "workspai workspace graph evidence \"GET /users\" --json",
         "workspai workspace graph mermaid"
       ]
@@ -4133,6 +4137,13 @@
       "moduleCommands": false,
       "doctor": "observed",
       "lifecycleCommands": [
+        "init",
+        "dev",
+        "start",
+        "build",
+        "test",
+        "lint",
+        "format",
         "help"
       ]
     },