diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..33dee1f00
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,132 @@
+# Project AIRI Agent Guide
+
+Concise but detailed reference for contributors working across the `moeru-ai/airi` monorepo. Improve code when you touch it; avoid one-off patterns.
+
+## Tech Stack (by surface)
+
+- **Desktop (stage-tamagotchi)**: Electron, Vue, Vite, TypeScript, Pinia, VueUse, Eventa (IPC/RPC), UnoCSS, Vitest, ESLint.
+- **Web (stage-web)**: Vue 3 + Vue Router, Vite, TypeScript, Pinia, VueUse, UnoCSS, Vitest, ESLint. Backend: WIP.
+- **UI/Shared Packages**:
+  - `packages/stage-ui`: Core business components, composables, stores shared by stage-web & stage-tamagotchi (heart of stage work).
+  - `packages/stage-ui-three`: Three.js bindings + Vue components.
+  - `packages/stage-ui-pixi`: Planned Pixi bindings.
+  - `packages/stage-shared`: Shared logic across stage-ui, stage-ui-three, stage-web, stage-tamagotchi.
+  - `packages/ui`: Standardized primitives (inputs, textarea, buttons, layout) built on reka-ui; minimal business logic.
+  - `packages/i18n`: Central translations.
+  - Server channel: `packages/server-runtime`, `packages/server-sdk`, `packages/server-shared` (power `services/` and `plugins/`).
+  - Legacy: `crates/` (old Tauri desktop; current desktop is Electron).
+
+## Structure & Responsibilities
+
+- **Apps**
+  - `apps/stage-web`: Web app; composables/stores in `src/composables`, `src/stores`; pages in `src/pages`; devtools in `src/pages/devtools`; router config via `vite.config.ts`.
+  - `apps/stage-tamagotchi`: Electron app; renderer pages in `src/renderer/pages`; devtools in `src/renderer/pages/devtools`; settings layout at `src/renderer/layouts/settings.vue`; router config via `electron.vite.config.ts`.
+  - Settings/devtools routes rely on `<route lang="yaml"> meta: layout: settings </route>`; ensure routes/icons are registered accordingly (`apps/stage-tamagotchi/src/renderer/layouts/settings.vue`, `apps/stage-web/src/layouts/settings.vue`).
+  - Shared page bases: `packages/stage-pages`.
+  - Stage pages: `apps/stage-web/src/pages`, `apps/stage-tamagotchi/src/renderer/pages` (plus devtools folders).
+- **Stage UI internals** (`packages/stage-ui/src`)
+  - Providers: `stores/providers.ts` and `stores/providers/` (standardized provider definitions).
+  - Modules: `stores/modules/` (AIRI orchestration building blocks).
+  - Composables: `composables/` (business-oriented Vue helpers).
+  - Components: `components/`; scenarios in `components/scenarios/` for page/use-case-specific pieces.
+  - Stories: `packages/stage-ui/stories`, `packages/stage-ui/histoire.config.ts` (e.g. `components/misc/Button.story.vue`).
+- **IPC/Eventa**: Always use `@moeru/eventa` for type-safe, framework/runtime-agnostic IPC/RPC. Define contracts centrally (e.g., `apps/stage-tamagotchi/src/shared`) and follow usage patterns in `apps/stage-tamagotchi/src/main/services/electron` for main/renderer integration.
+- **Dependency Injection**: Use `injeca` for services/electron modules/plugins/frontend; see `apps/stage-tamagotchi/src/main/index.ts` for composition patterns.
+- **Build/CI/Lint**: `.github/workflows` for pipelines; `eslint.config.js` for lint rules.
+- **Bundling libs**: Use `tsdown` for new modules (see `packages/vite-plugin-warpdrive`).
+- **Styles**: UnoCSS config at `uno.config.ts`; check `apps/stage-web/src/styles` for existing animations; prefer UnoCSS over Tailwind.
+
+## Key Path Index (what lives where)
+
+- `packages/stage-ui`: Core stage business components/composables/stores.
+  - `src/stores/providers.ts` and `src/stores/providers/`: provider definitions (standardized).
+  - `src/stores/modules/`: AIRI orchestration modules.
+  - `src/composables/`: reusable Vue composables (business-oriented).
+  - `src/components/`: business components; `src/components/scenarios/` for page/use-case-specific pieces.
+  - Stories: `packages/stage-ui/stories`, `packages/stage-ui/histoire.config.ts` (e.g. `components/misc/Button.story.vue`).
+- `packages/stage-ui-three`: Three.js bindings + Vue components.
+- `packages/stage-ui-pixi`: Planned Pixi bindings.
+- `packages/stage-shared`: Shared logic across stage-ui, stage-ui-three, stage-web, stage-tamagotchi.
+- `packages/ui`: Standardized primitives (inputs/textarea/buttons/layout) built on reka-ui.
+- `packages/i18n`: All translations.
+- Server channel: `packages/server-runtime`, `packages/server-sdk`, `packages/server-shared` (power `services/` and `plugins/`).
+- Legacy desktop: `crates/` (old Tauri; Electron is current).
+- Pages: `packages/stage-pages` (shared bases); `apps/stage-web/src/pages` and `apps/stage-tamagotchi/src/renderer/pages` for app-specific pages; devtools live in each app’s `.../pages/devtools`.
+- Router configs: `apps/stage-web/vite.config.ts`, `apps/stage-tamagotchi/electron.vite.config.ts`.
+- Devtools/layouts: `apps/stage-tamagotchi/src/renderer/layouts/settings.vue`, `apps/stage-web/src/layouts/settings.vue`.
+- IPC/Eventa contracts/examples: `apps/stage-tamagotchi/src/shared`, `apps/stage-tamagotchi/src/main/services/electron`.
+- DI examples: `apps/stage-tamagotchi/src/main/index.ts` (injeca).
+- Styles: `uno.config.ts` (UnoCSS), `apps/stage-web/src/styles` (animations/reference).
+- Build pipeline refs: `.github/workflows`; lint rules in `eslint.config.js`.
+- Tailwind/UnoCSS: prefer UnoCSS; if standardizing styles, add shortcuts/rules/plugins in `uno.config.ts`.
+- Bundling pattern: `packages/vite-plugin-warpdrive` (tsdown example).
+
+## Commands (pnpm with filters)
+
+> Use pnpm workspace filters to scope tasks. Examples below are generic; replace the filter with the target workspace name (e.g. `@proj-airi/stage-tamagotchi`, `@proj-airi/stage-web`, `@proj-airi/stage-ui`, etc.).
+
+- **Typecheck**
+  - `pnpm -F <package.json name> typecheck`
+  - Example: `pnpm -F @proj-airi/stage-tamagotchi typecheck` (runs `tsc` + `vue-tsc`).
+- **Unit tests (Vitest)**
+  - Targeted: `pnpm exec vitest run <path/to/file>`
+    e.g. `pnpm exec vitest run apps/stage-tamagotchi/src/renderer/stores/tools/builtin/widgets.test.ts`
+  - Workspace: `pnpm -F <package.json name> exec vitest run`
+    e.g. `pnpm -F @proj-airi/stage-tamagotchi exec vitest run`
+  - Root `pnpm test:run`: runs all tests across registered projects. If no tests are found, check `vitest.config.ts` include patterns.
+  - Root `vitest.config.ts` includes `apps/stage-tamagotchi` and other projects; each app/package can have its own `vitest.config`.
+- **Lint**
+  - `pnpm lint` and `pnpm lint:fix`
+  - Formatting is handled via ESLint; `pnpm lint:fix` applies formatting.
+- **Build**
+  - `pnpm -F <package.json name> build`
+  - Example: `pnpm -F @proj-airi/stage-tamagotchi build` (typecheck + electron-vite build).
+
+## Styling & Components
+
+- Prefer UnoCSS class arrays/attributes for readability: `:class="['px-2','py-1','flex','items-center','bg-white/50','dark:bg-black/50']"`; avoid long inline `class=""`. Refactor legacy when you touch it; prefer attributes/arrays over inline Tailwind blobs.
+- Use/extend UnoCSS shortcuts/rules in `uno.config.ts`; add new shortcuts/rules/plugins there when standardizing styles. Prefer UnoCSS over Tailwind.
+- Check `apps/stage-web/src/styles` for existing animations; reuse or extend before adding new ones. If you need config references, see `apps/stage-web/tsconfig.json` and `uno.config.ts`.
+- Build primitives on `@proj-airi/ui` (reka-ui) instead of raw DOM; see `packages/ui/src/components/Form` for patterns.
+- Use Iconify icon sets; avoid bespoke SVGs.
+- Animations: keep intuitive, lively, and readable.
+- `useDark` (VueUse): set `disableTransition: false` or use existing composables in `packages/ui`.
+
+## Testing Practices
+
+- Vitest per project; keep runs targeted for speed.
+- Mock IPC/services with `vi.fn`/`vi.mock`; do not rely on real Electron runtime.
+- For external providers/services, add both mock-based tests and integration-style tests (with env guards) when feasible. You can mock imports with Vitest.
+- Grow component/e2e coverage progressively (Vitest browser env where possible). Use `expect` and assert mock calls/params.
+
+## TypeScript / IPC / Tools
+
+- Keep JSON Schemas provider-compliant (explicit `type: object`, required fields; avoid unbounded records).
+- Favor functional patterns + DI (`injeca`); avoid new class hierarchies unless extending browser APIs (classes are harder to mock/test).
+- Centralize Eventa contracts; use `@moeru/eventa` for all events.
+
+## i18n
+
+- Add/modify translations in `packages/i18n`; avoid scattering i18n across apps/packages.
+
+## CSS/UNO
+
+- Use/extend UnoCSS shortcuts in `uno.config.ts`.
+- Prefer grouped class arrays for readability; refactor legacy inline strings when possible.
+
+## Naming & Comments
+
+- File names: kebab-case.
+- Avoid classes unless necessary for browser API extensions; FP + DI is easier to test/mock.
+- Avoid stubby/hacky scaffolding; prefer small refactors that leave code cleaner.
+- Use markers:
+  - `// TODO:` follow-ups
+  - `// REVIEW:` concerns/needs another eye
+  - `// NOTICE:` magic numbers, hacks, important context, external references/links
+
+## PR / Workflow Tips
+
+- Rebase pulls; branch naming `username/feat/short-name`; clear commit messages (gitmoji optional).
+- Summarize changes, how tested (commands), and follow-ups.
+- Improve legacy you touch; avoid one-off patterns.
+- Keep changes scoped; use workspace filters (`pnpm -F <workspace> <script>`).