Supporting docs

A Redis cluster migration can need a plan, a staging rehearsal runbook and a rollout checklist. Supporting docs keep those named markdown documents inside the design doc for the migration. Each belongs to exactly one design doc and inherits its access.

A variation describes part of the change in the document's configured review workflow. A supporting doc holds material you need while working on that change. You can have several runbooks with different names without adding variation types.

Add a document

Open the "Supporting docs" tab at the end of the design doc's tab row, then select "Add document". You can also use create_supporting_doc through MCP, or the supporting-doc API. Give the document a title and optionally a description and kind. Start blank or choose a Runbook, Test plan, Investigation, Rollout checklist or General document starter. Starters provide headings and prompts for you to fill in. They make no claim that a procedure is safe or has been verified.

For example, create a Runbook named "Redis staging rehearsal" and another named "Redis production migration" from the same starter. They have separate identities and revision histories. A blank document can have no kind.

Links and revisions

A current link has the form /design-docs/<docId>/supporting/<supportingDocId>. A revision link adds ?revision=1. Renaming the document keeps its identity and links. Earlier revisions retain their original title and content.

Every content change creates an immutable revision containing the full document snapshot and author attribution. Read the current revision before updating it. Send that revision as expectedRevision through MCP or baseRevision through the API. If someone saved first, the update returns a conflict with currentRevision. Reload, review their changes and retry with the new revision.

Record a rehearsal in the Work Log

Suppose you follow revision 1 of "Redis staging rehearsal" to move a staging cluster. Add a Work Log entry describing the environment, steps attempted, observations and outcome. Include a reference shaped like { kind: "SUPPORTING_DOC", id: "<supportingDocId>", revision: 1 }.

If the rehearsal exposes a missing replication check, update the runbook to revision 2. The first entry still links to revision 1. Record the next attempt in a new entry referencing revision 2. Omitting the revision on a new reference pins the current revision when the entry is written.

The procedure describes what to do. The Work Log records each attempt and what happened. Entries remain reported activity. Supporting docs and their references do not change approvals, acceptance criteria, the ship gate or verified evidence.

Archive and restore

Archive a document when it is no longer useful for active work. It leaves the active list in the "Supporting docs" tab and search, while direct links and revision links remain readable. Use "Show archived" in the tab to find archived documents. Restore a document to return it to active listings and search. Archiving and restoring do not create content revisions.

Supporting docs freeze when the parent design doc ships. An open amendment allows writes and marks new revisions as amendments. The shipped revision remains the latest revision that existed at shipping time. Terminal design docs reject supporting-doc writes. The Work Log still accepts entries after shipping.

MCP tools

Read active summaries with list_supporting_docs, or include archived documents with includeArchived. get_design_doc also returns active summaries without their bodies. Use get_supporting_doc for the content your task needs and list_supporting_doc_revisions for history.

Create with create_supporting_doc and save with update_supporting_doc. Use archive_supporting_doc and restore_supporting_doc for archive state. Read tools require docs:read and write tools require docs:write. Record each attempt to follow a procedure with add_journal_entry and a SUPPORTING_DOC reference at the revision used.