@writedocs/generator 0.2.0 → 0.3.0

package/bin/writedocs.js

@@ -8,6 +8,25 @@ import { runDev } from '../src/cli/dev.js';
 import { runBuild } from '../src/cli/build.js';
 import { runInit } from '../src/cli/init.js';
 import { requireBuildKey } from '../src/cli/build-auth.js';
+// O MESMO modulo que o build usa (via loadDocsConfig, que reexporta daqui) e
+// que a plataforma importa por `@writedocs/generator/config-schema` - e o que
+// faz os tres reportarem os mesmos problemas com as mesmas palavras, em vez de
+// cada um manter a sua copia do schema.
+//
+// `.js`, e nao o `.ts` que e a fonte de verdade: este arquivo e carregado por
+// node puro, sem o transform do Astro/Vite, e o Node RECUSA type stripping para
+// qualquer arquivo sob node_modules - por desenho, em qualquer versao
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). Ou seja: importar o `.ts` aqui
+// funciona a partir do checkout e falha 100% das vezes para quem instala o
+// pacote, que foi exatamente o que quebrou o `validate` no 0.2.0. O `.js` e
+// gerado do `.ts` pelo script `prepare` (package.json), entao ele existe tanto
+// no checkout quanto dentro do tarball, e o consumidor nao roda build nenhum.
+// Ver a mesma regra ja escrita em src/cli/write-redirects-file.js.
+import {
+  validateDocsConfig,
+  formatValidationIssuesDetailed,
+  unknownRootKeyIssues,
+} from '../src/lib/config-schema.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, '..');
@@ -77,39 +96,33 @@ program
       process.exit(1);
     }
 
-    // O MESMO modulo que o build usa (via loadDocsConfig) e que a plataforma
-    // importa por `@writedocs/generator/config-schema` - e o que faz os tres
-    // reportarem os mesmos problemas com as mesmas palavras, em vez de cada um
-    // manter a sua copia do schema.
-    //
-    // Import dinamico porque isto e um `.ts` sendo carregado por node puro (sem
-    // o transform do Astro/Vite): funciona com o type stripping nativo do Node,
-    // estavel a partir do 22.18/23.6. O astro deste pacote ja exige >=22.12, mas
-    // entre 22.12 e 22.18 o import falharia com uma mensagem cifrada sobre
-    // "Unknown file extension .ts" - a mensagem abaixo diz o que fazer.
-    let validateDocsConfig;
-    let formatValidationIssues;
-    try {
-      ({ validateDocsConfig, formatValidationIssues } = await import('../src/lib/config-schema.ts'));
-    } catch (err) {
-      console.error(
-        `[writedocs] validate needs a Node that can load TypeScript directly (Node 22.18+ or 23.6+); this one is ${process.version}.`
-      );
-      console.error(`[writedocs] ${err.message}`);
-      process.exit(1);
+    const rawText = fs.readFileSync(configPath, 'utf-8');
+    const result = validateDocsConfig(rawText);
+    // Chave desconhecida na raiz e AVISO, nunca erro: a raiz nao e `.strict()`
+    // de proposito (tornar strict quebraria configs existentes), entao o Zod
+    // descarta a chave em silencio. Sem JSON parseavel nao ha chave pra avaliar.
+    const warnings = result.kind === 'invalid_json' ? [] : unknownRootKeyIssues(rawText);
+    const nomeArquivo = path.basename(configPath);
+
+    if (!result.ok) {
+      // A versao longa (linha, frase humana, sugestao) em vez da curta que o
+      // `writedocs build` imprime: aqui o usuario pediu explicitamente um
+      // diagnostico, e tem a tela inteira pra ele.
+      console.error(`[writedocs] ${configPath} failed validation:\n`);
+      console.error(formatValidationIssuesDetailed(result.issues, { fileName: nomeArquivo }));
+      console.error('');
     }
 
-    const result = validateDocsConfig(fs.readFileSync(configPath, 'utf-8'));
-    if (result.ok) {
-      console.log(`[writedocs] ${configPath} is valid.`);
-      return;
+    if (warnings.length > 0) {
+      console.error(`[writedocs] ${warnings.length} warning${warnings.length === 1 ? '' : 's'}:\n`);
+      console.error(formatValidationIssuesDetailed(warnings, { fileName: nomeArquivo }));
+      console.error('');
     }
 
-    // Mesmo formato que o build imprime num config invalido - mesmo texto,
-    // mesma ordem, montado pelo mesmo formatador.
-    console.error('[writedocs] writedocs.json failed validation:');
-    console.error(formatValidationIssues(result.issues));
-    process.exit(1);
+    if (!result.ok) process.exit(1);
+    // Aviso nao invalida: um config so com avisos continua valido, e sai 0 -
+    // o mesmo criterio que a plataforma usa pra marcar o projeto como `valid`.
+    console.log(`[writedocs] ${configPath} is valid.`);
   });
 
 program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "exports": {
     "./components": "./src/components/index.ts",
-    "./config-schema": "./src/lib/config-schema.ts"
+    "./config-schema": "./src/lib/config-schema.js"
   },
   "files": [
     "bin",
@@ -18,7 +18,9 @@
   "scripts": {
     "dev": "node bin/writedocs.js dev",
     "build": "node bin/writedocs.js build",
-    "init": "node bin/writedocs.js init"
+    "init": "node bin/writedocs.js init",
+    "build:schema": "esbuild src/lib/config-schema.ts --format=esm --target=node22 --outfile=src/lib/config-schema.js",
+    "prepare": "npm run build:schema"
   },
   "keywords": [
     "docs",
@@ -63,6 +65,7 @@
     "commander": "^15.0.0",
     "dotenv": "^17.4.2",
     "gray-matter": "^4.0.3",
+    "jsonc-parser": "3.3.1",
     "katex": "^0.16.47",
     "mermaid": "^11.16.0",
     "pagefind": "^1.5.2",
@@ -75,6 +78,9 @@
     "zod": "^4.4.3"
   },
   "engines": {
-    "node": ">=22.18.0"
+    "node": ">=22.12.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
   }
 }

package/src/lib/config-schema.js

@@ -0,0 +1,692 @@
+import { z } from "zod";
+import { findNodeAtLocation, parseTree } from "jsonc-parser";
+const navPageSchema = z.string();
+const navGroupPagesSchema = 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();
+const navGroupSchema = z.union([navGroupPagesSchema, navGroupOpenApiSchema]);
+const navLinkSchema = z.object({ label: z.string(), href: z.string() }).strict();
+const navItemSchema = z.lazy(
+  () => z.union([navPageSchema, navGroupSchema, navLinkSchema])
+);
+function withChildren(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()
+  ]);
+}
+const tabSchema = z.lazy(
+  () => withChildren({ tab: z.string(), icon: z.string().optional() })
+);
+const versionSchema = z.lazy(
+  () => withChildren({
+    version: z.string(),
+    label: z.string().optional(),
+    tag: z.string().optional(),
+    default: z.boolean().optional()
+  })
+);
+const languageSchema = z.lazy(
+  () => withChildren({ language: z.string(), label: z.string().optional() })
+);
+const dropdownSchema = z.lazy(
+  () => withChildren({ dropdown: z.string(), icon: z.string().optional() })
+);
+const productSchema = z.lazy(
+  () => withChildren({ product: z.string(), icon: z.string().optional(), description: z.string().optional() })
+);
+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()
+]);
+const DEFAULT_PRIMARY = "#6366f1";
+const logoSchema = z.union([
+  z.string(),
+  z.object({ light: z.string().optional(), dark: z.string().optional(), label: z.string().optional() }).strict()
+]);
+const navbarColorValueSchema = z.union([
+  z.string(),
+  z.object({
+    background: z.string(),
+    accent: z.string().optional()
+  }).strict()
+]);
+const fontVariantSchema = z.object({
+  family: z.string(),
+  weight: z.number().optional(),
+  source: z.string().optional(),
+  format: z.enum(["woff", "woff2"]).optional()
+}).strict();
+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();
+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 } });
+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.'
+});
+const footerColumnSchema = z.object({
+  title: z.string().optional(),
+  links: z.array(topbarLinkSchema).default([])
+}).strict();
+const footerSchema = z.object({
+  columns: z.array(footerColumnSchema).default([]),
+  logo: logoSchema.optional()
+}).strict().default({ columns: [] });
+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();
+function mergeSeo(site, page) {
+  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 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 });
+const contextMenuSchema = z.object({
+  openIn: z.array(z.enum(["chatgpt", "claude", "perplexity"])).default(["chatgpt", "claude", "perplexity"])
+}).strict();
+const redirectSchema = z.object({
+  source: z.string(),
+  destination: z.string()
+}).strict();
+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();
+const notFoundSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional()
+}).strict().default({});
+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.'
+});
+const scriptsSchema = z.object({
+  head: z.array(scriptEntrySchema).default([]),
+  body: z.array(scriptEntrySchema).default([])
+}).strict().default({ head: [], body: [] });
+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();
+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({});
+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
+});
+function positionFromJsonError(message, rawText) {
+  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;
+}
+function formatValidationIssues(issues) {
+  return issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n");
+}
+function formatValidationIssuesDetailed(issues, { fileName = "writedocs.json" } = {}) {
+  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");
+}
+const ROOT_ALLOWED_EXTRA_KEYS = Object.freeze(["$schema"]);
+function issuesDoRamo(ramo) {
+  if (Array.isArray(ramo)) return ramo;
+  const comIssues = ramo;
+  return comIssues?.issues ?? [];
+}
+function melhorRamo(ramos) {
+  return ramos.map((ramo) => {
+    const lista = issuesDoRamo(ramo);
+    return {
+      lista,
+      n: lista.length,
+      profundidade: Math.max(0, ...lista.map((i) => (i.path ?? []).length))
+    };
+  }).sort((a, b) => a.n - b.n || b.profundidade - a.profundidade)[0].lista;
+}
+function desembrulharUnioes(issues, prefixo = []) {
+  const saida = [];
+  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;
+}
+function criarLocalizador(rawText) {
+  let arvore;
+  try {
+    arvore = parseTree(rawText);
+  } catch {
+    arvore = void 0;
+  }
+  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") };
+  };
+}
+function docKeyDoCaminho(caminho) {
+  const primeiro = caminho[0];
+  return typeof primeiro === "string" && primeiro ? `config.${primeiro}` : "config";
+}
+const ARTIGO_POR_TIPO = {
+  string: "a piece of text",
+  number: "a number",
+  boolean: "true or false",
+  array: "a list",
+  object: "an object",
+  null: "null"
+};
+const COMO_ESCREVER = {
+  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: { ... }."
+};
+function tipoReal(valor) {
+  if (valor === void 0) return "missing";
+  if (valor === null) return "null";
+  if (Array.isArray(valor)) return "array";
+  return typeof valor;
+}
+function valorEm(raiz, caminho) {
+  let atual = raiz;
+  for (const passo of caminho) {
+    if (atual === null || typeof atual !== "object") return void 0;
+    atual = atual[passo];
+  }
+  return atual;
+}
+function comoCampo(caminho) {
+  return caminho.length > 0 ? `"${caminho.join(".")}"` : "writedocs.json";
+}
+function fraseChaveDesconhecida(chaves, dentroDe) {
+  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."
+  };
+}
+function humanizar(issue, raiz) {
+  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": {
+      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." : void 0
+      };
+    }
+    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":
+      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":
+      return { humanMessage: issue.message };
+    default:
+      return {};
+  }
+}
+function unknownRootKeyIssues(rawText) {
+  let raiz;
+  try {
+    raiz = JSON.parse(rawText);
+  } catch {
+    return [];
+  }
+  if (raiz === null || typeof raiz !== "object" || Array.isArray(raiz)) return [];
+  const conhecidas = /* @__PURE__ */ new Set([...Object.keys(docsConfigSchema.shape), ...ROOT_ALLOWED_EXTRA_KEYS]);
+  const localizar = criarLocalizador(rawText);
+  return Object.keys(raiz).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"
+    };
+  });
+}
+function validateDocsConfig(rawText) {
+  let raw;
+  try {
+    raw = JSON.parse(rawText);
+  } catch (err) {
+    const parseError = err;
+    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).map((i) => {
+        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: [] };
+}
+export {
+  ROOT_ALLOWED_EXTRA_KEYS,
+  docsConfigSchema,
+  formatValidationIssues,
+  formatValidationIssuesDetailed,
+  mergeSeo,
+  seoFieldsSchema,
+  unknownRootKeyIssues,
+  validateDocsConfig
+};

package/src/lib/config-schema.ts

@@ -12,11 +12,25 @@
 // 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
@@ -922,6 +936,19 @@ export type ValidationIssue = {
   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);
@@ -958,11 +985,331 @@ function positionFromJsonError(message: string, rawText: string): { line: number
 
 /** 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. */
+ *  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 ?? [];
+}
+
+/** Escolhe qual ramo de uma uniao o cliente PROVAVELMENTE quis.
+ *
+ *  Criterio: menos issues primeiro; empate resolvido pelo caminho mais fundo. 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.
+ *
+ *  EMPATE TOTAL (mesmo numero de issues E mesma profundidade): 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 lista = issuesDoRamo(ramo);
+      return {
+        lista,
+        n: lista.length,
+        profundidade: Math.max(0, ...lista.map((i) => (i.path ?? []).length)),
+      };
+    })
+    .sort((a, b) => a.n - b.n || b.profundidade - a.profundidade)[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 {
@@ -975,21 +1322,45 @@ export function validateDocsConfig(rawText: string): ValidationResult {
       data: null,
       kind: 'invalid_json',
       parseError,
-      issues: [{ path: '(root)', message: parseError.message, code: 'invalid_json', ...(posicao ?? {}) }],
+      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: result.error.issues.map((i) => ({
-        path: i.path.join('.') || '(root)',
-        message: i.message,
-        code: i.code,
-      })),
+      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),
+        };
+      }),
     };
   }
 

package/src/lib/config.ts

@@ -23,6 +23,22 @@ import {
 // mantem a superficie deste arquivo exatamente como era - quem importa
 // `docsConfigSchema`, `DocsConfig`, `seoFieldsSchema`, `mergeSeo` etc. de
 // './config.js' continua importando do mesmo lugar, sem mudar uma linha.
+//
+// `.ts` e nao o `./config-schema.js` gerado, de proposito - e a unica coisa no
+// repositorio que ainda aponta pra fonte, e o bin/ e o `exports` apontam pro
+// `.js`. O motivo e que este reexport carrega 24 `export type`/`interface`
+// (DocsConfig, NavItem, Selector, GlobalDropdownView, ContextMenuConfig...) que
+// uma duzia de .astro consome como `import type { X } from '../lib/config'`, e
+// o esbuild apaga todos eles: o `.js` gerado exporta exatamente 5 simbolos de
+// runtime. Este repositorio nao tem tsconfig.json nem o typescript instalado,
+// entao (a) nada configura o mapeamento `.js` -> `.ts` que faria os tipos
+// voltarem e (b) nao existe typecheck que reclamasse - a troca so apagaria os
+// tipos em silencio. Aqui tudo passa pelo transform do Astro/Vite, que le `.ts`
+// nativamente, entao o `.js` nao resolve problema nenhum deste lado.
+//
+// O custo aceito e que o tarball leva as duas copias e um build do Astro pode
+// carregar as duas (o `.ts` por aqui, o `.js` por quem importa o subpath) - duas
+// instancias do schema, inofensivas porque nada compara identidade de schema.
 export * from './config-schema.ts';
 
 /** Normalizes writedocs.json's `domain` into a full origin with no trailing