# AGENTS.md

Guidance for coding agents working in this Vista repository. Runtime AI agents that ship inside apps live under `app/agents/` — see that convention below.

## How humans use this framework (point them here)

1. **React app** — pages/layouts under `app/`, `'use client'` for interactivity. See root [README](README.md#1-build-a-normal-react-app) and docs `/docs/getting-started/react-app`.
2. **Fullstack** — `app/**/route.ts`, `vista g api-init`, `vista g auth`, `middleware.ts`. Docs `/docs/getting-started/fullstack-app`.
3. **AI** — `vista g agent <name>`, `vista/ai` + `vista/ai/react`. Docs `/docs/ai/overview`.
4. **RAG** — `InMemoryVectorStore` + `createRetrieverTool` + optional `embedText`. Docs `/docs/ai/rag`. Demo: `apps/vista-rag-demo`.
5. **SEO** — `metadata` / `generateMetadata`, `vista g seo`, `vista/og` ImageResponse, `JsonLd`. Docs `/docs/seo/metadata`.

## Repo map

- `packages/vista` — framework, CLI (`vista`), RSC/SSR runtime, `vista/auth`, `vista/ai`, `vista/stack`
- `packages/create-vista-app` — app scaffold
- `apps/web` — docs site at vista.xyz
- `apps/vista-rag-demo` — runnable RAG chat demo
- `crates/` and `flashpack/` — Rust engines
- Build output is `.vista/` (Next's `.next` equivalent). Do not commit app `.vista/` folders.

## Commands

```bash
pnpm install
npm --prefix packages/vista run build
pnpm test:integrity
```

Narrow tests live as `pnpm test:<name>` in the root `package.json`. After changing `packages/vista/src`, rebuild `packages/vista/dist` (that folder is committed).

## Conventions

- App runtime agents: `vista g agent <name>` → `app/agents/<name>/agent.ts` + `app/api/agents/<name>/route.ts` + `app/AGENTS.md`
- Auth: `vista g auth` → `auth.ts`, catch-all route, `/signin`, `/account`, fail-closed `middleware.ts`, `SessionProvider` wrapper. Import from `vista/auth` (server) and `vista/auth/react` (client).
- SEO: `vista g seo` → `app/robots.ts`, `sitemap.ts`, `manifest.ts`. Metadata from `vista` / `vista/metadata`; OG images via `vista/og`.
- Typed API: `vista g api-init`. Call procedures from RSC with `v.createCaller(router, { ctx, env })`.
- Package imports in generated apps use `vista/...`. Inside this monorepo, published name is `@vistagenic/vista`.

## Models and embeddings

Model strings are `provider:model`:

- `openai:gpt-4o`, `anthropic:claude-3-5-sonnet`, `gemini:gemini-1.5-flash`, `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

```ts
import { embedText, createRetrieverTool } from 'vista/ai';
```

Do not commit API keys or `.env` files.

## Git

Keep commit messages free of editor-injected trailers. Dist files under `packages/vista/dist` must match `src`.