workspai 0.43.0

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -0,0 +1,333 @@
+# Workspai CLI Artifact Catalog
+
+Canonical map of **on-disk artifacts** produced by Workspai CLI commands. Dashboards, VS Code extension, and CI should read paths listed here — not infer from legacy fields (e.g. `workspace.json.projects`).
+
+## Authority layers (identity)
+
+| Artifact           | Path                                   | Writer                                                         | Reader purpose                                             |
+| ------------------ | -------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------- |
+| Workspace manifest | `.workspai/workspace.json`             | `create workspace`, `foundation ensure`, `bootstrap` (profile) | Profile, engine, bootstrap metadata — **not** project list |
+| Workspace contract | `.workspai/workspace.contract.json`    | `workspace sync`, `workspace contract *`, import/adopt         | Operational project registry (ports, contracts)            |
+| Registry summary   | `.workspai/workspace-registry.v1.json` | `workspace sync`, contract sync, `registry status --refresh`   | **Canonical** project count + authority for UI/CI          |
+| Workspace marker   | `.workspai-workspace`                  | `create workspace`, `foundation ensure`                        | Root detection                                             |
+
+Legacy `.rapidkit-workspace` and `.rapidkit/*` paths are read as fallback for
+older workspaces. New Workspai CLI writes target `.workspai-workspace` and
+`.workspai/*`. Workspace archive hydrate also normalizes legacy archive entries
+to canonical Workspai paths on restore.
+
+## Naming conventions
+
+| Pattern           | Meaning                                | Examples                                                     |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------ |
+| `*-last-run.json` | Latest gate/run evidence               | `doctor-last-run.json`, `pipeline-last-run.json`             |
+| `*.latest.json`   | Rolling alias + timestamped siblings   | `bootstrap-compliance.latest.json`, `mirror-ops.latest.json` |
+| Static state      | Current model/state (not a single run) | `workspace-model.json`, `workspace.contract.json`            |
+
+## Governance evidence loop
+
+| Command                  | Primary artifact                                          | Schema version                  | JSON Schema                                                  |
+| ------------------------ | --------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ |
+| `doctor workspace`       | `.workspai/reports/doctor-last-run.json`                  | `doctor-workspace-evidence-v1`  | `contracts/doctor-workspace-evidence.v1.json`                |
+| `doctor project`         | `.workspai/reports/doctor-project-last-run.json`          | `doctor-project-evidence-v1`    | `contracts/doctor-project-evidence.v1.json`                  |
+| `doctor * --plan`        | `.workspai/reports/doctor-remediation-plan-last-run.json` | `doctor-remediation-plan-v2`    | `contracts/doctor-remediation-plan.v1.json`                  |
+| `doctor * --fix/--apply` | `.workspai/reports/doctor-fix-result-last-run.json`       | `rapidkit-doctor-fix-result-v1` | `contracts/workspace-intelligence/doctor-fix-result.v1.json` |
+| `workspace remediation-plan --write` | `.workspai/reports/artifact-remediation-plan-last-run.json` | `artifact-remediation-plan-v1` | `contracts/artifact-remediation-plan.v1.json` |
+| `analyze`                | `.workspai/reports/analyze-last-run.json`                 | `rapidkit-analyze-v1`           | `contracts/analyze-last-run.v1.json`                         |
+| `readiness`              | `.workspai/reports/release-readiness-last-run.json`       | `release-readiness-v1`          | `contracts/release-readiness.v1.json`                        |
+| `pipeline`               | `.workspai/reports/pipeline-last-run.json`                | `rapidkit-pipeline-v1`          | `contracts/pipeline-last-run.v1.json`                        |
+| `autopilot release`      | `.workspai/reports/autopilot-release-last-run.json`       | `autopilot-release-v1`          | —                                                            |
+|                          | `.workspai/reports/autopilot-release.json`                | (alias, same payload)           | —                                                            |
+
+Side/cache (not gates): `.workspai/reports/doctor-workspace-cache.json` (`doctor-workspace-cache-v2`).
+
+Doctor Studio handoff:
+`doctor-remediation-plan-v2` (`contracts/doctor-remediation-plan.v1.json`) is emitted in JSON
+responses and persisted to `.workspai/reports/doctor-remediation-plan-last-run.json` by
+`doctor workspace|project --plan`, `--fix`, and `--apply` so IDEs can render approved commands,
+typed file edits, diff previews, ordered phases, step dependencies, rollback, and verification
+steps without inferring them. `doctor-fix-result-last-run.json` records the approved execution
+outcome, and fix/apply runs append a `kind: doctor-fix` entry to
+`workspace-intelligence-history.json`.
+
+Artifact remediation handoff:
+`artifact-remediation-plan-v1` (`contracts/artifact-remediation-plan.v1.json`) is emitted by
+`workspace remediation-plan --json` and persisted with `--write`. Add `--ci` to produce
+CI-oriented verify commands where the underlying command supports stricter gates. It is the cross-card Studio
+handoff for governance artifacts outside Doctor: Bootstrap compliance, Analyze, Readiness,
+Pipeline, Workspace Run, Workspace Verify, and Doctor plan bridging. Consumers should ask npm for
+this plan before inventing per-card repair logic. The plan carries ordered actions, safe file
+operations where deterministic, refresh/verify commands, risk, approval state, and rollback
+strategy.
+
+When `doctor project` runs inside a workspace, the workspace report remains the canonical
+governance artifact and Doctor mirrors `doctor-project-last-run.json`,
+`doctor-remediation-plan-last-run.json`, and `doctor-fix-result-last-run.json` into the scoped
+project's `.workspai/reports/` directory. This keeps Studio, agents, and project-local operators on
+the same evidence without losing the workspace source of truth.
+
+## Workspace intelligence
+
+| Command                                        | Artifact                                                                                                                                                                                                                                                     | Schema                                 | Contract file                                                             |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- |
+| `workspace model --write`                      | `workspace-model.json`                                                                                                                                                                                                                                       | `workspace-model.v1`                   | `contracts/workspace-intelligence/workspace-model.v1.json`                |
+| `workspace snapshot`                           | `workspace-model-snapshot.json`                                                                                                                                                                                                                              | `workspace-model-snapshot.v1`          | `workspace-model-snapshot.v1.json`                                        |
+| `workspace diff`                               | `workspace-model-diff-last-run.json`                                                                                                                                                                                                                         | `workspace-model-diff.v1`              | `workspace-model-diff.v1.json`                                            |
+| `workspace impact --from <diff>`               | `workspace-impact-last-run.json`                                                                                                                                                                                                                             | `workspace-impact.v1`                  | `workspace-impact.v1.json`                                                |
+| `workspace verify`                             | `workspace-verify-last-run.json`                                                                                                                                                                                                                             | `workspace-verify.v1`                  | `workspace-verify.v1.json`                                                |
+| `workspace context --write`                    | `workspace-context-agent.json`                                                                                                                                                                                                                               | `workspace-context.v1`                 | `workspace-context.v1.json`                                               |
+| `workspace agent-sync --write`                 | `reports/INDEX.json`, `reports/agent-customization-pack.json`, `reports/workspai-mcp-design.json`, `reports/workspace-skills-index.json`, `.workspai/skills/*.md`, `.workspai/AGENT-GROUNDING.md`, `AGENTS.md`, Copilot/Cursor/Claude/VS Code agent surfaces | `rapidkit-agent-customization-pack.v1` | `contracts/agent-customization-pack.v1.json`                              |
+| `workspace explain --write`                    | `workspace-explain-last-run.json`                                                                                                                                                                                                                            | `workspace-explain.v1`                 | `contracts/workspace-intelligence/workspace-explain.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` |
+
+**CLI semantics:** `workspace diff --from` expects a **model or snapshot** baseline. `workspace impact --from` expects a **diff report**.
+
+### Dependency graph (`workspace-dependency-graph.v1`)
+
+The dependency graph is the first-class structure that promotes inter-project
+relationships out of `workspace run`'s private logic into one versioned source
+of truth consumed by `impact` (transitive blast radius), `verify`
+(subgraph-scoped gating), `run --blast-radius`, and risk weighting.
+
+| Field   | Meaning                                                                                                                                                                                    |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `nodes` | Projects in the workspace (`id`, workspace-relative `path`).                                                                                                                               |
+| `edges` | Directed `from → to` relationships (`from` depends on `to`). Each edge carries a typed `kind`, a `source` (provenance), a `confidence` bucket, and `evidence` (the files that justify it). |
+| `stats` | Counts (`nodeCount`, `edgeCount`, per-source edge counts) and `hasCycle` for the integrity gate.                                                                                           |
+
+Edge `kind` ∈ `code-import`, `package-dep`, `event-pub-sub`, `service-dependsOn`,
+`shared-resource`. Edge `source` ∈ `inferred`, `contract`, `manual` (`manual`/`contract`
+are authoritative and override an `inferred` edge of the same kind between the same
+nodes). Canonical source: `src/contracts/workspace-dependency-graph-contract.ts`;
+JSON Schema: `contracts/workspace-intelligence/workspace-dependency-graph.v1.json`.
+
+**Inference engine.** The graph is derived deterministically by
+`src/workspace-dependency-graph.ts` (`inferWorkspaceDependencyGraph`) from multiple
+sources: package manifests (`package.json` deps, `pyproject.toml` path deps, `go.mod`
+replace → `package-dep`), cross-boundary JS/TS source imports (`code-import`), the
+workspace contract (`dependsOn` → `service-dependsOn`, matched `publishes`/`consumes`
+→ `event-pub-sub`, env↔port references → `shared-resource`), and an optional manual
+override file. Node/edge ordering and `hashDependencyGraph` are stable, so the graph is
+embedded as a first-class field of `workspace-model.v1` (`model.graph`) on every
+`buildWorkspaceModel` run; `hashModel` normalizes the embedded `graph.generatedAt` so the
+structural graph participates in the model hash without causing timestamp drift.
+(`model.graph` is additive/optional for pre-graph readers.)
+
+**Manual overrides.** `.workspai/workspace-graph.overrides.json` (`{ "edges": [{ "from",
+"to", "kind", "evidence" }] }`) declares authoritative edges that win over inference for
+the same `(from, to, kind)`.
+
+**Graph-aware impact.** `workspace impact` consumes the graph for a true transitive
+blast radius: alongside `affectedProjects` (directly changed) it emits `transitiveImpact[]`
+— projects reached only through the graph, each with `origin: 'transitive'`, `distance`,
+the shortest dependency `path`, and `via` (edge kind). `summary.blastRadius`
+(`directlyAffected`, `transitivelyAffected`, `maxDistance`, `graphEdges`) summarizes the
+reach. Both arrays feed the `verificationPlan`.
+
+**Graph-aware verify.** `workspace verify` gates the **whole affected subgraph**, not just
+the changed node. `affectedSubgraph` (`directlyChanged`, `transitiveDependents`, `covered`,
+`uncovered`, `unverifiable`) records coverage per project: a dependent with failed or
+missing-required verification evidence becomes a `graph.subgraph.<project>` blocking reason;
+missing non-required evidence escalates the verdict to `needs-attention`; a dependent with no
+applicable verification command is `unverifiable` (informational, never blocking).
+
+**Centrality-weighted risk.** `workspace impact` computes graph centrality
+(`fanIn`/`fanOut`/`reach`/`betweenness`) per project; each impact item carries `centrality`,
+a directly-changed critical-path hotspot escalates its risk one level, and the report lists
+`criticalPathHotspots[]` (ranked by reach then betweenness). Canonical source:
+`src/workspace-graph-centrality.ts` (`computeGraphCentrality`).
+
+**Graph integrity gate.** `workspace verify` emits `graphIntegrity` (`ok`, `cycles`,
+`danglingEdges`, `orphans`, `stats`). Cycles and dangling edges are blocking
+(`graph.integrity.cycle` / `graph.integrity.dangling` reasons); orphans are informational.
+Canonical source: `src/workspace-graph-integrity.ts` (`checkGraphIntegrity`).
+
+**Watch / daemon mode.** `workspace watch [--json] [--once]` keeps the model + graph in
+memory and streams `workspace-watch-event.v1` records (`ready`/`changed`/`unchanged`/`error`)
+on each settled change, driven by graph-aware incremental rebuilds. Events carry changed/added/
+removed projects, graph edge deltas, structural `modelHash`, and `mode`/`durationMs`. Canonical
+source: `src/workspace-watch.ts`.
+
+**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).
+Canonical source: `src/workspace-history.ts`.
+
+**Verify gate + policy violations.** `workspace verify --json` emits a `gate`
+object (`passed`, `mode`, `exitCode`, `reasons`) from `evaluateWorkspaceVerifyGate` — the
+definitive pre-action gate (default fails on `blocked`; `--strict` also fails on
+`needs-attention` and `stale` freshness). It also emits `policyMode` + `policyViolations[]`
+(model validation issues + contract `violations`); in `enforce` mode error-severity violations
+block, in `warn` mode they escalate to needs-attention.
+
+**Graph-aware freshness.** `workspace verify` emits a `freshness` block
+(`verdict: fresh|stale|unknown`, `changed`/`added`/`removed`, `projectHashes`). Each project's
+`transitiveInputsHash` chains its own content hash with its transitive dependencies' hashes, so
+a dependency change makes every dependent stale deterministically. The verdict compares against
+the previously written verify report. Canonical source: `src/workspace-graph-freshness.ts`.
+
+**Graph command surface.** `workspace graph` emits the graph plus integrity + hotspots;
+`workspace graph explain <project>` returns centrality and direct/transitive relationships;
+`workspace graph dot|mermaid` render deterministic visualizations. Canonical source:
+`src/workspace-graph.ts`. The `graph` subcommand is part of `WORKSPACE_SUBCOMMANDS` and is
+published via `runtime-command-surface.v1` for IDE/CI capability detection.
+
+### Model cache (`workspace-model-cache.v1`)
+
+On-disk path: `.workspai/cache/workspace-model.v1.json`. Opt-in (`workspace model --cache`)
+cache keyed by `inputsHash` — a deterministic fingerprint of the project set, per-project
+manifest contents, workspace files (contract/workspace.json/policies), build flags, and CLI
+version. On a hit the stored model is returned byte-for-byte; on a miss it is rebuilt and
+rewritten. Canonical source: `src/workspace-model-cache.ts` (`computeModelInputsHash`,
+`buildWorkspaceModelCached`). Granularity is manifest/project-set level, not per-source-file.
+
+The envelope also stores per-project signatures (`computeProjectSignatures`: manifest hashes +
+a source fingerprint of `path:size:mtime`) and workspace-file signatures, powering
+`workspace model --incremental` (`buildWorkspaceModelIncremental`): unchanged project models are
+reused and the dependency graph re-infers only edges incident to changed projects
+(`inferWorkspaceDependencyGraphIncremental`). It falls back to a full rebuild on workspace-file
+changes or project renames, and rescans code-imports fully when the node set changes. Reported
+modes: `full` / `incremental` / `unchanged`.
+
+### Freshness metadata (`rapidkit-freshness-metadata-v1`)
+
+Intelligence reports carry a shared freshness envelope so any consumer (CLI
+`workspace verify`, Workspai, CI) can detect staleness **without** re-running the
+whole chain:
+
+| Field         | Meaning                                                                                                                 |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `generatedAt` | ISO-8601 timestamp the report was produced.                                                                             |
+| `inputsHash`  | Stable sha256 of the inputs that produced the report. If a freshly recomputed inputs hash differs, the report is stale. |
+
+Canonical source: `src/contracts/freshness-metadata-contract.ts`
+(`computeInputsHash`, `buildFreshnessMetadata`, `assessFreshness`). Verdicts:
+`fresh` (hashes match), `stale` (hashes differ), `unknown` (either side missing,
+e.g. legacy reports).
+
+### Fact freshness (`rapidkit-fact-freshness-v1`)
+
+Artifact-level freshness answers "is this report still valid?" Fact-level freshness answers
+"may an agent safely remember this specific claim?" `workspace model` and
+`workspace context --for-agent --write` now emit `facts[]` plus a `factFreshness` summary so
+agents, Workspai, and CI can distinguish durable structure from perishable evidence.
+
+| Kind                | Meaning                                                                  |
+| ------------------- | ------------------------------------------------------------------------ |
+| `durable`           | Structural configuration such as workspace identity or policy mode       |
+| `derived`           | Inferred structure such as project count, runtime, framework, commands   |
+| `evidence-backed`   | A fact backed by a report that can expire or become stale                |
+| `live`              | Runtime state that must be re-observed quickly                           |
+| `verify-before-use` | Missing, stale, or release-sensitive fact that must be regenerated first |
+
+Every fact carries `category` (`structure`, `verification`, `state`), `generatedAt`,
+`ttlSeconds`, `status`, `verifyBeforeUse`, `sourceArtifact`, optional `sourcePath`, and a
+stable `inputsHash` for the fact value. Consumers must treat `verifyBeforeUse: true` as a hard
+refresh boundary before advice, edits, or release decisions. Canonical source:
+`src/contracts/fact-freshness-contract.ts`; JSON Schema:
+`contracts/workspace-intelligence/fact-freshness.v1.json`.
+
+### Run correlation (`runId`)
+
+When a command runs through the CLI with the structured log stream active, the
+persisted intelligence artifacts (`workspace-model.json`, `workspace-model-snapshot.json`,
+`workspace-model-diff-last-run.json`, `workspace-impact*.json`, `workspace-context-agent.json`)
+carry a top-level `runId`. It matches the `runId` on the `cli-log-event.v1` stream
+(`run.started`/`progress`/`run.completed`), so a consumer can tie an on-disk report
+to the exact run that produced it. `runId` is added at write time only and is
+ignored by `modelHash`/diff comparisons, so deterministic hashing is unaffected.
+Canonical source: `src/observability/run-correlation.ts` (`attachRunCorrelation`).
+
+## Operational / platform
+
+| Command                          | Artifact                                                               | Notes                                                                                        |
+| -------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------- |
+| `workspace run`                  | `workspace-run-last.json`                                              | `workspace-run-v1` (multi-stage: `stages.test`, `stages.build`, …)                           | `contracts/workspace-run-last.v1.json` |
+| `autopilot release` (run stages) | same `workspace-run-last.json`                                         | Autopilot publishes test/build into aggregate (no separate `autopilot-workspace-run-*.json`) | —                                      |
+| `bootstrap`                      | `bootstrap-compliance-{ts}.json`, `bootstrap-compliance.latest.json`   |                                                                                              |
+| `mirror status`                  | `mirror-ops-{ts}.json`, `mirror-ops.latest.json`                       |                                                                                              |
+| `mirror` (transparency)          | `transparency-evidence-{ts}.json`, `transparency-evidence.latest.json` |                                                                                              |
+| `infra plan`                     | `infra-plan.json`                                                      | `rapidkit.infra-plan.v1`                                                                     |
+| `workspace archive`              | `archive-manifest.json`                                                | Root `.workspai/`, handoff                                                                   |
+| `workspace share`                | `reports/share-bundle.json` (default)                                  | Aggregation bundle                                                                           |
+| `import` / `adopt`               | `{project}/.workspai/import-readiness.json`                            | Per project                                                                                  |
+| `workspace contract verify`      | `workspace-contract-verify-last-run.json`                              | CLI verify cache                                                                             |
+
+## Static capability contracts
+
+| Contract                                        | Schema version                            | Consumer purpose                                                                                 |
+| ----------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `contracts/runtime-command-surface.v1.json`     | `rapidkit-runtime-command-surface-v1`     | Runtime commands, scaffold kits, and create planner summary                                      |
+| `contracts/create-planner-capabilities.v1.json` | `rapidkit-create-planner-capabilities-v1` | Native create, external-create-adopt, and adopt-only lanes for CLI, CI, VS Code, and AI planners |
+
+## Observability stream (not on-disk)
+
+Separate from the on-disk artifacts above, Workspai CLI emits a structured
+**NDJSON log stream on stderr** when `--log-format json` (or `RAPIDKIT_LOG_FORMAT=json`)
+is set. This is the deterministic progress/outcome channel for IDEs and CI.
+
+| Stream                  | Schema version     | Contract file                     | Doc                                                  |
+| ----------------------- | ------------------ | --------------------------------- | ---------------------------------------------------- |
+| CLI log events (stderr) | `cli-log-event-v1` | `contracts/cli-log-event.v1.json` | [CLI_LOG_EVENT_STREAM.md](./CLI_LOG_EVENT_STREAM.md) |
+
+**Channel rule:** command **results** go to stdout (`--json`); **progress/lifecycle**
+events go to stderr (`--log-format json`). The two never mix.
+
+## Registry commands
+
+| Command                                          | Output                                                                           |
+| ------------------------------------------------ | -------------------------------------------------------------------------------- |
+| `workspace sync [--json]`                        | Updates contract + `workspace-registry.v1.json`; JSON includes `registrySummary` |
+| `workspace registry status [--refresh] [--json]` | Reads or publishes registry summary                                              |
+
+## Project-scoped reports
+
+Under `{project}/.workspai/reports/` when commands run at project scope (e.g. project doctor). Workspace-level reports stay under `{workspace}/.workspai/reports/`.
+
+## Consumer rules
+
+1. **Project count:** read `workspace-registry.v1.json` (or run `workspace registry status --json`).
+2. **Release gates:** follow chain doctor → analyze → readiness → verify → autopilot; use `pipeline-last-run.json` for 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 customization:** read `.workspai/reports/agent-customization-pack.json` first for generated surfaces, then `.workspai/reports/INDEX.json` and `workspace-context-agent.json`; regenerate with `workspace agent-sync --write --refresh-context --preset enterprise`.
+
+## Agent customization files (repo hooks)
+
+Written by `workspace agent-sync --write --refresh-context --preset enterprise` (and by default after `workspace context --for-agent --write`):
+
+| Path                                                                    | Consumer                                                       |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `AGENTS.md`                                                             | Copilot, Cursor, Claude Code, Codex, Grok (open standard)      |
+| `.github/copilot-instructions.md`                                       | GitHub Copilot / VS Code Chat                                  |
+| `.github/instructions/workspai-workspace.instructions.md`               | Copilot workspace scope and command discipline                 |
+| `.github/instructions/workspai-evidence.instructions.md`                | Copilot scoped `.workspai/**` and compatibility evidence rules |
+| `.github/prompts/workspai-diagnose.prompt.md`                           | Copilot prompt library                                         |
+| `.github/prompts/workspai-repair.prompt.md`                             | Copilot repair workflow prompt                                 |
+| `.github/prompts/workspai-release-readiness.prompt.md`                  | Copilot release readiness workflow prompt                      |
+| `.github/prompts/workspai-project-onboard.prompt.md`                    | Copilot project onboarding workflow prompt                     |
+| `.github/prompts/workspai-adopt-project.prompt.md`                      | Copilot adopt/import workflow prompt                           |
+| `.github/skills/workspai-grounding/SKILL.md`                            | Copilot skills                                                 |
+| `.github/skills/workspai-workspace-intelligence/SKILL.md`               | Enterprise Workspace Intelligence skill                        |
+| `.github/skills/workspai-workspace-intelligence/resources/mcp-tools.md` | Future MCP tool design reference                               |
+| `.github/agents/workspai-advisor.agent.md`                              | Read-only workspace advisor agent                              |
+| `.github/agents/workspai-repair.agent.md`                               | Blocker repair agent                                           |
+| `.github/agents/workspai-release.agent.md`                              | Release safety agent                                           |
+| `.github/agents/workspai-project-onboarder.agent.md`                    | Project onboarding agent                                       |
+| `.cursor/rules/workspai-grounding.mdc`                                  | Cursor always-on rule                                          |
+| `CLAUDE.md`                                                             | Claude Code (imports `@AGENTS.md`)                             |
+| `.claude/rules/workspai-evidence.md`                                    | Claude Code scoped evidence rule                               |
+| `.claude/rules/rapidkit-evidence.md`                                    | Legacy Claude Code scoped evidence mirror                      |
+| `.workspai/AGENT-GROUNDING.md`                                          | Tool-agnostic operator doc                                     |
+| `.workspai/reports/agent-customization-pack.json`                       | Versioned output inventory, target matrix, drift state         |
+| `.workspai/reports/workspai-mcp-design.json`                            | Read-mostly MCP-ready design manifest                          |
+| `.vscode/workspai-agent-hooks.json`                                     | Optional advisory VS Code agent hooks (`--experimental-hooks`) |
+
+Some `rapidkit-*` prompt, skill, Cursor, MCP-design, and hook paths remain available for older consumers during the rebrand window. New consumers should use the `workspai-*` paths first.
+
+## See also
+
+- [README.md](./README.md)
+- [COMMAND_OWNERSHIP_MATRIX.md](./COMMAND_OWNERSHIP_MATRIX.md)
+- [CLI_LOG_EVENT_STREAM.md](./CLI_LOG_EVENT_STREAM.md)
+- [commands-reference.md](../commands-reference.md)

package/docs/contracts/CLI_LOG_EVENT_STREAM.md

@@ -0,0 +1,123 @@
+# Workspai CLI Log Event Stream (`cli-log-event.v1`)
+
+Structured NDJSON observability stream emitted by Workspai CLI so IDEs (Workspai),
+CI, and agents can track command progress and outcome **without scraping human
+terminal text**.
+
+- **Schema version:** `cli-log-event-v1`
+- **JSON Schema:** [`contracts/cli-log-event.v1.json`](../../contracts/cli-log-event.v1.json)
+- **TypeScript contract:** `src/contracts/cli-log-event-contract.ts` (single runtime
+  source of `CLI_LOG_LEVELS`, `CLI_LOG_EVENT_KINDS`, `CLI_LOG_EVENT_REQUIRED_FIELDS`)
+- **Drift guard:** `src/__tests__/contracts/cli-log-event-contract.test.ts` pins the
+  TypeScript contract to the JSON schema so the two can never diverge silently.
+
+## Channel separation (critical)
+
+Workspai keeps two machine-readable channels strictly separate:
+
+| Channel | Flag | Content |
+| ------- | ---- | ------- |
+| **stdout** | `--json` | The command **result** payload (e.g. workspace model, analyze report). One JSON document. |
+| **stderr** | `--log-format json` (or `--log-json`, or `RAPIDKIT_LOG_FORMAT=json`) | The **NDJSON log stream** — one `cli-log-event.v1` object per line. |
+
+Because the two channels are independent, a consumer can request structured
+progress (`--log-format json`) **and** a structured result (`--json`) at the same
+time without corrupting either stream.
+
+## Activation
+
+Any of the following enables the stream:
+
+```bash
+workspai workspace model --json --log-format json
+RAPIDKIT_LOG_FORMAT=json workspai workspace verify --json
+workspai doctor workspace --log-json
+```
+
+In text mode (the default) no structured log events are written to stderr.
+
+### Flag normalization (why it works for every command)
+
+`--log-format json` / `--log-json` are **not** registered as per-command options. On
+startup the CLI resolves the requested format once, makes it sticky via
+`RAPIDKIT_LOG_FORMAT=json`, and strips the observability flags from `process.argv`
+before any command parser runs. This guarantees the stream works uniformly for
+commander-parsed commands (e.g. `workspace model`), manually handled commands
+(e.g. `create`), and delegated child CLIs (which inherit the env var) — without a
+command ever rejecting the flag as an "unknown option". The result flag (`--json`)
+is preserved, so the stdout result and the stderr stream stay independent.
+
+## Workspace intelligence phase events
+
+Every workspace intelligence subcommand (`model`, `snapshot`, `diff`, `impact`,
+`verify`, `context`, `agent-sync`) emits at least a `progress` event when the
+stream is active:
+
+```json
+{ "event": "progress", "component": "workspace",
+  "metadata": { "phase": "workspace.model", "action": "model", "status": "started" } }
+```
+
+The terminal outcome is always covered by the run lifecycle (`run.completed` /
+`run.failed`), so a consumer can settle UI state deterministically.
+
+## Event shape
+
+Each stderr line is a single JSON object:
+
+```json
+{
+  "schemaVersion": "cli-log-event-v1",
+  "runId": "5f1d…",
+  "timestamp": "2026-06-22T13:59:01.123Z",
+  "level": "info",
+  "event": "run.started",
+  "component": "cli",
+  "message": "CLI run started",
+  "command": ["workspace", "model"],
+  "metadata": { "cwd": "/path/to/workspace", "rapidkitVersion": "0.38.0" }
+}
+```
+
+### Fields
+
+| Field | Required | Notes |
+| ----- | -------- | ----- |
+| `schemaVersion` | yes | Always `cli-log-event-v1`. |
+| `runId` | yes | Stable UUID for the whole CLI invocation; correlates every event in one run. |
+| `timestamp` | yes | ISO-8601 date-time. |
+| `level` | yes | `debug` \| `info` \| `warn` \| `error`. |
+| `event` | yes | `log` \| `progress` \| `run.started` \| `run.completed` \| `run.failed`. |
+| `component` | yes | Emitting component (e.g. `cli`, `create`). |
+| `message` | yes | Human-readable message. |
+| `command` | no | Command argv (observability flags stripped). |
+| `metadata` | no | Sanitized key/value context (e.g. `exitCode`, `cwd`, `rapidkitVersion`). |
+
+## Run lifecycle events
+
+Every invocation that runs through the CLI run context emits a deterministic
+lifecycle, keyed by a shared `runId`:
+
+1. `run.started` — emitted on initialization (`level: info`).
+2. `run.completed` — emitted on exit code `0` (`level: info`, `metadata.exitCode: 0`).
+3. `run.failed` — emitted on any non-zero exit (`level: error`, `metadata.exitCode: <n>`).
+
+`run.completed` / `run.failed` are guaranteed even when a command calls
+`process.exit()`, because the CLI installs a process-exit hook that finalizes the
+run context.
+
+## Consumer guidance (IDE / CI)
+
+1. Spawn with `--log-format json` to receive progress; parse stderr line-by-line.
+2. Treat a line as an event only if it parses as JSON and matches the schema
+   (`schemaVersion === 'cli-log-event-v1'`). Ignore non-matching lines.
+3. Use `runId` to group events; show progress on `progress`/`log`, settle UI state
+   on `run.completed` / `run.failed`.
+4. Read the command **result** from stdout `--json`, not from the log stream.
+5. Workspai consumes this stream via `src/core/cliLogEventContract.ts`
+   (`parseCliLogEventLine`) to drive deterministic progress and evidence refresh.
+
+## See also
+
+- [ARTIFACT_CATALOG.md](./ARTIFACT_CATALOG.md) — on-disk artifacts produced by commands
+- [COMMAND_OWNERSHIP_MATRIX.md](./COMMAND_OWNERSHIP_MATRIX.md)

package/docs/contracts/COMMAND_OWNERSHIP_MATRIX.md

@@ -0,0 +1,138 @@
+# Command Ownership Matrix
+
+This document defines which layer owns command execution in Workspai CLI (`workspai`) versus RapidKit Core (`rapidkit-core`) to prevent runtime conflicts.
+
+## Goals
+
+- Keep project bootstrapping reliable across Python / Node / Go projects.
+- Avoid conflicting behavior between wrapper and core CLIs.
+- Make delegation behavior explicit and testable.
+
+## Ownership Rules
+
+### 1) Wrapper-owned commands (never forward to core)
+
+These commands are implemented and orchestrated by Workspai CLI:
+
+- `readiness`
+- `autopilot`
+- `pipeline`
+- `doctor`
+- `import`
+- `adopt`
+- `snapshot`
+- `workspace`
+- `bootstrap`
+- `setup`
+- `cache`
+- `mirror`
+- `ai`
+- `analyze`
+- `config`
+- `product`
+- `infra`
+- `commands`
+- `shell activate`
+
+Reason: workspace-level policy, registry, and platform orchestration live in npm wrapper.
+
+### 1.1) Wrapper-owned scoped commands
+
+These scoped commands are implemented and orchestrated by Workspai CLI:
+
+- `project commands`
+- `project archives`
+- `project archive`
+- `project restore`
+- `project delete`
+
+Reason: these are workspace project lifecycle and capability operations with
+archive manifests, safety snapshots, workspace registry side effects, and
+runtime-aware command discovery.
+
+`project detect` remains Core-owned because it is the stable machine-readable
+contract used by wrappers to detect Python RapidKit projects.
+
+`commands --scope project` is also wrapper-owned. It reports the effective
+project command capability matrix for the currently selected project without
+delegating to Core.
+
+### 2) Wrapper-orchestrated project commands
+
+These commands are handled by npm wrapper first (runtime-aware + fallback-aware)
+when the project capability matrix marks them as runtime-supported:
+
+- `init`
+- `dev`
+- `start`
+- `build`
+- `test`
+- `lint`
+- `format`
+- `help`
+
+Reason: generated projects can be Python, Node/NestJS, Go/Fiber, Go/Gin, or
+Spring Boot. Runtime commands must run through the selected project's adapter,
+not through a hard-coded global assumption.
+
+### 3) Core module/template commands
+
+These commands are supported only when the selected project is Core-backed
+and has module/template support:
+
+- `add`
+- `modules`
+- `upgrade`
+- `diff`
+- `merge`
+- `reconcile`
+- `rollback`
+- `uninstall`
+- `checkpoint`
+- `snapshot`
+- `optimize`
+
+Dispatch policy:
+
+- FastAPI / NestJS Core-backed project → supported and delegated to Core.
+- Go / Spring Boot / ASP.NET Core npm-owned project → blocked with a capability explanation.
+- Unknown project → blocked until project metadata is present.
+
+### 4) Global engine/catalog commands
+
+These commands are not project-specific even when run inside a project:
+
+- `create`
+- `list`
+- `info`
+- `frameworks`
+- `license`
+
+`create` remains npm-owned so the wrapper can orchestrate multi-language
+workspace/project generation. The other commands may delegate to Core as engine
+catalog operations.
+
+## Dynamic Project Capability Model
+
+A pure-core or pure-wrapper model causes regressions in mixed-language workspaces. Hybrid ownership keeps Python compatibility while letting npm wrapper enforce workspace policy and resilient cross-platform fallback behavior.
+
+The npm wrapper resolves project capabilities from `.workspai/project.json`,
+`.workspai/context.json`, legacy `.rapidkit/*` metadata, and framework/runtime markers. Users and tools can
+inspect the effective command surface with:
+
+- `workspai project commands`
+- `workspai project commands --json`
+- `workspai commands --scope project --json`
+
+This capability model is the canonical bridge between npm-owned kits and
+Core-backed kits. Adding a future language or framework should update the
+project metadata and runtime detector first, then the capability matrix follows
+without widening the Core/global command surface.
+
+## Guard Rails
+
+- `shouldForwardToCore()` must return `false` for wrapper-owned and wrapper-orchestrated project commands.
+- `project commands` and `commands --scope project` must never forward to Core.
+- Core module/template commands must be blocked for npm-owned projects that set `module_support: false`.
+- Tests must assert forwarding boundary rules.
+- Changes to ownership should update this file and tests together.