@flowdular/sdk 0.2.4 → 0.3.1

package/.ai/skills/spec-interview/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: spec-interview
+description: >-
+  Turn a business request into a schema-valid v2 module specification by
+  proposing a platform default for every decision and asking only what cannot be
+  inferred, so implementation never has to guess or scan the repository.
+roles:
+  - business-manager
+  - spec-author
+  - module-executor
+when: A request describes a module or a change and no approved specification covers it.
+---
+
+# Interview a request into a specification
+
+The specification is the contract implementation reads instead of the repository. Everything an engineer would otherwise have to guess belongs in it: entities, fields, screens, actions, settings, tools, and what was deliberately left out. A missing decision costs a round trip later, so surface it now.
+
+Work closed-world. `.ai/platform-capabilities.md` is the complete list of what the platform can deliver. Anything outside it is `outOfScope` with the business decision that replaces it, never a promise.
+
+## 1. Read exactly this
+
+1. `.ai/platform-capabilities.md`, the capability card (in a session: `reference/platform-capabilities.md`).
+2. `packages/contracts/schemas/module-spec.schema.json`, the shape and the enums (in a session: `reference/packages/contracts/schemas/module-spec.schema.json`).
+3. `.ai/references/catalog/spec/module.yaml`, a written example (in a session: `reference/example-module/spec/module.yaml`).
+
+For an edit, also read the module's current `spec/module.yaml` and write the smallest delta. Do not open `modules/` or `packages/` for anything else; the card carries what you need, and a fact it lacks is a question, not a search.
+
+## 2. Decision checklist
+
+One pass, in this order. For each row, write the default from the card into the spec and record it as a `decisions[]` entry with `decidedBy: default`. Ask only where the answer is a business fact that no default can supply.
+
+| Decision               | Default to propose                                                                          | Lands in                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Actors                 | Owner manages, member reads                                                                 | `permissions`, `invariants`              |
+| Entities and fields    | One primary entity; `name` required, `maxLength` 120; no field the request did not name     | `entities[]`                             |
+| Uniqueness             | The human-facing code is `unique: tenant`; everything else `none`                           | `entities[].fields[].unique`             |
+| States and transitions | `active` and `archived`, every transition behind the manage permission                      | `entities[].states`                      |
+| Who sees what          | Both permissions in the same navigation entry; the manage action hidden without the scope   | `permissions`, `screens[]`, `invariants` |
+| What is denied         | Unauthenticated 401, missing permission 403, cross-tenant read returns nothing              | `acceptanceScenarios`                    |
+| Failure behaviour      | A duplicate returns a stable conflict and changes nothing; bounds return 400                | `invariants`, `acceptanceScenarios`      |
+| Cross-module reads     | None. A read of another module goes through its public capability and a declared dependency | `dependencies`, `dataOwnership`          |
+| Screens                | One `list` screen with the entity's identifying columns                                     | `screens[]`                              |
+| Widgets                | None. A count belongs on `dashboard.metrics` only when the request asks for it              | `widgets[]`                              |
+| Settings               | None. A number the business may change later is `scope: tenant` with a stated default       | `settings[]`                             |
+| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`            | `agentTools[]`                           |
+| Reports                | None. There is no export, no PDF and no search; a report is a screen or it is out of scope  | `outOfScope[]`                           |
+| Out of scope           | Every item from the card's gap list the request touched, each with its business decision    | `outOfScope[]`, `decisions[]`            |
+
+A default you propose is still a decision: it goes into `decisions[]` so the operator can see and overturn it, and so the next agent never re-derives it.
+
+## 3. Ask only what you cannot infer
+
+Ask when the answer is a business fact: who may see a price, whether a code is unique across the company or per branch, what happens to an order whose customer is deleted. Never ask what the card already answers, and never ask two questions where one choice settles both. Keep it under about six questions per turn.
+
+In the sandbox, end the reply with exactly one fenced block tagged `questions`, nothing after it:
+
+````text
+```questions
+{
+	"questions": [
+		{
+			"id": "Q-1",
+			"question": "Is the item code unique for the whole workspace or per warehouse?",
+			"options": ["Unique per workspace", "Unique per warehouse"],
+			"recommended": "Unique per workspace",
+			"allowFreeText": true
+		}
+	]
+}
+```
+````
+
+The sandbox renders it as a form and the answers return in the next turn as a `Decisions` section. Outside the sandbox: in Claude Code ask through the question tool with the same options, and in Codex ask in plain text with the options numbered. In every host, `recommended` is the default from the card, and an unanswered question stays a question, never a guess.
+
+When the answers come back, copy each one into `decisions[]` with `decidedBy: user` and the answer text, and update whatever the answer changed.
+
+## 4. Write the specification
+
+`modules/<dir>/spec/module.yaml`, `schemaVersion: 2`, `status: draft`. Keep the v1 keys (`id`, `specVersion`, `name`, `description`, `profile`, `capabilities`, `dependencies`, `tenancy`, `locales`, `invariants`, `permissions`, `dataOwnership`, `acceptanceScenarios`) and add the v2 arrays:
+
+- `entities[]`: `{ id, name, fields[], states? }`. A field is `{ id, type, required?, unique?, maxLength?, values?, reference?, description? }`. `type` is one of `string`, `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `enum`, `reference`, `json`; `unique` is `tenant` or `none`. `enum` needs `values`, `reference` needs `reference`. Entity and screen ids are `^[a-z][a-z0-9-]*$`; field and setting keys are `^[a-z][a-zA-Z0-9]*$`. Money is `integer` minor units plus an explicit currency field, never `decimal`.
+- `screens[]`: `{ id, kind: list|record|form|dashboard, entity?, title?, columns?, filters?, navigationGroup? }`. `navigationGroup` is one of the six values on the card.
+- `actions[]`: `{ id, entity?, permission, kind: create|update|delete|custom, risk, idempotent, description }`. `risk: external` is refused by the platform, so an action may not declare it.
+- `widgets[]`: `{ id, slot, entity?, description }`; `slot` is one of the four workspace slots.
+- `settings[]`: `{ key, type: string|integer|boolean|enum, scope: tenant|platform, default?, values?, description }`.
+- `agentTools[]`: `{ id, permission, description, risk: read|workspace-write }`.
+- `outOfScope[]`: plain sentences, each naming the gap and the decision taken instead.
+- `decisions[]`: `{ id, question, answer, decidedBy: user|default }`; ids match `^[A-Z][A-Z0-9-]+$`, for example `D-UNIQUE-SKU`.
+
+Put the primary entity's read and manage permissions first: the scaffold builds that entity and later permissions become constants only. Every `acceptanceScenarios[]` entry stays observable (given, when, then) and covers success, denial and the cross-tenant case, because each one becomes at least one test. The schema rejects unknown keys.
+
+## 5. Validate
+
+```bash
+pnpm flowdular spec validate --all --json
+```
+
+In the sandbox this is the `spec-schema` gate and runs for you. Fix every issue before ending the turn; a spec that does not validate cannot be approved.
+
+## 6. Close the turn
+
+End with the decision list: each decision, the answer, and whether it came from the user or from a platform default. Then state plainly that implementation cannot start until the operator approves this exact specification, and that any later edit invalidates that approval. In the sandbox the operator approves the exact hash; on a host, approval is recorded only through `spec-approval` after an explicit user instruction.
+
+Sandbox handoff: `HANDOFF: none - <the open questions>` while questions are outstanding, otherwise the next specialist with the reason.
+
+## Refusals
+
+- Never write `status: approved`, and never claim a spec is approved. Approval is the operator's act.
+- Never write TypeScript, `module.json`, `package.json` or any implementation file. This skill produces `spec/module.yaml` and, where the role allows, `translations/**`.
+- Never invent a business fact. An unanswered question is `decisions[]` left open plus a question, not a plausible answer.
+- Never promise a capability the card lists as missing. It goes to `outOfScope[]`.
+
+## Pitfalls
+
+- A field nobody asked for is a cost forever. If the request did not name it, leave it out and record the omission.
+- `unique: tenant` without a stated conflict behaviour produces an undefined error path; pair it with an acceptance scenario.
+- `states` without `transitions` lets any state reach any other. Name the legal moves and their permission.
+- A screen with no `columns` gives the engineer nothing to build; list the identifying fields in display order.
+- An `enum` field with values that are really a lookup table wants its own entity instead.
+- Bumping `specVersion` is part of an edit, not an afterthought; the delivery gate compares it.

package/.ai/skills/test-hardening/SKILL.md

@@ -9,6 +9,7 @@ roles:
   - frontend-engineer
   - reviewer
   - module-executor
+  - agentic-engineer
 when: A module has few or tautological tests, a bug escaped the suite, or a reviewer asks whether the tests guard the change.
 ---
 

package/.ai/skills/ux-design/SKILL.md

@@ -65,8 +65,17 @@ Read-only master-detail (runs, playground) keeps `ui-two-col` (+ `--wide-aside`)
 - `Button`: `variant` primary, secondary (default), ghost, danger; `size` sm, md, lg; `type` button, submit; `block`; `disabled`; `onClick`.
 - `FormField`: `label`, `required`, `help`, `error`; one control child with `ui-input`, `ui-select` or `ui-textarea`.
 - `SearchField`: `value`, `placeholder`, `label` (accessible name), `onInput(value)`.
-- `Table`: `columns: TableColumn<Row>[]` (`key`, `header`, required `width`, `cell(row)`, `numeric`), `rows`, `rowKey(row)`, `status`, `loadingLabel`, `empty`, `emptyFiltered`, `filtered`, `actions(row): TableAction[]`, `actionsLabel`, optional stable `actionsWidth` (160 px default, 280 px for two actions), `onSelect(row)`, `selectedKey`, `caption`.
+- `Table`: `columns: TableColumn<Row>[]` (`key`, `header`, required `width`, `cell(row)`, `numeric`, `value(row)` for the comparable and searchable value behind the cell), `rows`, `rowKey(row)`, `status`, `loadingLabel`, `empty`, `emptyFiltered`, `filtered`, `sorting` with `sortingState` and `onSortingChange`, `globalFilter`, `pagination` (`pageIndex`, `pageSize`, `onPageChange`, `totalRows` when the module paged in SQL), `actions(row): TableAction[]`, `actionsLabel`, optional stable `actionsWidth` (160 px default, 280 px for two actions), `onSelect(row)`, `selectedKey`, `caption`. Only a column with `value` is sortable and searched. Multi-row selection: `selection` (`selectedKeys: ReadonlySet<string>`, `onSelectionChange(keys)`, `label` of the header checkbox, `rowLabel(row)`, optional `selectable(row)` and `clearLabel`) adds a leading checkbox column whose header toggles the rows on screen; `bulkActions: TableBulkAction[]` (`id`, `label`, `icon`, `tone`, `disabled`, `reason`, `onSelect(keys)`) render in the bar above the table while something is selected, and `selectionSummary(count)` translates "N selected". The screen keeps the keys in its own state and resets them on a page, sort or filter change; the header checkbox touches only the rows on screen, while the clear button empties the whole set through `onSelectionChange`.
 - `TableCard`: every `Table` prop plus `title`, `count`, `head`, `search`, `filters`, `before`, `after`, `note`, `noteIcon`.
+- `Pagination`: the pager for the `TableCard` `after` slot: `pageIndex`, `pageSize`, `totalRows` (after the screen's own filtering), `onPageChange(pageIndex)`, `pageSizes` with `onPageSizeChange(pageSize)` (both or neither), `label`, `previousLabel`, `nextLabel`, `pageSizeLabel`, `summary(range)` that the screen translates. It reads "1 of 1" over an empty set, so it is rendered unconditionally.
+- `Select`: the labelled native select: required `id`, `label`, `options` (`value`, `label`, `disabled`), `value`, `onChange(value)`, `placeholder`, `name` (defaults to `id`), `required`, `disabled`, `invalid`, `help`, `error`.
+- `DateField`: required `id`, `label`, ISO `value` (`YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` for `kind="datetime"`), `onChange(value)`, `kind`, `locale` from `activeLocale()`, `min`, `max`, `name`, `required`, `disabled`, `invalid`, `help`, `error`, `describedBy` for a message a group around it owns. The reading beside the input repeats the value in the reader's locale.
+- `DateRangeField`: required `id`, `legend`, `fromLabel`, `toLabel`, `value` (`from`, `to`), `onChange(value)`, `kind`, `locale`, `min`, `max`, `required`, `disabled`, `reversedMessage`, `help`, `error`; each side bounds the other and a reversed range is reported, never swapped.
+- `Tabs`: required `id`, `items` (`id`, `label`, `disabled`), `active`, `onChange(id)`, `label`; it renders only the tablist, and the caller renders `<id>-panel-<active>` labelled by `<id>-tab-<active>`.
+- `ToastHost`: `label`, `closeLabel`, optional `store`. One per screen that raises toasts, rendered even while empty; `toasts.success`, `.error` and `.info` raise them and `createToastStore` makes a scoped queue.
+
+`Select`, `DateField` and `DateRangeField` own their label, so they go straight into a `ui-form__row` and never inside a `FormField`.
+
 - `Filters`: `open`, `onToggle`, `activeCount`, `label`; children are the filter controls, which belong in the dropdown and nowhere else.
 - `CheckGrid`: `groups: { label, options: { value, label, hint? }[] }[]`, `value: string[]`, `mono`, `disabled`, `onChange(next)`.
 - `Drawer`: `open`, `title`, `subtitle`, `width` md or lg, `onClose`; child is `ui-drawer__form` or `ui-drawer__body`. Escape and the scrim close it.
@@ -79,16 +88,38 @@ Read-only master-detail (runs, playground) keeps `ui-two-col` (+ `--wide-aside`)
 - `Icon`: `name`, `size` (18 default, 16 in controls, 14 in `Button size="sm"`), `strokeWidth`.
 - `BrandMark`: `size`, `signature`, `tone`; brand moments only.
 
-Icon keys (`ICON_PATHS`, `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`, `plus`, `panel-left`, `check`, `filter`, `download`, `more`, `external`, `alert`, `x`, `sign-out`, `refresh`, `help`, `key`, `settings`, `braces`. An unknown name renders `modules` silently, so check the list.
+Icon keys (`ICON_PATHS`, `packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog`, `user`, `users`, `shield`, `code`, `modules`, `file-text`, `play`, `bot`, `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 `modules` silently, so check the list.
 
 ## 5. Classes a module writes by hand (`packages/ui/src/styles/components.css`)
 
-Layout `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`, `ui-kpi-grid`, `ui-tag-cloud`, `ui-section-head` (h2 plus actions inside a view), `ui-toolbar` (+`__spacer`). Surfaces `ui-card` (+`__head`, `__title`, `__body`). Data `ui-table` (+`ui-table-wrap`, `ui-table__empty`, `ui-table__state` for a dot plus label, `.num`), `ui-cell` (+`ui-cell__muted`), `ui-mono`, `ui-code`, `ui-dot` (+`--muted`). Row action classes are component-owned and are never written by a module. Forms `ui-form` (+`__row`, `__row--4`, `__foot`, `__actions`), `ui-input` (+`--error`), `ui-select`, `ui-textarea` (+`--error`), `ui-checkbox`, `ui-label`, `ui-help` (+`--error`). Drawer `ui-drawer__form`, `ui-drawer__body`, `ui-drawer__foot`. Bits `ui-kbd`, `ui-note`, `ui-menu` (+`__label`, `__item`, `__item--active`, `__item--danger`, `__sep`), `ui-btn ui-btn--icon` for an icon-only button. Classes rendered by components (`ui-drawer__panel`, `ui-search`, `ui-page-head*`, `ui-field`, `ui-empty*`, `ui-alert*`, `ui-tag*`, `ui-kpi__*`, `ui-checks*`, `ui-avatar*`) are not written by hand.
+Layout `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`, `ui-kpi-grid`, `ui-tag-cloud`, `ui-section-head` (h2 plus actions inside a view), `ui-toolbar` (+`__spacer`). Surfaces `ui-card` (+`__head`, `__title`, `__body`). Data `ui-table` (+`ui-table-wrap`, `ui-table__empty`, `ui-table__state` for a dot plus label, `.num`), `ui-cell` (+`ui-cell__muted`), `ui-mono`, `ui-code`, `ui-dot` (+`--muted`). Row action classes are component-owned and are never written by a module. Forms `ui-form` (+`__row`, `__row--4`, `__foot`, `__actions`), `ui-input` (+`--error`), `ui-select`, `ui-textarea` (+`--error`), `ui-checkbox`, `ui-label`, `ui-help` (+`--error`). Drawer `ui-drawer__form`, `ui-drawer__body`, `ui-drawer__foot`. Bits `ui-kbd`, `ui-note`, `ui-menu` (+`__label`, `__item`, `__item--active`, `__item--danger`, `__sep`), `ui-btn ui-btn--icon` for an icon-only button. Classes rendered by components (`ui-drawer__panel`, `ui-search`, `ui-page-head*`, `ui-field`, `ui-empty*`, `ui-alert*`, `ui-tag*`, `ui-kpi__*`, `ui-checks*`, `ui-avatar*`, `ui-table__sort`, `ui-pagination` (+`__summary`, `__size`, `__pages`), `ui-datefield` (+`__reading`), `ui-daterange` (+`__row`), `ui-tabs` (+`__tab`), `ui-toasts` with `ui-toast`) are not written by hand.
 
 ## 6. Copy
 
 User-facing copy lives in every declared `translations/*.json` bundle and is read with fully qualified `t()` keys. Eyebrow names the domain, title names the records, and description is one sentence. Table headers say what the value is. Buttons start with a verb. Loading text ends with `…`. Drawer footer states the constraint the user cannot see. Write natural copy in each locale, with no exclamation marks or database jargon.
 
+## 7. Inspect the rendered screen
+
+A screen is not finished until it has been looked at. Typecheck and tests say nothing about overflow, alignment, a duplicate label or a column that collapses.
+
+Where to look:
+
+- Repository root: `pnpm dev`, then `http://localhost:4310`. `pnpm flowdular setup quick --apply --confirm reset-local-auth` (stop `pnpm dev` first; local only) seeds two demo tenants and two logins: `admin@example.com` / `Owner!23456789` owns both tenants, `user@example.com` / `Member!2345678` is a reduced-scope member. Navigate to the entry's navigation group and open the view.
+- Sandbox: the session preview panel renders the draft module. Use it; a specialist has no shell and no dev server.
+- No browser at hand: a headless Chrome screenshot (`--headless --window-size=1440,900 --screenshot=<file>`) captures what a fresh, signed-out session sees, which covers sign-in and public pages only. A protected screen needs a real session, so drive it with whatever browser automation the host offers rather than a bare screenshot flag.
+
+Record one piece of evidence per state before handing off. A state you could not reach is stated as such, not assumed:
+
+| State     | How to reach it                                                       | What to check                                                                         |
+| --------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Loading   | First paint before the fetch resolves, or a throttled network profile | Column widths match the populated table, the head does not jump, a refresh keeps rows |
+| Empty     | A tenant with no records                                              | The icon renders, the sentence names the first action, `emptyFiltered` differs        |
+| Error     | Make the request fail (sign out in a second tab, or drop the scope)   | `Alert` under the header, no blank screen, no raw stack or SQL in the message         |
+| Populated | Several real records, including the longest realistic value           | No horizontal page scroll, identifiers in `ui-mono`, numbers tabular, actions aligned |
+| Denied    | Sign in as `user@example.com`                                         | The manage action is absent, navigation is hidden, a forced request still returns 403 |
+
+Check the drawer form in the same pass: one label per field, fields top-aligned, the footer constraint visible, the submit button disabled while busy.
+
 ## Pitfalls
 
 - `Kpi value={items.length}` does not typecheck; use `String(items.length)`.

package/.ai/skills/variables/SKILL.md

@@ -5,9 +5,7 @@ description: >-
   mask, and server-side resolution, with agents.core as the worked example.
 roles:
   - frontend-engineer
-  - ux-designer
   - agentic-engineer
-  - backend-engineer
   - module-executor
 when: A field must let a value embed {{ variable }} tokens filled from other fields, the request context, or another module.
 ---

package/.ai/skills/workflow-development/SKILL.md

@@ -6,7 +6,6 @@ description: >-
   audit boundaries.
 roles:
   - agentic-engineer
-  - backend-engineer
   - frontend-engineer
   - module-executor
 when: A brief asks for a workflow, pipeline, canvas node, workflow action, or a module feature that starts a workflow.

package/AGENTS.md

@@ -54,6 +54,10 @@ Do not load the whole skill catalog into the task context.
 12. Keep handoffs short and factual. No AI attribution footers or em/en dashes.
     Sandbox final line: `HANDOFF: <allowed-role> - <why>` or
     `HANDOFF: none - <why>`, never your own role.
+13. Flow: request, `spec-interview`, approval, `module-new`/`module-update`,
+    `auto-review`. Implement from the approved spec and its touch list; do not
+    scan `modules/` or `packages/`. First lookup is `.ai/platform-capabilities.md`.
+    What the spec lacks is a spec defect to report, never a guess.
 
 Detailed recipes: `docs/agent-contract.md` (lookup only).
 Reference module: `.ai/references/catalog`; visual contract: `docs/design-system.md`.

package/docs/agent-contract.md

@@ -31,8 +31,8 @@ Use the already selected task skill. Consult `.ai/references/catalog` for implem
 20. Passwords, session tokens and provider credentials never leave `auth.core` (or the `agents.core` vault) and never appear in logs, audit metadata or responses.
 21. `setup quick` and `auth greenfield` are destructive local resets. Preview first, stop the app, never point them at a custom or deployed database.
 22. Agent workers reach ERP data only through registered API or CLI tools. A module defines them with `defineApiAgentTool` or `defineCliAgentTool` from `@flowdular/sdk/harness/tool-adapters` and registers them inside `createServerComposition` with `context.agentTools.register([...])`; nothing else registers a tool. A module may also ship business agents with `defineAgent()` from `@flowdular/sdk/modules/agents/server` and `context.agentDefinitions.register([...])` after declaring an `agents.core` dependency. Their code allowlist is only a maximum: effective tools are the exact intersection of that allowlist, the tenant binding reduction, invocation grants, registered tool permissions, the actor's saved permission ceiling, and live authorization. Sandbox coding specialists are not business agents.
-23. A background run is persisted before enqueue returns; idempotency, leases, recovery, tenant scoping and append-only audit evidence for every fire-and-forget run.
-24. Module settings are declared with `defineModuleSettings` from `@flowdular/sdk/kernel`, returned as `settings` from the composition, read live with `context.settings.get(tenantId, '<module>.core', key)`, and rendered in that module's drawer under Administration, Modules. User-facing setting copy declares fully qualified `labelKey` and `descriptionKey` present in every module locale, with English `label` and `description` literals as compatibility fallbacks. Values, identifiers and secrets are never translated. Administration, Settings is only for workspace and organization settings. A cross-module setting read needs a declared dependency and a `shared`, non-secret setting. Cross-module operations use a typed public service registered in `context.capabilities` by the owning module and resolved by a declared dependent, never the other module's database.
+23. A background run is persisted before enqueue returns; idempotency, leases, recovery, tenant scoping and append-only audit evidence for every fire-and-forget run. A poll loop is `createJobRunner` from `@flowdular/sdk/server`, never a hand-written `setInterval`: it owns the timer and its unref, the guard against overlapping passes, the bound on claims per pass, per-item isolation, the lease renewal and its `CLAIM_LOST` abort, the backoff and the drain, while the module keeps its table, its routing read, its claim and renewal statements and its stale window. `packages/server/src/jobs/index.ts` carries the adoption recipe per module.
+24. Module settings are declared with `defineModuleSettings` from `@flowdular/sdk/kernel`, returned as `settings` from the composition, read with `context.settings.get(tenantId, '<module>.core', key)` after the tenant was primed (`await context.settings.prime(tenantId)`; the authenticated request path and the platform composition prime, a background path primes itself, an unprimed read fails loudly), written with `await context.settings.set(...)` against an asynchronous store, and rendered in that module's drawer under Administration, Modules. User-facing setting copy declares fully qualified `labelKey` and `descriptionKey` present in every module locale, with English `label` and `description` literals as compatibility fallbacks. Values, identifiers and secrets are never translated. Administration, Settings is only for workspace and organization settings. A cross-module setting read needs a declared dependency and a `shared`, non-secret setting. Cross-module operations use a typed public service registered in `context.capabilities` by the owning module and resolved by a declared dependent, never the other module's database.
 25. `Development` navigation is owner-only in the client; server permissions remain authoritative.
 26. Generated files are production code: no placeholders, silent fallbacks or skipped tests. `module.json` `version`, spec `specVersion` and `package.json` `version` move together.
 27. Commits and pull requests: short body, one line on verification, no AI attribution footers, generated files only through the CLI. Never use em or en dashes in anything you write.