**hero.actions.1.variant**: Invalid option: expected one of "primary"|"secondary"|"minimal"

[miichom]

What version of starlight are you using?

0.39.2

What version of astro are you using?

6.3.1

What package manager are you using?

npm

What operating system are you using?

Windows

What browser are you using?

Firefox

Describe the Bug

In the starlight docs, it mentions docsSchema() can modify fields, however it is unable to modify z.enum fields The likely cause is from how ZodIntersection are treated.

Why this happens

The Zod documentation explicitly notes that intersections (a logical "AND") produce a ZodIntersection instance rather than a ZodObject.

From the Zod v4 docs:

When merging object schemas, prefer A.extend(B) over intersections. Using .extend() will give you a new object schema, whereas z.intersection(A, B) returns a ZodIntersection instance which lacks common object methods like pick and omit.

This limitation also affects any tooling that expects to operate on a ZodObject, including schema‑amending utilities like docsSchema().

Current workarounds

1. Introduce an additional field to represent the enum option outside the intersection, or
2. To Rebuild the full schema.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-kzc2ffxo?file=src%2Fcontent.config.ts

Participation

• I am willing to submit a pull request for this issue.