docs: correct #675 zero-install caveat (Bun runs latest, ignores package.json + bun.lock)

[vivek7405]

Problem

The #675 docs frame the Bun zero-install reproducibility tradeoff as range-level ("resolves on demand", "dev resolves on demand vs a pinned prod image"). That understates it. Verified on a fresh cache: bun --bun auto-install (the exact path bun run dev / start take via the webjs-bun.mjs bootstrap, with no node_modules) IGNORES both the package.json version AND a committed bun.lock, and fetches latest for any bare import not physically in node_modules.

Proof: a package.json pinning zod EXACTLY to 3.22.4 ran zod 4.4.3; keeping a bun.lock that pinned 3.22.4 (with node_modules deleted) STILL ran 4.4.3. Only bun install (which materializes node_modules) honors the manifest/lockfile. So a zero-install Bun app runs UNPINNED LATEST deps, which can silently pull a breaking major. The current docs do not say this; they imply the app's declared versions are used.

Design / approach

Correct every #675 doc surface to state the accurate caveat plainly, framed as a real limitation, not a reproducibility nicety: "Zero-install (bun run dev / start with no node_modules) resolves each dependency to its LATEST version, ignoring the package.json range and any bun.lock. Run bun install to pin: it materializes node_modules from the manifest/lockfile, which the auto-install run path then uses." Keep the recommendation: run bun install when you need pinned/reproducible versions (and for editor types).

Implementation notes (for the implementing agent)

• Where to edit:
  • docs/app/docs/runtime/page.ts (the "Bun" section + the "Install model and reproducibility" subsection, which currently says "dev resolves on demand while a prod image pins").
  • docs/app/docs/getting-started/page.ts (the Bun pointer, if it implies the declared versions are honored).
  • agent-docs/runtime.md (the "Bun zero-install" section + the "Reproducibility tradeoff" line).
  • docs/app/docs/deployment/page.ts (the parenthetical linking to /docs/runtime, ensure it does not imply pinned).
• Landmines: invariant feat(server): replace esbuild TS stripping with Node 24+ strip-types #9 (NO backtick inside the html tagged-template bodies of the doc pages, use <code>), invariant release: bump core/server/cli versions, honest engines fields #11 (no em-dash, no space-surrounded hyphen/semicolon pause, no colon after a code-shaped LHS). The behavior is Bun's, not webjs's, so phrase it as "Bun's auto-install fetches latest", not "webjs fetches latest".
• This corrects docs shipped by Zero-install dev/start on Bun via native auto-install (carve from #669) #675/feat: zero-install dev/start on Bun via auto-install bootstrap #676/docs: note dev zero-install on the deployment Bun Dockerfile bullet #677/docs: add a Runtime page consolidating Node + Bun (+ future Deno) #680. Docs-only, no package code, NO version bump.
• Tests + docs: boot-check the edited pages serve 200 (the in-repo docs app via createRequestHandler, prod mode). No unit test layer applies (docs prose).

Acceptance criteria

• The runtime page, getting-started, agent-docs/runtime.md, and deployment all accurately state that Bun zero-install runs LATEST deps (ignoring package.json + bun.lock).
• They state bun install is how to pin (it materializes node_modules, which the run path then uses).
• No surface implies the declared versions are honored under zero-install.
• Edited pages boot 200.

[vivek7405]

Superseded by #685 (merged). #685 changed the behavior (Bun zero-install now PINS to the bun.lock / exact-pin version via an onLoad specifier rewrite) AND updated every doc surface to describe it accurately: the runtime docs page + agent-docs/runtime.md state that an EXACT version pins and a range without a bun.lock falls back to latest (the precise, corrected caveat #683 asked for), and getting-started/deployment defer to /docs/runtime. So the standalone 'correct the docs to say runs latest' task is moot. Closing.