@fateforge/wechat-mp-cli 1.0.3

package/docs/LIVE-SMOKE-EVIDENCE.md

@@ -0,0 +1,195 @@
+# Live Smoke Evidence
+
+Recorded live smoke for `release_readiness.required_evidence:
+recorded_live_smoke_for_stable`, run against the **real WeChat Official
+Account API** (`https://api.weixin.qq.com`).
+
+- **Date:** 2026-06-14
+- **Target:** a WeChat Official Account **sandbox/test account** (测试号).
+  The AppID and AppSecret are intentionally **not** recorded here; only
+  aggregate pass/fail. Credentials were supplied via the
+  `WECHAT_MP_CLI_APP_ID` / `WECHAT_MP_CLI_APP_SECRET` environment variables.
+- **Method:** each command invoked with `--format json`; envelope `ok`/`error`
+  asserted. The one real write was a temporary material upload, which WeChat
+  auto-expires in 3 days — no cleanup required.
+
+## 2026-06-14 — v1.0.2 new commands (live)
+
+Verified against the same test account (aggregate only):
+
+| Command | Result | Notes |
+|---|---|---|
+| `qrcode create --scene-str … --expire-seconds 60` (dry-run → confirm) | PASS | returned ticket + `showqrcode_url` |
+| `tag create` / `tag get` / `tag update` / `tag delete` (dry-run → confirm) | PASS | full CRUD; created tag id 100, updated, then deleted (cleaned up) |
+| `user list` | PASS | `total: 0`, `next_openid: ""` — correct empty result (test account has no followers) |
+| `menu addconditional --file … --dangerous` (dry-run) | PASS | preview generated; not confirmed to avoid leaving persistent conditional-menu state |
+| `user info <openid>` · `tag members` · `tag tagging`/`untagging` | implemented, mock-verified | **not live-exercisable on the test account** — these need real followers, which the 测试号 has none of. The commands authenticate and call the real endpoints correctly; only follower data is unavailable in the sandbox. |
+
+All v1.0.2 new commands are implemented + mock-verified; the follower-dependent ones are honestly noted as not exercisable on an empty test account.
+
+## 2026-06-15 — batch commands (dry-run / contract only)
+
+New batch surface: `message mass sendall` / `mass send --openids` / `mass preview`
+/ `mass get` / `mass delete`, and `user info-batch`.
+
+**Environment for this round: no live WeChat credentials were available**
+(`doctor` → `account_config: warn (no account configured)`, no
+`WECHAT_MP_CLI_APP_ID`/`_APP_SECRET`), and per the safety policy
+broadcast/irreversible batches are **dry-run only at night** regardless. So no
+real broadcast, preview-send, recall, or follower read was executed against the
+live API. Verification was done **offline against the built binary** (validation
+/ gate / envelope / single-use confirm) plus the **mock-upstream e2e suite**
+(per-item aggregation, replay-conflict through a real send to the mock).
+Aggregate pass/fail only — no openids, msg_ids, tokens, or secrets recorded.
+
+| Command | Result | Method |
+|---|---|---|
+| `message mass sendall` | dry-run only | binary: critical `--dangerous` double-gate enforced; `--dry-run` issues a confirm token (not executed); audience guard (`--to-all` xor positive `--tag-id`) and body guard (exactly one of `--text`/`--mpnews-media-id`) both return `E_VALIDATION`. **Not real-machine executed** (no creds + night policy). |
+| `message mass send --openids` | dry-run only | binary: critical gate enforced; plural `--openids` (comma + repeated) de-duped, input order preserved, blast-radius `total`/`targets` shown in preview; empty list and dual-body → `E_VALIDATION`. **Not real-machine executed.** |
+| `message mass preview` | dry-run only | binary: high-risk gate enforced; `--dry-run` confirm token issued; missing recipient (`--openid`/`--towxname`) → `E_VALIDATION`. Sends one real message when confirmed, so **not executed** (no creds). |
+| `message mass delete` | dry-run only | binary: critical gate enforced; `--dry-run` token issued (not executed); `--msg-id ≤ 0` → `E_VALIDATION`. Irreversible recall → **dry-run only, never real-machine executed.** |
+| `message mass get` | not tested (live) | binary: `--msg-id ≤ 0` → `E_VALIDATION` before any call; valid id with no creds → `E_CONFIG` (validation precedence confirmed). Live read **not tested** — needs a real `msg_id` + credentials. Read path mock-verified. |
+| `user info-batch` | dry/structure only | binary: empty `--openids` → `E_VALIDATION`; populated list with no creds → `E_CONFIG` (validation + plural parse precede the call). Per-item aggregation (`items[]` keyed by openid, de-dupe, `_untrusted`, `summary` total/succeeded/failed) **mock-verified** in e2e. Live read **not tested** — needs real followers. |
+
+### Contract points exercised this round
+
+| Contract point | Result | Method |
+|---|---|---|
+| Single-use confirm token (replay rejected) | PASS | binary: dry-run → first `--confirm` consumes token (then `E_CONFIG`, no creds) → replay returns `E_CONFLICT` "token already used". Also mock e2e `TestBatch_MassSendConfirmThenReplayConflict`. |
+| `--dangerous` second gate (high/critical) | PASS | binary: every critical (`sendall`/`send`/`delete`) and high (`preview`) command blocks with `E_CONFIRMATION_REQUIRED` when `--dangerous` is absent. |
+| Partial-failure aggregation shape | PASS | mock e2e `TestBatch_InfoBatchAggregatesPerItem`: 3 inputs incl. one non-follower → `succeeded:2 / failed:1`, item order preserved, ghost item carries `E_NOT_FOUND`. |
+
+No real broadcast, recall, preview-send, or follower read was performed. The
+irreversible/broadcast batches (`mass sendall`, `mass send`, `mass delete`) were
+**dry-run verified, never real-machine executed**, per the safety policy.
+
+## 2026-06-15 — batch commands (real credentials, live probe)
+
+Re-run of the batch surface **with real test-account credentials present** this
+time (supplied via `WECHAT_MP_CLI_APP_ID` / `WECHAT_MP_CLI_APP_SECRET` env vars
+only — never written to any file, commit, or this document). Built from branch
+`smoke/batch-2026-06-15` source (`go build`); the globally installed v1.0.2 has
+no batch commands.
+
+- **Account state:** `user list` → `total: 0`, `next_openid: ""`. The test
+  account still has **zero followers**, so follower-dependent reads have no live
+  data and broadcasts have no recipients (non-polluting by construction).
+- **AppID/AppSecret are intentionally not recorded.** Only aggregate pass/fail,
+  WeChat return codes, and exit codes — no openids, msg_ids, tokens, or secrets.
+
+### Live API probe results (real round-trips)
+
+Each command was driven to a **real** `api.weixin.qq.com` call to observe the
+genuine upstream return code per the test account's permission grant.
+
+| Command | Classification | Live result |
+|---|---|---|
+| `user info-batch --openids` | **live** | Real batchget call; invalid openids → upstream `40003` mapped per-item to `E_VALIDATION`; `items[]`/`summary` aggregated correctly (see below). |
+| `message mass sendall --to-all` | **live, permission OK** | Real call returned `errcode:0` "send job submission success" + a sandbox `msg_id`. Test account **has** sendall permission; 0 followers → no recipients reached. |
+| `message mass send --openids` | **live, permission restricted (48001)** | Real call returned WeChat `48001 api unauthorized` → `E_FORBIDDEN`, exit 4. **Openid-list mass send is not authorized on the test account.** |
+| `message mass preview` | **live, permission OK** | Real call returned `40003 invalid openid` (not 48001) → `E_VALIDATION`. The API accepted the request and only rejected the synthetic openid; preview permission is present. |
+| `message mass get --msg-id` | **live** | Real call with a bogus id returned `40059 invalid msg id` → `E_VALIDATION`. Read permission present. |
+| `message mass delete --msg-id` | **live** | Real call with a bogus id returned `40059 invalid msg id` → `E_VALIDATION`. Delete reached real API; only the bogus id was rejected. No real message recalled. |
+
+**Permission summary:** on this test account only the **openid-list `mass send`**
+returned `48001 api unauthorized`. `sendall`, `preview`, `get`, and `delete` all
+reached genuine API behavior (`errcode:0` or content-level errors), so they are
+**not** permission-restricted here.
+
+### user info-batch aggregation (live)
+
+Input `--openids o_fake_BBB,o_fake_AAA,o_fake_BBB --openids o_fake_AAA,o_fake_CCC`
+resolved to exactly `[BBB, AAA, CCC]` — **de-duplicated, input order preserved**.
+All three failed at the live batchget call (`40003`); the chunk-level error
+mapped onto **every item** as `E_VALIDATION`, `summary{total:3,succeeded:0,failed:3}`
+(counts equal the item tally), and the envelope carried `_untrusted:["items"]`.
+**Success path (live, 2026-06-15 — owner scanned the test-account QR to follow):**
+one real follower openid → `summary{total:1,succeeded:1,failed:0}`, `item.ok=true`
+with the full subscriber profile (nickname / openid / subscribe_time / tagid_list /
+remark / sex / … 17 fields) and `_untrusted` present. De-dupe + partial-failure in one
+call: real openid ×2 + one bogus → `total:2` (folded), `succeeded:1/failed:1`, per-item
+`[true,false]`. (No real openid/nickname values are recorded in this document.) The
+`E_NOT_FOUND` ghost-item path remains mock-verified.
+
+### Guards & gating (real creds present, so gates run for real)
+
+| Contract point | Result | Method |
+|---|---|---|
+| `--dangerous` second gate (critical `sendall`) | PASS | Without `--dangerous`: `E_CONFIRMATION_REQUIRED`, exit 5. With `--dangerous --dry-run`: confirm token + `expires_at` issued. |
+| Single-use confirm replay | PASS | `send` confirm token consumed by first call (token burned **before** the write, so even the 48001 failure consumed it); replay → `E_CONFLICT`, exit 6. |
+| Audience guard — neither `--to-all` nor `--tag-id` | PASS | `E_VALIDATION` "set --to-all or a positive --tag-id", exit 2. |
+| Audience guard — `--to-all` **and** `--tag-id` together | **PASS (fixed 2026-06-15, commit f2dcbef)** | Now rejected: both set → `E_VALIDATION` "mutually exclusive: set exactly one", exit 2. Originally an observed gap (`--to-all` silently won); fixed via XOR validation + unit test `TestResolveSendAllFilterXOR`. |
+| Body guard — no body | PASS | `E_VALIDATION` "a message body is required", exit 2. |
+| Body guard — both `--text` and `--mpnews-media-id` | PASS | `E_VALIDATION` "set only one of …", exit 2. |
+| `mass get` / `info-batch` validation precedence | PASS | `--msg-id 0` and empty `--openids` → `E_VALIDATION` before any API call. |
+| Dry-run envelopes (all batch cmds) | PASS | `send`/`preview`/`delete`/`sendall` dry-run all emit `operation` + `preview` + `confirm_token` + `expires_at`; `send` preview shows de-duped `targets[]` + `total`. |
+
+### Honest classification per command
+
+| Command | Grade |
+|---|---|
+| `user info-batch` | **live** (validation + per-item aggregation + **success path** against a real follower, 2026-06-15) |
+| `message mass sendall` | **live**, permission OK (0 followers → no recipients) |
+| `message mass send` | **live**, **permission restricted (48001)** |
+| `message mass preview` | **live**, permission OK (only synthetic openid rejected) |
+| `message mass get` | **live** |
+| `message mass delete` | **live** (real API reached; only bogus id rejected) |
+
+One gap found this round: `mass sendall` does not reject `--to-all` + `--tag-id`
+supplied together (see guards table). No test account pollution occurred.
+
+## Result by class
+
+### Auth + token — PASS
+| Command | Result |
+|---|---|
+| `doctor` | PASS (config + account credentials OK) |
+| `token refresh` (stable_token) | PASS — real access token, `expires_in: 7200` |
+| `token status` | PASS |
+
+### Reads — PASS
+| Command | Result |
+|---|---|
+| `asset count` | PASS |
+| `asset list --type image` | PASS |
+| `draft count` | PASS |
+| `draft list` | PASS |
+| `menu get` | PASS |
+| `draft switch status` | PASS |
+
+`asset list` output carries `_untrusted` markers for WeChat-controlled fields.
+
+### Write safety + real execution — PASS
+| Step | Result |
+|---|---|
+| `menu delete` without `--confirm` | blocked (`E_CONFIRMATION_REQUIRED`) |
+| `menu delete --dry-run` without `--dangerous` | blocked: "high risk and requires --dangerous in both steps" (T2 double gate) |
+| `menu delete --dangerous --dry-run` | confirm token issued, **not executed** |
+| `asset temp upload --type image --dangerous` (dry-run → confirm) | **real temporary material created** (media_id returned); auto-expires in 3 days |
+
+### Error taxonomy — PASS
+| Path | Result |
+|---|---|
+| `asset list --type <invalid>` | `E_VALIDATION` |
+| any write without `--confirm` | `E_CONFIRMATION_REQUIRED` |
+
+## Notes
+
+- This run used the WeChat sandbox/test account; its token, material, draft,
+  and menu endpoints are all live. A few advanced endpoints are restricted on
+  test accounts, but the core token / asset / draft / menu surface — including
+  the stable_token lifecycle and the T2 `--dangerous` write gate — is exercised
+  end-to-end here.
+- No defects were found in this run.
+
+## Reproduce
+
+```bash
+export WECHAT_MP_CLI_APP_ID=<appid>
+export WECHAT_MP_CLI_APP_SECRET=<secret>
+wechat-mp-cli doctor --compact
+wechat-mp-cli token refresh --compact
+wechat-mp-cli asset count --compact
+wechat-mp-cli asset temp upload --type image --dangerous cover.png --dry-run --compact
+wechat-mp-cli asset temp upload --type image --dangerous cover.png --confirm <token> --compact
+```

package/docs/OFFICIAL_ENDPOINT_COVERAGE.md

@@ -0,0 +1,42 @@
+# Official WeChat Endpoint Coverage
+
+This document maps `wechat-mp-cli` commands to the official WeChat Official Account documentation checked on 2026-06-12.
+
+## Sources
+
+- Draft box: <https://developers.weixin.qq.com/doc/offiaccount/Draft_Box/Add_draft.html>
+- Publish: <https://developers.weixin.qq.com/doc/offiaccount/Publish/Publish.html>
+- Comments: <https://developers.weixin.qq.com/doc/service/guide/product/comments.html>
+- Analytics: <https://developers.weixin.qq.com/doc/offiaccount/Analytics/Graphic_Analysis_Data_Interface.html>
+- Materials: <https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html>
+
+## Covered Article Workflow
+
+| Official area | Endpoints | CLI commands |
+| --- | --- | --- |
+| Drafts | `/cgi-bin/draft/switch`, `/add`, `/update`, `/count`, `/batchget`, `/get`, `/delete` | `draft switch status/enable`, `draft create/update/count/list/get/delete` |
+| Publish | `/cgi-bin/freepublish/submit`, `/get`, `/batchget`, `/getarticle`, `/delete` | `publish submit/status/list/get-article/delete` |
+| Comments | `/cgi-bin/comment/open`, `/close`, `/list`, `/markelect`, `/unmarkelect`, `/delete`, `/reply/add`, `/reply/delete` | `comment open/close/list/mark/unmark/delete/reply-add/reply-delete` |
+| Article analytics | `/datacube/getarticlesummary`, `/getarticletotal`, `/getuserread`, `/getuserreadhour`, `/getusershare`, `/getusersharehour`, `/getarticleread`, `/getarticleshare`, `/getbizsummary`, `/getarticletotaldetail` | `analytics article ...` |
+| User analytics | `/datacube/getusersummary`, `/getusercumulate` | `analytics user summary/cumulate` |
+| Materials used by articles | `/cgi-bin/media/uploadimg`, `/cgi-bin/material/add_material`, `/get_material`, `/get_materialcount`, `/batchget_material`, `/del_material` | `image upload`, `asset count/list/get/delete` |
+| Temporary media | `/cgi-bin/media/upload`, `/get`, `/get/jssdk` | `asset temp upload/get/get-hd-voice` |
+| Menu | `/cgi-bin/menu/create`, `/delete`, `/get_current_selfmenu_info`, `/addconditional` | `menu set/delete/get/addconditional` |
+| Account QR codes | `/cgi-bin/qrcode/create` | `qrcode create` |
+| Followers | `/cgi-bin/user/info`, `/cgi-bin/user/get` | `user info/list` |
+| Follower tags | `/cgi-bin/tags/create`, `/get`, `/update`, `/delete`, `/cgi-bin/user/tag/get`, `/cgi-bin/tags/members/batchtagging`, `/batchuntagging` | `tag create/get/update/delete/members/tagging/untagging` |
+
+## Intentional Boundaries
+
+The CLI does not claim to cover every Official Account API. Current scope is the article production and publication workflow plus adjacent diagnostics.
+
+Not yet implemented from the checked analytics page:
+
+- Message analytics: `/datacube/getupstreammsg*`.
+- Passive reply/interface analytics: `/datacube/getinterfacesummary`, `/datacube/getinterfacesummaryhour`.
+
+Not yet implemented from the checked draft page:
+
+- Product card DOM endpoint: `/channels/ec/service/product/getcardinfo`.
+
+These are useful future extensions, but they are not required for the core article draft, publish, comment, material, and article analytics path.

package/docs/OFFICIAL_ENDPOINT_COVERAGE_zh.md

@@ -0,0 +1,42 @@
+# 微信官方端点覆盖说明
+
+本文档记录 `wechat-mp-cli` 与微信官方公众号文档的端点对照。检查日期：2026-06-12。
+
+## 来源
+
+- 草稿箱：<https://developers.weixin.qq.com/doc/offiaccount/Draft_Box/Add_draft.html>
+- 发布：<https://developers.weixin.qq.com/doc/offiaccount/Publish/Publish.html>
+- 留言管理：<https://developers.weixin.qq.com/doc/service/guide/product/comments.html>
+- 数据统计：<https://developers.weixin.qq.com/doc/offiaccount/Analytics/Graphic_Analysis_Data_Interface.html>
+- 素材管理：<https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html>
+
+## 已覆盖的文章主链路
+
+| 官方领域 | 端点 | CLI 命令 |
+| --- | --- | --- |
+| 草稿 | `/cgi-bin/draft/switch`, `/add`, `/update`, `/count`, `/batchget`, `/get`, `/delete` | `draft switch status/enable`, `draft create/update/count/list/get/delete` |
+| 发布 | `/cgi-bin/freepublish/submit`, `/get`, `/batchget`, `/getarticle`, `/delete` | `publish submit/status/list/get-article/delete` |
+| 留言 | `/cgi-bin/comment/open`, `/close`, `/list`, `/markelect`, `/unmarkelect`, `/delete`, `/reply/add`, `/reply/delete` | `comment open/close/list/mark/unmark/delete/reply-add/reply-delete` |
+| 图文/发表内容数据 | `/datacube/getarticlesummary`, `/getarticletotal`, `/getuserread`, `/getuserreadhour`, `/getusershare`, `/getusersharehour`, `/getarticleread`, `/getarticleshare`, `/getbizsummary`, `/getarticletotaldetail` | `analytics article ...` |
+| 用户数据 | `/datacube/getusersummary`, `/getusercumulate` | `analytics user summary/cumulate` |
+| 文章相关素材 | `/cgi-bin/media/uploadimg`, `/cgi-bin/material/add_material`, `/get_material`, `/get_materialcount`, `/batchget_material`, `/del_material` | `image upload`, `asset count/list/get/delete` |
+| 临时素材 | `/cgi-bin/media/upload`, `/get`, `/get/jssdk` | `asset temp upload/get/get-hd-voice` |
+| 自定义菜单 | `/cgi-bin/menu/create`, `/delete`, `/get_current_selfmenu_info`, `/addconditional` | `menu set/delete/get/addconditional` |
+| 账号二维码 | `/cgi-bin/qrcode/create` | `qrcode create` |
+| 粉丝 | `/cgi-bin/user/info`, `/cgi-bin/user/get` | `user info/list` |
+| 粉丝标签 | `/cgi-bin/tags/create`, `/get`, `/update`, `/delete`, `/cgi-bin/user/tag/get`, `/cgi-bin/tags/members/batchtagging`, `/batchuntagging` | `tag create/get/update/delete/members/tagging/untagging` |
+
+## 有意保留的边界
+
+本 CLI 不声明覆盖公众号全部 OpenAPI。当前范围是文章生产、发布、评论、素材和文章数据统计主链路，以及相邻的诊断能力。
+
+本轮检查到但暂未实现的数据统计端点：
+
+- 消息数据：`/datacube/getupstreammsg*`。
+- 被动回复/接口数据：`/datacube/getinterfacesummary`, `/datacube/getinterfacesummaryhour`。
+
+本轮检查到但暂未实现的草稿相关端点：
+
+- 商品卡片 DOM：`/channels/ec/service/product/getcardinfo`。
+
+这些可以作为后续扩展，但不影响当前草稿、发布、留言、素材和文章统计主链路的完整性。

package/docs/OPEN_SOURCE_CHECKLIST.md

@@ -0,0 +1,60 @@
+# Open-Source Checklist
+
+[English](OPEN_SOURCE_CHECKLIST.md) | [中文](OPEN_SOURCE_CHECKLIST_zh.md)
+
+Run through this gate **before the first public push** of `wechat-mp-cli`. It is a security and quality checkpoint, not documentation — every box must be ticked (or consciously waived with a note) before the repo goes public. Once public, secrets in history cannot be un-leaked.
+
+## Secrets
+
+- [ ] No credentials, tokens, API keys, or passwords anywhere in the working tree.
+- [ ] No secrets in **git history** — checked with a scanner (e.g. `gitleaks detect`, `git log -p | grep`); if found, the history is rewritten or the repo re-created, not just deleted from `HEAD`.
+- [ ] No internal hostnames, private IPs, internal URLs, or employer-internal identifiers in code, config, or comments.
+- [ ] Test fixtures and recorded responses contain only synthetic / redacted data — no real account data, no real tokens.
+- [ ] `.env`, `*.local`, credential files, and `~/.wechat-mp-cli/` artifacts are listed in `.gitignore` and confirmed untracked (`git status --ignored`).
+- [ ] Credentials are stored encrypted at rest (OS keyring or encrypted envelope, `0600`), never plaintext in the config file.
+
+## Docs
+
+- [ ] `README.md` follows the REPO-SPEC §2 skeleton (Title/badges → Agent Install → What It Does → Capabilities → Agent Workflow → Machine Contract → Configuration → Project Structure → Development → Links).
+- [ ] `README.md` and `README_zh.md` are **content-synced** — same sections, same commands, same placeholders resolved to the same real values.
+- [ ] `CHANGELOG.md` exists, uses Keep a Changelog format, and has an `## [Unreleased]` section on top.
+- [ ] `LICENSE` is present, the license is chosen deliberately (default MIT), and `2026` / `Sean Guo` are filled in.
+- [ ] Install blocks are copy-paste-runnable and use the real published `@fateforge/wechat-mp-cli` / `fatecannotbealtered/wechat-mp-cli`.
+
+## Governance
+
+- [ ] `SECURITY.md` is present with a working disclosure channel (`security@example.com`) and a supported-versions table.
+- [ ] `CONTRIBUTING.md` is present (env setup, branch/commit, test, PR flow).
+- [ ] `CODE_OF_CONDUCT.md` is present (Contributor Covenant) if the project accepts external contributions.
+- [ ] If `wechat-mp-cli` wraps a third-party product (WeChat Official Account), `NOTICE.md` carries the trademark / non-affiliation notice and `docs/COMPATIBILITY.md` lists the verified backend version matrix.
+
+## Build / CI
+
+- [ ] CI (`.github/workflows/ci.yml`) is **green** on the commit being pushed.
+- [ ] CI **enforces** lint and tests — a red lint or failing test blocks merge (not advisory-only).
+- [ ] Functional Contract Coverage is 100%: every public behavior documented in README, Skill, `reference`, `--help`, `context`, `doctor`, `changelog`, or `update` has automated command-level tests.
+- [ ] `reference.release_readiness.level` is accurate: `stable` has FCC 100%, mock upstream/contract tests, and recorded live smoke/E2E evidence; missing live evidence is `beta`; missing command-level coverage is `unpublishable`.
+- [ ] `doctor` includes a `release_readiness` check whose status matches the declared release level.
+- [ ] The formatter config is committed (ruff / golangci-lint / prettier, by language) and CI runs the format check.
+- [ ] No build artifacts, caches, venvs, or IDE config are committed (covered by `.gitignore`).
+
+## Distribution
+
+- [ ] `package.json` `version` matches the git tag being released (`vX.Y.Z` ↔ `X.Y.Z`); `release.yml` guards this and fails on mismatch.
+- [ ] The binary itself (`bin/`, `*.exe`, `dist/`) is **not committed** — it is produced by CI and gitignored.
+- [ ] GitHub Release artifacts ship a `checksums.txt`; standalone binary install/update paths verify the checksum and **fail closed** on mismatch or missing entries.
+- [ ] Release pipeline signs `checksums.txt` with Sigstore/Cosign keyless signing, publishes the bundle, and standalone install/update paths report signature verification status separately from checksum verification.
+- [ ] npm distribution publishes the main wrapper package plus every supported OS/CPU platform package from CI-built artifacts, with `npm publish --provenance`.
+- [ ] The version number has a single source of truth; the runtime `changelog` command and the GitHub Release body are derived from `CHANGELOG.md`, not hand-copied.
+
+## AI-native
+
+- [ ] Root `AGENTS.md` is present and points to `.agent/AGENT.md`.
+- [ ] `.agent/{AGENT,CLI-SPEC,SKILL-SPEC,SEC-SPEC}.md` specs are present; the shared repo skeleton standard is referenced from `ai-native-cli-spec/REPO-SPEC.md`.
+- [ ] `skills/wechat-mp-cli/SKILL.md` is present; frontmatter includes `version`, `license: MIT`, `user-invocable: true`, and `metadata.requires.min_version` matching the CLI version.
+- [ ] `SKILL.md` includes `When to use`, `Do not use`, `First Step`, agent defaults, JSON contract, write recipe or explicit read-only boundary, `STOP CHECKPOINT`, error decision tree, security boundary, self-update, and eval scenarios.
+- [ ] `skills/wechat-mp-cli/test-prompts.json` is present, valid JSON, and covers fresh-agent read, write safety or read-only boundary, permission boundary, `_untrusted` handling, and self-update.
+- [ ] `update --confirm` syncs the whole `skills/wechat-mp-cli/` directory or returns a `skill_sync_command` equivalent to `npx skills add fatecannotbealtered/wechat-mp-cli -y -g`.
+- [ ] `wechat-mp-cli reference`, `wechat-mp-cli context`, and `wechat-mp-cli doctor` run and emit valid JSON envelopes — an agent can self-onboard from a clean checkout.
+- [ ] `wechat-mp-cli reference` exposes `release_readiness`, and `wechat-mp-cli doctor` reports the matching check.
+- [ ] The risk tier in `SECURITY.md` matches the tier declared in `.agent/SEC-SPEC.md` (`T2`).

package/docs/OPEN_SOURCE_CHECKLIST_zh.md

@@ -0,0 +1,60 @@
+# 开源检查清单
+
+[English](OPEN_SOURCE_CHECKLIST.md) | [中文](OPEN_SOURCE_CHECKLIST_zh.md)
+
+在 `wechat-mp-cli` **首次公开推送之前**逐项走查。这是一道安全与质量关卡，不是文档 —— 仓库公开前每一项都必须勾选（或明确写明理由后豁免）。一旦公开，历史中泄露的密钥就无法收回。
+
+## 密钥
+
+- [ ] 工作区任何位置都没有凭据、token、API key 或密码。
+- [ ] **git 历史**中没有密钥 —— 已用扫描工具检查（如 `gitleaks detect`、`git log -p | grep`）；若发现，需重写历史或重建仓库，而不是只从 `HEAD` 删除。
+- [ ] 代码、配置、注释中没有内部主机名、内网 IP、内部 URL 或公司内部标识符。
+- [ ] 测试夹具和录制的响应只含合成 / 脱敏数据 —— 没有真实账户数据，没有真实 token。
+- [ ] `.env`、`*.local`、凭据文件以及 `~/.wechat-mp-cli/` 产物已列入 `.gitignore` 并确认未被跟踪（`git status --ignored`）。
+- [ ] 凭据静态加密存储（操作系统钥匙串或加密信封，`0600`），绝不以明文写入配置文件。
+
+## 文档
+
+- [ ] `README.md` 遵循 REPO-SPEC §2 骨架（标题/徽章 → Agent 安装 → 它做什么 → 能力 → Agent 工作流 → 机器契约 → 配置 → 项目结构 → 开发 → 链接）。
+- [ ] `README.md` 与 `README_zh.md` **内容同步** —— 章节一致、命令一致、占位符解析为相同的真实值。
+- [ ] `CHANGELOG.md` 存在，使用 Keep a Changelog 格式，顶部有 `## [Unreleased]` 小节。
+- [ ] `LICENSE` 存在，许可证经过有意选择（默认 MIT），`2026` / `Sean Guo` 已填写。
+- [ ] 安装块可直接复制运行，使用真实已发布的 `@fateforge/wechat-mp-cli` / `fatecannotbealtered/wechat-mp-cli`。
+
+## 治理
+
+- [ ] `SECURITY.md` 存在，含可用的披露渠道（`security@example.com`）和受支持版本表。
+- [ ] `CONTRIBUTING.md` 存在（环境搭建、分支/提交、测试、PR 流程）。
+- [ ] 若项目接受外部贡献，`CODE_OF_CONDUCT.md` 存在（Contributor Covenant）。
+- [ ] 若 `wechat-mp-cli` 包装第三方产品（WeChat Official Account），`NOTICE.md` 载明商标 / 非隶属声明，且 `docs/COMPATIBILITY.md` 列出已验证的后端版本矩阵。
+
+## 构建 / CI
+
+- [ ] 待推送的提交上 CI（`.github/workflows/ci.yml`）为**绿色**。
+- [ ] CI **强制**执行 lint 和测试 —— lint 失败或测试失败会阻断合并（不仅仅是提示性的）。
+- [ ] 功能契约覆盖率为 100%：README、Skill、`reference`、`--help`、`context`、`doctor`、`changelog` 或 `update` 中记录的每个公开行为，都有自动化命令级测试。
+- [ ] `reference.release_readiness.level` 准确：`stable` 具备 FCC 100%、mock upstream / contract tests 和真实环境 smoke/E2E 记录；缺真实证据为 `beta`；缺命令级覆盖为 `unpublishable`。
+- [ ] `doctor` 包含 `release_readiness` 检查，且状态与声明的发布等级一致。
+- [ ] 格式化工具配置已提交（按语言：ruff / golangci-lint / prettier），且 CI 运行格式校验。
+- [ ] 没有提交构建产物、缓存、虚拟环境或 IDE 配置（已由 `.gitignore` 覆盖）。
+
+## 分发
+
+- [ ] `package.json` 的 `version` 与待发布的 git tag 一致（`vX.Y.Z` ↔ `X.Y.Z`）；`release.yml` 对此做守卫，不一致即失败。
+- [ ] 二进制本身（`bin/`、`*.exe`、`dist/`）**不提交** —— 由 CI 产出并被 gitignore。
+- [ ] GitHub Release 发布产物附带 `checksums.txt`；standalone 二进制安装/更新路径校验 checksum，且在不匹配或缺少条目时**失败关闭**。
+- [ ] release pipeline 使用 Sigstore/Cosign keyless 签署 `checksums.txt`，发布 bundle，standalone 安装/更新路径把签名验证状态与 checksum 校验分开报告。
+- [ ] npm 分发从 CI 构建产物发布主 wrapper 包和每个受支持 OS/CPU 的平台包，并使用 `npm publish --provenance`。
+- [ ] 版本号有唯一真相来源；运行时 `changelog` 命令和 GitHub Release 正文均派生自 `CHANGELOG.md`，而非手工复制。
+
+## AI 原生
+
+- [ ] 根目录 `AGENTS.md` 存在并指向 `.agent/AGENT.md`。
+- [ ] `.agent/{AGENT,CLI-SPEC,SKILL-SPEC,SEC-SPEC}.md` 规格文件齐全；共享仓库骨架标准引用 `ai-native-cli-spec/REPO-SPEC.md`。
+- [ ] `skills/wechat-mp-cli/SKILL.md` 存在；frontmatter 包含 `version`、`license: MIT`、`user-invocable: true`，且 `metadata.requires.min_version` 匹配 CLI 版本。
+- [ ] `SKILL.md` 包含 `When to use`、`Do not use`、`First Step`、Agent 默认规则、JSON contract、写操作配方或明确只读边界、`STOP CHECKPOINT`、错误决策树、安全边界、自更新和评估场景。
+- [ ] `skills/wechat-mp-cli/test-prompts.json` 存在、JSON 合法，并覆盖 fresh-agent read、写操作安全或只读边界、权限边界、`_untrusted` 处理和自更新。
+- [ ] `update --confirm` 同步整个 `skills/wechat-mp-cli/` 目录，或返回等价于 `npx skills add fatecannotbealtered/wechat-mp-cli -y -g` 的 `skill_sync_command`。
+- [ ] `wechat-mp-cli reference`、`wechat-mp-cli context`、`wechat-mp-cli doctor` 可运行并输出合法的 JSON 信封 —— 代理能从干净的检出自助上手。
+- [ ] `wechat-mp-cli reference` 暴露 `release_readiness`，`wechat-mp-cli doctor` 报告匹配的检查项。
+- [ ] `SECURITY.md` 中的风险等级与 `.agent/SEC-SPEC.md` 声明的等级一致（`T2`）。

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@fateforge/wechat-mp-cli",
+  "version": "1.0.3",
+  "description": "AI-native CLI for WeChat Official Account drafting, publishing, assets, comments, analytics, menus, users, and webhooks",
+  "keywords": [
+    "wechat",
+    "weixin",
+    "official-account",
+    "cli",
+    "ai-agent",
+    "publishing",
+    "content-workflow"
+  ],
+  "license": "MIT",
+  "author": "Sean Guo",
+  "homepage": "https://github.com/fatecannotbealtered/wechat-mp-cli#readme",
+  "bugs": {
+    "url": "https://github.com/fatecannotbealtered/wechat-mp-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fatecannotbealtered/wechat-mp-cli.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "wechat-mp-cli": "scripts/run.js"
+  },
+  "optionalDependencies": {
+    "@fateforge/wechat-mp-cli-darwin-arm64": "1.0.3",
+    "@fateforge/wechat-mp-cli-darwin-x64": "1.0.3",
+    "@fateforge/wechat-mp-cli-linux-arm64": "1.0.3",
+    "@fateforge/wechat-mp-cli-linux-x64": "1.0.3",
+    "@fateforge/wechat-mp-cli-win32-arm64": "1.0.3",
+    "@fateforge/wechat-mp-cli-win32-x64": "1.0.3"
+  },
+  "files": [
+    "scripts/run.js",
+    "skills/",
+    "README.md",
+    "README_zh.md",
+    "*_zh.md",
+    "LICENSE",
+    "NOTICE.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "AGENTS.md",
+    ".agent/",
+    "docs/"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/scripts/run.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+"use strict";
+
+// Thin forwarder: exec the binary shipped by the npm platform package.
+const { execFileSync } = require("child_process");
+const path = require("path");
+
+const rootPackage = require("../package.json");
+const toolName = Object.keys(rootPackage.bin || {})[0] || "wechat-mp-cli";
+const ext = process.platform === "win32" ? ".exe" : "";
+const platformKey = `${process.platform}-${process.arch}`;
+const platformPackage = `${rootPackage.name}-${platformKey}`;
+const optionalDependencies = rootPackage.optionalDependencies || {};
+
+if (!Object.prototype.hasOwnProperty.call(optionalDependencies, platformPackage)) {
+  console.error(
+    `${toolName} does not ship an npm platform package for ${platformKey}.\n` +
+    "Install a supported platform package or use the GitHub standalone binary."
+  );
+  process.exit(1);
+}
+
+let bin;
+try {
+  const platformPackageJson = require.resolve(`${platformPackage}/package.json`);
+  bin = path.join(path.dirname(platformPackageJson), "bin", toolName + ext);
+} catch {
+  console.error(
+    `${toolName} platform package ${platformPackage} is not installed.\n` +
+    "This usually means npm optional dependencies were omitted.\n" +
+    `Reinstall with:  npm install -g ${rootPackage.name} --include=optional`
+  );
+  process.exit(1);
+}
+
+try {
+  execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  if (e.code === "ENOENT") {
+    console.error(
+      `${toolName} binary not found inside ${platformPackage}.\n` +
+      `Reinstall with:  npm install -g ${rootPackage.name} --include=optional`
+    );
+  }
+  process.exit(e.status || 1);
+}