rapidkit 0.40.1 → 0.41.1

package/README.md

@@ -38,8 +38,8 @@ npx rapidkit my-workspace --yes --profile polyglot
 cd ~/rapidkit/workspaces/my-workspace
 
 npx rapidkit bootstrap --profile polyglot
-npx rapidkit create project
-npx rapidkit create frontend nextjs my-web --yes
+npx rapidkit create project nextjs my-web --yes
+npx rapidkit create project fastapi.standard my-api --yes
 
 npx rapidkit workspace model --json
 npx rapidkit workspace context --for-agent --json --write
@@ -162,8 +162,11 @@ For the visual experience, install the [Workspai VS Code extension](https://mark
 | What projects exist in this workspace?        | `workspace model --json`                       |
 | What context should AI agents receive?        | `workspace context --for-agent --json --write` |
 | What breaks if I change this?                 | `workspace impact --from <snapshot>`           |
+| Why is release blocked?                       | `workspace explain release-blocked --json --write` |
+| Trace a diff through blast radius and gates?  | `workspace trace --from .rapidkit/reports/workspace-model-diff-last-run.json --json --write` |
 | Can I safely release?                         | `pipeline --json --strict`                     |
 | How do I align AI tools and CI?               | `workspace agent-sync --write`                 |
+| Expose workspace evidence to MCP clients?     | `workspace mcp serve`                          |
 | How do I onboard an existing project?         | `adopt`                                        |
 | How do I bring repositories into a workspace? | `import`                                       |
 
@@ -242,11 +245,39 @@ Workspace Intelligence provides a shared understanding of projects, dependencies
 | `workspace snapshot --json`                       | Persist model snapshot                                                               |
 | `workspace diff --from <file\|git[:ref]> --json`  | Diff against snapshot or git                                                         |
 | `workspace impact --from <file> --json`           | Graph-aware transitive blast-radius evidence                                         |
-| `workspace verify [--strict] --json`              | Definitive verification gate (subgraph + freshness + policy)                         |
+| `workspace verify [--strict] --json`              | Definitive verification gate (subgraph + freshness + policy + fleet evidence)        |
+| `workspace explain <target> [--write] --json`     | Human narrative for release blockers, projects, or trace slices                      |
+| `workspace why <target>`                          | Alias of `workspace explain`                                                         |
+| `workspace trace --from <diff> [--write] --json`  | Diff → impact → gates narrative for agents and IDE handoff                           |
+| `workspace feedback record --json`                | Append structured agent action outcomes to intelligence history                      |
+| `workspace mcp serve`                             | Read-mostly stdio MCP bridge over workspace evidence                                 |
 | `workspace graph <emit\|explain\|dot\|mermaid>`   | Inspect and visualize the dependency graph                                           |
 | `workspace watch [--json] [--once]`               | Daemon mode: keep model + graph in memory, stream change events                      |
+| `workspace run <stage> [--scope project:X] [--reuse-passed]` | Fleet init/test/build/start or custom stages from `.rapidkit/context.json` |
 
-JSON schemas: `contracts/workspace-intelligence/`. Details: [commands-reference.md](docs/commands-reference.md).
+JSON schemas: `contracts/workspace-intelligence/`. Command coexistence and naming:
+[docs/contracts/NAMING_AND_COEXISTENCE.md](docs/contracts/NAMING_AND_COEXISTENCE.md).
+Details: [commands-reference.md](docs/commands-reference.md).
+
+### Operational intelligence (Phase 4)
+
+After model → diff → impact → verify, use **explain** and **trace** for
+human/agent narratives, **feedback** to record outcomes, and **MCP serve** for
+read-only tool access:
+
+```bash
+npx rapidkit workspace explain release-blocked --json --write
+npx rapidkit workspace trace --from .rapidkit/reports/workspace-model-diff-last-run.json --json --write
+npx rapidkit workspace feedback record --json
+npx rapidkit workspace mcp serve
+```
+
+Fleet runs support scoped execution and result reuse:
+
+```bash
+npx rapidkit workspace run test --scope project:api --reuse-passed --json
+npx rapidkit workspace run lint --scope project:api   # custom stage from context.json
+```
 
 ### Graph-aware intelligence engine
 
@@ -303,6 +334,9 @@ npm run check:agent-customization-drift -- --workspace <workspace-root>
 | Artifact / file                                                         | Purpose                                                  |
 | ----------------------------------------------------------------------- | -------------------------------------------------------- |
 | `.rapidkit/reports/agent-customization-pack.json`                       | Versioned output inventory, target matrix, drift state   |
+| `.rapidkit/reports/workspace-explain-last-run.json`                     | Unified explain / trace narrative for blockers and projects |
+| `.rapidkit/reports/workspace-skills-index.json`                        | Index of operational playbooks (`.rapidkit/skills/*.md`)      |
+| `.rapidkit/skills/rapidkit-*.md`                                       | Operational playbooks (generated by agent-sync)               |
 | `.rapidkit/reports/rapidkit-mcp-design.json`                            | Read-mostly MCP-ready tool design manifest               |
 | `.rapidkit/reports/INDEX.json`                                          | Read order, blockers, report timestamps                  |
 | `.rapidkit/reports/workspace-context-agent.json`                        | Canonical agent context pack                             |
@@ -379,13 +413,20 @@ cd ~/rapidkit/workspaces/my-workspace
 
 npx rapidkit bootstrap --profile polyglot
 npx rapidkit create project          # interactive kit picker
-npx rapidkit create frontend nextjs my-web --yes
+npx rapidkit create project nextjs my-web --yes
+npx rapidkit create project fastapi.standard my-api --yes
 cd <project-name> && npx rapidkit init && npx rapidkit dev
 ```
 
 Backend kits: `fastapi.standard`, `nestjs.standard`, `springboot.standard`, `gofiber.standard`, `dotnet.webapi.clean`, and more.
 
-Frontend: `create frontend nextjs|remix|vite-react|angular|astro|…` or `create project frontend.nextjs <name>`.
+Frontend kits: `nextjs`, `remix`, `vite-react`, `nuxt`, `angular`, `astro`, `sveltekit`, and more — same command shape:
+
+```bash
+npx rapidkit create project <kit> <name>
+```
+
+(`create frontend <id>` remains supported as an alias.)
 
 Shortcut: `npx rapidkit platform` (interactive workspace wizard).
 
@@ -450,7 +491,7 @@ Search **Workspai** in the marketplace or install via:
 | Enterprise evidence loop        | Partial                      | Full dashboard                  |
 | Module catalog (FastAPI/NestJS) | Limited                      | Browser UI                      |
 
-The extension invokes this npm CLI. For the latest `adopt` and `create frontend` features, install matching CLI version: `npm install -g rapidkit@latest` or `npm link` from this repo ([Development](#development)).
+The extension invokes this npm CLI. For the latest `adopt` and frontend generator features, install matching CLI version: `npm install -g rapidkit@latest` or `npm link` from this repo ([Development](#development)).
 
 ## Documentation
 

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

@@ -19,7 +19,8 @@
         ".github/prompts/rapidkit-diagnose.prompt.md",
         ".github/skills/rapidkit-workspace-intelligence/SKILL.md",
         ".github/agents/workspai-advisor.agent.md",
-        ".rapidkit/reports/rapidkit-mcp-design.json"
+        ".rapidkit/reports/rapidkit-mcp-design.json",
+        ".rapidkit/reports/workspace-skills-index.json"
       ]
     }
   },
@@ -99,6 +100,11 @@
       "label": "Agent context pack",
       "required": true
     },
+    {
+      "path": ".rapidkit/reports/workspace-skills-index.json",
+      "label": "Operational skills index",
+      "required": true
+    },
     {
       "path": ".rapidkit/reports/workspace-model.json",
       "label": "Workspace model graph",
@@ -133,6 +139,31 @@
       "path": ".rapidkit/reports/workspace-verify-last-run.json",
       "label": "Workspace verify",
       "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-model-snapshot.json",
+      "label": "Workspace model snapshot",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-model-diff-last-run.json",
+      "label": "Workspace model diff",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-explain-last-run.json",
+      "label": "Workspace explain",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-contract-verify-last-run.json",
+      "label": "Workspace contract verify",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-intelligence-history.json",
+      "label": "Workspace intelligence history",
+      "required": false
     }
   ],
   "strictRules": [
@@ -151,9 +182,28 @@
     "prompt",
     "skill",
     "skill-resource",
+    "operational-skill",
+    "skills-index",
+    "explain-report",
     "agent",
     "rule",
     "hook",
     "mcp-design"
-  ]
+  ],
+  "pathLayers": {
+    "l1CanonicalRoots": [
+      ".rapidkit/reports/",
+      ".rapidkit/skills/"
+    ],
+    "l2PrefixedMirrorRoots": [
+      ".github/",
+      ".cursor/",
+      ".claude/"
+    ],
+    "l3SharedIndustryFiles": [
+      "AGENTS.md",
+      ".github/copilot-instructions.md",
+      "CLAUDE.md"
+    ]
+  }
 }

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

@@ -1,10 +1,22 @@
 {
   "schemaVersion": "rapidkit-extension-cli-compatibility.v1",
   "cli": "rapidkit-npm",
-  "minimumVerifiedCliVersion": "0.40.1",
+  "minimumVerifiedCliVersion": "0.41.1",
   "publishedContractSchemas": {
     "runtimeCommandSurface": "rapidkit-runtime-command-surface-v1",
     "cliLogEvent": "cli-log-event-v1",
-    "freshnessMetadata": "rapidkit-freshness-metadata-v1"
+    "freshnessMetadata": "rapidkit-freshness-metadata-v1",
+    "blockerResolution": "rapidkit-blocker-resolution-v1",
+    "workspaceModel": "workspace-model.v1",
+    "workspaceImpact": "workspace-impact.v1",
+    "workspaceVerify": "workspace-verify.v1",
+    "workspaceContext": "workspace-context.v1",
+    "workspaceDependencyGraph": "workspace-dependency-graph.v1",
+    "workspaceIntelligenceHistory": "workspace-intelligence-history.v1",
+    "agentCustomizationPack": "rapidkit-agent-customization-pack.v1",
+    "workspaceOperationalSkill": "workspace-operational-skill.v1",
+    "workspaceSkillsIndex": "workspace-skills-index.v1",
+    "workspaceExplain": "workspace-explain.v1",
+    "agentActionOutcome": "agent-action-outcome.v1"
   }
 }

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

@@ -53,6 +53,11 @@
     "watch",
     "context",
     "agent-sync",
+    "explain",
+    "why",
+    "trace",
+    "feedback",
+    "mcp",
     "policy",
     "contract",
     "share",
@@ -70,7 +75,8 @@
     "impact",
     "verify",
     "context",
-    "agent-sync"
+    "agent-sync",
+    "explain"
   ],
   "moduleSuggestionFrameworks": [
     "fastapi",

package/contracts/workspace-intelligence/agent-action-outcome.v1.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/agent-action-outcome.v1.json",
+  "title": "RapidKit Agent Action Outcome",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "actionId", "scope", "summary", "outcome"],
+  "properties": {
+    "schemaVersion": { "const": "agent-action-outcome.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "actionId": { "type": "string", "minLength": 1 },
+    "scope": { "type": "string" },
+    "summary": { "type": "string" },
+    "outcome": { "enum": ["ok", "failed"] },
+    "affectedFiles": { "type": "array", "items": { "type": "string" } },
+    "commandsRun": { "type": "array", "items": { "type": "string" } },
+    "verifyBefore": { "type": "string" },
+    "verifyAfter": { "type": "string" },
+    "evidenceSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "evidencePath": { "type": "string" },
+    "patchMetadata": {
+      "type": "object",
+      "required": ["appliedCount", "rejectedCount", "failedCount", "affectedFiles"],
+      "properties": {
+        "patchId": { "type": "string" },
+        "sourceAction": { "enum": ["auto-fix", "apply-patch"] },
+        "reviewRequired": { "type": "boolean" },
+        "branchCreated": { "type": "string" },
+        "appliedCount": { "type": "integer", "minimum": 0 },
+        "rejectedCount": { "type": "integer", "minimum": 0 },
+        "failedCount": { "type": "integer", "minimum": 0 },
+        "affectedFiles": { "type": "array", "items": { "type": "string" } },
+        "rollbackCommand": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/blocker-resolution.v1.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/blocker-resolution.v1.json",
+  "title": "RapidKit Blocker Resolution Hint",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "blockerId",
+    "resolutionClass",
+    "blockerSignature",
+    "fixHints"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "rapidkit-blocker-resolution-v1"
+    },
+    "blockerId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "sourceCommand": {
+      "type": "string"
+    },
+    "sourceArtifact": {
+      "type": "string"
+    },
+    "resolutionClass": {
+      "enum": [
+        "artifact-missing",
+        "command-failed-repeat",
+        "config-fixable",
+        "semantic-attention",
+        "unresolvable-without-human"
+      ]
+    },
+    "blockerSignature": {
+      "type": "string",
+      "minLength": 8
+    },
+    "commandRetryHint": {
+      "type": "string"
+    },
+    "fixHints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["actionKind", "detail"],
+        "properties": {
+          "actionKind": {
+            "enum": ["edit-file", "run-once", "commit-files", "refresh-baseline"]
+          },
+          "targetPath": { "type": "string" },
+          "detail": { "type": "string" },
+          "studioActionId": {
+            "enum": ["fix-lens", "verify-gates", "run-analyze", "doctor-fix"]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "verifyCommand": { "type": "string" },
+    "verifyArtifact": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/doctor-fix-result.v1.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "rapidkit-doctor-fix-result-v1",
+  "title": "Doctor fix execution result",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schemaVersion", "appliedFixes", "remainingBlockers", "verifyRecommended"],
+  "properties": {
+    "schemaVersion": {
+      "const": "rapidkit-doctor-fix-result-v1"
+    },
+    "appliedFixes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "action", "outcome"],
+        "properties": {
+          "path": { "type": "string" },
+          "action": { "type": "string" },
+          "outcome": {
+            "enum": ["applied", "failed", "skipped", "guidance"]
+          }
+        }
+      }
+    },
+    "remainingBlockers": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "verifyRecommended": {
+      "type": "string"
+    }
+  }
+}

package/contracts/workspace-intelligence/studio-blocker-handoff.v1.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/studio-blocker-handoff.v1.json",
+  "title": "Workspai Studio Blocker Handoff",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "cardId",
+    "cardStatus",
+    "blockers",
+    "artifactPath",
+    "sourceCommand",
+    "scope"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "rapidkit-studio-blocker-handoff-v1"
+    },
+    "cardId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "cardLabel": {
+      "type": "string"
+    },
+    "cardStatus": {
+      "enum": ["pass", "warn", "fail", "missing"]
+    },
+    "blockers": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "artifactPath": {
+      "type": "string"
+    },
+    "sourceCommand": {
+      "type": "string"
+    },
+    "scope": {
+      "enum": ["workspace", "project"]
+    },
+    "stderrTail": {
+      "type": "string"
+    },
+    "exitCode": {
+      "type": ["integer", "null"]
+    },
+    "blockerSignature": {
+      "type": "string",
+      "minLength": 8
+    },
+    "commandRunCount": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "resolutionClass": {
+      "enum": [
+        "artifact-missing",
+        "command-failed-repeat",
+        "config-fixable",
+        "semantic-attention",
+        "unresolvable-without-human"
+      ]
+    },
+    "studioMode": {
+      "enum": ["FIX", "RUN_ONCE", "VERIFY_ONLY", "EXPLAIN"]
+    },
+    "resolutionHints": {
+      "type": "array",
+      "items": {
+        "$ref": "blocker-resolution.v1.json"
+      }
+    },
+    "verifyCommand": {
+      "type": "string"
+    },
+    "verifyArtifact": {
+      "type": "string"
+    },
+    "handoffSource": {
+      "enum": ["repair", "artifacts", "advisor", "tree", "dashboard"]
+    },
+    "workspacePath": {
+      "type": "string"
+    },
+    "projectPath": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/workspace-contract-verify.v1.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "workspace-contract-verify.v1",
+  "title": "Workspace contract verify evidence",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "status",
+    "contractPath",
+    "projectCount",
+    "checks",
+    "violations"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "workspace-contract-verify.v1"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "status": {
+      "enum": ["passed", "failed"]
+    },
+    "contractPath": {
+      "type": "string"
+    },
+    "projectCount": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "status", "message"],
+        "properties": {
+          "id": { "type": "string" },
+          "status": { "enum": ["passed", "failed"] },
+          "message": { "type": "string" }
+        }
+      }
+    },
+    "violations": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/contracts/workspace-intelligence/workspace-dependency-graph.v1.json

@@ -23,7 +23,33 @@
           "path": { "type": "string", "minLength": 1 },
           "runtime": { "type": "string" },
           "framework": { "type": "string" },
-          "kind": { "type": "string" }
+          "kind": { "type": "string" },
+          "operationalProfile": {
+            "type": "object",
+            "required": ["weight", "score", "verificationPriority", "reasons", "centrality"],
+            "properties": {
+              "weight": { "enum": ["low", "medium", "high", "critical"] },
+              "score": { "type": "integer", "minimum": 0, "maximum": 100 },
+              "verificationPriority": { "enum": ["normal", "elevated", "strict"] },
+              "reasons": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "centrality": {
+                "type": "object",
+                "required": ["fanIn", "fanOut", "reach", "betweenness", "isHotspot"],
+                "properties": {
+                  "fanIn": { "type": "integer", "minimum": 0 },
+                  "fanOut": { "type": "integer", "minimum": 0 },
+                  "reach": { "type": "integer", "minimum": 0 },
+                  "betweenness": { "type": "number", "minimum": 0 },
+                  "isHotspot": { "type": "boolean" }
+                },
+                "additionalProperties": true
+              }
+            },
+            "additionalProperties": true
+          }
         },
         "additionalProperties": true
       }
@@ -75,6 +101,14 @@
         "inferredEdges",
         "contractEdges",
         "manualEdges",
+        "authoritativeEdges",
+        "lowConfidenceEdges",
+        "orphanCount",
+        "connectedNodeCount",
+        "density",
+        "edgeCoverageRatio",
+        "evidenceCoverageRatio",
+        "hotspotCount",
         "hasCycle"
       ],
       "properties": {
@@ -83,9 +117,35 @@
         "inferredEdges": { "type": "integer", "minimum": 0 },
         "contractEdges": { "type": "integer", "minimum": 0 },
         "manualEdges": { "type": "integer", "minimum": 0 },
+        "authoritativeEdges": { "type": "integer", "minimum": 0 },
+        "lowConfidenceEdges": { "type": "integer", "minimum": 0 },
+        "orphanCount": { "type": "integer", "minimum": 0 },
+        "connectedNodeCount": { "type": "integer", "minimum": 0 },
+        "density": { "type": "number", "minimum": 0 },
+        "edgeCoverageRatio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "evidenceCoverageRatio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "hotspotCount": { "type": "integer", "minimum": 0 },
         "hasCycle": { "type": "boolean" }
       },
       "additionalProperties": true
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["code", "severity", "message"],
+        "properties": {
+          "code": { "type": "string", "minLength": 1 },
+          "severity": { "enum": ["info", "warning", "error"] },
+          "message": { "type": "string", "minLength": 1 },
+          "recommendation": { "type": "string" },
+          "nodeIds": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          }
+        },
+        "additionalProperties": true
+      }
     }
   },
   "additionalProperties": true

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

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-explain.v1.json",
+  "title": "RapidKit Workspace Explain Report",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "workspacePath", "target", "summary", "sections"],
+  "properties": {
+    "schemaVersion": { "const": "workspace-explain.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "workspacePath": { "type": "string" },
+    "target": { "type": "object", "additionalProperties": true },
+    "summary": { "type": "string" },
+    "sections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "body"],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "body": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "releaseRisk": { "type": "string" },
+    "blockingReasons": { "type": "array", "items": { "type": "string" } },
+    "resolutionHints": { "type": "array", "items": { "type": "object" } }
+  },
+  "additionalProperties": false
+}