Writing
Open a doc from Knowledge, or start one with New doc. It opens as a document: you see the formatting, not the markup. The toolbar has what a shared document needs:
The toolbar also inserts a divider and a table (with buttons to add and remove
rows and columns while the caret is in one), clears formatting, and includes an
issue or a session. Markdown typed straight into the document works too:
#
starts a heading, - a list, [ ] a checklist item.
Markdown in the header switches to the doc’s markdown beside its rendering,
for anyone who would rather write it that way. Both edit the same doc, live.
Writing together
When several people have a doc open, each one’s typing reaches the others as it happens, and each person’s cursor shows in the text in their colour, with their name as it moves. A selection shows in their colour too. The header shows everyone who has the doc open. Every change is one text operation sent to the API, which applies them one at a time in a single order and hands each to everyone with the doc open. Two people typing in the same paragraph never overwrite each other: an edit made against an older copy is moved past the edits that landed first, so everyone ends up with the same text. Undo undoes only your own edits. An edit in the document changes only the markdown it touched. A doc an agent wrote by hand keeps its own markdown everywhere else; the block you edit takes the editor’s spelling (- for a bullet, ** for bold).
If a connection drops, the editor keeps your edits and sends them again when it
is back; the API stores a resent edit once. A tab left closed long enough that
the doc moved far past it asks you to reload instead of guessing.
Issues and sessions in a doc
Type@ and a few letters to find an issue or a session, then pick one to
include it. In the markdown, an issue is its ref (W-12, or a synced ref such
as ORC-12) and a session is session: followed by its id, so writing either
by hand works the same way.
Each one shows live: an issue with its status and current title, a session with
its agent and title, and whether it is running now. Click one to open it. In the
Markdown view’s rendering and in a version, a name alone on its own line shows
as a card with a little more: the issue’s status and assignee, or how long ago
the session last did anything.
What a doc shows for a name is looked up for each reader, every time they read
it, through the same permission check as every other read. A doc never shows
anyone an issue or session they could not open themselves. An issue ref you
cannot open stays plain text, and a session you cannot open says it is not
available, the same as one that does not exist. The doc itself holds only the
names.
The doc’s side panel lists everything it includes under Included, issues
and sessions in the order the doc names them, each one click from opening.
Add there links an issue or a session to the doc as a reference without
writing it into the text, and the remove button takes a link off again.
Linking checks that you can see the issue or session; everyone else sees a
linked one only if they can open it. An issue’s page lists the docs that name
it or link it, and get_doc returns a doc’s linked issues and sessions to
agents.
Version history
Docs save themselves: a moment after the typing stops, the doc is saved as a new version, with everyone whose edits it holds, and the header says “Saved”. There is no Save button. ⌘S (Ctrl+S on Windows and Linux) saves at once instead of after the pause, and the header says “All changes saved”. Versions opens the history, which works like a Google Doc’s:- Saves made within half an hour of each other are grouped into one editing session, newest first, showing when it ended and everyone who wrote in it. The arrow beside a session shows each save in it.
- Choose a session or a save to see it in the doc’s place, with what changed in it marked: words added are highlighted, words taken out are struck through. Show changes turns the marks off to read it as it rendered.
- Restore this version puts it back as a new version, so nothing is lost, the restore included. Everyone with the doc open receives it as an edit.
- Name current version, at the top of the history, names what the doc says now (saving it first), like “Sent to legal”: a checkpoint to come back to. Name this version names any version you are looking at. A named version stands on its own in the history, and Only named versions hides the rest.
Export
Export in the header saves the doc as a file:- PDF: opens the print dialog for the doc alone; choose Save as PDF.
- Word: a
.docfile Word opens with headings, lists, links and tables. - Markdown, Web page (
.html) or Plain text (.txt).
Archiving and deleting
Archive a doc to take it out of Knowledge and the pickers while keeping it: it still opens from its link, reads but does not edit, and can be restored from the archive. Delete a doc to remove it from Orchestra: from the doc’s sidebar, or by right-clicking it in Knowledge. It leaves Knowledge, every session it is attached to, and its links, and the pages under it move up a level. Both ask first. As with everything in Orchestra, the record that it existed and was deleted stays in the event log.Agents and docs
Four tools on the Orchestra MCP server work with docs in your workspace:
An agent includes an issue by writing its ref and a session by writing
session:<sessionId>, and follows either with get_issue or get_session.
An agent’s write is merged like anyone’s edit. get_doc returns a revision;
passing it to save_doc as baseRevision means the agent’s body is applied as
an edit to the text it read, so what people typed since is kept. Each write is
saved as a version people can see and restore.
Docs in a session
On a session’s page, Docs attaches a doc in one of two modes:- Always in context: the agent gets the whole doc when the session starts, and at once if it is running and can hear messages. A very long doc is cut at 20,000 characters, and the agent is told how to read the rest.
- On demand: the agent is told the doc exists and reads it with
get_docwhen it bears on the work.