# AD: Admin redesign

Track AD (owner decision, 2026-11-14). This document is AD-1: the audit, the references, the font study and the proposed structure. AD-2 turns it into a Storybook prototype, and the owner approves the design before anything is built (AD-3 and later).

## Owner decisions (2026-11-14)

- **Look:** KimaAI's admin becomes an app with its own brand inside WordPress, as Yoast, WooCommerce and Jetpack have done. The WordPress admin bar and side menu stay, and so do WordPress accessibility patterns.
- **Navigation:** one KimaAI app with its own left navigation. The WordPress submenu keeps only a few entry points into it.
- **References:** Linear and Vercel (minimal, dense, keyboard-first), WooCommerce and Jetpack (React admin screens inside WordPress), Yoast (settings redesign since 20.0).
- **Multilingual:** sites with Polylang or WPML are designed in from the start.
- **Colours:** from the kimaai.com tokens, which DS already shares (`src/global/tokens.css`, checked against the website by `scripts/check-brand-tokens.mjs`).
- **Font:** chosen between open-licence fonts close to Satoshi and the system font (below).

## Audit of today's admin

Counted on `development` on 2026-11-14, on a free install.

### What exists

| Area           | Today                                                                                                                                                                                                                                                                      |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| WordPress menu | Four React pages: `kimaai` (settings), `kimaai-feedback-analytics` (Insights), `kimaai-leads` and `kimaai-wizard`, plus the Freemius pages (Account, Pricing and others)                                                                                                   |
| Settings       | 27 pages in 6 sidebar groups: AI Services, ChatBot, Embedding, Integrations, White label (premium only) and Tools. They hold 218 fields: 167 on pages, 51 in repeatable items                                                                                              |
| Biggest page   | Chatbot settings, with 16 sections and 100 fields                                                                                                                                                                                                                          |
| Pro            | 16 pages are locked on a free install, plus 6 sections and 56 fields on the chatbot settings page                                                                                                                                                                          |
| Save models    | Three: the main save bar; repeatable tables, which save at once from their modal; and components that save themselves (sync, MCP, history, logs, export)                                                                                                                   |
| Credentials    | 10 secret fields in 8 places: AI environments, embedding environments, Zendesk, Freshdesk and Help Scout (inside the 15-field handoff section), lead webhook, HubSpot, Brevo, Mailchimp and Pipedrive. Five integration pages are only "enable, key, one to three options" |
| Search         | None. Only the admin assistant's settings catalogue finds settings by meaning, and the assistant rail is switched off by default (`global.php`)                                                                                                                            |
| Preview        | A live chatbot preview beside chatbot appearance, chatbot settings and WooCommerce                                                                                                                                                                                         |
| Dark mode      | Per user, in user meta; the toggle sits in four places                                                                                                                                                                                                                     |
| Notices        | WordPress and third-party notices print above the React root. The plugin's own `Notices` component is never rendered                                                                                                                                                       |
| Setup wizard   | Six steps: welcome, AI environment, chat model, chat preview, appearance, done                                                                                                                                                                                             |

### Problems the redesign has to solve

1. **Too much in one place, too little in others.** The chatbot settings page has 100 fields in 16 sections, while each CRM has a page of three fields. Nearly every credential has a page of its own, yet helpdesk keys sit inside the handoff section.
2. **No way to find a setting** other than knowing the menu.
3. **Saving surprises:**
   - a repeatable modal saves the whole settings state, including unsaved edits on other pages;
   - nothing warns before leaving with unsaved changes;
   - Discard reverts every page, not only the open one.
4. **Gaps in multilingual handling:**
   - Nine translatable fields inside repeatable items (glossary, pinned answers, quick actions) are neither registered with WPML or Polylang nor locked in the UI, so they cannot be translated.
   - `wpml-config.xml` lacks the white-label credit.
5. **Leftovers:**
   - `?tab=tools` opens Function calling, while "Tools" is also a menu group;
   - `settings_ui.colors` reaches the admin but no CSS reads it;
   - the wizard falls back to `page=kimaai-settings`, a slug that does not exist.
6. **Links others rely on.** Notices, the Health panel, content-gap actions, the Leads page, docs and the assistant link to `?page=kimaai&tab=<link>`. Copy in the UI names menu paths ("Chatbot → Pinned Answers"). Every old link has to keep working.

### What the redesign builds on

React 18 with WordPress's own `@wordpress/components` (core's copy at runtime), Tailwind 4 loaded only on KimaAI's pages, the brand tokens, the DS atoms (`Card`, `EmptyState`, `Icon`, `StatusBadge`, `BetaBadge`, `ProBadge` and others), DataViews, the field registry (`kimaai.admin.fieldComponents`, `registerFieldComponent`) and the settings schema in PHP.

Third parties extend it through:

- `kimaai_settings_schema_files`: add-ons add settings groups;
- `kimaai_settings_ui_config`: a white-label shell with logo, version and badges;
- `kimaai_wizard_config`;
- the feature statuses (FS).

All of them keep working.

## What the references do

| Pattern                                                                                                                               | Where it comes from                                                                                                                                                                                                                                                                                                        | Fit for KimaAI                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| A grouped left sidebar inside the app (icon, label, collapsible items) that becomes a drawer below 783 px, WordPress's own breakpoint | Yoast settings ([source](https://github.com/Yoast/wordpress-seo/blob/trunk/packages/js/src/settings/app.js)), Vercel's sidebar ([changelog](https://vercel.com/changelog/new-dashboard-navigation-available))                                                                                                              | One app, one navigation                                                       |
| ⌘K / Ctrl+K search over every setting, grouped by page, with the result count announced to screen readers                             | Yoast ([search.js](https://github.com/Yoast/wordpress-seo/blob/trunk/packages/js/src/settings/components/search.js)), Linear ([guide](https://linear.app/enablement/guides/navigating-linear))                                                                                                                             | Settings can be found without knowing the menu                                |
| An app header with breadcrumbs, title and actions                                                                                     | Jetpack `AdminPage` on `@wordpress/admin-ui` `Page` ([source](https://github.com/Automattic/jetpack/blob/trunk/projects/js-packages/components/components/admin-page/index.tsx)), WooCommerce header ([docs](https://developer.woocommerce.com/docs/extensions/settings-and-config/working-with-woocommerce-admin-pages/)) | Context on deep pages; where the preview, assistant and language indicator go |
| WordPress notices caught by `.wp-header-end` and shown in the app's own notice area, not deleted                                      | WooCommerce `Loader.php` ([source](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/Admin/Loader.php)). Yoast removes all notices instead                                                                                                                                            | A clean app without hiding other plugins' important notices                   |
| Sections as `<fieldset>`, with title and description on the left and fields on the right, stacked when narrow                         | Yoast ([fieldset-layout.js](https://github.com/Yoast/wordpress-seo/blob/trunk/packages/js/src/shared-admin/components/fieldset-layout.js))                                                                                                                                                                                 | Already how KimaAI lays out sections; keep it and make it accessible          |
| A save bar that appears only with unsaved changes: Save, and Discard with a confirmation, plus a warning before leaving the page      | Yoast ([form-layout.js](https://github.com/Yoast/wordpress-seo/blob/trunk/packages/js/src/settings/components/form-layout.js))                                                                                                                                                                                             | Fixes the saving surprises                                                    |
| Integrations as cards by category, with a status and a toggle or "Manage"                                                             | Yoast integrations ([source](https://github.com/Yoast/wordpress-seo/tree/trunk/packages/js/src/integrations-page)), Chatbase channels ([docs](https://www.chatbase.co/docs/user-guides/chatbot/settings))                                                                                                                  | One Connections page instead of a page per key                                |
| One fixed set of statuses for connections: connected, not set up, error with a fix, needs Pro, plugin missing                         | My Jetpack `PRODUCT_STATUSES` ([constants.ts](https://github.com/Automattic/jetpack/blob/trunk/projects/packages/my-jetpack/_inc/constants.ts))                                                                                                                                                                            | The same words on Home, Connections and in the assistant                      |
| A home screen with a setup checklist and the live chatbot beside it; no redirect after activation and no tours                        | Intercom Fin "Simple deploy" ([help](https://www.intercom.com/help/en/articles/8286630-set-up-and-go-live-with-fin)), WooCommerce task list and onboarding rules ([UX guidelines](https://developer.woocommerce.com/docs/extensions/ux-guidelines-extensions/onboarding/))                                                 | Home shows what is left to do                                                 |
| A scoped component library: one root wrapper, scoped reset, styles that leak neither in nor out                                       | Yoast `@yoast/ui-library` and its Tailwind preset ([readme](https://github.com/Yoast/wordpress-seo/blob/trunk/packages/ui-library/readme.md))                                                                                                                                                                              | KimaAI uses Tailwind 4 with a global reset today; scope it to the app root    |
| Calm chrome, role-based colour scales (fill, border, text), dense and well aligned                                                    | Linear ([redesign](https://linear.app/now/how-we-redesigned-the-linear-ui)), Vercel Geist ([colours](https://vercel.com/geist/colors))                                                                                                                                                                                     | The visual direction                                                          |

**Multilingual:**

- WPML and Polylang both read the plugin's `wpml-config.xml` admin-texts ([WPML](https://wpml.org/documentation/support/language-configuration-files/translate-strings-in-wp-options-table), [Polylang](https://polylang.pro/doc/the-wpml-config-xml-file/)).
- Dynamic strings go through `wpml_register_single_string` and `pll_register_string` ([WPML](https://wpml.org/documentation/support/achieving-wpml-compatibility-for-your-themes-and-plugins/), [Polylang](https://polylang.pro/doc/function-reference/)).
- Yoast leaves translation entirely to WPML String Translation ([wpml-config.xml](https://github.com/Yoast/wordpress-seo/blob/trunk/wpml-config.xml)).
- None of the references marks translatable settings inside its own UI. KimaAI already does (the "edit it in the default language" notice), and the redesign makes that visible on every page.

## Font

**Satoshi cannot be bundled.** The kimaai.com font comes under the ITF Free Font License v2.0. That licence forbids distributing the font "through another … application or platform" and making it available "for use by third parties through any website, application" (§02, `License/FFL.txt` in the Fontshare download). Loading it from the Fontshare API inside the plugin very likely falls under the same ban [legal reading, unverified with ITF]. It would also send visitors' IP addresses to a third party.

**WordPress.org accepts OFL fonts.** The plugin directory counts the SIL OFL as GPL-compatible for fonts ([theme reviewers, 2013](https://lists.wordpress.org/pipermail/theme-reviewers/2013-May/012807.html); [Themes handbook](https://make.wordpress.org/themes/handbook/review/resources/)). Twenty Twenty-Four and Twenty Twenty-Five bundle Inter, Instrument Sans and Manrope under it.

**Shortlist.** All OFL 1.1. Measured from the font files: variable WOFF2 sizes, and x-height relative to cap height (x/H). Satoshi has an x/H of 0.676.

| Font               | Coverage                                      | Variable WOFF2 (Latin subset / full) | Tabular figures | x/H   | Close to Satoshi                                                                                                  |
| ------------------ | --------------------------------------------- | ------------------------------------ | --------------- | ----- | ----------------------------------------------------------------------------------------------------------------- |
| **Geist** (Vercel) | Latin, Latin Ext, Cyrillic, Vietnamese        | 28 KB / 68 KB                        | yes             | 0.746 | medium: grotesk with geometric touches; one family with the Geist Mono we already bundle; it is Vercel's own font |
| **Figtree**        | Latin, Latin Ext                              | 19 KB / 27 KB                        | yes             | 0.714 | high: geometric, a, g and R very close                                                                            |
| Plus Jakarta Sans  | Latin, Latin Ext, Vietnamese                  | 26 KB / 59 KB                        | yes             | 0.719 | high, a little narrow                                                                                             |
| Manrope            | Latin, Latin Ext, Cyrillic, Greek, Vietnamese | 24 KB / 52 KB                        | yes             | 0.750 | medium-high, no italic                                                                                            |
| Inter              | Latin, Latin Ext, Cyrillic, Greek, Vietnamese | 47 KB / 352 KB                       | yes             | 0.750 | low-medium: neutral, the heaviest                                                                                 |

None of them covers Arabic script. **Vazirmatn** (OFL 1.1, the Non-Latin build, 48 KB variable) covers Persian and Arabic. It loads only when such text is on screen (`unicode-range`). It could also replace Yekan, whose licence is still open.

**Recommendation:**

- **Geist** as the admin font. It matches the Linear and Vercel reference the owner chose, shares metrics with Geist Mono, has tabular figures for the data pages and covers Cyrillic.
- **Figtree** if looking like kimaai.com matters more than the Vercel look.
- **Vazirmatn** for Arabic script.
- Self-hosted, loaded only on KimaAI's pages, with the WordPress system stack as the fallback for other scripts.

The owner chooses at the AD-2 approval, from both fonts side by side in Storybook.

**Risks:**

- Geist is visibly more grotesk than Satoshi, so the admin will not mirror the website exactly.
- Greek, and for Figtree also Cyrillic, fall back to the system font.

## Proposed structure

### Navigation

One app at `admin.php?page=kimaai`. A left sidebar inside the app holds the groups below, with the logo, the plan label and the version from `settings_ui` at the top. The app header shows breadcrumbs, the page title, and the actions: preview, admin assistant, ⌘K search, and the language indicator on multilingual sites.

| Group           | Pages                                                                                                                                                                                                       | Today's pages and sections that move there                                                                                                                                          |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Home**        | Home                                                                                                                                                                                                        | new: setup checklist, status of every connection, conversations and resolution this week (Insights overview), link to the live preview                                              |
| **Chatbot**     | Appearance; Behaviour; Quick actions; Conversations                                                                                                                                                         | chatbot appearance; chatbot settings: model, advanced model, instructions, feedback; quick actions; chat history                                                                    |
| **Knowledge**   | Sources and sync; Content templates; Pinned answers; Glossary; Search on your site; Quality                                                                                                                 | embedding sync, query, collections and health; embedding settings; content templates; pinned answers with curation; glossary; Ask AI and search answers; eval cases with evaluation |
| **Leads**       | Leads; Lead form; Meeting booking                                                                                                                                                                           | Leads page; lead capture section; meeting booking                                                                                                                                   |
| **Support**     | Customer Centre; Handoff                                                                                                                                                                                    | customer centre section; handoff section without its credentials                                                                                                                    |
| **Insights**    | Overview; Topics; Content gaps; Conversions; Feedback                                                                                                                                                       | the Insights page and its tabs                                                                                                                                                      |
| **Connections** | one page of cards: AI providers, Vector database, CRM and email (HubSpot, Brevo, Mailchimp, Pipedrive, lead webhook), Helpdesks (FluentSupport, Zendesk, Freshdesk, Help Scout), Plugins (WooCommerce), MCP | AI environments; embedding environments; the CRM pages; the helpdesk fields; WooCommerce; MCP server                                                                                |
| **Settings**    | Privacy and security; Cost and usage; Function tools; White label; Logs; Data and export; About                                                                                                             | security section; observability; function calling and the tools section; white label; log settings and logs; data management and export/import; About                               |

Settings groups added by add-ons through `kimaai_settings_schema_files` appear under their own name below Settings. The feature statuses (FS) and the Pro badge (PL) work on every item as they do today.

### Connections

- A grid of cards in categories.
- Each card shows the service, what it is used for, and one status from a fixed set: connected, not set up, error (with how to fix it), needs Pro, plugin missing.
- "Manage" opens the connection's detail view: its credentials, a test of the connection, and its few options. A score field, for example, stays with its CRM.
- AI providers and vector databases keep several environments each (today's repeatables) as a list inside their card.
- Secrets are never shown again after saving, only "set" and a way to replace them. Today the stored values come back through `/wp/v2/settings`. Masking them changes the REST output, so it gets its own item and its own review.

### Settings pages

- Sections as `<fieldset>` with a legend: title and description on the left, fields on the right, stacked below the app's breakpoint (today's layout, made accessible).
- Rarely used settings sit in a collapsible "Advanced" part of their section, as in WooCommerce's settings guidelines.
- **Saving:**
    - a save bar appears with unsaved changes on the open page;
    - Discard reverts only that page, after a confirmation;
    - the browser warns before leaving with unsaved changes;
    - a repeatable's modal saves only its own list.
- The live preview stays beside Appearance and Behaviour.

### Search

⌘K / Ctrl+K opens a search over every setting:

- titles, descriptions and section names from the schema, grouped by page;
- results that open the page and scroll to the setting, using today's `data-kimaai-setting-path` targets;
- the result count announced to screen readers.

Later it can run actions and hand a question to the admin assistant.

### Home and setup

- Home replaces the separate wizard page. Its checklist covers: an AI provider, the chat model, what the chatbot knows (content and sync), the look, going live.
- Each step opens the page it concerns; finished steps are ticked from the settings.
- The live chatbot sits beside the checklist.
- The wizard's steps (`kimaai_wizard_config`) become checklist steps. `page=kimaai-wizard` keeps working as a link to Home.
- There is no redirect after activation, as WooCommerce's guidelines advise. Freemius' first-path points at Home.

### Multilingual

- On a site with WPML or Polylang, the app header shows the admin language and the default language.
- Fields that are translated per language carry a "Translatable" label with a link to String Translation or Polylang Strings.
- In a language other than the default, those fields are read-only, with the hint to edit them in the default language (today's lock, shown the same way on every page).
- **Fix on the way:**
    - the translatable fields of repeatable items (glossary, pinned answers, quick actions) are registered and translated per item;
    - the white-label credit goes into `wpml-config.xml`.
- No storage of KimaAI's own per language: WPML and Polylang stay the source, as the references do.

### Links and compatibility

- Every old link keeps working: `?page=kimaai&tab=<old link>` and `&sub-tab=` map to the new route, and `kimaai-feedback-analytics`, `kimaai-leads` and `kimaai-wizard` open the matching place in the app.
- The WordPress submenu keeps Home, Insights, Leads and Settings as entry points.
- UI copy that names menu paths is updated.
- The field registry, the settings schema format, `kimaai_settings_ui_config`, `kimaai_settings_schema_files`, `kimaai_wizard_config` and the feature statuses stay.
- WordPress notices are caught by `.wp-header-end` in a hidden wrapper and shown in the app's notice area, as WooCommerce does.

### Look

- Tokens from `src/global/tokens.css`, organised as role scales for fill, border and text (the Vercel Geist model), in light and dark. Dark mode stays per user.
- Calm chrome; the brand colour for actions and the current item only.
- Medium density, 14 px body text, a type scale from the font study, Lucide icons at 1.75 stroke.
- Tailwind scoped to the app root, so the reset and styles neither leak into wp-admin nor take in other plugins' styles.
- WCAG 2.2 AA: labels tied to fields, no state by colour alone, the native focus ring, keyboard paths for the sidebar, search and dialogs.

## AD-2: the prototype

The prototype is built in Storybook, from the real tokens and components, in light and dark and in LTR and RTL. It is published to the AI box Storybook (`npm run storybook:publish`).

- **Foundations:**
    - Geist and Figtree side by side, with Vazirmatn for Persian;
    - the type scale;
    - colour roles;
    - spacing.
- **Shell:** sidebar, header with breadcrumbs, the ⌘K search, notices, the save bar.
- **Pages:**
    - Home with the checklist;
    - Chatbot appearance with the preview;
    - Chatbot behaviour;
    - Connections, with one detail view;
    - Knowledge sources;
    - Leads;
    - Insights overview;
    - MCP;
    - a multilingual page in a second language;
    - a free install with Pro and Beta labels.

The pages run on fixture data. Nothing is saved.

**For the owner's approval:**

- the font, Geist or Figtree;
- the structure above;
- Home replacing the wizard page;
- Connections with detail views;
- the look.

## Owner feedback on the prototype (2026-11-14, round 1)

Applied to the prototype:

- **The live chatbot stays visible.** A full-height panel on the right of every page that changes how the chatbot looks or speaks, as in today's admin: appearance, behaviour, quick actions, lead form, search on your site. It has desktop/mobile and light/dark toggles and shows unsaved changes.
- **The sidebar collapses** to an icon rail and expands again.
- **The logo, the plan and the version** sit in the sidebar. Its footer holds documentation, what's new and About.
- **Every page is drawn**, About included, not only the layout.
- **More icons:** page headers, sections, stat tiles, connection cards, checklist steps, tabs and tables.
- **Minimal corner radius in the admin:** 4 px for controls, 6 px for cards and panels. This replaces the website's 10 and 20 px for the admin only; the chatbot keeps its own radius setting.
- **A richer, less basic look:**
    - stat tiles with trends and sparklines;
    - charts;
    - a feed of the latest conversations and a "Needs you" list on Home;
    - a "Live on N pages" indicator;
    - keyboard hints;
    - a dark save bar;
    - tabs inside pages;
    - Pro pages for free installs with what Pro adds.

## Owner feedback on the prototype (2026-11-14, round 2)

- **Approved:** Home replaces the setup wizard page. The admin font is my choice: Geist, as recommended above.
- **Asked for:** more polish, a premium look and better UX. The owner shared reference mock-ups for this.
- **Applied in round 3:**
    - **Premium look:**
    - a soft brand glow behind the page, strong in dark mode;
    - large bold page titles with a large icon tile;
    - cards with a soft shadow and an icon-led header;
    - primary buttons with a glow;
    - a "Premium" mark with a crown and the version under the logo;
    - a plan card and the site's user at the bottom of the sidebar.
    - **Sidebar:** every item has its own icon.
    - **Top bar:** back, the colour-mode switch, notifications, help and the user menu.
    - **Settings as rows:** label and description on the left, the control on the right. That covers segmented controls, number fields with a unit and a slider, and an icon picker with a check mark.
    - **Saving in the page header:** "Unsaved changes", Reset and Save.
    - **Live preview:** a sticky card beside the settings, with a browser frame, a mock site, the chatbot and its launcher, a "Real-time" badge, and desktop/mobile and light/dark switches.
    - **Tables:** search, filters, a count, rows with an icon and a description, provider chips, status, "last tested" and a ⋯ menu (edit, test, duplicate, delete), with a footer count. Connections gains tabs for AI environments and vector databases.
    - **Corners:** 6 px for controls, 8 px for cards (10 px for hero panels). This sits between the round-1 sharpness and the references.
- **Provider logos:** letter marks stand in for them until the providers allow their logos (the website's provider-logos question).

## Shared patterns (2026-11-14)

Owner, 2026-11-14: the design is approved, and the pages are built step by step without drawing all of them first. Only the patterns that almost every page needs and the prototype did not show get a Storybook page first ("Admin redesign/Patterns"):

- **Editing a list entry.** Rich entries (AI environments, quick actions, eval cases, function tools) open in a side panel over the list. Small ones (a glossary term) open in a dialog. Both save only that entry. Field errors appear under the field, and the connection test shows its result inline.
- **Empty, loading and error states.**
    - An empty state says what fills it and offers the next step.
    - Loading keeps the layout, with placeholders.
    - An error says what happened and how to fix it, and keeps unsaved changes.
- **Knowledge sync and query.**
    - The sync shows progress, counts, the current item and what failed, and can be paused.
    - The query tester shows the hits with their scores and text.
- **Confirmations and messages.**
    - Deleting asks first and names what goes. Deleting many asks for the word "DELETE".
    - Success is a short message at the bottom, with Undo where possible.
    - A risky setting warns where it is switched on.
- **Technical values** (keys, URLs, code) read left to right in RTL too.

## Owner note (2026-11-14, after the approval)

Pages with the chatbot preview on the right use the full width of the screen. Their left and right padding and margins are minimal and they have no maximum content width, so the settings and the chatbot both get as much room as possible. The shell has a full-width mode for these pages (AD-3), and the Chatbot, lead form and site search pages use it (AD-6 to AD-8).

## Persian font (owner, 2026-11-14)

The admin keeps Yekan for Persian (`:lang(fa)`), as decided on 2026-11-13: Geist draws the Latin text, Yekan the Persian. Vazirmatn NL is only for Arabic and the other Arabic-script languages.

## AD-3 and later

The items are defined after the approval. The expected order:

1. **App shell:** sidebar, header, routing with the old-link map, notices, scoped styles, the font.
2. **Settings anatomy and saving:** fieldsets, save bar per page, warning before leaving, repeatables saving only themselves.
3. **Connections.**
4. **The groups,** one by one: Chatbot, Knowledge, Leads, Support, Settings.
5. **Home and setup.**
6. **Search.**
7. **Multilingual fixes.**
8. **Insights, Leads and MCP inside the app.**
9. **Masking secrets** in the settings REST output.

**Tailwind scoping moved to AD-4** (AD-3, 2026-11-14). Scoping the reset and the utilities to the app root changes how every page's content looks, so it goes with the settings anatomy that restyles that content. Until then WordPress's element styles (common.css, forms.css), which sit outside any cascade layer and so beat Tailwind's layered utilities, step back only in the shell and the UI kit (`.kimaai-ui`, `revert-layer` in `src/admin/index.css`).

Each item keeps saved settings working (a migration where a key moves) and updates the e2e specs that pin today's links and menu texts. Those are `admin-settings`, `free-build`, `enterprise-kb`, `setup-wizard`, the Insights and Leads specs, and the page objects.

## AD-4: settings anatomy and saving (2026-11-14)

- **Sections as cards.** Each schema section is a card with an icon-led header. The icon is a Lucide name in the section's optional `icon` key (`'icon' => 'ShieldCheck'`); only the names in `src/admin/app/sectionIcons.js` are bundled, and any other name, or none, shows the default. A `panel` section collapses.
- **Setting rows.** Toggles, selects and short text fields are rows: label, labels and description on the start side, the control on the end side, tied to both. A field component opts in with a static `settingRow` (`toggle` or `input`) and then takes `layout="row"`, `controlId` and `descriptionId`. Textareas, the code editor, checkbox and radio groups, ranges, fields that share a row and add-on components stay stacked with their own label.
- **Saving per page.** Save, Reset and "Unsaved changes" sit in the page header. A save sends the open page's values and the stored values for every other page (the payload keeps `/wp/v2/settings` and `kimaai_options`), then puts the other pages' unsaved changes back. Another page of the app asks Save, Discard or Stay first (the browser's back button too); the browser warns before the page is left. Success and failure are short messages at the bottom; a failure keeps the changes and offers to try again.
- **List entries.** Rich entries open in a side panel, small ones (`'editor' => 'dialog'`: glossary, pinned answers) in a dialog. Saving an entry saves its list only; a failure keeps the entry open with the reason. Environments test their connection in the panel. Deleting asks first.
- **Tailwind scoped to the app roots.** `src/admin/preflight.css` is Tailwind's preflight, unchanged but nested under `:where(#kimaai-settings, #kimaai-feedback-analytics, #kimaai-leads, #kimaai-wizard, .components-modal__screen-overlay, .components-popover)`; `index.css` imports Tailwind's theme and utilities on their own. Inside the roots the reset is what it was (same rules, same zero specificity), so the pages look the same; outside, the admin bar, the WordPress menu and the footer are no longer reset, and the admin bar fix in `wpAdmin.css` is gone. The wizard root and WordPress's dialogs and popovers are in the list because they relied on the reset too. The copy has to follow Tailwind's preflight when Tailwind is updated.
- **Left for later:** a floating save for long pages when the header has scrolled away; the labels' wording in sentence case (the schema strings, page by page in AD-5 to AD-9); the list table itself (AD-5 onwards).

## AD-5: Connections (2026-11-14)

- **One page of the app.** `?page=kimaai&tab=connections` is the app's own page, not a schema page; its tabs are in `sub-tab` (`ai-environments`, `vector-databases`) and an open service's panel in `connection`. The old links (`ai-envs`, `embed-envs`, `lead-webhook`, `hubspot`, `brevo`, `mailchimp`, `pipedrive`, `woocommerce`) open it on the right tab or panel and the URL is rewritten to the new one (`src/admin/connections/routes.js`). The settings stay where they are stored; nothing migrates.
- **One status per service,** from what the plugin knows (`src/admin/connections/services.js`):
    - **needs Pro:** its settings are Pro and the install is free;
    - **plugin not active:** WooCommerce (today's plugin detection) or FluentSupport (`FLUENT_SUPPORT_VERSION`);
    - **needs attention, with the reason:** an environment's last connection test failed or it has no key; a CRM switched on without what it needs; the handoff channel's helpdesk without its keys;
    - **connected:** an environment with its key; a service switched on with what it needs; a helpdesk's keys, in the settings or in `wp-config.php`; the MCP endpoint on with a token;
    - **not set up:** anything else.
- **Failed lead deliveries** (AD-8, see there): a CRM switched on whose last delivery of some leads failed needs attention, with the count, the last error and a link to those leads. The prototype's "Recent deliveries" list in the panel is still not built: the Leads page holds the deliveries per lead. The prototype's "New connection" button and the table filters are left out until a page needs them.
- **Panels.** A service's settings open in the side panel as setting rows; Save sends that service's paths only (`saveScope`), Cancel drops the panel's changes. A stored password shows as "Saved" with Replace; a replacement left empty keeps the stored key. Only the environments have a connection test endpoint, so only their panels test.
- **Helpdesks.** Their keys keep their option keys in the chatbot settings and are marked `'connection' => '<helpdesk>'` with `'setInConfig'` (the `wp-config.php` constant is set); the handoff section hides them and links to Connections.
- **The lists.** AI environments and vector databases are today's lists in the app's table: name with a line under it, provider with a letter mark, status, last tested, and a ⋯ menu per row (edit, test connection, duplicate, delete).
- **Floating save** (owner, after AD-4): on a settings page with unsaved changes whose header has scrolled out of view, a slim bar with "Unsaved changes", Reset and Save stays at the top of the content (`src/admin/app/FloatingSave.jsx`). The header's buttons stay the main ones and keep their test ids and live region.

## AD-6: Chatbot (2026-11-15)

- **Pages made of sections.** A page of the app can show a chosen set of sections of a schema page under its own link, title, description and icon (`SECTION_PAGES` in `src/admin/app/sectionPages.js`, applied to the menu in `buildMenu`). Its fields keep their settings paths and option keys; the page saves, resets and reports unsaved changes for those fields only (`pageScopePaths` of a `partial` item). The schema page keeps the sections no page has taken, under its own title, with a note that links to the pages that took the others, and it is dropped once none is left. Its old link keeps working: it opens what is left of it, or the first page made of its sections, and a setting the admin assistant previews opens on the page that now holds it (`routeForSetting`). AD-7 to AD-9 add their pages to the same list.
- **The Chatbot group:**
    - **Appearance** (`chatbot-appearance`): the cards General (show on every page, the side as a segmented control, the distances from the bottom and the side as a number with its unit and a slider), Branding (the chat icon picker with the real icons and a check on the chosen one, Custom as Pro, the header icon, colours and style), Messages (title, name, greeting, placeholder, AI disclosure, copy button, avatars, disclaimer, the credit link) and Attention popover. The option keys are unchanged; only the section keys and the labels moved.
    - **Behaviour** (`behaviour`): the sections `llm`, `llmAdvanced`, `chatbotInstructions` and `vectorDb` of the chatbot settings. A section whose meta names `advancedOf` and the fields marked `advanced` sit in a collapsed "Advanced settings" part at the end of their card, which opens by itself while the admin assistant previews one of them.
    - **Quick actions:** the list in the app's table with a side panel per entry, beside the live preview.
    - **Conversations** (`chatbot-history`): the list (search, select, delete) beside the open conversation's transcript and its facts: questions, model, tokens and page. The data and the delete actions are today's.
    - **More settings** (interim, `chatbot-settings`): the chatbot settings no page has taken yet, until AD-7 to AD-9 move them.
- **The live preview card** on Appearance, Behaviour and Quick actions: the real chatbot in today's preview iframe, so its CSS stays apart from the admin's, with unsaved changes, on a mock site in a browser frame with the site's address, Desktop or Mobile, the site's Light or Dark scheme (a chatbot in "system" mode follows it), and the side from the setting. These pages use the full-width mode. The chatbot opens as on a site: its launcher shows once the chat is closed, or with the attention popover.
- **RTL and targets:** the slider's track fills from the start side in right-to-left text; a checkbox group is a fieldset whose options are whole rows at least 32 px high, with no physical margins, so label and box no longer overlap in RTL.
- **Not built, for now:**
    - the prototype's Launcher card (size, shape, animation) and the header logo: no such settings exist yet;
    - the conversation's cost: the history stores tokens per answer but no price, so the facts show tokens.

## AD-7: Knowledge (2026-11-15)

- **Sections that join a page.** A `SECTION_PAGES` entry whose `link` names a page that exists adds its sections to that page (`joined`) instead of making a new one: above a list as cards, or as a tab of its own (`subTab`). They keep their option keys and are saved from that page's header; the list still saves its entries itself. An old link to the source page, or one that names a moved setting, opens the page and tab that hold it (`resolveMovedRoute`).
- **The Knowledge group:**
    - **Sources and sync** (`embedding`): one title over the tabs Sync, Query, Collections, Health and Settings. Above the tabs' content: the vector database and four figures from its health check (synced items and their chunks, what the vector database holds, what changed since the last sync, the index's health and the last sync).
    - **The health check** asks the AI provider for one test embedding, so it runs only where it ran before: on Sync and Health, once per vector database, shared by both. Query, Collections and Settings run none and show the figures only from a check already made on the page.
    - **Sync** is the app's table: search, the source and language filters, the published date to sort by, a ⋯ menu per row (sync, delete), bulk select with bulk sync and delete, the count of items shown, and pages. The sync and delete dialogs are today's. Health is the app's tables of checks with a state each. Query and collections are today's.
    - **Settings tab:** the former "Embedding settings" page (`embed-settings`), whose sections all joined Sources and sync. Its option keys are unchanged; `?tab=embed-settings` opens the tab, and so does the admin assistant.
    - **Content templates, Pinned answers, Glossary:** today's lists in the app's table with a ⋯ menu per row; a pinned answer and a term open in a dialog, a template in the side panel. The columns say what an entry does: the fields a template writes, how many other phrasings an answer matches, the approved wording.
    - **Pinned answers** has the matching settings (on or off, the threshold) above the list, from the chatbot settings' `curation` section.
    - **Search on your site** (`site-search`): the Ask AI and search answer sections of the chatbot settings, at the normal width and without the chatbot preview (owner, 2026-11-15): none of its settings changes the chatbot. The answer's timing is a segmented control. With both features hidden the page is not there; with one hidden, only the other shows.
    - **Quality** (`eval-cases`): the last run's score with its change and history, its cases, and the schedule as figures; the scheduled runs settings (`evaluation`, the judge, language and webhook in "Advanced settings"); the cases; the recent runs. The runs are the ones Pro records (`kimaai_eval_runs`, scheduled, WP-CLI or MCP), passed to the page in `kimaaiAdmin.evalRuns`.
- **Interim:** "More chatbot settings" keeps privacy, function tools, feedback, cost, handoff, Insights, Customer Centre and leads until AD-8 and AD-9; its note links to the four pages that took sections from it. Query and Collections are today's panels on the app's card.
- **Not built** (owner, 2026-11-15):
    - the prototype's tiles per source with "synced of total": no endpoint counts the published items and the synced ones per post type, and none is added now; the summary uses the health check's figures. A count per source is a possible later item;
    - "Run now" for the quality cases: each case is a real chatbot conversation that costs AI credits, so runs stay scheduled or on WP-CLI;
    - "Sync now" for everything: no endpoint does it today;
    - "matches" per pinned answer: no count of matches is kept;
    - a Beta label on Search on your site in the navigation: its two sections have features of their own, and its cards carry the labels.

## AD-7: Sources and sync in real WordPress (2026-11-15)

Looked at in WordPress Playground (the e2e blueprint without networking, Pro forced by the e2e option, a fake embedding client and a Qdrant entry on a closed local port), free and Pro, light and dark, with and without a vector database. Storybook had looked right; real wp-admin did not:

- **WordPress's forms.css won over the app's controls.** Its `select` (40 px, grey border, its own arrow, a 25rem cap since WordPress 6.8) and text fields sit outside the cascade layers, so they beat the utility classes; in dark mode `wpAdmin.css` also set every select's background with `!important`, which removed the arrow. The app's own selects and text fields (`.kimaai-ui`) now get the app's 36 px look in `src/admin/index.css`, and the dark rule leaves them out. Leads, Insights and MCP use the same classes and get the same fix. The app's checkboxes are no longer white squares in dark mode.
- **The vector database picker** was a WordPress SelectControl with the raw option label (`qdrant-Site knowledge-e2eembedenv`). It is now a bar in an app card: the name and provider from the settings, the WordPress environment, and a link to Connections.
- **A new install** has an empty vector database entry from the defaults (`provider-not-set-name-not-set-…`), and the page showed that label, an error, dashes in the tiles, "Unhealthy" and a second error. A site with no vector database for its WordPress environment, or one without its provider or key, now sees one step: connect a vector database on Connections. No health check runs and the tabs show nothing until then.
- **Query** was WordPress's TextControl, SelectControl and an old button whose icon and label broke apart. It is now an app card with the search field, the number of results and the app's button. Hits are compact cards: rank, page, score as a pill, the chunk with the question's words marked, and the details on demand.
- **Collections** was an old table and a form in WordPress controls. It is now the app's table with a ⋯ menu to delete, an empty state, and a "New collection" card; cloud and region show only for Pinecone. A failed load says what the vector database answered instead of "500": the embedding routes return `{ok: false, error}`, and `useEmbedding` now reads that message.
- **Health** was a card around cards. It is now a "Health check" card with the figures and "Check again", the groups as the app's tables, and "Local details". Check names write "AI" in capitals.
- **Smaller fixes:** the tile "Changed since the last sync" was cut off at 1440 px and is now "Changed since sync"; the provider reads "Qdrant", not "qdrant"; the free placeholder is tall enough for the upgrade panel that covers it.

## AD-8: Leads and Support (2026-11-15)

- **The Leads group:**
    - **Leads** (`page=kimaai-leads`, its own WordPress page as before, so the filterable leads capability still opens it): the app's table with the status as tabs (Leads, Declined, Erased, All), a search, the date range, Pro's delivery filter, the count, bulk delete and pages. A row shows the lead with its email and company, the page, what made the chatbot ask (with "Meeting booked" under it), the score, where Pro sent it and when it came; its ⋯ menu opens or deletes it. A lead opens in a side panel: contact and consent (the consent wording as text, never as markup), where it came from with the score's reasons and the meeting, every delivery with its attempts and last error, and the chat it came from (the lead's own conversation route). The data, REST routes, export and deletion are today's; the export follows the filters. Score, meeting and deliveries are Pro and each follows its feature: a hidden feature has no column or filter.
    - **Lead form** (`lead-form`): the lead capture section of the chatbot settings, split into the cards Lead capture, When to ask (the number of messages as a number with a slider), What to ask, Consent and After a lead. It sits beside the live preview, which shows a visitor's question answered with the lead form as the unsaved settings make it, while lead capture is on (`preview.scene`); the chat opens for it even with the attention popover on.
    - **Meeting booking** (`meeting-booking`): its one card, Booking page, with the service as a segmented control. Still its own schema page; nothing moved.
- **The Support group:** **Customer Centre** (`customer-centre`: who gets the tools, and what customers can ask) and **Handoff** (`handoff`: when a conversation goes to a person, and where it goes), both at the normal width without the preview: the preview does not show the "Talk to a person" button. The helpdesks' keys stay on Connections; the handoff channel links there, as in AD-5.
- **Pages made of sections, two additions:** a page whose sections all carry the same feature shows its Beta label once, in its header and the navigation (Lead form, Customer Centre); a page whose sections are all Pro is a Pro page, locked as a whole on a free install with the upgrade panel and no save (Customer Centre, Handoff). The option keys are unchanged; the section keys of the moved fields are new (`leadWhen`, `leadAsk`, `leadConsent`, `leadAfter`, `customerTools`, `handoffDestination`), and an old link or a setting the admin assistant previews opens the page that holds it (`routeForSetting`).
- **Failed deliveries per destination** (`LeadSyncModel::failures()`): how many leads' last delivery to each destination failed, the latest error and when. One grouped query over `kimaai_lead_sync` counts them, and the result stays in a transient until a delivery state moves to or from "failed" (`record()`) or a lead is deleted, erased or expires (`LeadModel`), for an hour at most. Chosen over a query on every admin page, which would scan the whole table on each KimaAI page load, and over counters kept up to date on each write, which drift when rows go by other paths (retention, erasure). The admin gets the summary in `kimaaiAdmin.leadDeliveries` on Pro sites with lead sync; the error is left out for a user who may not see the leads, since it can quote a lead's details. Connections shows a switched-on CRM with failures as "needs attention" with the count and the last error and links to the Leads page filtered by that destination (`failed`, also on the leads route and the export).
- **The upgrade panel** of every Pro page, list and panel is an app card: the crown in its tile, the title with the Pro label, one short line, what Pro adds when the page names it (Insights), and the button. The generic list of three is gone.
- **Interim:** "More chatbot settings" keeps privacy, function tools, feedback, cost and the Insights settings until AD-9.
- **Not built, for now:**
    - the prototype's "Contacted" status and its counts per tab: leads have no such status and the route counts only the open filter;
    - the trigger filter: the leads route has none, and it is not added now;
    - the Customer Centre tiles with each plugin's state ("Plugin not active"): the schema does not say which plugins are active; the tools are setting rows;
    - the handoff channel as tiles: it stays a select with five channels;
    - "Recent deliveries" in a CRM's panel on Connections (see AD-5).

## AD-9: Insights and Settings (2026-11-15)

- **Insights is a page of the app** (`tab=insights`), no longer a WordPress page of its own. Its REST routes ask for `manage_options` like the settings page, and no filter lets anyone else open it, so nothing speaks for a page of its own (Leads keeps one for its filterable capability, AD-8); as a page of the app it shares the settings save, the old-link handling and the Settings tab. `page=kimaai-feedback-analytics` stays registered for the WordPress menu and old links and redirects before any output (`AdminInit::insightsUrl`): its `tab` becomes the `sub-tab`, a feedback view from before Insights (`message-feedback`, `csat`) the Feedback tab's `view`. The WordPress menu's Insights entry stays current on the page.
- **One tab per report:** Overview, Topics, Content gaps, Conversions and Feedback, each a tab of the schema page `insights` (in `chatbot.php`) with its feature, so a hidden feature has no tab (`FeatureSchema`). With Insights hidden the page keeps its 1.5.13 name, Feedback Analytics, and the feedback report. The Settings tab holds the chatbot settings' sections `insights` and `feedback` (same option keys); with Insights hidden only the feedback one is left.
    - **Overview:** four figure tiles, how the ended conversations end as meters, the top pages in the app's table.
    - **Topics:** the app's table with the change against the range before and the resolution as a meter.
    - **Content gaps:** a card per topic with its figures, three sample questions, the closest page and the three actions (pinned answer, eval case, draft post).
    - **Conversions:** six figure tiles, the orders and the leads, meetings and forms in the app's table.
    - **Feedback:** Overview, Message feedback and CSAT as a segmented control (`view`); the figures as tiles and the charts in app cards. The two lists keep their DataViews table and conversation panel inside an app card.
    - The REST calls, the date ranges, the CSV exports and the actions are today's; a report that is switched off says so and links to the Settings tab. Free installs see today's free Overview and the upgrade card on the Pro tabs.
- **The Settings group,** as the prototype orders it:
    - **Privacy and security** (`privacy`): the chatbot settings' security section split into the cards Consent, Personal data, Retention, and Blocked words and addresses (new section keys `privacyData`, `privacyRetention`, `privacyAccess`; `chatbotSecurity` is the Consent card). Normal width, no preview.
    - **Usage and cost** (`usage`): the token usage and budget section, a Pro page.
    - **Function tools** (`tools`): the allowed functions above the list of functions, which is now the app's table (name in code type, what it does, on or off).
    - **White label:** its one card, Footer credit.
    - **MCP server:** the connection with the endpoint switch and the environment as a segmented control, a form for a new token, the tokens in the app's table with a pill per scope, and how to connect. Its settings save themselves, as before.
    - **Logs** (`logs`): the files and the viewer in cards, and the log settings as its Settings tab; `tab=log-settings` opens that tab.
    - **Data and export** (`export-settings`): the export and import as cards and the uninstall setting below them, saved from the header; `tab=data-management` opens it. With the export switched off by the white-label config the uninstall setting is a page of its own under the same link.
    - **About:** the plugin's card from the white-label config (`tools.about`) and a System card (plugin version, plan, WordPress, PHP, environment, multilingual) to copy into a support request; the admin gets the WordPress and PHP versions for it.
- **No interim page.** Every section of the chatbot settings has a page now, so the page and its note are gone; `tab=chatbot-settings` opens Behaviour, and a setting the admin assistant previews opens the page that holds it. An add-on's section left there would bring the page back as "More settings". A section that joins a page which is missing (a hidden feature) stays on its schema page instead of making an untitled one.
- **Every setting has a place:** a Jest test (`reachability.test.js`) opens every visible field of the real schema, the premium white label file included, through `resolveMovedRoute` and the Connections routes, and checks that the navigation lists the page that holds it. The schema's shape is a fixture (`tests/js/admin/app/adminSchema.json`) that a PHPUnit test compares with the config files, so a moved or added setting fails until the fixture is written again.
- **Labels** of the moved sections, pages and fields are in sentence case (owner, 2026-11-15: Consent text, Blocked words, Blocked IP addresses, Message feedback, Session feedback), and the Privacy page's descriptions say "conversations" for persisted chatbot sessions. The admin assistant still finds the consent settings by their GDPR names (aliases in `SettingsCatalog`).
- **MCP server** uses the content width of the other settings pages, and its tokens' dates read as in the other app tables (`formatDateTime`).
- **Not built, for now:**
    - charts per day on the Overview, Conversions and Usage pages, and the trend sparklines of the prototype's tiles: no route returns a daily series for conversations, orders or tokens; the token usage is read with `wp kimaai usage report`;
    - routes with a daily series for conversations, orders and tokens, for those charts: a possible later item (owner, 2026-11-15: not now);
    - the prototype's log entries table with a level filter: the logs are text files, and the page shows them as files;
    - "Signed" per function tool: the code signature is checked on the server, and the admin does not know whether it is valid;
    - Message feedback and CSAT in the app's own table and side panel: they keep today's list and conversation panel;
    - the date range and the export in the page header: each report keeps its own range, so they sit above the report.

## AD-10: Home (2026-11-15)

- **Home is the app's landing page** (`src/admin/home/`): the first item of the navigation, opened by `?page=kimaai` without a tab, by `tab=home` and by any page the menu does not have (it used to open the first settings page). As the prototype draws it: the greeting with the setup state and "Live on every page" or "Not live yet", "Open your site" and the next step as the main button; four figures; the setup checklist; "Needs your attention"; shortcuts to Appearance, Sources and sync, Leads, Insights and Connections; on a free install the upgrade card.
- **The checklist** (`buildChecklist`) has the wizard's steps and what follows them, each ticked from what the plugin already knows and opening the page that holds its settings:
    - **Connect an AI provider:** an AI environment with its key (Ollama: its endpoint), the Connections status of AD-5; opens Connections on AI environments.
    - **Choose the chat model:** the chatbot's AI environment still exists and a model is set; opens Behaviour.
    - **Teach it your content:** any synced chunk (`kimaaiAdmin.home.contentSynced`: one query that stops at the first uploaded row, Pro only); opens Sources and sync. On a free install it carries the Pro label and counts neither as done nor as left.
    - **Make it look like your site:** the icon, the custom icon, the title, the name, the greeting, or the theme's mode, style, preset or primary colour differs from its default; opens Appearance.
    - **Capture leads:** lead capture is on; opens the Lead form, with its Beta label. Not there while lead capture is hidden.
    - **Go live:** "Show on every page" is on and an AI provider is connected. A chat block or shortcode placed by hand is not counted: finding one means searching every post.
    - A step whose settings the schema does not have is left out, so hidden features stay hidden.
- **Figures** of the last 30 days from routes the admin already has: conversations, answered without a person and escalations (`/insights/overview`, the Insights Overview's query) and leads (`/leads` with `per_page=1`, its total). A figure whose feature is hidden asks no route and shows no tile; a figure whose route fails is left out. Not built: the prototype's trends, sparklines and the conversations chart (no route returns a daily series, as in AD-9), "Live on N pages" (no cheap count of the pages that show the chatbot), and the latest conversations feed.
- **Needs your attention:** the connections with the status "needs attention" (AD-5), with failed lead deliveries (AD-8), each linking to the tab or panel that fixes it.
- **The setup wizard is gone; its links open Home.**
    - Removed: the wizard's React app (`src/admin/wizard/`), its "Setup Wizard" entry in the WordPress menu, `saveSettings` of `useSettings` (only the wizard saved everything at once), `AdminThemeToggle` and `isEmptyValue` (only the wizard used them), `kimaaiAdmin.urls.wizard`, the wizard's Playwright spec, page object and runtime hook.
    - Kept: `page=kimaai-wizard` stays registered, out of the menu, and redirects to Home before any output, with or without `force=1`, completed or not (`Wizard::redirectToHome`). The REST routes `/wizard/config` (with the `kimaai_wizard_config` filter), `/wizard/state`, `/wizard/complete` and `/wizard/reset`, the option `kimaai_wizard_state` and `app/Admin/Wizard/config.php` keep working for anything that reads them; nothing in the plugin does any more.
    - Freemius' first page after the opt-in (`first-path`) is Home; there is still no redirect after activation of our own. About's action is "Open the setup checklist" instead of "Run Setup Wizard".
- **Left for later:** the CSS of the wizard's root and page (`#kimaai-wizard`, `.kimaai_page_kimaai-wizard`, `.kimaai-wizard`, the theme toggle's `.kimaai-theme-toggle`) and `kimaai-wizard` in `useAdminTheme`'s roots, unused now, like `#kimaai-feedback-analytics` since AD-9; the `setup-wizard` entry of the feature registry, which nothing reads; readme.txt still describes the setup wizard (release copy).

## AD-11: Search (2026-11-15)

- **Opening it.** The top bar has a search field with the shortcut (⌘K on Apple devices, Ctrl K elsewhere), an icon below the medium breakpoint; ⌘K or Ctrl+K opens it on every page of the app, the Leads page too. Not from inside a field (an input, a text area, a select or a code editor): there the browser, WordPress or the editor keeps the shortcut. The visitors' Ask AI Ctrl+K is on the site only; the admin loads no chatbot mount.
- **What it finds** (`src/admin/app/search/searchIndex.js`), built when it opens from what the admin shows:
    - every page of the navigation, and each titled tab of a page (Insights' reports, Sources and sync, Logs);
    - every setting with a component and a label, on the page and tab that hold it now (`withSectionPages`), with its section and description; the fields of a list's entries are not settings of the page;
    - on Connections, its two lists, each service (HubSpot, Zendesk …) and a service's settings, which open its panel;
    - on the settings page, a field whose conditions hide it is left out; on the Leads page, where the settings are not loaded, it is in.
- **Hidden features never show:** the schema the admin gets has none (`FeatureSchema`), and a page, tab, section, field or service that still names a hidden feature is left out. Pro settings carry the Pro label on a free install, beta ones the Beta label.
- **Matching:** every word of the query has to be in the title, the section, the page or the description, without case or accents ("begrussung" finds "Begrüßung"). A match at the start of the title ranks first, then at the start of a word, then anywhere in the title, then the section or page, then the description; pages before settings on a tie. The results are grouped by the page that holds them, in the order of their best result. Without a query the dialog lists the pages by navigation group. The labels are searched as the schema has them, already in the admin's language.
- **The dialog** follows the prototype: a combobox with the results as a listbox (arrow keys, Enter, Escape, Tab kept inside), the number of results in a live region, and the keys in its footer. Escape gives the focus back to where it was.
- **Opening a result:** a page or tab opens in place, as from the sidebar (the unsaved-changes question included); a setting then is scrolled to the middle of the screen, its control gets the focus, and it is marked with a soft brand halo that fades (with reduced motion it stays without fading). The collapsed "Advanced settings" part that holds it opens, by the same class check as for the admin assistant's preview, and now stays open after either of them. From the Leads page a result loads the settings page with `&setting=<path>`, which the app reads once and drops from the URL.
- **Not built:**
    - the admin assistant's aliases (`SettingsCatalog`): they live on the server, in English only, and are not in the admin's data, so "GDPR" does not find the consent settings (their labels say "consent");
    - recent searches, and running actions or handing the query to the admin assistant (the "Later" of the Search section);
    - an e2e spec: the Jest tests cover the index, the keyboard and opening a setting on a section page, a tab and a Connections panel.

## AD-12: Multilingual (2026-11-15)

- **What was there:** `SettingsI18n` registers the schema's `translate` strings with WPML (`wpml_register_single_string`, domain `kimaai`) and Polylang (`pll_register_string`, group `KimaAI`), translates them on every read of the option (`option_<name>` filter) and keeps the default-language values when the admin saves in another language. `wpml-config.xml` lists the same strings as admin-texts. Lists were skipped, and the admin showed only a notice on locked fields outside the default language.
- **The language in the top bar:** on a site with WPML or Polylang, "Editing Deutsch · default English" (or "English · default language"), from the language names `Assets.php` now passes (`kimaaiAdmin.i18n.names`). Hidden below the `lg` breakpoint, as in the prototype.
- **A line under every translatable text, on every page:** in the default language "Translated per language in WPML String Translation" (or Polylang's strings translations), linked; in another language the text is read-only and the line says "Edit in English, translate in …". One component (`TranslatableHint` in `FieldWrapper`) for setting rows and stacked fields, so the old info notice above stacked fields is gone. The state comes from `fieldI18nMeta()` (`src/admin/multilingual.js`), for the settings pages and the list entries' side panels and dialogs. A locked text input is now disabled itself, not only covered.
- **List entries are translated per entry:** a list whose entries have `translate` fields is registered entry by entry, each string named after the entry's id (`settings:kimaai_options.chatbot.quickActions.<id>.label`), translated on read and kept in the default language on a save from another language (matched by id; a new entry is saved as written). The stored option keys do not change. A duplicated entry gets a new id and so starts without translations; a deleted entry's strings stay in WPML or Polylang until removed there.
- **Which list fields are translated (visitor-facing):**
    - quick actions: the button label, the message, the prefill text and the command message (sent as the visitor's message);
    - glossary: the approved wording, which the chatbot must use in its answers;
    - pinned answers: the answer.
    - Not translated any more: the glossary notes (guidance for the model, which visitors do not read) and the pinned answer's question and phrasings. Visitors' questions are matched against those, and the matching vectors are cached per text (`PinnedAnswers::entryVectors` drops the cache rows of texts it does not see), so a text per language would drop and re-embed the cache whenever the language changes.
- **The white-label credit in `wpml-config.xml`:** the generator (`npm run i18n:wpml-config`, part of `npm run i18n`) now reads the schema files of its own checkout, free and premium, and only those: the dump skips the installed plugin (`--skip-plugins=kimaai`) and loads the checkout's `kimaai.php`. So the file no longer depends on the site's licence, a local premium switch or add-ons, and `whiteLabel.footerCredit.text` is in it. The free plugin's file names the premium key too; WPML and Polylang ignore a key that is not stored. The release zips did not ship `wpml-config.xml` at all; they do now (`scripts/zip-utils.mjs`, `scripts/make-premium-zip.mjs`).
- **Covered by stubs only:** no WPML or Polylang install was available. The registration, the translated reads and the protected saves are PHPUnit tests with WPML's hooks and Polylang's functions stubbed (`tests/unit/Admin/SettingsI18nTest.php`, `tests/unit/Fixtures/polylang.php`); the indicator and the lock are Jest tests and stories (`Admin/Multilingual`). Not checked against the real plugins: how String Translation and Polylang's strings page list the per-entry strings, the links into them, and the language names WPML and Polylang return.

## AD-13: Secrets (2026-11-15)

- **What is a secret:** every setting marked `isSensitive` in the schema, the same flag the export already used. Today these are 10 fields in 8 places: the API key of each AI environment and each vector database, the Zendesk, Freshdesk and Help Scout keys in the chatbot settings, the lead webhook's signing secret, and the HubSpot, Brevo, Mailchimp and Pipedrive keys. A new secret field only needs the flag. No option key or stored format changed, and nothing migrates.
- **The browser only learns whether one is set** (`app/Admin/SettingsSecrets.php`). `/wp/v2/settings` answers with `kimaai:secret:saved` for a stored secret and an empty string for none, in every option and in every entry of a list (filter `rest_pre_get_setting`, so the answer to a save is masked too). The admin has the same two values in `src/admin/utils/secrets.js`; a Jest test checks that they match the PHP constants. Everything on the server (providers, connection tests, lead destinations, helpdesks, WP-CLI) reads the options as stored.
- **Saving** through `/wp/v2/settings` (filter `rest_dispatch_request`, after the permission check and the schema validation; only this route and only writes):
    - `saved` or an empty value keeps the stored secret;
    - `kimaai:secret:clear` removes it;
    - anything else replaces it.
- **Only the browser's saves** follow these rules. A server-side write (migrations, the assistant's rollback) still stores what it is given, so "empty" means empty there. The settings import uses the same rules, so an export with its secrets blanked still keeps the stored ones.
- **Lists** (AI environments, vector databases): an entry takes the stored secret of the stored entry with the same id. Moving, deleting and editing entries keep each entry's own key. An entry the server does not know (new, duplicated, or without an id) gets none, so the marker is never stored.
- **Duplicate** copies an environment without its key; the key is entered again. A copy made on the server would need a "copy the key of entry X" instruction from the browser, which adds a new way to move a key for little use: two environments with the same provider and key are rarely what anyone needs.
- **Connection tests** of a saved environment send its id. The server tests with the stored key only while the provider and the endpoint (AI) or the host (vector database) are the ones it was saved with. A test against another address asks for the key again, so the test endpoint cannot be used to send a stored key somewhere else.
- **Export:** the secrets are always blanked. The "Include sensitive data" option is gone, because it sent every key to the browser. An import on the same site keeps the stored keys; on another site they are entered again. A full copy of a site with its keys is a database copy, as for any other plugin.
- **The admin assistant and the MCP server** no longer see secrets. `SettingsCatalog` leaves them out, so they are neither sent to the model with the current values nor listed by the MCP tool `get_settings`, and a change to one is refused: the key is entered on its settings page. Before this, the CRM and helpdesk keys were catalog entries with their current values, which the assistant's model-based resolver sends to the AI provider when it runs. The assistant's vector database setup keeps its own secure form.
- **UI** (`TextField`, password type): a stored key shows as "Saved" with Replace and Remove. Replace opens an empty input, and left empty it keeps the stored key ("Keep the saved key" goes back). Remove shows "Removed when you save" with Undo. A required key that is to be removed counts as missing. The Connections panel uses the same field, and its own copy of this logic is gone.
- **Not changed:** the rollback ledger of the admin assistant still keeps the values it wrote (the vector database key of its setup flow) in the database; it never sends them to the browser. A stored key is not tied to its address when saving: changing a webhook URL, a helpdesk domain or a vector host keeps the key. That is a possible later item.

## AD: real WordPress pass (2026-11-15)

Every page of the app in WordPress Playground, as the Sources and sync fix was looked at: the e2e blueprint without networking, auto-login, Pro forced by the e2e option, the fake embedding and vector services, a fake chat provider, and neutral sample data (an AI environment with a fake key, three pages, three conversations through the chatbot route, three leads, two quick actions, a glossary term, a pinned answer, a Qdrant entry on a closed port). Free and Pro, light and dark, at 1440 px; Persian RTL for a sample of pages. WordPress 7.1.4 (the latest Playground has) and 6.7.2: the Playground CLI's SQLite driver installs WordPress 6.6.2 without tables, so the plugin's minimum could not be run here; 6.7 is the oldest that ran. Between the two: 6.7 has no ⌘K palette in the admin and forms.css has no 25rem select cap; the app looked the same. Storybook had looked right; real wp-admin did not, in these places:

- **WordPress's CSS over the app.** `.wp-core-ui select` (40 px, its padding, grey when disabled) beat the number slider's unit (`.kimaai-unit-select`), so the number showed "2(" and on a free install `input:disabled` took the slider's track away. The Leads page (its own WordPress page) kept WordPress's grey under the content, in dark mode too; `#wpwrap:has(.kimaai-app)` now has the app's background on every page of the app.
- **Layout at 1440 px.** The WordPress menu takes 160 px that Storybook does not have:
    - page actions (Reset, Save) wrapped under a long description (Pinned answers, Quality, White label) and now stay beside it;
    - the floating save bar covered the app's sticky top bar (breadcrumb, search) and now sits below it;
    - WordPress caps a dialog at 70 % of the screen's height, which cut the glossary dialog's buttons off, so a dialog's buttons now stay at its bottom while the fields scroll.
- **⌘K.** WordPress 6.9 and later open their own command palette on ⌘K in the whole admin, from a keydown listener on the document that steps back when the event's default is prevented. On the app's pages it opened instead of the app's search. The app's listener now runs in the capture phase, so on its pages the app's search opens and core's palette stays shut; the other admin pages do not load the app, and core's palette works there as before. In a field the key is still left alone (AD-11), so core's palette can open from a text field on the app's pages. Chosen over offering core's palette the app's pages as commands, which keeps two searches for the same pages.
- **The empty vector database entry.** Every repeatable list of the defaults starts with one empty item (`buildDefaults`), and a new install stores the vector database list as one entry with only its id. Connections showed it as a nameless Pinecone row that "has no key yet" (needs attention, on Home too), Sources and sync preselected it and asked the posts and collections routes for `provider-not-set-…` (400 errors, log entries), and `Config::defaultEnvId()` took it as the default vector database before a real one added after it. An entry without a name and without a key now counts as none: Connections leaves it out of the status, the count and the table (and keeps it when the list saves), `Helper::getEmbedEnvsOptions()` does not offer it (Sources and sync, the chatbot's vector database select) and `defaultEnvId()` skips it. The stored defaults are unchanged: sites that have the entry keep it, so the rule is needed anyway, and dropping the seed item from `buildDefaults` would touch all seven lists (see below).
- **Other bugs:**
    - Home never ticked "Choose the chat model": the check compared an environment's id with the stored `{provider}-{id}`; the fixtures had used an id that happened to be the slug.
    - The Leads page was blank on a site whose menu title is not "KimaAI" (the Persian translation, or a white label's name): its admin screen's hook starts with that title, and `Assets` only knew `kimaai_page_kimaai-leads`. It now asks WordPress (`get_plugin_page_hookname`).
    - Old setup wizard links showed "Sorry, you are not allowed to access this page.": a page removed from the menu is refused before `admin_init`, where its redirect to Home runs. It is now a page without a parent, opened but not listed.
    - A free install asked Pro routes on Sources and sync and the MCP server page (404s in the console, a "no route" error under the upgrade panel).
    - The AI environment and vector database selects showed the stored slug ("openai - Main OpenAI - realwpopenai"); they now read "Main OpenAI (OpenAI)".
- **Checked and fine:** the WordPress menu under KimaAI (KimaAI, Insights, Leads, Contact Us, Add-Ons, Upgrade; no Setup Wizard), Insights opening the app and staying current; WordPress notices, the update nag included, stay out of the app; no console errors or failed requests on any page except a Qdrant on a closed port; the settings REST response and the page carry no stored key, only `kimaai:secret:saved`; on Connections a rename keeps the stored key, Replace stores the new one, Remove on a required key asks for a key (AD-13), a CRM token saves; the side panel, the unsaved-changes dialog, the search and its highlight; dark mode; RTL once core's RTL styles load.
- **Left, for the owner:**
    - the other lists keep their empty seed row on a new install: content templates, quality cases and function tools (and quick actions, glossary and pinned answers until something is saved) show a nameless row that is "On";
    - on the wide pages beside the preview (Appearance, Behaviour, Lead form) the settings column is narrower than its 42rem breakpoint at 1440 px with the WordPress menu, so their setting rows stack, unlike in Storybook;
    - the brand colours have large gaps between them;
    - "Answered without a person" is cut off in Home's tile;
    - "Meeting booking" is cut off in the sidebar next to its two labels;
    - the e2e fixtures pass `wp` and `php` to `runCLI` with a blueprint file, whose preferred versions win, so `KIMAAI_E2E_WP` and `KIMAAI_E2E_PHP` seem not to take effect (here 6.6 ran as 7.1.4 until the versions went into the blueprint); not checked against an e2e run;
    - two changed strings (the lead retention note, "Add function") fall back to English in German and Persian until the translations are updated.

### Follow-ups (2026-11-15)

The points left above, decided by the lead and looked at again in Playground at 1440 px with the WordPress menu (WordPress 7.1.4 and PHP 8.3; Appearance, Home and the search also on 6.6.11 and PHP 8.0), Pro and free:

- **Empty list entries.** All eight lists already existed in 1.5.13, seven of them seeded with one empty entry (the AI environments have an explicit empty default). `buildDefaults` now starts every list empty, so a new install stores no such entry, and an emptied list is no longer filled with one again by the schema upgrade. Sites from 1.5.13 can have it stored, so the vector database rule is now one rule for all lists: `isEmptyListEntry` (src/admin/helpers.js) counts an entry as none when none of the fields a person types into it is filled in (vector database: name and key; content template: post type and template; glossary: term, wording and notes; pinned answer: question, answer and phrasings; quality case: id, turns and checks; quick action: label and its texts; function: name and description). Every list leaves such an entry out and keeps it when it saves. On the PHP side the vector database keeps `Helper::isEmptyEmbedEnv`: the other lists' readers (the glossary block, pinned answers, the quality runs, quick actions, function tools, content templates, the function select) already skip an entry without its name or content, the settings catalog of the assistant and the MCP server does not list repeatable entries, and the assistant's and the MCP server's writers append to an empty list. In Playground a fresh install whose first save went through the app stored no empty entry before the change either; the nameless rows came from defaults stored whole (the e2e and WP-CLI helpers store `buildDefaults`, as the sample data above did) and from 1.5.13 data, reproduced here by storing `[{id}]` in each list.
- **⌘K in a text field** opens the app's search, as in Linear or GitHub, also from the code editor of a function (WordPress's CodeMirror types into a text field; not looked at in the browser). Rich text keeps the key (a link), and Ctrl+K in a field on Apple devices keeps deleting to the end of the line.
- **Setting rows.** The settings column beside the preview is 570 px wide at 1440 px with the WordPress menu (the card's content 530 px). The rows follow the card's width with a container query, as before, but from 28rem (448 px) instead of 42rem: between the two the control takes half the row, from 42rem 20rem as before. Appearance, Behaviour and Lead form have their rows side by side; wide controls (the greeting, the instructions) stay under their label; the preview keeps its column.
- **Cut-off labels.** A navigation title wraps beside its labels ("Meeting booking" with Beta and Pro on a free install), and a tile's label wraps to a second line in a label row of two lines' height, so the values of a row stay level (Home, Insights). No label changed.
- **Brand colours.** The colour field lost its own 40 px bottom margin and its heading WordPress's top margin; the four brand colours sit in two columns from a 28rem card.
- **E2E versions.** Confirmed: runCLI resolves a blueprint path to a bundle and then uses the blueprint's own versions, and the e2e blueprint names none, so every e2e run had the latest WordPress and Playground's default PHP whatever `KIMAAI_E2E_WP` and `KIMAAI_E2E_PHP` said (a run with the old fixtures and 6.8/8.0 ran 7.1.4 and 8.5.10). The fixtures now pass the blueprint as an object with the versions in it; checked by starting the Playground as the fixtures do: the defaults run 6.8.12 and PHP 8.0.30, `KIMAAI_E2E_WP=6.6` runs 6.6.11 with all tables and the plugin active. So the next e2e run is on WordPress 6.8, not the latest. The 6.6 failure above was the cached 6.6.2; 6.6.11 installs and runs the app (no ⌘K palette in core there, the app's search opens).

## AD-14: Conversations (2026-11-15)

Owner's feedback: the conversation list and the transcript did not look premium, an answer's details were still the 1.5.13 debugger, and the search icon sat off the middle of its field. Looked at in WordPress Playground at 1440 and 1920 px with the WordPress menu (WordPress 7.1.4 and 6.8.12, PHP 8.3, Pro forced, invented sample conversations), light and dark, and in Storybook (light, dark, right to left, empty, answer details).

- **An inbox.** Conversations is one frame of two panes that fill the screen below the page header, each scrolling on its own, and the page uses the app's full width (`wide` in `navigation.js`). Below `lg` the panes stack.
    - **The list:** the search, filters by what a conversation led to (All, Leads, Handoffs, Feedback; only when the route reports those facts), a "select all shown" box with the count, and the conversations grouped under Today, Yesterday and the date. A row has the first question as its title, the time, the visitor and the page, the number of questions and its labels: Lead, Handed off, thumbs down and up with their counts, the CSAT rating. The visitor's mark turns into the row's checkbox on hover, on focus and while conversations are selected; the selection bar has "Delete (n)" and a clear button. The open row has a brand bar on its start side. Arrow keys move through the list and open the conversation. Loading shows placeholder rows; a search that finds nothing offers "Show all".
    - **The conversation:** the visitor and the time span with the labels and Delete, a strip of facts (questions, model, tokens, the page as a link), then the transcript: a line per day, the visitor's bubbles on the end side with their time, the chatbot's answers on the start side with its mark, name and time, the cited sources as small links under the answer, and the answer's actions: Details, copy, its tokens, and the visitor's rating with their comment.
- **Answer details** open in the app's side panel (Conversations and the Insights feedback views): the question; problems the provider reported, in words; the sources as a numbered list with title, link, type and heading path, excerpt, and Cited or Related; the model and usage (provider, model, the snapshot that answered, AI environment, status; input tokens with the cached part, output tokens with the reasoning part, total, figures aligned on the end side); the tool calls with their round and status, arguments and result behind a disclosure; and "Technical details", closed: ids and settings, the raw request and response as text with copy buttons. `ChatbotConversationDebugger` (the WordPress panels and CodeMirror) is gone; what it read is in `src/admin/components/conversation/answer.js`.
- **The shared view.** `ChatbotConversationPanel` keeps its props and the "Focused feedback message" mark, and now draws the same transcript in the app's card and dialog, with answer details in the side panel. The 1.5.13 labels USER, ASSISTANT and "Debugger Panel — Row id" are gone. The focused answer is brought into view by scrolling only the panel's own message list (to its middle), not with `scrollIntoView`, which also scrolled the side panel and the page that hold the panel (AD-17). `Bubble` is still exported from `ChatbotHistory` for the Leads panel.
- **The search icon.** In Playground the icon was geometrically centred (measured: 0 px off), so the drift the owner saw comes from styles that sit outside the cascade layers: forms.css gives the field `line-height: 2` and `margin: 0 1px`, and the field was an inline box in a block wrapper whose line box can be taller than the field; another plugin's `svg` or `input` rules (the owner's site runs WordPress 6.9.4 with several plugins) win over the utility classes the same way. The kit's new `SearchInput` (`src/admin/app/ui/`) makes the field a block in a flex box of its own height, centres the icon on that box by its own margins (`.kimaai-search-icon`, unlayered), and adds a clear button in place of the browser's. Conversations and Leads use it. Sources and sync and Query keep their own markup, with the same class, and get the block field from `index.css` too.
- **Data the page needed** (`ConversationFacts`, added to `/chatbot/sessions` and `/chatbot/session/<id>`): each conversation's page title and link (the page's "Page" fact always showed a dash: the route never had it), the logged-in visitor's display name, `escalated` from the Insights session table, `lead` from the leads table (any lead that was not declined), the thumbs up and down and the CSAT rating from the feedback tables, and each answer's rating with its comment. One query per table over the whole table, as the route already lists every conversation. A fact whose feature is hidden (`insights`, `lead-capture`, `feedback`) is neither asked nor sent, so its label and filter do not show. The constructor's new argument has a default, so a cached container keeps working.
- **WordPress's `.hidden`:** common.css hides `.hidden` outside the cascade layers, so `hidden sm:flex` never showed in wp-admin; the header's labels use `max-sm:hidden`.
- **Not built:**
    - cost per conversation or answer: the history stores tokens, no price;
    - timing per answer: the stored response has its start but no end, so no duration;
    - tokens per conversation in the list: they are inside each row's JSON, and summing them for every conversation would parse the whole history on each load;
    - a link from the Lead label to the lead: the Leads page cannot filter by conversation;
    - paging on the server: the route still returns every conversation, the list shows 30 at a time;
    - `useChatHistory` (`/chatbot/all`) is unused since AD-6 and left in place.
- **Left:** WordPress notices in dark mode show their text in a dark colour on the dark card (seen on the "needs an AI provider API key" notice; `WpNotices`, not this page). WordPress 6.9.4, the owner's version, was not available offline in Playground; 7.1.4 and 6.8.12 were checked.

## AD-15: Logs and checkboxes (2026-11-15)

Owner, 2026-11-15: the Logs page needs more styling and a better way to show the log list; the checkboxes still have WordPress's blue tick. Looked at in WordPress Playground (7.1.4, PHP 8.3, the e2e blueprint without networking, Pro forced, WordPress menu expanded) at 1440 px, light and dark, with invented log files of every level, and in Storybook.

- **The log format.** `app/Logger.php` writes one line per entry, newlines removed: `2026-11-15 10:42:07 [ERROR] [Class->method()] message @ path/file.php:74`, the time in UTC (`gmdate`), the levels DEBUG, INFO, NOTICE, WARN and ERROR. Read in the browser (`src/admin/logs/parseLog.js`): the format is fixed and single-line, so no structured output on the server is needed. The older `[time] LEVEL message` form (the wporg screenshot fixtures) is read too; any other line belongs to the entry above it.
- **The viewer** (`src/admin/logs/LogEntries.jsx`), as Vercel's and Datadog's log lists: newest first, one row per entry with the level as a coloured label (Error, Warning, Notice, Info, Debug; the text carries the meaning), the time in a fixed-width column in the browser's time zone, the message on one line in Geist Mono; error rows tinted, error and warning rows with a coloured start edge. A row opens its details: the whole message, a JSON body at its end pretty-printed, the source (`Class->method()`), the file and line, the time with its UTC value, and "Copy entry". Above the rows a search (message, source, file; matches marked) and the levels as a segmented control with their counts (notices count as Info). 200 rows at first and "Show more", since a 5 MB file has tens of thousands of entries.
- **The files** are a list beside the viewer: the day, the file name, the time, the size and, for the open file, its entry count (the server does not count the entries of the others: that would read every file on each list). Active marks the file being written. Clear all and Delete all sit in the list's ⋯ menu, Delete for the open file in the viewer's header; each asks first in the app's confirm dialog. Refresh, full screen, Copy and Download stay; the CodeMirror view, its "Wrap lines" checkbox and the File details card are gone (their path is the viewer's footer, their status the Active label).
- **States:** placeholders while loading; no files ("No log files yet", with a link to the log settings); an empty file; no match (with "Clear the filters"); an error with "Try again".
- **Checkboxes.** In wp-admin `forms.css` draws its own box on every checkbox and radio, a blue tick or dot in `::before` and a blue focus square (`#2271b1`), from rules outside the cascade layers. The app's `.kimaai-checkbox` (AD-6) kept the browser's own box with the brand as `accent-color`, so after a click the row checkboxes of Leads, Conversations and Sources and sync showed WordPress's blue square, and in dark mode CheckboxControl and RadioControl were white boxes. Now one style in `src/admin/index.css` (its own commented block at the end) draws the box itself (`appearance: none`): 16 px, 4 px radius (round for a radio), the input border, the brand fill with a white tick, dash or dot as background images (Firefox draws no `::before` on an input), the focus ring on keyboard focus only, half opacity when disabled. It applies to the app's own checkboxes, CheckboxControl (DataViews' row selection too) and RadioControl inside the app's roots (preflight.css's list); `:is()` gives the roots an id's weight, so it wins over forms.css and `@wordpress/components`. The AD-6 rule and the CodeMirror log colours in `wpAdmin.css` are gone. The Storybook page "Admin/Checkboxes and radios" loads forms.css's checkbox and radio rules to show the style winning over them.
- **WordPress's `.hidden`.** `common.css` has `.hidden { display: none }` outside the cascade layers, so Tailwind's `hidden md:inline-flex` never shows in wp-admin. That hid the viewer's time column, and the top bar's search button at every width (it shows in Storybook); both use `max-*:hidden` now. `BulkEntityList.jsx` (Sources and sync's bulk modal) has the same pattern and is left to that page.
- **Not built:** the entry count of the files that are not open; a live tail; filters by source or time range.

## AD-16: Sources and sync at a glance (2026-11-15)

Owner, 2026-11-15: the Health tab shows too much in too many ways and is confusing even for a technical user. The page now answers one question: is the knowledge base working, and if not, what do I do?

### What the page showed before

One health check (`/embeddings/health`, one test embedding) fed three places: the four tiles above every tab, the Sync tab's note, and the Health tab (a figures card, five group tables of twelve raw checks, a "Local details" card).

| Fact                                                  | Where it showed                                                                                 | Needed?                               | Leads to                                |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------- |
| Overall state (healthy, warning, unhealthy)           | tile "Index health", the Health card's pill, the Sync note (three wordings)                     | yes, once                             | nothing; no reason was given            |
| Synced items and their chunks                         | tile, Health figure "WordPress sources", "Local chunks", count drift details                    | yes, as "of how many"                 | Sync tab when nothing is synced         |
| Vectors in the vector database                        | tile, Health figure, count drift details, "Remote index data" details (four times)              | only when it differs                  | reconcile or sync again                 |
| Count difference                                      | Health figure, count drift check                                                                | only when not 0                       | as above                                |
| Changed since the last sync                           | tile, Health figure "Newer sources", local freshness details (also counted failed items)        | yes                                   | Sync tab                                |
| Embedding and index dimensions                        | two Health figures, the probe's details, the target's details, the dimension check (five times) | only when they differ                 | Connections (model) or a new collection |
| Last sync                                             | tile hint, "Local details" (raw), never as a check                                              | yes                                   | none                                    |
| Chunk states, queue counts                            | "Local details", local freshness details, queue state details                                   | details only                          | the logs when jobs failed               |
| Recent errors                                         | "Local details" list, recent errors check (printed as `[object Object]`)                        | yes, behind the failed items          | sync again                              |
| Target (environment, provider, collection, model)     | the Health card's description, tile hint                                                        | the provider and model in plain words | Connections                             |
| Saved configuration, local tables, Action Scheduler   | a pass row each                                                                                 | only when they fail                   | Connections; reactivating; the logs     |
| Links (vector databases, AI environments, Sync, Logs) | a row of links under "Local details"                                                            | per problem, where it is fixed        |                                         |

### The design

- **One verdict for the whole page** (`src/admin/knowledge/SourcesSummary.jsx`), in the vector database card under its selector: Healthy, Needs attention or Not working, with the reason in one sentence, the count of other problems, when it was checked, "Check again" on Sync and Health, and "See the checks" on the other tabs. It replaces the four tiles and the Sync tab's notes. On Sync a verdict of Not working adds "Sync is off until this is fixed." The verdict follows the same rule as the sync button (`syncBlocked`: a blocking check failed), so the two cannot disagree.
- **Health is a list of seven checks** (`HealthPanel.jsx`), one row each: a state icon (passed, needs attention, not working, not checked; the words for screen readers), the check's name, what it found in a sentence, and when it is not ok the fix in a line and a button to where it is made: Connections (vector databases or AI environments), or the Sync, Collections or Settings tab, which open in place through the app's router. "Details" opens the raw figures (technical values in Geist Mono, left to right in RTL) and what the service answered. The checks: vector database (settings, then the connection), embedding model (the test embedding), collection (exists, ready, fits the embeddings' dimensions), synced content (synced of published items; a vector database holding more or fewer chunks than KimaAI synced), failed items (with their latest errors), changed content, last sync (with running or failed background jobs).
- **Each fact lives in one place.** The verdict holds no figures; each figure is in one check's sentence or details; the target's parts are in the checks that use them. `src/admin/knowledge/healthReport.js` reads the endpoint's checks and metrics into the rows and the verdict; it is the only place that knows the raw shape.
- **Which problem is the reason:** what stops the knowledge base first (a failed blocking check), then nothing synced, failed items, changed content, background jobs, and last a count that differs. Running background jobs are not a problem (the endpoint warns about them); everything else follows the endpoint's states.
- **The cost rule of AD-7 stays:** the check runs once per vector database on Sync or Health and is shared; Query, Collections and Settings show the verdict of a check already made and run none; "Check again" is offered only where checks run. Checked in Playground: switching from Health to Sync and back through a fix button makes no new request and no reload. The "Connect a vector database" step and the free upgrade panel are unchanged.

### The endpoint

`EmbeddingDiagnostics` adds three local figures (`metrics`): `eligible_sources` (published items of the supported post types and the PDFs, as the Sync tab lists them per source), `failed_sources` (items with a failed chunk) and `changed_sources` (synced items whose post changed after their sync). `newer_source_count` also counted failed and unfinished items, so the old page showed one failed item as "changed" too; it stays for anything else that reads it, as do all other fields (the WP-CLI command reads `overall_status`, the MCP coverage tool passes the report through). A source added through `kimaai_embedding_supported_sources` with its own `query_args` is counted without them. PHPUnit covers the three queries with FakeWpdb.

### Checked

WordPress Playground (WordPress 7.1.4, PHP 8.3, Pro forced, the fake embedding client, a fake Qdrant on a local port answering the health, collection and count calls, twelve sample pages and posts with synced chunks), 1440 px with the WordPress menu, light and dark, free and Pro: healthy, needs attention (a failed chunk, two changed posts, two chunks more in Qdrant), not working (Qdrant answering 503), no vector database, free. Storybook: the same in light, dark and RTL. Screenshots in `scratchpad/shots-ad16/` (before, after, storybook).

- **Also fixed:** the bulk sync dialog's column headings never showed in wp-admin (`hidden md:grid`; WordPress's `.hidden` wins), now `max-md:hidden`.
- **Left:**
    - the sync dialog itself still has the pre-redesign look (grey Tailwind classes, its own table);
    - "Open Sync" for changed or failed items opens the Sync tab, which cannot filter by them yet: a "changed" and "failed" filter on the Sync table, or a fix button that opens the sync dialog with exactly those items (the endpoint would return their ids), is a possible next step.

## AD-17: Insights feedback (2026-11-15)

Owner, 2026-11-15: the Feedback tab had a second layer of tabs (Overview, Message feedback, CSAT) under the sidebar and the Insights tabs, and it did not feel premium; the CSAT part and the conversation behind a rating needed work. One layer of tabs per page, like the Overview.

- **One page, no inner tabs.** The Feedback tab (`src/admin/feedback/`) is one report under the range select, like the Overview:
    - four figure tiles: helpful answers (the rate, helpful and not helpful counts, a line of the rate so far), answer ratings, the CSAT score out of 5 (the share of 4 and 5, a line of the weekly average), CSAT answers;
    - "Answer ratings per day": a bar per day of the range, helpful and not helpful stacked, the days without ratings included; Chart.js as before (`ChartCard`), now in the app's colours and font read from the tokens, so it follows dark mode, and mirrored in RTL;
    - "CSAT scores": the five scores as meters with count and share, as the Overview's "How they end";
    - "Ratings and comments": every answer rating and CSAT answer of the range in the app's table, newest first. A row shows the rating (Helpful, Not helpful, or "2 of 5"), the visitor's comment, the rated answer or the conversation's first question under it, the page, Resolved and a note mark, the date and the ⋯ menu (open, mark as resolved or open again, delete). Filters: type (all, answer ratings, CSAT answers), rating (for both: positive, neutral, negative; for answers: helpful, not helpful; for CSAT: the score), "With a comment", a search in comments and notes; pages of 25; bulk delete.
    - Free installs see the upgrade card of the other Pro tabs. Without ratings in the range the tab says what fills it and links to the feedback settings; with both ratings switched off it says so.
- **The rating in the side panel** (720 px, `SidePanel` got a `wide` prop): the rating, the comment, page, model and date; the admins' note (Save note) and Mark as resolved or Open again in the footer (the same `admin-meta` route, now with the kit's text area instead of WordPress's toggle and textarea); then the conversation in the shared `ChatbotConversationPanel` with the rated answer highlighted and its rating under it. The note sits above the conversation, so it is in view without scrolling.
- **Old links:** `AdminInit::insightsUrl` is unchanged; `view=message-feedback` opens the list on answer ratings, `view=csat` on CSAT answers, `view=overview` unfiltered. The tab reads `view` once and drops it from the URL.
- **One list route** (`GET /kimaai/v1/feedback/analytics/items`, `manage_options`): both tables in one `UNION ALL` with the admin notes joined, so filters, the search and the pages work across both; per item the kind, rating or score, comment, the visitor's question, the answer (the stored final message), page, model and the note. The other feedback routes stay as they were. Checked in Playground's SQLite and by PHPUnit; not run against MySQL here.
- **Gone from the tab:** the segmented control, DataViews and WordPress's Notice, the "Most downvoted answers" and "Top 5 posts/pages by negative rate" tables (the list filtered to not helpful shows the answers, with their page), the incident's JSON export, and the old pages, `AdminNotesSidebar`, `FeedbackSummaryCard`, `ScorePill` and `utils.js`. The `incident` route is kept for anything that calls it.
- **Found on the way, not changed:** in Playground (SQLite) the CSAT average per week is empty, because `YEARWEEK()` does not exist there; the CSAT tile has no line then. The overview route names only the pages of downvoted answers (`getPostTitles` is fed from those), which the removed top pages table showed as "#5".
- **For AD-14 (the shared conversation panel):** it scrolls the focused message into view with `scrollIntoView`, which scrolls every box around it, the side panel and the page behind too. The Feedback panel puts its own content back to the top and the page back on close, and its frame clips (`overflow: clip`); scrolling only the panel's own list would make that unnecessary. The panel's "Focused feedback message" label, the USER and ASSISTANT labels and the "Debugger Panel — Row id" bars are its own.
