docs(bundler): clarify metadata manifest and externals

tools/egg-bundler/README.md

@@ -21,6 +21,12 @@ await bundle({
 `outputDir` is resolved from `baseDir` when it is relative. The default manifest
 path is `<baseDir>/.egg/manifest.json`.
 
+If the startup manifest is missing, the bundler generates it by starting the app
+with `metadataOnly: true`. In that mode Egg skips the agent and normal boot
+lifecycle, runs `loadMetadata()` hooks, and the manifest generation child
+process exits after writing the manifest, so registered `beforeClose` hooks do
+not run.
+
 ## Options
 
 | Option             | Description                                                                     |

tools/egg-bundler/docs/output-structure.md

@@ -60,14 +60,21 @@ checks (T17).
 ## Externals
 
 Packages classified as external by `ExternalsResolver` are **not** inlined.
-This includes the user's `externals.force` list, root `peerDependencies`, root
-`optionalDependencies`, and native addons/native binaries. They must be
-installed alongside the bundle — typically by copying the app's `package.json`
-next to `worker.js` and running `npm ci --omit=dev`, or by deploying into an
-environment where these dependencies are already installed. ESM-only packages,
-`egg`, `@swc/helpers`, and `@eggjs/*` packages are bundled by default unless
-`ExternalsResolver` externalizes them through `externals.force`, dependency
-metadata, or native addon detection.
+This includes the user's `externals.force` list plus auto-detected entries from
+root `peerDependencies`, root `optionalDependencies`, root dependency packages
+with native addons/native binaries, root dependency packages whose optional peer
+dependencies cannot be resolved, and the names of those missing optional peer
+packages. The native addon and missing optional peer checks run only while
+resolving the app's root dependencies/optionalDependencies; `ExternalsResolver`
+does not recursively scan every transitive dependency. `externals.inline`
+removes an auto-detected external unless the same name is also present in
+`externals.force`. External packages must be installed alongside the bundle —
+typically by copying the app's `package.json` next to `worker.js` and running
+`npm ci --omit=dev`, or by deploying into an environment where these dependencies
+are already installed. ESM-only packages, `egg`, `@swc/helpers`, and `@eggjs/*`
+packages are bundled by default unless `ExternalsResolver` externalizes them
+through `externals.force`, dependency metadata, native addon detection, or
+missing optional peer detection.
 
 ## Known limitations
 

wiki/log.md

@@ -1,5 +1,11 @@
 # Wiki Log
 
+## [2026-05-03] package | refine egg bundler docs
+
+- sources touched: `tools/egg-bundler/src/lib/ManifestLoader.ts`, `tools/egg-bundler/src/lib/ExternalsResolver.ts`, `packages/core/src/lifecycle.ts`, `packages/egg/src/lib/start.ts`
+- pages updated: `tools/egg-bundler/README.md`, `tools/egg-bundler/docs/output-structure.md`, `wiki/log.md`, `wiki/packages/egg-bundler.md`
+- note: Documented manifest auto-generation in metadataOnly mode and clarified root dependency external detection plus the `externals.inline` override.
+
 ## [2026-05-02] package | document egg bundler tooling
 
 - sources touched: `tools/egg-bundler/src/index.ts`, `tools/egg-bundler/src/lib/Bundler.ts`, `tools/egg-bin/src/commands/bundle.ts`, `tools/egg-bundler/docs/output-structure.md`

wiki/packages/egg-bundler.md

@@ -7,7 +7,7 @@ source_files:
   - tools/egg-bundler/src/lib/Bundler.ts
   - tools/egg-bin/src/commands/bundle.ts
   - tools/egg-bundler/docs/output-structure.md
-updated_at: 2026-05-02
+updated_at: 2026-05-03
 status: active
 ---
 
@@ -38,8 +38,20 @@ CommonJS artifact from an Egg application.
 
 - Relative `outputDir` values are resolved from `baseDir`.
 - Default mode is `production`; `development` is also accepted.
+- If `<baseDir>/.egg/manifest.json` is missing, `ManifestLoader` starts the app
+  with `metadataOnly: true` to generate it. This skips the agent and normal boot
+  lifecycle, runs `loadMetadata()` hooks, and the manifest generation child
+  process exits after writing the manifest, so registered `beforeClose` hooks do
+  not run.
 - The generated app runs in Egg single-process mode.
-- Explicit `externals.force` entries, root `peerDependencies`, `egg`,
-  `@swc/helpers`, `@eggjs/*`, native addons, and ESM-only packages are external.
+- Explicit `externals.force` entries are external, and `ExternalsResolver`
+  auto-detects root `peerDependencies`, root `optionalDependencies`, root
+  dependency packages with native addons, root dependency packages whose optional
+  peer dependencies cannot be resolved, and the names of those missing optional
+  peer packages as external.
+- `externals.inline` removes an auto-detected external unless the same package
+  name is also listed in `externals.force`.
+- ESM-only packages, `egg`, `@swc/helpers`, and `@eggjs/*` packages are bundled
+  by default unless force-external or dependency/native-addon rules apply.
 - `BundlerConfig.tegg` is accepted but not applied by the current implementation
   yet.