workspai 0.44.0 → 0.46.0

package/docs/DEVELOPMENT.md

@@ -6,7 +6,7 @@ Maintainer reference for the Workspai CLI (Node/TypeScript bridge to Python Core
 
 ## Prerequisites
 
-- Node.js `>= 20`
+- Node.js `>=20.19.0`
 - npm — see [PACKAGE_MANAGER_POLICY.md](./PACKAGE_MANAGER_POLICY.md)
 
 ```bash
@@ -18,7 +18,7 @@ npm run build
 
 ```bash
 npm run validate
-npm run validate:contracts
+npm run contracts:validate
 npm run test:drift
 ```
 
@@ -30,11 +30,11 @@ User defaults: [config-file-guide.md](./config-file-guide.md) (`$HOME/.workspair
 
 Priority: CLI flags > environment variables > config file > defaults.
 
-### Test mode (local Core)
+### Local Core checkout
 
 ```bash
 export WORKSPAI_DEV_PATH=/path/to/local/rapidkit-core
-npx workspai my-workspace --test-mode
+npx workspai my-workspace
 ```
 
 `RAPIDKIT_DEV_PATH` remains supported as a legacy fallback.
@@ -47,7 +47,7 @@ npx workspai create project fastapi.standard my-api --output .
 npx workspai create project nextjs my-web --yes
 
 # Workspace mode
-npx workspai create workspace my-workspace --yes --profile polyglot
+npx workspai create workspace my-workspace --here --yes --profile polyglot
 cd my-workspace
 npx workspai bootstrap --profile polyglot
 npx workspai create project

package/docs/OPEN_SOURCE_USER_SCENARIOS.md

@@ -2,6 +2,11 @@
 
 Practical workflows for OSS teams using the npm CLI. Command syntax: [commands-reference.md](./commands-reference.md). Import/adopt details: [workspace-operations.md](./workspace-operations.md).
 
+All scenarios use the same [Unified Workspace Intelligence Runner](./workspace-intelligence-runner.md):
+`sync` and baseline resolution are reported separately from the exact 11-stage
+chain. Treat exit `1` as an execution failure and exit `2` as an evidence-blocked
+completed run that requires remediation before release.
+
 ## Scenario 0 — Existing project (adopt or import)
 
 Goal: connect code you already have without reshuffling repositories.
@@ -10,7 +15,9 @@ Goal: connect code you already have without reshuffling repositories.
 
 ```bash
 npx workspai adopt /path/to/existing-app --workspace /path/to/workspace --json
-npx workspai workspace model --json
+cd /path/to/workspace
+npx workspai workspace intelligence run --for-agent codex --strict --json
+cd /path/to/existing-app
 npx workspai doctor project --json
 ```
 
@@ -49,7 +56,7 @@ Goal: get productive quickly with minimal complexity.
 ### Steps
 
 ```bash
-npx workspai my-workspace
+npx workspai create workspace my-workspace --here --yes --profile polyglot
 cd my-workspace
 npx workspai bootstrap --profile polyglot
 npx workspai setup python
@@ -60,6 +67,20 @@ npx workspai init
 npx workspai dev
 ```
 
+Run the canonical chain from the workspace before treating its evidence as a
+release or agent input:
+
+```bash
+cd ..
+npx workspai workspace intelligence run --for-agent codex --strict --json
+```
+
+The canonical durable outputs are `.workspai/reports/workspace-model.json`,
+`.workspai/reports/workspace-context-agent.json`, `.workspai/reports/INDEX.json`,
+`.workspai/reports/workspace-intelligence-run-last-run.json`, and `AGENTS.md`.
+Use `npx workspai pipeline --json --strict` separately as the broader governance
+and release gate.
+
 ### When manual vs automatic?
 
 - Manual: run commands directly in local dev.

package/docs/OPTIMIZATION_GUIDE.md

@@ -2,6 +2,10 @@
 
 Optimization ideas for the Workspai CLI codebase.
 
+> This is a proposal backlog, not a description of shipped APIs, benchmarks, CI,
+> or release policy. Validate every proposal against the current package manifest,
+> workflows, and [Development Guide](./DEVELOPMENT.md) before implementation.
+
 **Users:** [../README.md](../README.md) · [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md) · [Documentation index](./README.md)
 
 ## 1. Performance Optimizations
@@ -350,7 +354,10 @@ npm install -D typedoc
 }
 ```
 
-### 7.2 Interactive Examples
+### 7.2 Proposed public API example
+
+The package currently guarantees a CLI binary, not this programmatic API. The
+following is illustrative only and must not be used by consumers:
 ```typescript
 // examples/programmatic-usage.ts
 import { createProject } from 'workspai';
@@ -380,7 +387,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        node-version: [18, 20, 22]
+        node-version: ['20.19.0', 22]
     
     steps:
       - uses: actions/checkout@v3
@@ -392,28 +399,12 @@ jobs:
       - run: npm run build
 ```
 
-### 8.2 Automated Releases
-```yaml
-# .github/workflows/release.yml
-name: Release
-
-on:
-  push:
-    tags:
-      - 'v*'
+### 8.2 Releases
 
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-      - run: npm ci
-      - run: npm run build
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
+Do not publish directly from a tag-triggered example. Releases use the
+maintainer-only `.github/workflows/release-npm-manual.yml` workflow and package
+release scripts after all required exact-SHA gates pass. See
+[CI Workflows](./ci-workflows.md) and [Setup](./SETUP.md).
 
 ## 9. Monitoring & Analytics Optimizations
 
@@ -474,31 +465,8 @@ const createDemoWorkspace = async () => {
 };
 ```
 
-## Implementation Priority
-
-### 🔴 High Priority (Week 1)
-1. ESLint + Prettier setup ✅
-2. Better error messages with suggestions
-3. Input validation improvements
-4. Bundle size optimization
-
-### 🟡 Medium Priority (Weeks 2-3)
-1. Plugin system
-2. Integration tests
-3. Performance benchmarks
-4. CI/CD workflows (optional)
-
-### 🟢 Low Priority (Month 2+)
-1. Telemetry system
-2. Advanced caching
-3. Multi-language support
-4. Interactive documentation
-
-## Summary
-
-These optimizations can achieve:
-- **Performance**: ~40% faster installation
-- **Bundle Size**: ~30% reduction
-- **User Experience**: Significant improvements in error handling and progress tracking
-- **Code Quality**: Higher coverage and better maintainability
-- **Security**: Reduced attack surface and better validation
+## Evaluation requirements
+
+Proposals need an owner, measured baseline, target platform matrix, compatibility
+analysis, and tests before implementation. Do not claim performance or bundle
+improvements without committed, reproducible benchmark evidence.

package/docs/PACKAGE_MANAGER_POLICY.md

@@ -18,7 +18,10 @@ This repository is **npm-only** for development and CI workflows.
 
 ## Enforcement
 
-A `preinstall` guard blocks non-npm package managers during local install.
+`npm run check:package-manager` from `packages/cli`, or
+`npm --workspace workspai run check:package-manager` from the monorepo root,
+enforces the policy in package validation and quality workflows. There is no
+install-time `preinstall` guard.
 
 ## Notes
 

package/docs/README.md

@@ -2,6 +2,29 @@
 
 Hub for user and contributor documentation. Start with the [main README](../README.md) for install and quickstarts.
 
+`workspai` is the canonical package and command; `wspai` is only an optional
+short `npx` alias. Install with `npm install -g workspai`, or run the current
+release with `npx workspai@latest --help`.
+
+## Canonical quickstart
+
+```bash
+npx workspai adopt /path/to/project --json
+cd ~/.workspai/workspaces/workspai
+npx workspai workspace intelligence run --for-agent codex --strict --json
+```
+
+The broader governance/release pipeline is a separate gate:
+
+```bash
+npx workspai pipeline --json --strict
+```
+
+Adoption keeps source in place. The runner preserves contract order and writes
+the authoritative `.workspai/reports/workspace-intelligence-run-last-run.json`
+result alongside the model, agent context, report index, and generated
+instructions; see the [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md).
+
 ## Table of contents
 
 - [User documentation](#user-documentation)
@@ -15,9 +38,11 @@ Hub for user and contributor documentation. Start with the [main README](../READ
 
 | Document | Description |
 | --- | --- |
+| [creating-workspaces-and-projects.md](./creating-workspaces-and-projects.md) | Plain-language guide to every workspace and project creation scenario |
 | [commands-reference.md](./commands-reference.md) | Full CLI syntax, profiles, and policy keys |
 | [workspace-operations.md](./workspace-operations.md) | Import, adopt, snapshots, archives, contracts, infra |
 | [workspace-run.md](./workspace-run.md) | Polyglot fleet orchestration (`workspace run`) |
+| [workspace-intelligence-runner.md](./workspace-intelligence-runner.md) | Canonical unified runner, execution envelope, report schema, exit codes, failure propagation, and CI consumption |
 | [create-planner-capabilities.md](./create-planner-capabilities.md) | Native create, official, and existing lanes |
 | [../contracts/project-entry-capability.v1.json](../contracts/project-entry-capability.v1.json) | Contract: any readable project can enter through adopt/import when it can be registered |
 | [from-code-to-shared-understanding.md](./from-code-to-shared-understanding.md) | GitHub-rendered Workspace Intelligence diagram |
@@ -29,10 +54,12 @@ Hub for user and contributor documentation. Start with the [main README](../READ
 
 **Common tasks**
 
+- Create a workspace or project: [creating-workspaces-and-projects.md](./creating-workspaces-and-projects.md)
 - Adopt an existing repo: [workspace-operations.md#import-and-adoption](./workspace-operations.md#import-and-adoption)
 - Scaffold a frontend app: [commands-reference.md](./commands-reference.md) (`create project nextjs <name>`)
-- CI release gate: [commands-reference.md](./commands-reference.md) (`pipeline`, `readiness`)
-- Agent context: `workspace model` / `workspace context` — schemas in [contracts/workspace-intelligence/](../contracts/workspace-intelligence/)
+- Canonical intelligence gate: `workspace intelligence run --for-agent codex --strict --json`
+- Broader CI release gate: [commands-reference.md](./commands-reference.md) (`pipeline`, `readiness`)
+- Targeted model/context inspection — schemas in [contracts/workspace-intelligence/](../contracts/workspace-intelligence/)
 
 ## Operations & security
 
@@ -71,7 +98,7 @@ Regenerate and verify:
 ```bash
 npm run generate:contracts
 npm run check:generated-contracts
-npm run validate:contracts
+npm run contracts:validate
 ```
 
 ## Contributor documentation

package/docs/SECURITY.md

@@ -2,12 +2,10 @@
 
 ## Supported Versions
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.35.x (latest minor) | :white_check_mark: |
-| < 0.35.0 | :x: |
-
-During the `0.x` phase, only the latest minor line receives security fixes.
+During the `0.x` phase, only the latest published minor line receives security
+fixes. Check the [npm package](https://www.npmjs.com/package/workspai) and
+[changelog](../CHANGELOG.md) for the current supported line; older minor lines
+are unsupported.
 
 ## Known Security Considerations
 
@@ -46,12 +44,21 @@ When using Workspai:
 2. **Review generated code**: Always review the workspace structure before deployment
 3. **Use official releases**: Install from npm registry, not from git directly
 4. **Verify package integrity**: Use `npm audit` on your generated project
+5. **Treat executable config as code**: Prefer `workspai.config.json`; only use
+   `--trust-config` after reviewing JavaScript configuration.
+6. **Keep remote archives public-network-only**: Private and loopback archive
+   URLs are rejected unless `--allow-private-network` is explicitly supplied.
+7. **Constrain mirror targets**: Artifact targets are restricted to the managed
+   mirror directory and are committed only after integrity/policy verification.
 
 ## Security Scanning
 
 We use:
 - GitHub Security Advisories
 - npm audit (production dependencies)
+- CodeQL static analysis
+- Pull-request dependency review
+- CycloneDX SBOM generation
 - Dependabot for automated updates
 - Regular manual security reviews
 

package/docs/SETUP.md

@@ -4,6 +4,9 @@ Canonical setup reference for **maintainers** of the Workspai CLI.
 
 **End users:** start with [../README.md](../README.md), [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md), and [workspace-operations.md](./workspace-operations.md).
 
+Unless noted otherwise, run commands in this guide from `packages/cli`. From the
+monorepo root, use `npm --workspace workspai run <script>`.
+
 ## Prerequisites
 
 - Node.js `>= 20.19.0`
@@ -19,14 +22,14 @@ npm ci
 npm run build
 npm run validate
 npm run validate:docs
-npm run validate:contracts
+npm run contracts:validate
 ```
 
 | Command | Purpose |
 | --- | --- |
 | `validate` | typecheck + lint + format + tests |
 | `validate:docs` | markdown links, drift guard, doc examples, README smoke |
-| `validate:contracts` | generated JSON contracts + parity tests |
+| `contracts:validate` | generated/shared contracts, parity, runtime conformance, and adversarial gates |
 
 See [ci-workflows.md](./ci-workflows.md) for GitHub Actions mapping.
 
@@ -38,7 +41,7 @@ npm run build
 node dist/index.js --help
 node dist/index.js --version
 
-node dist/index.js create workspace test-ws --yes --profile polyglot
+node dist/index.js create workspace test-ws --here --yes --profile polyglot
 node dist/index.js workspace list
 cd test-ws
 node ../dist/index.js bootstrap --profile polyglot

package/docs/UTILITIES.md

@@ -36,9 +36,9 @@ await cache.clear();
 ### Cache Features
 - **Memory cache** for fast access
 - **Disk cache** for persistence
-- **TTL**: 24 hours (configurable)
+- **TTL**: fixed at 24 hours
 - **Versioning**: Version support
-- **Automatic cleanup**: Auto-removal of expired cache
+- **Lazy cleanup**: Expired disk entries are removed when read
 
 ## Performance Monitoring
 
@@ -138,18 +138,11 @@ const user = await fetchUserData('123');
 // Second time: Reads from cache (fast)
 ```
 
-## Environment Variables
+## Debugging
 
-```bash
-# Enable debug mode to see cache hits/misses
-DEBUG=rapidkit:cache npm run dev
-
-# Enable performance logging
-DEBUG=rapidkit:perf npm run dev
-
-# Enable all
-DEBUG=rapidkit:* npm run dev
-```
+These utilities do not implement `DEBUG=rapidkit:*` namespace handling. Use the
+CLI's supported `--debug` flag where available, or enable `logger.setDebug(true)`
+in a focused maintainer harness.
 
 ## Testing
 
@@ -211,11 +204,6 @@ chmod 700 "$HOME/.workspai/cache"
 ```
 
 ### Incorrect performance metrics
-```bash
-# Make sure you're in debug mode
-export DEBUG=rapidkit:perf
-npm run dev
 
-# Check memory usage
-node --expose-gc --max-old-space-size=4096 dist/index.js
-```
+Verify that each timer is started and ended exactly once. For focused memory
+diagnostics, run `node --expose-gc --max-old-space-size=4096 dist/index.js`.

package/docs/WORKSPACE_MARKER_SPEC.md

@@ -12,7 +12,7 @@ The `.workspai-workspace` file is the canonical marker that identifies a Workspa
 {
   "signature": "RAPIDKIT_WORKSPACE",
   "createdBy": "workspai-cli",
-  "version": "0.15.1",
+  "version": "<workspai-version>",
   "createdAt": "2026-02-01T12:23:31.993Z",
   "name": "workspace-name",
   "metadata": { ... }
@@ -36,20 +36,22 @@ The metadata layer allows each tool to store its own information without conflic
 {
   "metadata": {
     "vscode": {
-      "extensionVersion": "0.5.0",
+      "extensionVersion": "<extension-version>",
       "createdViaExtension": true,
       "lastOpenedAt": "2026-02-01T14:30:00.000Z",
       "openCount": 5
     },
     "npm": {
-      "packageVersion": "0.15.1",
+      "packageVersion": "<workspai-version>",
       "installMethod": "poetry",
       "lastUsedAt": "2026-02-01T12:23:31.993Z"
     },
     "python": {
-      "coreVersion": "0.2.1",
+      "coreVersion": "<rapidkit-core-version>",
       "pythonVersion": "3.10",
-      "venvPath": ".venv"
+      "venvPath": ".venv",
+      "coreStatus": "installed",
+      "coreReason": "workspace profile requires Python Core"
     },
     "custom": {
       "myTool": "data"
@@ -82,6 +84,8 @@ The metadata layer allows each tool to store its own information without conflic
 | `coreVersion` | `string` | RapidKit Core version |
 | `pythonVersion` | `string` | Python version used |
 | `venvPath` | `string` | Virtual environment path (relative) |
+| `coreStatus` | `"installed" \| "skipped"` | Whether the optional Python engine is installed |
+| `coreReason` | `string` | Reason for the current engine state |
 
 ## Usage Guidelines
 
@@ -91,7 +95,7 @@ The metadata layer allows each tool to store its own information without conflic
 ```typescript
 import { createNpmWorkspaceMarker, writeWorkspaceMarker } from './workspace-marker';
 
-const marker = createNpmWorkspaceMarker('my-workspace', '0.15.1', 'poetry');
+const marker = createNpmWorkspaceMarker('my-workspace', '<workspai-version>', 'poetry');
 await writeWorkspaceMarker('/path/to/workspace', marker);
 ```
 
@@ -100,7 +104,7 @@ await writeWorkspaceMarker('/path/to/workspace', marker);
 // Let npm create the marker, then add VS Code metadata
 await updateWorkspaceMetadata(workspacePath, {
   vscode: {
-    extensionVersion: '0.5.0',
+    extensionVersion: '<extension-version>',
     createdViaExtension: true,
     lastOpenedAt: new Date().toISOString(),
     openCount: 1,
@@ -127,18 +131,21 @@ if (marker) {
 
 ### Updating Metadata
 
-**Always use `updateWorkspaceMetadata()` to preserve existing metadata:**
+Prefer `updateWorkspaceMetadata()` for nested metadata updates. The marker writer
+preserves existing top-level metadata namespaces, but can replace core fields or
+an individual nested namespace value; it is not a deep-merge API.
 
 ```typescript
 // ✅ Correct - preserves other metadata
 await updateWorkspaceMetadata(workspacePath, {
   vscode: {
-    extensionVersion: '0.5.0',
+    extensionVersion: '<extension-version>',
+    createdViaExtension: false,
     lastOpenedAt: new Date().toISOString(),
   },
 });
 
-// ❌ Wrong - overwrites entire marker
+// Use direct writes only when intentionally replacing core marker fields.
 await writeWorkspaceMarker(workspacePath, newMarker);
 ```
 
@@ -172,10 +179,10 @@ Old format (Extension-specific):
 {
   "signature": "RAPIDKIT_WORKSPACE",
   "createdBy": "rapidkit-vscode",
-  "version": "0.15.1",
+  "version": "<legacy-tool-version>",
   "createdAt": "2026-02-01T12:24:21.830Z",
   "name": "alef",
-  "vscodeVersion": "0.5.0",
+  "vscodeVersion": "<legacy-extension-version>",
   "originalCreatedBy": "rapidkit-npm"
 }
 ```
@@ -185,12 +192,12 @@ New format (standardized):
 {
   "signature": "RAPIDKIT_WORKSPACE",
   "createdBy": "workspai-cli",
-  "version": "0.15.1",
+  "version": "<workspai-version>",
   "createdAt": "2026-02-01T12:24:21.830Z",
   "name": "alef",
   "metadata": {
     "vscode": {
-      "extensionVersion": "0.5.0",
+      "extensionVersion": "<extension-version>",
       "createdViaExtension": true,
       "lastOpenedAt": "2026-02-01T12:24:21.830Z",
       "openCount": 1
@@ -222,16 +229,16 @@ Result:
 {
   "signature": "RAPIDKIT_WORKSPACE",
   "createdBy": "workspai-cli",
-  "version": "0.15.1",
+  "version": "<workspai-version>",
   "createdAt": "2026-02-01T10:00:00.000Z",
   "name": "my-workspace",
   "metadata": {
     "npm": {
-      "packageVersion": "0.15.1",
+      "packageVersion": "<workspai-version>",
       "installMethod": "poetry"
     },
     "vscode": {
-      "extensionVersion": "0.5.0",
+      "extensionVersion": "<extension-version>",
       "createdViaExtension": false,
       "lastOpenedAt": "2026-02-01T11:00:00.000Z",
       "openCount": 1
@@ -253,16 +260,16 @@ Result:
 {
   "signature": "RAPIDKIT_WORKSPACE",
   "createdBy": "workspai-cli",
-  "version": "0.15.1",
+  "version": "<workspai-version>",
   "createdAt": "2026-02-01T10:00:00.000Z",
   "name": "my-workspace",
   "metadata": {
     "npm": {
-      "packageVersion": "0.15.1",
+      "packageVersion": "<workspai-version>",
       "installMethod": "poetry"
     },
     "vscode": {
-      "extensionVersion": "0.5.0",
+      "extensionVersion": "<extension-version>",
       "createdViaExtension": true,
       "lastOpenedAt": "2026-02-01T10:00:00.000Z",
       "openCount": 1

package/docs/ci-workflows.md

@@ -12,6 +12,13 @@ Map of GitHub Actions workflows in this repository. Use this when editing CI to
 | E2E smoke                | `.github/workflows/e2e-smoke.yml`                | Focused bridge regression smoke                                           |
 | Frontend generator smoke | `.github/workflows/frontend-generator-smoke.yml` | Official frontend generator drift gate                                    |
 | Security                 | `.github/workflows/security.yml`                 | Security scanning and policy checks                                       |
+| Manual npm release       | `.github/workflows/release-npm-manual.yml`       | Maintainer-only release gate and publish workflow                          |
+| Contributor onboarding   | `.github/workflows/contributor-onboarding.yml`   | Accepted-contributor onboarding automation                                |
+| Welcome                  | `.github/workflows/welcome.yml`                  | First-issue and first-contribution messages                                |
+
+The release workflow requires `Frontend Generator Smoke` for the exact release
+SHA. Maintainers must dispatch that workflow against the intended release ref
+before starting a manual npm release if no matching run exists.
 
 ## Consumer workspace: agent grounding CI
 
@@ -22,13 +29,20 @@ For Workspai **consumer workspaces** (not this CLI repo), use the copy-paste tem
 Minimal job:
 
 ```yaml
-- run: npx workspai pipeline --json --strict
-- run: npx workspai workspace agent-sync --write --refresh-context --strict --json --preset enterprise
+- run: npx workspai workspace intelligence run --for-agent codex --strict --json
+- run: npx workspai pipeline --json --strict --no-agent-sync
 - run: node ./node_modules/workspai/scripts/check-agent-customization-drift.mjs --workspace .
 ```
 
-`pipeline` writes governance evidence and **auto-syncs** agent grounding (`AGENTS.md`, Copilot, Cursor, Claude) unless `RAPIDKIT_NO_AGENT_SYNC=1` or `--no-agent-sync`.
-Run the drift check after `agent-sync --write` so CI fails when generated agent customization files are stale.
+The canonical runner owns ordered evidence and agent grounding. The separate
+pipeline uses `--no-agent-sync` so it cannot rewrite those surfaces afterward.
+Run the drift check last so CI fails when generated customization files are stale.
+Runner exit `1` is a hard execution failure; exit `2` is a completed but
+evidence-blocked run and must also block release. When evidence must be uploaded
+after either outcome, follow the `continue-on-error` plus final-failure pattern
+in the template. See
+[Unified Workspace Intelligence Runner](./workspace-intelligence-runner.md) for
+the exact preflight, 11-stage, artifact, and exit contract.
 
 ## Local validation scripts
 
@@ -48,7 +62,7 @@ Run the drift check after `agent-sync --write` so CI fails when generated agent
 npm run validate
 npm run validate:docs
 npm run security
-npm run security
+npm run contracts:validate
 npm run test:runtime-matrix:full
 ```