From fae82646d8f81833f3f12388bfbebfbb95d08fb3 Mon Sep 17 00:00:00 2001
From: edow <285729101@qq.com>
Date: Wed, 18 Feb 2026 12:53:47 +0800
Subject: [PATCH] add .cursor/rules/echo_rules.mdc to all echo-start templates
---
.../assistant-ui/.cursor/rules/echo_rules.mdc | 89 ++++++++
templates/authjs/.cursor/rules/echo_rules.mdc | 92 ++++++++
.../echo-cli/.cursor/rules/echo_rules.mdc | 152 +++++++++++++
.../next-chat/.cursor/rules/echo_rules.mdc | 148 ++++++++++++
.../next-image/.cursor/rules/echo_rules.mdc | 99 +++++++++
.../.cursor/rules/echo_rules.mdc | 99 +++++++++
templates/next/.cursor/rules/echo_rules.mdc | 210 ++++++++++++++++++
.../.cursor/rules/echo_rules.mdc | 109 +++++++++
.../react-chat/.cursor/rules/echo_rules.mdc | 100 +++++++++
.../react-image/.cursor/rules/echo_rules.mdc | 67 ++++++
templates/react/.cursor/rules/echo_rules.mdc | 116 ++++++++++
11 files changed, 1281 insertions(+)
create mode 100644 templates/assistant-ui/.cursor/rules/echo_rules.mdc
create mode 100644 templates/authjs/.cursor/rules/echo_rules.mdc
create mode 100644 templates/echo-cli/.cursor/rules/echo_rules.mdc
create mode 100644 templates/next-chat/.cursor/rules/echo_rules.mdc
create mode 100644 templates/next-image/.cursor/rules/echo_rules.mdc
create mode 100644 templates/next-video-template/.cursor/rules/echo_rules.mdc
create mode 100644 templates/next/.cursor/rules/echo_rules.mdc
create mode 100644 templates/nextjs-api-key-template/.cursor/rules/echo_rules.mdc
create mode 100644 templates/react-chat/.cursor/rules/echo_rules.mdc
create mode 100644 templates/react-image/.cursor/rules/echo_rules.mdc
create mode 100644 templates/react/.cursor/rules/echo_rules.mdc
diff --git a/templates/assistant-ui/.cursor/rules/echo_rules.mdc b/templates/assistant-ui/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..2bcf45988
--- /dev/null
+++ b/templates/assistant-ui/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,89 @@
+---
+description: Guidelines and best practices for building Echo applications with Assistant UI, including @assistant-ui/react integration, server/client boundaries, and AI SDK usage
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo Assistant UI Guidelines
+
+## SDK Initialization
+
+### Server-Side Initialization
+
+ALWAYS initialize the Echo SDK in `src/echo/index.ts`:
+
+```typescript
+import Echo from '@merit-systems/echo-next-sdk';
+
+export const { handlers, isSignedIn, openai, anthropic } = Echo({
+ appId: process.env.ECHO_APP_ID!,
+});
+```
+
+### Client-Side Provider
+
+ALWAYS wrap your application with `EchoProvider`:
+
+```typescript
+'use client';
+
+import { EchoProvider } from '@merit-systems/echo-next-sdk/client';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+```
+
+## Environment Variables
+
+ALWAYS store your Echo App ID in `.env.local`:
+
+```bash
+ECHO_APP_ID=your_echo_app_id
+NEXT_PUBLIC_ECHO_APP_ID=your_echo_app_id
+```
+
+NEVER hardcode API keys or app IDs directly in your code.
+
+## Assistant UI Integration
+
+This template uses `@assistant-ui/react` for the chat interface. Key patterns:
+
+- Use `@assistant-ui/react-ai-sdk` to bridge Assistant UI with the Vercel AI SDK
+- Customize thread and message components through `@assistant-ui/react`
+- Style with Tailwind CSS and Radix UI primitives
+
+## Server/Client Boundaries
+
+Use server components for Echo AI calls. Use client components ONLY for UI interactions.
+
+```typescript
+// ✅ CORRECT
+'use client';
+import { EchoTokens } from '@merit-systems/echo-next-sdk/client';
+
+// ❌ INCORRECT - Never import server SDK in client components
+'use client';
+import Echo from '@merit-systems/echo-next-sdk';
+```
+
+## Echo Authentication Handler
+
+ALWAYS register Echo auth handlers at `app/api/echo/[...echo]/route.ts`:
+
+```typescript
+import { handlers } from '@/echo';
+export const { GET, POST } = handlers;
+```
+
+## Best Practices
+
+1. **Separation**: Keep server logic in API routes and `src/echo/`, client logic in components
+2. **Environment Variables**: Use server variables for secrets, `NEXT_PUBLIC_` for client-side config
+3. **Validation**: Always validate inputs in API routes before processing
+4. **Error Handling**: Provide clear error messages and appropriate HTTP status codes
+5. **Type Safety**: Use TypeScript strictly, avoid `any`
+6. **Security**: Never expose server secrets to the client
diff --git a/templates/authjs/.cursor/rules/echo_rules.mdc b/templates/authjs/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..2d6454917
--- /dev/null
+++ b/templates/authjs/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,92 @@
+---
+description: Guidelines and best practices for building Echo Next.js applications with Auth.js (NextAuth) authentication, including session management and protected routes
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo Auth.js (NextAuth) Guidelines
+
+## SDK Initialization
+
+### Server-Side Initialization
+
+ALWAYS initialize the Echo SDK in `src/echo/index.ts`:
+
+```typescript
+import Echo from '@merit-systems/echo-next-sdk';
+
+export const { handlers, isSignedIn, openai, anthropic } = Echo({
+ appId: process.env.ECHO_APP_ID!,
+});
+```
+
+### Client-Side Provider
+
+ALWAYS wrap your application with `EchoProvider`:
+
+```typescript
+'use client';
+
+import { EchoProvider } from '@merit-systems/echo-next-sdk/client';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+```
+
+## Auth.js Integration
+
+This template uses `@merit-systems/echo-authjs-provider` to integrate Echo as a NextAuth provider.
+
+- Configure Auth.js with the Echo provider in your auth configuration
+- Use `next-auth` session management for protected routes
+- Access the Echo session through the NextAuth session object
+
+## Environment Variables
+
+ALWAYS store secrets in `.env.local`:
+
+```bash
+ECHO_APP_ID=your_echo_app_id
+NEXT_PUBLIC_ECHO_APP_ID=your_echo_app_id
+NEXTAUTH_SECRET=your_nextauth_secret
+NEXTAUTH_URL=http://localhost:3000
+```
+
+NEVER hardcode secrets directly in your code.
+
+## Server/Client Boundaries
+
+Use server components for Echo AI calls and auth checks. Use client components ONLY for UI interactions.
+
+```typescript
+// ✅ CORRECT
+'use client';
+import { EchoTokens } from '@merit-systems/echo-next-sdk/client';
+
+// ❌ INCORRECT - Never import server SDK in client components
+'use client';
+import Echo from '@merit-systems/echo-next-sdk';
+```
+
+## Echo Authentication Handler
+
+ALWAYS register Echo auth handlers at `app/api/echo/[...echo]/route.ts`:
+
+```typescript
+import { handlers } from '@/echo';
+export const { GET, POST } = handlers;
+```
+
+## Best Practices
+
+1. **Separation**: Keep server logic in API routes and `src/echo/`, client logic in components
+2. **Environment Variables**: Use server variables for secrets, `NEXT_PUBLIC_` for client-side config
+3. **Auth**: Use middleware or server-side checks for route protection
+4. **Validation**: Always validate inputs in API routes before processing
+5. **Error Handling**: Provide clear error messages and appropriate HTTP status codes
+6. **Type Safety**: Use TypeScript strictly, avoid `any`
+7. **Security**: Never expose server secrets, auth tokens, or API keys to the client
diff --git a/templates/echo-cli/.cursor/rules/echo_rules.mdc b/templates/echo-cli/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..421c5cdb9
--- /dev/null
+++ b/templates/echo-cli/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,152 @@
+---
+description: Guidelines and best practices for building Echo CLI applications, including authentication, wallet management, chat sessions, and AI SDK integration
+globs: **/*.ts,**/*.js
+---
+
+# Echo CLI Guidelines
+
+## SDK Initialization
+
+The CLI uses `@merit-systems/echo-typescript-sdk` for server-side Echo integration and `@merit-systems/ai-x402` for AI model access.
+
+## Project Structure
+
+```
+src/
+├── index.ts # CLI entry point (Commander.js)
+├── print.ts # Output formatting utilities
+├── auth/
+│ ├── index.ts # Auth barrel exports
+│ ├── client.ts # Echo auth client
+│ ├── login.ts # Login flow
+│ ├── logout.ts # Logout flow
+│ ├── providers.ts # Auth provider options
+│ ├── wallet.ts # Wallet-based auth
+│ └── local-wallet.ts # Local wallet auth
+├── config/
+│ ├── index.ts # Config barrel exports
+│ ├── store.ts # Persistent config storage
+│ ├── models.ts # Available AI models
+│ ├── wallet.ts # Wallet configuration
+│ ├── ascii.ts # ASCII art/branding
+│ └── messages.ts # User-facing messages
+├── core/
+│ ├── index.ts # Core barrel exports
+│ ├── chat.ts # Chat session logic
+│ ├── model.ts # Model selection
+│ ├── history.ts # Conversation history
+│ ├── profile.ts # User profile
+│ └── local-wallet.ts # Local wallet operations
+└── utils/
+ ├── index.ts # Utils barrel exports
+ ├── auth.ts # Auth helpers
+ ├── stream.ts # Streaming response handling
+ ├── wallet.ts # Wallet utilities
+ ├── local-wallet.ts # Local wallet helpers
+ ├── errors.ts # Error handling
+ ├── spinner.ts # CLI spinner
+ ├── chains.ts # Blockchain chain configs
+ └── signer.ts # Transaction signing
+```
+
+## Authentication
+
+The CLI supports multiple auth methods:
+
+- **Echo OAuth**: Browser-based login through Echo
+- **Wallet Connect**: Connect an existing crypto wallet
+- **Local Wallet**: Generate and manage a local wallet
+
+ALWAYS check authentication state before making API calls:
+
+```typescript
+import { isAuthenticated } from '@/utils';
+
+if (!isAuthenticated()) {
+ warning('Please login first: echodex login');
+ return;
+}
+```
+
+## CLI Commands
+
+Define commands using Commander.js:
+
+```typescript
+import { Command } from 'commander';
+
+const program = new Command();
+
+program
+ .name('echodex')
+ .description('CLI Coding Agent Powered by Echo')
+ .version('1.0.0');
+
+program
+ .command('login')
+ .description('Authenticate with Echo or Wallet')
+ .action(async () => { /* ... */ });
+```
+
+## Interactive Prompts
+
+Use `@clack/prompts` for interactive CLI prompts:
+
+```typescript
+import { select, isCancel } from '@clack/prompts';
+
+const choice = await select({
+ message: 'Choose an option:',
+ options: [
+ { label: 'Option A', value: 'a' },
+ { label: 'Option B', value: 'b' },
+ ],
+});
+
+if (isCancel(choice)) {
+ process.exit(0);
+}
+```
+
+## Streaming Responses
+
+ALWAYS use streaming for AI chat responses to provide real-time output.
+
+## TypeScript Guidelines
+
+ALWAYS use strict typing and avoid `any`:
+
+```typescript
+// ✅ CORRECT
+interface ChatMessage {
+ role: 'user' | 'assistant' | 'system';
+ content: string;
+}
+
+// ❌ INCORRECT
+function handleMessage(msg: any): any { ... }
+```
+
+## Error Handling
+
+ALWAYS handle errors explicitly with user-friendly messages:
+
+```typescript
+import { handleError } from '@/utils/errors';
+
+try {
+ await someOperation();
+} catch (error) {
+ handleError(error, 'Failed to complete operation');
+}
+```
+
+## Best Practices
+
+1. **Authentication**: Always verify auth state before API calls
+2. **Streaming**: Use streaming for AI responses to give real-time feedback
+3. **Error Handling**: Provide clear, actionable error messages
+4. **Type Safety**: Use TypeScript strictly, define interfaces for all data structures
+5. **Config Storage**: Use the config store for persistent user settings
+6. **Modularity**: Keep auth, config, core logic, and utils separated
+7. **User Experience**: Use spinners and formatted output for long-running operations
diff --git a/templates/next-chat/.cursor/rules/echo_rules.mdc b/templates/next-chat/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..9c454882a
--- /dev/null
+++ b/templates/next-chat/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,148 @@
+---
+description: Guidelines and best practices for building Echo Next.js Chat applications, including streaming responses, server/client boundaries, and AI SDK integration
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo Next.js Chat Guidelines
+
+## SDK Initialization
+
+### Server-Side Initialization
+
+ALWAYS initialize the Echo SDK in `src/echo/index.ts` for server-side usage:
+
+```typescript
+import Echo from '@merit-systems/echo-next-sdk';
+
+export const { handlers, isSignedIn, openai, anthropic } = Echo({
+ appId: process.env.ECHO_APP_ID!,
+});
+```
+
+### Client-Side Provider
+
+ALWAYS wrap your application with `EchoProvider` in your providers file:
+
+```typescript
+'use client';
+
+import { EchoProvider } from '@merit-systems/echo-next-sdk/client';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+```
+
+## Environment Variables
+
+ALWAYS store your Echo App ID in `.env.local`:
+
+```bash
+ECHO_APP_ID=your_echo_app_id
+NEXT_PUBLIC_ECHO_APP_ID=your_echo_app_id
+```
+
+NEVER hardcode API keys or app IDs directly in your code.
+
+## Chat API Route
+
+ALWAYS implement the chat API route at `app/api/chat/route.ts` with proper validation and streaming:
+
+```typescript
+import { convertToModelMessages, streamText, type UIMessage } from 'ai';
+import { openai } from '@/echo';
+
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+ const { model, messages }: { messages: UIMessage[]; model: string } = await req.json();
+
+ if (!model) {
+ return new Response(
+ JSON.stringify({ error: 'Bad Request', message: 'Model parameter is required' }),
+ { status: 400, headers: { 'Content-Type': 'application/json' } }
+ );
+ }
+
+ if (!messages || !Array.isArray(messages)) {
+ return new Response(
+ JSON.stringify({ error: 'Bad Request', message: 'Messages must be an array' }),
+ { status: 400, headers: { 'Content-Type': 'application/json' } }
+ );
+ }
+
+ const result = streamText({
+ model: openai(model),
+ messages: convertToModelMessages(messages),
+ });
+
+ return result.toUIMessageStreamResponse({
+ sendSources: true,
+ sendReasoning: true,
+ });
+}
+```
+
+## Server/Client Boundaries
+
+### Server Components
+
+Use server components for Echo AI calls that require authentication.
+
+### Client Components
+
+Use client components ONLY for UI interactions. NEVER import the server-side Echo SDK in client components:
+
+```typescript
+// ✅ CORRECT
+'use client';
+import { EchoTokens } from '@merit-systems/echo-next-sdk/client';
+
+// ❌ INCORRECT
+'use client';
+import Echo from '@merit-systems/echo-next-sdk';
+```
+
+## Echo Authentication Handler
+
+ALWAYS register Echo auth handlers at `app/api/echo/[...echo]/route.ts`:
+
+```typescript
+import { handlers } from '@/echo';
+export const { GET, POST } = handlers;
+```
+
+## Project Structure
+
+```
+src/
+├── app/
+│ ├── api/
+│ │ ├── echo/[...echo]/route.ts # Echo auth handlers
+│ │ └── chat/route.ts # Chat streaming endpoint
+│ ├── _components/ # Page-specific components
+│ ├── layout.tsx
+│ └── page.tsx
+├── components/
+│ ├── ai-elements/ # Chat UI components
+│ └── ui/ # Shared UI components
+├── echo/
+│ └── index.ts # Server-side Echo init
+├── lib/
+│ └── utils.ts # Utility functions
+└── providers.tsx # Client providers
+```
+
+## Best Practices
+
+1. **Streaming**: Use `streamText` and `toUIMessageStreamResponse` for chat responses
+2. **Validation**: Always validate `model` and `messages` params in API routes
+3. **Separation**: Keep server logic in API routes and `src/echo/`, client logic in components
+4. **Environment Variables**: Use server variables for secrets, `NEXT_PUBLIC_` for client-side config
+5. **Error Handling**: Provide clear error messages and appropriate HTTP status codes
+6. **Type Safety**: Use TypeScript strictly, avoid `any`
+7. **Security**: Never expose server secrets to the client
diff --git a/templates/next-image/.cursor/rules/echo_rules.mdc b/templates/next-image/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..625169fdf
--- /dev/null
+++ b/templates/next-image/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,99 @@
+---
+description: Guidelines and best practices for building Echo Next.js Image Generation applications, including server/client boundaries, environment variables, and API routes
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo Next.js Image Generation Guidelines
+
+## SDK Initialization
+
+### Server-Side Initialization
+
+ALWAYS initialize the Echo SDK in `src/echo/index.ts`:
+
+```typescript
+import Echo from '@merit-systems/echo-next-sdk';
+
+export const { handlers, isSignedIn, openai, anthropic } = Echo({
+ appId: process.env.ECHO_APP_ID!,
+});
+```
+
+### Client-Side Provider
+
+ALWAYS wrap your application with `EchoProvider`:
+
+```typescript
+'use client';
+
+import { EchoProvider } from '@merit-systems/echo-next-sdk/client';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+```
+
+## Environment Variables
+
+ALWAYS store your Echo App ID in `.env.local`:
+
+```bash
+ECHO_APP_ID=your_echo_app_id
+NEXT_PUBLIC_ECHO_APP_ID=your_echo_app_id
+```
+
+NEVER hardcode API keys or app IDs directly in your code.
+
+## Server/Client Boundaries
+
+Use server components for Echo AI calls. Use client components ONLY for UI interactions.
+
+```typescript
+// ✅ CORRECT
+'use client';
+import { EchoTokens } from '@merit-systems/echo-next-sdk/client';
+
+// ❌ INCORRECT - Never import server SDK in client components
+'use client';
+import Echo from '@merit-systems/echo-next-sdk';
+```
+
+## Echo Authentication Handler
+
+ALWAYS register Echo auth handlers at `app/api/echo/[...echo]/route.ts`:
+
+```typescript
+import { handlers } from '@/echo';
+export const { GET, POST } = handlers;
+```
+
+## Project Structure
+
+```
+src/
+├── app/
+│ ├── api/
+│ │ ├── echo/[...echo]/route.ts # Echo auth handlers
+│ │ └── generate/route.ts # Image generation endpoint
+│ ├── layout.tsx
+│ └── page.tsx
+├── components/ # UI components
+├── echo/
+│ └── index.ts # Server-side Echo init
+├── lib/
+│ └── utils.ts
+└── providers.tsx
+```
+
+## Best Practices
+
+1. **Separation**: Keep server logic in API routes and `src/echo/`, client logic in components
+2. **Environment Variables**: Use server variables for secrets, `NEXT_PUBLIC_` for client-side config
+3. **Validation**: Always validate inputs in API routes before processing
+4. **Error Handling**: Provide clear error messages and appropriate HTTP status codes
+5. **Type Safety**: Use TypeScript strictly, avoid `any`
+6. **Security**: Never expose server secrets to the client
diff --git a/templates/next-video-template/.cursor/rules/echo_rules.mdc b/templates/next-video-template/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..e6ee1ede8
--- /dev/null
+++ b/templates/next-video-template/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,99 @@
+---
+description: Guidelines and best practices for building Echo Next.js Video Generation applications, including server/client boundaries, environment variables, and API routes
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo Next.js Video Generation Guidelines
+
+## SDK Initialization
+
+### Server-Side Initialization
+
+ALWAYS initialize the Echo SDK in `src/echo/index.ts`:
+
+```typescript
+import Echo from '@merit-systems/echo-next-sdk';
+
+export const { handlers, isSignedIn, openai, anthropic } = Echo({
+ appId: process.env.ECHO_APP_ID!,
+});
+```
+
+### Client-Side Provider
+
+ALWAYS wrap your application with `EchoProvider`:
+
+```typescript
+'use client';
+
+import { EchoProvider } from '@merit-systems/echo-next-sdk/client';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+```
+
+## Environment Variables
+
+ALWAYS store your Echo App ID in `.env.local`:
+
+```bash
+ECHO_APP_ID=your_echo_app_id
+NEXT_PUBLIC_ECHO_APP_ID=your_echo_app_id
+```
+
+NEVER hardcode API keys or app IDs directly in your code.
+
+## Server/Client Boundaries
+
+Use server components for Echo AI calls. Use client components ONLY for UI interactions.
+
+```typescript
+// ✅ CORRECT
+'use client';
+import { EchoTokens } from '@merit-systems/echo-next-sdk/client';
+
+// ❌ INCORRECT - Never import server SDK in client components
+'use client';
+import Echo from '@merit-systems/echo-next-sdk';
+```
+
+## Echo Authentication Handler
+
+ALWAYS register Echo auth handlers at `app/api/echo/[...echo]/route.ts`:
+
+```typescript
+import { handlers } from '@/echo';
+export const { GET, POST } = handlers;
+```
+
+## Project Structure
+
+```
+src/
+├── app/
+│ ├── api/
+│ │ ├── echo/[...echo]/route.ts # Echo auth handlers
+│ │ └── generate/route.ts # Video generation endpoint
+│ ├── layout.tsx
+│ └── page.tsx
+├── components/ # UI components
+├── echo/
+│ └── index.ts # Server-side Echo init
+├── lib/
+│ └── utils.ts
+└── providers.tsx
+```
+
+## Best Practices
+
+1. **Separation**: Keep server logic in API routes and `src/echo/`, client logic in components
+2. **Environment Variables**: Use server variables for secrets, `NEXT_PUBLIC_` for client-side config
+3. **Validation**: Always validate inputs in API routes before processing
+4. **Error Handling**: Provide clear error messages and appropriate HTTP status codes
+5. **Type Safety**: Use TypeScript strictly, avoid `any`
+6. **Security**: Never expose server secrets to the client
diff --git a/templates/next/.cursor/rules/echo_rules.mdc b/templates/next/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..955e24d20
--- /dev/null
+++ b/templates/next/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,210 @@
+---
+description: Guidelines and best practices for building Echo Next.js applications, including server/client boundaries, environment variables, API routes, and real-world examples
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo Next.js Guidelines
+
+## SDK Initialization
+
+### Server-Side Initialization
+
+ALWAYS initialize the Echo SDK in `src/echo/index.ts` for server-side usage:
+
+```typescript
+import Echo from '@merit-systems/echo-next-sdk';
+
+export const { handlers, isSignedIn, openai, anthropic } = Echo({
+ appId: process.env.ECHO_APP_ID!,
+});
+```
+
+### Client-Side Provider
+
+ALWAYS wrap your application with `EchoProvider` in your providers file:
+
+```typescript
+'use client';
+
+import { EchoProvider } from '@merit-systems/echo-next-sdk/client';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+```
+
+## Environment Variables
+
+ALWAYS store your Echo App ID in `.env.local`:
+
+```bash
+# Server-side only
+ECHO_APP_ID=your_echo_app_id
+
+# Client-side (public)
+NEXT_PUBLIC_ECHO_APP_ID=your_echo_app_id
+```
+
+NEVER hardcode API keys or app IDs directly in your code. ALWAYS read from environment variables:
+
+```typescript
+// ✅ CORRECT
+const appId = process.env.ECHO_APP_ID!;
+
+// ❌ INCORRECT
+const appId = 'echo_app_123abc';
+```
+
+## Server/Client Boundaries
+
+### Server Components
+
+ALWAYS use server components for Echo AI calls that require authentication:
+
+```typescript
+// app/page.tsx
+import { openai } from '@/echo';
+import { generateText } from 'ai';
+
+export default async function Page() {
+ const { text } = await generateText({
+ model: openai('gpt-4o'),
+ prompt: 'Hello, world!',
+ });
+
+ return {text}
;
+}
+```
+
+### Client Components
+
+Use client components ONLY for UI interactions. NEVER make direct AI calls from client components with server secrets:
+
+```typescript
+// ✅ CORRECT - Client component uses Echo UI components
+'use client';
+
+import { EchoTokens } from '@merit-systems/echo-next-sdk/client';
+
+export function EchoButton() {
+ return ;
+}
+```
+
+```typescript
+// ❌ INCORRECT - Never use server secrets in client components
+'use client';
+
+import Echo from '@merit-systems/echo-next-sdk'; // Don't do this!
+
+export function BadComponent() {
+ const { openai } = Echo({ appId: process.env.ECHO_APP_ID! });
+ // This exposes server secrets to the client!
+}
+```
+
+## API Routes
+
+### Echo Authentication Handler
+
+ALWAYS register Echo authentication handlers at `app/api/echo/[...echo]/route.ts`:
+
+```typescript
+import { handlers } from '@/echo';
+
+export const { GET, POST } = handlers;
+```
+
+### Custom API Routes
+
+Place custom Echo-related API routes under `app/api/` and ALWAYS validate inputs:
+
+```typescript
+import { openai } from '@/echo';
+import { streamText } from 'ai';
+
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+ const { messages, model } = await req.json();
+
+ if (!model) {
+ return new Response(
+ JSON.stringify({ error: 'Bad Request', message: 'Model parameter is required' }),
+ { status: 400, headers: { 'Content-Type': 'application/json' } }
+ );
+ }
+
+ const result = streamText({
+ model: openai(model),
+ messages,
+ });
+
+ return result.toDataStreamResponse();
+}
+```
+
+## Project Structure
+
+Follow this recommended structure for Echo Next.js projects:
+
+```
+src/
+├── app/
+│ ├── api/
+│ │ ├── echo/
+│ │ │ └── [...echo]/
+│ │ │ └── route.ts # Echo auth handlers
+│ │ └── chat/
+│ │ └── route.ts # Custom API routes
+│ ├── layout.tsx
+│ └── page.tsx
+├── components/
+│ └── EchoWrapper.tsx # Client-side Echo components
+├── echo/
+│ └── index.ts # Server-side Echo initialization
+└── providers.tsx # Client providers including EchoProvider
+```
+
+## TypeScript Guidelines
+
+ALWAYS use strict typing and avoid `any`:
+
+```typescript
+// ✅ CORRECT
+function processMessages(messages: ChatMessage[]): string {
+ return messages.map(m => m.content).join('\n');
+}
+
+// ❌ INCORRECT
+function processMessages(messages: any): any {
+ return messages.map((m: any) => m.content).join('\n');
+}
+```
+
+## Error Handling
+
+ALWAYS handle errors explicitly and provide meaningful messages:
+
+```typescript
+try {
+ const result = await someOperation();
+ return result;
+} catch (error) {
+ console.error('Operation failed:', error);
+ throw new Error('Failed to complete operation');
+}
+```
+
+## Best Practices
+
+1. **Separation of Concerns**: Keep server logic in API routes and `src/echo/`, client logic in components
+2. **Environment Variables**: Use server variables for secrets, public variables for client-side config
+3. **Validation**: Always validate inputs in API routes before processing
+4. **Error Handling**: Provide clear error messages and appropriate HTTP status codes
+5. **Type Safety**: Use TypeScript strictly, export shared types
+6. **Security**: Never expose server secrets to the client
diff --git a/templates/nextjs-api-key-template/.cursor/rules/echo_rules.mdc b/templates/nextjs-api-key-template/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..91ab379c4
--- /dev/null
+++ b/templates/nextjs-api-key-template/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,109 @@
+---
+description: Guidelines and best practices for building Echo Next.js applications with server-side API key management, including database integration and authentication
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo Next.js API Key Template Guidelines
+
+## SDK Initialization
+
+### Server-Side Initialization
+
+ALWAYS initialize the Echo SDK in `src/echo/index.ts`:
+
+```typescript
+import Echo from '@merit-systems/echo-next-sdk';
+
+export const { handlers, isSignedIn, openai, anthropic } = Echo({
+ appId: process.env.ECHO_APP_ID!,
+});
+```
+
+### Client-Side Provider
+
+ALWAYS wrap your application with `EchoProvider`:
+
+```typescript
+'use client';
+
+import { EchoProvider } from '@merit-systems/echo-next-sdk/client';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+```
+
+## Environment Variables
+
+ALWAYS store secrets in `.env.local`:
+
+```bash
+ECHO_APP_ID=your_echo_app_id
+NEXT_PUBLIC_ECHO_APP_ID=your_echo_app_id
+DATABASE_URL=your_database_url
+```
+
+NEVER hardcode API keys, app IDs, or database URLs directly in your code.
+
+## Server/Client Boundaries
+
+Use server components for Echo AI calls and database operations. Use client components ONLY for UI interactions.
+
+```typescript
+// ✅ CORRECT
+'use client';
+import { EchoTokens } from '@merit-systems/echo-next-sdk/client';
+
+// ❌ INCORRECT - Never import server SDK in client components
+'use client';
+import Echo from '@merit-systems/echo-next-sdk';
+```
+
+## Echo Authentication Handler
+
+ALWAYS register Echo auth handlers at `app/api/echo/[...echo]/route.ts`:
+
+```typescript
+import { handlers } from '@/echo';
+export const { GET, POST } = handlers;
+```
+
+## Database & API Keys
+
+- Use Prisma for database access
+- Store API keys securely, never expose them to the client
+- Validate and sanitize all user inputs before database operations
+
+## Project Structure
+
+```
+src/
+├── app/
+│ ├── api/
+│ │ ├── echo/[...echo]/route.ts # Echo auth handlers
+│ │ └── keys/route.ts # API key management
+│ ├── layout.tsx
+│ └── page.tsx
+├── components/ # UI components
+├── echo/
+│ └── index.ts # Server-side Echo init
+├── lib/
+│ └── utils.ts
+└── providers.tsx
+prisma/
+└── schema.prisma # Database schema
+```
+
+## Best Practices
+
+1. **Separation**: Keep server logic in API routes and `src/echo/`, client logic in components
+2. **Environment Variables**: Use server variables for secrets, `NEXT_PUBLIC_` for client-side config
+3. **Validation**: Always validate inputs in API routes before processing
+4. **Error Handling**: Provide clear error messages and appropriate HTTP status codes
+5. **Type Safety**: Use TypeScript strictly, avoid `any`
+6. **Security**: Never expose server secrets or API keys to the client
+7. **Database**: Use Prisma migrations for schema changes, validate inputs before writes
diff --git a/templates/react-chat/.cursor/rules/echo_rules.mdc b/templates/react-chat/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..ae6983c0d
--- /dev/null
+++ b/templates/react-chat/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,100 @@
+---
+description: Guidelines and best practices for building Echo React Chat applications with Vite, including streaming responses, provider setup, and AI SDK integration
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo React Chat (Vite) Guidelines
+
+## SDK Initialization
+
+### EchoProvider Setup
+
+ALWAYS wrap your application with `EchoProvider` at the root level:
+
+```typescript
+import { EchoProvider } from '@merit-systems/echo-react-sdk';
+
+function App() {
+ return (
+
+
+
+ );
+}
+```
+
+### Using Echo Model Providers
+
+Access AI model providers through the `useEchoModelProviders` hook:
+
+```typescript
+import { useEchoModelProviders } from '@merit-systems/echo-react-sdk';
+
+function ChatWrapper() {
+ const { openai } = useEchoModelProviders();
+
+ // Use openai provider with the AI SDK
+ const result = streamText({
+ model: openai('gpt-4o'),
+ messages,
+ });
+}
+```
+
+### Chat Provider
+
+Use `EchoChatProvider` for chat-specific state management:
+
+```typescript
+import { EchoChatProvider } from '@merit-systems/echo-react-sdk';
+
+function ChatWrapper() {
+ return (
+
+
+
+ );
+}
+```
+
+## Environment Variables
+
+ALWAYS store your Echo App ID in `.env.local` with the `VITE_` prefix:
+
+```bash
+VITE_ECHO_APP_ID=your_echo_app_id
+```
+
+NEVER hardcode API keys or app IDs directly in your code.
+
+## Project Structure
+
+```
+src/
+├── main.tsx # App entry point
+├── App.tsx # Main app with EchoProvider and chat setup
+├── chat.tsx # Chat UI component
+├── header.tsx # Header component
+├── components/ # Shared UI components
+├── lib/ # Utility functions
+├── index.css # Global styles
+└── vite-env.d.ts # Vite type declarations
+```
+
+## TypeScript Guidelines
+
+ALWAYS use strict typing and avoid `any`:
+
+```typescript
+import type { ChatSendParams } from '@merit-systems/echo-react-sdk';
+import type { UIMessage } from 'ai';
+```
+
+## Best Practices
+
+1. **Provider Placement**: Always place `EchoProvider` at the root of your component tree
+2. **Streaming**: Use `streamText` from the AI SDK for chat responses
+3. **Hooks**: Use `useEcho` and `useEchoModelProviders` for accessing Echo state and models
+4. **Environment Variables**: Use `VITE_` prefix for all client-side environment variables
+5. **Type Safety**: Use TypeScript strictly, import types from the SDK
+6. **Security**: Remember that all Vite env vars are exposed to the browser
diff --git a/templates/react-image/.cursor/rules/echo_rules.mdc b/templates/react-image/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..f77b224d5
--- /dev/null
+++ b/templates/react-image/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,67 @@
+---
+description: Guidelines and best practices for building Echo React Image Generation applications with Vite, including provider setup, environment variables, and AI SDK integration
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo React Image Generation (Vite) Guidelines
+
+## SDK Initialization
+
+### EchoProvider Setup
+
+ALWAYS wrap your application with `EchoProvider` at the root level:
+
+```typescript
+import { EchoProvider } from '@merit-systems/echo-react-sdk';
+
+function App() {
+ return (
+
+
+
+ );
+}
+```
+
+### Using Echo Model Providers
+
+Access AI model providers through the `useEchoModelProviders` hook:
+
+```typescript
+import { useEchoModelProviders } from '@merit-systems/echo-react-sdk';
+
+function ImageGenerator() {
+ const { openai } = useEchoModelProviders();
+ // Use model providers for image generation
+}
+```
+
+## Environment Variables
+
+ALWAYS store your Echo App ID in `.env.local` with the `VITE_` prefix:
+
+```bash
+VITE_ECHO_APP_ID=your_echo_app_id
+```
+
+NEVER hardcode API keys or app IDs directly in your code.
+
+## Project Structure
+
+```
+src/
+├── main.tsx # App entry point with EchoProvider
+├── App.tsx # Main application component
+├── components/ # UI components
+├── lib/ # Utility functions
+├── index.css # Global styles
+└── vite-env.d.ts # Vite type declarations
+```
+
+## Best Practices
+
+1. **Provider Placement**: Always place `EchoProvider` at the root of your component tree
+2. **Environment Variables**: Use `VITE_` prefix for all client-side environment variables
+3. **Type Safety**: Use TypeScript strictly, avoid `any`
+4. **Error Handling**: Always provide meaningful error messages
+5. **Security**: Remember that all Vite env vars are exposed to the browser
diff --git a/templates/react/.cursor/rules/echo_rules.mdc b/templates/react/.cursor/rules/echo_rules.mdc
new file mode 100644
index 000000000..d023f5270
--- /dev/null
+++ b/templates/react/.cursor/rules/echo_rules.mdc
@@ -0,0 +1,116 @@
+---
+description: Guidelines and best practices for building Echo React (Vite) applications, including provider setup, environment variables, and component patterns
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo React (Vite) Guidelines
+
+## SDK Initialization
+
+### EchoProvider Setup
+
+ALWAYS wrap your application with `EchoProvider` at the root level in `src/main.tsx`:
+
+```typescript
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App.tsx';
+import { EchoProvider } from '@merit-systems/echo-react-sdk';
+
+createRoot(document.getElementById('root')!).render(
+
+
+
+
+
+);
+```
+
+### Using Echo Components
+
+Use the provided Echo UI components for common functionality:
+
+```typescript
+import { EchoTokens } from '@merit-systems/echo-react-sdk';
+
+function App() {
+ return (
+ <>
+ Welcome to Echo
+
+
+ );
+}
+```
+
+## Environment Variables
+
+ALWAYS store your Echo App ID in `.env.local` with the `VITE_` prefix:
+
+```bash
+VITE_ECHO_APP_ID=your_echo_app_id
+```
+
+NEVER hardcode API keys or app IDs directly in your code:
+
+```typescript
+// ✅ CORRECT
+const appId = import.meta.env.VITE_ECHO_APP_ID;
+
+// ❌ INCORRECT
+const appId = 'echo_app_123abc';
+```
+
+Note: Vite exposes environment variables prefixed with `VITE_` to the client. Be aware that these are visible in the browser.
+
+## Project Structure
+
+Follow this recommended structure for Echo React projects:
+
+```
+src/
+├── main.tsx # App entry point with EchoProvider
+├── App.tsx # Main application component
+├── App.css # App styles
+├── index.css # Global styles
+├── assets/ # Static assets
+└── vite-env.d.ts # Vite type declarations
+```
+
+## TypeScript Guidelines
+
+ALWAYS use strict typing and avoid `any`:
+
+```typescript
+// ✅ CORRECT
+interface Message {
+ id: string;
+ content: string;
+ role: 'user' | 'assistant';
+}
+
+// ❌ INCORRECT
+function handleMessage(msg: any): any { ... }
+```
+
+## Error Handling
+
+ALWAYS handle errors explicitly:
+
+```typescript
+try {
+ const result = await someOperation();
+ return result;
+} catch (error) {
+ console.error('Operation failed:', error);
+ throw new Error('Failed to complete operation');
+}
+```
+
+## Best Practices
+
+1. **Provider Placement**: Always place `EchoProvider` at the root of your component tree
+2. **Environment Variables**: Use `VITE_` prefix for all client-side environment variables
+3. **Type Safety**: Use TypeScript strictly, export shared types
+4. **Error Handling**: Always provide meaningful error messages
+5. **Security**: Remember that all Vite env vars are exposed to the browser -- never put true secrets there