inquirex 0.8.0 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae920c980bad7954d0f20a2973daa71998443c206d8e383382a0045404bbfd0c
-  data.tar.gz: 251356f0766dcab1a469cd2cfcdb71a20f4dcc4b9797f7fbcd5795c4d19533de
+  metadata.gz: a5f521bddfb7ad29c91aa0d99b19615ea43462739ba5da7b0a8ba4ce081fc411
+  data.tar.gz: 9096cdb056678b643213b17193b7228f984babce96f6bd04f22ce631542438f0
 SHA512:
-  metadata.gz: 4d87c1cdd2862ba816f3d593ff22b0ae9b57f2596e293e6974153bfc11cd499084ef3a8dc2fe58d877d073149514137bf9e87b0139e17afd682b497b7fb4c602
-  data.tar.gz: 71141f1d58413a3c5f03c90585ff4f845608cdd102a13fe3ac330b0c9d6e096b0ee8b393e92bbda9f77793ed6b76425f2750dbab02fbf845159bd19e620d1568
+  metadata.gz: 982bfd2e952d710be958ce3a2aba4fc0eccdcacfef4a0d761c6afae09e0a7a4fbfadce93e52ce22c736844cd659da58ec4dbdfb654fb7d6b2988783b885d7f5f
+  data.tar.gz: cf62d36c583af4fba6462ca8629187895d14a626ae157df99e5f6a58b0878a1c8b4b97152391dab61767b24449be77d36d0233badd7a17b54c037a3bf85fa1d6

data/README.md

@@ -11,7 +11,7 @@
 > - [`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.
+> - [`inquirex-widget`](https://github.com/inquirex/inquirex-js) (`npmjs` module [`inquirex-widget`](https://www.npmjs.com/package/inquirex-widget), formerly `@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 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).
 >
@@ -51,6 +51,8 @@ This one is the core gem in the Inquirex ecosystem that focuses on:
 
 - JSON round-trip serialization for cross-platform clients
 
+- Declarative completion emails (`send_email` DSL verb — templates the host application delivers)
+
 - A structured `Answers` wrapper and Mermaid graph export (provided by `inquirex-tty` gem's CLI)
 
 - In short:
@@ -86,7 +88,7 @@ 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.
+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 [inquirex-widget](https://www.npmjs.com/package/inquirex-widget) npmjs package.
 
 ## Quick Start
 
@@ -147,6 +149,7 @@ engine.finished? # => true
 - `start :step_id` sets the entry step
 - `meta title:, subtitle:, brand:, theme:` adds optional frontend metadata (see [Theme](#theme-and-branding))
 - `accumulator :name, type:, default:` declares a running total (see [Accumulators](#accumulators))
+- `send_email [if: rule] do ... end` declares a completion email the host application delivers (see [Completion Emails](#completion-emails-send_email))
 
 ### Step verbs
 
@@ -302,6 +305,41 @@ end
 
 A single step can contribute to any number of accumulators.
 
+### Text accumulators: the session transcript
+
+An accumulator declared `type: :text` accumulates prose instead of a running total, and — unlike every other kind — nothing declares `accumulate` into it. The engine fills it in on its own:
+
+```ruby
+Inquirex.define id: "depreciation-help" do
+  accumulator :transcript, type: :text
+  start :intro
+
+  say(:intro) { text "Depreciation spreads an asset's cost over its useful life."; transition to: :asset_kind }
+  ask :asset_kind do
+    type :enum
+    question "What kind of asset?"
+    options vehicle: "A vehicle", building: "A building"
+  end
+end
+```
+
+After the user advances past `:intro` and answers `:asset_kind`:
+
+```ruby
+engine.text(:transcript)
+# => "Depreciation spreads an asset's cost over its useful life.\n\nQ: What kind of asset?\nA: A vehicle"
+```
+
+Three things it deliberately does:
+
+- **Records only what was shown.** A step elided by `skip_if`, or a question auto-skipped because an extraction already answered it, was never on screen and never appears. The narrative is a record of the session, not of the graph.
+- **Renders answers as the user saw them.** Option values resolve to their labels, so it reads `A: Married filing jointly`, not `A: married_filing_jointly`. Booleans read `Yes`/`No`.
+- **Starts at `""`, not `0`.** `default:` is optional and defaults to the type's own zero.
+
+This exists because a flow that mostly *tells* the user things — a help flow, an explainer — collects almost no answers, so the answers hash says nothing about what the session contained. The transcript does, which is what makes such a flow summarizable. It is what [`inquirex-llm`](https://github.com/inquirex/inquirex-llm)'s `summarize` verb reads; a flow carrying a `summarize` step gets a `:transcript` accumulator automatically if it has not declared one.
+
+Read one with `engine.text(:name)`, or all of them with `engine.texts`.
+
 ### The `price` sugar
 
 Since `:price` is the most common use case (lead qualification, tax prep, SaaS quotes), there's a one-liner:
@@ -498,7 +536,7 @@ Guard rails:
 - `skip` on a **display** step raises `Errors::NonCollectingStepError` (use `advance`)
 - `skip` after the flow finished raises `Errors::AlreadyFinishedError`
 
-The `skipped` list survives `to_state` / `.from_state` round-trips (string keys from JSON are normalized back to symbols), and `engine.answers_with_metadata` merges it into the answers under `:skipped` — so post-completion actions (webhook payloads, email templates) and API consumers see which values were defaults-by-skip.
+The `skipped` list survives `to_state` / `.from_state` round-trips (string keys from JSON are normalized back to symbols), and `engine.answers_with_metadata` merges it into the answers under `:skipped` — so completion email templates and API consumers see which values were defaults-by-skip.
 
 On the wire, step JSON carries `"required": false` (omitted when true, like other defaults):
 
@@ -535,58 +573,47 @@ engine.after_completion do |eng|
 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}}`.
+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 completion email templates: `{{completion_metadata.engine}}` interpolates like any other field.
 
-## Post-Completion Actions
+## Completion Emails (`send_email`)
 
-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.
+A flow may declare emails to be sent after all questions are answered. `send_email` is a top-level DSL verb and a **declaration, not an action**: it serializes into the definition JSON under `"send_emails"`, and the host application (e.g. [qualified.at](https://qualified.at)) decides when and how to deliver. This is the only completion declaration the core DSL carries — richer post-completion behavior (webhooks, CRM pushes, custom code) belongs to the host application, not to the flow definition.
 
 ```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
+  # Sent only when the visitor left an email address.
+  send_email if: not_empty(:email) do
+    to      "{{email}}"
+    from    "forms@agentica.group"
+    subject "Thanks {{name}} — we received your intake"
+    markdown_text <<~TEXT
+      Hi {{name}},
 
-  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
+      We received your answers and will reply within one business day.
 
-  action :crm_push do
-    webhook url: "https://hooks.agentica.group/inquirex",
-            headers: { "X-Api-Key" => "..." }
+      {{answers_summary}}
+    TEXT
   end
+
+  # Inline keyword form works too:
+  send_email to: "owner@agentica.group", from: "forms@agentica.group",
+             subject: "New lead: {{name}} <{{email}}>",
+             html: "{{answers_summary}}"
 end
 ```
 
-Execution and delivery:
+Selecting and building on the host:
 
 ```ruby
-answers = Inquirex::Actions.run(definition, engine.answers)
-answers.outbox.messages   # => [Mail::Message, ...]
-answers.outbox.results    # => per-action :ok / :skipped / :failed trail
+definition.send_emails    # => [Inquirex::SendEmail, ...] in declaration order
+
+applicable = definition.send_emails.select { |email| email.applicable?(engine.answers) }
 
-# In a Rails host:
-answers.outbox.each do |message|
+# Optional convenience: build Mail::Message objects (what ActionMailer wraps).
+applicable.each do |declaration|
+  message = declaration.to_mail(Inquirex::Answers.new(engine.answers))
   ActionMailer::Base.wrap_delivery_behavior(message)  # adopt Rails delivery config
   message.deliver
 end
@@ -594,14 +621,13 @@ 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.
+- **Nothing is delivered by the gem.** A `SendEmail` is data: templated header fields (`to`, `from`, `cc`, `bcc`, `reply_to`, `subject`, `headers`) plus body templates. `#to_mail` is a pure convenience for Ruby hosts.
+- **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. The built-in `{{answers_summary}}` expands to all collected answers.
+- **Bodies**: `text:` renders verbatim; `html:` HTML-escapes every interpolated value automatically; `markdown_text:` is carried as Markdown on the wire — the core gem never renders Markdown to HTML (zero dependencies), hosts render it themselves. At least one body is required. In `#to_mail`, `text` (falling back to `markdown_text`) forms the plain-text part and `html` the HTML part.
+- **`if:` gates** reuse the serializable rule AST (`not_empty(:email)`, ...) and survive the JSON round-trip; hosts filter with `#applicable?(answers_hash)`.
+- Bodies accept `{ file: "path" }`, read **once at definition time** and inlined — a definition rehydrated from JSON never touches the filesystem.
 - **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.
+- The `mail` gem is a soft dependency, needed only when `#to_mail` is called (Rails hosts already have it via ActionMailer).
 
 ## Serialization
 
@@ -620,8 +646,7 @@ 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
+- Completion email declarations (`send_emails`) with their `if:` gate rules and body templates (`text`, `markdown_text`, `html`); the key is omitted when no emails are declared
 
 Important serialization details:
 
@@ -631,6 +656,47 @@ Important serialization details:
 - `required: false` step flag is preserved (omitted when true, the default)
 - Snake-case theme keys are converted to camelCase on serialization to match the JS widget contract
 
+## Loading Flows from Source (`load_dsl`)
+
+`Inquirex.load_dsl` evaluates a string of DSL and returns the `Definition`:
+
+```ruby
+definition = Inquirex.load_dsl(File.read("flow.rb"))
+```
+
+An `eval` is fine for a file in your own repository. It is not fine for a string that came from anywhere else — a column a customer edits, an upload, an LLM, a visual builder's "sync" button. Evaluating that unguarded is arbitrary code execution in the process that loads the flow.
+
+**Since 0.7.0, `load_dsl` validates before it evaluates.** Source is parsed with Prism and walked against `Inquirex::SafeSource::Vocabulary`, a **default-deny** allowlist of the real DSL: a word nobody declared is a violation, not an oversight. Only source that matches the vocabulary with literal arguments gets past it.
+
+```ruby
+Inquirex.load_dsl(customer.flow_dsl)                       # validates, then evaluates
+Inquirex.load_dsl(File.read("flow.rb"), unsafe: true)      # your own file: skip validation
+```
+
+Audit stored definitions without loading them — the answer is "would `load_dsl` accept this?", which is what you want before a deploy tightens the allowlist:
+
+```ruby
+Qualifier.find_each do |q|
+  violations = Inquirex::SafeSource.validate(q.flow_dsl)
+  puts "REJECT #{q.id}: #{violations.join("; ")}" if violations.any?
+end
+
+Inquirex::SafeSource.safe?(source)   # => true / false
+```
+
+Two ceilings bound the work handed to the parser, both adjustable:
+
+```ruby
+Inquirex::SafeSource.max_source_bytes = 256 * 1024   # default 64 KiB
+Inquirex::SafeSource.max_depth = 32                  # default 24
+```
+
+### What this means for existing flows
+
+This is the one change most likely to surprise you: **DSL that evaluated in 0.6.x can be rejected in 0.7.0+.** A flow using a construct outside the vocabulary — a top-level constant, a helper method, a computed value — now fails to load rather than silently running. That is the intended behaviour, but it is a real break; run `SafeSource.validate` over your stored flows before upgrading.
+
+Downstream gems extend the vocabulary at boot rather than forking it, so `require "inquirex-llm"` teaches it `extract`, `clarify`, and `summarize` automatically.
+
 ## Answers Wrapper
 
 `Inquirex::Answers` provides structured answer access:
@@ -674,6 +740,7 @@ Common exceptions under `Inquirex::Errors`:
 - `ValidationError`
 - `NonCollectingStepError`
 - `RequiredStepError`
+- `SendEmailError`
 
 ## Development
 

data/lib/inquirex/accumulator.rb

@@ -5,9 +5,18 @@ module Inquirex
   # flows accumulate into as the user answers questions. Pure data, serializable
   # to JSON, evaluated identically on Ruby and JS sides.
   #
+  # A `:text` accumulator is different in kind: nothing declares `accumulate`
+  # into it, and no Accumulation ever targets it. The Engine appends to it
+  # automatically as the user moves through the flow — every display step's
+  # text, and every question with the answer given to it. That running
+  # narrative is what an LLM `summarize` step reads, and it is the only way a
+  # flow that mostly *tells* the user things (a help or explainer flow) has
+  # anything to summarize at all: such a flow collects few answers, so the
+  # answers hash alone says nothing about what the user was shown.
+  #
   # @attr_reader name [Symbol] accumulator identifier (e.g. :price)
-  # @attr_reader type [Symbol] one of Node::TYPES (typically :currency, :integer, :decimal)
-  # @attr_reader default [Numeric] starting value (default: 0)
+  # @attr_reader type [Symbol] one of Node::TYPES (typically :currency, :integer, :decimal, :text)
+  # @attr_reader default [Numeric, String] starting value (0, or "" when :text)
   #
   # @example Declare a running price total and contribute to it from a step
   #   Inquirex.define do
@@ -17,19 +26,40 @@ module Inquirex
   #       accumulate :price, per_unit: 50
   #     end
   #   end
+  #
+  # @example Declare a transcript the engine fills in on its own
+  #   Inquirex.define do
+  #     accumulator :transcript, type: :text
+  #     say(:intro) { text "Here is how depreciation works." }
+  #   end
+  #   # engine.advance
+  #   # engine.text(:transcript)  # => "Here is how depreciation works."
   class Accumulator
+    # The accumulator type whose running value is appended prose rather than
+    # a running total. See the class docs for why it exists.
+    TEXT_TYPE = :text
+
     attr_reader :name, :type, :default
 
     # @param name [Symbol, String] accumulator identifier
     # @param type [Symbol, String] value type, one of Node::TYPES
-    # @param default [Numeric] starting value before any contributions
-    def initialize(name:, type: :decimal, default: 0)
+    # @param default [Numeric, String, nil] starting value before any
+    #   contributions; nil selects the type's own zero ("" for :text, else 0)
+    def initialize(name:, type: :decimal, default: nil)
       @name = name.to_sym
       @type = type.to_sym
-      @default = default
+      @default = default.nil? ? zero_value : default
       freeze
     end
 
+    # Whether this accumulator accumulates prose rather than a running total.
+    # Text accumulators are filled by the Engine, never by an Accumulation.
+    #
+    # @return [Boolean]
+    def text?
+      @type == TEXT_TYPE
+    end
+
     # Serializes the accumulator to its wire format. The name is omitted —
     # Definition#to_h keys the accumulators map by name.
     #
@@ -44,12 +74,24 @@ module Inquirex
     # @param hash [Hash] type/default attributes (string or symbol keys)
     # @return [Accumulator]
     def self.from_h(name, hash)
+      # `fetch`, not `||` — a text accumulator's serialized default is "",
+      # which `||` would discard in favour of the numeric zero.
+      default = hash.fetch("default") { hash.fetch(:default, nil) }
       new(
         name:    name,
         type:    hash["type"] || hash[:type] || :decimal,
-        default: hash["default"] || hash[:default] || 0
+        default: default
       )
     end
+
+    private
+
+    # The starting value implied by the type when none was declared.
+    #
+    # @return [Numeric, String]
+    def zero_value
+      text? ? "" : 0
+    end
   end
 
   # Per-step declaration of how a single answer contributes to one accumulator.

data/lib/inquirex/answers.rb

@@ -90,16 +90,6 @@ module Inquirex
       @data.size
     end
 
-    # Mail::Message objects (and result trail) built by post-completion
-    # actions. Deliberately excluded from #to_h, #to_flat_h, #to_json and
-    # #== — the outbox rides alongside the answer data, never inside it.
-    # Delivery is the host application's responsibility.
-    #
-    # @return [Actions::Outbox]
-    def outbox
-      @outbox ||= Actions::Outbox.new
-    end
-
     # Merge another hash or Answers into this one (returns new Answers instance).
     #
     # @param other [Hash, Answers]

data/lib/inquirex/definition.rb

@@ -19,8 +19,7 @@ module Inquirex
       :start_step_id,
       :steps,
       :accumulators,
-      :actions,
-      :allowed_domains
+      :send_emails
 
     # @param start_step_id [Symbol] id of the initial step
     # @param nodes [Hash<Symbol, Node>] all steps keyed by id
@@ -28,20 +27,18 @@ module Inquirex
     # @param version [String] semver
     # @param meta [Hash] frontend metadata
     # @param accumulators [Hash<Symbol, Accumulator>] named running totals
-    # @param actions [Array<Actions::Action>] post-completion actions, in order
-    # @param allowed_domains [Array<String>] hosts outbound effects (webhook)
-    #   may send answers to; "example.com" exact, "*.example.com" subdomains
+    # @param send_emails [Array<SendEmail>] emails the host application builds
+    #   after completion, in declaration order
     # @raise [Errors::DefinitionError] if start_step_id is not present in nodes
     def initialize(start_step_id:, nodes:, id: nil, version: "1.0.0", meta: {},
-      accumulators: {}, actions: [], allowed_domains: [])
+      accumulators: {}, send_emails: [])
       @id = id
       @version = version
       @meta = meta.freeze
       @start_step_id = start_step_id.to_sym
       @steps = nodes.freeze
       @accumulators = accumulators.freeze
-      @actions = actions.freeze
-      @allowed_domains = normalize_domains(allowed_domains)
+      @send_emails = send_emails.freeze
       validate!
       freeze
     end
@@ -63,25 +60,6 @@ module Inquirex
       @steps.keys
     end
 
-    # Whether a host is covered by the allowed_domains declaration.
-    # "example.com" matches that host exactly; "*.example.com" matches any
-    # subdomain but not the apex. Matching is case-insensitive; an empty
-    # allowlist allows nothing.
-    #
-    # @example With allowed_domains ["*.example.com"]
-    #   definition.allowed_host?("api.example.com") # => true
-    #   definition.allowed_host?("API.EXAMPLE.COM") # => true (case-insensitive)
-    #   definition.allowed_host?("example.com")     # => false (wildcard excludes the apex)
-    #
-    # @param host [String]
-    # @return [Boolean]
-    def allowed_host?(host)
-      target = host.to_s.downcase
-      @allowed_domains.any? do |entry|
-        entry.start_with?("*.") ? target.end_with?(entry[1..]) : target == entry
-      end
-    end
-
     # Serializes the definition to a JSON string.
     # Lambdas (default procs, compute blocks) are silently stripped.
     #
@@ -98,7 +76,6 @@ module Inquirex
       hash["id"] = @id if @id
       hash["version"] = @version
       hash["meta"] = @meta unless @meta.empty?
-      hash["allowed_domains"] = @allowed_domains unless @allowed_domains.empty?
       hash["start"] = @start_step_id.to_s
       unless @accumulators.empty?
         hash["accumulators"] = @accumulators.each_with_object({}) do |(name, acc), h|
@@ -106,8 +83,7 @@ module Inquirex
         end
       end
       hash["steps"] = @steps.transform_keys(&:to_s).transform_values(&:to_h)
-      serializable_actions = @actions.select(&:serializable?)
-      hash["actions"] = serializable_actions.map(&:to_h) unless serializable_actions.empty?
+      hash["send_emails"] = @send_emails.map(&:to_h) unless @send_emails.empty?
       hash
     end
 
@@ -132,8 +108,7 @@ module Inquirex
       start = hash["start"] || hash[:start]
       steps_data = hash["steps"] || hash[:steps] || {}
       acc_data = hash["accumulators"] || hash[:accumulators] || {}
-      actions_data = hash["actions"] || hash[:actions] || []
-      domains = hash["allowed_domains"] || hash[:allowed_domains] || []
+      emails_data = hash["send_emails"] || hash[:send_emails] || []
 
       nodes = steps_data.each_with_object({}) do |(step_id, step_hash), acc|
         sym_id = step_id.to_sym
@@ -145,7 +120,7 @@ module Inquirex
         h[sym] = Accumulator.from_h(sym, entry)
       end
 
-      actions = actions_data.map { |entry| Actions::Action.from_h(entry) }
+      send_emails = emails_data.map { |entry| SendEmail.from_h(entry) }
 
       new(start_step_id: start,
         nodes:,
@@ -153,32 +128,15 @@ module Inquirex
         version:,
         meta:,
         accumulators:,
-        actions:,
-        allowed_domains: domains)
+        send_emails:)
     end
 
     private
 
     def validate!
-      unless @steps.key?(@start_step_id)
-        raise Errors::DefinitionError, "Start step #{@start_step_id.inspect} not found in steps"
-      end
+      return if @steps.key?(@start_step_id)
 
-      @actions.each do |action|
-        action.effects.each { |effect| effect.validate_against(self) }
-      end
-    end
-
-    def normalize_domains(domains)
-      domains.map do |entry|
-        domain = entry.to_s.strip.downcase
-        if domain.empty? || domain == "*" || domain.match?(%r{[/\s:@]})
-          raise Errors::DefinitionError,
-            "allowed_domains entries must be bare domains like \"example.com\" " \
-            "or \"*.example.com\", got #{entry.inspect}"
-        end
-        domain
-      end.freeze
+      raise Errors::DefinitionError, "Start step #{@start_step_id.inspect} not found in steps"
     end
   end
 end

data/lib/inquirex/dsl/flow_builder.rb

@@ -16,28 +16,24 @@ module Inquirex
         @nodes = {}
         @meta = {}
         @accumulators = {}
-        @actions = []
-        @allowed_domains = []
-      end
-
-      # Declares the domains outbound effects (webhook) may send answers to.
-      # Conventionally the first declaration in a definition, so the flow's
-      # egress surface is auditable at a glance. "example.com" matches that
-      # host exactly; "*.example.com" matches its subdomains.
-      #
-      # @param domains [Array<String>]
-      def allowed_domains(*domains)
-        @allowed_domains.concat(domains.flatten)
+        @send_emails = []
       end
 
       # Declares a named running total the flow accumulates into as answers come in.
       # The `:price` accumulator is the common lead-qualification use case; others
       # (e.g. :complexity, :credit_score) work identically.
       #
-      # @param name [Symbol] e.g. :price
+      # A `:text` accumulator is filled by the engine rather than by
+      # `accumulate` declarations: it collects everything the user was shown
+      # and every answer they gave, which is what an LLM `summarize` step
+      # reads. See {Accumulator}.
+      #
+      # @param name [Symbol] e.g. :price, :transcript
       # @param type [Symbol] one of Node::TYPES (default :currency-ish: :decimal)
-      # @param default [Numeric] starting value (default: 0)
-      def accumulator(name, type: :decimal, default: 0)
+      # @param default [Numeric, String, nil] starting value; nil (the default)
+      #   takes the type's own zero, so a :text accumulator starts at "" and
+      #   every other kind starts at 0
+      def accumulator(name, type: :decimal, default: nil)
         sym = name.to_sym
         @accumulators[sym] = Accumulator.new(name: sym, type:, default:)
       end
@@ -116,33 +112,45 @@ module Inquirex
         add_step(id, :confirm, &)
       end
 
-      # Declares a named post-completion action: effects (send_email, run, ...)
-      # executed server-side after the flow finishes, with the collected
-      # answers. Runs in declaration order; gate with a serializable rule via
-      # the if: option.
+      # Declares an email the host application builds and delivers after the
+      # flow finishes, from the collected answers. Declarations run in order;
+      # gate with a serializable rule via the if: option. This is the only
+      # completion declaration the core DSL carries — richer post-completion
+      # behavior belongs to the host application.
+      #
+      # @example Receipt sent only when the visitor left an email address
+      #   send_email if: not_empty(:email) do
+      #     to      "{{email}}"
+      #     from    "forms@agentica.group"
+      #     subject "Thanks {{name}} — we got your inquiry"
+      #     markdown_text <<~TEXT
+      #       Hi {{name}},
       #
-      # @example Email the collected answers when business income was selected
-      #   action :notify_sales, if: Rules::Contains.new(:income_types, "Business") do
-      #     send_email to: "sales@example.com",
-      #                subject: "New lead: {{name}}",
-      #                html: "{{answers_summary}}"
+      #       We received your answers and will reply within one business day.
+      #
+      #       {{answers_summary}}
+      #     TEXT
       #   end
       #
-      # @param id [Symbol] action identifier
-      # @param opts [Hash] only if: is recognized — a Rules::Base gate
-      # @yield block evaluated in ActionBuilder (send_email, run, ...)
-      def action(id, **opts, &block)
+      # @param opts [Hash] if: takes a Rules::Base gate; any remaining keys are
+      #   SendEmail fields (to:, subject:, text:, ...) for the inline form
+      # @yield block evaluated in SendEmailBuilder (to, from, subject, ...);
+      #   block values override same-named inline keys
+      # @return [void]
+      # @raise [Errors::DefinitionError] on unknown fields or missing to:/subject:/body
+      def send_email(**opts, &block)
         rule = opts.delete(:if)
-        raise Errors::DefinitionError, "Unknown action options: #{opts.keys.inspect}" unless opts.empty?
-
-        sym = id.to_sym
-        if @actions.any? { |a| a.id == sym }
-          raise Errors::DefinitionError, "Duplicate action id: #{sym.inspect}"
+        params = opts
+        if block
+          builder = SendEmailBuilder.new
+          builder.instance_eval(&block)
+          params = params.merge(builder.params)
+        end
+        begin
+          @send_emails << SendEmail.new(**params, rule:)
+        rescue ArgumentError => e
+          raise Errors::DefinitionError, "send_email: #{e.message}"
         end
-
-        builder = ActionBuilder.new
-        builder.instance_eval(&block) if block
-        @actions << builder.build(sym, rule:)
       end
 
       # Produces the frozen Definition.
@@ -154,14 +162,13 @@ module Inquirex
         raise Errors::DefinitionError, "No steps defined" if @nodes.empty?
 
         Definition.new(
-          start_step_id:   @start_step_id,
-          nodes:           @nodes,
-          id:              @flow_id,
-          version:         @flow_version,
-          meta:            @meta,
-          accumulators:    @accumulators,
-          actions:         @actions,
-          allowed_domains: @allowed_domains
+          start_step_id: @start_step_id,
+          nodes:         @nodes,
+          id:            @flow_id,
+          version:       @flow_version,
+          meta:          @meta,
+          accumulators:  @accumulators,
+          send_emails:   @send_emails
         )
       end