@amalgm/automations 0.3.2 → 0.4.1

package/dist/src/machine-notifications.js

@@ -0,0 +1,124 @@
+import { AutomationError } from './errors.js';
+/** Ephemeral wakeups only. Supabase remains the queue and the eligibility clock. */
+export function createMachineRunNotifications(options) {
+    const targets = new Map();
+    const encoder = new TextEncoder();
+    let connected = false;
+    const key = (userId, computerId) => JSON.stringify([userId, computerId]);
+    const refresh = async (target) => {
+        target.dirty = true;
+        if (target.refreshing)
+            return;
+        target.refreshing = true;
+        try {
+            while (target.dirty && target.listeners.size) {
+                target.dirty = false;
+                clearTimeout(target.timer);
+                const delay = await options.wakeDelay(target.userId, target.computerId);
+                if (target.dirty || !target.listeners.size)
+                    continue;
+                if (delay === null)
+                    continue;
+                if (!Number.isFinite(delay) || delay < 0)
+                    throw new Error('Invalid machine wake delay');
+                if (delay === 0) {
+                    for (const listener of target.listeners)
+                        listener.send('wake');
+                }
+                else {
+                    target.timer = setTimeout(() => void refresh(target), Math.min(delay, 2_147_483_647));
+                    target.timer.unref();
+                }
+            }
+        }
+        catch {
+            options.log?.('automations.notifications.failed', { boundary: 'wake-deadline' });
+            for (const listener of [...target.listeners])
+                listener.close();
+        }
+        finally {
+            target.refreshing = false;
+        }
+    };
+    const disconnect = () => {
+        connected = false;
+        for (const target of targets.values()) {
+            for (const listener of [...target.listeners])
+                listener.close();
+        }
+    };
+    return Object.freeze({
+        connected() { connected = true; },
+        disconnected: disconnect,
+        close: disconnect,
+        changed(userId, computerId) {
+            const target = targets.get(key(userId, computerId));
+            if (target)
+                void refresh(target);
+        },
+        open(principal, signal) {
+            if (!connected)
+                throw new AutomationError('unavailable', 'Notifications are reconnecting', 503);
+            signal.throwIfAborted();
+            const targetKey = key(principal.userId, principal.computerId);
+            let target = targets.get(targetKey);
+            if (!target) {
+                target = { ...principal, listeners: new Set(), refreshing: false, dirty: false };
+                targets.set(targetKey, target);
+            }
+            const current = target;
+            let close = (_closeStream = true) => { };
+            const body = new ReadableStream({
+                start(controller) {
+                    let closed = false;
+                    let heartbeat;
+                    let expiry;
+                    const abort = () => close();
+                    close = (closeStream = true) => {
+                        if (closed)
+                            return;
+                        closed = true;
+                        clearInterval(heartbeat);
+                        clearTimeout(expiry);
+                        signal.removeEventListener('abort', abort);
+                        current.listeners.delete(listener);
+                        if (!current.listeners.size) {
+                            clearTimeout(current.timer);
+                            targets.delete(targetKey);
+                        }
+                        if (closeStream)
+                            controller.close();
+                    };
+                    const listener = {
+                        send(event) {
+                            if (closed)
+                                return;
+                            if ((controller.desiredSize ?? 0) <= 0)
+                                return close();
+                            controller.enqueue(encoder.encode(event === 'heartbeat'
+                                ? ': keepalive\n\n' : `event: ${event}\ndata: {}\n\n`));
+                        },
+                        close,
+                    };
+                    current.listeners.add(listener);
+                    signal.addEventListener('abort', abort, { once: true });
+                    heartbeat = setInterval(() => listener.send('heartbeat'), options.heartbeatMs ?? 30_000);
+                    heartbeat.unref();
+                    const lifetime = Math.min(options.maxStreamMs ?? 300_000, (principal.authorizationExpiresAt ?? Infinity) - Date.now());
+                    expiry = setTimeout(close, Math.max(0, lifetime));
+                    expiry.unref();
+                    listener.send('ready');
+                    void refresh(current);
+                },
+                cancel() { close(false); },
+            }, { highWaterMark: 8 });
+            return new Response(body, {
+                headers: {
+                    'content-type': 'text/event-stream',
+                    'cache-control': 'no-store, no-transform',
+                    'x-accel-buffering': 'no',
+                },
+            });
+        },
+    });
+}

package/dist/src/machine.d.ts

@@ -4,6 +4,7 @@ export interface AutomationMachinePrincipal {
     readonly userId: string;
     readonly computerId: string;
     readonly scopes: readonly AutomationScope[];
+    readonly authorizationExpiresAt?: number;
 }
 export interface ClaimedAutomationRun extends AutomationRun {
     readonly leaseToken: string;

package/dist/src/mcp.d.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type AutomationCommands } from './command-surface.js';
 import type { AutomationCrud } from './contract.js';
 import { createAutomationToolSurface } from './tool-surface.js';
 export { createAutomationToolSurface };
 export type { AutomationToolSurface, AutomationView, CreateAutomationDefinition, UpdateAutomationDefinition, WorkflowChange, } from './tool-surface.js';
-export declare function createAutomationMcpServer(sdk: AutomationCrud): McpServer;
+export declare function createAutomationMcpServer(sdk: AutomationCrud | AutomationCommands): McpServer;

package/dist/src/mcp.js

@@ -14,7 +14,7 @@ const resultSchema = {
 };
 export function createAutomationMcpServer(sdk) {
     const server = new McpServer({ name: 'amalgm-automations-mcp-server', version: '0.1.0' });
-    const commands = createAutomationCommands(sdk);
+    const commands = 'execute' in sdk ? sdk : createAutomationCommands(sdk);
     for (const definition of automationCommandDefinitions)
         register(server, commands, definition);
     return server;
@@ -23,7 +23,9 @@ function register(server, commands, definition) {
     server.registerTool(definition.mcpName, {
         title: definition.title,
         description: definition.description,
-        inputSchema: definition.inputShape,
+        // Forward unknown top-level fields to the SDK's strict parser. The MCP
+        // SDK's default object parser strips them before our command sees them.
+        inputSchema: z.object(definition.inputShape).passthrough(),
         outputSchema: resultSchema,
         annotations: definition.annotations,
     }, async (input) => {

package/dist/src/runner.d.ts

@@ -1,13 +1,15 @@
 import type { ClaimedAutomationRun, MachineRuns } from './machine.js';
 export interface AutomationMachineRunnerOptions {
     readonly runs: MachineRuns;
+    readonly notifications: (signal: AbortSignal) => AsyncIterable<void>;
     readonly execute: (run: ClaimedAutomationRun) => Promise<void>;
     readonly batchSize?: number;
     readonly leaseSeconds?: number;
-    readonly pollIntervalMs?: number;
+    readonly reconnectDelayMs?: number;
     readonly maxBackoffMs?: number;
     readonly log?: (event: string, details?: Readonly<Record<string, unknown>>) => void;
 }
+/** Listen first, then drain. There is no timer that asks an idle machine for work. */
 export declare function createAutomationMachineRunner(options: AutomationMachineRunnerOptions): Readonly<{
     start(): void;
     close(): Promise<void>;

package/dist/src/runner.js

@@ -1,61 +1,84 @@
+import { setTimeout as delay } from 'node:timers/promises';
+/** Listen first, then drain. There is no timer that asks an idle machine for work. */
 export function createAutomationMachineRunner(options) {
     const batchSize = integer(options.batchSize ?? 8, 1, 20, 'batchSize');
     const leaseSeconds = integer(options.leaseSeconds ?? 60, 30, 900, 'leaseSeconds');
-    const pollIntervalMs = integer(options.pollIntervalMs ?? 1_000, 1, 60_000, 'pollIntervalMs');
-    const maxBackoffMs = integer(options.maxBackoffMs ?? Math.max(30_000, pollIntervalMs), pollIntervalMs, 300_000, 'maxBackoffMs');
-    let active = null;
-    let timer = null;
-    let stopped = true;
-    let failures = 0;
-    let nextDelay = pollIntervalMs;
-    const schedule = (delay) => {
-        if (stopped)
+    const reconnectDelayMs = integer(options.reconnectDelayMs ?? 1_000, 1, 60_000, 'reconnectDelayMs');
+    const maxBackoffMs = integer(options.maxBackoffMs ?? 30_000, reconnectDelayMs, 300_000, 'maxBackoffMs');
+    let lifetime = null;
+    let listening = null;
+    let draining = null;
+    let pending = false;
+    const wake = (connection, signal) => {
+        pending = true;
+        if (draining)
             return;
-        timer = setTimeout(drain, delay);
-        timer.unref?.();
-    };
-    const drain = () => {
-        if (stopped || active)
-            return active;
-        active = options.runs.claim({ limit: batchSize, leaseSeconds })
-            .then(async (runs) => {
-            failures = 0;
-            if (runs.length)
-                options.log?.('automations.claimed', { count: runs.length });
-            const settled = await Promise.allSettled(runs.map(options.execute));
-            settled.forEach((result) => {
-                if (result.status === 'rejected') {
-                    options.log?.('automations.run.failed', { error: safe(result.reason) });
+        draining = (async () => {
+            while (pending && !signal.aborted) {
+                pending = false;
+                const runs = await options.runs.claim({ limit: batchSize, leaseSeconds });
+                if (runs.length)
+                    options.log?.('automations.claimed', { count: runs.length });
+                const settled = await Promise.allSettled(runs.map(options.execute));
+                for (const result of settled) {
+                    if (result.status === 'rejected')
+                        options.log?.('automations.run.failed', { error: safe(result.reason) });
                 }
-            });
-            nextDelay = runs.length === batchSize ? 0 : pollIntervalMs;
-        })
-            .catch((error) => {
-            failures += 1;
-            const delayMs = Math.min(maxBackoffMs, pollIntervalMs * (2 ** Math.min(failures - 1, 10)));
-            options.log?.('automations.poll.failed', { error: safe(error), retryInMs: delayMs });
-            nextDelay = delayMs;
-        })
-            .finally(() => {
-            active = null;
-            schedule(nextDelay);
+                // Work may arrive while execution is busy, including a partial last batch.
+                pending ||= runs.length > 0;
+            }
+        })().catch((error) => {
+            options.log?.('automations.claim.failed', { error: safe(error) });
+            connection.abort(error);
+        }).finally(() => {
+            draining = null;
+            if (pending && !signal.aborted && !connection.signal.aborted)
+                wake(connection, signal);
         });
-        return active;
+    };
+    const listen = async (signal) => {
+        let failures = 0;
+        while (!signal.aborted) {
+            const connection = new AbortController();
+            const connectedSignal = AbortSignal.any([signal, connection.signal]);
+            const startedAt = Date.now();
+            try {
+                for await (const _ of options.notifications(connectedSignal)) {
+                    if (connectedSignal.aborted)
+                        break;
+                    wake(connection, signal);
+                }
+            }
+            catch (error) {
+                if (!signal.aborted)
+                    options.log?.('automations.notifications.disconnected', { error: safe(error) });
+            }
+            finally {
+                connection.abort();
+                await draining;
+            }
+            if (signal.aborted)
+                break;
+            // A flapping stream must not reset its backoff merely by sending ready.
+            failures = Date.now() - startedAt >= 30_000 ? 0 : failures + 1;
+            const backoff = Math.min(maxBackoffMs, reconnectDelayMs * 2 ** Math.min(Math.max(0, failures - 1), 10));
+            await delay(backoff, undefined, { signal, ref: false }).catch(() => { });
+        }
     };
     return Object.freeze({
         start() {
-            if (!stopped)
+            if (lifetime)
                 return;
-            stopped = false;
-            failures = 0;
-            void drain();
+            lifetime = new AbortController();
+            pending = false;
+            listening = listen(lifetime.signal);
         },
         async close() {
-            stopped = true;
-            if (timer)
-                clearTimeout(timer);
-            timer = null;
-            await active;
+            lifetime?.abort();
+            await listening;
+            await draining;
+            lifetime = null;
+            listening = null;
         },
     });
 }

package/dist/src/schema.js

@@ -1,7 +1,7 @@
 import { z } from 'zod/v3';
 import { ValidationError } from './errors.js';
 import { compiledAutomationPlan } from './plan.js';
-import { IDENTIFIER } from './validation.js';
+import { IDENTIFIER, schedule } from './validation.js';
 const maxPageSize = 100;
 const identifierMessage = 'Identifier is invalid';
 const text = (maximum, label) => z.string()
@@ -96,10 +96,16 @@ export function parseListAutomations(value) {
     return parse(listAutomationsSchema, value);
 }
 export function parseCreateScheduleTrigger(value) {
-    return parse(createScheduleTriggerSchema, value);
+    const trigger = parse(createScheduleTriggerSchema, value);
+    schedule(trigger.cron, trigger.timezone ?? 'UTC');
+    return trigger;
 }
 export function parseUpdateScheduleTrigger(value) {
-    return parse(updateScheduleTriggerSchema, value);
+    const patch = parse(updateScheduleTriggerSchema, value);
+    if (patch.cron !== undefined || patch.timezone !== undefined) {
+        schedule(patch.cron ?? '* * * * *', patch.timezone ?? 'UTC');
+    }
+    return patch;
 }
 export function parseCreateWebhookTrigger(value) {
     return parse(createWebhookTriggerSchema, value);

package/dist/src/supabase-machine.d.ts

@@ -11,6 +11,7 @@ export declare class SupabaseMachineRunRepository implements MachineRunRepositor
     #private;
     private readonly client;
     constructor(client: MachineRpcClient);
+    wakeDelay(userId: string, computerId: string): Promise<number | null>;
     claim(input: Parameters<MachineRunRepository['claim']>[0]): Promise<ClaimedAutomationRun[]>;
     update(input: Parameters<MachineRunRepository['update']>[0]): Promise<ClaimedAutomationRun | null>;
 }

package/dist/src/supabase-machine.js

@@ -4,6 +4,9 @@ export class SupabaseMachineRunRepository {
     constructor(client) {
         this.client = client;
     }
+    wakeDelay(userId, computerId) {
+        return this.#call('amalgm_machine_wake_delay', { p_user_id: userId, p_target_id: computerId });
+    }
     async claim(input) {
         const rows = await this.#call('claim_amalgm_machine_runs', {
             p_user_id: input.userId,

package/dist/src/tool-surface.js

@@ -1,4 +1,5 @@
-import { NotFoundError, ValidationError } from './errors.js';
+import { AutomationError, NotFoundError, ValidationError } from './errors.js';
+import { parseCreateAutomation, parseCreateScheduleTrigger, parseCreateWebhookTrigger, parseCreateWorkflow, parseUpdateAutomation, parseUpdateScheduleTrigger, parseUpdateWebhookTrigger, parseUpdateWorkflow, } from './schema.js';
 export function createAutomationToolSurface(sdk) {
     const view = async (automationId, runs = false) => {
         const automation = await sdk.automations.get(automationId);
@@ -14,6 +15,11 @@ export function createAutomationToolSurface(sdk) {
     const surface = {
         async create(input) {
             const { schedules = [], webhooks = [], workflow, ...automationInput } = input;
+            parseCreateAutomation(automationInput);
+            schedules.forEach(parseCreateScheduleTrigger);
+            webhooks.forEach(parseCreateWebhookTrigger);
+            if (workflow)
+                parseCreateWorkflow(workflow);
             validateCreateIds(schedules, webhooks);
             const staged = schedules.length > 0 || webhooks.length > 0 || workflow !== undefined;
             const requestedEnabled = automationInput.enabled !== false;
@@ -40,6 +46,7 @@ export function createAutomationToolSurface(sdk) {
         get: view,
         async update(automationId, input) {
             requireChanges(input);
+            validateUpdate(input);
             validateChanges(input.schedules, 'schedule');
             validateChanges(input.webhooks, 'webhook');
             const current = await sdk.automations.get(automationId);
@@ -98,6 +105,18 @@ function requireChanges(input) {
         throw new ValidationError('Automation update must include a change');
     }
 }
+function validateUpdate(input) {
+    if (input.patch)
+        parseUpdateAutomation(input.patch);
+    input.schedules?.create?.forEach(parseCreateScheduleTrigger);
+    input.schedules?.update?.forEach(({ patch }) => parseUpdateScheduleTrigger(patch));
+    input.webhooks?.create?.forEach(parseCreateWebhookTrigger);
+    input.webhooks?.update?.forEach(({ patch }) => parseUpdateWebhookTrigger(patch));
+    if (input.workflow && 'create' in input.workflow)
+        parseCreateWorkflow(input.workflow.create);
+    if (input.workflow && 'update' in input.workflow)
+        parseUpdateWorkflow(input.workflow.update);
+}
 function hasChanges(changes) {
     return Boolean(changes && [changes.create, changes.update, changes.delete]
         .some((items) => items && items.length > 0));
@@ -122,5 +141,5 @@ function validateCreateIds(schedules, webhooks) {
 }
 function disabledDraftError(automationId, error) {
     const reason = error instanceof Error ? error.message : String(error);
-    return new Error(`Automation ${automationId} remains disabled because configuration failed: ${reason}`);
+    return new AutomationError(error instanceof AutomationError ? error.code : 'internal', `Automation ${automationId} remains disabled because configuration failed: ${reason}`, error instanceof AutomationError ? error.status : undefined);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/automations",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Amalgm's automation SDK: durable trigger admission and target-machine execution.",
   "license": "UNLICENSED",
   "repository": {
@@ -45,10 +45,11 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts && tsx scripts/build-public-skill.ts",
     "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json --noEmit",
     "test": "tsx --test test/*.test.ts",
     "test:supabase": "tsx --test test/integration/postgres.test.ts",
+    "test:notifications": "tsx scripts/test-notifications.ts",
     "verify": "npm run check && npm test && npm run build && tsx scripts/check-cli-artifact.ts",
     "release:check": "npm run verify && npm run test:supabase",
     "prepack": "npm run build",

package/skills/amalgm-automations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: amalgm-automations
-description: Operate complete Amalgm automations through the Automations MCP tools or the global `amalgm automations` CLI, including schedules, webhooks, Run Now, run history, native commands, scripts, and Amalgm actions.
+description: Set up, operate, and troubleshoot Amalgm Automations through MCP or the amalgm automations CLI. Use for installation, Google sign-in, scheduled or webhook workflows, Run Now, run history, and Automations support.
 ---
 
 # Amalgm Automations
@@ -10,6 +10,10 @@ workflow into one durable Amalgm automation and verify what actually ran.
 Automations owns configuration and permanent run history; the selected Amalgm
 machine executes the workflow.
 
+Amalgm Automations is free. Guide the person through Google sign-in and computer
+approval when needed; do not introduce a payment step. A native agent or other
+external service still uses its own account and may have its own usage costs.
+
 ## Choose the available adapter
 
 Prefer the six `amalgm_automations_*` MCP tools when they are callable. In a
@@ -28,11 +32,22 @@ amalgm_automations_run_now          amalgm automations run-now
 Both adapters accept the same JSON object and call the same SDK command
 surface. Do not translate one into a different resource-level API.
 
-For CLI use, first check `amalgm automations --help`. A signed-in, running
-Amalgm Shell supplies authentication through its loopback runtime. Never ask
-the user to copy a runtime token, DPoP proof, device key, or machine credential.
-If the runtime is unavailable, report that Shell must be signed in and running;
-do not fall back to an invented credential flow.
+Reuse a working connection. For an available MCP connection, a small `list`
+request with `{"limit":1}` proves access; do not install or log in again. For
+CLI use, check `amalgm automations --help` and use
+`amalgm automations list --input '{"limit":1}'`. An empty successful list is
+ready, not a setup failure. Respect an explicitly selected account.
+
+If the user asks to install or sign in, or that read fails, read
+[setup and support](references/setup-and-support.md). It covers the supported
+install, browser approval, account selection, runtime restart, and recovery
+commands. Carry setup through to a successful Automations read, then resume
+the original request. Do not stop at “Shell must be running.”
+
+Shell owns authentication. Never read, copy, or ask the user to supply a runtime
+token, DPoP proof, device key, or machine credential. The public connection
+commands obtain what they need; environment-variable credential setup is not
+the user login flow.
 
 Read [references/command-contract.md](references/command-contract.md) whenever
 composing `create` or `update`, or when exact fields are uncertain. Read
@@ -57,13 +72,16 @@ input.
   complex source. Do not expose those values in command arguments or logs.
 - Delete only after the exact id is established and deletion is within the
   user's request. Deleting configuration intentionally retains run history.
+  Omit `id` when creating a new automation; explicitly reusing a deleted id
+  refers to the same logical identity and retains its history and retry keys.
 
 ## Build one complete definition
 
 Create the automation, its schedule/webhook triggers, and its optional workflow
-in one task-level call. The service stages multi-resource changes safely and
-enables the definition only after setup succeeds. If setup fails, report the
-returned disabled draft id rather than silently creating a replacement.
+in one task-level call. Invalid supplied configuration fails before any write.
+The service stages valid multi-resource changes and enables the definition
+only after setup succeeds. If a later service failure returns a disabled draft
+id, get and repair that draft with `update`; do not create a replacement.
 
 Use a finite `maxOccurrences` when the user's request is bounded. Do not turn
 "ten times" into an unbounded schedule plus a future cleanup promise.
@@ -87,27 +105,47 @@ executables through the selected machine; never guess either.
 not evidence that work completed.
 
 1. Supply a stable, caller-chosen `idempotency_key` whenever the request might
-   be retried.
+   be retried. Use a new key for each new logical run.
 2. If admission is retried, send the same automation id, input, and key. The
    returned run id must remain the same.
 3. Poll `get` with `include_runs: true` or a `run_query` until the admitted run
    becomes `completed` or `failed`. Match the exact run id; do not assume the
-   newest unrelated run is yours.
+   newest unrelated run is yours. Space out reads and back off while state is
+   unchanged; a rate-limit response is a reason to wait, not to submit again.
 4. Inspect every step's status and bounded output. Report failure honestly,
    including the failing step and service error.
 
 `pending` means durable and awaiting its machine. `sent` or `running` means the
 machine holds a lease. Only `completed` and `failed` are terminal.
 
+Keep the user informed while waiting. If the machine stays unavailable or the
+current session cannot keep waiting, report the exact run id and observed
+nonterminal state; do not claim completion, create a replacement, or promise
+background monitoring that has not been set up.
+
 Diagnose at the failing boundary. Examples: `process_execution_unavailable`
 means that machine lacks the process host; an executable-not-found error is a
 machine PATH/install problem; `Installed agent has no model` is agent
 configuration; an action-specific HTTP error belongs to that action service.
 Do not relabel these as Run Now failures or patch the automation around them.
 
+## Help when something goes wrong
+
+Use [setup and support](references/setup-and-support.md) for login/runtime
+failures, HTTP 429 or reported rate limits, and contacting support. Preserve
+the actual error code, distinguish the failing service, and use bounded retries.
+Do not invent minute/hour allowances or reset times that the service has not
+reported.
+
+For an unresolved issue, offer **Email Aayush at aayush@amalgm.ai** and prepare
+a concise, redacted draft when helpful. Send only with the user's explicit
+authorization and an available email tool; otherwise give them the draft.
+
 ## Report the outcome
 
 Return the automation id, target choice if the user selected one, trigger
 summary, workflow lanes, and—when execution was requested—the exact run id and
 terminal result. Mention that run history is durable. Never claim a schedule
 fired merely because configuration creation succeeded.
+Include automation/run links when returned by the product; do not invent a
+deep link or use a private webhook URL as a viewing link.

package/skills/amalgm-automations/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Amalgm Automations"
-  short_description: "Create and verify durable Amalgm automations"
-  default_prompt: "Use $amalgm-automations to create and verify an automation for me."
+  short_description: "Set up, run, and troubleshoot Amalgm automations"
+  default_prompt: "Use $amalgm-automations to help me connect my account and create and verify an automation."

package/skills/amalgm-automations/references/command-contract.md

@@ -15,6 +15,8 @@ Failures use stderr, a nonzero exit, and:
 ```
 
 Do not scrape prose or infer success from exit code alone; parse the envelope.
+Unknown configuration fields are rejected. Arbitrary JSON inside workflow
+action input and Run Now input remains valid payload data.
 
 ## create
 
@@ -62,6 +64,11 @@ At least one executable step is required when `compiled` is supplied. Omit
 webhook URL is the provider destination; a configured signing secret is
 write-only on later reads.
 
+Omit `id` for a new automation. An explicit id names a persistent logical
+identity: deleting and recreating it retains that identity's run history and
+Run Now idempotency keys. Use a new key for each new logical run and reuse it
+only when retrying that run.
+
 CLI example:
 
 ```bash