workspai 0.43.0 → 0.44.0

package/docs/AI_FEATURES.md

@@ -29,6 +29,7 @@ npx workspai ai recommend "user authentication with social login"
 **Step 1:** Get OpenAI API key from [OpenAI Platform](https://platform.openai.com/api-keys)
 
 **Step 2:** Configure API key
+
 ```bash
 npx workspai config set-api-key
 # Or (non-interactive environments):
@@ -36,6 +37,7 @@ export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
 ```
 
 **Step 3:** Generate embeddings (one-time, provider-cost dependent)
+
 ```bash
 npx workspai ai generate-embeddings
 
@@ -53,6 +55,7 @@ npx workspai ai generate-embeddings
 ```
 
 **Step 4:** Use AI recommendations
+
 ```bash
 npx workspai ai recommend "user authentication"
 ```
@@ -82,6 +85,7 @@ Mock mode provides realistic (but not perfect) results for development and testi
 Get intelligent module suggestions based on natural language descriptions.
 
 **Example:**
+
 ```bash
 $ npx workspai ai recommend "I need user authentication with email"
 
@@ -106,18 +110,20 @@ $ npx workspai ai recommend "I need user authentication with email"
 ## 💰 Pricing
 
 ### One-Time Setup Cost (Estimates)
-| Item | Cost | Notes |
-|------|------|-------|
+
+| Item                | Cost   | Notes                                            |
+| ------------------- | ------ | ------------------------------------------------ |
 | Generate embeddings | Varies | One-time only, depends on model and module count |
-| Update embeddings | Varies | Only when catalog changes |
+| Update embeddings   | Varies | Only when catalog changes                        |
 
 ### Per-Query Cost (After Setup, Estimates)
-| Usage | Cost | Notes |
-|-------|------|-------|
-| Single query | Very low | Depends on provider/model |
-| 100 queries | Low | Depends on provider/model |
-| 1,000 queries | Moderate | Depends on provider/model |
-| 10,000 queries | Higher | Depends on provider/model |
+
+| Usage          | Cost     | Notes                     |
+| -------------- | -------- | ------------------------- |
+| Single query   | Very low | Depends on provider/model |
+| 100 queries    | Low      | Depends on provider/model |
+| 1,000 queries  | Moderate | Depends on provider/model |
+| 10,000 queries | Higher   | Depends on provider/model |
 
 **Important:** Provider pricing and limits change over time. Always validate current pricing/limits in the provider dashboard before budgeting.
 
@@ -126,21 +132,25 @@ $ npx workspai ai recommend "I need user authentication with email"
 ## 🔧 Configuration
 
 ### View Current Config
+
 ```bash
 npx workspai config show
 ```
 
 ### Set API Key
+
 ```bash
 npx workspai config set-api-key
 ```
 
 ### Remove API Key
+
 ```bash
 npx workspai config remove-api-key
 ```
 
 ### Enable/Disable AI
+
 ```bash
 npx workspai config ai enable
 npx workspai config ai disable
@@ -180,17 +190,17 @@ npx workspai config ai disable
 
 ### Technical Details
 
-1. **Module Catalog**: 
+1. **Module Catalog**:
    - 27+ production-ready modules (dynamic from Python Core)
    - Fallback to 11 hardcoded modules if Python unavailable
    - 5-minute cache for performance
 
-2. **Embeddings**: 
+2. **Embeddings**:
    - AI converts module descriptions to 1536-dimensional vectors
    - Generated once, reused for all queries
    - Stored in `data/modules-embeddings.json` (508KB)
 
-3. **Semantic Search**: 
+3. **Semantic Search**:
    - User query → embedding vector
    - Cosine similarity with all modules
    - Results sorted by relevance score (0-100%)
@@ -202,12 +212,14 @@ npx workspai config ai disable
    - Installation order calculation
 
 **Technology Stack:**
+
 - Model: `text-embedding-3-small` (OpenAI)
 - Dimension: 1536 vectors
 - Accuracy: 92%+ match scores
 - Cost: provider-dependent (check current provider pricing)
 
 **Performance:**
+
 - First query: ~200ms (embedding generation)
 - Subsequent queries: ~50ms (cached embeddings)
 - Catalog refresh: Every 5 minutes
@@ -215,21 +227,25 @@ npx workspai config ai disable
 ## 🎯 Use Cases
 
 ### E-commerce Platform
+
 ```bash
 workspai ai recommend "e-commerce with payments and inventory"
 ```
 
 ### SaaS Application
+
 ```bash
 workspai ai recommend "SaaS platform with subscriptions"
 ```
 
 ### Real-time Chat
+
 ```bash
 workspai ai recommend "real-time chat application"
 ```
 
 ### API Gateway
+
 ```bash
 workspai ai recommend "API gateway with rate limiting"
 ```
@@ -259,6 +275,7 @@ npx workspai ai recommend "auth"
 ```
 
 Or generate manually:
+
 ```bash
 npx workspai ai generate-embeddings
 ```
@@ -266,12 +283,14 @@ npx workspai ai generate-embeddings
 ### "OpenAI API key not configured"
 
 **Option 1:** Mock mode (no key needed, for testing)
+
 ```bash
 # Just use it! Mock mode activates automatically
 npx workspai ai recommend "database"
 ```
 
 **Option 2:** Get a real API key
+
 ```bash
 # 1. Get key: https://platform.openai.com/api-keys
 # 2. Configure it:
@@ -286,6 +305,7 @@ export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
 **Cause:** API key is incorrect or expired
 
 **Solution:**
+
 ```bash
 # Update your API key
 npx workspai config set-api-key
@@ -299,12 +319,14 @@ npx workspai config show
 **Cause:** OpenAI API quota or rate limit reached
 
 **Solutions:**
+
 1. **Check billing:** https://platform.openai.com/account/billing
 2. **Check limits:** https://platform.openai.com/account/limits
 3. **Upgrade tier:** Free tier has lower limits
 4. **Wait:** Rate limits reset automatically
 
 **Rate Limits:**
+
 - Limits vary by provider account tier and can change over time
 - Check your provider dashboard for current request/token limits
 
@@ -315,6 +337,7 @@ npx workspai config show
 **Impact:** Uses fallback catalog instead of the full runtime catalog
 
 **Solution (optional):**
+
 ```bash
 # Install RapidKit Python Core
 pip install -e /path/to/rapidkit-core
@@ -330,6 +353,7 @@ rapidkit modules list --json
 **Symptom:** New modules not appearing in recommendations
 
 **Solution:** Update embeddings with latest modules
+
 ```bash
 npx workspai ai update-embeddings
 
@@ -344,11 +368,13 @@ npx workspai ai update-embeddings
 **Symptom:** All results show <70% match
 
 **Possible Causes:**
+
 1. Query too vague: "build something"
 2. Query too specific: "blockchain NFT marketplace with AI"
 3. No matching modules exist
 
 **Solutions:**
+
 - Make query more specific: "authentication" → "user authentication with JWT"
 - Try different keywords: "storage" instead of "blockchain"
 - Check available modules: `npx workspai ai info`
@@ -358,6 +384,7 @@ npx workspai ai update-embeddings
 **Cause:** Mock embeddings are deterministic but not trained
 
 **Solution:** Use real OpenAI API for production
+
 ```bash
 # Get API key and generate real embeddings
 npx workspai config set-api-key
@@ -380,11 +407,13 @@ npx workspai config show
 ### Still Having Issues?
 
 1. **Enable debug logging:**
+
    ```bash
    DEBUG=rapidkit:* npx workspai ai recommend "auth"
    ```
 
 2. **Check for updates:**
+
    ```bash
    npm outdated workspai
    npm update workspai
@@ -398,25 +427,25 @@ npx workspai config show
 
 ### AI Commands
 
-| Command | Description | Example |
-|---------|-------------|---------|
-| `workspai ai recommend [query]` | Get module recommendations | `workspai ai recommend "auth"` |
-| `workspai ai recommend [query] -n <N>` | Get top N recommendations | `workspai ai recommend "database" -n 3` |
-| `workspai ai recommend [query] --json` | Get JSON output | `workspai ai recommend "auth" --json` |
-| `workspai ai generate-embeddings` | Generate embeddings (one-time) | `workspai ai generate-embeddings` |
-| `workspai ai generate-embeddings --force` | Force regenerate embeddings | `workspai ai generate-embeddings --force` |
-| `workspai ai update-embeddings` | Update with latest modules | `workspai ai update-embeddings` |
-| `workspai ai info` | Show AI features info | `workspai ai info` |
+| Command                                   | Description                    | Example                                   |
+| ----------------------------------------- | ------------------------------ | ----------------------------------------- |
+| `workspai ai recommend [query]`           | Get module recommendations     | `workspai ai recommend "auth"`            |
+| `workspai ai recommend [query] -n <N>`    | Get top N recommendations      | `workspai ai recommend "database" -n 3`   |
+| `workspai ai recommend [query] --json`    | Get JSON output                | `workspai ai recommend "auth" --json`     |
+| `workspai ai generate-embeddings`         | Generate embeddings (one-time) | `workspai ai generate-embeddings`         |
+| `workspai ai generate-embeddings --force` | Force regenerate embeddings    | `workspai ai generate-embeddings --force` |
+| `workspai ai update-embeddings`           | Update with latest modules     | `workspai ai update-embeddings`           |
+| `workspai ai info`                        | Show AI features info          | `workspai ai info`                        |
 
 ### Configuration Commands
 
-| Command | Description | Example |
-|---------|-------------|---------|
-| `workspai config set-api-key` | Set OpenAI API key (interactive) | `workspai config set-api-key` |
-| `workspai config show` | Show current config | `workspai config show` |
-| `workspai config remove-api-key` | Remove API key | `workspai config remove-api-key` |
-| `workspai config ai enable` | Enable AI features | `workspai config ai enable` |
-| `workspai config ai disable` | Disable AI features | `workspai config ai disable` |
+| Command                          | Description                      | Example                          |
+| -------------------------------- | -------------------------------- | -------------------------------- |
+| `workspai config set-api-key`    | Set OpenAI API key (interactive) | `workspai config set-api-key`    |
+| `workspai config show`           | Show current config              | `workspai config show`           |
+| `workspai config remove-api-key` | Remove API key                   | `workspai config remove-api-key` |
+| `workspai config ai enable`      | Enable AI features               | `workspai config ai enable`      |
+| `workspai config ai disable`     | Disable AI features              | `workspai config ai disable`     |
 
 ### Recommend Command Options
 
@@ -439,13 +468,17 @@ Options:
   -h, --help Display help
 ```
 
-## 🚀 Coming Soon
+## 🚀 Planned Workspace Intelligence Extensions
+
+These are roadmap ideas, not current CLI claims. New AI-facing surfaces must be
+grounded in `contracts/workspace-intelligence-architecture.v1.json` before they
+are documented as available features.
 
-- [ ] Code completion (GPT-4)
-- [ ] Codebase chat
-- [ ] Bug detection
-- [ ] Test generation
-- [ ] Architecture suggestions
+- [ ] Workspace Atlas generated from Workspace Intelligence evidence
+- [ ] Repository/project chat over generated evidence artifacts
+- [ ] Bug detection grounded in doctor, verify, and impact reports
+- [ ] Test generation informed by workspace model, runtime signals, and affected subgraphs
+- [ ] Architecture suggestions with evidence/freshness labels
 
 ## 🤝 Contributing
 

package/docs/README.md

@@ -18,7 +18,8 @@ Hub for user and contributor documentation. Start with the [main README](../READ
 | [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, external-create-adopt, and adopt-only lanes |
+| [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 |

package/docs/commands-reference.md

@@ -9,9 +9,9 @@ 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 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>]
+npx workspai pipeline [--json] [--strict] [--skip-verify] [--skip-analyze] [--skip-autopilot] [--autopilot-mode <audit|safe-fix|enforce>] [--agent-sync|--no-agent-sync]
 npx workspai analyze [--workspace <path>] [--json] [--strict] [--output <file>]
-npx workspai readiness [--json] [--strict] [--skip-verify]
+npx workspai readiness [--workspace <path>] [--json] [--strict] [--skip-verify]
 npx workspai autopilot release [--mode <audit|safe-fix|enforce>] [--json] [--output <file>] [--since <ref>] [--parallel] [--max-workers <n>]
 ```
 
@@ -49,19 +49,25 @@ 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 model [--json] [--write] [--strict]
-npx workspai workspace context --for-agent [codex|claude|cursor|orca] [--json] [--write] [--no-agent-sync]
-npx workspai workspace agent-sync [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|copilot,cursor,claude] [--experimental-hooks]
+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]
 npx workspai workspace remediation-plan [--json] [--write] [--ci] [--include-paths]
-npx workspai workspace snapshot [--json]
-npx workspai workspace diff --from <snapshot-or-report|git[:ref]> [--json]
-npx workspai workspace impact --from <snapshot-or-report> [--scope project:<name>] [--json]
-npx workspai workspace verify [--from-impact <file>] [--scope project:<name>] [--strict] [--json]
-npx workspai workspace export --output team-workspace.workspai-archive.zip
-npx workspai workspace archive inspect team-workspace.workspai-archive.zip [--json]
-npx workspai workspace archive verify team-workspace.workspai-archive.zip [--strict] [--json]
-npx workspai workspace archive doctor team-workspace.workspai-archive.zip [--strict] [--json]
-npx workspai workspace hydrate team-workspace.workspai-archive.zip --output ./team-workspace
+npx workspai workspace snapshot [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
+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 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]
+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 snapshot create [name] [--include-projects] [--reason <text>] [--json]
@@ -82,6 +88,12 @@ npx workspai infra status [--workspace <path>] [--json] [--strict]
 
 See [workspace-run.md](./workspace-run.md) for fleet orchestration semantics.
 
+After cloning or moving an existing workspace, `workspace sync` repairs its
+machine-local global registry entry before project discovery. For workspaces
+that only have legacy `.rapidkit-workspace` metadata, run `workspace foundation
+ensure` to add the canonical marker and foundation without deleting legacy
+compatibility inputs.
+
 Workspace profile compatibility is enforced consistently across `create project`,
 `import`, `adopt`, and `bootstrap` compliance. In default `warn` policy mode,
 cross-runtime additions are allowed with a recommendation such as

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -9,13 +9,17 @@ Canonical map of **on-disk artifacts** produced by Workspai CLI commands. Dashbo
 | Workspace manifest | `.workspai/workspace.json`             | `create workspace`, `foundation ensure`, `bootstrap` (profile) | Profile, engine, bootstrap metadata — **not** project list |
 | Workspace contract | `.workspai/workspace.contract.json`    | `workspace sync`, `workspace contract *`, import/adopt         | Operational project registry (ports, contracts)            |
 | Registry summary   | `.workspai/workspace-registry.v1.json` | `workspace sync`, contract sync, `registry status --refresh`   | **Canonical** project count + authority for UI/CI          |
-| Workspace marker   | `.workspai-workspace`                  | `create workspace`, `foundation ensure`                        | Root detection                                             |
+| Workspace marker   | `.workspai-workspace`                  | `create workspace`, `foundation ensure`                        | Portable root detection; commit with the workspace         |
 
 Legacy `.rapidkit-workspace` and `.rapidkit/*` paths are read as fallback for
 older workspaces. New Workspai CLI writes target `.workspai-workspace` and
 `.workspai/*`. Workspace archive hydrate also normalizes legacy archive entries
 to canonical Workspai paths on restore.
 
+The canonical `.workspai-workspace` marker must remain trackable. Generated
+workspace `.gitignore` files exclude legacy/local engine state but do not
+exclude the canonical marker.
+
 ## Naming conventions
 
 | Pattern           | Meaning                                | Examples                                                     |
@@ -26,23 +30,23 @@ to canonical Workspai paths on restore.
 
 ## Governance evidence loop
 
-| Command                  | Primary artifact                                          | Schema version                  | JSON Schema                                                  |
-| ------------------------ | --------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ |
-| `doctor workspace`       | `.workspai/reports/doctor-last-run.json`                  | `doctor-workspace-evidence-v1`  | `contracts/doctor-workspace-evidence.v1.json`                |
-| `doctor project`         | `.workspai/reports/doctor-project-last-run.json`          | `doctor-project-evidence-v1`    | `contracts/doctor-project-evidence.v1.json`                  |
-| `doctor * --plan`        | `.workspai/reports/doctor-remediation-plan-last-run.json` | `doctor-remediation-plan-v2`    | `contracts/doctor-remediation-plan.v1.json`                  |
-| `doctor * --fix/--apply` | `.workspai/reports/doctor-fix-result-last-run.json`       | `rapidkit-doctor-fix-result-v1` | `contracts/workspace-intelligence/doctor-fix-result.v1.json` |
-| `workspace remediation-plan --write` | `.workspai/reports/artifact-remediation-plan-last-run.json` | `artifact-remediation-plan-v1` | `contracts/artifact-remediation-plan.v1.json` |
-| `analyze`                | `.workspai/reports/analyze-last-run.json`                 | `rapidkit-analyze-v1`           | `contracts/analyze-last-run.v1.json`                         |
-| `readiness`              | `.workspai/reports/release-readiness-last-run.json`       | `release-readiness-v1`          | `contracts/release-readiness.v1.json`                        |
-| `pipeline`               | `.workspai/reports/pipeline-last-run.json`                | `rapidkit-pipeline-v1`          | `contracts/pipeline-last-run.v1.json`                        |
-| `autopilot release`      | `.workspai/reports/autopilot-release-last-run.json`       | `autopilot-release-v1`          | —                                                            |
-|                          | `.workspai/reports/autopilot-release.json`                | (alias, same payload)           | —                                                            |
+| Command                              | Primary artifact                                            | Schema version                  | JSON Schema                                                  |
+| ------------------------------------ | ----------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ |
+| `doctor workspace`                   | `.workspai/reports/doctor-last-run.json`                    | `doctor-workspace-evidence-v1`  | `contracts/doctor-workspace-evidence.v1.json`                |
+| `doctor project`                     | `.workspai/reports/doctor-project-last-run.json`            | `doctor-project-evidence-v1`    | `contracts/doctor-project-evidence.v1.json`                  |
+| `doctor * --plan`                    | `.workspai/reports/doctor-remediation-plan-last-run.json`   | `doctor-remediation-plan-v2`    | `contracts/doctor-remediation-plan.v2.json`                  |
+| `doctor * --fix/--apply`             | `.workspai/reports/doctor-fix-result-last-run.json`         | `rapidkit-doctor-fix-result-v1` | `contracts/workspace-intelligence/doctor-fix-result.v1.json` |
+| `workspace remediation-plan --write` | `.workspai/reports/artifact-remediation-plan-last-run.json` | `artifact-remediation-plan-v1`  | `contracts/artifact-remediation-plan.v1.json`                |
+| `analyze`                            | `.workspai/reports/analyze-last-run.json`                   | `rapidkit-analyze-v1`           | `contracts/analyze-last-run.v1.json`                         |
+| `readiness`                          | `.workspai/reports/release-readiness-last-run.json`         | `release-readiness-v1`          | `contracts/release-readiness.v1.json`                        |
+| `pipeline`                           | `.workspai/reports/pipeline-last-run.json`                  | `rapidkit-pipeline-v1`          | `contracts/pipeline-last-run.v1.json`                        |
+| `autopilot release`                  | `.workspai/reports/autopilot-release-last-run.json`         | `autopilot-release-v1`          | `contracts/autopilot-release.v1.json`                        |
+|                                      | `.workspai/reports/autopilot-release.json`                  | (alias, same payload)           | `contracts/autopilot-release.v1.json`                        |
 
 Side/cache (not gates): `.workspai/reports/doctor-workspace-cache.json` (`doctor-workspace-cache-v2`).
 
 Doctor Studio handoff:
-`doctor-remediation-plan-v2` (`contracts/doctor-remediation-plan.v1.json`) is emitted in JSON
+`doctor-remediation-plan-v2` (`contracts/doctor-remediation-plan.v2.json`) is emitted in JSON
 responses and persisted to `.workspai/reports/doctor-remediation-plan-last-run.json` by
 `doctor workspace|project --plan`, `--fix`, and `--apply` so IDEs can render approved commands,
 typed file edits, diff previews, ordered phases, step dependencies, rollback, and verification
@@ -71,16 +75,23 @@ the same evidence without losing the workspace source of truth.
 | Command                                        | Artifact                                                                                                                                                                                                                                                     | Schema                                 | Contract file                                                             |
 | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- |
 | `workspace model --write`                      | `workspace-model.json`                                                                                                                                                                                                                                       | `workspace-model.v1`                   | `contracts/workspace-intelligence/workspace-model.v1.json`                |
-| `workspace snapshot`                           | `workspace-model-snapshot.json`                                                                                                                                                                                                                              | `workspace-model-snapshot.v1`          | `workspace-model-snapshot.v1.json`                                        |
-| `workspace diff`                               | `workspace-model-diff-last-run.json`                                                                                                                                                                                                                         | `workspace-model-diff.v1`              | `workspace-model-diff.v1.json`                                            |
-| `workspace impact --from <diff>`               | `workspace-impact-last-run.json`                                                                                                                                                                                                                             | `workspace-impact.v1`                  | `workspace-impact.v1.json`                                                |
-| `workspace verify`                             | `workspace-verify-last-run.json`                                                                                                                                                                                                                             | `workspace-verify.v1`                  | `workspace-verify.v1.json`                                                |
-| `workspace context --write`                    | `workspace-context-agent.json`                                                                                                                                                                                                                               | `workspace-context.v1`                 | `workspace-context.v1.json`                                               |
-| `workspace agent-sync --write`                 | `reports/INDEX.json`, `reports/agent-customization-pack.json`, `reports/workspai-mcp-design.json`, `reports/workspace-skills-index.json`, `.workspai/skills/*.md`, `.workspai/AGENT-GROUNDING.md`, `AGENTS.md`, Copilot/Cursor/Claude/VS Code agent surfaces | `rapidkit-agent-customization-pack.v1` | `contracts/agent-customization-pack.v1.json`                              |
+| `workspace snapshot`                           | `workspace-model-snapshot.json`                                                                                                                                                                                                                              | `workspace-model-snapshot.v1`          | `contracts/workspace-intelligence/workspace-model-snapshot.v1.json`       |
+| `workspace diff`                               | `workspace-model-diff-last-run.json`                                                                                                                                                                                                                         | `workspace-model-diff.v1`              | `contracts/workspace-intelligence/workspace-model-diff.v1.json`           |
+| `workspace impact --from <diff>`               | `workspace-impact-last-run.json`                                                                                                                                                                                                                             | `workspace-impact.v1`                  | `contracts/workspace-intelligence/workspace-impact.v1.json`               |
+| `analyze --json`                               | `analyze-last-run.json`                                                                                                                                                                                                                                      | `rapidkit-analyze-v1`                  | `contracts/analyze-last-run.v1.json`                                      |
+| `workspace verify`                             | `workspace-verify-last-run.json`                                                                                                                                                                                                                             | `workspace-verify.v1`                  | `contracts/workspace-intelligence/workspace-verify.v1.json`               |
+| `workspace context --write`                    | `workspace-context-agent.json`                                                                                                                                                                                                                               | `workspace-context.v1`                 | `contracts/workspace-intelligence/workspace-context.v1.json`              |
+| `workspace agent-sync --write`                 | `reports/agent-customization-pack.json`                                                                                                                                                                                                                       | `rapidkit-agent-customization-pack.v1` | `contracts/workspace-intelligence/agent-customization-pack-report.v1.json` |
+| `workspace agent-sync --write`                 | `reports/INDEX.json`                                                                                                                                                                                                                                          | `rapidkit-agent-reports-index.v1`      | `contracts/workspace-intelligence/agent-reports-index.v1.json`            |
+| `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 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` |
 
 **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
+`contracts/cli-operation-result.v1.json`; the canonical artifact is nested under `artifact`.
 
 ### Dependency graph (`workspace-dependency-graph.v1`)
 
@@ -240,25 +251,33 @@ Canonical source: `src/observability/run-correlation.ts` (`attachRunCorrelation`
 
 ## Operational / platform
 
-| Command                          | Artifact                                                               | Notes                                                                                        |
-| -------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------- |
-| `workspace run`                  | `workspace-run-last.json`                                              | `workspace-run-v1` (multi-stage: `stages.test`, `stages.build`, …)                           | `contracts/workspace-run-last.v1.json` |
-| `autopilot release` (run stages) | same `workspace-run-last.json`                                         | Autopilot publishes test/build into aggregate (no separate `autopilot-workspace-run-*.json`) | —                                      |
-| `bootstrap`                      | `bootstrap-compliance-{ts}.json`, `bootstrap-compliance.latest.json`   |                                                                                              |
-| `mirror status`                  | `mirror-ops-{ts}.json`, `mirror-ops.latest.json`                       |                                                                                              |
-| `mirror` (transparency)          | `transparency-evidence-{ts}.json`, `transparency-evidence.latest.json` |                                                                                              |
-| `infra plan`                     | `infra-plan.json`                                                      | `rapidkit.infra-plan.v1`                                                                     |
-| `workspace archive`              | `archive-manifest.json`                                                | Root `.workspai/`, handoff                                                                   |
-| `workspace share`                | `reports/share-bundle.json` (default)                                  | Aggregation bundle                                                                           |
-| `import` / `adopt`               | `{project}/.workspai/import-readiness.json`                            | Per project                                                                                  |
-| `workspace contract verify`      | `workspace-contract-verify-last-run.json`                              | CLI verify cache                                                                             |
+| Command                          | Artifact                                                               | Notes                                                                                        | Contract                                                             |
+| -------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `workspace run`                  | `workspace-run-last.json`                                              | `workspace-run-v1` (multi-stage: `stages.test`, `stages.build`, …)                           | `contracts/workspace-run-last.v1.json`                               |
+| `autopilot release` (run stages) | same `workspace-run-last.json`                                         | Autopilot publishes test/build into aggregate (no separate `autopilot-workspace-run-*.json`) | —                                                                    |
+| `bootstrap`                      | `bootstrap-compliance-{ts}.json`, `bootstrap-compliance.latest.json`   |                                                                                              | —                                                                    |
+| `mirror status`                  | `mirror-ops-{ts}.json`, `mirror-ops.latest.json`                       |                                                                                              | —                                                                    |
+| `mirror` (transparency)          | `transparency-evidence-{ts}.json`, `transparency-evidence.latest.json` |                                                                                              | —                                                                    |
+| `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                                                                                  | —                                                                    |
+| `workspace contract verify`      | `workspace-contract-verify-last-run.json`                              | CLI verify cache                                                                             | `contracts/workspace-intelligence/workspace-contract-verify.v1.json` |
 
 ## Static capability contracts
 
-| Contract                                        | Schema version                            | Consumer purpose                                                                                 |
-| ----------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `contracts/runtime-command-surface.v1.json`     | `rapidkit-runtime-command-surface-v1`     | Runtime commands, scaffold kits, and create planner summary                                      |
-| `contracts/create-planner-capabilities.v1.json` | `rapidkit-create-planner-capabilities-v1` | Native create, external-create-adopt, and adopt-only lanes for CLI, CI, VS Code, and AI planners |
+| Contract                                               | Schema version                                   | Consumer purpose                                                                   |
+| ------------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| `contracts/runtime-command-surface.v1.json`            | `rapidkit-runtime-command-surface-v1`            | Runtime commands, scaffold kits, and create planner summary                        |
+| `contracts/cli-operation-result.v1.json`               | `workspai-cli-operation-result-v1`               | Stable success/error envelope for JSON command projections                         |
+| `contracts/command-capabilities.v1.json`               | `rapidkit-command-capabilities-v1`               | Effective command ownership and workspace command discovery                        |
+| `contracts/version.v1.json`                            | `rapidkit-version-v1`                            | Version and published-contract discovery response                                  |
+| `contracts/published-contract-catalog.v1.json`         | `workspai-published-contract-catalog-v1`         | Schema versions plus resolvable contract paths                                     |
+| `contracts/project-entry-capability.v1.json`           | `workspai-project-entry-capability-v1`           | Open-ended adopt/import capability boundaries for readable projects                |
+| `contracts/create-planner-capabilities.v1.json`        | `rapidkit-create-planner-capabilities-v1`        | Native create, official, and existing lanes for CLI, CI, VS Code, and AI planners  |
+| `contracts/workspace-archive-capabilities.v1.json`     | `workspai-workspace-archive-capabilities-v1`     | ZIP64, streaming, compression, limits, commands, flags, and linked archive schemas |
+| `contracts/workspace-archive-manifest.v1.json`         | `workspai-workspace-archive-manifest-v1`         | Runtime-validated archive manifest, file inventory, checksums, and security policy |
+| `contracts/workspace-archive-operation-result.v1.json` | `workspai-workspace-archive-operation-result-v1` | Stable JSON results for export, inspect, verify, doctor, hydrate, and failures     |
 
 ## Observability stream (not on-disk)
 
@@ -280,6 +299,11 @@ events go to stderr (`--log-format json`). The two never mix.
 | `workspace sync [--json]`                        | Updates contract + `workspace-registry.v1.json`; JSON includes `registrySummary` |
 | `workspace registry status [--refresh] [--json]` | Reads or publishes registry summary                                              |
 
+`workspace-registry.v1.json`, adoption records, and verification reports can
+contain machine-local absolute paths. Regenerate them after cloning; do not use
+them as portable repository contracts. The portable source is
+`.workspai/workspace.contract.json` plus canonical workspace/project metadata.
+
 ## Project-scoped reports
 
 Under `{project}/.workspai/reports/` when commands run at project scope (e.g. project doctor). Workspace-level reports stay under `{workspace}/.workspai/reports/`.

package/docs/contracts/README.md

@@ -36,11 +36,12 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `release-readiness.v1.json` — release readiness gate evidence
 - `workspace-run-last.v1.json` — multi-stage workspace run evidence
 - `doctor-workspace-evidence.v1.json` / `doctor-project-evidence.v1.json` — doctor evidence
-- `doctor-remediation-plan.v1.json` — persisted Doctor fix/plan Studio handoff contract
+- `doctor-remediation-plan.v2.json` — canonical persisted Doctor fix/plan Studio handoff contract (`v1` path is a deprecated compatibility alias)
 - `artifact-remediation-plan.v1.json` — cross-artifact Studio handoff for Bootstrap, Analyze, Readiness, Pipeline, Workspace Run, Workspace Verify, and Doctor plan bridging
 - `analyze-last-run.v1.json` — analyze evidence
 - `pipeline-last-run.v1.json` — governance pipeline orchestration
-- `create-planner-capabilities.v1.json` — native-create, external-create-adopt, and adopt-only capability lanes
+- `project-entry-capability.v1.json` — open-ended adopt/import contract for readable projects
+- `create-planner-capabilities.v1.json` — native, official, and existing capability lanes
 - `agent-customization-pack.v1.json` — generated instructions, prompts, skills, agents, optional hooks, MCP-ready design metadata, target matrix, and drift state for AI agent surfaces
 
 Workspace intelligence (`../../contracts/workspace-intelligence/`):