@agentled/cli 0.7.6 → 0.7.8

package/patterns/v1/13-entity-pipeline-lifecycle.md

@@ -0,0 +1,319 @@
+# Pattern 13 — Entity Pipeline Lifecycle
+
+Build lead, account, candidate, deal, or operator-target systems as a small group of workflows connected by one KG list and explicit status transitions.
+
+## When to use
+
+Use this pattern when the user describes a recurring business funnel:
+
+- source targets from one or more channels
+- save them to a list
+- qualify or score them
+- find the right contact
+- draft or send outreach with approval
+- run the whole process daily or weekly
+
+Do not build this as one large workflow unless the user needs a one-off run. The reusable shape is a workflow group.
+
+## Canonical shape
+
+```
+Source Channel A       -> kg.upsert-rows(status: "new")
+Source Channel B       -> kg.upsert-rows(status: "new")
+Score / Qualify        -> read status "new"              -> status "qualified" | "needs_review" | "disqualified"
+Find Contact           -> read status "qualified"        -> status "contact_found" | "contact_missing"
+Draft Outreach         -> read status "contact_found"    -> status "ready_to_contact"
+Send / Queue Outreach  -> read status "ready_to_contact" -> status "contacted"
+Daily / Weekly Orchestrator -> runs the stages in order, computes KPIs, writes a digest
+```
+
+The status names are examples. Use domain language that matches the list, then document it.
+
+## Build order
+
+1. Create the KG list first.
+2. Build one sourcing workflow that writes rows with `status: "new"` and stable `userKey`.
+3. Build one scoring workflow that reads `status: "new"` and writes a decisive next status.
+4. Build contact discovery only after scoring produces enough qualified rows.
+5. Build outreach as a separate workflow with approval. Never send directly from sourcing or scoring.
+6. Build the scheduled orchestrator last. It should coordinate already-working workflows, not hide broken stages.
+
+## Recommended CLI scaffolds
+
+```bash
+# Source rows from a native app into a KG list.
+agentled workflows scaffold source-from-platform --out 01-source.json
+
+# Score / qualify rows against an ICP and store the result.
+agentled workflows scaffold lead-scoring-kg --out 02-score-qualify.json
+
+# Draft/send approval-gated outreach from matched list rows.
+agentled workflows scaffold list-match-email --out 04-outreach.json
+
+# Coordinate the recurring funnel once child workflows are working.
+agentled workflows scaffold funnel-orchestrator --out 99-orchestrator.json
+```
+
+## KG list contract
+
+Every entity list used by this pattern needs:
+
+| Field | Purpose |
+|---|---|
+| `userKey` | Stable dedupe key. Prefer domain, email, LinkedIn URL, or canonical source URL. |
+| `status` | Indexed workflow phase. Every stage reads one status and writes the next. |
+| `source` / `source_channel` | Where the row came from. Useful for quality and cost analysis. |
+| `sourced_at` | When the row first entered the funnel. |
+| score fields | `fitScore`, `fitReasoning`, `qualificationReason`, or domain-specific equivalents. |
+| contact fields | `buyerRole`, `contactName`, `contactEmail`, `contactLinkedin`, `contactConfidence`. |
+| outreach fields | `outreachAngle`, `firstCallHook`, `notes`, `lastContactedAt`, `nextActionAt`. |
+| delivery fields | `messageId`, `threadId`, `channelUsed`, `sentAt`, `deliveryStatus`, `bouncedAt`, `bounceReason`. |
+| engagement fields | `openedAt`, `openCount`, `clickedAt`, `clickCount`, `lastClickedUrl`, `repliedAt`, `replySentiment`. |
+
+Use `mergeStrategy: "merge"` whenever a source workflow upserts rows. Re-sourcing the same entity must not wipe scoring or outreach fields.
+
+## Status rules
+
+1. Each workflow reads exactly one input status.
+2. Each workflow writes a forward status, never back to an earlier phase.
+3. Write status before customer-visible side effects when possible. This prevents duplicate sends on retries.
+4. Use a review status for uncertain rows instead of forcing them into qualified or disqualified.
+5. Keep disqualified rows. They are calibration data for future sourcing and scoring.
+
+## Sourcing workflow
+
+Purpose: create raw rows only.
+
+```
+trigger -> source/search app -> normalize -> kg.upsert-rows(status: "new") -> done
+```
+
+Rules:
+
+- Do not score in the source workflow.
+- Do not find contacts in the source workflow unless the source returns them cheaply.
+- Do not draft outreach in the source workflow.
+- Do write `source_channel`, `source_url`, and enough evidence for the scorer to judge quality.
+
+## Score / qualify workflow
+
+Purpose: be strict and reduce noise.
+
+```
+trigger -> kg.read-list(status: "new") -> read ICP/rubric -> score rows -> kg.upsert-rows(status buckets) -> done
+```
+
+Use three buckets:
+
+- `qualified`: ready for contact discovery or outreach drafting
+- `needs_review`: plausible, but a human should inspect before outreach
+- `disqualified`: do not contact
+
+If the list schema does not allow `needs_review`, use the workspace's closest status such as `enriched` or `review`.
+
+## Contact discovery workflow
+
+Purpose: find one realistic buyer path for qualified rows.
+
+```
+trigger -> kg.read-list(status: "qualified") -> find person/email/LinkedIn -> verify -> kg.upsert-rows(status: "contact_found" or "contact_missing")
+```
+
+Rules:
+
+- Use the best available source for the channel: LinkedIn/profile enrichment for the person path, email-finder/verification actions for email, and company-domain fallback only when no person-level contact is available.
+- Store both person and channel fields when found: `contactName`, `buyerRole`, `contactLinkedin`, `contactEmail`, `contactSource`, `contactConfidence`.
+- Prefer a likely role over invented person details.
+- Keep confidence fields.
+- Put missing-contact rows in their own status so they can be retried later with a different provider.
+
+## Outreach workflow
+
+Purpose: prepare or send customer-visible messages with approval.
+
+```
+trigger -> kg.read-list(status: "contact_found") -> draft message -> approval -> schedule-email -> kg.upsert-rows(status: "contacted")
+```
+
+For email, use the composed email pattern:
+
+- `pipelineStepPrompt.type: "email"`
+- `renderer: { type: "Email", config: { fromContextKey: "outreachProfile" } }`
+- `onApproval.action: "schedule-email"`
+- `next.conditions.approvalRequired: true`
+
+If the user only wants drafts, write the draft into `notes` and move rows to `ready_to_contact`. Do not send.
+
+Mark a row `contacted` only after the send/queue action succeeds, not when the draft is generated. Store the send result fields (`messageId`, `threadId`, `channelUsed`, `sentAt`, `lastContactedAt`) at the same time so future follow-up workflows can dedupe and thread replies.
+
+### Approval step examples
+
+**Email send with approval**
+
+Use the first-class composed email shape. This is the only supported pattern for approval-gated email sending; do not model this as `draft-email -> gmail.send-email`.
+
+```json
+{
+  "id": "send-outreach-email",
+  "type": "aiAction",
+  "name": "Send Outreach Email",
+  "pipelineStepPrompt": {
+    "type": "email",
+    "template": "Draft a concise outreach email for this target.\\n\\nTarget row:\\n{{steps.read-target.rows.0}}\\n\\nUse the outreach angle and first-call hook already stored on the row. Return email-safe HTML only.",
+    "responseStructure": {
+      "email": {
+        "from": "{{context.outreachProfile.fromEmail}}",
+        "to": "{{steps.read-target.rows.0.contactEmail}}",
+        "subject": "",
+        "body": "",
+        "bodyType": "html"
+      }
+    },
+    "responseType": "json"
+  },
+  "renderer": {
+    "type": "Email",
+    "config": { "fromContextKey": "outreachProfile" }
+  },
+  "integrations": [
+    {
+      "type": "oneOf",
+      "label": "Email",
+      "connectorType": "email",
+      "options": [
+        { "name": "Gmail", "url": "https://gmail.com", "isUserAccountConnectionRequired": true },
+        { "name": "Outlook", "url": "https://outlook.com", "isUserAccountConnectionRequired": true }
+      ],
+      "selectionHint": "preferConnected"
+    }
+  ],
+  "onApproval": {
+    "executedText": "Email sent by {{name}} at {{date}}",
+    "scheduledText": "Email scheduled for {{date}} by {{name}}",
+    "failedText": "Email failed to send.",
+    "action": "schedule-email"
+  },
+  "creditCost": 5,
+  "next": {
+    "stepId": "mark-contacted",
+    "conditions": { "approvalRequired": true }
+  }
+}
+```
+
+`mark-contacted` should run after the email step completes and upsert the row with `status: "contacted"`, `channelUsed: "email"`, `sentAt`, `lastContactedAt`, and any returned `messageId` / `threadId`.
+
+**LinkedIn connection note with approval**
+
+Use the `LinkedInMessage` renderer for the approval UI. A LinkedIn connection note is copy-only unless the workspace has a real LinkedIn outreach integration connected and verified. Do not use `schedule-linkedin-content`; that action is for publishing posts, not sending connection notes.
+
+```json
+{
+  "id": "draft-linkedin-connection-note",
+  "type": "aiAction",
+  "name": "Draft LinkedIn Connection Note",
+  "description": "Draft a LinkedIn connection note for review.",
+  "pipelineStepPrompt": {
+    "type": "analysis",
+    "template": "Draft a LinkedIn connection note for this target.\\n\\nTarget row:\\n{{steps.read-target.rows.0}}\\n\\nRules:\\n- connectionNote.body must be 300 characters or less\\n- no links\\n- plain text only\\n- mention the most concrete manual operation angle from outreachAngle or firstCallHook\\n\\nReturn JSON only.",
+    "responseStructure": {
+      "outreachMessage": {
+        "connectionNote": {
+          "mode": "connection_note",
+          "body": "≤300 chars, no links"
+        },
+        "linkedinUrl": "{{steps.read-target.rows.0.contactLinkedin}}",
+        "recipientName": "{{steps.read-target.rows.0.contactName}}"
+      },
+      "reasoning": "Why this note is relevant"
+    },
+    "responseType": "json"
+  },
+  "renderer": {
+    "type": "LinkedInMessage",
+    "config": { "responseField": "outreachMessage" }
+  },
+  "onApproval": {
+    "executedText": "LinkedIn connection note approved by {{name}} at {{date}}",
+    "scheduledText": "Waiting for approval to proceed",
+    "failedText": "Failed to proceed to next step",
+    "action": "PROCEED"
+  },
+  "creditCost": 3,
+  "next": {
+    "stepId": "queue-linkedin-note",
+    "conditions": { "approvalRequired": true }
+  }
+}
+```
+
+Then add a downstream step that either calls the verified LinkedIn/PhantomBuster connection-note action or queues the payload for manual send:
+
+```json
+{
+  "id": "queue-linkedin-note",
+  "type": "code",
+  "name": "Queue LinkedIn Connection Note",
+  "description": "Return the approved LinkedIn note payload for manual send or for a connected LinkedIn outreach action.",
+  "codeConfig": {
+    "language": "javascript",
+    "code": "const message = {{steps.draft-linkedin-connection-note.outreachMessage}};\\nif (!message?.linkedinUrl) return { queued: false, reason: 'missing_linkedin_url' };\\nif (!message?.connectionNote?.body || message.connectionNote.body.length > 300) return { queued: false, reason: 'invalid_connection_note' };\\nreturn { queued: true, channelUsed: 'linkedin_connection_note', linkedinUrl: message.linkedinUrl, note: message.connectionNote.body };"
+  },
+  "next": { "stepId": "mark-linkedin-contacted" }
+}
+```
+
+Only mark the row `contacted` after the real send/queue step succeeds. For manual LinkedIn sends, use a status such as `linkedin_note_queued` or `ready_for_manual_linkedin` until a user confirms the note was actually sent.
+
+## Engagement tracking workflow
+
+Purpose: update rows after outreach based on provider events or inbox polling.
+
+```
+email/linkedin event or polling -> match message/thread/contact -> kg.upsert-rows(status or tracking fields) -> optional follow-up workflow
+```
+
+Track these events when the channel supports them:
+
+- `delivered`: set `deliveryStatus: "delivered"` and `deliveredAt`.
+- `bounced`: set `deliveryStatus: "bounced"`, `bouncedAt`, `bounceReason`, and usually stop follow-ups.
+- `opened`: set `openedAt` on first open and increment `openCount`.
+- `clicked`: set `clickedAt`, increment `clickCount`, and store `lastClickedUrl`.
+- `replied`: set `repliedAt`, classify `replySentiment`, and move to a terminal or review status such as `replied_interested`, `replied_declined`, or `reply_needs_review`.
+
+Agentled workflow email supports open/click tracking for HTML emails when tracking is enabled: the email service injects an open pixel and rewrites links through tracking redirects, then writes `TrackingEvent` rows with `eventType: "opened"` or `eventType: "clicked"`.
+
+Important: opens and clicks are still not guaranteed signals. Some recipients block images, prefetch links, or use privacy proxies. Treat them as engagement hints, not proof that a human read the message. Delivery and bounce tracking are provider-event concerns and should be handled separately from open/click tracking.
+
+## Orchestrator workflow
+
+Purpose: run the machine on a cadence and report health.
+
+```
+schedule -> read new count -> call scoring workflow -> wait for loop completion
+         -> read qualified count -> call contact/outreach workflow
+         -> compute KPIs -> share/send digest -> done
+```
+
+Build the orchestrator after the child workflows validate and have passed at least one manual run. It should use `agentled.call-workflow` or `agentled.start-workflow` and loop over rows or stages with `loop_completion` gates.
+
+## Outreach metrics
+
+For outbound or email-heavy entity pipelines, configure business metrics in `analyticsConfig`:
+
+- `prospects_contacted`: count or extract rows moved to a contacted/sent status.
+- `positive_replies`: count or extract rows moved to `replied_positive`, `replied_interested`, `meeting_scheduled`, `paid`, or the workspace's equivalent positive outcome.
+- `pcpl`: prospects contacted per positive lead, computed as `prospects_contacted / positive_replies` with `ratioMode: "raw"`.
+- `positive_reply_rate`: optional percentage-style ratio, `positive_replies / prospects_contacted`.
+- `meetings_booked` / `paid_confirmations`: downstream conversion, if the workspace tracks it.
+- `bounce_count` / `failed_send_count`: deliverability guardrail, if available.
+
+Literal PCPL should use `type: "ratio"` with `ratioMode: "raw"`. A plain ratio metric without `ratioMode` keeps the legacy percentage behavior for rates.
+
+## What to tell the user
+
+Explain this pattern in business terms:
+
+> "We will create a simple operating funnel: one workflow finds candidates, one decides who is worth contacting, one finds the right contact, one prepares outreach for approval, and one scheduled workflow keeps the whole process moving."
+
+Avoid describing this as an AI stack, orchestration graph, or automation framework unless the user asks for implementation details.

package/scaffolds/README.md

@@ -20,16 +20,22 @@ Every bundled scaffold:
 4. Uses domain-agnostic placeholder names (`candidate`, `metric_a`,
    `entity_id`) — not specific verticals.
 
+> **Read [`patterns/v1/00-design-principles.md`](../patterns/v1/00-design-principles.md) first.** It defines the four pillars (idempotency, small scope, KG-list-as-connector, design-as-data) and the decision tree that tells you which scaffold to pick.
+
 ## Catalog
 
 | Slug | Pattern(s) | Shape |
 |------|-----------|-------|
 | `minimal` | — | trigger → milestone (smallest valid pipeline) |
+| `ai-with-tools` | — | trigger → `aiActionWithTools` (web_search + workspace_memory) → milestone |
 | `email-polling-dedup` | 02 + 13 | schedule → fetch emails (label dedup) → loop process → add label |
 | `lead-scoring-kg` | 04 + 09 | trigger → kg.read-list → AI scoring loop → knowledgeSync → report |
 | `list-match-email` | 08 | trigger → kg.read-list → AI match top candidates → composed email (approval gate) → knowledgeSync |
 | `extract-threshold-alert` | 06 + 09 | trigger → AI extract → threshold check (code) → external update → conditional Slack alert → knowledgeSync |
-| `ai-with-tools` | — | trigger → `aiActionWithTools` (web_search + workspace_memory) → milestone |
+| `source-to-kg` | 12 + 15a | schedule → generate queries → search → extract → kg.upsert-rows(`userKey`, status:`new`) — idempotent sourcing half of a two-workflow group |
+| `kg-process-update` | 12 + 15b | schedule → kg.read-list(status:`new`) → loop process → kg.update-rows(status:`processed`) — processing half of a two-workflow group |
+| `child-with-return` | 05 + 12 | manual → enrich → score → `return` (internal:true, called via call-workflow) |
+| `orchestrator-kg-loop` | 11 | manual → kg.read-list → loop call-workflow per row → wait loop_completion → kg.update-rows → summarize |
 
 ## Bring your own scaffolds
 

package/scaffolds/child-with-return.json

@@ -0,0 +1,71 @@
+{
+  "name": "Child Workflow with Return",
+  "goal": "A reusable child workflow that takes input via call-workflow and returns a structured result. Terminal step is `return`, not `milestone`.",
+  "description": "Pattern 12 (child-workflow-contracts). Mark `context.executionInputConfig.internal: true` so the UI hides the Run button — this workflow is invoked only by orchestrators via `call-workflow`. The return contract is explicit: every field a caller can read is declared in `returnConfig.fields`.",
+  "status": "draft",
+  "context": {
+    "executionInputConfig": {
+      "title": "Score Entity (called via orchestrator)",
+      "description": "This is a child workflow. Run it from an orchestrator via call-workflow, not by hand.",
+      "runCTALabel": "Score",
+      "allowRegeneration": false,
+      "internal": true,
+      "fields": [
+        { "name": "entity_id", "label": "Entity ID", "type": "text", "required": true },
+        { "name": "entity_url", "label": "Entity URL", "type": "text", "required": true }
+      ]
+    }
+  },
+  "steps": [
+    {
+      "id": "start",
+      "type": "trigger",
+      "name": "Called by Orchestrator",
+      "pipelineStepStartConditions": { "trigger": { "type": "manual" } },
+      "next": { "stepId": "enrich" }
+    },
+    {
+      "id": "enrich",
+      "type": "aiAction",
+      "name": "Enrich Entity",
+      "pipelineStepPrompt": {
+        "template": "Replace with your real enrichment logic.\n\nEntity: {{input.entity_id}}\nURL: {{input.entity_url}}\n\nReturn the enriched fields the score step will consume.",
+        "responseStructure": {
+          "enriched": "object — fields the score step needs"
+        }
+      },
+      "creditCost": 6,
+      "next": { "stepId": "score" }
+    },
+    {
+      "id": "score",
+      "type": "aiAction",
+      "name": "Score Entity",
+      "pipelineStepPrompt": {
+        "template": "Score this entity against the rubric stored in KG text (`kg.read-text` with key `design.scoring-rubric` — load upstream if you need it). Return total_score (0-100), decision (qualify|nurture|reject), and reasoning.\n\nEntity: {{input.entity_id}}\nEnriched: {{steps.enrich.enriched}}",
+        "responseStructure": {
+          "total_score": "number (0-100)",
+          "decision": "string (qualify | nurture | reject)",
+          "reasoning": "string"
+        }
+      },
+      "creditCost": 8,
+      "next": { "stepId": "return-result" }
+    },
+    {
+      "id": "return-result",
+      "type": "return",
+      "name": "Return Score to Caller",
+      "returnConfig": {
+        "source": "executionContent",
+        "fields": [
+          { "name": "entity_id", "stepId": "start", "field": "entity_id" },
+          { "name": "total_score", "stepId": "score", "field": "total_score" },
+          { "name": "decision", "stepId": "score", "field": "decision" },
+          { "name": "reasoning", "stepId": "score", "field": "reasoning" },
+          { "name": "enriched", "stepId": "enrich", "field": "enriched" }
+        ]
+      }
+    }
+  ]
+}

package/scaffolds/funnel-orchestrator.json

@@ -0,0 +1,134 @@
+{
+  "_scaffold": "funnel-orchestrator",
+  "_description": "Scheduled KG funnel coordinator: read new rows, call child scoring workflow, read qualified rows, queue outreach workflow, compute KPIs, and finish with a digest.",
+  "name": "Scheduled Funnel Orchestrator",
+  "goal": "Run a recurring funnel pass across already-working child workflows and report what moved.",
+  "description": "Use after sourcing, scoring, contact discovery, and outreach workflows have each passed manual validation.",
+  "status": "draft",
+  "context": {
+    "executionInputConfig": {
+      "title": "Run Funnel",
+      "description": "Manual override for the scheduled orchestrator.",
+      "runCTALabel": "Run funnel",
+      "fields": [
+        { "name": "source_list_key", "label": "Source list key", "type": "text", "required": true, "defaultValue": "leads", "description": "Knowledge list key (e.g. \"leads\", \"startups\")." },
+        { "name": "new_status", "label": "New status", "type": "text", "required": true, "defaultValue": "new" },
+        { "name": "qualified_status", "label": "Qualified status", "type": "text", "required": true, "defaultValue": "qualified" },
+        { "name": "score_workflow_id", "label": "Scoring workflow ID", "type": "text", "required": true, "description": "Workflow ID for the child scoring workflow." },
+        { "name": "outreach_workflow_id", "label": "Outreach workflow ID", "type": "text", "required": true, "description": "Workflow ID for the child outreach workflow." }
+      ]
+    }
+  },
+  "steps": [
+    {
+      "id": "start",
+      "type": "trigger",
+      "name": "Scheduled funnel run",
+      "pipelineStepStartConditions": {
+        "trigger": {
+          "type": "schedule",
+          "description": "Run weekly.",
+          "config": { "frequency": "weekly", "dayOfWeek": "monday", "time": "09:00" }
+        }
+      },
+      "next": { "stepId": "read-new" }
+    },
+    {
+      "id": "read-new",
+      "type": "appAction",
+      "name": "Read new rows",
+      "app": { "id": "kg", "actionId": "kg.read-list", "source": "native" },
+      "stepInputData": {
+        "listKey": "{{input.source_list_key}}",
+        "status": "{{input.new_status || 'new'}}",
+        "limit": "25"
+      },
+      "next": { "stepId": "score-rows" }
+    },
+    {
+      "id": "score-rows",
+      "type": "appAction",
+      "name": "Run scoring workflow",
+      "app": { "id": "agentled", "actionId": "agentled.call-workflow", "source": "native" },
+      "stepInputData": {
+        "workflowId": "{{input.score_workflow_id}}",
+        "executionInputData": "{\"row\": {{newRow}}, \"listKey\": \"{{input.source_list_key}}\"}",
+        "timeoutMinutes": "20"
+      },
+      "loopConfig": {
+        "source": "executionContent",
+        "config": { "stepId": "read-new", "field": "listEntries" },
+        "ItemAlias": "newRow",
+        "loopCompletion": { "criteria": "all_items_processed" }
+      },
+      "creditCost": 0,
+      "next": { "stepId": "read-qualified" }
+    },
+    {
+      "id": "read-qualified",
+      "type": "appAction",
+      "name": "Read qualified rows",
+      "app": { "id": "kg", "actionId": "kg.read-list", "source": "native" },
+      "stepInputData": {
+        "listKey": "{{input.source_list_key}}",
+        "status": "{{input.qualified_status || 'qualified'}}",
+        "limit": "25"
+      },
+      "entryConditions": {
+        "onCriteriaFail": "wait",
+        "conditionText": "Wait for scoring child workflows to complete.",
+        "criteria": [
+          { "type": "loop_completion", "stepId": "score-rows", "operator": "==", "value": true }
+        ]
+      },
+      "next": { "stepId": "queue-outreach" }
+    },
+    {
+      "id": "queue-outreach",
+      "type": "appAction",
+      "name": "Queue outreach workflow",
+      "app": { "id": "agentled", "actionId": "agentled.start-workflow", "source": "native" },
+      "stepInputData": {
+        "workflowId": "{{input.outreach_workflow_id}}",
+        "executionInputData": "{\"row\": {{qualifiedRow}}, \"listKey\": \"{{input.source_list_key}}\"}"
+      },
+      "entryConditions": {
+        "onCriteriaFail": "skip",
+        "conditionText": "Skip outreach if no qualified rows are available.",
+        "criteria": [
+          { "variable": "{{steps.read-qualified.count}}", "operator": ">", "value": 0 }
+        ]
+      },
+      "loopConfig": {
+        "source": "executionContent",
+        "config": { "stepId": "read-qualified", "field": "listEntries" },
+        "ItemAlias": "qualifiedRow",
+        "loopCompletion": { "criteria": "all_items_processed" }
+      },
+      "creditCost": 0,
+      "next": { "stepId": "summarize-run" }
+    },
+    {
+      "id": "summarize-run",
+      "type": "aiAction",
+      "name": "Summarize run",
+      "pipelineStepPrompt": {
+        "template": "Create a concise internal funnel digest.\n\nNew rows read: {{steps.read-new.count}}\nQualified rows read: {{steps.read-qualified.count}}\nScoring results: {{steps.score-rows}}\nOutreach starts: {{steps.queue-outreach}}\n\nReturn JSON only.",
+        "responseStructure": {
+          "summary": "string",
+          "newCount": "number",
+          "qualifiedCount": "number",
+          "outreachQueuedCount": "number",
+          "recommendations": ["string"]
+        }
+      },
+      "creditCost": 3,
+      "next": { "stepId": "done" }
+    },
+    {
+      "id": "done",
+      "type": "milestone",
+      "name": "Funnel run complete"
+    }
+  ]
+}

package/scaffolds/kg-process-update.json

@@ -0,0 +1,88 @@
+{
+  "name": "KG Process + Update (status state machine)",
+  "goal": "Read entities from a KG list filtered by status, process each in a loop, and flip status when done so the same row is never re-processed.",
+  "description": "Pattern 15b (processing half of the Source -> Process split) and pattern 12 (KG status as the API between workflows). Pair with `source-to-kg` as the producer. Loop processes one row at a time; after loop completion, `kg.update-rows` flips status to `processed` so the next run only sees what's still `new`.",
+  "status": "draft",
+  "context": {
+    "executionInputConfig": {
+      "title": "Process New Entities",
+      "description": "Process entities flagged as `new` in the shared KG list.",
+      "runCTALabel": "Process",
+      "allowRegeneration": false,
+      "fields": [
+        { "name": "list_key", "label": "KG list key", "type": "text", "required": true }
+      ]
+    }
+  },
+  "steps": [
+    {
+      "id": "schedule",
+      "type": "trigger",
+      "name": "Daily process",
+      "pipelineStepStartConditions": {
+        "trigger": {
+          "type": "schedule",
+          "description": "Run daily at 09:00 — picks up everything sourced overnight.",
+          "config": { "frequency": "daily", "time": "09:00" }
+        }
+      },
+      "next": { "stepId": "read-new" }
+    },
+    {
+      "id": "read-new",
+      "type": "appAction",
+      "name": "Read Rows with status: new",
+      "app": { "id": "kg", "actionId": "kg.read-list", "source": "native" },
+      "stepInputData": {
+        "listKey": "{{input.list_key}}",
+        "status": "new",
+        "limit": "100"
+      },
+      "next": { "stepId": "process" }
+    },
+    {
+      "id": "process",
+      "type": "aiAction",
+      "name": "Process Entity",
+      "loopConfig": {
+        "source": "executionContent",
+        "config": { "stepId": "read-new", "field": "listEntries" },
+        "ItemAlias": "row"
+      },
+      "pipelineStepPrompt": {
+        "template": "Process this entity. Replace this prompt with the real processing logic for your domain (enrich, score, classify, draft, etc.).\n\nEntity: {{row}}\n\nReturn the rowId verbatim plus any fields you want merged onto the KG row.",
+        "responseStructure": {
+          "rowId": "string — copy {{row.id}} verbatim so the update step can target this exact row",
+          "result": "object — fields to merge into the KG row (scores, decisions, derived data)"
+        }
+      },
+      "creditCost": 5,
+      "next": { "stepId": "mark-processed" }
+    },
+    {
+      "id": "mark-processed",
+      "type": "appAction",
+      "name": "Flip status -> processed",
+      "app": { "id": "kg", "actionId": "kg.update-rows", "source": "native" },
+      "entryConditions": {
+        "onCriteriaFail": "wait",
+        "conditionText": "Wait for the processing loop to finish before flipping status.",
+        "criteria": [
+          { "type": "loop_completion", "stepId": "process", "operator": "==", "value": true }
+        ]
+      },
+      "stepInputData": {
+        "listKey": "{{input.list_key}}",
+        "rowIds": "{{steps.process.rowIds}}",
+        "fieldUpdates": "{{steps.process.results}}",
+        "status": "processed"
+      },
+      "next": { "stepId": "done" }
+    },
+    {
+      "id": "done",
+      "type": "milestone",
+      "name": "Processing Done"
+    }
+  ]
+}