Feat/flow2 deterministic phone gated

.gitignore

@@ -1,2 +1,4 @@
 node_modules
 .DS_Store
+.superpowers
+.env

data/express-templates.json

@@ -0,0 +1,3 @@
+[
+  { "id": "img_1", "name": "Croma Diwali offer", "docId": "urn:aaid:sc:AP:4b4b25bb-0949-588e-bd7b-76d0e9a113bd" }
+]

data/offer-design.json

@@ -0,0 +1,22 @@
+{
+  "_comment": "Personalised customer offer used by create_design (source: 'local'). Two canned creatives — English and Hindi. Swap the image URLs for your hosted banners. Plans/featured drive the plan-picker buttons and the HQ price-floor governance in the system prompt.",
+  "images": {
+    "en": "https://s7ap1.scene7.com/is/image/varunAEM/banner-apoorva?cache=off",
+    "hi": "https://s7ap1.scene7.com/is/image/varunAEM/banner-apoorva-hindi?cache=off"
+  },
+  "plans": ["3-Yr Comprehensive", "Zero Dep + RSA", "Engine Protect combo"],
+  "featured": {
+    "plan": "3-Yr Comprehensive",
+    "price": "₹28,999/year",
+    "was": "₹52,499/year",
+    "savings": "₹23,500/year"
+  },
+  "defaults": { "customer": "Apoorva", "model": "Grand Vitara" },
+  "models": ["Grand Vitara", "Brezza", "Swift", "Baleno", "Ertiga", "Fronx", "Jimny", "Dzire", "Ciaz", "XL6"],
+  "slots": {
+    "editable": [
+      { "name": "language", "type": "text", "aliases": ["lang", "translate", "translation", "headline", "text"] }
+    ],
+    "locked": ["logo", "brand", "price", "plan", "product"]
+  }
+}

demo-auto-flow.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Drives the personalised automobile-insurance offer flow (Flow 2) against a
+# running webhook, one step at a time. Watch the server logs for `GPT chose
+# action:` and `[edit:local] resolved image`.
+#
+# Usage:  bash demo-auto-flow.sh
+#         BASE_URL=http://localhost:3000 PHONE=919899860983 bash demo-auto-flow.sh
+
+set -euo pipefail
+
+BASE_URL="${BASE_URL:-http://localhost:3000}"
+PHONE="${PHONE:-919899860983}"
+PAUSE="${PAUSE:-10}"
+GEN_PAUSE="${GEN_PAUSE:-30}"
+
+# Send a free-text WhatsApp message.
+send() {
+  echo ">>> [text] $1"
+  curl -s -X POST "$BASE_URL/" -H 'Content-Type: application/json' -d "$(cat <<JSON
+{"object":"whatsapp_business_account","entry":[{"changes":[{"value":{"messages":[
+{"from":"$PHONE","type":"text","text":{"body":"$1"}}]}}]}]}
+JSON
+)" >/dev/null
+  echo "    (200 ack — check server logs)"
+  echo
+}
+
+# Tap a reply button (WhatsApp interactive button_reply). Arg = button title.
+tap() {
+  echo ">>> [tap button] $1"
+  curl -s -X POST "$BASE_URL/" -H 'Content-Type: application/json' -d "$(cat <<JSON
+{"object":"whatsapp_business_account","entry":[{"changes":[{"value":{"messages":[
+{"from":"$PHONE","type":"interactive","interactive":{"type":"button_reply","button_reply":{"id":"qr:$1","title":"$1"}}}]}}]}]}
+JSON
+)" >/dev/null
+  echo "    (200 ack — check server logs)"
+  echo
+}
+
+echo "=== WhatsCraft personalised auto-insurance offer flow → $BASE_URL  (phone: $PHONE) ==="
+echo
+
+# 1) Salesman asks for a personalised offer → WC asks which HQ-approved plan [buttons]
+send "Apoorva test drove the Grand Vitara yesterday and asked for insurance options. Create a personalised offer for her."
+sleep "$PAUSE"
+
+# 2) Pick the plan → WC asks whether to add the salesman's contact [Yes/No]
+tap "3-Yr Comprehensive"
+sleep "$PAUSE"
+
+# 3) Yes to contact → WC asks "anything else?" [Yes / No, go ahead]
+tap "✅ Yes"
+sleep "$PAUSE"
+
+# 4) Nothing else → WC streams progress for a few seconds, then sends the English banner.
+#    Wait for that generation to finish before the next step so messages don't interleave.
+tap "➡️ No, go ahead"
+echo "... waiting ${GEN_PAUSE}s for generation to stream + finish ..."
+sleep "$GEN_PAUSE"
+
+# 5) Translate → WC streams briefly, then sends the Hindi banner
+send "make it in Hindi"
+
+echo "=== done — verify the two banners (English + Hindi) on WhatsApp and the tool choices in the logs ==="

docs/diagrams/flow-express-catalog-edit.mmd

@@ -0,0 +1,26 @@
+%% Flow A — Rajesh: edit an existing catalog design (image.source = "express")
+%% Backed by the real Adobe Express API, with interactive quick-reply buttons.
+%% Render: https://mermaid.live  or any Mermaid-capable viewer.
+flowchart TD
+  R1["User: 'what can I change?'"] --> CAE["tool: check_allowed_edits"]
+  CAE --> CAEa["actionCheckAllowedEdits<br/>image.source = express"]
+  CAEa --> EX1["expressApi.getTaggedDocument(docId)<br/>collectTaggedElements"]
+  EX1 --> BTN["buildEditOptions<br/>returns {edit_options, historyText}"]
+  BTN --> SEND1["sendEditOptions() → reply buttons<br/>id = 'edit:img_1:heading'"]
+
+  SEND1 -.->|"user taps a button"| TAP["webhook: messageTextForInteractiveReply()<br/>parse id → I'd like to change heading on image img_1"]
+  TAP --> ASK["tool: ask_for_more_information<br/>what would you like to change it to?"]
+  ASK -.->|"user replies with a value"| EG
+
+  R2["User: 'change the offer to 7500'"] --> EG["tool: edit_graphic"]
+  EG --> RT{"actionEditGraphic<br/>image.source?"}
+  RT -->|"express"| EXE["editExpressDesign"]
+  EXE --> V{"field is a tagged element?<br/>discount ≤ MAX_DISCOUNT?"}
+  V -->|"ok"| GEN["expressApi.generateVariation<br/>→ pollJobStatus → thumbnailUrl"]
+  GEN --> REC["recordEdits + sendImage(thumbnail)"]
+  V -->|"no"| REJ["reply: can't edit that field / discount capped"]
+
+  R3["User: 'change the product to a TV'"] --> STV["tool: select_tv_model"]
+  STV --> STVa["actionSelectTvModel → 3 model buttons<br/>id encodes full edits (buildValueEditId)"]
+  STVa -.->|"user taps e.g. LG UA82 AI"| TAP2["parse id → edits JSON → sentence → GPT"]
+  TAP2 --> EG

docs/diagrams/flow-local-create-design.mmd

@@ -0,0 +1,24 @@
+%% Flow B — Anjali: create + edit a brand-new design (image.source = "local")
+%% No Express calls — resolves to canned image URLs in data/onam-design.json.
+%% Render: https://mermaid.live  or any Mermaid-capable viewer.
+flowchart TD
+  A1["User: 'create a new design for Onam,<br/>LG washing machine + dishwasher, 20% off'"] --> CD["tool: create_design"]
+  CD --> CDa["actionCreateDesign<br/>loadOnamDesign + imageStore.createDesign<br/>(source = local, id = local_1)"]
+  CDa --> S1["sendImage(images.base)"]
+
+  A2["User: 'add my store address Princess Street Kochi'"] --> EG2["tool: edit_graphic"]
+  A3["User: 'translate the banner to Malayalam'"] --> EG3["tool: edit_graphic"]
+  EG2 --> RT{"actionEditGraphic<br/>image.source?"}
+  EG3 --> RT
+  RT -->|"local"| EL["editLocalDesign"]
+
+  EL --> M{"Malayalam request?<br/>(Malayalam script OR the word<br/>'Malayalam' in ANY key/value)"}
+  M -->|"yes"| MAL["short-circuit:<br/>appliedEdits = {language: 'Malayalam'}<br/>skip locked/palette guards"]
+  M -->|"no"| CANON["canonicalizeEdits (aliases)"]
+  CANON --> GUARD{"unknown key? → 'locked by HQ'<br/>background off-palette? → reject"}
+  GUARD -->|"ok"| RES["resolveLocalImage:<br/>address/background set → images.final<br/>else → images.base"]
+  MAL --> RESM["resolveLocalImage → images.malayalam"]
+  RES --> S2["recordEdits + sendImage(url)"]
+  RESM --> S2
+
+  RT -->|"express"| EXE["editExpressDesign<br/>(Adobe Express API — see other diagram)"]