procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/FORM-DEV-GUIDE/06-PROCESS-INTEGRATION.md

@@ -0,0 +1,347 @@
+# 06 — Wiring a form control to a process
+
+How a control triggers a PROCESIO process, how data goes in, how results come back
+into fields, and the design rule that saves a day of debugging: **one process
+output variable per form field.**
+
+---
+
+## 1. The event
+
+A `RUN_PROCESS` event on a control's trigger ([01](01-ANATOMY.md) §6):
+
+```json
+{
+  "id": "<guid>",
+  "type": "INPUT",
+  "action": "RUN_PROCESS",
+  "config": {
+    "processId": "<process guid>",
+    "syncRun": true,
+    "inputMap":  [ … ],
+    "outputMap": [ … ]
+  }
+}
+```
+
+**`syncRun: true` holds the line open** until the process finishes — verified live
+across a multi-second external API call. With `syncRun: false` the form fires and
+forgets, so an `outputMap` can never populate anything.
+
+**One event per trigger.** Two `RUN_PROCESS` events on the same trigger launch the
+process twice; the second result overwrites the first and the timing is not
+deterministic. When rewiring, use `--replace` rather than appending.
+
+## 2. The map rows — the shape that took three attempts to get right
+
+```json
+{
+  "id": 0,
+  "left":  {"value": "<PROCESS VARIABLE GUID>", "isList": false, "path": {}},
+  "right": {"value": "<form value path>",       "isList": false, "path": null}
+}
+```
+
+Four rules, each learned the hard way:
+
+1. **The process-variable GUID goes on the LEFT** — in `inputMap` *and* in
+   `outputMap`. A variable *name* on the left is accepted by the API, but the
+   designer then renders raw guids and the launch 400s.
+2. **Each side is an OBJECT, not a bare string.** Bare strings are accepted by the
+   API and produce a row the designer cannot render.
+3. **The two sides differ**: the process side carries `path: {}`, the form side
+   `path: null`. Discovered by reading a mapping the designer itself had written.
+4. **`path` carries the attribute chain** when a model-typed variable is mapped one
+   attribute at a time. Rebuilding a row without carrying `path` over silently maps
+   the whole object into a single text field — the classic `[object Object]`
+   in every field.
+
+The form side's value is the full field path from [01](01-ANATOMY.md) §5:
+
+```
+{dmRootId}.{FIELDS_NS}.{elementId}.{valueConfigId}
+```
+
+with `FIELDS_NS = 11223344-5566-7788-99aa-aabbccddeeff` (constant on every form).
+
+## 3. Wire it with the tool, not by hand
+
+`form-set-element-event` does a surgical read-modify-write: it touches **only** that
+element's event config, resolves variable names to guids, and fails loudly *before
+writing anything* if a name is unknown.
+
+```bash
+python scripts/run-tool.py procesio form-set-element-event \
+  --id <form-id> --element <element-name-or-id> \
+  --on input --action RUN_PROCESS --replace \
+  --config-file event.json --dry-run
+```
+
+Drop `--dry-run` to write. Inspect what is currently wired with:
+
+```bash
+python scripts/run-tool.py procesio form-get-element-events --id <form-id> --element <name>
+```
+
+Because it resolves names, `event.json` can be written readably:
+
+```json
+{"processId": "<guid>",
+ "inputMap":  [{"left": "input_file", "right": "<form value path>"}],
+ "outputMap": [{"left": "o_first_name", "right": "<form value path>"}]}
+```
+
+It also defaults `syncRun` to `true`, so you cannot forget it.
+
+## 3b. Driving a RUN_PROCESS from script: wait out the debounce (measured 2026-10-17)
+
+When a custom UI writes a control's value from script (native value setter + `input`
+event) and then clicks the control's RUN_PROCESS button with `element.click()`, the
+process receives the value the field had BEFORE the write unless the script waits first.
+Measured on a public form: a 300 ms wait, with or without a blur, sent the stale value;
+600, 800 and 1000 ms sent the new one every time. A finer run put the threshold at the form's
+~500 ms debounce: at 100, 250 and 400 ms 18 of 18 launches got the old value, at 500 and 650 ms
+11 of 11 got the new one. So write, wait about 560 ms, then click.
+Serialise these calls (one queue), or two writes interleave and each click sends the other's
+value. The click works on a button that is off screen. A process round trip from click to
+the output landing in the field took 0.7 to 1.0 s for a small Node-only flow. It is two
+sequential requests: `POST /api/formProcess/{formId}/{processId}/publish` (creates the instance,
+~300-470 ms) then `POST /api/formProcess/{formId}/{instanceId}/launch?runSynchronous=true`
+(~670-800 ms for ~260 ms of execution), so roughly 1.1-1.2 s per call whatever the flow does. A
+Node action costs ~56-85 ms of execution each and a Query Store ~16 ms: keep form-facing flows to
+few Nodes (pass one JSON value into SQL and unpack it with `JSON_EXTRACT` rather than one Node
+per column). For a live
+"N results" count while the visitor is still choosing, filter a cached copy in the browser
+and keep the process for the authoritative search and the logging.
+
+## 3c. The wire, request by request (measured on the forms host, 2026-10-22)
+
+What a RUN_PROCESS sends, for a runtime that has to follow one run among several:
+
+| request | carries |
+|---|---|
+| `POST /api/formProcess/{formId}/{processId}/publish`, body = the input values | answers the process VARIABLE list (inputs echoed as `defaultValue`), **no instance id** |
+| `POST /api/formProcess/{formId}/{instanceId}/launch?runSynchronous=true\|false&secondsTimeOut=300`, body `{"flowTemplateId": processId, "connectionId": …}` | the instance id is minted by the CLIENT and sits in the URL; the answer is `{"instanceId"}`, plus `status` + `variable` (outputs) when synchronous |
+| `GET /api/formProcess/{formId}/{processId}/{instanceId}/variables` (async only, polled) | `{"id", "status", "variables": [{name, defaultValue = the value, …}]}`, final at status 50 (finished) or 40 (finished with errors) |
+
+So tie a run to its process by the launch request BODY (`flowTemplateId`) and read the instance
+id from the launch URL; `/variables` carries both ids. A required process input whose form side
+is empty is refused at publish: `HTTP 400 statusCode 373 "Missing required input for variables:
+<name>"`, nothing launches.
+
+A File output mapped to a control is fetched ONCE, right after the run, by
+`GET /api/formProcess/download` with no query string: the file is named by request HEADERS
+(`flowtemplateid`, `formtemplateid`, `instanceid`, `variableid`, `workspaceid`, `uploadfilepath` =
+`flow/flow-<processId>/flow-instance-<instanceId>/variable-<variableId>/<fileId>`), cookie auth,
+answer = the bytes with `content-disposition: attachment; filename=…`. A File output that is empty
+still triggers the call with `uploadfilepath: undefined` and gets a 400; harmless, but it shows in
+the console.
+
+**A synchronous step keeps the form locked for its whole run.** While a chain runs every button is
+`disabled` ([08](08-PITFALLS.md)); with `syncRun: true` that lasts until the process ends (measured:
+a hidden RUN_PROCESS button stayed `disabled` for the 33 s a document-generating process took, and
+came back the moment it answered). With `syncRun: false` the chain ends at launch, so a hidden poll
+button can run while the async process is still going. A runtime that clicks a hidden button after
+a sync step must wait for `button.disabled === false`, not for a timer.
+
+**A list loaded at FORM_LOAD goes stale while the page stays open** (a signer signs, a status
+moves on). To refresh it without a page reload, put the same RUN_PROCESS on a hidden button whose
+output map writes the dynamic row again; the table re-renders from the new value and the selected
+detail stays where it is. Controls set by the chain that OPENED a record (MAPs on its status) do
+not follow the new row by themselves: reopen the record, or tell the user it moved on.
+
+**Testing a form runtime without running anything (measured 2026-10-22).** Route
+`**/formProcess/**/launch*` in Playwright, pick the run by the request body's `flowTemplateId`, and
+fulfill it with `{"instanceId": "<any guid>", "status": 50, "variable": {<output name>: <value>},
+"error": []}`. The form maps that answer exactly like a real synchronous one: outputs land in
+their fields and variables, `visible` outputs show their controls, and the chain's MAP conditions
+then run on the faked values. Nothing launches on the server (the publish before it only
+registers the inputs). This is how to rehearse states the test data no longer has; File outputs
+left out simply leave their viewers empty.
+
+## 4. Design rule: **one output variable per field, all primitives**
+
+The tempting design is one structured output variable (a data model, or a JSON blob)
+mapped attribute-by-attribute into the fields. Do not. The attribute-path shape on
+the form side of a map row is typed `left: any` in the renderer, so it is **not
+derivable** — you would be guessing, and a wrong guess writes `[object Object]`
+into every field with no error anywhere.
+
+The design that works:
+
+```
+File → Base64 → Decisional (branch by applicant type)
+                 ├── Call API  (branch A)  → Node: parse → structured result
+                 └── Call API  (branch B)  → Node: parse → structured result
+                            ↓
+                          Join
+                            ↓
+        one small "splitter" Node per field, each returning a plain string
+                            ↓
+        o_first_name, o_last_name, o_tax_code, …   (string outputs)
+```
+
+Each splitter is three lines:
+
+```js
+const o = <%0%>;                                  // the structured result
+return (o && o.field_name != null) ? String(o.field_name) : '';
+```
+
+Then `outputMap` is a flat list of **primitive → field** rows. No paths, nothing to
+guess, and every row is independently debuggable. The extra dozen Node actions cost
+nothing at runtime and buy a wiring you can reason about.
+
+**Do not add a hidden "carrier" field to the form** to receive the blob and then
+distribute it in JavaScript. It puts a second copy of the data in the DOM, it needs
+its own gating so it never shows, and the outputMap already populates fields
+natively — which is also the honest completion signal (§6).
+
+## 5. Notes on the process side
+
+- **A file input's variable is `FileDataModel`**, not a primitive type. `file` is
+  not a type.
+- **`Call API v3` is superseded** — use `Call API`, with `Response Status`,
+  `Response Body`, and `Time Out`. The framework's `process-create` refuses
+  superseded actions outright.
+- **A `Node` action's `Timeout` must be 60–300.** `30` is rejected by the validation
+  gate. `Node` returns its value raw; a `Javascript` action wraps it as
+  `{result: v}` — a difference that silently changes every downstream reference.
+- **`Decisional` is a diamond** and fans out any number of branches; they do not
+  have to re-converge, but a `Join` is the explicit merge point when they should.
+- Parse defensively at the boundary and return a *diagnosable* object rather than
+  throwing:
+
+  ```js
+  const r = <%0%>;
+  try {
+    const a = r.choices[0].message.tool_calls[0].function.arguments;
+    return (typeof a === 'string') ? JSON.parse(a) : a;
+  } catch (e) {
+    return ({ warning_status: true,
+              warning_message: 'Could not read the extraction service response.',
+              _err: String(e && e.message) });
+  }
+  ```
+
+  A thrown error inside a Node stops the flow and tells the form nothing. A returned
+  warning object flows on and can be surfaced to the user.
+
+- Carry a **`warning_status` / `warning_message` pair** through to the form. When an
+  external model returns mostly nulls (a partially legible document), that is an
+  *extraction quality* result, not a wiring failure — and the two are indistinguishable
+  from the form unless the process says which it was.
+
+## 6. The form side: detect arrival from the fields themselves
+
+```js
+/* The extraction is done when the platform has written into the fields — the
+   outputMap populates them natively, so there is no carrier to read. Detecting the
+   values themselves is also the honest signal: it is true exactly when there is
+   something worth showing. */
+function extractionArrived() {
+  var found = false;
+  fields().forEach(function (el) {
+    if (found) { return; }
+    if (!fieldKey(el)) { return; }
+    var f = q('input, textarea', el);
+    if (f && String(f.value || '').trim()) { found = true; }
+  });
+  return found;
+}
+```
+
+## 7. The full pattern: upload → veil → reveal only what applies
+
+```js
+/* 1. The upload starts the work: raise a HELD veil (the network is silent, so the
+      quiet-timer heuristic would lift it immediately). */
+D.addEventListener('change', function (e) {
+  var input = e.target;
+  if (!input || input.type !== 'file' || !input.files || !input.files.length) { return; }
+  if (!input.closest || !input.closest('.form-builder--file-upload')) { return; }
+  if (currentStep() !== IDENTITY_STEP) { return; }     // other steps just collect documents
+  window.__uxExtracting = true;
+  showVeil('Reading the document…', true);
+}, true);
+
+/* 2. Every refresh pass decides what the step shows. */
+function identityStep(active) {
+  if (active !== IDENTITY_STEP) { return; }
+  var arrived = extractionArrived();
+
+  if (arrived && window.__uxExtracting) {              // 3. dismiss the held veil
+    window.__uxExtracting = false;
+    hideVeil();
+  }
+
+  var ready = true;
+  fields().forEach(function (el) {
+    if (q('input[type=file]', el) || el.querySelector('.form-builder--file-upload')) {
+      return;                                          // the upload always stays
+    }
+    var key = fieldKey(el);
+    if (!key) { return; }
+
+    var group = FIELD_GROUP[key];                      // 'a' | 'b' | undefined
+    var mine  = !group || group === currentApplicantKind();
+
+    // Hidden until the document has been read, and then only the half that
+    // belongs to the chosen applicant type.
+    el.classList.toggle('ux-gated', !arrived || !mine);
+    if (!arrived) { ready = false; return; }
+    if (!mine) { return; }
+
+    var ok = validate(el, key);
+    if (el.offsetParent !== null && !ok) { ready = false; }   // only VISIBLE fields gate
+  });
+
+  gateNext(ready);                                     // 4. → appears only when complete
+}
+```
+
+Three details that matter:
+
+- **`el.offsetParent !== null`** is the real "is this visible" test. Counting a
+  hidden field against readiness makes the next button unreachable forever, with no
+  visible cause.
+- **`FIELD_GROUP` decides visibility here as well** as in the form's own logic. The
+  form's logic keys off its own state and runs on its own schedule; deciding here
+  too means the step never shows the wrong half, not even for the frame between the
+  results landing and that logic running.
+- **The upload is exempt from every gate.** It is the only thing on the step before
+  the results arrive, and it must stay reachable afterwards so a wrong document can
+  be replaced.
+
+## 8. Offer a manual escape
+
+Extraction from a photographed document fails sometimes. When the veil's ceiling
+fires, say so and let the person continue by hand — a form that can only be
+completed when a model cooperates is not a form.
+
+```js
+window.UXToast('This is taking longer than usual. You can fill the fields in manually.', 'err');
+```
+
+## Data store from a form (not an element - an event action)
+
+A form talks to a data store through an **event action**, not a dedicated element. On any
+element's `field-events`, add an `Event` with `action: "RUN_DATA_STORE_OPERATION"` and a
+config:
+
+```json
+{ "action": "RUN_DATA_STORE_OPERATION",
+  "config": {
+    "dataStoreId": "<uuid>",
+    "operation": "READ",                       // READ | ADD | UPDATE | DELETE
+    "inputMap":  [{ "id": 0, "left": "page", "right": "1" },
+                  { "id": 1, "left": "countPerPage", "right": "1000" }],
+    "outputMap": [{ "id": 0, "left": "rows", "right": "<target var/element>" }] } }
+```
+
+Canonical fields: `page`, `countPerPage`, `rows`, `success`. At runtime the form calls
+`api/Form/dataStore/{id}/rows` (scoped to the template's workspace, PRC-5559). For reading
+a data store from a PROCESS (not a form) use the **Query Store** action (see
+`../PROCESIO-CONNECTORS-NOTES.md`). The process-designer data-store node adds the control
+types `data-store-mapper` / `data-store-decisional` (`FeComponentType` 46 / 47) with a
+richer decisional operator set (BETWEEN, IN/BELONGS, IS_EMPTY→IsNull, IS_NOT_EMPTY→IsNotNull).

procesio_cli/tools/procesio/FORM-DEV-GUIDE/07-DEPLOY-WORKFLOW.md

@@ -0,0 +1,294 @@
+# 07 — Shipping it: tooling, testing, recovery
+
+How the CSS and JS get onto a live form without destroying it, how to test before
+you publish, and how to get back when you do not.
+
+---
+
+## 1. Never use `form-edit` to restyle an existing form
+
+`form-edit` is a **desired-state** editor: it rebuilds the whole DTO from a config.
+Pointing it at a large hand-authored form to change one thing means re-declaring
+every element — or losing them. On a form with a hundred-plus hand-built elements,
+that is the end of the form.
+
+Use the **surgical** actions. Each does a read-modify-write on the live DTO and
+touches exactly one thing:
+
+| Action | Touches | Everything else |
+|---|---|---|
+| `form-get-code` | nothing (read) | — |
+| `form-set-code` | `Data.code` only | elements, theme, data model, events byte-identical |
+| `form-get-element-events` | nothing (read) | — |
+| `form-set-element-event` | one element's one event config | every sibling byte-identical |
+| `form-get-element` | nothing (read) | — |
+| `form-set-element-config` | one element's plain configs | every sibling byte-identical |
+| `form-set-element-chains` | the ordered event chains of the listed element triggers, in ONE save | every other element byte-identical; kept events verbatim |
+
+Every write path maps the GET's camelCase onto the PUT's PascalCase envelope
+explicitly, so an unexpected extra field is never echoed back.
+
+### `form-set-element-config` — content and per-field rules belong in the DTO
+
+`label`, `placeholder`, `required`, `regex`, `visible`, `tooltip`, `defaultValue`.
+Rewriting a banner from the form-level JS instead is a trap worth naming: it is
+invisible in the designer, it has to be re-applied on every render, and it fights the
+runtime's own MutationObserver.
+
+```bash
+# long HTML from a file, so the copy lives under version control
+python scripts/run-tool.py procesio form-set-element-config \
+  --id <form-id> --element idhead --set-file label=elements/idhead.html --dry-run
+
+# scalars are parsed as JSON when they parse, so this stores a real boolean
+python scripts/run-tool.py procesio form-set-element-config \
+  --id <form-id> --element intro1 --set visible=false
+```
+
+Two refusals it makes on purpose, both before writing anything:
+
+- **a config the element does not already carry.** Adding one would also need a
+  data-model attribute whose id equals the new config's id; without it the designer
+  renders raw guids and values never flow ([01](01-ANATOMY.md) §5).
+- **an event config.** Those go through `form-set-element-event`, which resolves
+  process-variable names to guids and enforces one event per trigger.
+
+Config **ids are preserved** on every rewrite — a fresh id there breaks every value
+path pointing at that attribute.
+
+## 2. The loop
+
+**Check the key on each installation before the first write.** `form-set-code` encrypts
+with the key stored for the call's environment (§3), and refuses when there is none
+rather than borrow another installation's. A wrong key stored under the right name still
+gets through: the write succeeds and the form goes blank ([08](08-PITFALLS.md)). So first
+read back the code of a form whose CSS was written in the designer, on the same
+installation:
+
+```bash
+python scripts/run-tool.py procesio form-get-code --id <designer-edited-form> \
+  --css-out check.css
+```
+
+If it does not decrypt, stop there: the stored key is wrong for this installation (§3).
+
+```bash
+# 1. Pull the current code down to files
+python scripts/run-tool.py procesio form-get-code --id <form-id> \
+  --css-out form.css --js-out form.js
+
+# 2. Edit form.css / form.js locally, in a real editor, under version control
+
+# 3. Preview the write without performing it
+python scripts/run-tool.py procesio form-set-code --id <form-id> \
+  --css-file form.css --js-file form.js --dry-run
+
+# 4. Ship
+python scripts/run-tool.py procesio form-set-code --id <form-id> \
+  --css-file form.css --js-file form.js
+```
+
+Success looks like:
+
+```json
+{"updated": true, "css_bytes": 24157, "javascript_bytes": 28793, "elements": 135}
+```
+
+**Check `elements` on every write.** It is the count on the DTO you just PUT back.
+If it ever drops, you are not doing what you think you are doing — stop.
+
+### Omitting one side preserves it
+
+Passing only `--css-file` keeps the existing JavaScript untouched, and vice versa.
+Restyling never silently drops the behaviour layer.
+
+### Every overwrite is recoverable from the tool output
+
+`form-set-code` returns the **previous** decrypted css/js under `previous`. Pipe the
+output to a file when you are doing something risky, and a mistaken overwrite is a
+copy-paste away from being undone:
+
+```bash
+python scripts/run-tool.py procesio form-set-code --id <form-id> \
+  --js-file form.js > /tmp/last-write.json
+```
+
+### A 2xx is not a save: `form-set-code` reads the form back
+
+The platform has answered form writes with 2xx while storing nothing: `PUT /api/FormTemplate`
+moved `updatedOn` but left every `Data` field as it was (the code, even `browserTitle`), and
+`POST /api/FormTemplate` and `.../duplicate` returned forms with `data: null` (seen on
+Internal-PROD 2026-10-18, every payload shape, PascalCase and camelCase alike; the designer UI
+saves through the same endpoint, so it is not a client bug). The public page then keeps serving
+the old code, which looks exactly like a CDN cache that never expires.
+
+So `form-set-code` re-reads the form after the PUT and returns `verified: true`, or fails with
+**`not_persisted`** (details: `sent_bytes`, `stored_bytes`, `kept_previous`). On that error,
+create a tiny scratch form (`POST /api/FormTemplate` with `data: {elements: []}`) and read it
+back: `data: null` means the platform is not storing form content at all, so stop retrying and
+report it; real data means another editor saved the form between your read and your write.
+
+## 3. Credentials
+
+Two different secrets that look alike — both short opaque tokens:
+
+| Secret | What it does |
+|---|---|
+| the workspace **API key** (name + value) | gets you **at** the form (auth) |
+| `agents-and-tools:procesio:form-code-key@<environment>` | gets you **into** `Data.code` (AES passphrase), one per installation |
+
+```bash
+python scripts/set-credential.py procesio form-code-key@Internal-QA
+```
+
+The form-code passphrase is **installation-wide**: it decrypts the code blob of every
+form on that installation, and it cannot be cheaply rotated. Treat it accordingly —
+never in a file, never in a chat, never in a log.
+
+**One key per installation, stored per environment.** The platform team confirmed it:
+the key is the same on every workspace of an installation and is not guaranteed to
+match on another. An environment is how this tool names an installation, so the key is
+stored as `form-code-key@<environment>`. The bare `form-code-key` still works as the
+default environment's key, the same rule as a credential with no environment binding,
+and the tool never uses it for any other environment. A missing key is an error that
+names the secret to store.
+
+**It is not a secret from the people who open a form.** The renderer decrypts
+`Data.code` in the visitor's browser, so the passphrase reaches every browser that loads
+a form, and anyone who can open a form can read its CSS and JavaScript. Keep the key out
+of files, chats and logs as the rules require. Treat the form code itself as public: no
+credentials, no internal names, nothing you would not print on the page.
+
+### Diagnosing a decrypt failure
+
+A wrong passphrase and a corrupt blob are indistinguishable at the API layer: both
+surface as a `UnicodeDecodeError` after AES has run and emitted garbage. To tell
+them apart, round-trip `encrypt_code` / `decrypt_code` with a throwaway key. If that
+works, the cipher is fine and the **key** is wrong.
+
+## 4. Test on a replica, not on the live form
+
+The most expensive mistake available here is publishing straight to a live process
+or a live public form. Two levels of testing, and both are cheap:
+
+**A local HTML replica.** Save a rendered copy of the form, inline your CSS and JS,
+and open it in a browser. Because the installer falls back to `window` when there is
+no parent frame ([02](02-CODE-INJECTION.md) §4), the same file runs unchanged. This
+catches the majority of DOM and timing bugs, and it lets you *measure* a transition
+instead of guessing:
+
+**Replicate the whole flow, not one screen.** A single-step mock cannot exercise the
+two things most likely to break — the step gate and whatever bridges the DOM to the
+platform's field model — so those are exactly what nothing tests. A replica worth
+building carries: a fake `window.ProcesioForm.data.fields` with the DTO's own names,
+`required` flags and regexes; the form's own element-event visibility logic; the REAL
+`data-element-id` values; and a step change that **destroys and rebuilds** the controls
+(`box.innerHTML = …`), because that is what makes "state stored on a node" fail here
+the same way it fails live. Give it a harness row of buttons for the states that are
+otherwise unreachable (pick each branch, simulate the process result landing, fill the
+current step) and a `?raf=timeout` switch so it can be driven in a background tab.
+
+```js
+// in the page console — prove the class actually lifts
+setTimeout(() => console.log('at120',
+  box.classList.contains('ux-leaving'), getComputedStyle(box).opacity), 120);
+setTimeout(() => console.log('at600',
+  box.classList.contains('ux-leaving'), getComputedStyle(box).opacity), 600);
+```
+
+Run the same navigation **twice** and confirm nothing accumulates — a second copy of
+a listener, a class that never clears, a growing node count.
+
+**A small public test form on the live renderer**, for runtime mechanics a replica
+cannot reproduce (debounce timing, which chain fires when, the lock during a chain).
+Build the smallest form that exercises the mechanism (`form-create`, a stepper with
+two or three steps, the same `form.js`), give it a CustomUrl + `IsPrivate: false`,
+wire it with the same tool calls you will use on the real form, and drive it
+headless with the `web` tool. A saved session that is an EMPTY storageState
+(`{"cookies": [], "origins": []}`) is an anonymous browser. `eval` steps read live
+state (an input's `.value` property, `disabled`, which step is rendered) and can time
+a click. Delete the form and its CustomUrl afterwards. This is how a login-gated
+production form can still be changed on evidence: the gate blocks the headless run
+on the real form, not on the copy of its mechanism.
+
+**A duplicated form is the quickest test bench for a restyle.** `form-duplicate` keeps every
+element id and the data model's root id (the ORIGINAL form id), so every value path and
+event mapping still resolves in the copy (verified 2026-10-22). The copy comes back as a
+draft named `… (Copy)`: publish it (`form-update --status 1 --state true --is-private false`),
+then bend it into each state you need to see. Make the hidden sections visible, put a base64
+PDF in a file viewer's `src` (a raw base64 string renders), drop a load process's
+`outputMap` so it cannot hide what you made visible, or swap a submit button's RUN_PROCESS
+for a MAP_FORM_DATA that shows the success section. A state that real data cannot reach
+(no valid token left, a success that writes to a database) gets tested there, on the real
+renderer, with the exact build you will ship.
+
+**A duplicated process**, for anything on the process side. `procesio` can duplicate
+a process; change the copy, run the copy, and promote the change only once it works.
+Editing a live process that a public form is calling means every submission in
+flight is your test.
+
+**State plainly what you verified.** "Verified on the local replica" and "verified on
+the live form" are different claims. Do not let one stand in for the other.
+
+**Test the code you ship.** If the build minifies or bundles the scripts, point the
+replica at the built files. A replica that loads the sources leaves the shipped code with
+no browser test at all. Static checks are weaker still on built output: one that read
+minified CSS raised a false alarm, and the rendered page, measured with
+`getComputedStyle`, settled it.
+
+**Some failures exist only on the live form, signed in.** A replica that draws its own
+select hides a list the live form never hands over, and the first-frame flash needs the
+real renderer (both in [08](08-PITFALLS.md)). Open the live form and log what the page
+does every 50 ms. That is how both were found.
+
+## 5. Keep the source under version control — outside the framework
+
+The CSS and JS are the form's real source. `Data.code` is a deployment target, not a
+repository: it is encrypted, it has no history, and it cannot be diffed.
+
+Keep the files in the user-data area (`context-state-knowledge/resources/...`), not
+in `tools/` — a specific client's form is user data, and the framework/user-data
+boundary is hard. What belongs in the framework is the **generalized** knowledge:
+this guide.
+
+Alongside the CSS and JS, keep the process artifacts that are equally
+un-round-trippable — prompts, request bodies, the process definition — so a rebuild
+does not start from a screenshot.
+
+**Build each form from source in every workspace. Do not import it in.** An import keeps
+the form's id ([PROCESIO-API-NOTES](../PROCESIO-API-NOTES.md), *What an API import
+carries*), so one id then lives in several workspaces, and the copies do not fail
+together. Seen once: after a platform change, two imported copies came back empty and
+would not open, while the original kept its content. Rebuilt from source with new ids,
+they were back in minutes. Deleting a form touches only its own workspace, which is what
+makes that repair safe; prove it on a throwaway form before you rely on it. Find forms by
+name, never by a stored id, and let no save write when the read before it came back
+empty. The tool's surgical actions refused in exactly that case.
+
+## 6. Write the reasoning into the file, at the top
+
+Both files should open with a header stating **how the thing runs** and **which rules
+must never be broken**, with the symptom attached. This is not decoration: `Data.code`
+carries no history and the next person to open it — including you, in three months —
+has no other way to know.
+
+```css
+/* Two rules this file must never break, both learned on the live form:
+   - NO `overflow: hidden` on `.form-builder--form` — it kills page scrolling.
+   - NO `transform` on `.form-builder--form` — it makes the card the containing
+     block for `position: fixed` descendants, so the renderer's pinned footer
+     lands on top of the content. Entrances animate opacity only. */
+```
+
+The test for a good comment here: it names the **symptom** a future reader would
+otherwise chase, not just the rule.
+
+## 7. Before you touch a shared form
+
+- Confirm the form id and the workspace, out loud, before the first write.
+- `form-get-code` first, always — even when you are sure the form has no code. The
+  output *is* your backup.
+- One change per write when debugging. Two changes in one write means a regression
+  has two suspects.
+- After any change to a manifest or a contract, update the manifest in the same
+  commit (Hard rule 4) and re-run the tool's tests before publishing.