@fateforge/archery-cli 1.0.4 → 1.0.6

package/.agent/CLI-SPEC.md

@@ -134,6 +134,7 @@ Error codes and exit codes must align:
 - `E_CONFLICT` -> 6
 - `E_NETWORK` / `E_RATE_LIMITED` / `E_SERVER` -> 7
 - `E_TIMEOUT` -> 8
+- `E_INTEGRITY` -> 1 (release integrity failure: missing/invalid signature or checksum mismatch; **non-retryable**, see §14)
 - `E_HUMAN_REQUIRED` -> 9 (optional, only when §16.3 is enabled)
 
 When the failure comes from an upstream HTTP call, map the status onto the
@@ -635,17 +636,31 @@ Version notification contract:
 
 Release verification baseline:
 
-- Verify the archive/package against `checksums.txt`; checksum mismatch, missing
-  checksum file, or missing archive entry fails closed.
-- Signed releases should sign `checksums.txt` with Sigstore/Cosign keyless
-  signing from the tagged GitHub Actions release workflow. Verifiers should
-  validate the bundle against the expected repository workflow identity and the
-  GitHub OIDC issuer.
-- Update results carry `signature_status` (a short string describing where
-  release integrity verification happened: e.g. `verified`, `not_checked`,
-  `handled_by_npm_installer`, `manual_release_verification_required`) and
-  `signature_verified` (true only when local Sigstore verification actually
-  ran and succeeded). Never imply checksum verification is a signature.
+- **Mandatory signature verification, no skip path**: the binary self-update path
+  MUST verify the Sigstore signature on `checksums.txt` in-process, then verify
+  the archive SHA256 against it. A missing signature bundle, a signature that does
+  not verify, or a checksum mismatch all fail closed — there is no "can't verify,
+  proceed anyway" degradation. The whole chain surfaces `E_INTEGRITY` (exit 1,
+  non-retryable): a forged or corrupt release is not a transient blip to retry.
+- **Verifier embedded, no user-environment dependency**: verification happens
+  inside the tool binary (Go via `sigstore-go`, Python inside the frozen binary
+  via `sigstore`) with **no external cosign** and nothing pre-installed on the
+  machine. The TUF trust root is bootstrapped from the library's embedded
+  `root.json`, not fetched on first-use trust (TOFU).
+- **New bundle format**: the signing side produces a Sigstore protobuf bundle
+  (`checksums.txt.sigstore.json`) via `cosign sign-blob --new-bundle-format`, which
+  the in-process verifier consumes; the legacy cosign bundle format is not accepted.
+- **Identity binding**: verifiers bind the certificate SAN to this repo's tagged
+  release workflow (`…/release.yml@refs/tags/v*`, anchored `^…$`) and validate the
+  GitHub OIDC issuer. When the target tag is known, pin the exact identity (stronger
+  than a regexp).
+- **Cross-language parity**: Go binaries and Python frozen binaries follow the same
+  self-update contract — download archive → in-process signature verify → checksum
+  → replace binary. Package managers do not own integrity.
+- Update results carry `signature_status` (`verified` on success; any failure exits
+  via the error envelope) and `signature_verified` (true only when in-process
+  Sigstore verification actually ran and succeeded). Never imply checksum
+  verification is a signature.
 
 - After `update --confirm <token>` succeeds, return `previous_version` and `current_version` in `data`.
 - Also hint in the result: `run "changelog --since <previous_version>" to see what changed`.

package/.agent/CLI-SPEC_zh.md

@@ -131,6 +131,7 @@
 - `E_CONFLICT` -> 6
 - `E_NETWORK` / `E_RATE_LIMITED` / `E_SERVER` -> 7
 - `E_TIMEOUT` -> 8
+- `E_INTEGRITY` -> 1（发布完整性失败：签名缺失/无效或 checksum 不符；**非重试**，见 §14）
 - `E_HUMAN_REQUIRED` -> 9（可选，仅启用 §16.3 时）
 
 当错误来自上游 HTTP 调用时，按状态码映射到错误码，让 agent 能从 `error.code` +
@@ -583,9 +584,12 @@ update 必须遵守的契约：
 
 release 校验基线：
 
-- 按 `checksums.txt` 校验归档/包；checksum 不匹配、缺失 checksum 文件、或缺少当前归档条目，都必须失败关闭。
-- 已签名 release 应由 tagged GitHub Actions release workflow 使用 Sigstore/Cosign keyless 模式签署 `checksums.txt`。验证端应绑定到预期仓库 workflow 身份和 GitHub OIDC issuer。
-- update 结果携带 `signature_status`（一个短字符串说明发布完整性在哪里被验证：如 `verified`、`not_checked`、`handled_by_npm_installer`、`manual_release_verification_required`）与 `signature_verified`（仅当本地 Sigstore 验证真实执行且成功时为 true）。不能把 checksum 校验伪装成签名校验。
+- **强制签名验证，无跳过路径**：二进制自更新路径必须在进程内验证 `checksums.txt` 的 Sigstore 签名，再用它校验归档 SHA256。签名 bundle 缺失、签名验不过、checksum 不符，一律**失败关闭**，不存在"验不了就放行"的降级。整条链对外返回 `E_INTEGRITY`（exit 1，非重试）——伪造或损坏的发布不该被当成可重试的瞬时错误。
+- **验证器内置、不依赖用户环境**：验证在工具二进制内完成（Go 用 `sigstore-go`，Python 冻结二进制内用 `sigstore`），**不外挂 cosign**，不依赖机器上预装任何东西。TUF 信任根从库内嵌的 `root.json` 引导（不是 TOFU 现拉现信）。
+- **新版 bundle 格式**：签名侧用 `cosign sign-blob --new-bundle-format` 产出 Sigstore protobuf bundle（`checksums.txt.sigstore.json`），与进程内验证器对齐；旧版 cosign bundle 格式不被接受。
+- **身份绑定**：验证端把证书 SAN 绑定到本仓库的 tagged release workflow（`…/release.yml@refs/tags/v*`，锚定 `^…$`）并校验 GitHub OIDC issuer。已知目标 tag 时可绑精确身份，强于正则。
+- **跨语言统一**：Go 二进制与 Python 冻结二进制走同一套自更新契约——都是"下载归档 → 进程内验签 → checksum → 替换二进制"，包管理器不参与完整性。
+- update 结果携带 `signature_status`（成功即 `verified`；异常一律走 error envelope 中止）与 `signature_verified`（仅当进程内 Sigstore 验证真实执行且成功时为 true）。不能把 checksum 校验伪装成签名校验。
 
 - `update --confirm <token>` 成功后，结果 `data` 中返回 `previous_version` 与 `current_version`。
 - 同时在结果中提示：`run "changelog --since <previous_version>" to see what changed`。

package/.agent/SEC-SPEC.md

@@ -97,15 +97,20 @@ Fallback and channel rules:
 
 ## 5. Supply chain (applies to anything distributed)
 
-- **Integrity verification**: install scripts and self-update commands pulling a
-  binary must verify checksums, **hard-fail on mismatch**, and report signature
-  verification status explicitly. A checksum proves bytes match a checksum file;
-  it does not prove the checksum file came from the publisher.
-- **Signed release material**: release pipelines should sign `checksums.txt`
-  with Sigstore/Cosign keyless signing from the tagged GitHub Actions release
-  workflow, publishing the bundle alongside the checksum file. Verification must
-  bind the signature to the expected repository workflow identity and GitHub OIDC
-  issuer.
+- **Integrity verification, mandatory and no-skip**: binary self-update MUST verify
+  the Sigstore signature on `checksums.txt` **in-process** (the verifier is embedded
+  in the tool binary — Go via `sigstore-go`, Python inside the frozen binary via
+  `sigstore` — with **no external cosign** and no user-environment dependency), then
+  verify the archive SHA256. A missing/invalid signature or a checksum mismatch
+  **fails closed** with no "can't verify, proceed anyway" degradation, surfacing
+  `E_INTEGRITY` (non-retryable). A checksum proves bytes match a checksum file; only
+  the signature proves the checksum file came from the publisher.
+- **Signed release material**: release pipelines sign `checksums.txt` with
+  Sigstore/Cosign keyless signing from the tagged GitHub Actions release workflow
+  using `--new-bundle-format` (a Sigstore protobuf bundle the in-process verifier
+  consumes). Verification binds the signature to the expected repository workflow
+  identity (anchored `^…$`) and GitHub OIDC issuer; the TUF trust root is
+  bootstrapped from the library's embedded root, not TOFU.
 - **Dependency locking + audit**: commit a lockfile; CI runs `npm audit` / `pip-audit` and blocks high-severity dependencies.
 - **Traceable builds**: release artifacts are built by CI from tagged source, no hand-uploaded unknown binaries.
 - **No remote scripts in postinstall**: don't execute code freshly pulled from the network at install time.

package/.agent/SEC-SPEC_zh.md

@@ -88,8 +88,8 @@ Agent 侧约定（同时写进 SKILL-SPEC 的用法）：
 
 ## 5. 供应链（凡分发即适用）
 
-- **完整性校验**：安装脚本和自更新命令拉取二进制时必须校验 checksum，**不匹配硬失败**，并显式返回签名校验状态。checksum 只能证明字节与 checksum 文件一致，不能证明 checksum 文件来自发布者。
-- **签名发布材料**：release pipeline 应由 tagged GitHub Actions release workflow 使用 Sigstore/Cosign keyless 模式签署 `checksums.txt`，并把 bundle 与 checksum 一起发布。验证时必须绑定到预期仓库 workflow 身份和 GitHub OIDC issuer。
+- **完整性校验，强制且无跳过**：二进制自更新必须**在进程内**验证 `checksums.txt` 的 Sigstore 签名（验证器内置工具二进制，Go 用 `sigstore-go`、Python 冻结二进制内用 `sigstore`，**不外挂 cosign**、不依赖用户环境），再用它校验归档 SHA256。签名缺失/验不过/checksum 不符一律**失败关闭**，没有"验不了就放行"的降级；对外返回 `E_INTEGRITY`（非重试）。checksum 只能证明字节与 checksum 文件一致，签名才能证明 checksum 文件来自发布者。
+- **签名发布材料**：release pipeline 由 tagged GitHub Actions release workflow 用 Sigstore/Cosign keyless 模式以 `--new-bundle-format` 签署 `checksums.txt`（产出 Sigstore protobuf bundle），与进程内验证器对齐。验证时绑定到预期仓库 workflow 身份（锚定 `^…$`）和 GitHub OIDC issuer；TUF 信任根从库内嵌 root 引导，不 TOFU。
 - **依赖锁定 + 审计**：提交 lockfile；CI 跑 `npm audit` / `pip-audit` 一类，高危依赖阻断。
 - **构建可追溯**：发布产物由 CI 从打了 tag 的源码构建，不手工上传不明二进制。
 - **不在 postinstall 跑远程脚本**：安装期不执行从网络现拉的代码。

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.6] - 2026-06-16
+
+### Changed
+
+- `update` now verifies the release Sigstore signature on `checksums.txt` **in-process** (embedded `sigstore-go`, bootstrapped from the embedded TUF trust root) instead of shelling out to an external `cosign`. Verification is mandatory and fail-closed: a missing signature bundle, a signature that does not verify against this repo's tagged release-workflow identity, or a checksum mismatch all refuse the update — there is no skip path. Releases are now signed with `cosign sign-blob --new-bundle-format`.
+
+### Security
+
+- Release-integrity failures (missing/invalid signature or checksum mismatch) now return the non-retryable `E_INTEGRITY` error code (exit 1) instead of a retryable network code, so an agent treats a possible supply-chain issue as a hard stop rather than retrying.
+
+## [1.0.5] - 2026-06-16
+
+### Added
+
+- **`--read-only` global switch (and `ARCHERY_CLI_READONLY` env var).** When set, every write command is refused at the shared write chokepoint with an `E_FORBIDDEN` envelope (exit 4) — before the dry-run preview or any network call. Read commands are unaffected. This lets an agent run safely against production with writes hard-disabled regardless of `--dry-run`/`--confirm`. `doctor` and `context` report the current read-only state.
+- **2FA detection + `--otp` (and `ARCHERY_CLI_OTP`).** Session login now understands Archery's two-factor flow. If an account has 2FA enabled, `/authenticate/` accepts the password but does not log in (it returns a `session_key` in `data` with no `sessionid` cookie); the CLI now detects this:
+  - With `--otp <6-digit code>` it completes the login via `POST /api/v1/user/2fa/` and caches the resulting session, so **subsequent commands need no OTP** until the session expires.
+  - Without an OTP it fails fast with the new **`E_2FA_REQUIRED`** code (exit 9, "human required") and a clear hint to retry with `--otp`, instead of the old opaque "session login failed".
+  - 2FA codes are ~30s-lived: generate the code immediately before running. The cached `sessionid` (keyring) is reused afterwards, so OTP is a one-time cost per session.
+
+### Changed
+
+- **`workflow detail` reworked to surface execution results.** Detail now reads the execution/review result rows from `/sqlworkflow/detail_content/` and exposes them as `result[]` (each row carries `stage`, `stageStatus`, `errLevel`, `error`, `affectedRows`, `executeTime`), plus the string `statusCode` (e.g. `workflow_exception`) backfilled from the workflow list. An agent can now see **why an execution failed** (e.g. `Invalid remote backup information`) straight from the CLI instead of opening the web UI. SQL content is reconstructed from the rows, with inception wrapper statements filtered out.
+- **Unified instance/group flags for `workflow submit` / `sqlcheck` / `auto-review`.** Session mode now also accepts the numeric `--instance` (ID) and `--group` (ID), resolving them to names via the instance/resource-group lists — the same flags JWT mode already used, so agents no longer have to remember a different flag set per transport. The name flags (`--instance-name` / `--group-name`) still work and win when both are given; an unknown ID fails with a clear `E_NOT_FOUND`.
+- **Skill schema-discovery guidance.** The Skill now steers agents to locate tables/columns by **meaning** via `dict tables` / `dict table-info` (which carry table and column comments) instead of `instance resource` / `instance describe` (bare names only), with an explicit "stop guessing, ask the user" rule when no matching column exists. Fixes all `dict` examples that omitted the required `--db-type`, which fail with `Instance.DoesNotExist` on Archery v1.8.5.
+
+### Notes
+
+- **DDL execution and backups.** Executing a DDL workflow with backup enabled needs Archery's backup feature configured (`enable_backup_switch` on and a reachable backup database). On environments without it, execution fails with `Invalid remote backup information` — this is an Archery configuration prerequisite, not a CLI bug. Either have a DBA configure the backup database, or submit with backup disabled (`--backup=false`).
+
 ## [1.0.4] - 2026-06-16
 
 ### Added

package/README.md

@@ -41,6 +41,10 @@ PowerShell uses `$env:NAME = "value"` for the same environment variables. Keep r
 
 **Dual-mode transport — usable by ordinary developer accounts.** By default the CLI logs in and talks to Archery over its **web session + AJAX endpoints** (`/authenticate/`, `/sqlworkflow_list/`, `/sqlquery/`, …). This path works on every Archery version and for plain accounts, where the `/api/v1` REST surface is typically closed (`403`) or simply not enabled. REST + JWT is kept as an opt-in advanced mode: pass `--mode jwt` or set `mode: jwt` on a region. Mode precedence is `--mode` flag → region config → `session` default. Verified live against `hhyo/archery:v1.8.5` with an ordinary account.
 
+**Read-only mode.** Pass `--read-only` (or set `ARCHERY_CLI_READONLY` to any non-empty value) to hard-disable every write command. Writes are refused at the shared chokepoint with an `E_FORBIDDEN` envelope (exit 4) before any network call, regardless of `--dry-run`/`--confirm`; read commands are unaffected. Use it to run safely against production. `doctor` and `context` report the active state.
+
+**Two-factor auth.** For accounts with 2FA enabled, supply a fresh 6-digit code with `--otp <code>` (or `ARCHERY_CLI_OTP`). The CLI detects when Archery requires a second factor and, without a code, fails fast with `E_2FA_REQUIRED` (exit 9) and a hint to retry with `--otp`. Codes are ~30s-lived, so generate one immediately before running; the resulting session is cached, so later commands need no OTP until it expires.
+
 Worst-case risk tier: **T2 high** - can execute and manage SQL workflows against configured database instances. See [SECURITY.md](SECURITY.md) and [.agent/SEC-SPEC.md](.agent/SEC-SPEC.md).
 
 ## Capabilities
@@ -86,6 +90,8 @@ Config location: `~/.archery-cli/config.json`.
 | `ARCHERY_CLI_USERNAME` | Username |
 | `ARCHERY_CLI_PASSWORD` | Password |
 | `ARCHERY_CLI_REGION` | Active region/profile |
+| `ARCHERY_CLI_READONLY` | Any non-empty value disables all write commands (same as `--read-only`) |
+| `ARCHERY_CLI_OTP` | 6-digit 2FA code for accounts with two-factor auth (same as `--otp`) |
 | `NO_COLOR` | Disable colored text output when text mode is explicitly requested |
 
 Saved credentials, when supported, are encrypted or stored in the OS credential store. Environment variables take precedence and are the preferred path for short-lived Agent sessions.

package/README_zh.md

@@ -41,6 +41,10 @@ PowerShell 使用 `$env:NAME = "value"` 设置同样的环境变量。真实密
 
 **双模传输 —— 普通开发者账号即可用。** CLI **默认走 Archery 网页端的 session + AJAX 端点**（`/authenticate/`、`/sqlworkflow_list/`、`/sqlquery/` 等）登录和请求。这条路径在所有 Archery 版本、对普通账号都可用；而 `/api/v1` REST 面通常对普通账号关闭（`403`）或根本未开启。REST + JWT 作为可选的高级模式保留：传 `--mode jwt` 或在 region 配置 `mode: jwt` 即可。模式优先级为 `--mode` 参数 → region 配置 → 默认 `session`。已在 `hhyo/archery:v1.8.5` 上用普通账号真机验证。
 
+**只读模式。** 传 `--read-only`（或将 `ARCHERY_CLI_READONLY` 设为任意非空值）即可硬禁用所有写命令。写命令会在统一入口处被拒，返回 `E_FORBIDDEN`（退出码 4），且发生在任何网络调用之前，不受 `--dry-run`/`--confirm` 影响；读命令不受影响。适合在生产环境安全运行。`doctor` 和 `context` 会显示当前是否只读。
+
+**二次验证（2FA）。** 对开启了 2FA 的账号，用 `--otp <验证码>`（或 `ARCHERY_CLI_OTP`）传入新鲜的 6 位验证码。CLI 会检测到 Archery 要求二次验证；若未提供验证码，会立即失败并返回 `E_2FA_REQUIRED`（退出码 9），提示用 `--otp` 重试。验证码有效期约 30 秒，请在运行前即时生成；验证成功后会话会被缓存，后续命令在会话过期前无需再次输入 OTP。
+
 最坏情况风险等级：**T2 高风险** - 可对已配置数据库实例执行和管理 SQL 工单。参见 [SECURITY.md](SECURITY.md) 和 [.agent/SEC-SPEC.md](.agent/SEC-SPEC.md)。
 
 ## 能力
@@ -86,6 +90,8 @@ README 只做地图，不做完整手册。Agent 在执行任务命令前，应
 | `ARCHERY_CLI_USERNAME` | 用户名 |
 | `ARCHERY_CLI_PASSWORD` | 密码 |
 | `ARCHERY_CLI_REGION` | 当前区域/profile |
+| `ARCHERY_CLI_READONLY` | 任意非空值即禁用所有写命令（等价于 `--read-only`） |
+| `ARCHERY_CLI_OTP` | 开启 2FA 账号的 6 位验证码（等价于 `--otp`） |
 | `NO_COLOR` | 显式使用 text 模式时禁用彩色输出 |
 
 支持保存凭据时，凭据会加密或进入 OS 凭据库。环境变量优先级更高，也是短生命周期 Agent 会话的推荐方式。

package/docs/LIVE-SMOKE-EVIDENCE.md

@@ -361,6 +361,37 @@ intermittently returned `用户名或密码错误`. Using `http://127.0.0.1:9123
 defect; the session login flow itself (GET csrf → POST authenticate → cookie)
 matches the verified curl flow byte-for-byte.
 
+## 2026-06-16 — 1.0.5 features (read-only, 2FA, param unification, detail rework)
+
+Verified against the same `tools-e2e-archery` container (`hhyo/archery:v1.8.5`,
+base `http://localhost:9123`) with the ordinary superuser account `cli_verify`,
+binary built from this working tree (`go build -o /tmp/a.exe ./cmd/archery-cli`),
+`ARCHERY_CLI_NO_KEYRING=1`.
+
+### Result by feature
+
+| Feature | Status | Evidence |
+|---------|--------|----------|
+| `--read-only` reflected in `doctor` | live (read) | PASS — `doctor` JSON shows `readOnly:true` and a `read-only` warn check; `auth` still `pass` (logged in to the real server). |
+| `--read-only` reflected in `context` | live (read) | PASS — `context.data.readOnly == true`. |
+| `--read-only` refuses a write | live | PASS — `workflow submit ... --read-only --dry-run` → `E_FORBIDDEN`, exit 4, before any network call. |
+| `ARCHERY_CLI_READONLY` env | live | PASS — read command (`workflow list`) succeeds under the env var; the env is a pure read-allow path. |
+| Param unification: `--instance`/`--group` IDs (session) | live | PASS — `workflow submit --instance 1 --group 1 --dry-run` preview resolves `instanceName:e2e-mysql`, `groupName:smoke-rg`; confirm submitted real workflow id 4. |
+| Unknown instance ID | live | PASS — `--instance 999` → `E_NOT_FOUND` (exit 3) with a clear "check 'instance list'" message. |
+| `workflow detail` result rework | live | PASS — `detail 4` returns `result[]` (real auto-review rejection "仅支持DML和DDL语句…") + `statusCode:workflow_autoreviewwrong` + numeric `status:3`. |
+| `--otp` harmless for non-2FA account | live | PASS — passing `--otp 000000` for `cli_verify` (no 2FA) does not break login; the OTP path only fires when the server signals 2FA. |
+| 2FA detection + `--otp` completion | **mock only** | The `cli_verify` account has **no 2FA enabled**, so the 2FA login branch cannot be exercised live. Covered by unit tests `TestEnsureSession_2FARequiredNoOTP` / `2FAWithOTPSucceeds` / `2FAWrongOTP` against an httptest server that mimics v1.8.5's `/authenticate/` (status 0 + `data` session_key, no sessionid) and `/api/v1/user/2fa/`. **Honest gap: the real `/api/v1/user/2fa/` round-trip is not live-verified.** |
+
+Test workflow id 4 was cancelled after verification (`workflow cancel 4`) to
+leave the container clean.
+
+### Honesty notes
+
+- **Race detector not run on this host:** `go test -race` needs cgo + gcc, which
+  are unavailable on the verifier machine. The non-race suite (`go test ./...`)
+  is fully green, and `golangci-lint run` reports 0 issues.
+- **2FA is mock-verified only** for the reason above.
+
 ## Reproduce
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fateforge/archery-cli",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Archery SQL audit CLI for AI Agents - manage SQL workflows, queries, instances, diagnostics, and data dictionaries with a machine-readable contract",
   "keywords": [
     "archery",
@@ -26,12 +26,12 @@
     "archery-cli": "scripts/run.js"
   },
   "optionalDependencies": {
-    "@fateforge/archery-cli-darwin-arm64": "1.0.4",
-    "@fateforge/archery-cli-darwin-x64": "1.0.4",
-    "@fateforge/archery-cli-linux-arm64": "1.0.4",
-    "@fateforge/archery-cli-linux-x64": "1.0.4",
-    "@fateforge/archery-cli-win32-arm64": "1.0.4",
-    "@fateforge/archery-cli-win32-x64": "1.0.4"
+    "@fateforge/archery-cli-darwin-arm64": "1.0.5",
+    "@fateforge/archery-cli-darwin-x64": "1.0.5",
+    "@fateforge/archery-cli-linux-arm64": "1.0.5",
+    "@fateforge/archery-cli-linux-x64": "1.0.5",
+    "@fateforge/archery-cli-win32-arm64": "1.0.5",
+    "@fateforge/archery-cli-win32-x64": "1.0.5"
   },
   "files": [
     "scripts/run.js",

package/skills/archery-cli/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: archery-cli
-version: "1.0.4"
+version: "1.0.6"
 description: "Archery SQL audit platform CLI for managing SQL workflows, queries, instances, diagnostics. Use when the user asks about SQL审核, database operations, Archery platform management, or needs to submit/review/execute SQL against database instances."
 license: MIT
 user-invocable: true
-metadata: {"requires":{"bins":["archery-cli"],"min_version":"1.0.4"}}
+metadata: {"requires":{"bins":["archery-cli"],"min_version":"1.0.6"}}
 ---
 
 # archery-cli
@@ -58,6 +58,10 @@ First-time setup: ask user for Archery URL + credentials, then run `archery-cli
 | Dangerous writes | If `reference` shows `requiresDangerous`, include `--dangerous` in both dry-run and confirm commands |
 | Discovery | `archery-cli reference` is the machine truth for params, `write`, `requiresConfirmation`, `requiresDangerous`, `riskLevel`, output schemas, and errors |
 | Transport | Defaults to **session** mode (Archery web AJAX endpoints) — works for ordinary accounts on all versions. REST + JWT is opt-in via `--mode jwt` or a region's `mode: jwt`. Precedence: `--mode` flag → region config → `session`. |
+| Read-only | Pass `--read-only` (or set `ARCHERY_CLI_READONLY`) to hard-disable all writes; they fail with `E_FORBIDDEN` (exit 4) before any network call. Use it when the task is read-only/analysis. |
+| 2FA | If a command fails with `E_2FA_REQUIRED` (exit 9), the account has 2FA on. Ask the user for a fresh 6-digit code and retry the **same** command with `--otp <code>` (codes last ~30s). The session is then cached, so later commands need no OTP. |
+| Instance/group IDs | `workflow submit/sqlcheck/auto-review` accept either `--instance`/`--group` (numeric IDs, resolved automatically) **or** `--instance-name`/`--group-name`. IDs work in both transport modes. |
+| Schema discovery | To locate a table/column by **meaning** (not its exact name), use `dict tables` → `{name, comment}` then `dict table-info` → per-column `column_comment`: those carry the human labels (e.g. `班级学生表`, `性别`). `instance resource`/`instance describe` return **bare names with no comments** — use them only when you already know the exact identifier. Already know the table name but not which instance holds it? `instance table-instances --table <name>`. `dict` needs `--instance <name>` (not ID) **and** `--db-type <mysql/...>` (db-type is required on v1.8.5; omitting it fails with `Instance.DoesNotExist`). |
 
 ## Trigger list
 
@@ -99,7 +103,8 @@ First-time setup: ask user for Archery URL + credentials, then run `archery-cli
 | Review slow queries | `archery-cli slowquery review --instance mydb --start "2024-01-01 00:00:00" --end "2024-01-31 23:59:59"` |
 | List processes | `archery-cli diagnostic process --instance mydb` |
 | List binlog files | `archery-cli binlog list --instance mydb` |
-| Browse tables | `archery-cli dict tables --instance mydb --db test` |
+| Find a table/column by meaning | `archery-cli dict tables --instance mydb --db test --db-type mysql` (scan `comment`), then `dict table-info ... --table t` (scan `column_comment`) |
+| Browse tables | `archery-cli dict tables --instance mydb --db test --db-type mysql` |
 | Test instance connectivity | `archery-cli instance test-instance --instance 1 --compact` |
 | Create a database on an instance | `archery-cli instance create-db --instance 1 --db reporting --owner alice --dangerous --dry-run`, then `--dangerous --confirm <token>` |
 | Create a database account | `archery-cli instance create-user --instance 1 --user app --host '%' --password '...' --dangerous --dry-run`, then `--dangerous --confirm <token>` |
@@ -177,6 +182,7 @@ Check `ok` first, then act on exit code:
 | 6 | `E_CONFLICT` | Stale or invalid token | Re-run `--dry-run`, get fresh token, retry |
 | 7 | `E_NETWORK`/`E_RATE_LIMIT`/`E_SERVER` | Transient error | Back off and retry |
 | 8 | `E_TIMEOUT` | Timeout | Back off and retry |
+| 9 | `E_2FA_REQUIRED` | Account needs a 2FA code | Ask user for a fresh 6-digit code, retry same command with `--otp <code>` (~30s validity) |
 
 ## Permission and security boundary declarations
 
@@ -218,8 +224,13 @@ archery-cli workflow detail 42
 # After approval, execute
 archery-cli workflow execute 42 --mode auto --dangerous --dry-run
 archery-cli workflow execute 42 --mode auto --dangerous --confirm ct_...
+
+# If execution fails, `workflow detail 42` now shows the reason in result[]:
+archery-cli workflow detail 42 --compact   # look at result[].error / statusCode
 ```
 
+**DDL execution + backups.** If a DDL execution fails with `result[].error = "Invalid remote backup information"`, the target Archery environment has not configured backups (no `enable_backup_switch` / no reachable backup database). This is an **Archery configuration prerequisite, not a CLI bug**. Either ask a DBA to configure the backup database, or submit the workflow with backup disabled (`--backup=false`). The cause is visible directly from `workflow detail` (as of 1.0.5), so check `result[]` before escalating.
+
 ### 2. Query a database and analyze results
 
 ```bash
@@ -269,23 +280,37 @@ archery-cli diagnostic kill --instance prod-mysql --threads "12345,12346" --dang
 
 ### 5. Browse data dictionary and table structure
 
+**Locating a table/column from a vague ask** (e.g. "how old is 张三") — the comment is your map, don't guess at names:
+
+```bash
+# 1. Scan table comments to find the table that matches the concept ("学生")
+archery-cli dict tables --instance prod-mysql --db mydb --db-type mysql --compact
+#    → [{"name":"students","comment":"班级学生表"}, ...]
+
+# 2. Scan column comments to map the concept to a column ("年龄")
+archery-cli dict table-info --instance prod-mysql --db mydb --db-type mysql --table students --compact
+#    → if no age/birthday column exists, STOP guessing — ask the user or derive it.
+```
+
+Prefer the two steps above over `instance resource` (bare names) and `instance describe` (no comments) whenever the user names a **concept**, not an exact identifier. `dict` requires `--db-type` on v1.8.5.
+
 ```bash
 # List all tables in a database
-archery-cli dict tables --instance prod-mysql --db mydb
+archery-cli dict tables --instance prod-mysql --db mydb --db-type mysql
 
-# Show table metadata and indexes
-archery-cli dict table-info --instance prod-mysql --db mydb --table orders
+# Show table metadata and indexes (includes column_comment)
+archery-cli dict table-info --instance prod-mysql --db mydb --db-type mysql --table orders
 
-# Describe table columns
+# Describe table columns (bare structure, no comments — use when the name is already known)
 archery-cli instance describe --instance prod-mysql --db mydb --table orders
 
 # List views, triggers, procedures
-archery-cli dict views --instance prod-mysql --db mydb
-archery-cli dict triggers --instance prod-mysql --db mydb
-archery-cli dict procedures --instance prod-mysql --db mydb
+archery-cli dict views --instance prod-mysql --db mydb --db-type mysql
+archery-cli dict triggers --instance prod-mysql --db mydb --db-type mysql
+archery-cli dict procedures --instance prod-mysql --db mydb --db-type mysql
 
 # Export data dictionary as HTML
-archery-cli dict export --instance prod-mysql --db mydb --format raw > dict.html
+archery-cli dict export --instance prod-mysql --db mydb --db-type mysql --format raw > dict.html
 ```
 
 ### 6. Binlog parsing and data recovery

package/skills/archery-cli/reference/workflow.md

@@ -46,11 +46,17 @@ archery-cli workflow sqlcheck --instance 1 --db mydb --sql "ALTER TABLE users AD
 |------|------|-------------|
 | `--fields` | string | Comma-separated output fields |
 
+`workflow detail` returns the execution/review result rows in `result[]` (each
+`{stage, stageStatus, errLevel, error, affectedRows, executeTime}`) plus the
+string `statusCode` (e.g. `workflow_exception`). When an execution failed, the
+reason is in `result[].error` — read it before escalating.
+
 ### `workflow sqlcheck` flags
 
 | Flag | Type | Required | Description |
 |------|------|----------|-------------|
-| `--instance` | int | yes | Target instance ID |
+| `--instance` | int | one of | Target instance ID (resolved to a name in session mode) |
+| `--instance-name` | string | one of | Target instance name (session mode; wins over `--instance`) |
 | `--db` | string | yes | Target database name |
 | `--sql` | string | yes | SQL to check |
 
@@ -71,13 +77,21 @@ archery-cli workflow submit --name "Add email index" --instance 1 --db mydb \
 | Flag | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
 | `--name` | string | yes | -- | Workflow title |
-| `--instance` | int | yes | -- | Target instance ID |
+| `--instance` | int | one of | -- | Target instance ID (resolved to a name in session mode) |
+| `--instance-name` | string | one of | -- | Target instance name (session mode; wins over `--instance`) |
 | `--db` | string | yes | -- | Target database name |
 | `--sql` | string | yes | -- | SQL content |
-| `--group` | int | no | (auto) | Resource group ID |
-| `--backup` | bool | no | true | Require backup before execution |
+| `--group` | int | one of | (auto) | Resource group ID (resolved to a name in session mode) |
+| `--group-name` | string | one of | -- | Resource group name (session mode; wins over `--group`) |
+| `--backup` | bool | no | true | Require backup before execution (needs Archery backups configured; see note below) |
 | `--demand-url` | string | no | -- | Related demand/requirement URL |
 
+> **Backup prerequisite:** with `--backup=true` (the default), DDL execution
+> needs Archery's backup feature configured (`enable_backup_switch` + a reachable
+> backup DB). Without it, execution fails with `Invalid remote backup
+> information` (visible in `workflow detail` → `result[].error`). Submit with
+> `--backup=false` to skip backups, or have a DBA configure the backup database.
+
 ### Audit (approve or reject) a workflow
 
 ```bash