@veluai/velu 0.2.13 → 0.2.15

package/schema/velu.schema.json

@@ -1,423 +1,423 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://veludocs.com/velu.schema.json",
-  "title": "Velu project configuration",
-  "description": "Configuration for a Velu documentation project (velu.json). This schema is defined internally during iteration; it will be hosted at the $id URL so editors can validate + autocomplete velu.json files.",
-  "type": "object",
-  "required": ["name"],
-  "additionalProperties": false,
-  "properties": {
-    "$schema": {
-      "type": "string",
-      "description": "URL of this JSON Schema, enabling editor validation + autocomplete."
-    },
-    "name": {
-      "type": "string",
-      "description": "Project name; usually the folder name it's contained in.",
-      "minLength": 1
-    },
-    "colors": {
-      "type": "object",
-      "description": "Accent colors. Maps onto the --accent-color token in base.css.",
-      "additionalProperties": false,
-      "required": ["primary"],
-      "properties": {
-        "primary": {
-          "type": "string",
-          "description": "The accent color used across the UI (--accent-color)."
-        },
-        "light": {
-          "type": "string",
-          "description": "Light-mode accent override. Defaults to `primary`."
-        },
-        "dark": {
-          "type": "string",
-          "description": "Dark-mode accent override. Defaults to `primary`."
-        }
-      }
-    },
-    "favicon": {
-      "type": "string",
-      "description": "Path to the favicon, relative to the project root."
-    },
-    "api": { "$ref": "#/$defs/api" },
-    "logo": {
-      "description": "Site logo shown in the header, replacing the name wordmark. A single path used in both themes, or per-theme light/dark images with an optional click-through href. Paths are relative to the project root.",
-      "oneOf": [
-        {
-          "type": "string",
-          "minLength": 1,
-          "description": "Logo path used in both light and dark mode."
-        },
-        {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["light", "dark"],
-          "properties": {
-            "light": {
-              "type": "string",
-              "minLength": 1,
-              "description": "Logo shown in light mode."
-            },
-            "dark": {
-              "type": "string",
-              "minLength": 1,
-              "description": "Logo shown in dark mode."
-            },
-            "href": {
-              "type": "string",
-              "description": "Where clicking the logo links. Defaults to the site root."
-            }
-          }
-        }
-      ]
-    },
-    "navbar": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "The header's top-right area: secondary links plus a primary CTA button.",
-      "properties": {
-        "links": {
-          "type": "array",
-          "description": "Secondary header links (to the left of the primary CTA).",
-          "items": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["href"],
-            "properties": {
-              "label": { "type": "string", "description": "Link text." },
-              "href": { "type": "string", "description": "Link URL." },
-              "icon": { "type": "string", "description": "lucide icon id." }
-            }
-          }
-        },
-        "primary": {
-          "description": "The prominent CTA button at the far right.",
-          "oneOf": [
-            {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["type", "label", "href"],
-              "properties": {
-                "type": { "const": "button" },
-                "label": { "type": "string", "description": "Button text." },
-                "href": { "type": "string", "description": "Button URL." }
-              }
-            },
-            {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["type", "href"],
-              "properties": {
-                "type": { "const": "github" },
-                "href": { "type": "string", "description": "GitHub repository URL." },
-                "label": { "type": "string", "description": "Button text (default \"GitHub\")." }
-              }
-            }
-          ]
-        }
-      }
-    },
-    "footer": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "Site footer. With `links`, a full footer section renders; with only `socials`, the icons sit next to the \"Powered by\" line instead.",
-      "properties": {
-        "socials": {
-          "type": "object",
-          "description": "Social links as platform → URL. Recognized icons: github, x (or twitter), youtube, linkedin.",
-          "additionalProperties": { "type": "string" }
-        },
-        "links": {
-          "type": "array",
-          "description": "Footer link columns (max 4).",
-          "maxItems": 4,
-          "items": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["header", "items"],
-            "properties": {
-              "header": { "type": "string", "description": "Column heading." },
-              "items": {
-                "type": "array",
-                "items": {
-                  "type": "object",
-                  "additionalProperties": false,
-                  "required": ["label", "href"],
-                  "properties": {
-                    "label": { "type": "string", "description": "Link text." },
-                    "href": { "type": "string", "description": "Link URL." }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "font": {
-      "type": "object",
-      "description": "Typography. Maps onto the --font-sans token in base.css.",
-      "additionalProperties": false,
-      "required": ["family"],
-      "properties": {
-        "family": {
-          "type": "string",
-          "description": "Google Font family to use (--font-sans)."
-        }
-      }
-    },
-    "navigation": {
-      "$ref": "#/$defs/navContainer",
-      "description": "Site navigation. Mintlify-compatible: products > versions > languages > tabs > groups > pages. Switchable axes (product/version/language) become URL path prefixes; the default value of each is unprefixed. Dropdowns are intentionally unsupported."
-    },
-    "url": {
-      "type": "string",
-      "description": "Production site origin (e.g. \"https://docs.example.com\"), no trailing slash. Used by the static build for canonical URLs, og:url, and sitemap.xml, and by llms.txt for absolute links."
-    },
-    "thumbnails": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "Auto-generated OG (social share) image options. Build-only.",
-      "properties": {
-        "background": {
-          "type": "string",
-          "description": "Project-relative path to a background image for the OG cards (e.g. \"/images/og-background.png\"). Defaults to a brand-color glow."
-        }
-      }
-    },
-    "seo": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "Search-engine optimization. Build-only: meta tags and sitemap behaviour applied when the site is built (not in the dev preview).",
-      "properties": {
-        "metatags": {
-          "type": "object",
-          "description": "Extra meta tags injected on every page, as a flat key→value map (e.g. \"google-site-verification\", \"og:image\").",
-          "additionalProperties": { "type": "string" }
-        },
-        "indexing": {
-          "type": "string",
-          "enum": ["navigable", "all"],
-          "description": "\"navigable\" (default) indexes only pages in navigation; \"all\" also includes hidden pages."
-        }
-      }
-    },
-    "contextual": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "Per-page context menu — the \"Copy Page\" split-button + dropdown of agent/IDE actions shown at the top of each page. Mintlify-compatible. Unset → copy, view, chatgpt, claude.",
-      "required": ["options"],
-      "properties": {
-        "options": {
-          "type": "array",
-          "description": "Menu items, in order. Known string options, or custom { title, description, href } entries.",
-          "items": {
-            "oneOf": [
-              {
-                "type": "string",
-                "enum": [
-                  "copy", "assistant", "view", "download-pdf", "download-spec",
-                  "chatgpt", "claude", "perplexity", "grok", "aistudio", "devin", "windsurf",
-                  "mcp", "add-mcp", "cursor", "vscode", "devin-mcp"
-                ]
-              },
-              {
-                "type": "object",
-                "additionalProperties": false,
-                "required": ["title", "href"],
-                "properties": {
-                  "title": { "type": "string", "description": "Menu item label." },
-                  "description": { "type": "string", "description": "Secondary line under the label." },
-                  "href": { "type": "string", "description": "URL to open." },
-                  "icon": { "type": "string", "description": "Lucide icon id." }
-                }
-              }
-            ]
-          }
-        },
-        "display": {
-          "type": "string",
-          "enum": ["header", "toc"],
-          "description": "Where the menu renders. Default \"header\"."
-        }
-      }
-    },
-    "assistant": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "Docs-site \"Ask AI\" backend. When apiBase is set, the published build wires the chatbot to the public docs-AI-assistant API; absent → the chatbot shows a canned demo answer (also in the dev preview). On Velu-hosted sites apiBase (and, when unset, suggestions) are filled in at publish time.",
-      "properties": {
-        "apiBase": {
-          "type": "string",
-          "description": "Base URL of the Velu backend that serves /api/v1/public/ai-assistant/* (e.g. \"https://api.getvelu.com\"). Must be same-site with the docs (or send a SameSite=None visitor cookie) for the credentialed requests to work."
-        },
-        "host": {
-          "type": "string",
-          "description": "Override the tenant-resolution host sent as X-Velu-Site-Host. Defaults to the page's own host at runtime."
-        },
-        "suggestions": {
-          "type": "array",
-          "items": { "type": "string" },
-          "maxItems": 6,
-          "description": "Starter questions shown when the Ask-AI panel opens. Unset on a Velu-hosted site → generated from the site's content at publish time."
-        }
-      }
-    }
-  },
-  "$defs": {
-    "navContainer": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "A navigation container. Higher-precedence keys nest the lower ones (products contain versions contain languages contain tabs contain groups/pages).",
-      "properties": {
-        "products": { "type": "array", "items": { "$ref": "#/$defs/product" } },
-        "versions": { "type": "array", "items": { "$ref": "#/$defs/version" } },
-        "languages": { "type": "array", "items": { "$ref": "#/$defs/language" } },
-        "tabs": { "type": "array", "items": { "$ref": "#/$defs/tab" } },
-        "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
-        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
-        "pages": { "$ref": "#/$defs/pages" }
-      }
-    },
-    "pages": {
-      "type": "array",
-      "description": "Ordered list of page paths (no extension, relative to the project root) and/or nested groups.",
-      "items": {
-        "oneOf": [
-          { "type": "string" },
-          { "$ref": "#/$defs/group" }
-        ]
-      }
-    },
-    "group": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["group"],
-      "properties": {
-        "group": { "type": "string", "description": "Sidebar section heading." },
-        "icon": { "type": "string", "description": "lucide icon id." },
-        "expanded": { "type": "boolean", "description": "Start expanded." },
-        "root": { "type": "string", "description": "Landing page path for the group." },
-        "openapi": { "$ref": "#/$defs/openapiRef" },
-        "api": { "$ref": "#/$defs/api" },
-        "pages": { "$ref": "#/$defs/pages" }
-      }
-    },
-    "tab": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["tab"],
-      "properties": {
-        "tab": { "type": "string", "description": "Tab label (top nav)." },
-        "icon": { "type": "string" },
-        "href": { "type": "string", "description": "External/override link instead of in-site pages." },
-        "openapi": { "$ref": "#/$defs/openapiRef" },
-        "api": { "$ref": "#/$defs/api" },
-        "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
-        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
-        "pages": { "$ref": "#/$defs/pages" }
-      }
-    },
-    "api": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "API reference behaviour for OpenAPI-generated pages. Set at the root, or on a tab/group with `openapi` to override it for just that section.",
-      "properties": {
-        "server": {
-          "type": "string",
-          "description": "Base URL override for the playground + code samples (otherwise the spec's first server is used)."
-        },
-        "playground": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "display": {
-              "type": "string",
-              "enum": ["interactive", "simple", "none"],
-              "description": "Playground mode. \"none\" disables the proxy / live send."
-            },
-            "proxy": {
-              "type": "boolean",
-              "description": "Send Try-It requests through the dev proxy to avoid CORS (default true)."
-            }
-          }
-        },
-        "examples": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "languages": {
-              "type": "array",
-              "items": { "type": "string", "enum": ["curl", "javascript", "python", "ruby"] },
-              "description": "Which request-snippet languages to generate."
-            }
-          }
-        }
-      }
-    },
-    "openapiRef": {
-      "description": "Path or URL to an OpenAPI spec (JSON/YAML), or an array of them. Auto-generates a page per operation, grouped by tag.",
-      "oneOf": [
-        { "type": "string" },
-        { "type": "array", "items": { "type": "string" } }
-      ]
-    },
-    "anchor": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["anchor", "href"],
-      "properties": {
-        "anchor": { "type": "string", "description": "Anchor label (pinned sidebar link)." },
-        "icon": { "type": "string" },
-        "href": { "type": "string" },
-        "color": { "type": "string" }
-      }
-    },
-    "product": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["product"],
-      "properties": {
-        "product": { "type": "string", "description": "Product id (used for the URL slug)." },
-        "name": { "type": "string", "description": "Display name; defaults to `product`." },
-        "icon": { "type": "string" },
-        "color": { "type": "string" },
-        "default": { "type": "boolean", "description": "The default product is unprefixed in URLs." },
-        "versions": { "type": "array", "items": { "$ref": "#/$defs/version" } },
-        "languages": { "type": "array", "items": { "$ref": "#/$defs/language" } },
-        "tabs": { "type": "array", "items": { "$ref": "#/$defs/tab" } },
-        "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
-        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
-        "pages": { "$ref": "#/$defs/pages" }
-      }
-    },
-    "version": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["version"],
-      "properties": {
-        "version": { "type": "string", "description": "Version label (used for the URL slug)." },
-        "default": { "type": "boolean", "description": "The default version is unprefixed in URLs." },
-        "languages": { "type": "array", "items": { "$ref": "#/$defs/language" } },
-        "tabs": { "type": "array", "items": { "$ref": "#/$defs/tab" } },
-        "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
-        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
-        "pages": { "$ref": "#/$defs/pages" }
-      }
-    },
-    "language": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["language"],
-      "properties": {
-        "language": { "type": "string", "description": "Language code (used for the URL slug)." },
-        "default": { "type": "boolean", "description": "The default language is unprefixed in URLs." },
-        "tabs": { "type": "array", "items": { "$ref": "#/$defs/tab" } },
-        "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
-        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
-        "pages": { "$ref": "#/$defs/pages" }
-      }
-    }
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://veludocs.com/velu.schema.json",
+  "title": "Velu project configuration",
+  "description": "Configuration for a Velu documentation project (velu.json). This schema is defined internally during iteration; it will be hosted at the $id URL so editors can validate + autocomplete velu.json files.",
+  "type": "object",
+  "required": ["name"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "URL of this JSON Schema, enabling editor validation + autocomplete."
+    },
+    "name": {
+      "type": "string",
+      "description": "Project name; usually the folder name it's contained in.",
+      "minLength": 1
+    },
+    "colors": {
+      "type": "object",
+      "description": "Accent colors. Maps onto the --accent-color token in base.css.",
+      "additionalProperties": false,
+      "required": ["primary"],
+      "properties": {
+        "primary": {
+          "type": "string",
+          "description": "The accent color used across the UI (--accent-color)."
+        },
+        "light": {
+          "type": "string",
+          "description": "Light-mode accent override. Defaults to `primary`."
+        },
+        "dark": {
+          "type": "string",
+          "description": "Dark-mode accent override. Defaults to `primary`."
+        }
+      }
+    },
+    "favicon": {
+      "type": "string",
+      "description": "Path to the favicon, relative to the project root."
+    },
+    "api": { "$ref": "#/$defs/api" },
+    "logo": {
+      "description": "Site logo shown in the header, replacing the name wordmark. A single path used in both themes, or per-theme light/dark images with an optional click-through href. Paths are relative to the project root.",
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "description": "Logo path used in both light and dark mode."
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["light", "dark"],
+          "properties": {
+            "light": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Logo shown in light mode."
+            },
+            "dark": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Logo shown in dark mode."
+            },
+            "href": {
+              "type": "string",
+              "description": "Where clicking the logo links. Defaults to the site root."
+            }
+          }
+        }
+      ]
+    },
+    "navbar": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The header's top-right area: secondary links plus a primary CTA button.",
+      "properties": {
+        "links": {
+          "type": "array",
+          "description": "Secondary header links (to the left of the primary CTA).",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["href"],
+            "properties": {
+              "label": { "type": "string", "description": "Link text." },
+              "href": { "type": "string", "description": "Link URL." },
+              "icon": { "type": "string", "description": "lucide icon id." }
+            }
+          }
+        },
+        "primary": {
+          "description": "The prominent CTA button at the far right.",
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["type", "label", "href"],
+              "properties": {
+                "type": { "const": "button" },
+                "label": { "type": "string", "description": "Button text." },
+                "href": { "type": "string", "description": "Button URL." }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["type", "href"],
+              "properties": {
+                "type": { "const": "github" },
+                "href": { "type": "string", "description": "GitHub repository URL." },
+                "label": { "type": "string", "description": "Button text (default \"GitHub\")." }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "footer": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Site footer. With `links`, a full footer section renders; with only `socials`, the icons sit next to the \"Powered by\" line instead.",
+      "properties": {
+        "socials": {
+          "type": "object",
+          "description": "Social links as platform → URL. Recognized icons: github, x (or twitter), youtube, linkedin.",
+          "additionalProperties": { "type": "string" }
+        },
+        "links": {
+          "type": "array",
+          "description": "Footer link columns (max 4).",
+          "maxItems": 4,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["header", "items"],
+            "properties": {
+              "header": { "type": "string", "description": "Column heading." },
+              "items": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["label", "href"],
+                  "properties": {
+                    "label": { "type": "string", "description": "Link text." },
+                    "href": { "type": "string", "description": "Link URL." }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "font": {
+      "type": "object",
+      "description": "Typography. Maps onto the --font-sans token in base.css.",
+      "additionalProperties": false,
+      "required": ["family"],
+      "properties": {
+        "family": {
+          "type": "string",
+          "description": "Google Font family to use (--font-sans)."
+        }
+      }
+    },
+    "navigation": {
+      "$ref": "#/$defs/navContainer",
+      "description": "Site navigation. Mintlify-compatible: products > versions > languages > tabs > groups > pages. Switchable axes (product/version/language) become URL path prefixes; the default value of each is unprefixed. Dropdowns are intentionally unsupported."
+    },
+    "url": {
+      "type": "string",
+      "description": "Production site origin (e.g. \"https://docs.example.com\"), no trailing slash. Used by the static build for canonical URLs, og:url, and sitemap.xml, and by llms.txt for absolute links."
+    },
+    "thumbnails": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Auto-generated OG (social share) image options. Build-only.",
+      "properties": {
+        "background": {
+          "type": "string",
+          "description": "Project-relative path to a background image for the OG cards (e.g. \"/images/og-background.png\"). Defaults to a brand-color glow."
+        }
+      }
+    },
+    "seo": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Search-engine optimization. Build-only: meta tags and sitemap behaviour applied when the site is built (not in the dev preview).",
+      "properties": {
+        "metatags": {
+          "type": "object",
+          "description": "Extra meta tags injected on every page, as a flat key→value map (e.g. \"google-site-verification\", \"og:image\").",
+          "additionalProperties": { "type": "string" }
+        },
+        "indexing": {
+          "type": "string",
+          "enum": ["navigable", "all"],
+          "description": "\"navigable\" (default) indexes only pages in navigation; \"all\" also includes hidden pages."
+        }
+      }
+    },
+    "contextual": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Per-page context menu — the \"Copy Page\" split-button + dropdown of agent/IDE actions shown at the top of each page. Mintlify-compatible. Unset → copy, view, chatgpt, claude.",
+      "required": ["options"],
+      "properties": {
+        "options": {
+          "type": "array",
+          "description": "Menu items, in order. Known string options, or custom { title, description, href } entries.",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "copy", "assistant", "view", "download-pdf", "download-spec",
+                  "chatgpt", "claude", "perplexity", "grok", "aistudio", "devin", "windsurf",
+                  "mcp", "add-mcp", "cursor", "vscode", "devin-mcp"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["title", "href"],
+                "properties": {
+                  "title": { "type": "string", "description": "Menu item label." },
+                  "description": { "type": "string", "description": "Secondary line under the label." },
+                  "href": { "type": "string", "description": "URL to open." },
+                  "icon": { "type": "string", "description": "Lucide icon id." }
+                }
+              }
+            ]
+          }
+        },
+        "display": {
+          "type": "string",
+          "enum": ["header", "toc"],
+          "description": "Where the menu renders. Default \"header\"."
+        }
+      }
+    },
+    "assistant": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Docs-site \"Ask AI\" backend. When apiBase is set, the published build wires the chatbot to the public docs-AI-assistant API; absent → the chatbot shows a canned demo answer (also in the dev preview). On Velu-hosted sites apiBase (and, when unset, suggestions) are filled in at publish time.",
+      "properties": {
+        "apiBase": {
+          "type": "string",
+          "description": "Base URL of the Velu backend that serves /api/v1/public/ai-assistant/* (e.g. \"https://api.getvelu.com\"). Must be same-site with the docs (or send a SameSite=None visitor cookie) for the credentialed requests to work."
+        },
+        "host": {
+          "type": "string",
+          "description": "Override the tenant-resolution host sent as X-Velu-Site-Host. Defaults to the page's own host at runtime."
+        },
+        "suggestions": {
+          "type": "array",
+          "items": { "type": "string" },
+          "maxItems": 6,
+          "description": "Starter questions shown when the Ask-AI panel opens. Unset on a Velu-hosted site → generated from the site's content at publish time."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "navContainer": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "A navigation container. Higher-precedence keys nest the lower ones (products contain versions contain languages contain tabs contain groups/pages).",
+      "properties": {
+        "products": { "type": "array", "items": { "$ref": "#/$defs/product" } },
+        "versions": { "type": "array", "items": { "$ref": "#/$defs/version" } },
+        "languages": { "type": "array", "items": { "$ref": "#/$defs/language" } },
+        "tabs": { "type": "array", "items": { "$ref": "#/$defs/tab" } },
+        "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
+        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
+        "pages": { "$ref": "#/$defs/pages" }
+      }
+    },
+    "pages": {
+      "type": "array",
+      "description": "Ordered list of page paths (no extension, relative to the project root) and/or nested groups.",
+      "items": {
+        "oneOf": [
+          { "type": "string" },
+          { "$ref": "#/$defs/group" }
+        ]
+      }
+    },
+    "group": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["group"],
+      "properties": {
+        "group": { "type": "string", "description": "Sidebar section heading." },
+        "icon": { "type": "string", "description": "lucide icon id." },
+        "expanded": { "type": "boolean", "description": "Start expanded." },
+        "root": { "type": "string", "description": "Landing page path for the group." },
+        "openapi": { "$ref": "#/$defs/openapiRef" },
+        "api": { "$ref": "#/$defs/api" },
+        "pages": { "$ref": "#/$defs/pages" }
+      }
+    },
+    "tab": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tab"],
+      "properties": {
+        "tab": { "type": "string", "description": "Tab label (top nav)." },
+        "icon": { "type": "string" },
+        "href": { "type": "string", "description": "External/override link instead of in-site pages." },
+        "openapi": { "$ref": "#/$defs/openapiRef" },
+        "api": { "$ref": "#/$defs/api" },
+        "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
+        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
+        "pages": { "$ref": "#/$defs/pages" }
+      }
+    },
+    "api": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "API reference behaviour for OpenAPI-generated pages. Set at the root, or on a tab/group with `openapi` to override it for just that section.",
+      "properties": {
+        "server": {
+          "type": "string",
+          "description": "Base URL override for the playground + code samples (otherwise the spec's first server is used)."
+        },
+        "playground": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "display": {
+              "type": "string",
+              "enum": ["interactive", "simple", "none"],
+              "description": "Playground mode. \"none\" disables the proxy / live send."
+            },
+            "proxy": {
+              "type": "boolean",
+              "description": "Send Try-It requests through the dev proxy to avoid CORS (default true)."
+            }
+          }
+        },
+        "examples": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "languages": {
+              "type": "array",
+              "items": { "type": "string", "enum": ["curl", "javascript", "python", "ruby"] },
+              "description": "Which request-snippet languages to generate."
+            }
+          }
+        }
+      }
+    },
+    "openapiRef": {
+      "description": "Path or URL to an OpenAPI spec (JSON/YAML), or an array of them. Auto-generates a page per operation, grouped by tag.",
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "anchor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["anchor", "href"],
+      "properties": {
+        "anchor": { "type": "string", "description": "Anchor label (pinned sidebar link)." },
+        "icon": { "type": "string" },
+        "href": { "type": "string" },
+        "color": { "type": "string" }
+      }
+    },
+    "product": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["product"],
+      "properties": {
+        "product": { "type": "string", "description": "Product id (used for the URL slug)." },
+        "name": { "type": "string", "description": "Display name; defaults to `product`." },
+        "icon": { "type": "string" },
+        "color": { "type": "string" },
+        "default": { "type": "boolean", "description": "The default product is unprefixed in URLs." },
+        "versions": { "type": "array", "items": { "$ref": "#/$defs/version" } },
+        "languages": { "type": "array", "items": { "$ref": "#/$defs/language" } },
+        "tabs": { "type": "array", "items": { "$ref": "#/$defs/tab" } },
+        "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
+        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
+        "pages": { "$ref": "#/$defs/pages" }
+      }
+    },
+    "version": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version"],
+      "properties": {
+        "version": { "type": "string", "description": "Version label (used for the URL slug)." },
+        "default": { "type": "boolean", "description": "The default version is unprefixed in URLs." },
+        "languages": { "type": "array", "items": { "$ref": "#/$defs/language" } },
+        "tabs": { "type": "array", "items": { "$ref": "#/$defs/tab" } },
+        "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
+        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
+        "pages": { "$ref": "#/$defs/pages" }
+      }
+    },
+    "language": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["language"],
+      "properties": {
+        "language": { "type": "string", "description": "Language code (used for the URL slug)." },
+        "default": { "type": "boolean", "description": "The default language is unprefixed in URLs." },
+        "tabs": { "type": "array", "items": { "$ref": "#/$defs/tab" } },
+        "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
+        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
+        "pages": { "$ref": "#/$defs/pages" }
+      }
+    }
+  }
+}