From 202e8fc0bdebd00333bd06fed69645787959d533 Mon Sep 17 00:00:00 2001
From: oblomov-dev <noreply@anthropic.com>
Date: Fri, 11 Sep 2026 12:11:28 +0000
Subject: [PATCH 1/2] Search: stop words, phrase bonus, group order, compounds,
 plural, relaxed queries

Five ranking defects measured on the real index, each pinned in
test/search.test.mjs:

- "how do i install" answered with Client API > check_on_init: `a`, `i`,
  `to`, `do` are a prefix of something in every entry and each earned a
  title-hit's worth of points. Stop words are no longer search terms while
  a real word is left.
- "abap cloud" preferred abap-cleaner over the heading "ABAP Cloud": the
  words next to each other now earn a bonus.
- "dialog" opened on four pages that mention the word above 47 samples
  that are dialogs: groups come in the order of their best hit, the
  documentation leading only when it has a real answer.
- "messagebox" missed the heading "Message Box", "tables" found 33 of 202:
  a field is also matched with its spaces taken out, and a plural `s` is
  taken off before the prefix match.
- "tabel" and "readonly" found nothing: a query that finds nothing sets
  the rarest word aside, then tries one edit away against the titles, and
  the box says what it answered instead; synonyms are data in the index
  builder (readonly -> editable, f4 -> value help, ...).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017JMbwNQAZ65yn4GrgRdvsi
---
 AGENTS.md                              |  43 +++-
 docs/.vitepress/theme/SearchBox.vue    |   9 +-
 docs/.vitepress/theme/search-engine.js | 317 +++++++++++++++++++++----
 scripts/lib/search-index.mjs           |  46 +++-
 test/search.test.mjs                   | 130 +++++++++-
 5 files changed, 485 insertions(+), 60 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index d9478c044..4bd4336c7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -277,8 +277,47 @@ what a reader wants is a sample, in another repository, on another deployment.
 (`/docs/search-index.json`, built by `generate-search.mjs`): every page of the
 manual with its headings and its words, and all ~770 entries of the three
 sample catalogues with the titles, summaries and keywords those repositories
-maintain. Results are grouped by area, documentation first, and a sample hit
-opens that sample's own page in the catalogue.
+maintain. Results are grouped by area, and a sample hit opens that sample's
+own page in the catalogue. The groups come in the order of their best hit;
+the documentation leads whenever it has a real answer (a hit within half of
+the best hit anywhere), and a page that only MENTIONS the word comes after
+the samples that are about it — "dialog" used to open on Value Help, Popup,
+PDF and Lock above forty-seven samples that are dialogs.
+
+**What the matcher does with the words, and why.** Each rule is a query that
+was measured wrong on the real index before it, and each is pinned in
+`test/search.test.mjs`:
+
+- **Stop words are not search terms** while a real word is left. "how do i
+  install" was answered with Client API › check_on_init, and Installation
+  was not in the first four: `a` and `i` are a prefix of something in every
+  entry and each earned a title-hit's worth of points. A query that is
+  nothing but stop words still asks what it says.
+- **The words next to each other earn a bonus.** "abap cloud" preferred
+  Toolchain › abap-cleaner (a title hit on `abap`, a mention of `cloud`)
+  over the heading that IS the two words typed.
+- **A field with its spaces taken out is matched too**, at the weight of the
+  field, for terms of five letters and up: "messagebox" found the three
+  samples spelled that way and not the chapter whose heading is "Message
+  Box", nor "selectdialog" a single page. The index carries no compound
+  forms for this; the matcher looks (`joined( )`).
+- **The plural is the singular with an `s` on it**, taken off before the
+  prefix match — "tables" found 33 entries and "table" 202, and all 169 it
+  missed were about tables. Letters only, never `ss`, never a class name.
+- **Nothing found is not the end**: the word on the fewest entries is set
+  aside, then the next, until something answers; a single word that still
+  finds nothing is tried against every title word one edit away ("tabel" is
+  "table"; and the candidate that starts the way the reader started wins
+  over the one on more titles, or "tabel" would be "label"). Whatever
+  answered is on the result as `hits.relaxedTo` and both boxes say so above
+  the rows: a list that silently answers a different question than the one
+  typed is worse than an empty one.
+- **Synonyms are data in the index, not code in the matcher**: `SYNONYMS` in
+  `scripts/lib/search-index.mjs` is `[what is typed, what the entry says]`
+  pairs ("readonly" for `editable`, "f4" for the value help), added to an
+  entry's `terms` — the long tail's weight, so the alias finds the entry and
+  the ranking stays with the words it really carries. One direction each,
+  so it is the reader's word that is mapped, not the project's.
 
 **The box states the type it would otherwise inherit.** Every rule inside the
 panel is identical to `.search-panel`'s in `catalogue.css` — and the two still
diff --git a/docs/.vitepress/theme/SearchBox.vue b/docs/.vitepress/theme/SearchBox.vue
index 30bfb1cc8..f936bc015 100644
--- a/docs/.vitepress/theme/SearchBox.vue
+++ b/docs/.vitepress/theme/SearchBox.vue
@@ -74,6 +74,10 @@ function hide() {
  * them is not measurable. */
 const hits = computed(() => (entries.value.length ? search(entries.value, query.value, { limit: 500 }) : []));
 const groups = computed(() => grouped(hits.value));
+/* What answered, when it was not what was typed: a typo corrected or a word
+ * set aside (search-engine.js). The list says so above the results, and the
+ * marks in the rows are of the query that answered, not the one that did not. */
+const relaxedTo = computed(() => hits.value.relaxedTo || '');
 
 /* What is in the box, in the two numbers a reader recognises. Only once the
  * index has arrived - before that the box says what it is, not how much. */
@@ -185,7 +189,7 @@ onMounted(() => document.addEventListener('keydown', onKey));
 onUnmounted(() => document.removeEventListener('keydown', onKey));
 
 const indexOf = (hit) => rows.value.indexOf(hit);
-const parts = (text) => highlight(text, query.value);
+const parts = (text) => highlight(text, relaxedTo.value || query.value);
 </script>
 
 <template>
@@ -252,6 +256,9 @@ const parts = (text) => highlight(text, query.value);
           <p v-else-if="!rows.length" class="a2ui5-search-note">
             Nothing matches <strong>{{ query }}</strong>.
           </p>
+          <p v-else-if="relaxedTo" class="a2ui5-search-note">
+            Nothing matches <strong>{{ query }}</strong> — showing <strong>{{ relaxedTo }}</strong>.
+          </p>
 
           <div v-for="group in groups" :key="group.label" class="a2ui5-search-group">
             <div class="a2ui5-search-group-head">
diff --git a/docs/.vitepress/theme/search-engine.js b/docs/.vitepress/theme/search-engine.js
index 49b9bc7c5..f4725d194 100644
--- a/docs/.vitepress/theme/search-engine.js
+++ b/docs/.vitepress/theme/search-engine.js
@@ -35,6 +35,34 @@ const words = (s) => normalise(s).split(/[^\p{L}\p{N}._]+/u)
   .map((w) => w.replace(/^[._]+|[._]+$/g, ''))
   .filter(Boolean);
 
+/* WORDS THAT DECIDE NOTHING. "how do i install" is one question about one
+ * word, and the other three were being scored like it: `a` and `i` are a
+ * prefix of something in every entry, `to` and `do` in most, and each one
+ * earned the entry a title-hit's worth of points for a word nobody was asking
+ * about. The best answer to that query was Client API › check_on_init, and
+ * Installation was not in the first four. They are dropped from the matching
+ * as long as a real word is left - a query that is ONLY stop words ("is it",
+ * or a reader typing "a") still searches for what it says. The list is the
+ * short one: a word wrongly dropped is a search that finds nothing. */
+const STOP = new Set(('a an and are as at be by can do does for from has have how i in into is it its'
+  + ' my not of on or that the this to use using what when where which who will with you your').split(' '));
+
+/* One term as it is matched. The plural is the singular with an `s` on it -
+ * "tables" found 33 entries and "table" 202, and every one of the 169 it
+ * missed was about tables. The `s` comes off and the prefix match does the
+ * rest: "table" is the start of "tables". Not from `ss` (class, address), and
+ * not from anything short enough for the rule to be a guess. Only the letters
+ * a reader types are ever stemmed; a class name or a control name in the index
+ * is matched as it is. */
+const stem = (w) => (w.length > 3 && /^\p{L}+s$/u.test(w) && !w.endsWith('ss') ? w.slice(0, -1) : w);
+
+/** The words a query is matched by, in order, and the ones it was not. */
+export function queryTerms(query) {
+  const all = [...new Set(words(query))];
+  const kept = all.filter((w) => !STOP.has(w));
+  return (kept.length ? kept : all).map(stem);
+}
+
 /* How much a word found in each field is worth. A title hit beats everything:
  * the entries are short and their titles are what a reader is trying to
  * remember. `code` is the ABAP class name, which is either exactly what
@@ -45,14 +73,198 @@ function scoreField(value, term, weight) {
   if (!value) return 0;
   const hay = normalise(value);
   const at = hay.indexOf(term);
-  if (at < 0) return 0;
+  if (at < 0) return joined(hay, term, weight);
   /* Where the word sits decides how much of the weight it earns: the whole
    * field, the start of it, the start of any word in it, or somewhere inside
    * a longer word - `list` in `ActionListItem` is a real hit and a weaker one
-   * than `list` in `List Report`. */
+   * than `list` in `List Report`. A term of one or two letters - `ui`, `f4`,
+   * `v2` - counts at a word start only: inside a word it is a coincidence
+   * (`ui` is in `build`), not a hit. */
   if (hay === term) return weight * 3;
   if (at === 0) return weight * 2;
-  return /[^\p{L}\p{N}]/u.test(hay[at - 1] || '') ? weight : weight / 2;
+  if (/[^\p{L}\p{N}]/u.test(hay[at - 1] || '')) return weight;
+  if (term.length <= 2) {
+    const next = hay.indexOf(term, at + 1);
+    return next > 0 && /[^\p{L}\p{N}]/u.test(hay[next - 1]) ? weight : 0;
+  }
+  return weight / 2;
+}
+
+/* THE FIELD WITH ITS SPACES TAKEN OUT. The manual writes "Message Box" and
+ * the UI5 control is MessageBox; the reader types either. "messagebox" found
+ * the three samples whose title is spelled that way and not the chapter whose
+ * heading is two words - nor "selectdialog" a single page, nor "valuehelp" the
+ * Value Help chapter. A term that is in no word of the field is looked for in
+ * the field closed up, and earns what a word-start hit would: it is one, with
+ * the space on the other side of the keyboard. Five letters or more, so that
+ * `sap` cannot land across "is a p…". The other way round costs nothing:
+ * "select dialog" already finds "SelectDialog" by prefix. */
+function joined(hay, term, weight) {
+  if (term.length < 5 || !/\s/.test(hay)) return 0;
+  const tight = hay.replace(/[^\p{L}\p{N}._]+/gu, '');
+  const at = tight.indexOf(term);
+  if (at < 0) return 0;
+  if (tight === term) return weight * 3;
+  return at === 0 ? weight * 2 : weight / 2;
+}
+
+/* THE WORDS NEXT TO EACH OTHER. Two terms scored one at a time make "abap
+ * cloud" prefer Toolchain › abap-cleaner (a title hit on `abap`, a mention of
+ * `cloud`) over In a Nutshell › ABAP Cloud, which is the two words the reader
+ * typed, in that order, as a heading. A field that carries the phrase whole
+ * earns a bonus of twice its weight on top - three times when the phrase IS
+ * the field, which is the title the reader was remembering. The phrase is the
+ * query as typed ("drag and drop" is a title) and the query as matched ("drag
+ * drop"), whichever the field has. */
+function phraseBonus(value, phrases, weight) {
+  if (!value || !phrases.length) return 0;
+  const hay = normalise(value).replace(/\s+/g, ' ');
+  for (const p of phrases) {
+    if (hay === p) return weight * 3;
+    if (hay.includes(p)) return weight * 2;
+  }
+  return 0;
+}
+
+function phrasesOf(query, terms) {
+  if (terms.length < 2) return [];
+  const typed = words(query).join(' ');
+  const matched = terms.join(' ');
+  return typed === matched ? [typed] : [typed, matched];
+}
+
+/** One entry scored against the terms, or null if a term is in none of it. */
+function scoreEntry(e, terms, phrases) {
+  let total = 0;
+  /* Which heading matched, so the result can offer the SECTION rather than
+   * the page - the difference between "Cookbook: Tables" and the paragraph
+   * about sorting. */
+  let heading = null;
+  /* Did anything but the long tail match. A hit made of `terms` alone is a
+   * page that mentions the word somewhere, which is an answer and a weak one;
+   * the box can draw it as such. */
+  let strong = false;
+
+  for (const term of terms) {
+    const head = scoreField(e.title, term, FIELD.title)
+      + scoreField(e.code, term, FIELD.code)
+      + scoreField(e.text, term, FIELD.text);
+    let best = head + scoreField(e.terms, term, FIELD.terms) + scoreField(e.group, term, FIELD.group);
+    if (head) strong = true;
+
+    for (const [text, anchor] of e.headings || []) {
+      const s = scoreField(text, term, FIELD.heading);
+      if (!s) continue;
+      best += s;
+      strong = true;
+      if (!heading || s > heading.score) heading = { text, anchor, score: s };
+    }
+
+    if (!best) return null;
+    total += best;
+  }
+  if (!total) return null;
+
+  total += phraseBonus(e.title, phrases, FIELD.title) + phraseBonus(e.text, phrases, FIELD.text);
+  for (const [text, anchor] of e.headings || []) {
+    const s = phraseBonus(text, phrases, FIELD.heading);
+    if (!s) continue;
+    total += s;
+    if (!heading || s > heading.score) heading = { text, anchor, score: s };
+  }
+
+  /* A shorter entry that scored the same is the better answer: the words
+   * are a larger part of what it is about. */
+  return { entry: e, score: total - Math.min(4, (e.title || '').length / 40), heading, strong };
+}
+
+function rank(entries, terms, phrases, limit) {
+  const hits = [];
+  for (const e of entries) {
+    const hit = scoreEntry(e, terms, phrases);
+    if (hit) hits.push(hit);
+  }
+  hits.sort((a, b) => b.score - a.score || (a.entry.title || '').localeCompare(b.entry.title || ''));
+  return hits.slice(0, limit);
+}
+
+/* ── WHEN NOTHING MATCHES ──────────────────────────────────────────────────
+ *
+ * "tabel" answered with nothing, and so did "table sort backend" - one for a
+ * transposed pair of letters, the other for one word too many. Both are the
+ * box telling a reader who is one keystroke from the answer that the project
+ * has no page about it. So, and only when the terms as typed find nothing:
+ *
+ *   1. one word at a time is set aside, rarest first - the word that matched
+ *      the fewest entries is the one most likely to be the mistake - until
+ *      something answers;
+ *   2. a single word that still answers nothing is tried against every word in
+ *      every title, one edit away (a letter dropped, added, changed or two of
+ *      them swapped): "tabel" is "table", "dialgo" is "dialog".
+ *
+ * Whatever answered is reported on the result (`hits.relaxedTo`), because a
+ * list that silently answers a different question than the one typed is worse
+ * than an empty one. Titles only, for the spelling: the long tail of every
+ * page is six thousand words, and a near-miss of one of those is a different
+ * word more often than a typo of this one.
+ */
+
+/** How many entries carry the term anywhere - the measure of a term that is
+ *  probably the wrong one. */
+function reach(entries, term) {
+  let n = 0;
+  for (const e of entries) {
+    if (scoreEntry(e, [term], [])) n++;
+  }
+  return n;
+}
+
+const vocabularies = new WeakMap();
+function vocabulary(entries) {
+  let v = vocabularies.get(entries);
+  if (!v) {
+    v = new Set();
+    /* The titles' words and their singulars - "Tables" is a title, and the
+     * word a typo is one edit from is "table". */
+    for (const e of entries) for (const w of words(e.title)) if (w.length > 2) { v.add(w); v.add(stem(w)); }
+    vocabularies.set(entries, v);
+  }
+  return v;
+}
+
+/** Is `b` within one edit of `a` - a letter added, dropped or changed, or two
+ *  adjacent ones swapped. Bounded, so it costs nothing on the words that are
+ *  not close: most of the vocabulary is out on the length check alone. */
+function oneEditAway(a, b) {
+  if (a === b) return false;
+  const d = a.length - b.length;
+  if (d > 1 || d < -1) return false;
+  if (d) {
+    const [long, short] = d > 0 ? [a, b] : [b, a];
+    let i = 0;
+    while (i < short.length && long[i] === short[i]) i++;
+    return long.slice(i + 1) === short.slice(i);
+  }
+  let i = 0;
+  while (i < a.length && a[i] === b[i]) i++;
+  if (i === a.length) return false;
+  if (a.slice(i + 1) === b.slice(i + 1)) return true;
+  return a[i] === b[i + 1] && a[i + 1] === b[i] && a.slice(i + 2) === b.slice(i + 2);
+}
+
+function nearest(entries, term) {
+  if (term.length < 4) return null;
+  let best = null;
+  for (const w of vocabulary(entries)) {
+    if (!oneEditAway(term, w)) continue;
+    /* Of two candidates, the one that starts the way the reader started:
+     * "tabel" is one edit from "table" and one from "label", and nobody who
+     * typed a `t` meant an `l`. Then the one on more titles - the word this
+     * project actually uses. */
+    const n = reach(entries, w) + (w[0] === term[0] ? entries.length : 0);
+    if (!best || n > best.n) best = { w, n };
+  }
+  return best?.w ?? null;
 }
 
 /**
@@ -61,74 +273,73 @@ function scoreField(value, term, weight) {
  * Every term must be found somewhere in an entry, or the entry is out: typing
  * a second word is how a reader narrows a result list, and a search that
  * treats the words as alternatives grows the list instead, which reads as the
- * box ignoring what you typed.
+ * box ignoring what you typed. When that leaves nothing, the query is relaxed
+ * (above) and the list says so: `hits.relaxedTo` is the query that answered.
  */
 export function search(entries, query, { limit = 30 } = {}) {
-  const terms = words(query);
+  let terms = queryTerms(query);
   if (!terms.length) return [];
 
-  const hits = [];
-  for (const e of entries) {
-    let total = 0;
-    let missed = false;
-    /* Which heading matched, so the result can offer the SECTION rather than
-     * the page - the difference between "Cookbook: Tables" and the paragraph
-     * about sorting. */
-    let heading = null;
-
-    for (const term of terms) {
-      let best = scoreField(e.title, term, FIELD.title)
-        + scoreField(e.code, term, FIELD.code)
-        + scoreField(e.text, term, FIELD.text)
-        + scoreField(e.terms, term, FIELD.terms)
-        + scoreField(e.group, term, FIELD.group);
-
-      for (const [text, anchor] of e.headings || []) {
-        const s = scoreField(text, term, FIELD.heading);
-        if (!s) continue;
-        best += s;
-        if (!heading || s > heading.score) heading = { text, anchor, score: s };
-      }
-
-      if (!best) { missed = true; break; }
-      total += best;
-    }
-    if (missed || !total) continue;
+  let hits = rank(entries, terms, phrasesOf(query, terms), limit);
+  if (hits.length) return hits;
 
-    /* A shorter entry that scored the same is the better answer: the words
-     * are a larger part of what it is about. */
-    hits.push({ entry: e, score: total - Math.min(4, (e.title || '').length / 40), heading });
+  while (terms.length > 1) {
+    /* The word on the fewest entries goes; of two on as few, the one typed
+     * last - the reader's most recent word is the one most likely one too
+     * many. The rest keep their order, which is the reader's. */
+    let out = 0;
+    terms.forEach((t, i) => {
+      if (i && reach(entries, t) <= reach(entries, terms[out])) out = i;
+    });
+    terms = terms.filter((_, i) => i !== out);
+    hits = rank(entries, terms, [terms.join(' ')], limit);
+    if (hits.length) { hits.relaxedTo = terms.join(' '); return hits; }
   }
 
-  hits.sort((a, b) => b.score - a.score || (a.entry.title || '').localeCompare(b.entry.title || ''));
-  return hits.slice(0, limit);
+  const near = nearest(entries, terms[0]);
+  if (near) {
+    hits = rank(entries, [near], [], limit);
+    if (hits.length) hits.relaxedTo = near;
+  }
+  return hits;
 }
 
 /**
- * The hits, grouped the way the index declares its areas — Documentation
- * first, then each sample corpus — with at most `perGroup` in each, so one
- * corpus of 636 ports cannot bury the four pages that explain them.
+ * The hits, grouped the way the index declares its areas — with at most
+ * `perGroup` in each, so one corpus of 636 ports cannot bury the four pages
+ * that explain them.
+ *
+ * The groups come in the order of their best hit. The documentation used to
+ * come first whenever it was in the answer at all, and for "dialog" that put
+ * Value Help, Popup, PDF and Lock - four pages that mention the word - above
+ * forty-seven samples that are dialogs. It still leads whenever it has a real
+ * answer: a documentation hit within half of the best hit anywhere is offered
+ * first, because the reader who typed a word that is both a chapter and a
+ * control wants the explanation before the seven hundred examples of it. A
+ * page that only mentions the word comes after the samples that are about it.
  */
 export function grouped(hits, { perGroup = 8 } = {}) {
-  const order = [];
   const byGroup = new Map();
   /* How many a group HAS, beside how many it shows. A reader who typed
    * "table" and sees eight is looking at eight of two hundred and thirty-one,
    * and the difference between those two numbers is the difference between
    * "that is all there is" and "there is a whole shelf of this". */
-  const total = new Map();
   for (const hit of hits) {
     const key = hit.entry.area === 'docs' ? 'Documentation' : hit.entry.group;
-    if (!byGroup.has(key)) { byGroup.set(key, []); order.push(key); }
-    total.set(key, (total.get(key) ?? 0) + 1);
-    const rows = byGroup.get(key);
-    if (rows.length < perGroup) rows.push(hit);
+    let g = byGroup.get(key);
+    if (!g) { g = { label: key, hits: [], total: 0, best: hit.score }; byGroup.set(key, g); }
+    g.total++;
+    if (hit.score > g.best) g.best = hit.score;
+    if (g.hits.length < perGroup) g.hits.push(hit);
   }
-  /* Documentation first whenever it is in the answer at all. The reader who
-   * typed a word that is both a chapter and a control wants the explanation
-   * before the seven hundred examples of it. */
-  order.sort((a, b) => (a === 'Documentation' ? -1 : b === 'Documentation' ? 1 : 0));
-  return order.map((label) => ({ label, hits: byGroup.get(label), total: total.get(label) }));
+  const groups = [...byGroup.values()];
+  const top = groups.reduce((m, g) => Math.max(m, g.best), 0);
+  groups.sort((a, b) => {
+    if (a.label === 'Documentation' && a.best * 2 >= top) return -1;
+    if (b.label === 'Documentation' && b.best * 2 >= top) return 1;
+    return b.best - a.best;
+  });
+  return groups.map(({ label, hits: rows, total }) => ({ label, hits: rows, total }));
 }
 
 /** The index, fetched once. Callers await this on the first keystroke, never
@@ -146,7 +357,9 @@ export function loadIndex(url = INDEX_URL, { fetchFn = globalThis.fetch } = {})
  *  the list. Markup is the caller's business; three documents draw it three
  *  ways and none of them wants a string of HTML from here. */
 export function highlight(text, query) {
-  const terms = [...new Set(words(query))].sort((a, b) => b.length - a.length);
+  /* What is marked is what was MATCHED: the stop words are not, and "tables"
+   * typed marks "table" in "Tables" - which is the prefix the match was on. */
+  const terms = [...new Set(queryTerms(query))].sort((a, b) => b.length - a.length);
   const hay = text || '';
   if (!terms.length || !hay) return [[hay, false]];
   const marks = [];
diff --git a/scripts/lib/search-index.mjs b/scripts/lib/search-index.mjs
index 4c02f9a33..1df7a2658 100644
--- a/scripts/lib/search-index.mjs
+++ b/scripts/lib/search-index.mjs
@@ -144,6 +144,50 @@ export function trimTerms(entries, { ceiling = 1 / 3 } = {}) {
   return entries;
 }
 
+/* ── THE WORD THE READER HAS FOR IT ────────────────────────────────────────
+ *
+ * "readonly" found nothing, and every page about it says `editable`; "F4" is
+ * what half the readers call the value help. A pair is `[what is typed, what
+ * the entry says]`: an entry that says the second gets the first, added to
+ * `terms` - the long tail, at the long tail's weight, so the alias FINDS the
+ * entry and the ranking stays with the words it really carries. One direction
+ * each, on purpose: a reader who types "editable" has the project's word
+ * already. Data rather than code, so it is not a second thing the four bars
+ * have to carry a copy of.
+ *
+ * What is NOT here is the spelling with the space taken out - "messagebox"
+ * for "Message Box": the matcher looks for that itself (`joined( )` in
+ * theme/search-engine.js), at the weight of the field it is in.
+ */
+export const SYNONYMS = [
+  ['readonly', 'editable'],
+  ['f4', 'value help'],
+  ['msg', 'message'],
+  ['popup', 'dialog'],
+  ['dialog', 'popup'],
+  ['flp', 'launchpad'],
+  ['launchpad', 'flp'],
+  ['i18n', 'translation'],
+  ['translation', 'i18n'],
+  ['login', 'logon'],
+  ['logon', 'login'],
+  ['dropdown', 'select'],
+  ['excel', 'xlsx'],
+  ['xlsx', 'excel'],
+];
+
+/** The synonyms, added to every entry's `terms` that says the meaning and
+ *  not the alias. */
+export function enrich(entries, synonyms = SYNONYMS) {
+  for (const e of entries) {
+    const said = `${e.title} ${e.text} ${(e.headings || []).map((h) => h[0]).join(' ')} ${e.terms || ''}`.toLowerCase();
+    const has = (w) => new RegExp(`(^|[^\\p{L}\\p{N}_])${w}([^\\p{L}\\p{N}_]|$)`, 'u').test(said);
+    const extra = synonyms.filter(([alias, meaning]) => has(meaning) && !has(alias)).map(([alias]) => alias);
+    if (extra.length) e.terms = [e.terms, ...extra].filter(Boolean).join(' ');
+  }
+  return entries;
+}
+
 export async function buildIndex(root, { fetchFn = globalThis.fetch, log = () => {} } = {}) {
   const entries = trimTerms(docEntries());
   const areas = [{ area: 'docs', label: 'Documentation', count: entries.length }];
@@ -160,5 +204,5 @@ export async function buildIndex(root, { fetchFn = globalThis.fetch, log = () =>
     log(`  ${repo}: ${rows.length} sample(s) (${found.source})`);
   }
 
-  return { built: new Date().toISOString(), areas, entries };
+  return { built: new Date().toISOString(), areas, entries: enrich(entries) };
 }
diff --git a/test/search.test.mjs b/test/search.test.mjs
index 0e69109e7..1fdd6fc18 100644
--- a/test/search.test.mjs
+++ b/test/search.test.mjs
@@ -17,8 +17,8 @@ import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { sampleEntries, docEntries, trimTerms } from '../scripts/lib/search-index.mjs';
-import { search, grouped, highlight } from '../docs/.vitepress/theme/search-engine.js';
+import { sampleEntries, docEntries, trimTerms, enrich } from '../scripts/lib/search-index.mjs';
+import { search, grouped, highlight, queryTerms } from '../docs/.vitepress/theme/search-engine.js';
 import { terms, headings } from '../scripts/lib/pages.mjs';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -150,7 +150,127 @@ test('a second word narrows the answer rather than widening it', () => {
   const two = search(INDEX, 'popup message');
   assert.ok(two.length < one.length);
   assert.equal(two[0].entry.code, 'z2ui5_cl_smp_app_100');
-  assert.equal(search(INDEX, 'popup carousel zzz').length, 0, 'every word has to be somewhere');
+  /* Every word has to be somewhere - and when one is nowhere, the answer is
+   * for the words that are, and SAYS so (below). */
+  const three = search(INDEX, 'popup carousel zzz');
+  assert.equal(three.relaxedTo, 'popup carousel');
+  assert.ok(three.length);
+});
+
+/* ── THE WORDS THAT DECIDE NOTHING ─────────────────────────────────────────
+ *
+ * "how do i install" was answered with Client API › check_on_init, and
+ * Installation was not in the first four: `a` and `i` are a prefix of
+ * something in every entry, `to` and `do` in most, and each earned an entry a
+ * title-hit's worth of points for a word nobody was asking about. */
+const MANUAL = [
+  { area: 'docs', group: 'Getting Started', title: 'Installation', text: 'How to install it.', headings: [], terms: 'abapgit pull', url: '/docs/install.html' },
+  { area: 'docs', group: 'Resources', title: 'Client API', text: 'Every method, in one place.', headings: [['check_on_init', 'check-on-init'], ['Do I need this?', 'do-i-need-this']], terms: 'init', url: '/docs/api.html' },
+  { area: 'docs', group: 'Cookbook', title: 'In a Nutshell', text: 'What it is.', headings: [['ABAP Cloud', 'abap-cloud'], ['How It Works', 'how-it-works']], terms: 'cloud', url: '/docs/nutshell.html' },
+  { area: 'docs', group: 'Advanced', title: 'abapGit', text: 'Apps as artifacts.', headings: [['Toolchain', 'toolchain']], terms: 'cloud steampunk', url: '/docs/abapgit.html' },
+];
+
+test('a stop word is not a search term while a real word is there', () => {
+  assert.deepEqual(queryTerms('how do i install'), ['install']);
+  assert.deepEqual(queryTerms('drag and drop'), ['drag', 'drop']);
+  const [best] = search(MANUAL, 'how do i install');
+  assert.equal(best.entry.title, 'Installation');
+  /* A query that is nothing but stop words still asks what it says. */
+  assert.deepEqual(queryTerms('is it'), ['is', 'it']);
+  assert.ok(search(MANUAL, 'i').length, 'a single letter still searches');
+});
+
+test('a letter or two counts at the start of a word only', () => {
+  /* `ui` is in `build`, and that is a coincidence, not a hit. */
+  const [page] = [{ area: 'docs', title: 'Build', text: '', headings: [], terms: 'guide', url: '/x' }];
+  assert.equal(search([page], 'ui').length, 0);
+  assert.equal(search([{ ...page, title: 'UI5 Versions' }], 'ui').length, 1);
+});
+
+test('the words next to each other beat the words one at a time', () => {
+  /* "abap cloud" preferred abapGit (a title hit on `abap`, a mention of
+   * `cloud`) over the heading that IS the two words typed. */
+  const [best] = search(MANUAL, 'abap cloud');
+  assert.equal(best.entry.title, 'In a Nutshell');
+  assert.equal(best.heading.anchor, 'abap-cloud');
+});
+
+test('the plural finds what the singular finds', () => {
+  const rows = [
+    { area: 'samples', group: 'Controls', title: 'Table - Editable', text: '', code: 'z2ui5_cl_smpc_app_570', terms: 'table', url: '/a' },
+    { area: 'docs', group: 'Cookbook', title: 'Tables', text: '', headings: [], terms: '', url: '/b' },
+  ];
+  assert.equal(search(rows, 'tables').length, 2, '"tables" found 33 entries and "table" 202, and all 169 were about tables');
+  assert.deepEqual(queryTerms('class address'), ['class', 'address'], 'a double s is not a plural');
+  assert.deepEqual(queryTerms('z2ui5_cl_smpc_apps'), ['z2ui5_cl_smpc_apps'], 'only letters a reader types are stemmed');
+});
+
+test('a compound finds the two words it is made of', () => {
+  const rows = [
+    { area: 'docs', group: 'Cookbook', title: 'Message', text: '', headings: [['Message Box', 'message-box'], ['Message Toast', 'message-toast']], terms: '', url: '/m' },
+    { area: 'samples', group: 'Controls', title: 'Select Dialog', text: '', code: 'z2ui5_cl_smpc_app_103', terms: '', url: '/s' },
+    { area: 'samples', group: 'Controls', title: 'Message Box', text: '', code: 'z2ui5_cl_smpc_app_278', terms: '', url: '/t' },
+  ];
+  const [box, page] = search(rows, 'messagebox');
+  assert.equal(box.entry.title, 'Message Box', 'the title that IS the word, closed up, first');
+  assert.equal(page.entry.title, 'Message');
+  assert.equal(page.heading.anchor, 'message-box', 'and the heading, with its anchor');
+  assert.equal(search(rows, 'selectdialog')[0].entry.title, 'Select Dialog');
+  /* Three or four letters across a space are a coincidence - "sap" is in
+   * "is a p…" - and are not looked for. */
+  assert.equal(search([{ area: 'docs', title: 'Is a Page', text: '', headings: [], terms: '', url: '/p' }], 'sap').length, 0);
+});
+
+test('a typo is corrected against the titles, and the list says so', () => {
+  const rows = [
+    { area: 'samples', group: 'Controls', title: 'Label Properties', text: '', code: 'z2ui5_cl_smpc_app_058', terms: 'label', url: '/l' },
+    { area: 'docs', group: 'Cookbook', title: 'Tables', text: '', headings: [], terms: '', url: '/t' },
+  ];
+  /* "tabel" is one edit from "table" and one from "label"; nobody who typed a
+   * `t` meant an `l`. */
+  const hits = search(rows, 'tabel');
+  assert.equal(hits.relaxedTo, 'table');
+  assert.equal(hits[0].entry.title, 'Tables');
+  assert.equal(search(rows, 'dialgo').length, 0, 'nothing within one edit is an empty list, not a guess');
+  assert.equal(search(rows, 'tab').relaxedTo, undefined, 'a hit as typed is never second-guessed');
+  assert.equal(search(rows, 'zzzz').relaxedTo, undefined);
+});
+
+test('the word that matched nothing is the one set aside', () => {
+  const hits = search(MANUAL, 'install steampunk');
+  assert.equal(hits.length, 0 + 1, 'both words are somewhere, on different pages: nothing matches both');
+  assert.equal(hits.relaxedTo, 'install', 'the rarer word goes first - it is the one most likely wrong');
+});
+
+test('a page that only mentions the word comes after the samples that are about it', () => {
+  /* "dialog": Value Help, Popup, PDF and Lock - four pages that mention the
+   * word - stood above forty-seven samples that are dialogs. */
+  const rows = [
+    { area: 'docs', group: 'Cookbook', title: 'PDF', text: '', headings: [], terms: 'dialog', url: '/pdf' },
+    { area: 'samples', group: 'Controls', title: 'Dialog - Fullscreen', text: '', code: 'z2ui5_cl_smpc_app_274', terms: '', url: '/d' },
+  ];
+  const groups = grouped(search(rows, 'dialog'));
+  assert.deepEqual(groups.map((g) => g.label), ['Controls', 'Documentation']);
+  assert.equal(groups[1].hits[0].strong, false, 'and the row knows it is a mention');
+  /* But a real answer in the manual still leads - the chapter before the
+   * seven hundred examples. */
+  rows[0].headings = [['Print Dialog', 'print-dialog']];
+  assert.equal(grouped(search(rows, 'dialog'))[0].label, 'Documentation');
+});
+
+test('a synonym finds the entry that says it the other way', () => {
+  const rows = [
+    { area: 'docs', title: 'Input', text: 'An editable field.', headings: [], terms: 'field' },
+    { area: 'docs', title: 'Value Help', text: '', headings: [], terms: 'ddic' },
+    { area: 'docs', title: 'Editable', text: '', headings: [], terms: 'readonly' },
+  ];
+  enrich(rows);
+  assert.match(rows[0].terms, /\breadonly\b/);
+  assert.match(rows[1].terms, /\bf4\b/);
+  assert.equal(rows[2].terms, 'readonly', 'not added twice');
+  /* And it works end to end: "readonly" found nothing, and every page about
+   * it says `editable`. */
+  assert.equal(search(rows, 'readonly').length, 2);
 });
 
 test('a heading hit says which heading, so the link can carry its anchor', () => {
@@ -186,8 +306,10 @@ test('an empty query is not a search for everything', () => {
   assert.deepEqual(search(INDEX, '   '), []);
 });
 
-test('the highlight marks what was typed and nothing else', () => {
+test('the highlight marks what was matched and nothing else', () => {
   assert.deepEqual(highlight('Popups and popovers', 'popup'), [['Popup', true], ['s and popovers', false]]);
+  /* Not the stop word, and the plural as the prefix it was matched on. */
+  assert.deepEqual(highlight('Tables and rows', 'tables and'), [['Table', true], ['s and rows', false]]);
   assert.deepEqual(highlight('Carousel', 'zzz'), [['Carousel', false]]);
   assert.deepEqual(highlight('', 'popup'), [['', false]]);
   /* Two terms that overlap must not produce overlapping runs, or the row is

From 35c57fba70da0603537faf794798ed587a637bbf Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 11 Sep 2026 12:20:41 +0000
Subject: [PATCH 2/2] Home: centre the GitHub, LinkedIn and Sponsor row under
 the tiles

Three links at the left edge under three boxes that span the width read
as a fourth thing that did not get finished. In the published stylesheet
and in VitePress's copy of the rule.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017JMbwNQAZ65yn4GrgRdvsi
---
 docs/.vitepress/theme/style.css | 1 +
 scripts/site-css/docs.css       | 4 ++++
 2 files changed, 5 insertions(+)

diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css
index e11a43fa4..7f5c69d83 100644
--- a/docs/.vitepress/theme/style.css
+++ b/docs/.vitepress/theme/style.css
@@ -1286,6 +1286,7 @@
   display: flex;
   flex-wrap: wrap;
   gap: 8px 28px;
+  justify-content: center;
   margin: 32px 0 0;
   font-size: 14px;
   line-height: 22px;
diff --git a/scripts/site-css/docs.css b/scripts/site-css/docs.css
index af6a884ab..28cc68160 100644
--- a/scripts/site-css/docs.css
+++ b/scripts/site-css/docs.css
@@ -867,6 +867,10 @@ html { scroll-padding-top: 62px; }
  * and a rule under a row of boxes is a second edge on the same edge. */
 .vp-doc .a2ui5-links {
   display: flex; flex-wrap: wrap; gap: 8px 28px;
+  /* Centred, like the tiles' row above it is: three links at the left edge
+     under three boxes that span the width read as a fourth thing that did
+     not get finished. */
+  justify-content: center;
   /* Well clear of the tiles above, and close to the rule under it: the row
      belongs to the page's foot, not to the tiles. */
   margin: 56px 0 0;