docs(nx): document coordinated dependency updates

AGENTS.md

@@ -16,6 +16,12 @@ This file provides guidance to coding agents working in this repository.
 - Use scoped path aliases from `tsconfig.base.json` such as `@iptvnator/services`, `@iptvnator/shared/interfaces`, and `@iptvnator/ui/components`. Do not add new imports from legacy bare aliases such as `services`, `shared-interfaces`, `components`, `m3u-state`, or `database`.
 - Every Nx project should keep `scope:*`, `domain:*`, and `type:*` tags in `project.json` so `@nx/enforce-module-boundaries` remains useful for humans and agents.
 - See `docs/architecture/nx-workspace-boundaries.md` for the current Nx tag and alias policy.
+- Keep `nx` and every official `@nx/*` package on the same exact version; run
+  `pnpm run deps:nx:validate` after dependency updates.
+- Update Nx with `pnpm nx migrate nx@<target> --skipInstall`, regenerate the
+  lockfile, run generated migrations when present, and validate before opening
+  a PR. Major updates are always manual. Replace incomplete Dependabot security
+  PRs with a coordinated update instead of editing the bot branch.
 - ESLint enforces `max-lines` on TypeScript files: production code targets under 300 with a hard maximum of 400, while tests (`**/*.spec.ts`, `**/*.e2e.ts`, `apps/*-e2e/**`) are held to 1200 — a long spec signals coverage, not the design debt the production limit catches. Blank lines and comments are not counted, so a docblock never forces a split. Limits live in `tools/eslint/max-lines-config.mjs`, imported by both `eslint.config.mjs` and the generator so the rule and the baseline cannot drift. Files that predate the rule are baselined in `tools/eslint/max-lines-baseline.mjs`; after splitting a file, regenerate it with `node tools/eslint/generate-max-lines-baseline.mjs` (it runs ESLint's own rule rather than counting lines itself). Never add new files to the baseline — the list must only shrink. A new file that genuinely cannot be split (for example a function serialized into another process) instead carries its own file-wide `/* eslint-disable max-lines -- <why> */`; the generator skips those files, so a justified exemption never lands in the baseline. Remove such a directive once ESLint reports it as unused.
 - Project `lint` targets that shell out to eslint must quote the glob, e.g. `eslint "apps/<project>/**/*.ts"`. An unquoted `**` is expanded by the POSIX shell on Linux and macOS (which has no `globstar`, so it matches only a shallow subset of files) while Windows passes the literal pattern to ESLint, which expands it recursively — the two hosts then lint different file sets. The target still reports success either way, so a broken glob hides missing coverage instead of failing. After changing such a target, compare the linted file count against `find <project> -name '*.ts' | wc -l`.
 - Repository-specific skills live under `.codex/skills/`.

CLAUDE.md

@@ -74,6 +74,12 @@ pnpm nx show projects
 - Do not add new imports from legacy bare aliases such as `services`, `shared-interfaces`, `components`, `m3u-state`, or `database`.
 - Every Nx project should keep `scope:*`, `domain:*`, and `type:*` tags in `project.json`.
 - See `docs/architecture/nx-workspace-boundaries.md` for the current Nx tag and alias policy.
+- Keep `nx` and every official `@nx/*` package on the same exact version; run
+  `pnpm run deps:nx:validate` after dependency updates.
+- Update Nx with `pnpm nx migrate nx@<target> --skipInstall`, regenerate the
+  lockfile, run generated migrations when present, and validate before opening
+  a PR. Major updates are always manual. Replace incomplete Dependabot security
+  PRs with a coordinated update instead of editing the bot branch.
 - Repository-specific skills live under `.codex/skills/`.
 - Frontmatter descriptions are trigger-only and begin with `Use when`; keep
   each skill at or below 500 words.

docs/architecture/nx-workspace-boundaries.md

@@ -27,6 +27,29 @@ Do not invent a `test`, `build`, or `e2e` target because a similarly named
 project has one. Run affected lint/test/build targets that exist and the closest
 available E2E target for the changed behavior.
 
+## Nx Dependency Updates
+
+Keep `nx` and every official `@nx/*` package on the same exact version. Run
+`pnpm run deps:nx:validate` after any manifest or lockfile update; CI runs the
+same policy check and rejects both direct specifier drift and multiple resolved
+Nx versions.
+
+Dependabot groups routine minor and patch Nx updates when possible. A security
+update may still contain only the vulnerable package, so replace an incomplete
+Dependabot PR with a coordinated maintainer update instead of editing the bot
+branch:
+
+```bash
+pnpm nx migrate nx@<target> --skipInstall
+pnpm install --no-frozen-lockfile
+pnpm nx migrate --run-migrations
+pnpm run deps:nx:validate
+```
+
+Omit `pnpm nx migrate --run-migrations` when the first command reports that no
+migrations exist. Major Nx updates always use this manual workflow and the
+resulting PR runs the full CI pipeline.
+
 ## Placement Decision
 
 - `apps/` owns runtime applications, development servers, E2E applications,