docs: audit and correct all auto-install / bun zero-install documentation

[vivek7405]

Problem

The auto-install / bun zero-install documentation is out of sync across surfaces, found while dogfooding a fresh bun create webjs my-app (cli 0.10.26). The scaffolded app's AGENTS.md still carries the pre-#698 claim:

Under zero-install, deps resolve to their LATEST version: ranges and any bun.lock are ignored by the runtime auto-install (only an exact package.json pin is honored, via an onLoad rewrite). Run bun install when you want pinned, reproducible versions...

Wrong on two counts now:

1. feat: forward inline-safe ranges in the bun zero-install pin rewrite #698 (merged, released in server 0.8.37 / cli 0.10.26) made the onLoad rewrite forward inline-safe RANGES too, not just exact, so a caret/tilde/comparator range resolves to the highest match under zero-install (not absolute latest). "Only an exact pin is honored" is stale.
2. dogfood: bun zero-install bun run dev fails, cli can't resolve @webjsdev/server #709 (open): bun zero-install bun run dev currently FAILS for a fresh scaffold (the cli's bare import('@webjsdev/server') ENOENTs, bun's runtime auto-install does not reliably fetch it). So any doc that promises a Bun app "serves with no bun install" is currently OVER-PROMISING.

The main source surfaces were updated in #698/#700 (agent-docs/runtime.md, docs/app/docs/runtime/page.ts, root AGENTS.md, packages/cli/templates/AGENTS.md, packages/cli/lib/create.js banner), but these were MISSED and/or are now inaccurate given #709:

• packages/cli/AGENTS.md L102-106 ("auto-install resolves deps and a Bun app serves with no bun install"), L134, L202 ("since webjs create auto-installs").
• The PUBLISHED cli 0.10.26 artifact's template AGENTS.md is what the user actually scaffolded (the stale block above). Confirm whether the publish included the feat: forward inline-safe ranges in the bun zero-install pin rewrite #698 template fix or shipped stale, and whether a republish is needed.

Design / approach

One comprehensive pass (use the webjs-doc-sync skill's surface map) aligning EVERY auto-install / zero-install mention with the TRUE current behavior, gating the "it works" claims on #709:

• Correct: bun zero-install resolves a BARE import to latest (ignoring package.json), so webjs's onLoad rewrite pins each declared dep to its bun.lock-exact-else-package.json inline-safe semver (exact OR caret/tilde/comparator range, feat: forward inline-safe ranges in the bun zero-install pin rewrite #698), with protocol/wildcard/multi-token/dist-tag/caret-prerelease (bun-pin-rewrite: don't forward a caret-prerelease range (bun ENOENTs on it) #703) left bare.
• Be honest until dogfood: bun zero-install bun run dev fails, cli can't resolve @webjsdev/server #709 lands: a fresh bun run dev may currently fail to fetch the cli/server, so recommend bun install as the reliable path and qualify any "serves with no install" promise. Flip those to the working claim once dogfood: bun zero-install bun run dev fails, cli can't resolve @webjsdev/server #709 merges.
• Land this WITH or AFTER dogfood: bun zero-install bun run dev fails, cli can't resolve @webjsdev/server #709 so the "works zero-install" statements are true when written.

Implementation notes (for the implementing agent)

• Surfaces to audit (generative, run git ls-files + grep, not exhaustive): agent-docs/runtime.md, docs/app/docs/runtime/page.ts (+ getting-started/deployment), root AGENTS.md, packages/cli/AGENTS.md, packages/cli/templates/AGENTS.md + the per-agent rule files in packages/cli/templates/ (.cursorrules, .agents/rules/*, .github/copilot-instructions.md, CLAUDE.md, CONVENTIONS.md), packages/cli/lib/create.js (post-scaffold banner), website/app/page.ts, README.md, packages/*/README.md.
• Grep seeds: "resolve to their LATEST", "ranges and any", "only an exact", "serves with no bun install", "auto-install", "zero-install", "absolute latest".
• Landmine: the scaffolded app's AGENTS.md is generated from the template at the cli VERSION the user installed; a source fix only reaches users on the next cli publish. Confirm the next cli release carries the corrected template.
• Tie-in: feat: forward inline-safe ranges in the bun zero-install pin rewrite #698 (ranges), bun-pin-rewrite: don't forward a caret-prerelease range (bun ENOENTs on it) #703 (caret-prerelease bare), Revert scaffold @webjsdev/* + drizzle exact pins to semver ranges (after #698) #700 (scaffold ranges), dogfood: bun zero-install bun run dev fails, cli can't resolve @webjsdev/server #709 (the open dev-bootstrap failure that makes "serves with no install" currently false), research: can bun zero-install get lockfile-like reproducible versions? #705 (reproducibility).

Acceptance criteria

• Every auto-install / zero-install doc surface states the post-feat: forward inline-safe ranges in the bun zero-install pin rewrite #698 behavior accurately (ranges resolve, not "exact-only / latest").
• No surface promises "a Bun app serves with no bun install" while dogfood: bun zero-install bun run dev fails, cli can't resolve @webjsdev/server #709 is open (or this lands after dogfood: bun zero-install bun run dev fails, cli can't resolve @webjsdev/server #709 so the promise is true).
• The published cli template is confirmed corrected (republish if needed).
• webjs-doc-sync run so no surface is silently skipped.

Relates to #698, #700, #703, #705, #709.

---

Update (2026-06-25): #709 fixed + published, fold in #705 and #713

The landscape moved since filing:

• dogfood: bun zero-install bun run dev fails, cli can't resolve @webjsdev/server #709 is MERGED + published (cli 0.10.27). A fresh bun run dev now resolves the cli + server (the cli pins its own @webjsdev/* imports via importWebjsdev). So the "while dogfood: bun zero-install bun run dev fails, cli can't resolve @webjsdev/server #709 is open" framing and the "serves with no bun install is over-promising" caveat are RESOLVED. The docs can now state that bun zero-install dev works, with no install step.
• research: can bun zero-install get lockfile-like reproducible versions? #705 is CLOSED with a NEGATIVE verdict. Bun's runtime auto-install does NOT honor a committed bun.lock for bare imports (verified on bun 1.3.14: a bare import('lodash') ENOENTs with the lock + the version cached, while the inline lodash@x form resolves). So NO surface may claim bun.lock gives reproducible zero-install resolution today. bun install --lockfile-only is fast and node_modules-free, but only useful as an editor/tooling aid, not a runtime pin.
• dogfood: importmap vendors server-only @webjsdev/cli via jspm under bun zero-install #713 (server 0.8.38) removed the server-only @webjsdev/cli/server/mcp leak onto the jspm vendor path (not a doc surface, but confirms the vendor model the docs describe).

The accurate statement the audit should converge every surface to: bun zero-install resolves a BARE import to latest (ignoring package.json AND a committed bun.lock at runtime), so webjs's onLoad rewrite pins each declared dep to its inline-safe package.json semver (exact OR caret/tilde/comparator range, #698; caret-prerelease / wildcard / protocol left bare, #703); the cli pins its own @webjsdev/* imports (#709); and server-only framework packages are excluded from the browser vendor (#713). A committed bun.lock changes nothing at runtime (#705).

[vivek7405]

Closing as obsolete: Bun zero-install was removed in #721 (merged #722, released cli 0.10.28 / server 0.8.39). Bun apps now install with bun install like Node, so the pin shim, auto-install tooling, lockfile-drift, and zero-install docs this issue concerns no longer exist. True zero-install with editor types is a possible future Deno track (#669).