@nocobase/app-skills 0.1.0-beta.41 → 0.1.0-beta.42

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.41",
3
+ "version": "0.1.0-beta.42",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -41,21 +41,24 @@ Build the feature in the application. Do not run a plugin generator, create a `p
41
41
 
42
42
  NocoBase packages may publish Skills under `.agents/skills/`. Current application templates run `pnpm nocobase skills sync` automatically through `postinstall`; run it manually if install scripts were disabled or that directory is missing or stale. Confirm that the package is a direct `@nocobase/*` dependency or a registered plugin before relying on its Skill. The common capability mappings are:
43
43
 
44
- | The requirement sounds like | Read the Skill for |
45
- | -------------------------------------------------------------- | ------------------------------------------ |
46
- | Email, IM, or in-app messages | `@nocobase/app-plugin-notification` |
47
- | Roles, permissions, per-user or per-record access | `@nocobase/app-plugin-authorization` |
48
- | Sign-in, registration, sessions | `@nocobase/app-plugin-authentication` |
49
- | File upload and metadata through Repository | `@nocobase/app-plugin-file` |
50
- | File storage, disk configuration, or custom drivers | `@nocobase/drive` |
51
- | Translated text and language switching | `@nocobase/app-plugin-i18n` |
52
- | User administration and application-owned role assignment | `@nocobase/app-plugin-users` |
53
- | Live updates, snapshot recovery and replacing business polling | `@nocobase/realtime` (`nocobase-realtime`) |
54
- | Reading or writing data, schema changes, migrations | `@nocobase/db` |
44
+ | The requirement sounds like | Read the Skill for |
45
+ | -------------------------------------------------------------- | ------------------------------------------------------- |
46
+ | Email, IM, or in-app messages | `@nocobase/app-plugin-notification` |
47
+ | Approval processes, joint decisions and approval tasks | `@nocobase/app-plugin-approval` (commercial Pro plugin) |
48
+ | Roles, permissions, per-user or per-record access | `@nocobase/app-plugin-authorization` |
49
+ | Sign-in, registration, sessions | `@nocobase/app-plugin-authentication` |
50
+ | File upload and metadata through Repository | `@nocobase/app-plugin-file` |
51
+ | File storage, disk configuration, or custom drivers | `@nocobase/drive` |
52
+ | Translated text and language switching | `@nocobase/app-plugin-i18n` |
53
+ | User administration and application-owned role assignment | `@nocobase/app-plugin-users` |
54
+ | Live updates, snapshot recovery and replacing business polling | `@nocobase/realtime` (`nocobase-realtime`) |
55
+ | Reading or writing data, schema changes, migrations | `@nocobase/db` |
55
56
 
56
57
  Read the relevant Skill before writing the feature, but treat this table as a map rather than an installed-package list. Implementing a permission system, a notification sender, or a scheduler by hand when a registered plugin provides one is the most expensive mistake available here.
57
58
 
58
- When the stages of a business record are fixed by developers rather than drawn by administrators — an expense report, a ticket, a contract, an order — build it with `@nocobase/lifecycle` as [record lifecycles](references/lifecycle.md) describes: the state stays in the record's own field and changes only through declared transitions.
59
+ For approval requirements, check `@nocobase/app-plugin-approval` first. If missing, tell the user it is a commercial Pro plugin requiring appropriate authorization and a compatible version, and recommend installation before implementing approval. Follow [approval prerequisites](references/lifecycle.md#approval-requests-check-the-pro-plugin-first) and the plugin's installed Skill; do not silently build a substitute approval engine from lifecycle examples. Simple single-person confirmation or rejection can remain lifecycle actions.
60
+
61
+ When the stages of a business record are fixed by developers rather than drawn by administrators — an expense report, a ticket, a contract, an order — build it with `@nocobase/lifecycle` as [record lifecycles](references/lifecycle.md) describes: the state stays in the record's own field and changes only through declared transitions. Declare only required business paths with precise sources and destinations; the diagram expands every `from × to` pair rather than analyzing routing logic. Follow [readable process graphs](references/lifecycle-ui.md#keep-process-graphs-readable) before rendering dense definitions.
59
62
 
60
63
  For notification configuration or sending, follow the notification plugin Skill: `notification.channels` maps each name to one flat Provider configuration, and `send({ idempotencyKey, messages })` supplies a complete message per Channel. Use native addresses; email and in-app arrays create independent deliveries, while Webhooks forbid `to`.
61
64
 
@@ -95,31 +98,32 @@ The handbook's "Look up by task" table routes each frontend task to the sections
95
98
 
96
99
  Read the page for the task in front of you. Do not read all of them.
97
100
 
98
- | Task | Read |
99
- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
100
- | Anything under `client/`: pages, routes, components, styling, forms, API calls, copy, frontend tests | [frontend workflow](references/frontend/ui-workflow.md), which routes to the [frontend handbook](references/frontend/frontend-dev.md), the theme reference or the worked example |
101
- | Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md) |
102
- | Name an endpoint, shape its response or errors, validate its input, paginate a list, document it in the API document | [HTTP API design](references/http-api.md) |
103
- | A list, chart or polled endpoint, or keeping one live: read it with a fixed number of queries, refresh only what changed | [server routes](references/server-routes.md#lists-and-statistics-a-fixed-number-of-queries) and [client API requests](references/frontend/references/api.md#keeping-lists-and-charts-live) |
104
- | Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md) |
105
- | Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md) |
106
- | Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md) |
107
- | Translate server-produced text, add a language, set the default language | [internationalization](references/i18n.md) |
108
- | Departments, positions or another organisation dimension that permission sets are assigned to | [organisation dimension](references/organization.md) |
109
- | Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
110
- | Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
111
- | A record that moves through stages defined in code: approvals, tickets, orders, timeouts, effects after a state change | [record lifecycles](references/lifecycle.md) |
112
- | Administrator-adjustable approval departments, reviewers, thresholds or business values in a code-defined lifecycle | [configurable lifecycle parameters](references/lifecycle-parameters.md); keep workflow structure in source. For management forms and optional diagram-bound editing, see [Lifecycle UI](references/lifecycle-ui.md). |
113
- | Lifecycle definition catalogs, execution lists, process details, history or parameter settings | [Lifecycle UI](references/lifecycle-ui.md) |
114
- | Flowcharts, process diagrams or lifecycle state diagrams | Use UI Library `@nocobase/flow-diagram` for generic graphs and `@nocobase/lifecycle-diagram` for lifecycle descriptions; see [diagram guidance](references/lifecycle.md#draw-an-interactive-lifecycle-diagram) and the [UI catalog](references/frontend/references/ui-library.md#diagrams). Preserve their application theme tokens. |
115
- | Use `@nocobase/app-testing` for database, server, client or CLI tests; verify before finishing | [testing and verification](references/testing.md) |
116
- | Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
117
- | Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
118
- | Where a file goes, how the client and server are composed, configuration, changing the framework structure | [application structure](references/app-structure.md) |
119
- | Register, update, customize or remove a plugin; check what an installed plugin already provides | [plugins](references/plugins.md) |
120
- | Add an npm package, decide `dependencies` versus `devDependencies`, diagnose a missing module or native binary | [adding a dependency](references/dependencies.md) |
121
- | Report the application's URL, dev server restarts and file watching, develop against another backend | [the development server](references/dev-server.md) |
122
- | Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
101
+ | Task | Read |
102
+ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
103
+ | Anything under `client/`: pages, routes, components, styling, forms, API calls, copy, frontend tests | [frontend workflow](references/frontend/ui-workflow.md), which routes to the [frontend handbook](references/frontend/frontend-dev.md), the theme reference or the worked example |
104
+ | Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md) |
105
+ | Name an endpoint, shape its response or errors, validate its input, paginate a list, document it in the API document | [HTTP API design](references/http-api.md) |
106
+ | A list, chart or polled endpoint, or keeping one live: read it with a fixed number of queries, refresh only what changed | [server routes](references/server-routes.md#lists-and-statistics-a-fixed-number-of-queries) and [client API requests](references/frontend/references/api.md#keeping-lists-and-charts-live) |
107
+ | Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md) |
108
+ | Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md) |
109
+ | Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md) |
110
+ | Translate server-produced text, add a language, set the default language | [internationalization](references/i18n.md) |
111
+ | Departments, positions or another organisation dimension that permission sets are assigned to | [organisation dimension](references/organization.md) |
112
+ | Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
113
+ | Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
114
+ | Approval processes, joint decisions, added reviewers, reassignment or approval tasks | [approval plugin prerequisites](references/lifecycle.md#approval-requests-check-the-pro-plugin-first), then the installed `@nocobase/app-plugin-approval` Skill |
115
+ | A record that moves through stages defined in code: simple confirmations, tickets, orders, timeouts, effects after a state change | [record lifecycles](references/lifecycle.md) |
116
+ | Administrator-adjustable approval departments, reviewers, thresholds or business values in a code-defined lifecycle | [configurable lifecycle parameters](references/lifecycle-parameters.md); keep workflow structure in source. For management forms and optional diagram-bound editing, see [Lifecycle UI](references/lifecycle-ui.md). |
117
+ | Lifecycle definition catalogs, execution lists, process details, history or parameter settings | [Lifecycle UI](references/lifecycle-ui.md) |
118
+ | Flowcharts, process diagrams or lifecycle state diagrams | Use UI Library `@nocobase/flow-diagram` for generic graphs and `@nocobase/lifecycle-diagram` for lifecycle descriptions; see [diagram guidance](references/lifecycle.md#draw-an-interactive-lifecycle-diagram) and the [UI catalog](references/frontend/references/ui-library.md#diagrams). Preserve their application theme tokens. |
119
+ | Use `@nocobase/app-testing` for database, server, client or CLI tests; verify before finishing | [testing and verification](references/testing.md) |
120
+ | Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
121
+ | Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
122
+ | Where a file goes, how the client and server are composed, configuration, changing the framework structure | [application structure](references/app-structure.md) |
123
+ | Register, update, customize or remove a plugin; check what an installed plugin already provides | [plugins](references/plugins.md) |
124
+ | Add an npm package, decide `dependencies` versus `devDependencies`, diagnose a missing module or native binary | [adding a dependency](references/dependencies.md) |
125
+ | Report the application's URL, dev server restarts and file watching, develop against another backend | [the development server](references/dev-server.md) |
126
+ | Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
123
127
 
124
128
  A feature with a page and an API usually needs migrations, server routes, and a frontend change that follows the frontend workflow.
125
129
 
@@ -115,6 +115,8 @@ expect(run.json()).toMatchObject({
115
115
 
116
116
  `bindAppCommand()` pins the command to a fixture application, the way the runner would point it at the one it located; `id` is the id the runner would give it, colon-separated, so the document names the command. Pass `loadRuntime` and `createApp` as well to replace the application with a stub. `runAppCommand()` returns what `run()` returned as `result`, what escaped it as `error`, the `exitCode`, the captured `stdout` and `stderr`, and `json()` for the `--json` document. Assert on those rather than on printed text.
117
117
 
118
+ A command that opens the application needs isolated databases and storage. Follow the [complete database command example](testing/cli/command.md) for `createTestAppConfig()`, `bindTestAppCommand()`, schema preparation and cleanup; use the [file-command example](testing/cli/files.md) for temporary output directories. A custom `loadRuntime` must pass `config.path` as `configPath` and direct runtime storage into the fixture directory itself. The conventional loader runs through Node; a TypeScript application using `.js` import specifiers needs a compatible loader, compiled modules, or explicit imports of its runtime and app factory supplied through `loadRuntime` and `createApp`.
119
+
118
120
  ## Example
119
121
 
120
122
  ```ts
@@ -8,7 +8,7 @@ tests/logic/ Logic tests: route declarations, pure functions, providers (
8
8
  tests/playwright/ End-to-end tests against a running application (Playwright); create the directory with the first test
9
9
  ```
10
10
 
11
- Tests never go beside the source. Vitest discovers `tests/**/*.test.{ts,tsx}` and skips `tests/playwright/` (`vitest.config.ts`); Playwright discovers `tests/playwright/**/*.test.ts` (`playwright.config.ts`). Use `tests/playwright/` only for what needs a real server and database, such as a flow across the browser and the API or a server-side permission check seen from the page. Everything else is a component or logic test. Applications created from the Default and Examples templates have Playwright set up; an application without it, before its first end-to-end test, adds `@playwright/test` to `devDependencies`, a `playwright.config.ts` with `testDir: './tests/playwright'` and `testMatch: '**/*.test.ts'`, a `test:e2e` script running `playwright test --pass-with-no-tests`, `exclude: ['tests/playwright/**']` to the `test` section of `vitest.config.ts` unless it is already there, and `playwright.config.ts` and `tests/playwright/**/*.ts` to the `include` of `tsconfig.node.json`.
11
+ Tests never go beside the source. Vitest discovers `tests/**/*.test.{ts,tsx}` and skips `tests/playwright/` (`vitest.config.ts`); Playwright discovers `tests/playwright/**/*.test.ts` (`playwright.config.ts`). Use `tests/playwright/` for browser behavior and complete browser-to-API flows. A real server, database or sign-in alone belongs in a Node test with `createAppTest()` from `@nocobase/app-testing/server`; it does not require Playwright. Applications created from the Default and Examples templates have Playwright set up; an application without it, before its first end-to-end test, adds `@playwright/test` to `devDependencies`, a `playwright.config.ts` with `testDir: './tests/playwright'` and `testMatch: '**/*.test.ts'`, a `test:e2e` script running `playwright test --pass-with-no-tests`, `exclude: ['tests/playwright/**']` to the `test` section of `vitest.config.ts` unless it is already there, and `playwright.config.ts` and `tests/playwright/**/*.ts` to the `include` of `tsconfig.node.json`.
12
12
 
13
13
  ## What to test
14
14
 
@@ -27,7 +27,9 @@ Also run `tests/logic/page-permission-titles.test.ts` when adding or changing ro
27
27
 
28
28
  For a page or component that uses application services, start from the [complete `@nocobase/app-testing/client` example](../../testing/client/page.md). `renderWithApp()` supplies the real API client, router, translations and toaster. Supply HTTP responses through `answerApi()`, load the application's locale map, and assert visible state and `view.toasts()`. Register the client plugins or service doubles that the page actually consumes; avoid mocking the whole `@nocobase/app-client` module.
29
29
 
30
- Existing `tests/components/page-harness.test.tsx` files can still illustrate which states to cover: a request payload, a `403` without retry, a `401` offering sign-in, an action shown or hidden with permission, and a child route opened by URL. When adapting those cases, import the real page and use the application fixture for its service context. Put new files in the application's current test layout; the worked example uses `tests/client/` with an explicit React config.
30
+ `tests/components/page-harness.test.tsx` in the official templates uses `renderWithApp()` with real API, authorization, translation and toaster hooks. It covers a pending request, the request payload, a `403` without retry, a `401` with session refresh, allowed and denied actions, and a child route opened by URL and closed with a success toast. It replaces the authentication service through `services` while keeping its provider and hooks real. When adapting those cases, import the real page and supply its required plugins or services. Put new files in the application's current test layout; the worked example uses `tests/client/` with an explicit React config.
31
+
32
+ The template's local Vitest inline rules transform client plugins in any scope, including `@acme/app-plugin-*`, alongside `app-client` and the client test helper. Preserve that scope coverage when changing the configuration so installed plugins share application contexts and service tokens. Keep server and database modules external. The shared React preset handles native router resolution; preserve its package export conditions and router externalization when adjusting local rules.
31
33
 
32
34
  For anything else, start from the test that already sets it up:
33
35
 
@@ -136,14 +136,36 @@ The /device page where a signed-in person approves or denies the sign-in of a CL
136
136
 
137
137
  ### permission-editor
138
138
 
139
- A compact resource permission workspace with horizontal action checkboxes, adjacent data scopes and atomic visible selection.
139
+ A compact permission workspace with category navigation, individual action checkboxes, scoped data controls and accessible scope help.
140
140
 
141
141
  - Kind: component
142
142
  - Install: `yes n | pnpm exec shadcn add @nocobase/permission-editor`
143
143
  - Installs to: `client/components/permission-editor.tsx`, `client/components/permission-filter.tsx`
144
144
  - Plugin dependencies: none
145
145
  - Example: `@nocobase/permission-editor-demo` (`pnpm exec shadcn view @nocobase/permission-editor-demo`)
146
- - After installing: Map your permissions to sections of groups of rows; each row has an id, a label, an optional hint, whether it is enabled, and optionally the levels it can reach and the current one. onEnabledChange and onLevelChange report changes by row id. Every word comes through props, English by default. Resource groups render as compact rows with wrapping action checkboxes. Optional row.scopes bind independent scope selectors to their owning action. Pass onEnabledBatchChange to enable atomic group selection of visible toggleable permissions; omit it to keep single-action controls. Filtering never mutates the draft. Pass labels.selectVisible for the localized group checkbox name. Use group.accessOnly for a page with a single access action to show one title checkbox without redundant action text. Provide scope.configuration for parameterized scopes; PermissionFilter edits validated condition drafts and keeps role saving in the host form. Never save customFilter as a bare key: bind its native params.filter object.
146
+ - After installing: Map your permissions to sections of groups of rows; each row has an id, a label, an optional hint, whether it is enabled, and optionally the levels it can reach and the current one. onEnabledChange and onLevelChange report changes by row id. Every word comes through props, English by default. Resource groups render as compact rows with wrapping action checkboxes. Optional row.scopes bind independent scope selectors to their owning action. Actions are configured individually; category names and groups omit authorization counts and bulk selection. Filtering never mutates the draft. Use scope.hint for contextual scope help shown on hover, keyboard focus or tap, and labels.scopeHintFor for the accessible trigger name. Use group.accessOnly for a page with a single access action to show one title checkbox without redundant action text. Provide scope.configuration for parameterized scopes; PermissionFilter edits validated condition drafts and keeps role saving in the host form. Never save customFilter as a bare key: bind its native params.filter object.
147
+
148
+ ### role-list
149
+
150
+ A compact role content list with aligned names, identifiers and protected/custom labels. Use it on role administration pages backed by the Authorization plugin; the host supplies authorized data and edit destinations. Preinstalled in both application templates.
151
+
152
+ - Kind: component
153
+ - Install: `yes n | pnpm exec shadcn add @nocobase/role-list`
154
+ - Installs to: `client/components/role-list.tsx`
155
+ - Plugin dependencies: none
156
+ - Example: `@nocobase/role-list-demo` (`pnpm exec shadcn view @nocobase/role-list-demo`)
157
+ - After installing: Render inside a React Router with roles containing key, localized title, edit destination (to) and protected state. Pass localized protected/custom labels and an optional ariaLabel. The host owns loading, empty/error states, filtering, sorting and authorization. Rows use body-sized text and compact spacing; identifiers move under the name on narrow containers. Publishing the Registry does not replace installed source; existing apps merge role-list.tsx and the roles page integration through a template source upgrade.
158
+
159
+ ### default-access-editor
160
+
161
+ Controlled default data scope rule fields with business-object selection, independent operation scopes and native custom-filter slots. The host supplies current rules and performs authorized writes. Preinstalled in both application templates.
162
+
163
+ - Kind: component
164
+ - Install: `yes n | pnpm exec shadcn add @nocobase/default-access-editor`
165
+ - Installs to: `client/components/default-access-editor.tsx`
166
+ - Plugin dependencies: none
167
+ - Example: `@nocobase/default-access-editor-demo` (`pnpm exec shadcn view @nocobase/default-access-editor-demo`)
168
+ - After installing: Pass localized labels, a stable rule key, resource choices and scope controls. Explain that default data scopes combine with role-granted scopes for users who already hold the operation permission, and that restriction rules still constrain final access. The host loads authorization/defaultAccess and authorization/defaultAccess/options, enforces settings:authorization.default-access read/create/update/delete, and owns draft preservation, custom filters, validation, confirmation and writes. Existing apps reconcile the editor, default-access pages/model/routes, locales and contextual role-form link from the updated template. No existing rule is seeded or rewritten on upgrade. Both templates expose one Permission management sidebar entry with Roles and permissions and Default data scopes tabs, without changing their route ids, URLs, settings guards or stored rules. This navigation organization does not add sharing or restriction editors.
147
169
 
148
170
  ## Data display
149
171
 
@@ -14,6 +14,8 @@ These are this application's UI design guidelines: foundations, page structure,
14
14
 
15
15
  **F1 [Must] Color uses only semantic tokens**: `bg-background` for the page, `bg-card` for cards, `bg-muted` for muted areas, `text-foreground` and `text-muted-foreground` for text, `border-border` for borders, the default button for primary actions and `variant='destructive'` or `text-destructive` for destructive ones. The full mapping, with what each replaces, is in [section 7 of `references/styling.md`](references/styling.md#7-semantic-tokens). Do not use literal colors such as `bg-white`, `text-gray-500`, `#1677ff` or `rgb(…)`.
16
16
 
17
+ **F1.1 [Should] Record-name links stay visually quiet**: In tables and content lists, use the normal foreground color for a record's name or identifier, an underline on hover with `underline-offset-4`, and the shared keyboard focus treatment from `client/styles.css`. Apply this consistently to user, role and workflow names. Use the primary color for deliberate primary actions and selected navigation, rather than coloring every record link.
18
+
17
19
  **F2 [Must] Font sizes come from the scale**: PageHeader provides the page title; section titles use `text-base font-medium`; body text, tables and forms use the components' default size (`text-sm`); helper text uses `text-sm text-muted-foreground` or `text-xs`. Do not use arbitrary values such as `text-[13px]`.
18
20
 
19
21
  **F3 [Must] Spacing comes from the scale**: PageContainer spaces the sections of a page, and blocks you stack yourself use `flex flex-col` with `gap-4` or `gap-6` rather than `space-y-*`; cards keep the `Card` component's own padding, and whatever sits in a card lines up with its title: a `DataTable` in a card runs to the card's edges and pads its first and last cells to the card's spacing by itself ("Table in a card" in ["Common layouts" of `references/styling.md`](references/styling.md#common-layouts)); a panel you build yourself uses `p-4` or `p-6`; `gap-2` between related controls; FieldGroup's default spacing between form fields. Do not use arbitrary values such as `mt-[7px]`.
@@ -1,5 +1,7 @@
1
1
  # Configurable lifecycle parameters
2
2
 
3
+ For approval processes, first follow [approval plugin prerequisites](lifecycle.md#approval-requests-check-the-pro-plugin-first). Reviewer parameters here describe lifecycle configuration, not a substitute for the commercial approval plugin's task and decision model; use that plugin's installed Skill for its configuration and integration contracts.
4
+
3
5
  Apply this by default whenever building or iterating on a process with administrator-owned business policy, including approval departments, reviewers, thresholds or reopening windows. Inspect the business rules and proactively declare suitable configuration even when the user never asks for configurability; follow [system settings delivery](system-settings.md#discover-configurable-business-rules-by-default). Developers keep the workflow structure in source. Read [record lifecycles](lifecycle.md) first. This capability belongs to `@nocobase/lifecycle`; verify that the installed package exports `StoredLifecycleParameters` and `normalizeReviewerSelections` before using it. An older installation needs a compatible release upgrade rather than invented APIs.
4
6
 
5
7
  ## Code declaration and storage
@@ -4,6 +4,8 @@ Use this reference for management pages built around `@nocobase/lifecycle`. Read
4
4
 
5
5
  ## Default management structure
6
6
 
7
+ For approval-specific requests, tasks and decisions, first follow [approval plugin prerequisites](lifecycle.md#approval-requests-check-the-pro-plugin-first) and the installed `@nocobase/app-plugin-approval` Skill. The generic workflow management block does not itself implement an approval subsystem.
8
+
7
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.
8
10
 
9
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.
@@ -46,6 +48,23 @@ Prefer a visible parameter form beside the diagram. Group fields by business sta
46
48
 
47
49
  Provide contextual controls for declared, authorized bindings by default, sharing the same editor and save contract. Do not make tiny gear icons the only way to discover settings. Inspection and editing clicks never execute transitions.
48
50
 
51
+ ## Keep process graphs readable
52
+
53
+ Aim for a readable business process with its necessary branches, not a diagram of every implementation operation. Start with the main forward path, then include required approval, rejection, withdrawal, resubmission, timeout and recovery paths. Do not invent extra transitions for symmetry or connect each state to every other state. A technically automatic transition can still be an essential business step; do not hide it merely because it is automatic.
54
+
55
+ Check edge expansion before tuning layout. `LifecycleDiagram` draws every `from × to` pair in each supplied transition, including self-loops and separate actions with the same endpoints. A transition with three sources and three destinations produces nine edges. The static description does not encode the source-specific results of `route()` or guards, and `availableTransitions` only highlights edges. ELK can route those edges but cannot decide which are unnecessary.
56
+
57
+ For example, an approval declared as `from: ['manager', 'finance']` and `to: ['finance', 'approved']` draws four edges, including `finance → finance`, even if `route()` always sends finance approval to `approved`. In a new definition, declare manager approval with destinations `finance` or `approved` and finance approval with destination `approved`: three meaningful edges. Keep both manager destinations when either can occur under supported business parameters; do not prune a definition to today's parameter values or one record's allowed actions.
58
+
59
+ For an existing definition, simplify presentation without changing execution semantics:
60
+
61
+ - Keep the authoritative description intact. Derive a separate presentation description for `LifecycleDiagram`, filtering explicitly identified system-only repair/edit transitions. Do not guess from transition names or remove every self-loop: a same-state review or retry can be a real business operation. Preserve configuration access for omitted technical operations in the parameter form when authorized.
62
+ - If an existing multi-source transition creates impossible source/destination pairs, inspect its actual routing logic. Narrow only pairs proven impossible across supported inputs and parameters. When this needs pair-level filtering, inspect the installed graph builder and implement it in the application adapter while retaining the standard React Flow components, exact transition/source/destination identities, inspection and configuration behavior. There is no built-in edge-filter prop; do not invent one or evaluate server routing functions in the browser. If reachability is uncertain, keep the edge.
63
+ - Keep real business alternatives visible; do not apply a generic transitive reduction, merge distinct actions just because their endpoints match, or remove return paths to force a DAG. These operations can erase different permissions, effects or audit meanings. Use concise labels and node policy summaries instead of placing long explanations on every edge.
64
+ - On execution views, preserve the exact edges in the selected history prefix, including any technical transition omitted from the ordinary definition view. Keep the full history available and the current or historically selected state visible; never fabricate a shortcut between the remaining nodes. Inspection resolves to the original description, and business action availability still comes from the runtime.
65
+
66
+ Verify the resulting graph against the actual business paths: the main progression should be easy to trace, required alternatives should remain discoverable, and no unexplained cross-product edge should remain. Check a rejection/resubmission path and a routed multi-source transition when present, plus execution history and parameter controls. If a process is genuinely dense, preserve its semantics and improve spacing, sizing and navigation instead of silently dropping business paths.
67
+
49
68
  ## Diagram sizing and visual language
50
69
 
51
70
  React Flow needs a definite sized ancestor; min-height alone inside unconstrained flex parents may collapse or oversize the canvas. Choose autoHeight for content-sized diagrams or a bounded canvas with pan/zoom and refitting after layout or container resizing. The examples use a 720px definition canvas and matching execution minimum; adapt this to the graph and viewport rather than prescribing it universally.
@@ -4,19 +4,28 @@ Use `@nocobase/lifecycle` when a business record moves through stages that devel
4
4
 
5
5
  Administrators can adjust code-declared business parameters without editing workflow structure. Proactively declare suitable approval departments, reviewer choices and thresholds as business parameters, even without an explicit configurability request. For declarations, snapshot/live reads and shared configuration editors, read [configurable lifecycle parameters](lifecycle-parameters.md).
6
6
 
7
+ ## Approval requests: check the Pro plugin first
8
+
9
+ When requirements include an approval process, first check whether `@nocobase/app-plugin-approval` is installed and registered, and read its synchronized Skill when available. Tell the user that approval is provided by this commercial Pro plugin and requires the appropriate authorization and a compatible version. Simple single-person confirmation or rejection can remain lifecycle transitions; multi-stage approvals, countersigning/all-or-any decisions, added reviewers, reassignment and approval task management should use the approval plugin rather than an application-built substitute assembled from lifecycle examples.
10
+
11
+ If the plugin is missing, explain the commercial prerequisite and recommend installing it before implementing the approval subsystem. Follow [plugin installation](plugins.md#installing-and-updating) with `pnpm nocobase plugin register @nocobase/app-plugin-approval` once the user's authorization and package access are available. Honor authorization already given; do not ask again. Synchronize Skills with `pnpm nocobase skills sync` if needed and read the installed plugin's Skill before using its APIs. If licensing, registry access or a compatible version is unavailable, report that concrete prerequisite and continue independent business work; do not silently replace the plugin with a homegrown approval engine or invent plugin APIs. An explicit request for a simple confirmation or a custom implementation takes precedence; state its supported scope without claiming full approval-plugin behavior.
12
+
13
+ The lifecycle examples below illustrate state transitions, guards and effects, not a replacement for the approval plugin. Keep business record progression and post-approval execution distinct from approval decisions, and follow the plugin's integration contract for connecting them. Do not assume that an approved request means payment or another external effect succeeded.
14
+
7
15
  ## Deliver workflow management by default
8
16
 
9
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.
10
18
 
11
19
  ## Choose it or something else
12
20
 
13
- | The requirement | Use |
14
- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
15
- | A record has clear stages, developers own the rules, and someone will ask who changed it and when | A lifecycle, this page |
16
- | Administrators draw or change the process in the UI | The DAG flow plugin and its Skill, when it is installed |
17
- | A process that pauses for an external decision and is resumed by an id | The workflow plugin's `wait` node, as the main Skill describes |
18
- | A notification when a field changes, with no stages | An ordinary service call or event listener |
19
- | Work that runs once in the background, or on a schedule, with no record state | [services and jobs](services-and-jobs.md) |
21
+ | The requirement | Use |
22
+ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
23
+ | A record has clear stages, developers own the rules, and someone will ask who changed it and when | A lifecycle, this page |
24
+ | Multi-stage approval, joint decisions, added reviewers, reassignment or approval tasks | The Pro `@nocobase/app-plugin-approval` plugin; follow [approval prerequisites](#approval-requests-check-the-pro-plugin-first) and its installed Skill |
25
+ | Administrators draw or change the process in the UI | The DAG flow plugin and its Skill, when it is installed |
26
+ | A process that pauses for an external decision and is resumed by an id | The workflow plugin's `wait` node, as the main Skill describes |
27
+ | A notification when a field changes, with no stages | An ordinary service call or event listener |
28
+ | Work that runs once in the background, or on a schedule, with no record state | [services and jobs](services-and-jobs.md) |
20
29
 
21
30
  A parent and its children can each have a lifecycle and point at each other by foreign key, such as a document and the tasks it distributes; a child's last transition can move the parent on in the same transaction.
22
31
 
@@ -53,6 +62,8 @@ Add `@nocobase/lifecycle` to `dependencies` (`pnpm add @nocobase/lifecycle`): th
53
62
 
54
63
  ## 1. Types, effects and the definition
55
64
 
65
+ Model the required business steps and explicit exceptions, not every possible pair of states. Keep each transition's `from` and `to` as narrow as its actual behavior permits; do not add generic jump, reset, reopen or reverse paths unless the business requires them. For new definitions, prefer separate source-specific transitions when different sources have different destinations, sharing guards and effects where appropriate. A broad `from`/`to` declaration with a `route()` that chooses only some pairs makes the static diagram overstate connectivity: the renderer expands the Cartesian product and cannot inspect the routing function. Do not rename existing transitions just for appearance; their names identify history, bindings and callers. See [readable process graphs](lifecycle-ui.md#keep-process-graphs-readable) for display-only simplification that preserves runtime behavior.
66
+
56
67
  ```ts
57
68
  // server/lifecycles/leave.ts
58
69
  import {
@@ -449,6 +460,8 @@ When a page needs a lifecycle diagram, first reuse the template's preinstalled `
449
460
 
450
461
  Import `LifecycleDiagram` from `#components/lifecycle-diagram`. Pass the hook's `description.description`, an `ariaLabel`, `currentState: view.record.status` (use the lifecycle's own state field), and `availableTransitions: view.available.filter((item) => item.allowed).map((item) => item.name)`. Translate labels by stable state/transition names with `stateLabel` and `transitionLabel`; add the shared `flowDiagram` keys to your locale resources. Use `onStateClick` and `onTransitionClick` to open details, including effects, triggers and continuations from the description. Definitions remain in source and clicking the diagram never fires a transition; action buttons still follow `view.available`. Pass `history={view.history.transitions}` for visited paths; the component matches the exact transition, source and destination, including retries. `visitedStates` supplements node highlights only; never infer a traversed edge from the current state or visited endpoints. Pass a translated `endLabel` to display a separate decorative end marker after each explicit final state, without treating every state lacking outgoing transitions as final. Keep `toMermaid()` for documentation and export.
451
462
 
463
+ Before passing a dense description directly, apply [readable process graph guidance](lifecycle-ui.md#keep-process-graphs-readable). `availableTransitions` highlights edges; it does not filter them, and neither guards nor `route()` prune the graph. Use a separate presentation description when omitting documented technical transitions; keep the authoritative description for execution and inspection.
464
+
452
465
  `LifecycleDiagram` defaults to `direction="DOWN" autoHeight`. For direct `FlowDiagram` composition on a process page, set those props explicitly. Choose automatic height for a content-sized diagram, or a deliberately bounded canvas for the side-by-side management layouts in [Lifecycle UI](lifecycle-ui.md#diagram-sizing-and-visual-language). Fit the full routed graph, including outer edges and labels. A wide graph fitted into a short fixed-height panel makes its labels unreadable; verify the actual lifecycle in the target page.
453
466
 
454
467
  The label callbacks receive description objects, not name strings. Read `state.name` in `stateLabel` and `transition.name` in `transitionLabel` when building translation keys:
@@ -4,7 +4,7 @@ Part of [the organisation dimension](../organization.md). Follow [testing and ve
4
4
 
5
5
  ## Test against the real application
6
6
 
7
- Most of the matrix needs the real authorization routes and middleware, so start the application itself with the authentication and authorization plugins, and the sharing-rules plugin for the cross-department case, on a temporary SQLite database; startup then runs every plugin's migrations and seeds. Sign users up through `POST /api/auth/sign-up/email` and reuse the cookie, and create permission sets and assignments through `authz.permissionSets`. When a test composes the `Application` by hand instead of through `resolveAppRuntime`, resolve the plugins with `resolveAppServerPlugins(rootDir, defineServerPlugins([...]))`, since that is what finds each plugin's migrations and seeds, and name the driver in the database configuration, `drivers: { sqlite }`.
7
+ Most of the matrix needs real authorization routes and middleware. Use `createAppTest({ createServer: createStandaloneServer })` from `@nocobase/app-testing/server` with the application's own `server/standalone.ts`. Confirm its runtime registers authentication, authorization and, for the cross-department case, sharing-rules. The fixture installs their migrations and seeds on isolated databases on the selected test dialect; do not choose a dialect or configure a driver here. Sign in seeded or test-created users with `signIn()` from `@nocobase/app-plugin-authentication/testing`, and create permission sets and assignments through `authz.permissionSets`. Use `scope: 'test'` for cases that need fresh data, or explicitly clean up each test's records and assignments when sharing the file-scoped application. Follow the [complete application test example](../testing/server/routes.md) for fixture ownership, account setup and denied-access checks.
8
8
 
9
9
  ## Test matrix
10
10
 
@@ -6,14 +6,15 @@ Read this before registering, updating, customizing or removing a plugin, and be
6
6
 
7
7
  **You are not starting from scratch.** This application ships with NocoBase packages that already solve whole categories of requirement, and packages may publish a Skill explaining how to use them. `pnpm nocobase skills sync` copies Skills from direct `@nocobase/*` dependencies and registered plugins into `.agents/skills/`. Before implementing a feature, check whether an installed and registered plugin already covers it:
8
8
 
9
- | The requirement sounds like | Read the Skill for |
10
- | -------------------------------------------------------------------------------------------- | ------------------------------------- |
11
- | Email, IM, or in-app messages; notifying someone that something happened | `@nocobase/app-plugin-notification` |
12
- | Roles, permissions, "user A may only see their own records", field-level or row-level access | `@nocobase/app-plugin-authorization` |
13
- | Sign-in, registration, sessions, password reset | `@nocobase/app-plugin-authentication` |
14
- | User listing, account state, password reset, and application-owned role assignment | `@nocobase/app-plugin-users` |
15
- | File upload and metadata through Repository | `@nocobase/app-plugin-file` |
16
- | Translated text and language switching | `@nocobase/app-plugin-i18n` |
9
+ | The requirement sounds like | Read the Skill for |
10
+ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | Email, IM, or in-app messages; notifying someone that something happened | `@nocobase/app-plugin-notification` |
12
+ | Approval processes, joint decisions and approval tasks | `@nocobase/app-plugin-approval` (commercial Pro plugin; check [prerequisites](lifecycle.md#approval-requests-check-the-pro-plugin-first)) |
13
+ | Roles, permissions, "user A may only see their own records", field-level or row-level access | `@nocobase/app-plugin-authorization` |
14
+ | Sign-in, registration, sessions, password reset | `@nocobase/app-plugin-authentication` |
15
+ | User listing, account state, password reset, and application-owned role assignment | `@nocobase/app-plugin-users` |
16
+ | File upload and metadata through Repository | `@nocobase/app-plugin-file` |
17
+ | Translated text and language switching | `@nocobase/app-plugin-i18n` |
17
18
 
18
19
  Run `pnpm nocobase skills sync` if `.agents/skills/` is missing or looks out of date, then read the Skill for the plugin you need. It documents that plugin's public entries, the ownership boundary, and how to verify the result — which is faster and more correct than inferring an API from its source.
19
20
 
@@ -81,3 +81,15 @@ For approval policy, default to snapshot semantics for a formal submission unles
81
81
  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.
82
82
 
83
83
  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.
84
+
85
+ ## Role list presentation
86
+
87
+ The templates preinstall `#components/role-list` from the UI Registry. Keep role administration as a compact content list: body-sized names, muted identifiers and small protected/custom labels, with identifiers below names only in narrow containers. Reuse `RoleList` with localized labels and edit destinations; keep loading, empty/error states, search, sorting and authorization in the owning page. Do not turn each role into a heading or a padded card. For an existing application, reconcile the component together with its role-page integration through the template upgrade workflow, preserving application-specific fields and behavior.
88
+
89
+ Organize the role catalog around page access, business operations, users/accounts and system/tools. A page grant opens a page without granting its data or operations. Plugins register meaningful titles and action descriptions and explicitly place administrative capabilities; keep resource/action IDs stable when changing labels or grouping. User account actions are reviewed individually in information, security and role-assignment groups. Category navigation shows names only; omit group Select all controls and authorization counts. Do not add repetitive help disclosures to each checkbox. An empty composite data range grants no additional record access; default access, sharing and restriction rules may still apply, so do not label it as an effective denial. Show the names and selected values of multiple ranges in their collapsed summary.
90
+
91
+ ## Default data scope administration
92
+
93
+ 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.
94
+
95
+ On template upgrades reconcile the editor, list/form/model, route contribution, contextual role-form link, 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.
@@ -242,9 +242,17 @@ NocoBase Hub is discontinued, and with it `@nocobase/hub-cli` and the `pnpm noco
242
242
  3. Tell the user which CI steps and scripts published to a Hub, and that they need another deployment route: a deployment archive from `pnpm build --tar` installed with `@nocobase/app-installer`, or the application's `Dockerfile`, as the `nocobase-deployment` Skill describes. Ask before rewriting a pipeline; do not delete one silently.
243
243
  4. Ask the user to remove the saved Hub API keys from their credentials file themselves; never read or print them.
244
244
 
245
+ ## Compact role list source upgrades
246
+
247
+ When the target template introduces `client/components/role-list.tsx`, merge it together with the `RoleList` integration in `client/pages/settings/roles.tsx` and its declared Badge primitive dependency. The Registry source and both templates use the same compact rows; publishing the Registry or bumping dependencies alone does not update an existing application's copied source. Preserve application-owned role fields, search and sort behavior, query-preserving edit links, route registration, create permissions, loading/error/empty states and protected-role labels. Carry the presentation into a customized role page rather than replacing the page wholesale. Reconcile neutral record-name links in the user page and role list too, preserving hover underlines and the shared keyboard focus treatment. Verify long names, many roles, keyboard navigation and narrow layouts after reconciliation. Keep existing authorization resources, grants, saved roles and template version bookkeeping unchanged unless the complete corresponding template upgrade is performed.
248
+
245
249
  ## Permission editor source upgrades
246
250
 
247
- When the target template changes the permission workspace, reconcile `client/components/permission-editor.tsx`, its `permission-filter.tsx` input and declared UI primitives (including `checkbox` and `popover`), `client/pages/settings/permissions-model.ts`, the role form callback bindings, `permission-filters.tsx` and localized labels together. Resource rows use action checkboxes with scopes attached to their owning action; scope controls are not additional permissions. The optional `onEnabledBatchChange` reports one atomic batch for visible toggleable actions; bind it with one functional draft update that retains unknown grants, policies and scopes. Existing consumers without that callback retain individual action editing. Preserve application-specific resource registration, protected roles, save/revision checks and server authorization. Include a multi-action selection test and a test retaining existing scope policies. Registry source copies do not update themselves when the registry site publishes; bring this interaction in through the template source merge, preserving application customizations.
251
+ When the target template changes the permission workspace, reconcile `client/components/permission-editor.tsx`, its `permission-filter.tsx` input and declared UI primitives (including `checkbox`, `popover` and `tooltip`), `client/pages/settings/permissions-model.ts`, the role form callback bindings, `permission-filters.tsx` and localized labels together. Carry the compact permission layout and the localized `labels.dataRanges(count)` binding with it; multiple scopes expand under their owning action without modifying the draft. Resource rows use action checkboxes with scopes attached to their owning action; scope controls are not additional permissions. Keep individual draft updates atomic and retain unknown grants, policies and scopes; the legacy batch callback is accepted for source compatibility, but the updated editor renders no bulk controls. Existing consumers without that callback retain individual action editing. Preserve application-specific resource registration, protected roles, save/revision checks and server authorization. Include individual-action editing tests and a test retaining existing scope policies. Registry source copies do not update themselves when the registry site publishes; bring this interaction in through the template source merge, preserving application customizations.
252
+
253
+ ## Default data scope administration source upgrades
254
+
255
+ When the target introduces the default-access administration surface, reconcile `client/components/default-access-editor.tsx`, `client/pages/settings/default-access.tsx`, `default-access-form.tsx` and `default-access-model.ts`, the exported filter-label helper, confirmation error slot, route contribution, role-form link and locales together. Register the settings contribution in applications already exposing system management; preserve Default's intentionally bare Home-only startup when no settings are used. Merge the Permission management single-entry navigation transform, active-route aliases, `client/pages/settings/permission-management-page.tsx` and localized title with the existing role/default-scope pages; retain their route ids, URLs and guards, and do not create placeholder rule pages. Use the existing `settings:authorization.default-access` permissions and API. Preserve stored default rules and role grants: do not rerun seeds, rename resources, reset selections or default to All records. Keep unknown catalog values read-only, and merge into customized pages rather than overwriting them. Verify that the upgraded application reads existing rules and opens their independent scopes without writes; dependency updates or Registry publication alone do not install these source pages.
248
256
 
249
257
  ## Standard process management source upgrades
250
258
 
@@ -257,3 +265,7 @@ Verify the rendered directory/detail/history pages and parameter read/save behav
257
265
  ## Page permission label upgrades
258
266
 
259
267
  Reconcile `client/pages/settings/page-permissions.ts`, the role form's catalog adapter, the application-owned `page-permission-titles.ts` mapping, the localized unnamed-page fallback and `tests/logic/page-permission-titles.test.ts` together. Preserve existing mapping entries, route names, resource ids, actions, grants and policies; add translations for untitled page permissions rather than changing their authorization or adding breadcrumbs to overlays. Check the application's actual resolved routes in both languages, not just the bare template.
268
+
269
+ Reconcile the catalog descriptions, individual account-permission groups, category names without counts, individual action controls and labelled multi-scope summaries with the role form and locale updates. A display resource may share a stored resource ID with another display group: resolve a changed row by resource type, resource ID and action together, so later groups remain editable. Preserve all registered action IDs and existing unknown or structured policies. Update the authorization and Agent plugins together when adopting their new catalog labels, action-description metadata and administrative placement. An empty scope means no additional record access; retain default access, sharing and restriction behavior.
270
+
271
+ Keep empty-scope explanations in the range help tooltip rather than a permanent paragraph under every select. Reconcile the Tooltip primitive, scope hint label binding and localized text together; keyboard focus and touch activation must expose the same explanation without changing grants.