Runic keeps two kinds of document — process flows and sequence diagrams — as plain text, and draws them while you type. In a process every non-blank line is one node. A line that does not start with a dot is a plain step; a line that starts with . is one of exactly ten commands, and a menu appears as you type it. Indent with two spaces (or Tab) to nest steps under a branch. The diagram on the right redraws on every keystroke and can never disagree with the text — the text is the only source of truth.
Example
User lands on the login page
.if Does the user have an account?
.then Yes
User enters username and password
User presses the login button
.then No
.go Registered
.end
.end
What the editor tells you while you type
The sync chip
Above the editor: In sync (green, pulsing) · Saving… while a change is on its way · Offline — retrying (amber) when a save failed — it retries every 3 seconds and nothing is lost · Check line N (amber) while a line does not parse: the first bad line is named and tinted red in the editor · View only on a team document you can read but not edit.
Autosave
Signed in, text and name changes are sent 600 ms after your last keystroke. Snapshots for version history are taken automatically about every ten minutes of editing.
New nodes
A line you just added grows in at its place in the diagram (skipped when more than 30 lines arrive at once, e.g. a paste).
Empty document
The flow pane reads “Nothing to draw yet — Describe the first step in the editor and the flow will appear here as you type.” The editor placeholder: “Describe each step on its own line. Type . for commands.”
Errors
A dot-word that is not one of the ten commands is an error line, painted red. A sequence diagram lists its problems under the diagram instead (below).
Creating documents
+ in the sidebar
Two choices: Process flow — “Steps, decisions, sub-processes” — or Sequence diagram — “Actors exchanging messages”. New documents are named Untitled N / Diagram N; a new diagram starts with a seven-line example you can overwrite.
✨ Create with AI
Signed in: describe what you need and Runic writes the first draft — one document, a linked set, or a whole system.
Learn
Avatar menu → Learn opens a ten-step interactive tour in the real editor (signed in): first step, a decision, .wait/.input, a failure, a note, a call to another process, a caption, a loop back, editing the middle.
Docs
Avatar menu → Docs opens this page in a new tab.
Commands
Anything that does not start with a dot is a plain step — one card, connected to the previous one. The commands below add structure. Type . at the start of a line for the autocomplete menu.
.if
Branch on a condition. Press Enter at the end of the line and two .then branches scaffold themselves. Every decision needs AT LEAST two branches — one outcome is not a decision. A menu with many options is ONE .if with one .then per option, never a chain of one-branch .ifs.
.if Does the user have an account?
.then Yes
User signs in
.then No
User registers
WRONG
.if download chosen
.then yes
System downloads it
.if delete chosen
.then yes
System deletes it
RIGHT
.if What does the user choose?
.then Download
System downloads it
.then Delete
System asks to confirm
.then Cancel
Nothing changes
.end
An .if line cannot carry an arrow caption — branch arrows are labeled by their .then labels.
.then
One branch of the decision above it, indented two spaces from the .if; the branch’s own steps go two more. The label becomes the chip on the branch arrow: Yes renders green, No renders red, anything else violet — so menu options, error classes and approval levels all read naturally.
.if How urgent is it?
.then Urgent
Escalate to on-call
.then Normal
Queue for tomorrow
.end
Closes the nearest open .if, at the SAME indent as that .if — the branches merge and the flow continues below. At the top level of the document, .end draws the End pill instead.
.if Is it valid?
.then Yes
Process it
.then No
Fix it first
.end
Archive the request
.note Runs after EITHER branch — .end merged them
.end
Never use .end as a separator — only decisions close and flows end.
.go
Jump to another process and STOP this path — like a goto between flows. The target process gets a reference badge, and renaming it updates every .go pointing at it. Nothing may follow a .go on the same path.
.go Registered
WRONG
.go Check file size
System scans the file
RIGHT
.do Check file size
System scans the file
.do
Call another process and RETURN — the flow continues on the next line. Use it for sub-processes: verification, payment, anything reusable.
Customer submits the order
.do Verify identity
Order is confirmed
.input
A step where data enters the flow — a form, an upload, an answer. Renders with its own INPUT look so data boundaries stand out.
.input Email address and password
.wait
Pause for a time or an external event — a webhook, a human approval, a nightly job. Leave the text empty while you think; the card stays blank until you fill it.
.wait for the bank webhook: confirmed
.fail
Record a FAILURE OUTCOME — a red card. It does not end the path: the lines after it are the recovery (logging, notifications, cleanup) and connect with arrows as usual. A trailing .fail with nothing after it simply ends the branch.
.fail Payment declined
Customer is notified
Retry link is sent: 24h valid
.back
A dashed transition arrow to ANY other step, matched by a few words of its text — an earlier step (a loop or retry) or a later one (skip ahead, say from a mid-flow status straight to a terminal "Cancelled"). No card is drawn — the arrow leaves the box right above the .back line, and the flow continues below it, so several .backs stack multiple arrows off one box. While the target text does not match anything yet, a small hint pill shows in its place.
created
shipping
delivered
close
.back created: cancel order
.back delivered: keep record
archive the order
: caption
Arrow captions, UML-style. End any step line (plain steps, .input, .wait, .fail, .do — and .back for its return arrow) with a colon + caption to label its OUTGOING arrow. The colon needs a space on at least one side; tight colons like https://runic.app or 14:30 never split.
Customer pays: payment confirmed
Order ships
One caption per arrow, by construction: one line, one box, one colon.
.note
A sticky note pinned beside the previous step — context, ownership, edge cases. Several notes on one step stack; in the flow they collapse into a badge you click to read.
Manager approves the request
.note Only above €500
.note SLA: one business day
Rules the parser enforces
Exactly ten commands exist: .if .then .go .end .do .input .wait .back .note .fail. Any other dot-word is an error line (red) and the chip reads Check line N.
.if opens a decision and the next line must be a .then: a plain step directly under an .if, or a second .if before the first .then, is an error. A .then outside an .if is an error; a .then with no label shows “…” on its chip.
.end at the .if’s own indent closes it; at the top level it draws the End pill. An .end indented like a .then only ends that branch — the audit flags it as orphan-end and the decision stays open.
An arrow caption on an .if line is an error — branch arrows are labelled by their .then labels.
.go / .do with nothing after them target “Untitled”; a bare .note reads “Note”. Blank lines are ignored.
Captions split at the first colon that has a space on at least one side (https://… and 14:30 never split). A .go line is the exception: the parser takes everything after .go as the target name — keep .go lines caption-free and put captions on .do lines instead.
A block, for folding, dragging and extracting, is the line plus every deeper-indented line — and, for an .if, its matching .end.
Branch colours
A .then chip is coloured by its label, trimmed and case-insensitive: green for yes, true, evet; red for no, false, hayır / hayir; every other label violet. The editor tints the .then line the same way, so a Turkish document reads like an English one.
How .back finds its target
The words after .back are matched, case-insensitively, against the document’s plain steps and .input lines. An exact whole-text match wins outright; otherwise the first line containing the words wins, plain steps before .input lines. The target may sit above (a loop) or below (skip ahead).
Right after a box (a step, .input, .do, .wait or .fail — notes and earlier .backs are transparent) no card is drawn: the arrow leaves that box and the flow continues below. After a decision, a .go, an .end or at the top of the document, .back draws a card that ends the path.
While nothing matches yet a dashed hint pill shows in its place. Several .backs stack their arrows off one box with staggered captions; the : caption on a .back line labels the return arrow.
Type .back and the menu lists every plain step and .input line of the document (“line N · above” / “line N · below”, up to eight) — pick one and the line is rewritten with the step’s exact text.
Patterns & recipes
Copy-paste starting points for the shapes that come up in every real process. Every snippet is engine-tested: it parses clean and audits clean.
State machine with return arrows
Statuses as steps, transitions as captions, corrections as .back arrows — reads exactly like a UML state diagram.
created: request shipment
shipping: confirm arrival
delivered
close
.back created: cancel order
.back delivered: lost in transit
archive the order
Terminal state fed from mid-flow
A status like "Cancelled" is not part of the happy path — park it at the end and jump AHEAD to it with .back from wherever the exit can happen. The happy chain stays clean; the exits read as labeled transitions.
Order approved
Invoice can be issued
.back Cancelled: cancelled before invoicing
Invoice issued
Paid
Cancelled
Failure with recovery
The failure is an outcome, not the end — the notification and retry still happen.
Charge the card
.if Did the charge succeed?
.then Yes
Receipt is emailed
.then No
.fail Payment declined
Customer is notified
.wait 24h for a retry: retried
.back Charge the card
.end
A menu, done right
One decision, one branch per option — never a chain of separate .ifs.
.if What does the user pick?
.then Export
.do Export the report
.then Share
A read-only link is created
.then Delete
System asks to confirm
.end
Split across processes
.do calls a reusable sub-process and returns; .go hands off for good. Renames follow references automatically.
Customer submits the application
.do Verify identity
.if Approved?
.then Yes
.go Account opening
.then No
Rejection letter is sent
.end
Sequence diagrams
A second document type for who-talks-to-whom. Every line is one interaction between two actors — actors are created automatically the first time they appear, columns follow the order of appearance, and each message becomes the next arrow down the page.
Example
.autonumber
.actor Browser as Client (user)
.actor Auth Service as Auth (service)
.actor Postgres (database)
Client ->+ Auth: POST /login {email, password}
Auth ->+ Postgres: SELECT user by email
Postgres -->- Auth: row
.alt password matches
Auth -->- Client: 200 {jwt, refresh}
.note over Client: tokens kept in memory
.else wrong password
Auth -->- Client: 401
Auth ->> Mailer: failed-login alert
# async — nothing waits for a reply
.loop until the refresh token expires
Client ->+ Auth: POST /refresh
Auth -->- Client: 200 {jwt}
.do Password reset: after three failures
.go Onboarding
A -> B: text
A synchronous call from actor A to actor B (filled arrowhead). Both actors appear automatically. The text after the colon is optional.
A --> B: text
A dashed reply — use it for responses and returned data.
A ->> B: text
An asynchronous send (open arrowhead): events, queues, emails — nothing waits for a reply.
A ->+ B / B -->- A
Activation: "+" right after the arrow marks the receiver busy, "-" on the reply ends the sender’s bar. The busy span is drawn on the lifeline.
A -> A: text
A self message: the actor does something internally (validate, compute, retry).
> text · < text
Shorthands: the same two actors again, same direction and arrow style — or the dashed reply back. No names needed.
.actor Label as Alias (type)
Declare an actor up front to pin its column. Write the alias in messages; the label is shown. Types: user, system, service, database, queue, external — each gets a glyph (aliases below).
.alt / .else / .end
Alternative paths. Indent the messages inside each section by two spaces; .end or a dedent closes the fragment. .else also adds a section to a .critical.
.loop / .opt / .break
A repeated block, an optional block, or a block that leaves the flow when its condition holds.
.par / .and
Things that happen at the same time — each .and starts the next parallel block.
.critical / .group
A block that must not be interrupted, or just a labelled box around some messages.
.note over A: text
A sticky over an actor; ".note A, B: text" spans two, ".note left of A" / "right of A" sits beside one. A bare ".note text" goes in the side column.
.do Doc: caption
A reference box: that other document — a process or a sequence — runs here, then this diagram continues. Click it to open.
.go Doc
Hand off: this diagram ends and the story continues in that document.
.activate A / .deactivate A
An explicit activation bar on an actor that already appears in the diagram — when +/- on the arrows is not enough.
.autonumber · # comment
Number every message · lines starting with # or // are ignored.
Actor types and their aliases
The word in the parentheses of an .actor line picks the glyph. Six types exist; a handful of everyday words map onto them:
user
person · human · customer · actor
system
app · server
service
api · svc · worker
database
db · store · cache
queue
broker · topic · bus
external
third · vendor · ext
Any other word is refused: “(x)” isn’t an actor type — use user, system, service, database, queue or external. An .actor with no name: “.actor needs a name, e.g. “.actor Payment API”.” When label and alias differ, hovering the actor header shows “Label · written as “alias””.
Fragments, precisely
Openers: .loop .alt .opt .par .break .critical .group, each followed by a label; the body is indented two spaces. A dedent closes the fragment; .end closes the innermost open fragment from any indent (“.end has no open fragment to close.” when there is none).
.else adds a section to an .alt — or to a .critical — at the same indent as the opener; .and adds a block to a .par. The four things the parser will tell you: “.else only works inside an .alt — a .loop has a single body.” · “Inside a .par the next block starts with .and, not .else.” · “.and only works inside a .par — use .else for an .alt.” · “.else needs an open .alt at the same indent as its opening line.”
Enter after an opener, .else or .and indents two more. From the command menu .alt scaffolds “.alt ” + an indented line + “.else ” + an indented line; .par does the same with “.and ”; the other openers insert themselves plus one indented line.
Notes: .note over A: text, .note A, B: text (spans both), .note left of A: text / .note right of A: text. Naming an actor that is not in the diagram yet: “X” isn’t an actor in this diagram yet — declare it with .actor or mention it in a message first. A plain “.note some text: more” stays a side note.
.do Name: caption draws a REF box (that document runs here, then this one continues); .go Name a hand-off. Names resolve against every document of both kinds. A name with no document behind it renders as a dashed box (“No document is named “X” — click to create it”) and a click creates a process with that name — never a sequence.
.activate A / .deactivate A need an actor that already appears (“.activate needs an actor that already appears in the diagram.”). .autonumber numbers every message in reading order — the same order the Build Package’s S1.M3 ids follow.
> or < before any message: “>” continues the previous message — but there is none yet. Start with “From -> To: …”. A line that is none of the above: “Not an interaction — write “From -> To: what happens” (or --> for a response, ->> for async, or start with > / < to continue).” An unknown dot-word: “.x” isn’t a command — try .actor, .loop, .alt, .else, .opt, .par, .note, .do, .go or .end.
The sequence editor
The panel under the diagram lists at most four problems (line and a plain-language message) and “+ N more”; the header chip reads Check line N and the line is tinted. An empty diagram shows “Nothing to draw yet” with an Insert an example button (the seven-line starter).
Actor completion: at the start of a line, one letter of a known actor lists up to eight actors (“Message from this actor”; picking appends “ -> ”); after an arrow the partial receiver lists actors (“Send to this actor”; picking appends “: ”).
After .go or .do the menu lists your other documents of both kinds, labelled Process / Sequence diagram, until you type a “: ” caption.
⌘Z / ⇧⌘Z / ⌘Y undo and redo, Tab / ⇧Tab indent, hover-sync with the diagram — all as in the process editor. There is no gray AI suggestion in sequences.
Already have a Mermaid sequenceDiagram? Paste it: it is converted to Runic on the way in, around the caret, with no AI involved (sequence editor only).
Editor tips
Everything the process editor does beyond typing. Most of it works in the sequence editor too; the exceptions are named.
Keyboard
Enter after .if
scaffolds “.then Yes” and “.then No” with the caret in the first branch (only when the next line is not already a .then). Elsewhere Enter keeps the indent and adds two spaces after a .then or .if line.
Tab / ⇧Tab
indent / outdent by two spaces — the caret’s line, or every line a multi-line selection touches. Tab first accepts a visible gray suggestion.
⌘Z · ⇧⌘Z or ⌘Y
undo / redo: the last 15 states per document; keystrokes within 800 ms merge into one step, while a drag, an extract, an AI apply, a chat ↩ Restore or a Version-history Restore always starts a new step. The header buttons do the same; both editors.
⌘-click a .go/.do
opens the referenced document — process or sequence.
Esc
closes the topmost layer, one per press, in this order: fullscreen → icon picker → “Delete document?” → References → Version history → Create with AI → Map → Teams → Upgrade → Feedback. The menus, the gray suggestion, the AI edit bar and the extract name field handle Esc themselves.
Menus and completion
. at line start
opens the Commands menu (“↑↓ navigate · ↵ insert · esc dismiss”). It filters as you type; Esc silences it for that exact prefix until the prefix changes; Enter on a bare “.” just closes it. Inserting .if scaffolds the two branches, .end adds a fresh line. A bare modifier key (⌘, Ctrl, Alt, Shift — say ⌘⇧4 for a screenshot) leaves the menu open; a modifier combo closes it and passes through. The menu flips above the line when the window ends first, so it never covers what you type.
.go / .do
lists your other documents of both kinds — prefix matches first, then alphabetical, at most eight, each with “N lines” or “sequence · N lines”. The menu closes once the typed name equals an existing document, so Enter opens a new line instead of picking.
.back
lists the plain steps and .input lines of this document with “line N · above / below”; a pick rewrites the line with the step’s exact text.
✦ Suggest (gray text)
700 ms after you stop at the end of a non-empty line, the AI proposes the rest of that line or exactly one next line, in gray, with a TAB chip. Tab accepts; Esc, typing or moving the caret dismisses; a reply that arrives after you moved on is ignored. Signed in, process documents, not while a menu, the AI bar, a drag or a fold is active. Turn it off with the footer chip (“AI suggestions are on — click to turn off”); the preference is kept when Preferences cookies are allowed. Failures are silent.
Blocks: fold, move, extract
Gutter chevron
any line followed by deeper-indented lines can fold (“Collapse this block” / “Expand this block”); a folded opener shows a “⋯ N lines” chip. The folded view is read-only — the footer says “Folded view (N blocks) — click or type to edit” and any click or keystroke (arrows, Home/End, ⌘C and ⌘A excepted) expands every fold with the caret mapped to the right place. Handles, the extract bar, the gray suggestion and the AI bar are off while folded. Process documents only.
⋮⋮ drag handle
hover a line and drag the handle: the block (the line, its deeper lines and its matching .end) moves — or the whole selection when the grabbed line is inside one. A card says “Moving N lines”, a violet line marks the landing gap, and on drop the block re-indents to the line it lands in front of and flashes for a second.
Select lines
a selection touching two or more lines (or one whole non-blank line) shows a violet band: the rows you highlighted, plus lighter rows pulled in to keep blocks whole. The floating bar offers Convert to process (“N lines · +N to keep the block whole”) and, signed in, ✨ AI edit and 💬 Copy to chat.
Convert to process
opens a “New process” name field (max 80 characters, pre-filled from the first line, made unique as “Name 2”). The lines become their own process and a “.do <name>” line replaces them at the original indent; a .then, .end or .else inside the range drags its owning .if / .loop / .alt in. Signed in, the process is created first and the document rewritten only after that succeeds.
+ Create as process
a .go/.do whose target names no document tints amber and shows this chip (“No document is named “X” — create it as a process now”); clicking creates an empty process with exactly that name (the caption, if any, is not part of it). The sidebar shows a small amber dot on every document with broken references.
The diagram
Drag on the canvas
rubber-band nodes; the matching lines select in the text and the editor scrolls to them.
Hover either pane
the other pane highlights the twin and scrolls it into view.
Click a step icon
“Change icon”: search up to 98 Lucide icons per query, or press Auto-detect to drop your override and let the text pick (press/click/submit → pointer, mail/send → envelope, …). Overrides are remembered per document and line — with Preferences consent when signed in.
Notes
consecutive .note lines on one step collapse into a single yellow badge with a count; click to read them, click elsewhere to close. Exports print the full text.
Toolbar
Compact cards (60 % width, text wraps taller) · Branch alignment (the first branch continues straight down, or branches centre under the decision) · Tight packing (on by default: arms move aside only where they collide) · Flow direction (top-down ↔ left-to-right; not remembered) · Fullscreen (Esc returns). The first three are remembered.
Zoom
− / + in steps of 25 % between 25 % and 250 %; click the percentage to type one; ⌘/Ctrl + wheel or a trackpad pinch zooms toward the cursor. Sequence diagrams zoom 50–150 % by buttons only.
Go / Do cards
click (or Enter / Space) to jump to that document; a REF or GO box in a sequence does the same. Cross-document jumps are inert on shared and embedded pages.
Sidebar and documents
One list, both kinds
Documents holds processes and sequence diagrams together; a glyph marks the kind, a team badge the team, the number on the right the non-blank line count. A document referenced by exactly one other document nests under it (up to three levels); the parent’s glyph becomes a collapse chevron and the collapsed state is remembered. Opening a hidden child expands its ancestors.
Search
“Search documents” above the list; press / anywhere outside a text field. Every word must appear in the name, any order; accents and the Turkish dotted/dotless i are ignored (“giris” finds “Giriş”). Matches are highlighted, “N of M” counts against every document, and documents under a collapsed parent or in a folded group are found too. ↑ ↓ select, Enter opens, the first Esc clears.
Groups
names written “Prefix · Name” group themselves once three top-level documents share the prefix: one header “Prefix (N)”, the rows without the prefix. Click it to fold; past 60 documents every group starts folded, and the group holding the open document stays open. Folded groups are remembered with Preferences consent.
Drag a row
drop in the top or bottom 30 % of another row to reorder before / after it; drop on the middle 40 % to append “.do <dragged name>” to that document (no-op if it already references it, or is view-only).
Reference pill
“Referenced by N places — click to list” opens the References panel: one row per call site (“<caller> · line N” and the line); click a row to jump there, selected and flashing. Esc or a click outside closes it.
Rename
click the name in the top bar (max 80). Names stay unique across both kinds (“Name 2”), and every “.go/.do <old name>” line in your editable documents — processes and sequence diagrams — is rewritten to the new name, indent and caption kept.
Delete
the trash icon next to the name: “The process, its version history and any share or embed links stop working immediately. This can’t be undone.” Deleting the last document leaves a fresh “Untitled 1”.
Hide / resize
“Hide sidebar” collapses it to a 48 px rail of initials; drag its right edge between 150 and 420 px (default 192).
Map
“Map” in the top bar draws every document of both kinds — processes as circles, sequences as rounded squares, sized by line count — with .do (violet) and .go (blue) links and dashed red missing targets; hover to see “<name> — N lines · called by K documents”, drag nodes, wheel to zoom, Fit, click a node to open it.
Saving, history and sync
Version history (clock)
signed in, both kinds: a snapshot is taken automatically when the newest is more than ~10 minutes old and the text changed. Rows show the time, “N lines · same as now” or “now +A −R”, the first 40 characters, and Restore (asks first — “Restore this version?” with the time and the lines it changes — then saves the current text as a version, writes the snapshot back and offers Undo in a toast; ⌘Z undoes it too). Press “+ name” to pin a snapshot (max 60 characters): a snapshot you name never rolls off, whoever took it; unnamed ones are kept 50 deep. An MCP chip marks “Before Claude edit (MCP)” / “Before Claude restore (MCP)” snapshots — while they carry that automatic name they roll off with the newest 50, and naming one yourself pins it like any other row (clearing the name lets it roll off again). An OVERWRITTEN chip marks “Before a concurrent overwrite”: the text a save replaced when someone else — another tab, a teammate, Claude — had changed the document since that tab last saw it; those rows have their own pool of 50. The list shows up to 200 rows.
Coming back to a tab
when nothing is unsaved, the document list is refreshed on focus; if Claude changed a document over MCP a toast says “Claude edited “Name” over MCP while you were away.” with a History button.
Footer
“N lines · saved just now” under the editor — the chip above it is the one that knows about failed saves.
Panes and appearance
Dividers
drag to resize: the editor 260–720 px (default 408), the chat 240–520 (default 300), the sidebar 150–420 (default 192); sizes are remembered. The editor and the chat each collapse to a 40 px rail (“Collapse the text editor” / “Open AI chat”). Below 1024 px the layout narrows: a tablet keeps the panes side by side with the sidebar on its rail (it opens as a drawer) and the chat over the diagram; a phone (under 768 px) shows one pane at a time behind a Text | Diagram switch, opens the documents — search included — in a drawer from the Documents button and the chat full screen from ✨.
⤢ Fullscreen
hides sidebar, editor and chat; Esc brings them back.
Dark mode
avatar menu → Dark mode / Light mode — see Settings.
Power features
The moves you’ll use every day. Keyboard: ⌘Z undo · ⇧⌘Z or ⌘Y redo · Tab accept a gray suggestion, else indent · ⌘Click a .go/.do jumps to its document · Esc closes whatever is open, one layer per press.
.flow Payments
Check amount
.if Above 500?
.then Yes
Manager approves
add MASAK screening above 500
+3−0suggested edit
+ .if Above 500?
+ .then Yes
+ Manager approves
Apply
IMPORT
Import a whiteboard photo or Mermaid
Drag a screenshot onto the chat, paste one from the clipboard, or use 📎 Import flow (Mermaid files welcome). The agent translates it into Runic — as a new document, or merged into the open one. Steer it: “import as new” / “merge into this”.
.note refund v2
.do Notify owner
.do Log request
.do Send refund
Notify owner
Log request
Send refund
SELECT
Select in either pane
Select lines in the text, or drag a box over diagram nodes — it is the same selection. The floating bar offers Convert to process, AI edit and Copy to chat wherever the selection came from.
.if Payment flagged
Check card details
Match billing address
.do Verify payment
.do Notify customer
.note Log outcome
Extract to process
STRUCTURE
Fold, reorder, extract
Chevrons fold any indented block for reading — the folded view is read-only, a click or keystroke opens it again. Drag the ⋮⋮ handle to move steps with their children and matching .end. Convert to process lifts a selection into its own linked process and leaves a .do line in its place.
1.do Check amount
2.if Amount > $500⋯ 5 lines
3Yes .do Manager signs
4.do Send contract
5No .do Auto approve
6.note log the total
7.go Review queue
8.do Close request
HISTORY
Versions, undo, redo
Undo/redo cover your last 15 states per document — ⌘Z and ⇧⌘Z in both editors. The clock icon opens version history: a snapshot is taken automatically every ~10 minutes of editing; press “+ name” on a row to pin it forever; Restore asks first and can be undone. In the sidebar, drag rows to reorder, or drop one onto the middle of another to add a .do call to it.
The AI agent
The chat panel on the right of the editor is an agent scoped to the open document — a process or a sequence diagram. It proposes, you decide; everything it applies stays reversible.
.flow Payments
Check amount
.if Above 500?
.then Yes
Manager approves
add MASAK screening above 500
+3−0suggested edit
+ .if Above 500?
+ .then Yes
+ Manager approves
Apply
CHAT
Ask for a change in plain words
Type what should happen in the chat panel (open by default on the right; it works on processes and sequence diagrams alike). A change comes back as a green/red diff with the words “nothing is applied until you say so”. Click Apply to accept, Discard to drop it. An ambiguous request gets one precise question back instead of a guess.
✓Applied+2 lines
↩ Restore
every change is a checkpoint
.if Above 500?
.then Yes
Manager approves
Auto-approve
.note Log outcome
CHECKPOINTS
Undo any applied change, any time
Every applied change keeps a ↩ Restore button on its chat entry. Click it — even much later, even after more edits, even from inside an archived stretch of the conversation — and the document returns to how it was before that change.
Previewing suggested change
✓
Intake
Review
Payout
Above 500?
PREVIEW
Judge suggestions as a diagram
While a proposal for the open process is pending, the visual flow renders the suggested document with new or moved steps glowing green. Apply or Discard right from the banner on the diagram; any edit of your own ends the preview.
.flow KYC
Collect ID
Verify address
Screen sanctions
Copy to chat
make failure paths explicit
KYC · L2–L3
SELECTION
Scope the agent to exact lines
Select lines in the editor and press “Copy to chat” on the floating bar (or “AI edit” for a one-shot change without a chat turn). The chip pins your selection; the agent may rewrite only those lines — the rest of the document is off-limits by construction.
⚙ Audit
L4decision has no No branch
L9unreachable step
L12no failure path
analystNo KVKK consent collected
analystRoles undefined for refunds > 5000
AUDIT
Run the two-stage audit
Click “⚙ Audit + AI review” under the chat of a process. Instant checks flag structural gaps — one-branch decisions, empty or identical branches, unreachable steps, dead or ambiguous .back targets, a retry that falls through into guarded work, options lost to an arrow caption — with clickable line numbers; then an AI analyst reads for what the document does not say: failure paths, roles, thresholds, validations. Every code is explained below.
📦 Refunds rework · archived
Suggested: manual review above 5000
do what you suggested
Manual review above 5000
synced to your account
MEMORY
Refer back — it remembers
Say “do what you suggested” and the agent knows. Long conversations fold into summaries that keep every name and number verbatim, the agent recalls the archived messages that match what you just said, and the whole chat follows your account to any browser.
Three kinds of reply
The chat (open by default on the right, signed in) works on the open document of either kind. Enter sends, Shift+Enter breaks a line; while it works the panel cycles “Reading the process…”, “Thinking it through…”, “Writing…”. Every reply is one of:
EDIT
a complete revised document. The chat shows “Here’s the change — nothing is applied until you say so:” with a diff (+added / −removed, one line of context, 14 rows then “… N more rows in the document”), Apply / Discard, and “previewing in the diagram →” while the flow pane shows the proposal (processes). If the reply equals the document: “The document already does that — no changes needed.”
NEWDOC
a new document of the open document’s kind, named by the AI (made unique, at most 80 characters, “Imported flow” as the fallback), opened and typed in: “Imported as a new process: “Name” ✓”. The structural check runs on it.
ANSWER
prose, citing line numbers counted from 1; when the model searched the web the answer ends with “Sources:” links.
Checkpoints
an applied proposal shows Applied ✓ and ↩ Restore (at any time, even from an archived stretch of the chat); a discarded one “Discarded”; a proposal whose base no longer matches the document “Superseded — the document moved on”. Apply is enabled only for the same document with the same text underneath. On a team document you can only read: “X is view-only for you — ask an editor to apply this.” Restore puts an entry on the undo stack, so ⌘Z undoes it too.
The meta line
under every reply, in capitals: the model label — sonnet, haiku or opus for Claude, otherwise the model id without its date suffix — plus “· web research” when the model actually searched and “· self-checked” when the repair pass changed the text (which model answers what).
Ask before assuming
An ambiguous change — which step, which branch, an unstated threshold, role, system, SLA or retry count, a name that exists neither in the document nor in your workspace — comes back as an ANSWER with one precise question listing the candidates, not as an edit. A value you leave open lands in the document as .note TBD: …, in the document’s language. “Do that” / “apply those” builds the edit from the conversation. When a detail lives only in an archive summary, or in a history message that ends “[… truncated]”, the agent asks instead of inventing. Every untouched line is copied verbatim into an EDIT; web search is used only for external, current or domain knowledge (regulation, best practice, benchmarks, how the industry does it), and EDIT / NEWDOC bodies never contain links.
Audit + AI review — the codes
⚙ Audit + AI review (row above the input; processes only) runs two stages. Stage 1 is instant and deterministic: “Structural checks on “X” — N findings. Now reading it like an analyst…” (or “… — clean: decisions have branches, every step is reachable. …”) with clickable L12 rows — amber is a warning, grey a hint, “•” a document-level finding. Stage 2 sends one chat message on the heavy tier, web search off, asking a senior business analyst who must sign the process off to name, per finding, the exact line, what is missing or risky, and the concrete line(s) to add — in the document’s language. After every AI write into a process (an applied proposal, a Create with AI draft, an import, an inline edit, the main flow of a system) stage 1 re-runs on its own and posts “Structural check on “X” — N issue(s) in what was just written (run ⚙ Audit + AI review for the analyst pass):” only when it found something. It never edits.
Code
Level
What it means for you
single-branch-decision
warn
“This decision only covers "Yes" — what happens otherwise?” A decision with one branch (or none) is not a decision — add the other .then.
empty-branch
warn
“The "No" branch is empty — what actually happens on this path?”
identical-branches
warn
Two .then labels on one decision read the same — name each branch by its own answer.
not-a-question
hint
The .if text does not read as a question — phrase it so that each .then is an answer to it. Also an .if with no condition at all.
unreachable
warn
A line after a .go or an .end on the same path can never run — move it up or remove it.
dead-back
warn
“.back X” names no step: the target must be a fragment of an existing plain step or .input line, without its “: caption”. Also a .back with no target.
ambiguous-back
warn
“.back X” matches N steps (lines a, b) — the arrow lands on line c. Copy a longer fragment that names only the intended step; if two steps read exactly alike, reword the intended one.
input-caption
warn
You wrote “.input Field: option A, option B” and the options became the arrow’s caption. Write them in parentheses inside the field text: “.input Statü (oluşturuldu, başarılı, başarısız)”.
orphan-end
warn
This .end is indented like a .then, so it only ends that branch and the decision above is never closed — outdent it to the .if’s indent.
guard-fallthrough
warn
A branch ends with a retry .back (to “Enter PIN”, say), so after the .end the flow continues into the guarded work anyway — the check did not guard anything. End that path instead (.go, or .back to a later terminal step), or nest the steps below inside the other branch.
top-guard
hint
The first decision asks who may run this document, with one branch that only refuses. Who may run a document belongs in a .note on the first line — start the flow at the actor’s first real action.
reads-like-two-steps
hint
A long step with “ and ”, “ & ” or “, then ” probably bundles two actions — worth splitting.
no-failure-path
hint
Eight or more steps and nothing branches or fails — does every run really go perfectly? (the “•” row)
Sequence diagrams have their own checks — request-without-reply, unclosed-activation, single-section-alt, single-section-par, empty-fragment, lonely-actor, silent-receiver, no-failure-path, unpinned-actors, unknown-reference. There is no audit button on a sequence yet; they run inside the AI’s self-check and through the MCP tools audit_document and lint_text.
The self-check (“· self-checked”)
Every document the AI writes — a chat EDIT or NEWDOC, a Create with AI draft, a planned document, an import — is parsed and audited before you see it. The hard findings for a process are single-branch-decision, unreachable, empty-branch, dead-back, identical-branches, orphan-end, guard-fallthrough, input-caption and ambiguous-back, plus unknown-reference (a .do/.go naming no document you have or the reply creates); for a sequence: empty-fragment, single-section-par, unclosed-activation and unknown-reference. A parse error counts ten. When the score is above zero the same model gets one correction call with a validator report quoting each offending line and the rule that fixes each code (add the missing branch, retarget the .back, move options into parentheses, replace a guard .back with a .go, spell the reference exactly, keep text as a .note if a line cannot stay). The fix is kept only if it scores lower, adds no parse error, was not cut off, and every original line is still present verbatim — a line the report named may only become the rewrite its code allows. For a chat EDIT the baseline is your document: findings already in your text are your structure and are left alone.
Selection: AI edit and Copy to chat
Select lines (or rubber-band nodes) on a process, signed in. AI edit opens an instruction bar (“Describe the change — e.g. require manager approval above 500”); Enter or Suggest asks; the Suggested change panel shows +N / −N and a row diff with Discard / Apply. Apply splices the exact range, flashes it, runs the structural check and shows “AI edit applied” with an Undo for 15 seconds. No chat checkpoint is written — route through Copy to chat when you want one.
Copy to chat pins a chip “doc · L4–L9” (✕ detaches it) and the placeholder becomes “Describe the change for the selected lines…”. Your next message may rewrite only those lines; the reply reads “Here’s the change for L4–L9 — nothing is applied until you say so:” and is an ordinary checkpoint. If the document changed since you selected: “That selection no longer matches the document — select again.” Attaching a file drops the chip — one intent per message.
Both go through the same route: 30 per hour, the instruction up to 4,000 characters, the selection up to 20,000 (longer is refused: “That selection is too long for one edit — select a smaller region.”). The model sees the document with the selection marked and must return only the replacement, closing no .if it did not open; the mid tier answers.
Import a screenshot or a Mermaid file
📎 Import flow takes png, jpeg, webp, gif, .mmd, .mermaid, .md and .txt; you can also drop a file onto the panel or paste an image into the box. Images are downscaled to 1,568 px on the long side first (“⚠ That image is too large even after downscaling — try a tighter crop.” past ~5 MB); text files are read up to 20,000 characters. The heavy tier translates nodes and edges faithfully into the open document’s language — decisions → .if/.then, failures → .fail plus recovery lines, loops → .back with a caption, arrow labels → captions, other processes → .go/.do; for a sequence, .actor lines left to right, the three arrows, activation, fragments and notes — and answers with an EDIT (merge into the open document) or a NEWDOC (a separate one). Steer it with “merge into this” / “import as new”. Unreadable parts become a .note of what to check, never invented steps.
Memory
One conversation per account — not per document — saved 600 ms after every change (up to 400 KB), so it follows you to any browser. The live window is about 12,000 tokens; when it overflows and more than eight messages exist, everything older than the newest eight folds into an archive (“📦 N archived”, up to 20 kept) with a summary of up to ~150 words that keeps every step name, role, amount, threshold, SLA and document name verbatim (the fast tier writes it; until it lands the row reads “N earlier messages, starting with: …”). Expand an archive to read the originals; applied proposals inside keep their Restore. Each turn carries the newest 30 turns (6,000 characters per message, 48,000 in all — a cut ends with “[… truncated]”), up to six archive summaries, and the three archived messages that share the most words with what you just wrote; the agent treats both as real and asks rather than invents when a detail is only in a summary. Proposal bodies never travel again — a message with a proposal is sent as “[proposed an edit to “doc” — applied]”. Clear wipes conversation, archives and checkpoints.
Open questions — the interview
After Create with AI produces a linked set of processes — or right after a whole system — the chat shows an Open questions panel above the input: “answered / total”, Skip, ✕ “Close the queue”; rows read “doc · topic” (validation, decision, failure, timing, permission, data) and are marked ○ pending, ▸ current, ✓ answered, – skipped. For a linked set the questions are written by a reviewer call (5 to 10 that would change the diagram — validations, thresholds, what happens when things fail; 20 runs per hour; the reviewer reads up to 40 documents of 20,000 characters, 120,000 in total): “The draft covers the happy path. I have N questions that would change the diagram — …”. Each question switches the editor to the document it is bound to and posts “doc · topic” and the question. Your answer is sent for that bound document even if you navigated away (the bubble shows “[answer → “doc”]”), wrapped as “Update this process so the answer is reflected where it belongs — a validation step, an .if decision, a .fail with recovery, a .note threshold or a .back retry …”. When the reply is a proposal the queue waits for your Apply or Discard before asking the next question, so two answers never race on one document; an ANSWER moves on at once; a failed request leaves the question open; Skip releases a waiting proposal. If the bound document was renamed or deleted: “I can’t find “doc” anymore — skipping this question.” The end: “That’s the whole queue — X of N answered, M change(s) applied to the documents. Ask me anytime to go deeper on one.”; ✕ posts “Interview closed — the remaining questions are dropped.” The queue lives in the session only; the posted questions stay in the chat.
Limits and guards
Feature
Per hour
Sizes and time
Chat
60
message 4,000 characters (longer is cut) · document up to 60,000 characters — longer answers “This document is too long for chat (N of 60,000 characters) — split it into linked processes.” · 150 s per turn
AI edit / Copy to chat
30
instruction 4,000 · selection 20,000 (refused beyond) · 120 s
Gray suggestions
240
the last 3,000 characters before the caret · at most one line back · every failure silent
Archive summaries
30
the folded messages up to 60,000 characters · no verified-email requirement
Interview
20
40 documents × 20,000 characters, 120,000 in total · 120 s
Create with AI (one kind)
10
brief up to 12,000 characters — longer is refused with “Your brief is N characters — the limit is 12,000. Shorten it, or split it into two documents.”, never cut · 180 s
Whole system
10 plans · 300 documents
brief 12,000 · 300 s per call · four documents in flight
Build
12 shared
questions 120 s · spec 180 s · 40 processes + 20 diagrams · 20,000 characters per document, 120,000 in total
AI key saves
10
“Too many attempts — try again in an hour.”
Every AI route needs a signed-in account with a verified email (“Verify your email to use AI features.”), except archive summaries. On Runic’s key a monthly budget applies as well — see Models, budget & cost.
The output budget follows the document’s size. A reply cut off at its budget is retried once with twice the room (up to 24,000 tokens); a second cut answers “The reply was too long to finish in one go — select the part to change, or split the document into linked processes.”
Shrink guard: an EDIT that returns fewer than half the lines of a document of four or more lines, when you did not ask to remove, delete, shorten, trim, split, merge, simplify, replace or rewrite anything (in English or Turkish), is refused: “The AI returned N lines for your M-line document — it may have dropped steps, so no change was proposed. Try again, or select the lines to change and use AI edit.”
A reply that ignores the protocol is shown as plain text. Errors post as “⚠ message” in the chat, under the AI edit bar, or inside the Create with AI dialog.
Whole-system generation
One brief in, every process and sequence diagram a product needs out — planned first, written in waves, linked, checked, and followed by the questions the brief did not answer. It is the default choice of ✨ Create with AI in the sidebar (signed in, verified email): the dialog’s What to create radio offers Whole system · Process flow · Sequence diagram, and reads “Describe the product or operation in plain words. Runic plans it, writes every process and sequence diagram it needs, links them, then asks what the brief left open — and packages it for Claude Code and Claude Design.” The brief may be up to 12,000 characters; a longer one is refused with “Your brief is N characters — the limit is 12,000. Shorten it, or split the product into two briefs.”, never cut. ⌘/Ctrl + Enter or Create starts; Esc and the backdrop are inert while it runs.
Order-to-cash for a shopCreate with AI
=== PROCESS: Order intake ===
.do Payment
.go Fulfilment
=== PROCESS: Payment ===
=== PROCESS: Fulfilment ===
PLAN
1 · A plan before any document
Pick Whole system in Create with AI (it is the default) and describe the product or operation. Runic plans first: every process, back-office operation and integration, the actors, the entities with their closed status lists and one owner per transition, the brief’s own numbers and names pinned to the documents that must carry them — and a list of what the brief left open.
Open questions0 / 31 / 3Skip
▸✓
What happens when the charge is declined?
Payment · failure
○▸
Who confirms the shipment?
Fulfilment · owner
○
Which orders are held for review?
Order intake · edge case
Retry once, then notify↑
Charge card
Retry, then notify
Ship order
QUESTIONS
2 · The open questions come to you
Once the documents are written the plan’s open questions arrive in the chat one at a time, each bound to the document it is about. Answer in your own words; the agent proposes the edit to that document, waits for your Apply or Discard, then asks the next. Skip what does not apply.
1 · Brief → plan
The button reads Planning… and the dialog narrates “Reading your brief…”, “Planning every process, back-office operation and integration…”, “Pinning the brief’s facts to the documents that must carry them…”, “Listing what the brief left open…”. The plan is written by Claude Sonnet 5 with extended thinking (10 plans per hour). It covers the whole domain with no cap on counts — a real product usually needs 8–30 processes and 3–12 sequence diagrams: the user-facing operations, corrections, cancellations and disputes; back-office rules, approvals, period closes and reconciliation; every integration as a sequence diagram with every human in it as a lifeline; every status transition of a core entity as its own process. Depth follows the brief.
Actors
name, kind (user, system, service, database, queue, external) and goals.
Processes
name, purpose, one owner, trigger, the documents it calls, and its rules — the brief’s own names, numbers, thresholds, roles, systems and channels, verbatim. The first process is the main flow the operator starts from.
Sequences
name, purpose, actors, the process it belongs to, rules. A sequence draws the wire only and never calls the process it belongs to.
Entities
a closed list of statuses and the transitions between them, each owned by exactly one process. A status quoted in any document’s rules that no entity lists is added to the nearest entity.
Assumptions
one line per thing the plan had to take for granted — including a single “Platform” line for everything not drawn.
Open questions
5–12 questions bound to documents, the founder-blocking ones first (bound to the main flow); topics validation, decision, failure, timing, permission, data. Nothing is invented: a missing SLA, percentage, approver or system becomes a question instead of a design.
Names are 2–5 words, unique across processes and sequences (case-insensitive), without a colon, at most 80 characters, and used exactly as .do/.go targets. A reference the plan misspells is matched to the closest name when it is close enough (“Prim Hesaplaması” → “Prim Hesaplama”), otherwise dropped — never guessed. Documents you already have are referenced by name and never re-planned. All text is in the brief’s language. A plan with nothing usable answers “The AI could not produce a usable plan — try again.”
2 · The checklist
When the plan arrives the phase line gives way to a panel: the plan’s name and summary, then “P process(es) · S sequence diagram(s) · done of total written”, then one row per planned document in writing order — all processes first, then sequences — each with a glyph and a process / sequence tag:
○
queued (grey)
◐
writing (violet, spinning)
✓
done (green)
✕
failed (red) — the reason is in the hand-over message
Rows update the moment each document lands while the others are still running. Two lines can sit above the list: Platform, not drawn: A · B, and — in red — “The plan names no entity with statuses — each document may pick its own status words.” The dialog closes itself when the system exists; if nothing could be written it stays open with “None of the planned documents could be written — reason. Try again.”
What “Platform, not drawn” means
The plan draws your domain, not the platform under it. Sign-in and sessions, roles and permissions, audit logs, notification transport, exports, schedulers and cron, settings and generic CRUD are assumed: they become one “Platform” line in the assumptions and, wherever a flow touches them, one step or a .note — “who may run this” is a .note on a document’s first line, never an .if at the top (the top-guard audit hint says the same). Two more things are demoted to platform by construction: a planned process that many other processes call (at least five, or a quarter of them, whichever is more), that no user actor owns and that owns no status transition — an audit log, a notification router; and a scheduler drawn as a diagram between the product’s own components (system, database, queue actors named like scheduler/cron/timer/job) when the brief itself names no timer and the diagram carries no rules. Demoted names leave the plan and every calls list, and appear on the “Platform, not drawn” line. Any .do/.go to such a name — or from a sequence diagram to any process, least of all its own caller — is downgraded, never silently deleted: in a sequence it becomes “.note name” (caption kept), in a process a plain step “name — caption”; only a trailing hand-back .go at the very end of a diagram is removed. The hand-over message lists them (“calls to X were kept as notes or plain steps”).
3 · Documents in three waves
The button now reads Writing…. Wave 1 is the main flow alone, written by Claude Sonnet 5. Wave 2 is every document the main flow calls; wave 3 the rest — each on Claude Haiku 4.5, thinking off, up to four at a time. The finished texts of each wave travel to the next as written siblings (up to 12, 4,000 characters each), so no document repeats another’s steps. Every document is prompted with the plan as a cached context block (name, language, summary, actors, entities and their statuses, the document list, platform names, your existing documents, assumptions), the transitions this document owns and those other documents own (for a diagram: the status writes it may draw), its own purpose, owner, trigger, calls, rules and open questions, and — for the main flow — a section that gives every human real steps and .wait lines. The brief comes last, verbatim.
Every rule appears verbatim; every entry of calls becomes a .do/.go with the exact name; hand-offs only to plan or workspace names, never to a platform name; a trigger is a fact, never re-decided.
No new nouns. A gap the brief does not fill becomes .note karar bekliyor: … (“decision pending”, in the brief’s language) — that is why a generated document carries such notes instead of invented thresholds. Statuses come only from the entity list, quoted; .input names concrete fields with options in parentheses, never after a colon.
After the write: forbidden references are downgraded, the self-check repairs structure with the known names, forbidden references are downgraded again, and unresolved .do/.go targets get one rename-only fix pass (accepted only when it resolves more targets and changes nothing else). Anything still unresolved is reported in the response and the hand-over message, never hidden.
A document is retried once on a network error or a 5xx; a 4xx, a rate limit or a cut-off reply is final. 300 documents per hour; each call may take up to 300 s.
4 · Into your workspace
Sub-processes are created first, then sequence diagrams, then the main flow last — created empty and typed in while its diagram draws — so every link resolves the moment it opens. The entry document gets a numbered name on a clash (“X 2”); any other written document whose name you already have is linked to, not duplicated (“Linked to your existing document(s): …”), and every .do/.go in the set is rewritten to the final spelling, captions preserved. If creation stops half-way (on the free plan with billing on, after ten processes) the note reads “Created N of M documents — reason” and the upgrade dialog opens. The sidebar nests each document under its single caller, the main flow gets the automatic structural check, and the chat opens.
5 · Open questions bound to documents
No extra AI call: the plan’s open questions (up to 20) become the chat’s Open questions queue, each bound to the document — process or sequence — the plan wrote it for; a question about a document that was never written is dropped. The queue starts once the main flow has finished typing itself in, and behaves as described under the interview: the editor switches to the bound document, your answer edits that document, and the next question waits for your Apply or Discard.
6 · The hand-over message
<Plan name> is drafted: 9 processes, 4 sequence diagrams, linked.
Assumptions:
• …
Linked to your existing document(s): A, B.
Could not write: X (reason) — run it again or add it by hand; the other documents still link to that name.
References with no document behind them yet: …
Treated as platform, not drawn: A, B (calls to A were kept as notes or plain steps).
7 open questions follow — answer them or skip; then press Build to package it for Claude Code and Claude Design.
Each line appears only when it applies; without assumptions it reads “Assumptions: none — the brief covered everything the plan needed.”, without questions “No open questions — press Build to package it for Claude Code and Claude Design.” The brief, the plan and the entry flow stay attached for Build during this session, as long as one of the system’s documents is open.
Process flow and Sequence diagram modes
The other two radios write in one call on Sonnet 5 (10 per hour): a single document — or, for a process brief describing distinct sub-operations, a linked set of typically 2 to 12 processes, 4–40 steps each, the first being the main flow. The dialog narrates “Reading your brief…”, “Mapping the processes…”, “Drafting the steps…”, “Adding decisions and failure paths…”, “Wiring the linked processes…”, “Checking the structure…”, “Placing the boxes…”. A single document is named from the first 44 characters of the brief; a linked set is materialised like a system and starts the reviewer interview. Placeholders: “e.g. employee requests vacation; manager approves or rejects; HR records it…” and “e.g. a customer orders food; the app talks to the restaurant and a courier…”.
From flows to a build — the AI handoff
Shape the idea in Runic — by hand or with a whole system generated from one brief — then export a Build Package your AI tools execute. The pipeline below is the whole story; the three steps follow, and every file is described in the next section.
1 · SHAPE
2 · INTERVIEW
Who approves?
What if it fails?
3 · PACKAGE
CLAUDE.md
docs/spec.md
KICKOFF.md
docs/design-brief.md
.zip
4 · BUILD
Claude Code
❯ Reading docs/spec.md…
planning Milestone 1
Design AI
Who approves refunds?
Finance team
Which data is collected?
Email, order ID
docs/spec.md
Approver: Finance
Data: email + ID
INTERVIEW
1 · Answer the analyst
Press Build in the top bar (signed in) and tick which flows and diagrams to include — at most 40 processes and 20 diagrams. Runic asks 5 to 8 questions for what flows can’t express — the stack and its commands, roles and permissions, typed data, failure handling, numbers for the targets, how users sign in, the design tone. Unanswered questions land in the spec as open questions; nothing is invented.
.zip
CLAUDE.md
acceptance criteria are binding
docs/spec.md
KICKOFF.md
docs/design-brief.md
PACKAGE
2 · Read the tells, download the zip
Every branch, message, story and entity gets a deterministic ID (F1.D2.evet, S1.M3, US-4.AC2). You get CLAUDE.md under 150 lines, a plan-mode KICKOFF.md, docs/spec.md with a roles × permissions matrix, typed entities, contracts derived from your sequences and ID-cited acceptance criteria, vertical-slice milestones, a Claude Design brief, path-scoped .claude/rules for the DSL, hooks when the test command is known, and your flows and diagrams as source. Ten mechanical tells show what is still thin before you download; four copy chips hand the key files over without unzipping.
Claude Code
KICKOFF.md
❯ KICKOFF.md · 214 lines pasted
Plan mode: Milestone 1 — 6 tasks
waiting for your approval
HANDOFF
3 · Paste the kickoff
Run claude --permission-mode plan in the folder and paste KICKOFF.md. It reads YOUR files in order, scaffolds in Milestone 0 if the stack is unknown, asks for the sign-in method if nothing in the package says it, then per milestone: plan, branch, failing tests named by ID, implement, verify, fresh-context review, commit — and asks only for the four reasons the prompt names. For screens, copy the design brief into Claude Design.
Before you press Build
Build sits in the top bar between AI chat and Map (signed in; the two AI calls need a verified email). The modal — “📦 Build Package” — asks for a Project name (max 80; prefilled with the plan’s name when you arrive from a whole system, else the first process, else “My product”), then lists Processes in the package — the spec is written from these and Sequence diagrams with a checkbox and line count each: all ticked, or only the system’s own documents when seeded. “P of N processes · S of M diagrams selected.” At least one process must be ticked.
Caps: at most 40 processes and 20 sequences — more is refused with “A build package holds at most 40 processes and 20 sequences (P processes and S sequences picked) — untick some documents.” Each document is clipped at 20,000 characters and 120,000 in total, the cut announced inside the text so the model asks rather than assumes.
Stage 1 (“Reading your flows…”): 5 to 8 questions, written by Sonnet 5 with thinking, about roles and permissions, data per step, failures and edge cases, external systems, volume — and, only when neither the brief nor the flows answer it, the stack and its exact install/run/test/lint/typecheck commands, numbers for the targets (p95 latency, monthly availability, data retention, session length, concurrent users), the sign-in method and identity field, the target platform and 3–5 tone words. A plan assumption is confirmed once as a yes/no. “Answer what you can — unanswered questions land in the spec’s Open Questions so nothing gets invented.”
Stage 2 (“Writing the specification…”): the typed spec, written on the heavy tier — Claude Sonnet 5 with thinking; Opus 5 only when the owner set ANTHROPIC_MODEL_HEAVY. Your answers travel as up to 12 Q/A pairs (questions cut at 500 characters, answers at 2,000, a blank one as “(not answered)”); the flows are reordered entry-first and the ID index is appended so the model copies ids and never invents them. One retry when the JSON is invalid; then “The AI could not produce a valid spec — try again.” with your answers intact. The two stages share 12 calls per hour (“Build limit reached — try again in an hour.”).
The seed from a whole system — brief, plan, entry flow — lives in this session only and is attached only while one of that system’s documents is open. With it, the entry flow is put first (F1, Milestone 1) when ticked; the brief goes verbatim into the spec and the design brief; actors, assumptions and entities into both AI calls and CLAUDE.md’s gotchas. Reload, or open Build from an unrelated document, and the package is unseeded with every document ticked.
The Build Package
What is in the zip, how the ids tie the files together, what the ten tells check, and how to get the same package over MCP.
Every file and what it is for
File
What it is for
CLAUDE.md
Claude Code’s standing instructions, under 150 lines: Source of truth (docs/spec.md and the .runic files outrank code; the product’s UI language is the brief’s, never translated), Stack & commands (language, framework, database, then install / dev / test / test one / lint / typecheck / migrate — “TODO(M0): …” for anything unknown), Repo layout, Conventions that differ from defaults (names verbatim; entities and fields only from §Data model; sign-in and identity field; one “State of E-X: field ∈ {…}” line per entity; every .fail a distinct user-visible state with its recovery; external systems stubbed in tests; async messages need a transport decision logged in docs/decisions.md; tests named after ids), Verification, Workflow (one branch per milestone m<n>-<slug>, commit “m<n>: … (US-…, F…)”, PR body = the acceptance checklist, never merge red, never edit the .runic files), When to ask vs. decide, Gotchas (failure paths that continue vs. end, unconfirmed planning assumptions), Compaction.
KICKOFF.md
The first message for claude --permission-mode plan, under 40 lines: read CLAUDE.md, docs/spec.md, docs/plan.md, docs/design-brief.md and every flow and sequence, in that order; Milestone 0 when a core command is unknown (propose stack and commands, scaffold, one green test, replace the TODOs, add the test hook and the guard, commit “m0: scaffold”, stop for approval); Before M1 when nothing in the package says how users sign in — ask for the method and identity field first and log it; then per milestone: plan mode → branch → failing tests named by id → implement (the Verify sentence is the exit condition) → a fresh-context subagent reviews the diff → commit and PR with the ticked checklist → ask before the next. Ends with the ask-vs-decide sentence and the Never list.
docs/spec.md
Overview (product one-liner, problem, goal, scope, out of scope, success metric, the brief verbatim, the planning assumptions), Personas and the plan’s actors, Roles × permissions (one row per R-role, one column per subject, plus the sign-in line), Flows (per F: file, an ID | Kind | Text table of decisions, branches, failures, loops, waits and inputs, the source), Data model (per E: typed fields, relations, “Derived from”, a State table From | To | By branch id), Contracts (per S: ID | Caller → callee | Kind | Message | Payload fields | Only when | Failures | Retry | Timeout | Test, then Alternatives & failures), User stories with Given / When / Then criteria that cover ids, Screens (the spec’s, then one derived per flow with empty / loading / error / success read off the flow), Integrations, Non-functional requirements (a WCAG 2.2 AA row is added when none mentions it), Milestones, Open questions (yours, plus contract-payload and NF-gap questions such as “NF gap — sign-in”), Appendix: Interview.
docs/plan.md
The Definition of Done (ID-named tests green, lint and typecheck clean, commit cites ids, Verify walked, decisions logged), the milestone order, then per milestone Scope / Out of scope / Verify / an Acceptance checklist of ids and a /goal line. When the spec brings no milestones they are derived: M1 the entry flow’s happy path, M2 its failures, loops and alternatives, one per further flow, one for sequences nothing calls, last Non-functional hardening. Every branch id, criterion and NF id lands in exactly one milestone.
docs/design-brief.md
Thirteen sections for Claude Design (paste the file alone) or /design @docs/design-brief.md in Claude Code: product and brief, audience & personas, tone & brand, platform & responsive (breakpoints 360 / 768 / 1024 / 1440), navigation & journey in milestone order, screen inventory (SC ids, four states plus domain states), components reused on two or more screens, copy & content rules, accessibility (WCAG 2.2 AA numbers), what to design first, out of scope, every flow embedded with its legend (the first tagged “design this first”) plus an Integration touchpoints table per sequence, handoff.
docs/decisions.md
An empty log with the columns Date | Milestone | IDs affected | Decision | Why | Alternatives rejected.
.claude/rules/runic-dsl.md
The two reading legends and the id legend, path-scoped to docs/flows/**, docs/sequences/** and docs/spec.md.
.claude/settings.json
Only when the test command is known: a PreToolUse guard that refuses edits under docs/flows and docs/sequences (“propose the change in chat”) and a PostToolUse hook that runs the whole test suite after every edit.
Your documents verbatim with one trailing newline, in package order; slugs transliterated (“Ödeme API Akışı” → odeme-api-akisi), deduplicated with -2 / -3.
The zip is store-only and reproducible byte for byte, named <project>-build-package.zip. The one-liner (the plan’s summary, else the spec’s goal, else the project name) is the same string in CLAUDE.md, KICKOFF.md, the spec and the brief — tell 9 checks it.
The id scheme
Ids are assigned from the parsed text — never by the model — so every file cites the same thing:
F1, F2, …
processes in package order; the entry flow is F1.
F1.D2
the second .if of F1, in document order.
F1.D2.evet
its “Evet” branch: the .then label transliterated (ı → i, ş → s, ğ → g, ü → u, ö → o, ç → c), lowercased, non-alphanumerics → “-”, at most 24 characters, duplicates within one decision suffixed -2 / -3. F1.D2.yes and F1.D2.no likewise.
F1.X1 · F1.L1 · F1.W1 · F1.I1
the first .fail, .back, .wait and .input of F1.
S1.M3
the third message of the first sequence diagram in reading order — fragments flattened, the order .autonumber prints; kind sync (->), async (->>) or reply (-->).
S1.A2
the second .alt / .else / .opt / .break section of S1 (.loop, .par, .critical and .group carry no id).
US-4 · US-4.AC2
a user story and its second acceptance criterion; the criterion’s “covers” lists the branch and message ids it proves.
E-SiparişKalemi
an entity: the name with spaces and punctuation removed, casing kept.
SC-3 · R-manager · NF-1 · M2
a screen, a role (ASCII slug), a non-functional row, a milestone.
Every .then branch, every .fail, every .back and every .alt/.else/.opt/.break section is a “branch id” that needs an acceptance criterion. A branch is happy when its own body holds no .fail, .back or .go and it is not nested inside one that does — that is how Milestone 1 is cut.
The ten quality tells
#
Tell
What it checks
1
Branch coverage
every branch id is cited by some criterion’s covers, and no covers cites an id that does not exist.
2
Message coverage
per sequence, the Contracts section has exactly one row per message and mentions every alternative section id.
3
One When per criterion
each US-n.ACk line has a Given cell, exactly one When cell, a Then cell, and at most 5 steps counting “ And ” / “; ” clauses.
4
No placeholders
no TBD, TODO, <placeholder>, _None yet._ or lorem ipsum in any file outside the spec’s Open questions, the interview appendix and the sanctioned TODO(M0).
5
Field closure
every E-X.field referenced in the spec or the design brief exists in a data-model table, and every field is used by a screen, a contract or an .input / .wait / message.
6
Role closure
every persona, plan user actor and user-typed sequence actor is a row of Roles × permissions, and every .if whose question names a role is a column.
7
Numbers in NFRs
at least one NF row, and every row’s target has a digit and a comparator (≤ ≥ < > =, p95 / p99, max / min, at most / at least, under / within / below / above / over, en az / en fazla / en geç / en çok, altında / üzerinde / üstünde / aşmaz).
8
Milestone closure
every branch id, criterion and NF id appears as “- [ ] <id>” in exactly one milestone of docs/plan.md, every milestone has a Verify sentence, and M1’s Scope names exactly one flow.
9
Verbatim consistency
the one-liner is identical in CLAUDE.md, KICKOFF.md, spec and brief; flow, entity and screen names are spelled identically after their id in every file; every docs/flows/<slug>.runic exists; no id-shaped token in plan.md or the brief points nowhere (ids you typed yourself are excused).
10
Budgets
CLAUDE.md ≤ 150 lines with at least four command lines and no inlined legend; KICKOFF.md ≤ 40 lines naming plan mode, branch-per-milestone, ID-named tests and ask-vs-decide; every screen in the brief lists empty / loading / error / success; at least one screen; with two or more screens at least one component reused on two; .claude/rules/runic-dsl.md exists with a paths: frontmatter.
The done screen — quality panel, copy chips, download
“Package ready — N files · N stories · N roles · N contracts · N milestones.” (a part is left out when the spec has none). Then Package quality: “passed/total tells pass” and “score N/100” — ten points per passing tell, green when all pass, amber otherwise — with one row per tell, “✓ 1. Branch coverage — …” or “✗ …” with the detail. A failed tell never blocks the download. Below: Files with sizes, then Copy by hand — Copy kickoff prompt (KICKOFF.md, for Claude Code), Copy CLAUDE.md, Copy spec (docs/spec.md) and Copy design brief (docs/design-brief.md, for Claude Design), each confirming “Copied ✓” for a moment — and Download .zip. The hint under it: “Unzip into an empty folder, run claude --permission-mode plan there, and paste the kickoff prompt. For Claude Design, paste the brief — it stands alone, the designer never sees the repo.”
Export via MCP
The export_build_package tool returns the same files and the same ten tells to Claude Code, claude.ai or any MCP client — with a read-only token — and the build-spec prompt runs the interview with your client’s model, then loops on only: "lint" until lint.failing is empty, fetches the truncated files with paths and writes them into the repo. Over MCP the interview appendix is always empty. Details in Connect Claude (MCP).
Sharing & export styles
Everything lives under the Share button on the diagram. A share link is read-only and always shows the current document — the embed iframe too, so the diagram in your wiki can never rot. Revoke kills the link instantly.
Share links and embeds
Create share link (signed in) flushes pending saves and shows the URL — /s/<token> — already copied: “Copied to your clipboard — paste away. Anyone with the link can view — not edit.” Buttons: Copy, Copy embed, Revoke (“Link revoked — it no longer works.”). A document keeps the same link until revoked; 60 new links per hour per account.
The share page is a navy-headed read-only view (“Shared · read-only”, “Try Runic”) with zoom, hover and the Export menu (processes also get the direction toggle); cross-document jumps are inert. A viewer who keeps it open sees “This flow was updated after you opened it.” with Show the latest version — checked every 45 seconds; pressing it redraws the diagram and updates the title and the export, on both kinds of document, without a page reload. Share and embed pages are not indexed by search engines; an unknown link says “This link doesn’t exist”.
Copy embed copies an <iframe> (800 × 480, lazy, full-screen allowed) pointing at /embed/<token>: a chrome-free diagram that refreshes itself silently every 60 seconds and carries a “Made with Runic” badge.
Deleting the document ends both. Without an account: “Sharing needs an account — sign in so your flows live on the server.” On a team document you can only read: “You have view-only access — ask an editor to share it.”
Images, text and styles
Copy image · to clipboard
a 2× PNG straight to the clipboard (“Copied.”); a browser that cannot: “This browser can’t copy images — download the PNG instead.”
PNG image · 2× resolution
a file named after the document (lower-case, hyphens).
SVG image · scales forever
vector, same styling.
Text · .runic
the plain-text source (“.sequence.runic” for a diagram) — your processes are never locked in.
Markdown · .md — Claude-ready
“# Name”, a fenced ```runic block, and a “How to read this” legend — the process legend or the sequence legend, matching the document. The same file the MCP tool export_markdown returns.
Images export in a style of your choice. The editor never changes; the style dresses the export:
Runic
exactly what you see in the editor
Boardroom
ink on paper — made for print and PDFs
Blueprint
navy grid, cyan lines, monospace type
Midnight
dark — hues survive, lifted to glow
Pastel
soft, rounded, gallery-wall calm
Sunset
warm coral and amber on cream
Custom
pick page, card, ink and accent colours — the whole diagram follows
Your style choice is remembered (with Preferences consent). Notes print in full in every image. When billing is on and you are on the free plan, the three image items carry a PRO tag and open the upgrade dialog; Text and Markdown are always free. An empty canvas says “Nothing to export yet.”
Teams
Avatar menu → Teams (signed in) opens the Teams dialog: “Shared workspaces — teammates see every document that lives in the team. Editors can change them, viewers can only read.” A team is a workspace whose documents every member sees in the same Documents list, marked with the team’s initial.
Create a team
“New team name…” (max 80) + Create team. Needs a verified email; an account may own up to ten teams.
Roles
The creator is the owner: invites, changes roles, removes members, renames, deletes. An editor (“Can edit”) changes the team’s documents. A viewer (“Can view”) reads them: the sync chip says View only, and rename, delete, share and AI apply are off for that document. Invites are editor or viewer only.
Invite by email
“Invite people”: address + Can edit / Can view + Send invite → “Invitation to “T” emailed to x. It’s valid for 7 days and only works for that address.” (20 invites per hour). “Pending invites” lists them with “expires in Nd” and Revoke.
Open links
“can-edit link” / “can-view link” mint a join link for anyone: “Open can-edit link for “T” copied — valid 7 days. Minting a new one revokes the old.” The owner sees the live ones under “Open links” — who made it, “expires in Nd” — with New link (replace and copy) and Revoke. The URL is shown only when it is made; Runic stores a hash of it, not the link.
Joining
The link opens /join/<token>: “Join “Team” on Runic — inviter invited you as editor · sent to email.” Sign in — or create a free account with the invited address — and you join automatically (“Welcome to Team! You joined as editor — taking you to the app…”). An email-bound invite needs that address verified first (“One step left: verify your email address…”).
Members
the list with a role select (Can edit / Can view) and Remove, for the owner. Remove ends that person’s access to every team document at once — the ones they created included, in the app and over MCP — revokes the team’s open links so the same link cannot readmit them, and stops the public share links they made on team documents. Switching someone to Can view stops their share links too.
Editing together
Every save carries the version its tab last saw. When someone else saved in between, the save still lands, the text it replaces is kept in Version history as “Before a concurrent overwrite”, and both people are told with a toast that opens History on that version. A member who loses write access while typing sees “Access removed — not saved” (or “Deleted or access removed — not saved” once out of the team); the text stays on screen and Save a copy keeps it as a document of their own.
Team documents
“+ New process” / “+ New diagram” inside the team (owner or editor) create “<Team> process N” / “<Team> diagram N” and open them. Existing personal documents are not moved into a team. Team documents count against the owner’s plan.
What is shared
The documents — and only those. Chat conversations, checkpoints, preferences, AI keys and MCP tokens stay personal. Over MCP a token reaches what its owner can open in the app: personal documents plus every document of the teams they belong to now, teammates’ included — list, search, resources and the change stream show them, and a teammate’s edit triggers the same update notification. The role decides writing: a write to a team document where you are a viewer fails.
Leave / delete
“Leave team” (“Leave “T”? You lose access…”) and, for the owner, “Delete team…” and Rename. Esc closes the dialog.
Connect Claude (MCP)
Runic ships an MCP server at https://runicflow.ai/api/mcp — Streamable HTTP, JSON-RPC 2.0, protocol version 2025-06-18, server name runic — so Claude Code, claude.ai, Claude Desktop or any MCP client can list, read, search, lint, render, edit, create and share your flows, browse version history and package a build. Claude learns the Runic language automatically: the server’s instructions tell it to read the syntax guide before writing, to lint before every write and to render to show a diagram.
The server never spends Runic’s AI — your client’s model does the thinking. Every tool is deterministic (parse, audit, layout, raster), every prompt is a text template with your document inside. Whatever you do over MCP runs on your own Claude plan or API key and never touches Runic’s AI budget, the usage line under Settings → AI, or a key you stored there.
1 · Get access: a token, or a sign-in
Personal token — avatar menu → Settings → Claude & MCP → Create a token. Tick “Read-only — Claude can read, search, lint and render, but not change anything” for a read-only one. The token (it starts with runic_) is shown exactly once: “Token created — copy it now, it will not be shown again.” Tokens are named Claude or Claude (read-only); you may hold five personal tokens (“Token limit reached (5). Revoke one first.”) and create ten per hour; they never expire and are stored hashed.
Sign-in (OAuth) — claude.ai, Claude Desktop’s connectors and any client that speaks the MCP authorization spec need no token: they discover the sign-in from the endpoint and open Runic’s consent screen. See the connector walkthrough. Up to 20 such connections per account, counted apart from the five tokens.
Scopes — a token is read or read write; write implies read and there is no write-only token. Five tools need write: write_document, create_document, rename_document, restore_version, share_document. With a read-only token each of them answers, as a tool error, “This token is read-only (scope: read). Create a token with write access under Settings → Claude & MCP.” Every other tool, every prompt, every resource and the change stream work with read alone.
Active tokens — the list shows each token’s name, a pill read-only or read · write, an extra oauth pill for connections, “created … · last used …” (or “· never used”) and, for connections, when the access expires. Revoke is immediate — the next call with that token gets 401.
2 · Connect your client
Claude Code — one command, printed with your token by the Settings panel:
Or leave the header out — claude mcp add --transport http runic https://runicflow.ai/api/mcp — and let the client sign in over OAuth instead (any client that implements the MCP authorization spec can): Runic’s consent screen accepts a loopback redirect (http://localhost, 127.0.0.1 or [::1] on any port), which is what a command-line client registers. The server appears under the name you gave it (runic above). How Claude Code lists a server’s prompts and how large a tool result it accepts are its own conventions — see its docs; on Runic’s side export_build_package truncates past ~20k tokens and offers only and paths so a package fits in one reply.
claude.ai — Settings → Connectors → Add custom connector, paste the URL, sign in, Allow. No token; the full walkthrough is below.
Claude Desktop — add Runic as a remote server the way Claude Desktop’s own docs describe (the URL, then sign in and Allow). It goes through the same consent screen as claude.ai and shows up under Settings → Claude & MCP as OAuth · Claude.
MCP Inspector — point it at the URL over the HTTP transport; it registers itself and signs in through the consent screen, no token needed (or paste a token as the bearer header). Handy for checking what a tool actually returns.
Any other client — endpoint https://runicflow.ai/api/mcp, transport HTTP (streamable), header Authorization: Bearer <your token> (where the URL and header go is per that client’s own docs); or, for a client that implements the MCP authorization spec, no header at all: it registers itself with an https or loopback redirect (http://localhost, 127.0.0.1 or [::1] on any port) and signs in through the consent screen. The endpoint answers CORS preflights, so browser-hosted clients can call it directly. The server holds no session state; nothing is kept between calls.
3 · Tools
Eighteen tools. Document arguments take an id or an exact name (a process wins a name tie over a sequence); text arguments are cut at 100,000 characters, names at 200. Every write tool answers with the parse errors and audit findings of what it wrote, so the loop is draft → lint_text → fix → write.
Tool
Arguments
Scope
What comes back
list_documents
—
read
JSON rows {id, name, kind, lines} — processes first, then sequences; only the token owner’s documents.
read_document
document
read
“# name (kind, id …)”, the text, and the reading legend for that kind. Miss: “No document with that id or name. Use list_documents.”
search_documents
query
read
case-insensitive substring: “[kind] name — name matches” and “[kind] name:line — text” (0-based lines), processes first, the first 60 hits then “… N more”; “No matches.”
lint_text
kind (process | sequence) · text
read
parse + audit without saving — “Lint of N lines (kind):” then “No parse errors, no audit findings.” or the PARSE ERRORS / AUDIT lists (line, severity, code, message). Sequence .do/.go targets are checked against your document names.
write_document
document · text (the complete document)
write
replaces the text; the previous text is first snapshotted as “Before Claude edit (MCP)”. “Wrote N lines to "name".” + the report. A team document you may only read: “Write failed — the document may be read-only for this account.”
create_document
kind · name · text?
write
“Created kind "name" (id …).” + the report when text was given. Shares the app’s 60-new-documents-per-hour bucket; on the free plan with billing on: “The free plan includes 10 processes. Upgrade to Pro in the app for unlimited.”
rename_document
document · name
write
“Renamed "old" to "new".” The name only — .go/.do lines in other documents are not rewritten (renaming in the app does that).
audit_document
document
read
“Audit of "name":” + the report — processes and sequences alike, without writing.
render_document
document — or kind + text · format (png | svg, default png) · direction (ttb | ltr, processes) · compact (boolean) · scale (1–3, default 2)
read
a PNG as image content plus a line “name — kind diagram, W×H at S× (N KB PNG)”, or the SVG as text. Rendered with the editor’s own layout engines in the light theme; if the rasterizer is missing: “PNG rendering is unavailable on this server — SVG follows.” Empty text: “Nothing to draw — the text has no steps (or no messages).”
workspace_graph
—
read
JSON: documents [{node, id, name, kind, lines, referencedBy, isolated}], edges [{from, line, kind do | go, to | unresolved}], orphans, unresolved, cycles. The same JSON as the runic://graph resource.
references
document
read
“Referenced by N site(s):” with “- from:line .kind target” rows (or “— deleting or renaming it breaks nothing else.”), “References N document(s):” with “(no such document)” where unresolved, and a reminder that renaming via MCP does not rewrite call sites.
diff_versions
document · from? · to? — version ids, or “latest” (newest snapshot) and “current”; defaults latest → current
read
“"name": from → to”, “+A −R lines · parse errors X → Y”, “Findings fixed:” / “Findings introduced:”, then the unified line diff or “(identical)”. “No snapshots yet — nothing to diff against.”
export_markdown
document
read
the Markdown file the app’s Export menu downloads: “# name”, a fenced runic block, “## How to read this” and the legend.
compact JSON {project, lint: {score, failing: [{id, title, detail}]}, paths, files: [{path, content}]} — the files under #package. Without spec the spec sections read “None yet.”; the interview appendix is always empty over MCP. Past 80,000 characters (~20k tokens) each file is cut to its head (at least 300 characters) plus “…” with truncated: true, files past the budget are listed with omitted: true, and a note says to call again with paths and with only: "lint" while fixing tells.
“how it works” docs from the saved diagrams as files: README.md with a Mermaid system map, then one page per document under docs/how-it-works/business, product or engineering. analyst gets the business rules (every .note verbatim), decisions with their outcomes and exceptions with their recovery; pm the journey along the happy path, where it can go wrong and the open gaps from the audit; developer the same with the Build Package ids (F1.D2.<branch>, F1.X1, S1.M3), message tables and the DSL source. Nothing is invented; over ~20k tokens the rest is listed under omitted and fetched with paths.
share_document
document
write
creates or returns the public read-only link: “Read-only link for "name": …/s/<token>” and “Embed: …/embed/<token>”. Needs write access to the document.
list_versions
document
read
one line per snapshot, newest first, up to 200: “id · ISO time · N lines” + “· "label"” when named + “· mcp” when an MCP write or restore took it. A snapshot the app or the user named is pinned; unlabelled snapshots and MCP snapshots (named or not) keep the newest 50.
restore_version
document · version_id
write
snapshots the current text as “Before Claude restore (MCP)” when it differs, then replaces it: “Restored "name" to the <time> snapshot.” Unknown id: “No such version — use list_versions.”
get_syntax_guide
kind? (process | sequence | both, default both)
read
the process legend, the sequence legend, or both — what the model reads before writing.
An unknown tool name answers a tool error “Unknown tool: …”; a tool that throws, “Tool crashed — try again.” Batches of up to 20 JSON-RPC messages run concurrently; a larger batch is refused with HTTP 413.
4 · Prompts
Runic’s own workflows, packaged as MCP prompts and run by your client’s model with the document already embedded. They are advertised through prompts/list under the names below; where a client surfaces them (a prompt picker, a slash command) is that client’s own convention. Argument values are cut at 4,000 characters; a document argument that matches nothing answers “No document with id or name “…”. Call list_documents.”
Prompt
Argument
What it does
gap-analysis
document
the reading legend + Runic’s process-architect review brief: 5 to 10 questions ordered by impact, each naming the exact step, decision or message, in the document’s language, then the complete revised document — and the close-the-loop instruction: lint_text, write_document (the app keeps the “Before Claude edit (MCP)” snapshot), render_document.
review-before-merge
document
audit_document (or lint_text) first, then a review with the labels blocker / should-fix / nit over unhappy paths, decisions, right-sizing (about 6–15 steps), naming and cross-references (every workspace document is listed); each finding with line, problem and exact replacement; a verdict merge / merge after should-fixes / do not merge.
flows-to-tests
document
one Given / When / Then scenario per path — the happy path, every .then branch (every .alt/.else, .opt and .break in a sequence), every .fail with its recovery (every timeout or error reply), every .back loop with exit and exhaustion, every .wait with its resume event and the never-arrives case — as a Markdown table (id, path, given, when, then, lines) plus open assumptions.
code-to-sequence
feature · name?
trace the feature (say “POST /login”) through the codebase the client is in and write it as a sequence diagram: actors are system boundaries (3–6 is typical), every request with its reply or ->>, .alt/.break failures and .loop retries only where the code has them, .note for timeouts, TTLs and idempotency, .do only to documents that exist; then lint_text, create_document, render_document — and a reply that names the files traced.
document how the codebase the client is in really works, for one reader: map entry points, entities and their statuses, external systems and the rules that decide outcomes (file:line for each); propose the document set and stop for the user’s confirmation; write every branch, failure and retry the code has and nothing it does not, listing unhandled cases as gaps; lint_text, check both ways against the code, create or update the documents, render the main flow; then export_docs for the same lens, append the code citations to each page and write the files into the repo.
draft-process
brief
the in-app process-architect rules and your existing document names, then “Write a process for: <brief>” — one document or a linked set (=== PROCESS: name === headers); per document lint_text, create_document, render_document the main one; every .do/.go target must exist or be created.
build-spec
documents? (comma-separated; default all)
the spec rules, a nine-point interview your client’s model runs (stack and commands; roles × entity permissions; data fields, types, states and transitions; failures; external systems; numeric NFRs with comparator and unit; sign-in method and identity field; design tone, platform, design system, avoid; success metric and out of scope), the deterministic id rules, then the loop: export_build_package with spec + documents + only: "lint" → amend the spec (never the flows) until lint.failing is empty → once without only → fetch truncated files with paths → write every file into the repo, .claude/ included → report the score and what M0 / M1 will do.
5 · Resources
Every document is a resource — runic://doc/<id> (text/plain: “# name (kind)” and the text; an exact name works after the prefix too) — so clients that support it can @-mention a flow into context; resources/templates/list advertises runic://doc/{id}. Three fixed resources are always there: runic://legend/process, runic://legend/sequence and runic://graph (application/json — the workspace graph). Everything is scoped to the token’s account; an unknown URI answers “Unknown resource: …”. Subscribing is accepted and needs no bookkeeping — the change stream already reports every change.
6 · The change stream
A GET on the endpoint with Accept: text/event-stream (and the bearer) opens a server → client stream; without that header the GET answers 405 (“POST JSON-RPC messages here, or GET with Accept: text/event-stream for change notifications.”). The stream opens with “: runic change stream”, checks your documents every 4 seconds and emits notifications/resources/updated — {uri: "runic://doc/<id>", title, via: "mcp" | "app"} — for each document whose text or name moved, and notifications/resources/list_changed when a document was created or deleted. A “: ping” comment arrives every 15 seconds; each connection closes after 50 seconds and the client reconnects with Last-Event-ID (a millisecond timestamp) to miss nothing — without it the stream starts “now”. 120 opens per hour per account. An agent can therefore wait for a change instead of polling.
7 · How an MCP edit shows up in the app
Before write_document or restore_version changes anything, the previous text is snapshotted — unthrottled — as “Before Claude edit (MCP)” / “Before Claude restore (MCP)”. Version history shows those rows with an MCP chip (“Snapshot taken by an edit Claude made over MCP”). While an MCP snapshot still carries that automatic name it rolls off with the newest 50; rename it in Version history (“+ name”) and it is pinned like any snapshot you name.
Every MCP write, create, rename and restore marks the document as last changed via MCP. When you return to a tab that was in the background and nothing is unsaved, the document list is refreshed and — if Claude changed a document — a toast at the bottom says “Claude edited “Name” over MCP while you were away.” with a History button that opens that document’s version history. Created or deleted documents update the list silently.
Restore is one click in the app, and restore_version is itself reversible over MCP.
8 · Limits
What
Limit
Calls
600 per hour per account (“Rate limit reached.”, 429) · 20 JSON-RPC messages per batch (413 beyond)
Change stream
120 opens per hour per account · one connection lasts 50 s
create_document
60 new documents per hour per account — shared with the app
Personal tokens
5 per account · 10 creations per hour · never expire
OAuth connections
20 per account · access token 1 hour · refresh token 30 days · authorization code 10 minutes · 30 consents per hour
OAuth endpoints
register 100 per hour per address · token 2,000 per hour per address plus 30 code exchanges per client and 30 refreshes per refresh token per hour · revoke 2,000 per hour per address
Sizes
text 100,000 characters · name 200 · search 60 hits · prompt argument 4,000 characters · export_build_package 80,000 characters (~20k tokens) before truncation
Free plan (billing on)
10 processes and 10 sequence diagrams — create_document says so
9 · Who pays, and what a token reaches
Nothing under the MCP server calls a model. Your client’s model — your Claude Code, claude.ai or Claude Desktop plan, or whatever key another client uses — reasons, calls the tools and writes. MCP traffic never counts against the $5 monthly budget on Runic’s key, never appears on the usage line under Settings → AI, and never uses an AI key you stored (see cost). Only the in-app AI — chat, inline edit, Create with AI, Build — spends keys.
A token reaches the documents its owner created — personal ones and team documents you created. A teammate’s documents are not reachable; writing to a team document where you are a viewer fails. Cross-account access is impossible by construction.
Tokens, OAuth codes and refresh tokens are hashed at rest, shown once, revocable from Settings → Claude & MCP and deleted with your account. A full-access token grants read/write access to your documents — treat it like a password; a read-only one cannot change anything.
Things to try
“List my Runic flows and summarize what each covers.”
“Read the Onboarding flow and write a gap analysis — what edge cases are missing?”
“Create a customer-refund process in Runic: eligibility check, warehouse inspection, appeal loop.”
“Search my flows for every step that mentions ‘invoice’ and list where they live.”
“Audit every process and fix the findings, then give me share links.”
“Show me the Checkout flow as an image.” · “What depends on Payment check?” · “What changed in Onboarding since yesterday?”
In a repo: /mcp__runic__code-to-system with lens “analyst”, “pm” or “developer” — how the system works, written from the code as linked diagrams and then as docs/how-it-works pages. Or /mcp__runic__code-to-sequence with “POST /login” — one flow, documented from the code. Then /mcp__runic__build-spec — the Build Package written straight into the repo.
The claude.ai connector (OAuth)
claude.ai and other remote MCP clients do not take a pasted token — they sign in with OAuth. Runic is its own authorization server for that (OAuth 2.1: dynamic client registration, PKCE, refresh-token rotation), so there is nothing to configure:
In claude.ai open Settings → Connectors → Add custom connector and paste https://runicflow.ai/api/mcp (a trailing slash is fine).
Claude discovers the sign-in from the endpoint, registers itself and opens Runic’s consent screen — “Runic / Connect an application · Claude wants to access your Runic account”. Sign in, or create an account, if asked; “Signed in as you@…. Not you? Switch account” signs you out and returns to the same request.
Read what the connector may do — Read your documents (“List, read, search, lint, render and export every process flow and sequence diagram in your account.”) and Create and edit documents (“Write, create, rename and restore documents, and create public share links. Every edit is snapshotted first, so it can be undone.”) — and press Allow (or Deny). “You will be sent back to host. The access lasts until you revoke it under Settings → Claude & MCP; the application refreshes it on its own.”
Claude receives a one-hour access token and a 30-day refresh token and renews on its own — each refresh rotates the pair and restarts the 30 days. The connection appears under Settings → Claude & MCP as OAuth · Claude (in general OAuth · <client name>) with its scope pill, an oauth pill and “· access expires date time”, later “· access expired, renews on next use until date”, finally “· expired”. Revoke ends it immediately — access and refresh together.
What happens underneath
A call without a valid token gets 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource"; discovery lives at /.well-known/oauth-protected-resource (also the path-suffixed /.well-known/oauth-protected-resource/api/mcp) and /.well-known/oauth-authorization-server. Endpoints: /oauth/authorize, /api/oauth/token, /api/oauth/register, /api/oauth/revoke. Scopes read and write; the resource indicator, when a client sends one, must be the endpoint itself.
Registration (RFC 7591) is open to public clients only — no client secret is ever issued (a client asking for client_secret_post, as claude.ai does, is registered with none). Up to 10 redirect URIs of at most 2,048 characters, https or loopback http, no fragment; the body at most 32 KB; the same name and redirect set returns the same client. Registrations unused for 30 days are pruned.
Authorization requires response_type=code and PKCE S256. A request with an unknown client shows “Unknown client”; one with an unregistered redirect URI “Redirect URI not registered — … For your safety nothing was sent anywhere.”; any other bad parameter “Invalid request (error)” with a Continue to host link that carries the error back — never an automatic redirect. A registered loopback URI may come back on any port.
The authorization code lives ten minutes and is single-use; a code presented twice revokes everything its first use minted. A refresh token replayed after rotation revokes the whole grant. Consents are limited to 30 per hour per account.
Revocation (RFC 7009) at /api/oauth/revoke with the access or the refresh token ends the pair and the grant’s history; it always answers 200. Deleting your account or a suspension removes every token, code and grant.
AI settings & your own key
Every AI feature — the chat, Create with AI, whole-system generation, inline edits, gray suggestions, the build package — runs the same prompts. Which API key they run on is a workspace setting the owner picks: Runic’s Claude (nothing to configure), bring your own key (each account adds one), or both (Runic’s key unless you stored your own). The mode is spelled out at the top of Settings → AI: “AI features on this workspace run on Runic’s own Claude models. There is nothing to configure — …”, “This workspace runs AI features on your own API key. …”, or “AI features run on Runic’s Claude by default. Add your own Anthropic, OpenAI or Google key and this account switches to it — same prompts, your provider’s bill.”
Adding your key
Open the avatar menu → Settings → AI, pick Anthropic, OpenAI or Google, paste the key (placeholders sk-ant-… / sk-… / AIza…) and Save key. Runic checks the key against the provider’s model list before storing it (“Provider rejected that key — check it and try again.” / “Couldn’t reach Provider to check the key — try again in a moment.”), then keeps it encrypted; you only ever see a masked hint again (the first three and last four characters). Ten saves per hour. Leave the two model fields — Fast model (autocomplete, summaries) and Main model (chat, generation, edits) — empty for the defaults (Claude Haiku 4.5 / Claude Sonnet 5 · gpt-5-mini / gpt-5 · Gemini 2.5 Flash / Gemini 2.5 Pro), or name any model your key can use — a name the key cannot see is refused at save time (““x” isn’t available on this Provider key.”). Success: “Saved — AI features on this account now run on Provider.” The panel then shows “Using your Provider key hint” with “fast: … · main: …” and Change / Remove (“Key removed.”).
If the panel says “Key storage isn’t configured on this server yet — the owner needs to set AI_KEY_SECRET before keys can be saved.”, the server cannot encrypt keys yet; ask the owner.
What changes, what doesn’t
Prompts, the self-check, the structural audits and the routing are identical on every provider. Your Fast model replaces the fast tier (gray suggestions, archive summaries, the planned documents of a whole system); your Main model replaces both the main and the heavy tier (everything else) — see which model answers what.
The label under each chat reply names the model that answered — sonnet or haiku on Runic’s key (opus only when the owner has put Opus on the heavy tier), gpt-5, gemini-2.5-pro and so on on yours.
Web research in the chat uses the provider’s own search tool (Anthropic, OpenAI and Google all have one).
The bill goes to your provider account. The $5 monthly budget that applies on Runic’s key does not apply to yours; Runic’s hourly limits still do. The usage line under Settings → AI then reads “This month: N calls · ~$X on your own key (list-price estimate).”
A key that stops working answers “Your API key was rejected by the provider — check it under Settings → AI.”; in bring-your-own-key mode without a key: “Add your own API key first — open the account menu, choose Settings, then AI.”
Remove the key any time from the same screen; it is deleted with your account. Your data export lists the provider, the masked hint and your model picks — never the key itself.
Models, budget & cost
Every AI task is assigned to one of three tiers; the tier decides the model and whether it thinks before answering. On Runic’s key the defaults are Claude Haiku 4.5 for the fast tier and Claude Sonnet 5 for both the main and the heavy tier — no Opus by default; the owner can put Opus 5 on the heavy tier with ANTHROPIC_MODEL_HEAVY. Thinking is switched on only where a plan or a review benefits from it; every other task runs with thinking off and is checked by the deterministic self-check instead.
Which model answers what
Task
Tier
Model on Runic’s key
Thinking
Gray suggestions (autocomplete)
fast
Claude Haiku 4.5
off
Chat archive summaries
fast
Claude Haiku 4.5
off
Whole system — every document except the main flow
fast
Claude Haiku 4.5
off
Chat — an ordinary turn
main
Claude Sonnet 5
off
AI edit / Copy to chat
main
Claude Sonnet 5
off
Create with AI — one document or a linked set
main
Claude Sonnet 5
off
Whole system — the main flow
main
Claude Sonnet 5
off
Whole system — the plan
main
Claude Sonnet 5
on
Interview questions · Build questions
main
Claude Sonnet 5
on
Chat — a heavy turn (attachment, redesign / rewrite / from-scratch / architecture / audit verbs, over 600 characters, a long document plus fix / review verbs, the deep review)
heavy
Claude Sonnet 5
on
Build spec
heavy
Claude Sonnet 5
on
On your own key the Fast model takes the fast tier and the Main model both other tiers; the defaults are gpt-5-mini / gpt-5 on OpenAI and Gemini 2.5 Flash / Gemini 2.5 Pro on Google. Web search is added to a chat turn when it asks for research, regulation, best practice, benchmarks or “how do others do it” (Claude: at most three searches per turn).
The budget on Runic’s key
Calls paid by Runic’s key are capped at $5 per account per calendar month, counted from the ledger below at list prices. When the sum reaches the cap, every AI request — chat, edits, generation, interview, plan, build — answers 402: “This month’s AI budget on Runic’s key is used up — add your own key under Settings → AI or wait for the 1st.” Gray suggestions simply stop; archive summaries fall back to the plain “N earlier messages, starting with: …” row.
The count resets on the 1st of the month (UTC). The verdict is cached for a minute, so a burst can run slightly past the line. Owner accounts and addresses the owner lists as exempt are never budgeted.
Your own key has no budget: an account on its own key is billed by its provider and only Runic’s hourly limits apply. Bringing a key is the way past the cap without waiting.
The MCP server spends nothing on Runic’s side — see who pays.
The usage line under Settings → AI
On Runic’s key
“This month: N calls · $X.XX of $5.00 on Runic’s key.” — with “ (no limit on this account)” when you are exempt, or, in red, “ — used up until the 1st; add your own key to keep going” once the cap is reached. Amounts under a cent print “<$0.01”.
On your own key
“This month: N calls · ~$X.XX on your own key (list-price estimate).”
The cost ledger
Every model call — successful or not — is written to a usage ledger with its task, model, provider, whose key paid, input / output / cache tokens, duration and a list-price estimate: Claude Opus 5 $5 / $25, Claude Sonnet 5 $3 / $15, Claude Haiku 4.5 $1 / $5, gpt-5-mini $0.25 / $2, gpt-5 $1.25 / $10, Gemini 2.5 Pro $1.25 / $10, Gemini 2.5 Flash $0.30 / $2.50 per million input / output tokens; cache reads at a tenth and cache writes at 1.25× of the input price; an unknown model is estimated at $3 / $15 and flagged. No volume discounts, long-context surcharges or search fees are modelled — it is an early warning, the provider’s invoice is the truth. The owner sees the whole workspace under Admin → AI → Cost: this month and the last 30 days, calls (and failures), tokens, the share priced at a listed price, how many accounts are over the budget, and tables by day, model, task and account. When an account is deleted its ledger rows are kept with the account id blanked; the data export does not include them.
Settings & the account menu
The account menu
The avatar at the right end of the top bar (your initial; “G” when not signed in) opens a menu in this order:
Settings
opens /settings (signed in) — the sections below. A divider follows.
the ten-step interactive tour, in a new tab (signed in).
Docs
this page, in a new tab.
Dark mode / Light mode
toggles the theme — see below.
Feedback
“Send feedback” — “What’s broken, confusing, or missing?”; ⌘/Ctrl + Enter sends; “Thanks — received. We read everything.”
Sign out / Sign in
after a divider.
Left of the avatar the top bar holds Upgrade (free plan, when billing is on), Admin (staff), AI chat (toggles the chat panel), Build and Map; on the left, the R logo, “Runic”, the document name (click to rename), its kind chip and the trash icon. Esc closes the menu.
Dark mode
The toggle flips the whole editor app — panes, menus, dialogs and the editor’s own night theme — and the /settings page; the landing, login and docs pages stay light. The choice is stored in your preferences when Preferences cookies are allowed (otherwise it lasts the session) and is not taken from the operating system.
/settings
Reached from the account menu; signed out it redirects to the login page. A navy header shows your email and Back to the editor; a sticky left nav (a wrapped row on narrow screens) lists the sections, each also reachable by hash:
AI · #ai
“Whose key the AI features run on.” — the mode note, your key and model picks, the usage line (AI settings, cost).
Claude & MCP · #mcp
“Tokens for Claude Code, Claude Desktop and other MCP clients.” — the “Connect from claude.ai” note, Create a token with the Read-only checkbox, the one-line Claude Code command shown once, and Active tokens with Revoke (MCP).
Connected accounts · #accounts
“Google and GitHub sign-in, next to your password.” — Connect / Disconnect per provider, and whether password sign-in is enabled for the account.
Plan · #plan
only when billing is enabled: your plan pill (free / pro), the prices — $5.99 per month or $59.99 per year (two months free) — and Manage subscription. Pro lifts the free plan’s ten processes and ten sequence diagrams and unlocks PNG / SVG / copy-image export.
Your data · #data
“Download everything, or delete the account.” — Download my data (one JSON file: profile, documents, version snapshots, the chat conversation, feedback you sent, token names and dates, teams, and your AI key’s provider, masked hint and model picks — never the key) and Delete my account (“Delete…”, your password, then “Delete forever”: the account, every document, all versions, share links, the chat, tokens and OAuth connections and the AI key go with it; there is no undo — export first).
Cookies · #cookies
“What this browser has allowed; change or withdraw at any time.” — the consent categories; Preferences consent is what lets the theme, pane sizes, export style, icon overrides and the gray-suggestion switch persist.
Unverified accounts see a banner in the editor — “Verify your email — we sent a link to email. Some features stay locked until then.” with Resend link and I’ve verified; AI features, teams and Build wait for the verification.