docs

name	docs
description	Use when asked to write, migrate, or organize long-form Mighty docs, or decide whether something should be a doc or a spec/task/decision. Covers `mt doc` authoring, doc types, and when guides or runbooks should live in the Mighty graph instead of standalone repo markdown.

Docs

Overview

Use mt doc for long-form artifacts that should live in the Mighty graph: guides, runbooks, ADRs, RFCs, plans, migration notes, research, and other supporting narrative.

Choose the right entity

• Use a spec when the content defines normative product or system behavior that the code must satisfy. Specs are the control plane and should stay structured around Guarantees and Constraints.
• Use a task for scoped implementation work.
• Use a decision for a durable architectural or policy choice.
• Use a doc when the artifact is explanatory, operational, or review-oriented long-form writing.
• Use mt doc --type spec only for long-form supporting spec documents. Do not replace the canonical spec tree with a doc.

Doc workflow

1. Search first: mt search <topic> and mt show <id>.
2. Create or update the doc with mt doc new or mt doc update.
3. Link the doc back to the owning spec or decision: mt link --from <spec-id> --rel documented_by --to-doc <doc-id>.
4. If you are replacing standalone repo markdown that should be graph-native, migrate the content into mt doc, link it, and then remove the repo file so the graph is canonical.

Commands

Create a guide:

cat <<'EOF' | mt doc new --title "Guide: ..." --type guide --status published --content-file -
# Guide title

## Context
- Related spec: [Example](cite:mt-spec-...)
EOF

Update an existing doc section by section (preferred — preserves comment anchors and CRDT identity):

# Enumerate sections
mt show <doc-id> --sections

# Read a section as YAML with loro_ids
mt show <doc-id> --section @s:N > /tmp/edit.yaml

# Edit the YAML — keep loro_id to update nodes in place, omit for new nodes
mt edit <doc-id> --section @s:N --content-file /tmp/edit.yaml

See planning/references/targeted-edits.md for the full YAML schema and reconciliation rules. The mt edit command works uniformly across specs, tasks, decisions, and docs — any record-backed entity with a rich text description.

Last resort only — full doc rewrite (loses all comment anchors and CRDT identity):

cat <<'EOF' | mt doc update <doc-id> --content-file - --reason "Refresh guidance"
...
EOF

mt doc update --content-file replaces the entire LoroTree as a fresh rewrite. Use it only for brand new unpublished drafts or recovery from corrupted state. For any other edit, use mt edit section by section.

Writing rules

• Prefer docs for guides, runbooks, RFCs, ADRs, plans, and research.
• Prefer citations to specs, decisions, tasks, and other docs instead of restating ids in plain text.
• Keep the canonical requirement in specs; keep the deeper narrative in docs.
• When a doc needs files or screenshots, use the evidence skill.