docs(flows): name what the flow nodes do, not what they were once meant to do

.changeset/flow-node-labels.md

@@ -0,0 +1,46 @@
+---
+'hotcrm': patch
+---
+
+Make the flow **node** labels say what those nodes do. #851 corrected the
+Automation page's flow table and the `opportunity_won_alert` description; the
+same three claims survived one layer further in — on the nodes themselves, which
+ship as authored metadata in `dist/objectstack.json`, and in a file-header
+comment that had started contradicting the description right above it.
+
+- **`Notify Management` → `Notify Owner`** (`src/flows/opportunity-won-alert.flow.ts`).
+  The node addresses `{record.owner_id}` and nothing else. The comment directly
+  above it already explained why there is no manager recipient —
+  `{record.owner_id.manager}` cannot traverse a lookup on the raw trigger
+  snapshot, so it interpolates to the literal `undefined` and the message goes to
+  a phantom user — so the label was contradicted by its own header.
+- **`Assign to Senior Agent` → `Flag as Escalated`** (`src/flows/case-escalation.flow.ts`).
+  The `update_record` node writes `is_escalated`, `escalation_reason`,
+  `escalated_date` and `status`. It never touches `owner_id`; the comment inside
+  it opens with *"No owner reassignment"*. The case stays with the agent who had
+  it, exactly as the escalation notice already tells the recipient: *"It remains
+  assigned to you."*
+- **`Notify Support Team` → `Notify Case Owner`** (`src/flows/case-escalation.flow.ts`).
+  Same file, same class of claim: `recipients` is the single entry
+  `{caseRecord.owner_id}`, not a team. The identical node in
+  `src/flows/case-sla-monitor.flow.ts` — same `notify_team` id, same owner-only
+  recipient — already carries the honest label `Alert Owner`; this one had been
+  left behind.
+
+The file-header comment on `src/flows/opportunity-won-alert.flow.ts` still
+described the flow as *"notify the owner and their manager"*, the sentence #851
+removed from the `description` eleven lines below it. It now uses that same
+correction, so the two no longer disagree.
+
+Node **ids** are deliberately untouched — `notify_management`,
+`assign_senior_agent` and `notify_team` keep their original spellings because
+`edges[]` reference nodes by id and `CaseEscalationOnCreateFlow` rewrites the
+node list by id. Renaming one would be a behaviour change wearing a wording
+fix's clothes, so each node now carries a short note saying so, to keep the next
+reader from "tidying" an id that looks stale next to its corrected label.
+
+Labels and comments only. No flow behaviour changed: no recipient, condition,
+field set, edge or id differs, and this takes no position on whether escalation
+*should* reassign or *should* copy a manager — those remain open product
+questions whose answers would be behaviour changes with their own docs.
+Fixes #869.

src/flows/case-escalation.flow.ts

@@ -84,7 +84,13 @@ export const CaseEscalationFlow: Flow = {
       config: { objectName: 'crm_case', filter: { id: '{record.id}' }, outputVariable: 'caseRecord' },
     },
     {
-      id: 'assign_senior_agent', type: 'update_record', label: 'Assign to Senior Agent',
+      // The `label` names what this node actually does: it flags the case as
+      // escalated (see `fields` below) and reassigns nothing. The `id` keeps
+      // its original `assign_senior_agent` spelling on purpose — `edges[]`
+      // reference nodes by id, and `CaseEscalationOnCreateFlow` rewrites the
+      // node list by id, so renaming one is a behaviour change, not a wording
+      // fix.
+      id: 'assign_senior_agent', type: 'update_record', label: 'Flag as Escalated',
       config: {
         objectName: 'crm_case', filter: { id: '{record.id}' },
         // `escalation_reason` must be set whenever `is_escalated` flips true — the
@@ -108,7 +114,11 @@ export const CaseEscalationFlow: Flow = {
       // shape is a no-op stub in 7.4 and never delivered anything.
       // Owner only: `{caseRecord.owner_id.manager}` cannot traverse a lookup in
       // flow templates — it interpolates to the literal "undefined".
-      id: 'notify_team', type: 'notify', label: 'Notify Support Team',
+      // The `label` names the single recipient this node has (`recipients`
+      // below); the `id` keeps its `notify_team` spelling because `edges[]`
+      // reference it. Cf. the same node in `case-sla-monitor.flow.ts`, whose
+      // label already says `Alert Owner`.
+      id: 'notify_team', type: 'notify', label: 'Notify Case Owner',
       config: {
         // Owner only. Flow templates cannot traverse a lookup (see the note on
         // `assign_senior_agent` above): `{caseRecord.owner_id.manager}` and

src/flows/opportunity-won-alert.flow.ts

@@ -9,7 +9,8 @@ type Flow = Automation.Flow;
  *
  * Migrated from the removed `notify_on_large_deal_won` object workflow (7.7
  * dropped `workflows[]`). When a deal > $100K is marked closed_won, notify the
- * owner and their manager.
+ * owner — the owner alone, not their manager (see the notify node for why the
+ * manager cannot be reached).
  *
  * NB: `record.amount > 100000` is authored as bare CEL against the (string-
  * serialized) currency field — this relies on the 7.7 numeric-hydration fix
@@ -68,7 +69,11 @@ export const OpportunityWonAlertFlow: Flow = {
       },
     },
     {
-      id: 'notify_management', type: 'notify', label: 'Notify Management',
+      // The `label` names what this node actually does: it notifies the owner
+      // and nobody else. The `id` keeps its original `notify_management`
+      // spelling on purpose — `edges[]` reference nodes by id, so renaming one
+      // is a behaviour change, not a wording fix.
+      id: 'notify_management', type: 'notify', label: 'Notify Owner',
       config: {
         // Owner only: `{record.owner_id.manager}` cannot traverse a lookup on the
         // raw trigger snapshot — it interpolates to the literal "undefined"