add_cell
Adds one new org block (group, subsidiary, vertical, transversal, external, division, node, infrastructure…) at the x/y you give: absolute canvas coordinates for a root block, relative to the parent's top-left corner for a child of a parent in 'container' mode. Fits a single addition; several blocks with their content belong to apply_batch (positions computed server-side), an ERD table to add_entity, a node of an arch/process/journey/captable diagram to add_kind_node. With parentId it also creates the structural dependency (ID: struct-{parentId}-{cellId}) and grows the parent to hold the child; a parent does not enclose its children on every type (the parent's displayMode decides), and in 'hat' mode the children are root blocks without parentId, linked by structural dependencies (add_dependency); update_cell switches a block between container and hat and converts its children's coordinates. REFUSED, nothing written, when the id already exists, when the parent is unknown, or when the project locks root placement and a root block is created without confirmRootPlacement: true. x/y is only an initial position: the post-call tidy-up may recompute it, and the card height may be raised to fit desc/content. Over MCP the final values come back in the response cell; in the chat the tidy-up runs after the whole burst of tool calls, so the final position is the one get_cell_details reports. Returns cell, structuralDependency and a note. An existing block is changed with update_cell, re-parented with move_cell and duplicated with clone_cell.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | X position in pixels: from the top-left corner of the canvas for a root block, from the top-left corner of the parent for a child of a parent in 'container' mode. Only an initial position: the post-call tidy-up may recompute it. | |
| y | Yes | Y position in pixels: from the top-left corner of the canvas for a root block, from the top-left corner of the parent for a child of a parent in 'container' mode. Only an initial position: the post-call tidy-up may recompute it. | |
| id | Yes | Unique kebab-case ID (e.g. 'data-lab', 'world-models') | |
| desc | No | Short description of the block (supports \n for line breaks) | |
| icon | No | Emoji or image URL | |
| name | Yes | Display name of the block | |
| note | No | Internal note of the block (context not shown on the card, visible in the panel). | |
| type | Yes | Block type that determines the visual rendering | |
| label | No | Label under the type (e.g. 'Subsidiary · Vertical') | |
| order | No | Position in the parent's list of children | |
| width | No | Width in pixels (default: depends on the type, ~280px) | |
| height | No | Height in pixels (default: depends on the type, ~100px) | |
| origin | No | Origin of the project (e.g. 'Referred by Marc') | |
| status | No | Status badge (e.g. 'Exploring', 'Considered', 'In discussion') | |
| colorKey | No | Block color, taken from the supported colors. When omitted, it is DERIVED from the type (cell-type-config.ts) — same pattern as apply_batch: an omitted field gives the color of the type. | |
| parentId | No | ID of the parent block in the hierarchy. ⚠️ Declaring a parent is NOT enough for the children to be DRAWN INSIDE it: only groupe/filiale/sous-filiale/container enclose by default. On any other type (transversale, verticale, externe, node, infrastructure), the children are displayed NEXT TO the parent card, joined by an arrow; displayMode:'container' on the parent makes them drawn INSIDE. | |
| layoutHint | No | Placement hint, OPTIONAL: DERIVED from the type at creation (like colorKey) when omitted. 'column-side' forces the side column, 'bottom-center' forces the bottom band. | |
| statusType | No | Style of the status badge. 'done'/'abandoned' (kind='org' only) visually fade the card — 'abandoned' also strikes through the title — to flag a closed subject without deleting it or making it disappear from the view. | |
| displayMode | No | Rendering mode when the block has children: 'container' (visually encloses the children, in RELATIVE coordinates) | 'hat' (a hat above with structural arrows to each child, without containment — useful when the hierarchy is a 'family tree'; the size of a stake does not decide it: a stake percentage always stays on a `business` link). ⚠️ WHEN OMITTED, the behavior depends on the TYPE: groupe/filiale/sous-filiale/container enclose, all the others do NOT. On a transversale, a verticale, an externe, a node or an infrastructure that must contain its children, this field is therefore REQUIRED — otherwise the hierarchy will be right in the database but wrong on screen. | |
| kindMetadata | No | Legal metadata of the block (kind='org'): ISO 3166-1 alpha-2 jurisdiction, legal form, entity class, share capital, incorporation date. Shown on the card. | |
| childrenLabel | No | Label above the children (e.g. 'Verticals & services') | |
| expectedProjectId | No | UUID of the project targeted by THIS call. ACTUALLY targets this project instead of the session project. Refused without changing anything if access is not granted. | |
| confirmRootPlacement | No | ⚠️ Required (true) ONLY if the project has locked its root placement (Settings) AND this block has no parentId: without it, the creation of a NEW root is refused. Not applicable if the root placement is not locked, or if a parentId is provided. |