@writedocs/generator 0.4.7 → 0.4.9

package/src/lib/config-schema.ts

@@ -1,1437 +1,1574 @@
-// O schema do writedocs.json, e nada alem disso.
-//
-// Este arquivo era as primeiras 875 linhas do config.ts (que continua
-// reexportando tudo daqui, entao nada que importa de './config.js' mudou). A
-// separacao existe por um motivo concreto: o config.ts importa node:fs,
-// node:path e gray-matter no topo pras funcoes que leem o disco, e o
-// package.json passou a exportar './config-schema' pra que a plataforma
-// (writedocs-application) possa importar o schema DE VERDADE - o mesmo que o
-// build usa - em vez de manter uma copia que diverge em algumas semanas. Um
-// Worker da Cloudflare nao consegue importar um modulo que traz node:fs junto.
-//
-// Por isso a unica dependencia aqui e o zod. Nada neste arquivo pode passar a
-// tocar o sistema de arquivos: se precisar de fs/path, o lugar e o config.ts.
-//
-// ESTE arquivo e a fonte de verdade, mas NAO e o que o pacote publica: o script
-// `prepare` (package.json) transpila ele pra ./config-schema.js, e e o `.js` que
-// o `exports` e o bin/writedocs.js apontam. Sem isso o `writedocs validate`
-// quebra pra quem instala o pacote - o Node recusa type stripping sob
-// node_modules. Editou aqui, rode `npm run build:schema` (ou qualquer
-// `npm install`) antes de testar o caminho da CLI ou da plataforma.
-//
-// (`zod` e nao `astro/zod`: as duas especificacoes resolvem pra mesma instalacao
-// - node_modules/zod 4.4.3, que e o que astro@7.2.2 tambem pede via `^4.3.6` -
-// entao a troca nao muda comportamento nenhum, so tira o astro do caminho de
-// quem importa isto de fora do gerador.)
-import { z } from 'zod';
-// WD-063: `parseTree` + `findNodeAtLocation` traduzem o caminho de um erro
-// (`navigation.products.0.product`) para o offset dele no TEXTO, que e o que
-// vira linha. E o parser de JSON do VS Code: zero dependencias, nada de `node:`,
-// entao continua bundlavel pro Worker da plataforma. Escrever o scanner a mao
-// foi tentado e deu errado (perdia todo caminho aninhado, que e justamente o que
-// importa aqui) - nao repita.
-import { findNodeAtLocation, parseTree } from 'jsonc-parser';
-
-// ---------------------------------------------------------------------
-// Pages & groups - the leaf content any container ultimately bottoms out
-// at. A group can nest other groups arbitrarily deep, and can optionally
-// link its own label to a page (`page`) independent of expanding or
-// collapsing its children - see NavTree.astro for how that renders.
-// ---------------------------------------------------------------------
-
-const navPageSchema = z.string();
-
-// A group ordinarily lists its own children by hand (`pages`), but can
-// instead auto-generate them from an OpenAPI spec via `openapi: { src,
-// path }` - resolved by loadDocsConfig() (via expandOpenApiInNavigation()
-// below, reading the manifest generate-api-pages.js writes for this exact
-// group) into a real `{ group, pages }` node - one sub-group per tag -
-// before anything else in this file ever sees it, so
-// resolveSections()/flattenNav()/buildNavTree()/etc. only ever need to
-// understand the ordinary pages-array shape. `.strict()` on both variants
-// is load-bearing (see withChildren()'s own comment on this pattern
-// below): without it, a group written with both `pages` and `openapi` at
-// once would silently have one dropped instead of rejected.
-const navGroupPagesSchema: z.ZodType<{ group: string; page?: string; pages: NavItem[] }> = z.lazy(() =>
-  z
-    .object({
-      group: z.string(),
-      page: z.string().optional(),
-      pages: z.array(navItemSchema),
-    })
-    .strict()
-);
-
-const navGroupOpenApiSchema = z.object({
-  group: z.string(),
-  openapi: z
-    .object({
-      // Path to an OpenAPI 3.x spec, relative to the content directory
-      // (alongside writedocs.json) - same convention the old top-level
-      // `openapi` field used. See generate-api-pages.js (the pre-Astro
-      // build/dev step that actually parses this and writes the
-      // manifest/operation JSON this group's pages are expanded from).
-      src: z.string(),
-      // Base URL path every page generated from this spec is namespaced
-      // under, e.g. "/api" -> pages served at /api/<tag>/<operation>/.
-      // Also doubles as this spec's own unique key under
-      // writedocsTempDir()'s openapi/<path>/ directory (manifest.json + operations/*.json),
-      // so two openapi groups in the same writedocs.json must use different
-      // `path` values - generate-api-pages.js throws a clear error if
-      // they collide.
-      path: z.string(),
-    })
-    .strict(),
-}).strict();
-
-export type GroupNavItem =
-  | { group: string; page?: string; pages: NavItem[] }
-  | { group: string; openapi: { src: string; path: string } };
-
-const navGroupSchema: z.ZodType<GroupNavItem> = z.union([navGroupPagesSchema, navGroupOpenApiSchema]);
-
-// A bare external link sitting directly in a `pages` array, alongside
-// page slugs and groups - e.g. a "Support" link to an external help
-// desk shown right in the sidebar, rather than only reachable via
-// navigation.global.dropdowns. Discriminated from navGroupSchema by
-// its required `label`/`href` keys (vs `group`/`pages`/`openapi`), so a
-// plain (non-strict at the union level) schema is enough for Zod to pick
-// the right branch; `.strict()` here still catches a typo'd extra key.
-const navLinkSchema = z.object({ label: z.string(), href: z.string() }).strict();
-
-const navItemSchema: z.ZodType<NavItem> = z.lazy(() =>
-  z.union([navPageSchema, navGroupSchema, navLinkSchema])
-);
-
-export type NavItem = string | GroupNavItem | { label: string; href: string };
-
-// ---------------------------------------------------------------------
-// Containers: tabs, versions, languages, dropdowns, products.
-//
-// This schema is modeled directly on Mintlify's writedocs.json
-// (https://mintlify.com/writedocs.json / mintlify.com/docs/organize/navigation):
-// all five container kinds are structurally identical except for their
-// own identifying field. Each owns *exactly one* of {pages, tabs,
-// versions, languages, dropdowns, products} as its content, or is a bare
-// external `href` link with no content of its own. That symmetry is what
-// lets any of them nest inside any other - a tab can contain versions, a
-// version can contain languages, a language can contain tabs, and so on,
-// bottoming out at a `pages` array. `withChildren()` is the single place
-// that shape is defined, instead of hand-writing the union five times.
-// ---------------------------------------------------------------------
-
-export type NavChildren =
-  | { pages: NavItem[] }
-  | { tabs: TabItem[] }
-  | { versions: VersionItem[] }
-  | { languages: LanguageItem[] }
-  | { dropdowns: DropdownItem[] }
-  | { products: ProductItem[] }
-  | { href: string };
-
-export type TabItem = { tab: string; icon?: string } & NavChildren;
-export type VersionItem = { version: string; label?: string; tag?: string; default?: boolean } & NavChildren;
-export type LanguageItem = { language: string; label?: string } & NavChildren;
-export type DropdownItem = { dropdown: string; icon?: string } & NavChildren;
-export type ProductItem = { product: string; icon?: string; description?: string } & NavChildren;
-
-// `.strict()` on every variant is load-bearing, not decoration: Zod
-// objects silently strip unrecognized keys by default, so without it a
-// node written with two children fields at once (e.g. both `pages` and
-// `versions`) would just have the second one dropped instead of
-// rejected - defeating the entire "exactly one child kind per level"
-// rule this schema exists to enforce (mirroring Mintlify's own "a tab
-// cannot contain both anchors and groups at the same level").
-function withChildren<Base extends z.ZodRawShape>(base: Base) {
-  return z.union([
-    z.object({ ...base, pages: z.array(navItemSchema) }).strict(),
-    z.object({ ...base, tabs: z.array(tabSchema).min(1) }).strict(),
-    z.object({ ...base, versions: z.array(versionSchema).min(1) }).strict(),
-    z.object({ ...base, languages: z.array(languageSchema).min(1) }).strict(),
-    z.object({ ...base, dropdowns: z.array(dropdownSchema).min(1) }).strict(),
-    z.object({ ...base, products: z.array(productSchema).min(1) }).strict(),
-    z.object({ ...base, href: z.string() }).strict(),
-  ]);
-}
-
-// Each of these five is defined via z.lazy() because withChildren()
-// references all five by name (mutual recursion) - safe because none of
-// them are actually *called* until a real writedocs.json is parsed, by which
-// point every const below has been assigned. The same pattern already
-// used for navItemSchema/navGroupSchema above.
-const tabSchema: z.ZodType<TabItem> = z.lazy(() =>
-  withChildren({ tab: z.string(), icon: z.string().optional() })
-);
-
-const versionSchema: z.ZodType<VersionItem> = z.lazy(() =>
-  withChildren({
-    version: z.string(),
-    label: z.string().optional(),
-    tag: z.string().optional(),
-    default: z.boolean().optional(),
-  })
-);
-
-const languageSchema: z.ZodType<LanguageItem> = z.lazy(() =>
-  withChildren({ language: z.string(), label: z.string().optional() })
-);
-
-const dropdownSchema: z.ZodType<DropdownItem> = z.lazy(() =>
-  withChildren({ dropdown: z.string(), icon: z.string().optional() })
-);
-
-const productSchema: z.ZodType<ProductItem> = z.lazy(() =>
-  withChildren({ product: z.string(), icon: z.string().optional(), description: z.string().optional() })
-);
-
-// ---------------------------------------------------------------------
-// Root navigation: a flat array (shorthand for one implicit section - the
-// common case) or an object choosing exactly one primary organizational
-// pattern, per Mintlify's convention ("choose one primary organizational
-// pattern at the root level of your navigation").
-//
-// `global.dropdowns` is the one exception to "exactly one pattern": it's
-// not a primary pattern, it's a persistent set of topbar dropdown
-// triggers that render on every page regardless of which tab/version/
-// language/product is active - equivalent to Mintlify's
-// `navigation.global.anchors`. This replaces the earlier `{tabs,
-// dropdowns}` shape (both present at once), which doesn't generalize
-// once versions/languages/products are also root-level choices.
-// ---------------------------------------------------------------------
-
-export type NavigationConfig =
-  | NavItem[]
-  | { global?: { dropdowns: DropdownItem[] }; tabs: TabItem[] }
-  | { global?: { dropdowns: DropdownItem[] }; versions: VersionItem[] }
-  | { global?: { dropdowns: DropdownItem[] }; languages: LanguageItem[] }
-  | { global?: { dropdowns: DropdownItem[] }; dropdowns: DropdownItem[] }
-  | { global?: { dropdowns: DropdownItem[] }; products: ProductItem[] };
-
-const globalSchema = z.object({ dropdowns: z.array(dropdownSchema).min(1) });
-
-const navigationSchema = z.union([
-  z.array(navItemSchema),
-  z.object({ global: globalSchema.optional(), tabs: z.array(tabSchema).min(1) }).strict(),
-  z.object({ global: globalSchema.optional(), versions: z.array(versionSchema).min(1) }).strict(),
-  z.object({ global: globalSchema.optional(), languages: z.array(languageSchema).min(1) }).strict(),
-  z.object({ global: globalSchema.optional(), dropdowns: z.array(dropdownSchema).min(1) }).strict(),
-  z.object({ global: globalSchema.optional(), products: z.array(productSchema).min(1) }).strict(),
-]) as z.ZodType<NavigationConfig>;
-
-const DEFAULT_PRIMARY = '#6366f1';
-
-// A logo is either one path used for both color modes, or a
-// { light, dark, label } object - each image shown only while that mode
-// is active (see BaseLayout.astro's .wd-logo-light/.wd-logo-dark CSS).
-// The topbar shows *only* the image by default - no site name text next
-// to it, since a real logo asset usually already is a wordmark. `label`
-// is the opt-in way to add text back next to the image (e.g. a product
-// name alongside a symbol-only mark); it only exists on the object form,
-// since a single shared image path is just as easy to bake the label
-// into directly.
-//
-// `light`/`dark` are themselves optional (unlike the string form, which
-// is inherently "both"): a site with no logo *images* at all can still
-// set `styles.logo: { label: "..." }` to override the topbar's fallback
-// text without providing any image - see BaseLayout.astro's
-// hasLogoImage/logoLabel/brandLabel derivation, where an object with
-// only `label` set already resolves correctly (brandLabel = logoLabel,
-// same as if an image were also present) without needing any change
-// there; only this schema needed loosening; light/dark were previously
-// both required whenever the object form was used at all.
-//
-// Standalone const (rather than inlined into stylesSchema.logo below) so
-// footer.logo further down can share the exact same union instead of an
-// independently-written copy - see footerSchema's own comment on why a
-// footer logo needs this at all.
-const logoSchema = z.union([
-  z.string(),
-  z.object({ light: z.string().optional(), dark: z.string().optional(), label: z.string().optional() }).strict(),
-]);
-
-// Same {light, dark}-with-fallback shape applies to `colors.dark`: any
-// of primary/text left unset there falls back to the light-mode value
-// already given above, so a site only has to specify what actually
-// differs in dark mode. There used to be a `background`/`dark.background`
-// pair here too, doing effectively the same job as `background.colors`
-// further down (see that field's own comment) - two writedocs.json fields
-// both named "background" that visually looked interchangeable but
-// weren't quite (one drove --wd-background site-wide, the other only
-// the <body> canvas), which was confusing to author against and easy to
-// half-configure by setting only one. Removed in favor of `background`
-// alone being the single place to set any background color - see that
-// field's comment for what it now covers.
-// One side of `styles.navbar` (light or dark) - either a bare background
-// color (the original shape) or `{ background, accent? }` once a site
-// wants its own accent color (the active-tab fill / hover underline)
-// inside the navbar specifically, independent of the sitewide
-// `styles.colors.primary`. Deliberately does NOT carry a text/icon color
-// field at all - see `navbar`'s own comment below (stylesSchema) for why
-// that's resolved automatically instead of being configurable. Kept as a
-// standalone const rather than inlined so `light`/`dark` share the exact
-// same union rather than two independently-written (and possibly
-// drifting) copies of it.
-const navbarColorValueSchema = z.union([
-  z.string(),
-  z
-    .object({
-      background: z.string(),
-      accent: z.string().optional(),
-    })
-    .strict(),
-]);
-
-// One font declaration - almost exactly Mintlify's own `fonts` shape (see
-// docs/dev/docs/site-config.mdx's own "Fonts" section for the research this
-// was based on): a bare Google Fonts family name (`family` alone - Google
-// Fonts loads it automatically, see googleFontsHref() below), or a local/
-// externally-hosted font file (`source` + `format` together; `source` is
-// either a project-relative path like the other five asset-fallback fields
-// this schema already has - see collectConfiguredAssetPaths() - or a full
-// https:// URL to an externally-hosted font). `weight` does two things at
-// once, both driven by BaseLayout.astro: it narrows which file actually
-// loads (folded into the Google Fonts URL's `:wght@` axis, or the
-// generated `@font-face` rule's own `font-weight` descriptor for a
-// `source` font - see googleFontsHref()/fontFaceRule() below), *and* it's
-// applied as a real CSS `font-weight` on h1-h6 (for `heading`) or `body`
-// (for `body`) - see BaseLayout's own `wdFontWeightHeading`/
-// `wdFontWeightBody`. Both halves matter: loading only the 400-weight file
-// while leaving h1-h6 at the browser's UA-default `font-weight: bold`
-// faux-bolds that file back to looking bold anyway, with no visible
-// change from configuring a lighter weight at all - the bug this second
-// half fixes (caught from real user-reported behavior, not anticipated
-// up front). Left unset anywhere in `styles.fonts` renders no font-weight
-// rule at all, keeping today's plain browser-default bold headings/normal
-// body text unchanged for a site that hasn't touched this field.
-const fontVariantSchema = z
-  .object({
-    family: z.string(),
-    weight: z.number().optional(),
-    source: z.string().optional(),
-    format: z.enum(['woff', 'woff2']).optional(),
-  })
-  .strict();
-
-export type FontVariant = z.infer<typeof fontVariantSchema>;
-
-// The top-level shape adds `heading`/`body`: each independently optional,
-// each falling back to the top-level family/weight/source/format when
-// unset (see resolveFonts() below) - so a site can set one font for
-// everything (`fonts.family` alone), or split headings and body text
-// without needing to repeat itself for whichever side isn't changing.
-const fontsSchema = z
-  .object({
-    family: z.string(),
-    weight: z.number().optional(),
-    source: z.string().optional(),
-    format: z.enum(['woff', 'woff2']).optional(),
-    heading: fontVariantSchema.optional(),
-    body: fontVariantSchema.optional(),
-  })
-  .strict();
-
-export type FontsConfig = z.infer<typeof fontsSchema>;
-
-const stylesSchema = z
-  .object({
-    colors: z
-      .object({
-        primary: z.string().default(DEFAULT_PRIMARY),
-        text: z.string().optional(),
-        dark: z
-          .object({
-            primary: z.string().optional(),
-            text: z.string().optional(),
-          })
-          .optional(),
-      })
-      .default({ primary: DEFAULT_PRIMARY }),
-    logo: logoSchema.optional(),
-    favicon: z.string().optional(),
-    // No default value here (unlike `colors.primary`'s DEFAULT_PRIMARY) -
-    // resolveFonts() below is where "Inter" actually gets applied as the
-    // site-wide default whenever this field is left unset entirely, so
-    // that fallback lives in one place alongside the rest of the
-    // resolution logic rather than being duplicated as a schema default
-    // *and* a resolver fallback.
-    fonts: fontsSchema.optional(),
-    // The Shiki theme *name* (not a full theme object/JSON - see
-    // https://shiki.style/themes for the built-in list) each fenced
-    // (```) MDX code block, and the API playground's request/response
-    // snippets, use in light/dark mode - read out of writedocs.json by both
-    // astro.config.mjs (Shiki's dual-theme markdown config) and
-    // ApiReferencePanel.astro (its own separate <Code/> usages, which
-    // don't inherit markdown.shikiConfig) via resolveCodeblockTheme()
-    // below, the single source of truth for the 'github-light'/
-    // 'github-dark' fallback. Left per-key optional (not defaulted in
-    // the schema itself) so a site can override just one side (e.g.
-    // only `dark`) and still get the ordinary default for the other.
-    codeblocks: z
-      .object({
-        light: z.string().optional(),
-        dark: z.string().optional(),
-        // Maps a fenced (```) block's own language tag to whichever real
-        // Shiki grammar actually highlights it, before that tag ever
-        // reaches Shiki - see resolveCodeblockLangAlias() below for the
-        // one built-in entry (mdx -> jsx) this ships with by default and
-        // why. A site can add its own entries for any other language tag
-        // that either doesn't tokenize well under its own grammar, or
-        // that a site wants to write under a shorter/friendlier fence tag
-        // than Shiki's own bundled id (e.g. `groovy: 'java'` for a close-
-        // enough approximation Shiki doesn't ship a dedicated grammar for
-        // at all) - merged with, not replacing, the built-in default, so
-        // adding one of a site's own doesn't require re-declaring mdx.
-        langAlias: z.record(z.string(), z.string()).optional(),
-      })
-      .strict()
-      .optional(),
-    // The topbar's own background, independent of `background` below (the
-    // page's) - a site may want its navbar to stand out (a dark or
-    // brand-colored bar over a light page) rather than blend into the
-    // page, which is the default when this is left unset. Same {light,
-    // dark} shape (and same per-key-optional, not defaulted here) as
-    // `codeblocks` right above, rather than nested under `colors` - it's a
-    // topbar-specific override, not a third general-purpose page color, so
-    // it reads more like "one more themed surface" alongside codeblocks
-    // than a sibling of primary/text. BaseLayout.astro's own
-    // lightNavbarBg/darkNavbarBg resolution is what falls each side back
-    // to the page background when unset.
-    //
-    // Each side (`light`/`dark`) is either a bare string - just the
-    // background color, exactly the original shape, kept for backwards
-    // compatibility - or `{ background, accent? }`, for when a site also
-    // wants the navbar's own active-tab-fill/hover-underline color to
-    // differ from the sitewide `styles.colors.primary` (`accent`'s only
-    // job - see BaseLayout.astro's lightNavbarAccent). Deliberately no
-    // text/icon color field here at all: BaseLayout.astro always resolves
-    // the navbar's plain text/icon color itself, picking black or white by
-    // contrast against whatever `background` resolves to
-    // (contrastTextColor() below) the moment this field is configured at
-    // all (string or object) - never a value read from writedocs.json. A
-    // manually-set text color is a legibility footgun a site author can
-    // get wrong (or drift out of sync after later changing `background`
-    // without remembering to update it too) in a way "compute it
-    // correctly, every time" simply can't - there's no legitimate reason
-    // to want *illegible* navbar text, unlike `accent`, which is a real
-    // aesthetic choice. Real bug this fixes: a site setting `navbar.light`
-    // to the same value as `colors.primary` (a plausible thing to reach
-    // for - "brand-colored navbar") made every topbar label/icon/link
-    // render in the default near-black text color against that same
-    // saturated background, all but unreadable - and an earlier version of
-    // this feature that let a writedocs.json-supplied color double as the text
-    // color reintroduced the identical bug one level down, just requiring
-    // one more (still guessable-wrong) field to trigger it.
-    navbar: z
-      .object({
-        light: navbarColorValueSchema.optional(),
-        dark: navbarColorValueSchema.optional(),
-      })
-      .strict()
-      .optional(),
-    // The single place to configure any background color: `colors` is a
-    // solid color (falls back to '#ffffff'/'#0b1120' when unset - see
-    // BaseLayout.astro's lightBackground/darkBackground resolution), and
-    // `images` layers an image on top of it (or is the whole background
-    // by itself, if `colors` is left at its default). This one pair now
-    // drives everything background-related site-wide - --wd-background
-    // (dropdowns/modals/kbd chips/footer/topbar-fallback/etc., see every
-    // `var(--wd-background)` call site) *and* the <body> canvas behind the
-    // main/toc columns - rather than the two being independently
-    // configurable fields that happened to look alike but didn't affect
-    // the same things (see this schema's own comment on `colors.dark`
-    // above for why that split was removed). Both are per-mode optional,
-    // same "only specify what differs" pattern as codeblocks/navbar above.
-    // The topbar and footer still get their own explicit opaque
-    // background (topbar.css/footer.css) specifically so an `images`
-    // background doesn't show through them; see those files' own
-    // comments. The sidebar column has no background of its own (base.css)
-    // and lets it show through, same as the main/toc columns.
-    background: z
-      .object({
-        colors: z
-          .object({
-            light: z.string().optional(),
-            dark: z.string().optional(),
-          })
-          .strict()
-          .optional(),
-        images: z
-          .object({
-            light: z.string().optional(),
-            dark: z.string().optional(),
-          })
-          .strict()
-          .optional(),
-      })
-      .strict()
-      .optional(),
-  })
-  .default({ colors: { primary: DEFAULT_PRIMARY } });
-
-// `href` is always required - a link with nowhere to go isn't a link.
-// `label`/`icon` are each individually optional, but not both at once
-// (enforced by the .refine() below, same shape as scriptEntrySchema's own
-// exactly-one-of check above) - a link needs *something* visible to render,
-// whichever of the two, and can have both (icon rendered to the left of the
-// label - see TopBar.astro/SiteFooter.astro, the two renderers of this
-// shape). An icon-only link (no label) is the common case for something
-// like a bare GitHub mark in the topbar; label-only (no icon) is every
-// plain text link this already supported before `icon` existed - both
-// still need to keep working unchanged, hence neither field being outright
-// required on its own.
-const topbarLinkSchema = z
-  .object({
-    label: z.string().optional(),
-    href: z.string(),
-    // Same string shape as every other writedocs.json `icon` field (a plain
-    // Lucide name, or the explicit "collection:icon-name" form for
-    // anything else - see resolveIcon()/AppIcon.astro) - not documented
-    // again here since that convention is already established elsewhere
-    // in this file (tabs/switchers/socials all take the identical shape).
-    icon: z.string().optional(),
-  })
-  .strict()
-  .refine((link) => Boolean(link.label) || Boolean(link.icon), {
-    message: 'Each topbar.links/footer column link needs a "label", an "icon", or both - a link with neither has nothing to render.',
-  });
-
-// One column of the footer (BaseLayout.astro's <footer class="wd-footer">) -
-// an optional heading (e.g. "Resources", "Community") plus a list of links,
-// reusing the exact same {label, icon, href} shape as topbar.links above (a
-// footer link is the same thing rendered in a different place, no reason
-// for a second, identical-but-differently-named schema). `title` is
-// optional so a single-column footer with no heading (just a bare list of
-// links) is valid too.
-const footerColumnSchema = z
-  .object({
-    title: z.string().optional(),
-    links: z.array(topbarLinkSchema).default([]),
-  })
-  .strict();
-
-// Off by default (empty `columns`, same convention as `topbar` above - a
-// footer with nothing configured just doesn't render at all, see
-// BaseLayout.astro's `hasFooterContent` check) rather than `.optional()`
-// like contextMenu: unlike that field, an empty/default footer has no
-// build-output or routing implications to gate, it's purely visual, so
-// there's no reason to distinguish "unset" from "set to nothing" the way
-// contextMenu needs to.
-// Same {light, dark, label} union as `styles.logo` (via the shared
-// logoSchema above) - unset by default, in which case the footer just
-// shows the sitewide `styles.logo` (BaseLayout.astro's existing
-// logoLight/logoDark/logoLabel, already threaded into SiteFooter as-is).
-// Set here, it replaces that entirely rather than filling in only the
-// missing side of it - a footer.logo with only `dark` set shows *just*
-// the dark-mode image, not styles.logo's light image plus this dark one -
-// the same all-or-nothing-relative-to-styles.logo resolution BaseLayout.astro
-// already applies.
-const footerSchema = z
-  .object({
-    columns: z.array(footerColumnSchema).default([]),
-    logo: logoSchema.optional(),
-  })
-  .strict()
-  .default({ columns: [] });
-
-export type FooterColumn = z.infer<typeof footerColumnSchema>;
-export type FooterConfig = z.infer<typeof footerSchema>;
-
-// Shared by both writedocs.json's top-level `seo` (site-wide defaults) and a
-// page's own frontmatter `seo` (per-page overrides) - see
-// content.config.ts's docsSchema, which imports this exact schema rather
-// than redeclaring the same shape a second time. mergeSeo() below is what
-// actually combines the two, field by field, at render time.
-export const seoFieldsSchema = z
-  .object({
-    // Open Graph / Twitter card image - a relative path (resolved against
-    // `domain` below into an absolute URL, since most social crawlers
-    // require one) or an already-absolute https:// URL.
-    ogImage: z.string().optional(),
-    // og:type - "website" for most pages, "article" for blog-post-shaped
-    // content, etc. Defaults to "website" if never set anywhere.
-    ogType: z.string().optional(),
-    twitterCard: z.enum(['summary', 'summary_large_image']).optional(),
-    keywords: z.array(z.string()).optional(),
-    // Renders <meta name="robots" content="noindex, nofollow" /> and
-    // (see astro.config.mjs's sitemap `filter`) excludes the page from
-    // sitemap.xml entirely - both driven off this one flag, since listing
-    // a page in the sitemap while also telling crawlers not to index it
-    // would be self-contradictory.
-    noindex: z.boolean().optional(),
-  })
-  .strict();
-
-export type SeoFields = z.infer<typeof seoFieldsSchema>;
-
-/** Field-by-field merge of a page's own `seo` frontmatter over writedocs.json's
- *  site-wide `seo` defaults - a page only overrides the specific fields it
- *  sets, falling back to the site default for everything else, rather than
- *  a page's (possibly partial) `seo` object replacing the site's wholesale. */
-export function mergeSeo(site: SeoFields, page?: SeoFields): SeoFields {
-  if (!page) return site;
-  return {
-    ogImage: page.ogImage ?? site.ogImage,
-    ogType: page.ogType ?? site.ogType,
-    twitterCard: page.twitterCard ?? site.twitterCard,
-    keywords: page.keywords ?? site.keywords,
-    noindex: page.noindex ?? site.noindex,
-  };
-}
-
-// Controls for the OpenAPI API playground's "Try it" modal - separate
-// from a group's own `openapi: { src, path }` field (which spec to use,
-// and where) since this is about how a *request* it sends behaves, not
-// about the spec itself.
-const apiSchema = z
-  .object({
-    // Whether the Try-it modal's Send button routes its request through
-    // writedocs' own CORS proxy (https://proxy.writechoice.io/) rather
-    // than calling the API directly from the browser. Almost no
-    // real-world API sends back Access-Control-Allow-Origin headers
-    // permitting an arbitrary docs site's origin, so a direct browser
-    // fetch() from the Try-it modal fails for most real APIs without
-    // this - see PROXY_BASE_URL in ApiReferencePanel.astro for the
-    // actual request-forwarding logic. Defaults to enabled; a site can
-    // set this to `false` to always call the API directly instead (the
-    // API is already CORS-permissive, same-origin in some deployments,
-    // or the site owner doesn't want requests routed through a third
-    // party at all).
-    proxy: z.boolean().default(true),
-  })
-  .strict()
-  .default({ proxy: true });
-
-// The "Copy page" dropdown shown next to a page's title - copy the raw
-// Markdown to the clipboard, open the raw Markdown in a new tab, or
-// deep-link into an AI assistant with a prompt pointing at it. Opt-in:
-// undefined (the field simply absent from writedocs.json) means the feature
-// is off entirely - no menu rendered, no .md routes generated at build
-// time either (see [...slug].md.ts) - rather than defaulting to on,
-// since it changes both the UI and the build output. Once a site does
-// write a `contextMenu` key (even `{}`), copying/viewing-as-Markdown are
-// always included (they need nothing but the page's own content); only
-// `openIn` (the AI-assistant deep-links, which need an absolute URL to
-// point the assistant at) is independently configurable.
-const contextMenuSchema = z
-  .object({
-    openIn: z.array(z.enum(['chatgpt', 'claude', 'perplexity'])).default(['chatgpt', 'claude', 'perplexity']),
-  })
-  .strict();
-
-export type ContextMenuConfig = z.infer<typeof contextMenuSchema>;
-
-// One entry in writedocs.json's `redirects` array - wired almost directly into
-// Astro's own `redirects` config option (astro.config.mjs), which is what
-// actually generates the redirect pages. `permanent` is deliberately not
-// part of this schema: with no server/adapter (this project always builds
-// `output: 'static'` with none installed), Astro's own docs say a static
-// redirect "does not support status codes" at all - it's always a client-
-// side `<meta http-equiv="refresh">` page, full stop. Accepting a
-// `permanent` field here that silently did nothing would be worse than
-// not offering it.
-const redirectSchema = z
-  .object({
-    source: z.string(),
-    destination: z.string(),
-  })
-  .strict();
-
-export type RedirectConfig = z.infer<typeof redirectSchema>;
-
-// A site-wide banner rendered above the topbar on every page (except
-// `mode: blank`, which drops all site chrome including this - see
-// BaseLayout.astro). Optional/undefined by default, same convention as
-// `contextMenu` above - a site with no banner configured gets no banner
-// markup at all, not an empty one.
-const bannerSchema = z
-  .object({
-    content: z.string(),
-    // Persisted via localStorage once dismissed (see BaseLayout.astro's
-    // initBanner()) - a static site has no server-side session to track
-    // this against, so "dismissed" only ever means "dismissed in this
-    // browser". A banner without `dismissible` reappears on every visit,
-    // appropriate for something that should stay visible until the site
-    // author removes it from writedocs.json themselves (e.g. "this version is
-    // deprecated"), not something a reader can permanently clear.
-    dismissible: z.boolean().default(false),
-    type: z.enum(['info', 'warning', 'critical']).default('info'),
-  })
-  .strict();
-
-export type BannerConfig = z.infer<typeof bannerSchema>;
-
-// Content for the custom 404 page (src/pages/404.astro) - Astro's own
-// file-based convention (a static build emits this as 404.html at the
-// site root; most static hosts pick it up automatically for unmatched
-// routes). Both fields are optional with hardcoded fallbacks in 404.astro
-// itself, so a site doesn't have to set either to get a reasonably
-// branded 404 page (still rendered inside the normal BaseLayout/topbar
-// chrome, just with placeholder content).
-const notFoundSchema = z
-  .object({
-    title: z.string().optional(),
-    description: z.string().optional(),
-  })
-  .strict()
-  .default({});
-
-export type NotFoundConfig = z.infer<typeof notFoundSchema>;
-
-// One <script> tag to inject - exactly one of `src` (an external/local
-// file, rendered as `<script src="...">`) or `content` (inline JS,
-// rendered via `<script is:inline set:html="...">`) has to be set, not
-// both and not neither - enforced by the `.refine()` below rather than
-// leaving both optional and silently rendering an empty tag if a site
-// author gets this wrong.
-const scriptEntrySchema = z
-  .object({
-    src: z.string().optional(),
-    content: z.string().optional(),
-  })
-  .strict()
-  .refine((v) => (v.src ? !v.content : !!v.content), {
-    message: 'Each scripts.head/scripts.body entry needs exactly one of "src" or "content", not both or neither.',
-  });
-
-export type ScriptEntry = z.infer<typeof scriptEntrySchema>;
-
-// Raw third-party script injection - analytics snippets, chat widgets,
-// anything that needs a real <script> tag writedocs.json's own structured
-// fields (styles, integrations-style config, ...) don't have a dedicated
-// slot for yet. `head` renders right before </head>; `body` renders right
-// before </body> (after everything else has already loaded/hydrated -
-// see BaseLayout.astro), matching where a third-party script's own
-// install instructions usually say to put it.
-const scriptsSchema = z
-  .object({
-    head: z.array(scriptEntrySchema).default([]),
-    body: z.array(scriptEntrySchema).default([]),
-  })
-  .strict()
-  .default({ head: [], body: [] });
-
-export type ScriptsConfig = z.infer<typeof scriptsSchema>;
-
-// writedocs.json's `integrations` - a curated, high-value subset of analytics
-// providers, each getting its own minimal config object (just the id(s)
-// it actually needs) rather than requiring a site author to hand-write
-// the provider's own install snippet through the generic `scripts` field
-// above. This is deliberately its own thing, not built as sugar over
-// `scripts` the way the roadmap once implied it might be - most of these
-// providers' real snippets need `defer`/`async`/`data-*` attributes
-// ScriptEntry's plain `{ src?, content? }` shape has no way to express,
-// so BaseLayout.astro renders each provider with its own bespoke markup
-// instead of generating a ScriptEntry array to feed through the generic
-// renderer. Every snippet shape below was sourced from that provider's
-// own current official docs (fetched directly, not recalled from
-// training data) while building this feature - see
-// docs/dev/docs/integrations.mdx for links and dates.
-//
-// Every provider field is optional and independent - a site can turn on
-// any subset (including all of them at once, for a migration period) or
-// none. No "the" analytics field; a site picks whichever provider(s) it
-// actually uses.
-
-const ga4IntegrationSchema = z
-  .object({
-    // A GA4 "Measurement ID", always shaped like "G-XXXXXXXXXX" - not
-    // validated against that shape here, since Google could change the
-    // prefix/length without this schema needing to track it.
-    measurementId: z.string(),
-  })
-  .strict();
-
-const googleTagManagerIntegrationSchema = z
-  .object({
-    // A GTM container id, shaped like "GTM-XXXXXXX".
-    containerId: z.string(),
-  })
-  .strict();
-
-const plausibleIntegrationSchema = z
-  .object({
-    domain: z.string(),
-    // Plausible's own hosted script URL by default - override for a
-    // self-hosted instance, a reverse-proxy path (Plausible's own
-    // documented way to dodge ad-blockers), or one of Plausible's
-    // documented script *extensions* (e.g.
-    // "https://plausible.io/js/script.hash.outbound-links.js").
-    src: z.string().default('https://plausible.io/js/script.js'),
-  })
-  .strict();
-
-const fathomIntegrationSchema = z
-  .object({
-    // Fathom's own short "Site ID", not a full URL or measurement id.
-    siteId: z.string(),
-  })
-  .strict();
-
-const posthogIntegrationSchema = z
-  .object({
-    // PostHog calls this a "project API key" (starts with "phc_") in its
-    // own docs - `apiKey` here rather than that exact name, matching this
-    // schema's own plainer naming convention for the equivalent id on
-    // every other provider above.
-    apiKey: z.string(),
-    // PostHog is region-sharded (US/EU) with no single universal default
-    // - "https://us.i.posthog.com" is PostHog's own default for a new
-    // project, but a site on their EU cloud (or a self-hosted instance)
-    // must override this to the host shown in their own project
-    // settings, or events silently go nowhere.
-    apiHost: z.string().default('https://us.i.posthog.com'),
-  })
-  .strict();
-
-const umamiIntegrationSchema = z
-  .object({
-    websiteId: z.string(),
-    // Unlike Plausible/PostHog, Umami has no single hosted default that
-    // works for most users - it's commonly self-hosted, and even Umami
-    // Cloud users get a per-region script URL. Defaults to Umami Cloud's
-    // own documented script URL, which only happens to be correct for a
-    // Cloud user on that specific region; anyone self-hosting (the more
-    // common case for this particular provider) must override it to
-    // their own instance's own /script.js path.
-    src: z.string().default('https://cloud.umami.is/script.js'),
-  })
-  .strict();
-
-// AI chat over the site's own docs content, via a third-party provider
-// (DocsBot, currently the only one wired up) rather than a self-hosted
-// RAG pipeline - see the roadmap's own "AI chat over docs content" line
-// in docs/dev/docs/roadmap.mdx, which this fulfills via integration
-// rather than by building the retrieval/generation stack in-house.
-// Deliberately named `askAi` here, not `docsbot` - this is the
-// writedocs.json-facing, provider-neutral name for the feature (matching
-// the "Ask AI" label this kind of button/widget is conventionally
-// given in docs sites generally), independent of which vendor happens
-// to sit behind it today. `id` matches DocsBot's own embed config
-// field name exactly (`DocsBotAI.init({ id: 'teamId/botId' })`) - it's
-// a single opaque "teamId/botId" string DocsBot treats as one value,
-// not two separate ids, so this schema doesn't split it either.
-const askAiIntegrationSchema = z
-  .object({
-    id: z.string(),
-  })
-  .strict();
-
-const integrationsSchema = z
-  .object({
-    ga4: ga4IntegrationSchema.optional(),
-    googleTagManager: googleTagManagerIntegrationSchema.optional(),
-    plausible: plausibleIntegrationSchema.optional(),
-    fathom: fathomIntegrationSchema.optional(),
-    posthog: posthogIntegrationSchema.optional(),
-    umami: umamiIntegrationSchema.optional(),
-    askAi: askAiIntegrationSchema.optional(),
-  })
-  .strict()
-  .default({});
-
-export type IntegrationsConfig = z.infer<typeof integrationsSchema>;
-
-export const docsConfigSchema = z.object({
-  name: z.string(),
-  description: z.string().optional(),
-  styles: stylesSchema,
-  navigation: navigationSchema,
-  // Platform name -> profile/page URL (e.g. `{ "github": "https://
-  // github.com/...", "twitter": "https://twitter.com/..." }`), free-form
-  // rather than an enum of known platforms - the key doubles as the icon
-  // reference BaseLayout.astro's footer resolves via resolveIcon() below
-  // (bare `"github"` -> `lucide:github`; use an explicit
-  // `"simple-icons:whatever"` key instead when the bare lucide name isn't
-  // right for a given platform). Rendered as a row of icon links in the
-  // footer - see hasFooterContent/`.wd-footer-socials` in BaseLayout.astro.
-  socials: z.record(z.string(), z.string()).default({}),
-  topbar: z
-    .object({ links: z.array(topbarLinkSchema).default([]) })
-    .default({ links: [] }),
-  // Columns of links below the page content - see footerSchema/
-  // footerColumnSchema above. Renders alongside `socials` above (as a row
-  // of icon links) in the same <footer> - see BaseLayout.astro.
-  footer: footerSchema,
-  api: apiSchema,
-  // The site's own deployed domain, e.g. "docs.example.com" or
-  // "https://docs.example.com" (the scheme is optional - resolveSiteUrl()
-  // below normalizes either form to a full https:// origin). Powers three
-  // things that all need an absolute origin to work: sitemap.xml
-  // generation (astro.config.mjs only registers @astrojs/sitemap when this
-  // is set - a sitemap of relative URLs isn't meaningful), the canonical
-  // <link> and og:url/twitter meta tags (BaseLayout.astro), and resolving
-  // a relative `seo.ogImage` into an absolute URL for social crawlers.
-  // Left optional and simply skipped (with a log message, not an error) at
-  // every one of those call sites when unset - most fixtures/local builds
-  // have no real deployed domain yet.
-  domain: z.string().optional(),
-  // Site-wide meta tag defaults - see seoFieldsSchema above. A page's own
-  // frontmatter `seo` (content.config.ts's docsSchema) overrides these
-  // field by field via mergeSeo(), rather than needing to repeat every
-  // field on every page.
-  seo: seoFieldsSchema.default({}),
-  // The "Copy page" dropdown - see contextMenuSchema above. Absent by
-  // default (no menu, no .md routes).
-  contextMenu: contextMenuSchema.optional(),
-  // See redirectSchema above. Wired directly into Astro's own `redirects`
-  // config option in astro.config.mjs.
-  redirects: z.array(redirectSchema).default([]),
-  // Site-wide `[[key]]` substitution values, applied to page prose text
-  // at build time (see the remarkSubstituteVariables plugin wired into
-  // astro.config.mjs) - e.g. `{ "productName": "Acme" }` lets every page
-  // write `[[productName]]` once instead of hardcoding it everywhere.
-  // Double square brackets, not the more familiar `{{key}}` - MDX
-  // reserves single curly braces for embedded JS expressions, so
-  // `{{productName}}` in an .mdx file parses as a JS object-literal
-  // expression (`{productName}`, shorthand syntax) rather than literal
-  // text, and throws `ReferenceError: productName is not defined` at
-  // render time - see remarkSubstituteVariables' own comment in
-  // mdx-substitute-variables.js for the full explanation. Deliberately a
-  // flat string map, not typed values - this is text substitution into
-  // prose, not a templating language.
-  variables: z.record(z.string(), z.string()).default({}),
-  // See bannerSchema above. Absent by default (no banner rendered).
-  banner: bannerSchema.optional(),
-  // See notFoundSchema above.
-  notFound: notFoundSchema,
-  // See scriptsSchema above.
-  scripts: scriptsSchema,
-  // See integrationsSchema above.
-  integrations: integrationsSchema,
-});
-
-export type DocsConfig = z.infer<typeof docsConfigSchema>;
-
-// ---------------------------------------------------------------------
-// Ponto de entrada unico de validacao
-//
-// Existe pra que o gerador (`writedocs validate` e o `loadDocsConfig` que o
-// build usa) e a plataforma validem pelo MESMO codigo, com as MESMAS palavras -
-// o criterio de aceite do WD-066 e do WD-062. Se cada lado formatasse os erros
-// por conta propria, o cliente veria a plataforma aceitar um writedocs.json que
-// o build depois recusa, que e exatamente a classe de bug que a E11 existe pra
-// impedir.
-//
-// Recebe TEXTO CRU, e faz o JSON.parse por conta propria, por tres motivos:
-//   1. um JSON sintaticamente quebrado passa a ser um resultado de validacao
-//      como qualquer outro, em vez de uma excecao solta do runtime;
-//   2. linha/coluna so existem no texto - e o WD-063 precisa reportar linha;
-//   3. do lado da plataforma, importProjectConfig ja tem os bytes crus em maos
-//      antes de parsear, entao encaixa sem ginastica nenhuma.
-//
-// IMPORTANTE, e deliberado: as mensagens aqui sao as do Zod, VERBATIM. Melhorar
-// a linguagem delas e o WD-063, que precisa deste comportamento como ponto de
-// partida pra medir a melhora. Nada aqui reescreve, traduz ou embeleza mensagem.
-// ---------------------------------------------------------------------
-
-/** Um problema encontrado na configuracao. `path` e o caminho do campo em
- *  notacao de ponto (`navigation.tabs.0.label`), ou `(root)` quando o problema e
- *  do documento inteiro - o mesmo texto que a mensagem de erro do build ja
- *  imprime hoje. `line`/`column` so vem quando da pra saber (hoje: erro de JSON;
- *  no WD-063, tambem para erros de schema). */
-export type ValidationIssue = {
-  path: string;
-  message: string;
-  /** Codigo do Zod (`invalid_type`, `unrecognized_keys`, ...) ou `invalid_json`. */
-  code?: string;
-  line?: number;
-  column?: number;
-  /** WD-063: a mesma coisa que `message`, dita para gente. ADICIONAL, nunca
-   *  substituto - `message` continua sendo o texto do Zod verbatim, que e o que
-   *  o `writedocs build` imprime e o que o WD-062 grava em `validation_issues`.
-   *  Quem exibe escolhe qual dos dois mostrar. */
-  humanMessage?: string;
-  /** O que fazer a respeito, quando da pra dizer algo concreto. */
-  suggestion?: string;
-  /** Chave ESTAVEL de documentacao (`config.styles`), nunca uma URL: uma URL
-   *  cravada num pacote npm fica quebrada em toda instalacao ate a proxima
-   *  release, e o mesmo erro e exibido pela CLI e pelo dashboard, que podem
-   *  querer destinos diferentes. O mapa chave -> URL mora do lado de quem
-   *  renderiza. */
-  docKey?: string;
-};
-
-/** Sucesso carrega os dados ja validados (com os defaults do schema aplicados);
- *  falha carrega os problemas e diz de que tipo ela foi. `parseError` so aparece
- *  quando o JSON nao pode nem ser parseado, e existe para o chamador que quiser
- *  relancar exatamente o erro original (e o que o loadDocsConfig faz, pra nao
- *  mudar uma virgula do que o `writedocs build` ja imprime hoje). */
-export type ValidationResult =
-  | { ok: true; data: DocsConfig; issues: ValidationIssue[] }
-  | {
-      ok: false;
-      data: null;
-      kind: 'invalid_json' | 'schema';
-      issues: ValidationIssue[];
-      parseError?: SyntaxError;
-    };
-
-/** "at position 22 (line 1 column 23)" -> { line: 1, column: 23 }.
- *  O formato da mensagem de erro do JSON.parse e do V8, nao do padrao, entao
- *  isto e melhor-esforco: se a mensagem nao trouxer posicao, devolve null e o
- *  problema simplesmente fica sem linha. */
-function positionFromJsonError(message: string, rawText: string): { line: number; column: number } | null {
-  const comLinha = message.match(/line (\d+) column (\d+)/);
-  if (comLinha) return { line: Number(comLinha[1]), column: Number(comLinha[2]) };
-  const comPosicao = message.match(/position (\d+)/);
-  if (comPosicao) {
-    const pos = Math.min(Number(comPosicao[1]), rawText.length);
-    const antes = rawText.slice(0, pos);
-    const line = antes.split('\n').length;
-    return { line, column: pos - antes.lastIndexOf('\n') };
-  }
-  return null;
-}
-
-/** O corpo da mensagem de erro, uma linha por problema - exatamente o formato
- *  que o `writedocs build` imprime desde sempre (`  - campo: mensagem`). Fica
- *  aqui, e nao em cada chamador, pra que CLI e plataforma nao possam divergir.
- *
- *  NAO mudou no WD-063, de proposito: continua imprimindo `message` (o texto do
- *  Zod). O que melhorou foi o CONTEUDO dos issues - a uniao desembrulhada faz o
- *  `path` apontar pro campo real em vez de parar em `navigation`. Quem quiser a
- *  versao com frase humana e linha usa formatValidationIssuesDetailed. */
-export function formatValidationIssues(issues: ValidationIssue[]): string {
-  return issues.map((i) => `  - ${i.path}: ${i.message}`).join('\n');
-}
-
-/** A versao longa, para quem tem uma tela inteira (a CLI hoje, o dashboard do
- *  WD-065 se quiser): caminho, linha, frase humana, sugestao, e a mensagem do
- *  Zod por ultimo, entre parenteses, pra quem precisa do texto exato.
- *
- *  Mora aqui pelo mesmo motivo que a irma curta: se cada consumidor montasse a
- *  sua, a CLI e a plataforma divergiriam na primeira mudanca - que e exatamente
- *  o que o AC do WD-066 proibe. `fileName` so entra na referencia de linha. */
-export function formatValidationIssuesDetailed(
-  issues: ValidationIssue[],
-  { fileName = 'writedocs.json' }: { fileName?: string } = {}
-): string {
-  return issues
-    .map((i) => {
-      const temCampo = i.path !== '(root)';
-      const local = i.line ? `${fileName}:${i.line}` : i.path;
-      const linhas = [`  ${local}${i.line && temCampo ? `  (${i.path})` : ''}`];
-      linhas.push(`    ${i.humanMessage ?? i.message}`);
-      if (i.suggestion) linhas.push(`    ${i.suggestion}`);
-      if (i.humanMessage && i.message !== i.humanMessage) linhas.push(`    (${i.message})`);
-      return linhas.join('\n');
-    })
-    .join('\n\n');
-}
-
-// ---------------------------------------------------------------------
-// WD-063 — do issue do Zod para "onde esta o erro, e o que fazer"
-//
-// Tres transformacoes, nesta ordem:
-//   1. desembrulhar `invalid_union` (senao todo erro dentro da navigation vira
-//      `navigation: "Invalid input"`, que e inutil num arquivo de 10 KB);
-//   2. achar a linha no texto, pelo caminho ja desembrulhado;
-//   3. escrever a frase humana, a sugestao e a docKey - POR CODIGO do Zod, nao
-//      por campo: um mapa por campo teria 17 entradas so na raiz e centenas no
-//      total, e envelheceria a cada campo novo do schema.
-// ---------------------------------------------------------------------
-
-/** Chaves que a raiz aceita sem ser campo do schema, e que por isso NAO devem
- *  gerar aviso de chave desconhecida. Deliberadamente minuscula: a raiz nao e
- *  `.strict()` justamente pra nao quebrar configs existentes, e `$schema` foi um
- *  dos argumentos dessa decisao - avisar sobre ele contradiria o que o protegeu.
- *  Se esta lista passar de dois ou tres nomes, o problema e outro e a raiz
- *  precisa de outra conversa. */
-export const ROOT_ALLOWED_EXTRA_KEYS: readonly string[] = Object.freeze(['$schema']);
-
-type IssueCru = {
-  code?: string;
-  path?: (string | number)[];
-  message: string;
-  expected?: string;
-  values?: unknown[];
-  keys?: string[];
-  minimum?: number;
-  maximum?: number;
-  origin?: string;
-  format?: string;
-  errors?: unknown[];
-  unionErrors?: unknown[];
-};
-
-type IssuePlano = IssueCru & { caminho: (string | number)[] };
-
-function issuesDoRamo(ramo: unknown): IssueCru[] {
-  if (Array.isArray(ramo)) return ramo as IssueCru[];
-  const comIssues = ramo as { issues?: IssueCru[] };
-  return comIssues?.issues ?? [];
-}
-
-/** O maior valor de `f` sobre a lista, ou 0 se ela for vazia. Um `for` e nao
- *  `Math.max(0, ...lista.map(f))`: o spread vira argumentos de chamada, e uma
- *  lista grande o bastante (config com dezenas de milhares de erros) estoura o
- *  limite de argumentos com RangeError em vez de devolver um numero. */
-function maiorProfundidade(lista: IssuePlano[]): number {
-  let maior = 0;
-  for (const issue of lista) {
-    const p = issue.caminho.length + (issue.code === 'unrecognized_keys' ? 1 : 0);
-    if (p > maior) maior = p;
-  }
-  return maior;
-}
-
-/** Plano ACHATADO de um ramo, memoizado por identidade do ramo.
- *
- *  A memoizacao nao e otimizacao, e o que torna o achatamento viavel. Pontuar um
- *  ramo exige desembrulhar as unioes DENTRO dele, e cada uma dessas tem os seus
- *  proprios ramos - sem cache, a pontuacao visita o mesmo sub-ramo uma vez por
- *  caminho que leva ate ele, o que e exponencial na profundidade do aninhamento.
- *  Medido com grupos aninhados e um erro no fundo: 3,7 ms com 4 niveis, 281 ms
- *  com 8, 69 SEGUNDOS com 12. Com o cache, os mesmos casos ficam em 0,2 ms,
- *  porque cada no da arvore de erro do Zod e achatado uma vez so.
- *
- *  Se alguem remover este WeakMap por parecer supérfluo, o `writedocs validate`
- *  passa a travar em configs profundas. Nao remova. */
-const planoPorRamo = new WeakMap<object, IssuePlano[]>();
-
-function planoDoRamo(ramo: unknown): IssuePlano[] {
-  const lista = issuesDoRamo(ramo);
-  if (typeof ramo !== 'object' || ramo === null) return desembrulharUnioes(lista);
-  const memoizado = planoPorRamo.get(ramo);
-  if (memoizado) return memoizado;
-  // Prefixo vazio de proposito: a pontuacao compara ramos entre si, entao a
-  // profundidade tem que ser relativa ao proprio ramo, nao ao documento.
-  const plano = desembrulharUnioes(lista);
-  planoPorRamo.set(ramo, plano);
-  return plano;
-}
-
-/** Escolhe qual ramo de uma uniao o cliente PROVAVELMENTE quis.
- *
- *  Criterio: caminho mais fundo primeiro; empate resolvido por menos issues. A
- *  intuicao e a do Gabriel na spec - o ramo certo e o que nao reclama da chave
- *  que o cliente usou -, e a profundidade importa porque um ramo que chegou
- *  fundo antes de falhar (`products.0.product`) reconheceu a forma, enquanto um
- *  que falha na raiz (`expected array, received object`) so recusou o shape.
- *
- *  DUAS CORRECOES sobre a primeira versao (WD-063), as duas medidas contra o
- *  `00-kitchen-sink` real - ver o relato de revisao 43:
- *
- *  1. PONTUA O RAMO ACHATADO, nao a lista crua. Um ramo que e ele proprio uma
- *     uniao aparece como UM issue (`invalid_union`) no caminho vazio - ou seja,
- *     com a MENOR contagem e a MENOR profundidade possiveis, sem que isso diga
- *     nada sobre o quanto ele reconheceu. Era o caso mais comum que existe: um
- *     item de `pages` e `string | grupo | link`, e o grupo e outra uniao, entao
- *     todo erro estrutural dentro de um grupo empatava com o ramo `string` e
- *     perdia pela ordem de declaracao. O cliente que escrevia
- *     `{ "group": "G", "pages": 42 }` recebia "expected string, received
- *     object" - conselho errado, nao so inutil. Achatando primeiro, o mesmo caso
- *     vira `pages.0.pages: expected array, received number`.
- *
- *  2. PROFUNDIDADE EFETIVA: `unrecognized_keys` reporta no caminho do PAI, com a
- *     chave ofensora em `keys`, entao a profundidade dele sai subestimada em 1.
- *     Sem a correcao, um ramo que identificou a chave errada perde para um que
- *     so exigiu um campo ausente. (`validateDocsConfig` ja fazia a mesma conta
- *     para achar a LINHA; aqui ela entra tambem na pontuacao.)
- *
- *  Medido sobre as 60 folhas da `navigation` do `00-kitchen-sink`, trocando o
- *  tipo de cada uma: a versao anterior apontava o campo exato em 42/60 e PARAVA
- *  RASO em 18/60 (sempre os mesmos 18: os que ficam sob um `pages`); esta aponta
- *  60/60 para valor escalar errado e nunca para raso. Para um objeto vazio ou
- *  parcial no lugar de uma pagina, as duas ficam tecnicamente empatadas (41
- *  contra 42): a anterior diz "expected string", esta lista os campos que
- *  faltam para ser um grupo. E o custo aceito desta versao, e substitui o antigo
- *  (`tabs` e `products` escritos juntos, que agora sai como
- *  `Unrecognized key: "products"`).
- *
- *  EMPATE TOTAL (mesma profundidade E mesmo numero de issues): vence o ramo
- *  declarado primeiro no schema. `Array.prototype.sort` e estavel desde a
- *  ES2019, entao ordenar e pegar o [0] ja entrega isso - se alguem trocar por
- *  uma ordenacao instavel, o desempate vira sorteio. Duas razoes para "o
- *  primeiro" em vez de "todos os empatados":
- *    - um engano do cliente tem que virar UMA mensagem. Emitir os 5 ramos
- *      empatados de um `"navigation": {}` produz cinco exigencias que se
- *      contradizem ("tabs e obrigatorio", "versions e obrigatorio", ...);
- *    - determinismo: a mesma config sempre da a mesma mensagem. Um palpite
- *      instavel seria pior que um palpite ruim.
- *  E nada se perde no palpite errado: `message` continua sendo o texto do Zod. */
-function melhorRamo(ramos: unknown[]): IssueCru[] {
-  return ramos
-    .map((ramo) => {
-      const plano = planoDoRamo(ramo);
-      return {
-        lista: issuesDoRamo(ramo),
-        n: plano.length,
-        profundidade: maiorProfundidade(plano),
-      };
-    })
-    .sort((a, b) => b.profundidade - a.profundidade || a.n - b.n)[0].lista;
-}
-
-/** Desembrulha `invalid_union` recursivamente - o ramo escolhido normalmente e
- *  outra uniao (cada produto da navigation e, por sua vez, uma uniao de formas),
- *  entao para so quando chega num erro concreto. Sem recursao, o
- *  `navigation.products.0` para em "Invalid input" de novo, um nivel abaixo. */
-function desembrulharUnioes(issues: IssueCru[], prefixo: (string | number)[] = []): IssuePlano[] {
-  const saida: IssuePlano[] = [];
-  for (const issue of issues) {
-    const caminho = [...prefixo, ...(issue.path ?? [])];
-    const ramos = issue.code === 'invalid_union' ? issue.errors ?? issue.unionErrors : null;
-    if (Array.isArray(ramos) && ramos.length > 0) {
-      saida.push(...desembrulharUnioes(melhorRamo(ramos), caminho));
-    } else {
-      saida.push({ ...issue, caminho });
-    }
-  }
-  return saida;
-}
-
-/** Parseia o texto UMA vez e devolve "caminho -> linha/coluna". Devolve null
- *  quando o no nao existe no texto (campo obrigatorio ausente e o caso comum):
- *  `line` ausente e melhor que `line` inventada. */
-function criarLocalizador(rawText: string): (caminho: (string | number)[]) => { line: number; column: number } | null {
-  let arvore: ReturnType<typeof parseTree> | undefined;
-  try {
-    arvore = parseTree(rawText);
-  } catch {
-    arvore = undefined;
-  }
-  return (caminho) => {
-    if (!arvore || caminho.length === 0) return null;
-    const no = findNodeAtLocation(arvore, caminho);
-    if (!no) return null;
-    const antes = rawText.slice(0, no.offset);
-    return { line: antes.split('\n').length, column: no.offset - antes.lastIndexOf('\n') };
-  };
-}
-
-/** `styles.primaryColor` -> `config.styles`. Primeiro segmento so, com fallback
- *  pra `config`: o conjunto tem que ficar pequeno e estavel, porque vira
- *  superficie publica no instante em que alguem mapear chave -> URL. */
-function docKeyDoCaminho(caminho: (string | number)[]): string {
-  const primeiro = caminho[0];
-  return typeof primeiro === 'string' && primeiro ? `config.${primeiro}` : 'config';
-}
-
-const ARTIGO_POR_TIPO: Record<string, string> = {
-  string: 'a piece of text',
-  number: 'a number',
-  boolean: 'true or false',
-  array: 'a list',
-  object: 'an object',
-  null: 'null',
-};
-
-const COMO_ESCREVER: Record<string, string> = {
-  string: 'Write the value in double quotes, like "Core Platform".',
-  number: 'Write the value as a bare number, like 3 - no quotes.',
-  boolean: 'Write true or false - no quotes.',
-  array: 'Write the value as a list in square brackets: [ ... ].',
-  object: 'Write the value as an object in curly braces: { ... }.',
-};
-
-/** O tipo que o cliente REALMENTE escreveu, lido do JSON ja parseado em vez de
- *  extraido da mensagem do Zod por regex - o Zod v4 nao carrega `received` como
- *  propriedade, so dentro do texto, e depender do texto quebra na primeira vez
- *  que ele mudar de forma. */
-function tipoReal(valor: unknown): string {
-  if (valor === undefined) return 'missing';
-  if (valor === null) return 'null';
-  if (Array.isArray(valor)) return 'array';
-  return typeof valor;
-}
-
-function valorEm(raiz: unknown, caminho: (string | number)[]): unknown {
-  let atual: unknown = raiz;
-  for (const passo of caminho) {
-    if (atual === null || typeof atual !== 'object') return undefined;
-    atual = (atual as Record<string | number, unknown>)[passo];
-  }
-  return atual;
-}
-
-function comoCampo(caminho: (string | number)[]): string {
-  return caminho.length > 0 ? `"${caminho.join('.')}"` : 'writedocs.json';
-}
-
-/** A frase de chave desconhecida, num lugar so.
- *
- *  Decisao 6: chave desconhecida em sub-objeto strict e ERRO e na raiz e AVISO -
- *  a assimetria de SEVERIDADE e intencional e fica. A de VOCABULARIO nao: os
- *  dois caminhos chamam esta funcao, entao os dois dizem exatamente a mesma
- *  coisa, e so quem chama decide o peso. */
-function fraseChaveDesconhecida(chaves: string[], dentroDe: (string | number)[]) {
-  const onde = dentroDe.length > 0 ? ` inside "${dentroDe.join('.')}"` : '';
-  const lista = chaves.map((k) => `"${k}"`).join(', ');
-  return {
-    humanMessage:
-      chaves.length === 1
-        ? `${lista} is not a writedocs.json option${onde}.`
-        : `${lista} are not writedocs.json options${onde}.`,
-    suggestion: 'Remove it, or check the spelling - options are case-sensitive.',
-  };
-}
-
-/** A frase humana + a sugestao, escolhidas pelo CODIGO do Zod. `raiz` e o JSON
- *  ja parseado, usado so pra saber o que o cliente escreveu de fato. */
-function humanizar(issue: IssuePlano, raiz: unknown): { humanMessage?: string; suggestion?: string } {
-  const campo = comoCampo(issue.caminho);
-  switch (issue.code) {
-    case 'invalid_type': {
-      const esperado = issue.expected ?? 'a different type';
-      const recebido = tipoReal(valorEm(raiz, issue.caminho));
-      if (recebido === 'missing') {
-        return {
-          humanMessage: `${campo} is required, but writedocs.json does not set it.`,
-          suggestion: `Add ${campo} with ${ARTIGO_POR_TIPO[esperado] ?? `a ${esperado}`} as its value.`,
-        };
-      }
-      return {
-        humanMessage: `${campo} must be ${ARTIGO_POR_TIPO[esperado] ?? `a ${esperado}`}, but writedocs.json has ${ARTIGO_POR_TIPO[recebido] ?? `a ${recebido}`}.`,
-        suggestion: COMO_ESCREVER[esperado],
-      };
-    }
-    case 'unrecognized_keys': {
-      // O Zod agrega as chaves sobrando numa mensagem so, com o `path` no PAI.
-      const chaves = issue.keys ?? [];
-      if (chaves.length === 0) return {};
-      return fraseChaveDesconhecida(chaves, issue.caminho);
-    }
-    case 'invalid_value': {
-      const opcoes = (issue.values ?? []).map((v) => JSON.stringify(v)).join(', ');
-      return {
-        humanMessage: `${campo} must be one of: ${opcoes}.`,
-        suggestion: 'Replace the value with one of the options above.',
-      };
-    }
-    case 'too_small': {
-      const unidade = issue.origin === 'array' ? 'item' : 'character';
-      const minimo = issue.minimum ?? 1;
-      return {
-        humanMessage: `${campo} needs at least ${minimo} ${unidade}${minimo === 1 ? '' : 's'}.`,
-        suggestion: issue.origin === 'array' ? 'Add an entry, or remove the field entirely.' : undefined,
-      };
-    }
-    case 'too_big': {
-      const unidade = issue.origin === 'array' ? 'item' : 'character';
-      const maximo = issue.maximum ?? 0;
-      return { humanMessage: `${campo} allows at most ${maximo} ${unidade}${maximo === 1 ? '' : 's'}.` };
-    }
-    case 'invalid_format':
-      return {
-        humanMessage: `${campo} is not a valid ${issue.format ?? 'value'}.`,
-        suggestion: 'Check the format against the documentation for this field.',
-      };
-    case 'invalid_union':
-      // So chega aqui se o desembrulho nao achou ramo nenhum (uniao sem
-      // `errors`). Raro, mas melhor dizer o que aconteceu do que "Invalid input".
-      return {
-        humanMessage: `${campo} does not match any of the shapes writedocs.json accepts here.`,
-        suggestion: 'Check the documentation for the shapes this field accepts.',
-      };
-    case 'custom':
-      // As mensagens de `.refine()` deste schema ja sao frases escritas pra
-      // gente ("Each scripts.head/scripts.body entry needs exactly one of..."),
-      // entao reescrever seria piorar. Repassa como frase humana pra que quem
-      // exibe so `humanMessage` nao fique sem nada.
-      return { humanMessage: issue.message };
-    default:
-      return {};
-  }
-}
-
-/** Avisos de chave desconhecida na RAIZ.
- *
- *  A raiz nao e `.strict()` (decidido no E11-desenho-geral: tornar strict
- *  quebraria configs existentes), entao o Zod descarta a chave em silencio e
- *  nao ha issue nenhum. Quem quiser avisar chama isto. Mora aqui, e nao na
- *  plataforma, pelo motivo de sempre: era o unico texto escrito pela plataforma,
- *  e enquanto ele viver la os dois lados podem divergir.
- *
- *  Severidade e de quem chama - isto so descreve o problema. `validateDocsConfig`
- *  deliberadamente NAO chama: um config valido continua saindo com `issues: []`,
- *  porque a plataforma repassa `issues` como `errors` e um aviso ali viraria
- *  erro. */
-export function unknownRootKeyIssues(rawText: string): ValidationIssue[] {
-  let raiz: unknown;
-  try {
-    raiz = JSON.parse(rawText);
-  } catch {
-    return [];
-  }
-  if (raiz === null || typeof raiz !== 'object' || Array.isArray(raiz)) return [];
-  const conhecidas = new Set([...Object.keys(docsConfigSchema.shape), ...ROOT_ALLOWED_EXTRA_KEYS]);
-  const localizar = criarLocalizador(rawText);
-  return Object.keys(raiz as Record<string, unknown>)
-    .filter((chave) => !conhecidas.has(chave))
-    .map((chave) => {
-      const frase = fraseChaveDesconhecida([chave], []);
-      return {
-        path: chave,
-        // O mesmo formato singular da mensagem `unrecognized_keys` do Zod, pra
-        // que aviso e erro sejam indistinguiveis por quem so le `message`.
-        message: `Unrecognized key: "${chave}"`,
-        code: 'unrecognized_keys',
-        ...(localizar([chave]) ?? {}),
-        ...frase,
-        // `config`, e NAO `config.<chave>`: a chave aqui e o que o cliente
-        // digitou errado, e derivar a docKey dela faria cada erro de digitacao
-        // inventar uma chave nova. O conjunto de docKeys tem que ser fechado -
-        // `config` mais um por campo do schema, nada alem disso -, senao quem
-        // mapeia chave -> URL do outro lado nao tem lista pra mapear.
-        docKey: 'config',
-      };
-    });
-}
-
-export function validateDocsConfig(rawText: string): ValidationResult {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(rawText);
-  } catch (err) {
-    const parseError = err as SyntaxError;
-    const posicao = positionFromJsonError(parseError.message, rawText);
-    return {
-      ok: false,
-      data: null,
-      kind: 'invalid_json',
-      parseError,
-      issues: [
-        {
-          path: '(root)',
-          message: parseError.message,
-          code: 'invalid_json',
-          ...(posicao ?? {}),
-          humanMessage: 'writedocs.json is not valid JSON, so none of it could be checked.',
-          suggestion: posicao
-            ? `Look at line ${posicao.line} - a missing comma, an extra trailing comma, or an unclosed bracket is the usual cause.`
-            : 'A missing comma, an extra trailing comma, or an unclosed bracket is the usual cause.',
-          docKey: 'config',
-        },
-      ],
-    };
-  }
-
-  const result = docsConfigSchema.safeParse(raw);
-  if (!result.success) {
-    const localizar = criarLocalizador(rawText);
-    return {
-      ok: false,
-      data: null,
-      kind: 'schema',
-      issues: desembrulharUnioes(result.error.issues as IssueCru[]).map((i) => {
-        // Para chave desconhecida o `path` do Zod aponta pro PAI (`footer`), e a
-        // chave ofensora vem em `keys`. Para a LINHA vale a pena descer ate ela
-        // (`footer.banana`), que e onde o cliente precisa olhar; o `path` fica
-        // como o Zod deu, pra nao mudar o que a plataforma ja grava.
-        const alvoDaLinha =
-          i.code === 'unrecognized_keys' && i.keys?.length ? [...i.caminho, i.keys[0]] : i.caminho;
-        return {
-          path: i.caminho.join('.') || '(root)',
-          message: i.message,
-          code: i.code,
-          ...(localizar(alvoDaLinha) ?? localizar(i.caminho) ?? {}),
-          ...humanizar(i, raw),
-          docKey: docKeyDoCaminho(i.caminho),
-        };
-      }),
-    };
-  }
-
-  return { ok: true, data: result.data, issues: [] };
-}
+// O schema do writedocs.json, e nada alem disso.
+//
+// Este arquivo era as primeiras 875 linhas do config.ts (que continua
+// reexportando tudo daqui, entao nada que importa de './config.js' mudou). A
+// separacao existe por um motivo concreto: o config.ts importa node:fs,
+// node:path e gray-matter no topo pras funcoes que leem o disco, e o
+// package.json passou a exportar './config-schema' pra que a plataforma
+// (writedocs-application) possa importar o schema DE VERDADE - o mesmo que o
+// build usa - em vez de manter uma copia que diverge em algumas semanas. Um
+// Worker da Cloudflare nao consegue importar um modulo que traz node:fs junto.
+//
+// Por isso a unica dependencia aqui e o zod. Nada neste arquivo pode passar a
+// tocar o sistema de arquivos: se precisar de fs/path, o lugar e o config.ts.
+//
+// ESTE arquivo e a fonte de verdade, mas NAO e o que o pacote publica: o script
+// `prepare` (package.json) transpila ele pra ./config-schema.js, e e o `.js` que
+// o `exports` e o bin/writedocs.js apontam. Sem isso o `writedocs validate`
+// quebra pra quem instala o pacote - o Node recusa type stripping sob
+// node_modules. Editou aqui, rode `npm run build:schema` (ou qualquer
+// `npm install`) antes de testar o caminho da CLI ou da plataforma.
+//
+// (`zod` e nao `astro/zod`: as duas especificacoes resolvem pra mesma instalacao
+// - node_modules/zod 4.4.3, que e o que astro@7.2.2 tambem pede via `^4.3.6` -
+// entao a troca nao muda comportamento nenhum, so tira o astro do caminho de
+// quem importa isto de fora do gerador.)
+import { z } from 'zod';
+// WD-063: `parseTree` + `findNodeAtLocation` traduzem o caminho de um erro
+// (`navigation.products.0.product`) para o offset dele no TEXTO, que e o que
+// vira linha. E o parser de JSON do VS Code: zero dependencias, nada de `node:`,
+// entao continua bundlavel pro Worker da plataforma. Escrever o scanner a mao
+// foi tentado e deu errado (perdia todo caminho aninhado, que e justamente o que
+// importa aqui) - nao repita.
+import { findNodeAtLocation, parseTree } from 'jsonc-parser';
+
+// ---------------------------------------------------------------------
+// Pages & groups - the leaf content any container ultimately bottoms out
+// at. A group can nest other groups arbitrarily deep, and can optionally
+// link its own label to a page (`page`) independent of expanding or
+// collapsing its children - see NavTree.astro for how that renders.
+// ---------------------------------------------------------------------
+
+const navPageSchema = z.string();
+
+// A group ordinarily lists its own children by hand (`pages`), but can
+// instead auto-generate them from an OpenAPI spec via `openapi: { src,
+// path }` - resolved by loadDocsConfig() (via expandOpenApiInNavigation()
+// below, reading the manifest generate-api-pages.js writes for this exact
+// group) into a real `{ group, pages }` node - one sub-group per tag -
+// before anything else in this file ever sees it, so
+// resolveSections()/flattenNav()/buildNavTree()/etc. only ever need to
+// understand the ordinary pages-array shape. `.strict()` on both variants
+// is load-bearing (see withChildren()'s own comment on this pattern
+// below): without it, a group written with both `pages` and `openapi` at
+// once would silently have one dropped instead of rejected.
+const navGroupPagesSchema: z.ZodType<{ group: string; page?: string; pages: NavItem[] }> = z.lazy(() =>
+  z
+    .object({
+      group: z.string(),
+      page: z.string().optional(),
+      pages: z.array(navItemSchema),
+    })
+    .strict()
+);
+
+const navGroupOpenApiSchema = z.object({
+  group: z.string(),
+  openapi: z
+    .object({
+      // Path to an OpenAPI 3.x spec, relative to the content directory
+      // (alongside writedocs.json) - same convention the old top-level
+      // `openapi` field used. See generate-api-pages.js (the pre-Astro
+      // build/dev step that actually parses this and writes the
+      // manifest/operation JSON this group's pages are expanded from).
+      src: z.string(),
+      // Base URL path every page generated from this spec is namespaced
+      // under, e.g. "/api" -> pages served at /api/<tag>/<operation>/.
+      // Also doubles as this spec's own unique key under
+      // writedocsTempDir()'s openapi/<path>/ directory (manifest.json + operations/*.json),
+      // so two openapi groups in the same writedocs.json must use different
+      // `path` values - generate-api-pages.js throws a clear error if
+      // they collide.
+      path: z.string(),
+    })
+    .strict(),
+}).strict();
+
+export type GroupNavItem =
+  | { group: string; page?: string; pages: NavItem[] }
+  | { group: string; openapi: { src: string; path: string } };
+
+const navGroupSchema: z.ZodType<GroupNavItem> = z.union([navGroupPagesSchema, navGroupOpenApiSchema]);
+
+// A bare external link sitting directly in a `pages` array, alongside
+// page slugs and groups - e.g. a "Support" link to an external help
+// desk shown right in the sidebar, rather than only reachable via
+// navigation.global.dropdowns. Discriminated from navGroupSchema by
+// its required `label`/`href` keys (vs `group`/`pages`/`openapi`), so a
+// plain (non-strict at the union level) schema is enough for Zod to pick
+// the right branch; `.strict()` here still catches a typo'd extra key.
+const navLinkSchema = z.object({ label: z.string(), href: z.string() }).strict();
+
+const navItemSchema: z.ZodType<NavItem> = z.lazy(() =>
+  z.union([navPageSchema, navGroupSchema, navLinkSchema])
+);
+
+export type NavItem = string | GroupNavItem | { label: string; href: string };
+
+// ---------------------------------------------------------------------
+// Containers: tabs, versions, languages, dropdowns, products.
+//
+// This schema is modeled directly on Mintlify's writedocs.json
+// (https://mintlify.com/writedocs.json / mintlify.com/docs/organize/navigation):
+// all five container kinds are structurally identical except for their
+// own identifying field. Each owns *exactly one* of {pages, tabs,
+// versions, languages, dropdowns, products} as its content, or is a bare
+// external `href` link with no content of its own. That symmetry is what
+// lets any of them nest inside any other - a tab can contain versions, a
+// version can contain languages, a language can contain tabs, and so on,
+// bottoming out at a `pages` array. `withChildren()` is the single place
+// that shape is defined, instead of hand-writing the union five times.
+// ---------------------------------------------------------------------
+
+export type NavChildren =
+  | { pages: NavItem[] }
+  | { tabs: TabItem[] }
+  | { versions: VersionItem[] }
+  | { languages: LanguageItem[] }
+  | { dropdowns: DropdownItem[] }
+  | { products: ProductItem[] }
+  | { href: string };
+
+export type TabItem = { tab: string; icon?: string } & NavChildren;
+export type VersionItem = { version: string; label?: string; tag?: string; default?: boolean } & NavChildren;
+export type LanguageItem = { language: string; label?: string } & NavChildren;
+export type DropdownItem = { dropdown: string; icon?: string } & NavChildren;
+export type ProductItem = { product: string; icon?: string; description?: string } & NavChildren;
+
+// `.strict()` on every variant is load-bearing, not decoration: Zod
+// objects silently strip unrecognized keys by default, so without it a
+// node written with two children fields at once (e.g. both `pages` and
+// `versions`) would just have the second one dropped instead of
+// rejected - defeating the entire "exactly one child kind per level"
+// rule this schema exists to enforce (mirroring Mintlify's own "a tab
+// cannot contain both anchors and groups at the same level").
+function withChildren<Base extends z.ZodRawShape>(base: Base) {
+  return z.union([
+    z.object({ ...base, pages: z.array(navItemSchema) }).strict(),
+    z.object({ ...base, tabs: z.array(tabSchema).min(1) }).strict(),
+    z.object({ ...base, versions: z.array(versionSchema).min(1) }).strict(),
+    z.object({ ...base, languages: z.array(languageSchema).min(1) }).strict(),
+    z.object({ ...base, dropdowns: z.array(dropdownSchema).min(1) }).strict(),
+    z.object({ ...base, products: z.array(productSchema).min(1) }).strict(),
+    z.object({ ...base, href: z.string() }).strict(),
+  ]);
+}
+
+// Each of these five is defined via z.lazy() because withChildren()
+// references all five by name (mutual recursion) - safe because none of
+// them are actually *called* until a real writedocs.json is parsed, by which
+// point every const below has been assigned. The same pattern already
+// used for navItemSchema/navGroupSchema above.
+const tabSchema: z.ZodType<TabItem> = z.lazy(() =>
+  withChildren({ tab: z.string(), icon: z.string().optional() })
+);
+
+const versionSchema: z.ZodType<VersionItem> = z.lazy(() =>
+  withChildren({
+    version: z.string(),
+    label: z.string().optional(),
+    tag: z.string().optional(),
+    default: z.boolean().optional(),
+  })
+);
+
+const languageSchema: z.ZodType<LanguageItem> = z.lazy(() =>
+  withChildren({ language: z.string(), label: z.string().optional() })
+);
+
+const dropdownSchema: z.ZodType<DropdownItem> = z.lazy(() =>
+  withChildren({ dropdown: z.string(), icon: z.string().optional() })
+);
+
+const productSchema: z.ZodType<ProductItem> = z.lazy(() =>
+  withChildren({ product: z.string(), icon: z.string().optional(), description: z.string().optional() })
+);
+
+// ---------------------------------------------------------------------
+// Root navigation: a flat array (shorthand for one implicit section - the
+// common case) or an object choosing exactly one primary organizational
+// pattern, per Mintlify's convention ("choose one primary organizational
+// pattern at the root level of your navigation").
+//
+// `global.dropdowns` is the one exception to "exactly one pattern": it's
+// not a primary pattern, it's a persistent set of topbar dropdown
+// triggers that render on every page regardless of which tab/version/
+// language/product is active - equivalent to Mintlify's
+// `navigation.global.anchors`. This replaces the earlier `{tabs,
+// dropdowns}` shape (both present at once), which doesn't generalize
+// once versions/languages/products are also root-level choices.
+// ---------------------------------------------------------------------
+
+export type NavigationConfig =
+  | NavItem[]
+  | { global?: { dropdowns: DropdownItem[] }; tabs: TabItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; versions: VersionItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; languages: LanguageItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; dropdowns: DropdownItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; products: ProductItem[] };
+
+const globalSchema = z.object({ dropdowns: z.array(dropdownSchema).min(1) });
+
+const navigationSchema = z.union([
+  z.array(navItemSchema),
+  z.object({ global: globalSchema.optional(), tabs: z.array(tabSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), versions: z.array(versionSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), languages: z.array(languageSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), dropdowns: z.array(dropdownSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), products: z.array(productSchema).min(1) }).strict(),
+]) as z.ZodType<NavigationConfig>;
+
+const DEFAULT_PRIMARY = '#6366f1';
+
+// A logo is either one path used for both color modes, or a
+// { light, dark, label } object - each image shown only while that mode
+// is active (see BaseLayout.astro's .wd-logo-light/.wd-logo-dark CSS).
+// The topbar shows *only* the image by default - no site name text next
+// to it, since a real logo asset usually already is a wordmark. `label`
+// is the opt-in way to add text back next to the image (e.g. a product
+// name alongside a symbol-only mark); it only exists on the object form,
+// since a single shared image path is just as easy to bake the label
+// into directly.
+//
+// `light`/`dark` are themselves optional (unlike the string form, which
+// is inherently "both"): a site with no logo *images* at all can still
+// set `styles.logo: { label: "..." }` to override the topbar's fallback
+// text without providing any image - see BaseLayout.astro's
+// hasLogoImage/logoLabel/brandLabel derivation, where an object with
+// only `label` set already resolves correctly (brandLabel = logoLabel,
+// same as if an image were also present) without needing any change
+// there; only this schema needed loosening; light/dark were previously
+// both required whenever the object form was used at all.
+//
+// Standalone const (rather than inlined into stylesSchema.logo below) so
+// footer.logo further down can share the exact same union instead of an
+// independently-written copy - see footerSchema's own comment on why a
+// footer logo needs this at all.
+const logoSchema = z.union([
+  z.string(),
+  z.object({ light: z.string().optional(), dark: z.string().optional(), label: z.string().optional() }).strict(),
+]);
+
+// Same {light, dark}-with-fallback shape applies to `colors.dark`: any
+// of primary/text left unset there falls back to the light-mode value
+// already given above, so a site only has to specify what actually
+// differs in dark mode. There used to be a `background`/`dark.background`
+// pair here too, doing effectively the same job as `background.colors`
+// further down (see that field's own comment) - two writedocs.json fields
+// both named "background" that visually looked interchangeable but
+// weren't quite (one drove --wd-background site-wide, the other only
+// the <body> canvas), which was confusing to author against and easy to
+// half-configure by setting only one. Removed in favor of `background`
+// alone being the single place to set any background color - see that
+// field's comment for what it now covers.
+// One side of `styles.navbar` (light or dark) - either a bare background
+// color (the original shape) or `{ background, accent? }` once a site
+// wants its own accent color (the active-tab fill / hover underline)
+// inside the navbar specifically, independent of the sitewide
+// `styles.colors.primary`. Deliberately does NOT carry a text/icon color
+// field at all - see `navbar`'s own comment below (stylesSchema) for why
+// that's resolved automatically instead of being configurable. Kept as a
+// standalone const rather than inlined so `light`/`dark` share the exact
+// same union rather than two independently-written (and possibly
+// drifting) copies of it.
+const navbarColorValueSchema = z.union([
+  z.string(),
+  z
+    .object({
+      background: z.string(),
+      accent: z.string().optional(),
+    })
+    .strict(),
+]);
+
+// One font declaration - almost exactly Mintlify's own `fonts` shape (see
+// docs/dev/docs/site-config.mdx's own "Fonts" section for the research this
+// was based on): a bare Google Fonts family name (`family` alone - Google
+// Fonts loads it automatically, see googleFontsHref() below), or a local/
+// externally-hosted font file (`source` + `format` together; `source` is
+// either a project-relative path like the other five asset-fallback fields
+// this schema already has - see collectConfiguredAssetPaths() - or a full
+// https:// URL to an externally-hosted font). `weight` does two things at
+// once, both driven by BaseLayout.astro: it narrows which file actually
+// loads (folded into the Google Fonts URL's `:wght@` axis, or the
+// generated `@font-face` rule's own `font-weight` descriptor for a
+// `source` font - see googleFontsHref()/fontFaceRule() below), *and* it's
+// applied as a real CSS `font-weight` on h1-h6 (for `heading`) or `body`
+// (for `body`) - see BaseLayout's own `wdFontWeightHeading`/
+// `wdFontWeightBody`. Both halves matter: loading only the 400-weight file
+// while leaving h1-h6 at the browser's UA-default `font-weight: bold`
+// faux-bolds that file back to looking bold anyway, with no visible
+// change from configuring a lighter weight at all - the bug this second
+// half fixes (caught from real user-reported behavior, not anticipated
+// up front). Left unset anywhere in `styles.fonts` renders no font-weight
+// rule at all, keeping today's plain browser-default bold headings/normal
+// body text unchanged for a site that hasn't touched this field.
+const fontVariantSchema = z
+  .object({
+    family: z.string(),
+    weight: z.number().optional(),
+    source: z.string().optional(),
+    format: z.enum(['woff', 'woff2']).optional(),
+  })
+  .strict();
+
+export type FontVariant = z.infer<typeof fontVariantSchema>;
+
+// The top-level shape adds `heading`/`body`: each independently optional,
+// each falling back to the top-level family/weight/source/format when
+// unset (see resolveFonts() below) - so a site can set one font for
+// everything (`fonts.family` alone), or split headings and body text
+// without needing to repeat itself for whichever side isn't changing.
+const fontsSchema = z
+  .object({
+    family: z.string(),
+    weight: z.number().optional(),
+    source: z.string().optional(),
+    format: z.enum(['woff', 'woff2']).optional(),
+    heading: fontVariantSchema.optional(),
+    body: fontVariantSchema.optional(),
+  })
+  .strict();
+
+export type FontsConfig = z.infer<typeof fontsSchema>;
+
+const stylesSchema = z
+  .object({
+    colors: z
+      .object({
+        primary: z.string().default(DEFAULT_PRIMARY),
+        text: z.string().optional(),
+        dark: z
+          .object({
+            primary: z.string().optional(),
+            text: z.string().optional(),
+          })
+          .optional(),
+      })
+      .default({ primary: DEFAULT_PRIMARY }),
+    logo: logoSchema.optional(),
+    favicon: z.string().optional(),
+    // No default value here (unlike `colors.primary`'s DEFAULT_PRIMARY) -
+    // resolveFonts() below is where "Inter" actually gets applied as the
+    // site-wide default whenever this field is left unset entirely, so
+    // that fallback lives in one place alongside the rest of the
+    // resolution logic rather than being duplicated as a schema default
+    // *and* a resolver fallback.
+    fonts: fontsSchema.optional(),
+    // The Shiki theme *name* (not a full theme object/JSON - see
+    // https://shiki.style/themes for the built-in list) each fenced
+    // (```) MDX code block, and the API playground's request/response
+    // snippets, use in light/dark mode - read out of writedocs.json by both
+    // astro.config.mjs (Shiki's dual-theme markdown config) and
+    // ApiReferencePanel.astro (its own separate <Code/> usages, which
+    // don't inherit markdown.shikiConfig) via resolveCodeblockTheme()
+    // below, the single source of truth for the 'github-light'/
+    // 'github-dark' fallback. Left per-key optional (not defaulted in
+    // the schema itself) so a site can override just one side (e.g.
+    // only `dark`) and still get the ordinary default for the other.
+    codeblocks: z
+      .object({
+        light: z.string().optional(),
+        dark: z.string().optional(),
+        // Maps a fenced (```) block's own language tag to whichever real
+        // Shiki grammar actually highlights it, before that tag ever
+        // reaches Shiki - see resolveCodeblockLangAlias() below for the
+        // one built-in entry (mdx -> jsx) this ships with by default and
+        // why. A site can add its own entries for any other language tag
+        // that either doesn't tokenize well under its own grammar, or
+        // that a site wants to write under a shorter/friendlier fence tag
+        // than Shiki's own bundled id (e.g. `groovy: 'java'` for a close-
+        // enough approximation Shiki doesn't ship a dedicated grammar for
+        // at all) - merged with, not replacing, the built-in default, so
+        // adding one of a site's own doesn't require re-declaring mdx.
+        langAlias: z.record(z.string(), z.string()).optional(),
+      })
+      .strict()
+      .optional(),
+    // The topbar's own background, independent of `background` below (the
+    // page's) - a site may want its navbar to stand out (a dark or
+    // brand-colored bar over a light page) rather than blend into the
+    // page, which is the default when this is left unset. Same {light,
+    // dark} shape (and same per-key-optional, not defaulted here) as
+    // `codeblocks` right above, rather than nested under `colors` - it's a
+    // topbar-specific override, not a third general-purpose page color, so
+    // it reads more like "one more themed surface" alongside codeblocks
+    // than a sibling of primary/text. BaseLayout.astro's own
+    // lightNavbarBg/darkNavbarBg resolution is what falls each side back
+    // to the page background when unset.
+    //
+    // Each side (`light`/`dark`) is either a bare string - just the
+    // background color, exactly the original shape, kept for backwards
+    // compatibility - or `{ background, accent? }`, for when a site also
+    // wants the navbar's own active-tab-fill/hover-underline color to
+    // differ from the sitewide `styles.colors.primary` (`accent`'s only
+    // job - see BaseLayout.astro's lightNavbarAccent). Deliberately no
+    // text/icon color field here at all: BaseLayout.astro always resolves
+    // the navbar's plain text/icon color itself, picking black or white by
+    // contrast against whatever `background` resolves to
+    // (contrastTextColor() below) the moment this field is configured at
+    // all (string or object) - never a value read from writedocs.json. A
+    // manually-set text color is a legibility footgun a site author can
+    // get wrong (or drift out of sync after later changing `background`
+    // without remembering to update it too) in a way "compute it
+    // correctly, every time" simply can't - there's no legitimate reason
+    // to want *illegible* navbar text, unlike `accent`, which is a real
+    // aesthetic choice. Real bug this fixes: a site setting `navbar.light`
+    // to the same value as `colors.primary` (a plausible thing to reach
+    // for - "brand-colored navbar") made every topbar label/icon/link
+    // render in the default near-black text color against that same
+    // saturated background, all but unreadable - and an earlier version of
+    // this feature that let a writedocs.json-supplied color double as the text
+    // color reintroduced the identical bug one level down, just requiring
+    // one more (still guessable-wrong) field to trigger it.
+    navbar: z
+      .object({
+        light: navbarColorValueSchema.optional(),
+        dark: navbarColorValueSchema.optional(),
+      })
+      .strict()
+      .optional(),
+    // The single place to configure any background color: `colors` is a
+    // solid color (falls back to '#ffffff'/'#0b1120' when unset - see
+    // BaseLayout.astro's lightBackground/darkBackground resolution), and
+    // `images` layers an image on top of it (or is the whole background
+    // by itself, if `colors` is left at its default). This one pair now
+    // drives everything background-related site-wide - --wd-background
+    // (dropdowns/modals/kbd chips/footer/topbar-fallback/etc., see every
+    // `var(--wd-background)` call site) *and* the <body> canvas behind the
+    // main/toc columns - rather than the two being independently
+    // configurable fields that happened to look alike but didn't affect
+    // the same things (see this schema's own comment on `colors.dark`
+    // above for why that split was removed). Both are per-mode optional,
+    // same "only specify what differs" pattern as codeblocks/navbar above.
+    // The topbar and footer still get their own explicit opaque
+    // background (topbar.css/footer.css) specifically so an `images`
+    // background doesn't show through them; see those files' own
+    // comments. The sidebar column has no background of its own (base.css)
+    // and lets it show through, same as the main/toc columns.
+    background: z
+      .object({
+        colors: z
+          .object({
+            light: z.string().optional(),
+            dark: z.string().optional(),
+          })
+          .strict()
+          .optional(),
+        images: z
+          .object({
+            light: z.string().optional(),
+            dark: z.string().optional(),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .default({ colors: { primary: DEFAULT_PRIMARY } });
+
+// `href` is always required - a link with nowhere to go isn't a link.
+// `label`/`icon` are each individually optional, but not both at once
+// (enforced by the .refine() below, same shape as scriptEntrySchema's own
+// exactly-one-of check above) - a link needs *something* visible to render,
+// whichever of the two, and can have both (icon rendered to the left of the
+// label - see TopBar.astro/SiteFooter.astro, the two renderers of this
+// shape). An icon-only link (no label) is the common case for something
+// like a bare GitHub mark in the topbar; label-only (no icon) is every
+// plain text link this already supported before `icon` existed - both
+// still need to keep working unchanged, hence neither field being outright
+// required on its own.
+const topbarLinkSchema = z
+  .object({
+    label: z.string().optional(),
+    href: z.string(),
+    // Same string shape as every other writedocs.json `icon` field (a plain
+    // Lucide name, or the explicit "collection:icon-name" form for
+    // anything else - see resolveIcon()/AppIcon.astro) - not documented
+    // again here since that convention is already established elsewhere
+    // in this file (tabs/switchers/socials all take the identical shape).
+    icon: z.string().optional(),
+  })
+  .strict()
+  .refine((link) => Boolean(link.label) || Boolean(link.icon), {
+    message: 'Each topbar.links/footer column link needs a "label", an "icon", or both - a link with neither has nothing to render.',
+  });
+
+// One column of the footer (BaseLayout.astro's <footer class="wd-footer">) -
+// an optional heading (e.g. "Resources", "Community") plus a list of links,
+// reusing the exact same {label, icon, href} shape as topbar.links above (a
+// footer link is the same thing rendered in a different place, no reason
+// for a second, identical-but-differently-named schema). `title` is
+// optional so a single-column footer with no heading (just a bare list of
+// links) is valid too.
+const footerColumnSchema = z
+  .object({
+    title: z.string().optional(),
+    links: z.array(topbarLinkSchema).default([]),
+  })
+  .strict();
+
+// Off by default (empty `columns`, same convention as `topbar` above - a
+// footer with nothing configured just doesn't render at all, see
+// BaseLayout.astro's `hasFooterContent` check) rather than `.optional()`
+// like contextMenu: unlike that field, an empty/default footer has no
+// build-output or routing implications to gate, it's purely visual, so
+// there's no reason to distinguish "unset" from "set to nothing" the way
+// contextMenu needs to.
+// Same {light, dark, label} union as `styles.logo` (via the shared
+// logoSchema above) - unset by default, in which case the footer just
+// shows the sitewide `styles.logo` (BaseLayout.astro's existing
+// logoLight/logoDark/logoLabel, already threaded into SiteFooter as-is).
+// Set here, it replaces that entirely rather than filling in only the
+// missing side of it - a footer.logo with only `dark` set shows *just*
+// the dark-mode image, not styles.logo's light image plus this dark one -
+// the same all-or-nothing-relative-to-styles.logo resolution BaseLayout.astro
+// already applies.
+const footerSchema = z
+  .object({
+    columns: z.array(footerColumnSchema).default([]),
+    logo: logoSchema.optional(),
+  })
+  .strict()
+  .default({ columns: [] });
+
+export type FooterColumn = z.infer<typeof footerColumnSchema>;
+export type FooterConfig = z.infer<typeof footerSchema>;
+
+// Shared by both writedocs.json's top-level `seo` (site-wide defaults) and a
+// page's own frontmatter `seo` (per-page overrides) - see
+// content.config.ts's docsSchema, which imports this exact schema rather
+// than redeclaring the same shape a second time. mergeSeo() below is what
+// actually combines the two, field by field, at render time.
+export const seoFieldsSchema = z
+  .object({
+    // Open Graph / Twitter card image - a relative path (resolved against
+    // `domain` below into an absolute URL, since most social crawlers
+    // require one) or an already-absolute https:// URL.
+    ogImage: z.string().optional(),
+    // og:type - "website" for most pages, "article" for blog-post-shaped
+    // content, etc. Defaults to "website" if never set anywhere.
+    ogType: z.string().optional(),
+    twitterCard: z.enum(['summary', 'summary_large_image']).optional(),
+    keywords: z.array(z.string()).optional(),
+    // Renders <meta name="robots" content="noindex, nofollow" /> and
+    // (see astro.config.mjs's sitemap `filter`) excludes the page from
+    // sitemap.xml entirely - both driven off this one flag, since listing
+    // a page in the sitemap while also telling crawlers not to index it
+    // would be self-contradictory.
+    noindex: z.boolean().optional(),
+  })
+  .strict();
+
+export type SeoFields = z.infer<typeof seoFieldsSchema>;
+
+/** Field-by-field merge of a page's own `seo` frontmatter over writedocs.json's
+ *  site-wide `seo` defaults - a page only overrides the specific fields it
+ *  sets, falling back to the site default for everything else, rather than
+ *  a page's (possibly partial) `seo` object replacing the site's wholesale. */
+export function mergeSeo(site: SeoFields, page?: SeoFields): SeoFields {
+  if (!page) return site;
+  return {
+    ogImage: page.ogImage ?? site.ogImage,
+    ogType: page.ogType ?? site.ogType,
+    twitterCard: page.twitterCard ?? site.twitterCard,
+    keywords: page.keywords ?? site.keywords,
+    noindex: page.noindex ?? site.noindex,
+  };
+}
+
+const MINTLIFY_MODE_ALIASES: Record<string, string> = { center: 'frame', assistant: 'default' };
+
+/** A page's own frontmatter - the `pages` and `generatedDocs` content
+ *  collections' schema (content.config.ts), and what `writedocs validate`
+ *  checks every page against. */
+export const pageFrontmatterSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  // Overrides the URL this page is served at, independent of where the
+  // file actually lives - writedocs.json's `pages` arrays always keep
+  // referencing the file's own path regardless. This is Astro's own
+  // glob()-loader convention (a `slug` frontmatter field becomes
+  // `entry.id` verbatim - see generateIdDefault in
+  // astro/dist/content/loaders/glob.js), not writedocs-specific
+  // behavior; declaring it here just brings it into the schema (and
+  // its docs) rather than leaving it an undocumented Astro feature.
+  // See fileIdForEntry() in lib/config.ts for how routes/links still
+  // resolve a page by its file id once this diverges from `entry.id`.
+  // Leading/trailing slashes are fine either way ("/", "/guides/x",
+  // "guides/x" and "guides/x/" all mean the same thing) - see
+  // normalizeEntryId() in lib/config.ts, which is what actually
+  // strips them before this value is ever used as a route or href.
+  slug: z.string().optional(),
+  // Marks this page as an OpenAPI operation reference: "METHOD /path"
+  // matching an operation in the owning group's OpenAPI spec, e.g.
+  // "GET /pets/{petId}" - [...slug].astro renders <ApiPlayground /> for
+  // any page with this field set, below the page's own MDX body (if
+  // any). Sites don't write this by hand for most pages; it's either
+  // set on a generated stub in the `generatedDocs` collection below (see
+  // generate-api-pages.js) or hand-authored to "eject" one specific
+  // operation into a real file (in `docs`) with custom prose - either
+  // way, the value is always exactly the same "METHOD /path" key
+  // generate-api-pages.js uses to look up the operation's full resolved
+  // schema/examples at render time.
+  openapi: z.string().optional(),
+  // Controls how much of the site's own chrome (topbar, sidebar, table of
+  // contents) wraps this page - see BaseLayout.astro/[...slug].astro for
+  // what each value actually removes:
+  //   default - the normal three-column reading layout (all chrome).
+  //   wide    - drops the table of contents; the article itself also
+  //             renders wider, for content that wants the extra room
+  //             (wide tables, side-by-side images).
+  //   frame   - drops the sidebar and table of contents, but keeps the
+  //             topbar and the article's own normal presentation
+  //             ("frame" as in: still inside the site's outer frame).
+  //   custom  - drops the sidebar and table of contents, the
+  //             auto-rendered <h1>, and prev/next nav, and skips the
+  //             article's own prose width/padding too - a blank canvas
+  //             for a hand-built landing/home page made entirely of
+  //             components - but keeps the topbar, so the page still
+  //             has site branding/nav/search/theme-toggle available.
+  //   blank   - everything 'custom' drops, plus the topbar too: no site
+  //             chrome at all, just <slot />. For a page that wants to
+  //             look nothing like the rest of the site (an auth screen,
+  //             a print-style page).
+  //
+  // Two Mintlify values are accepted so a migrated page doesn't fail the
+  // build (see MINTLIFY_MODE_ALIASES above): `center` is the same layout
+  // as our `frame`, and `assistant` (a full-page Mintlify AI chat, which
+  // writedocs doesn't have) falls back to `default`. Mintlify's own
+  // `frame` means something else (a canvas that keeps the sidebar) - it's
+  // left as our `frame`; see docs/dev/docs/mintlify-compat.mdx.
+  mode: z
+    .preprocess(
+      (value) => (typeof value === 'string' && value in MINTLIFY_MODE_ALIASES ? MINTLIFY_MODE_ALIASES[value] : value),
+      z.enum(['default', 'wide', 'frame', 'custom', 'blank']),
+    )
+    .default('default'),
+  // Per-page meta tag overrides - same shape as writedocs.json's top-level
+  // `seo` (see seoFieldsSchema in lib/config.ts, the single source of
+  // truth for this shape). A page only needs to set the specific fields
+  // it wants to override; mergeSeo() falls back to the site-wide default
+  // for anything left unset. See BaseLayout.astro for where this and the
+  // site-wide seo actually get merged and rendered.
+  seo: seoFieldsSchema.optional(),
+  // Mintlify's spelling of `seo.noindex` - a top-level `noindex: true`.
+  // Folded into `seo` by the transform below, so everything downstream
+  // (the robots meta tag, sitemap.xml, llms.txt) keeps reading
+  // `seo.noindex` only.
+  noindex: z.boolean().optional(),
+  // Mintlify's short navigation label - used for the sidebar and the
+  // topbar dropdown menus in place of `title` ([...slug].astro's
+  // navTitleForSlug). The page's own <h1> and prev/next links keep `title`.
+  sidebarTitle: z.string().optional(),
+  // Mintlify's spellings of `seo.keywords`, `seo.ogImage`, `seo.ogType`
+  // and `seo.twitterCard`, folded into `seo` below like `noindex`.
+  keywords: z.array(z.string()).optional(),
+  'og:image': z.string().optional(),
+  'og:type': z.string().optional(),
+  'twitter:card': z.enum(['summary', 'summary_large_image']).optional(),
+  // Mintlify's sidebar/page-chrome fields - see NavTree.astro and
+  // [...slug].astro for where each is used:
+  //   icon                 - shown before the page's label in the sidebar.
+  //   tag                  - a short label after it (e.g. "NEW").
+  //   deprecated           - a "Deprecated" label in the sidebar and next
+  //                          to the page's <h1>.
+  //   hidden               - left out of the sidebar, dropdowns and
+  //                          prev/next, but still built and reachable by
+  //                          URL. Also noindexed, as on Mintlify.
+  //   url                  - an external link: the page's sidebar entry
+  //                          links straight to it, and the page's own URL
+  //                          redirects there.
+  //   hideFooterPagination - no prev/next links on this page.
+  //   hideApiMarker        - no HTTP method badge on this page's sidebar
+  //                          entry.
+  icon: z.string().optional(),
+  tag: z.string().optional(),
+  deprecated: z.boolean().optional(),
+  hidden: z.boolean().optional(),
+  url: z.string().optional(),
+  hideFooterPagination: z.boolean().optional(),
+  hideApiMarker: z.boolean().optional(),
+}).transform(
+  ({ noindex, keywords, 'og:image': ogImage, 'og:type': ogType, 'twitter:card': twitterCard, ...data }) => {
+    // Top-level Mintlify keys fill in `seo` only where the page's own `seo`
+    // doesn't already set that field - an explicit `seo` value always wins.
+    // A `hidden` page is noindexed unless it says otherwise.
+    const fromMintlify = { noindex: noindex ?? (data.hidden ? true : undefined), keywords, ogImage, ogType, twitterCard };
+    const seo = { ...data.seo };
+    let changed = false;
+    for (const [key, value] of Object.entries(fromMintlify)) {
+      if (value === undefined || seo[key as keyof typeof seo] !== undefined) continue;
+      (seo as Record<string, unknown>)[key] = value;
+      changed = true;
+    }
+    return changed ? { ...data, seo } : data;
+  },
+);
+
+// Controls for the OpenAPI API playground's "Try it" modal - separate
+// from a group's own `openapi: { src, path }` field (which spec to use,
+// and where) since this is about how a *request* it sends behaves, not
+// about the spec itself.
+const apiSchema = z
+  .object({
+    // Whether the Try-it modal's Send button routes its request through
+    // writedocs' own CORS proxy (https://proxy.writechoice.io/) rather
+    // than calling the API directly from the browser. Almost no
+    // real-world API sends back Access-Control-Allow-Origin headers
+    // permitting an arbitrary docs site's origin, so a direct browser
+    // fetch() from the Try-it modal fails for most real APIs without
+    // this - see PROXY_BASE_URL in ApiReferencePanel.astro for the
+    // actual request-forwarding logic. Defaults to enabled; a site can
+    // set this to `false` to always call the API directly instead (the
+    // API is already CORS-permissive, same-origin in some deployments,
+    // or the site owner doesn't want requests routed through a third
+    // party at all).
+    proxy: z.boolean().default(true),
+  })
+  .strict()
+  .default({ proxy: true });
+
+// The "Copy page" dropdown shown next to a page's title - copy the raw
+// Markdown to the clipboard, open the raw Markdown in a new tab, or
+// deep-link into an AI assistant with a prompt pointing at it. Opt-in:
+// undefined (the field simply absent from writedocs.json) means the feature
+// is off entirely - no menu rendered, no .md routes generated at build
+// time either (see [...slug].md.ts) - rather than defaulting to on,
+// since it changes both the UI and the build output. Once a site does
+// write a `contextMenu` key (even `{}`), copying/viewing-as-Markdown are
+// always included (they need nothing but the page's own content); only
+// `openIn` (the AI-assistant deep-links, which need an absolute URL to
+// point the assistant at) is independently configurable.
+const contextMenuSchema = z
+  .object({
+    openIn: z.array(z.enum(['chatgpt', 'claude', 'perplexity'])).default(['chatgpt', 'claude', 'perplexity']),
+  })
+  .strict();
+
+export type ContextMenuConfig = z.infer<typeof contextMenuSchema>;
+
+// One entry in writedocs.json's `redirects` array - wired almost directly into
+// Astro's own `redirects` config option (astro.config.mjs), which is what
+// actually generates the redirect pages. `permanent` is deliberately not
+// part of this schema: with no server/adapter (this project always builds
+// `output: 'static'` with none installed), Astro's own docs say a static
+// redirect "does not support status codes" at all - it's always a client-
+// side `<meta http-equiv="refresh">` page, full stop. Accepting a
+// `permanent` field here that silently did nothing would be worse than
+// not offering it.
+const redirectSchema = z
+  .object({
+    source: z.string(),
+    destination: z.string(),
+  })
+  .strict();
+
+export type RedirectConfig = z.infer<typeof redirectSchema>;
+
+// A site-wide banner rendered above the topbar on every page (except
+// `mode: blank`, which drops all site chrome including this - see
+// BaseLayout.astro). Optional/undefined by default, same convention as
+// `contextMenu` above - a site with no banner configured gets no banner
+// markup at all, not an empty one.
+const bannerSchema = z
+  .object({
+    content: z.string(),
+    // Persisted via localStorage once dismissed (see BaseLayout.astro's
+    // initBanner()) - a static site has no server-side session to track
+    // this against, so "dismissed" only ever means "dismissed in this
+    // browser". A banner without `dismissible` reappears on every visit,
+    // appropriate for something that should stay visible until the site
+    // author removes it from writedocs.json themselves (e.g. "this version is
+    // deprecated"), not something a reader can permanently clear.
+    dismissible: z.boolean().default(false),
+    type: z.enum(['info', 'warning', 'critical']).default('info'),
+  })
+  .strict();
+
+export type BannerConfig = z.infer<typeof bannerSchema>;
+
+// Content for the custom 404 page (src/pages/404.astro) - Astro's own
+// file-based convention (a static build emits this as 404.html at the
+// site root; most static hosts pick it up automatically for unmatched
+// routes). Both fields are optional with hardcoded fallbacks in 404.astro
+// itself, so a site doesn't have to set either to get a reasonably
+// branded 404 page (still rendered inside the normal BaseLayout/topbar
+// chrome, just with placeholder content).
+const notFoundSchema = z
+  .object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .strict()
+  .default({});
+
+export type NotFoundConfig = z.infer<typeof notFoundSchema>;
+
+// One <script> tag to inject - exactly one of `src` (an external/local
+// file, rendered as `<script src="...">`) or `content` (inline JS,
+// rendered via `<script is:inline set:html="...">`) has to be set, not
+// both and not neither - enforced by the `.refine()` below rather than
+// leaving both optional and silently rendering an empty tag if a site
+// author gets this wrong.
+const scriptEntrySchema = z
+  .object({
+    src: z.string().optional(),
+    content: z.string().optional(),
+  })
+  .strict()
+  .refine((v) => (v.src ? !v.content : !!v.content), {
+    message: 'Each scripts.head/scripts.body entry needs exactly one of "src" or "content", not both or neither.',
+  });
+
+export type ScriptEntry = z.infer<typeof scriptEntrySchema>;
+
+// Raw third-party script injection - analytics snippets, chat widgets,
+// anything that needs a real <script> tag writedocs.json's own structured
+// fields (styles, integrations-style config, ...) don't have a dedicated
+// slot for yet. `head` renders right before </head>; `body` renders right
+// before </body> (after everything else has already loaded/hydrated -
+// see BaseLayout.astro), matching where a third-party script's own
+// install instructions usually say to put it.
+const scriptsSchema = z
+  .object({
+    head: z.array(scriptEntrySchema).default([]),
+    body: z.array(scriptEntrySchema).default([]),
+  })
+  .strict()
+  .default({ head: [], body: [] });
+
+export type ScriptsConfig = z.infer<typeof scriptsSchema>;
+
+// writedocs.json's `integrations` - a curated, high-value subset of analytics
+// providers, each getting its own minimal config object (just the id(s)
+// it actually needs) rather than requiring a site author to hand-write
+// the provider's own install snippet through the generic `scripts` field
+// above. This is deliberately its own thing, not built as sugar over
+// `scripts` the way the roadmap once implied it might be - most of these
+// providers' real snippets need `defer`/`async`/`data-*` attributes
+// ScriptEntry's plain `{ src?, content? }` shape has no way to express,
+// so BaseLayout.astro renders each provider with its own bespoke markup
+// instead of generating a ScriptEntry array to feed through the generic
+// renderer. Every snippet shape below was sourced from that provider's
+// own current official docs (fetched directly, not recalled from
+// training data) while building this feature - see
+// docs/dev/docs/integrations.mdx for links and dates.
+//
+// Every provider field is optional and independent - a site can turn on
+// any subset (including all of them at once, for a migration period) or
+// none. No "the" analytics field; a site picks whichever provider(s) it
+// actually uses.
+
+const ga4IntegrationSchema = z
+  .object({
+    // A GA4 "Measurement ID", always shaped like "G-XXXXXXXXXX" - not
+    // validated against that shape here, since Google could change the
+    // prefix/length without this schema needing to track it.
+    measurementId: z.string(),
+  })
+  .strict();
+
+const googleTagManagerIntegrationSchema = z
+  .object({
+    // A GTM container id, shaped like "GTM-XXXXXXX".
+    containerId: z.string(),
+  })
+  .strict();
+
+const plausibleIntegrationSchema = z
+  .object({
+    domain: z.string(),
+    // Plausible's own hosted script URL by default - override for a
+    // self-hosted instance, a reverse-proxy path (Plausible's own
+    // documented way to dodge ad-blockers), or one of Plausible's
+    // documented script *extensions* (e.g.
+    // "https://plausible.io/js/script.hash.outbound-links.js").
+    src: z.string().default('https://plausible.io/js/script.js'),
+  })
+  .strict();
+
+const fathomIntegrationSchema = z
+  .object({
+    // Fathom's own short "Site ID", not a full URL or measurement id.
+    siteId: z.string(),
+  })
+  .strict();
+
+const posthogIntegrationSchema = z
+  .object({
+    // PostHog calls this a "project API key" (starts with "phc_") in its
+    // own docs - `apiKey` here rather than that exact name, matching this
+    // schema's own plainer naming convention for the equivalent id on
+    // every other provider above.
+    apiKey: z.string(),
+    // PostHog is region-sharded (US/EU) with no single universal default
+    // - "https://us.i.posthog.com" is PostHog's own default for a new
+    // project, but a site on their EU cloud (or a self-hosted instance)
+    // must override this to the host shown in their own project
+    // settings, or events silently go nowhere.
+    apiHost: z.string().default('https://us.i.posthog.com'),
+  })
+  .strict();
+
+const umamiIntegrationSchema = z
+  .object({
+    websiteId: z.string(),
+    // Unlike Plausible/PostHog, Umami has no single hosted default that
+    // works for most users - it's commonly self-hosted, and even Umami
+    // Cloud users get a per-region script URL. Defaults to Umami Cloud's
+    // own documented script URL, which only happens to be correct for a
+    // Cloud user on that specific region; anyone self-hosting (the more
+    // common case for this particular provider) must override it to
+    // their own instance's own /script.js path.
+    src: z.string().default('https://cloud.umami.is/script.js'),
+  })
+  .strict();
+
+// AI chat over the site's own docs content, via a third-party provider
+// (DocsBot, currently the only one wired up) rather than a self-hosted
+// RAG pipeline - see the roadmap's own "AI chat over docs content" line
+// in docs/dev/docs/roadmap.mdx, which this fulfills via integration
+// rather than by building the retrieval/generation stack in-house.
+// Deliberately named `askAi` here, not `docsbot` - this is the
+// writedocs.json-facing, provider-neutral name for the feature (matching
+// the "Ask AI" label this kind of button/widget is conventionally
+// given in docs sites generally), independent of which vendor happens
+// to sit behind it today. `id` matches DocsBot's own embed config
+// field name exactly (`DocsBotAI.init({ id: 'teamId/botId' })`) - it's
+// a single opaque "teamId/botId" string DocsBot treats as one value,
+// not two separate ids, so this schema doesn't split it either.
+const askAiIntegrationSchema = z
+  .object({
+    id: z.string(),
+  })
+  .strict();
+
+const integrationsSchema = z
+  .object({
+    ga4: ga4IntegrationSchema.optional(),
+    googleTagManager: googleTagManagerIntegrationSchema.optional(),
+    plausible: plausibleIntegrationSchema.optional(),
+    fathom: fathomIntegrationSchema.optional(),
+    posthog: posthogIntegrationSchema.optional(),
+    umami: umamiIntegrationSchema.optional(),
+    askAi: askAiIntegrationSchema.optional(),
+  })
+  .strict()
+  .default({});
+
+export type IntegrationsConfig = z.infer<typeof integrationsSchema>;
+
+export const docsConfigSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  styles: stylesSchema,
+  navigation: navigationSchema,
+  // Platform name -> profile/page URL (e.g. `{ "github": "https://
+  // github.com/...", "twitter": "https://twitter.com/..." }`), free-form
+  // rather than an enum of known platforms - the key doubles as the icon
+  // reference BaseLayout.astro's footer resolves via resolveIcon() below
+  // (bare `"github"` -> `lucide:github`; use an explicit
+  // `"simple-icons:whatever"` key instead when the bare lucide name isn't
+  // right for a given platform). Rendered as a row of icon links in the
+  // footer - see hasFooterContent/`.wd-footer-socials` in BaseLayout.astro.
+  socials: z.record(z.string(), z.string()).default({}),
+  topbar: z
+    .object({ links: z.array(topbarLinkSchema).default([]) })
+    .default({ links: [] }),
+  // Columns of links below the page content - see footerSchema/
+  // footerColumnSchema above. Renders alongside `socials` above (as a row
+  // of icon links) in the same <footer> - see BaseLayout.astro.
+  footer: footerSchema,
+  api: apiSchema,
+  // The site's own deployed domain, e.g. "docs.example.com" or
+  // "https://docs.example.com" (the scheme is optional - resolveSiteUrl()
+  // below normalizes either form to a full https:// origin). Powers three
+  // things that all need an absolute origin to work: sitemap.xml
+  // generation (astro.config.mjs only registers @astrojs/sitemap when this
+  // is set - a sitemap of relative URLs isn't meaningful), the canonical
+  // <link> and og:url/twitter meta tags (BaseLayout.astro), and resolving
+  // a relative `seo.ogImage` into an absolute URL for social crawlers.
+  // Left optional and simply skipped (with a log message, not an error) at
+  // every one of those call sites when unset - most fixtures/local builds
+  // have no real deployed domain yet.
+  domain: z.string().optional(),
+  // Site-wide meta tag defaults - see seoFieldsSchema above. A page's own
+  // frontmatter `seo` (content.config.ts's docsSchema) overrides these
+  // field by field via mergeSeo(), rather than needing to repeat every
+  // field on every page.
+  seo: seoFieldsSchema.default({}),
+  // The "Copy page" dropdown - see contextMenuSchema above. Absent by
+  // default (no menu, no .md routes).
+  contextMenu: contextMenuSchema.optional(),
+  // See redirectSchema above. Wired directly into Astro's own `redirects`
+  // config option in astro.config.mjs.
+  redirects: z.array(redirectSchema).default([]),
+  // Site-wide `[[key]]` substitution values, applied to page prose text
+  // at build time (see the remarkSubstituteVariables plugin wired into
+  // astro.config.mjs) - e.g. `{ "productName": "Acme" }` lets every page
+  // write `[[productName]]` once instead of hardcoding it everywhere.
+  // Double square brackets, not the more familiar `{{key}}` - MDX
+  // reserves single curly braces for embedded JS expressions, so
+  // `{{productName}}` in an .mdx file parses as a JS object-literal
+  // expression (`{productName}`, shorthand syntax) rather than literal
+  // text, and throws `ReferenceError: productName is not defined` at
+  // render time - see remarkSubstituteVariables' own comment in
+  // mdx-substitute-variables.js for the full explanation. Deliberately a
+  // flat string map, not typed values - this is text substitution into
+  // prose, not a templating language.
+  variables: z.record(z.string(), z.string()).default({}),
+  // See bannerSchema above. Absent by default (no banner rendered).
+  banner: bannerSchema.optional(),
+  // See notFoundSchema above.
+  notFound: notFoundSchema,
+  // See scriptsSchema above.
+  scripts: scriptsSchema,
+  // See integrationsSchema above.
+  integrations: integrationsSchema,
+});
+
+export type DocsConfig = z.infer<typeof docsConfigSchema>;
+
+// ---------------------------------------------------------------------
+// Ponto de entrada unico de validacao
+//
+// Existe pra que o gerador (`writedocs validate` e o `loadDocsConfig` que o
+// build usa) e a plataforma validem pelo MESMO codigo, com as MESMAS palavras -
+// o criterio de aceite do WD-066 e do WD-062. Se cada lado formatasse os erros
+// por conta propria, o cliente veria a plataforma aceitar um writedocs.json que
+// o build depois recusa, que e exatamente a classe de bug que a E11 existe pra
+// impedir.
+//
+// Recebe TEXTO CRU, e faz o JSON.parse por conta propria, por tres motivos:
+//   1. um JSON sintaticamente quebrado passa a ser um resultado de validacao
+//      como qualquer outro, em vez de uma excecao solta do runtime;
+//   2. linha/coluna so existem no texto - e o WD-063 precisa reportar linha;
+//   3. do lado da plataforma, importProjectConfig ja tem os bytes crus em maos
+//      antes de parsear, entao encaixa sem ginastica nenhuma.
+//
+// IMPORTANTE, e deliberado: as mensagens aqui sao as do Zod, VERBATIM. Melhorar
+// a linguagem delas e o WD-063, que precisa deste comportamento como ponto de
+// partida pra medir a melhora. Nada aqui reescreve, traduz ou embeleza mensagem.
+// ---------------------------------------------------------------------
+
+/** Um problema encontrado na configuracao. `path` e o caminho do campo em
+ *  notacao de ponto (`navigation.tabs.0.label`), ou `(root)` quando o problema e
+ *  do documento inteiro - o mesmo texto que a mensagem de erro do build ja
+ *  imprime hoje. `line`/`column` so vem quando da pra saber (hoje: erro de JSON;
+ *  no WD-063, tambem para erros de schema). */
+export type ValidationIssue = {
+  path: string;
+  message: string;
+  /** Codigo do Zod (`invalid_type`, `unrecognized_keys`, ...) ou `invalid_json`. */
+  code?: string;
+  line?: number;
+  column?: number;
+  /** WD-063: a mesma coisa que `message`, dita para gente. ADICIONAL, nunca
+   *  substituto - `message` continua sendo o texto do Zod verbatim, que e o que
+   *  o `writedocs build` imprime e o que o WD-062 grava em `validation_issues`.
+   *  Quem exibe escolhe qual dos dois mostrar. */
+  humanMessage?: string;
+  /** O que fazer a respeito, quando da pra dizer algo concreto. */
+  suggestion?: string;
+  /** Chave ESTAVEL de documentacao (`config.styles`), nunca uma URL: uma URL
+   *  cravada num pacote npm fica quebrada em toda instalacao ate a proxima
+   *  release, e o mesmo erro e exibido pela CLI e pelo dashboard, que podem
+   *  querer destinos diferentes. O mapa chave -> URL mora do lado de quem
+   *  renderiza. */
+  docKey?: string;
+};
+
+/** Sucesso carrega os dados ja validados (com os defaults do schema aplicados);
+ *  falha carrega os problemas e diz de que tipo ela foi. `parseError` so aparece
+ *  quando o JSON nao pode nem ser parseado, e existe para o chamador que quiser
+ *  relancar exatamente o erro original (e o que o loadDocsConfig faz, pra nao
+ *  mudar uma virgula do que o `writedocs build` ja imprime hoje). */
+export type ValidationResult =
+  | { ok: true; data: DocsConfig; issues: ValidationIssue[] }
+  | {
+      ok: false;
+      data: null;
+      kind: 'invalid_json' | 'schema';
+      issues: ValidationIssue[];
+      parseError?: SyntaxError;
+    };
+
+/** "at position 22 (line 1 column 23)" -> { line: 1, column: 23 }.
+ *  O formato da mensagem de erro do JSON.parse e do V8, nao do padrao, entao
+ *  isto e melhor-esforco: se a mensagem nao trouxer posicao, devolve null e o
+ *  problema simplesmente fica sem linha. */
+function positionFromJsonError(message: string, rawText: string): { line: number; column: number } | null {
+  const comLinha = message.match(/line (\d+) column (\d+)/);
+  if (comLinha) return { line: Number(comLinha[1]), column: Number(comLinha[2]) };
+  const comPosicao = message.match(/position (\d+)/);
+  if (comPosicao) {
+    const pos = Math.min(Number(comPosicao[1]), rawText.length);
+    const antes = rawText.slice(0, pos);
+    const line = antes.split('\n').length;
+    return { line, column: pos - antes.lastIndexOf('\n') };
+  }
+  return null;
+}
+
+/** O corpo da mensagem de erro, uma linha por problema - exatamente o formato
+ *  que o `writedocs build` imprime desde sempre (`  - campo: mensagem`). Fica
+ *  aqui, e nao em cada chamador, pra que CLI e plataforma nao possam divergir.
+ *
+ *  NAO mudou no WD-063, de proposito: continua imprimindo `message` (o texto do
+ *  Zod). O que melhorou foi o CONTEUDO dos issues - a uniao desembrulhada faz o
+ *  `path` apontar pro campo real em vez de parar em `navigation`. Quem quiser a
+ *  versao com frase humana e linha usa formatValidationIssuesDetailed. */
+export function formatValidationIssues(issues: ValidationIssue[]): string {
+  return issues.map((i) => `  - ${i.path}: ${i.message}`).join('\n');
+}
+
+/** A versao longa, para quem tem uma tela inteira (a CLI hoje, o dashboard do
+ *  WD-065 se quiser): caminho, linha, frase humana, sugestao, e a mensagem do
+ *  Zod por ultimo, entre parenteses, pra quem precisa do texto exato.
+ *
+ *  Mora aqui pelo mesmo motivo que a irma curta: se cada consumidor montasse a
+ *  sua, a CLI e a plataforma divergiriam na primeira mudanca - que e exatamente
+ *  o que o AC do WD-066 proibe. `fileName` so entra na referencia de linha. */
+export function formatValidationIssuesDetailed(
+  issues: ValidationIssue[],
+  { fileName = 'writedocs.json' }: { fileName?: string } = {}
+): string {
+  return issues
+    .map((i) => {
+      const temCampo = i.path !== '(root)';
+      const local = i.line ? `${fileName}:${i.line}` : i.path;
+      const linhas = [`  ${local}${i.line && temCampo ? `  (${i.path})` : ''}`];
+      linhas.push(`    ${i.humanMessage ?? i.message}`);
+      if (i.suggestion) linhas.push(`    ${i.suggestion}`);
+      if (i.humanMessage && i.message !== i.humanMessage) linhas.push(`    (${i.message})`);
+      return linhas.join('\n');
+    })
+    .join('\n\n');
+}
+
+// ---------------------------------------------------------------------
+// WD-063 — do issue do Zod para "onde esta o erro, e o que fazer"
+//
+// Tres transformacoes, nesta ordem:
+//   1. desembrulhar `invalid_union` (senao todo erro dentro da navigation vira
+//      `navigation: "Invalid input"`, que e inutil num arquivo de 10 KB);
+//   2. achar a linha no texto, pelo caminho ja desembrulhado;
+//   3. escrever a frase humana, a sugestao e a docKey - POR CODIGO do Zod, nao
+//      por campo: um mapa por campo teria 17 entradas so na raiz e centenas no
+//      total, e envelheceria a cada campo novo do schema.
+// ---------------------------------------------------------------------
+
+/** Chaves que a raiz aceita sem ser campo do schema, e que por isso NAO devem
+ *  gerar aviso de chave desconhecida. Deliberadamente minuscula: a raiz nao e
+ *  `.strict()` justamente pra nao quebrar configs existentes, e `$schema` foi um
+ *  dos argumentos dessa decisao - avisar sobre ele contradiria o que o protegeu.
+ *  Se esta lista passar de dois ou tres nomes, o problema e outro e a raiz
+ *  precisa de outra conversa. */
+export const ROOT_ALLOWED_EXTRA_KEYS: readonly string[] = Object.freeze(['$schema']);
+
+type IssueCru = {
+  code?: string;
+  path?: (string | number)[];
+  message: string;
+  expected?: string;
+  values?: unknown[];
+  keys?: string[];
+  minimum?: number;
+  maximum?: number;
+  origin?: string;
+  format?: string;
+  errors?: unknown[];
+  unionErrors?: unknown[];
+};
+
+type IssuePlano = IssueCru & { caminho: (string | number)[] };
+
+function issuesDoRamo(ramo: unknown): IssueCru[] {
+  if (Array.isArray(ramo)) return ramo as IssueCru[];
+  const comIssues = ramo as { issues?: IssueCru[] };
+  return comIssues?.issues ?? [];
+}
+
+/** O maior valor de `f` sobre a lista, ou 0 se ela for vazia. Um `for` e nao
+ *  `Math.max(0, ...lista.map(f))`: o spread vira argumentos de chamada, e uma
+ *  lista grande o bastante (config com dezenas de milhares de erros) estoura o
+ *  limite de argumentos com RangeError em vez de devolver um numero. */
+function maiorProfundidade(lista: IssuePlano[]): number {
+  let maior = 0;
+  for (const issue of lista) {
+    const p = issue.caminho.length + (issue.code === 'unrecognized_keys' ? 1 : 0);
+    if (p > maior) maior = p;
+  }
+  return maior;
+}
+
+/** Plano ACHATADO de um ramo, memoizado por identidade do ramo.
+ *
+ *  A memoizacao nao e otimizacao, e o que torna o achatamento viavel. Pontuar um
+ *  ramo exige desembrulhar as unioes DENTRO dele, e cada uma dessas tem os seus
+ *  proprios ramos - sem cache, a pontuacao visita o mesmo sub-ramo uma vez por
+ *  caminho que leva ate ele, o que e exponencial na profundidade do aninhamento.
+ *  Medido com grupos aninhados e um erro no fundo: 3,7 ms com 4 niveis, 281 ms
+ *  com 8, 69 SEGUNDOS com 12. Com o cache, os mesmos casos ficam em 0,2 ms,
+ *  porque cada no da arvore de erro do Zod e achatado uma vez so.
+ *
+ *  Se alguem remover este WeakMap por parecer supérfluo, o `writedocs validate`
+ *  passa a travar em configs profundas. Nao remova. */
+const planoPorRamo = new WeakMap<object, IssuePlano[]>();
+
+function planoDoRamo(ramo: unknown): IssuePlano[] {
+  const lista = issuesDoRamo(ramo);
+  if (typeof ramo !== 'object' || ramo === null) return desembrulharUnioes(lista);
+  const memoizado = planoPorRamo.get(ramo);
+  if (memoizado) return memoizado;
+  // Prefixo vazio de proposito: a pontuacao compara ramos entre si, entao a
+  // profundidade tem que ser relativa ao proprio ramo, nao ao documento.
+  const plano = desembrulharUnioes(lista);
+  planoPorRamo.set(ramo, plano);
+  return plano;
+}
+
+/** Escolhe qual ramo de uma uniao o cliente PROVAVELMENTE quis.
+ *
+ *  Criterio: caminho mais fundo primeiro; empate resolvido por menos issues. A
+ *  intuicao e a do Gabriel na spec - o ramo certo e o que nao reclama da chave
+ *  que o cliente usou -, e a profundidade importa porque um ramo que chegou
+ *  fundo antes de falhar (`products.0.product`) reconheceu a forma, enquanto um
+ *  que falha na raiz (`expected array, received object`) so recusou o shape.
+ *
+ *  DUAS CORRECOES sobre a primeira versao (WD-063), as duas medidas contra o
+ *  `00-kitchen-sink` real - ver o relato de revisao 43:
+ *
+ *  1. PONTUA O RAMO ACHATADO, nao a lista crua. Um ramo que e ele proprio uma
+ *     uniao aparece como UM issue (`invalid_union`) no caminho vazio - ou seja,
+ *     com a MENOR contagem e a MENOR profundidade possiveis, sem que isso diga
+ *     nada sobre o quanto ele reconheceu. Era o caso mais comum que existe: um
+ *     item de `pages` e `string | grupo | link`, e o grupo e outra uniao, entao
+ *     todo erro estrutural dentro de um grupo empatava com o ramo `string` e
+ *     perdia pela ordem de declaracao. O cliente que escrevia
+ *     `{ "group": "G", "pages": 42 }` recebia "expected string, received
+ *     object" - conselho errado, nao so inutil. Achatando primeiro, o mesmo caso
+ *     vira `pages.0.pages: expected array, received number`.
+ *
+ *  2. PROFUNDIDADE EFETIVA: `unrecognized_keys` reporta no caminho do PAI, com a
+ *     chave ofensora em `keys`, entao a profundidade dele sai subestimada em 1.
+ *     Sem a correcao, um ramo que identificou a chave errada perde para um que
+ *     so exigiu um campo ausente. (`validateDocsConfig` ja fazia a mesma conta
+ *     para achar a LINHA; aqui ela entra tambem na pontuacao.)
+ *
+ *  Medido sobre as 60 folhas da `navigation` do `00-kitchen-sink`, trocando o
+ *  tipo de cada uma: a versao anterior apontava o campo exato em 42/60 e PARAVA
+ *  RASO em 18/60 (sempre os mesmos 18: os que ficam sob um `pages`); esta aponta
+ *  60/60 para valor escalar errado e nunca para raso. Para um objeto vazio ou
+ *  parcial no lugar de uma pagina, as duas ficam tecnicamente empatadas (41
+ *  contra 42): a anterior diz "expected string", esta lista os campos que
+ *  faltam para ser um grupo. E o custo aceito desta versao, e substitui o antigo
+ *  (`tabs` e `products` escritos juntos, que agora sai como
+ *  `Unrecognized key: "products"`).
+ *
+ *  EMPATE TOTAL (mesma profundidade E mesmo numero de issues): vence o ramo
+ *  declarado primeiro no schema. `Array.prototype.sort` e estavel desde a
+ *  ES2019, entao ordenar e pegar o [0] ja entrega isso - se alguem trocar por
+ *  uma ordenacao instavel, o desempate vira sorteio. Duas razoes para "o
+ *  primeiro" em vez de "todos os empatados":
+ *    - um engano do cliente tem que virar UMA mensagem. Emitir os 5 ramos
+ *      empatados de um `"navigation": {}` produz cinco exigencias que se
+ *      contradizem ("tabs e obrigatorio", "versions e obrigatorio", ...);
+ *    - determinismo: a mesma config sempre da a mesma mensagem. Um palpite
+ *      instavel seria pior que um palpite ruim.
+ *  E nada se perde no palpite errado: `message` continua sendo o texto do Zod. */
+function melhorRamo(ramos: unknown[]): IssueCru[] {
+  return ramos
+    .map((ramo) => {
+      const plano = planoDoRamo(ramo);
+      return {
+        lista: issuesDoRamo(ramo),
+        n: plano.length,
+        profundidade: maiorProfundidade(plano),
+      };
+    })
+    .sort((a, b) => b.profundidade - a.profundidade || a.n - b.n)[0].lista;
+}
+
+/** Desembrulha `invalid_union` recursivamente - o ramo escolhido normalmente e
+ *  outra uniao (cada produto da navigation e, por sua vez, uma uniao de formas),
+ *  entao para so quando chega num erro concreto. Sem recursao, o
+ *  `navigation.products.0` para em "Invalid input" de novo, um nivel abaixo. */
+function desembrulharUnioes(issues: IssueCru[], prefixo: (string | number)[] = []): IssuePlano[] {
+  const saida: IssuePlano[] = [];
+  for (const issue of issues) {
+    const caminho = [...prefixo, ...(issue.path ?? [])];
+    const ramos = issue.code === 'invalid_union' ? issue.errors ?? issue.unionErrors : null;
+    if (Array.isArray(ramos) && ramos.length > 0) {
+      saida.push(...desembrulharUnioes(melhorRamo(ramos), caminho));
+    } else {
+      saida.push({ ...issue, caminho });
+    }
+  }
+  return saida;
+}
+
+/** Exported for `writedocs validate`'s content pass (lib/content-check.js),
+ *  which reports writedocs.json problems of its own - navigation entries
+ *  with no page, unknown icons - with the same line numbers as the schema
+ *  errors. Same function as criarLocalizador below. */
+export function createJsonLocator(rawText: string): (path: (string | number)[]) => { line: number; column: number } | null {
+  return criarLocalizador(rawText);
+}
+
+/** Parseia o texto UMA vez e devolve "caminho -> linha/coluna". Devolve null
+ *  quando o no nao existe no texto (campo obrigatorio ausente e o caso comum):
+ *  `line` ausente e melhor que `line` inventada. */
+function criarLocalizador(rawText: string): (caminho: (string | number)[]) => { line: number; column: number } | null {
+  let arvore: ReturnType<typeof parseTree> | undefined;
+  try {
+    arvore = parseTree(rawText);
+  } catch {
+    arvore = undefined;
+  }
+  return (caminho) => {
+    if (!arvore || caminho.length === 0) return null;
+    const no = findNodeAtLocation(arvore, caminho);
+    if (!no) return null;
+    const antes = rawText.slice(0, no.offset);
+    return { line: antes.split('\n').length, column: no.offset - antes.lastIndexOf('\n') };
+  };
+}
+
+/** `styles.primaryColor` -> `config.styles`. Primeiro segmento so, com fallback
+ *  pra `config`: o conjunto tem que ficar pequeno e estavel, porque vira
+ *  superficie publica no instante em que alguem mapear chave -> URL. */
+function docKeyDoCaminho(caminho: (string | number)[]): string {
+  const primeiro = caminho[0];
+  return typeof primeiro === 'string' && primeiro ? `config.${primeiro}` : 'config';
+}
+
+const ARTIGO_POR_TIPO: Record<string, string> = {
+  string: 'a piece of text',
+  number: 'a number',
+  boolean: 'true or false',
+  array: 'a list',
+  object: 'an object',
+  null: 'null',
+};
+
+const COMO_ESCREVER: Record<string, string> = {
+  string: 'Write the value in double quotes, like "Core Platform".',
+  number: 'Write the value as a bare number, like 3 - no quotes.',
+  boolean: 'Write true or false - no quotes.',
+  array: 'Write the value as a list in square brackets: [ ... ].',
+  object: 'Write the value as an object in curly braces: { ... }.',
+};
+
+/** O tipo que o cliente REALMENTE escreveu, lido do JSON ja parseado em vez de
+ *  extraido da mensagem do Zod por regex - o Zod v4 nao carrega `received` como
+ *  propriedade, so dentro do texto, e depender do texto quebra na primeira vez
+ *  que ele mudar de forma. */
+function tipoReal(valor: unknown): string {
+  if (valor === undefined) return 'missing';
+  if (valor === null) return 'null';
+  if (Array.isArray(valor)) return 'array';
+  return typeof valor;
+}
+
+function valorEm(raiz: unknown, caminho: (string | number)[]): unknown {
+  let atual: unknown = raiz;
+  for (const passo of caminho) {
+    if (atual === null || typeof atual !== 'object') return undefined;
+    atual = (atual as Record<string | number, unknown>)[passo];
+  }
+  return atual;
+}
+
+function comoCampo(caminho: (string | number)[]): string {
+  return caminho.length > 0 ? `"${caminho.join('.')}"` : 'writedocs.json';
+}
+
+/** A frase de chave desconhecida, num lugar so.
+ *
+ *  Decisao 6: chave desconhecida em sub-objeto strict e ERRO e na raiz e AVISO -
+ *  a assimetria de SEVERIDADE e intencional e fica. A de VOCABULARIO nao: os
+ *  dois caminhos chamam esta funcao, entao os dois dizem exatamente a mesma
+ *  coisa, e so quem chama decide o peso. */
+function fraseChaveDesconhecida(chaves: string[], dentroDe: (string | number)[]) {
+  const onde = dentroDe.length > 0 ? ` inside "${dentroDe.join('.')}"` : '';
+  const lista = chaves.map((k) => `"${k}"`).join(', ');
+  return {
+    humanMessage:
+      chaves.length === 1
+        ? `${lista} is not a writedocs.json option${onde}.`
+        : `${lista} are not writedocs.json options${onde}.`,
+    suggestion: 'Remove it, or check the spelling - options are case-sensitive.',
+  };
+}
+
+/** A frase humana + a sugestao, escolhidas pelo CODIGO do Zod. `raiz` e o JSON
+ *  ja parseado, usado so pra saber o que o cliente escreveu de fato. */
+function humanizar(issue: IssuePlano, raiz: unknown): { humanMessage?: string; suggestion?: string } {
+  const campo = comoCampo(issue.caminho);
+  switch (issue.code) {
+    case 'invalid_type': {
+      const esperado = issue.expected ?? 'a different type';
+      const recebido = tipoReal(valorEm(raiz, issue.caminho));
+      if (recebido === 'missing') {
+        return {
+          humanMessage: `${campo} is required, but writedocs.json does not set it.`,
+          suggestion: `Add ${campo} with ${ARTIGO_POR_TIPO[esperado] ?? `a ${esperado}`} as its value.`,
+        };
+      }
+      return {
+        humanMessage: `${campo} must be ${ARTIGO_POR_TIPO[esperado] ?? `a ${esperado}`}, but writedocs.json has ${ARTIGO_POR_TIPO[recebido] ?? `a ${recebido}`}.`,
+        suggestion: COMO_ESCREVER[esperado],
+      };
+    }
+    case 'unrecognized_keys': {
+      // O Zod agrega as chaves sobrando numa mensagem so, com o `path` no PAI.
+      const chaves = issue.keys ?? [];
+      if (chaves.length === 0) return {};
+      return fraseChaveDesconhecida(chaves, issue.caminho);
+    }
+    case 'invalid_value': {
+      const opcoes = (issue.values ?? []).map((v) => JSON.stringify(v)).join(', ');
+      return {
+        humanMessage: `${campo} must be one of: ${opcoes}.`,
+        suggestion: 'Replace the value with one of the options above.',
+      };
+    }
+    case 'too_small': {
+      const unidade = issue.origin === 'array' ? 'item' : 'character';
+      const minimo = issue.minimum ?? 1;
+      return {
+        humanMessage: `${campo} needs at least ${minimo} ${unidade}${minimo === 1 ? '' : 's'}.`,
+        suggestion: issue.origin === 'array' ? 'Add an entry, or remove the field entirely.' : undefined,
+      };
+    }
+    case 'too_big': {
+      const unidade = issue.origin === 'array' ? 'item' : 'character';
+      const maximo = issue.maximum ?? 0;
+      return { humanMessage: `${campo} allows at most ${maximo} ${unidade}${maximo === 1 ? '' : 's'}.` };
+    }
+    case 'invalid_format':
+      return {
+        humanMessage: `${campo} is not a valid ${issue.format ?? 'value'}.`,
+        suggestion: 'Check the format against the documentation for this field.',
+      };
+    case 'invalid_union':
+      // So chega aqui se o desembrulho nao achou ramo nenhum (uniao sem
+      // `errors`). Raro, mas melhor dizer o que aconteceu do que "Invalid input".
+      return {
+        humanMessage: `${campo} does not match any of the shapes writedocs.json accepts here.`,
+        suggestion: 'Check the documentation for the shapes this field accepts.',
+      };
+    case 'custom':
+      // As mensagens de `.refine()` deste schema ja sao frases escritas pra
+      // gente ("Each scripts.head/scripts.body entry needs exactly one of..."),
+      // entao reescrever seria piorar. Repassa como frase humana pra que quem
+      // exibe so `humanMessage` nao fique sem nada.
+      return { humanMessage: issue.message };
+    default:
+      return {};
+  }
+}
+
+/** Avisos de chave desconhecida na RAIZ.
+ *
+ *  A raiz nao e `.strict()` (decidido no E11-desenho-geral: tornar strict
+ *  quebraria configs existentes), entao o Zod descarta a chave em silencio e
+ *  nao ha issue nenhum. Quem quiser avisar chama isto. Mora aqui, e nao na
+ *  plataforma, pelo motivo de sempre: era o unico texto escrito pela plataforma,
+ *  e enquanto ele viver la os dois lados podem divergir.
+ *
+ *  Severidade e de quem chama - isto so descreve o problema. `validateDocsConfig`
+ *  deliberadamente NAO chama: um config valido continua saindo com `issues: []`,
+ *  porque a plataforma repassa `issues` como `errors` e um aviso ali viraria
+ *  erro. */
+export function unknownRootKeyIssues(rawText: string): ValidationIssue[] {
+  let raiz: unknown;
+  try {
+    raiz = JSON.parse(rawText);
+  } catch {
+    return [];
+  }
+  if (raiz === null || typeof raiz !== 'object' || Array.isArray(raiz)) return [];
+  const conhecidas = new Set([...Object.keys(docsConfigSchema.shape), ...ROOT_ALLOWED_EXTRA_KEYS]);
+  const localizar = criarLocalizador(rawText);
+  return Object.keys(raiz as Record<string, unknown>)
+    .filter((chave) => !conhecidas.has(chave))
+    .map((chave) => {
+      const frase = fraseChaveDesconhecida([chave], []);
+      return {
+        path: chave,
+        // O mesmo formato singular da mensagem `unrecognized_keys` do Zod, pra
+        // que aviso e erro sejam indistinguiveis por quem so le `message`.
+        message: `Unrecognized key: "${chave}"`,
+        code: 'unrecognized_keys',
+        ...(localizar([chave]) ?? {}),
+        ...frase,
+        // `config`, e NAO `config.<chave>`: a chave aqui e o que o cliente
+        // digitou errado, e derivar a docKey dela faria cada erro de digitacao
+        // inventar uma chave nova. O conjunto de docKeys tem que ser fechado -
+        // `config` mais um por campo do schema, nada alem disso -, senao quem
+        // mapeia chave -> URL do outro lado nao tem lista pra mapear.
+        docKey: 'config',
+      };
+    });
+}
+
+export function validateDocsConfig(rawText: string): ValidationResult {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(rawText);
+  } catch (err) {
+    const parseError = err as SyntaxError;
+    const posicao = positionFromJsonError(parseError.message, rawText);
+    return {
+      ok: false,
+      data: null,
+      kind: 'invalid_json',
+      parseError,
+      issues: [
+        {
+          path: '(root)',
+          message: parseError.message,
+          code: 'invalid_json',
+          ...(posicao ?? {}),
+          humanMessage: 'writedocs.json is not valid JSON, so none of it could be checked.',
+          suggestion: posicao
+            ? `Look at line ${posicao.line} - a missing comma, an extra trailing comma, or an unclosed bracket is the usual cause.`
+            : 'A missing comma, an extra trailing comma, or an unclosed bracket is the usual cause.',
+          docKey: 'config',
+        },
+      ],
+    };
+  }
+
+  const result = docsConfigSchema.safeParse(raw);
+  if (!result.success) {
+    const localizar = criarLocalizador(rawText);
+    return {
+      ok: false,
+      data: null,
+      kind: 'schema',
+      issues: desembrulharUnioes(result.error.issues as IssueCru[]).map((i) => {
+        // Para chave desconhecida o `path` do Zod aponta pro PAI (`footer`), e a
+        // chave ofensora vem em `keys`. Para a LINHA vale a pena descer ate ela
+        // (`footer.banana`), que e onde o cliente precisa olhar; o `path` fica
+        // como o Zod deu, pra nao mudar o que a plataforma ja grava.
+        const alvoDaLinha =
+          i.code === 'unrecognized_keys' && i.keys?.length ? [...i.caminho, i.keys[0]] : i.caminho;
+        return {
+          path: i.caminho.join('.') || '(root)',
+          message: i.message,
+          code: i.code,
+          ...(localizar(alvoDaLinha) ?? localizar(i.caminho) ?? {}),
+          ...humanizar(i, raw),
+          docKey: docKeyDoCaminho(i.caminho),
+        };
+      }),
+    };
+  }
+
+  return { ok: true, data: result.data, issues: [] };
+}