@agentled/cli 0.7.5 → 0.7.7

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"
+    }
+  ]
+}

package/scaffolds/orchestrator-kg-loop.json

@@ -0,0 +1,96 @@
+{
+  "name": "Orchestrator: Loop call-workflow over KG",
+  "goal": "Read rows from a KG list, call a child workflow per row to score/process each, persist the results back to KG, then summarize.",
+  "description": "Pattern 11 (orchestrator) wired to a child built from the `child-with-return` scaffold. The KG list is the source of truth; the child encapsulates the per-row logic. Uses `entryConditions.type: \"loop_completion\"` with `onCriteriaFail: \"wait\"` so downstream steps block until every child finishes.",
+  "status": "draft",
+  "context": {
+    "executionInputConfig": {
+      "title": "Orchestrate Scoring",
+      "description": "Score every `new` row in the KG list by calling a child workflow per row.",
+      "runCTALabel": "Run",
+      "allowRegeneration": false,
+      "fields": [
+        { "name": "source_list_key", "label": "Source KG list key", "type": "text", "required": true },
+        { "name": "child_workflow_id", "label": "Child workflow id (the scoring workflow)", "type": "text", "required": true }
+      ]
+    }
+  },
+  "steps": [
+    {
+      "id": "start",
+      "type": "trigger",
+      "name": "Manual Start",
+      "pipelineStepStartConditions": { "trigger": { "type": "manual" } },
+      "next": { "stepId": "read-candidates" }
+    },
+    {
+      "id": "read-candidates",
+      "type": "appAction",
+      "name": "Read Candidates from KG",
+      "app": { "id": "kg", "actionId": "kg.read-list", "source": "native" },
+      "stepInputData": {
+        "listKey": "{{input.source_list_key}}",
+        "status": "new",
+        "limit": "50"
+      },
+      "next": { "stepId": "call-child" }
+    },
+    {
+      "id": "call-child",
+      "type": "appAction",
+      "name": "Score Row (child workflow)",
+      "loopConfig": {
+        "source": "executionContent",
+        "config": { "stepId": "read-candidates", "field": "listEntries" },
+        "ItemAlias": "row"
+      },
+      "app": { "id": "agentled", "actionId": "agentled.call-workflow", "source": "native" },
+      "stepInputData": {
+        "workflowId": "{{input.child_workflow_id}}",
+        "executionInputData": "{\"entity_id\": \"{{row.id}}\", \"entity_url\": \"{{row.url}}\"}",
+        "timeoutMinutes": "30"
+      },
+      "next": { "stepId": "persist-scores" }
+    },
+    {
+      "id": "persist-scores",
+      "type": "appAction",
+      "name": "Write Scores Back to KG",
+      "app": { "id": "kg", "actionId": "kg.update-rows", "source": "native" },
+      "entryConditions": {
+        "onCriteriaFail": "wait",
+        "conditionText": "Wait for every child call to complete before flipping status.",
+        "criteria": [
+          { "type": "loop_completion", "stepId": "call-child", "operator": "==", "value": true }
+        ]
+      },
+      "stepInputData": {
+        "listKey": "{{input.source_list_key}}",
+        "rowIds": "{{steps.call-child.rowIds}}",
+        "fieldUpdates": "{{steps.call-child.returnData}}",
+        "status": "scored"
+      },
+      "next": { "stepId": "summarize" }
+    },
+    {
+      "id": "summarize",
+      "type": "aiAction",
+      "name": "Summarize Run",
+      "pipelineStepPrompt": {
+        "template": "Summarize this orchestration run.\n\nRows processed: {{steps.read-candidates.count}}\nResults: {{steps.call-child.returnData}}\n\nReport totals, top-3 by score, and anything that looked anomalous.",
+        "responseStructure": {
+          "totals": "object — counts by decision bucket",
+          "top": "array — top 3 rows",
+          "notes": "string"
+        }
+      },
+      "creditCost": 5,
+      "next": { "stepId": "done" }
+    },
+    {
+      "id": "done",
+      "type": "milestone",
+      "name": "Orchestration Done"
+    }
+  ]
+}

package/scaffolds/source-from-platform.json

@@ -0,0 +1,78 @@
+{
+  "_scaffold": "source-from-platform",
+  "_description": "Source entities from a native app, normalize them, and upsert to KG with status:new. Pair with a downstream scoring workflow that reads status:new.",
+  "name": "Source from Platform",
+  "goal": "Source entities from a platform and write them to a Knowledge Graph list for downstream processing.",
+  "status": "draft",
+  "context": {
+    "executionInputConfig": {
+      "title": "Run Sourcing",
+      "description": "Source entities and add them to the Knowledge Graph.",
+      "runCTALabel": "Source",
+      "fields": [
+        { "name": "search_query", "label": "Search query", "type": "text", "required": true },
+        { "name": "target_list_key", "label": "Target list key", "type": "text", "required": true, "defaultValue": "leads", "description": "Knowledge list key (e.g. \"leads\", \"startups\")." }
+      ]
+    }
+  },
+  "steps": [
+    {
+      "id": "start",
+      "type": "trigger",
+      "name": "Scheduled sourcing",
+      "pipelineStepStartConditions": {
+        "trigger": {
+          "type": "schedule",
+          "description": "Run weekly.",
+          "config": { "frequency": "weekly", "dayOfWeek": "monday", "time": "08:00" }
+        }
+      },
+      "next": { "stepId": "source-entities" }
+    },
+    {
+      "id": "source-entities",
+      "type": "appAction",
+      "name": "Source entities",
+      "_comment": "Replace the app with the source action. Run: agentled apps for-source <platform>",
+      "app": { "id": "REPLACE_WITH_APP_ID", "actionId": "REPLACE_WITH_APP_ID.REPLACE_WITH_ACTION_ID", "source": "native" },
+      "stepInputData": {
+        "query": "{{input.search_query}}",
+        "limit": "25"
+      },
+      "creditCost": 2,
+      "next": { "stepId": "normalize-entities" }
+    },
+    {
+      "id": "normalize-entities",
+      "type": "aiAction",
+      "name": "Normalize entities",
+      "pipelineStepPrompt": {
+        "template": "Extract real entities from the source output.\n\nSource output:\n{{steps.source-entities}}\n\nRules:\n- Keep only identifiable entities.\n- Use a stable userKey, preferably domain, profile URL, email, or canonical source URL.\n- Set rowData.status to \"new\".\n- Include source, source_url, sourced_at, and enough evidence for a downstream scoring workflow.\n- Do not score, find contacts, or draft outreach here.\n\nReturn JSON only.",
+        "responseStructure": {
+          "rows": "array of { userKey: string, rowData: object }",
+          "count": "number"
+        }
+      },
+      "creditCost": 5,
+      "next": { "stepId": "save-entities" }
+    },
+    {
+      "id": "save-entities",
+      "type": "appAction",
+      "name": "Save entities",
+      "app": { "id": "kg", "actionId": "kg.upsert-rows", "source": "native" },
+      "stepInputData": {
+        "listKey": "{{input.target_list_key}}",
+        "rows": "{{steps.normalize-entities.rows}}",
+        "mergeStrategy": "merge",
+        "status": "new"
+      },
+      "next": { "stepId": "done" }
+    },
+    {
+      "id": "done",
+      "type": "milestone",
+      "name": "Sourcing complete"
+    }
+  ]
+}

package/scaffolds/source-to-kg.json

@@ -0,0 +1,88 @@
+{
+  "name": "Source -> KG (idempotent sourcing)",
+  "goal": "Find entities and write them to a KG list with a stable userKey so re-running never produces duplicates.",
+  "description": "Pattern 15a (sourcing half of the Source -> Process split). Pair this scaffold with `kg-process-update` as the consumer. Uses `kg.upsert-rows` with `userKey` for O(1) dedup across runs and `status: \"new\"` so the processing workflow can filter cleanly.",
+  "status": "draft",
+  "context": {
+    "executionInputConfig": {
+      "title": "Source Entities",
+      "description": "Find entities and add them to the shared KG list.",
+      "runCTALabel": "Source",
+      "allowRegeneration": false,
+      "fields": [
+        { "name": "search_query", "label": "Search query / topic", "type": "text", "required": true },
+        { "name": "target_list_key", "label": "Target KG list key", "type": "text", "required": true }
+      ]
+    }
+  },
+  "steps": [
+    {
+      "id": "schedule",
+      "type": "trigger",
+      "name": "Weekly source",
+      "pipelineStepStartConditions": {
+        "trigger": {
+          "type": "schedule",
+          "description": "Run weekly on Monday morning.",
+          "config": { "frequency": "weekly", "dayOfWeek": "monday", "time": "08:00" }
+        }
+      },
+      "next": { "stepId": "generate-queries" }
+    },
+    {
+      "id": "generate-queries",
+      "type": "aiAction",
+      "name": "Generate Optimized Queries",
+      "pipelineStepPrompt": {
+        "template": "Generate 3 optimized search queries to find new entities matching: {{input.search_query}}\n\nUse boolean operators and filters appropriate to the target platform. Return a flat list of strings.",
+        "responseStructure": {
+          "queries": "array of strings"
+        }
+      },
+      "creditCost": 3,
+      "next": { "stepId": "search" }
+    },
+    {
+      "id": "search",
+      "type": "appAction",
+      "name": "Search (replace with target platform)",
+      "app": { "id": "REPLACE_WITH_APP_ID", "actionId": "REPLACE_WITH_APP_ID.REPLACE_WITH_ACTION_ID", "source": "native" },
+      "stepInputData": {
+        "queries": "{{steps.generate-queries.queries}}"
+      },
+      "creditCost": 2,
+      "next": { "stepId": "extract" }
+    },
+    {
+      "id": "extract",
+      "type": "aiAction",
+      "name": "Extract Entities",
+      "pipelineStepPrompt": {
+        "template": "Extract structured entity records from this raw source output.\n\nSource: {{steps.search.output}}\n\nEvery row MUST include a stable identifier (canonical URL, domain, or platform id) — this becomes the userKey for KG dedup. Drop rows you cannot uniquely identify.",
+        "responseStructure": {
+          "items": "array of { userKey: string (stable id e.g. canonical URL), rowData: { name, url, description, ...other fields } }"
+        }
+      },
+      "creditCost": 5,
+      "next": { "stepId": "save-to-kg" }
+    },
+    {
+      "id": "save-to-kg",
+      "type": "appAction",
+      "name": "Upsert to KG (status: new)",
+      "app": { "id": "kg", "actionId": "kg.upsert-rows", "source": "native" },
+      "stepInputData": {
+        "listKey": "{{input.target_list_key}}",
+        "rows": "{{steps.extract.items}}",
+        "mergeStrategy": "merge",
+        "status": "new"
+      },
+      "next": { "stepId": "done" }
+    },
+    {
+      "id": "done",
+      "type": "milestone",
+      "name": "Sourcing Done"
+    }
+  ]
+}

package/skills/agentled/SKILL.md

@@ -42,6 +42,28 @@ After orientation, ask **at most three to five** targeted questions. Focus only
 - Every possible future integration question before the first useful slice is designed.
 - Anything answerable by running `agentled workspace inspect`.
 
+## Outreach scale and segmentation
+
+For outbound, sales, investor, founder, or lead-generation workflows, classify the motion before designing the workflow. See `docs/OUTREACH_SCALE_GUIDANCE.md`.
+
+**Core diagnostic:**
+- PCPL = prospects contacted / positive replies over the last 30 days. PCPL at or below 250 is a scalable winner; above 250 means diagnose deliverability, then copy, then offer-audience match.
+- Daily volume = last 30 days sent / 22 working days.
+- TAM = total reachable prospects in the CRM, KG list, enrichment tool, or target account universe.
+- Reply ops = whether positive replies are handled quickly and followed up persistently.
+
+**Tier guidance:**
+- Tier 1 (~100/day, a few thousand prospects): enrich every account, route by strongest signal, use high-touch multi-channel outreach. This is the default for most small Agentled Ops / AngelHive-style motions.
+- Tier 2 (~1,000/day, 50K-100K prospects): split into top 200-500 home-run accounts with Tier 1 treatment plus segmented automation for the long tail.
+- Tier 3 (~10K/day, hundreds of thousands): test angle x offer x segment, generate script variations, keep tests running in parallel, and track PCPL per combination.
+- Tier 4 (50K-100K/day, millions): require provider segmentation, live monitoring, sender reserve capacity, hourly testing cadence, and reply-handling SLAs before increasing volume.
+
+**Workflow implications:**
+- Small TAM problems are usually segmentation and signal-enrichment problems, not copy-only problems.
+- Store `outreachAngle`, `offer`, `segment`, `campaignVariant`, `channelUsed`, `sender`, `contactedAt`, `replyStatus`, `meetingStatus`, and `positiveReplyAt` when the KG schema allows it.
+- Configure business metrics for prospects contacted, positive replies, PCPL, meetings/bookings/paid confirmations, bounce/failed-send count, and segment/angle performance. These are `analyticsConfig` business metrics, not ROI assumptions.
+- Literal PCPL should use `type: "ratio"` with `ratioMode: "raw"`. Use the default percentage ratio behavior for rates such as `positive_replies / prospects_contacted`.
+
 ## Valid step types (closed list)
 
 Every pipeline step **must** set `type` to one of these values. Any other value is silently normalised/rejected and the step won't execute. For full input/output schemas call `get_step_schema`.
@@ -111,6 +133,7 @@ agentled best-practices                             # summary + link to agentic-
 | **Outreach** — personalized email with user approval | `08-composed-email-approval` (outreachProfile + `pipelineStepPrompt.type: "email"` + `schedule-email`) | `list-match-email` |
 | **Report / dashboard** — structured output + sharing + KPI history | `09-reports-and-knowledge-storage` (Config renderer + share step + `knowledgeSync`) | `lead-scoring-kg`, `extract-threshold-alert` |
 | **Multi-workflow system** — workflows sharing KG state and status transitions | `12-event-driven-workflow-groups` (group manifest, state machines, build order) | — |
+| **Entity pipeline group** — sourcing → score/qualify → find contact → outreach → scheduled orchestrator | `13-entity-pipeline-lifecycle` | `source-from-platform`, `lead-scoring-kg`, `list-match-email`, `funnel-orchestrator` |
 
 Full patterns are maintained publicly at https://github.com/agentled/agentic-ops — the CLI ships a mirrored copy, see `agentled examples`. Scaffolds are preflight-clean pipeline JSON skeletons; start from one instead of writing from scratch.
 
@@ -420,7 +443,7 @@ agentled_<slug>/
 - Decisions ("we chose theme X for next edition", "we picked OpenVC + Crunchbase as initial sources") need a paper trail with reasoning. KG entries should carry the *outcome*, not the deliberation.
 - Workflow drafts often go through 3-5 iterations before push — keep them local until ready.
 
-**Sync rule:** at the end of any meaningful working session — and explicitly when the user says "save", "wrap up", "we're done for now" — summarize what's *durable and reusable* (final decisions, current themes, active sources, workflow purpose statements) and write it to the workspace KG via `upsert_knowledge_text` (for narrative docs) or `upsert_knowledge_rows` (for structured data). Use stable, predictable keys: `decisions.current-theme`, `groups.<slug>.spec`, `workflows.<id>.purpose`. Append a one-line entry to `worklog.md` recording what was synced and when.
+**Sync rule:** at the end of any meaningful working session — and explicitly when the user says "save", "wrap up", "we're done for now" — summarize what's *durable and reusable* (final decisions, current themes, active sources, workflow purpose statements) and write it to the workspace KG via `upsert_knowledge_text` (for narrative docs) or `upsert_knowledge_rows` (for structured data). Use stable, predictable keys: `decisions.current-theme`, `groups.<slug>.spec`, `workflows.<id>.purpose`. For any group of workflows that forms a client-facing workspace pipeline, also create or update a client-readable KG text guide such as `<workspace-or-pipeline>.design`, `groups.<slug>.guide`, or `pipelines.<slug>.design`. Put the client explanation first (what it does, how it works, where data comes from, how approvals/sync/reporting work), then put workflow IDs, caveats, and debug details under "Operator Notes." Append a one-line entry to `worklog.md` recording what was synced and when.
 
 **Don't sync:** raw debug bundles, full execution timelines, abandoned drafts, transcripts. Those stay local. Sync only what a future session — or another agent — will actually need to pick up the work.