feat(templates): add .cursor/rules/echo_rules.mdc to echo-start

templates/assistant-ui/.cursor/rules/echo_rules.mdc

@@ -0,0 +1,43 @@
+---
+description: Echo assistant-ui template rules covering Echo handler setup, App Router echo route, NEXT_PUBLIC vs server env vars, client-side provider config, and component conventions
+globs: **/*.{ts,tsx,js,jsx,mjs,cjs}
+---
+
+# Echo assistant-ui Template Rules
+
+## Echo Server Wiring
+
+- Echo is initialized in the root `echo.ts` file (not `src/echo/index.ts` — this template uses `echo.ts` at the project root).
+- The `echo.ts` default export is `echo.handlers`; named exports include `getUser`, `isSignedIn`, `openai`, `anthropic`, `google`.
+- The echo route (typically `app/api/echo/[...path]/route.ts` or `app/api/echo/[...echo]/route.ts`) must stay as a thin passthrough — import `handlers` from `@/echo` (the root `echo.ts`) and export `{ GET, POST }`.
+- Do not move or rename `echo.ts`; the assistant-ui components and API routes depend on its location.
+
+## Environment Variables
+
+- This template uses `NEXT_PUBLIC_ECHO_APP_ID` (not `ECHO_APP_ID`) for the Echo `appId`; this is intentional for the assistant-ui client-side provider.
+- Validate that `NEXT_PUBLIC_ECHO_APP_ID` is set before rendering the assistant UI; show a clear setup error if missing.
+- Never add server-only secrets to `NEXT_PUBLIC_` env vars; only the Echo app ID is safe to expose here.
+
+## assistant-ui Component Conventions
+
+- Keep assistant-ui component wiring (`<Thread>`, `<AssistantModal>`, providers) in the designated layout or page component; do not scatter provider setup across multiple files.
+- Use assistant-ui's built-in primitives for message rendering, input handling, and tool call display; avoid building custom replacements unless the template pattern requires it.
+- Pass the Echo-configured model (from `openai`, `anthropic`, or `google`) to the assistant runtime; do not configure model providers independently of Echo.
+
+## Client vs. Server
+
+- Keep `echo.ts` as server-only; import it only from Route Handlers and Server Components.
+- In Client Components, use the assistant-ui hooks and context rather than importing from `echo.ts` directly.
+- Use `@/` path alias for all internal imports.
+
+## App Router Conventions
+
+- Follow Next.js App Router structure with `page.tsx`, `layout.tsx`, `route.ts` conventions.
+- Default to Server Components; use `"use client"` only for assistant-ui interactive components.
+- Preserve the existing component structure in `app/` and `components/`; use the `lib/` folder for shared utilities.
+
+## Security
+
+- Route all model inference through the Echo server handler; the client receives streamed output, never raw API responses.
+- Use `isSignedIn` from `echo.ts` to gate any routes that require an authenticated Echo session.
+- Do not log or return `getUser()` data in client-visible error responses.

templates/authjs/.cursor/rules/echo_rules.mdc

@@ -0,0 +1,46 @@
+---
+description: Echo Next.js + Auth.js template rules covering Echo server wiring, Auth.js session handling, protected routes, client providers, and env safety
+globs: **/*.{ts,tsx,js,jsx,mjs,cjs}
+---
+
+# Echo Next.js + Auth.js Template Rules
+
+## Echo Server Wiring
+
+- Keep Echo server setup centralized in `src/echo/index.ts`; export `handlers`, `isSignedIn`, `openai`, `anthropic` from there.
+- The echo route (`src/app/api/echo/[...echo]/route.ts`) must stay as a thin passthrough: `export const { GET, POST } = handlers`.
+- Import from `@merit-systems/echo-next-sdk` in server code; use `@merit-systems/echo-next-sdk/client` in Client Components only.
+
+## Auth.js Integration
+
+- Define your Auth.js config in `src/auth.ts` (or `src/auth/index.ts`); export `auth`, `signIn`, `signOut`, and `handlers` from there.
+- Protect server routes and Server Components using the `auth()` helper — check `session.user` before proceeding.
+- Use `isSignedIn` from Echo (`src/echo/index.ts`) to additionally gate Echo-specific API usage; combine with Auth.js session checks when both are required.
+- Keep Auth.js providers, callbacks, and adapter config within the auth config file; do not scatter them across API routes.
+- For the Auth.js route, use `src/app/api/auth/[...nextauth]/route.ts` as a passthrough: `export const { GET, POST } = handlers`.
+
+## Environment Variables
+
+- `ECHO_APP_ID` — server-side Echo app identifier (never expose to client).
+- `NEXTAUTH_SECRET` — required by Auth.js; must be a strong random string in production.
+- `NEXTAUTH_URL` — set to the canonical deployment URL; required for OAuth redirects.
+- `NEXT_PUBLIC_ECHO_APP_ID` — only if needed for client-side Echo provider initialization.
+- Validate all required env vars at startup; fail fast with clear error messages.
+
+## Session & Protected Pages
+
+- Use `auth()` in Server Components/layouts to get the session and redirect unauthenticated users via `redirect('/login')`.
+- Do not trust client-supplied user identity; always derive user info from the server-side session.
+- Use middleware (`src/middleware.ts`) to protect entire route groups rather than repeating auth checks in each page.
+
+## App Router Conventions
+
+- Follow Next.js App Router structure: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts`.
+- Use `@/` path alias for all internal imports.
+- Default to Server Components; add `"use client"` only for interactive UI components.
+
+## Security
+
+- Never return raw provider tokens or internal error details to the client.
+- Rotate `NEXTAUTH_SECRET` on credential compromise; update all deployed environments.
+- Route all LLM calls through server Route Handlers authenticated via session or `isSignedIn`.

templates/echo-cli/.cursor/rules/echo_rules.mdc

@@ -0,0 +1,51 @@
+---
+description: Echo CLI template rules covering command architecture, auth flows, wallet handling, config management, output conventions, and error handling
+globs: **/*.{ts,js,mjs,cjs}
+---
+
+# Echo CLI Template Rules
+
+## Command Architecture
+
+- Define all CLI commands in `src/index.ts` using Commander; keep command `.action()` handlers thin — delegate to modules in `src/core/`, `src/auth/`, or `src/utils/`.
+- Organize business logic by domain: `src/core/` for chat/session logic, `src/auth/` for login/logout flows, `src/utils/` for shared helpers, `src/config/` for persistence.
+- Use `src/constants.ts` for all magic strings, ASCII art, and option arrays; never hardcode repeated values inline.
+- Register sub-commands as separate `program.command(...)` calls; do not nest all logic in a single giant command.
+
+## Authentication Flows
+
+- Gate commands that require authentication with the `isAuthenticated()` utility from `src/utils`; show a clear login prompt if the user is unauthenticated.
+- Use `loginWithEcho` and `loginWithWallet` from `src/auth` for the two supported auth modes; do not implement auth logic outside these modules.
+- Use `@clack/prompts` (`select`, `text`, `confirm`, `isCancel`) for all interactive prompts; always check `isCancel(result)` and exit cleanly with `process.exit(0)`.
+- Persist session/token data using the existing secure keychain/storage paths in `src/config`; never store sensitive values in plain files or env vars.
+
+## Wallet Handling
+
+- Use `initLocalWallet` and `exportPrivateKey` from `src/auth` for wallet creation/export; never generate or log key material outside these functions.
+- Show explicit user confirmation prompts before any wallet-destructive operations (export private key, fund wallet).
+- Display wallet addresses and balances using the print utilities in `src/print`; never construct raw `console.log` output for structured data.
+
+## Config & Environment
+
+- Read `ECHO_APP_ID` via the centralized constant in `src/constants.ts`; do not use `process.env.ECHO_APP_ID` directly in command handlers.
+- Store user preferences and session state in the config module (`src/config`); do not use ad-hoc files or global variables.
+- Validate required config at startup; surface clear error messages if `ECHO_APP_ID` or other required values are missing.
+
+## Output & UX Conventions
+
+- Use `info`, `warning`, `header`, and error utilities from `src/print` for all user-facing output; keep console output consistent in style.
+- Display the `ECHODEX_ASCII_ART` banner via `header()` at program startup and on appropriate subcommands.
+- Use `@clack/prompts` spinners for async operations that may take >1 second (network, wallet ops).
+- Handle `process.exit` semantics carefully: exit code `0` for user cancellation/clean exit, non-zero for errors.
+
+## Error Handling
+
+- Wrap async command handlers in try/catch; surface actionable error messages via `warning()` or `info()` — never raw stack traces in production mode.
+- For network failures (Echo API, wallet RPC), retry with backoff where appropriate; otherwise present a clear retry suggestion to the user.
+- Never crash silently; always give the user a next step (re-authenticate, check network, contact support).
+
+## TypeScript
+
+- Use strict TypeScript; add `@types/node` to `devDependencies` when using Node.js built-ins.
+- Type all function signatures explicitly; avoid inferred `any` from async operations.
+- Use `as const` for option arrays passed to `@clack/prompts` to get proper literal types.

templates/next-chat/.cursor/rules/echo_rules.mdc

@@ -0,0 +1,49 @@
+---
+description: Echo Next.js Chat template rules covering Echo server wiring, streaming chat, AI SDK patterns, client providers, message state, and env safety
+globs: **/*.{ts,tsx,js,jsx,mjs,cjs}
+---
+
+# Echo Next.js Chat Template Rules
+
+## Echo Server Wiring
+
+- Keep Echo initialization in `src/echo/index.ts`; export `handlers`, `isSignedIn`, `openai`, `anthropic` from there.
+- The echo route (`src/app/api/echo/[...echo]/route.ts`) must be a thin passthrough: `export const { GET, POST } = handlers`.
+- Import `@merit-systems/echo-next-sdk` in server code; use `@merit-systems/echo-next-sdk/client` in Client Components only.
+
+## Streaming Chat Architecture
+
+- Use the AI SDK (`streamText`, `convertToModelMessages`) for streaming responses; return `result.toUIMessageStream()` from server actions or route handlers.
+- Keep streaming logic within existing component boundaries (e.g., `ChatWrapper`); do not lift streaming state into layouts or global providers.
+- Handle stream errors at the component level with appropriate loading and error states; do not let unhandled promise rejections crash the UI.
+- Use `EchoChatProvider` from `@merit-systems/echo-react-sdk` to manage chat session state; do not build custom message state if the provider covers your use case.
+
+## Client Providers
+
+- Wrap the app root with `EchoProvider` (and `EchoChatProvider` where needed); pass `appId: import.meta.env.VITE_ECHO_APP_ID` (Vite) or `process.env.NEXT_PUBLIC_ECHO_APP_ID` (Next.js).
+- Use `useEcho()` and `useEchoModelProviders()` hooks to access the authenticated Echo client and model instances in Client Components.
+- Do not create additional provider wrappers unless you need to override default behavior; compose with existing providers instead.
+
+## Message State & UX
+
+- Maintain chat message history within the chat component or `EchoChatProvider`; do not persist messages to global state unless the template's existing pattern does so.
+- Show typing/loading indicators during streaming; disable the send button while a message is in-flight to prevent duplicate submissions.
+- Support graceful cancellation of in-flight streams via AbortController when the user navigates away or triggers a new request.
+
+## Environment Variables
+
+- `ECHO_APP_ID` — server-side only, for `src/echo/index.ts`.
+- `NEXT_PUBLIC_ECHO_APP_ID` — client-side provider config only.
+- Never embed provider API keys (OpenAI, Anthropic) in client code; route all model calls through the Echo server handler.
+
+## App Router Conventions
+
+- Use `@/` path alias for internal imports; never use deep relative paths.
+- Keep Server Components as the default; add `"use client"` only for interactive chat UI and hook consumers.
+- Use `loading.tsx` and `error.tsx` at appropriate route segments.
+
+## Security
+
+- All LLM inference calls must be proxied through the Echo server Route Handler; never call OpenAI/Anthropic APIs directly from the client.
+- Use `isSignedIn` to gate the chat route if authentication is required.
+- Sanitize user input before displaying it; avoid `dangerouslySetInnerHTML` with user-provided content.

templates/next-image/.cursor/rules/echo_rules.mdc

@@ -0,0 +1,50 @@
+---
+description: Echo Next.js Image Generation template rules covering Echo server wiring, image generation flows, provider config, file handling, and env safety
+globs: **/*.{ts,tsx,js,jsx,mjs,cjs}
+---
+
+# Echo Next.js Image Generation Template Rules
+
+## Echo Server Wiring
+
+- Keep Echo initialization in `src/echo/index.ts`; export `handlers`, `isSignedIn`, `openai`, `anthropic`, `google` and other provider helpers from there.
+- The echo route (`src/app/api/echo/[...echo]/route.ts`) must be a thin passthrough: `export const { GET, POST } = handlers`.
+- Use `ECHO_APP_ID` for server-side initialization; never expose it to the client bundle.
+- Import from `@merit-systems/echo-next-sdk` in server code; use `@merit-systems/echo-next-sdk/client` in Client Components only.
+
+## Image Generation Flows
+
+- Invoke image generation through the Echo-proxied provider client (e.g., `openai`, `google` from `src/echo/index.ts`); never call provider image APIs directly from client code.
+- Handle image generation as an async server-side operation; return URLs or base64 data from Route Handlers, not the raw provider response object.
+- Validate prompt inputs server-side before forwarding to the provider; reject empty or excessively long prompts with appropriate HTTP error responses.
+- Include model-specific parameters (size, quality, style, n) as named options; document supported values in a comment near the call site.
+
+## File & Asset Handling
+
+- Store generated images using Next.js public folder conventions or an external storage service; do not store binary data in the database.
+- Use Next.js `<Image>` component for displaying generated images to benefit from automatic optimization and lazy loading.
+- Set appropriate `alt` text on all generated images for accessibility.
+
+## Environment Variables
+
+- `ECHO_APP_ID` — server-side Echo app identifier.
+- `NEXT_PUBLIC_ECHO_APP_ID` — client-side provider config only.
+- Add any additional provider-specific keys (e.g., `GOOGLE_API_KEY`) to `.env.local` and document them in `.env.example`; never commit real values.
+
+## Client vs. Server
+
+- Trigger image generation from Server Actions or Route Handlers; client code should only submit the prompt and display results.
+- In client components, use `useEcho()` or `useEchoModelProviders()` hooks from `@merit-systems/echo-next-sdk/client` or `@merit-systems/echo-react-sdk`.
+- Show progress/loading state during generation (image generation typically takes 5–30 seconds).
+
+## App Router Conventions
+
+- Use `@/` path alias for all internal imports.
+- Use Server Components for data fetching and generation triggers; use Client Components only for interactive UI (prompt form, image gallery).
+- Handle generation errors in `error.tsx` or inline with try/catch in Server Actions.
+
+## Security
+
+- Implement rate limiting on image generation routes to prevent abuse.
+- Do not pass raw user input as system prompts; sanitize or constrain prompt inputs before forwarding.
+- Log generation requests for audit purposes but never log the full provider API response including billing metadata.

templates/next-video-template/.cursor/rules/echo_rules.mdc

@@ -0,0 +1,50 @@
+---
+description: Echo Next.js Video Generation template rules covering Echo server wiring, video generation flows, multi-provider config (openai/anthropic/google), async job handling, and env safety
+globs: **/*.{ts,tsx,js,jsx,mjs,cjs}
+---
+
+# Echo Next.js Video Generation Template Rules
+
+## Echo Server Wiring
+
+- Keep Echo initialization in `src/echo/index.ts`; export `handlers`, `isSignedIn`, `openai`, `anthropic`, `google`, `getUser`, `getEchoToken` from there.
+- The echo route (`src/app/api/echo/[...echo]/route.ts`) must remain a thin passthrough: `export const { GET, POST } = handlers`.
+- Use `ECHO_APP_ID` for server-side initialization; never expose this to the client.
+- Import from `@merit-systems/echo-next-sdk` in server code; use `@merit-systems/echo-next-sdk/client` in Client Components only.
+
+## Video Generation Flows
+
+- Invoke video generation through Echo-proxied provider clients (`openai`, `google`, `anthropic` from `src/echo/index.ts`); never call Sora, Veo, or other video provider APIs directly from client code.
+- Video generation is long-running; implement an async job pattern — submit the generation request, return a job ID, and poll for completion or use webhooks.
+- Return job status and video URLs from Route Handlers, not raw provider response payloads.
+- Validate prompt inputs server-side: enforce length limits, reject banned content categories, and normalize whitespace before forwarding.
+
+## Multi-Provider Handling
+
+- This template may use OpenAI (Sora), Google (Veo), or other providers; keep provider selection configurable via request parameters or environment variables.
+- Abstract provider-specific request shapes behind a shared server function; do not scatter provider-specific code across multiple route files.
+- Document which providers are enabled by which env vars; fail fast with clear errors when a requested provider is not configured.
+
+## Async Job Management
+
+- Track generation jobs server-side (in-memory for development, persistent storage for production); associate jobs with the requesting user via `getUser()` from Echo.
+- Implement job status polling endpoint at a well-known path; return `{ status: 'pending' | 'complete' | 'failed', url?: string, error?: string }`.
+- Clean up completed or failed job records after a reasonable TTL to prevent memory/storage leaks.
+
+## File & Asset Handling
+
+- Store generated videos in external object storage (S3, GCS, R2); do not stream large video blobs through Next.js responses.
+- Use signed URLs with appropriate expiry for video delivery; do not expose storage bucket paths directly.
+- Use Next.js `<video>` element with proper `controls`, `preload`, and `poster` attributes for video playback.
+
+## Environment Variables
+
+- `ECHO_APP_ID` — server-side Echo app identifier.
+- `NEXT_PUBLIC_ECHO_APP_ID` — client-side provider config only.
+- Add provider-specific keys to `.env.example`; document the required format and where to obtain them.
+
+## Security & Rate Limiting
+
+- Implement per-user rate limiting on video generation routes; video generation is expensive.
+- Use `isSignedIn` from Echo or `getUser()` to authenticate all generation requests; reject unauthenticated requests with 401.
+- Do not log full provider responses; they may contain billing metadata or PII.