create-flowdular 0.3.2 → 0.4.1

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

@@ -11,7 +11,9 @@ shared primitives, tokens, and the rules for using them.
   Variable, IBM Plex Mono) are self-hosted through `@fontsource` packages.
 - `packages/client`: the application shell (sidebar, topbar, command palette,
   dashboard, contribution outlets). Shell-only layout lives in
-  `src/shell/shell.css`.
+  `src/shell/shell.css`. Below 1200 px the sidebar starts as its icon rail and
+  below 960 px the context rail as its strip; either opens over the workspace
+  and leaves the stored preference alone (`src/shell/layout.ts`).
 - Modules: compose screens from `@flowdular/sdk/ui`. Module CSS may only add
   module-specific composites built on the tokens (example:
   `modules/agents/src/client/agents.css`).
@@ -35,9 +37,10 @@ shared primitives, tokens, and the rules for using them.
    Numbers in tables and KPIs are tabular (`.num`, `ui-kpi__value`).
 7. Layout containment is owned by the primitives, not by the screen. Children
    of `ui-view`, `ui-two-col`, `ui-grid-2`, and `ui-kpi-grid` are shrinkable
-   tracks, long words wrap, and the workspace never scrolls horizontally. Wide
-   content scrolls inside its own container (`ui-table-wrap`), so one long
-   value can never push the page sideways.
+   tracks, long words wrap (inside a table they end in an ellipsis instead),
+   and the workspace never scrolls horizontally. Wide content scrolls inside
+   its own container (`ui-table-wrap`), so one long value can never push the
+   page sideways.
 8. `Kpi` is a stat tile. Its value is a number or a short state word; addresses,
    identifiers, and paths belong in `note` or a `ui-mono` line.
 9. A screen never splits its width between records and a form. Records own the
@@ -143,13 +146,9 @@ 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
-columns normally add up to about 90 percent; the shared 160 px action column
-uses the rest. In a read-only table, data columns add up to 100 percent. The
-table keeps these widths in loading, empty and populated states and scrolls
-horizontally below its minimum readable width.
+Every column declares a `width` and a cell from the typed cells, and a table
+narrower than its columns hides the least important ones before it scrolls.
+The rules are in the Tables section below.
 
 The drawer holds one `ui-drawer__form`: fields scroll inside
 `ui-drawer__body`, and the primary action stays pinned in `ui-drawer__foot`.
@@ -170,6 +169,77 @@ settings are edited in its Drawer under Administration > Modules, as
 `SettingRow`s inside the drawer's Settings `ui-form__section`; a module
 without settings shows a one-line empty state there.
 
+## Tables
+
+A table reads at any width: a cell never breaks a word, a narrow card hides
+the columns that matter least and lists them under the row, and the table
+scrolls only when even its essential columns do not fit.
+
+**Cells.** A column's `cell` returns one of the typed cells, so every table
+truncates, titles and aligns the same way. Inside `ui-table` text wraps only at
+spaces; a value without one (an email, an id, an action code, a timestamp)
+stays whole and ends in an ellipsis with the full value as its title.
+
+| Cell         | Use                                                                                                                                                                                                                                                                                                                                                        |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CellText`   | One line of text: `value`, `strong` for the record's name, `mono` for a code or a path, `wrap` for prose (a description, a message, a list) that wraps at spaces up to two lines, `muted` for a description in the smaller secondary ink, `title` when the hover should say more than the value                                                            |
+| `CellStack`  | A primary line over a secondary one (a name over its id, a type over its identifier, a state over its note): `primary`, `secondary`, `primaryMono`, `secondaryMono`; a line may be another cell                                                                                                                                                            |
+| `CellTime`   | A timestamp: `value` as an ISO string, a `YYYY-MM-DD` day or epoch milliseconds, `kind` datetime (default) or date, `timeZone` for a value read in a zone of its own (a schedule's). Compact (`16 Sep, 19:39`, the year only when it is not this year), the hour cycle of the locale, a `<time datetime>` with the full timestamp and seconds as its title |
+| `CellCode`   | An identifier in monospace: `value`, `max` (16) past which it keeps its head and tail (`4783b5b2…40d8`), `copy` (true) for the copy button that shows on row hover and focus                                                                                                                                                                               |
+| `CellTag`    | A state or a value with meaning: `label`, `tone`, `dot`, `mono`; the label ends in an ellipsis instead of being cut                                                                                                                                                                                                                                        |
+| `CellNumber` | A count or an amount: `value`, `options` for `Intl.NumberFormat`; a string `value` arrives formatted (`1.2K`, `<$0.01`, `3/5`) and shows as it came; the column declares `numeric` for the right alignment                                                                                                                                                 |
+| `CellMuted`  | The placeholder for a missing value: "None", "Never"; `title` for the hover reading, such as why the value is missing                                                                                                                                                                                                                                      |
+
+**Widths.** `width` stays required. Give a bounded column a px width: a time
+170 px, a status or a tag 120 to 140 px, a number 100 to 140 px, an id or a
+version 120 to 200 px. Give `auto` to the one column that takes the rest,
+usually the record's identity or its description. Percentages still work and
+count as flexible columns.
+
+**Priority.** `TableColumn.priority` is 1 (default), 2 or 3:
+
+- 1: the identity, the state and the main value. Always visible. The first
+  column is always 1.
+- 2: secondary ids, counts and timestamps.
+- 3: details and descriptions.
+
+The table wrapper is a size container, and the table computes from the declared
+widths where each column stops fitting: px columns as declared, 200 px per
+flexible column, the selection and action columns, and 28 px for the expand
+button once something hides, rounded up to a 40 px step between 480 and 1600
+px (`table-steps.css`). Columns hide one at a time, priority 3 before 2 and the
+last declared first; each hides below the width it and every column still
+beside it need. The table scrolls only below its minimum, counted from priority
+1 alone at 120 px per flexible column, plus the selection column, the folded
+action column and the expand button. The container queries decide; the only
+measurement is the action column, which grows to its widest row of buttons so a
+longer translation is never cut.
+
+**Row expansion.** While any column is hidden, every row starts with an expand
+button (`aria-expanded`). An expanded row lists exactly the columns hidden at
+that width as label and value pairs, rendered by the same cells, so nothing is
+lost and nothing is cut. Widening the card brings the columns back and empties
+the list.
+
+**Row actions.** Up to two actions are compact buttons. Two actions fold into
+one More button when the card is narrower than three times the action column
+or than the narrowest table beside it; more than two actions always sit in the
+More menu, and the column then keeps the width of that one button. The menu
+opens over the page, arrows, Home and End move between items, Enter or Space
+runs one, and Escape or Tab closes it and returns focus to the button. A refused
+action stays in the menu, announced as unavailable, with its `reason`.
+
+**Clickable rows.** A table with `onSelect` makes its first cell a button, so
+Tab reaches the row and Enter or Space opens it. That column holds text, never
+a control; a `CellCode` there leaves out its copy button.
+
+**Headers** stay one line and end in an ellipsis with the label as their title.
+
+**Copy and locale.** The expand, collapse, More, copy and copied labels and the
+locale for `CellTime` and `CellNumber` come from `TableLocaleContext`, which the
+shell provides from its own `shell.table.*` bundle. A screen passes none of
+them; outside the shell the English defaults and the host locale apply.
+
 ## Components
 
 | Component          | Use                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
@@ -179,10 +249,11 @@ without settings shows a one-line empty state there.
 | `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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `CellText`         | One of the typed table cells (`CellText`, `CellStack`, `CellTime`, `CellCode`, `CellTag`, `CellNumber`, `CellMuted`); see Tables                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `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 |
+| `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 minimum `actionsWidth` (160 px default, grows to fit its buttons), `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
@@ -191,6 +262,7 @@ without settings shows a one-line empty state there.
 | `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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `SortableList`     | Reorderable list: required `id`, `label`, `items` (`id`, `label`), `onReorder(ids)`, `handleLabel(item)`, `instructions`, `announce(event)`, `renderItem(item, index)`, `disabled`; a grip per item drags with a pointer or picks up, moves and drops from the keyboard, with a polite live region                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -269,6 +341,20 @@ 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.
 
+`SortableList` renders an ordered list whose order the screen owns: it never
+reorders `items` itself and calls `onReorder` once per committed drop with the
+whole new order, never for a cancel or an order that did not change. Each item
+has a grip button named by `handleLabel` and described by `instructions`. From
+the keyboard, Space or Enter picks the item up, ArrowUp and ArrowDown move it,
+Space or Enter drops it, and Escape or moving focus away puts it back; focus
+stays on the moved grip. With a pointer, the grip drags the item, a line marks
+where it lands, releasing commits, and a cancelled pointer or Escape puts it
+back. Every step reaches a polite live region through `announce`, which gets
+the kind (`lifted`, `moved`, `dropped`, `cancelled`), the item label and its
+position of the total, so the screen supplies the words. `disabled` makes every
+grip inert, which is the loading and denied reading; an empty `items` renders an
+empty list, so the screen shows its own empty state instead.
+
 `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
@@ -295,7 +381,7 @@ Icon names (`packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog
 `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`, `info`, `key`, `settings`, `braces`. An unknown name renders
+`alert`, `x`, `sign-out`, `refresh`, `help`, `info`, `key`, `settings`, `braces`, `copy`. An unknown name renders
 `modules` without a warning; a new icon is one 24x24 stroke path added there.
 
 ## Classes
@@ -346,7 +432,20 @@ Rendered by components, not written by hand: `ui-page-head*`, `ui-search`,
 `__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-table__lead` with `ui-table__toggle` and `ui-table__open` (the first cell's
+expand and open buttons), `ui-table__hide-*` (a column hidden below that width),
+`ui-table__reveal-*` (the expand button, details list and detail shown below
+that width), `ui-table--fold-*` (the action fold step),
+`ui-table__placeholder-body` (the loading and empty row content),
+`ui-table__details` (+`-list`), `ui-table__detail`,
+`ui-table-more` (+`--always`), `ui-table-menu` (+`__scrim`, `__label`),
+`ui-cell-text` (+`--strong`, `--mono`, `--muted`, `--wrap`), `ui-cell-stack`
+(+`__primary`, `__secondary`, `__line--mono`), `ui-cell-time`, `ui-cell-code`
+(+`__value`, `__copy`, `__copy--done`), `ui-cell-number`, `ui-cell-muted`,
+`ui-tag__label`,
 `ui-tabs` (+`__tab`, `__tab--on`),
+`ui-sortable` (+`__item`, `__item--lifted`, `__item--dragging`,
+`__item--drop-before`, `__item--drop-after`, `__handle`, `__body`),
 `ui-toasts` with `ui-toast` (+`--success`, `--error`, `--info`, `__message`,
 `__close`), `ui-varfield` (+`__control`, `__highlight`, `__input`, `__pill`
 (+`--error`), `__trigger`, `__menu`, `__value`, `__empty`; the overlay layer

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

@@ -8,8 +8,8 @@ release artifacts. The landing is in [Flowdular/landing](https://github.com/Flow
 ```sh
 pnpm flowdular module search expenses
 pnpm flowdular module info expenses.core
-pnpm flowdular module install expenses.core@0.8.0
-pnpm flowdular module install expenses.core@0.8.0 --apply
+pnpm flowdular module install expenses.core@0.8.1
+pnpm flowdular module install expenses.core@0.8.1 --apply
 pnpm flowdular module enable expenses.core --apply
 pnpm flowdular module validate --locked
 ```
@@ -31,7 +31,7 @@ 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`
+(`^0.1.0`); the current platform API is `PLATFORM_API_VERSION` in `packages/contracts/src/index.ts` 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.
 
@@ -93,4 +93,11 @@ 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 consumer smoke` workflow (`.github/workflows/sdk-release.yml`, job
+`consumer`) runs the pack and the smoke on every pull request and push to main
+that touches `packages`, `modules` or `scripts`. It never publishes: its token
+can only read the repository, and the packed tarballs are kept as an Actions
+artifact only after a merge to main. `pnpm verify` is not repeated there, the
+CI workflow owns it.
+
 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).

package/agent-template/docs/modules.md

@@ -39,6 +39,18 @@ spec instead of scanning the repository. Every section is optional and a
   `agentTools[]`: `id`, `permission`, `description`, `risk`.
 - `outOfScope[]` records what is deliberately not built; `decisions[]` records
   each interview question, its answer and whether a user or a default decided.
+- `research`: `adapter` (`model-native`, `searxng`, `firecrawl`, `connector`
+  or `recorded`),
+  `allowDomains`, `denyDomains`, `monthlyQueryBudget`, and `evidenceOwner`, the
+  entity whose records evidence attaches to through `research.core`.
+- `adapters[]`: `id` (prefixed with the module id), `direction` (`source` or
+  `sink`), `connector` and `operation` (a `connectors.core` definition and
+  operation key), `port` (an import port id for a source, a list export id for a
+  sink), `schedule` (a five-field cron or `null`), `mapping[]` (`from`, `to`,
+  `transform` of `rename`, `constant`, `format` or `lookup`, `value`) and
+  `recorded` (`adapters/<name>.recorded.json`).
+- `templates[]`: `id`, `title`, `inputEntity`, `format` (`pdf` or `docx`) and
+  `body` (`templates/<name>.md`).
 
 Validation is more than the schema: an action permission must exist in
 `permissions`, every `entity` must name an entity, screen `columns` and
@@ -53,6 +65,19 @@ at least one entity (`SPEC_ACTION_PERMISSION_UNKNOWN`, `SPEC_ENTITY_UNKNOWN`,
 `SPEC_DUPLICATE_ID`). A client without a list screen, or a stored entity with no
 tenant-unique field, is a warning.
 
+The three optional sections have checks of their own. `research.evidenceOwner`
+and `templates[].inputEntity` must name an entity (`SPEC_ENTITY_UNKNOWN`). An
+adapter id must start with the module id (`SPEC_ADAPTER_ID_NAMESPACE`); a source
+adapter's `port` must belong to this module or a declared dependency
+(`SPEC_ADAPTER_PORT_UNKNOWN`); `schedule` must be a cron `automations.core`
+accepts: minute, hour, day of month, month and day of week, each `*`, a number,
+a three letter month or weekday name, a list, a range or a step
+(`SPEC_ADAPTER_SCHEDULE_INVALID`); and a mapping needs `from` unless it is a
+`constant` and `value` unless it is a `rename` (`SPEC_ADAPTER_MAPPING_INVALID`).
+`recorded` stays optional here; a sandbox session refuses a live adapter in its
+own `spec-schema` gate (`SANDBOX_LIVE_ADAPTER_REFUSED`, see
+[sandbox.md](sandbox.md)).
+
 ### 2. Scaffold
 
 ```bash
@@ -82,6 +107,15 @@ lifecycle field is set by the service), and the columns of the first `list`
 screen become the table view. Further entities are the implementing agent's
 work.
 
+The optional sections scaffold declarations and fixtures, nothing that runs:
+`src/research.ts` and `research-fixtures.json` (one example query and page in
+the shape the recorded research adapter reads) for `research`; per adapter one
+`src/adapters/<name>.ts` (the id without the module id, dots turned into
+hyphens) and one recorded fixture stub at the declared `recorded` path, else
+`adapters/<name>.recorded.json`; and one `templates/<name>.md` per template
+body, with `templates` added to the package `files`. Implementing them follows the `module-new` and `integration-adapter`
+skills.
+
 Files are written through the workspace Prettier, so the format gate passes
 without a rewrite. A directory that already holds `spec/module.yaml` or
 `translations/**` is extended, not rejected, and a failed run leaves nothing
@@ -119,7 +153,10 @@ pnpm --filter @flowdular/module-<dir> test
 `module validate` checks more than the schema: `platform.server` requires
 `src/platform.ts` and a `./platform` export, `platform.client` requires
 `src/client/index.ts` and a `./client` export, and every declared locale needs a
-`translations/<locale>.json` with the same key set as the others (an error).
+`translations/<locale>.json` with the same key set as the others (an error). A
+plural family such as `count.one`/`count.other` in `en` and
+`count.one`/`count.few`/`count.many`/`count.other` in `pl` counts as one key,
+and each locale must carry the categories its plural rules select.
 `module.json` version drift against `specVersion`, or a locale missing from
 `flowdular.json`, is reported as a warning.
 

package/agent-template/docs/operations.md

@@ -356,6 +356,8 @@ variable falls back to the default and logs one warning about it.
 ## Production checklist
 
 - `pnpm verify` and `pnpm build` pass on the commit being shipped.
+  The container image only builds; it does not run the tests again, so a tag
+  must point at a commit whose CI verify passed.
 - `FD_ENV=production`, `FD_DATABASE_ADAPTER=postgresql`, separate
   `FD_DATABASE_URL` and `FD_DATABASE_MIGRATOR_URL` roles, neither `SUPERUSER`
   nor `BYPASSRLS` on the runtime role.

package/agent-template/docs/sandbox.md

@@ -65,6 +65,79 @@ so a workspace can change them.
 When the work is done, eject it into `modules/` and enable it, or open a pull
 request with the gate evidence attached.
 
+## Sample data and recorded adapters
+
+A session can carry a sample of the data the module will really see: attach a
+CSV, JSON or plain text file (`.csv`, `.json`, `.txt`) to the brief or the
+composer, within the attachment limits (5 MB per file, 10 per session). The file
+stays in the session directory, is never sent to the connected application, and
+is deleted with the session.
+
+Every turn reads the sample through the read-only sandbox tool `sample-data`.
+Without input it lists each sample file with its columns, row count and a
+parsed preview of the first 20 rows; `{ "name": "customers.csv" }` previews one
+file. CSV is parsed with quoted fields and a detected `,`, `;` or tab delimiter,
+JSON from a top-level array or the first array inside an object, text as lines.
+A value is cut at 200 characters and a row at 40 columns; one preview stays
+under 32 KB and the listing under 64 KB, listing a file that does not fit
+without its rows. The BYOK driver offers the tool to the model. The local
+`claude` and `codex` drivers have no tool channel, so the same listing is
+written to `reference/sample-data.json` for the turn.
+
+The backend engineer derives the module's fixtures from the sample:
+`tests/fixtures/*.json` for the tests and `preview/seed.json` for the preview. It
+keeps the shape and replaces real names, contacts and identifiers with invented
+values, because fixtures ship with the module. The role may write `preview/**`,
+`src/preview.ts`, `research-fixtures.json` and `adapters/**`.
+
+### Seeding the preview
+
+When a draft module has both `preview/seed.json` (at most 1 MB) and
+`src/preview.ts` exporting `seed`, the preview calls it once the generation has
+started:
+
+```ts
+export async function seed(context: {
+	readonly tenantId: string; // the preview workspace
+	readonly accountId: string; // the preview account
+	readonly data: unknown; // parsed preview/seed.json
+	readonly databases: DatabaseProvider; // the preview's own provider
+}): Promise<void>;
+```
+
+`seed()` writes through the module's own repository, as the server composition
+does. The sandbox keeps a hash of both files in the session data directory and
+calls `seed()` again only when one of them changes, so it must be idempotent
+(upsert by the natural key). A failure is reported as the preview error of that
+module and never stops the preview. The preview does not seed through an
+`import.ports.v1` port: only `import.core` can read its port registry (the
+public capability registers ports), a port write needs a full principal and a
+job, and most drafts do not compose `import.core`.
+
+### Recorded adapters
+
+A draft spec with a `research` section previews through `research.core`. The
+preview composes it from the platform modules ahead of the drafts and holds
+`research.core.adapter` at `recorded`, the adapter chain at the recorded adapter
+alone (`searchOrder` at `recorded` with `recordedEnabled` on, `fetchOrder` at
+`direct`) and `research.core.recordedFixturesPath` at the absolute path of the
+module's `research-fixtures.json` for every workspace. A chain holding the
+recorded adapter reads pages from the same file before it looks at the fetch
+order, so nothing reaches the network. Changing any of them answers
+`409 SANDBOX_LIVE_ADAPTER_REFUSED`. When several drafts declare research, the
+first one in session order supplies the path. An entry of the spec's `adapters`
+section reads the fixture its `recorded` field names, by convention
+`adapters/<id>.recorded.json`.
+
+A session declares only recorded adapters; an owner connects a live search or
+connector instance after delivery. When a draft spec sets `research.adapter` to
+`model-native`, `searxng`, `firecrawl` or `connector`, or lists an adapter
+without `recorded`, the `spec-schema` gate fails with
+`SANDBOX_LIVE_ADAPTER_REFUSED` and names the file and field, so the turn goes
+back to its specialist and delivery stops. The preview refuses to compose such a
+session with the same code before a worker starts. A `research` section without
+`adapter` is previewed on the recorded fixtures.
+
 ## Deliver as a pull request
 
 The eject route (`POST /sandbox/api/sessions/:id/eject`) takes `target:
@@ -81,7 +154,9 @@ request time (`delivery/configuration.ts`): `targets`, `default`,
 `maxChangedFiles` and `git` with `remote`
 (`origin`), `repository` (`owner/name`, derived from the remote when null),
 `baseBranch` (`main`), `branchPrefix` (`sandbox`), `provider` (`github` or
-`none`), `mode` (`auto`, `direct` or `fork`), `forkOwner` and `reviewers`.
+`none`), `mode` (`auto`, `direct` or `fork`), `forkOwner`, `reviewers` and
+`labels` (added to the pull request after creation, default
+`sandbox-delivery`; a label the repository lacks never fails a delivery).
 
 Operator settings live in the sandbox configuration
 (`.flowdular/sandbox/config.json`, `GitHubDeliveryConfiguration` in

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-flowdular",
-	"version": "0.3.2",
+	"version": "0.4.1",
 	"type": "module",
 	"description": "Scaffold a Flowdular application: the platform, one example module and the secrets a fresh install needs.",
 	"license": "MIT",

package/template/default/flowdular.json

@@ -12,6 +12,7 @@
 			"system.core",
 			"auth.core",
 			"access.core",
+			"adapters.core",
 			"reports.core",
 			"metering.core",
 			"agents.core",
@@ -26,6 +27,7 @@
 			"import.core",
 			"notifications.core",
 			"profile.core",
+			"research.core",
 			"sandbox.core",
 			"search.core",
 			"users.core",

package/template/default/modules/example/package.json

@@ -16,7 +16,7 @@
 	"dependencies": {
 		"octane": "0.1.51",
 		"segment-state": "0.2.1",
-		"@flowdular/sdk": "0.3.2"
+		"@flowdular/sdk": "0.4.1"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",

package/template/default/modules/example/src/client/NotesView.tsrx

@@ -2,6 +2,9 @@ import { useEffect, useMemo } from 'octane';
 import {
 	Alert,
 	Button,
+	CellStack,
+	CellText,
+	CellTime,
 	Drawer,
 	FormField,
 	Icon,
@@ -31,20 +34,18 @@ function columns(): readonly TableColumn<Note>[] {
 		{
 			key: 'note',
 			header: t('example.table.column.note'),
-			width: '70%',
-			cell: (note) => <span class="ui-cell">
-				<b>{note.title}</b>
-				<span class="ui-cell__muted">{note.body}</span>
-			</span>,
+			width: 'auto',
+			cell: (note) =>
+				<CellStack
+					primary={note.title}
+					secondary={<CellText value={note.body} muted />}
+				/>,
 		},
 		{
 			key: 'created',
 			header: t('example.table.column.created'),
-			width: '30%',
-			cell: (note) => new Intl.DateTimeFormat(activeLocale(), {
-				dateStyle: 'medium',
-				timeStyle: 'short',
-			}).format(new Date(note.createdAt)),
+			width: '170px',
+			cell: (note) => <CellTime value={note.createdAt} />,
 		},
 	];
 }
@@ -152,12 +153,7 @@ export function NotesView(props: NotesViewProps) @{
 		}
 		<TableCard
 			title={t('example.table.title')}
-			count={t(
-				notes.length === 1
-					? 'example.table.count.one'
-					: 'example.table.count.other',
-				{ count: notes.length },
-			)}
+			count={t('example.table.count', { count: notes.length })}
 			search={<SearchField
 				value={query}
 				placeholder={t('example.table.search.placeholder')}

package/template/default/modules/example/tests/module.test.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
+import { translationKeys } from '@flowdular/sdk/contracts';
 import manifest from '../module.json' with { type: 'json' };
 import translationsEn from '../translations/en.json' with { type: 'json' };
 import translationsPl from '../translations/pl.json' with { type: 'json' };
@@ -28,8 +29,8 @@ describe('example.core manifest', () => {
 
 describe('example.core translations', () => {
 	it('ships the same key set in every declared locale', () => {
-		expect(Object.keys(translationsPl).sort()).toEqual(
-			Object.keys(translationsEn).sort(),
+		expect(translationKeys(translationsPl)).toEqual(
+			translationKeys(translationsEn),
 		);
 		expect(manifest.locales).toEqual(['en', 'pl']);
 	});

package/template/default/modules/example/translations/pl.json

@@ -9,7 +9,9 @@
 	"page.action.new": "Nowa notatka",
 	"table.title": "Notatki",
 	"table.count.one": "{count} notatka",
-	"table.count.other": "{count} notatek",
+	"table.count.few": "{count} notatki",
+	"table.count.many": "{count} notatek",
+	"table.count.other": "{count} notatki",
 	"table.column.note": "Notatka",
 	"table.column.created": "Utworzono",
 	"table.search.placeholder": "Szukaj notatek",

package/template/default/package.json

@@ -25,7 +25,7 @@
 	"devDependencies": {
 		"@tsrx/prettier-plugin": "0.3.120",
 		"prettier": "3.6.2",
-		"flowdular": "0.3.2",
+		"flowdular": "0.4.1",
 		"rulesync": "16.21.0"
 	}
 }

package/template/default/platform/package.json

@@ -15,7 +15,7 @@
 		"@octanejs/vite-plugin": "0.1.51",
 		"octane": "0.1.51",
 		"pg": "8.23.0",
-		"@flowdular/sdk": "0.3.2"
+		"@flowdular/sdk": "0.4.1"
 	},
 	"devDependencies": {
 		"@octanejs/app-core": "0.0.47",

package/template/default/platform/scripts/dev.mjs

@@ -10,6 +10,14 @@ import {
 } from '@flowdular/sdk/dev-console';
 
 const appRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
+/* `pnpm dev -- --port 4396 --host 0.0.0.0` overrides vite.config.ts, so a
+   second application runs beside the first one. */
+const flag = (name) => {
+	const index = process.argv.indexOf(name);
+	return index === -1 ? undefined : process.argv[index + 1];
+};
+const port = Number(flag('--port'));
+const host = flag('--host');
 const verbose =
 	process.argv.includes('--verbose') ||
 	process.argv.includes('-v') ||
@@ -24,6 +32,11 @@ try {
 		configFile: resolve(appRoot, 'vite.config.ts'),
 		customLogger: createOctaneLogger(verbose, color),
 		clearScreen: false,
+		...(Number.isInteger(port) && port > 0
+			? { server: { port, strictPort: true, ...(host ? { host } : {}) } }
+			: host
+				? { server: { host } }
+				: {}),
 	});
 	await server.listen();
 } catch (error) {
@@ -37,7 +50,9 @@ printReady({
 	lines: [
 		[
 			'local',
-			server.resolvedUrls?.local?.[0] ?? 'http://localhost:4310/',
+			server.resolvedUrls?.local?.[0] ??
+				server.resolvedUrls?.network?.[0] ??
+				'the address vite.config.ts sets',
 			'info',
 		],
 		['diagnostics', verbose ? 'verbose' : 'quiet · use --verbose', 'muted'],