workspai 0.45.0 → 0.47.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]
@@ -57,19 +65,19 @@ npx workspai workspace snapshot [--workspace <path>] [--json] [--include-paths]
 npx workspai workspace diff --from <snapshot-or-report|git[:ref]> [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
 npx workspai workspace impact --from <workspace-diff-report> [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
 npx workspai workspace verify [--from-impact <file>] [--workspace <path>] [--scope project:<name>] [--strict] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
-npx workspai workspace graph [emit|explain|dot|mermaid] [key] [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
+npx workspai workspace graph [emit|explain|search|benchmark|entities|evidence|path|overlay|dot|mermaid] [key] [value] [--from <graph.json>] [--limit <1..100>] [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
 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]
 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,28 @@ npx workspai infra down [--workspace <path>] [--volumes]
 npx workspai infra status [--workspace <path>] [--json] [--strict]
 ```
 
+The contract graph includes its backward-compatible service projection, the
+canonical `workspace-dependency-graph.v1` project topology, and the portable
+`workspace-knowledge-graph.v1` evidence graph. The knowledge projection covers
+workspace/project structure, packages and dependencies, source files, modules,
+symbols, HTTP endpoints, OpenAPI/GraphQL/Protocol Buffers/AsyncAPI contracts,
+Compose/Kubernetes/Dockerfile/Terraform/Helm infrastructure, CI workflows,
+documentation, ADRs, tests, owners, environments, databases, and queues.
+Every entity and relation has stable identity and portable proof paths; proof
+taxonomy separates authored, extracted, and inferred facts and records trust,
+confidence, and freshness. Environment and secret values are never emitted.
+
+`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
@@ -95,9 +125,45 @@ 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.
+`workspace graph emit --json` returns both the compatibility project graph and
+the knowledge graph. Use `workspace graph entities [kind]`, `workspace graph
+evidence <id-or-unique-label>`, and `workspace graph path <from> <to>` for
+indexed queries. `workspace graph overlay --from <prior-graph.json>` produces a
+portable change/PR overlay with additions, removals, changed fields, proof
+artifacts, proof additions/removals/content changes, bounded one-hop impact,
+and a risk summary. Observation timestamps and freshness alone do not create
+false change noise. Query indexes are cached
+per immutable graph object and invalidated automatically when a new graph is
+built. `dot` and `mermaid` intentionally remain project-topology renderers and
+emit raw text for direct piping.
+
+`workspace graph search <query> --limit <n> --json` returns bounded entities,
+one-hop relations, related entity summaries, and portable proofs instead of the
+complete graph. `workspace graph benchmark <query> --limit <n> --json` compares
+that retrieval payload with the readable proof-indexed corpus using a labelled
+`characters / 4` estimate. It measures payload reduction only; it does not
+assert equivalent answer quality or model-specific billing savings.
+
+`workspace model --write` also materializes the derived, contract-validated
+knowledge graph at `.workspai/reports/workspace-knowledge-graph.json`. The
+unified intelligence runner treats that artifact as a required output of the
+Model step, so CI, IDE adapters, agent grounding, and MCP all observe the same
+revision. Agent contexts carry its reference, quality counts, and bounded query
+commands instead of copying the entire graph into every prompt. MCP exposes
+`getWorkspaceKnowledgeGraph`, `searchWorkspaceGraph`, `queryWorkspaceEntities`,
+`getWorkspaceGraphEvidence`, and `findWorkspaceGraphPath`.
+
+Source extraction is bounded and language-neutral by contract. It recognizes
+the primary source formats for TypeScript/JavaScript, Python, Go, Java/Kotlin,
+.NET/F#, Rust, Ruby, PHP, Swift, Dart, Elixir, Scala, Clojure, Lua, R, C/C++,
+Vue, and Svelte. Package baselines also recognize npm/Deno, Python, Go, Cargo,
+Maven/Gradle, NuGet, Composer, Ruby, Elixir, Dart, SwiftPM, CMake, Bazel, and SBT.
+Regex-backed
+source facts are marked `observed` with medium confidence; authored manifests
+and interface/infrastructure specifications remain authoritative. This avoids
+presenting heuristic symbol discovery as compiler-grade truth while keeping the
+current CLI useful until deeper language providers move into the standalone
+graph package.
 
 See [workspace-run.md](./workspace-run.md) for fleet orchestration semantics.
 
@@ -122,11 +188,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
@@ -143,6 +212,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.
@@ -164,7 +238,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,120 @@
-# 📖 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'
-    ]
-  }
-}
-```
-
-**Result**: Every new project comes with these modules pre-configured.
-
----
-
-## 📝 Supported File Formats
-
-| 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 |
-
-Use `workspai.config.mjs` when you prefer `export default`.
-
----
-
-## ⚙️ 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
+```json
+{
+  "defaultKit": "fastapi.standard",
+  "defaultInstallMethod": "poetry",
+  "pythonVersion": "3.10",
+  "author": "Platform Team",
+  "license": "MIT",
+  "skipGit": false,
+  "aiEnabled": true,
+  "telemetry": false
 }
 ```
 
-### **projects** (Project Settings)
+The `workspai config` command owns persisted AI settings such as the OpenAI API
+key and `aiEnabled`. Do not commit user configuration or API keys.
 
-```typescript
-projects: {
-  defaultKit?: string;           // Default template
-  addDefaultModules?: string[];  // Default modules to install
-  skipGit?: boolean;             // Skip git initialization
-  skipInstall?: boolean;         // Skip npm install
-}
-```
+## Directory configuration
 
----
+The CLI can discover the nearest configuration file while walking from the
+current directory toward the filesystem root:
 
-## 🔄 Configuration Priority
+- `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
 
-```
-CLI Arguments > workspai.config.* > .workspairc.json > legacy rapidkit config > Defaults
-```
+JavaScript configuration is executable code. The CLI refuses to import it
+unless trust is explicit:
 
-**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',
+    defaultAuthor: 'Platform Team',
     pythonVersion: '3.10',
     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,
   },
 };
 ```
 
----
+Python-backed workflows require Python 3.10 or newer. `pythonVersion` selects a
+project target; it does not make Python a dependency for Node-only or other
+Python-free Workspai workflows.
 
-## 🚀 Usage Examples
-
-### Without Config File (Interactive):
-```bash
-npx workspai my-workspace
-# ❓ Prompts:
-#   - Author name?
-#   - Python version?
-#   - Install method?
-```
+## Command coverage
 
-### 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
+Directory configuration is currently consumed by the legacy top-level creation
+shorthand, for example `npx workspai my-workspace`. Its effective precedence is:
 
-# 2. Run Workspai
-npx workspai my-workspace --yes
-# ✅ No prompts, uses config defaults
+```text
+CLI flags > workspai.config.* > ~/.workspairc.json > legacy config > defaults
 ```
 
----
-
-## 🔍 Debugging Configuration
+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:
 
 ```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' }
+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.
 
-## 🎯 Common Use Cases
+## Debugging
 
-### ✅ Recommended Uses:
-
-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
-
-### ❌ 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
+Use `--debug` on the legacy shorthand to inspect loaded and merged configuration:
 
 ```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
+npx workspai my-workspace --debug
 ```
 
----
+A malformed or untrusted executable config fails closed with its path and an
+actionable error.
 
-## 🛡️ Workspace Policy vs `workspai.config.*`
+## Workspace policy is separate
 
-- `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:
+Configuration files supply creation defaults. Runtime governance belongs to
+`.workspai/policies.yml` and should normally be managed through:
 
 ```bash
 npx workspai workspace policy show
-npx workspai workspace policy set <key> <value>
+npx workspai workspace policy set mode strict
+npx workspai workspace policy set dependency_sharing_mode shared-runtime-caches
 ```
 
----
-
-**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).