workspai 0.44.0 → 0.46.0

package/docs/commands-reference.md

@@ -6,7 +6,7 @@ Complete CLI syntax for the Workspai CLI. For behavior and workflows, see [works
 
 ```bash
 npx workspai create # Prompts: workspace | project
-npx workspai create workspace <name> [--profile <profile>] [--author <name>] [--yes] [--here|--output <parent-dir>] [--skip-python-engine]
+npx workspai create workspace <name> [--profile <profile>] [--yes] [--here|--output <parent-dir>] [--skip-python-engine] [--skip-git] [--dry-run] [--install-method <poetry|venv|pipx>]
 npx workspai bootstrap [--profile <profile>] [--ci] [--json] [--compliance-only]
 npx workspai setup <python|node|go|java|dotnet> [--warm-deps]
 npx workspai pipeline [--json] [--strict] [--skip-verify] [--skip-analyze] [--skip-autopilot] [--autopilot-mode <audit|safe-fix|enforce>] [--agent-sync|--no-agent-sync]
@@ -17,6 +17,13 @@ npx workspai autopilot release [--mode <audit|safe-fix|enforce>] [--json] [--out
 
 Recommended CI:
 
+```bash
+npx workspai workspace intelligence run --for-agent codex --strict --json
+```
+
+Run the broader governance and release orchestrators as separate gates; they
+do not extend or redefine the canonical Workspace Intelligence chain:
+
 ```bash
 npx workspai pipeline --json --strict
 npx workspai autopilot release --mode enforce --json --output .workspai/reports/autopilot-release.json
@@ -49,6 +56,7 @@ npx workspai workspace contract init [--force] [--json]
 npx workspai workspace contract inspect [--json]
 npx workspai workspace contract verify [--strict] [--json]
 npx workspai workspace contract graph [--json]
+npx workspai workspace intelligence run [--workspace <path>] [--for-agent <agent>] [--strict] [--json]
 npx workspai workspace model [--workspace <path>] [--json] [--write] [--strict] [--cache] [--incremental] [--include-paths] [--include-evidence] [--scan-depth <count>]
 npx workspai workspace context --for-agent [codex|claude|cursor|orca] [--workspace <path>] [--json] [--write] [--agent-sync|--no-agent-sync] [--target <targets>] [--preset minimal|enterprise] [--include-evidence] [--scan-depth <count>]
 npx workspai workspace agent-sync [--workspace <path>] [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|agents,copilot,cursor,claude,codex,orca] [--experimental-hooks] [--hydrate-prompts]
@@ -61,15 +69,15 @@ npx workspai workspace graph [emit|explain|dot|mermaid] [key] [--workspace <path
 npx workspai workspace watch [--workspace <path>] [--json] [--once] [--scan-depth <count>]
 npx workspai workspace explain|why <target> [--workspace <path>] [--json] [--write]
 npx workspai workspace trace --from <workspace-diff-report> [--workspace <path>] [--json] [--write]
-npx workspai workspace feedback record [--workspace <path>] [--json]
+printf '%s\n' '{"actionId":"fix-api","summary":"API tests passed","outcome":"ok"}' | npx workspai workspace feedback record [--workspace <path>] --json
 npx workspai workspace mcp serve [--workspace <path>] [--json]
 npx workspai workspace export --output team-workspace.workspai-archive.zip [--archive-compression store|deflate]
-npx workspai workspace archive inspect team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--json]
-npx workspai workspace archive verify team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--strict] [--json]
-npx workspai workspace archive doctor team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--strict] [--json]
-npx workspai workspace hydrate team-workspace.workspai-archive.zip --output ./team-workspace [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>]
-npx workspai import <path|git-url> [--workspace <path>] [--name <project-name>] [--git] [--json]
-npx workspai adopt [path] [--workspace <path>] [--name <project-name>] [--dry-run] [--json]
+npx workspai workspace archive inspect team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network] [--json]
+npx workspai workspace archive verify team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network] [--strict] [--json]
+npx workspai workspace archive doctor team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network] [--strict] [--json]
+npx workspai workspace hydrate team-workspace.workspai-archive.zip --output ./team-workspace [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network]
+npx workspai import <path|git-url> [--workspace <path>] [--name <project-name>] [--git] [--enable-modules] [--json]
+npx workspai adopt [path] [--workspace <path>] [--name <project-name>] [--enable-modules] [--dry-run] [--json]
 npx workspai snapshot create [name] [--include-projects] [--reason <text>] [--json]
 npx workspai snapshot list [--json]
 npx workspai snapshot inspect <name> [--json]
@@ -86,6 +94,30 @@ npx workspai infra down [--workspace <path>] [--volumes]
 npx workspai infra status [--workspace <path>] [--json] [--strict]
 ```
 
+`workspace intelligence run` writes
+`.workspai/reports/workspace-intelligence-run-last-run.json`. Its `preflight`
+contains exactly `sync` and `baseline`, while `stages` contains exactly the 11
+ordered canonical chain steps. Exit `0` is passed, `1` is a hard execution
+failure, and `2` is a completed but evidence-blocked run. With `--strict`,
+warning-grade Analyze and Readiness verdicts can block the run without becoming
+execution failures. See
+[Unified Workspace Intelligence Runner](./workspace-intelligence-runner.md) for
+baseline creation/reuse, JSON fields, artifact invariants, skip propagation, and
+CI handling.
+
+`workspace feedback record` is a non-interactive machine interface. It requires
+exactly one JSON object on stdin and `--json`; an empty stdin or interactive TTY
+is rejected. Required fields are `actionId`, `summary`, and `outcome`. The
+accepted outcome values and optional scope/evidence fields are governed by
+`contracts/workspace-intelligence/agent-action-outcome.v1.json`. Successful
+records are appended to
+`.workspai/reports/workspace-intelligence-history.json`; no separate feedback
+artifact is created.
+
+`workspace graph dot` and `workspace graph mermaid` intentionally emit raw DOT
+and Mermaid text for direct piping to renderers. Use `workspace graph emit
+--json` or `workspace graph explain <project> --json` for structured JSON.
+
 See [workspace-run.md](./workspace-run.md) for fleet orchestration semantics.
 
 After cloning or moving an existing workspace, `workspace sync` repairs its
@@ -109,11 +141,14 @@ for every project that happens to use a first-class framework. For example, an
 arbitrary existing FastAPI application can be adopted and modeled as a
 Python/FastAPI project, but module mutation remains disabled unless its RapidKit
 project metadata identifies one of those module-enabled kits.
+`--enable-modules` preserves module commands only when existing RapidKit
+metadata already identifies a module-enabled kit; it does not enable Core module
+mutation for an arbitrary detected framework.
 
 ## Project lifecycle
 
 ```bash
-npx workspai create project <kit> <name> [--yes] [--skip-install] [--skip-git] [--output <dir>]
+npx workspai create project <kit> <name> [--yes] [--skip-install] [--skip-git] [--dry-run] [--output <dir>] [--create-workspace|--no-workspace]
 npx workspai project commands [--json]
 npx workspai commands --scope project [--json]
 npx workspai init
@@ -130,6 +165,11 @@ npx workspai create project fastapi.standard my-api --yes
 npx workspai create project nextjs my-web --yes
 ```
 
+Generator-specific options include `--port`, Spring Boot
+`--java-version`/`--spring-version`/`--package-name`/`--group-id`/`--artifact-id`,
+and .NET `--dotnet-version`/`--target-framework`/`--nullable`. Use
+`npx workspai create project --help` for the live option inventory.
+
 `create frontend <id> <name>` is still accepted and routes to the same generators.
 
 `project commands` shows the effective command contract for the current project. Core-backed FastAPI/NestJS projects can use module commands such as `add` and `modules`. Frontend apps, Go, Spring Boot, .NET, and adopted/imported repositories use runtime lifecycle commands and workspace governance while Core module mutation remains disabled.
@@ -151,7 +191,8 @@ See [workspace-operations.md](./workspace-operations.md#workspace-infrastructure
 - `python-only` — Python-focused workspace
 - `node-only` — Node.js-focused workspace
 - `go-only` — Go-focused workspace
-- `polyglot` — Python + Node.js + Go + Java
+- `dotnet-only` — .NET-focused workspace
+- `polyglot` — Python + Node.js + Go + Java + .NET
 - `enterprise` — polyglot + governance-oriented checks
 
 ## Policy modes

package/docs/config-file-guide.md

@@ -1,299 +1,116 @@
-# 📖 Workspai Config File Guide
+# Workspai Configuration Guide
 
-## 🎯 Purpose of `workspai.config.cjs`
+Workspai has two configuration surfaces with different scopes. Command-line
+flags remain authoritative when a command supports the corresponding option.
 
-The `workspai.config.cjs` file is an **optional configuration file** that allows you to define default settings for creating workspaces and projects.
+## User configuration
 
----
+`~/.workspairc.json` stores user-level settings. The legacy
+`~/.rapidkitrc.json` path is read only when the canonical file is absent.
 
-## 📍 File Location
+Supported fields include:
 
-```
-📁 Your Project Directory (where you run npx workspai)
-├── workspai.config.cjs      ← Config file (create manually)
-├── package.json
-└── ...
-```
-
-**Important Note**: This file is **not automatically created**. You must create it manually.
-
----
-
-## 🔍 When to Use
-
-### 1️⃣ **Team Development**
-
-```javascript
-// workspai.config.cjs
-module.exports = {
-  workspace: {
-    defaultAuthor: 'Your Team Name',
-    pythonVersion: '3.10',
-    installMethod: 'poetry'
-  }
-}
-```
-
-**Result**: All team members create workspaces with identical settings.
-
----
-
-### 2️⃣ **CI/CD Automation**
-
-```javascript
-// workspai.config.cjs for CI/CD
-module.exports = {
-  workspace: {
-    defaultAuthor: 'CI Bot',
-    pythonVersion: '3.11',
-    installMethod: 'venv'
-  },
-  projects: {
-    skipGit: true,        // No git init needed in CI
-    skipInstall: false
-  }
-}
-```
-
-**Usage**:
-```bash
-# In CI/CD pipeline
-npx workspai my-workspace --yes
-# Uses config without prompts
-```
-
----
-
-### 3️⃣ **Personal Projects**
-
-```javascript
-// workspai.config.cjs
-module.exports = {
-  workspace: {
-    defaultAuthor: 'John Doe',
-    pythonVersion: '3.12'
-  },
-  projects: {
-    defaultKit: 'fastapi.standard',     // Always use FastAPI standard template
-    addDefaultModules: [
-      'prisma',
-      'redis', 
-      'auth-jwt',
-      'monitoring'
-    ]
-  }
+```json
+{
+  "defaultKit": "fastapi.standard",
+  "defaultInstallMethod": "poetry",
+  "pythonVersion": "3.11",
+  "author": "Platform Team",
+  "license": "MIT",
+  "skipGit": false,
+  "aiEnabled": true,
+  "telemetry": false
 }
 ```
 
-**Result**: Every new project comes with these modules pre-configured.
-
----
-
-## 📝 Supported File Formats
+The `workspai config` command owns persisted AI settings such as the OpenAI API
+key and `aiEnabled`. Do not commit user configuration or API keys.
 
-| File | Description |
-|------|-------------|
-| `workspai.config.cjs` | CommonJS explicit, safest across package types |
-| `workspai.config.js` | CommonJS unless the project package uses `"type": "module"` |
-| `workspai.config.mjs` | Explicit ES Module |
-| `rapidkit.config.*` | Legacy fallback, still read during migration |
+## Directory configuration
 
-Use `workspai.config.mjs` when you prefer `export default`.
+The CLI can discover the nearest configuration file while walking from the
+current directory toward the filesystem root:
 
----
-
-## ⚙️ Available Configuration Options
-
-### **workspace** (Workspace Settings)
-
-```typescript
-workspace: {
-  defaultAuthor?: string;        // Author/team name
-  pythonVersion?: '3.10' | '3.11' | '3.12';  // Python version
-  installMethod?: 'poetry' | 'venv' | 'pipx';  // Core installation method
-}
-```
+- `workspai.config.json` (recommended; data-only and safe by default)
+- `workspai.config.cjs`
+- `workspai.config.mjs`
+- `workspai.config.js`, when its syntax matches the containing package type
+- `rapidkit.config.*`, as a legacy fallback
 
-### **projects** (Project Settings)
+JavaScript configuration is executable code. The CLI refuses to import it
+unless trust is explicit:
 
-```typescript
-projects: {
-  defaultKit?: string;           // Default template
-  addDefaultModules?: string[];  // Default modules to install
-  skipGit?: boolean;             // Skip git initialization
-  skipInstall?: boolean;         // Skip npm install
-}
-```
-
----
-
-## 🔄 Configuration Priority
-
-```
-CLI Arguments > workspai.config.* > .workspairc.json > legacy rapidkit config > Defaults
-```
-
-**Example**:
 ```bash
-# Config file: author='Team A'
-npx workspai my-workspace --author "Team B"
-# Result: author='Team B' (CLI overrides config)
+npx workspai my-workspace --trust-config
+# Non-interactive equivalent for controlled CI:
+WORKSPAI_TRUST_CONFIG=1 npx workspai my-workspace
 ```
 
----
+Do not trust executable configuration from an unreviewed repository. Prefer
+`workspai.config.json` whenever computed values are not required.
 
-## 📋 Complete Example
+Example:
 
 ```javascript
-/**
- * Workspai Configuration
- * Place in project root before running `npx workspai`
- */
+// workspai.config.cjs
 module.exports = {
-  // Workspace settings
   workspace: {
-    defaultAuthor: 'Workspai Dev Team',
-    pythonVersion: '3.10',
+    defaultAuthor: 'Platform Team',
+    pythonVersion: '3.11',
     installMethod: 'poetry',
   },
-  
-  // Project settings
   projects: {
     defaultKit: 'fastapi.standard',
-    
-    // Auto-add these modules to new projects
-    addDefaultModules: [
-      'prisma',          // Database ORM
-      'redis',           // Caching
-      'auth-jwt',        // Authentication
-      'monitoring',      // Observability
-    ],
-    
     skipGit: false,
-    skipInstall: false,
   },
 };
 ```
 
----
+## Command coverage
 
-## 🚀 Usage Examples
+Directory configuration is currently consumed by the legacy top-level creation
+shorthand, for example `npx workspai my-workspace`. Its effective precedence is:
 
-### Without Config File (Interactive):
-```bash
-npx workspai my-workspace
-# ❓ Prompts:
-#   - Author name?
-#   - Python version?
-#   - Install method?
+```text
+CLI flags > workspai.config.* > ~/.workspairc.json > legacy config > defaults
 ```
 
-### With Config File (Automated):
-```bash
-# 1. Create config
-cat > workspai.config.cjs << 'EOF'
-module.exports = {
-  workspace: {
-    defaultAuthor: 'My Team',
-    pythonVersion: '3.10',
-    installMethod: 'poetry'
-  }
-}
-EOF
+Canonical `create workspace` and `create project` flows do not currently apply
+all directory-config project defaults. In particular, `addDefaultModules` and
+`skipInstall` are reserved fields and are not automatically executed. Use
+explicit canonical command flags instead:
 
-# 2. Run Workspai
-npx workspai my-workspace --yes
-# ✅ No prompts, uses config defaults
+```bash
+npx workspai create workspace platform --profile polyglot --yes
+npx workspai create project fastapi.standard api --skip-install --yes
 ```
 
----
+Config discovery means a file can be loaded by a supported flow; it does not
+mean every command consumes every field. The
+[Command Reference](./commands-reference.md) is authoritative for command flags.
+
+## Debugging
 
-## 🔍 Debugging Configuration
+Use `--debug` on the legacy shorthand to inspect loaded and merged configuration:
 
 ```bash
-# Enable debug mode to see loaded config
 npx workspai my-workspace --debug
 ```
 
-Output:
-```
-[DEBUG] User config loaded {}
-[DEBUG] Workspai config loaded { workspace: { defaultAuthor: 'Team' } }
-[DEBUG] Merged config { author: 'Team', pythonVersion: '3.10' }
-```
-
----
-
-## 🎯 Common Use Cases
-
-### ✅ Recommended Uses:
+A malformed or untrusted executable config fails closed with its path and an
+actionable error.
 
-1. **Large Teams**: Standardize settings across developers
-2. **CI/CD**: Automate workspace creation
-3. **Personal Templates**: Always start with specific modules
-4. **Training/Workshops**: Ensure all participants have identical settings
+## Workspace policy is separate
 
-### ❌ Not Recommended:
-
-1. **One-time Use**: If you're only creating one workspace
-2. **Variable Settings**: If you need different settings each time
-3. **Quick Development**: For rapid testing, interactive prompts are faster
-
----
-
-## Additional resources
-
-- [Example config](../workspai.config.example.cjs)
-- [commands-reference.md](./commands-reference.md) — CLI syntax
-- [Documentation](https://workspai.dev/docs/config) (external)
-
----
-
-## 💡 Tips
-
-1. **Config is Optional**: You don't need to create this file
-2. **CLI Overrides**: You can always override config with command-line flags
-3. **Auto-detection**: CLI automatically discovers config files
-4. **Type Safety**: Use TypeScript types for IntelliSense support
-
----
-
-## 🔗 Related Commands
+Configuration files supply creation defaults. Runtime governance belongs to
+`.workspai/policies.yml` and should normally be managed through:
 
 ```bash
-# Create workspace with config
-npx workspai my-workspace --yes
-
-# Override config author
-npx workspai my-workspace --author "Different Author"
-
-# Check environment
-npx workspai doctor
-
-# Inspect/set workspace policy (recommended over manual YAML edits)
 npx workspai workspace policy show
 npx workspai workspace policy set mode strict
 npx workspai workspace policy set dependency_sharing_mode shared-runtime-caches
-npx workspai workspace policy set rules.enforce_toolchain_lock true
-
-# List available kits
-npx workspai list
-```
-
----
-
-## 🛡️ Workspace Policy vs `workspai.config.*`
-
-- `workspai.config.js|mjs|cjs` defines creation defaults and prompt behavior.
-- `rapidkit.config.*` remains supported as a legacy fallback.
-- `.workspai/policies.yml` defines runtime governance and enforcement behavior after workspace creation.
-- Preferred policy management path:
-
-```bash
-npx workspai workspace policy show
-npx workspai workspace policy set <key> <value>
 ```
 
----
-
-**Last updated:** June 2026 · **CLI version:** 0.35.x
+See the [example config](../workspai.config.example.cjs),
+[Creating Workspaces and Projects](./creating-workspaces-and-projects.md), and
+[Command Reference](./commands-reference.md).

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -86,8 +86,19 @@ the same evidence without losing the workspace source of truth.
 | `workspace agent-sync --write`                 | `reports/workspace-skills-index.json`                                                                                                                                                                                                                          | `workspace-skills-index.v1`            | `contracts/workspace-intelligence/workspace-skills-index.v1.json`         |
 | `workspace agent-sync --write`                 | `reports/workspai-mcp-design.json`, `.workspai/skills/*.md`, `.workspai/AGENT-GROUNDING.md`, `AGENTS.md`, IDE agent surfaces                                                                                                                                 | Mixed generated surfaces               | See customization pack output inventory                                  |
 | `workspace explain --write`                    | `workspace-explain-last-run.json`                                                                                                                                                                                                                            | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`              |
+| `workspace intelligence run`                   | `workspace-intelligence-run-last-run.json`                                                                                                                                                                                                                   | `workspace-intelligence-run.v1`        | `contracts/workspace-intelligence/workspace-intelligence-run.v1.json`     |
 | `workspace feedback record` / `doctor * --fix` | `workspace-intelligence-history.json` (`kind: agent-action`, `doctor-fix`)                                                                                                                                                                                   | `workspace-intelligence-history.v1`    | `contracts/workspace-intelligence/workspace-intelligence-history.v1.json` |
 
+The unified runner report separates its execution envelope from the canonical
+intelligence chain. `preflight` always contains exactly `sync` and `baseline`;
+baseline resolution runs after `model` and before `diff`, recording `created` or
+`reused`. `stages` always contains exactly the 11 ordered steps declared by
+`workspace-intelligence-chain.v1`. JSON Schema enforces the transport shape and
+the runtime semantic validator additionally enforces artifact parity,
+status/exit coherence, hard-failure skip propagation, and the aggregate verdict.
+See [Unified Workspace Intelligence Runner](../workspace-intelligence-runner.md)
+for the normative user and integration semantics.
+
 **CLI semantics:** `workspace diff --from` expects a **model or snapshot** baseline. `workspace impact --from` expects a **diff report**.
 Persisted artifacts retain their artifact schema. JSON command projections that add operation metadata
 such as `outputPath`, `status`, or structured errors use
@@ -261,7 +272,8 @@ Canonical source: `src/observability/run-correlation.ts` (`attachRunCorrelation`
 | `infra plan`                     | `infra-plan.json`                                                      | `rapidkit.infra-plan.v1`                                                                     | —                                                                    |
 | `workspace archive`              | `.workspai/archive-manifest.json` inside ZIP/ZIP64                     | Streaming handoff; workspace payload is unlimited by default and safety budgets are opt-in   | `contracts/workspace-archive-manifest.v1.json`                       |
 | `workspace share`                | `reports/share-bundle.json` (default)                                  | Aggregation bundle                                                                           | —                                                                    |
-| `import` / `adopt`               | `{project}/.workspai/import-readiness.json`                            | Per project                                                                                  | —                                                                    |
+| `import`                         | `{project}/.workspai/import.json`, `{project}/.workspai/import-readiness.json` | Copied/cloned project metadata and readiness                                           | —                                                                    |
+| `adopt`                          | `{project}/.workspai/adopt.json`, `{project}/.workspai/adopt-readiness.json`   | In-place project metadata and readiness                                                | —                                                                    |
 | `workspace contract verify`      | `workspace-contract-verify-last-run.json`                              | CLI verify cache                                                                             | `contracts/workspace-intelligence/workspace-contract-verify.v1.json` |
 
 ## Static capability contracts
@@ -311,7 +323,7 @@ Under `{project}/.workspai/reports/` when commands run at project scope (e.g. pr
 ## Consumer rules
 
 1. **Project count:** read `workspace-registry.v1.json` (or run `workspace registry status --json`).
-2. **Release gates:** follow chain doctor → analyze → readiness → verify → autopilot; use `pipeline-last-run.json` for orchestration summary.
+2. **Workspace Intelligence chain:** run `workspace intelligence run --for-agent codex --strict --json` to preserve Model → Diff → Impact → Doctor + Contract Verify + Analyze → Readiness → Verify → Context → Agent Sync → Explain. `pipeline` is the broader governance/release orchestrator and `autopilot` is a separate release surface; neither redefines the canonical chain. Use `pipeline-last-run.json` only for the pipeline orchestration summary.
 3. **Do not** use `workspace.json.projects` (removed in schema 1.0).
 4. Prefer `schemaVersion` constants in each artifact; legacy `v1` on readiness is accepted when reading old reports.
 5. **Agent customization:** read `.workspai/reports/agent-customization-pack.json` first for generated surfaces, then `.workspai/reports/INDEX.json` and `workspace-context-agent.json`; regenerate with `workspace agent-sync --write --refresh-context --preset enterprise`.

package/docs/contracts/CLI_LOG_EVENT_STREAM.md

@@ -75,7 +75,7 @@ Each stderr line is a single JSON object:
   "component": "cli",
   "message": "CLI run started",
   "command": ["workspace", "model"],
-  "metadata": { "cwd": "/path/to/workspace", "rapidkitVersion": "0.38.0" }
+  "metadata": { "cwd": "/path/to/workspace", "rapidkitVersion": "<workspai-version>" }
 }
 ```
 

package/docs/contracts/COMMAND_OWNERSHIP_MATRIX.md

@@ -32,23 +32,44 @@ These commands are implemented and orchestrated by Workspai CLI:
 - `product`
 - `infra`
 - `commands`
+- `create`
+- `project`
 - `shell activate`
 
 Reason: workspace-level policy, registry, and platform orchestration live in npm wrapper.
 
 ### 1.1) Wrapper-owned scoped commands
 
-These scoped commands are implemented and orchestrated by Workspai CLI:
-
+These nested Commander commands are implemented and orchestrated by Workspai CLI:
+
+- `ai generate-embeddings`
+- `ai info`
+- `ai recommend`
+- `ai update-embeddings`
+- `config ai`
+- `config remove-api-key`
+- `config set-api-key`
+- `config show`
+- `infra down`
+- `infra plan`
+- `infra status`
+- `infra up`
+- `product manifest`
+- `product manifest create`
+- `product plan`
 - `project commands`
 - `project archives`
 - `project archive`
 - `project restore`
 - `project delete`
-
-Reason: these are workspace project lifecycle and capability operations with
-archive manifests, safety snapshots, workspace registry side effects, and
-runtime-aware command discovery.
+- `snapshot create`
+- `snapshot inspect`
+- `snapshot list`
+- `snapshot restore`
+
+Reason: these routes are registered directly in the npm wrapper's live
+Commander tree. Their completeness is verified against `commands --json` and
+the generated runtime command surface during tests and prepack.
 
 `project detect` remains Core-owned because it is the stable machine-readable
 contract used by wrappers to detect Python RapidKit projects.

package/docs/contracts/README.md

@@ -12,7 +12,8 @@ Canonical JSON lives in **`../../contracts/`** (CLI package root, published in t
 | `npm run check:generated-contracts`       | Verify committed JSON matches generators                                                                              |
 | `npm run sync:parity-snapshot`            | Copy canonical → vscode `contracts/` mirror                                                                           |
 | `npm run check:parity-snapshot`           | Verify mirrors match canonical                                                                                        |
-| `npm run validate:contracts`              | Generate check + mirror check + contract tests                                                                        |
+| `npm run validate:contracts`              | Shared-contract checks and focused contract tests                                                                      |
+| `npm run contracts:validate`              | Comprehensive generated/shared contract, parity, runtime-conformance, and adversarial gate                            |
 | `npm run check:agent-customization-drift` | Verify generated agent customization files are committed in a consumer workspace                                      |
 
 Workflow: change code → `npm run generate:contracts` → `npm run sync:parity-snapshot` → commit npm + vscode `contracts/`.
@@ -46,6 +47,7 @@ Published under `../../contracts/` (not duplicated in this folder):
 
 Workspace intelligence (`../../contracts/workspace-intelligence/`):
 
+- `workspace-intelligence-run.v1.json` — authoritative full-chain result, stage outcomes, verdict, exit code, and durable artifact path
 - `workspace-model.v1.json`
 - `workspace-context.v1.json`
 - `workspace-dependency-graph.v1.json`
@@ -63,7 +65,8 @@ Workspace intelligence (`../../contracts/workspace-intelligence/`):
 - `doctor-fix-result.v1.json`
 - `studio-blocker-handoff.v1.json`
 
-CLI commands: see [commands-reference.md](../commands-reference.md) and [../README.md](../README.md#workspace-intelligence).
+CLI commands: see [commands-reference.md](../commands-reference.md) and the
+[CLI README](../../README.md#one-intelligence-chain).
 
 ## Core CLI JSON payloads
 

package/docs/contracts/RUNTIME_ACCEPTANCE_MATRIX.md

@@ -43,10 +43,10 @@ lifecycle failures only when the CLI prints actionable diagnostics such as
 
 The matrix verifies:
 
-- npm-owned global entrypoints: `--version` and `-v`.
-- global command ownership contract via `commands --json`, plus core-owned
-  catalog commands in default/full modes: `version`, `commands`, `list`,
-  `info`, `frameworks`, `modules`, and `license`.
+- npm-owned global entrypoints: `--version`, `-v`, and `commands --json`.
+- delegated Core catalog surfaces in default/full modes: `version`, `list`,
+  `info`, `frameworks`, `modules`, and `license`. The normal
+  `workspai --version` path remains wrapper-owned.
 - `create workspace` with a Python-free minimal profile.
 - `create project` for npm-backed Go Fiber, Go Gin, Spring Boot, and ASP.NET
   Core Clean Web API kits.