diff --git a/content/docs/data-modeling/queries.mdx b/content/docs/data-modeling/queries.mdx
index 58a2ce99b..67f4f71fa 100644
--- a/content/docs/data-modeling/queries.mdx
+++ b/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
diff --git a/content/docs/deployment/environment-variables.mdx b/content/docs/deployment/environment-variables.mdx
index 5b14df490..c0e83e4af 100644
--- a/content/docs/deployment/environment-variables.mdx
+++ b/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