docs(bundler): clarify metadata manifest and externals

tools/egg-bundler/README.md

@@ -21,6 +21,11 @@ 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 does not run registered
+`beforeClose` hooks while closing the temporary app.
+
 ## Options
 
 | Option             | Description                                                                     |

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

@@ -61,13 +61,20 @@ checks (T17).
 
 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.
+`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. 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. `externals.inline` removes an
+auto-detected external unless the same name is also present in
+`externals.force`.
 
 ## 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,18 @@ 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 skips registered `beforeClose`
+  hooks when the temporary app closes.
 - 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, 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 are 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.