# FS: feature status and Beta labels

Track FS (owner decision, 2026-11-14). `development` is far ahead of `master` (1.5.13). The tracks were built on top of each other and migrations only run forward, so features cannot be released one at a time through git. Instead, every feature gets a status in the code:

- **hidden:** switched off and invisible;
- **beta:** working, and labelled "Beta" in the admin;
- **stable:** no label.

All code goes to `master`, and each release moves the features the owner chooses.

## Decisions taken in this research (owner delegated, my recommendation, 2026-11-14)

- **What counts as a feature.** The registry lists what a site owner switches on or meets in the admin. Changes that improve an existing feature and have no setting of their own ship with that feature: the code copy button, the page section sent with the question, and section anchors in source links. Each section below names the feature it belongs to.
- **Compliance and protection are never hidden.**
    - The AI disclosure notice, the "Powered by" opt-in and PII masking are not registered as beta. They are part of the stable chatbot.
    - Hiding them would switch off a legal notice or a protection.
    - The same applies to the export, erase and retention of lead and insight data, and to the access filter on members-only content. They keep running while their feature is hidden, so data stored earlier stays exportable, erasable and filtered.
- **Features that need each other are merged.**
    - The Leads page, lead privacy and lead retention cannot work without the lead form, so the three are one feature: `lead-capture`.
    - "Ask for details before handing over" is an option of `lead-capture` that also needs `visitor-handoff`.
- **The hard-coded "Beta" pill in the admin assistant** (`AdminAssistantShell.jsx`) goes. The admin assistant shipped in 1.5.13, so it is stable. Its label now comes from the registry like every other feature's.
- **`since`.**
    - For new features it stays empty until the release that first shows them. The release-pr skill fills it in.
    - The 1.5.13 features have no `since`: the registry starts with them.

## The registry

`app/Features/Features.php` is a static class, so the settings config files, block registration and services can all ask it directly. It holds one map, `id => [status, title, tier, since]`.

| Method                     | Returns                                                      |
| -------------------------- | ------------------------------------------------------------ |
| `Features::status($id)`    | `hidden`, `beta` or `stable`                                 |
| `Features::isEnabled($id)` | Not hidden                                                   |
| `Features::isBeta($id)`    | Beta                                                         |
| `Features::forAdmin()`     | The statuses passed to the admin JS (`kimaaiAdmin.features`) |

How a status is worked out:

1. Start from the map.
2. `KIMAAI_FEATURES_PREVIEW` set to true in `wp-config.php` turns hidden into beta. The e2e (Playground) and WP-CLI test setups define it, so hidden features stay tested. It is not documented for customers.
3. The `kimaai_feature_status` filter runs last, for tests and development.
4. An unknown id is a programming error. It reports `_doing_it_wrong()` and counts as stable. A unit test fails when a `feature` key in a config file or a `Features::` call names an id that is not registered.

## Where a status takes effect

| Surface                                                                            | Hidden                                                                                                                                    | Beta                                                                      |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Settings schema: page, sub-tab, section, field, select option with a `feature` key | Removed from what the admin sees: the localised `schemaSettings` and REST `/settings-schema` (`FeatureSchema::filter()`)                  | "Beta" badge in the menu, page header, sub-tab, section heading or field  |
| Stored settings                                                                    | Kept. `Settings::getSchema()` stays complete: `register()` prunes stored values whose keys leave the schema, and export and import use it |                                                                           |
| Admin assistant and MCP settings tools                                             | The `SettingsCatalog` walk skips hidden nodes, so they cannot be read, changed or rolled back                                             |                                                                           |
| Admin pages and tabs (Leads, Insights tabs)                                        | Not registered, or not shown                                                                                                              | Badge on the page title or tab                                            |
| Blocks                                                                             | Not registered (the editor script is not loaded either)                                                                                   | The title gets " (Beta)" in the inserter (`block_type_metadata_settings`) |
| Shortcode modes, REST routes, AI tools, renderables, cron jobs, hooks              | The feature's class returns early before registering them                                                                                 |                                                                           |
| Chatbot widget                                                                     | Nothing new is sent to it                                                                                                                 | Visitors never see a Beta label                                           |
| Migrations                                                                         | Still run, so the migration order stays the same in every release                                                                         |                                                                           |

The gate sits at the choke point named for each feature below. Runtime code keeps reading its own setting, so a hidden feature is off even if its setting was saved as on.

## Features

### New in `development`: beta

| Id                       | Feature                                                                                   | Tier                      | Settings key                                                                      | Gate in the code                                                                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `inline-chat`            | Chat inside the content: the `kimaai/chat` block and `[kimaai_chatbot mode="inline"]`     | free                      | (none)                                                                            | Block registration in `ChatbotAssets::registerBlock()`. The shortcode falls back to the floating chat                                            |
| `ask-ai`                 | Ask AI search and chat modal, block, search form takeover, shortcut                       | free                      | section `askAi`                                                                   | `ChatbotAssets`: block, `get_search_form` and `render_block_core/search` filters, root and shortcut                                              |
| `search-answer`          | AI answer on the search results page, block, REST `/answer`                               | free (premium grounds it) | section `searchAnswer`                                                            | `SearchAnswerBox::register()`, `SearchAnswer` route                                                                                              |
| `answer-sources`         | Source list and related pages under answers                                               | premium                   | field `relatedPagesCount`                                                         | `AnswerQuality` `addSources` hook; without it every client gets the citations in the text again                                                  |
| `taxonomy-scope`         | Answers limited to taxonomy terms, `scope` attribute                                      | premium                   | fields `vectorDbScopeTaxonomies`, `vectorDbScopeFromPage`                         | `RetrievalScope::taxonomies()` returns none; `scope` attributes are ignored                                                                      |
| `members-only-knowledge` | Members-only content in the knowledge base, answered per visitor                          | premium                   | section `membersOnly` (embedding)                                                 | `Embedding::isIndexable()` skips members-only content. The access filter and `vectors backfill-access` keep running                              |
| `customer-tools`         | Logged-in customers ask about orders, subscriptions, memberships, courses                 | premium                   | section `customerCentre`                                                          | `CustomerTools::register()`                                                                                                                      |
| `helpdesk-tickets`       | Handoff opens a ticket in FluentSupport, Zendesk, Freshdesk or Help Scout                 | premium                   | ticket options of `handoffChannel`, fields `zendesk*`, `freshdesk*`, `helpscout*` | `Helpdesk::adapter()` returns null, so email and webhook are used                                                                                |
| `visitor-handoff`        | "Talk to a person" button and the `request_human` tool                                    | premium                   | field `handoffVisitorButton`                                                      | `VisitorHandoff::register()`                                                                                                                     |
| `lead-capture`           | Lead form in the chat, triggers, Leads page, CSV export, notification, privacy, retention | free                      | section `leads`                                                                   | `LeadForm`, `LeadTriggers`, `LeadsAdmin`, `LeadSettings::isEnabled()`, Leads submenu                                                             |
| `lead-crm-sync`          | Leads to a webhook, HubSpot, Brevo, Mailchimp, Pipedrive                                  | premium                   | integration pages `lead-webhook`, `hubspot`, `brevo`, `mailchimp`, `pipedrive`    | `LeadSyncQueue::register()`                                                                                                                      |
| `meeting-booking`        | Calendly or Cal.com booking in the chat                                                   | premium                   | integration page `meeting-booking`                                                | `MeetingBooking::register()`                                                                                                                     |
| `lead-score`             | Lead score in the list and in the CRMs                                                    | premium                   | field `leadHighIntentPages`, the CRMs' `score*` fields                            | `LeadScorer::register()`, score column                                                                                                           |
| `insights`               | Insights overview: conversations and resolution rate                                      | free                      | field `insightsSessionIdleMinutes`                                                | `SessionRecorder`, `SessionOutcomeJob`, `InsightsRoutes`. Hidden: the page keeps its 1.5.13 name, Feedback Analytics, with only the Feedback tab |
| `topics`                 | Questions grouped into topics                                                             | premium                   | fields `topicsEnabled`, `topicsMinSize`                                           | `TopicJob`, `TopicLabelJob`, topics route, tab                                                                                                   |
| `content-gaps`           | Gap report with actions                                                                   | premium                   | field `gapsFirstQuestionOnly`                                                     | Gap routes, tab                                                                                                                                  |
| `conversions`            | Orders, forms, leads and meetings linked to a chat                                        | premium                   | fields `attributionEnabled`, `attributionWindowDays`                              | `OrderAttribution`, `FormAttribution`, conversions route, tab                                                                                    |
| `white-label`            | The site's own footer credit instead of the KimaAI link                                   | premium                   | group `whiteLabel`                                                                | `WhiteLabel::addFooterCredit()`; its settings stay in the schema so a saved credit is kept                                                       |

Dependencies, enforced in the code (a feature counts as hidden when one it needs is hidden):

- `lead-crm-sync`, `meeting-booking` and `lead-score` need `lead-capture`.
- `topics`, `content-gaps` and `conversions` need `insights`.

### In 1.5.13: stable

`chatbot`, `chatbot-appearance`, `attention-popover`, `ai-models`, `content-awareness`, `guardrails`, `privacy-consent`, `chat-history`, `glossary`, `feedback`, `feedback-analytics`, `quick-actions`, `function-tools`, `knowledge-base`, `embeddings`, `ai-environments`, `pinned-answers`, `eval`, `cost-observability`, `human-handoff`, `admin-assistant`, `setup-wizard`, `woocommerce`, `mcp-server`, `export-settings`, `logs`, `data-management`, `multilingual`, `wp-cli`, `admin-theme`.

They carry no `feature` keys, because stable needs no label and none of them can be hidden. They are in the registry so the full list exists in one place. UD later builds its feature pages from it.

## Process (FS-6)

- A new feature enters the registry as hidden, with its `feature` key on its settings and a gate at its choke point.
- The release-pr skill lists every hidden and beta feature and asks the owner, per feature, what it becomes in the release. It then sets the status and `since`, in one commit on the release branch.
- `CONTRIBUTING.md` describes the statuses and the rule.

## Tests

- Unit:
    - the status rules: map, preview constant, filter, unknown id, dependencies;
    - `FeatureSchema::filter()` on pages, sections, fields and options;
    - every `feature` key in the config files is registered.
- Jest:
    - the badge shows for beta and not for stable;
    - `buildMenu()` and the sections pass `feature` through;
    - Insights tabs.
- WP-CLI:
    - a hidden feature's REST route is not registered, its settings are missing from `/settings-schema` and from the assistant catalogue, and its stored value is kept.
    - With `KIMAAI_FEATURES_PREVIEW` it is back.
