workspai 0.45.0 → 0.47.0

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,8 +2,32 @@
 
 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
 
+- [Choose a guide by goal](#choose-a-guide-by-goal)
 - [User documentation](#user-documentation)
 - [Operations & security](#operations--security)
 - [AI module recommendations](#ai-module-recommendations)
@@ -11,78 +35,103 @@ Hub for user and contributor documentation. Start with the [main README](../READ
 - [Contributor documentation](#contributor-documentation)
 - [Validation commands](#validation-commands)
 
+## Choose a guide by goal
+
+| I want to…                                     | Start here                                                                | Expected outcome                                                      |
+| ---------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Create a workspace or project                  | [Creating workspaces and projects](./creating-workspaces-and-projects.md) | A registered project with canonical `.workspai` metadata              |
+| Bring an existing repository under governance  | [Workspace operations](./workspace-operations.md#import-and-adoption)     | Source stays in place with `adopt`, or is copied/cloned with `import` |
+| Run the complete intelligence loop             | [Unified runner](./workspace-intelligence-runner.md)                      | One ordered run report with durable stage evidence                    |
+| Ask an architecture or dependency question     | [Workspace Knowledge Graph](./workspace-knowledge-graph.md)               | A bounded answer with proof references rather than the whole graph    |
+| Integrate CI or release gates                  | [CI workflows](./ci-workflows.md)                                         | Machine-readable exit codes and uploadable evidence                   |
+| Find the writer, schema, or path for an output | [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md)                       | One canonical source instead of path guessing                         |
+| Understand Workspai terminology                | [Glossary](./GLOSSARY.md)                                                 | Shared meanings for model, graph, evidence, gate, and artifacts       |
+| Contribute to the CLI                          | [Development](./DEVELOPMENT.md)                                           | Local build, test, contract, and documentation gates                  |
+
+There are two different AI-facing features. Workspace Intelligence is
+deterministic, proof-backed, and does not require an AI API key. The optional
+module recommender uses embeddings to suggest FastAPI or NestJS modules; start
+with [AI Quickstart](./AI_QUICKSTART.md) only when that is your goal.
+
 ## User documentation
 
-| Document | Description |
-| --- | --- |
-| [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`) |
-| [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 |
-| [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md) | Role-based workflows (junior → enterprise) |
-| [doctor-command.md](./doctor-command.md) | Doctor scopes, CI exit codes, JSON evidence |
-| [config-file-guide.md](./config-file-guide.md) | User config file (`~/.workspairc.json`, `workspai.config.*`, with legacy fallbacks) |
-| [WORKSPACE_MARKER_SPEC.md](./WORKSPACE_MARKER_SPEC.md) | Workspace marker format |
-| [PACKAGE_MANAGER_POLICY.md](./PACKAGE_MANAGER_POLICY.md) | npm-only policy for this repository |
+| 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   |
+| [workspace-knowledge-graph.md](./workspace-knowledge-graph.md)                                 | Two-minute graph quickstart, proof model, AI/MCP consumption, performance, and honest token-efficiency measurement |
+| [graph-benchmark-methodology.md](./graph-benchmark-methodology.md)                             | Reproducible payload-reduction benchmark, formulas, claim boundaries, and publication rules                        |
+| [GLOSSARY.md](./GLOSSARY.md)                                                                   | Plain-language definitions for workspace, model, graph, evidence, gates, and AI integrations                       |
+| [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                                                                     |
+| [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md)                               | Role-based workflows (junior → enterprise)                                                                         |
+| [doctor-command.md](./doctor-command.md)                                                       | Doctor scopes, CI exit codes, JSON evidence                                                                        |
+| [config-file-guide.md](./config-file-guide.md)                                                 | User config file (`~/.workspairc.json`, `workspai.config.*`, with legacy fallbacks)                                |
+| [WORKSPACE_MARKER_SPEC.md](./WORKSPACE_MARKER_SPEC.md)                                         | Workspace marker format                                                                                            |
+| [PACKAGE_MANAGER_POLICY.md](./PACKAGE_MANAGER_POLICY.md)                                       | npm-only policy for this repository                                                                                |
 
 **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
 
-| Document | Description |
-| --- | --- |
-| [SECURITY.md](./SECURITY.md) | Vulnerability reporting and supported versions |
-| [policies.workspace.example.yml](./policies.workspace.example.yml) | Workspace policy template |
-| [governance-policy.enterprise.example.json](./governance-policy.enterprise.example.json) | Sigstore governance allowlist template |
-| [mirror-config.enterprise.example.json](./mirror-config.enterprise.example.json) | Mirror + evidence export template |
+| Document                                                                                 | Description                                    |
+| ---------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| [SECURITY.md](./SECURITY.md)                                                             | Vulnerability reporting and supported versions |
+| [policies.workspace.example.yml](./policies.workspace.example.yml)                       | Workspace policy template                      |
+| [governance-policy.enterprise.example.json](./governance-policy.enterprise.example.json) | Sigstore governance allowlist template         |
+| [mirror-config.enterprise.example.json](./mirror-config.enterprise.example.json)         | Mirror + evidence export template              |
 
 ## AI module recommendations
 
 FastAPI/NestJS module suggestions via OpenAI embeddings (optional).
 
-| Document | Description |
-| --- | --- |
-| [AI_QUICKSTART.md](./AI_QUICKSTART.md) | 60-second setup |
-| [AI_FEATURES.md](./AI_FEATURES.md) | Complete feature reference |
-| [AI_EXAMPLES.md](./AI_EXAMPLES.md) | Use-case examples |
-| [AI_DYNAMIC_INTEGRATION.md](./AI_DYNAMIC_INTEGRATION.md) | Integration architecture |
+| Document                                                 | Description                |
+| -------------------------------------------------------- | -------------------------- |
+| [AI_QUICKSTART.md](./AI_QUICKSTART.md)                   | 60-second setup            |
+| [AI_FEATURES.md](./AI_FEATURES.md)                       | Complete feature reference |
+| [AI_EXAMPLES.md](./AI_EXAMPLES.md)                       | Use-case examples          |
+| [AI_DYNAMIC_INTEGRATION.md](./AI_DYNAMIC_INTEGRATION.md) | Integration architecture   |
 
 ## Technical contracts
 
 JSON schemas and ownership rules for tooling parity.
 
-| Location | Description |
-| --- | --- |
-| [contracts/README.md](./contracts/README.md) | Core CLI JSON contracts + generator scripts |
-| [contracts/COMMAND_OWNERSHIP_MATRIX.md](./contracts/COMMAND_OWNERSHIP_MATRIX.md) | npm wrapper vs Core command ownership |
-| [contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md) | Scaffold/import/lifecycle support tiers |
-| [contracts/RUNTIME_ACCEPTANCE_MATRIX.md](./contracts/RUNTIME_ACCEPTANCE_MATRIX.md) | Runtime acceptance test expectations |
-| [../contracts/](../contracts/) | Canonical JSON schemas (published in npm tarball) |
+| Location                                                                           | Description                                       |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------- |
+| [contracts/README.md](./contracts/README.md)                                       | Core CLI JSON contracts + generator scripts       |
+| [contracts/COMMAND_OWNERSHIP_MATRIX.md](./contracts/COMMAND_OWNERSHIP_MATRIX.md)   | npm wrapper vs Core command ownership             |
+| [contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md)       | Scaffold/import/lifecycle support tiers           |
+| [contracts/RUNTIME_ACCEPTANCE_MATRIX.md](./contracts/RUNTIME_ACCEPTANCE_MATRIX.md) | Runtime acceptance test expectations              |
+| [../contracts/](../contracts/)                                                     | Canonical JSON schemas (published in npm tarball) |
 
 Regenerate and verify:
 
 ```bash
 npm run generate:contracts
 npm run check:generated-contracts
-npm run validate:contracts
+npm run contracts:validate
 ```
 
 ## Contributor documentation
 
-| Document | Description |
-| --- | --- |
-| [DEVELOPMENT.md](./DEVELOPMENT.md) | Local dev, testing, debugging |
-| [SETUP.md](./SETUP.md) | Build gates, smoke flows, release hygiene |
-| [ci-workflows.md](./ci-workflows.md) | GitHub Actions workflow map |
-| [OPTIMIZATION_GUIDE.md](./OPTIMIZATION_GUIDE.md) | Performance and improvement notes |
-| [UTILITIES.md](./UTILITIES.md) | Internal cache and metrics helpers |
+| Document                                         | Description                               |
+| ------------------------------------------------ | ----------------------------------------- |
+| [DEVELOPMENT.md](./DEVELOPMENT.md)               | Local dev, testing, debugging             |
+| [SETUP.md](./SETUP.md)                           | Build gates, smoke flows, release hygiene |
+| [ci-workflows.md](./ci-workflows.md)             | GitHub Actions workflow map               |
+| [OPTIMIZATION_GUIDE.md](./OPTIMIZATION_GUIDE.md) | Performance and improvement notes         |
+| [UTILITIES.md](./UTILITIES.md)                   | Internal cache and metrics helpers        |
 
 Also see [../CONTRIBUTING.md](../CONTRIBUTING.md) and [../CHANGELOG.md](../CHANGELOG.md).
 

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
 ```