• Editing nodes on an existing flow → use the canvas, or hit the CLI directly (

  nodes:patch

  ).
• Deleting a flow →

  flows:delete

  .
• Re-laying out an existing flow without semantic changes →

  flows:layout

  .
• Empty project (nothing to analyze) → ask the user first.
• Debugging a single broken Play/Status script → edit in-place, re-run Phase 6.

• User's prompt; project root (

  $PWD

  );

  ~/.seeflow/config.json

  (optional studio host:port).
• Existing

  <project>/flow.json

  (skip the creation path if already present — fall back to

  register --flow flow.json

  ).

• $learnPath

  (

  $PWD/.seeflow/LEARN.md

  ) — persistent crib sheet shared across every flow in this host repo, written by prior

  /seeflow

  runs. Read before Phase 1. Format:

  references/learn-format.md

  .

$SEEFLOW_TMP

/tmp

/var/tmp

$TMPDIR

.seeflow/

.tmp/

1. Create on first use —

   mkdir -p "$SEEFLOW_TMP"

   inside any script or wrapper that writes there. Idempotent, costs nothing.
2. Generated scripts (Phase 5) — Play / Status bodies that need scratch space should reference

   "$SEEFLOW_TMP"

   (or hardcode

   .tmp/...

   relative to

   $repoPath

   when running outside a wrapper that exports it).
3. Cleanup at end of run — after Phase 6 prints the final

   Flow "..." registered ...

   line, the orchestrator removes

   $SEEFLOW_TMP

   (

   rm -rf "$SEEFLOW_TMP"

   ). On a failed/aborted run, leave it in place — the contents are the debugging trail.
4. Never check in — if

   .tmp/

   is not yet gitignored, add it before committing.

$SEEFLOW help

$SEEFLOW help <command>

references/cli.md

references/core-rules.md

1. No mocks. Real services, real state. If something isn't running, stop and ask.
2. Bigger picture before INSERTs. Use the natural data-entry path (API, file-drop, producer, seed, webhook).
3. Match the project's primary language. Use

   runtimeProfile.primaryLanguage

   for every script.

• Serial sub-agent dispatch (N messages, one Task call each). One message, N Task calls — see Phase 1's wrong/right.
• One sub-agent fixing multiple failing scripts in Phase 6. Each needs isolated context.
• Authoring

  flow.json

  directly. Every mutation is a CLI call.
• Silently overwriting (or silently falling back from) an existing flow at the target path. Phase 3 step 1's existing-flow gate is mandatory — open / rename / overwrite, the user decides. The old "fall back to

  register

  " behavior was data-loss-adjacent.
• Touching

  style.json

  . The studio owns it via

  flows:layout

  .
• Passing

  <slug>/scripts/…

  as

  scriptPath

  . New anchor is the node folder — emit just

  scripts/play.ts

  .
• Mocking services or fake fixtures. Use real triggers; copy fixtures from integration tests.
• Asking "what's your codebase?". Launch the analyzers — that is their job.
• Skipping or simulating Phase 6. Mandatory; the retry budget handles flakiness.
• Bypassing the Phase 0 consent check. Never default to

  enabled: true

  ; always read

  ~/.seeflow/consent.json

  first.
• Writing

  LEARN.md

  inside a flow folder (

  <host>/.seeflow/<flow-name>/LEARN.md

  ). It is shared across every flow in the host repo — always read/write

  $learnPath

  =

  $PWD/.seeflow/LEARN.md

  , never anywhere else.
• Touching

  status

  after the initial

  pending

  write. The

  SessionEnd

  hook owns that field — see

  feedback.md

  .
• Logging without a redacted summary. If the summary would leak a path, hostname, project name, or prompt text, skip the entry rather than emit a leaky one.
• Writing scratch files to

  /tmp

  (or

  $TMPDIR

  ). Use

  $SEEFLOW_TMP

  (

  <projectPath>/.tmp/

  ) — project-local, no permission prompts, and cleaned up at end of run. Same rule applies to scripts the Phase 4 designers emit.
• Forgetting to clean

  $SEEFLOW_TMP

  after a successful run. Leave it in place on failure (debugging trail);

  rm -rf "$SEEFLOW_TMP"

  after Phase 6 prints the final

  Flow registered

  line on success.

$SEEFLOW help

projects:create

register

flow:add-bulk

flows:layout

nodes:patch

schema

ids

e2e

@tuongaz/seeflow

npx

ids

projects:create

• Required missing → log

  env-capability-mismatch

  (

  severity: blocker

  ,

  phase: P0

  ,

  details: missing <subcommand>[, <subcommand>...]

  ,

  summary: $SEEFLOW lacks required subcommands; run 

  npm i -g @tuongaz/seeflow@latest

   and retry

  ). Then stop — do not start Phase 1.
• All present → continue.

$SEEFLOW help

npx

env-tool-missing

severity: blocker

phase: P0

summary: $SEEFLOW unresolved — neither local binary nor npx fallback available

1. curl --max-time 0.5 -fsS "$STUDIO_URL/health"

2. Read

   $learnPath

   (

   $PWD/.seeflow/LEARN.md

   ) if present →

   learnContext

   (else

   null

   ). This file is shared across every flow in this host — do not look inside any

   <flow-name>/

   folder for it. Format:

   references/learn-format.md

   .

• 200 → Phase 1.
• !200 → tell the user the studio isn't running, warn the first launch can take a minute or two if it has to fall back to

  npx

  , then run the CLI's

  start

  subcommand. Re-probe

  /health

  once. If still unreachable, log

  env-service-unreachable

  (

  severity: blocker

  ,

  phase: P0

  ,

  summary: studio /health unreachable after start retry

  ), surface and stop.

Task

message 1: Task(seeflow-code-analyzer, …) → wait
message 2: Task(seeflow-system-analyzer, …)

message 1: Task(seeflow-code-analyzer, …)
           Task(seeflow-system-analyzer, …)

• seeflow-code-analyzer

  — in:

  userPrompt

  ,

  projectRoot

  ,

  existingDemo

  ,

  learnContext

  . Out:

  userIntent

  ,

  audienceFraming

  ,

  scope

  ,

  codePointers

  ,

  knownEndpoints

  ,

  techStack

  ,

  existingDemo

  .

• seeflow-system-analyzer

  — in:

  projectRoot

  ,

  learnContext

  . Out:

  runtimeProfile

  + a

  learnUpdates

  payload (

  localDevSetup

  ,

  integrationTests

  ,

  fixtures

  ,

  factories

  ,

  seedCommands

  ,

  dataEntryPaths

  ,

  gotchas

  ,

  techAdaptations

  ). Every fact it learns about how to start / set up the local environment MUST land in

  learnUpdates

  .

Read, Grep, Glob, LS, Bash

agents/seeflow-code-analyzer.md

agents/seeflow-system-analyzer.md

references/learn-format.md

agent-output-unparseable

severity: failure

agent: <slug>

summary: <agent> returned unparseable JSON after retry

agent-output-unparseable

package.json

{
  "userIntent":     "<extracted verbatim from the user's prompt>",
  "audienceFraming":"design-only sketch — no running system to observe",
  "scope":          { "rootEntities": [<inferred from prompt>], "outOfScope": [] },
  "codePointers":   [],
  "knownEndpoints": [],
  "techStack":      [<user-stated, or empty>],
  "existingDemo":   null,
  "runtimeProfile": null
}

seeflow-node-planner

mode-fallback

severity: degraded

phase: P1

details: design-only

summary: empty project — analyzers skipped, synthetic brief built from prompt

• Phase 3 dynamic gate: default to static without re-asking. Without

  runtimeProfile

  , Phase 4 designers cannot pick a real interpreter or fixture; tell the user to populate code first if they later want dynamic.
• Phase 6 (e2e): N/A — skip with a one-line note when summarising the run.

• $learnPath

  : still write the flow row, but mark it

  (design-only)

  in the purpose column so the next run knows the canvas is not wired to a real system.

seeflow-node-planner

techStack

1. Size-check the payload first. Measure the JSON byte length. If > 16 KB (twice the agent's budget — see

   agents/seeflow-system-analyzer.md

   § "Output budget"), the analyzer drifted. Apply the per-field caps from that section before merging: truncate

   gotchas[]

   to 10,

   fixtures[]

   /

   factories[]

   to 8, prose fields to 400 chars, etc. Drop any inherited fact that already appears verbatim in

   $learnPath

   (the merger would keep it anyway). Log

   agent-output-corrected

   once with

   agent: seeflow-system-analyzer, details: oversize-learnupdates-truncated (Nb → Mb)

   . The trimmed payload is what feeds steps 1–3.
2. Merge

   learnUpdates

   into

   $learnPath

   (

   $PWD/.seeflow/LEARN.md

   — create

   $PWD/.seeflow/

   if missing; the file is shared across every flow in this host). Anything about boot, ports, env vars, fixtures, gotchas, or tech adaptations MUST land in the file. Re-cap

   $learnPath

   to ~6 KB after the merge per

   references/learn-format.md

   § "Merging rules" (push oldest gotchas into a collapsed

   <details>

   block).
3. Splice

   runtimeProfile

   +

   $learnPath

   facts into the in-memory context brief used by Phase 4. Forward the trimmed payload — never the raw analyzer output — and only the fields each designer actually consumes (

   runtimeProfile

   , the matching

   techAdaptations.<techId>

   for techs in this flow, the relevant

   dataEntryPaths

   , top 5

   gotchas

   ). The rest stays in

   $learnPath

   for the next run; it doesn't need to ride along in every designer prompt.
4. Merge

   knownEndpoints

   /

   techStack

   from the code-analyzer into the same write.

techId

## Tech stack

references/tech/<techId>.md

## Tech stack adaptations

techAdaptations

$learnPath

$SEEFLOW schema node

$SEEFLOW schema connector

flow:add-bulk

seeflow-node-planner

techAdaptations

techAdaptations

$SEEFLOW schema connector

flow:add-bulk

agent-output-corrected

details: connector-extras-stripped (×N)

• Resource nodes first — every DB, queue, event bus, cache, file store, external SaaS gets its own node, typed

  rectangle

  with a matching Lucide

  icon

  (

  database

  ,

  list-ordered

  ,

  radio-tower

  ,

  cloud

  ,

  server

  ) and a

  statusAction

  capability when state is worth probing.
• Abstraction — one node per service / workflow / worker / queue / DB. Exceptions: independently-meaningful pipeline stages, fan-out consumers, branches, and services hosting multiple independent state machines.
• Duplicate shared resources for clarity. When a DB / queue / bus is referenced by many nodes and the lines tangle the canvas, split it into role-specific copies (

  orders-db-read

  ,

  orders-db-write

  ) sharing the same

  type

  +

  data.icon

  +

  data.name

  but distinct

  id

  s.

name

slug

nodes

connectors

rationales

nodes

connectors

$SEEFLOW schema node

$SEEFLOW schema connector

flow:add-bulk

flow:add-bulk

agents/seeflow-node-planner.md

JSON.parse

• typeof name === 'string' && name.length > 0

• typeof slug === 'string' && slug.length > 0

• Array.isArray(nodes) && nodes.length > 0

• Array.isArray(connectors)

  (may be empty for single-node flows)

• rationales && typeof rationales === 'object' && Object.keys(rationales).length === nodes.length

  (one entry per node id)

Your previous output was missing: name, rationales[3 of 5 nodes]. Re-emit the full envelope.

agent-output-incomplete

severity: failure

phase: P2

agent: seeflow-node-planner

details: <missing-keys>

summary: planner returned partial envelope after retry

name

slug

flow.json

projects:create

$SEEFLOW help <command>

1. Scaffold + register inside the project via

   projects:create

   . This is the entry point for a new project: the CLI writes the empty

   flow.json

   at

   <repoPath>/flow.json

   (project root) and registers it in one shot.
   Existing-flow gate — check before the CLI write. Test

   test -f "$repoPath/flow.json"

   . If the file exists (or

   projects:create

   later returns

   alreadyExists

   exit code 4 because the pre-check raced), STOP and ask via

   AskUserQuestion

   — never silently overwrite, never silently fall back:

   A SeeFlow flow is already registered at this path. What do you want to do?

   1. Open the existing flow (Recommended) — skip creation; run

      $SEEFLOW register --path "$repoPath"

      to re-attach the existing envelope, surface

      $STUDIO_URL/d/<slug>

      , then stop. If the user wanted to inspect rather than edit, hand off to

      /seeflow-lookup

      .
   2. Create a new flow with a different name — ask the user for a new flow name, recompute

      $repoPath = $PWD/.seeflow/<new-slug>

      , then retry this step (Phase 1/2 only rerun if the user's intent also changed).
   3. Overwrite the existing flow — destructive. Confirm once more, then

      $SEEFLOW flows:delete --path "$repoPath"

      (and

      rm -rf "$repoPath"

      for any sidecar leftovers), then retry this step.

   Log one

   plan-revision

   per session (

   severity: friction

   ,

   phase: P3

   ,

   summary: existing flow at target path; user picked <open|rename|overwrite>

   ). Debounce — even if the user toggles between options, the entry is written once.
   Gate clear → forward the planner-supplied

   name

   (and

   description

   if the planner provided one):
   bash

   $SEEFLOW projects:create --path "$repoPath" --name "$plannerName" [--description "$plannerDescription"]

   The studio writes the envelope, adds a registry entry under

   ~/.seeflow/registry.json

   , and returns

   { id, slug }

   (slug is derived from

   name

   ). Capture

   id

   from the response and use it (not

   slug

   ) for every follow-up CLI call below — several commands document slug support in

   help

   but the server only resolves by id today. Registration is a precondition for opening the canvas: the

   $STUDIO_URL/d/<slug>

   route only works after this step succeeds, so never surface the canvas URL to the user before this step.
   If

   projects:create

   returns

   alreadyExists

   (code 4) after the pre-check passed (filesystem race), loop back to the gate above and let the user decide — do not auto-fall-back. Do not hardcode the envelope shape from memory; if you need to inspect what

   projects:create

   writes, run

   $SEEFLOW schema flow

   .
2. Normalize the planner output: strip

   rationales

   (keep them in memory for the review prompt below), then for the planner's designated trigger node (the one whose

   data.playAction

   is set even as a placeholder), inject the minimum

   playAction

   payload the contract requires so the server accepts the batch. Look up the exact required fields by running

   $SEEFLOW schema action

   and

   $SEEFLOW schema node

   (the

   PlayAction

   shape's required keys) — do not hardcode the shape from memory. Pick the interpreter from

   runtimeProfile.primaryLanguage

   (falling back to

   bun

   ) and point

   scriptPath

   at

   scripts/play.ts

   . The Phase 4 play-designer overwrites the placeholder with the real action via

   nodes:patch

   . The script file does not need to exist yet — Phase 5 writes it, Phase 6 runs it. 2a. Mint canonical ids. Planner ids are descriptive (

   checkout-api

   ,

   c-order-server-event-bus

   ); the studio's id producers (canvas, server auto-assign, the upload endpoint regex) use

   node-<10 base62>

   /

   conn-<10 base62>

   . Rewrite at the boundary so flow.json matches. Use the CLI — it shares the exact alphabet and rejection-sampling logic with every other id producer in the studio:
   bash

   mapfile -t nodeIds < <($SEEFLOW ids node "${#nodes[@]}")
   mapfile -t connIds < <($SEEFLOW ids connector "${#connectors[@]}")

   For each

   nodes[i].id

   that already matches

   ^node-[A-Za-z0-9]{10}$

   (edit-case reuse from

   editTarget

   ), keep it; only mint new canonical ids for net-new nodes. Build a

   descriptiveId → canonicalId

   map and rewrite:

   • nodes[].id

   • connectors[].id

     ,

     connectors[].source

     ,

     connectors[].target

   • rationales

     keys (kept in memory for the review prompt) 2b. Log any silent corrections from steps 2 and 2a (see

     feedback.md

     ). For each correction kind that fired (placeholder-

     playAction

     injection, descriptive→canonical id rewrite, unknown-type rename, unknown-field rename, bidir-connector strip, user-to-system-rectangle retype, …), emit one

     agent-output-corrected

     entry with

     severity: corrected

     ,

     phase: P3

     ,

     agent: seeflow-node-planner

     , and

     details: <correction-kind> (×N)

     where N is the count. Aggregate across nodes — never one entry per node. If no corrections were needed, log nothing. This is the signal that the planner drifted from the contract; without it, the orchestrator's silent patching is invisible.

   user-to-system-rectangle

   retype rule. If the planner shipped

   type:'user'

   for a node whose

   data.name

   is clearly a software system (

   Web UI

   ,

   Mobile App

   ,

   Browser

   ,

   SPA

   ,

   Desktop Client

   ,

   CLI

   ,

   SDK

   , anything ending in

   Client

   /

   App

   /

   UI

   /

   Frontend

   /

   Service

   ), silently retype to

   rectangle

   with

   data.icon

   inferred from the name (

   monitor

   for web/UI/frontend,

   smartphone

   for mobile,

   terminal

   for CLI,

   plug

   for SDK/Client). Keep

   type:'user'

   only when

   data.name

   is a human role (

   Customer

   ,

   Support Agent

   ,

   Reviewer

   ,

   Approver

   ,

   Operator

   ). Log one aggregate

   agent-output-corrected

   entry with

   details: user-to-system-rectangle (×N)

   . The Phase 3 canvas review surfaces the result to the user — they see the correction.

3. flow:add-bulk

   — atomic seed of nodes + connectors in one transactional write. Forward the normalized + id-rewritten

   nodes

   and

   connectors

   arrays as

   { nodes, connectors }

   . Connectors may reference nodes from the same call — the server validates the merged graph as a whole, so a dangling source/target or a malformed node rolls back both arrays together. No two-phase commit to reason about; no orphan nodes if connectors fail.

4. flows:layout

   — run ELK and write

   style.json

   .

badSchema

rationales

<data.name> (<canonical id>):

POST /orders (node-Ab12cd34Ef): Single HTTP service — internal routes are implementation detail.

URL="$STUDIO_URL/d/$slug"
(open "$URL" 2>/dev/null || xdg-open "$URL" 2>/dev/null || start "$URL" 2>/dev/null) &

Opened the canvas at

<url>

. Two quick questions:

1. Layout — any additions, removals, or renames?
2. Dynamic or static — continue with Play scripts + Status probes so the canvas reacts to your running system, or stop with the static layout?

• Layout changes requested → log

  plan-revision

  (

  severity: friction

  ,

  phase: P3

  ,

  summary: user requested layout changes at canvas review gate

  ), re-run node-planner with the feedback, repeat the combined ask. The dynamic answer (if given) is remembered but not acted on until the layout is approved. Debounce — log once per session even if the user revises multiple times.
• Layout approved + dynamic → Phase 4. If the system-analyzer is still running, await it now; Phase 4 designers need its

  runtimeProfile

  , fixtures, data-entry paths, and tech adaptations. Re-merge any new

  learnUpdates

  first.
• Layout approved + static → print

  Flow "<name>" registered as <slug> (static). Open: $STUDIO_URL/d/<slug>

  and stop. Still merge any pending

  learnUpdates

  .
• Dynamic answer unclear or absent → default to static (dynamic writes executable scripts; opt-in). Log

  mode-fallback

  (

  severity: degraded

  ,

  phase: P3

  ,

  details: dynamic-to-static

  ,

  summary: dynamic gate unclear; auto-downgraded to static

  ).

1. Write

   scriptFile.body

   to

   scriptFile.path

   (Write tool).

2. chmod

   per

   scriptFile.chmod

   (default 755).
3. Call

   nodes:patch

   with the overlay's

   patch

   body. (Body shape:

   $SEEFLOW help nodes:patch

   .)

newTriggerNodes

flow:add-bulk

flows:layout

$SEEFLOW help flow:add-bulk

editTarget

id

type

rectangle

database

nodes:patch { type, ...required fields }

nodes:delete

flow:add-bulk

nodes/<id>/

* → image

path

* → icon

icon

* → html

html

badSchema

nodes:patch

retry-exhausted

severity: failure

phase: P5

code: badSchema

summary: nodes:patch retries exhausted on <kind> (N nodes)

e2e

--skip-nodes

nodeId

validationSafe === false

skipped[]

$SEEFLOW help e2e

ok: true

Flow "<name>" registered as <slug>. Open: $STUDIO_URL/d/<slug>

rm -rf "$SEEFLOW_TMP"

ok: false

1. Identify failing nodes from

   plays[*].error

   /

   statuses[*].outcome

   .
2. Parallel fix-up (Phase 1 rule): one sub-agent per failing script, single message. A single agent fixing N scripts cross-contaminates.
3. Each agent gets the script path (under

   nodes/<nodeId>/scripts/

   ), the specific error payload, and a concrete fix hypothesis (

   play.ts: ECONNREFUSED on :3001 — start the app first

   ).
4. Edit in-place, re-run the

   e2e

   subcommand. Max 2 retries, then log

   seeflow:e2e-fail

   (

   severity: failure

   ,

   phase: P6

   ,

   details: <N> failing scripts after fix-up

   ,

   summary: e2e ok:false after retry budget exhausted

   ) and ask retry / stop.

phase-skipped

severity: degraded

phase: P6

details: design-only

summary: e2e skipped — no runtime to validate against