Collaborative document editing
Collaborative editing gives you and an AI agent a shared Markdown working copy. You can edit the document directly, ask the agent for changes, review the result, and decide when to publish it back to the content object.
The canonical document does not change while you collaborate. Studio creates a working-copy artifact for the editing session and publishes it only when you select Save to document.
Start an editing session
- Open a Markdown document under Content > Objects.
- Select Edit with AI (the sparkle action).
- Choose an environment and model if you do not want the project's default agent model.
- Start the editing conversation and describe the first change.
Studio hydrates drafts/<document-root-id>.md from the current document revision before the agent's first turn. The
agent reads and edits that artifact, not the canonical document. If you reopen the same document, Studio reattaches to
the active editing session when one exists for you and the document.
The environment and model are fixed after a conversation starts. Start a new conversation to use another configuration.
Choose an editing view
The workspace keeps the working copy on the left and the editing conversation on the right.
| View | Use it for |
|---|---|
| Document | Read the rendered Markdown, select a block, edit or comment on it, and insert content near it. |
| Full editor | Make broader rich-text changes, format content, edit tables, and use the change ruler to jump to modified regions. |
| Review changes | Compare the working copy with the document revision that started the session. |
Edit document components
In Document view, move over a block to show its contextual actions. Depending on the block, you can:
- edit the selected text with the rich-text editor
- comment on the selection so the agent can improve it
- insert a paragraph, heading, list, link, chart, code block, table, or other supported component
- add or remove table rows and columns from the table menu
A direct edit is applied to the working copy first. The agent receives the applied change as context and continues from the updated artifact; it is not asked to repeat your edit.
Edit the complete document
The Full editor saves changes to the working-copy artifact after a short debounce. Its change ruler marks regions that differ from the original document. Select Send changes to agent when you want the agent to receive a compact diff of your direct edits and continue from them.
Vertesia-specific Markdown elements that have a rich editor representation remain interactive. Unsupported custom blocks are kept as opaque Markdown so saving the document does not silently rewrite them.
Before opening the full rich-text editor, Studio checks whether parsing and serializing the Markdown would change the source. If it would, Studio asks you to choose between Edit Markdown source, which preserves the exact text, and Continue with rich text, which accepts the displayed normalization. YAML frontmatter is preserved as an opaque document header, but other valid Markdown styles, such as setext headings, can still be normalized by the rich-text serializer.
Collaborate with the agent
Ask for changes in normal language, or attach files containing review comments to apply several requests together. The agent is instructed to preserve unrelated content and edit only the working-copy artifact.
Artifact update events refresh the document view as the agent works. Changed blocks briefly highlight after a refresh. Use the refresh action in the workspace header to reload the artifact if the view appears stale.
You can also select Summarize changes from Review changes to ask the agent for a concise changelog without modifying the working copy.
Editing lock
Direct editing is locked while the agent is changing the working copy. A visible banner explains that the AI is working, and the editor, Send changes to agent, and Save to document remain disabled until the turn finishes. The workspace reloads the final artifact when the agent returns to idle.
Select Unlock editing if you must make a change before the agent finishes. The warning remains visible and offers Lock editing so you can restore the guard. Concurrent edits can conflict, so manual unlock is best used as a recovery control rather than the normal workflow.
Review and publish
Before publishing:
- Open Review changes and inspect additions and removals against the session's original revision.
- Return to Document or Full editor for any final adjustments.
- Select Save to document.
- Choose Update current version or Create new version. A new version can include an optional label.
Creating a version preserves the previous revision and navigates Studio to the new one after the save. Updating the current version keeps the same revision identity.
Publishing also persists supported run-local artifact links, such as images, into document storage and rewrites the links so the saved document does not depend on the editing session.
Conflicts and recovery
Every publish checks that the canonical document is still the revision on which the session started. If another user or workflow updated it, the save is rejected without discarding your working copy.
Select Ask agent to merge to fetch the latest canonical revision and merge its changes into the working copy. Review the result, then save again.
Other recovery controls:
- Refresh reloads the working-copy artifact when streamed updates appear incomplete.
- Starting a new conversation resets the working copy; Studio asks for confirmation when it contains unpublished changes.
- A failed direct-editor merge keeps your local text visible and offers a retry instead of replacing it with the remote artifact.
Working-copy boundaries
The working copy is the source of truth during the session. Agent tools that directly update or create canonical documents are excluded from the editing conversation, and the agent cannot bypass Save to document. This keeps review and publication under user control while still allowing full-control artifact editing inside the session.