@xeplr/cli 0.1.11 → 0.2.0

package/README.md

@@ -41,9 +41,12 @@ 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, if you run Xeplr Workflow** — your forms one after another, where
-  what someone fills in decides the next screen. Designed in Configure UI →
-  Flows, walked at `/journey/<key>`, and resumable, since Workflow keeps the run.
+- **Flows, in every app** — your forms one after another, where what someone
+  fills in decides the next screen. Designed in Configure UI → Flows, walked at
+  `/journey/<key>`, and resumable. Run by `@xeplr/workflow` **inside the API**,
+  in the app's own database — nothing extra to start, no port, no setting. It
+  follows the app's tenancy (none, or the levels you chose) and never creates
+  companies or workspaces of its own.
 - **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,
@@ -198,16 +201,17 @@ no defaults, ever.
 | Super admin email | the account you sign in with |
 | Super admin password | its password |
 | Multi-tenant? | no — or the levels, outermost first: `company`, `company, workspace` |
-| Flows — is Xeplr Workflow running? | no — or its address (`http://localhost:19122`) and its backend folder. Yes adds **Configure UI → Flows**, a `/journey/<key>` page, and `/api/flows` forwarded to Workflow — and sets multi-tenancy to Workflow's own levels, company then workspace, since it keeps every journey inside both |
 | Database connection | host, port, user, password — or skip, and fill it in later |
 
 Encryption keys and signing secrets are **generated, never asked**.
 
-**Flows need Workflow to share the app's sign-in.** Workflow is a separate
-service, not a package the project installs: set its `AUTH_URL` and
-`AUTH_DB_NAME` to the new app's, and the app's sign-in service loads Workflow's
-access rules from the folder you gave. The generated README says exactly which
-values.
+**Flows, inside the API.** `@xeplr/workflow` is a dependency of `api/`, and
+`bin/www` starts it with `registerWorkflow` after the screens — in the app's
+own database (`DB_API`, its own migration record `workflow_migrations`), 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`).
 
 ## Licence
 

package/lib/generate/index.js

@@ -8,10 +8,6 @@ var TEMPLATES = path.join(__dirname, '..', '..', 'templates');
 // with the same path as one there replaces it.
 var TENANCY_TEMPLATES = path.join(__dirname, '..', '..', 'templates-tenancy');
 
-// Files that exist ONLY in an app connected to Xeplr Workflow — the route that
-// forwards flows to it, the designer, and the page a journey runs on.
-var FLOWS_TEMPLATES = path.join(__dirname, '..', '..', 'templates-flows');
-
 // Files whose names cannot ship as-is. `.env` and `.gitignore` are both
 // swallowed on the way here — npm refuses to pack a .gitignore, and an .env in
 // a published package is a mistake waiting to happen — so they travel under a
@@ -32,56 +28,51 @@ function substitutions(answers) {
     __UI_PORT__: String(answers.ports.ui),
     __AUTH_PORT__: String(answers.ports.auth),
     __API_PORT__: String(answers.ports.api),
+    // The port after the API's — suggested for a service run on its own (workflow).
+    __NEXT_PORT__: String(answers.ports.api + 1),
     __ENCRYPTION_KEY__: answers.secrets.encryptionKey,
     __JWT_SECRET__: answers.secrets.jwtSecret,
     __ADMIN_EMAIL__: answers.admin.email,
     __ADMIN_PASSWORD__: answers.admin.password,
     __DB_CONNECTION__: answers.connection || '',
     __CONNECTION_NOTE__: connectionNote(answers)
-  }, tenancySubstitutions(answers.tenancy || []), flowsSubstitutions(answers.workflow || null, answers));
+  }, tenancySubstitutions(answers.tenancy || []), flowsSubstitutions(answers));
 }
 
 /**
- * The lines an app connected to Xeplr Workflow has, and one without it does
- * not. Like tenancy, every token exists either way and expands to nothing when
- * flows are off, so no template needs a condition of its own.
+ * 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(workflow, answers) {
-  var on = Boolean(workflow);
+function flowsSubstitutions(answers) {
   return {
-    __WF_ENV__: on ? [
-      '# ── Flows (Xeplr Workflow) ──',
-      '# Your forms, one after another — Workflow runs the journey. It is a separate',
-      '# service: start it, and point it at THIS app\'s sign-in (see README, "Flows").',
-      'WORKFLOW_URL=' + workflow.url,
+    // Where workflow runs. Its database is DB_API with the app's login — no
+    // setting; only the port, and only to run it as its own service.
+    __WF_ENV__: [
+      '# ── Flows (@xeplr/workflow) ──',
+      '# BLANK: workflow runs INSIDE this API (npm run start-api) — nothing else to',
+      '# start. Set a port to run it as its OWN SERVICE (npm run start-workflow);',
+      '# then point /api/workflow at it: WORKFLOW_URL in ui/.env for local, nginx',
+      '# in production (README, "Production"). This app\'s next free port: ' + (answers.ports.api + 1) + '.',
+      'WORKFLOW_PORT=',
       ''
-    ].join('\n') : '',
-    // Workflow's access rules — who may design a flow, who may run one — are
-    // loaded by this app's sign-in service, after the app's own.
-    __WF_AUTH_MIGRATIONS__: on && workflow.dir ? ',' + workflow.dir + '/migrations-auth' : '',
-    __WF_REQUIRED_ENV__: on ? "  // Where Xeplr Workflow is — flows are forwarded to it.\n  'WORKFLOW_URL'," : '',
-    __WF_API_ROUTE__: on ? [
-      '// Flows go to Xeplr Workflow (WORKFLOW_URL), behind this app\'s own gate.',
-      "router.use('/api/flows', require('./flows'));"
-    ].join('\n') : '',
-    __WF_UI_IMPORTS__: on ? [
-      "import FlowDesigner from './pages/FlowDesigner.jsx'",
-      "import Journey from './pages/Journey.jsx'"
-    ].join('\n') : '',
-    __WF_UI_ROUTES__: on ? [
-      '        <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 />} />'
-    ].join('\n') : '',
-    __WF_TAB_IMPORT__: on ? "import Flows from './Flows.jsx'" : '',
-    __WF_TAB__: on ? "  { id: 'flows', label: 'Flows', Page: Flows }," : '',
-    __WF_TAB_NOTE__: on ? '//   Flows  forms one after another — what is filled in decides the next; run by Xeplr Workflow' : '',
-    __WF_README__: on ? flowsReadme(workflow, answers) : '',
-    __WF_CLAUDE__: on ? [
-      '**Flows** — forms one after another, run by Xeplr Workflow (`WORKFLOW_URL`). Design them in Configure UI → Flows, never in code: a flow is data in Workflow, reached through `/api/flows`, and walked at `/journey/<key>`. An arrow tests one field of the screen it leaves; a form that is a step must be published first.',
+    ].join('\n'),
+    __WF_UI_ENV__: [
+      '',
+      '# Where /api/workflow goes. BLANK: the API above (workflow runs inside it).',
+      '# Set it when api/development.env sets WORKFLOW_PORT — e.g.',
+      '# http://localhost:' + (answers.ports.api + 1),
+      'WORKFLOW_URL='
+    ].join('\n'),
+    // Workflow's permissions — who may design a flow, who may run one — load
+    // into this app's sign-in service after the app's own.
+    __WF_AUTH_MIGRATIONS__: ',./node_modules/@xeplr/workflow/migrations-auth',
+    __WF_README__: flowsReadme(answers),
+    __WF_CLAUDE__: [
+      '**Flows** — forms one after another, run by `@xeplr/workflow` INSIDE this API (bin/www starts it) and stored in this app\'s own database. Design them in Configure UI → Flows, never in code: a flow is data, reached through `/api/flows` (routes/flows.js), and walked at `/journey/<key>`. An arrow tests one field of the screen it leaves; a form that is a step must be published first. Workflow follows this app\'s tenancy — it never creates companies or workspaces of its own.',
       ''
-    ].join('\n') : ''
+    ].join('\n')
   };
 }
 
@@ -126,6 +117,8 @@ function tenancySubstitutions(levels) {
       "      '/api/tenants': tenants.router,"
     ].join('\n') : '',
     __MT_MEMBER_GATE__: on ? 'tenants.memberGate' : 'access.anyone',
+    // api/app.js — the request middleware bin/workflow runs as well.
+    __MT_MIDDLEWARE_LIST__: on ? '[mtMiddleware()]' : '[]',
     __MT_MEMBER_NOUN__: on ? levels.map(function (l) { return l.label.toLowerCase(); }).join(' and ') : 'data (no tenancy: nothing to check)',
 
     // ui/src/main.jsx
@@ -166,33 +159,23 @@ function tenancySubstitutions(levels) {
   };
 }
 
-/**
- * The README's Flows section — what a flow is, and the one thing that has to
- * be true for it to work: Workflow and this app share a sign-in.
- */
-function flowsReadme(workflow, answers) {
+/** The README's Flows section. */
+function flowsReadme(answers) {
+  var tenancy = answers.tenancy || [];
   return [
     '## Flows',
     '',
-    'Your forms, one after another: what someone fills in on one decides which comes next. Design one in **Configure UI → Flows**, publish it, and open it 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.',
+    'Your forms, one after another: what someone fills in on one decides which comes next. Design one in **Configure UI → Flows**, 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**, a separate service at `WORKFLOW_URL` (' + workflow.url + '). The API forwards `/api/flows/…` to it unchanged; each screen still saves into its own table.',
+    'Flows are run by **`@xeplr/workflow`**, which runs **inside this API** — `bin/www` starts it after the screens. Nothing else to start, no port, no setting:',
     '',
-    'Workflow keeps every journey inside a **company and a workspace** — the two levels it registers — which is why this app has exactly those: a flow is made, and a run started, in the company and workspace picked after signing in.',
-    '',
-    '**Workflow must use this app\'s sign-in.** In Workflow\'s own `development.env`:',
-    '',
-    '```sh',
-    'AUTH_URL=http://localhost:' + answers.ports.auth + '      # this app\'s sign-in service',
-    'AUTH_DB_NAME=' + answers.name + '_auth               # and its database',
-    'REDIS_PREFIX=' + answers.name + ':',
-    '```',
-    '',
-    'If Workflow\'s database server is not this app\'s, also set `AUTH_DB_CONNECTION_INFO_ENCRYPTED` in Workflow to this app\'s server, encrypted with **Workflow\'s** `ENCRYPTION_KEY` (`npm run db:encrypt` in Workflow\'s backend). Otherwise every flow call fails with *database "' + answers.name + '_auth" does not exist*.',
-    '',
-    workflow.dir
-      ? 'Its access rules — who may design a flow, who may run one — are loaded by this app\'s sign-in service from `' + workflow.dir + '/migrations-auth` (in `XEPLR_AUTH_MIGRATIONS`). Restart the sign-in service after changing it.'
-      : 'Its access rules — who may design a flow, who may run one — live in Workflow\'s `backend/migrations-auth`. Add that folder to `XEPLR_AUTH_MIGRATIONS` in `api/development.env` (comma separated, after `./migrations-auth`) and restart the sign-in service; until then, flows answer 403.',
+    '| | |',
+    '|---|---|',
+    '| **Database** | this app\'s own (`DB_API`). Workflow\'s tables (`workflows`, `workflow_steps`, `workflow_runs`…) sit beside the forms\' tables, and it keeps its own record of which of its migrations ran (`workflow_migrations`). Each screen still saves into its own table. |',
+    '| **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 to Super Admin, CompanyAdmin, Creator and — read only — Viewer by `@xeplr/workflow`\'s `migrations-auth`, which `XEPLR_AUTH_MIGRATIONS` loads. |',
     ''
   ].join('\n');
 }
@@ -309,15 +292,6 @@ function generate(answers, target) {
     throw new Error(target + ' already exists and is not empty.');
   }
 
-  // Workflow files every flow and run under a company; an app without
-  // companies would build, start, and then refuse every flow it tried to make.
-  if (answers.workflow) {
-    var q = require('../questions');
-    if (!q.sameLevels(answers.tenancy || [], q.tenancyLevels(q.WORKFLOW_LEVELS))) {
-      throw new Error('Flows need the same multi-tenancy as Xeplr Workflow — levels "' + q.WORKFLOW_LEVELS + '" — because Workflow keeps every journey inside a company and a workspace.');
-    }
-  }
-
   var subs = substitutions(answers);
   var written = [];
 
@@ -326,9 +300,6 @@ function generate(answers, target) {
   if (answers.tenancy && answers.tenancy.length) {
     walk(TENANCY_TEMPLATES).forEach(function (src) { sources[path.relative(TENANCY_TEMPLATES, src)] = src; });
   }
-  if (answers.workflow) {
-    walk(FLOWS_TEMPLATES).forEach(function (src) { sources[path.relative(FLOWS_TEMPLATES, src)] = src; });
-  }
 
   Object.keys(sources).forEach(function (rel) {
     var src = sources[rel];

package/lib/questions.js

@@ -135,38 +135,8 @@ async function collect(session, argvName) {
   }
 
   // ── flows ─────────────────────────────────────────────────────────────
-  //
-  // Screens one after another, where what someone filled in decides the next
-  // screen. The journey is run by Xeplr Workflow — a separate service, not a
-  // package — so this only asks where it is. Off, the app has no flows at all.
-  var workflow = null;
-  var wantsFlows = await session.confirm('Flows — is Xeplr Workflow running for this app?', false);
-  if (wantsFlows) {
-    var workflowUrl = await session.ask('  Workflow API address?', {
-      default: 'http://localhost:19122',
-      validate: function (v) { return /^https?:\/\/[^\s]+$/.test(v) ? true : 'An http:// or https:// address.'; }
-    });
-    // Workflow keeps its access rules (who may design a flow, who may run one)
-    // in migrations-auth/. This app's sign-in service has to load them, so it
-    // needs to know where they are. Blank is allowed: the README says how.
-    var workflowDir = await session.ask('  Workflow backend folder (for its access rules — blank to add later)?', {
-      default: '',
-      validate: function (v) { return !v || !/\s/.test(v) ? true : 'A path without spaces.'; }
-    });
-    workflow = { url: workflowUrl.replace(/\/+$/, ''), dir: workflowDir.replace(/\/+$/, '') };
-
-    // Workflow files every flow and every run under a company and a workspace
-    // — the two levels it registers, with those headers. An app that sends
-    // anything else builds, starts, and then has every flow refused, so the
-    // levels that make flows work are set here, and said out loud.
-    if (!sameLevels(tenancy, tenancyLevels(WORKFLOW_LEVELS))) {
-      tenancy = tenancyLevels(WORKFLOW_LEVELS);
-      if (session.say) {
-        session.say('  Flows need the same tenancy as Xeplr Workflow — company, then workspace —');
-        session.say('  so this app uses those two levels.');
-      }
-    }
-  }
+  // Nothing to ask: every app has flows, run by @xeplr/workflow inside its own
+  // API and database (see lib/generate's flowsSubstitutions).
 
   // ── the database ──────────────────────────────────────────────────────
   //
@@ -208,7 +178,6 @@ async function collect(session, argvName) {
     databases: { auth: name + '_auth', api: name + '_api' },
     admin: { email: adminEmail, password: adminPassword },
     tenancy: tenancy,
-    workflow: workflow,
 
     // GENERATED, never asked. Nobody should be inventing these by hand, and a
     // prompt invites a weak answer or a reused one.
@@ -216,12 +185,4 @@ async function collect(session, argvName) {
   };
 }
 
-/** The tenancy Xeplr Workflow registers: a flows app must send the same headers. */
-var WORKFLOW_LEVELS = 'company, workspace';
-
-/** Same levels, in the same order, with the same headers. */
-function sameLevels(a, b) {
-  return a.length === b.length && a.every(function (l, i) { return l.header === b[i].header; });
-}
-
-module.exports = { collect: collect, envPrefix: envPrefix, tenancyLevels: tenancyLevels, sameLevels: sameLevels, WORKFLOW_LEVELS: WORKFLOW_LEVELS, NAME_RE: NAME_RE };
+module.exports = { collect: collect, envPrefix: envPrefix, tenancyLevels: tenancyLevels, NAME_RE: NAME_RE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/cli",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "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

@@ -11,7 +11,7 @@ A new UI is a **form**: a list, and an add / edit form it opens — on a page of
 
 Create every file below — the hooks and the model run the defaults (`super`) until the request needs more.
 
-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.
+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/`:
    ```sh
    npx xeplr-factory screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages
@@ -22,10 +22,10 @@ Create every file below — the hooks and the model run the defaults (`super`) u
 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`.
 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, clickHandler }` — by **key**, with an **icon** (a collapsed rail shows icons only). Never write the label in code.
+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.
 7. **The menu row** — `api/migrations-auth/000N_<forms>_menu.sql` (next free number): copy `0002_tasks_menu.sql`, its `name` being the **key** spelled exactly as in `drawerItems` — an unknown key is dropped silently. Set `label` only if it should read differently; people can rename it later in Configure UI → Menu. Then, in `api/`: `npm run migrate:auth`, and restart the sign-in service.
 8. **Restart the API.** It publishes screens that were never published — creating the table — and logs `[api] published screens: <form>_edit, <form>_list`.
-9. **Check** — open the page, New, fill in the form; the popup says "All changes saved" and the row is in the table.
+9. **Check** — open the page, New, fill in the form and press **Save**; it goes back to the list and the row is in the table.
 
 Then change only what the request asks for:
 
@@ -47,7 +47,7 @@ Then change only what the request asks for:
 - **`file`** — the column holds the **path**, never the file. Say which extensions (`"accept": ".pdf,.docx"`) and how large (`"maxSize": 10`, in MB); the API enforces both, by extension, and keeps the file under `FACTORY_FILES_DIR`. Uploading needs `multer` in `api/` (already in package.json).
 - **`stepper`** — a journey across the top. Every other field says which step it is on (`"step": "Planning"`), and one without a `step` shows on every step. `step(ctx)` in the front-end hooks runs before each move: return `false` to stay, a step's key to go there, `ctx.disable(['planning'])` to rule steps out (struck through on the bar, passed over by Next and Back) and `ctx.enable()` to bring them back.
 
-**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 Done goes back to): `Tasks.jsx` and `EditTask.jsx` show both, with routes `/tasks/new` and `/tasks/:id` in `App.jsx`.
+**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.

package/templates/README.md

@@ -21,6 +21,56 @@ 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) run **inside the API** — nothing else to start. To run
+them as their own service instead, see "Where each address goes" below.
+
+## Where each address goes
+
+The browser only ever calls **paths** on the app's own address — never a port.
+What serves each path is decided in ONE place per environment: Vite's dev proxy
+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` | `WORKFLOW_URL`, or `API_URL` when blank | the workflow process, or the API when it runs inside |
+| `/api/…`, `/health`, `/whoami` | the API | `API_URL` | `127.0.0.1:<__PREFIX___PORT>` |
+
+**Workflow on its own port.** Set `WORKFLOW_PORT` in `api/development.env`
+(this app's next free port is __NEXT_PORT__), set `WORKFLOW_URL` in `ui/.env` to
+`http://localhost:__NEXT_PORT__`, and start it beside the API:
+
+```bash
+cd api && npm run start-workflow   # flows            http://localhost:__NEXT_PORT__
+```
+
+Same database, same sign-in, same permissions and the same `/api/workflow/…`
+paths — only the process differs. Leave `WORKFLOW_PORT` blank and it runs inside
+the API again.
+
+### Production
+
+`api/production.env.example` lists every setting (copy it to
+`api/production.env`, fill in, start with `NODE_ENV=production`). Build the UI
+(`cd ui && npm run build`) and let nginx serve it and route the paths — the
+more specific `/api/workflow/` first:
+
+```nginx
+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/workflow/ { proxy_pass http://127.0.0.1:__API_PORT__; }   # or WORKFLOW_PORT when it runs on its own
+  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
+}
+```
+
+Every one of these checks the same sign-in token, so one login covers them all.
+
 ## What is in it
 
 - **Sign-in** — login, register, password reset, profile, and the admin screens for users, roles and permissions (`@xeplr/auth`, `@xeplr/ui-account`).

package/templates/api/app.js

@@ -12,7 +12,13 @@ var memberGate = __MT_MEMBER_GATE__;
 // default could only ever fire in a process that skipped that check.
 var port = process.env.__PREFIX___PORT;
 
-module.exports = function buildApp(extraRoutes) {
+module.exports = buildApp;
+// bin/www and bin/workflow hand the same gate to the flows router they start,
+// and bin/workflow runs the same request middleware (tenancy) as this app.
+module.exports.memberGate = memberGate;
+module.exports.middleware = function() { return __MT_MIDDLEWARE_LIST__; };
+
+function buildApp(extraRoutes) {
   return createApp(port, '__NAME___api', {
     // Every route needs a valid token, checked against the auth service at
     // AUTH_URL. This app names no `middleware` of its own — it takes the
@@ -48,4 +54,4 @@ __MT_APP_ROUTES__
       })
     })
   });
-};
+}

package/templates/api/bin/workflow

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// XEPLR WORKFLOW AS ITS OWN SERVICE — `npm run start-workflow`.
+//
+// Only when WORKFLOW_PORT is set (development.env / production.env). Blank, it
+// runs inside the API instead and this refuses to start, saying so.
+//
+// The SAME workflow as the embedded one (../workflow.js): this app's database,
+// this app's tenancy and membership gate, the same permission checks, and the
+// same path — /api/workflow/flows — so the browser cannot tell the two apart.
+// What routes /api/workflow here: ui/.env WORKFLOW_URL for Vite's dev proxy,
+// nginx in production (README, "Production").
+require('dotenv').config({ path: require('path').join(__dirname, '..', (process.env.NODE_ENV || 'development') + '.env') });
+
+if (!process.env.WORKFLOW_PORT) {
+  console.error('\n[workflow] WORKFLOW_PORT is blank — workflow runs INSIDE the API (npm run start-api).');
+  console.error('  To run it as its own service, set WORKFLOW_PORT in development.env,');
+  console.error('  and WORKFLOW_URL in ui/.env to http://localhost:<that port>.\n');
+  process.exit(1);
+}
+
+require('@xeplr/base-apis').checkEnv(require('../env.required.js'), { appName: 'workflow' });
+
+var express = require('express');
+var createApp = require('@xeplr/base-apis/express');
+
+async function start() {
+  // This app's tenancy levels, registered exactly as the API registers them.
+  await require('../db/setup');
+  var app = require('../app');
+  var flowsRouter = await require('../workflow')(app.memberGate);
+
+  var health = express.Router();
+  health.get('/', function(req, res) { res.json({ status: 'ok', service: 'workflow' }); });
+
+  createApp(process.env.WORKFLOW_PORT, '__NAME___workflow', {
+    // Every route needs a valid token, checked against the same sign-in
+    // service as the API — one login for both.
+    auth: { publicPaths: ['/health'] },
+    log: { logDir: process.env.LOG_DIR || './logs' },
+    middleware: app.middleware(),
+    routes: {
+      '/health': health,
+      '/api/workflow/flows': flowsRouter
+    }
+  });
+}
+
+start().catch(function(err) {
+  console.error('[workflow] startup failed:', err.stack || err.message);
+  process.exit(1);
+});

package/templates/api/bin/www

@@ -76,7 +76,21 @@ 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, inside this API and in this app's own database
+  // (routes/flows.js says why). It creates its tables on first start, keeps its
+  // own migration record, and follows this app's tenancy instead of creating
+  // companies / workspaces of its own.
+  var buildApp = require('../app');
+  // WORKFLOW_PORT set: it runs as its own service (npm run start-workflow),
+  // and this API leaves it alone.
+  if (process.env.WORKFLOW_PORT) {
+    console.log('[api] flows: workflow runs on its own port ' + process.env.WORKFLOW_PORT + ' (npm run start-workflow)');
+    buildApp();
+    return;
+  }
+  require('../routes/flows').mount(await require('../workflow')(buildApp.memberGate));
+
+  buildApp();
 }
 
 start().catch(function(err) {

package/templates/api/env.required.js

@@ -26,5 +26,4 @@ module.exports = [
   // error — the most expensive way for this to go wrong.
   'DB_API',
   '__PREFIX___CONNECTION',
-__WF_REQUIRED_ENV__
 ];

package/templates/api/gitignore.tpl

@@ -1,4 +1,9 @@
 node_modules/
 logs/
+# Settings hold this app's keys, secrets and database login — never committed.
+# production.env.example lists every name, with no values.
+development.env
+production.env
+*.local.env
 # Files people upload through a form's file field (FACTORY_FILES_DIR).
 uploads/

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

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "license": "UNLICENSED",
-  "description": "__NAME__ backend — @xeplr/base-apis app.",
+  "description": "__NAME__ backend \u2014 @xeplr/base-apis app.",
   "main": "app.js",
   "scripts": {
     "check-env": "dotenv -e development.env -- xeplr-check-env",
@@ -14,7 +14,8 @@
     "migrate:auth": "dotenv -e development.env -- xeplr-auth-migrate up --connection-env AUTH_DB_CONNECTION_INFO_ENCRYPTED",
     "migrate:up": "dotenv -e development.env -- xeplr-migrate up --dir ./migrations --connectionName api --connection-env __PREFIX___CONNECTION",
     "start-auth": "dotenv -e ./development.env -- xeplr-auth-server",
-    "start-api": "node ./bin/www"
+    "start-api": "node ./bin/www",
+    "start-workflow": "node ./bin/workflow"
   },
   "dependencies": {
     "@xeplr/auth": "^1.1.4",
@@ -23,6 +24,7 @@
     "@xeplr/factory": "^1.0.6",
     "@xeplr/ui-factory": "^1.0.14",
     "@xeplr/utils": "^1.0.11",
+    "@xeplr/workflow": "^1.1.0",
     "dotenv": "^17.4.2",
     "express": "^5.2.0",
     "multer": "^2.0.2"

package/templates/api/production.env.example

@@ -0,0 +1,39 @@
+# __NAME__ API — PRODUCTION settings. Copy to production.env on the server
+# and fill in; start with NODE_ENV=production (bin/www and bin/workflow read
+# <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.
+
+NODE_ENV=production
+LOG_DIR=./logs
+
+# ── Ports: one per process on this server ──
+__PREFIX___PORT=__API_PORT__
+AUTH_PORT=__AUTH_PORT__
+# Blank: workflow runs inside the API. Set: it runs as its own process
+# (npm run start-workflow) and nginx sends /api/workflow to it.
+WORKFLOW_PORT=
+
+# ── Databases (same server, one login) ──
+ENCRYPTION_KEY=
+__PREFIX___CONNECTION=
+AUTH_DB_CONNECTION_INFO_ENCRYPTED=
+DB_API=__NAME___api
+AUTH_DB_NAME=__NAME___auth
+
+# ── 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,./node_modules/@xeplr/workflow/migrations-auth
+AUTH_SUPER_ADMIN_EMAIL=
+AUTH_SUPER_ADMIN_PASSWORD=
+
+# ── Public addresses (what people's browsers open) ──
+AUTH_ACTIVATION_URL=https://app.example.com/auth/activate
+AUTH_INVITE_URL=https://app.example.com/auth/accept-invite
+
+# ── Uploaded files — an absolute path on the server ──
+FACTORY_FILES_DIR=/var/lib/__NAME__/uploads/factory

package/templates/api/routes/flows.js

@@ -0,0 +1,43 @@
+// FLOWS — screens one after another, run by Xeplr Workflow (@xeplr/workflow).
+//
+// WHERE IT RUNS. By default INSIDE THIS API, in this app's own database:
+// bin/www starts it (registerWorkflow) after the screens and plugs its flows
+// router in here. With WORKFLOW_PORT set in development.env / production.env it
+// runs as its own service instead (npm run start-workflow → bin/workflow), at
+// the SAME path — /api/workflow/flows — and this route answers 404 so a
+// misrouted request says where it should have gone. The front door routes
+// /api/workflow to it: ui/.env WORKFLOW_URL for Vite, nginx in production.
+//
+//   ONE DATABASE     workflow's tables (workflows, workflow_steps,
+//                    workflow_runs…) sit beside the forms' tables, with their
+//                    own migration record (workflow_migrations).
+//   THIS APP'S       embedded workflow registers no tenancy of its own. Its
+//   TENANCY          rows are filtered by the levels this app registered — or
+//                    none, in an app without tenancy — and the membership gate
+//                    below is the app's own. It never creates companies or
+//                    workspaces tables.
+//   PERMISSIONS      every route checks the caller's permissions ("List flows",
+//                    "Start flow run"…), granted by @xeplr/workflow's
+//                    migrations-auth — in XEPLR_AUTH_MIGRATIONS.
+//
+// Mounted by routes/index.js at /api/workflow/flows, behind this app's auth gate.
+var express = require('express');
+
+var router = express.Router();
+var flows = null;
+
+router.use(function(req, res, next) {
+  if (process.env.WORKFLOW_PORT) {
+    return res.status(404).json({ message: 'Workflow runs on its own port (WORKFLOW_PORT) — route /api/workflow there (ui/.env WORKFLOW_URL, or nginx)' });
+  }
+  // Only before startup has finished — bin/www mounts it before listening.
+  if (!flows) return res.status(503).json({ message: 'Flows are still starting' });
+  return flows(req, res, next);
+});
+
+/** bin/www hands over registerWorkflow's flowsRouter, already gated. */
+router.mount = function(flowsRouter) {
+  flows = flowsRouter;
+};
+
+module.exports = router;

package/templates/api/routes/index.js

@@ -34,6 +34,9 @@ router.get('/whoami', function(req, res) {
 //   var { genericRoute } = require('@xeplr/base-apis');
 //   router.use('/api/things', genericRoute({ key: 'thing', model: require('../models').Thing }));
 
-__WF_API_ROUTE__
+// Flows: Xeplr Workflow, at /api/workflow/flows — inside this API, or on its
+// own port with WORKFLOW_PORT (see routes/flows.js). The path is the same
+// either way: the browser never knows which.
+router.use('/api/workflow/flows', require('./flows'));
 
 module.exports = router;

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

@@ -77,7 +77,7 @@
       "z": 4,
       "props": {
         "label": "Status",
-        "placeholder": "Select…",
+        "placeholder": "Select\u2026",
         "data": {
           "source": "static",
           "options": [
@@ -109,7 +109,7 @@
       "x": 0.5125,
       "y": 0.4,
       "w": 0.4475,
-      "h": 0.065,
+      "h": 0.08,
       "z": 5,
       "props": {
         "label": "Priority",

package/templates/api/workflow.js

@@ -0,0 +1,27 @@
+// FLOWS — how @xeplr/workflow starts, in ONE place, for both ways it runs:
+//
+//   inside the API     bin/www calls this when WORKFLOW_PORT is blank
+//   its own service    bin/workflow (npm run start-workflow) when it is set
+//
+// Either way: this app's own database (its tables beside the forms', with its
+// own migration record), this app's tenancy (it creates no companies or
+// workspaces of its own), and a permission check on every route — granted by
+// @xeplr/workflow's migrations-auth, which XEPLR_AUTH_MIGRATIONS loads.
+var { registerWorkflow } = require('@xeplr/workflow');
+
+/** Runs workflow's migrations, and returns its flows router — already gated. */
+module.exports = async function startWorkflow(memberGate) {
+  var workflow = await registerWorkflow({
+    applicationId: '__NAME__',
+    db: {
+      name: process.env.DB_API,
+      connection: process.env.__PREFIX___CONNECTION,
+      connectionName: 'workflow',
+      migrationsTable: 'workflow_migrations'
+    },
+    tenantTables: false,
+    access: true,
+    mtMembershipGate: memberGate
+  });
+  return workflow.flowsRouter;
+};

package/templates/ui/README.md

@@ -24,5 +24,6 @@ npm run build     # → dist/
 ## Rules
 
 - `authFetch` returns the **parsed body**, not a Response — no `.json()`.
-- A side-rail item needs an **icon** (a collapsed rail shows icons only) and its key must exist as a menu row, or it is dropped silently.
+- A side-rail item needs an **icon** (a collapsed rail shows icons only) and its key must exist as a menu row, or it is dropped silently. Give it its **`path`** too: that is how the rail marks the page you are on.
+- The rail is 48px when collapsed; `--app-rail-width` in `src/index.css` reserves the same space and must match it.
 - Set page backgrounds on a container inside the theme, never on `body`.

package/templates/ui/dotenv.tpl

@@ -1,4 +1,4 @@
-# __NAME__ UI — dev port and the two services it talks to.
+# __NAME__ UI — dev port and the services it talks to.
 #
 # Read by vite.config.js, so no port is written in code. Change a number here
 # and the dev server and every proxy target follow.
@@ -6,3 +6,4 @@
 UI_PORT=__UI_PORT__
 AUTH_URL=http://localhost:__AUTH_PORT__
 API_URL=http://localhost:__API_PORT__
+__WF_UI_ENV__

package/templates/ui/src/App.jsx

@@ -4,7 +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'
-__WF_UI_IMPORTS__
+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'
@@ -22,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">
@@ -64,14 +75,19 @@ function Shell() {
   // The drawer's catalog, by KEY. A key must match a `menus` row's name —
   // @xeplr/ui-account drops unknown keys SILENTLY, so a typo removes the item
   // with no error anywhere. The text shown is the row's label (Configure UI →
-  // Menu), in the order set there — never written here.
+  // Menu), in the order set there — never written here. `path` is how the rail
+  // marks the page you are on (and /tasks/12 still counts as Tasks).
   const drawerItems = useMemo(() => [
-    { key: 'Home', icon: HomeIcon, clickHandler: () => navigate('/home') },
-    { key: 'Tasks', icon: TasksIcon, clickHandler: () => navigate('/tasks') },
+    { 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) => ({
-      key, icon: FormsIcon, clickHandler: () => navigate('/forms/' + key.slice(FORM_MENU_PREFIX.length))
+      key, icon: FormsIcon,
+      path: '/forms/' + key.slice(FORM_MENU_PREFIX.length),
+      clickHandler: () => navigate('/forms/' + key.slice(FORM_MENU_PREFIX.length))
     }))
   ], [navigate, menus])
 
@@ -113,7 +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 />} />
-__WF_UI_ROUTES__
+        {/* 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,8 @@
+// Flows are at /api/workflow/flows — served by @xeplr/workflow inside this
+// app's API, or on its own port; the dev proxy (vite.config.js) and nginx
+// decide which, never this file. 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

@@ -5,8 +5,9 @@
      of the page rather than pushing it along — the app has to leave the room
      itself. Without this the rail covers the first 60px of every screen, which
      reads as text mysteriously cut off down the left edge rather than as a
-     layout problem. */
-  --app-rail-width: 60px;
+     layout problem. 48px: compact, like VS Code's activity bar — it must
+     match @xeplr/ui-account's collapsed rail. */
+  --app-rail-width: 48px;
 }
 
 body { margin: 0; }
@@ -357,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

@@ -3,18 +3,19 @@
 //   Forms  every UI in the app: make one, design it, publish it, open it, add it
 //          to the side rail
 //   Menu   the side rail's items: rename, reorder, hide
-__WF_TAB_NOTE__
+//   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.
 import { useSearchParams } from 'react-router-dom'
 import Forms from './Forms.jsx'
 import MenuSettings from './MenuSettings.jsx'
-__WF_TAB_IMPORT__
+import Flows from './Flows.jsx'
 
 const TABS = [
   { id: 'forms', label: 'Forms', Page: Forms },
-__WF_TAB__
+  { id: 'flows', label: 'Flows', Page: Flows },
   { id: 'menu', label: 'Menu', Page: MenuSettings }
 ]
 

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

@@ -26,7 +26,7 @@ export class TaskHooks extends FactoryHooks {
     return super.get(ctx)
   }
 
-  /** Every autosave — keep it quick. Returns the saved record. */
+  /** The Save button — one AJAX call. Returns the saved record. */
   save(values, ctx) {
     return super.save(values, ctx)
   }
@@ -65,11 +65,11 @@ export const taskHooks = new TaskHooks()
 
 /**
  * The task form on a page of its own — /tasks/new, or /tasks/:id for a task
- * that exists. The list sends people here (its "Opens in" is a page), and
- * Done brings them back.
+ * that exists. The list sends people here (its "Opens in" is a page).
  *
- * There is no Save button: the form saves itself a moment after each change.
- * Done only waits for anything still in flight, then leaves.
+ * Nothing is written while typing. Save sends the task (one AJAX call, never
+ * a form submit) and comes back to the list; Cancel comes back without
+ * saving, asking first if anything is unsaved. Both go through onDone.
  */
 export default function EditTask({ record }) {
   const { id } = useParams()

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

@@ -0,0 +1,37 @@
+// One flow, on the canvas: the published forms on the left, arrows between
+// them, and on the right what happens after the screen you picked. Saves
+// itself; Publish is what people then walk through.
+import { useEffect, useState } from 'react'
+import { useParams, Link } from 'react-router-dom'
+import { FlowBuilder } from '@xeplr/ui-factory'
+import { flows } from '../api/flows.js'
+import { factory } from '../api/factory.js'
+
+export default function FlowDesigner() {
+  const { flow: key } = useParams()
+  const [flow, setFlow] = useState(null)
+  const [screens, setScreens] = useState([])
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    flows.loadFlow(key).then(setFlow, (e) => setError(e.message))
+    // A step is a FORM (an edit screen) that is published: what people will
+    // actually see, and something they can fill in.
+    factory.listScreens().then((rows) => setScreens(rows
+      .filter((s) => /_edit$/.test(s.screenKey) && s.version !== null)
+      .map((s) => ({ id: s.screenKey, name: s.name }))), () => {})
+  }, [key])
+
+  if (error) return <div className="app-page"><div className="app-error">{error}</div></div>
+  if (!flow) return null
+  return (
+    <div className="app-designer">
+      <div className="app-designer-bar">
+        <Link to="/configure?tab=flows">← All flows</Link>
+      </div>
+      <div className="app-designer-canvas">
+        <FlowBuilder {...flows.builderProps} flow={flow} screens={screens} loadScreen={factory.loadScreen} />
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,103 @@
+// CONFIGURE UI → FLOWS — every journey across the app's forms.
+//
+// A flow is screens one after another: what someone fills in on one decides
+// which comes next. It is run by Xeplr Workflow, so a journey can be left and
+// picked up later — by someone else, on another day. Design it here; open it
+// at /journey/<key>.
+//
+// Run by @xeplr/workflow inside this app's own API and database — nothing to
+// connect.
+import { useEffect, useState } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+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
+    const key = label.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+    try {
+      await flows.createFlow({ key, name: label })
+      navigate(`/configure/flows/${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 — what someone fills in decides the next one.
+        Xeplr Workflow runs it, so a journey can be left and picked up later.
+      </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 left: an API
+ * started before flows existed (404 on /api/flows) — 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/Tasks.jsx

@@ -1,6 +1,6 @@
 // THE SAMPLE — a list of tasks. New and Edit open the task form on a PAGE of
-// its own, where it saves itself as you type; there is no Save button, and
-// Done goes back here. (A list can open its form in a popup instead: Configure
+// its own. Its Save button saves over AJAX (never a form submit) and comes
+// back here; Cancel comes back without saving. (A list can open its form in a popup instead: Configure
 // UI → Forms → the list → Opens in.)
 //
 // Nothing about tasks is written in this file. The list and the form are

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

@@ -47,7 +47,8 @@ export default function TasksHelp() {
       </p>
       <p>
         <strong>New</strong> and <strong>Edit</strong> open the form on a page
-        of its own, and <strong>Done</strong> comes back here. A list can open
+        of its own. Nothing is saved while you type: <strong>Save</strong> saves
+        and comes back here, <strong>Cancel</strong> comes back without saving. A list can open
         it in a popup instead — that is its <strong>Opens in</strong> setting.
       </p>
 

package/templates/ui/vite.config.js

@@ -35,7 +35,13 @@ export default defineConfig(({ mode }) => {
     // Only the real network calls (/auth/api/*), NOT bare /auth — that prefix
     // is also used by client-side routes (/auth/login, /auth/profile), which
     // must fall through to Vite's SPA index.html rather than the auth backend.
-    '/auth/api': authUrl
+    '/auth/api': authUrl,
+    // A SERVICE THAT MAY RUN ON ITS OWN PORT, before the /api it sits under —
+    // the first matching prefix wins. Blank WORKFLOW_URL: it runs inside the
+    // API, so the API answers. The browser always calls /api/workflow/…; which
+    // process serves it is decided here (and by nginx in production), never in
+    // the UI's code.
+    '/api/workflow': env.WORKFLOW_URL || apiUrl
   }
   API_PATHS.forEach((p) => { proxy[p] = apiUrl })