workspai 0.49.0 → 0.50.0

package/docs/doctor-command.md

@@ -34,7 +34,8 @@ Checks:
 - all system checks
 - workspace marker resolution
 - project discovery and per-project health
-- dependency/env readiness by project type (Python/Node/Go)
+- dependency, environment, test, quality, security, deployment, and coverage readiness per project
+- runtime-native evidence without treating missing scanners as a clean result
 
 > Compatibility note: `npx workspai doctor --workspace` still works, but `doctor workspace` is the canonical form.
 
@@ -53,6 +54,8 @@ Checks:
 - dependency/env readiness for the selected project
 - enterprise probes (config contract, migration surface, runtime health surface)
 - score explainability breakdown for audit trails
+- normalized dependency-audit and test-coverage evidence for CI, IDEs, and agents
+- graph-aware root, impact-candidate, proof-path, and verification-target context
 
 > Compatibility note: `npx workspai doctor --project` also works.
 
@@ -84,6 +87,108 @@ npx workspai doctor project --json
 npx workspai doctor workspace --profile enterprise-strict --json
 ```
 
+## One verdict, backed by every probe
+
+Doctor calculates one verdict from the host and every project probe:
+
+- **Passed** means no blocking probe failed.
+- **Needs attention** means the current profile found advisory work.
+- **Blocked** means at least one error-level probe failed.
+
+The score and verdict use the same counts. A failed security, coverage, or
+runtime probe cannot be hidden behind a high percentage or a healthy host. New
+evidence includes the host/project score components and per-project probe
+summary; semantic validation rejects contradictory artifacts before they are
+written. Older v1 evidence remains readable so existing workspaces and IDEs do
+not break during migration.
+
+## Graph-aware diagnosis
+
+When the project belongs to a workspace with a current model and Knowledge
+Graph, Doctor enriches every warning or failure with evidence-backed structural
+context:
+
+- the package, file, service, deployment, or other graph entity nearest to the
+  finding;
+- reachable APIs, services, infrastructure, owners, and other affected
+  candidates;
+- connected test suites or CI pipelines that can verify the repair;
+- the exact proof path and source artifacts supporting each connection;
+- explicit unknowns when the graph cannot prove an effect or verification path.
+
+Runtime-native dependency audits preserve the affected package names,
+versions, advisory identifiers, and available severity/directness metadata.
+Doctor uses those subjects to select the corresponding package or module
+entity in the current project's graph neighborhood. If an audit names a
+dependency that the graph cannot resolve, the diagnosis reports it under
+`unresolvedSubjects`; it does not silently attach the finding to an unrelated
+package.
+
+This data is available under `project.graphDiagnosis` in project and workspace
+Doctor JSON evidence. Doctor rejects stale, invalid, or model-unbound graph
+evidence instead of presenting it as current.
+
+Graph reachability is deliberately described as a **structural impact
+candidate**, not runtime causality. It narrows investigation and gives Studio a
+proof-carrying starting point; final verification still comes from the
+runtime-owned checks.
+
+## Multi-runtime dependency evidence
+
+Doctor selects the audit adapter from the detected runtime and lockfile:
+
+| Ecosystem                            | Runtime-native evidence                                            |
+| ------------------------------------ | ------------------------------------------------------------------ |
+| npm                                  | npm, pnpm, Yarn Classic/Berry, Bun, or Deno audit                  |
+| Python                               | `pip-audit` through the project virtual environment when available |
+| Go                                   | `govulncheck`                                                      |
+| Rust                                 | `cargo audit`                                                      |
+| PHP                                  | `composer audit`                                                   |
+| Ruby                                 | `bundler-audit`                                                    |
+| .NET                                 | vulnerable transitive package report                               |
+| Elixir                               | `mix hex.audit`                                                    |
+| Java, Scala, Kotlin, Clojure, C, C++ | project/organization-owned scanner contract                        |
+
+Every result records the exact executable, arguments, ecosystem, severity
+counts, and limitations. A missing tool, timeout, registry failure,
+unparseable response, or unsupported zero-configuration workflow is explicit
+evidence—not a zero-vulnerability result. Compatible automatic fixes never use
+force; unresolved findings move to a targeted upgrade and verification plan.
+
+## Coverage goals that Doctor can verify
+
+Generate a normalized baseline from the current project:
+
+```bash
+npx workspai project coverage --run --target 80 --strict --json
+```
+
+Workspai detects the runtime-owned runner, reads machine-readable coverage, and
+normalizes lines, branches, functions, statements, low-coverage files, source
+hash, and the requested target. It understands Istanbul/LCOV, coverage.py,
+Go coverprofiles, JaCoCo/Cobertura/Clover, scoverage, SimpleCov, and LLVM
+coverage. Runtime plans cover Node/Bun/Deno, Python, Go, JVM, .NET, Rust, PHP,
+Ruby, Elixir, Clojure, Scala, Kotlin, C, and C++; if a project-owned runner does
+not emit one of those portable formats, the result is explicitly `unavailable`
+with setup guidance rather than an invented percentage.
+
+Doctor consumes the resulting
+`.workspai/reports/project-test-coverage-last-run.json`. If it is missing,
+below target, unavailable, or failed, the probe tells Studio what evidence to
+generate or which low-coverage source paths need source-aware tests. The repair
+contract explicitly forbids lowering the target, excluding difficult files,
+skipping tests, or removing assertions to manufacture a pass.
+
+When the project belongs to a workspace, Workspai also writes:
+
+```text
+<workspace>/.workspai/reports/project-test-coverage-last-run.json
+<workspace>/.workspai/reports/projects/<slug>--<hash>/project-test-coverage-last-run.json
+```
+
+The same namespaced layout is used for project Doctor evidence, preventing
+same-name projects from overwriting each other.
+
 ## Enterprise Fix Pipeline
 
 Doctor supports policy profiles so the same evidence can be interpreted correctly in local,
@@ -283,15 +388,17 @@ change is safe enough for Doctor to apply with approval and post-fix verificatio
 
 Runtime-native probes add a second layer on top of the generic surface checks:
 
-| Runtime family | Native signals sampled by Doctor                                      |
-| -------------- | --------------------------------------------------------------------- |
-| Node/Bun/Deno  | test runners, ESLint/Prettier/Biome markers, audit script/tooling     |
-| Python         | pytest/tox/nox, Ruff/Black/Mypy, pip-audit/Safety/Bandit markers      |
-| Go             | `*_test.go`, golangci-lint/Makefile quality, govulncheck/gosec hints  |
-| Java           | Maven/Gradle tests, Checkstyle/Spotless/PMD, OWASP dependency checks  |
-| .NET           | test projects, `.editorconfig`, NuGet audit and vulnerable checks     |
-| Rust           | test/Cargo markers, rustfmt/clippy, cargo-audit hints                 |
-| PHP/Ruby/etc.  | PHPUnit/Pint/PHPStan, RSpec/RuboCop/Bundler-audit and ecosystem hints |
+| Runtime family    | Native signals sampled by Doctor                                                 |
+| ----------------- | -------------------------------------------------------------------------------- |
+| Node/Bun/Deno     | Jest/Vitest/native tests, ESLint/Prettier/Biome, package-manager audit           |
+| Python            | pytest/tox/nox, Ruff/Black/Mypy, pip-audit/Safety/Bandit                         |
+| Go                | `*_test.go`, golangci-lint, govulncheck/gosec                                    |
+| Java/Kotlin/Scala | Maven/Gradle/sbt tests, Checkstyle/Spotless/Detekt/Scalafmt, declared JVM audit  |
+| .NET              | test projects, `.editorconfig`, NuGet audit                                      |
+| Rust              | Cargo tests, rustfmt/clippy, cargo-audit                                         |
+| PHP/Ruby          | PHPUnit/Pest/PHPStan and RSpec/Minitest/RuboCop/Bundler-audit                    |
+| Elixir/Clojure    | ExUnit/Credo/Hex and clojure.test/Kaocha/clj-kondo                               |
+| C/C++             | CTest/native test markers, clang tooling, declared SBOM or vulnerability scanner |
 
 ## CI Example
 
@@ -460,7 +567,7 @@ Legacy evidence without `schemaVersion` is still accepted. Unknown versions are
 
 ```bash
 npx workspai bootstrap [--profile <profile>]
-npx workspai setup <python|node|go|java|dotnet> [--warm-deps]
+npx workspai setup <python|node|go|java|dotnet|rust|php> [--warm-deps]
 npx workspai workspace list
 npx workspai cache <status|clear|prune|repair>
 npx workspai mirror <status|sync|verify|rotate>

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

@@ -32,7 +32,10 @@ flowchart TB
 1. **Connect your software.** Create something new, adopt an existing project
    without moving it, or import a repository.
 2. **Understand the workspace.** Workspai builds one model of the projects and
-   how they relate.
+   how they relate. That Workspace Model is canonical. Workspai then derives a
+   proof-backed Knowledge Graph from the model-owned project inventory so tools
+   can query files, APIs, packages, infrastructure, tests, ownership, and
+   decisions without creating a second source of truth.
 3. **Understand change and verify it.** Workspai shows affected areas and checks
    the evidence needed for a safe decision.
 4. **Share the result.** Developers, CI, IDEs, AI agents, and MCP clients consume

package/docs/graph-benchmark-methodology.md

@@ -27,8 +27,8 @@ The result conforms to
 It records:
 
 - the query and result limit;
-- the graph schema, entity/relation/proof counts, source artifact, and source
-  model SHA-256;
+- the graph schema, entity/relation/proof counts, source artifact, and stable
+  structural model SHA-256;
 - the number and size of readable, deduplicated proof-source artifacts;
 - the bounded retrieval size and match count;
 - unreadable artifacts rather than silently excluding them;

package/docs/workspace-intelligence-evaluation.md

@@ -94,6 +94,7 @@ Event bodies conform to
 ```bash
 npx workspai workspace eval status --json
 npx workspai workspace eval report --json
+npx workspai workspace eval report --output ./evidence/my-evaluation.json --json
 ```
 
 Finalization writes:
@@ -102,6 +103,10 @@ Finalization writes:
 .workspai/reports/workspace-intelligence-evaluation-last-run.json
 ```
 
+`--output` keeps that governed last-run artifact and also copies the finalized
+report to the requested workspace-relative or absolute path. JSON output reports
+the path that was actually requested, so automation does not need to infer it.
+
 Both live and final reports conform to
 [`workspace-intelligence-evaluation.v1.json`](../contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json).
 

package/docs/workspace-knowledge-graph.md

@@ -138,13 +138,79 @@ CLI queries · Context · MCP · Agents · IDEs · CI
 ```
 
 The graph does not rewrite or replace the canonical Workspace Model. It is a
-derived representation bound to an exact model revision by SHA-256. Context and
-MCP consumers reject a graph whose source hash no longer matches the model.
+derived representation bound to an exact model revision by the SHA-256 hash of
+the model's stable structural projection. Volatile timestamps, run correlation,
+live evidence references, and freshness fields are intentionally excluded from
+that structural identity. Context, Doctor, MCP, and graph-stream consumers
+reject a graph whose source binding no longer matches the current model.
 
-The model also contains a smaller project dependency graph. That projection is
-used for impact, blast radius, verify, explain, watch, and affected fleet runs.
-The richer Knowledge Graph is used for proof-backed retrieval and cross-domain
-understanding.
+### Model and graph relationship
+
+The current integrated CLI follows this order:
+
+```text
+workspace files + registered projects + contracts + selected evidence
+                              |
+                              v
+                 canonical Workspace Model
+                    |                 |
+                    |                 +-- compact project dependency topology
+                    |
+                    v
+       provider scan + facts/proofs + identity reconciliation
+                              |
+                              v
+                  Workspace Knowledge Graph
+```
+
+The model owns the canonical workspace boundary: project identity, runtime and
+framework observations, policies, contract state, evidence references, and the
+compact project topology used by the intelligence loop. The Knowledge Graph
+receives that project inventory and topology, then enriches it from bounded
+source providers. It can add files, symbols, packages, APIs, infrastructure,
+tests, owners, decisions, and proof-carrying relations, but it cannot mutate the
+model that authorized the build.
+
+The canonical project inventory reconciles filesystem discovery, imported and
+adopted registries, and `workspace.contract.json` declarations. A project that
+is still declared by the contract but missing on disk is preserved in the
+model and reported as `project.path.missing`; it is never silently removed from
+the graph boundary. A persisted Knowledge Graph is accepted only when its
+workspace identity and project topology also match that model.
+
+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
+`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
+reject the graph when that binding no longer matches `workspace-model.json`.
+
+This is therefore not a circular source-of-truth relationship. In the current
+CLI, the direction is **Model → Knowledge Graph**. Providers may use the same
+workspace sources that informed the model, but their output enriches the
+derived graph; it does not flow back into the model during that run. A future
+fact-first package may make normalized facts the shared input to both
+representations, but that is not the shipped contract today.
+
+The model also contains a smaller project dependency graph under the canonical
+`projectTopology` field. That projection is used for impact, blast radius,
+verify, explain, watch, and affected fleet runs. The richer Knowledge Graph is
+used for proof-backed retrieval and cross-domain understanding. The deprecated
+`graph` field is emitted only as a v1 compatibility alias and must remain
+structurally identical to `projectTopology`; new consumers must not depend on
+the alias.
+
+These rules are machine-owned, not Markdown conventions:
+
+- `workspace-intelligence-architecture.v1.json` declares the one-way direction,
+  artifact authority, mutation rule, publication rule, and stale-consumer rule;
+- `workspace-knowledge-graph.v1.json` permits only the canonical model source
+  kind and artifact path;
+- `workspace-intelligence-chain.v1.json` requires the Model stage to produce
+  both artifacts;
+- runtime source-binding guards enforce the structural hash before persisted
+  graph consumption.
 
 ## Sources and providers
 
@@ -161,9 +227,32 @@ deduplication, typed relations, reconciliation, quality metrics, diagnostics,
 and deterministic ordering. Regex-backed source observations are explicitly
 marked as observed/medium-confidence; authored contracts remain authoritative.
 
+Local source imports are resolved to indexed file entities when the target can
+be proven. External packages remain module entities, while unresolved relative
+imports are labelled `unresolved-local` and produce a diagnostic. This prevents
+an unknown local path from being silently presented as a third-party
+dependency.
+
+### Binding quality, not just graph size
+
+Entity and relation counts do not tell you whether a graph can answer useful
+engineering questions. `graph.quality.bindingCoverage` therefore reports four
+independent dimensions:
+
+- authored or observed endpoints connected to implementation evidence;
+- registered projects connected to test evidence;
+- registered projects connected to deployment evidence;
+- registered projects connected to ownership evidence.
+
+Each dimension reports eligible, bound, and unknown counts plus a ratio. A
+`null` ratio means the dimension was not applicable; zero means applicable
+surfaces were found but none were bound. Consumers must not turn either state
+into a false “complete” claim.
+
 ## Outputs and consumers
 
-`workspace model --write` publishes these two artifacts atomically:
+`workspace model --write` publishes these two artifacts as one locked,
+rollback-capable artifact set:
 
 ```text
 .workspai/reports/workspace-model.json
@@ -173,6 +262,12 @@ marked as observed/medium-confidence; authored contracts remain authoritative.
 The Knowledge Graph is consumed by:
 
 - `workspace graph search|entities|evidence|path|overlay`;
+- `doctor workspace|project`, which maps unresolved probes to structural root
+  candidates, reachable affected surfaces, proof paths, and graph-connected
+  test/pipeline verification targets. When a runtime audit names affected
+  dependencies, Doctor binds those subjects to exact package/module entities
+  instead of selecting an arbitrary project package. Names that cannot be
+  resolved remain explicit unknowns;
 - `workspace context`, which validates the model hash and publishes graph
   availability and query commands;
 - `workspace agent-sync`, which places it in the evidence index and generated

package/docs/workspace-operations.md

@@ -6,12 +6,23 @@ operation changes before you run it.
 
 Command syntax: [commands-reference.md](./commands-reference.md).
 
-## Import and adoption
+## Choose the operation by intent
 
-Use `import` to copy or clone an existing project into a Workspai workspace.
-Use `adopt` when the project must stay where it already lives but should become
-visible to Workspai. In both cases, the project becomes part of the shared
-system map, checks, and AI context.
+Workspai keeps project onboarding and workspace portability separate. Choose
+the operation by what should happen to the source:
+
+| Resource  | Source           | Intent                       | Command                      | Source moved or copied? | Registered? |
+| --------- | ---------------- | ---------------------------- | ---------------------------- | ----------------------- | ----------- |
+| Project   | Local folder     | Keep the project where it is | `workspai adopt`             | No                      | Yes         |
+| Project   | Local folder     | Copy it into a workspace     | `workspai import`            | Copied                  | Yes         |
+| Project   | Git URL          | Clone it into a workspace    | `workspai import --git`      | Cloned                  | Yes         |
+| Workspace | Existing folder  | Use it where it is           | `workspai workspace connect` | No                      | Yes         |
+| Workspace | Portable archive | Restore and start using it   | `workspai workspace import`  | Materialized            | Yes         |
+| Workspace | Portable archive | Extract files only           | `workspai workspace hydrate` | Materialized            | No          |
+
+All registered routes reconcile the canonical registry, workspace contract,
+and project entry surfaces. `hydrate` deliberately stops after safe extraction
+so automation can inspect the materialized files before registration.
 
 RapidKit Core module commands remain available only when existing project
 metadata identifies a kit that supports modules.
@@ -22,6 +33,8 @@ npx workspai import https://github.com/acme/orders-api.git --git
 npx workspai import ../orders-api --workspace ./my-workspace --name orders-api --json
 npx workspai adopt ../marketing-web --workspace ./my-workspace
 npx workspai adopt --json
+npx workspai workspace connect ../existing-workspace --json
+npx workspai workspace import team.workspai-archive.zip --output ./team --json
 ```
 
 ### Import behavior
@@ -29,8 +42,9 @@ npx workspai adopt --json
 - Local folders are copied; git sources are cloned with shallow history.
 - Outside any workspace (no `--workspace`), Workspai creates or reuses the managed `workspai` workspace. New defaults use `~/.workspai/workspaces/workspai`; valid legacy candidates under `~/rapidkit/workspaces/workspai` and `~/Workspai/rapidkits/workspai` can still be reused.
 - Existing workspaces under legacy managed roots remain registered after upgrade.
-- CLI prints the exact next `cd ...` step. JSON mode returns the same value as
-  `suggestedCdCommand`.
+- Workspai writes a validated machine-local workspace binding into the
+  imported project. Workspace commands can then be launched from that project
+  without changing directories.
 - Failed workspace sync rolls back imported files and registry entries.
 
 ### Adopt behavior
@@ -39,14 +53,107 @@ npx workspai adopt --json
 - Default workspace resolution matches import, including canonical creation and valid legacy managed-default reuse.
 - Writes `.workspai/project.json`, `.workspai/adopt.json`, and `.workspai/adopt-readiness.json`.
 - Registry and contract sync include adopted projects for `workspace model`, `workspace context`, Dashboard, and agents.
+- Managed grounding writes a portable project lens, project grounding, and a
+  bounded managed section in `AGENTS.md`. User-authored `AGENTS.md` content is
+  preserved.
 - `--dry-run --json` previews detection without writing metadata.
 
+### Existing workspace behavior
+
+- `workspace connect` registers a valid local Workspai workspace in place. It
+  does not copy its projects.
+- `workspace import` verifies an archive, materializes it atomically, removes
+  machine-local bindings from the source machine, registers the workspace, and
+  reconciles its portable contract snapshot and project entry links.
+- Archive import never silently overwrites an explicit `--output` destination.
+- External adopted projects are not copied into an archive. The manifest keeps
+  only their portable identity and reports that they must be relinked.
+- `workspace hydrate` is the lower-level extraction primitive. Use it when a
+  deployment or migration process—not Workspai—owns registration.
+
+Every registered onboarding route emits the same versioned ingestion plan in
+JSON. The plan states the resource, source kind, materialization mode,
+ownership, registration intent, destination, and grounding policy. Consumers
+should use that contract instead of inferring behavior from command names.
+`workspace hydrate` remains an unregistered archive primitive and emits the
+versioned archive operation result instead.
+
+### Automatic consumer sync
+
+Workspace creation publishes the initial contract, canonical model, Knowledge
+Graph, structural baseline, context, report index, `AGENTS.md`, operational
+skills, and supported IDE/agent surfaces—even before the first project exists.
+Successful project creation, adoption, import, workspace connection, and
+workspace import refresh those same projections in the background. The
+structural baseline is created once and preserved; current model, graph, diff,
+impact, context, and project grounding move forward with workspace membership.
+
+Doctor, Analyze, Readiness, and Verify remain explicit checks because they may
+run project tools or enforce release policy. Use `workspace intelligence run`
+when you want that governed decision chain, rather than only lifecycle sync.
+
+### Work from the project directory
+
+After `adopt`, `import`, or project creation, the project is a first-class
+entry point into its canonical workspace:
+
+```bash
+cd /absolute/path/to/project
+npx workspai project workspace status --json
+npx workspai doctor project --json
+npx workspai workspace graph search "authentication endpoint" --limit 12 --json
+npx workspai workspace intelligence run --for-agent generic --strict --json
+```
+
+Workspace resolution has one stable precedence:
+`--workspace` → parent workspace → validated local link → reverse registry.
+Workspai returns a specific error for an invalid explicit workspace, malformed
+or stale link, ambiguous registration, or an unlinked project. It never picks
+one workspace silently when ownership is ambiguous.
+
+The project receives four distinct surfaces:
+
+| File                                           | Purpose                                                                       | Portable              |
+| ---------------------------------------------- | ----------------------------------------------------------------------------- | --------------------- |
+| `.workspai/workspace-link.local.json`          | Machine-local canonical workspace binding                                     | No; always gitignored |
+| `.workspai/reports/project-context-agent.json` | Bounded project view of model, graph, proofs, diagnostics, and safe commands  | Yes                   |
+| `.workspai/PROJECT-GROUNDING.md`               | Human- and agent-readable project entry guide                                 | Yes                   |
+| `AGENTS.md` managed section                    | Tells compatible agents where to start and when to cross the project boundary | Yes                   |
+
+The bounded context includes project identity and commands, dependencies and
+dependents, related API/deployment/test surfaces, current project findings,
+portable proof locators, and model/graph freshness. It deliberately references
+rather than duplicates workspace-wide evidence.
+
+Use `--project-grounding managed` (default) to publish all portable surfaces,
+`local` to keep the project lens and grounding gitignored without managing
+`AGENTS.md`, or `off` to disable project grounding for that operation. The
+machine-local link remains enabled in every mode because it owns command
+resolution; it is private to the current machine and never belongs in a commit.
+Mode reconciliation is convergent: changing modes removes stale managed
+sections, portable files, or ignore rules that the new mode no longer owns,
+while preserving user-authored `AGENTS.md` and `.gitignore` content.
+
+If a workspace moved, or a cloned project has no valid local link, reconcile
+it explicitly:
+
+```bash
+npx workspai project workspace relink --workspace /absolute/path/to/my-workspace --json
+```
+
+Relink succeeds only when the project is already a member of the canonical
+workspace contract.
+
 ### JSON output (`--json`)
 
-- Import returns `workspacePath`, `workspaceResolution`, `defaultWorkspaceCreated`, `suggestedCdCommand`, and `importedProject`. The imported project includes its `source`.
+- Import returns `workspacePath`, `workspaceResolution`,
+  `defaultWorkspaceCreated`, `projectWorkspaceCommand`,
+  `commandsResolveWorkspaceFromProject`, and `importedProject`. The imported
+  project includes its `source`.
 - Adopt returns `workspacePath`, `workspaceResolution`,
   `defaultWorkspaceCreated`, `wouldCreateDefaultWorkspace`,
-  `suggestedCdCommand`, `dryRun`, and `adoptedProject`.
+  `projectWorkspaceCommand`, `commandsResolveWorkspaceFromProject`, `dryRun`,
+  and `adoptedProject`.
 - Project results include detected `name`, `path`, `stack`, `runtime`, `framework`, `supportTier`, `moduleSupport`, and `confidence` where available.
 
 Imported projects receive `.workspai/import-readiness.json`. Adopted projects add frontend-aware detection for Next.js, React, Vite, Vue, Angular, SvelteKit, Nuxt, Astro, Remix, and Solid.
@@ -137,6 +244,20 @@ queryable through the read-mostly MCP server. This keeps CLI, CI, IDE and agent
 consumers on one contract revision without injecting the full graph into every
 agent prompt.
 
+The relationship is one-way and contract-enforced: the Workspace Model owns the
+canonical project boundary and compact dependency topology in
+`workspace-model.json.projectTopology`; providers enrich
+that inventory into the Knowledge Graph. The graph source kind and artifact
+path are fixed to the model, its source hash identifies the stable structural
+model projection, and persisted current-state consumers reject a mismatched
+graph. `workspace contract graph` follows the same model-first build path; it
+does not create a competing contract- or source-owned Knowledge Graph.
+
+The deprecated `workspace-model.json.graph` field is a temporary v1
+compatibility alias. It is emitted with the same value as `projectTopology`,
+excluded as a duplicate from the canonical hash, and rejected when the two
+fields diverge. New integrations must consume `projectTopology`.
+
 The overlay follows
 `workspace-knowledge-graph-change-overlay.v1`: graph revisions are identified
 by content-derived fingerprints (timestamps do not create false changes), and
@@ -168,9 +289,21 @@ npx workspai workspace archive inspect team-workspace.workspai-archive.zip
 npx workspai workspace archive verify team-workspace.workspai-archive.zip --strict
 npx workspai workspace archive doctor team-workspace.workspai-archive.zip
 npx workspai workspace hydrate team-workspace.workspai-archive.zip --output ./team-workspace
+npx workspai workspace import team-workspace.workspai-archive.zip --output ./team-workspace
+npx workspai workspace connect /path/to/existing-workspace
 ```
 
-Export excludes dependency folders, build output, git history, logs, `.env`, and private keys by default. Use `--include-env` only for trusted internal handoffs. Hydrate accepts legacy `.rapidkit-workspace` and `.rapidkit/*` archive entries, but restores them as canonical `.workspai-workspace` and `.workspai/*` paths.
+Export excludes dependency folders, build output, git history, logs, `.env`,
+private keys, machine-local project links, derived registries, and raw
+absolute-path workspace contracts by default. The manifest carries a
+path-neutral contract snapshot so manual ports, APIs, ownership, events, and
+dependency declarations survive transfer. External projects and their absolute
+paths are excluded and reported as explicit relink actions. Use `--include-env`
+only for trusted internal handoffs. Hydrate accepts legacy
+`.rapidkit-workspace` and `.rapidkit/*` archive entries, but restores them as
+canonical `.workspai-workspace` and `.workspai/*` paths. Workspace import then
+reconciles the portable snapshot with project metadata on the destination
+machine and rebuilds machine-local bindings.
 
 Archive export, verification, and hydrate stream file payloads instead of loading the workspace into memory. Exports use ZIP64, so multi-gigabyte workspaces and archives with more than 65,535 files are supported. Stored ZIP entries are the default; use `--archive-compression deflate` when transfer size matters more than export CPU time.
 
@@ -228,6 +361,9 @@ Artifacts:
 | `autopilot release`                                         | Wrapper orchestrator   | End-to-end release gate evidence                   |
 | `import`                                                    | Workspace ingestion    | Rollback-safe sync                                 |
 | `adopt`                                                     | Workspace adoption     | In-place linking + registry sync                   |
+| `workspace connect`                                         | Workspace ingestion    | In-place workspace registration + reconciliation   |
+| `workspace import`                                          | Workspace ingestion    | Verified archive restore + registration            |
+| `workspace hydrate`                                         | Archive primitive      | Verified extraction without registration           |
 | `workspace model/context/diff/impact/verify`                | Workspace intelligence | Model, context packs, blast radius                 |
 | `workspace intelligence run`                                | Workspace intelligence | Canonical contract-backed chain and strict gate    |
 | `snapshot`                                                  | Workspace recovery     | Metadata or full snapshots                         |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workspai",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "type": "module",
   "description": "Open-source workspace intelligence CLI for software systems: create, adopt, govern, verify, and align polyglot workspaces for humans, CI, IDEs, and AI agents.",
   "keywords": [
@@ -95,7 +95,7 @@
     "validate:contracts": "corepack npm run check:shared-contracts && vitest run src/__tests__/contracts/",
     "test:parity-contract": "corepack npm run check:shared-contracts && vitest run src/__tests__/contracts/import-stack-parity.snapshot.test.ts",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage --reporter=default --reporter=json --outputFile.json=test-results/vitest.json",
+    "test:coverage": "corepack npm run test:prebuild && vitest run --coverage --reporter=default --reporter=json --outputFile.json=test-results/vitest.json",
     "test:prepare-embeddings": "node scripts/prepare-mock-embeddings.mjs",
     "generate-embeddings": "npx tsx src/ai/generate-embeddings.ts",
     "verify:package-cli": "node scripts/verify-package-cli.mjs",

package/scripts/enterprise-package-smoke.mjs

@@ -8,6 +8,11 @@ import process from 'node:process';
 
 const repoRoot = process.cwd();
 const cliPath = path.join(repoRoot, 'dist', 'index.js');
+const isolatedHome = fs.mkdtempSync(path.join(os.tmpdir(), 'workspai-enterprise-home-'));
+
+process.on('exit', () => {
+  fs.rmSync(isolatedHome, { recursive: true, force: true });
+});
 
 function fail(message) {
   console.error(`[enterprise-package-smoke] ${message}`);
@@ -19,7 +24,14 @@ function log(message) {
 }
 
 function cliEnv(extraEnv = {}) {
-  const env = { ...process.env, ...extraEnv };
+  const env = {
+    ...process.env,
+    HOME: isolatedHome,
+    USERPROFILE: isolatedHome,
+    XDG_CONFIG_HOME: path.join(isolatedHome, '.config'),
+    XDG_CACHE_HOME: path.join(isolatedHome, '.cache'),
+    ...extraEnv,
+  };
   delete env.NODE_ENV;
   delete env.NODE_OPTIONS;
   for (const key of Object.keys(env)) {

package/dist/analyze-EEEU3MIF.js

@@ -1 +0,0 @@
-export{b as printAnalyzeReport,a as runAnalyze}from'./chunk-54EP5CEV.js';

package/dist/autopilot-release-R4XRTWEM.js

@@ -1 +0,0 @@
-export{b as AUTOPILOT_RELEASE_ALIAS_FILENAME,a as AUTOPILOT_RELEASE_LAST_RUN_FILENAME,c as runAutopilotRelease}from'./chunk-K4X3DM7R.js';

package/dist/chunk-22DT744Z.js

@@ -1 +0,0 @@
-import {c,d,a,b}from'./chunk-5XATWNME.js';import s from'fs';import o from'path';function R(i){let n=o.resolve(i);for(;;){if(s.existsSync(o.join(n,c))||s.existsSync(o.join(n,d))||s.existsSync(o.join(n,a,"workspace.json"))||s.existsSync(o.join(n,b,"workspace.json")))return n;let r=o.dirname(n);if(r===n)return null;n=r;}}function l(i){let n=o.resolve(i),r=s.existsSync(o.join(n,c))||s.existsSync(o.join(n,d))||s.existsSync(o.join(n,a,"workspace.json"))||s.existsSync(o.join(n,b,"workspace.json")),p=s.existsSync(o.join(n,a,"project.json"))||s.existsSync(o.join(n,a,"context.json"))||s.existsSync(o.join(n,b,"project.json"))||s.existsSync(o.join(n,b,"context.json"));return r&&!p}export{R as a,l as b};