docs: make workflow sync one-command

README.md

@@ -2,20 +2,21 @@
 
 [中文](zh/README.md) | English
 
-This repository publishes bilingual downstream workflow-document templates, the canonical
-`workflow-docs-sync` Skill, and its installer. Chinese under `zh/` is the semantic source; `en/` is derived.
-
-Invoke the Skill once with only the target Git repository, `zh` or `en`, and whether a draft PR should be
-created after success:
+Copy this exact instruction into Codex while it is open in the target project:
 
 ```text
-Use $workflow-docs-sync for /absolute/path/to/repository in English.
-Do not create a draft PR.
+Use $skill-installer to install https://github.com/wlvh/coding-workflow/tree/main/zh/skills/workflow-docs-sync, then immediately use $workflow-docs-sync to synchronize the current project's documentation and create a draft pull request. If the newly installed Skill is not registered in the current session, read SKILL.md from the installation directory returned by the installer and continue in the same turn; do not stop to request a restart.
 ```
 
-The repository root contains CI and GitHub infrastructure. Downstream `.github/` templates live under the
-language directories and are installed without that leading language prefix.
+It infers the current Git root and request language, preserves an unclean original worktree through an
+external clean worktree, and creates only a draft PR. A newly installed Skill is read from the installer’s
+actual returned directory when the current session has not registered it yet.
+
+This repository publishes bilingual downstream workflow-document templates, the canonical
+`workflow-docs-sync` Skill, and its installer. Chinese under `zh/` is the semantic source; `en/` is derived.
+
+Detailed behavior and optional repository installation are in the [中文指南](zh/README.md#一句话开始) and
+[English guide](en/README.md#one-line-start).
 
 For source ownership, edit locations, and validation commands, use the
-[Chinese maintainer map](zh/README.md#维护者地图). English template and directory guidance is available in
-[en/README.md](en/README.md).
+[Chinese maintainer map](zh/README.md#维护者地图).

en/README.md

@@ -6,32 +6,94 @@ This directory provides English templates derived from the Chinese semantic sour
 language-, framework-, and project-neutral. The canonical `workflow-docs-sync` Skill remains under
 `zh/skills/workflow-docs-sync/` and reads English templates from the pinned upstream commit.
 
-## Quick Start
+## One-line start
 
-Invoke the Skill once with the target Git repository, `zh` or `en`, and whether to create a draft PR after
-success:
+Copy this exact instruction into Codex while it is open in the target project:
 
 ```text
-Use $workflow-docs-sync for /absolute/path/to/repository in English.
-Do not create a draft PR.
+Use $skill-installer to install https://github.com/wlvh/coding-workflow/tree/main/zh/skills/workflow-docs-sync, then immediately use $workflow-docs-sync to synchronize the current project's documentation and create a draft pull request. If the newly installed Skill is not registered in the current session, read SKILL.md from the installation directory returned by the installer and continue in the same turn; do not stop to request a restart.
 ```
 
+The instruction above is for first-time installation; once the Skill is installed, in another project directly ask `$workflow-docs-sync` to synchronize the current project's documentation and create a draft pull request.
+
+The user does not provide an absolute target path, `zh` / `en`, a branch name, upstream SHA, or installation
+path, and does not need to clean the target worktree first. A successful system `$skill-installer` run prints
+`Installed workflow-docs-sync to <installed-skill-root>`. If the current session has not registered the
+Skill, use that actual directory from this successful run, read its complete `SKILL.md`, resolve scripts from
+the same directory, and continue in the current turn. Do not guess an installation path or wait for another
+turn.
+
+## Defaults
+
+- Target: use the Git root containing Codex's current working directory. Ask only when the current directory
+  is not in a Git repository.
+- Language: an explicit `zh` / `en` wins; otherwise a Chinese request selects `zh` and any other language
+  selects `en`.
+- PR: an explicit request not to create a PR selects false. Mentioning PR, opening, creating, or submitting a
+  pull request selects true. No mention selects false. The Skill never marks a PR Ready or merges it.
+- Worktree: when a PR is requested, always create an external clean worktree and a unique branch from the
+  committed HEAD captured at invocation. The Skill does not change ordinary, staged, untracked, or ignored
+  content in the original worktree, or stash, clean, commit, or overwrite user changes there.
+  Before the final report, it compares the captured NUL-delimited status and staged entries, then rechecks
+  type, mode, regular-file SHA-256, or symlink target only for non-clean paths enumerated by the invocation-time
+  status and ignored-path snapshot. It does not hash the whole repository or compare raw Git index-file bytes.
+  New ignored paths created concurrently are outside the original set; any other difference proves concurrent
+  change, not that the Agent caused it.
+
+The final report states that the sync and PR use the invocation-time committed HEAD and exclude uncommitted
+changes from the original worktree.
+
+A repository with no commit is a `BLOCKER`. If documentation sync passes but the remote, authentication,
+push permission, or PR creation fails, the Skill preserves the external worktree, branch, commit, and
+out-of-repository PR body. It reports `Documentation sync: PASS`, `Publication: PR_BLOCKED`, and
+`Overall: PARTIAL` instead of claiming that a PR exists.
+
+## Repository installer (optional)
+
+This path is for maintainers or for installing both Codex and Claude copies; it is not the one-line entrypoint
+above. Clone the canonical repository and verify that this upstream checkout is clean. That clean requirement
+does not apply to the target project being synchronized:
+
+```bash
+git clone --depth 1 https://github.com/wlvh/coding-workflow.git
+cd coding-workflow
+
+git status --porcelain=v1 --untracked-files=all
+python3 zh/scripts/install_skills.py --upstream-dir "$PWD"
+```
+
+`git status` should print nothing. If it prints an entry, stop and inspect the canonical checkout. A
+successful JSON result lists actions for both `~/.agents/skills/workflow-docs-sync/` and
+`~/.claude/skills/workflow-docs-sync/`.
+
+To review and share the Skill as part of a target project, run this from the canonical checkout root:
+
+```bash
+python3 zh/scripts/install_skills.py \
+  --scope repo \
+  --target-repo "/absolute/path/to/target-repository" \
+  --upstream-dir "$PWD"
+```
+
+The repo-scope target must be exactly a clean Git repository root. Review the resulting Git diff, then commit
+it according to the target project's policy. Both scopes replace an existing Skill with the same name,
+remove only the obsolete `workflow-docs-sync-review`, store no source state, and do not update automatically.
+Studio can also load the canonical `zh/skills/workflow-docs-sync/` directly.
+
+## Synchronization boundary
+
 The Skill pins target HEAD and upstream SHA, reconstructs facts from current code, configuration, tests,
 committed artifacts, reproducible results, and necessary Git history, then makes only the document changes
 those facts require. Existing documents and upstream templates are hypotheses, not evidence.
 
 Architecture, Capability / User Behavior, Testing, and Governance are coverage dimensions, not a fixed
-agent topology. The main agent is the only target-workspace writer. Test environments follow actual
+agent topology. The main agent is the only execution-worktree writer. Test environments follow actual
 commands, side effects, CI capabilities, and project policy.
 
 Review prefers a fresh-context, blind-first independent reviewer. When cognitive isolation is unavailable,
 the result is reported honestly as self-review. The deterministic checker proves final repository state
 only, not investigation, test, or review history.
 
-The installer copies only the canonical Skill. Before any target mutation it rejects symlinks, frontmatter
-without standard delimiters, and ignored source residue that would otherwise be copied; it stores no source
-receipt.
-
 ## Template Contract
 
 Markdown project-fill slots use `<!-- project-fill: ... -->`; JSON uses strings prefixed with

tests/test_workflow_docs_sync.py

@@ -37,6 +37,22 @@
     ("claude", Path(".claude/skills")),
 )
 OBSOLETE_SKILL = "workflow-docs-sync-review"
+ZH_FIRST_USE_PROMPT = (
+    "用 $skill-installer 安装 "
+    "https://github.com/wlvh/coding-workflow/tree/main/zh/skills/"
+    "workflow-docs-sync，然后立即用 $workflow-docs-sync 同步当前项目文档并创建 "
+    "draft PR；如果当前会话尚未注册新 Skill，直接读取安装器返回目录中的 "
+    "SKILL.md 继续执行，不要停下来要求重启。"
+)
+EN_FIRST_USE_PROMPT = (
+    "Use $skill-installer to install https://github.com/wlvh/coding-workflow/"
+    "tree/main/zh/skills/workflow-docs-sync, then immediately use "
+    "$workflow-docs-sync to synchronize the current project's documentation "
+    "and create a draft pull request. If the newly installed Skill is not "
+    "registered in the current session, read SKILL.md from the installation "
+    "directory returned by the installer and continue in the same turn; do not "
+    "stop to request a restart."
+)
 
 
 def run_command(
@@ -1337,6 +1353,36 @@ def test_scenario_5_repository_distribution_contract() -> None:
     root_agents = REPO_ROOT / "AGENTS.md"
     assert root_agents.is_file() and not root_agents.is_symlink()
 
+    # 两种公开 prompt 必须位于对应首次使用入口，避免英文入口回退为中文。
+    assert ZH_FIRST_USE_PROMPT != EN_FIRST_USE_PROMPT
+    readme_prompts = (
+        (
+            REPO_ROOT / "zh/README.md",
+            "## 一句话开始",
+            "## 默认行为",
+            ZH_FIRST_USE_PROMPT,
+        ),
+        (
+            REPO_ROOT / "en/README.md",
+            "## One-line start",
+            "## Defaults",
+            EN_FIRST_USE_PROMPT,
+        ),
+        (
+            REPO_ROOT / "README.md",
+            "Copy this exact instruction into Codex",
+            "This repository publishes",
+            EN_FIRST_USE_PROMPT,
+        ),
+    )
+    for readme, entry_start, entry_end, prompt in readme_prompts:
+        readme_text = readme.read_text(encoding="utf-8")
+        assert readme_text.count(prompt) == 1
+        start_index = readme_text.index(entry_start)
+        end_index = readme_text.index(entry_end)
+        entry_text = readme_text[start_index:end_index]
+        assert f"```text\n{prompt}\n```" in entry_text
+
     skill_symlinks = sorted(
         path.relative_to(SKILL_ROOT).as_posix()
         for path in SKILL_ROOT.rglob("*")
@@ -1457,6 +1503,15 @@ def test_scenario_5_repository_distribution_contract() -> None:
     skill_text = (SKILL_ROOT / "SKILL.md").read_text(encoding="utf-8")
     assert canonical_anchor not in skill_text
 
+    openai_text = (SKILL_ROOT / "agents/openai.yaml").read_text(
+        encoding="utf-8"
+    )
+    assert openai_text.count("allow_implicit_invocation: false") == 1
+    assert "allow_implicit_invocation: true" not in openai_text
+    assert "当前 Git 根" in openai_text
+    assert "按当前请求语言选择 zh 或 en" in openai_text
+    assert "只有用户明确要求时才创建 draft PR" in openai_text
+
     # 机械兜底只覆盖本次真实误植过的八份下游模板与五个精确 token。
     internal_context_tokens = (
         "disposable clone",
@@ -1538,3 +1593,13 @@ def test_scenario_5_repository_distribution_contract() -> None:
         "finish-submit",
     ):
         assert removed_command not in help_result.stdout
+
+    # 默认推断留在 Agent 合同；公开机械 CLI 继续要求显式目标和语言。
+    prepare_help = run_command(
+        args=[sys.executable, str(SYNC_SCRIPT), "prepare", "--help"],
+        cwd=REPO_ROOT,
+        environment=None,
+    )
+    assert prepare_help.returncode == 0
+    for option in ("--target-repo", "--upstream-dir", "--language {zh,en}"):
+        assert option in prepare_help.stdout

zh/README.md

@@ -5,37 +5,88 @@
 本目录提供真正跨语言、跨框架、跨项目的中文核心模板、开发工作流和 canonical
 `workflow-docs-sync` Skill。
 
-## Quick Start
+## 一句话开始
 
-用户只调用一次 Skill，只提供目标 Git 仓库、`zh` 或 `en`，以及成功后是否创建 draft PR：
+在目标项目的 Codex 中复制这一句：
 
 ```text
-使用 $workflow-docs-sync 同步 /目标仓库绝对路径，语言 zh，结束后不要创建 draft PR。
+用 $skill-installer 安装 https://github.com/wlvh/coding-workflow/tree/main/zh/skills/workflow-docs-sync，然后立即用 $workflow-docs-sync 同步当前项目文档并创建 draft PR；如果当前会话尚未注册新 Skill，直接读取安装器返回目录中的 SKILL.md 继续执行，不要停下来要求重启。
 ```
 
+上述指令用于首次安装；已经安装后，在其他项目中直接要求 `$workflow-docs-sync` 同步当前项目文档并创建 draft PR。
+
+用户不需要提供目标绝对路径、`zh` / `en`、分支名、上游 SHA 或安装路径，也不需要预先清理
+目标工作树。系统 `$skill-installer` 成功时输出
+`Installed workflow-docs-sync to <installed-skill-root>`；当前会话尚未注册 Skill 时，以该次成功
+输出中的真实目录为准，完整读取其中的 `SKILL.md`，从同一目录解析脚本并在本轮继续。不要猜测
+固定安装目录，也不要等待下一轮。
+
+## 默认行为
+
+- 目标仓库：默认使用 Codex 当前工作目录所属的 Git 根；只有当前目录不在 Git 仓库中时才询问。
+- 语言：显式 `zh` / `en` 优先；否则中文请求使用 `zh`，其他语言请求使用 `en`。
+- PR：明确说不创建 PR 时不创建；提到 PR、提 PR、创建/提交 PR 或 open/create pull request 时
+  创建 draft PR；未提及则不创建。永不自动标记 Ready 或合并。
+- 工作树：请求 PR 时，无论原工作树是否 clean，都从调用时 committed HEAD 在仓库外创建 clean
+  worktree 和唯一新分支。Skill 不改动原工作树中的普通、staged、untracked 或 ignored 内容，也不
+  stash、clean、commit 或覆盖用户修改；最终报告前会重新比较 NUL 分隔的 status 与 staged
+  entries，并只对调用前 status/ignored 枚举出的非 clean 路径复核类型、mode、普通文件 SHA-256
+  或 symlink target，不扫描整棵仓库，也不比较原始 Git index 文件。调用期间新增的 ignored 路径
+  不在原集合内；其他差异只证明发生了并发变化，不归因于 Agent。
+
+最终报告会明确写：
+
+```text
+本次同步与 PR 基于调用时的 committed HEAD；原工作树中的未提交修改未进入调查或 PR。
+```
+
+仓库没有 commit 时会报告 `BLOCKER`。同步已经通过、但 remote、认证、push 权限或 PR 创建
+失败时，保留外部 worktree、分支、commit 和仓库外 PR body，并报告
+`Documentation sync: PASS`、`Publication: PR_BLOCKED`、`Overall: PARTIAL`，不会谎称 PR 已创建。
+
+## 仓库自带安装器（可选）
+
+以下是维护者或需要同时安装 Codex / Claude 副本时的可选路径，不是上述一句话入口。先克隆
+canonical 仓库并确认这个上游 checkout clean；这里的 clean 要求不适用于待同步的目标项目：
+
+```bash
+git clone --depth 1 https://github.com/wlvh/coding-workflow.git
+cd coding-workflow
+
+git status --porcelain=v1 --untracked-files=all
+python3 zh/scripts/install_skills.py --upstream-dir "$PWD"
+```
+
+`git status` 应无输出；如果有输出，停止安装并先检查 canonical checkout。成功 JSON 同时列出
+`~/.agents/skills/workflow-docs-sync/` 与 `~/.claude/skills/workflow-docs-sync/` 两项 action。
+
+需要把 Skill 作为目标项目的一部分审查和共享时，在 canonical checkout 根目录运行：
+
+```bash
+python3 zh/scripts/install_skills.py \
+  --scope repo \
+  --target-repo "/目标仓库绝对路径" \
+  --upstream-dir "$PWD"
+```
+
+repo scope 的目标路径必须恰好是 clean Git 根目录；审查生成的 Git diff 后，再按目标项目政策
+提交。两种 scope 都会覆盖已有同名 Skill，并精确移除废弃的 `workflow-docs-sync-review`，不会
+保存来源状态或自动更新。Studio 也可直接加载 canonical `zh/skills/workflow-docs-sync/`。
+
+## 同步边界
+
 Skill 固定目标 HEAD 与上游 SHA，从当前代码、配置、测试、committed artifacts、可重复运行
 结果和必要 Git 历史全量重建事实，再只做事实要求的最小文档改写。现有文档与上游模板都是
 hypotheses，不是证据。
 
 Architecture、Capability / User Behavior、Testing、Governance 是覆盖维度，不是固定 Agent
-拓扑。主 Agent 是目标工作区唯一写入者；测试环境由项目命令、副作用、CI 和项目政策决定。
+拓扑。主 Agent 是执行 worktree 的唯一写入者；测试环境由项目命令、副作用、CI 和项目政策
+决定。
 
 复核优先使用 fresh-context、blind-first independent reviewer。平台不能提供认知隔离时，
 最终结果诚实标记 self-review。确定性 checker 只验证最终仓库状态，不证明调查、测试或复核
 历史。
 
-## Skill 安装
-
-Studio 可直接加载 canonical `zh/skills/workflow-docs-sync/`。个人或团队安装只复制这一个
-Skill，不保存来源状态；安装器会在任何目标 mutation 前拒绝 symlink、缺少标准分隔的
-frontmatter 和会被复制的 ignored source residue：
-
-```bash
-python3 zh/scripts/install_skills.py --upstream-dir <clean-canonical-checkout>
-python3 zh/scripts/install_skills.py --scope repo \
-  --target-repo <目标仓库> --upstream-dir <clean-canonical-checkout>
-```
-
 ## Template Contract
 
 Markdown project-fill slot 使用 `<!-- project-fill: ... -->`，JSON 使用