Skip to content

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

Description

@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:

Implementation notes (for the implementing agent)

Acceptance criteria

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

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type
No fields configured for issues without a type.

Projects

Status
Todo

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions