makersclaw 0.8.0 → 0.8.1

package/registry/blocks/data-picker/data-picker.jsx

@@ -0,0 +1,210 @@
+"use client";
+
+// Mapping data from earlier steps into a field. The menu lists what a step
+// may read: this run (when it started, the clock), this item (inside a
+// for-each) and every earlier step's output, and where a real run left a
+// sample, the fields inside it with a taste of their values. A press
+// inserts `{{ steps.mail.output.messages }}` where the cursor was. The
+// platform checks every reference when the automation is saved.
+//
+// DataInput is a labelled text field (one line or several) with the menu
+// beside it; DataPairs is a list of name and value rows (a step's input,
+// a Set's values), each value with its own menu. Props in, callbacks out;
+// tokens only.
+
+import { useId, useRef, useState } from "react";
+import { Field, Input, Popover, Textarea, cx } from "../../ui";
+import { textToValue, valueToText } from "../automation-model";
+import { menuGroups } from "./fields";
+
+const ROW = "flex w-full min-w-0 items-baseline justify-between gap-3 rounded-md px-2 py-1.5 text-left text-[13px] hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+
+/**
+ * The menu itself, for a place of your own.
+ *   available   automation-model's availableBefore()
+ *   samples     { [stepId]: a real output } or null
+ *   onPick(text)
+ */
+export function DataPicker({ available, samples = null, onPick }) {
+  const groups = menuGroups(available, samples);
+  return (
+    <div role="menu" aria-label="Insert data" className="grid gap-1">
+      {groups.map((g) => (
+        <section key={g.title} className="grid gap-px">
+          <h5 className="m-0 px-2 pt-1.5 text-2xs font-semibold uppercase tracking-wide text-muted-foreground">{g.title}</h5>
+          {g.items.map((it) =>
+            it.fields?.length ? (
+              <details key={it.text} className="group">
+                <summary className={cx(ROW, "cursor-pointer list-none")}>
+                  <span className="min-w-0 truncate">{it.label}</span>
+                  <span className="shrink-0 text-xs text-muted-foreground">{it.preview}</span>
+                </summary>
+                <div className="grid gap-px border-l border-border pl-2 ml-3">
+                  <button type="button" role="menuitem" onClick={() => onPick(it.text)} className={ROW}>
+                    <span className="min-w-0 truncate">Everything it made</span>
+                    <span className="shrink-0 font-mono text-2xs text-muted-foreground">output</span>
+                  </button>
+                  {it.fields.map((f) => (
+                    <button key={f.path} type="button" role="menuitem" onClick={() => onPick(f.text)} className={ROW}>
+                      <span className="min-w-0 truncate font-mono text-xs">{f.label}</span>
+                      <span className="shrink-0 text-xs text-muted-foreground">{f.preview}</span>
+                    </button>
+                  ))}
+                </div>
+              </details>
+            ) : (
+              <button key={it.text} type="button" role="menuitem" onClick={() => onPick(it.text)} className={ROW}>
+                <span className="min-w-0 truncate">{it.label}</span>
+                {it.preview ? <span className="shrink-0 text-xs text-muted-foreground">{it.preview}</span> : it.hint ? <span className="shrink-0 font-mono text-2xs text-muted-foreground">{it.hint}</span> : null}
+              </button>
+            ),
+          )}
+        </section>
+      ))}
+      <p className="m-0 px-2 pb-1 pt-0.5 text-xs text-muted-foreground">It goes in where the cursor is, and the step it comes from runs first.</p>
+    </div>
+  );
+}
+
+/** The { } button and its menu, for a field of your own. */
+export function DataButton({ available, samples, onPick, disabled }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <Popover
+      open={open}
+      onOpenChange={setOpen}
+      side="bottom"
+      align="end"
+      width="md"
+      label="Insert data"
+      className="max-h-80 overflow-y-auto p-1"
+      trigger={(props) => (
+        <button
+          {...props}
+          type="button"
+          disabled={disabled}
+          title="Insert data from an earlier step"
+          className="inline-flex size-9 shrink-0 items-center justify-center rounded-md border border-border bg-secondary font-mono text-xs text-secondary-foreground hover:bg-accent disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          {"{ }"}
+        </button>
+      )}
+    >
+      <DataPicker
+        available={available}
+        samples={samples}
+        onPick={(text) => {
+          onPick(text);
+          setOpen(false);
+        }}
+      />
+    </Popover>
+  );
+}
+
+/** Put `text` into `value` where the caret was, and say where the caret goes. */
+function splice(value, caret, text) {
+  const at = Math.min(caret?.start ?? value.length, value.length);
+  const end = Math.min(caret?.end ?? at, value.length);
+  return { next: `${value.slice(0, at)}${text}${value.slice(end)}`, caret: { start: at + text.length, end: at + text.length } };
+}
+
+/**
+ * A labelled text field. With `available`, a { } button beside it.
+ *   label, value, onChange(text), help, placeholder, mono, multiline, rows, disabled
+ *   available   automation-model's availableBefore(); leave out for plain text
+ *   samples     { [stepId]: a real output } or null
+ */
+export function DataInput({ label, value, onChange, help, placeholder, mono = false, multiline = false, rows = 4, available, samples, disabled = false }) {
+  const id = useId();
+  const caret = useRef(null);
+  const remember = (el) => {
+    caret.current = { start: el.selectionStart ?? el.value.length, end: el.selectionEnd ?? el.value.length };
+  };
+  const insert = (text) => {
+    const r = splice(value, caret.current, text);
+    caret.current = r.caret;
+    onChange(r.next);
+  };
+  const common = { id, value, disabled, placeholder, className: mono ? "font-mono text-[13px]" : undefined, onChange: (e) => onChange(e.target.value), onBlur: (e) => remember(e.currentTarget) };
+  return (
+    <Field id={id} label={label} hint={help}>
+      <div className="flex min-w-0 items-start gap-1.5">
+        <div className="min-w-0 flex-1">{multiline ? <Textarea {...common} rows={rows} /> : <Input {...common} type="text" />}</div>
+        {available && !disabled ? <DataButton available={available} samples={samples} onPick={insert} /> : null}
+      </div>
+    </Field>
+  );
+}
+
+/**
+ * A list of name and value rows (a step's `input`, a Set's `values`).
+ *   value       { name: value }
+ *   onChange(next)
+ *   keyLabel, addLabel, help, available, samples, disabled
+ */
+export function DataPairs({ label, value, onChange, help, available, samples, disabled = false, keyLabel = "Name", addLabel = "Add a field" }) {
+  const entries = Object.entries(value ?? {});
+  const setAt = (i, key, text) => {
+    const next = entries.map(([k, v]) => [k, v]);
+    // A name another row already has would swallow it: keep what was typed apart.
+    if (text !== null && entries.some(([other], j) => j !== i && other === key)) return;
+    if (text === null) next.splice(i, 1);
+    else next[i] = [key, textToValue(text)];
+    onChange(Object.fromEntries(next));
+  };
+  return (
+    <fieldset className="m-0 grid min-w-0 gap-2 border-0 p-0">
+      <legend className="mb-1.5 p-0 text-sm font-medium text-foreground">{label}</legend>
+      {entries.length === 0 ? <p className="m-0 text-xs text-muted-foreground">Nothing yet.</p> : null}
+      {entries.map(([k, v], i) => (
+        <PairRow key={i} index={i} k={k} text={valueToText(v)} keyLabel={keyLabel} available={available} samples={samples} disabled={disabled} onChange={(key, text) => setAt(i, key, text)} onRemove={() => setAt(i, k, null)} />
+      ))}
+      {!disabled ? (
+        <button
+          type="button"
+          onClick={() => {
+            let n = entries.length + 1;
+            while (value && `field_${n}` in value) n += 1;
+            onChange({ ...(value ?? {}), [`field_${n}`]: "" });
+          }}
+          className="inline-flex min-h-9 items-center justify-self-start rounded-md border border-border bg-secondary px-3 text-sm text-secondary-foreground hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          + {addLabel}
+        </button>
+      ) : null}
+      {help ? <p className="m-0 text-xs text-muted-foreground">{help}</p> : null}
+    </fieldset>
+  );
+}
+
+function PairRow({ index, k, text, keyLabel, available, samples, disabled, onChange, onRemove }) {
+  const caret = useRef(null);
+  const insert = (t) => {
+    const r = splice(text, caret.current, t);
+    caret.current = r.caret;
+    onChange(k, r.next);
+  };
+  return (
+    <div className="flex min-w-0 items-center gap-1.5">
+      <Input className="w-[34%] min-w-0 font-mono text-[13px]" aria-label={`${keyLabel} ${index + 1}`} value={k} disabled={disabled} onChange={(e) => onChange(e.target.value, text)} />
+      <Input
+        className="min-w-0 flex-1 font-mono text-[13px]"
+        aria-label={`Value ${index + 1}`}
+        value={text}
+        disabled={disabled}
+        placeholder="a value, or {{ data }}"
+        onChange={(e) => onChange(k, e.target.value)}
+        onBlur={(e) => {
+          caret.current = { start: e.currentTarget.selectionStart ?? text.length, end: e.currentTarget.selectionEnd ?? text.length };
+        }}
+      />
+      {available && !disabled ? <DataButton available={available} samples={samples} onPick={insert} /> : null}
+      {!disabled ? (
+        <button type="button" aria-label={`Remove ${k || "field"}`} onClick={onRemove} className="inline-flex size-9 shrink-0 items-center justify-center rounded-md text-muted-foreground hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+          ×
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/registry/blocks/data-picker/demo.jsx

@@ -0,0 +1,34 @@
+"use client";
+
+// DataInput and DataPairs over a pretend run — the gallery's and the smoke
+// test's surface. Not installed into apps. Press { } beside a field: the
+// menu lists this run, the item, the questions and the earlier steps, and
+// opens a step to its fields with a taste of their values.
+import { useState } from "react";
+import { DataInput, DataPairs } from "../components/blocks/data-picker";
+
+const AVAILABLE = {
+  steps: [
+    { id: "mail", kind: "tool", label: "Read the mail since the last read" },
+    { id: "touches", kind: "action", label: "Save who wrote" },
+  ],
+  inLoop: true,
+  inputs: [{ name: "since", label: "Since when" }],
+};
+const OUTPUTS = {
+  mail: { count: 12, messages: [{ from: "ana@x.com", subject: "Quote for Q4", unread: true }] },
+  touches: { saved: 4, owed: [{ id: "p1", name: "Ana" }] },
+};
+
+export default function DataPickerDemo() {
+  const [message, setMessage] = useState("Read {{ steps.mail.output.count }} emails since {{ inputs.since }}.");
+  const [input, setInput] = useState({ person: "{{ item.id }}", limit: 20, note: "" });
+  return (
+    <div className="grid max-w-md gap-6 p-4">
+      <DataInput label="Message" value={message} onChange={setMessage} multiline rows={3} available={AVAILABLE} samples={OUTPUTS} help="Press { } to insert data." />
+      <DataInput label="Condition" value="{{ steps.touches.output.saved > 0 }}" onChange={() => {}} mono available={AVAILABLE} samples={OUTPUTS} />
+      <DataPairs label="What to give it" value={input} onChange={setInput} available={AVAILABLE} samples={OUTPUTS} />
+      <pre className="m-0 overflow-auto rounded-md bg-muted p-2 font-mono text-xs">{JSON.stringify({ message, input }, null, 2)}</pre>
+    </div>
+  );
+}

package/registry/blocks/data-picker/fields.js

@@ -0,0 +1,89 @@
+// The pure part of the data picker: what can be pointed at, as text.
+//
+// A step reads an earlier step's output with `{{ steps.read_mail.output.messages }}`.
+// The picker offers the trigger, the clock, the loop's item, and every
+// earlier step's output, and, when a real run left a sample of an output,
+// the fields inside it with a taste of their values, so a person picks
+// what they can see.
+
+const MAX_FIELDS = 24;
+const MAX_DEPTH = 3;
+
+/** A value as a short taste: "ana@x.com", "12 items", "yes". */
+export function preview(value) {
+  if (value === null || value === undefined) return "empty";
+  if (typeof value === "string") return value.length > 40 ? `${value.slice(0, 39)}…` : value || "empty text";
+  if (typeof value === "number") return String(value);
+  if (typeof value === "boolean") return value ? "yes" : "no";
+  if (Array.isArray(value)) return value.length === 1 ? "1 item" : `${value.length} items`;
+  return "a record";
+}
+
+/**
+ * The fields inside a sample, as [{ path, text, label, preview }]:
+ * `path` is what goes after `steps.<id>.output` (".messages[0].from"),
+ * `text` the whole reference. Objects go down a few levels; a list shows
+ * its first item's fields under `[0]`. A key that is not a plain name
+ * (spaces, dashes) is left out: the expression language cannot read it.
+ */
+export function fieldsOf(sample, base, depth = 0, out = [], path = "") {
+  if (depth >= MAX_DEPTH || out.length >= MAX_FIELDS || sample === null || typeof sample !== "object") return out;
+  const list = Array.isArray(sample);
+  const entries = list ? (sample.length ? [[0, sample[0]]] : []) : Object.entries(sample).filter(([key]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key));
+  for (const [key, value] of entries) {
+    if (out.length >= MAX_FIELDS) break;
+    const next = list ? `${path}[${key}]` : `${path}.${key}`;
+    out.push({ path: next, text: `{{ ${base}${next} }}`, label: next.replace(/^\./, ""), preview: preview(value) });
+    if (value && typeof value === "object") fieldsOf(value, base, depth + 1, out, next);
+  }
+  return out;
+}
+
+/**
+ * The groups the menu shows.
+ *   available   automation-model's availableBefore(): { steps: [{ id, kind, label }], inLoop },
+ *               and optionally `inputs: [{ name, label }]`, what a manual run asks first
+ *   samples     { [stepId]: a real output } or null
+ * → [{ title, items: [{ text, label, hint?, preview?, fields? }] }]
+ */
+export function menuGroups(available, samples = null) {
+  const groups = [
+    {
+      title: "This run",
+      items: [
+        { text: "{{ trigger.at }}", label: "When it started", hint: "trigger.at" },
+        { text: "{{ now }}", label: "Right now", hint: "now" },
+        { text: "{{ run.id }}", label: "This run's id", hint: "run.id" },
+      ],
+    },
+  ];
+  if (available?.inputs?.length) {
+    groups.push({ title: "Your questions", items: available.inputs.map((q) => ({ text: `{{ inputs.${q.name} }}`, label: q.label || q.name, hint: `inputs.${q.name}` })) });
+  }
+  if (available?.inLoop) {
+    groups.push({
+      title: "This item",
+      items: [
+        { text: "{{ item }}", label: "The item", hint: "item" },
+        { text: "{{ index }}", label: "Its place in the list", hint: "index" },
+      ],
+    });
+  }
+  if (available?.steps?.length) {
+    groups.push({
+      title: "Earlier steps",
+      items: [...available.steps].reverse().map((s) => {
+        const base = `steps.${s.id}.output`;
+        const sample = samples ? samples[s.id] : undefined;
+        return {
+          text: `{{ ${base} }}`,
+          label: s.label,
+          hint: base,
+          preview: sample === undefined ? undefined : preview(sample),
+          fields: sample && typeof sample === "object" ? fieldsOf(sample, base) : undefined,
+        };
+      }),
+    });
+  }
+  return groups;
+}

package/registry/blocks/data-picker/index.js

@@ -0,0 +1,4 @@
+// The DataPicker block — `makersclaw add data-picker`. Fixed: compose it
+// through its props (README.md beside this file).
+export { DataButton, DataInput, DataPairs, DataPicker } from "./data-picker";
+export { fieldsOf, menuGroups, preview } from "./fields";

package/registry/blocks/data-table/demo.jsx

@@ -282,7 +282,7 @@ function Orders() {
         <p className="mt-1 text-sm text-muted-foreground">Your recent orders, and the invoice for each.</p>
       </div>
       <Card padding="none" className="flex flex-wrap items-center justify-between gap-4 p-4">
-        <StatGroup variant="divided" columns={3} className="min-w-0 flex-1">
+        <StatGroup variant="divided" columns={3} className="min-w-0 flex-1 basis-64">
           <Stat label="Order" value={ORDER.number} size="sm" />
           <Stat label="Placed" value={date(ORDER.placed)} size="sm" />
           <Stat label="Total" value={money(ORDER.total)} size="sm" />

package/registry/blocks/first-run/README.md

@@ -0,0 +1,118 @@
+# FirstRun
+
+An app's first page, before anything is made (0.8.1). Working-tool style, not
+a landing page.
+
+The founder's review of Gantt Planner, 2026-10-12: its home was a 52px hero
+("Plan a project that lands on its date."), four stacked cards, a big example
+chart and a second shelf, and it "reads like a website, not an app's home".
+Roadmap's first run and Newsletter's differed again. Each app had invented
+its own. This is the one.
+
+In order, at the kit's normal sizes:
+
+1. **One plain heading line**, and one line of what the app does.
+2. **The first steps in a row** (action cards), offered in a fixed order
+   whatever order you list them in: the agent's way in, then making the first
+   thing yourself, then starting from the Library, then bringing it in from
+   another tool. The first is the page's one main button.
+3. **The starting points shelf**: your `LibraryShelf`, passed as a node.
+4. **What the agent will do**, and **the accounts it can use**, side by side.
+5. **A worked example, behind "See an example".** It never fills the page.
+
+A step with nothing to press is dropped: a card with no action is a lie.
+
+**An agent step never opens a form first.** Its `onClick` opens the agent's
+dock with a starting line ("Draft a project plan for me") and the agent asks
+for what it is missing, in chat, then makes the thing through the app's own
+actions. A form belongs to "type it yourself". (UI review X9: the founder,
+"the agent should be able to create these".)
+
+**One column; a form is revealed in the main flow.** The block has no side
+column. A "Name it" or "Paste a list" step, when pressed, reveals its own
+card under the steps (`children`), in the page's own scroll, and the shelf
+and the rest move down. Never put that form in a side column beside a short
+intro: the side is the fixed, short one and the main is the one that scrolls
+(UI review X13: the founder, looking at exactly that, "one small column and
+then all the card long scrolling in other column"). `npm run check` (rule
+`sidelong`) refuses an app that does.
+
+`npm run check` (rule `hero`) refuses an `<h1>` at 36px or more, so the page
+cannot go back to a hero.
+
+```jsx
+import { FirstRun } from "../components/blocks/first-run";   // a Makersclaw app ("./blocks/first-run" from components/)
+import { FirstRun } from "@/components/makersclaw/blocks/first-run";   // a shadcn project
+```
+
+A client component. It needs the kit and nothing else; the shelf, the
+accounts and the example come in as nodes.
+
+## Adopting it (an app that drew its own)
+
+1. Delete the app's own first-run page's layout: the hero, the card grid,
+   the headings of "what the agent will do" and "accounts". Keep what is the
+   app's: its copy, its starting points (`LibraryShelf`), its connect rows.
+2. Return `<FirstRun title lede choices shelf agentDoes accounts example />`
+   from the same place, inside the screen's `AppLayout` (the page pads
+   itself).
+3. Put the worked example behind `example`: `onOpen` if the app has an
+   example mode (Roadmap's `lookAround`), or `children` to reveal in place.
+   Do not draw it on the page.
+4. Make the agent step an opener of the dock, not a link to a form.
+
+## Props
+
+- `title`: the heading, one plain line.
+- `lede`: one line of what the app does and what happens next.
+- `notice`: a node above the steps (a `Notice`).
+- `choices`: `[{ key, kind, icon, title, description, action, status, note }]`.
+  `kind`: `agent` · `hand` · `library` · `import` · `other`. `action`:
+  `{ label, href | onClick, icon, cost, variant, disabled, loading }`; `cost`
+  is a node after the label (a `CostTag`). `status`: an ActionCard's
+  `{ tone, children }` ("Connected" only when an account is listed). `note`:
+  a node between the description and the status.
+- `children`: a node after the steps, in the main flow (a card that reveals
+  the form to name the first thing when its step is pressed).
+- `shelf`: your starting points, as a node.
+- `agentDoes`: `[{ name, when, what, cost }]`; `agentTitle`.
+- `accounts`: a node; `accountsTitle` (default "Accounts, all optional").
+- `example`: `{ label, title, description, onOpen, children }`.
+- `className`: spacing around the page.
+
+## The model (plain functions)
+
+`orderChoices(choices)`, `stepsOf(choices)` (ordered, each with its `variant`),
+`variantFor(choice, index)`, `columnsFor(count)` (the container classes that
+set how many sit in a row), `stepsWords(count)`, `KINDS`.
+
+## Example
+
+```jsx
+// components/first-run-page.jsx
+"use client";
+import { FirstRun } from "./blocks/first-run";
+import { openAgent } from "./blocks/agent-dock";
+
+export function Nothing({ onType, onLibrary }) {
+  return (
+    <FirstRun
+      title="Nothing is planned here yet."
+      lede="Add one project. From the next weekday at 9:00 the agent checks the plan and tells you which dates will slip."
+      choices={[
+        { kind: "hand", icon: "plus", title: "Add the first project", description: "A name, a start and a target.", action: { label: "New project", onClick: onType } },
+        { kind: "agent", icon: "sparkles", title: "Have the agent draft it", description: "Say what you are building; it asks for what it is missing.", action: { label: "Draft with the agent", onClick: () => openAgent("Draft a project plan for me") } },
+        { kind: "library", icon: "layers", title: "Start from a starting point", description: "Phases and tasks already set.", action: { label: "Browse", onClick: onLibrary } },
+      ]}
+      example={{ title: "See it working first", description: "A made-up team of seven, read only.", onOpen: () => {} }}
+    />
+  );
+}
+```
+
+## States drawn in the demo
+
+A plan's first run (four steps, listed out of order, a shelf, what the agent
+will do, accounts, an example mode); a newsletter's (three steps, a Notice
+above, an example revealed in place); the smallest (one heading, one line, one
+step).

package/registry/blocks/first-run/block.json

@@ -0,0 +1,11 @@
+{
+  "name": "first-run",
+  "title": "FirstRun",
+  "description": "An app's first page, before anything is made, in working-tool style and not a landing page. In order, at the kit's normal sizes: one plain heading line and one line of what the app does; the first steps in a row as action cards, offered in a fixed order whatever order the app lists them in (the agent's way in first, then making the first thing yourself, then starting from the Library, then bringing it in from another tool; the first is the page's one main button, and a step with nothing to press is dropped); the starting points shelf (the app's LibraryShelf, passed as a node); what the agent will do by itself and the accounts it can use, side by side; and a worked example behind a \"See an example\" button, either revealed in place or handed to the app's own example mode, never filling the page. A node above the steps takes a Notice, a node after them a form. An agent step opens the agent's dock with a starting line and lets the agent ask for what it is missing; it never opens a form first. `npm run check` refuses an <h1> at 36px or more. The step order, the row width and the variants are exported as plain functions.",
+  "useWhen": "Every app's first run: the page an app opens on while it has nothing yet, replacing each app's own components/<app>/first-run.jsx or home hero (Project Roadmap's four start cards, Newsletter Engine's start page, Gantt Planner's hero). Not for a screen that shows data (that is the app's own home), not an empty list inside a screen (the kit's Empty), and not a setup checklist that stays on the page after the first run (setup-checklist).",
+  "tags": ["first run", "home", "welcome", "start", "onboarding", "empty", "getting started", "starting points", "agent", "example", "steps"],
+  "exports": ["FirstRun", "KINDS", "columnsFor", "orderChoices", "stepsOf", "stepsWords", "variantFor"],
+  "files": ["index.js", "first-run.jsx", "first-run-model.js", "probe-rules.js"],
+  "requires": [],
+  "offer": { "since": "0.8.1", "why": "the shared first page before anything is made (the agent's way in first, the starting points), in place of the app's own hero and card grid" }
+}

package/registry/blocks/first-run/demo.jsx

@@ -0,0 +1,88 @@
+"use client";
+
+// FirstRun in the three shapes the apps had — the gallery's and the smoke
+// test's surface. Not installed into apps: `makersclaw add first-run` lays
+// index.js, first-run.jsx and first-run-model.js only.
+//   A plan         four steps, the agent's first (given last: the page
+//                  reorders), a starting points shelf, what the agent will
+//                  do, accounts, and a worked example behind a button
+//                  (Project Roadmap's and Gantt Planner's first run).
+//   A newsletter   three steps, a form between the steps and the shelf, a
+//                  Notice above (Newsletter Engine's first run).
+//   The smallest   one heading, one line, one step.
+import { useState } from "react";
+import { Notice } from "../components/ui";
+import { FirstRun } from "../components/blocks/first-run";
+import { openAgent } from "../components/blocks/agent-dock";
+
+const COST = <span className="font-normal text-muted-foreground">about 150 to 300 cr</span>;
+
+function Shelf({ title }) {
+  return (
+    <section aria-label={title} className="grid gap-2">
+      <h2 className="text-xs font-semibold uppercase tracking-[0.06em] text-muted-foreground">{title}</h2>
+      <ul className="m-0 grid list-none gap-2 p-0 @xl:grid-cols-3">
+        {["Website launch", "Product release", "Event"].map((name) => (
+          <li key={name} className="rounded-lg border border-border bg-card p-3 text-sm">
+            <p className="font-semibold">{name}</p>
+            <p className="text-xs text-muted-foreground">5 phases · 28 tasks</p>
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+export default function FirstRunDemo() {
+  const [log, setLog] = useState("Nothing pressed yet.");
+  const say = (what) => () => setLog(what);
+  return (
+    <div className="grid gap-8">
+      <p role="status" className="text-xs text-muted-foreground">
+        {log}
+      </p>
+
+      <section className="rounded-lg border border-border">
+        <FirstRun
+          title="Nothing is planned here yet."
+          lede="Add your team and one project. From the next weekday at 9:00 the agent checks the plan and tells you which dates will slip, by how much, and the fix."
+          choices={[
+            { key: "import", kind: "import", icon: "download", title: "Import open issues", description: "Bring GitHub or Linear issues in as tasks. A preview comes first; you pick.", status: { tone: "neutral", children: "Not connected" }, action: { label: "Choose a source", onClick: say("Import") } },
+            { key: "library", kind: "library", icon: "layers", title: "Start from a starting point", description: "Eight project shapes with phases, tasks and waits already set. Free.", action: { label: "Browse starting points", onClick: say("Library") } },
+            { key: "hand", kind: "hand", icon: "plus", title: "Add the first project yourself", description: "A name, a start and a target; then type the tasks.", action: { label: "New project", onClick: say("By hand") } },
+            { key: "agent", kind: "agent", icon: "sparkles", title: "Have the agent draft it", description: "Say what you are building. The agent asks for what it is missing and drafts the phases and tasks for you to review.", action: { label: "Draft with the agent", cost: COST, onClick: () => { openAgent("Draft a project plan for me"); setLog("Agent: opens the dock with a starting line"); } } },
+          ]}
+          shelf={<Shelf title="Start from a template" />}
+          agentDoes={[
+            { name: "Daily check", when: "Weekdays 9:00", what: "Counts what is late, blocked or unowned and proposes up to five fixes. You apply or dismiss each one.", cost: "up to 40 cr a run" },
+            { name: "Monday update", when: "Mondays 9:30", what: "Writes what shipped, what is on, what is at risk. A post waits for your yes.", cost: "up to 60 cr a run" },
+          ]}
+          accounts={<p className="text-sm text-muted-foreground">GitHub and Linear would import issues. A chat account would carry the Monday update, after your yes. The app is complete without them.</p>}
+          example={{ title: "See it working first: Larkline, a team of seven", description: "Example data, marked as an example everywhere, and read only.", onOpen: say("Example opened") }}
+        />
+      </section>
+
+      <section className="rounded-lg border border-border">
+        <FirstRun
+          title="Start your newsletter."
+          lede="Every Monday the agent reads what you shipped and drafts the issue in your voice. Nothing reaches a reader until you say yes."
+          notice={
+            <Notice tone="warning" title="Before issue 1 can be made ready">
+              Add the postal address for the footer and connect an email platform.
+            </Notice>
+          }
+          choices={[
+            { key: "hand", kind: "hand", icon: "pencil", title: "Start issue 1 by hand", description: "Write it here.", action: { label: "Start issue 1", onClick: say("Hand") } },
+            { key: "agent", kind: "agent", icon: "sparkles", title: "Draft issue 1", description: "The agent reads what shipped and drafts it.", action: { label: "Draft with the agent", onClick: () => { openAgent("Draft issue 1 for me"); setLog("Agent: opens the dock with a starting line"); } } },
+            { key: "lib", kind: "library", icon: "layers", title: "Begin from a shape", description: "Four issue shapes.", action: { label: "Pick a shape", onClick: say("Shape") } },
+          ]}
+          example={{ label: "See an example", title: "What it will do", description: "A worked example, invented.", children: <p className="rounded-lg border border-border bg-muted p-4 text-sm">The engineer's line on the left, your reader's paragraph on the right.</p> }}
+        />
+      </section>
+
+      <section className="rounded-lg border border-border">
+        <FirstRun title="No clients yet." lede="Add a client and the agent keeps their minutes." choices={[{ key: "hand", kind: "hand", icon: "plus", title: "Add a client", action: { label: "Add a client", onClick: say("Client") } }]} />
+      </section>
+    </div>
+  );
+}

package/registry/blocks/first-run/first-run-model.js

@@ -0,0 +1,51 @@
+// The first run's rules as plain functions: the order the first steps are
+// offered in, how many sit in a row at which width, and which step is the
+// page's one main button. No React here.
+//
+// The order is the founder's (UI review X9, 2026-10-12): "the agent should be
+// able to create these". The agent's way in comes first, then making the
+// first thing yourself, then starting from the Library, then bringing it in
+// from another tool. An app lists its steps in any order; the page offers
+// them in this one.
+
+export const KINDS = ["agent", "hand", "library", "import", "other"];
+
+/** The steps in the order they are offered; steps of one kind keep the order
+ *  given. A step with no kind goes last. A step without a way to take it
+ *  (no `action`) is dropped: a card with nothing to press is a lie. */
+export function orderChoices(choices) {
+  const rank = (c) => {
+    const i = KINDS.indexOf(c?.kind);
+    return i < 0 ? KINDS.length - 1 : i;
+  };
+  return (choices ?? [])
+    .map((c, at) => ({ c, at }))
+    .filter(({ c }) => c && c.title && c.action && (c.action.href || typeof c.action.onClick === "function") && c.action.label)
+    .sort((a, b) => rank(a.c) - rank(b.c) || a.at - b.at)
+    .map(({ c }) => c);
+}
+
+/** The container classes that set how many steps sit in a row: the page's
+ *  own width, whole class names for Tailwind. */
+export function columnsFor(count) {
+  if (count <= 1) return "";
+  if (count === 2) return "@xl:grid-cols-2";
+  if (count === 3) return "@xl:grid-cols-2 @3xl:grid-cols-3";
+  return "@xl:grid-cols-2 @5xl:grid-cols-4";
+}
+
+/** The step's button variant: the first step is the page's one main button
+ *  (primary); the rest are secondary, unless a step names its own. */
+export function variantFor(choice, index) {
+  return choice?.action?.variant ?? (index === 0 ? "primary" : "secondary");
+}
+
+/** The steps as the page will draw them: ordered, each with its variant. */
+export function stepsOf(choices) {
+  return orderChoices(choices).map((c, i) => ({ ...c, variant: variantFor(c, i) }));
+}
+
+/** Words for a screen reader about how many ways in there are. */
+export function stepsWords(count) {
+  return count === 1 ? "1 way to begin" : `${count} ways to begin`;
+}