# Workspace Operations

Use this guide to bring existing software into Workspai, move or share workspace
state safely, and manage supporting local services. It explains what each
operation changes before you run it.

Command syntax: [commands-reference.md](./commands-reference.md).

## Choose the operation by intent

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.

```bash
npx workspai import ../orders-api
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

- 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.
- 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

- Source files are not moved or copied.
- An interactive adopt outside every workspace offers the managed default or,
  only when the direct parent contains exactly the project being adopted,
  turning that parent into a workspace. Parent bootstrap is the recommended
  choice in that narrowly safe case.
- Non-interactive and `--json` callers keep the existing managed-default
  behavior unless they pass `--workspace` explicitly.
- `--workspace <path>` adopts into an existing valid Workspai workspace. An
  existing empty directory is bootstrapped first; a non-empty directory that
  is not already a valid workspace is rejected without modification.
- The project directory itself is never converted into its own workspace.
- 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`. It also publishes the portable agent
  entry manifest and host adapters. User-authored instruction content and
  symbolic links are preserved, and an authored tracked deletion is never
  resurrected.
- `--dry-run --json` previews detection without writing metadata. Its versioned
  `adoptedProject.effects` record also declares project metadata files,
  conditional `.gitignore`/`AGENTS.md` reconciliation, and the registration,
  contract, model, graph, and agent-grounding operations that a real run would
  perform.

### 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, profile-aware `README.md`,
`AGENTS.md`, applicable operational skills, and supported IDE/agent surfaces—even before
the first project exists. The README's Workspai-managed section shows the
current profile, project count, canonical intelligence loop, and consumer entry
points while preserving user-authored content. Successful project creation,
adoption, import, workspace connection, and workspace import refresh those same
projections in the background. The structural baseline is created once and
preserved; current model, graph, diff, impact, context, README, and project
grounding move forward with workspace membership.

Operational Skill generation is evidence-driven. Release readiness remains
available at workspace scope, while API, schema, dependency, contract, runtime,
test, delivery, and polyglot playbooks are emitted only for matching projects.
`.workspai/reports/workspace-skills-index.json` records both generated and
suppressed candidates, including the signals behind each decision. This keeps
agent discovery useful without claiming capabilities the repository does not
have.

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 agent bootstrap --for-agent codex --json
npx workspai doctor workspace --json=summary
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 seven complementary surfaces. They are different views of
one canonical workspace binding, not seven copies of the model or graph:

| File                                                       | Purpose                                                                        | Portable              |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------- |
| `.workspai/workspace-link.local.json`                      | Machine-local canonical workspace binding                                      | No; always gitignored |
| `.workspai/agent-entry.v1.json`                            | Versioned host coverage, read order, authority boundaries, and integrity proof | Yes                   |
| `.workspai/reports/project-context-agent.json`             | Bounded project view of model, graph, proofs, diagnostics, and safe commands   | Yes                   |
| `.workspai/reports/project-knowledge-graph-reference.json` | Integrity-bound locator for the canonical project graph projection             | Yes                   |
| `.workspai/PROJECT-GROUNDING.md`                           | Human- and agent-readable project entry guide                                  | Yes                   |
| `.agents/skills/workspai-*/SKILL.md`                       | Native project Skill wrappers for canonical workspace playbooks                | Yes                   |
| `AGENTS.md` and host adapters                              | Route supported hosts to the same canonical-first bootstrap                    | 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.

Representative graph entities are selected with a stratified round-robin
budget, so a large early-sorted kind cannot hide later architectural kinds.
`intelligence.projection` records the entity and byte budgets, selected and
omitted counts per kind, and the scoped graph-search command for retrieving
anything outside the lens. Aggregate counts in the lens remain exhaustive.

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.

Run `project agent-entry verify --for-agent all --strict --json` to audit every
host projection. See [Canonical-first agent entry](./agent-entry.md) for status,
freshness, privacy, and consumer rules.

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`, `projectWorkspaceCommand`,
  `commandsResolveWorkspaceFromProject`, and `importedProject`. The imported
  project includes its `source`.
- Adopt returns `workspacePath`, `workspaceResolution`,
  `defaultWorkspaceCreated`, `workspaceBootstrapped`,
  `wouldCreateDefaultWorkspace`, `wouldBootstrapWorkspace`,
  `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.

## Workspace snapshots and safe project operations

```bash
npx workspai snapshot create before-upgrade --reason "before dependency upgrade"
npx workspai snapshot list
npx workspai snapshot inspect before-upgrade
npx workspai snapshot restore before-upgrade --dry-run
npx workspai snapshot restore before-upgrade --force
```

Project delete is safe-by-default:

```bash
npx workspai project archive orders-api --reason "replaced by orders-v2"
npx workspai project archives
npx workspai project restore orders-api
npx workspai project delete orders-api
npx workspai project delete orders-api --permanent --confirm orders-api
```

Lifecycle safety:

- `project delete` archives by default; permanent removal requires `--permanent --confirm <exact-name>`.
- `snapshot restore` requires `--force` unless dry-run.
- Restore, archive, and permanent delete create pre-operation metadata snapshots.
- Archive manifests live under `.workspai/archive/projects`.
- Audit records append to `.workspai/audit/events.jsonl`.
- Workspace policy can require reasons, safety snapshots, or block permanent delete via `.workspai/policies.yml`.

## Workspace collaboration bundle

```bash
npx workspai workspace share
npx workspai workspace share --output ./team-share.json
npx workspai workspace share --include-paths
npx workspai workspace share --no-doctor
```

Bundle includes workspace metadata, discovered projects, report index, and latest doctor evidence (unless `--no-doctor`). `--include-paths` is for internal teams only (absolute paths).

## Workspace contract registry

```bash
npx workspai workspace contract init
npx workspai workspace contract inspect
npx workspai workspace contract verify --strict
npx workspai workspace contract graph
npx workspai workspace contract graph --output ./contract-graph.json --json
```

Contract file: `.workspai/workspace.contract.json`. Verification checks schema, duplicate slugs, port collisions, and unknown dependencies.

Project entries may also declare governance that lives outside the repository:

```json
{
  "slug": "api",
  "relativePath": "services/api",
  "governance": {
    "ci": { "mode": "external", "provider": "Prow", "reference": "platform/test-infra" },
    "release": { "mode": "external", "provider": "Release Engineering" },
    "ownership": { "mode": "repository" }
  }
}
```

Workspai reconciles each control as `repository`, `external-declared`,
`external-observed`, or `unknown`. Analyze does not misreport an explicitly
external control as a missing repository file. Observed-but-undeclared external
governance stays advisory until the canonical contract names its authority.
The resolved profile is emitted by the Workspace Model, project lens, agent
context, facts, and project graph attributes so every consumer sees the same
truth.

`workspace contract graph --json` preserves its original `nodes`, `edges`, and
summary fields for existing consumers, and now adds an evidence-backed
`dependencyGraph` using the public `workspace-dependency-graph.v1` contract. It
discovers package/workspace dependencies and supported cross-project imports,
records relationship provenance and confidence, and reports graph coverage,
orphans, hotspots, and cycles. Project nodes also expose safe package metadata,
public environment-template keys, command capabilities, key manifests,
entrypoints, API specifications, infrastructure, documentation, and an
operational verification profile. Environment values are never emitted.

The full contract graph can be large because it includes the Knowledge Graph.
For automation, IDEs, and agents, pass `--output`; the complete portable graph
is written to that file and stdout remains a bounded
`workspai-cli-operation-result-v1` receipt. Without `--output`, the existing
full JSON response remains backward compatible.

The same response also exposes `knowledgeGraph` under the public
`workspace-knowledge-graph.v1` contract. It is a provider-neutral,
proof-carrying view spanning source structure, packages, service and API
contracts, infrastructure, delivery pipelines, docs/ADRs, ownership, tests,
runtime resources, and safe configuration keys. Use the dedicated query and
change-overlay surfaces when the full document is larger than a human needs:

```bash
npx workspai workspace graph entities endpoint --json
npx workspai workspace graph search "authentication endpoint" --limit 12 --json
npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json
npx workspai workspace graph evidence "GET /users" --json
npx workspai workspace graph path frontend-api "GET /users" --json
npx workspai workspace graph emit --json > .workspai/reports/knowledge-baseline.json
npx workspai workspace graph overlay --from .workspai/reports/knowledge-baseline.json --json
```

The Model step persists the same projection to
`.workspai/reports/workspace-knowledge-graph.json`. It is registered in the
artifact contract registry and agent report index, required by the unified
runner's Model stage, referenced from `workspace-context-agent.json`, and
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
changed artifacts are portable proof paths rather than machine-local absolute
paths. Proof additions, removals, and content-hash changes are first-class
overlay changes, so a source edit is visible even when the entity and relation
shape remains stable. The builder performs one bounded inventory pass per project and reuses
in-memory content hashes; query indexes live only for the immutable graph
instance, so replacing the graph is the invalidation boundary.

Direction is explicit: legacy `edges` remain producer-to-consumer for backward
compatibility; `dependencyGraph.edges` use consumer-to-dependency semantics so
impact and blast-radius consumers share one canonical interpretation.

Workspai keeps the contract alive during `create project` and `workspace sync` without overwriting manual API/event/owner declarations.

On a freshly cloned or moved workspace, `workspace sync` also repairs the
machine-local global registry entry before discovering projects. The command is
therefore safe to use as the first reconciliation step after clone. For a
legacy workspace, run `workspace foundation ensure` once to add canonical
`.workspai-workspace` and `.workspai/*` foundation files while retaining legacy
metadata as read compatibility input.

## Portable workspace archives

```bash
npx workspai workspace export --output team-workspace.workspai-archive.zip
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`,
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.

Remote archives are protected by secure defaults: 5 GB maximum download, 20 GB
maximum expanded payload, 200,000 entries, per-entry and compression-ratio
guards, and a five-minute timeout. Public HTTPS destinations are accepted;
loopback, private, link-local, and private redirect destinations are rejected.
Budgets can be lowered or explicitly raised for a controlled workflow:

```bash
npx workspai workspace hydrate https://example.test/team.zip \
  --output ./team-workspace \
  --max-download-size 2gb \
  --max-expanded-size 8gb \
  --download-timeout-ms 120000
```

For a reviewed archive served from a private development network, opt in with
`--allow-private-network`. Never use that flag for user-controlled URLs in CI
or agent services.

IDE, CI, and AI consumers can discover archive behavior from
`contracts/workspace-archive-capabilities.v1.json`. The embedded manifest and every successful
`--json` operation result are runtime-validated against
`contracts/workspace-archive-manifest.v1.json` and
`contracts/workspace-archive-operation-result.v1.json`.

## Workspace infrastructure (sidecar)

Discovery sources: Core module slugs, project `.env.example`, workspace contract env, and `.workspai/infra/overrides.json`.

```bash
cd my-workspace
npx workspai infra plan
npx workspai infra up
npx workspai infra status --strict
npx workspai infra down
```

Artifacts:

- `.workspai/infra/docker-compose.yml`
- `.workspai/reports/infra-plan.json`
- `.workspai/infra/.env.example`

## Command ownership

| Command family                                              | Owner                  | Notes                                              |
| ----------------------------------------------------------- | ---------------------- | -------------------------------------------------- |
| `create workspace`, `workspace`, `cache`, `mirror`, `infra` | Workspai CLI           | Platform orchestration                             |
| `init`                                                      | Wrapper orchestrated   | Project init; full-init alias at workspace root    |
| `dev`, `test`, `build`, `start`                             | Runtime aware          | Delegates to active project/runtime                |
| `readiness`                                                 | Wrapper release gate   | Env + doctor + analyze + verify + dependency gates |
| `pipeline`                                                  | Wrapper orchestrator   | sync → doctor → analyze → readiness → autopilot    |
| `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                         |
| `project archive/restore/delete`                            | Project lifecycle      | Safe delete with confirmation                      |
| `doctor` / `doctor workspace` / `doctor project`            | Wrapper health         | Host, workspace, and project scopes                |
| `workspace run`                                             | Workspace orchestrator | Fleet stage execution                              |
| `infra`                                                     | Workspace sidecar      | Contract-driven local dependencies                 |

The readiness `env` gate only treats runtimes represented in
`.workspai/toolchain.lock` as pinned. A Workspai Node pin does not prove a
native C/C++ compiler or another unrepresented project toolchain; those scopes
remain `warn` until the project build contract or organization CI policy
provides verifiable toolchain evidence.

The unified intelligence runner keeps `sync` and baseline resolution in a
separate two-entry execution envelope and emits exactly 11 canonical stages.
Exit `2` means the evidence gate blocked readiness after successful execution;
exit `1` means a hard runtime failure. Read the complete
[Unified Workspace Intelligence Runner contract](./workspace-intelligence-runner.md)
before consuming its report from CI, IDE, or agent integrations.

## Verification evidence freshness

`workspace verify` treats evidence as release-gate material, not just as a file
presence check. Required project evidence must match the affected project in
`workspace-run-last.json`, and evidence generated before the current impact
report is treated as stale and blocking. Re-run the recommended commands from
`workspace impact --from .workspai/reports/workspace-model-diff-last-run.json --json` before using
`workspace verify --strict` in CI. Both `diff` and `impact` require an explicit trusted input; the
CLI never guesses which historical baseline or diff should authorize a release decision.

For doctor CI exit codes and JSON evidence fields, see [doctor-command.md](./doctor-command.md).

## See also

- [Documentation index](./README.md)
- [commands-reference.md](./commands-reference.md)
- [doctor-command.md](./doctor-command.md)