# 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.

---

## Core npm scripts (run from the repository root)
- `npm run dev` – Starts the development server with hot‑module replacement via **react‑router dev**. The app is served at `http://localhost:5173`.
- `npm run build` – Produces a production build using **react‑router build**. Output lives in `./build` with `client/` (static assets) and `server/` (Node entry point).
- `npm start` – Serves the built server bundle with **react‑router-serve ./build/server/index.js**. Use after `npm run build`.
- `npm run typecheck` – Runs **react‑router typegen** then `tsc`. Must be run before committing any TypeScript changes.

## Development workflow
1. **Install deps** – `npm install` (first time only).
2. **Start dev** – `npm run dev`. Changes are hot‑reloaded; no manual restart needed.
3. **Iterate** – Edit files under `src/` (React components, routes, loaders, actions, etc.).
4. **Validate** – Run `npm run typecheck` regularly; it catches missing typegen steps.
5. **Build & serve** – When ready for a preview:
   ```bash
   npm run build && npm start
   ```
   This uses the production‑ready server (`@react-router/serve`).

## Docker deployment (optional)
- Build image: `docker build -t aitrader .`
- Run container: `docker run -p 3000:3000 aitrader`
- The container expects the app to be built; include `npm run build` in your Dockerfile before the final `CMD`.

## 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.

## TailwindCSS
- Tailwind is configured via Vite (`@tailwindcss/vite`). No extra build steps are needed; the dev server and production build automatically process Tailwind classes.

## 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.
- **Assuming a `test` script exists** – This repository has no test suite; any `npm test` command will error.
- **Port assumptions** – Development server runs on `5173`; production server (Docker) defaults to `3000` unless overridden.

---

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