workspai 0.64.0 → 0.66.0

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -25,13 +25,15 @@ exclude the canonical marker.
 These paths are relative to each registered project root, not the workspace
 root:
 
-| Artifact                                       | Writer                                                                            | Schema / format             | Portability and reader purpose                                                        |
-| ---------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------- |
-| `.workspai/workspace-link.local.json`          | `adopt`, `import`, project creation, `workspace sync`, `project workspace relink` | `project-workspace-link.v1` | Machine-local absolute binding; always gitignored and never an agent evidence payload |
-| `.workspai/agent-entry.v1.json`                | Project lens reconciliation and `workspace agent-sync --write`                    | `workspai.agent-entry.v1`   | Portable host-discovery, canonical read-order, authority, and integrity contract      |
-| `.workspai/reports/project-context-agent.json` | Project lens reconciliation and `workspace agent-sync --write`                    | `project-context-agent.v1`  | Portable bounded model/graph/proof projection for project-local agents                |
-| `.workspai/PROJECT-GROUNDING.md`               | Project lens reconciliation                                                       | Markdown                    | Portable human/agent entry guide with path-free workspace references                  |
-| `AGENTS.md` managed section                    | Project lens reconciliation in `managed` mode                                     | Managed Markdown block      | Preserves user content and routes compatible agents to project/workspace evidence     |
+| Artifact                                                   | Writer                                                                            | Schema / format                        | Portability and reader purpose                                                         |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------- |
+| `.workspai/workspace-link.local.json`                      | `adopt`, `import`, project creation, `workspace sync`, `project workspace relink` | `project-workspace-link.v1`            | Machine-local absolute binding; always gitignored and never an agent evidence payload  |
+| `.workspai/agent-entry.v1.json`                            | Project lens reconciliation and `workspace agent-sync --write`                    | `workspai.agent-entry.v1`              | Portable host-discovery, canonical read-order, authority, and integrity contract       |
+| `.workspai/reports/project-context-agent.json`             | Project lens reconciliation and `workspace agent-sync --write`                    | `project-context-agent.v1`             | Portable bounded model/graph/proof projection for project-local agents                 |
+| `.workspai/reports/project-knowledge-graph-reference.json` | Workspace Model publication                                                       | `project-knowledge-graph-reference.v1` | Small portable reference whose projection hash is verified against the canonical graph |
+| `.workspai/PROJECT-GROUNDING.md`                           | Project lens reconciliation                                                       | Markdown                               | Portable human/agent entry guide with path-free workspace references                   |
+| `.agents/skills/workspai-*/SKILL.md`                       | Project lens reconciliation                                                       | Agent Skill                            | Project-native wrappers that resolve canonical workspace playbooks without local paths |
+| `AGENTS.md` managed section                                | Project lens reconciliation in `managed` mode                                     | Managed Markdown block                 | Preserves user content and routes compatible agents to project/workspace evidence      |
 
 The project link is validated against the canonical workspace contract and a
 SHA-256 binding over workspace identity, project identity, portable relative
@@ -40,13 +42,20 @@ absolute paths before writing. `managed`, `local`, and `off` grounding modes
 control portable project surfaces and converge by removing stale managed
 sections and ignore rules during transitions; they never make the
 machine-local link publishable. The context is bounded but not count-only: it
-includes topology, API/deployment/test surfaces, blockers, portable proofs,
-and model/graph freshness for the selected project.
+includes compact topology, representative API/deployment/test surfaces,
+blockers, portable proof locators, and model/graph freshness for the selected
+project. Complete graph evidence is retrieved through bounded search instead
+of duplicated into every project.
 
 `agent bootstrap --json` and `project agent-entry verify --json` emit a
 non-persisted `workspai.agent-bootstrap-receipt.v1` payload. The receipt proves
 the selected host route, contract validity, integrity, persisted and live
 freshness, and active Goal bindings without exposing the machine-local link.
+Its top-level status covers agent grounding only; project-environment and
+release readiness are emitted as separate dimensions so consumers cannot treat
+successful grounding as release approval. The receipt exposes distinct project
+reference and workspace graph paths and blocks when the project reference hash
+is not the exact current canonical projection.
 
 ## Naming conventions
 
@@ -123,7 +132,8 @@ Entries beginning with `reports/` are relative to `.workspai/`; paths such as
 | 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 model --write`                       | `workspace-knowledge-graph.json` (canonical workspace aggregate)                                                             | `workspace-knowledge-graph.v1`         | `contracts/workspace-intelligence/workspace-knowledge-graph.v1.json`         |
+| `workspace model --write`                       | Project-local `.workspai/reports/project-knowledge-graph-reference.json`                                                     | `project-knowledge-graph-reference.v1` | `contracts/workspace-intelligence/project-knowledge-graph-reference.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`                  |
@@ -152,10 +162,15 @@ status/exit coherence, hard-failure skip propagation, and the aggregate verdict.
 See [Unified Workspace Intelligence Runner](../workspace-intelligence-runner.md)
 for the normative user and integration semantics.
 
-`workspace-model.json` and `workspace-knowledge-graph.json` are published under
-one workspace lock as a rollback-capable artifact transaction. Individual file
-replacement is atomic, and a partial set failure restores both preimages. The
-model is canonical; the graph is derived and cannot mutate it during the run.
+`workspace-model.json`, the canonical workspace `workspace-knowledge-graph.json`,
+and each registered project's compact
+`.workspai/reports/project-knowledge-graph-reference.json` are published under
+one workspace lock as a rollback-capable multi-root artifact transaction.
+Individual replacement is atomic, and a partial set failure restores every
+preimage. Each reference integrity-binds the exact project projection and points
+to the canonical aggregate through a portable `workspace:` URI, avoiding graph
+duplication in every linked repository. The model remains canonical and the
+graph remains derived.
 The graph contract fixes `source.kind` to `workspace-model`,
 `source.artifact` to `.workspai/reports/workspace-model.json`, and `source.hash`
 to the model's stable structural SHA-256. Current-state consumers must reject a
@@ -397,9 +412,10 @@ 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) |
+| 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)    |
+| Live activity events (machine-local NDJSON) | `workspace-activity-event.v1` | `contracts/workspace-activity-event.v1.json` | [Workspai Live Activity](../workspace-live-activity.md) |
 
 **Channel rule:** command **results** go to stdout (`--json`); **progress/lifecycle**
 events go to stderr (`--log-format json`). The two never mix.
@@ -431,8 +447,9 @@ canonical file. Legacy files remain readable during the compatibility window.
 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. Use `--scope project:<name>` when the task has one registered project boundary, inspect `budget.omitted` before assuming the result is complete, and follow returned proof paths to source evidence. Read the full context, model, or graph only when the bounded result is insufficient.
+5. **Agent retrieval:** inside an adopted project, start with `.workspai/agent-entry.v1.json` (or the host projection that routes to it), then read `.workspai/reports/project-context-agent.json`; its `intelligence.projection` states exactly how much representative graph data was bounded. At workspace scope, start with `AGENTS.md` and `.workspai/reports/INDEX.json`. In either scope, use `workspace graph search <query> --limit <n> --json` or MCP `searchWorkspaceGraph` for question-sized facts. Use `--scope project:<name>` for one registered project, inspect `budget.omitted` before assuming completeness, and follow proof paths to source evidence. Read the full context, model, or graph only when the bounded result is insufficient.
 6. **Agent customization state:** use `.workspai/reports/agent-customization-pack.json` to inspect generated surfaces and drift; regenerate with `workspace agent-sync --write --refresh-context --preset enterprise`.
+7. **Operational Skill selection:** use `.workspai/reports/workspace-skills-index.json`. Its `selection.decisions` distinguishes evidence-backed generated Skills from suppressed candidates and records scoped projects and supporting signals. A missing specialized Skill means the current canonical evidence did not prove that capability; it is not permission to assume one.
 
 ## Agent customization files (repo hooks)
 
@@ -443,32 +460,34 @@ failure, all touched files are restored; an interrupted transaction is recovered
 before the next agent-sync. `agent-customization-pack.json` is written last and
 serves as the completed-generation marker.
 
-| 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` | MCP tool and evidence-retrieval 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 compatibility alias pointing to the canonical rule      |
-| `.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`) |
+| Path                                                                    | Consumer                                                                                               |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `AGENTS.md`                                                             | Copilot, Cursor, Claude Code, Codex, Grok (open standard)                                              |
+| `.agents/skills/workspai-grounding/SKILL.md`                            | Provider-neutral Agent Skills grounding                                                                |
+| `.agents/skills/workspai-*/SKILL.md`                                    | Generated workspace operational skills                                                                 |
+| `.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` | MCP tool and evidence-retrieval 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 compatibility alias pointing to the canonical rule                                              |
+| `.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`                            | Implemented read-mostly MCP runtime manifest, served/planned tool inventory, and protocol capabilities |
+| `.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.
 

package/docs/contracts/COMMAND_OWNERSHIP_MATRIX.md

@@ -36,6 +36,7 @@ These commands are implemented and orchestrated by Workspai CLI:
 - `goal`
 - `agent`
 - `project`
+- `live`
 - `shell activate`
 
 Reason: workspace-level policy, registry, and platform orchestration live in npm wrapper.

package/docs/contracts/NAMING_AND_COEXISTENCE.md

@@ -4,19 +4,19 @@ Rules for **operational intelligence** artifacts so npm CLI, VS Code extension,
 
 ## Canonical vs generated surfaces
 
-| Layer | Canonical (workspace-native) | Generated (agent-sync) |
-| ----- | ---------------------------- | ---------------------- |
-| Operational playbooks | `.workspai/skills/{skillId}.md` | Legacy `.rapidkit/skills/{legacySkillId}.md` read fallback |
-| Skills index | `.workspai/reports/workspace-skills-index.json` | — |
-| Copilot skill umbrella | `.github/skills/workspai-workspace-intelligence/SKILL.md` | `.github/skills/rapidkit-workspace-intelligence/SKILL.md` legacy consumer surface |
-| Explain report | `.workspai/reports/workspace-explain-last-run.json` | — |
-| Action / repair feedback | `.workspai/reports/workspace-intelligence-history.json` (`kind: agent-action`, `doctor-fix`) | — |
+| Layer                    | Canonical (workspace-native)                                                                 | Generated (agent-sync)                                                            |
+| ------------------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Operational playbooks    | `.workspai/skills/{skillId}.md`                                                              | Legacy `.rapidkit/skills/{legacySkillId}.md` read fallback                        |
+| Skills index             | `.workspai/reports/workspace-skills-index.json`                                              | —                                                                                 |
+| Copilot skill umbrella   | `.github/skills/workspai-workspace-intelligence/SKILL.md`                                    | `.github/skills/rapidkit-workspace-intelligence/SKILL.md` legacy consumer surface |
+| Explain report           | `.workspai/reports/workspace-explain-last-run.json`                                          | —                                                                                 |
+| Action / repair feedback | `.workspai/reports/workspace-intelligence-history.json` (`kind: agent-action`, `doctor-fix`) | —                                                                                 |
 
-**Rule:** Never add a standalone `workspace skills generate` command. Operational skills are produced only by `workspace agent-sync --write` (extend the Agent Customization Pack).
+**Rule:** Never add a standalone `workspace skills generate` command. Operational skills are produced only by `workspace agent-sync --write` (extend the Agent Customization Pack). Templates are candidates, not guaranteed output: agent-sync materializes a candidate only when the canonical model, graph, contract, or command surface proves it applies. The skills index records generated and suppressed decisions with their evidence signals.
 
 ## Skill identifiers
 
-Built-in operational skill ids use the `workspai-*` prefix:
+Built-in operational skill candidates use the `workspai-*` prefix:
 
 - `workspai-diagnose-api-failure`
 - `workspai-release-readiness`
@@ -27,17 +27,19 @@ Built-in operational skill ids use the `workspai-*` prefix:
 Paths are derived from id via `operationalSkillPath()` in `src/contracts/workspace-artifact-paths.ts`.
 Legacy `rapidkit-*` skill and prompt paths may remain for older consumers during the rebrand window; new consumers should read the `workspai-*` paths first.
 
+`workspai-release-readiness` is workspace-applicable. API diagnosis, schema migration, dependency upgrade, and contract rename are emitted only for projects with matching evidence. Runtime, test, delivery, and polyglot skills are derived dynamically. Every emitted skill states why it exists, its scoped projects, observed signals, registered lifecycle boundary, and safe verification commands. Absence of evidence suppresses a skill rather than presenting a generic playbook as a detected capability.
+
 ## Command coexistence
 
-| User intent | Command | Notes |
-| ----------- | ------- | ----- |
-| Project / release / blocker narrative | `workspace explain …` | Primary explain surface |
-| Shorthand alias | `workspace why …` | Same parser as `explain` |
-| Diff → blast radius → gates | `workspace trace --from <diff>` | Slice of explain (`kind: trace`) |
-| Graph node centrality | `workspace graph explain <project>` | Graph-topology slice; see **Graph explain coexistence** below |
-| Record agent outcome | `workspace feedback record --json` | Appends `kind: agent-action` to history, no separate feedback file |
-| Record Doctor repair outcome | `doctor workspace|project --fix --json` | Writes `doctor-fix-result-last-run.json` and appends `kind: doctor-fix` to history |
-| MCP read bridge | `workspace mcp serve` | Read-mostly stdio JSON-RPC; maps Phase 4 explain + skills tools |
+| User intent                           | Command                             | Notes                                                              |
+| ------------------------------------- | ----------------------------------- | ------------------------------------------------------------------ |
+| Project / release / blocker narrative | `workspace explain …`               | Primary explain surface                                            |
+| Shorthand alias                       | `workspace why …`                   | Same parser as `explain`                                           |
+| Diff → blast radius → gates           | `workspace trace --from <diff>`     | Slice of explain (`kind: trace`)                                   |
+| Graph node centrality                 | `workspace graph explain <project>` | Graph-topology slice; see **Graph explain coexistence** below      |
+| Record agent outcome                  | `workspace feedback record --json`  | Appends `kind: agent-action` to history, no separate feedback file |
+| Record Doctor repair outcome          | `doctor workspace                   | project --fix --json`                                              | Writes `doctor-fix-result-last-run.json` and appends `kind: doctor-fix` to history |
+| MCP read bridge                       | `workspace mcp serve`               | Read-mostly stdio JSON-RPC; maps Phase 4 explain + skills tools    |
 
 ## Graph explain coexistence (4.11)
 

package/docs/contracts/README.md

@@ -28,8 +28,8 @@ Canonical JSON lives in **`../../contracts/`** (CLI package root, published in t
 | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
 | `npm run generate:contracts`                | Regenerate runtime surface, create planner, agent customization pack, import-stack parity, module-layout, infra-stack |
 | `npm run check:generated-contracts`         | Verify committed JSON matches generators                                                                              |
-| `npm run sync:shared-contracts`             | Generate canonical JSON and sync root plus locally available consumer mirrors                                          |
-| `npm run sync:parity-snapshot`              | Compatibility alias for canonical and consumer mirror synchronization                                                  |
+| `npm run sync:shared-contracts`             | Generate canonical JSON and sync root plus locally available consumer mirrors                                         |
+| `npm run sync:parity-snapshot`              | Compatibility alias for canonical and consumer mirror synchronization                                                 |
 | `npm run check:parity-snapshot`             | Verify mirrors match canonical                                                                                        |
 | `npm run contracts:prepush`                 | Sync local consumers and require generated canonical CLI mirrors to be committed                                      |
 | `npm run validate:contracts`                | Shared-contract checks and focused contract tests                                                                     |
@@ -88,7 +88,7 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `pipeline-last-run.v1.json` — governance pipeline orchestration
 - `project-entry-capability.v1.json` — open-ended adopt/import contract for readable projects
 - `workspace-intelligence/project-agent-entry.v1.json` — portable host discovery, canonical read order, authority boundaries, and integrity for an adopted project
-- `workspace-intelligence/agent-bootstrap-receipt.v1.json` — per-session proof of workspace membership, host coverage, schema validity, freshness, live inputs, and active Goal bindings
+- `workspace-intelligence/agent-bootstrap-receipt.v1.json` — per-session proof of workspace membership, host coverage, schema validity, freshness, live inputs, active Goal bindings, and explicitly separated grounding/environment/release readiness
 - `adopt-effects.v1.json` — dry-run disclosure of project metadata, conditional repository-control reconciliation, and workspace operations before adoption
 - `create-planner-capabilities.v1.json` — native, official, and existing capability lanes
 - `agent-customization-pack.v1.json` — generated instructions, prompts, skills, agents, optional hooks, MCP-ready design metadata, target matrix, and drift state for AI agent surfaces
@@ -96,6 +96,7 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `project-archive.v1.json`, `workspace-snapshot.v1.json`, and `workspace-snapshot.v2.json` — recoverable lifecycle records
 - `infra-plan.v1.json`, `private-product-manifest.v1.json`, and `product-factory-plan.v1.json` — infrastructure and product planning payloads
 - `workspace-model-cache.v1.json`, `workspace-watch-event.v1.json`, `doctor-project-scan.v2.json`, and `doctor-workspace-cache.v2.json` — cache/watch/diagnostic support contracts
+- `workspace-activity-event.v1.json` — local-first run/block/operation/touch stream consumed by `workspai live`; observational only, never Evidence/Decision authority
 
 Workspace intelligence (`../../contracts/workspace-intelligence/`):
 

package/docs/real-world-qualification.md

@@ -66,6 +66,17 @@ npm run test:real-world:enterprise -- \
   --report "$QUALIFICATION_ROOT/enterprise-command-surface.json"
 ```
 
+The enterprise harness resolves a real project from the graph, workspace
+contract, model, or imported-project registry. It never assumes a fixture
+project name. Snapshot names are unique per run, so the harness can be repeated
+against the same isolated workspace without creating a false lifecycle failure.
+Graph queries may target either managed or linked projects. Project archive and
+delete dry runs use a separate lifecycle target and are emitted only for a
+managed project physically contained by the workspace. When a workspace has
+only linked external projects, the report records
+`coverage.projectLifecycle: skipped-no-managed-project`; it does not misreport
+that safety boundary as a command failure.
+
 ## Safety and interpretation
 
 - Reference repositories are cloned locally with `git clone --shared`; no
@@ -82,13 +93,18 @@ npm run test:real-world:enterprise -- \
 - Dependency installation, project build/test/start/init, infrastructure
   mutation, publication, and model network calls are not permitted.
 - Agent customization and destructive project operations are dry-run only.
+- Runtime candidates describe observed nested composition; the authoritative
+  project runtime controls repair-adapter assertions. An aggregate boundary with
+  runtime `unknown` therefore follows the governed manual-repair path instead of
+  promoting its first nested runtime candidate.
 - Goal qualification publishes one system-understanding Goal inside the
   isolated test workspace, validates its lifecycle binding, and previews
   runtime-specific coverage and release-readiness goals without executing
   project tests or mutating project source.
-- Exit codes `1` and `2` may be valid domain outcomes when their documented JSON
-  contracts parse successfully; unexpected process, timeout, buffer, or schema
-  failures fail qualification.
+- Exit codes `1` and `2` are accepted only for commands whose contract explicitly
+  permits a governed block and only when the JSON payload contains a recognized
+  blocked/not-ready outcome. Graph lookup, project lifecycle, process, timeout,
+  buffer, malformed JSON, and schema failures fail qualification.
 - A real repository warning remains evidence, not a CLI defect. Fix the CLI only
   when detection, classification, contract, portability, or command semantics
   are wrong.

package/docs/workspace-knowledge-graph.md

@@ -56,6 +56,9 @@ Useful follow-up questions:
 # What APIs and endpoints exist?
 npx workspai workspace graph entities endpoint --json
 
+# Which languages are evidenced in one project? The flag form is equivalent.
+npx workspai workspace graph entities --kind language --scope project:billing --limit 100 --json
+
 # Why does Workspai believe this entity exists?
 npx workspai workspace graph evidence "GET /users" --json
 
@@ -116,6 +119,26 @@ symbols are not implied to have been extracted. The graph diagnostic reports
 the sampled and indexed candidate counts and must not be read as exhaustive
 symbol coverage.
 
+Language inventory is intentionally broader than source-structure parsing.
+The complete eligible-path inventory recognizes systems languages and compiler
+DSLs such as Assembly, CUDA, Fortran, HLSL, LLVM IR/MIR, MLIR, Objective-C,
+OpenCL, and TableGen even when Workspai has no safe generic symbol parser for
+that syntax. Language counts therefore remain project-wide inventory facts;
+symbols, imports, and calls remain bounded to parser-supported source inputs.
+
+Call binding follows the same proof boundary. Workspai binds a call only when
+its target is uniquely defined in the same file or in a locally imported file
+that the Graph already resolved. Overloads, dynamic dispatch, and ambiguous
+names remain explicit unknowns for compiler or language-server evidence; the
+CLI does not turn a repository-wide text match into semantic certainty.
+
+When a previous graph has the same project set, provider versions, and live
+project fingerprints, unchanged project slices are reused and only changed
+projects repeat the expensive semantic scan. Workspace-level CI, governance,
+infrastructure, and topology providers still run against the complete current
+workspace. The `incremental-project-cache` provider receipt records reused and
+rescanned scope counts. A provider-version change forces a full rebuild.
+
 ### Fast reads without stale answers
 
 The read-oriented `search`, `entities`, `evidence`, `path`, and `benchmark`
@@ -127,13 +150,14 @@ only when all of the following remain true:
 - no proof is marked stale;
 - the graph fingerprint contains exactly one workspace scope and every
   canonical project scope with compatible scan limits;
-- a fresh bounded scan produces the same aggregate live-input hash.
+- a fresh complete eligible-path inventory produces the same aggregate
+  live-input hash.
 
 Git-backed scopes use `git-worktree-v2`, covering tracked tree state plus
-modified, deleted, renamed, untracked, and relevant ignored files. If Git cannot
+modified, deleted, renamed, and non-ignored untracked files. If Git cannot
 prove the scanned inventory safely—for example because a traversed initialized
 submodule or hidden index flag is present—Workspai falls back to
-`content-merkle-v1`, which hashes each bounded file by portable path and content.
+`content-merkle-v1`, which hashes each eligible file by portable path and content.
 The graph records the combined strategy as `hybrid-git-content-v2`.
 
 A miss rebuilds from live sources. Use `--refresh-graph` when the caller requires
@@ -143,23 +167,57 @@ an explicit rebuild even if the persisted snapshot is compatible:
 npx workspai workspace graph search "protobuf ownership" --refresh-graph --json
 ```
 
-The fingerprint proves compatibility of the exact bounded provider inventory;
-if a scope reports `truncated: true`, it must not be interpreted as proof about
-files beyond that declared limit.
+The fingerprint normally covers every eligible Git-tracked and non-ignored
+untracked file in each project scope. The default `500000`-file limit is an
+emergency safety boundary, not a semantic completeness target. A scope with
+`truncated: true` or `inventoryMode: emergency-bounded` must not be interpreted
+as proof about files beyond that boundary. Git inventories publish an exact
+`eligibleFileCount`; a non-Git fallback that reaches the boundary publishes
+`eligibleFileCountExact: false` instead of inventing a total.
+
+Path inventory and content-heavy extraction have separate budgets. Complete
+inventory feeds freshness, manifest discovery, language counts, architecture
+contracts, CI, ownership, infrastructure, and targeted providers. Semantic and
+deep providers receive deterministic adaptive selections distributed across
+component and language buckets. This prevents a large package, vendored tree,
+or alphabetically early directory from starving the rest of a polyglot
+monorepo. Every provider publishes `inputCoverage`; successful execution over a
+bounded selection is reported as `partial`, never as exhaustive coverage.
+
+Defaults scale with the eligible project population up to these safety
+ceilings:
+
+- complete inventory emergency bound: `500000` files per project;
+- adaptive semantic input: up to `100000` files per project;
+- adaptive deep-provider input: up to `25000` files per project;
+- source extraction: up to `20000` files per project.
+
+Use `--graph-inventory-limit`, `--graph-semantic-budget`,
+`--graph-deep-budget`, and `--graph-source-budget` on `workspace graph`, or the
+equivalent `WORKSPAI_GRAPH_INVENTORY_LIMIT`,
+`WORKSPAI_GRAPH_SEMANTIC_BUDGET`, `WORKSPAI_GRAPH_DEEP_BUDGET`, and
+`WORKSPAI_GRAPH_SOURCE_BUDGET` environment variables for non-interactive model,
+Adopt, and Intelligence runs. Increasing deep budgets affects cost, not the
+canonical per-project storage boundary.
+
+Workspai-generated agent entry projections are downstream consumers and are
+excluded from Graph inventory and Git diff hashing. Regenerating `AGENTS.md`,
+adapter entry files, or the Amazon Q entry rule therefore cannot invalidate the
+Graph that produced them or become circular architecture evidence.
 
 ## Pick the command by question
 
-| You want to know…                                    | Use                                                     |
-| ---------------------------------------------------- | ------------------------------------------------------- |
-| What is relevant to a natural-language question?     | `workspace graph search <query> --limit <n> --json`     |
-| Which entities of one type exist?                    | `workspace graph entities <kind> --json`                |
-| Why does Workspai believe an item exists?            | `workspace graph evidence <entity-or-relation> --json`  |
-| How are two things connected?                        | `workspace graph path <from> <to> --json`               |
-| What changed between graph revisions?                | `workspace graph overlay --from <graph.json> --json`    |
-| What is the full portable graph?                     | `workspace graph emit --output graph.json --json`       |
-| How do I render the project topology?                | `workspace graph dot\|mermaid [--output <file>]`        |
-| How do I export to semantic or graph-analysis tools? | `workspace graph jsonld\|graphml\|gexf --output <file>` |
-| How much retrieval payload did one query avoid?      | `workspace graph benchmark <query> --limit <n> --json`  |
+| You want to know…                                    | Use                                                                           |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------- |
+| What is relevant to a natural-language question?     | `workspace graph search <query> --limit <n> --json`                           |
+| Which entities of one type exist?                    | `workspace graph entities <kind> [--scope project:name] [--limit <n>] --json` |
+| Why does Workspai believe an item exists?            | `workspace graph evidence <entity-or-relation> --json`                        |
+| How are two things connected?                        | `workspace graph path <from> <to> --json`                                     |
+| What changed between graph revisions?                | `workspace graph overlay --from <graph.json> --json`                          |
+| What is the full portable graph?                     | `workspace graph emit --output graph.json --json`                             |
+| How do I render the project topology?                | `workspace graph dot\|mermaid [--output <file>]`                              |
+| How do I export to semantic or graph-analysis tools? | `workspace graph jsonld\|graphml\|gexf --output <file>`                       |
+| How much retrieval payload did one query avoid?      | `workspace graph benchmark <query> --limit <n> --json`                        |
 
 `graph emit --json` writes the complete dependency and Knowledge Graph to
 stdout and can be very large. Automation, IDEs, and agents should pass
@@ -275,9 +333,10 @@ in `project.runtimeCandidates` and aggregates them into
 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
+The model, workspace aggregate, and all project graph artifacts are published
+under one workspace lock using a rollback-capable multi-root artifact
+transaction. Each file replacement is atomic; if any write fails, Workspai
+restores every preimage. `graph.source.kind` is fixed to
 `workspace-model`, `graph.source.artifact` is fixed to
 `.workspai/reports/workspace-model.json`, and `graph.source.hash` contains the
 stable structural hash of the persisted model. A current-state consumer must
@@ -357,14 +416,23 @@ into a false “complete” claim.
 
 ## Outputs and consumers
 
-`workspace model --write` publishes these two artifacts as one locked,
-rollback-capable artifact set:
+`workspace model --write` publishes the canonical model, one complete workspace
+aggregate, and one compact integrity-bound reference for every registered
+project as one locked, rollback-capable multi-root artifact set:
 
 ```text
-.workspai/reports/workspace-model.json
-.workspai/reports/workspace-knowledge-graph.json
+<workspace>/.workspai/reports/workspace-model.json
+<workspace>/.workspai/reports/workspace-knowledge-graph.json
+<project>/.workspai/reports/project-knowledge-graph-reference.json
 ```
 
+The workspace artifact preserves all registered projects and cross-project
+relations for Graph, Doctor, Context, Goal, and MCP consumers. Each project
+reference carries source and projection hashes, summary counts, a bounded query,
+and a portable canonical URI; it does not duplicate graph entities or proofs.
+Nested and external projects follow the same rule. Any publication failure
+restores the model, aggregate, and all project reference preimages together.
+
 The Knowledge Graph is consumed by:
 
 - `workspace graph search|entities|evidence|path|overlay`;
@@ -385,8 +453,12 @@ The Knowledge Graph is consumed by:
   topology, rich graph, and quality summary in one response.
 
 The complete graph is an interchange artifact, not a prompt. Agents should
-start with `INDEX.json`, use bounded search, then retrieve evidence or a path
-for the selected result.
+start with compact project context, use bounded search, then retrieve evidence
+or a path for the selected result. Generated `project-context-agent.json`,
+`agent-entry.v1.json`, and bootstrap receipts expose a small project graph
+reference separately from the `workspace:` aggregate. Bootstrap schema-validates
+the reference and compares its projection hash with a fresh projection of the
+aggregate before it allows architecture claims. The complete graph is stored once.
 
 ### Interchange and visualization
 
@@ -451,12 +523,38 @@ hashes. Query indexes are cached per immutable graph object; replacing the graph
 is the in-memory invalidation boundary. Across CLI processes, compatible
 persisted read queries validate the live Git/Merkle fingerprint before reuse.
 `workspace model --cache` and `--incremental` avoid unnecessary model/project
-work when inputs are unchanged.
+work when inputs are unchanged. Full, cached, and incremental builds use the
+same project-discovery contract, including adopted/imported projects and
+projects declared only through a workspace contract `externalPath`. Manifest
+or source changes under an external project therefore invalidate the same
+signatures as equivalent in-workspace projects.
 
 Use full graph export for interchange or offline analysis. Use bounded search
 for interactive agents. The latter keeps response size proportional to the
 question instead of workspace size.
 
+### Runtime-generated API topology
+
+When an authored API contract is wired through framework registration or
+configuration rather than a literal route handler, the
+`dynamic-api-registration-binding` provider creates a proof-backed
+`runtime-unit -> implements -> api` relation. Detection is runtime-specific,
+production-only, filename-aware for routing configuration, and bounded per API.
+It intentionally does not claim endpoint implementation: endpoint coverage
+remains unknown until a method/path or operation-id binding is proven. Consumers
+can distinguish the two guarantees through `bindingCoverage.apiRuntimeRegistration`
+and `bindingCoverage.apiImplementation`.
+
+Runtime-registration eligibility is explicit. Network and event contracts such
+as OpenAPI, server-root GraphQL schemas, AsyncAPI, and authored workspace API
+contracts participate; command palettes, console scripts, chat participants,
+shared protocol identities, and client GraphQL operations do not. GraphQL query,
+mutation, subscription, and fragment documents are modeled as proof-backed
+symbols that consume the GraphQL protocol. Only an authored root `schema` or
+non-extension `Query`, `Mutation`, or `Subscription` type establishes a
+runtime-served GraphQL API. This prevents client-heavy repositories from
+inflating API registration unknowns while preserving their operation topology.
+
 ## Measuring retrieval payload reduction
 
 Workspai does not publish an unqualified “N× fewer tokens” claim. Such a claim
@@ -469,6 +567,10 @@ Measure the current workspace instead:
 npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json
 ```
 
+Use `--kind <entity-kind>` with search when the task requires a precise
+semantic surface, for example `--kind runtime-unit` for dynamic registration
+units or `--kind endpoint` for authored operations.
+
 The report compares the readable, proof-indexed source corpus with the bounded
 search payload using a clearly labelled `characters / 4` token estimate. It
 reports corpus size, retrieval size, estimated ratio, percentage reduction,
@@ -497,6 +599,8 @@ a general performance claim.
 - The live-input fingerprint enables whole-graph snapshot reuse; it is not yet
   a per-file incremental graph rebuild or a hosted semantic-vector index.
 - Compiler/LSP-grade symbol resolution belongs in deeper language providers.
+- Runtime registration evidence proves that an API enters the running topology;
+  it does not prove that every authored operation has a reachable handler.
 - Missing project edges mean “relationship not proven,” not “projects are
   independent.” Author service contracts or provide API/package/runtime
   evidence to close that gap.