@vc-shell/vc-app-skill 2.0.0-alpha.23 → 2.0.0-alpha.25

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [2.0.0-alpha.25](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.24...v2.0.0-alpha.25) (2026-03-25)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
+# [2.0.0-alpha.24](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.23...v2.0.0-alpha.24) (2026-03-25)
+
+
+### Features
+
+* **vc-app-skill:** add knowledge-stats script for knowledge base audit ([7a568fc](https://github.com/VirtoCommerce/vc-shell/commit/7a568fc57335d51349a644721c904586efd49273))
+* **vc-app-skill:** enrich knowledge base with When to Use sections, patterns, and sync-docs script ([c82ed63](https://github.com/VirtoCommerce/vc-shell/commit/c82ed639d748bdc8fd2d9c39435ee37baedd0563))
+* **vc-app:** add sidebar search bar for menu filtering ([72f17fc](https://github.com/VirtoCommerce/vc-shell/commit/72f17fc5b0e77e4e87457c5a29262345da50317d)), closes [#menu](https://github.com/VirtoCommerce/vc-shell/issues/menu) [#menu](https://github.com/VirtoCommerce/vc-shell/issues/menu)
 # [2.0.0-alpha.23](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.22...v2.0.0-alpha.23) (2026-03-23)
 
 

package/bin/knowledge-stats.cjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const KNOWLEDGE_DIR = path.join(__dirname, '..', 'runtime', 'knowledge');
+
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+function findFiles(dir, ext, base) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findFiles(full, ext, base));
+    } else if (entry.name.endsWith(ext)) {
+      results.push(path.relative(base, full));
+    }
+  }
+  return results.sort();
+}
+
+function analyzeDoc(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+  const title = (lines.find(l => l.startsWith('# ')) || '').replace('# ', '');
+  const hasWhenToUse = /^## When to Use/m.test(content);
+  const hasSlots = /^## Slots/m.test(content);
+  const hasQuickStart = /^## Quick Start/m.test(content);
+  const codeBlocks = (content.match(/```/g) || []).length / 2;
+  return { title, lines: lines.length, hasWhenToUse, hasSlots, hasQuickStart, codeBlocks: Math.floor(codeBlocks) };
+}
+
+function analyzePattern(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+  const title = (lines.find(l => l.startsWith('# ')) || '').replace('# ', '');
+  const sections = lines.filter(l => l.startsWith('## ')).map(l => l.replace('## ', ''));
+  const codeBlocks = (content.match(/```/g) || []).length / 2;
+  return { title, lines: lines.length, sections, codeBlocks: Math.floor(codeBlocks) };
+}
+
+// --- Docs ---
+const docsDir = path.join(KNOWLEDGE_DIR, 'docs');
+const docFiles = findFiles(docsDir, '.docs.md', docsDir);
+
+console.log(bold('\n📚 DOCS') + dim(` (${docsDir})`));
+console.log(dim('─'.repeat(80)));
+
+const docCategories = {};
+for (const f of docFiles) {
+  const cat = f.split(path.sep)[0]; // core, ui, shell, modules
+  if (!docCategories[cat]) docCategories[cat] = [];
+  docCategories[cat].push(f);
+}
+
+let totalDocs = 0;
+let withWhenToUse = 0;
+let withSlots = 0;
+let withQuickStart = 0;
+
+for (const [cat, files] of Object.entries(docCategories)) {
+  console.log(`\n  ${bold(cat.toUpperCase())} ${dim(`(${files.length} files)`)}`);
+  for (const f of files) {
+    const info = analyzeDoc(path.join(docsDir, f));
+    totalDocs++;
+    if (info.hasWhenToUse) withWhenToUse++;
+    if (info.hasSlots) withSlots++;
+    if (info.hasQuickStart) withQuickStart++;
+
+    const flags = [
+      info.hasWhenToUse ? green('WtU') : red('WtU'),
+      info.hasSlots ? green('Slt') : dim('Slt'),
+      info.hasQuickStart ? green('QS') : dim('QS'),
+    ].join(' ');
+
+    const name = info.title || path.basename(f, '.docs.md');
+    console.log(`    ${flags}  ${dim(`${String(info.lines).padStart(4)}L ${String(info.codeBlocks).padStart(2)}ex`)}  ${name}`);
+  }
+}
+
+console.log(dim('\n─'.repeat(80)));
+console.log(`  Total: ${bold(totalDocs)} docs | When to Use: ${withWhenToUse}/${totalDocs} | Slots: ${withSlots}/${totalDocs} | Quick Start: ${withQuickStart}/${totalDocs}`);
+
+// --- Patterns ---
+const patternsDir = path.join(KNOWLEDGE_DIR, 'patterns');
+const patternFiles = findFiles(patternsDir, '.md', patternsDir).filter(f => f !== '.gitkeep');
+
+console.log(bold('\n🧩 PATTERNS') + dim(` (${patternsDir})`));
+console.log(dim('─'.repeat(80)));
+
+for (const f of patternFiles) {
+  const info = analyzePattern(path.join(patternsDir, f));
+  console.log(`  ${dim(`${String(info.lines).padStart(4)}L ${String(info.codeBlocks).padStart(2)}ex`)}  ${bold(info.title || f)}`);
+  console.log(`         ${dim(info.sections.join(' → '))}`);
+}
+
+console.log(dim('\n─'.repeat(80)));
+console.log(`  Total: ${bold(patternFiles.length)} patterns`);
+
+// --- Examples ---
+const examplesDir = path.join(KNOWLEDGE_DIR, 'examples');
+const exampleFiles = findFiles(examplesDir, '.md', examplesDir);
+
+console.log(bold('\n📝 EXAMPLES') + dim(` (${examplesDir})`));
+console.log(dim('─'.repeat(80)));
+
+for (const f of exampleFiles) {
+  const content = fs.readFileSync(path.join(examplesDir, f), 'utf-8');
+  const lines = content.split('\n');
+  const title = (lines.find(l => l.startsWith('# ')) || '').replace('# ', '');
+  console.log(`  ${dim(`${String(lines.length).padStart(4)}L`)}  ${title || f}`);
+}
+
+console.log(dim('\n─'.repeat(80)));
+console.log(`  Total: ${bold(exampleFiles.length)} examples`);
+
+// --- Summary ---
+const totalKB = Math.round(docFiles.concat(patternFiles, exampleFiles)
+  .reduce((sum, f) => {
+    const dir = f.endsWith('.docs.md') ? docsDir : patternFiles.includes(f) ? patternsDir : examplesDir;
+    try { return sum + fs.statSync(path.join(dir, f)).size; } catch { return sum; }
+  }, 0) / 1024);
+
+console.log(bold('\n📊 SUMMARY'));
+console.log(dim('─'.repeat(80)));
+console.log(`  ${bold(totalDocs)} docs + ${bold(patternFiles.length)} patterns + ${bold(exampleFiles.length)} examples = ${bold(totalDocs + patternFiles.length + exampleFiles.length)} knowledge files (${totalKB} KB)`);
+console.log(`  Coverage: When to Use ${bold(Math.round(withWhenToUse/totalDocs*100)+'%')} | Slots ${bold(Math.round(withSlots/totalDocs*100)+'%')} | Quick Start ${bold(Math.round(withQuickStart/totalDocs*100)+'%')}`);
+console.log('');

package/bin/sync-docs.cjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const FRAMEWORK_DIR = path.join(ROOT, 'framework');
+const DOCS_DIR = path.join(__dirname, '..', 'runtime', 'knowledge', 'docs');
+
+function findDocsFiles(dir, base) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    const relPath = path.relative(base, fullPath);
+    if (entry.isDirectory()) {
+      results.push(...findDocsFiles(fullPath, base));
+    } else if (entry.name.endsWith('.docs.md')) {
+      results.push(relPath);
+    }
+  }
+  return results;
+}
+
+// Collect framework docs
+const frameworkDocs = findDocsFiles(FRAMEWORK_DIR, FRAMEWORK_DIR);
+
+let copied = 0;
+let skipped = 0;
+
+for (const relPath of frameworkDocs) {
+  const src = path.join(FRAMEWORK_DIR, relPath);
+  const dest = path.join(DOCS_DIR, relPath);
+
+  // Skip if dest is identical
+  if (fs.existsSync(dest)) {
+    const srcContent = fs.readFileSync(src);
+    const destContent = fs.readFileSync(dest);
+    if (srcContent.equals(destContent)) {
+      skipped++;
+      continue;
+    }
+  }
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  console.log(`  updated: ${relPath}`);
+  copied++;
+}
+
+// Remove docs that no longer exist in framework
+const skillDocs = findDocsFiles(DOCS_DIR, DOCS_DIR);
+let removed = 0;
+for (const relPath of skillDocs) {
+  if (!fs.existsSync(path.join(FRAMEWORK_DIR, relPath))) {
+    fs.unlinkSync(path.join(DOCS_DIR, relPath));
+    console.log(`  removed: ${relPath}`);
+    removed++;
+  }
+}
+
+console.log(`\nSync complete: ${copied} updated, ${removed} removed, ${skipped} unchanged`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.0-alpha.23",
+  "version": "2.0.0-alpha.25",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [
@@ -18,6 +18,10 @@
     "scaffolding",
     "vue3"
   ],
+  "scripts": {
+    "sync-docs": "node bin/sync-docs.cjs",
+    "knowledge-stats": "node bin/knowledge-stats.cjs"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/runtime/VERSION

@@ -1 +1 @@
-2.0.0-alpha.23
+2.0.0-alpha.25

package/runtime/agents/details-blade-generator.md

@@ -21,9 +21,10 @@ description: Generates a details blade Vue component and its singular composable
     "fields": [
       {
         "name": "string — camelCase field name",
-        "type": "string — 'string' | 'boolean' | 'number' | 'Date' | 'enum' | 'array'",
+        "type": "string — 'string' | 'text' | 'rich-text' | 'boolean' | 'number' | 'currency' | 'date-time' | 'Date' | 'enum' | 'multi-select' | 'image' | 'gallery' | 'file' | 'rating' | 'range' | 'color' | 'array'",
         "required": "boolean?",
-        "label": "string? — display label override"
+        "label": "string? — display label override",
+        "component": "string? — explicit component override (e.g., 'VcTextarea', 'VcEditor', 'VcInputCurrency'). If provided, use this instead of type-based mapping."
       }
     ],
     "isStandalone": "boolean — true if this is a workspace blade with its own URL (settings/profile page)",
@@ -54,7 +55,10 @@ Before generating, Read these files in order:
 2. `{knowledgeBase}/patterns/composable-details.md` — singular composable skeleton and rules
 3. `{knowledgeBase}/index.md` — to find relevant component docs
 
-From `index.md`, identify docs for `VcInput`, `VcSelect`, `VcSwitch`, `VcBlade`, `VcForm` and Read them from `{docsRoot}/`.
+From `index.md`, identify and Read docs from `{docsRoot}/` for:
+- **Always:** `VcBlade`, `VcForm`, `VcInput`, `VcSelect`, `VcSwitch`
+- **Based on field types present:** Read docs for each component that appears in the field type mapping below (e.g., if any field has type `text` → read `VcTextarea` docs; if `rich-text` → read `VcEditor` docs; if `currency` → read `VcInputCurrency` docs; etc.)
+- **Layout:** If 5+ fields → read `VcCard` docs; if 8+ fields → read `VcAccordion` docs
 
 ## Generation Rules
 
@@ -87,17 +91,42 @@ When `linkTo` is provided:
 
 ### Step 2: Map fields to components
 
-For each field in `fields`, determine the component and rules:
+For each field in `fields`, determine the component using this table. If the field already has a `component` property (from `/vc-app design`), use that directly. Otherwise, map from `type`:
 
 | Field type | Component | Validation rules | Notes |
 |------------|-----------|------------------|-------|
-| `string` | `VcInput` | `required` (if required) | Default input |
-| `boolean` | `VcSwitch` | none | No `Field` wrapper |
-| `number` | `VcInput type="number"` | `required\|bigint\|min_value:0` | |
-| `Date` | `VcInput type="datetime-local"` | `required` (if required) | |
-| `enum` | `VcSelect` | `required` (if required) | Needs `statusOptions` computed |
+| `string` | `VcInput` | `required` (if required) | Default for short text. Use `rules="email"` if name contains "email", `type="tel"` if phone, `type="url"` if url/website |
+| `text` | `VcTextarea` | `required` (if required) | Long text: description, notes, comments, bio, summary |
+| `rich-text` | `VcEditor` | `required` (if required) | HTML/WYSIWYG: body, content, article, template |
+| `boolean` | `VcSwitch` | none | No `Field` wrapper. Default for toggles (isActive, isEnabled) |
+| `boolean` | `VcCheckbox` | none | No `Field` wrapper. Use for consent/accept semantics (agreeTerms) |
+| `number` | `VcInput type="number"` | `required\|bigint\|min_value:0` | Plain numbers: quantity, count, age |
+| `currency` | `VcInputCurrency` | `required\|min_value:0` | Money: price, cost, amount, salary. Set `currency="USD"` (or infer from context) |
+| `date-time` | `VcDatePicker` | `required` (if required) | Preferred over `VcInput type="datetime-local"`. Calendar picker widget |
+| `Date` | `VcDatePicker` | `required` (if required) | Legacy alias — same as `date-time` |
+| `enum` | `VcSelect` | `required` (if required) | For 6+ options or dynamic options. Needs `{field}Options` computed |
+| `enum` (2-5 options) | `VcRadioGroup` | `required` (if required) | More visual for small static sets. Needs `{field}Options` array |
+| `multi-select` | `VcMultivalue` | none | Tags/multi-pick: tags, categories, roles. No `Field` wrapper needed |
+| `multi-select` (static) | `VcCheckboxGroup` | none | Few static checkboxes. Needs `{field}Options` array |
+| `rating` | `VcRating` | none | Star rating 1-5. No `Field` wrapper needed |
+| `range` | `VcSlider` | none | Numeric slider: discount, percentage. Set `:min` / `:max` |
+| `color` | `VcColorInput` | none | Color picker with hex. No `Field` wrapper needed |
+| `image` | `VcImageUpload` | none | Single image upload with preview |
+| `gallery` | `VcGallery` | none | Multi-image management grid |
+| `file` | `VcFileUpload` | none | File attachment. Set `:accept` filter for allowed extensions |
 | `array` | `VcDataTable` (inline) | none | Read-only nested table |
 
+**Field name heuristics:** When field type is plain `"string"`, upgrade based on the field name:
+- `description`, `notes`, `comment`, `bio`, `summary`, `about` → `text` (VcTextarea)
+- `body`, `content`, `html`, `article`, `template` → `rich-text` (VcEditor)
+- `price`, `cost`, `amount`, `total`, `salary`, `budget`, `fee` → `currency` (VcInputCurrency)
+- `avatar`, `logo`, `photo`, `thumbnail`, `banner` → `image` (VcImageUpload)
+- `tags`, `labels`, `categories`, `roles`, `permissions` → `multi-select` (VcMultivalue)
+- `rating`, `score`, `stars` → `rating` (VcRating)
+- `color`, `colour`, `brandColor` → `color` (VcColorInput)
+
+Refer to `details-blade-pattern.md` → "Field Type → Component Mapping" section for full template examples of each component.
+
 ### Step 3: Generate the singular composable
 
 Write to: `{targetDir}/composables/use{EntityName}/index.ts`
@@ -175,12 +204,35 @@ Follow `details-blade-pattern.md` template exactly:
 
 **Template:**
 - `<VcBlade :loading="loading" :modified="modified" :title="title" :toolbar-items="bladeToolbar" width="50%">`
-- `<VcContainer><VcForm><VcRow>`
-- For each non-array, non-boolean field: wrap in `<Field>` with `v-slot`, `name`, `:model-value`, `rules`
-- For boolean fields: `<VcSwitch v-model="entity.{name}">` without Field wrapper
+- `<VcContainer>`
+
+**Banners (contextual alerts):**
+- Add `<VcBanner>` at the top of the form (before `<VcForm>`) for state-dependent alerts. See `details-blade-pattern.md` → "Contextual Banners Pattern".
+- Use `variant="info"` for creation hints, `variant="danger"` for errors, `variant="warning"` for missing data.
+- Example: `<VcBanner v-if="!entity.id" variant="info" icon="lucide-lightbulb" icon-size="l">{{ $t("...CREATE_HINT") }}</VcBanner>`
+
+**Form fields:**
+- `<VcForm>` wraps all editable fields
+- Use the component determined in Step 2 for each field. Refer to `details-blade-pattern.md` for full template examples of each component type.
+- Components that need `<Field>` wrapper (for validation): `VcInput`, `VcTextarea`, `VcEditor`, `VcDatePicker`, `VcSelect`, `VcRadioGroup`, `VcInputCurrency`, `VcFileUpload`
+- Components that do NOT need `<Field>` wrapper: `VcSwitch`, `VcCheckbox`, `VcMultivalue`, `VcRating`, `VcSlider`, `VcColorInput`, `VcImageUpload`, `VcGallery`
 - For array fields: separate `<VcRow>` with inline `<VcDataTable>`
 - Use i18n keys: `{i18nPrefix}.FIELDS.{FIELD_NAME_UPPER}.LABEL` and `.PLACEHOLDER`
 
+**Read-only fields (VcField):**
+- For fields that should display data without editing (computed values, IDs, timestamps on existing entities), use `<VcField>` instead of `<VcInput>`:
+  ```vue
+  <VcField :label="$t('...')" :model-value="entity.number" orientation="horizontal" :aspect-ratio="[1, 2]" copyable type="text" />
+  ```
+- See `details-blade-pattern.md` → "Read-Only Details Pattern".
+- Use `VcField` when: the blade is view-only, or for specific non-editable fields within an editable form (order number, creation date).
+
+**Layout — ALWAYS use VcCard sections:**
+- Group related fields in `<VcCard :header="$t('...')">` sections. This is how real vc-shell apps are built — flat forms without cards look unfinished.
+- If 3+ fields → at minimum 1 card. If 5+ fields → 2+ cards grouped by topic.
+- If 8+ fields → consider `<VcAccordion>` for secondary/advanced fields.
+- **Grid:** Use `<VcRow><VcCol>` to arrange short fields in 2 columns. Wide fields (`VcTextarea`, `VcEditor`, `VcGallery`, `VcDataTable`) span full width.
+
 **Close guard:**
 ```ts
 onBeforeClose(async () => {
@@ -217,9 +269,18 @@ Before completing, verify:
 - [ ] `onBeforeClose` guard is present if `modified` is used
 - [ ] After save/delete: `callParent("reload")` before `closeSelf()`
 - [ ] `disabled` on toolbar items is a `computed(...)`, not a plain boolean
-- [ ] `boolean` fields use `VcSwitch` without a `Field` wrapper
-- [ ] `enum` fields use `VcSelect` with `option-value` and `option-label` props
+- [ ] `boolean` fields use `VcSwitch` (or `VcCheckbox` for consent) without a `Field` wrapper
+- [ ] `enum` fields use `VcSelect` (6+ options) or `VcRadioGroup` (2-5 options) with `option-value` and `option-label` props
+- [ ] `text` fields use `VcTextarea`, NOT `VcInput`
+- [ ] `rich-text` fields use `VcEditor`, NOT `VcTextarea`
+- [ ] `currency` fields use `VcInputCurrency`, NOT `VcInput type="number"`
+- [ ] `date-time` fields use `VcDatePicker`, NOT `VcInput type="datetime-local"`
+- [ ] `multi-select` fields use `VcMultivalue` or `VcCheckboxGroup`
+- [ ] `image` fields use `VcImageUpload`, `gallery` uses `VcGallery`, `file` uses `VcFileUpload`
+- [ ] `rating` fields use `VcRating`, `range` uses `VcSlider`, `color` uses `VcColorInput`
 - [ ] `array` fields render as inline `VcDataTable` in a separate `VcRow`
+- [ ] Components without `Field` wrapper: `VcSwitch`, `VcCheckbox`, `VcMultivalue`, `VcRating`, `VcSlider`, `VcColorInput`, `VcImageUpload`, `VcGallery`
+- [ ] Wide components (`VcTextarea`, `VcEditor`, `VcGallery`, `VcDataTable`) span full width, not in 2-col grid
 - [ ] `useModificationTracker` is used in composable (not blade)
 - [ ] `resetModificationState()` called after fetch AND after create/update
 - [ ] No `useI18n` import in the composable file

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 785583032 on 2026-03-23T13:30:02.724Z
+Synced from framework at commit 99a2f022b on 2026-03-25T11:57:14.169Z

package/runtime/knowledge/docs/core/api/platform.docs.md

@@ -6,10 +6,17 @@ Auto-generated TypeScript API client for the VirtoCommerce Platform REST API. Ge
 
 Communicating with the VirtoCommerce platform backend requires typed HTTP client classes that match the platform's REST endpoints. Rather than manually writing fetch calls or Axios requests, the framework provides auto-generated client classes that handle URL construction, request serialization, response deserialization, and authentication token injection.
 
-Each API client class extends `AuthApiBase`, which automatically attaches the Bearer token to every request. The clients are generated by NSwag from the platform's Swagger/OpenAPI specification and should not be edited manually -- any manual changes will be overwritten during regeneration.
+Each API client class extends `AuthApiBase`, which automatically attaches the Bearer token to every request. Data model types (DTOs, Commands, Queries) are generated as **interfaces** (not classes), so they cannot be instantiated with `new` -- use object literals with type annotations instead. The clients are generated by NSwag from the platform's Swagger/OpenAPI specification and should not be edited manually -- any manual changes will be overwritten during regeneration.
 
 **File:** `platform.ts` (auto-generated, do not edit manually)
 
+## When to Use
+
+- Call platform-level REST endpoints (security, settings, notifications, modules, dynamic properties) from typed TypeScript clients
+- Access platform DTOs (`ApplicationUser`, `PushNotification`, `Role`, `Permission`, etc.) as typed interfaces
+- Combine with `useApiClient` for automatic token management and caching
+- When NOT to use: for domain-module APIs (orders, catalog, inventory) -- use their own generated clients instead; for third-party APIs -- use `fetch` or Axios directly
+
 ## API Clients
 
 All clients extend `AuthApiBase` and accept an optional `baseUrl` and `http` fetch implementation.
@@ -30,10 +37,10 @@ All clients extend `AuthApiBase` and accept an optional `baseUrl` and `http` fet
 | `SecurityClient` | User management, roles, permissions, password operations |
 | `SettingClient` | Platform settings CRUD |
 
-## Key DTOs
+## Key DTOs (Interfaces)
 
-| Class | Description |
-|-------|-------------|
+| Interface | Description |
+|-----------|-------------|
 | `PushNotification` | Push notification payload: `id`, `title`, `notifyType`, `isNew`, `finished`, etc. |
 | `PushNotificationSearchCriteria` | Search criteria for notification queries |
 | `ApplicationUser` | Platform user with roles, permissions, logins |
@@ -68,7 +75,7 @@ The `getBaseUrl` method always returns an empty string, meaning API calls are re
 import { PushNotificationClient, PushNotificationSearchCriteria } from "@vc-shell/framework";
 
 const client = new PushNotificationClient();
-const criteria = new PushNotificationSearchCriteria({ take: 20, skip: 0 });
+const criteria: PushNotificationSearchCriteria = { take: 20, skip: 0 };
 const result = await client.searchPushNotification(criteria);
 
 console.log(`Found ${result.totalCount} notifications`);
@@ -131,10 +138,10 @@ const client = new SettingClient();
 const settings = await client.getValues(["VirtoCommerce.Notifications.SendGrid.ApiKey"]);
 
 // Update a setting
-const entry = new ObjectSettingEntry({
+const entry: ObjectSettingEntry = {
   name: "MyModule.SomeSetting",
   value: "new-value",
-});
+};
 await client.update([entry]);
 ```
 

package/runtime/knowledge/docs/core/blade-navigation/blade-nav-composables.docs.md

@@ -10,6 +10,12 @@ Blade navigation manages an ordered stack of blade descriptors (plain data objec
 2. **useBladeMessaging** -- inter-blade communication: parent-child method calls.
 3. **useBladeNavigation** (adapter) -- legacy API adapter that maps the old index-based API onto the new ID-based stack and messaging systems.
 
+## When to Use
+
+- Build or extend the blade navigation infrastructure itself (plugin authors, framework internals)
+- Need direct access to the blade stack state machine (`useBladeStack`) or inter-blade messaging (`useBladeMessaging`)
+- When NOT to use: for everyday blade operations in modules -- prefer `useBlade()` from `core/composables/useBlade/`, which wraps these low-level composables with a cleaner, context-aware API
+
 ## Exports
 
 ```typescript

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

@@ -2,6 +2,12 @@
 
 Creates a typed API client instance for communicating with VirtoCommerce platform APIs. The composable accepts a generated client class constructor and returns an async factory function that produces a configured, authenticated client. Base URL resolution and authentication token injection are handled automatically.
 
+## When to Use
+
+- Instantiate a generated VirtoCommerce API client with automatic authentication and base-URL resolution
+- Pair with `useAsync` for loading/error state on every API call in a blade or composable
+- When NOT to use: for third-party or non-platform APIs that do not extend `AuthApiBase` -- use `fetch` or Axios directly
+
 ## Quick Start
 
 ```typescript

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

@@ -0,0 +1,149 @@
+# useAssetsManager
+
+High-level composable for managing asset arrays (images, documents, files). Wraps upload, remove, reorder, and metadata editing operations, mutating a reactive ref directly — no manual wiring needed.
+
+Replaces the low-level `useAssets()` composable which required building handler objects manually.
+
+## When to Use
+
+- Manage a list of images/assets on an entity (product, offer, user profile, seller)
+- Need upload, remove, reorder, and edit-metadata on an asset array
+- Want to bind directly to `VcGallery` events without boilerplate
+
+## API
+
+```typescript
+import { useAssetsManager } from "@vc-shell/framework";
+
+const assets = useAssetsManager(ref, options);
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `source` | `Ref<AssetLike[] \| undefined \| null>` | Reactive ref to the asset array. Accepts `ref()`, `toRef()`, or `computed({ get, set })`. `undefined`/`null` values are treated as empty array. The composable holds an internal copy and syncs both ways. |
+| `options` | `UseAssetsManagerOptions` | Configuration (see below) |
+
+### Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `uploadPath` | `() => string` | Yes | Upload destination path (function — evaluated at upload time) |
+| `confirmRemove` | `() => Promise<boolean> \| boolean` | No | Called before remove. Return `false` to cancel. Omit for silent remove. |
+| `assetKey` | `string` | No | Key for matching items (default: `"url"`) |
+| `concurrency` | `number` | No | Max concurrent uploads (default: 4) |
+
+### Return (`UseAssetsManagerReturn`)
+
+| Property | Type | Description |
+|---|---|---|
+| `items` | `Ref<AssetLike[]>` | Reactive asset array (internal ref, safe to bind to templates) |
+| `upload` | `(files: FileList, startingSortOrder?: number) => Promise<void>` | Upload files, append to array |
+| `remove` | `(item: AssetLike) => Promise<void>` | Remove single item (with confirmation if configured) |
+| `removeMany` | `(items: AssetLike[]) => Promise<void>` | Remove multiple items (one confirmation for batch) |
+| `reorder` | `(items: AssetLike[]) => void` | Replace array with new order |
+| `updateItem` | `(item: AssetLike) => void` | Update single item metadata by `assetKey` |
+| `loading` | `ComputedRef<boolean>` | True during upload |
+
+## Usage Examples
+
+### Basic — gallery with confirmation
+
+```typescript
+import { useAssetsManager } from "@vc-shell/framework";
+import { toRef } from "vue";
+
+const assets = useAssetsManager(
+  computed({
+    get: () => offer.value.images ?? [],
+    set: (val) => { offer.value.images = val; },
+  }),
+  {
+    uploadPath: () => `offers/${offer.value?.id ?? "new"}`,
+    confirmRemove: () => showConfirmation(t("OFFERS.ALERTS.IMAGE_DELETE")),
+  },
+);
+```
+
+```html
+<VcGallery
+  :images="assets.items.value"
+  @upload="assets.upload"
+  @sort="assets.reorder"
+  @remove="assets.remove"
+  @edit="onGalleryItemEdit"
+/>
+```
+
+### Single image (photo/logo)
+
+Wrap a single value in a computed array:
+
+```typescript
+const photoAssets = computed({
+  get: () => user.value?.iconUrl ? [{ url: user.value.iconUrl }] : [],
+  set: (val) => { user.value!.iconUrl = val[0]?.url; },
+});
+
+const photo = useAssetsManager(photoAssets, {
+  uploadPath: () => `users/${user.value?.id}`,
+});
+```
+
+### Passing to AssetsManager blade
+
+When passing `useAssetsManager` through blade options, **always wrap with `markRaw()`**:
+
+```typescript
+import { markRaw } from "vue";
+import { useBlade, useAssetsManager } from "@vc-shell/framework";
+
+const { openBlade } = useBlade();
+
+const assets = useAssetsManager(productAssetsRef, {
+  uploadPath: () => `/catalog/${product.value?.id}`,
+  confirmRemove: () => showConfirmation("Delete selected assets?"),
+});
+
+openBlade({
+  name: "AssetsManager",
+  options: {
+    manager: markRaw(assets),  // IMPORTANT: prevents reactive proxy unwrap
+    disabled: !canEdit.value,
+  },
+});
+```
+
+**Why `markRaw`?** Blade descriptors are stored in `ref<BladeDescriptor[]>()`, which creates a deep reactive proxy. Vue auto-unwraps `Ref` values inside reactive objects — so `manager.items` would become a plain array instead of `Ref<AssetLike[]>`, breaking `.value` access. `markRaw()` tells Vue to skip this object, keeping Refs intact.
+
+## Reactivity Model
+
+The composable holds an **internal ref** (`_items`) that is the source of truth for the UI:
+
+1. **Source → internal**: A `watch` syncs changes from the source ref (e.g., when parent reloads data)
+2. **Mutations → internal → source**: Every operation (`upload`, `remove`, `reorder`, `updateItem`) updates `_items` first, then writes back to the source via `_sync()`
+
+This two-way sync avoids reactivity issues when the source is a `WritableComputed` wrapping deeply nested properties (e.g., `item.value.productData.assets`).
+
+## Types
+
+### `AssetLike`
+
+Minimal structural contract compatible with any domain image type:
+
+```typescript
+interface AssetLike {
+  url?: string;
+  name?: string;
+  sortOrder?: number;
+  [key: string]: any;  // compatible with Image, ProductImage, Asset, etc.
+}
+```
+
+## Related
+
+- `framework/modules/assets-manager/` — AssetsManager blade (table UI for managing assets)
+- `framework/modules/assets/` — AssetsDetails blade (single asset editing)
+- `framework/ui/components/organisms/vc-gallery/` — VcGallery component
+- `framework/core/composables/useAssets/` — deprecated low-level composable

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

@@ -8,6 +8,13 @@ When the returned `action` is called, `useAsync` automatically:
 3. On failure: parses the error into a `DisplayableError`, stores it in `error`, logs it, optionally shows a toast notification, and re-throws
 4. Sets `loading` to `false` (success or failure)
 
+## When to Use
+
+- Wrap any async operation (API calls, saves, deletes) with reactive `loading` and `error` state
+- Get automatic error parsing, toast notifications, and re-throw behavior for free
+- Combine with `useLoading` when a blade has multiple independent async operations
+- When NOT to use: for synchronous logic -- just use a regular function; for fire-and-forget operations where you do not need loading/error tracking
+
 ## Quick Start
 
 ```typescript

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

@@ -4,6 +4,13 @@ Unified composable for blade navigation, identity, communication, guards, and er
 
 `useBlade()` works **everywhere**: inside blades it provides the full API (identity, navigation, communication, guards, errors); outside blades (dashboard cards, notification templates, composables) it provides navigation only (`openBlade`). Blade-specific methods throw a descriptive runtime error if called outside blade context.
 
+## When to Use
+
+- Open, close, replace, or cover blades from any component (blade, dashboard widget, toolbar handler)
+- Read blade identity (`param`, `options`, `id`) or register close guards inside a blade
+- Communicate between parent and child blades via `callParent` / `exposeToChildren`
+- When NOT to use: for low-level stack manipulation or custom navigation plugins -- use the blade-navigation composables (`useBladeStack`, `useBladeMessaging`) directly
+
 ## Quick Start
 
 ```vue