@lotics/ui 14.2.0 → 14.3.1

package/docs/ai_patterns.md

@@ -39,7 +39,7 @@ Three shapes:
 
 The Document desk's Use-AI fork IS this table as UI: Extract data (1) · Cross-check (2) ·
 Edit with AI (3) — one entry point, three outcome shapes
-([`tpl_documents`](../examples/tpl_documents.tsx)).
+([`tpl_record`](../examples/tpl_record.tsx)'s Documents section).
 
 ## Command / compose — `Composer`
 
@@ -138,14 +138,20 @@ pass it as the `error` prop and it renders as a terminal danger row under the tr
 
 **In a bounded container, wrap it in `FollowScroll`.** An `AgentRun` streaming inside a dialog,
 drawer, or fixed-height panel grows BELOW the fold — a plain scroll container doesn't follow. Wrap
-the feed: `<FollowScroll style={{ maxHeight: … }}><AgentRun … /></FollowScroll>` — pinned to the
-newest content while streaming, unpinned when the human scrolls up to read (`AgentProgress`'s
-expanded panel already does this). A full-page inverted list (chat) follows by construction and
-doesn't need it.
+the feed: `<FollowScroll style={{ maxHeight: … }}><AgentRun … /></FollowScroll>` — the same
+inverted-list mechanism as a chat message list, packaged as a wrapper: the follow happens at
+LAYOUT level (each growth paints already pinned — no scroll-after-paint flash), scrolling up
+releases it, and the feed stays at the newest content when the run settles (`AgentProgress`'s
+expanded panel does this). When settling REPLACES the feed with different content (a results
+pane), swap `FollowScroll` for a plain scroller on the phase flip — the remount opens the new
+content at the top; a transcript that persists just stays in `FollowScroll`. A full-page chat
+list is already inverted and doesn't need the wrapper.
 
 Fed natively by `@lotics/app-sdk`'s `useAgentRun().parts` (reasoning + per-tool I/O + state come
 for free — no hand-assembly): `<AgentRun parts={run.parts} state={…} error={run.error} />` — see
-[the SDK doc](../../app-sdk/docs/ai.md) for the hook. Requires `ai` as an optional (type-only) peer.
+[the SDK doc](../../app-sdk/docs/ai.md) for the hook. The `ai` package is a regular dependency of
+`@lotics/ui` — its part TYPES resolve transitively in any consumer's typecheck with nothing to
+install; the imports are type-only (purity-enforced), so no `ai` runtime ever enters a bundle.
 **Reasoning only shows when the model produces it** — the declared model must support thinking
 (Sonnet / Opus, not Haiku); the renderer shows every reasoning part it's handed.
 
@@ -171,7 +177,7 @@ when done.
 
 Every "the agent proposes → the human accepts / edits / dismisses → nothing auto-applies" surface
 composes from twelve pieces in three groups (all in `@lotics/ui/change_review`; worked example:
-[`tpl_documents`](../examples/tpl_documents.tsx)).
+[`tpl_record`](../examples/tpl_record.tsx)'s Use-AI extract flow).
 
 **Frame**
 
@@ -278,7 +284,9 @@ Back / Next / Cancel / Submit (Next/Submit primary), the step position an eyebro
 question — no progress bar, and no eyebrow at all for a single question. Each step is a `Clarify`; advance only once the
 current question is answered; `onSubmit` gives one `{ value, custom }` per question (aligned by index,
 `custom` true when the answer came from "Other…"), `onCancel` dismisses. All navigation chrome is
-locale-wired (the `clarify` slice). The multi-question form of the ask-back.
+locale-wired (the `clarify` slice). The multi-question form of the ask-back. Worked example:
+[`tpl_item_list`](../examples/tpl_item_list.tsx)'s intake fork (the wizard between the analyze
+and import runs).
 
 ## Provenance — `Sources`
 
@@ -362,7 +370,7 @@ ranked set, don't cram it into chat prose:
   so the alternatives are first-class and picking a different one changes the outcome; refining
   the description re-ranks. For look-up-and-explain: tariff/classification codes, fee lookup,
   policy Q&A, a spec/compliance desk. (NOT a chat with the answer in a bubble.)
-- **Document desk** ([`tpl_documents`](../examples/tpl_documents.tsx) — THE go-to for
+- **Document desk** (in [`tpl_record`](../examples/tpl_record.tsx) — THE go-to for
   document-driven records) — the record's files block feeds ONE "Use AI" entry that FORKS into
   the two document tasks, each a specialized run with a task-pure result: **Extract** (files
   read → fields already matching fold into one quiet line → every add / update / conflict a
@@ -376,6 +384,15 @@ ranked set, don't cram it into chat prose:
   full-page `FileGalleryModal`. Plus **Create documents**: a readiness checklist (unchecked by
   default, missing inputs called out) → generate → the files land back on the record. Never merge
   the two AI tasks into one mixed output — the fork is the design.
+- **Intake desk** (in [`tpl_item_list`](../examples/tpl_item_list.tsx)'s "Enter data" fork) — the
+  register's New CTA leads with AI: a `FileDropzone` hero → a short ANALYZE run reads the files →
+  `ClarifyWizard` asks the ambiguities the analysis surfaced → the IMPORT run drafts records →
+  `ChangeRecord` cards + one Apply land the rows; the manual VARIANTS sit below the dropzone as
+  `CardSelectItem`s, each opening the classic create-then-refine form. The template mocks the
+  clarify step as TWO app-orchestrated phases (analyze-run → wizard → import-run); a real app
+  can do it in ONE run — every app agent carries `ask_user_choice`, so the run PARKS on the
+  agent's own question and `useAgentRun().pendingChoice`/`answerChoice` drive the same
+  `ClarifyWizard` (see the SDK's [ai doc](../../app-sdk/docs/ai.md)).
 - **Triage** — an inbox the agent classified + routed is a `ChangeReview` of `Change`s (body: the
   item + the agent's call; the standard Keep/Drop verbs; Keep-all covers the high-confidence
   sweep). Leads, tickets, documents, emails.

package/docs/catalog.md

@@ -1001,10 +1001,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`agent_progress`** — `AgentProgress`: `AgentRun`'s compact, floating, expandable form (same
   `parts` prop) — a composer's working state.
 - **`follow_scroll`** — `FollowScroll`: a scroll container that FOLLOWS its growing content —
-  pinned to the bottom as children stream in; scrolling up unpins (read history), scrolling back
-  re-pins. Wrap a streaming `AgentRun` with it in any bounded container (a dialog, a drawer,
-  a panel — put the height bound on `style`); `AgentProgress`'s expanded panel uses it. Chat
-  doesn't need it (an inverted message list follows by construction).
+  the chat message list's inverted mechanism packaged as a wrapper (single-cell inverted list),
+  so the follow happens at LAYOUT level: each growth paints already pinned (no flash), scrolling
+  up releases it, and short content still reads top-down. Wrap a streaming `AgentRun` with it in
+  any bounded container (a dialog, a drawer, a panel — put the height bound on `style`);
+  `AgentProgress`'s expanded panel uses it. Inherits the inverted pattern's quirks (scrollbar
+  thumb runs opposite; keyboard paging inverted) — same as chat. A full-page chat list is
+  already inverted and doesn't need it.
 - **`confidence`** — `Confidence` + `ConfidenceLevel` + `levelFromScore`: calibrated
   high/med/low; localized via the provider.
 - **`change_review`** — the COMPOUND review family — frame: `ChangeReview` provider/stack ·

package/docs/templates.md

@@ -50,7 +50,7 @@ the package index is [../AGENTS.md](../AGENTS.md).
 | Shift signup + staffing | `tpl_shifts` |
 | AI produces a visual artifact on a canvas | `tpl_dieline` |
 | AI ranks answers — look-up-and-explain | `tpl_lookup` |
-| AI over a record's documents (extract / cross-check / generate) | `tpl_documents` |
+| AI over a record's documents (extract / cross-check / generate) | `tpl_record` — its Documents + Document set sections |
 
 ## Composition rules — how a record surface is assembled
 
@@ -204,6 +204,17 @@ screens — register, per-row action, gated selection, and act-on-many in one. T
     newest first — an entry's attachments ride its expandable details as a thumbnail grid
     whose press opens the shared `FileGalleryModal`.
   - A closing `DangerZone`.
+- **The "Enter data" INTAKE FORK** (the New CTA) — AI FIRST, the form as fallback, one phased
+  dialog: a `FileDropzone` hero (drop the customer's files) → a short ANALYZE stream
+  (`AgentRun` in a `FollowScroll`) reads them → `ClarifyWizard` asks the ambiguities the
+  analysis surfaced (described options, one custom-answer slot) → the IMPORT stream drafts the
+  records → `ChangeRecord` cards to Keep/Drop (fee editable in place) + one outcome-named
+  Apply that really lands the rows in the register (no drawer on a bulk landing). BELOW the
+  dropzone, "or enter manually" → the record VARIANTS as `CardSelectItem`s, each opening the
+  same THREE-field create-then-refine form (a single manual create still opens its drawer).
+  The template mocks the clarify step as two app-orchestrated phases; a real app can do it in
+  ONE run — every app agent carries `ask_user_choice`, so the run parks on the agent's own
+  question and `useAgentRun().pendingChoice`/`answerChoice` drive the same `ClarifyWizard`.
 
 ### `tpl_pick` — the guided queue
 
@@ -266,15 +277,13 @@ billing, and quick-capture templates. Top → bottom:
   (dashed add-ghost when unset), sized to the list's `trailingWidth` so the title never overlaps.
   (Contrast the General section's dates/assignee, the same editors in the default `variant="form"`
   — a zinc-50 chip + hover-border + the full member chip.)
-- **Documents** — the Agents "Document desk" pattern (shared with `tpl_documents` — change
-  it in BOTH): the register `Table` (search · Add files) whose selection feeds the
-  `FloatingActionBar` → ONE "Use AI" fork (extract / cross-check / edit-with-AI). Every
-  row's leading visual is a `FileThumbnail` in ONE square 32px slot — an image file fills
-  it as a real thumbnail, a document centers its badge in it — never a bare `FileBadge`
-  (mixed footprints misalign the identity column). ONE
-  sanctioned divergence: GENERATION — on the record page this desk holds what ARRIVES and
-  Create moves to the Document set OUTPUT section below; `tpl_documents` (no output
-  pipeline on its page) keeps the toolbar "Create documents" dialog.
+- **Documents** — the Agents "Document desk" pattern (this template is its worked example —
+  see the Agents chapter below): the register `Table` (search · Add files) whose selection
+  feeds the `FloatingActionBar` → ONE "Use AI" fork (extract / cross-check / edit-with-AI).
+  Every row's leading visual is a `FileThumbnail` in ONE square 32px slot — an image file
+  fills it as a real thumbnail, a document centers its badge in it — never a bare `FileBadge`
+  (mixed footprints misalign the identity column). The desk holds what ARRIVES; generation
+  lives in the Document set OUTPUT section below.
 - **Customer — the LINKED-RECORD reference** via **`LinkedRecordBox`**: another record's data
   NEVER renders as field rows on this one — a BORDERED, fully pressable box (glyph anchor ·
   identity · facts stacked VERTICALLY) whose press opens the detail drawer; the verbs ride the
@@ -460,8 +469,9 @@ double-shift days flagged). Accepting and assigning move the board live.
 ## Agents
 
 Screens where AI does the work and the human reviews. `tpl_dieline` *produces* an artifact;
-`tpl_lookup` and `tpl_documents` *structure* information for a decision. The AI component
-contracts and the propose→review→apply loop live in [ai_patterns.md](./ai_patterns.md).
+`tpl_lookup` *structures* information for a decision; the document desk (in `tpl_record`)
+does both over a record's files. The AI component contracts and the propose→review→apply
+loop live in [ai_patterns.md](./ai_patterns.md).
 
 ### `tpl_dieline` — the design canvas
 
@@ -484,12 +494,15 @@ rows, policy `Callout`s, `Confidence`, and `Sources`. The flow is input → matc
 a single confident verdict: classification is ambiguous, so the alternatives are first-class.
 Refine the description in a follow-up and the ranking updates.
 
-### `tpl_documents` — the document desk
+### The document desk — in `tpl_record`
 
-THE worked example for everything document-driven on a record. A record's files block feeds
-ONE **"Use AI"** entry — the one AI entry point, never per-row AI buttons (the per-row `⋯`
+THE worked example for everything document-driven on a record lives on the record template
+(its Documents section — no standalone template). A record's files block feeds ONE
+**"Use AI"** entry — the one AI entry point, never per-row AI buttons (the per-row `⋯`
 menu holds only Rename/Download). Inside its dialog the run FORKS into three tasks as
-`CardSelectItem`s (select → a confirming footer CTA, never one-click):
+`CardSelectItem`s (select → a confirming footer CTA, never one-click), and the streaming
+phase runs inside a `FollowScroll` (swapped back to `DialogScrollArea` on the phase flip,
+so review opens at the top):
 
 - **Extract** (read the documents, fill the record) — the open `ChangeFields` review: ONE
   `Change` section per record whose body stacks a `ChangeField` per proposed value (label ·
@@ -502,10 +515,9 @@ menu holds only Rename/Download). Inside its dialog the run FORKS into three tas
 - **Edit with AI** — the `askAi` handoff: dialogue-shaped file iteration happens in the
   platform chat (the documents attached to a fresh thread), not in the app.
 
-Separately, a **Create documents** action opens its own dialog: a readiness checklist
-(hand-composed rows — per-document missing inputs open a fill screen, saved values recompute
-readiness) → generation runs as a visible `AgentRun`, never a teleport → generated files stay
-PENDING (previewable) until the user commits them onto the record.
+GENERATION is separate and deterministic — the record's Document set OUTPUT section
+(readiness checklist → template fill with a `loading` trigger, never `AgentRun` theater;
+the set appears at once).
 
 All mock — `useState` plus a timer streams the `AgentRun`; a real app drives the same
 components from its live agent run.