<!-- markdownlint-disable MD024 -->

# KimaAI roadmap

This file holds only open work: what waits for the owner, the order of the tracks and each open track. The pull request that merges a track deletes its section; what was done and why is in `git log`, the merged pull requests and `CHANGELOG.md`. How a track is built, reviewed and merged is in `CONTRIBUTING.md`, "Tracks, review and merging".

## Goal

KimaAI is the AI assistant that content-heavy WordPress sites (documentation, knowledge bases, publishers, shops with member areas) install to:

- answer visitors' questions from the site's own content and lead them to the right page or document;
- collect leads in the conversation and hand them to the site's CRM;
- support logged-in customers in their account area (orders, memberships, tickets, handoff to a person).

## Waiting on the owner

| Item    | What is needed                                                                                                                                                          |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BM      | In Freemius: decide whether white-label stays in every premium plan or moves to its own Agency plan, and set its price (`docs/research/BM-business-model.md`, option b) |
| Release | FS and PL are merged: decide per new feature whether it ships as beta or stays hidden, and give the word for the release                                                |

## Next

Order of the tracks (owner, 2026-11-14; VC added 2026-11-15):

1. **Hooks and developer docs (HK)**.
2. **User documentation (UD)**.
3. **Voice conversation (VC)**.

Every track's first item is its research or design document in `docs/research/<ID>-<slug>.md`.

Release (owner, 2026-11-14): the next version follows the merge of FS and PL (both merged; it waits for the owner's word); the admin redesign (AD, merged) comes in a later release. `development` is too far ahead of `master` to ship feature by feature through git: the tracks were built on each other and the migrations only run forward. So every feature has a status in the code (hidden, beta, stable), all code goes to `master`, and each release moves chosen features on. The notes of the next release must include the security fixes from SEC (#421), which also apply to 1.5.13, and the new minimum, WordPress 6.6 (WM): the built scripts need core's `react-jsx-runtime`, so 1.5.13 already failed to load its scripts on WordPress 6.0 to 6.5.

Tests (owner, 2026-11-14): `npm run check` before every commit; a track runs only its related tests (`npm run check:related`) once, before it is merged into `development`; the full `npm run check:all` runs before a release, and what it finds is fixed in that release.

The free/premium split of new features: freemium stays (BM, 2026-11-13, option b), so each feature track proposes its split in its research; features that need embeddings are premium.

### Hooks and developer docs (HK, owner decision, 2026-11-14)

Third-party developers extend KimaAI through its hooks and APIs; today there are 116 PHP hooks (92 filters, 24 actions) and two JS hooks (HK-1, 2026-11-16); kimaai.com documents 11 of them. This track tests every extension point, fixes what is broken, adds the few hooks that are missing and documents each public one on its own page on kimaai.com. Its items run one after another (owner, 2026-11-16); the kimaai.com side is built in this track too, in the website repository.

- **Scope:** PHP actions and filters, JS hooks (`@wordpress/hooks` in the admin and the chatbot), the extension APIs (addons, custom tools, renderables) as guides, and a reference page for every REST route, WP-CLI command and MCP tool.
- **Public or internal:** every hook is classified. Public hooks are documented and kept stable; internal ones carry `@internal`, get no page and may change. Hooks that could bypass the licence or a security check (for example `kimaai_is_premium`, `kimaai_can_use_premium_code`) stop being filterable from outside.
- **New hooks:** only where a concrete developer use case is not covered by an existing hook; the research lists each with its use case and where it fires, and the track goes on with my recommendation (owner delegated, 2026-11-14).
- **Changes:** a renamed, changed or removed public hook keeps working through `apply_filters_deprecated` or `do_action_deprecated` for two minor releases, and its page says "Deprecated since" and names the replacement. Inconsistent names (`kimaai_assistant_*` next to `kimaai_admin_assistant_*`) are cleaned up this way.
- **Code and page stay together:** each public hook has a docblock with `@kimaai-hook <name>`, `@since` and `@see` to its page, and one Markdown page in `docs/hooks/<name>.md` (frontmatter: name, type, since, free or premium, parameters, the feature it belongs to, deprecation). Whoever changes a hook, person or AI, changes its page in the same commit; `npm run check` fails when the code and the pages disagree.
- **Tests:** every public hook has an automated test that hooks in and checks the effect, and the main example of its page runs inside that test.
- **Publishing:** kimaai.com pulls the pages from the released version (`master`) into BetterDocs at `kimaai.com/docs/hooks/<name>`, with an index per area. Hooks of hidden features (FS) are not published. English only. kimaai.com already has 11 hook pages; all match hooks in the code, three of which (`kimaai_chatbot_after_response`, `kimaai_chatbot_error`, `kimaai_chatbot_response_payload`) only fire when an answer does not stream (fixed in HK-5 for the first two). The sync is built by this track in the website repository (owner, 2026-11-16), tracked by an issue there; it needs a read-only token on the server, which the owner creates.

| Item  | Title                                                                                                                                                                                                                                                                     |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HK-1  | Research → `docs/research/HK-hooks.md`: every extension point (116 PHP hooks, 2 JS hooks), public (72) or internal (46), 14 risky hooks, 6 renames, 2 new hooks, the kimaai.com pages (11), the page format, the check and the tests (my recommendation, owner delegated) |
| HK-2  | Conventions: the docblock tags, the page's frontmatter and body, `docs/hook-page-template.md`, `since: next`, the rule in `CONTRIBUTING.md`, `CLAUDE.md` and `AGENTS.md` that a hook change updates its page, and the release-pr step that replaces `next`                |
| HK-3  | The check: the inventory script, `scripts/check-hooks.mjs` and `docs/hooks/index.json`, its step in `npm run check`, the `ci/test-map.mjs` rules, a `hooks` WP-CLI group, and the test helper that runs each page's example                                               |
| HK-4  | Lock and mark: the licence filters replaced by a test-site check, the test seams behind it, the guards, `@internal` on internal hooks, `@kimaai-hook` on public ones, the renames through deprecation, the dead listener removed                                          |
| HK-5  | Chatbot: tests and pages for its public hooks; `kimaai_chatbot_error` and `kimaai_chatbot_after_response` on the streaming path; the ticket in `kimaai_chatbot_handoff`; the new `kimaai:chatbot` browser event                                                           |
| HK-6  | Embedding and search: tests and pages                                                                                                                                                                                                                                     |
| HK-7  | Leads and customer centre: tests and pages; the new `kimaai_lead_validate`                                                                                                                                                                                                |
| HK-8  | Admin assistant: tests and pages                                                                                                                                                                                                                                          |
| HK-9  | Settings and admin: tests and pages (two JS hooks); the field key in `kimaai_trigger_button_click`; the field-components guide                                                                                                                                            |
| HK-10 | Tools and addons: tests and pages; `kimaai_tool_call_allowed` for every tool call; the guides for add-ons and custom tools                                                                                                                                                |
| HK-11 | Reference pages for the REST routes, the WP-CLI command and the MCP tools                                                                                                                                                                                                 |
| HK-12 | The issue in the website repo for the sync                                                                                                                                                                                                                                |
| HK-13 | Website: the hook-docs sync from the released version into BetterDocs                                                                                                                                                                                                     |
| HK-14 | Website: `/docs/hooks/<name>/`, the area categories, the deprecation notice, the 301 redirects of the 11 old pages                                                                                                                                                        |

### User documentation (UD, owner decision, 2026-11-14)

After the redesign and the hooks, every feature gets a user documentation page on kimaai.com with explanations and screenshots, written and kept up to date by the AI the same way as the hook pages (HK).

- **Pages:** one page per feature in the FS registry (for example Lead capture, Ask AI search, Customer Centre, Connections), covering its admin screens and every setting, plus a few task guides (install, the first chatbot, connecting a provider) that link to the feature pages. Each page shows whether the feature is Pro or beta.
- **Source:** one Markdown page per feature in `docs/features/<feature>.md` and per guide in `docs/guides/<guide>.md`, with a frontmatter that names the feature, its settings and its screenshots. Whoever changes a feature, person or AI, changes its page in the same commit; `npm run check` fails when a setting of the feature is missing from its page or a page names a setting that no longer exists.
- **Screenshots:** made by Playwright on a seeded demo site (realistic made-up data, no personal data): the admin screens and the chatbot on the front end, in light mode, with numbered callouts that the text refers to. The pages hold the screenshot definitions; the images are regenerated for every release, so they always show the current design.
- **Review:** the release pull request lists the changed pages with before and after screenshots; they go live with the release once the owner approves it. Pages of hidden features are not published. English only.
- **Existing pages:** the 11 user pages on kimaai.com/docs are the starting point; the new pages keep their URLs where the topic matches, and the others redirect to the new page.
- **Publishing:** the same sync from the website repo as HK, extended to feature pages, guides and images; one request covers both.

| Item  | Title                                                                                                                                                                                                                                         |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UD-1  | Research → `docs/research/UD-user-docs.md`: the page list (features from FS, guides), the page and screenshot format, the demo site and its data, how images reach the release and the site, and the mapping of the existing kimaai.com pages |
| UD-2  | Seeded demo site and the Playwright screenshot runner with callouts                                                                                                                                                                           |
| UD-3  | The check in `npm run check` and the rule in `CONTRIBUTING.md`, `CLAUDE.md` and `AGENTS.md` that a feature change updates its page                                                                                                            |
| UD-4+ | Pages per area (chatbot, knowledge base and search, leads, customer centre, insights, connections, admin assistant, MCP, tools), then the guides                                                                                              |
| -     | The release-pr skill: changed pages and before and after screenshots in the release pull request                                                                                                                                              |
| -     | The format and the sync request for the website repo (together with HK)                                                                                                                                                                       |

### Voice conversation (VC, owner decision, 2026-11-15)

Visitors talk to the chatbot and hear its answers. The answers still come from the site's own content, as typed ones do.

- **Approaches compared in the research:** the browser's own speech recognition and speech output (no cost, quality and privacy depend on the browser), speech-to-text and text-to-speech through the AI provider (a cost per minute), and a realtime speech-to-speech session (lowest delay, highest cost, and the site's content has to reach it through tools). Supported providers and models are checked at the time of the research.
- **Privacy and consent:** audio is personal data; the research covers consent before the microphone opens, what is stored (the transcript, never audio by default), retention and the cost limits per visitor.
- **Design:** the voice mode, the microphone and the entry points are built behind the hidden `voice` feature (WD-10, merged); VC makes them work.
- **Free and Pro:** proposed in the research; features that cost per minute are expected to be Pro.

| Item  | Title                                                                                                                                                                                      |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| VC-1  | Research → `docs/research/VC-voice.md`: the approaches, providers, cost, delay, browser support, privacy and consent, accessibility, and the free/Pro split. **Waits for owner approval.** |
| VC-2+ | Build items, defined after the approval                                                                                                                                                    |

## Later

Not scheduled: a hosted KimaAI service with credits (BM option c: a provider prototype and a written question to the WordPress.org review team about service-side branding), WhatsApp and Telegram (`feat/telegram-integration` exists), Slack and Discord, embedding on non-WordPress sites, proactive triggers, several bots per site section, live chat inside the widget (CC, after CC-16), lazy-loaded syntax highlighting for code in answers (DOC-1), reasoning effort for Ollama thinking models that are not in the model catalogue (QA: `qwen3:4b` can spend the whole output limit on thinking), a setting for trusted reverse proxies (QA-6: today the `kimaai_trusted_proxies` filter), whether the dormant Contact Form 7, Gravity Forms and ElasticPress integration classes (not registered today) ship again or are removed (QA-1), a registration API for third-party renderables in the widget (HK-1: today only built-in types render), a personal-data export of chat messages for logged-in users (IN-11: the lead exporter covers the conversations of leads only), the routes no KimaAI code calls, removed or kept (HK-11: the four wizard routes, four Feedback analytics routes, `GET /chatbot/all` and `POST /chatbot/delete`), regular `## OPTIONS` docblocks for the WP-CLI subcommands whose help text lacks options or their descriptions (HK-11: `vectors query`, `fetch`, `delete`, `stats`, `health` and the `collections` subcommands; declaring them makes WP-CLI check the options), a provider-confirmed meeting booking instead of the one the visitor's browser reports to the lead route (HK-7: it adds 30 points to the lead score and a meeting conversion), and PHPCS and PHPStan coverage of `premium/` (CC: `npm run check` and the AI box runs do not scan `premium/` with either).
