docs(publish): clarify bundle module names

website/src/content/docs/docs/configuration-reference.mdx

@@ -50,7 +50,7 @@ For workspace setup, package discovery, and task exclusions, start with the
 | `publish.repository_tag_format` | with the other two | Repository tag template; must contain `{series}` and no `{name}`. |
 | `publish.repository_tags` | with the other two | Which repository tags to maintain, from the same vocabulary minus `exact`. Required alongside `repository_tag_package` and `repository_tag_format`; declare all three or none. |
 | `publish.path_dep_requirement` | no | How a workspace path dependency becomes a Hex requirement at publish time, from the dependency's current version `X.Y.Z`: `minor` (default, `>= X.Y.Z and < (X+1).0.0`), `patch` (`>= X.Y.Z and < X.(Y+1).0`), or `exact` (`== X.Y.Z`). |
-| `publish.bundle` | no | Map of exact publishing package names to direct non-Hex runtime dependency names, for example `{ lib_a = ["lib_b"] }`. Empty by default. Includes transitive non-Hex runtime source dependencies; see [source bundling](/docs/publishing/#bundling-private-dependencies). |
+| `publish.bundle` | no | Map of exact publishing package names to direct non-Hex runtime dependency names, for example `{ lib_a = ["lib_b"] }`. Empty by default. Copies source, including transitive non-Hex runtime dependencies, without renaming modules or rewriting imports. Module names must be unique across the combined package and its consumer's dependencies; see [source bundling](/docs/publishing/#bundling-private-dependencies). |
 | `publish.retry` | no | Backoff for Hex rate limits: `{ attempts, initial_delay, multiplier }`. Defaults: 5 attempts, `30s`, multiplier 2. |
 | `publish.lifecycle.default` | no | Release lifecycle for a member matched by no `packages` glob and no legacy `exclude.@release` glob: `workspace`, `git_only`, or `hex` (default). |
 | `publish.lifecycle.packages` | no | Per-package lifecycle overrides: a map of member-path glob to lifecycle. Takes precedence over `exclude.@release`. A member matched by globs resolving to different lifecycles is an error; matches agreeing on the same lifecycle are fine. |

website/src/content/docs/docs/publishing.mdx

@@ -172,6 +172,17 @@ that you do not want to publish on Hex. Keep separate packages for development;
 trellis copies the selected dependency's source into the publishing package
 for release.
 
+<Callout type="caution">
+
+**Bundling copies source; it does not rewrite modules.** Trellis does not
+rename modules, add a package-name prefix, or rewrite imports. Module names
+must be unique across the publishing package, its bundled dependencies, and
+the other dependencies in a consumer's build. Use distinct module paths,
+such as `lib_a/parser` and `lib_b/parser`, rather than defining `parser` in
+both packages. Different package names alone do not prevent module collisions.
+
+</Callout>
+
 ```toml title="gleam.toml"
 [tools.trellis]
 members = ["packages/*"]
@@ -248,9 +259,10 @@ check whether the version already exists.
 | `trellis publish lib_a` | Preparation conflicts plus errors from building and testing the combined package with its resolved dependencies before upload. |
 
 Two independent publishers can each include the same module names without a
-conflict in either package alone. A consumer that installs both can still
-encounter a collision. Neither publisher's `doctor` check can predict that
-future dependency combination; the consumer's build must check it.
+conflict in either package alone. A consumer that installs both, or installs
+a bundled package alongside a separate release of its bundled dependency,
+can still encounter a collision. Neither publisher's `doctor` check can
+predict that future dependency combination; the consumer's build must check it.
 
 ### Compatibility and release notes
 
@@ -278,8 +290,7 @@ independent release or changelog; a `git_only` dependency keeps its own rules.
 Bundling publishes the dependency's source in the Hex archive. Check that you
 can redistribute it and that the publishing package declares the required
 licences. Trellis includes attributed licence notices in a standard licence
-file. Two packages that bundle the same module names can conflict when a
-consumer installs both; trellis does not rename modules to prevent that.
+file.
 
 </Callout>