nuxt-unified-ui 0.5.1 → 0.5.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-unified-ui",
   "type": "module",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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.124",
     "@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) |
@@ -46,20 +50,24 @@ This is the **only** installable skill in this repo. Deep topics live under `ref
 
 ## Code style (read [code-style.md](references/code-style.md) before writing code)
 
-**Always apply** to Vue SFCs and app/server `.ts` files. Higher-level idea: code should **scan vertically** — double blanks between major sections, multi-line literals, predictable template wrapping, section comments as a map.
+**Always apply** to Vue SFCs and app/server `.ts` files. Higher-level idea: code should **scan vertically** — named sections, declaration-kind groups, multi-line literals, and predictable template wrapping.
 
 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
-- Double blank lines between major sections; blank line before `</script>`; **two** blanks before `<template>`
+- **`.js` / `.ts` file start:** two leading blank lines, **except** when the file starts with imports — then **no** blank lines before the first `import`
+- Every `<script setup>` section starts with `/* section name */`, then a blank line
+- Within a section, group declarations by kind (imports, refs, computeds, watchers, functions, etc.): two blank lines between groups; no blanks between consecutive refs; one blank between consecutive members of other groups
 - Non-trivial async/functions: blank line after `{`, double blank between major steps, blank before `}`
+- A function dedicated to choosing a return value from multiple criteria uses one exhaustive `if` / `else if` / `else` chain; broader functions may use guard clauses and early returns
 - `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
+- If a condition changes several component attributes, prefer explicit `<template v-if>` / `v-else` component variants over nested ternaries and overly dynamic bindings
+- **2+ attributes → one per line** except structural **`template` wrappers** and **`u-modal`** (keep either 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 +147,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 +159,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 +168,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

@@ -10,20 +10,20 @@ This document is about the **look and shape** of code — whitespace, wrapping,
 
 Write code so a reader can **scan vertically** and see structure before details.
 
-1. **Paragraphs of logic, not walls of text.**
-   Double blank lines mark major boundaries (sections, handlers, big steps). Single blank lines separate related statements inside a section. Tiny one-liner helpers stay tight — do not decorate them with empty lines.
+1. **Sections contain declaration-kind groups.**
+   Start each logical `<script setup>` domain with a `/* section name */` comment and a blank line. Within that section, group imports, refs, computeds, watchers, functions, and other declarations by kind. Double blank lines separate groups; refs stay tightly stacked; consecutive members of other groups have one blank line between them.
 
-2. **Breathing room inside non-trivial blocks.**
-   A non-trivial function/computed is a mini-document: blank line after `{`, full-block guards, double blank between guard/setup and the main sequence, blank line before `}`. That rhythm makes async flows readable without comments.
+2. **Function body spacing follows the work.**
+   A non-trivial workflow function is a mini-document: blank line after `{`, full-block guards, double blanks between major steps, and a blank before `}`. Small helpers and functions whose whole job is choosing a return value stay compact.
 
 3. **One idea per line in structured data.**
    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 one-line `<template>` wrappers so the rendered node stays a clean component/element. Rendered component 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.
+   `/* section */` labels define logical domains, while declaration-kind spacing exposes the structure inside each domain. Imports sit in the section that needs them, not in a hoisted pile at the top.
 
 6. **Names that match role.**
    Handlers read as actions (`handleLogin`), short callbacks use `it`, loops use real nouns. Shape and naming reinforce each other so you rarely need narrating comments.
@@ -48,20 +48,63 @@ 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.
-- **Single blank line** within a section (related consts, consecutive small helpers).
-- Blank line **before and after** each `/* section */` comment.
+- Start every logical `<script setup>` domain with `/* section name */`, followed by a blank line.
+- Within each section, group declarations by kind: imports, props/models, refs, computeds, watchers/lifecycle, functions, and outlets.
+- Use **two blank lines between different declaration groups** within a section.
+- Keep consecutive refs together with **no blank lines**.
+- Use **one blank line between consecutive declarations** in other same-kind groups, including computeds, watchers, and functions.
+- Keep a blank line before each section comment; the preceding group's double-boundary spacing still applies.
 - Blank line before `</script>`.
 - **Two** blank lines between `</script>` and `<template>`.
 
-### Non-trivial functions and computeds
+Declaration-group spacing is independent from spacing inside a function body. Do not add a new section comment merely because the declaration kind changes.
+
+### Non-trivial workflow functions
 
 Applies to async handlers, multi-step loaders, and non-trivial callbacks:
 
@@ -113,6 +156,26 @@ async function handleSubmitSelection(items) {
 
 Same for a `finally` that only flips one flag.
 
+### Return-only decision functions
+
+When a function's whole job is to choose and return a value from multiple criteria, express the complete decision as one compact `if` / `else if` / `else` chain:
+
+```ts
+function getSortLabel(column) {
+  if (sortedColumn.value !== column) {
+    return `Sort ${column} descending`;
+  }
+  else if (sortDirection.value === 'desc') {
+    return `Sort ${column} ascending`;
+  }
+  else {
+    return `Clear ${column} sorting`;
+  }
+}
+```
+
+Use this pattern only when value selection is essentially the function's entire body. Functions that perform broader work may use guard clauses and early returns when those make the workflow clearer; do not force their logic into an exhaustive chain.
+
 ### `else` / `catch`
 
 ```ts
@@ -185,6 +248,33 @@ const response = await ufetch(
 - Single-key object binding may stay inline: `:ui="{ content: 'max-w-7xl' }"`
 - Multi-key template object/array bindings are multi-line
 - Simple scalars and simple ternaries stay inline; break only when branches become objects/arrays or nested structure
+- When one condition changes several attributes, labels/icons, or an object-shaped binding such as `to`, use adjacent `<template v-if>` / `v-else-if` / `v-else` branches with explicit component variants. Prefer small markup duplication over nested ternaries and overly dynamic attributes.
+
+```vue
+<template v-if="state === 'complete'">
+  <u-badge
+    variant="subtle"
+    color="success"
+    icon="lucide:circle-check"
+    label="Completed"
+  />
+</template>
+<template v-else-if="state === 'in-progress'">
+  <u-badge
+    variant="subtle"
+    color="warning"
+    icon="lucide:clock"
+    label="In Progress"
+  />
+</template>
+<template v-else>
+  <u-badge
+    variant="subtle"
+    icon="lucide:circle"
+    label="Not Started"
+  />
+</template>
+```
 
 ---
 
@@ -224,18 +314,49 @@ Group with `/* name */`:
 | domain names | `/* login */`, `/* resource */`, `/* captcha */`, … |
 | `/* outlets */` | `defineExpose` |
 
-Blank line before and after the comment. Avoid comments that only restate obvious option names.
+The comment names a logical domain, not a declaration kind. Follow it with a blank line, then organize that domain into declaration-kind groups. Avoid comments that only restate obvious option names.
+
+```ts
+/* resource */
+
+import ResourceExplorerCell from '~/atoms/resource-explorer-cell.vue';
+
+
+const itemsPerPage = ref(20);
+const currentPage = ref(1);
+const sortedColumn = ref('createdAt');
+const sortDirection = ref('desc');
+
+
+const sort = computed(() => {
+  return `${sortedColumn.value}:${sortDirection.value}`;
+});
+
+const hasResources = computed(() => {
+  return !!resourcesData.value?.length;
+});
+
+
+watchImmediate(resourcePath, refreshResources);
+
+
+function getSortIcon(column) {
+  return sortedColumn.value === column ? 'lucide:arrow-down' : 'lucide:arrow-up-down';
+}
+
+function refreshAll() {
+  refreshResources();
+}
+```
 
 ### Script ordering
 
 **Components / dialogs**
 
-1. `/* interface */`
-2. State refs
-3. Computeds
-4. Watchers / lifecycle
-5. Handlers / async functions
-6. `/* outlets */` / `defineExpose` if needed
+1. `/* interface */` section
+2. Domain sections in reading order
+3. Within each section: imports, refs, computeds, watchers/lifecycle, functions
+4. `/* outlets */` / `defineExpose` section if needed
 
 **Pages**
 
@@ -300,7 +421,9 @@ 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)
+- **Structural `<template>` wrappers:** keep the opening tag on one line, even with several directives, keys, or dynamic slot bindings
+- **2+ attributes on rendered elements/components:** 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 +433,17 @@ 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')">
+<!-- ✅ structural template wrappers stay on one line -->
+<template v-for="column in columns" :key="column.accessorKey" #[column.accessorKey+'-cell']="{ row }">
+  ...
+</template>
+
+<!-- ✅ 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 +476,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 +544,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 +660,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 +698,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 +710,20 @@ 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 (rendered element/component other than `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 [ ... ]; })` |
+| Early-return ladder in a return-only decision function | Compact exhaustive `if` / `else if` / `else` |
+| Multiple nested ternaries across component attributes | Explicit component variants in `<template v-if>` / `v-else` branches |
 | `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,17 +731,21 @@ 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
-- [ ] 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 `}`
+- [ ] `.js`/`.ts`: two leading blank lines, or imports flush at line 1 (no blanks before first import)
+- [ ] Every `<script setup>` section starts with `/* section name */`, followed by a blank line
+- [ ] Declarations are grouped by kind inside each section: two blanks between groups; no blanks between refs; one blank between other same-kind declarations
+- [ ] Non-trivial workflow functions: blank after `{`, double blanks between major steps, blank before `}`
 - [ ] Tiny helpers stay tight
+- [ ] Return-only multi-criteria functions use a compact exhaustive `if` / `else if` / `else`; broader functions may use early returns
 - [ ] `else` / `catch` on new line
 - [ ] 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
-- [ ] Section comments + import co-location where the file has sections
+- [ ] Conditional states that change several attributes use explicit `<template v-if>` component variants, not nested ternaries
+- [ ] Structural `<template>` wrappers stay on one line; rendered elements/components with 2+ attributes wrap one per line (**`u-modal` stays on one line**); closing `>` / `/>` placement is correct
+- [ ] Attribute order + default-value omissions respected (`subtle`, **Cancel → `ghost` only**, no neutral color noise, `loading-auto`)
+- [ ] `{{ }}` on own line (static + dynamic mix OK)
+- [ ] Every section is named; imports are co-located with the section that uses them
 - [ ] `handleXxx` for action handlers; `it` for short callbacks; descriptive loop names
 - [ ] Computeds that return structures use block + `return`
 - [ ] Pages: explicit `definePageMeta.name`, reactive route params, named navigation ([pages.md](pages.md))

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)