@vc-shell/vc-app-skill 2.1.0-pr255.4dc5c0d → 2.1.0-pr256.0fe3abb

package/runtime/knowledge/docs/shell/_internal/popup/common/popup-common.docs.md

@@ -19,18 +19,18 @@ These components provide ready-to-use modal dialogs for common scenarios. Each v
 
 The foundation component. Wraps `VcPopup` and adds footer action buttons based on the `mode`.
 
-| Prop                 | Type                         | Default         | Description                                                    |
-| -------------------- | ---------------------------- | --------------- | -------------------------------------------------------------- |
-| `title`              | `string`                     | --              | Dialog title                                                   |
-| `variant`            | `PopupVariant`               | `"default"`     | Visual style: `"default"`, `"warning"`, `"error"`, `"info"`    |
-| `mode`               | `"acknowledge" \| "confirm"` | `"acknowledge"` | `acknowledge` = single OK button; `confirm` = Confirm + Cancel |
-| `actionLabel`        | `string`                     | `""`            | Label for the single button in acknowledge mode                |
-| `confirmLabel`       | `string`                     | `""`            | Label for the confirm button                                   |
-| `cancelLabel`        | `string`                     | `""`            | Label for the cancel button                                    |
-| `confirmAsText`      | `boolean`                    | `false`         | Render confirm button as text-only style                       |
-| `closable`           | `boolean`                    | `true`          | Show close (X) button in the header                            |
-| `isMobileFullscreen` | `boolean`                    | `true`          | Expand to fullscreen on mobile                                 |
-| `closeOnConfirm`     | `boolean`                    | `false`         | Auto-close the popup after confirm is emitted                  |
+| Prop                 | Type                         | Default         | Description                                                              |
+| -------------------- | ---------------------------- | --------------- | ------------------------------------------------------------------------ |
+| `title`              | `string`                     | --              | Dialog title                                                             |
+| `variant`            | `PopupVariant`               | `"default"`     | Visual style: `"default"`, `"warning"`, `"error"`, `"success"`, `"info"` |
+| `mode`               | `"acknowledge" \| "confirm"` | `"acknowledge"` | `acknowledge` = single OK button; `confirm` = Confirm + Cancel           |
+| `actionLabel`        | `string`                     | `""`            | Label for the single button in acknowledge mode                          |
+| `confirmLabel`       | `string`                     | `""`            | Label for the confirm button                                             |
+| `cancelLabel`        | `string`                     | `""`            | Label for the cancel button                                              |
+| `confirmAsText`      | `boolean`                    | `false`         | Render confirm button as text-only style                                 |
+| `closable`           | `boolean`                    | `true`          | Show close (X) button in the header                                      |
+| `isMobileFullscreen` | `boolean`                    | `true`          | Expand to fullscreen on mobile                                           |
+| `closeOnConfirm`     | `boolean`                    | `false`         | Auto-close the popup after confirm is emitted                            |
 
 Events: `close`, `confirm`
 
@@ -118,6 +118,14 @@ Slots: `header`, `default`
 - All popups are fullscreen on mobile by default. Set `isMobileFullscreen="false"` to keep the centered dialog style.
 - Button labels default to i18n keys: `COMPONENTS.ORGANISMS.VC_POPUP.CONFIRM`, `.CANCEL`, `.OK`.
 
+## CSS Variables
+
+| Variable                     | Default                | Description               |
+| ---------------------------- | ---------------------- | ------------------------- |
+| `--popup-base-confirm-color` | `var(--secondary-700)` | Confirm-button text color |
+
+The deprecated `--confirm-button-color` alias is still honored as a fallback: `--popup-base-confirm-color: var(--confirm-button-color, var(--secondary-700))`. Prefer `--popup-base-confirm-color`.
+
 ## Related
 
 - `framework/ui/components/organisms/vc-popup/` -- the underlying `VcPopup` organism

package/runtime/knowledge/docs/shell/auth/ChangePasswordPage/change-password-page.docs.md

@@ -19,12 +19,12 @@ Change password page with current, new, and confirm password fields. Supports a
 
 ```vue
 <template>
-  <ChangePassword />
+  <ChangePasswordPage />
 </template>
 
 <!-- Forced mode (expired password) -->
 <template>
-  <ChangePassword forced />
+  <ChangePasswordPage forced />
 </template>
 ```
 
@@ -32,7 +32,7 @@ With custom branding:
 
 ```vue
 <template>
-  <ChangePassword
+  <ChangePasswordPage
     forced
     logo="/assets/my-company-logo.svg"
     background="/assets/custom-background.jpg"
@@ -42,24 +42,24 @@ With custom branding:
 
 ## Key Props
 
-| Prop         | Type      | Default | Description                                          |
-| ------------ | --------- | ------- | ---------------------------------------------------- |
-| `forced`     | `boolean` | `false` | Show expired-password info banner and adjusted title |
-| `logo`       | `string`  | -       | Override logo image URL                              |
-| `background` | `string`  | -       | Custom background image URL                          |
+| Prop         | Type      | Default | Description                                                                  |
+| ------------ | --------- | ------- | ---------------------------------------------------------------------------- |
+| `forced`     | `boolean` | `false` | Show expired-password info banner and adjusted title                         |
+| `logo`       | `string`  | -       | Fallback logo image URL (used when the platform UI-settings logo is not set) |
+| `background` | `string`  | -       | Custom background image URL                                                  |
 
 ## Recipe: Router Configuration with Forced Mode
 
 Set up the route so the login page can redirect here when the password is expired:
 
 ```ts
-import ChangePassword from "@vc-shell/framework/shared/pages/ChangePasswordPage";
+import { ChangePasswordPage } from "@vc-shell/framework";
 
 const routes = [
   {
     path: "/change-password",
     name: "ChangePassword",
-    component: ChangePassword,
+    component: ChangePasswordPage,
     props: (route) => ({
       forced: route.query.forced === "true",
     }),

package/runtime/knowledge/docs/shell/auth/ForgotPasswordPage/forgot-password-page.docs.md

@@ -38,11 +38,11 @@ With custom branding:
 
 ## Key Props
 
-| Prop         | Type                       | Default | Description                                        |
-| ------------ | -------------------------- | ------- | -------------------------------------------------- |
-| `logo`       | `string`                   | -       | Override logo image URL                            |
-| `background` | `string`                   | -       | Custom background image URL                        |
-| `composable` | `() => { forgotPassword }` | -       | Custom composable providing `forgotPassword(args)` |
+| Prop         | Type                       | Default | Description                                                                  |
+| ------------ | -------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `logo`       | `string`                   | -       | Fallback logo image URL (used when the platform UI-settings logo is not set) |
+| `background` | `string`                   | -       | Custom background image URL                                                  |
+| `composable` | `() => { forgotPassword }` | -       | Custom composable providing `forgotPassword(args)`                           |
 
 ## Recipe: Custom Reset Flow with a Different API
 
@@ -73,7 +73,7 @@ export function useCustomPasswordReset() {
 Register the page in your application router:
 
 ```ts
-import ForgotPassword from "@vc-shell/framework/shared/pages/ForgotPasswordPage";
+import { ForgotPassword } from "@vc-shell/framework";
 
 const routes = [
   {

package/runtime/knowledge/docs/shell/auth/InvitePage/invite-page.docs.md

@@ -56,7 +56,7 @@ With custom branding:
 Set up the route to extract query parameters from the invitation email link:
 
 ```ts
-import Invite from "@vc-shell/framework/shared/pages/InvitePage";
+import { Invite } from "@vc-shell/framework";
 
 const routes = [
   {
@@ -79,13 +79,13 @@ The invitation email link typically looks like:
 https://your-app.com/invite?userId=abc123&userName=jane@example.com&token=xyz789...
 ```
 
-## Recipe: Custom Invitation Flow
+## Recipe: Custom Branding
 
-If your platform uses a different invitation API, you can create a wrapper that overrides the default behavior:
+Wrap `Invite` to pass a custom logo while keeping the standard invitation flow (token validation, password set, and auto sign-in are handled internally):
 
 ```vue
 <script setup lang="ts">
-import Invite from "@vc-shell/framework/shared/pages/InvitePage";
+import { Invite } from "@vc-shell/framework";
 import { useRoute } from "vue-router";
 
 const route = useRoute();

package/runtime/knowledge/docs/shell/auth/LoginPage/login-page.docs.md

@@ -41,18 +41,18 @@ SSO-only mode:
 
 ## Key Props
 
-| Prop         | Type      | Default               | Description                                    |
-| ------------ | --------- | --------------------- | ---------------------------------------------- |
-| `logo`       | `string`  | -                     | Override logo image URL                        |
-| `background` | `string`  | -                     | Custom background image URL                    |
-| `title`      | `string`  | i18n `LOGIN.TITLE`    | Page heading text                              |
-| `subtitle`   | `string`  | i18n `LOGIN.SUBTITLE` | Page subheading text                           |
-| `ssoOnly`    | `boolean` | `false`               | Hide credentials form, show only SSO providers |
+| Prop         | Type      | Default               | Description                                                                  |
+| ------------ | --------- | --------------------- | ---------------------------------------------------------------------------- |
+| `logo`       | `string`  | -                     | Fallback logo image URL (used when the platform UI-settings logo is not set) |
+| `background` | `string`  | -                     | Custom background image URL                                                  |
+| `title`      | `string`  | i18n `LOGIN.TITLE`    | Page heading text                                                            |
+| `subtitle`   | `string`  | i18n `LOGIN.SUBTITLE` | Page subheading text                                                         |
+| `ssoOnly`    | `boolean` | `false`               | Hide credentials form, show only SSO providers                               |
 
 ## Recipe: Router Configuration
 
 ```ts
-import Login from "@vc-shell/framework/shared/pages/LoginPage";
+import { Login } from "@vc-shell/framework";
 
 const routes = [
   {
@@ -73,7 +73,7 @@ const routes = [
 
 ```vue
 <script setup lang="ts">
-import Login from "@vc-shell/framework/shared/pages/LoginPage";
+import { Login } from "@vc-shell/framework";
 </script>
 
 <template>
@@ -94,11 +94,13 @@ The login page supports the `auth:after-form` extension point, allowing modules
 
 ```ts
 // In your module setup
-import { useExtensions } from "@vc-shell/framework";
+import { markRaw } from "vue";
+import { useExtensionPoint } from "@vc-shell/framework";
 
-const extensions = useExtensions();
+const { add } = useExtensionPoint("auth:after-form");
 
-extensions.register("auth:after-form", {
+add({
+  id: "auth-footer",
   component: markRaw(CustomAuthFooter),
   props: { message: "By signing in, you agree to our Terms of Service." },
 });
@@ -109,7 +111,7 @@ extensions.register("auth:after-form", {
 - **Auto-detects SSO providers**: Calls `useExternalProvider().getProviders()` on mount and renders provider buttons only when providers are available
 - **Expired password redirect**: Redirects to the `ChangePassword` route when `user.passwordExpired` is `true` after successful credential authentication
 - **Extension point support**: The `auth:after-form` extension point allows plugins to inject content below the form (terms of service, help links, etc.)
-- **Inline error messages**: Displays error messages for invalid credentials, locked accounts, and server errors directly in the form
+- **Inline error messages**: Displays error messages for invalid credentials and generic authentication errors directly in the form
 - **Forgot password link**: Navigates to the `ForgotPassword` route
 
 ## Details
@@ -117,7 +119,7 @@ extensions.register("auth:after-form", {
 - **Auth layout**: Renders inside `VcAuthLayout`, which provides the centered card design with the logo at the top and the background image filling the page.
 - **Public route**: This page must be accessible without authentication. The route should have `meta: { public: true }` or be excluded from authentication guards.
 - **SSO auto-detection**: The page fetches available providers asynchronously. If the API call fails or returns an empty list, only the credentials form is shown.
-- **Password expiry flow**: After successful login, if the API response indicates `passwordExpired`, the page redirects to `/change-password?forced=true` instead of the main application.
+- **Password expiry flow**: After successful login, if the API response indicates `passwordExpired`, the page redirects to the `ChangePassword` route (`router.push({ name: "ChangePassword" })`) instead of the main application. No `forced` query param is passed; wire that separately via route props if you need it.
 - **Remember me**: The page does not include a "remember me" checkbox. Session persistence is managed by the platform's token expiration settings.
 
 ## Tips

package/runtime/knowledge/docs/shell/auth/ResetPasswordPage/reset-password-page.docs.md

@@ -56,7 +56,7 @@ With custom branding:
 Set up the route to extract query parameters from the password reset email link:
 
 ```ts
-import ResetPassword from "@vc-shell/framework/shared/pages/ResetPasswordPage";
+import { ResetPassword } from "@vc-shell/framework";
 
 const routes = [
   {

package/runtime/knowledge/docs/shell/auth/sign-in/sign-in.docs.md

@@ -34,7 +34,7 @@ const { getProviders } = useExternalProvider();
 const providers = ref([]);
 
 onMounted(async () => {
-  providers.value = await getProviders();
+  providers.value = (await getProviders()) ?? [];
 });
 </script>
 ```
@@ -47,26 +47,27 @@ onMounted(async () => {
 
 ## API (`useExternalProvider`)
 
-| Method         | Signature                                       | Description                                             |
-| -------------- | ----------------------------------------------- | ------------------------------------------------------- |
-| `getProviders` | `() => Promise<ExternalSignInProviderInfo[]>`   | Fetch available SSO providers from the platform API     |
-| `signIn`       | `(authenticationType: string) => Promise<void>` | Redirect to external provider login                     |
-| `signOut`      | `(authenticationType: string) => Promise<void>` | Redirect to external provider logout                    |
-| `storage`      | `Ref<{ providerType?: string }>`                | Persisted localStorage ref tracking the active provider |
+| Method         | Signature                                                  | Description                                                                            |
+| -------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `getProviders` | `() => Promise<ExternalSignInProviderInfo[] \| undefined>` | Fetch available SSO providers from the platform API (returns `undefined` on API error) |
+| `signIn`       | `(authenticationType?: string) => Promise<void>`           | Redirect to external provider login (throws if `authenticationType` is missing)        |
+| `signOut`      | `(authenticationType: string) => Promise<void>`            | Redirect to external provider logout                                                   |
+| `storage`      | `Ref<{ providerType?: string }>`                           | Persisted localStorage ref tracking the active provider                                |
 
 ## Recipe: Custom Login Page with SSO and Credentials
 
 ```vue
 <script setup lang="ts">
-import { ref, onMounted } from "vue";
+import { ref, computed, onMounted } from "vue";
 import { ExternalProviders, useExternalProvider } from "@vc-shell/framework";
+import type { ExternalSignInProviderInfo } from "@vc-shell/framework";
 
 const { getProviders } = useExternalProvider();
 const providers = ref<ExternalSignInProviderInfo[]>([]);
 const hasProviders = computed(() => providers.value.length > 0);
 
 onMounted(async () => {
-  providers.value = await getProviders();
+  providers.value = (await getProviders()) ?? [];
 });
 </script>
 
@@ -127,7 +128,7 @@ This hides the username/password form and shows only the external provider butto
 
 ## Tips
 
-- If no external providers are configured on the platform, `getProviders()` returns an empty array and the `ExternalProviders` component renders nothing.
+- `getProviders()` returns `undefined` on API error (and whatever the API yields otherwise); the examples fall back to `[]`. When there are no providers, the `ExternalProviders` component renders nothing.
 - The `storage.providerType` value is set automatically during sign-in and used by the `LogoutButton` to trigger the correct provider sign-out.
 - For development, you can test SSO flows by configuring a local identity provider (like Keycloak) in the platform's authentication settings.
 
@@ -135,4 +136,4 @@ This hides the username/password form and shows only the external provider butto
 
 - **LoginPage** - The primary consumer that renders `ExternalProviders`
 - **VcAuthLayout** - The layout wrapper used by login and other auth pages
-- **LogoutButton** - Uses `useExternalProvider().signOut()` for SSO logout
+- **LogoutButton** - Calls `useUserManagement().signOut()`, which internally delegates to `useExternalProvider().signOut()` when `storage.providerType` is set (SSO session)

package/runtime/knowledge/docs/shell/components/change-password/change-password.docs.md

@@ -47,7 +47,7 @@ The `ChangePassword` component renders a `VcPopup` with three validated input fi
 - Field-level: `required` and `min:6` rules via vee-validate's `Field` component.
 - API-level: `validatePassword()` checks the platform's password policy on each input change.
 - Custom checks: confirms that new password matches confirmation and that the new password differs from the current one.
-- Errors are displayed as `IIdentityError` codes mapped to i18n keys: `COMPONENTS.CHANGE_PASSWORD.ERRORS.{code}`.
+- Errors are displayed as `IdentityError` codes mapped to i18n keys: `COMPONENTS.CHANGE_PASSWORD.ERRORS.{code}`.
 
 ## Usage
 
@@ -70,7 +70,7 @@ The `ChangePassword` component renders a `VcPopup` with three validated input fi
 
 ## Error Codes
 
-Common `IIdentityError.code` values (mapped to i18n keys):
+Common `IdentityError.code` values (mapped to i18n keys):
 
 - `PasswordTooShort` -- below minimum length
 - `PasswordRequiresNonAlphanumeric` -- needs special characters
@@ -86,7 +86,14 @@ Common `IIdentityError.code` values (mapped to i18n keys):
 - In forced mode, there is no way to dismiss the dialog without either changing the password or signing out.
 - The component uses `useRouter()` for navigation after sign-out or successful change.
 
+## CSS Variables
+
+| Variable                        | Default                 | Applies to                   |
+| ------------------------------- | ----------------------- | ---------------------------- |
+| `--change-password-error-color` | `var(--danger-500)`     | Inline API error hints       |
+| `--change-password-text-color`  | `var(--additional-950)` | Forced-mode info banner text |
+
 ## Related
 
 - `framework/core/composables/useUserManagement/` -- `changeUserPassword`, `validatePassword`, `signOut`
-- `framework/core/api/platform/` -- `IIdentityError` type
+- `framework/core/api/platform/` -- `IdentityError` type

package/runtime/knowledge/docs/shell/components/change-password-button/change-password-button.docs.md

@@ -44,7 +44,7 @@ settingsMenu.register({
 
 ## Key Props
 
-This component has no props. It uses `usePopup()` to open the ChangePassword form and `useUserManagement()` internally for password validation.
+This component has no props. It uses `usePopup()` to open the ChangePassword form and injects `CloseSettingsMenuKey` to dismiss the parent menu. Password validation lives in the ChangePassword popup, not in this button.
 
 ## Recipe: Registering Account Actions in a Module
 
@@ -78,12 +78,12 @@ export default {
 
 - **Flow sequence**: Click button -> close settings menu -> open popup -> user fills form -> submit -> popup closes.
 - **Password validation**: The popup form uses `useUserManagement().validatePassword()` to check the new password against the platform's password policy in real time (minimum length, required character classes, etc.).
-- **Equal password detection**: If the user enters the same value for current and new password, the form shows a specific "Equal-passwords" error without making an API call.
+- **Equal password detection**: If the user enters the same value for current and new password, the form shows a specific "Equal-passwords" error without submitting the password change (the `changeUserPassword` call is skipped; `validatePassword()` still runs on input).
 - **Error handling**: API errors (e.g., incorrect current password) are displayed inline within the popup form.
 
 ## Tips
 
-- The button renders as a `SettingsMenuItem` with a key/lock icon. Its label comes from the i18n key `SETTINGS.CHANGE_PASSWORD`.
+- The button renders as a `SettingsMenuItem` with the `lucide-key` icon. Its label comes from the i18n key `SHELL.ACCOUNT.CHANGE_PASSWORD`.
 - If you need to trigger password change from a different context (not the settings menu), use `usePopup()` directly with the ChangePassword component.
 - The popup is modal -- the user must complete or cancel the password change before interacting with the rest of the application.
 

package/runtime/knowledge/docs/shell/components/error-interceptor/error-interceptor.docs.md

@@ -28,6 +28,13 @@ The component is renderless -- it renders its default slot and passes the curren
 | --------- | --------- | ------- | ------------------------------------------------ |
 | `capture` | `boolean` | `false` | Force error capture even outside a blade context |
 
+## Events
+
+| Event   | Payload           | Description                             |
+| ------- | ----------------- | --------------------------------------- |
+| `error` | `Error \| string` | Emitted when a new error is captured    |
+| `reset` | --                | Emitted when the error state is cleared |
+
 ## Slot Props
 
 | Prop    | Type                       | Description                             |
@@ -74,7 +81,7 @@ The component is renderless -- it renders its default slot and passes the curren
 import { ErrorInterceptor } from "@vc-shell/framework";
 ```
 
-The component is registered globally -- it can be used in templates without importing.
+The component must be imported before use, as shown above.
 
 ## Tips
 
@@ -86,4 +93,4 @@ The component is registered globally -- it can be used in templates without impo
 
 - `framework/core/composables/useErrorHandler/` -- the underlying composable
 - `framework/core/utilities/pendingErrorNotifications.ts` -- cancels deferred toasts
-- `framework/shared/components/blade-navigation/` -- BladeStack error management
+- `framework/core/blade-navigation/` -- BladeStack error management (types the interceptor injects)

package/runtime/knowledge/docs/shell/components/language-selector/language-selector.docs.md

@@ -73,12 +73,14 @@ If you need to change the locale from code (e.g., based on user profile settings
 
 ```ts
 import { useLanguages } from "@vc-shell/framework";
+import { useI18n } from "vue-i18n";
 
-const { currentLocale, setLocale, availableLocales } = useLanguages();
+const { currentLocale, setLocale } = useLanguages();
+const { availableLocales } = useI18n();
 
 // Set locale on login based on user preference
 async function onLogin(user) {
-  if (user.preferredLocale && availableLocales.value.includes(user.preferredLocale)) {
+  if (user.preferredLocale && availableLocales.includes(user.preferredLocale)) {
     setLocale(user.preferredLocale);
   }
 }

package/runtime/knowledge/docs/shell/components/logout-button/logout-button.docs.md

@@ -80,7 +80,7 @@ export default {
 - **Menu dismissal**: Before starting the sign-out flow, the component calls the injected `CloseSettingsMenuKey` function to close the dropdown. This prevents a visual artifact where the menu stays open while the page redirects.
 - **Blade cleanup**: All open child blades are closed via `useBladeStack()` before redirecting. This avoids orphaned blade state in the navigation stack.
 - **Redirect**: After sign-out completes, the user is redirected to the `/login` route.
-- **External providers**: If the user signed in through an external SSO provider, the sign-out flow also triggers the provider's logout redirect via `useExternalProvider().signOut()`.
+- **External providers**: If the user signed in through an external SSO provider, `useUserManagement().signOut()` handles the provider's logout redirect internally as part of the same call — the component does not invoke it separately.
 
 ## Tips
 

package/runtime/knowledge/docs/shell/components/notification-dropdown/notification-dropdown.docs.md

@@ -7,7 +7,9 @@ internal: true
 
 # NotificationDropdown
 
-Dropdown panel that displays the push notification history in reverse chronological order. This component renders a scrollable list of all received push notifications, backed by the `useNotifications()` composable. It automatically marks unread notifications as read when the dropdown is closed (unmounted), updating the unread badge count in the toolbar.
+> **Note:** `useNotifications()` is deprecated (it logs a dev warning). Use `useBladeNotifications()` for blade-scoped subscriptions, or `useNotificationStore()` for direct store access — an advanced escape hatch that most apps do not need, since the shell already wires the bell and unread badge. The component itself uses `useNotificationStore()`.
+
+Dropdown panel that displays the push notification history in reverse chronological order. This component renders a scrollable list of all received push notifications, backed by the `useNotificationStore()`. It automatically marks unread notifications as read when the dropdown is closed (unmounted), updating the unread badge count in the toolbar.
 
 The dropdown is designed for persistent notification history (server-side push notifications via SignalR), not for transient toast messages.
 
@@ -31,18 +33,21 @@ import { NotificationDropdown } from "@vc-shell/framework";
 
 ## Key Props
 
-This component has no props. Notification data comes from the shared notification store via `useNotifications()`.
+This component has no props. Notification data comes from the shared notification store via `useNotificationStore()` — the same store the shell's bell is wired to.
 
 ## Recipe: Notification Bell with Unread Badge
 
-The typical integration pattern pairs a toolbar button with the dropdown:
+> **Advanced — most apps do not need this.** The standard `VcApp` shell already renders the bell, dropdown, and unread badge. Build your own only in a custom shell that replaces the shell chrome. To _react_ to notifications inside a blade, use [`useBladeNotifications()`](../../../core/notifications/composables/useBladeNotifications.docs.md) instead; its `unreadCount` is scoped to the notify types you subscribe to. For a global count across all types you need the store, as shown here.
+
+A custom bell pairs a toolbar button with the dropdown and reads the global unread count from the store:
 
 ```vue
 <script setup lang="ts">
 import { ref, computed } from "vue";
-import { NotificationDropdown, useNotifications } from "@vc-shell/framework";
+import { NotificationDropdown, useNotificationStore } from "@vc-shell/framework";
 
-const { notifications, unreadCount } = useNotifications();
+const store = useNotificationStore();
+const unreadCount = computed(() => store.unreadCount.value);
 const isOpen = ref(false);
 </script>
 
@@ -70,54 +75,53 @@ const isOpen = ref(false);
 For testing or injecting client-side notifications:
 
 ```ts
-import { useNotifications } from "@vc-shell/framework";
-import { PushNotification } from "@vc-shell/framework";
-
-const { addNotification } = useNotifications();
-
-addNotification(
-  new PushNotification({
-    id: "order-123",
-    notifyType: "OrderCreated",
-    title: "New order received",
-    description: "Order #123 placed by customer.",
-    isNew: true,
-    created: new Date(),
-  }),
-);
+import { useNotificationStore } from "@vc-shell/framework";
+import type { PushNotification } from "@vc-shell/framework";
+
+const store = useNotificationStore();
+
+store.ingest({
+  id: "order-123",
+  notifyType: "OrderCreated",
+  title: "New order received",
+  description: "Order #123 placed by customer.",
+  isNew: true,
+  created: new Date(),
+} as PushNotification);
 ```
 
 ### Custom notification templates
 
-Provide custom templates via the `NotificationTemplatesKey` injection key to render domain-specific notification layouts based on `notifyType`. This allows each module to define how its notifications look:
+Register custom templates through the module `notifications` config to render domain-specific notification layouts keyed by `notifyType`. Each module defines how its own notifications look:
 
 ```ts
-import { provide } from "vue";
-import { NotificationTemplatesKey } from "@vc-shell/framework";
+import { defineAppModule } from "@vc-shell/framework";
 import OrderNotification from "./OrderNotification.vue";
 import ImportNotification from "./ImportNotification.vue";
 
-provide(NotificationTemplatesKey, {
-  OrderCreated: OrderNotification,
-  OrderStatusChanged: OrderNotification,
-  CatalogImportCompleted: ImportNotification,
+export default defineAppModule({
+  notifications: {
+    OrderCreated: { template: OrderNotification, toast: { mode: "auto" } },
+    OrderStatusChanged: { template: OrderNotification, toast: { mode: "auto" } },
+    CatalogImportCompleted: { template: ImportNotification, toast: { mode: "auto" } },
+  },
 });
 ```
 
-When a notification's `notifyType` matches a registered template key, that component is rendered instead of the default `NotificationTemplate`.
+When a notification's `notifyType` matches a registered template, that component is rendered instead of the default `NotificationTemplate`. See [NotificationTemplate](../notification-template/notification-template.docs.md) for the full recipe.
 
 ## Details
 
 - **Unread tracking**: Notifications have an `isNew` flag. When the dropdown is mounted, it displays all notifications. On unmount (dropdown closes), all visible notifications are marked as read (`isNew = false`), which updates the unread badge count.
 - **Reverse chronological order**: Notifications are displayed newest-first, sorted by their `created` timestamp.
-- **SignalR integration**: Push notifications arrive via SignalR from the VirtoCommerce Platform. The `useNotifications()` composable manages the SignalR connection and notification store.
+- **SignalR integration**: Push notifications arrive via SignalR from the VirtoCommerce Platform, delivered by the `signalR` plugin and ingested into the notification store; the dropdown renders from that store.
 - **Scroll behavior**: The notification list is scrollable with a fixed maximum height to prevent the dropdown from growing beyond the viewport.
 
 ## Tips
 
 - The dropdown shows all notifications, not just unread ones. Read notifications appear with reduced visual emphasis.
-- To clear the notification history, use `useNotifications().clearAll()`.
-- For background task progress (e.g., catalog import), notifications include `progressValue` and `isRunning` fields. The `NotificationTemplate` can render a progress bar when these are present.
+- There is no clear-history API. `useNotificationStore()` exposes `markAllAsRead()` (flip everything to read) and `loadHistory(take?)` (reload the latest page from the server); neither deletes history.
+- For background task progress (e.g., catalog import), the progress/completion concept keys off a `finished` flag on the notification payload. When a type is configured with a progress toast (`toast: { mode: "progress" }`), `ToastConfig.isComplete` reads that flag (default `(msg) => !!msg.finished`) to decide when the operation is done.
 - The dropdown does not poll for new notifications -- they arrive in real time via SignalR. If the connection drops, a reconnection is attempted automatically.
 
 ## Related Components

package/runtime/knowledge/docs/shell/components/notification-template/notification-template.docs.md

@@ -9,7 +9,7 @@ internal: true
 
 Base template for rendering a single push notification with title, relative timestamp, optional icon, and a default slot for extra detail content. This component provides the standard layout that all notification types share, while allowing domain-specific content to be injected through the default slot.
 
-The template displays the notification title, a "time ago" timestamp (e.g., "3 minutes ago"), and optionally a colored icon badge. Custom notification templates extend this base by wrapping it and filling the slot with type-specific content like progress bars, action buttons, or entity links.
+The template displays the notification title and a timestamp — a relative "time ago" string for recent notifications (< 1 day, e.g., "3 minutes ago") or an absolute short date-time for older ones (>= 1 day) — and optionally a colored icon badge. Custom notification templates extend this base by wrapping it and filling the slot with type-specific content like progress bars, action buttons, or entity links.
 
 ## When to Use
 
@@ -38,13 +38,19 @@ const notification = computed(() => notificationRef.value);
 
 ## Key Props
 
-| Prop           | Type                | Default     | Description                                       |
-| -------------- | ------------------- | ----------- | ------------------------------------------------- |
-| `title`        | `string`            | --          | Notification headline text                        |
-| `notification` | `IPushNotification` | --          | Full notification object (required for timestamp) |
-| `icon`         | `string`            | `undefined` | Icon name displayed in a circular badge           |
-| `color`        | `string`            | `undefined` | Background color for the icon badge               |
-| `severity`     | `string`            | `undefined` | Semantic severity level                           |
+| Prop           | Type               | Default     | Description                                                    |
+| -------------- | ------------------ | ----------- | -------------------------------------------------------------- |
+| `title`        | `string`           | --          | Notification headline text                                     |
+| `notification` | `PushNotification` | --          | Full notification object (required for timestamp)              |
+| `icon`         | `string`           | `undefined` | Icon name displayed in a circular badge                        |
+| `color`        | `string`           | `undefined` | Background color for the icon badge                            |
+| `severity`     | `string`           | `undefined` | Accepted but currently unused by the base template (reserved). |
+
+## Events
+
+| Event   | Payload | Description                          |
+| ------- | ------- | ------------------------------------ |
+| `click` | --      | Emitted when the root row is clicked |
 
 ## Recipe: Custom Notification for Order Events
 
@@ -160,16 +166,16 @@ const isRunning = computed(() => (notification.value as any).isRunning ?? false)
 
 ## Details
 
-- **Relative timestamps**: The template displays the time elapsed since the notification was created using a "time ago" format (e.g., "2 minutes ago", "1 hour ago"). This updates reactively.
+- **Timestamps**: For recent notifications (less than a day old) the template shows a relative "time ago" string via `Intl.RelativeTimeFormat` (e.g., "2 minutes ago", "1 hour ago"); for older notifications (>= 1 day) it falls back to an absolute short date-time via `Intl.DateTimeFormat` (`dateStyle: "short"`, `timeStyle: "short"`). It is computed once per render from the notification's created time and does not tick on a clock; it recomputes only when the notification data changes.
 - **Icon badge**: When the `icon` prop is provided, it renders in a small circular badge with the specified `color` background. This helps users quickly identify notification types visually.
 - **Default slot**: The slot content appears below the title and timestamp, providing space for description text, progress indicators, action links, or any custom content.
-- **Unread indicator**: New (unread) notifications have a subtle visual indicator (e.g., a dot or bold title) to distinguish them from read notifications.
+- **Read state**: The base template renders no unread/read indicator — it has no `isNew`/read prop. Read-state styling, if any, is handled by the notification dropdown, not this template.
 
 ## Tips
 
 - Use `useNotificationContext()` to access notification data. No props needed — the renderer provides the notification automatically.
 - Use CSS custom property values for the `color` prop (e.g., `var(--success-500)`) to stay consistent with the active theme.
-- The `severity` prop can be used to apply predefined color schemes without specifying a custom `color`.
+- The `severity` prop is accepted but not yet consumed by the base template — it applies no color scheme. Use the `color` prop for the icon badge color.
 - When creating custom templates, keep the slot content concise. The notification dropdown shows many items in a scrollable list, and overly tall notifications push others out of view.
 
 ## Related Components