workspai 0.49.0 → 0.50.0

package/docs/README.md

@@ -19,14 +19,17 @@ npx workspai adopt .
 ```
 
 `adopt` keeps the project in place and creates or reuses the minimal default
-workspace. Without the VS Code extension, copy the exact `Next shell step`
-printed by the CLI and continue in that workspace terminal:
+workspace. Continue from the same project terminal:
 
 ```bash
-cd ~/.workspai/workspaces/workspai
+npx workspai project workspace status --json
 npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
+The first command proves which canonical workspace owns the project. Workspai
+uses a gitignored machine-local binding and portable project grounding, so
+workspace commands and compatible agents do not need a manual `cd`.
+
 Use `generic` for a vendor-neutral context pack, or select `codex`, `claude`,
 `cursor`, or `orca`. Agent Sync also publishes shared files for GitHub Copilot,
 VS Code, and `AGENTS.md` consumers.

package/docs/README_CONTENT_CONTRACT.md

@@ -58,10 +58,18 @@ as one undifferentiated command wall.
 ## Architectural statements that must remain true
 
 - The **Workspace Model is the canonical source of truth**.
-- The Knowledge Graph is a **derived, revision-bound representation** of
-  governed workspace knowledge.
+- The Knowledge Graph is a **derived, structurally bound representation** of
+  governed workspace knowledge. Its source kind and source artifact are fixed
+  to the canonical Workspace Model contract.
 - Providers emit facts and proofs; they do not independently own the canonical
   graph.
+- Graph enrichment must not mutate the authorizing model during the same run.
+- The canonical project inventory must reconcile discovered, imported,
+  adopted, and contract-declared projects. A missing contract-declared path is
+  a validation warning, not a silently deleted project.
+- Persisted current-state consumers must reject a graph whose structural model
+  hash, workspace identity, or project topology no longer matches the current
+  model.
 - Missing relationships mean **not proven**, not independent.
 - The graph is broader than a code graph, but it is not the entire product.
 - The canonical runner is
@@ -74,13 +82,14 @@ as one undifferentiated command wall.
 
 Normative machine sources:
 
-| Statement                      | Source of truth                                         |
-| ------------------------------ | ------------------------------------------------------- |
-| Ordered intelligence chain     | `contracts/workspace-intelligence-chain.v1.json`        |
-| Runtime commands and flags     | `contracts/runtime-command-surface.v1.json`             |
-| Published schemas and paths    | `contracts/published-contract-catalog.v1.json`          |
-| Architecture boundaries        | `contracts/workspace-intelligence-architecture.v1.json` |
-| Artifact writers and consumers | `docs/contracts/ARTIFACT_CATALOG.md`                    |
+| Statement                      | Source of truth                                                      |
+| ------------------------------ | -------------------------------------------------------------------- |
+| Ordered intelligence chain     | `contracts/workspace-intelligence-chain.v1.json`                     |
+| Runtime commands and flags     | `contracts/runtime-command-surface.v1.json`                          |
+| Published schemas and paths    | `contracts/published-contract-catalog.v1.json`                       |
+| Architecture boundaries        | `contracts/workspace-intelligence-architecture.v1.json`              |
+| Model → Graph source binding   | `contracts/workspace-intelligence/workspace-knowledge-graph.v1.json` |
+| Artifact writers and consumers | `docs/contracts/ARTIFACT_CATALOG.md`                                 |
 
 Markdown summarizes these contracts; it does not redefine them.
 

package/docs/commands-reference.md

@@ -8,7 +8,7 @@ Complete CLI syntax for the Workspai CLI. For behavior and workflows, see [works
 npx workspai create # Prompts: workspace | project
 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 setup <python|node|go|java|dotnet|rust|php> [--warm-deps]
 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 [--workspace <path>] [--json] [--strict] [--skip-verify]
@@ -49,6 +49,7 @@ npx workspai workspace policy set <key> <value>
 npx workspai doctor
 npx workspai doctor workspace [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
 npx workspai doctor project [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
+npx workspai project coverage [--project <path>] [--target <0-100>] [--run] [--strict] [--json]
 npx workspai workspace list
 npx workspai workspace foundation ensure [--force] [--json]
 npx workspai workspace share [--output <file>] [--include-paths] [--no-doctor]
@@ -59,7 +60,7 @@ 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]
+npx workspai workspace agent-sync [--workspace <path>] [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|agents,copilot,cursor,claude,codex,orca] [--project-grounding managed|local|off] [--experimental-hooks] [--hydrate-prompts]
 npx workspai workspace remediation-plan [--json] [--write] [--ci] [--include-paths]
 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]
@@ -77,8 +78,10 @@ npx workspai workspace archive inspect team-workspace.workspai-archive.zip [--ma
 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 workspace import team-workspace.workspai-archive.zip --output ./team-workspace [--project-grounding managed|local|off] [--dry-run] [--strict] [--json]
+npx workspai workspace connect [directory] [--project-grounding managed|local|off] [--dry-run] [--json]
+npx workspai import <path|git-url> [--workspace <path>] [--name <project-name>] [--git] [--enable-modules] [--project-grounding managed|local|off] [--json]
+npx workspai adopt [path] [--workspace <path>] [--name <project-name>] [--enable-modules] [--project-grounding managed|local|off] [--dry-run] [--json]
 npx workspai snapshot create [name] [--include-projects] [--reason <text>] [--json]
 npx workspai snapshot list [--json]
 npx workspai snapshot inspect <name> [--json]
@@ -87,6 +90,7 @@ npx workspai project archive <name> [--reason <text>] [--dry-run] [--json]
 npx workspai project archives [--json]
 npx workspai project restore <archive> [--name <project-name>] [--force] [--dry-run] [--json]
 npx workspai project delete <name> [--permanent --confirm <name>] [--dry-run] [--json]
+npx workspai project workspace [status|relink] [--workspace <path>] [--project <path>] [--json]
 npx workspai workspace init
 npx workspai workspace run <init|test|build|start> [--affected] [--blast-radius] [--since <ref>] [--parallel] [--max-workers <n>] [--strict] [--json]
 npx workspai infra plan [--workspace <path>] [--json] [--dry-run] [--verbose]
@@ -95,6 +99,17 @@ npx workspai infra down [--workspace <path>] [--volumes]
 npx workspai infra status [--workspace <path>] [--json] [--strict]
 ```
 
+Every workspace action has action-scoped help generated from the same contract
+that governs its accepted flags. For example:
+
+```bash
+npx workspai workspace impact --help
+npx workspai workspace graph search --help
+```
+
+This avoids guessing whether an option such as `--write`, `--from`, or
+`--output` belongs to a particular action.
+
 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
@@ -138,6 +153,12 @@ 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.
 
+Every integrated `workspace graph` Knowledge Graph is derived from the
+canonical Workspace Model. Its contract fixes the source artifact to
+`.workspai/reports/workspace-model.json` and binds the graph to the model's
+stable structural SHA-256. Graph providers enrich that model-owned inventory;
+they never write facts back into the authorizing model during the same run.
+
 `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
@@ -190,9 +211,11 @@ 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
 `npx workspai bootstrap --profile polyglot`; in `strict` mode, mismatches are
-blocked before the project is registered. Observed runtimes such as Rust, C,
-and C++ are counted in the workspace runtime mix even when Workspai does not own
-a native scaffold for them.
+blocked before the project is registered. Rust is an extended runtime with
+Axum/Tauri scaffolding and Cargo lifecycle support. PHP is extended through
+Laravel and Composer lifecycle support. Observed runtimes such as C and C++ are
+still counted in the workspace runtime mix even when Workspai does not own a
+native scaffold for them.
 
 Core module/template commands are intentionally narrower than runtime detection.
 RapidKit Core modules are guaranteed only for RapidKit Core module-enabled kits:
@@ -223,6 +246,10 @@ Examples:
 ```bash
 npx workspai create project fastapi.standard my-api --yes
 npx workspai create project nextjs my-web --yes
+npx workspai create project rust.axum my-rust-api --yes
+npx workspai create project desktop.tauri my-desktop-app --yes
+npx workspai create project extension.vscode my-extension --yes
+npx workspai create project php.laravel my-laravel-api --yes
 ```
 
 Generator-specific options include `--port`, Spring Boot
@@ -232,7 +259,11 @@ and .NET `--dotnet-version`/`--target-framework`/`--nullable`. Use
 
 `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.
+`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, desktop, extension, Go, Spring Boot, .NET, Rust, PHP, and
+adopted/imported projects use runtime lifecycle commands and workspace
+governance while Core module mutation remains disabled.
 
 ## Operations
 

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -20,6 +20,28 @@ The canonical `.workspai-workspace` marker must remain trackable. Generated
 workspace `.gitignore` files exclude legacy/local engine state but do not
 exclude the canonical marker.
 
+## Project entry and grounding
+
+These paths are relative to each registered project root, not the workspace
+root:
+
+| Artifact | Writer | Schema / format | Portability and reader purpose |
+| --- | --- | --- | --- |
+| `.workspai/workspace-link.local.json` | `adopt`, `import`, project creation, `workspace sync`, `project workspace relink` | `project-workspace-link.v1` | Machine-local absolute binding; always gitignored and never an agent evidence payload |
+| `.workspai/reports/project-context-agent.json` | Project lens reconciliation and `workspace agent-sync --write` | `project-context-agent.v1` | Portable bounded model/graph/proof projection for project-local agents |
+| `.workspai/PROJECT-GROUNDING.md` | Project lens reconciliation | Markdown | Portable human/agent entry guide with path-free workspace references |
+| `AGENTS.md` managed section | Project lens reconciliation in `managed` mode | Managed Markdown block | Preserves user content and routes compatible agents to project/workspace evidence |
+
+The project link is validated against the canonical workspace contract and a
+SHA-256 binding over workspace identity, project identity, portable relative
+path, machine paths, and relationship. Project context generation rejects
+absolute paths before writing. `managed`, `local`, and `off` grounding modes
+control portable project surfaces and converge by removing stale managed
+sections and ignore rules during transitions; they never make the
+machine-local link publishable. The context is bounded but not count-only: it
+includes topology, API/deployment/test surfaces, blockers, portable proofs,
+and model/graph freshness for the selected project.
+
 ## Naming conventions
 
 | Pattern           | Meaning                                | Examples                                                     |
@@ -30,18 +52,19 @@ exclude the canonical marker.
 
 ## 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.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`                        |
+| 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`                  |
+| `project coverage`                   | `.workspai/reports/project-test-coverage-last-run.json`     | `workspai.project-test-coverage.v1` | `contracts/project-test-coverage.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`).
 
@@ -64,11 +87,13 @@ this plan before inventing per-card repair logic. The plan carries ordered actio
 operations where deterministic, refresh/verify commands, risk, approval state, and rollback
 strategy.
 
-When `doctor project` runs inside a workspace, the workspace report remains the canonical
-governance artifact and Doctor mirrors `doctor-project-last-run.json`,
-`doctor-remediation-plan-last-run.json`, and `doctor-fix-result-last-run.json` into the scoped
-project's `.workspai/reports/` directory. This keeps Studio, agents, and project-local operators on
-the same evidence without losing the workspace source of truth.
+When `doctor project` runs inside a workspace, the project-local report is written beside the
+project and the workspace receives both a latest alias and a collision-safe project copy under
+`.workspai/reports/projects/<project-slug>--<identity-hash>/`. Coverage evidence follows the same
+three-location rule. The hash is derived from workspace-relative identity, so projects with the
+same folder name cannot overwrite each other. Remediation plans and fix results are also mirrored
+into the scoped project. Studio, CI, and project-local tools can therefore use the same evidence
+without guessing which project produced a latest alias.
 
 ## Workspace intelligence
 
@@ -108,10 +133,14 @@ 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.
 
-`workspace-model.json` and `workspace-knowledge-graph.json` are published as one
-recoverable artifact transaction. The graph carries a SHA-256 `source` binding
-to the canonical model, so consumers must reject a graph whose source hash does
-not equal the current structural model hash.
+`workspace-model.json` and `workspace-knowledge-graph.json` are published under
+one workspace lock as a rollback-capable artifact transaction. Individual file
+replacement is atomic, and a partial set failure restores both preimages. The
+model is canonical; the graph is derived and cannot mutate it during the run.
+The graph contract fixes `source.kind` to `workspace-model`,
+`source.artifact` to `.workspai/reports/workspace-model.json`, and `source.hash`
+to the model's stable structural SHA-256. Current-state consumers must reject a
+graph whose binding does not match the current model.
 
 `workspace graph jsonld|graphml|gexf --output <path>` creates explicit interchange
 projections from that bound graph. These files are portable exports, not competing
@@ -150,11 +179,13 @@ sources: package manifests (`package.json` deps, `pyproject.toml` path deps, `go
 replace → `package-dep`), cross-boundary JS/TS source imports (`code-import`), the
 workspace contract (`dependsOn` → `service-dependsOn`, matched `publishes`/`consumes`
 → `event-pub-sub`, env↔port references → `shared-resource`), and an optional manual
-override file. Node/edge ordering and `hashDependencyGraph` are stable, so the graph is
-embedded as a first-class field of `workspace-model.v1` (`model.graph`) on every
-`buildWorkspaceModel` run; `hashModel` normalizes the embedded `graph.generatedAt` so the
-structural graph participates in the model hash without causing timestamp drift.
-(`model.graph` is additive/optional for pre-graph readers.)
+override file. Node/edge ordering and `hashDependencyGraph` are stable, so the compact
+topology is embedded as the canonical `workspace-model.v1.projectTopology` field on every
+`buildWorkspaceModel` run. `hashWorkspaceModel` normalizes
+`projectTopology.generatedAt`, so the structural topology participates in the model hash
+without causing timestamp drift. During the v1 migration window the CLI also emits the
+deprecated `graph` compatibility alias. Consumers must read `projectTopology`; when both
+fields exist, validation requires them to be structurally identical.
 
 **Manual overrides.** `.workspai/workspace-graph.overrides.json` (`{ "edges": [{ "from",
 "to", "kind", "evidence" }] }`) declares authoritative edges that win over inference for
@@ -245,6 +276,14 @@ reused and the dependency graph re-infers only edges incident to changed project
 changes or project renames, and rescans code-imports fully when the node set changes. Reported
 modes: `full` / `incremental` / `unchanged`.
 
+The model command adds a non-structural `build` object to its JSON output and,
+when `--write` is used, to the persisted model result. `mode`, `outcome`, and
+`engineStatus` tell IDE/CI consumers
+whether the result was rebuilt, partially reused, or fully reused. This
+provenance is deliberately excluded from the canonical workspace-model hash,
+so switching between full, cached, and incremental execution cannot make the
+paired knowledge graph appear stale.
+
 ### Freshness metadata (`rapidkit-freshness-metadata-v1`)
 
 Intelligence reports carry a shared freshness envelope so any consumer (CLI

package/docs/contracts/COMMAND_OWNERSHIP_MATRIX.md

@@ -58,10 +58,12 @@ These nested Commander commands are implemented and orchestrated by Workspai CLI
 - `product manifest create`
 - `product plan`
 - `project commands`
+- `project coverage`
 - `project archives`
 - `project archive`
 - `project restore`
 - `project delete`
+- `project workspace`
 - `snapshot create`
 - `snapshot inspect`
 - `snapshot list`

package/docs/contracts/RUNTIME_SUPPORT_MATRIX.md

@@ -18,9 +18,9 @@ It separates three concerns:
 | Go                  | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
 | Java / Spring Boot  | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
 | .NET / ASP.NET Core | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
-| PHP                 | observed    |       no |    yes | help                                              |              no | observed  |
+| PHP                 | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
 | Ruby                | observed    |       no |    yes | help                                              |              no | observed  |
-| Rust                | observed    |       no |    yes | help                                              |              no | observed  |
+| Rust                | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
 | Elixir              | observed    |       no |    yes | help                                              |              no | observed  |
 | Clojure             | observed    |       no |    yes | help                                              |              no | observed  |
 | Scala               | observed    |       no |    yes | help                                              |              no | observed  |
@@ -40,7 +40,7 @@ It separates three concerns:
 | Tier        | Frameworks                                                                                                                                                                                                                          |
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | first-class | FastAPI, NestJS                                                                                                                                                                                                                     |
-| extended    | Go/Fiber, Go/Gin, Spring Boot, ASP.NET Core, Django, Flask, Express, Fastify, Koa, Echo, Laravel, Symfony, Rails, Sinatra, Actix, Axum, Rocket, Phoenix, Next.js, Remix, React, Vue, Svelte, Solid, Nuxt, Angular, Astro, SvelteKit |
+| extended    | Go/Fiber, Go/Gin, Spring Boot, ASP.NET Core, Django, Flask, Express, Fastify, Koa, Echo, Laravel, Symfony, Rails, Sinatra, Actix, Axum, Rocket, Phoenix, Next.js, Remix, React, Vue, Svelte, Solid, Nuxt, Angular, Astro, SvelteKit, Tauri, Electron, VS Code Extension |
 | observed    | Python, Node.js, Go, Java, PHP, Ruby, Rust, Elixir, Unknown/generic projects                                                                                                                                                        |
 
 ## Import Policy

package/docs/contracts/rapidkit-cli-contracts.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://getrapidkit.com/schemas/rapidkit-cli-contracts.json",
-    "title": "RapidKit Core CLI Contracts",
+    "$id": "https://workspai.dev/schemas/rapidkit-cli-contracts.json",
+    "title": "Workspai CLI Contracts (RapidKit Core Compatibility)",
     "type": "object",
     "definitions": {
         "VersionResponse": {

package/docs/create-planner-capabilities.md

@@ -21,10 +21,15 @@ Native create is reserved for Workspai-owned kits with deterministic contracts:
 - Go Fiber and Go Gin
 - Spring Boot
 - ASP.NET Core Web API
+- Rust / Axum
 
 These kits can be exposed through `workspai create project` because Workspai can
 create the project and immediately produce the expected `.workspai` metadata,
 workspace registry entries, doctor evidence, and workspace model data.
+They use a tested dependency baseline instead of floating to new upstream
+majors during creation. Baseline upgrades ship as reviewed Workspai changes so
+the same Workspai version remains reproducible across developer machines and
+CI.
 
 ## Official generators
 
@@ -35,19 +40,45 @@ by Workspai and then registered in Workspace Intelligence:
 - React Router: `npx create-react-router@latest <name>`
 - React, Vue, Svelte, Solid, and Vite: `npm create vite@latest <name> ...`
 - Nuxt: `npx create-nuxt@latest <name> ...`
-- Angular: `npx @angular/cli@19 new <name>`
-- Astro: `npm create astro@4 <name>`
+- Angular: `npx @angular/cli@latest new <name>`
+- Astro: `npm create astro@latest <name>`
 - SvelteKit: `npx sv@latest create <name>`
+- Tauri: `npm create tauri-app@latest <name> -- --template vanilla-ts`
+- Electron Forge: `npx create-electron-app@latest <name> --template=vite-typescript`
+- VS Code Extension: `npx --package yo@latest --package generator-code@latest -- yo code <name> ...`
+- Laravel: `composer create-project --no-interaction --prefer-dist --stability=stable laravel/laravel <name>`
+
+### Stable version and runtime policy
+
+Available official entries request the ecosystem's current stable release at
+execution time; Workspai does not silently pin an older framework major. npm
+generators use the `latest` distribution tag and Composer is restricted to
+stable packages. npm engine checks run in strict mode, so an upstream generator
+that does not support the operator's Node.js runtime stops before Workspai
+claims the scaffold is usable.
+
+Workspai also checks non-Node prerequisites before invoking a generator:
+
+- Tauri requires Rust and Cargo in addition to its platform-specific system
+  dependencies.
+- Electron Forge requires Git.
+- VS Code Extension generation requires Git unless `--skip-git` is selected.
+- Laravel requires PHP and Composer; Node.js/npm remain recommended for
+  frontend asset workflows.
+
+The official generator remains the authority for exact framework/runtime
+compatibility because its stable requirements can change independently of a
+Workspai release. The selected policy is persisted as `latest-stable` in
+project metadata and create evidence.
 
 Other ecosystems are planned official handoffs but are not automated yet:
 
 - WordPress site: `wp core download`, `wp config create`, `wp db create`, `wp core install`
 - WordPress block/plugin: `npx @wordpress/create-block@latest <slug>`
-- Laravel: `composer create-project laravel/laravel <name>`
 - Symfony: `composer create-project symfony/skeleton <name>`
 - Rails: `rails new <name>`
 
-These are `official` candidates, not active native kits. Until each planned
+The remaining entries are `official` candidates, not active native kits. Until each planned
 post-create contract is implemented end to end, Workspai should guide users to
 create externally and then adopt/import the project.
 
@@ -72,7 +103,7 @@ Adoption still gives the project Workspace Intelligence:
 ## Product rule
 
 Do not convert an unsupported or ambiguous stack request into a different native
-kit. For example, a PHP, WordPress, Laravel, Symfony, or Rails request must not
+kit. For example, a WordPress, Symfony, or Rails request must not
 be translated into FastAPI, NestJS, Go, Java, .NET, or a frontend kit.
 
 If executable create is unavailable, the planner should explain the supported

package/docs/creating-workspaces-and-projects.md

@@ -204,12 +204,29 @@ or update a registry.
 Workspace creation does not merge into or overwrite an existing target. If the
 resolved directory already exists, choose another name or output parent.
 
-To bring an existing repository into Workspai, use `adopt` or `import` instead:
+To bring existing software into Workspai, use the operation that matches who
+owns its location:
 
 ```bash
+# Keep a project where it is.
 npx workspai adopt /path/to/project
+
+# Copy or clone a project into the selected workspace.
+npx workspai import /path/to/project --workspace /path/to/my-workspace
+
+# Register an existing Workspai workspace without moving it.
+npx workspai workspace connect /path/to/existing-workspace
+
+# Restore and register a portable workspace archive.
+npx workspai workspace import team.workspai-archive.zip --output ./team
 ```
 
+Running `npx workspai create` interactively exposes the same choices as
+“Create a project”, “Add existing software”, and—when appropriate—“Create
+another workspace”. Inside a workspace, project and onboarding choices appear
+first; creating another workspace remains an explicit escape hatch rather than
+the default.
+
 ## Main workspace files
 
 A normal workspace includes:
@@ -249,7 +266,7 @@ npx workspai create
 If you choose project creation, the same project flow is used.
 
 When the terminal is interactive and the current directory is not inside a
-workspace, **every supported backend and frontend kit** shows the workspace
+workspace, **every supported backend, frontend, desktop, and extension kit** shows the workspace
 management question before scaffolding:
 
 ```text
@@ -275,7 +292,12 @@ npx workspai create project fastapi.standard api
 npx workspai create project gofiber.standard gateway
 npx workspai create project springboot.standard orders
 npx workspai create project dotnet.webapi.clean billing
+npx workspai create project rust.axum telemetry-api
 npx workspai create project frontend.nextjs dashboard
+npx workspai create project desktop.tauri desktop-app
+npx workspai create project desktop.electron admin-console
+npx workspai create project extension.vscode editor-tools
+npx workspai create project php.laravel customer-api
 ```
 
 The shorter frontend alias remains available:
@@ -295,6 +317,7 @@ npx workspai create frontend nextjs dashboard
 | `gogin.standard`      | Go      | Workspai npm CLI     | No                   |
 | `springboot.standard` | Java    | Workspai npm CLI     | No                   |
 | `dotnet.webapi.clean` | .NET    | Workspai npm CLI     | No                   |
+| `rust.axum`           | Rust    | Workspai npm CLI     | No                   |
 
 NestJS runs on Node.js, but its current scaffold is provided through the
 RapidKit Core bridge.
@@ -320,6 +343,34 @@ Workspai has official-generator paths for:
 The ecosystem's official generator creates the application. Workspai then adds
 project metadata and performs the selected workspace registration.
 
+## Desktop, extension, and additional backend generators
+
+| Category  | Project           | Kit                | Creation owner                         |
+| --------- | ----------------- | ------------------ | -------------------------------------- |
+| Backend   | Axum              | `rust.axum`        | Workspai deterministic Cargo baseline |
+| Backend   | Laravel           | `php.laravel`      | Composer / Laravel                     |
+| Desktop   | Tauri             | `desktop.tauri`    | create-tauri-app                       |
+| Desktop   | Electron Forge    | `desktop.electron` | create-electron-app                    |
+| Extension | VS Code Extension | `extension.vscode` | generator-code                         |
+
+Every generated project receives a canonical `kind` and `category`. The four
+user-facing categories are `backend`, `frontend`, `desktop`, and `extension`;
+they remain visible in the Workspace Model and Knowledge Graph so consumers do
+not have to guess a project’s role from its runtime.
+
+Official generators may download packages and therefore need network access.
+Each available integration requests the upstream latest stable channel rather
+than pinning an old framework major. npm engine compatibility is enforced
+strictly against the Node.js runtime running Workspai, and required ecosystem
+tools such as Rust/Cargo, Git, PHP, or Composer are checked before generation.
+The upstream generator remains authoritative for its exact supported runtime
+range; Workspai records the `latest-stable` policy in the generated project
+metadata and evidence.
+
+`desktop.electron`, `extension.vscode`, and `php.laravel` do not accept
+`--skip-install`, because their official generators do not expose a reliable,
+documented no-install contract.
+
 # Where the project is created
 
 The project path is always:
@@ -441,6 +492,9 @@ npx workspai create project gofiber.standard gateway \
 
 Unlike `create workspace --here`, this turns the current directory itself into
 a workspace. It then creates the project under the requested output parent.
+This registration is foundation-only: it does not probe Python or Poetry,
+create a virtual environment, or install `rapidkit-core`. The selected kit owns
+its runtime prerequisites and installation flow.
 
 For example, from `/home/me/platform`:
 
@@ -449,7 +503,9 @@ Workspace: /home/me/platform
 Project:   /home/me/platform/gateway
 ```
 
-This uses the full current-folder workspace registration flow.
+This uses the full current-folder Workspace Intelligence registration flow
+(contract, model, graph, agent context, and registry) without coupling the
+workspace to the optional Python engine.
 
 ## Choice 3: Create without workspace management