fix(docs): teach composition, not .extend — and stop depending on which FieldSchema declaration you get

CI rejected the first fix: `FieldSchema.in.extend(…)` passed locally and failed
with "Property 'in' does not exist on type 'ZodObject<…>'" on the runner. The two
builds emit DIFFERENT declarations for the same source — locally
z.ZodPipe<z.ZodObject<…>>, in CI a plain z.ZodObject.

The runtime is unambiguous: after `rm -rf dist && pnpm build`, FieldSchema is a
`bound ZodPipe` with `.extend === undefined` and `.in` a ZodObject. So CI's
declaration contradicts the value it describes — `.extend()` type-checks there and
throws at runtime. That is a real spec-side divergence (likely inference
instability in the DTS bundling of these very large zod types) and deserves its
own investigation; it is not something this docs fix should paper over.

So the checked example now uses only `.parse()`: parse with FieldSchema, validate
the additions alongside it. Correct under either declaration, verified to run, and
better advice anyway — composition keeps the transform, which `.extend()` discards.
`.in.extend()` stays in prose as the merged-schema route with that caveat.

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

Author: claude

.changeset/docs-fieldschema-extend-rot.md

@@ -20,10 +20,21 @@ time, which makes it a **`ZodPipe`, not a `ZodObject`** — `.extend` is `undefi
 on it (verified against the built package). Anyone following the FAQ got a
 `not a function` throw. The example also used `z` without importing it.
 
-Rewritten to `FieldSchema.in.extend({ … })` — `.in` is the input object the pipe
-wraps — verified to parse, and marked so the gate holds it. It also now names why
-(the same applies to `ObjectSchema` / `ActionSchema`) and warns that the extended
-schema no longer runs the transform.
+Rewritten to **compose** — parse with `FieldSchema`, validate your additions
+alongside it — verified to both type-check and run. `.in.extend()` is mentioned in
+prose as the merged-schema route, with the caveat that it skips the transform.
+
+**A divergence worth knowing about, found while fixing this.** The first fix used
+`FieldSchema.in.extend(…)` in the checked block. It passed locally and failed in
+CI with `Property 'in' does not exist on type 'ZodObject<…>'` — the two builds
+emit **different declarations for the same source**: locally
+`z.ZodPipe<z.ZodObject<…>>`, in CI a plain `z.ZodObject`. The runtime is
+unambiguous (`bound ZodPipe`, `.extend === undefined`, verified after a clean
+`rm -rf dist && pnpm build`), so **CI's declaration contradicts the value it
+describes** — `.extend()` type-checks there and throws at runtime. Probably
+inference instability in the DTS bundling of these very large zod types; worth its
+own investigation. The example now uses only `.parse()`, so it is correct under
+either declaration and the doc is not hostage to which one you get.
 
 **The sweep's method is recorded in the gate's docstring**, because two traps make
 a naive pass report a confident "nothing found":

content/docs/deployment/troubleshooting.mdx

@@ -359,30 +359,34 @@ Yes. All schemas work with plain JavaScript. You lose compile-time type checking
 
 ### How do I extend a built-in schema?
 
-Use Zod's `.extend()` — but reach the **object** first. Several built-in schemas
-(`FieldSchema`, `ObjectSchema`, `ActionSchema`, …) carry a `.transform()` that
-lowers author-facing sugar at parse time, which makes them a `ZodPipe` rather
-than a `ZodObject`. `.extend()` does not exist on a pipe; `.in` is the input
-object it wraps:
+**Not with `.extend()` on the schema itself.** Several built-in schemas —
+`FieldSchema`, `ObjectSchema`, `ActionSchema` — carry a `.transform()` that lowers
+author-facing sugar at parse time, which makes the exported value a **`ZodPipe`,
+not a `ZodObject`**. `FieldSchema.extend` is `undefined`, so calling it throws
+`is not a function`.
+
+Compose instead: parse with the built-in schema, and validate your additions
+alongside it. This keeps the transform running, which `.extend()` would discard.
 
 {/* os:check */}
 ```typescript
 import { z } from 'zod';
 import { FieldSchema } from '@objectstack/spec/data';
 
-// `.in` — the ZodObject the pipe wraps. Calling `.extend()` on FieldSchema
-// itself throws "not a function": it is a ZodPipe.
-const CustomFieldSchema = FieldSchema.in.extend({
-  customProperty: z.string().optional(),
-});
+const CustomProps = z.object({ customProperty: z.string().optional() });
+
+function parseCustomField(input: unknown) {
+  return { ...FieldSchema.parse(input), ...CustomProps.parse(input) };
+}
 
-CustomFieldSchema.parse({ name: 'code', type: 'text', customProperty: 'x' });
+parseCustomField({ name: 'code', type: 'text', customProperty: 'x' });
 ```
 
-Note the extended schema no longer runs the transform, so author-facing sugar
-that the pipe would have lowered stays raw. When you only need to *validate* an
-extra key alongside the real parse, prefer parsing with the built-in schema and
-checking your own additions separately.
+If you genuinely need one merged schema object, `FieldSchema.in` is the
+`ZodObject` the pipe wraps, so `FieldSchema.in.extend({ … })` builds one — but
+the result **skips the transform**, so author-facing sugar the pipe would have
+lowered stays raw. Prefer the composition above unless you specifically want the
+untransformed shape.
 
 ### Where are the JSON Schemas for IDE autocomplete?