makersclaw 0.8.0 → 0.8.2

package/registry/blocks/ai-action/demo.jsx

@@ -0,0 +1,93 @@
+"use client";
+
+// AiAction over a pretend useLlmAction(): priced, running, answered,
+// refused, shaped by a schema, and not connected yet — the gallery's and
+// the smoke test's surface. Not installed into apps.
+import { useEffect, useRef, useState } from "react";
+import { Card } from "../components/ui";
+import { AiAction } from "../components/blocks/ai-action";
+
+/** Shaped as useLlmAction returns it; `answer` is what run() resolves. */
+function usePretendCall(answer, { estimate = { credits: 1, credits_max: 1 }, ms = 1200 } = {}) {
+  const [state, setState] = useState({ result: null, loading: false, error: null });
+  const [estimating, setEstimating] = useState(true);
+  const timers = useRef([]);
+  useEffect(() => {
+    timers.current.push(setTimeout(() => setEstimating(false), 500));
+    return () => timers.current.forEach(clearTimeout);
+  }, []);
+  return {
+    estimate: estimating ? null : estimate,
+    estimating,
+    loading: state.loading,
+    result: state.result,
+    error: state.error,
+    unavailable: false,
+    run: () =>
+      new Promise((resolve) => {
+        setState({ result: null, loading: true, error: null });
+        timers.current.push(
+          setTimeout(() => {
+            const r = typeof answer === "function" ? answer() : answer;
+            setState(r.ok === false ? { result: null, loading: false, error: r.error } : { result: r, loading: false, error: null });
+            resolve(r);
+          }, ms),
+        );
+      }),
+    reset: () => setState({ result: null, loading: false, error: null }),
+  };
+}
+
+const DRAFT =
+  "Thanks so much for taking the time to meet with us last Thursday. We really enjoyed hearing about how Crumb & Co schedules its 22 shops, and we think there is a lot we could do together over the coming months.";
+
+export default function AiActionDemo() {
+  const [draft, setDraft] = useState(DRAFT);
+  const shorter = usePretendCall({ ok: true, text: "Thanks for meeting last Thursday. We'd love to help Crumb & Co schedule all 22 shops." });
+  const why = usePretendCall(
+    { ok: true, data: { reasons: ["Two replies in a week", "Asked for pricing", "A new head of operations"] } },
+    { estimate: { credits: 2, credits_max: 6 } },
+  );
+  const refused = usePretendCall({ ok: false, error: "The app's weekly allowance is used up. It starts again on Monday." });
+  const running = usePretendCall({ ok: true, text: "…" }, { ms: 1e9 });
+  return (
+    <div className="grid gap-6 p-6 [grid-template-columns:repeat(auto-fit,minmax(min(100%,20rem),1fr))]">
+      <Card title="A draft">
+        <div className="grid gap-3">
+          <p className="text-sm">{draft}</p>
+          <AiAction label="Shorter" action={shorter} useLabel="Replace the draft" onUse={(r) => setDraft(r.text)} />
+        </div>
+      </Card>
+      <Card title="A score">
+        <AiAction
+          label="Why is it 82?"
+          icon="lightbulb"
+          action={why}
+          render={(r) => (
+            <ul className="list-disc pl-5">
+              {r.data.reasons.map((x) => (
+                <li key={x}>{x}</li>
+              ))}
+            </ul>
+          )}
+        />
+      </Card>
+      <Card title="Refused">
+        <AiAction label="Summarize the thread" action={refused} />
+      </Card>
+      <Card title="Running">
+        <AiAction label="Summarize" action={{ ...running, estimate: { credits: 0.4, credits_max: 0.4 }, estimating: false, loading: true, run: () => undefined }} />
+      </Card>
+      <Card title="Not connected yet">
+        <AiAction label="Shorter" action={{ unavailable: true }} />
+      </Card>
+      <div className="w-80 max-w-full">
+        <AiAction
+          label="Explain why this account's health score moved down this week"
+          action={{ estimate: { credits: 1200, credits_max: 2400 }, estimating: false, run: () => undefined, result: { text: "Two of its five shops stopped scheduling on Monday, and the owner hasn't opened the last three emails." }, reset: () => undefined }}
+          onUse={() => undefined}
+        />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/ai-action/index.js

@@ -0,0 +1,3 @@
+// The AiAction block — `makersclaw add ai-action`. Fixed: compose it
+// through its props (README.md beside this file).
+export { AiAction, priceWords } from "./ai-action";

package/registry/blocks/approval/README.md

@@ -0,0 +1,145 @@
+# Approval
+
+The yes, given in the app. The app draws the card in its own theme: what
+will happen, to whom, the exact words, the cost. The press is not the
+app's. Under the card sits a small page of Makersclaw's, in the app's
+colours, that app code cannot script. It shows the server's own words for
+the request and only counts a press a person made on a card they can see.
+
+```jsx
+import { Approval } from "../components/blocks/approval";   // a Makersclaw app ("./blocks/approval" from components/)
+import { Approval } from "@/components/makersclaw/blocks/approval";   // a shadcn project
+```
+
+A client component. The Example is at the end.
+
+## Why a frame
+
+App code is written by an agent, and an in-app Approve button could be
+pressed by that same code, or by a script that got into the page. So the
+button that gives the yes is not in the app's page. It is a Makersclaw
+page, embedded in the card:
+
+- **Another origin.** The app cannot reach into it, read it or click it.
+- **The server's words.** It shows what Makersclaw holds for the request:
+  the agent's one question, who it goes to, from which account, the first
+  message in full, and the rule "Always allow this kind" would save. Never
+  the app's text. The app's card above it shows the same thing in the
+  app's own design; the frame is the one to trust.
+- **A press a person made, on a card they can see.** Where the browser
+  can tell (Chrome, Edge) the Approve button works only after the card
+  has been in view, uncovered and not faded, for half a second. Where it
+  cannot (Safari, Firefox) Approve is press and hold, for most of a
+  second. A click the page's script makes does nothing.
+- **The member's own sign-in.** The press carries the member's token from
+  the desk's storage, which the app has no way to read, and the server
+  checks it is the member who asked, for this app, for the question the
+  card showed.
+- **The same path as the desk's Approve.** The answer goes to the agent
+  as a structured answer from the member, so the audit trail, the rules
+  and the Standing yes stay one.
+
+"Always allow this kind" is in the same card: one tick, and the server
+writes one bounded line into the app's Standing yes (the kind: what is
+sent, to whom, from which account), shown beside the box before it is
+ticked. Rules, not items: the next one of that kind goes without asking.
+Anything wider still asks.
+
+## Which hook feeds it
+
+```js
+const approval = useApproval(item.id);   // lib/hooks.js; item from useNeedsYou
+// → { approval, state, always, fallback, frame, height, loading, error, … }
+```
+
+It reads `GET _claw/requests/:id/approval` once, for the request that
+waits on this member's yes (`item.via === "press"`), and listens to the
+frame. It approves nothing.
+
+## Props
+
+- `approval` — `useApproval(...)`'s answer (required).
+- `title` — what is about to happen, in the app's words ("Send 3
+  follow-ups to the Replies list").
+- `kicker` — the line over it. Default "Waiting for your yes".
+- `children` — the app's own card content: the draft, the recipients, the
+  exact words. Drawn above the press, in the app's theme.
+- `cost` — a node for the price (the `cost` block's `CostTag`), beside the
+  title.
+- `onOpenDesk()` — opens the desk on this ask (`needs.open(item)`): the
+  press of the fallback.
+- `onDone({ state, always })` — once, when the member has said yes
+  (`"approved"`) or not now (`"declined"`); `always` is true when "Always
+  allow this kind" was saved. Refresh what the yes unlocks.
+- `className` — layout around it. Never colour.
+
+## The states
+
+`approval.state` is one of: `loading` (a skeleton) · `ready` (the frame)
+· `approved` ("You said yes · the agent is on it", and "Always allowed for
+this kind" when it was) · `declined` ("Not now. Nothing went out.") ·
+`stale` (the question moved on since the card was drawn; it looks again
+by itself) · `gone` (nothing waits any more: answered elsewhere).
+
+When the frame cannot do its part, `approval.fallback` is true and the
+block draws `WaitingYes` instead: "Waiting for your yes on the desk",
+with **Open the desk**. That is the case when the frame did not load in
+seven seconds (`blocked`), the member must sign in again on the desk
+(`signin`), the claw is from before this door (`unavailable`) or the read
+failed (`error`). Nothing is lost: the yes is the same yes.
+
+## Who may do what
+
+- The member who asked gives the yes. Owners and admins do not give a
+  teammate's: the door refuses them (`not_your_request`).
+- Only a yes: one question, one Approve and Not now. A tool approval, a
+  connect, a spend and several questions at once go to the desk.
+- A question (not a yes) is answered in place, with `QuestionBox`
+  (`needs-you`), never here.
+- Topping up credits and signing in to an account stay on the desk.
+
+## Never
+
+- **Never an Approve, Yes or Send button of your own that gives the
+  yes.** The app's card may have a "Review the draft" press; the
+  approval is the frame's.
+- Never hide, cover, fade, scale or position the frame so that part of it
+  is out of view: a press then does not count, by design.
+- Never put the frame in an element with `pointer-events: none`,
+  `opacity` below 1 or a `transform`.
+- Never show another member's asks here.
+
+## Example
+
+The post that waits for its yes, inside the page that already shows it.
+
+```jsx
+"use client";
+import { useNeedsYou, useApproval } from "../lib/hooks";
+import { Approval } from "../components/blocks/approval";
+import { CostTag } from "../components/blocks/cost";
+
+export function SendCard({ item, draft }) {
+  const needs = useNeedsYou();
+  const approval = useApproval(item.id);
+  return (
+    <Approval
+      approval={approval}
+      title={`Send ${draft.count} follow-ups to ${draft.list}`}
+      cost={<CostTag credits={draft.credits} />}
+      onOpenDesk={() => needs.open(item)}
+      onDone={({ state }) => state === "approved" && refreshRows()}
+    >
+      <DraftList draft={draft} />
+    </Approval>
+  );
+}
+
+// …and in a queue of everything that waits:
+<NeedsYou
+  items={needs.items}
+  onOpen={needs.open}
+  onAnswer={needs.answer}
+  renderYes={(item) => <SendCard item={item} draft={draftFor(item)} />}
+/>
+```

package/registry/blocks/approval/approval.jsx

@@ -0,0 +1,163 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { Button, Icon, Skeleton, Spinner, cx } from "../../ui";
+import { WaitingYes } from "../needs-you";
+
+// Approval — the yes, given in the app (the app kit, D18). The app draws
+// the card in its own theme: what will happen, to whom, the exact words,
+// the cost. The press is not the app's. Under the card sits a small page
+// of Makersclaw's, in another origin, that app code cannot script: it
+// shows the SERVER's words for the request (the agent's question, who,
+// from which account, the first message, the rule "Always allow this
+// kind" would save), in the app's colours, and only counts a press a
+// person made on a card they can see (in view and uncovered, or held).
+// The block draws that frame and what it says back; it never draws an
+// Approve of its own.
+//
+//   const approval = useApproval(item.id);                // lib/hooks.js
+//   <Approval approval={approval} title="Send 3 follow-ups" onOpenDesk={…}>
+//     …the draft the app already shows…
+//   </Approval>
+//
+// If the frame cannot do its part (it did not load in time, the member
+// must sign in again, a claw from before this door) the block falls back
+// to WaitingYes: "Waiting for your yes on the desk", with the desk one
+// press away. Props in, callbacks out.
+
+/** A frame that has not said how tall it wants to be. */
+const FRAME_HEIGHT = 240;
+
+/** Why the fallback is showing, in a sentence. */
+const WHY = {
+  signin: "Sign in again on Makersclaw to say yes here. The desk has it.",
+  blocked: "The press could not load here. The desk has it.",
+  unavailable: "Saying yes here needs a newer Makersclaw. The desk has it.",
+  error: "The press could not be loaded just now. The desk has it.",
+};
+
+/** The card's receipt, once the press has been used. */
+function Receipt({ icon, tone, head, children }) {
+  return (
+    <div role="status" className="grid grid-cols-1 min-w-0 gap-1">
+      <p className={cx("flex min-w-0 items-center gap-2 font-medium", tone)}>
+        <Icon name={icon} size={16} className="shrink-0" />
+        <span className="min-w-0 break-words">{head}</span>
+      </p>
+      {children ? <p className="text-muted-foreground">{children}</p> : null}
+    </div>
+  );
+}
+
+/**
+ *   approval      what useApproval(requestId) returns (required)
+ *   title         what is about to happen, in the app's words ("Send 3
+ *                 follow-ups to the Replies list")
+ *   kicker        the line over it; default "Waiting for your yes"
+ *   children      the app's own card content: the draft, the recipients,
+ *                 the exact words. Drawn above the press, in the app's
+ *                 theme
+ *   cost          a node for the price ("about 700 cr": the `cost`
+ *                 block's CostTag); shown beside the title
+ *   onOpenDesk()  opens the desk on this ask: the press of the fallback
+ *                 (useNeedsYou's `open(item)`); without it the fallback
+ *                 only says where the yes is
+ *   onDone({ state, always })   called once when the member has said yes
+ *                 or not now ("approved" or "declined"; `always` true when
+ *                 "Always allow this kind" was saved): refresh what the
+ *                 yes unlocks
+ *   className     layout around it. Never colour.
+ */
+export function Approval({ approval, title, kicker = "Waiting for your yes", children, cost, onOpenDesk, onDone, className }) {
+  const state = approval?.state ?? "idle";
+  const spoken = useRef(null);
+  useEffect(() => {
+    if ((state === "approved" || state === "declined") && spoken.current !== state) {
+      spoken.current = state;
+      onDone?.({ state, always: Boolean(approval?.always) });
+    }
+    if (state !== "approved" && state !== "declined") spoken.current = null;
+  }, [state, approval?.always]);
+
+  if (state === "idle") return null;
+
+  if (state === "loading")
+    return (
+      <section aria-busy="true" aria-label="Waiting for your yes" className={cx("@container grid grid-cols-1 min-w-0 gap-3 rounded-lg border border-border bg-card p-3.5", className)}>
+        <Skeleton className="w-1/3" />
+        <Skeleton className="w-3/4" />
+        <Skeleton className="h-16 w-full" />
+      </section>
+    );
+
+  // The frame cannot be used: the desk's card, with the words the app drew.
+  if (approval?.fallback)
+    return (
+      <WaitingYes
+        title={title}
+        frozen={children}
+        kicker={kicker}
+        body={WHY[state] ?? WHY.error}
+        onOpen={onOpenDesk}
+        className={className}
+      />
+    );
+
+  const done = state === "approved" || state === "declined";
+  const head = (
+    <div className="grid grid-cols-1 min-w-0 gap-1">
+      <div className="flex min-w-0 items-start gap-2">
+        <div className="grid grid-cols-1 min-w-0 flex-1 gap-1">
+          {kicker ? (
+            <p className="flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+              {done ? null : <Icon name="shield-check" size={12} className="shrink-0" />}
+              {kicker}
+            </p>
+          ) : null}
+          {title ? <p className="break-words text-[15px] font-semibold leading-snug">{title}</p> : null}
+        </div>
+        {cost ? <div className="shrink-0 pt-0.5 text-xs text-muted-foreground">{cost}</div> : null}
+      </div>
+    </div>
+  );
+
+  return (
+    <section
+      aria-label={typeof title === "string" ? title : "Waiting for your yes"}
+      className={cx("@container grid grid-cols-1 min-w-0 content-start gap-3 rounded-lg border border-border bg-card p-3.5 text-sm text-card-foreground", className)}
+    >
+      {head}
+      {children != null && children !== "" ? <div className={cx("min-w-0 break-words", done && "text-muted-foreground")}>{children}</div> : null}
+
+      {state === "approved" ? (
+        <Receipt icon="check" tone="text-success" head="You said yes · the agent is on it">
+          {approval?.always ? "Always allowed for this kind. It will not ask again for the same." : null}
+        </Receipt>
+      ) : state === "declined" ? (
+        <Receipt icon="x" tone="text-muted-foreground" head="Not now. Nothing went out." />
+      ) : state === "gone" ? (
+        <Receipt icon="check" tone="text-muted-foreground" head="This has been answered." />
+      ) : state === "stale" ? (
+        <p role="status" className="flex items-center gap-2 text-muted-foreground">
+          <Spinner size="sm" label="Looking again" /> This changed since the card was drawn. Looking again…
+        </p>
+      ) : approval?.frame ? (
+        <iframe
+          ref={approval.frame.ref}
+          src={approval.frame.src}
+          srcDoc={approval.frame.srcDoc}
+          title={approval.frame.title ?? "Approve"}
+          scrolling="no"
+          className="block w-full border-0 bg-transparent"
+          style={{ height: approval.height ?? FRAME_HEIGHT }}
+        />
+      ) : null}
+      {state === "ready" && approval?.error ? <p className="text-xs text-destructive">{approval.error}</p> : null}
+      {state === "gone" && onOpenDesk ? (
+        <Button size="sm" variant="quiet" className="justify-self-start" onClick={onOpenDesk}>
+          Open it on the desk
+        </Button>
+      ) : null}
+    </section>
+  );
+}

package/registry/blocks/approval/block.json

@@ -0,0 +1,31 @@
+{
+  "name": "approval",
+  "title": "Approval",
+  "description": "The yes, given in the app. The app draws the card in its own theme — what will happen, to whom, the exact words, the cost — and under it sits the press: a small Makersclaw-origin frame, in the app's colours, that app code cannot script. It shows the server's own words for the request (the agent's question, who, from which account, the first message, the rule \"Always allow this kind\" would save) and only counts a press a person made on a card they can see. Fed by useApproval(requestId) (lib/hooks.js). If the frame cannot load or the member must sign in again, the card falls back to WaitingYes: \"Waiting for your yes on the desk\".",
+  "useWhen": "Anywhere the agent is about to do something public or paid and waits for the member's yes — a send, a post, a purchase: put the app's own card (the draft, the recipients, the cost) inside it, give it useApproval(item.id) for the request that waits, and the member says yes without leaving the app. For the queue of everything that waits use needs-you; for the conversation, agent-chat.",
+  "tags": [
+    "approval",
+    "approve",
+    "yes",
+    "send",
+    "confirm",
+    "needs you",
+    "agent",
+    "trust",
+    "always allow",
+    "rule",
+    "desk",
+    "publish",
+    "spend"
+  ],
+  "exports": [
+    "Approval"
+  ],
+  "files": [
+    "index.js",
+    "approval.jsx"
+  ],
+  "requires": [
+    "needs-you"
+  ]
+}

package/registry/blocks/approval/demo.jsx

@@ -0,0 +1,121 @@
+"use client";
+
+// Approval in every state, with fake data shaped as useApproval() returns
+// it — the gallery's and the smoke test's surface. Not installed into
+// apps. The press frame is a page of Makersclaw's in another origin; here
+// a stand-in of the same shape (`srcDoc`) takes its place, so the card's
+// layout can be looked at at every width.
+import { useEffect, useRef, useState } from "react";
+import { Approval } from "../components/blocks/approval";
+
+// Inline styles and the browser's own colour names only: the check refuses
+// a hex, a colour function or a <style> tag in a surface, and this is a
+// stand-in, not a design.
+const BOX = "border:1px solid GrayText;border-radius:10px;padding:12px 14px;display:flex;flex-direction:column;gap:10px";
+const BTN = "font:inherit;font-weight:600;padding:8px 14px;border-radius:8px;border:1px solid GrayText;background:transparent;color:inherit;min-height:36px";
+const standIn = (scheme) =>
+  `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="${scheme}">` +
+  `<body style="margin:0;background:transparent;font:14px/1.45 system-ui,sans-serif">` +
+  `<main style="${BOX}"><span style="font-size:11px;letter-spacing:.06em;text-transform:uppercase;opacity:.65">Waiting for your yes</span>` +
+  `<p style="margin:0;font-size:15px;font-weight:600">Send 3 follow-ups from ada@acme.com to the Replies list?</p>` +
+  `<div style="display:grid;grid-template-columns:auto 1fr;gap:2px 10px;font-size:13px"><span style="opacity:.65">To</span><span>3 investors on the Replies list</span>` +
+  `<span style="opacity:.65">From</span><span>ada@acme.com</span><span style="opacity:.65">First to</span><span>Maya Chen</span></div>` +
+  `<pre style="margin:0;padding:8px 10px;border-radius:8px;border:1px solid GrayText;font:13px/1.4 inherit;white-space:pre-wrap">Hi Maya, a short note on where we are&hellip;</pre>` +
+  `<label style="display:flex;gap:8px;font-size:13px"><input type="checkbox"><span>Always allow this kind: Send messages like &ldquo;Quick question about Northwind&rdquo; to the Replies list, from ada@acme.com.</span></label>` +
+  `<div style="display:flex;gap:8px;justify-content:flex-end;flex-wrap:wrap"><button style="${BTN}">Not now</button><button style="${BTN};background:Highlight;color:HighlightText;border-color:transparent">Send 3</button></div></main>`;
+
+// The real frame wears the app's theme sheet, whose :root names the same
+// colour scheme as the page around it, so its transparent ground stays
+// transparent. The stand-in reads the page's scheme for the same reason.
+function useScheme() {
+  const [scheme, setScheme] = useState("light dark");
+  useEffect(() => {
+    const read = getComputedStyle(document.documentElement).colorScheme;
+    if (read && read !== "normal") setScheme(read);
+  }, []);
+  return scheme;
+}
+
+const FACTS = {
+  request_id: "r1",
+  question: "Send 3 follow-ups from ada@acme.com to the Replies list?",
+  label: "Send 3",
+  covers: null,
+  always: "Send messages like “Quick question about Northwind” to the Replies list, from ada@acme.com.",
+  cap_credits: null,
+  at: "t1",
+};
+
+/** What useApproval() returns, for a state. */
+function fake(state, scheme, over = {}) {
+  const ref = useRef(null);
+  const framed = state === "ready";
+  return {
+    approval: FACTS,
+    state,
+    always: false,
+    fallback: state === "signin" || state === "blocked" || state === "unavailable" || state === "error",
+    frame: framed ? { src: undefined, srcDoc: standIn(scheme), ref, title: "Approve" } : null,
+    height: 440,
+    loading: state === "loading",
+    error: null,
+    code: null,
+    unavailable: state === "unavailable",
+    reload: () => {},
+    ...over,
+  };
+}
+
+const DRAFT = (
+  <div className="grid gap-2">
+    <p className="text-muted-foreground">3 follow-ups, ready to go</p>
+    <ul className="grid gap-1 pl-4 [list-style:disc]">
+      <li>Maya Chen · Northwind</li>
+      <li>Priya Nair · Harbor Seed</li>
+      <li>Tom Osei · Coastline</li>
+    </ul>
+    <p className="whitespace-pre-wrap rounded-[var(--radius)] bg-muted p-2.5">{"Hi Maya,\n\nA short note on where we are after the demo. Happy to answer anything before Friday."}</p>
+  </div>
+);
+
+export default function ApprovalDemo() {
+  const scheme = useScheme();
+  const ready = fake("ready", scheme);
+  const approved = fake("approved", scheme, { always: true });
+  const declined = fake("declined", scheme);
+  const stale = fake("stale", scheme);
+  const gone = fake("gone", scheme);
+  const loading = fake("loading", scheme);
+  const signin = fake("signin", scheme);
+  const blocked = fake("blocked", scheme);
+  const unavailable = fake("unavailable", scheme);
+  return (
+    <div className="grid gap-4 p-6 [grid-template-columns:repeat(auto-fit,minmax(min(100%,22rem),1fr))]">
+      <Approval approval={ready} title="Send 3 follow-ups" cost={<span>about 12 cr</span>} onOpenDesk={() => true}>
+        {DRAFT}
+      </Approval>
+      <Approval approval={approved} title="Send 3 follow-ups">
+        {DRAFT}
+      </Approval>
+      <Approval approval={declined} title="Send 3 follow-ups">
+        {DRAFT}
+      </Approval>
+      <Approval approval={stale} title="Send 3 follow-ups">
+        {DRAFT}
+      </Approval>
+      <Approval approval={gone} title="Send 3 follow-ups" onOpenDesk={() => true}>
+        {DRAFT}
+      </Approval>
+      <Approval approval={loading} title="Send 3 follow-ups" />
+      <Approval approval={signin} title="Send 3 follow-ups" onOpenDesk={() => true}>
+        {DRAFT}
+      </Approval>
+      <Approval approval={blocked} title="Send 3 follow-ups" onOpenDesk={() => true}>
+        {DRAFT}
+      </Approval>
+      <Approval approval={unavailable} title="Send 3 follow-ups">
+        {DRAFT}
+      </Approval>
+    </div>
+  );
+}

package/registry/blocks/approval/index.js

@@ -0,0 +1,3 @@
+// The Approval block — `makersclaw add approval`. Fixed: compose it
+// through its props (README.md beside this file).
+export { Approval } from "./approval";

package/registry/blocks/ask-bar/README.md

@@ -0,0 +1,105 @@
+# AskBar
+
+One line to ask the app's agent, in the app's look. Chips under it offer
+asks that fit the moment; a chip sends its words. Long chips wrap; they
+never run off the screen.
+
+After a send the bar says where the ask stands, in one line:
+
+- "Working…" while the agent is on it;
+- "Waiting for you" when it needs the member's yes or answer;
+- "Answered", "Stopped", or "It didn't finish".
+
+Beside the line, **Open** shows the conversation. Where it shows is the
+screen's choice: a `Sheet` with the `agent-chat` block, the inspector,
+a side column. When the agent waits on a question or a yes the app can
+settle (`chat.needs.in_app` is `"answer"` or `"press"`), Open shows that
+chat, where the answer is given (`agent-chat`) and the yes is pressed
+(`approval`). A need the app cannot settle goes to the desk instead
+(`chat.openOnDesk()`).
+
+It is a door into the conversation, not the conversation. The thread is
+the same one `agent-chat` and the desk's agent column draw.
+
+```jsx
+import { AskBar } from "../components/blocks/ask-bar";   // a Makersclaw app ("./blocks/ask-bar" from components/)
+import { AskBar } from "@/components/makersclaw/blocks/ask-bar";   // a shadcn project
+```
+
+A client component. The Example is at the end.
+
+## Props
+
+- `chat` — what `useAgentThread()` returns (lib/hooks.js). A send calls
+  `chat.send(text)`; the line reads `chat.state`, the last ask from
+  `chat.turns` or `chat.pending`, and `chat.error`.
+- `onAsk(text)` — instead of `chat`: your own sender. It may be async; an
+  answer of `{ ok: false, error }` (or a throw) shows its words under the
+  bar.
+- `state` — with `onAsk` only: where your ask stands, in
+  `useAgentThread`'s words (`queued` · `working` · `needs_you` · `done` ·
+  `stopped` · `failed`).
+- `suggestions` — asks that fit the moment, as chips. Say them in the
+  app's words ("Who should I call today?").
+- `placeholder` — the box's words. Default "Ask the agent…".
+- `label` — the box's name for a screen reader. Default "Ask the agent".
+- `onOpen()` — shows the conversation. Without it there is no Open.
+- `openOnSend` — `true`: a send also calls `onOpen`, so the chat opens at
+  once.
+- `className` — layout around it. Never colour.
+
+## Which hook feeds it
+
+`useAgentThread({ row, how, key })` (lib/hooks.js) over
+`POST _claw/ask` and `GET _claw/threads/<session>`. Give the same `row`
+the chat on the same screen gets, and both draw one thread.
+
+## Who may do what
+
+Any member who can open the app may ask. Each member sees only their own
+thread. Stop lives in the chat (`agent-chat`), not here.
+
+## Never
+
+- **Never an Approve.** The yes is the `approval` block's frame, which the
+  app's code cannot press. The bar says "Waiting for you" and Open shows
+  the chat that holds it.
+- Never answer the agent's question here: that is the chat's
+  `QuestionBox`.
+- Never show the agent's answer in the bar. One line of state, then Open.
+
+## Outside Makersclaw
+
+Any object of the same shape works: `state`, `turns` (`[{ member }]`),
+`pending`, `error`, `unavailable`, `send(text)` and `openOnDesk()`. Or
+use `onAsk` and `state`.
+
+## Example
+
+A home screen with the ask on top and the chat in a sheet.
+
+```jsx
+"use client";
+import { useState } from "react";
+import { Sheet } from "../components/ui";
+import { useAgentThread } from "../lib/hooks";
+import { AskBar } from "../components/blocks/ask-bar";
+import { AgentChat } from "../components/blocks/agent-chat";
+
+export default function Today() {
+  const [open, setOpen] = useState(false);
+  const chat = useAgentThread({ key: "today" });
+  return (
+    <>
+      <AskBar
+        chat={chat}
+        suggestions={["Who should I call today?", "What changed since Friday?"]}
+        onOpen={() => setOpen(true)}
+      />
+      <Sheet open={open} onClose={() => setOpen(false)} title="Ask the agent">
+        <AgentChat chat={chat} bare />
+      </Sheet>
+    </>
+  );
+}
+```