docs: improve onboarding flow and governance guidance

Author: DKFuH

README.md

@@ -2,80 +2,137 @@
 
 **Describe how your business works in a way humans and machines both understand.**
 
-OrgScript is a human-readable, AI-friendly description language for business logic, operational processes, rules, roles, and state transitions. It provides a shared, structured layer between plain-language documentation and technical execution.
+OrgScript is a human-readable, AI-friendly description language for business logic, operational processes, rules, roles, and state transitions. It sits between plain-language documentation and technical execution.
 
----
+## What It Is
 
-## Why OrgScript?
+- A shared text layer for business logic
+- Readable by people
+- Parseable by software
+- Stable in Git
+- Useful for AI analysis, validation, and export
 
-- **Shared Truth**: Teams get logic they can read and review directly in Git.
-- **AI-Ready**: Reliable context for LLMs and agents without guessing from unstructured prose.
-- **Artifact-First**: Generate diagrams, summaries, and HTML docs from a single source.
-- **CI/CD Ready**: Validate, lint, and check logic integrity in your pipeline.
+## What It Is Not
 
-## Quick Start
+- Not a general-purpose programming language
+- Not a workflow engine
+- Not free-form prose
+- Not a replacement for implementation code
 
-### Installation
+## Quickstart In 60 Seconds
 
 ```bash
-# Global installation
-npm install -g .
+# 1. Check an example end to end
+orgscript check ./examples/craft-business-lead-to-order.orgs
 
-# Or run via npx
-npx orgscript --help
+# 2. Generate a diagram
+orgscript export mermaid ./examples/craft-business-lead-to-order.orgs
+
+# 3. Generate a stakeholder-friendly summary
+orgscript export markdown ./examples/craft-business-lead-to-order.orgs
 ```
 
-### Usage
+If you want the fastest first read, start with:
 
-```bash
-# 1. Comprehensive health check (validate + lint + format-check)
-orgscript check ./examples/hiring-process.orgs
+- [craft-business-lead-to-order.orgs](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\examples\craft-business-lead-to-order.orgs)
+- [examples/README.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\examples\README.md)
 
-# 2. Structural Metrics & Analysis (WP1)
-orgscript analyze ./examples/hiring-process.orgs
+## Read This In Order
 
-# 3. Export AI Context (WP2)
-orgscript export context ./examples/hiring-process.orgs > logic-context.json
+If you are new to OrgScript, this is the intended reading path:
 
-# 4. Generate Visual Support
-orgscript export mermaid ./examples/craft-business-lead-to-order.orgs
-orgscript export html ./examples/order-approval.orgs
-```
+1. [docs/manifesto.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\docs\manifesto.md)  
+   Why OrgScript exists.
+2. [docs/language-principles.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\docs\language-principles.md)  
+   The design constraints and non-negotiable rules.
+3. [spec/language-spec.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\spec\language-spec.md)  
+   The canonical language definition.
+4. [docs/orgscript-for-humans.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\docs\orgscript-for-humans.md)  
+   How to write maintainable OrgScript files.
+5. [docs/orgscript-for-ai.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\docs\orgscript-for-ai.md)  
+   How tools and AI must interpret OrgScript without guessing.
+
+## Canonical Source Of Truth
+
+The normative language reference is:
+
+- [spec/language-spec.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\spec\language-spec.md)
+
+Supporting docs are there to help people adopt, use, and govern the language. If implementation and docs ever disagree, the canonical spec wins.
+
+## From Source To Artifact
+
+OrgScript is intentionally artifact-first. A single `.orgs` file can produce multiple useful outputs:
 
-## The Artifact Flow
+1. Source logic in plain text
+2. Validation and linting results
+3. Mermaid diagrams
+4. Markdown summaries
+5. HTML documentation
+6. AI-ready structured exports
 
-OrgScript transforms simple text into powerful operational assets:
+Generated examples live under:
 
-1.  **Source (`.orgs`)**: A diff-friendly, indentation-based logic source.
-2.  **Analysis**: Numerical metrics and complexity hints for your processes.
-3.  **Diagram (Mermaid)**: Automatic workflow and state-diagram generation.
-4.  **Summary (Markdown)**: Concise, stakeholder-ready documentation.
-5.  **Docs (HTML)**: Professional-grade static documentation site.
-6.  **AI Context**: Bundled logic package optimized for agent ingest.
+- [docs/demos](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\docs\demos)
+
+## Hero Demo
+
+The main showcase flow is:
+
+- Source: [craft-business-lead-to-order.orgs](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\examples\craft-business-lead-to-order.orgs)
+- Mermaid demo: [docs/demos/mermaid/craft-business-lead-to-order.mermaid.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\docs\demos\mermaid\craft-business-lead-to-order.mermaid.md)
+- Markdown demo: [docs/demos/markdown/craft-business-lead-to-order.summary.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\docs\demos\markdown\craft-business-lead-to-order.summary.md)
 
 ## Core Blocks
 
-- `process`: Step-by-step operational workflows.
-- `stateflow`: State transitions and lifecycle management.
-- `rule`: Cross-cutting guardrails and validation.
-- `role`: Permission boundaries (`can`, `cannot`).
-- `policy`: Governance and SLA requirements.
-- `metric`: Performance and data tracking definitions.
+- `process`: step-by-step operational workflows
+- `stateflow`: legal states and transitions
+- `rule`: cross-cutting constraints and requirements
+- `role`: permission boundaries
+- `policy`: context-driven or time-driven behavior
+- `event`: named triggers with reactions
+- `metric`: tracked business measures
+
+## CLI Quick Reference
+
+```bash
+orgscript validate <file> [--json]
+orgscript lint <file> [--json]
+orgscript check <file> [--json]
+orgscript format <file> [--check]
+orgscript export json <file>
+orgscript export markdown <file>
+orgscript export mermaid <file>
+orgscript export html <file>
+orgscript export context <file>
+orgscript analyze <file> [--json]
+```
+
+## Developer Path
 
-## Integration & Ecosystem
+For most contributors, the best practical sequence is:
 
-- **VS Code Extension**: Official highlighting and language support under `editors/vscode`.
-- **Quality Automation**: CI checks for tests and example validation live in `.github/workflows`.
-- **Showcase**: Generated demo artifacts live in `docs/demos` and can be rebuilt locally with `npm run demo:generate`.
+1. Read [examples/README.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\examples\README.md)
+2. Run `orgscript check` on a real example
+3. Inspect generated Mermaid or Markdown output
+4. Read the canonical spec
+5. Use [docs/governance.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\docs\governance.md) before proposing core language changes
 
 ## Testing
 
 ```bash
-npm test                # Run core logic tests
-npm run check:all        # Verify all examples
-npm run demo:generate    # Regenerate all showcase artifacts
+npm test
+npm run check:all
+npm run demo:generate
 ```
 
+## Ecosystem
+
+- VS Code extension: [editors/vscode](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\editors\vscode)
+- Governance: [docs/governance.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\docs\governance.md)
+- Language evolution: [docs/language-evolution.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\docs\language-evolution.md)
+- Changelog: [CHANGELOG.md](c:\Users\DanielKlas\OneDrive - Tischlermeister Daniel Klas\All Company - Dokumente\2_AREAS\AREA_IT_Infrastruktur\Entwicklung\OrgScript\CHANGELOG.md)
+
 ## License
 
 Apache-2.0

docs/governance.md

@@ -10,13 +10,34 @@ This note defines how the language evolves without losing its canonical shape.
 - Treat keyword meaning as stable once documented.
 - Keep the language readable for humans and deterministic for machines.
 
+## Stability levels
+
+- `canonical`: part of the normative language surface and safe to build against
+- `draft`: documented but not yet treated as a long-term compatibility promise
+- `experimental`: implementation or tooling exploration, not part of the canonical language contract
+
+Unless explicitly marked otherwise, the language surface described in `spec/language-spec.md` is treated as `canonical`.
+
 ## Change policy
 
 - Any change to keywords, grammar, canonical modeling, or diagnostics is a spec change.
 - New features should start as a documented proposal before implementation.
 - Experimental ideas should stay out of the canonical spec until they are stable enough to support long-term tooling.
 - If a change can be expressed with existing language forms, prefer that over adding a new construct.
 
+## Change matrix
+
+| Change type | Needs RFC | Needs spec update | Version impact |
+| --- | --- | --- | --- |
+| README, examples, tutorials | No | No | None |
+| Exporter behavior | Usually no | Only if contract changes | Patch or minor |
+| CLI output wording | No | Yes if diagnostics contract changes | Patch or minor |
+| Diagnostics structure or codes | Yes | Yes | Minor |
+| New lint rule | No, unless semantic | Only if normative | Patch or minor |
+| New keyword or grammar rule | Yes | Yes | Minor while `0.x`, major after `1.0` |
+| Semantic reinterpretation of an existing keyword | Yes | Yes | Breaking |
+| Canonical model breaking change | Yes | Yes | Breaking |
+
 ## Core vs tooling vs exporters
 
 - Core language changes affect keywords, grammar, semantics, formatting rules, or the canonical model.
@@ -31,6 +52,40 @@ This note defines how the language evolves without losing its canonical shape.
 - Check parser and formatter impact before approving syntax changes.
 - Check canonical model and diagnostic impact before approving semantic changes.
 
+## RFC template
+
+Use a lightweight RFC note when proposing a core change:
+
+```md
+# RFC: <short title>
+
+## Motivation
+
+Why is the change needed?
+
+## Proposed change
+
+Describe the exact language or semantic change.
+
+## Backward impact
+
+Is this backward compatible? If not, what breaks?
+
+## Alternatives considered
+
+What else was considered and why was it rejected?
+
+## Spec impact
+
+Which files need updates?
+
+## Decision log
+
+- proposed:
+- accepted/rejected:
+- release target:
+```
+
 ## Versioning guidance
 
 - Make breaking changes only with an explicit version plan.

docs/language-evolution.md

@@ -12,6 +12,18 @@ A core language change expands the canonical syntax (`spec/grammar.ebnf`) and re
 
 We treat core changes as **highly disruptive**. They break existing tooling, models, and potentially user workflows.
 
+## Practical rule of thumb
+
+If a user need can be solved by:
+
+- a new exporter
+- a stronger linter
+- better diagnostics
+- better editor support
+- clearer examples or documentation
+
+then it usually does **not** belong in the language core.
+
 ## What belongs in tooling instead?
 
 Most new features do *not* belong in the language core. They belong in:
@@ -28,6 +40,15 @@ OrgScript follows a strict protocol for backwards-incompatible breaks:
 - If a construct must change its semantic meaning, the version `package.json` and the corresponding `spec/language-spec.md` will bump the major version (or minor version while under `0.x`).
 - Breaking changes require a migration path to be published alongside the release.
 
+## Expected process for core changes
+
+1. Write a short RFC using the template in `docs/governance.md`.
+2. Compare the proposal against `spec/language-spec.md`.
+3. Decide whether the change belongs in core, tooling, or an exporter.
+4. Update the canonical spec before or alongside implementation.
+5. Add examples and regression coverage.
+6. Record the impact in release notes and changelog.
+
 ## Spec and Implementation Alignment
 
 The `spec/language-spec.md` is the absolute source of truth.

docs/manifesto.md

@@ -47,3 +47,20 @@ If organizations can describe their logic clearly:
 - onboarding becomes easier
 - hidden rules become visible
 - AI can support analysis and transformation without guessing
+
+## First 10 minutes with OrgScript
+
+Start with one real example and one real command path:
+
+1. Open `examples/craft-business-lead-to-order.orgs`
+2. Run `orgscript check ./examples/craft-business-lead-to-order.orgs`
+3. Run `orgscript export mermaid ./examples/craft-business-lead-to-order.orgs`
+4. Run `orgscript export markdown ./examples/craft-business-lead-to-order.orgs`
+
+That gives you the shortest path from idea to validation to visible output.
+
+Then continue with:
+
+- `examples/README.md` for the example catalog
+- `spec/language-spec.md` for the canonical definition
+- `docs/orgscript-for-humans.md` for authoring guidance