diff --git a/AGENTS.md b/AGENTS.md
index f08998e..c449826 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,6 +28,7 @@ Root: `docs` (docs + changelogs), `backend` (Go webui service), `frontend` (node
 - Talks to the backend only over the HTTP APIs in `backend/cmd/webui/api` — no direct infra access (DB, redis) from the browser app.
 - Build output (`dist/`) is disposable and git-ignored; only `src`/`public` are committed.
 - Dev runs from the source mount with `node_modules` provided by the image — install new deps inside the container and commit the lockfile.
+- TypeScript runs side-by-side (`frontend/package.json`): `typescript` = TS 6.0.2 JS API for tooling (typescript-eslint doesn't support TS 7 yet), `@typescript/native` = native 7.0.2 providing `tsc`. Do not re-alias `typescript` to 7.x until typescript-eslint ships TS 7 support. Plain `npm install` needs `--legacy-peer-deps` (also pinned in `frontend/.npmrc`); `npm ci` is unaffected.
 
 ### deploy
 - Only config templates/examples are tracked by git; rendered `*.conf` and `logs/` are git-ignored.
diff --git a/frontend/.npmrc b/frontend/.npmrc
new file mode 100644
index 0000000..521a9f7
--- /dev/null
+++ b/frontend/.npmrc
@@ -0,0 +1 @@
+legacy-peer-deps=true