openui-rails 0.1.0 → 0.2.0

data/README.md

@@ -2,470 +2,80 @@
 
 [![CI](https://github.com/yorzi/openui-rails/actions/workflows/ci.yml/badge.svg)](https://github.com/yorzi/openui-rails/actions/workflows/ci.yml)
 
-[Documentation](https://openui-rails.wangyaodi.com/)
+Render streaming, interactive OpenUI Lang interfaces inside an existing Rails
+application. Use Rails views and Stimulus to mount the official browser runtime;
+keep authentication, authorization, and persistence in Rails.
 
-Render model-generated, streaming, interactive **OpenUI Lang** UI inside an
-existing Rails application — without migrating the whole frontend to a
-React/Next.js SPA and without hand-writing the stream, state and action glue
-for every screen.
+**Unofficial integration:** this project is not affiliated with or maintained by
+Thesys. It uses the OpenUI JavaScript runtime and does not implement a Ruby parser
+or renderer.
 
-> **Unofficial integration.** `openui-rails` is not affiliated with, endorsed
-> by, or maintained by Thesys. It reuses the official, version-pinned OpenUI
-> JavaScript runtime (loaded in the browser) and keeps Rails authoritative for
-> authentication, authorization and persistence. It is **not** a Ruby
-> reimplementation of OpenUI Lang — there is no Ruby parser or renderer in this
-> Gem.
+[Documentation](https://openui-rails.wangyaodi.com/) ·
+[RubyGems](https://rubygems.org/gems/openui-rails) ·
+[Roadmap](ROADMAP.md)
 
-## What it does
+## What you get
 
-- **Rails view helper + Stimulus bridge** that mounts the official OpenUI
-  renderer against a server-owned surface record.
-- **Versioned library/prompt contract** so the model prompt and the browser
-  component library are generated from the *same* library revision, with a
-  SHA-256 fingerprint persisted alongside the response.
-- **Ordered streaming** envelopes with snapshot recovery when chunks arrive out
-  of order or a client reconnects. Transport-agnostic: broadcast over Turbo
-  Streams or Action Cable.
-- **A single, authorized action loop**: component `onAction` and browser
-  `toolProvider` `Query()`/`Mutation()` calls both route through one allowlisted
-  endpoint with CSRF, tenancy, staleness and idempotency controls. It fails
-  closed.
-- **Optional RubyLLM adapter** that owns RubyLLM-specific event normalization.
+- A view helper and Stimulus bridge for rendering server-owned surfaces.
+- A shared library fingerprint for the prompt, browser runtime, and stored UI.
+- Ordered stream envelopes with gap detection over Turbo Streams or Action Cable.
+- One allowlisted action endpoint with authorization, validation, and replay protection.
+- An optional RubyLLM streaming adapter.
 
-RubyLLM is an optional integration, never a core dependency. Rails remains the
-source of truth for users, tenants and business objects.
+Your app supplies scoped record lookup, stream subscriptions, snapshot recovery,
+and shared idempotency storage when running multiple processes.
 
-## Requirements
+## Get started
 
-| Component | Supported |
-| --- | --- |
-| Ruby | `>= 3.2` |
-| Rails | `>= 8.0` (`< 9.0`) |
-| OpenUI browser runtime | pinned JS runtime, `@openuidev/browser-bundle` **0.2.1** |
-| OpenUI CLI (prompt generation) | pinned `@openuidev/cli` **0.6.0** |
-| RubyLLM | optional; **2.1.1** verified through its real OpenAI chat-completions SSE parser with mocked HTTP |
-
-Unknown provider/version combinations are *unsupported*, not implicitly
-compatible. The JavaScript runtime is always referenced by an exact version;
-there is no `@latest` or floating CDN range.
-
-> **Rails 8.0 note.** On the Rails 8.0.x line, use `json < 3`. Rails 8.0's
-> ActiveSupport and integration-test helpers pass a `quirks_mode:` keyword to
-> `JSON.generate` that `json` 3.1 removed; Rails 8.1 no longer does. CI covers
-> both lines (`RAILS_VERSION` in the `Gemfile` pins the matrix).
-
-## Installation
+Requires Ruby 3.2+ and Rails 8.0 or 8.1. On Rails 8.0, use `json < 3`.
+The runtime-fetch task also needs npm. RubyLLM is optional.
 
 ```ruby
 # Gemfile
-gem "openui-rails", "~> 0.1.0"
+gem "openui-rails", "~> 0.2.0"
 ```
 
-```bash
+```sh
 bundle install
 bin/rails generate openui:install
+bin/rails openui:runtime:fetch
+bin/rails openui:library:prepare
+bin/rails openui:doctor
 ```
 
-The generator writes `config/initializers/openui.rb`, creates `config/openui/`
-and mounts the engine:
-
-```ruby
-# config/routes.rb
-mount OpenUI::Rails::Engine => "/openui-rails"
-```
-
-It intentionally does **not** download the runtime or generate the library
-prompt — those are explicit, reproducible steps (below).
-
-## Quickstart
-
-### 1. Configure
-
-```ruby
-# config/initializers/openui.rb
-OpenUI::Rails.configure do |config|
-  config.transport = :turbo          # :turbo, :action_cable or :none
-  config.library_spec_path = Rails.root.join("config/openui/library.spec.json")
-  config.prompt_path       = Rails.root.join("config/openui/library.prompt.txt")
-  config.runtime_assets    = :self_hosted   # :self_hosted or :external
-
-  # Authz is required and fails closed: with no authorizer an action is denied.
-  config.authorize_action = ->(invocation) { invocation.actor.present? }
-
-  # Resolve a surface id to a record scoped to the actor/tenant. Returning nil
-  # is treated as an unknown/inaccessible surface and denies the action.
-  config.surface_resolver = ->(surface_id, actor:, **) {
-    actor&.surfaces&.find_by(id: surface_id)
-  }
-
-   # The engine inherits your ApplicationController, including authentication
-   # filters. It reads current_user by default; configure this for other auth.
-  config.actor_resolver = ->(controller) { controller.current_user }
-end
-```
-
-### 2. Generate the library prompt and spec
-
-The default browser bundle contains **only `openuiChatLibrary`**. Its prompt
-and spec must describe that exact library, not an unrelated custom library.
-The loaded bundle exposes `window.__OpenUI.openuiChatLibrary.prompt()` and
-`.toSpec()`. Save those outputs as the configured prompt text and JSON spec.
-The compatibility suite verifies this exact workflow against the pinned bundle.
-
-For a host-built custom library, use the pinned CLI and a matching host-built
-runtime that exposes the same `window.__OpenUI` contract. The CLI alone does
-not add components to the default browser bundle:
-
-```bash
-npx --yes @openuidev/cli@0.6.0 generate ./src/library.ts \
-  --out config/openui/library.prompt.txt --no-telemetry
-# rename the emitted library.prompt.txt.spec.json to library.spec.json
-# (or point library_spec_path at the generated name) and commit both.
-```
-
-Set `DO_NOT_TRACK=1` in CI as well as `--no-telemetry`.
-
-### 3. Self-host the pinned runtime
-
-```bash
-bin/rails openui:runtime:fetch   # vendors the bundle into public/openui (needs npm)
-```
-
-The task checks the archive and exact JS/CSS/license files against committed
-checksums. It disables npm lifecycle scripts and never extracts archive paths
-to disk. The default runtime and stylesheet use pinned SRI hashes.
-
-Include the stylesheet once in your layout's `<head>`:
-
-```erb
-<%= openui_stylesheet_tag %>
-```
-
-For external assets, configure both `runtime_url` and `runtime_stylesheet_url`
-with exact-version URLs. Supply their integrity hashes too.
-
-### 4. Register the Stimulus controllers
-
-The engine adds its `app/javascript` directory to the asset paths, so the
-controllers are available to the asset pipeline. For importmap, add the pins:
-
-```ruby
-# config/importmap.rb
-pin_all_from OpenUI::Rails::Engine.root.join("app/javascript/openui"), under: "openui"
-```
-
-```js
-// app/javascript/controllers/index.js
-import { application } from "controllers/application"
-import OpenUIController from "openui/rails/openui_controller"
-import OpenUIEnvelopeController from "openui/rails/openui_envelope_controller"
-
-application.register("openui", OpenUIController)
-application.register("openui-envelope", OpenUIEnvelopeController)
-```
-
-The `openui` controller mounts the renderer; `openui-envelope` is only needed
-for the Turbo Streams transport (below).
-
-### 5. Render a surface
+Follow [Getting Started](https://openui-rails.wangyaodi.com/getting-started/) to
+register the Stimulus controllers and include the stylesheet. After setup,
+render a surface from an ERB view:
 
 ```erb
-<%# @surface is any object exposing #id (and optionally #version,
-    #library_version, #response, #context, #message_id) %>
-<%= openui_surface(surface: @surface, stream: true) %>
-```
-
-Pass `label: "Order details"` to expose the mount as a named `region` landmark.
-A streaming surface carries `aria-busy="true"` until it completes, so assistive
-technology waits for the region to settle instead of announcing each delta.
-
-### 6. Register actions
-
-```ruby
-# config/initializers/openui.rb (or an initializer of your own)
-OpenUI::Rails.actions.register "orders.refresh",
-  description: "Re-fetch an order",
-  schema: { "orderId" => String },
-  authorize: ->(invocation) { OrderPolicy.new(invocation.actor, invocation.args["orderId"]).refresh? },
-  handler: ->(invocation) { OrderSerializer.new(Order.find(invocation.args["orderId"])).as_json }
-```
-
-## Rendering surfaces
-
-```ruby
-openui_surface(surface = nil, stream: false, dom_id: nil, initial_state: nil, label: nil, **options)
+<%= openui_surface(
+  surface: { id: "support-42", response: 'root = TextContent("How can I help?")' },
+  label: "Support"
+) %>
 ```
 
-`Surface.coerce` accepts a `Surface`, a plain `Hash`, or a host record. It
-emits a flat `data-openui-*` mount element; the Stimulus controller reads it and
-never receives a credential or a server secret. Recognised record methods:
-`id`, `version`, `library_version`, `response`, `context`, `message_id`.
+Actions are denied until you configure authorization.
 
-When a manifest is configured, the helper rejects an incompatible persisted
-`library_version`. Before mounting, the browser hashes the runtime library's
-`toSpec()` output and compares it with that manifest. A mismatch emits
-`openui:error` with `library_version_mismatch` and does not mount the renderer.
-Without a configured manifest, no library identity check is possible.
+## Documentation and development
 
-## Streaming
-
-The stream bridge normalizes model output into ordered envelopes and coalesces
-small chunks up to `pending_byte_limit` (default 32 KiB), enforcing
-`stream_byte_limit` (default 1 MiB).
-
-Envelope types: `openui.delta`, `openui.snapshot`, `openui.completed`,
-`openui.error`. Every envelope carries `message_id`, `sequence` (from `0`) and
-an optional `library_version`.
-
-```ruby
-bridge = OpenUI::Rails::Stream::Bridge.new(
-  message_id: surface.id, library_version: config.library_fingerprint
-)
-
-# Pull source (an Enumerable of chunks):
-bridge.envelopes(chunks).each { |envelope| broadcast(envelope) }
-
-# Push source (a streaming provider callback):
-writer = bridge.writer
-writer.push(chunk).each { |envelope| broadcast(envelope) }
-writer.finish.each { |envelope| broadcast(envelope) }
-```
-
-The browser controller applies envelopes in order, ignores duplicates, and
-requests a canonical snapshot (`openui:snapshot-required` event) when it detects
-a sequence gap. Deltas pause until a current snapshot arrives. Stale snapshots,
-duplicate terminal frames, malformed frames, and post-completion deltas cannot
-rewind or extend a completed response. The browser also enforces the byte limit.
-
-The controller **receives** `openui:envelope` and emits `openui:action`,
-`openui:state`, `openui:error`, and `openui:snapshot-required`. Your host must
-fetch and dispatch the authoritative snapshot on a gap or reconnect. The gem
-does not provide a persistence layer or snapshot HTTP endpoint.
-
-### Transports
-
-`Stream::Broadcaster` binds the bridge to a transport and broadcasts each
-envelope as it is produced. Delivery is best effort — neither Action Cable nor
-Turbo Streams guarantee order — which is exactly why the client applies
-sequence numbers and recovers from a snapshot on a gap.
-
-```ruby
-transport = OpenUI::Rails::Stream::Transports.build(:action_cable, stream_name: "openui:surface:#{surface.id}")
-# or: Transports.build(:turbo, stream: surface, target: "openui-surface-#{surface.id}")
-# or: Transports.build(:memory)   # tests/examples
-
-broadcaster = OpenUI::Rails::Stream::Broadcaster.new(
-  transport: transport, message_id: surface.id, library_version: config.library_fingerprint
-)
-chat.complete { |chunk| broadcaster.push(chunk.content) }
-broadcaster.finish
-```
-
-- **Action Cable** (`:action_cable`) broadcasts the envelope hash. Subscribe in
-  the browser and re-emit it as an event; authorization for the subscription
-  stays in your channel:
-
-  ```js
-  import { createConsumer } from "@rails/actioncable"
-  const consumer = createConsumer()
-  consumer.subscriptions.create(
-    { channel: "YourStreamChannel", stream: "openui:surface:42" },
-    { received: (data) =>
-        document.dispatchEvent(new CustomEvent("openui:envelope", { bubbles: true, detail: data })) }
-  )
-  ```
-
-- **Turbo Streams** (`:turbo`) appends an `openui-envelope` element to a target
-  already in the DOM. The `openui-envelope` controller re-emits the envelope as
-  a bubbling `openui:envelope` event and removes itself — no inline script, no
-  CSP relaxation. This transport requires `turbo-rails` in the host; it is
-  looked up lazily and never a hard dependency of this Gem.
-
-  Subscribe with `<%= turbo_stream_from stream %>` and provide a dedicated
-  inbox, such as `<div id="openui-inbox" hidden></div>`. Pass that inbox's ID
-  as `target:`. Keep the inbox outside the React-owned subtree. Restrict stream
-  subscription and signed-stream access to authorized users in your host.
-
-- **Memory** (`:memory`) keeps every envelope in memory for tests and examples.
-
-The surface controller listens for `openui:envelope` on `document`, so any
-transport that produces a bubbling event (or dispatches on the element) works,
-and envelopes for other `message_id`s are ignored.
-
-## The action loop
-
-Component `onAction` and browser `toolProvider` `Query()`/`Mutation()` calls
-post the same body to the single endpoint (`/openui-rails/actions` by default):
-
-```json
-{ "action": "orders.refresh", "args": {}, "surface_id": "…", "version": 3,
-  "idempotency_key": "…", "confirmed": false }
-```
-
-The official component event uses `{ type, params }`; the bridge maps it to
-`action` and `args`. A tool receives the handler's `value`, not the endpoint's
-result wrapper. Unknown tool names still fail the server allowlist.
-
-`confirmed: true` is a host-supplied acknowledgement, not cryptographic proof
-of human consent. It is never inferred from `params` or form state. Collect
-confirmation in trusted host UI. For high-risk operations, verify a signed,
-server-issued approval in the authorizer as well.
-
-The `Actions::Dispatcher` applies every gate **before any side effect**, in
-order:
-
-1. submission parse/validate
-2. action is registered (allowlist — no reflection from a name to a method)
-3. args match the schema (required/optional types, extra keys rejected)
-4. explicit `confirmed: true` when the action is destructive
-5. surface revision is current (stale protection)
-6. authorizer allows it (required; fail closed)
-7. idempotency claim (duplicates never run twice, replay with different args is rejected)
-
-Idempotency keys are scoped to the server actor and tenant. The request digest
-also binds the action, surface, version, arguments, and confirmation flag.
-See [configuration](CONFIGURATION.md) for the shared-store contract and TTL
-limits. This is not an exactly-once guarantee across expiry or process restarts.
-
-Structured errors (JSON `{ error: { code, message } }`):
-
-| Code | Status | Meaning |
-| --- | --- | --- |
-| `unknown_action` | 404 | not in the registry |
-| `unauthorized` | 403 | authorizer denied, no authorizer, or unresolvable surface |
-| `stale_surface` | 409 | submitted against a superseded revision |
-| `replay` | 409 | idempotency key reused |
-| `invalid_action` | 422 | malformed payload/args or missing confirmation |
-| `csrf_failed` | 422 | invalid authenticity token |
-
-## Message protocol
-
-`OpenUI::Rails::Message` implements the upstream `buildMessage`/`parseMessage`
-framing (marker lines beginning with `]]>openui:`). Use it to store a response
-so the browser `Renderer` can read both content and context, and to strip the
-markers before a stored message is sent back to a model:
-
-```ruby
-stored = OpenUI::Rails::Message.build(content: lang, context: { form: form_state }, finished: true)
-OpenUI::Rails::Message.strip(stored)        # => model-safe content, no markers
-OpenUI::Rails::Message.parse(stored).context
-```
-
-This is *message framing*, not an OpenUI Lang parser. Client-supplied context is
-untrusted input.
-
-## RubyLLM adapter
-
-Optional and never required. It owns RubyLLM event normalization and delegates
-sequencing/limits to the stream bridge, so a host keeps RubyLLM's own Rails
-streaming pattern:
-
-```ruby
-OpenUI::Rails::Adapters::RubyLLM.stream(
-  chat: chat, question: question, surface_id: surface.id
-) { |envelope| broadcast(envelope) }
-```
-
-`ruby_llm` is isolated under `OpenUI::Rails::Adapters`; failures are classified
-by class *name*, so no `RubyLLM` constant is referenced at load time.
-
-## Assets and CSP
-
-- The runtime is version-pinned and served from your app (or an exact-version
-  URL you configure). Self-hosting is the default.
-- You may pin subresource integrity via `config.runtime_integrity`; the fetch
-  task prints the digest to use.
-- To use a strict Content Security Policy, add a nonce/host for the runtime
-  script you serve. This bridge adds no inline scripts. The upstream renderer
-  does use inline styles and injects a loading `<style>` element. Strict
-  `style-src` policies need separate validation; script SRI is not proof of
-  strict-CSP compatibility.
-
-## Accessibility
-
-- A streaming surface is marked `aria-busy="true"` and flips to `"false"` when
-  it completes (or errors), so a screen reader waits for the region to settle.
-- Pass `label:` to `openui_surface` to expose the mount as a named `region`
-  landmark; without a label no role is added, so unnamed containers are not
-  invented.
-- The mount is not `aria-hidden`. Automated checks cover named regions,
-  streaming busy states, and real keyboard activation. A human screen-reader
-  audit of generated content has not been performed.
-
-## Security model
-
-Model output is untrusted UI DSL. The controls this Gem is responsible for:
-
-- **Allowlist only** — the browser can resolve only components and actions the
-  pinned library declares, and only actions registered in the Rails registry.
-- **One action path** — every write passes all seven gates above; no
-  model-provided name maps to Ruby reflection.
-- **Fail closed** — no authorizer means denied.
-- **Rails-owned identity** — CSRF protection, session auth and per-surface
-  version all come from Rails; surface ids are resolved scoped to actor/tenant.
-- **Untrusted context** — client form state is never treated as a write
-  confirmation, and `]]>openui:` markers are stripped before model history.
-- **Pinned supply chain** — exact runtime/CLI versions, optional integrity,
-  no production mutable CDN.
-
-Report vulnerabilities privately per [`SECURITY.md`](SECURITY.md).
-
-## Versioning and rollback
-
-- `0.x` releases allow documented breaking changes with migration notes; the
-  Ruby API is not frozen. See [`CHANGELOG.md`](CHANGELOG.md).
-- The JS runtime is version-locked, and a response is stored with its
-  prompt/library fingerprint, so a mismatched fingerprint is a **visible
-  failure** rather than rendering old source against a new schema.
-- Downgrading the Gem is the supported rollback; persisted snapshots are
-  readable by previous versions where the schema is compatible, otherwise they
-  degrade to a safe read-only/fallback with a diagnostic.
-
-## Status
-
-Early development. The public API may change between `0.x` releases.
-
-The audit fixed defects that the original stub-only tests missed. See
-[AUDIT.md](AUDIT.md) for findings, verification evidence, and publication gates.
-CI runs unit/integration tests, deterministic browser tests, the real pinned
-OpenUI bundle, real Turbo/Action Cable delivery, a RubyLLM 2.1.1 SSE probe,
-dependency advisory checks, and a fresh-host test of the built gem.
-
-A live-provider smoke completed through OpenRouter on 2026-10-18; see
-[`AUDIT.md`](AUDIT.md) for its scope and evidence. Releases use the verified
-artifact, RubyGems Trusted Publishing, and the protected GitHub `release`
-environment. See [RubyGems](https://rubygems.org/gems/openui-rails) and
-[GitHub Releases](https://github.com/yorzi/openui-rails/releases) for published
-versions. Hosts that redistribute the fetched browser bundle must review its
-complete transitive notices as described in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
-
-## Development
-
-```bash
-bundle install
-bundle exec bin/rails db:test:prepare
-bundle exec bin/rails test        # unit + integration
-bundle exec bin/rails test:system # browser (needs Chrome)
-bundle exec rubocop               # rubocop-rails-omakase
-bundle exec gem build openui-rails.gemspec
-```
+The documentation site contains the full guides and API reference:
 
-See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+- [Configuration](https://openui-rails.wangyaodi.com/configuration/)
+- [Streaming](https://openui-rails.wangyaodi.com/streaming/) and [server actions](https://openui-rails.wangyaodi.com/actions/)
+- [RubyLLM](https://openui-rails.wangyaodi.com/ruby-llm/) and [production setup](https://openui-rails.wangyaodi.com/production/)
+- [Upgrading](https://openui-rails.wangyaodi.com/upgrading/) and [API reference](https://openui-rails.wangyaodi.com/api-reference/)
 
-## Documentation
+Version `0.2.0` adds default-library preparation and setup diagnostics.
+The API may change during `0.x`; see the
+[changelog](CHANGELOG.md) and the proposed [path to 1.0](ROADMAP.md).
+The site's stable channel follows the latest release; [/next/](https://openui-rails.wangyaodi.com/next/)
+follows `main`.
 
-- [`CHANGELOG.md`](CHANGELOG.md)
-- [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)
-- [`CONTRIBUTING.md`](CONTRIBUTING.md)
-- [`CONFIGURATION.md`](CONFIGURATION.md)
-- [`UPGRADING.md`](UPGRADING.md)
-- [`AUDIT.md`](AUDIT.md)
-- [`RELEASING.md`](RELEASING.md)
-- [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
-- [`SECURITY.md`](SECURITY.md)
+For repository work, use [Contributing](CONTRIBUTING.md),
+[Releasing](RELEASING.md), and the dated [0.1.0 audit](AUDIT.md).
+Report vulnerabilities through the [security policy](SECURITY.md).
 
 ## License
 
-Released under the [MIT License](LICENSE). OpenUI and the `@openuidev/*`
-packages are MIT-licensed by Thesys ("Copyright (c) 2011-2024 Thesys Inc.");
-their notices ship in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+[MIT](LICENSE). See [third-party notices](THIRD_PARTY_NOTICES.md) before
+redistributing the OpenUI browser bundle.

data/RELEASING.md

@@ -1,7 +1,7 @@
 # Releasing openui-rails
 
-The owner authorized the initial `0.1.0` release on 2026-10-18. This is an
-unofficial integration, not a Thesys product. Publish only a tag whose complete
+This is an unofficial integration, not a Thesys product. Obtain owner
+authorization to push and publish each release. Publish only a tag whose complete
 CI suite and release metadata checks pass.
 
 ## Publishing configuration
@@ -12,9 +12,15 @@ administrator bypass. Self-review is available for the single maintainer.
 RubyGems trusts workflow `release.yml` and environment `release` through GitHub
 OIDC. No long-lived RubyGems API key is stored in GitHub.
 
-The initial pending publisher was registered on 2026-10-18. Pending publishers
-expire if unused; check the RubyGems settings before a delayed first publish.
-The first successful publication creates the gem and activates its publisher.
+The initial pending publisher was registered and successfully used for `0.1.0`
+on 2026-10-18. Future releases use the gem's Trusted Publisher. Update RubyGems
+trust before changing the repository, workflow filename, or environment.
+
+The documentation uses GitHub Pages with the GitHub Actions source. Its
+`github-pages` environment permits branch `main` and tags matching `v*`.
+Both rules are needed: a published release triggers the docs workflow with
+the release tag, even though the workflow checks out the default branch to
+build the stable and next documentation channels.
 
 Before each release, review [AUDIT.md](AUDIT.md), the dated changelog section,
 and the complete CI result for the exact commit. Preserve third-party notices.
@@ -40,7 +46,8 @@ and a 16-token output cap. See [AUDIT.md](AUDIT.md) for the result and limits.
    RELEASE_TAG=vx.y.z ruby bin/check-release
    ```
 
-5. Commit the version and notes.
+5. Commit and push the version and notes to `main`. Wait for the complete CI
+   suite to pass for that exact commit before tagging.
 6. Create the release tag:
 
    ```bash
@@ -73,8 +80,11 @@ write permission then creates a **draft** GitHub release.
 The draft includes the verified gem, its SHA-256 checksum, and the dated
 changelog section. Verify the RubyGems version and review that draft before
 making it public.
-`CHANGELOG.md` now contains the dated `0.1.0` notes, and
-`RELEASE_TAG=v0.1.0 ruby bin/check-release` accepts the release metadata.
+Publishing the GitHub release triggers the versioned documentation deployment.
+Verify the stable site names the released version, `/next/` follows `main`,
+and both channels include the matching setup and upgrading guides. Record
+the workflow, published gem checksum, and hosted verification in a dated
+release record. Keep earlier local validation evidence unchanged.
 
 ## Recovery
 

data/THIRD_PARTY_NOTICES.md

@@ -24,6 +24,16 @@ or referenced at an exact pinned version):
 
 The OpenUI repository is licensed MIT: "Copyright (c) 2011-2024 Thesys Inc."
 
+## Default-library exports
+
+The gem includes the `openuiChatLibrary.prompt()` and `toSpec()` exports from
+the exact pinned browser bundle under `lib/openui/rails/default_library/`.
+`provenance.json` records the runtime integrity pin and export checksums. The
+upstream MIT license accompanies them as `openui.LICENSE.txt` and is copied
+alongside application artifacts by `openui:library:prepare`. Preserve it when
+redistributing these exports. The exports contain library definitions and
+prompt instructions, not the browser renderer implementation.
+
 ## Transitive browser dependencies
 
 The official browser bundle inlines dependencies, including React 19. They do

data/UPGRADING.md

@@ -1,26 +1,9 @@
-# Pre-release audit changes
+# Upgrading
 
-These changes apply before the first published release.
+Read the [upgrade guide](https://openui-rails.wangyaodi.com/upgrading/)
+for migration steps and the [changelog](CHANGELOG.md) for release changes.
 
-- Custom idempotency stores must distinguish `:pending` from completed
-  `:replay`, return a claim token, and accept `record(..., claim_token:)`.
-  See [CONFIGURATION.md](CONFIGURATION.md).
-- Action arguments are canonical JSON copies with string keys. Submissions,
-  surfaces, envelopes, and manifests no longer share mutable caller input.
-- The engine controller inherits the host's `ApplicationController` and
-  preserves its authentication filters. Full-stack Rails controllers are
-  required. API-only controllers need a host-owned HTML/session/CSRF boundary;
-  that integration is not covered by this release.
-- The helper rejects a persisted surface whose library differs from the
-  configured manifest. The browser verifies the actual runtime `toSpec()`.
-  Custom prompt/spec files require a matching custom runtime, not the default
-  chat bundle.
-- Add `<%= openui_stylesheet_tag %>` once in your layout. The runtime fetch task
-  now installs checksum-verified JS, CSS, and the upstream license.
-- The RubyLLM adapter no longer passes a question argument to `Chat#complete`.
-  It adds the user message first. Both `:complete` and `:ask` work with 2.1.1.
-- Completion and error frames participate in sequence validation. After a gap,
-  all deltas pause until the host sends a current snapshot. Duplicate finishes
-  and writes after a terminal writer state produce no additional frames.
-- Tag pushes verify and build a release artifact. Publication now requires an
-  explicit manual workflow dispatch after the full CI suite succeeds.
+The site documents the latest release. For `main`, use
+[/next/upgrading/](https://openui-rails.wangyaodi.com/next/upgrading/).
+To read offline, open the [guide source](docs/_reference/upgrading.md)
+at the tag matching your installed gem.

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

@@ -39,13 +39,14 @@ module OpenUI
       say "openui-rails installed.", :green
       say ""
       say "Next steps:"
-      say "  1. Generate the library prompt and spec with the pinned CLI:"
-      say "     npx --yes @openuidev/cli@0.6.0 generate <entry> --out config/openui/library.prompt.txt --no-telemetry"
+      say "  1. Prepare the default chat library (no browser, Node, or provider required):"
+      say "     bin/rails openui:library:prepare"
       say "  2. Self-host the pinned runtime:"
       say "     bin/rails openui:runtime:fetch"
-      say "  3. Register actions and an authorizer (see config/initializers/openui.rb)."
-      say "  4. Pin/register the Stimulus controllers and include openui_stylesheet_tag in your layout."
-      say "     The default bundle requires the exact openuiChatLibrary prompt/spec. See the gem README."
+      say "  3. Pin/register the Stimulus controllers and include openui_stylesheet_tag in your layout."
+      say "  4. Run bin/rails openui:doctor, then verify rendering in a browser."
+      say "  5. Configure scoped surfaces and authorization before enabling actions."
+      say "     Custom libraries require a matching custom runtime; see config/openui/README.md."
       say ""
     end
 

data/lib/generators/openui/install/templates/config/initializers/openui.rb.tt

@@ -4,8 +4,8 @@ OpenUI::Rails.configure do |config|
   # Transport for incremental updates: :turbo, :action_cable or :none.
   config.transport = :turbo
 
-  # The prompt and spec generated from the same, pinned library revision by the
-  # OpenUI CLI. See config/openui/README.md for the exact command.
+  # Run bin/rails openui:library:prepare for the pinned default chat library.
+  # Custom prompt/spec files need a matching custom runtime.
   config.library_spec_path = Rails.root.join("config/openui/library.spec.json")
   config.prompt_path = Rails.root.join("config/openui/library.prompt.txt")