workspai 0.47.0 → 0.49.0

package/docs/README_CONTENT_CONTRACT.md

@@ -0,0 +1,154 @@
+# 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.
+
+## 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.
+- Missing relationships mean **not proven**, not independent.
+- The graph is broader than a code graph, but it is not the entire product.
+- The canonical runner is
+  `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.
+
+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`                    |
+
+Markdown summarizes 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.
+
+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.
+
+## 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:
+
+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.
+
+Prefer user questions and outcomes over internal phase names. Define unavoidable
+terms in plain language and link to the glossary.
+
+## Validation
+
+Run from `packages/cli`:
+
+```bash
+npm run validate:docs
+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.
+
+## 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.

package/docs/ci-workflows.md

@@ -12,9 +12,9 @@ Map of GitHub Actions workflows in this repository. Use this when editing CI to
 | 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                                    |
 | 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                          |
+| 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                                |
+| 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
@@ -29,7 +29,7 @@ For Workspai **consumer workspaces** (not this CLI repo), use the copy-paste tem
 Minimal job:
 
 ```yaml
-- run: npx workspai workspace intelligence run --for-agent codex --strict --json
+- run: npx workspai workspace intelligence run --for-agent generic --strict --json
 - run: npx workspai pipeline --json --strict --no-agent-sync
 - run: node ./node_modules/workspai/scripts/check-agent-customization-drift.mjs --workspace .
 ```

package/docs/commands-reference.md

@@ -18,7 +18,7 @@ npx workspai autopilot release [--mode <audit|safe-fix|enforce>] [--json] [--out
 Recommended CI:
 
 ```bash
-npx workspai workspace intelligence run --for-agent codex --strict --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
 Run the broader governance and release orchestrators as separate gates; they
@@ -65,8 +65,9 @@ npx workspai workspace snapshot [--workspace <path>] [--json] [--include-paths]
 npx workspai workspace diff --from <snapshot-or-report|git[:ref]> [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
 npx workspai workspace impact --from <workspace-diff-report> [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
 npx workspai workspace verify [--from-impact <file>] [--workspace <path>] [--scope project:<name>] [--strict] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
-npx workspai workspace graph [emit|explain|search|benchmark|entities|evidence|path|overlay|dot|mermaid] [key] [value] [--from <graph.json>] [--limit <1..100>] [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
-npx workspai workspace watch [--workspace <path>] [--json] [--once] [--scan-depth <count>]
+npx workspai workspace graph [emit|explain|search|benchmark|entities|evidence|path|overlay|dot|mermaid|jsonld|graphml|gexf] [key] [value] [--from <graph.json>] [--output <file>] [--limit <1..100>] [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
+npx workspai workspace eval [init <task> [strategy]|record|status|report|compare --from <report>] [--workspace <path>] [--output <file>] [--json]
+npx workspai workspace watch [--workspace <path>] [--json] [--graph-stream] [--once] [--scan-depth <count>]
 npx workspai workspace explain|why <target> [--workspace <path>] [--json] [--write]
 npx workspai workspace trace --from <workspace-diff-report> [--workspace <path>] [--json] [--write]
 printf '%s\n' '{"actionId":"fix-api","summary":"API tests passed","outcome":"ok"}' | npx workspai workspace feedback record [--workspace <path>] --json
@@ -144,6 +145,18 @@ 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.
 
+`workspace graph jsonld|graphml|gexf` exports the current derived,
+evidence-backed Knowledge Graph for semantic, graph-analysis, and interactive
+2D/3D consumers.
+Use `--output <file>` for a durable export; Mermaid and DOT remain the compact
+documentation-oriented renderings.
+
+`workspace eval` records provider/tokenizer/estimate provenance, tool activity,
+cost, latency, and verified task outcome. `eval record` accepts a
+`model-usage-event.v1` JSON document on stdin. The live and finalized artifacts
+are suitable for IDE dashboards and conform to
+`workspace-intelligence-evaluation.v1`.
+
 `workspace model --write` also materializes the derived, contract-validated
 knowledge graph at `.workspai/reports/workspace-knowledge-graph.json`. The
 unified intelligence runner treats that artifact as a required output of the

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -76,25 +76,27 @@ Bare artifact names in this table are relative to `.workspai/reports/`.
 Entries beginning with `reports/` are relative to `.workspai/`; paths such as
 `AGENTS.md` are relative to the workspace root.
 
-| Command                                        | Artifact                                                                                                                     | Schema                                 | Contract file                                                              |
-| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------- |
-| `workspace model --write`                      | `workspace-model.json`                                                                                                       | `workspace-model.v1`                   | `contracts/workspace-intelligence/workspace-model.v1.json`                 |
-| `workspace model --write`                      | `workspace-knowledge-graph.json`                                                                                             | `workspace-knowledge-graph.v1`         | `contracts/workspace-intelligence/workspace-knowledge-graph.v1.json`       |
-| `workspace snapshot`                           | `workspace-model-snapshot.json`                                                                                              | `workspace-model-snapshot.v1`          | `contracts/workspace-intelligence/workspace-model-snapshot.v1.json`        |
-| `workspace diff`                               | `workspace-model-diff-last-run.json`                                                                                         | `workspace-model-diff.v1`              | `contracts/workspace-intelligence/workspace-model-diff.v1.json`            |
-| `workspace impact --from <diff>`               | `workspace-impact-last-run.json`                                                                                             | `workspace-impact.v1`                  | `contracts/workspace-intelligence/workspace-impact.v1.json`                |
-| `analyze --json`                               | `analyze-last-run.json`                                                                                                      | `rapidkit-analyze-v1`                  | `contracts/analyze-last-run.v1.json`                                       |
-| `workspace verify`                             | `workspace-verify-last-run.json`                                                                                             | `workspace-verify.v1`                  | `contracts/workspace-intelligence/workspace-verify.v1.json`                |
-| `workspace context --write`                    | `workspace-context-agent.json`                                                                                               | `workspace-context.v1`                 | `contracts/workspace-intelligence/workspace-context.v1.json`               |
-| `workspace agent-sync --write`                 | `reports/agent-customization-pack.json`                                                                                      | `rapidkit-agent-customization-pack.v1` | `contracts/workspace-intelligence/agent-customization-pack-report.v1.json` |
-| `workspace agent-sync --write`                 | `reports/INDEX.json`                                                                                                         | `rapidkit-agent-reports-index.v1`      | `contracts/workspace-intelligence/agent-reports-index.v1.json`             |
-| `workspace agent-sync --write`                 | `reports/workspace-skills-index.json`                                                                                        | `workspace-skills-index.v1`            | `contracts/workspace-intelligence/workspace-skills-index.v1.json`          |
-| `workspace agent-sync --write`                 | `reports/workspai-mcp-design.json`, `.workspai/skills/*.md`, `.workspai/AGENT-GROUNDING.md`, `AGENTS.md`, IDE agent surfaces | Mixed generated surfaces               | See customization pack output inventory                                    |
-| `workspace explain --write`                    | `workspace-explain-last-run.json`                                                                                            | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`               |
-| `workspace why --write`                        | `workspace-why-last-run.json`                                                                                                | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`               |
-| `workspace trace --write`                      | `workspace-trace-last-run.json`                                                                                              | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`               |
-| `workspace intelligence run`                   | `workspace-intelligence-run-last-run.json`                                                                                   | `workspace-intelligence-run.v1`        | `contracts/workspace-intelligence/workspace-intelligence-run.v1.json`      |
-| `workspace feedback record` / `doctor * --fix` | `workspace-intelligence-history.json` (`kind: agent-action`, `doctor-fix`)                                                   | `workspace-intelligence-history.v1`    | `contracts/workspace-intelligence/workspace-intelligence-history.v1.json`  |
+| Command                                         | Artifact                                                                                                                     | Schema                                 | Contract file                                                                |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| `workspace model --write`                       | `workspace-model.json`                                                                                                       | `workspace-model.v1`                   | `contracts/workspace-intelligence/workspace-model.v1.json`                   |
+| `workspace model --write`                       | `workspace-knowledge-graph.json`                                                                                             | `workspace-knowledge-graph.v1`         | `contracts/workspace-intelligence/workspace-knowledge-graph.v1.json`         |
+| `workspace snapshot`                            | `workspace-model-snapshot.json`                                                                                              | `workspace-model-snapshot.v1`          | `contracts/workspace-intelligence/workspace-model-snapshot.v1.json`          |
+| `workspace diff`                                | `workspace-model-diff-last-run.json`                                                                                         | `workspace-model-diff.v1`              | `contracts/workspace-intelligence/workspace-model-diff.v1.json`              |
+| `workspace impact --from <diff>`                | `workspace-impact-last-run.json`                                                                                             | `workspace-impact.v1`                  | `contracts/workspace-intelligence/workspace-impact.v1.json`                  |
+| `analyze --json`                                | `analyze-last-run.json`                                                                                                      | `rapidkit-analyze-v1`                  | `contracts/analyze-last-run.v1.json`                                         |
+| `workspace verify`                              | `workspace-verify-last-run.json`                                                                                             | `workspace-verify.v1`                  | `contracts/workspace-intelligence/workspace-verify.v1.json`                  |
+| `workspace context --write`                     | `workspace-context-agent.json`                                                                                               | `workspace-context.v1`                 | `contracts/workspace-intelligence/workspace-context.v1.json`                 |
+| `workspace agent-sync --write`                  | `reports/agent-customization-pack.json`                                                                                      | `rapidkit-agent-customization-pack.v1` | `contracts/workspace-intelligence/agent-customization-pack-report.v1.json`   |
+| `workspace agent-sync --write`                  | `reports/INDEX.json`                                                                                                         | `rapidkit-agent-reports-index.v1`      | `contracts/workspace-intelligence/agent-reports-index.v1.json`               |
+| `workspace agent-sync --write`                  | `reports/workspace-skills-index.json`                                                                                        | `workspace-skills-index.v1`            | `contracts/workspace-intelligence/workspace-skills-index.v1.json`            |
+| `workspace agent-sync --write`                  | `reports/workspai-mcp-design.json`, `.workspai/skills/*.md`, `.workspai/AGENT-GROUNDING.md`, `AGENTS.md`, IDE agent surfaces | Mixed generated surfaces               | See customization pack output inventory                                      |
+| `workspace explain --write`                     | `workspace-explain-last-run.json`                                                                                            | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`                 |
+| `workspace why --write`                         | `workspace-why-last-run.json`                                                                                                | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`                 |
+| `workspace trace --write`                       | `workspace-trace-last-run.json`                                                                                              | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.v1.json`                 |
+| `workspace intelligence run`                    | `workspace-intelligence-run-last-run.json`                                                                                   | `workspace-intelligence-run.v1`        | `contracts/workspace-intelligence/workspace-intelligence-run.v1.json`        |
+| `workspace feedback record` / `doctor * --fix`  | `workspace-intelligence-history.json` (`kind: agent-action`, `doctor-fix`)                                                   | `workspace-intelligence-history.v1`    | `contracts/workspace-intelligence/workspace-intelligence-history.v1.json`    |
+| `workspace eval init` / `workspace eval record` | `workspace-intelligence-evaluation-live.json`                                                                                | `workspace-intelligence-evaluation.v1` | `contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json` |
+| `workspace eval report`                         | `workspace-intelligence-evaluation-last-run.json`                                                                            | `workspace-intelligence-evaluation.v1` | `contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json` |
 
 The unified runner report separates its execution envelope from the canonical
 intelligence chain. `preflight` always contains exactly `sync` and `baseline`;
@@ -111,6 +113,13 @@ recoverable artifact transaction. The graph carries a SHA-256 `source` binding
 to the canonical model, so consumers must reject a graph whose source hash does
 not equal the current structural model hash.
 
+`workspace graph jsonld|graphml|gexf --output <path>` creates explicit interchange
+projections from that bound graph. These files are portable exports, not competing
+canonical or `last-run` artifacts: JSON-LD preserves semantic identifiers,
+GraphML targets general graph tooling, and GEXF targets exploration and
+visualization tools. Mermaid and DOT remain bounded text projections for docs
+and diagrams.
+
 **CLI semantics:** `workspace diff --from` expects a **model or snapshot** baseline. `workspace impact --from` expects a **diff report**.
 Persisted artifacts retain their artifact schema. JSON command projections that add operation metadata
 such as `outputPath`, `status`, or structured errors use
@@ -182,6 +191,12 @@ on each settled change, driven by graph-aware incremental rebuilds. Events carry
 removed projects, graph edge deltas, structural `modelHash`, and `mode`/`durationMs`. Canonical
 source: `src/workspace-watch.ts`.
 
+Use `workspace watch --graph-stream --json` for the transport-neutral
+`workspace-graph-stream.v1` feed consumed by IDEs. The first line is an
+authoritative snapshot; subsequent lines are hash-linked, revisioned deltas.
+Consumers must request a new snapshot after any revision, identity, generation,
+schema, validation, or hash-continuity failure.
+
 **Health/impact history.** Each `workspace verify` run appends a compact record to
 `.workspai/reports/workspace-intelligence-history.json` (`workspace-intelligence-history.v1`),
 a ring buffer capped at the 50 most-recent entries (verdict, risk, freshness, gate, counts).
@@ -347,7 +362,7 @@ canonical file. Legacy files remain readable during the compatibility window.
 ## Consumer rules
 
 1. **Project count:** read `workspace-registry.v1.json` (or run `workspace registry status --json`).
-2. **Workspace Intelligence chain:** run `workspace intelligence run --for-agent codex --strict --json` to preserve Model → Diff → Impact → Doctor + Contract Verify + Analyze → Readiness → Verify → Context → Agent Sync → Explain. `pipeline` is the broader governance/release orchestrator and `autopilot` is a separate release surface; neither redefines the canonical chain. Use `pipeline-last-run.json` only for the pipeline orchestration summary.
+2. **Workspace Intelligence chain:** run `workspace intelligence run --for-agent generic --strict --json` to preserve Model → Diff → Impact → Doctor + Contract Verify + Analyze → Readiness → Verify → Context → Agent Sync → Explain. `pipeline` is the broader governance/release orchestrator and `autopilot` is a separate release surface; neither redefines the canonical chain. Use `pipeline-last-run.json` only for the pipeline orchestration summary.
 3. **Do not** use `workspace.json.projects` (removed in schema 1.0).
 4. Prefer `schemaVersion` constants in each artifact; legacy `v1` on readiness is accepted when reading old reports.
 5. **Agent retrieval:** start with `AGENTS.md` and `.workspai/reports/INDEX.json`, then use `workspace graph search <query> --limit <n> --json` or MCP `searchWorkspaceGraph` for question-sized facts. Follow returned proof paths to source evidence. Read the full context, model, or graph only when the bounded result is insufficient.

package/docs/contracts/README.md

@@ -81,6 +81,9 @@ Workspace intelligence (`../../contracts/workspace-intelligence/`):
 - `workspace-knowledge-graph-change-overlay.v1.json` — proposed/change-set facts and relations without mutating the base graph
 - `workspace-knowledge-search.v1.json` — bounded ranked retrieval for CLI, MCP, IDE, and agent consumers
 - `workspace-graph-token-efficiency.v1.json` — reproducible corpus-versus-retrieval payload measurement
+- `model-usage-event.v1.json` — privacy-bounded model, tool, milestone, and verified-outcome events with explicit measurement provenance
+- `workspace-intelligence-evaluation.v1.json` — live/final token, cost, latency, activity, and verified-outcome evaluation
+- `workspace-intelligence-evaluation-comparison.v1.json` — task-aligned comparison of two completed evaluation strategies
 - `workspace-model-snapshot.v1.json`
 - `workspace-model-diff.v1.json`
 - `workspace-impact.v1.json`

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

@@ -1,16 +1,20 @@
 # Creating Workspaces and Projects
 
-This guide explains, in plain language, what Workspai does when you create a
-workspace or a project. It covers interactive commands, automation, project
-locations, workspace linking, supported kits, and the most important flags.
+Use this guide when you want to start a new software system or add a new
+application to an existing one. Workspai creates the files, records where the
+project belongs, and makes it visible to the same checks and tools as the rest
+of the workspace.
+
+The sections below explain project locations, supported starters, interactive
+commands, automation, and the most useful options.
 
 For a compact list of command syntax, see
 [commands-reference.md](./commands-reference.md).
 
 ## The two things you can create
 
-A **workspace** is the governed boundary that holds project registrations,
-policies, contracts, and Workspace Intelligence reports.
+A **workspace** is the shared home for related projects, rules, and saved
+Workspai reports.
 
 A **project** is an application or service, such as a FastAPI API, Go service,
 Spring Boot service, .NET API, or frontend application.
@@ -588,13 +592,13 @@ native, official, and existing-project lanes.
 
 # Failure and cleanup behavior
 
-| Situation                                                | Result                                 |
-| -------------------------------------------------------- | -------------------------------------- |
-| Invalid name                                             | Stops before normal scaffold writes    |
-| Target directory already exists                          | Stops without merging or overwriting   |
-| Project scaffold fails                                   | Workspace linking does not run         |
-| Git initialization fails                                 | Usually warns and keeps the scaffold   |
-| Go or Maven dependency warm-up fails                     | Warns and keeps the scaffold           |
+| Situation                                                | Result                                                                      |
+| -------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Invalid name                                             | Stops before normal scaffold writes                                         |
+| Target directory already exists                          | Stops without merging or overwriting                                        |
+| Project scaffold fails                                   | Workspace linking does not run                                              |
+| Git initialization fails                                 | Usually warns and keeps the scaffold                                        |
+| Go or Maven dependency warm-up fails                     | Warns and keeps the scaffold                                                |
 | Workspace registration/finalization fails after scaffold | Lifecycle rollback restores metadata and removes a newly owned project tree |
 
 Create finalization uses a durable lifecycle transaction. On failure it restores

package/docs/doctor-command.md

@@ -1,6 +1,8 @@
 # Workspai Doctor Command
 
-`doctor` checks health for the npm wrapper environment in system, workspace, or project scope.
+Use `doctor` to find setup and dependency problems before they interrupt
+development or block a release. It can check the computer, an entire workspace,
+or one project, and reports what is wrong and which fixes are available.
 
 **Related:** [workspace-operations.md](./workspace-operations.md) · [commands-reference.md](./commands-reference.md) · [Documentation index](./README.md)
 
@@ -20,7 +22,7 @@ Checks host prerequisites:
 - RapidKit Core availability
 - Go (optional)
 
-### 2) Workspace Check (Canonical)
+### 2) Workspace Check
 
 ```bash
 cd my-workspace
@@ -87,11 +89,11 @@ npx workspai doctor workspace --profile enterprise-strict --json
 Doctor supports policy profiles so the same evidence can be interpreted correctly in local,
 CI, release, and enterprise gates:
 
-| Profile             | Use when                         | Warning behavior                         |
-| ------------------- | -------------------------------- | ---------------------------------------- |
-| `local`             | Developer diagnostics             | Report warnings, do not block            |
-| `ci`                | CI feedback loop                  | Exit `2` on warnings, `1` on errors      |
-| `release`           | Release readiness gate            | Exit `1` on warnings or errors           |
+| Profile             | Use when                          | Warning behavior                                          |
+| ------------------- | --------------------------------- | --------------------------------------------------------- |
+| `local`             | Developer diagnostics             | Report warnings, do not block                             |
+| `ci`                | CI feedback loop                  | Exit `2` on warnings, `1` on errors                       |
+| `release`           | Release readiness gate            | Exit `1` on warnings or errors                            |
 | `enterprise-strict` | Enterprise/studio repair workflow | Exit `1`; every warning needs evidence or repair guidance |
 
 `--strict` maps to the `release` profile and `--ci` maps to the `ci` profile for backward
@@ -101,11 +103,11 @@ card is advisory locally but blocking for release.
 Doctor also attaches a **freshness contract** to evidence so tools do not treat live state as
 durable structure:
 
-| Freshness category | Meaning                                      | Default TTL |
-| ------------------ | -------------------------------------------- | ----------- |
-| `structure`        | Durable project/workspace shape and markers  | 7 days      |
+| Freshness category | Meaning                                       | Default TTL |
+| ------------------ | --------------------------------------------- | ----------- |
+| `structure`        | Durable project/workspace shape and markers   | 7 days      |
 | `verification`     | Test, script, lint, quality, and probe checks | 24 hours    |
-| `state`            | Live dependency/security state               | 5 minutes   |
+| `state`            | Live dependency/security state                | 5 minutes   |
 
 Each probe can include `freshness`, and each JSON artifact includes `evidenceFreshness`.
 Workspai and CI should refresh stale or `verifyBeforeUse` evidence before claiming a project is
@@ -113,10 +115,10 @@ ready, repaired, or release-safe.
 
 Doctor probes also include an **issue taxonomy** and **repair intent** for Studio-driven repair:
 
-| Field               | Purpose                                                                 |
-| ------------------- | ----------------------------------------------------------------------- |
-| `issueClass`        | Stable category such as `security`, `test`, `container`, or `dependency` |
-| `operationalImpact` | Product impact such as `ci-risk`, `release-risk`, or `security-risk`    |
+| Field               | Purpose                                                                                                       |
+| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `issueClass`        | Stable category such as `security`, `test`, `container`, or `dependency`                                      |
+| `operationalImpact` | Product impact such as `ci-risk`, `release-risk`, or `security-risk`                                          |
 | `repairIntent.mode` | Studio action mode: `edit-file`, `run-command`, `review-required`, `verify-before-fix`, or `refresh-evidence` |
 
 This lets Workspai distinguish "show guidance" from "apply an approved file edit", "run a command",
@@ -164,15 +166,15 @@ same repair evidence without guessing the workspace root.
 
 The remediation plan is intentionally ordered for Studio execution:
 
-| Phase | Purpose |
-| --- | --- |
-| `dependency-baseline` | Restore package/runtime dependency baselines before other fixes |
-| `local-environment` | Seed local env files without overwriting operator-owned values |
-| `source-hygiene` | Apply safe project-scoped hygiene files such as `.dockerignore` or `.gitignore` rules |
-| `command-contract` | Add missing test, quality, audit, or runtime command contracts |
-| `runtime-governance` | Run RapidKit/workspace initializers that may touch multiple project surfaces |
-| `manual-review` | Surface guidance that requires a human decision |
-| `generic-execution` | Last-resort shell remediation when no typed operation exists |
+| Phase                 | Purpose                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------- |
+| `dependency-baseline` | Restore package/runtime dependency baselines before other fixes                       |
+| `local-environment`   | Seed local env files without overwriting operator-owned values                        |
+| `source-hygiene`      | Apply safe project-scoped hygiene files such as `.dockerignore` or `.gitignore` rules |
+| `command-contract`    | Add missing test, quality, audit, or runtime command contracts                        |
+| `runtime-governance`  | Run RapidKit/workspace initializers that may touch multiple project surfaces          |
+| `manual-review`       | Surface guidance that requires a human decision                                       |
+| `generic-execution`   | Last-resort shell remediation when no typed operation exists                          |
 
 `dependsOn` lets Workspai avoid false loops: for example, a missing test script repair can depend on
 the project dependency baseline step, so Studio can run or ask for approval in the same order Doctor
@@ -311,11 +313,11 @@ jobs:
 
 ## Exit Codes
 
-| Code | Meaning                        |
-| ---- | ------------------------------ |
-| `0`  | Passed; local-profile warnings remain advisory |
+| Code | Meaning                                                            |
+| ---- | ------------------------------------------------------------------ |
+| `0`  | Passed; local-profile warnings remain advisory                     |
 | `1`  | Errors, or warnings under `release`/`enterprise-strict`/`--strict` |
-| `2`  | Warning-only result under the `ci` profile or `--ci` |
+| `2`  | Warning-only result under the `ci` profile or `--ci`               |
 
 ## Enterprise Probe Extensions
 

package/docs/examples/ci-agent-grounding.yml

@@ -39,7 +39,7 @@ jobs:
         # Exit 1 = hard execution failure; exit 2 = completed but evidence-blocked.
         # Continue here only so the durable run report and blocker evidence can
         # always be uploaded; the final step below still fails either outcome.
-        run: npx workspai workspace intelligence run --for-agent codex --strict --json
+        run: npx workspai workspace intelligence run --for-agent generic --strict --json
         continue-on-error: true
         id: intelligence
 

package/docs/from-code-to-shared-understanding.md

@@ -62,14 +62,14 @@ render Mermaid. When this source changes, regenerate
 Run the complete canonical chain in its versioned order:
 
 ```bash
-npx workspai workspace intelligence run --for-agent codex --json
+npx workspai workspace intelligence run --for-agent generic --json
 ```
 
 For enterprise CI and release enforcement, add `--strict`. A warning or
 needs-attention verdict then produces a blocked report and exit code `2`:
 
 ```bash
-npx workspai workspace intelligence run --for-agent codex --strict --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
 ```
 
 `pipeline` is the broader governance/release orchestrator. It does not replace

package/docs/graph-benchmark-methodology.md

@@ -52,8 +52,8 @@ language, model, or tokenizer.
 
 ## Current fixture observation
 
-The 16-project development workspace produced the following result on
-2026-07-21 for `api endpoint --limit 8`:
+The 16-project development workspace reproduced the following result on
+2026-07-22 for `api endpoint --limit 8`:
 
 | Measure                         | Observed value |
 | ------------------------------- | -------------: |