@veluai/velu 0.2.0 → 0.2.2

package/runtime/velu-ui/components/sidebar.css

@@ -7,10 +7,51 @@
    rotation, and centralized icon sizing/stroke. All values are tokens. */
 
 .velu-sidebar {
-  border-left: var(--border-width) solid var(--surface-color);
+  position: relative; /* anchors the gliding active indicator */
   margin-left: var(--s1);
 }
 
+/* The single active indicator — a crimson tint band with a flush-left 2px bar
+   that GLIDES between items (one element animating its position/height) instead
+   of each item painting its own active state. z-index 0 keeps it BEHIND the
+   items + sticky headings (both positioned, z-index 1), so the text reads over
+   the tint and a pinned heading's opaque background covers the indicator when an
+   item scrolls under it. Driven imperatively from JS (transform/height/opacity);
+   the easing curve makes the slide feel continuous. */
+.velu-sidebar__indicator {
+  position: absolute;
+  inset-inline-start: 0;
+  inset-inline-end: var(--s-3);
+  inset-block-start: 0;
+  height: 0;
+  opacity: 0;
+  z-index: 0;
+  pointer-events: none;
+  background: color-mix(in srgb, var(--accent-color) 8%, transparent);
+  border-radius: var(--radius-sm);
+  transition:
+    transform 0.3s cubic-bezier(0.32, 0.72, 0, 1),
+    height 0.3s cubic-bezier(0.32, 0.72, 0, 1),
+    opacity 0.2s ease;
+  will-change: transform, height;
+}
+.velu-sidebar__indicator::before {
+  content: '';
+  position: absolute;
+  inset-inline-start: 0;
+  inset-block: 15%;
+  inline-size: 2px;
+  border-start-end-radius: 2px;
+  border-end-end-radius: 2px;
+  background: var(--accent-color);
+}
+/* Honour reduced-motion: snap instead of glide. */
+@media (prefers-reduced-motion: reduce) {
+  .velu-sidebar__indicator {
+    transition: opacity 0.2s ease;
+  }
+}
+
 .velu-sidebar__section {
   /* Sticky section header: each heading pins to the top of the scroll
      region until its own section scrolls past, then the next heading
@@ -21,7 +62,10 @@
      bar is invisible until it's actually covering scrolled content. */
   position: sticky;
   inset-block-start: 0;
-  z-index: 1;
+  /* Above the items (z-index 1) so scrolled rows tuck UNDER the heading (its
+     opaque bg + the ::after fade hide them), not over it; above the gliding
+     indicator (z-index 0) too. */
+  z-index: 2;
   background: var(--page-bg);
   display: flex;
   align-items: center;
@@ -94,21 +138,38 @@
    so these stay CSS until/if a Cluster/Inline primitive exists. */
 .velu-sidebar__item,
 .velu-sidebar__subitem {
+  /* Positioned above the gliding indicator (z-index 0) so the label reads over
+     the tint band. */
+  position: relative;
+  z-index: 1;
   display: flex;
   align-items: center;
   gap: var(--s-3);
   padding-inline: var(--s0);
   color: var(--text-color);
   text-decoration: none;
+  transition: color 0.2s ease;
 }
 
 .velu-sidebar__subitem {
   padding-block: var(--s-5);
 }
 
+/* Active = colour + weight only; the moving indicator paints the bar + tint. */
 .velu-sidebar__item--active {
   color: var(--accent-color);
-  border-left: 2px solid var(--accent-color);
+  font-weight: 500;
+}
+.velu-sidebar__item--active .velu-sidebar__icon {
+  color: var(--accent-color);
+}
+
+/* The label fills the row so the group chevron (and any external-link icon)
+   sit flush at the row's RIGHT end, not crowded against the label — faithful
+   to the design's `flex: 1` label. */
+.velu-sidebar__label {
+  flex: 1;
+  min-inline-size: 0;
 }
 
 .velu-sidebar__summary {

package/runtime/velu-ui/components/theme-toggle.css

@@ -39,6 +39,7 @@
     transform 0.18s cubic-bezier(0.34, 1.56, 0.64, 1);
 }
 .velu-theme-toggle:hover {
+  background: var(--surface-color);
   border-color: var(--accent-color);
 }
 /* Tactile press feedback on click. */

package/runtime/velu-ui/index.js

@@ -42,6 +42,8 @@ export {
   VeluMark,
 } from './components/PageHeader.jsx';
 export { default as Search } from './components/Search.jsx';
+export { default as pagefindSearch } from './lib/pagefind.js';
+export { createDocsAssistant } from './lib/docs-assistant.js';
 export { default as Image } from './components/Image.jsx';
 export {
   default as CodeBlock,

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

@@ -6,9 +6,10 @@ import React from 'react';
  * 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.
+ * ALL marks use `currentColor` so the icon column reads as one uniform set:
+ * muted/grey at rest, accent on hover (matching the lucide icons beside them).
+ * The brand glyphs keep their distinctive shapes; only the fill follows the
+ * menu's text/hover color across light + dark.
  */
 
 export function MarkdownIcon({ size = '1em', ...rest }) {
@@ -39,7 +40,7 @@ export function OpenAIIcon({ size = '1em', ...rest }) {
 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" />
+      <path fill="currentColor" 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>
   );
 }
@@ -47,7 +48,7 @@ export function ClaudeIcon({ size = '1em', ...rest }) {
 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">
+      <g stroke="currentColor" 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" />
@@ -85,15 +86,15 @@ export function VscodeIcon({ size = '1em', ...rest }) {
       </mask>
       <g mask="url(#velu-vsc-mask)">
         <path
-          fill="#0065A9"
+          fill="currentColor"
           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"
+          fill="currentColor"
           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"
+          fill="currentColor"
           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>

package/runtime/velu-ui/lib/docs-assistant.js

@@ -0,0 +1,163 @@
+/**
+ * docs-assistant — runtime client for the published docs site's "Ask AI",
+ * talking to the backend's PUBLIC docs-AI-assistant API:
+ *
+ *   GET  /api/v1/public/ai-assistant/bootstrap                    (visitor cookie + tenant)
+ *   POST /api/v1/public/ai-assistant/messages                     ({ message, conversation_id })
+ *   GET  /api/v1/public/ai-assistant/conversations/{id}/events    (SSE; ?token=…)
+ *   POST|DELETE /api/v1/public/ai-assistant/messages/{id}/feedback ({ rating })
+ *
+ * `createDocsAssistant({ apiBase, host })` returns `{ ask, sendFeedback }`,
+ * shaped to drop straight into <Chatbot ask onFeedback>. `ask` is an async
+ * generator yielding the AskEvent shape Chatbot expects.
+ *
+ * Contract notes (from the backend):
+ *  - bootstrap sets an **httponly visitor cookie**, so every call uses
+ *    `credentials: 'include'`. Cross-origin therefore needs CORS w/ credentials
+ *    AND a cross-site-capable cookie (SameSite=None) — today the cookie is
+ *    SameSite=Lax, so the API must be same-site with the docs (proxied under the
+ *    docs domain) until the backend relaxes it. See the plan's open questions.
+ *  - tenant is resolved from the `X-Velu-Site-Host` header (falls back to Origin).
+ *  - POST /messages returns immediately; the answer is generated in the
+ *    background and arrives as a SINGLE `assistant.completed` SSE event with the
+ *    full content + citations (NOT token-by-token). So `ask` yields one content
+ *    event when the answer is ready (the panel shows its "thinking" state until).
+ */
+
+const trimSlash = (s) => String(s || '').replace(/\/+$/, '');
+
+function siteHost(explicit) {
+  if (explicit) return explicit;
+  return typeof window !== 'undefined' ? window.location.host : '';
+}
+
+// Parse one raw SSE record ("event: x\ndata: {…}") into { event, data }.
+function parseSseRecord(raw) {
+  let event = 'message';
+  const dataLines = [];
+  for (const line of raw.split('\n')) {
+    if (line.startsWith('event:')) event = line.slice(6).trim();
+    else if (line.startsWith('data:')) dataLines.push(line.slice(5).replace(/^ /, ''));
+  }
+  if (!dataLines.length) return { event, data: null };
+  try {
+    return { event, data: JSON.parse(dataLines.join('\n')) };
+  } catch {
+    return { event, data: null };
+  }
+}
+
+// Backend citation → the Chatbot's Source shape.
+function mapCitations(cits) {
+  if (!Array.isArray(cits)) return undefined;
+  return cits.map((c, i) => ({
+    num: c.num ?? c.index ?? i + 1,
+    title: c.title,
+    path: c.route_path ?? c.path,
+    url: c.url,
+  }));
+}
+
+export function createDocsAssistant({ apiBase, host } = {}) {
+  const base = trimSlash(apiBase);
+  if (!base) return null;
+  const root = `${base}/api/v1/public/ai-assistant`;
+  let bootstrapped = false;
+
+  const headers = (extra) => ({
+    'X-Velu-Site-Host': siteHost(host),
+    ...extra,
+  });
+
+  async function bootstrap() {
+    if (bootstrapped) return;
+    // Sets the httponly visitor cookie used by every subsequent call.
+    await fetch(`${root}/bootstrap`, {
+      method: 'GET',
+      credentials: 'include',
+      headers: headers(),
+    });
+    bootstrapped = true;
+  }
+
+  // Async generator: yields { conversationId } early, then one
+  // { delta, citations, messageId, conversationId } when the answer is ready.
+  async function* ask(prompt, { conversationId, signal } = {}) {
+    await bootstrap();
+
+    const res = await fetch(`${root}/messages`, {
+      method: 'POST',
+      credentials: 'include',
+      headers: headers({ 'Content-Type': 'application/json' }),
+      body: JSON.stringify({ message: prompt, conversation_id: conversationId ?? null }),
+      signal,
+    });
+    if (!res.ok) throw new Error(`ask-ai: messages ${res.status}`);
+    const { conversation_id: convId, conversation_token: token } = await res.json();
+    yield { conversationId: convId };
+
+    // Manual fetch-stream SSE parse (not EventSource): supports credentials,
+    // the X-Velu-Site-Host header, and AbortController cancellation.
+    const evRes = await fetch(
+      `${root}/conversations/${convId}/events?after_seq=0&token=${encodeURIComponent(token)}`,
+      { credentials: 'include', headers: headers({ Accept: 'text/event-stream' }), signal },
+    );
+    if (!evRes.ok || !evRes.body) throw new Error(`ask-ai: stream ${evRes.status}`);
+
+    const reader = evRes.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        let sep;
+        while ((sep = buf.indexOf('\n\n')) !== -1) {
+          const { event, data } = parseSseRecord(buf.slice(0, sep));
+          buf = buf.slice(sep + 2);
+          if (event === 'assistant.completed') {
+            const m = data?.message || {};
+            yield {
+              delta: m.content || '',
+              citations: mapCitations(m.citations),
+              messageId: m.id,
+              conversationId: convId,
+            };
+            return; // answer delivered — done
+          }
+          if (event === 'assistant.error') {
+            throw new Error(data?.error || 'ask-ai: generation failed');
+          }
+          // message.created (echoed user turn) and ping are ignored.
+        }
+      }
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+        /* already closed */
+      }
+    }
+  }
+
+  // rating: 'up' | 'down' to set, null to retract.
+  async function sendFeedback(messageId, rating) {
+    if (messageId == null) return;
+    const url = `${root}/messages/${messageId}/feedback`;
+    if (rating == null) {
+      await fetch(url, { method: 'DELETE', credentials: 'include', headers: headers() });
+      return;
+    }
+    await fetch(url, {
+      method: 'POST',
+      credentials: 'include',
+      headers: headers({ 'Content-Type': 'application/json' }),
+      body: JSON.stringify({ rating }),
+    });
+  }
+
+  return { ask, sendFeedback };
+}
+
+export default createDocsAssistant;

package/runtime/velu-ui/lib/pagefind.js

@@ -0,0 +1,113 @@
+// Pagefind client — queries the static search index that `velu build` writes to
+// /pagefind/. The index is a chunked, lazy-loaded WASM bundle: the browser only
+// downloads the fragments it needs per query, so search scales to huge sites
+// without shipping one giant index. Generated at build time; absent in dev
+// (the dev preview shows search as "unavailable").
+//
+// The runtime is loaded via a NON-analyzable dynamic import (a Function-wrapped
+// import) so neither Vite nor the bundler tries to resolve /pagefind/pagefind.js
+// at build time — it only exists in the deployed output.
+
+let _pf = null;
+let _loading = null;
+
+async function loadRuntime() {
+  if (_pf) return _pf;
+  if (_loading) return _loading;
+  _loading = (async () => {
+    const importer = new Function('p', 'return import(p)');
+    const mod = await importer('/pagefind/pagefind.js');
+    if (typeof mod.init === 'function') await mod.init();
+    _pf = mod;
+    return mod;
+  })();
+  try {
+    return await _loading;
+  } catch (err) {
+    _loading = null;
+    throw err;
+  }
+}
+
+const stripHtml = (s) => String(s || '').replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+
+// Pagefind returns directory URLs (/quickstart/, /a/b/, /); normalize to the
+// router's path form (/quickstart, /a/b, /). Preserve any #anchor.
+function normalizeUrl(url) {
+  if (!url) return '/';
+  let [path, hash] = String(url).split('#');
+  path = path.replace(/index\.html?$/i, '').replace(/\.html?$/i, '');
+  if (path.length > 1) path = path.replace(/\/+$/, '');
+  if (!path) path = '/';
+  return hash ? `${path}#${hash}` : path;
+}
+
+// Breadcrumb from the URL path (everything but the leaf), title-cased.
+function crumbsFromUrl(url) {
+  const segs = String(url).split('#')[0].split('/').filter(Boolean);
+  segs.pop();
+  return segs.map((s) => s.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()));
+}
+
+/**
+ * Run a query against the static Pagefind index.
+ * @returns {Promise<Array<SearchResult>|null>} palette-shaped results, or null
+ *   when the index can't be loaded (→ caller can show "unavailable").
+ */
+export default async function pagefindSearch(query) {
+  const q = String(query || '').trim();
+  if (!q) return [];
+
+  let pf;
+  try {
+    pf = await loadRuntime();
+  } catch {
+    return null; // index not present (e.g. not built) → unavailable
+  }
+
+  let response;
+  try {
+    response = await pf.search(q);
+  } catch {
+    return [];
+  }
+
+  const hits = await Promise.all(response.results.slice(0, 8).map((r) => r.data()));
+  const out = [];
+  const seen = new Set(); // dedupe by href
+  for (const hit of hits) {
+    const href = normalizeUrl(hit.url);
+    const title = hit.meta?.title || crumbsFromUrl(hit.url).pop() || href;
+    if (!seen.has(href)) {
+      seen.add(href);
+      out.push({
+        id: href,
+        group: 'Pages',
+        breadcrumb: crumbsFromUrl(hit.url),
+        title,
+        kind: 'page',
+        desc: stripHtml(hit.excerpt),
+        href,
+      });
+    }
+    // Heading-level matches → deep-linkable anchor rows. Skip the page's own
+    // top section (pagefind repeats it as a sub-result with the page title).
+    for (const sub of hit.sub_results || []) {
+      const subHref = normalizeUrl(sub.url);
+      if (seen.has(subHref) || !subHref.includes('#') || sub.title === title) continue;
+      seen.add(subHref);
+      out.push({
+        id: subHref,
+        group: 'Pages',
+        breadcrumb: [title],
+        title: sub.title || title,
+        kind: 'anchor',
+        desc: stripHtml(sub.excerpt),
+        href: subHref,
+      });
+      if (out.length >= 12) break;
+    }
+    if (out.length >= 12) break;
+  }
+  return out;
+}

package/schema/velu.schema.json

@@ -242,6 +242,22 @@
           "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).",
+      "required": ["apiBase"],
+      "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."
+        }
+      }
     }
   },
   "$defs": {

package/src/runtime/App.jsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Routes, Route, useLocation, Link } from 'react-router-dom';
+import { Routes, Route, useLocation, useNavigate, Link } from 'react-router-dom';
 import { MDXProvider } from '@mdx-js/react';
 // The project's pages + navigation, generated from velu.json by
 // vite-plugin-velu-site (see src/vite-plugin-velu-site.js). `pages` is
@@ -39,6 +39,8 @@ import {
   defaultMdxComponents,
   resolveIcon,
   Search,
+  pagefindSearch,
+  createDocsAssistant,
   Logo,
   SocialLinks,
   Tree,
@@ -719,6 +721,7 @@ function DocsPage() {
   // SSR and client compute these from the same pathname + the same
   // shared `resolve()`, so the render is identical (hydration-safe).
   const location = useLocation();
+  const navigate = useNavigate();
   const pathname = normalizeUrl(location.pathname);
   const entry = pages[pathname];
   const nav = React.useMemo(
@@ -726,6 +729,33 @@ function DocsPage() {
     [pathname],
   );
 
+  // Search source: Pagefind for content/excerpts, but resolve each result's
+  // breadcrumb from the real NAVIGATION (a page's nav group can differ from its
+  // URL path — e.g. essentials/markdown.mdx lives under the "Writing Content"
+  // group). Page rows show the path to the page; anchor rows include the page.
+  const searchDocs = React.useCallback(async (q) => {
+    const results = await pagefindSearch(q);
+    if (!Array.isArray(results)) return results;
+    return results.map((r) => {
+      const res = resolve(r.href.split('#')[0], navigation, pages);
+      if (!res?.breadcrumb?.length) return r;
+      const labels = res.breadcrumb.map((c) => c.label);
+      const crumbs = r.kind === 'anchor' ? labels : labels.slice(0, -1);
+      return crumbs.length ? { ...r, breadcrumb: crumbs } : r;
+    });
+  }, []);
+
+  // Ask-AI backend: wire the chatbot to the public docs-AI-assistant API only
+  // in a real build AND when an apiBase is configured (velu.json → assistant).
+  // Otherwise `ask` stays undefined and the Chatbot uses its canned demo answer
+  // (dev preview, or a site that hasn't enabled the assistant).
+  const assistant = React.useMemo(() => {
+    if (IS_DEV_PREVIEW) return null;
+    const apiBase = site.assistant?.apiBase;
+    if (!apiBase) return null;
+    return createDocsAssistant({ apiBase, host: site.assistant?.host });
+  }, []);
+
   const frontmatter = entry?.frontmatter ?? {};
   const PageComponent = entry?.Component ?? null;
   const pageToc = entry?.toc ?? [];
@@ -1116,7 +1146,12 @@ function DocsPage() {
         tabsTrailing={languageSwitcher || undefined}
         center={
           <Cluster space="var(--s-6)" align="center">
-            <Search style={{ inlineSize: '30ch' }} unavailable={IS_DEV_PREVIEW} />
+            <Search
+              style={{ inlineSize: '30ch' }}
+              unavailable={IS_DEV_PREVIEW}
+              search={IS_DEV_PREVIEW ? undefined : searchDocs}
+              onSelect={(item) => item.href && navigate(item.href)}
+            />
             {/* Ask AI talks to the deployed site's AI backend — hidden in
                 the local dev preview where there's nothing to talk to. */}
             {!IS_DEV_PREVIEW && (
@@ -1276,6 +1311,11 @@ function DocsPage() {
               )}
             </Stack>
           )}
+          {/* Hairline separating the top anchor links from the nav sections
+              (faithful to the sidebar design's anchor↔sidebar divider). */}
+          {anchors.length > 0 && (
+            <div className="velu-docs-context-divider" aria-hidden="true" />
+          )}
           {/* Only this region scrolls — the context zone above stays
               pinned. The up/down arrows overlay its top/bottom edges and
               appear (via the data-fade-* attrs the scroll handler sets)
@@ -1437,7 +1477,7 @@ function DocsPage() {
             })}
           </span>
         </button>
-        <div className="velu-docs-layout__article">
+        <div className="velu-docs-layout__article" data-pagefind-body="">
           {/* 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
@@ -1581,6 +1621,8 @@ function DocsPage() {
         open={chatOpen}
         seedQuestion={chatQuestion}
         onClose={() => setChatOpen(false)}
+        ask={assistant?.ask}
+        onFeedback={assistant?.sendFeedback}
       />
     </div>
   );