openui-rails 0.1.0 → 0.3.0

data/app/javascript/openui/rails/openui_controller.js

@@ -226,7 +226,7 @@ export default class extends Controller {
   async dispatchAction(payload = {}) {
     const body = {
       action: payload.action ?? payload.name ?? payload.type,
-      args: payload.args ?? payload.params ?? {},
+      args: this.actionArguments(payload),
       surface_id: this.surfaceId,
       version: this.version,
       idempotency_key: payload.idempotency_key ?? this.newIdempotencyKey(),
@@ -268,6 +268,19 @@ export default class extends Controller {
     }
   }
 
+  // The official renderer places conversation metadata beside params. Keep
+  // it in the allowlisted action's args so the host can validate and persist it.
+  actionArguments(payload) {
+    const args = payload.args ?? payload.params ?? {}
+    if ((payload.action ?? payload.name ?? payload.type) !== "continue_conversation") return args
+    if (typeof args !== "object" || Array.isArray(args)) return args
+    const metadata = {}
+    if (payload.humanFriendlyMessage !== undefined) metadata.message = payload.humanFriendlyMessage
+    if (payload.formState !== undefined) metadata.form_state = payload.formState
+    if (payload.formName !== undefined) metadata.form_name = payload.formName
+    return { ...args, ...metadata }
+  }
+
   // Every browser `Query()`/`Mutation()` tool call is routed to the same
   // server endpoint; the host registry decides what is permitted.
   toolProvider() {

data/examples/support_desk/README.md

@@ -0,0 +1,18 @@
+# Support Desk reference host
+
+This opt-in reference belongs to the host application, outside the engine's
+public API. It uses synthetic accounts, recorded generation, the real pinned
+OpenUI runtime, SQLite, importmap, and HTTP Turbo Streams.
+
+From the repository:
+
+```sh
+mkdir -p tmp/package
+bundle exec gem build openui-rails.gemspec --output tmp/package/openui-rails-0.3.0.gem
+bin/check-reference --gem tmp/package/openui-rails-0.3.0.gem --runtime tmp/real-runtime
+```
+
+Fetch the runtime first. See the [complete guide](https://openui-rails.wangyaodi.com/reference-workflow/)
+for setup, retained-host review, failure checks, and evidence limits. The
+reference is not enabled by requiring the gem. Keep the demo loopback-only;
+replace its synthetic login before adapting it to a real application.

data/examples/support_desk/app/controllers/support_desk/base_controller.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SupportDesk # :nodoc:
+  class BaseController < ::ApplicationController
+    protect_from_forgery with: :exception
+    layout "support_desk/application"
+    before_action :local_demo_only
+    before_action :authenticate
+    rescue_from ActiveRecord::RecordNotFound do
+      render json: { error: { code: "not_found", message: "inaccessible conversation" } }, status: :not_found
+    end
+    rescue_from OpenUI::Rails::Error do |error|
+      status = error.is_a?(OpenUI::Rails::StaleSurfaceError) ? :conflict : :unprocessable_content
+      code = error.is_a?(OpenUI::Rails::StaleSurfaceError) ? "stale_surface" : "invalid_state"
+      render json: { error: { code: code, message: "request rejected" } }, status: status
+    end
+
+    private
+
+    def current_actor
+      @current_actor ||= User.find_by(id: session[:support_desk_user_id])
+    end
+    helper_method :current_actor
+
+    def local_demo_only
+      head :forbidden unless [ "127.0.0.1", "::1" ].include?(request.remote_ip)
+    end
+
+    def authenticate
+      render json: { error: { code: "unauthorized", message: "sign in to the local demo" } }, status: :unauthorized unless current_actor
+    end
+
+    def conversation
+      @conversation ||= Conversation.find_by!(id: params[:id], user_id: current_actor.id, tenant_id: current_actor.tenant_id)
+    end
+  end
+end

data/examples/support_desk/app/controllers/support_desk/conversations_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module SupportDesk # :nodoc:
+  class ConversationsController < BaseController
+    # The state endpoint uses an explicit top-level JSON contract.
+    wrap_parameters false
+    skip_before_action :authenticate, only: :index
+
+    def index
+    end
+
+    def show
+      conversation
+    end
+
+    def stream
+      frames = conversation.generate!
+      transport = OpenUI::Rails::Stream::Transports::TurboStreams.new("unused", target: "desk-envelopes")
+      response.headers["Content-Type"] = "text/vnd.turbo-stream.html; charset=utf-8"
+      response.headers["Cache-Control"] = "no-store"
+      self.response_body = Enumerator.new do |body|
+        frames.each do |frame|
+          body << %(<turbo-stream action="append" target="desk-envelopes"><template>#{transport.element(frame)}</template></turbo-stream>\n)
+        end
+      end
+    end
+
+    def snapshot
+      if conversation.response.empty?
+        head :conflict
+      else
+        render json: conversation.snapshot.to_h
+      end
+    end
+
+    def state
+      record = conversation
+      body = request.request_parameters
+      unless (body.keys - %w[state version]).empty? && body["version"].is_a?(Integer) && body["version"] >= 0
+        raise OpenUI::Rails::InvalidActionError, "invalid state request"
+      end
+
+      record.save_form!(body["state"], expected_version: body["version"])
+      head :no_content
+    end
+  end
+end

data/examples/support_desk/app/controllers/support_desk/sessions_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SupportDesk # :nodoc:
+  class SessionsController < BaseController
+    skip_before_action :authenticate
+
+    def create
+      user = User.find_by!(name: params[:name])
+      reset_session
+      session[:support_desk_user_id] = user.id
+      redirect_to conversation_path(Conversation.find_by!(user_id: user.id))
+    end
+
+    def destroy
+      reset_session
+      redirect_to root_path
+    end
+  end
+end

data/examples/support_desk/app/javascript/support_desk.js

@@ -0,0 +1,109 @@
+import { Application, Controller } from "@hotwired/stimulus"
+import "@hotwired/turbo-rails"
+import OpenUIController from "openui/rails/openui_controller"
+import EnvelopeController from "openui/rails/openui_envelope_controller"
+
+class SupportDeskController extends Controller {
+  connect() {
+    this.abort = new AbortController()
+    this.saves = Promise.resolve()
+    this.lastState = null
+    if (this.surface.dataset.openuiStreaming === "true") this.stream().catch(error => this.failure(error))
+  }
+
+  disconnect() { this.abort.abort() }
+  get surface() { return this.element.querySelector("[data-controller='openui']") }
+  get status() { return this.element.querySelector("#desk-status") }
+
+  headers() {
+    return { "Content-Type": "application/json", "X-CSRF-Token": document.querySelector("meta[name='csrf-token']").content }
+  }
+
+  async checked(response) {
+    if (response.redirected || !response.ok) throw new Error(response.status === 401 || response.status === 403 ? "Session expired. Sign in again." : "Request rejected. Reload the conversation.")
+    return response
+  }
+
+  // Consume newline-delimited Turbo Stream elements as response chunks arrive.
+  // Authorization and canonical response persistence happen before delivery.
+  async stream() {
+    const response = await this.checked(await fetch(this.element.dataset.supportDeskStreamUrl, {
+      method: "POST", headers: this.headers(), signal: this.abort.signal, credentials: "same-origin"
+    }))
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let pending = ""
+    try {
+      while (true) {
+        const { value, done } = await reader.read()
+        pending += decoder.decode(value, { stream: !done })
+        let end
+        while ((end = pending.indexOf("\n")) >= 0) {
+          window.Turbo.renderStreamMessage(pending.slice(0, end))
+          pending = pending.slice(end + 1)
+        }
+        if (done) break
+      }
+      if (pending.trim()) throw new Error("Incomplete stream. Reload the conversation.")
+      this.status.textContent = "Response loaded"
+    } finally {
+      await reader.cancel().catch(() => {})
+    }
+  }
+
+  async recover() {
+    if (this.recovering) return
+    this.recovering = true
+    try {
+      const response = await this.checked(await fetch(this.element.dataset.supportDeskSnapshotUrl, {
+        headers: { Accept: "application/json" }, signal: this.abort.signal, credentials: "same-origin"
+      }))
+      const envelope = await response.json()
+      this.surface.dispatchEvent(new CustomEvent("openui:envelope", { bubbles: true, detail: envelope }))
+      this.element.dataset.recovered = "true"
+      this.status.textContent = "Recovered from a missing update"
+    } catch (error) { this.failure(error) }
+    finally { this.recovering = false }
+  }
+
+  saveState(event) {
+    const note = event.detail.state?.reply?.note
+    if (!note || typeof note.value !== "string") return
+    const state = { reply: { note: { value: note.value, componentType: "Input" } } }
+    const serialized = JSON.stringify(state)
+    if (this.lastState === serialized) return
+    this.lastState = serialized
+    this.status.textContent = "Saving draft"
+    const version = Number(this.surface.dataset.openuiVersion)
+    this.saves = this.saves.then(async () => {
+      await this.checked(await fetch(this.element.dataset.supportDeskStateUrl, {
+        method: "PATCH", headers: this.headers(), credentials: "same-origin", signal: this.abort.signal,
+        body: JSON.stringify({ state, version })
+      }))
+      if (this.lastState === serialized) this.status.textContent = "Draft saved"
+    }).catch(error => this.failure(error))
+  }
+
+  async action(event) {
+    if (!["continue_conversation", "close_ticket"].includes(event.detail.result.action)) return
+    await this.saves
+    window.location.reload()
+  }
+
+  error(event) {
+    if (["unauthorized", "csrf_failed"].includes(event.detail.code)) {
+      this.denied = true
+      this.failure(new Error("Action not permitted. Sign in again."))
+    } else if (!this.denied) {
+      this.failure(new Error(event.detail.message || "Unable to render this response."))
+    }
+  }
+  failure(error) {
+    if (error.name !== "AbortError") this.element.querySelector("#desk-error").textContent = error.message
+  }
+}
+
+const application = Application.start()
+application.register("support-desk", SupportDeskController)
+application.register("openui", OpenUIController)
+application.register("openui-envelope", EnvelopeController)

data/examples/support_desk/app/models/support_desk/conversation.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module SupportDesk # :nodoc:
+  # Host-owned state and business transactions, outside the gem's public API.
+  class Conversation < ActiveRecord::Base
+    belongs_to :user
+    belongs_to :ticket
+
+    def message_id = "desk-#{id}-turn-#{version}"
+
+    def surface
+      OpenUI::Rails::Surface.new(
+        id: id, version: version, message_id: message_id, response: response,
+        library_version: OpenUI::Rails.configuration.library_fingerprint,
+        next_sequence: next_sequence, completed: response.present?, streaming: response.empty?, context: form_state
+      )
+    end
+
+    # Persist canonical output before delivery. A disconnect cannot erase it.
+    # This deterministic fixture substitutes for a provider, not for the renderer.
+    def generate!
+      with_lock do
+        return [ snapshot ] if response.present?
+
+        controls = if ticket.reload.status == "closed"
+          'TextContent("Ticket is closed")'
+        else
+          'Buttons([Button("Close ticket", @Run(close))])'
+        end
+        source = <<~LANG
+          ticket = Query("ticket_lookup", {}, {title: "Loading ticket", status: "loading"})
+          close = Mutation("close_ticket", {})
+          note = FormControl("Private note", Input("note", "Write a note"))
+          replyButtons = Buttons([Button("Continue conversation", @ToAssistant("Review this ticket"))])
+          reply = Form("reply", replyButtons, [note])
+          controls = #{controls}
+          root = Card([CardHeader("Support ticket"), TextContent(ticket.title), TextContent(ticket.status), TextContent("Conversation turns: #{messages.length}"), reply, controls])
+        LANG
+        config = OpenUI::Rails::Configuration.new
+        config.pending_byte_limit = 1
+        frames = OpenUI::Rails::Stream::Bridge.new(message_id: message_id,
+          library_version: OpenUI::Rails.configuration.library_fingerprint, configuration: config).envelopes(source.lines).to_a
+        update!(response: source, next_sequence: frames.last.sequence + 1)
+        frames
+      end
+    end
+
+    def snapshot
+      OpenUI::Rails::Stream::Envelope.snapshot(message_id: message_id,
+        sequence: next_sequence - 1, response: response,
+        library_version: OpenUI::Rails.configuration.library_fingerprint)
+    end
+
+    def self.valid_form_state?(state)
+      state.is_a?(Hash) &&
+        (state.keys - [ "reply" ]).empty? && state.values.all? { |fields|
+          fields.is_a?(Hash) && (fields.keys - [ "note" ]).empty? && fields.values.all? { |field|
+            field.is_a?(Hash) && (field.keys - %w[value componentType]).empty? &&
+              field["value"].is_a?(String) && field["value"].bytesize <= 2000 &&
+              (!field.key?("componentType") || field["componentType"] == "Input")
+          }
+        } && JSON.generate(state).bytesize <= 4096
+    end
+
+    def save_form!(state, expected_version:)
+      raise OpenUI::Rails::InvalidActionError, "invalid note state" unless self.class.valid_form_state?(state)
+
+      with_lock do
+        check_version!(expected_version)
+        update!(form_state: state)
+      end
+    end
+
+    def close_ticket!(invocation)
+      with_lock do
+        check_version!(invocation.submission.version)
+        raise OpenUI::Rails::InvalidActionError, "ticket is already closed" if ticket.reload.status == "closed"
+
+        Receipt.create!(ticket_id: ticket_id, operation: "close")
+        ticket.update!(status: "closed")
+        advance!
+      end
+      { "version" => version, "status" => "closed" }
+    end
+
+    def continue!(invocation)
+      with_lock do
+        check_version!(invocation.submission.version)
+        raise OpenUI::Rails::InvalidActionError, "demo turn limit reached" if messages.length >= 20
+
+        update!(messages: messages + [ { "role" => "user", "text" => invocation.args.fetch("message") } ],
+          form_state: invocation.args.fetch("form_state", form_state))
+        advance!
+      end
+      { "version" => version }
+    end
+
+    private
+
+    def check_version!(expected)
+      raise OpenUI::Rails::StaleSurfaceError, "conversation changed; reload it" unless version == expected
+    end
+
+    def advance!
+      update!(version: version + 1, response: "", next_sequence: 0)
+    end
+  end
+end

data/examples/support_desk/app/models/support_desk/demo.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SupportDesk # :nodoc:
+  class Demo
+    def self.seed!
+      [ [ "Alice", "north", "agent" ], [ "Bob", "south", "agent" ], [ "Reader", "north", "reader" ] ].each do |name, tenant, role|
+        user = User.find_or_create_by!(name: name) { |record| record.tenant_id = tenant; record.role = role }
+        next if Conversation.exists?(user_id: user.id)
+
+        ticket = Ticket.create!(tenant_id: tenant, title: "#{tenant.capitalize} delivery question")
+        Conversation.create!(user: user, ticket: ticket, tenant_id: tenant)
+      end
+    end
+  end
+end

data/examples/support_desk/app/models/support_desk/receipt.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SupportDesk # :nodoc:
+  class Receipt < ActiveRecord::Base
+  end
+end

data/examples/support_desk/app/models/support_desk/ticket.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SupportDesk # :nodoc:
+  class Ticket < ActiveRecord::Base
+  end
+end

data/examples/support_desk/app/models/support_desk/user.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SupportDesk # :nodoc:
+  class User < ActiveRecord::Base
+  end
+end

data/examples/support_desk/app/views/layouts/support_desk/application.html.erb

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Support Desk · OpenUI Rails reference</title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= openui_stylesheet_tag %>
+    <%= javascript_importmap_tags "support_desk" %>
+    <style>
+      body { margin: 0; padding: 24px; font: 16px/1.6 system-ui; background: #f6f7f9; color: #17202a; }
+      main { max-width: 800px; margin: auto; } h1 { font-size: 28px; } button { cursor: pointer; }
+      header { display: flex; gap: 16px; align-items: center; flex-wrap: wrap; }
+      .notice { padding: 12px; background: #fff3cf; border-radius: 8px; }
+      [role="alert"] { color: #a11; } .openui-surface { background: white; padding: 16px; border-radius: 12px; }
+    </style>
+  </head>
+  <body><main><%= yield %></main></body>
+</html>

data/examples/support_desk/app/views/support_desk/conversations/index.html.erb

@@ -0,0 +1,6 @@
+<h1>Support Desk reference host</h1>
+<p class="notice">Synthetic accounts and tickets. Local demo only. No model provider is called.</p>
+<p>Sign in to stream a ticket, save a private draft, continue the conversation, and close the ticket.</p>
+<% %w[Alice Bob Reader].each do |name| %>
+  <%= button_to "Sign in as #{name}", session_path, params: { name: name } %>
+<% end %>

data/examples/support_desk/app/views/support_desk/conversations/show.html.erb

@@ -0,0 +1,16 @@
+<header>
+  <h1>Support Desk</h1>
+  <span><%= current_actor.name %> · <%= current_actor.tenant_id %> tenant</span>
+  <%= button_to "Sign out", session_path, method: :delete %>
+</header>
+<p class="notice">Recorded response, real OpenUI runtime. Your Rails host owns the ticket and conversation.</p>
+<section data-controller="support-desk"
+         data-support-desk-stream-url="<%= stream_conversation_path(@conversation) %>"
+         data-support-desk-snapshot-url="<%= snapshot_conversation_path(@conversation) %>"
+         data-support-desk-state-url="<%= state_conversation_path(@conversation) %>"
+         data-action="openui:state->support-desk#saveState openui:snapshot-required->support-desk#recover openui:action->support-desk#action openui:error->support-desk#error">
+  <%= openui_surface(surface: @conversation.surface, label: "Support ticket") %>
+  <div id="desk-envelopes" hidden></div>
+  <p role="status" id="desk-status">Ready</p>
+  <p role="alert" id="desk-error"></p>
+</section>

data/examples/support_desk/boot.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Explicitly loaded by the reference host. Never loaded by require "openui/rails".
+module SupportDesk # :nodoc:
+  class Engine < ::Rails::Engine
+    isolate_namespace SupportDesk
+    engine_name "support_desk"
+    config.root = File.expand_path(__dir__)
+
+    # The documented local review uses RAILS_ENV=test. Keep the reference's
+    # form tags and the shared action endpoint protected in that environment too.
+    initializer "support_desk.csrf", before: "action_controller.set_configs" do |app|
+      app.config.action_controller.allow_forgery_protection = true
+    end
+
+    initializer "support_desk.assets", before: "importmap" do |app|
+      app.config.assets.paths << root.join("app/javascript")
+      app.config.importmap.paths << root.join("config/importmap.rb")
+    end
+  end
+end

data/examples/support_desk/config/importmap.rb

@@ -0,0 +1,4 @@
+pin "support_desk", to: "support_desk.js"
+pin "@hotwired/turbo-rails", to: "turbo.min.js"
+pin "@hotwired/stimulus", to: "stimulus.min.js"
+pin_all_from OpenUI::Rails::Engine.root.join("app/javascript/openui"), under: "openui"

data/examples/support_desk/config/initializers/openui.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+OpenUI::Rails.configure do |config|
+  library = ENV.fetch("OPENUI_REFERENCE_LIBRARY_DIR") { Rails.root.join("config/openui") }
+  config.library_spec_path = File.join(library, "library.spec.json")
+  config.prompt_path = File.join(library, "library.prompt.txt")
+  config.actor_resolver = ->(controller) { SupportDesk::User.find_by(id: controller.session[:support_desk_user_id]) }
+  config.surface_resolver = ->(id, actor:, **) {
+    SupportDesk::Conversation.find_by(id: id, user_id: actor.id, tenant_id: actor.tenant_id) if actor
+  }
+  config.idempotency_scope = ->(invocation) { [ invocation.actor.tenant_id, invocation.actor.id ] }
+  config.authorize_action = ->(invocation) {
+    actor, conversation = invocation.actor, invocation.surface
+    actor && conversation && conversation.user_id == actor.id && conversation.tenant_id == actor.tenant_id &&
+      (invocation.action == "ticket_lookup" || actor.role == "agent")
+  }
+end
+OpenUI::Rails.actions.register "ticket_lookup", schema: {}, handler: ->(invocation) {
+  ticket = invocation.surface.ticket
+  { "title" => ticket.title, "status" => ticket.status }
+}
+OpenUI::Rails.actions.register "close_ticket", schema: {}, handler: ->(invocation) {
+  invocation.surface.close_ticket!(invocation)
+}
+OpenUI::Rails.actions.register "continue_conversation",
+  schema: ->(args) {
+    (args.keys - %w[message context form_name form_state]).empty? &&
+      args["message"].is_a?(String) && args["message"].bytesize.between?(1, 1000) &&
+      (!args.key?("context") || args["context"].is_a?(String) && args["context"].bytesize <= 1000) &&
+      (!args.key?("form_name") || args["form_name"] == "reply") &&
+      (!args.key?("form_state") || SupportDesk::Conversation.valid_form_state?(args["form_state"]))
+  }, handler: ->(invocation) { invocation.surface.continue!(invocation) }

data/examples/support_desk/config/routes.rb

@@ -0,0 +1,12 @@
+SupportDesk::Engine.routes.draw do
+  root "conversations#index"
+  post "/session", to: "sessions#create"
+  delete "/session", to: "sessions#destroy"
+  resources :conversations, only: [ :show ] do
+    member do
+      post :stream
+      get :snapshot
+      patch :state
+    end
+  end
+end

data/examples/support_desk/db/migrate/20261019000000_create_support_desk.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class CreateSupportDesk < ActiveRecord::Migration[8.0] # :nodoc:
+  def change
+    create_table :support_desk_users do |t|
+      t.string :name, null: false
+      t.string :tenant_id, null: false
+      t.string :role, null: false
+    end
+    add_index :support_desk_users, :name, unique: true
+    create_table :support_desk_tickets do |t|
+      t.string :tenant_id, null: false
+      t.string :title, null: false
+      t.string :status, null: false, default: "open"
+    end
+    create_table :support_desk_conversations do |t|
+      t.references :user, null: false, foreign_key: { to_table: :support_desk_users }
+      t.references :ticket, null: false, foreign_key: { to_table: :support_desk_tickets }
+      t.string :tenant_id, null: false
+      t.integer :version, null: false, default: 0
+      t.text :response, null: false, default: ""
+      t.integer :next_sequence, null: false, default: 0
+      t.json :form_state, null: false, default: {}
+      t.json :messages, null: false, default: []
+    end
+    create_table :support_desk_receipts do |t|
+      t.references :ticket, null: false, foreign_key: { to_table: :support_desk_tickets }
+      t.string :operation, null: false
+    end
+    # Domain-level guard survives a process restart and idempotency-store expiry.
+    add_index :support_desk_receipts, [ :ticket_id, :operation ], unique: true
+  end
+end

data/examples/support_desk/install.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Explicit reference-host wiring, not a generator and not a general installer.
+require "fileutils"
+root = File.realpath(ARGV.fetch(0, Dir.pwd))
+application = File.join(root, "config/application.rb")
+source = File.read(application)
+marker = "Bundler.require(*Rails.groups)"
+abort "expected a generated full-stack Rails host" unless source.include?(marker)
+line = 'require File.join(Gem.loaded_specs.fetch("openui-rails").full_gem_path, "examples/support_desk/boot")'
+File.write(application, source.sub(marker, "#{marker}\n#{line}")) unless source.include?(line)
+routes = File.join(root, "config/routes.rb")
+route = 'Rails.application.routes.draw { mount SupportDesk::Engine => "/support" }'
+File.open(routes, "a") { |file| file.puts route } unless File.read(routes).include?("SupportDesk::Engine")
+puts "Reference host wired. Install migrations, prepare the default library/runtime, and seed synthetic records as documented."

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")
 

data/lib/generators/openui/install/templates/config/openui/README.md

@@ -4,10 +4,23 @@ This directory holds the **prompt** and **spec** generated from the same,
 version-pinned component-library revision. Both must come from one revision so
 the model prompt and the browser component library cannot drift.
 
-The default browser bundle contains `openuiChatLibrary` only. For that bundle,
-save the exact outputs of `window.__OpenUI.openuiChatLibrary.prompt()` and
-`.toSpec()` as the prompt text and JSON spec. A custom library needs a matching
-host-built runtime; the CLI does not change the default browser bundle.
+The default browser bundle contains `openuiChatLibrary` only. Prepare its
+exported files without a browser, Node, or a provider:
+
+```sh
+bin/rails openui:library:prepare
+bin/rails openui:runtime:fetch
+bin/rails openui:doctor
+```
+
+Commit the prompt, spec, and `openui.LICENSE.txt`. Repeated preparation preserves
+identical files. Different existing files stop the task; back them up before
+explicitly replacing them with `bin/rails 'openui:library:prepare[true]'`.
+Outputs must stay within the application root. Keep the upstream license when
+redistributing the exported library.
+
+Register the Stimulus controllers and include `openui_stylesheet_tag` before
+rendering. Doctor does not verify browser setup or application authorization.
 
 For a custom library, use the pinned CLI (never `@latest`):
 
@@ -22,3 +35,5 @@ commit both files. `OpenUI::Rails` fingerprints the spec; a mismatched
 fingerprint is a visible failure rather than a silent re-render.
 
 Set `DO_NOT_TRACK=1` in CI as well as `--no-telemetry`.
+
+Full guides: https://openui-rails.wangyaodi.com/library-contract/