@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/.agents/skills/ppc-pipefy-pipe-authoring/SKILL.md

@@ -1,146 +1,146 @@
----
-name: ppc-pipefy-pipe-authoring
-description: Use when writing or editing the JSON of a Pipefy pipe's structure in a pipefy-process-coder workspace — phases, fields, automations, field conditions, labels, webhooks, pipe relations, preferences, public form. Covers the file layout, referencing entities that do not exist yet, and the specific edits that fail silently because a mutation accepts them and ignores them.
----
-
-# Authoring pipe structure JSON
-
-Read `ppc-pipefy-workspace` first for the loop and the identity rules. This is the
-detail: what goes in which file, and which edits look fine and are not.
-
-## Where things live
-
-```
-pipes/<id>--<name>/
-  pipe.json                    the repo row: name, noun, public, title_field_id
-  phases/NN--name.json         the phase, its fields[], jump_target_ids[], team_member_ids[]
-  automations/<name>.json      the automation, its condition, field_maps, response_schemas
-  field-conditions/<name>.json the condition and its actions
-  labels.json  webhooks.json  public-form.json  preferences.json  relations.json
-  _readonly/  _non-snapshot/  _meta.json
-```
-
-**Fields live inside their phase file.** That is where they make sense and where
-you will edit them most. Ordering comes from the `index` value inside the file,
-never from the filename — renumbering works without renaming.
-
-The start form is a real phase at `index: 0`. Deleting or reindexing it is
-catastrophic; the validator refuses.
-
-## Creating something new
-
-```json
-{ "id": null, "_new": true, "uuid": "<fresh v4>", "label": "Severity", "type_id": "select", … }
-```
-
-A new field nested in an existing phase file needs no `phase_id` — it inherits its
-owner's. A field in a *new* phase leaves it null; the compiler substitutes the
-phase's real id after the phase is created.
-
-**Referencing something you are creating in the same edit:** leave
-`%{_new:<its uuid>}` and the applier substitutes the real id once it exists. This
-works in automation `field_maps`, condition `field_address`, `jump_target_ids`,
-and field-condition action targets.
-
-## What cannot be changed at all
-
-| Edit | Why |
-| --- | --- |
-| a field's `type_id` | `updatePhaseField` has no `type_id`. Delete+create destroys every existing value. |
-| a field's `phase_id` | same — no input, and moving it would destroy the data |
-| a phase's `index` | `createPhase` takes an index, `updatePhase` does not |
-| a pipe's `description` | `UpdatePipeInput` has no `description` field at all |
-| `start_form_title` | no input on any preference mutation |
-| anything under `_readonly/` | no public write path exists |
-
-If a request needs one of these, say so and stop. `pipe plan` refuses them per
-column, with the reason.
-
-## The silent failures — every one of these cost a live incident
-
-These are edits the API *accepts* and does not apply, or applies wrongly. They are
-guarded now, but understanding them stops you writing them.
-
-**A mutation can succeed and change nothing.** Arguments are filtered against the
-live schema, so an argument the mutation has no input for is dropped and the call
-returns success. `description`, `anyone_can_create_card` and `create_card_label`
-all did this on `updatePipe`. That is why the registry names settable columns per
-entity rather than trusting the mutation.
-
-**Some arguments want a uuid where the payload stores an id.**
-`updatePipe.title_field_id` takes the field's **uuid** or slug, never the numeric
-id the payload holds. `archiveField` takes `{ uuid }`. Both are translated for you.
-
-**`phaseSettings` reports failure for changes it has already made.** Observed on
-three separate runs, with the row present in the read-back and timestamped to the
-failing call. Its errors are inconclusive — re-read before assuming nothing
-happened.
-
-**`hidden_top_buttons` and `hidden_start_form_attributes` are closed sets:**
-`Assignees, Attachments, Checklist, Comments, DueDate, Labels`. Anything else is
-rejected mid-apply. Checked offline now.
-
-**Every event and action accepts a fixed parameter list, and nothing enforces it.**
-Read `REFERENCE.md` in the workspace before writing an automation. It is generated
-by `pipe pull` from the API and lists each event's `event_params`, each action's
-`action_params`, and which pairings are refused.
-
-The reason it needs reading: the schema publishes these lists, then types
-`event_id`, `action_id` and `type_id` as `ID` and `String`, so GraphQL validates
-none of them. A wrong value returns `is invalid` or `All fields must be filled
-properly.` — naming nothing — partway through an apply. And the mistakes are
-near-misses, not nonsense:
-
-- `card_moved` takes only `to_phase_id`. `in_phase_id` is real, on
-  `card_inbox_received_email`.
-- `card_id` is accepted on `update_card_field` and refused on `move_single_card`.
-
-`pipe validate` catches all of it offline and names the parameter, so run it before
-`plan`. Treat it as the backstop, not the reference.
-
-**Automation params mix naming conventions.** `AutomationActionParamsInput` has
-`card_id`, `to_phase_id` and `field_map` in snake_case, but `taskParams`,
-`aiParams` and `httpMethod` in camelCase. Getting one wrong deleted a live
-automation once, because the update strategy is delete-then-recreate.
-
-**Pipe relation flags are spelled differently in the mutation and the payload.**
-`createPipeRelation` says `canCreateNewItems`; the payload row says
-`can_create_connected_cards`. Set both, or read the one that is there.
-
-**A phase's jump set is set-replacing.** `jump_target_ids` is written whole. Never
-append blindly to a set you have not fully read.
-
-## Cross-surface obligations
-
-**Deleting a field obliges you to fix every reference to it.** Automations and
-conditions hold bare numeric ids inside opaque JSON — `"field_address": "<fieldId>"`,
-`"trigger_field_ids": ["<fieldId>"]`, `"%{<fieldId>}"`. `pipe validate` fails on a
-dangling reference by design. `MAPPING.md` translates every id.
-
-**If the pipe has iPaaS flows, a field may be referenced there too**, by slug,
-and the tool cannot yet see it. Check `flows/` if it exists before deleting a
-field. See `ppc-pipefy-flow-authoring`.
-
-## A worked shape: creating a phase with fields and a jump
-
-The numbers below are made up — use the real ids from `MAPPING.md`.
-
-```json
-// phases/09--customer-validation.json
-{
-  "id": null, "_new": true, "uuid": "<fresh v4>",
-  "name": "Customer Validation", "index": 9, "done": false,
-  "repo_id": 100200300,
-  "fields": [
-    { "id": null, "_new": true, "uuid": "<fresh v4>", "label": "Customer acceptance",
-      "type_id": "select", "options": ["Accepted", "Needs rework", "Declined"],
-      "index": 0, "required": false, "repo_id": 100200300 }
-  ],
-  "jump_target_ids": [400500600],
-  "team_member_ids": []
-}
-```
-
-Set `index` on new phases explicitly and leave existing ones alone — their index
-cannot be edited. Creating a phase auto-links jumps, so state the jump set you
-want or the platform's default stands.
+---
+name: ppc-pipefy-pipe-authoring
+description: Use when writing or editing the JSON of a Pipefy pipe's structure in a pipefy-process-coder workspace — phases, fields, automations, field conditions, labels, webhooks, pipe relations, preferences, public form. Covers the file layout, referencing entities that do not exist yet, and the specific edits that fail silently because a mutation accepts them and ignores them.
+---
+
+# Authoring pipe structure JSON
+
+Read `ppc-pipefy-workspace` first for the loop and the identity rules. This is the
+detail: what goes in which file, and which edits look fine and are not.
+
+## Where things live
+
+```
+pipes/<id>--<name>/
+  pipe.json                    the repo row: name, noun, public, title_field_id
+  phases/NN--name.json         the phase, its fields[], jump_target_ids[], team_member_ids[]
+  automations/<name>.json      the automation, its condition, field_maps, response_schemas
+  field-conditions/<name>.json the condition and its actions
+  labels.json  webhooks.json  public-form.json  preferences.json  relations.json
+  _readonly/  _non-snapshot/  _meta.json
+```
+
+**Fields live inside their phase file.** That is where they make sense and where
+you will edit them most. Ordering comes from the `index` value inside the file,
+never from the filename — renumbering works without renaming.
+
+The start form is a real phase at `index: 0`. Deleting or reindexing it is
+catastrophic; the validator refuses.
+
+## Creating something new
+
+```json
+{ "id": null, "_new": true, "uuid": "<fresh v4>", "label": "Severity", "type_id": "select", … }
+```
+
+A new field nested in an existing phase file needs no `phase_id` — it inherits its
+owner's. A field in a *new* phase leaves it null; the compiler substitutes the
+phase's real id after the phase is created.
+
+**Referencing something you are creating in the same edit:** leave
+`%{_new:<its uuid>}` and the applier substitutes the real id once it exists. This
+works in automation `field_maps`, condition `field_address`, `jump_target_ids`,
+and field-condition action targets.
+
+## What cannot be changed at all
+
+| Edit | Why |
+| --- | --- |
+| a field's `type_id` | `updatePhaseField` has no `type_id`. Delete+create destroys every existing value. |
+| a field's `phase_id` | same — no input, and moving it would destroy the data |
+| a phase's `index` | `createPhase` takes an index, `updatePhase` does not |
+| a pipe's `description` | `UpdatePipeInput` has no `description` field at all |
+| `start_form_title` | no input on any preference mutation |
+| anything under `_readonly/` | no public write path exists |
+
+If a request needs one of these, say so and stop. `pipe plan` refuses them per
+column, with the reason.
+
+## The silent failures — every one of these cost a live incident
+
+These are edits the API *accepts* and does not apply, or applies wrongly. They are
+guarded now, but understanding them stops you writing them.
+
+**A mutation can succeed and change nothing.** Arguments are filtered against the
+live schema, so an argument the mutation has no input for is dropped and the call
+returns success. `description`, `anyone_can_create_card` and `create_card_label`
+all did this on `updatePipe`. That is why the registry names settable columns per
+entity rather than trusting the mutation.
+
+**Some arguments want a uuid where the payload stores an id.**
+`updatePipe.title_field_id` takes the field's **uuid** or slug, never the numeric
+id the payload holds. `archiveField` takes `{ uuid }`. Both are translated for you.
+
+**`phaseSettings` reports failure for changes it has already made.** Observed on
+three separate runs, with the row present in the read-back and timestamped to the
+failing call. Its errors are inconclusive — re-read before assuming nothing
+happened.
+
+**`hidden_top_buttons` and `hidden_start_form_attributes` are closed sets:**
+`Assignees, Attachments, Checklist, Comments, DueDate, Labels`. Anything else is
+rejected mid-apply. Checked offline now.
+
+**Every event and action accepts a fixed parameter list, and nothing enforces it.**
+Read `REFERENCE.md` in the workspace before writing an automation. It is generated
+by `pipe pull` from the API and lists each event's `event_params`, each action's
+`action_params`, and which pairings are refused.
+
+The reason it needs reading: the schema publishes these lists, then types
+`event_id`, `action_id` and `type_id` as `ID` and `String`, so GraphQL validates
+none of them. A wrong value returns `is invalid` or `All fields must be filled
+properly.` — naming nothing — partway through an apply. And the mistakes are
+near-misses, not nonsense:
+
+- `card_moved` takes only `to_phase_id`. `in_phase_id` is real, on
+  `card_inbox_received_email`.
+- `card_id` is accepted on `update_card_field` and refused on `move_single_card`.
+
+`pipe validate` catches all of it offline and names the parameter, so run it before
+`plan`. Treat it as the backstop, not the reference.
+
+**Automation params mix naming conventions.** `AutomationActionParamsInput` has
+`card_id`, `to_phase_id` and `field_map` in snake_case, but `taskParams`,
+`aiParams` and `httpMethod` in camelCase. Getting one wrong deleted a live
+automation once, because the update strategy is delete-then-recreate.
+
+**Pipe relation flags are spelled differently in the mutation and the payload.**
+`createPipeRelation` says `canCreateNewItems`; the payload row says
+`can_create_connected_cards`. Set both, or read the one that is there.
+
+**A phase's jump set is set-replacing.** `jump_target_ids` is written whole. Never
+append blindly to a set you have not fully read.
+
+## Cross-surface obligations
+
+**Deleting a field obliges you to fix every reference to it.** Automations and
+conditions hold bare numeric ids inside opaque JSON — `"field_address": "<fieldId>"`,
+`"trigger_field_ids": ["<fieldId>"]`, `"%{<fieldId>}"`. `pipe validate` fails on a
+dangling reference by design. `MAPPING.md` translates every id.
+
+**If the pipe has iPaaS flows, a field may be referenced there too**, by slug,
+and the tool cannot yet see it. Check `flows/` if it exists before deleting a
+field. See `ppc-pipefy-flow-authoring`.
+
+## A worked shape: creating a phase with fields and a jump
+
+The numbers below are made up — use the real ids from `MAPPING.md`.
+
+```json
+// phases/09--customer-validation.json
+{
+  "id": null, "_new": true, "uuid": "<fresh v4>",
+  "name": "Customer Validation", "index": 9, "done": false,
+  "repo_id": 100200300,
+  "fields": [
+    { "id": null, "_new": true, "uuid": "<fresh v4>", "label": "Customer acceptance",
+      "type_id": "select", "options": ["Accepted", "Needs rework", "Declined"],
+      "index": 0, "required": false, "repo_id": 100200300 }
+  ],
+  "jump_target_ids": [400500600],
+  "team_member_ids": []
+}
+```
+
+Set `index` on new phases explicitly and leave existing ones alone — their index
+cannot be edited. Creating a phase auto-links jumps, so state the jump set you
+want or the platform's default stands.

package/.agents/skills/ppc-pipefy-process-design/SKILL.md

@@ -1,127 +1,127 @@
----
-name: ppc-pipefy-process-design
-description: Use when deciding HOW to build a requirement in Pipefy — which mechanism a need calls for (phase, field condition, automation, iPaaS flow, pipe relation, phase jump, connector field), and how to shape a process so it survives contact with real users. Read before authoring, when the question is "what should this look like" rather than "what JSON does this need".
----
-
-# Designing a process in Pipefy
-
-Most bad Pipefy builds are not bad JSON. They are the right JSON for the wrong
-mechanism — an automation doing what a field condition should, a `CODE` node doing
-what a piece action does, a flow built where a phase would have been enough.
-
-Pick the mechanism first.
-
-## Choosing the mechanism
-
-Work down this list and stop at the first one that fits. Each rung costs more to
-build, more to explain, and more to debug than the one above it.
-
-| Need | Mechanism | Why it is the cheapest fit |
-| --- | --- | --- |
-| Show or hide a field depending on another field | **field condition** | Instant, no run history, no failure mode. Never build this as an automation. |
-| Constrain where a card can move | **phase jump set** | Structural. The board enforces it; no rule can be out of date. |
-| Stamp a timestamp, copy a value, set a label, move a card, send a task or email — **within one pipe** | **automation** | Native, visible in the pipe, no external dependency, no separate credential |
-| Compute something from fields in the same card | **automation with a formula, or an AI action** | Still inside the pipe |
-| Link cards between two pipes so people can navigate between them | **pipe relation + connector field** | Structural and bidirectional. An automation that "creates a card" does not link anything. |
-| Hold a reusable list people pick from — departments, products, suppliers, services | **a database**, not a pipe | A database has columns and records but no workflow. Reach it with a `connector` field. Reaching for a pipe here gives you phases nobody moves cards through. |
-| Store rows that a process reads but nobody works on | **a database** | If a row has no owner and no next step, it is reference data. Cards are for work that moves. |
-| Create a card in another pipe when something happens | **automation with `create_card` and `action_repo_id`** | Cross-pipe *writes* are within the automation engine's reach |
-| **Read** a pipe other than the one that triggered | **iPaaS flow** | The automation engine cannot. This is the real dividing line. |
-| Touch anything outside Pipefy — Slack, HTTP, Sheets, an ERP | **iPaaS flow** | Only iPaaS has pieces |
-| Aggregate across many cards, or run on a schedule | **iPaaS flow** | No automation trigger does either |
-| Anything else, plus arbitrary logic | **iPaaS flow with a `CODE` node** | Last rung. See the ladder below. |
-
-### The dividing line worth memorising
-
-**An automation can write to another pipe. It cannot read one.** That single fact
-decides most automation-versus-flow questions. "When X completes, open a card in
-Y" is an automation. "When X completes, check whether the card in Y exists" is a
-flow.
-
-### Inside a flow, the same discipline applies
-
-1. A **piece action** that already does it — check the catalogue first.
-2. An **inline formula expression** in a free-text input.
-3. A **`CODE` node**, only when no piece fits and the logic exceeds a formula.
-
-A `CODE` node is where the destination of a write can be computed at runtime,
-which means no static check can see it. That is the most expensive kind of bug in
-this domain — prefer a piece.
-
-## Shaping the process itself
-
-**Name the phases after states, not actions.** "Qualification & Prioritization",
-not "Qualify". A card *is in* a state; it does not *do* a phase.
-
-**Every phase needs an exit.** A phase whose `jump_target_ids` is empty is a dead
-end — cards arrive and cannot leave. Author the jump set explicitly; creating a
-phase auto-links jumps, and the platform's default is rarely the process you meant.
-
-**Make required fields answerable at the moment they are asked.** An intake form
-that requires a value only known after triage is a form nobody can submit. Real
-example: a Customer Success intake required "Account tier" and "Customer impact",
-which meant an automated handoff from another pipe could never satisfy it — the
-form was blocked until both became triage-time fields.
-
-**Distinguish intake from work.** The start form is what the requester knows; the
-first phase is what the team adds. Do not put "Triage owner" on the start form.
-
-**Let the last phase mean something.** Set `done: true` on the phase that ends the
-process. Webhooks and `cardDone` triggers depend on it, and a pipe whose final
-phase is not marked done cannot fire either.
-
-**Give closure a reason.** A "Rejected / Closed" phase with a `select` for the
-reason turns a dead card into data. Without it, nobody can answer "why do we
-decline things".
-
-## Designing the integration, not just the flow
-
-**Silence on success, noise on failure.** A flow that messages someone every time
-things go right gets muted, and then the one that matters is invisible too. If both
-outcomes are worth saying, say different things — and make the failure louder.
-
-**Assume the other side can be missing.** A cross-pipe read returns an empty list
-when the thing you expected was never created. That empty list is usually the most
-interesting outcome — handle it in a `ROUTER` branch rather than letting the flow
-run on with nothing.
-
-**Let a search fail without stopping the flow.** Set `continueOnFailure` on the
-step that can legitimately find nothing, so the branch that reports "not found"
-is reachable.
-
-**Never assume a connection exists in another workspace.** Connections are
-pipe-scoped. A flow that works in one pipe will not import into another that has
-no connection for the same piece.
-
-## Reviewing a process someone else built
-
-Ask these in order. Each has caught a real problem.
-
-1. **Does every phase have an exit?** Check every `jump_target_ids`.
-2. **Can the start form actually be submitted** by the people and systems that
-   need to submit it?
-3. **Is any required field only knowable later?**
-4. **Does the final phase have `done: true`?**
-5. **Does anything reference a field that no longer exists?** `pipe validate`
-   answers this; a dangling reference is an error by design.
-6. **If the pipe has flows, does any of them read a field the pipe is about to
-   lose?** The tool cannot check this yet — look at `flows/` yourself.
-7. **Is any automation doing a field condition's job?** Those are the first
-   things to delete.
-8. **Are there duplicate automations?** Two identical rules on one trigger is
-   almost always the residue of a failed apply, not a decision.
-
-## Two failure modes specific to this tool
-
-**A partial apply leaves created entities looking new.** If an apply half-fails,
-the files may still say `"id": null, "_new": true` for things that now exist.
-Re-planning would create them twice. `pipe apply` repairs this automatically, and
-`pipe verify --adopt` does it on demand — but if you see a diff proposing to create
-something you know exists, that is the cause.
-
-**A clean `pipe diff` covers flows too** — but only where they were readable.
-Check `pipes/<id>--<name>/flows/_meta.json`: `coverage: "complete"` means the
-flows were compared and match. **`coverage: "unknown"` means iPaaS could not be
-reached for that pipe, so its flows were not compared at all** — and a pipe can
-diff clean while its actual behaviour changed entirely, because the change was in
-a flow nobody looked at. That is the one case where a clean diff is not proof.
+---
+name: ppc-pipefy-process-design
+description: Use when deciding HOW to build a requirement in Pipefy — which mechanism a need calls for (phase, field condition, automation, iPaaS flow, pipe relation, phase jump, connector field), and how to shape a process so it survives contact with real users. Read before authoring, when the question is "what should this look like" rather than "what JSON does this need".
+---
+
+# Designing a process in Pipefy
+
+Most bad Pipefy builds are not bad JSON. They are the right JSON for the wrong
+mechanism — an automation doing what a field condition should, a `CODE` node doing
+what a piece action does, a flow built where a phase would have been enough.
+
+Pick the mechanism first.
+
+## Choosing the mechanism
+
+Work down this list and stop at the first one that fits. Each rung costs more to
+build, more to explain, and more to debug than the one above it.
+
+| Need | Mechanism | Why it is the cheapest fit |
+| --- | --- | --- |
+| Show or hide a field depending on another field | **field condition** | Instant, no run history, no failure mode. Never build this as an automation. |
+| Constrain where a card can move | **phase jump set** | Structural. The board enforces it; no rule can be out of date. |
+| Stamp a timestamp, copy a value, set a label, move a card, send a task or email — **within one pipe** | **automation** | Native, visible in the pipe, no external dependency, no separate credential |
+| Compute something from fields in the same card | **automation with a formula, or an AI action** | Still inside the pipe |
+| Link cards between two pipes so people can navigate between them | **pipe relation + connector field** | Structural and bidirectional. An automation that "creates a card" does not link anything. |
+| Hold a reusable list people pick from — departments, products, suppliers, services | **a database**, not a pipe | A database has columns and records but no workflow. Reach it with a `connector` field. Reaching for a pipe here gives you phases nobody moves cards through. |
+| Store rows that a process reads but nobody works on | **a database** | If a row has no owner and no next step, it is reference data. Cards are for work that moves. |
+| Create a card in another pipe when something happens | **automation with `create_card` and `action_repo_id`** | Cross-pipe *writes* are within the automation engine's reach |
+| **Read** a pipe other than the one that triggered | **iPaaS flow** | The automation engine cannot. This is the real dividing line. |
+| Touch anything outside Pipefy — Slack, HTTP, Sheets, an ERP | **iPaaS flow** | Only iPaaS has pieces |
+| Aggregate across many cards, or run on a schedule | **iPaaS flow** | No automation trigger does either |
+| Anything else, plus arbitrary logic | **iPaaS flow with a `CODE` node** | Last rung. See the ladder below. |
+
+### The dividing line worth memorising
+
+**An automation can write to another pipe. It cannot read one.** That single fact
+decides most automation-versus-flow questions. "When X completes, open a card in
+Y" is an automation. "When X completes, check whether the card in Y exists" is a
+flow.
+
+### Inside a flow, the same discipline applies
+
+1. A **piece action** that already does it — check the catalogue first.
+2. An **inline formula expression** in a free-text input.
+3. A **`CODE` node**, only when no piece fits and the logic exceeds a formula.
+
+A `CODE` node is where the destination of a write can be computed at runtime,
+which means no static check can see it. That is the most expensive kind of bug in
+this domain — prefer a piece.
+
+## Shaping the process itself
+
+**Name the phases after states, not actions.** "Qualification & Prioritization",
+not "Qualify". A card *is in* a state; it does not *do* a phase.
+
+**Every phase needs an exit.** A phase whose `jump_target_ids` is empty is a dead
+end — cards arrive and cannot leave. Author the jump set explicitly; creating a
+phase auto-links jumps, and the platform's default is rarely the process you meant.
+
+**Make required fields answerable at the moment they are asked.** An intake form
+that requires a value only known after triage is a form nobody can submit. Real
+example: a Customer Success intake required "Account tier" and "Customer impact",
+which meant an automated handoff from another pipe could never satisfy it — the
+form was blocked until both became triage-time fields.
+
+**Distinguish intake from work.** The start form is what the requester knows; the
+first phase is what the team adds. Do not put "Triage owner" on the start form.
+
+**Let the last phase mean something.** Set `done: true` on the phase that ends the
+process. Webhooks and `cardDone` triggers depend on it, and a pipe whose final
+phase is not marked done cannot fire either.
+
+**Give closure a reason.** A "Rejected / Closed" phase with a `select` for the
+reason turns a dead card into data. Without it, nobody can answer "why do we
+decline things".
+
+## Designing the integration, not just the flow
+
+**Silence on success, noise on failure.** A flow that messages someone every time
+things go right gets muted, and then the one that matters is invisible too. If both
+outcomes are worth saying, say different things — and make the failure louder.
+
+**Assume the other side can be missing.** A cross-pipe read returns an empty list
+when the thing you expected was never created. That empty list is usually the most
+interesting outcome — handle it in a `ROUTER` branch rather than letting the flow
+run on with nothing.
+
+**Let a search fail without stopping the flow.** Set `continueOnFailure` on the
+step that can legitimately find nothing, so the branch that reports "not found"
+is reachable.
+
+**Never assume a connection exists in another workspace.** Connections are
+pipe-scoped. A flow that works in one pipe will not import into another that has
+no connection for the same piece.
+
+## Reviewing a process someone else built
+
+Ask these in order. Each has caught a real problem.
+
+1. **Does every phase have an exit?** Check every `jump_target_ids`.
+2. **Can the start form actually be submitted** by the people and systems that
+   need to submit it?
+3. **Is any required field only knowable later?**
+4. **Does the final phase have `done: true`?**
+5. **Does anything reference a field that no longer exists?** `pipe validate`
+   answers this; a dangling reference is an error by design.
+6. **If the pipe has flows, does any of them read a field the pipe is about to
+   lose?** The tool cannot check this yet — look at `flows/` yourself.
+7. **Is any automation doing a field condition's job?** Those are the first
+   things to delete.
+8. **Are there duplicate automations?** Two identical rules on one trigger is
+   almost always the residue of a failed apply, not a decision.
+
+## Two failure modes specific to this tool
+
+**A partial apply leaves created entities looking new.** If an apply half-fails,
+the files may still say `"id": null, "_new": true` for things that now exist.
+Re-planning would create them twice. `pipe apply` repairs this automatically, and
+`pipe verify --adopt` does it on demand — but if you see a diff proposing to create
+something you know exists, that is the cause.
+
+**A clean `pipe diff` covers flows too** — but only where they were readable.
+Check `pipes/<id>--<name>/flows/_meta.json`: `coverage: "complete"` means the
+flows were compared and match. **`coverage: "unknown"` means iPaaS could not be
+reached for that pipe, so its flows were not compared at all** — and a pipe can
+diff clean while its actual behaviour changed entirely, because the change was in
+a flow nobody looked at. That is the one case where a clean diff is not proof.