feat: add preset include filters and safe apply command

README.md

@@ -92,7 +92,7 @@ package manager from the current npm user agent and falls back to npm.
 An unknown explicit `--from` value exits with an error; it never switches to
 interactive selection. Run `preset --list` to see registered IDs.
 
-`--dry-run` prints a JSON creation plan without cloning repositories, running
+`init --dry-run` prints a JSON creation plan without cloning repositories, running
 generators, resolving npm versions, or changing project files. Remote config
 URLs are still fetched and validated. `--yes` skips only the confirmation for
 replacing existing target files; official generators keep their own prompts.
@@ -101,6 +101,17 @@ Private presets are generated in a temporary directory before replacing the
 target. Original target files are backed up while an official generator runs
 and restored if it fails or exits without creating a project.
 
+## Apply presets to existing projects
+
+```bash
+preset apply .agents/skills --from https://example.com/skills.json --include code-review --include testing
+preset apply .agents/skills --from ./skills.json --dry-run
+```
+
+`apply` adds missing files, skips identical files, and fails on conflicts before writing. It preserves unrelated files and does not automatically rewrite `package.json.name`. It accepts JSON presets, including registered private configs. `--include` is repeatable on both `init` and `apply`, replaces the config's `include` list, and keeps configured exclusions active.
+
+`apply --dry-run` generates temporary files to report real additions and conflicts, so it clones the source and may resolve workspace dependencies. `init --dry-run` remains a plan-only preview. Neither changes target files. See [Preset configs](docs/preset-configs.md) for validation and rollback limits.
+
 ## Official generators
 
 Official generators remain responsible for their own prompts, dependencies,
@@ -145,7 +156,7 @@ starter into a new project:
 preset init my-docs --from https://example.com/preset.json
 ```
 
-Supported operations include selecting a monorepo directory, excluding files,
+Supported operations include selecting a monorepo directory, including or excluding files,
 writing files, replacing text, merging JSON, and resolving `workspace:`
 dependencies. See [Preset configs](docs/preset-configs.md) and the published
 [schema](https://preset.js.org/schema/preset.schema.json).

docs/local-debugging.md

@@ -48,7 +48,7 @@ target/release/preset init demo --from vite --dry-run
 target/release/preset init demo --from ./preset.json --dry-run
 ```
 
-`--dry-run` prints the creation plan as JSON and does not run external commands
+`init --dry-run` prints the creation plan as JSON and does not run external commands
 or modify the target. Remote config URLs are fetched and validated. Unknown
 `--from` values fail immediately instead of starting an interactive fallback.
 
@@ -142,6 +142,22 @@ reset the package name. Test the public delivery path with an HTTPS URL:
 
 See [Preset configs](preset-configs.md) for the contract and limits.
 
+## Apply and selection checks
+
+```bash
+"$PRESET_BIN" apply .agents/skills --from ./skills.json --include code-review --dry-run
+"$PRESET_BIN" apply .agents/skills --from ./skills.json --include code-review
+```
+
+Run from a temporary project. Check that only the selected skill appears and an unrelated local file survives. Repeat the command: identical files should move from `add` to `skip`. Edit one installed file and repeat: the command must exit nonzero, report a conflict, and leave all target files intact. `apply --dry-run` downloads and materializes the preset in temporary storage but must not create a missing target or its parents.
+
+Automated CLI and transaction tests cover empty/missing selections, exclusion precedence, CLI overrides, symbolic links, conflicts, and rollback after partial publication:
+
+```bash
+cargo test --all-targets
+cargo clippy --all-targets -- -D warnings
+```
+
 ## Private preset test
 
 Create a local JSON file outside the repository, for example

docs/preset-configs.md

@@ -63,12 +63,52 @@ Add `$schema` for editor completion and validation:
 `version` must be `1`. `source.repo` is required. `source.directory` selects a
 subdirectory inside the cloned repository and defaults to the repository root.
 
+## Select files with include and exclude
+
+`include` lists exact files or directories relative to `source.directory`. Directories include their descendants; paths are not globs. Omit `include` to select all source files. With both fields present, `exclude` takes precedence. A selected directory is not flattened in the output.
+
+```json
+{
+  "version": 1,
+  "source": {
+    "repo": "https://github.com/example/team-resources.git",
+    "directory": "skills"
+  },
+  "include": ["code-review", "testing"],
+  "exclude": ["testing/fixtures"]
+}
+```
+
+An empty or null `include`, a missing selected path, or a selection with no files after exclusions fails. Symbolic links and paths outside the source are rejected. When `include` is present, file operations must stay within that selection and cannot recreate excluded files. Without `include`, existing transformation behavior is unchanged.
+
+Repeat `--include` on `init` or `apply` to replace the entire config selection. Configured exclusions still apply. This option requires a JSON preset; it is not passed to official generators.
+
+```bash
+preset apply .agents/skills --from ./skills.json --include code-review --include writing
+```
+
+A static website can publish a base JSON config and turn checked items into repeated `--include` arguments. Department presets can keep their selections in JSON.
+
+## Add files to an existing project
+
+```bash
+preset apply .agents/skills --from ./skills.json --dry-run
+preset apply .agents/skills --from ./skills.json
+```
+
+`apply` accepts a local/remote JSON config or a registered private preset backed by a config. It adds missing files, skips identical files, and reports differing content or file types as conflicts before writing anything. On Unix, executable permission differences also count as conflicts. Unrelated files remain intact, and `package.json.name` is not automatically rewritten. Empty directories alone are not installed.
+
+The command prints JSON with `add`, `skip`, and `conflicts`; conflicts produce a nonzero exit status in both normal and dry-run modes. `apply` has no `--yes` or overwrite mode. It rejects symbolic links along destination paths and does not follow them when publishing files. It does not synchronize deletions or automatically update modified files.
+
+Unlike `init --dry-run`, `apply --dry-run` clones the source and runs configured transformations in temporary storage to compare actual files. It may query npm if workspace resolution is enabled, but does not create target directories or modify target files. Normal publication errors roll back this run's additions. Recovery failures report retained paths; forced termination or a system crash can leave partial additions. Avoid editing destination paths concurrently with an apply operation.
+
 ## Operations
 
 After selecting the source directory, Create Preset copies its files with
-`exclude` applied, then runs the remaining operations:
+`include` and `exclude` applied, then runs the remaining operations:
 
-- `exclude` skips repository paths before copying.
+- `include` selects exact source-relative files or directories; omission selects all.
+- `exclude` removes paths from that selection before copying.
 - `write` creates or replaces a UTF-8 text file from an array of lines.
 - `replace` replaces every exact text match in an existing UTF-8 file.
 - `json` applies a recursive merge patch to an existing JSON object. A `null`
@@ -149,7 +189,7 @@ in that case.
 The runtime enforces these boundaries:
 
 - remote and local config files are limited to 1 MiB;
-- config operation counts are limited to 1,000;
+- config operation counts (including include/exclude paths) are limited to 1,000;
 - unknown fields and unsupported versions are rejected;
 - paths must stay relative to the generated project;
 - source symlinks are rejected;

docs/private-presets.md

@@ -114,3 +114,24 @@ preserved.
 
 For a `config` entry, the referenced plan controls the checkout and file
 transformations. See [Preset configs](preset-configs.md).
+
+## Apply a team preset
+
+Register a config-backed preset for a reusable team selection:
+
+```json
+{
+  "tech": "skills",
+  "name": "team-skills",
+  "config": "./skills.json"
+}
+```
+
+After adding this entry to the bound manifest, use its name to add files to a project:
+
+```bash
+preset apply .agents/skills --from team-skills
+preset apply .agents/skills --from team-skills --include code-review --dry-run
+```
+
+`apply` accepts `config` entries, not bare `repo` entries or official generators. It preserves unrelated files, skips identical files, and stops on conflicts. Repeated `--include` arguments replace the config selection; exclusions remain active. See [Preset configs](preset-configs.md) for the JSON format and preview behavior.

docs/src/contents/en/examples/skills.mdx

@@ -20,12 +20,16 @@ If the agent reads skills from another location, change the target path in the c
 
 ## Existing skills
 
-**For a nonempty target, the CLI asks to replace the entire directory. It does not merge individual skills.** Generate into a new temporary directory first:
+Use `apply` to add skills while preserving the existing directory:
 
 ```bash
-pnpm create preset init skills-preview --from ./presets/skills.json
+pnpm create preset apply .agents/skills --from ./presets/skills.json --include code-review --include writing
 ```
 
-Check the files, then copy the skill folders needed into the project. Compare same-name files before overwriting them. Later updates can be fetched and compared the same way. Create Preset does not sync updates automatically or link skills into other agents' directories.
+Repeated `--include` arguments replace the config's selection. Configured `exclude` paths still apply. Omit `--include` to use the config's list, or select all source files if it has no list.
+
+Add `--dry-run` to generate temporary files and compare them before installation. Identical files are skipped. Different content, file types, or Unix executable permissions are reported as conflicts before any target writes. Resolve conflicts manually; `apply` does not overwrite or delete existing files. `init` still replaces a nonempty target after confirmation.
+
+Create Preset does not sync updates automatically or link skills into other agents' directories. See [Preset configs](/guide/preset-configs) for selection and rollback details.
 
 Each preset reads one source repository. Skills from several repositories need collecting in one repository before this config can distribute them together.

docs/src/contents/en/guide/getting-started.mdx

@@ -79,6 +79,16 @@ preset init my-docs --from ./preset.json --yes
 
 `--yes` skips only Create Preset's replacement confirmation. Official generators keep their own prompts.
 
+## Add files to an existing project
+
+Use a JSON preset with `apply` to preserve unrelated files and stop on conflicts:
+
+```bash
+preset apply .agents/skills --from ./skills.json --include code-review --include testing
+```
+
+Add `--dry-run` to compare actual generated files without modifying the target. This preview clones the source into temporary storage. See [Preset configs](/guide/preset-configs) for selection and conflict rules.
+
 ## Change the language
 
 Create Preset follows the system language and supports English, Simplified Chinese, Traditional Chinese, and Japanese. Set `PRESET_LANG` to choose a language explicitly. For example, switch to Japanese in a macOS or Linux terminal:

docs/src/contents/en/guide/preset-configs.md

@@ -45,12 +45,52 @@ This config copies `apps/starter` from the repository, excludes test files, writ
 
 File operations run in this order:
 
-- `exclude` skips paths before copying the selected template.
+- `include` selects exact source-relative files or directories; omission selects all.
+- `exclude` removes paths from that selection before copying.
 - `write` creates or replaces a UTF-8 text file from an array of lines.
 - `replace` replaces every exact text match in an existing UTF-8 file.
 - `json` applies a recursive merge patch to an existing JSON object; a `null` value removes a key.
 
-The generated `package.json.name` is set to the project name.
+With `init`, the generated `package.json.name` is set to the project name.
+
+## Select files with include and exclude
+
+`include` lists exact files or directories relative to `source.directory`. Directories include their descendants; paths are not globs. Omit `include` to select all source files. With both fields present, `exclude` takes precedence. A selected directory is not flattened in the output.
+
+```json
+{
+  "version": 1,
+  "source": {
+    "repo": "https://github.com/example/team-resources.git",
+    "directory": "skills"
+  },
+  "include": ["code-review", "testing"],
+  "exclude": ["testing/fixtures"]
+}
+```
+
+An empty or null `include`, a missing selected path, or a selection with no files after exclusions fails. Symbolic links and paths outside the source are rejected. When `include` is present, file operations must stay within that selection and cannot recreate excluded files. Without `include`, existing transformation behavior is unchanged.
+
+Repeat `--include` on `init` or `apply` to replace the entire config selection. Configured exclusions still apply. This option requires a JSON preset; it is not passed to official generators.
+
+```bash
+preset apply .agents/skills --from ./skills.json --include code-review --include writing
+```
+
+A static website can publish a base JSON config and turn checked items into repeated `--include` arguments. Department presets can keep their selections in JSON.
+
+## Add files to an existing project
+
+```bash
+preset apply .agents/skills --from ./skills.json --dry-run
+preset apply .agents/skills --from ./skills.json
+```
+
+`apply` accepts a local/remote JSON config or a registered private preset backed by a config. It adds missing files, skips identical files, and reports differing content or file types as conflicts before writing anything. On Unix, executable permission differences also count as conflicts. Unrelated files remain intact, and `package.json.name` is not automatically rewritten. Empty directories alone are not installed.
+
+The command prints JSON with `add`, `skip`, and `conflicts`; conflicts produce a nonzero exit status in both normal and dry-run modes. `apply` has no `--yes` or overwrite mode. It rejects symbolic links along destination paths and does not follow them when publishing files. It does not synchronize deletions or automatically update modified files.
+
+Unlike `init --dry-run`, `apply --dry-run` clones the source and runs configured transformations in temporary storage to compare actual files. It may query npm if workspace resolution is enabled, but does not create target directories or modify target files. Normal publication errors roll back this run's additions. Recovery failures report retained paths; forced termination or a system crash can leave partial additions. Avoid editing destination paths concurrently with an apply operation.
 
 ## Preview and replace files
 
@@ -96,7 +136,7 @@ Resolution covers `dependencies`, `devDependencies`, `peerDependencies`, and `op
 
 Use HTTPS for remote configs and their source repositories. HTTP is also accepted for trusted private networks, with a CLI warning. Remote configs cannot reference local files or SSH repository URLs.
 
-Config files are limited to 1 MiB, with at most 1,000 operations in total across `exclude`, `write`, `replace`, and `json`. The CLI rejects unknown fields, unsupported versions, paths outside the generated project, and source symlinks. Config values never evaluate JavaScript or invoke a shell. The JSON Schema helps catch errors in the editor; the CLI validates the config again when it runs.
+Config files are limited to 1 MiB, with at most 1,000 operations in total across `include`, `exclude`, `write`, `replace`, and `json`. The CLI rejects unknown fields, unsupported versions, paths outside the generated project, and source symlinks. Config values never evaluate JavaScript or invoke a shell. The JSON Schema helps catch errors in the editor; the CLI validates the config again when it runs.
 
 ## Blackwork example
 

docs/src/contents/en/guide/private-presets.md

@@ -68,6 +68,27 @@ Each entry uses either `repo` or `config`. The relative path above starts from t
 
 For custom stack labels and colors, use the format with a `version` field described in the [private preset reference](https://github.com/preset-cli/create-preset/blob/main/docs/private-presets.md).
 
+## Apply a team preset
+
+Register a config-backed preset for a reusable team selection:
+
+```json
+{
+  "tech": "skills",
+  "name": "team-skills",
+  "config": "./skills.json"
+}
+```
+
+After adding this entry to the bound manifest, use its name to add files to a project:
+
+```bash
+preset apply .agents/skills --from team-skills
+preset apply .agents/skills --from team-skills --include code-review --dry-run
+```
+
+`apply` accepts `config` entries, not bare `repo` entries or official generators. It preserves unrelated files, skips identical files, and stops on conflicts. Repeated `--include` arguments replace the config selection; exclusions remain active. See [Preset configs](/guide/preset-configs) for the JSON format and preview behavior.
+
 ## Files kept in the new project
 
 When using `repo` directly, the CLI removes only the cloned `.git` metadata. Lockfiles, licenses, workflows, skills, and `AGENTS.md` files are preserved. If a `package.json` exists, its `name` is updated to match the new project name.

docs/src/contents/zh/examples/skills.mdx

@@ -20,12 +20,16 @@ order: 2
 
 ## 已有 Skills 的处理
 
-**目标目录已有文件时，CLI 会询问是否替换整个目录，不会逐个合并 Skill。** 为保留项目中的现有内容，可以先生成到一个新的临时目录：
+使用 `apply` 追加需要的 Skills，保留目录中的现有内容：
 
 ```bash
-pnpm create preset init skills-preview --from ./presets/skills.json
+pnpm create preset apply .agents/skills --from ./presets/skills.json --include code-review --include writing
 ```
 
-检查生成内容后，将需要的 Skill 文件夹复制到项目中；同名文件需要比较后再决定是否覆盖。源仓库更新后，也可以通过临时目录比较新旧文件。Create Preset 不会自动同步更新，也不会把 Skills 链接到其他 agent 的目录。
+多个 `--include` 参数会整体覆盖配置中的选择清单，配置中的 `exclude` 继续生效。省略 `--include` 时使用配置清单；配置也没有清单时，选择全部源文件。
+
+添加 `--dry-run`，可以先在临时目录生成文件并比较。相同文件会跳过，内容、文件类型或 Unix 可执行权限不同则在写入前报告冲突。冲突需要手动处理，`apply` 不覆盖或删除已有文件。`init` 仍然会在确认后替换整个非空目标目录。
+
+Create Preset 不会自动同步更新，也不会把 Skills 链接到其他 agent 的目录。选择规则和回滚边界见 [Preset 配置](/zh/guide/preset-configs)。
 
 一份 Preset 只读取一个源仓库。如果常用 Skills 分散在多个仓库，需要先整理到同一个仓库，再用这份配置分发。

docs/src/contents/zh/guide/getting-started.mdx

@@ -79,6 +79,16 @@ preset init my-docs --from ./preset.json --yes
 
 `--yes` 只跳过 Create Preset 的替换确认，官方脚手架仍保留自己的提问。
 
+## 向已有项目追加文件
+
+使用 JSON 配置运行 `apply`，保留无关文件，遇到冲突时停止：
+
+```bash
+preset apply .agents/skills --from ./skills.json --include code-review --include testing
+```
+
+添加 `--dry-run` 可比较真实生成文件而不修改目标。这种预览会在临时目录克隆源仓库。选择和冲突规则见 [Preset 配置](/zh/guide/preset-configs)。
+
 ## 切换语言
 
 Create Preset 默认跟随系统语言，支持英文、简体中文、繁体中文和日文。用 `PRESET_LANG` 指定语言，例如在 macOS 或 Linux 中切换为日文：