workspai 0.45.0 → 0.46.0

package/docs/examples/ci-agent-grounding.yml

@@ -10,6 +10,7 @@ name: Workspai Agent Grounding
 on:
   pull_request:
     paths:
+      - '.workspai/**'
       - '.rapidkit/**'
       - 'AGENTS.md'
       - 'CLAUDE.md'
@@ -34,17 +35,21 @@ jobs:
       - name: Install Workspai CLI
         run: npm install --no-save workspai
 
-      - name: Run governance pipeline
-        run: npx workspai pipeline --json --strict
+      - name: Run canonical Workspace Intelligence chain
+        # Exit 1 = hard execution failure; exit 2 = completed but evidence-blocked.
+        # Continue here only so the durable run report and blocker evidence can
+        # always be uploaded; the final step below still fails either outcome.
+        run: npx workspai workspace intelligence run --for-agent codex --strict --json
+        continue-on-error: true
+        id: intelligence
+
+      - name: Run separate governance pipeline
+        run: npx workspai pipeline --json --strict --no-agent-sync
         continue-on-error: true
         id: pipeline
 
-      - name: Sync and verify agent grounding
-        run: |
-          npx workspai workspace agent-sync --write --refresh-context --strict --json --preset enterprise
-          node ./node_modules/workspai/scripts/check-agent-customization-drift.mjs --workspace .
-        env:
-          RAPIDKIT_NO_AGENT_SYNC: '0'
+      - name: Verify agent grounding drift
+        run: node ./node_modules/workspai/scripts/check-agent-customization-drift.mjs --workspace .
 
       - name: Upload agent grounding artifacts
         if: always()
@@ -54,12 +59,13 @@ jobs:
           path: |
             .workspai/reports/INDEX.json
             .workspai/reports/workspace-context-agent.json
+            .workspai/reports/workspace-intelligence-run-last-run.json
             .workspai/reports/agent-customization-pack.json
             .workspai/reports/workspai-mcp-design.json
             .workspai/reports/pipeline-last-run.json
             AGENTS.md
           if-no-files-found: ignore
 
-      - name: Fail if pipeline blocked
-        if: steps.pipeline.outcome == 'failure'
+      - name: Fail if canonical chain or pipeline blocked
+        if: steps.intelligence.outcome == 'failure' || steps.pipeline.outcome == 'failure'
         run: exit 1

package/docs/from-code-to-shared-understanding.md

@@ -1,45 +1,76 @@
 # From Code to Shared Understanding
 
-How Workspai transforms projects and repositories into workspace intelligence for developers, CI, and AI agents.
-
-This Mermaid diagram is kept in the internal documentation because GitHub renders it correctly. The main npm README uses a PNG version of the same diagram so it remains visible on npm package pages.
+Workspai gives everyone the same understanding of your software, without asking
+you to replace your frameworks or move existing source code.
 
 ```mermaid
 flowchart TB
+    Code["Your projects and repositories"]
+
+    Routes["Create a project<br/>Adopt it in place<br/>or Import a repository"]
+
+    Workspace["Workspai builds one model of<br/>projects, dependencies, rules, and commands"]
+
+    Change["What changed?<br/>What is affected?<br/>Is the evidence ready?"]
+
+    Outputs["Context, impact, verification,<br/>explanations, and release evidence"]
+
+    Code --> Routes
+    Routes --> Workspace
+    Workspace --> Change
+    Change --> Outputs
+
+    Outputs --> Developers["Developers"]
+    Outputs --> CI["CI and releases"]
+    Outputs --> IDEs["IDEs"]
+    Outputs --> Agents["AI agents"]
+    Outputs --> MCP["MCP clients"]
+```
+
+## What This Means
+
+1. **Connect your software.** Create something new, adopt an existing project
+   without moving it, or import a repository.
+2. **Understand the workspace.** Workspai builds one model of the projects and
+   how they relate.
+3. **Understand change and verify it.** Workspai shows affected areas and checks
+   the evidence needed for a safe decision.
+4. **Share the result.** Developers, CI, IDEs, AI agents, and MCP clients consume
+   the same workspace truth instead of building separate assumptions. The
+   current CLI exposes a read-mostly `workspace mcp serve` bridge; a dedicated
+   `packages/mcp` boundary is planned.
 
-    Code["Code & Repositories"]
-    Projects["Projects"]
-    Workspace["Workspace"]
-
-    Code --> Projects
-    Projects --> Workspace
-
-    subgraph Intelligence["Workspace Intelligence"]
-        Model["Workspace Model"]
-        Context["Agent Context"]
-        Impact["Impact Analysis"]
-        Verify["Verification"]
-        Evidence["Evidence & Gates"]
-    end
-
-    Workspace --> Model
-    Workspace --> Context
-    Workspace --> Impact
-    Workspace --> Verify
-    Workspace --> Evidence
-
-    Model --> Dev["Developers"]
-    Model --> CI["CI"]
-    Model --> Agents["AI Agents"]
-
-    Context --> Agents
-
-    Impact --> Dev
-    Impact --> CI
-
-    Verify --> CI
-    Verify --> Agents
-    Evidence --> Dev
-    Evidence --> CI
-    Evidence --> Agents
+This is the user-facing view. The implementation uses a versioned chain of
+model, change, evidence, verification, context, grounding, and explanation
+steps. Contributors and integrations can inspect the complete contracts:
+
+- [`workspace-intelligence-chain.v1.json`](../contracts/workspace-intelligence-chain.v1.json)
+- [`workspace-intelligence-architecture.v1.json`](../contracts/workspace-intelligence-architecture.v1.json)
+
+The unified runner also has a deterministic execution envelope: `sync` runs
+before Model and baseline resolution runs after Model/before Diff. These appear
+as two `preflight` entries, not as extra chain stages. The 11 canonical stages,
+baseline lifecycle, exit codes, and failure propagation are specified in
+[Unified Workspace Intelligence Runner](./workspace-intelligence-runner.md).
+
+The npm README uses a PNG rendering because npm package pages do not reliably
+render Mermaid. When this source changes, regenerate
+`From Code to Shared Understanding.png` before publishing.
+
+## Execute the Contract
+
+Run the complete canonical chain in its versioned order:
+
+```bash
+npx workspai workspace intelligence run --for-agent codex --json
 ```
+
+For enterprise CI and release enforcement, add `--strict`. A warning or
+needs-attention verdict then produces a blocked report and exit code `2`:
+
+```bash
+npx workspai workspace intelligence run --for-agent codex --strict --json
+```
+
+`pipeline` is the broader governance/release orchestrator. It does not replace
+or reorder the canonical Workspace Intelligence chain.

package/docs/workspace-intelligence-runner.md

@@ -0,0 +1,186 @@
+# Unified Workspace Intelligence Runner
+
+`workspace intelligence run` is the canonical contract-backed entrypoint for
+refreshing Workspace Intelligence evidence in one deterministic execution. Use
+it from a Workspai workspace root:
+
+```bash
+npx workspai workspace intelligence run --for-agent codex --strict --json
+```
+
+The authoritative result is written atomically to
+`.workspai/reports/workspace-intelligence-run-last-run.json` with schema
+`workspace-intelligence-run.v1`. JSON stdout returns the same report payload.
+Consumers should read the persisted report when they need durable evidence and
+use the process exit code for the immediate automation verdict.
+
+## Execution envelope and canonical chain
+
+The runner separates prerequisite operations from the versioned intelligence
+chain. `sync` and baseline handling are reported in `preflight`; they are not
+additional chain stages.
+
+```text
+Execution order
+
+sync
+  -> model
+  -> baseline resolution
+  -> diff
+  -> impact
+  -> doctor-evidence
+  -> contract-evidence
+  -> analyze-evidence
+  -> readiness-evidence
+  -> verify
+  -> context
+  -> agent-sync
+  -> explain
+```
+
+The report always contains exactly two ordered `preflight` entries:
+
+| ID         | Execution point              | Successful result     | Purpose                                            |
+| ---------- | ---------------------------- | --------------------- | -------------------------------------------------- |
+| `sync`     | Before `model`               | `synchronized`        | Reconcile workspace inventory and contract inputs. |
+| `baseline` | After `model`, before `diff` | `created` or `reused` | Ensure Diff has an explicit structural baseline.   |
+
+The report always contains exactly these 11 ordered `stages`:
+
+| Order | Stage                | Contract role                                           |
+| ----: | -------------------- | ------------------------------------------------------- |
+|     1 | `model`              | Build and persist the current workspace model.          |
+|     2 | `diff`               | Compare the current model with the selected baseline.   |
+|     3 | `impact`             | Calculate affected projects and transitive consequence. |
+|     4 | `doctor-evidence`    | Refresh workspace and project health evidence.          |
+|     5 | `contract-evidence`  | Verify the workspace contract.                          |
+|     6 | `analyze-evidence`   | Refresh structural and operational analysis.            |
+|     7 | `readiness-evidence` | Refresh pre-verify release-readiness evidence.          |
+|     8 | `verify`             | Produce the definitive evidence-backed gate.            |
+|     9 | `context`            | Build agent context from the same current evidence.     |
+|    10 | `agent-sync`         | Project canonical context into agent and IDE surfaces.  |
+|    11 | `explain`            | Explain the resulting release posture and blockers.     |
+
+The machine-readable authority is
+[`workspace-intelligence-chain.v1.json`](../contracts/workspace-intelligence-chain.v1.json).
+Commands, websites, IDEs, CI jobs, and agent instructions must not define a
+different order or insert `sync` or `snapshot-baseline` into `stages`.
+
+## Baseline semantics
+
+On the first run, the runner creates
+`.workspai/reports/workspace-model-snapshot.json` and reports:
+
+```json
+{
+  "id": "baseline",
+  "status": "passed",
+  "result": "created"
+}
+```
+
+On later runs, it reuses the existing snapshot and reports `result: "reused"`.
+`baselineCreated` is `true` only when that run created the baseline.
+
+The runner does not silently replace an existing baseline immediately before
+Diff. Doing so would erase the change boundary and incorrectly report no
+changes. Refresh or replace a baseline only through the explicit
+`workspace snapshot` workflow after the intended structural state has been
+accepted.
+
+## Status and exit semantics
+
+| Report status | Exit code | Meaning                                                                                        |
+| ------------- | --------: | ---------------------------------------------------------------------------------------------- |
+| `passed`      |       `0` | Every operation executed and no gate blocked the run.                                          |
+| `failed`      |       `1` | A required operation threw or could not complete. Downstream stages are recorded as `skipped`. |
+| `blocked`     |       `2` | Execution completed, but one or more evidence or verification gates rejected readiness.        |
+
+The canonical mapping is `passed` → `0`, `failed` → `1`, and `blocked` → `2`.
+
+A `blocked` evidence stage does not stop the chain. Context, grounding, and
+Explain must still be refreshed so humans and agents receive the current
+blocker evidence. A hard `failed` stage stops execution work and every
+downstream canonical stage is recorded with `status: "skipped"`, `exitCode: 0`,
+and `durationMs: 0`.
+
+Stage invariants:
+
+- `passed` requires `exitCode: 0`;
+- `blocked` requires a non-zero stage exit code;
+- `failed` requires `exitCode: 1`;
+- `skipped` requires `exitCode: 0` and `durationMs: 0`;
+- report status and exit code are derived from all preflight and stage results;
+- every stage artifact list must exactly match the runtime registry.
+
+`--strict` promotes warning-grade readiness states such as Analyze
+`needs-attention` and Readiness `warn` into blocked stage verdicts. It does not
+turn evidence blockers into execution failures: the aggregate exit remains `2`,
+not `1`.
+
+## Report contract
+
+The durable report contains:
+
+```json
+{
+  "schemaVersion": "workspace-intelligence-run.v1",
+  "chainSchemaVersion": "workspai-workspace-intelligence-chain-v1",
+  "generatedAt": "2026-07-18T00:00:00.000Z",
+  "workspacePath": "/absolute/machine-local/path",
+  "baselineCreated": false,
+  "preflight": [],
+  "status": "blocked",
+  "exitCode": 2,
+  "stages": [],
+  "artifactPath": ".workspai/reports/workspace-intelligence-run-last-run.json"
+}
+```
+
+The abbreviated arrays above illustrate the envelope only; conforming reports
+must contain exactly two preflight entries and 11 stages. The complete JSON
+Schema is
+[`workspace-intelligence-run.v1.json`](../contracts/workspace-intelligence/workspace-intelligence-run.v1.json).
+Structural schema validation is necessary but not sufficient. Workspai also
+enforces stage order, registered artifacts, baseline coherence, failure
+propagation, and aggregate verdict semantics before writing the report.
+
+`workspacePath` and some underlying evidence can contain machine-local absolute
+paths. Do not treat the run report as a portable workspace identity contract or
+publish it without applying the relevant redaction policy.
+
+## CI consumption
+
+The simplest hard gate is:
+
+```bash
+npx workspai workspace intelligence run --for-agent codex --strict --json
+```
+
+Both exit `1` and exit `2` fail a normal CI step. If artifacts must be uploaded
+after a blocked run, allow the runner step to continue, upload with `if: always()`,
+then fail the job from the recorded step outcome. See
+[`examples/ci-agent-grounding.yml`](./examples/ci-agent-grounding.yml).
+
+Automation must distinguish:
+
+- exit `1`: repair execution, environment, permissions, corruption, or another
+  hard runtime failure;
+- exit `2`: inspect Analyze, Readiness, Verify, and Explain evidence and resolve
+  the reported blockers;
+- exit `0`: consume the newly refreshed artifacts.
+
+Do not parse terminal prose. Read `status`, `exitCode`, `preflight`, `stages`,
+and their registered artifacts from the JSON report.
+
+## Relationship to other commands
+
+`workspace intelligence run` is the canonical Workspace Intelligence chain.
+`pipeline` is a broader governance/release orchestrator and `autopilot release`
+is a separate release surface. Neither command may replace, reorder, extend, or
+silently partially execute the canonical intelligence chain.
+
+Individual commands such as `workspace model`, `workspace diff`, and
+`workspace verify` remain useful for inspection and targeted renewal. A partial
+manual sequence must not be documented or treated as an equivalent replacement
+for the unified runner.

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.
 
@@ -115,16 +117,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 +172,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.46.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",

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');