@vc-shell/vc-app-skill 2.0.7 → 2.0.8-pr238.047030d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.7",
+  "version": "2.0.8-pr238.047030d",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [

package/runtime/VERSION

@@ -1 +1 @@
-2.0.7
+2.0.8

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 1fb1bd541 on 2026-06-04T07:51:39.317Z
+Synced from framework at commit 26ce8ec97 on 2026-06-11T08:10:44.520Z

package/runtime/knowledge/docs/core/composables/usePlatformLocaleSync/usePlatformLocaleSync.docs.md

@@ -1,34 +0,0 @@
----
-title: usePlatformLocaleSync
-category: composables
-group: user
----
-
-# usePlatformLocaleSync
-
-One-way reactive bridge from the VirtoCommerce platform's locale storage key (`NG_TRANSLATE_LANG_KEY`, set by AngularJS + angular-translate) to the shell's language service.
-
-Call this composable only when the shell runs embedded inside the platform — `useShellBootstrap` invokes it automatically when `options.isEmbedded === true`. In standalone mode the shell owns its own locale via `VC_LANGUAGE_SETTINGS`, and this composable should not be used.
-
-## When to Use
-
-- Never call directly from feature code. This is a framework-internal sync primitive.
-- It is invoked once per `VcApp` mount from `useShellBootstrap`.
-
-## Behaviour
-
-- Reads `localStorage["NG_TRANSLATE_LANG_KEY"]` via VueUse's `useLocalStorage`, which subscribes to `storage` events for cross-tab reactivity.
-- On setup, if the value is non-empty, calls `LanguageService.setLocale(value)`. `setLocale` normalises the value (e.g. `en-US` → `en-us`), falls back to `en` for unsupported locales, updates `vue-i18n`, reconfigures `vee-validate`, and persists to `VC_LANGUAGE_SETTINGS`.
-- On subsequent changes of the platform key, re-applies the value.
-- Skips empty strings (platform clearing the key does not blank the shell locale).
-- Skips values equal to `currentLocale` to avoid redundant re-configuration.
-
-## How It Works
-
-`useLocalStorage("NG_TRANSLATE_LANG_KEY", "")` returns a `Ref<string>` that VueUse keeps in sync with `localStorage` and the DOM `storage` event (which fires in tabs other than the writer). The composable applies the current ref value once synchronously and then registers a `watch` on it; any cross-tab mutation flows through the ref into `setLocale`.
-
-The watcher is bound to the active effect scope (typically `VcApp`'s setup). When `VcApp` unmounts, the watcher stops; `useLocalStorage` cleans up its own `storage` listener.
-
-## Relationship to `VC_LANGUAGE_SETTINGS`
-
-The sync is strictly one-directional. `setLocale` writes to `VC_LANGUAGE_SETTINGS` as a side effect, but this composable never writes to `NG_TRANSLATE_LANG_KEY`. In embedded mode the in-shell `LanguageSelector` is unreachable (it lives inside `UserDropdownButton`, which is hidden when `isEmbedded` is `true`), so there is no competing writer from the shell side.

package/runtime/knowledge/docs/core/notifications/composables/useBladeNotifications.docs.md

@@ -1,184 +0,0 @@
----
-title: useBladeNotifications
-category: composables
-group: notifications
----
-
-# useBladeNotifications
-
-Subscribes a blade to one or more push-notification types from the platform's SignalR stream. The composable returns a reactive list of matching unread messages, an unread count, and a `markAsRead` action. The subscription is bound to the current effect scope, so it disappears the moment the blade closes — no manual unsubscribe.
-
-This is the **Level 2** entry point in the notification system. Level 1 — `defineAppModule({ notifications })` — registers types globally with their toast configuration and is the always-on path. Level 2 layers blade-specific behavior on top of that: refresh a list, update a progress UI, mark a job complete.
-
-## When to use
-
-- A list blade needs to refresh when an entity is created, updated, or deleted elsewhere.
-- A long-running operation has a dedicated blade and the blade should update as `processedCount` / `errorCount` flow in.
-- A blade wants to surface an inline "N new" badge for messages of a specific type.
-- When NOT to use: app-wide toasts already come from the Level 1 module config — the blade does not need to subscribe just to show a toast. Reach for the blade subscription only when you also need to _react_ to the event in code.
-
-## Quick Start
-
-```ts
-import { useBladeNotifications } from "@vc-shell/framework";
-
-useBladeNotifications({
-  types: ["OfferDeletedDomainEvent"],
-  onMessage: () => reload(),
-});
-```
-
-That is the full recipe for "refresh this list when an offer is deleted somewhere in the app." The handler runs once per matching message; the framework cleans up the subscription when the blade unmounts.
-
-## API
-
-### Parameters
-
-```typescript
-interface BladeNotificationOptions<T extends PushNotification = PushNotification> {
-  types: string[];
-  filter?: (msg: T) => boolean;
-  onMessage?: (msg: T) => void;
-}
-```
-
-| Field       | Type                  | Required | Description                                                                                             |
-| ----------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
-| `types`     | `string[]`            | Yes      | Notification types to subscribe to. Must match the `notifyType` field on incoming messages.             |
-| `filter`    | `(msg: T) => boolean` | No       | Narrow the subscription further (for example, only events for the entity this blade is editing).        |
-| `onMessage` | `(msg: T) => void`    | No       | Callback fired once per matching message. Use it to refresh data, mark progress, or update local state. |
-
-### Returns
-
-```typescript
-interface BladeNotificationReturn<T extends PushNotification = PushNotification> {
-  messages: ComputedRef<T[]>;
-  unreadCount: ComputedRef<number>;
-  markAsRead: (msg: T) => void;
-}
-```
-
-| Property      | Type                  | Description                                                                                                             |
-| ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `messages`    | `ComputedRef<T[]>`    | Realtime messages matching `types` and `filter` that are still unread. Updates reactively as new messages arrive.       |
-| `unreadCount` | `ComputedRef<number>` | `messages.value.length`. Bind to a badge.                                                                               |
-| `markAsRead`  | `(msg: T) => void`    | Mark a specific message as read. Removes it from `messages` (and reduces the global unread badge in the bell dropdown). |
-
-## Typed payloads
-
-Notification payloads often extend `PushNotification` with domain fields. Pass the type parameter so `onMessage` and `messages` are typed:
-
-```ts
-import type { PushNotification } from "@vc-shell/framework";
-
-interface ImportPushNotification extends PushNotification {
-  jobId: string;
-  profileId: string;
-  profileName?: string;
-  processedCount: number;
-  errorCount: number;
-  finished: boolean;
-}
-
-const { messages, markAsRead } = useBladeNotifications<ImportPushNotification>({
-  types: ["ImportPushNotification"],
-  onMessage: (message) => {
-    if (message.finished) {
-      reload();
-      markAsRead(message);
-    }
-  },
-});
-```
-
-## Common patterns
-
-### Refresh a list on any matching event
-
-```ts
-useBladeNotifications({
-  types: ["OfferDeletedDomainEvent"],
-  onMessage: () => reload(),
-});
-```
-
-Drop-in for a list blade that needs to stay in sync with deletions happening anywhere in the app.
-
-### Filter to the entity this blade owns
-
-```ts
-useBladeNotifications<ImportPushNotification>({
-  types: ["ImportPushNotification"],
-  onMessage: (message) => {
-    if (message.profileId !== param.value) return; // not our job
-    if (!message.finished) updateProgress(message);
-    else finalizeImport(message);
-  },
-});
-```
-
-Two open import blades will both receive the stream; each one filters by its own `profileId` so they do not step on each other.
-
-### Drive a manual progress toast
-
-When the platform sends progress updates for a long-running job, you may want to render one persistent toast that you update as messages arrive — instead of letting Level 1 spawn a new toast per event.
-
-Set the Level 1 type to `silent` and drive the toast yourself:
-
-```ts title="src/modules/import/index.ts"
-defineAppModule({
-  notifications: {
-    ImportPushNotification: { toast: { mode: "silent" } },
-  },
-  // ...
-});
-```
-
-```ts title="pages/import-process.vue"
-import { useBladeNotifications, notification } from "@vc-shell/framework";
-
-let toastId: string | undefined;
-
-useBladeNotifications<ImportPushNotification>({
-  types: ["ImportPushNotification"],
-  onMessage: (message) => {
-    const content = message.profileName ? `${message.profileName}: ${message.title}` : message.title;
-
-    if (!toastId) {
-      toastId = notification(content, { timeout: false });
-    } else if (!message.finished) {
-      notification.update(toastId, { content });
-    } else {
-      notification.update(toastId, {
-        content,
-        timeout: 5000,
-        type: message.errorCount ? "error" : "success",
-        onClose: () => (toastId = undefined),
-      });
-    }
-  },
-});
-```
-
-The `notification()` helper returns the toast id; `notification.update` mutates it in place. The bell-dropdown history still grows — `silent` only suppresses the auto-toast.
-
-## Lifecycle
-
-`useBladeNotifications` calls `useNotificationStore().subscribe(...)` and registers `onScopeDispose(unsub)` against the current effect scope. Inside a Vue `setup()` (component or `<script setup>`) the scope is the component's; the subscription dies with the component.
-
-If you call the composable from a manually managed `effectScope()`, the cleanup runs when that scope is stopped. Calling it outside any scope is a bug — the subscription would never be released.
-
-## Tips
-
-- **Listen, do not declare.** `useBladeNotifications` does not register the notification type with the framework. Types must already be declared by some module via `defineAppModule({ notifications })`, otherwise nothing reaches `onMessage`.
-- **`messages` shows only unread.** `markAsRead(msg)` removes a message from `messages` (and from the global unread count). The notification stays in history.
-- **One subscription per call.** Calling `useBladeNotifications` multiple times in the same blade creates independent subscriptions. Combine handlers if you only need one.
-- **Type strings are case-sensitive.** The string in `types` must exactly equal the `notifyType` field on incoming messages.
-
-## Related
-
-- [useNotificationStore](./useNotificationStore.md) — direct store access for app-shell features (dropdown, badge).
-- [useNotificationContext](./useNotificationContext.md) — read the current notification inside a custom template.
-- [useBroadcastFilter](./useBroadcastFilter.md) — control which `SendSystemEvents` broadcasts reach the store.
-- [Notifications concept page.](../../concepts/notifications.md)
-- [Notifications plugin reference.](../../plugins/notifications.md)

package/runtime/knowledge/docs/core/notifications/composables/useBroadcastFilter.docs.md

@@ -1,117 +0,0 @@
----
-title: useBroadcastFilter
-category: composables
-group: notifications
----
-
-# useBroadcastFilter
-
-Controls which **broadcast** push notifications reach the store. The platform SignalR hub delivers messages through two channels: `Send` (targeted to a specific user) and `SendSystemEvents` (broadcast to everyone connected). Broadcasts run through the filter installed here; targeted messages are always accepted.
-
-This is the standard mechanism for scoping a multi-tenant app — show a seller only the broadcasts that mention them, hide events from other tenants. Without a filter every broadcast lands in every user's history.
-
-## When to use
-
-- Multi-tenant apps where the same broadcast topic carries events for different tenants (sellers, organizations, departments) and each user should only see their slice.
-- Apps that want to drop noisy `IndexProgressPushNotification` or similar maintenance events for non-admin roles.
-- When NOT to use: filtering targeted notifications. The platform already delivers `Send` messages only to the addressed user; `useBroadcastFilter` does not see them.
-
-## Quick Start
-
-```ts
-import { useBroadcastFilter, useUser } from "@vc-shell/framework";
-import { onMounted } from "vue";
-
-const { user } = useUser();
-const { setBroadcastFilter } = useBroadcastFilter();
-
-onMounted(() => {
-  setBroadcastFilter((msg) => msg.creator === user.value?.userName);
-});
-```
-
-Install the filter once at app bootstrap (or whenever the active user changes). Every incoming broadcast is run through it; messages that return `false` are dropped before they touch history, toasts, or subscribers.
-
-## API
-
-### Returns
-
-```typescript
-interface UseBroadcastFilterReturn {
-  setBroadcastFilter(fn: (msg: PushNotification) => boolean): void;
-  clearBroadcastFilter(): void;
-}
-```
-
-| Method                 | Type                                           | Description                                                                               |
-| ---------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `setBroadcastFilter`   | `((msg: PushNotification) => boolean) => void` | Install the filter. Replaces any previous filter — there is at most one active at a time. |
-| `clearBroadcastFilter` | `() => void`                                   | Remove the filter. All subsequent broadcasts are accepted.                                |
-
-The filter returns `true` to **accept** a message, `false` to **drop** it.
-
-## Common patterns
-
-### Scope by current user
-
-```ts
-onMounted(() => {
-  setBroadcastFilter((msg) => msg.creator === user.value?.userName);
-});
-```
-
-`creator` is the user that originated the event on the platform side. This is the canonical "show me my own broadcasts" filter in multi-tenant back-office apps.
-
-### Scope by tenant id
-
-```ts
-onMounted(() => {
-  setBroadcastFilter((msg) => (msg as TenantPush).sellerId === currentSellerId.value);
-});
-```
-
-When your broadcast payloads carry a tenant id, gate on it instead of `creator`. The cast clarifies typing without expanding `PushNotification` for every caller.
-
-### Re-install on user switch
-
-```ts
-import { watch } from "vue";
-
-watch(
-  () => user.value?.userName,
-  (name) => {
-    if (!name) clearBroadcastFilter();
-    else setBroadcastFilter((msg) => msg.creator === name);
-  },
-  { immediate: true },
-);
-```
-
-If the app supports user switching without a full reload (impersonation, multi-account), re-install the filter on every change. There is only one slot — installing again replaces the previous filter.
-
-### Drop a noisy type entirely
-
-```ts
-setBroadcastFilter((msg) => msg.notifyType !== "IndexProgressPushNotification");
-```
-
-Broadcast-only suppression. To suppress targeted messages too, set `toast: false` or `toast: { mode: "silent" }` on the type's `defineAppModule({ notifications })` config — that controls the toast surface; the history still records the event.
-
-## Behavior
-
-- The filter applies only to messages ingested with the `broadcast: true` flag (the SignalR `SendSystemEvents` channel).
-- Targeted messages (`Send`) bypass the filter entirely.
-- Installing a filter mid-session does not retroactively prune `history` or `realtime`. Past broadcasts stay; only future ones are filtered.
-- The filter is a single function. To compose multiple predicates, `&&` them inside one callback.
-
-## Tips
-
-- **Install once, early.** Setting the filter in `App.vue` `onMounted` (after authentication) is the canonical placement, so messages arriving before the first blade mounts are already scoped.
-- **Filter exceptions go straight to the console.** If your predicate throws, the message is dropped. Wrap the logic if you are reading off potentially missing fields.
-- **Do not query the store from inside the filter.** The store is `useBroadcastFilter`'s parent — calling back into it during ingestion causes re-entrancy.
-
-## Related
-
-- [useNotificationStore](./useNotificationStore.md) — exposes the same set/clear methods plus the rest of the store API.
-- [useBladeNotifications](./useBladeNotifications.md) — blade-scoped subscription that sees broadcasts after filtering.
-- [Notifications concept page — broadcasts.](../../concepts/notifications.md#broadcast-vs-targeted)

package/runtime/knowledge/docs/core/notifications/composables/useNotificationContext.docs.md

@@ -1,150 +0,0 @@
----
-title: useNotificationContext
-category: composables
-group: notifications
----
-
-# useNotificationContext
-
-Reads the current `PushNotification` payload inside a custom notification template. The framework provides the message via Vue's `inject()` from the dropdown or toast surface that hosts the template — the composable returns a reactive `ComputedRef` over it.
-
-This is the one piece you write when a notification type registered with `defineAppModule({ notifications: { Type: { template } } })` needs a richer rendering than the default `NotificationTemplate` chrome — for example, formatting a domain-specific status, deriving a colored accent, or wiring a click handler that opens the relevant blade.
-
-## When to use
-
-- Implementing the `template` component for a notification type registered through `defineAppModule({ notifications })`.
-- Reading typed payload fields (status, entity name, job id) to drive the template's layout, color, or actions.
-- When NOT to use: anywhere outside a notification template. The composable throws if the inject context is not present.
-
-## Quick Start
-
-```vue
-<script lang="ts" setup>
-import { PushNotification, NotificationTemplate, useNotificationContext } from "@vc-shell/framework";
-import { computed } from "vue";
-
-interface IOrderPushNotification extends PushNotification {
-  orderId: string;
-  total: number;
-}
-
-const notificationRef = useNotificationContext<IOrderPushNotification>();
-const notification = computed(() => notificationRef.value);
-</script>
-
-<template>
-  <NotificationTemplate
-    :title="notification.title ?? ''"
-    :notification="notification"
-  >
-    <p>Order {{ notification.orderId }} — ${{ notification.total }}</p>
-  </NotificationTemplate>
-</template>
-```
-
-## API
-
-### Parameters
-
-None. The composable is always called without arguments. Generic type parameter narrows the payload shape:
-
-```typescript
-function useNotificationContext<T extends PushNotification = PushNotification>(): ComputedRef<T>;
-```
-
-### Returns
-
-`ComputedRef<T>` — reactive reference to the current `PushNotification` (or your extended subtype via the generic). Update reactively if the same template instance is reused for a refreshed payload (for example, when a progress message is updated through `notification.update`).
-
-## Common patterns
-
-### Compute display strings from payload fields
-
-```vue
-<script lang="ts" setup>
-import { PushNotification, useNotificationContext, NotificationTemplate } from "@vc-shell/framework";
-import { computed } from "vue";
-import { useI18n } from "vue-i18n";
-
-interface IProductPush extends PushNotification {
-  productName?: string;
-  newStatus?: string;
-}
-
-const ctx = useNotificationContext<IProductPush>();
-const notification = computed(() => ctx.value);
-const { t } = useI18n({ useScope: "global" });
-
-const title = computed(() => (notification.value.productName ? `${t("PRODUCTS.PUSH.PRODUCT")} "${notification.value.productName}" ${t("PRODUCTS.PUSH.UPDATE")}` : (notification.value.title ?? "")));
-</script>
-```
-
-### Open a blade on click
-
-```vue
-<script lang="ts" setup>
-import { useBlade, useNotificationContext, NotificationTemplate } from "@vc-shell/framework";
-import { computed } from "vue";
-
-const { openBlade } = useBlade();
-const ctx = useNotificationContext<IOrderPush>();
-const notification = computed(() => ctx.value);
-
-function onClick() {
-  if (!notification.value.orderId) return;
-  openBlade({ name: "OrderDetails", param: notification.value.orderId });
-}
-</script>
-
-<template>
-  <NotificationTemplate
-    :title="notification.title ?? ''"
-    :notification="notification"
-    @click="onClick"
-  >
-    <p>{{ notification.description }}</p>
-  </NotificationTemplate>
-</template>
-```
-
-`NotificationTemplate` re-emits the click event so the host (dropdown row, toast) can close itself before your handler runs.
-
-### Color the template by status
-
-```ts
-const notificationStyle = computed(() => {
-  switch (notification.value.newStatus) {
-    case "Approved":
-      return { color: "var(--success-400)", icon: "lucide-check-circle" };
-    case "RequestChanges":
-      return { color: "var(--danger-400)", icon: "lucide-alert-circle" };
-    case "WaitForApproval":
-      return { color: "var(--warning-600)", icon: "lucide-clock" };
-    default:
-      return { color: "var(--primary-400)", icon: "lucide-bell" };
-  }
-});
-```
-
-`NotificationTemplate` accepts `:color` and `:icon` props that line up with these computeds — the dropdown row and the toast use the same template, so the styling stays consistent across surfaces.
-
-## Where the template runs
-
-Notification templates render in two places:
-
-- **In the bell dropdown**, as one row in the history list.
-- **As a toast**, when the type's `toast.mode` is `"auto"` or `"progress"` (set the mode to `"silent"` to render only in the dropdown).
-
-The template component must be **the same** in both — register it once on `defineAppModule({ notifications })` and the framework reuses it everywhere.
-
-## Tips
-
-- **Always type the generic.** `useNotificationContext<MyPushType>()` enables autocompletion on payload fields. Without it everything degrades to `PushNotification`.
-- **`computed(() => ctx.value)` is idiomatic** in the example apps because consumers want a regular `Ref` shape to pass into child components and template bindings. Direct access via `ctx.value` is fine too.
-- **Do not subscribe inside a template.** The template renders one message; if you need to react to other notifications, do that in a blade with `useBladeNotifications`.
-
-## Related
-
-- [useBladeNotifications](./useBladeNotifications.md) — subscribe to types inside a blade.
-- [useNotificationStore](./useNotificationStore.md) — access the underlying store.
-- [Notifications concept page.](../../concepts/notifications.md)

package/runtime/knowledge/docs/core/notifications/composables/useNotificationStore.docs.md

@@ -1,113 +0,0 @@
----
-title: useNotificationStore
-category: composables
-group: notifications
----
-
-# useNotificationStore
-
-!!! warning "Advanced — most apps do not need this"
-Reach for [useBladeNotifications](./useBladeNotifications.md), [useBroadcastFilter](./useBroadcastFilter.md), and the `notifications` option on `defineAppModule` first. The bell dropdown, unread badge, and toast pipeline are already wired by the shell. This composable is an **escape hatch** for the small set of cases where those facades do not fit.
-
-Returns the singleton store that backs the framework's notification system. Direct access exposes the full reactive state plus low-level actions: subscribing, ingesting synthetic messages, controlling the broadcast filter, paging history.
-
-## When to use
-
-There are only two cases where this composable belongs in app code:
-
-- **A test or scripted harness** that needs to push synthetic messages through the same pipeline SignalR uses, via `ingest`. Real-time production code never calls `ingest` directly.
-- **A custom shell** that replaces the framework's bell dropdown entirely — typically a module-federation host with its own chrome — and therefore needs to bind to `history`, `unreadCount`, and `markAllAsRead` outside the default surface. Apps that use the standard `VcApp` shell do not need this; the dropdown is already there.
-
-For everything else — reacting in a blade, gating broadcasts, registering types, displaying a toast — use the facades. Direct store mutations can bypass invariants the facades enforce (broadcast filter, scope-aware cleanup, type validation).
-
-## Quick Start
-
-```ts
-import { useNotificationStore } from "@vc-shell/framework";
-
-const store = useNotificationStore();
-
-await store.loadHistory(50);
-```
-
-## API
-
-The store exposes the full reactive state plus actions. The shape is summarized below; the underlying types live in `core/notifications/store.ts` and `core/notifications/types.ts`.
-
-| Member                   | Type                                                   | Description                                                                                                                                                                |
-| ------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `registry`               | `Map<string, NotificationTypeConfig>`                  | Notification types registered through `defineAppModule({ notifications })`.                                                                                                |
-| `history`                | `Ref<PushNotification[]>`                              | Full history (server-loaded plus ingested), newest first.                                                                                                                  |
-| `realtime`               | `Ref<PushNotification[]>`                              | Session-only realtime queue from the SignalR hub. Drives `messages` in `useBladeNotifications`.                                                                            |
-| `unreadCount`            | `ComputedRef<number>`                                  | Count of unread items in `history`. Drives the bell badge.                                                                                                                 |
-| `hasUnread`              | `ComputedRef<boolean>`                                 | Convenience boolean over `unreadCount`.                                                                                                                                    |
-| `registerType(t, cfg)`   | `(string, NotificationTypeConfig) => void`             | Register a type. Called by the framework when `defineAppModule({ notifications })` runs — rarely needed manually.                                                          |
-| `ingest(msg, opts?)`     | `(PushNotification, { broadcast?: boolean }?) => void` | Push a message through the same pipeline SignalR uses. Broadcasts pass through the active broadcast filter.                                                                |
-| `setBroadcastFilter(fn)` | `((PushNotification) => boolean) => void`              | Install a filter for broadcast messages. Prefer [useBroadcastFilter](./useBroadcastFilter.md) — same method.                                                               |
-| `clearBroadcastFilter()` | `() => void`                                           | Remove the broadcast filter.                                                                                                                                               |
-| `markAsRead(msg)`        | `(PushNotification) => void`                           | Mark one message as read. Mirrors to the server.                                                                                                                           |
-| `markAllAsRead()`        | `() => Promise<void>`                                  | Optimistic mark-all with rollback on failure.                                                                                                                              |
-| `loadHistory(take?)`     | `(number?) => Promise<void>`                           | Fetch history from the platform. Default page size is 10. The shell already calls this at bootstrap.                                                                       |
-| `subscribe(opts)`        | `({ types, filter?, handler? }) => () => void`         | Low-level pub/sub. Returns an `unsub` function. Inside blades use [useBladeNotifications](./useBladeNotifications.md) — it wraps this and registers cleanup automatically. |
-| `getByType(type)`        | `(string) => PushNotification[]`                       | Filter `history` by `notifyType`.                                                                                                                                          |
-
-## Escape-hatch patterns
-
-### Manually ingest a message (tests, scripted replay)
-
-```ts
-const store = useNotificationStore();
-
-store.ingest({
-  id: "test-1",
-  notifyType: "OrderCreatedDomainEvent",
-  title: "Test order",
-  isNew: true,
-  created: new Date().toISOString(),
-} as PushNotification);
-```
-
-The ingest pipeline runs the configured toast logic and notifies subscribers exactly like a real SignalR message would, so you can verify the end-to-end behavior of `defineAppModule({ notifications })` + `useBladeNotifications` without a live hub.
-
-`ingest` with `{ broadcast: true }` simulates `SendSystemEvents` and runs the broadcast filter; without it the message is treated as targeted and bypasses the filter.
-
-### Custom shell surface (replace the bell dropdown)
-
-When you are building a shell variant that omits the framework's bell dropdown — for example, a module-federation host that renders its own header — bind to the store directly:
-
-```ts
-import { useNotificationStore } from "@vc-shell/framework";
-import { onMounted } from "vue";
-
-const store = useNotificationStore();
-
-onMounted(() => store.loadHistory(100));
-// Use store.history, store.unreadCount, store.markAllAsRead in your own components.
-```
-
-If you are using `VcApp` (the default shell), do **not** do this — the dropdown is already mounted and binding to the same store, so a second surface duplicates what is already on screen.
-
-## Resolution
-
-`useNotificationStore()` resolves in this order:
-
-1. If called inside a Vue component's `setup` (or `app.runWithContext()`), it uses `inject(NotificationStoreKey)`.
-2. Otherwise it returns a module-level singleton created on first call.
-
-The fallback exists so module-federation remotes and standalone scripts see the same store the host app uses.
-
-## Tips
-
-- **Prefer facades.** Every time you find yourself writing `store.subscribe(...)` inside a blade, you want `useBladeNotifications`. Every time you write `store.setBroadcastFilter(...)`, you want `useBroadcastFilter`. The facades exist to keep cleanup, typing, and invariants in one place.
-- **Do not iterate `realtime` for unread counts inside a blade.** That is what `useBladeNotifications` does correctly. Touching `realtime` directly couples your component to shell internals.
-- **`loadHistory` replaces, then merges.** Calling it again pages in more entries and merges them with the existing history.
-- **`markAllAsRead` is optimistic.** The local state flips immediately; if the server call fails the change is rolled back and an error toast surfaces.
-- **Direct store mutations can bypass invariants.** The broadcast filter only runs through `ingest({ broadcast: true })`. Pushing arrays around `history.value` directly is not supported.
-
-## Related
-
-- [useBladeNotifications](./useBladeNotifications.md) — recommended scope-aware subscription. **Start here.**
-- [useBroadcastFilter](./useBroadcastFilter.md) — broadcast acceptance gate.
-- [useNotificationContext](./useNotificationContext.md) — payload access inside templates.
-- [Notifications concept page.](../../concepts/notifications.md)
-- [Notifications plugin reference.](../../plugins/notifications.md)

package/runtime/knowledge/docs/modules/assets/assets-details.docs.md

@@ -1,123 +0,0 @@
----
-title: Assets Module
-category: reference
-group: modules
-slug: assets
----
-
-# Assets Details Module
-
-A built-in child blade for editing a single asset's metadata: display name, alt text (images only), and description. Opened by `AssetsManager` when the user clicks a table row, but also usable standalone from any parent blade that needs single-asset editing.
-
-## Overview
-
-The blade reads an `AssetLike` instance from `options.asset`, exposes a form pre-populated from it, and delegates persistence back to the caller through two callbacks (`assetEditHandler`, `assetRemoveHandler`). The blade itself never mutates the original asset and never talks to the network — the caller decides what saving and removing means.
-
-The module is registered as `AssetsDetailsModule` and exposes the `AssetsDetails` blade (registered globally under the name `"AssetsDetails"`).
-
-## Module Registration
-
-```typescript
-import { AssetsDetailsModule } from "@vc-shell/framework";
-
-// Registered automatically when the framework loads
-// Exposes: AssetsDetails blade component
-```
-
-## Options (via `useBlade`)
-
-The blade reads its configuration from `options` via `useBlade<AssetsDetailsOptions>()` (not props):
-
-| Option               | Type                                          | Description                                                                                                                                   |
-| -------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `asset`              | `AssetLike`                                   | The asset to edit. The blade clones it into local state — the source object is never mutated until `assetEditHandler` is called.              |
-| `disabled`           | `boolean?`                                    | When true, every input is read-only and the toolbar Save/Delete buttons are disabled.                                                         |
-| `hiddenFields`       | `string[]?`                                   | Field names to hide. Supported values: `"name"`, `"altText"`, `"description"`. The header (preview, size, created date, URL) is always shown. |
-| `assetEditHandler`   | `(asset: AssetLike) => void \| Promise<void>` | Called by the toolbar Save button with the edited copy. The blade closes itself after the handler resolves.                                   |
-| `assetRemoveHandler` | `(asset: AssetLike) => Promise<void>`         | Called by the toolbar Delete button. The blade closes itself after the handler resolves.                                                      |
-
-## Usage
-
-### Direct invocation
-
-```typescript
-import { useBlade } from "@vc-shell/framework";
-
-const { openBlade } = useBlade();
-
-openBlade({
-  name: "AssetsDetails",
-  options: {
-    asset: selectedAsset,
-    disabled: !canEdit.value,
-    hiddenFields: ["altText"],
-    assetEditHandler: async (edited) => {
-      await api.updateAsset(edited);
-    },
-    assetRemoveHandler: async (asset) => {
-      await api.deleteAsset(asset.id);
-    },
-  },
-});
-```
-
-### Used by AssetsManager
-
-When `AssetsManager` opens this blade on row click, it wires the manager's mutation methods into the handlers automatically:
-
-```typescript
-// inside AssetsManager
-openBlade({
-  name: "AssetsDetails",
-  options: {
-    asset,
-    disabled: readonly.value,
-    hiddenFields: options.value?.hiddenFields,
-    assetEditHandler: (asset) => manager.updateItem(asset),
-    assetRemoveHandler: (asset) => manager.remove(asset),
-  },
-});
-```
-
-## Header
-
-The header is always rendered above the editable form and is not configurable through `hiddenFields`:
-
-| Element      | Source                                                                                             |
-| ------------ | -------------------------------------------------------------------------------------------------- |
-| Preview      | `VcImage` thumbnail for image extensions (png/jpg/jpeg/svg/gif), colored extension badge otherwise |
-| Size         | `readableSize(asset.size)` — formatted as `KB`/`MB`/`GB`                                           |
-| Created date | `asset.createdDate` rendered with `type="date-ago"`                                                |
-| URL          | `asset.url` displayed as a copyable link with `asset.name` as the visible label                    |
-
-## Form fields
-
-All fields are bound to a local clone of `asset`. They can be hidden individually via `hiddenFields`.
-
-| Field         | Visibility                                        | Notes                                                                                                                          |
-| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `name`        | Hidden if `hiddenFields` includes `"name"`        | Required. Edits the **base name only** — the original extension is preserved on save (e.g. editing `report.pdf` keeps `.pdf`). |
-| `altText`     | Image assets only; hide via `"altText"`           | Plain string. Shown only when `asset.typeId === "Image"`.                                                                      |
-| `description` | Hidden if `hiddenFields` includes `"description"` | Multiline textarea.                                                                                                            |
-
-## Toolbar
-
-| Button | Disabled condition                                                                                                  | Action                                                      |
-| ------ | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| Save   | `disabled === true`, the form is invalid, or the form is not dirty (vee-validate `useIsFormValid`/`useIsFormDirty`) | `await assetEditHandler(editedAsset)`, then `closeSelf()`   |
-| Delete | `disabled === true`                                                                                                 | `await assetRemoveHandler(editedAsset)`, then `closeSelf()` |
-
-## Tips
-
-- **Extension is locked.** The `name` input only edits the base name; the original extension is reattached on save. Renaming `photo.png` to `cover` produces `cover.png`.
-- **Required name validation** uses vee-validate's `required` rule. The Save button stays disabled until validation passes.
-- **`assetEditHandler`** is invoked with the edited clone — the original `options.asset` reference is never mutated. Callers should treat the argument as the new state.
-- **`disabled` makes the blade fully read-only:** inputs are disabled and toolbar Save/Delete are disabled regardless of dirtiness.
-- **`hiddenFields` does not enforce required-ness.** Hiding `"name"` skips the validated `<Field>`, so the Save button only depends on form dirtiness.
-
-## Related
-
-- `framework/modules/assets-manager/` -- parent `AssetsManager` blade that opens `AssetsDetails` on row click
-- `framework/core/composables/useAssetsManager/` -- `AssetLike` type definition
-- `framework/core/utilities/assets.ts` -- `isImage`, `readableSize`, `getExtensionColor`, `getExtensionLabel`
-- `framework/ui/components/molecules/vc-field/` -- `VcField` used by the header for size/date/url

package/runtime/knowledge/docs/shell/dashboard/draggable-dashboard/dashboard-widget-skeleton.docs.md

@@ -1,33 +0,0 @@
----
-title: DashboardWidgetSkeleton
-category: composables
-group: utilities
-internal: true
----
-
-# DashboardWidgetSkeleton
-
-Internal placeholder card used by `GridstackDashboard` while remote modules are still loading. Mimics the shape of `DashboardWidgetCard` (header with icon + title, stats row, content lines) with a shimmer animation. Not exported from `@vc-shell/framework` — consumed only inside the dashboard organism.
-
-## When to Use
-
-- You won't use this directly. `GridstackDashboard` renders one per `SkeletonItem` while `ModulesReadyKey` resolves to `false`.
-- If you build a custom dashboard layout and want the same loading aesthetic, copy this file rather than importing it — the component is intentionally internal so the dashboard team can change its markup at any time.
-
-## Layout Contract
-
-The skeleton has no props. Its parent positions it via inline `style` (`grid-column` / `grid-row`) inside a 12-column CSS grid. Card height/width is fully determined by the grid cell it occupies, so the skeleton stretches to fill its slot.
-
-## Accessibility
-
-- The wrapper has `aria-hidden="true"` so screen readers ignore the visual placeholders. The parent grid carries `role="status"` + `aria-busy="true"` to announce loading state once.
-- Shimmer animation is disabled when the user prefers reduced motion.
-
-## Design Tokens
-
-Skeleton inherits dashboard card tokens where possible (`--dashboard-widget-card-background`, `--dashboard-widget-card-border-color`, `--dashboard-widget-card-border-radius`, `--dashboard-widget-card-shadow`) so its silhouette matches the real card. Shimmer colors are read from `--neutrals-100` / `--neutrals-200`.
-
-## Related
-
-- [DraggableDashboard](./draggable-dashboard.docs.md) — owns the skeleton grid and decides when to render placeholders.
-- [DashboardWidgetCard](../dashboard-widget-card/dashboard-widget-card.docs.md) — the real card whose shape skeletons imitate.