fix: prevent random.int full-range overflow

# Conflicts:
#	README.md

.forgejo/workflows/ci.yml

@@ -15,6 +15,20 @@ jobs:
         run: make
       - name: Run tests
         run: ./claro test
+      - name: Run current release validation
+        run: ./claro validate
+      - name: Validate typecheck diagnostics
+        run: python3 tools/validate_typecheck_diagnostics.py
+      - name: Validate version convention
+        run: python3 tools/validate_version_convention.py
+      - name: Validate package security
+        run: python3 tools/validate_package_security.py
+      - name: Validate compiler warnings
+        run: python3 tools/validate_compiler_warnings.py
+      - name: Validate trusted command documentation
+        run: python3 tools/validate_trusted_command_docs.py
+      - name: Validate CI workflow coverage
+        run: python3 tools/validate_ci_workflow.py
       - name: Check lessons
         run: |
           ./claro check lessons/01_hello.claro

CHANGELOG.md

@@ -1,5 +1,295 @@
 # Changelog
 
+### Diagnose missing values in untyped object-field assignments
+
+- `claro typecheck` now explains how to repair `SET player.score` by adding a value expression after the field name.
+- Added focused negative coverage to the complete typecheck validation matrix.
+
+### Validate missing short method-field values
+
+- Added focused coverage for `SET score NUMBER` inside a method, preserving the learner-facing repair hint that one value expression is required after the type.
+- Wired the fixture into both typecheck validation gates.
+- Added the matching compatibility `TAKES` / `LEARNED` fixture so older method syntax receives the same coverage.
+
+### Diagnose missing `TO` in separated field annotations
+
+- `claro typecheck` now explains how to repair `SET player.score AS NUMBER` by adding `TO` and a value.
+- Added focused negative coverage to the complete typecheck validation matrix.
+
+### Diagnose missing values after short field annotations
+
+- `claro typecheck` now explains how to repair a short explicitly typed object-field assignment that stops after the type, such as `SET player.score NUMBER`.
+- Added focused negative coverage to the complete typecheck validation matrix.
+
+### Diagnose missing values after `AS ... TO` field annotations
+
+- `claro typecheck` now explains how to repair an explicitly typed object-field assignment that ends after `TO`, such as `SET player.score AS NUMBER TO`.
+- Added focused negative coverage to the complete typecheck validation matrix.
+
+### Diagnose extra words after short typed field assignments
+
+- `claro typecheck` now rejects trailing words after the value in short explicit object-field assignments such as `SET player.score NUMBER 10 extra`.
+- Added focused negative coverage to the complete typecheck validation matrix and documented the repair hint.
+
+### Validate explicitly typed YESNO object-field assignments
+
+- Added positive typecheck coverage for `SET player.ready YESNO YES` when the class declares `HAS ready YESNO`.
+- Added the fixture to the complete typecheck validation matrix and documented the explicit annotation form.
+
+### Validate explicitly typed TEXT object-field assignments
+
+- Added positive typecheck coverage for `SET player.name TEXT "Ada"` when the class declares `HAS name TEXT`.
+- Added the fixture to the complete typecheck validation matrix and documented the explicit annotation form.
+
+### Diagnose missing class field names
+
+- `claro typecheck` now explains how to repair a bare `HAS` declaration instead of reporting a confusing missing type for an unnamed field.
+- Added focused coverage to the complete typecheck diagnostic validation matrix.
+
+### Diagnose missing method names
+
+- `claro typecheck` now explains how to repair a bare `TEACH` declaration inside a class instead of describing it as a top-level function.
+- Added focused coverage to the complete typecheck diagnostic validation matrix.
+
+### Diagnose missing class names
+
+- `claro typecheck` now explains how to repair a bare `CLASS` declaration instead of silently accepting a class with no name.
+- Added focused coverage to the complete typecheck diagnostic validation matrix.
+
+### Diagnose missing function names
+
+- `claro typecheck` now explains how to repair a bare `TEACH` declaration instead of silently accepting a function with no name.
+- Added focused coverage to the complete typecheck diagnostic validation matrix.
+
+### Diagnose unknown class field types
+
+- `claro typecheck` now rejects class fields such as `HAS score BANANA` with a beginner-facing diagnostic that names the class and field, lists supported type examples, and suggests using a Claro type.
+
+### Validate compatibility duplicate-parameter diagnostics
+
+- Added focused coverage proving that compatibility `TAKES` / `LEARNED` functions reject repeated parameter names with the same repair-oriented diagnostic as modern functions.
+- Added the fixture to the complete typecheck diagnostic validation matrix.
+
+### Validate compatibility unknown inline method-field annotations
+
+- Added focused coverage proving that compatibility `TAKES` / `LEARNED` methods reject unknown inline field annotations with the same repair-oriented diagnostic as modern methods.
+
+### Diagnose unknown inline method-field annotations
+
+- `claro typecheck` now rejects unknown inline field annotations such as `BANANA` and suggests the class-declared `HAS` type.
+- Added focused negative coverage to the complete typecheck validation matrix.
+
+### Align inline method-field annotations with class fields
+
+- `claro typecheck` now compares an inline method assignment annotation with the class field declared by `HAS`.
+- A mismatch such as `SET score TEXT 10` inside a method for `HAS score NUMBER` explains both types and suggests the class-declared type.
+- Added positive and negative fixtures to the complete typecheck validation matrix.
+
+### Validate compatibility inline method-field annotations
+
+- Added matching positive and negative coverage for `TEACH ... TAKES ...` / `LEARNED` methods.
+- Release validation now protects the same class-declared-type diagnostic for older compatibility lessons.
+
+- Added focused modern-method coverage for the learner-facing diagnostic produced when an undeclared field is assigned from an expression whose type is not inferable yet.
+
+## Unreleased
+
+- Method-body `CHECK TYPE` diagnostics now name the current class method when a declared field is checked against the wrong type, with focused positive and negative validation coverage.
+
+- Typecheck diagnostics for typed method-body field assignments now name the class method and arithmetic operation when a known TEXT operand is used in a NUMBER field update.
+
+### Compatibility method field-assignment diagnostics
+
+- Added focused positive and negative typecheck fixtures for older `TEACH ... TAKES ...` / `LEARNED` methods that assign to typed class fields.
+- Release validation now preserves the learner-facing `Class.method` name in these compatibility diagnostics.
+
+### Validate compatibility method multiplication diagnostics
+
+- Added focused negative typecheck coverage proving that the older `TAKES` / `LEARNED` method syntax identifies a TEXT operand in a NUMBER multiplication return and explains the required operand type.
+- Wired the fixture into the standalone typecheck validator and `claro validate`.
+
+### Validate compatibility method division diagnostics
+
+- Added focused negative typecheck coverage proving that the older `TAKES` / `LEARNED` method syntax identifies a TEXT operand in a NUMBER division return and explains the required operand type.
+- Wired the fixture into the standalone typecheck validator and `claro validate`.
+
+### Validate compatibility method subtraction diagnostics
+
+- Added focused negative typecheck coverage proving that the older `TAKES` / `LEARNED` method syntax identifies a TEXT operand in a NUMBER subtraction return and explains the required operand type.
+- Wired the fixture into the standalone typecheck validator and `claro validate`.
+
+### Validate compatibility method addition diagnostics
+
+- Added focused negative typecheck coverage proving that the older `TAKES` / `LEARNED` method syntax identifies a TEXT operand in a NUMBER addition return and explains the required operand type.
+- Wired the fixture into the standalone typecheck validator and `claro validate`.
+
+### Validate compatibility method addition returns
+
+- Added focused positive typecheck coverage proving that the older `TEACH ... TAKES ... RETURNS NUMBER` / `LEARNED` method syntax accepts a numeric addition return after `CHECK TYPE` establishes the parameter type.
+- Wired the fixture into the standalone typecheck validator and `claro validate`.
+
+### Validate compatibility method multiplication returns
+
+- Added focused release validation for compatibility (`TAKES` / `LEARNED`) methods returning numeric multiplication results.
+
+### Validate compatibility method subtraction returns
+
+- Added focused positive typecheck coverage proving that the older `TEACH ... TAKES ... RETURNS NUMBER` / `LEARNED` method syntax accepts a numeric subtraction return after `CHECK TYPE` establishes the parameter type.
+- Wired the fixture into the standalone typecheck validator and `claro validate`.
+
+### Validate numeric function subtraction returns
+
+- Added focused positive typecheck coverage proving that a typed function can return a numeric subtraction expression after `CHECK TYPE` establishes its parameter type.
+- Wired the fixture into the standalone typecheck validator and `claro validate`.
+
+### Validate division return diagnostics
+
+- Added focused `claro typecheck` coverage proving that a typed function returning `amount / "oops"` identifies division, the required `NUMBER` operands, and the offending `TEXT` value.
+- Wired the negative fixture into the complete typecheck validator and `claro validate` coverage.
+
+### Validate numeric function return expressions
+
+- Added a focused positive typecheck fixture proving that a typed function can return a numeric multiplication expression after `CHECK TYPE` establishes its parameter type.
+- Wired the fixture into the standalone typecheck validator and `claro validate`.
+
+### Advertise typed-language keywords to IDE helpers
+
+- Added `RETURNS`, `CHECK`, and `TYPE` to `claro ide` keyword metadata so editor integrations can recognize the current typed function and type-checking syntax.
+- Extended the IDE metadata validator and documented the updated completion surface.
+
+### Validate the complete typecheck matrix
+
+- `claro validate` now runs the complete focused typecheck fixture matrix, including method-call, alias, return, and expression fixtures that were previously covered only by the standalone diagnostic validator.
+
+### Validate compatibility method return types
+
+- Added focused coverage proving that the older `TEACH ... TAKES ... RETURNS TYPE` / `LEARNED` method syntax receives the same learner-facing return-type diagnostic as modern methods.
+- Added the compatibility method fixture to the complete typecheck diagnostics validator.
+
+### Validate incomplete method return paths
+
+- Added focused typecheck coverage proving that a typed method with an incomplete conditional return reports the same learner-facing missing-path diagnostic as a typed function.
+- Added the method fixture to both `claro validate` and the complete typecheck diagnostics validator.
+
+### Validate compatibility function return types
+
+- Added focused coverage proving that the older `TEACH ... TAKES ... RETURNS TYPE` / `LEARNED` syntax receives the same learner-facing return-type diagnostic as modern functions.
+- Added the compatibility fixture to both `claro validate` and the complete typecheck diagnostics validator.
+
+### Validate unknown method return types
+
+- Added focused `claro typecheck` regression coverage for an object method declaring an unsupported `RETURNS` type such as `BANANA`.
+- The release validator now checks function and method unknown-return-type diagnostics separately.
+
+### Diagnose unknown declared return types
+
+- `claro typecheck` now reports a learner-facing error when a function or object method declares an unsupported `RETURNS` type such as `BANANA`.
+- Added focused negative-fixture coverage and release-validator coverage for the invalid declaration.
+
+### Diagnose empty typed returns
+
+- `claro typecheck` now reports a beginner-facing error when a function or method declares `RETURNS TYPE` but uses `RETURN` without a value.
+- Added a focused negative fixture and release-validation coverage for the missing return expression.
+
+### Check typed parameter expressions in returns
+
+- `claro typecheck` now carries a function or method parameter's `CHECK TYPE` metadata into later return-expression inference.
+- Added positive and negative arithmetic return fixtures for functions and object methods so a declared return type cannot silently accept an expression whose parameter type is already known.
+
+### Check simple function return types
+
+- Added `TEACH name ... RETURNS TYPE` syntax for a focused static return check.
+- `claro typecheck` now reports the expected and inferred types when a `RETURN` expression does not match.
+- Added positive and negative fixtures and wired both into `claro validate` and the complete typecheck diagnostics validator.
+
+### Diagnose explicitly typed unknown object fields
+
+- Added focused typecheck coverage for `SET player.level NUMBER 3` when `Player` declares no `level` field.
+- `claro typecheck` now gives the same beginner-facing missing-`HAS` hint for explicitly typed unknown fields as it does for untyped field assignments.
+
+### Reject unlisted typecheck fixtures
+
+- `tools/validate_typecheck_diagnostics.py` now discovers `tests/typecheck_*.claro` files and fails when a fixture is missing from the validator's positive or negative lists.
+- This keeps new learner-facing typecheck examples from silently escaping release validation.
+
+### Explain text operands in object-field addition
+
+- Added focused typecheck coverage for `SET player.score player.name + 1`.
+- `claro typecheck` now names the `TEXT` operand and explains that addition into a `NUMBER` field needs numeric values, matching the existing subtraction, multiplication, and division diagnostics.
+
+### Complete numeric object-field arithmetic coverage
+
+- Added a focused positive typecheck fixture for numeric subtraction in an object field.
+- Added the fixture to both the complete typecheck diagnostics validator and `claro validate`, keeping valid subtraction beside the existing division/multiplication positives and text-operand diagnostics.
+
+### Complete typecheck fixture validation
+
+- Added regression coverage requiring the focused typecheck validator to list every `typecheck_*.claro` fixture, plus the existing object-field validation script.
+- Added the two previously omitted positive fixtures so `tools/validate_typecheck_diagnostics.py` now exercises the complete typecheck fixture set.
+
+### CI release-gate validator hardening
+
+- Added focused regression coverage for the workflow validator.
+- `tools/validate_ci_workflow.py` now checks release commands inside actual `run` steps, so commented-out commands cannot make CI coverage appear complete.
+- The validator now requires its own executable CI command, protecting the workflow coverage check from being removed silently.
+
+### Object-alias field CHECK TYPE diagnostics
+
+- Added focused typecheck coverage for `CHECK TYPE alias.field IS TYPE` after a simple object alias.
+- `claro typecheck` now compares an aliased object's declared field type with the requested `CHECK TYPE` type.
+
+### Nested container type validation
+
+- Added a focused nested-container typecheck example for adding a typed map to a typed list.
+- Updated container matching so `LIST OF MAP` accepts map values with their own type metadata while preserving existing list/map mismatch diagnostics.
+
+### Object-field expression validation
+
+- Added positive and negative typecheck fixtures for assigning object fields from another field and from an arithmetic field expression.
+- Added both fixtures to `claro validate` and the focused typecheck diagnostics validator.
+- Added a focused negative fixture for the reverse expression mismatch: storing a numeric expression in a `TEXT` object field now remains covered by the release validation matrix.
+
+- `claro package doctor` now rejects duplicate `manifest-version:` fields in `claro.project` instead of accepting the first value and overlooking ambiguous project metadata.
+
+- `claro package doctor` now rejects duplicate package entries in `claro.lock` instead of allowing ambiguous lockfile data.
+- `claro package doctor` now rejects duplicate `name:` entries in a package manifest instead of accepting ambiguous package identity data.
+- `claro package doctor` now rejects duplicate `checksum:` entries in a package manifest instead of accepting ambiguous integrity data.
+- `claro package doctor` now rejects listed package manifests whose `version:` only starts with the supported local package version, such as `version: 10`.
+- `claro package doctor` now rejects listed package manifests whose `source:` only starts with the supported local source, such as `source: local-extra`.
+- `claro package doctor` now rejects project files whose `manifest-version:` only starts with the supported value, such as `manifest-version: 10`.
+
+## v1.18.26-dev exact package manifest-version validation
+
+- Added package-security coverage for a manifest version that only starts with the supported version, such as `manifest-version: 10` for the current `manifest-version: 1` format.
+- Changed `claro package doctor` to compare the complete `manifest-version:` value instead of accepting a version as a substring.
+
+## v1.18.26-dev exact package checksum validation
+
+- Added package-security coverage for a manifest checksum with valid digest text followed by extra data.
+- Changed `claro package doctor` to compare the complete `checksum:` field instead of accepting a checksum as a substring.
+
+## v1.18.26-dev exact package manifest-name validation
+
+- Added package-security coverage for a manifest name that only starts with the expected package name, such as `name: math-tools-extra` for package `math-tools`.
+- Changed `claro package doctor` to compare the complete `name:` value, preventing prefix matches from being accepted as valid manifests.
+
+## v1.18.26-dev package list unsafe-name diagnostic
+
+- Added focused package-security validation for `claro package list` when `claro.project` already contains an unsafe package name such as `../bad`.
+- Changed `claro package list` to fail with the existing beginner-facing `BAD package name: ...` diagnostic instead of displaying unsafe entries as normal package names.
+
+## v1.18.26-dev missing unchecked function argument diagnostic
+
+- Added a focused negative `claro typecheck` fixture for calling a simple function without its declared argument, such as `TEACH greet name` followed by `DO greet`.
+- Improved the static arity check so simple functions without `CHECK TYPE` hints still report a beginner-facing missing-argument diagnostic.
+- Wired the fixture into the typecheck diagnostics validator and `claro validate`.
+
+## v1.18.26-dev CI release validation coverage
+
+- Added `tools/validate_ci_workflow.py` to assert that Forgejo/Gitea CI keeps running Claro's current release gates.
+- Updated `.forgejo/workflows/ci.yml` to run `claro validate`, typecheck diagnostics validation, version convention validation, and the CI workflow coverage check in addition to the existing smoke tests.
+- Documented the CI coverage validator in the testing docs and current status/roadmap notes.
+
 ## v1.18.26-dev unknown object-field expression diagnostic
 
 - Added a focused negative `claro typecheck` fixture for assigning an expression with no inferable static type to an undeclared object field, such as `SET player.level score + 1` after `NEW Player player`.

CODEBERG_PUSH_HANDOFF.md

@@ -0,0 +1,10 @@
+# Gitea Push Handoff
+
+No prepared local commit is waiting on authentication for the configured private Gitea remote.
+
+- Updated: `2026-09-01T15:24:30Z`
+- Configured publication remote: `gitea` (`ssh://git@gitea.142-44-162-98.sslip.io:2222/RayPals/Claro.git`)
+- Latest completed work: `typecheck: validate missing method args`
+- Verification rule: compare `git rev-parse HEAD` with `GIT_TERMINAL_PROMPT=0 git ls-remote gitea refs/heads/main` after each push.
+
+The older Codeberg authentication blocker is historical only. This scheduled job is now configured to publish only to the private Gitea remote. Verify each completed run by comparing local `HEAD` with Gitea `main`.

HANDOFF_GPT56_LUNA.md

@@ -0,0 +1,281 @@
+# Handoff to GPT-5.6-Luna — Claro Project Review
+
+Prepared: 2026-08-17 (by Claude, evidence-based; see "Commands actually run" for what was verified in this session).
+
+This document distinguishes **VERIFIED** (I ran it in this session, in this checkout, and observed the result) from **CLAIMED** (asserted in existing docs/commit messages/handoff notes, not independently re-verified beyond what's noted).
+
+---
+
+## 1. Project purpose and architecture
+
+**Purpose** (from `README.md`, VERIFIED by reading): Claro is a small, readable scripting language/interpreter aimed at beginners, particularly learners with learning disabilities. It favors plain-text keywords (`SET`, `SAY`, `ASK`, `IF`/`END`, `TEACH`/`DO`) over punctuation-heavy syntax, while layering in optional static typing, objects/classes, a local package/project workflow, and offline-friendly HTTP networking.
+
+**Architecture** (VERIFIED by reading `src/claro.c` and `Makefile`):
+- Single-file C99 interpreter: `src/claro.c`, 641 lines (but extremely dense — most "lines" are long semicolon-chained C statements with many statements per physical line, not idiomatic multi-line C). `wc -l` undercounts real logical complexity substantially.
+- Built with plain `gcc -std=c99 -O0 -o claro src/claro.c -lm` (see `Makefile`). No external dependencies beyond libm and, optionally, `curl` as a subprocess for real HTTP(S).
+- Two build outputs are committed directly to the repo root: `claro` and `claro.exe` (both tracked in git despite `.gitignore` listing them — see §4 risk).
+- CLI subcommands dispatch from `main()`: `test`, `validate`, `check`, `typecheck`, `fmt`, `doctor`, `examples`, `repl`, `new`, `run`, `package *`, `ide`, `--version`, `help`.
+- The static type checker lives almost entirely in one function, `typecheck_file()` at `src/claro.c:550` — a single very long line implementing per-statement dispatch for `SET`, `DO`/`CALL`, and `CHECK TYPE`, including inline object/class field and method resolution. `run_validate()` (`src/claro.c:639`) is the master validation entrypoint invoked by `claro validate`, hardcoding the full list of "good" (must type-check clean) and "bad" (must produce a diagnostic) fixture files.
+- Object/class support: `NEW Class name` registers a synthetic type `OBJECT:Class` in the type environment (`src/claro.c:555`) and pre-seeds `name.field` types from `HAS` declarations collected by `collect_class_field_type_checks()`. Field/method diagnostics (unknown field, unknown method, use-before-`NEW`) are all resolved through this same type-environment lookup at typecheck time — this is a static, line-by-line heuristic checker, not a full parser/AST-based type system.
+- Tests: `tests/` holds 93 `.claro` fixture files, of which 33 are `typecheck_*` fixtures (paired `_good`/`_bad` cases) driving both `claro validate` and `tools/validate_typecheck_diagnostics.py`. Non-typecheck tests use `.claro`/`.out` pairs run via `claro test`.
+- `tools/*.py` are auxiliary Python 3 validation scripts (no pip dependencies observed) for specific feature slices (typecheck diagnostics, concurrency, IDE metadata, LSP helper, package security, version convention, per-RC/version validation).
+
+**Recent development focus** (VERIFIED via `git log --stat` on the last 6 commits): the last five feature commits (`68104bd` → `1cbdc1e`) are a tightly incremental sequence building out **static diagnostics for simple object fields and methods** — missing-`NEW` detection, unknown-field/unknown-method detection, and wrong-type detection — each commit touching `src/claro.c`, one new `tests/typecheck_*_bad.claro` fixture, `tools/validate_typecheck_diagnostics.py`, and three docs files (`README.md`, `docs/ADVANCED_STATIC_TYPING.md`, `docs/CURRENT_STATUS.md`, `docs/ROADMAP.md`) in lockstep. This is a consistent, disciplined pattern: every behavior change ships with a fixture and a doc update in the same commit.
+
+---
+
+## 2. Current branch/status (VERIFIED)
+
+- Branch: `main`. Working tree is clean except for one untracked file: `CODEBERG_PUSH_HANDOFF.md` (present before this session, left untouched — see §7).
+- No modifications, commits, or pushes were made in this session.
+- Three remotes configured: `origin` = Codeberg (`https://codeberg.org/RayPals/Claro.git`), `gitea` = self-hosted Gitea over SSH, `github` = `https://github.com/RayPals/Claro.git`.
+- After `git fetch` on all three remotes (read-only; no push attempted):
+  - `origin/main` (Codeberg) = `40f7881` ("feat: diagnose method calls before object creation") — **1 commit behind local `HEAD` (`1cbdc1e`)**. This exactly matches the blocker described in `CODEBERG_PUSH_HANDOFF.md` (§7).
+  - `gitea/main` = `1cbdc1e` — **identical to local `HEAD`**, i.e. the Gitea mirror is fully up to date and already has the commit that failed to reach Codeberg.
+  - `github/main` = `68104bd` — **4 commits behind local `HEAD`**, missing all five of the most recent object-field/method diagnostic commits.
+- So: local `HEAD` is the most advanced ref anywhere. Gitea already has it. Codeberg and GitHub do not.
+
+---
+
+## 3. Files / recent changes of interest
+
+- `src/claro.c:550` — `typecheck_file()`, the whole static-typechecker implementation.
+- `src/claro.c:639` — `run_validate()`, the hardcoded list of fixtures `claro validate` must pass/fail correctly against.
+- `tests/typecheck_method_unknown_method_bad.claro`, `tests/typecheck_method_unknown_object_bad.claro`, `tests/typecheck_object_field_unknown_expression_bad.claro`, `tests/typecheck_object_field_unknown_object_bad.claro` — the four newest negative fixtures (last four feature commits).
+- `tools/validate_typecheck_diagnostics.py` — asserts exact diagnostic text for every `_bad` fixture and "Type check OK" for every `_good` fixture; this is the source of truth for exact error-message wording.
+- `docs/ADVANCED_STATIC_TYPING.md` and `docs/CURRENT_STATUS.md` — kept in sync with each feature commit; read these together with `docs/ROADMAP.md` §"Near-term cleanup priorities" for the project's own stated next steps.
+- `CODEBERG_PUSH_HANDOFF.md` (untracked, root) — a prior handoff note describing a failed Codeberg push (see §7). Left unmodified per instructions.
+- `claro` / `claro.exe` (repo root) — prebuilt binaries, tracked in git even though `.gitignore` lists both names (git tracks files added before the ignore rule existed, or `git add -f` was used at some point — not verified which).
+
+---
+
+## 4. Commands actually run this session, and real results (all VERIFIED)
+
+All builds were done to `/tmp` to avoid touching the tracked binaries; no source files were modified.
+
+```
+$ gcc -std=c99 -O0 src/claro.c -o /tmp/claro_build -lm
+```
+→ Exit 0. Three `-Wformat-truncation` warnings in `create_package_folder()` (snprintf buffer-size warnings on `path[512]`/`readme[512]`), no errors.
+
+```
+$ cmp /tmp/claro_build ./claro
+```
+→ **Identical.** The tracked `./claro` binary is byte-for-byte reproducible from `src/claro.c` at current `HEAD` with this exact compiler/flags — the repo is not carrying a stale or hand-edited binary.
+
+```
+$ ./claro --version
+```
+→ `Claro v1.18.26` — matches `README.md` and `CHANGELOG.md`.
+
+```
+$ ./claro test
+```
+→ `PASS: 0 failure(s)` (all fixture `.claro`/`.out` pairs matched).
+
+```
+$ ./claro validate
+```
+→ Ran doctor + all `claro test` fixtures + lesson/example `claro check` + full `typecheck_*` good/bad matrix. Ends with `Validation passed. Claro v1.18.26 foundation checks are ready for use.`
+
+```
+$ python3 tools/validate_typecheck_diagnostics.py
+```
+→ Exit 0, `Typecheck diagnostics validation complete`. Every asserted diagnostic string matched exactly, including the two newest fixtures (`typecheck_method_unknown_method_bad.claro`, `typecheck_method_unknown_object_bad.claro`).
+
+```
+$ ./claro doctor
+```
+→ All checks `OK`, `Claro folder looks ready.`
+
+```
+$ ./claro check examples/quiz.claro
+$ make check
+```
+→ All `OK` (quiz.claro, lessons/01_hello.claro, lessons/03_variables.claro, lessons/08_functions.claro).
+
+```
+$ ./claro typecheck tests/typecheck_method_unknown_method_bad.claro
+```
+→ `tests/typecheck_method_unknown_method_bad.claro:11: Object Player has no method fly. Check the method name or add TEACH fly inside CLASS Player.` (exit 1, as intended for a negative fixture).
+
+```
+$ git fetch origin main && git fetch gitea main && git fetch github main
+```
+→ All three succeeded (network reachable, read-only). Results in §2.
+
+```
+$ git status  (before and after all of the above)
+```
+→ Unchanged: only the pre-existing untracked `CODEBERG_PUSH_HANDOFF.md`. No stray files were left behind by test/validate runs (e.g. no leftover `packages/`, no `MyProject/`, no `network_demo.json`).
+
+**Not run:** `claro new`, `claro package *`, `claro repl`, `claro ide`, `HTTP GET`/`HTTP SAVE` against real `http://`/`https://` URLs, `run_tests.bat`/`build.bat`/`build.ps1` (Windows-only), and any `tools/validate_*` script not shown above (e.g. `validate_concurrency.py`, `validate_ide_metadata.py`, `validate_lsp_helper.py`, `validate_package_security.py`, per-RC scripts) — these were not exercised and their status should be treated as unknown, not passing.
+
+---
+
+## 5. Current defects / blockers
+
+1. **Codeberg push blocker (CLAIMED in `CODEBERG_PUSH_HANDOFF.md`, corroborated by this session's `git fetch`)**: local `HEAD` (`1cbdc1e`) cannot reach `origin/main` (Codeberg) via HTTPS; the prior attempt failed with "Credentials are incorrect or have expired" using an askpash script against `CODEBERG_TOKEN`. This session's read-only `git fetch origin main` succeeded (network path to Codeberg is fine), so the issue is specifically push authentication/credential validity, not connectivity. This was **not re-attempted** in this session per instructions (no push).
+2. **GitHub mirror is stale by 4 commits** (VERIFIED via `git fetch github main`). Not previously flagged in any existing handoff doc — this is new information from this session.
+3. **Committed build artifacts** (`claro`, `claro.exe`) are tracked in git despite being listed in `.gitignore`. They are currently byte-identical to a fresh build from `HEAD` (verified above), so they aren't stale today, but nothing prevents future drift since nothing in CI enforces binary-vs-source parity — a future push could easily commit source changes without rebuilding, leaving a stale binary silently in the repo.
+4. **Compiler warnings** (VERIFIED): `-Wformat-truncation` on `create_package_folder()` in `src/claro.c` (buffer-size warnings around `path`/`readme`/`meta` snprintf calls at ~`src/claro.c:587`). Not fatal, not currently causing test failures, but worth resolving since `package init`/`package add` write these files for real projects — a sufficiently long package name plus deep path could theoretically truncate a written manifest path.
+5. **`typecheck_file()` is a single ~90-statement function on one physical line** (`src/claro.c:550`) mixing lexing, type-environment maintenance, and all diagnostic logic for `SET`/`DO`/`CALL`/`CHECK TYPE`. This is a maintainability risk more than a correctness defect today (all fixtures pass), but each new diagnostic (5 of the last 5 feature commits) adds more branches to this one function/line, compounding review difficulty.
+6. **CI workflow (`.forgejo/workflows/ci.yml`, VERIFIED by reading) does not run `claro validate` or `tools/validate_typecheck_diagnostics.py`** — it only runs `make`, `./claro test`, three lesson `claro check` calls, and `tools/validate_rc3.py`. So the entire typecheck-diagnostics matrix (33 fixtures) that this session hand-verified passes is **not covered by the repo's own CI**, only by manual/local runs. If Codeberg Actions (or Forgejo Actions) mirrors this workflow, a regression in `typecheck_file()` could land without CI catching it.
+
+---
+
+## 6. Risks
+
+- **Single dense source file with no automated static analysis in CI** (no `-Wall`/`-Wextra` gate visible in `Makefile` or CI; warnings above were only surfaced because I passed `-std=c99 -O0` — the same as `Makefile` — and gcc emitted them anyway to stderr, not because CI checks for them).
+- **Push-credential blocker means "local main" and "Codeberg main" have diverged for at least 6 days** (commit `1cbdc1e` dated in the repo's commit history vs. the handoff note's `2026-08-16` timestamp) with no CI proof that the unpushed commit is what actually will land — anyone treating Codeberg as the source of truth is looking at stale state.
+- **Three-remote setup (Codeberg/Gitea/GitHub) with no documented sync policy** found in the repo — `gitea` happens to be current, `github` is stale by design or neglect, unclear which is intended as canonical beyond `origin` = Codeberg per `CODEBERG_PUSH_HANDOFF.md`'s framing.
+- **No test coverage found for the compiler warnings' code path** (`create_package_folder`) — `claro package add` isn't exercised by `claro test`/`claro validate`, only by `tools/validate_v1_16.py` and `tools/validate_package_security.py`, neither of which was run this session.
+
+---
+
+## 7. Existing handoff note — preserved unchanged
+
+`CODEBERG_PUSH_HANDOFF.md` (untracked, repo root) was read but **not modified**, per instructions. Summary of its claims (CLAIMED, not re-verified beyond the `git fetch` cross-check in §2, which is consistent with it):
+- Local commit `1cbdc1e` could not be pushed to `origin/main` (Codeberg) due to an HTTPS credential failure with `CODEBERG_TOKEN` via non-interactive askpass.
+- It lists the same validation commands (`gcc` build, `claro typecheck` on the unknown-method fixture, `validate_typecheck_diagnostics.py`, `claro test`, `claro validate`) as having passed prior to the push attempt — this session independently re-ran all of these and got the same pass results (§4), so that portion of the note is corroborated, not just claimed.
+- Instructs: "After writing or updating this handoff note, rerun validation before making more source changes or retrying the push." This session did not retry the push (out of scope) and made no source changes.
+
+---
+
+## 8. Recommended next development task
+
+Given the state above, in priority order:
+
+1. **Resolve the Codeberg push credential issue** (human/credential-owner action — outside what an agent should do without explicit authorization: needs a valid `CODEBERG_TOKEN` or interactive re-auth). Until resolved, Codeberg `main` will keep drifting behind Gitea/local.
+2. **Sync GitHub `main`** — decide whether GitHub is meant to mirror Codeberg 1:1; if so, push the 4 missing commits once credentials/policy are confirmed.
+3. **Add `claro validate` and `python3 tools/validate_typecheck_diagnostics.py` to `.forgejo/workflows/ci.yml`**, so the 33-fixture typecheck matrix is actually gated in CI, not just run manually. This is a small, low-risk, high-value change.
+4. **Continue the object/method diagnostic series along its established pattern** (per `docs/ROADMAP.md` "Near-term cleanup priorities" and the `docs/ADVANCED_STATIC_TYPING.md` "Status" section, both CLAIMED as the project's own stated direction): the next natural narrow slice, following the existing good/bad-fixture-pair convention, would be object-field diagnostics for compound assignment (e.g. `SET player.score player.score + 5`) or a return-type check for simple methods — both currently listed as "still needed" in `docs/CURRENT_STATUS.md`. This keeps scope narrow and consistent with the last 5 commits' style (one fixture pair + one diagnostic branch + doc sync per commit).
+5. **Consider a low-risk refactor of `typecheck_file()`** into named per-statement-kind helper functions (e.g. `typecheck_set_statement`, `typecheck_call_statement`, `typecheck_check_type_statement`) before adding much more branching — purely mechanical extraction, same behavior, verified by the existing fixture suite, to keep the "one more `if` per feature" pattern from becoming unreviewable.
+
+---
+
+## 9. Precise review questions for GPT-5.6-Luna
+
+1. **Push blocker**: Given `origin` (Codeberg) is 1 commit behind and the failure mode was HTTPS credential rejection (not network unreachability — this session's `git fetch origin main` succeeded), do you see evidence of a token scope/expiry issue versus a repo-permission issue? Is there a safer non-interactive re-auth path than the askpash script previously used?
+2. **Remote policy**: Should GitHub `main` be treated as a required mirror of Codeberg `main`, or is its 4-commit staleness intentional (e.g. GitHub kept as a pre-migration snapshot, given the branch name `backup/github-main-before-codeberg-copy-20260717-185100` visible in `git branch -a`)? This affects whether "sync GitHub" belongs on the task list at all.
+3. **CI coverage gap**: Do you agree `claro validate` and `tools/validate_typecheck_diagnostics.py` should be added to `.forgejo/workflows/ci.yml`, or is there a reason (e.g. runtime cost, redundancy with `claro test`) they were deliberately left out?
+4. **`typecheck_file()` density**: Is the one-line-per-statement-kind style in `src/claro.c` (confirmed at `typecheck_file()`, `src/claro.c:550`, and `run_validate()`, `src/claro.c:639`) an intentional project convention (e.g. to minimize diff noise or match some formatting tool), or tech debt worth breaking up now, before the object/method diagnostic series grows further? If intentional, what's the constraint driving it?
+5. **Committed binaries**: Given `claro`/`claro.exe` are `.gitignore`d yet tracked and currently reproducible byte-for-byte from source (verified this session), should they be removed from tracking (relying on CI/Makefile to build), or is committing them load-bearing for some consumer (e.g. `claro new`/docs referencing a ready-to-run binary without requiring a local `gcc`)?
+6. **Next diagnostic slice**: Does compound field assignment (`SET player.score player.score + 5`) or method-return-type checking better match the project's actual near-term priority, or is there a different "still needed" item from `docs/CURRENT_STATUS.md` you'd rank higher given the codebase as it stands today?
+
+---
+
+## 10. Review addendum — 2026-08-17 (re-verification pass, by Claude)
+
+A second, independent pass was run in this same checkout shortly after the handoff above was written (handoff file mtime `2026-08-17 00:17:15 UTC`; this addendum's checks ran at `2026-08-17 00:18–00:20 UTC`, i.e. minutes later, same day/session window — not a later-day re-check). Purpose: confirm every claim in §1–§9 still holds before handing off, and record exact commands/output for Luna. **No source files were modified, nothing was committed, pushed, or deleted.** `CODEBERG_PUSH_HANDOFF.md` was read only, left byte-identical.
+
+### Commands run and results (all VERIFIED, this pass)
+
+```
+$ git status
+On branch main
+Your branch is ahead of 'origin/main' by 1 commit.
+Untracked: CODEBERG_PUSH_HANDOFF.md, HANDOFF_GPT56_LUNA.md
+```
+→ Same as §2, with `HANDOFF_GPT56_LUNA.md` now also untracked (it did not exist yet when §2 was written).
+
+```
+$ git log --oneline -5
+1cbdc1e feat: diagnose unknown object methods
+40f7881 feat: diagnose method calls before object creation
+a3c084b feat: improve unknown object field expression diagnostic
+c41d255 feat: diagnose object field assignment before NEW
+68104bd feat: diagnose missing object field type checks
+```
+→ Unchanged from §1/§2. `git log -1 --format='%H %ci'` confirms `HEAD` is `1cbdc1e`, authored `2026-08-13 15:30:33 +0000` — no new commits landed between the two passes.
+
+```
+$ git fetch origin main && git fetch gitea main && git fetch github main
+```
+→ All three succeeded (read-only). Ref comparison:
+- `origin/main` (Codeberg) = `40f7881` — still 1 commit behind local `HEAD`. **Codeberg push blocker is unchanged/unresolved.**
+- `gitea/main` = `1cbdc1e` — still identical to local `HEAD`.
+- `github/main` = `68104bd` — still 4 commits behind local `HEAD`.
+
+This exactly reproduces §2's numbers. `git branch -a` also still shows `remotes/github/backup/github-main-before-codeberg-copy-20260717-185100`, corroborating §9 Q2's observation that GitHub may be an intentional pre-migration snapshot rather than a required mirror.
+
+```
+$ gcc -std=c99 -O0 src/claro.c -o /tmp/claro_build_review -lm
+```
+→ Exit 0. Same three `-Wformat-truncation` warnings in `create_package_folder()` (`src/claro.c:587`, on the `path`/`meta`/`readme` `snprintf` calls), verbatim to §4/§5 item 4. No new warnings, no errors.
+
+```
+$ cmp /tmp/claro_build_review ./claro
+```
+→ **Identical**, confirming the tracked binary is still byte-for-byte reproducible from `HEAD`.
+
+```
+$ ./claro --version
+```
+→ `Claro v1.18.26` — unchanged.
+
+```
+$ ./claro test
+```
+→ `PASS: 0 failure(s)`.
+
+```
+$ ./claro validate
+```
+→ Full doctor + test + example-check + typecheck good/bad matrix, ending `Validation passed. Claro v1.18.26 foundation checks are ready for use.`
+
+```
+$ python3 tools/validate_typecheck_diagnostics.py
+```
+→ Exit 0, `Typecheck diagnostics validation complete`, same fixture set including the two newest method-diagnostic fixtures.
+
+```
+$ ./claro doctor
+```
+→ All `OK`, `Claro folder looks ready.`
+
+```
+$ ./claro check examples/quiz.claro && make check
+```
+→ All four checks (`quiz.claro`, `01_hello.claro`, `03_variables.claro`, `08_functions.claro`) `OK`.
+
+```
+$ ./claro typecheck tests/typecheck_method_unknown_method_bad.claro
+```
+→ `tests/typecheck_method_unknown_method_bad.claro:11: Object Player has no method fly. Check the method name or add TEACH fly inside CLASS Player.` (exit 1, as expected).
+
+```
+$ cat .forgejo/workflows/ci.yml
+```
+→ Confirmed: CI runs `make`, `./claro test`, three lesson `claro check` calls, and `tools/validate_rc3.py` only. It does **not** run `claro validate` or `tools/validate_typecheck_diagnostics.py`. §5 item 6's CI coverage gap is confirmed still present, unchanged.
+
+```
+$ cat .gitignore
+```
+→ Still lists `claro` and `claro.exe` alongside `*.o`, `*.obj`, `*.out`, `.DS_Store`, `Thumbs.db` — both tracked-yet-ignored binaries remain as described in §3/§5 item 3.
+
+```
+$ git status --porcelain | grep '^??'
+```
+→ `CODEBERG_PUSH_HANDOFF.md` and `HANDOFF_GPT56_LUNA.md` only, before and after all commands above — no stray files (`packages/`, `MyProject/`, etc.) left behind by any test/validate run.
+
+Also re-read `docs/CURRENT_STATUS.md` (Static type safety and Objects/classes sections) and `docs/ROADMAP.md` ("Near-term cleanup priorities" and "Complete-platform milestones §1–2"): both still list "broader object field checking beyond simple direct assignments," "method return typing," and "type checking through branches and loops" as still-needed — consistent with, and directly supporting, §8 item 4's recommendation. No doc changes since the original handoff was written.
+
+### Facts that changed between the two passes
+
+None. Branch state, remote divergence, binary reproducibility, all test/validate results, CI workflow contents, and `.gitignore` contents are identical to what §1–§9 already documented. The only diff is that `HANDOFF_GPT56_LUNA.md` itself now exists as a second untracked file (it was being written during §2's snapshot).
+
+### Newly discovered risks (from this pass)
+
+- None beyond what §5/§6 already capture. One clarification worth flagging explicitly for Luna: **both untracked handoff files (`CODEBERG_PUSH_HANDOFF.md`, `HANDOFF_GPT56_LUNA.md`) currently exist only in this local checkout.** Since they're untracked, they will not survive being lost if this checkout is discarded, and they are not visible on any of the three remotes. If this handoff's contents are meant to persist beyond this machine, they need to be committed (as a deliberate, human-approved action — not done in this session) or copied out manually.
+
+### Recommended next task for Luna (unchanged from §8, re-confirmed)
+
+The priority order in §8 still holds exactly as written:
+1. Resolve the Codeberg push credential issue (human/credential-owner action, still blocking `origin/main` by 1 commit).
+2. Decide GitHub's intended relationship to Codeberg (mirror vs. intentional pre-migration snapshot) before treating its 4-commit staleness as a bug.
+3. Add `claro validate` and `tools/validate_typecheck_diagnostics.py` to `.forgejo/workflows/ci.yml` — still a small, low-risk, high-value gap, re-confirmed present this pass.
+4. Continue the object/method diagnostic series — object-field checking for compound assignment or method-return-type checking are the best-supported next slices per the current `docs/CURRENT_STATUS.md`/`docs/ROADMAP.md` wording, re-read and re-confirmed this pass.
+5. Consider extracting `typecheck_file()` (`src/claro.c:550`) into named per-statement helpers before the diagnostic series grows further — still purely mechanical, still unattempted.
+
+No new task was surfaced by this re-verification pass; its purpose was confidence, not discovery. Luna can treat §1–§9 as current as of `2026-08-17`, not stale.

Makefile

@@ -2,11 +2,14 @@ CC = gcc
 CFLAGS = -std=c99 -O0
 LDFLAGS = -lm
 
-all: claro
+all: claro claro.exe
 
 claro: src/claro.c
 	$(CC) $(CFLAGS) -o claro src/claro.c $(LDFLAGS)
 
+claro.exe: src/claro.c
+	$(CC) $(CFLAGS) -o claro.exe src/claro.c $(LDFLAGS)
+
 test: claro
 	./claro test
 

README.md

@@ -1,48 +1,100 @@
-# Claro v1.18.26
+# Claro
 
 <img src="assets/Claro_Logo.jpg" alt="Claro logo" width="160">
 
-Claro is a small, readable scripting language designed to help beginners — especially learners with learning disabilities — learn programming without being overwhelmed by punctuation-heavy syntax.
+**Claro** is a small, readable scripting language for beginners. It is designed to make programming approachable without requiring punctuation-heavy syntax, while still providing a path toward functions, types, objects, files, packages, and networking.
 
-Claro stays plain-text first: simple enough to start with `SET name "Jon"`, but able to grow into stronger typed scripts, objects, packages, networking, and tooling over the v1 line. Graphics/SDL work is experimental and not enabled in the stable executable.
+Current release: **v1.18.26**
 
-## Status
+## Quick start
 
-**Current release:** Claro v1.18.26
+Build Claro with a C99 compiler and `make`:
-
-Validated in this package:
 
 ```bash
-./claro --version
+make
-# Claro v1.18.26
-
-./claro test
-# PASS: 0 failure(s)
-
-./claro validate
-# Validation passed. Claro v1.18.26 networking reliability is ready for use.
 ```
 
-## Beginner-first syntax
+Run a script:
 
-Claro accepts both the sentence-like style and the shorter simple style:
+```bash
+./claro lessons/01_hello.claro
+./claro examples/quiz.claro
+```
+
+Check a script without running it:
+
+```bash
+./claro check examples/quiz.claro
+```
+
+Run the built-in test suite and validation checks:
+
+```bash
+./claro test
+./claro validate
+```
+
+Useful commands:
+
+```text
+claro help
+claro --version
+claro doctor
+claro examples
+claro repl
+claro new MyProject
+claro run
+claro fmt file.claro
+claro typecheck file.claro
+```
+
+## First Claro program
 
 ```claro
-SET name TO "Jon"
+SAY "Hello from Claro!"
-SET name "Jon"
-SET city to "Edmonton"
 
 ASK "What is your name?" name
 SAY "Hello " + name
-
-IF name = "Jon"
-    SAY "Nice name!"
-END
 ```
 
-Older forms such as `ASK "Name?" AS name`, `ENDIF`, `DONE`, and `LEARNED` still work so older Claro examples do not break.
+Claro accepts both the short beginner-friendly form and older compatibility forms. For example, these are both valid:
 
-## Simple functions
+```claro
+SET name "Jon"
+SET name TO "Jon"
+```
+
+## Core language features
+
+### Decisions and loops
+
+```claro
+SET score 10
+
+IF score >= 5
+    SAY "Good job!"
+ELSE
+    SAY "Try again."
+END
+
+DO 3 TIMES
+    SAY "Practice"
+DONE
+```
+
+### Lists and maps
+
+```claro
+SET names AS LIST OF TEXT TO LIST
+ADD "Ada" TO names
+ADD "Grace" TO names
+
+FOR EACH name IN names
+    SAY name
+DONE
+```
+
+### Functions
 
 ```claro
 TEACH greet name
@@ -52,30 +104,24 @@ END
 DO greet "Jon"
 ```
 
-Older function syntax still works:
+The older compatibility syntax remains supported:
 
 ```claro
 TEACH greet TAKES name
-    SAY "Hello " + name
+    RETURN "Hello " + name
 LEARNED
 
 CALL greet WITH "Jon"
+SAY RESULT
 ```
 
-## Objects and classes
+### Objects and classes
-
-Classes can have typed fields and simple methods.
 
 ```claro
 CLASS Player
     HAS name TEXT
     HAS score NUMBER
 
-    TEACH show
-        SAY name
-        SAY score
-    END
-
     TEACH add points
         SET score score + points
     END
@@ -84,168 +130,52 @@ END
 NEW Player player
 SET player.name "Jon"
 SET player.score 10
-
-DO player.show
 DO player.add 5
 SAY player.score
 ```
 
-Object helper commands:
+### Type checking
 
-```claro
+Type annotations are optional for beginners:
-OBJECT CLASS player AS kind
-OBJECT FIELDS player AS fields
-```
-
-## Static type safety
-
-Beginners can still write the simplest form:
-
-```claro
-SET name "Jon"
-```
-
-When learners are ready, Claro can protect variables with plain-text types:
 
 ```claro
 SET score NUMBER 10
 SET name TEXT "Jon"
 SET ready YESNO YES
-
-TYPE OF score AS kind
-SAY kind
-
 CHECK TYPE score IS NUMBER
 ```
 
-Advanced container checks are available through `claro typecheck`:
+Run static checks with:
+
+```bash
+./claro typecheck examples/type_hardening.claro
+```
+
+Claro provides learner-facing diagnostics for many incorrect variable, function, method, and object-field types. For an explicitly typed object field, the separated form needs both `AS TYPE TO value`, so `SET player.score AS NUMBER` explains how to add `TO` and a value. Type checking is still a focused foundation rather than a complete static type system.
+
+## Files, JSON, and standard helpers
+
+Claro includes commands and libraries for practical scripts:
 
 ```claro
-SET names AS LIST OF TEXT TO LIST
+WRITE FILE "note.txt" WITH "Hello from Claro"
-ADD "Ada" TO names
+READ FILE "note.txt" AS note
-
+SAY note
-SET scores AS MAP OF NUMBER TO MAP
-PUT scores KEY "math" VALUE 98
 ```
 
-`claro typecheck` also has an early function-argument diagnostic foundation. A function can state a parameter expectation with `CHECK TYPE`, and calls with the wrong value type get a friendly error:
+Standard-library modules include path and collection helpers:
 
 ```claro
-TEACH square amount
+IMPORT "lib/path.claro" AS path
-    CHECK TYPE amount IS NUMBER
+CALL path.join WITH "notes", "today.txt"
-    SAY amount
+SAY RESULT
-END
-
-DO square "oops"
 ```
 
-```text
+See `docs/STDLIB.md` for the current helper API.
-Type mismatch for function square: parameter amount needs NUMBER, but this argument looks like TEXT.
-```
 
-For functions with more than one checked parameter, Claro reports each mismatched argument with the parameter name:
+## Projects and packages
 
-```claro
+Create a project:
-TEACH label TAKES name, age
-    CHECK TYPE name IS TEXT
-    CHECK TYPE age IS NUMBER
-END
-
-CALL label WITH 7, "old"
-```
-
-The same narrow diagnostic foundation now covers simple object method calls when the object was created with `NEW` and the method body uses `CHECK TYPE` for a parameter. Correct calls such as `DO player.add 5` are covered by validation, and wrong-type calls get a focused learner-facing error:
-
-```claro
-CLASS Player
-    HAS score NUMBER
-
-    TEACH add points
-        CHECK TYPE points IS NUMBER
-        SET score score + points
-    END
-END
-
-NEW Player player
-DO player.add "five"
-```
-
-```text
-Type mismatch for method Player.add: parameter points needs NUMBER, but this argument looks like TEXT.
-```
-
-If a learner calls a simple object method before creating the object with `NEW`, `claro typecheck` now points to the missing setup instead of letting the dotted call look like an ordinary unknown function:
-
-```text
-Object player is not known yet. Create it with NEW ClassName player before calling player.add.
-```
-
-For simple object fields created with `NEW Class name`, `claro typecheck` also catches direct wrong-type field assignments such as `SET player.score "ten"` when the class says `HAS score NUMBER`:
-
-```text
-Type mismatch for field player.score: expected NUMBER, but this value looks like TEXT.
-```
-
-It also catches direct assignments to undeclared fields and suggests the matching `HAS` line:
-
-```text
-Object Player has no field level. Check the field name or add HAS level NUMBER to the class.
-```
-
-TEXT-valued and YESNO-valued field-name mistakes are validated too:
-
-```text
-Object Player has no field nickname. Check the field name or add HAS nickname TEXT to the class.
-Object Player has no field ready. Check the field name or add HAS ready YESNO to the class.
-```
-
-If Claro cannot infer the value type for an undeclared field yet, it avoids exposing the internal `ANY` placeholder and keeps the hint beginner-facing:
-
-```text
-Object Player has no field level. Check the field name or add the field to the class with the right type.
-```
-
-Direct object-field `CHECK TYPE` metadata mismatches are validated for NUMBER, TEXT, and YESNO fields too. For example, after `HAS ready YESNO` and `SET player.ready YES`, `CHECK TYPE player.ready IS TEXT` reports:
-
-```text
-Type check failed: expected TEXT, but player.ready looks like YESNO.
-```
-
-If `CHECK TYPE` names an undeclared field, Claro now gives the same class-and-field hint as direct field assignment. For example, `CHECK TYPE player.level IS NUMBER` after `NEW Player player` reports:
-
-```text
-Object Player has no field level. Check the field name or add HAS level NUMBER to the class.
-```
-
-TEXT expectations are validated with the same pattern, for example `CHECK TYPE player.nickname IS TEXT` reports:
-
-```text
-Object Player has no field nickname. Check the field name or add HAS nickname TEXT to the class.
-```
-
-YESNO expectations are validated too; `CHECK TYPE player.enabled IS YESNO` reports:
-
-```text
-Object Player has no field enabled. Check the field name or add HAS enabled YESNO to the class.
-```
-
-If a learner checks a field before creating the object with `NEW`, `claro typecheck` points to the missing object setup:
-
-```text
-Object player is not known yet. Create it with NEW ClassName player before checking player.score.
-```
-
-The same missing-object guidance is now validated for direct field assignment before `NEW`:
-
-```text
-Object player is not known yet. Create it with NEW ClassName player before setting player.score.
-```
-
-## Project and package workflow
-
-v1.18.26 hardens Claro's project/package workflow.
-
-Create a starter project:
 
 ```bash
 claro new MyProject
@@ -253,18 +183,17 @@ cd MyProject
 claro run
 ```
 
-Manage packages:
+Manage local project packages:
 
 ```bash
 claro package init
 claro package add text
 claro package list
-claro package remove text
 claro package doctor
 claro package lock
 ```
 
-Claro now creates and maintains:
+Project metadata is stored in:
 
 ```text
 claro.project
@@ -272,99 +201,92 @@ claro.lock
 packages/
 ```
 
-Package names are checked so unsafe names such as `../bad` are rejected.
+The current package system is local and foundational. Remote registries, publishing, version constraints, and package signature verification are not yet stable features.
-
-
-## Standard-library path and collection helpers
-
-Claro includes tested, namespaced helpers for everyday programs:
-
-```claro
-IMPORT "lib/path.claro" AS path
-IMPORT "lib/collections.claro" AS collections
-
-CALL path.join WITH "notes", "today.txt"
-SAY RESULT
-
-SET names AS LIST OF TEXT TO LIST
-ADD "Ada" TO names
-ADD "Grace" TO names
-CALL collections.join WITH names, " and "
-SAY RESULT
-```
-
-The `path` module includes `join`, `basename`, `dirname`, `ext`, `stem`, and `absolute`. The `collections` module includes list length/search/join/reverse helpers and map key/value/default-access helpers. See `docs/STDLIB.md` for the complete, current API.
 
 ## Networking
 
-v1.18.26 adds safer beginner networking commands with offline `claro://` test URLs.
+Claro supports beginner-oriented HTTP commands and offline `claro://` test URLs:
 
 ```claro
-HTTP CHECK "claro://hello" AS safe
-SAY safe
-
 HTTP GET "claro://hello" AS page STATUS status
 SAY page
 SAY status
-
-HTTP SAVE "claro://json" TO "network_demo.json" AS saveStatus
-SAY saveStatus
 ```
 
-The latest HTTP status is also stored in `LASTHTTP`. Real `http://` and `https://` requests use `curl` when available, while `claro://` works offline for lessons and tests.
+Real HTTP and HTTPS requests use `curl` when available. The offline URLs make networking lessons and tests deterministic.
 
-## Useful commands
+## Current status
 
-```bash
+### Stable foundation
-claro help
-claro --version
-claro test
-claro validate
-claro doctor
-claro examples
-claro check examples/quiz.claro
-claro typecheck examples/type_hardening.claro
-claro fmt examples/quiz.claro
-claro repl
-claro new MyProject
-claro run
-claro package init
-claro package add text
-claro package list
-claro package doctor
-claro ide
-```
 
-## Good first scripts
+- Variables, output, input, expressions, and control flow
+- Loops, lists, maps, text, JSON, and file operations
+- Functions and compatibility syntax
+- Friendly errors and script checking
+- Path and collection helpers
+- Offline networking examples
 
-```bash
+### Foundation present
-./claro lessons/01_hello.claro
+
-./claro examples/quiz.claro
+- Static type checking
-./claro examples/simple_functions.claro
+- Objects and classes
-./claro examples/objects_classes.claro
+- Local projects and packages
-./claro examples/text_polish.claro
+- Networking beyond the offline test layer
-./claro examples/networking.claro
+- Cooperative tasks/concurrency helpers
-```
+- IDE metadata and completion helpers
+
+These areas work in focused scenarios but still need broader coverage and polish.
+
+### Experimental or planned
+
+- Real SDL graphics and game-oriented graphics support
+- Web-server syntax and routes
+- Remote package registry
+- Full editor extension/LSP support
+- A complete concurrency scheduler
+
+Do not treat experimental graphics as a stable cross-platform game runtime yet.
 
 ## Documentation map
 
-If you are new to Claro, start here:
+Recommended reading order for new learners:
 
 1. `docs/QUICK_START.md`
 2. `docs/FIRST_HOUR.md`
 3. `lessons/README.md`
 4. `docs/CLI.md`
-5. `docs/CURRENT_STATUS.md`
+5. `docs/SPEC.md`
+6. `docs/CURRENT_STATUS.md`
 
-Feature references by current status:
+Useful references:
 
-- **Ready for beginner lessons:** language reference (`docs/SPEC.md`), friendly errors/checking (`docs/ERRORS.md`, `docs/LINTER.md`, `docs/TESTING.md`), formatter (`docs/FORMATTER.md`), and simple functions (`docs/SIMPLE_FUNCTIONS.md`).
+- `docs/ERRORS.md` — friendly diagnostics
-- **Foundation present, still being polished:** static typing (`docs/ADVANCED_STATIC_TYPING.md`), objects/classes (`docs/V1_15_OBJECTS_CLASSES.md`), local projects/packages (`docs/V1_16_PACKAGES_PROJECTS.md`), HTTP client networking (`docs/V1_17_NETWORKING.md`), cooperative tasks (`docs/CONCURRENCY.md`), and IDE metadata/helper support (`docs/IDE.md`).
+- `docs/SIMPLE_FUNCTIONS.md` — function syntax
-- **Planned or experimental, not stable beginner features yet:** remote package registry (`docs/PACKAGE_REGISTRY.md`), web server API (`docs/WEB_SERVER_PLAN.md`), full editor extension/LSP (`docs/EDITOR_EXTENSION_PLAN.md`), and real SDL graphics (`docs/GRAPHICS.md`, `docs/SDL12.md`).
+- `docs/STDLIB.md` — standard helpers
-- **Roadmaps:** `docs/ROADMAP.md` for the current v1 direction and `docs/COMPLETE_PLATFORM_ROADMAP.md` for the larger platform goal.
+- `docs/TESTING.md` — test and validation workflow
+- `docs/FORMATTER.md` — formatting scripts
+- `docs/IDE.md` — editor metadata and helper support
+- `docs/ROADMAP.md` — current development direction
 
-Historical release notes and validation logs are kept in files such as `docs/RC*_NOTES.md`, `docs/RC*_VALIDATION.md`, and older `docs/V1_*_VALIDATION.md`. They are useful for project history, but they are not the beginner starting path.
+Historical release notes are kept under `docs/RC*_*.md` and older `docs/V1_*_VALIDATION.md` files. They describe project history rather than the current beginner path.
 
-## Release direction
+## Development
 
-Claro should remain in the `v1.xx.yy` line for normal development. A future Claro v2 should mean a full rewrite years later, not an ordinary feature update.
+The interpreter is implemented in `src/claro.c` and currently builds as a C99 program:
+
+```bash
+make
+make test
+make check
+```
+
+The repository includes examples, lessons, validation tools, and a test suite. Before submitting changes, run:
+
+```bash
+./claro test
+./claro validate
+```
+
+## License
+
+See [`LICENSE`](LICENSE) for the project license.

docs/ADVANCED_STATIC_TYPING.md

@@ -2,6 +2,44 @@
 
 Claro v1.18.26 adds the first advanced static-typing foundation: typed containers checked by `claro typecheck`.
 
+## Complete `TYPE OF` statements
+
+`TYPE OF` needs an expression, `AS`, and a result name. If the expression is missing, `claro typecheck` gives a repair example instead of silently creating the result variable:
+
+```claro
+TYPE OF AS kind
+```
+
+```text
+TYPE OF needs an expression before AS. Try: TYPE OF score AS kind.
+```
+
+Add the value whose type should be stored, such as `TYPE OF score AS kind`.
+
+If the result name is missing after `AS`, `claro typecheck` names the missing piece and shows the complete beginner form:
+
+```claro
+TYPE OF score AS
+```
+
+```text
+TYPE OF needs a result name after AS. Try: TYPE OF score AS kind.
+```
+
+Add a result name after `AS`, such as `kind`.
+
+Explicit short field annotations also need a value after the type. If a learner writes `SET player.score NUMBER` instead of `SET player.score NUMBER 10`, `claro typecheck` gives a repair hint:
+
+```text
+SET player.score needs a value after type NUMBER. Add one expression.
+```
+
+Class fields need a type after the field name. If a learner writes `HAS score` instead of `HAS score NUMBER`, `claro typecheck` explains the missing piece:
+
+```text
+Class Player field score is missing a type. Add a type such as NUMBER, TEXT, YESNO, LIST, or MAP after the field name.
+```
+
 ## Typed lists
 
 ```claro
@@ -43,6 +81,472 @@ Output:
 Type mismatch for map scores: expected NUMBER value, but this value looks like TEXT.
 ```
 
+## Nested container values
+
+A typed list can contain a typed map. `claro typecheck` keeps the map's own type metadata while checking the outer list:
+
+```claro
+SET people AS LIST OF MAP TO LIST
+SET person AS MAP OF TEXT TO MAP
+PUT person KEY "name" VALUE "Ada"
+ADD person TO people
+```
+
+This is accepted with `Type check OK`. More complex nested container operations and full key/value inference remain future work.
+
+## Unknown fields inside methods
+
+When a method assigns a known value to a bare name that is not a parameter, local variable, or declared class field, `claro typecheck` reports the missing field instead of silently treating the typo as a new variable:
+
+```claro
+CLASS Player
+    HAS score NUMBER
+
+    TEACH train
+        SET level 3
+    END
+END
+```
+
+The diagnostic is:
+
+```text
+Object Player has no field level. Check the field name or add HAS level NUMBER to the class.
+```
+
+This narrow check covers direct method assignments with a known expression in both modern `TEACH ... END` and compatibility `TEACH ... TAKES ... LEARNED` methods. The focused validation matrix keeps matching positive NUMBER, TEXT, and YESNO assignments in both syntax generations, including `SET ready value` followed by `DO player.toggle YES`. Broader local-variable and control-flow analysis remains future work.
+
+## Compatibility conditional returns
+
+The same every-path return check applies to older `TAKES` / `LEARNED` functions. If one branch returns but the other branch does not, `claro typecheck` explains how to repair both paths:
+
+```claro
+TEACH choose TAKES flag RETURNS NUMBER
+    IF flag
+        RETURN 1
+    END
+LEARNED
+```
+
+```text
+Function choose declares RETURNS NUMBER but does not return a NUMBER value on every path. Add RETURN to each branch or after the conditional.
+```
+
+Use `ELSE` with a `RETURN` value, or add a return after the conditional. This compatibility example is part of the focused release validation matrix.
+
+A complete compatibility conditional is accepted when both branches return the declared type:
+
+```claro
+TEACH choose TAKES flag RETURNS NUMBER
+    IF flag
+        RETURN 1
+    ELSE
+        RETURN 2
+    END
+LEARNED
+```
+
+This positive `TAKES` / `LEARNED` example is checked by both the focused typecheck validator and `claro validate`.
+
+## Complete conditional returns
+
+### Return expressions that need more information
+
+When a typed function or method returns a name or expression whose type the focused checker cannot infer yet, `claro typecheck` reports that clearly instead of silently accepting it:
+
+```claro
+TEACH square amount RETURNS NUMBER
+    RETURN missing
+END
+```
+
+```text
+Function square's return value could not be understood yet. Use a NUMBER expression after RETURN.
+```
+
+Use a known typed value, such as a parameter checked with `CHECK TYPE`, while broader expression inference remains future work.
+
+The same learner-facing diagnostic applies to compatibility functions written with `TAKES` / `LEARNED`, so older lessons do not get a less-helpful error when a return expression is still unknown.
+
+Known NUMBER parameters can also be used in arithmetic return expressions. Numeric division is accepted when both operands are known numbers:
+
+```claro
+TEACH halve amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount / 2
+END
+```
+
+This valid division case is included in the focused typecheck validation matrix beside the diagnostic for using a TEXT operand in division.
+
+Subtraction follows the same rule:
+
+```claro
+TEACH difference amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount - 2
+END
+```
+
+The focused validator checks this positive function case as well as the matching subtraction diagnostic for a TEXT operand.
+
+The same protection applies to object methods. A checked NUMBER parameter can be divided by a number and returned as NUMBER:
+
+```claro
+CLASS Player
+    TEACH total amount RETURNS NUMBER
+        CHECK TYPE amount IS NUMBER
+        RETURN amount / 2
+    END
+END
+```
+
+This valid method-division case is included in the focused typecheck validation matrix beside the method diagnostic for using a TEXT operand in division.
+
+Return declarations accept the same case-insensitive keyword style as the rest of Claro. For example, `returns NUMBER` still enables return checking:
+
+```claro
+TEACH square amount returns NUMBER
+    RETURN "oops"
+END
+```
+
+This reports a normal return mismatch naming `NUMBER` and `TEXT`; capitalization style does not disable the safety check.
+
+The same case-insensitive return declaration rule applies to compatibility methods. A lowercase `returns` still checks the method's `RETURN` value:
+
+```claro
+CLASS Player
+    TEACH score TAKES amount returns NUMBER
+        RETURN "oops"
+    LEARNED
+END
+```
+
+`claro typecheck` reports:
+
+```text
+Type mismatch for return from Player.score: expected NUMBER, but this value looks like TEXT.
+```
+
+A correct compatibility call also remains valid when the declaration uses lowercase `returns`:
+
+```claro
+NEW Player player
+CALL player.score WITH 4
+```
+
+This success path is included in the focused typecheck validation matrix.
+
+Compatibility methods also keep arithmetic return checks when they use the older
+`TAKES` / `LEARNED` spelling. For example, this checked division remains a valid
+NUMBER return:
+
+```claro
+CLASS Player
+    TEACH score TAKES amount RETURNS NUMBER
+        CHECK TYPE amount IS NUMBER
+        RETURN amount / 2
+    LEARNED
+ENDCLASS
+```
+
+This matching `CALL player.score WITH 4` path is included in focused validation.
+
+The same compatibility method return check explains an addition mistake instead of
+falling back to a generic return error:
+
+```claro
+CLASS Player
+    TEACH total TAKES amount RETURNS NUMBER
+        CHECK TYPE amount IS NUMBER
+        RETURN amount + "oops"
+    LEARNED
+ENDCLASS
+```
+
+`claro typecheck` reports:
+
+```text
+Type mismatch for return from Player.total: addition needs NUMBER values, but "oops" looks like TEXT.
+```
+
+This negative compatibility fixture is part of focused release validation.
+
+Compatibility methods support numeric subtraction in the same focused way:
+
+```claro
+CLASS Player
+    TEACH score TAKES amount RETURNS NUMBER
+        CHECK TYPE amount IS NUMBER
+        RETURN amount - 2
+    LEARNED
+ENDCLASS
+```
+
+The matching `CALL player.score WITH 4` success path is included in focused validation alongside the modern method subtraction case.
+
+Compatibility methods also keep numeric multiplication return checks. This older
+`TAKES` / `LEARNED` spelling accepts a checked NUMBER parameter multiplied by a
+number and returned as NUMBER:
+
+```claro
+CLASS Player
+    TEACH score TAKES amount RETURNS NUMBER
+        CHECK TYPE amount IS NUMBER
+        RETURN amount * 2
+    LEARNED
+ENDCLASS
+```
+
+The matching `CALL player.score WITH 4` success path is included in focused validation.
+
+Compatibility method division mistakes receive the same operation-specific guidance:
+
+```claro
+CLASS Player
+    TEACH total TAKES amount RETURNS NUMBER
+        CHECK TYPE amount IS NUMBER
+        RETURN amount / "oops"
+    LEARNED
+ENDCLASS
+```
+
+`claro typecheck` reports:
+
+```text
+Type mismatch for return from Player.total: division needs NUMBER values, but "oops" looks like TEXT.
+```
+
+This negative compatibility fixture is part of focused release validation.
+
+When a function declares a return type, `claro typecheck` accepts nested conditionals when every branch returns a value of that type:
+
+```claro
+TEACH choose flag RETURNS NUMBER
+    IF flag
+        IF flag
+            RETURN 1
+        ELSE
+            RETURN 2
+        END
+    ELSE
+        RETURN 3
+    END
+END
+```
+
+An incomplete branch still produces a missing-return diagnostic. Deeper control-flow analysis through loops and more complex conditions remains planned.
+
+## Object aliases and field checks
+
+When a simple object is assigned to another variable, `claro typecheck` preserves its class for direct field assignments:
+
+```claro
+NEW Player player
+SET alias player
+SET alias.score 10
+```
+
+If the value has the wrong type, the diagnostic names the alias and the expected class field type:
+
+```text
+Type mismatch for field alias.score: expected NUMBER, but this value looks like TEXT.
+```
+
+This is intentionally limited to simple aliases. Broader object-flow analysis through branches, loops, and complex expressions remains planned.
+
+The same field-assignment check follows a second simple alias. This lets a learner use a more descriptive name without losing the class field type:
+
+```claro
+SET backup alias
+SET backup.score "ten"
+```
+
+Output:
+
+```text
+Type mismatch for field backup.score: expected NUMBER, but this value looks like TEXT.
+```
+
+This remains limited to direct assignments through simple alias chains; control-flow and complex object-flow analysis are still planned.
+
+Text operands are also identified when they appear in arithmetic expressions assigned to NUMBER fields. The diagnostic names the operator and the text operand, which catches a common beginner mistake such as adding a text field to a number field:
+
+```claro
+SET player.score player.name + 1
+```
+
+```text
+Type mismatch for field player.score: addition needs NUMBER values, but player.name looks like TEXT.
+```
+
+Subtraction, multiplication, and division use the same beginner-facing guidance:
+
+```claro
+SET player.score player.score - player.name
+```
+
+```text
+Type mismatch for field player.score: subtraction needs NUMBER values, but player.name looks like TEXT.
+```
+
+The same learner-facing result is preserved for multiplication, so the checker does not lose the useful `TEXT` type when the invalid expression uses `*`:
+
+```claro
+SET player.score player.score * player.name
+```
+
+```text
+Type mismatch for field player.score: multiplication needs NUMBER values, but player.name looks like TEXT.
+```
+
+Division is covered in the same way:
+
+```claro
+SET player.score player.score / player.name
+```
+
+```text
+Type mismatch for field player.score: division needs NUMBER values, but player.name looks like TEXT.
+```
+
+Numeric division remains accepted in a NUMBER field, so the type checker protects both sides of this operator without rejecting a valid beginner expression:
+
+```claro
+SET player.score 10
+SET player.score player.score / 2
+```
+
+This example is included in the focused typecheck validation matrix.
+
+Numeric multiplication is accepted in a NUMBER field as well:
+
+```claro
+SET player.score player.score * 2
+```
+
+The focused validation matrix keeps this valid arithmetic case beside the multiplication text-operand diagnostic, so a useful expression is not confused with the nearby beginner mistake.
+
+The expression checker now gives operator-specific guidance for known TEXT operands in subtraction, multiplication, and division, including typed method return expressions. Broader expression inference remains future work.
+
+Compatibility methods use the same arithmetic return checks as modern methods. This older spelling is accepted when a checked NUMBER parameter is used in a numeric addition:
+
+```claro
+CLASS Player
+    TEACH score TAKES amount RETURNS NUMBER
+        CHECK TYPE amount IS NUMBER
+        RETURN amount + 2
+    LEARNED
+ENDCLASS
+
+NEW Player player
+CALL player.score WITH 4
+```
+
+The focused validation matrix covers this positive compatibility example alongside subtraction, multiplication, and division.
+
+The same operator-specific diagnostic is covered for older compatibility methods:
+
+```claro
+CLASS Player
+    TEACH total TAKES amount RETURNS NUMBER
+        CHECK TYPE amount IS NUMBER
+        RETURN amount - "oops"
+    LEARNED
+ENDCLASS
+```
+
+Claro reports:
+
+```text
+Type mismatch for return from Player.total: subtraction needs NUMBER values, but "oops" looks like TEXT.
+```
+
+This keeps `TAKES` / `LEARNED` lessons aligned with the modern method syntax.
+
+Text concatenation is also accepted when the result is assigned to a TEXT field. This keeps a common beginner pattern type-safe without treating every `+` expression as numeric:
+
+```claro
+SET player.name player.name + " Lovelace"
+```
+
+The focused typecheck validation matrix covers this positive case beside the existing numeric-expression and text-operand checks.
+
+The same rule works when the literal comes first:
+
+```claro
+SET player.name "Ada " + player.name
+```
+
+This reverse-order concatenation is also covered by focused validation, so learners can build text from either side without losing the declared `TEXT` field type.
+
+Compatibility methods use the same TEXT concatenation rule. The older `TAKES` / `LEARNED` spelling accepts both operand orders when a method updates declared `TEXT` fields:
+
+```claro
+TEACH full_name TAKES suffix
+    SET first first + suffix
+    SET last "Dr. " + last
+LEARNED
+```
+
+The focused validation matrix covers this compatibility example too, keeping modern and older method lessons aligned.
+
+Two TEXT fields can be combined as well:
+
+```claro
+SET player.name player.name + player.nickname
+```
+
+The focused validation matrix covers this field-to-field form so a learner can build text from named object fields without losing the declared `TEXT` type.
+
+`CHECK TYPE` also preserves TEXT field metadata through the same chained aliases:
+
+```claro
+CLASS Player
+    HAS name TEXT
+END
+
+NEW Player player
+SET alias player
+SET backup alias
+SET player.name "Ada"
+CHECK TYPE backup.name IS TEXT
+```
+
+This confirms the declared field type without requiring the learner to repeat the original object variable name. The broader limits are unchanged: aliases created through branches, loops, or complex expressions are still planned.
+
+`CHECK TYPE` also follows simple aliases for direct field metadata checks. This includes a second alias, so learners can give an object a more descriptive local name without losing the class field information:
+
+```claro
+NEW Player player
+SET alias player
+SET alias.score 10
+CHECK TYPE alias.score IS NUMBER
+```
+
+```claro
+SET backup alias
+CHECK TYPE backup.score IS NUMBER
+```
+
+If the requested type is wrong, the diagnostic names the alias and the declared field type:
+
+```text
+Type check failed: expected TEXT, but alias.score looks like NUMBER.
+```
+
+The same diagnostic remains specific after the second alias:
+
+```claro
+SET backup alias
+CHECK TYPE backup.score IS TEXT
+```
+
+```text
+Type check failed: expected TEXT, but backup.score looks like NUMBER.
+```
+
 ## Function parameter checks
 
 Claro now has a small static-checking foundation for function arguments. Keep the beginner-friendly function syntax, then put the expected type inside the function with `CHECK TYPE`:
@@ -73,6 +577,23 @@ Output:
 Type mismatch for function square: parameter amount needs NUMBER, but this argument looks like TEXT.
 ```
 
+If the learner forgets a checked argument, `claro typecheck` now names the missing parameter and expected type:
+
+```claro
+TEACH square amount
+    CHECK TYPE amount IS NUMBER
+    SAY amount
+END
+
+DO square
+```
+
+Output:
+
+```text
+Function square needs argument amount as NUMBER, but this call does not provide it.
+```
+
 Multiple checked parameters are reported separately, so a learner can fix each argument one at a time:
 
 ```claro
@@ -93,8 +614,92 @@ Type mismatch for function label: parameter name needs TEXT, but this argument l
 Type mismatch for function label: parameter age needs NUMBER, but this argument looks like TEXT.
 ```
 
+If a learner mistypes a function name, `claro typecheck` now names the unknown function and suggests either checking the spelling or adding a matching `TEACH` block. This is covered for both modern `DO` and older compatibility `CALL ... WITH` calls:
+
+```claro
+TEACH square amount
+    CHECK TYPE amount IS NUMBER
+    SAY amount
+END
+
+DO squre 4
+CALL squre WITH 4
+```
+
+Each form reports the same beginner-facing fix:
+
+```text
+Function squre is not known yet. Check the function name or add TEACH squre before calling it.
+```
+
+## 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. `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
+    TEACH score amount RETURNS NUMBER
+        RETURN amount
+    END
+END
+
+NEW Player player
+DO player.score 4
+```
+
+Returning text from this method produces a learner-facing diagnostic that names the class and method:
+
+```text
+Type mismatch for return from Player.score: expected NUMBER, but this value looks like TEXT.
+```
+
+If a method's return expression is not understood yet, the diagnostic names the method and gives the promised type so the learner knows what to replace:
+
+```claro
+CLASS Player
+    TEACH square amount RETURNS NUMBER
+        CHECK TYPE amount IS NUMBER
+        RETURN missing
+    END
+END
+```
+
+```text
+Method Player.square's return value could not be understood yet. Use a NUMBER expression after RETURN.
+```
+
+Methods can also return a typed field declared by their class. A field is available by its simple name inside the method, so `RETURN score` is checked against `HAS score NUMBER` instead of being treated as an unknown expression. Returning that field from a method declared `RETURNS TEXT` reports the same expected-versus-found diagnostic.
+
+This is a focused check for simple return expressions. When a parameter has a `CHECK TYPE` declaration, that known type also informs arithmetic return expressions in functions and methods, so `RETURN amount + 1` is checked against the declared return type. The `RETURNS` keyword is case-insensitive in both modern and compatibility function forms, so `returns NUMBER` keeps working while learners are still getting used to Claro's capitalization. A declared return with no `RETURN`, or with a `RETURN` only inside an `IF`, gets a beginner-facing message explaining that the function may finish without returning the promised type:
+
+```text
+Function choose declares RETURNS NUMBER but does not return a NUMBER value on every path. Add RETURN to each branch or after the conditional.
+```
+
+The focused validation matrix covers modern and compatibility syntax, including a compatibility method that returns a class-declared field, method success and mismatch fixtures, unknown method return expressions, typed field returns, missing returns, and conditional-only returns. It also includes a positive nested `IF`/`ELSE` return example inside a method, so a complete nested method path is protected from regression. Full path-sensitive analysis proving that every `IF`/`ELSE` branch returns remains planned.
+
 ## Object method parameter checks
 
+Method declarations also reject repeated parameter names before calls are checked. This protects both the modern `TEACH ... END` form and the compatibility `TAKES` / `LEARNED` form:
+
+```claro
+CLASS Player
+    TEACH greet name, name
+        SAY name
+    END
+END
+```
+
+```text
+Method Player.greet declares parameter name more than once. Give each parameter a different name.
+```
+
+Give every method parameter a different name. The focused validation matrix covers both method spellings.
+
 Claro also checks simple object method arguments when the method body names a parameter with `CHECK TYPE`. This keeps the method syntax beginner-readable while giving a clearer error before the program runs:
 
 ```claro
@@ -123,9 +728,33 @@ Output:
 Type mismatch for method Player.add: parameter points needs NUMBER, but this argument looks like TEXT.
 ```
 
-Both sides of this narrow method foundation are covered by validation: `tests/typecheck_method_good.claro` checks that `DO player.add 5` is accepted, and `tests/typecheck_method_bad.claro` checks the friendly wrong-type diagnostic.
+If the learner forgets a checked method argument, `claro typecheck` also names the missing method parameter and expected type:
 
-If the method call comes before the object is created, the type checker now gives the learner the missing setup step:
+```claro
+DO player.add
+```
+
+Output:
+
+```text
+Method Player.add needs argument points as NUMBER, but this call does not provide it.
+```
+
+If the learner gives too many arguments to a simple checked method, `claro typecheck` now points to the extra argument instead of silently accepting it:
+
+```claro
+DO player.add 5, 6
+```
+
+Output:
+
+```text
+Method Player.add only accepts 1 argument, but this call gives 2. Remove the extra argument.
+```
+
+Both sides of this narrow method foundation are covered by validation: `tests/typecheck_method_good.claro` checks that `DO player.add 5` is accepted, `tests/typecheck_method_bad.claro` checks the friendly wrong-type diagnostic, `tests/typecheck_method_missing_arg_bad.claro` checks the missing checked-argument diagnostic, and `tests/typecheck_method_extra_arg_bad.claro` checks the extra-argument diagnostic. Multi-method class examples are covered too, including the extra-argument case where the checked method appears after another method in the same class. A compatibility `CALL second.add WITH 5, 6` through a two-step alias is also covered by `tests/typecheck_object_alias_method_call_extra_arg_bad.claro`, preserving the same actionable extra-argument message for older lessons.
+
+If the method call comes before the object is created, the type checker now gives the learner the missing setup step. The modern `DO` form and the older compatibility `CALL ... WITH` form both get this guidance, even when the method name is also a typo:
 
 ```claro
 CLASS Player
@@ -138,18 +767,56 @@ CLASS Player
 END
 
 DO player.add 5
+CALL player.add WITH 5
+CALL player.fly WITH 5
 ```
 
 Output:
 
 ```text
 Object player is not known yet. Create it with NEW ClassName player before calling player.add.
+Object player is not known yet. Create it with NEW ClassName player before calling player.fly.
 ```
 
+If the object exists but the class does not declare the method, Claro now names the class and suggests where to add the missing `TEACH` block. This is validated for the modern `DO player.fly 5` form and the older compatibility `CALL player.fly WITH 5` form:
+
+```claro
+DO player.fly 5
+CALL player.fly WITH 5
+```
+
+Output:
+
+```text
+Object Player has no method fly. Check the method name or add TEACH fly inside CLASS Player.
+```
+
+When a script declares classes, `NEW` also checks that the requested class exists. A typo such as `NEW Plaeyr player` receives a repair hint:
+
+```text
+Class Plaeyr is not known yet. Check the class name or declare CLASS Plaeyr before creating player.
+```
+
+For backward compatibility, a script with no `CLASS` declarations keeps the older permissive `NEW` behavior.
+
 ## Object field assignment checks
 
 Claro also has a narrow static diagnostic for direct object-field assignments. If a class declares a typed field and a script creates a simple object with `NEW Class name`, `claro typecheck` remembers the field type:
 
+Keywords are case-insensitive, including object-field declarations and checks. This equivalent beginner example is accepted too:
+
+```claro
+class Player
+    has score number
+end
+
+new Player player
+set player.score number 10
+check type player.score is number
+```
+
+The focused validation fixture `tests/typecheck_object_field_lowercase_good.claro` protects this lowercased spelling.
+
 ```claro
 CLASS Player
     HAS score NUMBER
@@ -159,6 +826,74 @@ NEW Player player
 SET player.score 10
 ```
 
+An assignment may repeat the field type when the explicit form is easier to read:
+
+```claro
+CLASS Player
+    HAS name TEXT
+END
+
+NEW Player player
+SET player.name TEXT "Ada"
+```
+
+The compatibility-shaped `AS ... TO` form is also accepted when it is clearer to separate the annotation from the value:
+
+```claro
+SET player.score AS NUMBER TO 10
+```
+
+Both explicit forms must agree with the class field declaration. The separated form also needs `TO` before its value; `SET player.score AS NUMBER` reports `SET player.score needs TO after type NUMBER. Try: SET player.score AS NUMBER TO 10.`
+
+Each explicit field annotation accepts one value expression only. Extra words are rejected
+with a repair hint instead of being silently ignored:
+
+```claro
+SET player.score AS NUMBER TO 10 extra
+```
+
+The separated form also needs a value after `TO`:
+
+```claro
+SET player.score AS NUMBER TO
+```
+
+```text
+SET player.score needs a value after type NUMBER and TO. Add one expression.
+```
+
+```text
+SET player.score has extra text after value 10. Keep only the field name, type, TO, and one expression.
+```
+
+The short explicit form is checked too:
+
+```claro
+SET player.score NUMBER 10 extra
+```
+
+```text
+SET player.score has extra text after value 10. Keep only the field name, type, and one expression.
+```
+
+The `AS ... TO` spelling also works inside modern and compatibility object methods:
+
+```claro
+CLASS Player
+    HAS score NUMBER
+
+    TEACH set_score
+        SET score AS NUMBER TO 10
+    END
+END
+```
+
+The older `TAKES` / `LEARNED` method form accepts the same field annotation. Both forms are covered by focused typecheck validation, so method examples can use either the short annotation or the separated `AS ... TO` spelling.
+
+The explicit `TEXT` annotation must agree with the class field declaration. This
+keeps typed field examples consistent with typed variable assignments while
+still allowing the shorter `SET player.name "Ada"` form.
+
 If a learner assigns the wrong value type directly to that known field:
 
 ```claro
@@ -171,6 +906,28 @@ Output:
 Type mismatch for field player.score: expected NUMBER, but this value looks like TEXT.
 ```
 
+Simple expressions are checked too. Text joined with a number has a `TEXT` result, so this mistake is caught before running the program:
+
+```claro
+SET player.name "Ada"
+SET player.score player.name + 1
+```
+
+```text
+Type mismatch for field player.score: expected NUMBER, but this value looks like TEXT.
+```
+
+The reverse mismatch is checked as well. A numeric expression cannot be stored in a `TEXT` field:
+
+```claro
+SET player.score 10
+SET player.name player.score + 1
+```
+
+```text
+Type mismatch for field player.name: expected TEXT, but this value looks like NUMBER.
+```
+
 If a learner assigns to a field the class did not declare, `claro typecheck` now names the object class and suggests the matching `HAS` line:
 
 ```claro
@@ -261,10 +1018,36 @@ Output:
 Object player is not known yet. Create it with NEW ClassName player before setting player.score.
 ```
 
-Both sides of this narrow field foundation are covered by validation: `tests/typecheck_object_field_good.claro` checks that `SET player.score 10` is accepted for a `HAS score NUMBER` field, `tests/typecheck_object_field_text_good.claro` checks that `SET player.name "Ada"` is accepted for a `HAS name TEXT` field, `tests/typecheck_object_field_yesno_good.claro` checks that `SET player.ready YES` is accepted for a `HAS ready YESNO` field, `tests/typecheck_object_field_unknown_object_bad.claro` checks that `SET player.score 10` before `NEW Player player` reports the missing-object assignment diagnostic, `tests/typecheck_object_field_check_type_unknown_object_bad.claro` checks the matching missing-object `CHECK TYPE` diagnostic, and the remaining object-field fixtures cover known-field mismatches, unknown NUMBER/TEXT/YESNO fields, and unknown-field assignments whose value type is not inferable yet.
+Both sides of this narrow field foundation are covered by validation: `tests/typecheck_object_field_good.claro` checks that `SET player.score 10` is accepted for a `HAS score NUMBER` field, `tests/typecheck_object_field_typed_good.claro` checks the explicit `NUMBER` annotation, `tests/typecheck_object_field_text_good.claro` checks that `SET player.name "Ada"` is accepted for a `HAS name TEXT` field, `tests/typecheck_object_field_typed_text_good.claro` checks the explicit `TEXT` annotation, `tests/typecheck_object_field_yesno_good.claro` checks that `SET player.ready YES` is accepted for a `HAS ready YESNO` field, and `tests/typecheck_object_field_typed_yesno_good.claro` checks the explicit `YESNO` annotation. `tests/typecheck_object_field_unknown_object_bad.claro` checks that `SET player.score 10` before `NEW Player player` reports the missing-object assignment diagnostic, `tests/typecheck_object_field_check_type_unknown_object_bad.claro` checks the matching missing-object `CHECK TYPE` diagnostic, and the remaining object-field fixtures cover known-field mismatches, unknown NUMBER/TEXT/YESNO fields, and unknown-field assignments whose value type is not inferable yet.
 
-This slice is intentionally small: it covers direct `NEW Class object` plus `SET object.field value` cases in one file. Broader object flows, aliases, method return checks, and richer object signatures remain future work.
+This slice is intentionally small: it covers direct `NEW Class object` plus `SET object.field value` cases in one file. Field declarations are collected even when a learner writes a simple method before a later `HAS` field, so the type checker can still report the field's declared type. Broader object flows, aliases, method return checks, and richer object signatures remain future work.
+
+Simple functions also get an arity check before running. If a learner defines `TEACH greet name` and then writes `DO greet` without the `name` argument, `claro typecheck` reports:
+
+```text
+Function greet needs 1 argument, but this call gives 0. Add the missing argument.
+```
+
+The older compatibility spelling gets the same beginner-facing result when `WITH` is left empty:
+
+```claro
+CALL greet WITH
+```
+
+Output:
+
+```text
+Function greet needs 1 argument, but this call gives 0. Add the missing argument.
+```
+
+The same method-aware diagnostic is used when a method directly assigns the wrong value to a class field. For example, `SET name 123` inside `Player.rename` reports `Type mismatch for field name in Player.rename: expected TEXT, but this value looks like NUMBER.` The operator-specific form also remains available: `SET score score + name` inside `Player.add RETURNS NUMBER` reports `Type mismatch for field score in Player.add: addition needs NUMBER values, but name looks like TEXT.` YESNO fields use the same clear method context: assigning text to `HAS ready YESNO` inside `Player.toggle` reports `Type mismatch for field ready in Player.toggle: expected YESNO, but this value looks like TEXT.` Both modern `DO` and compatibility `CALL ... WITH` method forms are covered by the focused validation matrix. These focused checks cover typed method bodies; broader control-flow and object-flow analysis remains planned.
 
 ## Status
 
 This is currently a static checker feature. It improves `claro typecheck` and validation confidence for `DO` and compatibility `CALL ... WITH` function calls, simple `DO object.method ...` calls where the object was created with `NEW Class name`, and direct assignments to known object fields. Runtime enforcement for every container mutation and richer function/object signatures can be added later after the syntax is classroom-tested.
+
+Method-body field assignments are covered in both modern and compatibility syntax, including a valid YESNO assignment through `TEACH toggle TAKES value` and `CALL player.toggle WITH YES`. Method-body `CHECK TYPE` metadata has the same balanced coverage: a modern `DO player.toggle YES` example and the compatibility `CALL` example both verify a declared YESNO field. The focused release validator keeps these positive examples beside the wrong-type diagnostics.
+
+A bare field typo inside a method's `CHECK TYPE` is also checked now. For example, `CHECK TYPE level IS NUMBER` in `Player.train` reports `Object Player has no field level. Check the field name or add HAS level NUMBER to the class.` The older `TAKES` / `LEARNED` method spelling receives the same diagnostic. This keeps method metadata checks consistent with direct method-field assignments and uses the expected type to make the repair actionable.
+
+Inline method-field annotations are checked for known type names too. For example, `SET score AS BANANA TO 10` inside `Player.set_score` reports `Field score in Player.set_score needs a known type such as NUMBER, TEXT, or YESNO, but BANANA is not a Claro type. Use NUMBER for score.`

docs/CLI.md

@@ -58,7 +58,7 @@ claro package doctor
 claro package lock
 ```
 
-The v1.18.26 package command is a safer local project-file helper. It creates `claro.project`, `claro.lock`, and local folders under `packages/`. It is not yet an online package registry.
+The v1.18.26 package command is a safer local project-file helper. It creates `claro.project`, `claro.lock`, and local folders under `packages/`. Package names may appear only once in `claro.project`; `claro package doctor` reports duplicate entries so the lockfile stays unambiguous. It also requires the project manifest to have exactly one non-empty `name:` field. It is not yet an online package registry.
 
 ## IDE metadata
 

docs/CURRENT_STATUS.md

@@ -9,6 +9,44 @@ This file is the beginner-safe status map for the current package. It separates
 - **Experimental/planned**: do not rely on it in beginner lessons yet.
 - **Historical**: kept for release history, not current instructions.
 
+## Security and correctness review progress
+
+The v1.18.26 review identified missing-argument reads in standard-library built-ins. The current runtime now validates required argument counts centrally before any builtin indexes `args[]`. Covered calls include `math.abs`, `math.clamp`, `random.seed`, `random.int`, text helpers, CSV helpers, path helpers, and collection helpers. Missing arguments produce a beginner-facing `needs N arguments` runtime error.
+
+Focused regression coverage: `tests/38_builtin_arity.claro`, `tests/39_random_inverted_range.claro`, and `tests/40_call_depth_guard.claro`.
+
+The runtime now rejects inverted `random.int` ranges before modulo arithmetic with: `random.int needs the lower bound to be less than or equal to the upper bound.` This prevents invalid ranges from producing incorrect values or a divide-by-zero signal.
+
+User-defined function and object-method calls now have a documented maximum active call depth of 256. Exceeding it produces: `Claro function call depth exceeded the safe limit of 256. Simplify the recursion or add a stopping condition.` Ordinary non-recursive beginner programs are unaffected.
+
+Verified in this checkout on 2026-09-23:
+
+- `gcc -std=c99 -O0 -g -fsanitize=address,undefined src/claro.c -o /tmp/claro-call-depth-asan -lm` plus `ASAN_OPTIONS=detect_leaks=0 /tmp/claro-call-depth-asan tests/40_call_depth_guard.claro`: expected diagnostic; no AddressSanitizer or UndefinedBehaviorSanitizer report.
+- `gcc -std=c99 -O0 -g -fsanitize=address,undefined src/claro.c -o /tmp/claro-arity-asan -lm` plus `ASAN_OPTIONS=detect_leaks=0 UBSAN_OPTIONS=halt_on_error=1 /tmp/claro-arity-asan tests/38_builtin_arity.claro`: all four missing-argument diagnostics; no sanitizer report.
+- `make -s all`: rebuilt both `claro` and `claro.exe` from current source.
+- `./claro test`: `PASS: 0 failure(s)`.
+- `./claro doctor`: all checks `OK`.
+- `./claro validate`: validation passed.
+
+The memory cleanup slices release the previous deep value when a runtime variable or map entry is overwritten, release temporary split argument arrays and strings from `DO`, `CALL`, `TEXT ... CONTAINS`, and `RANDOM`, release loaded program paths, lines, and pointer arrays at the end of each script run, and now release the remaining runtime-owned variables, functions, modules, classes, import paths, captured output, return value, and error strings before the interpreter exits. The expression evaluator now releases discarded intermediate `Value` operands and command boundaries release evaluated `SET`/`SAY` values after copying or printing them. `FOR EACH` now releases its copied collection after iteration, preventing discarded list/map copies from accumulating in long scripts. `IF` and `DO ... TIMES` now release their temporary control-expression values after branch/loop selection. `ASK` now releases evaluated prompt values and temporary input values after converting/copying them into runtime storage. Focused coverage is `tools/validate_memory_cleanup.py`, `tools/validate_expression_cleanup.py`, `tools/validate_control_flow_cleanup.py`, `tools/validate_control_expression_cleanup.py`, and `tools/validate_ask_prompt_cleanup.py`; each focused cleanup validator runs an ASan/UBSan build with LeakSanitizer checking. Verified on 2026-09-24: `python3 tools/validate_ask_prompt_cleanup.py` passes (2,000 prompt/input operations under ASan/UBSan/LSan); `make -s all`, `./claro test`, `./claro doctor`, and `./claro validate` all pass. A malformed-input ASan/UBSan/LSan smoke run did not pass: it reports two leaked `rt_error` message strings (140 bytes total) at `src/claro.c:142`. This unrelated existing diagnostic-path leak remains unaddressed and blocks claiming sanitizer-clean malformed-input handling. The `COUNT ... AS` command now releases its evaluated list/map value after extracting the item count. `python3 tools/validate_count_expression_cleanup.py` first reproduced a 28,000-byte leak across 2,000 list expressions, then passed with LeakSanitizer enabled after the fix. `GET ... AT ... AS ...` now releases its copied collection and empty-result temporary after storing the selected item; `python3 tools/validate_get_expression_cleanup.py` first reproduced 34,000 bytes of leaks across 2,000 empty-list lookups, then passed with LeakSanitizer enabled after the fix. Remaining memory-growth areas include other expression temporaries and command boundaries. The `RUN COMMAND` path remains trusted shell execution, not a sandbox.
+
+The `FIND ... IN ... AS ...` command now releases its evaluated search value and copied list/map after storing the result. Focused coverage is `tools/validate_find_expression_cleanup.py`; it runs 2,000 searches under ASan/UBSan with LeakSanitizer enabled. Verified on 2026-09-24: `python3 tools/validate_find_expression_cleanup.py` passes with no reported leaks; `make -s all`, `./claro test` (0 failures), `./claro doctor`, `./claro validate`, and `git diff --check` pass. This slice is runtime-verified under sanitizers; broader malformed-input sanitizer coverage remains blocked by the previously documented `rt_error` message leak.
+
+`REMOVE` now releases its evaluated needle and copied list/map value after updating runtime storage. `python3 tools/validate_remove_expression_cleanup.py` passed with 2,000 repeated string-needle operations under ASan/UBSan/LSan. Removed elements from populated copied lists remain a separate ownership case. This slice is runtime-verified under sanitizers; malformed-input diagnostics still have the previously recorded `rt_error` leak.
+
+`ADD ... TO ...` now releases both the evaluated item and copied list after `list_add` and `rt_set` have made their owned copies. `python3 tools/validate_add_expression_cleanup.py` first reproduced leaks under ASan/UBSan/LSan (2,000 repeated string concatenations), then passed after the ownership cleanup. Full checks passed: `make -s all`, `./claro test` (0 failures), `./claro doctor`, `./claro validate`, all existing focused cleanup validators, and `git diff --check`. This slice is runtime-verified under sanitizers; malformed-input diagnostics still have the previously recorded `rt_error` leak.
+
+`PUT ... KEY ... VALUE ...` now releases the evaluated map, key, and value copies after runtime storage has copied them. `python3 tools/validate_put_expression_cleanup.py` passes with 2,000 repeated string writes under ASan/UBSan/LSan. Verified 2026-09-26: `make -s all`, `./claro test` (0 failures), `./claro doctor`, `./claro validate`, the focused sanitizer validator, and `git diff --check` pass. Separate malformed-argument sanitizer smoke tests for the existing builtin-arity and inverted-range diagnostics do not report out-of-bounds access, but LeakSanitizer reports the already documented `rt_error` diagnostic-string leaks (552 bytes/14 allocations for arity cases; 79 bytes/2 allocations for the inverted-range case). This slice is runtime-verified; those error-path leaks remain a separate blocker to claiming sanitizer-clean diagnostics.
+
+The `RUN COMMAND` path now decodes POSIX `pclose()` wait status before storing `LASTEXIT`, so a child that exits with code 3 exposes `3` rather than the encoded status 768. Focused coverage is `tests/42_last_exit_code.claro`. HTTP responses now have a 1,048,576-byte cap and marker-like response bodies are preserved while extracting the final HTTP status marker. Focused coverage is `tools/validate_http_hardening.py`. Remaining memory-growth areas include other expression temporaries. Claro remains a trusted-script interpreter, not a sandbox.
+
+`RUN COMMAND` is documented and validated as a trusted-code capability: it executes shell commands with the user's permissions and is not a sandbox. Claro does not claim untrusted-script safety or use a fragile blacklist sanitizer. Focused documentation coverage is `tools/validate_trusted_command_docs.py`.
+
+`GET ... KEY ... AS ...` now releases its temporary map and key values after lookup. `python3 tools/validate_get_key_expression_cleanup.py` reproduced 1,004,000 leaked bytes before the change and passes after it with ASan/UBSan/LSan enabled. `EXISTS FILE ... AS ...` now releases its evaluated path value after checking it; `python3 tools/validate_exists_expression_cleanup.py` first reproduced 62,000 leaked bytes across 2,000 calls, then passed with ASan/UBSan/LSan enabled. These are narrow expression-temporary cleanup slices, not a claim that all runtime allocations are leak-free.
+
+`LIST FOLDER ... AS ...` now releases its evaluated path and the temporary folder-list value after runtime storage copies the list. `python3 tools/validate_list_folder_expression_cleanup.py` reproduced 220,000 leaked bytes across 2,000 operations under ASan/UBSan/LSan before the change and passes after it with no leak report. The working-tree checks `make -s all`, `./claro test` (0 failures), `./claro doctor`, `./claro validate`, and `git diff --check` pass. This is a narrow ownership improvement, not a claim that all runtime allocations are leak-free.
+The `DELETE FILE ...` and `DELETE FOLDER ...` commands now release their evaluated path values after converting the paths to owned strings. `python3 tools/validate_delete_expression_cleanup.py` first reproduced 178,000 leaked bytes across 2,000 `DELETE FILE` expression evaluations under ASan/UBSan/LSan, then passed after cleanup. This check covers expression ownership; malformed-input diagnostic paths still have the previously documented `rt_error` message leak. The `COPY FILE` and `MOVE FILE` commands now also release their evaluated source/destination path values after conversion to strings; `python3 tools/validate_copy_move_expression_cleanup.py` reproduced 74,000 bytes leaked across 1,000 copy/move pairs before the fix and is the focused ASan/UBSan/LSan regression gate. `CREATE FOLDER ...` now releases its evaluated path value after converting it to an owned path string; `python3 tools/validate_create_folder_expression_cleanup.py` reproduced 200,000 leaked bytes across 2,000 calls before the fix and passes with ASan/UBSan/LSan enabled. This narrow cleanup slice does not establish that all runtime allocations are leak-free.
+
 ## Feature matrix
 
 ### Beginner scripting core
@@ -51,16 +89,55 @@ Status: **Foundation present**
 Ready now:
 - typed variables such as `SET score NUMBER 10`
 - `TYPE OF` and `CHECK TYPE`
-- typed list/map checks through `claro typecheck`
+- `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.`
-- a narrow function/method argument check: `CHECK TYPE parameter IS TYPE` inside a function or simple object method lets `claro typecheck` accept correct checked calls, catch mismatched `DO`, `CALL ... WITH`, and `DO object.method ...` arguments, and explain when a `DO object.method ...` call happens before the object is created with `NEW`
+- `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.`
-- a narrow object-field assignment/check-type check for simple `NEW Class object` plus direct `SET object.field value` and `CHECK TYPE object.field IS TYPE` cases when the class declares `HAS field TYPE`; validation now covers correct NUMBER, TEXT, and YESNO direct assignments, direct `CHECK TYPE` metadata acceptance for NUMBER/TEXT/YESNO fields, negative NUMBER/TEXT/YESNO field `CHECK TYPE` metadata mismatches, NUMBER/TEXT/YESNO-expectation unknown-field `CHECK TYPE` diagnostics, missing-object field assignment and `CHECK TYPE` diagnostics, NUMBER/TEXT/YESNO wrong-type diagnostics, NUMBER/TEXT/YESNO-valued unknown-field diagnostics for direct assignments to undeclared fields, plus a plain beginner-facing unknown-field diagnostic when the assigned expression type is not inferable yet
+- `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.` This is covered for modern functions and both modern and compatibility object methods.
+- `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
+- typed function return diagnostics also identify an unknown return expression in compatibility `TAKES` / `LEARNED` functions, matching the modern function and object-method guidance
+- `TYPE OF` reports a direct repair hint when the learner forgets `AS`, for example `TYPE OF score` suggests `TYPE OF score AS kind`
+- bare `TYPE OF` reports that the expression, `AS`, and result name are all required, with a complete repair example
+- `TYPE OF` reports a direct repair hint when the learner forgets the expression before `AS`, for example `TYPE OF AS kind` reports `TYPE OF needs an expression before AS. Try: TYPE OF score AS kind.`
+- `TYPE OF` prioritizes the missing expression diagnostic even when extra words follow the incomplete form, so `TYPE OF AS kind extra` still points the learner to the missing expression first.
+- `TYPE OF` reports a direct repair hint when the learner forgets the result name after `AS`, for example `TYPE OF score AS` reports `TYPE OF needs a result name after AS. Try: TYPE OF score AS kind.`
+- A valid `TYPE OF score AS kind` statement has a focused positive typecheck fixture, so the complete form is protected from diagnostic-only regression coverage.
+- `TYPE OF` remains case-insensitive like other Claro keywords, with focused positive coverage for lowercase `type of score as kind` syntax.
+- `CHECK TYPE` remains case-insensitive like other Claro keywords, with focused positive coverage for lowercase `check type score is number` syntax.
+- Object declarations and field checks remain case-insensitive like other Claro keywords, with focused positive coverage for lowercase `class`, `has`, `end`, `new`, `set`, and `check type` in one typed object-field example.
+- `TYPE OF` rejects extra words after its result name with a direct repair hint, so `TYPE OF score AS kind extra` explains that only one result name belongs there; typed `TEACH ... RETURNS TYPE` declarations likewise reject extra words after the return type with a direct repair hint
+- typed `TEACH ... RETURNS` declarations reject a missing return type with a direct repair hint, such as `Function greet needs a return type after RETURNS. Add a type such as NUMBER.` The same diagnostic names the complete class and method, including compatibility `TAKES` / `LEARNED` methods: `Method Player.score needs a return type after RETURNS. Add a type such as NUMBER.`
+- typed list/map checks through `claro typecheck`, including a nested `LIST OF MAP` insertion example
+- compatibility `TAKES` / `LEARNED` functions also have focused positive numeric-addition, subtraction, division, and multiplication return fixtures, keeping arithmetic return coverage aligned with modern functions and compatibility methods.
+- compatibility `TAKES` / `LEARNED` functions have positive complete-branch return coverage beside the incomplete-branch diagnostic, so older conditional examples are checked for both accepted and rejected paths.
+- a narrow function/method argument check: `CHECK TYPE parameter IS TYPE` inside a function or simple object method lets `claro typecheck` accept correct checked calls, catch mismatched `DO`, `CALL ... WITH`, `DO object.method ...`, and compatibility `CALL ... WITH` arguments, including checked methods that appear after another method in the same class, report missing checked function and method arguments, report missing unchecked arguments for simple functions and simple object methods in both modern `DO` and compatibility `CALL ... WITH` forms, treat empty compatibility calls such as `CALL greet WITH` and `CALL player.rename WITH` as missing-argument mistakes, catch extra arguments to simple functions and checked methods even when the checked method appears after another method in the same class, catch modern `DO` and compatibility `CALL ... WITH` calls to undeclared simple functions, explain when `DO object.method ...` or compatibility `CALL ...` happens before the object is created with `NEW` even if the method name is also wrong, and catch modern plus compatibility calls to undeclared object methods with a class-specific `TEACH` hint
+- simple function and object-method return checks with `TEACH name ... RETURNS TYPE` now include a compatibility `TAKES` / `LEARNED` function whose conditional returns are incomplete, preserving the same every-path diagnostic as modern functions.
+- function and method declarations now reject repeated parameter names with a direct repair hint before calls are checked, including modern and compatibility `TAKES` / `LEARNED` functions and methods; object methods with the same name are also rejected within a class with a rename hint in both modern and compatibility method syntax
+- top-level function declarations now reject repeated names with a direct repair hint, so two `TEACH greet` blocks cannot silently compete for one callable function; a missing function name after `TEACH` gets a direct beginner-facing repair hint, and a missing method name inside `CLASS` names the class and gives a method example
+- class declarations now reject a missing class name after `CLASS` with a direct beginner-facing repair hint
+- class declarations now reject repeated field names within the same class with a direct repair hint before field types are used, so two `HAS score ...` lines cannot silently choose conflicting metadata; different classes may independently use the same field name
+- class field declarations now reject missing names such as bare `HAS`, missing types such as `HAS score`, unknown types such as `HAS score BANANA`, and extra tokens such as `HAS score NUMBER TEXT` with the field name, class name, supported type examples, and a repair hint before object-field checks use that metadata
+- class declarations now reject repeated class names with a direct repair hint, so two `CLASS Player` blocks cannot silently compete for the same name; extra words after a class name also get a direct repair hint instead of becoming part of the class identity
+- object creation now rejects repeated object names with a direct repair hint, so two `NEW Player player` statements cannot silently replace one another during type checking; when a script declares at least one class, a misspelled `NEW` class name gets a direct declaration hint without changing the older permissive no-class form; a missing class name or object name gets a direct example repair; extra words after the object name get a direct repair hint instead of being silently ignored
+- a narrow object-field assignment/check-type check for simple `NEW Class object` plus direct `SET object.field value` and `CHECK TYPE object.field IS TYPE` cases when the class declares `HAS field TYPE`; validation now covers correct NUMBER, TEXT, and YESNO direct assignments, dedicated positive and explicitly typed NUMBER/TEXT field assignments, missing values in untyped direct field assignments with a repair hint, explicitly typed method-body assignments to undeclared fields with a `HAS field TYPE` repair hint in modern and compatibility method syntax, dedicated positive NUMBER/TEXT/YESNO `CHECK TYPE` metadata fixtures, simple and chained object aliases for both field assignments and `CHECK TYPE` metadata (including a chained TEXT-field check), aliased object-method calls including chained aliases in modern `DO` and compatibility `CALL ... WITH` forms (with a dedicated positive modern `DO` chained-alias fixture), field-to-field, compound arithmetic field expressions, and arithmetic/text expression result types, negative NUMBER/TEXT/YESNO field `CHECK TYPE` metadata mismatches, NUMBER/TEXT/YESNO-expectation unknown-field `CHECK TYPE` diagnostics, missing-object field assignment and `CHECK TYPE` diagnostics, NUMBER/TEXT/YESNO wrong-type diagnostics, field collection when a `HAS` field appears after a simple method, NUMBER/TEXT/YESNO-valued unknown-field diagnostics for direct assignments to undeclared fields including explicitly typed assignments, numeric and text results from simple arithmetic/text expressions in object-field assignments, plus method-body field assignment and `CHECK TYPE` diagnostics for NUMBER, TEXT, and YESNO fields in modern and compatibility syntax, including compatibility YESNO `CHECK TYPE` metadata coverage, direct method assignments to undeclared fields now produce a beginner-facing missing-field diagnostic when the assigned expression has a known type, and a plain beginner-facing unknown-field diagnostic when the assigned expression is not inferable yet in both modern and compatibility method syntax; method-body `CHECK TYPE` now reports an unknown field with a repair hint in both method syntaxes, including compatibility `TAKES` / `LEARNED` methods; explicitly typed assignments to declared method fields now validate the class-declared field type instead of trusting only the inline type annotation, so a wrong value such as `SET score TEXT \"oops\"` reports the method and field in the diagnostic.
+- inline method-field annotations are checked against the class `HAS` declaration in modern and compatibility methods; conflicting known types and unknown annotation names produce field-specific repair guidance, with positive and negative focused fixtures for both syntaxes.
+- direct object-field `AS ... TO` assignments reject extra words after the value with a repair hint, so `SET player.score AS NUMBER TO 10 extra` cannot silently ignore the trailing text; they explain when `TO` is missing after the type and when the value is missing after `TO`; short explicitly typed assignments such as `SET player.score NUMBER 10 extra` receive the same repair-oriented check and explain when the value is missing after the type
+- Direct object-field validation also has positive coverage for explicit `NUMBER`, `TEXT`, and `YESNO` annotations, such as `SET player.ready YESNO YES`, plus the compatibility-shaped `AS ... TO` form such as `SET player.score AS NUMBER TO 10`, while the shorter unannotated form remains supported; method-body field assignments have matching positive coverage for both modern and compatibility `TEACH` forms using `SET score AS NUMBER TO 10`, and those two `AS ... TO` method fixtures are now included in `claro validate`; conflicting annotations such as `SET player.score TEXT "oops"` explain the class-declared type and how to repair it, and unknown annotations such as `SET player.score AS BANANA TO 10` or `SET player.score BANANA 10` identify the invalid type and suggest the declared field type.
 
 Still needed:
-- richer typed function signatures and return values
+- Keep the focused typecheck validator's fixture list complete as new positive and negative examples are added. `claro validate` now executes the complete focused fixture matrix as well, so release validation cannot silently omit a listed typecheck example. Short explicitly typed field assignments inside modern and compatibility methods also have focused coverage: `SET score NUMBER` explains that one value expression is required after the type, matching direct object-field assignment guidance.
+- The expression checker now carries a known TEXT operand through all arithmetic operators so object-field and typed-function-return diagnostics do not hide addition, subtraction, multiplication, or division mistakes; focused numeric-subtraction, numeric-division, and numeric-multiplication positives plus text-operand addition, subtraction, multiplication, and division negatives protect this behavior. Typed-function return diagnostics now have focused subtraction and division positives alongside multiplication coverage. Text concatenation into a TEXT field has focused positive fixtures for both operand orders, including concatenation of two TEXT object fields. Each numeric operator names the text operand and explains that it needs NUMBER values.
+- Method return validation now has focused positive subtraction and division fixtures alongside the existing arithmetic return coverage, including compatibility `TAKES` / `LEARNED` subtraction and division cases, so checked NUMBER method parameters and numeric subtraction or division remain accepted by the release validator in both method spellings.
+- Modern and compatibility `TAKES` / `LEARNED` methods have positive NUMBER, TEXT, and YESNO field-assignment coverage, and modern plus compatibility method-body `CHECK TYPE` metadata now have positive YESNO coverage beside the wrong-value diagnostics.
+- Modern method-body TEXT concatenation has positive coverage in both operand orders, such as `SET first first + "!"` and `SET last "Dr. " + last`.
+- Compatibility method-body TEXT concatenation has matching positive coverage in both operand orders, so `TAKES` / `LEARNED` methods keep the same beginner-safe field update behavior.
+- richer typed function signatures and return values beyond the focused simple function/method `RETURNS TYPE` check
 - type checking through branches and loops
 - richer object field type checking beyond simple direct assignments
 - typed imports/modules
 
+
 Good starting docs:
 - `ADVANCED_STATIC_TYPING.md`
 - `V1_14_STATIC_TYPES.md` (feature history plus examples)
@@ -96,7 +173,25 @@ Ready now:
 - `claro package init`
 - `claro package add/list/remove/doctor/lock`
 - local project files such as `claro.project`, `claro.lock`, and `packages/`
-- package-name safety checks
+- starter projects from `claro new` now use the same manifest-version and lock-version headers as `claro package init`
+- the default `make` target builds both `claro` and `claro.exe`, so cross-platform release validators exercise freshly built executables
+- project-name safety checks for `claro new`, so unsafe names such as `../bad` are rejected before Claro creates folders
+- package-name safety checks when adding packages, including the 64-character package-name limit, when `claro package doctor` audits an existing `claro.project`, when `claro package lock` writes lockfile data, when `claro package list` shows existing packages, when `claro package init` sees unsafe names already present in `claro.project`, when `claro package add` sees unsafe names already present in `claro.project`, when `claro package remove` refreshes the lockfile after an edit, when learners need to remove an unsafe package entry that is already present, when `claro package doctor` verifies lockfile checksums for listed packages, and when `claro package doctor` rejects lockfile package entries that are not listed in `claro.project`
+- `claro package doctor` rejects a listed package manifest whose `name:` does not match the package name in `claro.project`
+- `claro package doctor` compares the complete manifest `name:` value, so a prefix such as `math-tools-extra` cannot be accepted for package `math-tools`
+- `claro package doctor` requires exactly one complete supported package `manifest-version: 1` field; missing, blank, unsupported, or duplicate format fields get a `BAD package manifest version` diagnostic with the file path and a repair hint, rather than calling an existing file missing
+- `claro package doctor` compares the complete manifest `checksum:` value, so a valid checksum followed by extra text is rejected
+- `claro package doctor` requires the complete supported `manifest-version: 1` value in `claro.project`, so a prefix such as `manifest-version: 10` is rejected
+- `claro package doctor` requires the complete supported `version: 1` value in each local package manifest, so a prefix such as `version: 10` is rejected
+- `claro package doctor` requires exactly one current `version: v1.18.26` line in `claro.lock`, so stale, missing, blank, or duplicate lockfile release versions are rejected
+- `claro package doctor` requires the complete supported `source: local` value in each local package manifest, so a prefix such as `source: local-extra` is rejected
+- package project entries must be unique; `claro package doctor`, `list`, `add`, `init`, and `lock` reject duplicate names instead of generating ambiguous package or lockfile data
+- lockfile package entries must also be unique; `claro package doctor` reports duplicate lock entries instead of accepting ambiguous package/checksum data
+- package manifest `name:` entries must also be unique; `claro package doctor` reports `BAD package manifest name` instead of accepting ambiguous package identity data
+- package manifest `checksum:` entries must also be unique; `claro package doctor` reports `BAD package checksum` instead of accepting ambiguous integrity data
+- package manifest `version:` entries must also be unique and must contain exactly `1`; `claro package doctor` reports `BAD package version` instead of accepting ambiguous package metadata
+- project manifests must contain exactly one `manifest-version: 1` field; duplicate or prefix-matching values are rejected with `BAD project manifest version: expected 1`
+- project manifests must contain exactly one non-empty `name:` field; `claro package doctor` reports `BAD project manifest name: expected a non-empty name` when the project identity is missing or blank
 
 Still needed:
 - install from local path
@@ -154,8 +249,9 @@ Status: **Foundation present**
 Ready now:
 - `claro ide`
 - metadata JSON
-- completion list
+- completion list, including the current typed-language keywords `RETURNS`, `CHECK`, and `TYPE`
 - diagnostics helper
+- Forgejo/Gitea CI coverage for the current release validation gates (`claro validate`, typecheck diagnostics validation, version convention validation, package security validation, compiler warning validation, and the CI workflow coverage check); the compiler warning validator rebuilds `src/claro.c` and rejects path-truncation warnings, while the workflow validator verifies these commands, including its own command, occur in executable `run` steps rather than comments
 
 Still needed:
 - syntax highlighting package
@@ -204,3 +300,9 @@ Use feature docs with these expectations:
 - **Plans or experiments:** `PACKAGE_REGISTRY.md`, `WEB_SERVER_PLAN.md`, `EDITOR_EXTENSION_PLAN.md`, `GRAPHICS.md`, `SDL12.md`, `COMPLETE_PLATFORM_ROADMAP.md`, `FUTURE_FEATURES_ROADMAP.md`.
 
 If a doc sounds more ambitious than this status map, treat this file as the current source of truth and update the older doc before teaching from it.
+
+## 2026-09-28 random.int full-range arithmetic follow-up
+
+`random.int` now calculates its inclusive range width and result in `long long`, avoiding signed-int overflow for the full accepted C `int` range. The regression fixture is `tests/43_random_int_extreme_bounds.claro`.
+
+Verified: built with `gcc -std=c99 -O0 -g -fsanitize=address,undefined src/claro.c -o /home/ubuntu/.hermes/profiles/maxwell/cache/scratch/claro-rng-probe -lm`; ran `ASAN_OPTIONS=detect_leaks=0 UBSAN_OPTIONS=halt_on_error=1 /home/ubuntu/.hermes/profiles/maxwell/cache/scratch/claro-rng-probe tests/43_random_int_extreme_bounds.claro` (exit 0, no sanitizer report). Before the change, the same full-range call failed with UBSan signed integer overflow at `src/claro.c:347`. This validates the extreme-range runtime behavior under ASan/UBSan; `make -s all`, `./claro test` (0 failures, including this fixture), `./claro doctor`, `./claro validate`, and `git diff --check` pass.

docs/HARDENING.md

@@ -8,3 +8,91 @@ Safety caps (to prevent memory abuse):
 - Maximum program lines: 500,000
 
 If a file exceeds these limits, the loader fails cleanly.
+
+## Expression-token cleanup
+
+Each expression now releases its token strings and token-array storage before returning. This is a narrow cleanup boundary; runtime-owned variables, loaded programs, and other allocations remain separate follow-up work.
+
+Focused verification:
+
+```text
+python3 tools/validate_memory_cleanup.py
+```
+
+The validator builds an AddressSanitizer/UndefinedBehaviorSanitizer binary, runs a repeated variable-overwrite probe, and confirms LeakSanitizer no longer reports allocations from `tokenize`/`toks_add`. The interpreter remains a trusted-script runtime, not a sandbox.
+
+## Overwritten-value cleanup
+
+Runtime variables and map entries own deep copies of their values. Replacing an existing variable or map entry now releases the previous string, list, or map value before storing its replacement. This is intentionally limited to overwrite boundaries; final runtime teardown remains a follow-up cleanup slice.
+
+## Split-argument cleanup
+
+Command argument lists created by `DO`, `CALL`, `TEXT ... CONTAINS`, and `RANDOM` are temporary parser storage. They now share one cleanup helper, so repeated calls do not retain the duplicated argument strings or pointer array. The helper does not change argument evaluation or syntax compatibility.
+
+Focused verification builds with AddressSanitizer/UndefinedBehaviorSanitizer, repeatedly exercises a four-argument `DO`, and checks the cleanup helper before confirming the existing string, list, and map overwrite behavior.
+
+The `REMOVE` command now releases its evaluated needle and copied list/map value after updating runtime storage. Focused verification: `python3 tools/validate_remove_expression_cleanup.py` runs 2,000 discarded string needles under ASan/UBSan/LSan; it passed with no reported leaks. This slice does not yet address the separate ownership of an item removed from a populated copied list.
+
+The `PUT ... KEY ... VALUE ...` command now releases its evaluated map, key, and value copies after `map_put`/`rt_set` have copied the data they own. Focused verification: `python3 tools/validate_put_expression_cleanup.py` exercises 2,000 string-valued writes under ASan/UBSan/LSan and passes with no reported leaks. This covers expression-temporary ownership only; broader malformed-input sanitizer runs still report the previously documented `rt_error` diagnostic-string leaks.
+
+## HTTP response handling
+
+HTTP responses are capped at 1,048,576 bytes. Exceeding the cap produces a beginner-facing runtime error instead of retaining an unbounded response. The curl status suffix is taken from the final status marker, so a response body containing marker-like text is preserved. Existing `HTTP CHECK` URL safety rules remain unchanged.
+
+Focused verification:
+
+```text
+python3 tools/validate_http_hardening.py
+```
+
+This validator uses a local HTTP server to check marker-like response text, status `200`, and the oversized-response diagnostic.
+
+## External command trust boundary
+
+`RUN COMMAND` intentionally executes a shell command with the user's permissions. It is a trusted-code capability, not a sandbox or an untrusted-script safety feature. Claro does not attempt a fragile blacklist sanitizer; users must review scripts before running them.
+
+Focused documentation verification:
+
+```text
+python3 tools/validate_trusted_command_docs.py
+```
+
+## Control-flow expression cleanup
+
+Conditions evaluated by `IF` are temporary runtime values. The `IF` command now
+releases its condition after choosing a branch, including when the condition is
+a text expression. This is a narrow cleanup boundary; other expression
+temporaries remain separate follow-up work.
+
+Focused verification:
+
+```text
+python3 tools/validate_control_expression_cleanup.py
+```
+
+The validator builds with AddressSanitizer/UndefinedBehaviorSanitizer,
+executes 2,000 temporary `IF` conditions under LeakSanitizer, and checks the
+expected output.
+
+## ASK temporary-value cleanup
+
+`ASK` releases the evaluated prompt value after converting it to display text,
+and releases the temporary input value after `rt_set_checked` copies it into
+runtime storage. This keeps prompt and input strings from accumulating during
+repeated input loops without changing prompt or input behavior.
+
+Focused verification:
+
+```text
+python3 tools/validate_ask_prompt_cleanup.py
+```
+
+The validator runs 2,000 prompt/input operations with AddressSanitizer, UndefinedBehaviorSanitizer, and LeakSanitizer enabled. The dedicated validator passes. A separate malformed-input sanitizer smoke run (`gcc -std=c99 -O0 -g -fsanitize=address,undefined src/claro.c -o ... -lm` followed by the generated malformed script) exits 1 due to two existing leaked error-message strings (140 bytes total) allocated in `rt_error` at `src/claro.c:142`; this is outside the ASK cleanup slice and remains a blocker to sanitizer-clean malformed-input validation.
+
+## GET KEY temporary-value cleanup
+
+`GET ... KEY ... AS ...` releases its evaluated map copy and key value after storing the selected value. `python3 tools/validate_get_key_expression_cleanup.py` runs 2,000 lookups under ASan/UBSan/LSan; before the cleanup it reproduced 1,004,000 bytes leaked, and after it passes with the expected output and no reported leaks.
+
+## COPY/MOVE expression temporary cleanup
+
+`COPY FILE ... TO ...` and `MOVE FILE ... TO ...` release both evaluated path values after converting them to owned path strings. `python3 tools/validate_copy_move_expression_cleanup.py` runs 1,000 copy/move pairs under ASan/UBSan/LSan; before the cleanup it reproduced 74,000 bytes leaked across 4,000 path-expression values, and after it passes with no reported leaks.

docs/PRACTICAL_SCRIPTING.md

@@ -64,3 +64,5 @@ SAY LASTEXIT
 ```
 
 Use this carefully. It runs commands on the user's computer.
+
+`RUN COMMAND` is for trusted code only. It is not a sandbox: it can start programs, read or change files, and use the same permissions as the user running Claro. Do not run scripts from an untrusted source, and do not treat this feature as a security boundary.

docs/ROADMAP.md

@@ -31,21 +31,90 @@ See `CURRENT_STATUS.md` for the detailed feature matrix.
 
 1. Keep beginner-facing docs current and separate from historical release notes.
 2. Keep examples aligned with the modern simple syntax (`END`, `DO`, short `SET`, short `ASK`) while documenting older compatibility forms separately.
-3. Expand validation around typecheck diagnostics and package/networking safety. Current object-method parameter validation covers one correct `DO object.method ...` call, one wrong-type diagnostic, and missing-object guidance when `DO player.method ...` appears before `NEW`; object-field validation covers correct NUMBER, TEXT, and YESNO direct `SET object.field value` assignments, direct `CHECK TYPE` metadata acceptance for NUMBER/TEXT/YESNO fields, negative NUMBER/TEXT/YESNO metadata mismatches, NUMBER/TEXT/YESNO-expectation unknown-field `CHECK TYPE` diagnostics, missing-object field assignment and `CHECK TYPE` diagnostics, NUMBER/TEXT/YESNO wrong-type direct assignments, simple NUMBER/TEXT/YESNO-valued unknown-field diagnostics after `NEW Class object`, and a beginner-facing fallback when the unknown field's assigned expression type is not inferable yet.
+3. Expand validation around typecheck diagnostics and package/networking safety. Current Forgejo/Gitea CI runs the documented release gates (`claro validate`, typecheck diagnostics validation, version convention validation, package security validation, compiler warning validation, and CI workflow coverage validation). The compiler warning validator rebuilds `src/claro.c` and blocks path-truncation warnings; the workflow coverage validator checks executable `run` steps rather than comments and requires its own command. Current package safety validation covers safe project creation, rejecting unsafe project names during `claro new`, safe manifest/lockfile creation, rejecting unsafe package names during `package add`, detecting unsafe package names already present in `claro.project` during `package doctor`, refusing to write lockfile data for unsafe package names during `package lock`, making `package list` fail instead of displaying unsafe package entries as normal package names, making `package init` fail instead of reporting the project ready when unsafe package names are already present, making `package add` fail before changing files when unsafe package names are already present, making `package remove` fail instead of reporting success when unsafe package names remain during lockfile refresh, allowing `package remove` to remove an exact unsafe package entry so learners can repair a bad `claro.project`, making `package doctor` reject stale lockfile checksums for listed packages, and making `package doctor` reject lockfile package entries that are not listed in `claro.project`. Current function validation covers correct checked calls, wrong-type arguments, missing checked-argument diagnostics, missing unchecked-argument diagnostics for simple functions in both modern `DO greet` and empty compatibility `CALL greet WITH` forms, extra-argument diagnostics, and beginner-facing unknown-function diagnostics for mistyped modern `DO` and compatibility `CALL ... WITH` calls; current object-method parameter validation covers correct modern `DO object.method ...` and compatibility `CALL object.method WITH ...` checked calls, wrong-type diagnostics for both call forms, checked methods after another method in the same class, missing and extra checked-argument diagnostics including the extra-argument case for a checked method after another method in the same class, missing unchecked-argument diagnostics for simple object methods, missing-object guidance when `DO player.method ...` or compatibility `CALL object.method WITH ...` appears before `NEW` even if the method name is also wrong, and class-specific unknown-method diagnostics for both modern and compatibility calls when a learner calls a method the class does not declare; current object-field validation covers direct NUMBER/TEXT/YESNO field-assignment positives, direct object-field `CHECK TYPE` metadata positives for NUMBER/TEXT/YESNO fields, negative NUMBER/TEXT/YESNO field metadata mismatches, NUMBER/TEXT/YESNO-expectation unknown-field `CHECK TYPE` diagnostics, direct wrong-type field assignment diagnostics, field collection when a `HAS` field appears after a simple method, direct unknown-field diagnostics for NUMBER/TEXT/YESNO values, a beginner-facing fallback for unknown fields assigned from expressions whose type is not inferable yet, and missing-object diagnostics for both `SET object.field value` and `CHECK TYPE object.field IS TYPE` before `NEW`.
-4. Add small examples for each foundation feature before adding bigger syntax.
+3a. Keep package diagnostics actionable: invalid package manifest format fields now name the file and explain how to repair it, separately from an absent manifest. Keep package validation honest by checking that the project manifest has one non-empty project name, that the project and each listed package manifest declare the exact supported manifest version, package version, local source, and expected package name, and that lockfiles declare exactly one current release version.
+3b. Keep package security validation in Forgejo/Gitea CI so unsafe names, exact manifest-version/name/version/checksum mismatches, missing manifests, duplicate project manifest versions and packages, duplicate lock packages, duplicate package manifest names, versions, and checksums, and lockfile errors remain release blockers.
+4. Add small examples for each foundation feature before adding bigger syntax. The object-field foundation now includes positive and negative validation for explicitly typed NUMBER/TEXT assignments and field expressions such as `SET player.score player.name`, `SET player.score player.score + 1`, `SET player.name player.score + 1`, explicitly typed field assignments, explicit typed assignments to undeclared fields, simple and chained aliases such as `SET alias player`, `SET backup alias`, followed by `SET backup.score ...` or `CHECK TYPE backup.score IS ...`, chained aliases in object-method calls through both modern `DO` and compatibility `CALL ... WITH` forms (including a dedicated positive modern `DO` fixture), field-to-field, compound arithmetic field expressions, and arithmetic/text expression mismatches; typed containers also accept a map with nested type metadata when it is added to a `LIST OF MAP`; broader alias/control-flow checking remains planned.
+5. Keep the focused typecheck validator complete: the method-body field diagnostic fixtures are now exercised by `claro validate` alongside the standalone diagnostic validator; continue wiring each new `typecheck_*.claro` fixture into both gates. Modern and compatibility unknown-field expression diagnostics now have matching focused coverage, explicitly typed unknown method-field assignments have matching modern and compatibility fixtures with the expected `HAS field TYPE` repair hint, and short explicitly typed method-field assignments have matching modern and compatibility missing-value coverage.
+-6. Continue narrowing expression diagnostics: known TEXT operands now remain visible through arithmetic, with focused numeric-subtraction, numeric-division, and numeric-multiplication positives plus text-operand addition, subtraction, multiplication, and division coverage. Typed function returns now include positive subtraction and division examples alongside multiplication, including compatibility `TAKES` / `LEARNED` numeric-addition, subtraction, division, and multiplication return fixtures. Text concatenation into TEXT fields is covered in both operand orders, including field-to-field concatenation. Each numeric operator names the text operand and explains that it needs NUMBER values. Compatibility method return diagnostics now cover addition, subtraction, division, and multiplication. `CHECK TYPE` also rejects misspelled expected type names.
+- Keep typed method return examples balanced: numeric addition, subtraction, division, and multiplication now have dedicated positive compatibility `TAKES` / `LEARNED` method fixtures in the focused validator, alongside compatibility addition, subtraction, and division mismatch coverage and the existing method return mismatch diagnostics.
+- Keep method field examples balanced across syntax generations: modern and compatibility `TAKES` / `LEARNED` NUMBER, TEXT, and YESNO assignments now have positive fixtures beside the modern and compatibility mismatch fixtures, and modern plus compatibility YESNO method-field metadata now have dedicated positive fixtures beside the negative fixture.
+- Keep IDE metadata aligned with the current beginner syntax: typed-language keywords such as `RETURNS`, `CHECK`, and `TYPE` are now included in the metadata used by editor helpers.
+- Keep compatibility-call coverage aligned with modern calls: empty `CALL object.method WITH` forms now have a focused missing-argument diagnostic fixture alongside the modern `DO object.method` case.
+Keep declared return types honest: `claro typecheck` now reports friendly diagnostics for unknown declared return types, missing return types, mismatched, not-yet-inferable, and empty return expressions (including compatibility `TAKES` / `LEARNED` methods), declarations with no `RETURN` in modern and compatibility function forms, and incomplete conditional branches, when a simple function or object method declares `RETURNS TYPE`; missing-type coverage includes modern functions and both modern and compatibility methods, with a compatibility-function fixture as well. Incomplete conditional-return coverage now also includes the compatibility `TAKES` / `LEARNED` function spelling, so older lessons receive the same every-path diagnostic. The declaration keyword is case-insensitive like other Claro keywords, with positive coverage in modern and compatibility function forms, including lowercase compatibility declarations and lowercase compatibility method declarations, plus a lowercase compatibility-method mismatch fixture. Complete `IF`/`ELSE` return branches, including nested complete conditionals in functions and methods, are accepted, and modern and compatibility function syntax plus compatibility method syntax are covered by focused fixtures. `CHECK TYPE` parameter metadata also informs arithmetic return-expression checking, including object methods; positive numeric multiplication return coverage now sits beside the mismatch fixtures, including a dedicated compatibility-method multiplication success fixture; typed methods can also return class-declared fields by simple name, with positive and mismatch fixtures in both modern and compatibility method syntax, and unknown method return expressions now have dedicated modern and compatibility diagnostic fixtures, and NUMBER return expressions with known TEXT arithmetic operands identify the operation and offending operand, including focused addition, subtraction, multiplication, and division coverage for functions and methods. Compatibility method subtraction diagnostics are also covered alongside the existing addition diagnostic. Full path-sensitive analysis across nested conditionals and loops remains planned.
 
-## Complete-platform milestones
+7. Keep method-body field diagnostics learner-facing: typed methods now name the class method when a simple class field receives a known mismatch in `CHECK TYPE` or assignment, or a known TEXT operand in a NUMBER expression, with matching text and numeric coverage in modern and compatibility method syntax; direct assignments to undeclared method fields now report the missing field when the value type is known, and bare `CHECK TYPE missing IS TYPE` statements inside methods now use the expected type in the repair hint in both modern and compatibility method syntax; broader control-flow and object-flow analysis remains planned.
+8: Keep method-body coverage balanced across beginner field types and syntax generations: YESNO field assignment mismatches are now validated for both modern `DO` and compatibility `CALL ... WITH` method syntax, method-body `CHECK TYPE` metadata mismatches now have matching compatibility `TAKES` / `LEARNED` coverage alongside the modern form, compatibility YESNO field metadata has dedicated positive and negative fixtures, and compatibility method assignments to undeclared fields have the same focused missing-field diagnostic as modern methods, including a beginner-facing fallback when the assigned expression is not inferable yet.
+8a. Keep method-body text expressions balanced: modern TEXT field concatenation is covered when the field is on either side of `+`, so both common beginner word-order patterns remain accepted.
+8b. Keep compatibility method-body text expressions aligned: `TAKES` / `LEARNED` methods now have positive TEXT concatenation coverage in both operand orders beside the modern `TEACH` / `END` examples.
+8c. Keep explicit method-field annotations aligned with class declarations: `SET score TEXT "oops"` inside a method with `HAS score NUMBER` now reports the declared field mismatch instead of accepting the inline annotation; broader annotation consistency remains planned.
+8d. Keep inline field annotations consistent with `HAS` declarations: `claro typecheck` now rejects conflicting annotations on method-body and direct object-field assignments, explains which type to use, and gives a known-type repair hint for unknown direct object-field annotations in both `AS ... TO` and short `SET field TYPE value` forms.
+8d.1. Keep direct field annotation forms balanced: the compatibility-shaped `SET player.score AS NUMBER TO 10` form now has a dedicated positive fixture beside short explicit annotations, so both accepted spellings remain protected by focused validation.
+8d.2. Keep method field annotation forms balanced: modern and compatibility methods now have dedicated positive fixtures for `SET score AS NUMBER TO 10`, so the compatibility-shaped annotation remains protected inside both supported method syntaxes.
+8d.3. Keep release validation aligned with method annotation coverage: the modern and compatibility `AS ... TO` method fixtures now run through `claro validate`, not only the focused Python diagnostic validator.
+8d.4. Keep separated direct field assignments unambiguous: `SET player.score AS NUMBER TO 10 extra` now reports the trailing text and explains the one-expression form instead of accepting a partially parsed value.
+8d.5. Keep short direct field assignments unambiguous: `SET player.score NUMBER 10 extra` now rejects trailing words with a repair hint, matching the separated `AS ... TO` form.
+8d.6. Keep separated direct field assignments complete: `SET player.score AS NUMBER TO` now explains that one value expression is required after `TO`.
+8d.7. Keep short direct field assignments complete: `SET player.score NUMBER` now explains that one value expression is required after the type.
+8d.8. Keep separated direct field assignments structurally complete: `SET player.score AS NUMBER` now explains that `TO` must appear before the value, with a complete repair example.
+8d.9. Keep untyped direct field assignments complete: `SET player.score` now explains that a value expression is required after the field name instead of silently accepting an empty assignment.
+8e. Keep inline method-field annotation coverage aligned across syntax generations: compatibility `TAKES` / `LEARNED` methods now have matching positive and negative fixtures, so older lessons retain the same class-declared-type guidance.
+8f. Keep inline method-field annotations learner-facing: an unknown annotation such as `BANANA` now names the field and method and suggests the `HAS` type instead of silently treating the annotation as an expression.
+8g. Keep unknown inline method-field annotation diagnostics aligned across syntax generations: compatibility `TAKES` / `LEARNED` methods now have matching focused coverage for misspelled annotations.
+8h. Keep function and method declarations unambiguous: `claro typecheck` now reports repeated parameter names with a repair hint, before duplicate names can make argument diagnostics confusing, including modern and compatibility `TAKES` / `LEARNED` functions and methods. Duplicate object method names within one class now get the same declaration-time protection and a rename hint, with focused coverage for both modern and compatibility method syntax. Broader signature validation remains planned.
+8h.1. Keep top-level function declarations unambiguous: duplicate `TEACH greet` blocks now get a declaration-time diagnostic with a rename hint, preventing two functions from competing for one name. Broader signature validation remains planned.
+8h.2. Keep function declarations understandable: a bare `TEACH` now gets a direct diagnostic explaining that a function name is required, with a small example repair. Broader signature validation remains planned.
+8h.3. Keep method declarations understandable: a bare `TEACH` inside a class now names the class and explains how to add a method name, instead of using the less-specific top-level function diagnostic.
+8i. Keep class declarations unambiguous: duplicate `HAS` field names within one class now get a declaration-time diagnostic with a repair hint, preventing conflicting field types from being silently accepted, while same-named fields in different classes remain valid. Broader object declaration validation remains planned.
+8j. Keep class names unambiguous: duplicate `CLASS Player` declarations now get a declaration-time diagnostic with a rename hint, preventing two class definitions from competing for one name. Extra words after a class name also get a declaration-time repair hint, so a typo such as `CLASS Player Extra` cannot silently create a surprising class identity.
+
+8k. Keep object names unambiguous: repeated `NEW Player player` statements now get a declaration-time diagnostic with a rename hint, preventing one object type environment from silently replacing another.
+
+8l. Keep object creation understandable: when classes are declared in a script, an unknown `NEW` class name now gets a direct class-name diagnostic and repair hint; the older permissive `NEW` behavior remains when no class declarations are present.
+
+8m. Keep class field metadata understandable: a missing or unknown type in a `HAS field TYPE` declaration, or extra text after a valid type, now gets a class-and-field diagnostic with supported type examples or a direct repair hint before object-field checks use that metadata.
+8m.1. Keep class field declarations understandable: a bare `HAS` now gets a direct diagnostic explaining that both a field name and type are required, with a small `HAS score NUMBER` repair example.
+8n. Keep object creation unambiguous: extra words after `NEW ClassName object` now get a direct repair hint, so a malformed object declaration cannot silently discard part of the learner's input.
+
+8o. Keep class declarations understandable: a bare `CLASS` now gets a direct diagnostic explaining that a class name is required, with a small example repair.
+
+8p. Keep object declarations understandable: a `NEW` statement with a class but no object name now gets a direct diagnostic with a complete `NEW Player player` repair example; a bare `NEW` now separately explains that both a class and object name are required.
+
+8q. Keep `CHECK TYPE` syntax understandable: a missing `IS` now gets a direct repair hint with a complete `CHECK TYPE score IS NUMBER` example.
+
+8q.1. Keep `CHECK TYPE` declarations understandable: `CHECK TYPE score IS` now gets a direct repair hint naming the missing expected type and showing a complete example.
+
+8q.2. Keep `CHECK TYPE` declarations unambiguous: extra words after a valid expected type now get a direct repair hint instead of being reported as an unknown type.
+8q.3. Keep `CHECK TYPE` declarations complete: a bare `CHECK TYPE` now explains that the expression, `IS`, and expected type are all required, with a complete repair example.
+8q.4. Keep `CHECK TYPE` declarations ordered: `CHECK TYPE IS NUMBER` now explains that an expression belongs before `IS`, with a complete repair example.
+8q.5. Keep `TYPE OF` declarations understandable: a missing `AS` now gets a direct repair hint with a complete `TYPE OF score AS kind` example.
+8q.5.1. Keep `TYPE OF` declarations complete: a missing expression before `AS` now gets a direct repair hint with a complete `TYPE OF score AS kind` example.
+8q.5.1a. Keep incomplete `TYPE OF` diagnostics focused: when the expression is missing, report that repair before secondary trailing-token errors.
+8q.5.2. Keep `TYPE OF` declarations named: a missing result name after `AS` now gets a direct repair hint with a complete `TYPE OF score AS kind` example.
+8q.5.3. Keep complete `TYPE OF` examples protected: the valid `TYPE OF score AS kind` form now has a positive fixture in the focused typecheck validation matrix.
+8q.5.3a. Keep `TYPE OF` keyword handling consistent: lowercase `type of score as kind` now has positive fixture coverage alongside the uppercase form.
+8q.5.3b. Keep `CHECK TYPE` keyword handling consistent: lowercase `check type score is number` now has positive fixture coverage alongside the uppercase form.
+8q.5.3c. Keep object-field examples consistent with keyword rules: lowercase `class`, `has`, `new`, `set`, and `check type` now have one focused positive typed-field fixture.
+8q.5.4. Keep bare `TYPE OF` declarations understandable: report that the expression, `AS`, and result name are all required, with a complete repair example.
+8q.6. Keep `TYPE OF` declarations unambiguous: extra words after the result name now get a direct repair hint instead of being silently included in the variable name.
+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.
+8q.11. Keep extra-token return diagnostics aligned across syntax generations: modern and compatibility functions and object methods now have focused fixtures for `RETURN value extra`, so errors keep the function or class-and-method name and the same repair hint.
+8q.12. Keep empty typed-return diagnostics aligned across syntax generations: modern and compatibility functions and object methods now have focused fixtures for bare `RETURN`, so each form explains that the declared type needs an expression.
+8q.13. Keep unknown typed-return diagnostics aligned across syntax generations: compatibility `TAKES` / `LEARNED` functions now have a focused fixture for an uninferable return expression, matching modern functions and methods.
 
 ### 1. Strong static types
 
 Goal: make larger beginner programs safer without making first scripts harder.
 
 Needed next:
-- richer typed function signatures
+- richer typed function signatures beyond the focused simple `RETURNS TYPE` check
-- typed function returns
+- typed function returns beyond the focused simple function/method `RETURNS TYPE` check
 - type checking across branches and loops
 - typed imports/modules
-- broader object field checking and method return typing
+- broader object field checking and richer method return typing
 - clearer error messages for type mismatches
 
 ### 2. Objects and classes polish
@@ -54,7 +123,7 @@ Goal: keep object-oriented examples readable enough for beginners.
 
 Needed next:
 - constructor-style defaults or beginner-friendly initialization helpers
-- method return checks
+- richer method return checks beyond the focused simple `RETURNS TYPE` check
 - object printing/debugging helpers
 - better examples that avoid abstract toy OOP
 

docs/TESTING.md

@@ -24,6 +24,7 @@ Validate the current v1.18.26 package after building:
 ./claro validate
 python tools/validate_typecheck_diagnostics.py
 python tools/validate_version_convention.py
+python tools/validate_ci_workflow.py
 ```
 
 Useful focused validation scripts:
@@ -39,6 +40,8 @@ python tools/validate_lsp_helper.py
 python tools/validate_package_security.py
 ```
 
+The Forgejo/Gitea CI workflow is expected to run the current release gates above, not only the older smoke tests. This includes `tools/validate_compiler_warnings.py`, which rebuilds the C source as an object file and rejects the known path-truncation warning class. `tools/validate_ci_workflow.py` checks that coverage so CI does not drift away from the documented package validation path.
+
 Older `validate_rc*.py` scripts are kept for historical release notes. They are not the recommended current package validation path.
 
 On Windows, after `build.bat` or `build.ps1`, run the same Python commands from the project root.

docs/V1_16_PACKAGES_PROJECTS.md

@@ -63,9 +63,35 @@ source: local
 checksum: 1234abcd
 ```
 
-`claro.lock` records the release version, lock format, packages, and checksums so future registry work has a stable safety foundation.
+`claro.lock` records the release version, lock format, packages, and checksums so future registry work has a stable safety foundation. `claro package doctor` checks those lockfile checksums for listed packages and reports `BAD lock checksum: name` if the lockfile is stale or edited incorrectly. It rejects duplicate `package:` entries with `DUPLICATE lock package: name`, so one package cannot have ambiguous lock data. It also reports `BAD lock package not in claro.project: name` when the lockfile contains a package entry that is not listed in `claro.project`, so learners know to refresh the lockfile instead of trusting stale package data. The project file must declare the complete supported `manifest-version: 1` value; a prefix such as `manifest-version: 10` is rejected as `BAD project manifest version: expected 1`. Package manifests must declare exactly one complete supported `manifest-version: 1` value. Missing, blank, unsupported (such as `10`), or duplicate format fields report `BAD package manifest version` with the package name, the manifest path, and a hint to keep exactly one `manifest-version: 1` line. The doctor leaves the file unchanged for you to repair; an absent manifest file still reports `MISSING package manifest`. They must also declare exactly one expected `name:` value; duplicate or prefix-matching names are rejected as `BAD package manifest name: name`. The manifest must contain exactly one checksum field with the expected complete value; duplicate, trailing, or extra checksum text is rejected as `BAD package checksum: name`. Package manifests must also declare exactly one `version: 1` field; duplicate or prefix-matching versions such as `version: 10` are rejected as `BAD package version: name`. Package manifests must also declare the complete supported local `source: local` value. Prefixes such as `source: local-extra` are rejected as `BAD package source: name` rather than being accepted as valid local manifests.
 
-## Safety rules
+If `package doctor` reports `BAD package source: math-tools`, open `packages/math-tools/claro.package` and keep exactly one `source: local` line. Duplicate `source:` lines are rejected even when both say `local`, or when a valid line appears before or after an unsupported source. The doctor leaves the file unchanged so you can review and repair it yourself.
+
+If `package doctor` reports `BAD lock checksum: math-tools`, check the `math-tools` entry in `claro.lock`. Each package must have exactly one matching `checksum:` line. Duplicate checksums are rejected even when they agree, or when a correct checksum appears before or after an incorrect one. The doctor leaves the file unchanged. After reviewing your project and package manifests, run `claro package lock` to regenerate the lockfile, then run `claro package doctor` again.
+
+## Lock format safety
+
+`claro package doctor` requires exactly one `lock-version: 1` line in `claro.lock`. Missing, empty, unsupported (such as `10`), or duplicate format versions now fail with:
+
+```text
+BAD lock version: expected exactly one lock-version: 1 line
+```
+
+The lockfile must also contain exactly one current release line, `version: v1.18.26`. A missing, stale, blank, or duplicate release line fails with:
+
+```text
+BAD lock release version: expected exactly one version: v1.18.26 line
+```
+
+The doctor leaves your files unchanged. After reviewing your project and package manifests, run `claro package lock` to regenerate the lockfile, then run `claro package doctor` again. Spaces around values and capitalization of the lock-format field name are accepted, as with other lockfile fields. Valid generated lockfiles continue to work unchanged; this check does not add registry downloads or verify package content hashes.
+
+## Project-name safety
+
+`claro new NAME` checks the project name before creating folders. Project names may use only letters, numbers, dash, and underscore, and they must be 64 characters or fewer.
+
+This keeps mistakes like `../bad` from creating a project outside the folder where the learner is working.
+
+## Package-name safety
 
 Package names may use only:
 
@@ -76,6 +102,8 @@ dash
 underscore
 ```
 
+Package names must be 64 characters or fewer so Claro can create predictable local package folders and metadata paths.
+
 This means simple names like these are allowed:
 
 ```text
@@ -93,6 +121,8 @@ folder/name
 bad name
 ```
 
+If an unsafe package name somehow gets into `claro.project`, package maintenance commands should not quietly continue. `claro package doctor` points out the bad name, `claro package lock` refuses to write lockfile data for it, `claro package list` refuses to display it as a normal package, `claro package init` refuses to report the project ready while the unsafe entry remains, and `claro package remove NAME` exits with an error if the lockfile refresh still sees an unsafe package name after the removal. Learners can still recover by removing the exact unsafe entry, such as `claro package remove ../bad`; Claro rewrites the project file and lockfile without using that unsafe name as a folder path.
+
 ## Why this matters
 
 Packages are important for Claro's future, but the workflow must stay friendly:

tests/38_builtin_arity.claro

@@ -0,0 +1,26 @@
+IMPORT "lib/math.claro" AS math
+IMPORT "lib/random.claro" AS random
+
+TRY
+    CALL math.abs
+CATCH
+ENDTRY
+SAY LASTERROR
+
+TRY
+    CALL math.clamp WITH 1, 0
+CATCH
+ENDTRY
+SAY LASTERROR
+
+TRY
+    CALL random.seed
+CATCH
+ENDTRY
+SAY LASTERROR
+
+TRY
+    CALL random.int WITH 1
+CATCH
+ENDTRY
+SAY LASTERROR

tests/38_builtin_arity.out

@@ -0,0 +1,4 @@
+math.abs needs 1 argument, but got 0. Try: CALL math.abs WITH value.
+math.clamp needs 3 arguments, but got 2. Try: CALL math.clamp WITH value, lower, upper.
+random.seed needs 1 argument, but got 0. Try: CALL random.seed WITH value.
+random.int needs 2 arguments, but got 1. Try: CALL random.int WITH lower, upper.

tests/39_random_inverted_range.claro

@@ -0,0 +1,7 @@
+IMPORT "lib/random.claro" AS random
+
+TRY
+    CALL random.int WITH 10, 1
+CATCH
+ENDTRY
+SAY LASTERROR

tests/39_random_inverted_range.out

@@ -0,0 +1 @@
+random.int needs the lower bound to be less than or equal to the upper bound.

tests/40_call_depth_guard.claro

@@ -0,0 +1,9 @@
+TEACH recurse
+    DO recurse
+LEARNED
+
+TRY
+    DO recurse
+CATCH
+    SAY LASTERROR
+ENDTRY

tests/40_call_depth_guard.out

@@ -0,0 +1 @@
+Claro function call depth exceeded the safe limit of 256. Simplify the recursion or add a stopping condition.

tests/42_last_exit_code.claro

@@ -0,0 +1,2 @@
+RUN COMMAND "exit 3" AS output
+SAY LASTEXIT

tests/42_last_exit_code.out

@@ -0,0 +1 @@
+3

tests/43_random_int_extreme_bounds.claro

@@ -0,0 +1,6 @@
+IMPORT "lib/random.claro" AS random
+CALL random.seed WITH 17
+CALL random.int WITH -2147483648, 2147483647
+SET value RESULT
+SAY value >= -2147483648
+SAY value <= 2147483647

tests/43_random_int_extreme_bounds.out

@@ -0,0 +1,2 @@
+YES
+YES

tests/test_validate_ci_workflow.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Regression tests for the CI workflow release-gate validator."""
+import importlib.util
+from pathlib import Path
+import unittest
+
+ROOT = Path(__file__).resolve().parents[1]
+SPEC = importlib.util.spec_from_file_location(
+    "validate_ci_workflow", ROOT / "tools" / "validate_ci_workflow.py"
+)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class ValidateCiWorkflowTests(unittest.TestCase):
+    def test_accepts_release_gate_commands_in_run_steps(self):
+        workflow = """
+        steps:
+          - name: Build
+            run: make
+          - name: Release gates
+            run: ./claro validate
+          - name: Type diagnostics
+            run: python3 tools/validate_typecheck_diagnostics.py
+          - name: Version
+            run: python3 tools/validate_version_convention.py
+          - name: Packages
+            run: python3 tools/validate_package_security.py
+          - name: Compiler warnings
+            run: python3 tools/validate_compiler_warnings.py
+          - name: CI workflow
+            run: python3 tools/validate_ci_workflow.py
+        """
+        self.assertEqual(MODULE.missing_release_gates(workflow), [])
+
+    def test_requires_the_workflow_validator_to_run_in_ci(self):
+        self.assertIn("python3 tools/validate_ci_workflow.py", MODULE.REQUIRED_COMMANDS)
+
+    def test_rejects_commands_that_only_appear_in_comments(self):
+        workflow = """
+        steps:
+          # run: ./claro validate
+          # python3 tools/validate_typecheck_diagnostics.py
+          - name: Build
+            run: make
+        """
+        self.assertEqual(
+            MODULE.missing_release_gates(workflow), MODULE.REQUIRED_COMMANDS
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_validate_ide_metadata.py

@@ -0,0 +1,34 @@
+import json
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_ide_metadata_lists_current_typed_function_keywords():
+    result = subprocess.run(
+        ["python3", "tools/validate_ide_metadata.py"],
+        cwd=ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+
+    assert result.returncode == 0, result.stdout
+    assert result.stdout.strip() == "IDE metadata validation OK"
+
+
+def test_ide_metadata_is_valid_json_with_keyword_list():
+    result = subprocess.run(
+        ["./claro", "ide"],
+        cwd=ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=True,
+    )
+    metadata = json.loads(result.stdout)
+
+    assert "RETURNS" in metadata["keywords"]
+    assert "CHECK" in metadata["keywords"]
+    assert "TYPE" in metadata["keywords"]

tests/test_validate_typecheck_diagnostics.py

@@ -0,0 +1,468 @@
+#!/usr/bin/env python3
+"""Regression tests for complete typecheck fixture coverage."""
+import importlib.util
+from pathlib import Path
+import subprocess
+import unittest
+
+ROOT = Path(__file__).resolve().parents[1]
+SPEC = importlib.util.spec_from_file_location(
+    "validate_typecheck_diagnostics", ROOT / "tools" / "validate_typecheck_diagnostics.py"
+)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class ValidateTypecheckDiagnosticsTests(unittest.TestCase):
+    def test_lists_every_typecheck_fixture(self):
+        listed = set(MODULE.EXPECTED) | set(MODULE.EXPECTED_OK)
+        fixtures = {
+            str(path.relative_to(ROOT))
+            for path in (ROOT / "tests").glob("typecheck_*.claro")
+        }
+        fixtures.add("tests/37_object_field_types.claro")
+        self.assertEqual(listed, fixtures)
+
+    def test_includes_modern_chained_alias_method_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_object_alias_method_do_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+    def test_has_compatibility_chained_alias_method_extra_arg_fixture(self):
+        self.assertTrue(
+            (ROOT / "tests/typecheck_object_alias_method_call_extra_arg_bad.claro").exists()
+        )
+
+    def test_includes_dedicated_yesno_field_check_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_object_field_check_type_yesno_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_explicitly_typed_text_field_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_object_field_typed_text_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_explicitly_typed_yesno_field_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_object_field_typed_yesno_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_as_to_typed_field_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_object_field_typed_as_to_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_as_to_typed_field_extra_tokens_fixture(self):
+        self.assertIn(
+            "tests/typecheck_object_field_typed_as_to_extra_tokens_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_as_to_method_field_success_fixtures(self):
+        self.assertIn(
+            "tests/typecheck_method_inline_field_annotation_as_to_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+        self.assertIn(
+            "tests/typecheck_method_compat_inline_field_annotation_as_to_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_reverse_text_concatenation_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_object_field_text_concat_reverse_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_typed_function_return_fixtures(self):
+        self.assertIn("tests/typecheck_function_return_bad.claro", MODULE.EXPECTED)
+        self.assertIn("tests/typecheck_function_return_good.claro", MODULE.EXPECTED_OK)
+
+    def test_includes_compatibility_missing_return_type_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_missing_return_type_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_function_return_arithmetic_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_return_multiplication_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_unknown_function_return_expression_fixtures(self):
+        self.assertIn(
+            "tests/typecheck_function_unknown_return_expression_bad.claro",
+            MODULE.EXPECTED,
+        )
+        self.assertIn(
+            "tests/typecheck_function_unknown_return_expression_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_unknown_compatibility_function_return_expression_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_unknown_return_expression_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_missing_object_name_fixture(self):
+        self.assertIn(
+            "tests/typecheck_missing_object_name_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_missing_expected_check_type_fixture(self):
+        self.assertIn(
+            "tests/typecheck_missing_expected_type_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_missing_type_of_expression_fixture(self):
+        self.assertIn(
+            "tests/typecheck_missing_type_of_expression_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_missing_type_of_expression_before_extra_tokens_fixture(self):
+        self.assertIn(
+            "tests/typecheck_missing_type_of_expression_extra_tokens_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_lowercase_type_of_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_lowercase_type_of_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_lowercase_check_type_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_lowercase_check_type_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_lowercase_compatibility_return_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_lowercase_return_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_lowercase_compatibility_syntax_return_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_lowercase_return_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_missing_function_return_fixture(self):
+        self.assertIn("tests/typecheck_function_missing_return_bad.claro", MODULE.EXPECTED)
+
+    def test_includes_missing_method_return_type_fixtures(self):
+        self.assertIn("tests/typecheck_method_missing_return_type_bad.claro", MODULE.EXPECTED)
+        self.assertIn("tests/typecheck_method_compat_missing_return_type_bad.claro", MODULE.EXPECTED)
+
+    def test_includes_branch_missing_function_return_fixture(self):
+        self.assertIn("tests/typecheck_function_branch_missing_return_bad.claro", MODULE.EXPECTED)
+
+    def test_includes_compatibility_branch_missing_function_return_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_branch_missing_return_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_compatibility_branch_complete_function_return_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_branch_complete_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    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_compatibility_function_extra_return_tokens_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_return_extra_tokens_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_compatibility_function_empty_return_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_empty_return_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_empty_compatibility_method_return_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_empty_return_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_missing_method_return_fixture(self):
+        self.assertIn("tests/typecheck_method_missing_return_bad.claro", MODULE.EXPECTED)
+
+    def test_includes_typed_method_return_expression_fixtures(self):
+        self.assertIn("tests/typecheck_method_return_expression_bad.claro", MODULE.EXPECTED)
+        self.assertIn("tests/typecheck_method_return_expression_good.claro", MODULE.EXPECTED_OK)
+
+    def test_includes_unknown_method_return_expression_fixtures(self):
+        self.assertIn(
+            "tests/typecheck_method_unknown_return_expression_bad.claro",
+            MODULE.EXPECTED,
+        )
+        self.assertIn(
+            "tests/typecheck_method_unknown_return_expression_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_method_field_return_diagnostic_fixture(self):
+        self.assertIn("tests/typecheck_method_field_return_bad.claro", MODULE.EXPECTED)
+        self.assertIn("tests/typecheck_method_field_return_good.claro", MODULE.EXPECTED_OK)
+
+    def test_includes_compatibility_method_field_return_fixtures(self):
+        self.assertIn("tests/typecheck_method_compat_field_return_bad.claro", MODULE.EXPECTED)
+        self.assertIn("tests/typecheck_method_compat_field_return_good.claro", MODULE.EXPECTED_OK)
+
+    def test_includes_compatibility_method_return_success_fixture(self):
+        self.assertIn("tests/typecheck_method_compat_return_good.claro", MODULE.EXPECTED_OK)
+
+    def test_includes_compatibility_method_multiplication_return_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_return_multiplication_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_method_addition_return_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_return_addition_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_method_addition_return_diagnostic_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_return_addition_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_compatibility_method_subtraction_return_diagnostic_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_return_subtraction_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_compatibility_method_division_return_diagnostic_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_return_division_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_compatibility_method_multiplication_return_diagnostic_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_return_multiplication_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_compatibility_function_arithmetic_return_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_return_addition_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_function_subtraction_return_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_return_subtraction_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_function_division_return_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_return_division_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_function_multiplication_return_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_return_multiplication_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_function_missing_return_fixture(self):
+        self.assertIn(
+            "tests/typecheck_function_compat_missing_return_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_lowercase_compatibility_method_return_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_lowercase_return_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_missing_method_argument_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_call_missing_unchecked_arg_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_method_field_assignment_diagnostic_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_field_assignment_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_method_field_assignment_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_field_assignment_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_unknown_method_field_assignment_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_unknown_field_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_typed_method_unknown_field_diagnostics(self):
+        self.assertIn(
+            "tests/typecheck_method_unknown_field_typed_bad.claro",
+            MODULE.EXPECTED,
+        )
+        self.assertIn(
+            "tests/typecheck_method_compat_unknown_field_typed_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_explicitly_typed_method_field_assignment_diagnostic(self):
+        self.assertIn(
+            "tests/typecheck_method_typed_field_assignment_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_method_text_field_assignment_diagnostic_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_text_field_assignment_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_method_text_field_assignment_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_text_field_assignment_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_method_text_concatenation_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_text_concat_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_method_text_concatenation_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_text_concat_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_yesno_method_field_assignment_diagnostics(self):
+        self.assertIn(
+            "tests/typecheck_method_yesno_field_assignment_bad.claro",
+            MODULE.EXPECTED,
+        )
+        self.assertIn(
+            "tests/typecheck_method_compat_yesno_field_assignment_bad.claro",
+            MODULE.EXPECTED,
+        )
+
+    def test_includes_compatibility_yesno_method_field_assignment_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_yesno_field_assignment_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_number_method_field_assignment_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_field_assignment_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_method_field_check_type_fixtures(self):
+        self.assertIn(
+            "tests/typecheck_method_field_check_type_bad.claro",
+            MODULE.EXPECTED,
+        )
+        self.assertIn(
+            "tests/typecheck_method_field_check_type_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_compatibility_method_field_check_type_fixtures(self):
+        self.assertIn(
+            "tests/typecheck_method_compat_field_check_type_bad.claro",
+            MODULE.EXPECTED,
+        )
+        self.assertIn(
+            "tests/typecheck_method_compat_field_check_type_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_includes_yesno_method_field_check_type_success_fixture(self):
+        self.assertIn(
+            "tests/typecheck_method_yesno_field_check_type_good.claro",
+            MODULE.EXPECTED_OK,
+        )
+
+    def test_release_validation_runs_method_field_diagnostic_fixtures(self):
+        source = (ROOT / "src" / "claro.c").read_text()
+        for fixture in (
+            "tests/typecheck_method_inline_field_annotation_as_to_good.claro",
+            "tests/typecheck_method_compat_inline_field_annotation_as_to_good.claro",
+            "tests/typecheck_method_field_assignment_bad.claro",
+            "tests/typecheck_method_text_field_assignment_bad.claro",
+            "tests/typecheck_method_compat_text_field_assignment_bad.claro",
+            "tests/typecheck_method_yesno_field_assignment_bad.claro",
+            "tests/typecheck_method_compat_yesno_field_assignment_bad.claro",
+            "tests/typecheck_method_field_check_type_bad.claro",
+            "tests/typecheck_method_compat_unknown_field_bad.claro",
+            "tests/typecheck_method_unknown_field_typed_bad.claro",
+            "tests/typecheck_method_compat_unknown_field_typed_bad.claro",
+            "tests/typecheck_duplicate_field_bad.claro",
+        ):
+            self.assertIn(f'"{fixture}"', source)
+
+    def test_release_validation_runs_compatibility_function_missing_return_fixture(self):
+        source = (ROOT / "src" / "claro.c").read_text()
+        self.assertIn(
+            '"tests/typecheck_function_compat_missing_return_bad.claro"',
+            source,
+        )
+
+    def test_release_validation_runs_method_call_fixture(self):
+        result = subprocess.run(
+            [str(ROOT / "claro"), "validate"],
+            cwd=ROOT,
+            capture_output=True,
+            text=True,
+        )
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertIn("tests/typecheck_method_call_bad.claro", result.stdout)
+        self.assertIn(
+            '"tests/typecheck_method_compat_lowercase_return_good.claro"',
+            (ROOT / "src" / "claro.c").read_text(),
+        )
+        self.assertIn(
+            '"tests/typecheck_method_compat_return_multiplication_bad.claro"',
+            (ROOT / "src" / "claro.c").read_text(),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/typecheck_duplicate_class_bad.claro

@@ -0,0 +1,7 @@
+CLASS Player
+    HAS score NUMBER
+END
+
+CLASS Player
+    HAS name TEXT
+END

tests/typecheck_duplicate_field_bad.claro

@@ -0,0 +1,7 @@
+CLASS Player
+    HAS score NUMBER
+    HAS score TEXT
+END
+
+NEW Player player
+SET player.score 10

tests/typecheck_duplicate_function_bad.claro

@@ -0,0 +1,7 @@
+TEACH greet name
+    SAY name
+END
+
+TEACH greet person
+    SAY person
+END

tests/typecheck_duplicate_object_bad.claro

@@ -0,0 +1,6 @@
+CLASS Player
+    HAS score NUMBER
+END
+
+NEW Player player
+NEW Player player

tests/typecheck_extra_check_type_tokens_bad.claro

@@ -0,0 +1,2 @@
+SET score NUMBER 10
+CHECK TYPE score IS NUMBER TEXT

tests/typecheck_extra_class_tokens_bad.claro

@@ -0,0 +1,5 @@
+CLASS Player Extra
+    HAS score NUMBER
+END
+
+NEW Player player

tests/typecheck_extra_field_tokens_bad.claro

@@ -0,0 +1,5 @@
+CLASS Player
+    HAS score NUMBER TEXT
+END
+
+NEW Player player

tests/typecheck_extra_new_tokens_bad.claro

@@ -0,0 +1,5 @@
+CLASS Player
+    HAS score NUMBER
+END
+
+NEW Player player extra

tests/typecheck_extra_teach_tokens_bad.claro

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

tests/typecheck_extra_type_of_tokens_bad.claro

@@ -0,0 +1,2 @@
+SET score NUMBER 10
+TYPE OF score AS kind extra

tests/typecheck_function_branch_complete_good.claro

@@ -0,0 +1,9 @@
+TEACH choose flag RETURNS NUMBER
+    IF flag
+        RETURN 1
+    ELSE
+        RETURN 2
+    END
+END
+
+DO choose YES

tests/typecheck_function_branch_missing_return_bad.claro

@@ -0,0 +1,5 @@
+TEACH choose flag RETURNS NUMBER
+    IF flag
+        RETURN 1
+    END
+END

tests/typecheck_function_call_missing_unchecked_arg_bad.claro

@@ -0,0 +1,5 @@
+TEACH greet name
+    SAY name
+END
+
+CALL greet WITH

tests/typecheck_function_call_unknown_bad.claro

@@ -0,0 +1,6 @@
+TEACH square amount
+    CHECK TYPE amount IS NUMBER
+    SAY amount
+END
+
+CALL squre WITH 4

tests/typecheck_function_compat_branch_complete_good.claro

@@ -0,0 +1,9 @@
+TEACH choose TAKES flag RETURNS NUMBER
+    IF flag
+        RETURN 1
+    ELSE
+        RETURN 2
+    END
+LEARNED
+
+CALL choose WITH YES

tests/typecheck_function_compat_branch_missing_return_bad.claro

@@ -0,0 +1,5 @@
+TEACH choose TAKES flag RETURNS NUMBER
+    IF flag
+        RETURN 1
+    END
+LEARNED

tests/typecheck_function_compat_duplicate_param_bad.claro

@@ -0,0 +1,4 @@
+TEACH greet TAKES name, name
+    SAY name
+LEARNED
+CALL greet WITH "Ada", "Grace"

tests/typecheck_function_compat_empty_return_bad.claro

@@ -0,0 +1,4 @@
+TEACH square TAKES amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN
+LEARNED

tests/typecheck_function_compat_lowercase_return_good.claro

@@ -0,0 +1,6 @@
+TEACH square TAKES amount returns NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount
+LEARNED
+
+CALL square WITH 4

tests/typecheck_function_compat_missing_return_bad.claro

@@ -0,0 +1,3 @@
+TEACH square TAKES amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+LEARNED

tests/typecheck_function_compat_missing_return_type_bad.claro

@@ -0,0 +1,3 @@
+TEACH greet TAKES name RETURNS
+    RETURN name
+LEARNED

tests/typecheck_function_compat_return_addition_good.claro

@@ -0,0 +1,6 @@
+TEACH total TAKES amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount + 1
+LEARNED
+
+CALL total WITH 4

tests/typecheck_function_compat_return_bad.claro

@@ -0,0 +1,6 @@
+TEACH square TAKES amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN "oops"
+LEARNED
+
+CALL square WITH 4

tests/typecheck_function_compat_return_division_good.claro

@@ -0,0 +1,6 @@
+TEACH total TAKES amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount / 2
+LEARNED
+
+CALL total WITH 4

tests/typecheck_function_compat_return_extra_tokens_bad.claro

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

tests/typecheck_function_compat_return_good.claro

@@ -0,0 +1,6 @@
+TEACH square TAKES amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount
+LEARNED
+
+CALL square WITH 4

tests/typecheck_function_compat_return_multiplication_good.claro

@@ -0,0 +1,6 @@
+TEACH total TAKES amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount * 2
+LEARNED
+
+CALL total WITH 4

tests/typecheck_function_compat_return_subtraction_good.claro

@@ -0,0 +1,6 @@
+TEACH total TAKES amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount - 1
+LEARNED
+
+CALL total WITH 4

tests/typecheck_function_compat_unknown_return_expression_bad.claro

@@ -0,0 +1,4 @@
+TEACH square TAKES amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN missing
+LEARNED

tests/typecheck_function_duplicate_param_bad.claro

@@ -0,0 +1,4 @@
+TEACH greet name, name
+    SAY name
+END
+DO greet "Ada", "Grace"

tests/typecheck_function_empty_return_bad.claro

@@ -0,0 +1,4 @@
+TEACH square amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN
+END

tests/typecheck_function_extra_arg_bad.claro

@@ -0,0 +1,6 @@
+TEACH square amount
+    CHECK TYPE amount IS NUMBER
+    SAY amount
+END
+
+DO square 5, 6

tests/typecheck_function_lowercase_return_bad.claro

@@ -0,0 +1,5 @@
+TEACH square amount returns NUMBER
+    RETURN "oops"
+END
+
+DO square 4

tests/typecheck_function_lowercase_return_good.claro

@@ -0,0 +1,6 @@
+TEACH square TAKES amount returns NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount
+LEARNED
+
+CALL square WITH 4

tests/typecheck_function_missing_arg_bad.claro

@@ -0,0 +1,6 @@
+TEACH square amount
+    CHECK TYPE amount IS NUMBER
+    SAY amount
+END
+
+DO square

tests/typecheck_function_missing_return_bad.claro

@@ -0,0 +1,5 @@
+TEACH square amount RETURNS NUMBER
+    SAY amount
+END
+
+DO square 4

tests/typecheck_function_missing_unchecked_arg_bad.claro

@@ -0,0 +1,5 @@
+TEACH greet name
+    SAY name
+END
+
+DO greet

tests/typecheck_function_nested_branch_complete_good.claro

@@ -0,0 +1,13 @@
+TEACH choose flag RETURNS NUMBER
+    IF flag
+        IF flag
+            RETURN 1
+        ELSE
+            RETURN 2
+        END
+    ELSE
+        RETURN 3
+    END
+END
+
+DO choose YES

tests/typecheck_function_return_arithmetic_bad.claro

@@ -0,0 +1,4 @@
+TEACH total amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount + "oops"
+END

tests/typecheck_function_return_bad.claro

@@ -0,0 +1,6 @@
+TEACH square amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN "oops"
+END
+
+DO square 4

tests/typecheck_function_return_division_bad.claro

@@ -0,0 +1,4 @@
+TEACH total amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount / "oops"
+END

tests/typecheck_function_return_division_good.claro

@@ -0,0 +1,6 @@
+TEACH halve amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount / 2
+END
+
+DO halve 8

tests/typecheck_function_return_expression_bad.claro

@@ -0,0 +1,4 @@
+TEACH label amount RETURNS TEXT
+    CHECK TYPE amount IS NUMBER
+    RETURN amount + 1
+END

tests/typecheck_function_return_expression_good.claro

@@ -0,0 +1,4 @@
+TEACH square amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount + 1
+END

tests/typecheck_function_return_extra_tokens_bad.claro

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

tests/typecheck_function_return_good.claro

@@ -0,0 +1,6 @@
+TEACH square amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount
+END
+
+DO square 4

tests/typecheck_function_return_multiplication_bad.claro

@@ -0,0 +1,4 @@
+TEACH total amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount * "oops"
+END

tests/typecheck_function_return_multiplication_good.claro

@@ -0,0 +1,6 @@
+TEACH scale amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount * 2
+END
+
+DO scale 3

tests/typecheck_function_return_subtraction_bad.claro

@@ -0,0 +1,4 @@
+TEACH total amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount - "oops"
+END

tests/typecheck_function_return_subtraction_good.claro

@@ -0,0 +1,6 @@
+TEACH difference amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount - 2
+END
+
+DO difference 5

tests/typecheck_function_unknown_bad.claro

@@ -0,0 +1,6 @@
+TEACH square amount
+    CHECK TYPE amount IS NUMBER
+    SAY amount
+END
+
+DO squre 4

tests/typecheck_function_unknown_return_expression_bad.claro

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

tests/typecheck_function_unknown_return_expression_good.claro

@@ -0,0 +1,4 @@
+TEACH square amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount
+END

tests/typecheck_invalid_expected_type_bad.claro

@@ -0,0 +1,2 @@
+SET score NUMBER 10
+CHECK TYPE score IS BANANA

tests/typecheck_invalid_return_type_bad.claro

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

tests/typecheck_lowercase_check_type_good.claro

@@ -0,0 +1,2 @@
+set score number 10
+check type score is number

tests/typecheck_lowercase_type_of_good.claro

@@ -0,0 +1,2 @@
+set score number 10
+type of score as kind

tests/typecheck_method_branch_missing_return_bad.claro

@@ -0,0 +1,7 @@
+CLASS Player
+    TEACH choose flag RETURNS NUMBER
+        IF flag
+            RETURN 1
+        END
+    END
+END

tests/typecheck_method_call_bad.claro

@@ -0,0 +1,11 @@
+CLASS Player
+    HAS score NUMBER
+
+    TEACH add points
+        CHECK TYPE points IS NUMBER
+        SET score score + points
+    END
+END
+
+NEW Player player
+CALL player.add WITH "five"

tests/typecheck_method_call_good.claro

@@ -0,0 +1,11 @@
+CLASS Player
+    HAS score NUMBER
+
+    TEACH add points
+        CHECK TYPE points IS NUMBER
+        SET score score + points
+    END
+END
+
+NEW Player player
+CALL player.add WITH 5

tests/typecheck_method_call_missing_unchecked_arg_bad.claro

@@ -0,0 +1,10 @@
+CLASS Player
+    HAS name TEXT
+
+    TEACH rename newName
+        SET name newName
+    END
+END
+
+NEW Player player
+CALL player.rename WITH

tests/typecheck_method_call_unknown_method_bad.claro

@@ -0,0 +1,11 @@
+CLASS Player
+    HAS score NUMBER
+
+    TEACH add points
+        CHECK TYPE points IS NUMBER
+        SET score score + points
+    END
+END
+
+NEW Player player
+CALL player.fly WITH 5

tests/typecheck_method_call_unknown_object_bad.claro

@@ -0,0 +1,10 @@
+CLASS Player
+    HAS score NUMBER
+
+    TEACH add points
+        CHECK TYPE points IS NUMBER
+        SET score score + points
+    END
+END
+
+CALL player.add WITH 5

tests/typecheck_method_call_unknown_object_unknown_method_bad.claro

@@ -0,0 +1,10 @@
+CLASS Player
+    HAS score NUMBER
+
+    TEACH add points
+        CHECK TYPE points IS NUMBER
+        SET score score + points
+    END
+END
+
+CALL player.fly WITH 5

tests/typecheck_method_compat_duplicate_name_bad.claro

@@ -0,0 +1,12 @@
+CLASS Player
+    TEACH show TAKES
+        SAY "first"
+    LEARNED
+
+    TEACH show TAKES
+        SAY "second"
+    LEARNED
+END
+
+NEW Player player
+CALL player.show WITH

tests/typecheck_method_compat_duplicate_param_bad.claro

@@ -0,0 +1,8 @@
+CLASS Player
+    TEACH greet TAKES name, name
+        SAY name
+    LEARNED
+ENDCLASS
+
+NEW Player player
+CALL player.greet WITH "Ada", "Grace"

tests/typecheck_method_compat_empty_return_bad.claro

@@ -0,0 +1,5 @@
+CLASS Player
+    TEACH score TAKES amount RETURNS NUMBER
+        RETURN
+    LEARNED
+ENDCLASS

tests/typecheck_method_compat_field_assignment_good.claro

@@ -0,0 +1,9 @@
+CLASS Player
+    HAS score NUMBER
+    TEACH add TAKES amount
+        SET score amount + 1
+    LEARNED
+ENDCLASS
+
+NEW Player player
+CALL player.add WITH 4

tests/typecheck_method_compat_field_check_type_bad.claro

@@ -0,0 +1,9 @@
+CLASS Player
+    HAS name TEXT
+    TEACH rename TAKES replacement
+        CHECK TYPE name IS NUMBER
+    LEARNED
+ENDCLASS
+
+NEW Player player
+CALL player.rename WITH "Ada"

tests/typecheck_method_compat_field_check_type_good.claro

@@ -0,0 +1,9 @@
+CLASS Player
+    HAS name TEXT
+    TEACH rename TAKES replacement
+        CHECK TYPE name IS TEXT
+    LEARNED
+ENDCLASS
+
+NEW Player player
+CALL player.rename WITH "Ada"

tests/typecheck_method_compat_field_return_bad.claro

@@ -0,0 +1,7 @@
+CLASS Player
+    HAS score NUMBER
+
+    TEACH label TAKES amount RETURNS TEXT
+        RETURN score
+    LEARNED
+ENDCLASS

tests/typecheck_method_compat_field_return_good.claro

@@ -0,0 +1,10 @@
+CLASS Player
+    HAS score NUMBER
+
+    TEACH score_value TAKES amount RETURNS NUMBER
+        RETURN score
+    LEARNED
+ENDCLASS
+
+NEW Player player
+CALL player.score_value WITH 4