workspai 0.48.0 → 0.50.0

package/README.md

@@ -9,17 +9,17 @@
 
 > One workspace. One truth. Humans and AI aligned.
 
-Workspai is an open-source CLI that turns one or many software projects into an
-organized, evidence-backed view of the whole system. Developers, CI, IDEs,
-MCP-compatible tools, and AI agents can use the same current model instead of
-rebuilding a different picture from scattered files.
+Workspai is an open-source CLI that connects one or many software projects and
+keeps a current, checkable view of the whole system. Developers, CI, IDEs,
+MCP-compatible tools, and AI agents can use that same view instead of rebuilding
+different context from scattered files.
 
 - **See the system:** projects, runtimes, APIs, dependencies, infrastructure,
   documentation, policies, and release state in one model.
-- **Ask with proof:** bounded graph answers linked to the files and facts that
-  support them.
-- **Act with confidence:** change impact, health, verification, readiness, and
-  agent context from one defined and versioned intelligence chain.
+- **Ask with proof:** get focused answers that link back to the supporting files
+  and facts.
+- **Change with confidence:** see what may be affected, run the right checks,
+  and prepare useful context for AI tools.
 
 [Quickstart](#start-in-two-minutes) ·
 [Architecture](#from-code-to-shared-understanding) ·
@@ -30,22 +30,24 @@ rebuilding a different picture from scattered files.
 ## Understand Workspai in one minute
 
 Your software system is more than a repository. It may include several
-applications and services, shared packages, API contracts, deployment files,
-documentation, tests, ownership, and CI evidence. Workspai connects those
-surfaces without making AI the source of truth.
+applications and services, shared packages, API definitions, deployment files,
+documentation, tests, owners, and CI results. Workspai connects those parts
+without asking an AI model to decide what is true.
 
 | Term                | Plain-language meaning                                                               |
 | ------------------- | ------------------------------------------------------------------------------------ |
-| **Workspace**       | The managed boundary containing registered projects, policy, contracts, and evidence |
-| **Project**         | An application, service, library, or existing source tree connected to the workspace |
-| **Workspace Model** | The authoritative structured record used to generate the other views and artifacts   |
-| **Knowledge Graph** | A queryable representation derived from the model, with typed relations and proofs   |
-| **Evidence**        | The source, observation, hash, or report that justifies a fact or decision           |
-| **Artifact**        | A durable file under `.workspai/` that another tool can safely consume               |
-
-The Workspace Model is the canonical source of truth. The Knowledge Graph is a
-derived, revision-bound representation—not a competing truth and not an
-LLM-generated guess.
+| **Workspace**       | A home for related projects, shared rules, and saved results                         |
+| **Project**         | An application, service, library, or existing source folder connected to a workspace |
+| **Workspace Model** | The main saved record of what Workspai knows about the system                        |
+| **Knowledge Graph** | A searchable map built from the model, with links back to supporting files           |
+| **Evidence**        | The file, observation, hash, or report that supports an answer                       |
+| **Artifact**        | A file under `.workspai/` that people and other tools can read                       |
+
+The Workspace Model is the canonical source of truth. This means it is the main
+saved record. The Knowledge Graph is built from that record to make
+relationships easy to search; it is not a second truth and it is not an AI
+guess. In the technical contract, the graph is a derived, revision-bound
+representation of the model.
 
 The deterministic model, graph, contracts, and verification chain do not
 require an AI API key. Optional AI-backed features declare that dependency
@@ -67,35 +69,45 @@ Global installation is optional. Every example below also works with
 npx wspai --help
 ```
 
-`workspai` is the canonical npm package and command. `wspai` is an optional
-short alias for `npx` workflows. This package is the active CLI boundary in the
+`workspai` is the main npm package and command. `wspai` is an optional shorter
+name for interactive use. This package is the active CLI in the
 [Workspai monorepo](../../README.md).
 
-### 2. Create a lightweight workspace and connect existing source
+### 2. Connect an existing project
 
 ```bash
-npx workspai create workspace platform --profile minimal --yes
-npx workspai adopt /absolute/path/to/project \
-  --workspace ~/.workspai/workspaces/platform \
-  --json
-cd ~/.workspai/workspaces/platform
+cd /absolute/path/to/project
+npx workspai adopt .
 ```
 
-`adopt` registers the project without moving or copying it. To create new
-software instead, start with `npx workspai create` or read
-[Creating Workspaces and Projects](docs/creating-workspaces-and-projects.md).
+`adopt` registers the project without moving or copying it. When run outside a
+workspace, it creates or reuses the minimal default workspace and binds the
+project to it.
 
-### 3. Run the complete Workspace Intelligence chain
+### 3. Continue from the project
+
+The project is now a first-class entry point into its Workspai workspace. Stay
+in the project directory and run:
 
 ```bash
-npx workspai workspace intelligence run --for-agent codex --strict --json
+npx workspai project workspace status --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
-`codex` selects the generated agent-facing surface; use another supported agent
-identifier when needed. The underlying intelligence chain and evidence remain
-the same.
+Workspai resolves the canonical workspace through a validated machine-local
+link. That link is gitignored; portable project grounding and bounded agent
+context are written under the project's `.workspai/` directory. The project
+lens carries bounded topology, related projects, API/deployment/test surfaces,
+current blockers, proof paths, and model/graph freshness without copying the
+full workspace graph. You only need `--workspace <path>` when resolving an
+ambiguous or moved binding.
+
+`generic` creates vendor-neutral context. Use `codex`, `claude`, `cursor`, or
+`orca` when you want context shaped for that agent. Agent Sync also writes the
+shared files used by GitHub Copilot, VS Code, and `AGENTS.md` consumers without
+changing the system information or the checks Workspai runs.
 
-The run creates durable, discoverable output:
+The run saves its results so people and tools can inspect and reuse them:
 
 ```text
 .workspai/
@@ -113,20 +125,63 @@ The run creates durable, discoverable output:
 AGENTS.md
 ```
 
-Exit code `0` means passed, `1` means execution failed, and `2` means the run
-completed but current evidence blocks the requested decision. A blocked result
+Each registered project also receives:
+
+```text
+.workspai/
+├── workspace-link.local.json        # machine-local, gitignored
+├── PROJECT-GROUNDING.md             # portable entry guide
+└── reports/project-context-agent.json
+AGENTS.md                             # existing content preserved
+```
+
+For automation details, including exit codes and blocked results, see the
+[Unified runner guide](docs/workspace-intelligence-runner.md). A blocked result
 is useful evidence, not a crashed command.
 
-The broader governance and release pipeline is a separate gate when you are
-ready; it is not a substitute for the canonical chain:
+When you are ready for the broader release workflow, run:
 
 ```bash
 npx workspai pipeline --json --strict
 ```
 
+Starting new software instead?
+
+```bash
+npx workspai create workspace my-workspace --profile minimal --yes
+cd ~/.workspai/workspaces/my-workspace
+npx workspai create project nextjs web --yes
+```
+
+The project picker is organized by **Backend**, **Frontend**, **Desktop**, and
+**Extension**. In addition to the existing web and service starters, Workspai
+can create Axum, Tauri, Electron, VS Code extension, and Laravel projects:
+
+```bash
+npx workspai create project rust.axum api
+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 web-api
+```
+
+Axum is a deterministic Workspai-owned baseline. Tauri, Electron, VS Code, and
+Laravel use their ecosystem generator, after which Workspai writes canonical
+project metadata and joins the project to the same Model, Doctor, Graph, and
+agent-context pipeline. All available official generators request their latest
+stable channel, enforce Node engine compatibility, check required local
+toolchains, and record that policy in project evidence. Frontend remains a
+first-class project category rather than being folded into a generic Node
+project.
+
+From the `my-workspace` terminal, create a project, use `adopt` to link one in
+place, or use `import` to copy or clone one into the workspace. See
+[Creating Workspaces and Projects](docs/creating-workspaces-and-projects.md)
+for supported starters.
+
 ## From Code to Shared Understanding
 
-![From Code to Shared Understanding](https://raw.githubusercontent.com/rapidkitlabs/workspai/main/packages/cli/docs/From%20Code%20to%20Shared%20Understanding.png)
+![From Code to Shared Understanding](https://raw.githubusercontent.com/chistiq/workspai/main/packages/cli/docs/From%20Code%20to%20Shared%20Understanding.png)
 
 [View the Mermaid source and explanation](docs/from-code-to-shared-understanding.md).
 
@@ -135,18 +190,16 @@ Workspai is the deterministic layer between source code and its consumers:
 ```text
 Code · packages · APIs · infrastructure · docs · CI · policies
                               │
-                   deterministic providers
-                              │
-                       facts + proofs
+             registration · detection · contract reconciliation
                               │
                   Canonical Workspace Model
-                       │              │
-                       │              └── Evidence-backed Knowledge Graph
-                       │                         │
-                       └──────────┬──────────────┘
-                                  │
+                              │
+               bounded providers · facts · proofs
+                              │
+               Evidence-backed Knowledge Graph
+                              │
                 diff · impact · verify · context · explain
-                                  │
+                              │
                Developers · CI · IDEs · MCP · AI agents
 ```
 
@@ -155,6 +208,7 @@ Code · packages · APIs · infrastructure · docs · CI · policies
 | **Model**             | What projects, runtimes, frameworks, commands, policies, contracts, and dependencies exist? |
 | **Snapshot and diff** | What changed between two known workspace states?                                            |
 | **Impact**            | Which projects and transitive dependents are affected?                                      |
+| **Doctor**            | Which runtime check failed, what graph evidence is related, and what should verify the fix? |
 | **Evidence**          | What do health, analysis, contracts, and readiness reports prove?                           |
 | **Verify**            | Is the affected workspace ready, blocked, stale, or missing evidence?                       |
 | **Context**           | What should developers, IDEs, and AI agents know before acting?                             |
@@ -266,11 +320,13 @@ reruns.
 
 ### Governance and operations
 
-| What you need                        | Command                                                                     |
-| ------------------------------------ | --------------------------------------------------------------------------- |
-| Run affected project tests           | `npx workspai workspace run test --affected --blast-radius --json`          |
-| Run the release/governance gate      | `npx workspai pipeline --json --strict`                                     |
-| Run the canonical intelligence chain | `npx workspai workspace intelligence run --for-agent codex --strict --json` |
+| What you need                        | Command                                                                       |
+| ------------------------------------ | ----------------------------------------------------------------------------- |
+| Run affected project tests           | `npx workspai workspace run test --affected --blast-radius --json`            |
+| Measure one project's test coverage  | `npx workspai project coverage --run --target 80 --strict --json`             |
+| Diagnose one project                 | `npx workspai doctor project --json`                                          |
+| Run the release/governance gate      | `npx workspai pipeline --json --strict`                                       |
+| Run the canonical intelligence chain | `npx workspai workspace intelligence run --for-agent generic --strict --json` |
 
 `workspace verify` consumes current impact, doctor, contract, analysis, and
 readiness evidence. Use `workspace intelligence run` for the canonical chain,
@@ -280,7 +336,7 @@ Other useful operational commands:
 
 ```bash
 npx workspai doctor workspace
-npx workspai setup <python|node|go|java|dotnet> [--warm-deps]
+npx workspai setup <python|node|go|java|dotnet|rust|php> [--warm-deps]
 npx workspai workspace list
 npx workspai cache <status|clear|prune|repair>
 npx workspai mirror <status|sync|verify|rotate>
@@ -312,6 +368,12 @@ developers, CI, IDEs, and agents reason over the same blast radius.
 
 ### Ground AI tools
 
+Workspai creates the initial model, graph, context, `AGENTS.md`, report index,
+skills, and supported agent/IDE files with the workspace. It refreshes them
+after successful project creation, adoption, import, or workspace connection.
+Run Agent Sync directly only when you want an explicit refresh or different
+targets/preset:
+
 ```bash
 npx workspai workspace agent-sync \
   --write \
@@ -330,6 +392,15 @@ and reproducible token-efficiency methodology, see the
 [Workspace Knowledge Graph guide](docs/workspace-knowledge-graph.md) and
 [Graph Benchmark Methodology](docs/graph-benchmark-methodology.md).
 
+The integrated CLI has one canonical direction: **Workspace Model → Knowledge
+Graph**. The model owns the workspace boundary and compact project topology;
+bounded providers enrich that inventory into proof-backed cross-domain
+relationships without writing back into the model. Both artifacts are published
+under one lock with rollback, and the graph contract fixes its source to
+`.workspai/reports/workspace-model.json` plus the model's stable structural
+SHA-256. Doctor, Context, MCP, and graph streaming reject a mismatched persisted
+graph.
+
 ## Outputs and Consumers
 
 Workspai separates human output, machine output, and durable cross-tool state:
@@ -383,18 +454,23 @@ tools without changing the source of truth:
 
 All onboarding routes feed the same Workspace Intelligence model.
 
-| Route            | Use it when                                       | Example                                                                                                  |
-| ---------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| Adopt            | Existing source should stay in place              | `npx workspai adopt /path/to/project --json`                                                             |
-| Import local     | Existing source should be copied into a workspace | `npx workspai import ../orders-api --workspace /path/to/workspace --json`                                |
-| Import Git       | A repository should be cloned into a workspace    | `npx workspai import https://github.com/acme/orders-api.git --git --workspace /path/to/workspace --json` |
-| Create workspace | You need a new governed boundary                  | `npx workspai create workspace platform --profile polyglot --yes`                                        |
-| Create project   | You need a supported new scaffold                 | `npx workspai create project nextjs web --yes`                                                           |
-| Interactive      | You want Workspai to guide the choice             | `npx workspai create`                                                                                    |
-
-Adopt never moves or copies source. Create can use a Workspai-managed kit or an
-available official ecosystem generator. Unsupported native create requests are
-directed toward official tooling followed by adoption.
+| Route             | Use it when                                       | Example                                                                                                  |
+| ----------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Adopt             | Existing source should stay in place              | `npx workspai adopt /path/to/project --json`                                                             |
+| Import local      | Existing source should be copied into a workspace | `npx workspai import ../orders-api --workspace /path/to/workspace --json`                                |
+| Import Git        | A repository should be cloned into a workspace    | `npx workspai import https://github.com/acme/orders-api.git --git --workspace /path/to/workspace --json` |
+| Connect workspace | An existing workspace should stay in place        | `npx workspai workspace connect /path/to/workspace --json`                                               |
+| Import workspace  | A portable workspace archive should become active | `npx workspai workspace import team.workspai-archive.zip --output ./team --json`                         |
+| Create workspace  | You need a new governed boundary                  | `npx workspai create workspace my-workspace --profile polyglot --yes`                                    |
+| Create project    | You need a supported new scaffold                 | `npx workspai create project nextjs web --yes`                                                           |
+| Interactive       | You want Workspai to guide the choice             | `npx workspai create`                                                                                    |
+
+Adopt and workspace connect never move or copy source. Project import copies or
+clones; workspace import verifies and materializes a portable archive before
+registration. `workspace hydrate` only extracts an archive and intentionally
+does not register it. Create can use a Workspai-managed kit or an available
+official ecosystem generator. Unsupported native create requests are directed
+toward official tooling followed by adoption.
 
 Detailed onboarding behavior:
 
@@ -483,7 +559,7 @@ For command-specific behavior, use the
 
 Workspai is MIT-licensed and developed in the open. Contributions to runtime
 support, contracts, documentation, tests, and Workspace Intelligence workflows
-are welcome.
+are welcome. Workspai is built by [Chistiq](https://chistiq.com/).
 
 From a source checkout:
 
@@ -499,12 +575,12 @@ Go, Java, and .NET are required only for workflows that exercise those runtimes.
 To validate only this package, run `npm --workspace workspai run validate` from
 the monorepo root.
 
-- Read [CONTRIBUTING.md](https://github.com/rapidkitlabs/workspai/blob/main/packages/cli/CONTRIBUTING.md) before submitting changes.
-- Use [GitHub Issues](https://github.com/rapidkitlabs/workspai/issues) for reproducible bugs and feature requests.
-- Use [GitHub Discussions](https://github.com/rapidkitlabs/workspai/discussions) for questions and design conversations.
+- Read [CONTRIBUTING.md](https://github.com/chistiq/workspai/blob/main/packages/cli/CONTRIBUTING.md) before submitting changes.
+- Use [GitHub Issues](https://github.com/chistiq/workspai/issues) for reproducible bugs and feature requests.
+- Use [GitHub Discussions](https://github.com/chistiq/workspai/discussions) for questions and design conversations.
 - Read the [Development Guide](docs/DEVELOPMENT.md) for local workflows.
 - Report vulnerabilities through the [Security Policy](docs/SECURITY.md), not a public issue.
-- Review the [Changelog](https://github.com/rapidkitlabs/workspai/blob/main/packages/cli/CHANGELOG.md) before upgrading.
+- Review the [Changelog](https://github.com/chistiq/workspai/blob/main/packages/cli/CHANGELOG.md) before upgrading.
 
 ## License
 

package/contracts/analyze-last-run.v1.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://getrapidkit.com/schemas/analyze-last-run.v1.json",
-  "title": "RapidKit Analyze Last Run Evidence",
+  "$id": "https://workspai.dev/schemas/analyze-last-run.v1.json",
+  "title": "Workspai Analyze Last Run Evidence",
   "type": "object",
   "required": [
     "schemaVersion",

package/contracts/artifact-remediation-plan.v1.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://rapidkit.dev/contracts/artifact-remediation-plan.v1.json",
-  "title": "RapidKit Artifact Remediation Plan",
+  "$id": "https://workspai.dev/contracts/artifact-remediation-plan.v1.json",
+  "title": "Workspai Artifact Remediation Plan",
   "type": "object",
   "additionalProperties": false,
   "required": ["schemaVersion", "generatedAt", "workspace", "source", "summary", "actions"],
@@ -35,13 +35,7 @@
     "summary": {
       "type": "object",
       "additionalProperties": false,
-      "required": [
-        "artifactsScanned",
-        "cardsCovered",
-        "totalActions",
-        "executableActions",
-        "risk"
-      ],
+      "required": ["artifactsScanned", "cardsCovered", "totalActions", "executableActions", "risk"],
       "properties": {
         "artifactsScanned": { "type": "integer", "minimum": 0 },
         "cardsCovered": { "type": "integer", "minimum": 0 },

package/contracts/autopilot-release.v1.json

@@ -1,5 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/autopilot-release.v1.json",
+  "title": "Workspai Autopilot Release Evidence",
   "type": "object",
   "required": [
     "schemaVersion",

package/contracts/bootstrap-compliance.v1.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://getrapidkit.com/schemas/bootstrap-compliance.v1.json",
+  "$id": "https://workspai.dev/schemas/bootstrap-compliance.v1.json",
+  "title": "Workspai Bootstrap Compliance Evidence",
   "type": "object",
   "required": ["schemaVersion", "command", "timestamp", "result", "checks"],
   "properties": {

package/contracts/cli-log-event.v1.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://getrapidkit.com/schemas/cli-log-event.v1.json",
+  "$id": "https://workspai.dev/schemas/cli-log-event.v1.json",
   "title": "Workspai CLI Log Event",
   "description": "NDJSON stream events emitted on stderr when RAPIDKIT_LOG_FORMAT=json or --log-format json",
   "type": "object",

package/contracts/cli-runtime-command-inventory.v1.snapshot.json

@@ -31,6 +31,10 @@
           "flags": "--enable-modules",
           "attributeName": "enableModules"
         },
+        {
+          "flags": "--project-grounding <mode>",
+          "attributeName": "projectGrounding"
+        },
         {
           "flags": "--dry-run",
           "attributeName": "dryRun"
@@ -432,6 +436,10 @@
           "flags": "--enable-modules",
           "attributeName": "enableModules"
         },
+        {
+          "flags": "--project-grounding <mode>",
+          "attributeName": "projectGrounding"
+        },
         {
           "flags": "--git",
           "attributeName": "git"
@@ -836,6 +844,41 @@
         }
       ]
     },
+    {
+      "path": [
+        "project",
+        "coverage"
+      ],
+      "command": "coverage",
+      "parent": "project",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Inspect or run runtime-native test coverage and publish normalized project evidence",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--project <path>",
+          "attributeName": "project"
+        },
+        {
+          "flags": "--target <percent>",
+          "attributeName": "target"
+        },
+        {
+          "flags": "--run",
+          "attributeName": "run"
+        },
+        {
+          "flags": "--strict",
+          "attributeName": "strict"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        }
+      ]
+    },
     {
       "path": [
         "project",
@@ -926,6 +969,39 @@
         }
       ]
     },
+    {
+      "path": [
+        "project",
+        "workspace"
+      ],
+      "command": "workspace",
+      "parent": "project",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Show or repair the canonical workspace binding for the current Workspai project",
+      "hidden": false,
+      "arguments": [
+        {
+          "name": "action",
+          "required": false,
+          "variadic": false
+        }
+      ],
+      "options": [
+        {
+          "flags": "--workspace <path>",
+          "attributeName": "workspace"
+        },
+        {
+          "flags": "--project <path>",
+          "attributeName": "project"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        }
+      ]
+    },
     {
       "path": [
         "readiness"
@@ -1216,6 +1292,10 @@
           "flags": "--once",
           "attributeName": "once"
         },
+        {
+          "flags": "--graph-stream",
+          "attributeName": "graphStream"
+        },
         {
           "flags": "--for-agent [agent]",
           "attributeName": "forAgent"
@@ -1236,6 +1316,10 @@
           "flags": "--preset <preset>",
           "attributeName": "preset"
         },
+        {
+          "flags": "--project-grounding <mode>",
+          "attributeName": "projectGrounding"
+        },
         {
           "flags": "--refresh-context",
           "attributeName": "refreshContext"

package/contracts/compatibility-matrix.v1.json

@@ -1,5 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/compatibility-matrix.v1.json",
+  "title": "Workspai Compatibility Matrix",
   "type": "object",
   "required": [
     "schemaVersion",