docs: clarify Claro learner documentation status

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.

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.
 

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.

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