diff --git a/content/docs/deployment/self-hosting.mdx b/content/docs/deployment/self-hosting.mdx
index e4262a0a00c..61f911d836b 100644
--- a/content/docs/deployment/self-hosting.mdx
+++ b/content/docs/deployment/self-hosting.mdx
@@ -168,7 +168,14 @@ image)? The official image is nothing more than:
```dockerfile title="Dockerfile (self-built runtime, equivalent)"
FROM node:22-slim
-RUN npm install -g @objectstack/cli@17.7.0
+# node:22-slim ships npm 10, which fails this install with "reading 'edgesOut'"
+# (see Troubleshooting). Install under a pinned npm 11, deleted in the same layer.
+RUN npm install --prefix /tmp/os-installer-npm --no-save --no-audit --no-fund "npm@11.21.0" \
+ && export PATH="/tmp/os-installer-npm/node_modules/.bin:$PATH" \
+ && test "$(npm --version)" = "11.21.0" \
+ && npm install -g @objectstack/cli@17.7.0 "pg@^8.0.0" "mysql2@^3.0.0" \
+ && npm cache clean --force \
+ && rm -rf /tmp/os-installer-npm
WORKDIR /srv/app
RUN chown node:node /srv/app
@@ -355,8 +362,14 @@ configuration-management estate already owns process supervision, or when you
are debugging directly on the box. It needs Node 22+ and the CLI on a Linux
host, and nothing else.
+Install the CLI with npm 11. npm 10, the npm that Node 22 ships, fails with
+`Cannot read properties of null (reading 'edgesOut')`, and a global install
+reads no `overrides`, so upgrading npm is the only fix here
+([Troubleshooting](/docs/deployment/troubleshooting#cannot-read-properties-of-null-reading-edgesout-from-npm-install)).
+
```bash
# On the host — no repo clone, just the CLI and your artifact
+npm install -g npm@11 # npm 11 needs Node 22.9+
npm install -g @objectstack/cli
npm install -g pg # Postgres driver is an optional peer of @objectstack/driver-sql —
# install it next to the CLI, or the boot fails loudly (use mysql2 for OS_DATABASE_URL=mysql://…)
diff --git a/content/docs/deployment/troubleshooting.mdx b/content/docs/deployment/troubleshooting.mdx
index 0bfac4957ba..8777b802677 100644
--- a/content/docs/deployment/troubleshooting.mdx
+++ b/content/docs/deployment/troubleshooting.mdx
@@ -8,6 +8,27 @@ Solutions to the most common issues encountered when working with ObjectStack.
---
+## Installation Issues
+
+### "Cannot read properties of null (reading 'edgesOut')" from npm install
+
+**Symptom:** npm exits 1 with `npm error Cannot read properties of null (reading 'edgesOut')` while installing `@objectstack/cli` or `@objectstack/plugin-auth`. This includes the install step of `npm create objectstack` and `npm install -g @objectstack/cli`.
+
+**Cause:** npm 10, the npm that Node 22 ships, crashes on an optional `vitest` peer in the auth library's dependency tree: the newest vitest 4 has no matching `@vitest/browser-webdriverio` release. npm 11 and pnpm install the same packages, and `npm ci` from a committed lockfile is not affected.
+
+**Fix** (either one):
+
+1. **Use npm 11** (it needs Node 22.9+): run `npm install -g npm@11`, then repeat the install. This is the only fix for `npm install -g`, because a global install reads no `overrides`. In a Dockerfile, install under a pinned npm 11, as the [self-built runtime recipe](/docs/deployment/self-hosting#docker-official-image--the-standard-path) does.
+2. **Stay on npm 10 and pin vitest** in your project's root `package.json`. Then run `npm install` again and commit the lockfile:
+
+ ```json title="package.json"
+ "overrides": { "vitest": "~4.0.0" }
+ ```
+
+This entry, the npm 11 steps in [Self-hosting](/docs/deployment/self-hosting), and the npm 10 notes in [Getting Started](/docs/getting-started#prerequisites) and [Your First Project](/docs/getting-started/your-first-project#prerequisites) can be removed once `@vitest/browser-webdriverio` publishes the version that `npm view vitest dist-tags` lists as `V4`, and a plain npm 10 install of `@objectstack/plugin-auth` passes.
+
+---
+
## Validation Errors
### "Invalid enum value" for field type
diff --git a/content/docs/getting-started/index.mdx b/content/docs/getting-started/index.mdx
index a48e7949cf3..dfbe403d3e5 100644
--- a/content/docs/getting-started/index.mdx
+++ b/content/docs/getting-started/index.mdx
@@ -169,6 +169,15 @@ Before you start, make sure you have the following installed:
That's everything the standard path needs — `npx create-objectstack my-app`
scaffolds a project with its own TypeScript toolchain and npm scripts.
+
+**npm 10 cannot install the CLI right now.** npm 10, the npm that Node 22 ships,
+fails with `Cannot read properties of null (reading 'edgesOut')`. Upgrade npm
+first with `npm install -g npm@11` (npm 11 needs Node 22.9+), or use pnpm.
+Already scaffolded? Upgrade, then run `npm install` in the project.
+[Troubleshooting](/docs/deployment/troubleshooting#cannot-read-properties-of-null-reading-edgesout-from-npm-install)
+has the other fix.
+
+
**pnpm and TypeScript versions only matter for the framework monorepo.** If you
clone [`objectstack-ai/objectstack`](https://github.com/objectstack-ai/objectstack)
diff --git a/content/docs/getting-started/your-first-project.mdx b/content/docs/getting-started/your-first-project.mdx
index 40aea0d81f8..e843f61fbac 100644
--- a/content/docs/getting-started/your-first-project.mdx
+++ b/content/docs/getting-started/your-first-project.mdx
@@ -28,6 +28,15 @@ That's all. A standalone project does **not** need pnpm, TypeScript pre-installe
or a database server — the default template runs on an in-memory driver, and
TypeScript comes in as a dev dependency.
+
+**npm 10 cannot install the CLI right now.** npm 10, the npm that Node 22 ships,
+fails with `Cannot read properties of null (reading 'edgesOut')`. Upgrade npm
+first with `npm install -g npm@11` (npm 11 needs Node 22.9+), or use pnpm.
+Already scaffolded? Upgrade, then run `npm install` in the project.
+[Troubleshooting](/docs/deployment/troubleshooting#cannot-read-properties-of-null-reading-edgesout-from-npm-install)
+has the other fix.
+
+
## 1. Scaffold
```bash