@agentled/cli 0.7.7 → 0.7.8

package/skills/agentled/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentled
-version: 0.6.0
+version: 0.7.0
 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
 ---
@@ -9,6 +9,32 @@ user-invocable: false
 
 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.
 
+This file is a **router**. It carries the always-needed core (orientation, the
+closed list of step types, the invalid-pattern guards, the build loop). The deep
+reference material lives in `references/` and the tactical playbooks in the
+pattern library — load them on demand rather than reading everything up front.
+
+## Reference index — load on demand
+
+When a task matches a row below, read that file before authoring. Don't preload
+them; that defeats the point.
+
+| When you're… | Read |
+|--------------|------|
+| Writing any step's JSON (field shapes, model IDs, loop/entry-condition syntax) | `references/step-schemas.md` (or `get_step_schema`) |
+| Editing an existing/live workflow (merge model, `update_step` / `update_workflow_context`, drafts) | `references/editing-workflows.md` |
+| Building anything that reads or sends email | `references/email-workflows.md` |
+| Sourcing/collecting entities to act on later | `references/entity-pipeline.md` |
+| Adding cross-execution memory | `references/persistent-memory.md` |
+| Designing outbound / sales / investor / lead-gen at scale | `references/outreach-and-scale.md` |
+| Producing local artifacts, or seeding a templated workspace's sidebar | `references/workspace-folder.md` |
+| Picking apps, testing credit-efficiently, decoding a validation error | `references/credits-apps-and-errors.md` |
+
+Tactical, shape-specific playbooks (triggers, dedup, loops, routing, reports,
+workflow groups, …) live in the **pattern library** — list with
+`agentled examples` and print one with `agentled examples <name>`. The
+"which pattern to read" table is below under *Before you build*.
+
 ## Goal and bottleneck first
 
 Before designing any workflow, determine what the user is actually trying to achieve and where the real bottleneck is. Agents that skip this step build the wrong system.
@@ -20,49 +46,36 @@ Before designing any workflow, determine what the user is actually trying to ach
 **The design loop:**
 1. Orient — inspect the workspace (identity, KG lists, connected apps, existing workflows, existing agents).
 2. Infer — determine the likely goal and bottleneck from workspace context.
-3. Ask — if the business direction is genuinely ambiguous, ask a few targeted questions.
+3. Ask — if the business direction is genuinely ambiguous, ask a few targeted questions (see `references/outreach-and-scale.md` for what to ask and what not to).
 4. Brief — produce a short build brief (goal, assumptions, assets to reuse, KG lists, workflow group, risks, cost hotspots, build order).
 5. Build — create workflows incrementally from the brief.
 
 > For multi-workflow systems, produce a group manifest before touching live workflow state. See `agentled group-manifest --help` and `docs/GROUP_MANIFEST.md`.
 
-## What to ask — and what not to ask
+## Orient Before Designing
 
-After orientation, ask **at most three to five** targeted questions. Focus only on what the workspace inspection cannot answer.
+Before helping with any request, inspect the workspace. Use `agentled workspace inspect` (CLI) or call these MCP tools individually:
 
-**Good questions:**
-- "What is the primary goal: source more paying leads, run each event smoothly, or report pipeline health?"
-- "Where is the bottleneck today: finding leads, getting replies, converting to paid, or operational follow-up?"
-- "What is the system of record for payments/bookings right now: Stripe webhook, a booking page, a manual form, or a KG list?"
-- "Which actions must be approval-gated: customer emails, status changes, or all customer-facing messages?"
-- "What success metric should this optimize: conversions per week, leads contacted, confirmations, fill rate, or operator time saved?"
+1. **`get_workspace`** — Confirm workspace identity (name, ID), team members, pending invitations, and knowledge-list schemas.
+2. **`get_workspace_company_profile`** — Business context: ICP, industry, target personas, saved preferences that should shape workflow design.
+3. **`list_workflows`** — Existing automations: avoid recreating, identify reuse opportunities, note gaps.
+4. **`list_knowledge_lists`** — KG lists: contacts, companies, scored leads, status machines. Shapes what a new workflow reads from or writes to.
+5. **`list_connections`** — Connected apps and integrations: know which enrichment, CRM, or email providers are already authed before designing steps that depend on them.
+6. **`list_agents`** — Existing agents and routines: understand what is already running autonomously before adding new agents.
 
-**Do not ask:**
-- Step type names, app action names, schema syntax, or implementation details — discover these from the workspace and CLI.
-- Every possible future integration question before the first useful slice is designed.
-- Anything answerable by running `agentled workspace inspect`.
+The workspace inspection directly informs which integrations are connected, what KG lists exist, whether new workflows should chain from or replace existing ones, and what existing agents already cover.
 
-## Outreach scale and segmentation
+> **Shortcut:** `agentled workspace inspect --json` returns all six contexts as one consolidated response. Use it at session start to load the full picture in a single call.
 
-For outbound, sales, investor, founder, or lead-generation workflows, classify the motion before designing the workflow. See `docs/OUTREACH_SCALE_GUIDANCE.md`.
+### MCP-connected but no local scaffold: expected behavior
 
-**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.
+If MCP tools are already connected and working, **do not block** on missing local folders.
 
-**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.
+- Continue with MCP operations immediately.
+- Add a brief, non-blocking hint once per session: `You're connected via MCP. If you want local drafts/fixtures/tests, run "agentled init" in your project directory (or "agentled setup" for full onboarding).`
+- Do **not** imply setup is required for read/write API operations through MCP.
 
-**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`.
+`agentled setup` is the full first-run path (auth, workspace folder scaffold, MCP config, skill install, knowledge probe). `agentled init` is the targeted local scaffold when they only want the local workspace folder and cache.
 
 ## Valid step types (closed list)
 
@@ -92,7 +105,7 @@ Every pipeline step **must** set `type` to one of these values. Any other value
 | `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.
+> Use `get_step_schema` to retrieve the authoritative input/output schema for any step type. Common shapes and template-variable syntax are in `references/step-schemas.md`.
 
 ## Before you build: read the schema and the patterns
 
@@ -137,21 +150,6 @@ agentled best-practices                             # summary + link to agentic-
 
 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.
 
-## Business metrics vs ROI (must not be conflated)
-
-Treat these as **two separate surfaces**:
-
-- **Business metrics (`pipeline.analyticsConfig`)** = customer/workflow outcome stats extracted from step outputs (volume, conversions, approvals, rates, SLA-ish KPIs), aggregated into dashboard business-metric snapshots.
-- **ROI (`pipeline.metadata.roi`)** = economic assumptions + rollups (minutes saved per unit, hourly rate, benchmark units/week, measured vs benchmark mode) used for ROI/time-saved reporting.
-
-### Required wording for agent outputs
-
-- If only `analyticsConfig` changes: say **"business metrics configured"**.
-- If only `metadata.roi` changes: say **"ROI assumptions configured"**.
-- If both change: report each section separately; never label analytics metrics as ROI metrics.
-
-This distinction applies to MCP and CLI users equally because both surfaces call the same external workflow API and return the same pipeline shape.
-
 ## 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:
@@ -182,45 +180,6 @@ Unknown fields at the step root are dropped. The most common mistakes (put them
 
 > 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**.
 
-## Platform capabilities (background reading)
-
-Agentled provides caching per step, automatic retry with backoff, a persistent Knowledge Graph, scoped permissions, and a unified credit system across 100+ integrations. For the full rationale, see `skills/agentled/WHY-AGENTLED.md`.
-
-**Practical implication:** "retry failed enrichment" and "avoid re-fetching already processed companies" are platform features. Use `retry_execution` to resume from a failed step; per-step caching is automatic. For cross-run row dedup, use `kg.upsert-rows` with a `userKey`.
-
-## Orient Before Designing
-
-Before helping with any request, inspect the workspace. Use `agentled workspace inspect` (CLI) or call these MCP tools individually:
-
-1. **`get_workspace`** — Confirm workspace identity (name, ID).
-2. **`get_workspace_company_profile`** — Business context: ICP, industry, target personas, saved preferences that should shape workflow design.
-3. **`list_workflows`** — Existing automations: avoid recreating, identify reuse opportunities, note gaps.
-4. **`list_knowledge_lists`** — KG lists: contacts, companies, scored leads, status machines. Shapes what a new workflow reads from or writes to.
-5. **`list_connections`** — Connected apps and integrations: know which enrichment, CRM, or email providers are already authed before designing steps that depend on them.
-6. **`list_agents`** — Existing agents and routines: understand what is already running autonomously before adding new agents.
-
-The workspace inspection directly informs:
-- Which app integrations are already connected (and which are missing auth)
-- What KG lists exist to read from or write to
-- Whether new workflows should chain from existing ones or replace them
-- What existing agents already cover, so you don't duplicate
-
-> **Shortcut:** `agentled workspace inspect --json` returns all six contexts as one consolidated response. Use it at session start to load the full picture in a single call.
-
-## MCP-connected but no local scaffold: expected behavior
-
-If MCP tools are already connected and working, **do not block** on missing local folders.
-
-- Continue with MCP operations immediately.
-- Add a brief, non-blocking hint once per session:
-  - `You're connected via MCP. If you want local drafts/fixtures/tests, run "agentled init" in your project directory (or "agentled setup" for full onboarding).`
-- Do **not** imply setup is required for read/write API operations through MCP.
-
-Use this when users ask "did anything get created locally?" or "why is there no workspace folder?"
-
-- `agentled setup` is the full first-run path (auth, workspace folder scaffold, MCP config, skill install, knowledge probe, restart prompt).
-- `agentled init` is the targeted local scaffold command when they only want the local workspace folder and cache.
-
 ## Incremental Authoring (recommended)
 
 Build workflows **one step at a time**. This catches errors per-step instead of dumping a full JSON blob and getting 10+ errors at once.
@@ -266,690 +225,37 @@ The full-pipeline `steps` array on `create_workflow` / `update_workflow` is supp
 
 Internal testing: **0 errors with incremental vs 13 errors with bulk JSON** on the same pipeline.
 
-### Editing existing workflows
-
-For live workflows, prefer per-step tools over bulk updates:
-
-- `update_step(workflowId, stepId, updates)` — change one step (prompt, inputs, next, etc.)
-- `add_step(workflowId, step, insertAfter?)` — insert a new step
-- `remove_step(workflowId, stepId)` — delete a step and re-wire neighbors
-- After edits: `validate_workflow` → `publish_workflow` (or `promote_draft` for live workflows)
-
-### Editing existing workflows: merge model
-
-`update_step` accepts three explicit operations on the same call. At least one must be non-empty.
-
-- **`updates`** — partial step patch, **deep-merged ONE LEVEL deep**. Top-level scalars are replaced; nested objects (e.g. `pipelineStepPrompt`, `stepInputData`) get their direct keys merged with the stored value's keys. Keys nested two levels deep are overwritten as a unit, not merged.
-- **`replace: string[]`** — dot-paths whose values from `updates` are assigned **wholesale**, skipping the deep-merge. Use this for **dictionary-shaped fields where keys are user data** (not config) — patching one inner key with `updates` alone silently wipes the others.
-- **`unset: string[]`** — dot-paths to delete. Each path must currently exist on the step (validated against the original — you cannot unset something you just created in the same call).
-
-**Read-before-write for dictionary fields.** Before editing `stepInputData.fieldUpdates`, `pipelineStepPrompt.responseStructure`, `knowledgeSync.fieldMapping`, or any field where keys are user data: call `get_step({ workflowId, stepId })`, modify locally, send the full new object back via `replace[]`. Cheap (~1KB) and avoids the "patched one key, silently wiped the others" trap.
-
-**Diff in the response.** Every `update_step` returns `diff: { addedPaths, changedPaths, removedPaths }` and `warnings[]`. If the merge silently removed ≥6 fields without an explicit `unset`, a warning fires. Read it.
-
-#### What to use where
-
-| Path / field | API | How to edit | Notes |
-|---|---|---|---|
-| `name`, `goal`, `description`, `pipelineStepPrompt.template`, `creditCost` | `update_step` | `updates` | Plain scalar; safe to send alone. |
-| `next`, `loopConfig`, `entryConditions` (full block) | `update_step` | `updates` | Direct nested config; sending the new value wholesale is fine — these are config, not user-data dictionaries. |
-| `tools`, `integrations` | `update_step` | `updates` | Arrays are replaced wholesale by design. To append, fetch with `get_step`, splice locally, send the full new array. |
-| `stepInputData.fieldUpdates` (kg.update-rows / kg.upsert-rows) | `update_step` | `get_step` → `updates` (full dict) + `replace: ["stepInputData.fieldUpdates"]` | Keys are user data; default one-level merge replaces this dict and can drop sibling mappings. |
-| `pipelineStepPrompt.responseStructure` | `update_step` | `get_step` → `updates` (full struct) + `replace: ["pipelineStepPrompt.responseStructure"]` | Output-shape dictionary; treat as user data. |
-| `knowledgeSync.fieldMapping` | `update_step` | `get_step` → `updates` (full mapping) + `replace: ["knowledgeSync.fieldMapping"]` | Source→target dict; same trap as `fieldUpdates`. |
-| `renderer.config` (when preserving sibling keys matters) | `update_step` | `updates` (full `renderer.config`) + `replace: ["renderer.config"]` | ⚠ `replace: ["renderer.config.layout"]` does NOT protect `renderer.config`'s siblings — the one-level deep-merge runs first on `updates.renderer`. Replace at the parent level. |
-| `entryConditions.criteria` (when preserving the rest of `entryConditions`) | `update_step` | `updates: { entryConditions: {...full block...} }` | Send the full `entryConditions` block; one-level merge already does the right thing for direct children. |
-| Removing a step input or stale field | `update_step` | `unset: ["stepInputData.oldKey"]` | Cleanest way to remove. Path must exist on the original. |
-| `context.inputPages`, `context.outputPages`, `context.executionInputConfig` | `update_workflow_context` | Three explicit verbs (`updates` / `replace` / `unset`) on workflow-relative paths, OR legacy `{ contextKey, value }` for wholesale per-key replacement | **Workflow-level, not step-level.** `update_step` cannot reach `context.*`. See workflow-level merge model below. |
-| `metadata` | `update_workflow_context` | Same three verbs on `metadata.*` paths; one-level shallow-merge under `updates.metadata` | Workflow-level. Metadata edits bypass the draft snapshot (write direct to Pipeline row even on live workflows). |
-
-**Type changes.** `step.type` is technically mutable but stale type-specific fields (`pipelineStepPrompt`, `app`, `tools`, `orchestratorConfig`) persist unless you `unset` them. For clean conversions, prefer `remove_step` + `add_step`. If editing in place, list the incompatible fields under `unset`.
-
-**Live workflows.** Edits are routed to a draft snapshot. Response includes `editingDraft: true`. Inspect via `get_draft`, ship via `promote_draft`, throw away via `discard_draft`. For high-stakes edits, `create_snapshot` first as a manual checkpoint.
-
-**Draft staleness.** When a draft already exists, every `update_step` / `get_step` response carries a `draft` summary:
-
-```jsonc
-"draft": {
-  "exists": true,
-  "draftCreatedAt": "...",
-  "liveUpdatedAt": "...",
-  "stale": true,                  // live advanced past draft.createdAt
-  "modifiedStepIds": ["step-x"],  // step IDs whose JSON differs between draft and live
-  "modifiedFields": ["steps"]     // top-level config keys that differ
-}
-```
-
-If `draft.stale === true`, the live workflow has been touched (template upgrade, UI edit, deploy) since the draft was forked. Promoting the draft will land its values for fields you didn't touch in this session — those values may be older than current live. Recovery: `discard_draft` and re-apply your edit, or call `get_draft` to inspect what's pending. The `update_step` response also pushes a staleness string into `warnings[]`.
-
-**Never** send a full `steps[]` array via `update_workflow`. Use `update_step`, `add_step`, `remove_step` instead.
-
-#### Workflow-level merge model (`update_workflow_context`)
-
-`update_workflow_context` is the workflow-level analog of `update_step` — same three verbs, but on **workflow-relative paths** (`context.executionInputConfig.fields`, `metadata.tags`, …). Step-relative paths like `pipelineStepPrompt.template` are rejected here, and conversely `update_step` rejects `context.*` / `metadata.*` paths. The boundary is hard.
+> **Editing an existing or live workflow?** The per-step merge model (`update_step` / `update_workflow_context`, the read-before-write rule for dictionary fields, drafts and staleness) is its own topic — read `references/editing-workflows.md` before touching a live workflow.
 
-Allowed path prefixes for `replace[]` / `unset[]`:
-
-- `context.inputPages`
-- `context.outputPages`
-- `context.executionInputConfig`
-- `metadata`
-
-Out-of-scope paths (e.g. `steps`, `name`) → `PATH_OUT_OF_SCOPE` (400). Other typed errors mirror `update_step`: `EMPTY_PAYLOAD`, `INVALID_PATH`, `REPLACE_VALUE_MISSING`, `UNSET_PATH_NOT_FOUND`. The response includes `diff: { addedPaths, changedPaths, removedPaths }` and `warnings[]` (≥6 silent removals fires the warning).
-
-Recipes:
-
-```jsonc
-// Flip executionInputConfig.internal — same merge-order trap as update_step.
-// Fetch (get_workflow), merge locally, replace at the parent level:
-{
-  "updates": { "context": { "executionInputConfig": {...full merged executionInputConfig with internal: true...} } },
-  "replace": ["context.executionInputConfig"]
-}
-
-// Replace inputPages wholesale:
-{
-  "updates": { "context": { "inputPages": [...new pages...] } },
-  "replace": ["context.inputPages"]
-}
-
-// Add a metadata tag (one-level shallow-merge — siblings preserved):
-{ "updates": { "metadata": { "tags": ["beta"] } } }
-
-// Delete an obsolete metadata key:
-{ "unset": ["metadata.legacyFlag"] }
-```
-
-Live workflows: context edits route to the draft snapshot. Metadata is NOT part of the snapshot config — it always writes direct to the Pipeline row, immediately and on the live workflow.
-
-⚠ **Mixed metadata + context in one call** is the sharp edge: metadata is applied immediately while context becomes pending in the draft. `discard_draft` reverts the pending context changes but **does NOT revert metadata** — metadata never went to the draft. If you need a single atomic checkpoint covering both, `create_snapshot` first or split the call into two.
-
-A legacy `{ contextKey, value }` body shape is still accepted as a **compatibility shape** for one-shot wholesale replacement of a single root context key. It can't edit metadata, doesn't return `diff` / `warnings`, and is not the recommended path for new code — prefer the three-verb shape above.
-
-### Post-authoring
-
-6. Test: `start_workflow` with sample input
-7. Check results: `get_execution` to see step outputs
-
-## Workspace Surfaces
+## Business metrics vs ROI (must not be conflated)
 
-The workspace home and sidebar carry workspace-level UI state on `Workspace.metadata`. These surfaces are read-only via the MCP today (most tooling does not need to write them), but agents authoring templated workspaces should know they exist:
+Treat these as **two separate surfaces**:
 
-### Pinned outputs (sidebar shortcuts)
+- **Business metrics (`pipeline.analyticsConfig`)** = customer/workflow outcome stats extracted from step outputs (volume, conversions, approvals, rates, SLA-ish KPIs), aggregated into dashboard business-metric snapshots.
+- **ROI (`pipeline.metadata.roi`)** = economic assumptions + rollups (minutes saved per unit, hourly rate, benchmark units/week, measured vs benchmark mode) used for ROI/time-saved reporting.
 
-`Workspace.metadata.pinnedOutputs[]` lists output pages that appear in the sidebar **after Knowledge & Data**, always visible regardless of which workflow is currently open. Operators set these manually from each output page's configuration sheet (toggle: *"Pin to workspace home"*). Pin sparingly: only pin output pages that are useful as direct workspace-level destinations, such as a recurring report, scoring dashboard, or canonical results list. Do not pin every output page, implementation detail, approval surface, or one-off execution artifact; normal workflow output pages remain accessible from the workflow itself. Each entry:
+**Required wording for agent outputs:**
+- If only `analyticsConfig` changes: say **"business metrics configured"**.
+- If only `metadata.roi` changes: say **"ROI assumptions configured"**.
+- If both change: report each section separately; never label analytics metrics as ROI metrics.
 
-```json
-{
-  "pipelineId": "wfl_abc123",
-  "pipelinePathname": "deal-flow",
-  "outputPagePathname": "weekly-report",
-  "label": "Weekly Investor Report",
-  "iconName": "FileText",
-  "pipelineName": "Deal Sourcing",
-  "colorTextClass": "text-emerald-700 dark:text-emerald-400",
-  "pinnedAt": "2026-05-09T10:00:00Z"
-}
-```
+This distinction applies to MCP and CLI users equally because both surfaces call the same external workflow API and return the same pipeline shape.
 
-All snapshot fields capture the source values at pin time and do not auto-update if the workflow or page is later renamed or restyled. To refresh, the operator unpins and re-pins.
+## Platform capabilities (background)
 
-Sidebar rendering uses each field directly:
-- `label` is the primary line.
-- `pipelineName` renders in small muted text below the label, so two pins with the same `label` from different workflows are distinguishable.
-- `iconName` resolves to a lucide icon (defaults to `Pin` if missing or unknown).
-- `colorTextClass` is applied as a Tailwind class on the icon, mirroring the source workflow's accent. Use the same shape produced by the workflow style picker (e.g. `text-emerald-700 dark:text-emerald-400`).
-- The pin row renders as **active** when the operator's current URL matches the pin's target.
+Agentled provides caching per step, automatic retry with backoff, a persistent Knowledge Graph, scoped permissions, and a unified credit system across 100+ integrations. For the full rationale, see `WHY-AGENTLED.md` (in this skill folder).
 
-When seeding a workspace via templates, pre-populate `pinnedOutputs[]` only for the curated artifacts the operator should access directly from the workspace sidebar on day one. Supply `pipelineName` and `colorTextClass` for the proper rendering (otherwise they fall back to the muted default, which still works but loses the visual cue). Pin entries reference output pages that exist on workflows in the same workspace; entries pointing at deleted or renamed pipelines still render — the URL just resolves to a 404 page until the pin is removed.
+**Practical implication:** "retry failed enrichment" and "avoid re-fetching already processed companies" are platform features. Use `retry_execution` to resume from a failed step; per-step caching is automatic. For cross-run row dedup, use `kg.upsert-rows` with a `userKey`.
 
 ## 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> ...`.
+- The standalone CLI can store multiple saved workspace profiles. Check the active one with `agentled auth current`; switch with `agentled auth use <workspace>`; override a single 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`.
 
-## Local Workspace Folder — `agentled_<workspace-slug>/`
-
-When working on Agentled tasks for a user (sourcing kits, workflow design, debugging executions, anything that spans more than a single tool call), **organize all local artifacts under a per-workspace folder named `agentled_<workspace-slug>/`** in the user's current working directory. The slug comes from the active workspace alias (e.g. `agentled_acme/`, `agentled_my-company/`) so a user with multiple workspaces never mixes their data. Resolve the slug from `agentled auth current` (use the alias if set, otherwise the workspace ID). Create the folder on first use; never scatter notes, JSON drafts, or transcripts at the repo root or under a generic `agentled_workspace/` name.
-
-**Required structure (replace `<slug>` with the actual workspace slug):**
-
-```
-agentled_<slug>/
-  README.md                 # what this folder is, current active workspace, last sync to KG
-  decisions/                # one file per non-trivial decision (theme, schema, source list, etc.)
-    YYYY-MM-DD-<slug>.md    # context · options considered · decision · rationale · revisit-when
-  workflows/                # local drafts and copies of pipeline JSON before push
-    <workflow-id>.json      # snapshot of the live workflow (use get_workflow → write file)
-    <slug>.draft.json       # work-in-progress before create_workflow
-  groups/                   # WorkflowGroup specs (see WG-001) — one file per group
-    <group-slug>.kit.json
-  kg/                       # local mirrors / drafts of KG content
-    lists/<listKey>.schema.json
-    text/<key>.md           # workspace company profile, theme docs, etc., before upserting
-  executions/               # debug bundles for failed runs
-    <executionId>/timeline.json, step-outputs/, notes.md
-  worklog.md                # append-only chronological log of what was done, in 1-2 lines per entry
-```
-
-**Why a local folder at all when the KG already stores state?**
-- KG is *workspace truth* — durable, structured, queryable. The local folder is *agent scratch* — drafts, decision rationale, raw debug data, transcripts. Mixing them pollutes the KG and loses local iteration history.
-- 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`. 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.
-
-**On session start:** if `agentled_<slug>/` for the active workspace already exists, read `README.md` and the most recent `decisions/` and `worklog.md` entries before proposing anything new. If it doesn't exist, ask the user once whether they want you to create it for this project, then proceed. If the user has multiple workspaces, only act on the folder matching the currently active workspace from `agentled auth current` — never operate on a sibling folder.
-
-## 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": "agentled.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.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
-- Set an output page `displayConfig.executionNameTemplate` that names the entity and the outreach state. For single-entity outreach, use `{{entityName}} - Email Drafted` before approval and `{{entityName}} - Email Sent` or `{{entityName}} - Contacted` after the post-send status step, e.g. `Joe Dan - VC Firm Name - Email Drafted`; add `{{today}}` only when a short date helps. For batch runs, summarize counts instead, e.g. `26 May - 4 sourced - 3 contacted`.
-
-## Entity Pipeline Pattern (Source → KG → Process)
-
-When a user asks about **finding leads, sourcing companies, collecting contacts, or discovering any entities they want to act on later**, propose this two-workflow architecture instead of a single monolithic workflow.
-
-### Why
-
-Sourcing and processing have different cadences and costs. Decoupling them lets you:
-- Source from many places (LinkedIn, web scrape, Crunchbase, email, webhooks) into one canonical list
-- Process (enrich, score, outreach) only new entities, on a schedule, without re-processing already-handled ones
-- Retry or re-run either phase independently without touching the other
-
-### Workflow 1 — Sourcing (runs on trigger or schedule)
-
-Finds entities from one or more sources and writes them into a shared KG list with `status: "new"`. Uses `kg.upsert-rows` with a caller-supplied `userKey` on each row so re-runs dedup (O(1), no table scan).
-
-```json
-// Step: write sourced entities to KG
-{
-  "id": "save-to-kg",
-  "type": "appAction",
-  "name": "Save to KG",
-  "app": { "id": "kg", "actionId": "kg.upsert-rows", "source": "native" },
-  "stepInputData": {
-    "listKey": "sourced-startups",
-    // rows must be [{ userKey, rowData }, ...] — userKey is the dedup contract.
-    // Use any stable caller-defined id: URL, domain, LinkedIn URL, etc.
-    "rows": "{{steps.extract.items}}",
-    "mergeStrategy": "merge",   // preserve fields added downstream (scores, notes)
-    "status": "new"
-  },
-  "next": { "stepId": "done" }
-}
-```
-
-**Key rules:**
-- Always include a `status` on sourcing writes (default `"new"`) so the processing workflow can filter on it
-- Give every row a stable `userKey` (URL, domain, LinkedIn URL — any caller-defined id that won't change). Same `userKey` in the same list = same DynamoDB row, forever
-- Use `mergeStrategy: "merge"` so downstream-added fields (scores, status updates) survive re-upserts from the source
-- Multiple sourcing workflows can write to the same `listKey` — they converge into one canonical list
-- Use `kg.add-rows` only for one-shot, never-re-run writes where duplicates are acceptable
-
-### Workflow 2 — Processing (runs on schedule, e.g. weekly)
-
-Reads only `status: "new"` rows, processes them (enrich, score, outreach, etc.), then updates status to `"processed"` (or `"scored"`, `"outreached"`, etc.) so they're never picked up again.
-
-```json
-// Step 1: read new entities
-{
-  "id": "read-new",
-  "type": "appAction",
-  "name": "Read New Entities",
-  "app": { "id": "kg", "actionId": "kg.read-list", "source": "native" },
-  "stepInputData": {
-    "listKey": "sourced-startups",
-    "filters": "{\"status\": \"new\"}",
-    "limit": "50"
-  },
-  "next": { "stepId": "process-loop" }
-}
-
-// Step 2: loop → enrich / score / outreach each entity
-// ... your enrichment and scoring steps here, using {{currentItem.url}} etc. ...
-
-// Step N: mark as processed
-{
-  "id": "mark-processed",
-  "type": "appAction",
-  "name": "Mark Processed",
-  "app": { "id": "kg", "actionId": "kg.update-rows", "source": "native" },
-  "stepInputData": {
-    "listKey": "sourced-startups",
-    "rowIds": "{{steps.process-loop.processedIds}}",
-    "fieldUpdates": "{\"status\": \"processed\"}"
-  },
-  "next": { "stepId": "done" }
-}
-```
-
-### Status values (suggested convention)
-
-| Value | Meaning |
-|-------|---------|
-| `new` | Sourced, not yet processed |
-| `scored` | Enriched and scored, not yet outreached |
-| `outreached` | Outreach sent |
-| `rejected` | Filtered out during scoring |
-| `processed` | Generic "done" for non-outreach pipelines |
-
-Use whatever values make sense for the use case — the pattern is the same.
-
-### When to propose this pattern
-
-Suggest it whenever the user says any of:
-- "find leads / companies / contacts"
-- "source startups / investors / candidates"
-- "collect entities from multiple sources"
-- "build a list I can act on later"
-- "score / enrich / outreach to a list"
-- "run this once a week on new items"
-
-The default answer is **two workflows**: one that sources into KG, one that processes from KG. A single do-everything workflow is only appropriate when the user has a fixed one-shot input and no recurring need.
-
-## 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")
-```
+For organizing local artifacts (drafts, decisions, debug bundles) under a per-workspace folder, see `references/workspace-folder.md`.
 
 ## Conversational Building