Describe the command areas and the new place rule (#429)

- MCP: the catalog by area, Variables nodes, groups and comments,
  the crossings in lint_graph, and the tests of stage 5a.
- Behaviors: Arrange puts the flow on top on a tie, and new nodes go
  next to the node they link to where their links cross the fewest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Behaviors.md

@@ -629,10 +629,14 @@ the inspector).
   up; the offset is a decision about rectangles and lives with the others in `editor/framing.ts`.
 - **Arrange** (next to the magnet, in every graph tab, in a song's only with its routing; #429) lays the graph out: the flow runs left
   to right in columns, a node that only feeds others (a Get, the Owner) stands just left of the
-  first one it feeds, each column is put in the order that crosses the fewest links, and the nodes
-  are moved up or down towards the ports they link to without ever overlapping. With several nodes
-  selected it arranges those and leaves the rest; they keep their place if they fit there, else they
-  go right of everything. A group around them stays where it is. One undo step, *Arrange nodes*.
+  first one it feeds, each column is put in the order that crosses the fewest links — of two
+  orders that cross as often, the one with the flow on top — and the nodes are moved up or down
+  towards the ports they link to without ever overlapping. With several nodes selected it arranges
+  those and leaves the rest; they keep their place if they fit there and no link to the rest runs
+  backwards from there. Else they go next to the node they link to — left of one they hand a value
+  to, right of one they take from — where there is room and their links cross the fewest others,
+  and of those places the one nearest to the two ports lying level; only when there is none, right
+  of everything. A group around them stays where it is. One undo step, *Arrange nodes*.
   It measures every node as drawn; the rule is the pure `editor/graph/arrange.ts`.
 - **One tab per behavior**: each behavior opens as a document of its own (double-click in the
   asset panel), several at once, each keeping its zoom and scroll for the session. A selection

MCP.md

@@ -57,11 +57,11 @@ the badge says *Agent offline* meanwhile.
 |---|---|
 | `get_view` | What you are looking at: the project, the tab and the document it shows, the selection with names (objects, nodes by type, frames, keys ...), the camera of the view, whether the game is playing or paused, tabs in windows of their own, and the menu or dialog on top (a menu by its first entries) |
 | `screenshot` | The whole editor as drawn, as a PNG, at most `maxWidth` pixels wide (1280 unless asked otherwise) |
-| `list_assets` | The assets with ids, names and types, by type or a part of the name |
-| `get_asset` | One asset as stored, with the rows of its properties and the named objects of a scene or container. A graph is only counted, pixels and map cells too |
-| `get_graph` | A graph: every node with its settings and its ports as they are now, the edges, the groups and notes |
+| `list_assets` | The project's settings (start scene, layers, play settings, master bus) and the assets with ids, names and types, by type or a part of the name |
+| `get_asset` | One asset as stored, with the rows of its properties and the named objects of a scene or container, the content of a placed container too (marked `fromContainer`, ids like `<container object>~<path>`). A graph is only counted, pixels and map cells too |
+| `get_graph` | A graph: every node with its settings and its ports as they are now (the ports it declares itself under `ports`), the edges, the groups and comments with their boxes and colors |
 | `lint_graph` | How a graph reads, counted as you see it: nodes on top of each other, links that cross, links running over a node that is not theirs, links running right to left, the longest links, with a few ids of each |
-| `catalog` | What there is to make: the commands with their arguments, the nodes a graph can hold (all of them, or the best matches of a search in full), the asset types and their properties, the variable kinds |
+| `catalog` | What there is to make: the commands by area with what each does, and with a query (an area or command names) their arguments; the nodes a graph can hold (all of them, or the best matches of a search in full); the asset types and their properties; the variable kinds |
 | `run_commands` | Changes the project, see below |
 | `open` | Brings up an asset's tab, or the scene or game tab |
 | `select` | Selects an asset, objects of a scene or container, or nodes of a graph |
@@ -93,10 +93,20 @@ it. One Ctrl+Z takes the whole call back.
 - **The editor places the nodes.** Nodes added without `x` and `y` are arranged when the call has
   run, the way the [Arrange](Behaviors) button does it, and the move is part of the same undo
   step. Nodes that were there before stay where they are, so what you laid out by hand is never
-  shuffled; the new ones keep the place right of them. `arrange_graph` arranges nodes the agent
+  shuffled; the new ones go next to the node they link to, where their links cross the fewest
+  others. `arrange_graph` arranges nodes the agent
   names, or the whole graph, which the agent is told to do only when you ask.
 - **Readable graphs.** The agent is told to fetch a value needed far away with a second Get or
-  Owner node next to where it is used rather than one long link, and to check with `lint_graph`.
+  Owner node next to where it is used rather than one long link, and to check with `lint_graph` —
+  the crossings too, with `arrange_graph` when there are more than the links need.
+  Nodes that belong together go into a group (`add_group`), with a comment on what they do
+  (`add_comment`). Both take the nodes they are about rather than a box: a group is drawn around
+  them, a comment just above, and when the call arranges its nodes they follow them there, still
+  in the same undo step. The group is the one *Group* in the graph's menu draws around a selection.
+- **Variables in a graph.** A Variables node reads (and with `set_port_write` writes) a variable
+  once `add_port` names it; the port takes the kind of the variable. Properties and Sound FX
+  parameters nodes work the same way, a start or end node or a struct gets ports of a kind given.
+  A port naming nothing the node knows is refused with the names there are.
 - **Deleting asks you.** A call that deletes an asset that was there before opens a dialog
   *The agent asks: Delete "..."?* with the same text as your own Delete. The call waits for your
   answer, up to 110 seconds; Cancel, Escape or no answer leave everything as it was.
@@ -112,13 +122,22 @@ it. One Ctrl+Z takes the whole call back.
 - **While the game runs** a change goes into the running copy, as yours would, and the answer says
   it is gone when the game stops.
 
-The 24 commands so far: assets (`create_asset`, `rename_asset`, `duplicate_asset`,
-`delete_asset`, `set_asset_property`, `reset_asset_property`, `set_start_scene`), variables
-(`add_variable`, `remove_variable`, `rename_variable`), placed objects (`place_asset`,
-`remove_objects`, `move_object`, `rename_object`, `set_override`, `clear_override`, `set_parent`)
-and graphs (`add_node`, `arrange_graph`, `remove_node`, `move_node`, `set_node_param`, `connect`,
-`disconnect`).
-Textures, fonts, sounds and videos need a file and cannot be made by an agent.
+The commands come in areas; `catalog` lists them with what each does, and gives the arguments
+for an area or for command names asked for.
+
+| Area | Commands |
+|---|---|
+| assets | `create_asset`, `rename_asset`, `duplicate_asset`, `delete_asset`, `set_asset_property`, `reset_asset_property`, `set_start_scene`, `set_machine_scope`, `set_machine_start`, `set_variables_scope`, `set_variables_persistent`, `make_project_asset` |
+| variables | `add_variable`, `remove_variable`, `rename_variable`, `move_variable`, `set_variable_kept`, `set_variable_private`, `add_struct_field`, `remove_struct_field`, `rename_struct_field`, `move_struct_field`, `set_struct_type`, `make_struct_type`, `set_list_item_type`, `make_list_item_type` |
+| objects | `place_asset`, `remove_objects`, `move_object`, `reorder_object`, `set_editor_offset`, `rename_object`, `set_override`, `clear_override`, `apply_override_to_asset`, `apply_override_to_container`, `revert_override_to_container`, `apply_position_to_container`, `revert_position_to_container`, `set_parent`, `group_objects`, `set_object_group`, `rename_object_group`, `ungroup_objects`, `create_container`, `unpack_container`, `add_collider`, `add_rigidbody`, `add_joint`, `fit_collider` |
+| graphs | `add_node`, `arrange_graph`, `remove_node`, `move_node`, `set_node_param`, `collapse_nodes`, `resize_node`, `connect`, `disconnect`, `fold_edge`, `name_transition`, `add_group`, `add_comment`, `fit_group`, `edit_annotation`, `remove_annotation`, `add_port`, `repoint_port`, `remove_port`, `rename_port`, `move_port`, `set_port_write`, `set_port_machine`, `set_port_default`, `set_node_struct_type`, `split_output`, `set_list_node_type` |
+| project | `rename_project`, `set_layer_names`, `set_play_from`, `set_while_playing`, `set_game_link_zoom`, `set_symbol_scale`, `set_master_volume`, `set_master_fx` |
+
+A change to the fields of a Struct asset reaches every variable and node of that type, as it does
+from the inspector. Animation, sprite frames, tilemaps, pixel art, vector art, songs and
+compositions come next (#429, stage 5).
+Not for the agent, on purpose: textures, fonts, sounds and videos need a file, pasting needs the
+clipboard (the agent builds directly instead), and switching a plugin on would run its code.
 
 A behavior acts on the object it is placed under. The smallest walking object is therefore a
 sprite, a behavior placed with the sprite as `parent`, and in the behavior an `OnKeyHeld` whose
@@ -171,7 +190,8 @@ Claude Code --- MCP over HTTPS ---> /mcp ---> relay (tools/mcp/) <--- WebSocket
 - A call has 30 seconds. One that asks you something (a delete) or plays the game for more than 5
   seconds tells the relay to wait, and then has two minutes.
 - `tools.json` holds each tool's argument schema; the editor checks every call against it
-  (`argCheck.ts`). The commands and their schemas are in `commandCatalog.ts`, the all-or-nothing
+  (`argCheck.ts`). The commands and their schemas are in `catalog/`, one file per area, gathered
+  in `commandCatalog.ts`; the all-or-nothing
   undo step in `editPlan.ts`, the reading tools in `readTools.ts`.
 
 What is behind it on the server, and the routes it uses: [API](API), [Development](Development).
@@ -188,11 +208,16 @@ What is behind it on the server, and the routes it uses: [API](API), [Developmen
   undo, a failing step that leaves nothing, argument checks, deletes that ask, nodes arranged at the
   end of a call while placed ones stay, `arrange_graph`, what the editor shows after a call (and
   the scene switch inside the undo step, and nothing with *Follow agent* off), the reading tools
-  and the catalog.
+  and the catalog (every area in full under the size an answer is cut at).
+- `tests/editor/agent-catalog.test.ts`: a Variables node reading a variable once `add_port` names
+  it (and refusing a name it does not know), a group and a comment fitted to the nodes after the
+  call arranged them, a field of a Struct asset reaching the variables of that type, a container's
+  content listed by the ids an override takes, object groups, and the project settings.
 - `tests/editor/graph-arrange.test.ts`: the layout on the graph an agent really built for "walk with
   the arrow keys" (no overlaps, no link over a node, none backwards, at most 8 crossings with one
-  Owner for four moves and 4 with one each), chains running straight, nodes that stay, groups kept
-  clear, loops, and what `lint_graph` counts.
+  Owner for four moves and 4 with one each), chains running straight, the flow on top when two
+  orders cross as often, nodes that stay, a new node placed where its link crosses least and level
+  with the port it feeds, groups kept clear, loops, and what `lint_graph` counts.
 - `tests/editor/agent-play.test.ts`: a held key walks the object as far as the game seconds say, a
   tapped one fires a key-down once, a kept one stays down across calls, a click on an object lands
   and one beside it does not, a call that gives up when the game stands still and lets go of its key,
@@ -203,6 +228,6 @@ What is behind it on the server, and the routes it uses: [API](API), [Developmen
   account menu, an MCP client reading the view, hearing a tab switch and taking a screenshot; the
   agent building a walking object whose graph comes up with its nodes selected and arranged,
   Arrange in the header untangling it as one undo step, the open tab's camera going after a node
-  added far away, the object moving when played, the agent holding the arrow and clicking the
+  added far away, a Variables node with a port and a group framing every drawn node, the object moving when played, the agent holding the arrow and clicking the
   object itself and reading with `get_runtime` how far it went, one Ctrl+Z taking it back, a delete waiting for
   the user's Cancel; and the badge switching it off.