inquirex 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef8604fa6b1eb6fb6cd9506c696c806067d209abf6260872f5d0cc87d5b6eae0
-  data.tar.gz: 1a543f219f202ff5ae05fcae1040e460391e044b177a94612519618d9604f943
+  metadata.gz: f99f7adba97c905c55490b57467fe062251719bbb98d698fe49e6dd04360fcf7
+  data.tar.gz: 2c6850590153b96ee376ddaa0314c2de3cf729f6ea2d7c8f3d0ccb20d2359683
 SHA512:
-  metadata.gz: eeeb13a340aaf5169f661c4fce77bdc666e68d8fac9c7b4ae52757c5b5999b46ae0a9ec83042c680d3f1b57302cf9f0e08c4e9b80467ccd98e2447294f0110cb
-  data.tar.gz: 0b213dde96f8ec277e31d302a557bb665361046529b9ebf75c19a159518f7f84e7d18ec6db4927e7d23d1ca4bd1dd1f0e68208c971624cd2c96b1624939dcc74
+  metadata.gz: 18b95d28461f971551997bb177c6ead5c4165562f1d627460d58656440a0884bf0972eef2d97a31e3883f34720349be82e24e2fa567b7181eea0f14361182355
+  data.tar.gz: ed93da41fe8d2f66098b0165224e472d794d6f7ab9313dd8ec9a8a80b0d299ef5623d957361d83a27680b1ce3c025dd294fc6690c855c02a32df90348726718c

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-19
+
+- Post-completion `action` DSL verb with an extensible effect registry
+- `send_email` effect: builds `Mail::Message` objects (multipart text/HTML)
+  from `{{field}}` templates into `Answers#outbox`; delivery is the host
+  application's responsibility. The `mail` gem is a soft dependency.
+- `run { |answers, outbox| ... }` escape-hatch effect (stripped from JSON)
+- `webhook` effect: POSTs the answers envelope to a static https URL whose
+  host must be covered by the new top-level `allowed_domains` declaration;
+  enforcement runs in `Definition#validate!`, so tampered JSON definitions
+  fail at rehydration
+- `Inquirex::Actions::Runner` and `Inquirex::Actions.run(definition, answers)`
+- Actions serialize to/from JSON with their rule gates
+- `CompletionMetadata` (OpenStruct; `engine` and `engine_version` required)
+  stamped by the engine at flow completion, enrichable by front-ends via the
+  new `Engine#after_completion` hook, persisted in engine state, and merged
+  into answers by `Engine#answers_with_metadata`
+
 ## [0.1.0] - 2026-04-13
 
 - Initial release

data/README.md

@@ -1,50 +1,72 @@
-[![Ruby](https://github.com/inquirex/inquirex/actions/workflows/main.yml/badge.svg)](https://github.com/inquirex/inquirex/actions/workflows/main.yml)   ![Coverage](docs/badges/coverage_badge.svg)
+[![Gem Version](https://badge.fury.io/rb/inquirex.svg)](https://badge.fury.io/rb/inquirex) [![Ruby](https://github.com/inquirex/inquirex/actions/workflows/main.yml/badge.svg)](https://github.com/inquirex/inquirex/actions/workflows/main.yml) ![Coverage](docs/badges/coverage_badge.svg)
 
 # Inquirex
 
-`inquirex` is a pure Ruby, declarative, rules-driven questionnaire engine for building conditional intake forms, qualification wizards, and branching surveys.
+`inquirex` family of libraries (part Ruby, part JavaScript), is a declarative, rules-driven questionnaire engine for building conditional intake forms, qualification wizards, and branching surveys, which can be AI-enabled, and rendered on your site inside a "copilot" widget window or in a TUI (Terminal UI) all the same.
 
 > [!IMPORTANT]
 >
-> Note that `inquirex` is the base gem of the ecosystem that contains:
+> Today the ecosystem contains:
 >
-> - [`inquirex`](https://github.com/inquirex/inquirex)
-> - [`inquirex-llm`](https://github.com/inquirex/inquirex-llm)
-> - [`inquirex-tty`](https://github.com/inquirex/inquirex-)
-> - [`inquirex-js`](https://github.com/inquirex/inquirex-js)
+> - [`inquirex`](https://github.com/inquirex/inquirex): the base gem that defines the graph via DSL and provides most of the backend features
+> - [`inquirex-llm`](https://github.com/inquirex/inquirex-llm): a tiny gem that extends the DSL by the word `extract` which, given a previous question answered in the form of free text, can use the model of your choice to return structured breakdown of text into answers to questions that might follow, thus shortening the form considerably.
+> - [`inquirex-tty`](https://github.com/inquirex/inquirex-tty): is the gem that renders the forms on the TUI (Terminal UI). This is also the gem that provides the CLI `inqurex` for performing various tasks such as validating DSL files, converting them from Ruby to JSON and back, and more. It is also the gem where a folder of DSL `examples` can be used to get a feel for how this works.
+> - [`inquirex-js`](https://github.com/inquirex/inquirex-js) (`npmjs` module [`@kigster/inquirex-js`](https://www.npmjs.com/package/@kigster/inquirex-js)) is the NPM package that connects web UI with the form definition in JSON format. If LLM is not needed, the entire flow becomes deterministic and collects answers as the user answers your questions, and then POSTS them to the URL of your choice.
 >
-> For a presentation on these gems and what they do please watch the [RubySF presentation](https://www.youtube.com/watch?v=iaoKW7Ap3_M&t=1s) and you can also [view the slides form the presentation](https://reinvent.one/images/talks/pdfs/2026.inquirex.pdf).
+> For a presentation about these gems and what they do please watch the [RubySF presentation](https://www.youtube.com/watch?v=iaoKW7Ap3_M&t=1s) and you can also [view the slides form the presentation](https://reinvent.one/images/talks/pdfs/2026.inquirex.pdf).
+>
+> Finally, the SaaS application [qualified.at](https://qualified.at) allows busy professionals such as consultants, doctors, tax-preparers, who are short on time, or can't be bothered to figure out the technical side of integrating these libraries, to leverage the entire ecosystem by creating their own custom lead intake forms on the SaaS application, dropping the auto-generated widget on their (potentially static website), and showing the copilot to their customers, customizing from nothing at all, to what triggers copilot's appearance, it's look and feel, and so on. The site automatically supports the LLM keyword `extract` as part of the DSL, and also collects the answers from your leads in your account: the data that you own, and can export at any time into a CSV download, a Google Spreadsheet, etc.
+
+## Why Inquirex?
+
+There are plenty of form builders, state machines, workflow libraries, etc. And yet, none of them combine the convenience of a DSL with logical separation between the form substance, and the rendering UI quite like this.
+
+There are plenty of form building gems, hard-coded branching controllers, React components, or database callbacks.
+
+***Inquirex is quite different.***
+
+It provides a rich DSL for creating dynamic user intake forms, with complexity ranging from a simple straight-line forms to multi-branch, conditional forms with dozens of potential branches, *UI widget hints* for various rendering platforms, with *accumulators* that allow computing sums or products based on user's answers (which allow you to compute — for user or for yourself — that the service you are requesting will cost between $X & $Y).
+
+> [!NOTE]
+>
+> For technically inclined, Inquirex turns user forms into a directed graph, where nodes are either questions or statements (or UI transitions), while edges are AST-based logical conditions that can be stacked and joined in arbitrarily complex ways, allowing you to move from one question to any other based on the previous answer. See the details below.
+
+***Don't want to deal with figuring it out? Head to [Qualified.At](https://qualified.at/onboarding) and walk through the demo onboarding form, that exists specifically to show you how quickly you can have the same conceptually on your site, tailored to YOUR users.***
 
 ## Summary
 
-It is the core gem in the Inquirex ecosystem and focuses on:
+This one is the core gem in the Inquirex ecosystem that focuses on:
 
 - A conversational DSL (`ask`, `say`, `header`, `btw`, `warning`, `confirm`)
+
 - A serializable AST rule system (`contains`, `equals`, `greater_than`, `less_than`, `not_empty`, `all`, `any`)
+
 - Framework-agnostic widget rendering hints (`widget` DSL verb, `WidgetHint`, `WidgetRegistry`)
-- Named **accumulators** for running totals (pricing, complexity scoring, credit scoring, lead qualification)
+
+- Named ***accumulators*** for running totals (pricing, complexity scoring, credit scoring, lead qualification)
+
 - An immutable flow definition graph
+
 - A runtime engine for stateful step traversal
+
 - JSON round-trip serialization for cross-platform clients
-- A structured `Answers` wrapper and Mermaid graph export
 
-## Status
+- A structured `Answers` wrapper and Mermaid graph export (provided by `inquirex-tty` gem's CLI)
 
-- Version: `0.4.0`
-- Ruby: `>= 4.0.0` (project currently uses `4.0.5`)
-- Test suite: `220 examples, 0 failures`
-- Coverage: ~`94%` line coverage
+- In short:
 
-## Why Inquirex
+  - Define once in Ruby
+  - Serialize to JSON if you need to show the questions on the web UI
+  - Evaluate transitions consistently using rule AST objects
+  - Run the same flow identically in concept in different frontends (web widget, TUI, etc.)
 
-Many form builders hard-code branching in controllers, React components, or database callbacks. Inquirex keeps flow logic in one portable graph:
+So, if you ever wanted to ask users who arrive at your site a few simple questions (PII questions are strongly discouraged due to the fact that the gem is typically used by non-logged in users on your end — except, perhaps, name and email), and depending on their answers you might want to dig a bit deeper, so that once you get on the phone with them you'll already have a general picture, these gems are for you (or head to [qualified.at](https://qualified.at) and set up your free account to see how this works in practice.
 
-- Define once in Ruby
-- Serialize to JSON
-- Evaluate transitions consistently using rule AST objects
-- Run the same flow in different frontends (web widget, terminal, etc.)
+## Examples
 
-This design is the foundation for the broader ecosystem (`inquirex-ui`, `inquirex-tty`, `inquirex-js`, `inquirex-llm`, `inquirex-rails`).
+> [!NOTE]
+>
+> There are a couple of examples shown in this `README` file, and also in the [`./examples`](./examples) folder. You can read about running them in a [`README.md`](./examples/README.md) inside that folder.
 
 ## Installation
 
@@ -52,6 +74,10 @@ Add to your Gemfile:
 
 ```ruby
 gem "inquirex"
+#  if you are building a TUI or need the CLI version of this gem
+gem "inquirex-tty" 
+#  if you want to add the keyword `extract` to the DSL vocabilary
+gem "inquire-llm"  
 ```
 
 Then install:
@@ -60,6 +86,8 @@ Then install:
 bundle install
 ```
 
+And then, define your form as a Ruby DSL file (see [examples](https://github.com/inquirex/inquirex-tty/tree/main/examples) on Github), and consume it by either the `inquirex-tty` gem on the command line, or on the web via the [@kigster/inqiurex-js](https://www.npmjs.com/package/@kigster/inquirex-js) npmjs package.
+
 ## Quick Start
 
 ```ruby
@@ -170,26 +198,35 @@ end
 
 When no explicit `widget` is set, `WidgetRegistry` fills in sensible defaults per data type:
 
-| Data Type | Desktop | Mobile | TTY |
-|-----------|---------|--------|-----|
-| `:enum` | `radio_group` | `dropdown` | `select` |
+| Data Type     | Desktop          | Mobile           | TTY            |
+| ------------- | ---------------- | ---------------- | -------------- |
+| `:enum`       | `radio_group`    | `dropdown`       | `select`       |
 | `:multi_enum` | `checkbox_group` | `checkbox_group` | `multi_select` |
-| `:boolean` | `toggle` | `yes_no_buttons` | `yes_no` |
-| `:string` | `text_input` | `text_input` | `text_input` |
-| `:text` | `textarea` | `textarea` | `multiline` |
-| `:integer` | `number_input` | `number_input` | `number_input` |
-| `:currency` | `currency_input` | `currency_input` | `number_input` |
-| `:date` | `date_picker` | `date_picker` | `text_input` |
+| `:boolean`    | `toggle`         | `yes_no_buttons` | `yes_no`       |
+| `:string`     | `text_input`     | `text_input`     | `text_input`   |
+| `:text`       | `textarea`       | `textarea`       | `multiline`    |
+| `:integer`    | `number_input`   | `number_input`   | `number_input` |
+| `:currency`   | `currency_input` | `currency_input` | `number_input` |
+| `:date`       | `date_picker`    | `date_picker`    | `text_input`   |
 
 Display verbs (`say`, `header`, `btw`, `warning`) have no widget hints.
 
 Widget hints are included in JSON serialization under a `"widget"` key, keyed by target:
 
 ```json
-"widget": {
-  "desktop": { "type": "radio_group", "columns": 3 },
-  "mobile":  { "type": "dropdown" },
-  "tty":     { "type": "select" }
+{
+  "widget": {
+    "desktop": {
+      "type": "radio_group",
+      "columns": 3
+    },
+    "mobile": {
+      "type": "dropdown"
+    },
+    "tty": {
+      "type": "select"
+    }
+  }
 }
 ```
 
@@ -197,7 +234,7 @@ Widget hints are included in JSON serialization under a `"widget"` key, keyed by
 
 ```ruby
 step = definition.step(:priority)
-step.widget_hint_for(target: :desktop)            # explicit hint or nil
+step.widget_hint_for(target: :desktop)             # explicit hint or nil
 step.effective_widget_hint_for(target: :desktop)   # explicit hint or registry default
 ```
 
@@ -225,12 +262,12 @@ end
 
 Use the `accumulate` verb inside any `ask`/`confirm` step. Exactly one **shape** key must be provided:
 
-| Shape | Fits | Semantics |
-|-------|------|-----------|
-| `lookup: { ... }` | `:enum` | Adds the amount mapped to the chosen option value |
-| `per_selection: { ... }` | `:multi_enum` | Sums the amounts for every selected option |
-| `per_unit: N` | `:integer`, `:decimal` | Multiplies the numeric answer by `N` |
-| `flat: N` | any type | Adds `N` when the step has a truthy, non-empty answer |
+| Shape                    | Fits                   | Semantics                                             |
+| ------------------------ | ---------------------- | ----------------------------------------------------- |
+| `lookup: { ... }`        | `:enum`                | Adds the amount mapped to the chosen option value     |
+| `per_selection: { ... }` | `:multi_enum`          | Sums the amounts for every selected option            |
+| `per_unit: N`            | `:integer`, `:decimal` | Multiplies the numeric answer by `N`                  |
+| `flat: N`                | any type               | Adds `N` when the step has a truthy, non-empty answer |
 
 ```ruby
 ask :filing_status do
@@ -429,6 +466,120 @@ Pass a custom adapter to the engine:
 engine = Inquirex::Engine.new(definition, validator: my_validator)
 ```
 
+## Completion Metadata
+
+When a flow finishes, the engine guarantees a `CompletionMetadata` — an
+OpenStruct describing how the answers were collected. Only `engine` and
+`engine_version` are required members; rendering front-ends attach richer
+environment details from an `after_completion` hook:
+
+```ruby
+engine.after_completion do |eng|
+  eng.completion_metadata = Inquirex::CompletionMetadata.new(
+    engine:         "inquirex-tty",
+    engine_version: Inquirex::TTY::VERSION,
+    uname:          OpenStruct.new(Etc.uname),
+    user:           Etc.getlogin,
+    terminal:       ENV["LC_TERMINAL"] || ENV["TERM_PROGRAM"] || "Unknown"
+  )
+end
+```
+
+If no hook supplies one, the engine stamps the minimal core version
+(`engine: "inquirex"`, `engine_version: Inquirex::VERSION`). The metadata
+persists through `Engine#to_state` / `Engine.from_state`, and
+`engine.answers_with_metadata` merges it into the answers hash under
+`:completion_metadata` — which also makes it available to post-completion
+actions: webhook payloads carry it, and email templates can interpolate
+`{{completion_metadata.engine}}`.
+
+## Post-Completion Actions
+
+After all questions are answered, `action` declarations run server-side with
+the collected answers. The flagship effect is `send_email`, which **builds**
+`Mail::Message` objects (the same object ActionMailer wraps) and attaches them
+to `answers.outbox` — **nothing is delivered**; the host application decides
+how and when to send.
+
+```ruby
+Inquirex.define id: "tax-intake-2025" do
+  allowed_domains "*.agentica.group"   # egress allowlist for webhook effects
+
+  # ... ask steps ...
+
+  action :client_receipt, if: not_empty(:email) do
+    send_email to:      "{{email}}",
+               from:    "forms@agentica.group",
+               subject: "Thanks {{name}} — we received your intake",
+               text:    <<~TEXT,
+                 Hi {{name}},
+                 We received your answers:
+
+                 {{answers_summary}}
+               TEXT
+               html:    <<~HTML
+                 <p>Hi {{name}},</p>
+                 <img src="https://cdn.agentica.group/logo.png" alt="Logo">
+                 {{answers_summary}}
+               HTML
+  end
+
+  action :admin_alert do
+    send_email to: "owner@agentica.group", from: "forms@agentica.group",
+               subject: "New lead: {{name}} <{{email}}>",
+               html: "{{answers_summary}}"
+    run { |answers, outbox| Metrics.count(:lead, answers.to_flat_h) }
+  end
+
+  action :crm_push do
+    webhook url: "https://hooks.agentica.group/inquirex",
+            headers: { "X-Api-Key" => "..." }
+  end
+end
+```
+
+Execution and delivery:
+
+```ruby
+answers = Inquirex::Actions.run(definition, engine.answers)
+answers.outbox.messages   # => [Mail::Message, ...]
+answers.outbox.results    # => per-action :ok / :skipped / :failed trail
+
+# In a Rails host:
+answers.outbox.each do |message|
+  ActionMailer::Base.wrap_delivery_behavior(message)  # adopt Rails delivery config
+  message.deliver
+end
+```
+
+Key semantics:
+
+- **Templating is `{{field}}` interpolation only** — dot-notation keys resolved
+  against `Answers#to_flat_h`, deliberately inert (no code execution), so
+  definitions stored in a database render safely. Values interpolated into
+  `html:` bodies are HTML-escaped automatically; `text:` bodies stay verbatim.
+  The built-in `{{answers_summary}}` expands to all collected answers.
+- **`if:` gates** reuse the serializable rule AST (`not_empty(:email)`, ...).
+  A false rule records `:skipped` — declare no actions (or gate them) when a
+  flow should only save answers.
+- **`run { |answers, outbox| ... }`** is the full-Ruby escape hatch; like all
+  lambdas it is stripped from JSON.
+- **Failures are isolated**: a raising effect records `:failed` in
+  `outbox.results` and never blocks other actions.
+- **Images** in HTML bodies must be external URLs; attachments are unsupported.
+- The `mail` gem is a soft dependency, needed only when a message is built
+  (Rails hosts already have it via ActionMailer).
+- **`webhook url:`** POSTs `{"answers": {...}}` as JSON to a static URL. The
+  URL's host must be covered by `allowed_domains`, declared at the top of the
+  definition so the flow's egress surface is auditable at a glance. The check
+  runs inside `Definition.new` — a JSON definition whose webhook URL was
+  tampered with fails at *rehydration*, before anything executes. Also
+  enforced: https only (plain http just for localhost), no userinfo, no
+  `{{field}}` templates in URLs (the destination must be static), redirects
+  are not followed, and non-2xx responses record `:failed`.
+- Effects are extensible: `Inquirex::Actions.register(:save_record, MyEffect)`
+  gives a new verb both DSL and JSON wire support.
+
 ## Serialization
 
 Definitions support round-trip serialization:
@@ -446,6 +597,11 @@ Serialized structure includes:
 - Steps and transitions
 - Rule AST payloads
 - Widget hints
+- Post-completion actions (`actions`) with their rules and effects; `run`
+  blocks are stripped, and an action left with no serializable effects is
+  omitted entirely
+- The `allowed_domains` egress allowlist, re-enforced against webhook URLs
+  every time a definition is rehydrated
 
 Important serialization details:
 
@@ -540,15 +696,10 @@ Inquirex.define do       # one entry point, all verbs available
 end
 ```
 
-### Ecosystem
-
-- **`inquirex-llm`** -- LLM-powered verbs (`clarify`, `describe`, `summarize`, `detour`) for server-side AI processing
-- **`inquirex-tty`** -- terminal adapter using TTY Toolkit
-- **`inquirex-js`** -- embeddable browser widget (chat-style)
-- **`inquirex-rails`** -- Rails Engine for persistence, API, and asset serving
+## License
 
-> **Note:** `inquirex-ui` has been merged into core as of v0.2.0. Widget hints (`widget` DSL verb, `WidgetHint`, `WidgetRegistry`) are now built in.
+MIT. See [`LICENSE.txt`](LICENSE.txt).
 
-## License
+© 2026 Konstantin Gredeskoul.
 
-MIT. See `LICENSE.txt`.
+0

data/docs/badges/coverage_badge.svg

@@ -15,7 +15,7 @@
   <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
     <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
     <text x="31.5" y="14">coverage</text>
-    <text x="80" y="15" fill="#010101" fill-opacity=".3">95%</text>
-    <text x="80" y="14">95%</text>
+    <text x="80" y="15" fill="#010101" fill-opacity=".3">96%</text>
+    <text x="80" y="14">96%</text>
   </g>
 </svg>

data/examples/01_readme_example.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "inquirex"
+
+DEFINITION = Inquirex.define id: "tax-intake-2025", version: "1.0.0" do
+  meta title: "Tax Preparation Intake", subtitle: "Let's understand your situation"
+  start :filing_status
+
+  ask :filing_status do
+    type :enum
+    question "What is your filing status?"
+    options single: "Single", married_jointly: "Married Filing Jointly"
+    widget target: :desktop, type: :radio_group, columns: 2
+    widget target: :mobile,  type: :dropdown
+    transition to: :dependents
+  end
+
+  ask :dependents do
+    type :integer
+    question "How many dependents?"
+    default 0
+    transition to: :business_income
+  end
+
+  confirm :business_income do
+    question "Do you have business income?"
+    transition to: :business_count, if_rule: equals(:business_income, true)
+    transition to: :done
+  end
+
+  ask :business_count do
+    type :integer
+    question "How many businesses?"
+    transition to: :done
+  end
+
+  say :done do
+    text "Thanks for completing the intake."
+  end
+end
+
+engine = Inquirex::Engine.new(DEFINITION)
+
+engine.answer("single") # filing_status
+engine.answer(2)        # dependents
+engine.answer(false)    # business_income
+engine.advance          # done (display step)
+engine.finished?        # => true
+
+if __FILE__ == $0
+  require 'json'
+  puts JSON.pretty_generate(DEFINITION.to_h)
+end

data/examples/02_readme_mermaid.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+require_relative '01_readme_example'
+require 'inquirex'
+require 'stringio'
+
+output = StringIO.new
+exporter = Inquirex::Graph::MermaidExporter.new(DEFINITION)
+output << exporter.export
+
+source = <<~HTML
+  <html>
+    <head>
+      <meta charset="utf-8">
+    </head>
+    <body>
+    <meta charset="utf-8">
+    <div class="mermaid">
+      #{output.string}
+    </div>
+    <script type="module">
+      import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+      mermaid.initialize({ startOnLoad: true });
+    </script>
+  </html>
+HTML
+
+if __FILE__ == $0
+  File.write('mermaid.html', source)
+  system("open mermaid.html")
+  sleep 10
+
+  at_exit do
+    File.delete('mermaid.html')
+  end
+end

data/examples/03_send_email_actions.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 03: Post-completion actions building emails into the outbox.
+#
+# The `action` verb runs server-side after the flow finishes. send_email
+# builds Mail::Message objects — nothing is delivered here; a host Rails app
+# would iterate answers.outbox and deliver via its own ActionMailer config.
+#
+# Run:
+#   bundle exec ruby examples/03_send_email_actions.rb
+
+require "bundler/setup"
+require "inquirex"
+
+DEFINITION = Inquirex.define id: "lead-intake", version: "1.0.0" do
+  # Egress allowlist: webhook effects may only POST to these hosts.
+  allowed_domains "*.agentica.group"
+
+  meta title: "Lead Intake", subtitle: "Tell us about your project"
+  start :name
+
+  ask :name do
+    type :string
+    question "What is your name?"
+    transition to: :email
+  end
+
+  ask :email do
+    type :email
+    question "Where can we reach you? (leave blank to skip the receipt)"
+    transition to: :budget
+  end
+
+  ask :budget do
+    type :currency
+    question "What is your approximate budget?"
+  end
+
+  # Sent only when the visitor left an email address.
+  action :client_receipt, if: not_empty(:email) do
+    send_email to:      "{{email}}",
+      from:    "forms@agentica.group",
+      subject: "Thanks {{name}} — we got your inquiry",
+      text:    <<~TEXT,
+        Hi {{name}},
+
+        We received your answers and will reply within one business day.
+
+        {{answers_summary}}
+      TEXT
+      html:    <<~HTML
+        <p>Hi {{name}},</p>
+        <p>We received your answers and will reply within one business day.</p>
+        {{answers_summary}}
+      HTML
+  end
+
+  # Always notify the site owner, and demonstrate the Ruby escape hatch.
+  action :admin_alert do
+    send_email to: "owner@agentica.group",
+      from: "forms@agentica.group",
+      subject: "New lead: {{name}} (budget {{budget}})",
+      html: "{{answers_summary}}"
+    run { |answers, _outbox| puts ">> run{} saw budget: #{answers.budget}" }
+  end
+
+  # Webhook to an allowed_domains host. Gated by an always-false rule so this
+  # example runs offline — it records :skipped instead of POSTing. Drop the
+  # if: to exercise it for real.
+  action :crm_push, if: equals(:name, "__network_demo__") do
+    webhook url: "https://hooks.agentica.group/inquirex",
+      headers: { "X-Api-Key" => "demo" }
+  end
+end
+
+answers = Inquirex::Actions.run(
+  DEFINITION,
+  name:   "Ada Lovelace",
+  email:  "ada@lovelace.io",
+  budget: 12_500.00
+)
+
+puts "Built #{answers.outbox.size} message(s):"
+answers.outbox.each do |mail|
+  puts "-" * 60
+  puts "To:      #{mail.to.join(", ")}"
+  puts "Subject: #{mail.subject}"
+  puts "Parts:   #{mail.multipart? ? "text + html" : mail.content_type}"
+end
+
+puts "-" * 60
+puts "Results: #{answers.outbox.results.map { |r| "#{r.action_id}=#{r.status}" }.join(", ")}"
+
+# The definition (rules and all) round-trips through JSON — run{} is stripped:
+restored = Inquirex::Definition.from_json(DEFINITION.to_json)
+puts "Actions after JSON round-trip: #{restored.actions.map(&:id).inspect}"

data/examples/README.md

@@ -0,0 +1,33 @@
+# Examples
+
+This folder contains just a couple examples to demonstrate the API and the functionality.
+
+For a fuller list of more comprehensive examples, please see the [examples in the `inquirex-tty` gem](https://github.com/inquirex/inquirex-tty/tree/main/examples).
+
+## Running Examples
+
+These examples are meant to be run as executables from the root level of the gem folder.
+
+### First Example
+
+This example should print to stdout the DSL definition in JSON:
+
+```bash
+# First example — creates a DSL definition and prints it to stdout in JSON format
+./examples/01_readme_example.rb | jq
+```
+
+### Second Example
+
+This is a more interesting example. It builds on the first, takes that definition and uses the mermaid converter to write a tiny HTML file with a mermaid diagram inside, which represents the definition defined in the first file.
+
+```bash
+# creates a mermaid.html file at the root of the project
+# opens the browser with the file and waits 10 seconds
+# deletes the HTML file and exits
+./examples/02_readme_mermaid.rb
+```
+
+The mermaid file generated should look like this:
+
+<img src="02_readme_mermaid.png" width="300px" text-align="left"></img>

data/justfile

@@ -31,7 +31,9 @@ test *args:
 test-coverage *args:
     export ENVIRONMENT=test; export COVERAGE=true; {{ rbenv }} rspec {{ args }}
 
-check-all: lint test-coverage 
+ci: lint test-coverage 
+
+alias check-all := ci
 
 clean:
     #!/usr/bin/env bash
@@ -59,7 +61,6 @@ doc:
 publish: build
     {{ rbenv }} rake release[remote]
 
-
 # Tag v{{ version }}, publish the GH release, & refresh the Homebrew tap.
 release:
     git fetch --tags