Groups, Alignment & Layout

By default AgentMark lays the graph out automatically (layered along the direction). When you want to cluster related nodes and control where and how they sit, declare a group.

A group:

• draws a labelled cluster box around its members,
• arranges its members horizontally or vertically (orientation),
• aligns itself on the cross axis of its container (align: top/bottom/left/right/center), and
• can nest other groups as members.

Declaring a group

[harness#hermes: Hermes] -> [agent#planner: Planner]
[harness#hermes] -> [agent#coder: Coder]

group: Cognition
  orientation: vertical     # stack members top→bottom
  align: top                # sit this group at the top of its lane
  members: [agent#planner, agent#coder]

Members reference existing nodes by the same form you used in the topology — by id ([agent#coder] / agent#coder) or, for label-less sketch nodes, by name ([Planner]). Inline form works too:

group: Cognition {orientation: vertical, align: top}
  - [agent#planner]
  - [agent#coder]

Orientation

orientation controls how members are arranged inside the box, independent of the diagram's overall direction:

• horizontal — a row (left → right)
• vertical — a column (top → bottom)

Alignment

align controls where a group (or subgroup) sits on its container's cross axis:

Value	Effect
top / left / start	packs to the start of the axis
bottom / right / end	packs to the end of the axis
center (default)	centred

In a left→right diagram the cross axis is vertical, so top/bottom apply; in a top→bottom diagram it's horizontal, so left/right apply.

Nesting subgroups

Groups can contain other groups. A subgroup is a member written as - group: <Name> (or via a subgroups: [A, B] field). Each subgroup keeps its own orientation and align, so you can compose layouts precisely:

group: Models
  orientation: vertical
  members: [model#sonnet, model#haiku]

group: Tools
  orientation: vertical
  align: bottom
  members: [mcp#gh, mcp#slack]

# Place the two clusters side by side inside one Backend group.
group: Backend
  orientation: horizontal
  - group: Models
  - group: Tools

Only top-level groups are placed by the auto-layout; subgroups are positioned recursively inside their parent. Open the Groups & alignment example in the editor to see it rendered, and switch the layout toggle (LR/TB) to watch the clusters re-flow.

How it renders

• SVG / editor — each group is a dashed, labelled box behind its members; nested boxes sit on top.
• Mermaid (am render --to mermaid, or Copy Mermaid) — each group becomes a subgraph with its own direction, nested to match.