@nocobase/app-skills 0.1.0-beta.57 → 0.1.0-beta.59

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.57",
3
+ "version": "0.1.0-beta.59",
4
4
  "description": "Agent Skills for developing applications and plugins, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -97,9 +97,9 @@ When the application already depends on `@nocobase/app-plugin-demo-mode`, a chan
97
97
 
98
98
  ## Deliver system administration by default
99
99
 
100
- When a user asks you to build a complete application, deliver a usable System management navigation section and administration pages alongside the business features, unless the user explicitly excludes them or requests a narrower deliverable such as an API-only service or a prototype explicitly limited to business screens. Users do not need to request administration pages individually. Include user management and role and permission management by default. Place workflow management, background tasks and other applicable administration entries directly under System management as siblings; show execution status, failures and supported recovery actions within each capability's pages, without an additional Operational monitoring group. Reuse existing pages and installed plugins, and implement missing application-owned pages. Read [system administration](references/system-administration.md) for the baseline, capability-specific pages and acceptance criteria. For a focused feature change, extend existing administration where that feature requires it.
100
+ When a user asks you to build a complete application, deliver the System settings structure ([System settings navigation](references/settings-navigation.md)) and administration pages alongside the business features, unless the user explicitly excludes them or requests a narrower deliverable such as an API-only service or a prototype explicitly limited to business screens. Users do not need to request administration pages individually. Include user management and role and permission management by default. Register workflow management, background tasks and other applicable administration as module cards of the System settings home; show execution status, failures and supported recovery actions within each capability's pages, without an additional Operational monitoring group. Reuse existing pages and installed plugins, and implement missing application-owned pages. Read [system administration](references/system-administration.md) for the baseline, capability-specific pages and acceptance criteria. For a focused feature change, extend existing administration where that feature requires it.
101
101
 
102
- Whenever application requirements include a process to develop, deliver its workflow management pages by default, even when the user mentions only the business process. Reuse the installed `workflow-management` UI Library block, or install it with `yes n | pnpm exec shadcn add @nocobase/workflow-management`. Follow [Lifecycle UI](references/lifecycle-ui.md) for installation, application adapters and the default layout: one Workflow management sidebar entry with in-page Definitions and Executions tabs, definition diagrams with visible parameter forms, and execution details with history and effects. The two tab views use URL-backed child routes without sidebar `navigation`. Extend an existing management area rather than adding a duplicate. Follow the scope exceptions in [system administration](references/system-administration.md#default-delivery).
102
+ Whenever application requirements include a process to develop, deliver its workflow management pages by default, even when the user mentions only the business process. Reuse the installed `workflow-management` UI Library block, or install it with `yes n | pnpm exec shadcn add @nocobase/workflow-management`. Follow [Lifecycle UI](references/lifecycle-ui.md) for installation, application adapters and the default layout: one Workflow management settings card with in-page Definitions and Executions tabs, definition diagrams with visible parameter forms, and execution details with history and effects. The two tab views use URL-backed child routes without sidebar `navigation`. Extend an existing management area rather than adding a duplicate. Follow the scope exceptions in [system administration](references/system-administration.md#default-delivery).
103
103
 
104
104
  For process management, distinguish administrator-adjustable reviewers, departments, thresholds and other [lifecycle parameters](references/lifecycle-parameters.md) from workflow structure, which remains defined in source unless a supported visual designer is explicitly required.
105
105
 
@@ -115,7 +115,7 @@ Replace `/main` with the application's `APP_BASE_PATH`. Swagger UI for people is
115
115
 
116
116
  ## Include administration by default
117
117
 
118
- For every application feature, apply [system settings delivery](references/system-settings.md): keep unused business settings disabled in a newly created application while retaining its restricted App Foundation entry; as the application develops beyond that basic shell, reconcile the template's prepared Users and Roles and permissions routes and the management surfaces for each capability actually used. Inspect this on every build or iteration, enable missing routes once and preserve already enabled pages, including workflow definitions, diagrams, configuration and authorized execution history. When building process rules, proactively declare appropriate thresholds and reviewer choices as validated, authorized business parameters and provide visible parameter forms in workflow management, with optional diagram-bound shortcuts to the same editor; the user need not ask for configurability. Apply the same check to non-workflow business policy, mutable dictionaries, business document numbering, important operation records and the other used capabilities in that reference. Follow its [business administration recipes](references/business-administration.md) for application-owned implementations and acceptance. The real execution must consume the saved values; source/deployment configuration retains its owner. This is part of implementing the feature, not a separate user request.
118
+ For every application feature, apply [system settings delivery](references/system-settings.md) and place every administration surface in the [System settings navigation](references/settings-navigation.md) (one sidebar entry, a home of cards by category, tabs inside a module): keep unused business settings disabled in a newly created application while retaining its restricted App Foundation entry; as the application develops beyond that basic shell, reconcile the template's prepared Users and Roles and permissions routes and the management surfaces for each capability actually used. Inspect this on every build or iteration, enable missing routes once and preserve already enabled pages, including workflow definitions, diagrams, configuration and authorized execution history. When building process rules, proactively declare appropriate thresholds and reviewer choices as validated, authorized business parameters and provide visible parameter forms in workflow management, with optional diagram-bound shortcuts to the same editor; the user need not ask for configurability. Apply the same check to non-workflow business policy, mutable dictionaries, business document numbering, important operation records and the other used capabilities in that reference. Follow its [business administration recipes](references/business-administration.md) for application-owned implementations and acceptance. The real execution must consume the saved values; source/deployment configuration retains its owner. This is part of implementing the feature, not a separate user request.
119
119
 
120
120
  For initialization prerequisites introduced by the feature, apply [setup readiness](references/setup-readiness.md): wire real required-role membership and applicable business relationship checks with the standard contextual hint. Users should see what configuration is missing and an authorized path to fix it. Installed plugins, read failures and missing business configuration are different states; keep the bare app and its protected App Foundation entry unchanged.
121
121
 
@@ -193,7 +193,7 @@ Everything else — `client/routing/`, `client/layouts/`, `client/theme/`, the s
193
193
 
194
194
  When the built-in mechanism genuinely cannot express the requirement, changing that structure is a legitimate answer. Comment what you changed and why the built-in path did not fit, and in the same change record the application-specific guidance in the matching `.agents/rules/<topic>.md`, adding its entry to the `AGENTS.md` index, so the guidance still describes the real application. Do not write the detail into `AGENTS.md` itself: it is a small always-on index of at most 32 KB that every agent loads on every start. The synchronized NocoBase Skills are package-owned; propose a change to their source package when the shared framework guidance itself is wrong.
195
195
 
196
- When you do change the shell (`client/layouts/`, `client/routing/`), keep the behaviors listed in [customizing the shell](references/frontend/references/shell.md#1-behaviors-to-keep): a single App shell with administration pages in the main sidebar rather than a separate settings layout, the language submenu, navigation group state, permission refresh and sign-out handling.
196
+ When you do change the shell (`client/layouts/`, `client/routing/`), keep the behaviors listed in [customizing the shell](references/frontend/references/shell.md#1-behaviors-to-keep): a single App shell with administration pages under its one System settings entry rather than a separate settings layout, the language submenu, navigation group state, permission refresh and sign-out handling.
197
197
 
198
198
  ## Ownership
199
199
 
@@ -385,13 +385,16 @@ test('native roles complete a purchasing loop with scoped selectors, editable li
385
385
  await reviewer.keyboard.press('Escape');
386
386
  await expect(reviewer.getByRole('menu')).toHaveCount(0);
387
387
  await reviewer
388
- .getByRole('button', { name: 'Appearance', exact: true })
388
+ .getByRole('button', { name: 'Open account menu', exact: true })
389
389
  .hover();
390
390
  await reviewer
391
- .getByRole('radiogroup', { name: 'Color mode' })
392
- .getByText('Dark', { exact: true })
391
+ .getByRole('menuitem', { name: 'Theme', exact: true })
392
+ .hover();
393
+ await reviewer
394
+ .getByRole('menuitemradio', { name: 'Dark', exact: true })
393
395
  .click();
394
396
  await reviewer.keyboard.press('Escape');
397
+ await reviewer.keyboard.press('Escape');
395
398
  await reviewer.getByRole('link', { name: title, exact: true }).click();
396
399
  await reviewer.setViewportSize({ width: 390, height: 844 });
397
400
  await expect(reviewer.locator('html')).toHaveClass(/dark/);
@@ -638,7 +638,7 @@ A page that shows a record whose detail is a page of its own — an orders list'
638
638
 
639
639
  ## 7. Settings pages
640
640
 
641
- - A settings page is an ordinary App page under a navigation group of the application's own, such as Settings ([section 5 of `page.md`](page.md#5-settings-pages)); there is no `/settings` or `/dev` surface.
641
+ - A settings page is an ordinary App page in the System settings structure ([section 5 of `page.md`](page.md#5-settings-pages)); a settings module with several views uses URL-backed tabs through `SettingsModulePage` ([System settings navigation](../../settings-navigation.md)).
642
642
  - Tabs in settings pages also use child routes ([section 4](#4-page-tabs)); nested details and tabs usually have no `navigation`.
643
643
  - A settings page checks its settings item; its child pages and tabs inherit that check or declare another action or item of their own, never a page grant.
644
644
  - Navigation groups carry no page permission. Access checks in the browser do not replace server authorization.
@@ -90,7 +90,7 @@ Rules:
90
90
  - **Write import paths with the `.js` extension**, even when the source file is `.tsx`. This is how this project resolves modules, not a typo.
91
91
  - **Paths are internal to the application**: do not write the deployment base path `/main`. The application is mounted under a base path (`/main` by default), and the runtime adds it automatically: `/projects` is `/main/projects` in the browser.
92
92
  - **Reserved paths**: `/login`, `/register`, `/forgot-password` and `/reset-password` can only use `auth: 'guest'`. They are already declared in `client/routes.ts`, and their pages are in `client/pages/auth/`.
93
- - Every page shares one path space. Registration rejects a path that another route already uses. Administration pages are ordinary App pages ([section 5](#5-settings-pages)); there is no `/settings` or `/dev` surface.
93
+ - Every page shares one path space. Registration rejects a path that another route already uses. Administration pages are ordinary App pages in the System settings structure ([section 5](#5-settings-pages)); there is no separate settings layout or `/dev` surface.
94
94
 
95
95
  ## 2. The page component
96
96
 
@@ -212,32 +212,27 @@ Provide English and Chinese text without unresolved interpolation placeholders.
212
212
 
213
213
  ## 5. Settings pages
214
214
 
215
- There is one kind of client route, `defineAppRoutes()`. The application has no separate settings area and no `/settings` or `/dev` prefix, and plugins contribute no settings pages: a page that configures something is an ordinary App page in the main navigation. Put such pages under a navigation group of their own, such as a Settings group at the end of the sidebar, and add the icons to the `lucide-react` import at the top of the file (here `Settings` and `SlidersHorizontal`):
215
+ There is one kind of client route, `defineAppRoutes()`, and plugins contribute no settings pages of their own: a page that configures something is an ordinary App page. Place it in the application's System settings structure — one sidebar entry opening a home page of cards by category, with tabs inside a module — by registering it with `parent` naming a settings category, as [System settings navigation](../../settings-navigation.md) describes. Add the icons to the `lucide-react` import at the top of the file (here `SlidersHorizontal`):
216
216
 
217
217
  ```ts
218
- // Appended to the defineAppRoutes([...]) array in client/routes.ts.
218
+ // Appended to the routes in client/routes.ts, beside the template's settings shell.
219
219
  {
220
- // A pure navigation group: no componentLoader, no authz.
221
- name: 'settings',
222
- path: '/settings',
223
- navigation: { title: 'navigation.settings', icon: Settings, order: 100 },
224
- children: [
225
- {
226
- // Opens for identities granted read on the project-settings item; the endpoints check the same item.
227
- authz: {
228
- resource: { type: 'settings', id: 'project-settings' },
229
- action: 'read',
230
- },
231
- componentLoader: () => import('./pages/settings/projects/index.js'),
232
- name: 'project-settings',
233
- navigation: {
234
- title: 'navigation.projectSettings',
235
- icon: SlidersHorizontal,
236
- },
237
- // The group's path is a prefix: this page is at /settings/projects.
238
- path: '/projects',
239
- },
240
- ],
220
+ // A card in the Business configuration category of the System settings home.
221
+ parent: 'settingsBusiness',
222
+ // Opens for identities granted read on the project-settings item; the endpoints check the same item.
223
+ authz: {
224
+ resource: { type: 'settings', id: 'project-settings' },
225
+ action: 'read',
226
+ },
227
+ componentLoader: () => import('./pages/settings/projects/index.js'),
228
+ name: 'project-settings',
229
+ navigation: {
230
+ title: 'navigation.projectSettings',
231
+ description: 'navigation.projectSettingsDescription',
232
+ icon: SlidersHorizontal,
233
+ },
234
+ // In Default the settings group's path is a prefix: this page is at /settings/projects.
235
+ path: '/projects',
241
236
  },
242
237
  ```
243
238
 
@@ -245,7 +240,7 @@ A configuration page checks a **settings item** rather than a page grant: a name
245
240
 
246
241
  - **Register the item on the server** in the `boot()` of the provider that owns the feature, with the service resolved from `authorizationToken`: `authz.settings.add({ id: 'project-settings', title, actions: [{ name: 'read' }, { name: 'update' }] })`, placed in the permission workspace with `authz.ui.place` (after `authz.ui.sections.add` when it needs a subsection of its own); an unplaced item is listed under "Other" with a startup warning. The server denies an item or action nobody registered, so an unregistered item keeps the page closed. The endpoints check the same item per action, `read` for loading and `update` for saving; see ["Authorization, when identity is not enough" in `../../server-routes.md`](../../server-routes.md#authorization-when-identity-is-not-enough). Actions are business actions (`read`, `update`); there is no conversion such as `list`, `show` or `edit`. Read the `nocobase-app-plugin-authorization` Skill before designing several items or actions.
247
242
  - **Gate the write controls on the write action**: `useCan({ resource: { type: 'settings', id: 'project-settings' }, action: 'update' })` ([section 8](#8-show-actions-by-permission-usecan)). Without it, render the values read-only instead of hiding the page.
248
- - `authz` is checked before the page loads; without permission the page disappears from the menu, and opening its URL directly does not load the component either. A group whose pages are all denied disappears with them.
243
+ - `authz` is checked before the page loads; without permission its card disappears from the settings home, and opening its URL directly does not load the component either. A category or module group whose pages are all denied disappears with them.
249
244
  - `navigation.order` sets the position in the menu; lower numbers come first.
250
245
  - For tabs and detail child pages, see [`child-routes.md`](child-routes.md).
251
246
 
@@ -4,11 +4,12 @@ The shell is `client/routing/` and `client/layouts/`, with the header, sidebar a
4
4
 
5
5
  ## 1. Behaviors to keep
6
6
 
7
- - There is no settings area and no Settings or Inbox entry in the header: every signed-in page renders inside `AppLayout`, and settings pages are ordinary pages in the sidebar ([section 5 of `page.md`](page.md#5-settings-pages)). Do not add a second layout or a `/settings` route split to the router.
7
+ - There is no separate settings layout and no Settings or Inbox entry in the header: every signed-in page renders inside `AppLayout`. Administration pages are ordinary routes under the System settings group, which the navigation transform (`client/lib/navigation-transform.ts`) folds into one sidebar entry opening the settings home; it stays selected on every page below the group, and the breadcrumb's System settings level links back to the home ([System settings navigation](../../settings-navigation.md)). Do not add a second layout, a resident settings sidebar or a router split for settings. The shell shares its single page permission check with pages through `RouteTreeProvider`'s `access` (`useRouteAccess`); the settings home and module tabs read it rather than checking again.
8
8
  - The account menu's language control (`client/layouts/components/language-switcher.tsx`) is a submenu with radio items and must stay inside `DropdownMenuContent`, which provides its keyboard navigation and selected state.
9
9
  - Collapsible navigation groups keep their expanded or collapsed state while the navigation tree stays mounted; opening a new page expands its ancestor groups without collapsing the others.
10
10
  - The sidebar is shadcn's `Sidebar`, composed in `client/layouts/components/app-sidebar.tsx` (provider, desktop sidebar, phone sheet, header toggle) and `navigation-menu.tsx` (the route tree as `SidebarMenu*` entries: a top-level group with no page is a section under a heading, its entries always shown; clickable parents and nested groups are controlled `Collapsible` sub-menus; counts beside entries come from the layout through its `badges`, [`page.md`](page.md#a-count-beside-an-entry)). Keep `client/components/ui/sidebar.tsx` as the shadcn CLI writes it and change the sidebar from these two files: the widths are set through the provider's `style` in spacing units (`--sidebar-width`, `--sidebar-width-icon`) so they follow the density preset; the phone sheet is rendered in `app-sidebar.tsx` with a translated title instead of the primitive's own; and the provider's Ctrl/Cmd+B shortcut is stopped by a `document` keydown listener, so the key stays with editors.
11
11
  - The desktop sidebar can collapse to icons: leaf entries then show their label in a tooltip without delay and section headings hide and their entries keep their icons, collapsible groups open in a popover on hover or keyboard focus, keeping the filtered entries, parent-page links, nested groups and the highlight of the group holding the current page. The collapsed state is shared through `useSidebarPreference` under `nocobase:sidebar:collapsed` by every application on the same origin, while whether the phone sheet is open stays local to each layout.
12
+ - Keep `RouteLeaveBoundary` in `AppLayout` outside every page Activity, including nested routes. Settings forms register with this shell boundary so navigation, confirmation dialogs and `beforeunload` protection remain active during permission checks. A final denial or session change removes the retained form guards. Activity restores Effects after a successful check, so mounted data hooks re-fetch; count those requests when assessing refresh cost.
12
13
  - The authorization provider clears the permission snapshot before rendering a new session; route navigation and page guards subscribe to the authorization revision, so account switches and permission changes take effect without a reload.
13
14
  - When signing out, the account menu checks the result from Better Auth and shows a localized error message on failure; do not treat navigating away as having signed out.
14
15
 
@@ -16,10 +17,10 @@ The shell is `client/routing/` and `client/layouts/`, with the header, sidebar a
16
17
 
17
18
  The icon button area in the top-right corner of the page is in `client/layouts/components/header-actions.tsx` (the layout's header, not `PageHeader`'s `actions`). Choose the hover behavior by what the entry does:
18
19
 
19
- | What the entry does | On hover | Examples |
20
- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------ |
21
- | Navigates to another page | Show a short tooltip describing the destination or purpose | Help, Notifications |
22
- | Opens a menu or configuration panel on the current page | Open the panel on hover; close it once the pointer leaves the trigger and panel area. Do not add a tooltip as well | Appearance, account menu |
20
+ | What the entry does | On hover | Examples |
21
+ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------- |
22
+ | Navigates to another page | Show a short tooltip describing the destination or purpose | Help, Notifications |
23
+ | Opens a menu or configuration panel on the current page | Open the panel on hover; close it once the pointer leaves the trigger and panel area. Do not add a tooltip as well | Account menu |
23
24
 
24
25
  ### Navigation entries
25
26
 
@@ -68,7 +69,7 @@ export function HeaderActions(): ReactElement {
68
69
  }
69
70
  ```
70
71
 
71
- - Keep every header entry the same size and style (`ACTION_LINK_CLASS` above matches the Appearance and account triggers).
72
+ - Keep every header entry the same size and style (`ACTION_LINK_CLASS` above matches the account trigger).
72
73
  - Keep the hint to a few words, such as "Help" or "Notification center"; do not write sentences like "Click here to go to…". It also shows on keyboard focus (Base UI's Tooltip does this by default; do not turn it off).
73
74
  - Translate both the tooltip and the `aria-label`; an unread count can be added to the `aria-label`.
74
75
  - Do not also write a native `title` attribute, or a second browser tooltip appears. An icon-only trigger must keep an accessible name.
@@ -79,7 +80,7 @@ export function HeaderActions(): ReactElement {
79
80
  - When the pointer moves from the trigger to the panel, or between a menu and the submenu it opens, the controls must stay reachable. Leave this interaction region, positioning, focus, and dismissal to the component.
80
81
  - Keep opening by click and touch, keyboard navigation, and closing with Esc.
81
82
  - Keep the component's default distinction: a panel opened by hover closes when the pointer leaves; a panel opened by click stays open until an outside click or Esc. Do not use custom mouseleave handlers, coordinate checks, timers, or extra open state to force a click-opened panel to close like a hover-opened one. Prefer the component's existing public options over reimplementing them yourself.
82
- - When selecting an item completes the action, use the component's built-in dismissal: the language radio items in the account menu have `closeOnClick`, so the menu closes immediately after a selection (`language-switcher.tsx` in the same directory); by default, radio items do not close the menu on selection. The header's Appearance popover (`client/theme/theme-settings.tsx`) stays open after a selection so you can keep adjusting, and closes the way `Popover` does by default.
83
+ - When selecting an item completes the action, use the component's built-in dismissal: the language radio items in the account menu have `closeOnClick`, so the menu closes immediately after a selection (`language-switcher.tsx` in the same directory); by default, radio items do not close the menu on selection. The account menu's Theme submenu (`client/theme/theme-settings.tsx`) keeps `closeOnClick={false}` so you can keep adjusting; Escape closes the submenu before the account menu.
83
84
 
84
85
  ### Consistency
85
86
 
@@ -14,7 +14,7 @@ The theming in the shadcn skill does not apply here: no `shadcn apply`, `shadcn
14
14
  | `client/styles.css` | Imported by `client/index.tsx`. Imports every preset (`default.css` first) and connects the variables to Tailwind: colors become `bg-*`, `text-*` and similar classes, `--radius` derives the `rounded-*` scale, and `@utility` adapters keep the shadow classes on the runtime variables |
15
15
  | `client/theme/theme-presets.ts` | The preset registry: `id` and `labelKey` per preset. The first entry is the fallback |
16
16
  | `appearance.themes.<id>` in `client/locales/*.ts` | Preset labels |
17
- | `client/theme/theme-settings.tsx` | The Appearance popover: color mode and theme |
17
+ | `client/theme/theme-settings.tsx` | The account menu’s Theme submenu: color mode and theme |
18
18
  | `client/theme/theme-provider.tsx`, `client/theme/theme-context.ts` | `AppThemeProvider`, which `client/react-providers.ts` mounts in the `root` layer, and `useThemePreset()` |
19
19
  | `client/theme/theme-preferences.ts` | Storage keys, configured defaults, and `initializeTheme()`, which `client/index.tsx` calls at startup |
20
20
  | `client.app.defaultColorScheme` and `client.app.defaultTheme` in `config.yml` | Application defaults, see [section 6](#6-application-defaults) |
@@ -22,7 +22,7 @@ The theming in the shadcn skill does not apply here: no `shadcn apply`, `shadcn
22
22
 
23
23
  How a preset takes effect:
24
24
 
25
- - A preset file sets CSS variables on `:root[data-theme='<id>']` for light and on `:root.dark[data-theme='<id>']` for dark, and the same values on `.theme-preview[data-theme='<id>']` for the thumbnails in the Appearance popover.
25
+ - A preset file sets CSS variables on `:root[data-theme='<id>']` for light and on `:root.dark[data-theme='<id>']` for dark, and the same values on `.theme-preview[data-theme='<id>']` for isolated theme previews.
26
26
  - The provider writes the chosen preset to the `data-theme` attribute of `<html>`, and `next-themes` sets the `light` or `dark` class and `color-scheme`. The `dark:` variant in `client/styles.css` is `&:is(.dark *)`, so it follows the same class.
27
27
  - Utilities read the variables at runtime: `bg-card` is `var(--card)` and `p-4` is `calc(var(--spacing) * 4)`. Switching the preset or the mode restyles every page without a rebuild.
28
28
 
@@ -200,7 +200,7 @@ Each adapter has this form:
200
200
  ### Scope of the rules
201
201
 
202
202
  - Each preset's light rule defines every color and every non-color token. Its dark rule defines every color and may override non-color values; anything it leaves out comes from the preset's light rule.
203
- - The same declarations go on the preview selectors `.theme-preview[data-theme='<id>']` and `:root.dark .theme-preview[data-theme='<id>']`, aliases included. A custom property inherits its resolved value, so an alias such as `--font-heading: var(--font-sans)` or `--sidebar: var(--card)` declared only for the page would carry the page's preset into another preset's thumbnail. Listing the preview selector in the same rule, as the template files do, keeps the two identical.
203
+ - The same declarations go on the preview selectors `.theme-preview[data-theme='<id>']` and `:root.dark .theme-preview[data-theme='<id>']`, aliases included. A custom property inherits its resolved value, so an alias such as `--font-heading: var(--font-sans)` or `--sidebar: var(--card)` declared only for the page would carry the page's preset into an isolated preview of another preset. Listing the preview selector in the same rule, as the template files do, keeps the two identical.
204
204
  - Do not reset whole Tailwind namespaces, and do not add per-page overrides to create a theme.
205
205
  - Extend the shared token contract only after design approval. An approved token needs a Tailwind mapping in `client/styles.css`, a value in every preset rule, and an entry in the token lists of `tests/client/theme-tokens.test.ts`. Do not change `components.json`, routes, component props or plugin APIs as a side effect of theme work.
206
206
 
@@ -210,11 +210,10 @@ Some values stay fixed on purpose. Know which ones, and keep your own explicit.
210
210
 
211
211
  - Arbitrary values (`text-[14px]`, `mt-[7px]`, `rounded-[…]`), container widths (`max-w-2xl`, `w-xs`), percentages and viewport units do not follow the theme, and neither do `rounded-xs`, `rounded-full` or `shadow-none`. Explicit line heights (`leading-*`, `text-sm/6`) replace the preset's line heights.
212
212
  - The template's own exceptions:
213
- - The Appearance popover panel is `w-xs max-w-[calc(100vw-2rem)]`, with a comment saying its width stays independent of density while its content uses tokens.
214
213
  - The small sizes of buttons, toggles and native selects cap their radius (see "Radius").
215
214
  - `index.html` sets `<meta name="theme-color" content="#171717">`, which colors the browser UI on some mobile browsers and does not follow the theme; change it by hand when a preset's page color changes noticeably.
216
215
  - `index.html` draws a loading indicator with literal colors that follow only `prefers-color-scheme`. It renders before the client restores the preferences, so it cannot use the tokens.
217
- - When a size must stay fixed, make it visible: a comment next to the value saying why, as `client/theme/theme-settings.tsx` does, and an entry in the design file, as guideline F7 in [`../ui-guidelines.md`](../ui-guidelines.md) requires. Colors, font sizes and spacing do not qualify.
216
+ - When a size must stay fixed, make it visible: a comment next to the value saying why, and an entry in the design file, as guideline F7 in [`../ui-guidelines.md`](../ui-guidelines.md) requires. Colors, font sizes and spacing do not qualify.
218
217
 
219
218
  ### Constraints from the token test
220
219
 
@@ -346,7 +345,7 @@ The steps below add a preset with the id `forest`.
346
345
 
347
346
  `ThemePresetId` is derived from the array, so the new id is accepted wherever a preset id is typed. `defaultThemePreset` does not decide the fallback, and no template code reads it; keep it equal to the first entry.
348
347
 
349
- 5. **Add the label** to `appearance.themes` in every application locale file, spreading the system group as [`i18n.md`](i18n.md) describes; removing or renaming a template preset rewords its key after the spread rather than editing `client/locales/system/`. `zh-CN.ts` is typed from `en-US.ts`, so the two must have the same keys or the type check fails; a label missing from both fails `tests/client/app-locale-coverage.test.ts`, which reads the registry's `labelKey` (without the label the popover would show the capitalized id). Give each preset a distinct label: it is the accessible name of the preset's radio option. Translation rules are in [`i18n.md`](i18n.md).
348
+ 5. **Add the label** to `appearance.themes` in every application locale file, spreading the system group as [`i18n.md`](i18n.md) describes; removing or renaming a template preset rewords its key after the spread rather than editing `client/locales/system/`. `zh-CN.ts` is typed from `en-US.ts`, so the two must have the same keys or the type check fails; a label missing from both fails `tests/client/app-locale-coverage.test.ts`, which reads the registry's `labelKey` (without the label the submenu would show the capitalized id). Give each preset a distinct label: it is the accessible name of the preset's radio option. Translation rules are in [`i18n.md`](i18n.md).
350
349
 
351
350
  ```ts
352
351
  // client/locales/en-US.ts
@@ -372,8 +371,8 @@ The steps below add a preset with the id `forest`.
372
371
  };
373
372
  ```
374
373
 
375
- 6. **Leave the popover alone.** The Appearance popover lists every registered preset in registry order, takes each label from the locale, and draws each thumbnail from the same CSS variables through `.theme-preview` and `data-theme`. Do not write a second palette in JavaScript. The presets sit in a two-column grid without search, so the popover suits a handful of presets.
376
- 7. **Check it.** Add the resources and the Chinese and system fallbacks for any new font. In light and dark, check body text, headings, code, long text, controls, navigation, charts where present, spacing, corners and shadows: text meets WCAG AA contrast (guideline A5; 4.5:1 for normal text), nothing is clipped, and keyboard focus is visible. The thumbnail shows colors, not typography or layout. Then run the checks in [section 7](#7-verify).
374
+ 6. **Reuse the Theme submenu.** The account menu lists every registered preset as a menu radio item in registry order and takes each label from the locale. Keep it inside the account menu; guest and optional pages inherit the saved theme without a separate appearance entry. Do not add a second theme selector or palette in JavaScript.
375
+ 7. **Check it.** Add the resources and the Chinese and system fallbacks for any new font. In light and dark, check body text, headings, code, long text, controls, navigation, charts where present, spacing, corners and shadows: text meets WCAG AA contrast (guideline A5; 4.5:1 for normal text), nothing is clipped, and keyboard focus is visible. Then run the checks in [section 7](#7-verify).
377
376
 
378
377
  ## 4. Change or remove a preset
379
378
 
@@ -390,7 +389,7 @@ The steps below add a preset with the id `forest`.
390
389
  A user makes two independent choices, each saved in the browser: the color mode (Light, Dark or System) and the preset.
391
390
 
392
391
  - `next-themes` owns the color mode: the `light` or `dark` class on `<html>` and its `color-scheme`. A preset only sets `data-theme`. Do not make a preset force a mode. Keep DOM changes in `client/theme/`.
393
- - The Appearance popover (`client/theme/theme-settings.tsx`) sits in the header of the App layout (`client/layouts/components/header-actions.tsx`) and in the top-right corner of guest and optional pages (`client/routing/standalone-page-layout.tsx`). It opens on hover, click or keyboard. A choice applies and is saved at once, the panel stays open for further changes, and Escape closes it and returns focus to the trigger. Its copy comes from `appearance.title`, `appearance.mode`, `appearance.preset`, `appearance.light`, `appearance.dark`, `appearance.system` and `appearance.themes.<id>`. The hover and dismissal rules for header entries are in [section 2 of `shell.md`](shell.md#2-header-icon-buttons).
392
+ - The Theme submenu (`client/theme/theme-settings.tsx`) lives inside the account menu (`client/layouts/components/user-menu.tsx`), whose avatar opens on hover, click or keyboard. A choice applies and is saved at once, and the submenu stays open for further changes. Escape first closes the submenu and returns focus to Theme, then closes the account menu and returns focus to the avatar. Guest and optional pages (`client/routing/standalone-page-layout.tsx`) inherit saved preferences without a theme entry. The submenu's copy comes from `appearance.title`, `appearance.mode`, `appearance.preset`, `appearance.light`, `appearance.dark`, `appearance.system` and `appearance.themes.<id>`.
394
393
  - Code that needs a choice reads it from the provider. `useTheme()` from `next-themes`, also re-exported by `client/theme/index.ts`, gives `theme` (`light`, `dark` or `system`), `resolvedTheme` (the mode actually applied) and `setTheme`. `useThemePreset()` from `client/theme/theme-context.ts` gives `preset` and `setPreset`. Both need `AppThemeProvider`, and `useThemePreset()` throws outside it. Do not read or write the storage keys or the `<html>` attributes yourself, and do not keep a copy of a choice in component state.
395
394
  - The storage keys come from `resolveAppBase()`, the deployment base path, not from the current route or the first path segment: `/crm/` becomes `crm`, `/team/crm/` becomes `team%2Fcrm`, and the root becomes `%2F`. The keys are `nocobase:<scope>:theme:color-scheme` and `nocobase:<scope>:theme:preset`. They are browser-local and per application, not synchronized with the account: two applications on the same origin keep separate choices, and tabs of the same application follow each other through `storage` events.
396
395
  - `client/index.tsx` calls `initializeTheme()` before the application starts. It applies the saved or default choices to `<html>` (class, `data-theme` and `color-scheme`) and removes an invalid saved mode before `next-themes` can read it. No script runs before the first paint; the loading indicator in `index.html` follows only `prefers-color-scheme`.
@@ -434,19 +433,19 @@ pnpm exec vitest run tests/client/theme-tokens.test.ts tests/client/theme-prefer
434
433
 
435
434
  - `theme-tokens.test.ts` checks that every registered preset defines all 32 colors and every non-color token in its light rule and every color in its dark rule, with the same declarations on the preview selectors; that Compact and Spacious differ only in dimensions, with Compact's spacing smaller; and, by compiling `client/styles.css` with Tailwind, that the color, font, size, line height, spacing, radius and shadow classes and the `body`, `h1` and `code` fonts still read the runtime variables.
436
435
  - `theme-preferences.test.ts` checks that Compact is first, the storage keys for each base path, restoring both choices at startup without reading another application's keys, and the fallbacks for invalid values, removed presets and unavailable storage.
437
- - `client-theme.test.tsx` checks the provider and the popover: labels in en-US and zh-CN, choosing and saving, configured defaults against saved choices, startup and provider agreeing, clearing and syncing across tabs, invalid values, and unavailable storage.
436
+ - `client-theme.test.tsx` checks the provider and the Theme submenu: labels in en-US and zh-CN, choosing and saving, configured defaults against saved choices, startup and provider agreeing, clearing and syncing across tabs, invalid values, and unavailable storage.
438
437
 
439
- Format the changed CSS and TypeScript files with Prettier, and lint only the TypeScript ones (ESLint has no CSS configuration; see ["Self-check before finishing" in `../frontend-dev.md`](../frontend-dev.md#self-check-before-finishing)). After changing the popover or its header entry, also run `pnpm exec vitest run tests/client/header-hover.test.tsx` (hover, keyboard and Escape). After changing the registry or a locale file, type-check the client with `pnpm exec tsc -p tsconfig.json --noEmit` and run `pnpm exec vitest run tests/client/app-locale-coverage.test.ts`.
438
+ Format the changed CSS and TypeScript files with Prettier, and lint only the TypeScript ones (ESLint has no CSS configuration; see ["Self-check before finishing" in `../frontend-dev.md`](../frontend-dev.md#self-check-before-finishing)). After changing the Theme submenu or its account-menu entry, also run `pnpm exec vitest run tests/client/header-hover.test.tsx` (hover, keyboard and Escape). After changing the registry or a locale file, type-check the client with `pnpm exec tsc -p tsconfig.json --noEmit` and run `pnpm exec vitest run tests/client/app-locale-coverage.test.ts`.
440
439
 
441
440
  A compiled CSS check cannot prove the layout. Check in a browser, scaled to the change:
442
441
 
443
442
  - **Any token change** (a color, font, size, spacing, radius or shadow):
444
- - With `pnpm dev` running, append `tests/fixtures/theme-tokens.html` to the `Local:` URL it prints, which already ends with the base path and a slash (`http://127.0.0.1:13000/main/tests/fixtures/theme-tokens.html`). The page renders the real sidebar, primitives and Appearance popover with sample headings, serif and code text, buttons, an input, a popover rendered in a portal, a card, the chart palette, and all seven radii and shadows, in mixed English and Chinese text. It mounts no translations, so the popover shows each preset's capitalized id (Default rather than Spacious); check labels in the application itself. It runs under the application's base path, so it shares the application's saved choices.
443
+ - With `pnpm dev` running, append `tests/fixtures/theme-tokens.html` to the `Local:` URL it prints, which already ends with the base path and a slash (`http://127.0.0.1:13000/main/tests/fixtures/theme-tokens.html`). The page renders the real sidebar, primitives and an account menu with the Theme submenu, plus sample headings, serif and code text, buttons, an input, a popover rendered in a portal, a card, the chart palette, and all seven radii and shadows, in mixed English and Chinese text. It mounts no translations, so the submenu shows each preset's capitalized id (Default rather than Spacious); check labels in the application itself. It runs under the application's base path, so it shares the application's saved choices.
445
444
  - Look at Light and Dark with each preset on a page that stacks panels and dividers, including at 375px wide (the screenshot tool's `colorScheme`, `theme` and `viewport` shots do this in one run; see [`../scripts/capture.md`](../scripts/capture.md)).
446
445
  - Measure contrast for every pair you changed, in both modes: body and muted text on `--background`, `--card` and `--popover`, `--primary-foreground` on `--primary`, and `--destructive` on the surfaces. In Chrome DevTools, inspect an element, click the color swatch of its `color` in the Styles pane: the picker shows the contrast ratio against the background and whether it passes AA (4.5:1 for normal text).
447
446
  - **A font, size, spacing or shadow change** additionally: temporarily set clearly different values and confirm the pages follow, since a token name existing does not prove it is used; revert afterwards. Look for fixed sizes, explicit line heights, constrained controls and portal content such as menus, dialogs and popovers.
448
- - **Adding, removing or renaming a preset, or changing the registry, the popover or the preference code** additionally:
449
- - Reload and confirm both choices are restored. Operate the popover with the keyboard: Tab into a group, arrow keys within it, Escape to close with focus back on the trigger.
447
+ - **Adding, removing or renaming a preset, or changing the registry, the Theme submenu or the preference code** additionally:
448
+ - Reload and confirm both choices are restored. Operate the account menu and Theme submenu with the keyboard: arrow keys navigate items, Enter selects an option, and Escape closes the submenu with focus back on Theme, then closes the account menu with focus back on the avatar.
450
449
  - Two tabs of the application stay in sync; an application under another base path on the same origin is unaffected.
451
450
  - Clearing site data restores the configured defaults; with storage blocked, switching still works; a saved id of a removed preset falls back.
452
451
  - Images, iframes, style-isolated third-party content and plugin content with literal colors do not follow the theme. Check them separately.
@@ -52,7 +52,7 @@ The one way to pick an agent: a trigger with the agent's avatar (availability do
52
52
 
53
53
  ### agent-chat
54
54
 
55
- The agents' chat: a side panel beside the content area, switching between the online agent and runner agents when both are configured, with the conversation, live steps, a composer with page-context chips and files to send (attach, paste, drop), the agent picker, the history, a full-page conversation view, and header, floating and Ask agent launchers. Use it to let people talk to agents from any page. Wired to the headless hooks of @nocobase/app-plugin-agents/client/chat.
55
+ A simple agent conversation panel with shared page/panel headers, history, composer and launchers. It has no association requirements. For related-work slots and conversation details, add agent-chat-details.
56
56
 
57
57
  - Kind: block
58
58
  - Install: `yes n | pnpm exec shadcn add @nocobase/agent-chat`
@@ -62,6 +62,18 @@ The agents' chat: a side panel beside the content area, switching between the on
62
62
  - Example: `@nocobase/agent-chat-demo` (`pnpm exec shadcn view @nocobase/agent-chat-demo`)
63
63
  - After installing: Requires the agents plugin (and the file plugin on the server for files sent in chat): wrap the routes in ChatProvider from @nocobase/app-plugin-agents/client/chat (pass memoryScope, the signed-in person's id, so a new conversation starts with the agent they used last; pass conversationPath when ChatConversationPage has a route such as /chat/:conversationId), optionally with ChatExtensionsContext for cards among the messages. Render ChatPanel as a sibling of <main> inside a `relative flex` row, ChatHeaderButton in the header and ChatFloatingButton anywhere; add the plugin's chatLinkRoutes(base) for links that open the panel; spread locales/ into client/locales/.
64
64
 
65
+ ### agent-chat-details
66
+
67
+ The agent chat workspace: the conversation list, one conversation and its details (linked work such as tasks, context usage, runtime and agent), laid out by its own width as one column, list beside conversation, or list, conversation and details. Mount it as a full page with the selection in the address, or in the side panel with LinkedChatPanel; both are the same component. Linked work uses generic ConversationLink sections; applications add their own through narrow slots. No task or project dependency.
68
+
69
+ - Kind: block
70
+ - Install: `yes n | pnpm exec shadcn add @nocobase/agent-chat-details`
71
+ - Installs to: `client/extensions/nocobase-agent-chat/`
72
+ - Plugin dependencies: none
73
+ - Also installs: `@nocobase/agent-chat`
74
+ - Example: `@nocobase/agent-chat-details-demo` (`pnpm exec shadcn view @nocobase/agent-chat-details-demo`)
75
+ - After installing: Mount ChatWorkspace on a page (selection in the address) and LinkedChatPanel under the same ChatProvider as the simple ChatPanel (selection in the panel store); both are the same workspace. Add application-specific parts through narrow slots: list.heading, list.row (extra, facts, status), list.filters/filter, renderBody, metadata, detailsMetadata and scope; slots[kind] renders a related-work section and renderSummary the summary row. Passive details reuse cached conversation and usage snapshots; no polling is added.
76
+
65
77
  ## Approval
66
78
 
67
79
  ### approval-ui
@@ -273,10 +285,10 @@ Read-only React Flow canvas with ELK orthogonal routing for directed graphs, inc
273
285
 
274
286
  - Kind: component
275
287
  - Install: `yes n | pnpm exec shadcn add @nocobase/flow-diagram`
276
- - Installs to: `client/components/flow-diagram.tsx`, `client/components/flow-layout.ts`, `client/components/flow-diagram-css.d.ts`
288
+ - Installs to: `client/components/flow-diagram.tsx`, `client/components/flow-layout.ts`, `client/components/flow-diagram-css.d.ts`, `client/components/body-portal.tsx`
277
289
  - Plugin dependencies: none
278
290
  - Example: `@nocobase/flow-diagram-demo` (`pnpm exec shadcn view @nocobase/flow-diagram-demo`)
279
- - After installing: Pass nodes and edges with unique ids, an ariaLabel and either a bounded canvas height or autoHeight. Use direction DOWN with autoHeight for detailed page diagrams; height follows the full layout including outer routes and labels. The default node is 232×104 canvas units; set width/height for richer renderNode content. direction is RIGHT or DOWN. nodeDescription and nodeActions add supporting summaries and configuration controls. For bounded canvases, initialMinZoom=0.8 preserves initial readability and showMiniMap provides overview navigation; Fit still shows the whole graph. Translate flowDiagram.overview when using the minimap. onNodeClick/onEdgeClick open your details; onLayoutError reports invalid graph or layout failures. Translate flowDiagram.empty, loading, failed, nodeHelp and edgeHelp; see the components README. Includes React Flow CSS. Uses application primary/card/foreground/border tokens in light and dark themes. Ordinary edges are subdued, solid and labeled directly on the route. Set visited on nodes/edges for actual history and highlighted for the current node or available edges; current nodes have a stronger fill and ring. ELK optimizes port order to reduce crossings. Decorative nodes/edges are not focusable or selectable.
291
+ - After installing: Pass nodes and edges with unique ids, an ariaLabel and either a bounded canvas height or autoHeight. Use direction DOWN with autoHeight for detailed page diagrams; height follows the full layout including outer routes and labels. The default node is 232×104 canvas units; set width/height for richer renderNode content. direction is RIGHT or DOWN. nodeDescription and nodeActions add supporting summaries and configuration controls. For bounded canvases, initialMinZoom=0.8 preserves initial readability and showMiniMap provides overview navigation; Fit still shows the whole graph. Translate flowDiagram.overview when using the minimap. onNodeClick/onEdgeClick open your details; onLayoutError reports invalid graph or layout failures. Translate flowDiagram.empty, loading, failed, nodeHelp and edgeHelp; see the components README. Includes React Flow CSS. Uses application primary/card/foreground/border tokens in light and dark themes. Ordinary edges are subdued, solid and labeled directly on the route. Set visited on nodes/edges for actual history and highlighted for the current node or available edges; current nodes have a stronger fill and ring. ELK optimizes port order to reduce crossings. Decorative nodes/edges are not focusable or selectable. Body portals detach when React Activity hides the diagram, retaining component state without leaving fullscreen content visible during permission rechecks.
280
292
 
281
293
  ### lifecycle-diagram
282
294
 
@@ -8,7 +8,7 @@ For approval-specific requests, tasks and decisions, first follow [approval plug
8
8
 
9
9
  Use the UI Library `workflow-management` block as the default starting point; it extracts the existing workflow example's layout and interactions. Adapt its business labels, data sources and supported operations to the application; do not require its example plugins as production dependencies. The sidebar has one clickable entry, System management → Workflow management. Its landing page has one Workflow management header and in-page Definitions and Executions tabs; these are two views of the same management page, not separate sidebar entries or a sidebar submenu. Definitions lead to full detail pages with a process diagram and visible parameter settings beside it; executions lead to full detail pages with a diagram, transition history, effect status and recorded parameter information. Include implemented workflows even when there is only one. Show an explicit empty state for definitions without adjustable parameters and for workflows without executions; add category management when classification is useful.
10
10
 
11
- Create the System management group if it is missing, or reuse the application's existing Settings group. Place Workflow management directly under that group, alongside User management, Roles and permissions, Background tasks and other applicable administration entries. Keep workflow execution inspection inside Workflow management; do not add an intermediate Operational monitoring group. Deliver real catalog and execution data, initial administrator grants and working page/API authorization alongside the process. Follow [system administration](system-administration.md) for the complete application's administration baseline and authenticated acceptance checks. Workflow configuration stays separate from business submit, approve and fulfil pages, and does not imply a visual workflow designer.
11
+ Register Workflow management as one module card in the Business configuration category of System settings ([System settings navigation](settings-navigation.md)), alongside the Users, Permission management, Background tasks and other applicable administration cards. Keep workflow execution inspection inside Workflow management; do not add an intermediate Operational monitoring group. Deliver real catalog and execution data, initial administrator grants and working page/API authorization alongside the process. Follow [system administration](system-administration.md) for the complete application's administration baseline and authenticated acceptance checks. Workflow configuration stays separate from business submit, approve and fulfil pages, and does not imply a visual workflow designer.
12
12
 
13
13
  ## Install and connect the block
14
14
 
@@ -20,9 +20,9 @@ Render the preinstalled `LifecycleDiagram` through the diagram slot/callback by
20
20
 
21
21
  ## Navigation and ownership
22
22
 
23
- Separate business work (submit, approve, fulfil) from administration (definitions, categories, parameters, executions). Place the single Workflow management entry under the existing System management or Settings group; definitions, categories, parameters and executions are views or controls within it. Use separate read and update permissions. Configuration permission does not grant business approval permission. Use the real authenticated identity rather than demonstration identity switchers.
23
+ Separate business work (submit, approve, fulfil) from administration (definitions, categories, parameters, executions). Register the single Workflow management module in System settings; definitions, categories, parameters and executions are views or controls within it. Use separate read and update permissions. Configuration permission does not grant business approval permission. Use the real authenticated identity rather than demonstration identity switchers.
24
24
 
25
- Within the workflow route subtree, declare `navigation` only on the Workflow management route. Implement Definitions and Executions as URL-backed child routes without `navigation`; their breadcrumb declarations do not make them sidebar entries. Render the child list through `Outlet` beneath the shared page header and line-style Tabs, using the URL to select the active tab and navigating on tab changes. Redirect the parent to its default accessible child. The example uses `/workflows`, `/workflows/definitions` and `/workflows/executions`; adapt the route prefix to the application. Preserve direct links, reloads and browser back/forward behavior. Keep the single Workflow management sidebar item active across both tabs and their detail pages. Give diagram-heavy details full child pages through Outlet; suppress the parent's list header, filters and tabs while a detail is open. Use the shell breadcrumb trail: System management → Workflow management → Definitions or Executions → current item. Preserve the list's query parameters in its breadcrumb instead of adding a competing Back link.
25
+ Within the workflow route subtree, declare `navigation` only on the Workflow management route. Implement Definitions and Executions as URL-backed child routes without `navigation`; their breadcrumb declarations do not make them sidebar entries. Render the child list through `Outlet` beneath the shared page header and line-style Tabs, using the URL to select the active tab and navigating on tab changes. Redirect the parent to its default accessible child. The example uses `/workflows`, `/workflows/definitions` and `/workflows/executions`; adapt the route prefix to the application. Preserve direct links, reloads and browser back/forward behavior. Keep the System settings sidebar entry active across both tabs and their detail pages. Give diagram-heavy details full child pages through Outlet; suppress the parent's list header, filters and tabs while a detail is open. Use the shell breadcrumb trail: System settings → Workflow management → Definitions or Executions → current item. Preserve the list's query parameters in its breadcrumb instead of adding a competing Back link.
26
26
 
27
27
  ## Definition catalog
28
28
 
@@ -14,7 +14,7 @@ The lifecycle examples below illustrate state transitions, guards and effects, n
14
14
 
15
15
  ## Deliver workflow management by default
16
16
 
17
- Whenever application requirements include a process to develop, include workflow management pages alongside its business operations; users do not need to request a console separately. Reuse or extend existing management pages with the UI Library `workflow-management` block and follow [Lifecycle UI](lifecycle-ui.md) for the default layout and organization based on the workflow example. Deliver one Workflow management sidebar entry with in-page Definitions and Executions tabs, definition details with diagrams and declared parameter settings, and execution details with history and effects. The tab views have URL-backed child routes without sidebar `navigation`. Follow the scope exceptions in [system administration](system-administration.md#default-delivery). Keep workflow structure in source; management pages do not imply a visual designer.
17
+ Whenever application requirements include a process to develop, include workflow management pages alongside its business operations; users do not need to request a console separately. Reuse or extend existing management pages with the UI Library `workflow-management` block and follow [Lifecycle UI](lifecycle-ui.md) for the default layout and organization based on the workflow example. Deliver one Workflow management card in System settings with in-page Definitions and Executions tabs, definition details with diagrams and declared parameter settings, and execution details with history and effects. The tab views have URL-backed child routes without sidebar `navigation`. Follow the scope exceptions in [system administration](system-administration.md#default-delivery). Keep workflow structure in source; management pages do not imply a visual designer.
18
18
 
19
19
  ## Choose it or something else
20
20
 
@@ -90,16 +90,20 @@ A department an administrator creates stores its title as plain text. A seeded d
90
90
 
91
91
  ## Settings page
92
92
 
93
- Declare one page in `client/routes.ts` with `defineAppRoutes`, titled with the same key and placed under the application's Settings navigation group (a group whose `path` is `/settings`, see [section 5 of `page.md`](../frontend/references/page.md#5-settings-pages)); the department details are a child route, so they inherit the entry page's `authz`:
93
+ Declare one page in `client/routes.ts` with `defineAppRoutes`, titled with the same key and placed as a card in the Accounts and permissions category of System settings ([System settings navigation](../settings-navigation.md)); the department details are a child route, so they inherit the entry page's `authz`:
94
94
 
95
95
  ```ts
96
96
  defineAppRoutes([
97
97
  {
98
- // Appended to the application's own Settings group; the page is at /settings/departments.
99
- parent: 'settings',
98
+ // A card in the Accounts and permissions category; in Default the page is at /settings/departments.
99
+ parent: 'settingsAccount',
100
100
  name: 'departments',
101
101
  path: '/departments',
102
- navigation: { title: 'navigation.departments', icon: Network },
102
+ navigation: {
103
+ title: 'navigation.departments',
104
+ description: 'navigation.departmentsDescription',
105
+ icon: Network,
106
+ },
103
107
  authz: {
104
108
  resource: { type: 'settings', id: 'departments' },
105
109
  action: 'read',
@@ -0,0 +1,72 @@
1
+ # System settings navigation
2
+
3
+ Every administration surface of an application lives under one System settings entry in the sidebar. Opening it shows a home page of cards grouped by category; a card opens one module; a module with several views shows them as tabs. Build every administration page into this structure without the user asking for it, and keep everyday business entries — the inbox, approval to-dos, a team's mailbox, a knowledge base people read — in the business navigation even when their names sound administrative.
4
+
5
+ ## The structure is the route tree
6
+
7
+ The templates register the structure in `client/routes.ts` (Default: `client/pages/settings/shell-routes.ts`; Examples: its `systemManagement` group) and the navigation transform in `client/lib/navigation-transform.ts` renders it. Nothing is hand-written per card: the home page and the tabs read the registered routes through the shell's single permission check.
8
+
9
+ | Level | Route | Shown as |
10
+ | -------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
11
+ | Settings group | the group holding `settingsHome` (`settings` in Default, `systemManagement` in Examples) | one sidebar entry, selected on every page below it |
12
+ | Category | a direct child group: `settingsAccount`, `settingsBusiness`, `settingsAi`, `settingsSystem` | a heading on the home page, hidden while the viewer can open nothing in it |
13
+ | Module | a page or a group inside a category | one card: icon, `navigation.title`, `navigation.description`, arrow |
14
+ | Tab | a page with `navigation` inside a module group | a URL-backed tab in `SettingsModulePage` |
15
+
16
+ - Register a module with `parent` naming its category, and give it `navigation.title`, `navigation.description` (one sentence on what it is for, translated like the title) and an icon. A card without a description is incomplete.
17
+ - A module with one view is a page; it renders its content directly, with no single tab. A module with several views is a group with `breadcrumb` whose pages each declare `navigation` and `authz`; wrap each view in `SettingsModulePage` from `client/pages/settings/settings-module-page.tsx`, which derives the tabs, hides the ones the viewer may not open and drops the tab bar when only one remains. The card opens the first tab the viewer may open. A module whose page already has its own tabs, such as workflow management's definitions and executions layout, stays a page.
18
+ - Categories are application-owned: rename, reorder (`navigation.order`), add or remove them in the same place. A page registered directly under the settings group, as a plugin's settings page is (App Foundation), is shown in `settingsSystem`.
19
+ - Never add another sidebar entry, a second settings layout, a resident settings sidebar or a hand-written card list. Never register a placeholder card for a capability the application does not use, and never put a dead link or a page that only says "coming soon" in a category.
20
+ - The home page (`settingsHome`) is `authz: 'skip'`: it grants nothing and lists only what the viewer may open. Hiding a card is presentation; every module keeps its own `authz` and its server checks.
21
+
22
+ ## URLs, breadcrumbs and permissions
23
+
24
+ Each module and tab keeps a URL of its own, so refresh, bookmarks and Back and Forward work, and the trail reads System settings → module → view with System settings linking back to the home. Moving an existing page into the structure changes its `parent` only: keep its route `name`, `path` and `authz`, so its page id, stored grants and deep links keep working. A pathless group adds nothing to its children's URLs; in Default the settings group's `/settings` prefix is already part of the existing settings URLs. If a URL must change, keep the old one working with a redirect route and say so in the delivery.
25
+
26
+ ## Standard modules
27
+
28
+ | Module | Route | Views |
29
+ | --------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
+ | Users | `settingsUsers` in `settingsAccount` (`client/pages/settings/routes.ts`) | one page |
31
+ | Permission management | `permissionManagement` group in `settingsAccount` | Roles and permissions (`settingsRoles`), Default data scopes (`settingsDefaultAccess`) |
32
+ | Workflow management | `workflows` page in `settingsBusiness` | its own definitions and executions tabs |
33
+ | Notifications | `notificationManagement` group in `settingsSystem`, path prefix `/notifications` | the views the application actually has: Delivery logs (`notificationLogs`, the UI Library `notification-logs-ui` page); Notification templates (`notificationTemplates`) when the application provides the catalogue |
34
+ | App Foundation | the Foundation plugin's `foundation` page, shown in `settingsSystem` | one page |
35
+
36
+ The templates' `includeNotificationTemplateRoutes` (`client/pages/settings/notification-routes.ts`) adds the Notification templates view (`/settings/notifications/templates`, `page:notification.templates`) to an existing `notificationManagement` group exactly once, or creates the group in `settingsSystem` when notification business is in use. Register Delivery logs and any later notification view in the same group rather than as another card, adding its title key to the application's locales:
37
+
38
+ ```ts
39
+ defineAppRoutes([
40
+ {
41
+ parent: 'settingsSystem',
42
+ name: 'notificationManagement',
43
+ navigation: {
44
+ title: 'settings.notificationManagement',
45
+ description: 'settings.notificationManagementDescription',
46
+ icon: Bell,
47
+ },
48
+ breadcrumb: { title: 'settings.notificationManagement' },
49
+ children: [
50
+ {
51
+ // Default: /settings/notifications/logs. The page checks the same grant as GET /api/notifications/logs.
52
+ name: 'notificationLogs',
53
+ path: '/notifications/logs',
54
+ auth: 'required',
55
+ authz: {
56
+ resource: { type: 'page', id: 'notification.logs' },
57
+ action: 'access',
58
+ },
59
+ navigation: { title: 'settings.notificationLogs' },
60
+ breadcrumb: { title: 'settings.notificationLogs' },
61
+ componentLoader: () => import('./pages/settings/notification-logs.js'),
62
+ },
63
+ ],
64
+ },
65
+ ]);
66
+ ```
67
+
68
+ Install the block with `yes n | pnpm exec shadcn add @nocobase/notification-logs-ui`. While Delivery logs is the module's only view, the page renders `NotificationLogsPage` from `#extensions/nocobase-notification-logs-ui/index` in a `PageContainer`; the block brings its own heading. When a second view such as Notification templates joins the group, render each view inside `SettingsModulePage` (titled with the module) and drop the block's own heading in the installed source, so the module has one heading above its tabs.
69
+
70
+ ## Checks
71
+
72
+ Cover the structure in the application's tests: the sidebar has one settings entry selected on every settings URL, the home groups the expected cards with their descriptions, an empty category is hidden, a restricted viewer sees only the cards and tabs their grants open, and the existing URLs and `authz` of moved pages are unchanged. `tests/client/settings-navigation.test.ts` and `tests/client/settings-home.test.tsx` in the templates are the starting point.
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Default delivery
4
4
 
5
- A complete application includes System management navigation and working administration pages by default. Users asking for a CRM, an order system or another business application do not need to enumerate its administrative infrastructure. Follow explicit exclusions and narrower deliverables such as API-only services or prototypes explicitly limited to business screens. For an individual feature, integrate its administration into the existing application.
5
+ A complete application includes the System settings structure and working administration pages by default. Users asking for a CRM, an order system or another business application do not need to enumerate its administrative infrastructure. Follow explicit exclusions and narrower deliverables such as API-only services or prototypes explicitly limited to business screens. For an individual feature, integrate its administration into the existing application.
6
6
 
7
7
  Inspect existing routes, pages, plugin registrations and plugin Skills before implementing administration. Reuse installed capabilities and existing management pages; create application-owned pages for missing interfaces. Deliver real data, actions and initial permission configuration, rather than empty menu entries or placeholder pages. Follow the normal plugin installation workflow when a required capability is missing.
8
8
 
@@ -19,9 +19,9 @@ Add management pages for the capabilities the application uses: organizations an
19
19
 
20
20
  ## Navigation and access
21
21
 
22
- Group administrative capabilities under a consistent System management or Settings section, separate from business navigation. Reuse an existing group and follow [settings pages](frontend/references/page.md#5-settings-pages); management pages use the application's normal layout. Use the UI Library `workflow-management` block for workflow administration, following [Lifecycle UI](lifecycle-ui.md) for installation, navigation and application-owned data/permission adapters.
22
+ Place administrative capabilities in the application's System settings structure, separate from business navigation: one sidebar entry, a home page of cards by category, and tabs inside a module ([System settings navigation](settings-navigation.md)). Management pages use the application's normal layout. Use the UI Library `workflow-management` block for workflow administration, following [Lifecycle UI](lifecycle-ui.md) for installation, navigation and application-owned data/permission adapters.
23
23
 
24
- Place User management, Roles and permissions, Workflow management, Background tasks and other applicable capabilities directly under System management as sibling menu entries. Include capability-specific entries only when the application uses those capabilities. Do not introduce an Operational monitoring menu or an intermediate monitoring group. Workflow management is a single clickable sidebar entry whose page switches between Definitions and Executions with in-page tabs. These views retain URL-backed child routes without sidebar `navigation`; background task pages own their task status, execution history, failures and supported recovery actions. Notification management similarly owns delivery records. Follow the same structure under an existing Settings section.
24
+ Register User management, Permission management, Workflow management, Background tasks and other applicable capabilities as module cards in the System settings categories. Include capability-specific cards only when the application uses those capabilities. Do not introduce an Operational monitoring card or category. Workflow management is a single card whose page switches between Definitions and Executions with in-page tabs. These views retain URL-backed child routes without sidebar `navigation`; background task pages own their task status, execution history, failures and supported recovery actions. Notification management similarly owns delivery records, and later notification views join its tabs.
25
25
 
26
26
  Configure initial administrator access through the supported authentication and authorization mechanisms. A signed-in administrator must be able to discover and use the management section. Distinguish administrative read and update access, and keep configuration permissions separate from business operations such as approvals. Enforce access in menu visibility, direct page access and server-side operations. Ordinary users receive only explicitly granted access.
27
27
 
@@ -29,4 +29,4 @@ Configure initial administrator access through the supported authentication and
29
29
 
30
30
  Verify with a real authenticated administrator that the management entry appears, its pages load actual data, and permitted management operations succeed. Verify with an ordinary user that restricted menus, direct URLs and API operations are protected. Where read-only administration is supported, verify that reading succeeds and updates are denied.
31
31
 
32
- Verify that applicable management entries are siblings directly under System management, with execution records and failures accessible inside each capability. When the application includes workflows, verify that Workflow management has one sidebar entry and that Definitions and Executions appear only as tabs within its page. For workflows, verify that implemented definitions and business executions appear in management, parameter changes respect their effective timing, and execution history and failures remain inspectable. Use the [Lifecycle UI verification guidance](lifecycle-ui.md#source-examples-and-verification) for detail navigation and presentation. Report any unverified behavior and its missing prerequisites explicitly.
32
+ Verify that the sidebar has one System settings entry, that applicable management modules are cards of its home in the right categories, and that execution records and failures are accessible inside each capability. When the application includes workflows, verify that Workflow management has one card and that Definitions and Executions appear only as tabs within its page. For workflows, verify that implemented definitions and business executions appear in management, parameter changes respect their effective timing, and execution history and failures remain inspectable. Use the [Lifecycle UI verification guidance](lifecycle-ui.md#source-examples-and-verification) for detail navigation and presentation. Report any unverified behavior and its missing prerequisites explicitly.
@@ -4,9 +4,9 @@ A usable application includes administration for the capabilities it uses. Do no
4
4
 
5
5
  ## Baseline
6
6
 
7
- A newly created Default application shows Home and the existing protected System settings → App Foundation entry for an unrestricted administrator. Other users do not see that entry. It does not enable business settings or their prerequisite checks merely because plugins are installed. The template includes reusable application-owned Users and Roles and permissions page modules, ready to enable as the application develops. Examples is already a built application and registers them.
7
+ A newly created Default application shows Home and, for an unrestricted administrator, one System settings entry whose home page holds the protected App Foundation card. Other users do not see that entry. It does not enable business settings or their prerequisite checks merely because plugins are installed. The template includes reusable application-owned Users and Permission management page modules, ready to enable as the application develops. Examples is already a built application and registers them. Every administration surface joins the System settings structure — one sidebar entry, a home page of cards by category, tabs inside a module — described in [System settings navigation](settings-navigation.md); follow it for every module this reference asks for.
8
8
 
9
- As business capabilities are developed, automatically supply core user and permission administration and any management surfaces those capabilities need. If the core settings routes are still absent, import `systemSettingsRoutes` from `./pages/settings/routes.js` in `client/routes.ts` and append it once to the exported route contribution array: `const routes: readonly AppClientRouteContribution[] = [appRoutes, systemSettingsRoutes]`. Reuse an existing registration instead of duplicating it. If System management already exists, register the contribution's child routes with `parent: 'systemManagement'` (using the existing group's actual name), instead of registering a second settings group so Users, Roles and permissions, Workflow management and other administration entries appear together while retaining their URLs and permission ids. Do not make the user ask for user or permission settings separately, and do not grant access to ordinary users as a side effect. Existing applications that predate these modules should install or build equivalent real management pages as part of the current development task when needed. Preserve already enabled pages and their server authorization on every iteration. Do not use a first-build flag, a one-time setup stage, or the number of development rounds as the trigger. Reuse UsersClient and AuthorizationClient; the plugins own accounts, role scopes, grants, protected sets and their invariants. Keep personal account and appearance controls in the existing account/header surfaces.
9
+ As business capabilities are developed, automatically supply core user and permission administration and any management surfaces those capabilities need. If the core settings routes are still absent, import `systemSettingsRoutes` from `./pages/settings/routes.js` in `client/routes.ts` and append it once to the exported route contribution array after the settings shell: `const routes: readonly AppClientRouteContribution[] = [appRoutes, settingsShellRoutes, systemSettingsRoutes]`. Its routes join the shell's Accounts and permissions category through `parent: 'settingsAccount'`. Reuse an existing registration instead of duplicating it, and never register a second settings group: Users, Permission management, Workflow management and other administration modules appear as cards of the one System settings home while retaining their URLs and permission ids. Do not make the user ask for user or permission settings separately, and do not grant access to ordinary users as a side effect. Existing applications that predate these modules should install or build equivalent real management pages as part of the current development task when needed. Preserve already enabled pages and their server authorization on every iteration. Do not use a first-build flag, a one-time setup stage, or the number of development rounds as the trigger. Reuse UsersClient and AuthorizationClient; the plugins own accounts, role scopes, grants, protected sets and their invariants. Keep personal account and appearance controls in the existing account/header surfaces.
10
10
 
11
11
  ## Reconcile administration on every iteration
12
12
 
@@ -86,7 +86,7 @@ For approval policy, default to snapshot semantics for a formal submission unles
86
86
 
87
87
  Check every applicable row above, not just the capability named by the user. Include a concise delivery map in the development report: capability, working entry, owning persistence/API, permission, execution consumer, and observed evidence or explicit limitation. Read [acceptance scenarios](business-administration.md#acceptance-scenarios) for blind-prompt and iteration checks. This is development evidence, not implementation detail to display to application users.
88
88
 
89
- Before finishing, map each used capability to its working management entry, route, real API, server-side permission and verification evidence. Group entries under the existing System management or Settings navigation section, with workflow definitions and executions as page tabs rather than sibling menus; hide an empty group after permission filtering. Repeated additions reconcile missing entries only: no duplicate menus, role seeds or configuration. Preserve existing stable route ids and unrelated administrator grants. Verify an authorized administrator, a user without management access, direct API denial, loading/empty/error states, write failure, deep links, Chinese/English, dark/light and narrow layouts. Keep execution data current through the existing realtime mechanism or a working Refresh action. For inferred threshold and reviewer parameters, save a different valid configuration and prove that a new eligible business execution uses it; also verify invalid values, an unauthorized update, snapshot preservation and repeated iterations without duplicate fields or bindings.
89
+ Before finishing, map each used capability to its working management entry, route, real API, server-side permission and verification evidence. Place entries as cards of the System settings home ([System settings navigation](settings-navigation.md)), with workflow definitions and executions as page tabs rather than sibling cards; an empty category is hidden after permission filtering. Repeated additions reconcile missing entries only: no duplicate menus, role seeds or configuration. Preserve existing stable route ids and unrelated administrator grants. Verify an authorized administrator, a user without management access, direct API denial, loading/empty/error states, write failure, deep links, Chinese/English, dark/light and narrow layouts. Keep execution data current through the existing realtime mechanism or a working Refresh action. For inferred threshold and reviewer parameters, save a different valid configuration and prove that a new eligible business execution uses it; also verify invalid values, an unauthorized update, snapshot preservation and repeated iterations without duplicate fields or bindings.
90
90
 
91
91
  ## Role list presentation
92
92
 
@@ -100,7 +100,7 @@ For Create actions, use `hiddenActionScopes` to omit a selector for the new reco
100
100
 
101
101
  ## Default data scope administration
102
102
 
103
- When the application exposes role management and uses the Default Access plugin, include the template's `/default-access` system settings contribution and its create/details child routes. The default template supplies this in `client/pages/settings/routes.ts`; Examples registers it under System management. Show one Permission management sidebar entry with Roles and permissions and Default data scopes as URL-backed tabs, leaving Users as a sibling. The application navigation transform selects the first readable tab and represents both existing routes with one entry. Keep existing paths, route ids and authorization requirements; do not add placeholder entries for rule editors the application does not expose. The list and form call `authorization/defaultAccess` and `/options`, with the existing `settings:authorization.default-access` read/create/update/delete requirements. Read permission allows full inspection; only create/update/delete permit writes. Use the Registry `default-access-editor` for the controlled fields and `PermissionFilter` for native custom conditions. Explain that baseline ranges apply to identities already holding an operation and remain subject to restrictions. Never equate a baseline rule with granting the operation itself.
103
+ When the application exposes role management and uses the Default Access plugin, include the template's `/default-access` system settings contribution and its create/details child routes. The default template supplies this in `client/pages/settings/routes.ts`; Examples registers it under System management. Show one Permission management card with Roles and permissions and Default data scopes as URL-backed tabs (`SettingsModulePage`), leaving Users as a sibling card. The card opens the first readable tab, and a viewer who may open only one of them sees it without a tab bar. Keep existing paths, route ids and authorization requirements; do not add placeholder entries for rule editors the application does not expose. The list and form call `authorization/defaultAccess` and `/options`, with the existing `settings:authorization.default-access` read/create/update/delete requirements. Read permission allows full inspection; only create/update/delete permit writes. Use the Registry `default-access-editor` for the controlled fields and `PermissionFilter` for native custom conditions. Explain that baseline ranges apply to identities already holding an operation and remain subject to restrictions. Never equate a baseline rule with granting the operation itself.
104
104
 
105
105
  On template upgrades reconcile the editor, list/form/model, route contribution, filter-label helper and locales. Preserve stored rule keys, resources, actions, record IDs and filter parameters; do not seed, rewrite or select All records during browsing or upgrades. Unknown metadata stays visible and read-only. The existing API has no atomic revision precondition, so re-read the target before replacing actions or deleting and refuse a detected stale edit.
106
106
 
@@ -117,3 +117,7 @@ Reuse the prepared Users page for role membership rather than creating another m
117
117
  The prepared lists keep paging and sorting in URL state through `#hooks/use-table-url-state`. Preserve query strings in child links, close destinations and contextual configuration links. Correct pages beyond the last loaded page after a successful write/refetch; never clamp using stale rows while a query is loading or failed. Return destinations are application-relative and validated with `client/lib/return-to.ts`; never navigate to an arbitrary external URL. On success update the displayed record from the response and refresh the owning list; on failure/conflict retain the draft and require explicit confirmation before discarding it. Verify filtered list → detail/edit → failed save → successful save → close/return and browser history, not merely a successful toast.
118
118
 
119
119
  `WorkflowDefinitionList.onSort` is optional: omit it when the adapter cannot actually order results instead of passing a no-op. Omit `name` when there is no useful secondary identifier; a linked title should not be accompanied by the same display name again. Registry components and template copies evolve together, and template upgrades merge these integrations without replacing application-specific routes, grants or edited policy.
120
+
121
+ ## Notification template directory
122
+
123
+ When notification business is used, include the existing Notification plugin’s source-owned read-only directory and synthetic preview in the same delivery. Read its `references/template-directory.md`, enumerate actual send call sites, register the shared real renderers and explicitly document dynamic or unregistered messages. Mount `notificationTemplates` in the existing `notificationManagement` module; use the template’s `includeNotificationTemplateRoutes` on the complete host route composition once, or insert its `notificationTemplateRoute` when that module already exists. Preserve the app-owned server bootstrap provider and Default runtime route factory: a configured built-in invitation mailer automatically enables the directory after restart, and an unused bare Default stays empty. Keep `page:notification.templates/access` restricted on both page and APIs. Distinguish a definition, channel configuration and business activation. Do not add an empty menu to a bare application with no notification business.
@@ -124,6 +124,8 @@ When the target adds standard form feedback, follow [form feedback source upgrad
124
124
 
125
125
  When the template changes the permission workspace, follow [Permission editor source upgrades](references/edge-cases.md#permission-editor-source-upgrades). Merge copied permission models and translations while preserving application-specific descriptions, grants and role behavior; a dependency update alone does not update them.
126
126
 
127
+ When the template introduces or changes the System settings structure (one settings entry, a home page of cards, tabs inside a module), follow [System settings navigation upgrades](references/settings-navigation-upgrade.md). Merge the navigation transform, routing, settings pages and locales, and move existing administration pages into categories without changing their names, paths or authorization; updating dependencies alone keeps the old navigation.
128
+
127
129
  When the template changes list-return behavior, read [list navigation upgrades](references/list-navigation-upgrade.md). Merge the routing context, breadcrumb and back-link sources together, and examine application-owned detail links and forms; updating dependencies alone does not update these copied sources.
128
130
 
129
131
  When the template changes loading, empty, filtered or failed list feedback, follow [list feedback source upgrades](references/list-feedback-upgrade.md). Reconcile copied components, request owners, translations and business empty content together, and verify both new and upgraded applications with retained permissions and records.
@@ -208,3 +210,5 @@ Compare BASE directly with TARGET and merge the resulting changes once. Check th
208
210
  When the target adds or changes the standard process UI sources, also follow [standard process management source upgrades](references/edge-cases.md#standard-process-management-source-upgrades): confirm existing process pages actually consume the merged components, while preserving explicit user customizations, parameters, grants and history.
209
211
 
210
212
  When the target introduces standard submission protection, follow [submission source upgrades](references/submission-upgrade.md) during planning and reconciliation. Dependency or version-marker changes alone do not update copied forms, custom actions or the application's receipt migrations. Verify both a fresh application and retained customized data.
213
+
214
+ For a target that adds notification template administration, follow [notification template source reconciliation](references/notification-template-upgrade.md) in the same version-selected upgrade, preserving business renderers, workflows, permissions and channel configuration.
@@ -0,0 +1,12 @@
1
+ # Reconcile notification template administration
2
+
3
+ Follow the version-selected upgrade entry point in the parent Skill. Fetch BASE and TARGET template tarballs and TARGET's compatible `@nocobase/app-skills` first. This reference applies only when TARGET contains `client/pages/settings/notification-routes.ts` and the Notification package exposes `notificationTemplateRegistryToken` plus `client/templates`. A dependency update alone does not replace application source or register this page. Before a target release is published, candidate-package checks are useful but do not establish a published upgrade pass.
4
+
5
+ 1. Record the clean application checkpoint, template package and baseline version. Preserve a representative business page, custom notification renderer/fixture, notification workflows, channel/mailer configuration, stored grants and business records for comparison. Keep secrets out of evidence.
6
+ 2. Compare BASE → TARGET and BASE → application. Bring in compatible package ranges through TARGET's manifest. Reconcile `client/pages/settings/notification-templates.tsx`, `notification-routes.ts`, the route composition, `client/runtime.ts`, `server/providers/notification-management.ts`, its provider registration and English/Chinese settings labels. Preserve custom route names, page permission IDs and existing deep links. Default's runtime route factory consumes the provider's derived `client.notificationTemplates.invitationConfigured` boolean, so a configured built-in invitation mailer enables the real directory automatically after restart. The provider and Users directory use the exported safe `describeInvitationEmailChannel` projection; never publish mailer credentials or copy a full server configuration into `client`. A bare application without notification business keeps the menu absent.
7
+ 3. Reuse the application's existing `notificationManagement` group under System settings. Apply `includeNotificationTemplateRoutes` to the complete host route contributions, or insert `notificationTemplateRoute` once into the existing module. Keep its path relative to any path-bearing ancestors so the stable application URL remains `/settings/notifications/templates`; do not register a second module. If applying the newer settings navigation source in the same upgrade, follow its upgrade reference and attach the group to its existing system category. Preserve the host's module container and log view. Do not invent channel-editing or test-send tabs.
8
+ 4. Reconcile application-owned send call sites into source registration. Preserve custom content and sender selection; extract a pure shared builder only when needed. Keep callback-based or non-enumerable messages explicitly listed as uncovered. Never replace business workflows with Examples or force a direct invitation mailer through persistent notification storage.
9
+ 5. Synchronize Skills through the upgraded CLI. Verify list/detail/preview as an administrator and direct API denial as a restricted user. Check actual language policy, configured/missing/disabled channels, synthetic-only rendering, search/category/channel filters and desktop/narrow layout. Browse and preview must leave notification history, business data and configuration unchanged.
10
+ 6. Verify retained custom content, records, grants, workflow behavior and old deep links after restart. Run affected application checks and record exact BASE/TARGET versions, tarball integrity, dependency resolution, source conflict decisions and results. Advance `nocobase.defaultTemplateVersion` only after this reconciliation and the retained-data checks succeed.
11
+
12
+ There are no new tables or migrations for this directory. Rolling back source and compatible packages removes the view and registrations without deleting notification history or custom business state. Do not roll back or rewrite existing executed migrations.
@@ -0,0 +1,35 @@
1
+ # System settings navigation upgrades
2
+
3
+ Use this reference when BASE → TARGET introduces the System settings structure: one sidebar entry, a home page of cards by category, and tabs inside a module ([System settings navigation](../../nocobase-app-development/references/settings-navigation.md)). The structure is application-owned source. Updating `@nocobase/*` dependencies alone leaves the old navigation in place and working: `navigation.description` is optional and ignored by an older shell, and no route, URL or permission changes. Do not report the navigation as upgraded until the source below is merged and verified.
4
+
5
+ ## Merge the source
6
+
7
+ Three-way merge each file from the BASE template, the application and the TARGET template; never copy TARGET over the application.
8
+
9
+ | Source | What TARGET adds |
10
+ | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | `client/lib/navigation-transform.ts` | `organizeNavigation`, `collapseSettingsNavigation`, `settingsCatalog`, `settingsHomeRoute` and the settings constants; `transformNavigation` now also takes the route tree |
12
+ | `client/routing/route-navigation.ts`, `route-context.tsx`, `route-tree.tsx`, `app-router.tsx` | `buildSettingsCatalog`; relative path nesting shared by the router and route matching; `filterRouteTree`, moved out of `app-router.tsx`, now keeping groups declared empty such as categories waiting for modules; and the shared `access` (`useRouteTree`, `useRouteAccess`) |
13
+ | `client/layouts/app-layout.tsx`, `client/components/breadcrumbs.tsx` | passing `access` to `RouteTreeProvider`; the System settings breadcrumb linking to the home |
14
+ | `client/pages/settings/shell-routes.ts` (Default) or the settings group in `client/routes.ts` (Examples) | the settings group with `settingsHome` and the four categories |
15
+ | `client/pages/settings/settings-home.tsx`, `settings-module-page.tsx`, `permission-management-page.tsx`, `routes.ts` | the home page, the module tab frame, Permission management on that frame, and `parent: 'settingsAccount'` on Users and Permission management |
16
+ | `client/locales/system/settings-*.ts` | `settings.home`, `settings.categories` and module descriptions |
17
+
18
+ Keep the application's own changes to these files and say in a comment why each remains.
19
+
20
+ Also merge `client/routing/route-leave-boundary.tsx`, its `AppLayout` wrapper and the `useSettingsLeave` re-export in `client/pages/settings/hooks.tsx`, as well as `client/routing/client-route.tsx`, `client/components/body-portal.tsx` and the `BodyPortal` use in `client/components/flow-diagram.tsx`. The route guard retains an already loaded page in React Activity while permissions are pending, then unmounts it on denial. Body portals detach their DOM in a layout Effect cleanup so hidden pages cannot leave a visible diagram or overlay behind. The leave boundary must sit outside every route Activity, including nested routes: Activity disconnects page Effects, so registering navigation and beforeunload guards inside the hidden page loses protection during a permission request. Keep confirmation UI in the boundary and clear retained guards on final denial, unmount or session change. Restoring visible Activity content restarts its Effects; existing list hooks re-fetch once per mounted request, in addition to the permission refresh. Keep the existing session boundary that clears page state when the signed-in identity changes. Review application-owned body portals for the same cleanup; field-error portals inside their form need no separate body container.
21
+
22
+ ## Place the application's administration
23
+
24
+ 1. Keep the application's settings group name. Default uses `settings`; Examples uses `systemManagement`; an application that renamed it sets `SETTINGS_GROUP` to its actual name rather than renaming the route, because its children's ids and grants do not depend on it but its customizations may.
25
+ 2. Add `settingsHome` under that group. In a group with a path it is `path: '/'`; in a pathless group pick a free path such as `/settings` and confirm no route uses it.
26
+ 3. Move each administration page into a category by changing only its `parent` (or its position in the tree): keep its `name`, `path` and `authz`. Add `navigation.description` keys in the application's locale files. Keep the application's custom categories, names and order; rename or add categories in the settings group rather than forcing the template's four.
27
+ 4. Turn sibling pages that are views of one capability into a module group with `breadcrumb`, and wrap each view in `SettingsModulePage`. Leave a page that already has its own tabs as it is.
28
+ 5. Move everyday business entries that had been placed in the settings group, such as a knowledge base people read, back to the business navigation without changing their URLs.
29
+ 6. Remove any application-specific sidebar collapse made redundant by the settings entry (the template's former `collapsePermissionNavigation`), and the template's old `systemSettingsRoutes` re-parenting in Examples-derived applications.
30
+
31
+ If a URL has to change, keep the old path working with a redirect route and list it in the upgrade record.
32
+
33
+ ## Verify
34
+
35
+ Run the application's navigation and settings tests, then check in the browser as an administrator and as a restricted user: one System settings entry selected on every settings page; the home shows the expected cards with descriptions and no empty category; each old deep link and bookmark opens the same page; tabs switch by URL, refresh and Back keep the view; the breadcrumb returns to the home; a restricted user sees only the cards and tabs their grants open and is still refused by direct URLs and APIs; list filters, unsaved-change guards and business data are unchanged. Trigger a permission refresh while editing: content and overlays must be hidden while pending, the same draft must return if access remains allowed, and denial or a different signed-in identity must remove the previous content. While the permission request remains pending, cancel leaving through the breadcrumb and browser Back, check that the URL and draft remain, and check the native beforeunload prompt; confirm leaving and check the destination. Cancel leaving through module tabs and the home breadcrumb and check that the draft remains; confirm leaving and check the final destination.