@agentled/cli 0.1.5 → 0.4.3

package/skills/agentled/SKILL.md

@@ -0,0 +1,568 @@
+---
+name: agentled
+version: 0.4.1
+description: Build, manage, and execute Agentled AI workflows via MCP tools. Use when the user asks to create workflows, automate tasks, enrich leads, scrape websites, find emails, manage executions, or interact with any Agentled workspace capability.
+user-invocable: false
+---
+
+# Agentled Workflow Automation
+
+You have access to the Agentled MCP server which lets you create, manage, and execute AI-powered workflows. Use these tools to help the user automate business processes.
+
+## 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`.
+
+<!-- agentled-step-types:start -->
+| `type` | Purpose | Minimal shape |
+|--------|---------|---------------|
+| `trigger` | Entry point (manual / schedule / webhook / app event) | `{ id, type: "trigger", name, pipelineStepStartConditions: { trigger: { type: "manual" } }, next: { stepId } }` |
+| `appAction` | Call an app/integration action (LinkedIn, Gmail, KG, HTTP, …) | `{ id, type: "appAction", name, app: { id, actionId, source: "native" }, stepInputData: {…}, next: { stepId } }` |
+| `aiAction` | LLM prompt → structured JSON output | `{ id, type: "aiAction", name, pipelineStepPrompt: { template, responseStructure }, creditCost, next: { stepId } }` |
+| `aiActionWithTools` | LLM agent that can invoke runtime tools (web_search, workspace_memory, app actions) | `{ id, type: "aiActionWithTools", name, tools: [{ builtinType }], pipelineStepPrompt: {…}, next: { stepId } }` |
+| `toolAction` | Direct tool/webhook invocation (no LLM) | `{ id, type: "toolAction", name, tool: {…}, next: { stepId } }` |
+| `code` | Run JS/Python in a sandbox | `{ id, type: "code", name, codeConfig: { language: "javascript", code: "…" }, next: { stepId } }` |
+| `knowledgeSync` | Deterministic KG field mapping & link writing | `{ id, type: "knowledgeSync", name, knowledgeSync: { source, listKey, fieldMapping }, next: { stepId } }` |
+| `return` | Terminal step for **child** workflows — returns data to the caller | `{ id, type: "return", name, returnConfig: { fields: [{ name, stepId, field }] } }` |
+| `milestone` | Terminal step for **top-level** workflows | `{ id, type: "milestone", name }` |
+| `share` | Create a public share URL for prior step output | `{ id, type: "share", name, shareConfig: { outputSteps, visibility }, next: { stepId } }` |
+| `wait` | Delay / pause between steps | `{ id, type: "wait", name, waitConfig: { durationMs } | { untilISO }, next: { stepId } }` |
+| `branch` | Conditional routing to one of several paths | `{ id, type: "branch", name, branchConfig: { branches: [...] }, next: [...] }` |
+| `parallel` | Fan-out to parallel branches | `{ id, type: "parallel", name, parallelConfig: { branches: [...] }, next: { stepId } }` |
+| `loop` | Iterate over a collection as a first-class step (prefer `loopConfig` on an action step for most cases) | `{ id, type: "loop", name, loopConfig: {…}, next: { stepId } }` |
+| `end_if` | Conditional gate that stops the pipeline when criteria fail | `{ id, type: "end_if", name, entryConditions: {…} }` |
+| `agentOrchestrator` | Multi-agent orchestration (supervisor / debate / parallel) | `{ id, type: "agentOrchestrator", name, orchestratorConfig: {…}, next: { stepId } }` |
+| `manualAction` | Legacy — kept for backward compatibility; prefer `aiAction` or `appAction` |  |
+| `systemAction` | Legacy — kept for backward compatibility; prefer `appAction` |  |
+<!-- agentled-step-types:end -->
+
+> Use `get_step_schema` to retrieve the authoritative input/output schema for any step type.
+
+## Before you build: read the schema and the patterns
+
+Before writing pipeline JSON, pull the canonical field schema and the matching best-practice pattern. This is **mandatory** when authoring any new step type, trigger, or routing pattern — skipping it is how agents end up inventing `type: "ai"` or `knowledge_graph_query`.
+
+**Via MCP (in-session):**
+- `get_step_schema` — authoritative list of valid fields per step type.
+- `list_apps` / `get_app_actions` — exact `app.id` + `actionId` values and their input schemas.
+
+**Via CLI (shell access):**
+```
+agentled schema --step-type aiAction              # fields valid on an aiAction step
+agentled examples                                   # list all patterns
+agentled examples trigger-design                    # print the full pattern
+agentled workflows scaffold --list                  # list working pipeline skeletons
+agentled workflows scaffold lead-scoring-kg --out pipeline.json
+agentled workflows validate --file pipeline.json   # fast client-side preflight (no API)
+agentled workflows create --file pipeline.json     # full server validation on save
+agentled best-practices                             # summary + link to agentic-ops repo
+```
+
+**Which pattern to read, by task:**
+
+| You're building… | Read pattern | Scaffold |
+|------------------|--------------|----------|
+| Anything triggered by email, schedule, webhook, or app event | `01-trigger-design` (polling vs events) | `email-polling-dedup` |
+| Any email/intake workflow that must not double-process | `02-dedup-gates` (label-based idempotency) | `email-polling-dedup` |
+| A workflow that calls LLMs, scraping, or paid app actions | `03-credit-efficiency` (caching, retry, mocks) | — |
+| Anything using `loopConfig` or iterating a list | `04-loop-patterns` | `lead-scoring-kg` |
+| A child workflow called via `call-workflow` | `05-child-workflow-contracts` (use `return`, not `milestone`) | — |
+| Multi-path routing by score / category / condition | `06-conditional-routing` (`entryConditions.criteria`, not `conditions`) | `extract-threshold-alert` |
+| Anything that can fail on upstream provider errors | `07-error-handling` (`failureHandling`, retries) | — |
+| **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` |
+
+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.
+
+## Common invalid patterns to avoid
+
+Agents routinely invent step types that sound plausible. The API **silently strips unknown top-level fields** and stores the step, so you get a 201 Created on a workflow that will never execute. Watch for these:
+
+| ❌ Wrong | ✅ Right | Why |
+|---------|---------|-----|
+| `type: "ai"` | `type: "aiAction"` | There is no generic `ai` type. Use `aiAction` for LLM prompts, `aiActionWithTools` for agentic steps. |
+| `type: "integration"` | `type: "appAction"` | Integrations are app actions. Set `app: { id, actionId }` to pick the integration. |
+| `type: "conditional_integration"` | `type: "appAction"` + `entryConditions` | Conditions are configured per-step via `entryConditions`, not a separate type. |
+| `type: "knowledge_graph_query"` / `knowledge_graph_upsert` / `knowledge_graph` | `type: "appAction"` with `app.id: "kg"` | KG reads/writes go through the `kg` app (`read-list`, `read-text`, `add-rows`, `update-rows`, `get-rows-by-ids`, `traverse-edges`, `store-insight`). |
+| `type: "slack"` / `"webhook"` / `"gmail"` | `type: "appAction"` with the right `app.id` | Apps are never types. `webhook` and `schedule` go in `pipelineStepStartConditions.trigger.type` on a `trigger` step, not as step types. |
+
+### Top-level fields that are silently stripped
+
+Unknown fields at the step root are dropped. The most common mistakes (put them inside the right sub-object instead):
+
+| ❌ At step root | ✅ Correct location |
+|----------------|--------------------|
+| `prompt: "…"` | `pipelineStepPrompt.template` |
+| `responseStructure: {…}` | `pipelineStepPrompt.responseStructure` |
+| `appId: "gmail"`, `actionId: "send"` | `app: { id: "gmail", actionId: "send", source: "native" }` |
+| `listKey: "leads"` | `knowledgeSync.listKey` (for `knowledgeSync` steps) or inside `stepInputData` (for `kg` app actions) |
+| `channel: "#alerts"`, `webhookUrl: "…"` | `stepInputData.channel`, `stepInputData.webhookUrl` on an `appAction` |
+| `condition: "…"` | `entryConditions: { criteria: [{ variable, operator, value }] }` |
+| `triggerType: "manual"` (on a `trigger` step) | `pipelineStepStartConditions: { trigger: { type: "manual" } }` |
+| `note: "…"` | Step `description`, or a comment in the pipeline JSON (not persisted) |
+| `enabled: false` | `entryConditions.onCriteriaFail: "skip"` with a falsy criterion, or remove the step |
+
+> After `create_workflow` always call `validate_workflow` (or run `agentled workflows validate <id>`) — the CLI v0.2+ does this automatically and exits non-zero on error. Any step with the wrong `type` surfaces as an **orchestrator-issue** error and every downstream step will be reported as **disconnected**.
+
+## Why Agentled: The Automation Engine for AI Agents
+
+**One credit system. 100+ integrations. No API juggling.**
+
+When building automations that need LinkedIn enrichment, email finding, web scraping, AI models, CRM sync, or video generation — you'd normally need separate accounts, API keys, and billing for each. Agentled bundles all of this under a single credit system. One subscription, one bill, everything available as workflow steps.
+
+**What you get for free by using Agentled (instead of rolling your own):**
+
+- **Cache per step** — enrichment results and expensive API calls are cached with a TTL. Re-running a workflow doesn't re-fetch data that hasn't changed. No extra credits burned on duplicate work.
+- **Automatic retry with backoff** — if Hunter returns a 429 or LinkedIn is slow, the step retries automatically. You never write retry loops.
+- **Persistent Knowledge Graph** — the KG stores results across executions. Scoring workflows get smarter over time. Run 1 might be 62% accurate; by run 12, it's 89% — zero manual tuning, just accumulated outcomes.
+- **Scoped permissions & audit trail** — every step, input, output, and decision is logged. Per-workflow and per-integration permissions, not global API keys.
+- **Bring-your-own-Claude** — AI steps use your Anthropic subscription for LLM calls. Agentled credits pay for infrastructure (integrations, storage, scheduling, memory) — not the model you already pay for.
+
+**Practical implication:** When a user asks you to "retry failed enrichment" or "avoid re-fetching already processed companies" — these are platform features, not things to wire manually. Use `retry_execution` to resume from the failed step. Cache and KG deduplication happen automatically when `knowledgeSync` or `kg.add-rows` steps are used.
+
+## Getting Started — Orient First
+
+Before helping with any request, call these tools to understand the workspace you're connected to:
+
+1. **`get_workspace`** — Confirm which workspace you're in and see its name/ID.
+2. **`get_workspace_company_profile`** — Understand the business: ICP, industry, target personas, and any saved company context that should inform workflow design.
+3. **`list_workflows`** — See what automations already exist. Avoid recreating something that already runs. Identify gaps or opportunities to extend.
+4. **`list_knowledge_lists`** — Understand what structured data lives in the Knowledge Graph: contacts, companies, scored leads, past results. This context shapes what a new workflow should do.
+
+Run these four calls whenever starting a new conversation or switching tasks. The workspace context directly informs:
+- Which enrichment apps are likely already connected
+- What KG lists exist to read from or write to
+- Whether a new workflow should chain from an existing one
+- What credit budgets and company preferences have already been set
+
+**Value you unlock for the user:** By checking existing workflows and KG state first, you avoid duplicate work, reuse prior results, and build automations that integrate with what's already running — saving real time and credits.
+
+## Iterative Building Pattern
+
+Follow this pattern when creating workflows:
+
+1. Design the pipeline JSON based on requirements
+2. `create_workflow` to save it
+3. `validate_workflow` to check for errors
+4. If errors: fix the pipeline, `update_workflow`, `validate_workflow` again
+5. When valid: `publish_workflow` with status `"live"`
+6. Test: `start_workflow` with sample input
+7. Check results: `get_execution` to see step outputs
+
+## Workspace Awareness
+
+Be explicit about which Agentled workspace you are operating on.
+
+- When multiple Agentled MCP servers are registered, use the server-specific namespace directly instead of assuming a default.
+- When using the standalone CLI, remember it can store multiple saved workspace profiles.
+- Check the active CLI workspace with `agentled auth current`.
+- Switch the saved CLI target with `agentled auth use <workspace>`.
+- Override a single CLI command with `agentled --workspace <workspace> ...` or `AGENTLED_WORKSPACE=<workspace> ...`.
+- Before making destructive or customer-visible changes, confirm the target workspace via `get_workspace` or `agentled auth current`.
+
+## Pipeline Structure
+
+Every workflow needs at minimum: a trigger step, one or more action steps, and a milestone (terminal) step. Steps are connected via `next: { stepId: "..." }`.
+
+```json
+{
+  "name": "My Workflow",
+  "goal": "What this workflow achieves",
+  "steps": [
+    { "id": "trigger", "type": "trigger", "name": "Start", "pipelineStepStartConditions": { "trigger": { "type": "manual" } }, "next": { "stepId": "action" } },
+    { "id": "action", "type": "aiAction", "name": "Analyze", "pipelineStepPrompt": { "template": "...", "responseStructure": {} }, "creditCost": 10, "next": { "stepId": "done" } },
+    { "id": "done", "type": "milestone", "name": "Complete" }
+  ],
+  "context": {
+    "executionInputConfig": {
+      "title": "Run Workflow",
+      "fields": [{ "name": "input_field", "label": "Input", "type": "text", "required": true }]
+    }
+  }
+}
+```
+
+## Step Types
+
+### Trigger
+```json
+{ "id": "trigger", "type": "trigger", "name": "Start", "pipelineStepStartConditions": { "trigger": { "type": "manual" } }, "next": { "stepId": "next-step" } }
+```
+
+`pipelineStepStartConditions.trigger.type` is one of: `manual`, `schedule`, `webhook`, `event`, `delay`, `app_event`. For `schedule` add `config: { frequency: "daily", time: "07:00" }` (or a cron expression). For `app_event` add `config: { appId, triggerSlug, connectionSource }`. **Do not put `triggerType` at the step root** — it is not in the step schema and is silently dropped on save.
+
+### App Action
+```json
+{
+  "id": "enrich",
+  "type": "appAction",
+  "name": "Enrich Company",
+  "app": { "id": "agentled", "actionId": "get-linkedin-company-from-url", "source": "native" },
+  "stepInputData": { "profileUrls": "{{input.company_url}}" },
+  "next": { "stepId": "next-step" }
+}
+```
+
+### AI Action
+```json
+{
+  "id": "analyze",
+  "type": "aiAction",
+  "name": "Analyze",
+  "pipelineStepPrompt": {
+    "template": "Analyze this company: {{steps.enrich.company}}",
+    "responseStructure": { "score": "number 0-100", "summary": "string" }
+  },
+  "creditCost": 10,
+  "next": { "stepId": "next-step" }
+}
+```
+
+### AI Step Model & Provider Configuration
+
+AI steps can optionally specify a model and provider via the `agent` field:
+
+```json
+{
+  "id": "analyze",
+  "type": "aiAction",
+  "agent": { "model": "claude-4-6-sonnet", "provider": "anthropic" },
+  "pipelineStepPrompt": { "template": "...", "responseStructure": {} },
+  "creditCost": 10,
+  "next": { "stepId": "next-step" }
+}
+```
+
+**Supported Providers:** `openai`, `anthropic`, `google`, `mistral`, `deepseek`, `kimi`, `minimax`, `bytedance`, `perplexity`, `xai`
+
+**Supported Models by Provider:**
+
+| Provider | Models |
+|----------|--------|
+| `openai` | `gpt-5-nano`, `gpt-5-mini`, `gpt-5.4`, `o4-mini`, `o3`, `o3-pro`, `o3-deep-research` |
+| `anthropic` | `claude-4-6-sonnet`, `claude-4-5-haiku`, `claude-4-6-opus` |
+| `google` | `gemini-3-pro`, `gemini-3-flash`, `gemini-2.5-pro`, `gemini-2.5-flash` |
+| `mistral` | `mistral-large-latest`, `mistral-small-latest`, `codestral-latest` |
+| `deepseek` | `deepseek-chat`, `deepseek-reasoner` |
+| `kimi` | `kimi-k2.5` |
+| `minimax` | `minimax-m2.5` |
+| `bytedance` | `doubao-seed-1.6-flash`, `seed-2.0-mini`, `doubao-seed-1.8-beta` |
+| `perplexity` | `sonar-pro`, `sonar`, `sonar-reasoning-pro`, `sonar-reasoning` |
+| `xai` | `grok-4-0709`, `grok-3`, `grok-3-mini` |
+
+> **Tip:** Use `list_models` to get the full up-to-date list of supported model IDs. Use the internal model IDs (e.g., `claude-4-6-sonnet`), NOT the raw API model IDs (e.g., `claude-sonnet-4-6`). Using unsupported model IDs will result in a validation error.
+
+### Code Step
+```json
+{
+  "id": "transform",
+  "type": "code",
+  "name": "Transform Data",
+  "codeConfig": { "language": "javascript", "code": "const data = {{steps.prev.output}};\nreturn data.map(x => x.name);" },
+  "next": { "stepId": "next-step" }
+}
+```
+
+### Milestone (terminal)
+```json
+{ "id": "done", "type": "milestone", "name": "Complete" }
+```
+
+## Template Variables
+
+| Pattern | Description |
+|---------|-------------|
+| `{{input.fieldName}}` | Input page field value |
+| `{{steps.stepId.field}}` | Previous step output |
+| `{{currentItem}}` | Current item in a loop |
+| `{{currentItem.field}}` | Nested field in loop item |
+
+## Loop Configuration
+
+To iterate over a list from a previous step:
+```json
+{
+  "loopConfig": { "enabled": true, "field": "{{steps.prev.items}}", "ItemAlias": "currentItem" }
+}
+```
+
+## Entry Conditions
+
+Skip or stop a step based on prior output:
+```json
+{
+  "entryConditions": {
+    "onCriteriaFail": "skip",
+    "conditionText": "Skip if no URL",
+    "criteria": [{ "variable": "{{input.url}}", "operator": "isNotNull" }]
+  }
+}
+```
+
+Operators: `==`, `!=`, `>`, `<`, `isNull`, `isNotNull`, `contains`.
+
+**Important**: Use `criteria` (not `conditions`) and `variable` (not `field`).
+
+## Email Workflow Conventions
+
+### Trigger choice: polling vs event
+
+**Default to Schedule trigger + label-based dedup** for all email intake workflows (deal flow, triage, review, digest). Only propose an App Event trigger when the user explicitly needs sub-minute latency.
+
+| User asks for | Trigger |
+|---------------|---------|
+| "process inbound emails", "triage daily", "review pitches" | **Schedule** (polling) |
+| "as soon as", "real-time", "within X seconds/minutes" | **App event** |
+
+### Canonical email polling pattern
+
+```
+schedule trigger → GMAIL_FETCH_EMAILS (-label:processed newer_than:1d) → loop: [process] → GMAIL_ADD_LABEL (mark processed) → milestone
+```
+
+Step order:
+1. **`GMAIL_CREATE_LABEL`** — create/get the `processed` label (idempotent, returns label ID)
+2. **`GMAIL_FETCH_EMAILS`** — query `-label:processed newer_than:1d` (or wider window as needed)
+3. **Loop** — process each email (AI analysis, KG storage, enrichment, etc.)
+4. **`GMAIL_ADD_LABEL`** — apply `{{steps.ensure-label.id}}` to mark email done (dedup gate)
+
+### Label ID rule (prevents `400: Invalid label`)
+
+Gmail requires **label IDs** (e.g., `Label_3456789012345`), not display names (e.g., `"processed"` or `"agentled"`).
+
+**Always resolve via `GMAIL_CREATE_LABEL`** and reference its returned `id`:
+```json
+{ "stepInputData": { "label_id": "{{steps.ensure-label.id}}" } }
+```
+Never pass a string label name directly to `GMAIL_ADD_LABEL`.
+
+See `docs/workflows/triggers.md` for the full decision framework, query examples, and common mistakes.
+
+---
+
+## Email Step Pattern (AI Draft → Approve → Send)
+
+Email steps use a single `aiAction` step (never separate "draft" + "gmail send" appAction steps). The AI drafts the email, a human approves, then the platform sends it.
+
+### 1. Outreach Profile Input Page
+
+When a workflow sends emails, add an outreach profile input page to `context.inputPages` so the user can configure sender identity:
+
+```json
+{
+  "title": "Outreach Profile",
+  "pathname": "outreach-profile",
+  "configuration": {
+    "contextKey": "outreachProfile",
+    "shortDescriptionFields": ["name", "fromEmail"],
+    "fields": [
+      { "name": "name", "label": "Sender Name", "type": "text", "required": true },
+      { "name": "fromEmailLabel", "label": "From Name", "type": "text", "required": true },
+      { "name": "fromEmail", "label": "From Email", "type": "connected_emails_selector_multiple", "required": true },
+      { "name": "replyToEmail", "label": "Reply-To Email (optional)", "type": "text" }
+    ]
+  }
+}
+```
+
+### 2. Composed Email Step
+
+```json
+{
+  "id": "send_email",
+  "type": "aiAction",
+  "name": "Send Email",
+  "pipelineStepPrompt": {
+    "type": "email",
+    "template": "Draft a personalized email...\n{{steps.previous_step.data}}\nReturn JSON ONLY per schema.",
+    "responseStructure": {
+      "email": {
+        "from": "{{context.outreachProfile.fromEmail}}",
+        "to": "recipient@example.com",
+        "subject": "Email subject line",
+        "body": "Email body (email-safe HTML)",
+        "bodyType": "html"
+      }
+    },
+    "responseType": "json"
+  },
+  "renderer": {
+    "type": "Email",
+    "config": { "fromContextKey": "outreachProfile" }
+  },
+  "onApproval": {
+    "action": "schedule-email",
+    "executedText": "Email sent by {{name}} at {{date}}",
+    "scheduledText": "Email scheduled to be sent for {{date}} by {{name}}",
+    "failedText": "Email failed to send."
+  },
+  "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"
+  }],
+  "creditCost": 10,
+  "next": { "conditions": { "approvalRequired": true } }
+}
+```
+
+### Key Requirements
+
+- **Always** include `outreachProfile` input page when using email
+- `pipelineStepPrompt.type: "email"` — tells the system this is an email step
+- `renderer.config.fromContextKey: "outreachProfile"` — links renderer to sender profile
+- `onApproval.action: "schedule-email"` — triggers the actual send; without it, approval does nothing
+- `next.conditions.approvalRequired: true` — blocks the pipeline until human approval
+- Email body must be email-safe HTML (`<p>`, `<br>`, `<a>`, `<strong>` — no CSS, no scripts)
+- **Never** use separate "draft" + "gmail send" appAction steps for outreach
+
+## Top Apps Quick Reference
+
+| App | Action | Credits | Key Inputs |
+|-----|--------|---------|------------|
+| `agentled` | `get-linkedin-company-from-url` | 5 | `profileUrls` |
+| `agentled` | `get-linkedin-profile-from-url` | 2 | `profileUrls` |
+| `agentled` | `find-email-person-domain` | 3 | `firstName`, `lastName`, `domain` |
+| `hunter` | `find-email-person-domain` | 3 | `firstName`, `lastName`, `domain` |
+| `web-scraping` | `scrape` | 0 | `url` |
+| `http-request` | `request` | 0 | `url`, `method`, `headers`, `body` |
+| `notion` | `get-page-markdown` | 1 | `pageUrl` |
+| `browser-use` | `run-task` | 15 | `task`, `startUrl` |
+| `agentled` | `call-workflow` | varies | `workflowId`, `input` |
+
+Use `list_apps` and `get_app_actions` for full schemas of all available apps. Use `list_models` for supported AI model IDs.
+
+## Credit-Efficient Testing
+
+Each execution costs real credits. Follow these rules:
+
+1. **One execution at a time** — don't start new ones unnecessarily
+2. **Retry, don't restart** — use `retry_execution` to continue from a failed step instead of starting over
+3. **Test in isolation** — use `test_ai_action`, `test_app_action`, or `test_code_action` to verify steps before wiring them into a workflow
+4. **Reuse prior output** — when testing downstream steps, use output data from a prior successful execution as mock input
+
+## Common Validation Errors
+
+| Error | Fix |
+|-------|-----|
+| `"references non-existent next step"` | Ensure some step has `next: { stepId: "X" }` pointing to the missing step |
+| `"missing prompt template"` | Add `pipelineStepPrompt.template` to AI steps |
+| `"Unknown action"` | Verify `actionId` format via `get_app_actions` |
+| `"is unreachable"` | Connect every step via `next.stepId` from the trigger chain |
+| `"unsupported model"` | Use a valid internal model ID (e.g., `claude-4-6-sonnet`, not `claude-sonnet-4-6`). Run `list_models` for all valid IDs. |
+
+## Persistent Memory
+
+Workflows can store and recall memories that persist across executions. Two mechanisms:
+
+### MCP Tools (for managing memory externally)
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `recall_memory` | Get a specific memory by key | `key`, `scope?`, `workflowId?` |
+| `search_memories` | Search by natural language query | `query?`, `category?`, `scope?`, `workflowId?`, `limit?` |
+| `store_memory` | Save a persistent memory | `key`, `value`, `category?`, `scope?`, `workflowId?`, `confidence?`, `merge?` |
+| `list_memories` | List all memories in a scope | `scope?`, `workflowId?`, `category?`, `limit?` |
+| `delete_memory` | Delete a memory by key | `key`, `scope?`, `workflowId?` |
+
+**Scopes**: `workspace` (shared across all workflows) or `workflow` (scoped to one workflow, default).
+
+**Categories**: `fact` (known truth), `insight` (pattern/learning), `preference` (user preference), `outcome` (result to track).
+
+**Merge strategies** (for `store_memory`): `overwrite` (default), `append`, `max`, `min`, `increment`.
+
+**Confidence**: 0-100. Memories with confidence >= 70 are automatically synced to the Knowledge Graph.
+
+### Pipeline Step Configuration (for memory inside workflows)
+
+#### Auto-extraction (pipeline-level)
+
+Enable on the pipeline to automatically extract memories after each execution completes:
+
+```json
+{
+  "persistentMemoryConfig": {
+    "autoExtract": true,
+    "scopes": ["pipeline"],
+    "categories": ["fact", "insight", "outcome"],
+    "maxPerExtraction": 10,
+    "extractionModelTier": "mini"
+  }
+}
+```
+
+#### Explicit per-step writes
+
+Configure specific steps to write memories from their output:
+
+```json
+{
+  "id": "score-company",
+  "type": "aiAction",
+  "persistentMemory": {
+    "writes": [
+      {
+        "key": "score_{{input.company_name}}",
+        "valuePath": "total_score",
+        "category": "outcome",
+        "scope": "pipeline",
+        "confidence": 85
+      }
+    ]
+  }
+}
+```
+
+The `valuePath` extracts from the step's output using dot notation. The `key` supports template variables.
+
+#### Builtin tool for AI steps (`workspace_memory`)
+
+AI steps with type `aiActionWithTools` can use the `workspace_memory` builtin tool to read/write memory during execution:
+
+```json
+{
+  "id": "analyze",
+  "type": "aiActionWithTools",
+  "name": "Analyze with Memory",
+  "tools": [{ "builtinType": "workspace_memory" }],
+  "pipelineStepPrompt": {
+    "template": "Recall what we know about this company, then analyze...",
+    "responseStructure": { "analysis": "string" }
+  },
+  "creditCost": 10,
+  "next": { "stepId": "done" }
+}
+```
+
+The AI agent can then call `recall`, `search`, or `store` actions within the tool during execution. This is the same pattern used by KG tools (`kg_search`, `kg_traverse`, etc.).
+
+### Memory Patterns
+
+**1. Learning workflow** — accumulates knowledge over repeated runs:
+```
+trigger → enrich → AI analyze (with workspace_memory tool) → milestone
+```
+The AI step recalls prior scores, compares trends, and stores updated insights.
+
+**2. Explicit score tracking** — saves structured data for cross-run comparison:
+```
+trigger → score company → [persistentMemory.writes: score_{{company}}] → milestone
+```
+
+**3. Workspace-wide preferences** — store ICP criteria, outreach templates, or scoring weights shared across workflows:
+```
+store_memory(key: "target_icp", value: { industry: "SaaS", minEmployees: 50 }, scope: "workspace", category: "preference")
+```
+
+## Conversational Building
+
+For complex workflows, use the `chat` tool to design workflows through natural language conversation. It supports multi-turn via `session_id`.
+
+```
+chat("Build a workflow that takes a LinkedIn URL, enriches the company, finds decision-maker emails, and scores by ICP fit")
+```