opencode-skills-collection 4.0.7 → 4.0.9

package/bundled-skills/n8n-multi-instance/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: n8n-multi-instance
+description: Select, verify, and safely switch n8n MCP instances across production, staging, teams, or clients, especially before credential writes.
+risk: critical
+source: https://github.com/czlonkowski/n8n-skills/tree/main/skills/n8n-multi-instance
+source_repo: czlonkowski/n8n-skills
+source_type: community
+date_added: "2026-07-21"
+author: Romuald Czlonkowski
+license: MIT
+license_source: https://github.com/czlonkowski/n8n-skills/blob/main/LICENSE
+---
+
+# Working with multiple n8n instances over MCP
+
+## When to Use
+
+Use this skill whenever one MCP connection can target multiple n8n instances, before instance-specific reads or writes, and whenever results suggest the session is aimed at the wrong environment.
+
+Resolve the target by stable instance ID, verify it with a read-only health check, and state the resolved environment before mutations. Require explicit confirmation for credential create/update/delete operations, never print secret values, and stop on ambiguous targeting rather than guessing.
+
+When the `n8n_instances` tool is available, the user has **multi-instance mode** on: one MCP
+connection can reach several n8n instances (e.g. `prod`, `staging`, or one per client/team).
+Every other n8n tool (`n8n_get_workflow`, `n8n_list_workflows`, `n8n_update_partial_workflow`,
+`n8n_manage_datatable`, `n8n_manage_credentials`, `n8n_executions`, `n8n_test_workflow`, …) runs
+against **whichever instance this session is currently targeting**. There is no per-call instance
+argument: you change the target only by switching. Target the wrong instance and a read returns the
+wrong data and a write lands in the wrong place — usually with **no error** (the one exception is an
+ambiguous credential write, which fails closed; see below). So target deliberately.
+
+If the `n8n_instances` tool is **not** present, the account is single-instance: ignore this skill
+and use the n8n tools directly.
+
+## Golden rules
+
+Six rules. Each prevents a class of silent misroute.
+
+1. **Discover first.** Call `n8n_instances({mode:"list"})` before acting so you know the instance
+   names and which one is `current`.
+2. **Switch by name to your target** before doing work on a non-default instance:
+   `n8n_instances({mode:"switch", name:"<instance name>"})`. The match is case-insensitive.
+3. **Switch in its own turn.** Never put a `switch` and a dependent operation in the **same
+   parallel tool-call batch**. Calls in one batch have no guaranteed order, so the dependent call
+   can be resolved against the *previous* instance before the switch's session state is visible.
+   Switch, let it return, *then* operate.
+4. **Verify before high-stakes ops.** Immediately before creating/updating/deleting **credentials**
+   (and before destructive workflow edits), confirm `current` is the instance you intend — primary
+   check is `n8n_instances({mode:"list"})`. The system fail-closes only the *ambiguous* credential
+   case (rule 6); an explicit switch to the **wrong** instance still writes there silently, so this
+   check is on you.
+5. **An unexpected `NOT_FOUND` is almost always a wrong-instance misroute, not a deletion.** Don't
+   recreate the object. Re-check the current instance and retry (see Recovery).
+6. **On `INSTANCE_AMBIGUOUS`, switch on *this* session, then retry.** The system is refusing to
+   write a secret because this session never picked a target itself. Comply — run `switch` here to
+   confirm the instance, then retry the write. Don't work around it or retry blindly.
+
+## Core workflow
+
+```
+1. n8n_instances({mode:"list"})                      # see available[] + current + default
+2. n8n_instances({mode:"switch", name:"prod"})       # bind THIS session to "prod"
+   → returns { previous, current }; confirm current.name == "prod"
+3. (do your work) n8n_list_workflows / n8n_get_workflow / n8n_manage_datatable / ...
+4. Before a credential write or a delete:
+   n8n_instances({mode:"list"})  → re-confirm current, THEN n8n_manage_credentials({action:"create", ...})
+```
+
+To move to another instance, just `switch` again. The whole session follows the switch.
+
+## The `n8n_instances` tool
+
+Two modes (`mode` is required and enum-validated):
+
+- `{mode:"list"}` → `{ current, default, available }`, no side effects.
+  - `current` and `default` are each one instance `{ id, name, url, isDefault }` (or `null`).
+  - `available` is every instance, each with an extra `isCurrent` boolean. Match by **`name`**;
+    never hard-code `id`.
+- `{mode:"switch", name:"<name>"}` → `{ previous, current }`, and binds this session to the named
+  instance. `name` is case-insensitive.
+
+### Error envelope (from the `n8n_instances` tool)
+
+Every error returns `{ error: "<CODE>", message, … }`. The ones you'll actually hit:
+
+| Code | When | What to do |
+|---|---|---|
+| `UNKNOWN_INSTANCE` | `name` matches no instance | Pick a name from the `available` list in the error payload and retry. |
+| `NAME_REQUIRED` | `switch` with no `name` | Re-call with a `name` (the error lists the valid ones in `available`). |
+| `MULTI_INSTANCE_DISABLED` | multi-instance mode is off | There's nothing to switch; use the n8n tools directly. The user can enable it at the n8n-mcp dashboard. |
+| `NO_SESSION` | the request has **neither** an MCP session id **nor** a credential id | A selection has nowhere to land. Reconnect / initialize a session, then switch. |
+| `UNKNOWN_MODE` | `mode` wasn't `list`/`switch` | Use `list` or `switch`. |
+| `INVALID_CONTEXT` | server-side metadata missing | A server bug, not your input — report it. |
+
+> Instance names can never be `default`, `current`, `list`, or `switch` (reserved), so you'll never
+> see an instance literally named after a mode or field.
+
+### `INSTANCE_AMBIGUOUS` (from the credential-write path, not the tool)
+
+A separate, higher-stakes error. It is **not** returned by `n8n_instances` — it's returned by the
+server when you call `n8n_manage_credentials` to **create/update/delete** a credential and the target
+instance is ambiguous: this session never switched on its own but inherited a switch made elsewhere
+(a fan-out / reconnect), pointing at a **non-default** instance. Rather than risk writing a secret to
+the wrong instance, the server **blocks the write** (it never reaches n8n, no quota is charged) and
+returns:
+
+```json
+{
+  "error": "INSTANCE_AMBIGUOUS",
+  "message": "… the session issuing this request never switched there itself … Re-run n8n_instances({mode:\"switch\", name:\"…\"}) on this session to confirm the target …",
+  "lastSelected": { "id": "…", "name": "…" },
+  "default":      { "id": "…", "name": "…" }
+}
+```
+
+**Fix:** decide which instance you actually want (`lastSelected` is the inherited switch, `default`
+is the account default), run `n8n_instances({mode:"switch", name:"…"})` on **this** session, then
+retry the write. See rule 6.
+
+## How targeting behaves (mental model)
+
+- A `switch` **binds this session** to the chosen instance. The binding **persists for the rest of
+  the session and survives reconnects, idle, and backend deploys** (~24h, the MCP session lifetime)
+  — you should not need to re-switch before every call.
+- Other sessions / terminals are **independent**: switching here does not move them.
+- One session targets **one instance at a time**. There is no per-call instance argument; you
+  change the target only via `switch`.
+- **Reads and non-credential writes** route to the currently-selected instance, silently — a
+  misroute produces wrong data or a `NOT_FOUND`, not an error.
+- **Credential writes are the one guarded case.** They route the same way, except the server
+  fail-closes the *ambiguous* state (a session that never switched, recovered onto a non-default
+  instance) with `INSTANCE_AMBIGUOUS`. This is a safety net, not a substitute for rule 4: an
+  explicit switch to the wrong instance still writes there.
+- **If your selected instance is deleted** (the user removes it mid-session), the next call silently
+  falls back to your **default** instance — no error. So default's data appearing where you expected
+  another instance's can look like "my data vanished." Re-list to see where you are.
+
+## Recovery playbook
+
+| Symptom | What it usually means | Do this |
+|---|---|---|
+| `INSTANCE_AMBIGUOUS` on a credential create/update/delete | This session never switched itself; the system won't guess which instance to write the secret to | Run `n8n_instances({mode:"switch", name:"<target>"})` on this session (the error names `lastSelected` and `default` — pick the one you want), then retry the write. Never retry blindly. |
+| `NOT_FOUND` for a workflow/datatable/credential you **know exists** | You're pointed at the wrong instance — **not** that it was deleted | `n8n_instances({mode:"list"})` → check `current`. If it's not your target, `switch` and retry. **Do not recreate the object.** |
+| A read returns **empty or unfamiliar** data | Wrong-instance read, or a silent fallback to `default` after your instance was deleted | `n8n_instances({mode:"list"})`, confirm `current`, switch if needed, re-read before drawing conclusions. |
+| `UNKNOWN_INSTANCE` on `switch` | The `name` is wrong (typo, or you guessed) | Read the `available` names in the error and switch to one of those. Names are case-insensitive. |
+| `n8n_health_check` reports an `instanceName` you didn't expect | This session is on a different instance than you think | `switch` to the intended instance, then proceed. |
+| Repeated misroutes within one turn | You batched a `switch` with dependent work | Split them: `switch` alone, await the result, then operate one logical step at a time. |
+
+After any recovery switch, sanity-check with `n8n_instances({mode:"list"})` (read `current`) as the
+primary signal. `n8n_health_check` also returns the resolved instance under `details.instanceName`,
+but it can be absent on some paths (legacy/chat), so treat it as a secondary confirmation.
+
+## Credential operations (highest stakes)
+
+Credentials hold live secrets, and a misrouted credential write puts a secret on the **wrong
+instance**. The server protects the **ambiguous** case automatically — if this session never picked
+a target and inherited a switch to a non-default instance, the write fails closed with
+`INSTANCE_AMBIGUOUS` (rule 6) and never reaches n8n. But that net is narrow: a credential write on a
+session that **did** switch goes through to whatever instance it switched to, with no second
+guess. So:
+
+- **Verify `current` immediately before** `n8n_manage_credentials` create/update/delete — call
+  `n8n_instances({mode:"list"})` in the same short sequence, not 10 steps earlier where a later
+  switch could have moved you.
+- **On `INSTANCE_AMBIGUOUS`**, switch on this session to confirm the target, then retry — don't
+  work around it.
+- Credential **reads** (`action:"list"`/`"get"`/`"getSchema"`) are not gated and don't write a
+  secret, but a read off the wrong instance returns the wrong schema or list — so still verify
+  `current` if the result looks wrong.
+- For the `n8n_manage_credentials` tool itself (CRUD shapes, `getSchema` discovery, never inlining
+  secrets into text fields), see `n8n-mcp-tools-expert`.
+
+## Common multi-instance task: copy something between instances
+
+To recreate a credential or workflow from instance A on instance B:
+
+```
+1. switch → A;  read the source (n8n_manage_credentials get / n8n_get_workflow)
+2. switch → B   (its own call — never batched with the create below)
+3. n8n_instances({mode:"list"})  → confirm current == B
+4. create on B  (n8n_manage_credentials create / n8n_create_workflow)
+```
+
+Do each instance's steps in its own turn; never overlap `switch → B` with the create-on-B call
+(rule 3), and switch explicitly on this session before the credential write so it isn't ambiguous
+(rules 4 and 6).
+
+## Quick reference
+
+- See instances + where you are: `n8n_instances({mode:"list"})` → `{ current, default, available }`
+- Change target: `n8n_instances({mode:"switch", name:"<name>"})` — its own turn, then operate
+- Confirm target: `current` from `list` (primary); `details.instanceName` from `n8n_health_check` (secondary, may be absent)
+- `UNKNOWN_INSTANCE` → switch to a name from the error's `available` list, then retry
+- `INSTANCE_AMBIGUOUS` (credential write) → `switch` on this session to confirm the target, then retry
+- Unexpected `NOT_FOUND` → verify the instance, switch, retry; **do not recreate**
+- Before credential writes → re-`list`, confirm `current`, then write (the fail-close only covers the ambiguous case)
+
+## Integration with other skills
+
+- **n8n-mcp-tools-expert** — owns `n8n_manage_credentials` (CRUD + `getSchema`) and the rule that
+  secrets go through the credential system, never text fields. This skill adds the "which instance?"
+  layer on top.
+- **using-n8n-mcp-skills** — the router; consult it for which skill owns a given build step.
+
+## Limitations
+
+- Instance discovery and switching depend on the connected n8n MCP server exposing multi-instance tools.
+- A successful switch does not authorize mutations or prove that the selected environment is appropriate for the task.
+- Unexpected empty or missing data may have causes other than misrouting; verify before changing targets.

package/bundled-skills/n8n-node-configuration/references/NODE_FAMILY_GOTCHAS.md

@@ -0,0 +1,241 @@
+# Node Family Gotchas
+
+Silent-failure traps grouped by node family. These don't show up in `validate_node` or `validate_workflow` — the workflow validates clean, runs without error, and quietly does the wrong thing. `get_node` shows you the fields exist; it doesn't tell you what happens when you leave them off. This file covers the consequence.
+
+Each entry: **symptom** (what you see at runtime), **cause** (why), **fix** (in n8n-mcp / JSON terms).
+
+## Contents
+
+- [Switch — dropped items on the unmatched path](#switch)
+- [Merge — wrong input count and the 1-vs-0 index trap](#merge)
+- [Database (Postgres / MySQL / Supabase) — SQL injection, transactions, no-rows](#database)
+- [Slack — Block Kit, threads, operation values](#slack)
+- [Webhook / Respond to Webhook — response codes and modes](#webhook--respond-to-webhook)
+- [Schedule Trigger — timezone, cron fields, missed runs](#schedule-trigger)
+
+---
+
+## Switch
+
+**Symptom:** items that match none of the rules vanish. No error, no warning — the workflow just loses data on the unmatched path.
+
+**Cause:** without a fallback output, the Switch has nowhere to send unmatched items, so it discards them.
+
+**Fix:** set `options.fallbackOutput: "extra"` and give it a name with `options.renameFallbackOutput`. While you're there, name every rule output too — unnamed `0 / 1 / 2` outputs are unreadable a month later, and a failure on "output 2" tells the operator nothing.
+
+```json
+{
+  "parameters": {
+    "mode": "rules",
+    "rules": {
+      "values": [
+        { "outputKey": "Paid", "renameOutput": true, "conditions": { "...": "..." } },
+        { "outputKey": "Refunded", "renameOutput": true, "conditions": { "...": "..." } }
+      ]
+    },
+    "options": {
+      "fallbackOutput": "extra",
+      "renameFallbackOutput": "Unexpected"
+    }
+  }
+}
+```
+
+Apply surgically with `patchNodeField` on `parameters.options.fallbackOutput`, or with `updateNode` for the full `options` object. After wiring, confirm the fallback branch goes somewhere real (a log, an alert, a NoOp) — an enabled fallback that connects to nothing drops items just the same.
+
+---
+
+## Merge
+
+Two traps, both silent. They live on different Merge modes — `numberOfInputs` on Append/Combine, `useDataOfInput` on Choose Branch — so in practice you hit one or the other, not both.
+
+### Trap 1: input count defaults to 2
+
+**Symptom:** you wire 3+ sources into a Merge, the canvas shows three wires going in, the workflow validates and runs — but only the first two sources' items appear downstream. The third silently drops.
+
+**Cause:** `numberOfInputs` defaults to `2`. The third wire connects to an input slot that doesn't exist on the node.
+
+**Fix:** set `numberOfInputs` to match your wire count.
+
+```json
+{ "parameters": { "mode": "append", "numberOfInputs": 3 } }
+```
+
+Verify with `get_node` for the merge node on the user's n8n version — the field name has shifted across versions. After building, pull the workflow with `n8n_get_workflow` and confirm `parameters.numberOfInputs` matches the number of source entries in the `connections` object feeding it.
+
+### Trap 2: `useDataOfInput` is 1-indexed, connections are 0-indexed
+
+**Symptom:** the Merge passes through the wrong source. Downstream gets real data with real field names — just from the wrong upstream branch. Looks identical to a working flow; the shape is right, the contents are wrong.
+
+**Cause:** `parameters.useDataOfInput` matches the UI labels (Input 1, Input 2, Input 3 — **1-indexed**), but the wiring position in `connections.<source>.main[idx]` is **0-indexed** like every other array. Off by one.
+
+**Fix — the translation rule:**
+
+> `useDataOfInput: "N"` is fed by the connection at `main[N-1]`.
+
+| `useDataOfInput` | Connection slot |
+|---|---|
+| `"1"` | `connections.<source>.main[0]` |
+| `"2"` | `connections.<source>.main[1]` |
+| `"3"` | `connections.<source>.main[2]` |
+
+When you add the connection via `n8n_update_partial_workflow`, the `addConnection` operation targets a specific input index. To pass through Input 2, the source whose data you want must land on the connection at `main[1]`. After wiring, **verify with `n8n_get_workflow`**: read the `connections` object and confirm the source you intend to pass through actually sits at `main[N-1]`. This is the only reliable check — it won't surface in validation.
+
+---
+
+## Database
+
+Covers Postgres, MySQL, and Supabase (when used via the Postgres node against the same database). The exact field set differs per node and version — `get_node` is canonical. This is the security and behavior layer it doesn't show.
+
+### Never interpolate user input into SQL
+
+**Symptom:** the query works in testing, then a value containing a quote or `;` produces a SQL error — or worse, executes injected SQL. `$json.email = "x'; DROP TABLE users; --"` is game over.
+
+**Cause:** n8n substitutes `{{ ... }}` expressions into the query text **before** the database driver binds parameters. Anything inside `{{ }}` becomes part of the SQL itself, not a bound value.
+
+**Fix:** use `$1, $2, ...` placeholders in the query and pass values through `options.queryReplacement`. The values flow through the driver's parameter binding and never touch the SQL text. (The n8n MySQL node also uses `$1, $2` + `queryReplacement`, not MySQL's native `?` — the node normalizes to the driver.)
+
+```json
+{
+  "parameters": {
+    "operation": "executeQuery",
+    "query": "SELECT * FROM users WHERE email = $1",
+    "options": {
+      "queryReplacement": "={{ $json.email }}"
+    }
+  }
+}
+```
+
+`queryReplacement` takes a comma-separated list — each piece becomes one parameter: `={{ $json.email }},={{ $json.id }}` → `$1, $2`. The `=` prefix is just n8n's expression-mode marker. Treat any DB node with a `{{ ... }}` expression inside `parameters.query` as a critical injection finding.
+
+### Transactions are bounded to one node
+
+**Symptom:** two separate DB nodes, the second fails, and the first's write is already committed — no rollback.
+
+**Cause:** there is no cross-node transaction in n8n. Atomicity is bounded to a single `executeQuery` invocation.
+
+**Fix:** for atomic multi-step writes, put all the statements in one Postgres/MySQL `executeQuery` node and set `options.queryBatching: "transaction"` explicitly — don't rely on the default, which has shifted across node versions (single-query and independent batching are the other modes; confirm the current set and default with `get_node`). Everything that node runs in that execution goes through one BEGIN/COMMIT; any failure rolls it all back. Pre-compute lookups and derived values upstream so the transactional node receives ready-to-write data.
+
+```json
+{
+  "parameters": {
+    "operation": "executeQuery",
+    "query": "INSERT INTO orders (customer_id, total) VALUES ($1, $2)",
+    "options": {
+      "queryBatching": "transaction",
+      "queryReplacement": "={{ $json.customerId }},={{ $json.total }}"
+    }
+  }
+}
+```
+
+Supabase's REST layer has no transactions — drop to the Postgres node connected directly to the same database when you need atomicity.
+
+### "No rows" produces no items
+
+**Symptom:** a `select` / `executeQuery` that matches nothing returns zero items, and the downstream node simply doesn't run — looks like the branch was skipped.
+
+**Cause:** zero matched rows = zero n8n output items, and most nodes treat "no input items" as "nothing to do."
+
+**Fix:** set `alwaysOutputData: true` on the DB node so a single empty item flows through, then branch on the result with an IF. (This is the same gotcha as write operations — INSERT/UPDATE/DELETE often return 0 items too; `alwaysOutputData: true` keeps the chain alive.)
+
+---
+
+## Slack
+
+The exact param shapes shift across versions — `get_node` for `nodes-base.slack` is canonical. These are the traps it won't warn you about.
+
+### Block Kit must be wrapped, or it posts as plain text
+
+**Symptom:** you pass a Block Kit array, the request succeeds, but the message arrives as plain text (or empty). No node error, no validation warning.
+
+**Cause:** the node accepts a bare array silently and drops the rich content. Slack's `chat.postMessage` expects `{ "blocks": [...] }` — an object with a `blocks` key — and the node forwards your value as-is.
+
+**Fix:** wrap the array in an object, in expression mode so the node receives a real object (not a stringified one). Reference the source by node name, not `$json`:
+
+```
+={{ { "blocks": $('Build Message').item.json.blocks } }}
+```
+
+Don't stringify-then-reparse hybrids (`{{ ... .toJsonString() }}` glued into a string) — they work on some versions but break on escaping and large payloads. Hand the node the structure directly.
+
+### Thread replies need `thread_ts`
+
+**Symptom:** a "reply" posts as a new top-level channel message instead of in the thread.
+
+**Cause:** without `thread_ts` (the timestamp of the message being replied to), Slack has no thread to attach to.
+
+**Fix:** set `thread_ts` to the parent message's `ts`. Use `get_node` to find where the field sits on the current version — it moved out of `otherOptions` where older docs put it. Add `reply_broadcast: true` if the reply should also show in the main channel.
+
+### Operation display name ≠ internal value
+
+**Symptom:** you set `operation: "send"` (matching the UI's "Send a message") and validation rejects it.
+
+**Cause:** the display label and the stored value diverge. "Send a message" is `operation: "post"`, not `"send"`.
+
+**Fix:** read the real operation values from `get_node` for `nodes-base.slack` rather than guessing from the UI label. This display-vs-value mismatch recurs across resource nodes (e.g. "Get Many" → `getAll` on Gmail/Supabase).
+
+---
+
+## Webhook / Respond to Webhook
+
+Entry and exit of request/response API workflows. `get_node` is canonical for field shapes; this is the runtime behavior it doesn't show.
+
+### Response code defaults to 200 — even on error branches
+
+**Symptom:** an error branch returns HTTP 200 with an error body. The caller's HTTP client sees success while the body says failure — the worst of both worlds, because the caller's error handling never fires.
+
+**Cause:** `responseCode` defaults to `200` on every Respond to Webhook node, including the ones you wired to error paths.
+
+**Fix:** set `responseCode` explicitly on every Respond branch — 4xx for caller errors (400 validation, 401/403 auth, 409 conflict, 429 rate limit), 5xx for server errors. A workflow can have multiple Respond nodes, one per response shape; n8n returns whichever fires first.
+
+### Use `responseMode: "responseNode"` for real request/response APIs
+
+**Symptom:** the caller gets an immediate 200 and never sees the workflow's actual output, even though the workflow computes a response.
+
+**Cause:** the Webhook trigger's `responseMode` defaults to `onReceived` (acknowledge immediately, run async). The caller can't see downstream results.
+
+**Fix:** set `parameters.responseMode: "responseNode"` on the Webhook trigger and control the response with explicit Respond to Webhook nodes. (`lastNode` returns the last node's output synchronously — fine for simple cases; `responseNode` is the flexible choice for multi-status APIs.)
+
+### `respondWith: "json"` takes the object, not a stringified string
+
+**Symptom:** the response body comes back double-encoded — escaped quotes, a JSON string wrapped in another JSON string.
+
+**Cause:** the `responseBody` field accepts both an object and a string. If you pass `JSON.stringify(obj)`, n8n serializes that string again.
+
+**Fix:** pass the object directly in expression mode and let the node serialize it once:
+
+```
+={{ { "status": "ok", "id": $('Create Record').item.json.id } }}
+```
+
+---
+
+## Schedule Trigger
+
+`get_node` for `nodes-base.scheduleTrigger` shows the rule structure. These are the behaviors outside the type def.
+
+### Timezone is workflow-level, not per-rule
+
+**Symptom:** a job that should fire at 9am local drifts after a DST change or an instance move.
+
+**Cause:** the Schedule Trigger uses the **workflow's** timezone (Workflow Settings → Timezone). There is no `timezone` field inside a rule. Without an explicit workflow timezone, it follows the host's clock.
+
+**Fix:** set the workflow timezone explicitly for any schedule that must run at a specific local time. The per-rule config has no timezone to set — don't look for one.
+
+### Cron accepts 5 or 6 fields
+
+**Symptom:** confusion over whether a cron expression needs a seconds field — the UI hint shows 6 fields, the placeholder shows 5.
+
+**Cause:** n8n's cron supports both 5-field (`Minute Hour DoM Month DoW`) and 6-field (`Second Minute Hour DoM Month DoW`) formats. Both are valid.
+
+**Fix:** use whichever you intend; just be consistent. For simple recurrences ("every Monday 9am"), the interval modes (`field: "weeks"` etc.) are clearer and less error-prone than cron.
+
+### Restarts can miss runs — design for idempotency
+
+**Symptom:** an instance restart or downtime window overlapping a scheduled time, and that run never happens.
+
+**Cause:** schedules fire against the instance's clock. If the instance is down at fire time, the run is simply skipped — there's no catch-up queue.
+
+**Fix:** for business-critical schedules, make the workflow idempotent (running it twice produces the same result) and, where it matters, detect missed runs at workflow start by comparing the last successful run to the expected cadence and catching up.