---
{
  "id": "platform.mindmap.tree-and-root-invariants",
  "topic": "mindmap",
  "title": "Mindmap forest and root invariants",
  "locale": "en",
  "version": "2026-08-07",
  "summary": "Forest roots are mutable while single-parent, cycle, node-limit, and client-provided ID invariants remain strict.",
  "content": "A Mindmap may contain zero or more roots. `add_node` with an omitted or null `parentId` creates an independent one-node tree; pass `manualOffset` to anchor it on the canvas. A root may be attached below any active node in the same Mindmap with `move_node`, merging two trees. Moving a non-root with `newParentId: null` detaches its whole subtree as a new root and requires its current absolute `manualOffset`; moving an already detached root to null conflicts, so update its layout to reposition it.\n\nEvery node still has at most one parent, and `move_node` cannot place a node under itself or any descendant. A non-null new parent must be active and in the same Mindmap; a different-map or missing parent fails rather than creating a cross-map edge. `delete_node` on a root soft-deletes that entire tree as one batch. `delete_node_promote_children` on a root deletes only it and promotes each direct child into an independent root; restore can reinstate a deleted root even while other roots are active.\n\nOne Mindmap supports at most 2,000 active nodes. A label is trimmed, then must contain 1–1,000 characters. These are invalid-input boundaries; do not retry the same over-limit content.\n\nA client may provide `nodeId` to make `add_node` retries idempotent. Reusing the same ID with identical content returns the existing row; reusing it with different content conflicts. `clientMutationId` is only echoed for client reconciliation and does not alter server identity, idempotency, or stored state.\n",
  "aliases": [
    "mindmap root",
    "move branch",
    "node parent",
    "node id retry",
    "tree cycle",
    "mindmap forest"
  ],
  "tags": [
    "mindmap",
    "root",
    "forest",
    "invariant"
  ],
  "relatedActions": [
    "arinova.mindmap.create_mindmap",
    "arinova.mindmap.add_node",
    "arinova.mindmap.move_node",
    "arinova.mindmap.delete_node",
    "arinova.mindmap.delete_node_promote_children",
    "arinova.mindmap.replace_outline"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/en/kb/mindmap/tree-and-root-invariants/"
}
---

A Mindmap may contain zero or more roots. `add_node` with an omitted or null `parentId` creates an independent one-node tree; pass `manualOffset` to anchor it on the canvas. A root may be attached below any active node in the same Mindmap with `move_node`, merging two trees. Moving a non-root with `newParentId: null` detaches its whole subtree as a new root and requires its current absolute `manualOffset`; moving an already detached root to null conflicts, so update its layout to reposition it.

Every node still has at most one parent, and `move_node` cannot place a node under itself or any descendant. A non-null new parent must be active and in the same Mindmap; a different-map or missing parent fails rather than creating a cross-map edge. `delete_node` on a root soft-deletes that entire tree as one batch. `delete_node_promote_children` on a root deletes only it and promotes each direct child into an independent root; restore can reinstate a deleted root even while other roots are active.

One Mindmap supports at most 2,000 active nodes. A label is trimmed, then must contain 1–1,000 characters. These are invalid-input boundaries; do not retry the same over-limit content.

A client may provide `nodeId` to make `add_node` retries idempotent. Reusing the same ID with identical content returns the existing row; reusing it with different content conflicts. `clientMutationId` is only echoed for client reconciliation and does not alter server identity, idempotency, or stored state.