# Documents & revisions

> Make focused changes while keeping human and agent work in sync.

A project has a saved `revision`; its document has a separate `schemaVersion`. Read the revision before changing the design. Every full-document save checks it atomically.

-  **Read.**  Get the document and revision together.
-  **Change.**  Apply a small operation array to the actual node IDs.
-  **Save.**  Send the observed revision, not a guessed newer number.
-  **Reconcile.**  On 409, read the current design and adapt your edit.

```
[
  {
    "op": "update-node",
    "nodeId": "ACTUAL_NODE_ID",
    "changes": { "text": "The next chapter" }
  }
]
```

```
dsa projects get PROJECT_ID
dsa schema --operations
dsa projects document patch PROJECT_ID \
  --revision OBSERVED_REVISION --file operations.json
```

**The document is shared, not duplicated per client** REST, MCP, WebMCP, and the CLI all use DesignDocument v1. The schema validates IDs, page parents, geometry, asset ownership, and timeline references. Keep the project ID and kind. Never use full regeneration to bypass a conflict.

## Proposal versus saved work

```
dsa generate PROJECT_ID --provider openai \
  --revision OBSERVED_REVISION --prompt-file brief.txt --output proposal.json

# Inspect the proposal before this separate write.
dsa projects document put PROJECT_ID \
  --revision OBSERVED_REVISION --file proposal.json
```

Media generation and uploads return assets independently of the document. Add the asset reference and node, inspect the result, then save. Publishing exposes a frozen snapshot of the saved revision; it does not automatically publish later edits.

## Interview, scope, and explicit approval

The brief stores the original request, contextual questions, answers, and scope separately from the design. Its `revision` is independent of the document revision; use zero only to create the first brief. Read the actual brief before every update.

- Save a clear request. An external agent can supply its own interview, or call the configured BYOK provider to ask contextual questions.
- Show the questions to the human. Save their answers; never manufacture an answer to make the workflow pass.
- Review a scope covering objective, audience, visual direction, deliverables, constraints, and acceptance criteria.
- Approve only after explicit human agreement. Every later brief or scope edit invalidates that approval.
- Generate and inspect the design as a separate action. Scope approval never publishes anything.

```
{
  "request": "Create a six-slide product introduction. Ask me for missing facts."
}
```

```
dsa brief put PROJECT_ID --revision 0 --file brief.json
dsa brief get PROJECT_ID

# Optional: invokes your configured provider and may incur charges.
dsa brief interview PROJECT_ID --revision OBSERVED_BRIEF_REVISION --provider openai

# After explicit human approval of the current answered scope:
dsa brief approve PROJECT_ID --revision OBSERVED_BRIEF_REVISION
```

Read the [live interview and scope schemas](https://beta.studio.agentkit.best/api/schema) before supplying an external agent's structured response. Questions support text, one choice, or multiple choices. On a brief conflict, reload and reconcile its current questions and answers.

## Inspect before delivery

```
dsa projects check PROJECT_ID
```

Preflight returns actionable findings with node/page IDs, severity, counts, and limitations. It estimates overflow, text fit, opaque-hex contrast, media readiness, and export duration. It does not composite overlapping backgrounds, measure every font, inspect animated extremes, or certify accessibility. Review the rendered design and actual export.

## Reusable design systems

In the editor, choose  **Manage design systems**  to create a library of tokens, component variants and reusable compositions. Capture the selected component or current page, edit its saved definition, then create a version before applying or inserting it.

Library `version` and project `revision` are separate. Applying a saved version copies its tokens/system into the project while retaining authored component overrides and records the pinned library version. Later library edits do not change existing projects automatically. Inserting a composition copies its hierarchy with fresh IDs; deleting a library leaves previously embedded project content intact.

Use `dsa design-systems schema`, the [live shared schemas](https://beta.studio.agentkit.best/api/schema), or [OpenAPI reference](https://beta.studio.agentkit.best/api/openapi) for complete validated definitions and request shapes. On a version conflict, read the current definition and reconcile changes before saving.

[Targeted operation implementation](https://github.com/bestagentkits/design-studio-ai/blob/main/src/shared/operations.ts)