docs(plugin-ai): compile the README's snippets against the shipped surface (#8180)

Burns down the `packages/plugin-ai/README.md` entry in this gate's
`UNGATED_DOCS` ledger (objectui#5174, batch 27). The entry is deleted
rather than rewritten because the page now reads zero.

The page taught an API the components do not have. All three exported
components take a single `schema` prop plus callbacks
(`AIFormAssistProps`, `AIRecommendationsProps`, `NLQueryInputProps`),
while every example passed flat props -- `formId=`, `objectName=`,
`fields=`, `maxResults=`, `layout=`. The README was wrong against
components that are right, so the README is what moves: one typed
binding per example, annotated with the schema type `@object-ui/types`
exports, passed as `schema={...}`, with `declare const` stand-ins for
the two ambient names the page never defined.

Three of the four `tsx` fences were bare JSX with no import line, so
the undefined component name short-circuited the prop check on the
same element: the ledger's `TS2322x3` was the visible half of six.
The three latent ones surface only once the names resolve, and this
diff pays down all six.

No `packages/plugin-ai/src/**` or `packages/types/src/**` edit, no
widened type, no fragment marker, no loosened gate. The gate file's
strictness region is byte-identical.


Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr

Co-authored-by: Claude <noreply@anthropic.com>

Author: baozhoutao

packages/plugin-ai/README.md

@@ -22,92 +22,147 @@ npm install @object-ui/plugin-ai
 
 ## Quick Start
 
+Every component in this package takes exactly one schema object plus optional
+callbacks — `schema` carries the configuration, the callbacks carry the
+behaviour. The schema types ship from `@object-ui/types`.
+
 ```tsx
 import { AIFormAssist, AIRecommendations, NLQueryInput } from '@object-ui/plugin-ai';
+import type {
+  AIFormAssistSchema,
+  AIRecommendationItem,
+  AIRecommendationsSchema,
+  NLQuerySchema,
+} from '@object-ui/types';
+
+declare const recommendationsData: AIRecommendationItem[];
+
+const contactAssist: AIFormAssistSchema = {
+  type: 'ai-form-assist',
+  formId: 'new-contact',
+  objectName: 'Contact',
+  fields: ['name', 'email', 'company'],
+  showConfidence: true,
+};
 
 function SmartForm() {
   return (
     <div>
-      <AIFormAssist
-        formId="new-contact"
-        objectName="Contact"
-        fields={['name', 'email', 'company']}
-        showConfidence
-      />
+      <AIFormAssist schema={contactAssist} />
     </div>
   );
 }
 
+const productPicks: AIRecommendationsSchema = {
+  type: 'ai-recommendations',
+  objectName: 'Product',
+  maxResults: 5,
+  layout: 'grid',
+  recommendations: recommendationsData,
+};
+
 function RecommendationsPanel() {
-  return (
-    <AIRecommendations
-      objectName="Product"
-      maxResults={5}
-      layout="grid"
-      recommendations={recommendationsData}
-    />
-  );
+  return <AIRecommendations schema={productPicks} />;
 }
 
+const orderSearch: NLQuerySchema = {
+  type: 'nl-query',
+  objectName: 'Order',
+  placeholder: 'Ask a question about your orders...',
+  suggestions: ['Show orders from last week', 'Top customers by revenue'],
+};
+
 function SearchBar() {
-  return (
-    <NLQueryInput
-      objectName="Order"
-      placeholder="Ask a question about your orders..."
-      suggestions={['Show orders from last week', 'Top customers by revenue']}
-    />
-  );
+  return <NLQueryInput schema={orderSearch} />;
 }
 ```
 
 ## API
 
 ### AIFormAssist
 
-AI-powered form field suggestions and auto-fill:
+AI-powered form field suggestions and auto-fill. Props: `schema`, plus the
+optional `onApply` and `onRefresh` callbacks.
 
 ```tsx
-<AIFormAssist
-  formId="new-lead"
-  objectName="Lead"
-  fields={['name', 'email', 'phone']}
-  autoFill={false}
-  showConfidence
-  showReasoning={false}
-/>
+import { AIFormAssist } from '@object-ui/plugin-ai';
+import type { AIFormAssistSchema } from '@object-ui/types';
+
+const leadAssist: AIFormAssistSchema = {
+  type: 'ai-form-assist',
+  formId: 'new-lead',
+  objectName: 'Lead',
+  fields: ['name', 'email', 'phone'],
+  autoFill: false,
+  showConfidence: true,
+  showReasoning: false,
+};
+
+const assistPanel = (
+  <AIFormAssist
+    schema={leadAssist}
+    onApply={(suggestion) => console.log(suggestion.fieldName, suggestion.value)}
+  />
+);
 ```
 
 ### AIRecommendations
 
-Display AI-generated recommendations:
+Display AI-generated recommendations. Props: `schema`, plus the optional
+`onSelect` and `onDismiss` callbacks.
 
 ```tsx
-<AIRecommendations
-  objectName="Product"
-  recommendations={data}
-  maxResults={10}
-  layout="list"       // 'list' | 'grid' | 'carousel'
-  showScores={false}
-  emptyMessage="No recommendations available"
-/>
+import { AIRecommendations } from '@object-ui/plugin-ai';
+import type { AIRecommendationItem, AIRecommendationsSchema } from '@object-ui/types';
+
+declare const data: AIRecommendationItem[];
+
+const productPicks: AIRecommendationsSchema = {
+  type: 'ai-recommendations',
+  objectName: 'Product',
+  recommendations: data,
+  maxResults: 10,
+  layout: 'list', // 'list' | 'grid' | 'carousel'
+  showScores: false,
+  emptyMessage: 'No recommendations available',
+};
+
+const panel = (
+  <AIRecommendations schema={productPicks} onSelect={(item) => console.log(item.id)} />
+);
 ```
 
 ### NLQueryInput
 
-Natural language query input for data exploration:
+Natural language query input for data exploration. Props: `schema`, plus the
+optional `onSubmit` callback.
 
 ```tsx
-<NLQueryInput
-  objectName="Order"
-  placeholder="Ask anything..."
-  suggestions={['Recent orders', 'Revenue by month']}
-  showHistory={false}
-/>
+import { NLQueryInput } from '@object-ui/plugin-ai';
+import type { NLQuerySchema } from '@object-ui/types';
+
+const orderSearch: NLQuerySchema = {
+  type: 'nl-query',
+  objectName: 'Order',
+  placeholder: 'Ask anything...',
+  suggestions: ['Recent orders', 'Revenue by month'],
+  showHistory: false,
+};
+
+const searchBar = <NLQueryInput schema={orderSearch} onSubmit={(query) => console.log(query)} />;
 ```
 
-### Schema-Driven Usage
+## Schema-Driven Usage
+
+Components auto-register with `ComponentRegistry` on import. The registry key is
+the schema's `type`, and it is **not** always the component name — `NLQueryInput`
+registers as `nl-query`:
 
-Components auto-register with `ComponentRegistry`:
+| Component | Registry `type` | Schema type |
+|---|---|---|
+| `AIFormAssist` | `ai-form-assist` | `AIFormAssistSchema` |
+| `AIRecommendations` | `ai-recommendations` | `AIRecommendationsSchema` |
+| `NLQueryInput` | `nl-query` | `NLQuerySchema` |
 
 ```json
 {

scripts/check-doc-snippet-types.mjs

@@ -779,8 +779,6 @@ const UNGATED_DOCS = {
     '1 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies; 15 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2741x1 — candidate real defects, un-triaged',
   'packages/fields/README.md':
     '2 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; 1 unresolved-module diagnostic(s)',
-  'packages/plugin-ai/README.md':
-    '5 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2322x3 — candidate real defects, un-triaged',
   'packages/plugin-charts/README.md':
     '6 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies',
   'packages/plugin-chatbot/README.md':