docs(cli): document npm install and release operations

[M4n5ter]

Summary

English

• Document npm installation, first-run provider setup, upgrades, uninstall behavior, local data, the validated platform matrix, and Eval prerequisites.
• Add the maintainer runbook for protected staging, npm 2FA approval, finalization, failure recovery, dist-tag rollback, and ownership recovery.
• Provide matching Simplified Chinese guides and ship the versioned Chinese CLI guide in the npm tarball.

Refs #3166

简体中文

• 补全 npm 安装、首次供应商配置、升级、卸载、本地数据、已验证平台矩阵和 Eval 前置条件说明。
• 增加受保护 Stage、npm 2FA 审批、Finalize、失败恢复、dist-tag 回滚和所有权恢复手册。
• 提供对应的简体中文文档，并将版本匹配的 CLI 中文指南收入 npm tarball。

关联 #3166

Verification

English

• npx --yes npm@11.19.0 run rebuild
• npx --yes npm@11.19.0 run check:release
• npx --yes npm@11.19.0 run release:cli:pack
• npx --yes npm@11.19.0 run release:cli:smoke
• Verified both packaged READMEs are byte-identical to their source documents and checked all changed relative Markdown links.

简体中文

• 完整构建、release 检查、clean-tree CLI pack 和安装态 smoke 均通过。
• 已确认 tarball 内的中英文 README 与源码逐字节一致，并检查了所有变更文档的相对链接。

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Codex drafted the bilingual documentation, updated the release document whitelist, and ran the reported validation.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 418b8dce-7f5c-460b-90f0-1fb5e5abec78

📥 Commits

Reviewing files that changed from the base of the PR and between 22069e7 and f852aa9.

📒 Files selected for processing (2)

• docs/cli-npm-release.md
• docs/cli-npm-release.zh-CN.md

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/cli-npm-release.md
• docs/cli-npm-release.zh-CN.md

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

What this PR solves

• Documents CLI installation, first-run setup, upgrades, uninstall data retention, local data, supported platforms, and Eval prerequisites.
• Adds equivalent English and Simplified Chinese CLI documentation.
• Adds a maintainer runbook for staged npm releases, toolchain requirements, 2FA approval, recovery, rollback, and ownership recovery.
• Packages the version-matched Chinese CLI guide in the npm tarball.
• Makes GitHub Release finalization retry-safe.
• Verifies release metadata, assets, sizes, and SHA-256 digests.

Source of truth and scope

This PR extends the existing README, CLI documentation, release documentation, and release tooling. It does not create a competing runtime or publishing path.

The release runbook becomes the operational source of truth for npm publishing. The Chinese documents provide the corresponding translated guidance. The workflow and validation command enforce the documented release controls.

The changes are the smallest coherent solution for the stated goals. Packaging support is required for the Chinese guide. Draft release recovery and exact asset verification are required for safe retries. The added tests cover the new release validation and workflow policy.

Simplification opportunities

No deletion or simplification is evident without reducing documentation coverage, release controls, packaging checks, or regression coverage.

Validation and risks

Validation covered:

• Rebuild and release checks.
• CLI packaging and smoke tests.
• README byte identity.
• Changed relative Markdown links.
• GitHub Release validation for metadata, assets, upload state, sizes, and SHA-256 digests.
• Workflow policy checks for draft creation, asset replacement, finalization, validation, and verifier-commit checkout.

The final status of required checks is unverified without direct check results.

Complexity delta

• Authorities: Adds the release runbook and maintains English/Chinese documentation parity.
• States: Adds Stage, approval, draft, Finalize, validation, rollback, failure recovery, and ownership recovery states.
• Branches: Adds retry and recovery paths for partial releases, defective versions, platform validation, and emergency recovery.
• Configuration: Documents GitHub Environment, npm Trusted Publisher, OIDC, 2FA, and minimum toolchain requirements.
• Public surface: Adds README links, a Chinese package README, and the validate-github-release command.
• Test-maintenance burden: Adds release metadata fixtures, digest checks, workflow policy assertions, and package-content expectations.

Total maintenance complexity increases. The increase is justified by stronger release safety, user guidance, and language support. No evidence indicates an unjustified increase.

Review-relevant risks

• Published npm package contents change because the Chinese README is added to the tarball.
• Release behavior changes because finalization creates or resumes draft GitHub Releases, verifies exact assets and digests, and controls prerelease status for next and latest.
• npm release governance changes because the runbook defines staged publishing, OIDC, 2FA approval, rollback, and ownership recovery.
• User-visible onboarding and troubleshooting guidance changes in both supported languages.
• The release workflow checks out the workflow commit before finalization, which affects the code used for release verification.

Material changes in these protected areas require independent human review under repository policy. The person performing the merge reviews the final diff, and a maintainer makes the final determination.

Walkthrough

The PR expands bilingual CLI documentation, defines npm release operations, validates GitHub Release artifacts, hardens Finalize workflow recovery, links the guides from repository documentation, and includes the Chinese README in staged npm packages.

Changes

CLI documentation and release publication

Layer / File(s)	Summary
CLI user guides packages/cli/README.md, packages/cli/README.zh-CN.md	Adds installation, setup, credentials, commands, upgrades, uninstall behavior, Eval prerequisites, troubleshooting, platform requirements, and project links.
Release controls and invariants docs/cli-npm-release.md, docs/cli-npm-release.zh-CN.md	Defines release invariants, GitHub Environment settings, Trusted Publisher configuration, OIDC publishing, approval, and 2FA requirements.
Staged release execution docs/cli-npm-release.md, docs/cli-npm-release.zh-CN.md, scripts/release-cli-publication.mjs, scripts/release-cli-publication.test.mjs, scripts/release-cli-workflow-policy.test.mjs, .github/workflows/release-cli-finalize.yml	Documents Stage and Finalize validation. The workflow recovers draft releases, uploads verified assets, publishes them, and validates final metadata and digests.
Release recovery and ownership docs/cli-npm-release.md, docs/cli-npm-release.zh-CN.md	Documents failed-stage recovery, defective-version handling, dist-tag and deprecation procedures, ownership responsibilities, emergency recovery, and references.
Documentation navigation and package inclusion README.md, README.zh-CN.md, docs/README.md, scripts/release-cli-package.mjs	Links the CLI and release guides from repository documentation. Includes README.zh-CN.md in staged documents, the npm manifest, and staging validation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to f852a

This PR adds bilingual CLI installation and release documentation alongside the related packaging and release updates; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant FinalizeWorkflow
  participant GitHubRelease
  participant ReleaseValidator
  FinalizeWorkflow->>GitHubRelease: create or recover draft release
  FinalizeWorkflow->>GitHubRelease: upload and publish verified assets
  FinalizeWorkflow->>ReleaseValidator: validate release metadata and digests
  ReleaseValidator-->>FinalizeWorkflow: return validated release record

Loading

Possibly related issues

• Publish the Maka CLI/TUI to npm as maka-agent #3166 — Directly covers the npm CLI publication plan implemented and documented by this PR.

Possibly related PRs

• maka-agent/maka-agent#3192 — Extends related CLI release workflows and publication validation.
• maka-agent/maka-agent#3173 — Introduces the CLI npm packaging and release workflow that this PR extends.
• maka-agent/maka-agent#3185 — Shares the scripts/release-cli-package.mjs packaging flow.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Ai Use Disclosure	⚠️ Warning	The PR discloses Codex and material documentation/code work, but commit 22069e7 has Generated-by: Codex embedded after literal \\n\\n, so no valid standalone trailer exists.	Amend or rewrite 22069e7 with a standalone Generated-by: Codex line, and ensure it survives squash or amend; see CONTRIBUTING.md section “Human ownership and AI attribution”.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary documentation changes for npm installation and release operations.
Description check	✅ Passed	The description includes the required summary, verification, AI-use disclosure, checklist, behavior declaration, and issue reference.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/cli-npm-release-readiness

---

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

[qodo-code-review]

PR Summary by Qodo

Document CLI npm usage and release operations

📝 Documentation ✨ Enhancement 🕐 40+ Minutes

AI Description

• Expand bilingual CLI guides for npm lifecycle, platforms, security boundaries, and Eval
 prerequisites.
• Add bilingual staged npm release runbooks covering approvals, finalization, rollback, and
 recovery.
• Include the Simplified Chinese CLI guide in validated npm release tarballs.

Diagram

sequenceDiagram
  actor Maintainer as Release Maintainer
  participant Stage as Stage Workflow
  participant NpmStage as npm Staging
  participant Registry as npm Registry
  participant Finalize as Finalize Workflow
  participant GitHub as GitHub Release
  Maintainer->>Stage: Dispatch version
  Stage->>NpmStage: Submit validated tarball
  Maintainer->>NpmStage: Inspect and approve
  NpmStage->>Registry: Publish immutable version
  Maintainer->>Finalize: Provide stage identity
  Finalize->>Registry: Verify release evidence
  Finalize->>GitHub: Create tag and release

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Host CLI guides externally

• ➕ Allows documentation updates without publishing a new package version.
• ➕ Avoids adding localized documentation to the npm tarball.
• ➖ Installed versions could link to instructions that no longer match their behavior.
• ➖ Users lose an offline, version-matched Simplified Chinese guide.
• ➖ External documentation availability becomes part of the installation experience.

Recommendation: Keep the PR's versioned bilingual guides in the package and the maintainer runbook in repository documentation. This separates user-facing package guidance from operational authority while preserving offline, release-matched instructions; byte-identity and packaging checks mitigate duplication and drift.

Files changed (8) +775 / -10

Enhancement (1) +11 / -1

release-cli-package.mjsPackage and validate the Chinese CLI guide +11/-1

Package and validate the Chinese CLI guide

• Copies README.zh-CN.md into the staged package, adds it to the release manifest, and requires it during staging validation. This ensures every published tarball contains the version-matched Chinese guide.

scripts/release-cli-package.mjs

Documentation (7) +764 / -9

README.mdDirect npm users to the packaged CLI guide +3/-0

Direct npm users to the packaged CLI guide

• Adds a link to the public npm installation guide and clarifies that the existing terminal commands run the development CLI from a source checkout.

README.md

README.zh-CN.mdLink Chinese readers to the npm CLI guide +3/-0

Link Chinese readers to the npm CLI guide

• Adds the corresponding Chinese CLI guide link and distinguishes public npm installation from source-checkout development commands.

README.zh-CN.md

README.mdIndex the CLI npm release runbook +4/-0

Index the CLI npm release runbook

• Adds a release operations section linking the English and Simplified Chinese npm release guides.

docs/README.md

cli-npm-release.mdDefine protected CLI npm release operations +229/-0

Define protected CLI npm release operations

• Introduces the authoritative maintainer runbook for OIDC trusted publishing, protected staging, npm 2FA approval, finalization, and evidence verification. It also documents failure handling, dist-tag rollback, ownership, and emergency recovery.

docs/cli-npm-release.md

cli-npm-release.zh-CN.mdProvide the Chinese npm release runbook +219/-0

Provide the Chinese npm release runbook

• Adds a Simplified Chinese counterpart covering the complete protected staging, approval, finalization, rollback, and ownership recovery process.

docs/cli-npm-release.zh-CN.md

README.mdExpand the npm CLI installation and lifecycle guide +149/-9

Expand the npm CLI installation and lifecycle guide

• Documents requirements, validated platforms, beta installation and upgrades, first-run provider setup, local credential boundaries, uninstall data retention, and troubleshooting. It also details external Harbor and Pier prerequisites for Eval usage.

packages/cli/README.md

README.zh-CN.mdAdd the Simplified Chinese CLI package guide +157/-0

Add the Simplified Chinese CLI package guide

• Provides a complete Chinese version of the npm CLI guide, including installation, provider setup, security boundaries, upgrades, local data, Eval prerequisites, and troubleshooting.

packages/cli/README.zh-CN.md

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c0885a94-7c15-4194-90cc-b9041c661322

📥 Commits

Reviewing files that changed from the base of the PR and between 49f8675 and ebc12ba.

📒 Files selected for processing (8)

• README.md
• README.zh-CN.md
• docs/README.md
• docs/cli-npm-release.md
• docs/cli-npm-release.zh-CN.md
• packages/cli/README.md
• packages/cli/README.zh-CN.md
• scripts/release-cli-package.mjs

Included review availability: Your plan includes up to 3 reviews per rolling hour; 1 remains after this review.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Rollback advertises missing version ✓ Resolved 🐞 Bug ≡ Correctness

Description

The defective-release procedure deprecates the bad version with a message directing users to
beta.3, but only afterward instructs maintainers to fix and release a new version. During that
interval the advertised replacement does not exist, so affected users following the recovery message
receive an unavailable-version error.

Code

docs/cli-npm-release.md[R195-197]

+bad_version=0.1.0-beta.2
+replacement=0.1.0-beta.3
+npm deprecate "maka-agent@$bad_version" "Known issue; install maka-agent@$replacement."

Relevance

●●● Strong

Clear temporal correctness bug: users are directed to a replacement version before the runbook
publishes it.

PR-#2993
PR-#3028

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The English runbook sets replacement=0.1.0-beta.3 and publishes that value in the deprecation
message at lines 195-197, while lines 200-202 place fixing and releasing the new version afterward.
The Chinese runbook repeats the same ordering at lines 185-195.

docs/cli-npm-release.md[182-202]
docs/cli-npm-release.zh-CN.md[175-195]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The rollback procedure advertises a replacement npm version before that replacement has been published, leaving users with an unusable recovery instruction during an incident.

## Issue Context
The English and Chinese runbooks both deprecate the defective version first and only then direct maintainers to fix and release the replacement. Either use the already-published `known_good` version in the immediate deprecation message, or publish and verify the new replacement before changing the message; keep both translations synchronized.

## Fix Focus Areas
- docs/cli-npm-release.md[182-202]
- docs/cli-npm-release.zh-CN.md[175-195]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context

✅ Web pages:

  🌐 Staged publishing for npm packages | npm Docs

  🌐 npm-stage | npm Docs

  🌐 Creating and publishing unscoped public packages | npm Docs

  +5 more

Review mode: ⚖️ Balanced: Mostly documentation, but the release-script packaging whitelist and required-file validation change runtime release behavior and npm distribution contracts, warranting a careful single-pass review.

Tip of the day

💡 Did you know, you can keep summaries lean with Finding overflow, which tucks the rest behind 'View more'

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗