Skip to content

Commit 75add07

Browse files
DKFuHDKFuH
committed
docs(handbook): add DE/EN manuals and include missing mermaid demo artifacts in the showcase site
1 parent 16aca09 commit 75add07

14 files changed

+986
-0
lines changed

‎docs/OrgScript-Handbuch-DE.docx‎

31.9 KB
Binary file not shown.

‎docs/OrgScript-Handbuch-DE.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# OrgScript Handbuch (Deutsch)
2+
3+
## Einführung
4+
OrgScript ist eine menschenlesbare, KI-freundliche Beschreibungssprache für operative Logik, Prozesse und Regeln. Es ist keine Programmiersprache im klassischen Sinne, sondern eine strukturierte Ebene zwischen natürlicher Sprache und technischer Ausführung.
5+
6+
## Kernkonzepte
7+
8+
### Prozesse (`process`)
9+
Ein Prozess beschreibt den operativen Ablauf einer Aufgabe. Er beginnt oft mit einem Auslöser (`when`) und enthält bedingte Anweisungen (`if`, `then`, `else`).
10+
- **Anweisungen**: `assign` (Zuweisung), `transition` (Zustandswechsel), `notify` (Benachrichtigung).
11+
12+
### Zustandsflüsse (`stateflow`)
13+
Zustandsflüsse definieren den Lebenszyklus eines Objekts (z. B. ein Auftrag oder ein Lead).
14+
- **states**: Die möglichen Zustände.
15+
- **transitions**: Die erlaubten Pfade zwischen den Zuständen.
16+
17+
### Regeln (`rule`)
18+
Regeln definieren dauerhafte Bedingungen oder Validierungen, die für ein Objekt gelten ("Guardrails").
19+
20+
### Rollen (`role`)
21+
Rollen definieren Berechtigungsgrenzen (`can`, `cannot`).
22+
23+
## Nutzung des CLI (Kommandozeile)
24+
25+
OrgScript bietet ein mächtiges CLI-Werkzeug (`orgscript`):
26+
27+
1. **Check**: `orgscript check <datei>` — Validiert Syntax, lintert die Logik und prüft die Formatierung.
28+
2. **Analyse**: `orgscript analyze <datei>` — Liefert strukturelle Metriken und Komplexitätshinweise.
29+
3. **Export**:
30+
- `export mermaid`: Generiert Diagramme.
31+
- `export html`: Erzeugt eine vollwertige Dokumentationsseite.
32+
- `export context`: Bereitet die Logik für KI-Systeme auf.
33+
34+
## Best Practices
35+
- **Inkrementell arbeiten**: Fange mit einfachen Zuständen an und füge Prozesse hinzu.
36+
- **KI nutzen**: Nutze `export context`, um KI-Agenten zuverlässig über deine internen Abläufe zu informieren.
37+
- **Git verwenden**: Versioniere deine Logik wie Code.
38+
39+
---
40+
*Version 0.8.0 / OrgScript Foundation*

‎docs/OrgScript-Manual-EN.docx‎

30.8 KB
Binary file not shown.

‎docs/OrgScript-Manual-EN.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# OrgScript Manual (English)
2+
3+
## Introduction
4+
OrgScript is a human-readable, AI-friendly description language for operational logic, processes, and rules. It provides a shared, structured layer between plain-language documentation and technical execution.
5+
6+
## Core Concepts
7+
8+
### Process (`process`)
9+
A process describes the operational flow of a task. It starts with a trigger (`when`) and contains conditional statements (`if`, `then`, `else`).
10+
- **Statements**: `assign` (set a value), `transition` (change status), `notify` (alert a role).
11+
12+
### Stateflow (`stateflow`)
13+
Stateflows define the lifecycle of an object (e.g., an Order or a lead).
14+
- **states**: The allowed states.
15+
- **transitions**: The defined paths between states.
16+
17+
### Rule (`rule`)
18+
Rules define permanent conditions or validations ("Guardrails") that apply to an object.
19+
20+
### Role (`role`)
21+
Roles define permission boundaries (`can`, `cannot`).
22+
23+
## CLI Usage (Command Line Interface)
24+
25+
OrgScript provides a powerful CLI tool (`orgscript`):
26+
27+
1. **Check**: `orgscript check <file>` — Validates syntax, lints the logic, and checks for canonical formatting.
28+
2. **Analyze**: `orgscript analyze <file>` — Provides structural metrics and complexity hints.
29+
3. **Export**:
30+
- `export mermaid`: Generates Mermaid diagrams.
31+
- `export html`: Creates a standalone documentation page.
32+
- `export context`: Prepares logic context for AI ingest.
33+
34+
## Best Practices
35+
- **Iterative Modeling**: Start with simple states and add processes over time.
36+
- **AI Context**: Use `export context` to reliably feed your internal operational rules into AI agents.
37+
- **Version Control**: Store your business logic in Git to track changes and collaborate through pull requests.
38+
39+
---
40+
*Version 0.8.0 / OrgScript Foundation*

‎docs/demos/html/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@ npm run demo:generate
1818
| --- | --- | --- |
1919
| Craft Business: Lead to Order | [craft-business-lead-to-order.orgs](../../../examples/craft-business-lead-to-order.orgs) | [craft-business-lead-to-order.html](./craft-business-lead-to-order.html) |
2020
| | | Our hero example showcasing multi-block processes, rules, and stateflows in a realistic business scenario. |
21+
| Hiring: Standard Candidate Process | [hiring-process.orgs](../../../examples/hiring-process.orgs) | [hiring-process.html](./hiring-process.html) |
22+
| | | A multi-role hiring process including GDPR policies, manager permissions, and conditional rejection branches. |
23+
| Incident Escalation SLA | [incident-escalation.orgs](../../../examples/incident-escalation.orgs) | [incident-escalation.html](./incident-escalation.html) |
24+
| | | Operational incident handling with time-based escalation policies and on-call role definitions. |
2125
| Lead qualification process | [lead-qualification.orgs](../../../examples/lead-qualification.orgs) | [lead-qualification.html](./lead-qualification.html) |
2226
| | | A compact process example that shows trigger, branching, assignment, notification, and state transition. |
2327
| Order approval stateflow | [order-approval.orgs](../../../examples/order-approval.orgs) | [order-approval.html](./order-approval.html) |

‎docs/demos/html/hiring-process.html‎

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>OrgScript Demo: Hiring: Standard Candidate Process</title>
7+
<style>
8+
:root {
9+
--primary: #2563eb;
10+
--bg: #f8fafc;
11+
--text: #1e293b;
12+
--border: #e2e8f0;
13+
--card-bg: #ffffff;
14+
}
15+
body {
16+
font-family: 'Inter', system-ui, -apple-system, sans-serif;
17+
line-height: 1.6;
18+
color: var(--text);
19+
background: var(--bg);
20+
margin: 0;
21+
padding: 2rem;
22+
max-width: 1000px;
23+
margin: 0 auto;
24+
}
25+
header {
26+
margin-bottom: 3rem;
27+
border-bottom: 2px solid var(--border);
28+
padding-bottom: 1rem;
29+
}
30+
nav {
31+
background: var(--card-bg);
32+
padding: 1.5rem;
33+
border-radius: 8px;
34+
box-shadow: 0 1px 3px rgba(0,0,0,0.1);
35+
margin-bottom: 3rem;
36+
}
37+
nav ul {
38+
list-style: none;
39+
padding: 0;
40+
columns: 2;
41+
}
42+
nav a {
43+
color: var(--primary);
44+
text-decoration: none;
45+
}
46+
nav a:hover {
47+
text-decoration: underline;
48+
}
49+
section {
50+
background: var(--card-bg);
51+
padding: 2rem;
52+
border-radius: 8px;
53+
box-shadow: 0 1px 3px rgba(0,0,0,0.1);
54+
margin-bottom: 2rem;
55+
scroll-margin-top: 2rem;
56+
}
57+
h1, h2, h3 {
58+
color: #0f172a;
59+
}
60+
.kind {
61+
display: inline-block;
62+
text-transform: uppercase;
63+
font-size: 0.75rem;
64+
font-weight: 700;
65+
letter-spacing: 0.05em;
66+
color: #64748b;
67+
margin-bottom: 0.5rem;
68+
}
69+
.mermaid {
70+
background: #fff;
71+
padding: 1rem;
72+
border: 1px solid var(--border);
73+
border-radius: 4px;
74+
margin: 1.5rem 0;
75+
overflow-x: auto;
76+
}
77+
footer {
78+
margin-top: 4rem;
79+
text-align: center;
80+
color: #94a3b8;
81+
font-size: 0.875rem;
82+
}
83+
pre {
84+
background: #f1f5f9;
85+
padding: 1rem;
86+
border-radius: 4px;
87+
font-size: 0.875rem;
88+
}
89+
code {
90+
font-family: 'Fira Code', 'Cascadia Code', monospace;
91+
background: #f1f5f9;
92+
padding: 0.2em 0.4em;
93+
border-radius: 4px;
94+
}
95+
ul {
96+
padding-left: 1.5rem;
97+
}
98+
.status-bar {
99+
display: flex;
100+
gap: 1rem;
101+
margin-top: 1rem;
102+
font-size: 0.875rem;
103+
}
104+
.tag {
105+
background: #e2e8f0;
106+
padding: 0.2rem 0.6rem;
107+
border-radius: 999px;
108+
}
109+
</style>
110+
</head>
111+
<body>
112+
<header>
113+
<h1>OrgScript Demo: Hiring: Standard Candidate Process</h1>
114+
<p>Generated by OrgScript v0.6.0</p>
115+
</header>
116+
117+
<nav>
118+
<h2>Table of Contents</h2>
119+
<ul>
120+
<li><a href="#stateflow-applicationlifecycle">stateflow: ApplicationLifecycle</a></li>
121+
<li><a href="#role-hiringmanager">role: HiringManager</a></li>
122+
<li><a href="#role-humanresources">role: HumanResources</a></li>
123+
<li><a href="#role-candidate">role: Candidate</a></li>
124+
<li><a href="#policy-gdprcompliance">policy: GDPRCompliance</a></li>
125+
<li><a href="#rule-screeningmandatory">rule: ScreeningMandatory</a></li>
126+
<li><a href="#process-standardhiring">process: StandardHiring</a></li>
127+
</ul>
128+
</nav>
129+
130+
<main>
131+
132+
<section id="stateflow-applicationlifecycle">
133+
<span class="kind">stateflow</span>
134+
<h2>ApplicationLifecycle</h2>
135+
<div class="summary-container">
136+
137+
<p><strong>States:</strong> <code>received</code>, <code>screening</code>, <code>interview-round-1</code>, <code>interview-round-2</code>, <code>offer_sent</code>, <code>background_check</code>, <code>hired</code>, <code>rejected</code></p>
138+
<p><strong>Transitions:</strong> 11 paths defined.</p>
139+
140+
</div>
141+
<div class="visual-container"><h3>Diagram</h3><pre class="mermaid">stateDiagram-v2
142+
state "received" as s1_state_1
143+
[*] --> s1_state_1
144+
state "screening" as s1_state_2
145+
state "interview-round-1" as s1_state_3
146+
state "interview-round-2" as s1_state_4
147+
state "offer_sent" as s1_state_5
148+
state "background_check" as s1_state_6
149+
state "hired" as s1_state_7
150+
state "rejected" as s1_state_8
151+
s1_state_1 --> s1_state_2
152+
s1_state_2 --> s1_state_3
153+
s1_state_2 --> s1_state_8
154+
s1_state_3 --> s1_state_4
155+
s1_state_3 --> s1_state_8
156+
s1_state_4 --> s1_state_5
157+
s1_state_4 --> s1_state_8
158+
s1_state_5 --> s1_state_6
159+
s1_state_5 --> s1_state_8
160+
s1_state_6 --> s1_state_7
161+
s1_state_6 --> s1_state_8
162+
s1_state_7 --> [*]
163+
s1_state_8 --> [*]</pre></div>
164+
</section>
165+
166+
167+
<section id="role-hiringmanager">
168+
<span class="kind">role</span>
169+
<h2>HiringManager</h2>
170+
<div class="summary-container">
171+
172+
<p><strong>Permissions:</strong></p>
173+
<ul><li>Can perform <code>shortlist candidate</code></li><li>Can perform <code>interview candidate</code></li><li>Can perform <code>approve offer</code></li></ul>
174+
175+
176+
</div>
177+
178+
</section>
179+
180+
181+
<section id="role-humanresources">
182+
<span class="kind">role</span>
183+
<h2>HumanResources</h2>
184+
<div class="summary-container">
185+
186+
<p><strong>Permissions:</strong></p>
187+
<ul><li>Can perform <code>create job posting</code></li><li>Can perform <code>schedule interview</code></li><li>Can perform <code>send offer</code></li><li>Can perform <code>verify background</code></li></ul>
188+
189+
190+
</div>
191+
192+
</section>
193+
194+
195+
<section id="role-candidate">
196+
<span class="kind">role</span>
197+
<h2>Candidate</h2>
198+
<div class="summary-container">
199+
200+
<p><strong>Permissions:</strong></p>
201+
<ul><li>Can perform <code>submit application</code></li><li>Can perform <code>accept offer</code></li></ul>
202+
203+
204+
</div>
205+
206+
</section>
207+
208+
209+
<section id="policy-gdprcompliance">
210+
<span class="kind">policy</span>
211+
<h2>GDPRCompliance</h2>
212+
<div class="summary-container">
213+
<p>Operational constraints and logic for <code>GDPRCompliance</code>.</p>
214+
</div>
215+
216+
</section>
217+
218+
219+
<section id="rule-screeningmandatory">
220+
<span class="kind">rule</span>
221+
<h2>ScreeningMandatory</h2>
222+
<div class="summary-container">
223+
224+
<p><strong>Scope:</strong> Applies to <code>application</code></p>
225+
<p>Contains behavioral constraints and logic for <code>ScreeningMandatory</code>.</p>
226+
227+
</div>
228+
229+
</section>
230+
231+
232+
<section id="process-standardhiring">
233+
<span class="kind">process</span>
234+
<h2>StandardHiring</h2>
235+
<div class="summary-container">
236+
237+
<p><strong>Triggered by:</strong> <code>candidate.application_submitted</code></p>
238+
<p>Orchestrates business logic and state transitions for the <code>StandardHiring</code> process.</p>
239+
240+
</div>
241+
<div class="visual-container"><h3>Diagram</h3><pre class="mermaid">flowchart TD
242+
p1_start_1(["StandardHiring"])
243+
class p1_start_1 success
244+
p1_trigger_2[/ "when candidate.application_submitted" /]
245+
class p1_trigger_2 trigger
246+
p1_action_3["transition application.status to 'received'"]
247+
class p1_action_3 action
248+
p1_action_4["notify hr_team with #quot;New candidate application#quot;"]
249+
class p1_action_4 action
250+
p1_decision_5{"if candidate.role_match_score > 70"}
251+
class p1_decision_5 decision
252+
p1_action_6["transition application.status to 'screening'"]
253+
class p1_action_6 action
254+
p1_action_7["assign application.assigned_to = 'hiring_manager'"]
255+
class p1_action_7 action
256+
p1_decision_8{"if application.screening_outcome = 'positive'"}
257+
class p1_decision_8 decision
258+
p1_action_9["transition application.status to 'interview-round-1'"]
259+
class p1_action_9 action
260+
p1_action_10["create interview_invite"]
261+
class p1_action_10 action
262+
p1_end_11(["done"])
263+
class p1_end_11 success
264+
p1_start_1 --> p1_trigger_2
265+
p1_trigger_2 --> p1_action_3
266+
p1_action_3 --> p1_action_4
267+
p1_action_4 --> p1_decision_5
268+
p1_decision_5 -->|yes| p1_action_6
269+
p1_action_6 --> p1_action_7
270+
p1_action_7 --> p1_decision_8
271+
p1_decision_5 -->|no| p1_decision_8
272+
p1_decision_8 -->|yes| p1_action_9
273+
p1_action_9 --> p1_action_10
274+
p1_action_10 --> p1_end_11
275+
p1_decision_8 -->|no| p1_end_11
276+
277+
%% Styling
278+
classDef trigger fill:#f0f4ff,stroke:#5c7cfa,stroke-width:2px
279+
classDef decision fill:#fff9db,stroke:#fab005,stroke-width:2px
280+
classDef action fill:#fff,stroke:#adb5bd,stroke-width:1px
281+
classDef stop fill:#fff5f5,stroke:#ff8787,stroke-width:2px
282+
classDef success fill:#f4fce3,stroke:#94d82d,stroke-width:2px</pre></div>
283+
</section>
284+
285+
</main>
286+
287+
<footer>
288+
<p>OrgScript — Human-readable, AI-interpretable business logic.</p>
289+
</footer>
290+
291+
<script type="module">
292+
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
293+
mermaid.initialize({ startOnLoad: true, theme: 'default' });
294+
</script>
295+
</body>
296+
</html>

0 commit comments

Comments
 (0)