nexo_ai 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8815820e94035d1d5c68defa4e862111c95572852098b735e885eaf98b6a3407
-  data.tar.gz: 57ca3d98c0d1acd6877276e9322715a7e003928b2da258866b1e7ccabcf33b29
+  metadata.gz: 6739e4be2c75c08ffb553133324b96b29d13e0212e21cc23c4cd6287316b3249
+  data.tar.gz: d051ce3a0916cd5fb9328df9b893e5aad15b6f60c8d5c23bb9be8b3126da7285
 SHA512:
-  metadata.gz: 8ad1a55220bcddd2ea1e2d06ea2bc2c680ae4f2a52c1cd8f24e0942f66ad38e38c6b1dc992fcc766b720400083bb07b500feaae9285fbb671e203bfa3f46e0f4
-  data.tar.gz: cea3ce8167dae3b4e44a5d87c84e42f04a333c7cd7e5aae8ad236133b821ba10fd3688e63851035d2c1b494b9c533807fa29bfbfd1c3439ed8c8ce6473fe1e52
+  metadata.gz: 94c1df2b9d56ab1c31aacd79a52473bf6ed3da9ba43d2e7403658fdee0e52bc31bded23181dbe7f60e82b4fd9b0f5e64c5d933de80cf99f546ca0982b883d878
+  data.tar.gz: ca8829f2003854bd1c24e2e77739b0b4c62bd173ee0bd31297171ba017f2c1a02dd31f6fb9bb7ef938fc1c67a93229c407f5fbae06b29c4aee305552f6eba242

data/.rdoc_options

@@ -0,0 +1,5 @@
+# RDoc configuration for `rdoc`, `gem rdoc`, and rubydoc.info. All comments in
+# lib/ and the docs/ guides are written in Markdown, not RDoc markup.
+markup: markdown
+main_page: README.md
+title: nexo_ai

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 ## [Unreleased]
 
+## [0.12.0] - 2026-09-12
+
+The gem now says exactly which ruby_llm it supports, and its API docs are written in Markdown.
+
+### Changed
+
+- **`ruby_llm` is now pinned to the 1.16 line (`~> 1.16`, was `>= 1.16`).** The supported
+  version is 1.16.0 — every composed API was verified against it. The upcoming ruby_llm 2.0
+  is not supported yet, and the pessimistic constraint keeps it from being resolved in.
+- **API documentation is written in Markdown.** RDoc now runs with `markup: markdown`
+  (`.rdoc_options` + the `rake doc` task), and every doc comment under `lib/` was converted
+  from RDoc markup — backtick code spans, `##` headings, fenced code samples. Guides link the
+  `examples/` files by GitHub URL so the links work on rubydoc.info as well as on GitHub.
+
+## [0.11.0] - 2026-08-20
+
+An agent's tool schema now tells the truth about what it may do.
+
+### Changed
+
+- **An agent no longer advertises a tool its permission mode can never authorize.**
+  Tool attach was gated on the sandbox (`Sandbox#supports?`) but not on the gate, so a
+  `:read_only` agent — the default — put `WriteFile` and `Shell` in its schema on every
+  turn even though `#authorize!` was guaranteed to deny them. The same held for `Fetch`
+  and `WebSearch`, which were gated on `fetch_allow` / `search_backend` being declared
+  but not on the capability being permitted. Models do try these tools, and each attempt
+  costs a full round trip.
+
+  `Agent#chat`, `#apply_fetch` and `#apply_search` now also consult
+  `Permissions#never_allows?`. Only `:read_only` is decidable ahead of time; `:auto`,
+  `:ask` and `:approve` decide per call and still attach — `:approve` in particular must
+  reach the gate so it can raise `ApprovalRequired` and suspend the run.
+
+  This is a cost and description-accuracy measure, **not** a security change:
+  `#authorize!` remains the boundary and still denies at call time.
+
+  **Upgrading:** an agent that is supposed to write, shell out, fetch or search needs the
+  capability in `allow:` (or a non-`:read_only` mode). If it does not have it today the
+  tool was already failing on every call — the tool now disappears from the schema instead
+  of erroring. Note that `fetch_allow` scopes hosts and `search_backend` names a backend;
+  neither is a capability grant.
+
+### Added
+
+- `Nexo::Permissions#never_allows?(capability)` — true when a capability can never be
+  authorized for this gate, for any call. Derived from the new `Permissions::PRIVILEGED`
+  constant, which `#authorize!` also reads, so the predicate cannot drift from the gate.
+
 ## [0.10.0] - 2026-08-20
 
 Durable workflows without a database.

data/README.md

@@ -94,7 +94,8 @@ access until you explicitly opt in.
 ## Requirements
 
 - Ruby 3.3+
-- [ruby_llm](https://github.com/crmne/ruby_llm) >= 1.16
+- [ruby_llm](https://github.com/crmne/ruby_llm) 1.16.x (`~> 1.16`) — the supported version is
+  **1.16.0**; the upcoming ruby_llm 2.0 is not supported yet
 - [ruby_llm-skills](https://github.com/kieranklaassen/ruby_llm-skills) — optional, only
   when you use the `skills` macro
 - [ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp) — optional, only when you attach

data/Rakefile

@@ -31,7 +31,12 @@ RDoc::Task.new(:doc) do |rd|
   # are not part of the gem's Ruby API, so they belong in neither the generated
   # API site nor the coverage denominator.
   rd.rdoc_files.exclude("lib/generators/**/templates/*.rb")
+  # Local planning notes (gitignored) that happen to live under docs/.
+  rd.rdoc_files.exclude("docs/SITE_DOCS_PLAN.md")
   rd.rdoc_dir = "doc"
+  # Every comment in lib/ (and the docs/ guides) is Markdown, not RDoc markup.
+  # Mirrors `.rdoc_options`, which `gem rdoc`/rubydoc.info read instead of this task.
+  rd.markup = "markdown"
 end
 
 # NOTE: `default` intentionally stays test + standard — `rake doc`/`doc:coverage`

data/docs/durable-workflows.md

@@ -61,7 +61,7 @@ run:
 DocumentApproval.resume_later(run.id, { approved: true }, queue: :nexo)
 ```
 
-See [`examples/approval_workflow.rb`](../examples/approval_workflow.rb) for the full
+See [`examples/approval_workflow.rb`](https://github.com/maquina-app/nexo/blob/main/examples/approval_workflow.rb) for the full
 offline flow (`ruby -Ilib examples/approval_workflow.rb`).
 
 ## Parallel checkpoints — `checkpoint_all`
@@ -187,7 +187,7 @@ resumed.status                                 # => "done" (the gate allowed the
   `ruby_llm` swallows tool exceptions, tool-triggered approval would be constrained — a
   genuine upstream dependency, stated plainly.
 
-See [`examples/approval_agent.rb`](../examples/approval_agent.rb) for the live flow
+See [`examples/approval_agent.rb`](https://github.com/maquina-app/nexo/blob/main/examples/approval_agent.rb) for the live flow
 (`NEXO_LIVE=1 NEXO_MODEL=… ruby -Ilib examples/approval_agent.rb`).
 
 The `state` column ships with fresh installs. Apps installed before this feature

data/docs/getting-started.md

@@ -97,7 +97,7 @@ Both are class macros with the same reader/writer convention as `model`. `provid
 is passed straight through to `RubyLLM.chat`; `assume_model_exists` defaults to
 `false` (registry validation on). Setting `assume_model_exists` **without** a
 `provider` raises `Nexo::ConfigurationError` — `ruby_llm` can't infer a provider once
-the lookup is skipped. See [`examples/code_reviewer.rb`](../examples/code_reviewer.rb)
+the lookup is skipped. See [`examples/code_reviewer.rb`](https://github.com/maquina-app/nexo/blob/main/examples/code_reviewer.rb)
 for a runnable Ollama example.
 
 ← Back to the [README](../README.md)

data/docs/loops.md

@@ -63,7 +63,8 @@ proven.
 
 ## Verified vs assumed
 
-Built against **`ruby_llm` 1.16** and **`ruby_llm-test` 0.2**. The tool body method is
+Built against **`ruby_llm` 1.16.0** (the supported line — the gemspec pins `~> 1.16`, and the
+upcoming `ruby_llm` 2.0 is not supported yet) and **`ruby_llm-test` 0.2**. The tool body method is
 `#execute`, tools attach with `chat.with_tools(*instances)`, and instructions set with
 `chat.with_instructions`. `Open3.capture3` has no `timeout:` keyword on the target Ruby, so
 `Local#shell` bounds the command with `Timeout.timeout`. These may differ on other

data/docs/permissions.md

@@ -8,7 +8,7 @@ and the agent loop continues — it does not raise. A path that escapes the work
 
 |                          | `:read` | `:glob` | `:write`            | `:shell`                          | `:fetch`   | `:search`  |
 | ------------------------ | ------- | ------- | ------------------- | --------------------------------- | ---------- | ---------- |
-| `:read_only` (default)   | ✅      | ✅      | ❌ `{error}`        | ❌ `{error}`                      | ❌ `{error}` | ❌ `{error}` |
+| `:read_only` (default)   | ✅      | ✅      | ❌ not attached ‡   | ❌ not attached ‡                 | ❌ not attached ‡ | ❌ not attached ‡ |
 | `:auto`                  | ✅      | ✅      | ✅                  | ✅                                | ✅         | ✅         |
 | `:ask`                   | ✅      | ✅      | per `on_ask`        | per `on_ask`                      | per `on_ask` | per `on_ask` |
 | `:approve`               | ✅      | ✅      | per `decision`      | per `decision`                    | per `decision` | per `decision` |
@@ -18,7 +18,22 @@ and the agent loop continues — it does not raise. A path that escapes the work
 
 `:read`/`:glob` are auto-allowed under **every** mode (they sit in the default
 `allow` list), so `:ask`/`:approve` never prompt for them — only
-`:write`/`:shell`/`:fetch`/`:search` reach the gate. **†** `:fetch` and `:search`
+`:write`/`:shell`/`:fetch`/`:search` reach the gate.
+
+**‡** Under `:read_only` these four capabilities can *never* be authorized, so their tools are
+not attached at all — the model never sees `WriteFile`, `Shell`, `Fetch` or `WebSearch` in its
+schema. Anything named in `allow:` is exempt and attaches normally, and `:auto`/`:ask`/`:approve`
+always attach because they decide per call. Leaving a guaranteed failure in the schema is not
+free: a model that reads the schema tries the tool, and each attempt costs a full round trip.
+`Permissions#never_allows?` is the predicate, and it is derived from the same `PRIVILEGED` list
+`#authorize!` uses so the two cannot disagree. This is a cost and description-accuracy measure,
+**not** a security boundary — `#authorize!` is still the gate and still denies at call time.
+
+Note that declaring `fetch_allow` or a `search_backend` is *not* a capability grant: `fetch_allow`
+scopes which hosts are reachable, and both still need `:fetch` / `:search` permitted before the
+tool is attached.
+
+**†** `:fetch` and `:search`
 run in the **host process** (stdlib `net/http` / a host-injected backend), so **no
 sandbox constrains them** — not even a `--network none` container. They are bounded
 only by the capability gate above plus `fetch_allow` / the injected backend.

data/docs/rails.md

@@ -156,7 +156,7 @@ run.artifact("digest.md")          # => {"name" =>, "content" =>, "at" =>} or ni
 run.artifact_content("digest.md")  # => "…the body…" or nil
 ```
 
-See [`examples/rails_usage.md`](../examples/rails_usage.md) for a controller +
+See [`examples/rails_usage.md`](https://github.com/maquina-app/nexo/blob/main/examples/rails_usage.md) for a controller +
 Turbo-page walkthrough.
 
 ← Back to the [README](../README.md)

data/docs/sandboxes.md

@@ -54,10 +54,19 @@ scope; none widens authority silently.
   instructions → sandbox instructions → skill instructions**. Provider-neutral, injected through
   the existing `with_instructions` path.
 
-- **Capability-gated tool attach (`Sandbox#supports?`).** A `:virtual` agent no longer advertises
-  a `Shell` tool it can never run — `Agent#chat` attaches `Shell` only when
-  `@sandbox.supports?(:shell)`. `Local`/`Container` support all four capabilities; `Virtual`
-  supports everything but `:shell`. `ReadFile`/`WriteFile`/`Glob` are always attached.
+- **Gated tool attach, on two axes.** An agent does not advertise a tool it could never
+  successfully call, because a guaranteed failure in the schema costs a round trip every time a
+  model tries it. `Agent#chat` attaches a tool only when **both** hold:
+
+  1. *The sandbox supports the capability* (`Sandbox#supports?`). `Local`/`Container` support all
+     four; `Virtual` supports everything but `:shell`, so a `:virtual` agent has no `Shell`.
+  2. *The permission gate does not deny it statically* (`Permissions#never_allows?`). Under
+     `:read_only`, `:write` and `:shell` can never be authorized unless listed in `allow:`, so
+     neither `WriteFile` nor `Shell` is attached. `:auto`, `:ask` and `:approve` decide per call
+     and always attach — `:approve` in particular *must* reach the gate so it can suspend the run.
+
+  `ReadFile` and `Glob` are always attached. This is a cost and description-accuracy measure, not
+  a security boundary: `Permissions#authorize!` remains the gate and still denies at call time.
 
 - **Shell output truncation (`Nexo::OutputTruncator`).** Unbounded command output (`npm install`,
   `git log`) is truncated before it reaches the model, so a single command can't blow a small

data/docs/tools.md

@@ -1,12 +1,22 @@
 # Tools
 Nexo attaches four sandbox-backed tools — `ReadFile`, `WriteFile`, `Shell`, and `Glob` — each gated by the [sandbox](sandboxes.md) and [permission](permissions.md) seams.
 
-Which tools attach depends on what the sandbox supports:
-
-- **Capability-gated tool attach (`Sandbox#supports?`).** A `:virtual` agent no longer advertises
-  a `Shell` tool it can never run — `Agent#chat` attaches `Shell` only when
-  `@sandbox.supports?(:shell)`. `Local`/`Container` support all four capabilities; `Virtual`
-  supports everything but `:shell`. `ReadFile`/`WriteFile`/`Glob` are always attached.
+Which tools attach depends on what the sandbox supports *and* on what the permission mode could
+ever allow:
+
+- **Gated tool attach, on two axes.** An agent does not advertise a tool it could never
+  successfully call, because a guaranteed failure in the schema costs a round trip every time a
+  model tries it. `Agent#chat` attaches a tool only when **both** hold:
+
+  1. *The sandbox supports the capability* (`Sandbox#supports?`). `Local`/`Container` support all
+     four; `Virtual` supports everything but `:shell`, so a `:virtual` agent has no `Shell`.
+  2. *The permission gate does not deny it statically* (`Permissions#never_allows?`). Under
+     `:read_only`, `:write` and `:shell` can never be authorized unless listed in `allow:`, so
+     neither `WriteFile` nor `Shell` is attached. `:auto`, `:ask` and `:approve` decide per call
+     and always attach — `:approve` in particular *must* reach the gate so it can suspend the run.
+
+  `ReadFile` and `Glob` are always attached. This is a cost and description-accuracy measure, not
+  a security boundary: `Permissions#authorize!` remains the gate and still denies at call time.
 
 `Shell` truncates unbounded command output before it reaches the model:
 

data/docs/workflows.md

@@ -176,7 +176,7 @@ artifact("digest.md", from: "app/templates/digest.md.erb",
 > or uploaded template is remote code execution. If a body is untrusted, pass it
 > as `content:` (inert data), not as a `from:` template.
 
-See [`examples/artifact_from_template.rb`](../examples/artifact_from_template.rb) for
+See [`examples/artifact_from_template.rb`](https://github.com/maquina-app/nexo/blob/main/examples/artifact_from_template.rb) for
 the full offline flow (`ruby -Ilib examples/artifact_from_template.rb`).
 ### Agent output — `produces`
 
@@ -307,7 +307,7 @@ end
 > *how* (skills/instructions). Driving an agent never widens its authority — its
 > safe default (`:read_only`) is untouched.
 
-See [`examples/inbox_digest_task.rb`](../examples/inbox_digest_task.rb) for a live
+See [`examples/inbox_digest_task.rb`](https://github.com/maquina-app/nexo/blob/main/examples/inbox_digest_task.rb) for a live
 example that wraps the MCP-backed `InboxTriage` agent in a workflow and captures
 the digest as an artifact.
 

data/lib/generators/nexo/artifacts/artifacts_generator.rb

@@ -5,15 +5,17 @@ require "rails/generators/migration"
 
 module Nexo
   module Generators
-    # Adds the +artifacts+ column to an already-installed +nexo_workflow_runs+
+    # Adds the `artifacts` column to an already-installed `nexo_workflow_runs`
     # table (Spec 7):
     #
-    #   rails g nexo:artifacts
+    # ```sh
+    # rails g nexo:artifacts
+    # ```
     #
-    # copies a timestamped, additive migration adding a +json+ +artifacts+ column
-    # (default +[]+), after which +rails db:migrate+ lets Nexo::Workflow runs
+    # copies a timestamped, additive migration adding a `json` `artifacts` column
+    # (default `[]`), after which `rails db:migrate` lets Nexo::Workflow runs
     # record named artifacts. Fresh installs get the column from
-    # +nexo:workflows+ directly; this generator is for apps installed before
+    # `nexo:workflows` directly; this generator is for apps installed before
     # Spec 7. Modeled on WorkflowsGenerator.
     class ArtifactsGenerator < Rails::Generators::Base
       include Rails::Generators::Migration
@@ -27,8 +29,8 @@ module Nexo
         ::ActiveRecord::Migration.next_migration_number(next_migration_number)
       end
 
-      # Generation step: copy the timestamped +artifacts+-column migration into
-      # +db/migrate+.
+      # Generation step: copy the timestamped `artifacts`-column migration into
+      # `db/migrate`.
       def create_migration_file
         migration_template "add_artifacts_to_nexo_workflow_runs.rb", "db/migrate/add_artifacts_to_nexo_workflow_runs.rb"
       end

data/lib/generators/nexo/artifacts/templates/add_artifacts_to_nexo_workflow_runs.rb

@@ -4,7 +4,7 @@
 # column from create_nexo_workflow_runs directly). Portable json column, default
 # [], matching the events column shape.
 class AddArtifactsToNexoWorkflowRuns < ActiveRecord::Migration[8.0]
-  # Adds the +artifacts+ json column (default +[]+) to +nexo_workflow_runs+.
+  # Adds the `artifacts` json column (default `[]`) to `nexo_workflow_runs`.
   def change
     add_column :nexo_workflow_runs, :artifacts, :json, null: false, default: []
   end

data/lib/generators/nexo/install/install_generator.rb

@@ -3,13 +3,15 @@
 require "rails/generators"
 
 module Nexo
-  # Namespace for Nexo's Rails generators (+rails g nexo:install+,
-  # +nexo:workflows+, +nexo:artifacts+, +nexo:state+, +nexo:skill+). Each is
+  # Namespace for Nexo's Rails generators (`rails g nexo:install`,
+  # `nexo:workflows`, `nexo:artifacts`, `nexo:state`, `nexo:skill`). Each is
   # Rails-coupled and never autoloaded by the plain-Ruby core.
   module Generators
     # Sets up the conventional Nexo layout in a host Rails app:
     #
-    #   rails g nexo:install
+    # ```sh
+    # rails g nexo:install
+    # ```
     #
     # creates the app/agents, app/workflows and app/skills directories (each
     # with a committable .keep) and a provider-neutral config/initializers/nexo.rb.
@@ -17,7 +19,7 @@ module Nexo
       source_root File.expand_path("templates", __dir__)
 
       # Generation step: create the app/agents, app/workflows, and app/skills
-      # directories, each with a committable +.keep+.
+      # directories, each with a committable `.keep`.
       def create_directories
         %w[app/agents app/workflows app/skills].each do |dir|
           empty_directory dir
@@ -26,7 +28,7 @@ module Nexo
       end
 
       # Generation step: copy the provider-neutral
-      # +config/initializers/nexo.rb+ into the host app.
+      # `config/initializers/nexo.rb` into the host app.
       def copy_initializer
         copy_file "nexo.rb", "config/initializers/nexo.rb"
       end

data/lib/generators/nexo/skill/skill_generator.rb

@@ -7,21 +7,23 @@ module Nexo
   module Generators
     # Scaffolds an Agent Skills package in a host Rails app:
     #
-    #   rails g nexo:skill triage
+    # ```sh
+    # rails g nexo:skill triage
+    # ```
     #
-    # creates +app/skills/triage/SKILL.md+ (valid frontmatter + placeholder
+    # creates `app/skills/triage/SKILL.md` (valid frontmatter + placeholder
     # process steps, per agentskills.io/specification) and a kept
-    # +app/skills/triage/references/+ directory for supporting docs the skill can
-    # cite. Reference it from an agent with the +skills :triage+ macro.
+    # `app/skills/triage/references/` directory for supporting docs the skill can
+    # cite. Reference it from an agent with the `skills :triage` macro.
     #
-    # Rails-coupled, like Nexo's other generators: it requires +rails/generators+
+    # Rails-coupled, like Nexo's other generators: it requires `rails/generators`
     # at load time and is never autoloaded by the plain-Ruby core, so
-    # +require "nexo"+ with no Rails present neither defines nor fails on it.
+    # `require "nexo"` with no Rails present neither defines nor fails on it.
     class SkillGenerator < Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
-      # Generation step: scaffold +app/skills/<name>/+ with a kept +references/+
-      # directory and a valid +SKILL.md+ rendered from the template.
+      # Generation step: scaffold `app/skills/<name>/` with a kept `references/`
+      # directory and a valid `SKILL.md` rendered from the template.
       def create_skill_package
         empty_directory File.join(skill_root, "references")
         # An empty references/ would not survive git; .keep keeps it tracked.

data/lib/generators/nexo/state/state_generator.rb

@@ -5,15 +5,17 @@ require "rails/generators/migration"
 
 module Nexo
   module Generators
-    # Adds the +state+ column to an already-installed +nexo_workflow_runs+ table
+    # Adds the `state` column to an already-installed `nexo_workflow_runs` table
     # (Spec 13):
     #
-    #   rails g nexo:state
+    # ```sh
+    # rails g nexo:state
+    # ```
     #
-    # copies a timestamped, additive migration adding a +json+ +state+ column
-    # (default +{}+), after which +rails db:migrate+ lets Nexo::Workflow runs
+    # copies a timestamped, additive migration adding a `json` `state` column
+    # (default `{}`), after which `rails db:migrate` lets Nexo::Workflow runs
     # store checkpoint results and suspend metadata (durable suspend/resume).
-    # Fresh installs get the column from +nexo:workflows+ directly; this generator
+    # Fresh installs get the column from `nexo:workflows` directly; this generator
     # is for apps installed before Spec 13. Modeled on ArtifactsGenerator.
     class StateGenerator < Rails::Generators::Base
       include Rails::Generators::Migration
@@ -27,8 +29,8 @@ module Nexo
         ::ActiveRecord::Migration.next_migration_number(next_migration_number)
       end
 
-      # Generation step: copy the timestamped +state+-column migration into
-      # +db/migrate+.
+      # Generation step: copy the timestamped `state`-column migration into
+      # `db/migrate`.
       def create_migration_file
         migration_template "add_state_to_nexo_workflow_runs.rb", "db/migrate/add_state_to_nexo_workflow_runs.rb"
       end

data/lib/generators/nexo/state/templates/add_state_to_nexo_workflow_runs.rb

@@ -6,7 +6,7 @@
 # "__suspend__" suspend metadata. The migration version is resolved from the host
 # app's ActiveRecord rather than hardcoded, so it tracks whatever Rails is installed.
 class AddStateToNexoWorkflowRuns < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
-  # Adds the +state+ json object column (default +{}+) to +nexo_workflow_runs+.
+  # Adds the `state` json object column (default `{}`) to `nexo_workflow_runs`.
   def change
     add_column :nexo_workflow_runs, :state, :json, null: false, default: {}
   end

data/lib/generators/nexo/workflows/templates/create_nexo_workflow_runs.rb

@@ -4,9 +4,9 @@
 # SQLite and PostgreSQL without an adapter-aware path. The primary key is the
 # UUID string id assigned by Nexo::WorkflowRun before_create.
 class CreateNexoWorkflowRuns < ActiveRecord::Migration[8.0]
-  # Creates the +nexo_workflow_runs+ table (UUID string primary key, portable
-  # +json+ columns for payload/result/events/artifacts/state) plus indexes on
-  # +workflow_class+ and +status+.
+  # Creates the `nexo_workflow_runs` table (UUID string primary key, portable
+  # `json` columns for payload/result/events/artifacts/state) plus indexes on
+  # `workflow_class` and `status`.
   def change
     create_table :nexo_workflow_runs, id: false do |t|
       t.string :id, null: false, primary_key: true

data/lib/generators/nexo/workflows/workflows_generator.rb

@@ -7,10 +7,12 @@ module Nexo
   module Generators
     # Installs the WorkflowRun persistence schema into a host Rails app:
     #
-    #   rails g nexo:workflows
+    # ```sh
+    # rails g nexo:workflows
+    # ```
     #
-    # copies a timestamped migration that creates the +nexo_workflow_runs+
-    # table, after which +rails db:migrate+ makes Nexo::Workflow runs persist
+    # copies a timestamped migration that creates the `nexo_workflow_runs`
+    # table, after which `rails db:migrate` makes Nexo::Workflow runs persist
     # to ActiveRecord instead of the in-memory store.
     class WorkflowsGenerator < Rails::Generators::Base
       include Rails::Generators::Migration
@@ -24,8 +26,8 @@ module Nexo
         ::ActiveRecord::Migration.next_migration_number(next_migration_number)
       end
 
-      # Generation step: copy the timestamped +create_nexo_workflow_runs+
-      # migration into +db/migrate+.
+      # Generation step: copy the timestamped `create_nexo_workflow_runs`
+      # migration into `db/migrate`.
       def create_migration_file
         migration_template "create_nexo_workflow_runs.rb", "db/migrate/create_nexo_workflow_runs.rb"
       end