docs(search): pinyin recall — spell out sys_user/picker coverage and existing-row backfill (#3057)

Answers the two questions the merged docs left open (#2486): whether the people picker (sys_user) is covered automatically (yes — verified against a live showcase: sign-up, admin rename, and engine writes are all searchable immediately), and how pre-existing rows get their companion value (automatic paged backfill on the first boot after the switch turns on; rebuildSearchCompanion for hook-bypassing bulk imports).

Refs #2486

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMugRriiNv3nsnmLczfhuY

Author: os-zhuang

content/docs/data-modeling/queries.mdx

@@ -380,6 +380,17 @@ the expanded filter; `fields` semantics, `searchableFields`, and drivers are unc
 (ADR-0097). Relevance ranking and typo tolerance remain Tier-2 (native FTS) and are not
 part of this.
 
+**Coverage** — every object with a resolvable display/name field gets the companion,
+**including `sys_user`**: the people picker (which sends a plain `$search` against
+`sys_user`) finds users by pinyin with zero per-object or per-field configuration. Users
+created through any write path — sign-up, admin rename, engine writes — are searchable
+immediately.
+
+**Pre-existing rows** are reconciled automatically: the first boot after the switch turns
+on runs a paged, idempotent backfill over every object that carries the companion column.
+For bulk imports that bypassed write hooks at runtime, `rebuildSearchCompanion` (exported
+by `@objectstack/plugin-pinyin-search`) recomputes the column on demand.
+
 ---
 
 ## Window Functions

content/docs/deployment/environment-variables.mdx

@@ -253,6 +253,13 @@ OS_SEARCH_PINYIN_ENABLED=false os start   # force off (e.g. a zh-locale stack th
 |:---|:---|:---|:---|
 | `OS_SEARCH_PINYIN_ENABLED` | boolean | locale-derived | Pinyin search recall. When unset, the default derives from the stack's configured locales (`i18n.defaultLocale` / `supportedLocales` / `fallbackLocale`): any `zh-*` locale turns it on; an explicit value always wins. Gates both the compile-time `__search` companion column and the `plugin-pinyin-search` populate hooks, so there is no half-state. Off ⇒ no extra column, and `pinyin-pro` is never loaded. |
 
+Coverage includes `sys_user` — the people picker finds users by pinyin with no
+per-object configuration. Rows that predate the switch are backfilled automatically
+on the first boot after it turns on (paged, idempotent); for runtime bulk imports
+that bypassed write hooks, `rebuildSearchCompanion` (from
+`@objectstack/plugin-pinyin-search`) recomputes the column on demand. See
+[Queries → Pinyin recall](/docs/data-modeling/queries#pinyin-recall-chinese-deployments).
+
 ---
 
 ## Marketplace & Metadata