nexo_ai 0.1.0 → 0.7.0

data/docs/getting-started.md

@@ -0,0 +1,103 @@
+# Getting started
+Install Nexo, configure the harness, and build your first agent.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "nexo_ai"
+```
+
+Or install directly:
+
+```sh
+gem install nexo_ai
+```
+
+In a Rails app, run the install generator to create the conventional layout and an initializer:
+
+```sh
+rails g nexo:install
+```
+
+```
+      create  app/agents/.keep
+      create  app/workflows/.keep
+      create  app/skills/.keep
+      create  config/initializers/nexo.rb
+```
+
+## Configuration
+
+Configure the harness in one place with `Nexo.configure`. Defaults are safe and
+provider-neutral — there is intentionally no hardcoded model:
+
+```ruby
+Nexo.configure do |config|
+  config.default_model       = ENV["NEXO_MODEL"] # provider-neutral: no default
+  config.default_sandbox     = :virtual          # :virtual | :local | :docker | :apple | a Hash | a Sandbox
+  config.default_permissions = :read_only        # :read_only | :auto | :ask | :approve
+  config.skills_path         = "app/skills"
+  config.concurrency         = :threaded         # :threaded | :async (opt-in fiber offload)
+  config.max_in_flight       = 8                 # Nexo.concurrent fan-out bound
+  config.buffer_workflow_events = false          # buffer + flush-once workflow events
+end
+
+Nexo.config.default_sandbox      # => :virtual
+Nexo.config.default_permissions  # => :read_only
+Nexo.config.default_model        # => nil unless set
+```
+
+`require "nexo"` works in plain Ruby with no Rails loaded.
+
+## Build an agent in five lines
+
+Subclass `Nexo::Agent`, declare the pieces with class macros, and call `#prompt`. No
+sandbox, permission, or tool object is wired by hand, and nothing is vendor-specific —
+the agent runs on any `ruby_llm`-supported model (set `NEXO_MODEL`, e.g. a local
+`gemma3:12b` via Ollama, or a hosted model):
+
+```ruby
+require "nexo"
+
+class CodeReviewer < Nexo::Agent
+  model       ENV.fetch("NEXO_MODEL")   # any ruby_llm model — never a hardcoded vendor default
+  sandbox     :local
+  permissions :read_only
+
+  instructions "You are a careful code reviewer. Read files and report issues. Do not write files."
+end
+
+CodeReviewer.new(cwd: "/path/to/repo").prompt("Review the auth module")
+```
+
+Defaults are safe: an agent with no `sandbox`/`permissions` declared gets the in-memory
+`:virtual` sandbox and `:read_only` permissions, so an untrusted model has zero host
+access until you explicitly opt in.
+
+## Unregistered models — local tags, self-hosted, brand-new releases
+
+`ruby_llm` normally validates a model id against its bundled `models.json` registry
+and infers the provider from it. A local Ollama tag (`gemma3:12b`), a self-hosted
+build, or a model newer than the installed registry isn't listed there — so declare
+the `provider` explicitly and set `assume_model_exists` to skip the registry lookup:
+
+```ruby
+class LocalReviewer < Nexo::Agent
+  model               "gemma3:12b"
+  provider            :ollama         # required once the registry lookup is skipped
+  assume_model_exists true            # opt out of models.json validation
+
+  instructions "You are a careful code reviewer."
+end
+```
+
+Both are class macros with the same reader/writer convention as `model`. `provider`
+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)
+for a runnable Ollama example.
+
+← Back to the [README](../README.md)

data/docs/loops.md

@@ -0,0 +1,93 @@
+# Loop backends — swap the engine, not the agent
+The loop is the engine that drives one prompt to completion; swap it by constructor injection without touching the agent class.
+
+The **loop** is the engine that drives one prompt to completion. Swapping it is constructor
+injection (`loop:`) — the agent class never changes. Two backends ship:
+
+|                    | `Loops::RubyLLM` (default)         | `Loops::AgentSDK` (opt-in)            |
+| ------------------ | ---------------------------------- | ------------------------------------- |
+| Provider neutral   | ✅ any `ruby_llm` model            | ❌ Anthropic-oriented                 |
+| Tool source        | your sandbox-backed tools          | the SDK's own built-in/host tools     |
+| Turn cap           | observability only (see caveat)    | native `max_turns` hard cap           |
+| Execution location | your sandbox (virtual/local/remote)| the host process                      |
+
+The whole point: **same agent code, swapped backends**. Both examples are model-agnostic
+(`ENV.fetch("NEXO_MODEL")` — never a hardcoded `"claude-…"`):
+
+```ruby
+# Claude fast path — AgentSDK's own loop + host tools + native max_turns
+claude = Nexo::Agent.new(
+  model: ENV.fetch("NEXO_MODEL"),
+  sandbox: Nexo::Sandboxes::Local.new(cwd: "/srv/checkout"),
+  permissions: Nexo::Permissions.new(mode: :auto),
+  loop: Nexo::Loops::AgentSDK.new
+)
+
+# Any-provider path — your sandbox, your tools, human-in-the-loop
+gpt = Nexo::Agent.new(
+  model: ENV.fetch("NEXO_MODEL"),                # gpt-5.5, gemini, gemma3:12b via Ollama…
+  sandbox: Nexo::Sandboxes::Remote.new(client: my_container_client),
+  permissions: Nexo::Permissions.new(mode: :ask, on_ask: ->(cap, detail) {
+    SlackApproval.request!(capability: cap, detail: detail)
+  }),
+  loop: Nexo::Loops::RubyLLM.new
+)
+```
+
+`Loops::AgentSDK` wraps `RubyLLM::AgentSDK.query` and requires the **optional**
+`ruby_llm-agent_sdk` gem (lazy `require`; a clear `Nexo::MissingDependencyError` if it's
+absent). It maps Nexo's permission modes onto the SDK's own vocabulary:
+
+| Nexo mode    | AgentSDK `permission_mode` |
+| ------------ | -------------------------- |
+| `:read_only` | `:default`                 |
+| `:auto`      | `:bypass_permissions`      |
+| `:ask`       | `:default` (human gating stays in Nexo's own `on_ask` path, not delegated to the SDK) |
+| `:approve`   | `:default` (durable approval stays in Nexo's own gate; any unmapped mode also falls back to `:default`) |
+
+## The turn-cap caveat (read before running untrusted/expensive workloads)
+
+`ruby_llm` runs the whole tool loop inside `ask`, so `Loops::RubyLLM` has **no clean public
+hard "stop after N turns" halt** — `before_tool_call` gives turn-count *observability*, not a
+hard stop. (Confirmed: `ruby_llm` 1.16.0's `Chat` exposes no public max-turns/max-iterations
+setting.) Your three real options:
+
+(a) use `Loops::AgentSDK` (native `max_turns`) for untrusted/expensive workloads;
+(b) have a tool return `{ error: "turn limit reached, stop and summarize" }` once a turn
+    counter trips;
+(c) check whether the installed `ruby_llm` exposes a max-iterations config (in 1.16.0 it
+    does not).
+
+Do **not** ship `Loops::RubyLLM` for untrusted workloads claiming a hard cap that isn't
+proven.
+
+## Verified vs assumed
+
+Built against **`ruby_llm` 1.16** 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
+`ruby_llm` versions.
+
+`Loops::RubyLLM`'s turn-count observability uses `RubyLLM::Chat#before_tool_call` /
+`#after_tool_result`, confirmed present on `ruby_llm` 1.16.0 and guarded with `respond_to?`
+so a version lacking them degrades to no observability rather than crashing.
+`Loops::AgentSDK` targets `RubyLLM::AgentSDK.query`; `ruby_llm-agent_sdk` is **not** a
+dependency of this release, so that signature is **assumed** (per the gem's README) and
+verified-on-install — confirm it the moment you add the gem.
+
+## Live smoke (optional)
+
+The core suite is fully offline and deterministic (models stubbed with `ruby_llm-test`).
+A real end-to-end check is opt-in and env-gated — small local models like Gemma have weak
+tool-calling, so it may be flaky and is never a gating test:
+
+```sh
+ollama serve &
+NEXO_LIVE=1 NEXO_MODEL=gemma3:12b bundle exec rake test TEST=test/live_smoke_test.rb
+```
+
+If Gemma's tool-calling proves too weak, point `NEXO_MODEL` at a stronger model — the gem
+stays provider-neutral; only the smoke target changes.
+
+← Back to the [README](../README.md)

data/docs/mcp.md

@@ -0,0 +1,144 @@
+# MCP data sources
+Attach one or more MCP servers with a single `mcp` macro — every call gated by a second, fail-closed permission axis.
+
+An **MCP server** exposes tools to a model over the [Model Context
+Protocol](https://modelcontextprotocol.io) — Gmail, a filesystem, a fetch endpoint,
+Drive, and so on. Nexo does not implement MCP; it composes the
+[`ruby_llm-mcp`](https://github.com/patvice/ruby_llm-mcp) gem so you attach one or more
+servers with a single `mcp` macro and no client wiring. Because a server is reached
+*through the protocol* (never a vendor SDK), the behavior is identical on Anthropic, a
+local model, or anything else `ruby_llm` supports.
+
+```ruby
+require "nexo"
+
+class InboxDigest < Nexo::Agent
+  model       ENV.fetch("NEXO_MODEL")   # any ruby_llm model — never a hardcoded vendor default
+  permissions :read_only
+  mcp :gmail, transport: :stdio, command: "npx", args: %w[-y @modelcontextprotocol/server-gmail]
+  mcp :fs,    transport: :stdio, command: "npx", args: %w[-y @modelcontextprotocol/server-filesystem /data]
+  mcp :fetch, transport: :sse,   url: "http://localhost:8080/sse"
+  mcp_allow %w[search_threads get_thread]
+end
+```
+
+Each `mcp` line accumulates a server declaration. `name` and `transport` map onto the
+client's `name:`/`transport_type:`; every other keyword is passed through verbatim as the
+server's `config:` — `command:`/`args:` for `:stdio`, `url:` for `:sse`. The server's tools
+are attached to the chat after the sandbox tools and skills, and fire the same
+`before_tool_call`/`after_tool_result` observability callbacks, so MCP calls appear in a
+run's event log automatically.
+
+## Every MCP tool call is gated — and fails closed
+
+MCP tools obey a **second permission axis**, separate from the sandbox capability axis,
+because an MCP tool executes inside the server, outside the sandbox. `mcp_allow` is the
+exact-match allow-list threaded into the agent's permissions:
+
+| Mode | MCP tool behavior |
+|---|---|
+| `:read_only` (default) | allow **only** tool names listed in `mcp_allow`; everything else is denied |
+| `:ask` | call `on_ask.call(:mcp, {tool:, args:})`; a truthy return allows, else deny |
+| `:approve` | names in `mcp_allow` are pre-approved; any other tool needs a human decision — undecided **suspends the run** (`Nexo::ApprovalRequired`), `approved: true` allows, `approved: false` denies (the durable sibling of `:ask`) |
+| `:auto` | allow every MCP tool |
+
+`mcp_allow` defaults to `[]`, so attaching a powerful server under `:read_only` with no
+allow-list denies **every** tool — a misconfigured agent fails closed, not open. A denied
+call returns `{ error: … }` to the model (recoverable) and never raises into the loop —
+identical to the sandbox tools. Escalation (`:auto`, a populated `mcp_allow`, or `:ask`
+with a real `on_ask`) is always explicit in your code. Matching is exact tool-name only —
+no globs or regexes.
+
+**Two caveats — read before attaching a server:**
+
+1. **MCP tool *effects* are not sandboxed.** The gate covers the authority to *invoke* a
+   tool; the tool then runs in the MCP server, outside Nexo's sandbox. Nexo cannot
+   constrain what that server does with a call it is authorized to make — attaching a write
+   server and allowing a write tool means real writes happen. Gate deliberately, and prefer
+   `:read_only` with a tight `mcp_allow`.
+2. **Connection lifecycle.** Clients are built once and **memoized on the agent instance**,
+   reused across prompts (the `ruby_llm-mcp` client connects on construction and stays
+   connected). A long-lived agent holding stdio/SSE servers should call `Agent#close` when
+   done to tear the connections down:
+
+   ```ruby
+   agent = InboxDigest.new
+   agent.prompt("Summarize invoices from this week")
+   agent.prompt("Any follow-ups needed?")   # reuses the same live MCP connections
+   agent.close                              # stops every attached server
+   ```
+
+## HTTP-family servers + an OAuth `token:` provider
+
+Beyond `:stdio`, Nexo attaches a server over any HTTP-family transport `ruby_llm-mcp`
+supports — `transport: :http`, `:sse`, or `:streamable`. For an OAuth-authenticated
+hosted server (Gmail, Drive, …) add a `token:` — a static bearer `String`, or a
+**callable** re-read close to connection time. Nexo resolves it and injects an
+`Authorization: Bearer <token>` header per connection:
+
+```ruby
+class InboxTriageHTTP < Nexo::Agent
+  model       ENV.fetch("NEXO_MODEL")
+  permissions :read_only
+
+  # Hosted Gmail MCP server over HTTP; the host supplies the OAuth access token.
+  mcp :gmail,
+    transport: :http,
+    url:       ENV.fetch("GMAIL_MCP_URL"),
+    token:     -> { Current.user.gmail_access_token }   # re-read at connection time
+
+  # READ tools only — the unchanged gate denies send/trash/modify.
+  mcp_allow %w[search_threads get_thread list_messages get_message list_labels]
+end
+```
+
+A static token (`token: ENV.fetch("GMAIL_TOKEN")`) is equally valid. Under the hood
+Nexo strips `token:` and hands off:
+
+```ruby
+RubyLLM::MCP.client(
+  name: "gmail", transport_type: :http,
+  config: { url: "https://…", headers: { "Authorization" => "Bearer <resolved>" } }
+)
+```
+
+Any other `headers:` you pass are preserved; Nexo's `Authorization` wins. With no
+`token:`, `config:` passes through byte-for-byte (no `headers` key) — the `:stdio` path
+is untouched.
+
+**Nexo does not own the OAuth flow.** It performs no authorization-code exchange, no
+token refresh, and keeps no token store — that is your app or an OAuth library. Nexo's
+only job is to call the provider, inject the header, and hand off. The token is never
+logged, persisted, placed in a URL/query string, or emitted in an event (the event path
+carries only tool `name`/`args` and return values — never connection config).
+
+**Refresh / reconnect caveat.** `ruby_llm-mcp`'s HTTP-family transports snapshot the
+`headers` hash **at construction** — there is no per-request header callback for a plain
+`headers` Hash. A callable `token:` is therefore resolved **once**, when the client is
+built, and the client is memoized on the agent instance across prompts. So when a token
+**rotates**, tear the connection down and reconnect to pick up the new value:
+
+```ruby
+agent.close                  # stops the memoized MCP client
+agent.prompt("…")            # a fresh prompt rebuilds the client → token: re-resolved
+```
+
+**The gate is unchanged.** An HTTP OAuth server's tools are gated exactly like `:stdio`
+tools: denied under `:read_only` until the exact name is in `mcp_allow` (default `[]` ⇒
+deny-all). Attaching an authenticated server adds no permission surface.
+
+**Two honest caveats — read before attaching a token:**
+
+1. **Refresh may require a reconnect.** Because headers are construction-only,
+   a rotated token needs `agent.close` + a fresh prompt (above), not just a new proc
+   return. A static token stays constant for the client's life.
+2. **The token is a live credential.** Even gated, an authorized MCP call runs its effect
+   server-side — a leaked bearer is a real compromise. Nexo keeps it out of logs, events,
+   persisted `WorkflowRun` records, and URLs; your host code must do the same. Nexo does
+   not police `ruby_llm-mcp`'s own internal logging of headers — that boundary is yours.
+
+`ruby_llm-mcp` is an **optional** dependency — required lazily only when you attach a
+server. Without it installed, `require "nexo"` still loads; building a server raises a clear
+`Nexo::MissingDependencyError` telling you to add `gem "ruby_llm-mcp"`.
+
+← Back to the [README](../README.md)

data/docs/permissions.md

@@ -0,0 +1,47 @@
+# Permissions
+The permission mode is *what* an agent's tools may do — read-only by default, with `:auto`, `:ask`, and `:approve` escalations; the separate MCP tool gate lives in [MCP](mcp.md).
+
+Two seams compose the execution environment. The **sandbox** is *where* tools act; the
+**permission mode** is *what* they may do. A denied capability returns `{ error: ... }`
+and the agent loop continues — it does not raise. A path that escapes the workspace raises
+`SecurityError`; an agent built with no resolvable model raises `Nexo::ConfigurationError`.
+
+|                          | `:read` | `:glob` | `:write`            | `:shell`                          | `:fetch`   | `:search`  |
+| ------------------------ | ------- | ------- | ------------------- | --------------------------------- | ---------- | ---------- |
+| `:read_only` (default)   | ✅      | ✅      | ❌ `{error}`        | ❌ `{error}`                      | ❌ `{error}` | ❌ `{error}` |
+| `:auto`                  | ✅      | ✅      | ✅                  | ✅                                | ✅         | ✅         |
+| `:ask`                   | ✅      | ✅      | per `on_ask`        | per `on_ask`                      | per `on_ask` | per `on_ask` |
+| `:approve`               | ✅      | ✅      | per `decision`      | per `decision`                    | per `decision` | per `decision` |
+| `Virtual` sandbox        | ✅      | ✅      | ✅ (in-memory)      | ❌ `NotImplementedError`→`{error}` | ✅ †       | ✅ †       |
+| `Local` sandbox          | ✅ (guarded) | ✅ | ✅ (guarded)        | ✅ (narrowed ENV)                 | ✅ †       | ✅ †       |
+| `Container` sandbox      | ✅ (guarded) | ✅ | ✅ (guarded, scratch) | ✅ (in container)               | ✅ †       | ✅ †       |
+
+`: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`
+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.
+
+## Human-gated writes (`:ask`)
+
+`:ask` mode defers every write/shell action to your callback. Build a `Permissions` with
+an `on_ask` hook and pass it in:
+
+```ruby
+gate = Nexo::Permissions.new(mode: :ask, on_ask: ->(cap, detail) {
+  $stdout.print("Allow #{cap} #{detail}? [y/N] "); $stdin.gets.strip == "y"
+})
+
+class Editor < Nexo::Agent
+  model   ENV.fetch("NEXO_MODEL")
+  sandbox :local
+end
+
+Editor.new(cwd: ".", permissions: gate).prompt("Fix the typo in README.md")
+```
+
+(The bare `:ask` symbol resolves to `Permissions.new(mode: :ask)` with **no** callback, so
+writes/shell are denied — pass a pre-built `Permissions` with `on_ask` for a real gate.)
+
+← Back to the [README](../README.md)

data/docs/rails.md

@@ -0,0 +1,129 @@
+# Rails
+Rails wiring: background execution with `run_later`, live progress broadcasting, and run-query helpers for a host UI.
+
+The install generator (`rails g nexo:install`) is covered in [Getting started](getting-started.md);
+the per-feature generators (`rails g nexo:workflows`, `nexo:artifacts`, `nexo:state`, `nexo:skill`)
+live with their topics in [Workflows](workflows.md), [Durable workflows](durable-workflows.md), and
+[Skills](skills.md).
+
+## Background execution — `run_later`
+
+`MyWorkflow.run_later(payload)` enqueues the run on your **existing ActiveJob
+adapter** and hands back the run **immediately** (status `"queued"`), so a
+controller can return while the work happens in the background. The job carries
+**only the run id** — the payload lives on the run record, so no arguments (and
+no secrets) travel through the queue. When the worker picks it up, it reconstitutes
+the workflow and calls the same `execute` the sync path uses, so an async run
+reaches the identical `done`/`failed` lifecycle, event log, and status
+notifications:
+
+```ruby
+class GenerateReport < Nexo::Workflow
+  def call(payload) = { url: build_report(payload[:account_id]) }
+end
+
+run = GenerateReport.run_later(account_id: 42)   # returns at once
+run.status                                        # => "queued"
+# ...the worker runs it in the background; later:
+Nexo::RunStore.default.find(run.id).status        # => "done"
+```
+
+Route jobs to a dedicated queue per call or globally:
+
+```ruby
+GenerateReport.run_later(account_id: 42, queue: :nexo)  # per-call
+Nexo.configure { |c| c.job_queue = :nexo }              # or a global default
+```
+
+Nexo ships **no queue and no scheduler** — ActiveJob uses whatever adapter your
+app configured (Sidekiq, GoodJob, Solid Queue, …), and scheduling (cron / GoodJob
+/ `whenever`) stays the host's. Without ActiveJob, `run_later` raises
+`Nexo::MissingDependencyError` — use `run` for synchronous execution.
+
+> **⚠️ Needs a shared store.** For a worker in **another process** to find the run,
+> use the ActiveRecord store (`rails g nexo:workflows`) with a real adapter — the
+> run must live in the database, not in a per-process memory store. The in-memory
+> store only works under the `:inline`/`:test` adapters, where the job runs
+> in-process on enqueue.
+>
+> **⚠️ No automatic crash recovery / no automatic retries.** A crashed or retried
+> job re-runs `#call` **from scratch** — Nexo adds no `retry_on` (configure retries
+> in your host job if you want them). Pair with `reconcile_interrupted!` (above) to
+> sweep runs orphaned in `"running"`. For an *intentional* pause-and-continue (a
+> human approval, an external callback), see **[Durable workflows](durable-workflows.md)** —
+> `checkpoint` skips already-paid-for work when a run resumes.
+
+## Live progress — notifications and opt-in Turbo
+
+Every run **broadcasts as it happens** over `ActiveSupport::Notifications`,
+decoupled from persistence (events still buffer/persist separately). Two
+notifications fire (a no-op with no ActiveSupport, so the plain-Ruby core stays
+Rails-free):
+
+- `nexo.workflow.event` — one per `emit`, payload `{ run_id:, event: }` (the event
+  is the string-keyed `{"type" =>, "data" =>, "at" =>}` hash). Fires **live**, even
+  when event *persistence* is buffered.
+- `nexo.workflow.status` — on each status transition, payload `{ run_id:, status: }`.
+
+The payloads carry only what `emit`/the run already hold — **no payload or
+credential dumps**. Subscribe for logging, metrics, or your own UI:
+
+```ruby
+ActiveSupport::Notifications.subscribe("nexo.workflow.event") do |*, payload|
+  Rails.logger.info("[run #{payload[:run_id]}] #{payload[:event]["type"]}")
+end
+```
+
+**Opt-in Turbo mirror.** Set `config.broadcast_events = true` (and have turbo-rails
+present) and the engine subscribes `Nexo::TurboBroadcaster`, which appends each
+event to a per-run Turbo stream, rendering the overridable partial
+`app/views/nexo/_event.html.erb`. To show live progress, add to your own page (Nexo
+ships **no** controllers, routes, or dashboard — the host owns all HTTP + UI):
+
+```erb
+<%= turbo_stream_from "nexo_run_#{@run.id}" %>
+<div id="nexo_run_<%= @run.id %>_events">
+  <%# appended events land here %>
+</div>
+```
+
+Override the appearance by defining your own `app/views/nexo/_event.html.erb` in
+the host app — it takes precedence over the engine's default (which renders
+`<div class="nexo-event">type: {data.inspect}</div>`).
+
+```ruby
+Nexo.configure { |c| c.broadcast_events = true }   # opt in; requires turbo-rails
+```
+
+> **⚠️ Broadcast reachability.** Broadcasts fire from **wherever the run executes**
+> — under `run_later`, that's the worker process. The cable backend (AnyCable,
+> Solid Cable, Redis) must therefore be reachable from your workers, not just your
+> web dynos. Nexo ships **no cable backend** — broadcasting composes whatever the
+> host configured. Without turbo-rails, `broadcast_events` is a harmless no-op:
+> the notifications still fire, so you can subscribe to them yourself.
+
+## Run helpers for a host UI
+
+`Nexo::WorkflowRun` exposes query helpers so a host can build its own runs UI
+without Nexo dictating controllers or views:
+
+```ruby
+Nexo::WorkflowRun::STATUSES  # => %w[pending queued running done failed interrupted suspended]
+
+Nexo::WorkflowRun.queued     # scope: status "queued"
+Nexo::WorkflowRun.running    # scope: status "running"
+Nexo::WorkflowRun.finished   # scope: status "done" or "failed"
+Nexo::WorkflowRun.suspended  # scope: status "suspended" (paused, awaiting resume)
+
+run.queued?  run.running?  run.done?  run.failed?  run.suspended?   # predicates
+
+# Artifact access — content only; serving files stays your
+# controller's job (Nexo ships no artifact routes/controllers):
+run.artifact("digest.md")          # => {"name" =>, "content" =>, "at" =>} or nil
+run.artifact_content("digest.md")  # => "…the body…" or nil
+```
+
+See [`examples/rails_usage.md`](../examples/rails_usage.md) for a controller +
+Turbo-page walkthrough.
+
+← Back to the [README](../README.md)