# Templates — the worked example screens

Each of the registry's shapes (`AGENTS.md`) owns its strip, its columns and which give way
on a phone, its cells and its empty states.

**A job none of them fits is a `custom` screen on the frame they configure** — `ShapeFrame`:
state its columns, `identity` and `record`.

**`record` is the row's DOOR in one of three forms**: `onOpen` a page, `render` the drawer,
`expand` the row's own rest revealed under it, one row at a time — for a line with no record worth
leaving the set for.

**The column a shape is NAMED for** rides under the identity where width cannot seat it.
**Reading a page at a time takes `more`, and states no TOTAL while `hasMore`**: `totals`, `above`
and a column's `total` stand down for the loaded count. **A run at a time takes `group`** — a
subhead per key over ONE column grid, the strip cutting the set before the runs fold it, and the
key then leaving the columns. **Rows leave and arrive left of the New**: `saved` takes the rows the
strip and the search KEPT; `taken` is a plain node, because the rows an import is about do not
exist yet.

## Which device answers the question

**Pick by the JOB, not the domain** — a pick run and a claims queue are the same shape. The entry,
the shape or archetype that draws it, the nearest WRONG device, and the worked example for a job
whose shape has not shipped. How loud each part is drawn is [hierarchy.md](./hierarchy.md).

| The reader must | Device | Not | Example |
|---|---|---|---|
| Scan a set and search it | the register shapes | a card grid | `tpl_item_list` |
| Read one record whole | `RecordPage`, a `work_record` page | a form | `tpl_record` |
| Read one line of a parent | the `line` drawer | a page of its own | |
| Read a sequence in time | `Timeline` | `Stepper` | |
| Show progress through steps | `Stepper`, `RecordProgress` | `Checklist` | |
| Work an ordered run, a step at a time | `GuidedRun` | `Stepper` | |
| See a set that must be COMPLETE | `Checklist`, `RecordExpectedSet` | `RecordFiles` | |
| Read a trip's stops in order | `Itinerary` — a list, `grouped` by day when the reader asks | a date column | `tpl_calendar`, `tpl_attendance` |
| Compare a figure with a reference | `ComparisonBar` | `Progress` | |
| Read a level against a limit | `LevelCell`, `MonitoredAssetSet` | `NumberCell` | |
| Read a composition | `Breakdown` | `PieChart` | `tpl_rollup` |
| Fold a set by one key | `GroupRegister` | a `group` | |
| Agree two sources | `ReconciliationDesk` | two registers | |
| Read the operation right NOW | `LiveBoard` | `TrendDeepDive` | |
| Move work through states | `LifecycleDesk`, `Board` | a status column | `tpl_board` |
| Take the next item off a queue | `LifecycleDesk` on one stage | a scrolled register | `tpl_pick`, `tpl_allocate` |
| Know what runs out first | `ObligationDesk` | a sort by date | |
| Read cash movements | `Ledger`, `TransactionLedger`, `MoneyBand` | `ChargeLines` | `tpl_money` |
| Read a day's log | `DaySheet` | a date column on the entries | |
| Price a job, line by line | `Worksheet` | `ChargeLines` | |
| Put work on a resource | `ResourceSchedule` | a `Board` | |
| Scan a grid of instruments | `StateMatrix` | `Matrix` | `tpl_pivot` |
| Fill a value per subject and period | `EntryMatrix`, `EntryGrid` | `Matrix` | `tpl_attendance` |
| Reach a person | `PartyRegister`, a `profile` page | a contact fact | |
| Sell a thing from a catalogue | `OfferingRegister`, a `catalogue_item` page | a name register | |
| Scan a body of pictures | `MediaSet`, `CardGrid variant="tile"` | `FileThumbnailGrid` | |
| See what NAMES this record | `RecordRelated`, one short section | a section of folds |  |
| File evidence | `RecordFiles`, `RecordExpectedSet`, the `evidence` drawer | an `Accordion` | |
| Read a period of the business | `TrendDeepDive` | a live board | `tpl_dashboard` |
| Read an answer a machine gave | `ai_patterns.md`'s entries | a register | `tpl_lookup` |

## The shape taxonomy — two families

**An app screen is `[tabs] + list → record`, and that is nearly every app.** A dashboard is the
other family and shares none of it.

### The lifecycle desk

One record type walking ordered stages: an order, a claim, an application, a shipment, a repair.
*"What is stuck, and what do I move next?"* — `LifecycleDesk`.

- **Tabs: the stages**, roughly five; past that the tail is a lens. The strip is a pipeline strip,
  because for a pipeline the ORDER is the subject — and it opens on ALL: the work is the whole
  flow, not its first band.
- **Record: a drawer.**
- **Row vs record:** the row carries what the NEXT act needs — the goods, the money, the clock — so
  the decision is made without opening anything. The record carries the history, the documents and
  the way back.
- **Adapt:** rename the stages; an approval queue is its two-stage degenerate case, not a shape of
  its own.

### The party register

A person or organisation you have a relationship with: a customer, a supplier, a member, a tenant,
a patient. *"Who is this, what is our history, is there a risk?"* — `PartyRegister`.

- **Tabs: usually NONE.** A party has no stages; its segments are filters, and splitting people
  into permanent piles buries the ones the reader did not pick.
- **Record: a PAGE** — a party is arrived at cold, so it must stand up without the list.
- **Row vs record:** identity, ONE reachable contact, what the relationship is WORTH, and the
  single flag that costs money when missed. The record holds the transaction history and the
  interaction log.
- **Adapt:** the worth metrics and the risk flag are the industry-specific half.

### The offering register

What you sell: products, services, plans, a rate card. *"What do we offer, at what price, can I
sell it today?"* — `OfferingRegister`.

- **Tabs: none, or the sales categories** the business already thinks in.
- **Record: a PAGE.** Media, a long description and variants need canvas.
- **Row vs record:** the row is IMAGE-led — a thumbnail in one square slot, then the name with its
  code on the supporting line, the price, and the one availability figure.
- **Adapt:** a services business swaps availability for a rate basis; the image column stays.

### The transaction ledger

Dated movements in a book: bank lines, journal entries, stock movements, metered usage. *"Does this
period reconcile, and what is still unexplained?"* — `TransactionLedger`.

- **Tabs: the BOOKS** — one per source or account. Not the periods: a period is a date-range field
  in the header band, and tabbing it strands every other period behind a bar that grows monthly.
- **Record: a drawer** — a line has little of its own beyond the document that proves it.
- **Row vs record:** date, counterparty, ONE signed amount (never paired in/out columns), its
  classification, and whether its document is attached — absence is the information.
- **Adapt:** the classification vocabulary. **The period's default decides whether the screen opens
  rich or empty** — open on a settled one; a screen opening on its own unfinished work reads broken.

### The monitored-asset set

A population with a live state and a history: stock, machines, vehicles, containers, sensors.
*"What needs attention now, and is that number normal?"* — `MonitoredAssetSet`.

- **Tabs: by RESPONSIBILITY, not by state** — holding, receiving and counting are different jobs
  with different acts. State is what the reader sorts and filters by, so it is a lens.
- **Record: a drawer** onto the unit's recent movements.
- **Row vs record:** the level, the THRESHOLD it is measured against and the derived shortfall — a
  level with no threshold beside it cannot be acted on — plus its trajectory. Scanned for red, a
  population in the hundreds is a status grid and one in the thousands a drill-down.
- **Adapt:** name the two levels the way the trade does. A gross level and an available level are
  never synonyms, and the available one is what a person checks before committing.

### The obligation desk

One row per thing that is OWED, fanned out of the records that owe it: a document cut-off, a permit
renewal, a payment due. *"What runs out first?"* `ObligationDesk`.

- **Tabs: none**, and the order is the answer — soonest first, overdue at the top. **Record: the
  PARENT's**: an obligation is derived and has no row of its own.
- **Row vs record:** what is owed over who owes it, the runway spent, the date, the countdown. An
  obligation with no date does not exist yet, and one whose closing STAMP is filled is done — a
  deadline met and one missed are both past, so the date alone cannot say.
- **Adapt:** the obligations are FIELDS, so the desk grows by a field. A select's options carry no
  date to count down to, so fanning a SET out is a checklist desk, not this one.

### The reconciliation desk

Two sources that should agree: a statement against the ledger, a count against the system, a
remittance against the orders it covers. *"What does not match, and by how much?"*
`ReconciliationDesk`.

- **Tabs: the RUNS**, each a dated session — or none where only one is ever open.
- **Record: a drawer on the PAIR**, not on either side.
- **Row vs record:** a row is a PAIRING carrying both figures and the DERIVED difference. A break
  with a reason or the verdict is accounted for — out of the attention ink and out of the sum —
  and what is left is the shape's own REMAINDER, zero when the desk is finished.
- **Adapt:** the two sources and the reason vocabulary; the arithmetic does not change.

### The guided run

An ordered procedure worked a step at a time: an inspection round, a hand-over. *"What is next?"*
`GuidedRun`.

- **A PAGE, not a register** — no set to narrow, so no strip and no fit budget; N of M and the
  clock ARE its band. One step at large targets, its capture the device its ROLE names.
- **Answering PINS the place**: only the forward press moves the run, and it survives a reload.

### The day sheet

The DAY is the record: a yard report, a shift log. *"What happened on the twelfth?"* `DaySheet`.

- **Rows: every day of the window**, the ones nobody wrote up among them, newest first and never
  past today. **A PAGE** composing that day's logs; an empty day says so, and only a written-up
  one opens or ticks.

### The entry matrix

One value per (subject, period) — a timesheet, a round of readings. *"What is still to fill in?"*
`EntryMatrix`.

- **A drawer on the CELL**: the row is a subject, so nothing is created here.
- **Blank means nothing was DUE**, never zero — in neither edge, and no door.
- **Adapt:** the axis, and whether the cell is the editor.

### The media set

A body of pictures — site shots, scanned papers, damage reports. *"What have we got of this, and
which one is current?"* `MediaSet`.

- **Tiles in RUNS**, headed by the tier they belong to — or by the day, where no tier is bound —
  and each head says how many. **A drawer**, newest run first.
- **Row vs record:** the picture IS the row, the name sits under it, and the line under THAT is
  whichever of the tier and the day the head did not say. One shot per subject is `current`; the
  rest are the chain behind it.
- **Adapt:** the tier. A row with no picture keeps its square — the gap is the information.

### The group register

A set folded by one key. *"Where is it concentrated, and what is behind each figure?"*
`GroupRegister`.

- **Tabs: none**, and **the record is the SET** — a group has none.
- **Row vs record:** the key, its size, each figure folded, the composition above; largest
  first, a period in key order.

### The resource schedule

Work put on a resource, under a ceiling — a despatch board. *"What is this van free for?"*
`ResourceSchedule`.

- **Lanes over the register:** one per resource, so the GAPS show — each named, and what an
  unplaced row's lane cell menus. **A drawer on the block.**
- **The load is the LANE's**, against its ceiling and the SECOND where two are stated; so is
  the overflow. Late is hatched.

### The worksheet

Priced lines still being decided — a quotation, a cost build-up. *"What does this come to?"*
`Worksheet`.

- **The cells ARE the editors**, in the column each figure is read in. **A drawer per line.**
- **Runs are the PARTS of the job**, each footed, the sheet closing under them. The MARGIN
  between the two bases is derived and never typed; so is every foot, from the two SUMS.
- **The cost base leaves with the margin** for the view the customer is shown.

### The arrangements a register offers

A layout is not a shape: the shape says what the screen IS, the layout how its answers are laid
out. The strip, the search, the lenses, the runs, the figures, the ticked set and the door stay
the frame's; `ShapeFrame`'s `body` is where a device takes the rows in place of its table.

**Offered by a value the rows HOLD**, never by a preference: `table` and `list` (`ListRows`) hold
any register; a mark affords `cards` and `gallery` (`CardGrid`); a lifecycle affords `board`
(`Board`, a drop writing that one field); a date affords `calendar` and `timeline`, and a date
with a duration affords `gantt`. The pick is the reader's and survives their reload.

### Dashboard shapes

Both are read-only and visual-first. They differ by the reader's CLOCK; a screen that mixes them
answers neither.

**The live-status board** — the operation's units, right now. *"Is everything OK?"* `LiveBoard`.
**No period control**; "now" has no range. Leads with the WALLBOARD, one chip per unit grouped by
where they stand; the register under it IS the exceptions rail — flagged, then past its bound,
then fine, longest-standing first. One colour per state, at every weight.

**The trend deep-dive** — a period of the business. *"How did it go, and why?"* `TrendDeepDive`.
Leads with the shape of CHANGE, then composition, then the BRIDGE that explains a movement.
**Adapt:** the metrics — each traces to a stored or derived value, and a chart licenses no number
the data cannot produce.

### The record

The door a register row opens — `RecordPage`: rule 6's header, an attention band a section's
`issue` raises, then the sections and the fence. A drawer holds the same.

**One section per data KIND, its body the component that kind names**: the lifecycle
`RecordProgress`; a required set `RecordExpectedSet`; its own rows `RecordChildren`, or `Itinerary`
where they are a trip's stops — each stop leading with its day, a `kind` colouring the spine's
nodes and a `span` drawing a stay once across the days it covers; its files `RecordFiles`,
thumbnails first and a ghost per slot `expected` owes. The rest is `RecordFacts` — which ROLE becomes which is the PLAN's,
`lotics scaffold docs` § Apps and screens. **The ORDER of the sections is what says what this
record is FOR**, so it runs as the job does.

**What is merely ABOUT the record is a section too** — its files, the talk, the registers that NAME
it (`RecordRelated`: a line each with its count, none where it is none) — placed near the end. The
rail beside it takes one item per section with that section's `icon`, following the scroll, and is
mirrored opposite so the column stays centred.

## Composition rules — how a record surface is assembled

For any screen where a record is edited and a primary action produces its output.

1. **Pipeline order.** Data sections run top→bottom as work flows; the OUTPUT section — the act and
   its configuration — comes LAST, never header chrome. The record's OWN acts ride it.
2. **Static shape.** The page's shape is DATA-driven, never output-selection-driven; relevance is a
   callout with a jump: warn, never hide or block.
3. **Colocation.** Every output option lives in the output section beside its action, a per-entity
   selection under its owner's name. Persisted record DATA never does — except a fill editor
   writing that field while a checked output lacks it.
4. **Resolved state.** Controls show the EFFECTIVE state, never raw storage: a derived selection
   renders checked, the first manual change persists the full explicit set, reset-to-auto only
   when explicit.
5. **Decision budget.** Every decision earns its place — derive it, default it, or render it
   conditionally; a placeholder states the honest fallback, never an example that lies. **A status
   is the canonical DERIVED value** — set by hand, it is not one — and **a taken OUTCOME is not a
   completion**: a door states its `verdict`.
6. **Header is identity, ONE figure and how to REACH the subject.** The mark — at the identity
   rung, or MEDIA scale (`hero`) where the thing IS its picture — the name, the `contacts` as one
   row of links, the acts right. No other fact row, no stage badge: a section's own, twice; the
   stage is a progress rung. Several are a `MoneyBand` under it, not a grown header.
7. **A verb goes where its effect lands** (`composition.md`). A committing act takes its own row at
   the section's end beside the blockers gating it, on an empty-label detail row so it lands in the
   CONTROL column.
8. **Destructive placement** — a DECLARED `DangerAction` in the fence.
9. **Create-then-refine.** An add is one click creating a draft edited in place, never fake data.
11. **Optimistic feedback.** Every edit echoes, saves in the background, reverts on error: silent
    success, loud failure, no "saved" chrome.