cowork-flow 2.3.0 → 2.4.0

package/docs/hosts.en.md

@@ -0,0 +1,299 @@
+# Host integration
+
+[中文](hosts.md) | English
+
+This document explains how to connect cowork-flow to an AI coding host, and how to check, upgrade, and uninstall it after installation. If you only need the first-time install, start with "Finish host setup" in the [README](../README.en.md).
+
+## Two kinds of files to tell apart first
+
+| Kind | Written to | Installed by |
+|---|---|---|
+| Project-level files | the current project's `AGENTS.md`, `.cowork-flow/`, and host directories | `cwf project init` / `cwf project sync` |
+| Machine-level components | the host's user configuration directory, such as plugins, presets, or hooks | `cwf host add` / `cwf host remove` |
+
+Every project needs at least one `cwf project init`. When `--host` is omitted, init first detects host markers already in the project (such as `.codex/` or `.claude/`), using the same detection as `cwf project sync`; an interactive terminal offers a picker when none is found, while a non-interactive environment must pass `--host` explicitly. `--platform` / `--platforms` remain accepted aliases. Task and plan artifacts default to Chinese; pass `--language en-US` when a non-interactive install needs English artifacts, or edit `language` in `.cowork-flow/config.yaml` and run `cwf project sync` to switch after installation.
+
+Whether `cwf host add` is needed depends on the host:
+
+| Host | Machine-level component needed after init | Suggested command |
+|---|---|---|
+| Codex | Works in the current project as-is; the global bootstrap entry point is optional | `cwf host add codex` |
+| Claude Code | Works in the current project as-is; the global bootstrap entry point is optional | `cwf host add claude-code` |
+| OpenCode | Works in the current project as-is; the global bootstrap entry point is optional | `cwf host add opencode` |
+| ZCode | Required | `cwf host add zcode` |
+| Qoder | Required | `cwf host add qoder` |
+| DeepSeek Harness | Required | `cwf host add dsh` |
+| Kimi Code | Required | `cwf host add kimi-code` (one command installs both the hook and the plugin) |
+
+## Common commands
+
+Preview first, then install:
+
+```bash
+cwf host add <host> --dry-run
+cwf host add <host>
+```
+
+List the hosts the project and the CLI know about:
+
+```bash
+cwf host list .
+cwf host list . --json
+```
+
+Upgrade or reinstall:
+
+```bash
+cwf host add <host> --force
+```
+
+Uninstall the machine-level component:
+
+```bash
+cwf host remove <host>
+```
+
+Use `--force` only once you have confirmed that an existing installation needs to be overwritten. The installer refuses by default to overwrite or delete files it does not own; `--dry-run` runs the same ownership checks.
+
+Machine-level hooks and the project runtime upgrade independently, yet a machine-level hook fires in any workspace — including projects whose runtime is older than the hook. The four machine-level injection shims (Qoder, ZCode, Kimi Code, OpenCode) are therefore **fail-open**: when the project runtime fails, they only record the reason in the host's run log and return 0; they do not inject, and they never turn "hook failed" into "your input is rejected". The project-level Edit-time hooks (Claude Code / Codex) have likewise stopped returning a non-zero exit since 2.0.0 and are always advisory. In an old project, injection silently has no effect; run `cwf project sync .` once to restore it.
+
+## Codex
+
+```bash
+cwf host add codex --dry-run
+cwf host add codex
+cwf host remove codex
+```
+
+The installer will:
+
+- Prepare a stable plugin source under `$CODEX_HOME/plugins/marketplaces/cowork-flow-local/`; when `CODEX_HOME` is unset, it uses `~/.codex`.
+- Register the marketplace and the plugin through Codex's official CLI; it does not hand-write `config.toml`.
+- When the `codex` command is not found, still prepare the source directory and print the manual commands.
+
+The plugin only carries the `cowork-flow-bootstrap` bootstrap Skill; project hooks and the three fixed subagents are still provided by project-level files. Start a new session after installing or upgrading.
+
+To upgrade to a new version, run:
+
+```bash
+cwf host add codex --force
+```
+
+## Claude Code
+
+```bash
+cwf host add claude-code --dry-run
+cwf host add claude-code
+cwf host remove claude-code
+```
+
+The plugin is written to `$CLAUDE_CONFIG_DIR/skills/cowork-flow`, or `~/.claude/skills/cowork-flow` when that variable is unset. Claude Code treats a Skill directory containing `.claude-plugin/plugin.json` as a plugin, so no extra marketplace command is needed.
+
+The plugin only provides the bootstrap Skill. Project hooks and agents already live in `.claude/`, which avoids duplicate execution from multiple hook sources. Start a new session after installing.
+
+`~/.claude/skills/` is user-maintained: when the target directory is not the cowork-flow plugin, both install and uninstall refuse; use `--force` only after deciding to take over that directory.
+
+## OpenCode
+
+```bash
+cwf host add opencode --dry-run
+cwf host add opencode
+cwf host remove opencode
+```
+
+The install location is `$XDG_CONFIG_HOME/opencode/`, or `~/.config/opencode` when that variable is unset. The installer only writes `plugins/cowork-flow.js` and `cowork-flow/`; it does not modify the user's `opencode.json`.
+
+The plugin registers the `cowork-flow-bootstrap` Skill directory shipped in its payload from the `config` hook, so a repository that has not initialized cowork-flow also sees the bootstrap entry point. Start a new session after installing.
+
+The plugin itself is only a transport shim: the injected text is rendered by the in-project Python runtime `inject.py --host opencode` (zcode has the same shape). The payload also carries a cached copy of `cowork-flow/runtime/scripts` to render the not-initialized context outside a project; inside a project, the project's own runtime copy always wins.
+
+OpenCode may generate `package.json`, `bun.lock`, and `node_modules/` inside the plugin directory. These are host files; the installer neither modifies nor cleans them. The load order of multiple plugins, and the precedence between a global and a project Skill of the same name, have not been measured yet.
+
+## ZCode
+
+```bash
+cwf host add zcode --dry-run
+cwf host add zcode
+cwf host add zcode --force --prune-old
+cwf host remove zcode
+```
+
+The installer maintains a stable marketplace source and the currently active copy; the plugin cache lives under `~/.zcode/cli/plugins/cache/`. The plugin provides hooks, the three fixed subagents, and the bootstrap Skill; project Skills are still provided by `.agents/skills/`.
+
+Old version caches are kept by default, so a running session does not suddenly lose the plugin. Use `--prune-old` when you need to clean up old versions. Restart ZCode or start a new session after upgrading.
+
+## Qoder
+
+```bash
+cwf host add qoder --dry-run
+cwf host add qoder
+cwf host add qoder --force
+cwf host remove qoder
+```
+
+The install location is determined by `QODER_CONFIG_DIR`, or `~/.qoder` when that variable is unset. The plugin provides hooks, the three fixed subagents, and the bootstrap Skill; the project-level `init` / `sync` commands only write the adaptation declarations and shared Skills.
+
+## DeepSeek Harness
+
+Installs the Cowork Flow preset by default:
+
+```bash
+cwf host add dsh --component preset --dry-run
+cwf host add dsh
+cwf host remove dsh --component preset
+```
+
+The preset writes both delivery lines at once, because the desktop version switched channels:
+
+| Location | Applies to | How to enable |
+| --- | --- | --- |
+| `~/.dsh/.agent-presets/cowork-flow/` (or the corresponding directory under `$DSH_HOME`) | DSH 0.1.x / CLI line | Appears directly in the session's preset list; restart and select **Cowork Flow** |
+| `~/.dsh/bundles/cowork-flow/` | DSH 0.2.0+ (desktop) | On the desktop sidebar's Plugins page, enter the absolute path of that directory to install it (the `plugin_manager` tool row is disabled in the desktop host composition and is unavailable in a session), then start a new session |
+
+As of 0.2.0 the host no longer reads the `.agent-presets/` directory (its bundled Skill text reads: "Nothing reads that directory any more"), and the preset becomes one declaration line for `@deepseek-ai/dsh-agent-preset` in a bundle patch. The host performs the bundle installation — it runs the package install and writes the profile manifest — so `cwf` only produces the bundle and the installation instructions, and does not rewrite `~/.dsh/profiles/**`. The two lines differ only in the two places where the host API differs: the workflow line (0.1.x `dsh-workflow-worker-thread` / 0.2.0 `dsh-workflow-ptc`) and the persona line's configuration key (0.1.x `text` / 0.2.0 `prefix`), substituted when the bundle is generated; both must match the target line, because a package that cannot be resolved or a configuration key the host rejects makes the host treat the **entire** preset as unavailable. An install without `--force` only adds the missing line and does not overwrite an existing directory.
+
+The preset already includes the workflow-state hook, so the hook component does not need to be installed as well. Use it only when debugging the composition layer's configuration:
+
+```bash
+cwf host add dsh --component hook
+cwf host remove dsh --component hook
+```
+
+Whether the hook line enters the agent prompt depends on the version line: in testing, DSH 0.1.1-rc.1 did not collect host-layer sections, so live injection could only come from the preset; 0.2.0-rc.1 (desktop) composes the global-layer sections into every agent prompt (`dsh-scope`'s `layers.merge()` takes the global layer first, and the scope chain then overrides it), so on that version the hook component alone can provide injection. The above is code- and documentation-level evidence; real-session verification still requires one run on the corresponding version.
+
+## Kimi Code
+
+The bare command installs both parts in one go: first the context-injection hook (required), then the plugin:
+
+```bash
+cwf host add kimi-code
+cwf host remove kimi-code
+```
+
+Reload the configuration or start a new session after installing or updating. The hook component always rewrites its own hook block and does not write the plugin; the plugin component provides the global bootstrap Skill in uninitialized projects. To install just one half, use `--component`:
+
+```bash
+cwf host add kimi-code --component plugin
+cwf host add kimi-code --component hook
+```
+
+The hook component does not accept `--force` (it always takes over and rewrites its own block); `--force` on the bare command applies only to the plugin part:
+
+```bash
+cwf host add kimi-code --force
+```
+
+The plugin is materialized to `$KIMI_CODE_HOME/plugins/sources/cowork-flow/` (the stable reinstall source) and `$KIMI_CODE_HOME/plugins/managed/cowork-flow/` (the copy the host loads), and writes directly into the host's plugin registry `$KIMI_CODE_HOME/plugins/installed.json`, matching Kimi Code's own on-disk installation format. Restarting Kimi Code is enough to take effect; no manual install in the TUI is needed. Uninstall cleans up both directories and the registry entry in reverse.
+
+## MCP client integration
+
+When an MCP client needs to read task facts, registering once globally is recommended:
+
+```bash
+cwf mcp serve
+```
+
+The client searches upward from the current working directory for `.cowork-flow/`, so one registration can serve multiple projects. Common configuration examples:
+
+```toml
+# Codex: ~/.codex/config.toml
+[mcp_servers.cowork-flow]
+command = "cwf"
+args = ["mcp", "serve"]
+```
+
+```json
+// OpenCode: ~/.config/opencode/opencode.json
+{
+  "mcp": {
+    "cowork-flow": {
+      "type": "local",
+      "command": ["cwf", "mcp", "serve"],
+      "enabled": true
+    }
+  }
+}
+```
+
+For Claude Code, run:
+
+```bash
+claude mcp add -s user cowork-flow -- cwf mcp serve
+```
+
+Without a global CLI install, you can also configure the in-project entry point directly:
+
+```bash
+<project>/.cowork-flow/run mcp-state
+```
+
+## Skill discovery
+
+The single source for project Skills is `template/skills/`; `init` / `sync` distributes them as shown in the table below. Host plugins no longer carry copies of project Skills.
+
+| Host | Project Skill read root | Host discovery |
+|---|---|---|
+| Codex | `.agents/skills/` | Natively scans `.agents/skills/` |
+| Claude Code | `.claude/skills/` | Natively scans the project's `.claude/skills/` |
+| OpenCode | `.agents/skills/` | Scans `.agents/skills/` and `.opencode/skills/`; cowork-flow only delivers the former |
+| ZCode | `.agents/skills/` | Scans the project's `.zcode/skills/` and `.agents/skills/`; the former wins on a name collision |
+| Qoder | `.agents/skills/` | `loadFromAgentsDirectory` is enabled by default |
+| Kimi Code | `.agents/skills/` | `PROJECT_GENERIC_DIRS` includes `.agents/skills` |
+| DeepSeek Harness | `.agents/skills/` | `skill-filesystem` uses it as the project Skill root |
+
+These channels are recorded as `verified:` in the Host Asset Manifest. After a host upgrade, if you observe behavior changes, update the evidence and tests rather than only the documentation.
+
+## Diagnostics
+
+Start with:
+
+```bash
+./.cowork-flow/run doctor --all
+./.cowork-flow/run doctor --all --json
+```
+
+<details>
+<summary>Common diagnostic codes</summary>
+
+| Scope | Diagnostic code | Meaning |
+|---|---|---|
+| General Skills | `SKILL-READROOT-MISSING` | The project is missing a declared Skill read root |
+| General Skills | `PLUGIN-SKILLS-LEGACY` | An old plugin still carries copies of project Skills; reinstall the plugin |
+| General Skills | `SKILL-DISCOVERY-GATED` | The host needs the directory trusted or a restart before it loads Skills |
+| Codex | `PLUGIN-NOT-INSTALLED` / `PLUGIN-PAYLOAD-MISSING` / `PLUGIN-DISABLED` | The plugin is not registered, its payload is missing, or it is not enabled |
+| Claude Code / OpenCode | `PLUGIN-NOT-INSTALLED` / `PLUGIN-PAYLOAD-INCOMPLETE` / `PLUGIN-STALE` | The plugin is not installed, its payload is incomplete, or its version is behind |
+| Qoder | `PLUGIN-NOT-INSTALLED` / `PLUGIN-PAYLOAD-MISSING` / `PLUGIN-PAYLOAD-INCOMPLETE` / `PLUGIN-DISABLED` / `PLUGIN-STALE` | Something is wrong with the plugin's installation, enablement, payload, or version |
+| DSH preset | `PRESET-UNKNOWN-VERSION` / `PRESET-STALE` | The preset lacks a version marker or its version is behind |
+| DSH / Kimi hook | `HOOK-NOT-INSTALLED` / `HOOK-SHIM-MISSING` / `HOOK-UNKNOWN-VERSION` / `HOOK-STALE` | The hook block, script, version marker, or version does not match |
+| Kimi plugin | `PLUGIN-NOT-INSTALLED` / `PLUGIN-DISABLED` / `PLUGIN-PAYLOAD-INCOMPLETE` / `PLUGIN-STALE` / `PLUGIN-SOURCES-MISSING` | The plugin is not registered, is disabled, has an incomplete payload, is behind, or its source directory is missing |
+
+`PLUGIN-NOT-INSTALLED` means the registry has no cowork-flow record yet; `cwf host add kimi-code` both installs and registers it in one step.
+
+</details>
+
+## Plugin icon fields
+
+Hosts support different manifest fields, so do not copy the same set of fields into every manifest.
+
+| Host | Supported fields | Requirement |
+|---|---|---|
+| Codex | `interface.logo`, `interface.brandColor` | The logo must be a relative path inside the payload |
+| ZCode | the marketplace entry's `icon` | Must be an `https://` URL |
+| Claude Code, OpenCode, Qoder, DSH, Kimi Code | None | Do not write icon keys |
+
+`assets/icon.svg` is the single source for the brand icon, and `presets/plugin-meta.json` stores the brand color. Run `npm run icons:export` at release time to re-export the raster assets.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `COWORK_FLOW_HOOKS=0` / `COWORK_FLOW_DISABLE_HOOKS=1` | Disable hook injection for all hosts |
+| `COWORK_FLOW_CONTEXT_ID` | Explicitly set the session identity; use when the host provides no session variable |
+| `COWORK_FLOW_HOST` | Explicitly set the host id |
+| `COWORK_FLOW_CODEX` | Set the Codex CLI executable |
+| `DSH_HOME` | Override the DeepSeek Harness configuration root |
+| `KIMI_CODE_HOME` | Override the Kimi Code configuration root |
+| `CODEX_HOME` | Override the Codex configuration root |
+| `QODER_CONFIG_DIR` | Override the Qoder configuration root |
+| `CLAUDE_CONFIG_DIR` | Override the Claude Code configuration root |
+| `COWORK_FLOW_BROWSER` | Browser executable used by `icons:export` |

package/docs/hosts.md

@@ -1,5 +1,7 @@
 # 宿主接入
 
+[English](hosts.en.md) | 中文
+
 本文说明如何把 cowork-flow 接到 AI 编码宿主，以及安装后如何检查、升级和卸载。只想完成首次安装时，先看 [README](../README.md) 的“完成宿主设置”。
 
 ## 先分清两类文件
@@ -9,7 +11,7 @@
 | 项目级文件 | 当前项目的 `AGENTS.md`、`.cowork-flow/` 和宿主目录 | `cwf project init` / `cwf project sync` |
 | 机器级组件 | 宿主的用户配置目录，如插件、预设或 hook | `cwf host add` / `cwf host remove` |
 
-每个项目至少需要执行一次 `cwf project init`。省略 `--host` 时，init 先按项目里已有的宿主标记（如 `.codex/`、`.claude/`）自动判定，与 `cwf project sync` 使用同一套探测；没有标记的交互终端会给出选择器，非交互环境则必须显式传 `--host`。`--platform` / `--platforms` 仍是兼容别名。
+每个项目至少需要执行一次 `cwf project init`。省略 `--host` 时，init 先按项目里已有的宿主标记（如 `.codex/`、`.claude/`）自动判定，与 `cwf project sync` 使用同一套探测；没有标记的交互终端会给出选择器，非交互环境则必须显式传 `--host`。`--platform` / `--platforms` 仍是兼容别名。任务与计划产物默认中文；非交互安装需要英文产物时传 `--language en-US`，安装后也可编辑 `.cowork-flow/config.yaml` 的 `language` 并运行 `cwf project sync` 切换。
 
 是否需要 `cwf host add`，取决于宿主：
 

package/docs/index.en.md

@@ -0,0 +1,30 @@
+# cowork-flow documentation
+
+[中文](index.md) | English
+
+If this is your first time installing and using cowork-flow, read [README](../README.en.md) first. When you need to understand host integration, how it works, or the development workflow, pick a document from the entries below.
+
+## Find by question
+
+| What you want to do | Which document to read | What you will find |
+|---|---|---|
+| Install, initialize a project, or start a task | [README](../README.en.md) | The shortest path to get started, day-to-day commands, and common questions |
+| Connect cowork-flow to an AI coding host | [Host integration](hosts.en.md) | Installation components, restart requirements, upgrades, uninstallation, and troubleshooting for each host |
+| Understand how project files are organized | [Architecture and extension](architecture.en.md) | The runtime, `template/`, `presets/`, sync policy, and extension boundaries |
+| Contribute to project development | [Contributing](../CONTRIBUTING.md) (Chinese) | Local setup, code conventions, tests, and PR checks |
+| Understand the test and release process | [Release and maintenance](release.en.md) | Test layers, CI, version releases, and maintainer commands |
+| Understand project direction and version planning | [Direction](direction.en.md) | The positioning statement, settled trade-offs, the version mainline, and open items |
+| See what changed in a given version | [Changelog](../CHANGELOG.md) (Chinese) | Feature changes, fixes, and migration notes recorded by version |
+
+## Common reading paths
+
+- **First-time use**: README → Host integration → Start a task.
+- **Submitting code**: README → Contributing → Architecture and extension.
+- **Troubleshooting installation or runtime issues**: Host integration → the "Troubleshooting" section of README.
+- **Preparing a release**: Architecture and extension → Release and maintenance → Changelog.
+
+## Documentation and actual behavior
+
+Documentation explains usage; for exact commands and current task state, rely on what the command actually outputs. For the command that shows the current state, see the "Troubleshooting" section of [README](../README.en.md).
+
+If command output disagrees with the documentation, trust the current command output and open an [issue](https://github.com/fishlikewater/cowork-flow/issues) to point out where the documentation needs fixing.

package/docs/index.md

@@ -1,5 +1,7 @@
 # cowork-flow 文档
 
+[English](index.en.md) | 中文
+
 第一次安装和使用请先看 [README](../README.md)。需要了解宿主接入、工作原理或开发流程时，再从下面的入口选择文档。
 
 ## 按问题查找

package/docs/release.en.md

@@ -0,0 +1,108 @@
+# Release and maintenance
+
+[中文](release.md) | English
+
+This document is for maintainers of the cowork-flow repository. Regular users only need the [README](../README.en.md); before submitting code, read [Contributing](../CONTRIBUTING.md) (Chinese) first.
+
+## Pre-release checks
+
+Choose tests according to the scope of the change; you do not have to start from the heaviest command every time.
+
+| Command | When to run |
+|---|---|
+| `npm run test:fast` | The minimum check after everyday changes |
+| `npm run test:smoke` | Verifies that the CLI loads and runs a minimal initialization after installation from a real npm tarball |
+| `npm run test:integration` | Changes to `project init` / `project sync` |
+| `npm run test:node:full` | Changes to the Node CLI, installers, or shared modules |
+| `npm run test:template` | Changes to core paths of the project template |
+| `npm run test:template:full` | Changes to the Python runtime, specs, hooks, or host adaptations |
+| `npm run test:windows:core` | Anything involving Windows, paths, line endings, or release behavior |
+| `python -m pytest -q` | Changes to `template/.cowork-flow/`, `tests/`, or Python contracts |
+| `npm run test:all` | The full Node, template, and packaging check when preparing a release |
+| `npm run release:check` | The release confidence gate: `test:all` plus checks that tests cannot express — drift of the self-instance and live-copy assets (`.claude/**`, `.codex/**`, skills) from `template/`, and `error`-level problems from `doctor --all` |
+
+When platform prerequisites are not met, tests may skip explicitly. Skips must be recorded as they are and never treated as passes.
+
+For stability-related changes, run the template tests repeatedly:
+
+```bash
+COWORK_TEMPLATE_TEST_REPEAT=3 \
+COWORK_TEMPLATE_TEST_SEED=<fixed-value> \
+npm run test:template:full
+```
+
+## Release commands
+
+| Command | Behavior |
+|---|---|
+| `npm run release` | Release a patch version |
+| `npm run release -- minor` | Release a minor version |
+| `npm run release -- --version 0.1.0` | Use the given version number and skip the automatic bump |
+| `npm run release -- minor --no-publish` | Finish the version, commit, and tag, push the commit and tag, but do not run `npm publish`; CI publishes |
+| `npm run release -- --dry-run` | Run the pre-release checks and stop before the version bump |
+
+`npm run release` runs `test:all` internally, not `release:check`: before running the tests it executes `source:refresh` and `sync --force`, so drift is already erased and only the `doctor` half is missing. Before releasing, run `release:check` separately as the standard flow requires.
+
+`--dry-run` is not a read-only command. It first requires a clean Git worktree and index, then runs `source:refresh` and `sync --force`, so it may refresh ignored runtime copies in the repository and temporarily overwrite and then restore `AGENTS.md`. It does not change version files, commit, tag, or publish; if local changes exist when the check starts, the script stops before any refresh.
+
+The target version is only known after the bump, so `--dry-run` does not run the CHANGELOG version-section gate.
+
+## Standard release flow
+
+1. Confirm that the worktree and the changelog are as expected.
+2. Run `npm run release:check` and `git diff --check`.
+3. For stability changes, repeat the template tests as described in the previous section.
+4. Run `npm run release -- <release-type>`; the CI route uses `--no-publish`, which pushes the tag to CI.
+5. The script syncs `package.json`, the lockfile, `template/.cowork-flow/.version`, and every plugin manifest bundled with the package.
+6. Check the commit and tag, then publish through the CI route below.
+
+`scripts/release.sh` checks after the bump whether `CHANGELOG.md` has a section for the current version. This check happens after the version has already changed; if it fails, restore `package.json`, `package-lock.json`, and `.version` with the rollback commands printed by the script, then run `npm run source:refresh`.
+
+## CI publishing route
+
+We recommend letting GitHub Actions run `npm publish`:
+
+1. Run `npm run release -- <release-type> --no-publish` locally. The script completes the checks, the version, the commit, and the tag, then pushes the branch and tag:
+
+   ```bash
+   git push
+   git push origin v<v>
+   ```
+
+2. Pushing the tag triggers `.github/workflows/publish.yml`. After the Ubuntu and Windows verification jobs pass, the workflow publishes only from the existing `v<version>` tag and verifies that the tag, `package.json`, and `template/.cowork-flow/.version` agree on the version.
+
+3. If you want release notes for this tag, create them manually (not required for publishing):
+
+   ```bash
+   gh release create v<v>
+   ```
+
+Do not run `gh release create` while the tag does not exist on the remote, or GitHub may create the tag from the latest commit on the default branch and point the release at the wrong commit.
+
+Repeated triggers on the same tag are serialized by the concurrency lock, so they never race; if that version is already published to npm, a repeated run is rejected by npm at the `npm publish` stage, which is expected. To publish again after a failed CI run, rerun with `workflow_dispatch` on the same tag.
+
+Pull requests and releases use the same core gates.
+
+Release credentials use **Trusted Publishing**: the publish job declares `id-token: write`, hands a GitHub OIDC token to npm in exchange for short-lived credentials, and no long-lived token is stored in the repository. Register it on the npm package page (Settings → Trusted Publishers), declaring the repository `fishlikewater/cowork-flow` and the workflow file `publish.yml`.
+
+That exchange is implemented by the npm CLI (since 11.5.1), while Node 20 bundles npm 10, so **only the publish job runs on Node 24**; the two verification jobs still use Node 20, matching the `engines` declared in `package.json`.
+
+The publish job's `setup-node` **keeps `registry-url`** but supplies no `NODE_AUTH_TOKEN`. npm starts the OIDC exchange only after reading a registry from `.npmrc` — remove it and publishing fails with `ENEEDAUTH` without ever contacting the token endpoint. The `${NODE_AUTH_TOKEN}` placeholder written by `setup-node` is **deliberately left unresolved**: npm first tries the exchange with that empty credential and falls back to it only when the exchange is rejected.
+
+Earlier versions used the `NPM_TOKEN` secret. With two-factor authentication enabled on the account, a classic token cannot complete an interactive OTP, so CI publishing failed with `EOTP` — which is also why we switched to Trusted Publishing. The verification jobs (Ubuntu / Windows) touch no release credentials and only run `release:check`.
+
+## Maintainer commands
+
+```bash
+npm run source:refresh:dry-run  # Preview refreshing the source repository's runtime copies
+npm run source:refresh          # Refresh the root .cowork-flow, .agents/skills, .claude/skills
+npm run icons:export            # Re-export PNGs from assets/icon.svg
+```
+
+`source:refresh` treats `template/.cowork-flow/` and `template/skills/` as the only distribution source and does not overwrite tasks, plans, developer identity, project configuration, or custom Skills. After refreshing, run:
+
+```bash
+./.cowork-flow/run doctor --all --json
+```
+
+`icons:export` requires Edge or Chrome on the machine; `COWORK_FLOW_BROWSER` can point at an executable. When the browser is missing, the command fails rather than treating the old images as updated.

package/docs/release.md

@@ -1,5 +1,7 @@
 # 发布与维护
 
+[English](release.en.md) | 中文
+
 本文面向 cowork-flow 仓库维护者。普通用户只需要 [README](../README.md)；提交代码前先看 [参与开发](../CONTRIBUTING.md)。
 
 ## 发布前检查

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "keywords": [
     "ai-agent",
@@ -49,7 +49,7 @@
   "scripts": {
     "test": "npm run test:fast",
     "test:smoke": "node --test --test-timeout=600000 test/smoke.test.js test/tarball-install.test.js",
-    "test:fast": "node --test --test-timeout=600000 test/asset-plan.test.js test/cli.test.js test/cli-registry.test.js test/claude-code-plugin.test.js test/codex-plugin.test.js test/compliance-e2e.test.js test/contract-fingerprint.test.js test/copy-template.obsolete-safety.test.js test/docs.test.js test/host-assets.test.js test/host-command.test.js test/kimi-hook.test.js test/kimi-installed-registry.test.js test/kimi-plugin.test.js test/opencode-plugin-installer.test.js test/opencode-plugin.test.js test/package.test.js test/plugin-metadata.test.js test/plugin-payload.test.js test/qoder-plugin.test.js test/smoke.test.js test/stage-contract.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
+    "test:fast": "node --test --test-timeout=600000 test/asset-plan.test.js test/cli.test.js test/cli-registry.test.js test/claude-code-plugin.test.js test/codex-plugin.test.js test/compliance-e2e.test.js test/contract-fingerprint.test.js test/copy-template.obsolete-safety.test.js test/docs.test.js test/host-assets.test.js test/host-command.test.js test/kimi-hook.test.js test/localization.test.js test/kimi-installed-registry.test.js test/kimi-plugin.test.js test/opencode-plugin-installer.test.js test/opencode-plugin.test.js test/package.test.js test/plugin-metadata.test.js test/plugin-payload.test.js test/qoder-plugin.test.js test/smoke.test.js test/stage-contract.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
     "test:integration": "node --test --test-timeout=600000 --test-name-pattern=\"^(init copies the template into a new target directory|sync updates safe template files and preserves protected files)$\" test/init.test.js test/sync.test.js",
     "test:node:full": "node --test --test-timeout=600000",
     "test:template": "node scripts/run-template-tests.js --suite core",

package/presets/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Claude Code。",
   "displayName": "Cowork Flow",
   "author": {

package/presets/claude-code/skills/cowork-flow-bootstrap/SKILL.md

@@ -25,6 +25,10 @@ Tell the user this repository has no cowork-flow runtime, then offer (replace
 npx cowork-flow project init --host <host>
 ```
 
+The default artifact language is `zh-CN`. When the user asks for English task or
+plan artifacts, append `--language en-US`. An existing
+`.cowork-flow/config.yaml` remains authoritative.
+
 After init the project carries its own Skills (`.agents/skills/`), the task
 runtime (`.cowork-flow/`), and the workflow entry `./.cowork-flow/run task next`.
 Resume the work through that entry.

package/presets/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Codex。",
   "author": {
     "name": "fishlikewater",

package/presets/codex/skills/cowork-flow-bootstrap/SKILL.md

@@ -25,6 +25,10 @@ Tell the user this repository has no cowork-flow runtime, then offer (replace
 npx cowork-flow project init --host <host>
 ```
 
+The default artifact language is `zh-CN`. When the user asks for English task or
+plan artifacts, append `--language en-US`. An existing
+`.cowork-flow/config.yaml` remains authoritative.
+
 After init the project carries its own Skills (`.agents/skills/`), the task
 runtime (`.cowork-flow/`), and the workflow entry `./.cowork-flow/run task next`.
 Resume the work through that entry.

package/presets/kimi-code/.kimi-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Kimi Code。",
   "author": {
     "name": "fishlikewater",

package/presets/kimi-code/skills/cowork-flow-bootstrap/SKILL.md

@@ -25,6 +25,10 @@ Tell the user this repository has no cowork-flow runtime, then offer (replace
 npx cowork-flow project init --host <host>
 ```
 
+The default artifact language is `zh-CN`. When the user asks for English task or
+plan artifacts, append `--language en-US`. An existing
+`.cowork-flow/config.yaml` remains authoritative.
+
 After init the project carries its own Skills (`.agents/skills/`), the task
 runtime (`.cowork-flow/`), and the workflow entry `./.cowork-flow/run task next`.
 Resume the work through that entry.

package/presets/opencode/cowork-flow/skills/cowork-flow-bootstrap/SKILL.md

@@ -25,6 +25,10 @@ Tell the user this repository has no cowork-flow runtime, then offer (replace
 npx cowork-flow project init --host <host>
 ```
 
+The default artifact language is `zh-CN`. When the user asks for English task or
+plan artifacts, append `--language en-US`. An existing
+`.cowork-flow/config.yaml` remains authoritative.
+
 After init the project carries its own Skills (`.agents/skills/`), the task
 runtime (`.cowork-flow/`), and the workflow entry `./.cowork-flow/run task next`.
 Resume the work through that entry.

package/presets/qoder/.qoder-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Qoder。",
   "displayName": "Cowork Flow",
   "author": {

package/presets/qoder/skills/cowork-flow-bootstrap/SKILL.md

@@ -25,6 +25,10 @@ Tell the user this repository has no cowork-flow runtime, then offer (replace
 npx cowork-flow project init --host <host>
 ```
 
+The default artifact language is `zh-CN`. When the user asks for English task or
+plan artifacts, append `--language en-US`. An existing
+`.cowork-flow/config.yaml` remains authoritative.
+
 After init the project carries its own Skills (`.agents/skills/`), the task
 runtime (`.cowork-flow/`), and the workflow entry `./.cowork-flow/run task next`.
 Resume the work through that entry.

package/presets/zcode/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fishlikewater",

package/presets/zcode/skills/cowork-flow-bootstrap/SKILL.md

@@ -25,6 +25,10 @@ Tell the user this repository has no cowork-flow runtime, then offer (replace
 npx cowork-flow project init --host <host>
 ```
 
+The default artifact language is `zh-CN`. When the user asks for English task or
+plan artifacts, append `--language en-US`. An existing
+`.cowork-flow/config.yaml` remains authoritative.
+
 After init the project carries its own Skills (`.agents/skills/`), the task
 runtime (`.cowork-flow/`), and the workflow entry `./.cowork-flow/run task next`.
 Resume the work through that entry.