> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cessy.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cessy.ai/_mcp/server.

# Workspace Seeding

> Prepare Design Workspaces with repeatable runtime data for previews, validation, and agent-driven testing.

Workspace seeding prepares realistic runtime data for a Design Workspace before
promotion. It lets builders and agents preview behavior against an isolated
Workspace runtime source without changing Production data.

## Status

The current Design MCP vNext surface stays at five lifecycle tools: Begin,
Inspect, Apply, Evaluate, and Finalize. Author `seed-set` artifacts with Apply,
evaluate an exact immutable revision, and inspect the resulting evidence. That
evaluation does not persist runtime data in a Workspace and does not currently
import Production projection snapshots. A vNext-native, evaluation-only
projection snapshot flow is tracked separately; it is not available today.

SeedSet delta checks execute changed SeedSets and their dependencies. A fresh
browser Evaluation Session or Runtime Agent exercise initializes all SeedSets
from the exact revision, including unchanged baseline definitions. Dependencies
run once in order before the runtime is exposed. Reads and navigation do not
reseed a live Session; a new Session rebuilds its isolated baseline without
copying persistent Workspace or published runtime data.

The persistent Workspace flows below describe legacy Design MCP v1. In v1,
create or update Seed Sets with `upsert_seed_set`, then apply them with
`apply_seed_sets`. Use `list_seed_sets(appId, workspaceId?)` to discover
existing definitions, and `get_seed_set(appId, workspaceId?, name)` to inspect
a definition before applying it. Do not use these v1 tools when connected to
the vNext five-tool surface.

## What seeding targets

Seeding is scoped to a Design Workspace. A Workspace runtime source is selected
with a `workspaceId`, and runtime data lands in that Workspace-specific runtime
state.

Seeded Workspace data is for:

* page previews with realistic documents
* projection and permission validation before promotion
* agent-driven smoke tests
* repeatable demo or review scenarios

Seeding is not for:

* Production data changes
* Sandbox provisioning
* direct database mutation
* importing historical event streams

## Projection-only Production baselines

Legacy Design MCP v1 can also copy an exact existing Production read-model
baseline into a Workspace with `copy_projection_document_to_workspace`. This
is separate from command-based Seed Sets: it creates non-event-backed,
Workspace-only test context.

For one bound page document, use the singular `id` in the `copyAction` returned
by `query_projection_data` or `diagnose_page`. That path remains compatible and
defaults `overwrite` to `false`.

For several documents, use one bounded call instead of parallel singular
requests:

```json
{
  "tool": "copy_projection_document_to_workspace",
  "arguments": {
    "appId": "11111111-1111-1111-1111-111111111111",
    "workspaceId": "ws_demo",
    "projectionName": "OrdersView",
    "ids": ["order-101", "order-102"],
    "idempotencyKey": "orders-baseline-2026-07-23",
    "expectedSourceHashes": {
      "order-101": "<copy-safe-sha256>",
      "order-102": "<copy-safe-sha256>"
    },
    "expectedSourceAggregateHash": "<sorted-id-hash-manifest-sha256>",
    "expectedTargetHashes": {
      "order-101": null,
      "order-102": null
    },
    "overwrite": false
  }
}
```

The `ids` manifest accepts 1 to 500 IDs of at most 1,024 UTF-16 code units each. Cessy
de-duplicates and sorts the selection, then uses a process-wide shared
two-permit FIFO scheduler. The
idempotency key accepts 1 to 128 letters, numbers, dots, underscores, colons,
and hyphens. The client should not create its own worker fan-out. Hash
preconditions are lowercase 64-character SHA-256 hex values and may only name
selected IDs.

"Exact" is manifest-scoped: the result, counts, and aggregate hashes cover
exactly the requested IDs. The operation does not enumerate or delete unrelated
documents already present in the destination collection.

Document hashes use projection-copy canonical JSON v1: SHA-256 over the UTF-8
bytes of the default-redacted document, with object keys sorted by UTF-16 code
units at every depth. Arrays preserve order, `undefined` object properties are
omitted, and `undefined` array entries become `null`. The aggregate applies the
same algorithm to the UTF-16-code-unit-ID-sorted array of
`{ "id": <id>, "hash": <document-hash> }` objects. This exact form is the
input for `expectedSourceAggregateHash`.

As a portable v1 check, `{ "é": 1, "z": 2, "😀": 3 }` canonicalizes to
`{"z":2,"é":1,"😀":3}` and hashes to
`4177f29d85d48c133fea6e4531c5817e8ad4a86eca582296fe34d6322db0799c`.

Cessy durably pins each first successful source hash and rechecks it before the
target write and during final verification. Use the optional expected source
hashes and aggregate hash to pin that first read to caller-known evidence. For
target CAS, `null` requires absence and a hash pins the exact existing target
that may be replaced with `overwrite: true`. An already-identical target is a
deterministic no-op, including after a lost response. A missing source, source
or aggregate mismatch, and a non-identical target conflict block the run.

The bulk run is durable and identified by `idempotencyKey`. After a client
timeout, call the same tool with the original `appId`, `workspaceId`,
`projectionName`, key, and `operation: "status"`. Use `operation: "resume"` to
continue an expired or retryable run. Omit `id`, `ids`, hashes, and `overwrite`
for status/resume; the server already has the manifest. Reusing a key with
different copy intent is rejected. Completed receipts are immutable
point-in-time evidence; use a new key and current hash expectations to verify a
target again after later Workspace mutations.

The result is content-free: it returns durable counts, per-ID status and
source/target hashes, plus aggregate hashes when complete, but never document
bodies. Hashes cover the default-redacted payload that is actually written, not
the raw secret-bearing Production record.

This operation never changes Production. It dispatches zero commands and
events, runs no policies, triggers, or subscriptions, and makes no external
HTTP calls. The copied documents are transient Workspace fixture data and are
not promoted as domain history. This tool is not available on the current
vNext five-tool surface.

## Seed Sets

A Seed Set is a named set of runtime-data steps. Builders and agents can select
one or more Seed Sets when preparing a Workspace.

Seed Sets are designed to be:

* **Named:** so builders can choose `demo-leads`, `invoice-review`, or
  `empty-account-with-user`.
* **Ordered:** so prerequisite data runs before dependent data.
* **Command-based:** so normal command validation, events, and projections are
  produced.
* **Workspace-only:** so the same app can have seeded preview data without
  changing Production.
* **Auditable:** so a failed or skipped run is visible.
* **Rerunnable safely:** so repeated preparation does not duplicate data by
  accident.

## Seed Set shape

A Seed Set contains metadata, optional dependencies, optional fixture values,
and ordered steps. Persisted Seed Set artifacts must include at least one
command step.

```ts
type SeedSet = {
  name: string;
  label?: string;
  description?: string;
  dependsOn?: string[];
  fixtures?: Record<string, unknown>;
  steps: Array<{
    id: string;
    kind: 'command';
    commandName: string;
    data: Record<string, unknown>;
    capture?: Record<string, string>;
    idempotencyKey?: string;
  }>;
};
```

Command steps are the first-class path. A step submits a command to the
Workspace runtime, captures useful ids if later steps need them, and then lets
the runtime produce events and projections normally.

Do not store composition-only presets as Seed Set artifacts with `steps: []`.
When you only need to apply existing Seed Sets together, pass the ordered
`seedSets` array to Workspace creation or Seed Set apply instead.

## Authoring and updating Seed Sets

Use `upsert_seed_set` to create or replace a named `seed-set:<name>` artifact in
a Design Workspace. The tool derives dependency metadata from `dependsOn` and
command step names, returns a diff preview, and can validate the resulting
Workspace graph before saving.

```json
{
  "tool": "upsert_seed_set",
  "arguments": {
    "appId": "11111111-1111-1111-1111-111111111111",
    "workspaceId": "ws_demo",
    "name": "demo-leads",
    "label": "Demo Leads",
    "dependsOn": ["base-users"],
    "fixtures": {
      "leadId": "lead-demo-1"
    },
    "steps": [
      {
        "id": "create-lead",
        "kind": "command",
        "commandName": "CreateLead",
        "data": {
          "leadId": "{{fixtures.leadId}}",
          "name": "Ada Lovelace"
        },
        "idempotencyKey": "demo-lead-1"
      }
    ],
    "dryRun": true,
    "validate": "changeset"
  }
}
```

Use `dryRun: true` to preview without mutating the Workspace. The default
`validate: "changeset"` catches missing command dependencies, missing Seed Set
dependencies, cycles, duplicate step ids, and other ChangeSet validation
failures before the artifact is saved. Use `validate: "artifact"` only while
drafting against an incomplete Workspace graph.

After a successful non-dry-run upsert, inspect `diff_workspace` before applying
the Seed Set to runtime data. Applying a Seed Set writes Workspace runtime data
only. Promoting the Seed Set definition is a separate ChangeSet decision, and
seeded runtime events/documents are not promoted.

## Discovering Seed Sets

Use `list_seed_sets` before applying by name. Without `workspaceId`, it lists
Seed Sets from the published app model. With `workspaceId`, it lists the
effective Workspace model and reports whether each Seed Set comes from the
Workspace base or from Workspace edits.

Each listed Seed Set includes its name, label, description, dependencies,
content hash, step count, and command names. Use `get_seed_set` to read the full
normalized definition before running commands. If `apply_seed_sets` receives an
unknown name, its error includes available candidates and points back to
`list_seed_sets`.

### Placeholders and literal template text

Seed step `data` supports the same placeholder resolver as design-time tests.
Use `{{fixtures.name}}` or `{{captures.name}}` for exact values. Non-exact
strings interpolate placeholders.

When a command value needs to store external template syntax that also uses
double braces, wrap the value with `$literal`. The runner unwraps it before
command execution and does not resolve placeholders inside it:

```json
{
  "body": {
    "$literal": "Hallo {{lead_first_name}}, danke fuer deine Bewerbung bei {{location_name}}."
  },
  "assigneeId": "{{fixtures.recruiterId}}"
}
```

## How a run works

When Seed Sets are applied to a Workspace, the runner:

1. Load the target app and Design Workspace.
2. Materialize the Workspace runtime config from the Workspace artifact graph.
3. Resolve requested Seed Sets in dependency order.
4. Resolve fixture values and captured values for each command step.
5. Execute commands against the Workspace runtime source.
6. Record the run status, selected Seed Sets, resolved step inputs, command
   outputs, captures, correlation ids, and errors.
7. Skip already completed Seed Sets with the same content hash unless a builder
   explicitly asks to rerun.

After the run, verify seeded data through Workspace runtime reads. Production
projections should not show the Workspace seed data.

## Reruns and failures

Seed runs should be idempotent by default. If the same Workspace already has a
completed run for the same Seed Set content, the runner reports it as skipped
or already completed instead of executing duplicate commands.

If a step fails, the run records the failed Seed Set, step id, command name, and
error. The failed step includes the safe runtime failure category and code plus
execution and correlation IDs for diagnostic lookup; sensitive guard values and
expressions remain in protected logs. Successful steps before the failure keep
enough resume metadata for a later `mode: "skip-completed"` retry to skip those
steps and continue from the first step that did not complete. The run-level
`recovery` field reports whether that resume is proven safe, and the MCP error
includes a ready-to-run resume action when it is. This keeps retries from
replaying commands whose runtime effects already persisted.

If the Workspace contains partial seed effects from an older failed run that
does not have per-step resume metadata, `skip-completed` fails with guidance
instead of replaying those commands. Use a fresh disposable Workspace, or use
`mode: "rerun"` / `force: true` only when duplicate command effects are
intentional.

## Applying Seed Sets

When the Seed Set definitions already exist in the Workspace base, apply them
during Workspace creation:

```json
{
  "tool": "create_workspace",
  "arguments": {
    "appId": "11111111-1111-1111-1111-111111111111",
    "fromRelease": "published",
    "name": "Demo review",
    "seedSets": ["demo-leads"],
    "seedMode": "skip-completed"
  }
}
```

The response includes `seedRun` when creation-time seeding runs. If seeding
fails, the tool returns an error with the new `workspaceId`, Workspace status,
and seed-run details so the run can be inspected or retried.

Use the standalone Design MCP tool when you create or change Seed Set
definitions after the Workspace exists, or when you intentionally need a rerun:

1. Run `upsert_seed_set` to create or update the definition.
2. Run `diff_workspace` to preview the `seed-set:<name>` artifact change.
3. Run `apply_seed_sets` to write Workspace runtime data.

```json
{
  "tool": "apply_seed_sets",
  "arguments": {
    "appId": "11111111-1111-1111-1111-111111111111",
    "workspaceId": "ws_demo",
    "seedSets": ["demo-leads"],
    "mode": "skip-completed"
  }
}
```

The runner stores a seed-run record with status, step details, hashes, resolved
inputs, command outputs, captures, correlation ids, and any error. Reapplying
the same Seed Set content to the same Workspace defaults to skipped steps. Use
`mode: "rerun"` or `force: true` only when repeated command execution is
intentional.

### Policy-driven follow-ups

Seed command steps intentionally run with policies, triggers, and subscriptions
disabled. The command still validates, emits events, stores them, and updates
projections, but policy fan-out products are not created automatically.

If a Seed Set step runs a command whose produced events trigger policies in the
full model, the seed run includes a `policy_fanout_disabled` warning on the run
and affected step. The warning lists the triggered policies and any command
names declared by those policies so authors can add explicit follow-up command
steps when their projections or pages need those downstream documents.

For example, if `AddContract` emits `ContractAdded` and the full model normally
uses policies to run `PrepareDatasheetWhenContractAdded` and
`ScheduleAccountingRegistrationOnContract`, a Seed Set that only runs
`AddContract` creates the contract projection but not the datasheet or
accounting registration projections. Add explicit command steps for the required
follow-up products.

## Safe defaults

Workspace seeding should default to safe runtime behavior:

* reject Production runtime sources
* avoid live external calls unless explicitly enabled for a validation profile
* use credential references instead of embedding secrets
* prefer command-level idempotency keys where commands support stable semantic
  ids
* keep seeded runtime data outside Changesets; Changesets carry model changes,
  not preview data