docs(release): finalize v0.5.0 release text

Author: DKFuH

docs/releases/v0.5.0.md

@@ -1,48 +1,65 @@
 # OrgScript v0.5.0
 
-OrgScript v0.5.0 is the first adoption and polish release.
+OrgScript v0.5.0 is a developer-experience, adoption, and polish release.
 
-This release focuses on making OrgScript as easy as possible to try, read, and understand. Instead of expanding the language, we improved the developer experience at the "front door"—our README, examples, diagnostics, and editor highlighting.
+This release does not expand the language itself. Instead, it improves how OrgScript is read, tried, understood, and used in practice.
 
 ## Highlights
 
-- **Visual Showcase**: A revamped `README.md` showing the "Three-Value Flow" from `.orgs` source to visual artifacts.
-- **60-Second Quickstart**: Faster path from installation to first successful command.
-- **Improved Highlighting**: Refined TextMate grammar for VS Code, including inline keywords and dotted properties.
-- **Curated Examples**: Reorganized example catalog categorized by learning depth (Simple, Realistic, Advanced).
-- **Polished Diagnostics**: More readable CLI reports with consistent padding, bracketed codes, and "passed" status messaging.
-- **Language Evolution Governance**: Documented boundaries between core language growth and tooling-level extensions.
+### Better front door and onboarding
+- The README now presents the core value of OrgScript more clearly
+- Added a stronger quickstart path
+- The “three-value flow” is now visible near the top:
+  - OrgScript source
+  - Mermaid diagram
+  - Markdown summary
 
-## CLI and UX
+### Improved VS Code highlighting
+- Refined the initial VS Code syntax grammar
+- Better handling for inline keywords and dotted references
+- Improved local editor onboarding documentation
 
-- Updated `check`, `lint`, and `format --check` to use `passed` instead of `ok` in human-readable output.
-- Refined diagnostic line formatting: `  SEVERITY [code] file:line - message`.
-- Added consistent padding to severity levels for better vertical alignment in logs.
-- Synchronized the diagnostics text contract in `spec/diagnostics.md` with the new CLI behavior.
+### Curated example catalog
+- The example catalog is now structured into:
+  - simple
+  - realistic
+  - advanced
+- Each example is easier to understand as a learning and adoption asset
 
-## Documentation and Onboarding
+### Diagnostics UX polish
+- CLI text output is now more consistent and deliberate
+- `ok` is now reported as `passed`
+- Diagnostic codes are shown more clearly in bracketed form
+- Output spacing and readability were improved without changing the documented JSON contract
 
-- Added a visual showcase in the root `README.md`.
-- Added categorized example descriptions in `examples/README.md`.
-- Added `docs/language-evolution.md` for clear project governance.
-- Improved VS Code extension onboarding and local testing documentation.
+### Language evolution guidance
+- Added `docs/language-evolution.md`
+- Clarifies what belongs to core language evolution vs tooling, exporters, and editor integrations
+- Establishes a cleaner baseline for future breaking-change discussions
 
-## Editor Support
+## Scope note
 
-- Refined `editors/vscode/syntaxes/orgscript.tmLanguage.json` to handle keywords like `then` and `else if` without requiring line-start positioning.
-- Improved coloring for dotted references and operators.
-- Cleaned up scope naming for better compatibility with modern VS Code themes.
+v0.5.0 intentionally focuses on usability and adoption.
+
+It does **not** introduce:
+- new language keywords
+- new block types
+- parser redesigns
+- IntelliSense / hovers / semantic tokens
+- speculative future syntax
 
 ## Verification
 
-Verified with:
+Verified on the current release state with:
 
 - `npm test`
 - `npm run check:all`
 - `node ./bin/orgscript.js check ./examples/craft-business-lead-to-order.orgs`
 - `node ./bin/orgscript.js export mermaid ./examples/order-approval.orgs`
 - `node ./bin/orgscript.js export markdown ./examples/order-approval.orgs`
 
-## Project Status
+## Project direction
+
+OrgScript is becoming easier to try, easier to demo, and easier to trust.
 
-v0.5.0 ensures that OrgScript is not just a stable specification, but a toolset that invites exploration. By focusing on polish and adoption readiness, we have made the project's value proposition visible at first glance.
+The next release cycle will focus on integrations, generated artifacts, and stronger showcase value.