nuxt-unified-ui 0.5.0 → 0.5.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-unified-ui",
   "type": "module",
-  "version": "0.5.0",
+  "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

@@ -4,10 +4,13 @@ description: >-
   Single skill for the nuxt-unified-ui Nuxt layer and mandatory Nuxt code style:
   install/extend the layer, required CSS, modules/config, radashi radXxx
   auto-imports, un-form / useForm, launchFormPickerDialog /
-  launchChoicePickerDialog, toast helpers, un-card / un-typography, and the
-  whitespace/formatting/code-shape 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.
+  launchChoicePickerDialog, toast helpers, un-card / un-typography, pages /
+  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
@@ -22,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)
@@ -29,6 +33,9 @@ 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) |
 | Public surface inventory | [references/public-surface.md](references/public-surface.md) |
 | Forms (`useForm` / `un-form`) | [references/forms.md](references/forms.md) |
@@ -49,16 +56,19 @@ 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**; 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)
+- Fetching: `ufetch(url, {` one line; `useUFetch` with URL on next line + `data*Data` / `is*Loading` / `refresh*` → [data-fetching.md](references/data-fetching.md)
 
 ---
 
@@ -132,6 +142,9 @@ From `nuxt.config.ts`: `@vueuse/nuxt`, `@nuxt/ui`, `@nuxtjs/i18n`; `ui.colorMode
 | Page chrome | `un-typography` + `un-card` |
 | Custom field | `registerFormExtraElement` in a plugin |
 | 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
@@ -143,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**
 
@@ -151,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"
@@ -330,18 +367,65 @@ Keep tight `v-if` / `v-else` chains adjacent (no blank line between matching bra
 When wrapping, order attributes as:
 
 1. Refs / identity: `ref`, `id`, `name`
-2. Visual props: `variant`, `color`, `size`, `icon`, static `label`
+2. Component visual props: `variant`, `color`, `size`, `icon`, static `label`
 3. Static presentation: `class`, `style`
 4. Data bindings: `:items`, `:data`, `:placeholder`, `:value`, dynamic `:label`, …
 5. `v-model` / `:model-value` / `v-model:*`
-6. Navigation / state: `to`, `href`, `block`, `disabled`, `loading`, `loading-auto`, `fluid-body`, …
+6. Navigation / state: `to`, `href`, `block`, `disabled`, `loading`, `loading-auto`, `fluid-body`, `scrollable`, …
 7. Events last: `@click`, `@update:*`, …
 
 Practical shortcuts:
 
 - `u-button`: `variant` → `color` → `size` → `icon` → label/value → `block` → `disabled` → `loading-auto` → events
-- `u-input` / `u-select*`: user-facing props → `:loading`/`:disabled` → `:items` → `class` → `v-model` → events
+- `u-input` / `u-select*`: user-facing props (`:placeholder`, `:label`) → transient state (`:loading`, `:disabled`) → data source (`:items`) → `class` → `v-model` → events
+- Action objects (`:actions`, `:append-actions`, table row actions): `vIf` → `color` → `icon` → `label` → `tooltip` → `disabled` → `to` → `onClick`
+- Tab / select item objects: `value` → `icon` → `label`
 
+### Default attribute values (omit noise)
+
+Prefer defaults by **omitting** props rather than restating them:
+
+| Component / context | Default convention |
+|---------------------|--------------------|
+| `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; Cancel actions set `variant: 'ghost'` |
+| Icons | Always `lucide:*` prefix |
+
+```vue
+<!-- ✅ omit neutral color; subtle badge -->
+<u-badge
+  variant="subtle"
+  :label="item.name"
+/>
+
+<!-- ✅ ternary falls back with undefined -->
+<u-badge
+  variant="subtle"
+  :color="item.digital ? 'info' : undefined"
+  :label="item.digital ? 'Digital' : 'Physical'"
+/>
+
+<!-- ❌ restating neutral / wrong variant -->
+<u-badge
+  variant="outline"
+  color="neutral"
+  :label="item.name"
+/>
+```
+
+```vue
+<!-- ✅ async button -->
+<u-button
+  variant="subtle"
+  icon="lucide:trash"
+  loading-auto
+  @click="handleDelete()"
+/>
+```
 ### `>` and `/>` placement
 
 **Non-self-closing**, multi-attribute: `>` on the **same line** as the last attribute:
@@ -371,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
@@ -408,6 +504,38 @@ Refs unwrap automatically — do not write `.value` in template expressions or i
 
 ---
 
+## Pages, routing, and data fetching
+
+These are part of the same “shape” conventions when generating app code:
+
+- Pages / named routes / reactive params → [pages.md](pages.md)
+- `ufetch` / `useUFetch` wrapping, naming, options order → [data-fetching.md](data-fetching.md)
+
+### `useUFetch` wrapping (summary)
+
+```ts
+const { data: ordersData, pending: isOrdersLoading, refresh: refreshOrders } = useUFetch(
+  computed(() => `/api/patients/${patientUid.value}/orders`),
+  {
+    query: {
+      limit: itemsPerPage,
+    },
+  },
+);
+```
+
+- First line: destructure + `= useUFetch(`
+- Next line: URL (string or `computed`)
+- Optional multi-line options object
+- Closing `);` alone on the last line
+- Consecutive `useUFetch` calls: **one** blank line between them
+
+### `ufetch` wrapping (summary)
+
+Keep `ufetch(url, {` on one line — do not break the URL above `{`.
+
+---
+
 ## Light naming (reading shape)
 
 | Context | Convention |
@@ -443,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({
@@ -479,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)
@@ -493,11 +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 |
 
 ---
 
@@ -505,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
@@ -512,9 +648,11 @@ 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 respected
-- [ ] `{{ }}` 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`
+- [ ] Pages: explicit `definePageMeta.name`, reactive route params, named navigation ([pages.md](pages.md))
+- [ ] Fetching: `ufetch` / `useUFetch` wrap styles and destructure names ([data-fetching.md](data-fetching.md))

package/skills/nuxt-unified-ui/references/data-fetching.md

@@ -0,0 +1,196 @@
+# Data fetching (`ufetch` / `useUFetch`)
+
+Prefer host-app unified API helpers (`ufetch`, `useUFetch`) over raw `useFetch` / `useAsyncData` / `$fetch` for app API calls. Formatting rules below are mandatory; wire paths to whatever your app’s API plugin expects (relative paths — do not manually prepend `baseApiUrl`).
+
+Combine with [code-style.md](code-style.md).
+
+## `ufetch` (imperative)
+
+One-off requests (submit, delete, button click):
+
+```ts
+const response = await ufetch(`/api/resources/${id}`, {
+  silent: true,
+  method: 'post',
+  body: {
+    field: value,
+  },
+});
+```
+
+Rules:
+
+- Name the result `response` (not `result`), unless a more specific name is clearer (`loginResponse`)
+- Inline `body` / `query` objects in the options — extract only when large/reused
+- `silent: true` — suppress automatic error toast when handling errors locally
+- `responseType: 'blob'` — file downloads
+
+### Options order
+
+- Mutations: behavior flags (`silent`, `responseType`) → `method` → `body` → `query` / other
+- Reads without `method`/`body`: behavior flags before `query`
+
+### Call wrapping (critical)
+
+Keep `ufetch(url, {` on **one line**. Do not break the URL onto its own line above `{`:
+
+```ts
+// ✅
+const response = await ufetch(`/api/items/${item.uid}/documents`, {
+  silent: true,
+});
+
+// ❌
+const response = await ufetch(
+  `/api/items/${item.uid}/documents`,
+  {
+    silent: true,
+  },
+);
+```
+
+### After mutation
+
+```ts
+const response = await ufetch(url, {
+  method: 'post',
+  body: {
+    field: value,
+  },
+});
+
+
+await refresh();
+
+toastSuccess({
+  title: 'Created successfully.',
+});
+
+formValue.value = '';
+```
+
+Call `refresh()` **before** resetting local form UI state. Put side effects in dialog button `onClick` when the mutation is launched from a picker (see [dialogs.md](dialogs.md)).
+
+### Response guards
+
+Fail-fast after `ufetch`:
+
+1. Special non-success statuses first when relevant
+2. Invalid success → early `return toastError({ ... })`
+3. Success path without deep `else` nesting
+
+Prefer direct access on `response` (`response.status`) over optional chaining when the call is expected to return a body.
+
+---
+
+## `useUFetch` (reactive)
+
+For route/param/reactive-driven lists and detail loads:
+
+```ts
+const { data: ordersData, pending: isOrdersPending, refresh: refreshOrders } = useUFetch(
+  computed(() => `/api/patients/${patientUid.value}/orders`),
+  {
+    query: {
+      page: computed(() => currentPage.value - 1),
+      limit: itemsPerPage,
+      search: searchTerm,
+    },
+  },
+);
+```
+
+### Wrapping style (critical)
+
+Always format as:
+
+1. `const { ... } = useUFetch(` on the first line
+2. URL argument on the next line (string **or** `computed(() => ...)`)
+3. Optional options object as a multi-line second argument
+4. Closing `);` on its own line
+
+```ts
+// ✅ string URL + options
+const { data: mediaData, pending: isMediaPending, refresh: refreshMedia } = useUFetch(
+  '/api/media',
+  {
+    query: {
+      'sort': '_id:-1',
+      'limit': itemsPerPage,
+    },
+  },
+);
+
+// ✅ computed URL only
+const { data: patientData, pending: isPatientPending, refresh: refreshPatient } = useUFetch(
+  computed(() => `/api/patients/${patientUid.value}`),
+);
+
+// ❌ crammed one-liner or URL broken like ufetch's wrong form without the useUFetch indent pattern
+```
+
+### Destructuring names
+
+| Key | Convention | Example |
+|-----|------------|---------|
+| `data` | suffix `Data` | `ordersData`, `flashCardsData` |
+| `pending` | `is` + name + `Pending` | `isOrdersPending` |
+| `refresh` | prefix `refresh` | `refreshOrders` |
+
+### Spacing between consecutive calls
+
+When several `useUFetch` calls sit in the same section, use **one** blank line between them (not two):
+
+```ts
+const { data: mediaData, pending: isMediaPending, refresh: refreshMedia } = useUFetch(
+  '/api/media',
+  {
+    query: {
+      'limit': itemsPerPage,
+    },
+  },
+);
+
+const { data: mediaCountData, refresh: refreshMediaCount } = useUFetch(
+  '/api/media/count',
+);
+```
+
+Major section boundaries elsewhere still use double blanks.
+
+### Conditional fetching
+
+When the request must wait on a prop/id, prefer a reactive gate (e.g. reactive `method` or `enabled`) over one-shot `immediate: !!prop` evaluated only at mount:
+
+```ts
+const { data: itemsData, pending: isItemsPending, refresh: refreshItems } = useUFetch(
+  computed(() => `/api/groups/${props.groupUid}/items`),
+  {
+    method: computed(() => props.groupUid ? 'get' : ''),
+  },
+);
+```
+
+Do **not** use `{ immediate: !!props.groupUid }` when the dependency can appear later.
+
+### Query values
+
+- Refs and computeds are fine inside `query`
+- Keep query object multi-line with trailing commas
+- Quoted keys are fine when matching API conventions (`'filter'`, `'sort'`)
+
+---
+
+## Do / don’t
+
+**Do**
+
+- Use `ufetch` / `useUFetch` for app API traffic
+- Keep `ufetch(url, {` on one line; wrap `useUFetch` with URL on the next line
+- Refresh lists before clearing local form state after mutations
+
+**Don’t**
+
+- Reach for raw `$fetch` / `useFetch` for the same app API
+- Manually prepend `baseApiUrl`
+- Break `useUFetch` destructuring into ad-hoc formatting that hides the URL argument

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/pages.md

@@ -0,0 +1,151 @@
+# Pages and routing
+
+Page shape conventions for Nuxt apps using this stack. Always combine with [code-style.md](code-style.md).
+
+## Page script skeleton
+
+```vue
+<script setup>
+
+/* page */
+
+definePageMeta({
+  name: 'dashboard.patients.single',
+});
+
+useHead({
+  title: $t('patients.single.pageTitle'),
+});
+
+
+const route = useRoute();
+
+const patientUid = computed(() => {
+  return route.params.patientUid;
+});
+
+
+/* data */
+
+const { data: patientData, pending: isPatientLoading, refresh: refreshPatient } = useUFetch(
+  computed(() => `/api/patients/${patientUid.value}`),
+);
+
+
+/* handlers */
+
+async function handleAction() {
+
+  ...
+
+}
+
+</script>
+
+
+<template>
+  <div>
+
+    <h1 class="text-2xl font-semibold">
+      {{ $t('patients.single.title') }}
+    </h1>
+
+    <!-- content -->
+
+  </div>
+</template>
+```
+
+## Script ordering (pages)
+
+1. `/* page */` — `definePageMeta`, then `useHead` (head may move below data when title depends on fetched data)
+2. Route / params (`useRoute`, reactive param computeds)
+3. Domain sections (`/* data */`, forms, etc.) including `useUFetch`
+4. Watchers / lifecycle
+5. Handlers (`handleXxx`)
+
+## `definePageMeta`
+
+- **Always** set an explicit `name`
+- Dot notation: `dashboard.home`, `flash-cards.single`, `authentication.login`
+- `layout: 'empty'` for login / full-bleed auth-style pages only
+- Never use `layout: false`
+
+```ts
+definePageMeta({
+  name: 'authentication.login',
+  layout: 'empty',
+});
+```
+
+## Dynamic routes
+
+- Files: `[patientUid].vue`, `[flashCardSlug]/index.vue`
+- Params: **camelCase** in brackets and when reading `route.params`
+- Keep params **reactive** for async workflows — do not snapshot once into a bare `const`:
+
+```ts
+const route = useRoute();
+
+const flashCardSlug = computed(() => {
+  return route.params.flashCardSlug;
+});
+```
+
+## Navigation
+
+Always prefer **named routes**:
+
+```ts
+await navigateTo({
+  name: 'authentication.account',
+});
+```
+
+```vue
+<nuxt-link
+  :to="{
+    name: 'flash-cards.single',
+    params: {
+      flashCardSlug,
+    },
+  }">
+  ...
+</nuxt-link>
+```
+
+### Navigation in action objects
+
+When an action only navigates, use `to` — not `onClick: () => navigateTo(...)`:
+
+```ts
+{
+  icon: 'lucide:arrow-left',
+  label: 'Back',
+  to: {
+    name: 'orders.single',
+    params: {
+      orderUid,
+    },
+  },
+}
+```
+
+## Page headings
+
+- Primary title: `h1` with `class="text-2xl font-semibold"` (match local siblings if they consistently differ)
+- Subtitle / secondary line: size-based hierarchy (`text-sm` / `text-xs`) — see text-hierarchy rules in [code-style.md](code-style.md)
+
+## Item / tab object property order
+
+For objects in `:items` arrays (tabs, selects, menus):
+
+`value` → `icon` → `label` → other props
+
+```ts
+{
+  value: 'preview',
+  icon: 'lucide:eye',
+  label: $t('section.preview'),
+}
+```

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)