fix: bun_install adds node_modules to each directory

docs/BUILD.bazel

@@ -16,4 +16,5 @@ stardoc(
         "ts_library",
     ],
     deps = ["//bun:defs_bzl"],
+    target_compatible_with = ["@platforms//os:linux"],
 )

docs/bun_install.md

@@ -0,0 +1,90 @@
+# `bun_install`
+
+`bun_install` is a Bzlmod module extension for creating an external repository
+that contains a Bun-generated `node_modules/` tree.
+
+Unlike the build rules in [rules.md](rules.md), `bun_install` is not loaded from
+`@rules_bun//bun:defs.bzl`. It is loaded from
+`@rules_bun//bun:extensions.bzl`, so it is documented separately.
+
+## What it does
+
+`bun_install`:
+
+- runs `bun install --frozen-lockfile`
+- uses your checked-in `package.json` and `bun.lock` or `bun.lockb`
+- creates an external Bazel repository exposing `:node_modules`
+- keeps dependency installation under Bun rather than npm
+
+The generated repository can then be passed to rules such as `bun_script`,
+`bun_binary`, `bun_bundle`, and `bun_test`.
+
+## Usage
+
+```starlark
+bun_install_ext = use_extension("@rules_bun//bun:extensions.bzl", "bun_install")
+
+bun_install_ext.install(
+    name = "bun_deps",
+    package_json = "//:package.json",
+    bun_lockfile = "//:bun.lock",
+)
+
+use_repo(bun_install_ext, "bun_deps")
+```
+
+Then reference the installed dependencies from build targets:
+
+```starlark
+load("@rules_bun//bun:defs.bzl", "bun_script")
+
+bun_script(
+    name = "web_dev",
+    script = "dev",
+    package_json = "package.json",
+    node_modules = "@bun_deps//:node_modules",
+)
+```
+
+## `install(...)` attributes
+
+### `name`
+
+Repository name to create.
+
+This becomes the external repository you reference later, for example
+`@bun_deps//:node_modules`.
+
+### `package_json`
+
+Label string pointing to the source `package.json` file.
+
+Example:
+
+```starlark
+package_json = "//:package.json"
+```
+
+### `bun_lockfile`
+
+Label string pointing to the Bun lockfile.
+
+Supported lockfile names are:
+
+- `bun.lock`
+- `bun.lockb`
+
+Example:
+
+```starlark
+bun_lockfile = "//:bun.lock"
+```
+
+## Notes
+
+- `bun_install` runs Bun, not npm.
+- The repository name is arbitrary. `bun_deps` is only an example.
+- The generated repository exposes a standard `node_modules/` tree because that
+  is the dependency layout Bun installs.
+- `--frozen-lockfile` is used, so the lockfile must already be in sync with
+  `package.json`.

docs/index.md

@@ -14,16 +14,21 @@ Supporting material lives in:
 
 - [examples/](../examples/) for usage samples
 - [tests/](../tests/) for repository conformance and integration tests
-- [docs/rules.md](rules.md) for generated rule reference
+- [docs/rules.md](rules.md) for generated build rule reference
+- [docs/bun_install.md](bun_install.md) for `bun_install` extension docs
 
 ## Rule reference
 
 - [rules.md](rules.md)
 
+## Bzlmod extensions
+
+- [bun_install.md](bun_install.md)
+
 ## Typical Bzlmod setup
 
 ```starlark
-bazel_dep(name = "rules_bun", version = "0.2.0")
+bazel_dep(name = "rules_bun", version = "0.2.1")
 
 bun_ext = use_extension("@rules_bun//bun:extensions.bzl", "bun")
 
@@ -50,6 +55,9 @@ register_toolchains(
 Use `bun_script` for package-script driven workflows such as `dev`, `build`,
 and `preview`.
 
+The `node_modules` label below refers to dependencies installed by
+`bun_install`.
+
 ```starlark
 load("@rules_bun//bun:defs.bzl", "bun_script")
 
@@ -57,7 +65,7 @@ bun_script(
 	name = "web_dev",
 	script = "dev",
 	package_json = "package.json",
-	node_modules = "@npm//:node_modules",
+	node_modules = "@my_workspace//:node_modules",
 	data = glob([
 		"src/**",
 		"public/**",

docs/rules.md

@@ -9,7 +9,7 @@ Runs a JS/TS entry point with Bun as an executable target (`bazel run`).
 Attributes:
 
 - `entry_point` (label, required): path to the main JS/TS file to execute.
-- `node_modules` (label, optional): Bun/npm package files in runfiles.
+- `node_modules` (label, optional): package files from a `node_modules` tree, typically produced by `bun_install`, made available in runfiles.
 - `data` (label_list, optional): additional runtime files.
 - `working_dir` (string, default: `"workspace"`, values: `"workspace" | "entry_point"`): runtime working directory.
 
@@ -22,7 +22,7 @@ Attributes:
 - `entry_point` (label, required): path to the main JS/TS file.
 - `watch_mode` (string, default: `"watch"`, values: `"watch" | "hot"`): Bun live-reload mode.
 - `restart_on` (label_list, optional): files that trigger full process restart when changed.
-- `node_modules` (label, optional): Bun/npm package files in runfiles.
+- `node_modules` (label, optional): package files from a `node_modules` tree, typically produced by `bun_install`, made available in runfiles.
 - `data` (label_list, optional): additional runtime files for dev process.
 - `working_dir` (string, default: `"workspace"`, values: `"workspace" | "entry_point"`): runtime working directory.
 
@@ -38,7 +38,7 @@ Attributes:
 
 - `script` (string, required): package script name passed to `bun run <script>`.
 - `package_json` (label, required): `package.json` file containing the named script.
-- `node_modules` (label, optional): Bun/npm package files in runfiles.
+- `node_modules` (label, optional): package files from a `node_modules` tree, typically produced by `bun_install`, made available in runfiles.
 - `data` (label_list, optional): additional runtime files for the script.
 - `working_dir` (string, default: `"package"`, values: `"workspace" | "package"`): runtime working directory. The default is a good fit for Vite and similar package-script based tools.
 
@@ -49,7 +49,7 @@ Bundles one or more JS/TS entry points with Bun build.
 Attributes:
 
 - `entry_points` (label_list, required): entry files to bundle.
-- `node_modules` (label, optional): Bun/npm package files for resolution.
+- `node_modules` (label, optional): package files from a `node_modules` tree, typically produced by `bun_install`, used for package resolution.
 - `deps` (label_list, optional): source/library dependencies for transitive inputs.
 - `data` (label_list, optional): additional non-source files needed during bundling.
 - `target` (string, default: `"browser"`, values: `"browser" | "node" | "bun"`): Bun build target.
@@ -65,7 +65,7 @@ Runs Bun tests as a Bazel test target (`bazel test`).
 Attributes:
 
 - `srcs` (label_list, required): test source files passed to `bun test`.
-- `node_modules` (label, optional): Bun/npm package files in runfiles.
+- `node_modules` (label, optional): package files from a `node_modules` tree, typically produced by `bun_install`, made available in runfiles.
 - `deps` (label_list, optional): library dependencies required by tests.
 - `data` (label_list, optional): additional runtime files needed by tests.