Add initial documentation and configuration files for AITrader project

2026-05-12 19:50:16 +02:00
parent 818e179fd0
commit aaafe8fa3f
12 changed files with 391 additions and 0 deletions
@@ -0,0 +1,44 @@
+# 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.*