# AGENTS.md

## Stack
{{framework}}{{#if frameworkVersion}} {{frameworkVersion}}{{/if}}{{#if frameworkVariant}} ({{frameworkVariant}}){{/if}}, TypeScript, {{styling || css}}{{#if unitTest}}, {{unitTest}}{{/if}}{{#if e2eTest}}, {{e2eTest}}{{/if}}

{{#if aiEntryPoints}}## Entry Points
{{aiEntryPoints}}

{{/if}}
## Commands
{{#if hasAiAnalysis}}
| Action | Command |
|--------|---------|
| Dev | `{{devCommand}}` |
| Build | `{{buildCommand}}` |
| Test | `{{testCommand}}` |
| Lint | `{{lintCommand}}` |
| Typecheck | `{{typecheckCommand}}` |
{{else}}
All commands run from `{{appDir}}/` directory:

| Action | Command |
|--------|---------|
| Dev | `cd {{appDir}} && {{devCommand}}` |
| Build | `cd {{appDir}} && {{buildCommand}}` |
| Lint | `cd {{appDir}} && {{lintCommand}}` |
| Lint fix | `cd {{appDir}} && {{lintCommand}} -- --fix` |
| Format | `cd {{appDir}} && {{formatCommand}}` |
| Typecheck | `cd {{appDir}} && {{typecheckCommand}}` |
{{#if unitTest}}| Test | `cd {{appDir}} && {{testCommand}}` |
| Test watch | `cd {{appDir}} && {{testCommand}} -- --watch` |{{/if}}
{{/if}}

## Validation (run before commit)
```bash
{{lintCommand}} && {{typecheckCommand}}{{#if unitTest}} && {{testCommand}}{{/if}} && {{buildCommand}}
```

{{#if aiKeyDirectories}}## Project Structure

| Directory | Purpose |
|-----------|---------|
{{aiKeyDirectories}}

{{else}}
## Patterns
- Pages: `{{appDir}}/app/` - Next.js App Router
- Components: `{{appDir}}/components/` - see ui/, ai-elements/, survey-editor/
- API: `{{appDir}}/app/api/` - streaming endpoints with tool calling
- Store: `{{appDir}}/store/` - State management
- Server Actions: `{{appDir}}/app/actions.ts` and `{{appDir}}/app/actions/`
- Libs: `{{appDir}}/lib/` - utilities and integrations
{{/if}}

{{#if aiImplementationGuidelines}}## Implementation Guidelines
{{aiImplementationGuidelines}}

{{/if}}
## Search Tools
- **Codebase search**: Use `mgrep "query"` (preferred over Grep/Glob)
- **Documentation lookup**: Use Context7 MCP for library/framework docs
- **Web search**: Use `mgrep --web "query"` for general web lookups

## Code Rules
{{#if aiNamingConventions}}- Naming: {{aiNamingConventions}}
{{/if}}- Explicit return types on functions
- No `any` - use `unknown` if truly unknown
- Early returns over nested conditionals
- Named exports, not default exports
- Path alias `@/` maps to `{{appDir}}/` root
- Follow patterns in existing code
- 2-space indentation, single quotes

{{#if unitTest}}## Testing
- Framework: {{unitTest}}{{#if unitTestVersion}} {{unitTestVersion}}{{/if}}
- Run: `{{testCommand}}`
- Each feature task should include tests
- Validation fails if tests fail
{{/if}}

## Secrets
- Use `.env.local` for secrets, never commit API keys
- Use `process.env.*` for all secrets

## Git
- Commits: `type(scope): description` (conventional commits)
- Types: feat, fix, docs, refactor, test, chore
- After changes: validate, commit, push

## MCP Servers Available
{{#if aiMcpEssential}}- **Essential**: {{aiMcpEssential}}
{{/if}}{{#if aiMcpRecommended}}- **Recommended**: {{aiMcpRecommended}}
{{/if}}- **Supabase**: Query DB, manage migrations, generate types
- **PostHog**: Analytics, feature flags, experiments
- **Playwright**: Browser automation for E2E testing
  - Navigate: `browser_navigate`, `browser_snapshot`
  - Interact: `browser_click`, `browser_type`, `browser_fill_form`
  - Verify: `browser_wait_for`, `browser_console_messages`
  - Debug: `browser_take_screenshot`
- **Context7**: Documentation lookup for libraries/frameworks

{{#if aiMissedTechnologies}}## May Also Use
{{aiMissedTechnologies}}

{{/if}}
## Quick Triggers
| Keywords | Action |
|----------|--------|
| type error, ts | Run typecheck |
| lint, format | Run lint --fix |
| deploy, build | Run full build |
| error, debug | Check logs or console |
| database, table | Use Supabase MCP |
| e2e, browser test | Use Playwright MCP |

## Detailed Docs
- Frontend: `.ralph/guides/FRONTEND.md` - design patterns, component usage, quality checklist