Claro/docs/DOCUMENTATION_AUDIT_v1.18.26.md

Claro v1.18.26 Documentation Audit

Date: 2026-06-05

Scope

Reviewed the Markdown documentation in the Claro v1.18.26 package:

• README.md
• CHANGELOG.md
• lessons/README.md
• docs/*.md — 55 files

Total Markdown files inventoried: 57.

Overall finding

This audit is a historical snapshot from the first v1.18.26 documentation cleanup pass. At audit time, the docs were useful and broad, but they read like a historical bundle plus a current release bundle. That was okay for internal development, but before a polished public release the documentation needed to be reorganized so beginners saw one clear current path and advanced/history material was separated.

The cleanup notes at the end of this file record the follow-up work that has already been completed. For current learner guidance, use CURRENT_STATUS.md, ROADMAP.md, and the README documentation map before relying on the problem list below.

Current strongest documentation

These docs are clear and should remain part of the current user-facing docs:

• README.md — good high-level overview of Claro v1.18.26.
• docs/QUICK_START.md — important beginner entry point.
• docs/FIRST_HOUR.md — useful learner sequence.
• lessons/README.md — useful for guided learning.
• docs/CLI.md — needed command reference.
• docs/SPEC.md — core language reference.
• docs/ERRORS.md — important for beginner-friendly diagnostics.
• docs/FORMATTER.md
• docs/LINTER.md
• docs/TESTING.md
• docs/ADVANCED_STATIC_TYPING.md
• docs/IDE.md
• docs/CONCURRENCY.md
• docs/V1_15_OBJECTS_CLASSES.md
• docs/V1_16_PACKAGES_PROJECTS.md
• docs/V1_17_NETWORKING.md
• docs/SDL12.md
• docs/FUTURE_FEATURES_ROADMAP.md

Main documentation problems found at audit time

1. Old RC language is still mixed with current docs

At audit time, several docs still said or implied that Claro was in an old release-candidate phase:

• docs/ROADMAP.md still says:
  • RC3 - Classroom Readiness
  • RC4 - Final Polish
  • 1.0 - Stable Beginner Release
• docs/CLASSROOM_READINESS.md says Claro RC3 is suitable... but not final 1.0.
• docs/LINTER.md says RC3 catches:.
• docs/TESTING.md mentions validating an RC3 package and validate_rc3.py.
• docs/FIRST_HOUR.md references RC2 behavior.

Recommendation: keep historical RC docs, but move them under a clear docs/history/ section or label them as historical at the top.

2. Current version story is inconsistent

The package is v1.18.26, but several docs are tied to old versions:

• docs/STABLE_RELEASE.md is specifically Claro v1.10.26 Stable Release.
• docs/POST_1_0_ROADMAP.md lists old future milestones like v1.11.26 through v1.15.26, even though many are already superseded.
• docs/V1_14_STATIC_TYPES.md, docs/V1_15_OBJECTS_CLASSES.md, etc. are useful but read like version-specific release notes instead of current feature docs.

Recommendation: use current feature docs for beginners and keep old version docs as historical release notes.

3. The complete-platform roadmap needs to be promoted

docs/FUTURE_FEATURES_ROADMAP.md is the best roadmap for the complete beginner-language goal:

1. Advanced static typing
2. IDE support
3. Concurrency
4. Web programming
5. GUI/game engine
6. Package registry
7. Optimization

But it should now explicitly reflect the user's desired completion targets:

• SDL graphics
• classes/objects
• package manager
• networking
• threads/concurrency
• strong static types
• advanced IDE support

Recommendation: rename or supplement it with docs/COMPLETE_PLATFORM_ROADMAP.md and track each feature as Not Started / Foundation / Beta / Stable.

4. SDL graphics are correctly marked as not stable, but need a clearer beginner path

docs/SDL12.md is honest and says SDL is not included in the current stable executable. That is good.

Current status:

• Placeholder graphics commands exist.
• Real SDL commands are planned/experimental.
• examples/experimental_sdl/ will fail with current claro.exe.

Recommendation: add docs/GRAPHICS.md with two tracks:

• Current: beginner-safe placeholder graphics commands.
• Future: optional SDL backend behind a build flag.

5. Advanced IDE support has a foundation, not a complete IDE experience

docs/IDE.md documents:

• claro ide
• metadata JSON
• completion list
• diagnostics helper

Missing for a complete beginner platform:

• syntax highlighting package
• real LSP server or editor extension
• hover help
• go-to definition
• code actions/fixes
• integrated lesson/help flow

Recommendation: add docs/EDITOR_EXTENSION_PLAN.md or expand docs/IDE.md with a phased roadmap.

6. Static types are currently partial

docs/ADVANCED_STATIC_TYPING.md clearly documents typed lists and maps checked by claro typecheck.

Missing for strong static types:

• function parameter types
• function return types
• object method type checking
• typed imports
• better type checking across branches/loops
• runtime enforcement strategy for containers

Recommendation: add a Strong Static Types section to the roadmap and keep the beginner syntax examples very small.

7. Concurrency is deterministic foundation, not real threads yet

docs/CONCURRENCY.md is clear that Claro has cooperative concurrency foundations and no native threads yet.

Missing for complete platform:

• real cooperative scheduler
• cancellation
• timeouts
• message passing
• eventually optional native threads only if safe

Recommendation: avoid saying "threads" in user-facing docs until semantics are safe; use "tasks" first.

8. Package manager foundation exists, but registry is not complete

docs/V1_16_PACKAGES_PROJECTS.md documents local package workflow, manifests, lock files, and safety rules.

Missing for full package ecosystem:

• dependency versions
• local install from path
• package publish/export
• remote registry protocol
• signature/checksum verification for downloaded packages

Recommendation: add docs/PACKAGE_REGISTRY.md before implementing online downloads.

9. Networking foundation exists, web server does not

docs/V1_17_NETWORKING.md is good for HTTP client commands and offline claro:// URLs.

Missing for complete platform:

• beginner web server syntax
• routes
• request/response objects
• local-only safe server mode
• docs and examples for web apps

Recommendation: add docs/WEB_SERVER_PLAN.md before implementing sockets.

Recommended cleanup order from the original audit

1. Add a docs/CURRENT_STATUS.md file with a plain feature matrix for v1.18.26.
2. Rewrite docs/ROADMAP.md so it no longer describes RC3/RC4 as current.
3. Move or label RC docs as historical.
4. Split docs into beginner-facing vs maintainer/history docs.
5. Add complete-platform roadmap docs for:
   • strong static types
   • IDE/editor support
   • cooperative tasks/threads
   • package registry
   • web server/networking
   • SDL graphics
   • object/class polish
6. Update README.md to point beginners only to current docs.

Feature status summary

• Beginner scripting core: stable foundation.
• Classes/objects: foundation present; needs polish and stronger typing.
• Package manager: local foundation present; registry incomplete.
• Networking: HTTP client foundation present; web server incomplete.
• Threads/concurrency: cooperative foundation present; real scheduling/threads incomplete.
• Strong static types: typed variables and containers foundation present; function/object/import typing incomplete.
• Advanced IDE support: metadata/helper foundation present; full editor/LSP experience incomplete.
• SDL graphics: not included in stable executable; experimental/planned only.

Bottom line

Documentation is good enough for internal development, but before the complete beginner-language release it needs a current-status pass. The largest documentation problem is not missing docs; it is that historical RC/version docs are mixed into the current package without clear labeling.

Cleanup pass completed

A documentation cleanup pass was applied after this audit:

• Added CURRENT_STATUS.md.
• Rewrote ROADMAP.md so old RC3/RC4/1.0 milestones are no longer presented as current.
• Added complete-platform planning docs: COMPLETE_PLATFORM_ROADMAP.md, GRAPHICS.md, PACKAGE_REGISTRY.md, WEB_SERVER_PLAN.md, and EDITOR_EXTENSION_PLAN.md.
• Updated README.md with a beginner-first documentation map.
• Updated stale current-facing docs: CLASSROOM_READINESS.md, LINTER.md, TESTING.md, FIRST_HOUR.md, SPEC.md, and POST_1_0_ROADMAP.md.
• Labeled RC and older validation/release files as historical.