diff --git a/AGENTS.md b/AGENTS.md
index 1c59677..04fab6f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,11 +6,12 @@ Fork of [AnotherRedisDesktopManager](https://github.com/qishibo/AnotherRedisDesk
 
 ## Stack
 
-- **Shell:** Electron 43 (`src/main/index.ts`)
+- **Shell:** Electron 33 (`src/main/index.ts`)
 - **Preload:** `src/preload/index.ts` (contextBridge, typed API)
 - **Renderer:** Vue 3 + Pinia + Element Plus + Vue Router (`src/renderer/src/`)
 - **IPC types:** `src/preload/index.d.ts` (ElectronAPI interface, global Window augmentation)
 - **Build:** electron-vite + Vite 6 + TypeScript 5
+- **Module system:** `"type": "module"` (ESM) — main outputs `.js`, preload outputs `.mjs`
 - **Redis client:** ioredis 5 (main process only)
 - **Persistence:** electron-store + safeStorage (credentials)
 
@@ -207,13 +208,26 @@ Renderer (src/renderer/)
 ## Build config
 
 - `electron.vite.config.ts` defines three build targets: main, preload, renderer
-- Entry points auto-detected: `src/main/index.ts`, `src/preload/index.ts`, `src/renderer/index.html`
-- Build output: `out/main/`, `out/preload/`, `out/renderer/`
+- Entry points auto-detected (zero-config): `src/main/index.ts`, `src/preload/index.ts`, `src/renderer/index.html`
+- Build output: `out/main/index.js`, `out/preload/index.mjs`, `out/renderer/` (index.html + assets/)
+- `package.json` `"main"` points to `./out/main/index.js`
 - electron-builder packages into `release/`
 - Renderer dev server runs on port 5173
 - Main/preload use `externalizeDepsPlugin()` to keep node_modules external
 - `@renderer` alias resolves to `src/renderer/src`
 
+### Runtime paths in main process
+
+`src/main/index.ts` uses `__dirname` (resolved to `out/main/` at runtime) to locate siblings:
+
+| Target | Expression |
+|--------|-----------|
+| Preload script | `join(__dirname, '../preload/index.mjs')` |
+| Renderer HTML | `join(__dirname, '../renderer/index.html')` |
+| App icon | `join(__dirname, '../../build/icons/icon_256.png')` |
+
+If output directory or file extensions change, update these paths accordingly.
+
 ## TypeScript
 
 - Root `tsconfig.json` references `tsconfig.node.json` (main + preload) and `tsconfig.web.json` (renderer)
@@ -232,3 +246,23 @@ Renderer (src/renderer/)
 ## Legacy
 
 The `legacy/` directory contains the old Vue 2 + Webpack 4 codebase. It is gitignored and not part of the v2 build. See `legacy/AGENTS.md` for its documentation.
+
+## Known issues
+
+### Electron binary not installed after `npm install`
+
+The `allowScripts` field in `package.json` blocks electron's postinstall script (`node install.js`), so `npm install` only fetches the npm package without downloading the ~100 MB binary. `npm run dev` then fails with `Error: Electron failed to install correctly` or `spawn ... ENOENT`.
+
+**Fix:** Run the install script manually after `npm install`:
+
+```bash
+node node_modules/electron/install.js
+```
+
+If the download is slow (GitHub releases), use a mirror:
+
+```bash
+ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" node node_modules/electron/install.js
+```
+
+> `package.json` references `scripts/fix-electron.sh` (`npm run fix:electron`) but the script does not exist yet.