@xeplr/cli 0.1.3 → 0.1.5

package/README.md

@@ -28,15 +28,24 @@ Already working, with nothing to wire up:
   table. Neither is written by hand: both are screens
   ([`@xeplr/ui-factory`](https://www.npmjs.com/package/@xeplr/ui-factory)),
   published when the API first starts.
-- **A Designer page** — move, add and restyle fields, then Publish; the table
-  gains its new columns as you do. Only the admin roles see it, and the API
-  refuses everyone else.
+- **A Forms page** for Super Admin — every form in the app; make a new one by
+  hand (no Claude needed), design its form and its list, publish (which creates
+  or changes its table), open it. Nobody else sees it, and the API refuses
+  everyone else.
 - **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,
   and choosing one is the first screen after signing in.
 - **A welcome screen** that checks it can reach everything and tells you which
   files to change first.
+- **A `CLAUDE.md`** that tells Claude how to create a new UI in this app — the
+  screens, the page with its front-end hooks, the server hooks and model, the
+  route and menu entry — and a ready prompt (also shown beside the sample):
+
+  > 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.
 
 ## Before you start
 

package/lib/generate/index.js

@@ -77,10 +77,8 @@ function tenancySubstitutions(levels) {
       '      // The ' + levels.map(function (l) { return l.table; }).join(' / ') + ' the picker lists and adds to.',
       "      '/api/tenants': tenants.router,"
     ].join('\n') : '',
-    __MT_FACTORY_AUTH__: on ? [
-      '        // …and only for a ' + first.label.toLowerCase() + ' the caller belongs to.',
-      '        auth: tenants.memberGate'
-    ].join('\n') : '',
+    __MT_MEMBER_GATE__: on ? 'tenants.memberGate' : 'access.anyone',
+    __MT_MEMBER_NOUN__: on ? levels.map(function (l) { return l.label.toLowerCase(); }).join(' and ') : 'data (no tenancy: nothing to check)',
 
     // ui/src/main.jsx
     __MT_UI_IMPORTS__: on ? [
@@ -96,7 +94,8 @@ function tenancySubstitutions(levels) {
 
     // ui/src/App.jsx
     __MT_APP_UI_IMPORTS__: on ? "import SelectScope, { ScopeGate } from './pages/SelectScope.jsx'" : '',
-    __MT_DRAWER_ITEM__: on ? "    { name: 'Switch " + first.label.toLowerCase() + "', icon: SwitchIcon, clickHandler: () => navigate('/select') }," : '',
+    __MT_MENU_KEY__: on ? "  'Switch " + first.label.toLowerCase() + "'," : '',
+    __MT_DRAWER_ITEM__: on ? "    { key: 'Switch " + first.label.toLowerCase() + "', icon: SwitchIcon, clickHandler: () => navigate('/select') }," : '',
     __MT_SWITCH_ICON__: on ? [
       'const SwitchIcon = (',
       '  <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"',

package/lib/plan.js

@@ -30,6 +30,7 @@ function describe(answers) {
   L.push('');
   L.push('  Settings written for you:');
   L.push('    ' + p + '_PORT, AUTH_PORT, AUTH_URL, DB_API, AUTH_DB_NAME');
+  L.push('    REDIS_PREFIX                            ' + answers.name + ':');
   L.push('    ENCRYPTION_KEY and AUTH_JWT_SECRET      generated, not asked');
   L.push('    AUTH_SUPER_ADMIN_EMAIL / _PASSWORD      from your answers');
   L.push('');

package/package.json

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

@@ -0,0 +1,59 @@
+# __NAME__
+
+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.
+
+## Create a new UI
+
+A new UI is a **form**: a list, and an add / edit form it opens 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.
+
+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.
+2. **Screens + server files** — from `api/`:
+   ```sh
+   npx xeplr-factory screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages
+   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`.
+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.
+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.
+
+Then change only what the request asks for:
+
+| the request says… | change |
+|---|---|
+| 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 | front-end hooks — `ui/src/pages/Edit<Form>.jsx` |
+| must / only if / check against / email when / only managers see | server hooks — `api/screens/<form>/<form>.hooks.js` |
+| 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.
+
+**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
+
+> 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.
+
+Replace the bold parts. Add behaviour in the same message if you want it — "a Mark active button on each row", "Region is required when Area is over 100", "store tags as an array".
+
+## Rules
+
+- **Records live in real tables, one column per field — never JSON.** A screen's design is the only JSON, in the `factory_screens` table.
+- **Never rename a field that is already a column** — it would drop the column and its data. Add a new field instead.
+- 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.
+- Hooks and models are **methods** calling `super` — never arrow-function properties.
+- `authFetch` returns the parsed body, not a Response.

package/templates/api/app.js

@@ -1,8 +1,13 @@
 var createApp = require('@xeplr/base-apis/express');
 var factory = require('@xeplr/factory');
 var routes = require('./routes');
+var access = require('./routes/access');
 __MT_APP_REQUIRE__
 
+// Every screen route first checks the caller may use the request's
+// __MT_MEMBER_NOUN__.
+var memberGate = __MT_MEMBER_GATE__;
+
 // No `|| __API_PORT__` fallback — the port is required in env.required.js, so a
 // default could only ever fire in a process that skipped that check.
 var port = process.env.__PREFIX___PORT;
@@ -23,7 +28,7 @@ __MT_APP_MIDDLEWARE__
       '/': routes,
 __MT_APP_ROUTES__
 
-      // THE SCREENS — every entity made with the Designer, one set of routes:
+      // THE SCREENS — every form, one set of routes:
       //   /api/factory/screens/...   designs: load, save draft, publish
       //   /api/factory/records/...   a screen's records: list, one, save, delete
       //
@@ -33,7 +38,13 @@ __MT_APP_ROUTES__
       // Viewer (read) by node_modules/@xeplr/factory/migrations-auth.
       '/api': factory.router({
         access: true,
-__MT_FACTORY_AUTH__
+        auth: {
+          view: memberGate,
+          write: memberGate,
+          // Designing, new forms and publishing change tables: Super Admin
+          // only (routes/access.js).
+          design: [memberGate, access.superAdminOnly]
+        }
       })
     })
   });

package/templates/api/bin/www

@@ -58,12 +58,13 @@ async function start() {
   // time has no connection at all until this has finished.
   var knex = await require('../db/setup');
 
-  // The screens. A hooks file with a typo ("beforeSave") stops startup here,
-  // rather than silently never running.
-  await factory.init({ knex: knex, hooks: screens.hooks });
+  // 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.
+  await factory.init({ knex: knex, hooks: screens.hooks, models: screens.models });
 
   // Screens never published yet are published now, creating their tables.
-  // Ones already published are left alone — the Designer owns them.
+  // Ones already published are left alone — Configure UI → Forms owns them.
   var published = await factory.publishScreens(screens.documents);
   if (published.published.length) console.log('[api] published screens: ' + published.published.join(', '));
 

package/templates/api/development.env.tpl

@@ -29,6 +29,11 @@ AUTH_DB_NAME=__NAME___auth
 # localhost:6379; set REDIS_HOST / REDIS_PORT to point elsewhere. Without it
 # the service refuses to start and says so — rather than letting every login
 # succeed and every request afterwards fail as "Invalid or expired token".
+#
+# REDIS_PREFIX keeps this app's keys apart from any other app on the same
+# Redis. Required, and unique per app: two apps sharing one see each other's
+# menus and permissions.
+REDIS_PREFIX=__NAME__:
 AUTH_PORT=__AUTH_PORT__
 AUTH_JWT_SECRET=__JWT_SECRET__
 

package/templates/api/env.required.js

@@ -9,7 +9,7 @@
  */
 module.exports = [
   // ENCRYPTION_KEY, AUTH_JWT_SECRET, AUTH_PORT, AUTH_DB_NAME,
-  // XEPLR_AUTH_MIGRATIONS
+  // XEPLR_AUTH_MIGRATIONS, AUTH_SUPER_ADMIN_EMAIL / _PASSWORD, REDIS_PREFIX
   ...require('@xeplr/auth').requiredEnv,
 
   // ── this app's own ──

package/templates/api/migrations/README.md

@@ -4,6 +4,6 @@ Hand-written `.sql` files, applied once each, in name order, every time the API
 starts (`0001_something.sql`, `0002_…`).
 
 **Tables for screens are not written here.** A screen's table (`tasks`) is
-created and changed by **Publish** in the Designer page — see `screens/`.
+created and changed by **Publish** in Configure UI → Forms — see `screens/`.
 
 Put here only tables no screen owns: lookup data, a table your own code writes.

package/templates/api/migrations-auth/0001_home_menu.sql

@@ -1,5 +1,5 @@
 -- "Home" — this app's own drawer item, matching the name used in the UI's
--- drawerItems list (ui/src/App.jsx).
+-- drawerItems list (ui/src/App.jsx), by key. Its label is changed in Configure UI → Menu.
 --
 -- Without this row the item is dropped from the drawer SILENTLY: the name has
 -- to exist here for @xeplr/ui-account to show it, and an unrecognised one

package/templates/api/migrations-auth/0002_tasks_menu.sql

@@ -1,6 +1,7 @@
 -- "Tasks" — the drawer item for the sample page.
 --
--- The name must match ui/src/App.jsx's drawerItems entry EXACTLY.
+-- 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.
 -- @xeplr/ui-account drops unrecognised names silently, so a typo removes the
 -- item with no error anywhere.
 

package/templates/api/migrations-auth/0003_configure_ui_menu.sql

@@ -0,0 +1,20 @@
+-- "Configure UI" — in the settings menu (top right): every form (design, publish,
+-- open, add to the menu) and the side rail's items (rename, reorder, hide).
+-- ui/src/pages/ConfigureUI.jsx.
+--
+-- SUPER ADMIN ONLY: publishing changes database tables. The API refuses
+-- everyone else as well (api/routes/access.js, and @xeplr/auth's menu routes).
+--
+-- The name is the KEY the app matches on (App.jsx settingsOverrides). What
+-- people read is the label, which Configure UI → Menu can change.
+
+INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), 'Configure UI', '', false, true, '*', now(), now()
+WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = 'Configure UI');
+
+INSERT INTO "menuRolesMapping" (id, "roleId", "menuId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), r.id, m.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name = 'Super Admin'
+  AND m.name = 'Configure UI'
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);

package/templates/api/models/index.js

@@ -2,7 +2,7 @@
 // class extending @xeplr/db's BaseModel, handed to genericRoute in
 // routes/index.js.
 //
-// Tables made with the Designer (screens/) need no model: @xeplr/factory saves
+// Tables made as forms (Configure UI → Forms, screens/) need no model: @xeplr/factory saves
 // and reads them from the screen itself.
 
 module.exports = {};

package/templates/api/package.json

@@ -17,11 +17,12 @@
     "start-api": "node ./bin/www"
   },
   "dependencies": {
-    "@xeplr/auth": "^1.1.2",
+    "@xeplr/auth": "^1.1.4",
     "@xeplr/base-apis": "^2.0.0",
     "@xeplr/db": "^1.0.6",
-    "@xeplr/factory": "^1.0.3",
-    "@xeplr/utils": "^1.0.8",
+    "@xeplr/factory": "^1.0.5",
+    "@xeplr/ui-factory": "^1.0.5",
+    "@xeplr/utils": "^1.0.11",
     "dotenv": "^17.4.2",
     "express": "^5.2.0"
   },

package/templates/api/routes/access.js

@@ -0,0 +1,25 @@
+// WHO MAY DO WHAT — beyond the permission catalog every route already checks.
+//
+// Designing screens, making new forms and publishing them change the
+// database's tables, so they are kept to Super Admin alone, whatever else a
+// role has been granted. Relax superAdminOnly here when your app has decided
+// who else should.
+
+var FORBIDDEN = { code: 'FORBIDDEN', message: 'Only Super Admin can design and publish forms', error: null, dataArray: [] };
+
+function isSuperAdmin(req) {
+  var roles = (req.access && req.access.roles) || (req.user && req.user.roles) || [];
+  return roles.indexOf('Super Admin') !== -1;
+}
+
+function superAdminOnly(req, res, next) {
+  if (isSuperAdmin(req)) return next();
+  res.status(403).send(FORBIDDEN);
+}
+
+/** No check of its own — the token and the permission catalog still apply. */
+function anyone(req, res, next) {
+  next();
+}
+
+module.exports = { isSuperAdmin: isSuperAdmin, superAdminOnly: superAdminOnly, anyone: anyone };

package/templates/api/routes/index.js

@@ -26,7 +26,7 @@ router.get('/whoami', function(req, res) {
 // path which to forward. Serve data at /tasks and the UI's own /tasks page is
 // shadowed by it — opening that page shows raw JSON instead of the app.
 //
-// Screens made in the Designer (tasks) need nothing here — @xeplr/factory
+// Forms (tasks, and any made in Configure UI) need nothing here — @xeplr/factory
 // serves them at /api/factory/..., mounted in app.js.
 //
 // A table you write by hand gets its four addresses from one line:

package/templates/api/screens/index.js

@@ -6,16 +6,18 @@
 //
 // On startup (bin/www) every screen here that has never been published is
 // published — which creates its table. After that the DATABASE holds the
-// design: change it in the app's Designer page, where Publish changes the
+// design: change it in the app's Configure UI → Forms, where Publish changes the
 // table to match. Editing a .screen.json later changes nothing for an
 // already-published screen.
 //
-// ADD AN ENTITY:
+// ADD ONE: follow "Create a new UI" in the project's CLAUDE.md — or ask Claude
+// to, with the prompt there. Every form's folder holds the same files:
 //
-//   npx xeplr-factory screens screens/project/project.entity.json -o screens/project
-//
-// then list its two screens and its hooks below, and add a page and a menu
-// entry for it (see the UI's src/pages/Tasks.jsx and migrations-auth/).
+//   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
 
 module.exports = {
   // Publish order is worked out for you: a table before the dropdowns that
@@ -28,5 +30,10 @@ module.exports = {
   // 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.model.js

@@ -0,0 +1,29 @@
+// 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')] })
+//
+// Used everywhere: the screens' routes and factory.table('tasks'). Models shape
+// data; the hooks file decides behaviour.
+
+var { FactoryModel } = require('@xeplr/factory');
+
+class TaskModel extends FactoryModel {
+  static table = 'tasks';
+
+  // Per field: set(value, values) before it is written, get(value, row) after it is read.
+  //   tags: { set: (v) => (Array.isArray(v) ? v.join(',') : v), get: (v) => (v ? v.split(',') : []) }
+  static fields = {};
+
+  /** Every value about to be written. Override for more than one field at a time. */
+  static toDb(values) {
+    return super.toDb(values);
+  }
+
+  /** Every row just read. */
+  static fromDb(row) {
+    return super.fromDb(row);
+  }
+}
+
+module.exports = TaskModel;

package/templates/ui/package.json

@@ -10,9 +10,9 @@
   },
   "dependencies": {
     "@tanstack/react-table": "^8.21.3",
-    "@xeplr/ui-account": "^1.0.6",
+    "@xeplr/ui-account": "^1.0.7",
     "@xeplr/ui-canvas": "^1.0.2",
-    "@xeplr/ui-factory": "^1.0.4",
+    "@xeplr/ui-factory": "^1.0.5",
     "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",

package/templates/ui/src/App.jsx

@@ -1,9 +1,12 @@
 import { useMemo } from 'react'
 import { Routes, Route, Outlet, Navigate, useNavigate } from 'react-router-dom'
-import { authRoutes, authPath, NavPage, ProtectedRoute } from '@xeplr/ui-account'
+import { authRoutes, authPath, NavPage, ProtectedRoute, useAccess } from '@xeplr/ui-account'
 import Home from './pages/Home.jsx'
 import Tasks from './pages/Tasks.jsx'
-import Designer from './pages/Designer.jsx'
+import ConfigureUI from './pages/ConfigureUI.jsx'
+import { FORM_MENU_PREFIX } from './menu.js'
+import FormDesigner from './pages/FormDesigner.jsx'
+import FormRecords from './pages/FormRecords.jsx'
 __MT_APP_UI_IMPORTS__
 
 // The rail is ICON-ONLY when collapsed, so a drawer item without one is
@@ -17,7 +20,7 @@ const TasksIcon = (
   </svg>
 )
 
-const DesignerIcon = (
+const FormsIcon = (
   <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="18" height="18" rx="2" />
@@ -38,26 +41,37 @@ const HomeIcon = (
 const notifications = { count: 0, onClick: () => {} }
 
 // Rendered above the framework's built-in Profile / Change Password section.
+// `key` is the menu row it matches (shown only to roles given that row); what
+// people read is its label, changed in Configure UI → Menu.
 const settingsOverrides = [
-  { name: 'Admin', path: authPath('userRoles') }
+  { key: 'Admin', path: authPath('userRoles') },
+  // Super Admin only (migrations-auth/0003): every form, and the side rail.
+  { key: 'Configure UI', path: '/configure' }
 ]
 
+
 // Layout route: NavPage and the routed page are independent siblings, and this
 // holds no state of its own — lifting page state up here would re-render the
 // nav on every unrelated change.
 function Shell() {
   const navigate = useNavigate()
 
-  // The drawer's catalog. A name here must match a seeded `menus` row —
-  // @xeplr/ui-account drops unrecognised names SILENTLY, so a typo removes the
-  // item with no error anywhere.
+  const { access } = useAccess()
+  const menus = (access && access.menus) || []
+
+  // 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.
   const drawerItems = useMemo(() => [
-    { name: 'Home', icon: HomeIcon, clickHandler: () => navigate('/home') },
-    { name: 'Tasks', icon: TasksIcon, clickHandler: () => navigate('/tasks') },
-    // Shown only to roles given the "Designer" menu (migrations-auth/0003).
-    { name: 'Designer', icon: DesignerIcon, clickHandler: () => navigate('/designer') },
+    { key: 'Home', icon: HomeIcon, clickHandler: () => navigate('/home') },
+    { key: 'Tasks', icon: TasksIcon, clickHandler: () => navigate('/tasks') },
 __MT_DRAWER_ITEM__
-  ], [navigate])
+    // 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))
+    }))
+  ], [navigate, menus])
 
   return (
     <div className="app">
@@ -91,7 +105,9 @@ __MT_SELECT_ROUTE__
         <Route path="/" element={<Navigate to="/home" replace />} />
         <Route path="/home" element={<Home />} />
         <Route path="/tasks" element={<Tasks />} />
-        <Route path="/designer" element={<Designer />} />
+        <Route path="/forms/:form" element={<FormRecords />} />
+        <Route path="/configure" element={<ConfigureUI />} />
+        <Route path="/configure/forms/:form/design/:part" element={<FormDesigner />} />
       </Route>
 
       <Route path="*" element={<Navigate to="/auth/login" replace />} />

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

@@ -1,4 +1,4 @@
-// MODEL LAYER — every call the screens and the Designer make, to the API's
+// MODEL LAYER — every call the screens and Configure UI make, to the API's
 // @xeplr/factory routes (mounted at /api in api/app.js).
 //
 // authFetch attaches the signed-in user's token (and the active company, when

package/templates/ui/src/index.css

@@ -274,6 +274,48 @@ body { margin: 0; }
   .app-help { position: static; margin-top: 28px; width: auto; }
 }
 
+/* ── Forms ────────────────────────────────────────────────────────────── */
+/* ── Configure UI ─────────────────────────────────────────────────────── */
+.app-tabs { display: flex; gap: 4px; margin: 4px 0 18px; border-bottom: 1px solid var(--xeplr-border-primary); }
+
+.app-tab {
+  padding: 8px 14px;
+  border: none;
+  border-bottom: 2px solid transparent;
+  background: none;
+  color: var(--xeplr-text-muted);
+  font: inherit;
+  cursor: pointer;
+}
+
+.app-tab.is-active { color: var(--xeplr-text-primary); border-bottom-color: var(--xeplr-accent); }
+
+.app-forms-new { display: flex; gap: 10px; align-items: flex-end; flex-wrap: wrap; max-width: 820px; margin: 0 0 18px; }
+
+.app-forms-field { display: flex; flex-direction: column; gap: 4px; flex: 1; min-width: 220px; font-size: 12px; color: var(--xeplr-text-muted); }
+
+.app-menu-label,
+.app-forms-new input {
+  flex: 1;
+  padding: 9px 11px;
+  border-radius: 6px;
+  border: 1px solid var(--xeplr-input-border);
+  background: var(--xeplr-input-bg);
+  color: var(--xeplr-input-text);
+  font: inherit;
+}
+
+.app-forms-pending { color: var(--xeplr-warning); }
+
+.app-notice {
+  margin: 0 0 14px;
+  padding: 10px 14px;
+  border-radius: 6px;
+  border: 1px solid var(--xeplr-success-border);
+  background: var(--xeplr-success-bg);
+  color: var(--xeplr-success);
+}
+
 /* ── Designer ─────────────────────────────────────────────────────────── */
 /* The builder fills the space it is given, so it needs a height: the page
    below the top bar, less .main's padding. */
@@ -298,3 +340,20 @@ body { margin: 0; }
   border-radius: 8px;
   overflow: hidden;
 }
+
+.app-help-prompt {
+  white-space: pre-wrap;
+  font-size: 12px;
+  line-height: 1.5;
+  padding: 10px 12px;
+  margin: 8px 0;
+  border-radius: 6px;
+  background: var(--xeplr-bg-tertiary);
+  border: 1px solid var(--xeplr-border-primary);
+}
+
+.app-menu-hidden td { opacity: 0.5; }
+
+.app-menu-shown { display: inline-flex; gap: 6px; align-items: center; }
+
+.app-menu-settings .app-table { margin-bottom: 14px; }

package/templates/ui/src/menu.js

@@ -0,0 +1,17 @@
+// THE APP'S MENU KEYS — one place, used by App.jsx and Configure UI → Menu.
+//
+// A key is a `menus` row's name: what the side rail and the settings menu match
+// on. It never changes. What people read is that row's LABEL, renamed in
+// Configure UI → Menu — so no label is written anywhere in code.
+
+/** A form added to the menu from Configure UI is the menu row "form:<its key>". */
+export const FORM_MENU_PREFIX = 'form:'
+
+/** Every key this app shows — Configure UI → Menu lists these, and the forms added to the menu. */
+export const APP_MENU_KEYS = [
+  'Home',
+  'Tasks',
+__MT_MENU_KEY__
+  'Admin',
+  'Configure UI'
+]

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

@@ -0,0 +1,42 @@
+// CONFIGURE UI — Super Admin, from the settings menu (top right).
+//
+//   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
+//
+// 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'
+
+const TABS = [
+  { id: 'forms', label: 'Forms', Page: Forms },
+  { id: 'menu', label: 'Menu', Page: MenuSettings }
+]
+
+export default function ConfigureUI() {
+  const [params, setParams] = useSearchParams()
+  const current = TABS.find((t) => t.id === params.get('tab')) || TABS[0]
+
+  return (
+    <div className="app-page app-configure">
+      <h1>Configure UI</h1>
+      <div className="app-tabs" role="tablist">
+        {TABS.map((t) => (
+          <button
+            key={t.id}
+            type="button"
+            role="tab"
+            aria-selected={t.id === current.id}
+            className={'app-tab' + (t.id === current.id ? ' is-active' : '')}
+            onClick={() => setParams({ tab: t.id })}
+          >
+            {t.label}
+          </button>
+        ))}
+      </div>
+      <current.Page />
+    </div>
+  )
+}