@agentled/cli 0.7.6 → 0.7.7

package/dist/utils/workspace-meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-meta.js","sourceRoot":"","sources":["../../src/utils/workspace-meta.ts"],"names":[],"mappings":"AAQA,SAAS,QAAQ,CAAC,KAAc;IAC5B,OAAO,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,WAAW,CAAC,GAAG,MAAiB;IACrC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,SAAS;QACxC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;IAChC,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC7C,MAAM,IAAI,GAAG,KAAK;SACb,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACnB,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE7B,OAAO,IAAI,IAAI,WAAW,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAMpC;IACG,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,MAAM,iBAAiB,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3E,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,MAAM,IAAI,GAAG,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC;IAEvC,MAAM,WAAW,GAAG,WAAW,CAAC,iBAAiB,CAAC,EAAE,EAAE,iBAAiB,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IAChH,IAAI,CAAC,WAAW,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,gGAAgG,CAAC,CAAC;IACtH,CAAC;IAED,MAAM,IAAI,GAAG,WAAW,CACpB,iBAAiB,CAAC,IAAI,EACtB,IAAI,CAAC,IAAI,EACT,OAAO,CAAC,IAAI,EACZ,IAAI,CAAC,IAAI,EACT,WAAW,CACb,CAAC;IACH,MAAM,UAAU,GAAG,WAAW,CAC1B,KAAK,CAAC,YAAY,EAClB,iBAAiB,CAAC,IAAI,EACtB,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,KAAK,EACV,IAAI,EACJ,WAAW,CACb,CAAC;IAEH,OAAO;QACH,WAAW;QACX,IAAI,EAAE,mBAAmB,CAAC,UAAU,CAAC;QACrC,IAAI;QACJ,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACvD,CAAC;AACN,CAAC"}
+{"version":3,"file":"workspace-meta.js","sourceRoot":"","sources":["../../src/utils/workspace-meta.ts"],"names":[],"mappings":"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"}

package/llms-full.txt

@@ -93,6 +93,8 @@ agentled workflows publish <id> --status paused
 agentled workflows start <id> --input '{"company_url":"https://linkedin.com/company/acme"}'
 agentled workflows start <id> --input-file input.json
 
+`workflows start` always returns `executionInputId` (the submitted input/run record). It may also return `executionId` if the async execution row is already available. Use only `executionId` with `executions get`. If `executionId` is absent, run `agentled executions list <workflow-id> --limit 5` and find the row whose `pipelineExecutionInputId` matches the `executionInputId`; that row's `id` is the execution ID.
+
 # Export / Import (cross-environment transfer)
 agentled workflows export <id> --output workflow-export.json
 agentled workflows import --file workflow-export.json
@@ -396,7 +398,7 @@ agentled workflows publish <id> --status live
 agentled workflows start <id> --input '{"url":"https://linkedin.com/company/acme"}'
 
 # Check results
-agentled executions list <id> --limit 1
+agentled executions list <id> --limit 5   # match pipelineExecutionInputId if start returned only executionInputId
 agentled executions get <id> <exec-id>
 ```
 
@@ -495,7 +497,7 @@ agentled workflows start <workflow-id> --input '{"company_url": "$ARGUMENTS"}'
 
 Check results with:
 \`\`\`bash
-agentled executions list <workflow-id> --limit 1
+agentled executions list <workflow-id> --limit 5  # match pipelineExecutionInputId from workflows start
 agentled executions get <workflow-id> <exec-id>
 \`\`\`
 ```

package/llms.txt

@@ -29,3 +29,20 @@ to switch targets.
 ## Docs
 
 - [Full Reference](llms-full.txt): Complete single-file reference for LLM consumption — all CLI commands, workflow schema, app actions, and examples
+- [Design Principles](patterns/v1/00-design-principles.md): The four-pillar authoring contract — idempotency, small scope, KG-list-as-connector, design-as-data — read this **before authoring any workflow**.
+
+## Scaffolds (zero-iteration starters)
+
+Every scaffold is preflight-clean. List them with `agentled workflows scaffold --list`; copy one with `agentled workflows scaffold <slug> --out my.json`.
+
+Idempotent sourcing + processing (Pattern 15 — the user's default for "find leads then process on a schedule"):
+
+- `source-to-kg` — schedule → generate queries → extract → `kg.upsert-rows` with `userKey` + `status:new`. Re-runs dedup via userKey.
+- `kg-process-update` — schedule → `kg.read-list(status:new)` → loop → `kg.update-rows(status:processed)`. Pair with `source-to-kg`.
+
+Composition:
+
+- `child-with-return` — child workflow with `internal:true` + `return` step. Called via `agentled.call-workflow`.
+- `orchestrator-kg-loop` — orchestrator that loops `call-workflow` over a KG list, waits for `loop_completion`, persists results.
+
+See `scaffolds/README.md` for the full catalog.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentled/cli",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "CLI for Agentled — manage workflows, apps, and knowledge from the command line. Zero context-window cost for AI agents.",
   "type": "module",
   "main": "dist/index.js",

package/patterns/v1/00-design-principles.md

@@ -0,0 +1,161 @@
+# 00 — Design Principles
+
+> The four-pillar contract every Agentled workflow follows. Read this **before authoring any step.**
+
+The other docs in this folder (`01-trigger-design`, `02-dedup-gates`, …) are tactical playbooks for specific shapes. This one is the contract underneath them: the four invariants every workflow you author has to satisfy, and the questions to answer before you write a single step.
+
+If you remember nothing else from this folder, remember the four pillars and the three questions.
+
+---
+
+## The four pillars
+
+### 1. Idempotency — re-running is safe
+
+Every workflow you author must be re-runnable on the same input without producing duplicates, double-charges, or partial state. This is a property of the *workflow*, not the platform.
+
+The two implementations:
+
+- **Polling intake** — every trigger that reads from an external source (Gmail, Slack, a feed, a webhook replay) starts with a **dedup gate**. The default for email is a Gmail label gate (`-label:processed`) plus `GMAIL_ADD_LABEL` at the end of the loop. See [02-dedup-gates](02-dedup-gates.md).
+- **KG writes** — use `kg.upsert-rows` with an explicit `userKey` (the LinkedIn URL, the domain, the order id — whatever is stable). Same `userKey` = same row across runs, O(1), no table scan. Reach for `kg.add-rows` only when duplicates are *acceptable*. See [12-event-driven-workflow-groups](12-event-driven-workflow-groups.md) §"Status is the API".
+
+> **Test:** if you ran your workflow twice with the same input, would the world look the same as if you ran it once? If no, you have a missing dedup gate.
+
+### 2. Small scope — one workflow owns one stage
+
+A workflow that "sources leads, enriches them, scores them, drafts outreach, sends email, and updates the CRM" is not a workflow — it's a system that needs five. Symptoms of an over-scoped workflow:
+
+- A failed step at minute 20 forces re-running steps 1–4 to retry step 5.
+- The execution log spans 200+ rows and you can't tell which stage failed.
+- Two upstream sources both want to feed in, but they can't share infrastructure.
+- The "outreach" step needs different scheduling than the "sourcing" step.
+
+The default decomposition rule: **one workflow per stage in the business process.** Stages are the things a human would describe with a different verb — *source*, *enrich*, *score*, *outreach*, *follow up*, *report*. Each stage gets its own workflow, its own trigger, its own retry semantics. See [05-child-workflow-contracts](05-child-workflow-contracts.md) for child workflows and [12-event-driven-workflow-groups](12-event-driven-workflow-groups.md) for multi-workflow systems.
+
+> **Test:** can a human point at your workflow and say in one sentence what it does, without saying "and" twice? If not, split it.
+
+### 3. KG list is the connector between workflows
+
+When one workflow finishes and another begins, **the handoff is a Knowledge Graph list row, not a direct call**. The producing workflow writes (`kg.upsert-rows` with `status: "new"`); the consuming workflow reads (`kg.read-list` with `filters: { status: "new" }`) and updates (`kg.update-rows` to set `status: "processed"`).
+
+Why a KG list and not `call-workflow`?
+
+| KG-list handoff | Direct call |
+|---|---|
+| Producer doesn't know which consumers exist | Producer hardcodes consumer ID |
+| Consumer can be paused, replaced, or duplicated freely | Pausing the consumer breaks the producer |
+| Backfill = widen the status filter | Backfill = re-run the producer |
+| State is durable and inspectable in the UI | State exists only in the execution log |
+| Multiple producers can write to one list | Each producer wires up its own caller chain |
+
+Use `call-workflow` (Pattern 11/12) when a child workflow is a **pure function** — same input always yields the same output, and the parent immediately consumes the return value. Use the KG list as connector for everything else.
+
+> **Test:** if you swap one of your workflows for a different implementation tomorrow, do the others keep working without code changes? If no, you have a brittle direct-call dependency.
+
+### 4. Design as data — persist decisions in KG text
+
+The workflow JSON tells you *what* the workflow does. It does not tell you *why* it does it that way. Why this trigger? Why this scoring rubric? Why a dedup label and not a userKey? Without those answers, the next agent session — or the next human — rebuilds your reasoning from scratch every time.
+
+Save the rationale **in the platform**, not in your local scratch folder. Two places, two purposes:
+
+**Working memory (local, per-group)** — `workflow-groups/<group-slug>/design.md`, `decisions/`, `worklog.md`. The agent's scratch space while building. See [12-event-driven-workflow-groups](12-event-driven-workflow-groups.md) §"Folder layout".
+
+**Durable memory (KG text, per-workspace)** — call the `upsert_knowledge_text` MCP tool when you reach a non-trivial decision. The decision survives across agent sessions, users, and CLI reinstalls. Example:
+
+```text
+upsert_knowledge_text({
+  key: "design.<group-slug>.scoring-rubric",
+  value: "Scoring rubric for the <group> funnel.\n\nDimensions: team (40), traction (30), market (30).\nThreshold: score >= 70 → outreach; 50-69 → nurture; <50 → reject.\nWhy: validated against 200 hand-scored seed-stage rows. See decisions/0003.\nLast review: 2026-04."
+})
+```
+
+Use the `design.<group-slug>.<topic>` key convention so a later agent can `recall_memory({ key: "design.<group-slug>.scoring-rubric" })` or `search_memories({ query: "scoring rubric", scope: "workspace" })` without guessing.
+
+What to upsert as `design.*` text:
+
+| Topic | Key suffix | What to capture |
+|-------|-----------|-----------------|
+| Group goal & operating principles | `.charter` | The 1-paragraph goal and the 3–5 operating principles |
+| ICP / scoring rubric | `.scoring-rubric` | Dimensions, weights, thresholds, the data the thresholds were calibrated on |
+| KG list shapes | `.kg-lists` | List keys, `userKeyField`, state machines, who reads/writes |
+| Approval gate policies | `.approvals` | Which steps gate, who approves, escalation rules |
+| Channel / outreach voice | `.outreach-voice` | Tone, forbidden phrases, brand rules |
+| Rejected alternatives | `.tradeoffs` | What you considered and didn't ship, and why |
+
+> **Test:** if a new agent picks up this group tomorrow with no chat history, can it answer "what is the rubric and why does it look like this?" by reading what's in KG text? If no, you owe a `design.*` upsert.
+
+---
+
+## The three questions before you author
+
+Answer all three out loud (or in `design.md`) before the first `add_step`. If you can't answer, you don't have enough context — orient the workspace first (`agentled workspace inspect`, `list_workflows`, `list_knowledge_lists`).
+
+1. **What is the unit of work?** One company? One lead? One inbound email? One edition? The unit determines the loop scope, the KG row, the `userKey`, and the retry granularity.
+2. **What is the completion signal?** A KG row status flip? A downstream trigger firing? A human approval? A milestone with no successor? "Completion" must be a thing the platform can observe — not an intent in the agent's head.
+3. **Is this workflow part of a group?** If the user describes more than one verb ("source *and* enrich", "enrich *and* outreach"), the answer is yes and you owe a group manifest before you write step 1. See [12-event-driven-workflow-groups](12-event-driven-workflow-groups.md).
+
+---
+
+## Decision tree: which shape do I author?
+
+```
+Is the user describing one verb, one input, one output?
+├─ YES, and it's truly one-shot → Single workflow, milestone end.
+│                                  Scaffolds: minimal, ai-with-tools, list-match-email.
+│
+├─ YES, but the same logic will be reused by other workflows → Child workflow.
+│                                  Terminal step is `return`, not `milestone`.
+│                                  Scaffold: child-with-return.
+│                                  Pattern: 05.
+│
+└─ NO, the user is describing a process with multiple stages →
+   │
+   ├─ Stages share state and run on different cadences → Two (or more) workflows
+   │  connected by a KG list. Producer upserts with status: "new"; consumer
+   │  reads by status, processes, updates status.
+   │  Scaffolds: source-to-kg + kg-process-update.
+   │  Pattern: 12, 15.
+   │
+   └─ One workflow needs to fan out the same operation per item with deterministic
+      results → Orchestrator + child via call-workflow inside a loop.
+      Scaffold: orchestrator-kg-loop.
+      Pattern: 11.
+```
+
+---
+
+## The 30-second sanity check
+
+Before you publish, walk this checklist. Each "no" is a blocker.
+
+- [ ] If this workflow is re-run on the same input, does it produce the same state? (Pillar 1)
+- [ ] Can I describe what this workflow does in one short sentence without "and"? (Pillar 2)
+- [ ] If the next workflow in the chain is paused or replaced, does this one still do its job? (Pillar 3)
+- [ ] Are the design rationale, ICP/rubric, and list shapes saved as `design.<group>.*` in KG text? (Pillar 4)
+- [ ] Did I answer the three questions before writing step 1?
+- [ ] Did I pick the shape from the decision tree, not invent a new one?
+- [ ] Does the workflow pass `agentled workflows validate <wfId>` with zero errors and zero warnings?
+- [ ] Did I run the [Dry-Run Protocol](../../../CLAUDE.md) (`validate_workflow` → `test_*_action` per key step → check `{{steps.X.field}}` refs against captured payloads) before any `start_workflow`?
+
+If all eight pass, ship it. If not, fix before publish — the platform won't catch a missing rationale or a misnamed list key for you.
+
+---
+
+## Where to go next
+
+| If you're doing… | Read |
+|---|---|
+| Choosing a trigger | [01-trigger-design](01-trigger-design.md) |
+| Building a polling intake | [02-dedup-gates](02-dedup-gates.md) |
+| Iterating without burning credits | [03-credit-efficiency](03-credit-efficiency.md) |
+| Looping over a KG list | [04-loop-patterns](04-loop-patterns.md) |
+| Building a child workflow | [05-child-workflow-contracts](05-child-workflow-contracts.md) |
+| Conditional routing | [06-conditional-routing](06-conditional-routing.md) |
+| Handling errors / skips / waits | [07-error-handling](07-error-handling.md) |
+| Sending email with approval | [08-composed-email-approval](08-composed-email-approval.md) |
+| Rendering reports + KG storage | [09-reports-and-knowledge-storage](09-reports-and-knowledge-storage.md) |
+| Researching a person | [10-person-research-ladder](10-person-research-ladder.md) |
+| Researching a company | [11-company-research-ladder](11-company-research-ladder.md) |
+| Designing a multi-workflow group | [12-event-driven-workflow-groups](12-event-driven-workflow-groups.md) |
+
+And before you start: `agentled workflows scaffold --list` to see every starter shape, then `agentled workflows scaffold <slug> --out my-pipeline.json` to bootstrap.

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