oevery · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git a/docs/site/en/guides/execution.md b/docs/site/en/guides/execution.md
@@ -50,7 +50,7 @@ export default {
 - With artifact cleanup enabled, the order is: clean the target output directory, prepare if needed, run the target, then deliver artifacts. Later variants may still clean or move the output directory. Keep reusable preparation files outside target output directories; generate per-build output files in the target command array rather than in one-time project preparation.
 - `target.prepare: false` skips preparation only for that target; later eligible targets still trigger it. Failure or cancellation stops execution before subsequent targets start.
 - Commands run in the project root with global configuration, selected dotenv, and Shell values, without merging product env or injecting product/variant identity. They do not inherit a target's default NODE_ENV; global/external values are preserved. Matrix injects `MATRIX_PROJECT`, `MATRIX_ENV_NAME`, and `MATRIX_TARGET=prepare`.
-- `matrix prepare [product]` explicitly prepares projects referenced by the selected product (all products if omitted), then generates runtime types without running business targets. Build-plugin type generation is unchanged.
+- `matrix prepare [product]` prepares projects referenced by the selected product (all products if omitted), then generates runtime declarations without running business targets. See [type preparation](./integrations.md#type-preparation) for shared-project collection.
 - `matrix plan` lists preparation commands, working directories, environments, and `beforeTask` in its JSON `preparations` field. `doctor` performs static preflight checks. Neither executes preparation.
 
 `project.prepare` is separate from an ordinary target named `prepare`. Preparation never recursively prepares itself and does not support dependencies, continuous services, or artifact settings.

diff --git a/docs/site/en/guides/integrations.md b/docs/site/en/guides/integrations.md
@@ -103,15 +103,23 @@ electron-vite must support the selected Vite version. Type preparation and real
 
 ## Type preparation
 
-Run `matrix prepare` before starting development to generate runtime declarations for the selected products. Scope stays in the build plugin configuration; it does not need to be repeated in `matrix.config`.
+Run `matrix prepare [product]` to generate declarations without running business targets. The product selects projects; each shared project + scope includes all referring products and variants in the selected `--env`, never other environments. Projects with equal or overlapping physical roots are collected together. `matrix dev` and `matrix build` collect after project preparation, before starting the target.
 
-- By default, preparation checks files directly in the project root only: `electron.vite.config.*` takes priority over `vite.config.*`. It never searches subdirectories or parent directories. Multiple files matching the selected rule require an explicit choice. The locally installed host resolves the real configuration, including plugin hooks, `root`, `envDir`, `envPrefix`, `scope`, and `types` options. Electron main/preload declarations are generated separately, without starting Electron, a dev server, or a bundle build.
-- Set `projects.desktop.configFile`, for example `'config/electron.vite.config.ts'`, to select a file relative to that project's root. This overrides automatic discovery; the basename must still match a supported rule (`electron.vite.config.*` or `vite.config.*`, with a JS/TS module extension). Missing, unsupported, or failing explicit configs are errors, never a reason to fall back. `configFile` only controls preparation and does not modify target commands; no separate host setting is needed.
-- Preparation resolves the development configuration (`serve`; Electron main/preload use their normal development-time `build` configuration hooks), with `NODE_ENV=development` and `mode` set to the Matrix `--env` selection. Each product/variant is evaluated in an isolated process with `MATRIX_TARGET=prepare` and its product key, project, and variant. Product identity (ID/name/slug/appId, including suffixes and overrides) and version use the same resolution rules as execution plans; a missing package version is allowed when no version is configured. This is not a production build context; keep scope and type contracts independent of the selected product and target.
-- Shared projects merge the selected products' public field names. Schema-declared fields do not need runtime values to generate their types. Duplicate scopes, conflicting outputs/prefixes, changing scope sets, and configuration failures are diagnosed before Matrix writes declarations. Preparation does execute configuration code and configuration hooks, in addition to the existing project preparation commands; it is not a side-effect-free static scan. Each host evaluation has a 30-second timeout.
-- Projects with neither an explicit config nor a supported project-root config retain the generic `.matrix/types/matrix-runtime.d.ts` generation from Matrix configuration and public environment keys. Other hosts and arbitrary config basenames are not supported yet. A successfully resolved config without a Matrix plugin also retains this generic generation (using Matrix settings, not host-specific prefixes or scopes); an active plugin with `types: false` disables generation. Existing stale declaration files are not automatically deleted.
+### Configuration and compatibility
 
-Preparation and builds generate `ImportMetaEnv` and `matrix.config` declarations without environment values. `matrix prepare` honors `types: false` and runs even in Vitest. For build-time defaults and explicit overrides, see [plugin options](../reference/plugins.md#plugin-options). Add the generated directory to each project's `tsconfig.json`:
+- Discovery checks only the project root: `electron.vite.config.*` takes priority over `vite.config.*`. Multiple matches require an explicit choice. Set `projects.desktop.configFile` (for example, `'config/electron.vite.config.ts'`) relative to the project root, using a supported JS/TS config basename. Missing, unsupported, or failing explicit configs are errors. This setting does not change target commands; scope stays in the build plugin config.
+- **Output boundary:** the resolved host root and declaration output must stay within `project.root`, including through symlinks; escaping or dangling links fail before writes. To migrate, set `project.root` to the shared host directory and use `configFile` for a config stored elsewhere. Nested host roots and internal custom outputs work; external outputs are rejected. Standalone explicit generation is unchanged.
+- Shared collection supports standard Vite/electron-vite dev/build targets. Custom targets and other hosts retain existing plugin behavior. Collection does not parse target command flags such as `--mode` or `--config`; an active plugin that adds uncollected fields or changes scope, prefixes, output, or schema fails rather than replacing the contract.
+- Explicit `matrix prepare` falls back to Matrix settings and public environment keys in `.matrix/types/matrix-runtime.d.ts` when no supported config exists or a resolved config has no Matrix plugin. This fallback cannot discover host-specific prefixes or outputs.
+
+### Contract behavior
+
+- The locally installed host resolves each product/variant in both dev (`MATRIX_TARGET=dev`, `command=serve`, `NODE_ENV=development`) and build (`MATRIX_TARGET=build`, `command=build`, `NODE_ENV=production`) contexts. Configured `nodeEnv` overrides apply; `mode` is the selected Matrix environment. Electron main/preload use normal development-time build hooks. Product identity and version follow execution-plan rules.
+- Configuration code and hooks run for both contexts, adding startup work, with a 30-second timeout per evaluation. Collection itself starts no Electron process, server, or bundle build.
+- Inferred public fields missing from some products, variants, or contexts become optional. Explicit schema types, defaults, optionality, and validation are unchanged; schema fields need no runtime values. Runtime values remain active-product-only, respecting public prefixes and Electron scope boundaries.
+- Duplicate scopes, conflicting outputs/prefixes, changing scope sets, and configuration failures are rejected before writing: across all affected projects for `prepare`, or per collection group for dev/build. Contracts are rebuilt from current sources, so removed fields/products and empty configurations remove obsolete fields. Obsolete output files are not deleted automatically.
+
+Declarations contain `ImportMetaEnv` and `matrix.config` types, never environment values. `types: false` disables generation. Explicit `matrix prepare` runs even in Vitest; automatic dev/build collection follows the [plugin defaults and explicit opt-ins](../reference/plugins.md#plugin-options), including Vitest suppression and missing-context safeguards. Add the generated directory to each project's `tsconfig.json`:
 
 ```json
 {

diff --git a/docs/site/en/reference/cli.md b/docs/site/en/reference/cli.md
@@ -42,6 +42,8 @@ matrix prepare [product] [--env <environment>]
 matrix <custom-target> [product] [--env <environment>]
 ```
 
+Shared-project declaration generation for `prepare`, `dev`, and `build` is described in [type preparation](../guides/integrations.md#type-preparation).
+
 ## Static preflight
 
 `matrix doctor [--env <environment>]` checks all configured products, variants, and targets in the selected environment without running target/preparation commands, probing ports, generating types, or cleaning output. Configuration loading still evaluates the configuration file as usual.

diff --git a/docs/site/en/reference/configuration.md b/docs/site/en/reference/configuration.md
@@ -21,12 +21,12 @@ Use `matrix.config.ts` in the workspace root, export `defineMatrixConfig({...})`
 
 Preparation behavior is in [execution](../guides/execution.md#project-preparation). Supported host filenames and type generation are in [integration](../guides/integrations.md#type-preparation). Changing `configFile` does not change target commands.
 
-| Field        | Type / default                             | Purpose                                                                                                         |
-| ------------ | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `root`       | String; `.`                                | Project directory relative to the workspace root; commands run here.                                            |
-| `targets`    | Target map; required                       | Project commands; built-in names supply defaults, not commands.                                                 |
-| `prepare`    | String or non-empty string array; optional | Finite preparation commands, once per project per invocation.                                                   |
-| `configFile` | String; optional                           | Host config relative to the project root, loaded by `matrix prepare` and checked statically by `matrix doctor`. |
+| Field        | Type / default                             | Purpose                                                                                                                           |
+| ------------ | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `root`       | String; `.`                                | Project directory relative to the workspace root; commands run here.                                                              |
+| `targets`    | Target map; required                       | Project commands; built-in names supply defaults, not commands.                                                                   |
+| `prepare`    | String or non-empty string array; optional | Finite preparation commands, once per project per invocation.                                                                     |
+| `configFile` | String; optional                           | Host config relative to the project root, loaded for prepare/dev/build type collection and checked statically by `matrix doctor`. |
 
 ## Products
 

diff --git a/docs/site/en/reference/plugins.md b/docs/site/en/reference/plugins.md
@@ -26,6 +26,8 @@ Pass these options to `matrix()` from the Vite, Rollup, Webpack, or esbuild entr
 
 **Default behavior change:** without Matrix CLI context, automatic generation leaves declarations untouched, creates no output directory, and warns once per plugin instance. This applies to all adapters. Run the target through Matrix or use `matrix prepare`. Runtime configuration may be incomplete; opting into type generation does not restore missing context.
 
+For shared-project declarations in Matrix CLI dev/build, see [type preparation](../guides/integrations.md#type-preparation).
+
 Relative output paths resolve from Vite's resolved root or other adapters' working directory. The default is `.matrix/types/matrix-runtime.d.ts`, or `matrix-runtime-<scope>.d.ts` in the same directory for scoped builds. Include custom outputs in the project's `tsconfig.json`.
 
 ## Runtime fields

diff --git a/docs/site/zh-CN/guides/execution.md b/docs/site/zh-CN/guides/execution.md
@@ -50,7 +50,7 @@ export default {
 - 启用产物清理时，顺序为“清理目标输出目录 → 按需 prepare → 执行 target → 交付产物”。后续变体仍可能清理或移动输出目录，因此跨变体复用的准备文件应放在 target 输出目录之外；每次构建都需要生成的输出文件应放入 target 命令数组，而不是一次性的项目准备。
 - `target.prepare: false` 只跳过当前目标，不影响后续其他目标的准备需求。准备失败或取消会停止本次执行，不启动后续目标。
 - 准备命令在 project 根目录执行，使用全局配置、当前 dotenv 和 Shell 环境，不合并产品级 env 或注入产品／变体身份。不继承某个目标的默认 NODE_ENV，保留全局／外部环境中的值；注入 `MATRIX_PROJECT`、`MATRIX_ENV_NAME` 和 `MATRIX_TARGET=prepare`。
-- `matrix prepare [product]` 显式准备所选产品引用的项目（省略产品则处理所有产品），成功后生成现有 runtime 类型，不运行业务 target。构建插件的自动类型生成功能保持不变。
+- `matrix prepare [product]` 准备所选产品引用的项目（省略产品则处理所有产品），成功后生成 runtime 声明，不运行业务 target。共享项目收集规则见[类型准备](./integrations.md#类型准备)。
 - `matrix plan` 只展示准备步骤：JSON 的 `preparations` 包含命令、工作目录、环境和 `beforeTask`；`doctor` 执行静态预检，两者均不执行准备命令。
 
 `project.prepare` 与名为 `prepare` 的普通 target 是不同概念。准备阶段本身不会递归触发准备，也不支持依赖、持续服务或产物交付选项。