@pipefy/pipefy-process-coder 0.1.0 → 0.1.2

package/{src/workspace/docs.ts → dist/workspace/docs.js}

@@ -1,407 +1,367 @@
-import { join } from 'node:path';
-import { rm } from 'node:fs/promises';
-import { writeFile, exists } from '../util/fsx.ts';
-import type { Tree } from '../model/tree.ts';
-import type { Capabilities } from '../pipefy/capability.ts';
-import { registryRows } from '../apply/registry.ts';
-import type { Lock } from './lock.ts';
-import { paths } from './layout.ts';
-import { renderReferenceMd, type Reference } from '../pipefy/reference.ts';
-
-/**
- * The generated docs that are the whole interface for whoever edits this
- * workspace — PLAN.md §6. No agent baked into the app: the FDE pulls, edits
- * with an agent in a terminal, and publishes. These files are what make that
- * work unattended, regardless of which agent is reading them.
- */
-
-const AGENTS_MD = (lock: Lock, trees: Tree[]) => {
-  const reconstructed = lock.repos.filter((r) => r.source === 'reconstructed');
-  const unknownGroups = new Set<string>();
-  for (const r of lock.repos) {
-    for (const [name, cov] of Object.entries(r.coverage)) if (cov === 'unknown') unknownGroups.add(name);
-  }
-
-  return `# Editing this Pipefy workspace
-
-This directory is a Pipefy pipe (and everything it connects to) pulled to disk as
-JSON. Edit the JSON, then let \`pipe\` validate, plan and apply it. The rules below
-are not style preferences — breaking one either corrupts a live pipe or makes the
-apply refuse.
-
-## The loop
-
-\`\`\`bash
-pipe validate          # JSON shape + referential integrity. Instant, offline.
-pipe diff              # what you changed, against the last pull
-pipe plan --dry-run    # is every change actually applicable? refuses if not
-pipe apply             # snapshot, apply, verify
-\`\`\`
-
-**\`pipe validate && pipe plan --dry-run\` must both be clean before you propose an
-apply.** Iterate against them yourself; they need no network for validate and no
-writes for plan.
-
-## Identity rules
-
-- \`id\` is **server-owned**. Never invent one, never edit one, never reuse one.
-- A **new** entity is \`"id": null\` plus \`"_new": true\`. For \`phases\`, \`fields\`,
-  \`automations\` and \`labels\` — the only four arrays that have one — also add a
-  fresh v4 \`uuid\`. Everything else is identified by its owner.
-- To **delete**, remove the object (or the whole file). Do not set a tombstone.
-- \`_\`-prefixed keys are tool metadata. Leave them alone; they are ignored by
-  every comparator and never sent to the API.
-
-## What cannot be changed at all
-
-| Edit | Why it is refused |
-| --- | --- |
-| a field's \`type_id\` | \`updatePhaseField\` has no \`type_id\`. Doing it as delete+create destroys every existing value. |
-| a field's \`phase_id\` | \`updatePhaseField\` has no \`phase_id\`. Same data loss. |
-| a phase's \`index\` (reordering) | \`createPhase\` takes an index, \`updatePhase\` does not. |
-| anything under \`_readonly/\` | no public write path exists. Read it, reason with it, don't edit it. |
-| anything under \`_non-snapshot/\` | not part of the structure payload; never written back. |
-| the start-form phase's existence, \`index\`, or \`name\` | it is a real phase at index 0; deleting or reindexing it is catastrophic, and its name is referenced by other things (the public form, automations, a client's own docs) this tool cannot check for breakage. |
-
-If a request needs one of these, say so plainly and stop — do not work around it
-with a delete and a create.
-
-## Field references
-
-Automations and conditions refer to fields by numeric id inside opaque JSON:
-\`"recipients": "%{<fieldId>}"\`, \`"field_address": "433255493"\`,
-\`"trigger_field_ids": ["433255544"]\`. \`MAPPING.md\` translates every one of those
-numbers into a label and a phase.
-
-- **Deleting a field obliges you to fix every reference to it.** \`pipe validate\`
-  fails on a dangling reference, by design.
-- Referencing a field you are creating in the same edit is fine: leave the
-  placeholder \`%{_new:<uuid>}\` and the applier substitutes the real id after the
-  field exists.
-
-## Flows reference fields too, and \`pipe validate\` does not check them
-
-If this workspace has any \`flows/\` directories, they are iPaaS flows (Advanced
-Automations) — the same entities as the pipe, pulled, diffed, planned and
-applied by the same \`pipe pull/diff/plan/apply\` commands (\`--no-flows\` opts
-out). A flow's datapills address a field by **slug**, inside opaque strings:
-\`{{step_1['output'].data.card.fields.<slug>.value}}\`.
-
-- **\`pipe validate\` never looks inside a flow.** Renaming, retyping or deleting
-  a field is checked against automations and conditions, never against flow
-  datapills — a broken reference there is silent until the flow runs. Before
-  editing a field a flow might use, grep \`flows/\` for its slug yourself.
-- A field's slug does **not** change when its label is renamed (measured;
-  \`VALIDATION.md\` §3g), so a label-only rename is safe for existing datapills.
-  Anything that changes or removes the slug is not.
-- **Adding a node to an existing flow works if the node is reachable from the
-  trigger** — some other node's \`_nextAction\`, \`_firstLoopAction\` or a
-  branch's \`_children\` must point at it, which is how the diff finds the
-  parent to send \`ADD_ACTION\` after. An orphan node nothing points to is
-  still refused, by name, rather than guessed at.
-- Enabling a flow arms it against live traffic and is refused unless you pass
-  \`--allow-flow-enable\`, the same shape as \`--allow-card-moves\`.
-- Load the \`ppc-pipefy-flow-authoring\` skill before writing or debugging a flow by
-  hand — it covers node shapes, datapill syntax and the traps that validate
-  clean and resolve nothing at runtime.
-
-## Values that come from a closed set
-
-\`REFERENCE.md\` in this workspace lists what the API accepts in every position
-where a value must come from a fixed list: each automation event's
-\`event_params\`, each action's \`action_params\`, which events and actions cannot be
-paired, and the field \`type_id\`, \`color\` and \`filter\` sets. It was read from the
-API on the last pull.
-
-**Read it before writing an automation.** The schema publishes these lists and
-then types the inputs that consume them as \`ID\` and \`String\`, so a wrong value is
-not caught by GraphQL. It reaches a runtime check and comes back as \`is invalid\`
-or \`All fields must be filled properly.\` — naming no parameter, no event, and no
-accepted value, partway through an apply.
-
-The traps are near-misses, not nonsense. \`in_phase_id\` is a real parameter that
-belongs to \`card_inbox_received_email\`; \`card_moved\` takes only \`to_phase_id\`.
-\`card_id\` is real on \`update_card_field\` and refused on \`move_single_card\`.
-
-\`pipe validate\` checks all of this offline and names the parameter, so a wrong
-value costs a second rather than a half-applied change. It is a backstop, not a
-substitute for reading the file.
-
-## Where things live
-
-\`\`\`
-pipes/<id>--<name>/
-  pipe.json                    the repo row
-  phases/NN--name.json         phase + its fields[] + jump_target_ids[] + team_member_ids[]
-  automations/<name>.json      automation + condition + field_maps + response_schemas
-  field-conditions/<name>.json condition + actions
-  labels.json  webhooks.json  public-form.json  preferences.json  relations.json
-  _readonly/   _non-snapshot/  _meta.json
-databases/<id>--<apiId>--<name>/
-  table.json                   the database row
-  phases/00--start-form.json   the database's COLUMNS live here, as fields[]
-  phases/NN--*.json            record statuses — readable, no write path
-  README.md                    what each of those files actually is
-\`\`\`
-
-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, so renumbering works without renaming anything.
-
-${
-  reconstructed.length
-    ? `## This workspace was read without snapshots
-
-${reconstructed.length} of ${lock.repos.length} repo(s) were reconstructed from the
-GraphQL and internal APIs rather than from a snapshot payload. Consequences you
-must respect:
-
-${[...unknownGroups].sort().map((g) => `- \`${g}\` is **unknown**, not empty. Do not add to it and do not conclude the pipe has none.`).join('\n')}
-
-An \`unknown\` entity group is never diffed and never applied. \`_meta.json\` in each
-repo directory records exactly what was and was not read.
-`
-    : `## This workspace was read from snapshots
-
-Every entity group came from the snapshot payload, so absence means absence.
-`
-}
-## Secrets
-
-Webhook URLs are bearer-equivalent — possession is authorization — and
-HTTP-request automations can carry live credentials in \`action_params\`. This
-workspace has a \`.gitignore\`, but do not paste these files into anything, and do
-not commit the workspace.
-
-## Runs
-
-Pass \`--report\` to any of pull, apply, dry run or verify and it writes a folder
-under \`runs/\` recording what happened:
-
-\`\`\`
-runs/index.md                         one line per run, oldest first
-runs/<when>--<kind>/report.md         what happened, readable, no credentials
-runs/<when>--<kind>/run.json          the same thing structured
-runs/<when>--<kind>/pipe.json         the payload as of the end of that run
-runs/<when>--<kind>/integrations.json webhooks, relations, cross-repo automations
-\`\`\`
-
-An apply also writes \`pipe.before.json\`, so both sides of the change sit in one
-folder. Read \`report.md\` first — it is the only file in there written for a
-human.
-
-It is off by default: a run folder holds a full copy of the pipe, credentials
-included, and one per command would grow without bound. The record an apply
-needs in order to resume is the plan file under \`.ppc/plans/\`, which is always
-written.
-
-${trees.length ? `## This workspace\n\n${trees.map((t) => `- ${t.repo['name']} (${t.meta.repoKind} ${t.repo['id']}) — ${t.phases.length} phases, ${t.phases.reduce((n, p) => n + p.fields.length, 0)} fields, ${t.automations.length} automations, read from ${t.meta.source}`).join('\n')}` : ''}
-`;
-};
-
-const MAPPING_MD = (trees: Tree[], lock: Lock) => {
-  const sections = trees.map((t) => {
-    const fields = t.phases.flatMap((p) => p.fields.map((f) => ({ f, phase: String(p['name'] ?? '') })));
-    const fieldRows = fields
-      .map(({ f, phase }) => `| \`${f['id']}\` | ${f['label']} | \`${f['slug'] ?? ''}\` | ${f['type_id']} | ${phase} |`)
-      .join('\n');
-
-    const phaseRows = t.phases
-      .map(
-        (p) =>
-          `| ${p['index']} | \`${p['id']}\` | ${p['name']}${Number(p['index']) === 0 ? ' **(start form)**' : ''} | ${
-            p.fields.length
-          } | ${p.jump_target_ids.length ? p.jump_target_ids.map((j) => `\`${j}\``).join(', ') : '—'} |`,
-      )
-      .join('\n');
-
-    const autoRows = t.automations
-      .map(
-        (a) =>
-          `| \`${a['id']}\` | ${a['name']} | ${a['event_id']} → ${a['action_id']} | ${
-            a['action_repo_id'] !== a['event_repo_id'] ? `cross-repo → \`${a['action_repo_id']}\`` : 'same repo'
-          } | ${a.condition ? 'yes' : '—'} |`,
-      )
-      .join('\n');
-
-    const connectors = fields
-      .filter(({ f }) => f['type_id'] === 'connector')
-      .map(({ f, phase }) => `| \`${f['id']}\` | ${f['label']} | ${phase} | \`${f['connected_pipe_id']}\` |`)
-      .join('\n');
-
-    return `## ${t.repo['name']} — ${t.meta.repoKind} \`${t.repo['id']}\`
-
-### Phases
-
-| index | id | name | fields | jumps to |
-| --- | --- | --- | --- | --- |
-${phaseRows}
-
-### Fields
-
-| id | label | slug | type | phase |
-| --- | --- | --- | --- | --- |
-${fieldRows}
-
-### Automations
-
-| id | name | event → action | scope | condition |
-| --- | --- | --- | --- | --- |
-${autoRows || '| — | none | | | |'}
-
-${connectors ? `### Connector fields\n\n| field id | label | phase | connected repo |\n| --- | --- | --- | --- |\n${connectors}\n` : ''}`;
-  });
-
-  /**
-   * Edges name what they point at, not just its id.
-   *
-   * `301908697` on its own tells a reader nothing — and a connector field aimed
-   * at a database means something different from one aimed at a pipe: the target
-   * has columns and records rather than phases and cards. The repo is looked up
-   * in the lock, so a target outside the workspace still shows as unknown rather
-   * than being guessed at.
-   */
-  const byId = new Map(lock.repos.map((r) => [String(r.id), r]));
-  const edgeRows = lock.edges
-    .map((e) => {
-      const to = byId.get(String(e.to));
-      const target = to ? `${to.kind} · ${to.name}` : 'not in this workspace';
-      return `| \`${e.from}\` | \`${e.to}\` | ${target} | ${e.kind} | ${e.label ?? ''} |`;
-    })
-    .join('\n');
-
-  return `# Mapping
-
-Generated on pull. This is what makes \`%{<fieldId>}\` mean "Requester email".
-
-${sections.join('\n\n')}
-
-## Connections
-
-Discovered as the union of \`pipe_relations\`, connector fields, and cross-repo
-automations — connector fields alone find edges that neither \`pipe_relations\` nor
-\`pipeMapGraph\` reports (PLAN.md §2.2).
-
-| from | to | what it is | via | label |
-| --- | --- | --- | --- | --- |
-${edgeRows || '| — | — | — | — | — |'}
-`;
-};
-
-const CAPABILITIES_MD = (caps: Capabilities | null) => {
-  const rows = registryRows()
-    .sort((a, b) => a.key.localeCompare(b.key))
-    .map(
-      (r) =>
-        `| \`${r.entity}\` | ${r.op} | ${
-          r.status === 'SUPPORTED' ? 'yes' : r.status === 'PARTIAL' ? 'partly' : '**no**'
-        } | ${r.via ? `\`${r.via}\`` : '—'} | ${r.reason ?? ''}${r.ask ? ` _(ask ${r.ask})_` : ''} |`,
-    )
-    .join('\n');
-
-  const detected = caps
-    ? `## Detected on this endpoint
-
-| Capability | Present | Consequence if absent |
-| --- | --- | --- |
-| snapshots (\`createRepoSnapshot\`) | ${caps.snapshots ? 'yes' : '**no**'} | pulls reconstruct the structure over GraphQL instead |
-| \`restoreRepoSnapshot\` | ${caps.restoreRepoSnapshot ? 'yes' : '**no**'} | no atomic rollback; a failed apply is repaired forward |
-| \`createRepoDraft\` | ${caps.createRepoDraft ? 'yes' : '**no**'} | no free rehearsal environment; plans are checked, not proven |
-| \`importRepoSnapshot\` | ${caps.importRepoSnapshot ? 'yes' : 'no'} | Route B is unavailable; writes go through the mutation compiler |
-| internal API | ${caps.internalApi} | automation detail and phase-jump editing depend on it |
-
-${caps.internalApi === 'unavailable' ? '> The internal endpoint did not answer. Automations and phase jumps are reported as **unknown** rather than empty, and any change to them is refused rather than silently skipped.\n' : ''}`
-    : '';
-
-  return `# Capabilities
-
-Generated from the live registry in \`src/apply/registry.ts\`, so what you read
-here is what the applier will actually attempt. If something says **no**, propose
-a different change rather than a workaround.
-
-${detected}
-## Write coverage
-
-| Entity | Operation | Writable | Via | Notes |
-| --- | --- | --- | --- | --- |
-${rows}
-
-## Flows (iPaaS), separately from the table above
-
-Flows compile through \`src/apply/flowops.ts\`, not the registry above — they are
-still applied by the same \`pipe apply\` (skip with \`--no-flows\`), just tracked
-here rather than in the write-coverage table.
-
-| Change | Writable | Via | Notes |
-| --- | --- | --- | --- |
-| create a flow | yes | \`createFlow\` (whole tree) | built trigger-first, then each node in execution order |
-| delete a flow | yes | \`deleteFlow\` | destructive |
-| rename a flow | yes | \`CHANGE_NAME\` | |
-| update the trigger | yes | \`UPDATE_TRIGGER\` | whole node, not a sparse patch |
-| update an action | yes | \`UPDATE_ACTION\` | whole node; a router's branches live in \`settings.branches\`, so editing them is an \`UPDATE_ACTION\` on the router — there is no \`UPDATE_BRANCH\` |
-| delete an action | yes | \`DELETE_ACTION\` | destructive |
-| add a node **to an existing flow** | yes, if reachable from the trigger | \`ADD_ACTION\` | the parent is found by scanning the authored tree for whoever's \`_nextAction\` / \`_firstLoopAction\` / \`_children\` points at the new node. An orphan node nothing points to is refused by name |
-| enable a flow | partly | \`CHANGE_STATUS\` | arms it against live traffic — refused unless \`--allow-flow-enable\`, and refused outright while any connection it uses is still a placeholder |
-| disable a flow | yes | \`CHANGE_STATUS\` | |
-| a connection the flow needs but the project lacks | yes, as a placeholder | \`createConnection\` | created disabled with a placeholder credential so the structure can still be built; reconnect it for real before enabling |
-| whole-tree replace | **refused on purpose** | — | \`IMPORT_FLOW\` exists and is never used — it re-runs an old schema migration on an already-live tree and doubles every datapill (\`{{step_1['output'].x}}\` → \`{{step_1['output']['output'].x}}\`), resolving nothing at runtime while every validator still calls it valid |
-
-After any flow write, the applier reads the flow back and diffs its datapills
-against what was sent — the only check that catches the \`IMPORT_FLOW\`-shaped
-migration bug, and the reason a flow apply is not reported successful on the
-mutation's response alone.
-
-## The three that hurt most
-
-1. **Field type changes** — routine to ask for, impossible to do without
-   destroying data. Refused.
-2. **Moving a field between phases** — same.
-3. **Reordering phases** — \`createPhase\` takes an index, \`updatePhase\` does not.
-
-These are asks 2, 3 and 4 in \`ROUTE-B-V2.md\`. Every refusal pipe emits is a data
-point for them.
-`;
-};
-
-const GITIGNORE = `# A pulled workspace contains webhook URLs (bearer-equivalent: possession is
-# authorization) and HTTP-request automation credentials. Never commit it.
-.ppc/
-*.gz
-
-# Run folders hold a full copy of the pipe (runs/*/pipe.json) and its integration
-# surface, credentials included. The report beside them is redacted and can be
-# shared by hand; the payloads cannot.
-runs/*/pipe*.json
-runs/*/integrations*.json
-
-# Uncomment to keep the structure out of git entirely.
-# pipes/
-# databases/
-# runs/
-`;
-
-export const writeDocs = async (
-  root: string,
-  lock: Lock,
-  trees: Tree[],
-  caps: Capabilities | null,
-  ref: Reference | null = null,
-) => {
-  const p = paths(root);
-  await writeFile(p.agentsMd, AGENTS_MD(lock, trees));
-  await writeFile(p.mappingMd, MAPPING_MD(trees, lock));
-  await writeFile(p.capabilitiesMd, CAPABILITIES_MD(caps));
-  await writeFile(p.referenceMd, renderReferenceMd(ref));
-  await writeFile(p.gitignore, GITIGNORE);
-
-  /**
-   * Migration cleanup: a workspace pulled before this rename has a stale
-   * `CLAUDE.md` sitting beside the new `AGENTS.md`, still telling whoever
-   * reads it to look here — remove it rather than leave a duplicate that
-   * silently goes out of date the next time this file is regenerated.
-   */
-  const staleClaudeMd = join(root, 'CLAUDE.md');
-  if (await exists(staleClaudeMd)) await rm(staleClaudeMd, { force: true });
-
-  return [p.agentsMd, p.mappingMd, p.capabilitiesMd, p.referenceMd, p.gitignore];
-};
+import { join } from 'node:path';
+import { rm } from 'node:fs/promises';
+import { writeFile, exists } from "../util/fsx.js";
+import { registryRows } from "../apply/registry.js";
+import { paths } from "./layout.js";
+import { renderReferenceMd } from "../pipefy/reference.js";
+/**
+ * The generated docs that are the whole interface for whoever edits this
+ * workspace — PLAN.md §6. No agent baked into the app: the FDE pulls, edits
+ * with an agent in a terminal, and publishes. These files are what make that
+ * work unattended, regardless of which agent is reading them.
+ */
+const AGENTS_MD = (lock, trees) => {
+    const reconstructed = lock.repos.filter((r) => r.source === 'reconstructed');
+    const unknownGroups = new Set();
+    for (const r of lock.repos) {
+        for (const [name, cov] of Object.entries(r.coverage))
+            if (cov === 'unknown')
+                unknownGroups.add(name);
+    }
+    return `# Editing this Pipefy workspace
+
+This directory is a Pipefy pipe (and everything it connects to) pulled to disk as
+JSON. Edit the JSON, then let \`pipe\` validate, plan and apply it. The rules below
+are not style preferences — breaking one either corrupts a live pipe or makes the
+apply refuse.
+
+## The loop
+
+\`\`\`bash
+pipe validate          # JSON shape + referential integrity. Instant, offline.
+pipe diff              # what you changed, against the last pull
+pipe plan --dry-run    # is every change actually applicable? refuses if not
+pipe apply             # snapshot, apply, verify
+\`\`\`
+
+**\`pipe validate && pipe plan --dry-run\` must both be clean before you propose an
+apply.** Iterate against them yourself; they need no network for validate and no
+writes for plan.
+
+## Identity rules
+
+- \`id\` is **server-owned**. Never invent one, never edit one, never reuse one.
+- A **new** entity is \`"id": null\` plus \`"_new": true\`. For \`phases\`, \`fields\`,
+  \`automations\` and \`labels\` — the only four arrays that have one — also add a
+  fresh v4 \`uuid\`. Everything else is identified by its owner.
+- To **delete**, remove the object (or the whole file). Do not set a tombstone.
+- \`_\`-prefixed keys are tool metadata. Leave them alone; they are ignored by
+  every comparator and never sent to the API.
+
+## What cannot be changed at all
+
+| Edit | Why it is refused |
+| --- | --- |
+| a field's \`type_id\` | \`updatePhaseField\` has no \`type_id\`. Doing it as delete+create destroys every existing value. |
+| a field's \`phase_id\` | \`updatePhaseField\` has no \`phase_id\`. Same data loss. |
+| a phase's \`index\` (reordering) | \`createPhase\` takes an index, \`updatePhase\` does not. |
+| anything under \`_readonly/\` | no public write path exists. Read it, reason with it, don't edit it. |
+| anything under \`_non-snapshot/\` | not part of the structure payload; never written back. |
+| the start-form phase's existence, \`index\`, or \`name\` | it is a real phase at index 0; deleting or reindexing it is catastrophic, and its name is referenced by other things (the public form, automations, a client's own docs) this tool cannot check for breakage. |
+
+If a request needs one of these, say so plainly and stop — do not work around it
+with a delete and a create.
+
+## Field references
+
+Automations and conditions refer to fields by numeric id inside opaque JSON:
+\`"recipients": "%{<fieldId>}"\`, \`"field_address": "433255493"\`,
+\`"trigger_field_ids": ["433255544"]\`. \`MAPPING.md\` translates every one of those
+numbers into a label and a phase.
+
+- **Deleting a field obliges you to fix every reference to it.** \`pipe validate\`
+  fails on a dangling reference, by design.
+- Referencing a field you are creating in the same edit is fine: leave the
+  placeholder \`%{_new:<uuid>}\` and the applier substitutes the real id after the
+  field exists.
+
+## Flows reference fields too, and \`pipe validate\` does not check them
+
+If this workspace has any \`flows/\` directories, they are iPaaS flows (Advanced
+Automations) — the same entities as the pipe, pulled, diffed, planned and
+applied by the same \`pipe pull/diff/plan/apply\` commands (\`--no-flows\` opts
+out). A flow's datapills address a field by **slug**, inside opaque strings:
+\`{{step_1['output'].data.card.fields.<slug>.value}}\`.
+
+- **\`pipe validate\` never looks inside a flow.** Renaming, retyping or deleting
+  a field is checked against automations and conditions, never against flow
+  datapills — a broken reference there is silent until the flow runs. Before
+  editing a field a flow might use, grep \`flows/\` for its slug yourself.
+- A field's slug does **not** change when its label is renamed (measured;
+  \`VALIDATION.md\` §3g), so a label-only rename is safe for existing datapills.
+  Anything that changes or removes the slug is not.
+- **Adding a node to an existing flow works if the node is reachable from the
+  trigger** — some other node's \`_nextAction\`, \`_firstLoopAction\` or a
+  branch's \`_children\` must point at it, which is how the diff finds the
+  parent to send \`ADD_ACTION\` after. An orphan node nothing points to is
+  still refused, by name, rather than guessed at.
+- Enabling a flow arms it against live traffic and is refused unless you pass
+  \`--allow-flow-enable\`, the same shape as \`--allow-card-moves\`.
+- Load the \`ppc-pipefy-flow-authoring\` skill before writing or debugging a flow by
+  hand — it covers node shapes, datapill syntax and the traps that validate
+  clean and resolve nothing at runtime.
+
+## Values that come from a closed set
+
+\`REFERENCE.md\` in this workspace lists what the API accepts in every position
+where a value must come from a fixed list: each automation event's
+\`event_params\`, each action's \`action_params\`, which events and actions cannot be
+paired, and the field \`type_id\`, \`color\` and \`filter\` sets. It was read from the
+API on the last pull.
+
+**Read it before writing an automation.** The schema publishes these lists and
+then types the inputs that consume them as \`ID\` and \`String\`, so a wrong value is
+not caught by GraphQL. It reaches a runtime check and comes back as \`is invalid\`
+or \`All fields must be filled properly.\` — naming no parameter, no event, and no
+accepted value, partway through an apply.
+
+The traps are near-misses, not nonsense. \`in_phase_id\` is a real parameter that
+belongs to \`card_inbox_received_email\`; \`card_moved\` takes only \`to_phase_id\`.
+\`card_id\` is real on \`update_card_field\` and refused on \`move_single_card\`.
+
+\`pipe validate\` checks all of this offline and names the parameter, so a wrong
+value costs a second rather than a half-applied change. It is a backstop, not a
+substitute for reading the file.
+
+## Where things live
+
+\`\`\`
+pipes/<id>--<name>/
+  pipe.json                    the repo row
+  phases/NN--name.json         phase + its fields[] + jump_target_ids[] + team_member_ids[]
+  automations/<name>.json      automation + condition + field_maps + response_schemas
+  field-conditions/<name>.json condition + actions
+  labels.json  webhooks.json  public-form.json  preferences.json  relations.json
+  _readonly/   _non-snapshot/  _meta.json
+databases/<id>--<apiId>--<name>/
+  table.json                   the database row
+  phases/00--start-form.json   the database's COLUMNS live here, as fields[]
+  phases/NN--*.json            record statuses — readable, no write path
+  README.md                    what each of those files actually is
+\`\`\`
+
+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, so renumbering works without renaming anything.
+
+${reconstructed.length
+        ? `## This workspace was read without snapshots
+
+${reconstructed.length} of ${lock.repos.length} repo(s) were reconstructed from the
+GraphQL and internal APIs rather than from a snapshot payload. Consequences you
+must respect:
+
+${[...unknownGroups].sort().map((g) => `- \`${g}\` is **unknown**, not empty. Do not add to it and do not conclude the pipe has none.`).join('\n')}
+
+An \`unknown\` entity group is never diffed and never applied. \`_meta.json\` in each
+repo directory records exactly what was and was not read.
+`
+        : `## This workspace was read from snapshots
+
+Every entity group came from the snapshot payload, so absence means absence.
+`}
+## Secrets
+
+Webhook URLs are bearer-equivalent — possession is authorization — and
+HTTP-request automations can carry live credentials in \`action_params\`. This
+workspace has a \`.gitignore\`, but do not paste these files into anything, and do
+not commit the workspace.
+
+## Runs
+
+Pass \`--report\` to any of pull, apply, dry run or verify and it writes a folder
+under \`runs/\` recording what happened:
+
+\`\`\`
+runs/index.md                         one line per run, oldest first
+runs/<when>--<kind>/report.md         what happened, readable, no credentials
+runs/<when>--<kind>/run.json          the same thing structured
+runs/<when>--<kind>/pipe.json         the payload as of the end of that run
+runs/<when>--<kind>/integrations.json webhooks, relations, cross-repo automations
+\`\`\`
+
+An apply also writes \`pipe.before.json\`, so both sides of the change sit in one
+folder. Read \`report.md\` first — it is the only file in there written for a
+human.
+
+It is off by default: a run folder holds a full copy of the pipe, credentials
+included, and one per command would grow without bound. The record an apply
+needs in order to resume is the plan file under \`.ppc/plans/\`, which is always
+written.
+
+${trees.length ? `## This workspace\n\n${trees.map((t) => `- ${t.repo['name']} (${t.meta.repoKind} ${t.repo['id']}) — ${t.phases.length} phases, ${t.phases.reduce((n, p) => n + p.fields.length, 0)} fields, ${t.automations.length} automations, read from ${t.meta.source}`).join('\n')}` : ''}
+`;
+};
+const MAPPING_MD = (trees, lock) => {
+    const sections = trees.map((t) => {
+        const fields = t.phases.flatMap((p) => p.fields.map((f) => ({ f, phase: String(p['name'] ?? '') })));
+        const fieldRows = fields
+            .map(({ f, phase }) => `| \`${f['id']}\` | ${f['label']} | \`${f['slug'] ?? ''}\` | ${f['type_id']} | ${phase} |`)
+            .join('\n');
+        const phaseRows = t.phases
+            .map((p) => `| ${p['index']} | \`${p['id']}\` | ${p['name']}${Number(p['index']) === 0 ? ' **(start form)**' : ''} | ${p.fields.length} | ${p.jump_target_ids.length ? p.jump_target_ids.map((j) => `\`${j}\``).join(', ') : '—'} |`)
+            .join('\n');
+        const autoRows = t.automations
+            .map((a) => `| \`${a['id']}\` | ${a['name']} | ${a['event_id']} → ${a['action_id']} | ${a['action_repo_id'] !== a['event_repo_id'] ? `cross-repo → \`${a['action_repo_id']}\`` : 'same repo'} | ${a.condition ? 'yes' : '—'} |`)
+            .join('\n');
+        const connectors = fields
+            .filter(({ f }) => f['type_id'] === 'connector')
+            .map(({ f, phase }) => `| \`${f['id']}\` | ${f['label']} | ${phase} | \`${f['connected_pipe_id']}\` |`)
+            .join('\n');
+        return `## ${t.repo['name']} — ${t.meta.repoKind} \`${t.repo['id']}\`
+
+### Phases
+
+| index | id | name | fields | jumps to |
+| --- | --- | --- | --- | --- |
+${phaseRows}
+
+### Fields
+
+| id | label | slug | type | phase |
+| --- | --- | --- | --- | --- |
+${fieldRows}
+
+### Automations
+
+| id | name | event → action | scope | condition |
+| --- | --- | --- | --- | --- |
+${autoRows || '| — | none | | | |'}
+
+${connectors ? `### Connector fields\n\n| field id | label | phase | connected repo |\n| --- | --- | --- | --- |\n${connectors}\n` : ''}`;
+    });
+    /**
+     * Edges name what they point at, not just its id.
+     *
+     * `301908697` on its own tells a reader nothing — and a connector field aimed
+     * at a database means something different from one aimed at a pipe: the target
+     * has columns and records rather than phases and cards. The repo is looked up
+     * in the lock, so a target outside the workspace still shows as unknown rather
+     * than being guessed at.
+     */
+    const byId = new Map(lock.repos.map((r) => [String(r.id), r]));
+    const edgeRows = lock.edges
+        .map((e) => {
+        const to = byId.get(String(e.to));
+        const target = to ? `${to.kind} · ${to.name}` : 'not in this workspace';
+        return `| \`${e.from}\` | \`${e.to}\` | ${target} | ${e.kind} | ${e.label ?? ''} |`;
+    })
+        .join('\n');
+    return `# Mapping
+
+Generated on pull. This is what makes \`%{<fieldId>}\` mean "Requester email".
+
+${sections.join('\n\n')}
+
+## Connections
+
+Discovered as the union of \`pipe_relations\`, connector fields, and cross-repo
+automations — connector fields alone find edges that neither \`pipe_relations\` nor
+\`pipeMapGraph\` reports (PLAN.md §2.2).
+
+| from | to | what it is | via | label |
+| --- | --- | --- | --- | --- |
+${edgeRows || '| — | — | — | — | — |'}
+`;
+};
+const CAPABILITIES_MD = (caps) => {
+    const rows = registryRows()
+        .sort((a, b) => a.key.localeCompare(b.key))
+        .map((r) => `| \`${r.entity}\` | ${r.op} | ${r.status === 'SUPPORTED' ? 'yes' : r.status === 'PARTIAL' ? 'partly' : '**no**'} | ${r.via ? `\`${r.via}\`` : '—'} | ${r.reason ?? ''}${r.ask ? ` _(ask ${r.ask})_` : ''} |`)
+        .join('\n');
+    const detected = caps
+        ? `## Detected on this endpoint
+
+| Capability | Present | Consequence if absent |
+| --- | --- | --- |
+| snapshots (\`createRepoSnapshot\`) | ${caps.snapshots ? 'yes' : '**no**'} | pulls reconstruct the structure over GraphQL instead |
+| \`restoreRepoSnapshot\` | ${caps.restoreRepoSnapshot ? 'yes' : '**no**'} | no atomic rollback; a failed apply is repaired forward |
+| \`createRepoDraft\` | ${caps.createRepoDraft ? 'yes' : '**no**'} | no free rehearsal environment; plans are checked, not proven |
+| \`importRepoSnapshot\` | ${caps.importRepoSnapshot ? 'yes' : 'no'} | Route B is unavailable; writes go through the mutation compiler |
+| internal API | ${caps.internalApi} | automation detail and phase-jump editing depend on it |
+
+${caps.internalApi === 'unavailable' ? '> The internal endpoint did not answer. Automations and phase jumps are reported as **unknown** rather than empty, and any change to them is refused rather than silently skipped.\n' : ''}${caps.internalApi === 'incompatible' ? '> The internal endpoint refused one of this tool\'s own queries as invalid — a bug in `pipe`, not an outage. Automations are reported as **unknown** or **partial** rather than empty, and any change to them is refused. `pipe doctor` names the query.\n' : ''}`
+        : '';
+    return `# Capabilities
+
+Generated from the live registry in \`src/apply/registry.ts\`, so what you read
+here is what the applier will actually attempt. If something says **no**, propose
+a different change rather than a workaround.
+
+${detected}
+## Write coverage
+
+| Entity | Operation | Writable | Via | Notes |
+| --- | --- | --- | --- | --- |
+${rows}
+
+## Flows (iPaaS), separately from the table above
+
+Flows compile through \`src/apply/flowops.ts\`, not the registry above — they are
+still applied by the same \`pipe apply\` (skip with \`--no-flows\`), just tracked
+here rather than in the write-coverage table.
+
+| Change | Writable | Via | Notes |
+| --- | --- | --- | --- |
+| create a flow | yes | \`createFlow\` (whole tree) | built trigger-first, then each node in execution order |
+| delete a flow | yes | \`deleteFlow\` | destructive |
+| rename a flow | yes | \`CHANGE_NAME\` | |
+| update the trigger | yes | \`UPDATE_TRIGGER\` | whole node, not a sparse patch |
+| update an action | yes | \`UPDATE_ACTION\` | whole node; a router's branches live in \`settings.branches\`, so editing them is an \`UPDATE_ACTION\` on the router — there is no \`UPDATE_BRANCH\` |
+| delete an action | yes | \`DELETE_ACTION\` | destructive |
+| add a node **to an existing flow** | yes, if reachable from the trigger | \`ADD_ACTION\` | the parent is found by scanning the authored tree for whoever's \`_nextAction\` / \`_firstLoopAction\` / \`_children\` points at the new node. An orphan node nothing points to is refused by name |
+| enable a flow | partly | \`CHANGE_STATUS\` | arms it against live traffic — refused unless \`--allow-flow-enable\`, and refused outright while any connection it uses is still a placeholder |
+| disable a flow | yes | \`CHANGE_STATUS\` | |
+| a connection the flow needs but the project lacks | yes, as a placeholder | \`createConnection\` | created disabled with a placeholder credential so the structure can still be built; reconnect it for real before enabling |
+| whole-tree replace | **refused on purpose** | — | \`IMPORT_FLOW\` exists and is never used — it re-runs an old schema migration on an already-live tree and doubles every datapill (\`{{step_1['output'].x}}\` → \`{{step_1['output']['output'].x}}\`), resolving nothing at runtime while every validator still calls it valid |
+
+After any flow write, the applier reads the flow back and diffs its datapills
+against what was sent — the only check that catches the \`IMPORT_FLOW\`-shaped
+migration bug, and the reason a flow apply is not reported successful on the
+mutation's response alone.
+
+## The three that hurt most
+
+1. **Field type changes** — routine to ask for, impossible to do without
+   destroying data. Refused.
+2. **Moving a field between phases** — same.
+3. **Reordering phases** — \`createPhase\` takes an index, \`updatePhase\` does not.
+
+These are asks 2, 3 and 4 in \`ROUTE-B-V2.md\`. Every refusal pipe emits is a data
+point for them.
+`;
+};
+const GITIGNORE = `# A pulled workspace contains webhook URLs (bearer-equivalent: possession is
+# authorization) and HTTP-request automation credentials. Never commit it.
+.ppc/
+*.gz
+
+# Run folders hold a full copy of the pipe (runs/*/pipe.json) and its integration
+# surface, credentials included. The report beside them is redacted and can be
+# shared by hand; the payloads cannot.
+runs/*/pipe*.json
+runs/*/integrations*.json
+
+# Uncomment to keep the structure out of git entirely.
+# pipes/
+# databases/
+# runs/
+`;
+export const writeDocs = async (root, lock, trees, caps, ref = null) => {
+    const p = paths(root);
+    await writeFile(p.agentsMd, AGENTS_MD(lock, trees));
+    await writeFile(p.mappingMd, MAPPING_MD(trees, lock));
+    await writeFile(p.capabilitiesMd, CAPABILITIES_MD(caps));
+    await writeFile(p.referenceMd, renderReferenceMd(ref));
+    await writeFile(p.gitignore, GITIGNORE);
+    /**
+     * Migration cleanup: a workspace pulled before this rename has a stale
+     * `CLAUDE.md` sitting beside the new `AGENTS.md`, still telling whoever
+     * reads it to look here — remove it rather than leave a duplicate that
+     * silently goes out of date the next time this file is regenerated.
+     */
+    const staleClaudeMd = join(root, 'CLAUDE.md');
+    if (await exists(staleClaudeMd))
+        await rm(staleClaudeMd, { force: true });
+    return [p.agentsMd, p.mappingMd, p.capabilitiesMd, p.referenceMd, p.gitignore];
+};