ruby_llm-ag_ui 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab7bc5eeccd9381e134cd795b20b0815aed665ac3f4371d29503bed969811410
-  data.tar.gz: 5991ee6bec49c64e3dd5ac0f8f9ccd18abe7c5f9aab55cb5493b232cff088cbe
+  metadata.gz: d8529d394d1ef5d52bc73952e047ee5303634af7aa7738cc894acc8dde378f8b
+  data.tar.gz: ed676da00af762d17fbf6d1a743b995f03d1e7744aba9afb985b95c20bedf93f
 SHA512:
-  metadata.gz: 205524fd5c5cbcd214da1f98c2c2b3678e0961b417ee598803741b577a7c7400be2e51b8d78716905cb14b2fb386d3ee46a8a3e157947cbf06afe6eaf8d01669
-  data.tar.gz: 8680a5a03eacc9cfa8d3920db2be725d5f148befd24125a9b6875312307c4207528f69b527dc294f7e064a2c4f33d0c5bf3666318d3ea81f5927089f6408ae78
+  metadata.gz: 34df865e3f9dd71cbf573ad7a89d19259d16931685cb153df6aab6e989d92be68407f6207e654fc44f615b625a840a90a44e6c4e725e5781e976e253d6744457
+  data.tar.gz: 40c5c7fd607e2ce6ccd54e53e6e6e8c2482bf7645d3155e4cdf0eedb95c58f3337bb481650a44c902863629a52bc70cd03dd4224ecaad2ab0546a947f633a0e1

data/CHANGELOG.md

@@ -6,6 +6,25 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-19
+
+### Added
+
+- Opt-in tool progress as redacted `ACTIVITY_SNAPSHOT` events, with stable
+  per-call identity and per-run or global configuration.
+- Installed-artifact host checks for generated migrations, RubyLLM model setup,
+  actor-scoped chat persistence, and Ruby/Rails run paths.
+- A pinned official AG-UI client demo for Ruby and Rails, with browser workflow
+  tests, mobile screenshots, and schema validation of consumed events.
+
+### Fixed
+
+- Reconnect an exact completed resume request without redeeming its approval
+  again. Changed input still conflicts, and a new run cannot reuse an answered
+  interrupt.
+- Supply the required actor scope in the opt-in live-provider check and exercise
+  its run setup offline, before provider verification.
+
 ## [0.1.0] - 2026-10-18
 
 ### Added

data/CONTRIBUTING.md

@@ -7,8 +7,7 @@ with tests are the easiest to accept.
 
 ```bash
 bundle install
-bundle exec rspec
-bundle exec rubocop
+bin/check
 ```
 
 ## Ground rules
@@ -33,15 +32,40 @@ bundle exec rubocop
 
 ## Tests
 
+Run focused specs first, then `bin/check`. For client or demo changes, also run
+`bin/check-browser` and inspect its screenshots. The browser suite uses synthetic
+fixtures, a real AG-UI client, and a temporary local server. Keep artifacts in
+ignored `tmp/`. Use `bin/check --package --browser` for the full local check,
+or `bin/check-browser --grep "rails: approval"` for one browser workflow.
+The package probe installs the artifact outside the checkout using available
+development dependencies; `bin/verify-package` separately tests clean dependency
+resolution. Shut down all task-owned processes when the check finishes.
+
 Every behavior change needs a test, and lifecycle, identity and security changes
 need their negative case too. The acceptance IDs (FR-01..FR-08) are referenced
 in spec descriptions. Offline CI uses fakes; live provider tests are opt-in and
 never required:
 
 ```bash
-RUBY_LLM_LIVE=1 OPENAI_API_KEY=... bundle exec rspec spec/live
+RUBY_LLM_LIVE=1 bundle exec rspec spec/live
 ```
 
+Load provider credentials through your environment or an untracked env file,
+never through command-line arguments. See the
+[compatibility guide](https://rubyllm-ag-ui.wangyaodi.com/compatibility/) for
+what each check establishes.
+
+## Documentation
+
+- Keep README to the project introduction, installation, one example, and links.
+- Keep usage, configuration, compatibility, and API details in `docs/`, the
+  source of the documentation site. Link to a guide instead of copying it.
+- Keep contributor rules here, shipped changes in [CHANGELOG.md](CHANGELOG.md),
+  and proposed work in [ROADMAP.md](ROADMAP.md).
+- Change a public API's guide in the same commit. Follow [AGENTS.md](AGENTS.md)
+  and build with `docs/bin/build.sh` before submitting documentation changes.
+- Keep example READMEs specific to running or adapting that example.
+
 ## Commit style
 
 Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, `refactor:`),

data/README.md

@@ -2,145 +2,69 @@
 
 [![CI](https://github.com/yorzi/ruby_llm-ag-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/yorzi/ruby_llm-ag-ui/actions/workflows/ci.yml)
 
-Run [RubyLLM](https://rubyllm.com) 2.x chats as [AG-UI](https://github.com/ag-ui-protocol/ag-ui) 1.0 agent runs.
-
-`ruby_llm-ag_ui` turns one RubyLLM chat turn into one AG-UI run: it validates the
-inbound `RunAgentInput`, maps RubyLLM streaming, tool and lifecycle behavior onto
-schema-valid AG-UI events, turns `requires_approval` pauses into interrupt
-outcomes with host-authorized resume, reports `Chat#cancel` as the cancelled
-outcome, and writes the stream as Server-Sent Events. A pure-Ruby core comes
-with an optional Rails adapter.
-
-> **Unofficial community project.** This gem is not affiliated with, endorsed
-> by, or maintained by the RubyLLM maintainers or the AG-UI protocol
-> maintainers. `RubyLLM::` and "AG-UI" appear here because this gem extends
-> those projects, not because it speaks for them.
-
-## Why
-
-If your agent already runs on RubyLLM and you want an AG-UI client (CopilotKit,
-`@ag-ui/client`, or another AG-UI consumer) in front of it, you currently have
-to hand-map RubyLLM callbacks, approval pauses and cancellation onto the AG-UI
-run lifecycle, and you have to parse and authorize `RunAgentInput` yourself:
-the community Ruby SDK builds outbound events but has no inbound parser. The
-usual results are wrong terminal events, duplicate runs on retry, approvals that
-are not bound to the call they approve, and cancellations reported as success.
-This gem removes that mapping work.
-
-## What it does and does not do
-
-It owns the RubyLLM → AG-UI mapping, input parsing, event ordering, run identity
-and terminal correctness. It is **not** an AG-UI core SDK, a schema fork, a chat
-UI, a CopilotKit runtime clone, or a second agent framework. RubyLLM owns the
-agent loop, tool execution, approval pauses and cancellation checkpoints. Your
-application owns identity, authorization, which tools and model a run may use,
-and persistence.
-
-## Status
-
-Version `0.1.0` is the first release. The pure-Ruby core, run store, approval/resume, cancel
-handling and the Rails adapter are implemented and covered by an offline test
-suite. Compatibility claims for real AG-UI clients and live providers are
-tracked in the [compatibility guide](https://rubyllm-ag-ui.wangyaodi.com/compatibility/) and are
-**not** asserted until recorded there.
-
-Read the [documentation site](https://rubyllm-ag-ui.wangyaodi.com/) for the
-guides, protocol coverage, compatibility matrix and security model. Its source
-is in [docs/](https://github.com/yorzi/ruby_llm-ag-ui/tree/main/docs).
-
-## Installation
+Connect [RubyLLM](https://rubyllm.com) chats to [AG-UI](https://docs.ag-ui.com)
+clients over Server-Sent Events. The gem handles streaming text, tool calls, approval and resume,
+cancellation outcomes, and run identity. Use it from plain Ruby or with the
+optional Rails adapter.
 
-```ruby
-# Gemfile
-gem 'ruby_llm-ag_ui', '~> 0.1.0'
-```
+Your application provides authentication, tool permissions, chat history, and
+the model. This is an unofficial community project, independent of the
+RubyLLM and AG-UI maintainers.
 
-```bash
-bundle install
+**[Documentation](https://rubyllm-ag-ui.wangyaodi.com/)** ·
+[Getting started](https://rubyllm-ag-ui.wangyaodi.com/getting-started/) ·
+[Rails guide](https://rubyllm-ag-ui.wangyaodi.com/rails-integration/) ·
+[Compatibility](https://rubyllm-ag-ui.wangyaodi.com/compatibility/)
+
+## Install
+
+```ruby
+gem 'ruby_llm-ag_ui', '~> 0.2.0'
 ```
 
-Requires Ruby >= 3.2, RubyLLM >= 2.1 and `ag-ui-protocol` ~> 0.2.0.
-Runtime dependencies also select patched `cgi`, `resolv`, `uri` and `zlib` gems.
+Requires Ruby >= 3.2, RubyLLM >= 2.1 and < 3.0, and `ag-ui-protocol` 0.2.x.
+Run `bundle install` after adding the gem.
 
-## Quick start (pure Ruby)
+## Stream a run
 
-The host authenticates, authorizes and builds the chat; the gem writes the
-stream.
+Pass a chat authorized for the current actor, a shared run store, and an
+IO-like response stream from your application:
 
 ```ruby
-require 'ruby_llm'
 require 'ruby_llm/ag_ui'
 
-input = RubyLLM::AgUI::Input.parse(request_body)   # bounds, validates, digests
-chat  = host_chat_for(actor, input.thread_id)     # your RubyLLM::Chat
+input = RubyLLM::AgUI::Input.parse(request_body)
+chat = authorized_chat_for(current_user, input.thread_id)
 
 RubyLLM::AgUI::Run.new(
   chat: chat,
   input: input,
-  scope: "tenant:#{tenant.id}:actor:#{actor.id}", # from authenticated identity
+  scope: "actor:#{current_user.id}",
   store: run_store
-).stream(to: sse_io)
-```
-
-`scope` is what the run is reserved under: it must be a non-empty String the host
-builds from authenticated identity, never anything from the request body.
-
-`examples/pure_ruby/app.rb` is a runnable Rack endpoint that streams a complete
-run (a tool call, an approval pause and the run that answers it) with no
-provider and no credentials (`rake example`, or
-`rackup examples/pure_ruby/config.ru`). Set `RUBY_LLM_AG_UI_EXAMPLE_MODEL` to
-drive a real `RubyLLM::Chat` through the same code.
-
-## Rails
-
-The optional adapter provides a controller concern, a durable run store keyed
-by the actor's scope, and reconnect snapshots. It loads only when
-`Rails::Railtie` is already defined.
-
-```ruby
-class AgentRunsController < ApplicationController
-  include RubyLLM::AgUI::Rails::Streaming
-
-  def create
-    stream_ag_ui_run { |input| current_user.chats.find_or_create_by!(ag_ui_thread_id: input.thread_id) }
-  end
-
-  def ag_ui_scope
-    "actor:#{current_user.id}"
-  end
-end
+).stream(to: response_stream)
 ```
 
-See the [Rails integration guide](https://rubyllm-ag-ui.wangyaodi.com/rails-integration/) and `examples/rails_8`.
+Build `scope` from authenticated identity. See the
+[streaming guide](https://rubyllm-ag-ui.wangyaodi.com/streaming-runs/) for setup
+and the [examples](examples/) for integration code.
 
 ## Development
 
-```bash
+```sh
 bundle install
 bundle exec rspec
 bundle exec rubocop
-rake example        # prints a full AG-UI run as SSE
+bundle exec rake example # offline approval and resume demo, no API key needed
 ```
 
-The suite is offline: fakes instead of a provider, no network, no credentials.
-The only test that talks to a model is opt-in:
-
-```bash
-RUBY_LLM_LIVE=1 OPENAI_API_KEY=... bundle exec rspec spec/live
-```
-
-## Documentation
-
-- [Architecture](https://rubyllm-ag-ui.wangyaodi.com/overview/) - the components, run, and invariants.
-- [Protocol coverage](https://rubyllm-ag-ui.wangyaodi.com/protocol-coverage/) - all 31 AG-UI 1.0 event types
-  and what this gem does with each.
-- [Compatibility](https://rubyllm-ag-ui.wangyaodi.com/compatibility/) - what this repository verifies.
-- [Rails](https://rubyllm-ag-ui.wangyaodi.com/rails-integration/) - the controller concern, store, and transport.
-- [Security](https://rubyllm-ag-ui.wangyaodi.com/security-and-deployment/) - the threat model and deployment checklist.
-
-## License
+The default suite is offline. Real client and provider verification is tracked
+in the [compatibility guide](https://rubyllm-ag-ui.wangyaodi.com/compatibility/).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and documentation rules,
+[ROADMAP.md](ROADMAP.md) for the proposed path to 1.0, and
+[CHANGELOG.md](CHANGELOG.md) for shipped changes.
 
-MIT. See [LICENSE.txt](LICENSE.txt). Read the [third-party notices](https://rubyllm-ag-ui.wangyaodi.com/third-party-notices/).
+## License and security
 
-This is an unofficial community project and is not affiliated with the RubyLLM or
-AG-UI maintainers. Report security issues privately. See [SECURITY.md](SECURITY.md).
+[MIT](LICENSE.txt). See the
+[third-party notices](https://rubyllm-ag-ui.wangyaodi.com/third-party-notices/)
+and report vulnerabilities through [SECURITY.md](SECURITY.md).

data/docs/_advanced/client-example.md

@@ -0,0 +1,96 @@
+---
+layout: default
+title: Client Example
+nav_order: 3
+description: Run a real AG-UI browser client against offline Ruby and Rails endpoints.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to run the maintained offline client example.
+* Which interactions it verifies with the official client.
+* Which responsibilities remain with a real host application.
+
+## Run the Example
+
+From the repository, install the development dependencies and build the client:
+
+```sh
+bundle install
+npm ci
+npm run build:demo
+bundle exec ruby examples/client/server.rb
+```
+
+Open `http://127.0.0.1:3199`. Stop the server with `Ctrl-C` when finished.
+The host binds loopback and serves only the demo HTML and its locally bundled
+JavaScript. It creates and removes a temporary SQLite database on each run.
+No CDN, provider account, or API key is needed.
+
+Choose **Plain Ruby** or **Rails + SQLite**, then run a turn. The official
+`@ag-ui/client` package consumes the SSE stream. The scripted host retains one
+chat per fixture actor and thread, so approval resumes the original tool call
+and later turns use the same conversation.
+
+## Try the Interactions
+
+The tool scenario pauses for approval. Approve it to run a synthetic order
+cancellation once, or deny it to leave the order unchanged. Tool results stay
+redacted by default. Approved tools also publish synthetic progress counts;
+the host policy withholds progress messages. The text, sanitized failure, and cancelled scenarios show
+the other run outcomes.
+
+Use **Reconnect completed run** after a successful turn. The client sends the
+original input and receives the recorded outcome and snapshot; no new model
+turn or text delta is produced.
+
+## Check in a Browser
+
+```sh
+bin/check-browser
+```
+
+This runs Playwright with Chrome or its installed Chromium. On Linux, install
+the browser first with `npx playwright install --with-deps chromium`. Set
+`CHROME_BIN` to select another local Chrome executable.
+
+The check starts its own server, runs desktop and 390px mobile scenarios, saves
+screenshots and consumed events under ignored `tmp/browser/`, and stops the
+server and browser. It validates the captured events against the pinned JSON
+schema. Failures retain traces and screenshots. Inspect those artifacts before
+retrying; a screenshot alone is not an assertion.
+
+## Verify an Installed Gem
+
+```sh
+bin/check --package
+```
+
+The package probe builds a gem, installs that artifact outside the checkout,
+and checks both run paths, generated migration, approval, progress, and
+reconnect. It also generates RubyLLM's models and tables, applies the Rails
+example migrations in order, and checks actor-scoped chat persistence. It uses
+available development dependencies. Use `bin/verify-package --rails --audit`
+after `bundle exec rake build` to resolve dependencies in a clean gem home.
+
+## Adapt to a Real Host
+
+The example's actor header is a synthetic identity selector. It does not
+provide authentication, CSRF protection, or durable chat history. The run store
+uses SQLite, but the scripted chat objects live in one process and disappear
+when that process stops. A real host authorizes the thread and the next user
+turn, persists its RubyLLM chat, and rechecks tool permission before execution.
+
+The demo and browser suite make no live provider call. Read
+[Compatibility]({% link _reference/compatibility.md %}) for the exact versions
+and evidence boundaries.
+
+## Next Steps
+
+* [Rails Integration]({% link _advanced/rails-integration.md %}) - install the adapter in your application.
+* [Approval and Resume]({% link _core_features/approval-and-resume.md %}) - inspect the resume contract.

data/docs/_advanced/security-and-deployment.md

@@ -52,7 +52,7 @@ responsibility.
 - **Redeclare a run id.** The same identity with a *different* input is refused
   as `RunConflictError` (409 in the Rails adapter) rather than executed
   ("refuses the same identity with a changed input as a conflict").
-- **Run the same tool twice.** A resume is recorded once; a second answer to the
+- **Run the same tool twice.** A resume is recorded once; a new run that answers the
   same interrupt is refused without executing the tool ("refuses a decision
   another resume already recorded, without executing the tool").
 - **Widen what an approval covers.** An interrupt pins the tool call and the

data/docs/_core_features/reconnects.md

@@ -29,6 +29,12 @@ The store reserves a run before any provider work. It keys the record by authent
 
 Reconnect does not replay text or tool deltas. Replaying deltas could display text twice or repeat a side effect. The host can publish a state snapshot for a finished run, but the gem does not reconstruct conversation history.
 
+The same rule applies to a completed approval-resume run. Resend its exact
+input, including `resume`, with the original run id to receive the recorded
+outcome without applying the decision again. A new run id that tries to answer
+an already answered interrupt is refused. Changing the input under an existing
+run id is a conflict.
+
 ## Choose a Store
 
 `MemoryStore` is suitable for tests and a single process. Its records disappear on restart and are not shared between workers. The Rails adapter's `ActiveRecordStore` persists records and redeems interrupts under a database lock.

data/docs/_core_features/streaming-runs.md

@@ -45,5 +45,6 @@ The run record reaches a terminal state before the terminal event is written. If
 ## Next Steps
 
 * [Validating Input]({% link _core_features/input-validation.md %}) - parse untrusted request data.
+* [Tool Progress]({% link _core_features/tool-progress.md %}) - publish local tool updates.
 * [Approval and Resume]({% link _core_features/approval-and-resume.md %}) - answer an interrupt on a new run.
 * [Reconnects and Run Identity]({% link _core_features/reconnects.md %}) - serve a completed run again.

data/docs/_core_features/tool-progress.md

@@ -0,0 +1,90 @@
+---
+layout: default
+title: Tool Progress
+nav_order: 5
+description: Publish local tool progress as redacted AG-UI activity snapshots.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to enable tool progress globally or for one run.
+* How progress snapshots identify a tool call and replace earlier values.
+* How to choose which progress values reach the client.
+
+## Enable Progress
+
+Long tools can report their work before the result arrives. Enable progress
+when your client handles AG-UI activity messages:
+
+```ruby
+RubyLLM::AgUI.configure do |config|
+  config.emit_tool_progress = true
+end
+```
+
+The default is `false`. You can override it on one run with
+`Run.new(chat: chat, input: input, scope: scope, store: store,
+emit_tool_progress: true)`. Set the per-run option to `false` to disable a global
+opt-in. The Rails concern uses the global setting.
+
+The gem listens to RubyLLM's `after_tool_progress(tool_call, progress)` callback.
+Your RubyLLM tool reports progress through its own `progress` method. The gem
+publishes only values that the tool reports; it does not estimate a percentage
+or make up a total.
+
+## Choose a Redaction Policy
+
+Progress can include private messages. Its values pass through the configured
+redactor with kind `:tool_progress`. The default replaces each reported value
+with `[redacted]`, including numeric values. The tool call identifier remains
+available so the client can associate the activity with the existing call.
+
+For example, a host can publish counts while withholding messages:
+
+```ruby
+RubyLLM::AgUI.configure do |config|
+  config.emit_tool_progress = true
+  config.redact = lambda do |kind, payload|
+    if kind == :tool_progress
+      payload.slice('value', 'total')
+    else
+      RubyLLM::AgUI::Redaction.default(kind, payload)
+    end
+  end
+end
+```
+
+Use `Redaction.method(:none)` only for host-approved public data. The same
+policy still protects tool results with kind `:tool_result`.
+
+## Read an Activity Snapshot
+
+With counts approved by the host, a tool update can produce:
+
+```json
+{"type":"ACTIVITY_SNAPSHOT","messageId":"run-1:progress:call-1","activityType":"TOOL_PROGRESS","content":{"toolCallId":"call-1","progress":{"value":1,"total":3}},"replace":true}
+```
+
+Each tool call has one activity id per run. Later updates replace that
+activity's content. Unknown fields are absent: a message-only update has no
+`value` or `total`. Empty progress updates produce no event.
+
+Snapshots do not open another tool call, change an approval, or determine the
+run outcome. Updates for a tool whose result has arrived are ignored, as are
+callbacks after the run closes. Concurrent callbacks and run finalization use
+the same lock so progress cannot be written after the terminal event.
+
+Progress is not retained for reconnect. A completed-run reconnect serves its
+recorded outcome and optional state snapshot, without replaying activity,
+text, or tool deltas. No `ACTIVITY_DELTA` events are produced.
+
+## Next Steps
+
+* [Client Example]({% link _advanced/client-example.md %}) - try a real client with offline tools.
+* [Configuration]({% link _getting_started/configuration.md %}) - choose run defaults.
+* [Protocol Coverage]({% link _reference/protocol-coverage.md %}) - inspect supported events.

data/docs/_getting_started/configuration.md

@@ -32,12 +32,13 @@ p RubyLLM::AgUI.config.to_h[:redact]
 
 ## Settings
 
-The global configuration supplies defaults. `Run.new` can override the store, logger, redaction policy, clock, and interrupt expiry for one run. `MemoryStore` is process-local, so use a durable store when runs can move between workers.
+The global configuration supplies defaults. `Run.new` can override the store, logger, redaction policy, clock, interrupt expiry, and tool progress for one run. `MemoryStore` is process-local, so use a durable store when runs can move between workers.
 
 | Setting | Default | Purpose |
 | --- | --- | --- |
 | `run_store` | `nil` | Store run records and interrupts. A run needs a store, supplied here or to `Run.new`. |
 | `redact` | `Redaction.default` | Transform tool results before they reach the stream. |
+| `emit_tool_progress` | `false` | Publish tool progress as redacted activity snapshots. |
 | `logger` | `nil` | Receive host-side diagnostics without prompts or raw tool payloads. |
 | `protocol_version` | `"1.0"` | Value reported by `RUN_STARTED`. |
 | `max_input_bytes` | `256_000` | Maximum request body size. |

data/docs/_getting_started/whats-new-in-0-2.md

@@ -0,0 +1,53 @@
+---
+layout: default
+title: "What's New in 0.2"
+nav_order: 0
+description: Verify real AG-UI client workflows and opt in to redacted tool progress.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to publish tool progress without exposing private messages.
+* How to run the maintained browser client example.
+* Which client checks run offline and which provider checks remain separate.
+
+## Publish Tool Progress
+
+Enable activity snapshots when your client supports them:
+
+```ruby
+RubyLLM::AgUI.configure do |config|
+  config.emit_tool_progress = true
+end
+```
+
+Progress is off by default. Each tool call has a stable activity id and later
+snapshots replace earlier values. Values pass through the host redaction policy;
+late callbacks cannot write after the run closes. See
+[Tool Progress]({% link _core_features/tool-progress.md %}).
+
+## Run the Official Client Locally
+
+```sh
+bundle install
+npm ci
+bin/check-browser
+```
+
+The maintained example connects a pinned official `@ag-ui/client` to plain Ruby
+and Rails endpoints. It covers text, a second turn, approval/denial, progress,
+completed-run reconnect, sanitized failure, and cancellation outcomes. The Rails
+endpoint uses a generated migration and temporary SQLite database. See
+[Client Example]({% link _advanced/client-example.md %}).
+
+Browser screenshots, event traces, and schema validation are local fixture
+evidence. They do not establish live provider behavior, all-client compatibility,
+or remote CI success. The opt-in live spec now shares an actor-scoped setup
+with an offline harness check. See
+[Compatibility]({% link _reference/compatibility.md %}) and
+[Upgrading]({% link _reference/upgrading.md %}) before updating your application.

data/docs/_reference/compatibility.md

@@ -21,15 +21,16 @@ dependency does.
 
 ## Supported versions
 
-| Component | Range | Verified |
+| Component | Range | Evidence |
 |---|---|---|
-| Ruby | `>= 3.2` | 3.2, 3.3, 3.4 in CI; 3.3.5 locally |
+| Ruby | `>= 3.2` | CI passes on 3.2.11, 3.3.12, and 3.4.11; 3.3.5 checked locally |
 | RubyLLM | `>= 2.1`, `< 3.0` | 2.1.1 (callback, approval and cancellation behavior read from its source) |
 | `ag-ui-protocol` | `~> 0.2.0` | 0.2.0 |
-| Rails (adapter only) | `railties`, `actionpack`, `activerecord` `>= 8.0` | 8.0.x and 8.1.x in CI |
+| Rails (adapter only) | `railties`, `actionpack`, `activerecord` `>= 8.0` | CI passes on 8.0.5.1 and 8.1.4 with Ruby 3.3/3.4; 8.1.4 checked locally |
 | AG-UI schema | pinned commit `89cedd3fd549feeee41e50e1d7c6d373e549241a` | vendored, SHA-256 recorded in [AG-UI Protocol Coverage]({% link _reference/protocol-coverage.md %}) |
 
-The pure-Ruby core depends only on `ruby_llm` and `ag-ui-protocol`. Rails,
+The pure-Ruby core uses `ruby_llm` and `ag-ui-protocol`, plus the patched
+standard-library gems required by the gemspec. Rails,
 `ToolViews`, `OpenUI` and `OddlyDock` are not runtime dependencies, and the Rails
 adapter is only loaded when `Rails::Railtie` is already defined.
 
@@ -52,15 +53,40 @@ adapter is only loaded when `Rails::Railtie` is already defined.
 
 The RSpec suite runs offline with fakes and no provider credentials. Package verification uses the network only to install dependencies, then runs its core and Rails checks without a provider. Its advisory check includes the actual default-library gem versions activated by the isolated core install.
 
+## Recorded Client Verification
+
+On 2026-10-19, the local 0.2.0 candidate passes the maintained browser workflows
+with `@ag-ui/client` 1.0.3, Playwright 1.64.1, and Chrome 155.0.8059.82 on macOS.
+Both the plain Ruby and Rails endpoints use scripted chats. Checks cover text,
+a second turn, approval/denial, incremental progress before completion, default
+tool-result redaction, sanitized failure, cancellation, and exact completed-run
+reconnect, including a completed resume run. Captured events also validate
+against the pinned schema. The progress demo publishes synthetic counts through
+a host policy and withholds messages; unit tests check default progress redaction.
+
+Run `bin/check-browser` to reproduce and inspect screenshots and events under
+`tmp/browser/`. `bin/check --package` separately installs the built artifact
+outside the checkout, checks both endpoints, and generates RubyLLM models and
+ordered example migrations to verify scoped chat persistence. This package
+probe uses available development dependencies; `bin/verify-package` checks a
+clean gem home with freshly resolved dependencies.
+
+The [2026-10-19 CI run](https://github.com/yorzi/ruby_llm-ag-ui/actions/runs/39179834370)
+passes all ten jobs at `4aba0dc`: the Ruby and Rails matrices above, lint,
+installed-host verification, and the browser suite on Ubuntu 24.04.
+The browser job uses Playwright's Chromium 156.0.8078.4 and passes all 12
+scenarios, with 154 consumed events validated against the schema. Its desktop
+progress and mobile denial screenshots were also inspected. These remain
+synthetic checks; no live provider session is recorded.
+
 ## What is not asserted
 
-- **Real AG-UI clients** (CopilotKit, `@ag-ui/client`, any other consumer). No
-  client has been recorded against this producer. The events are schema-valid and
-  the ordering rules the protocol documents are enforced, but "a specific client
-  renders this correctly" is a separate claim, and it is not made here.
+- **Other clients or versions.** CopilotKit and client versions other than the
+  recorded `@ag-ui/client` version have not been verified. Schema conformance
+  does not establish that every UI renders the events correctly.
 - **Live providers.** `spec/live/live_run_spec.rb` is the opt-in check
-  (`RUBY_LLM_LIVE=1`, plus a provider key); it is skipped in the default suite.
-  Provider behavior in 2.1.1 is derived from its source, not from a recorded
+  (`RUBY_LLM_LIVE=1`, plus a provider key); its provider context is skipped in the default suite. The same run setup
+  is exercised separately with an offline chat. Provider behavior in 2.1.1 is derived from its source, not from a recorded
   session.
 - **Every RubyLLM patch release in the `>= 2.1, < 3.0` range.** The upper bound
   is enforced by the gemspec; the verified version is 2.1.1.
@@ -83,9 +109,9 @@ These are choices, not gaps, and each has a reason:
   repeating it would duplicate the call in the client's conversation.
 - **`MESSAGES_SNAPSHOT` is never produced.** History is the host's, and the gem
   will not re-id it. `STATE_SNAPSHOT` is produced, on a reconnect.
-- **No `ACTIVITY_*`, `REASONING_*`, `RAW` or `SUBAGENT_*` events.** RubyLLM 2.x
-  exposes no data for them on the supported path, and the gem does not invent
-  events. A thinking-only chunk produces nothing.
+- **Tool progress is opt-in.** `ACTIVITY_SNAPSHOT` carries local tool progress
+  when enabled. `ACTIVITY_DELTA`, `REASONING_*`, `RAW` and `SUBAGENT_*` remain
+  unproduced. A thinking-only chunk produces nothing.
 - **Message ids are the gem's** (`run-<id>:a<n>`), scoped to the run, because
   RubyLLM streaming chunks carry no message id.
 - **Steps are per phase** (`completion`, `tool`), named `step-<n>` per run.

data/docs/_reference/protocol-coverage.md

@@ -66,11 +66,12 @@ Legend:
 | `TOOL_CALL_RESULT` | tool | The tool result, after the host redaction policy. |
 | `STATE_SNAPSHOT` | state | On a reconnect: the state the host gave the run. |
 
-### Optional (1)
+### Optional (2)
 
 | Event type | Family | When |
 |---|---|---|
 | `CUSTOM` | raw/custom | Only safe, documented host extensions. Nothing in the gem emits one today. |
+| `ACTIVITY_SNAPSHOT` | activity | Local tool progress when `emit_tool_progress` is enabled, after host redaction. |
 
 ### Host-owned, not produced (2)
 
@@ -79,14 +80,13 @@ Legend:
 | `MESSAGES_SNAPSHOT` | state | The conversation belongs to the host. Producing one would mean re-synthesizing message ids the gem did not mint, which a client would then render as new messages. |
 | `STATE_DELTA` | state | Deltas describe a change the host made. The gem never invents a patch, and it has no API that publishes one. |
 
-### Not produced (15)
+### Not produced (14)
 
 | Event type | Family | Why |
 |---|---|---|
 | `TEXT_MESSAGE_CHUNK` | text | Convenience form of the explicit triad; the gem emits `START`/`CONTENT`/`END`. |
 | `TOOL_CALL_CHUNK` | tool | Convenience form; the gem emits the explicit triad. |
-| `ACTIVITY_SNAPSHOT` | activity | No `ACTIVITY_*` projection yet; RubyLLM's progress signals are not mapped. |
-| `ACTIVITY_DELTA` | activity | Same: no progress projection, and no invented patches. |
+| `ACTIVITY_DELTA` | activity | Progress uses full snapshots; no patches are produced. |
 | `RAW` | raw/custom | The gem never passes provider payloads through. |
 | `REASONING_START` | reasoning | Private reasoning is not emitted until a host opts in, and there is no opt-in yet. |
 | `REASONING_MESSAGE_START` | reasoning | A chunk that carries thinking is ignored. |
@@ -99,7 +99,7 @@ Legend:
 | `SUBAGENT_FINISHED` | subagents | Same. |
 | `SUBAGENT_ERROR` | subagents | Same. |
 
-Totals: 13 produced + 1 optional + 2 host-owned + 15 not produced = **31**.
+Totals: 13 produced + 2 optional + 2 host-owned + 14 not produced = **31**.
 
 ## Terminal events
 
@@ -172,4 +172,5 @@ must produce no event at all.
 ## Next Steps
 
 * [Streaming Runs]({% link _core_features/streaming-runs.md %}) - follow event order and outcomes.
+* [Tool Progress]({% link _core_features/tool-progress.md %}) - opt in to activity snapshots.
 * [Compatibility]({% link _reference/compatibility.md %}) - see what this repository verifies.

data/docs/_reference/release-history.md

@@ -11,12 +11,13 @@ description: Review RubyLLM AG-UI releases, newest first, with highlights and up
 {{ page.description }}
 {: .fs-6 .fw-300 }
 
-{% if site.docs_unreleased %}This build follows `main`. The latest stable release is `{{ site.version }}`.
+{% if site.docs_unreleased %}This build follows `main` for version `{{ site.version }}` development. Select Stable in the version menu for the published release.
 {% else %}This documentation describes version `{{ site.version }}`. Use its tag and release notes to identify the exact source.
 {% endif %}
 
 | Release | Date | Highlights |
 | --- | --- | --- |
-| [0.1.0](https://github.com/yorzi/ruby_llm-ag-ui/releases/tag/v0.1.0) | 2026-10-18 | [First release]({% link _getting_started/whats-new-in-0-1.md %}): AG-UI event mapping, approval and resume, cancellation, reconnect, and the optional Rails adapter |
+| [0.2.0](https://github.com/yorzi/ruby_llm-ag-ui/releases/tag/v0.2.0) | 2026-10-19 | [Client workflows and tool progress]({% link _getting_started/whats-new-in-0-2.md %}): opt-in redacted progress, a real-client demo, and completed resume reconnect |
+| [0.1.0](https://github.com/yorzi/ruby_llm-ag-ui/releases/tag/v0.1.0) | 2026-10-18 | [First release]({% link _reference/whats-new-in-0-1.md %}): AG-UI event mapping, approval and resume, cancellation, reconnect, and the optional Rails adapter |
 
 To move an application from one release to the next, follow [Upgrading]({% link _reference/upgrading.md %}).

data/docs/_reference/releasing.md

@@ -20,16 +20,31 @@ After reading this guide, you will know:
 
 ```bash
 bundle exec rake
+npm ci
+bin/check-browser
 bundle exec bundle-audit check --update
 bundle exec rake build
+bundle exec ruby scripts/check_package_host.rb --built
 bundle exec ruby bin/verify-package --rails --audit
 docs/bin/build.sh
+python3 scripts/check_docs_links.py
 ```
 
 The package check installs dependencies in a fresh temporary gem home and requires the installed artifact from outside the checkout. It verifies the core entrypoint, shipped templates and guides, and input parsing. With `--rails`, it invokes the documented generator and migrates its table up and down in SQLite. With `--audit`, it checks the actually activated core dependencies against the advisory database.
 
 These checks make no live provider call. Keep provider and client interoperability evidence in [Compatibility]({% link _reference/compatibility.md %}).
 
+Install the documentation bundle before building the site: run `bundle install`
+from `docs/`. API HTML and Markdown use the RDoc version locked in that bundle,
+so local and CI builds use the same navigation and parser.
+
+## Review Release Scope
+
+Use the repository's [roadmap](https://github.com/yorzi/ruby_llm-ag-ui/blob/main/ROADMAP.md)
+for proposed iterations and the 1.0 release conditions. Guides describe available
+behavior; the roadmap describes planned work. Check the release's conditions
+before preparing its tag.
+
 ## Configure Trusted Publishing
 
 Before the first tag, register a pending trusted publisher on RubyGems with gem name `ruby_llm-ag_ui`, GitHub owner `yorzi`, repository `ruby_llm-ag-ui`, workflow `release.yml`, and environment `release`. The workflow uses a short-lived GitHub OIDC identity instead of a stored RubyGems API key.

data/docs/_reference/upgrading.md

@@ -15,28 +15,33 @@ After reading this guide, you will know:
 * How to move between versioned releases.
 * Where to find changes that need code updates.
 
-## One Release at a Time
+## Move from 0.1 to 0.2
 
-Version `0.1.0` is the first release. There is no earlier published version to upgrade from. Start with [Getting Started]({% link _getting_started/getting-started.md %}). For future releases, upgrade one release at a time.
-
-## Install Version 0.1
+Change your Gemfile and update the dependency:
 
 ```ruby
-gem 'ruby_llm-ag_ui', '~> 0.1.0'
+gem 'ruby_llm-ag_ui', '~> 0.2.0'
+```
+
+```sh
+bundle update ruby_llm-ag_ui
 ```
 
-If you used an untagged development checkout, review [Configuration]({% link _getting_started/configuration.md %}) and [Rails Integration]({% link _advanced/rails-integration.md %}) before changing the dependency. No compatibility with earlier untagged checkouts is promised.
+The 0.2 release keeps the 0.1 run, store, and Rails APIs. It does not require
+another migration or installer run.
 
-## Use the Full Generator Command
+Tool progress is off by default. Set `config.emit_tool_progress = true` only
+when your client handles activity snapshots, and review its redaction policy.
+See [Tool Progress]({% link _core_features/tool-progress.md %}).
 
-Untagged development checkouts registered the shorter `ruby_llm:ag_ui` namespace. Version 0.1 registers the documented installation command:
+## Completed Resume Retries in 0.2
 
-```bash
-# Before, on an untagged checkout
-bin/rails generate ruby_llm:ag_ui
+An exact retry of a completed resume run now returns its recorded outcome.
+Keep the original run id and full input, including `resume`. A new run id that
+tries to answer an already answered interrupt is still refused, and changed
+input under the original id is a conflict. No approval or tool is executed again.
 
-# Version 0.1
-bin/rails generate ruby_llm:ag_ui:install
-```
+## Older Development Checkouts
 
-Existing generated tables and initializers do not need to be regenerated for this command-name correction.
+For the initial release's generator namespace correction, read the
+[0.1 upgrading guide](https://github.com/yorzi/ruby_llm-ag-ui/blob/v0.1.0/docs/_reference/upgrading.md).

data/docs/{_getting_started → _reference}/whats-new-in-0-1.md

@@ -1,7 +1,8 @@
 ---
 layout: default
 title: "What's New in 0.1"
-nav_order: 0
+nav_order: 1
+parent: Release History
 description: Use the first RubyLLM AG-UI release to stream, resume, cancel, and reconnect agent runs.
 ---
 

data/lib/ruby_llm/ag_ui/configuration.rb

@@ -28,6 +28,10 @@ module RubyLLM
       # RubyLLM::AgUI::Redaction.method(:none), or replace it with your policy.
       attr_writer :redact
 
+      # Whether runs publish local tool progress as activity snapshots. Off
+      # unless the host opts in; progress payloads still pass through redaction.
+      attr_accessor :emit_tool_progress
+
       # A Logger used for host-side diagnostics. Never receives prompts, raw
       # tool payloads or credentials.
       attr_accessor :logger
@@ -71,6 +75,7 @@ module RubyLLM
         @interrupt_ttl = 900
         @clock = -> { Time.now.utc }
         @allow_client_history = false
+        @emit_tool_progress = false
       end
 
       # The redaction policy in force. Never nil: an unset or nil policy falls
@@ -105,7 +110,8 @@ module RubyLLM
           max_tools: max_tools,
           max_context: max_context,
           interrupt_ttl: interrupt_ttl,
-          allow_client_history: allow_client_history
+          allow_client_history: allow_client_history,
+          emit_tool_progress: emit_tool_progress
         }
       end
     end

data/lib/ruby_llm/ag_ui/coverage.rb

@@ -66,8 +66,8 @@ module RubyLLM
         'MESSAGES_SNAPSHOT' => [:host_owned, 'Not produced: history is the host\'s; ids are never re-synthesized.'],
         'STATE_SNAPSHOT' => [:produced, 'Reconnect: the state the host gave the run, never replayed deltas.'],
         'STATE_DELTA' => [:host_owned, 'Not produced: patches are the host\'s to describe; the gem invents none.'],
-        'ACTIVITY_SNAPSHOT' => [:not_produced, 'No ACTIVITY_* projection yet; after_tool_progress is not mapped.'],
-        'ACTIVITY_DELTA' => [:not_produced, 'No ACTIVITY_* projection yet; the gem does not invent patches.'],
+        'ACTIVITY_SNAPSHOT' => [:optional, 'Opt-in local tool progress, after host redaction.'],
+        'ACTIVITY_DELTA' => [:not_produced, 'Progress uses full snapshots; the gem does not invent patches.'],
         'REASONING_START' => [:not_produced, 'Private reasoning is not emitted until a host opts in.'],
         'REASONING_MESSAGE_START' => [:not_produced, 'Never emitted; a chunk that carries thinking is ignored.'],
         'REASONING_MESSAGE_CONTENT' => [:not_produced, 'Never emitted; a chunk that carries thinking is ignored.'],

data/lib/ruby_llm/ag_ui/mapper.rb

@@ -53,6 +53,7 @@ module RubyLLM
         @last_message_id = nil
         @text_emitted = false
         @calls = {}
+        @completed_tools = {}
         @open_step = nil
         @step_kind = nil
         @warned_redaction = false
@@ -95,6 +96,23 @@ module RubyLLM
         events
       end
 
+      # Reports a tool's actual progress as a replacing activity snapshot.
+      # Each call has one run-scoped activity id. Values pass through the host's
+      # :tool_progress redaction policy; the tool call id remains structural.
+      # Empty updates and callbacks for finished tools or runs produce nothing.
+      def tool_progress(tool_call, progress)
+        return [] if @closed || @completed_tools[tool_call.id]
+
+        payload = { 'value' => progress.value, 'total' => progress.total, 'message' => progress.message }.compact
+        return [] if payload.empty?
+
+        [::AgUiProtocol::Core::Events::ActivitySnapshotEvent.new(
+          message_id: "#{@run_id}:progress:#{tool_call.id}", activity_type: 'TOOL_PROGRESS',
+          content: { 'toolCallId' => tool_call.id, 'progress' => redact(Redaction::TOOL_PROGRESS, payload) },
+          replace: true
+        )]
+      end
+
       # Closes any open text message, tool call and step, and closes the mapper.
       #
       # The caller writes these before the terminal event: AG-UI has no way to
@@ -261,6 +279,7 @@ module RubyLLM
       # --- tool results --------------------------------------------------------
 
       def tool_result_events(message)
+        @completed_tools[message.tool_call_id] = true
         events = close_text_events
         events.concat(close_tool_calls)
         events.concat(ensure_step(STEP_TOOL))
@@ -320,7 +339,7 @@ module RubyLLM
         return if @warned_redaction
 
         @warned_redaction = true
-        @logger&.warn('[ruby_llm_ag_ui] tool results are redacted by default; ' \
+        @logger&.warn('[ruby_llm_ag_ui] tool results and progress are redacted by default; ' \
                       'configure RubyLLM::AgUI.config.redact to publish them')
       end
 

data/lib/ruby_llm/ag_ui/redaction.rb

@@ -25,6 +25,7 @@ module RubyLLM
 
       # The kinds a policy is asked about.
       TOOL_RESULT = :tool_result
+      TOOL_PROGRESS = :tool_progress
 
       module_function
 

data/lib/ruby_llm/ag_ui/resume.rb

@@ -32,9 +32,13 @@ module RubyLLM
         @input.resume?
       end
 
-      # Checks every entry and builds the plan. Writes nothing, so a rejected
-      # resume is rejected before the run opens a stream.
+      # Checks a new resume and builds its plan before the run opens a stream.
+      # An existing identity is left to reservation and reconnect: an exact
+      # retry reports its recorded outcome, never redeems the decision twice.
       def plan(now:)
+        existing = @store.find(scope: @scope, thread_id: @input.thread_id, run_id: @input.run_id)
+        return self if existing
+
         source = interrupted_run
         @plan = @input.resume.map { |entry| plan_entry(source, entry, now) }
         self

data/lib/ruby_llm/ag_ui/run.rb

@@ -25,15 +25,17 @@ module RubyLLM
 
       # rubocop:disable-next Metrics/ParameterLists -- one keyword per host-supplied or overridable value
       def initialize(chat:, input:, scope:, store: nil, logger: nil, redact: nil, clock: nil, expires_in: nil,
-                     state: nil)
+                     state: nil, emit_tool_progress: RubyLLM::AgUI.config.emit_tool_progress)
+        defaults = RubyLLM::AgUI.config
         @chat = chat
         @input = input
         @scope = scope
-        @store = store || RubyLLM::AgUI.config.run_store!
-        @logger = logger || RubyLLM::AgUI.config.logger
+        @store = store || defaults.run_store!
+        @logger = logger || defaults.logger
         @redact = redact
-        @clock = clock || RubyLLM::AgUI.config.clock
-        @expires_in = expires_in || RubyLLM::AgUI.config.interrupt_ttl
+        @clock = clock || defaults.clock
+        @expires_in = expires_in || defaults.interrupt_ttl
+        @emit_tool_progress = emit_tool_progress
         @mutex = Mutex.new
         validate!
         @state = state.nil? ? @input.state : state
@@ -84,16 +86,20 @@ module RubyLLM
       end
 
       def execute(record, to)
-        @mapper = build_mapper(record)
-        @emitter = build_emitter(record, to, mapper: @mapper)
-        @emitter.start(run_started_event(record), state: @state)
+        start_execution(record, to)
         resume.apply(now: @clock.call) if resume.needed?
         drive
-        @record = finish
+        @record = finalize { finish }
       rescue RubyLLM::CancelledError
-        @record = @emitter.cancel
+        @record = finalize { @emitter.cancel }
       rescue StandardError => e
-        @record = @emitter.fail(e)
+        @record = finalize { @emitter.fail(e) }
+      end
+
+      def start_execution(record, to)
+        @mapper = build_mapper(record)
+        @emitter = build_emitter(record, to, mapper: @mapper)
+        @emitter.start(run_started_event(record), state: @state)
       end
 
       def build_emitter(record, to, mapper: build_mapper(record))
@@ -113,9 +119,14 @@ module RubyLLM
       def drive
         @chat.before_tool_call { |tool_call| project { @mapper.before_tool_call(tool_call) } }
         @chat.after_message { |message| project { @mapper.message(message) } }
+        if @emit_tool_progress == true
+          @chat.after_tool_progress { |call, progress| project { @mapper.tool_progress(call, progress) } }
+        end
         @chat.complete { |chunk| project { @mapper.chunk(chunk) } }
       end
 
+      def finalize(&) = @mutex.synchronize(&)
+
       def project
         @mutex.synchronize { @emitter.write(yield) }
       end

data/lib/ruby_llm/ag_ui/store/base.rb

@@ -9,7 +9,7 @@ module RubyLLM
     # already in progress instead of executing twice, and it keeps the
     # interrupts that a later resume has to answer.
     #
-    # Two stores ship with the gem: Store::MemoryStore, which is the default for
+    # Two stores ship with the gem: Store::MemoryStore for
     # a single process, and the optional Rails adapter's ActiveRecord store. A
     # host may implement this interface instead; every method must be safe to
     # call from concurrent threads.

data/lib/ruby_llm/ag_ui/version.rb

@@ -3,6 +3,6 @@
 module RubyLLM
   module AgUI
     # The version of the ruby_llm-ag_ui gem, as a string.
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-ag_ui
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andy Wang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ag-ui-protocol
@@ -142,16 +142,18 @@ files:
 - LICENSE.txt
 - README.md
 - SECURITY.md
+- docs/_advanced/client-example.md
 - docs/_advanced/rails-integration.md
 - docs/_advanced/security-and-deployment.md
 - docs/_core_features/approval-and-resume.md
 - docs/_core_features/input-validation.md
 - docs/_core_features/reconnects.md
 - docs/_core_features/streaming-runs.md
+- docs/_core_features/tool-progress.md
 - docs/_getting_started/configuration.md
 - docs/_getting_started/getting-started.md
 - docs/_getting_started/overview.md
-- docs/_getting_started/whats-new-in-0-1.md
+- docs/_getting_started/whats-new-in-0-2.md
 - docs/_reference/api-reference.md
 - docs/_reference/compatibility.md
 - docs/_reference/protocol-coverage.md
@@ -159,6 +161,7 @@ files:
 - docs/_reference/releasing.md
 - docs/_reference/third-party-notices.md
 - docs/_reference/upgrading.md
+- docs/_reference/whats-new-in-0-1.md
 - docs/index.md
 - lib/generators/ruby_llm/ag_ui/install_generator.rb
 - lib/generators/ruby_llm/ag_ui/templates/create_ruby_llm_ag_ui_runs.rb.tt