chore: consolidate shared toolchain devDependencies into the root package.json

.claude/skills/local-dev/SKILL.md

@@ -152,6 +152,93 @@ renderer with a React it was not installed against, which is the same split the
 pin exists to prevent, arrived at from the other side. `dedupe` still collapses
 each install to one copy, which is what actually has to hold.
 
+### Why the shared toolchain is root-only
+
+Every client's `validate` shells out to `prettier`, `eslint`, `tsc` and `vitest`,
+which makes them look like they belong beside the scripts that call them. They
+do not need to be: `npm run` prepends **every ancestor** `node_modules/.bin` to
+`PATH`, and Node and TypeScript walk parent `node_modules` /
+`node_modules/@types` the same way — so a client that declares no toolchain at
+all still resolves the root's copy. `clients/launcher` declares no
+`devDependencies` whatsoever and its `validate` is unchanged.
+
+What a per-client declaration *does* buy is a second copy free to drift, and it
+had (#2196): `globals` sat at `^17.7.0` at the root against `^17.4.0` in all four
+clients, and `typescript-eslint` at `^8.65.0` against `^8.56.1`. Nothing failed —
+which is the point. A lint or format tool that differs per client makes the gate's
+verdict a function of *where you ran it*, and the exact `prettier` pin (#1790)
+only means something when there is one of it.
+
+⚠️ The line is **used by every client**, not "used by one" and not "is it
+toolchain". `tsx`, `playwright`, `storybook`, `happy-dom`, `ink-testing-library`,
+`vite-node` and each client's own `@types/*` are toolchain too and stay where
+they are — hoisting them would make every client install the union of all four.
+So do the ones **more than one** client declares without all of them doing so:
+`tsup` sits in web, cli and tui, and `vite` in web and tui on top of the root
+*runtime* `dependency` that `--web --dev` needs. Neither is in scope here;
+whether to consolidate them is a separate call with a separate rationale (`vite`
+especially, since its root declaration is a `dependency`, not a
+`devDependency`).
+
+#### What the walk-up does *not* buy you
+
+⚠️ **Deleting a client's declaration does not always delete the copy** — and
+where a copy survives, it is the one that wins. Two mechanisms put one back,
+neither of which the manifest mentions:
+
+- **An unmet peer.** npm auto-installs a peer into the install that needs it, and
+  a client install has no visibility into the root's tree, so the root's copy
+  cannot satisfy it. Web's `eslint-plugin-react-refresh` / `eslint-plugin-storybook`
+  and the TUI's `eslint-plugin-react-hooks` each pull a client-local `eslint`;
+  web's Storybook/Vitest stack pulls a local `typescript` and `vitest`.
+- **A hoisted transitive.** `@types/express` brings `@types/node` into web and
+  cli's trees on its own.
+
+Those copies sit *nearer* than the root's, so `clients/web/node_modules/.bin`
+precedes the root bin directory on `PATH` and TypeScript resolves the nearest
+`node_modules/@types`. Verify with `npm exec -- which eslint` from the client
+rather than assuming — the assumption is what made the first cut of #2196 claim
+more than it delivered (Copilot).
+
+So the consolidation buys **one declaration and one place to bump**, not one copy
+on disk. The two mechanisms are **not** equally safe, and neither is a guarantee:
+
+- A **peer** copy is at least constrained by its holder's peer range. That is a
+  real pin only when the range is exact — `@vitest/browser-playwright` pins
+  `vitest` to a single version, which is why the trio below is pinned too. For a
+  wide range (`eslint-plugin-react-refresh` accepts `^9 || ^10`) the copies agree
+  only because npm happens to resolve the same latest in both installs, which is
+  a coincidence that holds until it doesn't.
+- A **transitive** copy is constrained by nothing of ours whatsoever, and one has
+  already diverged: cli's `@types/node` is `24.13.1` against the root's
+  `24.13.3`, and was `24.13.1` on `v2/main` too — a declared `^24.12.4` loses to
+  a nearer transitive.
+
+⚠️ **Nothing gates either of those, and `verify:dep-lockstep` is not it.**
+That guard derives its candidate set from what each `tsc` **program** resolves
+(see below), so it sees only packages a program loads from two installs. A tool
+*binary* — `eslint`, `prettier`, `vitest` — never enters a program, so it is
+outside the candidate set no matter how far it drifts, and the cli `@types/node`
+skew above passes for a second reason on top of that: no one program sees both
+copies. When you change what a client declares, check by hand from that client:
+
+```sh
+cd clients/web && npm exec -- which eslint prettier tsc vitest
+```
+
+#### Why the vitest trio is pinned exactly
+
+`@vitest/browser-playwright` declares an **exact** peer on `vitest` (`"vitest":
+"4.1.10"`, not a range), so that package — not the root's range — decides which
+`vitest` lands in `clients/web`. Left floating, the root resolves the newest
+patch while web's peer stays pinned to the older one, and web's tests then run on
+one `vitest` while loading a `@vitest/coverage-v8` provider built against
+another. Both would still pass, which is the bad part.
+
+So `vitest` and `@vitest/coverage-v8` at the root and `@vitest/browser-playwright`
+in `clients/web` are all pinned **exactly**, and a bump edits all three in one
+change — the same discipline as the exact `prettier` pin (#1790).
+
 ### Why runtime consumption decides `dependencies`
 
 The client builds externalise npm packages, so a published install resolves them

AGENTS.md

@@ -90,6 +90,9 @@ The reasoning behind each of these, and what breaks when it is ignored, is the
 - **A client declares only what that client alone consumes** — its own UI stack, its bundler-inlined packages, its dev tooling. `clients/cli` and `clients/launcher` therefore declare **no** runtime dependencies at all, and that is the expected steady state, not an omission: everything they run on is root-declared and resolves by walk-up from the client directory. Re-adding a root-declared package to a client manifest re-creates the second copy this rule exists to make impossible (#1896), so a missing module at runtime is a signal to check the **root** manifest and the client's `external` list, never to add it back.
 - **A package that moves to the root moves its `vitest.shared.mts` pin with it.** Left pointing at `<client>/node_modules` a pin resolves to a directory that no longer exists — or, where a transitive copy happens to sit there (`chokidar` under `vite`, `react` as a peer of `react-dom` and `ink`), to the very duplicate the pin list exists to prevent. **`react` and `react-dom` are the deliberate exception** and stay pinned per client, so a client's renderer and the React it calls into come from one install; every other root-owned pin resolves from the repo root.
 - **`dependencies` vs `devDependencies` follows from who consumes it at runtime**, not from where it is declared. Anything `core/` imports at runtime must be a root **`dependency`** — the client builds externalize npm packages and a published install resolves them from the root manifest, where devDependencies are absent.
+- **The shared toolchain is declared once, at the repo root, and in no client manifest.** `eslint`, `@eslint/js`, `typescript-eslint`, `globals`, `prettier`, `typescript`, `vitest`, `@vitest/coverage-v8` and `@types/node` are used by every client's own scripts, and a client that declares none of them still resolves the root copy by walk-up — `npm run` puts each ancestor `node_modules/.bin` on `PATH`, and Node and TypeScript walk parent `node_modules` / `node_modules/@types` the same way. `clients/launcher` declares no `devDependencies` at all and its `validate` is unchanged. A client-side declaration buys nothing and installs a second copy free to drift, as `globals` (`^17.7.0` root / `^17.4.0` clients) and `typescript-eslint` (`^8.65.0` / `^8.56.1`) had before #2196. These stay **`devDependencies`** — none is consumed at runtime and the tarball ships only each client's `build/`. The boundary is **used by every client**, not "used by one": anything narrower stays where it is, whether one client declares it (`tsx`, `playwright`, `storybook`, `happy-dom`, `ink-testing-library`, `vite-node`, each client's own `@types/*`) or several do — `tsup` is declared in web, cli and tui, and `vite` in web and tui on top of the root **runtime** `dependency` that `--web --dev` needs. Those are out of scope here; consolidating them is a different call with a different rationale.
+  - ⚠️ **Deleting the declaration does not always delete the copy, and the local copy still wins.** npm auto-installs an unmet **peer** into the install that needs it, and it has no visibility into the root's tree — so a client-only ESLint plugin drags a client-local `eslint` in (`eslint-plugin-react-refresh`/`-storybook` in web, `eslint-plugin-react-hooks` in tui), and web's Storybook/Vitest stack drags in a local `typescript` and `vitest`. A hoisted transitive does the same: `@types/express` puts an `@types/node` in web and cli. Those copies sit *nearer* than the root's and take precedence. The consolidation is therefore about **one declaration and one place to bump**, not about a single copy on disk. ⚠️ **Nothing keeps the surviving copies aligned, and nothing gates them.** A **peer** copy is at least constrained by its holder's peer range — tightly for `vitest` (an exact peer, hence the pin below), loosely for `eslint` (`^9 || ^10`), where the copies agree only because npm resolves the same latest in both installs. A **transitive** copy is constrained by nothing of ours at all, and cli's `@types/node` (`24.13.1` against the root's `24.13.3`) has already diverged on exactly that. `verify:dep-lockstep` does not catch either: it compares only packages that one `tsc` **program** loads from two installs, so a stray `eslint`, `prettier` or `vitest` binary is outside its candidate set entirely, and the cli `@types/node` difference goes unreported because no one program sees both copies. Check a tool copy by hand — `npm exec -- which eslint` from the client — when you change what a client declares.
+  - ⚠️ **`vitest`, `@vitest/coverage-v8` and web's `@vitest/browser-playwright` are pinned exactly, and move together.** `@vitest/browser-playwright` declares an **exact** peer on `vitest`, so it — not the root range — decides which `vitest` web installs. Left to float, the root resolves a newer patch and web's tests then run on one `vitest` while loading a coverage provider built against another. Bumping means editing all three in one change, the same discipline the exact `prettier` pin (#1790) exists for.
 - **A root-declared package that `core/` imports at runtime must also be named in all three bundler `external` lists** (`clients/{cli,tui}/tsup.config.ts`, `clients/web/tsup.runner.config.ts`), since which client reaches it is a function of what `core/` imports rather than of what the client's own code names. `npm run verify:bundle-externals` enforces this against the **built output**.
 - **A dependency that renders React components must be bundled** into the client that uses it (`noExternal`) and declared only there — an externalized one resolves its own `react` and splits the tree. `ink` is the single exemption, on cost, and it is only safe while the root `react` range stays open to the whole major (`^19.0.0`).
 - **One version per install-crossing dependency.** When bumping a dependency the shared sources pull in, bump it in every install that declares it. Consolidating to the root is what makes most of these unbumpable in two places at once, but it does not retire the rule — a client's `devDependencies`, and any package that arrives transitively into a client install, can still skew against the root. Never raise the tsc heap to work around one. `npm run verify:dep-lockstep` enforces this.