From 2dd612805e5874afa4f30149cd331da79deb75fa Mon Sep 17 00:00:00 2001 From: Kurt Overmier Date: Sat, 30 May 2026 12:53:49 -0500 Subject: [PATCH] docs(readme): add npm peer-dependency (ERESOLVE) upgrade guidance (#187) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Installing/upgrading @stackbilt/cli can trip npm's strict peer resolver when the consumer's tree already has a conflicting peer range (e.g. a package peering zod@^4 against Charter's zod@^3). The conflict is consumer-side and Charter's runtime is unaffected once installed. Document both fixes — --legacy-peer-deps for a fast unblock, or aligning the conflicting dependency at its source — and note pnpm/yarn resolve without the flag. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index 6d2243d..8dc7440 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,25 @@ Two distinct issues can appear when the repo lives on a Windows-mounted filesyst Both flags are safe for CI environments where the filesystem is Linux-native — the workarounds only matter locally on DrvFs mounts. +### npm peer-dependency conflicts on install/upgrade + +Installing or upgrading `@stackbilt/cli` can fail under npm's strict peer resolver with an `ERESOLVE` error — for example, a conflict involving `zod` when your app already depends on a package whose peer range differs from Charter's (`zod@^3`): + +```text +npm error ERESOLVE could not resolve +npm error While resolving: your-app@x.y.z +npm error Found: zod@3.x … peer zod@"^4.0.0" from agents@0.12.3 +``` + +This is a conflict in your existing dependency tree that npm surfaces while re-resolving — Charter's runtime is unaffected once installed. Fix it one of two ways: + +| Fix | When | +|-----|------| +| `npm install --save-dev @stackbilt/cli --legacy-peer-deps` | Fastest unblock; tells npm to use the looser legacy resolution it used before v7 | +| Align the conflicting dependency's version in your app (e.g. upgrade/downgrade `zod` so one range satisfies both) | Preferred long-term; removes the conflict at its source | + +`pnpm` and `yarn` use a more permissive resolver and generally install without this flag. + ## AI agent governance with ADF Charter replaces monolithic agent config files (CLAUDE.md, .cursorrules, GEMINI.md) with **ADF (Attention-Directed Format)** -- a modular context system where agents load only the rules they need.