Merge branch 'main' into codex/models-json-unsupported-provider

Author: heimanba

README.md

@@ -149,7 +149,7 @@ Beta testers can install `@openagentpack/cli@beta`; see the [release guide](./do
 | MCP Server | native | native | native | native |
 | Memory Store | unsupported | native | unsupported | native |
 | Multi-Agent | unsupported | unsupported | native | native |
-| Deployment | emulated | emulated | native | emulated |
+| Deployment | emulated | native | native | emulated |
 | Session | native | native | native | native |
 
 The full capability matrix and per-provider differences live in the [Provider reference](./docs/reference/providers.md).

README.zh-CN.md

@@ -149,7 +149,7 @@ Beta 用户可以安装 `@openagentpack/cli@beta`；固定版本及切回稳定
 | MCP Server | native | native | native | native |
 | Memory Store | unsupported | native | unsupported | native |
 | Multi-Agent | unsupported | unsupported | native | native |
-| Deployment | emulated | emulated | native | emulated |
+| Deployment | emulated | native | native | emulated |
 | Session | native | native | native | native |
 
 完整能力矩阵与各 Provider 差异见 [Provider 参考](./docs/reference/providers.zh-CN.md)。

docs/architecture/how-it-works.md

@@ -63,4 +63,4 @@ agents state import <address> <remote-id>
 
 Resources (agents, environments, skills…) are **infrastructure** — long-lived, managed by `plan`/`apply`. A **session** is a **runtime** conversation started from an agent. Sessions are managed separately with `agents session` and are not part of the plan/apply lifecycle.
 
-Deployments sit between the two: they are declared as resources but produce runs. On Claude they schedule server-side; on Bailian, Qoder, and Volcengine Ark a `deployment run` expands into a session.
+Deployments sit between the two: they are declared as resources but produce runs. On Qoder and Claude they schedule server-side; on Bailian and Volcengine Ark a `deployment run` expands into a session.

docs/concepts/agents-as-code.md

@@ -19,7 +19,7 @@ Because the declaration is a file, it gets everything a file gets: code review,
 - The **agent harness** is the provider-managed layer that wraps a model into an agent: knowledge base, skills, MCP wiring, prompt/instructions, vault, deployment, multi-agent orchestration. These are the customer's portable assets.
 - The **agent infra** is the interchangeable execution substrate beneath the harness — the specific provider (Bailian, Qoder, Claude, Volcengine Ark) that runs the agent.
 
-OpenAgentPack's portability claim is that the same harness declaration can target different agent infra. Portability means the *core declaration* is portable and the per-provider **capability contract** is explicit — unsupported facets degrade gracefully (for example, an emulated `Deployment` on Bailian/Qoder/Volcengine Ark) — not that every feature is identical on every provider.
+OpenAgentPack's portability claim is that the same harness declaration can target different agent infra. Portability means the *core declaration* is portable and the per-provider **capability contract** is explicit — unsupported facets degrade gracefully (for example, an emulated `Deployment` on Bailian/Volcengine Ark) — not that every feature is identical on every provider.
 
 ## What this enables
 

docs/concepts/sessions-and-deployments.md

@@ -23,7 +23,8 @@ How a deployment *runs* depends on the provider's capability tier:
 | Provider | Deployment tier | What `agents deployment run` does |
 |----------|:--------------:|------------------------------------|
 | Claude | native | schedules server-side through the deployments API |
-| Qoder, Bailian, Ark | emulated | expands into a one-shot session at run time |
+| Qoder | native | creates a deployment run and associated session |
+| Bailian, Ark | emulated | expands into a one-shot session at run time |
 
 On the emulated providers, scheduling and outcome rubrics are **not** enforced server-side — use external cron/CI for always-on or scheduled runs.
 

docs/examples.md

@@ -52,7 +52,7 @@ agents destroy
 | MCP Server | native | native | native | native |
 | Memory Store | unsupported | native | unsupported | native |
 | Multi-Agent | unsupported | unsupported | native | native |
-| Deployment | emulated | emulated | native | emulated |
+| Deployment | emulated | native | native | emulated |
 | Session | native | native | native | native |
 
 See [Provider reference](./reference/providers.md) for per-provider configuration and notes.

docs/guides/configure-an-agent.zh-CN.md

@@ -460,7 +460,7 @@ Deployment 是介于「定义」与「运行」之间的声明式中间层。它
 - **部署层**（Deployment）：声明「用哪个 Agent、带哪些绑定、以什么初始事件和调度运行」。
 - **运行层**（Session）：一次具体的执行实例。
 
-> Provider 差异：Claude 原生支持 Deployment（对应平台的 deployments API，可服务端调度）；百炼、Qoder、火山方舟为**模拟**实现——`apply` 只写本地状态（`remote_id` 为 `null`），`agents deployment run` 时展开为一个 Session。详见 [Provider 参考](../reference/providers.zh-CN.md#模拟emulated资源的能力降级)。
+> Provider 差异：Qoder 和 Claude 原生支持 Deployment（对应平台的 deployments API，可服务端调度）；百炼、火山方舟为**模拟**实现——`apply` 只写本地状态（`remote_id` 为 `null`），`agents deployment run` 时展开为一个 Session。详见 [Provider 参考](../reference/providers.zh-CN.md#模拟emulated资源的能力降级)。
 
 ### 定义 Deployment
 
@@ -498,7 +498,7 @@ deployments:
 
 - `agent` 必填，引用顶层 `agents` 中定义的 Agent。
 - 未声明 `environment` / `vaults` / `memory_stores` 时，**继承所引用 Agent 的声明**；显式声明则覆盖。
-- `schedule.expression` 为 cron 表达式；`timezone` 为必填的 IANA 时区标识。仅 Claude 在服务端执行调度，百炼、Qoder、火山方舟需用外部 cron/CI 触发。
+- `schedule.expression` 为 cron 表达式；`timezone` 为必填的 IANA 时区标识。Qoder 和 Claude 在服务端执行调度，百炼、火山方舟需用外部 cron/CI 触发。
 - `initial_events` **必填**（1–50 条），在 Deployment 运行时按顺序投递给 Agent。
 
 ### 初始事件（initial_events）
@@ -507,17 +507,17 @@ deployments:
 |---------|------|------|
 | `user.message` | `content` | 以用户身份发送的消息 |
 | `system.message` | `content` | 系统提示（Qoder 上展平为 `user.message`） |
-| `user.define_outcome` | `description` / `rubric` / `rubric_file` / `max_iterations` | 定义结果评分目标（仅 Claude 服务端执行评分） |
+| `user.define_outcome` | `description` / `rubric` / `rubric_file` / `max_iterations` | 定义结果评分目标（Qoder 和 Claude 服务端执行评分） |
 
 ### 资源（resources）
 
 Deployment 运行时可挂载的资源：
 
 | 资源类型 | 字段 | 说明 |
 |---------|------|------|
-| `file` | `file_id` / `source` / `mount_path` | 文件资源；`file_id` 引用已上传文件；`source` 为本地路径，Claude 在 `apply` 时上传、Qoder 在 `run` 时上传 |
+| `file` | `file_id` / `source` / `mount_path` | 文件资源；`file_id` 引用已上传文件；`source` 为本地路径，Qoder 和 Claude 在 `apply` 时上传 |
 | `memory_store` | `memory_store` / `access` / `instructions` | 引用 Memory Store；`access` 为 `read_write`（默认）或 `read_only` |
-| `github_repository` | `url` / `checkout` / `mount_path` / `authorization_token` | 检出 Git 仓库（仅 Claude） |
+| `github_repository` | `url` / `checkout` / `mount_path` / `authorization_token` | 检出 Git 仓库（Qoder 和 Claude） |
 
 ### 运行与查看
 
@@ -669,7 +669,7 @@ Session 的架构遵循 Serverless Framework 模式：**定义管理**（`plan/a
 | `memory_stores` | string[] | 否 | 覆盖 Agent 的 Memory Store |
 | `resources` | array | 否 | 运行时挂载的资源（file / memory_store / github_repository） |
 | `initial_events` | array | 是 | 运行时投递的初始事件（user.message / system.message / user.define_outcome），1–50 条 |
-| `schedule` | object | 否 | cron 调度（`expression` + 必填 `timezone`），仅 Claude 服务端执行 |
+| `schedule` | object | 否 | cron 调度（`expression` + 必填 `timezone`），Qoder 和 Claude 服务端执行 |
 | `description` | string | 否 | 描述 |
 | `provider` | string | 否 | 指定 Provider，覆盖 defaults |
 | `metadata` | Record | 否 | 自定义元数据 |

docs/guides/deploy-to-qoder.md

@@ -1,6 +1,6 @@
 # Deploy to Qoder
 
-Qoder is a managed-agent platform with native **memory stores** but no multi-agent or server-side deployment primitive.
+Qoder is a managed-agent platform with native **memory stores** and **deployments**, but no multi-agent primitive.
 
 ## Provider configuration
 
@@ -20,11 +20,10 @@ providers:
 
 | Feature | Tier |
 |---------|:----:|
-| Environment, Vault, Skill, Agent, MCP Server, Memory Store, Session | native |
+| Environment, Vault, Skill, Agent, MCP Server, Memory Store, Deployment, Session | native |
 | Multi-Agent | unsupported |
-| Deployment | emulated |
 
-A `deployment run` on Qoder expands into a one-shot session at run time; scheduling and outcome rubrics are not enforced server-side — use external cron/CI for scheduled runs.
+A `deployment run` on Qoder creates a native Deployment Run and associated Session. Cron schedules run server-side.
 
 ## Tool naming
 

docs/guides/manage-deployments.md

@@ -67,12 +67,13 @@ agents deployment run <name>            # trigger a run
 | Provider | Deployment tier | What `deployment run` does |
 |----------|:--------------:|----------------------------|
 | Claude | native | schedules server-side through the deployments API |
-| Qoder, Bailian, Ark | emulated | expands into a one-shot session at run time |
+| Qoder | native | creates a deployment run and associated session |
+| Bailian, Ark | emulated | expands into a one-shot session at run time |
 
 On the emulated providers, scheduling and outcome rubrics are **not** enforced server-side — use external cron/CI for always-on or scheduled runs.
 
 ## Examples
 
 - Native deployment + outcome rubric: [`examples/claude/deployment/`](../../examples/claude/deployment/)
-- Emulated deployment + memory store: [`examples/qoder/deployment/`](../../examples/qoder/deployment/)
+- Native deployment + memory store: [`examples/qoder/deployment/`](../../examples/qoder/deployment/)
 - Emulated deployment + file resources: [`examples/bailian/deployment/`](../../examples/bailian/deployment/) and [`examples/ark/deployment/`](../../examples/ark/deployment/)

docs/reference/cli.md

@@ -6,13 +6,13 @@ The `agents` command. This page documents every command and option defined in `p
 
 | Option | Description |
 |--------|-------------|
-| `-f, --config <path>` | Path to the config file. Defaults to `agents.yaml`. |
+| `-f, --file <path>` | Path to the config file. Defaults to `agents.yaml`. |
 | `-v, --verbose` | Increase logging verbosity. Repeat: `-vv`. |
 | `-q, --quiet` | Suppress non-error output. |
 | `--no-color` | Disable colored output. |
 | `-V, --version` | Print the CLI version. |
 
-Most commands accept `--config <path>` and `--provider <name>` to target a single provider. Run `agents <command> --help` for the definitive list.
+Provider-backed commands such as `plan`, `apply`, `models`, `session`, and `deployment` accept `--provider <name>` to target a single provider. `validate` is an offline whole-file check and does not accept a provider filter. Run `agents <command> --help` for the definitive option list.
 
 ## `agents init`
 
@@ -30,7 +30,7 @@ Launch the local web UI (fetches `@openagentpack/playground` on demand) and open
 
 ## `agents validate`
 
-Validate the configuration file offline — checks YAML shape and field validity without making API calls.
+Validate the whole configuration file offline — checks YAML shape and field validity without making API calls. This command does not accept `--provider`; use `plan --provider <name> --refresh false` when you want to inspect one provider's projected changes without contacting remote APIs.
 
 ## `agents plan`
 
@@ -120,7 +120,7 @@ Manage scheduled / triggered deployments.
 |------------|-------------|
 | `deployment list` | List deployments tracked in state. |
 | `deployment get <name>` | Show a deployment's status and resolved bindings. |
-| `deployment run <name>` | Trigger a deployment run (native on Claude, emulated as a session on Bailian/Qoder/Volcengine Ark). |
+| `deployment run <name>` | Trigger a deployment run (native on Qoder/Claude, emulated as a session on Bailian/Volcengine Ark). |
 
 ## `agents models`