create-flowdular 0.2.6 → 0.3.0

package/agent-template/docs/design-system.md

@@ -54,10 +54,24 @@ shared primitives, tokens, and the rules for using them.
 13. Destructive actions close a drawer in their own `ui-form__section--danger`:
     one title, one line of consequence, one `Button variant="danger"`. They are
     never mixed into a status row.
-14. Menus (workspace switcher, account menu, session actions) are `ui-menu`
+14. A screen never writes a bare `select.ui-select`, a bare date input, a bare
+    file input, or its own label for any of them: it uses `Select`,
+    `DateField`, `DateRangeField`, `DatePicker`, or `FileUpload`, which own the
+    label association, the invalid state, and the help or error line. The only
+    bare `ui-select` left is the one a primitive renders inside itself (the
+    `Pagination` page size), where the row is the label and the control carries
+    `aria-label`.
+15. Menus (workspace switcher, account menu, session actions) are `ui-menu`
     with `ui-menu__item` rows: 40 px, 10 px inset, the same hover and selected
     background, a 32 px avatar, two lines of text, and the trailing check
     pushed to the right edge.
+16. A surface that opens over the workspace holds the keyboard. `Drawer` and
+    `ConfirmDialog` trap Tab inside the open panel, close on Escape, and return
+    focus to the control that opened them; the screen only names the first
+    field with `autoFocus`, and the panel takes focus when it names none.
+17. A refusal is stated where the reader meets it, never folded into a label.
+    A disabled `TableAction` carries `reason`, and a refused file carries the
+    `FileUpload` refusal line; an action label stays the name of the action.
 
 ## Screen pattern
 
@@ -90,6 +104,45 @@ still use the smaller Flowdular `Table` and `TableCard` contract from
 the TanStack features, row model, header model and cell rendering so every
 screen keeps the same states, widths and actions.
 
+Sorting, narrowing and paging are opt-in on the same `Table`. A column that
+declares `value` (the comparable, searchable value behind the rendered cell) is
+sortable once the table carries `sorting`, and is scanned by `globalFilter`; a
+column without it stays presentation only. Sorting is uncontrolled by default
+and reported through `onSortingChange`; pass `sortingState` as well to keep it
+in the screen's own state. `pagination` takes `pageIndex`, `pageSize` and
+`onPageChange` and slices `rows` client-side; add `totalRows` when `rows`
+already holds one page because the module paginated in SQL. The page window is
+taken over the rows that survive `globalFilter`, so a narrowed set can never
+page into emptiness. The table never moves the page on its own: it clamps the
+index when the row set shrinks under it and reports that through `onPageChange`
+after the render commits, so the reader keeps their place when they sort or
+filter. A screen that wants the first page after a sort or a new search term
+resets the index itself.
+
+A list the module already sorted, narrowed and cut in SQL passes `mode="server"`
+instead. The table then renders `rows` exactly as they arrive and narrows
+nothing: the headers still toggle and report through `onSortingChange`, the page
+still reports through `onPageChange`, and the screen turns both into its next
+request. `pagination.totalRows` stays optional there. With a total the table
+clamps the page index the same way it does client-side; without one the page is
+a keyset page nobody counted, and `pagination.hasMore` says whether another
+follows, so an empty page with nothing behind it walks the reader back one page
+rather than leaving them on a page that does not exist.
+
+A row action that is refused carries `reason` beside `disabled`. The label stays
+the name of the action and the reason becomes the button's accessible
+description, so a reader who cannot see the greyed button still hears why.
+
+The pager is a separate `Pagination` in the `TableCard` `after` slot, so the
+screen holds one page index and size that both the table and the pager read.
+It takes the row total the screen already knows (after its own filtering) and
+a `summary(range)` the screen translates; `pageRange` is exported for a screen
+that needs the same arithmetic elsewhere. Default page size is 25. A keyset
+page passes `hasMore` in place of `totalRows`: Previous behaves the same, Next
+stays open exactly while another page follows, and `summary(page)` reads a
+`keysetPage` with the page index, size and first row but no page count, because
+nobody counted the set.
+
 Every column declares a semantic CSS `width`. Give the primary record and its
 description the largest share, medium shares to dates and identifiers, and the
 smallest share to counts and lifecycle state. In a table with row actions, data
@@ -119,39 +172,130 @@ without settings shows a one-line empty state there.
 
 ## Components
 
-| Component          | Use                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Button`           | Actions: `variant` primary, secondary (default), ghost, danger; `size` sm, md, lg; `block`                                                                                                                                                                                                                                                                                                                                                                                |
-| `FormField`        | Label + control + help or error. Put `ui-input`, `ui-select`, or `ui-textarea` inside                                                                                                                                                                                                                                                                                                                                                                                     |
-| `VariableTextarea` | Multiline template field: `value`, `onInput`, `variables` (scope-filtered `VariableDefinition[]`), `sampleValues`, `label`, `name`; a `braces` menu inserts `{{ key }}` and tokens highlight as pills (error pill when unknown). Presentational, never fetches                                                                                                                                                                                                            |
-| `VariableInput`    | Single-line variant of `VariableTextarea` with the same props                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `VariableSelect`   | Native select that stores either a literal option value or one allowed `{{ key }}` token. Takes scope-filtered `variables`, `sampleValues`, literal `options`, `value`, `onInput`, `name`, `label`, and native required/disabled state. It preserves keyboard, validation, accessibility, and `FormData` semantics and never fetches or resolves data                                                                                                                     |
-| `Tag`              | Status and metadata: `tone` neutral, success, warning, danger, info, ink; `dot` adds a state dot; `mono`                                                                                                                                                                                                                                                                                                                                                                  |
-| `Kpi`              | Stat tile: `label`, `value`, `unit`, `badge`, `note`, `href`, `linkLabel`                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `Chart`            | Token-driven Chart.js wrapper on a client-only canvas: `type` area, bar, line; `data`, `series` (`key`, `label`, `token`), `xKey`, `height`, `title`, `xTickFormatter`; series colors come from `--chart-1..5`; shows an EmptyState for empty or all-zero data                                                                                                                                                                                                            |
-| `Table`            | The one data table, backed by `@octanejs/tanstack-table`: `columns` (`key`, `header`, required `width`, `numeric`, `cell`), `rows`, `rowKey`, `status` idle/loading, `loadingLabel`, `empty` and `emptyFiltered` picked by `filtered`, `actions(row): TableAction[]`, `actionsLabel`, optional stable `actionsWidth` (160 px by default, 280 px for two actions), `onSelect` with `selectedKey`, `caption`; fixed layout and `colgroup` keep columns stable across states |
-| `TableCard`        | The record card around `Table`: `title`, `count`, the `head`, `search`, and `filters` head slots, `before` and `after` around the table, `note` with `noteIcon` as the footer                                                                                                                                                                                                                                                                                             |
-| `PageHeader`       | Every view starts with it: `eyebrow`, `title`, `description`; children render as right-side actions                                                                                                                                                                                                                                                                                                                                                                       |
-| `EmptyState`       | `icon`, `title`, children, optional `code`                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `Alert`            | Inline message: `tone` danger (default), warning, info                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `Drawer`           | Editor panel over the records: `open`, `title`, `subtitle`, `width` md/lg, `onClose`                                                                                                                                                                                                                                                                                                                                                                                      |
-| `SearchField`      | Filter control for a panel head: `value`, `placeholder`, `label`, `onInput`                                                                                                                                                                                                                                                                                                                                                                                               |
-| `CheckGrid`        | Grouped multi-select for scopes, tools, and long option sets: `groups` (`label`, `options` of `value`, `label`, `hint`), `value`, `mono`, `disabled`, `onChange`                                                                                                                                                                                                                                                                                                          |
-| `ScopeSummary`     | Read-only summary of `module.entity.action` scopes: one row per module, one chip per entity with its actions: `scopes`, `labels` (module id to display name)                                                                                                                                                                                                                                                                                                              |
-| `SettingRow`       | One setting: `label`, `description` (node, one line), `scopeLabel` (small neutral tag), `status` (`ok`, `message` of the last save), children as the control cluster                                                                                                                                                                                                                                                                                                      |
-| `Avatar`           | Initials from `name`: `square` for organizations, round for people; `large` in profile and account headers                                                                                                                                                                                                                                                                                                                                                                |
-| `Switch`           | Boolean setting that applies on its own (no form submit): `checked`, `label` as the accessible name, `disabled`, `onChange`                                                                                                                                                                                                                                                                                                                                               |
-| `ConfirmDialog`    | One question before an irreversible action: `open`, `title`, children, `confirmLabel`, `tone` danger (default) or primary, `busy`, `onConfirm`, `onCancel`                                                                                                                                                                                                                                                                                                                |
-| `Icon`             | Stroke icon by `name` from `ICON_PATHS`; `size` 18 default, 16 in controls, 14 in `Button size="sm"`; `strokeWidth` 1.75 default                                                                                                                                                                                                                                                                                                                                          |
-| `BrandMark`        | The weave: `size`, `signature` (copper weft, large brand moments only), `tone` brand, current, inverse                                                                                                                                                                                                                                                                                                                                                                    |
+| Component          | Use                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Button`           | Actions: `variant` primary, secondary (default), ghost, danger; `size` sm, md, lg; `block`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `FormField`        | Label + control + help or error. Put `ui-input`, `ui-select`, or `ui-textarea` inside                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `VariableTextarea` | Multiline template field: `value`, `onInput`, `variables` (scope-filtered `VariableDefinition[]`), `sampleValues`, `label`, `name`; a `braces` menu inserts `{{ key }}` and tokens highlight as pills (error pill when unknown). Presentational, never fetches                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `VariableInput`    | Single-line variant of `VariableTextarea` with the same props                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `VariableSelect`   | Native select that stores either a literal option value or one allowed `{{ key }}` token. Takes scope-filtered `variables`, `sampleValues`, literal `options`, `value`, `onInput`, `name`, `label`, and native required/disabled state. It preserves keyboard, validation, accessibility, and `FormData` semantics and never fetches or resolves data                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `Tag`              | Status and metadata: `tone` neutral, success, warning, danger, info, ink; `dot` adds a state dot; `mono`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `Kpi`              | Stat tile: `label`, `value`, `unit`, `badge`, `note`, `href`, `linkLabel`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `Chart`            | Token-driven Chart.js wrapper on a client-only canvas: `type` area, bar, line; `data`, `series` (`key`, `label`, `token`), `xKey`, `height`, `title`, `xTickFormatter`; series colors come from `--chart-1..5`; shows an EmptyState for empty or all-zero data                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `Table`            | The one data table, backed by `@octanejs/tanstack-table`: `columns` (`key`, `header`, required `width`, `numeric`, `value`, `cell`), `rows`, `rowKey`, `status` idle/loading, `loadingLabel`, `empty` and `emptyFiltered` picked by `filtered`, `sorting` with `sortingState` and `onSortingChange`, `globalFilter`, `pagination`, `mode` client (default) or server, `actions(row): TableAction[]` (`id`, `label`, `icon`, `tone`, `disabled`, `reason`), `actionsLabel`, optional stable `actionsWidth` (160 px by default, 280 px for two actions), `onSelect` with `selectedKey`, `selection` (`selectedKeys`, `onSelectionChange`, `label`, `rowLabel`, `selectable`, `clearLabel`) with `bulkActions: TableBulkAction[]` (`id`, `label`, `icon`, `tone`, `disabled`, `reason`, `onSelect(keys)`) and `selectionSummary(count)`, `caption`; fixed layout and `colgroup` keep columns stable across states. Selection is a leading checkbox column; the header checkbox toggles the rows on screen and reads mixed while some are selected; the bulk bar sits above the table only while something is selected and its clear button empties the whole set through `onSelectionChange`. The screen owns the selected keys and resets them on a page, sort or filter change |
+| `TableCard`        | The record card around `Table`: `title`, `count`, the `head`, `search`, and `filters` head slots, `before` and `after` around the table, `note` with `noteIcon` as the footer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `Pagination`       | The pager for the `TableCard` `after` slot: `pageIndex`, `pageSize`, `totalRows` or `hasMore` for a keyset page nobody counted, `onPageChange`, `pageSizes` with `onPageSizeChange` (the type couples the pair, so one cannot arrive without the other), `label`, `previousLabel`, `nextLabel`, `pageSizeLabel`, and `summary(range)` that the screen translates                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `Select`           | The labelled native select: required `id`, `label`, `options` (`value`, `label`, `disabled`), `value`, `onChange`, `placeholder`, `name` (defaults to `id`), `required`, `disabled`, `autoFocus`, `invalid`, `help`, `error`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `DateField`        | Native date or datetime control: required `id`, `label`, ISO `value`, `onChange`, `kind` date (default) or datetime, `locale`, `min`, `max`, `name`, `required`, `disabled`, `invalid`, `help`, `error`, `describedBy` for a message a group around the field owns; the reading beside the input repeats the value in the reader's locale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `DateRangeField`   | Two `DateField`s with one answer: required `id`, `legend`, `fromLabel`, `toLabel`, `value` (`from`, `to`), `onChange`, `kind`, `locale`, `min`, `max`, `required`, `disabled`, `reversedMessage`, `help`, `error`; each side bounds the other and a reversed range reports instead of swapping                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `DatePicker`       | The calendar picker: required `id`, `label`, `openLabel`, `previousMonthLabel`, `nextMonthLabel`, `value` (`from`, `to`), `onChange`, `mode` single (default) or range, `kind`, `locale`, `min`, `max`, `presets` with `presetsLabel`, `fromLabel` and `toLabel` for a range, `name`, `required`, `disabled`, `autoFocus`, `invalid`, `help`, `error`; one popover holds the presets and the month grid                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `FileUpload`       | The file control: required `id`, `label`, `value`, `onChange`, `refusal(reason, file)`, `chosen(file)`, `clearLabel`, plus `accept`, `maxBytes`, `hint`, `busy` with `busyLabel`, `error`, `name`, `required`, `disabled`, `autoFocus`; it refuses an unaccepted type and a file over `maxBytes` and hands the screen back `null`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `Tabs`             | Accessible tablist: required `id`, `items` (`id`, `label`, `disabled`), `active`, `onChange`, `label`; arrows, Home and End move roving focus, an `active` that names no enabled tab selects the first enabled one, and the caller renders the panel                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `ToastHost`        | Renders the toast queue: `label`, `closeLabel`, optional `store`. Raise toasts with `toasts.success/error/info(message)`; `createToastStore` makes a scoped queue                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `PageHeader`       | Every view starts with it: `eyebrow`, `title`, `description`; children render as right-side actions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `EmptyState`       | `icon`, `title`, children, optional `code`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `Alert`            | Inline message: `tone` danger (default), warning, info                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `Drawer`           | Editor panel over the records: `open`, `title`, `subtitle`, `width` md/lg, `onClose`; traps Tab and restores focus to the opener                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `SearchField`      | Filter control for a panel head: `value`, `placeholder`, `label`, `onInput`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `CheckGrid`        | Grouped multi-select for scopes, tools, and long option sets: `groups` (`label`, `options` of `value`, `label`, `hint`), `value`, `mono`, `disabled`, `onChange`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `ScopeSummary`     | Read-only summary of `module.entity.action` scopes: one row per module, one chip per entity with its actions: `scopes`, `labels` (module id to display name)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `SettingRow`       | One setting: `label`, `description` (node, one line), `scopeLabel` (small neutral tag), `status` (`ok`, `message` of the last save), children as the control cluster                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `Avatar`           | Initials from `name`: `square` for organizations, round for people; `large` in profile and account headers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `Switch`           | Boolean setting that applies on its own (no form submit): `checked`, `label` as the accessible name, `disabled`, `onChange`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `ConfirmDialog`    | One question before an irreversible action: `open`, `title`, children, `confirmLabel`, `tone` danger (default) or primary, `busy`, `onConfirm`, `onCancel`; traps Tab and restores focus to the opener                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `Icon`             | Stroke icon by `name` from `ICON_PATHS`; `size` 18 default, 16 in controls, 14 in `Button size="sm"`; `strokeWidth` 1.75 default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `BrandMark`        | The weave: `size`, `signature` (copper weft, large brand moments only), `tone` brand, current, inverse                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 `Drawer` takes one child, a `ui-drawer__form` (fields in `ui-drawer__body`, actions in `ui-drawer__foot`) or a plain `ui-drawer__body`; it closes on Escape and on the scrim. `SearchField` carries no visible label, so pass `label` as its accessible name. `FormField` renders `error` in place of `help` and marks it `role="alert"`. `SettingRow` is presentation only: the caller owns the draft value, the save call, and passes the result back as `status`. `ScopeSummary` is the read side of `CheckGrid`; both keep the first-seen module order, and `summarizeScopes` is exported for callers that need the grouping without the markup.
 
+`Select`, `DateField` and `DateRangeField` own their own label, so they go
+straight into a form row and not inside a `FormField`. Each requires an `id`:
+it binds the label to the control and keeps the browser's association stable
+across renders, and `name` defaults to it for `FormData`. `invalid` marks the
+control without occupying the message line; `error` does both and replaces
+`help`.
+
+A `DateField` holds the ISO value the platform stores and the form submits
+(`YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` for `kind="datetime"`), because a native
+date input picks its own display format and no page can change it. The reading
+beside the input repeats that value in the reader's locale: pass `locale` from
+`activeLocale()`, and use the exported `formatDateValue` for the same reading
+in a table cell. `DateRangeField` bounds each side by the other, so the picker
+cannot produce a reversed range, and shows `reversedMessage` when one arrives
+from the screen's own state; `dateRangeReversed` is exported for the same check
+before a submit. Its one help or error line describes both inputs through
+`describedBy`, because a fieldset's own `aria-describedby` never reaches the
+controls inside it.
+
+`DatePicker` is the calendar over those same native inputs: the trigger opens
+one popover holding the presets and the month grid, and a range is picked in
+that one calendar, first end then second, ordered on the way out so the picker
+can never make a reversed range. `mode="single"` reads and writes `value.from`
+and mirrors it into `to`, because a single day is a range whose ends match and
+one shape keeps one keyboard model. Arrows move by day and week, PageUp and
+PageDown by month, Home and End to the ends of the week, Enter or Space selects,
+and Escape closes the calendar and stops there, so a picker inside a `Drawer`
+never dismisses the drawer with the same keystroke. The four standard windows
+come from `datePresetRange('today' | 'last-7-days' | 'last-30-days' |
+'this-month')`, which the screen pairs with its own translated labels;
+'this-month' is the month so far. With `kind="datetime"` the calendar answers
+about the day only and keeps the time the value already carried, clamping the
+result into `min` and `max`. Use `DateField` for a plain date a reader types,
+`DateRangeField` for two dates in two labelled fields, and `DatePicker` when the
+reader picks from a calendar or takes a window in one click.
+
+`FileUpload` owns the two refusals a browser cannot state: a content type the
+`accept` list does not cover, and a file over `maxBytes`. It detects them and
+the screen supplies the words through `refusal(reason, file)`, the same way
+every other primitive takes its copy. A refused file is never handed on: the
+control reports `null`, empties the native list so the same file can be chosen
+again, and shows the refusal in place of the reading. It re-reads the file it
+holds whenever the limits change, so a ceiling that arrives after the drawer
+opened still refuses what it must, and the screen keeps one `File | null` and no
+check of its own. The native input stays the focus stop, so the picker opens
+from the keyboard.
+
+`Drawer` and `ConfirmDialog` hold the keyboard while they are open. Tab wraps at
+both ends of the panel, Escape closes, and closing returns focus to the control
+that opened the panel. Focus moves in on open: to the control the screen marked
+`autoFocus` if there is one, otherwise to the first focusable control in the
+panel, otherwise to the panel itself. A drawer whose first field is a `Select`
+marks it `autoFocus`; the screen never moves focus by hand.
+
+`Tabs` renders only the tablist. The caller renders the panel and wires it to
+the tab: the tabs are `<id>-tab-<item.id>` and point at `<id>-panel-<item.id>`,
+so a panel is `<div id={id + '-panel-' + active} role="tabpanel"
+aria-labelledby={id + '-tab-' + active}>`. Arrow keys move focus and selection
+over enabled tabs and wrap, Home and End jump to the ends, and only the active
+tab is in the tab order, so Tab leaves the list for the panel.
+
+`Toast` is a transient confirmation of something the reader just did, never a
+state a screen must keep showing: a failure that blocks work stays in `Alert`.
+A screen that raises toasts renders one `ToastHost`; the region keeps its place
+in the DOM while empty, because a live region added with its first message is
+not announced. `toasts.success`, `.error` and `.info` raise them from anywhere,
+the queue keeps the four newest and dismisses each after five seconds, and
+`createToastStore` makes a scoped queue for a surface or a test. The entry
+animation follows the global reduced-motion rule in `base.css`.
+
+The five states read the same way on every one of these: `Select`, `DateField`,
+`DateRangeField` and `DatePicker` are loading when the screen disables them,
+empty with an empty `value` (and a `placeholder` on `Select`), in error through
+`error` or `invalid`, populated with a value, and denied by not being rendered
+at all. `FileUpload` is loading while `busy`, empty with no `value` and its
+`hint` on the line, in error through `error` or a refusal it made itself,
+populated with the `chosen` reading beside a remove button, and denied the same
+way: the screen does not render it.
+`Table` keeps its own loading row, empty state and filtered-empty message, and
+`Pagination` reads "1 of 1" over an empty set rather than disappearing.
+`ToastHost` has no loading or denied state: it is empty or it carries toasts.
+
 Icon names (`packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog`,
 `user`, `users`, `shield`, `code`, `modules`, `file-text`, `play`, `bot`,
-`flask`, `activity`, `plug`, `search`, `chevron-down`, `chevrons-up-down`,
+`flask`, `activity`, `plug`, `search`, `chevron-down`, `chevron-left`,
+`chevron-right`, `chevrons-up-down`, `sort`, `calendar`,
 `plus`, `panel-left`, `check`, `filter`, `download`, `more`, `external`,
-`alert`, `x`, `sign-out`, `refresh`, `help`, `key`, `settings`, `braces`. An unknown name renders
+`alert`, `x`, `sign-out`, `refresh`, `help`, `info`, `key`, `settings`, `braces`. An unknown name renders
 `modules` without a warning; a new icon is one 24x24 stroke path added there.
 
 ## Classes
@@ -172,8 +316,8 @@ Icon names (`packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog
   with `__section-head` (`b` title, `small` description) and
   `__section--danger`), `ui-control-row` (a growing control beside one fixed
   button), `ui-choices` (a short wrapping row of `ui-checkbox`), `ui-input`
-  (+`--error`), `ui-select`, `ui-textarea` (+`--error`), `ui-checkbox`,
-  `ui-label`, `ui-help` (+`--error`)
+  (+`--error`), `ui-select` (+`--error`), `ui-textarea` (+`--error`),
+  `ui-checkbox`, `ui-label`, `ui-help` (+`--error`)
 - Drawer: `ui-drawer__form` (scrolling body plus pinned footer),
   `ui-drawer__body`, `ui-drawer__foot`
 - Settings rows inside a `ui-card` or a drawer `ui-form__section`, rendered
@@ -183,7 +327,8 @@ Icon names (`packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog
 - Buttons: `ui-btn` with `--primary`, `--secondary`, `--ghost`, `--danger`,
   `--sm`, `--lg`, `--block`, and `--icon` for an icon-only square button
   (the `Button` component renders all but `--icon`)
-- Bits: `ui-kbd`, `ui-dot` (+`--muted`), `ui-note`, `ui-menu` (+`__label`,
+- Bits: `ui-visually-hidden` (text only a screen reader reads), `ui-kbd`,
+  `ui-dot` (+`--muted`), `ui-note`, `ui-menu` (+`__label`,
   `__section` for a static identity or connection block, `__item`,
   `__item--active`, `__item--danger`, `__sep`), `ui-icon`
 
@@ -194,6 +339,15 @@ Rendered by components, not written by hand: `ui-page-head*`, `ui-search`,
 `__note`, `__link`), `ui-avatar` (+`--sq`, `--lg`), `ui-checks` (+`__group`,
 `__head`, `__count`, `__all`, `__items`, `__option`), `ui-scopes` (+`__row`,
 `__chip`), `ui-drawer-slot`, `ui-drawer` (+`__panel`, `__panel--lg`, `__head`,
+`__close`), `ui-table__sort` with `ui-table__sort-icon` (+`--on`, `--asc`),
+`ui-pagination` (+`__summary`, `__size`, `__pages`), `ui-datefield`
+(+`__reading`), `ui-daterange` (+`__row`), `ui-datepicker` (+`__row`,
+`__trigger`, `__scrim`, `__popover`, `__presets`, `__preset`, `__calendar`,
+`__head`, `__month`, `__step`, `__grid`, `__day` (+`--outside`, `--between`,
+`--on`)), `ui-fileupload` (+`__control`, `__input`, `__clear`),
+`ui-table-action` (the wrapper carrying a refused action's title),
+`ui-tabs` (+`__tab`, `__tab--on`),
+`ui-toasts` with `ui-toast` (+`--success`, `--error`, `--info`, `__message`,
 `__close`), `ui-varfield` (+`__control`, `__highlight`, `__input`, `__pill`
 (+`--error`), `__trigger`, `__menu`, `__value`, `__empty`; the overlay layer
 that highlights `{{ key }}` tokens, rendered by `VariableTextarea` and

package/agent-template/docs/getting-started.md

@@ -0,0 +1,118 @@
+# Getting started
+
+Run Flowdular on your machine, seed a demo workspace, and sign in.
+
+## Requirements
+
+- Node.js 22.22.2 or newer
+- pnpm 11.17.0
+- No database server: the platform ships an embedded PostgreSQL and keeps it
+  under `.flowdular/data`
+
+## Install and check the workspace
+
+```bash
+pnpm install
+pnpm flowdular doctor
+```
+
+`doctor` reports workspace health (configuration, enabled modules, generated
+composition, guardrail files). Add `--json` for a machine-readable envelope.
+
+## Seed a local demo
+
+`pnpm flowdular setup` opens an interactive wizard. Choose a local demo, configure PostgreSQL, or check the existing configuration. Local initialization requires confirmation and a stopped application.
+
+For scripts and CI, `setup quick` is a destructive local reset. It prints its full plan first and
+writes only after a typed confirmation:
+
+```bash
+pnpm flowdular setup quick                                     # dry run, prints the plan
+pnpm flowdular setup quick --apply --confirm reset-local-auth  # resets and seeds
+```
+
+Stop `pnpm dev` before applying it. Quick setup is blocked outside development
+and test, and must never point at a deployed database.
+
+It creates two demo tenants (Operations Demo, Finance Demo) and two logins:
+
+| Account             | Password         | Role                       |
+| ------------------- | ---------------- | -------------------------- |
+| `admin@example.com` | `Owner!23456789` | Owner of both demo tenants |
+| `user@example.com`  | `Member!2345678` | Reduced scope member       |
+
+## Run the platform
+
+```bash
+pnpm dev
+```
+
+Open `http://localhost:4310`. Vite HMR covers TSRX, TypeScript and styles. The
+launcher keeps tool warnings quiet; use `pnpm dev -- --verbose` for full
+diagnostics. `pnpm dev` runs `module sync` first, so a composition change is
+picked up without a manual step.
+
+The first visit opens the `auth.core` sign-in flow. The session lives in an
+HttpOnly cookie and carries the scopes of the selected tenant membership. On a
+clean database the sign-up wizard is available: workspace name plus a unique
+workspace id (the first URL segment, `/{workspace}/{view}`), then the
+administrator account, then an optional email confirmation step. A bookmark
+pointing at another workspace you belong to switches the session on load.
+
+`Development` navigation is visible only to tenant owners; server permissions
+stay authoritative either way.
+
+## Where local state lives
+
+The database and the development vault keys live under `.flowdular/data`. Every
+module shares one embedded PostgreSQL in `.flowdular/data/pglite`, which
+`FD_DATABASE_PGLITE_DIRECTORY` can redirect. Point `FD_DATABASE_ADAPTER` at
+`postgresql` and give it `FD_DATABASE_URL` to run against a real server instead.
+See [configuration.md](configuration.md).
+
+## Migrating preserved state from `.octane-erp`
+
+`setup migrate-state` is an isolated compatibility bridge for workspaces that
+still hold state under the old directory:
+
+```bash
+pnpm flowdular setup migrate-state
+# Stop the platform, the sandbox, and anything holding those files open first.
+pnpm flowdular setup migrate-state --apply --confirm migrate-legacy-state
+```
+
+The dry run lists every source, destination and collision. Apply copies the
+vault key files, refuses symbolic links and existing destination files, verifies
+every copied file and never removes the legacy source directory. SQLite database
+files are reported by name and left in place: the PostgreSQL and PGlite adapters
+cannot read them, so start a fresh workspace on the current adapter; that data
+does not carry over.
+
+## Agents in a local workspace
+
+`agents.core` ships enabled: reusable agent definitions, an isolated playground
+and durable run history. Enqueue returns once the run is committed, so execution
+continues across navigation, a closed browser or a sign-out. Agents reach
+platform data only through tools registered against approved API endpoints or
+CLI capabilities. The default local provider is a simulation: it calls no
+external model and no network service, so nothing leaves your machine until you
+bind a real provider under Providers.
+
+## Landing site
+
+The public website lives in [Flowdular/landing](https://github.com/Flowdular/landing): one
+server-rendered page, no session and no module composition, so marketing work
+never reaches the product. The platform serves the workspace itself at `/`.
+
+```bash
+git clone https://github.com/Flowdular/landing.git
+cd landing
+pnpm install
+pnpm dev       # http://127.0.0.1:4330
+```
+
+## Next
+
+- Build a module: [modules.md](modules.md)
+- Build one by chat: [sandbox.md](sandbox.md)
+- Every command: [cli.md](cli.md)

package/agent-template/docs/module-distribution.md

@@ -0,0 +1,96 @@
+# Installing official modules
+
+Core is maintained in [Flowdular/flowdular](https://github.com/Flowdular/flowdular).
+[Flowdular/official-modules](https://github.com/Flowdular/official-modules) owns
+expenses, parties and catalog, including their source, reviews and immutable
+release artifacts. The landing is in [Flowdular/landing](https://github.com/Flowdular/landing).
+
+```sh
+pnpm flowdular module search expenses
+pnpm flowdular module info expenses.core
+pnpm flowdular module install expenses.core@0.6.1
+pnpm flowdular module install expenses.core@0.6.1 --apply
+pnpm flowdular module enable expenses.core --apply
+pnpm flowdular module validate --locked
+```
+
+Without `--apply`, installation and updates return a plan and write nothing.
+Installation downloads source into the first configured module root and writes
+`flowdular.modules.lock.json`. It does not install npm dependencies, run downloaded
+scripts, activate modules, grant scopes or touch a database. Enablement links npm
+packages with install lifecycle scripts disabled, generates composition and runs
+its existing scope-grant flow. Review the source before enabling it.
+
+`module update <id[@version]> [--apply]` requires an installer-managed module and
+refuses local source changes, removed or edited historical migrations, incompatible
+versions and downgrades. Additional source files count as local edits. Generated
+`dist`, `node_modules` and Git metadata do not. `module validate --locked` requires
+a lock and checks source hashes as well as ordinary manifest/dependency validation.
+
+The installer resolves a consistent dependency closure, including diamond
+constraints, within a bounded search budget. Existing workspace/package versions
+are preserved. Registry and runtime validation share semver semantics, including
+pre-1.0 caret ranges. Every module declares `platformApi` as a range
+(`^0.1.0`); the current platform API is `0.1.3` and `module search --compatible`
+filters releases by it. A release that declares `requires` is resolved together
+with the newest compatible release providing each required capability.
+
+## Trust and recovery
+
+The default catalog is the official repository's `registry/index.json`. HTTPS
+artifact URLs must point to the declared immutable commit in that same repository.
+Downloads have time and size limits. Source bundles are bounded JSON records of
+regular files, validated for path escapes, duplicate names, digest mismatches,
+identity, portable dependencies and stale/missing review evidence. No archive
+extraction or install lifecycle scripts execute during source installation.
+
+A checksum does not authenticate an arbitrary publisher. The trust root is the
+configured official repository over HTTPS. An operator can explicitly supply
+`--registry /absolute/path/index.json` for an offline catalog; artifacts must stay
+inside that catalog directory. Third-party remote registries are not supported.
+A review report is an assessment, not a guarantee or a defense against a malicious
+publisher. Official release CI also executes the checks independently.
+
+Concurrent installs share an exclusive transaction directory. Recover an
+interrupted operation with `module recover` and `module recover --apply` after
+its owner process has exited. Recovery restores the previous source and module
+lock and refuses to discard conflicting edits. Keep the transaction directory
+when a conflict is reported. Source recovery never rolls back database migrations.
+Installation and updates are host/operator capabilities and do not expand sandbox
+agents' network, filesystem or tool permissions.
+
+## SDK publication and consumer checks
+
+```sh
+pnpm release:pack
+pnpm release:smoke
+# Also install and test actual source artifacts from the official repo:
+node scripts/smoke-sdk.mjs release-artifacts/sdk /path/to/official-modules/registry/local-index.json
+```
+
+`release-artifacts/sdk/sdk.json` lists exactly `@flowdular/sdk`, `flowdular`, `create-flowdular` and `@flowdular/sandbox`, with versions, tarballs
+and SHA-256 digests. Publish those tarballs with `npm publish <tarball> --access public`.
+Publish all SDK dependencies before consumers install the starter. The three
+business modules and the landing are not in this npm publication set. Keep release
+artifacts outside runtime state directories; creating both `.flowdular` and legacy
+`.coreloom` state would correctly stop the application.
+
+The smoke test creates a separate project and resolves SDK dependencies from
+packed artifacts, without aliases or symlinks into core sources. With a module
+catalog it installs all module source artifacts, enables their source composition,
+checks the lock, typechecks and executes the consumer's tests. Its composition
+check does not grant tenant scopes; auth CLI tests cover that separate boundary.
+
+Sandbox examples use `.ai/references/catalog`, generated from a reviewed official
+artifact. `pnpm reference:check` verifies every file against the pinned provenance
+record. Do not edit the generated reference. To update it, build the CLI and run
+`scripts/module-reference.mjs` with `--artifact`, `--sha256`, `--source-commit` and
+`--apply`. Skills and sandbox preparation refer to that offline snapshot.
+
+`pnpm release:publish` previews the exact publication set after validating every
+artifact digest. The operator can then use `pnpm release:publish --apply` after npm
+authentication. It skips already-published identical tarballs and stops if a
+version exists with different bytes. No npm publication is performed by packing,
+smoke testing or the default publication preview.
+
+The SDK is assembled from private internal workspaces. Import UI from `@flowdular/sdk/ui` and styles from `@flowdular/sdk/ui/styles`; use `@flowdular/sdk/server`, `client`, `contracts` or `modules/<name>` for other surfaces. There is no root SDK barrel, so browser imports do not load server entrypoints. See [npm publication](https://github.com/flowdular/flowdular/blob/main/docs/npm-publication.md).