makersclaw 0.8.0 → 0.8.2

package/registry/blocks/automation-editor/block.json

@@ -0,0 +1,39 @@
+{
+  "name": "automation-editor",
+  "title": "AutomationEditor",
+  "description": "The whole editor for one automation: a header with its name, a status (New, Draft, Draft ahead, Live, Off, Unsaved changes), a test chip (Not tested, Tested with the steps that would run, Last test failed), the run picker, the Live switch, Test run (a dry run: it reads real data and changes nothing) with its price on it, Keep this version and Save; a strip that says what is wrong with it, in words and by step; the node canvas (flow-editor) with an undo history; and the panel for whatever is pressed (the trigger, a step, or the automation as a whole), over the canvas on a narrow width and beside it on a wide one. It holds the working copy of the definition and knows nothing of the network: Save, Keep, Live and Test are callbacks that resolve the platform's answer. Keep and Live need a passed test; when the platform refuses for want of one, the editor offers a test or, after one more question, a deliberate skip. A draft shared with an agent is never buried: the editor remembers the version its copy began on, saves against it, and when a newer version arrives while there are edits not saved it says so (Look at it, Keep mine, or save on top of it on purpose); a line under the header says when the agent drew the draft. Delete automation is in a menu at the end of the header and asks first.",
+  "useWhen": "A member opens, edits, tests and switches on an automation inside an app. Pair it with automation-list (the rows) and run-view (a run), and the useAutomations / useAutomation / useAutomationRun hooks (lib/hooks.js).",
+  "tags": [
+    "automation",
+    "workflow",
+    "builder",
+    "editor",
+    "canvas",
+    "save",
+    "test run",
+    "keep",
+    "live",
+    "draft",
+    "undo",
+    "n8n",
+    "make",
+    "zapier",
+    "page"
+  ],
+  "exports": [
+    "AutomationEditor",
+    "RunInputs"
+  ],
+  "files": [
+    "index.js",
+    "automation-editor.jsx",
+    "run-inputs.jsx"
+  ],
+  "requires": [
+    "automation-model",
+    "fix-note",
+    "flow-editor",
+    "step-settings",
+    "trigger-picker"
+  ]
+}

package/registry/blocks/automation-editor/demo.jsx

@@ -0,0 +1,284 @@
+"use client";
+
+// An Automations page with a pretend platform behind it — the gallery's and
+// the smoke test's surface. Not installed into apps. The list, the builder
+// (edit a step, add one with a +, Save, Keep, switch it Live, Test run) and
+// a run on the same canvas, all in memory. Test run is a dry run (dashed
+// pencil cards); Keep and Live refuse with "needs_test" until one passed, and
+// the note offers Run a test or, after one more question, Go live without one.
+// "The agent saves a draft" pretends the agent wrote a newer version while the
+// editor is open: with nothing edited the canvas follows it ("Drawn by the
+// agent", with What changed); with edits not saved, a strip offers Look at it or
+// Keep mine, and Save, which names the version the copy began on, is refused
+// ("changed") until the member chooses to save on top. Delete automation is in
+// the header's menu and each row's (it asks first; the app's own shipped job
+// says to use the app's settings instead). A width picker shows the page at
+// 1280, 800, 368 and 320 px of the block's own width.
+import { useMemo, useState } from "react";
+import { Button, ButtonGroup } from "../components/ui";
+import { AutomationEditor } from "../components/blocks/automation-editor";
+import { AutomationList } from "../components/blocks/automation-list";
+import { RunView, RunsList } from "../components/blocks/run-view";
+import { STARTING_POINTS, blankAutomation, keyFromName } from "../components/blocks/automation-model";
+
+const MORNING = {
+  format: 1,
+  key: "morning-read",
+  name: "Morning read",
+  does: "Reads your mail, saves who wrote, drafts the follow-ups that are owed.",
+  trigger: { type: "schedule", cron: "0 7 * * 1-5", tz: "team" },
+  inputs: {},
+  settings: { overlap: "skip", on_failure: "retry_then_agent", only_if_changed: false },
+  steps: [
+    { id: "mail", kind: "tool", label: "Read the mail since the last read", needs: { category: "mail" }, tool: "list_messages", input: { since: "{{ trigger.at }}", limit: 200 } },
+    { id: "touches", kind: "action", label: "Save who wrote", action: "record_touches", input: { touches: "{{ steps.mail.output.messages }}" } },
+    { id: "write", kind: "llm", label: "Write the follow-up", tier: "smart", prompt: "Write a short follow-up to the last person who wrote." },
+    { id: "tell", kind: "notify", message: "Morning read done." },
+  ],
+};
+
+const FRIDAY = {
+  format: 1,
+  key: "friday-review",
+  name: "Friday review",
+  trigger: { type: "schedule", cron: "0 16 * * 5", tz: "team" },
+  inputs: {},
+  settings: { overlap: "skip", on_failure: "retry_then_agent", only_if_changed: false },
+  steps: [{ id: "tell", kind: "notify", message: "Friday review is ready." }],
+};
+
+const flat = (steps) => steps.flatMap((s) => [s, ...(s.then ?? []).flatMap((x) => flat([x])), ...(s.else ?? []).flatMap((x) => flat([x])), ...flat(s.steps ?? [])]);
+const WIDTHS = [1280, 800, 368, 320];
+
+function Page() {
+  const [store, setStore] = useState(() => ({
+    a1: {
+      id: "a1",
+      source: "package",
+      def: MORNING,
+      liveDef: MORNING,
+      live: 1,
+      draft: 1,
+      status: "on",
+      versions: [{ version: 1, kind: "shipped", created_at: "2026-10-09T09:00:00Z" }],
+      runs: [],
+      // What the agent drafted from a failed run: kept, it becomes version 2 and runs.
+      suggestions: [{ id: "s1", run_id: "r0", why: "The mail tool refused a limit of 200. Asking for 50 at a time works.", base_version: 1, stale: false, patch: { changes: [{ id: "mail", input: { limit: 50 } }] } }],
+    },
+    a2: { id: "a2", source: "member", def: FRIDAY, liveDef: FRIDAY, live: 1, draft: 1, status: "off", versions: [{ version: 1, kind: "member", created_at: "2026-10-09T09:00:00Z" }], runs: [] },
+  }));
+  const [at, setAt] = useState({ id: null, run: null, tab: "flow", start: null });
+  const go = (next) => setAt({ id: null, run: null, tab: "flow", start: null, ...next });
+
+  const rows = useMemo(
+    () =>
+      Object.values(store).map((a) => ({
+        id: a.id,
+        key: a.def.key,
+        name: a.def.name,
+        status: a.status,
+        live_version: a.live,
+        draft_version: a.draft,
+        trigger: a.def.trigger,
+        tz: "America/New_York",
+        next_run_at: a.status === "on" ? "2026-10-12T11:00:00.000Z" : null,
+        last_run: a.runs[0] ? { status: a.runs[0].status, started_at: a.runs[0].created_at, credits: a.runs[0].credits } : null,
+        owner_kind: "app",
+        app_id: "crm",
+        edited: a.versions.some((v) => v.kind === "member"),
+        source: a.source,
+      })),
+    [store],
+  );
+  const patch = (id, fn) => setStore((s) => ({ ...s, [id]: fn(s[id]) }));
+  // The platform's answer to a delete: gone (its runs stay in history), and the one that followed it named.
+  const remove = async (x) => {
+    setStore((s) => Object.fromEntries(Object.entries(s).filter(([k]) => k !== x.id)));
+    go({});
+    return { ok: true };
+  };
+  // What the platform says about tests: a shipped version needs none; any other
+  // needs a passed test of that very version.
+  const testsOf = (a) => {
+    const view = (version) => (version === null || version === undefined ? null : { version, exempt: a.versions.some((v) => v.version === version && v.kind === "shipped"), passed: a.passed === version, last: a.lastTest && a.lastTest.version === version ? a.lastTest.last : null });
+    return { live: view(a.live), draft: a.draft !== a.live ? view(a.draft) : null };
+  };
+  const needsTest = (a, version, opts) => !opts?.skipTest && !testsOf(a)[version === a.live ? "live" : "draft"]?.exempt && a.passed !== version;
+  const REFUSED = { ok: false, code: "needs_test", error: "Run a test of this version first. It reads your real data and changes nothing." };
+
+  if (at.id === "new") {
+    const taken = new Set(Object.values(store).map((a) => a.def.key));
+    const picked = STARTING_POINTS.find((s) => s.id === at.start);
+    return (
+      <AutomationEditor
+        key="new"
+        automationId={null}
+        status="new"
+        baseline={picked ? picked.build(taken) : blankAutomation("", keyFromName("New automation", taken))}
+        ownedByApp
+        onBack={() => go({})}
+        onSave={async (def) => {
+          const id = `a${Object.keys(store).length + 1}`;
+          setStore((s) => ({ ...s, [id]: { id, def: { ...def, key: keyFromName(def.name, taken) }, live: null, draft: 1, status: "draft", versions: [{ version: 1, kind: "member", created_at: new Date().toISOString() }], runs: [] } }));
+          go({ id });
+          return { ok: true };
+        }}
+      />
+    );
+  }
+
+  const a = at.id ? store[at.id] : null;
+  if (!a) {
+    return (
+      <AutomationList
+        rows={rows}
+        grouped={false}
+        appName={() => "CRM"}
+        now={new Date("2026-10-11T12:00:00.000Z")}
+        onOpen={(id) => go({ id })}
+        onNew={(s) => go({ id: "new", start: s?.id ?? null })}
+        onToggle={async (row, on) => patch(row.id, (x) => ({ ...x, status: on ? "on" : "off" }))}
+        onDelete={remove}
+      />
+    );
+  }
+
+  const tabs = (
+    <ButtonGroup aria-label="Inside this automation">
+      {[["flow", "Flow"], ["runs", "Runs"]].map(([id, label]) => (
+        <Button key={id} size="sm" variant={at.tab === id ? "primary" : "secondary"} onClick={() => go({ id: a.id, tab: id })}>
+          {label}
+        </Button>
+      ))}
+    </ButtonGroup>
+  );
+  const run = at.run ? a.runs.find((r) => r.id === at.run) : null;
+  if (run) {
+    return (
+      <RunView
+        def={a.def}
+        detail={{ run, steps: run.steps, steps_visible: true, automation: { name: a.def.name } }}
+        runs={a.runs}
+        tz="America/New_York"
+        tabs={tabs}
+        name={a.def.name}
+        onBack={() => go({ id: a.id })}
+        onPickRun={(r) => go({ id: a.id, run: r })}
+      />
+    );
+  }
+  if (at.tab === "runs") {
+    return (
+      <div className="flex min-h-0 flex-1 flex-col">
+        <div className="flex items-center gap-2 border-b border-border px-3 py-2">
+          <Button size="sm" variant="quiet" icon="arrow-left" onClick={() => go({})}>
+            Automations
+          </Button>
+          {tabs}
+        </div>
+        <RunsList runs={a.runs} tz="America/New_York" onOpen={(r) => go({ id: a.id, run: r })} />
+      </div>
+    );
+  }
+  const agentSaves = () =>
+    patch(a.id, (x) => {
+      const version = x.versions.length + 1;
+      const def = { ...x.def, steps: x.def.steps.map((st) => (st.id === "mail" ? { ...st, input: { ...st.input, limit: 100 } } : st)) };
+      return { ...x, def, draft: version, versions: [...x.versions, { version, kind: "agent", author: "agent", note: "Changed: read 100 at a time", created_at: new Date().toISOString() }] };
+    });
+  return (
+    <>
+    <div className="flex items-center gap-2 border-b border-border bg-muted px-3 py-1.5 text-xs text-muted-foreground">
+      <span>Pretend platform:</span>
+      <Button size="sm" variant="secondary" onClick={agentSaves}>
+        The agent saves a draft
+      </Button>
+    </div>
+    <AutomationEditor
+      key={a.id}
+      automationId={a.id}
+      status={a.status}
+      liveVersion={a.live}
+      draftVersion={a.draft}
+      baseline={a.def}
+      compareTo={{ version: a.live, definition: a.liveDef }}
+      versions={[...a.versions].reverse()}
+      runs={a.runs}
+      estimate={{ credits: 3, credits_max: 12, steps: [{ id: "write", credits: 3, credits_max: 12 }] }}
+      ownedByApp
+      tabs={tabs}
+      source={a.source}
+      onDelete={remove}
+      onBack={() => go({})}
+      onSave={async (def, { baseVersion } = {}) => {
+        // The platform's own rule: a save names the version it was made from; a newer one refuses it.
+        const latest = a.versions.length;
+        if (baseVersion !== latest) return { ok: false, code: "changed", latest, error: "Someone saved a newer version while you were editing. Open it again to see theirs." };
+        patch(a.id, (x) => ({ ...x, def, draft: x.versions.length + 1, versions: [...x.versions, { version: x.versions.length + 1, kind: "member", created_at: new Date().toISOString() }] }));
+        return { ok: true, version: latest + 1 };
+      }}
+      suggestions={a.suggestions ?? []}
+      onKeepSuggestion={async (id) => {
+        const s = (a.suggestions ?? []).find((x) => x.id === id);
+        if (!s) return { ok: false, error: "That suggestion is gone." };
+        patch(a.id, (x) => {
+          const version = x.versions.length + 1;
+          const def = { ...x.def, steps: x.def.steps.map((st) => { const c = s.patch.changes.find((ch) => ch.id === st.id); return c && c.input ? { ...st, input: { ...st.input, ...c.input } } : st; }) };
+          return { ...x, def, liveDef: def, live: version, draft: version, versions: [...x.versions, { version, kind: "agent", created_at: new Date().toISOString() }], suggestions: x.suggestions.filter((y) => y.id !== id) };
+        });
+        return { ok: true };
+      }}
+      onDropSuggestion={async (id) => {
+        patch(a.id, (x) => ({ ...x, suggestions: (x.suggestions ?? []).filter((y) => y.id !== id) }));
+        return { ok: true };
+      }}
+      tests={testsOf(a)}
+      onKeep={async (opts) => {
+        if (needsTest(a, a.draft, opts)) return REFUSED;
+        patch(a.id, (x) => ({ ...x, live: x.draft, liveDef: x.def }));
+        return { ok: true };
+      }}
+      onLive={async (on, opts) => {
+        if (on && needsTest(a, a.live, opts)) return REFUSED;
+        patch(a.id, (x) => ({ ...x, status: on ? "on" : "off" }));
+        return { ok: true };
+      }}
+      onTest={async () => {
+        const id = `r${a.runs.length + 1}`;
+        const t = new Date().toISOString();
+        // A dry run: reading and thinking happen, writing and telling are only drawn.
+        const standIn = new Set(["action", "notify"]);
+        const steps = flat(a.def.steps).map((s) => {
+          const wouldDo = standIn.has(s.kind);
+          return { path: s.id, step_id: s.id, kind: s.kind, attempt: 1, status: "done", started_at: t, ended_at: t, credits: s.kind === "llm" ? 3 : 0, error: null, ...(wouldDo ? { simulated: true, output: { simulated: true, would: { kind: s.kind, effect: s.kind === "notify" ? "note" : "write", words: s.kind === "notify" ? "Would leave a note." : `Would run ${s.action}.` } } } : { output: { ok: true } }) };
+        });
+        const would = steps.filter((x) => x.simulated).length;
+        const wouldList = steps.filter((x) => x.simulated).map((x) => ({ step: x.step_id, path: x.path, kind: x.kind, effect: x.output.would.effect, words: x.output.would.words }));
+        const version = a.draft;
+        patch(a.id, (x) => ({ ...x, passed: version, lastTest: { version, last: { run_id: id, status: "done", ended_at: t, credits: 3, would } }, runs: [{ id, status: "done", dry: true, version, trigger_type: "manual", is_test: true, created_at: t, started_at: t, ended_at: t, credits: 3, result: { dry: { simulated: would, would: wouldList, unchecked: [], sampled: [] } }, steps }, ...x.runs] }));
+        go({ id: a.id, run: id });
+        return { ok: true };
+      }}
+      onOpenRun={(r) => go({ id: a.id, run: r })}
+    />
+    </>
+  );
+}
+
+export default function AutomationEditorDemo() {
+  const [width, setWidth] = useState(1280);
+  return (
+    <div className="grid gap-4 p-4">
+      <ButtonGroup aria-label="The block's width">
+        {WIDTHS.map((w) => (
+          <Button key={w} size="sm" variant={w === width ? "primary" : "secondary"} onClick={() => setWidth(w)}>
+            {w} px
+          </Button>
+        ))}
+      </ButtonGroup>
+      <div className="flex h-[720px] w-full flex-col overflow-hidden rounded-lg border border-border" style={{ maxWidth: width }}>
+        <Page />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/automation-editor/index.js

@@ -0,0 +1,4 @@
+// The AutomationEditor block — `makersclaw add automation-editor`.
+// Fixed: compose it through its props (README.md beside this file).
+export { AutomationEditor } from "./automation-editor";
+export { RunInputs } from "./run-inputs";

package/registry/blocks/automation-editor/run-inputs.jsx

@@ -0,0 +1,82 @@
+"use client";
+
+// The small question a manual run asks first: one field for each input the
+// automation declares, with its default. The values are typed to the
+// input's kind before they go (the platform checks them again).
+
+import { useId, useState } from "react";
+import { Button, Checkbox, Field, Input, Select, Sheet } from "../../ui";
+
+function initial(spec) {
+  if (spec.type === "boolean") return spec.default === true;
+  return spec.default === undefined ? "" : String(spec.default);
+}
+
+/**
+ *   open, inputs   { name: { type: string|number|boolean|date, label, default, required, options } }
+ *   onRun(values), onCancel()
+ */
+export function RunInputs({ open, inputs, onRun, onCancel }) {
+  const names = Object.keys(inputs ?? {});
+  const [values, setValues] = useState(() => Object.fromEntries(names.map((n) => [n, initial(inputs[n])])));
+  const id = useId();
+  const missing = names.filter((n) => inputs[n].required && inputs[n].type !== "boolean" && String(values[n] ?? "").trim() === "");
+
+  const submit = () => {
+    const out = {};
+    for (const n of names) {
+      const spec = inputs[n];
+      const v = values[n];
+      if (spec.type === "boolean") out[n] = v === true;
+      else if (String(v ?? "").trim() === "") continue;
+      else out[n] = spec.type === "number" ? Number(v) : String(v);
+    }
+    onRun(out);
+  };
+
+  return (
+    <Sheet
+      open={open}
+      onClose={onCancel}
+      side="center"
+      title="Test run"
+      footer={
+        <>
+          <Button variant="quiet" onClick={onCancel}>
+            Cancel
+          </Button>
+          <Button variant="primary" disabled={missing.length > 0} onClick={submit}>
+            Run it
+          </Button>
+        </>
+      }
+    >
+      <form
+        className="grid gap-4"
+        onSubmit={(e) => {
+          e.preventDefault();
+          if (!missing.length) submit();
+        }}
+      >
+        <p className="m-0 text-sm text-muted-foreground">It runs once with real data. Nothing is sent or changed by a step marked as a pencil draft.</p>
+        {names.map((n, i) => {
+          const spec = inputs[n];
+          const fid = `${id}-${i}`;
+          const label = `${spec.label || n}${spec.required ? " *" : ""}`;
+          if (spec.type === "boolean") {
+            return <Checkbox key={n} id={fid} label={label} checked={values[n] === true} onChange={(e) => setValues({ ...values, [n]: e.target.checked })} />;
+          }
+          return (
+            <Field key={n} id={fid} label={label}>
+              {spec.options?.length ? (
+                <Select id={fid} value={String(values[n] ?? "")} options={[{ value: "", label: "" }, ...spec.options.map((o) => ({ value: o, label: o }))]} onChange={(e) => setValues({ ...values, [n]: e.target.value })} />
+              ) : (
+                <Input id={fid} type={spec.type === "number" ? "number" : spec.type === "date" ? "date" : "text"} value={String(values[n] ?? "")} onChange={(e) => setValues({ ...values, [n]: e.target.value })} />
+              )}
+            </Field>
+          );
+        })}
+      </form>
+    </Sheet>
+  );
+}

package/registry/blocks/automation-list/README.md

@@ -0,0 +1,129 @@
+# AutomationList
+
+An app's automations as rows. **The whole row opens the automation** (a
+stretched button under the switch), so a member is never hunting for a
+small arrow. Each row says what it is called and when it runs (in words, in
+the automation's own time zone), how its last run went as a dot and a word
+(Healthy, Last run failed, Needs its owner, Waiting, Running, Off, Not live
+yet), when the next is due, what the last one cost, and an on/off switch
+that keeps its own press.
+
+- A line above the rows counts what is on, what failed last time, what
+  waits for its owner, and which runs next.
+- A search box; **New automation** (a picker of starting points once there
+  are some, straight to a blank when there are none).
+- **First run** — with no automations, a few ready-made flows to start
+  from (a Monday reminder, check then tell me, wait then follow up, an
+  app's action every morning, ask the model for a line).
+- **Describe it** (with `onDescribe`) — a box at the top, above the rows, on
+  the first-run screen and in the New automation sheet: say what it should
+  do in a sentence, press "Draft it" (the button carries its price), and the
+  platform draws it; it opens when ready. It says "Drawing it…" while it
+  works. A question back is listed under the box ("Ask me about: …"); any
+  other refusal shows its words. Three chips start the sentence. Without
+  `onDescribe` nothing changes.
+- On a team page, the rows are grouped Team and From <app>; on an app's
+  own page pass `grouped={false}`.
+
+```jsx
+import { AutomationList } from "../components/blocks/automation-list";   // a Makersclaw app
+import { AutomationList } from "@/components/makersclaw/blocks/automation-list";   // a shadcn project
+```
+
+`makersclaw add automation-list` lays `automation-model` with it. A client
+component. It replaces `schedule-card` for an app whose jobs run on the
+automations engine (the card still works for an app that has not moved).
+Its own width decides its layout: under about 576 px a row stacks its
+facts under its name.
+
+## Props
+
+- `rows` — the list: `useAutomations().automations`. Each: `{ id, name,
+  key, status (on · off · draft · needs_owner), live_version, trigger,
+  next_run_at, tz, last_run: { status, started_at, credits }, active_runs,
+  edited, owner_kind, app_id }`.
+- `onOpen(id)` — a whole row was pressed.
+- `onNew(start?)` — New automation; `start` is a starting point (`{ id,
+  name, build(takenKeys) }`) when one was picked, else a blank is meant.
+- `onDelete(row)` — async: **Delete automation**, in a menu on each row. It
+  asks first, in words that say what it does (`Deletes "<name>". Its runs
+  stay in history.`, and for a row that is on, that deleting also switches it
+  off). Resolves `{ ok: true }` (the screen says what followed) or `{ ok:
+  false, error }` (shown above the rows as it is). A row from an app's own job
+  or one an app shipped (`row.source` `legacy`, `package`) has the item
+  disabled, pointing at the app's settings. `canDelete` hides the menu
+  (default true). Without `onDelete`, no menu.
+- `onToggle(row, on)` — async; the switch. A refusal throws its words
+  (shown above the rows). `canToggle` — draw the switch (default true).
+  `canCreate` — draw New automation (default true).
+- `appName(id)`, `appFilter`, `onClearFilter`, `grouped`.
+- `query`, `onQueryChange(text)`: the search box starts with `query` and reports each change. A screen that opens an automation and comes back keeps the words in its own place and hands them back, so the list returns as it was left.
+- `starts` — your own starting points (default automation-model's
+  `STARTING_POINTS`). An app offers flows that name its own actions here.
+  The platform's own come through `startsFromPlatform(useAutomations().starts)`
+  (automation-model): each card then also says what it needs, what a model
+  does and what it costs ("needs payments, a mailbox · a model writes three
+  lines · about 6 cr", or "free"). The raw list is also accepted.
+- `onDescribe(ask)` — async: `useAutomations().describe`. Resolves `{ ok,
+  id }` (the list calls `onOpen(id)`), `{ ok: true }` with no id (the
+  sentence was handed on, to an agent beside the list say: the box empties),
+  `{ ok: false, questions }` or `{ ok: false, error }`. `describePrice` — what the button says it costs (default
+  "1 call · about 1 cr"); `describeChips` — the sentences that start the
+  box (default three).
+- `title`, `intro`, `now` (the clock, for a test), `className`.
+
+### StartingPoints
+
+The picker New automation opens: `open`, `onClose`, `starts`, `onPick(s)`,
+`onBlank()`, and (for Describe it) `onDescribe`, `onOpen`, `describePrice`,
+`describeChips`. With Describe it, the ready-made ones sit under "Start from
+a ready one".
+
+## Hooks (lib/hooks.js)
+
+`useAutomations()` → `{ automations, triggers, starts, describe(ask, app?),
+describing, busy, creating, setStatus(id, on), create(definition), loading,
+error, unavailable, reload }`. It reads
+`GET _claw/automations`; `setStatus` patches `status`; `create` posts a
+definition and resolves `{ ok, data: { id } }` or `{ ok: false, error,
+problems }`. Looks every 30 s (5 s while one runs), not at all while the
+page is hidden. On a claw from before the engine it is `unavailable`:
+show a quiet "not set up yet". `starts` is `[]`: the desk's starting points are not served to an app
+(`_claw/automation-starts` does not exist), so the lib asks nothing and
+an app brings its own; `describe(ask, app?)` posts `_claw/automation-draft`
+and resolves `{ ok: true, id, … }`, `{ ok: false, error, code, questions? }`
+or `{ ok: false, code: "unavailable" }`, never thrown.
+
+## Never
+
+- Never switch an automation on that has no version kept: the switch is
+  disabled until one is (`live_version`).
+- Never show a time in the viewer's zone: `next_run_at` is shown in `tz`.
+
+## Example
+
+```jsx
+"use client";
+import { useRouter } from "next/navigation";
+import { useAutomations } from "../lib/hooks";
+import { AutomationList } from "../components/blocks/automation-list";
+
+export default function Automations() {
+  const router = useRouter();
+  const { automations, setStatus, unavailable } = useAutomations();
+  if (unavailable) return <p className="p-4 text-sm text-muted-foreground">Automations are not set up here yet.</p>;
+  return (
+    <AutomationList
+      rows={automations}
+      grouped={false}
+      title="Automations"
+      onOpen={(id) => router.push(`?automation=${id}`)}
+      onToggle={async (row, on) => {
+        const r = await setStatus(row.id, on);
+        if (!r.ok) throw new Error(r.error);
+      }}
+      onNew={(start) => router.push(`?automation=new${start ? `&start=${start.id}` : ""}`)}
+    />
+  );
+}
+```