makersclaw 0.8.0 → 0.8.2

package/registry/blocks/agent-dock/demo.jsx

@@ -0,0 +1,153 @@
+"use client";
+
+// AgentDock in the kit's AppLayout over a pretend agent — the gallery's and
+// the smoke test's surface. Not installed into apps. The frame is an
+// AppLayout with a rail and a top bar whose Ask button is useAgentDock's
+// toggle; the dock is its `dock`. A width picker sets how wide the app is:
+// at 1100 it is a column (drag its divider, or focus the divider and press
+// the arrows; Home goes back to a quarter), at 700 it is a sheet over the
+// app (Escape folds it). The chat is a pretend one: Chats lists two past
+// chats, New chat clears, and any ask is answered after a moment. "Have the
+// agent draft it" is openAgent: the dock opens with the line already sent in
+// a new chat; "Start a line" puts the line in the box instead.
+import { useEffect, useRef, useState } from "react";
+import { AppLayout, Button, ButtonGroup } from "../components/ui";
+import { AgentDock, openAgent, useAgentDock } from "../components/blocks/agent-dock";
+import { AgentPane } from "../components/blocks/agent-pane";
+
+const CHATS = {
+  items: [
+    { sessionId: "past-1", requestId: "q1", title: "Who should we follow up with this week?", mark: "needs", at: new Date(Date.now() - 20 * 60 * 1000).toISOString() },
+    { sessionId: "past-2", requestId: "q2", title: "Weekly pipeline read", mark: null, at: new Date(Date.now() - 3 * 3600 * 1000).toISOString() },
+  ],
+  loading: false,
+  error: null,
+  unavailable: false,
+};
+
+function usePretendChat(withChats) {
+  const [messages, setMessages] = useState([]);
+  const [state, setState] = useState(null);
+  const timers = useRef([]);
+  useEffect(() => () => timers.current.forEach(clearTimeout), []);
+  return {
+    sessionId: messages.length ? "demo" : null,
+    state,
+    needs: null,
+    turns: [],
+    view: { messages, thinking: state === "working", failure: null, questions: [] },
+    place: "app",
+    request: messages.length ? { id: "demo-request", title: "Ask" } : null,
+    pending: null,
+    sending: false,
+    loading: false,
+    error: null,
+    unavailable: false,
+    chats: withChats ? CHATS : { items: [], loading: false, error: null, unavailable: false },
+    send: (text) => {
+      const id = `m${Date.now()}`;
+      setState("working");
+      setMessages((m) => [...m, { id: `${id}u`, role: "user", text, files: [] }]);
+      timers.current.push(
+        setTimeout(() => {
+          setMessages((m) => [...m, { id: `${id}a`, role: "assistant", live: false, blocks: [{ kind: "text", key: "t", text: "Three people have gone quiet for over two weeks. Want me to draft a note to each?", streaming: false }] }]);
+          setState("done");
+        }, 900),
+      );
+    },
+    answer: async () => ({ ok: true }),
+    stop: () => setState("stopped"),
+    openOnDesk: () => true,
+    openRequest: () => true,
+    openSession: () => undefined,
+    callDetail: async () => ({ ok: false }),
+    newChat: () => {
+      setMessages([]);
+      setState(null);
+    },
+    reload: () => undefined,
+  };
+}
+
+const WIDTHS = [
+  { id: "1100", label: "1100 px (a column)" },
+  { id: "700", label: "700 px (a sheet)" },
+];
+
+function Frame({ withChats, label }) {
+  const dock = useAgentDock({ storageKey: "gallery-dock" });
+  const chat = usePretendChat(withChats);
+  return (
+    <AppLayout
+      height="parent"
+      navigationWidth={160}
+      navigation={<nav className="grid gap-1 p-3 text-sm"><span className="font-medium">People</span><span className="text-muted-foreground">Companies</span><span className="text-muted-foreground">Deals</span></nav>}
+      header={
+        <div className="flex h-10 items-center justify-between gap-2 px-3 text-sm">
+          <span className="font-semibold">{label}</span>
+          <Button size="sm" variant={dock.open ? "secondary" : "primary"} icon="sparkles" onClick={dock.toggle} aria-pressed={dock.open}>
+            Ask
+          </Button>
+        </div>
+      }
+      dock={
+        <AgentDock dock={dock} label="Ask the agent">
+          <AgentPane
+            chat={chat}
+            title="Ask the agent"
+            empty="The agent reads every person and deal. What it changes you can take back."
+            suggestions={["Who should we follow up with?", "What changed this week?"]}
+          />
+        </AgentDock>
+      }
+      className="text-sm"
+    >
+      <div className="grid gap-3 p-6">
+        <h2 className="text-lg font-semibold">People</h2>
+        <p className="max-w-prose text-muted-foreground">The content reflows beside the column and keeps its own scroll. Ask opens the dock; the close in its head folds it; the width and the open state are kept in this browser.</p>
+        {/* "Have the agent do it" (X9): the dock opens with the line already sent in a new chat, no form first. */}
+        <div className="flex flex-wrap gap-2">
+          <Button variant="primary" icon="sparkles" onClick={() => openAgent("Draft a project plan for me")}>
+            Have the agent draft it
+          </Button>
+          <Button onClick={() => openAgent({ ask: "Draft a project plan for ", send: false })}>Start a line</Button>
+        </div>
+        {Array.from({ length: 12 }, (_, i) => (
+          <div key={i} className="rounded-[var(--radius)] border border-border px-3 py-2">
+            Row {i + 1}: a person, a company, the last time you spoke.
+          </div>
+        ))}
+      </div>
+    </AppLayout>
+  );
+}
+
+export default function AgentDockDemo() {
+  const [width, setWidth] = useState("1100");
+  const [chats, setChats] = useState("some");
+  return (
+    <div className="grid gap-3 p-6">
+      <div className="flex flex-wrap items-center gap-3">
+        <ButtonGroup>
+          {WIDTHS.map((w) => (
+            <Button key={w.id} size="sm" variant={width === w.id ? "secondary" : "quiet"} onClick={() => setWidth(w.id)}>
+              {w.label}
+            </Button>
+          ))}
+        </ButtonGroup>
+        <ButtonGroup>
+          <Button size="sm" variant={chats === "some" ? "secondary" : "quiet"} onClick={() => setChats("some")}>
+            Past chats
+          </Button>
+          <Button size="sm" variant={chats === "none" ? "secondary" : "quiet"} onClick={() => setChats("none")}>
+            No chats yet
+          </Button>
+        </ButtonGroup>
+      </div>
+      {/* The transform makes this box the sheet's containing block, so a sheet lays over this frame in the gallery as it lays over an app's window. */}
+      <div className="h-[640px] max-w-full overflow-hidden rounded-lg border border-border" style={{ width: `${width}px`, transform: "translateZ(0)" }}>
+        <Frame key={`${chats}`} withChats={chats === "some"} label="Pinewood CRM" />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/agent-dock/dock-model.js

@@ -0,0 +1,118 @@
+// agent-dock: the numbers and the keys, as plain functions (they work on the
+// server too, and test/agent-dock.test.mjs holds them).
+//
+// The dock is a column beside the work. Its width is the member's to drag:
+// never under MIN_W, never over half the body it sits in, a quarter of it
+// until dragged. Below `columnAt` px of body the column has no room and the
+// dock becomes a sheet laid over the app.
+
+/** The narrowest the column goes, px. */
+export const MIN_W = 280;
+/** One press of an arrow key on the divider, px. */
+export const STEP = 16;
+/** The body width from which the dock is a column beside the work (the
+ *  desk's own agent column uses 900). */
+export const COLUMN_AT = 900;
+/** The share of the body the column takes until it is dragged. */
+export const DEFAULT_SHARE = 0.25;
+
+/** The widest the column goes in a body this wide: half of it, never under MIN_W. */
+export function maxWidth(body) {
+  const b = Number(body);
+  return Math.max(MIN_W, Number.isFinite(b) && b > 0 ? Math.floor(b / 2) : MIN_W);
+}
+
+/** A width kept inside its bounds, whole px. */
+export function clampWidth(width, body) {
+  const w = Number(width);
+  if (!Number.isFinite(w)) return MIN_W;
+  return Math.min(maxWidth(body), Math.max(MIN_W, Math.round(w)));
+}
+
+/** What a stored width is worth: a whole number of px at least MIN_W, else
+ *  null (the default). The CSS clamps it again whatever was stored. */
+export function storedWidth(raw) {
+  if (raw === null || raw === undefined || raw === "") return null;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= MIN_W ? Math.round(n) : null;
+}
+
+/** The width the column has now: the dragged one, else a quarter of the
+ *  body, kept inside the same bounds the CSS uses. */
+export function columnWidth(width, body) {
+  const b = Number(body) > 0 ? Number(body) : 0;
+  return clampWidth(width ?? b * DEFAULT_SHARE, b);
+}
+
+/** Is there room for a column beside the work? An unmeasured body (0) is
+ *  taken to have room: the first paint is never a sheet by mistake. */
+export function hasRoom(body, columnAt = COLUMN_AT) {
+  const b = Number(body);
+  return !(Number.isFinite(b) && b > 0) || b >= columnAt;
+}
+
+/** The divider dragged: the pointer moving left widens the column. */
+export function dragged(startWidth, startX, x, body) {
+  return clampWidth(Number(startWidth) - (Number(x) - Number(startX)), body);
+}
+
+/** The divider's keys. Left widens, Right narrows, End opens it to the
+ *  widest, Home goes back to the default (null). `undefined` = not ours. */
+export function nudged(key, now, body) {
+  if (key === "ArrowLeft") return clampWidth(Number(now) + STEP, body);
+  if (key === "ArrowRight") return clampWidth(Number(now) - STEP, body);
+  if (key === "End") return maxWidth(body);
+  if (key === "Home") return null;
+  return undefined;
+}
+
+/** The two keys this browser keeps for one app's dock. */
+export function dockKeys(storageKey) {
+  const k = String(storageKey || "app").replace(/[^\w.-]+/g, "-");
+  return { open: `mc.dock.${k}.open`, width: `mc.dock.${k}.width` };
+}
+
+// ---- "have the agent do it" (X9) -------------------------------------------
+//
+// A button that says the agent will do the work does not open a form. It
+// opens the dock with the agent's first line already sent (or in the box),
+// and the agent asks only for what it is missing, in the chat. openAgent()
+// (agent-dock.jsx) is the call; this is its message.
+
+/** The window event openAgent() dispatches; every useAgentDock hears it. */
+export const OPEN_EVENT = "mc:agent-dock:open";
+
+let seq = 0;
+
+/**
+ * What openAgent was asked, made whole. The argument is a line ("Draft a
+ * project plan for me") or an object:
+ *
+ *   ask         the starting line
+ *   send        true (the default): send it as the member's first words.
+ *               false: put it in the box for the member to finish
+ *   fresh       true (the default): in a new chat, so it is its own thing
+ *               and not a follow-up. false: carry on in the open one
+ *   storageKey  only the dock of that app (default: any dock on the page)
+ *
+ * → { ask, send, fresh, storageKey, nonce }. The line is kept as given (a
+ * trailing space is where the member goes on typing); the pane trims what it
+ * sends. The nonce is new every call: a pane takes a nonce once.
+ */
+export function openRequest(input, now = Date.now()) {
+  const o = typeof input === "string" ? { ask: input } : (input ?? {});
+  return {
+    ask: String(o.ask ?? ""),
+    send: o.send !== false,
+    fresh: o.fresh !== false,
+    storageKey: o.storageKey ? String(o.storageKey) : null,
+    nonce: `${now}-${++seq}`,
+  };
+}
+
+/** Does an openAgent call carry a line for the pane? With no line
+ *  (`openAgent()`, `{ ask: "" }`, a blank string) the dock only opens: nothing
+ *  is sent and no chat is started. */
+export function carriesLine(request) {
+  return Boolean(String(request?.ask ?? "").trim());
+}

package/registry/blocks/agent-dock/index.js

@@ -0,0 +1,5 @@
+// The AgentDock block — `makersclaw add agent-dock`. Fixed: compose it
+// through its props (README.md beside this file). The model's helpers are
+// plain functions; they work on the server too.
+export { AgentDock, openAgent, useAgentDock } from "./agent-dock";
+export { COLUMN_AT, DEFAULT_SHARE, MIN_W, OPEN_EVENT, STEP, carriesLine, clampWidth, columnWidth, dockKeys, dragged, hasRoom, maxWidth, nudged, openRequest, storedWidth } from "./dock-model";

package/registry/blocks/agent-kit/README.md

@@ -0,0 +1,73 @@
+# AgentKit
+
+What the app's agent knows and what it can do, shown inside the app.
+Part of the agent kit (0.8.1).
+
+- **What it knows** — its skills. The app's own references first, each
+  with when the agent reads it ("Before writing a follow-up"); then the
+  skills added on top, marked **Added**, and **Not installed** where one
+  is not yet.
+- **What it can do** — its tools: the app's declared actions, by what
+  they do ("Move a deal to another stage"), with the action's name
+  under it.
+
+Read only. Adding or removing a skill is the window's Settings › Skills;
+`onManage` opens it ("Manage in Settings").
+
+```jsx
+import { AgentKit } from "../components/blocks/agent-kit";   // a Makersclaw app
+import { AgentKit } from "@/components/makersclaw/blocks/agent-kit";   // a shadcn project
+```
+
+A client component. Its own width decides its layout: the two lists sit
+side by side from about 768 px, one over the other below.
+
+## Props
+
+- `skills` — useAgentKit's `skills`: `[{ name, title, when, from: "app"
+  | "added", installed }]`.
+- `tools` — useAgentKit's `tools`: `[{ name, description }]` (only the
+  actions the agent may run; one declared `"agent": false` is left out).
+- `onManage` — opens the window's Settings › Skills. Leave it out for no
+  button. `manageLabel` — its words (default "Manage in Settings").
+- `title` — the head (default "The agent"); `null` for none.
+- `empty` — `{ skills, tools }`: what an empty list says.
+- `className` — layout around it. Never colour.
+
+## useAgentKit (lib/hooks.js)
+
+```js
+const { skills, tools } = useAgentKit();
+```
+
+It reads `GET _claw/agent` once: `own_skills` (`{ name, title, when }`,
+from the app's `references/*.md`), `skills` (added on top, `{ name,
+installed }`) and `actions` (`{ name, description, agent }`, the
+declared actions). On a claw from before `own_skills` and `actions` it
+answers empty lists: the block says so plainly, never an error.
+
+## Who may do what
+
+Any member reads it. Adding or removing a skill: the window's Settings ›
+Skills, on the desk, by whoever may change the app there.
+
+## Never
+
+- Never an Add or Remove of a skill here: that is the desk's.
+- Never the agent's instructions (its brief) word for word: they are
+  for the agent. Say what it knows by its skills' titles.
+- Never a tool the app does not declare: the list is the declared
+  actions, nothing written by hand.
+
+## Example
+
+```jsx
+"use client";
+import { useAgentKit } from "../lib/hooks";
+import { AgentKit } from "../components/blocks/agent-kit";
+
+export default function AboutTheAgent({ openSettings }) {
+  const { skills, tools } = useAgentKit();
+  return <AgentKit title="What the CRM's agent knows" skills={skills} tools={tools} onManage={openSettings} />;
+}
+```

package/registry/blocks/agent-kit/agent-kit.jsx

@@ -0,0 +1,86 @@
+"use client";
+
+// What the app's agent knows and what it can do, inside the app: its
+// skills (the app's own references, with when it reads each, and those
+// added on top, marked added and, where so, not installed) and its tools
+// (the app's declared actions). Props in, callbacks out; read only —
+// adding or removing a skill stays in the window's Settings › Skills,
+// which onManage opens. Tokens only. Its own width decides its layout
+// (@container): the two lists sit side by side from about 768 px.
+
+import { Badge, Button, Icon, cx } from "../../ui";
+
+function Section({ icon, title, count, children }) {
+  return (
+    <section aria-label={title} className="grid min-w-0 content-start gap-1">
+      <h3 className="m-0 flex min-w-0 items-center gap-2 px-3.5 pt-3 text-sm font-semibold">
+        <Icon name={icon} size={14} className="shrink-0 text-muted-foreground" />
+        <span className="truncate">{title}</span>
+        {count ? <span className="text-xs font-normal tabular-nums text-muted-foreground">{count}</span> : null}
+      </h3>
+      {children}
+    </section>
+  );
+}
+
+/**
+ *   skills     [{ name, title, when, from: "app" | "added", installed }]
+ *              (useAgentKit's `skills`)
+ *   tools      [{ name, description }] (useAgentKit's `tools`)
+ *   onManage   opens the window's Settings › Skills; leave it out for none
+ *   manageLabel    its words (default "Manage in Settings")
+ *   title      the head (default "The agent"); null for none
+ *   empty      { skills, tools }: what an empty list says
+ */
+export function AgentKit({ skills = [], tools = [], onManage, manageLabel = "Manage in Settings", title = "The agent", empty, className }) {
+  const known = Array.isArray(skills) ? skills : [];
+  const can = Array.isArray(tools) ? tools : [];
+  return (
+    <section aria-label={title ?? "The agent"} className={cx("@container grid min-w-0 overflow-hidden rounded-[var(--radius)] border border-border bg-card text-card-foreground", className)}>
+      {title || onManage ? (
+        <header className="flex min-w-0 flex-wrap items-center gap-2 border-b border-border px-3.5 py-2">
+          {title ? <b className="min-w-0 flex-1 truncate text-sm font-semibold">{title}</b> : <span className="flex-1" />}
+          {onManage ? (
+            <Button size="sm" variant="quiet" icon="settings" onClick={onManage}>
+              {manageLabel}
+            </Button>
+          ) : null}
+        </header>
+      ) : null}
+      <div className="grid min-w-0 divide-y divide-border @3xl:grid-cols-2 @3xl:divide-x @3xl:divide-y-0">
+        <Section icon="lightbulb" title="What it knows" count={known.length || null}>
+          {known.length ? (
+            <ul className="m-0 grid list-none p-0 pb-1.5">
+              {known.map((s) => (
+                <li key={`${s.from}-${s.name}`} className="grid min-w-0 gap-0.5 px-3.5 py-2">
+                  <span className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
+                    <span className="min-w-0 truncate text-[13px] font-medium">{s.title || s.name}</span>
+                    {s.from === "added" ? <Badge tone="info">Added</Badge> : null}
+                    {s.from === "added" && !s.installed ? <Badge tone="warning">Not installed</Badge> : null}
+                  </span>
+                  {s.when ? <span className="line-clamp-2 text-xs text-muted-foreground">{s.when}</span> : null}
+                </li>
+              ))}
+            </ul>
+          ) : (
+            <p className="m-0 px-3.5 pb-3 text-[13px] text-muted-foreground">{empty?.skills ?? "Nothing of its own yet: it works from the app's instructions."}</p>
+          )}
+        </Section>
+        <Section icon="wand" title="What it can do" count={can.length || null}>
+          {can.length ? (
+            <ul className="m-0 grid list-none p-0 pb-1.5">
+              {can.map((t) => (
+                <li key={t.name} className="grid min-w-0 gap-0.5 px-3.5 py-2">
+                  <span className="min-w-0 text-[13px]">{t.description || t.name}</span>
+                  {t.description ? <code className="truncate text-[11.5px] text-muted-foreground">{t.name}</code> : null}
+                </li>
+              ))}
+            </ul>
+          ) : (
+            <p className="m-0 px-3.5 pb-3 text-[13px] text-muted-foreground">{empty?.tools ?? "No actions declared yet: it reads, and asks before it writes."}</p>
+          )}
+        </Section>
+      </div>
+    </section>
+  );
+}

package/registry/blocks/agent-kit/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "agent-kit",
+  "title": "AgentKit",
+  "description": "What the app's agent knows and what it can do, inside the app: its skills (the app's own references, each with when the agent reads it, and the skills added on top, marked Added and, where so, Not installed) and its tools (the app's declared actions, by what they do). Read only; \"Manage in Settings\" (onManage) opens the window's Settings › Skills, where skills are added and removed. It draws what useAgentKit() returns (lib/hooks.js, GET _claw/agent).",
+  "useWhen": "An app shows its member what its agent is for and may do: an About the agent page, a side card beside the agent's chat, a settings screen's Agent section, a help panel (\"What can I ask?\"). For the agent's runs use run-history; for its schedule use schedule-card; for the chat itself use agent-chat.",
+  "tags": ["skills", "tools", "actions", "capabilities", "knowledge", "about", "settings", "help", "kit"],
+  "exports": ["AgentKit"],
+  "files": ["index.js", "agent-kit.jsx"],
+  "requires": []
+}

package/registry/blocks/agent-kit/demo.jsx

@@ -0,0 +1,35 @@
+"use client";
+
+// AgentKit with a pretend agent — the gallery's and the smoke test's
+// surface. Not installed into apps. A CRM's agent at 800 px (side by
+// side from 768), the same at 320 px, and a new app's agent with nothing
+// of its own yet.
+import { AgentKit } from "../components/blocks/agent-kit";
+
+const SKILLS = [
+  { name: "reading-mail", title: "Reading the morning mail", when: "On every morning read, before it files a thread under a person", from: "app", installed: true },
+  { name: "drafting", title: "Drafting follow-ups", when: "Before it writes a follow-up: the tone, the length, never a promise of a date", from: "app", installed: true },
+  { name: "deal-stages", title: "What each deal stage means", when: "Before it moves a deal", from: "app", installed: true },
+  { name: "web-research", title: "web-research", when: null, from: "added", installed: true },
+  { name: "linkedin-lookup", title: "linkedin-lookup", when: null, from: "added", installed: false },
+];
+
+const TOOLS = [
+  { name: "add_person", description: "Add a person, with where they were found" },
+  { name: "update_person", description: "Change a person's details" },
+  { name: "move_deal", description: "Move a deal to another stage" },
+  { name: "log_meeting", description: "Put a meeting on a person's timeline" },
+  { name: "draft_follow_up", description: "Draft a follow-up for your yes" },
+];
+
+export default function AgentKitDemo() {
+  return (
+    <div className="grid gap-6 p-4">
+      <AgentKit className="w-full max-w-[800px]" title="What the CRM's agent knows" skills={SKILLS} tools={TOOLS} onManage={() => {}} />
+      <div className="flex flex-wrap items-start gap-4">
+        <AgentKit className="w-full max-w-[320px]" skills={SKILLS.slice(0, 3)} tools={TOOLS.slice(0, 3)} onManage={() => {}} />
+        <AgentKit className="w-full max-w-[368px]" title="A new app's agent" skills={[]} tools={[]} />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/agent-kit/index.js

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

package/registry/blocks/agent-marks/README.md

@@ -0,0 +1,80 @@
+# AgentMarks
+
+Two marks and a byline, one of each for the whole platform.
+
+- **AgentMark** — a filled diamond. The agent's work: it read, used
+  tools, wrote. It may cost more than one call.
+- **CallMark** — a sparkle in a dashed ring. One model call: no
+  conversation, no tools ("Shorter · 1 cr").
+- **Byline** — who did it, in words: "By the agent, on Priya's ask ·
+  11:20".
+
+Before the kit, the store's apps drew the agent in six different glyphs.
+A member who learns the diamond in one app now reads it in every app.
+
+The two marks differ in **shape**, filled against dashed. Never tell them
+apart by colour alone, and never draw a sparkle or a robot of your own.
+
+```jsx
+import { AgentMark, CallMark, Byline } from "../components/blocks/agent-marks";   // a Makersclaw app ("./blocks/agent-marks" from components/)
+import { AgentMark, CallMark, Byline } from "@/components/makersclaw/blocks/agent-marks";   // a shadcn project
+```
+
+No data, no hook, no door. Props in.
+
+## Props
+
+### AgentMark · CallMark
+
+- `label` — what a screen reader hears when the mark stands alone ("The
+  agent", "One model call"). Leave it out when words beside the mark
+  already say it: the mark is then decoration.
+- `size` — `xs` · `sm` (default, 12px) · `md` · `lg`, or pixels.
+- `children` — words drawn beside the mark ("Agent", "1 call").
+- `className` — layout around it. Never colour: the agent's mark is the
+  theme's `primary`, the call's is muted.
+
+### Byline
+
+- `by` — `"agent"` (the default; its mark leads), `"call"` (one model
+  call), or a person's name ("Owen").
+- `ask` — whose ask the agent worked on: a name ("Priya" → "on Priya's
+  ask"), `"you"` ("on your ask"), or `"run"` for a scheduled job's run
+  ("on a run").
+- `at` — when: words ("11:20"), a `Date`, or an ISO string (today reads
+  as the time, another day as "12 Sep").
+- `mark` — `false` drops the mark before the words, for a head that
+  already draws one.
+
+## Where each one goes
+
+- A value the agent wrote, in a cell or beside a field: `AgentMark` with
+  `label="Written by the agent"`.
+- A button that makes one model call: `CallMark` (the `ai-action` block
+  draws it for you).
+- The head of a receipt, a timeline line, a draft: `Byline`.
+
+## Never
+
+- Never mark a person's own work with either mark.
+- Never use `AgentMark` for one model call, or `CallMark` for an ask: the
+  member reads cost and reach from the shape.
+- Never colour a mark through `className`.
+
+## Example
+
+```jsx
+import { AgentMark, Byline } from "./blocks/agent-marks";
+
+export function WrittenBy({ note }) {
+  return (
+    <div className="grid gap-1">
+      <p className="flex items-center gap-1.5">
+        <AgentMark label="Written by the agent" />
+        {note.text}
+      </p>
+      <Byline by="agent" ask={note.asked_by_name} at={note.created_at} />
+    </div>
+  );
+}
+```