makersclaw 0.7.0 → 0.8.1

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

@@ -0,0 +1,197 @@
+# AgentColumn
+
+A column an agent fills for every record, cell by cell, and a person
+checks. Each answer says what state it is in (queued, waits for another
+column, looking up, found, not found, two answers, can't fill, failed,
+out of date, checked or typed by a person) and how sure the agent is,
+as a mark that differs in shape, never colour alone: filled is **sure**,
+half is **likely**, a dashed ring is a **guess**, a tick is a person's.
+Its detail shows where the answer came from, the words on the page with
+the answer marked in them, how it was found, both answers when two
+sources disagree, what was tried when nothing was found, and what a
+person can do about it.
+
+Born in Data Enrichment (0.5.0), moved into the template with the app
+kit (D15), written for any app whose agent fills or suggests values one
+record at a time: a CRM filling in a contact, a base whose agent fills a
+field or proposes a cleaner value, a research list. For one field on the
+record you have open, use `suggestion`; for one source outside a column,
+`source-receipt` (a clipping from this block).
+
+```jsx
+import { AnswerCell, AnswerDetail, ColumnHeader, ColumnPicker, SureLegend, summarizeAnswers } from "../components/blocks/agent-column";   // a Makersclaw app ("./blocks/agent-column" from components/)
+import { AnswerCell } from "@/components/makersclaw/blocks/agent-column";   // a shadcn project
+```
+
+Client components, plus server-safe helpers (`model.js`: `answerState`,
+`answerWords`, `needsCheck`, `summarizeAnswers`, `progressWords`,
+`markWords`, `shortUrl`). No npm packages. It requires `agent-marks`
+(laid with it), whose diamond is the agent's mark here too.
+
+## The answer
+
+One plain object per cell. Map your rows into it; the block never reads
+your database.
+
+```js
+{
+  id: "c-42",
+  status: "found",          // queued · working · found · not_found · two_answers · failed · stale · suggested
+  value: "62",              // the answer
+  detail: "51–200 on LinkedIn",   // a line under it
+  link: "https://pennantpay.com", // a URL, when the answer is one
+  confidence: "likely",     // sure · likely · guess
+  source: { url: "pennantpay.com/team", title: "Their team page", evidence: "62 people" },
+  other: { value: "70", detail: "in their own words", source: { url, title, evidence } },  // two_answers
+  note: "Read their LinkedIn page and their team page.",   // how it was found; what was tried
+  tried: [{ title, url, evidence }],   // what it read, for "not found"
+  flag: "may_not_fit",      // your own word for "look at this" on a found answer
+  setBy: "agent",           // "person": typed by a person, never overwritten
+  checked: false,           // a person accepted it
+  looking: "reading klarwerk.de/team",   // while working
+  waitsFor: ["Domain"],     // queued, waiting for other columns
+  blockedBy: ["Head of Compliance"],     // queued, needs a column that wasn't found
+  waitsForRow: false,       // queued, reads the whole record and goes last
+  hint: "try their careers page",        // the person's words when asking again
+}
+```
+
+`null` is "not asked yet". `needsCheck(answer)` is the one rule for "a
+person should look at this": not accepted, and not found, two answers,
+failed, a guess, flagged, or a suggestion.
+
+## The pieces
+
+- **`AnswerCell`** `{ answer, type, onOpen, onRetry, lines, label }` —
+  the cell. `type` text · link · email · number · domain (the last four
+  in the mono face). `onOpen` makes it a button (open your detail);
+  `onRetry` adds "Try again" to a failed one. Two answers and flagged
+  answers get a warning tint. Use it in `data-table`'s `cell(row)`, in a
+  list, or through `answerColumnType` in a spreadsheet.
+- **`SureMark`** `{ confidence, checked, typed }` and **`SureLegend`** —
+  the mark alone (`role="img"` with its word), and the key to the marks.
+- **`ColumnHeader`** `{ name, progress, agent, note }` — the name and the
+  live line under it ("138 of 480 · 3 to check · 1 waiting", "to check"
+  in the warning tone). `progress` is `summarizeAnswers(answers, total)`.
+  `agent={false}` for a person's own column ("yours", or `note`).
+- **`AnswerDetail`** — the answer in full, for your `Sheet`: `answer`,
+  `type`, `title` and `subtitle` (the record), `needs` (`[{ name, answer
+  }]`, what it read), `history` (`[{ at, words, credits }]`), `askCost`,
+  `placeholder`, `hintPlaceholder`, `note`, `busy`, `children` (your own
+  choices under it: a record's Keep / Skip / Remove). The actions show
+  when you pass their callback and the state allows them: `onAccept()`,
+  `onPick("one" | "other")`, `onType(value)`, `onAskAgain(hint)`,
+  `onKeepNotFound()`, `onKeep()` / `onDrop()` (a suggestion).
+- **`Source`** `{ source, mark }` — a source's title and address, and its
+  words in the display face with `mark` highlighted where it appears.
+- **`ColumnPicker`** — choose the columns to add: `recipes` (`[{ key,
+  name, description, credits, input?: "role" | "instructions", defaultRole,
+  defaultAsk, defaultExample, checked }]`), `rows` (for the total),
+  `heading`, `noun`, `unit`, `ownCredits`, `answerTypes`, `busy`,
+  `submitLabel(n)`, `onSubmit(chosen)` with `[{ recipe, name, ask,
+  example, answerType, options, credits }]`. It also offers "Your own
+  question" with the kind of answer.
+- **`answerColumnType`** — the spreadsheet type (`types={{ answer:
+  answerColumnType }}`, a column `{ type: "answer", answerType }`). Typing
+  in the cell makes the value the person's (`setBy: "person"`).
+
+## Example
+
+```jsx
+"use client";
+import { DataTable } from "./blocks/data-table";
+import { AnswerCell, ColumnHeader, summarizeAnswers } from "./blocks/agent-column";
+
+export default function Companies({ rows, open }) {
+  const headcount = rows.map((r) => r.answers.headcount);
+  return (
+    <DataTable
+      rows={rows}
+      columns={[
+        { key: "name", header: "Company" },
+        {
+          key: "headcount",
+          header: <ColumnHeader name="Headcount" progress={summarizeAnswers(headcount, rows.length)} />,
+          cell: (r) => <AnswerCell answer={r.answers.headcount} type="number" onOpen={() => open(r, "headcount")} label={`Headcount of ${r.name}`} />,
+        },
+      ]}
+    />
+  );
+}
+```
+
+## The receipt (0.5.0, from Data Enrichment's v2 design)
+
+A second way to draw the same answers, for a dense grid and a panel
+beside it. Colours are the theme's slots, each with a shape and a word:
+`chart-1` sure (filled dot), `chart-2` likely (half), `chart-3` guess
+(dashed ring, never shown as verified), `success` a person's check (✓),
+`chart-5` typed by a person (✎), `warning` two answers or a flag (split
+square), `info` looking up (a bar), `destructive` failed (▲), muted for
+queued, waiting, can't fill, not found and out of date.
+
+```jsx
+import { AnswerLine, JobHeader, Receipt, ReceiptActions, Clipping, TrustMark } from "./blocks/agent-column";
+```
+
+- **`AnswerLine`** `{ answer, onRetry, queuedWord }` — one line for a
+  32px cell: the value at the start, its trust at the end ("pennantpay.com
+  ● sure", "62 ◐ ✓", "85 · 70 ▣ 2 answers", "⊘ not found", "◌ can't
+  fill · needs Head of Compliance", "▲ failed · didn't respond  Try
+  again"). A flagged answer (`may_not_fit`, `left`) reads in the warning
+  tone.
+- **`TrustMark`** `{ kind, word, check }` — the mark and its word:
+  `sure` · `likely` · `guess` · `two` · `warn` · `looking` · `wait` ·
+  `none` · `failed` · `typed` · `sent` · `stale` · `quiet`.
+- **`AgentMark`** — the platform's agent mark (a filled diamond, from
+  `agent-marks`), re-exported here for what the agent did.
+- **`JobHeader`** `{ name, agent, source, progress, part, cost, menu }` —
+  a column heading as a job: the mark and the name with its menu, then a
+  bar (`part` 0 to 1), the words ("21 of 22 · 3 to check") and the price
+  ("40 cr/row"). `agent={false}` draws a person's column, `source` the line
+  under it ("yours · summit-leads.csv"; default "yours").
+- **`Receipt`** `{ answer, title, question, where, onPick, pickWords,
+  picked, read, by, valueLabel, stateWords, leftTitle, busy, children }`
+  — the answer opened: its head, the value big with its state in words,
+  then the sources as clippings. Two answers are two clippings with Pick
+  on each; a person who left shows the page that says so and, under
+  `leftTitle`, who holds the role now; not found and failed list what was
+  tried, crossed off. `children` go under it (your actions).
+- **`Clipping`** `{ source: { url, title, evidence, read }, trust, mark,
+  title, action, footnote, picked }` — one source: the title, the address
+  and date, the words on the page with the deciding words underlined in
+  the accent. Mark them in the words with `[[…]]` ("[[51–200
+  employees]] · [[85]] members"); without marks the answer's value is
+  underlined where it appears (`decidingWords`).
+- **`TriedList`** `{ tried }` — the pages read, crossed off.
+- **`ReceiptActions`** `{ onType, typePlaceholder, onAskAgain,
+  hintPlaceholder, askCost, askNote, askLabel, hint, busy }` — "Type my
+  own" (yours, never overwritten) and "Ask again" with a hint, its price
+  said under it.
+
+```jsx
+<Receipt answer={a} title="Klarwerk" question="Headcount" where="row 2" read="read 22 Sep"
+  onPick={(which) => pick(a.id, which)}
+  by={<><AgentMark /> Found by the agent · 22 Sep, 10:31</>}>
+  <ReceiptActions onType={(v) => type(a.id, v)} onAskAgain={(h) => askAgain(a.id, h)} askCost="Asking again costs about 40 credits" />
+</Receipt>
+```
+
+## For a second app
+
+- **Suggested values on cells** (a base's cleaner value, a CRM's filled-in
+  title): give the answer `status: "suggested"`, the proposed `value`,
+  its `source`, and pass `onKeep` / `onDrop` to `AnswerDetail`; `needsCheck`
+  counts it. When a person changed the value since, mark it `stale`.
+- **A person's value wins**: map a typed value to `setBy: "person"`; the
+  cell shows a tick and `AnswerDetail` offers no ask-again over it.
+- **Waiting and can't-fill** are yours to compute (which of your columns
+  an answer reads), passed as `waitsFor` / `blockedBy` names.
+- The block draws no toast and no undo: your callbacks save, and your
+  toast offers Undo.
+
+## What it will not do
+
+- Fetch, save or start the agent. Callbacks out; `useJob` is yours.
+- Decide what is sure. The agent says; the mark draws it.
+- Colour a state alone: every state has its words, every mark its shape.