docs: clarify success envelope contract — judge success by ok, not code

[spacegeologist]

Summary

The stdout success envelope is {ok, identity, data, meta?} and carries no top-level code/msg field, but the docs never state this. Wrappers following the raw OpenAPI convention ({"code": 0, "msg": "ok"}) test code == 0, misclassify every successful call as a failure, and around write commands this defeats caller-side idempotency and causes duplicate creates — exactly the incident described in #1689.

Changes

• errs/ERROR_CONTRACT.md: add a Success envelope (stdout) subsection next to the error wire format, stating the shape, that code exists only inside error (invariant 4), and why code == 0 checks are unsafe.
• README.md / README.zh.md: add a JSON Output Contract section under Advanced Usage showing both envelopes side by side and the ok == true rule.
• skills/lark-shared/SKILL.md: add a JSON 输出契约 section, since every skill reference lists lark-shared as a prerequisite — this covers all write-type skills in one place.
• skills/lark-task/references/lark-task-create.md: add a concrete success response example (data.guid / data.url, matching shortcuts/task/shortcuts.go CreateTask output) and change the "Report the result" step to judge success by ok.

Docs-only; no behavior change. The issue's optional code-side suggestion (adding code: 0 or status to the success envelope) is left out deliberately — the maintainer reply on #1689 scoped this to documentation.

Test Plan

• Docs-only change; make unit-test unaffected (no Go changes)
• Verified the documented success shape against internal/output/envelope.go (Envelope struct) and shortcuts/task/shortcuts.go (CreateTask outputs {guid, url})

Related Issues

• Closes 文档/契约：成功响应应明确用 ok 而非 code 判断，避免封装者误判导致重复创建等副作用 #1689

Summary by CodeRabbit

• Documentation
  • Clarified the CLI “JSON output contract” with distinct success (stdout) and error (stderr) envelopes.
  • Documented success detection via ok == true (and/or exit code 0), warning that code == 0 is unreliable.
  • Specified where fields like error and its upstream numeric code appear, and linked to the full error taxonomy.
  • Updated task creation docs to use ok == true and added a success JSON example.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation updates define the JSON output contract for --format json, clarifying success and error envelope shapes, stdout/stderr and exit-code behavior, and that success must be detected with ok == true rather than code == 0.

Changes

JSON output contract documentation

Layer / File(s)	Summary
README and error contract updates README.md, README.zh.md, errs/ERROR_CONTRACT.md	Adds JSON output contract sections that define success and error envelope shapes, stdout/stderr separation, exit-code expectations, and the rule that successful responses do not use top-level code or msg.
Skill documentation and task-create example skills/lark-shared/SKILL.md, skills/lark-task/references/lark-task-create.md	Adds JSON output contract guidance to the shared skill docs and updates the task-create workflow to check ok == true, report data.guid, and show a success example envelope.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• larksuite/cli#144: Updates the same JSON envelope contract, including ok and error.code.
• larksuite/cli#1598: Also updates skills/lark-shared/SKILL.md around JSON output contract behavior.

Suggested reviewers: albertnusouo

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The docs updates satisfy #1689 by documenting the success envelope, ok-based success checks, and a write-flow example.
Out of Scope Changes check	✅ Passed	All changes are documentation-only and directly support the requested contract clarification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly summarizes the docs-only change to clarify that success is determined by ok, not code.
Description check	✅ Passed	The description follows the template with Summary, Changes, Test Plan, and Related Issues, and it is specific and complete enough.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Around line 240-246: The README JSON example is using a plain json fence even
though the snippet contains // annotations, which makes the sample invalid JSON.
Update the documentation block to use a jsonc fence or move the explanatory
comments outside the fenced block, keeping the success/error examples associated
with the contract while making the sample copy-paste valid.

In `@README.zh.md`:
- Around line 241-247: The README.zh.md example block is labeled as JSON but
contains inline `//` annotations, which makes it invalid JSON. Update the
documentation sample around the JSON response examples to use a `jsonc` fence or
move the explanatory comments outside the fenced block, keeping the `ok`,
`identity`, `data`, and `error` examples valid and copy-pasteable.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 25e3b6ee-d105-43ec-ae9f-9cbbcf11efd6

📥 Commits

Reviewing files that changed from the base of the PR and between c2d6038 and d46e961.

📒 Files selected for processing (5)

• README.md
• README.zh.md
• errs/ERROR_CONTRACT.md
• skills/lark-shared/SKILL.md
• skills/lark-task/references/lark-task-create.md

[spacegeologist]

Both findings were already addressed in 54c844c (the current head, force-pushed shortly after the review ran on d46e961): the // annotations were moved out of the fenced blocks into prose lines, so the json fences now contain pure, copy-paste-valid JSON.

@coderabbitai resolve

[coderabbitai]

@spacegeologist Thanks for the update — moving the // annotations out of the fenced blocks into prose lines is the right fix, since it keeps the json code fences as pure, valid JSON that can be copy-pasted directly. Resolving now.

✅ Action performed

Comments resolved. Approval is disabled; enable reviews.request_changes_workflow to allow explicit top-level @coderabbitai resolve or @coderabbitai approve commands.

[github-actions]

PR Quality Summary

CI did not complete successfully. Use the failed check links below to decide whether this PR needs a code change or a rerun.

Failed checks

• deterministic-gate — failure — details
• results — failure — details

deterministic-gate

• public_content_provenance_marker — pull_request_metadata:25 — public contribution contains a prohibited provenance marker — Action: remove the value from the public contribution and replace it with a non-sensitive placeholder

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@54c844c29f301e879c73ca9995e1369045ecead6

🧩 Skill update

npx skills add spacegeologist/cli#docs/success-envelope-contract -y -g