woml-cli 1.0.4 → 1.0.6

package/README.md

@@ -1,81 +1,404 @@
-<div align="center">
-
 # WOML: Workflow Orchestration Markup Language
 
-![WOML banner](./woml.png)
+WOML is a declarative markup language for building and running production-grade workflow automation. A WOML workflow is a structured, HTML-inspired document that compiles into a typed, durable execution graph. Triggers, steps, control flow, lifecycle hooks, concurrency, and human approvals all live in one readable file with a Rust engine underneath.
+
+When a step needs real logic, JavaScript runs inside `<script>`, so there is no ceiling on what a workflow can do. WOML handles everything around that code — execution order, retries, concurrency, lifecycle, human-in-the-loop, external services, and a durable, inspectable history of every run.
+
+---
+
+## Install
+
+```bash
+npm install -g woml-cli
+```
+
+Or with Bun:
+
+```bash
+bun add -g woml-cli
+```
+
+Or with pnpm:
 
-### If you can read HTML, you can use WOML to automate anything, literally anything.
+```bash
+pnpm add -g woml-cli
+```
 
-<!-- WOML banner image placeholder: ./docs/assets/banner.png -->
+Verify:
 
-[![npm version](https://img.shields.io/npm/v/woml-cli.svg)](https://www.npmjs.com/package/woml-cli)
-[![GitHub stars](https://img.shields.io/github/stars/dali-benothmen/woml.svg?style=social)](https://github.com/dali-benothmen/woml)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
-[![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)]()
+```bash
+woml --version
+```
 
-</div>
+**Requirements:** macOS (x64, arm64), Linux (x64, glibc), or Windows (x64, arm64). No database to set up — the default state store is bundled.
 
 ---
 
-WOML is a markup language for building and running workflow automation. A workflow written in WOML is a document you can read top to bottom, its triggers, steps, control flow, approvals, and lifecycle all expressed as clear, HTML-inspired structure instead of tangled code or an unreadable diagram.
+## Document structure
 
-When a step needs real logic, JavaScript is always available inside `<script>`, so there is no ceiling on what a workflow can do. WOML handles everything _around_ that code: execution order, retries, concurrency, human approvals, external services, and a durable, inspectable history of every run. The result is automation that scales without becoming spaghetti, that your whole team can read, and that you can actually trust in production.
+A workflow is one `<woml>` document with a `<workflow>` root plus the standard containers: `<config>` for runtime policies, `<lifecycle>` for hooks, `<triggers>` for what starts a run, and `<steps>` for what runs.
 
-## Why another automation tool?
+```xml
+<woml>
+  <workflow id="..." name="..." version="1.0.0">
+    <config concurrency="4" timeout="10m" />
+    <lifecycle>
+      <on-success><script>...</script></on-success>
+      <on-error><script>...</script></on-error>
+    </lifecycle>
+    <triggers>...</triggers>
+    <steps>...</steps>
+  </workflow>
+</woml>
+```
 
-Five nodes in n8n or Zapier feels like magic. Twenty nodes feels like a crime scene.
+Runtime bindings available inside every `<script>`:
 
-The canvas turns into spaghetti, a single run takes a lifetime, and the moment the built-in integrations fall short you end up stuffing JavaScript into a tiny textbox in a browser UI, no version control, no code review, no idea what changed last Tuesday.
+- `context.payload` — trigger input
+- `context.steps.<id>` — earlier step output
+- `context.run` — durable run metadata
+- `services.http`, `services.database`, `services.slack`, `services.storage`, `services.cache`, `services.event`, `services.messaging` — supervised capabilities (each must be declared by the workflow or its modules)
+- `secrets.<NAME>` — only the secrets proven necessary at compile time
 
-WOML takes a different bet: your workflow is **a file**. It reads like HTML, so anyone on the team can follow it. Every step can run real JavaScript with any npm package, so you never hit a wall. It lives in git, so every change is a diff and a review. And the engine underneath is Rust, so it stays fast when your workflows get big, because big workflows are exactly what WOML is built for.
+Scripts return JSON-compatible values. The Rust engine records every outcome durably.
 
-## Why WOML
+---
 
-- **Readable as a document.** A workflow is structure you can read, diff, and review, not a canvas of boxes and wires that turns into spaghetti as it grows.
-- **No ceiling.** Common actions are clean tags; when you need real logic, drop into `<script>` with full JavaScript and any npm package. Automate anything, literally anything.
-- **Triggers for everything.** Manual, webhook, schedule, interval, event, Slack, Telegram, Discord, and WhatsApp, and you can build your own providers for anything else.
-- **Built to run in production.** Durable run history, retries, concurrency, lifecycle hooks, and a fold-from-events core mean you can always see what happened, track down errors, and replay it.
-- **Human-in-the-loop.** Pause a workflow for approvals with real notifications and durable waiting.
-- **Modular.** Reusable step definitions, local modules, and workflows that call other workflows.
-- **Fast core.** The execution engine is written in Rust for speed and reliability under load.
-- **Free and runs anywhere.** Open source, self-hosted, runs on macOS, Linux, and Windows.
+## Triggers
 
-## Installation
+Triggers decide **when** a workflow runs. Place one or more inside `<triggers>`.
 
-```bash
-npm i -g woml-cli
+### `<manual>` — run on demand
+
+The simplest trigger. Starts a run when the operator calls `woml run` with a payload.
+
+```xml
+<manual id="start" />
 ```
 
-Or with Bun:
+### `<webhook>` — accept HTTP requests
 
-```bash
-bun add --global woml-cli
+Registers a static HTTP route that starts a run for every validated payload.
+
+```xml
+<webhook id="hook"
+         path="/webhooks/orders"
+         method="POST"
+         auth="bearer"
+         secret="{{secrets.ORDER_WEBHOOK_TOKEN}}">
+  <schema>
+    { "type": "object", "required": ["orderId"], "properties": { "orderId": { "type": "string" } } }
+  </schema>
+</webhook>
 ```
 
-Or with pnpm:
+- `auth="bearer"` requires a `secret`; `auth="none"` is for deliberately public routes.
+- The inline `<schema>` is JSON Schema Draft 2020-12; invalid payloads return `400 Bad Request` with the `WOML_TRIGGER_SCHEMA_INVALID` code and never start a run.
 
-```bash
-pnpm add -g woml-cli
+### `<schedule>` — cron expressions
+
+Starts a run on a WOML Cron v1 schedule. Five numeric fields (`minute hour day-of-month month day-of-week`), wildcards, lists, inclusive ranges, and `/step` are supported. Seconds, names, and Quartz-only tokens are rejected.
+
+```xml
+<schedule id="daily"
+          cron="0 9 * * MON-FRI"
+          timezone="UTC"
+          on-missed="skip" />
 ```
 
-This installs the `woml` command:
+`timezone` defaults to UTC. `on-missed` chooses `skip` or `run-once` after a restart.
 
-```bash
-woml --version
+### `<interval>` — fixed cadence
+
+Starts a run on a fixed interval. The compiler must not translate it into cron if semantics would change.
+
+```xml
+<interval id="heartbeat" every="30s" on-missed="skip" />
+```
+
+### `<event>` — react to internal events
+
+Starts a run when another workflow emits a named event through the durable event bus.
+
+```xml
+<event id="created"
+       name="order.created"
+       secret="{{secrets.EVENT_CONTROL_TOKEN}}">
+  <schema>
+    { "type": "object", "required": ["orderId"], "properties": { "orderId": { "type": "string" } } }
+  </schema>
+</event>
+```
+
+### `<slack>` — Slack Socket Mode
+
+Starts a run for Slack workspace events via a single Socket Mode connection per credential pair.
+
+```xml
+<slack id="msg"
+       events="app-mention,direct-message"
+       channels="ops,alerts"
+       bot-token="{{secrets.SLACK_BOT_TOKEN}}"
+       app-token="{{secrets.SLACK_APP_TOKEN}}" />
+```
+
+`events` accepts `app-mention` and `direct-message`. `channels` is optional and limits mentions to a comma-separated set.
+
+### `<telegram>` — Telegram long polling
+
+Starts a run for every incoming Telegram message via long polling and durable admission.
+
+```xml
+<telegram id="bot"
+          events="message"
+          bot-token="{{secrets.TELEGRAM_BOT_TOKEN}}" />
+```
+
+Telegram v1 supports the single `message` event.
+
+### `<discord>` — Discord Gateway
+
+Starts a run for Discord activity via a shared resumable Gateway connection.
+
+```xml
+<discord id="bot"
+         events="app-mention,direct-message"
+         bot-token="{{secrets.DISCORD_BOT_TOKEN}}" />
+```
+
+`channels` is optional and accepts comma-separated numeric channel IDs (17–20 digits). Channel names are rejected because they are mutable display labels.
+
+### `<whatsapp>` — WhatsApp Cloud API
+
+Starts a run for inbound WhatsApp messages via signed Meta Cloud API callbacks.
+
+```xml
+<whatsapp id="bot"
+          events="message"
+          phone-number-id="123456789012345"
+          verify-token="{{secrets.WHATSAPP_VERIFY_TOKEN}}"
+          app-secret="{{secrets.WHATSAPP_APP_SECRET}}" />
 ```
 
-**Requirements:** macOS (x64, arm64), Linux (x64, glibc), or Windows (x64, arm64). No database to set up, the default state store is bundled.
+`phone-number-id` is Meta's durable Phone Number ID, not the display phone number.
+
+---
 
-## Quick example: organize your Downloads folder
+## Steps
 
-Run this once and it sorts every file in a folder into the right place — images, documents, videos, archives — using conditional logic, a real filesystem loop, and zero external services.
+Steps run sequentially inside `<steps>`. Each `<step>` returns a value that becomes available at `context.steps.<stepId>`.
+
+```xml
+<step id="greet">
+  <script>
+    return { message: `Hello, ${context.payload.name}!` };
+  </script>
+</step>
+```
+
+---
+
+## Control flow
+
+Two compact routing primitives cover most branching needs.
+
+### `<choose>` — mutually exclusive routes
+
+`<choose id="...">` selects the first `<when>` whose `test` reference is true and publishes a merged result at `context.steps.<chooseId>`. The `test` attribute holds exactly one context reference — complex conditions belong in named steps.
+
+```xml
+<step id="needsReview">
+  <script>
+    return { value: context.steps.analysis.risk > 0.3 };
+  </script>
+</step>
+
+<choose id="reviewRoute">
+  <when test="{{context.steps.needsReview.value}}">
+    <step id="humanDecision">
+      <script>return { routed: 'review' };</script>
+    </step>
+    <result value="{{context.steps.humanDecision}}" />
+  </when>
+  <otherwise>
+    <step id="automaticDecision">
+      <script>return { routed: 'auto' };</script>
+    </step>
+    <result value="{{context.steps.automaticDecision}}" />
+  </otherwise>
+</choose>
+```
+
+### `<switch>` — exact-string routing
+
+`<switch id="..." value="...">` compares one context reference against ordered string cases and runs exactly one route.
+
+```xml
+<switch id="route" value="{{context.steps.classify.intent}}">
+  <case value="bug">
+    <step id="sendBugs">
+      <script>return { routedTo: 'bugs' };</script>
+    </step>
+    <result value="{{context.steps.sendBugs}}" />
+  </case>
+  <default>
+    <step id="dropNoise">
+      <script>return { dropped: true };</script>
+    </step>
+    <result value="{{context.steps.dropNoise}}" />
+  </default>
+</switch>
+```
+
+---
+
+## Concurrent steps — `<parallel>`
+
+`<parallel>` runs its direct child steps concurrently and joins after they finish. A one-step parallel is a valid degenerate fork/join.
+
+```xml
+<parallel id="fieldData" concurrency="2" on-error="wait-all">
+  <step id="loadWeather">
+    <script>return loadWeather(context.payload.fieldId);</script>
+  </step>
+  <step id="loadSoil">
+    <script>return loadSoil(context.payload.fieldId);</script>
+  </step>
+</parallel>
+```
+
+- `concurrency` caps simultaneous child steps; defaults to the number of children.
+- `on-error` is `fail-fast` (default) or `wait-all`. `fail-fast` stops scheduling new children; `wait-all` lets every child reach its terminal outcome first.
+- All children see the same context view from immediately before the fork.
+- A child cannot reference a sibling's output.
+
+For multi-step concurrent routes (each branch holds its own sequence of steps), use `<fork>` and `<branch>` instead.
+
+---
+
+## Concurrent routes — `<fork>` and `<branch>`
+
+`<fork>` runs multiple multi-step branches concurrently and joins on a chosen set. Each `<branch>` may contain steps, choices, switches, parallel groups, and approvals. Branches remain sequential internally while overlapping through the multiplexed Bun host.
+
+```xml
+<fork id="distribution" join="all">
+  <branch id="tiktok">
+    <step id="formatTikTok">
+      <script>return { caption: `${context.steps.campaign.title} #automation` };</script>
+    </step>
+    <step id="publishTikTok">
+      <script>return { platform: 'tiktok', caption: context.steps.formatTikTok.caption };</script>
+    </step>
+  </branch>
+  <branch id="instagram">
+    <step id="formatInstagram">
+      <script>return { caption: `${context.steps.campaign.title}\n${context.steps.campaign.url}` };</script>
+    </step>
+    <step id="publishInstagram">
+      <script>return { platform: 'instagram', caption: context.steps.formatInstagram.caption };</script>
+    </step>
+  </branch>
+</fork>
+```
+
+- `join="all"` (or omitted) waits for every branch.
+- `join="none"` waits for none.
+- A whitespace-separated branch-ID list waits only for those branches.
+- A branch can read context available before the fork and outputs created earlier in that same branch; it cannot read sibling-branch outputs.
+- Nested forks inside a fork-owned branch are rejected.
+- A workflow whose only terminal structure is a fork is rejected.
+
+---
+
+## Human approvals — `<approval>`
+
+`<approval>` is a first-class durable control-flow item. It records that a run is waiting for a decision, optionally fires notifications, suspends the run, and selects exactly one continuation after the decision arrives.
+
+```xml
+<approval id="contentApproval"
+          name="Content approval"
+          description="Ask a moderator to approve or reject"
+          timeout="24h"
+          on-timeout="reject">
+  <notify>
+    <slack channels="moderators"
+           bot-token="{{secrets.SLACK_BOT_TOKEN}}"
+           app-token="{{secrets.SLACK_APP_TOKEN}}" />
+  </notify>
+
+  <step id="hold" />
+  <when-approved>
+    <step id="publish">
+      <script>return { published: true };</script>
+    </step>
+    <result value="{{context.steps.publish}}" />
+  </when-approved>
+  <when-rejected>
+    <step id="archive">
+      <script>return { archived: true };</script>
+    </step>
+    <result value="{{context.steps.archive}}" />
+  </when-rejected>
+</approval>
+```
+
+- `timeout` caps how long the approval waits; `on-timeout` chooses `approve`, `reject`, or another arm.
+- Optional `<notify>` fires built-in Slack/Telegram/Discord/WhatsApp notifications when the approval is armed.
+- Exactly one `<when-approved>` or `<when-rejected>` is selected after the decision arrives.
+
+---
+
+## Notifications — `<notify>`
+
+`<notify>` is a container for built-in Slack, Telegram, Discord, or WhatsApp deliveries. It is not a standalone step — it is attached to the parent that arms the notification.
+
+### Inside lifecycle hooks
+
+Fire a notification when the run finishes successfully or fails.
+
+```xml
+<lifecycle>
+  <on-success>
+    <notify>
+      <slack channels="ops"
+             bot-token="{{secrets.SLACK_BOT_TOKEN}}"
+             app-token="{{secrets.SLACK_APP_TOKEN}}" />
+    </notify>
+    <script>
+      console.log('Run completed successfully');
+    </script>
+  </on-success>
+  <on-error>
+    <notify>
+      <slack channels="oncall"
+             bot-token="{{secrets.SLACK_BOT_TOKEN}}"
+             app-token="{{secrets.SLACK_APP_TOKEN}}" />
+    </notify>
+    <script>
+      console.error('Run failed');
+    </script>
+  </on-error>
+</lifecycle>
+```
+
+### Inside an approval
+
+Fire a notification when the approval is armed so the right moderator sees the decision request (see the `<approval>` example above).
+
+A `<notify>` contains one or more built-in provider tags — `<slack>`, `<telegram>`, `<discord>`, or `<whatsapp>` — and must not contain anything else.
+
+---
+
+## Real examples
+
+### Local automation — organize a folder by file type
+
+Run once, sorts every file into the right subfolder. Zero external services, zero API keys.
 
 ```xml
 <woml>
-  <workflow id="organize" name="Organize a folder by file type">
-    <triggers>
-      <manual id="start" />
-    </triggers>
+  <workflow id="organize" name="Organize a folder by file type" version="1.0.0">
+    <triggers><manual id="start" /></triggers>
 
     <steps>
       <step id="scan">
@@ -93,86 +416,70 @@ Run this once and it sorts every file in a folder into the right place — image
         </script>
       </step>
 
-      <for-each id="organize" source="{{context.steps.scan.files}}">
-        <step id="classify">
+      <parallel id="moveAll" concurrency="4">
+        <step id="moveImages">
           <script>
-            return { ext: context.item.ext };
+            const { promises: fs } = await import('fs');
+            const path = await import('path');
+            const { folder, files } = context.steps.scan;
+            for (const f of files.filter(f => ['.jpg','.jpeg','.png','.gif','.webp','.svg'].includes(f.ext))) {
+              const from = path.join(folder, f.name);
+              const to = path.join(folder, 'Images', f.name);
+              await fs.mkdir(path.dirname(to), { recursive: true });
+              await fs.rename(from, to);
+            }
+            return { ok: true };
           </script>
         </step>
-
-        <choose>
-          <when test="{{context.steps.classify.ext in ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.svg']}}">
-            <step id="move-image">
-              <script>
-                const { promises: fs } = await import('fs');
-                const path = await import('path');
-                const from = path.join(context.steps.scan.folder, context.item.name);
-                const to = path.join(context.steps.scan.folder, 'Images', context.item.name);
-                await fs.mkdir(path.dirname(to), { recursive: true });
-                await fs.rename(from, to);
-                return { movedTo: 'Images' };
-              </script>
-            </step>
-          </when>
-          <when test="{{context.steps.classify.ext in ['.pdf', '.doc', '.docx', '.txt', '.md', '.rtf']}}">
-            <step id="move-doc">
-              <script>
-                const { promises: fs } = await import('fs');
-                const path = await import('path');
-                const from = path.join(context.steps.scan.folder, context.item.name);
-                const to = path.join(context.steps.scan.folder, 'Docs', context.item.name);
-                await fs.mkdir(path.dirname(to), { recursive: true });
-                await fs.rename(from, to);
-                return { movedTo: 'Docs' };
-              </script>
-            </step>
-          </when>
-          <when test="{{context.steps.classify.ext in ['.mp4', '.mov', '.avi', '.mkv', '.webm']}}">
-            <step id="move-video">
-              <script>
-                const { promises: fs } = await import('fs');
-                const path = await import('path');
-                const from = path.join(context.steps.scan.folder, context.item.name);
-                const to = path.join(context.steps.scan.folder, 'Videos', context.item.name);
-                await fs.mkdir(path.dirname(to), { recursive: true });
-                await fs.rename(from, to);
-                return { movedTo: 'Videos' };
-              </script>
-            </step>
-          </when>
-          <when test="{{context.steps.classify.ext in ['.zip', '.tar', '.gz', '.7z', '.rar', '.dmg']}}">
-            <step id="move-archive">
-              <script>
-                const { promises: fs } = await import('fs');
-                const path = await import('path');
-                const from = path.join(context.steps.scan.folder, context.item.name);
-                const to = path.join(context.steps.scan.folder, 'Archives', context.item.name);
-                await fs.mkdir(path.dirname(to), { recursive: true });
-                await fs.rename(from, to);
-                return { movedTo: 'Archives' };
-              </script>
-            </step>
-          </when>
-          <otherwise>
-            <step id="move-misc">
-              <script>
-                const { promises: fs } = await import('fs');
-                const path = await import('path');
-                const from = path.join(context.steps.scan.folder, context.item.name);
-                const to = path.join(context.steps.scan.folder, 'Misc', context.item.name);
-                await fs.mkdir(path.dirname(to), { recursive: true });
-                await fs.rename(from, to);
-                return { movedTo: 'Misc' };
-              </script>
-            </step>
-          </otherwise>
-        </choose>
-      </for-each>
+        <step id="moveDocs">
+          <script>
+            const { promises: fs } = await import('fs');
+            const path = await import('path');
+            const { folder, files } = context.steps.scan;
+            for (const f of files.filter(f => ['.pdf','.doc','.docx','.txt','.md','.rtf'].includes(f.ext))) {
+              const from = path.join(folder, f.name);
+              const to = path.join(folder, 'Docs', f.name);
+              await fs.mkdir(path.dirname(to), { recursive: true });
+              await fs.rename(from, to);
+            }
+            return { ok: true };
+          </script>
+        </step>
+        <step id="moveVideos">
+          <script>
+            const { promises: fs } = await import('fs');
+            const path = await import('path');
+            const { folder, files } = context.steps.scan;
+            for (const f of files.filter(f => ['.mp4','.mov','.avi','.mkv','.webm'].includes(f.ext))) {
+              const from = path.join(folder, f.name);
+              const to = path.join(folder, 'Videos', f.name);
+              await fs.mkdir(path.dirname(to), { recursive: true });
+              await fs.rename(from, to);
+            }
+            return { ok: true };
+          </script>
+        </step>
+        <step id="moveArchives">
+          <script>
+            const { promises: fs } = await import('fs');
+            const path = await import('path');
+            const { folder, files } = context.steps.scan;
+            for (const f of files.filter(f => ['.zip','.tar','.gz','.7z','.rar'].includes(f.ext))) {
+              const from = path.join(folder, f.name);
+              const to = path.join(folder, 'Archives', f.name);
+              await fs.mkdir(path.dirname(to), { recursive: true });
+              await fs.rename(from, to);
+            }
+            return { ok: true };
+          </script>
+        </step>
+      </parallel>
 
       <step id="summary">
         <script>
-          const total = context.steps.scan.files.length;
-          return { message: `Organized ${total} file(s) into Images/, Docs/, Videos/, Archives/, Misc/.` };
+          return {
+            message: `Organized ${context.steps.scan.files.length} file(s) into Images/, Docs/, Videos/, Archives/.`
+          };
         </script>
       </step>
     </steps>
@@ -180,58 +487,127 @@ Run this once and it sorts every file in a folder into the right place — image
 </woml>
 ```
 
-Save it as `organize.woml` and run it:
-
 ```bash
 woml run organize.woml --payload '{"path":"/path/to/Downloads"}'
 ```
 
-WOML scans the folder, loops over every file with `<for-each>`, routes each one through a `<choose>` decision by extension, and moves it into the right subfolder with `fs.rename`. Press Ctrl+C to stop the run.
-
-```mermaid
-graph TD
-    A[Manual trigger] --> B[Scan folder for files]
-    B --> C[For each file]
-    C --> D{File extension?}
-    D -->|jpg, png, gif, webp, svg| E[Move to Images/]
-    D -->|pdf, doc, txt, md| F[Move to Docs/]
-    D -->|mp4, mov, avi, mkv| G[Move to Videos/]
-    D -->|zip, tar, gz, dmg| H[Move to Archives/]
-    D -->|anything else| I[Move to Misc/]
-    E --> J[Summary: organized N files]
-    F --> J
-    G --> J
-    H --> J
-    I --> J
-```
+---
 
-This is one WOML file. No setup, no cloud, no API keys. It runs locally, pulls in real npm packages (`fs`, `path`) on demand, and exercises the same primitives that make n8n workflows become spaghetti and Zapier workflows impossible: `<choose>` for conditional routing, `<for-each>` for iteration, and `<script>` for the parts that need real code.
+### AI-powered — classify Slack messages and route them to the right channel
 
-## Real workflows in WOML
+Send every incoming Slack message to an LLM, classify intent, and forward to a dedicated channel.
 
-Four triggers, four real automations. Each is a complete, runnable workflow.
+```xml
+<woml>
+  <workflow id="slack-router" version="1.0.0">
+    <triggers>
+      <slack id="incoming"
+             events="app-mention,direct-message"
+             channels="inbox"
+             bot-token="{{secrets.SLACK_BOT_TOKEN}}"
+             app-token="{{secrets.SLACK_APP_TOKEN}}" />
+    </triggers>
 
-**Webhook — flag risky orders and alert Slack:**
+    <steps>
+      <step id="classify">
+        <script>
+          const response = await services.http.request({
+            method: 'POST',
+            url: 'https://api.openai.com/v1/chat/completions',
+            headers: { authorization: `Bearer ${secrets.OPENAI_API_KEY}` },
+            body: {
+              model: 'gpt-4o-mini',
+              messages: [
+                {
+                  role: 'system',
+                  content: 'Classify the message into one of: bug, feature, question, noise. Reply with JSON { "intent": "...", "confidence": 0..1 }.'
+                },
+                { role: 'user', content: context.payload.text }
+              ],
+              response_format: { type: 'json_object' }
+            },
+            timeoutMs: 10000
+          });
+          return JSON.parse(response.body.choices[0].message.content);
+        </script>
+      </step>
+
+      <switch id="route" value="{{context.steps.classify.intent}}">
+        <case value="bug">
+          <step id="sendBugs">
+            <script>
+              await services.slack.send({
+                channel: '#bugs',
+                text: `🐛 ${context.payload.text}\n> confidence ${context.steps.classify.confidence}`
+              });
+              return { routedTo: 'bugs' };
+            </script>
+          </step>
+          <result value="{{context.steps.sendBugs}}" />
+        </case>
+        <case value="feature">
+          <step id="sendFeatures">
+            <script>
+              await services.slack.send({
+                channel: '#feature-requests',
+                text: `💡 ${context.payload.text}`
+              });
+              return { routedTo: 'feature-requests' };
+            </script>
+          </step>
+          <result value="{{context.steps.sendFeatures}}" />
+        </case>
+        <case value="question">
+          <step id="sendQuestions">
+            <script>
+              await services.slack.send({
+                channel: '#questions',
+                text: `❓ ${context.payload.text}`
+              });
+              return { routedTo: 'questions' };
+            </script>
+          </step>
+          <result value="{{context.steps.sendQuestions}}" />
+        </case>
+        <default>
+          <step id="dropNoise">
+            <script>return { dropped: true };</script>
+          </step>
+          <result value="{{context.steps.dropNoise}}" />
+        </default>
+      </switch>
+    </steps>
+  </workflow>
+</woml>
+```
+
+---
+
+### Webhook — flag risky orders, alert Slack
 
 ```xml
 <woml>
-  <workflow id="order-guard">
+  <workflow id="order-guard" version="1.0.0">
     <triggers>
-      <webhook id="order" path="/webhooks/orders" method="POST"
+      <webhook id="order"
+               path="/webhooks/orders"
+               method="POST"
+               auth="bearer"
                secret="{{secrets.ORDER_WEBHOOK_TOKEN}}">
         <schema>
           {
             "type": "object",
             "required": ["orderId", "total", "customerId"],
             "properties": {
-              "orderId": { "type": "string" },
-              "total": { "type": "number" },
+              "orderId":    { "type": "string" },
+              "total":      { "type": "number" },
               "customerId": { "type": "string" }
             }
           }
         </schema>
       </webhook>
     </triggers>
+
     <steps>
       <step id="risk">
         <script>
@@ -240,35 +616,52 @@ Four triggers, four real automations. Each is a complete, runnable workflow.
             url: `https://internal.api/customers/${context.payload.customerId}`,
             timeoutMs: 5000
           });
-          return { flagged: context.payload.total > 10000 || customer.body.disputes > 0 };
+          return {
+            flagged: context.payload.total > 10000 || customer.body.disputes > 0
+          };
         </script>
       </step>
+
+      <step id="isFlagged">
+        <script>return { value: context.steps.risk.flagged };</script>
+      </step>
+
+      <choose id="alertRoute">
+        <when test="{{context.steps.isFlagged.value}}">
+          <step id="alert">
+            <script>
+              await services.slack.send({
+                channel: '#fraud',
+                text: `High-risk order ${context.payload.orderId} ($${context.payload.total}) needs review.`
+              });
+              return { alerted: true };
+            </script>
+          </step>
+          <result value="{{context.steps.alert}}" />
+        </when>
+        <otherwise>
+          <step id="logOk">
+            <script>return { logged: true };</script>
+          </step>
+          <result value="{{context.steps.logOk}}" />
+        </otherwise>
+      </choose>
     </steps>
-    <choose>
-      <when test="context.steps.risk.flagged">
-        <step id="alert">
-          <script>
-            await services.slack.send({
-              channel: '#fraud',
-              text: `High-risk order ${context.payload.orderId} ($${context.payload.total}) needs review.`
-            });
-            return { alerted: true };
-          </script>
-        </step>
-      </when>
-    </choose>
   </workflow>
 </woml>
 ```
 
-**Schedule — a daily sales report, every weekday at 9am:**
+---
+
+### Schedule — daily sales report at 9am weekdays
 
 ```xml
 <woml>
-  <workflow id="daily-report">
+  <workflow id="daily-report" version="1.0.0">
     <triggers>
       <schedule id="weekdays" cron="0 9 * * MON-FRI" timezone="UTC" />
     </triggers>
+
     <steps>
       <step id="totals">
         <script>
@@ -279,6 +672,7 @@ Four triggers, four real automations. Each is a complete, runnable workflow.
           return rows[0];
         </script>
       </step>
+
       <step id="publish">
         <script>
           const { orders, revenue } = context.steps.totals;
@@ -294,30 +688,26 @@ Four triggers, four real automations. Each is a complete, runnable workflow.
 </woml>
 ```
 
-**Telegram — answer `/sales` from your team chat:**
+---
+
+### Telegram — answer mentions in your team chat
 
 ```xml
 <woml>
-  <workflow id="telegram-sales">
+  <workflow id="telegram-echo" version="1.0.0">
     <triggers>
-      <telegram id="ask" events="message" commands="/sales"
+      <telegram id="incoming"
+                events="message"
                 bot-token="{{secrets.TELEGRAM_BOT_TOKEN}}" />
     </triggers>
+
     <steps>
-      <step id="lookup">
-        <script>
-          const rows = await services.database.query({
-            sql: "SELECT COUNT(*) AS today FROM orders WHERE created_at >= date('now')",
-            parameters: []
-          });
-          return { today: rows[0].today };
-        </script>
-      </step>
-      <step id="notify">
+      <step id="reply">
         <script>
-          await services.slack.send({
-            channel: '#sales',
-            text: `Today's numbers were requested on Telegram: ${context.steps.lookup.today} orders so far.`
+          await services.messaging.send({
+            channel: 'telegram',
+            conversationId: context.payload.conversationId,
+            text: `You said: ${context.payload.text}`
           });
           return { ok: true };
         </script>
@@ -327,25 +717,30 @@ Four triggers, four real automations. Each is a complete, runnable workflow.
 </woml>
 ```
 
-**Event — send a confirmation email whenever another workflow emits `order.created`:**
+---
+
+### Event — send a confirmation email when another workflow emits `order.created`
 
 ```xml
 <woml>
-  <workflow id="order-confirmation">
+  <workflow id="order-confirmation" version="1.0.0">
     <triggers>
-      <event id="created" name="order.created" secret="{{secrets.EVENT_CONTROL_TOKEN}}">
+      <event id="created"
+             name="order.created"
+             secret="{{secrets.EVENT_CONTROL_TOKEN}}">
         <schema>
           {
             "type": "object",
             "required": ["orderId", "email"],
             "properties": {
               "orderId": { "type": "string" },
-              "email": { "type": "string" }
+              "email":   { "type": "string" }
             }
           }
         </schema>
       </event>
     </triggers>
+
     <steps>
       <step id="confirm">
         <script>
@@ -368,34 +763,7 @@ Four triggers, four real automations. Each is a complete, runnable workflow.
 </woml>
 ```
 
-Every script gets explicit runtime bindings — `context.payload` (trigger input), `context.steps.<id>` (earlier step output), `services.*` (supervised capabilities like HTTP, database, Slack, storage, cache), and `secrets.*` (only the secrets proven necessary at compile time). Scripts return JSON-compatible values; the Rust engine records every outcome durably.
-
-**→ [Browse all examples](./examples/)**
-
-## WOML vs alternatives
-
-| Tool           | How you write it    | Readable by the whole team    | Self-hosted | No ceiling |
-| -------------- | ------------------- | ----------------------------- | ----------- | ---------- |
-| **WOML**       | Markup + JavaScript | ✅                            | ✅          | ✅         |
-| n8n            | Visual canvas       | ⚠️ Until it becomes spaghetti | ✅          | ❌         |
-| Zapier         | Visual canvas       | ⚠️ Until it becomes spaghetti | ❌          | ❌         |
-| Temporal       | Code (TS/Go/Java)   | ❌                            | ✅          | ✅         |
-| Step Functions | JSON (ASL)          | ❌                            | ❌          | ⚠️         |
-| Airflow        | Python DAGs         | ❌                            | ✅          | ✅         |
-
-WOML is the only one that combines all three: readable as markup, free and self-hosted, and unlimited in what it can express.
-
-## What WOML includes
-
-- Manual, webhook, schedule, interval, event, Slack, Telegram, Discord, and WhatsApp triggers.
-- Sequential steps, retries, parallel groups, choices, switches, and forked multi-step branches.
-- Durable approvals with provider notifications and shared decisions.
-- Workflow and step lifecycle hooks.
-- Built-in HTTP, SQL database, storage, cache, event, durable-state, messaging, and workflow call/start services.
-- Local JavaScript/TypeScript modules, reusable WOML steps, and custom notification providers.
-- Runtime concurrency, rate-limit, queue, and timeout policies.
-- Foreground and background operation, run inspection, log following, backup, recovery, and retention.
-- A VS Code extension with HTML-style markup and embedded JavaScript syntax.
+---
 
 ## Common commands
 
@@ -411,22 +779,8 @@ woml backup backups/latest               # Snapshot the durable state store to a
 woml prune --before 30d --dry-run        # Preview which old runs would be purged
 ```
 
-See the [CLI reference](docs/cli-reference.md) for every command and option.
-
-## Documentation
-
-Full documentation — language reference, all tags, triggers, control flow, services, modules, and production deployment — lives in the docs.
-
-**→ [Read the full documentation](./docs/README.md)**
-
-## Support and security
-
-Use [GitHub Discussions](https://github.com/dali-benothmen/woml/discussions) for questions and [GitHub Issues](https://github.com/dali-benothmen/woml/issues) for reproducible bugs. Please report vulnerabilities privately according to the [security policy](SECURITY.md).
-
-## Contributing
-
-Contributions are welcome — bug reports, feature ideas, docs, or a custom provider. See [CONTRIBUTING.md](./CONTRIBUTING.md) to get started.
+---
 
 ## License
 
-WOML is released under the [Apache License 2.0](./LICENSE).
+Apache-2.0.