diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 30ceb9e..2f958d6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -92,3 +92,27 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm test
+
+  python-client:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: '3.9'
+          - os: ubuntu-latest
+            python: '3.14'
+          - os: windows-latest
+            python: '3.9'
+          - os: windows-latest
+            python: '3.14'
+          - os: macos-latest
+            python: '3.14'
+    runs-on: ${{ matrix.os }}
+    name: Python client (${{ matrix.os }}, ${{ matrix.python }})
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m unittest discover -s python/tests -v
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0610bff..1569867 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,19 @@ All notable changes to capcut-cli are documented here. The format follows [Keep
 
 ## [Unreleased]
 
+## [0.28.0] — 2026-10-03
+
+### 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
+
+- Python client v0.1.3 parses quoted Windows `CAPCUT_CLI` paths without retaining surrounding quotes or losing backslashes. Escaped quotes, trailing backslashes, and empty arguments follow Windows argv quoting; malformed quotes fail before spawning a process. POSIX command quoting and shell-free execution remain unchanged. Python client regression tests now run on Linux, macOS, and Windows, including Python 3.9 and 3.14.
+
 ## [0.27.0] — 2026-10-03
 
 ### Added
diff --git a/README.md b/README.md
index 059426f..5350520 100644
--- a/README.md
+++ b/README.md
@@ -105,9 +105,20 @@ The host reads a draft and passes its JSON as tool input. The component itself h
 
 ## Release notes
 
+> **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).
 
-> **Fixed in v0.26.1:** ratio-only compile canvases and full source-media durations; JSON-escaped Windows fixture redaction with automatic leak verification; and active-timeline edits on the fixture-backed CapCut 8.7.0 Windows layout. A patched desktop round-trip remains pending. 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
 
@@ -136,6 +147,8 @@ JSON by default (pipe to `jq`); add `-H` for a human-readable table. Pass `--jia
 | **Long-form → short** | `cut` · `detect-scenes` (ffmpeg scene-cut detection) · `detect-silence` · `detect-retakes` (repeated takes) |
 | **Automation** | `serve` (stateless JSONL runner) · `migrate` · `doctor` · `sync-timelines` (8.7 mirror repair) |
 
+`capcut describe --compact` lists command names, summaries, usage, and write status. Fetch a complete contract with `capcut describe --command compile`; repeat `--command` for several commands. Plain `capcut describe` still emits the full registry.
+
 **Full reference** for every command, option, and exit code: **[docs/command-reference.md](./docs/command-reference.md)** (简体中文: [docs/command-reference.zh-CN.md](./docs/command-reference.zh-CN.md)).
 
 ## Sponsor
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 358d2ed..ec02a4d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -82,9 +82,9 @@ Claude Code 也可以把它作为插件加载：
 
 ## 发布说明
 
-> **v0.27.0 新增：** 按文件内容安全替换媒体；替换和重链接后自动更新媒体导入登记；递归搜索并报告同名歧义；精确处理小数秒时间边界；编译前校验操作并清理失败输出；将队列 ID 绑定到任务参数；统一项目锁；限制队列输出；以及解析 OTIO 的本地文件 URL 和相对路径。完整说明见[更新日志](./CHANGELOG.md)。
+> **v0.28.0 新增：** 显式选择活动时间线、向应用创建的空项目编译，以及精简的命令发现索引与按命令名筛选；Python 客户端 v0.1.3 修复 Windows 命令路径的引号解析，并在 Linux、macOS、Windows 上运行客户端 CI。详见 [更新日志](./CHANGELOG.md)。
 
-> **v0.26.1 修复：** 仅指定比例的编译画布与完整源媒体时长；对 JSON 转义的 Windows 路径进行 fixture 脱敏并自动检查泄漏；以及基于真实 fixture 的 CapCut 8.7.0 Windows 活动时间线编辑。修复后的桌面应用往返验证仍待完成。完整说明见[更新日志](./CHANGELOG.md)。
+> **v0.27.0 新增：** 按文件内容安全替换媒体；替换和重链接后自动更新媒体导入登记；递归搜索并报告同名歧义；精确处理小数秒时间边界；编译前校验操作并清理失败输出；将队列 ID 绑定到任务参数；统一项目锁；限制队列输出；以及解析 OTIO 的本地文件 URL 和相对路径。完整说明见[更新日志](./CHANGELOG.md)。
 
 ## 使用 capcut-cli 构建
 
@@ -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` 查看完整参数。
@@ -113,6 +124,8 @@ Claude Code 也可以把它作为插件加载：
 | **长视频切短** | `cut` · `detect-scenes`（ffmpeg 场景切点检测）· `detect-silence` · `detect-retakes`（重复口播段落）|
 | **自动化** | `serve`（无状态 JSONL 执行器）· `migrate` · `doctor` · `sync-timelines`（8.7 时间线镜像修复）|
 
+`capcut describe --compact` 列出命令名、简介、用法和是否写入。`capcut describe --command compile` 返回指定命令的完整契约；重复 `--command` 可选择多个命令。不带选项的 `capcut describe` 仍输出完整注册表。
+
 **完整命令参考**（每个命令、参数与退出码）：**[docs/command-reference.zh-CN.md](./docs/command-reference.zh-CN.md)**（[英文原版](./docs/command-reference.md)）。
 
 ## 赞助
diff --git a/docs/command-reference.json b/docs/command-reference.json
index 35e2b03..60a64aa 100644
--- a/docs/command-reference.json
+++ b/docs/command-reference.json
@@ -1,6 +1,6 @@
 {
   "name": "capcut-cli",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "schema_version": 2,
   "description": "Edit CapCut/JianYing draft_content.json directly. JSON in, JSON out.",
   "global_flags": [
@@ -80,7 +80,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": false,
       "prerequisites": [],
       "output": {
@@ -103,7 +113,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": false,
       "prerequisites": [],
       "output": {
@@ -230,6 +250,15 @@
           "type": "path",
           "required": false,
           "description": "ffprobe binary."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -255,7 +284,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": false,
       "prerequisites": [],
       "output": {
@@ -293,6 +332,15 @@
           "type": "string",
           "required": false,
           "description": "Track or material type filter."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -317,7 +365,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": false,
       "prerequisites": [],
       "output": {
@@ -350,7 +408,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": true,
       "prerequisites": [],
       "output": {
@@ -383,7 +451,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": true,
       "prerequisites": [],
       "output": {
@@ -440,6 +518,15 @@
           "type": "time",
           "required": false,
           "description": "Shift only segments starting at or after this boundary; refuses a segment crossing it."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -474,7 +561,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": true,
       "prerequisites": [],
       "output": {
@@ -507,7 +604,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": true,
       "prerequisites": [],
       "output": {
@@ -545,7 +652,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": true,
       "prerequisites": [],
       "output": {
@@ -578,7 +695,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": true,
       "prerequisites": [],
       "output": {
@@ -629,6 +756,15 @@
             "vtt"
           ],
           "default": "srt"
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -676,6 +812,15 @@
           "type": "path",
           "required": false,
           "description": "Output path."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -728,6 +873,15 @@
             "markers"
           ],
           "default": "skip"
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -784,6 +938,15 @@
           "type": "path",
           "required": false,
           "description": "Template directory for --out."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -823,6 +986,15 @@
           "type": "string",
           "required": false,
           "description": "Track or material type filter."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -852,7 +1024,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": false,
       "prerequisites": [],
       "output": {
@@ -880,7 +1062,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": false,
       "prerequisites": [],
       "output": {
@@ -964,6 +1156,15 @@
           "type": "path",
           "required": false,
           "description": "ffprobe binary."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1060,6 +1261,15 @@
           "type": "path",
           "required": false,
           "description": "ffprobe binary."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1170,6 +1380,15 @@
           "type": "path",
           "required": false,
           "description": "Apply a make-preset style preset; explicit flags override preset values."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1273,6 +1492,15 @@
           "type": "path",
           "required": false,
           "description": "ffprobe binary."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1345,6 +1573,15 @@
           "type": "boolean",
           "required": false,
           "description": "Restore the full frame."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1388,6 +1625,15 @@
           "type": "path",
           "required": false,
           "description": "Output path."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1440,6 +1686,15 @@
           "type": "boolean",
           "required": false,
           "description": "Create a fresh same-type track directly above the source (the default)."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1496,6 +1751,15 @@
           "type": "boolean",
           "required": false,
           "description": "Close the removed time span across every track; refuses crossing segments."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1571,6 +1835,15 @@
             "hold"
           ],
           "default": "linear"
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1619,6 +1892,15 @@
           "type": "time",
           "required": false,
           "description": "Transition duration."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1748,6 +2030,15 @@
             "common_mask",
             "common_masks"
           ]
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -1791,6 +2082,15 @@
           "type": "boolean",
           "required": false,
           "description": "Remove background blur."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -2069,6 +2369,15 @@
           "type": "path",
           "required": false,
           "description": "Apply a make-preset style preset; explicit flags override preset values."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -2356,6 +2665,15 @@
           "type": "path",
           "required": false,
           "description": "Apply a make-preset style preset; explicit flags override preset values."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -2439,6 +2757,15 @@
           "type": "time",
           "required": false,
           "description": "Combo duration."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -2522,6 +2849,15 @@
           "type": "time",
           "required": false,
           "description": "Combo duration."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -2606,6 +2942,15 @@
           "type": "string",
           "required": false,
           "description": "Target track name."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -2640,7 +2985,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": true,
       "prerequisites": [],
       "output": {
@@ -2692,6 +3047,15 @@
           "type": "number",
           "required": false,
           "description": "Fade-out seconds."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -2735,6 +3099,15 @@
           "type": "number",
           "required": false,
           "description": "Cover timestamp in milliseconds."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -2820,6 +3193,15 @@
           "required": false,
           "description": "Apply to the whole timeline (start 0, duration = draft duration).",
           "default": false
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -2876,6 +3258,15 @@
           "type": "string",
           "required": false,
           "description": "Custom resource ID."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -2979,6 +3370,15 @@
           "type": "string",
           "required": false,
           "description": "Experimental: attach to one segment instead of the whole frame (segment ID)."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -3022,6 +3422,15 @@
           "type": "path",
           "required": false,
           "description": "Output path."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -3084,6 +3493,15 @@
           "type": "number",
           "required": false,
           "description": "Vertical position override."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -3122,6 +3540,15 @@
           "type": "path",
           "required": false,
           "description": "Output path."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -3178,6 +3605,15 @@
           "type": "boolean",
           "required": false,
           "description": "Commit only successful operations and exit 1 if any fail."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -3521,6 +3957,15 @@
           "required": false,
           "description": "Emphasis size for --highlight-words matches, as a multiplier on the cue's base font size.",
           "default": 1.2
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -3826,6 +4271,15 @@
           "type": "number",
           "required": false,
           "description": "Background vertical offset."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -3864,6 +4318,15 @@
           "type": "json",
           "required": false,
           "description": "Inline JSON or @file style ranges."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4098,6 +4561,15 @@
           "required": false,
           "description": "Emphasis size for --highlight-words matches, as a multiplier on the cue's base font size.",
           "default": 1.2
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4170,6 +4642,15 @@
           "type": "string",
           "required": false,
           "description": "Anthropic model."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4237,6 +4718,15 @@
           "type": "boolean",
           "required": false,
           "description": "Like --like, with the newest app-authored project in this draft's own drafts folder as the donor."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4294,6 +4784,15 @@
           "type": "string",
           "required": false,
           "description": "Target track name."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4355,6 +4854,15 @@
           "type": "boolean",
           "required": false,
           "description": "Remove chroma key."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4393,6 +4901,15 @@
           "type": "boolean",
           "required": false,
           "description": "Turn smart matting off: writes the documented flag-0 matting object on the segment's video material (cache fields kept)."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4417,7 +4934,17 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
+        }
+      ],
       "mutates": true,
       "prerequisites": [],
       "output": {
@@ -4472,6 +4999,15 @@
           "type": "path",
           "required": false,
           "description": "Draft store root when the draft does not live inside a known one."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4515,6 +5051,15 @@
           "type": "path",
           "required": false,
           "description": "Draft store root when the draft does not live inside a known one."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4589,6 +5134,15 @@
           "type": "boolean",
           "required": false,
           "description": "Copy each file this run relinks into the draft's assets/<kind>/ and point the material at the copy, so the repaired draft is portable (video/audio only; skipped under --dry-run — a copy is a side effect no draft write rolls back)."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4641,6 +5195,15 @@
           "type": "path",
           "required": false,
           "description": "ffprobe binary for duration/dimension detection."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -4680,6 +5243,15 @@
           "required": false,
           "description": "Timeline columns.",
           "default": 60
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -4830,10 +5402,123 @@
     },
     {
       "name": "describe",
-      "summary": "Emit the full command surface as JSON (agent tool spec).",
-      "usage": "capcut describe",
-      "positionals": [],
-      "options": [],
+      "summary": "Emit command contracts as JSON, optionally filtered by name or reduced to a compact discovery index.",
+      "usage": "capcut describe [--compact] [--command <name>]",
+      "positionals": [
+        {
+          "name": "name",
+          "type": "string",
+          "required": false
+        }
+      ],
+      "options": [
+        {
+          "name": "compact",
+          "flags": [
+            "--compact"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Emit a discovery index with names, summaries, usage, and write status."
+        },
+        {
+          "name": "command",
+          "flags": [
+            "--command"
+          ],
+          "type": "enum",
+          "required": false,
+          "description": "Describe only this command; repeat to select several.",
+          "values": [
+            "info",
+            "version",
+            "lint",
+            "tracks",
+            "segments",
+            "texts",
+            "set-text",
+            "shift",
+            "shift-all",
+            "speed",
+            "volume",
+            "trim",
+            "opacity",
+            "export-srt",
+            "export-ass",
+            "export-timeline",
+            "import-timeline",
+            "materials",
+            "segment",
+            "material",
+            "add-audio",
+            "tts",
+            "add-video",
+            "add-text",
+            "crop",
+            "cut",
+            "duplicate",
+            "remove",
+            "keyframe",
+            "transition",
+            "mask",
+            "bg-blur",
+            "text-style",
+            "restyle",
+            "text-anim",
+            "image-anim",
+            "add-sticker",
+            "mix-mode",
+            "audio-fade",
+            "add-cover",
+            "add-filter",
+            "bubble-text",
+            "add-effect",
+            "save-template",
+            "apply-template",
+            "make-preset",
+            "batch",
+            "import-srt",
+            "import-ass",
+            "text-ranges",
+            "caption",
+            "translate",
+            "migrate",
+            "add-sfx",
+            "chroma",
+            "matting",
+            "prune",
+            "register",
+            "rename",
+            "relink",
+            "timeline",
+            "projects",
+            "diff",
+            "concat",
+            "config",
+            "describe",
+            "completions",
+            "enums",
+            "catalogue",
+            "harvest-enums",
+            "doctor",
+            "diagnose",
+            "fixture",
+            "sync-timelines",
+            "restore",
+            "serve",
+            "decrypt",
+            "export",
+            "replace-media",
+            "init",
+            "quickstart",
+            "compile",
+            "render",
+            "detect-scenes",
+            "detect-silence",
+            "detect-retakes"
+          ]
+        }
+      ],
       "mutates": false,
       "prerequisites": [],
       "output": {
@@ -5034,6 +5719,15 @@
           "type": "string",
           "required": false,
           "description": "Effect id for an --add entry that carries both ids."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -5105,6 +5799,15 @@
           "type": "path",
           "required": false,
           "description": "Write a redacted JSON diagnostic bundle."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -5147,6 +5850,15 @@
           "type": "boolean",
           "required": false,
           "description": "Scan the finished bundle (SANITIZE_REPORT.json and README included) for residual home paths, emails, device ids and the account name, reporting file:line per finding and exiting non-zero on any. New bundles are checked automatically. With only a bundle directory as the argument, re-checks an existing bundle without rebuilding."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -5189,6 +5901,15 @@
           "type": "boolean",
           "required": false,
           "description": "Also reconcile the nested Timelines/<id>/ documents (draft_info.json, draft_content.json, template-2.tmp), each keeping its own GUID — the workaround verified on CapCut Mac 9.2.8 in issue #50, as an explicit opt-in. On Windows 8.7.0 active layouts only the selected timeline and root mirrors are reconciled, even with this flag. Timelines/project.json is never touched."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -5236,6 +5957,15 @@
           "type": "boolean",
           "required": false,
           "description": "List snapshots."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -5622,7 +6352,7 @@
     {
       "name": "compile",
       "summary": "Build a draft from a declarative JSON spec (the inverse of describe).",
-      "usage": "capcut compile <spec.json> [--out <draftdir>] [--template auto|bundled|<dir>] [--data <rows.jsonl|->] [--check | --plan]",
+      "usage": "capcut compile <spec.json> [--out <draftdir> | --into <project>] [--template auto|bundled|<dir>] [--data <rows.jsonl|->] [--check | --plan]",
       "positionals": [
         {
           "name": "spec.json",
@@ -5650,6 +6380,15 @@
           "required": false,
           "description": "Output path."
         },
+        {
+          "name": "into",
+          "flags": [
+            "--into"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "Populate an existing empty app-created project, preserving its identity and store registration. Incompatible with --out, --drafts, --template and --data."
+        },
         {
           "name": "drafts",
           "flags": [
@@ -5703,6 +6442,15 @@
           "type": "boolean",
           "required": false,
           "description": "With --data: build only the rows that validate and exit 1 if any fail (batch's contract)."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": true,
@@ -5835,6 +6583,15 @@
           "type": "boolean",
           "required": false,
           "description": "Stream ffmpeg's progress to stderr instead of buffering it."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
@@ -6104,6 +6861,15 @@
           "type": "boolean",
           "required": false,
           "description": "Force JSON output (the default; overrides -H)."
+        },
+        {
+          "name": "active_timeline",
+          "flags": [
+            "--active-timeline"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force."
         }
       ],
       "mutates": false,
diff --git a/docs/command-reference.md b/docs/command-reference.md
index 9e1873b..32b8966 100644
--- a/docs/command-reference.md
+++ b/docs/command-reference.md
@@ -71,7 +71,7 @@
 | `diff` | `capcut diff <project-a> <project-b>` | no | Compare two drafts (segments/materials/tracks added/removed/changed). |
 | `concat` | `capcut concat <project-a> <project-b> [--out <path>]` | yes | Append one draft onto another's timeline (id-safe), write to --out or in place. |
 | `config` | `capcut config` | no | Show the resolved config (.capcutrc + effective defaults). |
-| `describe` | `capcut describe` | no | Emit the full command surface as JSON (agent tool spec). |
+| `describe` | `capcut describe [--compact] [--command <name>]` | no | Emit command contracts as JSON, optionally filtered by name or reduced to a compact discovery index. |
 | `completions` | `capcut completions <bash\|zsh\|fish>` | no | Generate shell completions (bash|zsh|fish). |
 | `enums` | `capcut enums <category-flag> [--jianying]` | no | List enum slugs (transitions, masks, effects, ...) by category. |
 | `catalogue` | `capcut catalogue <query> [--kind <category>] [--limit <n>] [--jianying]` | no | Find a resource id by name across every category, harvested entries included. |
@@ -86,7 +86,7 @@
 | `export` | `capcut export <drafts-dir> --batch [options]` | yes | EXPERIMENTAL UI-automated render queue (macOS). |
 | `init` | `capcut init <name> [--template auto\|bundled\|<dir>] [--drafts <dir>] [--ratio <r> \| --width <px> --height <px>]` | yes | Create a new empty draft from a template. |
 | `quickstart` | `capcut quickstart <name> [--video <f>] [--audio <f>] [--srt <f>] [--drafts <dir>] [--template auto\|bundled\|<dir>] [--ratio <r> \| --width <px> --height <px>]` | yes | One-command first draft: create + add one input + lint + print the open-in-CapCut step. |
-| `compile` | `capcut compile <spec.json> [--out <draftdir>] [--template auto\|bundled\|<dir>] [--data <rows.jsonl\|->] [--check \| --plan]` | yes | Build a draft from a declarative JSON spec (the inverse of describe). |
+| `compile` | `capcut compile <spec.json> [--out <draftdir> \| --into <project>] [--template auto\|bundled\|<dir>] [--data <rows.jsonl\|->] [--check \| --plan]` | yes | Build a draft from a declarative JSON spec (the inverse of describe). |
 | `render` | `capcut render <project> [--out <preview.mp4>] [options]` | no | Render a low-res ffmpeg proxy preview (trim+speed+audio, --burn-captions); not CapCut's final render. |
 | `detect-scenes` | `capcut detect-scenes <video> [options]` | no | Detect scene-change cut points in a video (ffmpeg scene filter); prints cuts + segments to seed compile/cut. |
 | `detect-silence` | `capcut detect-silence <media> [options]` | no | Detect silence spans in a media file (ffmpeg silencedetect); prints silences + keep segments to seed compile/cut. |
diff --git a/docs/command-reference.zh-CN.md b/docs/command-reference.zh-CN.md
index e8ae8a9..25eb7aa 100644
--- a/docs/command-reference.zh-CN.md
+++ b/docs/command-reference.zh-CN.md
@@ -4,6 +4,8 @@
 
 > 英文版 [command-reference.md](./command-reference.md) 由 `npm run docs:commands` 从 v2 命令注册表自动生成，是权威版本；本页是它的人工维护中文翻译。命令有新增或变更时，请先重新生成英文版，再同步更新本翻译。用法（Usage）一列与命令名保持英文原样 —— 那就是你在终端里输入的内容。
 
+项目命令可使用 `--active-timeline`，显式依据 `Timelines/project.json` 选择活动时间线。`compile` 与 `import-timeline` 需同时指定 `--into`。无效、已删除、符号链接或相互冲突的活动文档会被拒绝；写入保护不会绕过，桌面应用往返接受情况仍未验证。
+
 | 命令 | 用法 | 修改草稿 | 说明 |
 |---|---|:---:|---|
 | `info` | `capcut info <project>` | 否 | 项目概览与素材汇总。 |
@@ -72,7 +74,7 @@
 | `diff` | `capcut diff <project-a> <project-b>` | 否 | 比较两个草稿（片段/素材/轨道的增、删、改）。 |
 | `concat` | `capcut concat <project-a> <project-b> [--out <path>]` | 是 | 把一个草稿追加到另一个的时间线末尾（ID 安全），写入 --out 或原地写入。 |
 | `config` | `capcut config` | 否 | 显示解析后的配置（.capcutrc + 生效的默认值）。 |
-| `describe` | `capcut describe` | 否 | 以 JSON 输出完整命令面（Agent 工具规范）。 |
+| `describe` | `capcut describe [--compact] [--command <name>]` | 否 | 以 JSON 输出命令契约；可按命令名筛选，或输出精简的命令发现索引。 |
 | `completions` | `capcut completions <bash\|zsh\|fish>` | 否 | 生成 shell 补全（bash\|zsh\|fish）。 |
 | `enums` | `capcut enums <category-flag> [--jianying]` | 否 | 按类别列出枚举 slug（转场、蒙版、特效等）。 |
 | `harvest-enums` | `capcut harvest-enums [<project> \| --sync \| --add <kind> <slug> <resource-id>] [--apply] [--catalogue <path>]` | 否 | 把商店资源 ID 学习进用户级素材目录：来源可以是单个草稿、整个草稿库（--sync），或手动添加（--add）。 |
@@ -86,7 +88,7 @@
 | `export` | `capcut export <drafts-dir> --batch [options]` | 是 | 实验性的 UI 自动化渲染队列（macOS）。 |
 | `init` | `capcut init <name> [--template <dir>] [--drafts <dir>]` | 是 | 从模板创建一个新的空草稿。 |
 | `quickstart` | `capcut quickstart <name> [--video <f>] [--audio <f>] [--srt <f>] [--drafts <dir>]` | 是 | 一条命令生成第一个草稿：创建 + 添加一个素材 + lint + 打印“在 CapCut 中打开”的步骤。 |
-| `compile` | `capcut compile <spec.json> [--out <draftdir>] [--data <rows.jsonl\|->] [--check \| --plan]` | 是 | 从声明式 JSON spec 构建草稿（describe 的逆操作）。 |
+| `compile` | `capcut compile <spec.json> [--out <draftdir> \| --into <project>] [--template auto\|bundled\|<dir>] [--data <rows.jsonl\|->] [--check \| --plan]` | 是 | 从声明式 JSON spec 构建草稿；`--into` 填充应用创建的空项目，保留项目身份和注册信息。 |
 | `render` | `capcut render <project> [--out <preview.mp4>] [options]` | 否 | 渲染低清 ffmpeg 代理预览（裁剪+变速+音频，--burn-captions）；支持 --crf / --video-bitrate，大型滤镜图自动走脚本文件；不是 CapCut 的最终渲染。 |
 | `detect-scenes` | `capcut detect-scenes <video> [options]` | 否 | 检测视频中的场景切换切点（ffmpeg scene 滤镜）；输出切点与片段列表，供 compile/cut 使用。 |
 | `detect-silence` | `capcut detect-silence <media> [options]` | 否 | 检测媒体文件中的静音区间（ffmpeg silencedetect）；输出静音与保留片段列表，供 compile/cut 使用。 |
diff --git a/docs/version-support.md b/docs/version-support.md
index 5074f0e..59fee0c 100644
--- a/docs/version-support.md
+++ b/docs/version-support.md
@@ -22,8 +22,8 @@ Run `capcut version <project>` for schema flags and `capcut diagnose <project> -
 | 8.4.0 (International, macOS) | reported | root → nested on first open | A draft created from a copy of a real 8.4 project (`init --template`), edited on the root files only, opened with every segment intact; the app then created `Timelines/project.json` and `Timelines/<id>/` itself from the root documents ([#50](https://github.com/renezander030/capcut-cli/issues/50), IrizaD, 2026-08-31). The bundled 6.5.0 template's draft was refused on the same build (see the 8.7 row). This is the materialisation direction v0.23's seeding relies on: a seeded draft ships no `Timelines/` and lets the app build it. |
 | 8.7.0 Windows, existing active timeline | fixture-tested storage selection; patched desktop round-trip pending | active document → root mirrors | The app-authored fixture from [#50](https://github.com/renezander030/capcut-cli/issues/50#issuecomment-5954728670), fpisasale / Spirito Digitale, 2026-10-02, is committed under `test/fixtures/capcut-8.7-windows-active/`. A valid active pointer selects the nested document; ordinary writes synchronize only that timeline and the root mirrors. Other timelines are preserved. The reporter observed nested content winning on open and close on 8.7.0.3685; a patched app round-trip remains pending. This evidence is specific to this storage shape and OS; the version-only registry retains its narrower existing evidence label. |
 | 8.7 Windows | reported + synthetic-tested + one real round-trip (negative with the bundled template, positive with a captured one) | adapter shipped; seed from the store | Issue #35 reports that `draft_content.json` edits may be ignored in favour of `template-2.tmp` / `draft_meta_info.json`. v0.11 discovers nested/string JSON timeline envelopes, selects modern storage, synchronizes every readable target, and provides `diagnose --bundle` and `fixture --out` (one-command sanitized bundle). v0.13 adds `sync-timelines` to reconcile an already-drifted mirror (plan by default, `--apply` to write); `diagnose` names it as the remedy. **Real validation ([#111](https://github.com/renezander030/capcut-cli/issues/111), 2026-09-10):** every draft built from the bundled 6.5.0 template — `quickstart` included — was refused by a real 8.7.0 Windows install as "from an unusual path"; `register --materials`, `relink` and `sync-timelines` changed nothing, because the cause is the template's stale markers (#67), not the path. Compiled against a template captured from the installed app, the same pipeline round-tripped on 9.3.0 (open, edit, save, close, reopen — edit persisted). v0.23 makes that the default: `init` / `quickstart` / `compile` seed new drafts from the store's newest app-authored project, and `migrate --from-store` restamps drafts already built. A reporter-provided real folder is still required before marking this fixture-tested. |
-| 9.2.8-beta4 (International, macOS) | reported | nested document authoritative — artifact pending | On this build the app reads `Timelines/<main_timeline_id>/draft_info.json`; the root `draft_info.json` / `template-2.tmp` are legacy mirrors, so a root-only write is a silent no-op from the app's point of view ([#50](https://github.com/renezander030/capcut-cli/issues/50), k12ktv, 2026-08-23). `sync-timelines --nested --apply` is the opt-in repair for a project whose nested document exists; the canonical flip stays gated on the requested fixture. Note that `init --template <app project>` used to copy the donor's `Timelines/` too, which is exactly how the report's new draft opened with the donor's empty timeline — v0.23 never carries `Timelines/` over. |
-| 9.3.0 (International, macOS) | reported | opens tool-built drafts seeded from a real project | The #111 reporter's real round-trip (above), and the shell-first recipe published at [zxypro1/capcut-shell-inject](https://github.com/zxypro1/capcut-shell-inject) (2026-09-11): create an empty project in the app, quit, write into that folder with this CLI, then `sync-timelines --nested --apply` and `register --materials --apply`. Both are the same finding — the app accepts a draft whose schema markers it wrote itself — and `--template auto` (the v0.23 default) is that recipe automated. Also on 9.3.0: a video material's blank `local_material_id` leaves the clip unresolvable with no in-app repair ([JmsLdrn/capcut-mcp#1](https://github.com/JmsLdrn/capcut-mcp/issues/1)); v0.23 links it at add time and `lint --fix` repairs existing drafts (`media-unlinked`). |
+| 9.2.8-beta4 (International, macOS) | reported | nested document authoritative — artifact pending | On this build the app reads `Timelines/<main_timeline_id>/draft_info.json`; the root `draft_info.json` / `template-2.tmp` are legacy mirrors, so a root-only write is a silent no-op from the app's point of view ([#50](https://github.com/renezander030/capcut-cli/issues/50), k12ktv, 2026-08-23). `sync-timelines --nested --apply` is the opt-in repair for a project whose nested document exists; automatic canonical selection stays gated on verified fixtures; `--active-timeline` explicitly selects a validated pointer on an unverified build, refusing conflicting selected documents. Note that `init --template <app project>` used to copy the donor's `Timelines/` too, which is exactly how the report's new draft opened with the donor's empty timeline — v0.23 never carries `Timelines/` over. |
+| 9.3.0 (International, macOS) | reported | opens tool-built drafts seeded from a real project | The #111 reporter's real round-trip (above), and the shell-first recipe published at [zxypro1/capcut-shell-inject](https://github.com/zxypro1/capcut-shell-inject) (2026-09-11): create an empty project in the app, quit, write into that folder with this CLI, then `sync-timelines --nested --apply` and `register --materials --apply`. `--template auto` (the v0.23 default) seeds a new project from app-authored settings. `compile --into` instead fills an existing empty app-created project while keeping its identity and shared store registration; nested projects also need `--active-timeline`. The new opt-in paths have automated safety coverage, with desktop round-trip acceptance still pending. Also on 9.3.0: a video material's blank `local_material_id` leaves the clip unresolvable with no in-app repair ([JmsLdrn/capcut-mcp#1](https://github.com/JmsLdrn/capcut-mcp/issues/1)); v0.23 links it at add time and `lint --fix` repairs existing drafts (`media-unlinked`). |
 | 9.x (other builds) | expected-compatible | unverified | `common_masks` may coexist with legacy mask fields. Use `version`, `diagnose`, and `migrate`; do not treat this row as desktop-app verification. |
 | 10.x (Mac and Windows) | reported | write-guarded | New builds are reported to reject tool-written drafts as corrupted ("内容已损坏"; pyJianYingDraft#177, #194 for the JianYing 10.8 counterpart; Mac primary file reported as `draft_info.json`, Jianying-CapCut2XML#4). No fixture exists; mutating commands refuse without `--force-write`. Fixture wanted — see the write guard section below. |
 
diff --git a/package-lock.json b/package-lock.json
index c9aa996..c1f886a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "capcut-cli",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "capcut-cli",
-      "version": "0.27.0",
+      "version": "0.28.0",
       "license": "MIT",
       "bin": {
         "capcut": "dist/index.js",
diff --git a/package.json b/package.json
index a9659f6..5583b7a 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "capcut-cli",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Independent, unofficial CLI to create and edit CapCut projects — build drafts from scratch, add video/audio/text, subtitles, timing, speed, volume, templates, cut long-form to shorts. No API needed. Not affiliated with ByteDance.",
   "type": "module",
   "bin": {
diff --git a/python/README.md b/python/README.md
index 26c359f..21b2c4b 100644
--- a/python/README.md
+++ b/python/README.md
@@ -24,7 +24,7 @@ print(capcut.run("lint", d["draft_path"])["summary"])
 
 - **关键字参数就是命令行选项**：`font_size=16` → `--font-size 16`，`karaoke=True` → `--karaoke`，列表会重复该选项，`None` / `False` 直接省略。
 - **位置参数原样传递**，每个参数就是一个 argv，中文、空格、引号都不需要转义。
-- 全部命令、参数和选项见[命令参考（中文）](https://github.com/renezander030/capcut-cli/blob/master/docs/command-reference.zh-CN.md)，或者在 Python 里 `capcut.describe()`。
+- 全部命令、参数和选项见[命令参考（中文）](https://github.com/renezander030/capcut-cli/blob/master/docs/command-reference.zh-CN.md)，或者在 Python 里 `capcut.describe()`。使用 `capcut.describe(compact=True)` 获取精简索引，`capcut.describe(command="compile")` 获取单个命令的完整契约（命令行需要 v0.28.0 或更新版本）。
 
 ## 出错时
 
@@ -39,6 +39,12 @@ except capcut.CommandError as e:
 
 不想抛异常就用 `capcut.run_raw(...)`，它返回 `Result`（`ok`、`status`、`data`、`error`）。找不到 `capcut` 命令时抛 `capcut.CliNotFound`，提示里有安装命令；也可以用环境变量 `CAPCUT_CLI` 指定，例如 `CAPCUT_CLI="node /path/to/capcut-cli/dist/index.js"`。
 
+Windows 上的 `CAPCUT_CLI` 使用双引号包住带空格的路径（不是 POSIX 单引号）。例如在 PowerShell 中：
+
+```powershell
+$env:CAPCUT_CLI = '"C:\Program Files\nodejs\node.exe" "C:\CapCut Tools\dist\index.js"'
+```
+
 ## 批量：`serve`
 
 `capcut serve` 是一个无状态的 JSONL 任务队列。从 Python 喂任务进去，拿回每个任务一条结果：
@@ -90,7 +96,7 @@ print(capcut.run("lint", d["draft_path"])["summary"])
 
 - **Keyword arguments are flags**: `font_size=16` → `--font-size 16`, `karaoke=True` → `--karaoke`, a list repeats the flag, `None` / `False` are dropped.
 - **Positional arguments pass through as they are**, one argv token each: text with spaces or quotes never needs escaping.
-- Every command, argument and option: [command reference](https://github.com/renezander030/capcut-cli/blob/master/docs/command-reference.md), or `capcut.describe()` from Python.
+- Every command, argument and option: [command reference](https://github.com/renezander030/capcut-cli/blob/master/docs/command-reference.md), or `capcut.describe()` from Python. Use `capcut.describe(compact=True)` for the small discovery index and `capcut.describe(command="compile")` for a complete command contract (requires CLI v0.28.0 or newer). A list selects several names.
 
 ### Errors
 
@@ -105,6 +111,14 @@ except capcut.CommandError as e:
 
 `capcut.run_raw(...)` never raises; it returns a `Result` (`ok`, `status`, `data`, `error`). A missing binary raises `capcut.CliNotFound` with the install line; `CAPCUT_CLI` can point at one explicitly, e.g. `CAPCUT_CLI="node /path/to/capcut-cli/dist/index.js"`.
 
+On Windows, quote paths with double quotes inside `CAPCUT_CLI`. For example in PowerShell:
+
+```powershell
+$env:CAPCUT_CLI = '"C:\Program Files\nodejs\node.exe" "C:\CapCut Tools\dist\index.js"'
+```
+
+When setting the variable from Python, `subprocess.list2cmdline([node_path, cli_path])` builds Windows quoting; `shlex.join(...)` is for POSIX. Command arguments are passed directly to the child process without shell expansion.
+
 ### Batch: `serve`
 
 `capcut serve` is a stateless JSONL job queue. Feed it jobs from Python and get one result per job:
diff --git a/python/capcut/__init__.py b/python/capcut/__init__.py
index d878a79..c55852b 100644
--- a/python/capcut/__init__.py
+++ b/python/capcut/__init__.py
@@ -29,7 +29,7 @@
 from dataclasses import dataclass, field
 from typing import Any, Iterable, List, Mapping, Optional, Sequence, Union
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 __all__ = [
     "CapcutError",
     "CliNotFound",
@@ -110,11 +110,55 @@ def stderr(self) -> str:
         return self.result.stderr
 
 
+def _split_windows_command(command: str) -> List[str]:
+    """Parse Windows argv quoting, preserving path backslashes (no shell expansion)."""
+    args: List[str] = []
+    index = 0
+    while index < len(command):
+        while index < len(command) and command[index] in " \t":
+            index += 1
+        if index == len(command):
+            break
+        token: List[str] = []
+        quoted = False
+        while index < len(command):
+            char = command[index]
+            if char in " \t" and not quoted:
+                break
+            if char == "\\":
+                start = index
+                while index < len(command) and command[index] == "\\":
+                    index += 1
+                count = index - start
+                if index == len(command) or command[index] != '"':
+                    token.append("\\" * count)
+                    continue
+                token.append("\\" * (count // 2))
+                if count % 2:
+                    token.append('"')
+                    index += 1
+                    continue
+                # An even run of backslashes leaves the quote structural.
+            if command[index] == '"':
+                if quoted and index + 1 < len(command) and command[index + 1] == '"':
+                    token.append('"')
+                    index += 2
+                    continue
+                quoted = not quoted
+            else:
+                token.append(command[index])
+            index += 1
+        if quoted:
+            raise ValueError("CAPCUT_CLI has an unclosed double quote")
+        args.append("".join(token))
+    return args
+
+
 def cli_command() -> List[str]:
-    """The argv prefix that runs capcut-cli: ``CAPCUT_CLI`` split like a shell would, else ``capcut`` on PATH."""
+    """The argv prefix: ``CAPCUT_CLI`` with platform quoting, else ``capcut`` on PATH."""
     configured = os.environ.get("CAPCUT_CLI", "").strip()
     if configured:
-        return shlex.split(configured, posix=(os.name != "nt"))
+        return _split_windows_command(configured) if os.name == "nt" else shlex.split(configured)
     found = shutil.which("capcut")
     if found:
         return [found]
@@ -220,9 +264,10 @@ def version() -> str:
     return result.stdout.strip()
 
 
-def describe() -> Any:
-    """The full command surface as JSON (``capcut describe``): names, usage, options, exit codes."""
-    return run("describe")
+def describe(*, compact: bool = False, command: Optional[Union[str, Sequence[str]]] = None) -> Any:
+    """Command contracts, or a compact discovery index. ``command`` selects one or several names."""
+    selected = list(command) if command is not None and not isinstance(command, str) else command
+    return run("describe", compact=compact, command=selected)
 
 
 def doctor(**flags: Any) -> Any:
diff --git a/python/pyproject.toml b/python/pyproject.toml
index 5767721..b0966d2 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "capcut"
-version = "0.1.2"
+version = "0.1.3"
 description = "Python client for capcut-cli: create and edit CapCut / JianYing (剪映) drafts from Python. JSON in, JSON out, no server."
 readme = "README.md"
 requires-python = ">=3.9"
diff --git a/python/tests/fake_capcut.py b/python/tests/fake_capcut.py
index 5b54d14..20552d7 100644
--- a/python/tests/fake_capcut.py
+++ b/python/tests/fake_capcut.py
@@ -4,6 +4,8 @@
 import json
 import sys
 
+sys.stdout.reconfigure(encoding="utf-8")
+
 argv = sys.argv[1:]
 if argv == ["--version"]:
     print("0.0.0-fake")
diff --git a/python/tests/test_client.py b/python/tests/test_client.py
index 755c009..0d624e2 100644
--- a/python/tests/test_client.py
+++ b/python/tests/test_client.py
@@ -1,8 +1,12 @@
 import os
 import shlex
+import shutil
+import subprocess
 import sys
+import tempfile
 import unittest
 from pathlib import Path
+from unittest.mock import patch
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
@@ -14,7 +18,8 @@
 class FakeCliMixin:
     def setUp(self):
         self._saved = os.environ.get("CAPCUT_CLI")
-        os.environ["CAPCUT_CLI"] = " ".join(shlex.quote(p) for p in (sys.executable, str(FAKE)))
+        argv = [sys.executable, str(FAKE)]
+        os.environ["CAPCUT_CLI"] = subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
 
     def tearDown(self):
         if self._saved is None:
@@ -29,6 +34,49 @@ def test_kwargs_become_flags(self):
         self.assertEqual(got, ["--font-size", "16", "--karaoke", "--tag", "a", "--tag", "b"])
 
 
+class CommandParsing(unittest.TestCase):
+    def test_quoted_windows_paths_lose_quotes_and_keep_backslashes(self):
+        command = '"C:\\Program Files\\nodejs\\node.exe" "C:\\视频 工具\\dist\\index.js"'
+        self.assertEqual(
+            capcut._split_windows_command(command),
+            [r"C:\Program Files\nodejs\node.exe", r"C:\视频 工具\dist\index.js"],
+        )
+
+    def test_windows_command_round_trips_argument_escaping(self):
+        values = ["", "plain", "two words", "a\tb", 'say "hello"', "你好 世界", "&|;$()", "\\", "\\\\"]
+        values.extend("prefix " + "\\" * n + suffix for n in range(5) for suffix in ('"tail', "", " end"))
+        for value in values:
+            argv = [r"C:\Program Files\nodejs\node.exe", value, "tail"]
+            with self.subTest(value=value):
+                self.assertEqual(capcut._split_windows_command(subprocess.list2cmdline(argv)), argv)
+
+    def test_windows_embedded_quotes_and_double_quotes(self):
+        self.assertEqual(capcut._split_windows_command('node pre"fix path"tail "a""b"'), ["node", "prefix pathtail", 'a"b'])
+
+    def test_unclosed_windows_quote_is_actionable(self):
+        with self.assertRaisesRegex(ValueError, "CAPCUT_CLI.*unclosed"):
+            capcut._split_windows_command('node "C:\\broken path')
+
+    def test_cli_command_uses_windows_quoting(self):
+        argv = [r"C:\Program Files\nodejs\node.exe", r"C:\my tool\index.js"]
+        with patch.dict(os.environ, {"CAPCUT_CLI": subprocess.list2cmdline(argv)}), patch("capcut.os.name", "nt"):
+            self.assertEqual(capcut.cli_command(), argv)
+
+    def test_cli_command_keeps_posix_shell_quoting(self):
+        argv = ["/opt/my node/bin/node", "/tmp/a'b/index.js"]
+        with patch.dict(os.environ, {"CAPCUT_CLI": shlex.join(argv)}), patch("capcut.os.name", "posix"):
+            self.assertEqual(capcut.cli_command(), argv)
+
+    def test_spawn_with_spaces_and_unicode_in_configured_path(self):
+        with tempfile.TemporaryDirectory(prefix="capcut client 空格 ") as directory:
+            script = Path(directory) / "fake capcut.py"
+            shutil.copyfile(FAKE, script)
+            argv = [sys.executable, str(script)]
+            configured = subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
+            with patch.dict(os.environ, {"CAPCUT_CLI": configured}):
+                self.assertEqual(capcut.run("info", "project with spaces")["args"], ["project with spaces"])
+
+
 class Run(FakeCliMixin, unittest.TestCase):
     def test_returns_parsed_json(self):
         self.assertEqual(capcut.run("info", "/p"), {"ok": True, "cmd": "info", "args": ["/p"]})
@@ -56,6 +104,14 @@ def test_human_returns_text(self):
     def test_version(self):
         self.assertEqual(capcut.version(), "0.0.0-fake")
 
+    def test_describe_forwards_compact_and_command_filters(self):
+        self.assertEqual(
+            capcut.describe(compact=True, command=["compile", "relink"])["args"],
+            ["--compact", "--command", "compile", "--command", "relink"],
+        )
+        self.assertEqual(capcut.describe(command="compile")["args"], ["--command", "compile"])
+        self.assertEqual(capcut.describe()["args"], [])
+
     def test_doctor_returns_report_even_on_exit_1(self):
         report = capcut.doctor(drafts="/store")
         self.assertFalse(report["ok"])
diff --git a/scripts/release-smoke.mjs b/scripts/release-smoke.mjs
index 7ef97e5..97e7620 100644
--- a/scripts/release-smoke.mjs
+++ b/scripts/release-smoke.mjs
@@ -30,6 +30,13 @@ try {
   const lib = await import(pathToFileURL(join(packageRoot, "dist", "lib.js")));
   assert.equal(typeof lib.loadDraft, "function");
   assert.ok(existsSync(join(packageRoot, "docs", "command-reference.json")));
+  const contract = load(join(packageRoot, "docs", "command-reference.json"));
+  const compact = invoke(["describe", "--compact"]);
+  assert.equal(compact.json.detail, "compact");
+  assert.ok(Buffer.byteLength(compact.stdout) < 64 * 1024);
+  assert.deepEqual(compact.json.commands.map((command) => command.name), contract.commands.map((command) => command.name));
+  const selected = invoke(["describe", "--command", "compile"]);
+  assert.deepEqual(selected.json.commands, contract.commands.filter((command) => command.name === "compile"));
 
   const beat = (60 / 136) * 4;
   const beatsSpec = join(root, "beats.json");
diff --git a/skills/capcut-edit/SKILL.md b/skills/capcut-edit/SKILL.md
index 5c40b6a..01680ac 100644
--- a/skills/capcut-edit/SKILL.md
+++ b/skills/capcut-edit/SKILL.md
@@ -80,4 +80,4 @@ Batch is transactional: one failing operation writes nothing. Use `--continue-on
 - Karaoke: `capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke`.
 - Proxy: `capcut render <project> --all-video-tracks --burn-captions`; run `doctor` first for FFmpeg capability flags.
 - Automation: `capcut serve --workers N --retries N --timeout MS`; give jobs stable `id` fields and let the runner serialize writes per project.
-- Agent schema: `capcut describe` is the source of truth. Do not scrape help text or invent flags.
+- Agent schema: on CLI v0.28.0 or newer, start with `capcut describe --compact` to discover commands, then fetch complete contracts with `capcut describe --command <name>` (repeat for several names). Plain `capcut describe` returns the full registry and works on older versions. Use these contracts as the source of truth; do not scrape help text or invent flags.
diff --git a/src/command-specs.ts b/src/command-specs.ts
index e69fc88..888d8ca 100644
--- a/src/command-specs.ts
+++ b/src/command-specs.ts
@@ -242,7 +242,7 @@ const usages = {
   diff: "capcut diff <project-a> <project-b>",
   concat: "capcut concat <project-a> <project-b> [--out <path>]",
   config: "capcut config",
-  describe: "capcut describe",
+  describe: "capcut describe [--compact] [--command <name>]",
   completions: "capcut completions <bash|zsh|fish>",
   enums: "capcut enums <category-flag> [--jianying]",
   catalogue: "capcut catalogue <query> [--kind <category>] [--limit <n>] [--jianying]",
@@ -261,7 +261,7 @@ const usages = {
   quickstart:
     "capcut quickstart <name> [--video <f>] [--audio <f>] [--srt <f>] [--drafts <dir>] [--template auto|bundled|<dir>] [--ratio <r> | --width <px> --height <px>]",
   compile:
-    "capcut compile <spec.json> [--out <draftdir>] [--template auto|bundled|<dir>] [--data <rows.jsonl|->] [--check | --plan]",
+    "capcut compile <spec.json> [--out <draftdir> | --into <project>] [--template auto|bundled|<dir>] [--data <rows.jsonl|->] [--check | --plan]",
   render: "capcut render <project> [--out <preview.mp4>] [options]",
   "detect-scenes": "capcut detect-scenes <video> [options]",
   "detect-silence": "capcut detect-silence <media> [options]",
@@ -276,6 +276,17 @@ export function commandNames(): CommandName[] {
 }
 
 const optionsByCommand: Record<string, OptionSpec[]> = {
+  describe: [
+    option(
+      "compact",
+      ["--compact"],
+      "boolean",
+      "Emit a discovery index with names, summaries, usage, and write status.",
+    ),
+    option("command", ["--command"], "enum", "Describe only this command; repeat to select several.", {
+      values: commandNames(),
+    }),
+  ],
   lint: [
     option(
       "max_chars",
@@ -792,6 +803,12 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
   ],
   compile: [
     OUT,
+    option(
+      "into",
+      ["--into"],
+      "path",
+      "Populate an existing empty app-created project, preserving its identity and store registration. Incompatible with --out, --drafts, --template and --data.",
+    ),
     option("drafts", ["--drafts"], "path", "Draft root directory."),
     TEMPLATE,
     option("check", ["--check"], "boolean", "Validate without writing."),
@@ -923,7 +940,8 @@ optionsByCommand["image-anim"] = optionsByCommand["text-anim"];
 //   --catalogue          -> harvest-enums (v0.16 user catalogue path)
 //   --sync, --add        -> harvest-enums (v0.20 library sweep + manual entry)
 //   --data               -> compile (v0.17 one-draft-per-JSONL-row)
-//   --into               -> import-timeline (v0.17 append target)
+//   --into               -> import-timeline (append target), compile (empty app-owned shell)
+//   --active-timeline    -> project commands, compile/import-timeline with --into
 //   --encoder            -> render (v0.20 proxy video encoder)
 //   --crf, --video-bitrate -> render (v0.26 proxy quality controls)
 //   --threshold-db, --min-silence, --pad -> detect-silence (v0.20 silence spans)
@@ -946,6 +964,9 @@ optionsByCommand["image-anim"] = optionsByCommand["text-anim"];
 // Everywhere else they fall through to the positional stream verbatim, matching
 // pre-release behaviour where these tokens were unknown and preserved.
 export const RELEASE_SCOPED_FLAGS: ReadonlySet<string> = new Set([
+  "--active-timeline",
+  "--compact",
+  "--command",
   "--add",
   "--audio-stream",
   "--apply",
@@ -1008,10 +1029,26 @@ export const RELEASE_SCOPED_FLAGS: ReadonlySet<string> = new Set([
 /** True when `command` declares `flag` among its command-specific options. */
 export function commandDeclaresFlag(command: string | undefined, flag: string): boolean {
   if (command === undefined) return false;
+  if (flag === "--active-timeline") return supportsActiveTimeline(command);
   const opts = optionsByCommand[command];
   return opts?.some((o) => o.flags.includes(flag)) ?? false;
 }
 
+const ACTIVE_TIMELINE_OPTION = option(
+  "active_timeline",
+  ["--active-timeline"],
+  "boolean",
+  "Explicitly follow the validated Timelines/project.json pointer on an unverified app build. Invalid, deleted or conflicting selected timelines are refused; write guards remain in force.",
+);
+
+function supportsActiveTimeline(command: string): boolean {
+  return (
+    command === "compile" ||
+    command === "import-timeline" ||
+    /<project(?:-dir)?>/.test(usages[command as CommandName] ?? "")
+  );
+}
+
 const mutating = new Set([
   "set-text",
   "shift",
@@ -1131,7 +1168,7 @@ export function buildCommandSpecs(commands: readonly string[], summaries: Record
       summary: summaries[name] ?? "",
       usage,
       positionals: positionalsFromUsage(usage),
-      options: optionsByCommand[name] ?? [],
+      options: [...(optionsByCommand[name] ?? []), ...(supportsActiveTimeline(name) ? [ACTIVE_TIMELINE_OPTION] : [])],
       mutates: mutating.has(name),
       prerequisites,
       output: {
diff --git a/src/compile.ts b/src/compile.ts
index 951fa01..055ccc0 100644
--- a/src/compile.ts
+++ b/src/compile.ts
@@ -1,5 +1,19 @@
-import { existsSync, lstatSync, readFileSync, rmSync, statSync } from "node:fs";
-import { basename, dirname, isAbsolute, resolve } from "node:path";
+import {
+  closeSync,
+  existsSync,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync,
+  rmdirSync,
+  rmSync,
+  statSync,
+  writeSync,
+} from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { stripBom } from "./bom.js";
 import {
   addKeyframes,
@@ -10,7 +24,16 @@ import {
   type TextRangeInput,
   type TextStyleOptions,
 } from "./decorators.js";
-import { type Draft, findSegment, loadDraft, saveDraft } from "./draft.js";
+import {
+  assertDraftWriteable,
+  assertTargetsUnchangedOnDisk,
+  type Draft,
+  findSegment,
+  isDryRun,
+  loadDraft,
+  loadedDraftStore,
+  saveDraft,
+} from "./draft.js";
 import {
   addAudio,
   addEffect,
@@ -20,12 +43,15 @@ import {
   applyTemplate,
   copyTextStyle,
   initDraft,
+  planAssetCopy,
   registerDraftInIndex,
   resolveCanvas,
   setAudioFade,
 } from "./factory.js";
+import { planChangedMediaRegistration } from "./materials-register.js";
 import { type MediaProbe, probeMedia } from "./probe.js";
 import { parseSrt } from "./srt.js";
+import { assertActiveTimelineUnchanged, type DraftStoreOptions } from "./store.js";
 
 /**
  * Declarative draft compiler: a spec file -> a guaranteed-valid CapCut draft.
@@ -730,6 +756,205 @@ export function compileDraft(spec: CompileSpec, opts: CompileOptions): CompileRe
   }
 }
 
+export interface CompileIntoOptions extends DraftStoreOptions {
+  intoDir: string;
+  specDir: string;
+}
+
+export type CompileIntoResult = Omit<CompileResult, "template"> & { into: true };
+
+/** Reject symlink traversal even for paths that do not exist yet. */
+function assertShellPath(projectDir: string, target: string): void {
+  const rel = relative(projectDir, target);
+  if (isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`))
+    throw new Error(`compile --into: path escapes the project: ${target}`);
+  let current = projectDir;
+  for (const part of rel.split(sep).filter(Boolean)) {
+    current = resolve(current, part);
+    if (existsSync(current) && lstatSync(current).isSymbolicLink())
+      throw new Error(`compile --into: symlink traversal is refused: ${current}`);
+  }
+}
+
+function prepareCompileInto(spec: CompileSpec, opts: CompileIntoOptions) {
+  const plan = planCompile(spec, opts.specDir);
+  const projectDir = resolve(opts.intoDir);
+  if (!existsSync(projectDir) || !lstatSync(projectDir).isDirectory())
+    throw new Error("compile --into: target must be an existing project directory created in the app.");
+  const { filePath, draft: loaded } = loadDraft(projectDir, opts);
+  const store = loadedDraftStore(filePath);
+  if (store.nestedTimelines.length && !store.activeTimeline)
+    throw new Error("compile --into: nested timelines require --active-timeline to select the app's live document.");
+  for (const candidate of store.candidates) {
+    if (!candidate.exists) continue;
+    assertShellPath(projectDir, candidate.path);
+    if (!candidate.parseable && /(?:draft_content\.json|draft_info\.json|template-2\.tmp)$/.test(candidate.name))
+      throw new Error(`compile --into: unreadable timeline document: ${candidate.name}`);
+  }
+  for (const target of store.targets) {
+    const draft = target.draft as Draft;
+    if (
+      draft.tracks.some((track) => !Array.isArray(track.segments) || track.segments.length > 0) ||
+      Number(draft.duration ?? 0) !== 0
+    )
+      throw new Error(`compile --into: project must be empty in every root and active mirror (${target.name}).`);
+    if (typeof draft.id !== "string" || !draft.id || !draft.platform?.app_version)
+      throw new Error("compile --into: target must retain an app-created project id and version marker.");
+  }
+  const draft = structuredClone(loaded);
+  const canvas = resolveCanvas(spec);
+  if (canvas) draft.canvas_config = { ...draft.canvas_config, ...canvas };
+  if (spec.fps !== undefined) draft.fps = spec.fps;
+  const sidecarPath = resolve(projectDir, "draft_meta_info.json");
+  assertShellPath(projectDir, sidecarPath);
+  const sidecarRaw = existsSync(sidecarPath) ? readFileSync(sidecarPath, "utf-8") : null;
+  if (spec.tracks.some((track) => track.type !== "text")) {
+    let sidecar: unknown;
+    try {
+      sidecar = sidecarRaw === null ? null : JSON.parse(stripBom(sidecarRaw));
+    } catch {
+      sidecar = null;
+    }
+    if (!sidecar || typeof sidecar !== "object" || Array.isArray(sidecar))
+      throw new Error("compile --into: media requires a readable app-created draft_meta_info.json sidecar.");
+  }
+  return { plan, projectDir, store, filePath, draft, sidecarPath, sidecarRaw };
+}
+
+/** Validate both the specification and destination without staging assets or changing registration. */
+export function planCompileInto(
+  spec: CompileSpec,
+  opts: CompileIntoOptions,
+): CompilePlan & { into: true; file_path: string } {
+  const { plan, draft, filePath } = prepareCompileInto(spec, opts);
+  return {
+    ...plan,
+    name: draft.name,
+    canvas: { ...draft.canvas_config, fps: draft.fps },
+    into: true,
+    file_path: filePath,
+  };
+}
+
+/** Fill an app-owned empty shell. Asset cleanup and the timeline/sidecar transaction own only this call's writes. */
+export function compileIntoDraft(spec: CompileSpec, opts: CompileIntoOptions): CompileIntoResult {
+  if (isDryRun()) throw new Error("compile --into: use planCompileInto for a dry run.");
+  const { projectDir, store, filePath, draft, sidecarPath, sidecarRaw } = prepareCompileInto(spec, opts);
+  const warnings: string[] = [];
+  if (spec.name && spec.name !== draft.name)
+    warnings.push("compile --into: spec.name is ignored; the app-created project keeps its name.");
+  const previousMedia = new Set(
+    [...(draft.materials.videos ?? []), ...(draft.materials.audios ?? [])].map((material) => material.id),
+  );
+  // Placeholder mode builds real segments with their probed metadata in memory,
+  // leaving source paths to stage after every operation has validated.
+  const { segments, maxEnd, refs } = populateDraft(spec, opts.specDir, draft, filePath, warnings, true);
+  draft.duration = maxEnd;
+  assertDraftWriteable(filePath, draft, { warnings: false });
+  for (const target of store.targets) assertDraftWriteable(filePath, target.draft as Draft, { warnings: false });
+  assertActiveTimelineUnchanged(store);
+  // --force-write may override version/editor gates, but it cannot invalidate
+  // the proof that this destination was empty.
+  assertTargetsUnchangedOnDisk(store.targets);
+  const ownedFiles: Array<{ path: string; dev: number; ino: number }> = [];
+  const ownedDirs: typeof ownedFiles = [];
+  const ensureDir = (dir: string): void => {
+    assertShellPath(projectDir, dir);
+    if (existsSync(dir)) {
+      if (!lstatSync(dir).isDirectory()) throw new Error(`compile --into: asset directory is not a directory: ${dir}`);
+      return;
+    }
+    ensureDir(dirname(dir));
+    mkdirSync(dir);
+    const stat = lstatSync(dir);
+    ownedDirs.push({ path: dir, dev: stat.dev, ino: stat.ino });
+  };
+  try {
+    const materials = [...(draft.materials.videos ?? []), ...(draft.materials.audios ?? [])].filter(
+      (material) => !previousMedia.has(material.id),
+    );
+    const audioIds = new Set((draft.materials.audios ?? []).map((material) => material.id));
+    for (const material of materials) {
+      const source = material.path as string;
+      const kind = audioIds.has(material.id) ? "audio" : "video";
+      const dir = resolve(projectDir, "assets", kind);
+      assertShellPath(projectDir, dir);
+      const asset = planAssetCopy(source, dir, basename(source));
+      assertShellPath(projectDir, asset.destination);
+      if (asset.copyNeeded) {
+        ensureDir(dir);
+        const output = openSync(asset.destination, "wx");
+        const owned = fstatSync(output);
+        ownedFiles.push({ path: asset.destination, dev: owned.dev, ino: owned.ino });
+        try {
+          const input = openSync(source, "r");
+          try {
+            const buffer = Buffer.alloc(64 * 1024);
+            while (true) {
+              const length = readSync(input, buffer, 0, buffer.length, null);
+              if (length === 0) break;
+              let offset = 0;
+              while (offset < length) offset += writeSync(output, buffer, offset, length - offset);
+            }
+            fsyncSync(output);
+          } finally {
+            closeSync(input);
+          }
+        } finally {
+          closeSync(output);
+        }
+      }
+      material.path = asset.destination;
+      if ("material_name" in material) material.material_name = basename(asset.destination);
+      else material.name = basename(asset.destination);
+    }
+    const registration = planChangedMediaRegistration(
+      draft,
+      projectDir,
+      materials.map((material) => material.id as string),
+    );
+    if (materials.length && (!registration || registration.raw !== sidecarRaw))
+      throw new Error(
+        "refused [draft-changed-on-disk]: The project sidecar changed while compiling. Reload and retry.",
+      );
+    // A readable sidecar is always a guarded dependency, even for text-only specs.
+    const additionalFiles = registration
+      ? [registration]
+      : sidecarRaw === null
+        ? []
+        : [{ path: sidecarPath, raw: sidecarRaw, content: sidecarRaw }];
+    assertActiveTimelineUnchanged(store);
+    assertTargetsUnchangedOnDisk(store.targets);
+    saveDraft(filePath, draft, { additionalFiles, preserveProjectFields: true });
+    return {
+      ok: true,
+      into: true,
+      name: draft.name,
+      draft_path: projectDir,
+      file_path: filePath,
+      tracks: draft.tracks.length,
+      segments,
+      duration_us: maxEnd,
+      warnings,
+      refs: Object.fromEntries(refs),
+    };
+  } catch (error) {
+    for (const item of [...ownedFiles, ...ownedDirs.reverse()]) {
+      if (!existsSync(item.path)) continue;
+      const current = lstatSync(item.path);
+      if (current.dev === item.dev && current.ino === item.ino && !current.isSymbolicLink()) {
+        try {
+          if (current.isDirectory()) rmdirSync(item.path);
+          else rmSync(item.path);
+        } catch {
+          /* Preserve non-empty directories or another writer's replacement. */
+        }
+      }
+    }
+    throw error;
+  }
+}
+
 function populateDraft(
   spec: CompileSpec,
   specDir: string,
diff --git a/src/draft.ts b/src/draft.ts
index 2c91163..fb987fc 100644
--- a/src/draft.ts
+++ b/src/draft.ts
@@ -22,7 +22,9 @@ import {
   assertActiveTimelineUnchanged,
   type DraftCandidate,
   type DraftStore,
+  type DraftStoreOptions,
   discoverDraftStore,
+  draftProjectDir,
   editorProcesses,
   isManagedDraftPath,
   nestedTimelinesWriteWarning,
@@ -137,8 +139,8 @@ export interface Draft {
   [key: string]: unknown;
 }
 
-export function findDraft(input: string): string {
-  return discoverDraftStore(input).canonical.path;
+export function findDraft(input: string, options: DraftStoreOptions = {}): string {
+  return discoverDraftStore(input, options).canonical.path;
 }
 
 interface LoadContext {
@@ -147,12 +149,11 @@ interface LoadContext {
 
 const loadContexts = new Map<string, LoadContext>();
 
-export function loadDraft(path: string): { draft: Draft; filePath: string } {
-  const store = discoverDraftStore(path);
+export function loadDraft(path: string, options: DraftStoreOptions = {}): { draft: Draft; filePath: string } {
+  const store = discoverDraftStore(path, options);
   const filePath = store.canonical.path;
   // The caller gets the parsed timeline itself, not a copy of it. The store
-  // kept here never escapes this module — `loadContexts` is private and
-  // `saveDraft` is its only reader — and everything saveDraft takes from it is
+  // snapshot is also used for asset roots and compiler preflight. Everything saveDraft takes from it is
   // either fixed at discovery (`version`, `layout`, `projectDir`) or a string
   // snapshot of the file on disk (`raw`, `path`, `envelopePath`), never
   // anything re-derived from `canonical.draft`. So nothing observes the
@@ -164,6 +165,15 @@ export function loadDraft(path: string): { draft: Draft; filePath: string } {
   return { draft: store.canonical.draft as Draft, filePath };
 }
 
+/** Project root captured at load, including an explicit active-timeline selection. */
+export function loadedDraftProjectDir(filePath: string): string {
+  return loadContexts.get(resolve(filePath))?.store.projectDir ?? draftProjectDir(filePath);
+}
+
+export function loadedDraftStore(filePath: string): DraftStore {
+  return loadContexts.get(resolve(filePath))?.store ?? discoverDraftStore(filePath);
+}
+
 // Canonical bottom->top layer order CapCut expects in the tracks array.
 // Derived from a real CapCut-authored draft: [video, audio, text].
 // Tracks are pushed in command-call order as content is added, so without
@@ -307,20 +317,43 @@ export interface AdditionalDraftFile {
 export function commitDraftTargets(
   targets: DraftCandidate[],
   draft: Draft,
-  options: { backup?: boolean; additionalFiles?: AdditionalDraftFile[] } = {},
+  options: { backup?: boolean; additionalFiles?: AdditionalDraftFile[]; preserveProjectFields?: boolean } = {},
 ): Map<string, string> {
   const written = new Map<string, string>();
   if (dryRun) return written;
 
+  // A sidecar can also contain a timeline. Shell compilation merges its
+  // import group into that file's serialized timeline and commits it once.
+  const embeddedSidecars = new Map<string, AdditionalDraftFile>();
+  const additionalPaths = new Set<string>();
+  for (const file of options.additionalFiles ?? []) {
+    const path = resolve(file.path);
+    if (additionalPaths.has(path)) throw new Error(`Duplicate draft transaction target: ${path}`);
+    additionalPaths.add(path);
+    if (
+      options.preserveProjectFields &&
+      basename(path) === "draft_meta_info.json" &&
+      targets.some((target) => resolve(target.path) === path)
+    )
+      embeddedSidecars.set(path, file);
+  }
+
   // Prepare every replacement before renaming any target. This keeps the
   // multi-file write as close to a transaction as the filesystem allows.
   const replacements = [
     ...targets.map((target) => ({
       path: target.path,
       raw: target.raw,
-      content: serializeDraftCandidate(target, draft),
+      content: serializeDraftCandidate(
+        target,
+        draft,
+        options.preserveProjectFields,
+        embeddedSidecars.has(resolve(target.path))
+          ? { draft_materials: JSON.parse(embeddedSidecars.get(resolve(target.path))!.content).draft_materials }
+          : undefined,
+      ),
     })),
-    ...(options.additionalFiles ?? []),
+    ...(options.additionalFiles ?? []).filter((file) => !embeddedSidecars.has(resolve(file.path))),
   ];
   const paths = new Set<string>();
   for (const item of replacements) {
@@ -381,28 +414,14 @@ export function commitDraftTargets(
   return written;
 }
 
-export function saveDraft(
+/** Run the normal save gates before a caller stages project assets. Save repeats them at commit. */
+export function assertDraftWriteable(
   filePath: string,
   draft: Draft,
-  options: { backup?: boolean; skipVersionGuard?: boolean; additionalFiles?: AdditionalDraftFile[] } = {},
+  options: { skipVersionGuard?: boolean; warnings?: boolean } = {},
+  storeSnapshot?: DraftStore,
 ): void {
-  if (dryRun) {
-    // Version guard, warning only: dry-run writes nothing, so it never blocks,
-    // but the WARNING still previews what a real write would do. Draft-only
-    // assessment (no store discovery) keeps dry-run free of extra I/O.
-    if (options.skipVersionGuard !== true) {
-      const safety = assessWriteSafety(draft, null);
-      if (safety.action !== "ok") process.stderr.write(`WARNING: ${safety.reasons.join(" ")}\n`);
-    }
-    // Normalize in memory (so any read-back is consistent) but write nothing.
-    sortTracks(draft);
-    return;
-  }
-
-  const resolved = resolve(filePath);
-  const context = loadContexts.get(resolved) ?? { store: discoverDraftStore(filePath) };
-  const { store } = context;
-
+  const store = storeSnapshot ?? loadContexts.get(resolve(filePath))?.store ?? discoverDraftStore(filePath);
   if (!forceWrite && isManagedDraftPath(filePath)) {
     const running = editorProcesses();
     if (running.length > 0) {
@@ -431,7 +450,7 @@ export function saveDraft(
     if (safety.action === "refuse" && !forceWrite) {
       throw new Error(`refused [version-boundary]: ${safety.reasons.join("\n")}`);
     }
-    if (safety.action === "warn" || (safety.action === "refuse" && forceWrite)) {
+    if (options.warnings !== false && (safety.action === "warn" || (safety.action === "refuse" && forceWrite))) {
       process.stderr.write(`WARNING: ${safety.reasons.join(" ")}\n`);
     }
   }
@@ -444,12 +463,42 @@ export function saveDraft(
   // no longer silent: warn, never refuse. Shares skipVersionGuard with the
   // version guard: restore's mirror re-sync is the escape hatch, not a new
   // sighting of the hazard.
-  if (options.skipVersionGuard !== true && store.layout === "timelines-nested") {
+  if (options.warnings !== false && options.skipVersionGuard !== true && store.layout === "timelines-nested") {
     process.stderr.write(`WARNING: ${nestedTimelinesWriteWarning(store.version)}\n`);
   }
 
   assertActiveTimelineUnchanged(store);
   if (!forceWrite) assertTargetsUnchangedOnDisk(store.targets);
+}
+
+export function saveDraft(
+  filePath: string,
+  draft: Draft,
+  options: {
+    backup?: boolean;
+    skipVersionGuard?: boolean;
+    additionalFiles?: AdditionalDraftFile[];
+    preserveProjectFields?: boolean;
+  } = {},
+): void {
+  if (dryRun) {
+    // Version guard, warning only: dry-run writes nothing, so it never blocks,
+    // but the WARNING still previews what a real write would do. Draft-only
+    // assessment (no store discovery) keeps dry-run free of extra I/O.
+    if (options.skipVersionGuard !== true) {
+      const safety = assessWriteSafety(draft, null);
+      if (safety.action !== "ok") process.stderr.write(`WARNING: ${safety.reasons.join(" ")}\n`);
+    }
+    // Normalize in memory (so any read-back is consistent) but write nothing.
+    sortTracks(draft);
+    return;
+  }
+
+  const resolved = resolve(filePath);
+  const context = loadContexts.get(resolved) ?? { store: discoverDraftStore(filePath) };
+  const { store } = context;
+
+  assertDraftWriteable(filePath, draft, options, store);
 
   sortTracks(draft);
   const written = commitDraftTargets(store.targets, draft, options);
@@ -475,7 +524,12 @@ export function saveDraft(
   // establish what the write already knew.
   const timelinePaths = new Set(store.targets.map((target) => target.path));
   const timelineWrites = new Map([...written].filter(([path]) => timelinePaths.has(path)));
-  loadContexts.set(resolved, { store: storeAfterWrite(store, draft, timelineWrites) });
+  const embeddedSidecar = options.additionalFiles?.some((file) => timelinePaths.has(resolve(file.path)));
+  loadContexts.set(resolved, {
+    store: embeddedSidecar
+      ? discoverDraftStore(filePath, { activeTimeline: store.activeTimeline?.explicit === true })
+      : storeAfterWrite(store, draft, timelineWrites, options.preserveProjectFields),
+  });
 }
 
 function writeAndSync(path: string, content: string): void {
diff --git a/src/factory.ts b/src/factory.ts
index 9cd47c9..b9e1e7d 100644
--- a/src/factory.ts
+++ b/src/factory.ts
@@ -21,10 +21,10 @@ import { stripBom } from "./bom.js";
 import { uuidHex } from "./decorators.js";
 import { detectEncryption } from "./decrypt.js";
 import type { Draft, Segment, Timerange, Track } from "./draft.js";
-import { findMaterialGlobal, findSegment, makeTrack, writeAtomic } from "./draft.js";
+import { findMaterialGlobal, findSegment, loadedDraftProjectDir, makeTrack, writeAtomic } from "./draft.js";
 import { findEnum, type Namespace } from "./enums.js";
 import { PHOTO_META_DURATION_US, registerMediumInSidecar } from "./materials-register.js";
-import { draftProjectDir, isManagedDraftPath, parseCandidate } from "./store.js";
+import { isManagedDraftPath, parseCandidate } from "./store.js";
 import { storedTextLength } from "./text-offsets.js";
 import { atLeast, versionTuple } from "./version.js";
 import { fetchWikimediaAsset, isWikimediaUrl, type WikimediaAsset } from "./wikimedia.js";
@@ -1989,7 +1989,7 @@ export function addAudio(
 
   // Copy file into draft assets directory (collision-safe). Placeholder clips
   // reference their (possibly empty/broken) path verbatim — nothing to copy.
-  const draftDir = draftProjectDir(filePath);
+  const draftDir = loadedDraftProjectDir(filePath);
   const assetsDir = resolve(draftDir, "assets", "audio");
   const destPath = opts.placeholder ? opts.placeholder.path : copyAssetDeduped(opts.path, assetsDir, "audio.mp3");
   // Use the local assets path — CapCut rewrites to placeholder on open
@@ -2099,7 +2099,7 @@ export function addVideo(
 
   // Copy file into draft assets directory (collision-safe). Placeholder clips
   // reference their (possibly empty/broken) path verbatim — nothing to copy.
-  const draftDir = draftProjectDir(filePath);
+  const draftDir = loadedDraftProjectDir(filePath);
   const assetsDir = resolve(draftDir, "assets", "video");
   const destPath = opts.placeholder ? opts.placeholder.path : copyAssetDeduped(opts.path, assetsDir, "media");
   // Use the local assets path — CapCut rewrites to placeholder on open
diff --git a/src/index.ts b/src/index.ts
index 29f9112..d4b17de 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -69,7 +69,9 @@ import {
   NESTED_TIMELINES_MODERN_ACTION,
   nestedTimelinesAction,
   nestedTimelinesWriteWarning,
+  parseCandidate,
   planTimelineSync,
+  setActiveTimelineSelection,
 } from "./store.js";
 import { formatDuration, formatTime, parseTimeInput } from "./time.js";
 import type { UserEnumEntry } from "./user-enums.js";
@@ -178,6 +180,8 @@ Global flags:
   -q, --quiet     No output on success, exit code only (write commands)
   --dry-run       Preview a mutating command: print the result (with
                   "dryRun":true) but leave the draft and its .bak untouched
+  --active-timeline  Follow the validated Timelines/project.json pointer explicitly
+                    on an unverified build; existing write guards still apply.
   --force-write   Override editor-running, changed-on-disk, and
                   version-boundary safety checks
   --jianying      Use JianYing enum namespace (default: CapCut) for
@@ -240,7 +244,7 @@ Create:
              Durations come from ffprobe when available (5s placeholder if not).
              --ratio / --width / --height set the canvas exactly as in init.
              Exit codes: 0 created & lint-clean · 2 created but lint errors
-  compile    <spec.json> [--out <draftdir>] [--drafts <dir>] [--data <rows.jsonl|->]
+  compile    <spec.json> [--out <draftdir> | --into <project>] [--drafts <dir>] [--data <rows.jsonl|->]
              Build a whole draft from a declarative JSON spec (the inverse of
              describe). Times are in seconds. Media paths resolve relative to
              the spec file. Validates the full spec before writing anything.
@@ -497,7 +501,7 @@ Maintenance & inspection:
   diff       <projectA> <projectB>             Compare two drafts (added/removed/changed)
   concat     <projectA> <draftB> [--out <p>]   Append draftB onto projectA's timeline (id-safe)
   config                                       Show resolved .capcutrc + effective defaults
-  describe                                      Emit the full command surface as JSON (agent tool spec)
+  describe [--compact] [--command <name>]        Emit command contracts or a compact discovery index
   diagnose   <project> [--bundle <report.json>] Inspect canonical draft files and divergence
   fixture    <project> --out <dir>              Build a shareable, redacted compatibility bundle
              (timeline JSON only, no media; home paths + emails redacted) to
@@ -1058,6 +1062,8 @@ interface Flags {
   backoffMs?: number;
   maxBufferMb?: number;
   version?: boolean;
+  describeCompact?: boolean;
+  describeCommands?: string[];
   // relink / projects / timeline / restore
   dir?: string;
   recursive?: boolean;
@@ -1076,6 +1082,7 @@ interface Flags {
   maxCps?: number;
   safeArea?: number;
   forceWrite?: boolean;
+  activeTimeline?: boolean;
   bundle?: string;
   continueOnError?: boolean;
   check?: boolean;
@@ -1188,7 +1195,14 @@ function parseFlags(args: string[]): { positional: string[]; flags: Flags } {
     if (a === "-H" || a === "--human") flags.human = true;
     else if (a === "-v" || a === "--version") flags.version = true;
     else if (a === "-q" || a === "--quiet") flags.quiet = true;
-    else if (a === "--batch") flags.batch = true;
+    else if (a === "--compact") flags.describeCompact = true;
+    else if (a === "--active-timeline") flags.activeTimeline = true;
+    else if (a === "--command") {
+      const name = args[++i];
+      if (!name || name.startsWith("-")) die("--command requires a command name (for example: --command compile)");
+      flags.describeCommands ??= [];
+      flags.describeCommands.push(name);
+    } else if (a === "--batch") flags.batch = true;
     else if (a === "--easing" && i + 1 < args.length) {
       flags.easing = args[++i];
     } else if ((a === "--track" || a === "--type") && i + 1 < args.length) {
@@ -3777,7 +3791,12 @@ function cmdVersion(draft: Draft, filePath: string, flags: Flags): void {
   // discarded by the app — name the layout alongside the write-guard notes.
   // On >= 8.7 storage the layout value stays content-/info-primary by design,
   // so the same question needs the claim-free note instead of silence.
-  if (store.activeTimeline) v.support.notes.push(ACTIVE_TIMELINE_WINDOWS_ACTION);
+  if (store.activeTimeline)
+    v.support.notes.push(
+      store.activeTimeline.explicit
+        ? "Active timeline selected by explicit --active-timeline opt-in; desktop acceptance is unverified on this build."
+        : ACTIVE_TIMELINE_WINDOWS_ACTION,
+    );
   else if (store.layout === "timelines-nested") v.support.notes.push(nestedTimelinesAction(store.version));
   else if (store.nestedTimelines.length > 0) v.support.notes.push(NESTED_TIMELINES_MODERN_ACTION);
   if (flags.human) {
@@ -4862,6 +4881,19 @@ function cmdRestore(projectPath: string | undefined, flags: Flags): void {
     return;
   }
 
+  const restoreSource = (source: string): void => {
+    if (!hasSynchronizedSiblings) {
+      copyFileSync(source, filePath);
+      return;
+    }
+    const restored = loadDraft(filePath);
+    const backup = parseCandidate(source);
+    if (!backup.draft) die(`Backup does not contain a readable timeline: ${source}`);
+    // Load all current targets before committing the backup. This also avoids
+    // creating disagreement between active documents during pointer validation.
+    saveDraft(restored.filePath, backup.draft, { backup: false, skipVersionGuard: true });
+  };
+
   if (flags.step !== undefined) {
     if (!Number.isInteger(flags.step) || flags.step < 1) die("--step must be a positive integer (1 = most recent).");
     const target = snaps.find((s) => s.step === flags.step);
@@ -4869,16 +4901,7 @@ function cmdRestore(projectPath: string | undefined, flags: Flags): void {
       const avail = snaps.length ? `1..${snaps.length}` : "none yet";
       die(`No snapshot at --step ${flags.step}. Available: ${avail}. Try: capcut restore ${projectPath} --list`);
     }
-    if (!isDryRun()) {
-      copyFileSync(target.path, filePath);
-      if (hasSynchronizedSiblings) {
-        // skipVersionGuard: restore is the undo path and must never be gated
-        // (docs/version-support.md) — a refusal here would fire AFTER the
-        // canonical was already rolled back, leaving the mirrors diverged.
-        const restored = loadDraft(filePath);
-        saveDraft(restored.filePath, restored.draft, { backup: false, skipVersionGuard: true });
-      }
-    }
+    if (!isDryRun()) restoreSource(target.path);
     out({ ok: true, restored: filePath, from: target.path, step: flags.step }, flags);
     return;
   }
@@ -4887,14 +4910,7 @@ function cmdRestore(projectPath: string | undefined, flags: Flags): void {
   if (!existsSync(bakPath)) {
     die(`No backup found at ${bakPath}. Nothing to restore (a .bak is written on the first edit).`);
   }
-  if (!isDryRun()) {
-    copyFileSync(bakPath, filePath);
-    if (hasSynchronizedSiblings) {
-      // skipVersionGuard: see the --step branch above — restore stays ungated.
-      const restored = loadDraft(filePath);
-      saveDraft(restored.filePath, restored.draft, { backup: false, skipVersionGuard: true });
-    }
-  }
+  if (!isDryRun()) restoreSource(bakPath);
   out({ ok: true, restored: filePath, from: bakPath }, flags);
 }
 
@@ -5137,7 +5153,7 @@ const SUMMARIES: Record<string, string> = {
   diff: "Compare two drafts (segments/materials/tracks added/removed/changed).",
   concat: "Append one draft onto another's timeline (id-safe), write to --out or in place.",
   config: "Show the resolved config (.capcutrc + effective defaults).",
-  describe: "Emit the full command surface as JSON (agent tool spec).",
+  describe: "Emit command contracts as JSON, optionally filtered by name or reduced to a compact discovery index.",
   completions: "Generate shell completions (bash|zsh|fish).",
   restore: "Undo writes from .bak / snapshot history (--step N, --list).",
   serve: "Run a stateless JSONL job queue from stdin/--queue.",
@@ -5158,6 +5174,14 @@ const SUMMARIES: Record<string, string> = {
 // don't have to scrape --help. Names come from COMMANDS (source of truth);
 // summaries from SUMMARIES (test-enforced complete).
 function cmdDescribe(flags: Flags): void {
+  let commands = commandSpecs();
+  if (flags.describeCommands) {
+    const selected = new Set(flags.describeCommands);
+    const known = new Set(commands.map((command) => command.name));
+    const unknown = [...selected].filter((name) => !known.has(name));
+    if (unknown.length) die(`Unknown command(s): ${unknown.join(", ")}. Use capcut describe --compact to list names.`);
+    commands = commands.filter((command) => selected.has(command.name));
+  }
   out(
     {
       name: "capcut-cli",
@@ -5165,7 +5189,10 @@ function cmdDescribe(flags: Flags): void {
       schema_version: 2,
       description: "Edit CapCut/JianYing draft_content.json directly. JSON in, JSON out.",
       global_flags: GLOBAL_OPTION_SPECS,
-      commands: commandSpecs(),
+      ...(flags.describeCompact ? { detail: "compact" } : {}),
+      commands: flags.describeCompact
+        ? commands.map(({ name, summary, usage, mutates }) => ({ name, summary, usage, mutates }))
+        : commands,
     },
     flags,
   );
@@ -5379,10 +5406,15 @@ async function cmdConcat(positional: string[], flags: Flags): Promise<void> {
 // factory functions the imperative add-* commands use. Resolves the bundled
 // _init template the same way `init` does.
 async function cmdCompile(positional: string[], flags: Flags): Promise<void> {
-  const { compileDraft, parseSpec, planCompile } = await import("./compile.js");
+  const { compileDraft, compileIntoDraft, parseSpec, planCompile, planCompileInto } = await import("./compile.js");
   const specPath = positional[1];
-  if (!specPath) die("Usage: capcut compile <spec.json> [--out <draftdir>] [--drafts <dir>] [--data <rows.jsonl|->]");
+  if (!specPath)
+    die(
+      "Usage: capcut compile <spec.json> [--out <draftdir> | --into <project>] [--drafts <dir>] [--data <rows.jsonl|->]",
+    );
   if (!existsSync(specPath)) die(`Spec file not found: ${specPath}`);
+  if (flags.into && [flags.out, flags.drafts, flags.template, flags.data].some((value) => value !== undefined))
+    die("compile: --into is incompatible with --out, --drafts, --template and --data.");
 
   // --data: mass production. One spec + N JSONL rows = N drafts. Branches
   // before anything else so the single-draft path below stays untouched.
@@ -5398,6 +5430,22 @@ async function cmdCompile(positional: string[], flags: Flags): Promise<void> {
     die((e as Error).message);
   }
 
+  if (flags.into) {
+    const options = {
+      intoDir: flags.into,
+      specDir: path.dirname(path.resolve(specPath)),
+      activeTimeline: flags.activeTimeline === true,
+    };
+    if (flags.check || flags.plan || isDryRun())
+      out({ ...planCompileInto(spec, options), checked: true, write: false }, flags);
+    else {
+      const result = compileIntoDraft(spec, options);
+      out(result, flags);
+      if (!flags.quiet) process.stderr.write(`Compiled into existing project: ${result.draft_path}\n`);
+    }
+    return;
+  }
+
   if (flags.check || flags.plan) {
     const plan = planCompile(spec, path.dirname(path.resolve(specPath)));
     out({ ...plan, checked: true, write: false }, flags);
@@ -5803,6 +5851,9 @@ async function main(): Promise<void> {
   // Global --dry-run: gate every saveDraft write (see src/draft.ts).
   setDryRun(flags.dryRun === true);
   setForceWrite(flags.forceWrite === true);
+  if (flags.activeTimeline && ["compile", "import-timeline"].includes(positional[0]) && !flags.into)
+    die("--active-timeline requires --into for this command.");
+  setActiveTimelineSelection(flags.activeTimeline === true);
 
   if (flags.version) {
     console.log(getCliVersion());
diff --git a/src/lib.ts b/src/lib.ts
index a40b19a..3234fb1 100644
--- a/src/lib.ts
+++ b/src/lib.ts
@@ -56,6 +56,7 @@ export type { RunCommandRequest, RunCommandResult } from "./runner.js";
 export { runCommand } from "./runner.js";
 export type { GroupingDefaults } from "./script.js";
 export { groupingDefaults, wordSeparator } from "./script.js";
+export type { DraftStoreOptions } from "./store.js";
 export {
   fromStoredOffset,
   rangesLookDoubled,
diff --git a/src/serve.ts b/src/serve.ts
index 0cae429..97b160e 100644
--- a/src/serve.ts
+++ b/src/serve.ts
@@ -274,6 +274,9 @@ function projectKey(input: string): string {
       }
     }
   }
+  // Nested-file discovery can retain legacy local-file semantics on an
+  // unverified build. It still belongs to the enclosing project's write lock.
+  if (basename(dirname(root)) === "Timelines") root = dirname(dirname(root));
   const key = canonicalPath(root);
   return process.platform === "win32" ? key.toLowerCase() : key;
 }
@@ -298,7 +301,8 @@ function projectLockKeys(job: JobInput): string[] {
       ? [positionals[index]]
       : [],
   );
-  if (job.cmd === "import-timeline" && options.has("--into")) paths.push(options.get("--into") as string);
+  if (["import-timeline", "compile"].includes(job.cmd) && options.has("--into"))
+    paths.push(options.get("--into") as string);
   if (["compile", "import-timeline", "cut", "concat", "translate"].includes(job.cmd) && options.has("--out")) {
     paths.push(options.get("--out") as string);
   }
diff --git a/src/store.ts b/src/store.ts
index 44897a0..63b2523 100644
--- a/src/store.ts
+++ b/src/store.ts
@@ -43,6 +43,18 @@ interface ActiveTimeline {
   id: string;
   pointerPath: string;
   pointerRaw: string;
+  explicit?: boolean;
+}
+
+export interface DraftStoreOptions {
+  /** Opt in to pointer-based selection on an app build without a verified fixture. */
+  activeTimeline?: boolean;
+}
+
+let activeTimelineSelection = false;
+/** CLI process default; library callers should pass options to loadDraft instead. */
+export function setActiveTimelineSelection(value: boolean): void {
+  activeTimelineSelection = value;
 }
 
 export interface DraftStore {
@@ -89,7 +101,7 @@ export interface DraftStoreReport {
     error?: string;
   }>;
   next_actions: string[];
-  active_timeline?: { id: string; canonical: string };
+  active_timeline?: { id: string; canonical: string; explicit?: boolean };
   /** Present only when the timeline references local media that
    * draft_meta_info.json's `draft_materials` provably does not register —
    * see assessMediaRegistration. Informational: no exit-code change. */
@@ -439,36 +451,55 @@ function selectActiveTimeline(
   projectDir: string,
   root: DraftCandidate,
   version: string | null,
+  explicit = false,
 ): {
   active: ActiveTimeline;
   candidates: DraftCandidate[];
 } | null {
-  if (version !== "8.7.0" || !isEvidencedWindowsDraft(root.draft)) return null;
+  if (!explicit && (version !== "8.7.0" || !isEvidencedWindowsDraft(root.draft))) return null;
+  const invalid = (reason: string): never => {
+    throw new Error(`refused [active-timeline-invalid]: ${reason}`);
+  };
   const pointerPath = join(projectDir, "Timelines", "project.json");
-  if (!containedPath(projectDir, pointerPath)) return null;
   try {
+    if (!containedPath(projectDir, pointerPath))
+      invalid("The active timeline pointer is missing or traverses a symlink.");
     const pointerRaw = stripBom(readFileSync(pointerPath, "utf-8"));
     const pointer = JSON.parse(pointerRaw) as Record<string, unknown>;
     const id = pointer.main_timeline_id ?? pointer.id;
-    if (typeof id !== "string" || !/^[A-Za-z0-9_-]+$/.test(id)) return null;
+    if (typeof id !== "string" || !/^[A-Za-z0-9_-]+$/.test(id))
+      return invalid("The pointer must name one safe timeline id.");
     if (
       Array.isArray(pointer.timelines) &&
       pointer.timelines.some((entry) => entry?.id === id && entry.is_marked_delete === true)
     )
-      return null;
+      invalid("The selected timeline is marked deleted.");
     const candidates: DraftCandidate[] = [];
     for (const name of ["draft_content.json", "draft_info.json", "template-2.tmp"]) {
       const rel = join("Timelines", id, name);
       const path = join(projectDir, rel);
-      if (!containedPath(projectDir, path)) continue;
+      if (!existsSync(path)) continue;
+      if (!containedPath(projectDir, path)) invalid("A selected timeline document traverses a symlink.");
       const candidate = parseCandidate(path);
+      if (explicit && !candidate.parseable) invalid(`The selected document ${rel} is unreadable.`);
       candidates.push({ ...candidate, name: rel.split(sep).join("/") });
     }
     const primary = candidates.find((candidate) => candidate.parseable && candidate.draft);
-    if (!primary || !isEvidencedWindowsDraft(primary.draft)) return null;
-    if (candidates.some((candidate) => candidate.parseable && !isEvidencedWindowsDraft(candidate.draft))) return null;
-    return { active: { id, pointerPath, pointerRaw }, candidates };
-  } catch {
+    if (!primary) return invalid("The selected timeline has no readable document.");
+    if (
+      !explicit &&
+      (!isEvidencedWindowsDraft(primary.draft) ||
+        candidates.some((candidate) => candidate.parseable && !isEvidencedWindowsDraft(candidate.draft)))
+    )
+      return null;
+    if (explicit && new Set(candidates.map((candidate) => timelineHashWithoutId(candidate.draft as Draft))).size > 1)
+      invalid("The selected timeline's documents disagree. Reconcile them in the app before using --active-timeline.");
+    return { active: { id, pointerPath, pointerRaw, ...(explicit ? { explicit: true } : {}) }, candidates };
+  } catch (error) {
+    if (explicit) {
+      if ((error as Error).message.startsWith("refused [active-timeline-invalid]:")) throw error;
+      invalid((error as Error).message);
+    }
     // A malformed or inaccessible pointer must never redirect a root write.
     return null;
   }
@@ -498,11 +529,11 @@ function highestVersion(parseable: DraftCandidate[]): string | null {
   return versions.sort((a, b) => (atLeast(a, b) ? -1 : 1))[0] ?? null;
 }
 
-export function discoverDraftStore(input: string): DraftStore {
-  return discoverStore(input, true);
+export function discoverDraftStore(input: string, options: DraftStoreOptions = {}): DraftStore {
+  return discoverStore(input, true, options.activeTimeline ?? activeTimelineSelection);
 }
 
-function discoverStore(input: string, nestedRoot: boolean): DraftStore {
+function discoverStore(input: string, nestedRoot: boolean, explicit = false): DraftStore {
   const { projectDir, requested, paths } = candidatePaths(input, nestedRoot);
   let candidates = paths.map(parseCandidate);
   let parseable = candidates.filter((candidate) => candidate.parseable && candidate.draft);
@@ -514,8 +545,8 @@ function discoverStore(input: string, nestedRoot: boolean): DraftStore {
     );
   }
 
-  const version = highestVersion(parseable);
-  const modernStorage = atLeast(version, "8.7");
+  let version = highestVersion(parseable);
+  let modernStorage = atLeast(version, "8.7");
 
   let canonical: DraftCandidate | undefined;
   if (requested) canonical = parseable.find((candidate) => candidate.path === requested);
@@ -529,13 +560,17 @@ function discoverStore(input: string, nestedRoot: boolean): DraftStore {
 
   const root =
     parseable.find((candidate) => candidate.path === join(projectDir, "template-2.tmp")) ??
-    parseable.find((candidate) => candidate.path === join(projectDir, "draft_content.json"));
+    parseable.find((candidate) => candidate.path === join(projectDir, "draft_content.json")) ??
+    (explicit ? parseable.find((candidate) => dirname(candidate.path) === projectDir) : undefined);
+  if (explicit && !root) throw new Error("refused [active-timeline-invalid]: No readable project-root timeline.");
+  if (explicit && requested && !STANDARD_FILES.some((name) => basename(requested) === name))
+    throw new Error("refused [active-timeline-invalid]: Pass the project directory or a standard timeline document.");
   const selection =
     root && (!requested || STANDARD_FILES.some((name) => basename(requested) === name))
-      ? selectActiveTimeline(projectDir, root, version)
+      ? selectActiveTimeline(projectDir, root, version, explicit)
       : null;
   if (!selection && nestedRoot && requested && dirname(requested) !== projectDir) {
-    return discoverStore(input, false);
+    return discoverStore(input, false, explicit);
   }
   if (selection) {
     const activeDir = join(projectDir, "Timelines", selection.active.id);
@@ -546,6 +581,8 @@ function discoverStore(input: string, nestedRoot: boolean): DraftStore {
     }
     candidates = [...candidates.filter((candidate) => dirname(candidate.path) === projectDir), ...selection.candidates];
     parseable = candidates.filter((candidate) => candidate.parseable && candidate.draft);
+    version = highestVersion(parseable);
+    modernStorage = atLeast(version, "8.7");
     canonical = selection.candidates.find((candidate) => candidate.parseable && candidate.draft) as DraftCandidate;
     for (const candidate of parseable) {
       candidate.keepGuid = dirname(candidate.path) === activeDir ? selection.active.id : candidate.draft?.id;
@@ -615,7 +652,12 @@ function discoverStore(input: string, nestedRoot: boolean): DraftStore {
  * `diverged` collapses to false on its own, because every written target now
  * exposes the same timeline.
  */
-export function storeAfterWrite(store: DraftStore, draft: Draft, written: Map<string, string>): DraftStore {
+export function storeAfterWrite(
+  store: DraftStore,
+  draft: Draft,
+  written: Map<string, string>,
+  preserveProjectFields = false,
+): DraftStore {
   const refresh = (candidate: DraftCandidate): DraftCandidate => {
     const content = written.get(candidate.path);
     if (content === undefined) return candidate;
@@ -629,6 +671,7 @@ export function storeAfterWrite(store: DraftStore, draft: Draft, written: Map<st
       // The file is there — it was just renamed into place — but a stat can
       // still fail on a racing sync client. Fall back to what we wrote.
     }
+    const candidateDraft = draftForCandidate(candidate, draft, preserveProjectFields);
     let timelineHash: string | null = null;
     return {
       name: candidate.name,
@@ -640,13 +683,10 @@ export function storeAfterWrite(store: DraftStore, draft: Draft, written: Map<st
       raw: content,
       parseable: true,
       envelopePath: candidate.envelopePath,
-      draft: candidate.keepGuid === undefined ? draft : { ...draft, id: candidate.keepGuid },
+      draft: candidateDraft,
       ...(candidate.keepGuid === undefined ? {} : { keepGuid: candidate.keepGuid }),
       get timelineHash(): string {
-        if (timelineHash === null)
-          timelineHash = hash(
-            JSON.stringify(candidate.keepGuid === undefined ? draft : { ...draft, id: candidate.keepGuid }),
-          );
+        if (timelineHash === null) timelineHash = hash(JSON.stringify(candidateDraft));
         return timelineHash;
       },
     };
@@ -727,14 +767,43 @@ function indentOf(raw: string | null): string | number {
   return match[1].includes("\t") ? "\t" : match[1].length;
 }
 
-export function serializeDraftCandidate(candidate: DraftCandidate, draft: Draft): string {
-  if (candidate.keepGuid !== undefined) draft = { ...draft, id: candidate.keepGuid };
+function draftForCandidate(candidate: DraftCandidate, draft: Draft, preserveProjectFields: boolean): Draft {
+  if (preserveProjectFields && candidate.draft) {
+    draft = {
+      ...candidate.draft,
+      tracks: draft.tracks,
+      materials: { ...candidate.draft.materials, ...draft.materials },
+      duration: draft.duration,
+      fps: draft.fps,
+      canvas_config: {
+        ...draft.canvas_config,
+        ...candidate.draft.canvas_config,
+        width: draft.canvas_config.width,
+        height: draft.canvas_config.height,
+        ratio: draft.canvas_config.ratio,
+      },
+    };
+  }
+  return candidate.keepGuid === undefined ? draft : { ...draft, id: candidate.keepGuid };
+}
+
+export function serializeDraftCandidate(
+  candidate: DraftCandidate,
+  draft: Draft,
+  preserveProjectFields = false,
+  metadata?: { draft_materials: unknown },
+): string {
+  draft = draftForCandidate(candidate, draft, preserveProjectFields);
   if (!candidate.raw || candidate.envelopePath.length === 0) {
-    return JSON.stringify(draft, null, indentOf(candidate.raw));
+    return JSON.stringify(metadata ? { ...draft, ...metadata } : draft, null, indentOf(candidate.raw));
   }
   const root = JSON.parse(candidate.raw) as unknown;
   const updated = replaceAtPath(root, candidate.envelopePath, draft);
-  return JSON.stringify(updated, null, indentOf(candidate.raw));
+  return JSON.stringify(
+    metadata ? { ...(updated as Record<string, unknown>), ...metadata } : updated,
+    null,
+    indentOf(candidate.raw),
+  );
 }
 
 export function editorProcesses(): string[] {
@@ -957,15 +1026,23 @@ function timelineHashWithoutId(draft: Draft): string {
  * it does not change which file any command reads (PR #51's canonical flip
  * stays rejected pending a field artifact).
  */
-export function planTimelineSync(input: string, opts: { nested?: boolean } = {}): TimelineSyncResult {
+export function planTimelineSync(
+  input: string,
+  opts: { nested?: boolean; activeTimeline?: boolean } = {},
+): TimelineSyncResult {
   const resolved = resolve(input);
-  if (existsSync(resolved) && statSync(resolved).isFile() && basename(resolved) !== "draft_content.json") {
+  const store = discoverDraftStore(input, opts);
+  if (
+    !store.activeTimeline &&
+    existsSync(resolved) &&
+    statSync(resolved).isFile() &&
+    basename(resolved) !== "draft_content.json"
+  ) {
     throw new Error(
       `sync-timelines reconciles a project's mirror files from draft_content.json and cannot target ${basename(resolved)} directly. ` +
         `Pass the project directory instead: capcut sync-timelines ${dirname(resolved)}`,
     );
   }
-  const store = discoverDraftStore(input);
   // draft_content.json is the sync canonical. On the draft_info-primary layout
   // (no draft_content.json; newer Mac builds drive the project from
   // draft_info.json — jianying-mcp#5, pyJianYingDraft#177/#194) draft_info.json
@@ -986,7 +1063,9 @@ export function planTimelineSync(input: string, opts: { nested?: boolean } = {})
     );
   }
   const canonicalNote = store.activeTimeline
-    ? "The selected active timeline is canonical on the evidenced CapCut 8.7.0 Windows layout (issue #50). Only its documents and the root mirrors are reconciled; other timelines are preserved."
+    ? store.activeTimeline.explicit
+      ? "The selected active timeline is canonical by explicit --active-timeline opt-in. Only its documents and root mirrors are reconciled; other timelines are preserved. App round-trip acceptance is unverified on this build."
+      : "The selected active timeline is canonical on the evidenced CapCut 8.7.0 Windows layout (issue #50). Only its documents and the root mirrors are reconciled; other timelines are preserved."
     : canonical.name === "draft_info.json"
       ? "draft_info.json is the canonical source: this project has no draft_content.json (draft_info-primary " +
         "layout, reported as the primary project file on newer Mac builds). Round-trip evidence for this layout " +
@@ -1205,8 +1284,8 @@ export function assessMediaRegistrationAt(draft: Draft, projectDir: string): Med
   }
 }
 
-export function diagnoseDraftStore(input: string): DraftStoreReport {
-  const store = discoverDraftStore(input);
+export function diagnoseDraftStore(input: string, options: DraftStoreOptions = {}): DraftStoreReport {
+  const store = discoverDraftStore(input, options);
   const running = editorProcesses();
   const safety = store.canonical.draft ? assessWriteSafety(store.canonical.draft, store.version) : null;
   const actions: string[] = [];
@@ -1243,7 +1322,11 @@ export function diagnoseDraftStore(input: string): DraftStoreReport {
     );
   }
   if (store.activeTimeline) {
-    actions.push(ACTIVE_TIMELINE_WINDOWS_ACTION);
+    actions.push(
+      store.activeTimeline.explicit
+        ? "Active timeline selected by explicit --active-timeline opt-in. App round-trip acceptance remains unverified on this build."
+        : ACTIVE_TIMELINE_WINDOWS_ACTION,
+    );
   } else if (store.layout === "timelines-nested") actions.push(nestedTimelinesAction(store.version));
   else if (store.nestedTimelines.length > 0) actions.push(NESTED_TIMELINES_MODERN_ACTION);
   if (running.length > 0) actions.push(`Close ${running.join(" / ")} before editing this managed draft.`);
@@ -1264,7 +1347,13 @@ export function diagnoseDraftStore(input: string): DraftStoreReport {
     layout: store.layout,
     nested_timelines: store.nestedTimelines,
     ...(store.activeTimeline
-      ? { active_timeline: { id: store.activeTimeline.id, canonical: store.canonical.name } }
+      ? {
+          active_timeline: {
+            id: store.activeTimeline.id,
+            canonical: store.canonical.name,
+            ...(store.activeTimeline.explicit ? { explicit: true } : {}),
+          },
+        }
       : {}),
     write_guard: safety?.action ?? "ok",
     editor_running: running,
diff --git a/test/active-timeline-opt-in.test.mjs b/test/active-timeline-opt-in.test.mjs
new file mode 100644
index 0000000..6fde445
--- /dev/null
+++ b/test/active-timeline-opt-in.test.mjs
@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import { existsSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { describe, it } from "node:test";
+import { loadDraft, saveDraft, setForceWrite } from "../dist/draft.js";
+import { addAudio } from "../dist/factory.js";
+import { diagnoseDraftStore, discoverDraftStore, planTimelineSync } from "../dist/store.js";
+import { projectShell, readJson, snapshot } from "./helpers/project-shell.mjs";
+import { spawnCli } from "./helpers/spawn-cli.mjs";
+
+describe("explicit active timeline selection (#50)", () => {
+  it("keeps default Mac selection and follows the pointer only on opt-in", (t) => {
+    const s = projectShell(t);
+    assert.equal(discoverDraftStore(s.dir).canonical.path, s.root);
+    assert.equal(discoverDraftStore(s.dir, { activeTimeline: true }).canonical.path, s.active);
+    const report = diagnoseDraftStore(s.dir, { activeTimeline: true });
+    assert.equal(report.active_timeline.explicit, true);
+    assert.match(report.next_actions.join(" "), /acceptance.*unverified/);
+    assert.equal(planTimelineSync(s.active, { activeTimeline: true }).canonicalCandidate.path, s.active);
+    const cli = spawnCli(["diagnose", s.dir, "--active-timeline"]);
+    assert.equal(cli.json.active_timeline.explicit, true, cli.stderr);
+  });
+
+  it("edits and restores the selected timeline, preserving root IDs, pointer and archived edits", (t) => {
+    const s = projectShell(t);
+    const beforePointer = readFileSync(s.pointer, "utf-8");
+    const beforeArchive = readFileSync(s.archive, "utf-8");
+    const mirror = join(dirname(s.active), "template-2.tmp");
+    writeFileSync(mirror, JSON.stringify({ opaque: 1, timeline: JSON.stringify(readJson(s.active)) }));
+    const result = spawnCli(["add-text", s.dir, "0", "1s", "Selected edit", "--active-timeline"]);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(readJson(s.active).tracks[0].segments.length, 1);
+    assert.equal(readJson(s.active).id, "active-id");
+    assert.equal(readJson(s.root).id, "project-id");
+    assert.equal(readJson(mirror).opaque, 1);
+    assert.equal(readFileSync(s.pointer, "utf-8"), beforePointer);
+    assert.equal(readFileSync(s.archive, "utf-8"), beforeArchive);
+    const restored = spawnCli(["restore", s.dir, "--active-timeline"]);
+    assert.equal(restored.status, 0, restored.stderr);
+    assert.equal(readJson(s.active).tracks.length, 0);
+    assert.equal(readJson(s.root).id, "project-id");
+    assert.equal(JSON.parse(readJson(mirror).timeline).tracks.length, 0);
+  });
+
+  for (const [name, pointer] of [
+    ["unsafe id", { main_timeline_id: "../outside" }],
+    ["missing timeline", { main_timeline_id: "absent" }],
+    ["deleted timeline", { main_timeline_id: "active-id", timelines: [{ id: "active-id", is_marked_delete: true }] }],
+    ["malformed pointer", "bad JSON"],
+  ]) {
+    it(`refuses ${name} without falling back to a root write, including force-write`, (t) => {
+      const s = projectShell(t);
+      writeFileSync(s.pointer, typeof pointer === "string" ? pointer : JSON.stringify(pointer));
+      const before = snapshot(s.dir);
+      const result = spawnCli(["add-text", s.dir, "0", "1s", "Keep safe", "--active-timeline", "--force-write"]);
+      assert.notEqual(result.status, 0);
+      assert.match(result.stderr, /active-timeline-invalid/);
+      assert.deepEqual(snapshot(s.dir), before);
+    });
+  }
+
+  it("refuses conflicting documents and explicitly addressed archived timelines", (t) => {
+    const s = projectShell(t);
+    const mirror = join(dirname(s.active), "draft_content.json");
+    writeFileSync(mirror, JSON.stringify({ ...readJson(s.active), duration: 1_000_000 }));
+    assert.throws(() => discoverDraftStore(s.dir, { activeTimeline: true }), /documents disagree/);
+    rmSync(mirror);
+    assert.throws(() => discoverDraftStore(s.archive, { activeTimeline: true }), /inactive timeline/);
+  });
+
+  it("refuses pointer traversal through a symlink", (t) => {
+    const s = projectShell(t);
+    const outside = join(s.base, "outside.json");
+    writeFileSync(outside, readFileSync(s.pointer));
+    rmSync(s.pointer);
+    symlinkSync(outside, s.pointer);
+    assert.throws(() => discoverDraftStore(s.dir, { activeTimeline: true }), /symlink/);
+  });
+
+  it("keeps version and pointer-change guards even with the new option", (t) => {
+    const s = projectShell(t, { version: "99.0.0" });
+    const result = spawnCli(["add-text", s.dir, "0", "1s", "Refuse", "--active-timeline"]);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /version-boundary/);
+    const loaded = loadDraft(s.dir, { activeTimeline: true });
+    writeFileSync(s.pointer, '{"main_timeline_id":"archive-id"}');
+    setForceWrite(true);
+    try {
+      assert.throws(() => saveDraft(loaded.filePath, loaded.draft), /active-timeline-changed/);
+    } finally {
+      setForceWrite(false);
+    }
+  });
+
+  it("uses the loaded project root for library media additions without a process-wide option", (t) => {
+    const s = projectShell(t);
+    const media = join(s.base, "music.wav");
+    writeFileSync(media, "audio bytes");
+    const { draft, filePath } = loadDraft(s.dir, { activeTimeline: true });
+    const result = addAudio(draft, filePath, { path: media, start: 0, duration: 1_000_000 });
+    assert.equal(result.registered, true);
+    assert.ok(draft.materials.audios[0].path.startsWith(join(s.dir, "assets", "audio")));
+    assert.equal(existsSync(join(dirname(s.active), "assets")), false);
+  });
+
+  it("does not consume the option on unrelated free-text commands", () => {
+    const result = spawnCli(["compile", "--active-timeline", "--check"]);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /requires --into/);
+    const described = spawnCli(["describe", "--command", "compile"]);
+    assert.ok(described.json.commands[0].options.some((option) => option.flags.includes("--active-timeline")));
+    const enums = spawnCli(["catalogue", "--active-timeline"]);
+    assert.equal(enums.status, 0, enums.stderr);
+  });
+});
diff --git a/test/compile-into.test.mjs b/test/compile-into.test.mjs
new file mode 100644
index 0000000..3841590
--- /dev/null
+++ b/test/compile-into.test.mjs
@@ -0,0 +1,370 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
+import { join } from "node:path";
+import { after, describe, it } from "node:test";
+import { compileIntoDraft, planCompileInto } from "../dist/compile.js";
+import { setForceWrite } from "../dist/draft.js";
+import { projectShell, readJson, shellDraft, snapshot } from "./helpers/project-shell.mjs";
+import { spawnCli } from "./helpers/spawn-cli.mjs";
+
+const stateDir = fs.mkdtempSync(join((await import("node:os")).tmpdir(), "capcut-into-state-"));
+const previousState = process.env.CAPCUT_CLI_APP_VERSIONS;
+process.env.CAPCUT_CLI_APP_VERSIONS = join(stateDir, "versions.json");
+after(() => {
+  fs.rmSync(stateDir, { recursive: true, force: true });
+  if (previousState === undefined) delete process.env.CAPCUT_CLI_APP_VERSIONS;
+  else process.env.CAPCUT_CLI_APP_VERSIONS = previousState;
+});
+
+const textSpec = () => ({
+  name: "Spec name",
+  tracks: [{ type: "text", items: [{ ref: "title", text: "A title", start: 0, duration: 2 }] }],
+});
+const options = (s) => ({ intoDir: s.dir, specDir: s.base, activeTimeline: true });
+function mediaSpec(s) {
+  const spec = textSpec();
+  fs.writeFileSync(join(s.base, "clip.mp4"), "first video bytes");
+  fs.writeFileSync(join(s.base, "music.wav"), "audio bytes");
+  spec.tracks.push({ type: "video", items: [{ path: "clip.mp4", start: 0, duration: 3 }] });
+  spec.tracks.push({ type: "audio", items: [{ path: "music.wav", start: 0, duration: 3 }] });
+  return spec;
+}
+
+function inject(method, replacement, run) {
+  const original = fs[method];
+  fs[method] = (...args) => replacement(original, ...args);
+  syncBuiltinESMExports();
+  try {
+    run();
+  } finally {
+    fs[method] = original;
+    syncBuiltinESMExports();
+  }
+}
+
+describe("compile into an app-created empty project (#52)", () => {
+  it("keeps each document's identity, markers, unknown settings and store registration", (t) => {
+    const s = projectShell(t);
+    const spec = mediaSpec(s);
+    const root = readJson(s.root);
+    root.name = "Root project name";
+    root.platform.app_version = "7.6.0";
+    root.root_only = { preserve: true };
+    root.canvas_config.app_setting = "root-specific";
+    root.materials.root_only = [{ opaque: true }];
+    fs.writeFileSync(s.root, JSON.stringify(root));
+    const index = fs.readFileSync(s.index, "utf-8");
+    const pointer = fs.readFileSync(s.pointer, "utf-8");
+    const archive = fs.readFileSync(s.archive, "utf-8");
+    const meta = readJson(s.meta);
+    const result = compileIntoDraft(spec, options(s));
+    assert.equal(result.into, true);
+    assert.equal(result.file_path, s.active);
+    assert.equal(result.name, "App-created shell");
+    assert.equal(result.duration_us, 3_000_000);
+    const active = readJson(s.active);
+    const writtenRoot = readJson(s.root);
+    assert.equal(active.id, "active-id");
+    assert.equal(writtenRoot.id, root.id);
+    assert.equal(writtenRoot.name, root.name);
+    assert.deepEqual(writtenRoot.platform, root.platform);
+    assert.deepEqual(writtenRoot.root_only, root.root_only);
+    assert.equal(writtenRoot.canvas_config.app_setting, "root-specific");
+    assert.deepEqual(writtenRoot.materials.root_only, root.materials.root_only);
+    assert.deepEqual(active.canvas_config, shellDraft().canvas_config);
+    assert.equal(active.fps, 24);
+    assert.deepEqual(active.opaque_setting, shellDraft().opaque_setting);
+    assert.equal(fs.readFileSync(s.index, "utf-8"), index);
+    assert.equal(fs.readFileSync(s.pointer, "utf-8"), pointer);
+    assert.equal(fs.readFileSync(s.archive, "utf-8"), archive);
+    const sidecar = readJson(s.meta);
+    assert.equal(sidecar.draft_id, meta.draft_id);
+    assert.equal(sidecar.draft_name, meta.draft_name);
+    assert.deepEqual(sidecar.opaque, meta.opaque);
+    assert.deepEqual(
+      sidecar.draft_materials.find((group) => group.type === 1),
+      meta.draft_materials[0],
+    );
+    for (const material of [...active.materials.videos, ...active.materials.audios]) {
+      assert.ok(material.path.startsWith(join(s.dir, "assets")));
+      assert.ok(fs.existsSync(material.path));
+      assert.ok(
+        sidecar.draft_materials
+          .flatMap((group) => group.value)
+          .some((entry) => entry.id === material.local_material_id && entry.file_Path === material.path),
+      );
+    }
+    assert.equal(fs.readFileSync(`${s.active}.bak`, "utf-8"), JSON.stringify(shellDraft("active-id"), null, 2));
+    assert.equal(fs.readFileSync(`${s.meta}.bak`, "utf-8"), JSON.stringify(meta));
+    assert.equal(fs.existsSync(join(s.dir, "Timelines", "active-id", "assets")), false);
+  });
+
+  it("supports a flat shell, preserving settings unless the spec explicitly changes them", (t) => {
+    const s = projectShell(t, { nested: false });
+    const spec = { ...textSpec(), width: 1920, height: 1080, fps: 30 };
+    const result = compileIntoDraft(spec, { ...options(s), activeTimeline: false });
+    assert.equal(result.file_path, s.root);
+    assert.equal(readJson(s.root).canvas_config.width, 1920);
+    assert.equal(readJson(s.root).canvas_config.app_setting, true);
+    assert.equal(readJson(s.root).fps, 30);
+  });
+
+  for (const preview of ["--check", "--plan", "--dry-run"]) {
+    it(`validates the target and leaves all files unchanged with ${preview}`, (t) => {
+      const s = projectShell(t);
+      const specPath = join(s.base, "spec.json");
+      fs.writeFileSync(specPath, JSON.stringify(mediaSpec(s)));
+      const before = snapshot(s.base);
+      const result = spawnCli(["compile", specPath, "--into", s.dir, "--active-timeline", preview]);
+      assert.equal(result.status, 0, result.stderr);
+      assert.equal(result.json.into, true);
+      assert.equal(result.json.write, false);
+      assert.equal(result.json.canvas.fps, 24);
+      assert.equal(result.json.name, "App-created shell");
+      assert.deepEqual(snapshot(s.base), before);
+    });
+  }
+
+  for (const target of ["root", "active"]) {
+    it(`refuses existing edits in the ${target}, including a forced write`, (t) => {
+      const s = projectShell(t);
+      const doc = readJson(s[target]);
+      doc.tracks = [{ id: "existing", type: "text", segments: [{ material_id: "keep" }] }];
+      fs.writeFileSync(s[target], JSON.stringify(doc));
+      const before = snapshot(s.dir);
+      setForceWrite(true);
+      try {
+        assert.throws(() => compileIntoDraft(textSpec(), options(s)), /must be empty/);
+      } finally {
+        setForceWrite(false);
+      }
+      assert.deepEqual(snapshot(s.dir), before);
+    });
+  }
+
+  it("checks destination emptiness for previews too", (t) => {
+    const s = projectShell(t);
+    fs.writeFileSync(s.root, JSON.stringify({ ...readJson(s.root), duration: 1_000_000 }));
+    assert.throws(() => planCompileInto(textSpec(), options(s)), /must be empty/);
+  });
+
+  it("requires active selection for nested layouts and keeps the version boundary", (t) => {
+    const s = projectShell(t, { version: "99.0.0" });
+    assert.throws(
+      () => compileIntoDraft(textSpec(), { ...options(s), activeTimeline: false }),
+      /require --active-timeline/,
+    );
+    const before = snapshot(s.dir);
+    assert.throws(() => compileIntoDraft(mediaSpec(s), options(s)), /version-boundary/);
+    assert.deepEqual(snapshot(s.dir), before);
+  });
+
+  it("rejects invalid operations and unreadable sidecars before creating assets", (t) => {
+    const s = projectShell(t);
+    const spec = mediaSpec(s);
+    spec.operations = [{ op: "transition", target: "title", slug: "missing-transition" }];
+    const before = snapshot(s.dir);
+    assert.throws(() => compileIntoDraft(spec, options(s)), /transition/);
+    assert.deepEqual(snapshot(s.dir), before);
+    delete spec.operations;
+    fs.writeFileSync(s.meta, "bad sidecar");
+    assert.throws(() => compileIntoDraft(spec, options(s)), /readable app-created/);
+    assert.equal(fs.existsSync(join(s.dir, "assets")), false);
+  });
+
+  it("preserves colliding existing media and stages distinct same-named sources correctly", (t) => {
+    const s = projectShell(t);
+    const spec = mediaSpec(s);
+    const assets = join(s.dir, "assets", "video");
+    fs.mkdirSync(assets, { recursive: true });
+    fs.writeFileSync(join(assets, "clip.mp4"), "existing media");
+    fs.mkdirSync(join(s.base, "other"));
+    fs.writeFileSync(join(s.base, "other", "clip.mp4"), "second video bytes");
+    spec.tracks[1].items.push({ path: "other/clip.mp4", start: 3, duration: 1 });
+    compileIntoDraft(spec, options(s));
+    assert.equal(fs.readFileSync(join(assets, "clip.mp4"), "utf-8"), "existing media");
+    const videos = readJson(s.active).materials.videos;
+    assert.equal(new Set(videos.map((material) => material.path)).size, 2);
+    assert.deepEqual(
+      videos.map((material) => fs.readFileSync(material.path, "utf-8")),
+      ["first video bytes", "second video bytes"],
+    );
+  });
+
+  it("removes partial copies and newly created asset directories on an I/O failure", (t) => {
+    const s = projectShell(t);
+    const spec = mediaSpec(s);
+    const before = snapshot(s.dir);
+    inject(
+      "writeSync",
+      (original, fd, ...args) => {
+        if (Buffer.isBuffer(args[0])) {
+          original(fd, ...args);
+          throw new Error("injected copy failure");
+        }
+        return original(fd, ...args);
+      },
+      () => assert.throws(() => compileIntoDraft(spec, options(s)), /copy failure/),
+    );
+    assert.deepEqual(snapshot(s.dir), before);
+  });
+
+  it("rolls back timeline and sidecar targets after a partial commit", (t) => {
+    const s = projectShell(t);
+    const spec = mediaSpec(s);
+    const before = [s.root, s.active, s.meta, s.index, s.pointer, s.archive].map((path) =>
+      fs.readFileSync(path, "utf-8"),
+    );
+    inject(
+      "renameSync",
+      (original, source, destination) => {
+        if (destination === s.meta) throw new Error("injected sidecar commit failure");
+        return original(source, destination);
+      },
+      () => assert.throws(() => compileIntoDraft(spec, options(s)), /sidecar commit failure/),
+    );
+    for (const [index, path] of [s.root, s.active, s.meta, s.index, s.pointer, s.archive].entries())
+      assert.equal(fs.readFileSync(path, "utf-8"), before[index]);
+    assert.equal(fs.existsSync(join(s.dir, "assets")), false);
+  });
+
+  it("preserves another writer's sidecar and index changes and cleans staged assets", (t) => {
+    const s = projectShell(t);
+    const spec = mediaSpec(s);
+    const beforeTimeline = fs.readFileSync(s.active, "utf-8");
+    let changed = false;
+    inject(
+      "writeSync",
+      (original, fd, ...args) => {
+        if (!changed && Buffer.isBuffer(args[0])) {
+          changed = true;
+          fs.writeFileSync(s.meta, '{"another_writer":true}');
+          fs.writeFileSync(s.index, "another writer's index");
+        }
+        return original(fd, ...args);
+      },
+      () => assert.throws(() => compileIntoDraft(spec, options(s)), /sidecar changed/),
+    );
+    assert.equal(fs.readFileSync(s.meta, "utf-8"), '{"another_writer":true}');
+    assert.equal(fs.readFileSync(s.index, "utf-8"), "another writer's index");
+    assert.equal(fs.readFileSync(s.active, "utf-8"), beforeTimeline);
+    assert.equal(fs.existsSync(join(s.dir, "assets")), false);
+  });
+
+  it("refuses a pointer changed while assets are staged, even with force-write", (t) => {
+    const s = projectShell(t);
+    const spec = mediaSpec(s);
+    const before = fs.readFileSync(s.active, "utf-8");
+    let changed = false;
+    inject(
+      "writeSync",
+      (original, fd, ...args) => {
+        if (!changed && Buffer.isBuffer(args[0])) {
+          changed = true;
+          fs.writeFileSync(s.pointer, '{"main_timeline_id":"archive-id"}');
+        }
+        return original(fd, ...args);
+      },
+      () => {
+        setForceWrite(true);
+        try {
+          assert.throws(() => compileIntoDraft(spec, options(s)), /active-timeline-changed/);
+        } finally {
+          setForceWrite(false);
+        }
+      },
+    );
+    assert.equal(fs.readFileSync(s.active, "utf-8"), before);
+    assert.equal(fs.existsSync(join(s.dir, "assets")), false);
+  });
+
+  it("preserves edits made to an empty mirror during staging, even with force-write", (t) => {
+    const s = projectShell(t);
+    const spec = mediaSpec(s);
+    const edited = JSON.stringify({ ...readJson(s.root), duration: 1_000_000 });
+    let changed = false;
+    inject(
+      "writeSync",
+      (original, fd, ...args) => {
+        if (!changed && Buffer.isBuffer(args[0])) {
+          changed = true;
+          fs.writeFileSync(s.root, edited);
+        }
+        return original(fd, ...args);
+      },
+      () => {
+        setForceWrite(true);
+        try {
+          assert.throws(() => compileIntoDraft(spec, options(s)), /draft-changed-on-disk/);
+        } finally {
+          setForceWrite(false);
+        }
+      },
+    );
+    assert.equal(fs.readFileSync(s.root, "utf-8"), edited);
+    assert.equal(readJson(s.active).tracks.length, 0);
+    assert.equal(fs.existsSync(join(s.dir, "assets")), false);
+  });
+
+  it("reuses existing registered media without rewriting its sidecar", (t) => {
+    const s = projectShell(t);
+    const spec = mediaSpec(s);
+    spec.tracks = [spec.tracks[1]];
+    const asset = join(s.dir, "assets", "video", "clip.mp4");
+    fs.mkdirSync(join(s.dir, "assets", "video"), { recursive: true });
+    fs.copyFileSync(join(s.base, "clip.mp4"), asset);
+    const meta = readJson(s.meta);
+    meta.draft_materials.push({ type: 0, value: [{ id: "existing-import-id", file_Path: asset, opaque: true }] });
+    fs.writeFileSync(s.meta, JSON.stringify(meta));
+    const before = fs.readFileSync(s.meta, "utf-8");
+    compileIntoDraft(spec, options(s));
+    assert.equal(readJson(s.active).materials.videos[0].local_material_id, "existing-import-id");
+    assert.equal(fs.readFileSync(s.meta, "utf-8"), before);
+    assert.equal(fs.existsSync(`${s.meta}.bak`), false);
+  });
+
+  it("refuses an asset-directory symlink and preserves the external directory", (t) => {
+    const s = projectShell(t);
+    const spec = mediaSpec(s);
+    const outside = join(s.base, "outside");
+    fs.mkdirSync(outside);
+    fs.writeFileSync(join(outside, "keep.txt"), "outside bytes");
+    fs.symlinkSync(outside, join(s.dir, "assets"), "junction");
+    const before = snapshot(s.dir);
+    assert.throws(() => compileIntoDraft(spec, options(s)), /symlink traversal/);
+    assert.deepEqual(snapshot(s.dir), before);
+    assert.deepEqual(fs.readdirSync(outside), ["keep.txt"]);
+  });
+
+  it("commits registration once when the metadata sidecar also contains a timeline", (t) => {
+    const s = projectShell(t, { nested: false });
+    const spec = mediaSpec(s);
+    const meta = { ...readJson(s.meta), timeline: JSON.stringify(shellDraft()) };
+    fs.writeFileSync(s.meta, JSON.stringify(meta));
+    compileIntoDraft(spec, { ...options(s), activeTimeline: false });
+    const sidecar = readJson(s.meta);
+    const embedded = JSON.parse(sidecar.timeline);
+    assert.equal(embedded.duration, 3_000_000);
+    assert.equal(sidecar.opaque.keep, 1);
+    assert.ok(
+      sidecar.draft_materials
+        .flatMap((group) => group.value)
+        .some((entry) => entry.id === embedded.materials.videos[0].local_material_id),
+    );
+    assert.equal(fs.readFileSync(`${s.meta}.bak`, "utf-8"), JSON.stringify(meta));
+  });
+
+  for (const flag of ["--out", "--drafts", "--template", "--data"]) {
+    it(`rejects ${flag} with --into before any writes`, (t) => {
+      const s = projectShell(t);
+      const specPath = join(s.base, "spec.json");
+      fs.writeFileSync(specPath, JSON.stringify(textSpec()));
+      const before = snapshot(s.base);
+      const result = spawnCli(["compile", specPath, "--into", s.dir, flag, "value"]);
+      assert.notEqual(result.status, 0);
+      assert.match(result.stderr, /incompatible/);
+      assert.deepEqual(snapshot(s.base), before);
+    });
+  }
+});
diff --git a/test/describe.test.mjs b/test/describe.test.mjs
index 8e86645..3dd77c0 100644
--- a/test/describe.test.mjs
+++ b/test/describe.test.mjs
@@ -1,9 +1,71 @@
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
 import { describe, it } from "node:test";
+import { extractText } from "../dist/draft.js";
 import { spawnCli } from "./helpers/spawn-cli.mjs";
+import { tmpDraft } from "./helpers/tmp-draft.mjs";
 
 // `describe` emits a machine-readable tool spec for agent callers.
 describe("describe", () => {
+  it("offers a compact discovery index below 64 KiB without losing command names", () => {
+    const full = spawnCli(["describe"]);
+    const compact = spawnCli(["describe", "--compact"]);
+    assert.equal(compact.status, 0, compact.stderr);
+    assert.equal(compact.json.detail, "compact");
+    assert.equal(full.json.detail, undefined);
+    assert.deepEqual(
+      compact.json.commands.map((command) => command.name),
+      full.json.commands.map((command) => command.name),
+    );
+    assert.ok(Buffer.byteLength(compact.stdout) < 64 * 1024);
+    assert.ok(Buffer.byteLength(compact.stdout) < Buffer.byteLength(full.stdout) / 2);
+    assert.deepEqual(compact.json.global_flags, full.json.global_flags);
+    for (const command of compact.json.commands) {
+      assert.ok(command.summary && command.usage);
+      assert.equal(typeof command.mutates, "boolean");
+      assert.equal(command.options, undefined);
+    }
+  });
+
+  it("filters complete contracts, deduplicates repeated selections, and supports compact filters", () => {
+    const full = spawnCli(["describe"]);
+    const selected = spawnCli(["describe", "--command", "compile", "--command", "relink", "--command", "compile"]);
+    assert.equal(selected.status, 0, selected.stderr);
+    assert.deepEqual(
+      selected.json.commands,
+      full.json.commands.filter((command) => ["compile", "relink"].includes(command.name)),
+    );
+    const compact = spawnCli(["describe", "--compact", "--command", "compile"]);
+    assert.equal(compact.status, 0, compact.stderr);
+    assert.deepEqual(
+      compact.json.commands.map((command) => command.name),
+      ["compile"],
+    );
+    assert.equal(compact.json.commands[0].options, undefined);
+  });
+
+  it("refuses unknown, missing, and empty command selections", () => {
+    for (const args of [["--command", "not-a-command"], ["--command"], ["--command", ""], ["--command", "--compact"]]) {
+      const result = spawnCli(["describe", ...args]);
+      assert.notEqual(result.status, 0);
+      assert.match(JSON.parse(result.stderr).error, /command/i);
+    }
+  });
+
+  it("preserves discovery flags as free text on unrelated commands", () => {
+    const fix = tmpDraft();
+    try {
+      const result = spawnCli(["add-text", fix.path, "0s", "1s", "--compact", "--command", "compile"]);
+      assert.equal(result.status, 0, result.stderr);
+      const draft = JSON.parse(readFileSync(fix.path, "utf8"));
+      assert.ok(
+        draft.materials.texts.some((material) => extractText(material.content) === "--compact --command compile"),
+      );
+    } finally {
+      fix.cleanup();
+    }
+  });
+
   it("emits valid JSON with name, version, global_flags, and commands", () => {
     const r = spawnCli(["describe"]);
     assert.equal(r.status, 0, `stderr: ${r.stderr}`);
diff --git a/test/helpers/project-shell.mjs b/test/helpers/project-shell.mjs
new file mode 100644
index 0000000..be37f12
--- /dev/null
+++ b/test/helpers/project-shell.mjs
@@ -0,0 +1,81 @@
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Synthetic fixtures exercise write safety, not CapCut desktop acceptance.
+export function shellDraft(id = "project-id", version = "7.7.0") {
+  return {
+    id,
+    name: "App-created shell",
+    duration: 0,
+    fps: 24,
+    canvas_config: { width: 720, height: 1280, ratio: "9:16", app_setting: true },
+    platform: { app_source: "cc", app_version: version, os: "mac" },
+    opaque_setting: { keep: "app-owned" },
+    tracks: [],
+    materials: {
+      videos: [],
+      audios: [],
+      texts: [],
+      speeds: [],
+      material_animations: [],
+      audio_fades: [],
+      transitions: [],
+    },
+  };
+}
+
+export function projectShell(t, { nested = true, version = "7.7.0" } = {}) {
+  const base = mkdtempSync(join(tmpdir(), "capcut-shell-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+  const dir = join(base, "App project 工具");
+  mkdirSync(dir);
+  const root = join(dir, "draft_info.json");
+  writeFileSync(root, JSON.stringify(shellDraft("project-id", version), null, 2));
+  const meta = join(dir, "draft_meta_info.json");
+  writeFileSync(
+    meta,
+    JSON.stringify({
+      draft_id: "project-id",
+      draft_name: "App-created shell",
+      opaque: { keep: 1 },
+      draft_materials: [{ type: 1, value: [{ id: "preserve-entry", file_Path: "/old/import.wav", custom: true }] }],
+    }),
+  );
+  const index = join(base, "root_meta_info.json");
+  writeFileSync(index, '{"all_draft_store":[{"draft_id":"project-id","app_owned":true}],"opaque":"preserve"}');
+  let active = root;
+  let pointer;
+  let archive;
+  if (nested) {
+    mkdirSync(join(dir, "Timelines", "active-id"), { recursive: true });
+    pointer = join(dir, "Timelines", "project.json");
+    writeFileSync(
+      pointer,
+      JSON.stringify({ main_timeline_id: "active-id", timelines: [{ id: "active-id" }], opaque: true }),
+    );
+    active = join(dir, "Timelines", "active-id", "draft_info.json");
+    writeFileSync(active, JSON.stringify(shellDraft("active-id", version), null, 2));
+    mkdirSync(join(dir, "Timelines", "archive-id"));
+    archive = join(dir, "Timelines", "archive-id", "draft_info.json");
+    writeFileSync(archive, JSON.stringify({ ...shellDraft("archive-id", version), duration: 9_000_000 }));
+  }
+  return { base, dir, root, active, meta, index, pointer, archive };
+}
+
+export const readJson = (path) => JSON.parse(readFileSync(path, "utf-8"));
+
+export function snapshot(dir) {
+  const files = {};
+  const visit = (path, prefix = "") => {
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+      const key = `${prefix}${entry.name}`;
+      if (entry.isDirectory()) {
+        files[`${key}/`] = null;
+        visit(join(path, entry.name), `${key}/`);
+      } else if (entry.isFile()) files[key] = readFileSync(join(path, entry.name)).toString("base64");
+    }
+  };
+  visit(dir);
+  return files;
+}
diff --git a/test/serve-boundaries.test.mjs b/test/serve-boundaries.test.mjs
index 034228b..7a0ca8f 100644
--- a/test/serve-boundaries.test.mjs
+++ b/test/serve-boundaries.test.mjs
@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, relative } from "node:path";
 import { after, describe, it } from "node:test";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { projectShell } from "./helpers/project-shell.mjs";
 import { tmpDraft } from "./helpers/tmp-draft.mjs";
 
 const SERVE_URL = pathToFileURL(join(dirname(fileURLToPath(import.meta.url)), "../dist/serve.js")).href;
@@ -307,6 +308,26 @@ describe("serve queue identity and capture boundaries", () => {
     assert.ok(indexOf("end", "rename") < indexOf("begin", "renamed-target"));
   });
 
+  it("serializes shell compilation with edits through root and unverified nested file aliases", (t) => {
+    const fixture = setup();
+    t.after(fixture.cleanup);
+    const shell = projectShell(t);
+    fixture.script(eventScript(fixture.log));
+    const result = fixture.run(
+      [
+        { cmd: "compile", args: ["spec.json", "--into", shell.dir, "--active-timeline", "compile"] },
+        { cmd: "add-text", args: [shell.active, "0", "1s", "--active-timeline", "nested"] },
+        { cmd: "add-text", args: [shell.root, "0", "1s", "--active-timeline", "root"] },
+      ],
+      { workers: 3 },
+    );
+    assert.equal(result.status, 0, result.stderr);
+    assert.deepEqual(
+      fixture.events().map((event) => event.event),
+      ["begin", "end", "begin", "end", "begin", "end"],
+    );
+  });
+
   it("allows separate projects to run concurrently and does not treat non-project arguments as projects", () => {
     const fixture = setup();
     const first = tmpDraft();