viatris-exam-cli 0.0.0-stage → 1.4.0

package/README.md

@@ -1,3 +1,237 @@
-# Temporary Holding Version
+# Viatris Exam CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+面向 Agent 的 Viatris 考试 OpenAPI 命令行客户端。运行时零第三方依赖，要求 Node.js 18 或更高版本。
+
+## 安装
+
+```bash
+npm link
+export VIATRIS_API_KEY="replace-with-real-key"
+```
+
+默认连接线上环境：
+
+```text
+https://apaaspsc.doubaoapps.com/app/app_17gbe211qq5/openapi/
+```
+
+切换到开发环境：
+
+```bash
+export VIATRIS_API_ENV="development"
+```
+
+开发环境地址：
+
+```text
+https://apaaspsc-app_17gbe211qq5-1879207268486311.aiforce.run/app/app_17gbe211qq5/openapi/
+```
+
+`VIATRIS_API_ENV` 支持 `production`、`development`，以及别名 `prod`、`dev`。如需临时连接其他部署，可设置 `VIATRIS_API_BASE_URL`；该变量的优先级高于环境预设。
+
+CLI 不接受 `--api-key` 参数，避免密钥进入 shell history、进程列表或 Agent 日志。默认使用：
+
+```text
+X-API-Key: <VIATRIS_API_KEY>
+```
+
+若服务端使用 Bearer Token：
+
+```bash
+export VIATRIS_API_KEY_HEADER="Authorization"
+export VIATRIS_API_KEY_PREFIX="Bearer "
+```
+
+## Agent 接口约定
+
+- API 成功响应以 JSON 写入 `stdout`。
+- 错误以单行结构化 JSON 写入 `stderr`。
+- POST/PUT 请求从文件、`stdin` 或 `--json` 读取 JSON 对象。
+- API Key 只从 `VIATRIS_API_KEY` 环境变量读取。
+- 默认使用线上环境，可通过 `VIATRIS_API_ENV=development` 切换到开发环境。
+- `VIATRIS_API_BASE_URL` 可覆盖当前环境地址。
+- GET 请求遇到网络错误、HTTP 429 或 5xx 时自动重试，POST/PUT/PATCH/DELETE 不自动重试。
+- `describe` 返回机器可读的命令、参数、认证和退出码清单。
+- ID 路径参数自动进行 URL 编码。
+- HTTP 401/403 使用专用退出码，方便 Agent 判断需要刷新认证。
+
+```bash
+viatris-exam describe --compact
+```
+
+退出码：
+
+| 退出码 | 含义 |
+| --- | --- |
+| `0` | 成功 |
+| `1` | API 返回错误 |
+| `2` | 命令、参数、校验或输入错误 |
+| `3` | 环境配置错误 |
+| `4` | 网络或超时错误 |
+| `5` | 认证或授权错误 |
+
+## 命令
+
+### 产品知识树
+
+```bash
+viatris-exam products get "$PRODUCT_ID"
+viatris-exam products update-knowledge-tree "$PRODUCT_ID" \
+  --input knowledge-tree.json
+```
+
+产品是隐藏系统容器，不属于业务知识树层级。固定维度为 L1；知识树回写是完整替换操作，必须一次提交全部 15-500 个 L2/L3/L4 动态节点。先查询产品以获取固定 L1 维度的 `clientRef`。
+
+### 知识节点与文档
+
+```bash
+viatris-exam knowledge tree <product-code>
+viatris-exam knowledge nodes by-path --input path.json
+viatris-exam knowledge nodes create --input node.json
+viatris-exam knowledge nodes get <node-id>
+viatris-exam knowledge nodes update <node-id> --input changes.json
+viatris-exam knowledge nodes move <node-id> --input move.json
+viatris-exam knowledge nodes delete <node-id>
+viatris-exam knowledge documents list <node-id>
+viatris-exam knowledge documents create <node-id> --input document.json
+viatris-exam knowledge documents upsert <node-id> --input documents.json
+viatris-exam knowledge documents update <document-id> --input changes.json
+viatris-exam knowledge documents delete <document-id>
+```
+
+节点删除会级联删除整棵子树及文档。产品根和固定维度受保护，不能改名、移动或删除。
+
+`/knowledge` CRUD 响应中的 `level` 是物理存储层级（产品根为 1、固定维度为 2）；产品生成接口使用业务层级（产品隐藏、固定维度为 L1、动态节点为 L2-L4）。
+
+### 出题任务
+
+```bash
+viatris-exam gen-tasks list --status generating --limit 20
+viatris-exam gen-tasks get "$TASK_ID"
+viatris-exam gen-tasks submit "$TASK_ID" --input examples/generated-questions.json
+```
+
+`externalRef` 是题目回写的幂等键。Agent 重试 POST 前应复用原值。
+
+产品全节点任务的 `dimension` 为 `all`。应按 `knowledgeContexts` 覆盖每个叶子节点，并在回写题目时携带对应 `knowledgeNodeId`。
+
+### 考试记录
+
+```bash
+viatris-exam exam-records get "$RECORD_ID"
+viatris-exam exam-records scoring-rules "$RECORD_ID"
+```
+
+第二个命令返回答卷绑定版本的完整评分规则及用于回写的 `taskId`。
+
+### 评分任务
+
+```bash
+viatris-exam scoring get "$TASK_ID"
+viatris-exam scoring submit "$TASK_ID" --input examples/scoring-results.json
+```
+
+评分规则 V2 使用稳定的评分点 ID、扣分规则 ID 和题目级封顶规则，由服务端计算最终得分。V1 `pointResults` 结构继续兼容。
+
+### 考试与题库
+
+```bash
+viatris-exam exams create --input exam.json
+viatris-exam questions create < questions.json
+viatris-exam questions version "$QUESTION_ID" --input version.json
+```
+
+### 医疗知识检索
+
+简单查询可直接使用参数：
+
+```bash
+viatris-exam medical-search search "阿托伐他汀 适应症" \
+  --file-type drug \
+  --limit 4 \
+  --max-length 1200
+```
+
+也可提交完整 JSON：
+
+```bash
+printf '%s' '{"query":"阿托伐他汀 适应症","limit":4}' |
+  viatris-exam medical-search search
+```
+
+响应中的 `rawJson` 已是结构化对象，可直接读取 `rawJson.documents`，无需再次 `JSON.parse`。
+
+## 错误格式
+
+```json
+{
+  "error": {
+    "type": "http_error",
+    "message": "API request failed with HTTP 422.",
+    "details": {
+      "status": 422,
+      "method": "POST",
+      "path": "/openapi/questions",
+      "requestId": "request-id",
+      "response": {
+        "message": "validation failed"
+      }
+    }
+  }
+}
+```
+
+## 全局参数
+
+```text
+--base-url <url>       覆盖当前环境地址
+--key-header <name>    覆盖 VIATRIS_API_KEY_HEADER
+--key-prefix <value>   覆盖 VIATRIS_API_KEY_PREFIX
+--timeout <ms>         超时时间，默认 30000
+--retries <n>          GET 重试次数，默认 2
+--compact              输出单行紧凑 JSON
+```
+
+地址选择优先级为 `--base-url`、`VIATRIS_API_BASE_URL`、`VIATRIS_API_ENV` 对应的预设地址。认证 Key 仍必须通过 `VIATRIS_API_KEY` 提供。
+
+## 项目结构
+
+```text
+src/
+├── cli.js       # 入口与异常收口
+├── app.js       # 应用编排
+├── commands.js  # 领域命令路由
+├── command-handlers/
+│   └── *.js     # 各领域到 OpenAPI 请求的映射
+├── args.js      # 参数解析与校验
+├── input.js     # JSON 文件、stdin 与内联输入
+├── config.js    # 环境、地址与认证配置
+├── http.js      # HTTP、重试与响应处理
+├── metadata.js  # 版本、命令和环境元数据
+├── help.js      # 帮助文本
+├── output.js    # 标准 JSON 输出
+└── errors.js    # 错误类型
+skills/
+└── viatris-exam-cli/
+    ├── SKILL.md
+    └── references/cli-reference.md
+```
+
+可分发的 Agent Skill 位于 `skills/viatris-exam-cli/`，与 `src/` 同级并包含在 npm 发布包中。`skills/viatris-exam-cli.zip` 是同步生成的独立分发包。`.trae/skills/viatris-exam-cli` 是指向规范目录的相对符号链接，仅用于本地自动发现。
+
+## 变更规则
+
+任何代码、命令、接口结构、环境地址或文档变化都必须：
+
+1. 更新 `skills/viatris-exam-cli/SKILL.md` 及受影响的参考文件。
+2. 同步递增 `package.json`、`src/metadata.js` 和 Skill frontmatter 中的版本。
+3. 保持 `src/cli.js` 为薄入口，将能力放在职责单一的模块中。
+4. 重新生成 Skill ZIP 并执行验证：
+
+```bash
+npm run pack:skill
+npm test
+npm run check
+npm run check:versions
+npm run check:skill
+```

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "viatris-exam-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.0",
+  "description": "Agent-friendly CLI for the Viatris exam OpenAPI",
+  "type": "module",
+  "bin": {
+    "viatris-exam": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "skills/"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/*.js && node --check src/command-handlers/*.js",
+    "check:versions": "node scripts/check-versions.js",
+    "check:skill": "node scripts/check-skill.js",
+    "pack:skill": "cd skills && /bin/rm -f viatris-exam-cli.zip && /usr/bin/zip -qr viatris-exam-cli.zip viatris-exam-cli -x '*.DS_Store'"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}

package/skills/viatris-exam-cli/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: viatris-exam-cli
+description: Operate the Viatris exam OpenAPI through its agent-friendly CLI. Use for products, knowledge nodes or documents, generation tasks, exam records, scoring, exams, questions, or medical search.
+version: 1.4.0
+---
+
+# Viatris Exam CLI
+
+Use the repository-local CLI for every supported API operation. Do not call the HTTP endpoints directly when the CLI covers the task.
+
+## Start
+
+1. Run commands from the repository root.
+2. Require `VIATRIS_API_KEY` in the environment. Never place the key in arguments, files, output, or logs.
+3. Use production by default. Set `VIATRIS_API_ENV=development` only when the user requests development or testing.
+4. Run `node src/cli.js describe --compact` when capability discovery or exact machine-readable metadata is needed.
+5. Read [references/cli-reference.md](references/cli-reference.md) before constructing a write payload or handling a nonzero exit code.
+
+## Execute
+
+- Invoke the CLI as `node src/cli.js ...`. Do not require `npm link`.
+- Prefer `--input <file>` for existing payloads and stdin for generated payloads.
+- Parse successful `stdout` as JSON.
+- Parse failed `stderr` as JSON and branch on both exit code and `error.type`.
+- Preserve `externalRef` when retrying question submission. It is the idempotency key.
+- For product-wide generation tasks, create one or more questions for every entry in `knowledgeContexts` and include its `knowledgeNodeId`.
+- Prefer scoring rule V2 for generated questions and scoring results. Use stable point and deduction-rule IDs.
+- Treat product IDs as hidden containers, not knowledge-tree levels. Fixed dimensions are business L1; generated nodes are L2-L4.
+- Do not automatically retry POST, PUT, PATCH, or DELETE commands. Inspect the returned error and determine whether the server accepted the request.
+- Keep temporary payloads outside the repository unless they are requested deliverables.
+
+## Maintain
+
+Treat every repository behavior, command, schema, URL, documentation, or implementation change as a versioned Skill change.
+
+For every change:
+
+1. Update `skills/viatris-exam-cli/` and its affected references.
+2. Increment the semantic version in `package.json`, `src/metadata.js`, and this frontmatter `version`.
+3. Keep all three versions identical.
+4. Keep `src/cli.js` as a thin entrypoint. Put capabilities in focused modules under `src/`.
+5. Keep `.trae/skills/viatris-exam-cli` as a relative symlink to the distributable Skill directory.
+6. Run `npm run pack:skill` so `skills/viatris-exam-cli.zip` matches the canonical directory.
+7. Run `npm test`, `npm run check`, `npm run check:versions`, and `npm run check:skill`.
+
+Do not finish a code change while the Skill or any version is stale.

package/skills/viatris-exam-cli/references/cli-reference.md

@@ -0,0 +1,388 @@
+# CLI Reference
+
+## Authentication And Environment
+
+Required:
+
+```bash
+export VIATRIS_API_KEY="..."
+```
+
+Environment selection:
+
+| Value | Target |
+| --- | --- |
+| unset, `production`, `prod` | Production |
+| `development`, `dev` | Development |
+
+`VIATRIS_API_BASE_URL` overrides the selected environment. Use it only for an explicitly supplied custom deployment or local mock.
+
+Default authentication header:
+
+```text
+X-API-Key: <VIATRIS_API_KEY>
+```
+
+For Bearer authentication:
+
+```bash
+export VIATRIS_API_KEY_HEADER="Authorization"
+export VIATRIS_API_KEY_PREFIX="Bearer "
+```
+
+## Capability Discovery
+
+```bash
+node src/cli.js describe --compact
+node src/cli.js --help
+node src/cli.js --version
+```
+
+`describe` does not require credentials. It returns commands, paths, environment metadata, authentication metadata, and exit codes as JSON.
+
+## Commands
+
+Get a product and its fixed L1 dimensions:
+
+```bash
+node src/cli.js products get "$PRODUCT_ID" --compact
+```
+
+The product ID represents a hidden system container and is not part of business levels L1-L4. Use each returned `fixedDimensions[].clientRef` as the parent reference for an L2 node. Each fixed dimension also returns `level: 1` and a display `codePrefix`.
+
+Replace a product knowledge tree:
+
+```bash
+node src/cli.js products update-knowledge-tree "$PRODUCT_ID" \
+  --input knowledge-tree.json \
+  --compact
+```
+
+Payload shape:
+
+```json
+{
+  "nodes": [
+    {
+      "clientRef": "disease.hypertension",
+      "parentClientRef": "dimension:disease",
+      "level": 2,
+      "dimensionCode": "disease",
+      "name": "高血压",
+      "sortOrder": 1
+    },
+    {
+      "clientRef": "disease.hypertension.diagnosis",
+      "parentClientRef": "disease.hypertension",
+      "level": 3,
+      "dimensionCode": "disease",
+      "name": "定义与诊断",
+      "sortOrder": 1
+    },
+    {
+      "clientRef": "disease.hypertension.diagnosis.threshold",
+      "parentClientRef": "disease.hypertension.diagnosis",
+      "level": 4,
+      "dimensionCode": "disease",
+      "name": "诊断阈值",
+      "sortOrder": 1,
+      "documents": [
+        {
+          "title": "药品说明书",
+          "url": "https://example.com/source",
+          "summary": "与该知识点直接对应的证据摘录"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Submit the complete L2/L3/L4 node set, between 15 and 500 nodes. Every `clientRef` must be unique within the payload. L2 nodes use `dimension:<code>` as `parentClientRef`; L3/L4 nodes use their direct parent's `clientRef`. Every L4 node needs at least one document. A successful PUT replaces the previous dynamic nodes, so do not send a partial tree.
+
+### Incremental Knowledge Management
+
+Get the complete physical tree and all product documents:
+
+```bash
+node src/cli.js knowledge tree lipitor --compact
+```
+
+The incremental `/knowledge` responses expose physical storage levels where the product root is 1 and fixed dimensions are 2. This differs from the product-generation business taxonomy, where the product is hidden, fixed dimensions are L1, and generated content is L2-L4.
+
+Create or reuse a visible path:
+
+```bash
+node src/cli.js knowledge nodes by-path --json \
+  '{"product":"lipitor","path":["疾病知识","血脂异常基础","ASCVD 风险评估"]}'
+```
+
+The path has one to three entries. The first entry must be a fixed dimension name. The response separates all resolved `nodes` from nodes newly `created`.
+
+Create or reuse one node under a known parent:
+
+```bash
+node src/cli.js knowledge nodes create --json \
+  '{"parentId":"PARENT_ID","name":"ASCVD 风险评估","sortOrder":20}'
+```
+
+Read, update, move, or delete a node:
+
+```bash
+node src/cli.js knowledge nodes get "$NODE_ID"
+node src/cli.js knowledge nodes update "$NODE_ID" \
+  --json '{"name":"血脂异常与他汀治疗","sortOrder":5}'
+node src/cli.js knowledge nodes move "$NODE_ID" \
+  --json '{"newParentId":"NEW_PARENT_ID","sortOrder":30}'
+node src/cli.js knowledge nodes delete "$NODE_ID"
+```
+
+Product roots and fixed dimensions are protected from rename, move, and deletion. Moving cannot cross products, target the node itself or its descendants, or produce levels deeper than L4. Deleting a node deletes its entire subtree and attached documents; inspect the node first and only delete when explicitly required.
+
+Manage documents:
+
+```bash
+node src/cli.js knowledge documents list "$NODE_ID"
+node src/cli.js knowledge documents create "$NODE_ID" \
+  --json '{"title":"说明书","url":"https://example.com/source","summary":"摘录"}'
+node src/cli.js knowledge documents upsert "$NODE_ID" \
+  --json '{"items":[{"title":"说明书","summary":"更新后的摘录"}]}'
+node src/cli.js knowledge documents update "$DOCUMENT_ID" \
+  --json '{"url":null,"summary":"更新后的摘要"}'
+node src/cli.js knowledge documents delete "$DOCUMENT_ID"
+```
+
+Create reuses a document with the same title under the node. Batch upsert accepts 1-20 items and updates `url` and `summary` for existing titles. A single-document update changes only supplied fields; send `null` to clear `url` or `summary`. Inspect a document before an explicitly requested delete.
+
+List generation tasks:
+
+```bash
+node src/cli.js gen-tasks list \
+  --status generating \
+  --limit 20 \
+  --compact
+```
+
+`--status` accepts `generating`, `partial_failed`, or `failed`. `--limit` accepts 1 through 50.
+
+Get one generation task:
+
+```bash
+node src/cli.js gen-tasks get "$TASK_ID" --compact
+```
+
+For a leaf-node task, `knowledgeContext` is the mandatory target context. For a product-wide task, `dimension` is `all`, `knowledgeContext` is null, and `knowledgeContexts` contains every leaf context. Generate `questionsPerNode` questions for every listed context and follow all returned `rules`.
+
+Submit generated questions:
+
+```bash
+node src/cli.js gen-tasks submit "$TASK_ID" --input payload.json --compact
+```
+
+Payload shape:
+
+```json
+{
+  "items": [
+    {
+      "externalRef": "agent-q-0001",
+      "failureId": "optional-failure-id",
+      "knowledgeNodeId": "required-for-product-wide-task",
+      "content": {
+        "stem": "Question stem",
+        "referenceAnswer": "Reference answer",
+        "scoringPoints": [
+          {
+            "id": "dose-selection",
+            "point": "Scoring point",
+            "maxScore": 4,
+            "criteria": "Choose one deduction level",
+            "deductionRules": [
+              {
+                "id": "dose-selection-full",
+                "level": "full",
+                "deductScore": 0,
+                "criteria": "Complete answer"
+              },
+              {
+                "id": "dose-selection-zero",
+                "level": "zero",
+                "deductScore": 4,
+                "criteria": "Wrong or missing answer"
+              }
+            ]
+          }
+        ],
+        "scoringRuleVersion": 2,
+        "scoreCapRules": [
+          {
+            "id": "critical-error-1",
+            "description": "Critical contradictory conclusion",
+            "maxTotalScore": 2
+          }
+        ],
+        "evidence": [
+          {
+            "source": "Source",
+            "citation": "Citation",
+            "relevance": "Relevance"
+          }
+        ]
+      },
+      "qcResult": {
+        "outOfScope": false,
+        "insufficientEvidence": false,
+        "answerConflict": false,
+        "duplicateRisk": false,
+        "summary": "No obvious issue"
+      }
+    }
+  ],
+  "finished": true
+}
+```
+
+Omit `knowledgeNodeId` for ordinary tasks. For a product-wide task it is required and must match a node in the task's `knowledgeContexts`.
+
+Get a submitted exam record and its frozen answers:
+
+```bash
+node src/cli.js exam-records get "$RECORD_ID" --compact
+```
+
+Get the complete scoring rules bound to the record:
+
+```bash
+node src/cli.js exam-records scoring-rules "$RECORD_ID" --compact
+```
+
+The response includes the scoring `taskId`, `schemaVersion`, frozen question versions, evidence, V2 deduction rules, score caps, and item IDs. Use its `taskId` for scoring submission.
+
+Get a scoring task:
+
+```bash
+node src/cli.js scoring get "$TASK_ID" --compact
+```
+
+Submit scoring results:
+
+```bash
+node src/cli.js scoring submit "$TASK_ID" --input results.json --compact
+```
+
+Payload shape:
+
+```json
+{
+  "items": [
+    {
+      "itemId": "item-id",
+      "ok": true,
+      "pointJudgements": [
+        {
+          "pointId": "dose-selection",
+          "appliedDeductionRuleId": "dose-selection-full",
+          "reason": "Reason for selecting this deduction level",
+          "quote": "Supporting answer quote"
+        }
+      ],
+      "triggeredScoreCaps": [],
+      "flags": [],
+      "needReview": false
+    }
+  ]
+}
+```
+
+For V2, submit exactly one `pointJudgement` per scoring point. IDs must match the fetched rule set. Add triggered cap rule IDs to `triggeredScoreCaps`; the server calculates the score, so `total` is optional and must match if supplied. V1 remains compatible through `pointResults` and required `total`. For a failed item, set `ok` to `false` and provide `failureReason`.
+
+Create an exam:
+
+```bash
+node src/cli.js exams create --input exam.json --compact
+```
+
+Required top-level fields are `name`, `product`, `questionCount`, `startAt`, `endAt`, `resultPolicy`, and `assigneeIds`. `questionCount` is 1 through 150. Use either `questions` or legacy `questionIds`, never both. Each question score must be a positive integer and the complete exam must total exactly 100.
+
+Create questions directly:
+
+```bash
+node src/cli.js questions create --input questions.json --compact
+```
+
+Payload shape is `{ "items": [...] }`. Each item requires `product`, `dimension`, and `content`; provide `externalRef` for idempotency. Prefer `scoringRuleVersion: 2`, stable IDs on scoring points and deduction rules, and explicit `scoreCapRules`.
+
+The API has partial-success semantics: inspect `accepted`, `duplicates`, and every entry in `rejected` even when the HTTP response is successful.
+
+Add a question version:
+
+```bash
+node src/cli.js questions version "$QUESTION_ID" --input version.json --compact
+```
+
+Required fields are `stem`, `referenceAnswer`, nonempty `scoringPoints`, `evidence`, and `editReason`. V2 versions may also include `scoringRuleVersion: 2`, deduction rules, and `scoreCapRules`.
+
+Search medical evidence:
+
+```bash
+node src/cli.js medical-search search "阿托伐他汀 适应症" \
+  --file-type drug \
+  --limit 4 \
+  --max-length 1200 \
+  --compact
+```
+
+Or use JSON:
+
+```bash
+printf '%s' '{"query":"阿托伐他汀 适应症","limit":4}' |
+  node src/cli.js medical-search search --compact
+```
+
+Do not combine query flags with JSON input.
+
+The response `rawJson` is already a structured object. Read `rawJson.documents` directly; do not call `JSON.parse`. Each result contains `rank`, `doc_info`, optional `medical_info`, and the upstream `logid`.
+
+## Input Rules
+
+Choose exactly one input form:
+
+```bash
+node src/cli.js questions create --input payload.json
+node src/cli.js questions create --input - < payload.json
+node src/cli.js questions create --json '{"items":[]}'
+printf '%s' '{"items":[]}' | node src/cli.js questions create
+```
+
+The top-level JSON value must be an object.
+
+## Output And Errors
+
+Success writes API JSON to `stdout`. Errors write one JSON object to `stderr`:
+
+```json
+{
+  "error": {
+    "type": "http_error",
+    "message": "API request failed with HTTP 422.",
+    "details": {
+      "status": 422,
+      "method": "POST",
+      "path": "/openapi/questions",
+      "requestId": "optional-request-id",
+      "response": {}
+    }
+  }
+}
+```
+
+| Exit | Meaning | Agent action |
+| --- | --- | --- |
+| `0` | Success | Parse stdout JSON |
+| `1` | API error | Inspect status and response |
+| `2` | Usage, validation, or input error | Correct command or payload |
+| `3` | Configuration error | Check environment configuration |
+| `4` | Network or timeout error | GET may be retried; inspect write state first |
+| `5` | Authentication or authorization error | Refresh or correct credentials |
+
+GET automatically retries network errors, HTTP 429, and HTTP 5xx. POST, PUT, PATCH, and DELETE never retry automatically.