echo_rules.mdc

---
description: Guidelines for the Echo Next.js API-key/database template.
globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx,**/*.mjs,**/*.cjs
---

# Echo template guidelines

## Echo principles
- Keep Echo as the billing/auth boundary: do not bypass Echo model providers with direct OpenAI, Anthropic, or Google SDK calls unless this template already demonstrates a non-Echo provider for a specific reason.
- Keep Echo App IDs in environment variables. Never hard-code real app IDs, API keys, private keys, wallet keys, or webhook secrets.
- Prefer the Echo SDK package that matches this template (`@merit-systems/echo-next-sdk`, `@merit-systems/echo-react-sdk`, `@merit-systems/echo-typescript-sdk`, or Auth.js provider) instead of mixing SDKs.
- Preserve the template's package manager, import aliases, styling stack, and file structure.
- Keep examples minimal and copy-pasteable for users who generated the template with `echo-start`.

## TypeScript and AI SDK conventions
- Use explicit TypeScript types for public helpers, route handlers, and SDK wrappers.
- Keep streaming AI responses compatible with the Vercel AI SDK patterns already used by the template.
- Prefer existing model provider exports/hooks from the template (`openai`, `anthropic`, `useEchoModelProviders`, or configured clients) over creating new clients.
- Do not log full prompts, user secrets, API keys, access tokens, payment links, or wallet/private-key data.

## Verification before finishing changes
- Run the template's local check when practical: lint, build, or typecheck according to `package.json`.
- If a check depends on external Echo credentials, document that limitation instead of replacing real credentials with fake checked-in values.

## Next.js API-key/database specifics
- Keep Prisma access in `src/lib/db.ts` and never instantiate Prisma clients in React components.
- Preserve Echo server setup in `src/echo/index.ts` and client provider setup in `src/providers.tsx`.
- Store API keys securely: hash or encrypt secrets where the existing code expects it, and never expose raw API keys in client payloads or logs.
- Keep database setup files (`docker-local-db.yml`, `prisma/schema.prisma`, `env.example`) consistent when changing API-key flows.
- Use the template's Biome and Prisma scripts when validating relevant changes.