Help Assistant Developer Guide

🛠️ The help assistant - Developer Guide

How the help assistant works under the hood. The plan, the decisions and the reasoning are on The help assistant - design; this page covers what is built.

Step	What	State
1	One shared embedding file	✅ Embeddings - Developer Guide
2	The help index and word search	✅ this page
3	System → Help assistant and the window (no-AI level)	✅ section 7
4	Vectors - matching by meaning	✅ section 8
5	Ask - the written answer	✅ section 10
6	Unanswered questions	✅ section 9

For users: The help assistant.

---

The shape of it

File	What it does
includes/help_index.php	The pages, reading a rendered page, building the index, the search
scripts/help_render_page.php	Renders ONE help page in ONE language and prints its sections as JSON
scripts/help_index_build.php	Builds or refreshes the index from the command line
help_sections	The index - only a cache of the help, one row per section per language
includes/i18n.php	I18n::pinLocale() - fixes the language for a command-line render
tests/help-search.php, tests/help-search-questions.php	The search tests, and the question set every step is measured against
includes/help_assistant.php	Who may use it, the reply and its canned line, the conversation, the index status, starting a rebuild
includes/help_assistant_widget.php	The header button and the window's config, drawn by renderHeaderRight()
assets/js/help-assistant.js, assets/css/help-assistant.css	The window
api/help_assistant/{ask,history,reset}.php	The window's endpoints
system/help-assistant/index.php, api/system/help_assistant.php	System → Help assistant
help_assistant_messages, analysts.help_assistant	The conversation; who has it
tests/help-assistant.php	Step 3's tests
includes/help_vectors.php	Matching by meaning: settings, status, building, ready-made vectors, ranking, the merge
includes/ai_embeddings.php	Every provider's embedding call (shared with Knowledge) - see Embeddings - Developer Guide
help_section_vectors	One vector per help section per model
data/help-vectors/openai-text-embedding-3-small-512.json.gz	The ready-made English vectors, refreshed each release
scripts/help_vectors_export.php	Writes them (RELEASING step 3b)
tests/help-vectors.php	Step 4's tests, against the stand-in server tests/ai-compatible/mock.php
help_assistant_unanswered, analysts.help_assistant_named	Questions the help could not answer; whose name an admin chose to record
includes/help_ask.php	Written answers: the rules, the search_help tool, reading the reply, permission marks
tests/help-ask.php	Step 5's tests (the stand-in server's help-answer / help-none / help-search models)

php scripts/help_index_build.php                   # English
php scripts/help_index_build.php --locales=de,es   # plus German and Spanish

---

1. What a section is - the house-style markup

Every help page already marks its sections the same way, so that markup is the contract - no new markup was needed:

<div class="help-section" id="settings" data-cap="TICKETS_SETTINGS" data-help-search="off">
    <div class="help-section-header">
        <span class="help-section-num">10</span>
        <div><h3>Settings</h3> <p>...</p></div>
    </div>
    <div class="help-cards">
        <div class="help-card"><strong>Departments</strong><span>Create departments like IT...</span></div>
    </div>
</div>

Part	Becomes
id	the anchor an answer links to - tickets/help.php#settings
the first <h3>	the title
everything inside	the text, kept as blocks - one per paragraph, card, step, note, list item, table row
data-cap (optional)	the capability (Cap enum) the section describes - for permission-aware answers in step 5
data-help-search="off" (optional)	never indexed

The number badge, <script> and <style> are left out. A section without an id is ignored.

Plus one entry for the page's introduction - its .help-hero banner and any .help-lede paragraph outside the sections, titled by the hero's (or the page's) <h2>. It has no anchor (section_key is the page itself), so it links to the top of the page, and it is often the best answer to "what is X?". An audit of all 74 pages (November 2026) found no section without an id and no help text outside a section other than these introductions. This is written into Help page house style, and tests/help-search.php fails if any help page gives no sections.

data-cap is read and stored now; the marks themselves go onto the pages with step 5, when answers start using them.

---

2. Rendering, not reading the source

The obvious approach - read each page's source for t('...') keys - does not work:

• Many pages build their sections in a loop through helpers ($h($id . '.title') in people/help.php), so the keys never appear literally.
• The System help pages are English in the page itself, with no keys at all.

So every page is rendered, exactly as a reader would see it, and the sections are read out of the HTML (helpRenderSections(), using DOMDocument).

One process per page

function helpIndexRenderPage(string $root, string $php, string $page, string $locale, int $analystId): ?array
{
    $cmd = escapeshellarg($php) . ' ' . escapeshellarg("$root/scripts/help_render_page.php") . ' '
         . escapeshellarg($page) . ' ' . escapeshellarg($locale) . ' ' . (int)$analystId;
    exec($cmd . ' 2>' . (stripos(PHP_OS_FAMILY, 'Windows') === 0 ? 'NUL' : '/dev/null'), $out, $code);
    // ...the last non-empty line is the JSON
}

TRAP: never render two help pages in one PHP process. Pages define functions and constants, call session_start() and may exit() - the second would collide with the first, or never run. help_render_page.php renders one, prints JSON from a shutdown function (so it is printed even when the page exits), and ends.

The renderer gives the page an ordinary signed-in GET:

I18n::pinLocale((string)$locale);                      // the page's own initFromSession() cannot change it
session_id('helprender' . bin2hex(random_bytes(8)));   // a throwaway session, destroyed at the end
session_start();
$_SESSION['analyst_id'] = (int)$analystId;
parse_str($query, $_GET);                              // system/integrations/help.php?provider=jira
ob_start();
register_shutdown_function(function () {
    $html = '';
    while (ob_get_level() > 0) $html = ob_get_clean() . $html;
    @session_destroy();
    echo "\n" . json_encode(['ok' => true, 'sections' => helpRenderSections($html)], ...) . "\n";
});
chdir(dirname("$root/$page"));
require "$root/$page";

• The analyst is an active administrator with every module (helpIndexRenderAnalyst()), only so each page's own requireModuleAccess() lets it through. Nothing is written for them - help pages do not touch the Recent trail.
• The language: a page calls I18n::initFromSession(), which reads the analyst's saved preference. I18n::pinLocale() - command line only, it does nothing in a web request - makes that call leave the locale alone.
• It is command-line only (PHP_SAPI !== 'cli' → 404), and the page argument must match the help-page pattern, so it cannot be pointed at anything else.

Which pages

helpIndexPages(): every */help*.php and */*/help*.php that calls requireModuleAccess('...') (its module), every system/help/*.php except _*.php and index.php (module system), plus HELP_INDEX_EXTRA - the integrations guide, one page per ?provider=, which the folder scan cannot find. Left out on purpose (HELP_INDEX_EXCLUDE): the self-service portal's guide and Help Centre, which are for requesters. Today: 74 pages, 712 entries - 639 sections plus 73 page introductions.

---

3. Building the index

helpIndexBuild($conn, $locales) renders every page in English, then each extra language:

Unchanged section	left alone - its row, and later its vector, are kept (text_hash matches)
Changed section	updated
Section gone from its page	deleted; a page that no longer exists takes its sections with it
Another language	stored only where the text differs from the English - an untranslated section would be a second copy of the English, so the System help pages (English in the page) never get "German" rows
A module switched off	skipped, its rows left alone - nobody can open it, so the search never returns them

An unchanged rebuild changes nothing (tested). English takes about 25 seconds for 74 pages; English, German and Spanish about 80.

help_sections:

CREATE TABLE IF NOT EXISTS `help_sections` (
    `section_key`      VARCHAR(191) NOT NULL,   -- 'tickets/help.php#settings'
    `locale`           VARCHAR(10) NOT NULL DEFAULT 'en',
    `page`, `anchor`, `module`, `cap`, `title`, `body`,
    `text_hash`        CHAR(64) NOT NULL,       -- sha256 of title + body: what it says now
    `embedding`        MEDIUMTEXT NULL,         -- step 4
    `embedding_hash`   CHAR(64) NULL,           -- the text_hash the vector was made from
    `embedding_model`  VARCHAR(80) NULL,
    `source`           VARCHAR(20) NOT NULL DEFAULT 'built',   -- or 'release'
    `source_version`   VARCHAR(20) NULL,
    `built_datetime`   DATETIME NOT NULL,
    UNIQUE KEY `uq_help_sections_key_locale` (`section_key`, `locale`),
    KEY `idx_help_sections_locale_module` (`locale`, `module`)
);

embedding_hash is how the out-of-date warning will work: a section whose text_hash is not its embedding_hash has changed since its vector was made.

---

4. The word search

helpSearch($conn, $analystId, $question, $locale, $currentModule) = helpRank(helpSectionsFor(...), ...).

Which sections - helpSectionsFor()

Every section in the analyst's language where there is one, otherwise its English row - the fallback is per section, so a half-translated language never hides the other half. Then only modules the analyst can open (analystCanAccessModule(), which also says no to a module switched off for the install).

Search words - helpTokens() and helpStem()

Lower case; letters and digits only; common English words dropped (how, do, I, a, the...); then a cut-down Porter stemmer. It only has to be consistent - the question and the help go through the same rules - not produce real words:

In	Out
departments	department
categories	category
statuses, status	status
adding, added, adds, add	add
settings, setting	set
create, created, creating	creat
route, routing	rout
breached	breach
class, analysis, business	unchanged

Non-English words are only lower-cased.

Ranking - BM25 over passages

BM25 is the classic search-engine scoring. For each question word t in a passage d:

$$\text{score} = \sum_t \text{idf}(t)\cdot\frac{f(t,d),(k_1+1)}{f(t,d)+k_1\left(1-b+b,\frac{|d|}{\text{avg}|d|}\right)},\qquad \text{idf}(t)=\ln!\left(1+\frac{N-n_t+0.5}{n_t+0.5}\right)$$

with k₁ = 1.2 and b = 0.75. In words: rare words count for more (ticket is in most sections and says little; department narrows it right down), a word appearing more often helps but with diminishing returns, and a long passage does not win just by being long. Title words count three times (HELP_TITLE_WEIGHT).

TRAP: score passages, not whole sections. The first build scored whole sections, and the very first test question - how do I create a ticketing department - missed. Tickets → Settings is about 10,000 characters of cards (the average section is 1,500), and BM25's length rule, correctly, buried its one Departments card. Now each section is cut into passages of about 700 characters made of whole blocks (helpPassages() - the renderer's blank-line-separated blocks, packed in order, never splitting a card), passages are scored, and a section scores as its best passage, with that passage as the snippet.

foreach ($sections as $i => $s) {
    $titleTokens = helpTokens($s['title']);
    foreach (helpPassages($s['body']) as $text) {
        $tokens = array_merge(...array_fill(0, HELP_TITLE_WEIGHT, $titleTokens), ...[helpTokens($text)]);
        // ...term frequencies, document frequencies over PASSAGES
    }
}
// ...each section keeps its best passage's score
if ($currentModule !== null && $s['module'] === $currentModule) $score *= HELP_MODULE_BOOST;   // 1.15 - a tie-breaker

About 80 ms over 712 entries on a laptop, all in PHP.

---

5. How good it is - the question set

tests/help-search.php holds 65 realistic questions, each with every section that would be a right answer, scored as is a right section in the top 5:

Kind	Example	Word search
Plain	how do I create a ticketing department	43/47 (91%) - floor 80%
Exact names	Warbot, MoSCoW, Enforce approvals	6/6 (100%) - floor 80%
Vague - no words shared with the answer	my boss wants a weekly PDF of how we are doing	2/6 (33%)
Other languages	Wie erstelle ich eine Abteilung?, Hogyan hozzak létre jegykezelő részleget?	2/6 (33%)

Plain and exact questions must stay above their floor. Vague questions and other languages are reported, not failed - they are exactly what vectors (step 4) and the AI's own searching (step 5) are for, and these numbers are the baseline those steps have to beat. Typical misses, and why:

• my boss wants a weekly PDF → the answer is Report packs; no word in common.
• Wie erstelle ich eine Abteilung? → the German help says Abteilungen; there is no German stemming.
• Restablecer la contraseña de un analista → the answer is System help, which is English only.
• Hungarian and Polish → no help in those languages, so no words to match at all.

---

6. Tests

tests/help-search.php:

• No database (19 checks): reading sections from rendered HTML (only sections with an id, the page's introduction, the h3 title without the number badge, a card's title not glued to its body, scripts left out, data-cap, data-help-search="off"); search words and the stemmer; passages made of whole blocks of at most 700 characters; one card in a very long section winning, with that card as the snippet; the module tie-breaker.
• With FREEITSM_TEST_DATABASE: builds English, German and Spanish through the real renderer; every help page gives sections; every section has a title; German rows only where the text is German (none for System help); an unchanged rebuild changes nothing; a ZZ analyst with only Tickets is searched over Tickets help only (control: an administrator gets every module); then the question set.

php tests/help-search.php
FREEITSM_TEST_DATABASE=<the throwaway db> php tests/help-search.php

See also Developer Tests - Knowledge.

---

7. Step 3: the window and System → Help assistant

Who has it

Two switches, both needed: help_assistant_enabled = '1' in system_settings (System → Help assistant, off by default) and analysts.help_assistant = 1 for the analyst (ticked on the same page). helpAssistantAllowed() asks both, plus active, once per request - the header asks on every page:

function helpAssistantAllowed(PDO $conn, int $analystId): bool
{
    static $cache = [];
    if (isset($cache[$analystId])) return $cache[$analystId];
    if ($analystId <= 0 || !helpAssistantReady($conn) || !helpAssistantEnabled($conn)) return $cache[$analystId] = false;
    $st = $conn->prepare("SELECT 1 FROM analysts WHERE id = ? AND help_assistant = 1 AND COALESCE(is_active, 1) = 1");
    ...
}

TRAP: the header must not break before Database Verify. helpAssistantReady() checks the column and tables exist; until they do, the assistant is simply absent. helpAssistantWidgetRender() also swallows any error and draws nothing - a help button is never worth an error on every page.

The three window endpoints share one gate, helpAssistantRequireJson(): signed in (401), allowed (403). They are not a module, so tests/module-access-coverage.php lists api/help_assistant/ with that reason; the search itself only returns modules the analyst can open (helpSectionsFor()).

The header button

renderHeaderRight() (includes/waffle-menu.php) - the header on every module - calls helpAssistantWidgetRender($GLOBALS['current_module'] ?? null). When allowed it prints the button, links the CSS, and hands the window its config:

window.HELP_ASSISTANT = {
    ask, history, reset,        // endpoint URLs from BASE_URL
    module: 'tickets',          // the page's module - a search tie-breaker
    strings: { title, greeting, placeholder, ... }   // help_assistant.* in the analyst's language
};

The reply

api/help_assistant/ask.php → helpAssistantAnswer(): helpRank() over helpSectionsFor() in the analyst's language, each result given its page's title (from that page's introduction entry) and a link from BASE_URL. Then the kind of reply, which picks the line:

function helpAssistantReplyKind(array $results, ?string $currentModule = null): string
{
    if (!$results) return 'none';
    $top = (float)$results[0]['score'];
    if ($top < HELP_ASSISTANT_WEAK_SCORE) return 'weak';                       // 9.0
    $second = isset($results[1]) ? (float)$results[1]['score'] : 0.0;
    if ($second <= 0.0 || $top >= HELP_ASSISTANT_CLEAR_RATIO * $second) return 'clear';   // 1.25
    if ($currentModule !== null && ($results[0]['module'] ?? null) === $currentModule) return 'module';
    return 'several';
}

The thresholds come from the question set, not a guess. Printing every question's top score and its lead over the runner-up: of the 22 questions whose top result was at least 1.25 times the next, 20 had a right section first and one more had it in the top five - so "this looks like exactly what you need" is honest about nine times in ten. Below a top score of 9 sat most of the shaky answers, where "these might be close" is the right tone even when it is right.

helpAssistantPhrase($kind) picks at random from help_assistant.phrase.<kind>.1, .2, ... - as many as the language file has; English fills any a language lacks. A test checks no line claims an AI read anything.

The conversation

help_assistant_messages: one row per message - role (user / assistant), body, and for a reply results as JSON ({kind, results}), so history redraws exactly what was shown. The newest 200 per analyst are kept. Reset deletes the analyst's rows. The table has a cascading foreign key to analysts and is registered in analystReferenceRegistry() as personal.

The window

assets/js/help-assistant.js builds the window on first open - everything with textContent, since questions and help text are data:

• Desktop: fixed, bottom right by default, dragged by its header (pointer events, clamped below the header and inside the viewport). Position and open are a per-viewer convenience in localStorage (try/catch - private mode just forgets). Open on one page, it reopens on the next.
• Phone (≤ 768px): a full-screen sheet; place() clears any desktop position so the CSS wins without !important; 16px text so iOS does not zoom (Mobile Techniques §3); opening pushes a history entry, so the device back button closes it; never reopened by itself, because it would cover the page just opened.
• Opening a result scrolls the help panel, never the page (#2774). Help pages scroll inside .help-main; a plain #anchor made the browser scroll the page too, sliding the header up about 14px. A result on the same page (samePage(), which ignores .php for pretty URLs) scrolls only its panel and updates the hash with replaceState; one on another page leaves a jump note in localStorage, and that page, once loaded, puts the page back at the top and scrolls its panel to the section - the help pages' own section links do the same.
• Classes are hlpa-. It is loaded on every page, beside every module's CSS - System → Help assistant itself uses ha-.

System → Help assistant and the index

The page opens with a green panel saying it works without any AI, before the switch, the per-analyst list (All / None / a filter) and the index panel. Saving with the assistant on and no index yet starts a build, so the window is never answering "nothing found" to everything.

Rebuild spawns scripts/help_index_build.php with the Intune worker's intuneSpawnGenericWorker() (reused, not copied). The build writes its progress to help_index_build_state (running / done / failed, with stats), which the page polls every four seconds; a running older than half an hour counts as dead. With no --locales, it builds English plus every language analysts have chosen (helpIndexLocalesInUse()). The changed since warning is the quick check: any help page or language file newer than the last build.

TRAP: a background worker must not print. intuneSpawnGenericWorker() pclose()s the worker's output straight away. On Windows the first write to that closed pipe killed the build after one page - it said running for ever. Started with the job id 0, the builder now prints nothing; progress goes to the setting.

TRAP: the renderer's one expected notice. Each page's own session_start() is ignored because the renderer's session is already running, and PHP logs a notice per render - 74 per language per build. help_render_page.php silences exactly that notice and nothing else.

Tests

tests/help-assistant.php - 12 checks without a database (the reply kinds at the thresholds; every kind has wording in English, German and Spanish; a German asker gets German; the lines vary; none claims an AI read anything) and 20 over HTTP with a ZZ administrator and a ZZ analyst made for the run: the settings are admin-only; off by default, the window refuses and the header draws no button; saving switches it on for exactly who is ticked; the button appears with the page's module; asking returns a line and results with a right answer; nothing found gives the none line; an empty question is refused; a non-admin gets no System help; history oldest first; Reset; and a background rebuild that finishes on its own (about 22 seconds). The switch and every analyst's flag are restored in finally.

The window itself was driven in headless Chrome at 1280 and 390 pixels wide: it opens bottom right (desktop) or full screen with 16px text (phone), nothing scrolls sideways, a question returns four cards with Tickets help → Settings first, and Reset brings the greeting back.

---

8. Step 4: matching by meaning

Optional. With no embedding model set up, nothing in includes/help_vectors.php runs and the assistant searches by words exactly as in step 3. With one, every help section has a vector, each question gets one when it is asked, and the word ranking and the meaning ranking are merged.

What it bought - measured, not guessed

The 65-question set, OpenAI text-embedding-3-small, right section in the top five:

	Plain (47)	Exact (6)	Vague (6)	Other language (6)
Words alone (step 3)	43	6	2	2
Vectors alone	46	6	4	4
Merged, equal weight	46	6	5	3
Merged, words at half weight (shipped)	46	6	6	3

• 512 dimensions scored exactly as the full 1,536 and compare three times faster (16 ms against 50 ms over 720 sections), so OpenAI's text-embedding-3 models are asked for 512 (HELP_VECTORS_DIMENSIONS).
• Through the real reply (helpAssistantAnswer()), the clear winner line came up 37 times: a right section first 32 times, in the top five the other 5 - never wrong.
• Cost: embedding all 720 English sections is about 300,000 tokens - well under a penny. A question is a few tokens; the call takes 0.4-0.5 s, and FreeITSM's own part of an answer 130-200 ms.

Settings, and the key

The embedding model is its own AI settings namespace, help_embed (includes/ai_settings.php), so its key is stored encrypted by aiSettingsSave() like every other AI key, and its cost shows on its own. The entry is marked 'embeddings' => true, which keeps it off System → AI thinking and out of the D014 chat test - an embedding model can neither think nor chat.

• Providers: AI_EMBEDDING_PROVIDERS - OpenAI, Azure OpenAI, an OpenAI-compatible server. Anthropic has no embedding model; the endpoint refuses any provider not on the list.
• Models come from a dropdown, never typed: aiEmbeddingModels() asks OpenAI or the server for its list (Azure: the OpenAI models - choose the one the deployment runs).
• The key never goes back to the page. The status carries key_hint = **** + the last four characters; a blank box or that hint posted back means "keep the saved key", because isMaskedNoChangeValue() treats a value starting with * as unchanged.

TRAP: the hint must start with asterisks. A hint of bullets (••••abcd) posted back would be saved as the new key.

Storage: one vector per section per model

CREATE TABLE help_section_vectors (
    section_id  INT NOT NULL,            -- help_sections.id, ON DELETE CASCADE
    model       VARCHAR(120) NOT NULL,   -- aiEmbeddingModelId(): 'openai:text-embedding-3-small@512'
    text_hash   CHAR(64) NOT NULL,       -- the section's text_hash when made; different now = out of date
    vector      MEDIUMTEXT NOT NULL,     -- float32, base64 (aiVectorPack()) - a third of JSON's size
    source      VARCHAR(20) NOT NULL DEFAULT 'built',   -- or 'release'
    source_version VARCHAR(20) NULL,
    UNIQUE KEY (section_id, model)
);

Vectors from different models mean nothing to each other, so only those made by the model in use (help_vectors_model) are compared with a question. OpenAI and Azure running the same model make the same vectors, so aiEmbeddingModelId() gives them one identity - the ready-made vectors suit both. A compatible server's models are compatible:<name>.

The merge

helpAssistantAnswer() asks both rankings for their top 20 and merges them with reciprocal rank fusion - each list adds weight ÷ (60 + position), so a section near the top of both comes first:

foreach ($word as $i => $r)          $fused[$r['section_key']] += HELP_MERGE_WORD_WEIGHT / (60 + $i + 1);   // 0.5
foreach ($vec['ranked'] as $i => $r) $fused[$r['section_key']] += 1 / (60 + $i + 1);
arsort($fused);

A section only meaning found is included, with the start of its text as the preview. Below a similarity of HELP_VECTORS_FLOOR (0.32) meaning is ignored: off-topic questions ("best pizza recipe", "xyzzy plugh") reached 0.21-0.26, the lowest real question 0.38 - so nonsense still gets "I couldn't find anything".

The reply kind, with vectors (helpAssistantReplyKind()): weak only when the similarity is under 0.45 and the word score is weak; clear when meaning's first choice leads the next by 0.10, or is first by words and by meaning at once.

Changing model without going dark

helpVectorsBuild(): take the ready-made vectors if this is the shipped model; embed every section with no current vector, 64 to a request; and only when none is missing, make this model the one in use and delete the others.

TRAP: a question must be embedded by the model in use, not the model chosen. Once an admin saves a new model, the saved settings describe the new one - so the in-use model's settings are kept apart (help_vectors_active_cfg, written at the switch, its key encrypted with encryptValue()). helpVectorsReady() embeds questions with those. That is what lets the old model keep answering while the new one builds; the first version of this step used the saved settings, and choosing a model would have silently dropped the assistant to words until the rebuild finished. Writing the test found it.

A build that fails changes nothing. A provider that cannot be reached when a question is asked logs it and falls back to words - the window still answers.

The ready-made vectors

data/help-vectors/openai-text-embedding-3-small-512.json.gz - the English sections' vectors, keyed by section_key|locale with the text_hash each was made from (720 vectors, about 1 MB). helpVectorsImportShipped() takes a vector only where the install's section text still hashes the same; a section the install has changed is embedded there. A fresh build on prtest took 720 ready-made and embedded only the 659 German and Spanish sections.

Each release refreshes the file: php scripts/help_vectors_export.php X.Y.Z (RELEASING step 3b), on an install with the release's help and this model set up.

System → Help assistant

A Matching by meaning panel: the switch, the provider, the key (or the Azure endpoint / deployment / version, or the server address), the model dropdown ("ready-made vectors included" beside text-embedding-3-small), Save and Test. Under it the status - "In use: … - 720 sections matched by meaning"; when the chosen model differs from the one in use, the warning with Rebuild (or Use the ready-made vectors, which is instant and free); and "N sections have changed since their vectors were made". Saving it on for the first time starts the build; a change of model is not started on save, because it may cost money - the page offers it.

Tests

tests/help-vectors.php - 20 checks with no network (storing a vector; model identities; the URL, headers and body for OpenAI, Azure deployment and v1, and a compatible server; a provider that cannot embed refused; the merge; the reply kinds with vectors) and 14 against the stand-in OpenAI-compatible server tests/ai-compatible/mock.php (which serves /v1/embeddings and /v1/models too), started with PHP's built-in server - deterministic vectors, two models that disagree, one that fails: building in batches, the model in use, a rebuild that changes nothing, a merged reply, the old model answering while a new one is chosen, the switch, a failed build changing nothing, the server going away (words, no error), switched off. The vectors and settings are put back in finally.

---

9. Step 6: unanswered questions

The questions the help could not answer, in people's own words - the most useful thing the assistant produces for whoever writes the help.

What is kept, and when

api/help_assistant/ask.php calls helpAssistantRecordUnanswered() after every reply. It keeps the question when the reply kind is none or weak (helpAssistantShouldRecord()), with its language, the module the asker was in and the closest section found:

CREATE TABLE help_assistant_unanswered (
    question         VARCHAR(500) NOT NULL,
    locale           VARCHAR(10) NOT NULL,
    module           VARCHAR(50) NULL,
    kind             VARCHAR(10) NOT NULL,      -- 'none' or 'weak'
    best_title       VARCHAR(255) NULL,         -- the closest section, if any
    analyst_id       INT NULL,                  -- ONLY when Record who asked is on for them
    dealt_by         INT NULL,
    dealt_datetime   DATETIME NULL,             -- NULL = waiting
    created_datetime DATETIME NOT NULL
);

TRAP: missing for them is not missing. A non-admin asking "reset an analyst password" gets nothing - System help is admins-only - but the help covers it. Recording that would put help that exists on the list of help to write. So before keeping a question, it is asked again as an all-modules administrator (helpIndexRenderAnalyst()); if that finds a good answer, it is not kept. That only runs on a miss, so it costs nothing usually. The test's non-admin landing on the list is how this was found.

A failure here is logged and swallowed: it must never cost the asker their answer.

The bell: administrators, never the asker

NotificationsService::notify($conn, [
    'analyst_id'  => $adminId,              // every active administrator
    'event_type'  => 'help.unanswered',
    'entity_type' => 'help_unanswered',
    'entity_id'   => 1,                     // ONE entity for all of them - so they coalesce
    'actor_id'    => $analystId,            // the asker - rule 1: never notify the actor
    'actor_name'  => $named ? $fullName : null,
    ...
]);

• One row with a count. notify() merges unread notifications about the same entity within its window, and every question uses entity 1 - so twenty questions in an afternoon are one bell entry saying 20, not twenty.
• Never the asker - including an administrator asking: they are the actor, and rule 1 drops it. No special case was needed.
• admin_only. The type is registered with 'admin_only' => true; effectivePreferences() now leaves such a type out for anyone who is not an administrator, so Preferences never offers a switch for a notification someone can never get.
• The link: entityLink('help_unanswered', 1) → system/help-assistant/#unanswered.

Record who asked

analysts.help_assistant_named - a second tick per analyst under Who has it, saved with the rest (only meaningful for someone who has the assistant). helpAssistantNamed() decides whether analyst_id and the bell's actor_name are filled in. The window is told (window.HELP_ASSISTANT.named) and shows "If the help can't answer a question, it's shared with your admins with your name" under its header - never recorded silently.

Both analyst_id and dealt_by are registered in analystReferenceRegistry() as history: the question outlives the name, and an anonymised analyst shows as Former analyst #N, like every other "created by".

The list

api/system/help_assistant.php: unanswered (status new / done / all, newest first, names joined in where kept) and mark (dealt true or false). The page draws everything with textContent - the questions are whatever people typed - and shows the waiting count beside the heading.

Readiness

TRAP: check every table, not the first ones. Step 4's code arriving on an install before Database Verify had created help_section_vectors made System → Help assistant fail with "Something went wrong". helpAssistantReady() now checks every table and column the assistant uses; until they exist the page says to run Database Verification and the header shows no icon.

Tests

tests/help-assistant.php gained 17 checks (now 49): a question nothing answers is kept as asked, without a name by default; the administrators' bell rings and later questions join the same row with a growing count; the asker's never rings, nor an administrator's for their own question; an answered question is not kept, nor one answered in a module the asker cannot open; with Record who asked on, their window says so (and nobody else's) and their name is kept; the list is admin-only, newest first, names only where recorded; Done and Reopen move the waiting count; Preferences offers the type to administrators only. Everything the run records is removed in finally.

---

10. Step 5: written answers

Optional. A chat AI - namespace help_ai, set up with the same shared AI panel as every other AI feature, key encrypted, administrators only - reads the sections the search found and answers in a sentence or two, in the asker's language. Switched on by help_ask_enabled; helpAskReady() is that switch plus a configured provider. With either missing the assistant replies exactly as in steps 3-4.

What the AI is given

helpAssistantAnswer() runs the search as before, then helpAskAnswer() numbers the best four sections and sends them with the question. A long section is given from the passage the search matched (helpAskSectionText(), up to 3,000 characters) - helpRank() now returns each result's best passage for this. A section marked with a permission the asker lacks is labelled [needs permission the user does not have].

The rules (helpAskSystemPrompt()), in short:

1. Only the numbered sections (and any fetched with search_help) - never other products or general IT knowledge.
2. Never invent a menu, button, field or page; write names exactly as the sections do - they are the words on the screen.
3. The user's language by name (or the question's, if clearly different) - with screen names kept as written.
4. Brief; start with the answer - never "Based on the help sections".
5. Check the sections really are about the question (analysts are not requesters); if not, or the question is not in English, search_help in English first - up to twice; then NOT_COVERED, never a guess.
6. Without the permission: say who can do it, not how.
7. A SOURCES: line.
8. Signpost: the way there as a bold path from the module - Tickets → Settings → Departments - built only from the sections' own words, in their language; the help page's name is never a step (#2778).

Each section is headed with its module's menu name ((module: Software), from helpAskModuleName(), in the asker's language) because the help writes paths from inside the module - "Settings → Renewals" in the Software help. That module name is the missing first step.

TRAP: an English example in a rule gets copied into other languages. The first wording also said section titles are never menus - so for German, whose section is titled Einstellungen, the model dropped it and used the example's Settings: Tickets → Settings → Abteilungen. Only the help page name is excluded now, and the rule says to take every step from the sections' language, never the example.

TRAP: NOT_COVERED can come last. A model that narrated its search ended with NOT_COVERED on its own line; only the start of the reply was checked, so the narration was shown as an answer. A line that is just NOT_COVERED, anywhere, now means not covered.

TRAP: the end of the question beats the system rules. Haiku kept opening with "Based on the help sections…" and narrating ("I'm checking the sections…") despite rule 4 - 9 of 65 answers. The user message now ends by repeating the format ("Reply with the answer only - no description of what you are doing…"), and it fell to 1.

The tool, and when it ends badly

search_help(words) runs helpRank() over the analyst's sections and returns new numbered sections, continuing the numbering, so the SOURCES line can name them. It is how a language with no help files gets answered: the AI searches in English itself. Nothing found at first still goes to the AI for that reason - before that change, Hungarian and Polish questions never reached it.

TRAP: a model that searches every round ends with no text. With three rounds and a keen model, the last reply can be another tool call - so content is empty. One last call without tools, with every section gathered, makes it answer or say NOT_COVERED.

TRAP: a model sometimes WRITES a tool call. Claude Haiku once replied with a sentence of narration, then <function_calls><invoke name="search_help">…</invoke></function_calls> as plain text, then the answer. helpAskParse() keeps only what follows the last such block, and takes off a forbidden opening if one slipped through.

Reading the reply

helpAskParse(): NOT_COVERED - alone, or followed by an explanation, as models do - means not covered; otherwise the SOURCES: line becomes the sections it names (numbers it was never given are ignored), and is removed with any inline [1] markers. The reply is then:

AI said	Reply kind	The window shows
an answer	answer	the text (line breaks and bold, built from text nodes - it is model output) and "From the help" cards for the cited sections
NOT_COVERED	not_covered	an honest line ("The help doesn't seem to cover that. These are the closest sections:") and three cards; the question joins the unanswered list
nothing usable / an error	the search kinds	exactly the step 3-4 reply

The unanswered check now asks again search only as an all-modules administrator, and skips recording only when that finds a good answer in a module the asker cannot open - a not_covered from an AI that could see the right module is recorded.

Permission marks

The settings help of eleven modules carries data-cap with the module's umbrella permission (tickets.manage, tasks.manage, ... - see Help page house style). helpAskCapHeld() counts an umbrella as held when the analyst has any permission of that module - the section covers all of them. Checklists (open to its module) and Reporting's dashboard filters are not marked.

Measured

Claude Haiku (claude-haiku-4-5-20251001, the default), the 65-question set on prtest, answered from a right section:

Plain (47)	Exact (6)	Vague (6)	Other language (6)
46	6	5	3 (and 1 honestly not covered)

About 2.7 seconds, ~3,000 tokens in and ~150 out a question - around a third of a penny. Polish and Hungarian come back in Polish and Hungarian with the English menu names kept. Known miss: a Spanish question about resetting an analyst's password is answered from Tickets → Users - System help is English only, so a Spanish question does not match it by words, and the model did not search in English. It goes when the System help pages move into the language files.

The first full run ended part-way with Anthropic's "Your credit balance is too low" - and every remaining question fell back to the search reply, as designed.

Try it

System → Help assistant → Try it (action: try): the reply as the admin would get it, plus what the AI was given ([1] …), any searches it made, the model, time and tokens. Nothing is saved and nothing goes on the unanswered list.

Tests

tests/help-ask.php - 21 checks with no AI (reading replies: SOURCES, inline markers, NOT_COVERED in its forms, unknown numbers, the written-out tool call, a forbidden opening; the rules; a long section's text; the permission label) and 15 against the stand-in server tests/ai-compatible/mock.php, which gained three models: help-answer quotes the first section it was given (proof the sections arrived), help-none says NOT_COVERED, help-search calls search_help once and cites what it found - plus missing for the AI failing. help-assistant.php and help-vectors.php now switch written answers off for their runs: on an install with them on, those tests began calling the real AI.

Found in a real browser: the patch that added answerText() turned the \n in its regex into a real line break - a syntax error that stopped help-assistant.js loading at all, so the whole window vanished, not just answers. Every PHP test passed. A headless Chrome check of the real widget found it before it was committed.

---

Related

• Internals series - the hybrid model in depth: 1 - the index · 2 - the hybrid search · 3 - answers and misses · every design question, answered
• The help assistant - for users
• The help assistant - design
• Embeddings - Developer Guide - step 1, and what step 4 builds on
• Help page house style - the markup the index reads
• Internationalisation (i18n)