docs: add AGENTS.md

AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+Bun + TypeScript single-file server that exposes an OpenAI-compatible image
+generation endpoint and serves a small vanilla HTML/JS playground.
+
+## Runtime
+
+- Bun, not Node. See `CLAUDE.md` for the full Bun-vs-Node cheatsheet
+  (prefer `Bun.serve`, `Bun.file`, `bun:test`, `Bun.sql`, etc.). Do not add
+  `dotenv` — Bun loads `.env` automatically.
+- Bun version baseline: `1.3.13` (per `README.md`).
+
+## Commands
+
+- Install: `bun install`
+- Dev (HMR): `bun run dev` → `bun --hot ./index.ts`
+- Start: `bun run start` → `bun ./index.ts`
+- Typecheck: no script defined. Use `bunx tsc --noEmit` (tsconfig already sets
+  `noEmit: true`, so plain `bunx tsc` works too).
+- Tests / lint / formatter: none configured. If adding tests, use `bun test`.
+
+The server binds `0.0.0.0` (see `index.ts:6`), so it is reachable from other
+hosts on the network when running locally — be mindful when entering API keys.
+
+## Architecture
+
+- `index.ts` — the entire backend. One `Bun.serve` instance with:
+  - `/` serves `index.html` via Bun's HTML import (`import index from "./index.html"`).
+  - `POST /api/generate` accepts `{ baseURL, apiKey, model, prompt, size }`,
+    builds an OpenAI-compatible provider with `@ai-sdk/openai-compatible`, and
+    calls `generateImage` from `ai`. Images come back as base64 and are
+    returned as `data:` URLs in `{ images: string[] }`.
+- `index.html` — self-contained UI: inline CSS, plain DOM JS, no build step.
+  Settings (baseURL, apiKey, model, size, prompt) persist in `localStorage`
+  under the `aip:<field>` prefix. There is no React code despite
+  `react` / `react-dom` / `@types/react*` being in `package.json` — treat
+  those deps as latent. Do not invent a React frontend unless asked.
+- No router, no DB, no auth. API key is supplied per-request by the browser
+  and never stored server-side.
+
+## TypeScript conventions
+
+`tsconfig.json` is strict with bundler-mode resolution:
+- `strict`, `noUncheckedIndexedAccess`, `noImplicitOverride`,
+  `noFallthroughCasesInSwitch` are on — array/object index access is
+  `T | undefined` and must be narrowed.
+- `verbatimModuleSyntax` + `moduleDetection: "force"` — use `import type` for
+  type-only imports; every file is a module.
+- `allowImportingTsExtensions` is on; `.ts` extensions in imports are fine.
+- `jsx: "react-jsx"` is set but unused (see frontend note above).
+
+## When extending the API
+
+- Add new routes inside the `routes` object in `index.ts`; keep the
+  `{ POST: async (req) => … }` shape used by `/api/generate`.
+- Return JSON with `Response.json(...)`. Validate the request body shape
+  explicitly — the existing handler asserts required fields and returns 400
+  before calling the model.
+- The AI SDK image type is loose; the current handler casts to
+  `{ mediaType?: string; base64?: string }`. Mirror that pattern rather than
+  trusting field presence.