From 078b7874d3480ee7e03d75661dd0daac2b839f10 Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Sun, 7 Jun 2026 16:39:29 -0600 Subject: [PATCH] docs: clarify Claro learner documentation status --- CHANGELOG.md | 6 ++++++ README.md | 17 +++++------------ docs/CURRENT_STATUS.md | 16 ++++++++++++++++ docs/FUTURE_FEATURES_ROADMAP.md | 22 ++++++++++++++++++++-- 4 files changed, 47 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index af101ac..6ec8980 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## v1.18.26-dev learner documentation status cleanup + +- Grouped the README documentation map by current feature status so new learners can see what is ready, what is foundation-level, and what is still planned or experimental. +- Added a learner-first trust order to `docs/CURRENT_STATUS.md`. +- Marked `docs/FUTURE_FEATURES_ROADMAP.md` as a historical implementation plan plus remaining ideas, with completed slices separated from still-planned work. + ## v1.18.26-dev documentation audit consistency update - Clarified that `docs/DOCUMENTATION_AUDIT_v1.18.26.md` is a historical snapshot from the first documentation cleanup pass. diff --git a/README.md b/README.md index 8c61e3a..57e19bc 100644 --- a/README.md +++ b/README.md @@ -223,19 +223,12 @@ If you are new to Claro, start here: 4. `docs/CLI.md` 5. `docs/CURRENT_STATUS.md` -Feature references: +Feature references by current status: -- Language reference: `docs/SPEC.md` -- Friendly errors and checking: `docs/ERRORS.md`, `docs/LINTER.md`, `docs/TESTING.md` -- Formatter: `docs/FORMATTER.md` -- Static typing: `docs/ADVANCED_STATIC_TYPING.md` -- Objects/classes: `docs/V1_15_OBJECTS_CLASSES.md` -- Projects/packages: `docs/V1_16_PACKAGES_PROJECTS.md`, `docs/PACKAGE_REGISTRY.md` -- Networking/web: `docs/V1_17_NETWORKING.md`, `docs/WEB_SERVER_PLAN.md` -- Tasks/concurrency: `docs/CONCURRENCY.md` -- IDE/editor support: `docs/IDE.md`, `docs/EDITOR_EXTENSION_PLAN.md` -- Graphics/SDL status: `docs/GRAPHICS.md`, `docs/SDL12.md` -- Roadmaps: `docs/ROADMAP.md`, `docs/COMPLETE_PLATFORM_ROADMAP.md` +- **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`). +- **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`). +- **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`). +- **Roadmaps:** `docs/ROADMAP.md` for the current v1 direction and `docs/COMPLETE_PLATFORM_ROADMAP.md` for the larger platform goal. 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. diff --git a/docs/CURRENT_STATUS.md b/docs/CURRENT_STATUS.md index 31d7fff..faf147f 100644 --- a/docs/CURRENT_STATUS.md +++ b/docs/CURRENT_STATUS.md @@ -185,3 +185,19 @@ Good starting docs: ## 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. + +## Which docs should a new learner trust first? + +For the current v1.18.26 package, read docs in this order: + +1. `QUICK_START.md`, `FIRST_HOUR.md`, and `lessons/README.md` for first programs. +2. `README.md` and this file for the current feature map. +3. `ROADMAP.md` for the next v1 work. + +Use feature docs with these expectations: + +- **Ready for beginner lessons:** `SPEC.md`, `SIMPLE_FUNCTIONS.md`, `ERRORS.md`, `LINTER.md`, `TESTING.md`, `FORMATTER.md`. +- **Foundation present:** `ADVANCED_STATIC_TYPING.md`, `V1_14_STATIC_TYPES.md`, `V1_15_OBJECTS_CLASSES.md`, `V1_16_PACKAGES_PROJECTS.md`, `V1_17_NETWORKING.md`, `CONCURRENCY.md`, `IDE.md`. +- **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. diff --git a/docs/FUTURE_FEATURES_ROADMAP.md b/docs/FUTURE_FEATURES_ROADMAP.md index 300d2b7..bbe6896 100644 --- a/docs/FUTURE_FEATURES_ROADMAP.md +++ b/docs/FUTURE_FEATURES_ROADMAP.md @@ -1,6 +1,24 @@ # Claro Future Features Roadmap -> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task. +Current status: **historical implementation plan plus remaining ideas**. + +This file began as a task-by-task plan. Some early slices have since been completed or moved into current feature docs. For the current learner-facing truth, start with `CURRENT_STATUS.md`, `ROADMAP.md`, and `COMPLETE_PLATFORM_ROADMAP.md`. + +Already moved into current foundations: + +- typed list/map checking and clearer type mismatch diagnostics +- IDE metadata and the command-based diagnostics helper +- deterministic cooperative task commands +- HTTP client safety with offline `claro://` test URLs +- local project/package manifest and lockfile hardening + +Still planned or experimental: + +- real web server API +- remote package registry/install flow +- full editor extension/LSP experience +- optional SDL graphics backend +- optimization work backed by benchmarks **Goal:** Grow Claro from a beginner scripting language into a stable accessible platform without breaking the learning-friendly core. @@ -10,7 +28,7 @@ --- -> Current note: Some tasks in this implementation plan have since been partially completed or moved into dedicated status docs. For the current high-level view, start with `ROADMAP.md`, `CURRENT_STATUS.md`, and `COMPLETE_PLATFORM_ROADMAP.md`. +> Current note: this is not the beginner starting path. Use it for remaining implementation ideas only after checking `CURRENT_STATUS.md`. ## Priority order