workspai 0.45.0 → 0.47.0

package/docs/workspace-knowledge-graph.md

@@ -0,0 +1,295 @@
+# Workspace Knowledge Graph
+
+Most code graphs answer questions about one repository. Workspai connects code,
+APIs, infrastructure, delivery, documentation, ownership, tests, and runtime
+configuration across a whole workspace—and records why every relationship is
+believed.
+
+The graph is local-first and deterministic. Building it does not require an
+LLM, a hosted service, embeddings, or a graph database.
+
+## Why this is useful
+
+A repository graph can tell you that function A calls function B. A workspace
+question is usually wider:
+
+> If we change this endpoint, which project consumes it, which deployment ships
+> it, which tests cover it, which document describes it, and which release gate
+> can stop it?
+
+Workspai keeps those domains in one proof-carrying representation. The graph is
+not the final product screen; it is the shared knowledge layer behind impact,
+verification, context, MCP, IDE, CI, and agent workflows.
+
+| If you are…          | The graph helps you…                                                                       |
+| -------------------- | ------------------------------------------------------------------------------------------ |
+| A developer          | find the implementation, nearby dependencies, tests, and evidence without repo-wide search |
+| A tech lead          | inspect cross-project boundaries, owners, contracts, and change paths                      |
+| An AI coding agent   | retrieve question-sized context and verify every returned claim                            |
+| A CI/release system  | consume versioned JSON, source hashes, quality diagnostics, and deterministic exits        |
+| An IDE or MCP client | offer the same system understanding without rebuilding a private index                     |
+
+## What makes it a workspace graph
+
+Workspai does not stop at files, imports, functions, and classes. Repository
+structure is one provider domain alongside APIs, containers, infrastructure,
+pipelines, documents, decisions, ownership, tests, environments, and authored
+workspace contracts.
+
+That distinction matters when the answer crosses repositories. The canonical
+Workspace Model remains the source of truth; the Knowledge Graph is its rich,
+queryable, evidence-backed representation. AI is a consumer, never a requirement
+for building the graph.
+
+## Try it in two minutes
+
+Run from a Workspai workspace:
+
+```bash
+npx workspai workspace model --write --json
+npx workspai workspace graph search "authentication endpoint" --limit 12 --json
+```
+
+Useful follow-up questions:
+
+```bash
+# What APIs and endpoints exist?
+npx workspai workspace graph entities endpoint --json
+
+# Why does Workspai believe this entity exists?
+npx workspai workspace graph evidence "GET /users" --json
+
+# How are two services, files, or APIs connected?
+npx workspai workspace graph path frontend-api "GET /users" --json
+
+# What changed since a saved graph revision?
+npx workspai workspace graph overlay --from previous-graph.json --json
+```
+
+For agents and MCP clients, prefer bounded search over loading the complete
+graph:
+
+```bash
+npx workspai workspace graph search "billing database" --limit 12 --json
+```
+
+A simplified response looks like this:
+
+```json
+{
+  "schemaVersion": "workspace-knowledge-search.v1",
+  "query": "billing database",
+  "totalMatches": 23,
+  "truncated": true,
+  "entities": [{ "kind": "database", "label": "billing-db", "proofIds": ["proof:..."] }],
+  "relations": [{ "kind": "reads-from", "from": "service:billing", "to": "database:billing-db" }],
+  "proofs": [{ "provider": "compose", "artifact": "infra/compose.yml", "trust": "authoritative" }]
+}
+```
+
+The response is intentionally bounded. `totalMatches` tells the consumer more
+results exist, `truncated` prevents silent omission, and every returned claim can
+be traced through `proofIds`.
+
+## Pick the command by question
+
+| You want to know…                                    | Use                                                    |
+| ---------------------------------------------------- | ------------------------------------------------------ |
+| What is relevant to a natural-language question?     | `workspace graph search <query> --limit <n> --json`    |
+| Which entities of one type exist?                    | `workspace graph entities <kind> --json`               |
+| Why does Workspai believe an item exists?            | `workspace graph evidence <entity-or-relation> --json` |
+| How are two things connected?                        | `workspace graph path <from> <to> --json`              |
+| What changed between graph revisions?                | `workspace graph overlay --from <graph.json> --json`   |
+| What is the full portable graph?                     | `workspace graph emit --json`                          |
+| How much retrieval payload did one query avoid?      | `workspace graph benchmark <query> --limit <n> --json` |
+| How should an MCP-compatible agent retrieve context? | `workspace mcp serve` → `searchWorkspaceGraph`         |
+
+## What it models
+
+The current graph can represent:
+
+- workspaces, projects, services, packages, modules, files, and symbols;
+- APIs, endpoints, schemas, events, queues, and databases;
+- containers, deployments, environments, pipelines, and infrastructure;
+- documentation, architecture decisions, tests, and owners.
+
+Relations include `contains`, `imports`, `depends-on`, `calls`, `exposes`,
+`implements`, `reads-from`, `writes-to`, `publishes`, `consumes`, `deploys`,
+`documents`, `decided-by`, `tests`, and `owns`.
+
+Every entity and relation carries portable proof references. A proof records its
+provider, source artifact, optional pointer/line, content hash, freshness,
+derivation, trust, and confidence. Secret values and machine-local absolute
+paths are excluded from the portable graph contract.
+
+## Model first, graph second
+
+The canonical direction is one-way:
+
+```text
+Workspace sources
+      ↓
+Canonical Workspace Model + project topology
+      ↓
+Evidence-backed Workspace Knowledge Graph
+      ↓
+CLI queries · Context · MCP · Agents · IDEs · CI
+```
+
+The graph does not rewrite or replace the canonical Workspace Model. It is a
+derived representation bound to an exact model revision by SHA-256. Context and
+MCP consumers reject a graph whose source hash no longer matches the model.
+
+The model also contains a smaller project dependency graph. That projection is
+used for impact, blast radius, verify, explain, watch, and affected fleet runs.
+The richer Knowledge Graph is used for proof-backed retrieval and cross-domain
+understanding.
+
+## Sources and providers
+
+The current CLI uses bounded providers for:
+
+- workspace/project foundations and service contracts;
+- language-neutral source structure and package manifests;
+- OpenAPI, GraphQL, Protobuf, and AsyncAPI interfaces;
+- Docker/Compose, Kubernetes, Terraform, and CI workflows;
+- README/docs, ADRs, tests, and CODEOWNERS.
+
+Providers emit facts and proofs. The graph engine owns stable identity,
+deduplication, typed relations, reconciliation, quality metrics, diagnostics,
+and deterministic ordering. Regex-backed source observations are explicitly
+marked as observed/medium-confidence; authored contracts remain authoritative.
+
+## Outputs and consumers
+
+`workspace model --write` publishes these two artifacts atomically:
+
+```text
+.workspai/reports/workspace-model.json
+.workspai/reports/workspace-knowledge-graph.json
+```
+
+The Knowledge Graph is consumed by:
+
+- `workspace graph search|entities|evidence|path|overlay`;
+- `workspace context`, which validates the model hash and publishes graph
+  availability and query commands;
+- `workspace agent-sync`, which places it in the evidence index and generated
+  agent/MCP instructions;
+- `workspace mcp serve`, through `getWorkspaceKnowledgeGraph`,
+  `searchWorkspaceGraph`, `queryWorkspaceEntities`,
+  `getWorkspaceGraphEvidence`, and `findWorkspaceGraphPath`;
+- `workspace contract graph`, which exposes the contract projection, project
+  topology, rich graph, and quality summary in one response.
+
+The complete graph is an interchange artifact, not a prompt. Agents should
+start with `INDEX.json`, use bounded search, then retrieve evidence or a path
+for the selected result.
+
+## AI tool output locations
+
+`workspace agent-sync --write --preset enterprise` generates native surfaces
+without changing project source:
+
+| Consumer               | Canonical output                                                                                                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Cross-tool/Codex       | `AGENTS.md`, `.workspai/reports/INDEX.json`                                                                                                                        |
+| Claude Code            | `CLAUDE.md`, `.claude/rules/workspai-evidence.md`                                                                                                                  |
+| GitHub Copilot/VS Code | `.github/copilot-instructions.md`, `.github/instructions/workspai-*.instructions.md`, `.github/agents/workspai-*.agent.md`, `.github/prompts/workspai-*.prompt.md` |
+| Cursor                 | `.cursor/rules/workspai-grounding.mdc`                                                                                                                             |
+| MCP clients            | `.workspai/reports/workspai-mcp-design.json`, `workspace mcp serve`                                                                                                |
+
+Files named `rapidkit-*` are compatibility aliases for older consumers. They
+must stay narrowly scoped and must not duplicate an always-applied canonical
+rule.
+
+### Avoiding duplicate AI instructions
+
+Canonical Workspai rules are the only always-applied surfaces. Legacy RapidKit
+aliases point to the canonical files and apply only to `.rapidkit/**`. This
+prevents two equivalent instruction files from being injected into one prompt.
+
+The recommended read order is:
+
+1. `AGENTS.md` for stable workspace policy and navigation;
+2. `.workspai/reports/INDEX.json` for artifact discovery and freshness;
+3. `workspace graph search` or `searchWorkspaceGraph` for question-sized facts;
+4. `workspace graph evidence|path` when a claim needs proof;
+5. the complete model or graph only for export, audit, or whole-system analysis.
+
+## Performance and scale
+
+Graph construction inventories each project once per build and caps the number
+of scanned files. Providers reuse the same in-memory inventory and content
+hashes. Query indexes are cached per immutable graph object; replacing the graph
+is the invalidation boundary. `workspace model --cache` and `--incremental`
+avoid unnecessary model/project work when inputs are unchanged.
+
+Use full graph export for interchange or offline analysis. Use bounded search
+for interactive agents. The latter keeps response size proportional to the
+question instead of workspace size.
+
+## Measuring retrieval payload reduction
+
+Workspai does not publish an unqualified “N× fewer tokens” claim. Such a claim
+depends on the workspace, query, tokenizer, model, answer-quality target, and
+baseline.
+
+Measure the current workspace instead:
+
+```bash
+npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json
+```
+
+The report compares the readable, proof-indexed source corpus with the bounded
+search payload using a clearly labelled `characters / 4` token estimate. It
+reports corpus size, retrieval size, estimated ratio, percentage reduction,
+unreadable artifacts, query, limit, graph counts, and the exact source-model
+SHA-256 needed to reproduce the run.
+
+This proves **retrieval payload reduction**, not equivalent answer quality,
+model-specific billing savings, or universal token savings. A publishable
+cross-project claim additionally requires pinned source revisions, fixed
+queries, a real tokenizer, repeated runs, and answer-quality evaluation.
+
+In the current 16-project development fixture, the query `api endpoint` with
+`--limit 8` returned 8 entities and 9 proofs. The compact retrieval was 2,812
+estimated tokens versus 134,105 estimated tokens in 392 readable proof-source
+artifacts: an observed 47.69× / 97.9% payload reduction. This is a transparent
+fixture result, not a headline claim for every workspace.
+
+See [Graph Benchmark Methodology](./graph-benchmark-methodology.md) for formulas,
+reproduction rules, realistic baselines, and the gate required before publishing
+a general performance claim.
+
+## Current boundaries
+
+- The CLI graph is intentionally file-backed; a graph database is not required.
+- Text search is deterministic lexical retrieval, not embedding similarity.
+- Compiler/LSP-grade symbol resolution belongs in deeper language providers.
+- Missing project edges mean “relationship not proven,” not “projects are
+  independent.” Author service contracts or provide API/package/runtime
+  evidence to close that gap.
+- The standalone `@workspai/graph` package remains unpublished while its public
+  contracts and conformance gates are developed.
+
+## When the graph looks incomplete
+
+Workspai does not invent relationships. If projects appear as disconnected
+nodes, check the following in order:
+
+1. run `workspace sync --json` and regenerate the model;
+2. declare `dependsOn`, APIs, published events, and consumed events in the
+   workspace/project contracts;
+3. confirm package manifests, OpenAPI/AsyncAPI/GraphQL/Protobuf documents,
+   Compose/Kubernetes/Terraform files, and CI definitions are inside registered
+   project paths;
+4. inspect `graph.quality`, `providers`, and `diagnostics` before treating a
+   missing edge as proof of independence.
+
+An absent edge means “not proven by current evidence,” not “no dependency
+exists.”
+
+For schemas and machine contracts, see the
+[Artifact Catalog](./contracts/ARTIFACT_CATALOG.md). For the full command
+surface, see [Commands Reference](./commands-reference.md).

package/docs/workspace-operations.md

@@ -7,7 +7,9 @@ Command syntax: [commands-reference.md](./commands-reference.md).
 ## Import and adoption
 
 Use `import` to copy or clone an existing project into a Workspai workspace.
-Use `adopt` when the project must stay where it already lives but should become visible to RapidKit and Workspai workspace intelligence.
+Use `adopt` when the project must stay where it already lives but should become
+visible to Workspai Workspace Intelligence. Core module commands remain limited
+to projects whose existing RapidKit metadata identifies a module-enabled kit.
 
 ```bash
 npx workspai import ../orders-api
@@ -20,24 +22,24 @@ npx workspai adopt --json
 ### Import behavior
 
 - Local folders are copied; git sources are cloned with shallow history.
-- Outside any workspace (no `--workspace`), Workspai auto-creates/reuses the managed workspace at `~/.workspai/workspaces/workspai`.
-- Existing workspaces under `~/rapidkit/workspaces/*` and `~/Workspai/rapidkits/*` remain registered after upgrade.
+- Outside any workspace (no `--workspace`), Workspai creates or reuses the managed `workspai` workspace. New defaults use `~/.workspai/workspaces/workspai`; valid legacy candidates under `~/rapidkit/workspaces/workspai` and `~/Workspai/rapidkits/workspai` can still be reused.
+- Existing workspaces under legacy managed roots remain registered after upgrade.
 - CLI prints a next-step `cd ...` hint (`suggestedCdCommand` in JSON mode).
 - Failed workspace sync rolls back imported files and registry entries.
 
 ### Adopt behavior
 
 - Source files are not moved or copied.
-- Default workspace resolution matches import (`workspai` under `~/.workspai/workspaces/`).
+- Default workspace resolution matches import, including canonical creation and valid legacy managed-default reuse.
 - Writes `.workspai/project.json`, `.workspai/adopt.json`, and `.workspai/adopt-readiness.json`.
 - Registry and contract sync include adopted projects for `workspace model`, `workspace context`, Dashboard, and agents.
 - `--dry-run --json` previews detection without writing metadata.
 
 ### JSON output (`--json`)
 
-- `workspacePath`, `workspaceResolution` (`explicit` | `nearest` | `default-auto`)
-- `defaultWorkspaceCreated`, `suggestedCdCommand`
-- `importedProject` or `adoptedProject` (`name`, `path`, `stack`, `runtime`, `framework`, `supportTier`, `moduleSupport`, `confidence`, `source`)
+- Import returns `workspacePath`, `workspaceResolution`, `defaultWorkspaceCreated`, `suggestedCdCommand`, and `importedProject`. The imported project includes its `source`.
+- Adopt returns `workspacePath`, `workspaceResolution`, `defaultWorkspaceCreated`, `wouldCreateDefaultWorkspace`, `dryRun`, and `adoptedProject`.
+- Project results include detected `name`, `path`, `stack`, `runtime`, `framework`, `supportTier`, `moduleSupport`, and `confidence` where available.
 
 Imported projects receive `.workspai/import-readiness.json`. Adopted projects add frontend-aware detection for Next.js, React, Vite, Vue, Angular, SvelteKit, Nuxt, Astro, Remix, and Solid.
 
@@ -92,6 +94,55 @@ npx workspai workspace contract graph
 
 Contract file: `.workspai/workspace.contract.json`. Verification checks schema, duplicate slugs, port collisions, and unknown dependencies.
 
+`workspace contract graph --json` preserves its original `nodes`, `edges`, and
+summary fields for existing consumers, and now adds an evidence-backed
+`dependencyGraph` using the public `workspace-dependency-graph.v1` contract. It
+discovers package/workspace dependencies and supported cross-project imports,
+records relationship provenance and confidence, and reports graph coverage,
+orphans, hotspots, and cycles. Project nodes also expose safe package metadata,
+public environment-template keys, command capabilities, key manifests,
+entrypoints, API specifications, infrastructure, documentation, and an
+operational verification profile. Environment values are never emitted.
+
+The same response also exposes `knowledgeGraph` under the public
+`workspace-knowledge-graph.v1` contract. It is a provider-neutral,
+proof-carrying view spanning source structure, packages, service and API
+contracts, infrastructure, delivery pipelines, docs/ADRs, ownership, tests,
+runtime resources, and safe configuration keys. Use the dedicated query and
+change-overlay surfaces when the full document is larger than a human needs:
+
+```bash
+npx workspai workspace graph entities endpoint --json
+npx workspai workspace graph search "authentication endpoint" --limit 12 --json
+npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json
+npx workspai workspace graph evidence "GET /users" --json
+npx workspai workspace graph path frontend-api "GET /users" --json
+npx workspai workspace graph emit --json > .workspai/reports/knowledge-baseline.json
+npx workspai workspace graph overlay --from .workspai/reports/knowledge-baseline.json --json
+```
+
+The Model step persists the same projection to
+`.workspai/reports/workspace-knowledge-graph.json`. It is registered in the
+artifact contract registry and agent report index, required by the unified
+runner's Model stage, referenced from `workspace-context-agent.json`, and
+queryable through the read-mostly MCP server. This keeps CLI, CI, IDE and agent
+consumers on one contract revision without injecting the full graph into every
+agent prompt.
+
+The overlay follows
+`workspace-knowledge-graph-change-overlay.v1`: graph revisions are identified
+by content-derived fingerprints (timestamps do not create false changes), and
+changed artifacts are portable proof paths rather than machine-local absolute
+paths. Proof additions, removals, and content-hash changes are first-class
+overlay changes, so a source edit is visible even when the entity and relation
+shape remains stable. The builder performs one bounded inventory pass per project and reuses
+in-memory content hashes; query indexes live only for the immutable graph
+instance, so replacing the graph is the invalidation boundary.
+
+Direction is explicit: legacy `edges` remain producer-to-consumer for backward
+compatibility; `dependencyGraph.edges` use consumer-to-dependency semantics so
+impact and blast-radius consumers share one canonical interpretation.
+
 Workspai keeps the contract alive during `create project` and `workspace sync` without overwriting manual API/event/owner declarations.
 
 On a freshly cloned or moved workspace, `workspace sync` also repairs the
@@ -115,16 +166,24 @@ Export excludes dependency folders, build output, git history, logs, `.env`, and
 
 Archive export, verification, and hydrate stream file payloads instead of loading the workspace into memory. Exports use ZIP64, so multi-gigabyte workspaces and archives with more than 65,535 files are supported. Stored ZIP entries are the default; use `--archive-compression deflate` when transfer size matters more than export CPU time.
 
-Workspace size is unrestricted by default. For untrusted remote archives, optional operational budgets can be set without imposing a product-wide workspace limit:
+Remote archives are protected by secure defaults: 5 GB maximum download, 20 GB
+maximum expanded payload, 200,000 entries, per-entry and compression-ratio
+guards, and a five-minute timeout. Public HTTPS destinations are accepted;
+loopback, private, link-local, and private redirect destinations are rejected.
+Budgets can be lowered or explicitly raised for a controlled workflow:
 
 ```bash
 npx workspai workspace hydrate https://example.test/team.zip \
   --output ./team-workspace \
-  --max-download-size 100gb \
-  --max-expanded-size 500gb \
-  --download-timeout-ms 21600000
+  --max-download-size 2gb \
+  --max-expanded-size 8gb \
+  --download-timeout-ms 120000
 ```
 
+For a reviewed archive served from a private development network, opt in with
+`--allow-private-network`. Never use that flag for user-controlled URLs in CI
+or agent services.
+
 IDE, CI, and AI consumers can discover archive behavior from
 `contracts/workspace-archive-capabilities.v1.json`. The embedded manifest and every successful
 `--json` operation result are runtime-validated against
@@ -162,12 +221,20 @@ Artifacts:
 | `import`                                                    | Workspace ingestion    | Rollback-safe sync                                 |
 | `adopt`                                                     | Workspace adoption     | In-place linking + registry sync                   |
 | `workspace model/context/diff/impact/verify`                | Workspace intelligence | Model, context packs, blast radius                 |
+| `workspace intelligence run`                                | Workspace intelligence | Canonical contract-backed chain and strict gate    |
 | `snapshot`                                                  | Workspace recovery     | Metadata or full snapshots                         |
 | `project archive/restore/delete`                            | Project lifecycle      | Safe delete with confirmation                      |
 | `doctor` / `doctor workspace` / `doctor project`            | Wrapper health         | Host, workspace, and project scopes                |
 | `workspace run`                                             | Workspace orchestrator | Fleet stage execution                              |
 | `infra`                                                     | Workspace sidecar      | Contract-driven local dependencies                 |
 
+The unified intelligence runner keeps `sync` and baseline resolution in a
+separate two-entry execution envelope and emits exactly 11 canonical stages.
+Exit `2` means the evidence gate blocked readiness after successful execution;
+exit `1` means a hard runtime failure. Read the complete
+[Unified Workspace Intelligence Runner contract](./workspace-intelligence-runner.md)
+before consuming its report from CI, IDE, or agent integrations.
+
 ## Verification evidence freshness
 
 `workspace verify` treats evidence as release-gate material, not just as a file

package/docs/workspace-run.md

@@ -11,7 +11,10 @@ npx workspai workspace run test --affected --blast-radius
 npx workspai workspace run build --json --max-workers 8
 ```
 
-`--blast-radius` uses `.workspai/workspace.contract.json` (and legacy `.rapidkit/workspace-dependency-graph.json` as fallback) to expand direct `dependsOn` and publish/consume event relationships.
+`--blast-radius` resolves the canonical or legacy workspace contract first, then
+`.workspai/workspace-dependency-graph.json`, and finally the legacy
+`.rapidkit/workspace-dependency-graph.json` fallback. It expands direct
+`dependsOn` and publish/consume event relationships.
 
 ## Supported runtimes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workspai",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "type": "module",
   "description": "Open-source workspace intelligence CLI for software systems: create, adopt, govern, verify, and align polyglot workspaces for humans, CI, IDEs, and AI agents.",
   "keywords": [
@@ -64,8 +64,8 @@
     "access": "public"
   },
   "scripts": {
-    "preinstall": "node scripts/enforce-package-manager.cjs",
     "postinstall": "node scripts/check-cli-resolution.cjs",
+    "check:package-manager": "node scripts/enforce-package-manager.cjs",
     "sync-kits": "bash scripts/sync-kits.sh",
     "sync:kits": "corepack npm run sync-kits",
     "build": "tsup",
@@ -77,7 +77,8 @@
     "prepare": "node scripts/prepare-husky.mjs",
     "test:e2e:first-install": "bash scripts/e2e-first-install.sh",
     "test:e2e:user-first-install": "bash scripts/e2e-user-first-install.sh",
-    "test": "vitest run",
+    "test:prebuild": "tsup",
+    "test": "corepack npm run test:prebuild && vitest run",
     "test:drift": "node scripts/run-drift-guard.mjs",
     "benchmark:intelligence": "vitest run src/__tests__/workspace-intelligence-benchmark.test.ts",
     "sync:shared-contracts": "node scripts/sync-shared-contracts.mjs",
@@ -90,7 +91,7 @@
     "validate:contracts": "corepack npm run check:shared-contracts && vitest run src/__tests__/contracts/",
     "test:parity-contract": "corepack npm run check:shared-contracts && vitest run src/__tests__/contracts/import-stack-parity.snapshot.test.ts",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
+    "test:coverage": "vitest run --coverage --reporter=default --reporter=json --outputFile.json=test-results/vitest.json",
     "test:prepare-embeddings": "node scripts/prepare-mock-embeddings.mjs",
     "generate-embeddings": "npx tsx src/ai/generate-embeddings.ts",
     "verify:package-cli": "node scripts/verify-package-cli.mjs",
@@ -111,10 +112,10 @@
     "format": "prettier --write \"src/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\"",
     "typecheck": "tsc --noEmit",
-    "validate": "corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm test",
+    "validate": "corepack npm run check:package-manager && corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm test",
     "security": "corepack npm audit --audit-level=moderate",
     "security:fix": "corepack npm audit fix",
-    "metrics": "npx tsx scripts/metrics.ts",
+    "metrics": "tsx scripts/metrics.ts",
     "validate:docs-examples": "node scripts/validate-doc-examples.mjs",
     "check:markdown-links": "node scripts/check-markdown-links.mjs",
     "check:docs-drift": "node scripts/docs-drift-guard.mjs",
@@ -128,13 +129,13 @@
     "analyze": "corepack npm run build && node scripts/analyze-dist.mjs",
     "size-check": "corepack npm run build && size-limit",
     "bench": "npx tsx scripts/benchmarks.ts",
-    "quality": "corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm test && corepack npm run size-check && corepack npm run check:workspace-intelligence-runtime && corepack npm run check:workspace-intelligence-adversarial && corepack npm run security && corepack npm run validate:docs && corepack npm run smoke:frontend-generators && corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:parity-snapshot && corepack npm run check:agent-customization-drift",
+    "quality": "corepack npm run check:package-manager && corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm test && corepack npm run size-check && corepack npm run check:workspace-intelligence-runtime && corepack npm run check:workspace-intelligence-adversarial && corepack npm run security && corepack npm run validate:docs && corepack npm run smoke:frontend-generators && corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:parity-snapshot && corepack npm run check:agent-customization-drift",
     "act-matrix": "act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-22.04 -P macos-latest=ghcr.io/catthehacker/ubuntu:act-22.04 -P windows-latest=ghcr.io/catthehacker/ubuntu:act-22.04 --pull=false -j build-test-matrix",
     "release:dry": "bash scripts/release.sh --no-publish --yes --allow-dirty",
     "release:patch": "bash scripts/release.sh patch",
     "release:minor": "bash scripts/release.sh minor",
     "release:major": "bash scripts/release.sh major",
-    "check": "corepack npm run check:windows-registry && corepack npm run typecheck && corepack npm run lint && corepack npm run format:check",
+    "check": "corepack npm run check:package-manager && corepack npm run check:windows-registry && corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm run test:coverage && corepack npm run metrics",
     "ci": "corepack npm run quality",
     "contracts:sync": "corepack npm run sync:contracts && corepack npm run sync:shared-contracts",
     "contracts:check": "corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:parity-snapshot && corepack npm run check:generated-contracts && corepack npm run check:agent-customization-drift",
@@ -157,6 +158,7 @@
     "openai": "^6.22.0",
     "ora": "^8.0.1",
     "validate-npm-package-name": "^5.0.1",
+    "yaml": "^2.9.0",
     "yauzl": "^3.4.0",
     "yazl": "^3.3.1"
   },

package/rapidkit.config.example.cjs

@@ -19,9 +19,9 @@ module.exports = {
     // Default author name for new workspaces
     defaultAuthor: 'Your Name or Team',
 
-    // Default Python version to use
-    // Options: '3.10' | '3.11' | '3.12'
-    pythonVersion: '3.10',
+    // Optional version pin. Python 3.10 is the minimum supported version.
+    // Omit this setting to let Workspai detect and select an installed version.
+    // pythonVersion: '3.10',
 
     // Default installation method for RapidKit Core
     // Options: 'poetry' | 'venv' | 'pipx'
@@ -53,10 +53,10 @@ module.exports = {
 
 // Example usage:
 // npx workspai my-workspace
-// -> Uses config: author='Your Name or Team', pythonVersion='3.10', installMethod='poetry'
+// -> Uses config: author='Your Name or Team', installMethod='poetry'; Python is auto-detected
 //
 // npx workspai my-workspace --author "Different Author"
-// -> Overrides: author='Different Author', but still uses pythonVersion='3.10', installMethod='poetry'
+// -> Overrides author; installMethod remains 'poetry' and Python is auto-detected
 //
 // npx workspai create project my-api
 // -> Uses config: defaultKit='fastapi.standard', adds default modules

package/scripts/enforce-package-manager.cjs

@@ -4,7 +4,7 @@ const userAgent = process.env.npm_config_user_agent || '';
 const usingNpm = userAgent.startsWith('npm/');
 
 if (!usingNpm) {
-  console.error('❌ Workspai uses npm as the only supported package manager for development.');
+  console.error('Workspai uses npm as the only supported package manager for development.');
   console.error('Please run: npm install');
   process.exit(1);
 }

package/scripts/prepack-enterprise.mjs

@@ -33,6 +33,10 @@ if (!fs.existsSync(tsupCli)) {
   fail(`missing tsup CLI at ${tsupCli}; run npm ci before packaging`);
 }
 
+runNode(
+  ['scripts/generate-shared-contracts.mjs', '--check'],
+  'checking generated contracts, including extension CLI compatibility'
+);
 runNode([tsupCli], 'building dist');
 runNode(['scripts/prepare-mock-embeddings.mjs'], 'preparing packaged embeddings');
 runNode(['scripts/verify-package-cli.mjs'], 'verifying bundled CLI command ownership');