@xeplr/cli 0.3.3 → 0.3.4

package/README.md

@@ -41,6 +41,19 @@ Already working, with nothing to wire up:
   - **Menu**: rename, reorder and hide the side rail's items.
 
   Nobody else sees it, and the API refuses everyone else.
+- **Flows, in every app** — your forms one after another. Designed in
+  Configure UI → Flows: for each screen, the app's functions that run around
+  its records (its events) and where the journey goes once it is saved — a
+  screen, a function that decides, or the end. Walked at `/journey/<key>`, and
+  resumable. Run by `@xeplr/workflow-api` **inside the API**, in a database of
+  its own (`<name>_workflow`, created on first start) — nothing extra to start.
+  It follows the app's tenancy (none, or the levels you chose) and never creates
+  companies or workspaces of its own. Approvals (another person's turn) are not
+  part of it.
+- **Functions** — `api/functions/`: the app's own code, registered with
+  `@xeplr/actions` by the event it is for (`beforeSave`, `afterSave`, …,
+  `decide`) and picked by name in a screen's events or a flow step. Two to start
+  from: `tidyTaskTitle` (Tasks' `beforeSave`) and `byPriority` (a `decide`).
 - **Multi-tenancy, if you ask for it** — companies (or companies and
   workspaces, up to four levels). Every row is stamped with the one it was made
   in, every read sees only its rows, membership is checked on every request,
@@ -71,7 +84,7 @@ These are architecture decisions, not defaults to tune — each one exists becau
 | **`REDIS_PREFIX` is required and unique per app** (`api/development.env`, set to `<name>:`). | `@xeplr/auth`, `@xeplr/utils` | Two apps on one Redis under the shared default serve each other's sessions, menus and API permissions. Sign-in refuses to start without it, or with `xeplr:`. |
 | **Designing, new forms and publishing are Super Admin only.** | `api/routes/access.js`, `@xeplr/auth` menu routes | Publishing changes database tables. Every other screen route checks the permission catalog. |
 | **The browser is not a security boundary.** Front-end hooks (`ui/src/pages/Edit<Form>.jsx`) shape what people see and send; anything that must hold goes in server hooks (`api/screens/<form>/<form>.hooks.js`); data shape in the model (`<form>.model.js`). | `@xeplr/ui-factory`, `@xeplr/factory` | |
-| **Anything every app would write identically lives in a package, not in the generated app.** A generated app is a starting point that then lives its own life — glue copied into it can never be fixed centrally, so an app made last month keeps that copy forever. When Configure UI → Masters needed to know which forms are masters, that answer went into `@xeplr/ui-factory` (`useScreenSource`) and the generated page only reads `masters`. | `@xeplr/ui-factory` | A fix or a new control type has to reach apps that already exist, and it cannot reach code that was copied into them. `test/cli.test.js` fails if the glue reappears in the generated app. |
+| **Anything every app would write identically lives in a package, not in the generated app.** A generated app is a starting point that then lives its own life — glue copied into it can never be fixed centrally, so an app made last month keeps that copy forever. When the flow designer needed this app's forms, its functions and its flows, the wiring went into `@xeplr/ui-factory` (`FlowDesignerPage`) and the generated page passes its two API clients. | `@xeplr/ui-factory` | A fix or a new control type has to reach apps that already exist, and it cannot reach code that was copied into them. `test/cli.test.js` fails if the glue reappears in the generated app. |
 | **Every data address is under `/api`.** | `api/routes`, `ui/vite.config.js` | A page path and a data path must never collide. |
 | **No guessed database names or connections.** | `api/development.env` | A wrong-but-present value starts cleanly and reads as empty data. |
 | **Email is checked at start, never fatal.** The sign-in banner shows `email ✓ …` or `✗ NOT WORKING — reason`. | `@xeplr/auth` | Sign-in works without email; activation, invite and reset links cannot be sent until `EMAIL_PROVIDER` is set. |
@@ -119,6 +132,12 @@ see **Configure UI** in the settings menu, top right.
 (`<name>_auth`, `<name>_api`); an existing database is kept as it is, with its
 accounts — the super admin you enter is created only in a fresh one.
 
+Dashes in the name become underscores in the database names: `my-app` gets
+`my_app_auth` and `my_app_api`. `@xeplr/db` creates only plain identifiers
+(letters, digits, `_`) because `CREATE DATABASE` cannot take its name as a
+parameter, and the project name itself cannot hold `_` (it is also a folder and
+a package name).
+
 `xeplr new myapp --no-install` only writes the files; then run `npm install` in
 `api` and `ui`, and `npm run setup` in `api`, yourself. If set-up stops part
 way (Postgres not running, say), the installer says which step and the command
@@ -139,7 +158,7 @@ Two ways, both in the running app's project:
   > (file: .pdf or .jpg), Notes (long text). Show Name, Region and Area in the
   > list. Follow "Create a new UI" in CLAUDE.md.
 
-  Claude follows `CLAUDE.md`: the screens and server hooks and model
+  Claude follows `CLAUDE.md`: the screens and server functions and model
   (`npx xeplr-factory screens … --no-pages`), the page with its front-end hooks,
   the route, the side-rail item and its menu row. Then restart the sign-in
   service and the API — the API publishes the new screens and creates the table.
@@ -153,7 +172,7 @@ Two ways, both in the running app's project:
 | `api/` | `npm run start-api` | the API — runs migrations and publishes never-published screens on start |
 | `api/` | `npm run migrate:auth` | apply new `migrations-auth/*.sql` (e.g. a new menu row) |
 | `api/` | `npm run db:encrypt` | redo the encrypted database connection |
-| `api/` | `npx xeplr-factory screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages` | a form's screens, server hooks and model from its spec |
+| `api/` | `npx xeplr-factory screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages` | a form's screens, server functions and model from its spec |
 | `api/` | `npx xeplr-factory validate <screen>.json` | check a screen document |
 | `ui/` | `npm run dev` | the app |
 
@@ -200,6 +219,17 @@ no defaults, ever.
 
 Encryption keys and signing secrets are **generated, never asked**.
 
+**Flows, inside the API.** `@xeplr/workflow-api` is a dependency of `api/`,
+and `bin/www` starts it with `registerWorkflow` after the screens — in a
+database of its own (`DB_WORKFLOW`, `<name>_workflow`: a sub-product embedded in
+an app keeps its tables apart, and creates the database on first start), with
+`tenantTables: false` so it follows the app's tenancy rather than creating
+`companies` / `workspaces`, and `access: true` so each flows route checks the
+caller's permissions, which its `migrations-auth` grants (loaded through
+`XEPLR_AUTH_MIGRATIONS`). The designer is `@xeplr/ui-factory`'s
+`FlowDesignerPage`; the paid canvas designer (X-Flow) is not part of a
+generated app.
+
 ## Licence
 
 MIT

package/lib/generate/index.js

@@ -24,6 +24,9 @@ var RENAME = {
 function substitutions(answers) {
   return Object.assign({
     __NAME__: answers.name,
+    __DB_API__: answers.databases.api,
+    __DB_AUTH__: answers.databases.auth,
+    __DB_WORKFLOW__: answers.databases.workflow,
     __PREFIX__: answers.prefix,
     __UI_PORT__: String(answers.ports.ui),
     __AUTH_PORT__: String(answers.ports.auth),
@@ -34,7 +37,25 @@ function substitutions(answers) {
     __ADMIN_PASSWORD__: answers.admin.password,
     __DB_CONNECTION__: answers.connection || '',
     __CONNECTION_NOTE__: connectionNote(answers)
-  }, tenancySubstitutions(answers.tenancy || []));
+  }, tenancySubstitutions(answers.tenancy || []), flowsSubstitutions(answers));
+}
+
+/**
+ * FLOWS ARE IN EVERY APP, and so is what runs them: @xeplr/workflow, started
+ * INSIDE the API (bin/www → registerWorkflow) in the app's own database. There
+ * is no Workflow server to run, no port, no setting and nothing to connect, so
+ * nothing here depends on an answer — these tokens only carry text.
+ */
+function flowsSubstitutions(answers) {
+  return {
+    __WF_README__: flowsReadme(answers),
+    __WF_CLAUDE__: [
+      '**Flows** — forms one after another, run by `@xeplr/workflow-api` INSIDE this API (bin/www starts it, workflow.js) in a database of its own (`DB_WORKFLOW`). Design them in Configure UI → Flows, never in code: a flow is data, reached through `/api/workflow/flows`, and walked at `/journey/<key>`. After a step, a flow goes to a screen, lets one of the app\'s `decide` functions choose, or finishes. Workflow follows this app\'s tenancy — it never creates companies or workspaces of its own.',
+      '',
+      '**Functions** — the code around a form\'s records lives in `api/functions/`, registered with `@xeplr/actions` under the event it is for (`beforeLoad`, `beforeSave`, `afterSave`, `beforeDelete`, `onError`, or `decide` for a flow), and is picked BY NAME in the screen\'s `events` or a flow step\'s navigation. There are no hook files. A screen naming a function nobody registered is refused at publish.',
+      ''
+    ].join('\n')
+  };
 }
 
 /**
@@ -118,6 +139,42 @@ function tenancySubstitutions(levels) {
   };
 }
 
+/** The README's Flows section. */
+function flowsReadme(answers) {
+  var tenancy = answers.tenancy || [];
+  return [
+    '## Flows',
+    '',
+    'Your forms, one after another. Design one in **Configure UI → Flows**: pick the screens, and for each one say what runs around its records (its **events**) and where the journey goes once it is saved — a screen, a **function that decides**, or the end. Publish it, and people start it from **Flows** in the side rail (or at `/journey/<key>`). The run id joins the address once it starts, so a journey can be reloaded, left, or handed to someone else and opened on the step it is on.',
+    '',
+    'Flows are run by **`@xeplr/workflow-api`**, **inside this API** — `bin/www` starts it after the screens. Nothing else to start:',
+    '',
+    '| | |',
+    '|---|---|',
+    '| **Database** | its own, `DB_WORKFLOW` (`' + answers.databases.workflow + '`), beside this app\'s — a sub-product embedded in an app keeps its tables apart. Created and migrated the first time the API starts. Each screen still saves into its own table in `DB_API`. |',
+    '| **Tenancy** | ' + (tenancy.length
+      ? 'this app\'s — flows and runs belong to the ' + tenancy.map(function (l) { return l.label.toLowerCase(); }).join(' and ') + ' chosen after signing in, checked by the same membership gate as everything else.'
+      : 'none, like the rest of this app — flows belong to the whole app.') + ' Workflow never creates companies or workspaces of its own. |',
+    '| **Permissions** | each route checks the caller\'s (`List flows`, `Start flow run`, `Publish flow`…), granted by `@xeplr/workflow-api`\'s `migrations-auth`, which `XEPLR_AUTH_MIGRATIONS` loads. |',
+    '',
+    '## Functions — your code, picked by name',
+    '',
+    'Code around a form\'s records — a check on save, an email after, a list narrowed to the user\'s own — is a **function** in `api/functions/`, registered with `@xeplr/actions` under the **event** it is for. A screen names it in its `events`; a flow step names a `decide` function to choose where to go next. The designer shows each event only the functions written for it, with what they are handed and return; the code stays in `api/functions/` and runs on the server.',
+    '',
+    '| event | runs | return |',
+    '|---|---|---|',
+    '| `beforeLoad` | before records are read | nothing, or a narrower `ctx.query` |',
+    '| `beforeSave` | before a record is written | the values to save; `ctx.reject(message, { field })` refuses |',
+    '| `afterSave` | once it is saved | (ignored) |',
+    '| `beforeDelete` | before a delete | nothing; `ctx.reject` refuses |',
+    '| `onError` | when load / save / delete failed | (ignored) |',
+    '| `decide` | a flow step is done | the next step\'s key |',
+    '',
+    '`api/functions/index.js` registers two to start from: `tidyTaskTitle` (Tasks\' `beforeSave`) and `byPriority` (a `decide`). A screen that names a function nobody registered is refused when it is published, by name.',
+    ''
+  ].join('\n');
+}
+
 /** One level's own table: what the picker lists. Its parents' ids in mtIdN. */
 function tenantTableSql(level, i) {
   var parents = i === 0 ? 'none — the outermost level' : i === 1 ? 'mtId1 holds the one above' : 'mtId1–mtId' + i + ' hold the ones above';

package/lib/plan.js

@@ -18,6 +18,7 @@ function describe(answers) {
   L.push('  Databases (created for you on first run):');
   L.push('    ' + answers.databases.auth + '    accounts, roles, permissions');
   L.push('    ' + answers.databases.api + '     your own data');
+  L.push('    ' + answers.databases.workflow + '  flows and their runs');
   L.push('');
   L.push('  You will sign in as ' + answers.admin.email + '.');
   L.push('');

package/lib/questions.js

@@ -20,6 +20,21 @@ function envPrefix(name) {
   return name.toUpperCase().replace(/-/g, '_');
 }
 
+// What @xeplr/db's ensureDatabase accepts: CREATE DATABASE cannot take its
+// name as a parameter, so it allows plain identifiers only.
+var DB_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function databaseNames(name) {
+  // my-app → my_app_auth, my_app_api. Dashes are fine in a folder and a
+  // package name but not in an unquoted identifier, and @xeplr/db refuses
+  // them ("Unsafe database name"). NAME_RE does not allow underscores, so
+  // without this every name with a separator in it failed at set-up.
+  var base = name.replace(/-/g, '_');
+  // Workflow gets a database of its own: a sub-product embedded in an app is
+  // given its own store, never a share of the app's (see the API's workflow.js).
+  return { auth: base + '_auth', api: base + '_api', workflow: base + '_workflow' };
+}
+
 // ── tenancy ──────────────────────────────────────────────────────────────
 //
 // At most four levels — @xeplr/db has four tenant columns (mtId1-4) — named
@@ -134,6 +149,10 @@ async function collect(session, argvName) {
     tenancy = tenancyLevels(levelsText);
   }
 
+  // ── flows ─────────────────────────────────────────────────────────────
+  // Nothing to ask: every app has flows, run by @xeplr/workflow inside its own
+  // API and database (see lib/generate's flowsSubstitutions).
+
   // ── the database ──────────────────────────────────────────────────────
   //
   // ASKED, not defaulted, and not left for the reader to do by hand either.
@@ -171,7 +190,7 @@ async function collect(session, argvName) {
     name: name,
     prefix: envPrefix(name),
     ports: { ui: base, auth: base + 1, api: base + 2 },
-    databases: { auth: name + '_auth', api: name + '_api' },
+    databases: databaseNames(name),
     admin: { email: adminEmail, password: adminPassword },
     tenancy: tenancy,
 
@@ -181,4 +200,4 @@ async function collect(session, argvName) {
   };
 }
 
-module.exports = { collect: collect, envPrefix: envPrefix, tenancyLevels: tenancyLevels, NAME_RE: NAME_RE };
+module.exports = { collect: collect, envPrefix: envPrefix, databaseNames: databaseNames, DB_NAME_RE: DB_NAME_RE, tenancyLevels: tenancyLevels, NAME_RE: NAME_RE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/cli",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Creates a working xeplr application — API, sign-in and UI — from a few answers.",
   "license": "MIT",
   "author": "xeppie <admin@xeplr.com>",

package/templates/CLAUDE.md

@@ -3,13 +3,13 @@
 An xeplr app: `api/` (Node, @xeplr/base-apis, sign-in by @xeplr/auth) and `ui/` (React + Vite, @xeplr/ui-account).
 Forms are **screens** made with @xeplr/ui-factory and served by @xeplr/factory. The sample is **Tasks**.
 
-Read `api/node_modules/@xeplr/ui-factory/AUTHORING.md` for what screens, hooks and models mean. This file says where they go in **this** app.
+Read `api/node_modules/@xeplr/ui-factory/AUTHORING.md` for what screens, functions, front-end hooks and models mean. This file says where they go in **this** app.
 
 ## Create a new UI
 
 A new UI is a **form**: a list, and an add / edit form it opens — on a page of its own (like Tasks) or in a popup — saved in its own table. Use the singular for `<form>` (`farming_department`), the plural for the page (`FarmingDepartments`).
 
-Create every file below — the hooks and the model run the defaults (`super`) until the request needs more.
+Create every file below — the front-end hooks and the model run the defaults (`super`) until the request needs more, and the server functions file registers nothing until it does.
 
 1. **The spec** — `api/screens/<form>/<form>.entity.json`: the name and the fields in reading order. Copy `api/screens/task/task.entity.json`; the format is "The entity spec" in AUTHORING.md. A dropdown on another form's table needs that form to exist first. **Use the ready-made fields** for email, phone, website, LinkedIn, age, date of birth, gender, country, amount, percentage, yes/no and postal code — `"type": "email"` and so on ("Choosing controls" in AUTHORING.md): they bring the keyboard, format check and options with them, so don't write those by hand.
 2. **Screens + server files** — from `api/`:
@@ -18,8 +18,8 @@ Create every file below — the hooks and the model run the defaults (`super`) u
    npx xeplr-factory validate screens/<form>/<form>-edit.screen.json
    npx xeplr-factory validate screens/<form>/<form>-list.screen.json
    ```
-   Writes `<form>-list.screen.json`, `<form>-edit.screen.json`, `<form>.hooks.js` (server hooks), `<form>.model.js` (server model).
-3. **Register them** in `api/screens/index.js`: both screens in `documents` (edit before list), `<form>_edit: require('./<form>/<form>.hooks')` in `hooks`, `require('./<form>/<form>.model')` in `models`.
+   Writes `<form>-list.screen.json`, `<form>-edit.screen.json`, `<form>.functions.js` (server functions, none registered yet), `<form>.model.js` (server model).
+3. **Register them** in `api/screens/index.js`: both screens in `documents` (edit before list), `require('./<form>/<form>.model')` in `models`; and in `api/functions/index.js`, `require('../screens/<form>/<form>.functions')`.
 4. **The form's page, with the front-end hooks** — `ui/src/pages/Edit<Form>.jsx`: copy `EditTask.jsx`; rename `TaskHooks` → `<Form>Hooks`, `taskHooks` → `<form>Hooks`, `'task_edit'` → `'<form>_edit'`. Keep every method calling `super`.
 5. **The list's page** — `ui/src/pages/<Forms>.jsx`: copy `Tasks.jsx`; load `'<form>_list'`, import `<form>Hooks` from `./Edit<Form>.jsx`, drop `TasksHelp`.
 6. **Route and side-rail item** — `ui/src/App.jsx`: import the list page, add `<Route path="/<forms>" element={<Forms />} />` next to `/tasks`, and a `drawerItems` entry `{ key: '<Forms>', icon, path: '/<forms>', clickHandler }` — by **key**, with an **icon** (a collapsed rail shows icons only) and the **path** (so the rail marks it as the current page). Never write the label in code.
@@ -33,11 +33,11 @@ Then change only what the request asks for:
 |---|---|
 | a field, label, rule, dropdown, layout, colour | the screen JSON → validate → publish in Configure UI → Forms (or, never published yet, restart the API) |
 | hide / filter rows on screen, an extra button on each row, fill in a value before saving, check something before Next moves on | front-end hooks — `ui/src/pages/Edit<Form>.jsx` (`get`, `save`, `delete`, `actions`, `step`) |
-| must / only if / check against / email when / only managers see | server hooks — `api/screens/<form>/<form>.hooks.js` |
+| must / only if / check against / email when / only managers see | a server function — registered in `api/screens/<form>/<form>.functions.js` with its `event`, then named in `<form>-edit.screen.json`'s `events` (or picked in Configure UI → Flows → Events). Register before naming: a screen naming an unregistered function is refused at publish |
 | store as / convert / comma-separated ↔ array / work out X from Y | server model — `api/screens/<form>/<form>.model.js` |
 | a query in your own server code | `factory.table('<forms table>')` — this company, active rows, the model applied |
 
-**Without code:** Super Admin can also make a form in **Configure UI → Forms** (settings menu, top right): New form (label + key) → design → Publish → Add to menu. It gets no page, hooks or model files; add them with the steps above when it needs them.
+**Without code:** Super Admin can also make a form in **Configure UI → Forms** (settings menu, top right): New form (label + key) → design → Publish → Add to menu. It gets no page, functions or model files; add them with the steps above when it needs them.
 
 ### The controls a field can be
 
@@ -49,6 +49,7 @@ Then change only what the request asks for:
 
 **A list opens its form on a page or in a popup** — `"openIn": "page"` in the entity spec, or Configure UI → Forms → the list. A page needs `onOpenRecord` on the list's page (where to navigate) and `onDone` on the form's page (where Save and Cancel go back to): `Tasks.jsx` and `EditTask.jsx` show both, with routes `/tasks/new` and `/tasks/:id` in `App.jsx`.
 
+__WF_CLAUDE__
 **Keys and labels.** A form's key names its screens and table and never changes once published; its label is the screens' name. A menu item's key (`menus.name`) is what `drawerItems` matches; its label is what the rail shows, renamed in Configure UI → Menu. Code only ever uses keys.
 
 ### The prompt
@@ -64,6 +65,6 @@ Replace the bold parts. Add behaviour in the same message if you want it — "a
 - A published screen's design lives in the **database**. Editing its `.screen.json` changes nothing afterwards: publish the change in Configure UI → Forms.
 - Every data address is under `/api` (a page and a data path must never collide). New routes go in `api/routes/index.js`, and `ui/vite.config.js` must proxy their prefix.
 - Designing and publishing are **Super Admin only** (`api/routes/access.js`); every other route checks the permission catalog.
-- The browser is not a security boundary: anything that must hold goes in server hooks.
+- The browser is not a security boundary: anything that must hold goes in a server function, named in the screen's events.
 - Hooks and models are **methods** calling `super` — never arrow-function properties.
 - `authFetch` returns the parsed body, not a Response.

package/templates/README.md

@@ -21,6 +21,9 @@ cd ui  && npm run dev            # the app           http://localhost:__UI_PORT_
 
 Open http://localhost:__UI_PORT__ and sign in as `__ADMIN_EMAIL__`.
 
+Flows (`@xeplr/workflow-api`) run **inside the API**, in a database of their
+own that the API creates on first start — nothing else to start.
+
 ## Where each address goes
 
 The browser only ever calls **paths** on the app's own address — never a port.
@@ -30,6 +33,7 @@ locally (`ui/vite.config.js`, from `ui/.env`), nginx in production.
 | path | served by | local (`ui/.env`) | production (nginx) |
 |---|---|---|---|
 | `/auth/api/…` | the sign-in service | `AUTH_URL` | `127.0.0.1:<AUTH_PORT>` |
+| `/api/workflow/…` | flows — `@xeplr/workflow-api`, inside the API | `API_URL` | `127.0.0.1:<__PREFIX___PORT>` |
 | `/api/…`, `/health`, `/whoami` | the API | `API_URL` | `127.0.0.1:<__PREFIX___PORT>` |
 
 ### Production
@@ -43,11 +47,11 @@ server {
   server_name app.example.com;
   root /srv/__NAME__/ui/dist;
 
-  location /auth/api/ { proxy_pass http://127.0.0.1:__AUTH_PORT__; }
-  location /api/      { proxy_pass http://127.0.0.1:__API_PORT__; }
-  location = /health  { proxy_pass http://127.0.0.1:__API_PORT__; }
-  location = /whoami  { proxy_pass http://127.0.0.1:__API_PORT__; }
-  location /          { try_files $uri /index.html; }   # the React app's own pages
+  location /auth/api/     { proxy_pass http://127.0.0.1:__AUTH_PORT__; }
+  location /api/          { proxy_pass http://127.0.0.1:__API_PORT__; }
+  location = /health      { proxy_pass http://127.0.0.1:__API_PORT__; }
+  location = /whoami      { proxy_pass http://127.0.0.1:__API_PORT__; }
+  location /              { try_files $uri /index.html; }   # the React app's own pages
 }
 ```
 
@@ -57,7 +61,9 @@ Every one of these checks the same sign-in token, so one login covers them all.
 
 - **Sign-in** — login, register, password reset, profile, and the admin screens for users, roles and permissions (`@xeplr/auth`, `@xeplr/ui-account`).
 - **Tasks** — a sample built from screens: a list, and a form it opens on a page of its own, saved into an ordinary `tasks` table. The form is filled in over three steps and uses every control there is — text, a dropdown, radio buttons, a tick box, a date, a date and time, several tags at once, and a file.
-- **Configure UI** — in the settings menu, for Super Admin: every form (make one, design it, publish it, add it to the side rail) and the side rail itself (rename, reorder, hide).
+- **Configure UI** — in the settings menu, for Super Admin: every form (make one, design it, publish it, add it to the side rail), every flow (screens one after another — each screen's events, and where it goes next) and the side rail itself (rename, reorder, hide).
+- **Flows** — in the side rail: the journeys people can start, run by `@xeplr/workflow-api` inside the API.
+- **Functions** — `api/functions/`: your code, registered by event and picked by name in a screen's events or a flow step (see "Functions" below).
 
 ## Create a new UI
 
@@ -66,6 +72,7 @@ Every one of these checks the same sign-in token, so one login covers them all.
 
   > Create a new UI for farming departments. One record is a farming department with: Name (required), Region (dropdown: North, South, East, West), Area in acres (number, at least 0), Started on (date), Notes (long text). Show Name, Region and Area in the list. Follow "Create a new UI" in CLAUDE.md.
 
+__WF_README__
 ## Rules this app follows
 
 | Rule | Why |
@@ -74,7 +81,7 @@ Every one of these checks the same sign-in token, so one login covers them all.
 | A **key** and a **label**, everywhere: code uses keys (form keys, menu keys); people read labels, renamed in Configure UI. | Renaming what people see never breaks code. |
 | **`REDIS_PREFIX`** in `api/development.env` is required and unique to this app. | Apps sharing a Redis would otherwise serve each other's sessions and permissions. |
 | Designing and publishing forms is **Super Admin only**. | Publishing changes database tables. |
-| Rules that must hold go in **server hooks**; the browser only shapes what people see and send. | The browser is not a security boundary. |
+| Rules that must hold go in **server functions** (`api/functions/`), named in a screen's events; the browser only shapes what people see and send. | The browser is not a security boundary. |
 | Every data address is under **`/api`**. | A page and a data path must never collide. |
 
 The full list, and where each piece lives, is in `CLAUDE.md`.

package/templates/api/README.md

@@ -6,13 +6,13 @@ The API (`@xeplr/base-apis`) and the sign-in service (`@xeplr/auth`), with this
 
 | Command | Does |
 |---|---|
-| `npm run setup` | create both databases (`__NAME___auth`, `__NAME___api`), the sign-in tables, permissions and menus |
+| `npm run setup` | create both databases (`__DB_AUTH__`, `__DB_API__`), the sign-in tables, permissions and menus |
 | `npm run start-auth` | the sign-in service, port __AUTH_PORT__ — refuses to start without Redis or `REDIS_PREFIX`; its banner says whether email works |
 | `npm run start-api` | the API, port __API_PORT__ — runs `migrations/` and publishes never-published screens on start |
 | `npm run migrate:auth` | apply new `migrations-auth/*.sql` (a new menu row, say), then restart sign-in |
 | `npm run db:encrypt` | redo the encrypted database connection |
 | `npm run check-env` | check every required setting is present |
-| `npx xeplr-factory screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages` | a form's screens, server hooks and model from its spec |
+| `npx xeplr-factory screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages` | a form's screens, server functions and model from its spec |
 | `npx xeplr-factory validate <screen>.json` | check a screen document |
 
 ## Layout
@@ -24,7 +24,9 @@ The API (`@xeplr/base-apis`) and the sign-in service (`@xeplr/auth`), with this
 | `app.js` | the Express app: the auth gate, and the routes |
 | `routes/index.js` | this app's own routes — every data address under `/api` |
 | `routes/access.js` | who may design and publish forms (Super Admin) |
-| `screens/` | the forms this app ships with: per form, its spec, list and edit screens, server hooks and model — registered in `screens/index.js` |
+| `screens/` | the forms this app ships with: per form, its spec, list and edit screens, server functions and model — registered in `screens/index.js` |
+| `functions/` | this app's functions — the code screens' events and flows' `decide` pick by name — registered with `@xeplr/actions` by event, loaded at startup |
+| `workflow.js` | flows: `@xeplr/workflow-api` started inside this API, in its own database (`DB_WORKFLOW`) |
 | `uploads/` | what people attach through a form's **file** field (`FACTORY_FILES_DIR`). Never committed, and never served: a file comes back only through the API's own route, which checks the caller the way reading a record does |
 | `migrations/` | hand-written SQL for tables no form owns |
 | `migrations-auth/` | this app's rows in the sign-in database — menus (by key), permissions |

package/templates/api/app.js

@@ -13,6 +13,8 @@ var memberGate = __MT_MEMBER_GATE__;
 var port = process.env.__PREFIX___PORT;
 
 module.exports = buildApp;
+// bin/www hands the same gate to the flows router it starts (workflow.js).
+module.exports.memberGate = memberGate;
 
 function buildApp(extraRoutes) {
   return createApp(port, '__NAME___api', {

package/templates/api/bin/www

@@ -33,6 +33,10 @@ var path = require('path');
 var { resolveConfig } = require('@xeplr/db');
 var { up } = require('@xeplr/db').sqlMigrator;
 var factory = require('@xeplr/factory');
+// This app's functions — what screens' events and flows' "let a function
+// decide" pick by name. Registered before anything can publish a screen that
+// names one.
+require('../functions');
 var screens = require('../screens');
 
 async function start() {
@@ -58,15 +62,13 @@ async function start() {
   // time has no connection at all until this has finished.
   var knex = await require('../db/setup');
 
-  // The screens, their hooks and their models. A hooks file with a typo
-  // ("beforeSave") or a malformed model stops startup here, rather than
-  // silently never running.
+  // The screens and their models. A malformed model stops startup here,
+  // rather than silently never running.
   // filesDir: where a form's file field puts what people upload. Nothing is
   // served from it — a file comes back only through the factory's own route,
   // which checks the caller the way reading a record does.
   await factory.init({
     knex: knex,
-    hooks: screens.hooks,
     models: screens.models,
     filesDir: process.env.FACTORY_FILES_DIR
   });
@@ -76,7 +78,13 @@ async function start() {
   var published = await factory.publishScreens(screens.documents);
   if (published.published.length) console.log('[api] published screens: ' + published.published.join(', '));
 
-  require('../app')();
+  // FLOWS — @xeplr/workflow-api, inside this API, in a database of its own
+  // (DB_WORKFLOW — created and migrated on first start). It follows this
+  // app's tenancy and creates no companies or workspaces of its own.
+  var buildApp = require('../app');
+  require('../routes/flows').mount(await require('../workflow')(buildApp.memberGate));
+
+  buildApp();
 }
 
 start().catch(function(err) {

package/templates/api/db/setup.js

@@ -4,7 +4,7 @@
 var { getConnection } = require('@xeplr/db');
 __MT_DB_REGISTER__
 
-// No `|| '__NAME___api'` fallback. DB_API is required at startup
+// No `|| '__DB_API__'` fallback. DB_API is required at startup
 // (env.required.js), so a default could only ever fire in a process that
 // skipped that check — and silently connecting to a database nobody named is
 // exactly what the check exists to prevent.

package/templates/api/development.env.tpl

@@ -18,10 +18,12 @@ __PREFIX___CONNECTION=__DB_CONNECTION__
 AUTH_DB_CONNECTION_INFO_ENCRYPTED=__DB_CONNECTION__
 
 # ── Databases ──
-# Two of them: accounts in one, your own data in the other. Both are created
-# for you the first time you run the setup.
-DB_API=__NAME___api
-AUTH_DB_NAME=__NAME___auth
+# Three of them: accounts, your own data, and flows (workflow's own, kept apart
+# from yours). The first two are created by the setup; the flows one by the API
+# the first time it starts.
+DB_API=__DB_API__
+AUTH_DB_NAME=__DB_AUTH__
+DB_WORKFLOW=__DB_WORKFLOW__
 
 # ── Sign-in service ──
 #
@@ -40,9 +42,10 @@ AUTH_JWT_SECRET=__JWT_SECRET__
 # Where the sign-in service is. Your API asks it to check every token.
 AUTH_URL=http://localhost:__AUTH_PORT__
 
-# Sign-in setup files: the screens' permissions (@xeplr/factory's), then this
-# app's own — menu entries and anything else it adds. Comma-separated, in order.
-XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./migrations-auth
+# Sign-in setup files: the screens' permissions (@xeplr/factory's), flows'
+# (@xeplr/workflow-api's), then this app's own — menu entries and anything else
+# it adds. Comma-separated, in order.
+XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./node_modules/@xeplr/workflow-api/migrations-auth,./migrations-auth
 
 # ── The first account you sign in with ──
 # Created for you when you set up the database. Change the password here and

package/templates/api/env.required.js

@@ -26,4 +26,8 @@ module.exports = [
   // error — the most expensive way for this to go wrong.
   'DB_API',
   '__PREFIX___CONNECTION',
+
+  // Flows' own database (DB_WORKFLOW) — workflow is embedded in this API but
+  // keeps its tables apart from yours. The library names it.
+  ...require('@xeplr/workflow-api').embedRequiredEnv,
 ];

package/templates/api/functions/index.js

@@ -0,0 +1,47 @@
+// THIS APP'S FUNCTIONS — the code a screen's events and a flow's "let a
+// function decide" run. Loaded once at startup (bin/www), before the screens.
+//
+// A function is registered under the EVENT it is written for, and picked BY
+// NAME in the designer: Configure UI → Flows → a step → Events & navigation
+// (or a screen's own `events` in its .screen.json). The designer only ever
+// sees the name, the description and what the event hands it — the code
+// stays here, and runs on the server.
+//
+//   event          runs                                   ctx adds              return
+//   beforeLoad     before records are read                query (narrow it)     nothing, or a new query
+//   beforeSave     before a record is written             values, isNew,        the values to save
+//                                                         previous
+//   afterSave      once it is saved                       result                (ignored)
+//   beforeDelete   before a delete                        previous              nothing
+//   onError        when load / save / delete failed       error                 (ignored)
+//   decide         a flow step is done: where next?       values, targets       a step key
+//
+// Every ctx has user, tenant, knex, db() (this form's table, scoped) and
+// reject(message, { field }) — which refuses with the message on that field.
+//
+// A screen that names a function nobody registered is refused when it is
+// published, by name — so renaming one here means renaming it there too.
+// Add files beside this one and require them below as the app grows.
+var { register } = require('@xeplr/actions');
+
+register({
+  name: 'tidyTaskTitle',
+  event: 'beforeSave',
+  description: 'Trims a task\'s title and squeezes repeated spaces, so "  Plant   seeds " is saved as "Plant seeds".',
+  execute: function(ctx) {
+    var title = String(ctx.values.title || '').replace(/\s+/g, ' ').trim();
+    if (!title) ctx.reject('A task needs a title', { field: 'title' });
+    return Object.assign({}, ctx.values, { title: title });
+  }
+});
+
+register({
+  name: 'byPriority',
+  event: 'decide',
+  description: 'High-priority tasks go to the first screen it may choose; everything else to the second.',
+  execute: function(ctx) {
+    // ctx.targets: the steps ticked under "It may choose", in the flow's order.
+    var high = ctx.values && ctx.values.priority === 'high';
+    return high ? ctx.targets[0] : (ctx.targets[1] || ctx.targets[0]);
+  }
+});

package/templates/api/migrations-auth/0005_flows_menu.sql

@@ -0,0 +1,14 @@
+-- "Flows" — the side-rail item for journeys across the app's forms.
+--
+-- ALWAYS THERE: flows are run by @xeplr/workflow inside this app's own API,
+-- so there is nothing to switch on.
+--
+-- The name is the KEY: it must match ui/src/App.jsx's drawerItems `key`
+-- EXACTLY. What people read is the label, changed in Configure UI → Menu.
+-- (0005, not 0004: a multi-tenant app's own 0004 is the switch menu.)
+
+INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), 'Flows', '', true, true, '*', now(), now()
+WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = 'Flows');
+
+UPDATE "menus" SET "isPublic" = true WHERE name = 'Flows';

package/templates/api/package.json

@@ -20,12 +20,14 @@
     "@xeplr/auth": "^1.1.4",
     "@xeplr/base-apis": "^2.0.0",
     "@xeplr/db": "^1.0.6",
-    "@xeplr/factory": "^1.1.0",
-    "@xeplr/ui-factory": "^1.1.0",
+    "@xeplr/factory": "^2.0.0",
+    "@xeplr/ui-factory": "^1.7.1",
     "@xeplr/utils": "^1.0.11",
     "dotenv": "^17.4.2",
     "express": "^5.2.0",
-    "multer": "^2.0.2"
+    "multer": "^2.0.2",
+    "@xeplr/actions": "^1.4.0",
+    "@xeplr/workflow-api": "^1.1.0"
   },
   "devDependencies": {
     "dotenv-cli": "^8.0.0",

package/templates/api/production.env.example

@@ -1,5 +1,6 @@
 # __NAME__ API — PRODUCTION settings. Copy to production.env on the server
-# and fill in; start with NODE_ENV=production (bin/www reads <NODE_ENV>.env). production.env is never committed (.gitignore).
+# and fill in; start with NODE_ENV=production (bin/www reads <NODE_ENV>.env).
+# production.env is never committed (.gitignore).
 #
 # Every value that is a secret is blank here. Generate new ones for production
 # — never reuse development's.
@@ -15,15 +16,16 @@ AUTH_PORT=__AUTH_PORT__
 ENCRYPTION_KEY=
 __PREFIX___CONNECTION=
 AUTH_DB_CONNECTION_INFO_ENCRYPTED=
-DB_API=__NAME___api
-AUTH_DB_NAME=__NAME___auth
+DB_API=__DB_API__
+AUTH_DB_NAME=__DB_AUTH__
+DB_WORKFLOW=__DB_WORKFLOW__
 
 # ── Sign-in ──
 REDIS_PREFIX=__NAME__:
 AUTH_JWT_SECRET=
 # Where THIS server reaches the sign-in service (not the public address).
 AUTH_URL=http://127.0.0.1:__AUTH_PORT__
-XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./migrations-auth
+XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./node_modules/@xeplr/workflow-api/migrations-auth,./migrations-auth
 AUTH_SUPER_ADMIN_EMAIL=
 AUTH_SUPER_ADMIN_PASSWORD=
 # none for one set of roles; a multi-tenant app names its company header, e.g. x-company-id

package/templates/api/routes/flows.js

@@ -0,0 +1,23 @@
+// FLOWS — screens one after another, run by @xeplr/workflow-api inside this
+// API (bin/www starts it; workflow.js says where its data lives).
+//
+// Mounted by routes/index.js at /api/workflow, behind this app's auth gate:
+//   /api/workflow/flows       the flows people walk through (Journey) and design
+//   /api/workflow/workflows   the workflow document API underneath
+var express = require('express');
+
+var router = express.Router();
+var workflow = null;
+
+router.use(function(req, res, next) {
+  // Only before startup has finished — bin/www mounts it before listening.
+  if (!workflow) return res.status(503).json({ message: 'Flows are still starting' });
+  return workflow(req, res, next);
+});
+
+/** bin/www hands over registerWorkflow's router, already gated. */
+router.mount = function(workflowRouter) {
+  workflow = workflowRouter;
+};
+
+module.exports = router;

package/templates/api/routes/index.js

@@ -34,4 +34,8 @@ router.get('/whoami', function(req, res) {
 //   var { genericRoute } = require('@xeplr/base-apis');
 //   router.use('/api/things', genericRoute({ key: 'thing', model: require('../models').Thing }));
 
+// Flows: @xeplr/workflow-api, at /api/workflow, running inside this API (see
+// routes/flows.js and workflow.js).
+router.use('/api/workflow', require('./flows'));
+
 module.exports = router;

package/templates/api/screens/index.js

@@ -16,8 +16,11 @@
 //   screens/<form>/<form>.entity.json       its name and fields
 //   screens/<form>/<form>-list.screen.json  the list
 //   screens/<form>/<form>-edit.screen.json  the add / edit form
-//   screens/<form>/<form>.hooks.js          server hooks — save / get / delete
 //   screens/<form>/<form>.model.js          server model — getters / setters
+//
+// Code around a form's records — checks on save, an email after — is not in
+// these folders: it is a FUNCTION in functions/, named in the screen's
+// `events` (task-edit.screen.json names tidyTaskTitle).
 
 module.exports = {
   // Publish order is worked out for you: a table before the dropdowns that
@@ -27,11 +30,6 @@ module.exports = {
     require('./task/task-list.screen.json')
   ],
 
-  // Your own code around save / get / delete, per screen — see task/task.hooks.js.
-  hooks: {
-    task_edit: require('./task/task.hooks')
-  },
-
   // How each table's values are shaped — see task/task.model.js.
   models: [
     require('./task/task.model')

package/templates/api/screens/task/task-edit.screen.json

@@ -269,5 +269,8 @@
       }
     }
   ],
-  "source": "tasks"
+  "source": "tasks",
+  "events": {
+    "beforeSave": "tidyTaskTitle"
+  }
 }

package/templates/api/screens/task/task.model.js

@@ -1,10 +1,10 @@
 // The model for task records — how values are shaped between your code and
 // the "tasks" table, like Sequelize's getters and setters.
 //
-// Register with @xeplr/factory:  factory.init({ knex, hooks, models: [require('./task.model')] })
+// Register with @xeplr/factory:  factory.init({ knex, models: [require('./task.model')] })
 //
 // Used everywhere: the screens' routes and factory.table('tasks'). Models shape
-// data; the hooks file decides behaviour.
+// data; the functions its events name decide behaviour (api/functions/).
 
 var { FactoryModel } = require('@xeplr/factory');
 

package/templates/api/workflow.js

@@ -0,0 +1,32 @@
+// FLOWS — how @xeplr/workflow-api starts, inside this API.
+//
+//   ITS OWN DATABASE   DB_WORKFLOW, beside yours rather than in it — a
+//                      sub-product embedded in an app gets a store of its own.
+//                      Created and migrated on first start, with the same
+//                      server login as the app (__PREFIX___CONNECTION).
+//   THIS APP'S         it registers no tenancy of its own: flows and runs are
+//   TENANCY            filtered by the levels this app registered (or none),
+//                      behind this app's membership gate.
+//   PERMISSIONS        every route checks the caller's ("List flows", "Start
+//                      flow run"…), granted by @xeplr/workflow-api's
+//                      migrations-auth, which XEPLR_AUTH_MIGRATIONS loads.
+//
+// A flow's "let a function decide" picks one of this app's functions
+// (functions/), the same registry the screens' events use.
+var { registerWorkflow } = require('@xeplr/workflow-api');
+
+/** Creates and migrates workflow's database, and returns its router — already gated. */
+module.exports = async function startWorkflow(memberGate) {
+  var workflow = await registerWorkflow({
+    applicationId: '__NAME__',
+    db: {
+      name: process.env.DB_WORKFLOW,
+      connection: process.env.__PREFIX___CONNECTION,
+      connectionName: 'workflow'
+    },
+    tenantTables: false,
+    access: true,
+    mtMembershipGate: memberGate
+  });
+  return workflow.router;
+};

package/templates/ui/package.json

@@ -12,7 +12,7 @@
     "@tanstack/react-table": "^8.21.3",
     "@xeplr/ui-account": "^1.0.9",
     "@xeplr/ui-canvas": "^1.1.0",
-    "@xeplr/ui-factory": "^1.1.0",
+    "@xeplr/ui-factory": "^1.7.1",
     "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",

package/templates/ui/src/App.jsx

@@ -4,6 +4,9 @@ import { authRoutes, authPath, NavPage, ProtectedRoute, useAccess } from '@xeplr
 import Home from './pages/Home.jsx'
 import Tasks from './pages/Tasks.jsx'
 import EditTask from './pages/EditTask.jsx'
+import FlowDesigner from './pages/FlowDesigner.jsx'
+import Journey from './pages/Journey.jsx'
+import FlowsHome from './pages/FlowsHome.jsx'
 import ConfigureUI from './pages/ConfigureUI.jsx'
 import { FORM_MENU_PREFIX } from './menu.js'
 import FormDesigner from './pages/FormDesigner.jsx'
@@ -21,6 +24,15 @@ const TasksIcon = (
   </svg>
 )
 
+const FlowsIcon = (
+  <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
+       strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+    <rect x="3" y="3" width="6" height="6" rx="1" />
+    <rect x="15" y="15" width="6" height="6" rx="1" />
+    <path d="M9 6h4a2 2 0 0 1 2 2v7" />
+  </svg>
+)
+
 const FormsIcon = (
   <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
        strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
@@ -68,6 +80,8 @@ function Shell() {
   const drawerItems = useMemo(() => [
     { key: 'Home', icon: HomeIcon, path: '/home', clickHandler: () => navigate('/home') },
     { key: 'Tasks', icon: TasksIcon, path: '/tasks', clickHandler: () => navigate('/tasks') },
+    // Always in the rail — the page says when Xeplr Workflow is not connected.
+    { key: 'Flows', icon: FlowsIcon, path: '/flows', clickHandler: () => navigate('/flows') },
 __MT_DRAWER_ITEM__
     // Every form added to the menu, with no code: "form:crop" opens /forms/crop.
     ...menus.filter((key) => key.startsWith(FORM_MENU_PREFIX)).map((key) => ({
@@ -115,6 +129,12 @@ __MT_SELECT_ROUTE__
         <Route path="/forms/:form" element={<FormRecords />} />
         <Route path="/configure" element={<ConfigureUI />} />
         <Route path="/configure/forms/:form/design/:part" element={<FormDesigner />} />
+        {/* Flows — run by @xeplr/workflow inside this app's own API. */}
+        <Route path="/flows" element={<FlowsHome />} />
+        <Route path="/configure/flows/:flow" element={<FlowDesigner />} />
+        {/* A journey: its run id joins the address once it starts, so it can be resumed. */}
+        <Route path="/journey/:flow" element={<Journey />} />
+        <Route path="/journey/:flow/:run" element={<Journey />} />
       </Route>
 
       <Route path="*" element={<Navigate to="/auth/login" replace />} />

package/templates/ui/src/api/flows.js

@@ -0,0 +1,6 @@
+// Flows are at /api/workflow/flows — @xeplr/workflow-api, running inside this
+// app's API. authFetch carries the same sign-in and company as every other call.
+import { authFetch } from '@xeplr/ui-account'
+import { createFlowsApi } from '@xeplr/ui-factory'
+
+export const flows = createFlowsApi({ fetch: authFetch, base: '/api/workflow' })

package/templates/ui/src/index.css

@@ -358,3 +358,19 @@ body { margin: 0; }
 .app-menu-shown { display: inline-flex; gap: 6px; align-items: center; }
 
 .app-menu-settings .app-table { margin-bottom: 14px; }
+
+/* ── Flows, before Workflow is connected (src/pages/Flows.jsx) ─────────────── */
+.app-connect {
+  max-width: 720px;
+  padding: 22px 24px;
+  border: 1px solid var(--xeplr-border-primary);
+  border-radius: 10px;
+  background: var(--xeplr-bg-tertiary);
+  line-height: 1.55;
+}
+.app-connect h2 { margin: 0 0 8px; font-size: 18px; }
+.app-connect p { margin: 0 0 14px; }
+.app-connect-steps { margin: 0 0 14px; padding-left: 20px; }
+.app-connect-steps li { margin-bottom: 14px; }
+.app-connect code { font-size: 12.5px; padding: 1px 5px; border-radius: 4px; background: var(--xeplr-bg-secondary); border: 1px solid var(--xeplr-border-primary); }
+.app-connect pre { margin: 6px 0 0; font-size: 12.5px; }

package/templates/ui/src/menu.js

@@ -11,6 +11,7 @@ export const FORM_MENU_PREFIX = 'form:'
 export const APP_MENU_KEYS = [
   'Home',
   'Tasks',
+  'Flows',
 __MT_MENU_KEY__
   'Admin',
   'Configure UI'

package/templates/ui/src/pages/ConfigureUI.jsx

@@ -6,6 +6,8 @@
 //          countries. Ordinary forms with a flag, gathered in one place because
 //          that is what they are: reference data, not daily work
 //   Menu   the side rail's items: rename, reorder, hide
+//   Flows  forms one after another — what is filled in decides the next; run by
+//          Xeplr Workflow, and says how to connect it until it is
 //
 // Configuration lives here, not in the side rail — the rail is for the pages
 // people use.
@@ -13,10 +15,12 @@ import { useSearchParams } from 'react-router-dom'
 import Forms from './Forms.jsx'
 import Masters from './Masters.jsx'
 import MenuSettings from './MenuSettings.jsx'
+import Flows from './Flows.jsx'
 
 const TABS = [
   { id: 'forms', label: 'Forms', Page: Forms },
   { id: 'masters', label: 'Masters', Page: Masters },
+  { id: 'flows', label: 'Flows', Page: Flows },
   { id: 'menu', label: 'Menu', Page: MenuSettings }
 ]
 

package/templates/ui/src/pages/EditTask.jsx

@@ -18,8 +18,8 @@ import { factory } from '../api/factory.js'
 //
 // ctx.screen says which screen is calling ("task_list" or "task_edit").
 // Keep them as methods (save(values, ctx) { … }) — super does not work in
-// arrow functions. Rules that must hold belong in the server's hooks
-// (api/screens/task/task.hooks.js).
+// arrow functions. Rules that must hold belong in a server function
+// (api/functions/), named in the screen's events.
 export class TaskHooks extends FactoryHooks {
   /** A list's rows (ctx.many), or the record Edit opens (ctx.id). */
   get(ctx) {
@@ -82,7 +82,7 @@ export default function EditTask({ record }) {
     factory.loadScreen('task_edit').then(setScreen, (e) => setError(e.message))
   }, [])
 
-  // The record as it is NOW, through the server's get hooks — not a copy the
+  // The record as it is NOW, through the server's events — not a copy the
   // list happened to have.
   useEffect(() => {
     if (record || !id || id === 'new') return

package/templates/ui/src/pages/FlowDesigner.jsx

@@ -0,0 +1,30 @@
+// ONE FLOW, DESIGNED — /configure/flows/<key>.
+//
+// @xeplr/ui-factory's designer: the flow's screens down the left; for the one
+// picked, its Form design (the screen's own builder) and its Events &
+// navigation — this app's functions (api/functions/) picked by name for each
+// event, and where the journey goes once the screen is saved. The selected
+// step and tab live in the address (?flowSelected=…&flowTab=…), so a reload or
+// a shared link opens the same place.
+//
+// Everything it needs comes from the two API clients — the wiring lives in
+// the package, so an upgrade reaches this app.
+import { useNavigate, useParams } from 'react-router-dom'
+import { FlowDesignerPage } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+import { flows } from '../api/flows.js'
+
+export default function FlowDesigner() {
+  const { flow } = useParams()
+  const navigate = useNavigate()
+  return (
+    <div className="app-designer">
+      <div className="app-designer-bar">
+        <button type="button" className="app-btn app-btn-quiet" onClick={() => navigate('/configure?tab=flows')}>← Flows</button>
+      </div>
+      <div className="app-designer-canvas">
+        <FlowDesignerPage factory={factory} flows={flows} flowKey={flow} urlKey="flow" />
+      </div>
+    </div>
+  )
+}

package/templates/ui/src/pages/Flows.jsx

@@ -0,0 +1,106 @@
+// CONFIGURE UI → FLOWS — every journey across the app's forms.
+//
+// A flow is what someone is walked through: screens one after another. For
+// each screen it says what runs around its records (its events — this app's
+// functions, picked by name) and where the journey goes once it is saved: a
+// screen, a function that decides, or the end. @xeplr/workflow-api runs it,
+// inside this app's API, so a journey can be left and picked up later.
+//
+// A flow is addressed by a key made from its name — /configure/flows/<key> to
+// design it, /journey/<key> to walk it.
+import { useEffect, useState } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+import { flowKey } from '@xeplr/ui-factory'
+import { flows } from '../api/flows.js'
+
+export default function Flows() {
+  const [list, setList] = useState(null)
+  const [error, setError] = useState(null)
+  const [offline, setOffline] = useState(null)   // API_NOT_RESTARTED
+  const [name, setName] = useState('')
+  const navigate = useNavigate()
+
+  const load = () => flows.listFlows().then(setList, (e) => {
+    const off = flowsOffline(e)
+    if (off) setOffline(off)
+    else setError(e.message)
+  })
+  useEffect(() => { load() }, [])
+
+  const create = async (e) => {
+    e.preventDefault()
+    const label = name.trim()
+    if (!label) return
+    try {
+      // No steps yet: the designer is where those come from, and it opens on
+      // the flow this creates. `key` is what every link to it uses from here on.
+      const made = await flows.createFlow({ key: flowKey(label), name: label })
+      navigate(`/configure/flows/${made.key}`)
+    } catch (err) {
+      setError(err.message)
+    }
+  }
+
+  if (offline) return <NotConnected offline={offline} />
+
+  return (
+    <div className="app-forms">
+      <p className="app-page-lead">
+        A flow is your forms, one after another. For each one, pick what runs around its records and
+        where the journey goes next — a screen, one of the app’s functions, or the end.
+      </p>
+      {error && <div className="app-error">{error}</div>}
+
+      <form className="app-forms-new" onSubmit={create}>
+        <label className="app-forms-field">
+          <span>Name</span>
+          <input value={name} onChange={(e) => setName(e.target.value)} placeholder="Employee registration" />
+        </label>
+        <button type="submit" className="app-btn" disabled={!name.trim()}>New flow</button>
+      </form>
+
+      {list && list.length === 0 && <p className="app-sub">No flows yet.</p>}
+      {list && list.length > 0 && (
+        <table className="app-table">
+          <thead><tr><th>Flow</th><th>Key</th><th>Status</th><th>Screens</th><th /></tr></thead>
+          <tbody>
+            {list.map((f) => (
+              <tr key={f.key}>
+                <td><strong>{f.name}</strong></td>
+                <td className="app-sub">{f.key}</td>
+                <td>{f.status}</td>
+                <td>{typeof f.steps === 'number' ? f.steps : (f.steps || []).length}</td>
+                <td className="app-row-actions">
+                  <Link to={`/configure/flows/${f.key}`}>Design</Link>
+                  {f.status === 'published' && <Link to={`/journey/${f.key}`}>Open</Link>}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Why flows cannot run right now, or null when the error is something else.
+ * Workflow runs inside this app's API, so there is one such case: an API
+ * started before flows existed (404 on /api/workflow) — restart it.
+ */
+export function flowsOffline(err) {
+  if (err && err.status === 404) return { code: 'API_NOT_RESTARTED', message: 'This app\'s API does not have the flows route yet.' }
+  return null
+}
+
+/** Flows before the API has been restarted with them. */
+export function NotConnected({ offline }) {
+  return (
+    <div className="app-forms">
+      <div className="app-connect">
+        <h2>Restart the API to use flows</h2>
+        <p>{offline.message} It was started before flows were added — restart it, then reload this page.</p>
+      </div>
+    </div>
+  )
+}

package/templates/ui/src/pages/FlowsHome.jsx

@@ -0,0 +1,65 @@
+// FLOWS — the side-rail page: the journeys people can start, one click each.
+//
+// Always in the rail. Flows are run by @xeplr/workflow inside this app's own
+// API, so they are simply there. Designing them is Configure UI → Flows.
+import { useEffect, useState } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+import { useAccess } from '@xeplr/ui-account'
+import { flows } from '../api/flows.js'
+import { NotConnected, flowsOffline } from './Flows.jsx'
+
+export default function FlowsHome() {
+  const [list, setList] = useState(null)
+  const [error, setError] = useState(null)
+  const [offline, setOffline] = useState(null)
+  const navigate = useNavigate()
+  const { access } = useAccess()
+  // Whoever may open Configure UI may design flows and connect Workflow.
+  const admin = ((access && access.menus) || []).includes('Configure UI')
+
+  useEffect(() => {
+    flows.listFlows().then(setList, (e) => {
+      const off = flowsOffline(e)
+      if (off) setOffline(off)
+      else setError(e.message)
+    })
+  }, [])
+
+  const published = (list || []).filter((f) => f.status === 'published')
+
+  return (
+    <div className="app-page">
+      <h1>Flows</h1>
+      <p className="app-page-lead">
+        Forms one after another — what you fill in on one decides which comes next. A journey you
+        leave is kept, and picks up where it stopped.
+      </p>
+      {offline && <NotConnected offline={offline} />}
+      {error && <div className="app-error">{error}</div>}
+      {list && published.length === 0 && (
+        <p className="app-sub">
+          No flows to start yet.{admin && <> <Link to="/configure?tab=flows">Design one</Link> in Configure UI.</>}
+        </p>
+      )}
+      {published.length > 0 && (
+        <table className="app-table">
+          <thead><tr><th>Flow</th><th>Screens</th><th /></tr></thead>
+          <tbody>
+            {published.map((f) => (
+              <tr key={f.key}>
+                <td><strong>{f.name}</strong></td>
+                <td>{typeof f.steps === 'number' ? f.steps : (f.steps || []).length}</td>
+                <td className="app-row-actions">
+                  <button type="button" className="app-btn" onClick={() => navigate(`/journey/${f.key}`)}>Start</button>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+      {admin && list && published.length > 0 && (
+        <p className="app-sub" style={{ marginTop: 16 }}><Link to="/configure?tab=flows">Design flows</Link> in Configure UI.</p>
+      )}
+    </div>
+  )
+}

package/templates/ui/src/pages/Journey.jsx

@@ -0,0 +1,33 @@
+// A FLOW, being walked through — /journey/<key>, and /journey/<key>/<run> once
+// it has started. The run id in the address is what lets a journey be
+// reloaded, left, or handed to someone else and opened on the step it is on.
+//
+// This page holds no route through the journey: Workflow says which screen
+// comes next, from what was filled in.
+import { useNavigate, useParams } from 'react-router-dom'
+import { FlowRunner } from '@xeplr/ui-factory'
+import { flows } from '../api/flows.js'
+import { factory } from '../api/factory.js'
+
+export default function Journey() {
+  const { flow, run } = useParams()
+  const navigate = useNavigate()
+  return (
+    <div className="app-page">
+      <FlowRunner
+        {...flows.runnerProps}
+        {...factory.screenProps}
+        flowKey={flow}
+        runId={run}
+        onStep={(step) => { if (step.runId && step.runId !== run) navigate(`/journey/${flow}/${step.runId}`, { replace: true }) }}
+        renderDone={() => (
+          <div className="app-help">
+            <h2>All done</h2>
+            <p>Everything in this journey is filled in.</p>
+            <button type="button" className="app-btn" onClick={() => navigate(`/journey/${flow}`)}>Start another</button>
+          </div>
+        )}
+      />
+    </div>
+  )
+}

package/templates/ui/src/pages/TasksHelp.jsx

@@ -63,7 +63,7 @@ export default function TasksHelp() {
       <h3>Or without code</h3>
       <p>
         <strong>Configure UI → Forms → New form</strong>: label and key, design,
-        publish, add to menu — no code. The full steps for a form with its own page, hooks and
+        publish, add to menu — no code. The full steps for a form with its own page, functions and
         model are in <code>CLAUDE.md</code>, under "Create a new UI".
       </p>
 
@@ -75,7 +75,8 @@ export default function TasksHelp() {
       </p>
       <p>
         On the server — a check against other records, an email afterwards, a
-        list only managers see: <code>api/screens/task/task.hooks.js</code>.
+        list only managers see: a function in <code>api/functions/</code>, registered by the event it
+        is for and named in the screen’s events — Tasks names <code>tidyTaskTitle</code>.
       </p>
 
       <h3>Two things that catch people</h3>

package/templates/ui/vite.config.js

@@ -44,7 +44,10 @@ export default defineConfig(({ mode }) => {
     // Force every import to THIS app's copy, so hook-using libraries don't
     // load twice and break the rules of hooks in ways that read as impossible.
     resolve: { dedupe: ['react', 'react-dom', 'react-router-dom', '@xeplr/ui-canvas', '@xeplr/ui-table'] },
-    server: { port, strictPort: true, proxy },
+    // 127.0.0.1, not 'localhost': Node resolves 'localhost' to IPv6 (::1)
+    // first, so the dev server listened on ::1 alone and a browser going to
+    // 127.0.0.1 was refused.
+    server: { host: '127.0.0.1', port, strictPort: true, proxy },
     preview: { port, strictPort: true }
   }
 })

package/templates/api/screens/task/task.hooks.js

@@ -1,37 +0,0 @@
-// Server hooks for task records — screen "task_edit" (and "task_list", which edits in it).
-//
-// Register with @xeplr/factory:
-//   factory.init({ knex, hooks: { task_edit: require('./task.hooks') } })
-//
-// Each operation has four hooks. Delete the ones you do not need.
-//   before(ctx)       first — save: return new values to replace them (they are then checked
-//                     against the screen's rules); get: narrow ctx.query; any: ctx.reject(message, { field })
-//   after(ctx)        once it succeeded — ctx.id, ctx.result; return a value to replace the result.
-//                     If it throws, the operation still happened (and error is told).
-//   error(ctx, err)   when the operation failed
-//   override(ctx)     does the WHOLE operation instead — no rules, no before / after / error,
-//                     no generic query. What it returns is the response.
-//
-// ctx: op, screenKey, screen, table, id, isNew (save), many (get), input (what the UI sent, read-only),
-//      values (save), previous (save / delete: the row before), result, user, tenant, knex, query (get), reject
-
-module.exports = {
-  save: {
-    // before: async function(ctx) { return ctx.values },
-    // after: async function(ctx) {},
-    // error: async function(ctx, err) {},
-    // override: async function(ctx) { return savedRecord },
-  },
-  get: {
-    // before: async function(ctx) { /* ctx.query.where(...) */ },
-    // after: async function(ctx) { return ctx.result },
-    // error: async function(ctx, err) {},
-    // override: async function(ctx) { return ctx.id ? record : records },
-  },
-  delete: {
-    // before: async function(ctx) {},
-    // after: async function(ctx) {},
-    // error: async function(ctx, err) {},
-    // override: async function(ctx) { return { id: ctx.id } },
-  }
-}