Tools reference

Read diagram. Read the diagram as Flowmark markup, with every node's #id and the current modeling-rule issues. Call this before editing if you have not seen the latest version (the user may have edited it by hand).

For a sequence diagram: its code with every element's id, and the current issues.

For an ER diagram: its schema code with every element's id, and the current issues.

Replace diagram. Replace the whole diagram with new Flowmark markup. Use it to draft a new process or to restructure most of one; use edit_diagram for small changes. Layout and wiring are automatic. Returns the element ids and modeling-rule issues, or a line-numbered syntax error to fix.

Flowmark in brief (lookup_guidance "flowmark" has the full reference):
process <name>
lanes <A> | <B>        optional lane order
lane <name>            following nodes go in this lane
<kind>[:<event>[(<arg>)]] <name> [#id]
  kinds: start end catch throw task user service manual script rule send receive call sub xor and or eventgw
  events: message timer error signal conditional escalation terminate compensation; timer args are ISO 8601 (P2D, PT4H)
Indented lines under a node:
  <label> [<condition>] (default) -> <target>   explicit flow
  on:<event>(<arg>) <name> -> <target>          interrupting boundary event (on~ for non-interrupting)
  doc: <text>           documentation, hidden; one line each (before the first node: the process's)
  note: <text>          a short note shown beside the node; one line per note: line
  => <pool>: <message>  sends a message to an outside pool; <= <pool>: <message> receives one
pool <name> [(below)]  an outside party as a black-box pool, above the process unless (below)
Each node connects to the node on the line above; a blank line starts a new path. Nodes with -> lines, and end events, don't continue. Targets are names or #id; give unnamed or duplicate-named nodes an #id (e.g. "xor #merge").

For a sequence diagram, write sequence code (lookup_guidance "sequence-code" has the rest):
title <name>; actor/participant/database <name> [as <alias>]
A->B: call   B-->A: reply   A->>B: async   A->B ++ / -- starts or ends a bar
alt <cond> ... else <cond> ... end; opt, loop, par (and), break, critical, group
note over A, B: text; == Phase ==

For an ER diagram, write schema code (DBML; lookup_guidance "schema-code" has the syntax). Call read_context once per chat before your first change, for the team's names and rules.

For a sequence diagram: the complete diagram in sequence code.

For an ER diagram: the complete diagram in schema code. |

Edit diagram. Apply targeted edits to the diagram. Prefer this to write_diagram for small changes: it keeps element ids (and the user's references) stable. The batch is atomic: if one operation fails, none apply and the error says what to fix. Nodes and lanes can be referenced by id or exact name. Returns the updated diagram and its modeling-rule issues.

For a sequence diagram: operations on participants, messages, notes, dividers and fragments; participants by id, alias or name, items by id.

For an ER diagram: operations on tables, columns, relationships, enums, groups and indexes; tables by id or name, columns by id or table.column. Call read_context once per chat before your first change, for the team's names and rules.

Each entry in operations is one of the operations below.

Read comments. Read the open comments the user left on the diagram's elements: notes for themselves and for you, such as changes to make or questions to settle. Each comes with the elements it is on (name and id) and its replies. get_diagram says how many are open. Comments are read-only for you; when you have addressed some, say which, so the user can resolve them.

Look up BPMN guidance, Look up sequence diagram guidance, Look up ER diagram guidance. Look up the app's curated guidance: the Flowmark syntax ("flowmark"), modeling style, structural patterns, or a domain reference process (typical roles, steps, decisions, exceptions and KPIs). Use it before drafting in a known domain, or when unsure of the syntax or a pattern.

For a sequence diagram: the syntax ("sequence-code"), drawing style ("sequence-style") and reference interactions (api-request, cache-aside, oauth-sign-in, webhook-retries, queue-async, payment-3ds).

For an ER diagram: the syntax ("schema-code") and modeling style ("schema-style").

List diagrams. List the diagrams saved in the user's Penna, with their diagram_id, name, kind, size, and which one is open in the app.

No parameters.

Show diagram in the app. Show a diagram in the user's app, so they can watch it while you work. It doesn't change which diagram the other tools act on; they take a diagram_id.

Create diagram. Create a new, empty diagram, open it in the app, and return its diagram_id. Follow up with write_diagram to draft it. Call read_context once per chat before your first change, for the team's names and rules.

Read business context. Read what the user's team wrote about their business (roles and teams, systems, the names they use, approval limits, deadlines) and the learnings they saved from earlier corrections. Call it once per chat before your first create_diagram, write_diagram or edit_diagram, and use their names and rules instead of generic ones. The user's request wins when it says otherwise.

Save learning. Save a learning for the user's team: one rule about their business that the in-app assistant and you will follow from now on, such as "Loans over $250k go to the Credit Committee." Only when the user asks you to remember something, or agrees when you offer to after they corrected you. Write about roles, systems and rules, never a named person, contact details or a secret, in one sentence under 300 characters. They can see and remove it in the app.

Show diagram. Show the user a diagram as an interactive picture in the chat, where the chat can display one; elsewhere the result is a link to it in the app. Use it when the user wants to see a diagram without changing it. write_diagram and edit_diagram show the diagram after every change by themselves, so don't call it after them.

Add a node. after/before connect it in the same step.

Change a node's fields.

Remove a node and its flows.

Connect two nodes.

Change or re-route a flow.

Remove a flow.

Split a flow with a new node.

Add a lane (a role or department).

Rename or move a lane.

Remove a lane.

Rename the process or set its documentation.

Add an outside party (customer, supplier, carrier, bank) as a black-box pool: it shows what it sends and receives, not its steps. Your own roles are lanes.

Rename a pool or move it above or below the process.

Remove a pool and its messages.

Add a message between a step and an outside pool, e.g. from a send task to the Carrier pool, or from the Customer pool to a message start event.

Rename a message or move one of its ends.

Remove a message.

Change how the diagram is laid out, not the process: how far apart steps sit, and putting steps moved by hand back in their automatic spots. For requests about spacing, room, readability or tidying the layout; lookup_guidance("layout-and-polish") says which to pick. Spacing steps, tightest first: compact, standard (the default), roomy, spacious.

Set the title, or number the messages.

Add a participant: a system, service or role. Messages add the ones they name, so this is for its kind, alias or column.

Rename a participant, change its kind or alias, or move its column.

Add a message. Without a position it goes at the end.

Change a message's text, arrow, ends or activation.

Add a note. Without a position it goes at the end.

Change a note's text or where it sits.

Add a divider that names a phase, e.g. Checkout.

Change a divider's label.

Move a message, note, divider or fragment.

Put items that sit next to each other in a fragment: alt for conditions, opt for one optional part, loop for repeats and retries, par for parallel work, break to stop, critical, or group.

Change a fragment's kind, or a branch's condition.

Add an else branch to an alt, or an and branch to a par.

Remove a branch of an alt or par and what it holds.

Remove a fragment, keeping what it holds in its place.

Remove a participant (with its messages) or an item (a fragment with what it holds).

Set the schema's name, database or note.

Add a table with its columns. A column's references adds its relationship too.

Rename a table, or change its schema, alias, note, group or place.

Add a column to a table.

Rename a column, or change its type, key, constraints, default or note.

Move a column within its table.

Relate columns: from holds the reference (the foreign key), to is what it points at, usually a primary key.

Change a relationship's cardinality, name or actions, or swap its ends.

Add an enum: a type with a fixed list of values. Set a column's type to its name to use it.

Rename an enum (its columns follow) or replace its values.

Group tables that belong to one area, such as billing or catalog. A table is in one group at most.

Rename a group, set its tables or note.

Add an index, or a composite primary key or unique constraint.

Remove an index.

Add a note of its own to the diagram.

Change a note's text or name.

Remove a table (with its relationships), a column (with its relationships), a relationship, an enum, a group (keeping its tables) or a note.