diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6a46d7b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,48 @@
+# cssnr-vue (cssnr.github.io)
+
+Vue 3 SPA — GitHub Pages org site showcasing CSSNR projects.
+
+## Commands
+
+| Command | Action |
+| ------------------------ | --------------------------------------- |
+| `npm run dev` | Dev server at localhost:5173 |
+| `npm run tsc` | Typecheck via `vue-tsc --build` |
+| `npm run build` | `tsc` then `vite build` (prebuild hook) |
+| `npm run lint` | ESLint 10 with `--cache --fix` |
+| `npm run lint:check` | ESLint read-only |
+| `npm run prettier` | `npx prettier --write .` |
+| `npm run prettier:check` | Prettier read-only |
+
+Run `lint` before `tsc` before `build`. No test framework exists.
+
+## Config & formatting
+
+- ESLint: flat config at `eslint.config.ts` (ESLint 10)
+- Prettier: `.prettierrc.json` — no semis, single quotes, `.vue` printWidth 120, `.js` tabWidth 4
+- Lint CI checks: `lint:check` + `prettier:check` + yamllint + actionlint
+- Path alias `@/` → `src/`
+
+## Architecture
+
+- **No state management (Pinia/Vuex)** — all data is static, imported from `src/config/`
+- `src/config/apps.ts` (~1068 lines) defines 9 categories of ~80+ projects — the site's core data
+- `src/router/index.ts` — 3 routes: `/` (Home), `/about` (lazy), catch-all redirects to `/`
+- Theme: `public/theme.js` (blocking `