create-flowdular 0.2.3 → 0.2.5

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

@@ -0,0 +1,217 @@
+# Flowdular design system
+
+Identity 1.0 (2026-08-31). The implementation reference for humans and agents:
+shared primitives, tokens, and the rules for using them.
+
+## Where things live
+
+- `packages/ui` (`@flowdular/sdk/ui`): the only source of visual primitives.
+  Design tokens (`src/styles/tokens.css`), base styles, `ui-*` component
+  classes, TSRX components, icons, and the brand mark. Fonts (IBM Plex Sans
+  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`.
+- 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`).
+- `platform/public`: `favicon.svg`, `og.png` (1200x630 Open Graph image).
+- Brand mark geometry is generated: `node packages/ui/scripts/gen-mark.mjs`
+  rewrites `packages/ui/src/brand/mark.ts` from the weave parameters.
+
+## Rules
+
+1. Primitives first. Use a `ui-*` class or an exported component before
+   writing any new visual code.
+2. Colors, fonts, sizes, radii, and shadows come only from tokens
+   (`var(--...)`). No hex values in shell or module CSS.
+3. Never restyle or override a `ui-*` class outside `packages/ui`.
+4. A missing primitive is added per use case as a module-local component built
+   on the tokens, and flagged as a promotion candidate for `packages/ui`.
+5. Blue means action and selection. Green, amber, and red mean state. Copper
+   is reserved for the brand (mark, splash, sign-in) and is never a button or
+   a state color.
+6. Minimum text size is 12 px (`--text-sm`); labels use `--text-xs` uppercase.
+   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.
+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
+   page; creating and editing happens in a `Drawer`.
+10. `Tag` carries state or a value with meaning (a status, a count, a scope).
+    Never decoration: no "Secure", "Master data", or "Suggested setup" badges.
+    A card head is a title, a one-line description in its `small`, and at most
+    one right-aligned cluster (`ui-card__actions`: a count, a state, buttons).
+11. A row is title and description on the left and its controls on one line on
+    the right, vertically centered (`SettingRow`). The row title is the label;
+    the control inside carries `aria-label`, never a second visible label.
+12. Large sets are summarized where they are read (`ScopeSummary`, grouped by
+    module) and edited in full only inside the drawer (`CheckGrid`).
+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`
+    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.
+
+## Screen pattern
+
+Every record screen is built the same way, so a user who learns one learns all
+of them:
+
+```text
+PageHeader        eyebrow, title, description, [Refresh] [+ New ...]
+Alert             only when the last action failed
+TableCard
+  ui-card__head   title, count, SearchField and Filters on one line
+  Table           the records, full width
+  ui-note         the constraint worth stating (permissions, boundaries)
+Drawer            the create or edit form, opened from the header or a row
+```
+
+`TableCard` is the default for a record screen. It owns the card, the one-line
+head (title, `count`, and the `search` and `filters` slots inside
+`ui-card__filters`), the `Table`, and the optional `ui-note` footer, so every
+screen shows the same head, loading row, empty state, and filtered-empty
+message. A screen passes data and slots, never table markup. Row actions are
+compact, visible buttons in a narrow trailing column with an accessible but
+visually empty header. The column is part of the same `colgroup` in loading,
+empty and populated states, so widths do not drift. `Table` on its own covers
+what needs a bare table, such as the list side of a master-detail screen.
+
+`Table` is backed by the official `@octanejs/tanstack-table` adapter. Modules
+still use the smaller Flowdular `Table` and `TableCard` contract from
+`@flowdular/sdk/ui`; they never import TanStack directly. The shared primitive owns
+the TanStack features, row model, header model and cell rendering so every
+screen keeps the same states, widths and actions.
+
+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.
+
+The drawer holds one `ui-drawer__form`: fields scroll inside
+`ui-drawer__body`, and the primary action stays pinned in `ui-drawer__foot`.
+Escape and the scrim close it. Master-detail screens that only read (agent runs,
+the playground) keep `ui-two-col`; the list side is a `ui-table` whose open
+record carries `is-selected`.
+
+A drawer that edits several independent things (a member, a module) stacks
+`ui-form__section` blocks inside its `ui-form`: an uppercase title and one-line
+description in `ui-form__section-head`, then the fields and a right-aligned
+`ui-form__actions` row with one primary per section. An input paired with one
+action (a temporary password and its Reset) sits in a `ui-control-row`. The
+danger section comes last, and the foot then keeps only Close.
+
+Administration > Settings holds only workspace settings: full-width cards
+(Workspace, Preferences), each `SettingRow` one setting. A module's declared
+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.
+
+## 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                                                                                                                                                                                                                                                                                                                                                                    |
+
+`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.
+
+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`,
+`plus`, `panel-left`, `check`, `filter`, `download`, `more`, `external`,
+`alert`, `x`, `sign-out`, `refresh`, `help`, `key`, `settings`, `braces`. An unknown name renders
+`modules` without a warning; a new icon is one 24x24 stroke path added there.
+
+## Classes
+
+- Layout: `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`,
+  `ui-kpi-grid`, `ui-tag-cloud`, `ui-section-head` (an `h2` with actions
+  inside a view)
+- Surfaces: `ui-card` (+`__head`, `__title` with a `small` description,
+  `__actions` for the right-aligned cluster, `__body`), `ui-toolbar`
+  (+`__spacer` to push actions right; a bare `ui-input` or `ui-select` inside
+  it takes the button height and an `aria-label`)
+- Data: `ui-table` (+`ui-table-wrap`, `ui-table__empty`, `ui-table__actions`
+  for the component-owned trailing button column, `ui-table__state` for a dot plus label,
+  `ui-table__placeholder` for the loading and empty rows inside the table,
+  `.num`, row states `is-clickable` and `is-selected`), `ui-cell`
+  (+`ui-cell__muted`), `ui-mono`, `ui-code`
+- Forms: `ui-form` (+`__row`, `__row--4`, `__foot`, `__actions`, `__section`
+  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`)
+- 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
+  by `SettingRow`: `ui-setting`
+  (+`__text` for title, scope tag, and help, `__control` for the one-line
+  control cluster, `__status` (+`--error`) for the inline result)
+- 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`,
+  `__section` for a static identity or connection block, `__item`,
+  `__item--active`, `__item--danger`, `__sep`), `ui-icon`
+
+Rendered by components, not written by hand: `ui-page-head*`, `ui-search`,
+`ui-field`, `ui-switch` (+`--on`), `ui-dialog` (+`__panel`, `__title`,
+`__body`, `__actions`), `ui-empty` (+`__icon`), `ui-alert` (+`--danger`, `--warning`,
+`--info`), `ui-tag` (+tone and `--mono`), `ui-kpi` (+`__label`, `__value`,
+`__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-varfield` (+`__control`, `__highlight`, `__input`, `__pill`
+(+`--error`), `__trigger`, `__menu`, `__value`, `__empty`; the overlay layer
+that highlights `{{ key }}` tokens, rendered by `VariableTextarea` and
+`VariableInput`).
+
+## Token cheat sheet
+
+- Surfaces: `--bg`, `--surface`, `--surface-2`; lines: `--line`, `--line-2`
+- Text: `--ink`, `--ink-2` (labels), `--ink-3` (descriptions), `--ink-4`
+  (placeholders only, below AA for text)
+- Action: `--primary`, `--primary-hover`, `--primary-soft`, `--primary-tint`,
+  `--focus`
+- State: `--success`, `--warning`, `--danger` with `-bg` and `-line` pairs
+- Brand: `--brand`, `--brand-weft` (copper)
+- Type: `--font-sans`, `--font-mono`, `--text-xs` 11 to `--text-display` 36
+- Dimensions: `--sidebar-w` 260, `--rail-w` 60, `--topbar-h` 52, `--control-h`
+  36, `--button-h` 32, `--row-h` 44, radii `--r-sm` 4, `--r` 6, `--r-md` 8,
+  `--r-lg` 12
+
+Components reference the semantic layer only, so a dark theme is one token
+override block, not a rewrite.

package/agent-template/docs/modules.md

@@ -0,0 +1,146 @@
+# Modules
+
+A module is a self-contained slice of the product: its own permissions,
+endpoints, migrations, services, screens, translations and tests, wired into the
+platform without touching a core file. `.ai/references/catalog` is the pinned reference
+implementation; copy its shape.
+
+## Lifecycle
+
+```text
+approved spec -> module new -> implement -> gates -> module enable -> verify
+```
+
+### 1. Specification
+
+A module is created only from a `spec/module.yaml` with `status: approved`. The
+spec is the contract: `permissions[].id` equal the constants in
+`src/acl/permissions.ts`, and those permissions are exactly what
+`auth sync-scopes` grants. An agent never approves a spec on its own judgment.
+
+```bash
+pnpm flowdular spec validate --all
+```
+
+### 2. Scaffold
+
+```bash
+pnpm flowdular module new sales.orders \
+  --spec modules/sales-orders/spec/module.yaml            # dry run
+pnpm flowdular module new sales.orders \
+  --spec modules/sales-orders/spec/module.yaml --apply
+```
+
+The scaffold derives everything from the spec: `platform.server` and
+`platform.client` flags from the capabilities, `src/platform.ts` and
+`src/client/index.ts` with the canonical `createServerComposition` and
+`createClientContribution` entries, one `defineEndpoint` per
+`<ns>.<entity>.read` (list) and `.manage` (create) permission of the first
+entity, and, with the `database` capability, an asynchronous repository on the
+`@flowdular/sdk/database` provider, a runtime that acquires and releases its lease,
+and `migrations/0001_*.up.sql` and `.down.sql` with the tenant table and its
+forced row-level security block. The contract is in
+[Database adapters](database-adapters.md) and the `database-adapter` skill.
+
+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
+behind.
+
+### 3. Implement
+
+Rules that bite first (the full contract is in [../AGENTS.md](../AGENTS.md)):
+
+- Tenant id comes only from `principalFromContext(octane)!.tenantId`; every
+  query on a tenant-owned table filters by `tenant_id`.
+- Every endpoint is `defineEndpoint` with an explicit permission; every mutation
+  starts with `sessionMutationDenial(octane, auth)`.
+- Numbered `migrations/000N_*.up.sql` files are the schema source and are
+  immutable once applied; add a new additive migration instead of editing one.
+- Repositories acquire their database through `context.databases`, keep service
+  and endpoint callers asynchronous, run every operation inside
+  `database.transaction(..., { tenantId, access })`, and ship explicit
+  PostgreSQL SQL plus migration adoption checks.
+- UI is built only from `@flowdular/sdk/ui` components, `ui-*` classes and tokens
+  ([design-system.md](design-system.md)).
+- Cross-module operations go through a typed public service registered in
+  `context.capabilities`, never another module's database.
+- Every imported package is declared in the module `package.json`; relative
+  imports carry `.ts` or `.tsrx`.
+
+### 4. Validate
+
+```bash
+pnpm flowdular module validate
+pnpm --filter @flowdular/module-<dir> typecheck
+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).
+`module.json` version drift against `specVersion`, or a locale missing from
+`flowdular.json`, is reported as a warning.
+
+### 5. Enable
+
+```bash
+pnpm flowdular module enable sales.orders --apply
+pnpm flowdular module disable sales.orders --apply
+```
+
+`enable` resolves the module's complete dependency closure, writes every newly
+enabled module to `flowdular.json` in deterministic dependency-first order, adds
+the required packages to `platform/package.json`, runs `pnpm install` when a
+package is not linked yet, and regenerates
+`platform/src/generated/modules.{server,client}.ts`. With `--apply` it also
+grants the scopes declared by each newly enabled module to every workspace owner
+through `auth sync-scopes`; a failed grant is reported as
+`MODULE_SCOPES_SYNC_FAILED`, and when `auth.core` is unavailable the grant is
+skipped with a warning.
+
+`disable` refuses while another enabled module depends on the target, then
+removes it and regenerates. `system.core` and `auth.core` are protected.
+
+A running `pnpm dev` picks the change up live: the octane plugin reloads server
+routes when the generated composition changes and the client hot-reloads, so no
+rebuild is needed. `pnpm dev` and `pnpm build` run the sync automatically.
+
+## Files the CLI owns
+
+Never edit these by hand:
+
+- `flowdular.json` `modules.enabled`
+- `platform/package.json` dependencies
+- `platform/src/generated/**`
+- `platform/octane.config.ts` and `platform/src/App.tsrx`
+
+## Module settings
+
+Modules can also contribute standalone public or protected web pages outside the
+workspace shell. See [Module web surfaces](module-web-surfaces.md) for page
+entries, layouts, tenant-bound path mounts, loaders and access rules.
+
+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. Administration, Settings holds
+only workspace and organization settings.
+
+## Adding a CLI command
+
+Module commands live in `src/cli/commands.json` and `src/cli/index.ts`,
+metadata-identical, inside the module namespace. See
+[cli-extensions.md](cli-extensions.md).
+
+## Guided procedures
+
+Each change class has a canonical skill in [`.ai/skills`](../.ai/skills).
+RuleSync generates the discovery copies for supported coding agents:
+`module-new`, `module-update`, `migration-authoring`, `ux-design`,
+`database-adapter`, `translations-i18n`, `auth-security-review`,
+`test-hardening`, `cli-extension`, `agent-tool-design`,
+`business-agent-design`, `workflow-development`, `release-eject-pr`.
+
+Official business modules are maintained outside core. See [module distribution](module-distribution.md) for install, update, lock verification and release checks.

package/agent-template/platform/scripts/build.mjs

@@ -0,0 +1,38 @@
+import { randomBytes } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const stateDirectory = mkdtempSync(join(tmpdir(), 'flowdular-build-'));
+const buildSecret = () => randomBytes(32).toString('base64');
+
+/* The Octane plugin evaluates the server composition while bundling it. Give
+   that build-time process isolated state and ephemeral keys, without using deployment database settings or encryption keys. The emitted server still reads its real
+   production environment when it starts. */
+const environment = {
+	...process.env,
+	/* A production bundle is evaluated while it is built, but the build must not
+	   connect to the deployment database. The embedded engine writes into the
+	   throwaway state directory below; runtime still reads its real adapter. */
+	FD_ENV: 'development',
+	FD_INTERNAL_BUILD: 'true',
+	FD_DATABASE_ADAPTER: 'pglite',
+	FD_DATABASE_PGLITE_DIRECTORY: join(stateDirectory, 'pglite'),
+	FD_AGENT_CREDENTIAL_KEY: buildSecret(),
+	FD_AGENT_RUN_GRANT_KEY: buildSecret(),
+	FD_AUTOMATIONS_CREDENTIAL_KEY: buildSecret(),
+	FD_WORKFLOWS_PAYLOAD_KEY: buildSecret(),
+	FD_WORKFLOWS_CURSOR_KEY: buildSecret(),
+};
+
+try {
+	const result = spawnSync('vite', ['build'], {
+		env: environment,
+		stdio: 'inherit',
+	});
+	if (result.error) throw result.error;
+	process.exitCode = result.status ?? 1;
+} finally {
+	rmSync(stateDirectory, { recursive: true, force: true });
+}

package/agent-template/rulesync.jsonc

@@ -0,0 +1,11 @@
+{
+	"$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/config-schema.json",
+	"inputRoots": [".ai"],
+	"outputRoots": ["."],
+	"targets": ["codexcli", "claudecode"],
+	"features": ["rules", "skills"],
+	"delete": true,
+	"verbose": false,
+	"silent": false,
+	"global": false,
+}

package/dist/bin.js

@@ -438,7 +438,9 @@ async function scaffold(request) {
       `${directory} is not empty. Pass --force to scaffold into it anyway.`
     );
   }
-  const files = await copyTemplate(template, directory);
+  const agentTemplate = resolve2(templatesRoot(), "..", "agent-template");
+  await assertTemplateExists(agentTemplate, "agent guidance");
+  const files = await copyTemplate(template, directory) + await copyTemplate(agentTemplate, directory);
   await rewritePackageName(directory, name);
   await writeFile(
     join2(directory, ".env"),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-flowdular",
-	"version": "0.2.3",
+	"version": "0.2.5",
 	"type": "module",
 	"description": "Scaffold a Flowdular application: the platform, one example module and the secrets a fresh install needs.",
 	"license": "MIT",
@@ -25,7 +25,8 @@
 		"dist",
 		"template",
 		"README.md",
-		"assets"
+		"assets",
+		"agent-template"
 	],
 	"engines": {
 		"node": ">=22.22.2"

package/template/default/.prettierignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+pnpm-lock.yaml
+.flowdular/
+AGENTS.md
+CLAUDE.md
+.agents/skills/
+.claude/skills/
+.ai/references/

package/template/default/README.md

@@ -27,6 +27,18 @@ install. Data lives under `.flowdular/data`.
 | `flowdular.json`  | Enabled modules and locales, owned by the CLI                |
 | `.env`            | The keys generated for this app. Never commit it             |
 
+## Work with coding agents
+
+`AGENTS.md` and `CLAUDE.md` introduce the application contract. `.ai` contains the
+editable rules, skills, role prompts, policies, blueprints and reference module.
+Codex and Claude Code discover generated skills in `.agents/skills` and
+`.claude/skills`. Supporting guides are in `docs`.
+
+After editing `.ai/rules` or `.ai/skills`, run `pnpm rules:generate`.
+`pnpm rules:check` detects drift and also runs as part of `pnpm verify`.
+Extend local modules using the published `@flowdular/sdk` imports. Installed
+SDK source is reference material and must not be edited in `node_modules`.
+
 ## Build your first module
 
 ```bash

package/template/default/flowdular.json

@@ -23,8 +23,8 @@
 	},
 	"locales": ["en", "pl"],
 	"agent": {
-		"policy": "platform/node_modules/@flowdular/sdk/.ai/policies/capabilities.yaml",
-		"modelRouting": "platform/node_modules/@flowdular/sdk/.ai/policies/model-routing.yaml",
-		"blueprints": "platform/node_modules/@flowdular/sdk/.ai/blueprints"
+		"policy": ".ai/policies/capabilities.yaml",
+		"modelRouting": ".ai/policies/model-routing.yaml",
+		"blueprints": ".ai/blueprints"
 	}
 }

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

@@ -16,7 +16,7 @@
 	"dependencies": {
 		"octane": "0.1.51",
 		"segment-state": "0.2.0",
-		"@flowdular/sdk": "0.2.2"
+		"@flowdular/sdk": "0.2.3"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",

package/template/default/package.json

@@ -16,11 +16,15 @@
 		"flowdular": "flowdular",
 		"cl": "flowdular",
 		"doctor": "flowdular doctor",
-		"verify": "pnpm typecheck && pnpm test && flowdular module validate && pnpm format:check"
+		"verify": "pnpm rules:check && pnpm typecheck && pnpm test && flowdular module validate && pnpm format:check",
+		"rules:generate": "rulesync generate",
+		"rules:check": "rulesync generate --check",
+		"build": "flowdular module sync --apply && pnpm --filter @app/platform build"
 	},
 	"devDependencies": {
 		"@tsrx/prettier-plugin": "0.3.120",
 		"prettier": "3.6.2",
-		"flowdular": "0.2.2"
+		"flowdular": "0.2.3",
+		"rulesync": "16.21.0"
 	}
 }

package/template/default/platform/octane.config.ts

@@ -34,9 +34,13 @@ function checkedRoutes<T extends Parameters<typeof assertRouteConflicts>[0]>(
 
 const SHELL = ['App', '/src/App.tsrx'] as const;
 const workspaceRoot = resolve(import.meta.dirname, '..');
+const building = process.env.FD_INTERNAL_BUILD === 'true';
 
 const databases = createPlatformDatabaseProvider(
-	databaseProviderConfigFromEnvironment(process.env, workspaceRoot),
+	databaseProviderConfigFromEnvironment(
+		building ? { ...process.env, NODE_ENV: 'development' } : process.env,
+		workspaceRoot,
+	),
 );
 const configuredApplicationPath = validateApplicationPath(
 	process.env.FD_APPLICATION_PATH ?? applicationBasePath,
@@ -68,9 +72,11 @@ agentDefinitions.seal();
 
 /* check() proves the runtime role holds neither SUPERUSER nor BYPASSRLS before
    any module reads a row. */
-await databases.check();
-for (const composition of moduleCompositions) await composition.prepare?.();
-for (const composition of moduleCompositions) composition.start?.();
+if (!building) {
+	await databases.check();
+	for (const composition of moduleCompositions) await composition.prepare?.();
+	for (const composition of moduleCompositions) composition.start?.();
+}
 
 let stopping = false;
 const shutdown = async () => {
@@ -83,8 +89,13 @@ const shutdown = async () => {
 	await authRuntime.dispose();
 	await databases.dispose();
 };
-process.once('SIGINT', () => void shutdown());
-process.once('SIGTERM', () => void shutdown());
+// Bundling needs route declarations without background work or retained leases.
+if (building) {
+	await shutdown();
+} else {
+	process.once('SIGINT', () => void shutdown());
+	process.once('SIGTERM', () => void shutdown());
+}
 
 export default defineConfig({
 	middlewares: [authRuntime.middleware],

package/template/default/platform/package.json

@@ -6,7 +6,8 @@
 	"scripts": {
 		"dev": "node scripts/dev.mjs",
 		"preview": "octane-preview --host 127.0.0.1 --port 4310 --strictPort",
-		"typecheck": "tsrx-tsc --noEmit -p tsconfig.json"
+		"typecheck": "tsrx-tsc --noEmit -p tsconfig.json",
+		"build": "node scripts/build.mjs"
 	},
 	"dependencies": {
 		"@app/module-example": "workspace:*",
@@ -14,7 +15,7 @@
 		"@octanejs/vite-plugin": "0.1.51",
 		"octane": "0.1.51",
 		"pg": "8.23.0",
-		"@flowdular/sdk": "0.2.2"
+		"@flowdular/sdk": "0.2.3"
 	},
 	"devDependencies": {
 		"@octanejs/app-core": "0.0.47",