diff --git a/plugins/ui5/README.md b/plugins/ui5/README.md
index c73b603..8494784 100644
--- a/plugins/ui5/README.md
+++ b/plugins/ui5/README.md
@@ -108,6 +108,17 @@ Authoritative development guidelines for all UI5 table controls (SAPUI5 1.136+ L
 - **Personalization** - `sap.m.p13n.Engine` integration
 - **Cell templates & alignment** - Type-based alignment and model type namespace rules
 
+#### ui5-fiori-guidelines
+
+Picks the correct SAP Fiori / UI5 control for a use case — and stops the wrong one — giving both the SAPUI5 class and the `ui5-*` web component tag:
+
+- **Wrong → Right mapping** - The exact wrong control mapped to the right one (e.g. `sap.m.Bar` used as an app header → `sap.f.ShellBar` / `ui5-shellbar`)
+- **Use-case → Component map** - "App-level navigation" → `ShellBar`; "list → detail split" → `FlexibleColumnLayout`
+- **Table selection by data, not looks** - Responsive vs Grid vs Analytical vs Tree, and when a responsive table degrades
+- **Decision-first reference files** - Per control: when to use, when NOT (with the alternative), machine-checkable rules, gotchas — across actions, inputs, containers, navigation, lists/tables, display, messages, AI, and upload
+- **Critical one-liners** - One emphasized button per page, icon-only buttons need a tooltip, links navigate / buttons act, Popover is non-modal / Dialog is modal
+- **Maintenance** - `REFRESH.md` documents an agent-driven re-sync against SAP sources with human review (no unattended writes)
+
 ---
 
 ## Installation
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/README.md b/plugins/ui5/skills/ui5-fiori-guidelines/README.md
new file mode 100644
index 0000000..2559b9a
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/README.md
@@ -0,0 +1,50 @@
+# SAP Fiori Component Selection Skill
+
+Picks the correct SAP Fiori / UI5 control for a use case — and stops the wrong one (a `sap.m.Bar` used as an
+app header, a responsive table used for 5,000 rows). This skill catches those before the code ships.
+
+Built for AI coding assistants working alongside application developers.
+
+## What it does
+
+- **Wrong → Right mapping.** The exact wrong control → the correct one, with both the SAPUI5 class and the `ui5-*` web component tag.
+- **Use-case → Component map.** "I need to show app navigation" → `ShellBar`, not `Bar`.
+- **Decision-first reference files.** Every component: when to use, when NOT (with the alternative), machine-checkable rules, gotchas. No anatomy, no fluff.
+
+## Usage
+
+Starts automatically on SAP Fiori / UI5 questions and on code containing UI5 control names. Example triggers:
+
+- "How do I build a navigation bar in Fiori?"
+- "I'm using sap.m.Bar for my app header" (→ ShellBar)
+- "Which table should I use for 5,000 rows?"
+- "Which control for a brief success confirmation?" (→ MessageToast)
+
+## Contents
+
+`SKILL.md` is the router: Wrong→Right table, Use-case→Component map, reference routing, critical one-liners.
+
+| Reference file | Topic |
+|---|---|
+| `component-selection.md` | Full wrong→right + table-type decision + long tail |
+| `theming-tokens.md` | CSS tokens, semantic colors, density tiers |
+| `ui-actions.md` | Buttons, links, toggle/segmented/menu buttons |
+| `ui-inputs.md` | Inputs, selects, combo/multi, pickers, filter bar, value help |
+| `ui-containers.md` | Cards, dialog, popover, shell bar, toolbars, user menu |
+| `ui-navigation.md` | Icon tab bar, tab container, side nav, shell search, breadcrumbs |
+| `ui-lists-tables.md` | Responsive / Grid / Analytical / Tree table, Grid List, List |
+| `ui-display.md` | Avatar, progress, busy, illustrated message |
+| `ui-messages.md` | Message strip / box / toast / popover |
+| `ui-ai.md` | AI button, guided/quick prompts, regenerate, local AI notice |
+| `ui-upload.md` | File Uploader vs Upload Set |
+| `implementation-checklist.md` | Code-review checklist for a built app |
+
+## Maintenance
+
+`REFRESH.md` documents the repeatable, agent-driven process to re-sync against latest SAP sources
+(diff + human review, no unattended writes).
+
+## Version
+
+Source: SAP Fiori Design Guidelines. Component tags verified against `ui5.sap.com`,
+`sap.github.io/ui5-webcomponents`, and the UI5 Web Components MCP server.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/REFRESH.md b/plugins/ui5/skills/ui5-fiori-guidelines/REFRESH.md
new file mode 100644
index 0000000..d41aa7e
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/REFRESH.md
@@ -0,0 +1,66 @@
+# Refreshing this skill
+
+The skill is a snapshot of SAP Fiori guidelines + UI5 APIs. Sources change. This is the repeatable
+process to re-sync it and keep it up to date. **No unattended writes** — the process reports drift and proposes edits; a
+human reviews and applies.
+
+## Authoritative sources
+
+| Source | URL | Reachable? | Use for |
+|---|---|---|---|
+| Fiori Design Guidelines | `sap.com/design-system/fiori-design-web/` | Often 403s automated fetches | Human reference for design rules, when-to-use |
+| SAPUI5 API | `ui5.sap.com/` | Yes | Verifying `sap.*` class names, deprecations |
+| UI5 Web Components | `sap.github.io/ui5-webcomponents/` | Yes | Verifying `ui5-*` tags, slots, properties |
+| Theming tokens | `github.com/SAP/theming-base-content` | Yes (raw.githubusercontent.com) | CSS token names + values |
+| UI5 Web Components MCP server | local MCP (`get_component_api`, `get_doc`, `list_docs`) | Yes | Fastest tag/API verification + V2→V3 migration/deprecations |
+
+The design portal blocks scrapers; treat it as a human-read source. Everything machine-checkable
+(control names, tags, tokens) comes from the API sources and the MCP server.
+
+## Refresh process (agent-driven diff + review)
+
+Run one agent per file group so context stays scoped. Each agent:
+1. Reads its current reference file(s).
+2. Fetches the matching live source(s) above. For every `ui5-*` tag, calls MCP `get_component_api`
+   to confirm it still exists and its package hasn't moved. For tokens, fetches
+   `theming-base-content`. For `sap.*` classes, checks `ui5.sap.com`.
+3. Diffs live vs current and **reports** — new/renamed/deprecated controls, changed tags or
+   packages, changed token values, new wrong-component pitfalls, dead links — plus a proposed edit
+   list. It does **not** write.
+4. A human reviews the report and applies edits.
+
+File groups: `ui-actions/inputs/navigation` · `ui-containers/lists-tables` ·
+`ui-display/messages/ai/upload` ·
+`SKILL.md + component-selection/theming-tokens`.
+
+Can be launched as a Workflow (one agent per group, results collected) or via the Agent tool.
+
+## Invariants every refresh must preserve
+
+- Decision-first contract per section: **SAPUI5 + Web Component identifiers · Use when · Do NOT use when → alternative · Rules · Gotchas.** No anatomy, no state prose.
+- Every control names both framework identifiers, or explicitly states "none" when one doesn't exist.
+- SKILL.md body stays a router: Wrong→Right table, Use-case→Component map, routing table, one-liners. Keep it under ~200 lines; keep `description` under ~1,536 chars.
+- Tone: short, concise, no fluff.
+
+## Verification after any refresh
+
+```bash
+# 1. No scrape artifacts or dead/internal links (must return nothing)
+grep -rnE '\+-+x-+\+|:badge|:decline:|:overflow:|:bell:|builder-prospect|ui5\.github\.io|wiki\.one\.int\.sap|&#x[0-9a-f]+;|Section Metadata|external_only' references/ SKILL.md
+
+# 2. Every ui-*.md component section names an identifier (spot-check)
+grep -rnE '`sap\.|`ui5-' references/ui-*.md | head
+
+# 3. SKILL.md budget
+wc -l SKILL.md   # target < 200
+```
+- For each `ui5-*` tag referenced anywhere, confirm via MCP `get_component_api` that it resolves
+  (this catches invented tags like the non-existent `ui5-menu-button`).
+- Trigger test in a fresh session: "how do I build a navigation bar in Fiori", "I'm using sap.m.Bar
+  for my header", "which table for 5000 rows", "design an object page" should each surface the right
+  guidance.
+
+## Version stamping
+
+- Record the SAP Fiori guideline version and refresh date in `README.md`.
+- On material change, bump the version line in `README.md`.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/SKILL.md b/plugins/ui5/skills/ui5-fiori-guidelines/SKILL.md
new file mode 100644
index 0000000..fd45882
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: ui5-fiori-guidelines
+description: Picks the correct SAP Fiori / UI5 control for a use case and prevents the usage of the wrong one. Use when choosing between UI5 controls, building or reviewing code with sap.m.*, sap.f.*, sap.uxap.*, sap.ui.table.*, or ui5-* web components (XML views, fragments, controllers, manifest.json). Catches the classic wrong-component mistakes that cause false usage, for example: sap.m.Bar used as a navigation bar / app header (use sap.f.ShellBar), a List used as side navigation (use sap.f.SideNavigation), a responsive sap.m.Table used for large or aggregated data (use sap.ui.table.Table / AnalyticalTable), a Dialog used for a plain error (use MessageBox or MessageStrip), a Page used for object details (use sap.uxap.ObjectPageLayout).
+---
+
+# SAP Fiori Component Selection
+
+The job of this skill: pick the right control for the task or plan the correct Fiori application architecture / UX.
+
+Two frameworks, two names for the same component. Always give both:
+- **SAPUI5** — `sap.m.*`, `sap.f.*`, `sap.uxap.*`, `sap.ui.table.*` (XML views, S/4HANA, Fiori Elements).
+- **UI5 Web Components** — `ui5-*` (React/Vue/Angular, framework-agnostic).
+
+Not every control exists in both. Where it doesn't, say so — don't invent a tag.
+
+## Wrong → Right
+
+| Developer says / writes | WRONG | RIGHT (SAPUI5 · Web Component) | Why |
+|---|---|---|---|
+| "navigation bar", "app header", "top bar" | `sap.m.Bar` | `sap.f.ShellBar` · `ui5-shellbar` | Bar is a generic toolbar container; ShellBar is the app-level header (logo, search, notifications, profile, Joule). |
+| "side menu", "left navigation" | `sap.m.List` | `sap.f.SideNavigation` · `ui5-side-navigation` | List has no nav semantics, no expand/collapse, no selection state. WC must sit in `ui5-navigation-layout`. |
+| "tabs on a page", "sections" | `sap.m.TabContainer` | `sap.m.IconTabBar` · `ui5-tabcontainer` | TabContainer is for editable multi-document (like browser tabs); IconTabBar is in-page section/filter nav. |
+| "header with title + actions on a detail page" | `sap.m.Bar` / `sap.m.Page` | `sap.uxap.ObjectPageLayout` · (no WC) | ObjectPage provides the standard header + anchored sections; Bar/Page don't compose with it. |
+| "error popup", "confirmation dialog" | hand-built `sap.m.Dialog` | `sap.m.MessageBox` · `ui5-dialog` + `ui5-message-strip` | MessageBox gives semantic types (Error/Warning/Success/Confirm) and buttons for free. |
+| "inline error / warning banner" | `sap.m.Dialog` / `MessageBox` | `sap.m.MessageStrip` · `ui5-message-strip` | Dialogs interrupt; strips are non-blocking, stay on the page. |
+| "brief success confirmation" | `sap.m.MessageStrip` / `Dialog` | `sap.m.MessageToast` · (no WC — use `ui5-toast`) | Toast auto-dismisses; a strip persists and clutters. |
+| "many validation errors at once" | repeated `MessageStrip` | `sap.m.MessagePopover` · (no direct WC) | One entry point, grouped by severity, navigable. |
+| "big data table", "needs totals/subtotals" | `sap.m.Table` | `sap.ui.table.AnalyticalTable` · (no WC) | Responsive table has no aggregation/freeze and degrades past ~200 rows. |
+| "grid table with thousands of rows" | `sap.m.Table` | `sap.ui.table.Table` · (no WC — `ui5-table` ≠ grid table) | `ui5-table` is popin-capable but not a grid/analytical replacement. |
+| "hierarchy / tree" | grouped `AnalyticalTable` | `sap.ui.table.TreeTable` · (no WC) | Grouping clusters by value; TreeTable models real parent-child nodes. |
+| "master–detail", "list + details side by side" | nested routes / custom CSS columns | `sap.f.FlexibleColumnLayout` · (no WC) | FCL handles column transitions, breakpoints, and back nav. |
+| "object detail page" | `sap.m.Page` | `sap.uxap.ObjectPageLayout` · (no WC) | Page has no anchored section navigation. |
+| "menu button / split button (WC)" | `ui5-menu-button` | `ui5-button` + `ui5-menu` · `sap.m.MenuButton` | No standalone `ui5-menu-button` exists. |
+| "secondary button (WC)" | `design="Ghost"` | `design="Transparent"` · `sap.m.Button type="Transparent"` | `Ghost` is legacy SAPUI5-only; WC has no Ghost design. |
+| "on/off setting" | `sap.m.CheckBox` for immediate effect | `sap.m.Switch` · `ui5-switch` | Switch = immediate effect; CheckBox = confirmed-on-save. |
+| "pick one from a long list" | `sap.m.Select` | `sap.m.ComboBox` / value help · `ui5-combobox` | Select is for short fixed lists (~2–12); ComboBox filters/free-texts. |
+| "pick a date" | `sap.m.Input` | `sap.m.DatePicker` · `ui5-date-picker` | Input has no calendar, parsing, or validation. |
+
+## Use case → Component
+
+| I need to… | Use (SAPUI5 · WC) | NOT |
+|---|---|---|
+| App-level nav: logo, search, notifications, profile | `sap.f.ShellBar` · `ui5-shellbar` | Bar, Toolbar |
+| Left-hand navigation menu | `sap.f.SideNavigation` · `ui5-side-navigation` | List, VerticalLayout |
+| Navigate between facets of one object | `sap.m.IconTabBar` · `ui5-tabcontainer` | TabContainer, SegmentedButton |
+| Switch a small set of views (2–3) | `sap.m.SegmentedButton` · `ui5-segmented-button` | RadioButtonGroup, Select |
+| Persistent page-level error/warning | `sap.m.MessageStrip` · `ui5-message-strip` | MessageBox, Dialog |
+| One-time success confirmation | `sap.m.MessageToast` · `ui5-toast` | MessageStrip, Dialog |
+| Show entity details (header + sections) | `sap.uxap.ObjectPageLayout` | Page, Panel |
+| List → detail split layout | `sap.f.FlexibleColumnLayout` | custom columns |
+| Empty / no-data / error state | `sap.m.IllustratedMessage` · `ui5-illustrated-message` | plain Text/Label |
+| Contextual detail without leaving page | `sap.m.Popover` · `ui5-popover` | Dialog (that's modal) |
+| Personalize 20+ table columns | `sap.m.p13n.Popup` · (no WC) | ViewSettingsDialog |
+
+## Reference files — read on demand
+
+| Topic | File | Read when |
+|---|---|---|
+| Full wrong→right + long tail, table-type decision | `references/component-selection.md` | Any control-choice question not fully answered above |
+| CSS tokens, semantic colors, density tiers | `references/theming-tokens.md` | Colors, theming, cozy/compact/condensed |
+| Buttons, links, toggle/segmented/menu buttons | `references/ui-actions.md` | Choosing an action control |
+| Inputs, selects, combo/multi, pickers, filter bar | `references/ui-inputs.md` | Form/input/filter design |
+| Containers: cards, dialog, popover, shell bar, toolbars | `references/ui-containers.md` | Overlays, cards, shell structure |
+| Navigation: icon tab bar, side nav, shell search | `references/ui-navigation.md` | Tab/section/side navigation |
+| Tables and lists (Responsive/Grid/Analytical/Tree/List) | `references/ui-lists-tables.md` | Choosing a table or list |
+| Avatar, progress, busy, illustrated message | `references/ui-display.md` | Status/empty-state display |
+| Message strip / popover / box / toast | `references/ui-messages.md` | Message pattern and placement |
+| AI/Joule: AI button, guided/quick prompts, notice | `references/ui-ai.md` | AI-powered features |
+| Upload (File Uploader vs Upload Set) | `references/ui-upload.md` | File upload |
+| Implementation review checklist | `references/implementation-checklist.md` | Reviewing a built app |
+
+## Rules that stop the most mistakes
+
+- **One emphasized/primary button per page or dialog.** Everything else is Default/Transparent.
+- **Icon-only buttons need a tooltip** and a recognizable, worldwide-consistent icon metaphor.
+- **App header = ShellBar, never Bar.** Bar is a content-area toolbar.
+- **Button text is an imperative verb** — Save, Edit, Create. Not "OK to save?".
+- **Table choice is by data, not looks:** ≤~200 rows → Responsive; large/desktop → Grid; totals → Analytical; hierarchy → Tree.
+- **Links navigate, buttons act.** Don't use a Button to go to a page or a Link to submit.
+- **Popover is non-modal contextual; Dialog is modal.** Don't use a Popover for anything requiring focus or confirmation.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/component-selection.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/component-selection.md
new file mode 100644
index 0000000..860c6af
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/component-selection.md
@@ -0,0 +1,155 @@
+# Component Selection
+
+The full wrong to right map. SKILL.md carries the high-frequency subset; this file carries the long
+tail and the decision criteria. Every entry gives both framework identifiers, or says when one
+doesn't exist.
+
+## Contents
+- [Tables — the biggest offender](#tables--the-biggest-offender)
+- [Inputs & selection](#inputs--selection)
+- [Actions](#actions)
+- [Navigation & structure](#navigation--structure)
+- [Overlays & messaging](#overlays--messaging)
+- [Controls with no Web Component](#controls-with-no-web-component)
+
+---
+
+## Tables — the biggest offender
+
+Choose by **data shape**, never by appearance. This single decision causes more wrong-component
+usage than anything else.
+
+| Need | Control | SAPUI5 | Web Component |
+|---|---|---|---|
+| ≤ ~200 rows, mobile + desktop, simple | Responsive Table | `sap.m.Table` | `ui5-table` (popin mode) |
+| Large data, many columns, desktop-first, cell comparison | Grid Table | `sap.ui.table.Table` | none — do not substitute `ui5-table` |
+| Aggregation: sums/subtotals per group (OData) | Analytical Table | `sap.ui.table.AnalyticalTable` | none |
+| True parent-child hierarchy (BOM, org, cost centers) | Tree Table | `sap.ui.table.TreeTable` | none |
+| Card/tile visual layout, images, non-tabular | Grid List | `sap.f.GridList` | none |
+| Simple vertical item list, not columnar | List | `sap.m.List` / `sap.m.StandardListItem` | `ui5-list` / `ui5-li` |
+
+Decision order:
+1. **Hierarchy?** → Tree Table.
+2. **Aggregation/totals?** → Analytical Table.
+3. **Large (>~200) or desktop cell-comparison?** → Grid Table.
+4. **Visual cards, not columns?** → Grid List.
+5. **Otherwise** → Responsive Table (`sap.m.Table`), or `ui5-table` in web-component apps.
+
+Common misuses:
+- **Responsive Table for 5,000 rows.** It loads and renders everything → DOM bloat, single-column pop-in mush. Use Grid Table.
+- **Analytical Table with no aggregation** as a "nicer grid." Adds cost, drops mobile. Use Grid Table.
+- **Grouping an Analytical Table to fake a hierarchy.** Grouping ≠ nodes. Use Tree Table.
+- **Grid List for text-heavy tabular data** because "cards look nice." No column alignment/sort. Use Responsive Table.
+- **`ui5-table` as a drop-in for the grid/analytical tables.** It supports `overflow-mode="Popin"` (≈ `sap.m.Table`) but has no aggregation or freeze. There is no web-component grid/analytical/tree table.
+
+Smart/MDC tables (Fiori Elements): `sap.ui.comp.smarttable.SmartTable` (V2) / `sap.ui.mdc.Table` (V4) are annotation-driven wrappers — see `fiori-elements-vs-freestyle.md`. Don't hand-build these.
+
+---
+
+## Inputs & selection
+
+Pick the simplest control that fits the cardinality and source.
+
+| Need | Control | SAPUI5 | Web Component |
+|---|---|---|---|
+| Single-line free text | Input | `sap.m.Input` | `ui5-input` |
+| Multi-line text | Text Area | `sap.m.TextArea` | `ui5-textarea` |
+| Pick one, short fixed list (~2–12) | Select | `sap.m.Select` | `ui5-select` |
+| Pick one, long list, type-ahead/free text | Combo Box | `sap.m.ComboBox` | `ui5-combobox` |
+| Pick many from a list | Multi-Combo Box | `sap.m.MultiComboBox` | `ui5-multi-combobox` |
+| Enter many tokens (with value help/suggestions) | Multi-Input | `sap.m.MultiInput` | `ui5-multi-input` |
+| Pick one, all options visible, ≤ ~8 | Radio Button (group) | `sap.m.RadioButton` / `RadioButtonGroup` | `ui5-radio-button` |
+| Toggle a confirmed-on-save flag | Checkbox | `sap.m.CheckBox` | `ui5-checkbox` |
+| Toggle an immediate on/off state | Switch | `sap.m.Switch` | `ui5-switch` |
+| Pick a date | Date Picker | `sap.m.DatePicker` | `ui5-date-picker` |
+| Pick a date range | Date Range Selection | `sap.m.DateRangeSelection` | none — use `ui5-date-picker` with a range, or compose two |
+| Pick date + time | Date/Time Picker | `sap.m.DateTimePicker` | none — compose `ui5-date-picker` + `ui5-time-picker` |
+| Pick a time | Time Picker | `sap.m.TimePicker` | `ui5-time-picker` |
+| Numeric with steppers | Step Input | `sap.m.StepInput` | `ui5-step-input` |
+| Search a list/table | Search Field | `sap.m.SearchField` | `ui5-search` |
+| Complex value selection (dialog + inline) | Value Help Dialog | `sap.m.ValueHelpDialog` / `sap.ui.mdc.ValueHelp` | none |
+
+Common misuses:
+- **Input for dates** → use Date Picker (parsing, calendar, validation come free).
+- **Select for 200 items** → use Combo Box or Input + value help.
+- **Checkbox for an immediate on/off** → use Switch; Checkbox implies "applies on save."
+- **Multiple Inputs for multi-value entry** → use Multi-Input or Multi-Combo Box.
+- **Select for a binary** → use Switch (setting) or Radio group (2 visible choices).
+
+---
+
+## Actions
+
+| Need | Control | SAPUI5 | Web Component |
+|---|---|---|---|
+| Trigger an action | Button | `sap.m.Button` | `ui5-button` |
+| Navigate to a page/anchor/URL | Link | `sap.m.Link` | `ui5-link` |
+| Toggle a two-state toolbar action | Toggle Button | `sap.m.ToggleButton` | `ui5-toggle-button` |
+| Choose one of a small option set | Segmented Button | `sap.m.SegmentedButton` | `ui5-segmented-button` |
+| Button that opens a menu | Menu Button | `sap.m.MenuButton` | `ui5-button` + `ui5-menu` (no `ui5-menu-button`) |
+| Default action + menu | Split Button | `sap.m.MenuButton` (split) | `ui5-split-button` |
+
+Button emphasis:
+- **Primary:** `type="Emphasized"` / `design="Emphasized"` — one per page/dialog.
+- **Secondary:** `type="Default"` (or `"Transparent"` in header/footer toolbars) / `design="Transparent"`. `Ghost` is legacy SAPUI5; no Web Component equivalent.
+- **Positive/Negative:** semantic `Accept`/`Reject` (SAPUI5) / `design="Positive"`/`"Negative"` (WC). Text buttons only.
+
+Common misuses:
+- **Button for navigation** → Link. **Link to submit** → Button.
+- **`design="Ghost"` in web components** → doesn't exist; use `Transparent`.
+- **`ui5-menu-button`** → doesn't exist; compose `ui5-button` + `ui5-menu`.
+
+---
+
+## Navigation & structure
+
+| Need | Control | SAPUI5 | Web Component |
+|---|---|---|---|
+| App header (logo, search, notifications, profile, Joule) | Shell Bar | `sap.f.ShellBar` | `ui5-shellbar` (`assistant` slot = Joule) |
+| Left navigation menu | Side Navigation | `sap.tnt.SideNavigation` | `ui5-side-navigation` (inside `ui5-navigation-layout`) |
+| In-page section/facet navigation | Icon Tab Bar | `sap.m.IconTabBar` | `ui5-tabcontainer` |
+| Editable multi-document tabs | Tab Container | `sap.m.TabContainer` | `ui5-tabcontainer` |
+| Object detail floorplan | Object Page | `sap.uxap.ObjectPageLayout` | none |
+| List → detail columns | Flexible Column Layout | `sap.f.FlexibleColumnLayout` | none |
+| Breadcrumb trail | Breadcrumbs | `sap.m.Breadcrumbs` | `ui5-breadcrumbs` |
+| Save/load view configurations | Variant Management | `sap.m.VariantManagement` / `sap.ui.fl.variants.VariantManagement` | none |
+
+Common misuses:
+- **Bar as app header** → ShellBar. Bar is a content-area toolbar (page/dialog header/footer).
+- **List as side nav** → SideNavigation (nav semantics, expand/collapse, selection).
+- **TabContainer for in-page sections** → IconTabBar. TabContainer is browser-tab-style editing.
+- **`ui5-side-navigation` standalone** → wrap in `ui5-navigation-layout` or responsive behavior breaks.
+- **Shell Bar `Back` button** → prefer the browser back button; only use ShellBar back when technically forced.
+
+---
+
+## Overlays & messaging
+
+| Need | Control | SAPUI5 | Web Component |
+|---|---|---|---|
+| Modal that blocks and requires input | Dialog | `sap.m.Dialog` | `ui5-dialog` |
+| Semantic error/warning/success/confirm dialog | Message Box | `sap.m.MessageBox` | `ui5-dialog` (build manually) |
+| Non-blocking inline page message | Message Strip | `sap.m.MessageStrip` | `ui5-message-strip` |
+| Transient success confirmation | Message Toast | `sap.m.MessageToast` | `ui5-toast` |
+| Aggregate many messages | Message Popover | `sap.m.MessagePopover` | none |
+| Contextual detail beside a trigger | Popover | `sap.m.Popover` | `ui5-popover` |
+| Standardized object preview | Quick View | `sap.m.QuickView` | none |
+| Responsive popover (full-screen on phone) | Responsive Popover | `sap.m.ResponsivePopover` | `ui5-responsive-popover` |
+
+Common misuses:
+- **Dialog for a plain error** → MessageBox (semantic type + buttons for free).
+- **MessageBox/Dialog for inline feedback** → MessageStrip (non-blocking).
+- **MessageStrip/Dialog for brief success** → MessageToast (auto-dismiss).
+- **Popover for confirmation** → Dialog. Popover is non-modal, background stays interactive.
+- **Custom Popover structure for object preview** → QuickView (standard) unless it truly can't fit.
+
+---
+
+## Controls with no Web Component
+
+State this explicitly instead of inventing a `ui5-*` tag:
+- `sap.ui.table.Table` / `AnalyticalTable` / `TreeTable` — no WC grid/analytical/tree table.
+- `sap.uxap.ObjectPageLayout`, `sap.f.FlexibleColumnLayout`, `sap.f.GridList` — no WC equivalent.
+- `sap.m.MessagePopover`, `sap.m.QuickView`, `sap.m.ValueHelpDialog`, `sap.m.VariantManagement` — no WC.
+- `sap.m.MenuButton` — no `ui5-menu-button`; use `ui5-button` + `ui5-menu`.
+- `sap.m.p13n.Popup` — no WC.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/implementation-checklist.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/implementation-checklist.md
new file mode 100644
index 0000000..0f6de22
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/implementation-checklist.md
@@ -0,0 +1,111 @@
+# Implementation Checklist
+
+Use this when reviewing a built Fiori app. Each item is a yes/no check.
+
+## Shell and Navigation
+
+- [ ] App header uses `sap.f.ShellBar` / `ui5-shellbar` — not `sap.m.Bar` or a custom header
+- [ ] Left-hand navigation uses `sap.f.SideNavigation` / `ui5-side-navigation` — not a List
+- [ ] Master–detail layout uses `sap.f.FlexibleColumnLayout` — not custom CSS columns
+- [ ] Cross-app navigation uses semantic object / action intents — not raw URLs
+- [ ] Back navigation works with the browser back button and shell back arrow
+- [ ] `manifest.json` declares `crossNavigation.inbounds` and `outbounds`
+
+## Layout and Floorplan
+
+- [ ] Object detail pages use `sap.uxap.ObjectPageLayout` — not `sap.m.Page`
+- [ ] List → detail split uses FCL — not nested routes with manual column CSS
+- [ ] Wizards use `sap.m.Wizard` — not a sequence of dialogs
+- [ ] Tab-based in-page navigation uses `sap.m.IconTabBar` / `ui5-tabcontainer` — not `TabContainer`
+
+## Buttons and Actions
+
+- [ ] Exactly one emphasized / primary button per page or dialog
+- [ ] Destructive actions (Delete, Discard) are Default or Transparent — never emphasized
+- [ ] Icon-only buttons have a tooltip and an accessible name
+- [ ] Button text is an imperative verb (Save, Edit, Approve) — not "OK", "Yes", "Submit"
+- [ ] Page-level actions are in the toolbar or floating footer — not inline in content
+- [ ] Overflow actions use an overflow menu — button labels are not truncated
+
+## Forms and Inputs
+
+- [ ] Every input field has a visible label (not placeholder-only)
+- [ ] Required fields marked with `*`; convention explained once on the form
+- [ ] Date inputs use `sap.m.DatePicker` / `ui5-date-picker` — not a plain `Input`
+- [ ] Short fixed lists (2–12 items) use `Select`; long/dynamic lists use `ComboBox` + value help
+- [ ] Immediate-effect toggles use `Switch`; save-confirmed selections use `CheckBox`
+- [ ] Form validation uses `valueState` on the control — not manual border color CSS
+- [ ] Error messages are associated with their field (`aria-describedby` or control API)
+
+## Tables and Lists
+
+- [ ] Responsive table (`sap.m.Table`) used only for ≤~200 rows, no aggregation needed
+- [ ] Large datasets or totals use `sap.ui.table.AnalyticalTable` — not responsive table
+- [ ] Hierarchical data uses `sap.ui.table.TreeTable` — not grouped AnalyticalTable
+- [ ] Table type choice matches the data shape (see `references/ui-lists-tables.md`)
+- [ ] Empty table state uses `IllustratedMessage` — not a plain "No data" text
+
+## Messaging
+
+- [ ] Persistent page-level messages use `MessageStrip` — not a Dialog
+- [ ] One-time success confirmations use `MessageToast` — not a persistent strip
+- [ ] Multiple validation errors use `MessagePopover` — not stacked strips
+- [ ] Modal confirmations and errors use `MessageBox` — not a hand-built Dialog
+- [ ] MessageToast text fits within 3 seconds of reading (~80 chars)
+
+## Colors and Theming
+
+- [ ] No hard-coded hex colors — all colors use `--sap*` CSS tokens
+- [ ] Semantic colors used by meaning: error → `--sapNegativeColor`, warning → `--sapCriticalColor`, etc.
+- [ ] AI surfaces use `--sapAssistant_Color1/2` gradient — not repurposed brand colors
+- [ ] Form field validation uses `valueState` — not manual color overrides
+
+## Content Density
+
+- [ ] Density set once at the app root (Cozy / Compact / Condensed)
+- [ ] Cozy and Compact not mixed arbitrarily in the same app context
+- [ ] Condensed used only in table contexts within a Compact container
+
+## Accessibility
+
+- [ ] Every interactive element has an accessible name (label, `aria-label`, or tooltip)
+- [ ] Images that convey meaning have `alt` text; decorative images have `alt=""` and `aria-hidden="true"`
+- [ ] Form fields have an associated `<label>` — placeholder text not used as the only label
+- [ ] Heading hierarchy is sequential (H1 → H2 → H3) with no skipped levels
+- [ ] Focus indicator is visible on all interactive elements — `outline: none` not used without a replacement
+- [ ] Focus is trapped in modal dialogs; on close, focus returns to the trigger element
+- [ ] Dynamic content updates use `aria-live` regions
+- [ ] App tested with keyboard-only navigation
+
+## AI Features
+
+- [ ] AI Notice shown for every AI-generated output (required under EU AI Act Art. 50)
+- [ ] AI icon (`sap-icon://ai`) used on AI entry points — not on non-AI controls
+- [ ] AI color palette (`--sapAssistant_*`) used only for AI surfaces
+- [ ] At least Level 1 explanation indicator on all AI-generated results
+- [ ] Level 2 explanation available when Level 1 indicator is clickable
+- [ ] Level 3 explanation is role-gated (not accessible to general users by default)
+- [ ] Agentic AI workflows have cancel/pause controls and a human confirmation step before irreversible actions
+
+## Loading and Empty States
+
+- [ ] `BusyIndicator` shown for operations ≥ 1 second; minimum display time 500 ms
+- [ ] Placeholder loading (skeleton) used for initial page load of large datasets
+- [ ] Empty states use `sap.m.IllustratedMessage` / `ui5-illustrated-message`
+- [ ] Empty state includes an actionable button when the user can create or reset
+
+## Fiori Elements (when applicable)
+
+- [ ] Column visibility, criticality, and actions configured via annotations — not controller code
+- [ ] Table columns defined in `UI.LineItem` annotation — not added programmatically
+- [ ] Field visibility controlled by `UI.Hidden` annotation — not `visible="{= ...}"` in XML
+- [ ] Object page header facets in `UI.HeaderFacets` — not custom fragments in the header
+- [ ] Custom actions registered via `manifest.json` extensions — not added directly to controller
+
+## Data Formatting
+
+- [ ] Dates formatted via SAPUI5 `DateFormat` — not manual string formatting
+- [ ] Numbers formatted via SAPUI5 `NumberFormat` with locale-aware separators
+- [ ] Currency displayed with ISO code or symbol
+- [ ] Units of measurement abbreviated per SI standard with a space before the unit
+- [ ] Input values trimmed of leading/trailing whitespace before persistence
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/theming-tokens.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/theming-tokens.md
new file mode 100644
index 0000000..c2453e7
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/theming-tokens.md
@@ -0,0 +1,79 @@
+# Theming Tokens
+
+Use SAP theme parameters (CSS custom properties), never hard-coded hex. The theme (default:
+**Horizon**) resolves them, including High Contrast Black/White and dark variants. Values below are
+Horizon Morning (light); do not hard-code them — reference the token.
+
+Convention: `--sap<Category>_<Variant>` — e.g. `--sapButton_Emphasized_Background`,
+`--sapField_InvalidColor`. Full set: `github.com/SAP/theming-base-content`.
+
+## Base & brand
+
+| Token | Value | Use |
+|---|---|---|
+| `--sapBrandColor` | `#0070f2` | Primary brand accent |
+| `--sapHighlightColor` | `#0064d9` | Highlighted/active elements |
+| `--sapBaseColor` | `#fff` | Base background |
+| `--sapContent_Selected_TextColor` | `#0064d9` | Selected text |
+
+## Semantic status colors
+
+Map meaning → token. Don't pick colors by eye.
+
+| Meaning | Token | Value |
+|---|---|---|
+| Positive / success | `--sapPositiveColor` | `#256f3a` |
+| Critical / warning | `--sapCriticalColor` | `#e76500` |
+| Negative / error | `--sapNegativeColor` | `#aa0808` |
+| Informative | `--sapInformativeColor` | `#0070f2` |
+| Neutral | `--sapNeutralColor` | `#788fa6` |
+
+For form fields use the value-state tokens (`--sapField_InvalidColor`, `--sapField_WarningColor`,
+`--sapField_SuccessColor`, `--sapField_InformationColor`) via the control's `valueState`, not manual CSS.
+
+## Buttons & fields
+
+| Token | Value |
+|---|---|
+| `--sapButton_Emphasized_Background` | `#0070f2` |
+| `--sapButton_Emphasized_TextColor` | `#fff` |
+| `--sapField_BorderColor` | `#556b81` |
+
+## AI / Joule
+
+AI surfaces have a distinct purple→magenta identity. Use it only for AI-generated content.
+
+| Token | Value |
+|---|---|
+| `--sapAssistant_Color1` | `#5d36ff` |
+| `--sapAssistant_Color2` | `#a100c2` |
+| `--sapAssistant_BackgroundGradient` | `linear-gradient(#5d36ff, #a100c2)` |
+
+## Typography
+
+| Token | Value |
+|---|---|
+| `--sapFontFamily` | `"72", "72full", Arial, Helvetica, sans-serif` |
+| `--sapFontSize` | `.875rem` (14px) |
+
+The SAP font is **72**. Condensed density uses `72-Condensed`. Don't set a custom font family.
+
+## Content density — three tiers
+
+Set once at the app root; controls inherit it.
+
+| Tier | Element height token | Value | When |
+|---|---|---|---|
+| Cozy (default) | `--sapElement_Height` | `2.25rem` | Touch, mobile, low-density screens |
+| Compact | `--sapElement_Compact_Height` | `1.625rem` | Mouse/desktop, data-dense screens |
+| Condensed | `--sapElement_Condensed_Height` | `1.375rem` | Very dense tables (with Compact on the page) |
+
+- SAPUI5: add the CSS class `sapUiSizeCozy` / `sapUiSizeCompact` / `sapUiSizeCondensed` on a container.
+- Web Components: cozy is default; opt into compact via `import "@ui5/webcomponents-base/dist/features/ui5-content-density.js"` and the `ui5-content-density-compact` class.
+- Condensed is table-only and must sit inside a Compact container.
+
+## Rules
+
+- Reference tokens, never hex. A hard-coded `#aa0808` breaks in dark/HCB themes.
+- Semantic color = meaning, not decoration. Error is always the negative token.
+- One density per app context; don't mix cozy and compact arbitrarily.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-actions.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-actions.md
new file mode 100644
index 0000000..9eafd16
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-actions.md
@@ -0,0 +1,90 @@
+# UI Actions
+
+## Contents
+- [Button](#button)
+- [Link](#link)
+- [Toggle Button](#toggle-button)
+- [Segmented Button](#segmented-button)
+- [Menu Button](#menu-button)
+- [Split Button](#split-button)
+
+---
+
+## Button
+
+- **SAPUI5:** `sap.m.Button`  **Web Component:** `ui5-button` (`@ui5/webcomponents`)
+- **Use when:** The user needs to trigger an action — submit, save, create, delete, open a dialog.
+- **Do NOT use when:** You need to navigate to a page or URL → use `ui5-link` instead.
+- **Rules:**
+  - One `design="Emphasized"` button per page or dialog — the primary action only.
+  - Secondary actions in header/footer toolbars: `design="Transparent"` (not Default). Content toolbar secondary: also `design="Transparent"`.
+  - `design="Ghost"` does not exist in web components — use `design="Transparent"`.
+  - Semantic actions (accept/reject): use `design="Positive"` / `design="Negative"` — text buttons only, never icon-only.
+  - Icon-only buttons must have a `tooltip` property set.
+- **Gotchas:** In S/4HANA XML views, use `type="Ghost"` for secondary toolbar actions; in web components the equivalent is `design="Transparent"` — the property name is `design`, not `type`. Fiori Elements supports only text buttons except in table inline actions (icon or text, not both).
+
+---
+
+## Link / Hyperlink
+
+- **SAPUI5:** `sap.m.Link`  **Web Component:** `ui5-link` (`@ui5/webcomponents`)
+- **Use when:** Navigating to another page, anchor, or external URL.
+- **Do NOT use when:** Triggering an action (submit, delete, open dialog) → use `ui5-button` instead.
+- **Rules:**
+  - Link text must describe the destination — never "Click here" or "Link".
+  - Use `design="Subtle"` only inside tables for secondary links in dense data.
+  - Use `design="Emphasized"` only when a link needs stronger visual prominence than default.
+  - Do not use a link with no `href` and no click handler — that is decorative and invalid.
+- **Gotchas:** `ui5-link` does not resize with cozy/compact density — size is fixed. Icon-only links are not supported; always pair with text.
+
+---
+
+## Toggle Button
+
+- **SAPUI5:** `sap.m.ToggleButton`  **Web Component:** `ui5-toggle-button` (`@ui5/webcomponents`)
+- **Use when:** Activating or deactivating a toolbar element (e.g. show/hide panel, toggle filter) — a two-state secondary action.
+- **Do NOT use when:** Triggering a one-shot action (Create, Save, Edit) → use `ui5-button`. Showing many options → use a menu.
+- **Rules:**
+  - Use `design="Default"` (standard) for secondary actions; `design="Transparent"` for tertiary.
+  - Icon-only toggle buttons must have a `tooltip`.
+  - Do not change the button text or icon between toggled and untoggled — the pressed state is communicated via ARIA, not text change.
+- **Gotchas:** `pressed` is the property to read/set the toggle state programmatically. Do not swap text to indicate state — screen readers will misread it.
+
+---
+
+## Segmented Button / View Switch
+
+- **SAPUI5:** `sap.m.SegmentedButton`  **Web Component:** `ui5-segmented-button` (`@ui5/webcomponents`)
+- **Use when:** Choosing one option from a small, related set visible all at once (Year/Month/Day, Small/Medium/Large — 2–5 options).
+- **Do NOT use when:** More than ~5 options → use a Select or RadioButton group. Navigation between page sections → use IconTabBar.
+- **Rules:**
+  - Use child `ui5-segmented-button-item` elements, not generic buttons.
+  - Icon-only segments must have a `tooltip` on each item.
+  - `selection-mode="Multiple"` is WC-only; SAPUI5 SegmentedButton is single-select only.
+- **Gotchas:** Do not use as an in-page navigation control — that is IconTabBar (`ui5-tabcontainer`). The WC supports multi-select via `selection-mode="Multiple"` which has no SAPUI5 equivalent.
+
+---
+
+## Menu Button / Button + Menu
+
+- **SAPUI5:** `sap.m.MenuButton`  **Web Component:** none — compose `ui5-button` + `ui5-menu` (`@ui5/webcomponents`)
+- **Use when:** A button that opens a dropdown menu of actions (no default action — clicking always opens the menu).
+- **Do NOT use when:** You only have one action → use a plain button. You need a default action + overflow → use Split Button.
+- **Rules:**
+  - No `ui5-menu-button` tag exists in web components. Wire a `ui5-button` click handler to open a `ui5-menu` with `opener` set to the button's ID.
+  - Use `design="Transparent"` for menu buttons in content toolbars.
+  - On phones, `ui5-menu` renders as a full-screen dialog automatically.
+- **Gotchas:** `ui5-menu-button` is a common wrong guess — the tag does not exist. Always compose `ui5-button` + `ui5-menu`.
+
+---
+
+## Split Button / Default Action + Menu
+
+- **SAPUI5:** `sap.m.MenuButton` (with `buttonMode="Split"`)  **Web Component:** `ui5-split-button` (`@ui5/webcomponents`)
+- **Use when:** One default action (left area) plus a menu of additional actions (arrow area), and the default is used most often.
+- **Do NOT use when:** All actions are equally weighted → use a Menu Button. Only one action exists → use a plain Button.
+- **Rules:**
+  - `click` event fires on the default action (left area); `arrow-click` fires on the arrow area.
+  - Both areas share the same `design` value — they cannot be styled independently.
+  - Use `design="Transparent"` in content toolbars.
+- **Gotchas:** In SAPUI5, the split button is `sap.m.MenuButton` with `buttonMode` property set to `sap.m.MenuButtonMode.Split` — it is not a separate class. In web components, `ui5-split-button` is a distinct component.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-ai.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-ai.md
new file mode 100644
index 0000000..4676124
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-ai.md
@@ -0,0 +1,136 @@
+# UI AI Components
+
+## Contents
+- [AI Button](#ai-button)
+- [AI Acknowledgment](#ai-acknowledgment)
+- [AI Writing Assistant](#ai-writing-assistant)
+- [Quick Prompts](#quick-prompts)
+- [Guided Prompts](#guided-prompts)
+- [Regenerate](#regenerate)
+- [Local AI Notice](#local-ai-notice)
+- [Home Page Banner](#home-page-banner)
+
+---
+
+## AI Button
+
+- **SAPUI5:** none (pattern built on `sap.m.Button` / `sap.m.MenuButton` / `sap.m.SplitButton`)  **Web Component:** `ui5-ai-button` (`@ui5/webcomponents-ai`)
+- **Use when:** Triggering one or more AI-powered actions from a toolbar, form, or detail area.
+- **Do NOT use when:** The action is not AI-powered → use a regular `ui5-button`; using `Ghost` design → does not exist in WC, use `Transparent`.
+- **Rules:**
+  - Always use the sparkles icon (no other icon); icon is leading only.
+  - Use `design="Default"` (secondary) by default; `design="Emphasized"` only when the AI action is the primary action of the page.
+  - Do not include "AI" in the button label (not "Generate with AI" — just "Generate").
+  - Three variants: simple button (single action), menu button (multiple actions via dropdown), split button (main action + dropdown alternatives).
+  - While generating: change button to "Stop Generating" to let users cancel at any time.
+  - In `ui5-ai-button`, define states via child `ui5-ai-button-state` elements and switch between them by setting `state`.
+- **Gotchas:** The WC import is `@ui5/webcomponents-ai/dist/Button.js` — it is not in `@ui5/webcomponents`. In SAPUI5 there is no `sap.m.AIButton` class; compose with standard `sap.m.Button`/`sap.m.MenuButton` following the AI button pattern guidelines.
+
+---
+
+## AI Acknowledgment
+
+- **SAPUI5:** composed pattern — `sap.m.MessageBox` (dialog type)  **Web Component:** composed — `ui5-dialog`
+- **Use when:** Onboarding a user to an application that contains AI features for the first time — especially in high-stakes scenarios (financial forecasting, contract recommendations, HR insights, customer communications).
+- **Do NOT use when:** Notifying about failed/successful AI processes → use messaging patterns; sending marketing information about AI; displaying general system information.
+- **Rules:**
+  - Display on first launch of an AI-enabled application; re-display when significant new AI capabilities are added.
+  - Use the standard disclaimer text: "Artificial Intelligence (AI) generates results based on multiple sources. Outputs may contain errors and inaccuracies. Consider reviewing all generated results and adjust as necessary."
+  - Provide a "Don't show me again" checkbox to suppress future instances; always offer a way for users to retrieve the information again.
+  - Footer buttons: informational-only → "Close"; with opt-out → "OK" + checkbox; acknowledgment required → "Accept" + "Dismiss" + checkbox.
+  - Use clear plain language — no legal jargon.
+- **Gotchas:** This is a UX pattern, not a standalone control. There is no `ui5-ai-acknowledgment` tag. Low-stakes scenarios (entertainment, generic greetings) may omit the acknowledgment entirely.
+
+---
+
+## AI Writing Assistant
+
+- **SAPUI5:** composed pattern  **Web Component:** composed pattern — `ui5-ai-button` + `ui5-menu` embedded in `ui5-input` / `ui5-textarea`
+- **Use when:** Adding AI-assisted text generation, rewriting, or refinement to an input field, text area, or rich text editor.
+- **Do NOT use when:** The task is not text editing; using alongside the standalone quick-prompts button/menu on the same field; pre-populated fields with confident AI recommendations; context or data is insufficient for quality results.
+- **Rules:**
+  - Embed the AI icon menu button within the input/textarea component — do not place it in a toolbar outside the field.
+  - Always include a "Stop Generating" control visible during generation.
+  - Versioning appears only when a prompt is applied to a populated field or more than one prompt is applied to the same field.
+  - Standard error message: "Something went wrong while generating your content. Please try again."
+  - Pair with the Local AI Notice (see below) to disclose AI involvement.
+  - Only enable on fields where AI adds measurable value — coordinate with the product team on prompt count limits (cost and sustainability).
+- **Gotchas:** There is no `ui5-ai-writing-assistant` tag. `Make Bulleted List` and `Adjust Length` prompts are not appropriate for single-line inputs.
+
+---
+
+## Quick Prompts
+
+- **SAPUI5:** composed pattern  **Web Component:** composed — `ui5-ai-button` + `ui5-menu`
+- **Use when:** Tasks are repetitive or common within a workflow; the system supports only a specific set of actions; consistent and predictable output is needed.
+- **Do NOT use when:** User intent is unpredictable; users need free-form control over the output; used alongside the AI writing assistant on the same field; applied to multiple fields in a form (use form-level actions instead).
+- **Rules:**
+  - Use a single `ui5-ai-button` for one quick prompt; use `ui5-ai-button` in menu mode for multiple.
+  - Always identify quick prompts with the sparkles (AI) icon.
+  - Use standard action labels: Generate, Revise, Regenerate, Fix Spelling and Grammar, Summarize, Paraphrase, Make Bulleted List, Explain Content, Rewrite Text, Change Tone, Adjust Length, Translate.
+  - Ensure users can complete the task without quick prompts — AI must always be optional.
+  - Primary (Emphasized) button only when the quick prompt is the sole primary action on the page.
+- **Gotchas:** There is no standalone `ui5-quick-prompts` tag. During generation, primary actions should be temporarily disabled to prevent interaction with partially generated content.
+
+---
+
+## Guided Prompts
+
+- **SAPUI5:** composed pattern  **Web Component:** composed — `ui5-dialog` + `ui5-ai-button` + form inputs
+- **Use when:** Users need to specify parameters (language, tone, length, type) to guide AI output; users lack prompt-writing experience; consistent and controlled output is required.
+- **Do NOT use when:** Users need full free-form flexibility → use custom prompts; tasks are repetitive/single-action → use quick prompts; user intent is uncertain → use custom prompts.
+- **Rules:**
+  - Always use an explicit confirmation action (AI button) to trigger generation — never auto-trigger on input change.
+  - Always include a cancel option so users can exit without committing.
+  - Standard trigger labels: "Compose Text" (initial generation), "Revise" (editing).
+  - Choose input components suited to the parameter type (select for language, range slider for length) — don't default everything to dropdowns.
+  - Standard error message: "Something went wrong while generating your content. Please try again."
+- **Gotchas:** No `ui5-guided-prompts` tag. This is a pattern assembled from existing components. The dialog must prevent automatic regeneration — user confirmation is always required to avoid unintended content replacement.
+
+---
+
+## Regenerate
+
+- **SAPUI5:** composed pattern  **Web Component:** composed — `ui5-ai-button` (simple or split)
+- **Use when:** Re-running or refining a previously generated AI result for a specific content element.
+- **Do NOT use when:** The function is not AI-powered → use a regular button.
+- **Rules:**
+  - Always use buttons with both icon and label — never icon-only for Regenerate.
+  - Only use the sparkles icon — no alternative icons on the Regenerate button.
+  - Label "Regenerate" is the default; use more descriptive wording only when the outcome is not obvious from context.
+  - Warn users before overwriting existing content: "Regenerating will overwrite all fields with AI-generated content. Do you want to continue?"
+  - In mixed forms, regenerate only AI-generated fields — preserve user-entered content.
+  - In most cases, Regenerate replaces the Generate button in the same position once initial content exists.
+- **Gotchas:** No `ui5-regenerate` tag. Versioning is only supported inside the AI writing assistant experience — outside it, always show the overwrite warning dialog. Do not place Regenerate as a primary action in page footer bars.
+
+---
+
+## Local AI Notice
+
+- **SAPUI5:** composed — `sap.m.Link` or `sap.m.Label`  **Web Component:** composed — `ui5-link` or `ui5-label`
+- **Use when:** Any UI surface displays AI-generated or AI-edited content — this pattern is mandatory.
+- **Do NOT use when:** Marking non-AI content; any purpose other than disclosing AI-generated content.
+- **Rules:**
+  - Mandatory per [EU AI Act Article 50](https://artificialintelligenceact.eu/article/50/) and SAP AI Ethics Policy — no exceptions for production UIs.
+  - Standard text: "Created with AI. Verify before use." (short form for limited space: "Created with AI.")
+  - Use the interactive variant (link → popover → SAP Help Portal) for high and very high impact scenarios.
+  - Use the read-only label variant only when no further AI result details can be provided.
+  - Limit to one AI notice label per screen; place it next to the lowest hierarchical title that contains all AI results.
+  - High-impact placement: above content area (between section header and content). Low-impact: footer of the AI results area.
+  - Never truncate the notice — always fully readable; use breakpoints to switch between standard and short variants.
+- **Gotchas:** No `ui5-local-ai-notice` tag. Not yet available in SAP Fiori Elements (as of 2026) — freestyle only. AI surfaces use assistant color identity tokens; see `references/theming-tokens.md` for the `--sapAssistant_Color*` values rather than hardcoding hex.
+
+---
+
+## Home Page Banner
+
+- **SAPUI5:** work in progress  **Web Component:** work in progress — no stable tag yet
+- **Use when:** Any product home page that is part of SAP Business Suite — will be mandatory for S/4HANA Cloud Public Edition ERP and SuccessFactors.
+- **Do NOT use when:** Not a SAP Business Suite home page context.
+- **Rules:**
+  - Mandatory elements: banner container, current date (full format: "Weekday, Month DD, YYYY"), personalized salutation ("Hello, \<First Name>").
+  - Banner must scroll out of view — never sticky.
+  - Action area: secondary buttons only (no Emphasized/Transparent primary); show/hide per role.
+  - Content area items must be enclosed in cards to ensure proper color contrast.
+  - Min height 5.75rem; max recommended height 24rem.
+- **Gotchas:** Implementation is still in progress upstream — do not treat this component as stable for general use. Check SAP Business Suite product team guidance before implementing. There is no confirmed `ui5-home-page-banner` tag in any released package as of current versions.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-containers.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-containers.md
new file mode 100644
index 0000000..71d5f45
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-containers.md
@@ -0,0 +1,211 @@
+# UI Containers
+
+## Contents
+- [Card (Basic)](#card-basic)
+- [Card (Integration)](#card-integration)
+- [Dialog](#dialog)
+- [Popover](#popover)
+- [ResponsivePopover](#responsivepopover)
+- [QuickView](#quickview)
+- [Filter Bar](#filter-bar)
+- [Notification Center](#notification-center)
+- [P13n Dialog Popup](#p13n-dialog-popup)
+- [Shell Bar](#shell-bar)
+- [Table Toolbar](#table-toolbar)
+- [User Menu](#user-menu)
+- [VariantManagement](#variantmanagement)
+- [ValueHelpDialog](#valuehelpdiag)
+
+---
+
+## Card (Basic)
+
+- **SAPUI5:** `sap.m.Card` **Web Component:** `ui5-card` (`@ui5/webcomponents`)
+- **Use when:** Showing a self-contained unit of information (header + content) in a layout alongside other cards — launchpad tiles, dashboard widgets, KPI snapshots.
+- **Do NOT use when:** You need cross-host embedding or annotation-driven card types (List, Table, Analytical, Timeline, Calendar) → use Integration Card instead.
+- **Rules:**
+  - Always set `accessible-name` or `accessible-name-ref` — required for ARIA region label.
+  - Use `ui5-card-header` in the `header` slot; do not put a title as plain text content.
+  - Numeric KPIs belong in a NumericHeader variant, not in the content area as plain text.
+  - Do not nest cards.
+- **Gotchas:** `ui5-card` (`@ui5/webcomponents`) is a simple container. The full card types (List, Analytical, Timeline, Calendar, Object, Component) are only available via `sap.ui.integration.widgets.Card` — there is no web-component equivalent for those types.
+
+---
+
+## Card (Integration)
+
+- **SAPUI5:** `sap.ui.integration.widgets.Card` **Web Component:** none — use the SAPUI5 class directly or the `ui5-card` web component for simple cases only.
+- **Use when:** Embedding app content across host environments (SAP Fiori launchpad, third-party portals, mobile); need annotation-driven card types (List, Table, Analytical, Timeline, Calendar, Object, Component).
+- **Do NOT use when:** You just need a styled container with a header in a single app → use `ui5-card` (basic) instead.
+- **Rules:**
+  - Card manifest JSON drives the content type; do not hand-build card content as free HTML inside an integration card.
+  - The card header is clickable by default and navigates to the underlying source — always provide a meaningful navigation target.
+  - Numeric header: always supply `unitOfMeasurement` via the dedicated property, not free text in the subtitle.
+  - Counter in the header (e.g. "6 of 12") is automatic when the content contains multiple items — do not add a custom counter label.
+- **Gotchas:** Integration cards load via a card manifest (descriptor JSON), not via control properties. The host environment controls container sizing; the card adapts — do not set fixed widths on integration cards.
+
+---
+
+## Dialog
+
+- **SAPUI5:** `sap.m.Dialog` **Web Component:** `ui5-dialog` (`@ui5/webcomponents`)
+- **Use when:** The action is modal — user must respond before continuing (confirmation, form requiring input, destructive action).
+- **Do NOT use when:** The message is informational only and non-blocking → use `sap.m.MessageStrip` / `ui5-message-strip`; for a plain semantic error/warning/success/confirm dialog → use `sap.m.MessageBox` (SAPUI5) or `ui5-dialog` with `state` property set; for contextual detail beside an element → use Popover.
+- **Rules:**
+  - One emphasized button per dialog maximum; all other actions are Default/Transparent.
+  - Do not nest dialogs — each dialog must be a separate element in the markup.
+  - Use `state="Negative"` / `state="Critical"` on `ui5-dialog` for error/warning dialogs; this sets `role="alertdialog"` automatically.
+  - On phone, set `stretch` to `true` for full-screen display.
+  - For semantic error/warning/confirm in SAPUI5 freestyle, prefer `sap.m.MessageBox` over a hand-built Dialog.
+- **Gotchas:** `ui5-dialog` is always modal. `draggable` and `resizable` only work on desktop. Setting `initialFocus` has no effect if the target element has `autofocus`.
+
+---
+
+## Popover
+
+- **SAPUI5:** `sap.m.Popover` **Web Component:** `ui5-popover` (`@ui5/webcomponents`)
+- **Use when:** Non-modal contextual content anchored to a trigger — detail without leaving the page, lightweight preview, non-disruptive actions.
+- **Do NOT use when:** User input or confirmation is required (modal context) → use Dialog; content is an object preview following a standard structure → use QuickView; the content takes more than one-third of phone screen → use ResponsivePopover.
+- **Rules:**
+  - Popover is non-modal by default — background stays interactive; set `modal` only when click-outside-to-close must be suppressed.
+  - Closing must always be possible: click outside, re-click trigger, or an action inside.
+  - On phone, `sap.m.Popover` opens as a full-screen dialog automatically; `ui5-popover` does not — use `ui5-responsive-popover` for phone support.
+- **Gotchas:** `resize` is SAPUI5 only — not available on `ui5-popover`.
+
+---
+
+## ResponsivePopover
+
+- **SAPUI5:** `sap.m.ResponsivePopover` **Web Component:** `ui5-responsive-popover` (`@ui5/webcomponents`)
+- **Use when:** You need popover behavior on desktop/tablet but full-screen dialog on phone — i.e. when the content must be fully accessible on all device sizes.
+- **Do NOT use when:** Phone behavior is irrelevant (desktop-only app) → plain Popover suffices; content requires confirmed modal interaction → use Dialog.
+- **Rules:**
+  - Treat this as the default overlay choice for any content that must work across all breakpoints.
+  - All Dialog and Popover slot / property rules apply (header, footer, content).
+- **Gotchas:** On phone it acts as a Dialog (modal, full screen); on tablet/desktop it acts as a Popover. The `modal` property behaves accordingly per device.
+
+---
+
+## QuickView
+
+- **SAPUI5:** `sap.m.QuickView` **Web Component:** none — no `ui5-quick-view` exists; do not invent this tag.
+- **Use when:** Standardized object-preview card anchored to a trigger (contact details, business object summary) following the Fiori QuickView pattern.
+- **Do NOT use when:** The structure does not fit the QuickView pattern (groups of label/value pairs with optional navigation) → use a custom Popover; the content is object detail that should live in an Object Page → navigate there instead.
+- **Rules:**
+  - Use `sap.m.QuickViewGroup` / `sap.m.QuickViewGroupElement` for the content structure — do not put arbitrary layouts inside.
+  - QuickView supports back-navigation for multi-page scenarios; do not replicate this with manual Popover navigation flows.
+- **Gotchas:** No web component equivalent. In WC-based apps, build a `ui5-popover` with a structured content if you need a quick view — but that will not match the SAPUI5 QuickView design spec exactly.
+
+---
+
+## Filter Bar
+
+- **SAPUI5:** `sap.ui.mdc.FilterBar` (V4/MDC) / `sap.ui.comp.filterbar.FilterBar` (V2/SmartFilterBar) **Web Component:** none — no `ui5-filter-bar` exists.
+- **Use when:** Part of a List Report, Analytical List Page, or Overview Page floorplan to let users narrow data loaded into the main table.
+- **Do NOT use when:** Table is inside an Object Page section → use ViewSettings dialog; in a Wizard; in a simple list → use Search only.
+- **Rules:**
+  - Prefer **live update mode** unless data volume is very high or multiple filters must be set before any results are meaningful.
+  - Always define a *Basic* group of mandatory and frequently used filters to ship with the app.
+  - Mandatory filters (asterisk) must have values before search returns results — preset them to prevent errors on page load.
+  - Use the simplest selection control that fits: Select for short fixed lists, ComboBox for longer/type-ahead, DatePicker for dates, Value Help only as a last resort.
+  - Do not show a Search field in the Table Toolbar when a Filter Bar is present — the Filter Bar's basic search field covers this.
+- **Gotchas:** In Fiori Elements (V4), the Filter Bar is annotation-driven via `sap.ui.mdc.FilterBar` — do not hand-build it. The SmartFilterBar (`sap.ui.comp.filterbar.FilterBar`) is maintained but no longer enhanced; prefer MDC for new V4 apps.
+
+---
+
+## Notification Center
+
+- **SAPUI5:** `sap.m.NotificationListItem` / `sap.m.NotificationListGroup` (within a `sap.m.Popover`) **Web Component:** `ui5-notification-list` (`@ui5/webcomponents-fiori`), items: `ui5-li-notification` / `ui5-li-notification-group`
+- **Use when:** Surfacing real-time, event-driven alerts in the Shell Bar notification panel (bell icon).
+- **Do NOT use when:** Inline page feedback is needed → use MessageStrip; a brief confirmation is needed → use MessageToast; the message is part of the current flow → use MessagePopover.
+- **Rules:**
+  - Notifications are one-way and cannot be retracted — content must be accurate at creation time.
+  - Group similar event types to avoid flooding — individual low-priority notifications should be grouped.
+  - Each notification must be clear on purpose, brief, and action-oriented.
+  - Sort by date (default) or importance; do not add other sort options.
+  - The bell counter shows new notifications since last panel open; clicking the bell resets it to zero.
+- **Gotchas:** `ui5-notification-list` is in `@ui5/webcomponents-fiori`, not `@ui5/webcomponents`. Import: `import "@ui5/webcomponents-fiori/dist/NotificationList.js"`. The notification panel itself is a Popover in both SAPUI5 and WC implementations.
+
+---
+
+## P13n Dialog Popup
+
+- **SAPUI5:** `sap.m.p13n.Popup` **Web Component:** none — no WC equivalent exists.
+- **Use when:** Users need to personalize a table or Smart Chart with 20+ columns, or need multiple personalization dimensions simultaneously (Columns + Sort + Filter + Group).
+- **Do NOT use when:** Fewer than ~20 columns or only column show/hide needed → use `sap.m.ViewSettingsDialog` (simple) or `sap.m.TablePersoDialog` (basic); if a Filter Bar is present, disable the P13n Filter tab (use the Filter Bar instead).
+- **Rules:**
+  - Tabs can be shown in any combination (Sort, Filter, Columns, Group, Chart) — include only those relevant to the use case.
+  - Columns tab: only columns marked visible can be used for grouping.
+  - Sort tab: if column-header sort is also enabled, it replaces ALL sort options set in the dialog.
+  - New P13n panels from SmartTable (Columns, Sort, Group) are available for freestyle development.
+- **Gotchas:** No web component for `sap.m.p13n.Popup`. Opening is done via toolbar buttons — the P13n dialog is not self-opening.
+
+---
+
+## Shell Bar
+
+- **SAPUI5:** `sap.f.ShellBar` **Web Component:** `ui5-shellbar` (`@ui5/webcomponents-fiori`)
+- **Use when:** Universal app header at the top of every screen — logo, product title, search, notifications, Joule (AI assistant), user profile, product switch.
+- **Do NOT use when:** You need a page-level or section-level toolbar → use `sap.m.Toolbar` / `sap.m.OverflowToolbar`; do not use `sap.m.Bar` as an app header.
+- **Rules:**
+  - Branding element (SAP logo + product name) is mandatory.
+  - Help and Profile slots are mandatory.
+  - Only add actions to the Shell Bar if users need them **frequently** — do not replicate Shell Bar actions in the User Menu or side navigation.
+  - Avoid using the Shell Bar Back button; prefer the browser back button. Only show it when back navigation is technically impossible via the browser.
+  - Use `assistant` slot for Joule/AI assistant button.
+- **Gotchas:** `ui5-shellbar` is in `@ui5/webcomponents-fiori` (not `@ui5/webcomponents`). Import: `import "@ui5/webcomponents-fiori/dist/ShellBar.js"`. The `assistant` slot is the designated entry point for Joule — do not add Joule as a custom shell item.
+
+---
+
+## Table Toolbar
+
+- **SAPUI5:** `sap.m.OverflowToolbar` (wrapping the table) **Web Component:** `ui5-toolbar` (use `sap.m.OverflowToolbar` in SAPUI5 for full overflow support)
+- **Use when:** The table needs a title, actions, view controls, search, or variant management placed above it.
+- **Do NOT use when:** The table is used for selection only; all meaningful actions are row-level only.
+- **Rules:**
+  - Follow the predefined action group order: Finalizing → Business → Modification → Personalization → Share → Export → View → End slot.
+  - *Create*, *Delete*, *Add*, *Remove* must never move into the overflow menu.
+  - Do not show a Search field in the toolbar when a Filter Bar is present on the same page.
+  - One emphasized button maximum per toolbar; use ghost/transparent for the rest in header/footer toolbars.
+  - Variant Management replaces the title in most cases — do not show both unless necessary (insert a separator between them if you do).
+- **Gotchas:** `sap.m.OverflowToolbar` handles responsive overflow automatically. If you use a plain `sap.m.Toolbar`, items do not overflow — critical actions may become invisible on small screens.
+
+---
+
+## User Menu
+
+- **SAPUI5:** accessed via `sap.f.ShellBar` (profile slot) **Web Component:** `ui5-user-menu` (`@ui5/webcomponents-fiori`)
+- **Use when:** User-specific settings, account switching, and sign-out — always accessed via the Shell Bar avatar/profile icon.
+- **Do NOT use when:** App-level navigation items belong here — they go in the side navigation or the app menu, not the User Menu.
+- **Rules:**
+  - Show *Manage Account* button only if a central profile management URL exists outside the product.
+  - Show *Other Accounts* panel only if the product supports multiple accounts.
+  - Standard items: Settings, Legal Information, About. Add product-specific user-related items only.
+  - On S (phone), the User Menu opens full screen.
+- **Gotchas:** `ui5-user-menu` is in `@ui5/webcomponents-fiori`. Import: `import "@ui5/webcomponents-fiori/dist/UserMenu.js"`. It is used inside `ui5-shellbar` via the `profile` slot and opened by setting `open` + `opener` — it is not a standalone dropdown.
+
+---
+
+## VariantManagement
+
+- **SAPUI5:** `sap.m.VariantManagement` / `sap.ui.fl.variants.VariantManagement` **Web Component:** none — no WC equivalent exists.
+- **Use when:** Users need to save, load, and switch between named sets of table/filter-bar settings (column layout, sort, filter, group).
+- **Do NOT use when:** No personalization persistence is needed; only a static title is required.
+- **Rules:**
+  - In tables: VariantManagement replaces the table title — do not show both unless unavoidable.
+  - In Filter Bars: VariantManagement stores filter values, visible filters, and filter order — this is the "Views" selector at the top of the Filter Bar.
+  - Use `sap.ui.fl.variants.VariantManagement` for SAPUI5 Flexibility-backed persistence (recommended for Fiori Elements and freestyle apps with key user adaptation support).
+- **Gotchas:** No web component. In WC-based apps, variant management must be custom-built or left out.
+
+---
+
+## ValueHelpDialog {#valuehelpdiag}
+
+- **SAPUI5:** `sap.m.ValueHelpDialog` / `sap.ui.mdc.ValueHelp` (V4) **Web Component:** none — no WC equivalent exists.
+- **Use when:** Users need to select single or multiple values from a complex source (search + table + token management in one dialog) — especially for filter fields with large data sets.
+- **Do NOT use when:** The list is short and fixed → use Select or ComboBox; for date selection → use DatePicker; for free text → use Input with suggestions. Value Help is a last resort — choose simpler controls first.
+- **Rules:**
+  - In Fiori Elements (V4), Value Help is driven by `@sap.ui.mdc.ValueHelp` annotations — do not hand-build a ValueHelpDialog in Elements apps.
+  - Use `sap.ui.mdc.ValueHelp` for all new V4/MDC freestyle apps; `sap.m.ValueHelpDialog` is V2/legacy.
+  - Always enable the search field inside the dialog when the data source is large.
+- **Gotchas:** No web component. The ValueHelpDialog is also the basis for the Filter Bar's "Adapt Filters" search when using SmartFilterBar — do not confuse the two.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-display.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-display.md
new file mode 100644
index 0000000..34d12aa
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-display.md
@@ -0,0 +1,82 @@
+# UI Display Components
+
+## Contents
+- [Avatar](#avatar)
+- [Avatar Group](#avatar-group)
+- [Progress Indicator](#progress-indicator)
+- [Busy Indicator](#busy-indicator)
+- [Illustrated Message](#illustrated-message)
+
+---
+
+## Avatar
+
+- **SAPUI5:** `sap.m.Avatar`  **Web Component:** `ui5-avatar` (`@ui5/webcomponents`)
+- **Use when:** Representing a person (photo/initials/placeholder), a product, or a business object visually in a list, card, or header.
+- **Do NOT use when:** Displaying a sequence of images → use `sap.m.Carousel`; triggering an action on an icon → use `sap.m.Button` with an icon.
+- **Rules:**
+  - Circle shape for people; square shape for products/business objects.
+  - Use predefined sizes (XS/S/M/L/XL) — no ad-hoc pixel sizes.
+  - Interactive avatars (`mode="Interactive"`) require both a tooltip and `accessible-name`.
+  - Decorative-only avatars: set `mode="Decorative"` (renders `aria-hidden="true"`).
+  - Avoid badges on avatars smaller than size S.
+- **Gotchas:** The legacy `interactive` boolean property overrides `mode`; prefer `mode="Interactive"` in new code. `colorScheme="Auto"` resolves to Accent6, not a random color — use `"Accent1"`–`"Accent10"` or `"Placeholder"` explicitly when you need a specific look.
+
+---
+
+## Avatar Group
+
+- **SAPUI5:** `sap.f.AvatarGroup`  **Web Component:** `ui5-avatar-group` (`@ui5/webcomponents`)
+- **Use when:** Showing 2+ people or entities that share something (team, project, assignment).
+- **Do NOT use when:** Displaying a single avatar, a gallery of unrelated images (use `sap.m.Carousel`), or non-avatar visual content.
+- **Rules:**
+  - Always display horizontally; minimum 2 avatars.
+  - `type="Group"` (default) — overlapping, one click target; use for large groups or when identity of individuals is secondary.
+  - `type="Individual"` — side-by-side, per-avatar click; use for small teams where users need to access individual profiles.
+  - Always provide an `accessible-name` or `accessible-name-ref` on the group.
+  - Overflow popover must show at minimum a full list of overflowed avatars; for >100 overflow navigate to a dedicated page.
+- **Gotchas:** Square-shaped child avatars create visual inconsistency because the built-in overflow button is always a circle — use circle avatars inside `ui5-avatar-group`.
+
+---
+
+## Progress Indicator
+
+- **SAPUI5:** `sap.m.ProgressIndicator`  **Web Component:** `ui5-progress-indicator` (`@ui5/webcomponents`)
+- **Use when:** Showing the percentage completion of a process (upload, wizard step, task) where the exact value is known.
+- **Do NOT use when:** The process duration is unknown → use `ui5-busy-indicator`; conveying status without a numeric value → use a status indicator or `ObjectStatus`.
+- **Rules:**
+  - Set `value` (0–100); values >100 are clamped to 100.
+  - Use `value-state` (`Positive`, `Critical`, `Negative`, `Information`, `None`) to convey meaning semantically, not just visually.
+  - Use `display-value` to override the label text when showing something other than the raw percentage (e.g., "3 of 10 files").
+  - Set `hide-value` only when the percentage is visually obvious from the surrounding context.
+- **Gotchas:** Size is controlled entirely via CSS `width`/`height` — there are no predefined size props. The component has no slots; it is a pure display element.
+
+---
+
+## Busy Indicator
+
+- **SAPUI5:** `sap.m.BusyIndicator`  **Web Component:** `ui5-busy-indicator` (`@ui5/webcomponents`)
+- **Use when:** An operation is in progress and duration is unknown; only part of the UI is affected and the user can still interact with the rest.
+- **Do NOT use when:** The operation takes less than 1 second (avoid flicker); you need to block the entire screen → use a `sap.m.Dialog` with `busyIndicatorDelay`; multiple concurrent operations → show one indicator, not several.
+- **Rules:**
+  - Wrap the affected element as a child: `<ui5-busy-indicator active>...</ui5-busy-indicator>`.
+  - Set `active` to toggle visibility — the indicator is hidden by default.
+  - Use `delay` (default 1000ms) to prevent flicker on fast operations.
+  - Wrap block-level elements with `display: block` on the busy indicator itself (it is `inline-block` by default).
+  - Add `text` to inform users of what is loading when the operation type is non-obvious.
+- **Gotchas:** Do not show multiple `ui5-busy-indicator` instances simultaneously. The `active` property is the toggle — do not mount/unmount the element to show/hide it.
+
+---
+
+## Illustrated Message
+
+- **SAPUI5:** `sap.m.IllustratedMessage`  **Web Component:** `ui5-illustrated-message` (`@ui5/webcomponents-fiori`)
+- **Use when:** Showing an empty state, no-data state, error state, or success state — anywhere plain text would leave the user without visual guidance.
+- **Do NOT use when:** The state needs only a one-line message with no illustration → use `sap.m.MessageStrip`. Never substitute plain `sap.m.Text` or `sap.m.Label` for empty states.
+- **Rules:**
+  - Always place inside a container (`ui5-card`, `ui5-dialog`, page content area) — the component does not size itself.
+  - Import the specific illustration you need beyond the default: `import "@ui5/webcomponents-fiori/dist/illustrations/NoData.js"`.
+  - Default illustration is `BeforeSearch`; set `name` explicitly for the correct context (e.g., `"NoData"`, `"UnableToUpload"`, `"ErrorScreen"`).
+  - TNT illustration set uses the `tnt/` prefix: `name="tnt/Success"` + separate import.
+  - Provide `title-text` and `subtitle-text` (or the matching slots) to override the built-in i18n defaults when context-specific wording is needed.
+- **Gotchas:** `design="Auto"` (default) adapts the illustration size to available space — override with `"Spot"`, `"Dialog"`, `"Scene"` etc. only when you need a specific breakpoint variant. The component lives in `@ui5/webcomponents-fiori`, not `@ui5/webcomponents` — wrong package = import failure.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-inputs.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-inputs.md
new file mode 100644
index 0000000..d8f61fd
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-inputs.md
@@ -0,0 +1,275 @@
+# UI Inputs
+
+## Contents
+- [Input](#input)
+- [TextArea](#textarea)
+- [Select](#select)
+- [ComboBox](#combobox)
+- [MultiComboBox](#multicombobox)
+- [MultiInput](#multiinput)
+- [RadioButton](#radiobutton)
+- [CheckBox](#checkbox)
+- [Switch](#switch)
+- [DatePicker](#datepicker)
+- [DateRangeSelection](#daterangeselection)
+- [DateTimePicker](#datetimepicker)
+- [TimePicker](#timepicker)
+- [StepInput](#stepinput)
+- [SearchField](#searchfield)
+- [Slider](#slider)
+- [RangeSlider](#rangeslider)
+- [Filter Bar](#filter-bar)
+- [ValueHelpDialog](#valuhelpdialog)
+
+---
+
+## Input / Text Field
+
+- **SAPUI5:** `sap.m.Input`  **Web Component:** `ui5-input` (`@ui5/webcomponents`)
+- **Use when:** Single-line free text, numeric, email, URL, phone, or password entry; or selecting from a large dataset (>200 items) with suggestions + value help.
+- **Do NOT use when:** Entering a date → `ui5-date-picker`. Entering long text → `ui5-textarea`. Picking from a short fixed list → `ui5-select`. Picking one item from 20–200 options → `ui5-combobox`. Multiple values → `ui5-multi-input`.
+- **Rules:**
+  - Always pair with a visible `Label` — do not rely on placeholder as the only label.
+  - Set `showSuggestions` + populate suggestion slot to enable type-ahead; suggestions are not automatic.
+  - Value help icon is triggered via `showValueHelp` property (WC: `show-value-help-icon` on `ui5-multi-input`); handle the `value-help-trigger` event to open the dialog.
+  - `type="Search"` on `ui5-input` enables WC-only search mode — no SAPUI5 equivalent; use `sap.m.SearchField` in SAPUI5 instead.
+- **Gotchas:** Tabular suggestions are SAPUI5-only. The WC `ui5-input` does not auto-validate — apps must handle `valueState` themselves.
+
+---
+
+## TextArea / Multi-line Input
+
+- **SAPUI5:** `sap.m.TextArea`  **Web Component:** `ui5-textarea` (`@ui5/webcomponents`)
+- **Use when:** Multi-line text input — descriptions, comments, notes.
+- **Do NOT use when:** Single-line entry → `ui5-input`. Structured data (date, number with step) → use the dedicated picker.
+- **Rules:**
+  - Set `growing` to let the field auto-expand with content; pair with `growing-max-rows` to cap height.
+  - Set `maxlength` + `show-exceeded-text` to display a character counter and allow controlled overflow.
+  - Always use a `Label` above or beside the control — do not use placeholder alone.
+- **Gotchas:** `rows` defines initial height but CSS `height` overrides it. `growing` and a fixed CSS `height` conflict — pick one.
+
+---
+
+## Select / Dropdown
+
+- **SAPUI5:** `sap.m.Select`  **Web Component:** `ui5-select` (`@ui5/webcomponents`)
+- **Use when:** User picks exactly one item from a short, fixed list (~2–12 options) that stays hidden until opened.
+- **Do NOT use when:** Only two binary options → `ui5-switch`. More than ~12 options or the list can be typed → `ui5-combobox`. All options should be visible at once → RadioButton group. Multi-attribute search → Input + value help.
+- **Rules:**
+  - Always define a default selection; use "(Not Selected)" text — never a blank value — for the empty option.
+  - Use `ui5-option` children inside `ui5-select`; use `ui5-option-custom` for custom content.
+  - Sort options logically — most common first; alphabetical for >8 options.
+  - Avoid icon-only options in the list; use icons only when they add recognition.
+- **Gotchas:** On smartphones `ui5-select` opens full-screen. The dropdown max width is 600px; use `wrapItemsText` / `wrap-items-text` to prevent truncation for long entries.
+
+---
+
+## ComboBox / Type-ahead Select
+
+- **SAPUI5:** `sap.m.ComboBox`  **Web Component:** `ui5-combobox` (`@ui5/webcomponents`)
+- **Use when:** Picking one item from a long list (20–200 items) where type-ahead filtering speeds selection, or when free-text entry alongside suggestions is needed.
+- **Do NOT use when:** Short fixed list (~2–12) → `ui5-select`. Very large dataset (>200) or multi-attribute search → Input + value help. Multiple selections → `ui5-multi-combobox`.
+- **Rules:**
+  - Use `ui5-cb-item` children; set `value` on each item when you need an identifier separate from display text, then read `selectedValue` on the combo.
+  - Default `filter="StartsWithPerTerm"` — change to `"Contains"` for substring matching.
+  - `show-clear-icon` lets users reset the field without reopening the list.
+- **Gotchas:** The WC distinguishes `value` (display text / typed text) from `selected-value` (the item's key). Mixing `selectedValue` with the deprecated `selected` property on items causes unpredictable behavior.
+
+---
+
+## MultiComboBox / Multi-select with Filtering
+
+- **SAPUI5:** `sap.m.MultiComboBox`  **Web Component:** `ui5-multi-combobox` (`@ui5/webcomponents`)
+- **Use when:** Selecting multiple items from a list (< ~200) where type-ahead filtering and tokenized selection are needed.
+- **Do NOT use when:** Single selection → `ui5-combobox`. Tokens from a very large or complex dataset → `ui5-multi-input` + value help. No filtering needed and list is short → CheckBox group.
+- **Rules:**
+  - Use `ui5-mcb-item` children; set `value` on each item; use `selected-values` array to programmatically select items.
+  - `show-select-all` adds a "Select All" checkbox at the top — use only when batch selection is a primary workflow.
+  - `no-validation` allows free-text tokens not matching any item.
+- **Gotchas:** The deprecated `selected` property on individual items conflicts with `selected-values` — use only one mechanism.
+
+---
+
+## MultiInput / Token Entry Field
+
+- **SAPUI5:** `sap.m.MultiInput`  **Web Component:** `ui5-multi-input` (`@ui5/webcomponents`)
+- **Use when:** Entering multiple free-text or suggestion-based values that appear as dismissible tokens; typically combined with a value help for large datasets (>200 items).
+- **Do NOT use when:** Picking multiple items from a managed list < ~200 → `ui5-multi-combobox`. Single value only → `ui5-input` or `ui5-combobox`.
+- **Rules:**
+  - Tokens are added via the `tokens` slot; listen to `token-delete` to remove them.
+  - Enable `show-suggestions` + populate suggestion slot for type-ahead; enable `show-value-help-icon` to expose the value-help trigger.
+  - Listen to `value-help-trigger` to open `sap.m.ValueHelpDialog` or `sap.ui.mdc.ValueHelp`.
+- **Gotchas:** `ui5-multi-input` extends `ui5-input` — all Input properties apply. Tokens are not automatically created on Enter; the app must handle `change` or `selection-change` and add token elements to the slot.
+
+---
+
+## RadioButton / Single Selection Visible
+
+- **SAPUI5:** `sap.m.RadioButton` / `sap.m.RadioButtonGroup`  **Web Component:** `ui5-radio-button` (`@ui5/webcomponents`)
+- **Use when:** User picks exactly one from a small set of options (≤ ~8) that should all be visible simultaneously without interaction.
+- **Do NOT use when:** More than ~8 options or options should stay hidden → `ui5-select` or `ui5-combobox`. Multiple selections allowed → CheckBox group. Immediate on/off toggle → `ui5-switch`.
+- **Rules:**
+  - Group radio buttons by setting the same `name` attribute — only one per group can be checked.
+  - Never use a standalone radio button that cannot be deselected; it will be permanently selected once clicked.
+  - Use `value` on each button to identify the selection on form submit.
+- **Gotchas:** A `ui5-radio-button` not in a group (`name` unset) cannot be unchecked once checked. In SAPUI5, prefer `sap.m.RadioButtonGroup` to manage selection state automatically.
+
+---
+
+## CheckBox / Confirmed Flag
+
+- **SAPUI5:** `sap.m.CheckBox`  **Web Component:** `ui5-checkbox` (`@ui5/webcomponents`)
+- **Use when:** A confirmed-on-save binary flag; selecting any combination from a group of independent options; intermediate/indeterminate state is needed.
+- **Do NOT use when:** The change should take immediate effect → `ui5-switch`. Exactly one of several options must be chosen → RadioButton group.
+- **Rules:**
+  - A CheckBox change takes effect only after the user explicitly saves — this is the semantic contract that distinguishes it from Switch.
+  - `indeterminate` state is set programmatically only — it cannot result from direct user interaction.
+  - Use the `text` property for the checkbox label; use an external `Label` for the group label.
+- **Gotchas:** `display-only` makes the checkbox non-interactive and not in the tab chain — use for review-mode forms. Do not use `disabled` when you mean `readonly`; disabled removes it from accessibility tree.
+
+---
+
+## Switch / Immediate Toggle
+
+- **SAPUI5:** `sap.m.Switch`  **Web Component:** `ui5-switch` (`@ui5/webcomponents`)
+- **Use when:** A setting that takes effect immediately on toggle — no save required. Examples: enable notifications, activate dark mode.
+- **Do NOT use when:** The change requires confirmation or save → `ui5-checkbox`. Multiple simultaneous selections → CheckBox group. Ambiguous meaning of on/off → `ui5-checkbox` (clearer semantics).
+- **Rules:**
+  - Always add an external `Label` or set `accessible-name` / `accessible-name-ref` — the switch alone conveys no context.
+  - `design="Graphical"` replaces text with icons (green check / red X) — use for semantic on/off states.
+  - Keep optional `text-on` / `text-off` to 3 characters maximum; longer strings are cut off.
+  - Do not put text inside the switch component — localization causes overflow.
+- **Gotchas:** Hover states are not supported on touch devices. Provide a `tooltip` when no label is visible.
+
+---
+
+## DatePicker / Single Date
+
+- **SAPUI5:** `sap.m.DatePicker`  **Web Component:** `ui5-date-picker` (`@ui5/webcomponents`)
+- **Use when:** Selecting a single date via calendar popup or typed entry.
+- **Do NOT use when:** Date + time needed → DateTimePicker. Date range → DateRangeSelection. Always-visible calendar → `sap.m.Calendar`. Month or year only → use `format-pattern` / `value-format` to configure date picker mode.
+- **Rules:**
+  - Set `min-date` and `max-date` (ISO `yyyy-MM-dd` format when `format-pattern` is not set) to restrict the selectable range at the source.
+  - Use `format-pattern` to set the display format; `value-format` to set the internal storage format.
+  - On phones the picker opens full-screen automatically — do not override.
+- **Gotchas:** Special dates, custom initial focus, "Today" shortcut button, and footer OK/Cancel are SAPUI5-only. The WC supports `hide-week-numbers` which SAPUI5 does not. The WC `date-value` property returns a JS `Date` object; use `date-value-async` when the component may not yet be fully initialized.
+
+---
+
+## DateRangeSelection / Date Range
+
+- **SAPUI5:** `sap.m.DateRangeSelection`  **Web Component:** none — no `ui5-date-range-picker` exists; use `sap.m.DateRangeSelection` (SAPUI5 only) or compose two `ui5-date-picker` controls in web component apps.
+- **Use when:** Selecting a start and end date in a single field.
+- **Do NOT use when:** Only a single date → `ui5-date-picker`. Start/end pickers must be independent (different pages/forms) → two separate DatePickers.
+- **Rules:**
+  - In SAPUI5, `sap.m.DateRangeSelection` extends `sap.m.DatePicker` — all DatePicker rules apply.
+  - Use `delimiter` property to configure the separator character displayed between dates.
+  - Access `dateValue` for start date and `secondDateValue` for end date.
+- **Gotchas:** No `ui5-date-range-picker` web component exists. In WC apps, use two `ui5-date-picker` elements with cross-validation logic.
+
+---
+
+## DateTimePicker / Date and Time
+
+- **SAPUI5:** `sap.m.DateTimePicker`  **Web Component:** none — no `ui5-date-time-picker` exists; use `sap.m.DateTimePicker` (SAPUI5 only) or compose `ui5-date-picker` + `ui5-time-picker` in WC apps.
+- **Use when:** Selecting both date and time in a single input field.
+- **Do NOT use when:** Date only → `ui5-date-picker`. Time only → `ui5-time-picker`.
+- **Rules:**
+  - In SAPUI5, popover always includes OK/Cancel buttons — the user must confirm.
+  - `minDate`/`maxDate` restrict both date and time range.
+  - Timezone display is SAPUI5-only — configure via local or global timezone settings.
+- **Gotchas:** No `ui5-date-time-picker` web component exists. Timezone, special dates, and minutes/seconds step configuration are SAPUI5-only features.
+
+---
+
+## TimePicker / Time Only
+
+- **SAPUI5:** `sap.m.TimePicker`  **Web Component:** `ui5-time-picker` (`@ui5/webcomponents`)
+- **Use when:** Selecting a time (hours, minutes, seconds) without a date.
+- **Do NOT use when:** Date + time → DateTimePicker. Date only → `ui5-date-picker`.
+- **Rules:**
+  - Configure `format-pattern` (e.g. `HH:mm:ss`) to control display; set `value-format` for the stored value format.
+  - Use `min-date` / `max-date` properties (as JS Date) to restrict the time range.
+  - `isValid()` method checks the entered value against the current format pattern.
+- **Gotchas:** The WC `ui5-time-picker` opens a clock-based picker — not a scroll wheel — on desktop. On mobile it uses a touch-friendly clock.
+
+---
+
+## StepInput / Numeric with Increment/Decrement
+
+- **SAPUI5:** `sap.m.StepInput`  **Web Component:** `ui5-step-input` (`@ui5/webcomponents`)
+- **Use when:** Adjusting a numeric quantity by a defined increment — quantities, counts, numeric settings.
+- **Do NOT use when:** Free numeric text entry without steps → plain `ui5-input` with `type="Number"`. Date/time input → use the dedicated pickers. Static identifier (ZIP code, phone) → `ui5-input`.
+- **Rules:**
+  - Set `min` and `max` to bound the range; the increment/decrement buttons auto-disable at bounds.
+  - Set `step` (default 1) and `value-precision` (decimal places) to match business requirements.
+  - Always label via an external `Label` — `StepInput` has no built-in label.
+- **Gotchas:** `value-precision` controls decimal display — if `step` is a float, ensure `value-precision` matches or the displayed value will be rounded unexpectedly.
+
+---
+
+## SearchField / Local Search
+
+- **SAPUI5:** `sap.m.SearchField`  **Web Component:** `ui5-search` (`@ui5/webcomponents-fiori`)
+- **Use when:** Filtering or searching a local list, table, or dataset on the current page. Cross-app / shell-level search belongs in the ShellBar search slot.
+- **Do NOT use when:** Filtering a table with many attributes → Filter Bar. Product-wide search → ShellBar `searchField` slot + `ui5-search` component.
+- **Rules:**
+  - `ui5-search` lives in `@ui5/webcomponents-fiori` — import from `@ui5/webcomponents-fiori/dist/Search.js`.
+  - Use the `search` event (Enter / Search button) to trigger filtering; use `input` for live filtering.
+  - Optionally add scope selection via `scopes` slot and a filter button via `filterButton` slot.
+- **Gotchas:** `ui5-search` is the WC equivalent for both `sap.m.SearchField` and the shell search field — the package differs from most input components (`@ui5/webcomponents-fiori` not `@ui5/webcomponents`). Do not use a plain `ui5-input` with `type="Search"` as a drop-in for `sap.m.SearchField` — it lacks the search button and events.
+
+---
+
+## Slider / Single Value Range
+
+- **SAPUI5:** `sap.m.Slider`  **Web Component:** `ui5-slider` (`@ui5/webcomponents`)
+- **Use when:** Selecting a single value along a continuous numeric range (volume, brightness, percentage).
+- **Do NOT use when:** Selecting a range (min + max) → `ui5-range-slider`. Selecting from a fixed list of categories → RadioButton or Select. Space is very limited on mobile → prefer Input with stepper.
+- **Rules:**
+  - Set `min`, `max`, and `step` to define the range and snap intervals.
+  - Enable `show-tooltip` (`editable-tooltip` recommended for accessibility) to display the current value on the handle.
+  - Enable `show-tickmarks` + `label-interval` to show visual step markers and labels.
+  - Custom scale labels (non-numeric) are SAPUI5-only.
+- **Gotchas:** The WC `ui5-slider` does not support custom scales or descriptive label strings on tick marks (SAPUI5 `sap.m.Slider` only). Always label what the slider controls — the component has no built-in label area.
+
+---
+
+## RangeSlider / Min–Max Range
+
+- **SAPUI5:** `sap.m.RangeSlider`  **Web Component:** `ui5-range-slider` (`@ui5/webcomponents`)
+- **Use when:** Selecting a value range (start and end) — price filter, date window, size range.
+- **Do NOT use when:** Single value → `ui5-slider`. Exact numeric input preferred → two StepInput fields.
+- **Rules:**
+  - `start-value` and `end-value` properties hold the two handle positions.
+  - Dragging the active track between handles moves the entire range at once.
+  - `editable-tooltip` converts the value indicators to inline input fields for precise entry.
+  - Custom scales are SAPUI5-only.
+- **Gotchas:** The two handles can swap positions when the user drags one past the other — this is intentional. Always account for `startValue > endValue` in your code or normalize after the `change` event.
+
+---
+
+## Filter Bar / Smart Filtering
+
+- **SAPUI5:** `sap.ui.comp.smartfilterbar.SmartFilterBar` (V2) / `sap.ui.mdc.FilterBar` (V4)  **Web Component:** none
+- **Use when:** The List Report, Analytical List Page, or Overview Page floorplan needs a collapsible filter area above a table or chart. The Filter Bar binds directly to OData metadata and manages filter state, "Go" / "Adapt Filters" buttons.
+- **Do NOT use when:** Object pages, wizards, simple lists, or forms — use a Search Field there. The data source is not OData or there are only 1–3 filters — use individual Input/Select/DatePicker controls.
+- **Rules:**
+  - In Fiori Elements, SmartFilterBar / FilterBar is annotation-driven (`@UI.SelectionFields`) — do not hand-code filter fields.
+  - Filter Bar manages its own state (Basic vs. All filters visibility) — do not re-implement the expand/collapse logic.
+  - Always pair with a "Go" button to trigger explicit search; avoid auto-search on every filter change.
+  - In freestyle apps, use `sap.ui.mdc.FilterBar` for V4; do not combine SmartFilterBar with V4 services.
+- **Gotchas:** No web component equivalent. `sap.ui.comp.smartfilterbar.SmartFilterBar` is SAP-internal (`@sap/ui5-core`); `sap.ui.mdc.FilterBar` is part of the `sap.ui.mdc` library and requires explicit enablement. Both are wrappers — never hand-build their internal structure.
+
+---
+
+## ValueHelpDialog / Complex Value Selection
+
+- **SAPUI5:** `sap.m.ValueHelpDialog` / `sap.ui.mdc.ValueHelp`  **Web Component:** none
+- **Use when:** The user needs to search, filter, and select from a large or complex dataset — too large for a ComboBox (>200 items) or requiring multi-attribute search or tabular display.
+- **Do NOT use when:** ≤ ~200 items with simple text matching → `ui5-combobox`. Short fixed list → `ui5-select`. Simple single-screen selection → SelectDialog.
+- **Rules:**
+  - Trigger from an `Input` or `MultiInput` via the value-help icon; open on `value-help-trigger` event.
+  - `sap.m.ValueHelpDialog` provides search, filter bar, and table — configure via its API; do not hand-build the dialog content.
+  - In V4 Fiori Elements apps, use `sap.ui.mdc.ValueHelp` tied to `FieldHelp` annotations instead.
+- **Gotchas:** No `ui5-*` web component equivalent exists. In WC-based apps, compose a `ui5-dialog` with a `ui5-table` + search manually, or use the `sap.ui.mdc.ValueHelp` shell when possible.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-lists-tables.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-lists-tables.md
new file mode 100644
index 0000000..a219e3a
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-lists-tables.md
@@ -0,0 +1,142 @@
+# UI Lists and Tables
+
+## Contents
+- [Table Type Decision](#table-type-decision)
+- [Responsive Table](#responsive-table)
+- [Grid Table](#grid-table)
+- [Analytical Table](#analytical-table)
+- [Tree Table](#tree-table)
+- [Grid List](#grid-list)
+- [List](#list)
+- [Upload Set with Table Plugin](#upload-set-with-table-plugin)
+
+---
+
+## Table Type Decision
+
+Choose by **data shape**, never by appearance.
+
+| Need | Control | SAPUI5 | Web Component |
+|---|---|---|---|
+| General-purpose, mobile + desktop, simple, up to ~200 rows | Responsive Table | `sap.m.Table` | `ui5-table` (popin mode) |
+| Large data, many columns, desktop-first, cell comparison | Grid Table | `sap.ui.table.Table` | none |
+| Aggregation: sums/subtotals per group (OData analytical binding) | Analytical Table | `sap.ui.table.AnalyticalTable` | none |
+| True parent-child hierarchy (BOM, org chart, cost centers) | Tree Table | `sap.ui.table.TreeTable` | none |
+| Card/tile visual layout with images, non-tabular | Grid List | `sap.f.GridList` | none |
+| Simple vertical item list, not columnar | List | `sap.m.List` | `ui5-list` |
+
+Decision order:
+1. **Hierarchy?** → Tree Table.
+2. **Aggregation/totals?** → Analytical Table.
+3. **Large (>~200 rows) or desktop cell-comparison?** → Grid Table.
+4. **Visual cards/tiles, not columns?** → Grid List.
+5. **Otherwise** → Responsive Table / `ui5-table`.
+
+Smart/MDC tables: `sap.ui.comp.smarttable.SmartTable` (V2) / `sap.ui.mdc.Table` (V4) are annotation-driven wrappers. Do not hand-build these.
+
+Common misuses:
+- **Responsive Table for 5,000 rows** → DOM bloat, single-column pop-in mush. Use Grid Table.
+- **Analytical Table with no aggregation** as a "nicer grid" → adds cost, breaks mobile. Use Grid Table.
+- **Grouping an Analytical Table to fake a hierarchy** → grouping is not nodes. Use Tree Table.
+- **`ui5-table` as a drop-in for grid/analytical/tree tables** → `ui5-table` supports `overflow-mode="Popin"` (equivalent to `sap.m.Table`) but has no aggregation, freeze, or hierarchy. There is no web-component grid/analytical/tree table.
+- **Grid List for text-heavy tabular data** because "cards look nice" → no column alignment or sort. Use Responsive Table.
+
+---
+
+## Responsive Table
+
+- **SAPUI5:** `sap.m.Table` **Web Component:** `ui5-table` (`@ui5/webcomponents`)
+- **Use when:** Up to ~200 rows; needs to work on mobile and desktop; content is line-item oriented; pop-in behavior for narrow screens is acceptable.
+- **Do NOT use when:** More than ~200 rows with performance concerns → use Grid Table; aggregation/totals needed → use Analytical Table; true hierarchy → use Tree Table; cell-comparison across many columns on desktop → use Grid Table.
+- **Rules:**
+  - Set `overflow-mode="Popin"` on `ui5-table` for responsive column behavior (equivalent to `sap.m.Table` pop-in).
+  - Use `ui5-table-header-row` + `ui5-table-header-cell` + `ui5-table-row` + `ui5-table-cell` — do not put raw `<tr>`/`<td>` inside.
+  - Selection features must be imported separately: `TableSelectionMulti`, `TableSelectionSingle` (WC).
+  - `rememberSelections` (SAPUI5 property) should be `false` when a Filter Bar triggers search — reset selections on each search.
+  - Show no more columns than fit ~80% of use cases; use pop-in / column hide for the rest.
+- **Gotchas:** `ui5-table` in `@ui5/webcomponents` is a popin-capable table only — it is NOT a drop-in replacement for `sap.ui.table.Table`, `AnalyticalTable`, or `TreeTable`. `TableVirtualizer` feature (WC) adds virtualization for large datasets but this still does not make it equivalent to the grid table.
+
+---
+
+## Grid Table
+
+- **SAPUI5:** `sap.ui.table.Table` **Web Component:** none — there is no `ui5-grid-table` or equivalent; do not substitute `ui5-table`.
+- **Use when:** Large datasets (hundreds to thousands of rows), desktop-first, many columns requiring horizontal scroll and freeze, cell-level comparison.
+- **Do NOT use when:** Mobile is a requirement → use Responsive Table with an adaptive fallback; aggregation with OData analytical binding → use Analytical Table; hierarchy → use Tree Table.
+- **Rules:**
+  - Always pair with a toolbar (`sap.m.OverflowToolbar`) — the grid table does not have a built-in title area.
+  - For column personalization with many columns, use `sap.m.p13n.Popup` (P13n Dialog), not `sap.m.ViewSettingsDialog`.
+  - Use the multi-selection plug-in (`sap.ui.table.plugins.MultiSelectionPlugin`) over multi-toggle mode for reliable select-all behavior with server-side data.
+  - Set `selectionBehavior` explicitly: `RowSelector` when row-click is used for navigation; `Row` otherwise.
+  - Horizontal scroll appears automatically when column widths exceed the table width — do not use percentage widths for tables with many columns.
+- **Gotchas:** No web component equivalent. Adaptive approach required for phones — provide a separate UI (e.g. Responsive Table or charts) for S screen sizes.
+
+---
+
+## Analytical Table
+
+- **SAPUI5:** `sap.ui.table.AnalyticalTable` **Web Component:** none — there is no WC analytical table; do not substitute `ui5-table`.
+- **Use when:** Aggregated data with OData analytical binding — summed/subtotaled cells per group, financial analysis, waterfall views, >1,000 rows with aggregation.
+- **Do NOT use when:** No aggregation is needed → use Grid Table; hierarchy (BOM, org) → use Tree Table; mobile is required → Analytical Table is desktop/tablet only.
+- **Rules:**
+  - Use `sap.ui.table.AnalyticalColumn` with `summed` property for aggregation columns.
+  - Multi-selection: strongly prefer the `MultiSelectionPlugin` over multi-toggle — it handles server-side data correctly.
+  - When setting a selection limit, enable `enableNotification` to show users when the limit is reached.
+  - Column freeze: set `enableColumnFreeze` on the table; freeze is triggered from the column header menu.
+  - Do not use grouping to simulate a hierarchy — use Tree Table for real parent-child nodes.
+- **Gotchas:** No web component. Not responsive — requires an adaptive approach (separate UI or chart fallback) for smartphones. `condensed` density must always be set together with `compact` — never use `condensed` alone or mix with `cozy`.
+
+---
+
+## Tree Table
+
+- **SAPUI5:** `sap.ui.table.TreeTable` **Web Component:** none — there is no WC tree table; do not substitute `ui5-table`.
+- **Use when:** True parent-child hierarchy data — bill of materials, org charts, cost center hierarchies, any structure where nodes have real children.
+- **Do NOT use when:** Data is flat with value-based grouping only → use Analytical Table's group feature; hierarchy is shallow (1–2 levels) and count is small → use a grouped Responsive Table or Tree control.
+- **Rules:**
+  - Bind via `ODataTreeBinding` or `JSONTreeBinding` — do not simulate a tree by manual nesting.
+  - Expand/collapse controls are automatic — do not add custom chevrons.
+  - For personalization with many columns, use `sap.m.p13n.Popup`.
+  - Column freeze, sort, and filter follow the same rules as Grid Table.
+- **Gotchas:** No web component. Desktop/tablet only — same adaptive requirement as Analytical and Grid tables. Do not use `sap.ui.table.AnalyticalTable` with grouping as a tree substitute — grouping clusters rows by value, it does not model parent-child nodes.
+
+---
+
+## Grid List
+
+- **SAPUI5:** `sap.f.GridList` **Web Component:** none — there is no `ui5-grid-list`; do not invent this tag.
+- **Use when:** Visual card/tile layout with images or rich preview content, non-tabular; tile-grid patterns on dashboards or catalog pages.
+- **Do NOT use when:** Data is columnar and requires sorting/filtering per column → use Responsive Table; items are simple text lines → use List.
+- **Rules:**
+  - Use `sap.f.GridListItem` (or custom items) — do not place raw `<div>` tiles inside `GridList`.
+  - Grid List does not provide column headers, column sort, or pop-in — do not add them manually.
+  - For selection, use the built-in `mode` property (`SingleSelect`, `MultiSelect`, `Delete`).
+- **Gotchas:** No web component equivalent. `sap.f.GridList` uses CSS Grid layout via `sap.ui.layout.cssgrid.GridBoxLayout` — do not try to control tile sizing with external CSS without considering the grid layout API.
+
+---
+
+## List
+
+- **SAPUI5:** `sap.m.List` / `sap.m.StandardListItem` / `sap.m.CustomListItem` **Web Component:** `ui5-list` / `ui5-li` / `ui5-li-custom` / `ui5-li-group` (`@ui5/webcomponents`)
+- **Use when:** Simple vertical item list — menus, settings lists, notification items, object lists without columnar data, side navigation items (but see note below).
+- **Do NOT use when:** Data is columnar with headers → use Responsive Table; items need persistent left-nav selection and expand/collapse → use `sap.f.SideNavigation` / `ui5-side-navigation`; visual card layout → use Grid List.
+- **Rules:**
+  - Use typed list items (`ui5-li`, `ui5-li-custom`, `ui5-li-group`) — do not put raw HTML children directly in `ui5-list`.
+  - Set `selection-mode` explicitly: `None` (default), `Single`, `Multiple`, `Delete`.
+  - Use `growing="Button"` or `growing="Scroll"` for large lists — do not load all items upfront.
+  - `sticky-header` keeps the header visible while scrolling — use it for long lists with a header.
+- **Gotchas:** `sap.m.List` has no nav semantics and no expand/collapse state — do not use it as an application side navigation. `ui5-list` items (`ui5-li`) support `type="Navigation"` for list-to-detail patterns but do not replace `ui5-side-navigation` for persistent app nav.
+
+---
+
+## Upload Set with Table Plugin
+
+- **SAPUI5:** `sap.m.upload.UploadSet` with table plugin **Web Component:** `ui5-upload-collection` (`@ui5/webcomponents-fiori`) for simple display; full managed upload uses `sap.m.upload.UploadSet` (no WC equivalent).
+- **Use when:** Managed file upload with progress, status, retry, and remove — a list of files to be uploaded or already uploaded, with full lifecycle management.
+- **Do NOT use when:** Single-file pick with no lifecycle management → use `sap.m.upload.FileUploader` / `ui5-file-uploader`; displaying an existing attachment list without upload actions → a plain List or Table suffices.
+- **Rules:**
+  - `UploadCollection` (old, `sap.m.UploadCollection`) is deprecated — do not use it for new development. Use `sap.m.upload.UploadSet` instead.
+  - `ui5-upload-collection` (`@ui5/webcomponents-fiori`) is a display/selection list for files — it does not provide the full upload lifecycle of `sap.m.upload.UploadSet`; use it only when display and simple interaction (delete/select) is all that is needed.
+  - In UploadSet, set `uploadUrl` and handle `beforeUploadStarts` / `uploadCompleted` events — do not handle the HTTP upload manually outside the control.
+  - Drag-and-drop overlay on `ui5-upload-collection`: set `hide-drag-overlay` to disable it if drag-drop is not supported.
+- **Gotchas:** `sap.m.UploadCollection` is deprecated — replace with `sap.m.upload.UploadSet`. No full-featured WC equivalent for `UploadSet`; `ui5-upload-collection` covers display only. Import: `import "@ui5/webcomponents-fiori/dist/UploadCollection.js"`.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-messages.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-messages.md
new file mode 100644
index 0000000..e2e2073
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-messages.md
@@ -0,0 +1,64 @@
+# UI Message Components
+
+## Contents
+- [Message Strip](#message-strip)
+- [Message Box](#message-box)
+- [Message Toast](#message-toast)
+- [Message Popover](#message-popover)
+
+---
+
+## Message Strip
+
+- **SAPUI5:** `sap.m.MessageStrip`  **Web Component:** `ui5-message-strip` (`@ui5/webcomponents`)
+- **Use when:** Displaying a persistent, non-blocking message scoped to a page, section, or single component (e.g., a table) that the user needs to see while working.
+- **Do NOT use when:** The message requires a decision or interruption → use `sap.m.MessageBox`; the message is a brief, transient success confirmation → use `sap.m.MessageToast` / `ui5-toast`; there are many validation errors → use `sap.m.MessagePopover`.
+- **Rules:**
+  - Always set `design` explicitly: `Negative`, `Critical`, `Positive`, or `Information`.
+  - Place the strip close to the content it describes — top of a section, not buried in a footer.
+  - Add a close button (`hide-close-button="false"`) for temporary/informational messages; omit it for persistent system-state messages.
+  - Show an icon (default: on) — only hide it when a custom icon via the `icon` slot is used instead.
+  - Keep text concise; use inline links (`ui5-link`) only to point to related details, not as primary actions.
+- **Gotchas:** `design="ColorSet1"` / `"ColorSet2"` do not render a default icon — you must supply one via the `icon` slot. The strip has no WC `valueState` prop; semantic color is set via `design`, not `value-state`.
+
+---
+
+## Message Box
+
+- **SAPUI5:** `sap.m.MessageBox`  **Web Component:** none — use `ui5-dialog` + `ui5-message-strip` manually
+- **Use when:** A semantic error, warning, success, or confirmation dialog is needed that interrupts the user and requires an explicit response before continuing.
+- **Do NOT use when:** The message is informational and non-blocking → use `sap.m.MessageStrip`; the message is a brief success toast → use `sap.m.MessageToast`; building in a web-component-only stack → compose `ui5-dialog` with an embedded `ui5-message-strip`.
+- **Rules:**
+  - Use the semantic static methods: `MessageBox.error()`, `.warning()`, `.success()`, `.confirm()`, `.information()`, `.show()` — never hand-build a Dialog for these cases in SAPUI5.
+  - Dialog title and button labels are auto-generated per type and locale — override only when semantics demand it.
+  - The `onClose` callback receives the button key pressed (`sap.m.MessageBox.Action.*`) — always handle all outcomes.
+  - One emphasized/primary button per dialog maximum.
+- **Gotchas:** `MessageBox` is a static utility class, not a control you instantiate — `new sap.m.MessageBox()` is wrong. In web-component apps there is no `ui5-message-box`; build with `ui5-dialog` and set `state` on a nested `ui5-message-strip` for coloring.
+
+---
+
+## Message Toast
+
+- **SAPUI5:** `sap.m.MessageToast`  **Web Component:** `ui5-toast` (`@ui5/webcomponents`)
+- **Use when:** Confirming a successful, low-stakes operation (save, send, delete) with a brief message the user does not need to act on.
+- **Do NOT use when:** The message is an error or warning that the user must see → use `sap.m.MessageStrip` or `sap.m.MessageBox`; the user must be able to copy the message text; the user must read it before leaving the page.
+- **Rules:**
+  - Keep text to one short sentence — the toast auto-dismisses and cannot be recalled.
+  - Default `duration` is 3000ms; the minimum is 500ms. Increase only for longer messages.
+  - Use `placement` to position (`BottomCenter` default; `TopCenter` in dialogs/panels where bottom is clipped).
+  - Show `open` to display; do not rely on mount/unmount cycling.
+- **Gotchas:** In SAPUI5, `MessageToast.show()` is a static call — it is not a view control. In web components, `<ui5-toast>` is a declarative element: set `open` to `true` to show it. The toast is not announced by screen readers as an alert by default — for critical notifications use a `MessageStrip` instead.
+
+---
+
+## Message Popover
+
+- **SAPUI5:** `sap.m.MessagePopover`  **Web Component:** none
+- **Use when:** Aggregating multiple validation messages (from multiple fields or sections) into one accessible, grouped entry point — typically in a page footer toolbar.
+- **Do NOT use when:** There is only one message → use `sap.m.MessageStrip`; the message requires a modal response → use `sap.m.MessageBox`; building in a pure web-component stack (no WC equivalent exists — build a custom solution).
+- **Rules:**
+  - Populate via `sap.m.MessageItem` — set `type`, `title`, `subtitle`, `description`, and `target` (control ID) for deep linking.
+  - Place the trigger button in the footer toolbar of the page or dialog, never inline in content.
+  - Display the count of messages on the trigger button; use the highest-severity icon.
+  - Do not use repeated `MessageStrip` instances to replace a `MessagePopover` — one strip per message creates visual clutter and is not navigable.
+- **Gotchas:** There is no `ui5-message-popover` tag. Do not invent one. In web-component apps, aggregate messages into a `ui5-responsive-popover` with a custom list — or switch to the SAPUI5 `sap.m.MessagePopover` control if the app shell allows it.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-navigation.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-navigation.md
new file mode 100644
index 0000000..ca29729
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-navigation.md
@@ -0,0 +1,91 @@
+# UI Navigation
+
+## Contents
+- [Icon Tab Bar](#icon-tab-bar)
+- [Tab Container](#tab-container)
+- [Segmented Button (cross-ref)](#segmented-button-cross-ref)
+- [Side Navigation](#side-navigation)
+- [Shell Search](#shell-search)
+- [Breadcrumbs](#breadcrumbs)
+
+---
+
+## Icon Tab Bar / In-page Section Navigation
+
+- **SAPUI5:** `sap.m.IconTabBar`  **Web Component:** `ui5-tabcontainer` (`@ui5/webcomponents`)
+- **Use when:** Navigating between sections or facets of a single page; filtering a list by category; visualizing process steps.
+- **Do NOT use when:** Editable browser-tab-style multi-document workspace → use TabContainer (`sap.m.TabContainer`). Switching between 2–3 views in a toolbar → use Segmented Button. Left-hand app navigation → use Side Navigation.
+- **Rules:**
+  - Text-only tabs: set `HeaderMode="Inline"` so counters appear in parentheses, not above the label. Disable `UpperCase` property; use title case.
+  - Icon-only tabs: use only when icons are universally recognizable; max 4–5 tabs.
+  - For process steps with fixed order, set `TabsOverflowMode="StartAndEnd"` so tabs don't reorder.
+  - Do not use cross-navigation (clicking tab A to open tab B) — it breaks back navigation.
+  - WC uses `ui5-tab` and `ui5-tab-separator` as children of `ui5-tabcontainer`.
+- **Gotchas:** The WC tag is `ui5-tabcontainer` — same tag name as TabContainer — but it maps to `sap.m.IconTabBar` semantics for in-page navigation. `sap.m.TabContainer` (browser-tabs editing paradigm) is a different control. Do not hide tabs with no content unless users cannot create content in them; show empty tabs that allow creation.
+
+---
+
+## Tab Container / Editable Multi-document Tabs
+
+- **SAPUI5:** `sap.m.TabContainer`  **Web Component:** `ui5-tabcontainer` (`@ui5/webcomponents`) — same WC tag, different semantic use
+- **Use when:** Browser-tab-style editing of multiple documents or entities side by side, each closeable and renameable (e.g. open multiple sales orders simultaneously).
+- **Do NOT use when:** In-page section/facet navigation → use IconTabBar (`sap.m.IconTabBar`). Simple 2–3 view switch → Segmented Button.
+- **Rules:**
+  - Tabs can be closed and reordered by users — implement `tab-close` event handler to remove the closed tab's data.
+  - Each tab represents an independent document or work item, not a section of one document.
+  - Do not use for read-only content sections — that is IconTabBar territory.
+- **Gotchas:** Both `sap.m.IconTabBar` and `sap.m.TabContainer` share the WC tag `ui5-tabcontainer`. The distinction is semantic and behavioral. In SAPUI5, they are entirely separate classes with different APIs. Choosing the wrong one is a frequent mistake — see the wrong→right table in SKILL.md.
+
+---
+
+## Segmented Button (cross-ref)
+
+See [ui-actions.md — Segmented Button](ui-actions.md#segmented-button) for the full entry.
+
+- **Use for navigation when:** Switching between 2–3 closely related views in a toolbar (not in-page section tabs).
+- **Do NOT use for:** In-page sections (5+ options, or needs counters) → IconTabBar. Left nav → Side Navigation.
+
+---
+
+## Side Navigation / Left Menu
+
+- **SAPUI5:** `sap.tnt.SideNavigation`  **Web Component:** `ui5-side-navigation` (`@ui5/webcomponents-fiori`)
+- **Use when:** Primary navigation across multiple application areas or modules — persistent left-hand menu with expandable groups.
+- **Do NOT use when:** Only a single navigation target exists. Structuring layout or implementing app-specific logic. On-page section switching → IconTabBar.
+- **Rules:**
+  - Always wrap `ui5-side-navigation` inside `ui5-navigation-layout` — standalone use breaks responsive behavior and misaligns ShellBar padding.
+  - First navigation item must be "Home" linking to the entry page.
+  - Keep navigation item labels short — wrapping is not supported in collapsed mode.
+  - Limit the fixed footer to max 4 elements (1 action button + 3 nav items); phone-first: 1 element only.
+  - Do not mix embedded and overlay modes in the same app; choose one.
+  - WC children: `ui5-side-navigation-group`, `ui5-side-navigation-item`, `ui5-side-navigation-sub-item`.
+- **Gotchas:** `ui5-side-navigation` is in `@ui5/webcomponents-fiori` — import from `@ui5/webcomponents-fiori/dist/SideNavigation.js`. On screens ≤ 599px (`size S`) the WC automatically switches to full-screen slide-in overlay regardless of embedded/overlay setting — this is expected behavior. Using `sap.m.List` as side navigation is the most common wrong-component error: List has no nav semantics, expand/collapse, or selection state.
+
+---
+
+## Shell Search / Cross-app Search
+
+- **SAPUI5:** Experimental — integrate via UI5 Web Components integration into SAPUI5  **Web Component:** `ui5-search` (`@ui5/webcomponents-fiori`)
+- **Use when:** Product-wide or cross-product search is required, surfacing results from across the entire application or suite, placed in the ShellBar.
+- **Do NOT use when:** Filtering a local list or table on the current page → use `sap.m.SearchField` / `ui5-search` without ShellBar context. Filtering with multiple attributes → Filter Bar.
+- **Rules:**
+  - Place `ui5-search` in the `searchField` slot of `ui5-shellbar`; set `show-search-field` on the ShellBar to make it visible.
+  - Keep the search field expanded by default (`disableSearchCollapse`) for better discoverability.
+  - Group results with `ui5-search-item-group` header items — do not present as a flat ungrouped list.
+  - Placeholder format: start with "Search"; add scope(s) if space allows — "Search in Sales", "Search for Devices".
+  - Do not overlay or dim the page when the search is active — the suggestion dropdown already provides visual separation.
+- **Gotchas:** `ui5-search` is in `@ui5/webcomponents-fiori` (`@ui5/webcomponents-fiori/dist/Search.js`) — same component used for both shell search and local search contexts, but shell usage requires ShellBar integration. The shell search is still marked experimental in SAPUI5. Autocomplete completes the first suggestion matching the input prefix — this may not be the topmost visual result depending on list ordering.
+
+---
+
+## Breadcrumbs / Navigation Trail
+
+- **SAPUI5:** `sap.m.Breadcrumbs`  **Web Component:** `ui5-breadcrumbs` (`@ui5/webcomponents`)
+- **Use when:** Showing the user's navigation path through a hierarchical app structure so they can jump back to any ancestor page.
+- **Do NOT use when:** There is no hierarchy (flat navigation) — breadcrumbs are meaningless without depth. The navigation history is browser-managed — use the browser's back button instead.
+- **Rules:**
+  - Use `ui5-breadcrumbs-item` children inside `ui5-breadcrumbs`; each item can carry an `href` for direct navigation.
+  - `design="Standard"` renders the last item as "current page" (bold, no separator, not a link) — do not make the current page a clickable link.
+  - `design="NoCurrentPage"` shows all items as links — use when the current page needs to be linkable.
+  - Call `event.preventDefault()` on `item-click` to handle navigation in-app (SPA routing) instead of browser URL change.
+- **Gotchas:** The last three breadcrumb items are visible directly; earlier items collapse into a dropdown. Do not put more than ~6–8 items in the trail — deep hierarchies become unusable. Do not use breadcrumbs as a substitute for a Back button in object pages — the ObjectPageLayout's anchor bar handles that.
diff --git a/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-upload.md b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-upload.md
new file mode 100644
index 0000000..96b07f3
--- /dev/null
+++ b/plugins/ui5/skills/ui5-fiori-guidelines/references/ui-upload.md
@@ -0,0 +1,48 @@
+# UI Upload Components
+
+## Contents
+- [File Uploader](#file-uploader)
+- [Upload Collection (deprecated)](#upload-collection-deprecated)
+- [Upload Set with Table Plugin](#upload-set-with-table-plugin)
+
+---
+
+## File Uploader
+
+- **SAPUI5:** `sap.ui.unified.FileUploader`  **Web Component:** `ui5-file-uploader` (`@ui5/webcomponents`)
+- **Use when:** The user needs to select and trigger upload of one (or a small number of) files with no requirement to manage, rename, reorder, or delete them after selection.
+- **Do NOT use when:** Users need to manage a list of uploads (rename, delete individual files, preview, track per-file status) → use `sap.m.plugins.UploadSetwithTable`; using the deprecated `sap.m.UploadCollection` → migrate to `UploadSetwithTable`.
+- **Rules:**
+  - Use the input-field variant by default — it shows selected file names inline; use the button-only variant (`hide-input="true"`) only when the surrounding layout provides visible file-name feedback.
+  - Restrict accepted file types via `accept` (comma-separated MIME types or extensions with a leading `.`).
+  - Set `max-file-size` (in MB) to enforce client-side size limits before upload.
+  - Use `multiple` only when the user genuinely needs to select several files at once.
+  - Reflect upload status (busy, success, error) via `value-state` and a `valueStateMessage` slot message.
+- **Gotchas:** Clicking the browse button always replaces the current selection — there is no "add more" mode. A batch error (any single file fails) blocks the entire batch — no partial uploads. The `change` event fires in Chrome even when the user cancels the OS dialog; guard against empty `files`.
+
+---
+
+## Upload Collection (deprecated)
+
+- **SAPUI5:** `sap.m.UploadCollection` — **DEPRECATED, do not use in new code**  **Web Component:** `ui5-upload-collection` (`@ui5/webcomponents-fiori`) — **legacy only**
+- **Use when:** Never in new development.
+- **Do NOT use when:** Always — replace with `sap.m.plugins.UploadSetwithTable` (SAPUI5) or `ui5-file-uploader` for simple cases.
+- **Rules:**
+  - Migrate existing `sap.m.UploadCollection` usage to `UploadSetwithTable`.
+  - The `ui5-upload-collection` WC tag still exists in `@ui5/webcomponents-fiori` for legacy apps but receives no new features.
+- **Gotchas:** `UploadCollection` is the classic control that preceded `UploadSet`. It lacks the table-based management model, plugin architecture, and modern rename/preview capabilities. Do not start new implementations with it.
+
+---
+
+## Upload Set with Table Plugin
+
+- **SAPUI5:** `sap.m.plugins.UploadSetwithTable`  **Web Component:** none (SAPUI5-only plugin)
+- **Use when:** Users need a managed upload list: upload multiple files, track per-file status, rename files, delete individual items, preview, or integrate upload into a table with custom columns.
+- **Do NOT use when:** Simple single-file upload with no management UI → use `sap.ui.unified.FileUploader` / `ui5-file-uploader`.
+- **Rules:**
+  - `UploadSetwithTable` is a `sap.m.plugins.DataStateIndicator`-compatible plugin attached to a `sap.m.Table` — it is not a standalone control.
+  - Configure upload endpoint via the `uploadUrl` property on the plugin; handle `beforeUploadStarts`, `uploadCompleted`, and `uploadTerminated` events.
+  - Each row maps to one file via `sap.m.plugins.UploadSetwithTableItem`; bind file-level status (uploading, complete, error) to the item's `uploadState` property.
+  - For rename: set `fileNameEditable` to enable inline editing of the file name token.
+  - Enforce allowed file types and size limits at both plugin level and server side.
+- **Gotchas:** There is no `ui5-upload-set-table` or `ui5-upload-set` WC tag — this feature does not exist in `@ui5/webcomponents` or `@ui5/webcomponents-fiori`. Web-component-only apps must compose their own file-management table using `ui5-table` + `ui5-file-uploader`. `UploadSetwithTable` replaces the older `sap.m.UploadSet` control as well as the deprecated `sap.m.UploadCollection`.