@nocobase/app-skills 0.0.0-stage → 0.1.0-beta.26

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.
Files changed (85) hide show
  1. package/package.json +37 -3
  2. package/skills/nocobase-app-development/SKILL.md +232 -0
  3. package/skills/nocobase-app-development/references/authorization.md +35 -0
  4. package/skills/nocobase-app-development/references/cli.md +70 -0
  5. package/skills/nocobase-app-development/references/commands.md +214 -0
  6. package/skills/nocobase-app-development/references/database-and-data.md +38 -0
  7. package/skills/nocobase-app-development/references/database-connections.md +212 -0
  8. package/skills/nocobase-app-development/references/frontend/frontend-dev.md +114 -0
  9. package/skills/nocobase-app-development/references/frontend/references/api.md +479 -0
  10. package/skills/nocobase-app-development/references/frontend/references/child-routes.md +647 -0
  11. package/skills/nocobase-app-development/references/frontend/references/example/complete-button.md +110 -0
  12. package/skills/nocobase-app-development/references/frontend/references/example/copy.md +444 -0
  13. package/skills/nocobase-app-development/references/frontend/references/example/create-dialog.md +99 -0
  14. package/skills/nocobase-app-development/references/frontend/references/example/create-page.md +96 -0
  15. package/skills/nocobase-app-development/references/frontend/references/example/customer-picker.md +162 -0
  16. package/skills/nocobase-app-development/references/frontend/references/example/delete-dialog.md +158 -0
  17. package/skills/nocobase-app-development/references/frontend/references/example/detail-drawer.md +267 -0
  18. package/skills/nocobase-app-development/references/frontend/references/example/detail-page-tabs.md +613 -0
  19. package/skills/nocobase-app-development/references/frontend/references/example/edit-dialog.md +250 -0
  20. package/skills/nocobase-app-development/references/frontend/references/example/list-page.md +545 -0
  21. package/skills/nocobase-app-development/references/frontend/references/example/members-card.md +222 -0
  22. package/skills/nocobase-app-development/references/frontend/references/example/project-dashboard.md +488 -0
  23. package/skills/nocobase-app-development/references/frontend/references/example/project-form.md +272 -0
  24. package/skills/nocobase-app-development/references/frontend/references/example/project-summary.md +180 -0
  25. package/skills/nocobase-app-development/references/frontend/references/example/public-switch.md +104 -0
  26. package/skills/nocobase-app-development/references/frontend/references/example/server-table.md +364 -0
  27. package/skills/nocobase-app-development/references/frontend/references/example/session-expired-alert.md +41 -0
  28. package/skills/nocobase-app-development/references/frontend/references/example/settings-form.md +284 -0
  29. package/skills/nocobase-app-development/references/frontend/references/example/settings-page.md +188 -0
  30. package/skills/nocobase-app-development/references/frontend/references/example/types.md +64 -0
  31. package/skills/nocobase-app-development/references/frontend/references/example/url-search.md +162 -0
  32. package/skills/nocobase-app-development/references/frontend/references/example.md +27 -0
  33. package/skills/nocobase-app-development/references/frontend/references/form.md +381 -0
  34. package/skills/nocobase-app-development/references/frontend/references/i18n.md +372 -0
  35. package/skills/nocobase-app-development/references/frontend/references/overlay.md +413 -0
  36. package/skills/nocobase-app-development/references/frontend/references/page.md +561 -0
  37. package/skills/nocobase-app-development/references/frontend/references/shadcn.md +91 -0
  38. package/skills/nocobase-app-development/references/frontend/references/shell.md +95 -0
  39. package/skills/nocobase-app-development/references/frontend/references/styling.md +361 -0
  40. package/skills/nocobase-app-development/references/frontend/references/table.md +242 -0
  41. package/skills/nocobase-app-development/references/frontend/references/testing.md +125 -0
  42. package/skills/nocobase-app-development/references/frontend/references/theme.md +446 -0
  43. package/skills/nocobase-app-development/references/frontend/references/ui-library.md +373 -0
  44. package/skills/nocobase-app-development/references/frontend/scripts/capture.md +114 -0
  45. package/skills/nocobase-app-development/references/frontend/scripts/capture.mjs +351 -0
  46. package/skills/nocobase-app-development/references/frontend/shadcn/SKILL.md +277 -0
  47. package/skills/nocobase-app-development/references/frontend/shadcn/agents/openai.yml +5 -0
  48. package/skills/nocobase-app-development/references/frontend/shadcn/assets/shadcn-small.png +0 -0
  49. package/skills/nocobase-app-development/references/frontend/shadcn/assets/shadcn.png +0 -0
  50. package/skills/nocobase-app-development/references/frontend/shadcn/cli.md +290 -0
  51. package/skills/nocobase-app-development/references/frontend/shadcn/customization.md +209 -0
  52. package/skills/nocobase-app-development/references/frontend/shadcn/evals/evals.json +77 -0
  53. package/skills/nocobase-app-development/references/frontend/shadcn/mcp.md +105 -0
  54. package/skills/nocobase-app-development/references/frontend/shadcn/registry.md +277 -0
  55. package/skills/nocobase-app-development/references/frontend/shadcn/rules/base-vs-radix.md +306 -0
  56. package/skills/nocobase-app-development/references/frontend/shadcn/rules/chat.md +250 -0
  57. package/skills/nocobase-app-development/references/frontend/shadcn/rules/composition.md +213 -0
  58. package/skills/nocobase-app-development/references/frontend/shadcn/rules/forms.md +192 -0
  59. package/skills/nocobase-app-development/references/frontend/shadcn/rules/icons.md +101 -0
  60. package/skills/nocobase-app-development/references/frontend/shadcn/rules/styling.md +185 -0
  61. package/skills/nocobase-app-development/references/frontend/templates/design.md +127 -0
  62. package/skills/nocobase-app-development/references/frontend/templates/prompts.md +51 -0
  63. package/skills/nocobase-app-development/references/frontend/templates/review.md +44 -0
  64. package/skills/nocobase-app-development/references/frontend/templates/run.md +39 -0
  65. package/skills/nocobase-app-development/references/frontend/ui-guidelines.md +220 -0
  66. package/skills/nocobase-app-development/references/frontend/ui-workflow.md +156 -0
  67. package/skills/nocobase-app-development/references/http-api.md +367 -0
  68. package/skills/nocobase-app-development/references/i18n.md +54 -0
  69. package/skills/nocobase-app-development/references/migrations.md +144 -0
  70. package/skills/nocobase-app-development/references/organization/model-and-service.md +112 -0
  71. package/skills/nocobase-app-development/references/organization/permission-design.md +103 -0
  72. package/skills/nocobase-app-development/references/organization/scopes.md +185 -0
  73. package/skills/nocobase-app-development/references/organization/settings-page.md +118 -0
  74. package/skills/nocobase-app-development/references/organization/subjects.md +275 -0
  75. package/skills/nocobase-app-development/references/organization/testing.md +25 -0
  76. package/skills/nocobase-app-development/references/organization.md +43 -0
  77. package/skills/nocobase-app-development/references/server-routes.md +267 -0
  78. package/skills/nocobase-app-development/references/services-and-jobs.md +289 -0
  79. package/skills/nocobase-app-development/references/template-variants.md +21 -0
  80. package/skills/nocobase-app-development/references/testing.md +171 -0
  81. package/skills/nocobase-app-upgrade/SKILL.md +143 -0
  82. package/skills/nocobase-app-upgrade/references/edge-cases.md +224 -0
  83. package/skills/nocobase-deployment/SKILL.md +164 -0
  84. package/skills/nocobase-deployment/agents/openai.yaml +6 -0
  85. package/README.md +0 -3
package/package.json CHANGED
@@ -1,6 +1,40 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0-beta.26",
4
+ "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
+ "license": "Apache-2.0",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/nocobase/nocobase.git",
9
+ "directory": "packages/app/app-skills"
10
+ },
11
+ "prettier": "@nocobase/dev-config/prettier",
12
+ "files": [
13
+ "skills"
14
+ ],
15
+ "publishConfig": {
16
+ "access": "public"
17
+ },
18
+ "devDependencies": {
19
+ "@playwright/test": "^1.62.1",
20
+ "prettier": "^3.9.6",
21
+ "@nocobase/dev-config": "0.1.0-beta.20"
22
+ },
23
+ "peerDependencies": {
24
+ "@playwright/test": "^1.62.1",
25
+ "prettier": "^3.9.6"
26
+ },
27
+ "peerDependenciesMeta": {
28
+ "@playwright/test": {
29
+ "optional": true
30
+ },
31
+ "prettier": {
32
+ "optional": true
33
+ }
34
+ },
35
+ "scripts": {
36
+ "format": "prettier . --write",
37
+ "format:check": "prettier . --check",
38
+ "check": "pnpm format:check"
39
+ }
6
40
  }
@@ -0,0 +1,232 @@
1
+ ---
2
+ name: nocobase-app-development
3
+ description: >-
4
+ Primary entry for developing features and UI in a NocoBase 3 application:
5
+ pages, routes, components, endpoints, data, permissions, services, translations, and tests.
6
+ Use this application-local workflow instead of globally installed NocoBase 2
7
+ Skills. Do not use for a published NocoBase 3 plugin package.
8
+ metadata:
9
+ short-description: Develop features in a NocoBase 3 application
10
+ ---
11
+
12
+ # NocoBase 3 application development
13
+
14
+ Use this Skill when building a feature in this application: a page, an endpoint, a table, a service, or the tests covering them.
15
+
16
+ Do not use it to develop a published plugin package. Plugin development has its own protocol and lives in a separate repository.
17
+
18
+ Do not use it to upgrade the template this application was generated from. That is `.agents/skills/nocobase-app-upgrade/`, which reconciles a newer template release against the application without reverting the user's work.
19
+
20
+ ## Before you start
21
+
22
+ Read the application's `AGENTS.md` first for the rules that apply everywhere. This Skill's references are the detail behind it. Before running any `pnpm nocobase` command, read [the command line](references/cli.md): it maps tasks to commands and states the flags an agent must not add on its own.
23
+
24
+ Confirm you are in an application and not a plugin package. An application has:
25
+
26
+ ```text
27
+ client/runtime.ts
28
+ server/runtime.ts
29
+ config.example.yml
30
+ ```
31
+
32
+ If instead you find `client/plugin.ts`, `server/plugin.ts`, or a `defineServerPlugin()` declaration, you are in a plugin package and this Skill does not apply.
33
+
34
+ Do not infer the application's capabilities from a template name or from this Skill. Inspect `package.json`, `client/plugins.ts`, `server/plugins.ts`, `cli/plugins.ts`, `server/config/index.ts`, and `database/` before deciding what is installed, registered, configured, or application-owned. `nocobase.templatePackage` and `nocobase.templateKind` identify known template ancestry when present, but a new template remains valid without being listed here. Read [template variants](references/template-variants.md) only when those files identify one of the documented official templates.
35
+
36
+ ## The one rule that decides most tasks
37
+
38
+ Build the feature in the application. Do not run a plugin generator, create a `packages/plugins/` directory, or write a `defineServerPlugin()` declaration for this application's own feature. Create a plugin only when the user explicitly asks for an independently published, reusable package.
39
+
40
+ ## Check the installed plugins first
41
+
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
+
44
+ | The requirement sounds like | Read the Skill for |
45
+ | --------------------------------------------------------- | ------------------------------------- |
46
+ | Approvals, multi-step processes, "when X happens then Y" | `@nocobase/app-plugin-workflow` |
47
+ | Email, IM, or in-app messages | `@nocobase/app-plugin-notification` |
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
+ | Translated text and language switching | `@nocobase/app-plugin-i18n` |
52
+ | User administration and application-owned role assignment | `@nocobase/app-plugin-users` |
53
+ | Reading or writing data, schema changes, migrations | `@nocobase/db` |
54
+
55
+ The Workflow plugin is disabled by default in the official application templates. Its presence in `dependencies` or synchronized Skills does not enable it; verify registration in Client, Server, and CLI before using it.
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.
58
+
59
+ For a workflow that pauses for an external decision, use the workflow plugin's `wait` node and its App-facing Skill. Persist the `runId` alongside the application's business identity and share the wait node's stable `nodeKey` with the authorized resumer; submit a stable event id through `workflowService.getInstructionApi('wait').resume()`. Keep early events for retry when the node is not ready, and keep authentication, authorization, and business side-effect idempotency in the application.
60
+
61
+ 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`.
62
+
63
+ Skills synchronization reads direct `@nocobase/*` dependencies from the application manifest and retains compatibility with explicitly registered plugins. It does not make an unregistered runtime plugin active; the composition roots remain the authority for registration and contribution order.
64
+
65
+ Install plugins with `pnpm nocobase plugin register <name>`. All application plugins belong in `dependencies`, including client-only and disabled plugins, because deployment dependencies come from that field. Plugin frontend libraries remain peers and are not automatically installed in the deployment. Re-registering migrates legacy `devDependencies` entries while preserving the declared range; verify the manifest and lockfile afterward. With an older CLI, use `pnpm add --save-prod <package>@<declared-range>` to correct the declaration; `--no-install` leaves lockfile synchronization to the caller.
66
+
67
+ To update a registered plugin, use `pnpm nocobase plugin update @nocobase/app-plugin-authentication` (or the short name `authentication`). Omit the name to update all registered plugins; add `--dry-run` to preview. `plugin update` takes a positional name, not `--plugin`, and re-synchronizes Skills after a successful package update. See the Plugins section of the application's `README.MD` for version-range behavior and examples.
68
+
69
+ ## Learn the endpoints from the API document
70
+
71
+ The running application describes every `/api` endpoint it serves — its own routes, every installed plugin's, the data endpoints and Better Auth's `/api/auth/...` — in an OpenAPI 3.1 document. Before calling an endpoint or building on one, fetch that document instead of reading route sources:
72
+
73
+ ```bash
74
+ curl -H "x-api-key: <key>" http://127.0.0.1:13000/main/api/swagger
75
+ ```
76
+
77
+ Replace `/main` with the application's `APP_BASE_PATH`. Swagger UI for people is at `<APP_BASE_PATH>/api/swagger/docs`. Reading either needs a signed-in session or an API key, which a user creates at `<APP_BASE_PATH>/settings/api-keys`; without one the routes answer `401`, and an application with no access check registered, such as one without the authentication plugin, answers `404`. Ask the user for a key rather than creating one yourself. [HTTP API design](references/http-api.md#api-documentation) explains how to read the document and how a new route declares itself in it.
78
+
79
+ ## Removing a direct NocoBase package
80
+
81
+ Before removing an `@nocobase/*` dependency, search the application's imports, Client/Server/CLI plugin registrations, routes, services, configuration, tests, and build scripts for the package name and the contracts it provides. Migrate or remove those references first. `package remove` updates dependency metadata and generated Skills; it does not rewrite application code or configuration and cannot decide whether the capability is still needed.
82
+
83
+ Run `pnpm nocobase package remove @nocobase/example`. The command uses the application's package manager to update `package.json` and the lockfile, then removes only synchronized Skills recorded as owned by that package. An `@nocobase/app-plugin-*` target delegates to the plugin unregister workflow so its Client, Server, and CLI registrations are removed together; `pnpm nocobase plugin unregister <name>` remains available. Use `--dry-run` before a consequential removal and `--json` when structured output is needed.
84
+
85
+ After an interrupted or manual removal, verify that the manifest no longer declares the package and run a full `pnpm nocobase skills sync` to reconcile stale package-owned output. Passing an already-absent package to `package remove` cleans recorded historical Skill ownership without uninstalling or cleaning another package.
86
+
87
+ ## Frontend work
88
+
89
+ Before writing or changing anything under `client/` — pages, components, styles, copy — read [the frontend workflow](references/frontend/ui-workflow.md). It decides whether the change takes the full workflow (a design file reviewed once, then an independent acceptance review), a theme change (tokens and presets, verified with the theme tests and a browser check) or a quick change (edit directly, then the static checks, the related tests and one look at the changed element in the browser), and which parts of [the UI guidelines](references/frontend/ui-guidelines.md) and [the frontend handbook](references/frontend/frontend-dev.md) to read at each step.
90
+
91
+ The handbook's "Look up by task" table routes each frontend task to the sections that cover it, and [the worked example](references/frontend/references/example.md) holds the complete files of the projects feature its rules are illustrated with. Components are shadcn/ui primitives, added with the CLI when a page first needs one: the shadcn/ui skill in `references/frontend/shadcn/` covers their API and composition rules, and [its guide in this handbook](references/frontend/references/shadcn.md) says what to read there and where this application departs from it.
92
+
93
+ ## Choose your reference
94
+
95
+ Read the page for the task in front of you. Do not read all of them.
96
+
97
+ | Task | Read |
98
+ | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99
+ | 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 |
100
+ | Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md) |
101
+ | 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) |
102
+ | Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md) |
103
+ | Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md) |
104
+ | Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md) |
105
+ | Translate server-produced text, add a language, set the default language | [internationalization](references/i18n.md) |
106
+ | Departments, positions or another organisation dimension that permission sets are assigned to | [organisation dimension](references/organization.md) |
107
+ | Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
108
+ | Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
109
+ | Write server and migration tests, choose a test layer, verify before finishing | [testing and verification](references/testing.md) |
110
+ | Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
111
+ | Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
112
+ | Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
113
+
114
+ A feature with a page and an API usually needs migrations, server routes, and a frontend change that follows the frontend workflow.
115
+
116
+ The three database pages above are the application side — where the files live, which commands run them, how connections are configured. The database API they are written against belongs to `@nocobase/db` and is documented by the `nocobase-db` Skill synchronized alongside this one. Read that Skill before writing a migration, a seed, or a query.
117
+
118
+ Frontend validation complements server-side validation and does not replace it.
119
+
120
+ ## Business permissions
121
+
122
+ When users describe different jobs, team responsibilities, confidential data, collaboration, field editing or restricted operations, read [application permission development](references/authorization.md) and the installed `nocobase-app-plugin-authorization` Skill before implementing the feature. Design pages, business actions and record scopes separately; apply database policies on the server and use client checks for visibility. The dedicated Skill covers declarations, custom scopes, relations, inherited subjects, optional rules, assignments and verification. Keep application-owned implementation in this App rather than scaffolding a plugin.
123
+
124
+ ## Database configuration factories
125
+
126
+ When a database driver requires `@nocobase/db` as a runtime peer, keep both in `dependencies`. TypeScript also uses that declaration to resolve inferred database configuration through the public package name; putting it only in `devDependencies` can cause TS2883 in an installed application even while a source workspace builds successfully.
127
+
128
+ Declare database defaults with `defineAppDatabaseConfig` from `@nocobase/app-server/database`. When switching or adding connections, read [database connections](references/database-connections.md) for complete examples, YAML overrides, schema ownership and verification.
129
+
130
+ ## Where to work
131
+
132
+ Business code belongs in a small, stable set of places:
133
+
134
+ ```text
135
+ client/routes.ts, client/pages/, client/components/, client/hooks/,
136
+ client/locales/, client/service-provider.ts, server/routes/,
137
+ server/providers/, database/main/migrations/, database/main/seeds/, tests/
138
+ ```
139
+
140
+ Everything else — `client/routing/`, `client/layouts/`, `client/theme/`, the server entry points, the build scripts, the tsconfigs — is the framework structure the template provides and evolves. Prefer the mechanism the system already offers: most work that looks like it needs a change there does not.
141
+
142
+ 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 update the application's `AGENTS.md` in the same change so it still describes the real application. The synchronized NocoBase Skills are package-owned; propose a change to their source package when the shared framework guidance itself is wrong.
143
+
144
+ 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): the Settings header entry, dev pages inside the App shell, the language submenu, navigation group state, permission refresh and sign-out handling.
145
+
146
+ ## Ownership
147
+
148
+ ```text
149
+ You own pages, components, endpoints, tables, migrations, services,
150
+ translations, tests, navigation, theme, business logic
151
+
152
+ Packages own their routes, components, tokens, services, internal tables,
153
+ and any skills/ they publish
154
+
155
+ Generated .agents/skills/ — synchronized copies, gitignored, replaced
156
+ wholesale on the next sync; never edit
157
+ .claude/skills/ — symbolic links to the above so Claude Code
158
+ discovers them; gitignored, rewritten by the same sync
159
+
160
+ Config config.yml — written by pnpm nocobase config init, gitignored, holds
161
+ secrets; document options in config.example.yml instead
162
+ ```
163
+
164
+ Reach a plugin's capability only through its documented package exports. Never import a plugin's internal source path or write to its tables directly.
165
+
166
+ ## Reversible customization
167
+
168
+ When customizing template or registry UI, prefer existing props and composition, then new application components outside `client/extensions/`. Keep the original extension implementation as the reusable baseline; edit it only when explicitly requested or when composition cannot reasonably meet the requirement, and explain that choice. See [styling](references/frontend/references/styling.md).
169
+
170
+ Treat disabling a feature as a reversible availability change by default: preserve its page and component source, conditionally exclude or guard its route, and hide its links and actions. A hidden navigation item alone does not disable direct URL access. Enforce the same feature policy on the server so direct API calls cannot execute the disabled operation. Do not delete feature code merely to remove it from the current UI; explicit permanent removal can justify deletion. See [pages and routes](references/frontend/references/page.md).
171
+
172
+ ## Non-negotiables
173
+
174
+ These cause real damage and appear in every reference:
175
+
176
+ - **Every server route owns its own authentication and authorization.** Mounting under `/api` authenticates nothing.
177
+ - **Every `/api` route follows [HTTP API design](references/http-api.md).** camelCase paths, `{ data }` on success, `ApiError` on failure, input validated through `apiValidator()`, and a `describeRoute()` declaration for the API document. Never hand-write an error body.
178
+ - **A migration is immutable history and self-contained.** Never import an evolving definition into one. Never edit one whose branch is merged.
179
+ - **Every user-visible string goes through a translation key**, the English built into shadcn/ui primitives included.
180
+ - **Let the owning page supply `PageContainer`.** One per page; inline child pages and tabs use the parent's, covering child pages add their own, overlays use their own container. See [section 2 of pages and routes](references/frontend/references/page.md#2-the-page-component).
181
+ - **Visual consistency is application-wide.** Restyling only your part is a defect. Change the design tokens if a change is needed.
182
+ - **Route paths never include the deployment base path.** The runtime restores it.
183
+ - **Route navigation creates sidebar entries.** Declare `navigation` in `client/routes.ts`. Refine resources create no menu entries and, with no data provider registered, load nothing; pages load data with `useApiClient` (see [calling the API](references/frontend/references/api.md)).
184
+ - **Reach for the built-in mechanism first.** Changing framework structure is allowed when nothing else fits — comment it and update the docs.
185
+ - **Tests live in `tests/`,** never beside the source; browser tests against a running application go in `tests/playwright/`.
186
+ - **Remove direct NocoBase packages with `package remove` after reviewing their usage.** Do not hand-delete only the manifest entry or leave synchronized Skills and plugin registrations behind.
187
+
188
+ ## Development file watching
189
+
190
+ `pnpm dev` checks native file watching before starting its children. If watcher resources are exhausted or native events are unavailable, it uses polling for client and server hot updates and disables agent annotations for that run, with a warning. An explicit `CHOKIDAR_USEPOLLING=true` selects the same mode. Configuration files use stat polling so atomic saves and newly created files restart the server without native directory watchers.
191
+
192
+ Vite must exclude the application's entire `dist/` tree from development file watching. Its default exclusion covers only `dist/client`; watching the compiled server and vendored packages can cause `EMFILE` after a build. Keep the exclusion scoped to this application so linked workspace dependencies, including their `dist/` files, still receive hot updates.
193
+
194
+ ## Remote backend development
195
+
196
+ Treat `/main` in examples as a default, never as a fixed route. Local `APP_BASE_PATH` resolves from the command-line environment, then `.env.local`, then `.env`, with `/main` as the fallback. Determine the remote application's actual public mount path separately and include it in `PROXY_TARGET_URL`; local and remote paths may differ. For example, local `APP_BASE_PATH=/local` and a target ending in `/crm` map `/local/api` to `/crm/api` and `/local/ws` to `/crm/ws`.
197
+
198
+ For local client debugging against another running application, use `PROXY_TARGET_URL=<remote-application-base-url> pnpm dev` (for example, `http://127.0.0.1:13000/main`, without `/api`). This starts Vite, proxies API and WebSocket paths, and skips the local server and its watchers. Existing `beforeDev` hooks still run. Open the printed Local URL. Client edits reload locally; backend edits require running or deploying the target separately. Requests use the target's data and permissions. See README.MD for authentication and path mapping requirements. Unset the variable to develop both sides locally.
199
+
200
+ The proxy maps same-origin browser HTTP and WebSocket Origin headers to the target origin, with matching Referer paths mapped to the target app base. It preserves foreign origins and does not add missing Origin headers. Test browser handshakes with an explicit Origin; an Origin-less Node WebSocket test does not verify browser compatibility. Production does not use this Vite adaptation: configure `APP_PUBLIC_ORIGIN` and preserve public Host/protocol information through the reverse proxy.
201
+
202
+ Use `APP_SERVER_PORT` for the local entry port in both development modes. With `PROXY_TARGET_URL` it selects Vite's preferred port, defaulting to 5173; without it, it selects the local backend port, defaulting to 13000, and Vite still starts from 5173. If occupied, the port advances automatically. Open the printed Local URL and keep the remote service address in `PROXY_TARGET_URL`.
203
+
204
+ ## Finishing
205
+
206
+ `pnpm build --help` (or `-h`) lists build options and exits without loading build dependencies, running hooks, or modifying `dist/`. Every successful build records `nocobase.buildTarget` in `dist/package.json`, including builds with no native modules: `platform`, `arch`, `libc`, `nodeMajor`, and `nodeAbi`. Use `libc` only for Linux; its value on other platforms is a compatibility placeholder. Deployment checks should compare these fields with the host runtime and also respect `engines.node`. With `--target current` (the default), the Node version and ABI come from the running process; an explicit platform target defaults to Node 24 unless `--node-version` is supplied.
207
+
208
+ When building for another platform, pass `--target` and verify the native binaries retained in `dist/node_modules`. `better-sqlite3` 13 bundles N-API binaries for multiple platforms; Alpine targets need the `linuxmusl` binary, while other Linux targets use the `linux` binary.
209
+
210
+ For each change, scope all verification to affected files, projects, or packages and their affected consumers, including formatting, lint, type checking, tests, builds, and runtime checks. Use supported file selectors, project configurations, and workspace package filters. Do not default to full-application or workspace-wide commands or `pnpm check`. Run the smallest supported scope when a required check cannot be narrowed further, and explain why. Expand or repeat checks only when further changes, dependency impact, configuration changes, or failures justify it, or the user requests it. Documentation-only changes need formatting and link checks for changed documents, not type checking, runtime tests, or builds. Follow [Testing and verification](references/testing.md) for selection examples.
211
+
212
+ Verify observable behavior, not just that the commands passed. [Testing and verification](references/testing.md) lists what to check for each kind of change.
213
+
214
+ After adding or removing a language in `client/locales/` or `server/locales/`, run `pnpm nocobase locales check`. It compares only the two language lists: it reports a language declared on one side alone and exits nonzero until the lists align. A client-only language is still supported at runtime and the server falls back to English; add matching server translations when server-produced text should use that language.
215
+
216
+ Application startup defaults belong in `config.yml`: `i18n.defaultLocale` for the language, and `client.app.defaultColorScheme` and `client.app.defaultTheme` for appearance. Valid browser-local choices take precedence. Which languages the interface offers is not configured — `client/locales/` is that list, while `server/locales/` independently defines the server's translated languages. See [internationalization](references/i18n.md), [frontend copy](references/frontend/references/i18n.md) and [themes and tokens](references/frontend/references/theme.md).
217
+
218
+ ## Publish application releases
219
+
220
+ Deploying to a Hub uses the `pnpm nocobase hub` commands, which the application has while it depends on `@nocobase/hub-cli`: `hub remote add` records the target App in `.nocobase/hub.json`, `hub auth login` saves its API key outside the project, and `hub deploy` builds for the Hub, uploads and deploys. Read `.agents/skills/nocobase-hub-cli/SKILL.md`, which that package ships, before running them, and the `nocobase-deployment` Skill for the rest of a production deployment.
221
+
222
+ ## Logging and hosted applications
223
+
224
+ Use the application logging service for diagnostics so entries carry application identity and follow its level and output policy. Development pretty output uses local time and displays `[appId/logger]`; file and JSON console output retain UTC timestamps and structured context. Request starts and headers, configuration diagnostics and AI resource loading stages are DEBUG; request completions and AI resource totals are INFO. Default optional `ai/skills` directories may be absent; explicitly configured missing directories still warn.
225
+
226
+ The Hub configures hosted application output under `hub.logging.apps`; its own output uses `logging`. Deployed releases carry their own runtime and logging packages: updating the Hub cannot repair an old application formatter that prints numeric levels or omits context, or make an old runtime understand the structured console policy. Upgrade the application dependencies, rebuild and deploy a new release; never edit a deployed artifact or intercept process-wide stdout to rewrite other applications’ logs. Verify console enablement and pretty mode after upgrading.
227
+
228
+ Authentication diagnostics use the application `auth` logger unless an explicit authentication logger is configured. A missing Better Auth base URL is a configuration warning, not a logging error: configure `app.publicOrigin` with the externally reachable origin in the application deployment configuration. Do not substitute the internal Host bind address or suppress the warning to make startup appear clean.
229
+
230
+ ## Hub storage maintenance
231
+
232
+ Hub storage separates Hub-owned state, Host runtime files, release archives, expanded revisions and persistent application volumes. Standalone source and compiled entries share the deployment directory's storage; `APP_STORAGE_DIR` selects another storage directory, and explicit storage paths take precedence over it. Embedded applications use Host-provided paths. Expanded releases live at `appRevisionsDir/<appId>/<sha256>` and restart recovery requires their installed metadata. Build archives use `storage/exports/dist.tar.gz`.
@@ -0,0 +1,35 @@
1
+ # Design application permissions
2
+
3
+ Use this reference when a feature distinguishes people, jobs, teams, pages, operations, fields or records. Model access while designing the feature; adding only hidden buttons after building unrestricted endpoints leaves the system incomplete.
4
+
5
+ ## Discover the capability
6
+
7
+ Inspect `package.json`, `client/plugins.ts`, `server/plugins.ts` and `server/config/authorization.ts`. Read the installed `.agents/skills/nocobase-app-plugin-authorization/SKILL.md` before implementation. If installed Skills are stale, run `pnpm nocobase skills sync`; do not edit generated copies. Check registration separately from dependency presence.
8
+
9
+ Default access, sharing rules and restriction rules are optional plugins. Read their installed Skills when the business requirement calls for a common baseline, collaboration exception or record exclusion. If the corresponding Skill is absent, treat the capability as unsupported in this App and explain that it requires separate development. Do not assume its APIs, tables or seed format, or silently install/configure it. If the Skill exists, follow it to verify runtime activation and migrations. Implementation and seed details belong to that owning Skill. Do not implement replacement role tables or assume all optional plugins are present.
10
+
11
+ ## Turn requirements into a matrix
12
+
13
+ Record actor/job, page, business operation, data scope, readable/writable fields, relation capabilities and administrator responsibilities. Use real jobs as permission sets and business relationships as scopes. Clarify material missing boundaries, such as whether a delegate can submit as well as edit, and whether a confidentiality restriction must cover every operation.
14
+
15
+ Keep page access independent from business action grants. Distinguish operations that can touch the same table: editing a draft may update amount/notes while submission only changes state after checking the parent project. A user can hold both a personal job and a team job; revoking the team source should preserve unrelated personal responsibilities.
16
+
17
+ ## Implement in application-owned files
18
+
19
+ For new and existing features alike, classify the requested changes by content. Supported operations, fields/relations, resolver behavior and enforcement belong to the model; selecting supported scopes/parameters, grants, rules and recipients belongs to configuration. A request can require both. When developing a permission model, also complete its usable initial or adjusted business configuration from the responsibility matrix; do not stop at declarations unless the user explicitly asks for model-only work. Clarify unknown recipients without guessing assignments.
20
+
21
+ Declare reusable collection permissions and business operations, defined as composite resources, in a feature module. In `server/providers/`, resolve `authorizationToken`, then register collections (`authz.database.collections.add`), composites (`authz.compositeResources.define`), record access (`authz.recordAccess.define`), settings items (`authz.settings.add`) and, when the feature owns a team or department model, inherited subjects (`authz.subjects.add`, built as [an organisation dimension](organization.md)); add workspace subsections with `authz.ui.sections.add` and list each composite or settings item in one with `authz.ui.place`. Pages are not registered on the server; the client routes list them. Read the authorization Skill’s bundled `references/code-and-seeds.md` before choosing initialization: code declares capabilities, provider boot registers them, and seeds initialize the agreed business configuration for fresh installations. Use authorized services or controlled data changes for existing installations. Seeded permission sets, selected scopes, rules and assignments remain editable in the backend; seeds do not make them code-owned or protected. App features own composite declarations and initial business configuration, not root/member protection or other platform permission configuration. Never rewrite administrator configuration at boot. Normal seeds have a restricted database context, not the running authorization service. Keep schema changes in migrations and initial assignments in idempotent seeds or controlled provisioning. Do not create a plugin package for an application-owned feature.
22
+
23
+ Every `server/routes/` endpoint installs authentication and authorization. A business operation checks `{ resource: { type: 'composite', id }, action }` with the request context's `authorize` once and binds each returned `conditions.database` policy through `repository.withPolicy`. Do not replace it with collection-level authorization or an in-memory filter. Use `authz.database.policyFor` for collection CRUD and `authz.database.authorizeRepository` for simple business Repository routes, mapping each method to its composite action. The authorization Skill documents these choices and their contracts.
24
+
25
+ Declare `authz` on the first page of every path in `client/routes.ts`: `{ resource: { type: 'page', id }, action: 'access' }` for a business page, the page's `settings` item for a settings page, `'unrestricted'` for a root-only page, or `'skip'` explicitly; nothing is inferred from the route name. Nested pages inherit it; an omitted value on a first page defaults to `'unrestricted'` for protected App and settings pages and `'skip'` otherwise, with a development warning. Use `useCan({ resource, action })` for button visibility and server-computed eligibility for record-sensitive actions. Keep pending/failed checks closed and refresh after permission changes. Client visibility does not enforce the API. The authorization Skill’s `references/client-development.md` includes the component, relation controls and settings lifecycle; all required APIs are bundled in that Skill rather than external package documentation.
26
+
27
+ The permission workspace edits page grants, business actions with their data scopes, and settings items. Field and relation capabilities are code-owned. A new field or workflow must update its declaration and enforcement; it is not an administrator entering arbitrary database grants. Follow the dedicated Skill for custom record access, multi-table transactions, relation targets, protected assignments and last-administrator checks.
28
+
29
+ ## Verify and explain
30
+
31
+ Test an ordinary user with no grant, page-only and action-only grants, rows owned by another user, forbidden fields, invalid relation targets, and stale workflow states. For multi-table operations, remove each required scope independently. Test direct API requests, rollback and independent revocation of direct/inherited sources. Use the inspector to understand decisions, not as a substitute for running the operation.
32
+
33
+ Explain to the user which business decisions were implemented, which settings they can maintain and which changes require development. Use the authorization Skill’s bundled quote/project/delivery workflow as the implementation reference, but do not copy demo credentials, fixed record IDs or reset endpoints into the App.
34
+
35
+ For a custom initial administrator, configure `users.initialAdmin` before the first seed run; see the authentication plugin Skill for its username/password contract. Omitting the node preserves the legacy account. The authentication seed creates the account only in an empty user table, and the authorization seed assigns root using the same configured username. Do not reset credentials at startup.
@@ -0,0 +1,70 @@
1
+ # The application command line
2
+
3
+ This page is how to use the application's CLI: which command a task needs, and the rules its `--help` does not state. For a command's flags and arguments, run `pnpm nocobase <topic> <command> --help` rather than guessing; for the whole tree, `pnpm nocobase commands --json`, which lists every command registered here — built-in, the application's and each plugin's — with its source, arguments, flags, examples, and whether it takes `--json`, `--dry-run` and `--force`.
4
+
5
+ ## How to invoke it
6
+
7
+ `pnpm nocobase <topic> <command>` runs the `nocobase` bin of `@nocobase/app-cli`, which this application depends on. It finds the application from the nearest `package.json` and loads `cli/plugins.ts` and `cli/commands/` itself.
8
+
9
+ Only `pnpm dev`, `pnpm build`, `pnpm start` and the quality scripts (`pnpm test`, `pnpm lint`, `pnpm typecheck`, `pnpm check`, …) are scripts. Every other command is reached through `pnpm nocobase`; there is no `pnpm db:apply` or `pnpm config:init`. Older documentation that names a script alias, or an id under the `app` topic such as `nocobase app db apply`, is describing a removed layout.
10
+
11
+ Write `pnpm nocobase`, not a bare `nocobase`: a machine may have an unrelated global `nocobase` on its `PATH`, while `pnpm` resolves this application's own bin first.
12
+
13
+ ## Find the command by task
14
+
15
+ | Task | Command |
16
+ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
17
+ | Create `config.yml` for a new checkout | `pnpm nocobase config init` (`--dialect <name>` when several drivers are installed) |
18
+ | Change a configuration value, or read a secret from the environment | `pnpm nocobase config set key=value`, `--from-env` for secrets |
19
+ | Confirm the configuration before starting | `pnpm nocobase config check` |
20
+ | See which environment variables the application reads | `pnpm nocobase config env` |
21
+ | Describe every variable for a deployment (`dist/variables.json`) | `pnpm nocobase config variables`, `--out <file>` to write it |
22
+ | Apply new migrations and seeds | `pnpm nocobase db apply` |
23
+ | Undo or rerun the latest migration batch while its branch is open | `pnpm nocobase db rollback`, `pnpm nocobase db redo` |
24
+ | Start the schema over from empty | `pnpm nocobase db reset` — destructive, see below |
25
+ | Clear a checksum warning after a deliberate, schema-neutral edit | `pnpm nocobase db repair --dry-run`, then without `--dry-run` |
26
+ | Release a migration lock a killed run left behind | `pnpm nocobase db unlock` |
27
+ | Load sample data an installation skipped, in development | `pnpm nocobase db sample` |
28
+ | Read the current data model | the files under `database/<connection>/collections/`, see below |
29
+ | Find Collection metadata that disagrees with its table | `pnpm nocobase collections doctor` |
30
+ | Check that client and server declare the same languages | `pnpm nocobase locales check` |
31
+ | Add, remove or update a plugin | `pnpm nocobase plugin register`, `plugin unregister`, `plugin update` |
32
+ | Check a plugin's registration without changing anything | `pnpm nocobase plugin inspect <name> --json` |
33
+ | Remove a direct NocoBase package that is not a plugin | `pnpm nocobase package remove <package>` |
34
+ | Refresh `.agents/skills/` after an install or upgrade | `pnpm nocobase skills sync` |
35
+ | Build for another platform, or re-check an existing `dist/` | `pnpm build --target <platform>`; `pnpm nocobase dist retarget`, `dist check` |
36
+ | Deploy to a Hub | `pnpm nocobase hub deploy`, after `hub remote add` and `hub auth login` — read its `nocobase-hub-cli` Skill |
37
+ | Give the application a command line of its own, for people and agents | declare `nocobase.cli` in `package.json`, then `pnpm nocobase cli link`; see below |
38
+ | Pack that CLI, or the agent runner, for the application to serve | `pnpm nocobase cli build`, `pnpm nocobase cli build --runner` |
39
+
40
+ Every command listed takes `--connection <name>` or `--all` where connections apply; without either it acts on the default connection.
41
+
42
+ ## Conventions an agent relies on
43
+
44
+ - **`--json`** prints one JSON document on stdout, success or failure, the same shape for every command: `{ schemaVersion, ok, command, status, result | error, warnings }`. `status` is `success`, `success-noop` (nothing needed changing: a dry run, or a run that found nothing to do), `partial-success` or `failure`. Read `result` on success; on failure read `error.code`, `error.suggestions` — each a `message` and, where the next step is a command, a `run` with its `command` and `args`, which names `node <dist>/cli/index.js` rather than `pnpm nocobase` in a built `dist/` — and `error.details`. Read `warnings` too, and check the exit code rather than parsing text. `NOCOBASE_CONTENT_TYPE=json` turns `--json` on for every command in a session. What the application logs while a command runs, and a command's progress, go to stderr, also under `--json`. When a command fails for a reason its message does not explain, rerun it with `NOCOBASE_CLI_DEBUG=1` to print the error behind it, redacted, on stderr; do not paste that output anywhere public without reading it.
45
+ - **Invalid usage** — a flag or argument the command rejects, or a command that does not exist — fails with `error.code` `INVALID_USAGE`, and its suggestions name the flag or command that was probably meant. Check that suggestion against the task before running it. The message names flags, arguments and allowed values but never repeats a value that was typed, since a mistyped line can carry a secret; compare it with the line you ran.
46
+ - **Exit codes** are `0` for success, `1` for a runtime failure and `2` for invalid usage; `hub deploy` and `hub upload` add `3` for a result the Hub could not confirm. Keep a non-zero exit visible in your report; do not rerun until it passes by changing flags.
47
+ - **Paths** given in a flag resolve from the current directory, as with any command line. The exception is `config init --config`, which resolves against the application root, the same way as `APP_CONFIG_FILE`. A default path a command names in its `--help`, such as the `hub deploy` archive, is inside the application.
48
+ - **Preview first.** `db apply`, `db rollback`, `db redo`, `db reset`, `db repair`, `plugin register`, `plugin unregister`, `plugin update`, `package remove` and `skills sync` take `--dry-run`: it changes nothing — it does not even create a SQLite file that does not exist yet — answers `status: "success-noop"`, and returns the plan in `result` — for the `db` commands `result.plan`, one entry per connection and kind with its `action` and the task names. Use it before any change whose effect you have not already confirmed with the user.
49
+ - **Destructive commands need `--force` outside a terminal.** `db reset`, `db rollback`, `db redo` and `db repair` ask for confirmation interactively and refuse without `--force` in CI or any non-interactive shell, which is how an agent runs them: `error.code` is `FORCE_REQUIRED` (exit 2), `error.details.plan` is exactly what the command would do, and `error.suggestions` carry the `--force` and `--dry-run` forms. Do not add `--force` on your own initiative to get past that refusal: `db reset` drops every managed table. Show the user the plan, ask, and never run it against a database whose data matters. `db unlock --force` releases a lock that is still sending heartbeats, which lets a second run start beside a live one — only do it when the user confirms the other run is gone. A command that finds the lock held fails with `DATABASE_LOCKED`; `error.details` names the holder (`lockedBy`, `heartbeatAt`, whether it `expired`), and the suggestions say whether unlocking needs `--force`. Waiting and retrying is the usual answer.
50
+ - **Do not start the application to run a command.** CLI commands work on files and the database directly; none of them needs `pnpm dev` running.
51
+
52
+ ## Reading the data model
53
+
54
+ `database/<connection>/collections/` holds what the database currently resolves each Collection to — `collection.json`, `metadata.json` and `schema.json` per Collection, plus `_manifest.json` — written by `pnpm nocobase collections generate`. Read these files, and search across them, rather than inferring the model from migrations.
55
+
56
+ The directory is a local cache for every connection, external ones included: gitignored, safe to delete, and never read back. `db apply`, `db redo`, `db rollback` and `db reset` refresh it for each connection whose migrations they change, and `pnpm dev` does the same after its startup migrations; a built `dist/` never writes it. Run `pnpm nocobase collections generate` yourself only when a command ran with `--no-collections` or warned that the refresh failed, after editing an external connection's `metadata/`, or after another system changed an external connection's schema. `--check` exits non-zero when the files are out of date. Never edit them by hand or import them from a migration.
57
+
58
+ An external connection's metadata — titles, descriptions and relations its schema cannot express — is written by hand in `database/<connection>/metadata/<name>.json`, one metadata document per Collection, and committed. Edit those files, then regenerate so the cache reflects them; the command reports a document whose Collection the database no longer has as unused metadata.
59
+
60
+ ## A command line of the application's own
61
+
62
+ Besides `pnpm nocobase`, an application may give the people and agents who use it a CLI of its own, such as `acme`: `@nocobase/app-cli-client` under the application's name, which signs in to the running application and runs the business commands its API publishes (`GET /api/cli/manifest`). No template declares one. To add it, put `"nocobase": { "cli": { "bin": "<command>", "displayName": "<Name>" } }` in `package.json` (the fields are in `@nocobase/app-cli`'s README: the state directory, the environment prefix, the device sign-in client id, the Skill directories it ships to runners, …) and add `@nocobase/app-cli-client` to `devDependencies`. `pnpm nocobase cli link` makes it a command in `node_modules/.bin`; `pnpm nocobase cli build` packs it into standalone tarballs in `storage/runners/dist`, which the agents plugin serves to its install script and to runners, and `cli build --runner` packs the runner (`nocobase-runner`, from `@nocobase/agent-runner`) beside it. In production a CI job builds them and mounts them into that storage; do not commit them or bake them into an image.
63
+
64
+ ## The application's own commands
65
+
66
+ An application's own commands answer under the `app` topic, one file per command under `cli/commands/`. To add or change one, read [adding an application command](commands.md).
67
+
68
+ ## In a built dist/
69
+
70
+ `pnpm build` writes `dist/cli/index.js`. A deployment runs `node dist/cli/index.js <topic> <command>` from any directory, or `pnpm nocobase <topic> <command>` inside `dist/`. Only runtime commands are registered there — `config`, `db`, `collections`, `locales`, `info`, the application's own commands and plugins' runtime commands. `dev`, `build`, `start`, `dist`, `plugin`, `package` and `skills` exist only in the source checkout, and so do the `hub` commands `@nocobase/hub-cli` contributes. See the `nocobase-deployment` Skill for production procedure.