Add active-timeline opt-in and compile into app-created projects

CHANGELOG.md

@@ -8,6 +8,9 @@ All notable changes to capcut-cli are documented here. The format follows [Keep
 
 ### Added
 
+- `--active-timeline` explicitly follows a validated `Timelines/project.json` pointer on app builds without a verified storage fixture (#50). Invalid, deleted, symlinked or conflicting selected timelines are refused; normal defaults and write guards remain unchanged. Writes keep root and active IDs and preserve other timelines.
+- `compile --into <project>` populates an existing empty project created in CapCut (#52). It preserves project identity, per-document app markers and unknown settings, stages content-correct media, and commits imported-media registration with timeline writes. Failed copies and commits clean up only newly owned assets; the shared store index is never rewritten. `--check`, `--plan` and `--dry-run` validate both spec and destination without writing. Nested layouts require active selection. Desktop acceptance on these opt-in paths remains unverified.
+
 - `describe --compact` emits a small command discovery index with names, summaries, usage, and write status. `describe --command <name>` returns complete contracts for selected commands; repeat the flag for several names. The full v2 command contract remains the default. Python client v0.1.3 forwards these options through `capcut.describe(compact=True, command="compile")`.
 
 ### Fixed

README.md

@@ -105,10 +105,21 @@ The host reads a draft and passes its JSON as tool input. The component itself h
 
 ## Release notes
 
-> **New in v0.28.0:** compact command discovery and selection by name for agents; Windows command-path quoting fixed in Python client v0.1.3; and Python client CI on Linux, macOS, and Windows. Full details in the [changelog](./CHANGELOG.md).
+> **New in v0.28.0:** opt-in active-timeline selection; compilation into empty app-created projects; compact command discovery and selection by name for agents; Windows command-path quoting fixed in Python client v0.1.3; and Python client CI on Linux, macOS, and Windows. Full details in the [changelog](./CHANGELOG.md).
 
 > **New in v0.27.0:** content-safe media replacement; automatic import registration after replacement and relink; recursive, ambiguity-safe relinking; exact fractional-second compile boundaries; operation preflight and failed-build cleanup; payload-bound queue IDs; canonical project locks; bounded queue results; and local OTIO file/relative references. Full details in the [changelog](./CHANGELOG.md).
 
+For an existing nested project, use `capcut diagnose <project> --active-timeline` to inspect the selected document before editing. The opt-in follows the pointer on unverified builds and refuses invalid or conflicting selected documents; it does not bypass write guards.
+
+To populate a project that CapCut already owns, create an empty project in the app and quit CapCut, then run:
+
+```sh
+capcut compile spec.json --into /path/to/app-created-project --active-timeline --check
+capcut compile spec.json --into /path/to/app-created-project --active-timeline
+```
+
+Omit `--active-timeline` for a flat project without `Timelines/`. Every root and active mirror must be empty. The project keeps its name and registration; canvas and frame rate change only when supplied in the spec. Imported media is staged under the project, with registration and timeline backups committed together. Reopen, save, close and reopen in CapCut to check that edits persist. Automated safety tests cover these paths; desktop acceptance on your app build remains unverified.
+
 ## Built with capcut-cli
 
 - [OpenChatCut](https://github.com/0xsline/OpenChatCut) — exports an agent-edited timeline, local media, audio, and captions into a real CapCut / JianYing draft for review and rendering.

README.zh-CN.md

@@ -82,7 +82,7 @@ Claude Code 也可以把它作为插件加载：
 
 ## 发布说明
 
-> **v0.28.0 新增：** 精简的命令发现索引与按命令名筛选；Python 客户端 v0.1.3 修复 Windows 命令路径的引号解析，并在 Linux、macOS、Windows 上运行客户端 CI。详见 [更新日志](./CHANGELOG.md)。
+> **v0.28.0 新增：** 显式选择活动时间线、向应用创建的空项目编译，以及精简的命令发现索引与按命令名筛选；Python 客户端 v0.1.3 修复 Windows 命令路径的引号解析，并在 Linux、macOS、Windows 上运行客户端 CI。详见 [更新日志](./CHANGELOG.md)。
 
 > **v0.27.0 新增：** 按文件内容安全替换媒体；替换和重链接后自动更新媒体导入登记；递归搜索并报告同名歧义；精确处理小数秒时间边界；编译前校验操作并清理失败输出；将队列 ID 绑定到任务参数；统一项目锁；限制队列输出；以及解析 OTIO 的本地文件 URL 和相对路径。完整说明见[更新日志](./CHANGELOG.md)。
 
@@ -95,6 +95,17 @@ Claude Code 也可以把它作为插件加载：
 项目描述须经其维护者确认。收录不代表背书或关联。
 
 
+使用 `capcut diagnose <project> --active-timeline` 检查嵌套项目中的活动时间线。此显式选项依据 `Timelines/project.json` 选择文档；无效、已删除、符号链接或相互冲突的文档会被拒绝，现有写入保护仍然生效。
+
+若要填充 CapCut 已创建的项目，先在应用中创建空项目并退出应用，然后运行：
+
+```sh
+capcut compile spec.json --into /path/to/app-created-project --active-timeline --check
+capcut compile spec.json --into /path/to/app-created-project --active-timeline
+```
+
+没有 `Timelines/` 的平面项目请省略 `--active-timeline`。所有根目录和活动时间线镜像必须为空；保留项目名称、身份和注册信息，只有 spec 明确指定时才修改画布和帧率。媒体写入项目的 assets 目录，时间线与媒体注册信息一起备份和提交。`--check`、`--plan`、`--dry-run` 均不写入。请在应用中打开、保存、关闭并重新打开，确认编辑保留；自动测试覆盖写入安全性，尚未验证此路径在各应用版本中的桌面往返行为。
+
 ## 常用命令
 
 默认输出 JSON（可管道给 `jq`）；加 `-H` 显示人类可读表格。加 `--jianying` 使用剪映枚举命名空间。运行 `capcut <command> --help` 查看完整参数。