@veluai/velu 0.1.16 → 0.2.0

package/runtime/velu-ui/components/not-found.css

@@ -0,0 +1,94 @@
+/* not-found.css — the 404 page (Direction 1 · Classic).
+   Mapped onto Velu tokens, so light/dark follow [data-theme]. */
+
+.velu-404 {
+  inline-size: 34rem;
+  max-inline-size: 100%;
+  margin-inline: auto;
+  text-align: center;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+.velu-404__eyebrow {
+  margin: 0 0 var(--s-1);
+  font-size: 0.75rem;
+  font-weight: var(--weight-medium);
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--accent-color);
+}
+
+/* Big crimson numeral — the brand font (Outfit), light weight. clamp keeps
+   it large on desktop but never overflows a narrow screen. */
+.velu-404__num {
+  font-family: var(--font-brand);
+  font-weight: var(--weight-light);
+  font-size: clamp(7rem, 30vw, 9.375rem);
+  line-height: 0.9;
+  letter-spacing: -0.04em;
+  color: var(--accent-color);
+  margin-block-end: var(--s0);
+}
+
+.velu-404__title {
+  margin: 0 0 var(--s-1);
+  font-size: var(--f-h2);
+  font-weight: var(--weight-semibold);
+  letter-spacing: -0.02em;
+  line-height: 1.1;
+  color: var(--text-color);
+}
+
+.velu-404__body {
+  margin: 0 0 var(--s2);
+  max-inline-size: 27rem;
+  font-size: var(--f-body);
+  font-weight: var(--weight-light);
+  line-height: 1.55;
+  color: var(--muted-color);
+}
+
+.velu-404__actions {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-wrap: wrap;
+  gap: var(--s-1);
+  margin-block-start: var(--s-2);
+}
+
+.velu-404__btn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2);
+  white-space: nowrap;
+  padding: var(--s-2) var(--s1);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-md);
+  background: var(--page-bg);
+  color: var(--text-color);
+  font: inherit;
+  font-size: var(--f-h6);
+  font-weight: var(--weight-medium);
+  text-decoration: none;
+  cursor: pointer;
+  transition: border-color 0.12s ease, background 0.12s ease;
+}
+.velu-404__btn:hover {
+  border-color: var(--accent-color);
+}
+.velu-404__btn--primary {
+  background: var(--accent-color);
+  border-color: var(--accent-color);
+  color: #fff;
+  font-weight: var(--weight-bold);
+}
+.velu-404__btn--primary:hover {
+  background: color-mix(in srgb, var(--accent-color) 88%, #000);
+}
+.velu-404__btn-ic {
+  display: inline-flex;
+  align-items: center;
+}

package/runtime/velu-ui/components/powered-by.css

@@ -16,6 +16,12 @@
 .velu-content-foot .velu-powered-by {
   margin: 0;
   padding: 0;
+  /* Fill the row so the badge's own `justify-content: flex-end` right-aligns
+     it — with or without the social icons as a sibling. (Avoids a
+     `margin-inline-start: auto` reset, which the production CSS minifier folds
+     away when it follows `margin: 0`, leaving the lone badge stuck at the
+     start in the build but not in dev.) */
+  flex: 1;
 }
 .velu-content-foot .velu-social {
   color: var(--muted-color);

package/runtime/velu-ui/index.js

@@ -4,6 +4,7 @@ export { default as Cluster } from './primitives/Cluster.jsx';
 export { default as ThemeToggle } from './components/ThemeToggle.jsx';
 export { default as Sidebar } from './components/Sidebar.jsx';
 export { default as NavSelect } from './components/NavSelect.jsx';
+export { default as ContextMenu } from './components/ContextMenu.jsx';
 export { default as Toc } from './components/Toc.jsx';
 export { default as TocBar } from './components/TocBar.jsx';
 export { default as Callout } from './components/Callout.jsx';
@@ -28,6 +29,7 @@ export { default as ApiClient } from './components/ApiClient.jsx';
 export { default as ApiSidebar } from './components/ApiSidebar.jsx';
 export { default as ApiReferencePage } from './components/ApiReferencePage.jsx';
 export { default as ApiSamples } from './components/ApiSamples.jsx';
+export { default as NotFound } from './components/NotFound.jsx';
 export { default as AskBar } from './components/AskBar.jsx';
 export { default as Chatbot } from './components/Chatbot.jsx';
 export { default as PageFeedback } from './components/PageFeedback.jsx';

package/runtime/velu-ui/lib/brand-icons.jsx

@@ -0,0 +1,102 @@
+import React from 'react';
+
+/**
+ * Brand glyphs for the contextual menu's "Open in <tool>" / "Connect to <IDE>"
+ * actions. Sourced from svgl.app and inlined (the project inlines icons as JSX,
+ * like lucide — no SVG loader). Each takes a `size` prop, mirroring lucide's
+ * icon API so they're drop-in in the menu.
+ *
+ * Monochrome marks (OpenAI, Cursor) use `currentColor` so they follow the menu
+ * text/hover color across light + dark. Multi-color marks (Claude, Perplexity,
+ * VS Code) keep their brand colors — legible on both themes.
+ */
+
+export function MarkdownIcon({ size = '1em', ...rest }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 208 128" fill="none" aria-hidden="true" {...rest}>
+      <path
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="10"
+        d="M15 5h178a10 10 0 0 1 10 10v98a10 10 0 0 1-10 10H15a10 10 0 0 1-10-10V15A10 10 0 0 1 15 5z"
+      />
+      <path
+        fill="currentColor"
+        d="M30 98V30h20l20 25 20-25h20v68H90V59L70 84 50 59v39H30zm125 0-30-33h20V30h20v35h20l-30 33z"
+      />
+    </svg>
+  );
+}
+
+export function OpenAIIcon({ size = '1em', ...rest }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 256 260" fill="currentColor" aria-hidden="true" {...rest}>
+      <path d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z" />
+    </svg>
+  );
+}
+
+export function ClaudeIcon({ size = '1em', ...rest }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 256 257" aria-hidden="true" {...rest}>
+      <path fill="#D97757" d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z" />
+    </svg>
+  );
+}
+
+export function PerplexityIcon({ size = '1em', ...rest }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 48 48" fill="none" aria-hidden="true" {...rest}>
+      <g stroke="#20808d" strokeLinecap="round" strokeLinejoin="round">
+        <path d="M24 4.5v39M13.73 16.573v-9.99L24 16.573m0 14.5L13.73 41.417V27.01L24 16.573m0 0l10.27-9.99v9.99" />
+        <path d="M13.73 31.396H9.44V16.573h29.12v14.823h-4.29" />
+        <path d="M24 16.573L34.27 27.01v14.407L24 31.073" />
+      </g>
+    </svg>
+  );
+}
+
+export function CursorIcon({ size = '1em', ...rest }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 466.73 532.09" fill="currentColor" aria-hidden="true" {...rest}>
+      <path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z" />
+    </svg>
+  );
+}
+
+export function VscodeIcon({ size = '1em', ...rest }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 100 100" fill="none" aria-hidden="true" {...rest}>
+      <mask
+        id="velu-vsc-mask"
+        width="100"
+        height="100"
+        x="0"
+        y="0"
+        maskUnits="userSpaceOnUse"
+        style={{ maskType: 'alpha' }}
+      >
+        <path
+          fill="#fff"
+          fillRule="evenodd"
+          clipRule="evenodd"
+          d="M70.912 99.317a6.223 6.223 0 0 0 4.96-.19l20.589-9.907A6.25 6.25 0 0 0 100 83.587V16.413a6.25 6.25 0 0 0-3.54-5.632L75.874.874a6.226 6.226 0 0 0-7.104 1.21L29.355 38.04 12.187 25.01a4.162 4.162 0 0 0-5.318.236l-5.506 5.009a4.168 4.168 0 0 0-.004 6.162L16.247 50 1.36 63.583a4.168 4.168 0 0 0 .004 6.162l5.506 5.01a4.162 4.162 0 0 0 5.318.236l17.168-13.032L68.77 97.917a6.217 6.217 0 0 0 2.143 1.4ZM75.015 27.3 45.11 50l29.906 22.701V27.3Z"
+        />
+      </mask>
+      <g mask="url(#velu-vsc-mask)">
+        <path
+          fill="#0065A9"
+          d="M96.461 10.796 75.857.876a6.23 6.23 0 0 0-7.107 1.207l-67.451 61.5a4.167 4.167 0 0 0 .004 6.162l5.51 5.009a4.167 4.167 0 0 0 5.32.236l81.228-61.62c2.725-2.067 6.639-.124 6.639 3.297v-.24a6.25 6.25 0 0 0-3.539-5.63Z"
+        />
+        <path
+          fill="#007ACC"
+          d="m96.461 89.204-20.604 9.92a6.229 6.229 0 0 1-7.107-1.207l-67.451-61.5a4.167 4.167 0 0 1 .004-6.162l5.51-5.009a4.167 4.167 0 0 1 5.32-.236l81.228 61.62c2.725 2.067 6.639.124 6.639-3.297v.24a6.25 6.25 0 0 1-3.539 5.63Z"
+        />
+        <path
+          fill="#1F9CF0"
+          d="M75.858 99.126a6.232 6.232 0 0 1-7.108-1.21c2.306 2.307 6.25.674 6.25-2.588V4.672c0-3.262-3.944-4.895-6.25-2.589a6.232 6.232 0 0 1 7.108-1.21l20.6 9.908A6.25 6.25 0 0 1 100 16.413v67.174a6.25 6.25 0 0 1-3.541 5.633l-20.601 9.906Z"
+        />
+      </g>
+    </svg>
+  );
+}

package/runtime/velu-ui/styles.css

@@ -21,6 +21,7 @@
 @import './primitives/switcher.css';
 @import './components/sidebar.css';
 @import './components/nav-select.css';
+@import './components/context-menu.css';
 @import './components/accordion.css';
 @import './components/card.css';
 @import './components/image.css';
@@ -31,6 +32,7 @@
 @import './components/tree.css';
 @import './components/api.css';
 @import './components/api-page.css';
+@import './components/not-found.css';
 @import './components/ask-bar.css';
 @import './components/chatbot.css';
 @import './components/page-feedback.css';

package/schema/velu.schema.json

@@ -40,43 +40,7 @@
       "type": "string",
       "description": "Path to the favicon, relative to the project root."
     },
-    "api": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "API reference behaviour for OpenAPI-generated pages.",
-      "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."
-            }
-          }
-        }
-      }
-    },
+    "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": [
@@ -206,6 +170,78 @@
     "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\"."
+        }
+      }
     }
   },
   "$defs": {
@@ -243,6 +279,7 @@
         "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" }
       }
     },
@@ -255,11 +292,49 @@
         "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": [

package/src/runtime/App.jsx

@@ -14,6 +14,7 @@ import {
   NavSelect,
   Toc,
   TocBar,
+  ContextMenu,
   Callout,
   Accordion,
   AccordionGroup,
@@ -48,6 +49,7 @@ import {
   ApiField,
   ApiSidebar,
   ApiSamples,
+  NotFound,
   VeluMark,
 } from 'velu-ui';
 import { X, ChevronDown, ChevronUp } from 'lucide-react';
@@ -727,6 +729,9 @@ function DocsPage() {
   const frontmatter = entry?.frontmatter ?? {};
   const PageComponent = entry?.Component ?? null;
   const pageToc = entry?.toc ?? [];
+  // No renderable page for this route → show the 404 page (a clean centered
+  // takeover: header + footer stay, the docs sidebar/TOC are hidden).
+  const isNotFound = !PageComponent;
 
   // Switcher option sets (only render a switcher when an axis has >1
   // option). Anchors are pinned sidebar links shown in the context zone.
@@ -763,6 +768,27 @@ function DocsPage() {
     />
   );
 
+  // Keep document.title / meta description / <html lang> in sync on client-side
+  // navigation. The HTML is SSR'd with a per-page (build) or generic (dev) title;
+  // without this the tab title would stay frozen on the first page as you
+  // navigate the SPA, and JS-executing crawlers would read the stale value.
+  React.useEffect(() => {
+    const t = frontmatter.title;
+    document.title = isNotFound
+      ? `Page not found - ${site.name}`
+      : t && t !== site.name
+        ? `${t} - ${site.name}`
+        : site.name;
+    let descTag = document.querySelector('meta[name="description"]');
+    if (!descTag) {
+      descTag = document.createElement('meta');
+      descTag.setAttribute('name', 'description');
+      document.head.appendChild(descTag);
+    }
+    descTag.setAttribute('content', frontmatter.description || '');
+    document.documentElement.lang = nav?.activeLanguageCode || 'en';
+  }, [pathname, isNotFound, frontmatter.title, frontmatter.description, nav?.activeLanguageCode]);
+
   // Frontmatter title needs an id so scroll-spy + click-to-scroll work
   // against it like any other heading.
   const pageId = React.useMemo(() => {
@@ -1059,6 +1085,7 @@ function DocsPage() {
       data-sidebar-open={sidebarOpen ? 'true' : 'false'}
       data-drawer-open={drawerOpen ? 'true' : 'false'}
       data-api={entry?.api ? 'true' : 'false'}
+      data-not-found={isNotFound ? 'true' : undefined}
     >
       {/* Scrim — visible at mobile while the drawer OR the chatbot
           sheet is open. Sits between the article (z-0) and the
@@ -1353,6 +1380,21 @@ function DocsPage() {
           and the right margin collapses to 0 while the chatbot is
           open via [data-chat-open="true"]). */}
       <div className="velu-docs-layout__center">
+        {isNotFound ? (
+          <main className="velu-404-main">
+            <NotFound
+              homeHref="/"
+              linkComponent={RouterLink}
+              onSearch={() =>
+                window.dispatchEvent(
+                  new KeyboardEvent('keydown', { key: 'k', ctrlKey: true, metaKey: true }),
+                )
+              }
+              onAskAI={IS_DEV_PREVIEW ? undefined : () => askAI('')}
+            />
+          </main>
+        ) : (
+        <>
         {/* Narrow-layout TOC bar — always in DOM, only visible at
             < 1024px (toggled by @container in toc-bar.css). Shares
             its `items` + `activeId` + `onSelect` API with the
@@ -1396,6 +1438,24 @@ function DocsPage() {
           </span>
         </button>
         <div className="velu-docs-layout__article">
+          {/* Per-page agent/IDE action bar: the section eyebrow + a
+              "Copy Page" split-button whose dropdown is driven by the
+              Mintlify-compatible `contextual` config. Renders nothing
+              when there's neither an eyebrow nor any enabled options. */}
+          <ContextMenu
+            eyebrow={
+              nav?.breadcrumb && nav.breadcrumb.length > 1
+                ? nav.breadcrumb[nav.breadcrumb.length - 2].label
+                : undefined
+            }
+            pageUrl={pathname}
+            title={frontmatter.title}
+            isApi={entry?.api === true}
+            siteName={site.name}
+            options={site.contextual?.options ?? []}
+            onAssistant={IS_DEV_PREVIEW ? undefined : () => askAI('')}
+          />
+
           {/* Page hero from MDX frontmatter. `.velu-hero` rules
               (in base.css) keep the title and description tightly
               grouped and create a clear break before the prose body. */}
@@ -1494,6 +1554,8 @@ function DocsPage() {
           )}
         </div>
       </main>
+        </>
+        )}
       </div>
 
       {/* Full site footer — only when the config provides link columns. Spans

package/templates/starter/velu.json

@@ -1,10 +1,14 @@
 {
   "$schema": "https://veludocs.com/velu.schema.json",
   "name": "Starter",
+  "url": "https://veludocs.com",
   "colors": {
     "primary": "#dc143c"
   },
   "favicon": "/favicon.svg",
+  "contextual": {
+    "options": ["copy", "view", "chatgpt", "claude", "mcp", "cursor", "vscode"]
+  },
   "navigation": {
     "anchors": [
       { "anchor": "Documentation", "icon": "book-open", "href": "https://veludocs.com" },