diff --git a/.cursor/rules/ui5-knowledge-base.mdc b/.cursor/rules/ui5-knowledge-base.mdc
new file mode 100644
index 0000000000000..fc82a344c04b5
--- /dev/null
+++ b/.cursor/rules/ui5-knowledge-base.mdc
@@ -0,0 +1,29 @@
+---
+description: UI5 Web Components conventions and guardrails. Consult before editing component code.
+globs:
+  - packages/**/*.ts
+  - packages/**/*.tsx
+  - packages/**/*.css
+  - packages/**/cypress/specs/**/*.cy.tsx
+alwaysApply: false
+---
+
+# UI5 Web Components — AI Knowledge Base
+
+Detailed conventions, guardrails, and good/bad examples live in the AI Knowledge Base at
+`ai-knowledge-base/`. It is the authority on how to write code here.
+
+Before editing this file, read `ai-knowledge-base/INDEX.md`, find your task in its routing table,
+and open the **one** reference file it names — do not read every file. Only the rules that apply to
+your task cost context.
+
+Non-negotiables (full rationale in `ai-knowledge-base/INDEX.md`):
+
+- Never run the full test suite. Run one spec: `yarn test:cypress:single cypress/specs/<Component>.cy.tsx`.
+- Enums are type-only: `import type`, declare as `` `${X}` ``, compare against string literals.
+- Select by attribute, never tag name: `[ui5-button]` in CSS, `querySelector`, and specs.
+- No `instanceof` against a UI5 class. Use `createInstanceChecker` with a duck-typing marker.
+- `@query` refs are for method calls like `.focus()`; set child state through the template.
+- Make the smallest change that solves the problem. No opportunistic cleanup.
+
+When done, check your work: `yarn ts`, `yarn lint`, and `yarn lint:scope`.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 4d7f455b12637..5758cab220ea5 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -2,6 +2,10 @@
 
 When reviewing pull requests to UI5 Web Components project, follow these guidelines:
 
+## AI Knowledge Base
+
+  Detailed conventions, guardrails, and good/bad examples live in the **AI Knowledge Base** at [`ai-knowledge-base/`](../ai-knowledge-base/). When a change touches a `.ts`, `.tsx`, or `.css` file under `packages/`, a Cypress spec, or a `ui5-*` component/property/slot/event/design token/ARIA attribute, consult [`ai-knowledge-base/INDEX.md`](../ai-knowledge-base/INDEX.md) and open the one reference file its routing table names for the area under review. Review the diff against those rules.
+
 ## Commit Message and PR Title Validation
 
 Check that commit messages and PR titles follow the [Conventional Commits](https://conventionalcommits.org) specification as outlined in [Conventions and guidelines](../docs/5-contributing/02-conventions-and-guidelines.md):
diff --git a/AGENTS.md b/AGENTS.md
index 12c85d30c81e0..a411bd51289fd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,6 +2,22 @@
 
 This file provides guidance for AI coding assistants (Claude, Copilot, Cursor, etc.) when working with this repository.
 
+## Knowledge Base — read this first
+
+Detailed conventions, guardrails, and good/bad examples live in the **AI Knowledge Base** at
+`ai-knowledge-base/`. It is the authority on how to write code here. Load it **on demand**,
+not up front: it has a routing table that points you to the one reference file your task needs.
+
+**Read `ai-knowledge-base/INDEX.md` before you edit code whenever any of these is true:**
+
+- You add, change, review, or test a `.ts`, `.tsx`, or `.css` file under `packages/`.
+- You write or debug a Cypress spec.
+- The task names a `ui5-*` component, a property, slot, event, design token, or ARIA attribute.
+
+Then open **only** the reference file its routing table names for your task — do not read every file.
+If your work is purely conversational, a docs-only edit, or a question that touches no component code,
+you do not need it.
+
 ## Project Overview
 
 UI5 Web Components is an enterprise-grade, framework-agnostic web components library implementing SAP Fiori design. It's a Yarn-based monorepo using Lerna and Yarn Workspaces.
@@ -28,6 +44,7 @@ packages/
 ### Root Level (Always run from repo root)
 ```bash
 yarn start       # Start dev server with watch mode (recommended for development)
+yarn ts          # TypeScript type-check (use this to verify compilation)
 yarn build       # Full production build
 yarn lint        # Lint all packages
 ```
@@ -71,19 +88,9 @@ Remove `.only` before committing and run the full test file for final verificati
 
 ## Component Development
 
-For detailed component architecture, development rules, and testing patterns, see [`packages/base/AGENTS.md`](./packages/base/AGENTS.md).
-
-### Quick Reference
-
-| Rule | Bad | Good |
-|------|-----|------|
-| Enum imports | `import Enum from "..."` | `import type Enum from "..."` |
-| Enum types | `prop: Enum` | `prop: \`${Enum}\`` |
-| Enum values | `Enum.Value` | `"Value"` |
-| DOM queries | `querySelector("ui5-tag")` | `querySelector("[ui5-tag]")` |
-| CSS selectors | `ui5-tag { }` | `[ui5-tag] { }` |
-| Type checks | `instanceof Component` | `isInstanceOfComponent(el)` |
-| DOM mutation | `this._ref.value = x` | Template: `<Comp value={x} />` |
+For component architecture, coding rules, testing patterns, and the full bad/good examples, read the
+AI Knowledge Base and follow its routing table (see "Knowledge Base" above). Package-specific
+base-class detail lives in [`packages/base/AGENTS.md`](./packages/base/AGENTS.md).
 
 ## Commit Message Format
 
diff --git a/ai-knowledge-base/INDEX.md b/ai-knowledge-base/INDEX.md
new file mode 100644
index 0000000000000..553bf7ead9848
--- /dev/null
+++ b/ai-knowledge-base/INDEX.md
@@ -0,0 +1,114 @@
+---
+name: ui5-knowledge-base
+description: Conventions and patterns for writing UI5 Web Components code in this repository. Use when adding, changing, reviewing, or testing any .ts, .tsx, or .css file under packages/, when writing a Cypress spec, or when a task names a ui5-* component, property, slot, event, design token, or ARIA attribute.
+---
+
+# UI5 Web Components — AI Knowledge Base
+
+Guidance for any AI coding tool (Claude, Cursor, Copilot, or other). This is a reference bundle, not a
+tool-specific plugin: read the **one** file the routing table names for your task, and nothing more.
+
+Find your task in the routing table and open the one file it names.
+
+## Non-negotiables
+
+1. Never run the full test suite. Run one spec: `yarn test:cypress:single cypress/specs/<Component>.cy.tsx`.
+2. Enums are type-only: `import type X`, declare the property as `` `${X}` ``, compare against string literals.
+3. Select by attribute, never by tag name: `[ui5-button]` in CSS, in `querySelector`, and in specs.
+4. No `instanceof` against a UI5 class. Use `createInstanceChecker` with a duck-typing marker.
+5. `@query` refs exist to call methods like `.focus()`. Set child state through the template instead.
+6. Make the smallest change that solves the problem. No opportunistic cleanup, no drive-by refactors.
+
+## Routing table
+
+| Your task | Open |
+|-----------|------|
+| Changing component code, and you are not sure what applies | `references/core-rules.md` |
+| Reviewing a diff, or checking your own work before declaring done | `references/core-rules.md` (Reviewing a diff) |
+| Adding or changing a property, slot, event, or public method | `references/api-design.md` |
+| Understanding how a component is assembled, or which file does what | `references/component-anatomy.md` |
+| Creating a brand-new component | `references/new-component.md` |
+| Writing, fixing, or debugging a Cypress test | `references/testing.md` |
+| CSS, theming, design tokens, RTL, `::part`, `:host` | `references/theming-and-css.md` |
+| Keyboard navigation, ARIA, focus, screen reader output | `references/accessibility.md` |
+| Any text a user can see | `references/i18n.md` |
+| Unnecessary re-renders, slow interaction, invalidation | `references/performance.md` |
+| A test that passes locally and fails in CI | `references/testing.md`, then `references/performance.md` |
+| Build fails with a documentation error | `references/api-design.md` (CEM validation) |
+
+## Commands
+
+### From the repository root
+
+| Command | What it does |
+|---------|--------------|
+| `yarn ts` | `tsc -b` across all packages. This is the type-check |
+| `yarn generate` | Compiles `.css` and `.properties` into `src/generated/**`. Required on a clean checkout before `yarn ts` |
+| `yarn lint` | ESLint across all packages |
+| `yarn lint:scope` | Fails on tag-name selectors in `src/**/*.css` and `querySelector("ui5-...")` in `src/**/*.ts` |
+| `yarn start` | Runs `generate` once, builds the Cypress helper packages, then starts the dev server with per-package watchers |
+
+### From a package folder
+
+```bash
+cd packages/main
+yarn test:cypress:single cypress/specs/Button.cy.tsx   # one spec
+yarn test:cypress:open                                 # interactive runner
+yarn lint
+yarn lint:scope
+```
+
+## Debugging
+
+Start at the top and stop as soon as you have an answer: read the neighbouring component, then
+`yarn ts`, then one spec with `.only`, then `yarn start` and a test page.
+
+From the root dev server the page is `packages/main/test/pages/<Component>.html`; from a package-level
+`yarn start` it is `test/pages/<Component>.html`. The port is chosen at startup — read it from the console.
+
+In the DevTools console:
+
+```js
+const el = document.querySelector("[ui5-button]");
+el.getDomRef()      // the component's root shadow element
+el.isUI5Element     // confirm it upgraded
+```
+
+When a spec fails, in order: read the assertion rather than the stack; rerun that case with `.only`;
+confirm the component upgraded, since one missing from `bundle.esm.ts` mounts with an empty shadow
+root; check for async focus (`references/testing.md`); then throttle the CPU. If it still
+fails under throttling it is a product bug, not a test bug.
+
+One thing accounts for most interaction bugs here: handlers that read `event.target` break when the
+event crosses a shadow boundary — use `composedPath()` instead.
+
+| Build symptom | Cause |
+|---------------|-------|
+| `Missing default value for 'x'` | A public property without `@default` |
+| `Type 'X' is used to describe a public API but is not exported` | Add it to `export type { ... }` |
+| `Boolean properties must be initialzed to false` | Invert the property name (the typo is in the real message) |
+| Scope lint failure | A tag-name selector in CSS or TS |
+| Cannot find `./generated/...` | Run `yarn generate` |
+| Unresolved i18n constant | The key is in the properties file but not in `i18n-defaults.ts` |
+
+## Checking your work
+
+Before declaring a task done: `yarn ts` for types, `yarn lint` for style, and `yarn lint:scope` to
+catch tag-name selectors and `querySelector("ui5-...")`. Then re-read `references/core-rules.md`
+(Reviewing a diff) and confirm your change respects each non-negotiable above.
+
+## When sources disagree
+
+1. `references/` in this skill governs how you write new code. The rules are absolute even where
+   existing code disagrees; each one records how much legacy code violates it so you can recognise
+   the violation rather than copy it.
+2. Neighbouring source code governs structure and idiom — file layout, naming, how a template is put
+   together. Copy its shape, not its rule violations. `Button.ts` is the reference component and it
+   still uses runtime enum imports.
+
+## Keeping this accurate
+
+Add a learning here only when it is a repeatable rule that applies beyond one component. One-off
+incidents don't belong here.
+
+Cite files without line numbers and state rules without counts — both go stale on unrelated commits.
diff --git a/ai-knowledge-base/SKILL.md b/ai-knowledge-base/SKILL.md
new file mode 100644
index 0000000000000..0052b4a7effc6
--- /dev/null
+++ b/ai-knowledge-base/SKILL.md
@@ -0,0 +1,12 @@
+---
+name: ui5-knowledge-base
+description: Conventions and patterns for writing UI5 Web Components code in this repository. Use when adding, changing, reviewing, or testing any .ts, .tsx, or .css file under packages/, when writing a Cypress spec, or when a task names a ui5-* component, property, slot, event, design token, or ARIA attribute.
+---
+
+# UI5 Web Components — AI Knowledge Base (Claude skill entry)
+
+This is the Claude-discoverable entry point. The canonical, tool-neutral index — routing table,
+non-negotiables, commands, and debugging — lives in [`INDEX.md`](./INDEX.md) next to this file.
+
+Read `INDEX.md`, find your task in its routing table, and open the **one** reference file it names.
+Do not read every file. If the task touches no component code, you do not need this bundle.
diff --git a/ai-knowledge-base/references/accessibility.md b/ai-knowledge-base/references/accessibility.md
new file mode 100644
index 0000000000000..db19565d0c3af
--- /dev/null
+++ b/ai-knowledge-base/references/accessibility.md
@@ -0,0 +1,187 @@
+# Accessibility
+
+## The accessibility API
+
+Interactive components expose this surface. Match the names exactly.
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `accessibleName` | string | Direct label text |
+| `accessibleNameRef` | string | Space-separated IDs of elements whose text forms the label |
+| `accessibleDescription` | string | Longer description |
+| `accessibleDescriptionRef` | string | IDs of elements forming the description |
+| `accessibleRole` | `` `${SomeRole}` `` | Overrides the default ARIA role |
+| `accessibilityAttributes` | `AccessibilityAttributes` | `expanded`, `hasPopup`, `controls`, `role`, `ariaLabel`, ... |
+
+Components opt into a subset — not every one carries all six. `accessibleDescriptionRef` in particular is absent from many (Button, Link, Icon).
+
+`AccessibilityAttributes` is a real type, not a free-form object. Narrow it per component with `Pick`: `type ButtonAccessibilityAttributes = Pick<AccessibilityAttributes, "expanded" | "hasPopup" | "controls" | "ariaKeyShortcuts" | "ariaLabel">`. Not every `*AccessibilityAttributes` type is a `Pick`, though — `ListAccessibilityAttributes` is a bespoke nested object (`{ growingButton?: { name?, description? } }`), unrelated to the base type. Check the actual declaration before assuming.
+
+### Resolving the texts
+
+Every helper below comes from `@ui5/webcomponents-base/dist/util/AccessibilityTextsHelper.js`. `getEffectiveAriaLabelText(el)` returns the `accessibleNameRef` texts, else `accessibleName`. It does **not** resolve native `<label for>` — a form control must combine both:
+
+```ts
+get ariaLabelText() {
+  return getEffectiveAriaLabelText(this) || getAssociatedLabelForTexts(this);
+}
+```
+
+| Helper | Returns |
+|--------|---------|
+| `getEffectiveAriaLabelText(el)` | ref texts, else `accessibleName`, else `undefined` |
+| `getEffectiveAriaDescriptionText(el)` | ref texts, else `accessibleDescription`, else `undefined` |
+| `getAllAccessibleNameRefTexts(el)` | joined text of the `accessibleNameRef` targets |
+| `getAllAccessibleDescriptionRefTexts(el)` | joined text of the `accessibleDescriptionRef` targets |
+| `getAssociatedLabelForTexts(el)` | joined text of `<label for={this.id}>` |
+
+### Keeping the ref texts live
+
+`registerUI5Element` in `onEnterDOM` observes the targets of **both** `accessibleNameRef` and `accessibleDescriptionRef`. Call `deregisterUI5Element(this)` in `onExitDOM`. The registered callback refreshes whichever ref texts the component actually reads — there is no single canonical method. Names and fields vary: `List` uses `_updateAssociatedLabelsTexts` refreshing both name and description ref texts; `Button` uses `_updateAccessibleNameRefTexts` (name only); `Input` refreshes label-for, name and description texts under different field names. Copy the shape, not the exact identifiers:
+
+```ts
+// List's variant — mirror the fields your component reads, don't paste verbatim
+_updateAssociatedLabelsTexts() {
+  this._associatedDescriptionRefTexts = getAllAccessibleDescriptionRefTexts(this);
+  this._associatedLabelsRefTexts = getAllAccessibleNameRefTexts(this);
+}
+```
+
+## Wiring ARIA in the template
+
+ARIA and `tabindex` go on the focusable inner element, **never on the host**. Two patterns exist for marking that element:
+
+- **`data-sap-focus-ref`** — an explicit marker (Button's inner `<button>`). Use when the focus target isn't the first shadow child.
+- **First shadow child** — most form components (CheckBox, RadioButton, Link) put ARIA/`tabindex`/`role` on the first element in the shadow root and skip the marker entirely; `getFocusDomRef()` falls back to `shadowRoot.children[0]`. This is the majority pattern.
+
+`data-sap-focus-ref` is therefore optional, not required.
+
+```tsx
+disabled={this.disabled}
+data-sap-focus-ref
+tabindex={this.tabIndexValue}
+aria-expanded={this._computedAccessibilityAttributes?.expanded}
+aria-label={this._computedAccessibilityAttributes?.ariaLabel}
+aria-description={this.ariaDescriptionText}
+role={this.effectiveAccRole}
+```
+
+- `aria-disabled={false}` renders as the literal string `"false"`; return `undefined` instead.
+- Bundle many ARIA outputs into one getter the template reads (e.g. an `accInfo` getter feeding the template).
+- Expose an `accessibilityInfo` getter so containers can describe a slotted child.
+
+## Focus
+
+`delegatesFocus: true` in `shadowRootOptions` lets a native `element.focus()` from an application reach the inner control when the host itself isn't focusable. It is **not** required for every focusable component — only a few use it (Button, ColorPicker, ColorPaletteItem). Most focusable components (CheckBox, RadioButton, Input, Link, Switch, Slider, Select) put `tabindex` on their inner shadow child and rely on the `getFocusDomRef()` fallback instead.
+
+| API | Purpose | Source |
+|-----|---------|--------|
+| `getFocusDomRef()` | The `[data-sap-focus-ref]` element, else the root | `UI5Element.ts` |
+| `getFocusDomRefAsync()` | Same, after `_waitForDomRef()` | `UI5Element.ts` |
+| `focus(options?)` | Async — awaits rendering | `UI5Element.ts` |
+| `getFirstFocusableElement(el)` | Deep first focusable descendant | `FocusableElements.ts` |
+| `getLastFocusableElement(el)` | Deep last focusable descendant | `FocusableElements.ts` |
+| `Popover.focusOpener()` | Returns focus to the opener | `Popover` |
+
+`ItemNavigation` focuses items through `getFocusDomRef()`; F6 lands a group on `getFirstFocusableElement()`.
+
+## Keyboard
+
+Use the predicates from `Keys.js`, never a raw `event.key` comparison — they encode the modifier rules. `isEnter`, `isSpace`, `isUp`, `isDown`, `isHome`, `isEnd` and `isEscape` follow the same shape. `preventDefault()` on Space, or the page scrolls.
+
+| Predicate | Matches | Source |
+|-----------|---------|--------|
+| `isTabNext` / `isTabPrevious` | Tab / Shift+Tab | `Keys.ts` |
+| `isPageUp` / `isPageDown` | PageUp / PageDown, no modifiers | `Keys.ts` |
+| `isShow` | F4, or Alt+ArrowDown / Alt+ArrowUp — open a picker | `Keys.ts` |
+| `isF6Next` | F6 or Ctrl+Alt+Down | `Keys.ts` |
+| `isF6Previous` | Shift+F6 or Ctrl+Alt+Up | `Keys.ts` |
+
+### F6 fast navigation
+
+`fastNavigation: true` in `@customElement` does exactly one thing: `UI5Element` sets `data-sap-ui-fastnavgroup="true"` on the host. Two more pieces are required.
+
+- The application must import the feature or nothing listens for the key: `import "@ui5/webcomponents-base/dist/features/F6Navigation.js"`.
+- Handlers react through `isF6Next` / `isF6Previous`, which also cover Shift+F6 and Ctrl+Alt+Arrow.
+- Any element carrying `data-sap-ui-fastnavgroup="true"` is a group; it need not be a UI5 component.
+
+### Roving tabindex with `ItemNavigation`
+
+An item group is a single tab stop. `ItemNavigation` computes which item is current and writes `"0"` / `"-1"` into each item's `forcedTabIndex` property; it never touches the DOM `tabindex` attribute directly — the item maps `forcedTabIndex` onto its rendered `tabindex` (see below).
+
+```ts
+import NavigationMode from "@ui5/webcomponents-base/dist/types/NavigationMode.js";
+this._itemNavigation = new ItemNavigation(this, {
+  skipItemsSize: PAGE_UP_DOWN_SIZE,
+  navigationMode: NavigationMode.Vertical,
+  getItemsCallback: () => this.getEnabledItems(),
+});
+```
+
+| Option | Meaning |
+|--------|---------|
+| `getItemsCallback` | Required. Returns the navigable items |
+| `navigationMode` | `Auto` (both axes), `Horizontal`, `Vertical` |
+| `rowSize` | Items per row when `navigationMode: Auto` |
+| `behavior` | `Static` stops at the ends, `Cyclic` wraps |
+| `skipItemsSize` | Items `PageUp` / `PageDown` jump |
+| `affectedPropertiesNames` | Root properties to reassign so the root re-renders |
+
+`NavigationMode.Paging` exists in the enum but has no usages, and `_onkeydown` branches only on `Horizontal`, `Vertical` and `Auto` — selecting it disables arrow navigation. Use only those three. The behavior member is `ItemNavigationBehavior.Cyclic`; the constructor param JSDoc's "Cycling" is wrong.
+
+Call `setCurrentItem(item)` when a click selects an item, and `setRowSize(n)` when a grid's column count changes.
+
+**Arrow keys do nothing unless the current item already holds focus** — `_canNavigate()` compares `_getCurrentItem()` with `getActiveElement()`. This explains most reports of broken arrow navigation.
+
+Items must expose `forcedTabIndex` as an `@property()` — `ItemNavigation` writes `"0"` / `"-1"` into it, and on a `UI5Element` item the decorator is what triggers the re-render that flushes the new `tabindex`. A plain class field will not re-render. The item maps it onto the rendered `tabindex`:
+
+```ts
+get _effectiveTabIndex() {
+  if (!this._focusable) {
+    return -1;
+  }
+  if (this.selected) {
+    return 0;
+  }
+  return this.forcedTabIndex ? parseInt(this.forcedTabIndex) : undefined;
+}
+```
+
+`_focusable` is `!this.disabled`; filter the items callback on it so disabled items are skipped. If items are plain `{ id, forcedTabIndex }` objects rather than `UI5Element`s, name the owning root property in `affectedPropertiesNames` so the re-render happens.
+
+In a container `onKeyDown`, resolve the intended item from `event.composedPath()`, not `e.target` — the handler receives keydowns from every descendant, and treating a non-item target as an item steals focus back into the group.
+
+### `div` with `role="button"`
+
+Check disabled first and bail with `preventDefault`. Fire the action on Enter in `onKeyDown`; `preventDefault` Space in `onKeyDown` and fire it in `onKeyUp`, matching native button timing. Pairing these with `onMouseDown` does not double-fire, because browsers do not fire `mousedown` on keyboard activation of a `<div>`.
+
+## Announcing dynamic changes
+
+Use the shared live region, not a hand-rolled `aria-live` element:
+
+```ts
+import announce from "@ui5/webcomponents-base/dist/util/InvisibleMessage.js";
+announce(selectedText, "Polite");
+```
+
+Both `announce(text, "Polite")` and `announce(text, InvisibleMessageMode.Polite)` are valid — `InvisibleMessageMode` is a const-object, and most call sites access its members. The string literal is accepted by the signature and reads cleaner, but the enum form is not a rule violation. Compose the text from the i18n bundle first — build "option text + position" before announcing. See `i18n.md`.
+
+## Disabled state
+
+Split by element type; a natively `disabled` element needs no `aria-disabled`.
+
+- Native control — render the native attribute and drop the tabindex: `disabled={this.disabled}` in the template, with a `tabIndexValue`-style getter returning `undefined` when disabled. The native `<button disabled>` / `<input disabled>` already removes itself from the tab order and needs no `aria-disabled`.
+- Non-native role — bind `aria-disabled` (`true` / `undefined`, never `false`) and force the tabindex to `-1` when disabled. Naming varies by component (`_ariaDisabled`, `isDisabled`, `accInfo.ariaDisabled`; `_effectiveTabIndex` or an inline ternary) — match the component you're in rather than assuming one canonical getter name.
+
+## Checklist
+
+- [ ] `delegatesFocus: true` in `shadowRootOptions`
+- [ ] ARIA and `tabindex` on the inner focusable element (`[data-sap-focus-ref]` or first shadow child), never the host
+- [ ] `accessibleName` / `accessibleNameRef` via the helpers, plus `<label for>` for form controls
+- [ ] `ItemNavigation` for item groups, with `forcedTabIndex` bound in the template
+- [ ] `role="button"` fires Enter on `onKeyDown` and Space on `onKeyUp`
+- [ ] `Escape` closes the popup, and `focusOpener()` returns focus to the trigger
+- [ ] Disabled expressed natively or via `aria-disabled`, and removed from tab order
+- [ ] Every announced or rendered string comes from the i18n bundle
+
+This repo has no axe or automated accessibility tooling. Coverage means an explicit Cypress test — `cy.realPress` plus focus and attribute assertions.
diff --git a/ai-knowledge-base/references/api-design.md b/ai-knowledge-base/references/api-design.md
new file mode 100644
index 0000000000000..97ecc7db54db2
--- /dev/null
+++ b/ai-knowledge-base/references/api-design.md
@@ -0,0 +1,407 @@
+# Public API Design
+
+Properties, slots, events, methods, CSS parts, and the JSDoc that documents them.
+
+JSDoc is validated when the Custom Elements Manifest is generated, by `yarn generateAPI`. Neither
+`yarn ts` nor `yarn start` runs it, so a documentation error is invisible while you type and fails
+later. Run `yarn generateAPI` before declaring an API change done.
+
+`core-rules.md` carries the declarative-API rule and the rules on event ordering, boolean defaults,
+and strict decorators. This file covers how to shape and document the API, not why.
+
+## Choosing the mechanism
+
+| The application needs to… | Use |
+|---------------------------|-----|
+| Configure a value or a mode | property — `design`, `disabled`, `placeholder` |
+| Put the component into a state | property — `open`, `collapsed`, `selected` |
+| Supply markup, or a component the host must talk to | slot — `content`, `header`, `valueStateMessage` |
+| React to something the user did | event — `click`, `selection-change` |
+| Restyle an internal element | CSS part |
+| Add an optional capability that carries its own API | a slotted subcomponent — see Features below |
+| Compute something the property model cannot express | public method |
+
+Prefer a property. A public method is justified in three cases and no others: a pure computation over
+an argument (`isValidValue(value)`, `formatValue(date)`), a transient action with no resting state
+(`navigateTo`, `reset`, `closeOverflow`), or handing out a DOM reference. A method that would only
+flip a boolean the application already owns should be a property.
+
+`open` is the canonical state property. It is inherited from `Popup` by `Popover`, `Dialog`, and
+`ResponsivePopover` rather than redeclared, and also exists on `Menu`, `Input`, `ComboBox`,
+`MultiComboBox`, `Toast`, and the pickers. `Select` does **not** expose one — it tracks open state
+in `opened`, marked `@private` (so it's out of the public API and docs), though it still reflects as
+an attribute since it isn't `noAttribute`.
+
+### Writing your own public property
+
+A component writes its own public property when a user interaction or its own lifecycle changes that
+state, then fires the matching event in the same handler. This is the normal pattern, not an
+exception — `CheckBox.checked`, `Panel.collapsed`, and `Input.value` all follow it.
+
+```ts
+_afterPopoverClose() {
+	this.open = false;
+	this.fireDecoratorEvent("close");
+}
+```
+
+What is forbidden is different: never write to a *child or sibling* component's public property from
+JavaScript — pass the value through the template — and never write your own public property from a
+timer, observer, or fetch callback. See `core-rules.md`.
+
+### Features: capability as a slotted subcomponent
+
+When an optional capability carries its own properties, events, state, and bundle cost, model it as a
+subcomponent the application slots in rather than as properties on the host.
+
+For example `Table` has one `features` slot typed to an `ITableFeature` interface that declares lifecycle hooks (`onTableActivate`, `onTableBeforeRendering`, `onTableAfterRendering`), and looks features up by a string `identifier`, never by class. Because `TableSelectionMulti`, `TableGrowing`, and `TableVirtualizer` are separate imports, a table that does not select does not pay for selection.
+
+## Properties
+
+```ts
+/**
+ * Defines the component design.
+ * @default "Default"
+ * @public
+ */
+@property()
+design: `${ButtonDesign}` = "Default";
+```
+
+`type`, `noAttribute`, and `converter` are the only options that exist.
+
+| Option | Effect |
+|--------|--------|
+| `@property()` | String, reflected as an attribute. `{ type: String }` is the same thing written out |
+| `{ type: Number }` | Reflected. Never coerces — assigning a string stores the string |
+| `{ type: Boolean }` | Presence-based attribute |
+| `{ type: Object }`, `{ type: Array }` | Not reflected outbound. An author-set attribute is still parsed inbound with `JSON.parse` |
+| `{ noAttribute: true }` | No attribute in either direction |
+| `{ converter: { fromAttribute, toAttribute } }` | Custom serialisation. `converters/DOMReference.js` already exists for `opener`-style properties that accept an element or an id string |
+
+Reflection notes that cause bug reports: `undefined` and `null` remove the attribute, while `""`
+leaves a present, empty one. Nothing is reflected before the first render, so reading `getAttribute`
+in a constructor or early in a test sees nothing. In dev mode a type mismatch logs a `[UI5-FWK]`
+console error and stops converting that attribute — that message is the fastest way to spot a
+missing `type`.
+
+### `@default`
+
+Required on every public property. A literal initializer satisfies it on its own, so most properties
+need no tag. A property with **no** initializer needs the tag written explicitly:
+
+```ts
+/**
+ * @default undefined
+ * @public
+ */
+@property()
+icon?: string;
+```
+
+Public getters need it too. This is the most common CEM failure on a new API.
+
+### Boolean polarity
+
+No public boolean property in this library defaults to `true` — CEM rejects it. When the behaviour
+you want is on by default, invert the name so `false` is the default, using the prefix that matches
+what is being turned off:
+
+| Prefix | For | Examples |
+|--------|-----|----------|
+| `hide*` | a rendered sub-element that is shown by default | `hideArrow`, `hideCloseButton`, `hideWeekNumbers` |
+| `no*` | an automatic behaviour | `noTypeahead`, `noAnimation`, `noAutoSelection` |
+| `prevent*` | a focus or closing side effect | `preventFocusRestore`, `preventInitialFocus` |
+| `disable*` | a whole capability, distinct from `disabled` | `disableResizing`, `disableSearchCollapse` |
+
+The mirror case is `show*` with a `false` default (`showSuggestions`, `showClearIcon`). Pick the
+polarity that makes `false` correct, then name accordingly. `suppress*`, `without*`, and `omit*` are
+not used here.
+
+### `@property` on a setter
+
+The decorator works on an accessor pair, and this is how every state property with a side effect is
+written — `Popup.open` calls the open and close routines from its setter, `Popover.opener` re-opens
+when it changes, `Select.value` stores into a backing field and reconciles against the slotted
+options during `onBeforeRendering`. Put the JSDoc above the setter.
+
+### Naming
+
+| Name | Use for |
+|------|---------|
+| `design` | visual style |
+| `type` | behavioural or semantic kind — `Button.type` drives form submit and reset |
+| `mode` | how the component operates — Image/Text, Button/Scroll |
+| `value` | the machine or form payload; `text` is the human-visible label |
+| `selected` | on item components only. Containers get `selectionMode` |
+| `collapsed` / `expanded` | pick the one whose `false` default is right — panels are expanded by default, tree nodes are collapsed |
+
+`variant` is never used. `readonly` is spelled all-lowercase. Whether `text` is a property or a
+default slot varies by component (`Button.text` is a slot; `MenuItem.text`, `Tab.text`, and
+`ToolbarButton.text` are properties) — check the neighbour rather than assuming.
+
+### Enums
+
+Import the enum type-only, type the property as `` `${Enum}` ``, default it to a string literal, and
+compare against string literals. The attribute path assigns a raw string, so a property typed as the
+enum itself is a type lie. One enum per file in `src/types/`.
+
+Much of the existing code violates this — importing enums as runtime values and comparing against
+members like `ButtonDesign.Default`. Write the correct form; do not migrate neighbours as a drive-by.
+
+### Accessibility properties
+
+An interactive component carries `accessibleName` and `accessibleNameRef` as optional strings with no
+default, `accessibleRole` typed to a component-specific enum rather than a raw ARIA role, and
+`accessibilityAttributes` as `{ type: Object }` defaulting to `{}` and narrowed with
+`Pick<AccessibilityAttributes, …>` to the fields it actually applies. `accessibleNameRef` needs a
+registration in `onEnterDOM` to resolve — see `accessibility.md`.
+
+### Form-associated components
+
+`formAssociated: true` in `@customElement`, plus `formValidityMessage`, `formValidity`,
+`formElementAnchor()`, and `formFormattedValue`. Mark the value member `@formProperty`, and
+`@formEvents` with the space-separated names of the events that signal a change.
+
+### Re-typing an inherited property
+
+Narrowing a property from a base class needs `declare`, which emits no field and leaves the
+framework's accessor intact:
+
+```ts
+declare selected: boolean;
+```
+
+Without it the class field shadows the prototype accessor, the component silently stops
+invalidating, and the console warns that the property is "shadowed by the instance".
+
+## Slots
+
+Import the default export of `decorators/slot-strict.js`. From the `decorators.js` barrel the plain
+`slot` export is the deprecated decorator, so alias: `slotStrict as slot`.
+
+Two member types, both exported from `UI5Element.js`. Getting this wrong is the most common slot
+mistake:
+
+- `DefaultSlot<T>` — only for the slot declared `"default": true`
+- `Slot<T>` — every named slot
+
+```ts
+@slot({ type: Node, "default": true })
+text!: DefaultSlot<Node>;
+
+@slot({ type: HTMLElement, invalidateOnChildChange: true })
+badge!: Slot<ButtonBadge>;
+```
+
+| Option | Effect |
+|--------|--------|
+| `"default": true` | The unnamed slot. One per component; a second one throws |
+| `type` | `typeof Node` or `typeof HTMLElement`. Validated at runtime per child with `instanceof`, and a mismatch **throws** — text-content slots need `Node` or a bare text node fails. Defaults to `HTMLElement` |
+| `individualSlots: true` | Each child gets a generated slot name in `_individualSlot`, for templates that place children at unrelated positions |
+| `invalidateOnChildChange` | `true`, or `{ properties, slots }` where each is a boolean or an array of names. An absent key means `false`. Omitting the option entirely means child changes never invalidate |
+
+Blanket `true` on a slot holding hundreds of children is a performance bug — scope it to the
+properties you read, as `Table` does for its rows. See `performance.md`.
+
+Applications address a named slot by the **camelCase member name** — `slot="endContent"`, not
+kebab-case. The default slot is a bare `<slot></slot>` in the template. With `individualSlots`, the
+template reads the generated name off each child: `<slot name={step._individualSlot}></slot>`.
+
+Read through a re-projected slot with `this.getSlottedNodes<T>(slotName)` — a method inherited from
+`UI5Element` (the helper lives in `util/SlotsHelper.js`, but components call the method, they don't
+import it). There is no `getSlottedElements`.
+
+### Typing slot children
+
+Constrain children with an interface, declared in the file of the component that *consumes* the slot
+and exported as a type from it (e.g. `IMenuItem` in `Menu.ts`, `ITab` in `TabContainer.ts`). Extend
+`HTMLElement` when any element qualifies, `UI5Element` when framework services are needed. The one
+common exception is `IButton` below: it lives in `Button.ts` because `Button` is the shared building
+block many containers slot, so the interface travels with the implementer rather than each consumer.
+
+```ts
+/**
+ * Interface for components that may be used as a button inside numerous higher-order components
+ * @public
+ */
+interface IButton extends HTMLElement, ITabbable {
+	nonInteractive: boolean;
+}
+```
+
+The slot references the interface while `type` stays `HTMLElement` — the interface is a compile-time
+contract only: `startButton!: Slot<IButton>`. The implementing class adds `implements IButton`, an
+`@implements {IButton}` JSDoc tag, and a duck-typing marker getter (`get isMenuItem() { return
+true; }`) paired with `createInstanceChecker` exported from the bottom of its file. Never pass a
+component class as a slot `type` — it reintroduces `instanceof` and breaks under scoping.
+
+A slot with no accessor is documented with a class-level tag instead:
+`@slot {Array<Node>} default - Defines the content…`
+
+## Events
+
+Import the default export of `decorators/event-strict.js`; from the barrel, `eventStrict as event`.
+Omitted options default to `bubbles: false` and `cancelable: false`. Write the booleans as literals —
+CEM reads them literally and records anything that is not a literal `false` as `true`.
+
+`@customElement` must be present or CEM rejects the class, but the decorator order does not matter.
+What does matter is that each JSDoc block sits immediately **above the decorator it documents**. An
+`@event` with no JSDoc block is silently private: no error, and the event never reaches the docs or
+the framework wrappers.
+
+```ts
+@customElement({ tag: "ui5-button", renderer: jsxRenderer, template: ButtonTemplate })
+/**
+ * Fired when the component is activated either with a mouse/tap or by using the Enter or Space key.
+ * @public
+ */
+@event("click", {
+	bubbles: true,
+	cancelable: true,
+})
+class Button extends UI5Element implements IButton {
+	eventDetails!: {
+		"click": ButtonClickEventDetail,
+		"active-state-change": void,
+	};
+}
+```
+
+Every event needs an `eventDetails` entry — `void` when there is no payload, otherwise a named
+exported type. `@event("open")` with no options object is the right form for a plain, non-bubbling
+event.
+
+### Subclasses must re-declare `eventDetails`
+
+The strict decorator resolves event names from `keyof this["eventDetails"]`, so a subclass that does
+not re-declare it cannot fire its parent's events and cannot compile a new `@event`. Re-declare even
+when adding nothing (`eventDetails!: Popup["eventDetails"];`), and put your own events **last** in
+the intersection — CEM reads only the final member, so the reversed order compiles and then fails
+validation:
+
+```ts
+eventDetails!: ListItem["eventDetails"] & {
+	"before-open": MenuBeforeOpenEventDetail,
+	"open": void,
+}
+```
+
+Export every detail type from the module, or CEM rejects it as an undocumented public type.
+
+### What one `fireDecoratorEvent` dispatches
+
+Up to four events, all with `composed: false`. For a multi-word name like `selection-change` it fires
+`ui5-selection-change` and `selection-change`, then repeats the pair PascalCased
+(`ui5-SelectionChange`, `SelectionChange`). A single-word name like `open` fires four too —
+`ui5-open`, `open`, `ui5-Open`, `Open` — because `kebabToPascalCase("open")` is `"Open"`, which
+differs from the original and so is not skipped. The `ui5-` prefixed events always fire; the
+un-prefixed ones are what no-conflict configuration suppresses, so listen to the prefixed name inside
+the library. The PascalCase alias exists so React's `onSelectionChange` binds to a real dispatched
+event.
+
+Two consequences: a bubbling event stops at the first shadow boundary, so a host listening to its own
+slotted children attaches listeners directly; and preventing the kebab-named event suppresses the
+PascalCase form too, so a React consumer's handler silently does not run.
+
+`fireDecoratorEvent` returns `false` when prevented:
+
+```ts
+const prevented = !this.fireDecoratorEvent("item-click", { item, text: item.text || "" });
+```
+
+| Aspect | Convention |
+|--------|-----------|
+| Name | kebab-case, and it must survive a round trip through `pascalToKebabCase` or `onX` binding breaks in templates |
+| Privacy | Internal events carry no public JSDoc; the `_` prefix is a weak, inconsistently applied hint |
+| `bubbles` | `false` for popup lifecycle events — `open`, `close`, `before-open`, `before-close` — because host components embed popovers and a bubbling `open` surfaces as the host's own. Also `false` across the Table family |
+
+### Cancelable events
+
+Two idioms coexist. Lifecycle events fire first and act only if not prevented (`Popup.openPopup`,
+`TabContainer.selectTab`). Value and selection changes apply the change, fire, and revert if prevented
+(`CheckBox.toggle`, `List` selection) — so a `change` listener sees the new value while a `before-open`
+listener sees the old state. Use fire-then-act for new lifecycle events.
+
+Setting `open` on a popup from application code runs the full event sequence, since the setter drives
+it. Events here are not user-interaction-only.
+
+## Public methods
+
+Justified in the three cases listed under Choosing the mechanism. An explicit return type is
+required; CEM fails without it. Add `@param` for each parameter and `@returns` for the result.
+
+```ts
+getSelectedRows(): TableRow[] {
+	return this._table ? this._table.rows.filter(row => this.isSelected(row)) : [];
+}
+```
+
+Expose focus by overriding `getFocusDomRef()`, not `focus()`. A named public focus entry point
+(`Popup.applyFocus`) is rare and needs a reason.
+
+## JSDoc that passes CEM
+
+Every tag is checked twice: it must be allowed for that kind of member, and it must have the right
+shape. A tag in the wrong shape fails with the same "Incorrect use of @tag" error as a disallowed
+one, so the shape rules matter more than the error list.
+
+| Tag | Shape |
+|-----|-------|
+| `@param` on a **method** | no braces — `@param selectedSet A set of row keys` |
+| `@param` on an **event** | braces required — `@param {HTMLElement} item The previewed item` |
+| `@returns` | text, no braces |
+| `@implements` | braces — `@implements {IButton}` |
+| `@extends` | no braces — `@extends UI5Element` |
+| `@default` | a value only, no braces and no trailing description |
+| `@since` | a version |
+| `@csspart`, `@cssState` | `name - description`, no braces |
+| `@deprecated`, `@experimental` | free text, no braces |
+| Bare, no text at all | `@public`, `@private`, `@protected`, `@abstract`, `@constructor`, `@override`, `@formProperty` |
+
+### Allowed tags per member
+
+Anything outside these is rejected.
+
+| Entity | Allowed |
+|--------|---------|
+| all | `@public`, `@protected`, `@private`, `@since`, `@deprecated` |
+| property, getter | plus `@default`, `@formProperty`, `@formEvents`, and `@override` on getters |
+| slot | plus `@default` |
+| event | plus `@param` |
+| method | plus `@param`, `@returns`, `@override` |
+| class | plus `@constructor`, `@class`, `@abstract`, `@experimental`, `@implements`, `@extends`, `@slot`, `@csspart`, `@cssState` |
+| enum, enum member, interface | plus `@experimental` |
+
+`@native` and `@allowPreventDefault` are accepted but should not be written — cancelability is
+derived from the decorator and documented in prose.
+
+### Class-level JSDoc
+
+The block needs `@class`, `@constructor`, or `@abstract` to be recognised at all. Without one of
+them the entire class JSDoc is skipped — silently, with no error and no manifest entry. Beyond that:
+`@extends`, `@public`, and `@implements` when there is an `implements` clause. The `### Overview`,
+`### Usage`, and `### ES6 Module Import` prose sections are conventional. Full boilerplate in
+`new-component.md`.
+
+A `part` in the template also needs a class-level `@csspart name - description`, or the part ships
+undocumented with no error.
+
+### Three errors whose message misleads
+
+- `@interface {X} tag is used, but the class doesn't implement…` — the tag you write is
+  `@implements`, not `@interface`. Add the `implements` clause or drop the tag.
+- `Type 'X' is used to describe a public API but is not exported.` — add it to the module's
+  `export type { … }`. Hits event detail types most often.
+- `Event details for event 'x' must be described.` — the event has `@param` tags but no matching
+  `eventDetails` entry, or the intersection puts the parent's types last.
+
+Everything else CEM reports names the missing tag directly.
+
+## Versioning
+
+- New public property, slot, event, or method gets `@since <next minor>` — read the current version
+  from `lerna.json` and bump the minor. Nothing enforces this; a reviewer will.
+- Removing or renaming anything public is breaking. Mark the old name `@deprecated` pointing at the
+  replacement, keep it working, and note it in the commit body under `BREAKING CHANGE:`.
+- `@experimental` marks API that may still change, with optional explanatory text.
diff --git a/ai-knowledge-base/references/component-anatomy.md b/ai-knowledge-base/references/component-anatomy.md
new file mode 100644
index 0000000000000..cb7fdc0b57d00
--- /dev/null
+++ b/ai-knowledge-base/references/component-anatomy.md
@@ -0,0 +1,232 @@
+# Component Anatomy
+
+## The file set
+
+A component named `Foo` in package `main`. Fiori is identical under `packages/fiori/src` — swap the
+package prefix (`ShellBar.ts`, `ShellBarTemplate.tsx`, `themes/ShellBar.css`). `ai` and `compat` share
+the same file set and build pipeline; see "packages/ai and packages/compat" below for where `ai`
+diverges.
+
+| File | Required | Purpose |
+|------|----------|---------|
+| `packages/main/src/Foo.ts` | yes | Class, decorators, logic, public API |
+| `packages/main/src/FooTemplate.tsx` | yes, unless the component is headless (no visible markup) | Preact JSX template |
+| `packages/main/src/themes/Foo.css` | yes, unless headless | Component styles |
+| `packages/main/src/themes/base/Foo-parameters.css` | if themed | Default values for `--_ui5_foo_*` variables |
+| `packages/main/src/themes/<theme>/Foo-parameters.css` | if themed | Per-theme overrides |
+| `packages/main/src/themes/<theme>/parameters-bundle.css` | if themed | Per-theme aggregator, and the registration unit. Add an `@import` for your file to the theme families the component should be styled in, or the variables never load there. The `*_auto` folders (e.g. `sap_horizon_auto`) are generated composites of their light/dark siblings — never add a direct import there, only to the themes they draw from. Not every component needs every theme family; some are intentionally scoped to fewer |
+| `packages/main/src/types/FooSomething.ts` | if it has a public enum | One enum per file. A private, unexported enum can live inline in `Foo.ts` instead |
+| `packages/main/src/i18n/messagebundle.properties` | if it has text | One bundle per package, mixing component-specific (`BUTTON_*`) and shared (`ACC_STATE_*`, `DELETE`) keys. Prefix new keys with the component name |
+| `packages/main/src/i18n/messagebundle_en.properties` | if the English text changes | The defaults generator merges this with `messagebundle.properties` and the translated file wins, so an English copy fix that only touches `messagebundle.properties` has no visible effect until this file is updated too. Edit it by hand alongside `messagebundle.properties`. Other locale files (`messagebundle_de.properties`, etc.) are pipeline-owned — never hand-edit those |
+| `packages/main/cypress/specs/Foo.cy.tsx` | conventional | Behaviour tests. A subcomponent's tests usually live in its parent's spec — `AvatarBadge` is covered by `Avatar.cy.tsx`, `MenuItem` by `Menu.cy.tsx` |
+| `packages/main/cypress/specs/visuals/Foo.cy.tsx` | if visual | Screenshot tests |
+| `packages/main/test/pages/Foo.html` | recommended | Manual test page for the dev server |
+| `packages/website/docs/_samples/main/Foo/...` | if public | Documentation samples |
+
+### Beyond the standard set
+
+- Extra templates for popovers and detached subtrees: `InputPopoverTemplate.tsx`,
+  `SelectPopoverTemplate.tsx`, `features/InputSuggestionsTemplate.tsx`
+- Several entries in `styles: [...]` when composing shared CSS: `Select.ts`, `ShellBar.ts`
+- `features/` modules, lazily imported at runtime: `features/InputSuggestions.ts` from `Input.ts`
+- Registration entries in `src/bundle.esm.ts`, `src/bundle.scoped.esm.ts` (paired with
+  `bundle.scoped.config.ts`), and `src/Assets.ts` — plus `src/Assets-fetch.ts` and
+  `src/Assets-node.ts` for the fetch- and Node-targeted asset variants. Keep all of them in sync
+  when adding a component
+
+### Generated output
+
+Produced by `yarn generate`, which the dev server runs in watch mode. Never committed —
+`**/src/generated` is in `.gitignore` with no exceptions.
+
+| Script | Output |
+|--------|--------|
+| `build.styles.components` | `src/generated/themes/Foo.css.ts` |
+| `build.styles.themes` | `src/generated/themes/<theme>/parameters-bundle.css.ts` |
+| `build.i18n.defaultsjs` | `src/generated/i18n/i18n-defaults.ts` |
+| `build.i18n.json` | `dist/generated/assets/i18n` |
+| `build.jsonImports.*` | `src/generated/json-imports/` — each of `Themes` and `i18n` emits three variants (default, `-node`, `-fetch`); `Assets.ts` wires up the default pair, `Assets-fetch.ts`/`Assets-node.ts` wire up the other two |
+
+Under `UI5_TS` the compiled CSS on disk is `Foo.css.ts`, while imports keep the `.css.js` suffix.
+
+JSX templates are compiled by tsc and Vite, not by `yarn generate`: `build.templates` runs only when
+`options.legacy` is set, for the retired Handlebars pipeline.
+
+`src/generated/i18n/i18n-defaults.ts` is the exception: gitignored, absent on a clean checkout, so
+with the dev server stopped you add your key to it by hand. Procedure in `i18n.md`.
+
+### packages/ai and packages/compat
+
+Both use the identical file set and `wc-dev`-based build pipeline described above — same
+`Assets.ts`/`Assets-fetch.ts`/`Assets-node.ts` triad, same `bundle.esm.ts`/`bundle.scoped.esm.ts`
+pair, same generated-output tree. `compat` hasn't been seen to diverge structurally.
+`ai` differs in four ways:
+
+- No `src/types/` directory. Its components reuse `main`'s enums directly (e.g. `ButtonDesign`
+  imported from `@ui5/webcomponents/dist/types/ButtonDesign.js`) rather than declaring their own.
+- Theming is Horizon-only: `src/themes/` contains only `sap_horizon*` folders, no `sap_fiori_3*`.
+  The folders that exist enforce this, not just the prose.
+- Some components subclass a concrete `main` component directly instead of composing it — e.g. an
+  `ai` input extends the `main` input (from `@ui5/webcomponents/dist/Input.js`) and reuses the
+  parent's generated CSS file directly. This is tighter coupling than main-to-fiori composition: a
+  change to the base class in `main` can break `ai` without touching any `ai` file.
+- i18n bundle acquisition is inconsistent: most components use `@i18n(bundleName) static
+  i18nBundle`, but a few still use the deprecated `static async onDefine()` + `getI18nBundle()`
+  pattern. Write new `ai` components against the `@i18n` decorator; do not copy the `onDefine`
+  pattern.
+
+## Order inside the `.ts` file
+
+Framework, then base utilities and types, then local modules, then the template, then generated
+last — a common tendency, not a rule. Plenty of existing components import out of this order
+somewhere. Match the imports around where you're adding one rather than deriving a position from
+this list.
+
+```ts
+// A component's imports, condensed — a real file has more framework/base imports than shown
+import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
+import type { Slot, DefaultSlot } from "@ui5/webcomponents-base/dist/UI5Element.js";
+import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
+import property from "@ui5/webcomponents-base/dist/decorators/property.js";
+import event from "@ui5/webcomponents-base/dist/decorators/event-strict.js";
+import slot from "@ui5/webcomponents-base/dist/decorators/slot-strict.js";
+import i18n from "@ui5/webcomponents-base/dist/decorators/i18n.js";
+import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
+import {
+	isSpace,
+	isEnter,
+} from "@ui5/webcomponents-base/dist/Keys.js";
+import type { ITabbable } from "@ui5/webcomponents-base/dist/delegate/ItemNavigation.js";
+import type I18nBundle from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import ButtonDesign from "./types/ButtonDesign.js";
+import type ButtonBadge from "./ButtonBadge.js";
+import ButtonTemplate from "./ButtonTemplate.js";
+import {
+	BUTTON_ARIA_TYPE_ACCEPT,
+} from "./generated/i18n/i18n-defaults.js";
+
+// Styles
+import buttonCss from "./generated/themes/Button.css.js";
+```
+
+`Button.ts` imports `ButtonDesign` as a value because it compares against enum members.
+New code follows `core-rules.md`: `import type` plus string literals.
+
+Decorator imports come from individual files here; the Table family instead imports from the barrel.
+Both compile identically, but the barrel is essentially a Table-only convention — write new
+components with individual-file imports unless you're extending the Table family.
+
+### Order inside the class
+
+A common tendency, not a rule: `eventDetails` first, then public `@property` fields, then `@slot`
+fields, then plain private fields and `@query` fields, then the static `@i18n` bundle, then the
+constructor, lifecycle hooks, event handlers, the getters the template calls, and static helpers
+last. A simple component follows this closely end-to-end.
+
+This pattern breaks down in larger components and subclasses, so don't enforce it across existing
+code. Larger components interleave `@property` and `@slot` fields around the `static i18nBundle`,
+put form-validity getters (`formValidityMessage`, `formValidity`, `formFormattedValue`) before the
+constructor, drop the constructor entirely, or declare a getter/setter property (like `opener`)
+after the constructor instead of with the other properties. A subclass may have no `eventDetails`,
+no i18n bundle, and no constructor of its own — those can live in the base class instead. Match the
+surrounding code in the file you're editing.
+
+`Foo.define()` runs at module scope after the class body, followed by `export default Foo`. A
+component with exported enums or constants often has a plain `export { ... }` here too, and
+`export type { ... }` only appears when there's a public API type left to export; not every component
+needs one. Every type used in a public API signature must be exported this way — see `api-design.md`
+for the CEM validation this satisfies.
+
+## Decorators
+
+The barrel `@ui5/webcomponents-base/dist/decorators.js` exports every decorator except `query` and
+`queryAll`, which come from their own files.
+
+| Decorator | Applies to | Notes |
+|-----------|-----------|-------|
+| `@customElement(config)` | class | See config keys below |
+| `@property(options)` | field | `type`, `noAttribute`, `converter`. Default type is String |
+| `@slot(options)` | field | Use `decorators/slot-strict.js`, or `slotStrict` from the barrel. `type`, `default`, `invalidateOnChildChange`, `individualSlots`, `propertyName` (rarely passed explicitly — `slot-strict` sets it for the default slot) |
+| `@event(name, options)` | class | Use `decorators/event-strict.js`, or `eventStrict` from the barrel. `bubbles`, `cancelable` |
+| `@i18n(bundleName)` | static field | e.g. `@i18n("@ui5/webcomponents")` |
+| `@query(selector)` | field | Shadow DOM `querySelector`, evaluated on access |
+| `@queryAll(selector)` | field | Shadow DOM `querySelectorAll` |
+| `@bound` | method | Auto-binds `this`. Real, but not currently used by any shipped component — no example to copy if you reach for it |
+
+The strict decorators take their types from the class's `eventDetails` map and from `Slot<T>` /
+`DefaultSlot<T>`. Use `slot-strict.js` and `event-strict.js` (or `slotStrict`/`eventStrict` from the
+barrel) for `@slot` and `@event`. The `wc-create-ui5-element` scaffolder emits the wrong `slot.js`
+import — fix it to `slot-strict.js` after scaffolding (its `event-strict.js` import is already
+correct).
+
+### `@customElement` config keys
+
+| Key | Type | When to set it |
+|-----|------|----------------|
+| `tag` | string | Always. Kebab-case, `ui5-` prefix in this repo. Pass it alone as `@customElement("ui5-foo")` when no other key is needed — common for components that inherit everything else from a base class |
+| `renderer` | `jsxRenderer` | Set on whichever class in the chain owns the template. Inherited by subclasses through the static prototype chain, so a subclass whose base already sets it doesn't repeat it |
+| `template` | imported template | Any component that renders its own visible markup. Omitted entirely by headless components that render nothing (Table "feature" plugins with no shadow DOM of their own) and by subclasses that inherit a base's template unchanged |
+| `styles` | one or an array | Set together with `template`, or omitted together with it. Array when composing shared CSS |
+| `languageAware` | boolean | The component renders translated text |
+| `themeAware` | boolean | The component needs to re-render on theme change |
+| `cldr` | boolean | The component formats dates or numbers |
+| `formAssociated` | boolean | The component participates in form submission — pairs with `formAssociatedCallback()`, see Lifecycle |
+| `fastNavigation` | boolean | The component is an F6 navigation group |
+| `shadowRootOptions` | object | `{ delegatesFocus: true }` for anything focusable |
+| `dependencies` | array | Still consumed at runtime for micro-frontend tag scoping (`getUniqueDependencies`/`tagsToScope`), despite an `@deprecated` JSDoc on the field — that tag means only "unnecessary for the old Handlebars renderer," not "remove this." Some components still set it deliberately. Set it when your component slots in other custom elements and needs correct scoping |
+| `features` | array | A different, disused mechanism from the Table `features` *slot* pattern in `api-design.md` — don't confuse the two. Deprecated. Do not add |
+
+## Lifecycle
+
+| Hook | Fires | Use it for |
+|------|-------|-----------|
+| `constructor` | once, on creation | Field initialisation only. No DOM |
+| `static async onDefine()` | once, inside `define()` | Deprecated for new code — use `@i18n` and the `cldr` option instead. Still relied on by a few `ai` components; don't copy that pattern into a new component |
+| `onInvalidation(changeInfo)` | at invalidation time, before the deferred render | React to a specific property or slot change. Does not fire for language, theme, or RTL-direction changes — those bypass invalidation and re-render directly; see `performance.md` |
+| `onBeforeRendering` | before each render | Derive state the template needs. No DOM reads. May be declared `async` — several components do (`Button`, `Icon`, `AvatarBadge`) even though the base signature is `void` |
+| `onAfterRendering` | after each render | DOM measurement, positioning. Guard any `@property` write — an unconditional write re-invalidates and loops |
+| `onEnterDOM` | late in `connectedCallback`, after the first render, only if still connected | Listeners on `this`, `ResizeObserver`, delegate setup |
+| `onExitDOM` | `disconnectedCallback`, skipped if the element was never fully connected | Tear down everything `onEnterDOM` created |
+| `formAssociatedCallback()` | when the browser associates or disassociates the form, for `formAssociated: true` components | Calls `updateFormValue()`; override to react to the association changing |
+| `attributeChangedCallback` | on every attribute write | Framework-owned: converts the attribute and assigns the property. Never override |
+
+`onEnterDOM` and `onExitDOM` must be symmetric: whatever you register in one, tear down in the
+other. For example, pair `registerUI5Element` in `onEnterDOM` with `deregisterUI5Element` in
+`onExitDOM`.
+
+Do not read layout in `onBeforeRendering`; the DOM still reflects the previous render.
+
+## Templates
+
+Templates are Preact JSX in `.tsx` files. Each is a default-exported function that types `this` as
+the component, so `this.foo` in the JSX reads the instance.
+
+```tsx
+		<button
+			type="button"
+			class={{
+				"ui5-button-root": true,
+				"ui5-button-badge-placement-end": this.badge[0]?.design === "InlineText",
+				"ui5-button-badge-placement-end-top": this.badge[0]?.design === "OverlayText",
+				"ui5-button-badge-dot": this.badge[0]?.design === "AttentionDot"
+			}}
+			disabled={this.disabled}
+			data-sap-focus-ref
+```
+
+- `part="..."` on anything an application may need to style, documented with a class-level
+  `@csspart` tag — see `api-design.md` for the JSDoc shape this requires.
+- `data-sap-focus-ref` marks the element that receives focus; `UI5Element`'s default
+  `getFocusDomRef()` queries for it inside the shadow root.
+- Computed values come from getters on the class, not from expressions in the template. Inline
+  `class={{ ... }}` objects are the accepted exception, and much of the codebase uses them.
+- A template can take an `injectedProps` parameter and be reused by another component's template
+  via `templateFn.call(this, { ... })` — `ButtonTemplate.tsx` accepts one so
+  `ToggleButtonTemplate.tsx` can call `buttonTemplate.call(this, { ariaPressed: this.pressed })`.
+  Large templates are commonly split into local helper functions that take the instance
+  (`RangeSliderTemplate.tsx`'s `startTooltip`/`endTooltip`) rather than inlined as one long tree.
+- Putting `onKeyDown` directly on a child UI5 custom element in a template is fine and common
+  (`MultiComboBoxPopoverTemplate.tsx`, `RangeSliderTemplate.tsx`, `SearchPopoverTemplate.tsx`) — it
+  is not a pattern to avoid. If a container-level keydown or click handler misbehaves, check
+  whether it reads `event.target` instead of `event.composedPath()` first; see the Debugging
+  section of `INDEX.md`.
diff --git a/ai-knowledge-base/references/core-rules.md b/ai-knowledge-base/references/core-rules.md
new file mode 100644
index 0000000000000..6e2f7194befd8
--- /dev/null
+++ b/ai-knowledge-base/references/core-rules.md
@@ -0,0 +1,241 @@
+# Core Rules
+
+Every rule here is what you follow in code you write. Legacy code violates many of them, sometimes at
+scale — do not copy those patterns, and do not migrate them as a drive-by. A rule being listed here
+does not mean the codebase is already clean; it means new code must not add to the debt.
+
+## Blocking
+
+| # | Rule | Wrong | Right |
+|---|------|-------|-------|
+| 1 | Enum imports: type-only when the enum is only used as a type; runtime when members are compared at runtime | `import type ButtonDesign from "./types/ButtonDesign.js"` when you write `ButtonDesign.Default` in code | `import type` for property declarations only; `import` (runtime) when comparing `=== ButtonDesign.Default` |
+| 2 | Enum properties use template literal types | `design: ButtonDesign = ButtonDesign.Default` | ``design: `${ButtonDesign}` = "Default"`` |
+| 3 | Enum comparisons use dot notation *when the enum is runtime-imported*; a string-literal compare is correct when the enum is type-only imported | `if (this.design === "Transparent")` while `ButtonDesign` is runtime-imported | `if (this.design === ButtonDesign.Transparent)` — or the literal when no runtime import exists |
+| 4 | Query and test by attribute | `querySelector("ui5-popover")`, `cy.get("ui5-button")` | `querySelector("[ui5-popover]")`, `cy.get("[ui5-button]")` |
+| 5 | Style by attribute | `ui5-button { }` | `[ui5-button] { }` |
+| 6 | Identify UI5 components with an instance checker | `el instanceof Button` | `isInstanceOfButton(el)` |
+| 7 | Never compare `tagName` against a UI5 tag | `el.tagName === "UI5-BUTTON"` | `isInstanceOfButton(el)` |
+| 8 | Set child state through the template | `this._input.value = x` | `<Input value={x} />` |
+| 9 | No imperative attribute mutation on child UI5 elements | `childUi5El.setAttribute("disabled", "")` | `<El disabled={this.isDisabled} />` |
+| 10 | No class toggling for persistent state | `el.classList.add("active")` to track open/selected state | `:host([active]) { }` driven by a `@property` |
+| 11 | No `any` — strongly discouraged; acceptable only as a documented workaround for an external/untyped API | `const d: any = f()` | `const d: MyType = f()`, or `unknown` plus narrowing |
+| 12 | Boolean properties default to `false` | `@property({ type: Boolean }) open = true` | `@property({ type: Boolean }) open = false` |
+
+## Structural
+
+| # | Rule | Wrong | Right |
+|---|------|-------|-------|
+| 13 | Private `@property` fields get `noAttribute: true`, unless a CSS selector reads the attribute | `@property({ type: Boolean }) _open = false` | `@property({ type: Boolean, noAttribute: true }) _open = false` |
+| 14 | Non-rendered state is a plain field | `@property() _lastKey = ""` | `_lastKey = ""` |
+| 15 | Fire the event after the state update | fire, then mutate | mutate, then fire |
+| 16 | Revert state when a cancelable event is prevented | fire and ignore the return value | revert if `fireDecoratorEvent` returns `false` |
+| 17 | Focusable components are reachable via `focus()` — either `delegatesFocus: true`, or an inner focusable element found through `getFocusDomRef()` | neither `delegatesFocus` nor an inner focus target | `shadowRootOptions: { delegatesFocus: true }`, **or** `tabindex` on the inner element (the majority pattern) |
+| 18 | Children never reach for their parent | `this.parentElement as Table` | the child fires, the parent listens |
+| 19 | Public properties change only in response to user interaction | reassigns `this.value` from a timer or observer | update on user action, then fire the event |
+| 20 | State is declared, not commanded | `show(): void` | `@property({ type: Boolean }) open = false` |
+| 21 | `fireDecoratorEvent`, never `fireEvent` | `this.fireEvent("change", d, true, true)` | `this.fireDecoratorEvent("change", d)` |
+| 22 | Strict decorators only | `decorators/slot.js`, `decorators/event.js` | `decorators/slot-strict.js`, `decorators/event-strict.js` |
+| 23 | Relative imports end in `.js` | `from "./Button"` | `from "./Button.js"` |
+| 24 | Keyboard checks use the `Keys.js` predicates where one exists | `e.key === "Enter"` | `isEnter(e)` |
+
+## Quality
+
+| # | Rule | Wrong | Right |
+|---|------|-------|-------|
+| 25 | Import every icon explicitly | rely on the test bundle | `import download from "@ui5/webcomponents-icons/dist/download.js"` |
+| 26 | Assert against the i18n bundle, not English | `should("have.text", "Cancel")` | `Button.i18nBundle.getText(KEY)` |
+| 27 | Logical CSS direction properties | `margin-left`, `text-align: left` | `margin-inline-start`, `text-align: start` |
+| 28 | Real events in specs | `.click()`, `.type()` | `.realClick()`, `.realType()` |
+| 29 | Never wait a fixed number of milliseconds | `cy.wait(300)` | assert the condition and let Cypress retry |
+| 30 | Descriptive names in samples and test pages | `mgr`, `da`, `q`, `asc` | `itemManager`, `dateA`, `searchQuery`, `isAscending` |
+| 31 | No issue or PR numbers in comments | `// fixes #1234` | state the constraint, or nothing |
+| 32 | Comments state constraints, not what the code does | `// increment the counter` | `// Popover measures its opener, so this must run after layout` |
+
+## Reviewing a diff
+
+`yarn lint:scope` catches tag-name selector violations mechanically. The rest require eyes.
+
+| # | Spot it | Checked by |
+|---|---------|------------|
+| 1 | `^import [A-Z]\w* from "\./types/` without `type` keyword — only a problem if the enum members are never used at runtime | review only |
+| 2, 3 | A string literal like `=== "Default"` in a comparison where an enum member (`ButtonDesign.Default`) should be used | review only |
+| 4 | `querySelector("ui5-`, `cy.get("ui5-` | `yarn lint:scope` for `.ts`; review for `.tsx` and specs |
+| 5 | a bare `ui5-*` selector in `.css` | `yarn lint:scope` |
+| 6 | `instanceof` followed by a UI5 class name | review only |
+| 7 | `.tagName ===` against `"UI5-*"` (native tags like `INPUT`, `IMG`, `SLOT`, `IFRAME` are fine) | review only |
+| 8 | an assignment to a property of a `@query` ref | review only |
+| 9 | `setAttribute`/`removeAttribute` on a child UI5 element (calling it on `this` in a lifecycle hook, on native HTML elements, or for browser-API-required attributes like `popover="manual"` is legitimate) | review only |
+| 10 | `.classList.add/remove/toggle(` for persistent state (animation-trigger classes, read-only `.classList.contains`, and marking state on elements outside your shadow tree are legitimate) | review only |
+| 11 | `: any`, `as any` | review only |
+| 12 | `@property({ type: Boolean })` with `= true` | review only |
+| 13 | a `@property` named `_*` with no `noAttribute` and no matching `:host([_*])` selector | review only |
+| 14 | a `@property` whose name never appears in the `.tsx` or `.css` | review only |
+| 15 | `fireDecoratorEvent` above the assignments it describes | review only |
+| 16 | `fireDecoratorEvent` for a `cancelable` event with the result discarded | review only |
+| 17 | a template `tabindex`/`focus()` override **and** no `delegatesFocus` — only a problem if there is also no inner focus target; the inner-element pattern is valid and common | review only |
+| 18 | `this.parentElement`, `this.closest(`, `this.getRootNode().host` | review only |
+| 19 | a `@public` property assigned from a timer, observer, or fetch callback | review only |
+| 20 | a new `@public` method named `open`, `show`, `close`, `toggle`, `refresh`, `expand`, `reset` | review only |
+| 21 | `.fireEvent(` on anything (`this` or a child element) | review only |
+| 22 | `decorators/slot.js`, `decorators/event.js` | review only |
+| 23 | a relative import with no extension | `yarn lint` — `import/extensions` |
+| 24 | `e.key ===`, `e.keyCode` when a `Keys.js` predicate covers that key | review only |
+| 25 | an icon name in a template with no matching import | review only |
+| 26 | a quoted English string in a `should(` | review only |
+| 27 | `margin-left`, `padding-right`, `border-left`, bare `left:`/`right:`, `text-align: left` | review only |
+| 28 | `.click()`, `.type(` in a `.cy.tsx` | review only |
+| 29 | `cy.wait(<digit>` | review only |
+| 30 | short identifiers in `test/pages/` or `_samples/` | review only |
+| 31 | `#` followed by digits in a comment | review only |
+| 32 | a comment that restates the line under it | review only |
+
+## Why enums need both import styles
+
+A runtime import is required whenever you compare against an enum member by name (`=== ButtonDesign.Default`).
+A type-only import is correct when the enum is only used in a property declaration as a template literal type.
+
+```ts
+// type-only: WrappingType is only used in the property type annotation
+import type WrappingType from "./types/WrappingType.js";
+
+@property()
+wrappingType: `${WrappingType}` = "Normal";
+
+// runtime: TagDesign is compared by member in a switch
+import TagDesign from "./types/TagDesign.js";
+
+if (this.design === TagDesign.Positive) { /* ... */ }
+```
+
+The same component can have both. The enum file stays a real TypeScript enum and stays exported for consumers. The distinction is purely about whether members are accessed at runtime inside component code.
+
+Legacy: runtime imports still outnumber type-only ones across the codebase. Both forms appear in current code — the key is matching the import style to the usage.
+
+## Why attribute selectors
+
+Applications can register these components under scoped tag names so two versions of the library can
+coexist on one page. `ui5-button` becomes `ui5-button-f5331039`, and every tag-name selector silently
+stops matching. The `ui5-button` attribute is present either way.
+
+`yarn lint:scope` fails on bare `ui5-*` selectors in `src/**/*.css` and on `querySelector("ui5-...")` in
+`src/**/*.ts`. It does not read `.tsx` and it does not read specs, where a residue of `cy.get("ui5-...")`
+calls survives among the attribute selectors.
+
+## Why not `instanceof`
+
+Same scoping problem, plus module duplication: with two copies of the library loaded, `Button` from
+copy A is not the same class object as `Button` from copy B.
+
+```ts
+import createInstanceChecker from "@ui5/webcomponents-base/dist/util/createInstanceChecker.js";
+
+class MenuItem extends UI5Element {
+  get isMenuItem(): boolean { return true; }   // the duck-typing marker
+}
+
+export const isInstanceOfMenuItem = createInstanceChecker<MenuItem>("isMenuItem");
+```
+
+This applies to UI5 component classes only. `instanceof HTMLElement`, `instanceof Node`,
+`instanceof Date` and the like are fine. `tagName ===` against native tags (`INPUT`, `IMG`, `SLOT`,
+`IFRAME`, `TEXTAREA`) is also fine. Some current code still uses `instanceof` against UI5 classes
+(Toolbar, NotificationList, ShellBar, UserMenuItem, Popover) — treat these as legacy, not precedent.
+
+## Why `@query` is read-only
+
+`@query` is a live reference into your own shadow DOM. Call methods on it; do not assign, because the
+next render overwrites the assignment from the template and the value flickers or reverts.
+
+```ts
+import query from "@ui5/webcomponents-base/dist/decorators/query.js";
+
+@query("[ui5-input]")
+_input!: Input;
+
+this._input?.focus();        // fine
+this._input.value = "x";     // wrong — the next render undoes this
+```
+
+Put the value in the template: `<Input value={this.inputValue} />`.
+
+## Why `@property` is not free
+
+Every assignment to a `@property` schedules a re-render. If nothing in the template or the CSS reads
+the field, that render is waste, and a render mid-interaction runs `onBeforeRendering`, which can
+overwrite state the user is editing.
+
+```ts
+@property({ type: Boolean, noAttribute: true })
+_isOpen = false;             // the template reads it — property is correct
+
+_lastPressedKey = "";        // only JS reads it — plain field is correct
+```
+
+`noAttribute: true` is the convention for internal state (not the framework default — the framework
+reflects by default), but drop it when a CSS selector reads the attribute — `:host([_open])` needs the
+attribute to exist.
+
+## Why event ordering matters
+
+Listeners read component state when the event fires, so firing first shows them the old value. For a
+cancelable event, `fireDecoratorEvent` returns `false` when a listener called `preventDefault()`, and
+you must undo the change.
+
+```ts
+this.checked = !this.checked;
+if (!this.fireDecoratorEvent("change")) {
+  this.checked = !this.checked;   // a listener prevented it
+}
+```
+
+## Why children must not know their parent
+
+`this.parentElement as Table` breaks the moment the child is wrapped in a `div`, slotted somewhere
+unexpected, or rendered standalone in a test, and it creates a module cycle.
+
+```ts
+// wrong — a child reaching for its parent
+const row = this.parentElement as TableRow | null;
+
+// right — the child announces, the parent decides
+this.fireDecoratorEvent("selection-change", { selected: this.selected });
+```
+
+A few such casts remain in Table and Tree internals, where the parent contract is fixed. New components do not get that exemption.
+
+## Why the API is declarative
+
+Applications describe the state they want and the component gets itself there. A method forces every
+React, Vue, and Angular consumer out of its own rendering model to hold a ref; a property is one
+attribute binding.
+
+```html
+<ui5-date-picker open></ui5-date-picker>
+```
+
+A verb in a public API name is the signal: `open` the adjective is a property, `open()` the verb is
+not. When the user does something that changes that state — pressing Escape, for instance — the
+component updates its own property and fires the matching event.
+
+## When imperative DOM calls are legitimate
+
+These are the known production exceptions to rules 9 and 10. They are narrow — do not expand them.
+
+**`this.setAttribute` on the component's own host in a lifecycle hook** — for browser-API-required
+attributes (`popover="manual"` must be a real DOM attribute for the native Popover API to activate)
+and for platform-detection markers (`desktop`). Template binding cannot set attributes on `this`.
+
+**Setting attributes on native HTML elements inside shadow DOM** — `<input>` elements accept
+attributes like `autocomplete`, `pattern`, and `inputmode` that have no UI5 property-binding path.
+Use `setAttribute` on them directly.
+
+**Animation-trigger class toggling** — when a CSS animation must start imperatively (e.g., adding
+`ui5-popup-opening` for 50 ms to trigger a CSS transition), the template re-renders synchronously and
+would remove the class before the animation fires. `classList.add/remove` is the only viable path.
+
+**Marking state on elements outside your shadow tree** — `classList.add` on an opener element owned
+by another component (e.g., `SideNavigation` marking an external button active while a popover is
+open) cannot use template binding because the element is not in your template.
+
+**Read-only `classList.contains`** — checking a class for event routing (`target.classList.contains("ui5-mp-item")`)
+is not DOM mutation and is not covered by rule 10.
diff --git a/ai-knowledge-base/references/i18n.md b/ai-knowledge-base/references/i18n.md
new file mode 100644
index 0000000000000..6df8434059aaf
--- /dev/null
+++ b/ai-knowledge-base/references/i18n.md
@@ -0,0 +1,136 @@
+# Internationalisation
+
+Every user-visible or screen-reader-audible string comes from the message bundle — ARIA labels,
+announcements, and tooltips included. Nothing in the build, lint, or CI catches a hardcoded English
+string; review is the only guard.
+
+`packages/localization` is CLDR, calendars, and date formatting — not UI strings.
+
+## The pipeline
+
+Two independent halves; adding a key covers only the first. Root `yarn generate` runs the package's
+`wc-dev generate`, which runs both branches.
+
+```
+src/i18n/messagebundle.properties  <- you edit this
+  |- build.i18n.defaultsjs -> src/generated/i18n/i18n-defaults.ts   English fallback, typed constants
+  |- build.i18n.json       -> dist/generated/assets/i18n/messagebundle_<locale>.json
+                              registered by src/generated/json-imports/i18n.ts, via src/Assets.js only
+```
+
+The build targets that drive this are `build.i18n.defaultsjs` (writes `i18n-defaults.ts`) and
+`build.i18n.json` (writes the locale JSON assets).
+
+`src/generated` is gitignored. When the default language is `en` the defaults
+generator merges `messagebundle.properties` with `messagebundle_en.properties`, the translated file
+winning.
+
+The dev-server watch rebuilds defaults only, and only on `messagebundle.properties` — never locale
+files, never the JSON assets. That is why "I added a key
+and nothing happened".
+Locale files come from the SAP translation pipeline; add your key to the default bundle only.
+
+## 1. Add the key
+
+```properties
+# messagebundle.properties
+#XACT: ARIA announcement for the Button Badge with value 1 - "{0} item"
+BUTTON_BADGE_ONE_ITEM={0} item
+
+#XACT: ARIA announcement for the Button Badge with value more than 1 - "{0} items"
+BUTTON_BADGE_MANY_ITEMS={0} items
+```
+
+Every new key carries an annotation comment; it is the only context translators get. Nothing
+enforces it, and a few legacy outliers have none or use a non-standard prefix (two keys use `#ACC:`,
+one uses `#FLD:`). Do not copy those.
+
+The codes, most common first: `#XACT` ARIA text and announcements, `#XFLD` field label, `#XTOL`
+tooltip, `#XBUT` button text, `#XTXT` general text, `#XTIT` title or heading, `#XMSG` message,
+`#XLNK` link text, `#XCKL` checkbox.
+
+Placeholders are `{0}`, `{1}`, positional, passed to `getText` in order. No ICU plural syntax —
+plurals are separate keys, as above.
+
+```properties
+# messagebundle.properties
+#XACT: ARIA announcement for the position of the list items in an entire list
+LIST_ITEM_POSITION=List item {0} of {1}
+```
+
+## 2. Name it
+
+`SCREAMING_SNAKE_CASE`, prefixed with the component name — one namespace per package:
+`BUTTON_ARIA_TYPE_ACCEPT`, `COLORPALETTE_CONTAINER_LABEL`, `DATEPICKER_OPEN_ICON_TITLE`.
+
+Never duplicate a generic key under a new prefix; reuse the unprefixed shared ones:
+`ACC_STATE_REQUIRED`, `DELETE`, `SELECT_OPTIONS`, `VALUE_STATE_*`.
+Never reuse another component's key even if the English matches — translations diverge by context.
+
+## 3. Add the generated constant
+
+If the dev server is not watching, prefer running `yarn generate` — the real `i18n-defaults.ts` is
+minified onto two lines, so a hand-edit is fragile. If you must edit by hand, add the entry to
+`src/generated/i18n/i18n-defaults.ts` and append the name to the `export {...}` list at the bottom,
+so type-checking and tests pass. Keep `defaultText` byte-identical to the properties value.
+
+```ts
+// i18n-defaults.ts
+const BUTTON_BADGE_ONE_ITEM: I18nText = {key: "BUTTON_BADGE_ONE_ITEM", defaultText: "{0} item"};
+```
+
+## 4. Use it in the component
+
+`i18nBundle` is a **static** class member: `Button.i18nBundle`, never `this.i18nBundle`.
+
+```ts
+import {
+	BUTTON_BADGE_ONE_ITEM,
+} from "./generated/i18n/i18n-defaults.js";
+
+@customElement({
+	tag: "ui5-button",
+	formAssociated: true,
+	languageAware: true,
+
+@i18n("@ui5/webcomponents")
+static i18nBundle: I18nBundle;
+
+return Button.i18nBundle.getText(BUTTON_BADGE_ONE_ITEM, badgeEffectiveText);
+```
+
+`languageAware: true` is required — without it the text resolves once and goes stale on language
+switch. The bundle name is the package: `@ui5/webcomponents` for `main`,
+`@ui5/webcomponents-fiori` for `fiori`.
+
+For a component class, always use the `@i18n` decorator. The `getI18nBundle` function form is for
+cases where the class isn't the natural owner: dynamic icon bundles resolved at runtime (`Icon`,
+`AvatarBadge` in `main`), or a fixed bundle fetched in `onDefine()` (the `ai` package's `TextArea`,
+`WritingAssistant`, `Versioning`). A plain utility with no class can construct `new I18nBundle(pkg)`
+directly (`CustomAnnouncement`). `getText` also accepts a raw string key, but always pass the
+generated constant.
+
+## Testing
+
+Assert against the bundle, never an English literal — `getText` when the string has placeholders,
+`defaultText` when it is static:
+
+```tsx
+import { FORM_GROUP_ACCESSIBLE_NAME } from "../../src/generated/i18n/i18n-defaults.js";
+
+	.should("have.attr", "aria-label", Form.i18nBundle.getText(FORM_GROUP_ACCESSIBLE_NAME, "1"));
+```
+
+```tsx
+btnText: MESSAGE_STRIP_CLOSE_BUTTON_INFORMATION.defaultText,
+```
+
+To test a non-default locale, import the asset bundle in the spec:
+
+```tsx
+import "../../src/Assets.js";
+```
+
+Without that import only the default language is loaded, and the locale switch silently does
+nothing — `Assets.ts` is what pulls in the generated `registerI18nLoader` calls that fetch the
+locale JSON.
diff --git a/ai-knowledge-base/references/new-component.md b/ai-knowledge-base/references/new-component.md
new file mode 100644
index 0000000000000..8707764524d42
--- /dev/null
+++ b/ai-knowledge-base/references/new-component.md
@@ -0,0 +1,179 @@
+# Creating a New Component
+
+The scaffolder writes three files; the rest is manual. Theme bundles and website wiring get skipped.
+
+## 1. Scaffold
+
+```bash
+cd packages/main
+UI5_TAG_NAME_PREFIX=ui5 yarn create-ui5-element Foo
+```
+
+Without `UI5_TAG_NAME_PREFIX=ui5` the tag becomes `my-foo`. PascalCase name; exactly three files:
+
+- `src/Foo.ts` — `@customElement`, one `@property`, `@slot`, `@event`, `eventDetails`, `.define()`
+- `src/FooTemplate.tsx` — Hello World template
+- `src/themes/Foo.css` — empty
+
+One mandatory fix in `Foo.ts`: it imports the legacy `decorators/slot.js` — switch to
+`decorators/slot-strict.js`. The event import is already `event-strict.js`.
+
+A Fiori component is scaffolded the same way from `packages/fiori`, which has its own
+`src/bundle.esm.ts` and `src/themes/` folders.
+
+## 2. Write the component
+
+Follow `component-anatomy.md` for file layout and member order, `api-design.md` for the public
+surface and its JSDoc. The smallest complete component in the repo:
+
+```ts
+// The smallest complete component (class JSDoc and IMenuItem specifics omitted)
+import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
+import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
+import menuSeparatorTemplate from "./MenuSeparatorTemplate.js";
+import menuSeparatorCss from "./generated/themes/MenuSeparator.css.js";
+import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
+
+@customElement({
+	tag: "ui5-menu-separator",
+	renderer: jsxRenderer,
+	styles: [menuSeparatorCss],
+	template: menuSeparatorTemplate,
+})
+class MenuSeparator extends UI5Element {
+	// ... properties, slots, eventDetails ...
+}
+
+MenuSeparator.define();
+
+export default MenuSeparator;
+```
+
+Set these in `@customElement` up front:
+
+| Question | If yes |
+|----------|--------|
+| Can it receive focus? | `shadowRootOptions: { delegatesFocus: true }` |
+| Does it show translated text? | `languageAware: true`, plus an `@i18n` bundle |
+| Does it format dates or numbers? | `cldr: true` |
+| Does it take part in form submission? | `formAssociated: true` |
+| Is it an F6 navigation group? | `fastNavigation: true` |
+
+A component slotted inside an existing one also changes that parent: the parent's slot JSDoc must
+name the new tag and its CSS must style the new child. `AvatarBadge` changed `Avatar.ts` and
+`themes/Avatar.css`.
+
+## 3. Types
+
+One enum per file in `src/types/`, with `export default` there and `@public` on the enum and every
+member. Import it type-only and type the property as `` `${FooDesign}` ``. Do not re-export the enum
+from the component file — `ButtonBadge.ts` imports `ButtonBadgeDesign` and exports only itself. CEM
+requires the export only for a type declared in the component file itself; that case fails the build
+with `Type 'X' is used to describe a public API but is not exported.`
+
+## 4. Register in the bundle
+
+`src/bundle.esm.ts` — default import, alphabetical:
+
+```ts
+// src/bundle.esm.ts
+import Avatar from "./Avatar.js";
+import AvatarBadge from "./AvatarBadge.js";
+```
+
+Use this form, not the side-effect `import "./Foo.js";` the scaffolder prints. Either form registers the component (`.define()` runs on import either way), but every other entry in `bundle.esm.ts` uses the default-import form — match it for consistency.
+
+## 5. Styles and theme parameters
+
+`src/themes/Foo.css` holds structure. Any value that differs per theme belongs in
+`src/themes/base/Foo-parameters.css`, plus a per-theme file wherever the base default is wrong.
+Then `@import` those files into the `parameters-bundle.css` of every theme folder in the package
+(excluding `*_auto`, which are generated composites). In `packages/fiori` the `*_exp` folders
+(`sap_horizon_exp`, `sap_horizon_dark_exp`, `sap_horizon_hcb_exp`, `sap_horizon_hcw_exp`) are **not**
+generated — they need the manual `@import` too. A theme whose bundle is missing
+the import renders the component with unresolved custom properties. See `theming-and-css.md`.
+
+```css
+/* sap_horizon/parameters-bundle.css */
+@import "../base/HeroBanner-parameters.css";
+@import "./HeroBanner-parameters.css";
+```
+
+## 6. Text
+
+Every user-visible or announced string goes in `src/i18n/messagebundle.properties` with a text-type
+comment. `yarn generate` from the repo root writes `src/generated/i18n/i18n-defaults.ts`; edit that
+file by hand only as a fallback when you cannot run generate. See `i18n.md`.
+
+## 7. Accessibility
+
+Work through the checklist at the end of `accessibility.md` before you consider the component done.
+
+## 8. Tests
+
+`cypress/specs/Foo.cy.tsx` covers rendering, every property, every event and payload, the keyboard
+path, and ARIA. A new visual component also gets `cypress/specs/visuals/Foo.cy.tsx` (`testing.md`).
+
+## 9. Manual test page
+
+`packages/main/test/pages/Foo.html`, to exercise the component across themes and text directions.
+
+## 10. Website
+
+**API page.** One `.mdx` under `packages/website/docs/_components_pages/<package>/` — top-level
+(`main/ExpandableText.mdx`) or nested under the parent for a subcomponent
+(`main/Avatar/AvatarBadge.mdx`). It must import and render each sample, not just the placeholders:
+
+```mdx
+// _components_pages/main/ExpandableText.mdx
+---
+slug: ../ExpandableText
+---
+
+import Basic from "../../_samples/main/ExpandableText/Basic/Basic.md";
+
+<%COMPONENT_OVERVIEW%>
+
+## Basic Sample
+<Basic />
+
+<%COMPONENT_METADATA%>
+```
+
+**Samples.** `packages/website/docs/_samples/<package>/Foo/<SampleName>/` with `sample.html`,
+`main.js`, `sample.tsx`, and `<SampleName>.md`:
+
+```md
+// _samples/main/AvatarBadge/Basic/Basic.md
+import html from '!!raw-loader!./sample.html';
+import js from '!!raw-loader!./main.js';
+import react from '!!raw-loader!./sample.tsx';
+
+<Editor html={html} js={js} react={react} />
+```
+
+**React playground.** Add `import FooClass from "@ui5/webcomponents/dist/Foo.js";` and `FooClass` to
+the `ComponentClasses` map in `packages/website/src/components/Editor/ReactPlayground.tsx`,
+or the sample fails at runtime.
+
+**Monaco types.** Add an entry to the `COMPONENTS` array in
+`packages/website/scripts/generate-monaco-types.mjs`, next to
+`{ name: "ButtonBadge", package: "main", tag: "ui5-button-badge" }`.
+
+**Generate.** `docs/components/<package>/` is generated from `_components_pages` and the sidebar
+reads the generated folder, so a new page stays invisible until
+`cd packages/website && yarn generate-api-reference` runs. It needs the CEM manifest from
+`yarn generateAPI`.
+
+## 11. Verify
+
+Run `yarn generate` first. The component imports `./generated/themes/Foo.css.js`, which does not
+exist until then, so `yarn ts` and the tests both fail without it.
+
+```bash
+yarn generate                                        # repo root — or yarn start, which watches
+yarn ts                                              # repo root
+yarn generateAPI                                     # repo root — validates JSDoc and CEM
+cd packages/main && yarn lint && yarn lint:scope
+yarn test:cypress:single cypress/specs/Foo.cy.tsx
+```
diff --git a/ai-knowledge-base/references/performance.md b/ai-knowledge-base/references/performance.md
new file mode 100644
index 0000000000000..60acad65055ea
--- /dev/null
+++ b/ai-knowledge-base/references/performance.md
@@ -0,0 +1,176 @@
+# Performance and Rendering
+
+## The invalidation model
+
+```
+assign to an @property
+        |
+   _invalidate()
+        |
+  onInvalidation(changeInfo)     you can observe this; suppression is OFF here
+        |
+  render queued (async, batched)
+        |
+  onBeforeRendering()            derive state here; suppression is ON
+        |
+  template runs, DOM patched
+        |
+  onAfterRendering()             measure DOM here; suppression is OFF
+```
+
+Renders are batched and deduped, so you cannot read the DOM right after setting a property.
+`RenderQueue.add()` ignores a component already queued, and `scheduleRenderTask()` drains the whole
+queue inside a single `requestAnimationFrame`: N assignments in one synchronous turn cost
+one render per component. A component re-queued during the drain is processed again; the queue throws
+after a component is processed eleven times in one task (the `MAX_PROCESS_COUNT` guard) — the
+only guard against a render loop.
+
+## What schedules a render
+
+| Trigger | Effect |
+|---------|--------|
+| A **different** value assigned to an `@property` field | schedules a render |
+| An object or array property reassigned with identical contents | schedules a render — the guard is `!==` |
+| An attribute write, via `attributeChangedCallback` assigning the property | schedules a render if the value differs |
+| A slotted child added or removed | schedules a render, `reason: "children"` |
+| Default-slot text content changed | schedules a render, `reason: "textcontent"` |
+| `slotchange` from a slot element in the light DOM | schedules a render, `reason: "slotchange"` |
+| `slotchange` from a slot the component itself rendered | reprocesses children |
+| A child change matching `invalidateOnChildChange` | schedules a render, `reason: "childchange"` |
+| `setLanguage()`, with `languageAware: true` | re-renders every language-aware instance |
+| Theme change, with `themeAware: true` | re-renders every theme-aware instance |
+| `applyDirection()`, for `rtlAware` components | re-renders every RTL-aware instance |
+
+The last three go through `reRenderAllUI5Elements`, which queues instances directly with
+`renderDeferred`, never reaching `_invalidate`: `onInvalidation` does not fire and the flag below does
+not apply.
+
+The setter guard is reference equality: `const isDifferent = oldState !== value;`. A
+new array with identical contents invalidates. `push` into the existing array does not, and does not
+update the UI either. Writing the same primitive back does not. A plain class field never does.
+
+`languageAware` and `themeAware` are class-level flags that trigger a **global** re-render of every
+matching instance on the page. Declaring one on a component that has no i18n text or no themed style is
+a global regression, not a local convenience.
+
+## One suppression flag, two phases
+
+`_suppressInvalidation` makes `_invalidate` return early. It is set in the
+constructor, so nothing invalidates before the first render, then set again around
+`onBeforeRendering` and cleared in the `finally`. Deriving state in `onBeforeRendering` therefore
+cannot loop — those assignments update `_state` silently.
+
+The flag is `false` again for the entire rest of `_render()`: through `updateShadowRoot`, past
+`_rendered = true`, and through `onAfterRendering`. Any `@property` assignment in that whole span
+queues a second render. This is why rule 3 exists.
+
+Invalidation is also skipped for a `languageAware` component while language bundles load; the language
+change re-renders it when the data arrives.
+
+`onInvalidation(changeInfo)` fires with suppression **off**, before the render is queued. It is the
+cheap place to inspect `changeInfo.reason` (e.g. `"childchange"`) and cache a derived value.
+Assigning an `@property` there queues a second render, so cache into a plain field.
+
+## The four rules
+
+### 1. State only JavaScript reads is not a property
+
+The rule is `core-rules.md` rule 13. The invalidation consequence: the wasted render runs
+`onBeforeRendering`, which can overwrite input the user is still editing. A re-render on the first
+keystroke reset the value and moved the caret to the start of the field.
+
+`@property({ type: Object })` and `type: Array` never reflect to an attribute — the setter returns
+early ("Don't reflect arrays and objects to the DOM"). Reassigning still invalidates,
+but a CSS attribute selector will never see the value. `noAttribute: true` on any other property skips
+the per-render `setAttribute`/`removeAttribute`; use it for private state not read by CSS.
+
+### 2. Scope `invalidateOnChildChange` to the properties you depend on
+
+Unscoped, every property change on every child re-renders the parent. The option takes an object form
+`{ properties, slots }` where each is a boolean or a list of names:
+
+```ts
+// Follow two named properties, ignore slot changes
+@slot({ type: HTMLElement, "default": true, invalidateOnChildChange: { properties: ["navigated", "position"], slots: false } })
+rows!: DefaultSlot<TableRow>;
+
+// The inverse: any slot change, no property change
+@slot({ type: HTMLElement, invalidateOnChildChange: { properties: false, slots: true } })
+headerRow!: Slot<TableHeaderRow>;
+```
+
+Many component files still use the unscoped `invalidateOnChildChange: true`. Do not copy them. To
+follow one child instead of every child in a slot, attach to that instance:
+
+```ts
+// Attaching to a single child; detaches on the first "position" change
+lastRow.attachInvalidate(this._onRowInvalidateBound);
+```
+
+### 3. Guard any property you set in `onAfterRendering`
+
+Hook semantics are in `component-anatomy.md`. `onAfterRendering` runs with suppression off, so an
+`@property` written there reaches `_invalidate` and queues another render; compare
+before assigning, and keep measurements in plain fields. `getDomRef()` is not cached — it reads
+`shadowRoot.children[0]` on every call, so never call it in a loop.
+
+### 4. Clean up in `onExitDOM`
+
+The symmetry list is in `component-anatomy.md`. Nothing is torn down automatically: an unmatched
+`ResizeHandler`, `IntersectionObserver`, scroll listener, or `setTimeout`/`setInterval` keeps firing
+on a detached component and blocks GC. Deregister with the **same bound reference** you registered — a
+fresh arrow each time never matches and leaks. Gate registration on `open` inside
+`onAfterRendering` and keep a safety deregister in `onExitDOM`.
+
+## Repo patterns to reuse
+
+- Size changes: `ResizeHandler`, one shared `ResizeObserver` whose callbacks are coalesced into a rAF. It resolves `getDomRef()` at registration, so register in `onEnterDOM`, not earlier.
+- Scroll handlers: the base `throttle()` (`base/util/throttle.js`) is a `setTimeout`-based trailing call — used e.g. by `ShellBar` for resize. `TableUtils.ts` has a separate rAF-based throttle used only by `TableVirtualizer`; don't confuse the two.
+- Infinite scroll: `debounce()`, a `setTimeout`-based call. Caveat: it uses a single module-level timer shared by every caller on the page, so a second `debounce()` cancels the first pending one. Safe only when one component at a time calls it (as List's infinite-scroll trigger does).
+- End-of-list detection: `IntersectionObserver`.
+- Scroll and touch listeners: `{ passive: true }`.
+- State for many children: one pass in the parent's `onBeforeRendering` writing plain child fields, not a `@property` per child.
+- Derived objects: a key-guarded field on the instance.
+
+`individualSlots: true` runs a `setAttribute("slot", …)` pass over every child on every render.
+Combined with an unscoped `invalidateOnChildChange` on a high-cardinality slot it
+compounds; use it only where per-child `::slotted()` targeting is required.
+
+`DateFormat.getDateInstance()` is cached repo-wide by options and locale; a runtime locale or
+pattern change produces a new key and a new instance, and a caller holding the old instance keeps
+the old formatter.
+
+## Animations
+
+Animation state is global configuration, not a per-component decision.
+
+```ts
+return this.noAnimation || getAnimationMode() === AnimationMode.None;
+```
+
+`getAnimationMode` comes from `@ui5/webcomponents-base/dist/config/AnimationMode.js`. Compare against
+the `AnimationMode` enum member — `getAnimationMode() === AnimationMode.None` — as every component does.
+The enum values are the lowercase strings `"full"`, `"basic"`, `"minimal"`, `"none"`, so a raw
+`=== "none"` is equivalent, but the enum member is the established pattern; import the enum object.
+
+A component that animates unconditionally produces timing-dependent tests, because the test
+environment may have animations disabled while the component waits for a transition that never fires.
+
+## Awaiting a render
+
+`renderFinished()`, from `@ui5/webcomponents-base/dist/Render.js`, is not "after paint": it awaits
+`whenAllCustomElementsAreDefined()` and then `whenDOMUpdated()`. `whenDOMUpdated` is one
+`requestAnimationFrame` that resolves once the queue is empty; the render task itself adds a 200 ms
+`setTimeout` settle after draining the queue (named `mutationObserverTimer`, but it is a plain
+timeout, not a `MutationObserver`). Do not call `renderFinished()` in a hot path.
+
+`onAfterRendering` runs synchronously at the end of `_render()`: after the DOM
+patch, still before the next paint. Measure your own DOM there, not through `renderFinished()`.
+
+In tests use `cy.waitRenderFinished()`. `cy.mount` and
+the wrapped real-event commands already wait — see `testing.md`.
+
+## Large lists
+
+`Table` is the reference implementation for anything list-shaped at scale — virtualisation, keyboard
+navigation over a virtualised range, and growing are all solved there.
diff --git a/ai-knowledge-base/references/testing.md b/ai-knowledge-base/references/testing.md
new file mode 100644
index 0000000000000..b6e9189ae27b2
--- /dev/null
+++ b/ai-knowledge-base/references/testing.md
@@ -0,0 +1,205 @@
+# Testing
+
+Cypress component tests in TSX, mounting real components. Under `packages/<pkg>/cypress/specs/`:
+`<Component>.cy.tsx`, `<Component>.mobile.cy.tsx` (phone, via `cy.ui5SimulateDevice("phone")`), `base/`
+(framework-level), `visuals/` (screenshots, only with `CYPRESS_VISUAL=true`). Commands: `INDEX.md`. Add
+`.only` to one case while iterating; remove it and run the full spec file before you finish.
+
+## Mounting
+
+```tsx
+cy.mount(<Button icon={download} design="Negative">Action Bar Button</Button>);
+
+cy.get<Button>("[ui5-button]")
+	.shadow()
+	.find(".ui5-button-text>bdi>slot")
+	.should("have.length", 1, "Button text is not rendered");
+```
+
+`cy.mount` waits for rendering and for `document.fonts.ready`; never follow it with a wait. Import
+every icon you use — the test bundle contains all of them, so a missing import passes here and breaks
+in a real application.
+
+## Selecting
+
+Use `[ui5-*]` everywhere — tag selectors break under scoping, and `/test-lint` flags them. A residue
+of tag-name `cy.get("ui5-…")` calls survives in the specs; do not add to it.
+The rule holds inside `.shadow().find(...)` as well:
+
+```tsx
+cy.get("[ui5-button]")            // attribute selector, never the tag name
+	.shadow()                     // cross into the shadow root
+	.find(".ui5-button-text");    // internal element
+
+// wrong, should be "[ui5-tag]"
+cy.get("@badge").shadow().find("ui5-tag").as("tag");
+```
+
+## Interacting
+
+| Use | Not |
+|-----|-----|
+| `.realClick()` | `.click()` |
+| `.realPress("Enter")` | `.type("{enter}")` |
+| `.realType("hello")` | `.type("hello")` |
+| `.realHover()` | `.trigger("mouseover")` |
+
+**`realPress` and `realType` take no subject.** They dispatch CDP key events to whatever currently has
+focus, so a piped subject is ignored. In practice specs focus the target first, then type — most often
+against the native input inside the shadow root: `cy.get("@input").shadow().find("input").realType("abc")`.
+Never chain them after a *focus-changing* command in the same chain: the preceding command's focus
+change has not settled.
+
+```tsx
+// wrong — realType chained after another command
+cy.get("@startTooltipInput").realClick().realType("23");
+
+// right — two statements
+cy.get("@startTooltipInput").realClick();
+cy.realType("23");
+```
+
+A few such chains survive in the specs. Do not add more.
+
+**There is no `realClear()`.** For a native input inside the shadow root, Cypress's built-in
+`.clear()` works. Otherwise clear by selecting all and typing over it, by pressing Escape, or by
+clicking the component's own clear icon.
+
+**Never use `cy.wait(<number>)`.** Assert the condition instead; `should` retries. Numeric waits
+remain throughout the existing specs — do not add more.
+
+```tsx
+// wrong — the assertion already retries
+cy.wait(3000);
+cy.get("#field").shadow().find<ResponsivePopover>("[ui5-responsive-popover]").ui5ResponsivePopoverClosed();
+```
+
+To wait for a render, use `cy.waitRenderFinished()`. It is new, so there is no precedent in the
+existing specs to copy — use it anyway rather than a numeric wait.
+
+## Asserting
+
+`have.attr` for reflected properties and ARIA; `have.prop` for state that is not reflected to an
+attribute.
+
+```tsx
+.should("have.attr", "title", "my tooltip");
+cy.get("#myInput2").should("have.prop", "focused", true);
+```
+
+## Asserting on events
+
+No global event helper — attach a stub:
+
+```tsx
+cy.get("@tag").then(tag => {
+	tag.get(0).addEventListener("click", cy.stub().as("clicked"));
+});
+
+cy.get("@tag").realClick();
+
+cy.get("@clicked").should("have.been.calledOnce");
+
+// payload
+cy.get("@clickHandler").should("be.calledWithMatch", { detail: { ctrlKey: true } });
+```
+
+StepInput has a dedicated helper — `ui5StepInputAttachHandler(eventName, stubName)`. No other
+component has one.
+
+## Asserting on focus
+
+`UI5Element.focus()` is asynchronous, so an alias captured before the interaction can be stale.
+
+```tsx
+// wrong, races in CI
+cy.get("@defaultColorButton").should("have.focus");
+
+// right
+cy.focused().should("have.attr", "aria-label").and("include", "cyan");
+```
+
+`cy.focused()` returns the inner shadow focus ref, not the host, so host-level `value` or
+`[ui5-color-palette-item]` are not on it — assert `aria-label`.
+
+## Text and i18n
+
+Compare against the bundle, never an English literal:
+
+```tsx
+.should("have.attr", "aria-label", Form.i18nBundle.getText(FORM_GROUP_ACCESSIBLE_NAME, "1"));
+```
+
+Non-default locales and `Assets.js`: `i18n.md`.
+
+## Custom commands
+
+Framework-level commands live in the shared cypress-internal package; package-level ones in each
+package's `support/commands.ts`:
+
+| Command | Behaviour |
+|---------|-----------|
+| `cy.mount(jsx)` | Mount, wait for render, wait for `document.fonts.ready` |
+| `cy.waitRenderFinished()` | Drain the render queue |
+| `cy.focus` | Overwritten — waits for render, then routes through the UI5 element's own `focus()` |
+| `realClick`, `realHover`, `realTouch`, `realSwipe`, `realMouseDown`, `realMouseUp`, `realMouseMove` | Overwritten — wait for render, then assert the element is visible and has a DOM ref |
+| `realPress`, `realType` | Overwritten — wait for render only |
+| `cy.screenshot` | Overwritten — honours the `SCREENSHOT_DELAY` env var |
+| `cy.ui5SimulateDevice("phone")` | Force phone behaviour; `"phone"` is the only device |
+| `cy.ui5AssertValidityState(partial)` | Assert any subset of form validity state |
+| `cy.ui5UserMenuOpen(options?)`, `cy.ui5UserMenuOpened()` | fiori UserMenu helpers |
+
+`cy.ui5DOMRef()` is declared in `support/commands.ts` but never implemented —
+it type-checks and fails at runtime. Do not call it.
+
+Many `ui5*` commands exist, named `ui5<Component><Action>`. Read the existing
+`support/commands/` files before writing a helper; these families already have one:
+Calendar, ColorPalette, ColorPalettePopover, ColorPicker, DatePicker, DateRangePicker, DateTimePicker,
+TimePicker, TimeSelectionClocks, DynamicDateRange, Dialog, Popover, ResponsivePopover, Menu, MenuItem,
+SegmentedButton, StepInput, Switch, TabContainer, ToggleButton, plus AI Button and UserMenu (fiori).
+Most popup families have `Open`/`Opened` state helpers; the `Closed` variant is not universal —
+`Menu` and `ResponsivePopover` have it, but `Dialog` and `Popover` expose only `Opened`. Read the
+`support/commands/` file for the family before assuming a `Closed` helper exists. Use these instead
+of asserting the `open` attribute yourself.
+
+## Visual tests
+
+Import the component; from `specs/visuals/` the source path is one level deeper than a normal spec.
+`/visual-test` skill lists the components that need a specific parent container.
+
+```tsx
+import Avatar from "../../../src/Avatar.js";
+import "@ui5/webcomponents-icons/dist/employee.js";
+
+cy.mount(<Avatar size="XS" initials="XS" />);
+cy.screenshot();
+```
+
+## What to cover
+
+Default rendering; every new property including its default; each event's payload and call count; the
+keyboard path, not just the click path; ARIA attributes; disabled and read-only states not reacting.
+
+## Flaky tests
+
+1. **Async focus.** A stale alias instead of `cy.focused()`.
+2. **Animation.** `setAnimationMode(None)` does not disable CSS `@keyframes`; a component that waits
+   for `animationend` must also branch on `getAnimationMode()`.
+3. **Deferred focus after render.** A handler focusing in `onAfterRendering` can land after your
+   assertion — await `cy.waitRenderFinished()`. In component code prefer `getFocusDomRef().focus()`
+   over the async `UI5Element.focus()`: synchronous, and the caller stays in the stack trace (same
+   memory).
+4. **`forcedTabIndex` re-render.** `ItemNavigation.setCurrentItem()` changes `forcedTabIndex`, which
+   schedules an async re-render that races the synchronous focus call (ColorPalette 2026-04-02 memory).
+5. **Container keydown handler.** A handler on a container receives events from every descendant;
+   resolve the intended item through `event.composedPath()`, never `e.target`.
+6. **Preact event proxy.** Move the handler to a wrapper `div` — `component-anatomy.md`.
+7. **A real race in the component.** Reproduce with CDP CPU throttling. If it reproduces at 5-6x it is
+   a product bug — switch to the bugfix workflow.
+
+```ts
+cy.wrap(null).then(() => Cypress.automation("remote:debugger:protocol", {
+	command: "Emulation.setCPUThrottlingRate",
+	params: { rate: 6 },
+}));
+```
diff --git a/ai-knowledge-base/references/theming-and-css.md b/ai-knowledge-base/references/theming-and-css.md
new file mode 100644
index 0000000000000..250773b9be5ab
--- /dev/null
+++ b/ai-knowledge-base/references/theming-and-css.md
@@ -0,0 +1,157 @@
+# Theming and CSS
+
+## The variable tiers
+
+| Tier | Prefix | Defined in | Use it for |
+|------|--------|------------|-----------|
+| Global design tokens | `--sap*` | Outside this repo | Colours, fonts, shadows, focus |
+| Component parameters | `--_ui5_<component>_*` | The component's `-parameters.css` | Values that differ per theme or density |
+| Cross-boundary values | `--ui5_*` / `--ui5-*`, no leading underscore | Component CSS or a shared partial | Values another component or the build reads |
+
+No `--sap*` token is defined in this monorepo — the theme's `parameters-bundle.css` only `@import`s the `--sap*` variables from `@sap-theming/theming-base-content`.
+
+`--_ui5_*` component parameters are by far the most common variable in the theme CSS. `--ui5_*` / `--ui5-*` cross-boundary variables (no leading underscore) are rare and reserved for a value another component or the build reads across a boundary — for example `--ui5_content_density` (read by the build, below), `--ui5-form-column-span-s`, and `--ui5_value_state-background`.
+
+```css
+:host {
+	height: var(--_ui5_button_base_height);
+	font-family: var(--_ui5_button_fontFamily);
+	font-size: var(--sapFontSize);
+	background-color: var(--sapButton_Background);
+	border: var(--sapButton_BorderWidth) solid var(--sapButton_BorderColor);
+}
+
+/* A token missing from some themes needs a chained fallback. */
+--_ui5_table_row_alternating_background: var(--sapTableRow_AlternatingBackground, var(--sapList_AlternatingBackground));
+margin: var(--_ui5_button_overlay_badge_offset, -0.5rem);
+```
+
+Never hard-code a colour or a font. A handful of legacy files still do — do not copy them.
+
+## How CSS reaches the component
+
+`yarn generate` compiles each `.css` file to a `.css.js` module; the component imports that module and passes it to `styles:`. `themeAware: true` on `@customElement` additionally re-renders on theme change.
+
+```ts
+import buttonCss from "./generated/themes/Button.css.js";
+
+// Several stylesheets compose into one styles array:
+	styles: [inputStyles, ResponsivePopoverCommonCss, ValueStateMessageCss, SuggestionsCss],
+```
+
+Shared partials come in through `@import` at the top of the component CSS instead — a component's `.css` file can pull in `./FormComponents.css`, `./InvisibleTextStyles.css`, and similar partials.
+
+## Where each file goes
+
+```
+src/themes/Foo.css                         structure and layout, theme-independent
+src/themes/base/Foo-parameters.css         default --_ui5_foo_* values
+src/themes/sap_horizon/Foo-parameters.css  overrides
+src/themes/sap_fiori_3/Foo-parameters.css  overrides
+```
+
+A per-theme file usually `@import`s the base one and overrides only what changes, but chains exist: `sap_horizon_hcw/rtl-parameters.css` imports `../sap_horizon/rtl-parameters.css`.
+
+Themes: `sap_horizon` (+ `_dark`, `_hcb`, `_hcw`, `_auto`, `_hc_auto`) and `sap_fiori_3` (+ `_dark`, `_hcb`, `_hcw`). A new `--_ui5_*` parameter needs a value in `base/`; central compact overrides live in `base/sizes-parameters.css` onward.
+
+`parameters-bundle.css` is the registration unit — `sap_horizon/parameters-bundle.css` aggregates every `-parameters.css` plus `sizes-parameters.css` and `rtl-parameters.css`. A parameters file that is not imported there does nothing. Add it in every theme folder.
+
+## Selectors
+
+Never use tag names — write `[ui5-button].accept`, not `ui5-button.accept`, or the selector breaks under tag scoping. `yarn lint:scope` enforces it.
+
+Persistent state comes from reflected attributes, not classes. Transient classes for animation or measurement-driven layout are legitimate (`Popup`'s `ui5-popup-opening`, `Bar`'s `ui5-bar-root-shrinked`) — the rule is that *durable* state must be a reflected attribute, not that `classList` is never touched. An internal property gets `noAttribute: true` only when CSS does *not* read it.
+
+```css
+:host([design="Transparent"]) {
+	background-color: var(--sapButton_Lite_Background);
+	color: var(--sapButton_Lite_TextColor);
+}
+
+/* Reach into a child component's part the way an application would. */
+.ui5-breadcrumbs-link-wrapper [ui5-link]::part(root) {
+	padding-top: 0.25rem;
+}
+```
+
+Anything marked `part="..."` is public API: document it with `@csspart` and treat renaming it as a breaking change.
+
+```ts
+ * @csspart button - Used to style the native button element
+ * @csspart icon - Used to style the icon in the native button element
+ * @csspart endIcon - Used to style the end icon in the native button element
+```
+
+## Right-to-left
+
+| Instead of | Write |
+|------------|-------|
+| `margin-left` / `margin-right` | `margin-inline-start` / `margin-inline-end` |
+| `padding-left` / `padding-right` | `padding-inline-start` / `padding-inline-end` |
+| `left` / `right` | `inset-inline-start` / `inset-inline-end` |
+| `border-left` / `border-right` | `border-inline-start` / `border-inline-end` |
+| `text-align: left` | `text-align: start` |
+| `width` (in a flow context) | `inline-size` |
+
+Physical directional properties and `left:`/`right:` positioning still exist throughout the older theme CSS. Do not migrate old ones opportunistically; do not add new ones.
+
+The `post-edit-lint.sh` hook catches only a subset — `padding-left/right`, `margin-left/right`, `border-left/right`, `float: left|right`, `text-align: left|right`, minus lines containing `[dir=`. It misses `left:` / `right:` positioning and physical corner radii such as `border-top-right-radius`.
+
+Mirrored icons, transforms and gradient directions flip by swapping *parameters*, not by writing `:dir(rtl)` rules per component:
+
+```css
+:dir(rtl) {
+	--_ui5_icon_transform_scale: scale(-1, 1);
+	--_ui5_panel_toggle_btn_rotation: var(--_ui5_rotation_minus_90deg);
+}
+```
+
+CSS alone is not enough — keyboard and positioning logic must read `effectiveDir`:
+
+```ts
+const isForward = this.effectiveDir === "rtl" ? isLeft(e) : isRight(e);
+
+return this.effectiveDir === "rtl" ? "right" : "left";
+```
+
+## Density
+
+Two densities: cozy (default) and compact. An ancestor carrying `data-ui5-compact-size`, `.ui5-content-density-compact` or `.sapUiSizeCompact` switches compact on by setting `--_ui5_content_density`.
+
+Scope compact values with a container style query — the pattern used across the theme CSS. Note the two distinct variables: `--ui5_content_density` (no leading `_`) is a **build-time** directive the postcss plugin reads; `--_ui5_content_density` (leading `_`) is the **runtime** signal set by `SystemCSSVars.css`. This matters: the `@container style(--ui5_content_density: compact)` block only works inside a `-parameters.css` file, where `cssVariablesTarget: "host"` runs the postcss plugin that strips the `@container` and merges both densities into one `:host` declaration — `--_ui5_bar_base_height: var(--_ui5-compact-size, 2.5rem) var(--_ui5-cozy-size, 2.75rem)`. The same block placed in component CSS (`themes/Foo.css`) is left unprocessed and never fires at runtime, because `--ui5_content_density` is never set on `:root`.
+
+```css
+@container style(--ui5_content_density: compact) {
+	:host {
+		--_ui5_button_base_height: var(--sapElement_Compact_Height);
+		--_ui5_button_base_min_width: 2rem;
+	}
+}
+```
+
+A density block that styles *slotted children* belongs in the component CSS, never in `<Component>-parameters.css`: a `-parameters.css` declaration is merged into a single shared `CSSStyleSheet` adopted into every component's shadow root, where `:host` applies to all of them and `::slotted()` would target slots across all of them. Same rule for any variable whose producer and consumer are different components.
+
+```css
+@container style(--ui5_content_density: compact) {
+	::slotted([ui5-button]) {
+		--_ui5_button_overlay_badge_offset: initial;
+	}
+}
+```
+
+## Focus, animation, high contrast
+
+| Concern | Rule |
+|---------|------|
+| Sizes | `rem` for element sizing; `px` is acceptable for hairline borders and small positioning offsets |
+| Animation | Gate on `getAnimationMode()`; see `performance.md` |
+| High contrast | `_hcb` and `_hcw` resolve most colours to pure black and white |
+
+Focus styling is a pseudo-element border, not a native outline: the focusable root sets `outline: none` and the ring is drawn on `:after`. Where a native outline suffices, drive it from the tokens directly.
+
+```css
+	border: var(--_ui5_button_focused_border);  /* resolves to var(--sapContent_FocusColor) */
+
+	outline: var(--sapContent_FocusWidth) var(--sapContent_FocusStyle) var(--sapContent_FocusColor);
+	outline-offset: calc(-1 * var(--sapContent_FocusWidth));
+```
diff --git a/packages/base/AGENTS.md b/packages/base/AGENTS.md
index 83620f9a9ebd7..1eb0877334963 100644
--- a/packages/base/AGENTS.md
+++ b/packages/base/AGENTS.md
@@ -1,195 +1,34 @@
 # AGENTS.md - UI5 Web Components Development Guide
 
-This file provides guidance for AI coding assistants when developing web components built on `@ui5/webcomponents-base`.
+This file guides AI coding assistants developing components built on `@ui5/webcomponents-base`.
 
 > **Working in the ui5-webcomponents monorepo?** See the [root AGENTS.md](../../AGENTS.md) for repository commands, build flow, and commit guidelines.
 
-## Component Architecture
+## Knowledge Base — read this first
 
-Components use decorator-based definitions with Preact JSX templates:
+The conventions, guardrails, and good/bad examples for writing components live in the **AI Knowledge Base**
+at [`ai-knowledge-base/`](../../ai-knowledge-base/) (repo root). It is the single source of truth, for any AI
+tool. Load it **on demand**, not up front.
 
-```typescript
-import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
-import { customElement, property, slot } from "@ui5/webcomponents-base/dist/decorators.js";
-import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
+**Read [`ai-knowledge-base/INDEX.md`](../../ai-knowledge-base/INDEX.md) before you edit code whenever any of these is true:**
 
-@customElement({
-  tag: "my-button",
-  renderer: jsxRenderer,
-  template: MyButtonTemplate,
-  styles: myButtonCss,
-  languageAware: true,  // Re-render on language change
-  themeAware: true,     // Re-render on theme change
-})
-class MyButton extends UI5Element {
-  @property() design: `${ButtonDesign}` = "Default";
-  @property({ type: Boolean }) disabled = false;
-  @slot({ type: HTMLElement, "default": true }) content!: Array<HTMLElement>;
-}
-```
+- You add, change, review, or test a `.ts`, `.tsx`, or `.css` file under `packages/`.
+- You write or debug a Cypress spec.
+- The task names a `ui5-*` component, a property, slot, event, design token, or ARIA attribute.
 
-**Recommended file structure for a component:**
-- `src/ComponentName.ts` - Component class with decorators
-- `src/ComponentNameTemplate.tsx` - JSX template
-- `src/themes/ComponentName.css` - Styles (use CSS variables for theming)
-- `src/i18n/messagebundle*.properties` - Translations (if language-aware)
+Then open **only** the reference file its routing table names for your task — do not read every file.
+The relevant references for base-package work:
 
-## Critical Development Rules
+| Your task | Open |
+|-----------|------|
+| How a component is assembled, which file does what | `references/component-anatomy.md` |
+| A property, slot, event, or public method | `references/api-design.md` |
+| A brand-new component | `references/new-component.md` |
+| A Cypress test | `references/testing.md` |
+| CSS, theming, design tokens, `themeAware` | `references/theming-and-css.md` |
+| Keyboard, ARIA, focus | `references/accessibility.md` |
+| Any user-visible text, `languageAware` | `references/i18n.md` |
 
-### DOM Manipulation Anti-Pattern
-
-Accessing DOM elements via `@query` or `querySelector` is allowed only for calling methods like `.focus()`:
-
-```typescript
-@query("[ui5-input]")
-_input!: Input;
-
-// GOOD - calling methods
-this._input?.focus();
-
-// BAD - modifying properties directly
-this._input.value = "don't do this";
-```
-
-Always modify child component state through the template:
-
-```tsx
-// GOOD - use the template for state
-<Input value={this.inputValue} />
-```
-
-### Always Use Template Literal Types for Enums
-
-This pattern eliminates runtime overhead from enum objects:
-
-**Imports:**
-```typescript
-// BAD - imports the enum object (runtime overhead)
-import ButtonDesign from "./types/ButtonDesign.js";
-
-// GOOD - import type only (no runtime overhead)
-import type ButtonDesign from "./types/ButtonDesign.js";
-```
-
-**Property types:**
-```typescript
-// BAD - uses enum object at runtime
-design: ButtonDesign = ButtonDesign.Default;
-
-// GOOD - template literal type with string value
-design: `${ButtonDesign}` = "Default";
-```
-
-**Value comparisons:**
-```typescript
-// BAD - runtime enum access
-if (this.design !== ButtonDesign.Transparent) { }
-
-// GOOD - string comparison (IDE autocomplete + TS type safety)
-if (this.design !== "Transparent") { }
-```
-
-### Scoping-Safe Code (Required for Micro-Frontend Support)
-
-UI5 Web Components support tag name scoping for micro-frontend scenarios where multiple versions may coexist. Always use attribute selectors:
-
-**In TypeScript:**
-```typescript
-// BAD - hard-coded tag names break when scoped
-this.shadowRoot.querySelector("ui5-popover")
-element.tagName === "UI5-BUTTON"
-
-// GOOD - attribute selectors work with any scoping
-this.shadowRoot.querySelector("[ui5-popover]")
-```
-
-**In CSS:**
-```css
-/* BAD - tag selector breaks with scoping */
-ui5-button.accept-btn { color: green; }
-
-/* GOOD - attribute selector works with scoping */
-[ui5-button].accept-btn { color: green; }
-```
-
-### No `instanceof` Checks
-
-`instanceof` fails when multiple versions of the framework are loaded. Use duck-typing instead:
-
-```typescript
-// BAD - fails with multiple framework versions
-if (element instanceof Button) { }
-
-// BAD - tag name could be scoped (e.g., "UI5-BUTTON-F5331039")
-if (element.tagName === "UI5-BUTTON") { }
-
-// GOOD - use createInstanceChecker helper
-import createInstanceChecker from "@ui5/webcomponents-base/dist/util/createInstanceChecker.js";
-
-// In your component class:
-class MyItem extends UI5Element {
-  readonly isMyItem = true;  // Duck-typing marker
-}
-export const isInstanceOfMyItem = createInstanceChecker<MyItem>("isMyItem");
-
-// Usage:
-if (isInstanceOfMyItem(element)) {
-  // element is typed as MyItem
-}
-```
-
-### Property and Event Conventions
-
-- **Never change public properties programmatically** - only in response to user interaction
-- **Use `noAttribute: true`** for private/internal properties not used in CSS selectors
-- **Fire events for all user interactions** - applications rely on events for state management
-- **Import icons explicitly** - don't rely on bundled icon imports
-
-```typescript
-@property({ noAttribute: true })
-_internalState = false;  // Won't create HTML attribute
-
-// Fire events for user interactions
-this.fireDecoratorEvent("change", { value: this.value });
-```
-
-## Testing with Cypress
-
-Tests use Cypress component testing with JSX mounting:
-
-```typescript
-import MyButton from "../../src/MyButton.js";
-
-describe("MyButton", () => {
-  it("fires click event", () => {
-    cy.mount(<MyButton>Click me</MyButton>);
-
-    // Use attribute selector for scoping safety
-    cy.get("[my-button]").then(($btn) => {
-      $btn[0].addEventListener("click", cy.stub().as("clicked"));
-    });
-
-    // Use cypress-real-events for realistic interaction
-    cy.get("[my-button]").realClick();
-    cy.get("@clicked").should("have.been.called");
-  });
-});
-```
-
-**Key testing patterns:**
-- Use `cypress-real-events`: `realClick()`, `realPress()`, `realType()` instead of Cypress simulated events
-- Always use attribute selectors `[my-component]` not tag selectors `my-component`
-- Use `.only` to run a single test case when debugging, remove before committing
-
-## Summary of Rules
-
-| Rule | Bad | Good |
-|------|-----|------|
-| Enum imports | `import Enum from "..."` | `import type Enum from "..."` |
-| Enum types | `prop: Enum` | `prop: \`${Enum}\`` |
-| Enum values | `Enum.Value` | `"Value"` |
-| DOM queries | `querySelector("ui5-tag")` | `querySelector("[ui5-tag]")` |
-| CSS selectors | `ui5-tag { }` | `[ui5-tag] { }` |
-| Type checks | `instanceof Component` | `isInstanceOfComponent(el)` |
-| Tag comparison | `el.tagName === "UI5-TAG"` | Use instance checker |
-| DOM mutation | `this._ref.value = x` | `<Comp value={x} />` in template |
+The non-negotiables (full rationale in `INDEX.md`): never run the full test suite;
+enums are type-only; select by attribute not tag name; no `instanceof` on a UI5 class; `@query` refs are
+for method calls like `.focus()`, not state; make the smallest change that solves the problem.