@agentled/cli 0.6.4 → 0.6.6

package/dist/utils/workspace-folder.js

@@ -0,0 +1,340 @@
+/**
+ * Workspace folder helpers — local agentled_<slug>/ directory used as the
+ * agent's working tree for building, testing, and iterating on workflows.
+ *
+ * Folder layout:
+ *
+ *   agentled_<slug>/
+ *   ├── README.md                # agent-facing guide
+ *   ├── .agentled/
+ *   │   ├── workspace.json       # workspaceId, slug, apiBase, syncedAt
+ *   │   └── cache/
+ *   │       ├── apps.json        # app registry
+ *   │       └── models.json      # supported models
+ *   ├── docs/
+ *   │   ├── SKILL.md             # full skill reference (copied from package)
+ *   │   └── GOTCHAS.md           # documented failure modes
+ *   ├── examples/
+ *   │   ├── scaffolds/           # bundled scaffold JSONs (editable)
+ *   │   └── live/                # workflows pulled from the workspace
+ *   ├── fixtures/
+ *   │   └── step-outputs/        # captured step outputs (zero-credit replay)
+ *   ├── tests/                   # <wfId>.test.json declarative test files
+ *   └── drafts/                  # in-progress pipeline JSON files
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// ---------------------------------------------------------------------------
+// Resolve a workspace folder from cwd: try cwd → walk up → scan children
+// ---------------------------------------------------------------------------
+export function findWorkspaceDir(cwd = process.cwd()) {
+    // 1. cwd itself is a workspace
+    if (existsSync(join(cwd, '.agentled', 'workspace.json')))
+        return cwd;
+    // 2. Walk up parents
+    let current = cwd;
+    while (true) {
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        if (existsSync(join(parent, '.agentled', 'workspace.json')))
+            return parent;
+        current = parent;
+    }
+    // 3. Scan child dirs for agentled_*
+    try {
+        const entries = readdirSync(cwd, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !entry.name.startsWith('agentled_'))
+                continue;
+            const wsFile = join(cwd, entry.name, '.agentled', 'workspace.json');
+            if (existsSync(wsFile))
+                return join(cwd, entry.name);
+        }
+    }
+    catch {
+        // cwd unreadable
+    }
+    return null;
+}
+export function readWorkspaceMeta(wsDir) {
+    const raw = readFileSync(join(wsDir, '.agentled', 'workspace.json'), 'utf-8');
+    return JSON.parse(raw);
+}
+export function writeWorkspaceMeta(wsDir, meta) {
+    writeFileSync(join(wsDir, '.agentled', 'workspace.json'), JSON.stringify(meta, null, 2) + '\n');
+}
+// ---------------------------------------------------------------------------
+// Resolve bundled assets shipped with @agentled/cli
+// ---------------------------------------------------------------------------
+function pkgRoot() {
+    const here = fileURLToPath(import.meta.url);
+    // dist/utils/workspace-folder.js → ../.. → package root
+    return resolve(dirname(here), '..', '..');
+}
+export function bundledScaffoldsDir() {
+    return join(pkgRoot(), 'scaffolds');
+}
+export function bundledSkillMd() {
+    return join(pkgRoot(), 'skills', 'agentled', 'SKILL.md');
+}
+// ---------------------------------------------------------------------------
+// GOTCHAS.md — embedded so it stays in sync with the CLI release
+// ---------------------------------------------------------------------------
+export const GOTCHAS_MD = `# Agentled — Documented Failure Modes (GOTCHAS)
+
+These pass JSON syntax validation but silently misbehave at runtime.
+Run \`agentled workflows lint <file>\` to catch them statically before deploying.
+
+---
+
+## 1. \`criteria\` not \`conditions\` in entryConditions  [CRITERIA_NOT_CONDITIONS]
+
+**Wrong:** \`{ "entryConditions": { "conditions": [...] } }\`
+**Correct:** \`{ "entryConditions": { "criteria": [...] } }\`
+
+The executor reads \`entryConditions.criteria\`. The key \`conditions\` is silently ignored.
+
+---
+
+## 2. \`variable\` not \`field\` in criteria items  [VARIABLE_NOT_FIELD]
+
+**Wrong:** \`{ "field": "{{steps.x.score}}", "operator": ">", "value": 70 }\`
+**Correct:** \`{ "variable": "{{steps.x.score}}", "operator": ">", "value": 70 }\`
+
+Using \`field\` causes the criterion to be silently skipped.
+
+---
+
+## 3. Gmail label_id must be the internal Label_XXXX ID  [GMAIL_LABEL_DISPLAY_NAME]
+
+Gmail's API requires \`Label_XXXXXXXXXX\` IDs, not display names.
+Add a \`GMAIL_CREATE_LABEL\` step before and use \`{{steps.ensure-label.id}}\`.
+
+---
+
+## 4. \`aiActionWithTools\` with no tools  [AI_STEP_TOOLS_REQUIRED]
+
+A step with \`type: "aiActionWithTools"\` must have at least one tool in
+\`step.tools\` or \`step.agent.tools\`.
+
+Valid \`builtinType\` values: \`web_search\`, \`file_search\`, \`code_interpreter\`,
+\`fetch_website_content\`, \`kg_search\`, \`kg_traverse\`, \`kg_nodes\`, \`kg_write\`,
+\`workspace_memory\`.
+
+---
+
+## 5. Email steps need type + approval action + outreachProfile  [EMAIL_MISSING_*]
+
+Three required pieces:
+- \`pipelineStepPrompt.type: "email"\`
+- \`onApproval.action: "schedule-email"\`
+- \`outreachProfile\` input page in \`context.inputPages\`
+
+Missing the schedule-email action means the email is drafted but never sent.
+
+---
+
+## 6. Only the first step in a loop gets \`loopConfig\`  [LOOP_CONFIG_MULTIPLE_STEPS]
+
+\`loopConfig\` must be on the first step in the loop chain only. Subsequent
+steps inside the loop iterate automatically.
+
+---
+
+## 7. Don't pass raw \`{{input.*}}\` directly to search APIs  [RAW_INPUT_TO_SEARCH]
+
+Add an aiAction step before the search that generates optimized queries.
+Raw user input makes poor search queries.
+
+---
+
+## 8. Child workflows must use \`return\` step, not \`milestone\`  [CHILD_WORKFLOW_NO_RETURN]
+
+If a workflow is called via \`agentled.call-workflow\`, use \`type: "return"\`.
+\`milestone\` produces no return data. Also set \`context.executionInputConfig.internal: true\`.
+
+---
+
+## 9. Model IDs are internal format, not Anthropic format  [MODEL_ID_FORMAT]
+
+Wrong: \`claude-sonnet-4-6\`. Correct: \`claude-4-6-sonnet\`.
+Run \`agentled models list\` for valid internal IDs.
+
+---
+
+## 10. Native app actionId must include appId prefix  [ACTION_ID_MISSING_PREFIX]
+
+Wrong: \`{ "id": "kg", "actionId": "read-list" }\`
+Correct: \`{ "id": "kg", "actionId": "kg.read-list" }\`
+
+---
+
+## 11. \`loop_completion\` criteria requires \`onCriteriaFail: "wait"\`  [LOOP_COMPLETION_NOT_WAIT]
+
+Without \`onCriteriaFail: "wait"\`, the step skips instead of blocking until
+the loop finishes. The \`stepId\` field is also required.
+
+---
+
+## 12. Arrays in JSON template strings — don't JSON.stringify
+
+The serializer detects when a template variable is the sole content of a JSON
+field and inlines the raw value. Pass \`{ "items": "{{steps.x.items}}" }\`
+directly — no stringify needed.
+
+---
+
+## 13. \`kg.upsert-rows\` needs \`userKey\` for dedup; \`kg.add-rows\` always inserts
+
+\`kg.upsert-rows\` with \`userKey\`: same key = same row, cross-run dedup O(1).
+\`kg.add-rows\`: always inserts a new row, duplicates accumulate.
+Use \`mergeStrategy: "merge"\` to preserve downstream-added fields.
+`;
+// ---------------------------------------------------------------------------
+// README.md — agent-facing guide written into each new workspace folder
+// ---------------------------------------------------------------------------
+export function makeWorkspaceReadme(meta) {
+    return `# Agentled Workspace — ${meta.name}
+
+**Workspace ID:** \`${meta.workspaceId}\`
+**Slug:** \`${meta.slug}\`
+**API Base:** ${meta.apiBase}
+**Last synced:** ${meta.syncedAt}
+
+---
+
+## What this folder is
+
+Local working tree for building, testing, and iterating on workflows for the
+\`${meta.slug}\` workspace.
+
+- **\`docs/\`** — SKILL.md (full reference) + GOTCHAS.md (13 failure modes)
+- **\`examples/scaffolds/\`** — preflight-clean pipeline JSON skeletons
+- **\`examples/live/\`** — pulled copies of real workspace workflows
+- **\`fixtures/step-outputs/\`** — captured step outputs for credit-free testing
+- **\`tests/\`** — declarative test files for each workflow
+- **\`drafts/\`** — in-progress pipelines before pushing to workspace
+
+---
+
+## Quick commands
+
+\`\`\`bash
+# Pull a workflow from the workspace to iterate locally
+agentled workflows pull <workflowId>
+
+# Static gotcha checks (no API)
+agentled workflows lint <file.json>
+
+# Capture step outputs from a past execution
+agentled fixture capture <executionId> --wf <workflowId>
+
+# Run declarative tests against captured fixtures (zero credits)
+agentled test <workflowId>
+
+# Run tests with live API calls (costs credits)
+agentled test <workflowId> --live
+
+# Push a local pipeline to the workspace
+agentled workflows create --file <file.json>
+
+# Refresh cached app registry + models
+agentled workspace sync
+\`\`\`
+
+---
+
+## Testing strategy (zero-credit loop)
+
+1. Build the workflow incrementally via MCP tools or CLI.
+2. Run once via \`workflows start\` with sample input.
+3. Capture outputs: \`agentled fixture capture <execId> --wf <wfId>\`
+4. Iterate on step logic, test against fixtures: \`agentled test <wfId>\`
+5. For AI step changes, re-test with \`--live\` (costs credits for that step only).
+6. Use \`agentled workflows lint\` before every \`workflows validate\` to catch gotchas first.
+
+---
+
+## Folder layout
+
+\`\`\`
+agentled_${meta.slug}/
+├── README.md
+├── .agentled/
+│   ├── workspace.json
+│   └── cache/
+│       ├── apps.json
+│       └── models.json
+├── docs/
+│   ├── SKILL.md
+│   └── GOTCHAS.md
+├── examples/
+│   ├── scaffolds/
+│   └── live/
+├── fixtures/
+│   └── step-outputs/
+├── tests/
+└── drafts/
+\`\`\`
+`;
+}
+// ---------------------------------------------------------------------------
+// Folder bootstrap: create dirs, copy bundled assets, write GOTCHAS+README
+// ---------------------------------------------------------------------------
+export function createWorkspaceFolder(folderPath, meta, opts = {}) {
+    const dirs = [
+        folderPath,
+        join(folderPath, '.agentled', 'cache'),
+        join(folderPath, 'docs'),
+        join(folderPath, 'examples', 'scaffolds'),
+        join(folderPath, 'examples', 'live'),
+        join(folderPath, 'fixtures', 'step-outputs'),
+        join(folderPath, 'tests'),
+        join(folderPath, 'drafts'),
+    ];
+    for (const dir of dirs)
+        mkdirSync(dir, { recursive: true });
+    writeWorkspaceMeta(folderPath, meta);
+    if (opts.appsList) {
+        writeFileSync(join(folderPath, '.agentled', 'cache', 'apps.json'), JSON.stringify(opts.appsList, null, 2) + '\n');
+    }
+    if (opts.modelsList) {
+        writeFileSync(join(folderPath, '.agentled', 'cache', 'models.json'), JSON.stringify(opts.modelsList, null, 2) + '\n');
+    }
+    // Copy SKILL.md from bundled package
+    const skillSrc = bundledSkillMd();
+    if (existsSync(skillSrc)) {
+        copyFileSync(skillSrc, join(folderPath, 'docs', 'SKILL.md'));
+    }
+    else {
+        writeFileSync(join(folderPath, 'docs', 'SKILL.md'), '# SKILL.md\n\nRun `agentled workspace sync` to refresh.\n');
+    }
+    writeFileSync(join(folderPath, 'docs', 'GOTCHAS.md'), GOTCHAS_MD);
+    // Copy bundled scaffolds into examples/scaffolds/
+    const scaffoldDir = bundledScaffoldsDir();
+    if (existsSync(scaffoldDir)) {
+        for (const file of readdirSync(scaffoldDir).filter((f) => f.endsWith('.json'))) {
+            copyFileSync(join(scaffoldDir, file), join(folderPath, 'examples', 'scaffolds', file));
+        }
+    }
+    writeFileSync(join(folderPath, 'README.md'), makeWorkspaceReadme(meta));
+    writeFileSync(join(folderPath, '.gitignore'), ['.agentled/cache/', 'fixtures/', 'tests/_runs/'].join('\n') + '\n');
+}
+export function refreshWorkspaceFolder(wsDir, opts) {
+    const cacheDir = join(wsDir, '.agentled', 'cache');
+    mkdirSync(cacheDir, { recursive: true });
+    if (opts.appsList)
+        writeFileSync(join(cacheDir, 'apps.json'), JSON.stringify(opts.appsList, null, 2) + '\n');
+    if (opts.modelsList)
+        writeFileSync(join(cacheDir, 'models.json'), JSON.stringify(opts.modelsList, null, 2) + '\n');
+    const skillSrc = bundledSkillMd();
+    if (existsSync(skillSrc))
+        copyFileSync(skillSrc, join(wsDir, 'docs', 'SKILL.md'));
+    writeFileSync(join(wsDir, 'docs', 'GOTCHAS.md'), GOTCHAS_MD);
+    const meta = readWorkspaceMeta(wsDir);
+    meta.syncedAt = new Date().toISOString();
+    writeWorkspaceMeta(wsDir, meta);
+}
+//# sourceMappingURL=workspace-folder.js.map

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

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

package/package.json

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

package/patterns/v1/12-event-driven-workflow-groups.md

@@ -0,0 +1,288 @@
+# Pattern 12 — Event-Driven Workflow Groups
+
+Multi-workflow systems connected through shared KG lists and status transitions.
+
+## When to use
+
+Use this pattern whenever the user's business process naturally decomposes into **more than one workflow** connected by shared state. Common signals:
+
+- "Find leads, then process them on a schedule"
+- "Source from multiple places into one canonical list"
+- "Trigger downstream outreach when an upstream entity reaches a milestone"
+- "Process inbound items, triage them, then approve a response"
+- "Run sourcing weekly but scoring only when new items arrive"
+
+A single monolithic workflow is only appropriate for truly one-shot, linear processes. Most real operations are a group.
+
+## Core insight: workflows communicate through KG status, not direct calls
+
+Instead of one large workflow that does everything, build workflows that each own one stage of a process and hand off to the next via KG row status transitions.
+
+```
+[Workflow A]  trigger → source entities → kg.upsert-rows(status: "new") → done
+[Workflow B]  trigger → kg.read-list(filter: "new") → enrich/score → kg.update-rows(status: "scored") → done
+[Workflow C]  trigger → kg.read-list(filter: "scored") → outreach → kg.update-rows(status: "outreached") → done
+```
+
+Each workflow is independently runnable, retryable, and testable. No direct dependency between them at runtime — only the KG list is shared.
+
+## The Group Manifest
+
+Before creating any workflow, write a group manifest that describes the whole system. This keeps design state durable and lets you validate the plan locally before touching the API.
+
+The example below is a generic two-list, seven-workflow group: continuous founder sourcing → self-serve paid booking → per-edition activation. The structure is template-shaped — fill in your group's identity and replace the workflows, lists, and states with your domain's vocabulary.
+
+```json
+{
+  "$schema": "https://schemas.agentled.app/group-manifest/v0.json",
+  "manifestVersion": "0.1.0",
+  "group": {
+    "id": "founder-showcase",
+    "name": "Founder Showcase Events",
+    "description": "Continuous founder sourcing → self-serve paid booking → per-edition investor activation.",
+    "goal": "Optimize for funnel conversion, not theme curation."
+  },
+  "operatingPrinciples": [
+    "Do not pick themes upfront — the first paid founder sets the edition theme and date.",
+    "Outreach is broad and continuous, not one batch per edition.",
+    "Investor outreach fires per edition, triggered by the first confirmed paid founder.",
+    "All customer-facing messages are approval-gated."
+  ],
+  "knowledgeLists": {
+    "founders": {
+      "description": "Founders sourced and tracked through the showcase funnel.",
+      "userKeyField": "linkedin_url",
+      "fields": [
+        { "name": "name", "type": "string" },
+        { "name": "linkedin_url", "type": "string" },
+        { "name": "domain", "type": "string" },
+        { "name": "email", "type": "string" },
+        { "name": "score", "type": "number" },
+        { "name": "edition_id", "type": "string" },
+        { "name": "status", "type": "string" }
+      ],
+      "producers": ["source-channel-a", "source-channel-b"],
+      "consumers": ["enrich-and-score", "send-founder-outreach"]
+    },
+    "editions": {
+      "description": "Showcase editions, each triggered by the first paid founder confirmation.",
+      "userKeyField": "edition_id",
+      "fields": [
+        { "name": "edition_id", "type": "string" },
+        { "name": "theme", "type": "string" },
+        { "name": "date", "type": "string" },
+        { "name": "confirmed_founders", "type": "number" },
+        { "name": "status", "type": "string" }
+      ],
+      "producers": ["process-bookings"],
+      "consumers": ["activate-investors", "edition-report"]
+    }
+  },
+  "stateMachines": {
+    "founders": {
+      "states": ["new", "enriched", "scored", "outreached", "booked", "confirmed", "rejected"],
+      "initialState": "new",
+      "transitions": [
+        { "from": "new",        "to": "enriched",   "trigger": "enrich-and-score" },
+        { "from": "enriched",   "to": "scored",     "trigger": "enrich-and-score" },
+        { "from": "scored",     "to": "outreached", "trigger": "send-founder-outreach" },
+        { "from": "outreached", "to": "booked",     "trigger": "process-bookings",    "description": "Stripe checkout initiated" },
+        { "from": "booked",     "to": "confirmed",  "trigger": "process-bookings",    "description": "Payment confirmed" },
+        { "from": "scored",     "to": "rejected",   "trigger": "enrich-and-score",    "description": "Score below threshold" }
+      ]
+    },
+    "editions": {
+      "states": ["forming", "active", "completed"],
+      "initialState": "forming",
+      "transitions": [
+        { "from": "forming", "to": "active",    "trigger": "process-bookings", "description": "First paid founder confirmed" },
+        { "from": "active",  "to": "completed", "trigger": "edition-report" }
+      ]
+    }
+  },
+  "workflows": [
+    {
+      "id": "source-channel-a",
+      "name": "Source — Channel A",
+      "purpose": "Find recently active founders from channel A and add to KG with status: new.",
+      "trigger": "schedule",
+      "schedule": "weekly",
+      "writes": ["founders"],
+      "creditEstimate": "5-10",
+      "status": "planned"
+    },
+    {
+      "id": "source-channel-b",
+      "name": "Source — Channel B",
+      "purpose": "Find founders from channel B and add to KG with status: new.",
+      "trigger": "schedule",
+      "schedule": "weekly",
+      "writes": ["founders"],
+      "creditEstimate": "5-10",
+      "status": "planned"
+    },
+    {
+      "id": "enrich-and-score",
+      "name": "Enrich & Score",
+      "purpose": "Enrich new founders via LinkedIn, find contact emails, score against ICP. Update status to scored or rejected.",
+      "trigger": "schedule",
+      "schedule": "daily",
+      "reads": ["founders"],
+      "writes": ["founders"],
+      "creditEstimate": "15-40",
+      "status": "planned"
+    },
+    {
+      "id": "send-founder-outreach",
+      "name": "Send Founder Outreach",
+      "purpose": "Draft personalized outreach to scored founders about the showcase opportunity. Send after approval.",
+      "trigger": "schedule",
+      "schedule": "weekly",
+      "reads": ["founders"],
+      "writes": ["founders"],
+      "approvalGates": ["draft-outreach-email"],
+      "creditEstimate": "5-15",
+      "status": "planned"
+    },
+    {
+      "id": "process-bookings",
+      "name": "Process Bookings",
+      "purpose": "Receive Stripe webhook or booking form submission, update founder status to booked/confirmed, and create/update edition when first founder confirms.",
+      "trigger": "webhook",
+      "reads": ["founders"],
+      "writes": ["founders", "editions"],
+      "creditEstimate": "2-5",
+      "status": "planned"
+    },
+    {
+      "id": "activate-investors",
+      "name": "Activate Investors",
+      "purpose": "When a new edition activates (first confirmed founder), reach out to investors for that edition's theme. Send after approval.",
+      "trigger": "schedule",
+      "schedule": "daily",
+      "reads": ["editions"],
+      "approvalGates": ["draft-investor-email"],
+      "creditEstimate": "5-15",
+      "status": "planned"
+    },
+    {
+      "id": "edition-report",
+      "name": "Edition Report",
+      "purpose": "Generate a post-event report for each completed edition: attendees, scores, conversion rate.",
+      "trigger": "schedule",
+      "reads": ["founders", "editions"],
+      "writes": ["editions"],
+      "creditEstimate": "5-10",
+      "status": "planned"
+    }
+  ],
+  "existingWorkflows": [
+    {
+      "workflowId": "<existing-source-workflow-id>",
+      "name": "Existing source workflow",
+      "action": "reuse",
+      "notes": "Already sources entities. Will be wired to write to the founders KG list with status: new."
+    }
+  ],
+  "integrations": {
+    "agentled":     { "required": true, "purpose": "LinkedIn enrichment" },
+    "hunter":       { "required": true, "purpose": "Email finding" },
+    "kg":           { "required": true, "purpose": "KG list reads/writes for founders and editions" },
+    "webhook":      { "required": true, "purpose": "Stripe booking webhooks" },
+    "gmail":        { "required": true, "purpose": "Outreach email sending" }
+  },
+  "workspaceSettings": [
+    "Outreach profile configured with sender name and connected Gmail account",
+    "Stripe webhook URL registered and pointing to process-bookings trigger"
+  ],
+  "buildOrder": [
+    "source-channel-a",
+    "source-channel-b",
+    "enrich-and-score",
+    "send-founder-outreach",
+    "process-bookings",
+    "activate-investors",
+    "edition-report"
+  ],
+  "openQuestions": [
+    {
+      "question": "What is the primary success metric: paid bookings per month, qualified entities contacted, or investor confirmations per edition?",
+      "impact": "Determines which KPI to surface in the edition report and which step outputs to track in analytics.",
+      "status": "open"
+    },
+    {
+      "question": "What is the system of record for bookings: Stripe webhook, a form provider, or a manual update?",
+      "impact": "Determines trigger type and input schema of process-bookings workflow.",
+      "status": "open"
+    },
+    {
+      "question": "How many entities constitute a full edition, and what is the minimum to activate downstream outreach?",
+      "impact": "Entry condition logic in activate-investors and edition creation in process-bookings.",
+      "status": "open"
+    }
+  ]
+}
+```
+
+## CLI commands
+
+```bash
+# Scaffold a starter manifest for your pattern
+agentled group-manifest scaffold event-driven-funnel --out workflow-groups/<group-slug>/group.manifest.json
+
+# Edit the manifest to match your actual workspace
+
+# Validate locally before touching the API
+agentled group-manifest validate workflow-groups/<group-slug>/group.manifest.json
+
+# One-shot workspace orientation (run at session start)
+agentled workspace inspect --json
+
+# Then build workflows in buildOrder sequence
+agentled wf create --pipeline '{"name":"Source — Channel A","goal":"..."}' --skip-validate
+# ... incremental step authoring ...
+agentled wf validate <wfId>
+agentled wf publish <wfId> --status live
+```
+
+## Design rules for event-driven groups
+
+1. **Status is the API between workflows.** One workflow writes a status; another reads it. Use `kg.upsert-rows` with `mergeStrategy: "merge"` so each workflow adds fields without wiping others.
+
+2. **Each workflow owns one stage.** Source workflows only source. Enrich workflows only enrich. Outreach workflows only outreach. Crossing stage boundaries in one workflow makes individual retries and auditing harder.
+
+3. **Build in build order.** A workflow that calls another via `call-workflow` must be built after the called workflow exists. The manifest `buildOrder[]` enforces this.
+
+4. **Existing workflows are first-class.** Document reused workflows in `existingWorkflows[]` so the manifest is the complete system description, not just the new parts.
+
+5. **Ask three goal questions before writing any step.** What is the primary goal? Where is the bottleneck? What is the system of record for the conversion event? The answers determine scope and trigger type.
+
+## Folder layout for a workflow group
+
+```
+workflow-groups/
+  <group-slug>/
+    group.manifest.json        # source of truth for the group design
+    design.md                  # build brief: goal, assumptions, risks, credit estimates
+    decisions/                 # one file per non-trivial design decision
+    worklog.md                 # append-only chronological log
+    workflows/                 # local pipeline JSON drafts before push
+      <workflow-id>.json
+```
+
+## Smoke-test plan
+
+After building each workflow in order, smoke-test before proceeding to the next:
+
+1. `source-*` — run once, confirm rows appear in KG with `status: "new"`
+2. `enrich-and-score` — run on a single row, confirm enrichment fields and `status: "scored"`
+3. `send-*-outreach` — trigger with one entity, approve draft, confirm email sends
+4. `process-bookings` — send a test webhook, confirm status update and edition row created
+5. `activate-*` — trigger with a forming edition, approve draft, confirm email
+6. `edition-report` — run on a completed test edition, confirm report structure
+
+## When not to use this pattern
+
+- One-shot, non-recurring operation with a fixed input → single workflow.
+- Child workflow called only via `call-workflow`, never directly → use Pattern 5 (child-workflow-contracts) instead.
+- Real-time event response required (sub-minute) → use an `app_event` trigger on a single workflow, not a KG polling loop.

package/scaffolds/extract-threshold-alert.json

@@ -33,9 +33,9 @@
         "configuration": {
           "contextKey": "thresholds",
           "fields": [
-            { "name": "metric_a_min", "label": "Metric A floor", "type": "Numeric" },
-            { "name": "metric_b_max", "label": "Metric B ceiling", "type": "Numeric" },
-            { "name": "metric_c_min", "label": "Metric C minimum", "type": "Numeric" }
+            { "name": "metric_a_min", "label": "Metric A floor", "type": "numeric" },
+            { "name": "metric_b_max", "label": "Metric B ceiling", "type": "numeric" },
+            { "name": "metric_c_min", "label": "Metric C minimum", "type": "numeric" }
           ]
         }
       }