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

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+# [2.0.0-alpha.34](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.33...v2.0.0-alpha.34) (2026-04-22)
+
+
+### Bug Fixes
+
+* **datatable:** normalise date-range filter values to YYYY-MM-DD ([d89864a](https://github.com/VirtoCommerce/vc-shell/commit/d89864aa635e7479137fb0ad501197adf335f99e))
+* **migrate:** datatable prompt forbids 'removed filters for green build' shortcut ([af5ae8e](https://github.com/VirtoCommerce/vc-shell/commit/af5ae8e4259b435729e6cea9e4c61d74b41d3952))
+* **migrate:** use-data-table-pagination prompt — per-file scope skip ([8949f01](https://github.com/VirtoCommerce/vc-shell/commit/8949f01da97b69c15fc6e3a2fca951608731979c))
+
+
+### chore
+
+* **scripts:** normalize yarn scripts per industry standards ([1cdd0cb](https://github.com/VirtoCommerce/vc-shell/commit/1cdd0cb517d2436ef2a509c6b6c358f6a48630d1))
+
+
+### Features
+
+* **migrate:** add use-data-table-pagination-audit + AI migration prompt ([0c2e7b6](https://github.com/VirtoCommerce/vc-shell/commit/0c2e7b6efba387d9fafe04e5bdcd21ea20500259))
+* **migrate:** expand v2 migration tooling — icon/asset/audit prompts and blade-event cleanup ([f4788d4](https://github.com/VirtoCommerce/vc-shell/commit/f4788d4d9c588157ca5c11facfe558a69c254c2e)), closes [#41](https://github.com/VirtoCommerce/vc-shell/issues/41)
+
+
+### BREAKING CHANGES
+
+* **scripts:** for external consumers: old script names
+(storybook-serve, build-framework, check-locales etc) are removed.
+Legacy aliases are deliberately not provided — they would perpetuate
+the non-standard naming this commit eliminates.
 # [2.0.0-alpha.33](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.32...v2.0.0-alpha.33) (2026-04-14)
 
 ### Bug Fixes

package/README.md

@@ -14,6 +14,7 @@ The skill covers:
 - Enhancing existing modules with surgical modifications (add columns, fields, toolbar actions, logic, blade links)
 - Generating full multi-module applications from a free-text prompt (design command)
 - Promoting prototype modules from mock data to real API clients
+- Migrating existing apps to the latest `@vc-shell/framework` version (runs the CLI migrator, regenerates API clients, completes AI-assisted manual refactors)
 - Following vc-shell conventions: Vue 3 + TypeScript, Tailwind with `tw-` prefix, `<script setup>`, BEM class names
 
 ## Installation
@@ -154,6 +155,28 @@ When you generate a module without an API client, it uses mock data with `// vc-
 - **Phase 4: Code Transformation** — replaces mock code with real API calls, renames fields, updates locales
 - **Phase 5: Cleanup** — type-checks, removes prototype marker on success
 
+### `/vc-app migrate`
+
+Fully automatic migration of an existing app to the latest `@vc-shell/framework` version. Runs the CLI migrator for mechanical transforms, regenerates API clients with the new Interface-style output, installs updated dependencies, and dispatches AI agents to complete manual refactors flagged in `MIGRATION_REPORT.md`.
+
+```
+/vc-app migrate
+```
+
+Flow:
+
+- **Step 1: Pre-flight** — verifies the project uses `@vc-shell/framework`; warns on uncommitted changes
+- **Step 2: CLI migrator** — runs `@vc-shell/migrate --update-deps` to apply mechanical transforms and align peer-dependency versions (including `@vc-shell/*`, ESLint, Vite, TypeScript, VueUse, `vue-router` and other curated peer deps)
+- **Step 2.5: API client regeneration** — adds `APP_TYPE_STYLE=Interface`, runs `generate-api-client`, verifies types compile
+- **Step 3: Install** — `yarn install` to refresh the lockfile
+- **Step 4: Parse report** — reads `MIGRATION_REPORT.md`, maps "Manual Migration Required" topics to migration prompts and patterns
+- **Step 5: AI migration** — dispatches `migration-agent` on affected files per topic (supports partial resume via `.vc-app-migrate-state.json`)
+- **Step 6: Verify** — runs `vue-tsc --noEmit` and `yarn build`, iteratively fixes type errors
+- **Step 6.5: Format** — runs Prettier across the project
+- **Step 7: Summary** — updates the report and prints a completion summary with remaining issues
+
+Handles topics: widgets, form management (`useBladeForm`), injection-key renames, NSwag class-to-interface, blade props simplification, notifications, VcTable → VcDataTable, icon replacements, assets API, pagination, and a manual-audit catch-all.
+
 ## Update
 
 ```bash
@@ -215,17 +238,18 @@ cli/vc-app-skill/
 
 The skill dispatches specialized agents for different tasks:
 
-| Agent                     | Purpose                                                           |
-| ------------------------- | ----------------------------------------------------------------- |
-| `api-analyzer`            | Discovers entities and CRUD methods in API client files           |
-| `list-blade-generator`    | Generates list blade + plural composable                          |
-| `details-blade-generator` | Generates details blade + singular composable                     |
-| `locales-generator`       | Scans generated files for i18n keys, writes locale JSON           |
-| `module-assembler`        | Creates barrel files and registers module (create + append modes) |
-| `type-checker`            | Runs vue-tsc, iteratively fixes type errors                       |
-| `promote-agent`           | Transforms mock composables/blades/locales to use real API        |
-| `module-analyzer`         | Analyzes existing module structure (read-only)                    |
-| `blade-enhancer`          | Surgical edits to existing blades/composables/locales             |
+| Agent                     | Purpose                                                                    |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `api-analyzer`            | Discovers entities and CRUD methods in API client files                    |
+| `list-blade-generator`    | Generates list blade + plural composable                                   |
+| `details-blade-generator` | Generates details blade + singular composable                              |
+| `locales-generator`       | Scans generated files for i18n keys, writes locale JSON                    |
+| `module-assembler`        | Creates barrel files and registers module (create + append modes)          |
+| `type-checker`            | Runs vue-tsc, iteratively fixes type errors                                |
+| `promote-agent`           | Transforms mock composables/blades/locales to use real API                 |
+| `migration-agent`         | Applies AI-assisted manual migrations on files flagged by the migrate flow |
+| `module-analyzer`         | Analyzes existing module structure (read-only)                             |
+| `blade-enhancer`          | Surgical edits to existing blades/composables/locales                      |
 
 ### Running locally
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.0-alpha.33-pr220.455e322",
+  "version": "2.0.0-alpha.34",
   "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.0-alpha.33
+2.0.0-alpha.34

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit b399787ff on 2026-04-14T15:15:27.844Z
+Synced from framework at commit cec6c9078 on 2026-04-22T09:43:16.584Z

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

@@ -56,14 +56,14 @@ import { toRef } from "vue";
 
 const assets = useAssetsManager(
   computed({
-    get: () => entity.value.images ?? [],
+    get: () => offer.value.images ?? [],
     set: (val) => {
-      entity.value.images = val;
+      offer.value.images = val;
     },
   }),
   {
-    uploadPath: () => `entities/${entity.value?.id ?? "new"}`,
-    confirmRemove: () => showConfirmation(t("MODULE.ALERTS.IMAGE_DELETE")),
+    uploadPath: () => `offers/${offer.value?.id ?? "new"}`,
+    confirmRemove: () => showConfirmation(t("OFFERS.ALERTS.IMAGE_DELETE")),
   },
 );
 ```

package/runtime/knowledge/docs/core/composables/useBladeWidgets/index.docs.md

@@ -22,21 +22,21 @@ import { useBladeWidgets } from "@vc-shell/framework";
 
 const { refreshAll } = useBladeWidgets([
   {
-    id: "ChildListWidget",
+    id: "OffersWidget",
     icon: "lucide-tag",
-    title: "MODULE.WIDGETS.CHILD_LIST.TITLE",
-    badge: childCount,
-    loading: childLoading,
-    onClick: () => openBlade({ name: "ChildList" }),
-    onRefresh: () => reloadChildren(),
+    title: "OFFERS.TITLE",
+    badge: offersCount,
+    loading: offersLoading,
+    onClick: () => openBlade({ name: "OffersList" }),
+    onRefresh: () => reloadOffers(),
   },
   {
-    id: "NotesWidget",
+    id: "ReviewsWidget",
     icon: "lucide-star",
-    title: "MODULE.WIDGETS.NOTES.TITLE",
-    badge: notesCount,
+    title: "REVIEWS.TITLE",
+    badge: reviewsCount,
     isVisible: computed(() => !!item.value?.id),
-    onClick: () => openBlade({ name: "NotesList" }),
+    onClick: () => openBlade({ name: "ReviewsList" }),
   },
 ]);
 
@@ -119,7 +119,7 @@ import { MessageWidget } from "./components/widgets";
 registerExternalWidget({
   id: "MessageWidget",
   component: markRaw(MessageWidget),
-  targetBlades: ["EntityDetails", "AnotherDetails"],
+  targetBlades: ["ProductDetails", "OrderDetails"],
   isVisible: (blade?: BladeDescriptor) => !!blade?.param,
 });
 ```
@@ -176,61 +176,61 @@ import { useBladeWidgets } from "@vc-shell/framework";
 const { refresh, refreshAll } = useBladeWidgets([]);
 
 async function save() {
-  await api.saveEntity(entity.value);
+  await api.saveProduct(product.value);
   refreshAll(); // refresh all widgets (including MessageWidget)
   // or: refresh("MessageWidget");  // refresh a specific widget by ID
 }
 </script>
 ```
 
-## Recipe: Entity Detail Blade with Multiple Widgets
+## Recipe: Product Detail Blade with Multiple Widgets
 
 ```vue
 <script setup lang="ts">
 import { ref, computed } from "vue";
 import { useBladeWidgets, defineBladeContext } from "@vc-shell/framework";
 
-const entity = ref({ id: "ent-1", name: "Sample" });
-const childCount = ref(0);
-const notesCount = ref(0);
-const childLoading = ref(false);
+const product = ref({ id: "prod-1", name: "Widget A" });
+const offersCount = ref(0);
+const reviewsCount = ref(0);
+const offersLoading = ref(false);
 
-// Expose entity data to widgets
-defineBladeContext(computed(() => ({ id: entity.value?.id })));
+// Expose product data to widgets
+defineBladeContext(computed(() => ({ id: product.value?.id })));
 
-async function reloadChildren() {
-  childLoading.value = true;
+async function reloadOffers() {
+  offersLoading.value = true;
   try {
-    const result = await api.searchChildren({ entityId: entity.value.id });
-    childCount.value = result.totalCount;
+    const result = await api.searchOffers({ productId: product.value.id });
+    offersCount.value = result.totalCount;
   } finally {
-    childLoading.value = false;
+    offersLoading.value = false;
   }
 }
 
 const { refreshAll } = useBladeWidgets([
   {
-    id: "ChildListWidget",
+    id: "OffersWidget",
     icon: "lucide-tag",
-    title: "MODULE.WIDGETS.CHILD_LIST",
-    badge: childCount,
-    loading: childLoading,
-    isVisible: computed(() => !!entity.value?.id),
-    onClick: () => openBlade({ name: "ChildList" }),
-    onRefresh: reloadChildren,
+    title: "PRODUCT.WIDGETS.OFFERS",
+    badge: offersCount,
+    loading: offersLoading,
+    isVisible: computed(() => !!product.value?.id),
+    onClick: () => openBlade({ name: "OffersList" }),
+    onRefresh: reloadOffers,
   },
   {
-    id: "NotesWidget",
+    id: "ReviewsWidget",
     icon: "lucide-star",
-    title: "MODULE.WIDGETS.NOTES",
-    badge: notesCount,
-    isVisible: computed(() => !!entity.value?.id),
-    onClick: () => openBlade({ name: "NotesList" }),
+    title: "PRODUCT.WIDGETS.REVIEWS",
+    badge: reviewsCount,
+    isVisible: computed(() => !!product.value?.id),
+    onClick: () => openBlade({ name: "ReviewsList" }),
   },
 ]);
 
 async function save() {
-  await api.saveEntity(entity.value);
+  await api.saveProduct(product.value);
   // Refresh all widget counts after saving
   refreshAll();
 }

package/runtime/knowledge/docs/core/composables/useMenuExpanded/index.docs.md

@@ -67,7 +67,7 @@ const isVisuallyExpanded = computed(() => isExpanded.value || isHoverExpanded.va
 
 ## Details
 
-- **Storage key scoping**: The key is scoped per application using the first URL path segment: `VC_APP_MENU_EXPANDED_{appName}`. For example, if the app is hosted at `/my-app/`, the key is `VC_APP_MENU_EXPANDED_my-app`. This allows multiple vc-shell apps on the same domain to maintain independent sidebar states.
+- **Storage key scoping**: The key is scoped per application using the first URL path segment: `VC_APP_MENU_EXPANDED_{appName}`. For example, if the app is hosted at `/vendor-portal/`, the key is `VC_APP_MENU_EXPANDED_vendor-portal`. This allows multiple vc-shell apps on the same domain to maintain independent sidebar states.
 - **Hover delay**: Opening uses a 200ms debounce to prevent accidental expansion when the cursor briefly passes over the sidebar. Closing is immediate to feel responsive.
 - **Cleanup**: Pending hover timeouts are cleaned up via `onScopeDispose` to prevent memory leaks when the composable's effect scope is destroyed.
 - **Default state**: The sidebar starts pinned open (`true`) on first visit, which is the most user-friendly default for new users.

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

@@ -0,0 +1,28 @@
+# 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/composables/useSettings/useSettings.docs.md

@@ -88,8 +88,8 @@ const { applySettings } = useSettings();
 
 // Override default platform settings with module-specific branding
 applySettings({
-  logo: "/modules/my-module/logo.svg",
-  title: "My Module",
+  logo: "/modules/vendor-portal/logo.svg",
+  title: "Vendor Portal",
 });
 </script>
 ```

package/runtime/knowledge/docs/core/plugins/extension-points/extension-points.docs.md

@@ -51,7 +51,7 @@ This is how vc-shell achieves its modular architecture: modules can extend each
 
     <!-- Other modules can inject components here -->
     <ExtensionPoint
-      name="entity:custom-fields"
+      name="seller:commissions"
       separator
       gap="1rem"
     />
@@ -66,14 +66,14 @@ import { ExtensionPoint } from "@vc-shell/framework";
 **Plugin module** -- registers a component into that extension point:
 
 ```typescript
-// modules/entity-extensions/index.ts
+// modules/marketplace-commissions/index.ts
 import { defineAppModule, useExtensionPoint } from "@vc-shell/framework";
-import CustomFields from "./components/CustomFields.vue";
+import CommissionFields from "./components/CommissionFields.vue";
 
-const { add } = useExtensionPoint("entity:custom-fields");
+const { add } = useExtensionPoint("seller:commissions");
 add({
-  id: "entity-extension",
-  component: CustomFields,
+  id: "marketplace-commission",
+  component: CommissionFields,
   props: { showAdvanced: true },
   priority: 10,
 });
@@ -83,7 +83,7 @@ export default defineAppModule({
 });
 ```
 
-When the seller details page renders, `CustomFields` appears automatically below the main form -- with a separator and 1rem gap.
+When the seller details page renders, `CommissionFields` appears automatically below the main form -- with a separator and 1rem gap.
 
 ---
 
@@ -97,9 +97,9 @@ Extension points follow a two-role architecture:
 HOST (declares)                      PLUGIN (registers)
 -----------------                    ------------------
 "I have a slot called                "I want to put my
- entity:custom-fields                   CustomFields
+ seller:commissions                   CommissionFields
  where plugins can                    component in the
- inject content."                     entity:custom-fields slot."
+ inject content."                     seller:commissions slot."
 
       |                                       |
       v                                       v
@@ -116,8 +116,8 @@ Neither side imports the other. They communicate through a shared **name string*
 
 Plugins can register components **before** the host declares the extension point. The reactive store handles this gracefully:
 
-1. Plugin calls `useExtensionPoint("entity:custom-fields")` and `add(...)` -- the store creates an undeclared entry and stores the component.
-2. Later, host calls `defineExtensionPoint("entity:custom-fields")` -- the store upgrades the entry to "declared" and preserves all previously registered components.
+1. Plugin calls `useExtensionPoint("seller:commissions")` and `add(...)` -- the store creates an undeclared entry and stores the component.
+2. Later, host calls `defineExtensionPoint("seller:commissions")` -- the store upgrades the entry to "declared" and preserves all previously registered components.
 3. The host's `components` computed ref reactively picks up the registered components.
 
 This means module load order does not matter. Remote modules loaded via Module Federation may install in any sequence, and extensions still work.
@@ -165,7 +165,7 @@ Used in pages or components that **accept** plugin content. Declares the extensi
 ```typescript
 import { defineExtensionPoint } from "@vc-shell/framework";
 
-const { components, hasComponents } = defineExtensionPoint("entity:custom-fields", {
+const { components, hasComponents } = defineExtensionPoint("seller:commissions", {
   description: "Commission fee fields in the seller details form",
 });
 
@@ -201,7 +201,7 @@ Used in modules that **provide** content to an extension point. Returns `add` an
 import { useExtensionPoint } from "@vc-shell/framework";
 import MyComponent from "./MyComponent.vue";
 
-const { add, remove } = useExtensionPoint("entity:custom-fields");
+const { add, remove } = useExtensionPoint("seller:commissions");
 
 // Register a component
 add({
@@ -231,7 +231,7 @@ The `<ExtensionPoint>` component is the easiest way to render extensions in a te
 
 ```vue
 <template>
-  <ExtensionPoint name="entity:custom-fields" />
+  <ExtensionPoint name="seller:commissions" />
 </template>
 
 <script setup lang="ts">
@@ -260,10 +260,10 @@ The component has three rendering modes, chosen automatically:
 
 ```vue
 <!-- Layout mode: separator + gap -->
-<ExtensionPoint name="entity:custom-fields" separator gap="1rem" wrapper-class="tw-p-4" />
+<ExtensionPoint name="seller:commissions" separator gap="1rem" wrapper-class="tw-p-4" />
 
 <!-- Plain mode: no wrapper -->
-<ExtensionPoint name="entity:custom-fields" />
+<ExtensionPoint name="seller:commissions" />
 ```
 
 ### Scoped Slots for Custom Rendering
@@ -334,7 +334,7 @@ Currently defined constants:
 | --------------------------------- | ------------------- | ---------------------------------- |
 | `ExtensionPoints.AUTH_AFTER_FORM` | `"auth:after-form"` | Login page, below the sign-in form |
 
-App-level extension point names (e.g., `"entity:custom-fields"`) are the app's responsibility to define. Consider creating a shared constants file in your application.
+App-level extension point names (e.g., `"seller:commissions"`) are the app's responsibility to define. Consider creating a shared constants file in your application.
 
 ---
 
@@ -356,7 +356,7 @@ Scenario: You want to add commission fee fields to the Seller Details page, whic
 
     <ExtensionPoint
       v-if="sellerDetails?.id"
-      name="entity:custom-fields"
+      name="seller:commissions"
       wrapper-class="tw-p-2"
     />
   </VcBlade>
@@ -368,13 +368,13 @@ Scenario: You want to add commission fee fields to the Seller Details page, whic
 ```typescript
 // commissions/index.ts
 import { defineAppModule, useExtensionPoint } from "@vc-shell/framework";
-import CustomFields from "./components/CustomFields.vue";
+import CommissionFields from "./components/CommissionFields.vue";
 import en from "./locales/en.json";
 
-const { add } = useExtensionPoint("entity:custom-fields");
+const { add } = useExtensionPoint("seller:commissions");
 add({
   id: "commission-fields",
-  component: CustomFields,
+  component: CommissionFields,
   props: { editable: true },
   priority: 10,
 });
@@ -382,10 +382,10 @@ add({
 export default defineAppModule({ locales: { en } });
 ```
 
-**Step 3:** `CustomFields.vue` receives props and renders:
+**Step 3:** `CommissionFields.vue` receives props and renders:
 
 ```vue
-<!-- commissions/components/CustomFields.vue -->
+<!-- commissions/components/CommissionFields.vue -->
 <template>
   <div class="commission-fields">
     <h3>{{ $t("COMMISSIONS.TITLE") }}</h3>
@@ -449,14 +449,14 @@ The host renders them in order: ShippingInfo, PaymentInfo, OrderNotes.
 If you call `add()` with an `id` that already exists, the component is replaced:
 
 ```typescript
-const { add } = useExtensionPoint("entity:custom-fields");
+const { add } = useExtensionPoint("seller:commissions");
 
 // Original registration (e.g., from another module or earlier in the code)
-add({ id: "commission-fields", component: OldCustomFields, priority: 10 });
+add({ id: "commission-fields", component: OldCommissionFields, priority: 10 });
 
 // Override with a new component (same id)
-add({ id: "commission-fields", component: NewCustomFields, priority: 10 });
-// Only NewCustomFields is rendered
+add({ id: "commission-fields", component: NewCommissionFields, priority: 10 });
+// Only NewCommissionFields is rendered
 ```
 
 This is useful for overriding default behavior provided by a base module.
@@ -504,7 +504,7 @@ add({ id: "quick-action", component: QuickAction, meta: { zone: "toolbar" } });
 // WRONG -- typo: "seller:comissions" (single 'm')
 const { add } = useExtensionPoint("seller:comissions");
 add({ id: "my-fields", component: MyFields });
-// Component is registered but never rendered because the host declared "entity:custom-fields"
+// Component is registered but never rendered because the host declared "seller:commissions"
 ```
 
 The dev-mode console warning (`Extension point "seller:comissions" is not declared`) will alert you to this. Always check the console in development.
@@ -514,7 +514,7 @@ The dev-mode console warning (`Extension point "seller:comissions" is not declar
 > ```typescript
 > // shared/extension-points.ts
 > export const EP = {
->   ENTITY_CUSTOM_FIELDS: "entity:custom-fields",
+>   SELLER_COMMISSIONS: "seller:commissions",
 >   ORDER_SIDEBAR: "order:sidebar",
 > } as const;
 > ```
@@ -524,7 +524,7 @@ The dev-mode console warning (`Extension point "seller:comissions" is not declar
 ```vue
 <!-- WRONG -- ExtensionPoint is not imported -->
 <template>
-  <ExtensionPoint name="entity:custom-fields" />
+  <ExtensionPoint name="seller:commissions" />
 </template>
 
 <script setup lang="ts">
@@ -546,7 +546,7 @@ add({ id: "my-component", component: ComponentB });
 Use globally unique IDs. A good convention is `module-name:component-name`:
 
 ```typescript
-add({ id: "module:custom-fields", component: CustomFields });
+add({ id: "marketplace:commission-fields", component: CommissionFields });
 add({ id: "shipping:delivery-estimate", component: DeliveryEstimate });
 ```
 
@@ -668,9 +668,10 @@ These are used internally by `defineExtensionPoint` and `useExtensionPoint`. You
 
 ## Related
 
-| Resource                 | Path                                               | Description                                   |
-| ------------------------ | -------------------------------------------------- | --------------------------------------------- |
-| Modularity Plugin        | `core/plugins/modularity/`                         | Module definition and registration            |
-| Extension Point Store    | `core/plugins/extension-points/store.ts`           | Reactive registry implementation              |
-| ExtensionPoint Component | `core/plugins/extension-points/ExtensionPoint.vue` | Declarative render component                  |
-| Types                    | `core/plugins/extension-points/types.ts`           | `ExtensionComponent`, `ExtensionPointOptions` |
+| Resource                       | Path                                               | Description                                   |
+| ------------------------------ | -------------------------------------------------- | --------------------------------------------- |
+| Modularity Plugin              | `core/plugins/modularity/`                         | Module definition and registration            |
+| Extension Point Store          | `core/plugins/extension-points/store.ts`           | Reactive registry implementation              |
+| ExtensionPoint Component       | `core/plugins/extension-points/ExtensionPoint.vue` | Declarative render component                  |
+| Types                          | `core/plugins/extension-points/types.ts`           | `ExtensionComponent`, `ExtensionPointOptions` |
+| Seller Details (usage example) | `apps/vendor-portal/src/modules/seller-details/`   | Real-world extension point host               |

package/runtime/knowledge/docs/core/plugins/modularity/modularity.docs.md

@@ -703,16 +703,16 @@ export default defineAppModule({});
 A module can extend another module's UI by using extension points (see the [Extension Points Plugin](../extension-points/extension-points.docs.md)):
 
 ```typescript
-// modules/entity-extensions/index.ts
+// modules/marketplace-commissions/index.ts
 import { defineAppModule, useExtensionPoint } from "@vc-shell/framework";
-import CustomFields from "./components/CustomFields.vue";
+import CommissionFields from "./components/CommissionFields.vue";
 import en from "./locales/en.json";
 
-// Register into the entity details extension point
-const { add } = useExtensionPoint("entity:custom-fields");
+// Register into the seller details extension point
+const { add } = useExtensionPoint("seller:commissions");
 add({
-  id: "entity-extension",
-  component: CustomFields,
+  id: "marketplace-commission",
+  component: CommissionFields,
   props: { showAdvanced: true },
   priority: 10,
 });
@@ -733,7 +733,7 @@ The host blade declares the extension point:
     <!-- Other modules can inject components here -->
     <ExtensionPoint
       v-if="sellerDetails?.id"
-      name="entity:custom-fields"
+      name="seller:commissions"
       wrapper-class="tw-p-2"
     />
   </VcBlade>

package/runtime/knowledge/docs/shell/components/settings-menu/settings-menu.docs.md

@@ -46,7 +46,7 @@ This component has no props. All content is driven by the settings menu service
 A typical module registers all its settings entries during the module install phase:
 
 ```ts
-// my-module/index.ts
+// vendor-portal-module/index.ts
 import { markRaw } from "vue";
 import { useSettingsMenu, ThemeSelector, LanguageSelector, ChangePasswordButton, LogoutButton } from "@vc-shell/framework";
 

package/runtime/knowledge/docs/ui/components/organisms/vc-data-table/composables/table-composables.docs.md

@@ -10,12 +10,13 @@ The composables follow a PrimeVue-inspired pattern: each returns reactive state
 
 ### Data & State
 
-| Composable          | Purpose                                                                                                                                                            |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `useDataTableState` | Persists column widths, order, and hidden IDs to localStorage/sessionStorage. Key format: `VC_DATATABLE_{KEY}`. Debounced auto-save (150ms) with restore-on-mount. |
-| `useTableColumns`   | Column ordering, width tracking, alignment helpers, flex-column detection. Watches `visibleColumns` and appends new columns without dropping hidden ones.          |
-| `useDataProcessing` | Client-side sort pipeline (single/multi) and row grouping. Skipped when `lazy: true` (server-side).                                                                |
-| `useTableContext`   | Provides/injects table-level context for sub-components.                                                                                                           |
+| Composable             | Purpose                                                                                                                                                                                                                                             |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useDataTableState`    | Persists column state (v2 schema: weights, order, hidden/shown IDs) to localStorage/sessionStorage. Auto-migrates v1 (pixel-based) state on first load. Key format: `VC_DATATABLE_{KEY}`. Debounced auto-save (150ms) with restore-on-mount.        |
+| `useTableColumns`      | Column ordering, width management via `columnState` (weight store), computed pixel widths via `engineOutput`. Exposes `recompute()` to trigger a recalculation pass. Watches `visibleColumns` and appends new columns without dropping hidden ones. |
+| `useColumnWidthEngine` | Pure functions for deterministic column width computation (see below).                                                                                                                                                                              |
+| `useDataProcessing`    | Client-side sort pipeline (single/multi) and row grouping. Skipped when `lazy: true` (server-side).                                                                                                                                                 |
+| `useTableContext`      | Provides/injects table-level context for sub-components.                                                                                                                                                                                            |
 
 ### Sorting & Filtering
 
@@ -27,13 +28,13 @@ The composables follow a PrimeVue-inspired pattern: each returns reactive state
 
 ### Interaction
 
-| Composable               | Purpose                                                                                                                                                         |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `useTableRowReorder`     | Drag-and-drop row reordering with live-swap at 50% vertical threshold. Commits via `dragend` (always fires) with `drop` as preferred path.                      |
-| `useTableColumnsReorder` | Drag-and-drop column reordering with 50% horizontal threshold. Returns `getReorderHeadProps()` for easy binding.                                                |
-| `useTableColumnsResize`  | Two-column resize: dragging grows left column and shrinks right neighbor. DOM-based updates during drag for smooth 60fps; commits to reactive state on mouseup. |
-| `useTableSelectionV2`    | Row selection: single, multiple (checkbox), and row-click modes. Emits `RowSelectEvent` / `RowSelectAllEvent`.                                                  |
-| `useTableSwipe`          | Mobile swipe context (provide/inject). Tracks which row has an active swipe action.                                                                             |
+| Composable               | Purpose                                                                                                                                                                                                                                                         |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useTableRowReorder`     | Drag-and-drop row reordering with live-swap at 50% vertical threshold. Commits via `dragend` (always fires) with `drop` as preferred path.                                                                                                                      |
+| `useTableColumnsReorder` | Drag-and-drop column reordering with 50% horizontal threshold. Returns `getReorderHeadProps()` for easy binding.                                                                                                                                                |
+| `useTableColumnsResize`  | Weight-based resize: dragging adjusts the weights of the dragged column and its right neighbor without touching other columns. DOM-based px updates during drag for smooth 60fps; commits new weights to `columnState` on mouseup. No `ResizeObserver` scaling. |
+| `useTableSelectionV2`    | Row selection: single, multiple (checkbox), and row-click modes. Emits `RowSelectEvent` / `RowSelectAllEvent`.                                                                                                                                                  |
+| `useTableSwipe`          | Mobile swipe context (provide/inject). Tracks which row has an active swipe action.                                                                                                                                                                             |
 
 ### Editing
 
@@ -53,6 +54,68 @@ The composables follow a PrimeVue-inspired pattern: each returns reactive state
 | `useTableRowGrouping` | Groups rows by field and inserts group header rows.                                                                                             |
 | `useMobileCardLayout` | Mobile card view layout logic for responsive table display.                                                                                     |
 
+## useColumnWidthEngine
+
+`useColumnWidthEngine` is a collection of **pure functions** (no reactive state) for deterministic column width computation. `useTableColumns` calls these internally on every render pass and on container resize.
+
+### Core functions
+
+#### `computeColumnWidths(input: EngineInput): EngineOutput`
+
+The central engine. Distributes `availableWidth` among visible columns according to their current weights, enforcing `minWidth` / `maxWidth` constraints.
+
+```ts
+interface EngineInput {
+  visibleIds: string[]; // Ordered list of visible column IDs
+  specs: Record<string, ColumnSpec>; // Per-column: weight, minWidth, maxWidth
+  availableWidth: number; // Container width in px
+  fitMode: "gap" | "fit"; // "gap" leaves filler space, "fit" fills width
+}
+
+interface EngineOutput {
+  widths: Record<string, number>; // Computed px width per column ID
+  totalWidth: number; // Sum of all computed widths
+  overflow: boolean; // true when sum(minWidth) > availableWidth
+}
+```
+
+In crisis (`overflow: true`), each column receives its `minWidth` regardless of weight, and a console warning is emitted.
+
+#### `parseColumnWidth(value: string | number | undefined, availableWidth: number): ParsedWidth`
+
+Parses a `VcColumn` `width` prop into a concrete pixel value.
+
+```ts
+type ParsedWidth =
+  | { type: "px"; value: number } // "200", 200, "200px"
+  | { type: "pct"; value: number } // "20%" → 0.2 * availableWidth
+  | { type: "auto"; value: undefined }; // undefined, "auto"
+```
+
+#### `buildInitialWeights(parsed: ParsedWidth[], availableWidth: number): Record<string, number>`
+
+Converts an array of `ParsedWidth` values (one per column) into initial weights. Auto columns receive an equal share of the space not claimed by px/% columns.
+
+```ts
+// Example: three columns — 200px, 20%, auto — with 800px available
+// px-column  → weight 200
+// pct-column → weight 160  (20% of 800)
+// auto-column→ weight 440  (800 - 200 - 160)
+```
+
+#### `normalizeWeights(specs: Record<string, ColumnSpec>, visibleIds: string[]): void`
+
+Mutates `specs` in place so that the weights of `visibleIds` sum to 1.0. Called before a `"fit"` mode computation pass.
+
+### When weights update
+
+| User action                 | Weight change                                                                           |
+| --------------------------- | --------------------------------------------------------------------------------------- |
+| Column resize (drag border) | Dragged column and right neighbor exchange weight proportionally                        |
+| Column show/hide            | Hidden column's weight is preserved; shown column uses saved or initial weight          |
+| Reset columns               | All weights rebuilt from declarative `width` props                                      |
+| Container resize            | Weights unchanged; engine recomputes px widths from same weights × new `availableWidth` |
+
 ## Usage
 
 These composables are consumed internally by VcDataTable. If you need to interact with them, use VcDataTable's props and events:
@@ -79,10 +142,12 @@ register({
 
 ## Tips
 
-- `useTableColumns` never removes entries from `columnWidths` -- hidden columns preserve their width/order for when they reappear.
+- `useTableColumns` never removes entries from `columnState` — hidden columns preserve their weight and order for when they reappear. Use `engineOutput` (not `columnState` directly) to read computed pixel widths for rendering.
+- Call `recompute()` (returned by `useTableColumns`) whenever the container width changes to force the engine to redistribute widths without altering weights.
+- `useDataTableState` stores the v2 schema (weights, order, hidden/shown IDs). It automatically migrates v1 state (pixel-based) on the first restore. Guard against save-during-restore loops with the `isRestoring` flag.
+- `useColumnWidthEngine` functions are pure — pass immutable copies of `specs` when testing or previewing layouts without committing to state.
 - `useTableRowReorder`: `event.preventDefault()` in `dragover` MUST be called on every event or `drop` never fires.
-- `useTableColumnsResize` pins all columns to fixed widths during drag to prevent flex redistribution, then unpins on mouseup.
-- `useDataTableState` guards against save-during-restore loops with an `isRestoring` flag.
+- `useTableColumnsResize` applies DOM-level px changes during drag for 60fps performance, then commits final weights to `columnState` on mouseup. No `ResizeObserver` scaling is involved.
 - `useVirtualScroll` requires a fixed `itemSize` (row height in pixels) for accurate positioning.
 
 ## Related

package/runtime/knowledge/docs/ui/components/organisms/vc-data-table/vc-data-table.docs.md

@@ -551,6 +551,40 @@ Columns are reorderable by default. Drag a column header to a new position. Disa
 </VcDataTable>
 ```
 
+### Column Width Model
+
+VcDataTable uses a **weight-based engine** to compute exact pixel widths for every column deterministically, based on the container's available width.
+
+**How it works:**
+
+1. Developer declares initial widths via the `VcColumn` `width` prop (px, %, or omitted for auto).
+2. At runtime, these declarations become proportional weights. The engine converts weights to exact pixel values by distributing `availableWidth` proportionally.
+3. When a user resizes a column, only the weights change — the engine recomputes all pixel widths from the new weights on the next render.
+4. Clicking **Reset columns** returns all columns to their declarative hints.
+
+**`fitMode` prop** controls what happens to leftover space:
+
+| Value             | Behavior                                                                      |
+| ----------------- | ----------------------------------------------------------------------------- |
+| `"gap"` (default) | A filler pseudo-element absorbs unused space at the right end.                |
+| `"fit"`           | All column weights are normalized so columns fill the entire container width. |
+
+**Width prop contract:**
+
+| Declaration                     | Meaning                                                      |
+| ------------------------------- | ------------------------------------------------------------ |
+| `width="200"` or `:width="200"` | Initial 200 px hint                                          |
+| `width="20%"`                   | Initial hint based on 20% of available width                 |
+| `width` omitted                 | Auto — splits remaining space equally among all auto columns |
+
+After initialization the column lives in the weight model. Container resizes recompute px values without changing weights.
+
+**`minWidth` / `maxWidth`:**
+
+- `minWidth` and `maxWidth` are enforced by the engine on every computation pass.
+- Default `minWidth` is 40 px when not specified.
+- In crisis (sum of all `minWidth` values exceeds available width), the engine squeezes columns below their minimums and emits a console warning rather than breaking layout.
+
 ### Column Switcher
 
 A built-in panel lets users show/hide columns. Enabled by default when `column-switcher` is truthy.
@@ -992,6 +1026,10 @@ Persist column widths, column order, hidden columns, sort, and filters across pa
 
 **Storage key format:** `VC_DATATABLE_PRODUCT-LIST` (uppercased `state-key`).
 
+**Schema version:** The persisted state uses the **v2 schema**, which stores column weights, column order, and hidden/shown column IDs. `containerWidth` is no longer stored because weights are container-independent — the engine recomputes pixel values from weights on every mount.
+
+If an older browser tab wrote **v1** state (pixel-based widths), it is automatically migrated to v2 on first load. No manual migration is needed.
+
 Use sessionStorage instead of localStorage:
 
 ```vue
@@ -1534,9 +1572,9 @@ function onRowRemove(event: { data: Product; index: number; cancel: () => void }
 
 ## Recipes
 
-### Recipe 1: Entity List Blade
+### Recipe 1: Products List Blade
 
-A typical list blade with search, pagination, row actions, and empty states.
+A typical list blade with search, pagination, row actions, and empty states -- modeled after real vendor-portal usage.
 
 ```vue
 <template>

package/runtime/knowledge/docs/ui/components/organisms/vc-gallery/vc-gallery.docs.md

@@ -11,23 +11,23 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 
 ## Props
 
-| Prop            | Type                                                      | Default                                       | Description                                                                                                                    |
-| --------------- | --------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `layout`        | `"filmstrip" \| "grid"`                                   | `"filmstrip"`                                 | Layout mode — filmstrip shows a single scrollable row with expand/collapse; grid shows the classic multi-row auto-fill layout. |
-| `label`         | `string`                                                  | `undefined`                                   | Label text displayed in the gallery header.                                                                                    |
-| `required`      | `boolean`                                                 | `false`                                       | Shows a required indicator (`*`) on the label.                                                                                 |
-| `images`        | `ICommonAsset[]`                                          | `[]`                                          | Array of image assets to display.                                                                                              |
-| `disabled`      | `boolean`                                                 | `false`                                       | Disables all interactive actions.                                                                                              |
-| `multiple`      | `boolean`                                                 | `false`                                       | Allow selecting multiple files in upload dialog.                                                                               |
-| `loading`       | `boolean`                                                 | `false`                                       | Shows a loading overlay with spinner on the gallery.                                                                           |
-| `itemActions`   | `{ preview?: boolean; edit?: boolean; remove?: boolean }` | `{ preview: true, edit: true, remove: true }` | Per-tile action visibility.                                                                                                    |
-| `rules`         | `IValidationRules`                                        | `undefined`                                   | Validation rules for uploaded files.                                                                                           |
-| `name`          | `string`                                                  | `"Gallery"`                                   | Field name for validation messages.                                                                                            |
-| `accept`        | `string`                                                  | `undefined`                                   | Accepted file extensions.                                                                                                      |
-| `size`          | `"sm" \| "md" \| "lg"`                                    | `"md"`                                        | Tile size preset. Sizes are smaller on mobile.                                                                                 |
-| `gap`           | `number`                                                  | `8`                                           | Gap between tiles in pixels.                                                                                                   |
-| `imagefit`      | `"contain" \| "cover"`                                    | `"contain"`                                   | How images fit within tiles.                                                                                                   |
-| `thumbnailSize` | `ThumbnailSize`                                           | auto from `size`                              | Thumbnail size for tile images. Auto-mapped: sm→128x128, md→216x216, lg→348x348. Preview thumbnails use 64x64.                 |
+| Prop            | Type                                                      | Default                                       | Description                                                                                                                                                                                 |
+| --------------- | --------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `layout`        | `"filmstrip" \| "grid"`                                   | `"filmstrip"`                                 | Layout mode — filmstrip shows a single scrollable row with expand/collapse; grid shows the classic multi-row auto-fill layout.                                                              |
+| `label`         | `string`                                                  | `undefined`                                   | Label text displayed in the gallery header.                                                                                                                                                 |
+| `required`      | `boolean`                                                 | `false`                                       | Shows a required indicator (`*`) on the label.                                                                                                                                              |
+| `images`        | `ICommonAsset[]`                                          | `[]`                                          | Array of image assets to display.                                                                                                                                                           |
+| `disabled`      | `boolean`                                                 | `false`                                       | Disables all interactive actions.                                                                                                                                                           |
+| `multiple`      | `boolean`                                                 | `false`                                       | Allow selecting multiple files in upload dialog.                                                                                                                                            |
+| `loading`       | `boolean`                                                 | `false`                                       | Shows a loading overlay with spinner on the gallery.                                                                                                                                        |
+| `itemActions`   | `{ preview?: boolean; edit?: boolean; remove?: boolean }` | `{ preview: true, edit: true, remove: true }` | Per-tile action visibility.                                                                                                                                                                 |
+| `rules`         | `IValidationRules`                                        | `undefined`                                   | Validation rules for uploaded files.                                                                                                                                                        |
+| `name`          | `string`                                                  | `"Gallery"`                                   | Field name for validation messages.                                                                                                                                                         |
+| `accept`        | `string`                                                  | `"image/*"`                                   | Accepted file MIME types / extensions. Gallery is image-only by default — non-image files dropped from the OS are filtered out. Override (e.g. `"image/png,image/jpeg"`) to narrow further. |
+| `size`          | `"sm" \| "md" \| "lg"`                                    | `"md"`                                        | Tile size preset. Sizes are smaller on mobile.                                                                                                                                              |
+| `gap`           | `number`                                                  | `8`                                           | Gap between tiles in pixels.                                                                                                                                                                |
+| `imagefit`      | `"contain" \| "cover"`                                    | `"contain"`                                   | How images fit within tiles.                                                                                                                                                                |
+| `thumbnailSize` | `ThumbnailSize`                                           | auto from `size`                              | Thumbnail size for tile images. Auto-mapped: sm→128x128, md→216x216, lg→348x348. Preview thumbnails use 64x64.                                                                              |
 
 ## Events