# 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 or v2. Character rigs, boards and paintings require v2; downgrades are rejected. 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://studio.datxanhmientrung.ai/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://studio.datxanhmientrung.ai/api/schema), or [OpenAPI reference](https://studio.datxanhmientrung.ai/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)