@xeplr/cli 0.1.4 → 0.1.6

package/README.md

@@ -4,9 +4,11 @@ Creates a working xeplr application — an API, sign-in, and a UI — from a few
 questions, installs it, and sets up its databases.
 
 ```bash
-npx @xeplr/cli new myapp
+npx @xeplr/cli@latest new myapp
 ```
 
+`@latest` makes npx fetch the newest version rather than one it cached earlier.
+
 ## What you get
 
 ```
@@ -28,10 +30,15 @@ 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 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.
+- **Configure UI** for Super Admin, in the settings menu (top right) — not in
+  the side rail, which is for the pages people use:
+  - **Forms**: every UI in the app. New form (a **label** people see and a
+    **key** that names its table), design its form and its list, publish (which
+    creates or changes its table), open it, **add it to the side rail** — no
+    code, no Claude needed.
+  - **Menu**: rename, reorder and hide the side rail's items.
+
+  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,
@@ -47,6 +54,21 @@ Already working, with nothing to wire up:
   > 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.
 
+## Rules the generated app follows
+
+These are architecture decisions, not defaults to tune — each one exists because the alternative failed quietly.
+
+| Rule | Where | Why |
+|---|---|---|
+| **Records live in real tables, one column per field — never JSON.** | `@xeplr/factory` | `select * from tasks` and plain-SQL reports must work. Only a screen's *design* is JSON (the `factory_screens` table). |
+| **A key and a label, everywhere.** A form's key (`farming_department`) names its screens and table and never changes once published; its label is renamed any time. A menu item's key (`menus.name`, used by `drawerItems` / `settingsOverrides` in `ui/src/App.jsx` and `ui/src/menu.js`) is what code matches; its label is what the rail shows. | `@xeplr/auth`, `@xeplr/ui-account` | Code must never break because someone renamed something people read. No label is written in code. |
+| **`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` | |
+| **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. |
+
 ## Before you start
 
 - **Node.js** 18 or later
@@ -83,13 +105,49 @@ cd myapp/api && npm run start-api    # your API — publishes the sample screens
 cd myapp/ui  && npm run dev          # the app
 ```
 
-Open the UI and sign in with the account you named.
+Open the UI and sign in with the account you named. As Super Admin you will
+see **Configure UI** in the settings menu, top right.
+
+**Use a new project name for a new app.** The name decides the database names
+(`<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.
 
 `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
 to run again.
 
+## Creating a new UI
+
+Two ways, both in the running app's project:
+
+- **No code** — Configure UI → Forms → New form → design → Publish → Add to menu.
+- **With Claude** — open Claude in the project folder and give it this (it is
+  also beside the sample, with a Copy button):
+
+  > 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.
+
+  Claude follows `CLAUDE.md`: the screens and server hooks 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.
+
+## Commands in a generated project
+
+| Where | Command | Does |
+|---|---|---|
+| `api/` | `npm run setup` | create both databases, the sign-in tables, permissions and menus |
+| `api/` | `npm run start-auth` | the sign-in service |
+| `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 validate <screen>.json` | check a screen document |
+| `ui/` | `npm run dev` | the app |
+
 ## Changing the database connection later
 
 A password rotates, the database moves, or the first answer was wrong. From

package/lib/generate/index.js

@@ -94,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/package.json

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

@@ -22,8 +22,8 @@ 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 with an **icon** (a collapsed rail shows icons only).
-7. **The menu row** — `api/migrations-auth/000N_<forms>_menu.sql` (next free number): copy `0002_tasks_menu.sql`, with the item's name spelled **exactly** as in `drawerItems` — an unknown name is dropped silently. Then, in `api/`: `npm run migrate:auth`, and restart the sign-in service (menus are cached for 10 minutes).
+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.
 
@@ -31,13 +31,15 @@ Then change only what the request asks for:
 
 | the request says… | change |
 |---|---|
-| a field, label, rule, dropdown, layout, colour | the screen JSON → validate → publish on the Forms page (or, never published yet, restart the API) |
+| 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 on the **Forms** page (New form → design → Publish → Open). 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, 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
 
@@ -49,7 +51,7 @@ Replace the bold parts. Add behaviour in the same message if you want it — "a
 
 - **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 on the Forms page.
+- 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.

package/templates/api/bin/www

@@ -64,7 +64,7 @@ async function start() {
   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 Forms page 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/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** on the Forms 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 as forms (Forms page, 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,12 +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.4",
+    "@xeplr/factory": "^1.0.5",
     "@xeplr/ui-factory": "^1.0.5",
-    "@xeplr/utils": "^1.0.8",
+    "@xeplr/utils": "^1.0.11",
     "dotenv": "^17.4.2",
     "express": "^5.2.0"
   },

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.
 //
-// Forms (tasks, and any made on the Forms page) 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,7 +6,7 @@
 //
 // 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 on the app's Forms 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.
 //

package/templates/ui/package.json

@@ -10,7 +10,7 @@
   },
   "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.5",
     "@xeplr/ui-table": "^1.0.6",

package/templates/ui/src/App.jsx

@@ -1,9 +1,10 @@
 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 Forms from './pages/Forms.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__
@@ -40,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') },
-    // Super Admin only — the "Forms" menu (migrations-auth/0003).
-    { name: 'Forms', icon: FormsIcon, clickHandler: () => navigate('/forms') },
+    { 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">
@@ -93,9 +105,9 @@ __MT_SELECT_ROUTE__
         <Route path="/" element={<Navigate to="/home" replace />} />
         <Route path="/home" element={<Home />} />
         <Route path="/tasks" element={<Tasks />} />
-        <Route path="/forms" element={<Forms />} />
         <Route path="/forms/:form" element={<FormRecords />} />
-        <Route path="/forms/:form/design/:part" element={<FormDesigner />} />
+        <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 Forms pages 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

@@ -275,8 +275,26 @@ body { margin: 0; }
 }
 
 /* ── Forms ────────────────────────────────────────────────────────────── */
-.app-forms-new { display: flex; gap: 8px; max-width: 640px; margin: 0 0 18px; }
+/* ── 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;
@@ -333,3 +351,9 @@ body { margin: 0; }
   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>
+  )
+}

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

@@ -1,6 +1,6 @@
 // THE TASK FORM — and what the task screens do in the browser.
 //
-// The form itself is the "task_edit" screen, designed on the Forms page. This
+// The form itself is the "task_edit" screen, designed in Configure UI → Forms. This
 // module holds its HOOKS, used by this page, by the Tasks list and by the
 // popup the list opens.
 import { useEffect, useState } from 'react'

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

@@ -43,14 +43,14 @@ export default function FormDesigner() {
   return (
     <div className="app-designer">
       <div className="app-designer-bar">
-        <button type="button" className="app-btn app-btn-quiet" onClick={() => navigate('/forms')}>← Forms</button>
+        <button type="button" className="app-btn app-btn-quiet" onClick={() => navigate('/configure')}>← Configure UI</button>
         <span className="app-designer-title">{current ? current.document.name : form}</span>
         {PARTS.map((p) => (
           <button
             key={p.part}
             type="button"
             className={'app-btn app-btn-quiet' + ((part === 'list') === (p.part === 'list') ? ' is-active' : '')}
-            onClick={() => navigate('/forms/' + form + '/design/' + p.part)}
+            onClick={() => navigate('/configure/forms/' + form + '/design/' + p.part)}
           >
             {p.label}
           </button>

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

@@ -1,15 +1,17 @@
-// FORMS — every form in the app, for Super Admin: see them, make a new one,
-// design it, publish it, open it.
+// FORMS — every UI in the app (Configure UI → Forms). Make one, design it,
+// publish it, open it, add it to the side rail.
 //
-// A form is two screens: a LIST of its records, and the add / edit FORM the
-// list opens in a popup. Records live in an ordinary table named for the form
-// ("farming_departments"), created when the form is first published.
+// A form is two screens: a LIST of its records, and the add / edit FORM the list
+// opens in a popup. Its KEY (farming_department) names the screens and the table
+// (farming_departments) and cannot change once published; its LABEL is what
+// people see, renamed any time in its design.
 //
-// Claude can make forms too (api/screens/, `npx xeplr-factory screens`); this
-// page is the same thing by hand.
+// Claude can make forms too — see "Create a new UI" in CLAUDE.md.
 import { useCallback, useEffect, useState } from 'react'
 import { useNavigate } from 'react-router-dom'
+import { listMenuItems, addMenuItem, removeMenuItem, useAccess } from '@xeplr/ui-account'
 import { factory } from '../api/factory.js'
+import { FORM_MENU_PREFIX } from '../menu.js'
 
 /** listScreens rows → one entry per form: { key, name, source, list, edit }. */
 function groupForms(rows) {
@@ -34,26 +36,48 @@ function state(screen) {
   return { label: 'v' + screen.version + (screen.hasDraft ? ' · unpublished changes' : ''), unpublished: screen.hasDraft }
 }
 
+/** "Farming departments" → "farming_department": a suggestion, editable. */
+function suggestKey(label) {
+  const words = String(label).toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().split(' ').filter(Boolean)
+  if (!words.length) return ''
+  const last = words[words.length - 1]
+  words[words.length - 1] = /ies$/.test(last) ? last.slice(0, -3) + 'y' : /(ss|us)$/.test(last) ? last : last.replace(/s$/, '')
+  const key = words.join('_')
+  return /^[a-z]/.test(key) ? key : 'form_' + key
+}
+
 export default function Forms() {
   const navigate = useNavigate()
+  const { refreshAccess } = useAccess()
   const [forms, setForms] = useState(null)
+  const [inMenu, setInMenu] = useState(new Set())
   const [error, setError] = useState(null)
   const [notice, setNotice] = useState(null)
-  const [name, setName] = useState('')
+  const [label, setLabel] = useState('')
+  const [key, setKey] = useState('')
+  const [keyEdited, setKeyEdited] = useState(false)
   const [busy, setBusy] = useState(null)
 
   const load = useCallback(() => {
     factory.listScreens().then((rows) => { setForms(groupForms(rows)); setError(null) }, (e) => setError(e.message))
+    listMenuItems().then(
+      (items) => setInMenu(new Set(items.filter((m) => m.name.startsWith(FORM_MENU_PREFIX) && !m.isHidden).map((m) => m.name.slice(FORM_MENU_PREFIX.length)))),
+      () => {}
+    )
   }, [])
   useEffect(load, [load])
 
+  const onLabel = (value) => {
+    setLabel(value)
+    if (!keyEdited) setKey(suggestKey(value))
+  }
+
   const create = async (e) => {
     e.preventDefault()
     setBusy('new')
     try {
-      const made = await factory.createEntity({ entity: name })
-      // Straight into its form, to add the fields.
-      navigate('/forms/' + made.edit.replace(/_edit$/, '') + '/design/form')
+      const made = await factory.createEntity({ key: key.trim(), label: label.trim() })
+      navigate('/configure/forms/' + made.key + '/design/form')
     } catch (err) {
       setError(err.message)
       setBusy(null)
@@ -74,8 +98,6 @@ export default function Forms() {
       setError(null)
       load()
     } catch (err) {
-      // Removing a field drops its column — that is confirmed in the designer,
-      // where the columns and their values are shown.
       setError(err.confirm
         ? 'Publishing "' + form.name + '" would remove columns and their data — open Design form and publish there to see what, and confirm.'
         : err.message)
@@ -84,21 +106,37 @@ export default function Forms() {
     }
   }
 
+  const toggleMenu = async (form) => {
+    setBusy(form.key)
+    try {
+      if (inMenu.has(form.key)) await removeMenuItem(FORM_MENU_PREFIX + form.key)
+      else await addMenuItem({ name: FORM_MENU_PREFIX + form.key, label: form.name })
+      await refreshAccess()
+      setNotice(inMenu.has(form.key) ? 'Removed "' + form.name + '" from the menu' : 'Added "' + form.name + '" to the menu — rename or move it in the Menu tab')
+      load()
+    } catch (err) {
+      setError(err.message)
+    } finally {
+      setBusy(null)
+    }
+  }
+
   return (
-    <div className="app-page app-forms">
-      <h1>Forms</h1>
+    <div className="app-forms">
       <p className="app-page-lead">
-        Every form in the app. A new one starts with a Name field — add the rest in its design, then publish to create its table.
+        Every UI in the app. A new one starts with a Name field — add the rest in its design, then publish to create its table.
       </p>
 
       <form className="app-forms-new" onSubmit={create}>
-        <input
-          value={name}
-          onChange={(e) => setName(e.target.value)}
-          placeholder='New form — one record is a… e.g. "farming department"'
-          aria-label="New form name"
-        />
-        <button type="submit" className="app-btn" disabled={!name.trim() || busy === 'new'}>
+        <label className="app-forms-field">
+          <span>Label — what people see</span>
+          <input value={label} onChange={(e) => onLabel(e.target.value)} placeholder="Farming departments" />
+        </label>
+        <label className="app-forms-field">
+          <span>Key — names its table; fixed once published</span>
+          <input value={key} onChange={(e) => { setKey(e.target.value); setKeyEdited(true) }} placeholder="farming_department" />
+        </label>
+        <button type="submit" className="app-btn" disabled={!key.trim() || busy === 'new'}>
           {busy === 'new' ? 'Creating…' : 'New form'}
         </button>
       </form>
@@ -110,7 +148,7 @@ export default function Forms() {
       {forms && forms.length > 0 && (
         <table className="app-table">
           <thead>
-            <tr><th>Name</th><th>Table</th><th>Form</th><th>List</th><th /></tr>
+            <tr><th>Label</th><th>Table</th><th>Form</th><th>List</th><th /></tr>
           </thead>
           <tbody>
             {forms.map((form) => {
@@ -125,8 +163,11 @@ export default function Forms() {
                   <td className={list.unpublished ? 'app-forms-pending' : undefined}>{list.label}</td>
                   <td className="app-row-actions">
                     <button className="app-btn app-btn-quiet" disabled={!canOpen} title={canOpen ? '' : 'Publish it first'} onClick={() => navigate('/forms/' + form.key)}>Open</button>
-                    {form.edit && <button className="app-btn app-btn-quiet" onClick={() => navigate('/forms/' + form.key + '/design/form')}>Design form</button>}
-                    {form.list && <button className="app-btn app-btn-quiet" onClick={() => navigate('/forms/' + form.key + '/design/list')}>Design list</button>}
+                    {form.edit && <button className="app-btn app-btn-quiet" onClick={() => navigate('/configure/forms/' + form.key + '/design/form')}>Design form</button>}
+                    {form.list && <button className="app-btn app-btn-quiet" onClick={() => navigate('/configure/forms/' + form.key + '/design/list')}>Design list</button>}
+                    <button className="app-btn app-btn-quiet" disabled={!canOpen || busy === form.key} title={canOpen ? '' : 'Publish it first'} onClick={() => toggleMenu(form)}>
+                      {inMenu.has(form.key) ? 'Remove from menu' : 'Add to menu'}
+                    </button>
                     {(edit.unpublished || list.unpublished) && (
                       <button className="app-btn" disabled={busy === form.key} onClick={() => publish(form)}>
                         {busy === form.key ? 'Publishing…' : 'Publish'}

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

@@ -59,8 +59,8 @@ export default function Home() {
           sample logo, in the top bar and the side rail.
         </li>
         <li>
-          <strong>Forms</strong>, in the side rail — make a new form, or change the
-          sample task screens. Publish creates or changes the table too.
+          <strong>Configure UI</strong>, in the settings menu — every form (make one,
+          design it, publish it, add it to the menu) and the side rail's labels.
         </li>
         <li>
           <code>src/App.jsx</code> — add your own pages, and the side-rail items

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

@@ -0,0 +1,99 @@
+// THE SIDE RAIL'S ITEMS (Configure UI → Menu) — rename, reorder, hide.
+//
+// Each item has a KEY, which the code matches on and which never changes here,
+// and a LABEL, which is what people read. Leave the label empty to show the key.
+// Saved for everyone at once; your own rail updates straight away.
+import { useCallback, useEffect, useState } from 'react'
+import { listMenuItems, saveMenuItems, useAccess } from '@xeplr/ui-account'
+import { APP_MENU_KEYS, FORM_MENU_PREFIX } from '../menu.js'
+
+// The app's own items (ui/src/menu.js) and forms added to the menu. The rest —
+// sign-in's pages (Login, Register …) and admin screens — only with "Show all".
+const isAppItem = (name) => APP_MENU_KEYS.includes(name) || name.startsWith(FORM_MENU_PREFIX)
+
+export default function MenuSettings() {
+  const { refreshAccess } = useAccess()
+  const [items, setItems] = useState(null)
+  const [error, setError] = useState(null)
+  const [notice, setNotice] = useState(null)
+  const [saving, setSaving] = useState(false)
+  const [showAll, setShowAll] = useState(false)
+
+  const load = useCallback(() => {
+    listMenuItems().then((rows) => { setItems(rows.map((r) => ({ ...r, label: r.label || '' }))); setError(null) }, (e) => setError(e.message))
+  }, [])
+  useEffect(load, [load])
+
+  const shown = (it) => showAll || isAppItem(it.name)
+  const change = (name, patch) => setItems((list) => list.map((it) => (it.name === name ? { ...it, ...patch } : it)))
+  // Swap with the next row ON SCREEN — entries filtered out keep their places.
+  const move = (name, by) => setItems((list) => {
+    const visible = list.filter(shown).map((it) => it.name)
+    const k = visible.indexOf(name) + by
+    if (k < 0 || k >= visible.length) return list
+    const a = list.findIndex((it) => it.name === name)
+    const b = list.findIndex((it) => it.name === visible[k])
+    const next = [...list]
+    ;[next[a], next[b]] = [next[b], next[a]]
+    return next
+  })
+
+  const save = async () => {
+    setSaving(true)
+    setNotice(null)
+    try {
+      // The order on screen becomes the order in the rail.
+      await saveMenuItems(items.map((it, i) => ({ name: it.name, label: it.label, sortOrder: i, isHidden: it.isHidden })))
+      await refreshAccess()
+      setNotice('Saved — the menu shows it now')
+      setError(null)
+      load()
+    } catch (err) {
+      setError(err.message)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <div className="app-menu-settings">
+      <p className="app-page-lead">
+        What the side rail and the settings menu show, and in what order. Add a form to the menu from the Forms tab.
+      </p>
+      <label className="app-menu-shown">
+        <input type="checkbox" checked={showAll} onChange={(e) => setShowAll(e.target.checked)} /> Show all menu entries, including sign-in and admin pages
+      </label>
+      {error && <div className="app-error">{error}</div>}
+      {notice && <div className="app-notice">{notice}</div>}
+      {items && (
+        <table className="app-table">
+          <thead>
+            <tr><th>Order</th><th>Label</th><th>Key</th><th>Shown</th></tr>
+          </thead>
+          <tbody>
+            {items.filter(shown).map((it, i, visible) => (
+              <tr key={it.name} className={it.isHidden ? 'app-menu-hidden' : undefined}>
+                <td className="app-row-actions">
+                  <button type="button" className="app-btn app-btn-quiet" aria-label={'Move ' + it.shown + ' up'} disabled={i === 0} onClick={() => move(it.name, -1)}>↑</button>
+                  <button type="button" className="app-btn app-btn-quiet" aria-label={'Move ' + it.shown + ' down'} disabled={i === visible.length - 1} onClick={() => move(it.name, 1)}>↓</button>
+                </td>
+                <td>
+                  <input className="app-menu-label" value={it.label} placeholder={it.name} aria-label={'Label for ' + it.name} onChange={(e) => change(it.name, { label: e.target.value })} />
+                </td>
+                <td><code>{it.name}</code></td>
+                <td>
+                  <label className="app-menu-shown">
+                    <input type="checkbox" checked={!it.isHidden} onChange={(e) => change(it.name, { isHidden: !e.target.checked })} /> Shown
+                  </label>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+      {items && (
+        <button type="button" className="app-btn" disabled={saving} onClick={save}>{saving ? 'Saving…' : 'Save menu'}</button>
+      )}
+    </div>
+  )
+}

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

@@ -2,7 +2,7 @@
 // where it saves itself as you type; there is no Save button.
 //
 // Nothing about tasks is written in this file. The list and the form are
-// SCREENS, designed on the Forms page and stored by the API; this page only
+// SCREENS, designed in Configure UI → Forms and stored by the API; this page only
 // loads the published "task_list" and hands it the calls it needs — and the
 // task hooks (EditTask.jsx), which the popup uses too.
 import { useEffect, useState } from 'react'

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

@@ -45,7 +45,7 @@ export default function TasksHelp() {
 
       <h3>Change it</h3>
       <p>
-        Open <strong>Forms</strong> in the side rail and{' '}
+        Open <strong>Configure UI</strong> in the settings menu (top right) and{' '}
         <strong>Design form</strong> on Tasks. Add a field, move one, change a
         label or a colour — then <strong>Publish</strong>. The table gains its
         new column as you publish.
@@ -53,8 +53,8 @@ export default function TasksHelp() {
 
       <h3>Or by hand</h3>
       <p>
-        <strong>Forms → New form</strong>: name it, design it, publish it, open
-        it — no code. The full steps for a form with its own page, hooks and
+        <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
         model are in <code>CLAUDE.md</code>, under "Create a new UI".
       </p>
 

package/templates-tenancy/api/migrations-auth/0004_switch_menu.sql

@@ -1,7 +1,8 @@
 -- "__MT_SWITCH_NAME__" — the drawer item that goes back to the picker.
 --
 -- Public: everybody who signs in works inside one, so everybody can change it.
--- 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.
 
 INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
 SELECT encode(gen_random_bytes(12), 'hex'), '__MT_SWITCH_NAME__', '', true, true, '*', now(), now()

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

@@ -1,19 +0,0 @@
--- "Forms" — the drawer item for every form in the app: see them, make a new
--- one, design it, publish it (ui/src/pages/Forms.jsx).
---
--- SUPER ADMIN ONLY: publishing changes database tables. The API refuses
--- everyone else as well (api/routes/access.js); this keeps the menu honest
--- about it.
---
--- The name must match ui/src/App.jsx's drawerItems entry EXACTLY.
-
-INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
-SELECT encode(gen_random_bytes(12), 'hex'), 'Forms', '', false, true, '*', now(), now()
-WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = 'Forms');
-
-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 = 'Forms'
-  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);