# Frontend Service Agent

Expert agent for working in frontend React/TypeScript services.

## Context

You are working in a React/TypeScript frontend application for the Orchard Insights music analytics platform.

## Service Identification

- `frontend-insights` — Main analytics app (single app, Yarn, Webpack+SWC, Jest)
- `orchard-suite` — Shared component library monorepo (71 packages, pnpm, Vite, Vitest)

## frontend-insights Patterns

### Adding a New Page

1. Create directory in `src/pages/<page-name>/`
2. Create `<PageName>Page.tsx` with `<Page>` compound component
3. Add sub-views in `pages/`, components in `components/`, hooks in `hooks/`
4. Add route with `React.lazy` + `Suspense`
5. Add URL params as constants in `src/constants/params.ts`

### Adding a GraphQL Query

1. Create `.gql` file in `src/apollo/queries/<domain>/`
2. Create `.ts` wrapper with data transformation
3. Run `yarn generate:types` to regenerate TypeScript
4. Use generated hook in component
5. Default fetch policy: `cache-and-network` with `nextFetchPolicy: cache-first`

### Component Conventions

- Use components from `@theorchard/suite-components` (70+ available)
- Feature flags via `useIdentity()` hook
- URL params via `useRouteParams` (constants in `src/constants/params.ts`)
- Analytics via Segment helpers in `src/utils/segment/`
- Styling: colocated SCSS, BEM naming, global vars from `src/styles/variables.scss`

## orchard-suite Patterns

### Component Development

Read `packages/suite-components/AGENTS.md` for detailed patterns. Key rules:
- Uppercase `CLASSNAME` constant
- `classnames` as `cx` for conditional classes
- Always include `testId` prop
- JSDoc with `@type`, `@status`, `@tags`
- Tests use `screen` + React Testing Library queries (prefer `getByRole`)

### Package Development

1. Build produces ESM + CJS dual output
2. Run package-specific commands with `pnpm -F @theorchard/<name> <command>`
3. Changes to shared packages affect all downstream consumers
4. Build order matters — see orchard-suite CLAUDE.md

## Common Commands

```bash
# frontend-insights
yarn start              # Dev server (requires VPN)
yarn test:unit          # Jest unit tests
yarn generate:types     # Regenerate GraphQL types
yarn lint               # ESLint + Stylelint

# orchard-suite
pnpm install            # Install all workspace deps
pnpm -F <package> test:unit   # Test specific package
pnpm -F <package> build       # Build specific package
```

## Common Mistakes to Avoid

- Do NOT import entire lodash — use `import map from 'lodash/map'` (bundle size)
- Do NOT edit `src/apollo/definitions/` — auto-generated
- Do NOT use string literals for feature flags — use constants from `src/constants/featureFlags.ts`
- Do NOT use string literals for URL params — use constants from `src/constants/params.ts`
- Do NOT use string literals for Segment events — use constants from `src/constants/segment.ts`
- Do NOT add inline styles — use CSS classes
- Do NOT mock Apollo queries inline — use established mock patterns in `lib/test/`
- In orchard-suite: do NOT use npm or yarn — pnpm is enforced
- In orchard-suite: do NOT add Bootstrap dependencies to new components