typecheck: clarify extra return tokens

README.md

@@ -272,6 +272,18 @@ Function square needs a NUMBER value after RETURN. Add a NUMBER expression.
 
 The same repair applies to compatibility methods written with `TAKES` / `LEARNED`, so older lessons also receive a method-specific hint instead of a generic type error.
 
+If a return value has extra space-separated text, `claro typecheck` identifies the first value and explains that `RETURN` accepts one expression:
+
+```claro
+TEACH square amount RETURNS NUMBER
+    RETURN amount extra
+END
+```
+
+```text
+Function square has extra text after return value amount. Keep only one expression after RETURN.
+```
+
 If a function or method declares `RETURNS TYPE` but contains no `RETURN`, the checker points out the missing statement:
 
 ```text

docs/ADVANCED_STATIC_TYPING.md

@@ -568,7 +568,11 @@ Function squre is not known yet. Check the function name or add TEACH squre befo
 
 ## Function and method return checks
 
-Simple functions and object methods can declare a return type with `RETURNS TYPE`. `claro typecheck` checks each simple `RETURN` expression before the program runs:
+Simple functions and object methods can declare a return type with `RETURNS TYPE`. `claro typecheck` checks each simple `RETURN` expression before the program runs. `RETURN` accepts one expression; if a simple value is followed by extra text, the checker gives a repair hint:
+
+```text
+Function square has extra text after return value amount. Keep only one expression after RETURN.
+```
 
 ```claro
 CLASS Player

docs/CURRENT_STATUS.md

@@ -54,6 +54,7 @@ Ready now:
 - `CHECK TYPE` gives a direct repair hint when the learner forgets the `IS` keyword, for example `CHECK TYPE score` reports `CHECK TYPE needs IS. Try: CHECK TYPE score IS NUMBER.`
 - `CHECK TYPE` gives a direct repair hint when `IS` has no expected type, for example `CHECK TYPE score IS` reports `CHECK TYPE score needs a type after IS. Try: CHECK TYPE score IS NUMBER.`
 - `CHECK TYPE` explains when the learner leaves out the expression as well, for example bare `CHECK TYPE` reports `CHECK TYPE needs an expression, IS, and a type. Try: CHECK TYPE score IS NUMBER.`
+- typed function and method returns reject simple extra tokens after a return value with a direct repair hint, such as `RETURN amount extra` reporting `Keep only one expression after RETURN.`
 - `CHECK TYPE` explains when `IS` is present but the expression is missing, for example `CHECK TYPE IS NUMBER` reports `CHECK TYPE needs an expression before IS. Try: CHECK TYPE score IS NUMBER.`
 - `CHECK TYPE` rejects extra words after a valid expected type with a direct repair hint, so `CHECK TYPE score IS NUMBER TEXT` explains that only one type belongs in the check
 - `CHECK TYPE` rejects unknown expected type names with a beginner-facing list of supported types

docs/ROADMAP.md

@@ -83,6 +83,7 @@ Keep declared return types honest: `claro typecheck` now reports friendly diagno
 8q.7. Keep typed `TEACH` declarations unambiguous: extra words after a declared return type now get a direct repair hint instead of being treated as part of an unknown type.
 8q.8. Keep typed `TEACH` declarations complete: a bare `RETURNS` now gets a direct repair hint naming the missing type and showing a supported example such as `NUMBER`.
 8q.9. Keep missing return-type diagnostics aligned across functions and methods: modern and compatibility methods now name the complete `Class.method` identity when `RETURNS` has no type, with focused fixtures in the typecheck and release validation matrices.
+8q.10. Keep return statements beginner-readable: typed returns now identify simple extra tokens after a value and explain that `RETURN` accepts one expression, with focused release validation coverage.
 
 ### 1. Strong static types
 

tests/test_validate_typecheck_diagnostics.py

@@ -108,6 +108,12 @@ class ValidateTypecheckDiagnosticsTests(unittest.TestCase):
     def test_includes_empty_function_return_fixture(self):
         self.assertIn("tests/typecheck_function_empty_return_bad.claro", MODULE.EXPECTED)
 
+    def test_includes_extra_return_tokens_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_return_extra_tokens_bad.claro",
+            MODULE.EXPECTED,
+        )
+
     def test_includes_empty_compatibility_method_return_fixture(self):
         self.assertIn(
             "tests/typecheck_method_compat_empty_return_bad.claro",

tests/typecheck_function_return_extra_tokens_bad.claro

@@ -0,0 +1,3 @@
+TEACH square amount RETURNS NUMBER
+    RETURN amount extra
+END

tools/validate_typecheck_diagnostics.py

@@ -67,6 +67,9 @@ EXPECTED = {
     "tests/typecheck_function_return_bad.claro": [
         "tests/typecheck_function_return_bad.claro:3: Type mismatch for return from square: expected NUMBER, but this value looks like TEXT.",
     ],
+    "tests/typecheck_function_return_extra_tokens_bad.claro": [
+        "tests/typecheck_function_return_extra_tokens_bad.claro:2: Function square has extra text after return value amount. Keep only one expression after RETURN.",
+    ],
     "tests/typecheck_function_lowercase_return_bad.claro": [
         "tests/typecheck_function_lowercase_return_bad.claro:2: Type mismatch for return from square: expected NUMBER, but this value looks like TEXT.",
     ],