AGENTS.md Critique Report

What worked well

• Clear role definition: The opening line immediately establishes this is a React frontend that talks to a FastAPI backend via REST and AG-UI streaming protocol.
• Explicit "Modify these" vs "Do NOT modify" sections: This is excellent for preventing accidental changes to config files or static assets.
• Command reference with context: Commands include the dr task run prefix and note they run from project root, preventing common path errors.
• Technology stack is explicit: React 19, Vite 7, TypeScript strict mode, Tailwind v4, Radix UI, shadcn/ui, Zustand, React Query — all clearly listed.
• Critical constraints section: Calling out AG-UI protocol compatibility, ESM-only, and MSW v2 helps avoid breaking changes.
• Convention for API calls: "Always through src/api/ — never raw fetch/axios in components" is clear and actionable.
• Route addition workflow: Explicitly states to update src/routesConfig.tsx when adding pages.

What was unclear or missing

1. What is dr?

The commands use dr task run but never explain what dr is. Is it a custom CLI tool? Does it need to be installed separately?

Suggested fix: Add to the Commands section:

> **Note**: `dr` is the DataRobot CLI tool. If not installed, run `npm install -g @datarobot/dr-cli` or use the project's local installation.

2. Port numbers and backend dependency

The dev server runs on port 5173, but there's no mention of what port the fastapi_server runs on or how to configure the API base URL.

Suggested fix: Add to Commands or a new "Local Development" section:

## Local Development

- Frontend dev server: `http://localhost:5173`
- Backend API (required): `http://localhost:8000` (default)
- API base URL is configured in `src/api/apiClient.ts`

3. What is the AG-UI protocol?

It's mentioned as critical but never explained. What does it do? What breaks if I violate it?

Suggested fix: Add to Critical constraints:

- **AG-UI protocol**: `src/api/chat/` implements `@ag-ui/client` for streaming chat responses. This protocol must match the server implementation in `fastapi_server/app/ag_ui/`. Do not modify message formats, event types, or streaming handlers without coordinating backend changes.

4. How to add a new API endpoint

The doc says to use src/api/ but doesn't explain the structure. Should I create a new folder? Where do types go? What about hooks?

Suggested fix: Add to Conventions:

- **New API modules**: Create `src/api/<domain>/` with:
  - `types.ts` — request/response types
  - `requests.ts` — API call functions using `apiClient`
  - `hooks.ts` — React Query hooks (useQuery/useMutation)
  - `index.ts` — re-export public API

5. Zustand store location

Global state uses Zustand, but where are the stores defined? Is there a naming convention?

Suggested fix: Add to Key directories/files:

- `src/stores/` — Zustand global state stores (e.g., `useAuthStore.ts`)

6. shadcn/ui component installation

The doc mentions shadcn/ui patterns but doesn't explain how to add new components.

Suggested fix: Add to Conventions or Commands:

- **Adding UI components**: Use `npx shadcn@latest add <component>` to install new shadcn/ui components. They'll be added to `src/components/ui/`.

7. Test file naming and location

"Mirror src/ structure" for tests, but what's the naming convention? *.test.tsx? *.spec.tsx?

Suggested fix: Add to Conventions:

- **Test files**: Use `*.test.tsx` for unit tests, `*.spec.ts` for E2E tests. Unit tests mirror `src/` structure in `tests/`.

8. MSW mock handler update process

It says "update only when API changes" but not how to update them.

Suggested fix: Add to Do NOT modify section:

- `tests/__mocks__/` — MSW mock handlers. Update only when API contracts change:
  1. Add/modify handlers in `tests/__mocks__/handlers/*.ts`
  2. Re-export from `tests/__mocks__/handlers.ts`
  3. Ensure response types match `src/api/*/types.ts`

Commands or instructions that need fixing

1. E2E test command inconsistency

All other commands use dr task run from project root, but E2E tests require cd frontend_web && npm run test:e2e. This is inconsistent.

Suggested fix: Either add a dr task for E2E or explain why it's different:

E2E tests (requires running backend):
```shell
dr task run frontend_web:test:e2e  # if available
# OR
cd frontend_web && npm run test:e2e  # (not wrapped in dr task)

2. Missing test watch mode

Vitest typically has a watch mode for development, but only "single run" is documented.

Suggested fix: Add to Commands:

dr task run frontend_web:test       # vitest (single run)
dr task run frontend_web:test:watch # vitest watch mode

Suggested additions

1. Add a "Quick Start" section

New agents need a fast path to get running:

## Quick Start

1. Install dependencies: `dr task run frontend_web:install`
2. Start backend: `dr task run fastapi_server:dev` (in separate terminal)
3. Start frontend: `dr task run frontend_web:dev`
4. Open `http://localhost:5173`

First time? Check `src/pages/` for existing pages and `src/api/` for API patterns.

2. Add "Common Tasks" section

Concrete examples for frequent operations:

## Common Tasks

**Add a new page:**
1. Create `src/pages/MyPage.tsx`
2. Add route in `src/routesConfig.tsx`
3. Add navigation link if needed

**Add a new API endpoint:**
1. Create `src/api/myDomain/types.ts` with request/response types
2. Create `src/api/myDomain/requests.ts` with API call using `apiClient`
3. Create `src/api/myDomain/hooks.ts` with React Query hooks
4. Update `tests/__mocks__/handlers/myDomain.ts` with mock responses

**Add a new component:**
1. Shared: `src/components/MyComponent.tsx`
2. Page-specific: colocate in `src/pages/MyPage/MyComponent.tsx`
3. Add tests: `tests/components/MyComponent.test.tsx`

3. Add "Debugging" section

## Debugging

- **API calls**: Check Network tab; all requests go through `apiClient.ts`
- **React Query**: Install React Query DevTools (already configured)
- **State**: Zustand DevTools available in browser console
- **Build errors**: Check for CommonJS imports (Vite 7 is ESM-only)

4. Add "File naming conventions"

## File Naming

- Components: PascalCase (`MyComponent.tsx`)
- Hooks: camelCase with `use` prefix (`useMyHook.ts`)
- Types: PascalCase for interfaces/types, camelCase for files (`types.ts`)
- API modules: camelCase folders (`src/api/myDomain/`)
- Tests: Match source file with `.test.tsx` suffix

Overall verdict

NEEDS WORK — The document provides a solid foundation and prevents major mistakes, but has several meaningful gaps that would force an agent to grep the codebase for patterns (API module structure, Zustand store location, shadcn/ui usage) and lacks concrete examples for common tasks.