@vistagenic/vista 0.3.6 → 0.3.9

package/dist/server/rsc-engine.js

@@ -616,13 +616,29 @@ async function createRouteElement(route, context, isDev, rootLayout, runtimeRoot
         clearProjectRequireCache(runtimeRoot);
     }
     const PageModule = require(route.pagePath);
-    let metadata = { ...(rootLayout.metadata || {}) };
+    const { deepMergeMetadata, mergeMetadataChain } = require('../metadata/merge');
+    const layoutMetadata = [];
+    for (const layoutPath of route.layoutPaths || []) {
+        try {
+            const layoutModule = require(layoutPath);
+            if (layoutModule?.metadata && typeof layoutModule.metadata === 'object') {
+                layoutMetadata.push(layoutModule.metadata);
+            }
+        }
+        catch {
+            // Ignore layout metadata load failures
+        }
+    }
+    if (layoutMetadata.length === 0 && rootLayout.metadata) {
+        layoutMetadata.push(rootLayout.metadata);
+    }
+    let metadata = mergeMetadataChain(layoutMetadata);
     if (PageModule.metadata) {
-        metadata = { ...metadata, ...PageModule.metadata };
+        metadata = deepMergeMetadata(metadata, PageModule.metadata);
     }
     if (typeof PageModule.generateMetadata === 'function') {
         const dynamicMeta = await PageModule.generateMetadata({ params, searchParams }, metadata);
-        metadata = { ...metadata, ...dynamicMeta };
+        metadata = deepMergeMetadata(metadata, dynamicMeta);
     }
     const element = await renderAppSubtreeElement({
         subtreeRootDir: (0, app_dir_1.resolveAppDir)(runtimeRoot),
@@ -877,6 +893,18 @@ function wrapInDocumentShell(bodyContent, metadataHtml, chunkFiles, rootMode) {
 </body>
 </html>`;
 }
+function logWebpackBuildErrors(errors) {
+    const count = errors.length;
+    console.error('');
+    (0, logger_1.logError)(`Build failed with ${count} error${count === 1 ? '' : 's'}`);
+    for (const message of errors) {
+        const text = message.replace(/\u001b\[[0-9;]*m/g, '').trim();
+        if (!text)
+            continue;
+        console.error(text);
+        console.error('');
+    }
+}
 function normalizeWebpackErrors(stats) {
     const errors = stats.toJson().errors || [];
     const normalizedErrors = errors
@@ -1137,8 +1165,26 @@ function startRSCServer(options = {}) {
     // - Pushes compile errors/success from webpack client build
     // ========================================================================
     const sseReloadClients = new Set();
+    // Cold start only: block until the first successful client compile.
+    // After that, rebuilds must not flash a full-page "compiling" interstitial
+    // (Next does not either — HMR/reload waits for the rebuild to finish).
     let clientCompileState = isDev && options.compiler ? 'compiling' : 'ready';
     let clientCompileErrors = [];
+    let clientBundleReadyOnce = !(isDev && options.compiler);
+    let clientRebuildInFlight = false;
+    let pendingLiveReload = false;
+    const pushSSE = (payload) => {
+        sseReloadClients.forEach((c) => c.write(`data: ${payload}\n\n`));
+    };
+    const flushPendingLiveReload = () => {
+        if (!pendingLiveReload)
+            return;
+        pendingLiveReload = false;
+        (0, logger_1.logEvent)('Source changed, reloading...');
+        pushSSE('reload');
+    };
+    /** True only while we still have no usable client/SSR bundle to serve. */
+    const shouldBlockForClientCompile = () => Boolean(isDev && options.compiler && !clientBundleReadyOnce && clientCompileState === 'compiling');
     if (isDev) {
         app.get(constants_1.SSE_ENDPOINT, (req, res) => {
             res.setHeader('Content-Type', 'text/event-stream');
@@ -1151,9 +1197,6 @@ function startRSCServer(options = {}) {
                 sseReloadClients.delete(res);
             });
         });
-        const pushSSE = (payload) => {
-            sseReloadClients.forEach((c) => c.write(`data: ${payload}\n\n`));
-        };
         const watchExtPattern = /\.(?:[cm]?[jt]sx?|css|md|mdx|json)$/i;
         const watchRoots = [
             'app',
@@ -1171,6 +1214,12 @@ function startRSCServer(options = {}) {
             .filter((entry) => fs_1.default.existsSync(entry));
         let reloadTimer = null;
         const scheduleReload = () => {
+            // If webpack is mid-rebuild, wait for `done` so the browser does not
+            // reload into a compiling gate (the intermittent Next-unlike flash).
+            if (options.compiler && (clientRebuildInFlight || !clientBundleReadyOnce)) {
+                pendingLiveReload = true;
+                return;
+            }
             if (reloadTimer)
                 clearTimeout(reloadTimer);
             reloadTimer = setTimeout(() => {
@@ -1229,28 +1278,36 @@ function startRSCServer(options = {}) {
         }));
         // No webpack-hot-middleware — Vista uses SSE live-reload for RSC
         options.compiler.hooks.invalid.tap('VistaRSCCompileStateInvalid', () => {
-            clientCompileState = 'compiling';
+            clientRebuildInFlight = true;
             clientCompileErrors = [];
+            // Only gate requests on the cold first compile — not every HMR rebuild.
+            if (!clientBundleReadyOnce) {
+                clientCompileState = 'compiling';
+            }
         });
         // Push compile errors/success to SSE clients
         options.compiler.hooks.done.tap('VistaRSCLiveReload', (stats) => {
+            clientRebuildInFlight = false;
             if (stats.hasErrors()) {
                 const normalizedErrors = normalizeWebpackErrors(stats);
                 const fallback = normalizedErrors.join('\n\n');
                 clientCompileState = 'error';
                 clientCompileErrors = normalizedErrors;
+                logWebpackBuildErrors(normalizedErrors);
                 const payload = JSON.stringify({
                     type: 'error',
                     message: fallback,
                     errors: normalizedErrors,
                 });
-                sseReloadClients.forEach((c) => c.write(`data: ${payload}\n\n`));
+                pushSSE(payload);
             }
             else {
                 clientCompileState = 'ready';
                 clientCompileErrors = [];
+                clientBundleReadyOnce = true;
                 const payload = JSON.stringify({ type: 'ok' });
-                sseReloadClients.forEach((c) => c.write(`data: ${payload}\n\n`));
+                pushSSE(payload);
+                flushPendingLiveReload();
             }
         });
         options.compiler.hooks.afterEmit.tap('VistaRSCServerManifestReload', () => {
@@ -1341,13 +1398,17 @@ function startRSCServer(options = {}) {
     const imageHandler = (0, image_optimizer_1.createImageHandler)(runtimeRoot, isDev);
     app.get(constants_1.IMAGE_ENDPOINT, imageHandler);
     app.use(express_1.default.static(path_1.default.join(runtimeRoot, 'public')));
+    // Also serve the project public/ (dev + apps whose runtimeRoot is a standalone copy).
+    if (path_1.default.resolve(runtimeRoot) !== path_1.default.resolve(cwd)) {
+        app.use(express_1.default.static(path_1.default.join(cwd, 'public')));
+    }
     app.use(`${constants_1.URL_PREFIX}/static`, express_1.default.static(path_1.default.join(cwd, constants_1.BUILD_DIR, 'static')));
     app.use(constants_1.URL_PREFIX, express_1.default.static(path_1.default.join(cwd, constants_1.BUILD_DIR)));
     app.use(express_1.default.static(path_1.default.join(cwd, constants_1.BUILD_DIR)));
     const getUpstreamUnavailableMessage = () => `RSC upstream unavailable (${upstreamOrigin}/rsc): ${upstreamUnavailableReason || 'upstream process is not running'}`;
     const proxyRSCRequest = async (req, res) => {
         if (isDev && options.compiler) {
-            if (clientCompileState === 'compiling') {
+            if (shouldBlockForClientCompile()) {
                 res.status(503).type('text/plain').send('[vista] Client bundle is compiling. Retry shortly.');
                 return;
             }
@@ -1457,7 +1518,7 @@ function startRSCServer(options = {}) {
                 return;
             }
             if (isDev && options.compiler) {
-                if (clientCompileState === 'compiling') {
+                if (shouldBlockForClientCompile()) {
                     res.status(503).type('text/html').send(renderCompilePendingHTML());
                     return;
                 }
@@ -1556,8 +1617,8 @@ function startRSCServer(options = {}) {
                 }
             }
             if (!useFlightSSR || !flightSSRClient || !isSSRManifestReady(ssrManifest)) {
-                if (isDev && options.compiler) {
-                    // Wait for a non-empty SSR manifest after the first webpack emit.
+                if (isDev && options.compiler && !clientBundleReadyOnce) {
+                    // Cold start only — wait for the first webpack emit / SSR manifest.
                     res.status(503).type('text/html').send(renderCompilePendingHTML());
                     return;
                 }
@@ -1589,15 +1650,31 @@ function startRSCServer(options = {}) {
                             clearProjectRequireCache(runtimeRoot);
                         }
                         const PageModule = require(route.pagePath);
-                        let metadata = { ...(rootLayout.metadata || {}) };
+                        const { deepMergeMetadata, mergeMetadataChain } = require('../metadata/merge');
+                        const layoutMetadata = [];
+                        for (const layoutPath of route.layoutPaths || []) {
+                            try {
+                                const layoutModule = require(layoutPath);
+                                if (layoutModule?.metadata && typeof layoutModule.metadata === 'object') {
+                                    layoutMetadata.push(layoutModule.metadata);
+                                }
+                            }
+                            catch {
+                                // Ignore layout metadata load failures
+                            }
+                        }
+                        if (layoutMetadata.length === 0 && rootLayout.metadata) {
+                            layoutMetadata.push(rootLayout.metadata);
+                        }
+                        let metadata = mergeMetadataChain(layoutMetadata);
                         if (PageModule.metadata) {
-                            metadata = { ...metadata, ...PageModule.metadata };
+                            metadata = deepMergeMetadata(metadata, PageModule.metadata);
                         }
                         if (typeof PageModule.generateMetadata === 'function') {
                             const params = extractParams(req.path, route);
                             const searchParams = Object.fromEntries(new URLSearchParams(req.query).entries());
                             const dynamicMeta = await PageModule.generateMetadata({ params, searchParams }, metadata);
-                            metadata = { ...metadata, ...dynamicMeta };
+                            metadata = deepMergeMetadata(metadata, dynamicMeta);
                         }
                         const { generateMetadataHtml } = require('../metadata/generate');
                         metadataHtml = metadata ? generateMetadataHtml(metadata) : '';

package/dist/server/static-generator.js

@@ -322,11 +322,12 @@ async function prerenderPage(urlPath, route, params, cwd, vistaDirRoot, appPprEn
             }
             let metadata = {};
             const searchParams = {};
+            const { deepMergeMetadata } = require('../metadata/merge');
             for (const layoutPath of route.layoutPaths) {
                 try {
                     const layoutModule = require(layoutPath);
                     if (layoutModule?.metadata && typeof layoutModule.metadata === 'object') {
-                        metadata = { ...metadata, ...layoutModule.metadata };
+                        metadata = deepMergeMetadata(metadata, layoutModule.metadata);
                     }
                 }
                 catch {
@@ -334,13 +335,13 @@ async function prerenderPage(urlPath, route, params, cwd, vistaDirRoot, appPprEn
                 }
             }
             if (pageModule.metadata && typeof pageModule.metadata === 'object') {
-                metadata = { ...metadata, ...pageModule.metadata };
+                metadata = deepMergeMetadata(metadata, pageModule.metadata);
             }
             if (typeof pageModule.generateMetadata === 'function') {
                 try {
                     const dynamicMeta = await pageModule.generateMetadata({ params: params || {}, searchParams }, metadata);
                     if (dynamicMeta && typeof dynamicMeta === 'object') {
-                        metadata = { ...metadata, ...dynamicMeta };
+                        metadata = deepMergeMetadata(metadata, dynamicMeta);
                     }
                 }
                 catch (metadataError) {

package/dist/server/typed-api-runtime.js

@@ -33,7 +33,9 @@ const METADATA_ROUTE_MAPPINGS = [
     { requestPath: '/sitemap.xml', stem: 'sitemap' },
     { requestPath: '/manifest.webmanifest', stem: 'manifest' },
 ];
+const IMAGE_ROUTE_STEMS = new Set(['opengraph-image', 'twitter-image']);
 const ROUTE_FILE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+const STATIC_IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp'];
 class BodyLimitError extends Error {
     status = 413;
     constructor(limitBytes) {
@@ -136,6 +138,42 @@ function resolveMetadataRoutePath(cwd, stem) {
     };
     return searchGroupDirectories(appDir);
 }
+/**
+ * Resolve `opengraph-image` / `twitter-image` conventions (Next parity).
+ * `/docs/opengraph-image` → `app/docs/opengraph-image.tsx` (or static `.png`).
+ */
+function resolveImageMetadataRoutePath(cwd, requestPath) {
+    const pathname = String(requestPath || '').split('?')[0];
+    const match = pathname.match(/^(.*)\/(opengraph-image|twitter-image)(?:\.[a-z0-9]+)?$/i);
+    if (!match)
+        return null;
+    const prefix = (match[1] || '').replace(/\/+$/, '');
+    const stem = match[2].toLowerCase();
+    if (!IMAGE_ROUTE_STEMS.has(stem))
+        return null;
+    const appDir = (0, app_dir_1.resolveAppDir)(cwd);
+    const dir = prefix ? path_1.default.join(appDir, prefix.replace(/^\//, '')) : appDir;
+    for (const extension of ROUTE_FILE_EXTENSIONS) {
+        const candidate = path_1.default.join(dir, `${stem}${extension}`);
+        if (fs_1.default.existsSync(candidate))
+            return candidate;
+    }
+    for (const extension of STATIC_IMAGE_EXTENSIONS) {
+        const candidate = path_1.default.join(dir, `${stem}${extension}`);
+        if (fs_1.default.existsSync(candidate))
+            return candidate;
+    }
+    // Also allow route-group nesting: app/(marketing)/opengraph-image.tsx for /
+    if (!prefix) {
+        return resolveMetadataRoutePath(cwd, stem);
+    }
+    return null;
+}
+function getMetadataStemForRequest(requestPath) {
+    const pathname = String(requestPath || '').split('?')[0];
+    const mapping = METADATA_ROUTE_MAPPINGS.find((entry) => entry.requestPath === pathname);
+    return mapping?.stem ?? null;
+}
 function hasMethodMatch(router, pathname, method) {
     const normalized = method.toLowerCase();
     return router.resolve(pathname, normalized) !== null;
@@ -456,6 +494,10 @@ function resolveLegacyRouteHandlerPath(cwd, requestPath) {
             routeCandidates.push(resolvedMetadataPath);
         }
     }
+    const imageRoutePath = resolveImageMetadataRoutePath(cwd, requestPath);
+    if (imageRoutePath) {
+        routeCandidates.push(imageRoutePath);
+    }
     if (normalized.startsWith('api/')) {
         const apiRoute = normalized.slice('api/'.length);
         routeCandidates.push(path_1.default.join(appDir, 'api', apiRoute, 'route.ts'), path_1.default.join(appDir, 'api', apiRoute, 'route.tsx'), path_1.default.join(appDir, 'api', apiRoute, 'route.js'), path_1.default.join(appDir, 'api', apiRoute, 'route.jsx'), path_1.default.join(appDir, 'api', `${apiRoute}.ts`), path_1.default.join(appDir, 'api', `${apiRoute}.tsx`), path_1.default.join(appDir, 'api', `${apiRoute}.js`), path_1.default.join(appDir, 'api', `${apiRoute}.jsx`));
@@ -475,6 +517,23 @@ function getExportedRouteMethods(apiModule) {
 async function runLegacyApiRoute(options) {
     const { req, res, apiPath, isDev } = options;
     const params = options.params || {};
+    const requestPath = String(req.path || req.url || '').split('?')[0];
+    const fileExt = path_1.default.extname(apiPath).toLowerCase();
+    // Static opengraph-image.png / twitter-image.jpg convention files.
+    if (STATIC_IMAGE_EXTENSIONS.includes(fileExt)) {
+        const contentTypes = {
+            '.png': 'image/png',
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.gif': 'image/gif',
+            '.webp': 'image/webp',
+        };
+        res.status(200);
+        res.setHeader('Content-Type', contentTypes[fileExt] || 'application/octet-stream');
+        res.setHeader('Cache-Control', 'public, max-age=0, s-maxage=3600');
+        fs_1.default.createReadStream(apiPath).pipe(res);
+        return;
+    }
     if (isDev) {
         delete require.cache[require.resolve(apiPath)];
     }
@@ -506,6 +565,16 @@ async function runLegacyApiRoute(options) {
                 await sendFetchResponse(res, result);
                 return;
             }
+            const metadataStem = getMetadataStemForRequest(requestPath);
+            if (metadataStem && result !== undefined) {
+                const { metadataRouteToResponse } = require('../metadata/routes');
+                const converted = metadataRouteToResponse(metadataStem, result);
+                if (converted) {
+                    res.req = res.req || req;
+                    await sendFetchResponse(res, converted);
+                    return;
+                }
+            }
             if (result !== undefined) {
                 res.status(200).json(result);
                 return;
@@ -521,6 +590,29 @@ async function runLegacyApiRoute(options) {
             throw error;
         }
     }
+    // MetadataRoute + OG image conventions: default export returning data or Response.
+    const metadataStem = getMetadataStemForRequest(requestPath);
+    const isImageMetadataRoute = /(?:^|\/)(opengraph-image|twitter-image)(?:\.[a-z0-9]+)?$/i.test(requestPath);
+    if ((metadataStem || isImageMetadataRoute) &&
+        typeof apiModule.default === 'function' &&
+        (method === 'GET' || method === 'HEAD')) {
+        try {
+            const result = await apiModule.default({ params });
+            let response = result instanceof Response ? result : null;
+            if (!response && metadataStem) {
+                const { metadataRouteToResponse } = require('../metadata/routes');
+                response = metadataRouteToResponse(metadataStem, result);
+            }
+            if (response) {
+                res.req = res.req || req;
+                await sendFetchResponse(res, response);
+                return;
+            }
+        }
+        catch (error) {
+            throw error;
+        }
+    }
     if (isEdgeRuntime(runtime) && typeof apiModule.default === 'function') {
         res.status(500).json({
             error: 'Edge runtime route handlers must export HTTP method functions instead of a default Express handler.',

package/docs/ai.md

@@ -0,0 +1,69 @@
+# AI
+
+Import app code from `vista/ai` and React hooks from `vista/ai/react`. Do not add a third-party agent SDK for these primitives.
+
+## Model strings
+
+`provider:model`:
+
+- `openai:gpt-4o` (`OPENAI_API_KEY`)
+- `anthropic:claude-3-5-sonnet` (`ANTHROPIC_API_KEY`)
+- `gemini:gemini-1.5-flash` (`GEMINI_API_KEY`)
+- `ollama:llama3`
+- `groq:llama-3.1-8b-instant` (`GROQ_API_KEY`)
+- `nvidia:meta/llama-3.1-8b-instruct` (`NVIDIA_API_KEY` or `NIM_API_KEY`)
+- `mock:echo` for tests with no key
+
+Do not commit API keys or `.env` files.
+
+## Agent
+
+`vista g agent support` writes the files. The generated module looks like this:
+
+```ts
+import { agent, tool } from 'vista/ai';
+
+export const supportAgent = agent({
+  name: 'support',
+  model: process.env.VISTA_AI_MODEL || 'openai:gpt-4o',
+  systemPrompt: 'You are a helpful AI assistant for support.',
+  tools: [
+    tool({
+      name: 'ping',
+      description: 'Check agent connectivity',
+      execute: async () => ({ status: 'ok', time: new Date().toISOString() }),
+    }),
+  ],
+  memory: true,
+});
+```
+
+Route:
+
+```ts
+import { supportAgent } from '../../../agents/support/agent';
+
+export async function POST(req: Request) {
+  const { prompt, messages, sessionId } = await req.json();
+  const stream = supportAgent.stream({ prompt, messages, sessionId });
+  return stream.toDataStreamResponse();
+}
+```
+
+Client:
+
+```tsx
+'use client';
+import { useAgent } from 'vista/ai/react';
+
+export default function ChatPage() {
+  const { messages, input, setInput, handleSubmit, isLoading } = useAgent({
+    api: '/api/agents/support',
+  });
+  // render messages and a form that calls handleSubmit
+}
+```
+
+`agent()` options used by the framework: `name`, `model`, `systemPrompt`, `tools`, `memory`, `maxSteps` (default 5), `temperature`, `observability`. Turn another agent into a tool with `.asTool({ description })`.
+
+`tool()` takes `name`, `description`, optional JSON-schema `parameters`, and `execute`.

package/docs/app.md

@@ -0,0 +1,30 @@
+# App conventions
+
+Vista apps are React. Server Components are the default under `app/`. Add `'use client'` only on modules that use state, effects, or browser events.
+
+## Routes
+
+- `app/index.tsx` is the home page (`/`). There is no `app/page.tsx` convention.
+- `app/root.tsx` is the root layout. There is no `app/layout.tsx` convention.
+- A route segment is `app/<segment>/page.tsx` (for example `app/about/page.tsx` → `/about`).
+- Dynamic segments use brackets: `app/docs/[...slug]/page.tsx`.
+- HTTP handlers are `app/**/route.ts` exporting `GET`, `POST`, and the other methods.
+- Shared UI is not scaffolded. Import theme pieces from `vista/theme` (`ThemeProvider`, `ThemeScript`, `ThemeToggle`). Add `components/` only when UI is reused.
+
+## Client boundaries
+
+`'use client'` may live in `app/`, `components/`, `utils/`, `lib/`, or `src/`. The client manifest scans those roots.
+
+## Config and output
+
+- `vista.config.ts` selects the engine with `engine.variant`: `'default'` or `'flashpack'`.
+- `package.json` `vista.engine` is the same switch. Scripts stay `vista dev`, `vista build`, `vista start`.
+- Production output is `.vista/` (the `.next` equivalent). Do not commit it.
+- Flashpack dev output is `.flash/`. It is a compiler cache, not a second copy of `.vista/`.
+- Dev server port is `3003`.
+
+## SEO files already in a new app
+
+- `app/robots.ts`, `app/sitemap.ts`, `app/opengraph-image.tsx`
+- Metadata helpers come from `vista` / `vista/metadata`. OG images use `vista/og`.
+- `vista g seo` adds `app/manifest.ts` when it is missing.

package/docs/cli.md

@@ -0,0 +1,29 @@
+# CLI
+
+## Create an app
+
+```bash
+npx create-vista-app@latest my-app
+npx create-vista-app@latest my-app --engine flashpack
+npx create-vista-app@latest my-app --no-agents-md
+```
+
+The scaffold writes `AGENTS.md` and `CLAUDE.md` unless `--no-agents-md` is set. `CLAUDE.md` is `@AGENTS.md`.
+
+## Generators
+
+```bash
+vista g api-init
+vista g router <name>
+vista g procedure <name> [get|post]
+vista g agent <name>
+vista g auth
+vista g seo
+```
+
+- `vista g agent <name>` writes `app/agents/<name>/agent.ts`, `app/api/agents/<name>/route.ts`, and `app/AGENTS.md` if that file is missing.
+- `vista g auth` writes `auth.ts`, `app/api/auth/[...vista]/route.ts`, `/signin`, `/account`, fail-closed `middleware.ts`, a `SessionProvider` wrapper, and `.env.example`. Set `AUTH_SECRET` before signing in. Import the server helper from `vista/auth` and the client helper from `vista/auth/react`.
+- `vista g api-init` starts the typed API. Call procedures from a Server Component with `v.createCaller(router, { ctx, env })`.
+- `vista g seo` writes `app/robots.ts`, `app/sitemap.ts`, and `app/manifest.ts`.
+
+`vista deploy` writes platform files. The scaffold does not copy Docker, Render, Netlify, Vercel, or Cloudflare configs.

package/docs/index.md

@@ -0,0 +1,18 @@
+# Vista docs for agents
+
+These files ship with the installed `vista` package and match that version. Read the guide that fits the task before writing code. Do not invent Next.js App Router APIs, `app/page.tsx` as the home route, or `app/layout.tsx`.
+
+| Guide | Use it for |
+| --- | --- |
+| [app.md](app.md) | Routes, layouts, client components, `vista.config.ts`, build output |
+| [cli.md](cli.md) | `create-vista-app` and `vista g` generators |
+| [ai.md](ai.md) | Agents, tools, streaming, model strings |
+| [rag.md](rag.md) | `InMemoryVectorStore`, `createRetrieverTool`, `embedText` |
+
+Workflow skills (read the matching `SKILL.md` before a multi-step task):
+
+- `../skills/vista-dev-loop/SKILL.md`
+- `../skills/vista-agent/SKILL.md`
+- `../skills/vista-rag/SKILL.md`
+
+Imports in an app are `vista/...`. The published package name is `@vistagenic/vista`.

package/docs/rag.md

@@ -0,0 +1,54 @@
+# RAG
+
+Index documents, retrieve matches, and pass them to an agent as a tool. Imports:
+
+```ts
+import { agent, InMemoryVectorStore, createRetrieverTool, embedText } from 'vista/ai';
+```
+
+## Keyword search
+
+Omit `embed`. The retriever uses keyword search and needs no API key. `mock:echo` is enough for a smoke test.
+
+```ts
+const store = new InMemoryVectorStore();
+store.addDocuments([
+  { id: 'rsc', text: 'Vista uses React Server Components by default under app/.' },
+]);
+
+const search = createRetrieverTool({
+  name: 'search_knowledge_base',
+  description: 'Search the product knowledge base',
+  store,
+  topK: 3,
+});
+
+export const ragAgent = agent({
+  name: 'rag',
+  model: 'mock:echo',
+  systemPrompt: 'Answer using search_knowledge_base results only.',
+  tools: [search],
+  memory: true,
+});
+```
+
+## Embeddings
+
+`embedText` calls an OpenAI-compatible `/embeddings` endpoint. Set the provider key. Pass the same embedder to the store and the tool.
+
+```ts
+const text = 'Vista builds into .vista/, similar to Next.js .next/.';
+store.addDocument({
+  id: 'build',
+  text,
+  vector: await embedText(text, { model: 'openai:text-embedding-3-small' }),
+});
+
+const search = createRetrieverTool({
+  store,
+  embed: (query) => embedText(query, { model: 'openai:text-embedding-3-small' }),
+  topK: 3,
+});
+```
+
+Stream the agent from `app/api/agents/<name>/route.ts` and render it with `useAgent` from `vista/ai/react`. A runnable demo lives in the Vista repo at `apps/vista-rag-demo`.