@agentled/cli 0.1.5 → 0.4.3

package/patterns/v1/06-conditional-routing.md

@@ -0,0 +1,151 @@
+# 06 — Conditional routing: conditions that actually fire
+
+**Problem**: Entry conditions on workflow steps silently fail to apply — steps run unconditionally, or skip unconditionally — because the wrong field names are used to configure them.
+
+**Why it fails silently**: The wrong field names (`conditions` instead of `criteria`, `field` instead of `variable`) are not validation errors. The platform silently ignores unrecognized fields and applies no condition at all. The step runs every time, or skips every time, with no visible indication that the condition isn't being evaluated.
+
+---
+
+## The field name trap
+
+This is the most subtle silent failure in workflow configuration. Two pairs of field names look interchangeable but aren't:
+
+| Wrong | Correct |
+|---|---|
+| `conditions` | `criteria` |
+| `field` | `variable` |
+
+```yaml
+# Wrong: unrecognized field names — condition is silently ignored
+entryConditions:
+  onCriteriaFail: "skip"
+  conditions:                    # ← wrong: should be "criteria"
+    - field: "{{input.score}}"   # ← wrong: should be "variable"
+      operator: ">"
+      value: 70
+
+# Correct: recognized field names — condition is evaluated
+entryConditions:
+  onCriteriaFail: "skip"
+  criteria:                      # ← correct
+    - variable: "{{input.score}}"  # ← correct
+      operator: ">"
+      value: 70
+```
+
+The wrong version doesn't error. The step runs unconditionally, as if no condition existed.
+
+---
+
+## Anti-pattern
+
+```yaml
+# Wrong: routes HOT leads to Slack, but the condition is silently ignored
+- id: notify-hot-lead
+  type: app-action
+  app: slack
+  entryConditions:
+    onCriteriaFail: "skip"
+    conditions:                         # ← wrong field name
+      - field: "{{steps.score.category}}"  # ← wrong field name
+        operator: "=="
+        value: "HOT"
+  # Result: every lead triggers a Slack notification, including COLD and WARM
+```
+
+---
+
+## Correct pattern
+
+```yaml
+# Correct: HOT leads only
+- id: notify-hot-lead
+  type: app-action
+  app: slack
+  entryConditions:
+    onCriteriaFail: "skip"
+    conditionText: "Only notify for HOT leads"
+    criteria:                                    # ← correct
+      - variable: "{{steps.score.category}}"    # ← correct
+        operator: "=="
+        value: "HOT"
+```
+
+---
+
+## How to verify a condition is actually firing
+
+When a condition behaves unexpectedly (step always runs, or always skips), check:
+
+1. **Field names**: is it `criteria`/`variable`? Not `conditions`/`field`?
+2. **Variable path**: does `{{steps.score.category}}` actually resolve? Check the referenced step's output in execution logs.
+3. **Value type**: comparing a string `"70"` to a number `70` with `>` may not work as expected — check that types match.
+4. **Null safety**: `isNotNull` checks should come before value comparisons to avoid null reference issues.
+
+```yaml
+# Pattern: null-safe condition chain
+criteria:
+  - variable: "{{steps.enrich.company}}"
+    operator: "isNotNull"          # check existence first
+  - variable: "{{steps.score.total}}"
+    operator: ">"
+    value: 70                      # then compare value
+```
+
+---
+
+## The LLM-as-router anti-pattern
+
+Using an AI step to make a binary routing decision that a simple condition can handle:
+
+```yaml
+# Wrong: burning 10 credits to decide yes/no
+- id: decide-routing
+  type: ai-action
+  creditCost: 10
+  prompt: |
+    Given this lead's score of {{steps.score.value}}, should we send a Slack alert?
+    Score above 80 means yes. Below 80 means no.
+    Return: { shouldAlert: boolean }
+
+- id: send-alert
+  entryConditions:
+    criteria:
+      - variable: "{{steps.decide-routing.shouldAlert}}"
+        operator: "=="
+        value: true
+```
+
+```yaml
+# Correct: free condition, no LLM call needed
+- id: send-alert
+  entryConditions:
+    onCriteriaFail: "skip"
+    conditionText: "Only alert for high-score leads"
+    criteria:
+      - variable: "{{steps.score.value}}"
+        operator: ">"
+        value: 80
+```
+
+Use AI for decisions that require reasoning, judgment, or context. Use conditions for decisions that follow a deterministic rule.
+
+---
+
+## `onCriteriaFail` reference
+
+| Value | Behavior |
+|---|---|
+| `"skip"` | Skip this step, continue to the next |
+| `"stop"` | Stop the entire execution |
+| `"wait"` | Block this step until criteria are met (used for loop/group completion) |
+
+Common mistakes:
+- Using `"stop"` when you mean `"skip"` — stops the whole workflow instead of just bypassing one step
+- Using `"skip"` when you mean `"wait"` — the step runs immediately with incomplete data instead of waiting for a loop to finish
+
+---
+
+## One-line rule
+
+> Always use `criteria` (not `conditions`) and `variable` (not `field`) in entry conditions — wrong field names are silently ignored and the condition never evaluates.

package/patterns/v1/07-error-handling.md

@@ -0,0 +1,157 @@
+# 07 — Error handling: skip vs stop vs wait
+
+**Problem**: Developers use the same error behavior (`stop` or `skip`) everywhere, causing workflows to either halt on recoverable errors or continue silently with missing data.
+
+**Why it fails silently**: `skip` silently passes empty/null data to downstream steps, which then produce wrong outputs with no error. `stop` halts workflows on optional steps that should have been bypassed. Neither produces a visible failure at the wrong step — the failure surfaces later, in a confusing place.
+
+---
+
+## The three behaviors
+
+Every entry condition has an `onCriteriaFail` setting that determines what happens when the condition isn't met:
+
+| Value | What it does | When to use |
+|---|---|---|
+| `skip` | Skip this step, pass `null`/empty to downstream steps, continue execution | Optional step — workflow is valid without it |
+| `stop` | Halt the entire execution immediately | Hard prerequisite — nothing downstream is meaningful without this step |
+| `wait` | Block this step until criteria become true | Async dependency — waiting for a loop or parallel group to finish |
+
+---
+
+## Anti-pattern: stop everywhere
+
+```yaml
+# Wrong: using stop for an optional enrichment step
+- id: enrich-linkedin
+  type: app-action
+  entryConditions:
+    onCriteriaFail: "stop"       # ← wrong: this is optional
+    criteria:
+      - variable: "{{input.linkedinUrl}}"
+        operator: "isNotNull"
+# If linkedinUrl is missing: entire workflow halts.
+# But the workflow could run fine without LinkedIn data.
+```
+
+```yaml
+# Correct: optional enrichment step uses skip
+- id: enrich-linkedin
+  type: app-action
+  entryConditions:
+    onCriteriaFail: "skip"       # ← correct: skip if no URL
+    conditionText: "Skip LinkedIn enrichment if no URL provided"
+    criteria:
+      - variable: "{{input.linkedinUrl}}"
+        operator: "isNotNull"
+```
+
+---
+
+## Anti-pattern: skip for hard prerequisites
+
+```yaml
+# Wrong: using skip for required input validation
+- id: validate-required-fields
+  type: code
+  entryConditions:
+    onCriteriaFail: "skip"       # ← wrong: nothing downstream works without this
+    criteria:
+      - variable: "{{input.companyDomain}}"
+        operator: "isNotNull"
+# If domain is missing: validation is skipped.
+# Next step tries to enrich with null domain.
+# Enrichment fails with a confusing error 3 steps later.
+```
+
+```yaml
+# Correct: hard prerequisite uses stop
+- id: validate-required-fields
+  type: code
+  entryConditions:
+    onCriteriaFail: "stop"       # ← correct: stop early with a clear failure
+    conditionText: "Company domain is required"
+    criteria:
+      - variable: "{{input.companyDomain}}"
+        operator: "isNotNull"
+```
+
+Fail fast. A clear stop at the prerequisite is better than a confusing error 5 steps later.
+
+---
+
+## `wait`: blocking on async completion
+
+`wait` is for a specific use case: blocking a step until an async process finishes. The two common cases are loop completion and parallel group completion.
+
+```yaml
+# Wait for a loop to finish before consuming its output
+- id: aggregate-results
+  type: ai-action
+  entryConditions:
+    onCriteriaFail: "wait"
+    conditionText: "Wait for all enrichment loop iterations to complete"
+    criteria:
+      - type: loop_completion
+        stepId: enrich-loop
+        operator: "=="
+        value: true
+  prompt: "Summarize these enriched companies: {{steps.enrich-loop.outputs}}"
+```
+
+`wait` is not a general-purpose retry mechanism. It's specifically for dependency ordering in async workflows.
+
+---
+
+## Decision guide
+
+Ask these questions in order:
+
+**1. Is this step required for the workflow to produce a valid output?**
+- Yes → `stop`
+- No → continue to question 2
+
+**2. Is this step waiting for another step/loop/group to finish?**
+- Yes → `wait`
+- No → `skip`
+
+Examples:
+
+| Step | Required? | Async wait? | Use |
+|---|---|---|---|
+| "Validate required domain field" | Yes | No | `stop` |
+| "Enrich LinkedIn (optional)" | No | No | `skip` |
+| "Send Slack alert (if webhook configured)" | No | No | `skip` |
+| "Aggregate loop results" | Yes | Yes (loop) | `wait` |
+| "Score company (ICP match required)" | Yes | No | `stop` |
+| "Add CRM note (nice to have)" | No | No | `skip` |
+
+---
+
+## Handling downstream null data after skip
+
+When a step is skipped, its outputs are `null` or empty. Downstream steps that reference those outputs must handle nulls gracefully:
+
+```yaml
+# Pattern: null-safe reference in AI prompt
+prompt: |
+  Company: {{steps.enrich.company.name | default: "Unknown"}}
+  LinkedIn headline: {{steps.enrich-linkedin.headline | default: "Not available"}}
+  Score this company based on what's available.
+```
+
+Or use a code step to normalize before passing to downstream AI steps:
+
+```javascript
+// Code step: normalize potentially-null enrichment data
+return {
+  name: input.enrichData?.name ?? input.rawInput.companyName,
+  industry: input.enrichData?.industry ?? "Unknown",
+  employees: input.enrichData?.employees ?? null,
+};
+```
+
+---
+
+## One-line rule
+
+> Use `skip` for optional steps, `stop` for hard prerequisites, and `wait` for async dependencies — and always handle `null` outputs from skipped steps in downstream steps.

package/patterns/v1/08-composed-email-approval.md

@@ -0,0 +1,130 @@
+# 08 — Composed email with approval gate: outreach that ships safely
+
+**Problem**: Agents build outreach by chaining a "draft email" AI step with a separate "gmail send" app action. This skips the user-review step, sends unreviewed drafts, and can't display the email in the pending-approval UI.
+
+**Why it fails silently**: A raw draft-then-send pipeline has no concept of "email" as a first-class artifact. The orchestrator's approval UI won't render a preview, the `schedule-email` action can't fire, and there's no audit trail of what was sent to whom. The workflow looks correct at authoring time and may even work in testing — until a real recipient gets an unreviewed draft.
+
+---
+
+## The composed-email shape
+
+An email step is a specialized `aiAction` with four coupled pieces:
+
+1. **Prompt type**: `pipelineStepPrompt.type: "email"` — tells the orchestrator this is an email step (not a generic AI step).
+2. **Renderer**: `renderer: { type: "Email", config: { fromContextKey: "outreachProfile" } }` — tells the UI to render the result as an email preview, pulling sender info from a context input page.
+3. **Integrations declaration**: declares that the workflow needs a connected email account (Gmail or Outlook).
+4. **Approval + send action**: `onApproval: { action: "schedule-email" }` + `next.conditions.approvalRequired: true` — the step waits for user approval, then the `schedule-email` action actually sends the email.
+
+All four must be present. Omit any one and the step silently degrades: no preview, no approval gate, or no send.
+
+## Required input page: outreachProfile
+
+Sender identity lives on a workflow-level `inputPages` entry with `contextKey: "outreachProfile"`. Without this page, the `{{context.outreachProfile.fromEmail}}` template resolves to empty and the email has no sender.
+
+```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 (optional)", "type": "text" }
+    ]
+  }
+}
+```
+
+## Full composed-email step (copy-paste)
+
+```json
+{
+  "id": "send-outreach-email",
+  "type": "aiAction",
+  "name": "Send Outreach Email",
+  "pipelineStepPrompt": {
+    "type": "email",
+    "template": "Draft a personalized email to {{steps.enrich.contact.fullName}} at {{steps.enrich.company.name}} introducing our offering. Keep it warm, concise, and specific to their role.",
+    "responseStructure": {
+      "email": {
+        "from": "{{context.outreachProfile.fromEmail}}",
+        "to": "{{steps.enrich.contact.email}}",
+        "subject": "",
+        "body": "",
+        "bodyType": "html"
+      }
+    }
+  },
+  "renderer": {
+    "type": "Email",
+    "config": { "fromContextKey": "outreachProfile" }
+  },
+  "integrations": [
+    {
+      "type": "oneOf",
+      "label": "Email",
+      "connectorType": "email",
+      "options": [
+        { "name": "Gmail", "url": "https://gmail.com", "isUserAccountConnectionRequired": true },
+        { "name": "Outlook", "url": "https://outlook.com", "isUserAccountConnectionRequired": true }
+      ],
+      "selectionHint": "preferConnected"
+    }
+  ],
+  "onApproval": {
+    "executedText": "Email sent by {{name}} at {{date}}",
+    "failedText": "Email failed to send.",
+    "action": "schedule-email"
+  },
+  "creditCost": 5,
+  "next": { "stepId": "done", "conditions": { "approvalRequired": true } }
+}
+```
+
+## Anti-patterns
+
+**Draft + Gmail send (no approval):**
+
+```
+❌ draft-email (aiAction) → gmail.send-email (appAction) → done
+```
+
+No preview, no user approval, and the drafted body is written as a plain string instead of the structured `email` object — Gmail's send-email action expects specific fields (`to`, `subject`, `html`) that the draft prompt has no way to produce reliably.
+
+**Missing `pipelineStepPrompt.type: "email"`:**
+
+```yaml
+pipelineStepPrompt:
+  template: "..."
+  responseStructure:
+    email: { from, to, subject, body, bodyType }
+# ❌ No `type: "email"` — the renderer falls back to a generic JSON view,
+# and the orchestrator treats this as a regular aiAction (no schedule-email).
+```
+
+**Email body as plain text when `bodyType: "html"`:**
+
+Email clients render HTML bodies literally if the wrapping element is missing. Always generate email-safe HTML (`<p>`, `<br>`, `<a>`, `<strong>` — no CSS blocks, no `<script>`). Don't use markdown — the approval UI won't convert it.
+
+**No `outreachProfile` input page:**
+
+`{{context.outreachProfile.fromEmail}}` resolves to an empty string. The email has no sender. It may still send (from the default connected account) but you lose per-workflow sender control.
+
+## Checklist
+
+Before wiring a composed-email step into a workflow:
+
+- [ ] `context.inputPages[]` contains the `outreachProfile` page (pattern above)
+- [ ] `pipelineStepPrompt.type: "email"` is set
+- [ ] `renderer: { type: "Email", config: { fromContextKey: "outreachProfile" } }` is present
+- [ ] `integrations[]` declares the email connector (Gmail / Outlook)
+- [ ] `onApproval.action: "schedule-email"` is set
+- [ ] `next.conditions.approvalRequired: true` on the outgoing edge
+- [ ] Recipient and subject are derived from prior step output, not hardcoded
+
+## When to use a generic approval gate instead
+
+For non-email approvals (sending a Slack post, firing a webhook), use a plain `aiAction` + `next.conditions.approvalRequired: true` without the email renderer. The approval gate is a general-purpose feature; the email shape is only required when the approved artifact is an email that needs to be sent through the user's connected mailbox.

package/patterns/v1/09-reports-and-knowledge-storage.md

@@ -0,0 +1,166 @@
+# 09 — Reports, sharing, and knowledge-graph storage: closing the loop
+
+**Problem**: Agents produce analysis as free-form prose in AI step output, then either never display it or drop it into a raw JSON view. Results aren't shareable with stakeholders, aren't comparable across runs, and don't feed back into the Knowledge Graph for trend analysis or future scoring calibration.
+
+**Why it fails silently**: Without a `renderer`, an AI step's structured output is unreadable in the workspace UI. Without a `share` step, the output has no URL that can be sent to a stakeholder. Without a `knowledgeSync` step, each run's data is discarded — the second run can't learn from the first, and KPIs have no history to trend against.
+
+---
+
+## The three-part closing loop
+
+```
+... upstream steps → AI report step (with Config renderer)
+                   → [optional] share step (public URL)
+                   → [optional] composed email step (delivery)
+                   → knowledgeSync (persist to KG for trending)
+                   → milestone
+```
+
+The three pieces are independent and optional, but they compound. A report with a renderer is readable. A report with a renderer + share step is forwardable. A report with all three + knowledgeSync is how KPI dashboards actually get built.
+
+## 1. Report AI step with Config renderer
+
+The Config renderer turns structured AI output into a KPI dashboard view. Key blocks: `kpiRow`, `markdown`, `table`, `signalList`.
+
+```json
+{
+  "id": "generate-report",
+  "type": "aiAction",
+  "name": "Generate Report",
+  "pipelineStepPrompt": {
+    "template": "Analyze the data and produce a structured report.\n\nData: {{steps.evaluate.items}}",
+    "responseStructure": {
+      "summary": "string — executive summary",
+      "kpis": "object { total: number, qualified: number, avgScore: number }",
+      "items": "array of { name, score, decision }",
+      "insights": "array of strings"
+    }
+  },
+  "renderer": {
+    "type": "Config",
+    "config": {
+      "layout": {
+        "title": "Run Report",
+        "blocks": [
+          { "blockType": "kpiRow", "kpis": [
+            { "label": "Total", "valuePath": "kpis.total", "icon": "Hash" },
+            { "label": "Qualified", "valuePath": "kpis.qualified", "icon": "CheckCircle" },
+            { "label": "Avg Score", "valuePath": "kpis.avgScore", "format": "score" }
+          ]},
+          { "blockType": "markdown", "contentPath": "summary" },
+          { "blockType": "table", "arrayPath": "items", "searchable": true, "columns": [
+            { "header": "Name", "field": "name" },
+            { "header": "Score", "field": "score", "display": "score", "sortable": true },
+            { "header": "Decision", "field": "decision", "display": "badge" }
+          ]},
+          { "blockType": "signalList", "title": "Insights", "arrayPath": "insights", "variant": "signal" }
+        ]
+      }
+    }
+  },
+  "creditCost": 10,
+  "next": { "stepId": "share-report" }
+}
+```
+
+**Rule**: the `responseStructure` keys must match the renderer's `valuePath`/`arrayPath`/`contentPath` references. Drift between the two silently produces empty KPI tiles and blank tables.
+
+## 2. Share step for a public URL
+
+```json
+{
+  "id": "share-report",
+  "type": "share",
+  "name": "Create Public Report Link",
+  "shareConfig": {
+    "outputSteps": ["generate-report"],
+    "expiresInDays": 30,
+    "visibility": "public"
+  },
+  "next": { "stepId": "send-report-email" }
+}
+```
+
+Outputs `{ shareId, shareUrl, expiresAt }`. Downstream steps use `{{steps.share-report.shareUrl}}` to reference the public URL (e.g., in an email body).
+
+**When to add a share step**:
+
+- Anyone outside the workspace needs to see the report.
+- The report should remain accessible after the execution's detail page expires.
+- The workflow delivers the report via email and the body should link to the full report.
+
+**When to skip it**: internal-only dashboards where viewers already have workspace access.
+
+## 3. Knowledge-graph storage for trending
+
+Without this, each run's data vanishes. With it, you can:
+
+- Compare "today's MRR" against last month's.
+- Calibrate future AI scoring on past outcomes (see `kg.retrieve-scoring-memory`).
+- Build a timeline view of any metric.
+
+```json
+{
+  "id": "store-history",
+  "type": "knowledgeSync",
+  "name": "Store to KPI History",
+  "knowledgeSync": {
+    "source": { "stepId": "generate-report" },
+    "listKey": "kpi_history",
+    "fieldMapping": {
+      "mrr": "mrr",
+      "burn": "burn",
+      "runway_months": "runway_months",
+      "executedAt": "executedAt"
+    }
+  },
+  "next": { "stepId": "done" }
+}
+```
+
+If you're inside a loop (scoring many items per run), set `source.resultsPath: "items"` so each loop iteration produces one KG row.
+
+## Anti-patterns
+
+**AI step with no renderer:**
+
+```yaml
+type: aiAction
+responseStructure:
+  summary: string
+  kpis: { total, avgScore }
+# ❌ No renderer — the workspace UI shows raw JSON. Nobody reads it.
+```
+
+**Share step without `outputSteps`:**
+
+```yaml
+type: share
+shareConfig:
+  visibility: public
+  # ❌ Missing outputSteps — share URL renders nothing
+```
+
+**`knowledgeSync` without a clear schema:**
+
+If `listKey` doesn't already exist, the KG creates an implicit schema from the first write. Subsequent writes with different field shapes fail to index. For trending, pre-create the list with a typed schema.
+
+**Reusing `fieldMapping` values with source-side renames:**
+
+`fieldMapping` keys are source field names (from the prior step's output), values are target field names (in the KG). Flipping them silently stores the wrong data.
+
+```yaml
+# ✅ Correct: source → target
+fieldMapping:
+  mrr: monthly_revenue          # steps.extract.mrr → row.monthly_revenue
+  burn: monthly_expenses
+```
+
+## Checklist for any "report" workflow
+
+- [ ] `responseStructure` keys match every renderer `valuePath` / `arrayPath` / `contentPath`
+- [ ] Renderer `blocks` cover at least one KPI + one tabular view
+- [ ] Share step exists if report is forwardable to non-workspace users
+- [ ] If delivered via email, the email template embeds `{{steps.share.shareUrl}}`
+- [ ] `knowledgeSync` persists to a list with a typed schema (not implicit)
+- [ ] `executedAt` (or a similar timestamp) is stored so rows can be trended

package/scaffolds/README.md

@@ -0,0 +1,61 @@
+# CLI scaffolds
+
+Each `*.json` file in this directory is a **preflight-clean pipeline skeleton**
+keyed to one of the patterns in `agentic-ops/patterns/v1/` (canonical) or
+`packages/cli/patterns/v1/` (byte-identical mirror).
+
+Scaffolds are **pattern shapes, not domain templates.** The goal is to give
+an agent (or human) a known-good starting point for a structural shape —
+loop over a KG list, composed email with approval, conditional alert on
+threshold, etc. — not to ship templates for every possible business use case.
+
+## Contract
+
+Every bundled scaffold:
+
+1. Passes `agentled workflows validate --file <scaffold>` with zero errors
+   and zero warnings.
+2. Has a clear `name` and `goal` field that describes the pattern shape.
+3. References the matching agentic-ops pattern number(s) in its `description`.
+4. Uses domain-agnostic placeholder names (`candidate`, `metric_a`,
+   `entity_id`) — not specific verticals.
+
+## Catalog
+
+| Slug | Pattern(s) | Shape |
+|------|-----------|-------|
+| `minimal` | — | trigger → milestone (smallest valid pipeline) |
+| `email-polling-dedup` | 02 + 13 | schedule → fetch emails (label dedup) → loop process → add label |
+| `lead-scoring-kg` | 04 + 09 | trigger → kg.read-list → AI scoring loop → knowledgeSync → report |
+| `list-match-email` | 08 | trigger → kg.read-list → AI match top candidates → composed email (approval gate) → knowledgeSync |
+| `extract-threshold-alert` | 06 + 09 | trigger → AI extract → threshold check (code) → external update → conditional Slack alert → knowledgeSync |
+
+## Bring your own scaffolds
+
+The bundled set is deliberately small. Workspaces, teams, or customers who
+have recurring workflow shapes should maintain their own scaffold library
+outside this CLI release cycle:
+
+1. Drop JSON files in `~/.agentled/scaffolds/` or set
+   `AGENTLED_SCAFFOLDS_DIR=/path/to/your/scaffolds`.
+2. Run `agentled workflows scaffold --list` — local scaffolds appear with
+   a `[local]` tag next to their name.
+3. Local slugs **shadow bundled ones** with the same name, so a team can
+   override `list-match-email.json` with a locally-tuned version without
+   forking the CLI.
+
+Any JSON in those directories must also pass `workflows validate --file`.
+The CLI doesn't gate this at load time — but a scaffold that fails preflight
+will waste an operator's time, which is exactly what the scaffold set is
+meant to prevent.
+
+## Editing the bundled set
+
+The bundled scaffolds are meant to stay small and pattern-focused. If you
+want to propose a new one:
+
+- It must map to an existing agentic-ops pattern (or come with a new pattern).
+- It must be domain-agnostic — name fields `candidate` / `metric_a` /
+  `entity_id`, not `mentor` / `mrr` / `companyId`.
+- The `description` must state the pattern number it demonstrates.
+- Commit both the scaffold and a preflight test verifying it passes.