docs: narrow the customer review queue to unanswered escalations

[NikitaVr]

Description

Follows chainpatrol/chainpatrol-web#7452, which fixes needsCustomerReview so it
means "waiting on you" rather than "yours". A customer filed a test report, saw
it come back as needing their review, and asked what the filter actually means —
these pages were part of the confusion, because they described the old behavior
accurately.

external-api/organization-proposals-review.mdx

• The overview no longer claims proposals on reports you submitted yourself are
  reviewable here. A callout states the new rule and, more importantly, why:
  ChainPatrol triages self-submitted reports and staff approval blocks the asset
  on its own, so submitting the report is already the organization's intent and
  there is no second decision to record.
• The 403 section now shows the "not waiting on your organization" error next
  to the safety-check 403 it already documented, with the three ways to hit it
  (never escalated, already answered, self-submitted).
• Two notes the page never stated: answering includes escalating back to
  ChainPatrol (with a later re-escalation returning the proposal to the queue),
  and Obligatory Organization Admin Approval does not by itself put a proposal in
  the queue.

external-api/organization-reports-list.mdx

• The needsCustomerReview row spells out what qualifies, what counts as
  answering, and the two things that do not put a report in the queue.
• The filtering example says plainly that self-submitted reports are decided by
  ChainPatrol staff and are still returned unfiltered — the distinction between
  "I can see it" and "I have to act on it" is what the customer was missing.

Screenshots, Videos (if applicable)

No new assets; prose and one <Note> callout, matching the components already
used on the page.

Additional Notes

Schema-driven fields still come from the live OpenAPI document, so the request
and response tables update themselves once the API change deploys. Only the prose
needed changing here.

Merge order does not matter much, but this reads best merged after
chainpatrol/chainpatrol-web#7452 deploys — until then it describes a 403 the
API does not yet return.

The pre-existing inaccuracies I flagged in #108 are still untouched:
reports[].id is documented as rpt_… when it is a number, and the pagination
field is nextCursor/totalCount rather than cursor. Still worth their own
pass against the live spec.

---

Generated by Claude Code

---

Note

Low Risk
Documentation-only prose changes in two MDX files; no runtime or API code in this PR.

Overview
Updates external API docs so the customer review queue matches the fixed needsCustomerReview behavior: only proposals ChainPatrol escalated to you that you haven’t answered count as “waiting on you,” not every proposal tied to your org’s reports.

On organization-proposals-review, the overview drops the idea that self-submitted reports are reviewable via this endpoint. A Note explains self-submitted proposals return 403 (ChainPatrol triages them; submitting the report is already your intent). The 403 section adds the “not waiting on your organization” error and when it applies. New Notes clarify that answering includes escalating back to ChainPatrol (re-escalation can put the proposal back in the queue) and that Obligatory Organization Admin Approval alone doesn’t put a proposal in the queue.

On organization-reports-list, the needsCustomerReview parameter description and the “awaiting your review” example spell out qualification rules, what counts as answering, and that self-submitted reports stay visible in unfiltered listings but don’t appear under this filter.

^{Reviewed by Cursor Bugbot for commit b532ad6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
chainpatrol	🟢 Ready	View Preview	Aug 8, 2026, 2:15 PM