@xdelivered/emberflow 0.2.0

package/studio-dist/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="46" fill="none" viewBox="0 0 48 46"><path fill="#863bff" d="M25.946 44.938c-.664.845-2.021.375-2.021-.698V33.937a2.26 2.26 0 0 0-2.262-2.262H10.287c-.92 0-1.456-1.04-.92-1.788l7.48-10.471c1.07-1.497 0-3.578-1.842-3.578H1.237c-.92 0-1.456-1.04-.92-1.788L10.013.474c.214-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.471c-1.07 1.498 0 3.579 1.842 3.579h11.377c.943 0 1.473 1.088.89 1.83L25.947 44.94z" style="fill:#863bff;fill:color(display-p3 .5252 .23 1);fill-opacity:1"/><mask id="a" width="48" height="46" x="0" y="0" maskUnits="userSpaceOnUse" style="mask-type:alpha"><path fill="#000" d="M25.842 44.938c-.664.844-2.021.375-2.021-.698V33.937a2.26 2.26 0 0 0-2.262-2.262H10.183c-.92 0-1.456-1.04-.92-1.788l7.48-10.471c1.07-1.498 0-3.579-1.842-3.579H1.133c-.92 0-1.456-1.04-.92-1.787L9.91.473c.214-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.471c-1.07 1.498 0 3.578 1.842 3.578h11.377c.943 0 1.473 1.088.89 1.832L25.843 44.94z" style="fill:#000;fill-opacity:1"/></mask><g mask="url(#a)"><g filter="url(#b)"><ellipse cx="5.508" cy="14.704" fill="#ede6ff" rx="5.508" ry="14.704" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -4.47 31.516)"/></g><g filter="url(#c)"><ellipse cx="10.399" cy="29.851" fill="#ede6ff" rx="10.399" ry="29.851" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -39.328 7.883)"/></g><g filter="url(#d)"><ellipse cx="5.508" cy="30.487" fill="#7e14ff" rx="5.508" ry="30.487" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.814 -25.913 -14.639)scale(1 -1)"/></g><g filter="url(#e)"><ellipse cx="5.508" cy="30.599" fill="#7e14ff" rx="5.508" ry="30.599" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.814 -32.644 -3.334)scale(1 -1)"/></g><g filter="url(#f)"><ellipse cx="5.508" cy="30.599" fill="#7e14ff" rx="5.508" ry="30.599" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -34.34 30.47)"/></g><g filter="url(#g)"><ellipse cx="14.072" cy="22.078" fill="#ede6ff" rx="14.072" ry="22.078" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="rotate(93.35 24.506 48.493)scale(-1 1)"/></g><g filter="url(#h)"><ellipse cx="3.47" cy="21.501" fill="#7e14ff" rx="3.47" ry="21.501" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.009 28.708 47.59)scale(-1 1)"/></g><g filter="url(#i)"><ellipse cx="3.47" cy="21.501" fill="#7e14ff" rx="3.47" ry="21.501" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.009 28.708 47.59)scale(-1 1)"/></g><g filter="url(#j)"><ellipse cx=".387" cy="8.972" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(39.51 .387 8.972)"/></g><g filter="url(#k)"><ellipse cx="47.523" cy="-6.092" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 47.523 -6.092)"/></g><g filter="url(#l)"><ellipse cx="41.412" cy="6.333" fill="#47bfff" rx="5.971" ry="9.665" style="fill:#47bfff;fill:color(display-p3 .2799 .748 1);fill-opacity:1" transform="rotate(37.892 41.412 6.333)"/></g><g filter="url(#m)"><ellipse cx="-1.879" cy="38.332" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 -1.88 38.332)"/></g><g filter="url(#n)"><ellipse cx="-1.879" cy="38.332" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 -1.88 38.332)"/></g><g filter="url(#o)"><ellipse cx="35.651" cy="29.907" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 35.651 29.907)"/></g><g filter="url(#p)"><ellipse cx="38.418" cy="32.4" fill="#47bfff" rx="5.971" ry="15.297" style="fill:#47bfff;fill:color(display-p3 .2799 .748 1);fill-opacity:1" transform="rotate(37.892 38.418 32.4)"/></g></g><defs><filter id="b" width="60.045" height="41.654" x="-19.77" y="16.149" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="c" width="90.34" height="51.437" x="-54.613" y="-7.533" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="d" width="79.355" height="29.4" x="-49.64" y="2.03" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="e" width="79.579" height="29.4" x="-45.045" y="20.029" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="f" width="79.579" height="29.4" x="-43.513" y="21.178" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="g" width="74.749" height="58.852" x="15.756" y="-17.901" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="h" width="61.377" height="25.362" x="23.548" y="2.284" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="i" width="61.377" height="25.362" x="23.548" y="2.284" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="j" width="56.045" height="63.649" x="-27.636" y="-22.853" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="k" width="54.814" height="64.646" x="20.116" y="-38.415" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="l" width="33.541" height="35.313" x="24.641" y="-11.323" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="m" width="54.814" height="64.646" x="-29.286" y="6.009" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="n" width="54.814" height="64.646" x="-29.286" y="6.009" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="o" width="54.814" height="64.646" x="8.244" y="-2.416" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="p" width="39.409" height="43.623" x="18.713" y="10.588" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter></defs></svg>

package/studio-dist/icons.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg">
+  <symbol id="bluesky-icon" viewBox="0 0 16 17">
+    <g clip-path="url(#bluesky-clip)"><path fill="#08060d" d="M7.75 7.735c-.693-1.348-2.58-3.86-4.334-5.097-1.68-1.187-2.32-.981-2.74-.79C.188 2.065.1 2.812.1 3.251s.241 3.602.398 4.13c.52 1.744 2.367 2.333 4.07 2.145-2.495.37-4.71 1.278-1.805 4.512 3.196 3.309 4.38-.71 4.987-2.746.608 2.036 1.307 5.91 4.93 2.746 2.72-2.746.747-4.143-1.747-4.512 1.702.189 3.55-.4 4.07-2.145.156-.528.397-3.691.397-4.13s-.088-1.186-.575-1.406c-.42-.19-1.06-.395-2.741.79-1.755 1.24-3.64 3.752-4.334 5.099"/></g>
+    <defs><clipPath id="bluesky-clip"><path fill="#fff" d="M.1.85h15.3v15.3H.1z"/></clipPath></defs>
+  </symbol>
+  <symbol id="discord-icon" viewBox="0 0 20 19">
+    <path fill="#08060d" d="M16.224 3.768a14.5 14.5 0 0 0-3.67-1.153c-.158.286-.343.67-.47.976a13.5 13.5 0 0 0-4.067 0c-.128-.306-.317-.69-.476-.976A14.4 14.4 0 0 0 3.868 3.77C1.546 7.28.916 10.703 1.231 14.077a14.7 14.7 0 0 0 4.5 2.306q.545-.748.965-1.587a9.5 9.5 0 0 1-1.518-.74q.191-.14.372-.293c2.927 1.369 6.107 1.369 8.999 0q.183.152.372.294-.723.437-1.52.74.418.838.963 1.588a14.6 14.6 0 0 0 4.504-2.308c.37-3.911-.63-7.302-2.644-10.309m-9.13 8.234c-.878 0-1.599-.82-1.599-1.82 0-.998.705-1.82 1.6-1.82.894 0 1.614.82 1.599 1.82.001 1-.705 1.82-1.6 1.82m5.91 0c-.878 0-1.599-.82-1.599-1.82 0-.998.705-1.82 1.6-1.82.893 0 1.614.82 1.599 1.82 0 1-.706 1.82-1.6 1.82"/>
+  </symbol>
+  <symbol id="documentation-icon" viewBox="0 0 21 20">
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="m15.5 13.333 1.533 1.322c.645.555.967.833.967 1.178s-.322.623-.967 1.179L15.5 18.333m-3.333-5-1.534 1.322c-.644.555-.966.833-.966 1.178s.322.623.966 1.179l1.534 1.321"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M17.167 10.836v-4.32c0-1.41 0-2.117-.224-2.68-.359-.906-1.118-1.621-2.08-1.96-.599-.21-1.349-.21-2.848-.21-2.623 0-3.935 0-4.983.369-1.684.591-3.013 1.842-3.641 3.428C3 6.449 3 7.684 3 10.154v2.122c0 2.558 0 3.838.706 4.726q.306.383.713.671c.76.536 1.79.64 3.581.66"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M3 10a2.78 2.78 0 0 1 2.778-2.778c.555 0 1.209.097 1.748-.047.48-.129.854-.503.982-.982.145-.54.048-1.194.048-1.749a2.78 2.78 0 0 1 2.777-2.777"/>
+  </symbol>
+  <symbol id="github-icon" viewBox="0 0 19 19">
+    <path fill="#08060d" fill-rule="evenodd" d="M9.356 1.85C5.05 1.85 1.57 5.356 1.57 9.694a7.84 7.84 0 0 0 5.324 7.44c.387.079.528-.168.528-.376 0-.182-.013-.805-.013-1.454-2.165.467-2.616-.935-2.616-.935-.349-.91-.864-1.143-.864-1.143-.71-.48.051-.48.051-.48.787.051 1.2.805 1.2.805.695 1.194 1.817.857 2.268.649.064-.507.27-.857.49-1.052-1.728-.182-3.545-.857-3.545-3.87 0-.857.31-1.558.8-2.104-.078-.195-.349-1 .077-2.078 0 0 .657-.208 2.14.805a7.5 7.5 0 0 1 1.946-.26c.657 0 1.328.092 1.946.26 1.483-1.013 2.14-.805 2.14-.805.426 1.078.155 1.883.078 2.078.502.546.799 1.247.799 2.104 0 3.013-1.818 3.675-3.558 3.87.284.247.528.714.528 1.454 0 1.052-.012 1.896-.012 2.156 0 .208.142.455.528.377a7.84 7.84 0 0 0 5.324-7.441c.013-4.338-3.48-7.844-7.773-7.844" clip-rule="evenodd"/>
+  </symbol>
+  <symbol id="social-icon" viewBox="0 0 20 20">
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M12.5 6.667a4.167 4.167 0 1 0-8.334 0 4.167 4.167 0 0 0 8.334 0"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M2.5 16.667a5.833 5.833 0 0 1 8.75-5.053m3.837.474.513 1.035c.07.144.257.282.414.309l.93.155c.596.1.736.536.307.965l-.723.73a.64.64 0 0 0-.152.531l.207.903c.164.715-.213.991-.84.618l-.872-.52a.63.63 0 0 0-.577 0l-.872.52c-.624.373-1.003.094-.84-.618l.207-.903a.64.64 0 0 0-.152-.532l-.723-.729c-.426-.43-.289-.864.306-.964l.93-.156a.64.64 0 0 0 .412-.31l.513-1.034c.28-.562.735-.562 1.012 0"/>
+  </symbol>
+  <symbol id="x-icon" viewBox="0 0 19 19">
+    <path fill="#08060d" fill-rule="evenodd" d="M1.893 1.98c.052.072 1.245 1.769 2.653 3.77l2.892 4.114c.183.261.333.48.333.486s-.068.089-.152.183l-.522.593-.765.867-3.597 4.087c-.375.426-.734.834-.798.905a1 1 0 0 0-.118.148c0 .01.236.017.664.017h.663l.729-.83c.4-.457.796-.906.879-.999a692 692 0 0 0 1.794-2.038c.034-.037.301-.34.594-.675l.551-.624.345-.392a7 7 0 0 1 .34-.374c.006 0 .93 1.306 2.052 2.903l2.084 2.965.045.063h2.275c1.87 0 2.273-.003 2.266-.021-.008-.02-1.098-1.572-3.894-5.547-2.013-2.862-2.28-3.246-2.273-3.266.008-.019.282-.332 2.085-2.38l2-2.274 1.567-1.782c.022-.028-.016-.03-.65-.03h-.674l-.3.342a871 871 0 0 1-1.782 2.025c-.067.075-.405.458-.75.852a100 100 0 0 1-.803.91c-.148.172-.299.344-.99 1.127-.304.343-.32.358-.345.327-.015-.019-.904-1.282-1.976-2.808L6.365 1.85H1.8zm1.782.91 8.078 11.294c.772 1.08 1.413 1.973 1.425 1.984.016.017.241.02 1.05.017l1.03-.004-2.694-3.766L7.796 5.75 5.722 2.852l-1.039-.004-1.039-.004z" clip-rule="evenodd"/>
+  </symbol>
+</svg>

package/studio-dist/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Emberflow</title>
+    <script type="module" crossorigin src="/assets/index-O26dKRjW.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DNJwW-hM.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/templates/skills/emberflow-basics/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: emberflow-basics
+description: Use whenever working with Emberflow in this project — running the studio, understanding the file layout, adding or editing API operations and scenarios, registering custom nodes, or using the CLI/MCP. The foundation the other emberflow-* skills build on. Trigger on "emberflow", "workflow builder", "operation", "api", "flow", "run a scenario", "emberflow dev".
+metadata:
+  version: 2.7.0
+---
+
+# Emberflow basics
+
+Emberflow is a visual builder for **API operations** in this project. An operation
+is a JSON file describing a node graph (a "flow"); the project's own code is
+exposed as **nodes**; runs execute on a local runner and are visualised in a
+browser studio. An operation with an `http` trigger is a live HTTP endpoint; one
+without is an internal sub-flow other operations call. This skill is the
+mechanics reference — how the pieces fit and how to drive them correctly.
+
+## File layout (in the consumer project)
+
+- `emberflow.config.mjs` (project root) — the contract. Exports `defineConfig({ flowsDir, registerNodes })`.
+- `emberflow/apis/<api>/<folder…>/<operation>.json` — one operation per file, in a tree. `<api>` is the top-level API (e.g. `default`, `billing`); folders under it are free-form grouping.
+- **An operation's `id` is its path relative to the apis dir, without `.json`.** `emberflow/apis/billing/charge.json` → `id: "billing/charge"`; `emberflow/apis/default/greet.json` → `id: "default/greet"`. The store keys ops by their in-file `id` but stores them by path, so the two MUST match — a mismatched id makes the op unreachable.
+- `emberflow/apis/…/<operation>.scenarios.json` — that op's scenarios ("stories": named inputs), a sidecar array alongside the op file. The op file never contains a `scenarios` key.
+- `emberflow/apis/<api>/<folder…>/_meta.json` — optional. Holds the `auth` policy inherited by every operation at or below that directory (see Auth below).
+- `emberflow.environments.json` — **structure only**: named environments, their non-secret `vars`, and each env's `secrets` as a LIST of key NAMES (no values). Safe for you to read and edit. `emberflow.secrets.json` — secret **values only**, shape `{ "<envName>": { "<KEY>": "<value>" } }`, chmod `0600`; you NEVER read or write it (the user sets values via the studio's Manage Environment dialog or `login-environment`). A value of `"$ENV:VAR_NAME"` indirects to `process.env.VAR_NAME` at load. Both files are git-ignored (machine-local). The config and the `emberflow/apis` tree ARE committed.
+- `emberflow/infrastructure.json` — **committed, structure-only** manifest of the infrastructure this project already uses (databases, external APIs, providers) with evidence pointing at the files that prove it. Written by the infrastructure scout (the studio's Infra tab / the `scout-infrastructure` agent intent); READ by agents before authoring operations so they REUSE existing systems and secret NAMES instead of inventing parallel config. Holds env-var NAMES only — never secret values.
+
+## Running it
+
+- `npx emberflow dev` — boots the runner **and** the studio in one process and opens the browser (`http://127.0.0.1:8092`). This is the primary loop: edit an operation file or config, the studio picks it up.
+- `npx emberflow run <id> --scenario <name>` — run an operation to completion against a running runner; prints the result JSON. `<id>` is the operation's path-based id (e.g. `billing/charge`).
+- `npx emberflow run <id> --input '{}'` — same as the studio's Plain Run button: it uses only the Input node's `defaults`. Use this to catch missing defaults before relying on scenarios.
+- `npx emberflow mcp` — expose the MCP tools (list/get/save/validate/run/publish operations) to an agent.
+- `npx emberflow init` — scaffold config + an example operation (already done if this project has an `emberflow.config.(mjs|js|ts)`).
+
+Always have `emberflow dev` running while authoring — it's how you see and test.
+
+## The config and custom nodes
+
+The project's `language:` field (`'javascript'` or `'typescript'`, in
+`emberflow.config.(mjs|js|ts)`) is the **authoritative signal for which
+language to author in** — always match it, whichever scaffold shape below
+the project actually uses.
+
+JavaScript (`emberflow.config.mjs`, JSDoc types):
+
+```js
+import { defineConfig } from '@xdelivered/emberflow';
+export default defineConfig({
+  language: 'javascript',
+  flowsDir: 'emberflow/flows',      // anchor: the apis tree lives at emberflow/apis (sibling)
+  /** @param {import('@xdelivered/emberflow').NodeRegistry} registry */
+  registerNodes(registry) {
+    registry.register(
+      {
+        type: 'Greet',                 // unique id, referenced by operations
+        label: 'Greet',
+        description: 'Greets by name.',
+        category: 'my-app',
+        inputSchema:  { fields: [{ name: 'name', type: 'string', required: true }] },
+        outputSchema: { fields: [{ name: 'hello', type: 'string' }] },
+        // effects: 'mutation'  ← add for nodes that write/POST/email; they dry-run under safe mode
+        // traceKind: 'db'|'http'|'llm'  ← add for nodes that touch infrastructure; mock mode intercepts by this
+      },
+      async (ctx) => ({ hello: `Hello, ${ctx.input.name}!` }),
+    );
+  },
+});
+```
+
+TypeScript (`emberflow.config.ts`, typed) — same shape, typed instead of JSDoc:
+
+```ts
+import { defineConfig } from '@xdelivered/emberflow';
+import type { NodeRegistry } from '@xdelivered/emberflow';
+export default defineConfig({
+  language: 'typescript',
+  flowsDir: 'emberflow/flows',
+  registerNodes(registry: NodeRegistry) {
+    registry.register(
+      { type: 'Greet', label: 'Greet', /* schemas/category/effects/traceKind as above */ },
+      async (ctx) => ({ hello: `Hello, ${ctx.input.name}!` }),
+    );
+  },
+});
+```
+
+- A node = a **definition** (metadata: type/label/schemas/category/tags/effects — what the studio shows) plus an **implementation** (an `async (ctx) => output`). The studio fetches definitions over HTTP; implementations run on the runner (next to your app code, so they can touch your DB/services).
+- `ctx.input` = the node's resolved inputs. `ctx.config` = its per-node config. Return a plain object; downstream nodes read fields off it.
+- Mark side-effecting nodes `effects: 'mutation'` so safe mode can dry-run them,
+  and infrastructure-touching nodes with `traceKind` so mock mode can intercept them.
+- **Design for both worlds.** An operation ships with real node implementations
+  (so it serves live) AND sidecar `mocks` covering every infra node (so it runs
+  in mock mode). Neither substitutes for the other — see Mock mode below.
+- **A mutation node has exactly three behaviours** — mock run → canned output
+  from the sidecar; dry-run (`config.commit` false, or safe mode) → a
+  `wouldSend`/`wouldWrite` summary, nothing touched; commit
+  (`config.commit === true && !ctx.safeMode`) → the REAL side effect. There is
+  no fourth state: a commit path that logs "[SIMULATED]" and returns success is
+  FORBIDDEN — these are operational APIs, not demos. If the real call can't be
+  made (a missing secretRef, no webhook configured), the commit path THROWS a
+  clear error naming the missing key. Fake success is worse than failure;
+  `doctor` flags simulated commit paths as `simulated-commit`.
+
+## Operation file shape
+
+```json
+{
+  "id": "default/greet", "name": "Greet", "version": 1,
+  "http": { "method": "GET", "path": "/greet" },
+  "nodes": [
+    { "id": "in", "type": "Input", "label": "Request", "position": {"x":0,"y":0},
+      "config": { "fields": [
+        {"name":"params","type":"object"}, {"name":"query","type":"object"},
+        {"name":"body","type":"object"},   {"name":"headers","type":"object"}
+      ], "defaults": { "query": {"name":"world"} } } },
+    { "id": "greet", "type": "Greet", "label": "Greet", "position": {"x":300,"y":0},
+      "config": {}, "inputMap": { "name": {"sourceNodeId":"in","sourceField":"query.name"} } },
+    { "id": "res", "type": "Response", "label": "Response", "position": {"x":600,"y":0},
+      "config": {}, "inputMap": { "body": {"sourceNodeId":"greet","sourceField":"$"} } }
+  ],
+  "edges": [ {"id":"e1","source":"in","target":"greet"}, {"id":"e2","source":"greet","target":"res"} ],
+  "createdAt": "2026-07-05T00:00:00Z", "updatedAt": "2026-07-05T00:00:00Z"
+}
+```
+
+- **`http`** = `{ method, path }`. Present → the operation is mounted as an HTTP endpoint. Absent → it's an internal sub-flow (call it from another op's `Subflow` node). Optional `auth` field (see below).
+- **`Input`** is the entry node. For an HTTP operation the run payload is the request shape `{ params, query, body, headers }` (plus the request body's own fields promoted to the top level, and `user` when auth ran). Read a request part with a dotted `sourceField` like `query.name` or `body.amount`.
+- **`Response`** is the terminus of an HTTP operation. Its input `{ status, body }` becomes the HTTP response; omit `status` and it defaults to `200`.
+- **`inputMap`** wires a node's input field to a source node's output: `{ sourceNodeId, sourceField }`. `sourceField: "$"` means the whole output; otherwise a dot-path into it.
+- **`edges`** draw the graph and, critically, define execution order (topological). **Every inputMap needs a matching edge** — an inputMap without an edge renders as a floating node AND the ordering can't see the dependency. Rule: if node B reads from node A, there is an `A→B` edge.
+- **Input defaults matter.** The studio's Plain Run button sends no request. Every required Input field must either have a sensible `config.defaults` value or the author must intentionally accept/report that Plain Run fails. Do not call an operation done after only scenario runs.
+
+## Built-in node types
+
+You'll use these most (custom project nodes come from `registerNodes`):
+
+- `Input` — entry; emits the run payload merged over `defaults`. For an HTTP op the payload is `{ params, query, body, headers }`.
+- `Response` — **HTTP terminus.** Input `{ status, body }` → the HTTP response. Use this for any operation with an `http` trigger.
+- `Result` — **internal terminus / display sink.** The collected output of a non-HTTP (internal) flow comes from its `Result` nodes. Use `Response` for HTTP endpoints, `Result` for internal sub-flows and while iterating on logic in the studio.
+- `Conditional`/`Route` — branching. Emit `$branch`; downstream edges carry a `sourceHandle` = branch name and only run when that branch is taken.
+- `ForEach`/`Collect` — loop over an array and gather the results.
+- `Subflow` — runs another operation (by id) with mapped input and emits its output. This is how one operation calls an internal flow.
+- `requireAuth` — verifies the request against an auth policy and attaches `{ user }` for downstream nodes (usually you rely on `_meta.json`/`http.auth` instead; use this node only for in-flow checks).
+
+## Auth
+
+Auth is resolved per operation by walking its path from the API root down:
+
+- `_meta.json` at any level sets a default `auth` policy `{ scheme: 'bearer'|'apiKey', secretRef, header?, verify? }` inherited by every op at or below it. The nearest ancestor wins.
+- An operation overrides via `http.auth`: a policy object (use that policy), `'none'` (explicitly public, ignoring inherited policy), or `'inherit'`/absent (defer to the nearest `_meta.json`).
+- No `_meta.json` and no `http.auth` → public. A present-but-corrupt `_meta.json` fails closed (the op is denied, not mounted open).
+
+## Environment auth (login once, auto-attach)
+
+Separate from operation `auth` above: an *environment* in `emberflow.environments.json`
+(git-ignored) can carry an `auth` block so runs against a real backend authenticate
+automatically instead of failing 401 — `{ attach: {as:'cookie'|'header', name, secretRef},
+login?: {request:{method,url,headers?,bodyRef?}, capture} }`, where `capture` is
+`{from:'set-cookie', cookieName?}` / `{from:'json', path}` / `{from:'header', name}`
+and `bodyRef` names a secret holding the login credentials as a JSON string. Once
+configured and logged in, the runner attaches the stored credential to every
+studio/CLI run against that environment — you never see the secret value, only
+`«secret:KEY»` in run output/logs. Run `login-environment <name>` when an op fails
+401/unauthorized and `list-environments` shows auth configured but not authenticated
+(also use it after scaffolding a new auth block, to verify capture works). If the
+login target enforces CSRF origin checks (e.g. better-auth), add a trusted `origin`
+header to `login.request.headers`.
+
+`attach.prefix` prepends a fixed string to the credential at attach time (e.g.
+`"Bearer "` for a captured token, `"Basic "` when the secret already holds
+`base64(user:pass)`). Set (or clear with `--json 'null'`) an environment's auth
+block from the CLI: `set-environment-auth <name> --json '<EnvAuth JSON>'`.
+
+When a user asks you to set up auth for an environment (the studio's Manage
+Environment dialog's "Set up with AI"), the flow is: compose the `EnvAuth`
+JSON from what they describe (curl command, prose, or both) — `attach`
+(`as`, `name`, `secretRef`, optional `prefix`) plus an optional `login`
+(`request` + `capture`) — apply it with `set-environment-auth`, then tell the
+user exactly which secret key(s) to fill in under the dialog's Secrets section
+(a `bodyRef` for the login request body, or the `attach.secretRef` for a
+static key with no login), and verify with `login-environment` once those
+secrets are set. If `login-environment` fails, read the error, adjust the
+auth JSON, re-apply, and retry.
+
+Two rules are load-bearing here: **never** edit an environment's `auth`
+block in `emberflow.environments.json` directly — `set-environment-auth` is
+the only way to change it (the rest of the file is structure-only and safe to
+read/edit); and **never** ask for, accept, or handle a credential value
+yourself — secret values live in `emberflow.secrets.json` (chmod `0600`,
+which you never touch), and the user always enters them in the studio dialog,
+never in chat or a CLI arg.
+
+## Scenarios
+
+A scenario is `{ id, name, input, description?, expect? }` in the
+`<operation>.scenarios.json` sidecar. For an HTTP operation, `input` is the
+request shape `{ params?, query?, body?, headers? }` — running the scenario
+passes it through the exact same path a live HTTP request uses, so a green
+scenario is real parity. `emberflow run <id> --scenario <name>` runs the op
+with that input. In the studio, the Run split-button's dropdown lists
+scenarios; each row has a play (run) and a step (step-through) button.
+Adding/removing scenarios in the studio round-trips to the sidecar file.
+
+**IMPORTANT: when you build or edit an operation, give its scenarios an
+`expect`** so `emberflow test` actually covers them — a scenario with no
+`expect` (or `expect: {}`) is silently skipped, not asserted. `expect` is
+`{ status?, body?, executedNodes? }`: `body` is checked as a **deep subset**
+of the real response (every key you list must match, recursively; extra
+response keys are fine — don't restate the whole payload), `executedNodes`
+lists node ids that must have reached `succeeded`. Every scenario that
+exercises a distinct branch should assert `status` + `executedNodes` for
+that branch, so a suite of green scenarios is proof, not vibes:
+
+```json
+{
+  "id": "not-found",
+  "name": "unknown id",
+  "input": { "params": { "id": "missing" } },
+  "expect": { "status": 404, "executedNodes": ["lookup", "notFoundResponse"] }
+}
+```
+
+Run the suite with `npx emberflow test [opId] [--environment NAME]
+[--json]` — in-process, no runner needed, exit `0`/`1`/`2`. It does **not**
+auto-attach environment auth (hermetic by design); a scenario that needs
+auth must carry the header/cookie in its own `input`. It also never fires
+`errorOperation` (below) — treat `emberflow test` failures as assertion
+failures, not incidents.
+
+Add `--mock` to run scenarios as Mock runs (`mockRun: true`) instead of for
+real: infrastructure nodes (`traceKind` db/http/llm) return their sidecar
+mock (op-level `mocks`, overlaid by the scenario's own `mocks` per nodeId)
+instead of touching real Postgres/HTTP/LLM, and fail loudly if a scenario
+exercises one with no mock. It's the hermetic way to prove branch coverage
+on infra-heavy ops without live infrastructure — `npx emberflow test <opId>
+--mock`.
+
+**After creating or editing any operation, run `npx emberflow doctor
+<opId>` and resolve every finding before you consider the work done.** It
+reports coded diagnostics — `missing-param-default` (a `:param` in the
+HTTP path with no value under the Input node's `defaults.params`; leaves
+the studio Run button disabled), `param-no-real-scenario` (no scenario
+supplies a real value for a path param), `no-expects` (nothing asserts the
+operation). `doctor --fix` seeds missing param defaults as `""`
+placeholders; real ids in scenarios are your job — pull one from the
+project's data when you can. Exit `0` means advisory-only findings; the
+studio shows the same diagnostics as a problems chip in the toolbar.
+
+## Retry and error workflow
+
+- **`retry` on a node** — `{ "maxTries": 3, "waitMs": 500 }`, sibling of
+  `config`/`optional` in the node JSON. Reach for it on nodes that call a
+  flaky external (HTTP, a third-party SDK): `maxTries` is total attempts
+  including the first, `waitMs` a fixed delay between them, and only the
+  implementation call retries (input/config resolve once). Pair with
+  `"optional": true` when the flow should fail soft after retries exhaust
+  rather than abort the run.
+- **`errorOperation` in `emberflow.config.mjs`** — an op id to run whenever
+  a *server* run (live HTTP endpoint or `POST /runs`) finishes `failed`. It
+  receives `{ failedRunId, failedWorkflowId, failedNodeId, error,
+  environment }`. Use it for alerting/logging side-effect ops, not for
+  business logic — it never fires for its own runs, firing is best-effort,
+  and `emberflow test`/scenario runs never trigger it.
+
+## Mock mode
+
+Mock is the studio's design-first mode. The environment dropdown's first
+row is Mock; picking it is instant, and picking a real environment while
+mocked goes live behind a "Go live?" confirm. A project with NO
+`emberflow.environments.json` boots in Mock by default (nothing real to
+serve against); creating environments — by hand, or via the dropdown's
+"Manage environments…" modal whose Set-up-with-AI action opens the agent
+panel in environment-setup mode (chat dispatches the `setup-environments`
+intent) — is what unlocks going live. That intent scaffolds
+environment entries, vars and `protected` flags but never secret values.
+
+**Mock runs execute.** In Mock, Run/Step/scenario runs execute the flow
+for real — routing, mappings, step-through — except infrastructure nodes
+(`traceKind` `db`/`http`/`llm`) return canned outputs from the scenarios
+sidecar's `mocks` maps instead of calling their implementations. Shape:
+top-level `"mocks": { "<nodeId>": <output> }` (plain Run uses this) plus
+optional per-scenario `mocks` (scenario wins per nodeId); the value is the
+node's OUTPUT verbatim — read the node implementation to match its shape.
+An infra node with no mock FAILS the mock run loudly (nothing real is ever
+touched; no auth attached; subflow children inherit mock mode and use
+their own op-level mocks). `compute`/unmarked nodes run their real logic —
+so set `traceKind` honestly when authoring nodes: an unmarked infra node
+silently executes for real in mock runs. `doctor` reports uncovered infra
+nodes as `missing-node-mock`. When you author scenarios for an op with
+infra nodes, ALWAYS write the mocks maps (cover-operation does this).
+Never put secret values in mocks.
+
+Serving is switchable at runtime via `POST /serving {mode}`, `emberflow serving <real|mock>` from the terminal, or the studio's environment dropdown; `emberflow serve --mock` / `dev --mock` mounts every HTTP endpoint but
+answers purely from a scenario's `expect` — no auth, no node execution.
+Selection order: `x-emberflow-scenario` request header (exact scenario
+name) → `__scenario` query param → the first scenario on that op with an
+`expect`. A named-but-unknown scenario is `404`; an op with no mockable
+scenario is `501`. Every response carries `x-emberflow-mock: true`, and the
+server logs a MOCK MODE banner at boot. Useful for pointing a frontend at
+stable canned responses without wiring real backends — but it means an op
+needs at least one scenario with `expect` before `--mock` can serve it.
+Note: mock serves `expect.body` verbatim as the WHOLE response — a partial subset body written for testing is returned as-is.
+
+## Validation
+
+The runner validates operations: unknown node types, missing edges/handles, orphan
+regions, self-referential subflows all surface as errors/warnings. A clean op
+runs; an invalid one is rejected. Run the plain Run/default-input path plus one
+scenario per branch, and check the run console — the logs stream node-by-node
+with input/output you can click into.
+
+## Related skills
+
+- **emberflow-new-workflow** — design and build a brand-new HTTP operation from a goal.
+- **emberflow-model-process** — port existing functionality into Emberflow: one process as an operation, or a whole subsystem as an API (its "At subsystem scale" section).
+- **emberflow-review-workflow** — review an operation before it ships.

package/templates/skills/emberflow-model-process/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: emberflow-model-process
+description: Use when modeling or MIGRATING EXISTING functionality into Emberflow — a single process (script, controller, job, runbook) as one operation, or a whole subsystem (a worker, a pipeline, a service's job handlers) as an API of operations. Emphasises verbatim porting, branch fidelity, determinism, and (at subsystem scale) decomposition and seam verification. For designing something brand-new, use emberflow-new-workflow instead.
+metadata:
+  version: 2.7.0
+---
+
+# Modeling an existing process as an Emberflow operation
+
+Read **emberflow-basics** first. This skill is the discipline for turning a real,
+already-working process into an operation that mirrors it — the goal is
+*fidelity*, not reinvention. Done well, the operation becomes executable
+documentation of the system. Sections 1–6 govern each individual port; when
+the source is a whole subsystem spanning several operations, ALSO apply
+**At subsystem scale** at the end.
+
+If the process is (or is triggered by) an HTTP endpoint, model it as an HTTP
+operation: create `emberflow/apis/<api>/<folder…>/<name>.json` with `id` equal to
+that path (`emberflow/apis/billing/charge.json` → `"billing/charge"`), add the
+`http` trigger `{ method, path }` matching the real route, start with an `Input`
+receiving `{ params, query, body, headers }`, and end in a `Response` emitting
+`{ status, body }` — mirror the real endpoint's status codes. A process with no
+HTTP surface is an internal flow (no `http`) ending in `Result`.
+
+## 0. Intake — interview the user before you port
+
+The source code tells you the logic; it cannot tell you how the user wants the
+model to run. Interview them BEFORE porting — one short question at a time,
+skipping anything already answered by the project or the source:
+
+Check `emberflow/infrastructure.json` FIRST: if the scout has already mapped
+this project's databases, APIs and providers, reuse those systems and their
+secret NAMES instead of re-deriving infrastructure the manifest already names.
+
+1. **Environments — only when the project doesn't already answer it.**
+   Environments are PROJECT-level (`emberflow.environments.json` is shared by
+   every API and operation) — read it first. If it already covers what the
+   port needs, note that and move on; don't re-interview per operation. Ask
+   only when the file doesn't exist ("Which environments — local, dev,
+   staging, prod? Default? Production-like?") or the port introduces a delta
+   (a var or environment nothing carries yet). Production-like →
+   `protected: true` (safe mode by default; mutations dry-run). Scaffold via
+   `setup-environments`; environment auth via `set-environment-auth`, never a
+   hand-edit.
+2. **Secrets — same scoping.** Existing keys need no questions. For NEW keys
+   the ported dependencies introduce (the DB URL, API keys you found in the
+   source), propose names and ask whether values differ per environment. You
+   only handle `secretRef` NAMES — the user enters values in the studio's
+   Manage Environment dialog, never in chat or any file/argument you produce.
+3. **Mocks.** "Do you have a captured response or a real representative row
+   from the source system I should use as the canned data?" Mock values
+   sourced from the real system make mock runs exercise real shapes — this is
+   the difference between a trustworthy model and a green-but-lying one.
+4. **Scenarios.** "Beyond one scenario per branch of the source, which
+   specific cases do you want named and asserted?" (A known incident, a
+   particular account shape, the case that motivated the port.)
+
+Confirm the summary before porting. The answers feed sections 4–6.
+
+## 1. Read the source first, fully
+
+Find and read the actual implementation — the script, controller, job, or written
+runbook. Identify:
+
+- **The steps**, in execution order.
+- **The decisions** — every `if`/`switch`/early-return/threshold. These become
+  `Conditional`/`Route` nodes. Note the exact conditions and constants.
+- **The side effects** — DB writes, external POSTs, emails, queue sends. These
+  become custom nodes marked `effects: 'mutation'`.
+- **The inputs and external data sources** it reads.
+
+Do not skim. A faithful model requires knowing what the code actually does,
+including the edge cases.
+
+## 2. Port logic VERBATIM
+
+Copy the real constants, formulas, thresholds, and branch order into your custom
+node implementations — do not "improve", round, or simplify them. If the source
+uses `>= 0.7` and `MAX = 30`, your node uses `>= 0.7` and `30`. The whole value
+is that the flow behaves exactly like the system.
+
+- Keep a `PORT NOTE:` comment where your model diverges from the source for a
+  real reason (e.g. the original interleaves two passes; the flow does them in
+  order). Divergences must be deliberate and documented.
+- Where the source calls an in-process function you can't run here, model it as a
+  node with the same inputs/outputs and note the substitution.
+
+## 3. Call out ambiguities — do not silently resolve them
+
+If the source is contradictory (a comment says one threshold, the code uses
+another), port the **code** (the source of truth), and surface the discrepancy to
+the user rather than quietly picking one. Dead code, unreachable branches, and
+stale constants are findings worth reporting — not things to tidy away.
+
+## 4. Map the shape onto Emberflow
+
+- Request in → an `Input` node reading `{ params, query, body, headers }` (for an
+  HTTP op); response out → a `Response` node `{ status, body }` per real exit,
+  matching the source's status codes (internal flow → `Result`).
+- Linear steps → a chain of nodes with `inputMap` + edges.
+- Decisions → `Conditional` (ordered rules) or `Route` (switch on a field), one
+  branch per real code path, including the else/default. A branch that returns a
+  different HTTP status gets its own `Response`.
+- Loops over collections → `ForEach`/`Collect`.
+- Sub-procedures the source factors out → a `Subflow` node calling a separate
+  operation (mirror the real call structure — if `handleA()` calls `handleB()`,
+  operation A calls operation B).
+- Effects → `effects: 'mutation'` nodes that dry-run by default and only commit
+  under an explicit opt-in. The commit path performs the REAL side effect the
+  source performs — the same insert, the same webhook, the same send. A
+  "[SIMULATED]"-success commit path is forbidden: if the credential isn't set,
+  commit THROWS naming the secretRef. The port isn't operational until a
+  mutation has committed for real against a real environment (or is explicitly
+  reported "operational-pending" with the exact secrets needed).
+- Infrastructure boundaries → set `traceKind` (`'db'|'http'|'llm'`) on every
+  node that reads a database, calls an external service, or invokes a model.
+  Mock mode intercepts by `traceKind`; an unmarked infra node silently executes
+  for real during mock runs.
+
+**Reuse a node when one fits; author a new one when none does** — inventing
+nodes is expected, it's how a process becomes real code. The only rule: register
+a node's implementation in `registerNodes` before you reference its `type`; the
+runner rejects an unregistered type (a name with no implementation), but a type
+you register in the same change is exactly how you model the step.
+
+## 5. Make it deterministic and reproducible
+
+Real processes read the clock, the DB, live data. For a faithful, testable model,
+lift those into node **inputs** (a `now` timestamp, a fetched snapshot) so a
+scenario can pin them. Every branch of the original gets a scenario whose pinned
+input drives exactly that path — named for the case it reproduces
+("critically-low", "poor-forecast", "already-ran-today").
+Also set Input `defaults` for every required field needed by the studio's plain
+Run button, or explicitly report that plain Run is intentionally unsupported.
+Scenarios prove branches; defaults prove the unscoped authoring run works.
+
+**Model both worlds: real implementations AND mocks.** The ported node
+implementations call the real dependencies (the actual query, the actual API,
+the actual model) — verbatim porting means real code, not canned data in the
+implementation. Then, in the same change, author the sidecar `mocks` maps so
+the model also runs in mock mode: a top-level `"mocks": { "<nodeId>": <output> }`
+covering every `traceKind` infra node, plus per-scenario `mocks` where a branch
+needs different canned data. Source the mock values from realistic outputs of
+the original system (a captured response, a representative row) so mock runs
+exercise the same shapes the real system produces. An infra node with no mock
+fails the mock run loudly; `doctor` reports it as `missing-node-mock`. A model
+that only runs against live infrastructure isn't executable documentation —
+and one that only runs mocked was never proven faithful.
+
+## 6. Prove fidelity
+
+Run both: plain Run and every scenario — in mock mode always, and against a
+real environment when one exists. Confirm the flow reaches the same decision
+the real system would for each input. Where you have reference outputs from the
+source system, assert the flow matches them. Run `npx emberflow doctor <opId>`
+and clear every finding (including `missing-node-mock`). Then run
+**emberflow-review-workflow**.
+
+## At subsystem scale (migrating a worker / pipeline / job family)
+
+When the source is a whole subsystem, the per-operation discipline above still
+governs each port — these rules govern the campaign around it. The core
+lesson from real migrations: **the serious defects live in the wiring between
+correct nodes, not in the ported logic** — an inputMap reading a field the
+producer never emits, a single object wired where the consumer maps an array,
+`timestamp` vs `date` keys, an identity (signalId, token) dropped between
+phases — and a wrongly-shaped mock masks every one of them.
+
+- **Scout first, completely.** Before designing, write down: entry points and
+  triggers (cron/queue/HTTP), the phases in execution order with file:line,
+  every constant in a table (that table becomes the fidelity checklist all
+  reviews check against), external dependencies per phase, and the data
+  shapes phases pass each other.
+- **One operation per process boundary.** A queue or cron hop in the source is
+  an operation boundary in the model — do NOT collapse an async boundary into
+  a synchronous `Subflow` (the fan-out op models the *send*; the per-job op is
+  invoked separately). A sub-procedure called in-process IS a `Subflow`.
+- **Inventory existing nodes before authoring new ones** — migrations often
+  land where partial models already exist. Reuse and extend.
+- **Producers own their output contracts.** If a consumer needs rows, the
+  producer emits rows — inputMap cannot compose objects or wrap arrays. When
+  a seam mismatch surfaces, fix the producer node, never the mock.
+- **Mocks are truthful.** A mock is the producer's real emittable output,
+  verbatim — never the shape the consumer wishes for; that is exactly how
+  wiring bugs go green. A `Subflow` mock uses whatever the child's Result
+  terminals actually emit (run the child; don't imagine an aggregate).
+- **Drive branch scenarios through real logic.** Prefer feeding the REAL
+  detector/gate a crafted infra mock (a series that genuinely promotes, spend
+  that genuinely overspends) over mocking the compute node itself — a
+  scenario that cans the detector it claims to prove proves only wiring.
+- **Verify the seams, then the system.** Check every inputMap sourceField
+  against the producer's outputSchema as you wire (doctor's
+  `inputmap-schema-mismatch` catches misnamed fields but NOT type/shape drift
+  on a correctly-named field — that check is yours). After per-op reviews
+  (emberflow-review-workflow on every op), run one whole-system review with
+  fresh eyes over the full diff, tracing infra-node inputs through REAL node
+  implementations with fixture data — mock-green proves nothing about real
+  mode. Finish with a real-mode spot check against a real environment (safe
+  mode on); if credentials block it, report "real-mode pending" — never imply
+  live parity you didn't prove.
+
+## The bar
+
+Someone who knows the original system should read the flow and recognise it
+exactly — same steps, same decisions, same constants, same effects — with every
+divergence explicitly marked. If they'd be surprised by a branch, you modeled it wrong.
+For a subsystem migration the same bar holds system-wide, and both worlds must
+work: every scenario green in mock mode, and the real path proven or explicitly
+pending.