docs: add Ready Set Ride system overview and conventions

AGENTS.md

@@ -3,3 +3,40 @@
 
 This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
 <!-- END:nextjs-agent-rules -->
+
+# Ready Set Ride
+
+「展件互動系統」的 iPad 端控制介面。三組「電腦＋螢幕＋iPad」在展場區網內，民眾透過 iPad（PWA）操控 Unity 螢幕內容，流程結束後上傳圖片至客戶 FTPS，並以 QR Code 顯示對應圖片網址供掃描。
+
+完整的系統架構、網路 / TLS、MQTT topic 設計、Windows 部署與開工檢查清單請見 **[docs/architecture.md](docs/architecture.md)**（單一事實來源，動到部署 / MQTT / 上傳流程前先讀）。
+
+## Stack
+
+- **Next.js 16 (Turbopack)** + React 19，App Router，`src/` 目錄。`output: 'standalone'`（Windows 上以 `node server.js` 跑，非 `next start`）。
+- **Bun** 為套件管理與 script runner（`bun run dev` / `bun run build`）。
+- **PWA**：`@serwist/turbopack`（service worker，非 `@serwist/next`）。
+- **MQTT**：`mqtt.js` over WebSocket（`useMQTT` hook）。
+- **狀態**：`zustand` + `persist`（裝置設定，如 station id）。
+- **樣式**：Tailwind v4 + shadcn（style `base-nova`，icon `lucide`）。
+- **驗證**：`zod` v4（import 為 `import * as z from 'zod'`）。
+- **圖片上傳**：`basic-ftp`（implicit FTPS）。
+
+## Commands
+
+- `bun run dev` — 開發伺服器
+- `bun run build` — production build
+- `bun run lint` — Biome check
+- `bun run format` — Biome format（write）
+
+## Conventions
+
+- 路徑別名 `@/*` → `./src/*`。元件 `@/components`、UI `@/components/ui`、hooks `@/hooks`、lib `@/lib`。
+- **Biome** 為唯一 formatter / linter：2 空格縮排、**single quotes**、import 自動排序。`src/components/ui`（shadcn 產出）不在 format / lint 範圍內，勿手動改它的風格。
+- Next.js domain rules（`next` / `react`）已在 Biome 開啟，遵守其提示。
+
+## Gotchas
+
+- **`src/` 目錄**：所有 app code 在 `src/` 下。serwist 的 `swSrc` 等以「專案根目錄」為基準的路徑要寫成 `src/app/sw.ts`，不是 `app/sw.ts`（後者會在 build collect page data 階段報 `Could not resolve .../app/sw.ts`）。
+- **FTPS 必須跑在 Node runtime，不能用 Bun**：此 FTPS server 在 data connection 上要求 TLS session resumption，Bun 不支援。涉及 `src/lib/ftps.ts` 的 Server Action / script 一律標 Node runtime（standalone 預設即 Node，勿標 edge）。
+- FTPS 設定由環境變數載入（`FTP_HOST` / `FTP_USER` / `FTP_PASSWORD` 必填，`FTP_PORT`/`FTP_REMOTE_DIR`/`FTP_PUBLIC_BASE_URL` 選填），見 `loadFtpConfig()`。勿把帳密寫死進程式碼。
+- **Windows host**：路徑用 `path` API，勿寫死 POSIX 斜線。