nexo_ai 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a372c4ac5c253a76cbf930d99b134bbdc62c596dc8bde4414da26f08c99ad39
-  data.tar.gz: 8329003fd163b8b4131f4608b18ecb5604717b7dd6995699328216cb22143320
+  metadata.gz: 6739e4be2c75c08ffb553133324b96b29d13e0212e21cc23c4cd6287316b3249
+  data.tar.gz: d051ce3a0916cd5fb9328df9b893e5aad15b6f60c8d5c23bb9be8b3126da7285
 SHA512:
-  metadata.gz: 3e3de8747793d6c7b052d9272f6e23345e33d0749e66cd17a4247429eec1999f1329830c1c21841ac399bc04743f2d6595126496d8a24d340b537ad5ee4de026
-  data.tar.gz: 271699e28b6c236f618250b06f75ed8c4fc5d0dec269d24d0f4bac145366e1cedc0f6fee37926117b9fbf2446a8d4d7b54054f2c73562f3d6a1bfd6ae41e21d5
+  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,19 @@
 ## [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.

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/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/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