nuxt-unified-ui 0.5.1 → 0.5.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-unified-ui",
   "type": "module",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "main": "./nuxt.config.ts",
   "types": "./index.d.ts",
   "exports": {
@@ -20,7 +20,7 @@
   ],
   "dependencies": {
     "@formkit/tempo": "1.1.0",
-    "@iconify-json/lucide": "1.2.122",
+    "@iconify-json/lucide": "1.2.123",
     "@nuxt/kit": "4.5.2",
     "@nuxt/ui": "4.10.0",
     "@nuxtjs/i18n": "10.6.0",

package/skills/nuxt-unified-ui/SKILL.md

@@ -5,10 +5,12 @@ description: >-
   install/extend the layer, required CSS, modules/config, radashi radXxx
   auto-imports, un-form / useForm, launchFormPickerDialog /
   launchChoicePickerDialog, toast helpers, un-card / un-typography, pages /
-  definePageMeta, ufetch / useUFetch wrapping, attribute order/defaults, and
-  whitespace/formatting conventions for all Nuxt-generated code. Use when
-  working in or consuming nuxt-unified-ui, or whenever generating Vue/Nuxt code
-  that must match unified code style.
+  definePageMeta, ufetch / useUFetch wrapping, unified resources
+  (server plugins, REST handleResource*, resource-manager dashboard /
+  customization), attribute order/defaults, and whitespace/formatting
+  conventions for all Nuxt-generated code. Use when working in or consuming
+  nuxt-unified-ui, declaring or customizing resources, or whenever generating
+  Vue/Nuxt code that must match unified code style.
 ---
 
 # nuxt-unified-ui
@@ -23,6 +25,7 @@ This is the **only** installable skill in this repo. Deep topics live under `ref
 
 - Installing / extending `nuxt-unified-ui` as a Nuxt layer
 - Using `un-form`, dialogs, toasts, `un-card`, radashi `radXxx`, etc.
+- Declaring or customizing **unified resources** (plugins, REST, dashboard)
 - **Whenever generating or editing Nuxt/Vue/server code** that must follow the unified look (whitespace, wrapping, template shape, sectioning)
 
 ## References (read as needed)
@@ -30,6 +33,7 @@ This is the **only** installable skill in this repo. Deep topics live under `ref
 | Topic | File |
 |-------|------|
 | **Code style (mandatory)** | [references/code-style.md](references/code-style.md) |
+| Unified resources (plugins → REST → dashboard) | [references/resources.md](references/resources.md) |
 | Pages / routing | [references/pages.md](references/pages.md) |
 | Data fetching (`ufetch` / `useUFetch`) | [references/data-fetching.md](references/data-fetching.md) |
 | Layer install + required CSS | [references/layer-setup.md](references/layer-setup.md) |
@@ -52,14 +56,15 @@ Absolute highlights:
 
 - `<script setup>` only — **never** `lang="ts"`; no TS annotations in Vue (runtime prop types)
 - 2-space indent; single quotes; semicolons; trailing commas in multi-line literals
+- **`.js` / `.ts` file start:** two leading blank lines, **except** when the file starts with imports — then **no** blank lines before the first `import`
 - Double blank lines between major sections; blank line before `</script>`; **two** blanks before `<template>`
 - Non-trivial async/functions: blank line after `{`, double blank between major steps, blank before `}`
 - `else` / `catch` on their own line after `}`
 - Script object literals always multi-line (even one property)
 - Kebab-case tags (`u-button`, `un-card`)
 - `v-if` / `v-for` on `<template>` wrappers — not on rendered nodes
-- **2+ attributes → one per line**; attribute order + default omissions (`variant="subtle"`, omit neutral `color`, `loading-auto`); non-self-closing `>` on same line as last attr; multi-line self-closing `/>` on its own line
-- `{{ ... }}` on its own line
+- **2+ attributes → one per line** except **`u-modal`** (keep all `u-modal` attrs on one line); attribute order + default omissions (`variant="subtle"`, **Cancel only → `ghost`**, omit neutral `color`, `loading-auto`); non-self-closing `>` on same line as last attr; multi-line self-closing `/>` on its own line
+- `{{ ... }}` on its own line (static + dynamic text may mix)
 - `/* section */` comments; imports co-located under the section that uses them
 - Light naming: `handleXxx` handlers, `it` in short callbacks, descriptive `for...of`, computeds use block + `return`
 - Pages: explicit `definePageMeta.name`, reactive route params, named `navigateTo` / `nuxt-link` → [pages.md](references/pages.md)
@@ -139,6 +144,7 @@ From `nuxt.config.ts`: `@vueuse/nuxt`, `@nuxt/ui`, `@nuxtjs/i18n`; `ui.colorMode
 | Utilities | `radXxx` → [radashi.md](references/radashi.md) |
 | New page / route | [pages.md](references/pages.md) |
 | List/detail fetch or mutation | [data-fetching.md](references/data-fetching.md) |
+| New / custom resource | [resources.md](references/resources.md) |
 | Formatting any of the above | [code-style.md](references/code-style.md) |
 
 ## Do / don’t
@@ -150,6 +156,7 @@ From `nuxt.config.ts`: `@vueuse/nuxt`, `@nuxt/ui`, `@nuxtjs/i18n`; `ui.colorMode
 - Use field `identifier` for element kind; `type` only for HTML input types
 - Handle dialog actions in `onClick`
 - Follow code style for every generated file
+- Resources: plugin → full REST set → dashboard nav / custom `<resource-manager>` page → [resources.md](references/resources.md)
 
 **Don’t**
 
@@ -158,3 +165,4 @@ From `nuxt.config.ts`: `@vueuse/nuxt`, `@nuxt/ui`, `@nuxtjs/i18n`; `ui.colorMode
 - Use PascalCase component tags in templates
 - Set choice-button `value` unless the await result must distinguish buttons
 - Assume color mode is enabled (layer disables it)
+- Reimplement resource CRUD in route files (use `handleResource*`; customize via dedicated pages + domain APIs)

package/skills/nuxt-unified-ui/references/code-style.md

@@ -20,7 +20,7 @@ Write code so a reader can **scan vertically** and see structure before details.
    Object/array literals in script are multi-line with trailing commas — even single-property objects passed to helpers (`toastSuccess`, `ufetch` options, etc.). Compact one-liners hide diffs and force horizontal reading.
 
 4. **Templates are layout, not mini-scripts.**
-   Structural directives live on `<template>` wrappers so the rendered node stays a clean component/element. Attributes wrap predictably; closing `>` / `/>` placement is consistent; interpolations sit on their own line so markup nesting is obvious.
+   Structural directives live on `<template>` wrappers so the rendered node stays a clean component/element. Attributes wrap predictably (`u-modal` stays one line); closing `>` / `/>` placement is consistent; interpolations sit on their own line (static + dynamic text may share one `{{ ... }}` or surrounding text).
 
 5. **Section comments are the map.**
    `/* section */` labels replace scavenger hunts through long `<script setup>` blocks. Imports sit next to the section that needs them, not in a hoisted pile at the top.
@@ -48,11 +48,49 @@ When editing an existing file, **absolute rules below always win**. For choices
 | Component tags | lowercase kebab-case (`u-button`, `un-card`) — never PascalCase |
 | Braces | always for `if` / `else` / `for` / `while` — no brace-less single-liners |
 | `else` / `catch` | on their **own line** after `}` |
+| `.js` / `.ts` file start | **two** blank lines at the top, **unless** the file starts with imports — then **no** blank lines before the first `import` |
 
 ---
 
 ## Vertical whitespace (script / TS)
 
+### File start (`.js` / `.ts` only)
+
+Start of every `.js` and `.ts` file must have **two blank lines**, except if it has imports at the start of the file — then put **no** blank lines before the first import.
+
+```ts
+// ✅ no imports — exactly two blank lines, then code
+
+
+export default defineEventHandler(async event => {
+  ...
+});
+```
+
+```ts
+// ✅ imports at start — import on line 1, no leading blanks
+import { join } from 'node:path';
+
+
+const { schema, type, inferred } = parseSchema({
+  ...
+});
+```
+
+```ts
+// ❌ missing leading blanks when there are no imports
+export default defineEventHandler(async event => {
+  ...
+});
+```
+
+```ts
+// ❌ blank lines before the first import
+import { join } from 'node:path';
+```
+
+Vue SFCs are unchanged: `<script setup>` begins immediately inside the script block (no artificial leading blanks at the top of the `.vue` file).
+
 ### Section rhythm
 
 - **Double blank line** between major boundaries: after `defineProps`/`defineEmits` blocks, between `/* section */` domains, before handler functions, between major async steps.
@@ -300,7 +338,8 @@ Keep tight `v-if` / `v-else` chains adjacent (no blank line between matching bra
 ### Attribute wrapping (hard rule)
 
 - **0–1 attributes:** may stay on one line with the tag
-- **2+ attributes:** one attribute per line (always)
+- **2+ attributes:** one attribute per line — **except `u-modal`**
+- **`u-modal` only:** keep **all** attributes on the **same single line** as the tag (do not wrap), even when there are many
 
 ```vue
 <!-- ✅ 0–1 attributes — inline OK -->
@@ -310,14 +349,12 @@ Keep tight `v-if` / `v-else` chains adjacent (no blank line between matching bra
 </u-form-field>
 <u-icon name="lucide:check" />
 
-<!-- ✅ 2+ attributes — one per line -->
-<u-modal
-  :ui="{ content: 'max-w-5xl' }"
-  scrollable
-  @update:open="!$event && emit('close')">
+<!-- ✅ u-modal — always one line (exception) -->
+<u-modal :ui="{ content: 'max-w-5xl' }" scrollable @update:open="!$event && emit('close')">
   ...
 </u-modal>
 
+<!-- ✅ other components — 2+ attributes, one per line -->
 <u-button
   variant="subtle"
   icon="lucide:refresh-ccw"
@@ -350,11 +387,12 @@ Prefer defaults by **omitting** props rather than restating them:
 
 | Component / context | Default convention |
 |---------------------|--------------------|
-| `u-button` | Prefer `variant="subtle"` over `ghost` for new buttons |
+| `u-button` | Prefer `variant="subtle"` (or omit) for normal actions |
+| Cancel buttons only | Use `variant="ghost"` / `variant: 'ghost'` — **only** for Cancel dismiss actions; do not use `ghost` on other buttons |
 | Async `u-button` clicks | Prefer `loading-auto` over hand-rolled `isLoading` when nothing else depends on that flag |
 | `u-badge` | Always `variant="subtle"`; use `icon` + `:label` (no default slot text); **do not** set `size`; **omit** `color` for neutral (use `undefined` in ternaries, never `color="neutral"`) |
 | `u-tooltip` | Do not set `:delay-duration` — use the default delay |
-| Action objects where subtle is the local default | Omit `variant: 'subtle'` unless overriding |
+| Action objects where subtle is the local default | Omit `variant: 'subtle'` unless overriding; Cancel actions set `variant: 'ghost'` |
 | Icons | Always `lucide:*` prefix |
 
 ```vue
@@ -417,12 +455,24 @@ Closing tags for block components (`</un-card>`, `</u-modal>`, …) always on th
 
 ### Text interpolation
 
-Put `{{ ... }}` on its own line:
+Put `{{ ... }}` on its own line (not glued onto the opening/closing tag). **Static + dynamic text may mix** in the same interpolation or around it — do not force template literals / split words solely to isolate dynamics:
 
 ```vue
 <h1 class="text-2xl font-semibold">
   Login
 </h1>
+
+<!-- ✅ static + dynamic together -->
+<h1 class="text-2xl font-semibold">
+  Welcome, {{ user.name }}!
+</h1>
+
+<h2 class="mt-1">
+  {{ flashCardData?.category?.name }} - by {{ flashCardData?.owner?.name }}
+</h2>
+
+<!-- ❌ glued to tags -->
+<h1 class="text-2xl font-semibold">{{ user.name }}</h1>
 ```
 
 ### Root structure
@@ -521,9 +571,11 @@ Pass handler **references** into action objects / watchers when possible (`onCli
 
 ## Server / plain TS files
 
-Same whitespace, brace, literal, and call-formatting rules as script blocks:
+Same whitespace, brace, literal, and call-formatting rules as script blocks. Honor the **file-start** rule (two leading blanks, or imports flush at line 1). Prefer `async event =>` style consistent with siblings:
 
 ```ts
+
+
 export default defineEventHandler(async event => {
 
   await assertRateLimit({
@@ -557,8 +609,6 @@ export default defineEventHandler(async event => {
 });
 ```
 
-Leading blank line at top of file is fine when the local tree uses it. Prefer `async event =>` style consistent with siblings.
-
 ---
 
 ## Anti-patterns (quick)
@@ -571,14 +621,18 @@ Leading blank line at top of file is fine when the local tree uses it. Prefer `a
 | `if (!x) return;` | braced block |
 | `} else {` | `}\nelse {` |
 | `toastSuccess({ title: 'x' })` one-liner object | multi-line object + trailing comma |
-| 3 attrs on one line | one attr per line |
+| 3 attrs on one line (non-`u-modal`) | one attr per line |
+| Multi-line `u-modal` attrs | keep `u-modal` attrs on one line |
 | `>` on its own line after attrs | `>` after last attr |
-| `{{ x }}` glued to tags | interpolation on its own line |
+| `{{ x }}` glued to tags | interpolation on its own line (static + dynamic mix OK) |
+| `ghost` on non-Cancel buttons | `ghost` only for Cancel |
 | Hoisted import block | imports co-located under section |
 | `computed(() => [ ... ])` | `computed(() => { return [ ... ]; })` |
 | `color="neutral"` on badge | omit `color` / use `undefined` |
 | `ufetch(\n  url,\n  {` | `ufetch(url, {` on one line |
 | One-line `useUFetch(...)` | URL on next line; options multi-line |
+| `.ts`/`.js` with no leading blanks (and no imports) | two blank lines at file start |
+| Blank lines before first `import` | `import` on line 1 |
 
 ---
 
@@ -586,6 +640,7 @@ Leading blank line at top of file is fine when the local tree uses it. Prefer `a
 
 - [ ] `<script setup>` without `lang="ts"`; no TS annotations in Vue
 - [ ] 2-space indent; single quotes; semicolons; trailing commas in multi-line literals
+- [ ] `.js`/`.ts`: two leading blank lines, or imports flush at line 1 (no blanks before first import)
 - [ ] Double blanks between major sections; blank line before `</script>`; two blanks before `<template>`
 - [ ] Non-trivial functions: blank after `{`, double blank between major steps, blank before `}`
 - [ ] Tiny helpers stay tight
@@ -593,9 +648,9 @@ Leading blank line at top of file is fine when the local tree uses it. Prefer `a
 - [ ] Script objects multi-line; template single-key objects may be inline
 - [ ] Kebab-case component tags
 - [ ] `v-if` / `v-for` on `<template>` wrappers
-- [ ] 2+ attributes → one per line; `>` same line as last attr; multi-line self-closing `/>` on own line
-- [ ] Attribute order + default-value omissions respected (`subtle`, no neutral color noise, `loading-auto`)
-- [ ] `{{ }}` on own line
+- [ ] 2+ attributes → one per line (**`u-modal` attrs stay on one line**); `>` same line as last attr; multi-line self-closing `/>` on own line
+- [ ] Attribute order + default-value omissions respected (`subtle`, **Cancel → `ghost` only**, no neutral color noise, `loading-auto`)
+- [ ] `{{ }}` on own line (static + dynamic mix OK)
 - [ ] Section comments + import co-location where the file has sections
 - [ ] `handleXxx` for action handlers; `it` for short callbacks; descriptive loop names
 - [ ] Computeds that return structures use block + `return`

package/skills/nuxt-unified-ui/references/dialogs-impl.md

@@ -27,7 +27,7 @@ Default action row:
 
 1. Submit (merged `submitButton`, label default `$t('common.submit')`)
 2. Spacer
-3. Cancel (ghost, `$t('common.cancel')`)
+3. Cancel (`variant: 'ghost'` only here — `$t('common.cancel')`)
 
 `handleSubmit`:
 

package/skills/nuxt-unified-ui/references/dialogs.md

@@ -153,6 +153,14 @@ Avoid setting `value` on custom buttons unless the await result must distinguish
 
 Action entries support `actionType: 'spacer'` (flex grow) and optional `tooltip`. Buttons use `loading-auto`.
 
+Cancel / dismiss actions use `variant: 'ghost'` (or `variant="ghost"`). Do **not** use `ghost` on primary/submit/other actions — prefer omit / `subtle`.
+
+Hand-rolled dialog shells keep **`u-modal` attributes on one line** (see [code-style.md](code-style.md)):
+
+```vue
+<u-modal :ui="{ content: 'max-w-5xl' }" scrollable @update:open="!$event && emit('close')">
+```
+
 ## Do / don’t
 
 **Do**
@@ -160,9 +168,12 @@ Action entries support `actionType: 'spacer'` (flex grow) and optional `tooltip`
 - Prefer `launchFormPickerDialog` / `launchChoicePickerDialog` over hand-rolled `u-modal` for these flows
 - Handle actions in button / submit `onClick`
 - Keep field lists consistent with `un-form` (`identifier`, not `type`, for element kind)
+- Mark Cancel with `variant: 'ghost'`; keep `u-modal` attrs on one line
 
 **Don’t**
 
 - Call `toast*` without `u-app` / toaster setup
 - Set `value` on choice buttons by default — omit it unless needed
 - Put primary dialog logic only after `await` when `onClick` should own it
+- Use `ghost` on non-Cancel buttons
+- Wrap `u-modal` attributes across multiple lines

package/skills/nuxt-unified-ui/references/resources.md

@@ -0,0 +1,285 @@
+# Unified resources
+
+How CRUD **resources** are declared and consumed in apps built on this stack. Use this whenever adding or customizing a resource end-to-end.
+
+## Mental model
+
+A resource is one Mongo collection + typed schema + optional field meta, registered on a global `app` registry, exposed through a fixed REST file set, and managed in the dashboard via `<resource-manager>`.
+
+| Layer | Role |
+|-------|------|
+| Nitro plugin (`*-resource.ts`) | `parseSchema` → augment `UnifiedAppRegistry` → `app.foo = { dbo: createUnifiedResourceController(...) }` |
+| REST under `server/api/{kebab-plural}/` | Thin handlers calling `handleResource*` |
+| Dashboard | Generic `[resourceName]` page, or a dedicated page wrapping `<resource-manager>` with extra actions |
+
+Naming:
+
+| Context | Shape | Example |
+|---------|-------|---------|
+| Registry / `dbo` / `handleResource*` `resource` | camelCase plural | `flashCards`, `authorizationRoles`, `users` |
+| API folder + URL path | kebab-case plural | `flash-cards`, `authorization-roles`, `users` |
+| Dashboard `resourceName` param | same as API path | `flash-cards` |
+| Permissions (when used) | `admin.{kebab-plural}.{action}` | `admin.users.list`, `admin.flash-cards.create` |
+
+Client helpers (`useResourceName`) derive:
+
+- `resource` → Pascal singular (internal)
+- `resourcePath` → kebab plural (API)
+- `title` / `titlePlural` → display strings
+
+Pass either camelCase or kebab-case into `<resource-manager resource="...">`; path/title conversion is handled for you. Prefer the name that matches the surrounding context (dashboard nav uses kebab; dedicated pages often pass camel like `users`).
+
+---
+
+## 1. Declare in a server plugin
+
+File: `server/plugins/{name}-resource.ts`
+
+Pattern:
+
+1. Two leading blank lines (no imports) **or** imports flush at line 1 — see [code-style.md](code-style.md).
+2. `parseSchema({ ... })` → `{ schema, type, inferred }`.
+3. `declare global { interface UnifiedAppRegistry { ... } }` so `app.resourceName` is typed.
+4. `defineNitroPlugin` assigns `app.resourceName = { dbo: createUnifiedResourceController({ resource, schema, type, meta? }) }`.
+
+Minimal example:
+
+```ts
+
+
+const { schema, type, inferred } = parseSchema({
+  'name': 'string',
+  'username': 'string',
+});
+
+
+declare global {
+  interface UnifiedAppRegistry {
+    users: {
+      dbo: UnifiedResourceController<typeof inferred>
+    };
+  }
+};
+
+
+export default defineNitroPlugin(() => {
+  app.users = {
+    dbo: createUnifiedResourceController({
+      resource: 'users',
+      schema,
+      type,
+    }),
+  };
+});
+```
+
+With relations and UI meta:
+
+```ts
+createUnifiedResourceController({
+  resource: 'flashCards',
+  schema,
+  type,
+  meta: {
+    owner: {
+      resource: 'users',
+    },
+    category: {
+      resource: 'flashCardCategories',
+    },
+    description: {
+      hideInTable: true,
+    },
+    cards: {
+      children: {
+        backText: {
+          longText: true,
+        },
+      },
+    },
+  },
+});
+```
+
+Extra non-dbo fields on the registry entry are allowed (e.g. `app.media.directory` alongside `dbo`).
+
+### Schema DSL (`parseSchema`)
+
+Keys are field names; optional fields use a trailing `?` in the key (`'tags?'`, `'permissions?'`).
+
+Common value shapes:
+
+| Value | Meaning |
+|-------|---------|
+| `'string'`, `'number'`, `'boolean'` | Scalars |
+| `'string[]'` | String array (tags UI) |
+| `'Record<string, string>'` | String map |
+| `[{ ...fields }, '[]']` | Array of nested objects (series UI) |
+
+`createUnifiedResourceController` validates create/update with the compiled ArkType `type`, auto-adds `_id` / `createdAt` / nested `_id`s, and uses `resource` as the Mongo collection name.
+
+### Field `meta` (drives schema API + forms + table)
+
+| Meta | Effect |
+|------|--------|
+| `resource: 'otherResource'` | Relation: populate + form `identifier: 'resource'` (or `media` when target is `media`) |
+| `hidden: true` | Omit from form fields |
+| `hideInTable: true` | Omit from table columns (still in forms unless `hidden`) |
+| `longText: true` | Textarea |
+| `enum: [{ label, value }]` | Select |
+| `labelFormat: '...'` | Date field |
+| `width` | Form field width hint |
+| `children: { ... }` | Nested meta for object-array item fields |
+
+`GET .../schema` returns schema properties merged with this meta; the client maps that into form fields and columns via `useResourceMeta`.
+
+---
+
+## 2. Standard REST routes
+
+For each resource, add the full set under `server/api/{kebab-plural}/`:
+
+| File | Handler | Typical permission suffix |
+|------|---------|---------------------------|
+| `schema.get.ts` | `handleResourceSchema` | `.schema` |
+| `index.get.ts` | `handleResourceList` | `.list` |
+| `index.post.ts` | `handleResourceCreate` | `.create` |
+| `count.get.ts` | `handleResourceCount` | `.count` |
+| `[resourceId].get.ts` | `handleResourceRetrieve` | `.retrieve` |
+| `[resourceId].patch.ts` | `handleResourceUpdate` | `.update` |
+| `[resourceId].delete.ts` | `handleResourceDelete` | `.delete` |
+
+Every file is a thin wrapper:
+
+```ts
+
+
+export default defineEventHandler(async event => {
+  return handleResourceList({
+    resource: 'flashCards',
+    event,
+    permission: 'admin.flash-cards.list',
+  });
+});
+```
+
+Rules:
+
+- `resource` is always the **camelCase registry key**, not the folder name.
+- `permission` is optional; omit when the route is open to any caller that already passed other gates, or when auth is handled elsewhere. Prefer consistent `admin.{kebab}.{action}` when protecting admin CRUD.
+- Do not reimplement list/create/update logic in route files — extend via custom endpoints next to the resource (e.g. `/api/authentication/onboard-user`) when the default CRUD is not enough.
+
+List query helpers (handled inside `handleResourceList` / siblings): `filter`, `select`, `sort`, `skip`, `limit`, `populate`, and `single=xtruex` for a single `find`.
+
+---
+
+## 3. Dashboard: standard declaration
+
+Generic page (one page for all standard resources):
+
+```vue
+<!-- pages/dashboard/resources/[resourceName].vue -->
+definePageMeta({
+  name: 'dashboard.resources.single',
+  layout: 'dashboard',
+  middleware: ['is-authenticated'],
+});
+
+// template
+<resource-manager :resource="resourceName" />
+```
+
+Nav links pass the **kebab API segment**:
+
+```ts
+{
+  label: 'Flash Cards',
+  to: {
+    name: 'dashboard.resources.single',
+    params: {
+      resourceName: 'flash-cards',
+    },
+  },
+},
+```
+
+`<resource-manager>` provides Create / Refresh toolbar actions, table via `<resource-explorer-table>`, and per-row Edit / Delete dialogs wired to `/api/{resourcePath}`.
+
+---
+
+## 4. Dashboard: customize (users pattern)
+
+When default Create/Edit is wrong for the domain, **do not** overload the generic `[resourceName]` page. Add a dedicated page that still uses `<resource-manager>` but supplies extra actions.
+
+Example: `pages/resources/users.vue` (named route, not necessarily under `dashboard/resources/`):
+
+```vue
+definePageMeta({
+  name: 'dashboard.resources.users',
+  layout: 'dashboard',
+  middleware: ['is-authenticated'],
+});
+
+
+const resourceManagerEl = useTemplateRef('resourceManager');
+
+
+// custom handlers → domain APIs (onboard, reset-password, …)
+
+
+<template>
+  <resource-manager
+    ref="resourceManager"
+    resource="users"
+    :actions="[
+      {
+        variant: 'subtle',
+        icon: 'lucide:user-plus',
+        label: 'Onboard User',
+        onClick: handleOnboardUser,
+      },
+    ]"
+    :resource-actions="[
+      {
+        icon: 'lucide:key-round',
+        tooltip: 'Reset Password',
+        onClick: handleResetPassword,
+      },
+    ]"
+  />
+</template>
+```
+
+Customization knobs on `<resource-manager>`:
+
+| Prop | Placement | Merge order |
+|------|-----------|-------------|
+| `actions` | Card toolbar | After default **Create**, before **Refresh** |
+| `resourceActions` | Per-row table actions | Before default **Edit** / **Delete** |
+| `ref` → `refreshResources()` | After custom mutations | Call so the table reloads |
+
+Point nav at the custom named route instead of `dashboard.resources.single`:
+
+```ts
+to: {
+  name: 'dashboard.resources.users',
+},
+```
+
+Custom handlers typically:
+
+1. `launchFormPickerDialog` / `launchChoicePickerDialog` with explicit `fields`
+2. `ufetch` to a **domain** endpoint (not necessarily the generic resource CRUD)
+3. `await resourceManagerEl.value?.refreshResources()`
+4. `toastSuccess` / `toastError`
+
+Keep the standard REST resource routes even when the UI is customized — other tools and the generic schema/list still depend on them.
+
+---
+
+## Checklist: new resource
+
+- [ ] `server/plugins/{name}-resource.ts` — schema, registry, `createUnifiedResourceController`, meta for relations/UI
+- [ ] Full `server/api/{kebab-plural}/` route set with camelCase `resource` (+ permissions if admin)
+- [ ] Dashboard: nav → `dashboard.resources.single` + kebab `resourceName`, **or** dedicated page + `actions` / `resource-actions`
+- [ ] Follow [code-style.md](code-style.md) (including file-start blank lines)