workspai 0.47.0 → 0.49.0

package/README.md

@@ -1,137 +1,171 @@
 # Workspai CLI
 
-## Open-Source Workspace Intelligence for Software Systems
-
 [![npm version](https://img.shields.io/npm/v/workspai.svg?style=flat-square)](https://www.npmjs.com/package/workspai)
 [![Downloads](https://img.shields.io/npm/dm/workspai.svg?style=flat-square)](https://www.npmjs.com/package/workspai)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
 [![Built by Workspai](https://img.shields.io/badge/Built%20by-Workspai-0f172a?logo=github)](https://workspai.dev)
 
-Not another AI coding assistant.
-Not another agent framework.
-Not another context engine.
+## Workspace Intelligence for software systems
 
 > One workspace. One truth. Humans and AI aligned.
 
-Workspai turns scattered projects into a governed, agent-ready workspace.
-
-It gives developers, CI, IDEs, and AI agents the same evidence-backed source of
-truth: workspace model, agent context, impact analysis, verification evidence,
-contracts, and release gates.
-
-### What changes for the user?
-
-Without Workspai, an agent repeatedly searches files and reconstructs a partial
-picture. With Workspai, it can ask a bounded question and receive the matching
-entities, nearby relations, and source proofs:
-
-```bash
-npx workspai workspace graph search "who implements the login API?" --limit 8 --json
-```
-
-Workspai is broader than a repository code graph. It connects projects, source,
-packages, APIs, infrastructure, pipelines, documentation, decisions, tests, and
-ownership inside one workspace model—then uses that same truth for impact,
-verification, CI, IDEs, MCP, and agent grounding.
-
-### Current measured fixture
-
-| Measure                              | Observed value |
-| ------------------------------------ | -------------: |
-| Registered projects                  |             16 |
-| Knowledge Graph entities             |          1,738 |
-| Knowledge Graph relations            |          2,244 |
-| Portable proofs                      |          2,106 |
-| Readable proof-source artifacts      |            392 |
-| Corpus size (`characters / 4`)       | 134,105 tokens |
-| `api endpoint --limit 8` retrieval   |   2,812 tokens |
-| Observed retrieval payload reduction |          97.9% |
-| Observed corpus/retrieval ratio      |         47.69× |
-
-This is a reproducible observation from one 16-project development workspace on
-2026-07-21, not a universal token-cost or answer-quality claim. See
-[Graph Benchmark Methodology](docs/graph-benchmark-methodology.md) for the source
-hash, formulas, limitations, and publication gate.
-
-## Start here
-
-### Install
+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:** 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) ·
+[Commands](#core-workflows) ·
+[Outputs](#outputs-and-consumers) ·
+[Documentation](#documentation)
+
+## Understand Workspai in one minute
+
+Your software system is more than a repository. It may include several
+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**       | 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
+separately.
+
+## Start in two minutes
+
+### 1. Install or use `npx`
 
 ```bash
 npm install -g workspai
 workspai --help
 ```
 
-For short `npx` workflows, use the separate alias package:
+Global installation is optional. Every example below also works with
+`npx workspai`. The separate `wspai` package is only a short alias:
 
 ```bash
 npx wspai --help
 ```
 
-`workspai` is the canonical npm package and command. `wspai` is an optional
-short alias for `npx` workflows. RapidKit Core is the optional Python engine
-used only by Python/Core-dependent workflows; it is not a replacement CLI.
-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).
 
-### CLI help
-
-Browse all commands from the latest release without a global install:
+### 2. Connect an existing project
 
 ```bash
-npx workspai@latest --help
+cd /absolute/path/to/project
+npx workspai adopt .
 ```
 
-## Get Workspace Intelligence
+`adopt` registers the project without moving or copying it. When run outside a
+workspace, it creates or reuses the minimal default workspace and prints the
+exact `Next shell step`.
 
-Project creation, import, and adoption are entry routes. The core experience
-starts when Workspai builds a durable model of the whole workspace and turns it
-into evidence that different tools can consume.
+### 3. Continue from the workspace root
 
-Connect an existing project without moving or copying its source:
+Without the VS Code extension, copy the printed `Next shell step` and continue
+in that workspace terminal:
 
 ```bash
-npx workspai adopt /path/to/project --json
 cd ~/.workspai/workspaces/workspai
+npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
-Execute the canonical chain and persist the shared model, evidence, and
-agent-ready context:
-
-```bash
-npx workspai workspace intelligence run --for-agent codex --strict --json
-```
+`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.
 
-You now have a common source of truth for projects, runtimes, dependencies,
-commands, policies, contracts, health, and release evidence. The first durable
-outputs include:
+The run saves its results so people and tools can inspect and reuse them:
 
 ```text
-.workspai/reports/workspace-model.json
-.workspai/reports/workspace-context-agent.json
-.workspai/reports/INDEX.json
-.workspai/reports/workspace-intelligence-run-last-run.json
+.workspai/
+├── workspace.json
+├── workspace.contract.json
+├── AGENT-GROUNDING.md
+└── reports/
+    ├── workspace-model.json
+    ├── workspace-knowledge-graph.json
+    ├── workspace-impact-last-run.json
+    ├── workspace-verify-last-run.json
+    ├── workspace-context-agent.json
+    ├── workspace-intelligence-run-last-run.json
+    └── INDEX.json
 AGENTS.md
 ```
 
-Already inside a Workspai workspace? Start directly with the canonical
-`workspace intelligence run --for-agent codex --strict --json` runner.
+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
+```
+
+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).
 
 Workspai is the deterministic layer between source code and its consumers:
 
+```text
+Code · packages · APIs · infrastructure · docs · CI · policies
+                              │
+                   deterministic providers
+                              │
+                       facts + proofs
+                              │
+                  Canonical Workspace Model
+                       │              │
+                       │              └── Evidence-backed Knowledge Graph
+                       │                         │
+                       └──────────┬──────────────┘
+                                  │
+                diff · impact · verify · context · explain
+                                  │
+               Developers · CI · IDEs · MCP · AI agents
+```
+
 | Capability            | What it answers                                                                             |
 | --------------------- | ------------------------------------------------------------------------------------------- |
 | **Model**             | What projects, runtimes, frameworks, commands, policies, contracts, and dependencies exist? |
@@ -147,6 +181,10 @@ Create, import, and adopt add software to this boundary. Workspace Intelligence
 then models and governs every registered project, whether Workspai created it or
 it already existed.
 
+Unlike repository-only code intelligence, the workspace boundary can connect
+evidence across multiple projects and repositories. A missing relationship
+means **not proven by current evidence**, not "these projects are independent."
+
 ## One Intelligence Chain
 
 The canonical execution order is versioned in
@@ -174,29 +212,81 @@ and enforce this exact contract-backed order. `pipeline --json --strict` remains
 the broader governance/release orchestrator (`sync → doctor → analyze → readiness
 → autopilot`); it is not an alias for the canonical intelligence chain.
 
+## Evidence and measurable context
+
+Without bounded retrieval, a developer or agent often has to search and read a
+large part of the workspace before answering a local question. Workspai can
+return the matching entities, nearby relations, and source proofs first:
+
+```bash
+npx workspai workspace graph search "who implements the login API?" --limit 8 --json
+```
+
+Use the complete graph for interchange and audits; use bounded search for
+normal questions and agent context. Workspai reports unknown or unproven
+relationships instead of inventing an edge.
+
+### Current measured fixture
+
+| Measure                              | Observed value |
+| ------------------------------------ | -------------: |
+| Registered projects                  |             16 |
+| Knowledge Graph entities             |          1,738 |
+| Knowledge Graph relations            |          2,244 |
+| Portable proofs                      |          2,106 |
+| Readable proof-source artifacts      |            392 |
+| Corpus size (`characters / 4`)       | 134,105 tokens |
+| `api endpoint --limit 8` retrieval   |   2,812 tokens |
+| Observed retrieval payload reduction |          97.9% |
+| Observed corpus/retrieval ratio      |         47.69× |
+
+This is a reproducible observation from one 16-project development workspace on
+2026-07-22, not a universal token-cost, answer-quality, or task-success claim.
+See [Graph Benchmark Methodology](docs/graph-benchmark-methodology.md) for the
+source hash, formulas, limitations, and publication gate. Use
+`workspace eval` when measuring provider-reported tokens, latency, cost, and a
+verified execution outcome.
+
 ## Core Workflows
 
-| What you need                              | Command                                                                                  |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| Build and persist the current system model | `npx workspai workspace model --json --write`                                            |
-| Generate agent-ready context               | `npx workspai workspace context --for-agent --json --write`                              |
-| Generate portable agent and IDE surfaces   | `npx workspai workspace agent-sync --write --refresh-context --preset enterprise --json` |
-| Save a model baseline                      | `npx workspai workspace snapshot --json`                                                 |
-| Compare with a baseline or Git state       | `npx workspai workspace diff --from <snapshot-or-git-ref> --json`                        |
-| Calculate transitive blast radius          | `npx workspai workspace impact --from <diff-report> --json`                              |
-| Verify affected projects and evidence      | `npx workspai workspace verify --from-impact <impact-report> --json --strict`            |
-| Explain a blocker                          | `npx workspai workspace explain release-blocked --json --write`                          |
-| Inspect a project in the dependency graph  | `npx workspai workspace graph explain <project> --json`                                  |
-| Query proof-backed workspace entities      | `npx workspai workspace graph entities endpoint --json`                                  |
-| Retrieve bounded context for an agent      | `npx workspai workspace graph search "authentication endpoint" --limit 12 --json`        |
-| Measure retrieval payload reduction        | `npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json`     |
-| Trace a relationship and its evidence      | `npx workspai workspace graph path <from> <to> --json`                                   |
-| Compare two knowledge-graph revisions      | `npx workspai workspace graph overlay --from <graph.json> --json`                        |
-| Persist model + agent/MCP graph artifact   | `npx workspai workspace model --write --json`                                            |
-| 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`              |
-| Expose current evidence to MCP clients     | `npx workspai workspace mcp serve`                                                       |
+Use the complete intelligence runner for the normal end-to-end path. The
+individual commands below are useful for inspection, automation, and targeted
+reruns.
+
+### Model, change, and decisions
+
+| What you need                              | Command                                                                       |
+| ------------------------------------------ | ----------------------------------------------------------------------------- |
+| Build and persist the current system model | `npx workspai workspace model --json --write`                                 |
+| Save a model baseline                      | `npx workspai workspace snapshot --json`                                      |
+| Compare with a baseline or Git state       | `npx workspai workspace diff --from <snapshot-or-git-ref> --json`             |
+| Calculate transitive blast radius          | `npx workspai workspace impact --from <diff-report> --json`                   |
+| Verify affected projects and evidence      | `npx workspai workspace verify --from-impact <impact-report> --json --strict` |
+| Explain a blocker                          | `npx workspai workspace explain release-blocked --json --write`               |
+
+### Graph, agents, and interoperability
+
+| What you need                             | Command                                                                                  |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Inspect a project in the dependency graph | `npx workspai workspace graph explain <project> --json`                                  |
+| Query proof-backed workspace entities     | `npx workspai workspace graph entities endpoint --json`                                  |
+| Retrieve bounded context for an agent     | `npx workspai workspace graph search "authentication endpoint" --limit 12 --json`        |
+| Measure retrieval payload reduction       | `npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json`     |
+| Start a model-usage evaluation            | `npx workspai workspace eval init repair-readiness workspace-intelligence --json`        |
+| Export graph for semantic/visual tools    | `npx workspai workspace graph graphml --output workspace-graph.graphml`                  |
+| Trace a relationship and its evidence     | `npx workspai workspace graph path <from> <to> --json`                                   |
+| Compare two knowledge-graph revisions     | `npx workspai workspace graph overlay --from <graph.json> --json`                        |
+| Generate agent-ready context              | `npx workspai workspace context --for-agent --json --write`                              |
+| Generate portable agent and IDE surfaces  | `npx workspai workspace agent-sync --write --refresh-context --preset enterprise --json` |
+| Expose current evidence to MCP clients    | `npx workspai workspace mcp serve`                                                       |
+
+### 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 generic --strict --json` |
 
 `workspace verify` consumes current impact, doctor, contract, analysis, and
 readiness evidence. Use `workspace intelligence run` for the canonical chain,
@@ -272,22 +362,39 @@ Workspai separates human output, machine output, and durable cross-tool state:
 
 Important durable outputs:
 
-| Artifact                                                | Producer                       | Used for                              |
-| ------------------------------------------------------- | ------------------------------ | ------------------------------------- |
-| `.workspai/reports/workspace-model.json`                | `workspace model --write`      | Canonical system structure            |
-| `.workspai/reports/workspace-knowledge-graph.json`      | `workspace model --write`      | Proof-backed retrieval and MCP        |
-| `.workspai/reports/workspace-model-diff-last-run.json`  | `workspace diff`               | Structural change evidence            |
-| `.workspai/reports/workspace-impact-last-run.json`      | `workspace impact`             | Blast radius and affected scope       |
-| `.workspai/reports/workspace-verify-last-run.json`      | `workspace verify`             | Structured verification gate          |
-| `.workspai/reports/workspace-context-agent.json`        | `workspace context --write`    | Canonical agent context               |
-| `.workspai/reports/INDEX.json`                          | `workspace agent-sync --write` | Agent read order and report discovery |
-| `.workspai/reports/workspace-explain-last-run.json`     | `workspace explain --write`    | Evidence-backed narrative             |
-| `.workspai/reports/workspace-intelligence-history.json` | Verify and feedback flows      | Trends and audit history              |
-| `.workspai/reports/pipeline-last-run.json`              | `pipeline --json`              | CI and release workflow result        |
+| Artifact                                                            | Producer                       | Used for                                         |
+| ------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------ |
+| `.workspai/reports/workspace-model.json`                            | `workspace model --write`      | Canonical system structure                       |
+| `.workspai/reports/workspace-knowledge-graph.json`                  | `workspace model --write`      | Proof-backed retrieval and MCP                   |
+| `.workspai/reports/workspace-model-diff-last-run.json`              | `workspace diff`               | Structural change evidence                       |
+| `.workspai/reports/workspace-impact-last-run.json`                  | `workspace impact`             | Blast radius and affected scope                  |
+| `.workspai/reports/workspace-verify-last-run.json`                  | `workspace verify`             | Structured verification gate                     |
+| `.workspai/reports/workspace-context-agent.json`                    | `workspace context --write`    | Canonical agent context                          |
+| `.workspai/reports/INDEX.json`                                      | `workspace agent-sync --write` | Agent read order and report discovery            |
+| `.workspai/reports/workspace-explain-last-run.json`                 | `workspace explain --write`    | Evidence-backed narrative                        |
+| `.workspai/reports/workspace-intelligence-history.json`             | Verify and feedback flows      | Trends and audit history                         |
+| `.workspai/reports/workspace-intelligence-evaluation-live.json`     | `workspace eval init/record`   | Live provider/tokenizer usage and activity       |
+| `.workspai/reports/workspace-intelligence-evaluation-last-run.json` | `workspace eval report`        | Final usage, cost, and verified outcome evidence |
+| `.workspai/reports/pipeline-last-run.json`                          | `pipeline --json`              | CI and release workflow result                   |
 
 See the [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md) for the complete
 writer, schema, and consumer map.
 
+### Graph interchange formats
+
+The canonical persisted graph is JSON. Explicit projections make the same
+governed data usable in documentation, semantic systems, and visualization
+tools without changing the source of truth:
+
+| Format  | Typical use                             | Command selector              |
+| ------- | --------------------------------------- | ----------------------------- |
+| JSON    | Canonical artifact and programmatic use | `workspace graph emit --json` |
+| JSON-LD | Semantic-web and linked-data tools      | `workspace graph jsonld`      |
+| Mermaid | Markdown documentation and diagrams     | `workspace graph mermaid`     |
+| DOT     | Graphviz rendering                      | `workspace graph dot`         |
+| GraphML | General graph analysis tools            | `workspace graph graphml`     |
+| GEXF    | Exploration and visualization tools     | `workspace graph gexf`        |
+
 ## Onboard Software
 
 All onboarding routes feed the same Workspace Intelligence model.
@@ -297,7 +404,7 @@ All onboarding routes feed the same Workspace Intelligence model.
 | 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 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`                                                                                    |
 
@@ -337,23 +444,27 @@ Python is not required for Python-free workspace profiles, npm-owned backend
 generators, frontend generators, or workspaces created with
 `--skip-python-engine`.
 
+RapidKit Core is the optional Python engine used only by Python/Core-dependent
+workflows; it is not a replacement CLI.
+
 ## Documentation
 
-| Documentation                                                                | Purpose                                                       |
-| ---------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| [Documentation index](docs/README.md)                                        | All user, operator, contract, and contributor docs            |
-| [Command reference](docs/commands-reference.md)                              | Complete command syntax and flags                             |
-| [Creating workspaces and projects](docs/creating-workspaces-and-projects.md) | Interactive, automated, location, and linking behavior        |
-| [Workspace operations](docs/workspace-operations.md)                         | Adopt, import, snapshots, archives, contracts, and infra      |
-| [Workspace run](docs/workspace-run.md)                                       | Polyglot and affected-project execution                       |
-| [Workspace Knowledge Graph](docs/workspace-knowledge-graph.md)               | Proof-backed queries, AI/MCP retrieval, and graph outputs     |
-| [Graph benchmark methodology](docs/graph-benchmark-methodology.md)           | Reproducible payload-reduction measurements and claim limits  |
-| [Glossary](docs/GLOSSARY.md)                                                 | Plain-language meanings for model, graph, evidence, and gates |
-| [Doctor command](docs/doctor-command.md)                                     | Health checks, evidence, fixes, and exit codes                |
-| [CI workflows](docs/ci-workflows.md)                                         | CI examples and repository validation                         |
-| [Configuration](docs/config-file-guide.md)                                   | User configuration and precedence                             |
-| [Open-source scenarios](docs/OPEN_SOURCE_USER_SCENARIOS.md)                  | Role-oriented examples                                        |
-| [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md)                       | Canonical files, writers, schemas, and readers                |
+| Documentation                                                                  | Purpose                                                       |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| [Documentation index](docs/README.md)                                          | All user, operator, contract, and contributor docs            |
+| [Command reference](docs/commands-reference.md)                                | Complete command syntax and flags                             |
+| [Creating workspaces and projects](docs/creating-workspaces-and-projects.md)   | Interactive, automated, location, and linking behavior        |
+| [Workspace operations](docs/workspace-operations.md)                           | Adopt, import, snapshots, archives, contracts, and infra      |
+| [Workspace run](docs/workspace-run.md)                                         | Polyglot and affected-project execution                       |
+| [Workspace Knowledge Graph](docs/workspace-knowledge-graph.md)                 | Proof-backed queries, AI/MCP retrieval, and graph outputs     |
+| [Graph benchmark methodology](docs/graph-benchmark-methodology.md)             | Reproducible payload-reduction measurements and claim limits  |
+| [Workspace Intelligence Evaluation](docs/workspace-intelligence-evaluation.md) | Live token, cost, activity, and verified-outcome measurements |
+| [Glossary](docs/GLOSSARY.md)                                                   | Plain-language meanings for model, graph, evidence, and gates |
+| [Doctor command](docs/doctor-command.md)                                       | Health checks, evidence, fixes, and exit codes                |
+| [CI workflows](docs/ci-workflows.md)                                           | CI examples and repository validation                         |
+| [Configuration](docs/config-file-guide.md)                                     | User configuration and precedence                             |
+| [Open-source scenarios](docs/OPEN_SOURCE_USER_SCENARIOS.md)                    | Role-oriented examples                                        |
+| [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md)                         | Canonical files, writers, schemas, and readers                |
 
 Repository workflows include
 [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml),
@@ -376,7 +487,7 @@ contributor-automation map.
 | Python/Core workflow cannot start  | `python3 --version`                            | Install Python 3.10+ or use a Python-free profile where supported        |
 | Workspace is not detected          | Look for `.workspai-workspace`                 | Run from the workspace or pass `--workspace <path>`                      |
 | Strict policy blocks a command     | `.workspai/policies.yml`                       | Inspect `workspace policy show` before changing policy                   |
-| Reports are stale                  | Report timestamps                              | Re-run `pipeline` or the required chain stages                           |
+| Reports are stale                  | Report timestamps                              | Re-run `workspace intelligence run` or the documented producing command  |
 | AI tools ignore workspace evidence | `AGENTS.md` and `.workspai/reports/INDEX.json` | Run `workspace agent-sync --write --refresh-context`                     |
 | Project generator fails            | Runtime and network output                     | Fix the reported prerequisite, then retry or create officially and adopt |
 
@@ -388,7 +499,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:
 
@@ -404,12 +515,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/agent-customization-pack.v1.json

@@ -115,6 +115,11 @@
       "label": "Workspace knowledge graph",
       "required": false
     },
+    {
+      "path": ".workspai/reports/workspace-intelligence-evaluation-last-run.json",
+      "label": "Workspace Intelligence evaluation",
+      "required": false
+    },
     {
       "path": ".workspai/reports/doctor-last-run.json",
       "label": "Workspace doctor",

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

@@ -1216,6 +1216,10 @@
           "flags": "--once",
           "attributeName": "once"
         },
+        {
+          "flags": "--graph-stream",
+          "attributeName": "graphStream"
+        },
         {
           "flags": "--for-agent [agent]",
           "attributeName": "forAgent"

package/contracts/extension-cli-compatibility.v1.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "rapidkit-extension-cli-compatibility.v1",
   "cli": "workspai",
-  "minimumVerifiedCliVersion": "0.47.0",
+  "minimumVerifiedCliVersion": "0.49.0",
   "publishedContractSchemas": {
     "workspaceContract": 1,
     "runtimeCommandSurface": "rapidkit-runtime-command-surface-v1",
@@ -32,7 +32,9 @@
       "skillsIndex": "workspace-skills-index.v1",
       "agents": null,
       "explain": "workspace-explain.v1",
-      "intelligenceRun": "workspace-intelligence-run.v1"
+      "intelligenceRun": "workspace-intelligence-run.v1",
+      "evaluationLive": "workspace-intelligence-evaluation.v1",
+      "evaluationLastRun": "workspace-intelligence-evaluation.v1"
     },
     "cliLogEvent": "cli-log-event-v1",
     "freshnessMetadata": "rapidkit-freshness-metadata-v1",
@@ -44,9 +46,13 @@
     "workspaceContext": "workspace-context.v1",
     "workspaceDependencyGraph": "workspace-dependency-graph.v1",
     "workspaceKnowledgeGraph": "workspace-knowledge-graph.v1",
+    "workspaceGraphStream": "workspace-graph-stream.v1",
     "workspaceKnowledgeGraphChangeOverlay": "workspace-knowledge-graph-change-overlay.v1",
     "workspaceKnowledgeSearch": "workspace-knowledge-search.v1",
     "workspaceGraphTokenEfficiency": "workspace-graph-token-efficiency.v1",
+    "modelUsageEvent": "model-usage-event.v1",
+    "workspaceIntelligenceEvaluation": "workspace-intelligence-evaluation.v1",
+    "workspaceIntelligenceEvaluationComparison": "workspace-intelligence-evaluation-comparison.v1",
     "workspaceIntelligenceHistory": "workspace-intelligence-history.v1",
     "agentCustomizationPackCapabilities": "workspai-agent-customization-pack-capabilities.v1",
     "agentCustomizationPackReport": "rapidkit-agent-customization-pack.v1",