diff --git a/skills/software-development/atproto-development/SKILL.md b/skills/software-development/atproto-development/SKILL.md
index d3fdcf9..b97a96d 100644
--- a/skills/software-development/atproto-development/SKILL.md
+++ b/skills/software-development/atproto-development/SKILL.md
@@ -386,3 +386,40 @@ This keeps the PDS identity separate from the public-facing business domain, pre
 ## References
 
 - `references/did-web-serving.md` — Detailed DID:WEB serving patterns and DNS configuration
+
+## CRA/webpack 5 + @atproto Pitfalls (blank page)
+
+Symptom: deployed CRA app renders a blank page; console shows
+`TypeError: Cannot read properties of undefined (reading 'enum')` thrown during
+module initialization (minified stack module id `79054` = `@atproto/jwk`'s zod
+schema module).
+
+Three separate traps, all real:
+
+1. **Mismatched @atproto generations** — `@atproto/api@^0.13.x` uses
+   `@atproto/lexicon@0.4.x` while newer `@atproto/oauth-client-browser@^0.3.4x`
+   pulls `@atproto/lexicon@0.6.x`. Two lexicon copies in one webpack bundle →
+   `new Lexicons(schemas)` at import time reads `.enum` off an undefined def.
+   Fix: pin a compatible pair, e.g. `@atproto/api@0.13.35` +
+   `@atproto/oauth-client-browser@0.3.30` (both resolve
+   `@atproto/lexicon@0.4.14`). Verify with `npm ls @atproto/lexicon` — must
+   show one deduped version.
+
+2. **zod ≥3.25 dual-build** — zod 3.25.x restructured to `index.cjs` + ESM
+   `index.js` with `./v3`/`./v4` subpaths; webpack 5 (CRA) resolves the wrong
+   entry for CJS `require()` calls, so `z` ends up undefined (`o.z.enum`
+   throws). Fix: pin zod to the proven classic build via
+   `"overrides": {"zod": "3.24.3"}` in package.json (satisfies `^3.23.8`
+   ranges). Verify the page renders in a real browser after deploy — build
+   success alone does NOT catch this (it only shows at runtime).
+
+3. **ESM-only @atproto 0.5x line** — `@atproto/oauth-client-browser@0.5.x`
+   and `@atproto/api@0.20.x` are ESM-only; webpack 5 fails with
+   `Module parse failed: 'import' and 'export' may appear only with
+   'sourceType: module'`. Do not use them with CRA 5 (react-scripts 5.0.1).
+   Keep the 0.3.x/0.13.x CJS line.
+
+Debugging technique that works: install an error catcher before page scripts
+run via CDP `Page.addScriptToEvaluateOnNewDocument` (plain `window.onerror`
+hooks get wiped by reload), then resolve the minified module id against the
+bundle's source map, or grep the bundle for the module id's factory body.