docs(deployment): name the npm 10 edgesOut install failure and its two remedies

npm 10 (the npm Node 22 ships) cannot install @objectstack/cli or
@objectstack/plugin-auth: better-auth's optional vitest peer resolves to
vitest@4.1.12, whose @vitest/browser-webdriverio peer set is incoherent.

- self-hosting: the self-built runtime recipe installs under a pinned npm 11
  the way docker/Dockerfile does (and with the image's pg/mysql2 drivers, so
  "equivalent" holds); the host install upgrades npm to 11 first.
- troubleshooting: one Installation Issues entry, findable by the error
  text, with both remedies and when the entry can be removed.
- getting-started: a short npm 10 note at both Prerequisites tables.

Claude-Session: https://claude.ai/code/session_016PVjjuVPte5XEJvaQx1E4t
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

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://…)

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

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.
 
+<Callout type="warn">
+**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.
+</Callout>
+
 <Callout type="info">
 **pnpm and TypeScript versions only matter for the framework monorepo.** If you
 clone [`objectstack-ai/objectstack`](https://github.com/objectstack-ai/objectstack)

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.
 
+<Callout type="warn">
+**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.
+</Callout>
+
 ## 1. Scaffold
 
 ```bash