@lotics/ui 4.4.0 → 4.5.0

package/AGENTS.md

@@ -78,9 +78,16 @@ Pick by capability, not by name. (→ the source file for the API.)
 - **AI surfaces** — `PromptField` (the NL command that triggers agent work — NOT a chat),
   `AgentRun` (the live streaming work feed) + `AgentProgress` (its compact, floating, expandable
   form — a composer's "working" state), `Suggestion` (review-for-approval of a proposal)
-  + `Confidence`, `AssistedField` (a confirmable AI estimate), `ChangeReview` (before→after for an
-  agent-proposed edit — whole-set OR 1-by-1), `Clarify` (the agent asks back — a question + quick
-  replies), `Sources` (provenance chips for AI output). See §AI workflows.
+  + `Confidence`, `RecordReview` (an extracted record reviewed + edited before save — fields
+  click-to-edit, Confirm collapses it), `ChangeReview` (before→after for an agent-proposed edit —
+  whole-set OR 1-by-1), `Clarify` (the agent asks back — selectable `ChoiceList` options),
+  `Sources` (provenance chips for AI output). For STRUCTURED AI output the four review
+  surfaces above don't cover: `SpecList` (the "exact breakdown" — a labeled-value spec sheet, the
+  panel of an answer), `MatchRow` (a two-sided AI pairing — source ↔ proposed match + confidence),
+  `Finding` (one ranked briefing/audit insight — severity + metric + sources + action), `Discrepancy`
+  (a field whose value disagrees across sources — pick the truth), `TriageRow` (an incoming item the
+  agent classified + routed), `ScoredOption` (an AI-ranked candidate — score + rationale + specs).
+  See §AI workflows.
 
 ---
 
@@ -218,7 +225,8 @@ Compose the surfaces as a loop, and reach for the right one by job:
 - **Command** — `PromptField`, NOT a chat composer. A prompt TRIGGERS agent work (Enter sends);
   while it runs the field locks and the send spins. The imperative "do this" surface.
 - **Show the work** — `AgentRun`: a live feed of the agent's steps (reasoning, tool calls) on a
-  spine, the running node pulsing violet. Transparent work, NEVER a bare spinner — the
+  spine, the running node a pulsing ink dot (a done step settles to a hollow ring). Transparent
+  work, NEVER a bare spinner — the
   intelligence is legible. On a canvas/composer app reach for `AgentProgress` — `AgentRun`
   collapsed into a floating pill (avatar + current step) that EXPANDS on press; the composer
   morphs into it while running, and reveals again when done.
@@ -227,9 +235,10 @@ Compose the surfaces as a loop, and reach for the right one by job:
   For a shortlist, stack ranked `Suggestion`s (highest confidence first). `ChangeReview` also has a
   **1-by-1** mode — pass `onAcceptItem`/`onRejectItem` and each suggested change gets its own ✓/✕,
   Apply committing only the accepted set (the chat copilot). Nothing auto-applies.
-- **Confirmable estimates** — `AssistedField`: an AI-prefilled value reads as a TINTED ESTIMATE
-  until a person confirms or overrides it — provenance stays visible. Stack several with one
-  form-level "Confirm all".
+- **Review an extracted record** — `RecordReview`: one record the agent pulled from a document, its
+  fields click-to-edit (`InlineTextInput`), with a confidence + Confirm / Remove; Confirm collapses
+  it to a checklist row (Undo to re-open). Stack several under a "Save all" to capture a whole
+  document → table (see `tpl_extract`). Nothing writes until the human confirms + saves.
 - **Ask back** — `Clarify`: when the agent is unsure, it asks a question with quick-reply options
   and PAUSES, instead of guessing wrong. Human-in-the-loop input mid-run.
 - **Provenance** — `Sources`: openable chips saying where the output came FROM (records, a
@@ -240,22 +249,68 @@ Compose the surfaces as a loop, and reach for the right one by job:
   "make it a bit less", but it's a run LOG, not a conversation transcript — that's why it's not a
   chat.)
 
-Four shapes prove the range — pick by whether the work is a living artifact, a conversation, a
-single pass, or generated prose:
-- **Canvas** (`tpl_dieline`) — the page IS the design, a FLOATING composer at the bottom that
-  morphs into `AgentProgress` while running; the centre goes empty → processing → result, and a
-  prompt re-flows the design in place. For a design/document the user shapes over time.
+Ten shapes prove the range. The first four PRODUCE — pick by whether the work is a living artifact,
+a conversation, a single pass, or generated prose:
+- **Canvas** (`tpl_dieline`) — the page IS the design on a pannable/zoomable surface: it stays
+  CENTRED at every zoom (a floating zoom pill bottom-left), the FLOATING composer at the bottom
+  morphs into `AgentProgress` while running, and a pinned PARAMS PANEL (the `RecordReview` field-card
+  in live-edit mode, carrying the single Download; minimizes to a pill) floats centre-right. Panel, zoom pill and composer
+  float ON TOP — they never shift the design. (Floating layers use a `pointerEvents:"none"` wrapper
+  with the interactive child set `"auto"`; RN-Web ignores `"box-none"` in style, so a full-width
+  wrapper would otherwise eat clicks on the canvas behind it.) Change the design by prompt ("5 mm
+  taller") OR by editing a param directly — either re-flows it in place. For a design/document the
+  user shapes over time.
 - **Chat** (`tpl_assistant`) — a conversation where the agent's answer carries suggested edits the
   user approves/rejects **1-by-1** (`ChangeReview` per-item), applying only the accepted set. An AI
   copilot that proposes changes to a record and never commits on its own.
-- **One-shot** (`tpl_extract`) — document → stream → confirm each extracted field → submit. A
-  data-capture pass with no iteration.
+- **One-shot** (`tpl_extract`, `RecordReview`) — read an image → the agent extracts the records →
+  review each (`RecordReview`: fields click-to-edit, Confirm collapses it to a checklist row) →
+  Save all to the table. A data-capture pass; nothing stored until confirmed.
 - **Draft** (`tpl_draft`) — the agent writes a first draft from context; the OUTPUT itself streams
   (the text fills in live), then becomes an editable surface the human refines before sending.
   Tone/length steer it. For generated prose — a reply, a quote, a listing.
 
-The AI accent is **violet** — distinct from the purpose accents (blue=pipeline, emerald=money), it
-marks what came from the agent.
+The next six output STRUCTURE the first four can't — when the answer is a panel of facts, a queue of
+decisions, or a ranked set, don't cram it into chat prose. Each pairs a template with a primitive:
+- **Answer desk** (`tpl_lookup`, `SpecList`) — converse on the LEFT, a pinned STRUCTURED answer on
+  the RIGHT (a verdict header + an exact breakdown + the policies + sources); a follow-up refines the
+  same panel. For look-up-and-explain: tariff/HS, fee lookup, policy Q&A, a spec/compliance desk. The
+  structured answer is the product; chat just steers. (NOT a chat with the answer buried in a bubble.)
+- **Match** (`tpl_match`, `MatchRow`) — the agent proposes PAIRINGS with its reasoning; each row is
+  two-sided (source ↔ proposed counterpart + confidence), accept / reassign / reject, high-confidence
+  batch-accept. The AI reconciliation / dedup / correlation queue. (The deterministic cousin
+  `tpl_reconcile` has no agent reasoning — that's the tell for which to reach for.)
+- **Briefing** (`tpl_briefing`, `Finding`) — a generated narrative over the data + a RANKED list of
+  what needs attention, each finding carrying a severity, a metric, its sources, and one action. The
+  leadership digest / anomaly scan — the agent's COMMENTARY, not a raw dashboard.
+- **Cross-check** (`tpl_crosscheck`, `Discrepancy`) — the agent compares the documents of one
+  transaction and surfaces every field that DISAGREES; resolve each to a source of truth or flag it.
+  The audit / 3-way-match desk. Symmetric (N sources), unlike a before→after edit.
+- **Triage** (`tpl_triage`, `TriageRow`) — an inbox the agent classified + routed; accept the call,
+  override, or dismiss, high-confidence in bulk. Leads, tickets, documents, emails.
+- **Compare** (`tpl_compare`, `ScoredOption`) — the agent SCORES and ranks options with its rationale
+  and the key specs; the human picks one. Quotes, carriers, suppliers, plans.
+
+The AI vocabulary has **no purple accent and no gimmick glyphs** (no sparkles) — but it is NOT
+monochrome: **colour is used where it carries meaning, not for decoration.** What the violet sparkle
+used to carry now reads structurally — **provenance** is an uppercase microlabel naming the artifact
+(`PROPOSED` · `MATCH` · `MISMATCH` · `SUGGESTED EDIT` · `QUESTION`), and the agent's **reasoning** is
+a left-ruled margin note (a hairline rule + muted text), quoted apart from the facts and the human's
+controls — while **status/severity/diffs use functional colour** the way the rest of the kit does:
+- **Confidence** — a 3-tick meter + word, emerald / amber / zinc by level.
+- **Finding severity** — a coloured dot `Badge` + metric: red critical, amber warning, blue note,
+  emerald on-track (+ stacking order, most severe first).
+- **AgentRun** — `Timeline`-style tinted-disc nodes that fade in: a running step spins **blue**, a
+  finished step is an **emerald check**, a failure a **red** alert; the header reads `Working` (blue
+  spinner) / `Done` (emerald check) / `Stopped` (red).
+- **ChangeReview diffs** — the old value struck in **red**, the new value in **green**.
+- **Discrepancy** — the agent's pick gets a **blue** highlight; `Mismatch` reads amber, `Resolved`
+  emerald.
+
+Card chrome (borders, microlabels) stays neutral — colour marks the *state*, never the container.
+The **composer keeps its icons**: `PromptField` is a single-row pill with circular attach + send
+`Button`s; `AgentProgress` is the `WaveAvatar` pill. "No icons" was only ever about the review
+surfaces' sparkles/severity glyphs, not functional affordances.
 
 ---
 
@@ -274,10 +329,14 @@ marks what came from the agent.
     content, sections separated by ONE `Divider`. Do NOT wrap each section in its own `CardHeader`
     (its auto-divider double-stacks hairlines around every title). A card-less full page uses
     `SectionHeading` + `SectionHeadingTitle`. NEVER a bare eyebrow standing in for a section title.
-  · **Eyebrow** (`<Text size="xs" color="muted" transform="uppercase">`, WEIGHTLESS): ONLY a
-    column header or a truly minor one-line label — not a section that owns real content. Don't add
-    `weight`. (A COLORED status word like "Blocked" — `weight="semibold"` + `color="danger"` — is a
-    different element, the verdict word, and keeps its weight.)
+  · **Eyebrow / label** (`<Text size="xs" color="muted" weight="medium">` — **sentence case, NEVER
+    `transform="uppercase"`**): a small quiet label above or beside content — an artifact tag
+    ("Proposed", "Question", "Suggested edit"), a field name, a metric caption, a minor one-line
+    label. **All-caps is banned — it reads as shouting and the redundant uppercasing of every little
+    label is the #1 thing that makes a surface feel templated.** Sentence case + medium weight, full
+    stop. (A COLORED status word — a verdict like "Mismatch" / "Resolved" — keeps the same xs/medium
+    shape with a status `color`, still not uppercase.) This applies to every hand-written label; don't
+    reach for a wrapper component either, just write the `Text`.
   · **Gate header**: a `Dialog` uses `DialogHeaderTitle`; a popover form uses `Text size="sm"
     weight="semibold"` + an optional `xs muted` subtitle.
 - **Time-constrained data gets a period filter** in the header band — `DateRangeFilterField`, never
@@ -401,12 +460,18 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
   `tpl_timeline` (audit feed).
 - **Planning & time** — `tpl_calendar` · `tpl_attendance` · `tpl_shifts`.
 - **Administration** — `tpl_settings`.
-- **AI workflows** — `tpl_dieline` (the design CANVAS: photo → stream → the dieline reveals at
-  centre, the floating composer morphing into `AgentProgress`; prompt to iterate) · `tpl_assistant`
-  (a chat copilot: the agent's answer carries suggested edits approved/rejected 1-by-1) ·
-  `tpl_extract` (one-shot extract-&-confirm: document → stream → confirm each field → submit) ·
-  `tpl_draft` (draft generation: context → the reply text streams into an editable surface →
-  refine → send; tone/length steer it).
+- **AI workflows** — *produce*: `tpl_dieline` (the design CANVAS: photo → stream → the dieline
+  reveals CENTRED on a pannable/zoomable surface, the floating composer morphing into `AgentProgress`,
+  a pinned live-edit params panel centre-right; prompt OR edit a param to iterate) ·
+  `tpl_assistant` (a chat copilot: the agent's answer carries suggested edits approved/rejected
+  1-by-1) · `tpl_extract` (read an image → extract records → review/edit each (`RecordReview`) →
+  Save all) · `tpl_draft` (draft generation: context → the reply text streams into an editable surface
+  → refine → send; tone/length steer it). *Structure*: `tpl_lookup` (the ANSWER desk: converse left,
+  a pinned `SpecList` verdict panel right; a follow-up refines it) · `tpl_match` (AI reconciliation:
+  `MatchRow` pairings with reasoning, accept/reassign/reject) · `tpl_briefing` (a generated narrative
+  + a ranked `Finding` attention list) · `tpl_crosscheck` (the audit desk: `Discrepancy` cards where
+  the documents disagree) · `tpl_triage` (an inbox of `TriageRow`s the agent classified + routed) ·
+  `tpl_compare` (ranked `ScoredOption` candidates the agent scored).
 
 ---
 
@@ -437,7 +502,12 @@ spacer · stack · section_card · page_header · page_content · calendar (cale
 comments_thread · agent_run (live streaming work feed) · agent_progress (its compact floating
 expandable form — a composer's working state) · prompt_field (the NL command surface + optional
 `onAttach`, not a chat) · suggestion (review-for-approval) · confidence (calibrated high/med/low) ·
-assisted_field (confirmable AI estimate) · change_review (before→after — whole-set OR 1-by-1) ·
-clarify (the agent asks back) · sources (provenance chips) ·
+record_review (RecordReview — an extracted record reviewed + edited before save) · change_review (before→after — whole-set OR 1-by-1) ·
+clarify (the agent asks back, via ChoiceList) · choice_list (ChoiceList — selectable answer options,
+the agent's quick-reply surface) · sources (provenance chips, per-kind glyphs) · spec_list (SpecList — the exact
+labeled-value breakdown, the panel of an answer) · match_row (MatchRow — a two-sided AI pairing) ·
+finding (Finding — one ranked briefing/audit insight) · discrepancy (Discrepancy — a field that
+disagrees across sources) · triage_row (TriageRow — an item the agent classified + routed) ·
+scored_option (ScoredOption — an AI-ranked candidate) ·
 format_money · format_date · colors (solid · tint · ramp · ColorName ·
 isColorName · asColorName — coerce a stored option/status token to a ColorName, neutral fallback).

package/examples/tpl_assistant.tsx

@@ -1,8 +1,7 @@
 import { useRef, useState } from "react";
 import { ScrollView, View } from "react-native";
-import { colors, solid, tint } from "@lotics/ui/colors";
+import { colors } from "@lotics/ui/colors";
 import { Text } from "@lotics/ui/text";
-import { Icon } from "@lotics/ui/icon";
 import { DotsIndicator } from "@lotics/ui/dots_indicator";
 import { PromptField } from "@lotics/ui/prompt_field";
 import { ChangeReview, type ChangeReviewItem, type ChangeReviewItemStatus } from "@lotics/ui/change_review";
@@ -80,8 +79,8 @@ export function TplAssistant() {
   return (
     <View style={{ flex: 1, backgroundColor: colors.zinc[50] }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingHorizontal: 20, paddingVertical: 12, borderBottomWidth: 1, borderBottomColor: colors.zinc[200], backgroundColor: colors.background }}>
-        <View style={{ width: 24, height: 24, borderRadius: 7, alignItems: "center", justifyContent: "center", backgroundColor: tint("violet", 0.12) }}>
-          <Icon name="sparkles" size={13} color={solid("violet")} />
+        <View style={{ width: 24, height: 24, borderRadius: 7, alignItems: "center", justifyContent: "center", backgroundColor: colors.zinc[100] }}>
+          <View style={{ width: 4, height: 4, borderRadius: 2, backgroundColor: colors.zinc[900] }} />
         </View>
         <Text size="sm" weight="semibold">Record assistant</Text>
       </View>
@@ -100,8 +99,8 @@ export function TplAssistant() {
           const active = m.changes != null && !m.applied;
           return (
             <View key={m.id} style={{ flexDirection: "row", gap: 10, alignItems: "flex-start" }}>
-              <View style={{ width: 26, height: 26, borderRadius: 8, alignItems: "center", justifyContent: "center", backgroundColor: tint("violet", 0.12), marginTop: 1 }}>
-                <Icon name="sparkles" size={14} color={solid("violet")} />
+              <View style={{ width: 26, height: 26, borderRadius: 8, alignItems: "center", justifyContent: "center", backgroundColor: colors.zinc[100], marginTop: 1 }}>
+                <View style={{ width: 4, height: 4, borderRadius: 2, backgroundColor: colors.zinc[900] }} />
               </View>
               <View style={{ flex: 1, gap: 10 }}>
                 {m.typing ? (
@@ -115,6 +114,7 @@ export function TplAssistant() {
                     applyLabel="Apply accepted"
                     onAcceptItem={active ? (i) => decide(m.id, i, "accepted") : undefined}
                     onRejectItem={active ? (i) => decide(m.id, i, "rejected") : undefined}
+                    onUndoItem={active ? (i) => setDecisions((d) => { const n = { ...d }; delete n[`${m.id}:${i}`]; return n; }) : undefined}
                     onApply={active ? () => applyMsg(m.id) : undefined}
                     onDiscard={active ? () => setMessages((ms) => ms.map((x) => (x.id === m.id ? { ...x, applied: true } : x))) : undefined}
                   />

package/examples/tpl_briefing.tsx

@@ -0,0 +1,121 @@
+import { useState } from "react";
+import { ScrollView, View } from "react-native";
+import { Text } from "@lotics/ui/text";
+import { colors } from "@lotics/ui/colors";
+import { KPIStrip } from "@lotics/ui/kpi_strip";
+import { SegmentedControl } from "@lotics/ui/segmented_control";
+import { Sources } from "@lotics/ui/sources";
+import { Finding, type FindingSeverity } from "@lotics/ui/finding";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Template · Briefing — the agent reads the period's data and writes a short
+// narrative, then a RANKED list of what needs attention. Each finding carries a
+// severity, a headline metric, the sources it rests on, and the one action it
+// suggests. Unlike a dashboard (raw charts), this is the agent's COMMENTARY:
+// what changed, what's at risk, what to do. The leadership digest / daily ops
+// brief / anomaly scan. The narrative explains; the findings are the worklist.
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface F {
+  severity: FindingSeverity;
+  title: string;
+  detail: string;
+  metric: string;
+  metricCaption: string;
+  action: string;
+  sources: { id: string; label: string; kind: "record" | "table" | "document" }[];
+}
+
+const NARRATIVE: Record<"today" | "week", string> = {
+  today:
+    "Volume held steady at 41 active shipments. Three reefer containers to Hamburg are inside the demurrage window and need a pickup booked today. Cash collection is lagging — five invoices crossed 30 days overdue. On-time delivery improved on the back of the new Cát Lái slotting.",
+  week:
+    "A solid week: 268 shipments moved, on-time delivery up 6 points after the Cát Lái slotting change. Two ocean lanes slipped below the 12% margin target on bunker surcharges. Receivables remain the soft spot — ₫120M is now past 30 days, concentrated in two accounts.",
+};
+
+const FINDINGS: Record<"today" | "week", F[]> = {
+  today: [
+    { severity: "critical", title: "3 reefer containers at demurrage risk", detail: "Hamburg shipments HBL-4471/4472/4480 hit free-time expiry at 18:00 today; no pickup is booked.", metric: "₫48M", metricCaption: "exposure", action: "Open the shipments", sources: [{ id: "a1", label: "SHIP-4471", kind: "record" }, { id: "a2", label: "Demurrage tracker", kind: "table" }] },
+    { severity: "warning", title: "5 invoices overdue past 30 days", detail: "Two accounts — Crestline and Meridian — make up most of the balance. No promise-to-pay logged this week.", metric: "₫120M", metricCaption: "overdue", action: "Open receivables", sources: [{ id: "a3", label: "Aged receivables", kind: "table" }] },
+    { severity: "warning", title: "Margin on the Hamburg lane below target", detail: "Bunker surcharge rose 9%; the lane is at 9.8% gross vs the 12% floor.", metric: "−2.2 pts", metricCaption: "vs target", action: "Review lane pricing", sources: [{ id: "a4", label: "Lane P&L", kind: "table" }] },
+    { severity: "positive", title: "On-time delivery improving", detail: "The Cát Lái slotting change lifted on-time pickups for the third day running.", metric: "+6 pts", metricCaption: "3-day", action: "See the trend", sources: [{ id: "a5", label: "OTD report", kind: "document" }] },
+  ],
+  week: [
+    { severity: "critical", title: "Receivables concentration risk", detail: "₫120M past 30 days sits in two accounts; one is also near its credit limit.", metric: "2", metricCaption: "accounts", action: "Open receivables", sources: [{ id: "b1", label: "Aged receivables", kind: "table" }] },
+    { severity: "warning", title: "Two ocean lanes below margin target", detail: "Hamburg and Rotterdam slipped under 12% on bunker surcharges sustained all week.", metric: "2", metricCaption: "lanes", action: "Review lane pricing", sources: [{ id: "b2", label: "Lane P&L", kind: "table" }] },
+    { severity: "positive", title: "On-time delivery up 6 points", detail: "The slotting change held all week — the strongest OTD in two months.", metric: "+6 pts", metricCaption: "this week", action: "See the trend", sources: [{ id: "b3", label: "OTD report", kind: "document" }] },
+    { severity: "info", title: "RFQ volume rising", detail: "12 new quote requests this week, ahead of the trailing average — capacity planning should get ahead of it.", metric: "12", metricCaption: "RFQs", action: "Open the pipeline", sources: [{ id: "b4", label: "Quote pipeline", kind: "table" }] },
+  ],
+};
+
+export function TplBriefing() {
+  const [period, setPeriod] = useState<"today" | "week">("today");
+  const findings = FINDINGS[period];
+  const attention = findings.filter((f) => f.severity === "critical" || f.severity === "warning").length;
+
+  return (
+    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+      <View style={{ width: "100%", maxWidth: 860, alignSelf: "center", gap: 16 }}>
+        <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 16 }}>
+          <View style={{ flex: 1, gap: 2 }}>
+            <Text size="xl" weight="semibold">Operations briefing</Text>
+            <Text size="sm" color="muted">What the agent sees in the numbers — and what needs a decision</Text>
+          </View>
+          <SegmentedControl
+            accessibilityLabel="Period"
+            options={[
+              { label: "Today", value: "today" },
+              { label: "This week", value: "week" },
+            ]}
+            value={period}
+            onValueChange={setPeriod}
+          />
+        </View>
+
+        {/* the generated narrative */}
+        <View style={{ borderWidth: 1, borderColor: colors.zinc[200], backgroundColor: colors.white, borderRadius: 14, padding: 18, gap: 12 }}>
+          <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+            <Text size="xs" color="muted" weight="medium" style={{ flex: 1 }}>Summary</Text>
+            <Text size="xs" color="muted">{period === "today" ? "as of 14:20" : "week to date"}</Text>
+          </View>
+          <Text size="md" style={{ lineHeight: 22 }}>{NARRATIVE[period]}</Text>
+          <Sources
+            label="Read from"
+            onOpen={() => {}}
+            sources={[
+              { id: "n1", label: "Shipments", kind: "table" },
+              { id: "n2", label: "Aged receivables", kind: "table" },
+              { id: "n3", label: "Lane P&L", kind: "table" },
+            ]}
+          />
+        </View>
+
+        <KPIStrip
+          items={[
+            { label: "Active shipments", value: period === "today" ? 41 : 268, format: "number", trend: period === "today" ? 0 : 4 },
+            { label: "On-time delivery", value: "94%", trend: 6 },
+            { label: "Overdue receivables", value: 120_000_000, format: "currency", compact: true, tone: "danger" },
+            { label: "Needs attention", value: attention, format: "number", tone: attention > 0 ? "warning" : "default" },
+          ]}
+        />
+
+        <View style={{ gap: 10 }}>
+          <Text size="sm" weight="semibold">Needs attention</Text>
+          {findings.map((f, i) => (
+            <Finding
+              key={i}
+              severity={f.severity}
+              title={f.title}
+              detail={f.detail}
+              metric={f.metric}
+              metricCaption={f.metricCaption}
+              sources={f.sources}
+              onOpenSource={() => {}}
+              action={{ label: f.action, onPress: () => {} }}
+            />
+          ))}
+        </View>
+      </View>
+    </ScrollView>
+  );
+}

package/examples/tpl_compare.tsx

@@ -0,0 +1,133 @@
+import { useState } from "react";
+import { ScrollView, View } from "react-native";
+import { Text } from "@lotics/ui/text";
+import { colors } from "@lotics/ui/colors";
+import { Callout, CalloutText, CalloutTitle } from "@lotics/ui/callout";
+import { ScoredOption } from "@lotics/ui/scored_option";
+import type { SpecRow } from "@lotics/ui/spec_list";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Template · Compare — the agent SCORES and ranks the options against the
+// criteria, shows its reasoning and the key specs, and the human picks one. The
+// agent does the legwork (gather, normalise, score); the choice stays the
+// human's. Quotes, carriers, suppliers, plans, routes. The recommended option
+// wears a RECOMMENDED label; selecting one settles the shortlist to the decision.
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface O {
+  id: string;
+  rank: number;
+  title: string;
+  subtitle: string;
+  score: number;
+  rationale: string;
+  specs: SpecRow[];
+  recommended?: boolean;
+}
+
+const OPTIONS: O[] = [
+  {
+    id: "o1",
+    rank: 1,
+    title: "Maersk — Cát Lái → Hamburg",
+    subtitle: "Direct, weekly service · reefer guaranteed",
+    score: 0.92,
+    rationale: "Best balance: only 4% above the cheapest, but the most reliable schedule and guaranteed reefer plugs — lowest demurrage risk for time-sensitive cargo.",
+    recommended: true,
+    specs: [
+      { label: "All-in rate", value: "$2,840" },
+      { label: "Transit", value: "28 days" },
+      { label: "Schedule reliability", value: "94%" },
+      { label: "Free time", value: "14 days" },
+    ],
+  },
+  {
+    id: "o2",
+    rank: 2,
+    title: "CMA CGM — Cát Lái → Hamburg",
+    subtitle: "1 transshipment at Singapore",
+    score: 0.78,
+    rationale: "Cheapest of the four, but the Singapore transshipment adds three days and a reliability hit — workable for non-urgent cargo.",
+    specs: [
+      { label: "All-in rate", value: "$2,730" },
+      { label: "Transit", value: "31 days" },
+      { label: "Schedule reliability", value: "86%" },
+      { label: "Free time", value: "10 days" },
+    ],
+  },
+  {
+    id: "o3",
+    rank: 3,
+    title: "Hapag-Lloyd — Cát Lái → Hamburg",
+    subtitle: "Direct, premium service",
+    score: 0.64,
+    rationale: "Fastest transit and strong reliability, but the premium rate is hard to justify unless the customer pays for speed.",
+    specs: [
+      { label: "All-in rate", value: "$3,210" },
+      { label: "Transit", value: "26 days" },
+      { label: "Schedule reliability", value: "92%" },
+      { label: "Free time", value: "10 days" },
+    ],
+  },
+  {
+    id: "o4",
+    rank: 4,
+    title: "ONE — Cát Lái → Hamburg",
+    subtitle: "2 transshipments · no reefer guarantee",
+    score: 0.41,
+    rationale: "Lowest score: two transshipments and no guaranteed reefer plug make it unsuitable for frozen cargo, despite a mid-range rate.",
+    specs: [
+      { label: "All-in rate", value: "$2,910" },
+      { label: "Transit", value: "34 days" },
+      { label: "Schedule reliability", value: "79%" },
+      { label: "Free time", value: "7 days" },
+    ],
+  },
+];
+
+export function TplCompare() {
+  const [chosen, setChosen] = useState<string | null>(null);
+  const pick = OPTIONS.find((o) => o.id === chosen) ?? null;
+
+  return (
+    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+      <View style={{ width: "100%", maxWidth: 720, alignSelf: "center", gap: 16 }}>
+        <View style={{ gap: 2 }}>
+          <Text size="xl" weight="semibold">Freight options</Text>
+          <Text size="sm" color="muted">Ocean · Cát Lái → Hamburg · 2×40HC reefer · frozen shrimp</Text>
+        </View>
+
+        <View style={{ borderLeftWidth: 2, borderLeftColor: colors.zinc[300], paddingLeft: 12 }}>
+          <Text size="sm" color="muted">
+            The agent scored four quotes against cost, transit time and schedule reliability, weighted for time-sensitive reefer cargo.
+          </Text>
+        </View>
+
+        {pick ? (
+          <Callout tone="neutral">
+            <CalloutTitle>Chosen · {pick.title}</CalloutTitle>
+            <CalloutText>{pick.specs[0].label} {String(pick.specs[0].value)} · {String(pick.specs[1].value)} transit. Booking can proceed on this option.</CalloutText>
+          </Callout>
+        ) : null}
+
+        <View style={{ gap: 12 }}>
+          {OPTIONS.map((o) => (
+            <ScoredOption
+              key={o.id}
+              rank={o.rank}
+              title={o.title}
+              subtitle={o.subtitle}
+              score={o.score}
+              rationale={o.rationale}
+              specs={o.specs}
+              recommended={o.recommended}
+              selected={chosen === o.id}
+              selectLabel="Choose this option"
+              onSelect={() => setChosen((c) => (c === o.id ? null : o.id))}
+            />
+          ))}
+        </View>
+      </View>
+    </ScrollView>
+  );
+}

package/examples/tpl_crosscheck.tsx

@@ -0,0 +1,120 @@
+import { useState } from "react";
+import { ScrollView, View } from "react-native";
+import { Text } from "@lotics/ui/text";
+import { colors } from "@lotics/ui/colors";
+import { KPIStrip } from "@lotics/ui/kpi_strip";
+import { Callout, CalloutText, CalloutTitle } from "@lotics/ui/callout";
+import { Discrepancy, type DiscrepancyValue } from "@lotics/ui/discrepancy";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Template · Cross-check — the agent compares the documents of one transaction
+// and surfaces every field whose value DISAGREES across sources. Each card lays
+// the conflicting values side by side (with where each came from), marks the one
+// the agent believes, and the human resolves to a truth or flags it. The audit /
+// 3-way-match / contract-vs-invoice desk. Symmetric (N sources disagree), unlike
+// a before→after edit. The agreeing fields stay out of the way — only conflicts
+// need a decision.
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface D {
+  id: string;
+  field: string;
+  values: DiscrepancyValue[];
+  note: string;
+}
+
+const SEED: D[] = [
+  {
+    id: "d1",
+    field: "Total cartons",
+    values: [
+      { source: "Shipping instruction", value: "525" },
+      { source: "Commercial invoice", value: "520", recommended: true },
+      { source: "Packing list", value: "520" },
+    ],
+    note: "Two of three documents agree at 520; the SI looks stale — it predates the final load.",
+  },
+  {
+    id: "d2",
+    field: "Net weight",
+    values: [
+      { source: "Commercial invoice", value: "11,980 kg" },
+      { source: "Packing list", value: "12,050 kg", recommended: true },
+    ],
+    note: "The packing list carries the measured weight; the CI rounded for the invoice.",
+  },
+  {
+    id: "d3",
+    field: "Incoterm",
+    values: [
+      { source: "Shipping instruction", value: "FOB" },
+      { source: "Commercial invoice", value: "CIF", recommended: true },
+    ],
+    note: "The commercial invoice governs the sale terms — CIF matches the freight prepaid on the bill of lading.",
+  },
+  {
+    id: "d4",
+    field: "HS code",
+    values: [
+      { source: "Commercial invoice", value: "0306.17", recommended: true },
+      { source: "Customs draft", value: "0306.16" },
+    ],
+    note: "0306.16 is cold-water shrimp; the goods are warm-water Penaeidae → 0306.17. The CI is right — fix the draft.",
+  },
+];
+
+const CHECKED = 22;
+
+export function TplCrosscheck() {
+  const [res, setRes] = useState<Record<string, { idx?: number; flagged?: boolean }>>({});
+
+  const resolvedCount = Object.values(res).filter((r) => r.idx != null || r.flagged).length;
+  const openCount = SEED.length - resolvedCount;
+
+  return (
+    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+      <View style={{ width: "100%", maxWidth: 760, alignSelf: "center", gap: 16 }}>
+        <View style={{ gap: 2 }}>
+          <Text size="xl" weight="semibold">Document cross-check</Text>
+          <Text size="sm" color="muted">Shipment HBL-4471 · Shipping instruction · Commercial invoice · Packing list · Customs draft</Text>
+        </View>
+
+        <KPIStrip
+          items={[
+            { label: "Fields checked", value: CHECKED, format: "number" },
+            { label: "In agreement", value: CHECKED - SEED.length, format: "number" },
+            { label: "Disagree", value: openCount, format: "number", tone: openCount > 0 ? "danger" : "default", info: "Fields whose value differs across the documents — each needs a resolution before the set can be filed." },
+            { label: "Resolved", value: resolvedCount, format: "number" },
+          ]}
+        />
+
+        {openCount > 0 ? (
+          <Callout tone="warning">
+            <CalloutTitle>{openCount} of {CHECKED} fields disagree across the documents</CalloutTitle>
+            <CalloutText>The agent reconciled the other {CHECKED - SEED.length}. Resolve each conflict to a source of truth, or flag it for the desk.</CalloutText>
+          </Callout>
+        ) : (
+          <Callout tone="success">
+            <CalloutTitle>All conflicts resolved</CalloutTitle>
+            <CalloutText>Every field now has a single source of truth — the document set is ready to file.</CalloutText>
+          </Callout>
+        )}
+
+        <View style={{ gap: 10 }}>
+          {SEED.map((d) => (
+            <Discrepancy
+              key={d.id}
+              field={d.field}
+              values={d.values}
+              note={d.note}
+              resolvedIndex={res[d.id]?.idx}
+              flagged={res[d.id]?.flagged}
+              onResolve={(idx) => setRes((p) => ({ ...p, [d.id]: { idx } }))}
+              onFlag={() => setRes((p) => ({ ...p, [d.id]: { flagged: true } }))}
+            />
+          ))}
+        </View>
+      </View>
+    </ScrollView>
+  );
+}