docs(search)+seed(showcase): document pinyin recall and make it demonstrable out of the box (#3034)

Follow-ups to the merged pinyin-search feature (ADR-0097, PR #3027):

- environment-variables.mdx: new "Search" section documenting OS_SEARCH_PINYIN_ENABLED (locale-derived default, explicit override, what it gates).
- queries.mdx: "Pinyin recall" subsection under Full-Text Search.
- showcase seed: CJK-named account (华宁科技) and contacts (张伟/王芳/李雷) so the auto-enabled pinyin search is demonstrable out of the box.

Verified on a fresh showcase boot: $search=zhangwei/zw/wf/huaning/hnkj all recall the seeded CJK records.

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

@@ -367,6 +367,19 @@ Only `query` and `fields` are implemented. The engine expands `search` into a dr
 are always AND-ed regardless of `operator`.
 </Callout>
 
+### Pinyin recall (Chinese deployments)
+
+When pinyin search is enabled (`OS_SEARCH_PINYIN_ENABLED` — auto-on when the stack's
+i18n config lists any `zh-*` locale, see
+[Environment Variables → Search](/docs/deployment/environment-variables#search)), records
+with CJK names are also found by typing their **full pinyin** or **initials**: searching
+`zhangwei` or `zw` matches a record named `张伟`, alongside the normal CJK and latin
+matching. This is transparent to queries and clients — the platform maintains a hidden
+`__search` companion column derived from each object's display/name field and ORs it into
+the expanded filter; `fields` semantics, `searchableFields`, and drivers are unchanged
+(ADR-0097). Relevance ranking and typo tolerance remain Tier-2 (native FTS) and are not
+part of this.
+
 ---
 
 ## Window Functions

content/docs/deployment/environment-variables.mdx

@@ -235,6 +235,26 @@ OS_MCP_SERVER_ENABLED=true os start     # additionally auto-start the stdio tran
 
 ---
 
+## Search
+
+Pinyin recall for `$search` (ADR-0097): with the switch on, every object's
+display/name field gets a hidden, platform-maintained companion column storing
+full pinyin + initials ("张伟" → "zhangwei zw"), so lookup pickers, list
+quick-search and ⌘K match `zhangwei` / `zw` against CJK names — transparently,
+with no client or object changes.
+
+```bash
+os start                                  # auto-on when the stack's i18n config lists any zh-* locale
+OS_SEARCH_PINYIN_ENABLED=true os start    # force on regardless of locales
+OS_SEARCH_PINYIN_ENABLED=false os start   # force off (e.g. a zh-locale stack that doesn't want the extra column)
+```
+
+| Variable | Type | Default | Description |
+|:---|:---|:---|:---|
+| `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. |
+
+---
+
 ## Marketplace & Metadata
 
 | Variable | Type | Default | Description |

examples/app-showcase/src/data/seed/index.ts

@@ -47,6 +47,10 @@ const accounts = defineSeed(Account, {
     { name: 'Initech', industry: 'finance', annual_revenue: 5_400_000, website: 'https://initech.example', status: 'active', hq: { lat: 30.2672, lng: -97.7431 }, tax_id: '74-2233110', billing_email: 'ap@initech.example' },
     { name: 'Globex', industry: 'technology', annual_revenue: 42_000_000, website: 'https://globex.example', status: 'active', hq: { lat: 34.0522, lng: -118.2437 }, tax_id: '95-8841200', billing_email: 'billing@globex.example' },
     { name: 'Stark Industries', industry: 'technology', annual_revenue: 180_000_000, website: 'https://stark.example', status: 'active', hq: { lat: 40.7580, lng: -73.9855 }, tax_id: '13-5567421', billing_email: 'ap@stark.example' },
+    // CJK-named account so pinyin search recall (#2486) is demonstrable out of
+    // the box: with the zh-CN locale configured, `$search=huaning` / `hnkj`
+    // must find 华宁科技 in the record picker and list quick-search.
+    { name: '华宁科技', industry: 'technology', annual_revenue: 36_000_000, website: 'https://huaning.example', status: 'active', hq: { lat: 31.2304, lng: 121.4737 }, tax_id: '91-3100001', billing_email: 'billing@huaning.example' },
     { name: 'Wayne Enterprises', industry: 'finance', annual_revenue: 210_000_000, website: 'https://wayne.example', status: 'active', hq: { lat: 40.7128, lng: -74.0060 }, tax_id: '22-9087733', billing_email: 'billing@wayne.example' },
     { name: 'Acme Retail', industry: 'retail', annual_revenue: 3_200_000, website: 'https://acme.example', status: 'prospect', hq: { lat: 41.8781, lng: -87.6298 }, tax_id: '36-4471209', billing_email: 'accounts@acme.example' },
     { name: 'Soylent Foods', industry: 'healthcare', annual_revenue: 9_900_000, website: 'https://soylent.example', status: 'prospect', hq: { lat: 37.3382, lng: -121.8863 }, tax_id: '77-1029384', billing_email: 'ap@soylent.example' },
@@ -69,6 +73,12 @@ const contacts = defineSeed(Contact, {
     { name: 'Cara Ito', email: 'cara@contoso.example', phone: '+1 555 020 1111', company: 'Contoso', title: 'IT Director', account: 'Contoso', stage: 'new' },
     { name: 'Carl Fox', email: 'carl@contoso.example', phone: '+1 555 020 2222', company: 'Contoso', title: 'Data Lead', account: 'Contoso', stage: 'qualified' },
     { name: 'Faye Lin', email: 'faye@fabrikam.example', phone: '+1 555 030 1111', company: 'Fabrikam', title: 'Compliance Officer', account: 'Fabrikam', stage: 'new' },
+    // CJK-named contacts so pinyin search recall (#2486) is demonstrable out
+    // of the box: `$search=zhangwei` (full pinyin), `zw` (initials) and `张`
+    // (CJK) must all find 张伟 in the people picker / list quick-search.
+    { name: '张伟', email: 'zhangwei@huaning.example', phone: '+86 21 5550 1111', company: '华宁科技', title: 'Engineering Manager', account: '华宁科技', stage: 'qualified' },
+    { name: '王芳', email: 'wangfang@huaning.example', phone: '+86 21 5550 2222', company: '华宁科技', title: 'Procurement Director', account: '华宁科技', stage: 'working' },
+    { name: '李雷', email: 'lilei@huaning.example', phone: '+86 21 5550 3333', company: '华宁科技', title: 'IT Specialist', account: '华宁科技', stage: 'new' },
   ],
 });