Consulted for every schema ZodToOpenApi.transform is about to convert — the top-level one AND every sub-schema it recurses into.

Returning undefined means "transform normally". Returning a schema object REPLACES the transform for that node, which is how a document generator substitutes a $ref to a reusable component without the transformer knowing anything about components.

On the zod v4 path the hook is bridged onto zod's own override callback, which carries the original zod node — so the hook always receives the real Zod schema about to be transformed, on both majors.