diff --git a/docs/openclawcode/run-json-contract.md b/docs/openclawcode/run-json-contract.md
index 959c604f0f..6ba431d82b 100644
--- a/docs/openclawcode/run-json-contract.md
+++ b/docs/openclawcode/run-json-contract.md
@@ -50,7 +50,7 @@ those nested objects.
 - `runHasUpdatedAt`
 - `runAgeSeconds`
 - `id`
-- `issueNumber`
+- `issueNumber` (`number | null`) - mirrors `issue.number` when available; otherwise `null`
 - `issueLabelCount`
 - `issueHasLabels`
 - `issueLabelListPresent`