> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orchestrahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge docs

> Pages the team writes together, live, like a shared document, with versions, issues and sessions inside, that agents read and write and sessions carry in context

Knowledge holds the team's own pages: conventions, runbooks, designs, the
reasoning behind a decision. Several people can write a doc at the same time,
agents read and write them over MCP, and a session can carry a doc in its
agent's context. Underneath, every doc is markdown.

## 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:

| Button | Shortcut on a Mac | Shortcut on Windows and Linux |
| - | - | - |
| Undo, redo | ⌘Z, ⌘⇧Z | Ctrl+Z, Ctrl+Shift+Z |
| Normal text, Heading 1 to 3 | ⌘⌥0 to ⌘⌥3 | Ctrl+Alt+0 to Ctrl+Alt+3 |
| Bold, italic, underline | ⌘B, ⌘I, ⌘U | Ctrl+B, Ctrl+I, Ctrl+U |
| Strikethrough, code | ⌘⇧S, ⌘E | Ctrl+Shift+S, Ctrl+E |
| Link | ⌘K | Ctrl+K |
| Bulleted, numbered, check list | ⌘⇧8, ⌘⇧7, ⌘⇧9 | Ctrl+Shift+8, 7, 9 |
| Quote, code block | ⌘⇧B, ⌘⌥C | Ctrl+Shift+B, Ctrl+Alt+C |

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.

Secrets are redacted before a version is stored. A key typed into a doc is
replaced at the next save, as an edit everyone with the doc open receives.

## 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 `.doc` file Word opens with headings, lists, links and tables.
* **Markdown**, **Web page** (`.html`) or **Plain text** (`.txt`).

Each file starts with the doc's title. Issues and sessions in it become links
with their titles, as you see them: anything you cannot open is left as it was
written.

## 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:

| Tool | What it does |
| - | - |
| `list_docs` | The workspace's docs, most recently changed first, optionally for one project. |
| `search_docs` | Docs whose title or saved text contains the words, with the passage that matched. |
| `get_doc` | One doc in full, as it is right now, including edits not yet saved as a version. |
| `save_doc` | Create a doc, or change its title or body. |

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_doc`
  when it bears on the work.

The page says which happened: the agent was sent the doc now, or it will be in
the agent's context when the session next starts (for a captured Claude Code
session, the next time it starts or resumes). Docs can also be attached when
starting a session in the cloud.

## Who can see a doc

A doc belongs to its workspace, like a project: every member of the workspace
can read and edit it, and nobody outside the workspace can find it, by link,
search or MCP.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.