docs(deployment): name the npm 10 edgesOut install failure and its npm 11 / overrides.vitest remedies

[objectstack-fleet]

Fixes #23849

Clause-②: no

Docs only. npm 10, the npm that Node 22 ships, cannot install @objectstack/cli or @objectstack/plugin-auth today. This PR names the failure where npm readers meet it and gives the two measured remedies: npm 11, or a root overrides.vitest. A global install can only use the first.

Upstream, re-measured at claim (2026-10-16T09:13Z)

• npm view vitest dist-tags gives V4: 4.1.12 and latest: 5.0.5.
• npm view @vitest/browser-webdriverio versions --json shows the 4.x line ending at 4.1.11. There is no 4.1.12.
• vitest@4.1.12 has an optional peer @vitest/browser-webdriverio: ^4.1.11, and @vitest/browser-webdriverio@4.1.11 peers vitest: 4.1.11 exactly.
• better-auth@1.7.3 has an optional peer vitest: ^2.0.0 || ^3.0.0 || ^4.0.0. @objectstack/plugin-auth@next (18.0.0-next.2) still pins better-auth: 1.7.3.
• Verdict: no coherent vitest 4 peer set has shipped, so the target does not shrink.

Reproduction and remedies

Each case ran in a fresh empty directory with a fresh --cache. Exit codes were captured before any pipe, and every tree was deleted afterwards. On the host: Node 22.22.0 with npm 10.9.4. In the container: node:22-slim at sha256:c3de60bf2f9dd0ac6370e6117950ff62d6e339527e7472301c9c78a017978392 (Node 22.23.3, npm 10.9.9).

case	npm	command	exit	edgesOut
A	10.9.4	npm install @objectstack/plugin-auth@next	1	yes
B	10.9.4	npm install -g @objectstack/cli@next	1	yes
F	10.9.4	npm install -g @objectstack/cli@17.7.0 (the page's pin)	1	yes
K	10.9.4	npm create objectstack@latest my-app, no pnpm on PATH	0, but its install step failed	yes
docker, current recipe	10.9.9	the page's self-built recipe at 1eac7ad75, as written	1	yes
C	11.21.0	npm install @objectstack/plugin-auth@next	0	no
D	11.21.0	npm install -g @objectstack/cli@next	0	no
G	11.21.0	npm install -g @objectstack/cli@17.7.0	0	no
I	11.19.1 (Node 24's npm)	npm install -g @objectstack/cli@next	0	no
J	12.2.0	npm install -g @objectstack/cli@next	0 (warns that npm 12 does not support Node 22.22.0)	no
O	11.21.0	npm create objectstack@latest my-app	0, install ran	no
N	10.9.4, then 11.21.0	scaffold on npm 10 (its install fails), then npm install on npm 11 in that project	0	no
E	10.9.4 with a root override vitest: ~4.0.0	npm install @objectstack/plugin-auth@next	0	no
E2	10.9.4 with the same override	npm install @objectstack/cli@next	0	no
H	10.9.4 with the same override in the cwd	npm install -g @objectstack/cli@next	1	yes: -g reads no overrides
L	lockfile from 11.21.0, then npm ci on 10.9.4	@objectstack/cli 17.7.0 as a devDependency, no override	0	no
M	pnpm 10.28.0	pnpm add @objectstack/plugin-auth@next	0	no
docker, new recipe	10.9.9 image npm, install under 11.21.0	the new recipe at dc2370288, as written	0	no

Both published scaffolders ship a blank template with no overrides: create-objectstack@17.7.0 (latest) and @18.0.0-next.2 (next). The template fix from #23799 is on main but not released yet, which is why case K fails.

Checks on the new-recipe image, run with docker run:

• os --version prints @objectstack/cli/17.7.0.
• The image's own npm is still 10.9.9.
• /tmp/os-installer-npm is gone.
• pg and mysql2 resolve from driver-sql's directory.
• No vitest is installed.
• The image is 1.14 GB.

The boot is NOT MEASURED. The build context carried a placeholder artifact, and the only line this PR changes is the install RUN.

How the Docker builds ran: a private dockerd in this container, behind its agent proxy. The base was node:22-slim at the digest above, with the proxy CA added through NODE_EXTRA_CA_CERTS and re-tagged locally. The builds used --network host and took the proxy as build args. Each recipe was extracted byte-for-byte from the committed page, not retyped.

Pages changed

• content/docs/deployment/self-hosting.mdx
  • Self-built runtime recipe. It now installs under a pinned npm 11: npm is fetched into /tmp, put first on PATH for that RUN, and deleted in the same layer. This is the shape docker/Dockerfile has used since fix(devx): npm 10 crashes with edgesOut on the vendor-export probe and the blank scaffold — the probe installs with a pinned npm 11, the template overrides vitest #23799.
  • The install line also takes docker/Dockerfile's "pg@^8.0.0" "mysql2@^3.0.0". The page presents this recipe as what "the official image is nothing more than", and without the drivers that is not true. Both drivers are optional peers of @objectstack/driver-sql@17.7.0, which npm does not install, and the new image's CLI tree carries no pg of its own.
  • The @objectstack/cli@17.7.0 literal stays, so check:docs-image-tag still reads it.
  • Bare Node.js host install. One sentence names the failure, and npm install -g npm@11 now comes before the CLI install. npm 11 needs Node 22.9 or newer (the engines of npm@11.21.1). The text says npm@11 and not npm@latest, because npm@latest is 12.2.0, which warns on Node 22.22.0.
• content/docs/deployment/troubleshooting.mdx: a new "Installation Issues" section with one entry, headed by the error text (anchor #cannot-read-properties-of-null-reading-edgesout-from-npm-install). It gives the symptom, a one-line cause, both fixes, and when the entry and the notes that link to it can be removed.
• content/docs/getting-started/index.mdx and content/docs/getting-started/your-first-project.mdx: one warn Callout at each Prerequisites table. Both pages tell an npm user to scaffold, and the published scaffolder's install step fails on npm 10 (case K). build-with-claude-code.mdx links to the first one for its prerequisites.

This PR leaves the dockerfile title="Dockerfile" block alone. That is the scaffold's build stage: dockerfile-build-stage.test.ts pins it to the template, and its npm ci from a lockfile is not affected (case L).

Pages grepped and left alone

I ran git grep over content/docs/**, excluding releases/** and references/**. It searched for npm install, npm i, npm ci, npm install -g, npm create objectstack, npx create-objectstack, and pnpm add or yarn add of the CLI or plugin-auth. These matches stay as they are:

• getting-started/build-with-claude-code.mdx:51 (npm create objectstack@latest). Its prerequisites link to getting-started#prerequisites, which now carries the note.
• getting-started/index.mdx:186: npm install -g pnpm, not the CLI.
• deployment/install-modes.mdx: no npm install of the CLI or plugin-auth, only os package install.
• deployment/cli.mdx:14 (pnpm add -D @objectstack/cli), permissions/authentication.mdx:98 and plugins/index.mdx:196 (pnpm add @objectstack/plugin-auth): these use pnpm, which passes (case M).
• deployment/cli.mdx:26,100, capabilities/index.mdx:30 and ai/skills-reference.mdx:36 (npm create objectstack@latest): outside this claim's file surface, so not edited. Readers there can find the troubleshooting entry by the error text. They are named in the Acceptance notes.
• npm install of other packages (@objectstack/driver-turso, @objectstack/skills, @objectstack/core, pg, mysql2): plugin-auth is not in their trees.
• skills/objectstack-platform/references/bootstrap.md (comment 6211828218): a Tier H file, not in this claim, and left with triage.

Gates (local, at 7f4e1158e)

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 41 commands. All 41 ran and all exited 0. The --ran reconciliation reports 41 derived, 41 run, 0 NOT-MEASURED and 0 UNRUN.
  • Two gates first refused with exit 3 (prerequisite not met) and passed once their inputs were built. check:docs-transcript-drift needed @objectstack/lint... built. @objectstack/spec check:skill-examples needed @objectstack/client-react... built.
• check:docs-image-tag exits 0.
• Tests that read these pages:
  • create-objectstack: src/dockerfile-build-stage.test.ts, 5 of 5 pass.
  • @objectstack/cli: the doc-floor cases of test/scaffold-emission-policy.e2e.test.ts (a nightly-tier file), 2 pass. The TypeScript floors it reads (5.3+ and 5.3.0 or later) are unchanged.
• An MDX compile of the four pages with the docs app's @mdx-js/mdx and remark-gfm passes for all four. The control, one page with its closing Callout tags removed, fails.
• node scripts/pm/check-governed-merges.mjs --branch claude/issue-23849-npm10-install-docs reports the PR as not governed, with 54 changed lines.
• The Build Docs job and the rest of CI are read from this PR's check-runs.

Acceptance notes

• When the dependency install fails, the published create-objectstack prints "Run npm install manually.", but its "Next steps" list leaves npm install out. It prints that step only under --skip-install (the options.skipInstall branch of the next-steps block in packages/create-objectstack/src/index.ts). Measured on 17.7.0 in case K. Reported to the seat, not fixed here.
• deployment/cli.mdx, capabilities/index.mdx and ai/skills-reference.mdx also tell npm readers to scaffold, but they are outside this claim's surface.
• The troubleshooting entry states its own removal condition and lists the notes that go with it.

---

Generated by Claude Code

[objectstack-fleet]

席位核对 · ACCEPT · PR #23864 (draft, head 7f4e1158e, Fixes #23849) · domain:devx seat 2 · session_016PVjjuVPte5XEJvaQx1E4t · 2026-10-16T10:03Z

Checked on GitHub and against the sources, not on the report's say-so.

• Shape:
  • 4 files, +53 / −1, all under content/docs/ and inside the claim's surface (6212146413).
  • Not governed: this seat ran check-governed-merges --pr 23864 and it reads 0 of 4 paths.
  • The body opens Fixes #23849, then Clause-②: no at line start.
  • It is docs only, so the seat applied skip-changeset in this act.
• Read line by line on the diff:
  • self-hosting.mdx. The self-built recipe now installs under a pinned npm@11.21.0 fetched to /tmp, asserts the version, and deletes it in the same layer. That is docker/Dockerfile's shape since fix(devx): npm 10 crashes with edgesOut on the vendor-export probe and the blank scaffold — the probe installs with a pinned npm 11, the template overrides vitest #23799. It also adds "pg@^8.0.0" "mysql2@^3.0.0". The seat accepts that addition: the page calls this recipe what the official image is "nothing more than", and docker/Dockerfile installs both drivers. The host install gains one sentence and npm install -g npm@11, with the note that npm 11 needs Node 22.9+.
  • troubleshooting.mdx. It gets a new "Installation Issues" section with one entry headed by the error text. The entry gives both fixes, says that -g reads no overrides, and states when to remove it: once @vitest/browser-webdriverio publishes vitest's V4 version and a plain npm 10 install passes.
  • getting-started/index.mdx and your-first-project.mdx. Each gets one warn Callout at Prerequisites. The dev measured npm create objectstack@latest failing its install on npm 10, because the published create-objectstack templates carry no override yet.
• Measured by the dev:
  • Upstream re-read at 2026-10-16T09:13:53Z: still incoherent (V4 = 4.1.12; browser-webdriverio 4.x ends at 4.1.11). So the target did not shrink.
  • On npm 10.9.4, local plugin-auth@next and -g cli@next / @17.7.0 all exit 1 with edgesOut. On npm 11.21.0 they exit 0, and npm 10 with a root overrides.vitest exits 0. -g with an override in the current directory still fails.
  • The new recipe, extracted byte-for-byte, builds on node:22-slim (npm 10.9.9) in 94 s and runs os --version = 17.7.0. The old recipe fails at its install step.
  • MDX compile of the 4 pages: all ok.
• Gates:
  • Local: 41 derived, 41 exit 0, --ran 0 NOT-MEASURED. The run includes check:docs-image-tag and check:doc-anchors.
  • CI on 7f4e1158e at this act: 20 success, 6 roster skips, 10 still running. One failure, Check Changeset, is the missing label and clears with skip-changeset.
• Out of scope, routed by this seat:
  • The create-objectstack next-steps defect (on a failed install it prints no install step) is a packages/create-objectstack code defect. The seat files it as its own card.
  • Four more pages say npm create objectstack@latest: deployment/cli.mdx, capabilities/index.mdx and ai/skills-reference.mdx. The seat does not widen this PR. A reader who hits the error finds the new troubleshooting entry by its text, and the callouts sit on the two entry pages.
  • The skills/** bootstrap manifest stays with triage (6211828218).
• Landing: when every check on this head reads green, the seat readies the PR, arms auto-merge, and confirms the merge on origin/main.

---

Generated by Claude Code