workspai 0.50.0 → 0.52.0

package/docs/README_CONTENT_CONTRACT.md

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

package/docs/ci-workflows.md

@@ -4,21 +4,59 @@ Map of GitHub Actions workflows in this repository. Use this when editing CI to
 
 ## Workflows
 
-| Workflow                 | Path                                             | Purpose                                                                   |
-| ------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------- |
-| Build / test matrix      | `.github/workflows/ci.yml`                       | Build, lint, typecheck, tests, coverage, contract gates                   |
-| Workspace E2E matrix     | `.github/workflows/workspace-e2e-matrix.yml`     | Cross-OS workspace lifecycle smoke; setup `--warm-deps`; cache/mirror ops |
-| Windows bridge E2E       | `.github/workflows/windows-bridge-e2e.yml`       | Native Windows bridge and lifecycle checks                                |
-| E2E smoke                | `.github/workflows/e2e-smoke.yml`                | Focused bridge regression smoke                                           |
-| Frontend generator smoke | `.github/workflows/frontend-generator-smoke.yml` | Official frontend generator drift gate                                    |
-| Security                 | `.github/workflows/security.yml`                 | Security scanning and policy checks                                       |
-| Manual npm release       | `.github/workflows/release-npm-manual.yml`       | Maintainer-only release gate and publish workflow                         |
-| Contributor onboarding   | `.github/workflows/contributor-onboarding.yml`   | Accepted-contributor onboarding automation                                |
-| Welcome                  | `.github/workflows/welcome.yml`                  | First-issue and first-contribution messages                               |
-
-The release workflow requires `Frontend Generator Smoke` for the exact release
-SHA. Maintainers must dispatch that workflow against the intended release ref
-before starting a manual npm release if no matching run exists.
+| Workflow                 | Path                                                 | Purpose                                                                   |
+| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------- |
+| Build / test matrix      | `.github/workflows/ci.yml`                           | Build, lint, typecheck, tests, coverage, contract gates                   |
+| Workspace E2E matrix     | `.github/workflows/workspace-e2e-matrix.yml`         | Cross-OS workspace lifecycle smoke; setup `--warm-deps`; cache/mirror ops |
+| Windows bridge E2E       | `.github/workflows/windows-bridge-e2e.yml`           | Native Windows bridge and lifecycle checks                                |
+| E2E smoke                | `.github/workflows/e2e-smoke.yml`                    | Focused bridge regression smoke                                           |
+| Official generator smoke | `.github/workflows/frontend-generator-smoke.yml`     | Contract-driven official-generator drift gate                             |
+| Security                 | `.github/workflows/security.yml`                     | Security scanning and policy checks                                       |
+| Manual npm release       | `.github/workflows/release-npm-manual.yml`           | Maintainer-only release gate and publish workflow                         |
+| Discord announcement     | `.github/workflows/discord-release-announcement.yml` | Preview and publish one idempotent product-aware release announcement     |
+| Contributor onboarding   | `.github/workflows/contributor-onboarding.yml`       | Accepted-contributor onboarding automation                                |
+| Welcome                  | `.github/workflows/welcome.yml`                      | First-issue and first-contribution messages                               |
+
+The release workflow requires the cost-bounded
+`Official Generator Smoke · primary` Linux run for the exact release SHA. A
+normal push that touches the contracted generator surface produces this gate;
+maintainers do not need to run the full cross-platform matrix before publishing.
+
+Pushes and pull requests run every contracted generator on the primary Linux
+lane. The weekly schedule and manual dispatch can run the complete Linux,
+macOS, and Windows matrix as a non-blocking compatibility and upstream-drift
+signal. npm and Composer download caches reduce repeated network work without
+caching generated projects; every smoke run still exercises the current
+upstream generator, generated artifacts, build surface, registry, and Doctor
+evidence.
+
+## Release announcements
+
+`packages/cli/releases/release-products.v1.json` maps a release product to its
+display name, package version, tag template, notes path, repository, and upgrade
+command. Release-event runs resolve the product from its tag, so future
+independently versioned monorepo packages do not require a new workflow.
+Each versioned release-note file carries one hidden
+`workspai-release-announcement` JSON block with its public headline, summary,
+and two to five highlights.
+
+Validate or preview the current CLI announcement locally:
+
+```bash
+npm --workspace workspai run check:release-announcement
+npm --workspace workspai run release:announcement -- \
+  --product workspai-cli \
+  --tag v0.51.0 \
+  --markdown-output /tmp/workspai-discord-announcement.md
+```
+
+Publishing a GitHub Release sends the generated embed to Discord. Configure the
+repository Actions secret `ANNOUNCEMENTS_WEBHOOK_URL` with the incoming
+webhook for `#announcements`. Manual workflow dispatch defaults to preview-only.
+When send is explicitly enabled, an existing message for the same product and
+tag is updated rather than duplicated. The workflow stores the Discord message
+id in a hidden marker on the GitHub Release. Release events read automation
+from the released tag; manual previews use the selected branch commit.
 
 ## Consumer workspace: agent grounding CI
 

package/docs/commands-reference.md

@@ -5,7 +5,7 @@ Complete CLI syntax for the Workspai CLI. For behavior and workflows, see [works
 ## Workspace lifecycle
 
 ```bash
-npx workspai create # Prompts: workspace | project
+npx workspai create # Guided create or existing-software ingestion
 npx workspai create workspace <name> [--profile <profile>] [--yes] [--here|--output <parent-dir>] [--skip-python-engine] [--skip-git] [--dry-run] [--install-method <poetry|venv|pipx>]
 npx workspai bootstrap [--profile <profile>] [--ci] [--json] [--compliance-only]
 npx workspai setup <python|node|go|java|dotnet|rust|php> [--warm-deps]
@@ -58,6 +58,9 @@ npx workspai workspace contract inspect [--json]
 npx workspai workspace contract verify [--strict] [--json]
 npx workspai workspace contract graph [--json]
 npx workspai workspace intelligence run [--workspace <path>] [--for-agent <agent>] [--strict] [--json]
+npx workspai workspace goal plan <release-readiness|dependency-security|test-coverage> [--scope project:<name>] [--target <0-100>] [--allow-breaking] [--allow-force] [--no-build] [--no-tests] [--json]
+npx workspai workspace goal status <goal-id> [--json]
+npx workspai workspace goal verify <goal-id> [--no-run] [--reuse-intelligence] [--json]
 npx workspai workspace model [--workspace <path>] [--json] [--write] [--strict] [--cache] [--incremental] [--include-paths] [--include-evidence] [--scan-depth <count>]
 npx workspai workspace context --for-agent [codex|claude|cursor|orca] [--workspace <path>] [--json] [--write] [--agent-sync|--no-agent-sync] [--target <targets>] [--preset minimal|enterprise] [--include-evidence] [--scan-depth <count>]
 npx workspai workspace agent-sync [--workspace <path>] [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|agents,copilot,cursor,claude,codex,orca] [--project-grounding managed|local|off] [--experimental-hooks] [--hydrate-prompts]
@@ -132,6 +135,15 @@ execution failures. See
 baseline creation/reuse, JSON fields, artifact invariants, skip propagation, and
 CI handling.
 
+`workspace goal` turns a user outcome into a durable success contract. Plan a
+release-readiness, dependency-security, or test-coverage goal once; Studio or
+another agent can then work toward it and ask the CLI to verify current
+evidence. Goal definitions live under `.workspai/goals/`, while the latest
+portable verdict is written to
+`.workspai/reports/verified-goal-last-run.json`. See
+[Verified engineering goals](./workspace-intelligence-runner.md#verified-engineering-goals)
+for the supported scopes, safety constraints, and verification boundary.
+
 `workspace feedback record` is a non-interactive machine interface. It requires
 exactly one JSON object on stdin and `--json`; an empty stdin or interactive TTY
 is rejected. Required fields are `actionId`, `summary`, and `outcome`. The
@@ -161,7 +173,9 @@ they never write facts back into the authorizing model during the same run.
 
 `workspace graph search <query> --limit <n> --json` returns bounded entities,
 one-hop relations, related entity summaries, and portable proofs instead of the
-complete graph. `workspace graph benchmark <query> --limit <n> --json` compares
+complete graph. Ranking is deterministic and offline: it removes natural-language
+stopwords, weights rarer graph terms more strongly, and prefers exact labels and
+identities. `workspace graph benchmark <query> --limit <n> --json` compares
 that retrieval payload with the readable proof-indexed corpus using a labelled
 `characters / 4` estimate. It measures payload reduction only; it does not
 assert equivalent answer quality or model-specific billing savings.

package/docs/doctor-command.md

@@ -293,6 +293,22 @@ Workspai should use this contract to offer two clear actions for a blocked card:
 After either path, Studio should run the step `verifyCommand` when present, then refresh the card
 with `refreshCommands` before claiming the issue is resolved.
 
+Dependency repairs have an additional closure contract. Editing a manifest is
+only the start of the transaction; the consumer must complete these stages in
+order:
+
+```text
+reconcile manifest and lockfile -> audit -> declared tests -> declared build
+-> canonical Workspace Intelligence verification
+```
+
+Doctor exposes this requirement as
+`workspai.doctor-dependency-repair-transaction.v1`. Studio and other consumers
+must not mark a dependency card fixed while the installed tree or lockfile is
+stale, the focused audit is still blocked, or declared build/test validation
+has not completed. The portable schema is
+[`doctor-dependency-repair-transaction.v1.json`](../contracts/workspace-intelligence/doctor-dependency-repair-transaction.v1.json).
+
 In `enterprise-strict`, guarded and invasive fixes are exposed as `review-required` even when they
 are executable. That keeps Studio honest: it can preview and propose the change, but the operator
 must approve before Doctor mutates project files or runs a dependency command.

package/docs/workspace-intelligence-runner.md

@@ -184,6 +184,54 @@ Automation must distinguish:
 Do not parse terminal prose. Read `status`, `exitCode`, `preflight`, `stages`,
 and their registered artifacts from the JSON report.
 
+## Verified engineering goals
+
+The intelligence runner answers what is true now. A verified goal adds the
+durable definition of what must become true, so a person or agent can resume
+work without changing the success criteria between attempts.
+
+```bash
+# Prepare the whole workspace for release.
+npx workspai workspace goal plan release-readiness --json
+
+# Remove blocking dependency vulnerabilities from one registered project.
+npx workspai workspace goal plan dependency-security --scope project:api --json
+
+# Raise one project's measured coverage to at least 75%.
+npx workspai workspace goal plan test-coverage --scope project:web --target 75 --json
+
+# Re-measure the goal against current source and evidence.
+npx workspai workspace goal verify <goal-id> --json
+```
+
+Planning writes an immutable goal definition and its current status under
+`.workspai/goals/<goal-id>/`. Verification also refreshes the canonical latest
+verdict at `.workspai/reports/verified-goal-last-run.json`. Consumers must read
+the JSON verdict; they must not infer success from an agent message or a source
+edit alone.
+
+The three shipped goal kinds have explicit completion rules:
+
+| Goal kind             | Completion boundary                                                            |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `release-readiness`   | Readiness passes and Workspace Verify reports ready.                            |
+| `dependency-security` | A fresh audit reports zero blocking vulnerabilities and required checks pass.  |
+| `test-coverage`       | Runtime-owned coverage reaches the selected percentage and required checks pass. |
+
+Goals are workspace-scoped by default. Use `--scope project:<registered-name>`
+when the requested outcome belongs to one project. Dependency goals preserve a
+hash baseline for recognized manifests and lockfiles across supported
+ecosystems. Breaking or force-based changes remain forbidden unless the goal
+explicitly records `--allow-breaking` or `--allow-force`; changing a manifest
+alone never satisfies the goal.
+
+`--no-run` only reads current goal evidence. `--reuse-intelligence` may reuse a
+just-completed canonical run, but it does not waive goal-specific measurement.
+The goal schemas are
+[`verified-goal.v1.json`](../contracts/workspace-intelligence/verified-goal.v1.json)
+and
+[`verified-goal-status.v1.json`](../contracts/workspace-intelligence/verified-goal-status.v1.json).
+
 ## Relationship to other commands
 
 `workspace intelligence run` is the canonical Workspace Intelligence chain.

package/docs/workspace-knowledge-graph.md

@@ -91,6 +91,12 @@ The response is intentionally bounded. `totalMatches` tells the consumer more
 results exist, `truncated` prevents silent omission, and every returned claim can
 be traced through `proofIds`.
 
+Search remains deterministic, local, and offline. Natural-language filler words
+are removed before ranking, and the remaining terms are weighted by how rare
+they are in the current graph. Exact labels and identities still win. This keeps
+a common word such as `check` from outranking a rarer term such as `user` merely
+because it appears in more files. No embedding service or model call is involved.
+
 ## Pick the command by question
 
 | You want to know…                                    | Use                                                     |
@@ -123,6 +129,31 @@ provider, source artifact, optional pointer/line, content hash, freshness,
 derivation, trust, and confidence. Secret values and machine-local absolute
 paths are excluded from the portable graph contract.
 
+## Read graph quality correctly
+
+Provider execution and graph completeness are separate signals:
+
+| Provider status | Meaning                                                                     |
+| --------------- | --------------------------------------------------------------------------- |
+| `passed`        | A matching source surface was found and graph evidence was produced.        |
+| `partial`       | The provider found applicable input but produced incomplete or no evidence. |
+| `skipped`       | No applicable source surface was present in this workspace.                 |
+| `failed`        | The provider could not complete its bounded scan.                           |
+
+`quality.providerSuccessRatio` is an execution-health ratio, not a completeness
+claim. A skipped provider is healthy but not applicable. Applicable providers
+that emit no evidence become `partial` and add an explicit unknown diagnostic,
+which contributes to `quality.unknownCount`. Bounded-scan limits and unresolved
+source relationships also contribute unknowns instead of being presented as
+complete coverage. Binding coverage remains the dimension-specific source for
+API implementation, tests, deployment, and ownership gaps; its unknowns are
+included in the aggregate count.
+
+Profiles govern workspace policy and verification expectations; they do not hide
+source providers. Running the same unchanged workspace with `minimal` and
+`polyglot` can therefore produce identical graph content. Changing a profile
+does update the canonical workspace manifest and contract identity.
+
 ## Model first, graph second
 
 The canonical direction is one-way:
@@ -178,6 +209,14 @@ model and reported as `project.path.missing`; it is never silently removed from
 the graph boundary. A persisted Knowledge Graph is accepted only when its
 workspace identity and project topology also match that model.
 
+An adopted monorepo remains one canonical project unless its internal projects
+are separately registered, discovered inside the workspace boundary, or
+declared by contract. The model still records bounded nested runtime manifests
+in `project.runtimeCandidates` and aggregates them into
+`workspace.identity.runtimeFamilies`. Graph providers can then discover the
+monorepo's internal services, contracts, delivery surfaces, and proofs without
+pretending that the primary runtime describes the whole repository.
+
 The two artifacts are published under one workspace lock using a
 rollback-capable artifact transaction. Each file replacement is atomic; if any
 write fails, Workspai restores both preimages. `graph.source.kind` is fixed to

package/docs/workspace-operations.md

@@ -81,12 +81,15 @@ versioned archive operation result instead.
 ### Automatic consumer sync
 
 Workspace creation publishes the initial contract, canonical model, Knowledge
-Graph, structural baseline, context, report index, `AGENTS.md`, operational
-skills, and supported IDE/agent surfaces—even before the first project exists.
-Successful project creation, adoption, import, workspace connection, and
-workspace import refresh those same projections in the background. The
-structural baseline is created once and preserved; current model, graph, diff,
-impact, context, and project grounding move forward with workspace membership.
+Graph, structural baseline, context, report index, profile-aware `README.md`,
+`AGENTS.md`, operational skills, and supported IDE/agent surfaces—even before
+the first project exists. The README's Workspai-managed section shows the
+current profile, project count, canonical intelligence loop, and consumer entry
+points while preserving user-authored content. Successful project creation,
+adoption, import, workspace connection, and workspace import refresh those same
+projections in the background. The structural baseline is created once and
+preserved; current model, graph, diff, impact, context, README, and project
+grounding move forward with workspace membership.
 
 Doctor, Analyze, Readiness, and Verify remain explicit checks because they may
 run project tools or enforce release policy. Use `workspace intelligence run`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workspai",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "type": "module",
   "description": "Open-source workspace intelligence CLI for software systems: create, adopt, govern, verify, and align polyglot workspaces for humans, CI, IDEs, and AI agents.",
   "keywords": [
@@ -122,19 +122,24 @@
     "metrics": "tsx scripts/metrics.ts",
     "validate:docs-examples": "node scripts/validate-doc-examples.mjs",
     "check:github-release-notes": "node scripts/github-release-notes.mjs --check",
+    "check:release-announcement": "node scripts/discord-release-announcement.mjs --check",
+    "release:announcement": "node scripts/discord-release-announcement.mjs",
     "check:markdown-links": "node scripts/check-markdown-links.mjs",
     "check:docs-drift": "node scripts/docs-drift-guard.mjs",
     "smoke:readme": "node scripts/smoke-readme-commands.mjs",
-    "validate:docs": "corepack npm run check:markdown-links && corepack npm run check:docs-drift && corepack npm run validate:docs-examples && corepack npm run check:github-release-notes && corepack npm run smoke:readme",
+    "validate:docs": "corepack npm run check:markdown-links && corepack npm run check:docs-drift && corepack npm run validate:docs-examples && corepack npm run check:github-release-notes && corepack npm run check:release-announcement && corepack npm run smoke:readme",
     "smoke:frontend-generators": "tsup && node scripts/smoke-frontend-generators.mjs",
     "smoke:frontend-generators:network": "tsup && node scripts/smoke-frontend-generators.mjs --execute",
+    "smoke:official-generators": "tsup && node scripts/smoke-official-generators.mjs",
+    "smoke:official-generators:network": "tsup && node scripts/smoke-official-generators.mjs --execute",
+    "check:generator-smoke-coverage": "node scripts/check-generator-smoke-coverage.mjs",
     "sync:contracts": "node scripts/sync-contracts.mjs",
     "check:contracts": "node scripts/sync-contracts.mjs --check",
     "bundle-size": "corepack npm run build && node scripts/report-dist-size.mjs",
     "analyze": "corepack npm run build && node scripts/analyze-dist.mjs",
     "size-check": "corepack npm run build && size-limit",
     "bench": "npx tsx scripts/benchmarks.ts",
-    "quality": "corepack npm run check:package-manager && corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm test && corepack npm run size-check && corepack npm run check:workspace-intelligence-runtime && corepack npm run check:workspace-intelligence-adversarial && corepack npm run security && corepack npm run validate:docs && corepack npm run smoke:frontend-generators && corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:parity-snapshot && corepack npm run check:agent-customization-drift",
+    "quality": "corepack npm run check:package-manager && corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm test && corepack npm run size-check && corepack npm run check:workspace-intelligence-runtime && corepack npm run check:workspace-intelligence-adversarial && corepack npm run security && corepack npm run validate:docs && corepack npm run check:generator-smoke-coverage && corepack npm run smoke:official-generators && corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:parity-snapshot && corepack npm run check:agent-customization-drift",
     "act-matrix": "act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-22.04 -P macos-latest=ghcr.io/catthehacker/ubuntu:act-22.04 -P windows-latest=ghcr.io/catthehacker/ubuntu:act-22.04 --pull=false -j build-test-matrix",
     "release:dry": "bash scripts/release.sh --no-publish --yes --allow-dirty",
     "release:patch": "bash scripts/release.sh patch",
@@ -146,7 +151,7 @@
     "contracts:check": "corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:parity-snapshot && corepack npm run check:generated-contracts && corepack npm run check:agent-customization-drift",
     "contracts:validate": "corepack npm run contracts:check && corepack npm run validate:contracts && corepack npm run build && corepack npm run check:workspace-intelligence-runtime && corepack npm run check:workspace-intelligence-adversarial",
     "docs:validate": "corepack npm run validate:docs",
-    "smoke": "corepack npm run smoke:enterprise-package && corepack npm run smoke:readme && corepack npm run smoke:frontend-generators",
+    "smoke": "corepack npm run smoke:enterprise-package && corepack npm run smoke:readme && corepack npm run check:generator-smoke-coverage && corepack npm run smoke:official-generators",
     "fix": "corepack npm run lint:fix && corepack npm run format && corepack npm run sync:contracts && corepack npm run sync:shared-contracts && corepack npm run sync-kits"
   },
   "dependencies": {

package/scripts/enterprise-package-smoke.mjs

@@ -376,6 +376,17 @@ function smokeCreateNpmBackedKits() {
         'rapidkit',
       ],
     },
+    {
+      kit: 'rust.axum',
+      name: 'enterprise-rust-axum',
+      extraArgs: [],
+      expectedFiles: [
+        'Cargo.toml',
+        'src/main.rs',
+        '.workspai/project.json',
+        'rapidkit',
+      ],
+    },
   ];
 
   try {