Docs, and how a written record sits alongside the work

Not everything a team needs is a task. A runbook, a decision you want to keep, a description of how a workflow is meant to work — these are written records that outlast any one task, and that people read rather than move through stages. In Cadence you keep them as docs: pages of content that live in a space alongside its workflows and tasks. This page explains what a doc is and how it is versioned, so the Docs reference makes sense.

What a doc is

A doc is a page of content in a space. It has a title and a body, and it sits in a tree: a doc can have a parent doc and a position among the docs that share that parent, so a space's docs form an outline rather than a flat list. You create, read, list and move docs over the Model Context Protocol endpoint — docs_create, docs_get, docs_list, docs_move — and in the web interface. Reading and searching a doc need the read role; creating and moving one need member.

A doc belongs to one space and stays there. Moving a doc reparents it and reorders it among its siblings within that space; a move that would take it to another space, or that would make a doc its own ancestor, is refused.

How a doc is versioned

A doc's content is not edited in place. A doc's body lives in versions, and a version is in one of three states:

• draft — content you are editing, not yet visible to readers.
• ready — the published version. A doc has at most one, and it is the content a reader sees.
• archived — a version that a later publish has superseded.

Creating a doc writes its first draft; the doc has no readable content until you publish that draft, and reading a doc that has never been published is refused. Publishing moves a draft to ready, and the version it replaced becomes archived. A doc has at most one draft and at most one published version at a time.

Publishing is a step you take, not something Cadence does for you: a draft stays a draft, invisible to readers, until it is published. Cadence never publishes a draft on its own — a person publishes it, and only then does a reader see the change. There is no un-archive — to bring back an old version, fork it into a new draft and publish that.

How a doc is addressed and found

Each doc has a stable web address in its space. That address carries a short slug made from the doc's title when it was created — but the doc is identified by its id, not its slug, so renaming a doc does not change its address, and a link built from the old title still resolves to it.

A doc is searchable next to your tasks: the search that spans a space returns its docs alongside its tasks, so a written record turns up beside the work it describes rather than in a separate place you have to remember to look.

Where to go next

For every doc tool and its fields, the version lifecycle and its refusals, doc attachments, and the exact web addresses and downloads, see Docs. For the search that spans tasks and docs, see Search.