makersclaw 0.7.0 → 0.8.1

package/registry/blocks/step-settings/step-settings.jsx

@@ -0,0 +1,290 @@
+"use client";
+
+// The panel for one step: its name, what it does (a form made for its
+// kind), what happens if it fails, and the plain list of what is wrong
+// with it. In a run the same panel is read-only and adds how the step went,
+// what went in and what came out, and, when the agent fixed the step,
+// what it changed (fix-note).
+//
+// Fields are written in a person's words; the definition's own keys stay
+// out of sight (the step id is shown small, because it is what a run's rows
+// and an app update match steps by). Props in, callbacks out: every change
+// is `onChange(patch)`, applied by the screen with automation-model's
+// updateStep.
+
+import { useState } from "react";
+import { Button, Confirm, Icon, cx } from "../../ui";
+import { Glyph, KINDS, SidePanel, creditsWords, innerCount, nodeStateWords, stepTitle } from "../automation-model";
+import { DataInput, DataPairs } from "../data-picker";
+import { FixNote } from "../fix-note";
+import { NumberField, SelectField, TextField } from "./fields";
+
+const FAIL_OPTIONS = [
+  { value: "stop", label: "Stop the run" },
+  { value: "continue", label: "Carry on without it" },
+];
+const OP_OPTIONS = [
+  { value: "search", label: "Search" },
+  { value: "get", label: "Get one" },
+  { value: "list", label: "List" },
+];
+const METHOD_OPTIONS = [
+  { value: "GET", label: "Ask (GET)" },
+  { value: "POST", label: "Send (POST)" },
+  { value: "PUT", label: "Replace (PUT)" },
+  { value: "PATCH", label: "Change (PATCH)" },
+];
+const TIER_OPTIONS = [
+  { value: "fast", label: "Quick" },
+  { value: "smart", label: "Careful" },
+];
+
+const show = (v) => JSON.stringify(v, null, 2) ?? "";
+
+function Data({ label, value }) {
+  if (value === undefined || value === null) return null;
+  const text = show(value);
+  return (
+    <details open={text.length < 240} className="rounded-md border border-border bg-muted">
+      <summary className="cursor-pointer px-2 py-1 text-xs font-medium">{label}</summary>
+      <pre className="m-0 max-h-64 overflow-auto px-2 pb-2 font-mono text-xs">{text.length > 4000 ? `${text.slice(0, 4000)}\n…` : text}</pre>
+    </details>
+  );
+}
+
+/** A run's own account of the step: how it went, what went in and out. */
+function RunBlock({ summary, dataVisible, title, fixProps }) {
+  const last = summary.rows[summary.rows.length - 1];
+  return (
+    <section aria-label="How it went" className="grid gap-2 rounded-lg border border-border bg-background p-3">
+      <h4 className={cx("m-0 text-sm font-semibold", summary.state === "failed" && "text-destructive", summary.state === "done" && "text-success", summary.state === "would" && "text-primary")}>{nodeStateWords(summary.state)}</h4>
+      <p className="m-0 text-xs text-muted-foreground">
+        {summary.passes > 1 ? `${summary.passes} times · ` : ""}
+        {creditsWords(summary.credits)}
+      </p>
+      {summary.words ? <p className="m-0 text-[13px] text-destructive">{summary.words}</p> : null}
+      {summary.state === "would" && summary.would ? <p className="m-0 text-[13px] text-primary">{summary.would}</p> : null}
+      {summary.unchecked ? <p className="m-0 text-[13px] text-muted-foreground">Not checked: it needs what an earlier step would have made.</p> : null}
+      {summary.fix ? <FixNote fix={summary.fix} stepTitle={title} {...fixProps} /> : null}
+      {dataVisible && last ? (
+        <>
+          <Data label="Went in" value={last.input} />
+          <Data label="Came out" value={last.output} />
+        </>
+      ) : (
+        <p className="m-0 text-xs text-muted-foreground">What went in and came out is shown to the automation's owner and the admins.</p>
+      )}
+    </section>
+  );
+}
+
+/**
+ *   step          the step shown
+ *   available     automation-model's availableBefore(def, id, stepTitle), plus
+ *                 optionally `inputs: [{ name, label }]` (what a manual run asks)
+ *   samples       { [stepId]: a real output } for the data picker, or null
+ *   apps          the workspace's apps, [{ id, name }], for an action in a team automation
+ *   actions       the app's declared actions, [{ name, description? }]: an action
+ *                 step picks from them instead of typing a name
+ *   ownedByApp    the automation belongs to an app (its actions need no app)
+ *   problems      lines about this step to fix
+ *   readOnly      shown, not editable (a run)
+ *   onChange(patch), onRemove(), onDuplicate(), onClose()
+ *   summary       a run: automation-model's summarizeSteps() entry for this step
+ *   dataVisible   the member may read what went in and out
+ *   fixProps      what FixNote needs for a step the agent fixed: { draft, onKeep, onDrop, onUndo }
+ *   onKeepFix()   keep a fix the agent made, for next time (shorthand for fixProps.onKeep)
+ *   runActions    a run: what the member can do with this step (a node), drawn under how it went
+ */
+export function StepSettings({ step, available, samples = null, apps = [], actions, ownedByApp = false, problems = [], readOnly = false, onChange, onRemove, onDuplicate, onClose, summary = null, dataVisible = false, fixProps, onKeepFix, runActions = null }) {
+  const info = KINDS[step.kind] ?? KINDS.action;
+  const dis = readOnly;
+  const set = (patch) => onChange?.(patch);
+  const inner = innerCount(step);
+  const [confirming, setConfirming] = useState(false);
+  const title = stepTitle(step);
+
+  const remove = () => {
+    if (inner > 0) setConfirming(true);
+    else onRemove?.();
+  };
+
+  return (
+    <SidePanel
+      glyph={<Glyph name={info.glyph} size={20} />}
+      tone={info.tone === "plain" ? "plain" : "ai"}
+      title={title}
+      subtitle={`${info.name}${info.paid ? " · costs credits" : " · free"}`}
+      label={`${info.name} settings`}
+      onClose={onClose}
+      footer={
+        readOnly ? null : (
+          <>
+            <Button size="sm" variant="secondary" icon="copy" onClick={onDuplicate}>
+              Duplicate
+            </Button>
+            <Button size="sm" variant="danger" icon="trash" onClick={remove}>
+              Remove
+            </Button>
+          </>
+        )
+      }
+    >
+      {summary ? <RunBlock summary={summary} dataVisible={dataVisible} title={title} fixProps={fixProps ?? (onKeepFix ? { onKeep: onKeepFix } : undefined)} /> : null}
+      {summary && runActions ? runActions : null}
+
+      <TextField label="Name" value={step.label ?? ""} placeholder={stepTitle({ ...step, label: undefined })} disabled={dis} onChange={(v) => set({ label: v.trim() ? v : undefined })} help="What this step is called on the canvas." />
+
+      {step.kind === "action" ? (
+        <>
+          {!ownedByApp ? (
+            <SelectField label="App" value={step.app ?? ""} disabled={dis} onChange={(v) => set({ app: v || undefined })} options={[{ value: "", label: "Pick an app" }, ...apps.map((a) => ({ value: a.id, label: a.name }))]} help="Which of your apps this action belongs to." />
+          ) : null}
+          {actions?.length ? (
+            <SelectField
+              label="Action"
+              value={step.action}
+              disabled={dis}
+              onChange={(v) => set({ action: v })}
+              options={[{ value: "", label: "Pick an action" }, ...actions.map((a) => ({ value: a.name, label: a.description ? `${a.name}: ${a.description}` : a.name })), ...(step.action && !actions.some((a) => a.name === step.action) ? [{ value: step.action, label: step.action }] : [])]}
+              help="The actions this app declares."
+            />
+          ) : (
+            <TextField label="Action" value={step.action} mono disabled={dis} placeholder="add_people" onChange={(v) => set({ action: v })} help="The name of the action the app declares." />
+          )}
+          <DataPairs label="What to give it" value={step.input} available={available} samples={samples} disabled={dis} onChange={(v) => set({ input: v })} />
+        </>
+      ) : null}
+
+      {step.kind === "tool" ? (
+        <>
+          <TextField label="Kind of account" value={step.needs?.category ?? ""} mono disabled={dis} placeholder="mail" onChange={(v) => set({ needs: { category: v } })} help="The account is chosen by kind (mail, calendar, chat), never by product." />
+          <TextField label="Tool" value={step.tool} mono disabled={dis} placeholder="list_messages" onChange={(v) => set({ tool: v })} />
+          <TextField label="Which account" value={step.account ?? ""} disabled={dis} placeholder="you@company.com" onChange={(v) => set({ account: v || undefined })} help="Only when you have several of that kind." />
+          <DataPairs label="What to give it" value={step.input} available={available} samples={samples} disabled={dis} onChange={(v) => set({ input: v })} />
+        </>
+      ) : null}
+
+      {step.kind === "brain.read" ? (
+        <>
+          <SelectField label="How" value={step.op} options={OP_OPTIONS} disabled={dis} onChange={(v) => set({ op: v })} />
+          <DataPairs label="What to look for" value={step.input} available={available} samples={samples} disabled={dis} onChange={(v) => set({ input: v })} />
+        </>
+      ) : null}
+
+      {step.kind === "condition" ? (
+        <DataInput label="Go the Yes way when" value={step.if} mono multiline rows={3} disabled={dis} available={available} samples={samples} onChange={(v) => set({ if: v })} help="Anything else goes the No way. Branches are drawn on the canvas; add steps to each with +." />
+      ) : null}
+
+      {step.kind === "loop" ? (
+        <>
+          <DataInput label="Go through" value={step.over} mono disabled={dis} available={available} samples={samples} onChange={(v) => set({ over: v })} help="A list from an earlier step." />
+          <NumberField label="At most" value={step.max} min={1} max={500} disabled={dis} onChange={(v) => set({ max: v })} help="How many items it will go through." />
+          <DataInput label="Collect from each pass" value={step.collect ?? ""} mono disabled={dis} available={available} samples={samples} onChange={(v) => set({ collect: v || undefined })} help="Optional: what to keep from every pass, as a list." />
+        </>
+      ) : null}
+
+      {step.kind === "set" ? <DataPairs label="Values" value={step.values} available={available} samples={samples} disabled={dis} keyLabel="Name" onChange={(v) => set({ values: v })} /> : null}
+
+      {step.kind === "wait" ? (
+        <>
+          <TextField label="Wait for" value={step.for ?? ""} mono disabled={dis} placeholder="10m" onChange={(v) => set({ for: v || undefined, ...(v ? { until: undefined } : {}) })} help="A number and a unit: 30s, 10m, 2h, 3d. Nothing runs while it waits." />
+          <DataInput label="Or wait until" value={step.until ?? ""} mono disabled={dis} available={available} samples={samples} onChange={(v) => set({ until: v || undefined, ...(v ? { for: undefined } : {}) })} help="A time, as data." />
+        </>
+      ) : null}
+
+      {step.kind === "stop" ? (
+        <>
+          <DataInput label="Message" value={step.message} multiline rows={3} disabled={dis} available={available} samples={samples} onChange={(v) => set({ message: v })} />
+          <SelectField
+            label="Ends as"
+            value={step.as ?? "done"}
+            disabled={dis}
+            onChange={(v) => set({ as: v === "done" ? undefined : v })}
+            options={[
+              { value: "done", label: "Done" },
+              { value: "failed", label: "Failed" },
+            ]}
+          />
+        </>
+      ) : null}
+
+      {step.kind === "notify" ? <DataInput label="Message" value={step.message} multiline rows={3} disabled={dis} available={available} samples={samples} onChange={(v) => set({ message: v })} help="A line for the owner, in their Needs you." /> : null}
+
+      {step.kind === "search" ? (
+        <>
+          <DataInput label="Search for" value={step.query} multiline rows={2} disabled={dis} available={available} samples={samples} onChange={(v) => set({ query: v })} />
+          <NumberField label="How many results" value={step.limit} min={1} max={20} disabled={dis} onChange={(v) => set({ limit: v })} />
+        </>
+      ) : null}
+
+      {step.kind === "llm" ? (
+        <>
+          <DataInput label="What to ask" value={step.prompt} multiline rows={6} disabled={dis} available={available} samples={samples} onChange={(v) => set({ prompt: v })} />
+          <SelectField label="Which model" value={step.tier ?? "fast"} options={TIER_OPTIONS} disabled={dis} onChange={(v) => set({ tier: v })} help="Quick is cheaper. Careful thinks longer." />
+          <TextField label="Standing instructions" value={step.system ?? ""} multiline rows={2} disabled={dis} onChange={(v) => set({ system: v || undefined })} help="Optional instructions that frame every answer." />
+        </>
+      ) : null}
+
+      {step.kind === "agent" ? (
+        <>
+          <DataInput label="What the agent should do" value={step.instructions} multiline rows={7} disabled={dis} available={available} samples={samples} onChange={(v) => set({ instructions: v })} help="Plain words. The agent may use your apps and connected accounts, within what you can reach." />
+          <NumberField label="Most it may spend" value={step.cap_credits} min={1} disabled={dis} onChange={(v) => set({ cap_credits: v })} help="In credits. The run stops the agent there." />
+        </>
+      ) : null}
+
+      {step.kind === "zero" ? (
+        <>
+          <TextField label="Paid service" value={step.capability ?? ""} mono disabled={dis} placeholder="the service's name" onChange={(v) => set({ capability: v })} help="The name the platform's catalog of paid services gave it." />
+          <DataInput label="Address" value={step.url ?? ""} mono disabled={dis} available={available} samples={samples} onChange={(v) => set({ url: v })} help="The service's own web address, starting with https://." />
+          <SelectField label="How it is called" value={step.method ?? "GET"} options={METHOD_OPTIONS} disabled={dis} onChange={(v) => set({ method: v === "GET" ? undefined : v })} help="Ask puts what you give it on the address; the others send it as a body." />
+          <DataPairs label="What to give it" value={step.input} available={available} samples={samples} disabled={dis} onChange={(v) => set({ input: v })} />
+          <NumberField label="Most one call may cost, in dollars" value={step.max_pay_usd} min={0.01} max={2} step={0.01} disabled={dis} onChange={(v) => set({ max_pay_usd: v })} help="The step never pays more than this, and the same call is not paid for twice. It comes out of your credits." />
+        </>
+      ) : null}
+
+      {step.kind === "automation" ? (
+        <>
+          <TextField label="Which automation" value={step.key} mono disabled={dis} placeholder="morning-read" onChange={(v) => set({ key: v })} />
+          <DataPairs label="What to give it" value={step.input} available={available} samples={samples} disabled={dis} onChange={(v) => set({ input: v })} />
+        </>
+      ) : null}
+
+      <section className="grid gap-3 border-t border-border pt-3">
+        <h4 className="m-0 text-2xs font-semibold uppercase tracking-wide text-muted-foreground">If it fails</h4>
+        <SelectField label="After the tries are used up" value={step.on_error ?? "stop"} options={FAIL_OPTIONS} disabled={dis} onChange={(v) => set({ on_error: v === "stop" ? undefined : v })} help="The agent steps in first, if the flow lets it." />
+        <NumberField label="Tries after the first" value={step.retry?.max} min={0} max={5} disabled={dis} placeholder="3" onChange={(v) => set({ retry: v === undefined ? undefined : { max: v } })} help="For a slow or busy service. Leave empty for the usual three." />
+      </section>
+
+      {problems.length > 0 ? (
+        <div role="alert" className="grid gap-1 rounded-lg border border-destructive/50 bg-destructive/10 p-3">
+          <h4 className="m-0 flex items-center gap-1.5 text-sm font-semibold text-destructive">
+            <Icon name="warning" size={14} /> To fix
+          </h4>
+          <ul className="m-0 grid list-disc gap-0.5 pl-5 text-[13px]">
+            {problems.map((x) => (
+              <li key={x}>{x}</li>
+            ))}
+          </ul>
+        </div>
+      ) : null}
+
+      <p className="m-0 text-xs text-muted-foreground">
+        Step id <span className="font-mono">{step.id}</span>
+      </p>
+
+      <Confirm
+        open={confirming}
+        onClose={() => setConfirming(false)}
+        onConfirm={() => {
+          setConfirming(false);
+          onRemove?.();
+        }}
+        title="Remove this step?"
+        body={`This also removes the ${inner} step${inner === 1 ? "" : "s"} inside it.`}
+        confirmLabel="Remove"
+        tone="danger"
+      />
+    </SidePanel>
+  );
+}

package/registry/blocks/suggestion/README.md

@@ -0,0 +1,171 @@
+# Suggestion
+
+A value the agent proposes, drawn in pencil: **dashed** while it is a
+proposal, **solid** once kept. Its source is always shown, and a person
+keeps or drops it. A proposal differs from a fact in shape, never colour
+alone.
+
+Five shapes, one idea:
+
+- **FieldSuggestion** — under a field: what it holds now ("empty now"),
+  the proposed value, where it came from, Keep and Drop.
+- **InlineSuggestion** — found in place: a small dashed chip inside the
+  cell or field it would fill, its source, a tick and a cross (CRM v2).
+- **TextSuggestion** — a span of text: the old words struck, the new
+  beside them, the reason, the source (Writing Review's proof marks).
+- **Pencil** — the dashed frame for a whole proposed record: a drafted
+  email, a deal, a week's plan ("pencil to ink", Weekly Planner).
+- **SuggestionGroup** — the head over several: "Keep all 6", "Drop all".
+
+And **Looking**: "✦ Looking…" where a value is still being found.
+
+Grown in the CRM (0.7.0) as `field-suggestion`; every export kept its
+props. One change: a FieldSuggestion that was dropped now goes, as an
+InlineSuggestion always did.
+
+```jsx
+import { FieldSuggestion, InlineSuggestion, TextSuggestion, Pencil, SuggestionGroup, Looking } from "../components/blocks/suggestion";   // a Makersclaw app ("./blocks/suggestion" from components/)
+import { FieldSuggestion } from "@/components/makersclaw/blocks/suggestion";   // a shadcn project
+```
+
+Client components; `suggestionSource` is a plain function.
+
+## Which hook feeds it
+
+None of its own. The proposals are app data the agent wrote (a
+`suggestions` table, a column of proposed values). **A keep runs the
+app's own declared action** (`runAction`, lib/actions), so a keep is the
+same write the agent would make, and the door's rules hold for it.
+
+## The verbs are props
+
+Each app says it its way: Keep/Drop (CRM), Apply/Dismiss (Data Tables),
+Accept/Decline (Writing Review). Every shape takes `keepLabel` and
+`dropLabel`; FieldSuggestion and TextSuggestion also take `keptLabel`
+("Applied").
+
+## Props
+
+### FieldSuggestion
+
+- `label` — the field's name ("Job title"). It also names the group for a
+  reader ("Suggested job title") and the buttons ("Keep job title").
+- `current` — what the field holds now; empty → "empty now".
+- `value` — the proposed value (text or a node).
+- `source` — `{ from, at }` ("her email signature", "2026-09-12") or a
+  string.
+- `onKeep()` · `onDrop()` — async, answer `{ ok: true }` or `{ ok: false,
+  error }` (a throw counts as failed). The frame spins while it runs,
+  turns solid when kept, goes when dropped, and says why when it fails.
+- `compact` — icon buttons at the row's end, the label inside the frame:
+  for a list of several.
+- `showLabel` — `false` when you draw the field's label above it.
+- `keepLabel` · `dropLabel` · `keptLabel` — default "Keep", "Drop", "Kept".
+- `formatDate(date)` — how `source.at` is worded (default "Sat 12 Sep").
+
+Under 22rem of its own width the buttons go below the value.
+
+### InlineSuggestion
+
+- `value`, `source`, `label` (names the buttons for a reader),
+  `onKeep()` · `onDrop()`, `keepLabel` · `dropLabel`, `formatDate`.
+
+A dashed chip in the agent's tone (`border-info`); kept, solid with a
+tick; dropped, gone. For a table cell or a record's field list.
+
+### TextSuggestion
+
+- `before` — the words now, struck. Empty for an insertion.
+- `after` — the words proposed. Empty for a cut.
+- `lead` · `tail` — a few words around the span, muted, so it reads in
+  place ("…sorry about ", " order").
+- `reason` — why, one line.
+- `source` — `{ from, at }` or a string: what it leans on (the style
+  guide, a page).
+- `onKeep()` · `onDrop()` — async `{ ok }`.
+- `keepLabel` · `dropLabel` · `keptLabel`.
+
+A reader hears "Remove: … Add: …" for the struck and new words.
+
+### Pencil
+
+- `kicker` — the small line above ("A NEW DEAL").
+- `title` — what it is ("Crumb & Co: 22 shops").
+- `reason` — why the agent proposes it.
+- `children` — your content between the title and the reason.
+- `actions` — your buttons, with your verbs ("Make the deal", "Drop").
+- `state` — `pencil` (default) · `kept` (solid) · `failed` (with
+  `error`).
+- `label` — the region's name for a reader.
+
+### SuggestionGroup
+
+- `title` — "3 details found for Sofia: job title, LinkedIn and city".
+- `description` — where they came from; that nothing changes until kept.
+- `count` — for "Keep all 3" (or `keepAllLabel`). `dropAllLabel` —
+  default "Drop all".
+- `onKeepAll()` · `onDropAll()` — async `{ ok }`; a failure shows under
+  the title.
+- `children` — the suggestions under it.
+
+### Looking
+
+`children` replaces "Looking…". Pulses, and stays still under reduced
+motion.
+
+### suggestionSource({ from, at }, format?)
+
+"her email signature, Sat 12 Sep".
+
+## Who may do what
+
+The block shows the buttons it is given. Give `onKeep`/`onDrop` only to a
+member who may make that write; the declared action's door refuses anyone
+else anyway.
+
+## Never
+
+- Never write the value yourself on render: nothing changes until a
+  person keeps it.
+- Never draw a proposal solid, or a kept value dashed.
+- Never hide the source.
+
+## Example
+
+A contact's found details, kept through the app's declared actions.
+
+```jsx
+"use client";
+import { runAction } from "../lib/actions";
+import { FieldSuggestion, SuggestionGroup } from "../components/blocks/suggestion";
+
+export function FoundDetails({ person, suggestions, reload }) {
+  const done = (r) => {
+    if (r.ok) reload();
+    return r;
+  };
+  return (
+    <SuggestionGroup
+      title={`${suggestions.length} details found for ${person.first_name}`}
+      description="From her email signature and a web search. Nothing changes until you keep them."
+      count={suggestions.length}
+      onKeepAll={async () => done(await runAction({ name: "keep_details", args: { person: person.id } }))}
+      onDropAll={async () => done(await runAction({ name: "drop_details", args: { person: person.id } }))}
+    >
+      {suggestions.map((s) => (
+        <FieldSuggestion
+          key={s.id}
+          label={s.label}
+          current={person[s.column]}
+          value={s.value}
+          source={{ from: s.from, at: s.at }}
+          onKeep={async () => done(await runAction({ name: "keep_detail", args: { id: s.id } }))}
+          onDrop={async () => done(await runAction({ name: "drop_detail", args: { id: s.id } }))}
+        />
+      ))}
+    </SuggestionGroup>
+  );
+}
+```
+
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.

package/registry/blocks/suggestion/block.json

@@ -0,0 +1,40 @@
+{
+  "name": "suggestion",
+  "title": "Suggestion",
+  "description": "A value the agent proposes, drawn in pencil — dashed while it is a proposal, solid once kept — with its source always shown and a keep or a drop. Five shapes: FieldSuggestion under a field (\"empty now\", the proposed value, where it came from, Keep and Drop); InlineSuggestion found in place, a small dashed chip inside the cell it would fill with a tick and a cross; TextSuggestion, a span of text struck with its replacement beside it, the reason and the source; Pencil, the dashed frame for a whole proposed record (\"pencil to ink\"); SuggestionGroup, the head over several (\"Keep all 6\", \"Drop all\"); and Looking while a value is still being found. The verbs are props (Keep/Drop, Apply/Dismiss, Accept/Decline). Keeps and drops go out through async callbacks that answer { ok }; a failure says why in place.",
+  "useWhen": "The agent proposes values or changes a person keeps or drops: a CRM filling in a contact, a cleaner value in a table cell, a priority on an issue, a proofread sentence, a drafted plan for the week, a batch of moves on a board. For a whole column of answers across many records use agent-column; for one ask's finished changes with an undo use agent-changes.",
+  "tags": [
+    "suggestion",
+    "proposal",
+    "keep",
+    "drop",
+    "accept",
+    "decline",
+    "apply",
+    "dismiss",
+    "pencil",
+    "field",
+    "inline",
+    "found in place",
+    "proofread",
+    "redline",
+    "diff",
+    "enrichment",
+    "source",
+    "review"
+  ],
+  "exports": [
+    "FieldSuggestion",
+    "InlineSuggestion",
+    "TextSuggestion",
+    "Pencil",
+    "SuggestionGroup",
+    "Looking",
+    "suggestionSource"
+  ],
+  "files": [
+    "index.js",
+    "suggestion.jsx"
+  ],
+  "requires": []
+}

package/registry/blocks/suggestion/demo.jsx

@@ -0,0 +1,91 @@
+"use client";
+
+// Every shape of a suggestion, kept, dropped, saving and failing — the
+// gallery's and the smoke test's surface. Not installed into apps.
+import { Button, Card } from "../components/ui";
+import { FieldSuggestion, InlineSuggestion, TextSuggestion, Pencil, SuggestionGroup, Looking } from "../components/blocks/suggestion";
+
+const ok = () => new Promise((r) => setTimeout(() => r({ ok: true }), 600));
+const no = () => new Promise((r) => setTimeout(() => r({ ok: false, error: "The table didn't answer. Try again." }), 600));
+const slow = () => new Promise(() => undefined);
+
+export default function SuggestionDemo() {
+  return (
+    <div className="grid gap-6 p-6 [grid-template-columns:repeat(auto-fit,minmax(min(100%,22rem),1fr))]">
+      <div className="grid content-start gap-4">
+        <SuggestionGroup
+          title="3 details found for Sofia: job title, LinkedIn and city"
+          description="From her email signature of Sat 12 Sep and a web search. Nothing changes until you keep them."
+          count={3}
+          onKeepAll={ok}
+          onDropAll={ok}
+        />
+        <FieldSuggestion label="Job title" value="Head of Retail Operations" source={{ from: "her email signature", at: "2026-09-12" }} onKeep={ok} onDrop={ok} />
+        <FieldSuggestion label="LinkedIn" current="linkedin.com/in/sofia" value="linkedin.com/in/sofia-lindqvist" source="a web search" onKeep={no} onDrop={ok} />
+        <FieldSuggestion compact label="City" value="Minneapolis, MN · Central time" source="her email signature" onKeep={ok} onDrop={ok} />
+        <FieldSuggestion label="Priority" value="Urgent" source="three customers wrote in today" keepLabel="Apply" dropLabel="Dismiss" keptLabel="Applied" onKeep={slow} onDrop={ok} />
+      </div>
+
+      <div className="grid content-start gap-4">
+        <Card title="Found in place">
+          <table className="w-full table-fixed text-sm">
+            <tbody>
+              <tr className="border-b border-border">
+                <td className="w-[7.5rem] py-2 pr-3 text-muted-foreground">Phone</td>
+                <td className="py-2">
+                  <InlineSuggestion label="Phone" value="+1 612 555 0142" source={{ from: "her email signature", at: "2026-09-12" }} onKeep={ok} onDrop={ok} />
+                </td>
+              </tr>
+              <tr className="border-b border-border">
+                <td className="py-2 pr-3 text-muted-foreground">Company size</td>
+                <td className="py-2">
+                  <InlineSuggestion label="Company size" value="51–200" source="LinkedIn" onKeep={no} onDrop={ok} />
+                </td>
+              </tr>
+              <tr>
+                <td className="py-2 pr-3 text-muted-foreground">Website</td>
+                <td className="py-2">
+                  <Looking />
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </Card>
+
+        <TextSuggestion
+          lead="We're sorry about "
+          before="you're"
+          after="your"
+          tail=" order arriving late."
+          reason="“Your” is the owner's; “you're” is “you are”."
+          source="Kestrel's style guide"
+          keepLabel="Accept"
+          dropLabel="Decline"
+          keptLabel="Accepted"
+          onKeep={ok}
+          onDrop={ok}
+        />
+        <TextSuggestion before="we are working to resolve it" reason="Says nothing the next sentence doesn't." onKeep={ok} onDrop={ok} />
+        <TextSuggestion lead="Ships in " after="two to three" tail=" days." reason="The order page says two to three." onKeep={no} onDrop={ok} />
+
+        <Pencil
+          kicker="A new deal"
+          title="Crumb & Co: 22 shops"
+          reason="Sofia: “we're looking at scheduling for all 22 shops”"
+          actions={
+            <>
+              <Button size="sm" variant="primary">
+                Make the deal
+              </Button>
+              <Button size="sm" variant="quiet">
+                Drop
+              </Button>
+            </>
+          }
+        />
+        <Pencil kicker="Monday" title="Pencilled: deep work 9–11, the board review at 2" state="kept" />
+        <Pencil kicker="A move" title="Harbor Seed to Proposal" state="failed" error="Proposal needs an amount first." />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/suggestion/index.js

@@ -0,0 +1,3 @@
+// The Suggestion block — `makersclaw add suggestion`. Fixed: compose it
+// through its props (README.md beside this file).
+export { FieldSuggestion, InlineSuggestion, TextSuggestion, Pencil, SuggestionGroup, Looking, suggestionSource } from "./suggestion";