@agentled/cli 0.1.6 → 0.5.0

package/dist/utils/skills.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Skills installer — copies the bundled Agentled Claude Code skills into the
+ * user's `~/.claude/skills/` (global) or `./.claude/skills/` (project) dir.
+ *
+ * Why: When an agent drives the CLI with a fresh Claude Code session, it does
+ * not have the Agentled skill loaded unless the skill is present on disk in a
+ * Claude-discoverable location. Without the skill, the LLM invents invalid
+ * step types (`type: "ai"`, `knowledge_graph_query`, …) — the exact class of
+ * silent CLI failure that MCP-025 is closing.
+ *
+ * The installer is version-aware:
+ *   - Reads a `version:` frontmatter field from each `SKILL.md`
+ *   - Leaves newer or hand-edited skills alone (unless --force)
+ *   - Reports status so we can print a one-line summary after `auth login`
+ */
+export type SkillInstallOutcome = 'installed' | 'updated' | 'up-to-date' | 'newer-local' | 'hand-edited' | 'forced';
+export interface SkillInstallResult {
+    skill: string;
+    outcome: SkillInstallOutcome;
+    bundledVersion: string;
+    installedVersion: string | null;
+    targetPath: string;
+}
+export interface InstallSkillsOptions {
+    /** true = install to `~/.claude/skills/` (global); false = `./.claude/skills/` (project) */
+    global?: boolean;
+    /** overwrite regardless of version comparison or local edits */
+    force?: boolean;
+}
+/**
+ * Locate the `skills/` directory that ships with @agentled/cli.
+ *
+ * When running from source (`node dist/index.js`) the layout is:
+ *   packages/cli/dist/utils/skills.js  → packages/cli/skills/…
+ * When installed globally via npm, the package layout is the same relative
+ * structure (`dist/utils/skills.js` → `skills/`).
+ */
+export declare function resolveBundledSkillsDir(): string;
+export declare function getSkillsTargetDir(global: boolean): string;
+export declare function installSkills(options?: InstallSkillsOptions): SkillInstallResult[];
+export declare function describeSkillsInstall(results: SkillInstallResult[], targetDir: string): string;
+/**
+ * Produce a short one-line hint for the `auth login` summary, e.g.
+ *   "Skill installed: agentled v0.2.0 → ~/.claude/skills/"
+ *   "Skill already installed (v0.1.0), latest is v0.2.0 — run `agentled skills update` to refresh."
+ *
+ * Returns null if there is nothing worth showing.
+ */
+export declare function summarizeForLoginBanner(results: SkillInstallResult[], targetDir: string): string | null;

package/dist/utils/skills.js

@@ -0,0 +1,214 @@
+/**
+ * Skills installer — copies the bundled Agentled Claude Code skills into the
+ * user's `~/.claude/skills/` (global) or `./.claude/skills/` (project) dir.
+ *
+ * Why: When an agent drives the CLI with a fresh Claude Code session, it does
+ * not have the Agentled skill loaded unless the skill is present on disk in a
+ * Claude-discoverable location. Without the skill, the LLM invents invalid
+ * step types (`type: "ai"`, `knowledge_graph_query`, …) — the exact class of
+ * silent CLI failure that MCP-025 is closing.
+ *
+ * The installer is version-aware:
+ *   - Reads a `version:` frontmatter field from each `SKILL.md`
+ *   - Leaves newer or hand-edited skills alone (unless --force)
+ *   - Reports status so we can print a one-line summary after `auth login`
+ */
+import { existsSync, readFileSync, mkdirSync, readdirSync, statSync, cpSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+/**
+ * Locate the `skills/` directory that ships with @agentled/cli.
+ *
+ * When running from source (`node dist/index.js`) the layout is:
+ *   packages/cli/dist/utils/skills.js  → packages/cli/skills/…
+ * When installed globally via npm, the package layout is the same relative
+ * structure (`dist/utils/skills.js` → `skills/`).
+ */
+export function resolveBundledSkillsDir() {
+    const here = fileURLToPath(import.meta.url);
+    // dist/utils/skills.js → package root is two levels up
+    const pkgRoot = resolve(dirname(here), '..', '..');
+    return join(pkgRoot, 'skills');
+}
+export function getSkillsTargetDir(global) {
+    return global
+        ? join(homedir(), '.claude', 'skills')
+        : join(process.cwd(), '.claude', 'skills');
+}
+/**
+ * Parse a `version:` field out of the YAML-style frontmatter at the top of a
+ * SKILL.md file. Returns null if no frontmatter or no version field is present.
+ */
+function parseSkillVersion(skillMdPath) {
+    try {
+        const content = readFileSync(skillMdPath, 'utf-8');
+        // Only inspect frontmatter (between the first two --- delimiters)
+        const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch)
+            return null;
+        const versionMatch = fmMatch[1].match(/^version:\s*(.+)$/m);
+        return versionMatch ? versionMatch[1].trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare two semver-ish version strings. Returns -1, 0, or 1.
+ * Handles missing prereleases by treating undefined segments as 0.
+ */
+function compareVersions(a, b) {
+    const parse = (v) => v.replace(/^v/, '').split('.').map(n => parseInt(n, 10) || 0);
+    const [a1, a2 = 0, a3 = 0] = parse(a);
+    const [b1, b2 = 0, b3 = 0] = parse(b);
+    if (a1 !== b1)
+        return a1 < b1 ? -1 : 1;
+    if (a2 !== b2)
+        return a2 < b2 ? -1 : 1;
+    if (a3 !== b3)
+        return a3 < b3 ? -1 : 1;
+    return 0;
+}
+/**
+ * Recursively hash-compare two directories by content. Returns true if the
+ * byte contents of every file match (directory structure + file bytes).
+ *
+ * Used to detect hand-edited installs: if the installed version matches the
+ * bundled version but the bytes differ, the user (or a prior agent session)
+ * has customised the skill and we should not overwrite without --force.
+ */
+function directoriesIdentical(a, b) {
+    try {
+        const aEntries = readdirSync(a).sort();
+        const bEntries = readdirSync(b).sort();
+        if (aEntries.length !== bEntries.length)
+            return false;
+        for (let i = 0; i < aEntries.length; i++) {
+            if (aEntries[i] !== bEntries[i])
+                return false;
+            const aChild = join(a, aEntries[i]);
+            const bChild = join(b, bEntries[i]);
+            const aStat = statSync(aChild);
+            const bStat = statSync(bChild);
+            if (aStat.isDirectory() !== bStat.isDirectory())
+                return false;
+            if (aStat.isDirectory()) {
+                if (!directoriesIdentical(aChild, bChild))
+                    return false;
+            }
+            else {
+                const aBuf = readFileSync(aChild);
+                const bBuf = readFileSync(bChild);
+                if (!aBuf.equals(bBuf))
+                    return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function installSkills(options = {}) {
+    const sourceDir = resolveBundledSkillsDir();
+    if (!existsSync(sourceDir)) {
+        throw new Error(`Bundled skills directory not found at ${sourceDir}`);
+    }
+    const targetBase = getSkillsTargetDir(options.global ?? false);
+    const results = [];
+    const skills = readdirSync(sourceDir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => d.name);
+    for (const skill of skills) {
+        const src = join(sourceDir, skill);
+        const dest = join(targetBase, skill);
+        const bundledVersion = parseSkillVersion(join(src, 'SKILL.md')) ?? '0.0.0';
+        const installedVersion = existsSync(dest) ? parseSkillVersion(join(dest, 'SKILL.md')) : null;
+        let outcome;
+        if (!existsSync(dest)) {
+            outcome = 'installed';
+        }
+        else if (options.force) {
+            outcome = 'forced';
+        }
+        else if (installedVersion && compareVersions(installedVersion, bundledVersion) > 0) {
+            outcome = 'newer-local';
+        }
+        else if (installedVersion && compareVersions(installedVersion, bundledVersion) === 0) {
+            outcome = directoriesIdentical(src, dest) ? 'up-to-date' : 'hand-edited';
+        }
+        else {
+            outcome = 'updated';
+        }
+        if (outcome === 'installed' || outcome === 'updated' || outcome === 'forced') {
+            mkdirSync(dest, { recursive: true });
+            cpSync(src, dest, { recursive: true, force: true });
+        }
+        results.push({
+            skill,
+            outcome,
+            bundledVersion,
+            installedVersion,
+            targetPath: dest,
+        });
+    }
+    return results;
+}
+export function describeSkillsInstall(results, targetDir) {
+    if (results.length === 0)
+        return 'No skills to install.';
+    const lines = [];
+    for (const r of results) {
+        switch (r.outcome) {
+            case 'installed':
+                lines.push(`  ✓ ${r.skill} v${r.bundledVersion} installed`);
+                break;
+            case 'updated':
+                lines.push(`  ✓ ${r.skill} v${r.installedVersion} → v${r.bundledVersion} updated`);
+                break;
+            case 'forced':
+                lines.push(`  ✓ ${r.skill} v${r.bundledVersion} installed (forced)`);
+                break;
+            case 'up-to-date':
+                lines.push(`  • ${r.skill} v${r.bundledVersion} already installed`);
+                break;
+            case 'newer-local':
+                lines.push(`  • ${r.skill} local v${r.installedVersion} is newer than bundled v${r.bundledVersion} — left as-is`);
+                break;
+            case 'hand-edited':
+                lines.push(`  • ${r.skill} v${r.bundledVersion} already installed with local edits — left as-is (run with --force to overwrite)`);
+                break;
+        }
+    }
+    lines.push(`  Skills directory: ${targetDir}`);
+    return lines.join('\n');
+}
+/**
+ * Produce a short one-line hint for the `auth login` summary, e.g.
+ *   "Skill installed: agentled v0.2.0 → ~/.claude/skills/"
+ *   "Skill already installed (v0.1.0), latest is v0.2.0 — run `agentled skills update` to refresh."
+ *
+ * Returns null if there is nothing worth showing.
+ */
+export function summarizeForLoginBanner(results, targetDir) {
+    if (results.length === 0)
+        return null;
+    const fresh = results.filter(r => r.outcome === 'installed');
+    const stale = results.filter(r => r.outcome === 'newer-local' || r.outcome === 'hand-edited');
+    const updatable = results.filter(r => r.outcome === 'up-to-date' && r.installedVersion && r.bundledVersion && compareVersions(r.installedVersion, r.bundledVersion) < 0);
+    if (fresh.length > 0) {
+        const names = fresh.map(r => `${r.skill} v${r.bundledVersion}`).join(', ');
+        return `Installed Claude Code skill: ${names} → ${targetDir}`;
+    }
+    if (stale.length > 0) {
+        const r = stale[0];
+        return `Skill "${r.skill}" already installed (v${r.installedVersion ?? '?'}), bundled is v${r.bundledVersion} — run \`agentled skills update\` to refresh.`;
+    }
+    if (updatable.length > 0) {
+        const r = updatable[0];
+        return `Skill "${r.skill}" v${r.installedVersion} installed, v${r.bundledVersion} available — run \`agentled skills update\` to refresh.`;
+    }
+    return null;
+}
+//# sourceMappingURL=skills.js.map

package/dist/utils/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/utils/skills.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentled/cli",
-  "version": "0.1.6",
+  "version": "0.5.0",
   "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",
@@ -28,6 +28,9 @@
   },
   "files": [
     "dist",
+    "skills",
+    "patterns",
+    "scaffolds",
     "README.md",
     "llms.txt",
     "llms-full.txt"

package/patterns/v1/00-why-agentic-ops.md

@@ -0,0 +1,107 @@
+# 00 — Why agentic-ops
+
+> The ops discipline that makes AI agents production-ready.
+
+---
+
+## The pitch deck demo works. Production doesn't.
+
+You've seen it: an AI agent that looks brilliant in a demo — processes a lead, writes a personalized email, updates the CRM. Then you run it on 500 leads a week and the wheels fall off. Duplicates. Missing records. Costs 3× what you expected. No way to know what actually went through.
+
+This isn't an AI problem. It's an **architecture problem**.
+
+The fix has a name in every other engineering discipline: operations. CI/CD, observability, idempotency, retries, caching, audit trails — these didn't exist on day one of web development either. Developers invented them because raw execution didn't scale. Agentic workflows are at the same inflection point.
+
+This is **agentic-ops**: the patterns that make the gap between "demo" and "production" crossable.
+
+---
+
+## 1. Unit economics collapse without dedup discipline
+
+This is the argument that lands before developers hit the wall themselves.
+
+You're processing 500 inbound leads per week. Your workflow enriches each one (5 credits). No dedup gate — the workflow polls every hour, no label marking what's been processed.
+
+- Average lead appears in 3 polls before it's handled: **1,500 enrichments instead of 500**
+- At 5 credits each: **5,000 wasted credits per week**
+- At scale, you're paying for work you already did
+
+This isn't hypothetical. It's the default outcome of any polling workflow without a dedup gate. See [02-dedup-gates](02-dedup-gates.md) for the fix.
+
+---
+
+## 2. Non-determinism at scale
+
+A one-off prompt works once. Run the same prompt 1,000 times against your pipeline and you get 1,000 slightly different outputs — different field names, different score ranges, different JSON shapes. No two downstream steps can reliably consume the previous one.
+
+Structured workflows define a **response contract**: the output schema is declared upfront, validated at runtime, and consistent across every execution. The AI fills in the values; the workflow enforces the shape.
+
+Without this contract, you're parsing surprises, not outputs.
+
+---
+
+## 3. No audit trail, no trust
+
+"The AI processed our deal flow last week" — can you tell me exactly which companies it looked at, what data it used, what score it assigned, and why three were dropped? If not, you can't trust it in any context that matters: regulated industries, board reporting, customer-facing processes.
+
+Structured workflows produce **per-step execution records**: inputs, outputs, duration, status, timestamp. You can replay any run. You can compare two runs on the same input. You can show an auditor exactly what happened.
+
+Ad-hoc prompts produce a chat message and nothing else.
+
+---
+
+## 4. Retries without idempotency destroy partial state
+
+An AI agent that crashes halfway through is worse than one that never started. You have partial writes: some records enriched, some not; some CRM entries created, some missing. You don't know where it stopped.
+
+Structured workflows solve this at two levels:
+- **Step-level retry**: resume from the exact failed step with the same inputs — no re-running the work that succeeded
+- **Idempotency gates**: dedup keys, label markers, and processed flags ensure a retried step produces the same outcome as the original, not a duplicate
+
+See [07-error-handling](07-error-handling.md) and [02-dedup-gates](02-dedup-gates.md).
+
+---
+
+## 5. Caching requires stable step boundaries
+
+Enriching the same LinkedIn company URL twice in the same workflow shouldn't hit the API twice. But caching requires a **stable cache key**: a defined input that uniquely identifies the computation.
+
+Ad-hoc prompts have no stable key — the prompt is the key, and it changes with every rephrasing. Structured steps have explicit inputs, which means the platform can cache at the step level, deduplicate in-flight requests, and short-circuit repeated work.
+
+No step boundary = no cache key = no caching.
+
+---
+
+## 6. Production requirements don't exist in raw prompting
+
+Running AI agents at production scale without structured execution is like running a web server without a framework. You'll reinvent every wheel:
+
+- **Observability**: knowing which step is running, how long it's taking, when it silently failed
+- **Rate limiting**: preventing a burst of executions from hammering a downstream API
+- **Concurrency control**: ensuring two parallel runs don't write conflicting records to the same CRM entry
+- **Backpressure**: slowing intake when the processing queue backs up
+
+These are solved problems in structured workflow systems. They don't exist as primitives in a prompt-and-hope architecture.
+
+---
+
+## 7. Human-in-the-loop gates need a first-class abstraction
+
+"Have a human review the AI's output before it sends an email" sounds simple. In practice it requires: a UI to surface the output for review, a way to approve or reject, a mechanism to block the next step until the human acts, and a timeout path if they don't.
+
+This is a first-class primitive in workflow systems — an approval gate with configurable behavior. In raw prompting, you build it from scratch every time.
+
+Any workflow that touches customers, sends communications, or writes to a system of record should have a human-in-the-loop gate. See [09-human-in-the-loop](../v2/09-human-in-the-loop.md) (v2).
+
+---
+
+## The pattern
+
+Every production failure in agentic workflows traces back to one of these seven gaps. The patterns in this repo address each one directly — not as theoretical advice, but as the specific implementations that fix them.
+
+Start with the one that matches your current pain:
+- Burning credits → [03-credit-efficiency](03-credit-efficiency.md)
+- Processing duplicates → [02-dedup-gates](02-dedup-gates.md)
+- Steps silently skipping → [06-conditional-routing](06-conditional-routing.md)
+- Crashes with partial state → [07-error-handling](07-error-handling.md)
+- Wrong trigger choice → [01-trigger-design](01-trigger-design.md)

package/patterns/v1/01-trigger-design.md

@@ -0,0 +1,107 @@
+# 01 — Trigger design: polling vs event triggers
+
+**Problem**: Developers default to event triggers for email/document intake workflows, creating fragile pipelines that drop records, can't backfill, and are hard to debug.
+
+**Why it fails silently**: Event triggers appear to work in testing (low volume, reliable delivery). At production scale, re-deliveries cause duplicates, Pub/Sub TTL loses events during outages, and there's no way to backfill records missed during downtime — without any visible error.
+
+---
+
+## Decision framework
+
+| | Schedule (polling) | App Event (real-time) |
+|---|---|---|
+| **Latency** | minutes–hours | seconds |
+| **Idempotency** | trivial — label/flag marks processed | must dedupe on messageId; re-deliveries happen |
+| **Backfill** | built-in — widen the query window | doesn't exist; needs a separate bootstrap run |
+| **Replay after outage** | automatic on next scheduled run | events can be permanently lost (TTL) |
+| **Debugging** | read last execution log | subscription status + delivery + filter + dedupe all need checking |
+| **Infrastructure** | none | webhook receiver, watch renewal, Pub/Sub |
+
+**Default rule: polling for intake, events for reactions.**
+
+---
+
+## Anti-pattern
+
+Using an event trigger for email intake because it "feels more real-time":
+
+```yaml
+# Wrong: event trigger for deal flow email intake
+trigger:
+  type: app_event
+  app: gmail
+  event: GMAIL_NEW_MESSAGE_RECEIVED
+  filters:
+    query: "from:investor subject:pitch"
+```
+
+Problems:
+- Duplicate delivery means the same email gets processed 2-3× with no dedup mechanism
+- Gmail watch tokens expire — you need a renewal job or emails stop arriving silently
+- No backfill: if the workflow is down for 2 days, those emails are gone
+- Debugging requires checking: is the watch active? Did the webhook fire? Did the filter match? Did the dedup run?
+
+---
+
+## Correct pattern
+
+Schedule trigger with label-based dedup:
+
+```yaml
+# Correct: scheduled polling with dedup gate
+trigger:
+  type: schedule
+  config:
+    frequency: daily
+    time: "08:00"
+
+steps:
+  - id: fetch-emails
+    action: GMAIL_FETCH_EMAILS
+    input:
+      query: "-label:processed newer_than:1d"
+      max_results: 50
+
+  - id: process-email
+    type: loop
+    over: "{{steps.fetch-emails.messages}}"
+    # ... processing steps ...
+
+  - id: mark-processed
+    action: GMAIL_ADD_LABEL
+    input:
+      message_id: "{{currentItem.id}}"
+      label_id: "{{steps.ensure-label.id}}"  # resolved ID, not display name
+```
+
+The `-label:processed` filter does the dedup work. Each email is processed exactly once. If the workflow goes down for a week, widen to `newer_than:7d` on the next run to backfill.
+
+---
+
+## When to use event triggers
+
+Event triggers are correct when:
+- The user explicitly requires sub-minute latency ("alert within 30 seconds", "as soon as", "real-time")
+- The workflow is a **side effect** (fire-and-forget notification), not a record-of-truth producer
+- Missed events are acceptable (or you have a separate reconciliation job)
+
+---
+
+## Trigger type cheatsheet
+
+| User says | Trigger |
+|---|---|
+| "process inbound pitch emails" | Schedule (daily) |
+| "triage support emails every morning" | Schedule (daily 08:00) |
+| "every Monday summarize last week's emails" | Schedule (weekly) |
+| "analyze my inbox and create Notion entries" | Schedule (daily) |
+| "page oncall within 30s of an escalation email" | App event |
+| "create a ticket the moment a customer emails" | App event |
+| "run every time a form is submitted" | Webhook |
+| "user clicks Run" | Manual |
+
+---
+
+## One-line rule
+
+> Default to Schedule + label-based dedup for email and document intake; use event triggers only when the user explicitly states a latency requirement under one minute.

package/patterns/v1/02-dedup-gates.md

@@ -0,0 +1,135 @@
+# 02 — Dedup gates: idempotency for agentic workflows
+
+**Problem**: Without a dedup gate, every record in a polling or webhook workflow gets processed multiple times — silently, expensively, and often with conflicting writes.
+
+**Why it fails silently**: The first few runs look correct. Duplicates only surface when you notice your CRM has 3 entries for the same company, your enrichment bill is 2× expected, or your outreach tool sent the same email twice. By then, the damage is done.
+
+---
+
+## The Gmail label-ID bug (the most common dedup failure)
+
+This is the one that wastes 2 hours and isn't documented anywhere.
+
+You build an email polling workflow. You add a step to mark each email as processed. You pass the label name:
+
+```json
+{
+  "action": "GMAIL_ADD_LABEL",
+  "input": {
+    "message_id": "{{currentItem.id}}",
+    "label_id": "processed"
+  }
+}
+```
+
+Result: `400 Bad Request: Invalid label: processed`
+
+The Gmail API does not accept label **display names**. It requires internal label **IDs** — strings that look like `Label_3456789012345678`. The display name "processed" is what you see in Gmail's UI. The ID is what the API needs.
+
+Same bug with any user-created label: `"agentled"`, `"reviewed"`, `"done"` — all invalid.
+
+---
+
+## Anti-pattern
+
+```json
+// Wrong: passing label display name
+{
+  "action": "GMAIL_ADD_LABEL",
+  "input": {
+    "message_id": "{{currentItem.id}}",
+    "label_id": "processed"
+  }
+}
+// → 400: Invalid label: processed
+```
+
+---
+
+## Correct pattern
+
+Always resolve the label ID first using a create-or-get-label step:
+
+```json
+// Step 1: create label if it doesn't exist, or get existing (idempotent)
+{
+  "id": "ensure-label",
+  "action": "GMAIL_CREATE_LABEL",
+  "input": { "name": "processed" }
+}
+// Returns: { "id": "Label_3456789012345678", "name": "processed" }
+
+// Step 2: fetch unprocessed emails
+{
+  "id": "fetch-emails",
+  "action": "GMAIL_FETCH_EMAILS",
+  "input": {
+    "query": "-label:processed newer_than:1d",
+    "max_results": 50
+  }
+}
+
+// Step 3 (inside loop): mark each email processed using the resolved ID
+{
+  "id": "mark-processed",
+  "action": "GMAIL_ADD_LABEL",
+  "input": {
+    "message_id": "{{currentItem.id}}",
+    "label_id": "{{steps.ensure-label.id}}"  // ← resolved ID, not display name
+  }
+}
+```
+
+`GMAIL_CREATE_LABEL` is idempotent — if the label already exists, it returns the existing label's ID. Run it every time with no side effects.
+
+---
+
+## How label-based dedup works
+
+The `-label:processed` filter in the fetch query does the dedup work:
+
+1. First run: fetches 50 emails. Processes each. Adds `processed` label to each.
+2. Second run: fetches emails without `processed` label. Those 50 are now excluded. Only new emails are returned.
+3. Outage for 3 days: widen to `newer_than:7d` on the next run. All unprocessed emails in the window are caught. Processed ones are excluded.
+
+This gives you **exactly-once processing** with no database, no external state store, and no coordination overhead.
+
+---
+
+## Dedup for webhook triggers
+
+Webhooks re-deliver. Always. Your endpoint will receive the same event 2–5× under normal conditions (retries on timeout, delivery confirmation failures). Without dedup:
+
+```
+Webhook fires → workflow starts → enrichment call × 3 duplicates → 3 CRM entries
+```
+
+The fix: use a unique event ID as an idempotency key and check before processing:
+
+```javascript
+// Code step at workflow entry
+const eventId = input.webhookPayload.id;  // or messageId, leadId, etc.
+const alreadyProcessed = await kv.get(`processed:${eventId}`);
+if (alreadyProcessed) {
+  return { skipped: true, reason: "duplicate" };
+}
+await kv.set(`processed:${eventId}`, true, { ttl: 86400 });
+```
+
+---
+
+## Dedup patterns by source
+
+| Source | Dedup mechanism |
+|---|---|
+| Gmail polling | `-label:processed` query + `GMAIL_ADD_LABEL` after processing |
+| Webhook | Idempotency key from event ID, stored in KV or DB |
+| Scheduled API poll | Cursor / `since_id` / `updated_at` timestamp stored in persistent memory |
+| File/S3 intake | Move to `processed/` prefix after reading |
+| Form submissions | Unique submission ID checked before processing |
+
+---
+
+## One-line rule
+
+> Always resolve label IDs before passing them to the Gmail API — display names cause a silent 400 error — and always add the processed label as the final step in every email intake loop.