# AGENTS.md – Repository Quick‑Start Guide

**Purpose**: Give OpenCode agents the exact commands and conventions they need to work safely and efficiently in the *AITrader* codebase. Only include items that are easy to miss without explicit guidance.

---

## Project structure

- `app/routes/` – React Router 7 file-based routes (`landing.tsx` is the index/home page)
- `app/components/` – Shared React components
- `app/routes.ts` – Route definitions (uses `index` and `route` helpers from `@react-router/dev/routes`)
- `app/root.tsx` – Root layout with global HTML shell, Links, Meta, Scripts
- `app/app.css` – Global styles (Tailwind is configured via Vite)
- `tests/` – Playwright E2E tests
- `vitest.config.ts` / `vitest.setup.ts` – Unit test config (Vitest)
- `vite.config.ts` – Vite config with Tailwind and React Router plugins
- `react-router.config.ts` – React Router framework config
- `tsconfig.json` – TypeScript config (ES modules: `"type": "module"`)

## Core npm scripts (run from the repository root)

- `npm run dev` – Starts the dev server with HMR via **react-router dev**. Served at `http://localhost:5173`.
- `npm run build` – Produces a production build using **react-router build**. Output lives in `./build` with `client/` and `server/`.
- `npm start` – Serves the production bundle with `react-router-serve ./build/server/index.js`. Requires a prior `npm run build`.
- `npm run typecheck` – Runs **react-router typegen** then `tsc`. Must be run before committing TypeScript changes.
- `npm run test:e2e` – Runs Playwright E2E tests (server starts automatically via `playwright.config.ts`).

## Development workflow

1. **Install deps** – `npm install` (first time only).
2. **Start dev** – `npm run dev`. Changes are hot-reloaded; no manual restart.
3. **Iterate** – Edit files under `app/` (routes, components, loaders, actions).
4. **Validate** – Run `npm run typecheck` regularly; it catches missing typegen steps.
5. **E2E tests** – `npm run test:e2e` (Playwright handles server startup).
6. **Build & serve** – `npm run build && npm start`.

## Routing (React Router 7)

- `index()` routes render into the parent `<Outlet />` at the parent's path.
- `route(segment, file)` creates an explicit path segment.
- The landing page is `index("routes/landing.tsx")` — it is the default page at `/`.
- Do **not** use multiple `index()` routes at the same nesting level — only one is allowed per level.
- All route files export `meta()` for `<title>` and `<meta>` tags, and a default export component.

## TypeScript nuances

- The `typecheck` script runs **react-router typegen** first; agents must not skip this step because generated types are required for successful compilation.
- The project uses ES modules (`"type": "module"`). Import paths should include file extensions (`.js`, `.ts`) where Node requires them.
- Route types are generated — use `import type { Route } from "./+types/<route-name>"` for type-safe loaders/actions.

## TailwindCSS

- Configured via Vite (`@tailwindcss/vite`). No extra build steps needed; the dev server and production build automatically process Tailwind classes.
- Use arbitrary values and `className` composition freely.

## Playwright E2E testing

- Config: `playwright.config.ts` in the repo root.
- The web server starts automatically (`npm run dev` on port 5173) before tests run.
- Tests live in `tests/` directory.
- Generate the report with: `npm run test:e2e -- --reporter=html` (output in `test-results/`).
- To run tests in headed mode for debugging, set `headless: "false"` in `playwright.config.ts` or pass `--headed`.
- To debug a single test: `npx playwright test tests/<file-name>.spec.ts`.

## Playwright MCP Server

An MCP (Model Context Protocol) server provides Playwright browser automation to AI assistants.

- **Start MCP server**: `npm run mcp:dev` (runs via stdio, connects to AI clients)
- **Build MCP server**: `npm run mcp:build` (compiles to `mcp-server/dist/`)

Available tools:
- `navigate` - Navigate to a URL and get page title
- `getPageContent` - Get text content from a page
- `click` - Click an element by CSS selector
- `fillForm` - Fill a form input

## Alpaca API Setup

- Copy `.env.example` to `.env` and fill in your Alpaca credentials:
  - `ALPACA_API_KEY` – Your Alpaca API key
  - `ALPACA_SECRET_KEY` – Your Alpaca secret key
  - `ALPACA_BASE_URL` – API endpoint (default: paper trading URL)
- The `.env` file is gitignored – never commit credentials.
- Account data is fetched from `/api/alpaca/account` and displayed on the landing page.

## Design Guidelines

**Layout & Structure:**
- All routes use gradient background: `<div className="min-h-screen bg-gradient-to-br from-gray-50 to-blue-50">`
- Use `<Navbar />` component at the top of every page (sticky, with backdrop blur)
- Content container: `<div className="mx-auto max-w-7xl px-6 sm:px-8 lg:px-8">`

**Navbar:**
- Use the shared `Navbar` component from `app/components/Navbar.tsx`
- Logo: blue-600 rounded square with white "A", text "AITrader" in gray-900 with hover effect
- Links have underline animation on hover

**Color Palette:**
- Background: `bg-gradient-to-br from-gray-50 to-blue-50` for pages, `bg-white` for cards
- Text: `text-gray-900` for headings, `text-gray-600` for secondary
- Accent colors for account values: `text-green-600` (Cash), `text-blue-600` (Buying Power), `text-purple-600` (Portfolio Value)
- Error: `text-red-600` for error messages

**Components:**
- Cards: `bg-white rounded-xl shadow-lg p-6 border border-gray-200`
- Buttons: `bg-blue-600 text-white px-6 py-2.5 rounded-lg font-medium hover:bg-blue-700 transition-colors`
- Inputs: `border border-gray-300 rounded-lg px-4 py-2.5 focus:ring-2 focus:ring-blue-500`

**Typography:**
- Page headings: `text-4xl font-bold text-gray-900`
- Section headings: `text-xl font-bold text-gray-900`
- Card titles: `text-xl font-bold text-gray-900`

## Common pitfalls agents might miss

- **Running the server without a build** – `npm start` will fail if `npm run build` hasn't been executed first.
- **Skipping typegen** – Directly running `tsc` without the preceding `react-router typegen` results in missing type definitions.
- **Multiple index routes at same level** – React Router 7 only allows one `index()` per nesting level. Use `route()` for additional paths.
- **Port assumptions** – Dev server runs on `5173`; production server (Docker) defaults to `3000` unless overridden.
- **Route file naming** – Route files must match the pattern `app/routes/<name>.tsx` and the corresponding type file at `app/routes/+types/<name>.ts` if types are needed.
- **Import paths** – Use `react-router` for framework imports (`Link`, `Outlet`), not `@remix-run/react`.

---

*Keep this file up‑to‑date as scripts or tooling evolve.*