feat(export): add markdown summary exporter and demo outputs

Author: DKFuH

CHANGELOG.md

@@ -11,6 +11,8 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 - Added `orgscript check <file>` as the combined quality command for validation, linting, and formatting checks.
 - Added `orgscript check <file> --json` for machine-readable combined quality diagnostics.
 - Added `npm run check:all` and switched CI to the combined quality path.
+- Added `orgscript export markdown <file>` for concise Markdown summaries of OrgScript files.
+- Added Markdown summary golden snapshots and demo outputs.
 - Added `orgscript export mermaid <file>` for first-pass Mermaid exports of processes and stateflows.
 - Added `npm run demo:generate` plus a Mermaid demo package with generated Markdown and `.mmd` artifacts.
 - Added a canonical master language spec and lightweight governance guidance.

README.md

@@ -71,16 +71,21 @@ process CraftBusinessLeadToOrder
 
 See the full example in [`examples/craft-business-lead-to-order.orgs`](examples/craft-business-lead-to-order.orgs).
 
-## From Source To Diagram
+## From Source To Output
 
 OrgScript already generates visible downstream artifacts.
 
-Minimal Mermaid demos live in [`docs/demos/mermaid/README.md`](docs/demos/mermaid/README.md):
+Mermaid demos live in [`docs/demos/mermaid/README.md`](docs/demos/mermaid/README.md):
 
 - process demo from [`examples/lead-qualification.orgs`](examples/lead-qualification.orgs) to [`docs/demos/mermaid/lead-qualification.mermaid.md`](docs/demos/mermaid/lead-qualification.mermaid.md)
 - stateflow demo from [`examples/order-approval.orgs`](examples/order-approval.orgs) to [`docs/demos/mermaid/order-approval.mermaid.md`](docs/demos/mermaid/order-approval.mermaid.md)
 
-Generate the demo artifacts with:
+Markdown summary demos live in [`docs/demos/markdown/README.md`](docs/demos/markdown/README.md):
+
+- process summary from [`examples/lead-qualification.orgs`](examples/lead-qualification.orgs) to [`docs/demos/markdown/lead-qualification.summary.md`](docs/demos/markdown/lead-qualification.summary.md)
+- mixed summary from [`examples/order-approval.orgs`](examples/order-approval.orgs) to [`docs/demos/markdown/order-approval.summary.md`](docs/demos/markdown/order-approval.summary.md)
+
+Generate both demo sets with:
 
 ```text
 npm run demo:generate
@@ -141,6 +146,7 @@ npm run demo:generate
 - [`docs/repository-structure.md`](docs/repository-structure.md)
 - [`docs/syntax.md`](docs/syntax.md)
 - [`docs/semantics.md`](docs/semantics.md)
+- [`docs/demos/markdown/README.md`](docs/demos/markdown/README.md)
 - [`docs/demos/mermaid/README.md`](docs/demos/mermaid/README.md)
 - [`examples/README.md`](examples/README.md)
 - [`spec/grammar.ebnf`](spec/grammar.ebnf)
@@ -169,12 +175,14 @@ npm run demo:generate
 - Combined quality checks: `orgscript check <file>`
 - Machine-readable combined checks: `orgscript check <file> --json`
 - Canonical JSON export: `orgscript export json <file>`
+- Markdown summary export: `orgscript export markdown <file>`
 - Mermaid export for `process` and `stateflow`: `orgscript export mermaid <file>`
 - Machine-readable diagnostics: `orgscript validate <file> --json`, `orgscript lint <file> --json`, `orgscript check <file> --json`
 - Golden snapshot tests for AST, canonical model, and formatter output
 - Stable lint severities: `error`, `warning`, `info`
 - Canonical master spec: [`spec/language-spec.md`](spec/language-spec.md)
 - Initial VS Code syntax-highlighting scaffold: [`editors/vscode`](editors/vscode)
+- Generated demo artifacts for Mermaid and Markdown summaries under [`docs/demos`](docs/demos)
 
 ## Quick start
 
@@ -189,6 +197,7 @@ node ./bin/orgscript.js format ./examples/craft-business-lead-to-order.orgs --ch
 node ./bin/orgscript.js lint ./tests/lint/process-missing-trigger.orgs
 node ./bin/orgscript.js lint ./tests/lint/process-missing-trigger.orgs --json
 node ./bin/orgscript.js export json ./examples/craft-business-lead-to-order.orgs
+node ./bin/orgscript.js export markdown ./examples/craft-business-lead-to-order.orgs
 node ./bin/orgscript.js export mermaid ./examples/craft-business-lead-to-order.orgs
 ```
 
@@ -312,6 +321,13 @@ OrgScript exposes stable JSON diagnostics for CI, editors, AI systems, and downs
 - Example catalog: [`examples/README.md`](examples/README.md)
 - VS Code editor scaffold: [`editors/vscode/README.md`](editors/vscode/README.md)
 
+## Visible outputs
+
+OrgScript currently produces two human-facing output types from the same source file:
+
+- Mermaid diagrams via `orgscript export mermaid <file>`
+- Markdown summaries via `orgscript export markdown <file>`
+
 ## Editor support
 
 OrgScript now ships with a first VS Code syntax-highlighting scaffold under [`editors/vscode`](editors/vscode).
@@ -346,6 +362,7 @@ orgscript format file.orgs --check
 orgscript lint file.orgs
 orgscript lint file.orgs --json
 orgscript export json file.orgs
+orgscript export markdown file.orgs
 orgscript export mermaid file.orgs
 orgscript check file.orgs
 orgscript check file.orgs --json
@@ -361,6 +378,7 @@ See [`docs/cli-v0.1-plan.md`](docs/cli-v0.1-plan.md) for the implementation plan
 
 ```text
 npm test
+npm run export:markdown
 npm run export:mermaid
 npm run demo:generate
 npm run check

docs/cli-v0.1-plan.md

@@ -15,6 +15,7 @@ Implemented:
 - `format --check`
 - `lint`
 - `export json`
+- `export markdown`
 - `export mermaid`
 - `validate --json`
 - `lint --json`
@@ -47,6 +48,27 @@ Output:
 
 Exports the parsed document into the canonical JSON model.
 
+### `orgscript export markdown <file>`
+
+Exports the parsed document into a concise Markdown summary.
+
+Current scope:
+
+- `process`
+- `stateflow`
+- `rule`
+- `role`
+- `policy`
+- `event`
+- `metric`
+
+Output style:
+
+- human-readable
+- deterministic
+- structured for code review and docs
+- intentionally concise rather than prose-heavy
+
 ### `orgscript export mermaid <file>`
 
 Exports supported blocks as a Markdown document with Mermaid code blocks.
@@ -170,5 +192,6 @@ TypeScript is the fastest start:
 - Lint exit codes are safe for CI use with advisory warnings.
 - Invalid files produce useful errors with line references.
 - Valid files can be exported to canonical JSON.
+- Valid files can be exported to concise Markdown summaries.
 - Formatter output is deterministic.
 - Linter catches at least a handful of high-value modeling mistakes.

docs/demos/markdown/README.md

@@ -0,0 +1,29 @@
+# Markdown summary demos
+
+This folder shows the shortest path from OrgScript source to human-readable Markdown summaries.
+
+Each demo keeps the source file in `examples/` and generates one downstream artifact here:
+
+- `*.summary.md`: a concise Markdown summary of the modeled logic
+
+## Generate
+
+```text
+npm run demo:generate
+```
+
+## Demos
+
+| Demo | Source | Markdown summary |
+| --- | --- | --- |
+| Lead qualification process | [lead-qualification.orgs](../../../examples/lead-qualification.orgs) | [lead-qualification.summary.md](./lead-qualification.summary.md) |
+|  |  | A compact process example that shows trigger, branching, assignment, notification, and state transition. |
+| Order approval stateflow | [order-approval.orgs](../../../examples/order-approval.orgs) | [order-approval.summary.md](./order-approval.summary.md) |
+|  |  | A stateflow-focused example that also demonstrates how Mermaid export skips unsupported blocks while still producing useful output. |
+
+## Notes
+
+- These artifacts are generated from the current Markdown summary exporter.
+- The summaries are intentionally concise and deterministic rather than prose-heavy.
+- If you change Markdown export behavior, regenerate this folder with `npm run demo:generate` and review the diffs.
+

docs/demos/markdown/lead-qualification.summary.md

@@ -0,0 +1,10 @@
+# Process: LeadQualification
+
+## Trigger
+- `lead.created`
+
+## Summary
+- If `lead.source = "referral"`, assign `lead.priority` to `"high"`, assign `lead.path` to `"premium"`, and notify `sales` with `"New referral lead"`.
+- Else if `lead.source = "ads"`, assign `lead.priority` to `"normal"` and assign `lead.path` to `"standard"`.
+- If `lead.budget < 10000`, transition `lead.status` to `"disqualified"`, notify `sales` with `"Budget below threshold"`, and stop the branch.
+- Then transition `lead.status` to `"qualified"`.

docs/demos/markdown/order-approval.summary.md

@@ -0,0 +1,25 @@
+# Stateflow: OrderStatus
+
+## States
+- draft
+- pending_approval
+- approved
+- production
+- completed
+- cancelled
+
+## Allowed transitions
+- `draft -> pending_approval`
+- `pending_approval -> approved`
+- `approved -> production`
+- `production -> completed`
+- `draft -> cancelled`
+- `pending_approval -> cancelled`
+
+# Rule: NoProductionWithoutApproval
+
+## Scope
+- `order`
+
+## Summary
+- If `order.approved = false`, require `management_approval` and notify `operations` with `"Order cannot enter production"`.

docs/repository-structure.md

@@ -17,6 +17,10 @@ docs/
   governance.md
   cli-v0.1-plan.md
   demos/
+    markdown/
+      README.md
+      lead-qualification.summary.md
+      order-approval.summary.md
     mermaid/
       README.md
       lead-qualification.mermaid.md

docs/roadmaps/v0.4.0.md

@@ -21,6 +21,7 @@ Make OrgScript easier to use in daily development, CI, and editor workflows with
 - JSON diagnostics examples in the README and diagnostics spec
 - canonical language spec and governance notes
 - initial VS Code syntax-highlighting scaffold
+- Markdown summary exporter
 - Mermaid demo package with generated Markdown and `.mmd` artifacts
 
 ## Non-goals

examples/README.md

@@ -30,7 +30,10 @@ This folder shows OrgScript at three adoption levels.
 ```text
 node ./bin/orgscript.js validate ./examples/lead-qualification.orgs
 node ./bin/orgscript.js check ./examples/craft-business-lead-to-order.orgs
+node ./bin/orgscript.js export markdown ./examples/order-approval.orgs
 node ./bin/orgscript.js export mermaid ./examples/order-approval.orgs
 ```
 
 For generated Mermaid demo artifacts, see [`../docs/demos/mermaid/README.md`](../docs/demos/mermaid/README.md).
+
+For generated Markdown summary demo artifacts, see [`../docs/demos/markdown/README.md`](../docs/demos/markdown/README.md).

package.json

@@ -17,6 +17,7 @@
     "validate:all": "node ./scripts/validate-all.js",
     "lint:all": "node ./scripts/lint-all.js",
     "export:json": "node ./bin/orgscript.js export json ./examples/craft-business-lead-to-order.orgs",
+    "export:markdown": "node ./bin/orgscript.js export markdown ./examples/craft-business-lead-to-order.orgs",
     "export:mermaid": "node ./bin/orgscript.js export mermaid ./examples/craft-business-lead-to-order.orgs",
     "demo:generate": "node ./scripts/generate-demo.js",
     "golden:generate": "node ./scripts/generate-golden.js",