workspai 0.49.0 → 0.51.0

package/docs/GLOSSARY.md

@@ -5,22 +5,23 @@ CI workflows, and AI consumers.
 
 ## Core concepts
 
-| Term               | Plain-language meaning                                                                                                                                      |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Workspace          | A governed collection of one or more registered projects. It is not required to be a Git monorepo.                                                          |
-| Project            | One registered application, service, library, or infrastructure unit inside or linked to a workspace.                                                       |
-| Workspace manifest | `.workspai/workspace.json`; workspace identity, profile, engine, and bootstrap metadata. It is not the project registry.                                    |
-| Workspace contract | `.workspai/workspace.contract.json`; the operational registry of projects and their declared ports, APIs, ownership, and relationships.                     |
-| Registry summary   | `.workspai/workspace-registry.v1.json`; the canonical lightweight project count and registry status for UI and CI.                                          |
-| Workspace Model    | The canonical, deterministic structural description produced from registered projects, manifests, contracts, policies, and detected facts.                  |
-| Knowledge Graph    | A proof-backed representation derived from the Workspace Model. It makes entities and relationships queryable; it is not the source of truth for the model. |
-| Dependency graph   | The project-to-project dependency subgraph embedded in the Workspace Model and used by impact and verification.                                             |
-| Provider           | A deterministic source adapter that emits facts from code, manifests, APIs, infrastructure, documentation, Git, or another supported source.                |
-| Fact               | A normalized observation about the workspace, such as a package, endpoint, import, deployment, or owner.                                                    |
-| Evidence / proof   | The source location and extraction details that justify a fact or relationship.                                                                             |
-| Proof path         | A traceable route from a query result or relationship back to its supporting evidence.                                                                      |
-| Artifact           | A versioned file written under `.workspai/`, usually `.workspai/reports/`, for people or automation to consume.                                             |
-| Command projection | The JSON returned on stdout for one command. It can include status and output metadata around a canonical artifact payload.                                 |
+| Term                  | Plain-language meaning                                                                                                                                                                                |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Workspace             | A governed collection of one or more registered projects. It is not required to be a Git monorepo.                                                                                                    |
+| Project               | One registered application, service, library, or infrastructure unit inside or linked to a workspace.                                                                                                 |
+| Workspace manifest    | `.workspai/workspace.json`; workspace identity, profile, engine, and bootstrap metadata. It is not the project registry.                                                                              |
+| Workspace contract    | `.workspai/workspace.contract.json`; the operational registry of projects and their declared ports, APIs, ownership, and relationships.                                                               |
+| Registry summary      | `.workspai/workspace-registry.v1.json`; the canonical lightweight project count and registry status for UI and CI.                                                                                    |
+| Workspace Model       | The canonical, deterministic structural description produced from registered projects, manifests, contracts, policies, and detected facts.                                                            |
+| Knowledge Graph       | A proof-backed representation derived from and structurally bound to the canonical Workspace Model. It makes entities and relationships queryable; it cannot replace or mutate the authorizing model. |
+| Structural model hash | A stable SHA-256 over model structure. Volatile timestamps, run correlation, live evidence references, and freshness fields are excluded so harmless refreshes do not create false graph drift.       |
+| Dependency graph      | The project-to-project dependency subgraph embedded in the Workspace Model and used by impact and verification.                                                                                       |
+| Provider              | A deterministic source adapter that emits facts from code, manifests, APIs, infrastructure, documentation, Git, or another supported source.                                                          |
+| Fact                  | A normalized observation about the workspace, such as a package, endpoint, import, deployment, or owner.                                                                                              |
+| Evidence / proof      | The source location and extraction details that justify a fact or relationship.                                                                                                                       |
+| Proof path            | A traceable route from a query result or relationship back to its supporting evidence.                                                                                                                |
+| Artifact              | A versioned file written under `.workspai/`, usually `.workspai/reports/`, for people or automation to consume.                                                                                       |
+| Command projection    | The JSON returned on stdout for one command. It can include status and output metadata around a canonical artifact payload.                                                                           |
 
 ## Intelligence and governance
 

package/docs/OPEN_SOURCE_USER_SCENARIOS.md

@@ -17,10 +17,10 @@ Goal: connect code you already have without reshuffling repositories.
 ### Adopt in place (keep source where it is)
 
 ```bash
-npx workspai adopt /path/to/existing-app --workspace /path/to/workspace --json
-cd /path/to/workspace
-npx workspai workspace intelligence run --for-agent generic --strict --json
 cd /path/to/existing-app
+npx workspai adopt . --workspace /path/to/workspace --json
+npx workspai project workspace status --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 npx workspai doctor project --json
 ```
 
@@ -91,6 +91,11 @@ The canonical durable outputs are `.workspai/reports/workspace-model.json`,
 Use `npx workspai pipeline --json --strict` separately as the broader governance
 and release gate.
 
+The model is the canonical workspace boundary. The Knowledge Graph is generated
+from that model-owned inventory, structurally hash-bound to it, and enriched
+with provider facts and proofs. Consumers must not treat the graph as a second
+source of truth.
+
 Success check: the application starts locally, project Doctor reports the
 expected runtime, and the unified run report contains all 11 ordered stages.
 

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

@@ -1,130 +1,114 @@
 # README Content Contract
 
-The repository README is Workspai's primary product entry point. It must help a
-new user understand the problem, see a concrete result, run a safe quickstart,
-and choose the next document without first learning the internal architecture.
-
-This contract keeps that experience aligned with the CLI's machine-readable
-contracts. It applies to the root `README.md`; the package README may add detail
-but must not contradict it.
-
-The npm package README at `packages/cli/README.md` is the operational product
-entry point. It follows the same truth boundaries but adds beginner definitions,
-a copyable workspace onboarding path, exact exit semantics, command families,
-durable outputs, requirements, and troubleshooting.
-
-## Required reader journey
-
-The root README keeps these sections in this order:
-
-1. `Workspace Intelligence for software systems` — the category, slogan, and
-   three user outcomes;
-2. `See your workspace as a system` — a concrete before/after mental model;
-3. `Start in two minutes` — install, connect software, run the canonical chain;
-4. `What Workspai gives you` — user questions mapped to product outcomes;
-5. `How Workspace Intelligence works` — sources, facts, model, graph, decisions,
-   and consumers;
-6. `Evidence, not guesses` — identity, proof, bounded retrieval, and unknown
-   relationships;
-7. `Measure context honestly` — reproducible numbers and claim boundaries;
-8. `One contract-backed intelligence chain` — the canonical runner and its
-   distinction from `pipeline`;
-9. `Choose your workflow` — goal-oriented routing;
-10. `Open outputs for every consumer` — human, CI, agent, MCP, IDE, and graph
-    interoperability surfaces;
-11. documentation, packages, contributor, community, and license routes.
-
-Do not move package internals, exhaustive flags, troubleshooting, or contributor
-implementation details above the user value and quickstart.
-
-## CLI package README journey
-
-The CLI README keeps these sections in order:
-
-1. product category and the `See / Ask with proof / Act with confidence` value;
-2. plain-language definitions of Workspace, Project, Model, Graph, Evidence,
-   and Artifact;
-3. a copyable two-minute path that creates a minimal workspace, adopts source,
-   and runs the canonical chain;
-4. the Model → derived Graph architecture and its unknown-relationship rule;
-5. the exact intelligence chain, evidence, and bounded measurement semantics;
-6. grouped commands, outputs, onboarding choices, integrations, requirements,
-   documentation, and troubleshooting.
-
-Measurement tables must not precede installation or the first successful run.
-Advanced command inventories must be grouped by user goal instead of appearing
-as one undifferentiated command wall.
+The root and npm package READMEs are product entry points, not release logs,
+command references, or architecture specifications.
+
+Their job is to help a new reader answer four questions quickly:
+
+1. What is Workspai?
+2. What problem does it solve?
+3. How can I try it safely?
+4. Where do I go for more detail?
+
+The root README presents the product. The CLI README adds a practical first-run
+path and a small set of everyday commands. Detailed behavior belongs in the
+versioned contracts and focused guides.
+
+## Stable reader journey
+
+The root README keeps this order:
+
+1. product category, slogan, and three outcomes;
+2. one copyable path for existing software and one guided path for new software;
+3. a short outcome-oriented view of what Workspai provides;
+4. the canonical Model → derived Graph boundary and intelligence chain;
+5. consumer surfaces and goal-based documentation links;
+6. package, contributor, community, and license routes.
+
+The CLI README keeps this order:
+
+1. product category, slogan, and value;
+2. a two-minute existing-project path and the guided create path;
+3. the small set of durable outputs a user should recognize;
+4. the canonical Model → derived Graph boundary and intelligence chain;
+5. everyday workflows grouped by goal;
+6. outputs, requirements, documentation, troubleshooting, and contribution.
+
+## What does not belong in a main README
+
+Keep these in their focused documents:
+
+- release-specific changes and version numbers;
+- exhaustive commands, flags, and artifact inventories;
+- exact runner exit-code and failure-propagation semantics;
+- benchmark tables, fixture metadata, and formulas;
+- CI workflow inventories;
+- provider implementation details;
+- schema property documentation;
+- long troubleshooting catalogs;
+- internal package extraction plans.
+
+A README changes only when the product promise, primary onboarding path,
+canonical architecture, supported consumer boundary, or documentation routes
+change. A small implementation feature normally changes the Changelog, Release
+Notes, or a focused guide—not the README.
 
 ## 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.
-- Providers emit facts and proofs; they do not independently own the canonical
-  graph.
+- The Knowledge Graph is a **derived, revision-bound representation** of the
+  governed Workspace Model.
+- Providers enrich the graph with facts and proofs; they do not mutate the
+  authorizing model during the same run.
+- Persisted current-state consumers reject a graph that no longer matches the
+  current model revision and workspace identity.
 - Missing relationships mean **not proven**, not independent.
-- The graph is broader than a code graph, but it is not the entire product.
+- The graph is broader than a repository code graph, but it is not the entire
+  product.
 - The canonical runner is
   `npx workspai workspace intelligence run --for-agent generic --strict --json`.
-- `pipeline` is a broader governance/release orchestrator and must not be taught
-  as a replacement for the intelligence chain.
-- The integrated CLI already exposes current capabilities. Future standalone
-  packages are extraction boundaries, not promises to add currently missing CLI
-  features.
+- `pipeline` is the broader release/governance workflow and does not replace the
+  canonical intelligence chain.
+- Current integrated capabilities are not described as future missing packages.
 
 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 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.
+Markdown explains these contracts; it does not redefine them.
 
 ## Claim policy
 
-Every performance or token statement must identify:
-
-- the workspace or pinned corpus;
-- the query and result limit;
-- whether token counts are estimated, tokenizer-counted, or provider-reported;
-- the baseline;
-- the date or revision;
-- what the measurement does not prove.
+Performance and token claims belong in the benchmark and evaluation guides.
+They must identify the fixture, query, limit, tokenizer or estimate, baseline,
+revision, and limitations. Results vary by workspace and query.
 
-The current fixture may be used only with wording equivalent to:
-
-> On the current 16-project development fixture, one bounded query reduced the
-> estimated retrieval payload by 97.9%; results vary by workspace and query.
-
-Never turn a retrieval-payload result into a universal model-cost, answer-quality,
-or task-success claim. Use `workspace eval` and a verified outcome before making
-execution-efficiency comparisons.
+Do not turn a retrieval-payload result into a universal cost, quality, or
+task-success claim.
 
 ## Command policy
 
 - Quickstarts must be copyable and use the canonical `workspai` package.
-- `wspai` is described only as an optional short alias.
-- A partial sequence such as `model → context` must not be taught as a replacement
-  for the canonical intelligence chain.
-- Every documented command must exist in the runtime command surface or be an
-  ordinary shell command such as `cd` or `npm install`.
-- Durable filenames must come from published contracts or the Artifact Catalog.
-
-## Information hierarchy
-
-Write for three reading depths:
+- `wspai` is only an optional short alias.
+- The main path uses the complete contract-backed intelligence runner.
+- A partial command sequence must not be presented as a replacement loop.
+- Exhaustive syntax belongs in `docs/commands-reference.md`.
 
-1. **Ten seconds:** category, user problem, three outcomes.
-2. **Two minutes:** quickstart, concrete artifacts, architecture, proof example.
-3. **Deep evaluation:** measurements, contracts, guides, boundaries, contributor
-   material.
+## Writing policy
 
-Prefer user questions and outcomes over internal phase names. Define unavoidable
-terms in plain language and link to the glossary.
+- Prefer plain language and short sentences.
+- Explain user outcomes before internal terms.
+- Introduce only the architecture needed to trust the product.
+- Prefer one representative command over a wall of variants.
+- Link to deeper guidance instead of duplicating it.
+- Do not add a README section for every feature or release.
 
 ## Validation
 
@@ -136,19 +120,18 @@ npm run check:generated-contracts
 npm run check:contracts
 ```
 
-`docs-drift-guard.mjs` enforces the required root headings, their order,
-canonical runner, Model/Graph truth boundary, honest measurement language,
-documentation routes, and package-status semantics. `smoke-readme-commands.mjs`
-executes representative documented CLI help surfaces.
+`docs-drift-guard.mjs` verifies the stable reader journey, canonical runner,
+Model/Graph truth boundary, claim boundaries, and documentation routes.
 
 ## Review checklist
 
 Before merging a README change, confirm:
 
-- a new user can explain Workspai without saying “chatbot” or “code generator”;
-- the first quickstart reaches a durable evidence artifact;
-- every architecture statement agrees with the generated contracts;
-- every number is reproducible and bounded;
-- every promised output exists today or is explicitly labelled as future work;
-- links route users by goal rather than exposing the documentation tree;
-- the package table cannot be read as a list of missing product capabilities.
+- the first screen states the product value and slogan;
+- a new user can run one safe path without learning internal architecture;
+- the root README remains comfortably under 250 lines;
+- the CLI README remains comfortably under 350 lines;
+- details already explained elsewhere are linked, not repeated;
+- every architecture statement matches generated contracts;
+- no release-specific prose was added to a main README;
+- the package section cannot be read as a list of missing capabilities.

package/docs/ci-workflows.md

@@ -10,15 +10,24 @@ Map of GitHub Actions workflows in this repository. Use this when editing CI to
 | Workspace E2E matrix     | `.github/workflows/workspace-e2e-matrix.yml`     | Cross-OS workspace lifecycle smoke; setup `--warm-deps`; cache/mirror ops |
 | Windows bridge E2E       | `.github/workflows/windows-bridge-e2e.yml`       | Native Windows bridge and lifecycle checks                                |
 | E2E smoke                | `.github/workflows/e2e-smoke.yml`                | Focused bridge regression smoke                                           |
-| Frontend generator smoke | `.github/workflows/frontend-generator-smoke.yml` | Official frontend generator drift gate                                    |
+| Official generator smoke | `.github/workflows/frontend-generator-smoke.yml` | Contract-driven official-generator drift gate                             |
 | Security                 | `.github/workflows/security.yml`                 | Security scanning and policy checks                                       |
 | Manual npm release       | `.github/workflows/release-npm-manual.yml`       | Maintainer-only release gate and publish workflow                         |
 | Contributor onboarding   | `.github/workflows/contributor-onboarding.yml`   | Accepted-contributor onboarding automation                                |
 | Welcome                  | `.github/workflows/welcome.yml`                  | First-issue and first-contribution messages                               |
 
-The release workflow requires `Frontend Generator Smoke` for the exact release
-SHA. Maintainers must dispatch that workflow against the intended release ref
-before starting a manual npm release if no matching run exists.
+The release workflow requires the cost-bounded
+`Official Generator Smoke · primary` Linux run for the exact release SHA. A
+normal push that touches the contracted generator surface produces this gate;
+maintainers do not need to run the full cross-platform matrix before publishing.
+
+Pushes and pull requests run every contracted generator on the primary Linux
+lane. The weekly schedule and manual dispatch can run the complete Linux,
+macOS, and Windows matrix as a non-blocking compatibility and upstream-drift
+signal. npm and Composer download caches reduce repeated network work without
+caching generated projects; every smoke run still exercises the current
+upstream generator, generated artifacts, build surface, registry, and Doctor
+evidence.
 
 ## Consumer workspace: agent grounding CI
 

package/docs/commands-reference.md

@@ -5,10 +5,10 @@ Complete CLI syntax for the Workspai CLI. For behavior and workflows, see [works
 ## Workspace lifecycle
 
 ```bash
-npx workspai create # Prompts: workspace | project
+npx workspai create # Guided create or existing-software ingestion
 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,9 +153,17 @@ 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
+complete graph. Ranking is deterministic and offline: it removes natural-language
+stopwords, weights rarer graph terms more strongly, and prefers exact labels and
+identities. `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.
@@ -190,9 +213,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 +248,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 +261,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