diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7b467cd
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,37 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/main.ts` bootstraps the Vue app, mounts `App.vue`, and registers Pinia + router.
+- `src/App.vue` hosts the layout shell; global theme styles live in `src/assets/main.css`.
+- `src/pages` holds route-level views (e.g., `HomePage.vue`), wired in `src/router/index.ts`.
+- `src/components` contains shareable UI (`Randomizer.vue`); aim to keep these presentational.
+- `src/stores` stores state and side effects (e.g., `randomData.ts` for `/api/randomize` and localStorage prefs); static datasets sit in `src/data`.
+- `public` serves static assets as-is; `vite.config.ts` configures aliases (`@` → `src`) and plugins.
+
+## Build, Test, and Development Commands
+- `npm run dev` — start Vite dev server with hot reload.
+- `npm run build` — type-check via `vue-tsc`, then produce the production bundle.
+- `npm run build-only` — production bundle without type-check (useful for quick iteration).
+- `npm run preview` — serve the built assets locally to verify production output.
+- `npm run type-check` — standalone TS/SFC type validation.
+
+## Coding Style & Naming Conventions
+- Vue 3 + TypeScript with `