docs: clarify Claro v1 status and validation

2026-06-07 03:03:13 -06:00
parent 0da1095c03
commit 1e0ea06d21
74 changed files with 2351 additions and 336 deletions
@@ -0,0 +1,187 @@
+# Claro v1.18.26 Current Status
+
+This file is the beginner-safe status map for the current package. It separates what is ready to use from what is historical, experimental, or still planned.
+
+## How to read the status labels
+
+- **Stable foundation**: good enough for normal examples and beginner learning.
+- **Foundation present**: usable, but still missing important polish or coverage.
+- **Experimental/planned**: do not rely on it in beginner lessons yet.
+- **Historical**: kept for release history, not current instructions.
+
+## Feature matrix
+
+### Beginner scripting core
+
+Status: **Stable foundation**
+
+Ready now:
+- variables with `SET`
+- output with `SAY`
+- input with `ASK`
+- choices with `IF` / `ELSE` / `END`
+- loops
+- lists and maps
+- files, JSON, and text helpers
+- friendly checking with `claro check`
+
+Good starting docs:
+- `QUICK_START.md`
+- `FIRST_HOUR.md`
+- `CLI.md`
+- `SPEC.md`
+
+### Functions
+
+Status: **Stable foundation**
+
+Ready now:
+- simple modern form: `TEACH name arg` ... `END`
+- compatibility form: `TEACH name TAKES arg` ... `LEARNED`
+- calls with `DO` or older `CALL ... WITH`
+
+Good starting docs:
+- `SIMPLE_FUNCTIONS.md`
+- `README.md`
+
+### Static type safety
+
+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`
+
+Still needed:
+- typed function parameters and return values
+- type checking through branches and loops
+- object method and field type checking
+- typed imports/modules
+
+Good starting docs:
+- `ADVANCED_STATIC_TYPING.md`
+- `V1_14_STATIC_TYPES.md` (feature history plus examples)
+
+### Objects and classes
+
+Status: **Foundation present**
+
+Ready now:
+- `CLASS`
+- typed `HAS` fields
+- `NEW`
+- field access such as `player.score`
+- simple methods
+- object helper commands
+
+Still needed:
+- stronger method/field type checking
+- constructor/default-value polish
+- clearer object debugging and teaching examples
+
+Good starting docs:
+- `V1_15_OBJECTS_CLASSES.md`
+- `README.md`
+
+### Package and project workflow
+
+Status: **Foundation present**
+
+Ready now:
+- `claro new`
+- `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
+
+Still needed:
+- install from local path
+- package version constraints
+- publish/export format
+- remote registry protocol
+- checksum/signature verification before downloads
+
+Good starting docs:
+- `V1_16_PACKAGES_PROJECTS.md`
+- `PACKAGE_REGISTRY.md`
+
+### Networking
+
+Status: **Foundation present**
+
+Ready now:
+- beginner HTTP commands
+- offline `claro://` URLs for tests and lessons
+- `LASTHTTP`
+- real `http://` and `https://` through `curl` when available
+
+Still needed:
+- web server syntax
+- routes
+- request/response helpers
+- localhost-safe server mode
+
+Good starting docs:
+- `V1_17_NETWORKING.md`
+- `WEB_SERVER_PLAN.md`
+
+### Concurrency and tasks
+
+Status: **Foundation present**
+
+Ready now:
+- deterministic task/concurrency helpers where documented
+- beginner-safe direction toward cooperative tasks
+
+Still needed:
+- full cooperative scheduler semantics
+- cancellation
+- timeouts
+- message passing
+- decision on whether native threads should ever be exposed
+
+Good starting docs:
+- `CONCURRENCY.md`
+
+### IDE/editor support
+
+Status: **Foundation present**
+
+Ready now:
+- `claro ide`
+- metadata JSON
+- completion list
+- diagnostics helper
+
+Still needed:
+- syntax highlighting package
+- editor extension
+- hover help
+- go-to-definition
+- code actions/fixes
+- full LSP server if/when useful
+
+Good starting docs:
+- `IDE.md`
+- `EDITOR_EXTENSION_PLAN.md`
+
+### Graphics and SDL
+
+Status: **Experimental/planned**
+
+Ready now:
+- placeholder/planned graphics documentation
+- experimental examples may exist for future SDL work
+
+Not ready in the stable executable:
+- real SDL window/drawing support
+- beginner game lessons that run everywhere
+
+Good starting docs:
+- `GRAPHICS.md`
+- `SDL12.md`
+
+## Historical docs
+
+Files named `RC*_NOTES.md`, `RC*_VALIDATION.md`, older `V1_*_VALIDATION.md`, and older release notes are kept for project history. They may mention old version numbers, old planned milestones, or old validation scripts. Use them to understand how Claro evolved; do not treat them as the current beginner path.