@vc-shell/vc-app-skill 2.0.0-alpha.33 → 2.0.0-alpha.34

package/runtime/knowledge/patterns/form-validation.md

@@ -1,7 +1,6 @@
 # Form Validation Pattern
 
-Reference source: `apps/vendor-portal/src/modules/products/components/ProductDetailsBase.vue`
-Secondary source: `apps/vendor-portal/src/modules/offers/pages/offers-details.vue`
+Generic worked example for form validation in details blades.
 
 ## Overview
 
@@ -18,12 +17,7 @@ Every validated field follows the same three-part contract:
 3. `handleChange` keeps vee-validate in sync on every update
 
 ```vue
-<Field
-  v-slot="{ errorMessage, handleChange, errors }"
-  :model-value="item.name"
-  name="name"
-  rules="required"
->
+<Field v-slot="{ errorMessage, handleChange, errors }" :model-value="item.name" name="name" rules="required">
   <VcInput
     v-model="item.name"
     label="Name"
@@ -46,12 +40,7 @@ The same pattern applies to every vc-shell input. Only the inner component chang
 ### VcSelect
 
 ```vue
-<Field
-  v-slot="{ errorMessage, handleChange, errors }"
-  :model-value="item.categoryId"
-  name="categoryId"
-  rules="required"
->
+<Field v-slot="{ errorMessage, handleChange, errors }" :model-value="item.categoryId" name="categoryId" rules="required">
   <VcSelect
     v-model="item.categoryId"
     label="Category"
@@ -70,12 +59,7 @@ The same pattern applies to every vc-shell input. Only the inner component chang
 ### VcEditor (Rich Text)
 
 ```vue
-<Field
-  v-slot="{ errorMessage, handleChange, errors }"
-  :model-value="item.description"
-  name="description"
-  rules="required"
->
+<Field v-slot="{ errorMessage, handleChange, errors }" :model-value="item.description" name="description" rules="required">
   <VcEditor
     v-model="item.description"
     label="Description"
@@ -90,12 +74,7 @@ The same pattern applies to every vc-shell input. Only the inner component chang
 ### VcTextarea
 
 ```vue
-<Field
-  v-slot="{ errorMessage, handleChange, errors }"
-  :model-value="item.notes"
-  name="notes"
-  rules="required|min:10"
->
+<Field v-slot="{ errorMessage, handleChange, errors }" :model-value="item.notes" name="notes" rules="required|min:10">
   <VcTextarea
     v-model="item.notes"
     label="Notes"
@@ -124,29 +103,29 @@ Rules are composed with `|` (pipe) in the `rules` string.
 
 ### Standard Rules (from @vee-validate/rules)
 
-| Rule | Example | Description |
-|------|---------|-------------|
-| `required` | `"required"` | Must have a value |
-| `email` | `"required\|email"` | Valid email format |
-| `min:N` | `"required\|min:3"` | Minimum string length |
-| `max:N` | `"max:255"` | Maximum string length |
-| `min_value:N` | `"min_value:0"` | Minimum numeric value |
-| `between:N,M` | `"between:1,100"` | Numeric range |
-| `numeric` | `"numeric"` | Digits only |
-| `alpha_dash` | `"alpha_dash"` | Letters, digits, dashes, underscores |
-| `regex:P` | `"regex:^[A-Z]+"` | Custom regex match |
-| `confirmed:F` | `"confirmed:password"` | Must match another field |
-| `url` | `"url"` | Valid URL format |
+| Rule          | Example                | Description                          |
+| ------------- | ---------------------- | ------------------------------------ |
+| `required`    | `"required"`           | Must have a value                    |
+| `email`       | `"required\|email"`    | Valid email format                   |
+| `min:N`       | `"required\|min:3"`    | Minimum string length                |
+| `max:N`       | `"max:255"`            | Maximum string length                |
+| `min_value:N` | `"min_value:0"`        | Minimum numeric value                |
+| `between:N,M` | `"between:1,100"`      | Numeric range                        |
+| `numeric`     | `"numeric"`            | Digits only                          |
+| `alpha_dash`  | `"alpha_dash"`         | Letters, digits, dashes, underscores |
+| `regex:P`     | `"regex:^[A-Z]+"`      | Custom regex match                   |
+| `confirmed:F` | `"confirmed:password"` | Must match another field             |
+| `url`         | `"url"`                | Valid URL format                     |
 
 ### Custom vc-shell Rules
 
-| Rule | Params | Description |
-|------|--------|-------------|
-| `bigint` | -- | Value is a safe integer (`Number.isSafeInteger`) |
-| `mindimensions` | `[width, height]` | Image meets minimum pixel dimensions |
-| `fileWeight` | `[sizeInKB]` | File size under limit (KB) |
-| `before` | `[targetDate]` | Date is before target |
-| `after` | `[targetDate]` | Date is after target |
+| Rule            | Params            | Description                                      |
+| --------------- | ----------------- | ------------------------------------------------ |
+| `bigint`        | --                | Value is a safe integer (`Number.isSafeInteger`) |
+| `mindimensions` | `[width, height]` | Image meets minimum pixel dimensions             |
+| `fileWeight`    | `[sizeInKB]`      | File size under limit (KB)                       |
+| `before`        | `[targetDate]`    | Date is before target                            |
+| `after`         | `[targetDate]`    | Date is after target                             |
 
 ---
 
@@ -197,12 +176,7 @@ When rules depend on reactive state, use a computed or `:rules` binding:
 
 ```vue
 <!-- Conditionally required -->
-<Field
-  :rules="item.trackInventory ? 'required|bigint|min_value:0' : 'bigint|min_value:0'"
-  :model-value="item.quantity"
-  name="quantity"
-  v-slot="{ errorMessage, handleChange, errors }"
->
+<Field :rules="item.trackInventory ? 'required|bigint|min_value:0' : 'bigint|min_value:0'" :model-value="item.quantity" name="quantity" v-slot="{ errorMessage, handleChange, errors }">
   <VcInput
     v-model="item.quantity"
     type="number"
@@ -277,12 +251,7 @@ const endDateRules = computed(() => `required|after:${startDate.value}`);
 ### Password Confirmation
 
 ```vue
-<Field
-  v-slot="{ errorMessage, handleChange, errors }"
-  :model-value="password"
-  name="password"
-  rules="required|min:8"
->
+<Field v-slot="{ errorMessage, handleChange, errors }" :model-value="password" name="password" rules="required|min:8">
   <VcInput
     v-model="password"
     type="password"
@@ -294,12 +263,7 @@ const endDateRules = computed(() => `required|after:${startDate.value}`);
   />
 </Field>
 
-<Field
-  v-slot="{ errorMessage, handleChange, errors }"
-  :model-value="confirmPassword"
-  name="confirmPassword"
-  rules="required|confirmed:password"
->
+<Field v-slot="{ errorMessage, handleChange, errors }" :model-value="confirmPassword" name="confirmPassword" rules="required|confirmed:password">
   <VcInput
     v-model="confirmPassword"
     type="password"

package/runtime/knowledge/patterns/list-blade-pattern.md

@@ -2,7 +2,7 @@
 
 Describes the full structure of a list blade: workspace entry point with `VcBlade` + `VcDataTable`, sort, pagination, toolbar, and child blade navigation.
 
-Source: extracted from `apps/vendor-portal/src/modules/orders/pages/orders-list.vue` and `apps/vendor-portal/src/modules/offers/pages/offers-list.vue`.
+Generic worked example for a typical list blade (search, sort, pagination, row actions).
 
 ---
 
@@ -80,11 +80,13 @@ Source: extracted from `apps/vendor-portal/src/modules/orders/pages/orders-list.
 ```
 
 **CRITICAL: Do NOT use `v-for` to render columns.** Declare each `<VcColumn>` explicitly in the template. This is necessary for:
+
 - Custom `#body` slots (status badges, images, formatted values)
 - Per-column `mobile-role` / `mobile-position` attributes
 - Readability and maintainability
 
 **Key VcDataTable props:**
+
 - `state-key` — unique string key for persisting column widths/order/visibility to localStorage. Use snake_case module name (e.g., `"team_list"`, `"catalog_list"`).
 - `v-model:active-item-id` — highlights the currently open row. Bind to `selectedItemId` ref.
 - `v-model:sort-field` and `v-model:sort-order` — two-way sort binding from `useDataTableSort`.
@@ -97,17 +99,17 @@ Source: extracted from `apps/vendor-portal/src/modules/orders/pages/orders-list.
 
 VcColumn `type` prop determines built-in rendering:
 
-| Type | Renders as | When to use |
-|------|-----------|-------------|
-| *(none)* | Plain text | Default for string fields |
-| `"date-ago"` | Relative time ("2 hours ago") | Dates in list blades — preferred over `"date-time"` |
-| `"date"` | Formatted date | Date-only fields |
-| `"datetime"` | Formatted date+time | When full timestamp needed |
-| `"money"` | Formatted currency | Monetary values (reads `currency` field from row by default) |
-| `"number"` | Formatted number | Numeric fields |
-| `"image"` | Thumbnail | Image URL fields |
-| `"status"` | Status badge area | Status/state fields (use with `#body` slot + `VcStatus`) |
-| `"status-icon"` | Boolean icon | Boolean on/off fields (e.g., `isActive`) |
+| Type            | Renders as                    | When to use                                                  |
+| --------------- | ----------------------------- | ------------------------------------------------------------ |
+| _(none)_        | Plain text                    | Default for string fields                                    |
+| `"date-ago"`    | Relative time ("2 hours ago") | Dates in list blades — preferred over `"date-time"`          |
+| `"date"`        | Formatted date                | Date-only fields                                             |
+| `"datetime"`    | Formatted date+time           | When full timestamp needed                                   |
+| `"money"`       | Formatted currency            | Monetary values (reads `currency` field from row by default) |
+| `"number"`      | Formatted number              | Numeric fields                                               |
+| `"image"`       | Thumbnail                     | Image URL fields                                             |
+| `"status"`      | Status badge area             | Status/state fields (use with `#body` slot + `VcStatus`)     |
+| `"status-icon"` | Boolean icon                  | Boolean on/off fields (e.g., `isActive`)                     |
 
 **CRITICAL:** Use `"date-ago"` (NOT `"date-time"`) for dates in list blades. `"date-time"` is the legacy `ITableColumnsBase` format — VcColumn uses `"datetime"` or `"date-ago"`.
 
@@ -118,12 +120,14 @@ VcColumn `type` prop determines built-in rendering:
 Each VcColumn can specify its position in the mobile card layout:
 
 **`mobile-position`** — where the column appears in the card grid:
+
 - `"top-left"` — primary identifier (name, title)
 - `"top-right"` — secondary value (price, total)
 - `"bottom-left"` — tertiary info (SKU, category)
 - `"bottom-right"` — timestamp or date
 
 **`mobile-role`** — special rendering roles:
+
 - `"image"` — displayed as card thumbnail on the left
 - `"status"` — displayed as status badge at bottom
 - `"title"` — main card title
@@ -136,14 +140,7 @@ Each VcColumn can specify its position in the mobile card layout:
 For fields that represent a status/state (e.g., order status, approval state), use `VcStatus` component in a `#body` slot:
 
 ```vue
-<VcColumn
-  id="status"
-  :title="t('XXX.PAGES.LIST.TABLE.HEADER.STATUS')"
-  :always-visible="true"
-  :sortable="true"
-  type="status"
-  mobile-role="status"
->
+<VcColumn id="status" :title="t('XXX.PAGES.LIST.TABLE.HEADER.STATUS')" :always-visible="true" :sortable="true" type="status" mobile-role="status">
   <template #body="{ data }">
     <VcStatus :variant="statusVariant(data.status)">
       {{ data.status }}
@@ -203,7 +200,7 @@ defineBlade({
   name: "XxxList",
   url: "/xxx",
   isWorkspace: true,
-  permissions: ["xxx:manage"],          // array of permission strings from your UserPermissions enum
+  permissions: ["xxx:manage"], // array of permission strings from your UserPermissions enum
   menuItem: {
     title: "XXX.MENU.TITLE",
     icon: "lucide-<icon>",
@@ -330,43 +327,54 @@ exposeToChildren({ reload });
 ## Key Rules
 
 ### `defineBlade` placement
+
 `defineBlade(...)` is a compiler macro (like `defineProps`). It must be called at the **top level of `<script setup>`**, not inside any function or conditional. The framework registers blade config at module parse time.
 
 ### `useDataTableSort` — three outputs
+
 ```ts
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
   initialField: "createdDate",
   initialDirection: "DESC",
 });
 ```
+
 - `sortField` — reactive ref, two-way bound to `VcDataTable` via `v-model:sort-field`
 - `sortOrder` — reactive ref (`"ASC"` | `"DESC"`), two-way bound via `v-model:sort-order`
 - `sortExpression` — computed string `"field:DIR"` (e.g., `"createdDate:DESC"`), passed to the API
 
 ### Sort watcher pattern
+
 ```ts
 watch(sortExpression, async (value) => {
   await getXxxs({ ...searchQuery.value, sort: value });
 });
 ```
+
 Watch `sortExpression` (not `sortField`/`sortOrder` separately) to trigger a reload whenever sort changes.
 
 ### `exposeToChildren`
+
 ```ts
 exposeToChildren({ reload });
 ```
+
 Call this ONCE at the end of setup. The details blade calls `callParent("reload")` after save/delete, which invokes this `reload` function.
 
 ### Column declaration — explicit, NOT v-for
+
 **CRITICAL:** Always declare each `<VcColumn>` explicitly in the template. Do NOT use `v-for` with a computed array.
 
 Why:
+
 - Allows `#body` slots for custom rendering (VcStatus, images, formatted values)
 - Allows per-column `mobile-role` and `mobile-position` attributes
 - Makes the template self-documenting and easier to customize
 
 ### Column type selection rules
+
 When choosing `type` for each column, apply these rules based on the field's data type from the API:
+
 - **String enum / status field** (field name contains "status", "state") → `type="status"` + `#body` slot with `VcStatus`
 - **Boolean field** (field name starts with "is", "has", "can") → `type="status-icon"`
 - **Date/DateTime field** (field name contains "date", "created", "modified", "updated") → `type="date-ago"` for list blades
@@ -376,7 +384,9 @@ When choosing `type` for each column, apply these rules based on the field's dat
 - **Everything else** → no type (plain text)
 
 ### Mobile layout assignment rules
+
 Assign mobile attributes based on column semantic role:
+
 - **Primary identifier** (name, number, title) → `mobile-position="top-left"`
 - **Image** → `mobile-role="image"` + `:always-visible="true"`
 - **Status** → `mobile-role="status"`
@@ -385,7 +395,9 @@ Assign mobile attributes based on column semantic role:
 - **Date** → `mobile-position="bottom-right"`
 
 ### `state-key` naming
+
 Use snake_case: `"team_list"`, `"catalog_items"`, `"orders_list"`. Must be unique across all modules in the app.
 
 ### List-only blades (no details)
+
 For read-only list blades, omit `onItemClick` and the `addItem` toolbar button. Keep `exposeToChildren({ reload })` only if a parent blade might need to refresh this list.

package/runtime/knowledge/patterns/module-structure.md

@@ -72,6 +72,7 @@ export * from "./composables";
 ```
 
 **Rules:**
+
 - `blades: pages` — passes the pages namespace object (all named exports from `pages/index.ts`)
 - `locales` — passes the locales namespace object
 - Re-export `pages` and `composables` so callers can import blades/composables directly from the module package
@@ -89,6 +90,7 @@ export { default as XxxDetails } from "./xxx-details.vue";
 ```
 
 Real example:
+
 ```ts
 export { default as TeamList } from "./team-list.vue";
 export { default as TeamMemberDetails } from "./team-member-details.vue";
@@ -106,12 +108,14 @@ export { default as useXxx } from "./useXxx";
 ```
 
 Real example:
+
 ```ts
 export { default as useTeamMembers } from "./useTeamMembers";
 export { default as useTeamMember } from "./useTeamMember";
 ```
 
 For list-only modules, only the plural composable is exported:
+
 ```ts
 export { default as useCatalogItems } from "./useCatalogItems";
 ```
@@ -153,6 +157,7 @@ export * from "./composables";
 ```
 
 `notifications/index.ts` barrel:
+
 ```ts
 export { default as XxxCreatedDomainEvent } from "./XxxCreatedDomainEvent.vue";
 ```
@@ -191,10 +196,11 @@ The module assembler registers the new module in the app's module registry, typi
 
 ```ts
 export { default as Orders } from "./orders";
-export { default as Team } from "./team";    // ← added by assembler
+export { default as Team } from "./team"; // ← added by assembler
 ```
 
 The assembler must:
+
 1. Read existing `src/modules/index.ts`
 2. Parse existing exports to avoid duplicates
 3. Append a new named export for the new module

package/runtime/knowledge/patterns/multilanguage-fields.md

@@ -63,6 +63,7 @@ export function useMultilanguage() {
 ```
 
 Key points:
+
 - `currentLocale` and `languages` are module-level refs (shared across blades in the same module).
 - Deduplicate concurrent `getLanguages` calls with a promise guard if multiple blades mount simultaneously.
 - `useLanguages()` from the framework provides `getLocaleByTag` (display name) and `getFlag` (async flag URL).
@@ -75,7 +76,10 @@ Use the blade's `#actions` slot to position the language picker in the toolbar a
 
 ```vue
 <template>
-  <VcBlade :title="bladeTitle" :toolbar-items="bladeToolbar">
+  <VcBlade
+    :title="bladeTitle"
+    :toolbar-items="bladeToolbar"
+  >
     <template #actions>
       <MultilanguageSelector
         v-if="isMultilanguage"
@@ -131,19 +135,9 @@ Guard against undefined with `??` — when a language has no content yet, the fi
 `VcInput` and `VcEditor` both accept `:multilanguage` and `:current-language` props. These add a visual language indicator on the field label.
 
 ```vue
-<VcInput
-  v-model="localizedName"
-  :label="t('MY_MODULE.FIELDS.NAME')"
-  multilanguage
-  :current-language="currentLocale"
-/>
-
-<VcEditor
-  v-model="localizedDescription"
-  :label="t('MY_MODULE.FIELDS.DESCRIPTION')"
-  multilanguage
-  :current-language="currentLocale"
-/>
+<VcInput v-model="localizedName" :label="t('MY_MODULE.FIELDS.NAME')" multilanguage :current-language="currentLocale" />
+
+<VcEditor v-model="localizedDescription" :label="t('MY_MODULE.FIELDS.DESCRIPTION')" multilanguage :current-language="currentLocale" />
 ```
 
 - `multilanguage` (boolean) — enables the language indicator badge on the label.

package/runtime/knowledge/patterns/notification-template.md

@@ -25,7 +25,10 @@ Push notifications are displayed in the notification dropdown. Each notification
     :icon="style.icon"
     :notification="notification"
   >
-    <VcHint v-if="notification.description" class="tw-mb-1">
+    <VcHint
+      v-if="notification.description"
+      class="tw-mb-1"
+    >
       {{ notification.description }}
     </VcHint>
   </NotificationTemplate>
@@ -47,24 +50,24 @@ const style = {
 
 ### `NotificationTemplate` props
 
-| Prop           | Type            | Description                                      |
-|----------------|-----------------|--------------------------------------------------|
-| `title`        | `string`        | Notification title text                          |
+| Prop           | Type                | Description                                      |
+| -------------- | ------------------- | ------------------------------------------------ |
+| `title`        | `string`            | Notification title text                          |
 | `notification` | `IPushNotification` | Full notification object (for timestamp display) |
-| `icon`         | `string`        | Lucide icon name, e.g., `"lucide-check"`         |
-| `color`        | `string`        | CSS color or variable for the icon background    |
+| `icon`         | `string`            | Lucide icon name, e.g., `"lucide-check"`         |
+| `color`        | `string`            | CSS color or variable for the icon background    |
 
 The default slot renders below the title/timestamp row. Use it for additional details.
 
 ### Icon + color conventions
 
-| Event type    | Color                       | Icon                    |
-|---------------|-----------------------------|-------------------------|
-| Created       | `var(--success-400)`        | `lucide-check`          |
-| Updated       | `var(--primary-500)`        | `lucide-pencil`         |
-| Deleted       | `var(--danger-500)`         | `lucide-trash-2`        |
-| Error/Failed  | `var(--danger-500)`         | `lucide-x-circle`       |
-| Processing    | `var(--warning-400)`        | `lucide-loader`         |
+| Event type   | Color                | Icon              |
+| ------------ | -------------------- | ----------------- |
+| Created      | `var(--success-400)` | `lucide-check`    |
+| Updated      | `var(--primary-500)` | `lucide-pencil`   |
+| Deleted      | `var(--danger-500)`  | `lucide-trash-2`  |
+| Error/Failed | `var(--danger-500)`  | `lucide-x-circle` |
+| Processing   | `var(--warning-400)` | `lucide-loader`   |
 
 ---
 
@@ -100,7 +103,10 @@ Full typed template example:
     :icon="style.icon"
     :notification="notification"
   >
-    <VcHint v-if="notification.orderId" class="tw-mb-1">
+    <VcHint
+      v-if="notification.orderId"
+      class="tw-mb-1"
+    >
       Order #{{ notification.orderNumber }}
     </VcHint>
   </NotificationTemplate>
@@ -163,6 +169,7 @@ src/modules/xxx/
 ```
 
 `notifications/index.ts` barrel:
+
 ```ts
 export { default as XxxCreatedDomainEvent } from "./XxxCreatedDomainEvent.vue";
 ```

package/runtime/knowledge/patterns/signalr-notifications.md

@@ -45,18 +45,17 @@ Each notification type can have a custom Vue SFC that controls how it renders in
     :notification="notification"
     @click="onClick"
   >
-    <VcHint v-if="notification.description" class="tw-mb-1">
+    <VcHint
+      v-if="notification.description"
+      class="tw-mb-1"
+    >
       {{ notification.description }}
     </VcHint>
   </NotificationTemplate>
 </template>
 
 <script lang="ts" setup>
-import {
-  NotificationTemplate,
-  useNotificationContext,
-  useBlade,
-} from "@vc-shell/framework";
+import { NotificationTemplate, useNotificationContext, useBlade } from "@vc-shell/framework";
 import type { PushNotification } from "@vc-shell/framework";
 import { computed } from "vue";
 
@@ -68,9 +67,7 @@ interface IOrderShippedNotification extends PushNotification {
 const notificationRef = useNotificationContext<IOrderShippedNotification>();
 const notification = computed(() => notificationRef.value);
 
-const color = computed(() =>
-  notification.value.trackingNumber ? "var(--success-400)" : "var(--primary-500)"
-);
+const color = computed(() => (notification.value.trackingNumber ? "var(--success-400)" : "var(--primary-500)"));
 
 const { openBlade } = useBlade();
 
@@ -82,12 +79,12 @@ async function onClick() {
 
 ### `NotificationTemplate` props
 
-| Prop           | Type               | Description                                    |
-|----------------|--------------------|------------------------------------------------|
-| `title`        | `string`           | Notification title text                        |
-| `notification` | `PushNotification`  | Full notification object (used for timestamp)  |
-| `icon`         | `string`           | Lucide icon name, e.g. `"lucide-truck"`        |
-| `color`        | `string`           | CSS color/variable for the icon circle         |
+| Prop           | Type               | Description                                   |
+| -------------- | ------------------ | --------------------------------------------- |
+| `title`        | `string`           | Notification title text                       |
+| `notification` | `PushNotification` | Full notification object (used for timestamp) |
+| `icon`         | `string`           | Lucide icon name, e.g. `"lucide-truck"`       |
+| `color`        | `string`           | CSS color/variable for the icon circle        |
 
 The default slot renders below the title/timestamp. Use it for description text, progress bars, or action links.
 
@@ -120,13 +117,13 @@ export default defineAppModule({
 
 The `toast` object controls how the notification appears as a popup.
 
-| Property        | Type                                        | Description                                          |
-|-----------------|---------------------------------------------|------------------------------------------------------|
-| `mode`          | `"auto" \| "progress" \| "silent"`          | `auto` = fire-and-forget; `progress` = persistent until complete; `silent` = no toast |
-| `severity`      | `Severity \| (msg) => Severity`             | Static or dynamic: `"info"`, `"warning"`, `"error"`, `"critical"` |
-| `timeout`       | `number`                                    | Override default timeout (ms). Defaults: info=5s, warning=8s, error/critical=persistent |
-| `isComplete`    | `(msg) => boolean`                          | For `"progress"` mode: returns true when the operation finishes |
-| `completedType` | `(msg) => string`                           | For `"progress"` mode: final toast variant (`"success"` or `"error"`) |
+| Property        | Type                               | Description                                                                             |
+| --------------- | ---------------------------------- | --------------------------------------------------------------------------------------- |
+| `mode`          | `"auto" \| "progress" \| "silent"` | `auto` = fire-and-forget; `progress` = persistent until complete; `silent` = no toast   |
+| `severity`      | `Severity \| (msg) => Severity`    | Static or dynamic: `"info"`, `"warning"`, `"error"`, `"critical"`                       |
+| `timeout`       | `number`                           | Override default timeout (ms). Defaults: info=5s, warning=8s, error/critical=persistent |
+| `isComplete`    | `(msg) => boolean`                 | For `"progress"` mode: returns true when the operation finishes                         |
+| `completedType` | `(msg) => string`                  | For `"progress"` mode: final toast variant (`"success"` or `"error"`)                   |
 
 #### Toast mode examples
 
@@ -186,19 +183,19 @@ const { messages, unreadCount, markAsRead } = useBladeNotifications({
 
 **Parameters:**
 
-| Field      | Type                        | Description                                      |
-|------------|-----------------------------|--------------------------------------------------|
-| `types`    | `string[]`                  | Notification type(s) to subscribe to             |
-| `filter`   | `(msg) => boolean`          | Optional: further filter by message fields       |
-| `onMessage`| `(msg) => void`             | Callback fired for each matching notification    |
+| Field       | Type               | Description                                   |
+| ----------- | ------------------ | --------------------------------------------- |
+| `types`     | `string[]`         | Notification type(s) to subscribe to          |
+| `filter`    | `(msg) => boolean` | Optional: further filter by message fields    |
+| `onMessage` | `(msg) => void`    | Callback fired for each matching notification |
 
 **Returns:**
 
-| Field        | Type                      | Description                                    |
-|--------------|---------------------------|------------------------------------------------|
-| `messages`   | `ComputedRef<T[]>`        | Matching unread messages from the realtime queue |
-| `unreadCount`| `ComputedRef<number>`     | Count of matching unread messages               |
-| `markAsRead` | `(msg) => void`           | Mark a specific message as read                 |
+| Field         | Type                  | Description                                      |
+| ------------- | --------------------- | ------------------------------------------------ |
+| `messages`    | `ComputedRef<T[]>`    | Matching unread messages from the realtime queue |
+| `unreadCount` | `ComputedRef<number>` | Count of matching unread messages                |
+| `markAsRead`  | `(msg) => void`       | Mark a specific message as read                  |
 
 ---
 
@@ -215,6 +212,7 @@ src/modules/orders/
 ```
 
 `notifications/index.ts` barrel:
+
 ```ts
 export { default as OrderShippedEvent } from "./OrderShippedEvent.vue";
 ```