用途：把源仓库（如 dash0hq/otel-cicd-action）的文档同步到 Dash0 官网仓库。转换与 PR 流程都封装在 action 中，各源仓库共用同一实现。调用方先检出自身仓库，再调用该 action。
主要能力：两种模式。dry-run（dry-run: "true"）只应用转换与覆盖检查后停止，不检出目标仓库、不复制、不建 PR，无需目标侧输入和令牌，适合在 PR 和非发布构建上做漂移/覆盖守卫。完整同步（dry-run: "false"，默认）端到端运行，在目标仓库创建或更新 PR，需要目标侧输入和令牌。
关键输入：source-root（默认 .）、transformations-file（默认 .github/workflows/sync-docs/transformations.yaml，相对 source-root）、dry-run、target-repository、target-directory、target-github-token、target-base-branch（默认 main）、pr-branch、pr-title、pr-body、pr-reviewers、pr-assignees、commit-message。除 dry-run 外的目标侧必需输入在运行时校验，缺失会报错，因为复合 action 的 required: true 不被强制执行，且必需项取决于 dry-run。
transformations.yaml：files: 是唯一的选择加入允许列表，未列出的文件被忽略；会自动为每个条目生成并前置 frontmatter（title/description 及 lastUpdated 时间戳），不要在源文档手写 frontmatter。common: 放所有文件共享的转换，按顺序执行；files 条目的 transformations: 只对该文件生效，在 common: 之后运行。转换类型有 prepend、replace-regex（可选 flags：multiline、dotall、ignorecase；默认必须至少匹配一次，可用 required: false 允许零匹配）、remove-line。插入或替换文本中唯一支持的占位符是 $timestamp。coverage: 可选，用于让新文档页未被同步时令 CI 失败；nav: 可选，生成 nav.json，支持 id、title、order、parentPath、groupTitles。
使用方式：源仓库加 .github/workflows/sync-docs.yml，一次调用覆盖两种模式，由 dry-run 决定；真实同步通过 workflow_dispatch（取消勾选 dry-run）或 release 工作流的 workflow_call 触发，模板不含 push 触发。
限制：目标仓库、目录和令牌密钥名因调用方而异，不应硬编码，需向用户确认；验证时需检出 sync-docs-action 并从其根目录运行 pnpm install --frozen-lockfile，再执行 node packages/transformation-engine/src/apply-transformations.ts <source-root> <source-root>/.github/workflows/sync-docs/transformations.yaml /tmp/transformed-docs。迁移版本时，target-repository 和 target-directory 不再有默认值，属破坏性变更。