[JoanAbad82]

Purpose

This is a small, API-focused documentation improvement related to #1925. It is not intended to resolve the broader proposal for an LLM-agnostic STACK essentials guide.

Automated question authors can misinterpret a successful POST /test result: when istests is false, the API may run a default check based on the teacher's answers. A positive passes count in that situation does not demonstrate that explicit question tests were run.

Change

• Add a compact interpretation table to api/README.md, based on existing STACK API controller test cases.
• Distinguish a fallback/default check, failing explicit tests, upgrade-related incomplete results, and per-seed results requiring further coverage checks.
• Propose conservative client-side reporting criteria for explicit tests across evaluated seeds, including outcomes, failures, errors and randomized deployed seeds. The example labels are not new API response fields.
• Link to the existing controller tests and question-testing guidance.

No API implementation, response contract or executable tests are changed.

Validation and limits

• Confirmed field names and fallback logic against api/controller/TestController.php and api/README.md at base commit 1b4e42d44930157a01f49ab35057e88b0883884d.
• Cross-checked the documented scenarios against tests/api_controller_test.php and the official testing guide.
• Evaluated 10 synthetic decision cases in memory: 10/10 matched expected classifications. A naive passes > 0 check would have overclaimed success on five intentionally selected cases. This is a targeted synthetic comparison, not a measured error rate in real agents.
• The synthetic check is not included as an executable repository test. STACK API/PHP integration tests were not run, because a working STACK runtime was not available in the preparation environment.
• Checked the documentation diff and its CRLF-compatible whitespace; exactly one file changed, with 17 insertions and no deletions.

This guidance deliberately reports results conservatively. Passing explicit tests is evidence only for the tested questions and variants, not a proof of all mathematical grading behavior.

[sangwinc]

Thanks @JoanAbad82 I'll merge this change into our issue branch for the agents authoring, and make sure this all gets rolled into one sensible change.