Echo Cursor Rules Template

templates/.cursor/rules/echo_rules.mdc

@@ -0,0 +1,15 @@
+---
+description: Shared Echo conventions for starter templates.
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+---
+
+# Echo Starter Guidelines
+
+- Keep Echo SDK setup in the template's existing Echo module or provider file.
+- Read Echo app IDs, API keys, and wallet credentials from environment variables.
+- Keep server-only Echo clients out of browser bundles.
+- Use TypeScript types for provider configuration, model selection, and API payloads.
+- Keep React UI components focused on rendering and user interaction.
+- Keep API, auth, wallet, and provider concerns in separate modules.
+- Prefer async/await and explicit error handling for Echo SDK calls.
+- Do not hardcode model names in multiple places; centralize supported model choices.

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

@@ -0,0 +1,39 @@
+---
+description: Guidelines for building Echo CLI starter apps.
+globs: **/*.ts
+---
+
+# Echo CLI Guidelines
+
+## CLI Boundaries
+
+- Keep command parsing in `src/index.ts` and delegate work to `src/core`.
+- Keep Echo auth and provider creation inside `src/auth`.
+- Keep config loading and persistence inside `src/config`.
+- Keep terminal output formatting inside `src/print.ts` or `src/utils`.
+
+## Authentication And Secrets
+
+- Read Echo API keys, wallet settings, and profile configuration from the existing config layer.
+- Do not print secrets, private keys, raw tokens, or full wallet credentials.
+- Keep local wallet operations isolated in the wallet/auth modules.
+- Return user-friendly auth errors without exposing credential material.
+
+## Provider Usage
+
+- Create Echo model providers through `@merit-systems/echo-typescript-sdk`.
+- Centralize supported model names in `src/config/models.ts`.
+- Stream model output through the existing stream utilities.
+- Preserve chat history through `src/core/history.ts` instead of ad hoc files.
+
+## Validation
+
+- Validate command inputs with the schemas in `src/validation`.
+- Fail early for missing model, prompt, API key, or wallet configuration.
+- Keep error messages actionable and avoid swallowing provider failures.
+
+## TypeScript
+
+- Use explicit types for CLI options, auth profiles, model configs, and chat messages.
+- Prefer async/await for provider, wallet, and filesystem operations.
+- Keep side effects at the command boundary and core/auth modules.

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

@@ -0,0 +1,40 @@
+---
+description: Guidelines for building Echo Next.js starter apps.
+globs: **/*.ts,**/*.tsx
+---
+
+# Echo Next.js Guidelines
+
+## SDK Setup
+
+- Initialize the server Echo SDK in `src/echo/index.ts`.
+- Export the SDK helpers from that module and import them from application code.
+- Register Echo client providers in `src/providers.tsx`.
+- Wrap the app with `EchoProvider` using `NEXT_PUBLIC_ECHO_APP_ID`.
+
+## Server And Client Boundaries
+
+- Use server components, route handlers, or server actions for operations that need server-only credentials.
+- Keep `"use client"` components limited to UI state, sign-in UI, account display, and token/balance controls.
+- Import browser hooks and UI helpers from `@merit-systems/echo-next-sdk/client`.
+- Do not import the server SDK from client components.
+
+## API Routes
+
+- Put Echo-related API handlers under `src/app/api`.
+- Validate JSON request bodies before calling provider models.
+- Return explicit HTTP status codes for validation and provider errors.
+- Stream model responses from route handlers when building chat or generation flows.
+
+## Environment
+
+- Use `ECHO_APP_ID` only on the server.
+- Use `NEXT_PUBLIC_ECHO_APP_ID` only for public client configuration.
+- Do not hardcode app IDs, API keys, wallet keys, or model-provider secrets.
+
+## Project Shape
+
+- Keep shared Echo setup in `src/echo`.
+- Keep client wrappers in `src/components` or `src/providers.tsx`.
+- Keep reusable request/response types close to the route or in `src/lib`.
+- Add tests or examples beside the route/component when adding a new Echo workflow.

templates/react/.cursor/rules/echo_rules.mdc

@@ -0,0 +1,37 @@
+---
+description: Guidelines for building Echo Vite React starter apps.
+globs: **/*.ts,**/*.tsx
+---
+
+# Echo React Guidelines
+
+## Provider Setup
+
+- Configure `EchoProvider` in `src/main.tsx`.
+- Read the public Echo app ID from `import.meta.env.VITE_ECHO_APP_ID`.
+- Keep provider configuration at the app boundary instead of duplicating it in pages.
+- Use hooks from `@merit-systems/echo-react-sdk` inside React components.
+
+## Components
+
+- Keep Echo account, balance, and token controls in small reusable components.
+- Keep model selection and prompt state in typed React state.
+- Avoid putting provider setup or long-running model orchestration directly in presentational components.
+- Extract shared Echo UI state into hooks when more than one component needs it.
+
+## Environment
+
+- Only expose values intended for the browser through `VITE_` variables.
+- Do not place server credentials, private wallet keys, or API keys in Vite env values.
+- Route server-only Echo calls through a backend service instead of calling them from the browser.
+
+## TypeScript
+
+- Type chat messages, model options, and provider responses explicitly.
+- Avoid `any` for Echo hook values and model payloads.
+- Keep supported model/provider lists centralized.
+
+## Testing
+
+- Mock Echo hooks and provider clients in component tests.
+- Test loading, signed-out, signed-in, and provider-error states for Echo UI.