ruby_llm-browser 0.1.0

data/docs/_plugins/versioned_docs.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Runs once per build, after Jekyll reads the site.
+#
+# - docs_unreleased is true for the /next/ build, and for an unversioned build
+#   while _config.yml says `released: false`. Pages use it to show the install
+#   command for the default branch. A build of a release tag is never
+#   unreleased, even when that tag forgot to set `released: true`.
+# - A versioned build takes `version` from _data/versions.yml, which
+#   bin/prepare_versions.rb fills in from the tag, so a tag that forgot to bump
+#   `version` still shows the right install command.
+# - An absolute canonical_url on this site becomes a path, so the theme adds
+#   this build's base path (/next/, /v1/) and the page stays in its own
+#   build's llms.txt and sitemap.
+# - llms.txt names the documented version, and links to the site's /api/
+#   point at this build's API reference.
+Jekyll::Hooks.register :site, :post_read, priority: :high do |site|
+  versions = site.data['versions'].is_a?(Hash) ? site.data['versions'] : {}
+  current = versions['current'].to_s
+  if current.empty?
+    site.config['docs_unreleased'] = site.config['released'] == false
+  else
+    site.config['docs_unreleased'] = [ 'next', 'Next (unreleased)' ].include?(current)
+    release = versions['release'].to_s
+    site.config['version'] = release unless release.empty?
+  end
+
+  origin = site.config['url'].to_s.delete_suffix('/')
+  base = site.config['baseurl'].to_s.delete_suffix('/')
+  root = "#{origin}#{versions.fetch('base', base).to_s.delete_suffix('/')}"
+  unless origin.empty?
+    (site.pages + site.collections.values.flat_map(&:docs)).each do |page|
+      canonical = page.data['canonical_url']
+      next unless canonical.is_a?(String) && canonical.start_with?("#{root}/")
+
+      page.data['canonical_url'] = canonical.delete_prefix(root)
+    end
+  end
+
+  llms = site.config.dig('jekyll_vitepress', 'llms')
+  next unless llms.is_a?(Hash) && !current.empty?
+
+  label = current == 'next' ? 'Next (unreleased)' : current
+  llms['description'] = "Developer documentation for #{site.config['title']} #{label}."
+  llms['details'] = llms['details'].to_s.gsub("#{root}/api/", "#{origin}#{base}/api/") unless origin.empty?
+end

data/docs/_reference/api-reference.md

@@ -0,0 +1,29 @@
+---
+layout: default
+title: API Reference
+nav_order: 1
+guide: false
+description: Find the RubyLLM::Browser classes for tools, policy, results, backends, and Rails jobs.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+The [generated RDoc reference]({{ '/api/' | relative_url }}) documents classes and public methods from the Ruby source. Start with the task you need to perform:
+
+| Task | Public API |
+| --- | --- |
+| Build trusted inputs for an operation | `Context`, `Policy`, `Budget` |
+| Inspect a page or extract structured data | `Inspect`, `Extract`, `Engine` |
+| Simulate one host-approved action offline | `Act`, `Approval`, `ApprovalStore` |
+| Read a bounded result | `Result` |
+| Use an offline backend | `FakeBackend` |
+| Adapt the Stagehand Ruby SDK | `StagehandBackend`, `Capabilities`, `Doctor` |
+| Persist operation or approval state | `OperationStore`, `ApprovalStore` and their implementations |
+| Run Rails background jobs and cleanup | `RubyLLM::Browser::Rails::OperationJob`, `Reaper` |
+
+Start with [Getting Started]({% link _getting_started/getting-started.md %}) for a runnable offline example. The [API and configuration guide]({% link API.md %}) explains inputs, results, limits, and errors.
+
+The reference is generated from source comments. Build it locally with `docs/bin/build-api.sh tmp/api`.

data/docs/_reference/release-history.md

@@ -0,0 +1,23 @@
+---
+layout: default
+title: Release History
+nav_order: 9
+guide: false
+description: Follow release tags and their documentation for RubyLLM::Browser.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+{% if site.docs_unreleased %}The current source build follows `main`. The latest stable release is `0.1.0`.
+{% else %}This documentation describes the `{{ site.version }}` release. Use the tag and
+release notes to identify the exact source for this version.
+{% endif %}
+
+| Release | Date | Highlights |
+| --- | --- | --- |
+| [0.1.0](https://github.com/yorzi/ruby_llm-browser/releases/tag/v0.1.0) | 2026-10-18 | Offline read-only Inspect and Extract, Rails adapter, and Act simulation; live Stagehand and live Act are unsupported |
+
+For changes to existing applications, follow [Upgrading]({% link _reference/upgrading.md %}).

data/docs/_reference/upgrading.md

@@ -0,0 +1,33 @@
+---
+layout: default
+title: Upgrading
+nav_order: 2
+description: Check the supported upgrade path before moving a RubyLLM::Browser application to a new version.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* What changed in the first public release.
+* Where to find migration steps for earlier development snapshots.
+* What evidence must exist before a release tag is treated as supported.
+
+## Public Releases
+
+Version `{{ site.version }}` is the first public release. It has no earlier public version
+to migrate from. Install it with `bundle add ruby_llm-browser --version "~> {{ site.version }}"`.
+
+## Earlier Development Snapshots
+
+If you ran an earlier development Rails generator, do not drop existing operation data
+or rerun a create-table migration. Follow the additive migration instructions under
+"Upgrading an earlier development snapshot" in the [Rails guide]({% link RAILS.md %}). Drain workers during the migration and do not reuse idempotency keys for legacy rows that lack request digests.
+
+## Next Steps
+
+* Review the [release history]({% link _reference/release-history.md %}) for version records.
+* Review the [release audit]({% link RELEASE_AUDIT.md %}) before enabling a live backend.

data/docs/bin/build-api.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Build the RDoc API reference, with a Markdown copy of every class page and
+# the guides' search and social metadata, into <output-dir>.
+#   docs/bin/build-api.sh <output-dir> [source-root]
+# bin/build.sh sets SITE_URL to the build's address (such as
+# https://example.com/next) and ROOT_URL to the production site's.
+set -euo pipefail
+
+out="${1:?usage: build-api.sh <output-dir> [source-root]}"
+docs="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source_root="${2:-$(git -C "$docs" rev-parse --show-toplevel)}"
+case "$out" in /*) ;; *) out="$PWD/$out" ;; esac
+
+( cd "$source_root" && ruby -rrdoc/rdoc -e 'RDoc::RDoc.new.document(ARGV)' -- --output "$out" --quiet lib )
+ruby "$docs/bin/export-api-markdown.rb" "$out" "$source_root" "RubyLLM::Browser"
+
+main="RubyLLM::Browser"
+if [[ -n "$main" && -f "$out/$main.html" ]]; then
+  # Both pages sit at the same depth, so the module page's relative links work at /api/.
+  cp "$out/$main.html" "$out/index.html"
+fi
+
+ruby "$docs/bin/postprocess_api_seo.rb" "$out" "$docs/_config.yml" "$main.html"

data/docs/bin/build.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# Build the docs into docs/_site.
+# Once the latest release tag has docs, that release is built at /, the working
+# tree at /next/, and the newest tag of each older major version that has docs
+# at /vN/. Until then, the working tree is built at /.
+#   docs/bin/build.sh        BASE=/repo docs/bin/build.sh        SITE=/tmp/out docs/bin/build.sh
+# BASE is the site's base path. It defaults to baseurl in _config.yml; the
+# workflow sets it from GitHub Pages, and an empty BASE means the site is at the
+# root of its domain.
+set -euo pipefail
+
+unset RUBYOPT RUBYLIB BUNDLE_GEMFILE BUNDLE_BIN_PATH BUNDLE_BIN BUNDLE_APP_CONFIG
+
+docs="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+repo="$(git -C "$docs" rev-parse --show-toplevel)"
+repo="$(cd "$repo" && pwd -P)"
+docs="$(cd "$docs" && pwd -P)"
+rel="${docs#"$repo"/}"
+site_input="${SITE:-$docs/_site}"
+site_input="${site_input%/}"
+site_name="${site_input##*/}"
+site_parent="${site_input%/*}"
+if [[ "$site_input" == /* ]]; then
+  [[ -n "$site_parent" ]] || site_parent="/"
+else
+  [[ -n "$site_parent" ]] || site_parent="."
+  site_parent="$PWD/$site_parent"
+fi
+site_parent="$(cd "$site_parent" && pwd -P)"
+if [[ -z "$site_name" || "$site_name" == "." || "$site_name" == ".." ]]; then
+  echo "Refusing unsafe site output path: ${SITE:-$docs/_site}" >&2
+  exit 1
+fi
+site="$site_parent/$site_name"
+if [[ "$site" == "/" || "$site" == "$repo" || "$site" == "$docs" || -L "$site" ]]; then
+  echo "Refusing unsafe site output path: $site" >&2
+  exit 1
+fi
+if [[ "$site" == "$repo/"* && "$site" != "$docs/_site" ]]; then
+  echo "Refusing site output inside the source tree: $site" >&2
+  exit 1
+fi
+marker="${site}.ruby-llm-browser-generated"
+marker_contents="Generated by docs/bin/build.sh for $site"
+if [[ -L "$marker" ]]; then
+  echo "Refusing to replace an existing unowned output directory: $site" >&2
+  echo "Choose a new SITE path or remove that output directory yourself." >&2
+  exit 1
+fi
+if [[ -e "$site" ]] && [[ ! -d "$site" || ! -f "$marker" || "$(<"$marker")" != "$marker_contents" ]]; then
+  echo "Refusing to replace an existing unowned output directory: $site" >&2
+  echo "Choose a new SITE path or remove that output directory yourself." >&2
+  exit 1
+fi
+gemfile="$docs/Gemfile"
+read_config() { ruby -ryaml -e 'puts YAML.load_file(ARGV.fetch(0))[ARGV.fetch(1)].to_s.chomp("/")' "$docs/_config.yml" "$1"; }
+origin="$(read_config url)"
+BASE="${BASE-$(read_config baseurl)}"
+BASE="${BASE%/}"
+
+# A tag has docs when its tree holds this site's _config.yml on the same theme.
+has_docs() { git -C "$repo" show "$1:$rel/_config.yml" 2>/dev/null | grep -q 'jekyll-vitepress-theme'; }
+major() { local version="${1#v}"; echo "${version%%.*}"; }
+
+tags="$(git -C "$repo" tag --list --sort=-v:refname | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+$' || true)"
+latest="$(printf '%s\n' "$tags" | head -n 1)"
+release=""
+if [[ -n "$latest" ]] && has_docs "$latest"; then
+  release="$latest"
+fi
+
+build_api() {
+  local output="$1" source_root="$2" prefix="$3"
+  if [[ -x "$docs/bin/build-api.sh" ]]; then
+    SITE_URL="$origin$prefix" ROOT_URL="$origin$BASE" "$docs/bin/build-api.sh" "$output/api" "$source_root"
+  fi
+}
+
+if [[ -z "$release" ]]; then
+  ( cd "$docs" && BUNDLE_GEMFILE="$gemfile" bundle exec jekyll build --baseurl "$BASE" -d "$site" --quiet )
+  build_api "$site" "$repo" "$BASE"
+  printf '%s\n' "$marker_contents" > "$marker"
+  echo "Built the working tree at ${BASE:-/}. No release has docs yet, so there is no /next/."
+  exit 0
+fi
+
+archives=()
+top="$(major "$release")"
+seen=" "
+while read -r tag; do
+  [[ -n "$tag" ]] || continue
+  number="$(major "$tag")"
+  if (( number >= top )) || [[ "$seen" == *" $number "* ]]; then continue; fi
+  seen="$seen$number "
+  if has_docs "$tag"; then archives+=("$tag"); fi
+done <<< "$tags"
+
+workspace="$(mktemp -d)"
+trap 'rm -rf "$workspace"' EXIT
+
+extract() {
+  local tag="$1" target="$2" path
+  local paths=("$rel")
+  for path in lib .rdoc_options README.md; do
+    if git -C "$repo" cat-file -e "$tag:$path" 2>/dev/null; then paths+=("$path"); fi
+  done
+  mkdir -p "$target"
+  git -C "$repo" archive "$tag" -- "${paths[@]}" | tar -x -C "$target"
+  if [[ ! -f "$target/.rdoc_options" && -f "$repo/.rdoc_options" ]]; then
+    cp "$repo/.rdoc_options" "$target/.rdoc_options"
+  fi
+}
+
+prepare() {
+  local source="$1" channel="$2"
+  mkdir -p "$source/_data" "$source/_plugins"
+  cp "$docs/bin/versions.yml" "$source/_data/versions.yml"
+  cp "$docs/_plugins/versioned_docs.rb" "$source/_plugins/"
+  ruby "$docs/bin/prepare_versions.rb" "$source/_data/versions.yml" "$channel" "$BASE" "$release" \
+    ${archives[@]+"${archives[@]}"}
+}
+
+build() {
+  local source="$1" output="$2" prefix="$3" source_root="$4"
+  ( cd "$source" && BUNDLE_GEMFILE="$gemfile" bundle exec jekyll build --baseurl "$prefix" -d "$output" --quiet )
+  build_api "$output" "$source_root" "$prefix"
+}
+
+extract "$release" "$workspace/stable"
+prepare "$workspace/stable/$rel" stable
+build "$workspace/stable/$rel" "$workspace/stable-out" "$BASE" "$workspace/stable"
+
+mkdir -p "$workspace/next"
+rsync -a --exclude=_site --exclude=vendor --exclude=.jekyll-cache --exclude=.bundle "$docs/" "$workspace/next/"
+prepare "$workspace/next" next
+build "$workspace/next" "$workspace/next-out" "$BASE/next" "$repo"
+
+channels=(next)
+for tag in ${archives[@]+"${archives[@]}"}; do
+  channel="v$(major "$tag")"
+  extract "$tag" "$workspace/$channel"
+  prepare "$workspace/$channel/$rel" "$channel"
+  build "$workspace/$channel/$rel" "$workspace/$channel-out" "$BASE/$channel" "$workspace/$channel"
+  channels+=("$channel")
+done
+
+rm -rf "$site"
+mkdir -p "$site"
+cp -a "$workspace/stable-out/." "$site/"
+for channel in "${channels[@]}"; do
+  mkdir -p "$site/$channel"
+  cp -a "$workspace/$channel-out/." "$site/$channel/"
+done
+ruby "$docs/bin/link_versions.rb" "$site" "$origin" "$BASE" "${channels[@]}"
+printf '%s\n' "$marker_contents" > "$marker"
+
+summary="Built $release at ${BASE:-/} and the working tree at $BASE/next/"
+for tag in ${archives[@]+"${archives[@]}"}; do
+  summary="$summary, $tag at $BASE/v$(major "$tag")/"
+done
+echo "$summary."

data/docs/bin/export-api-markdown.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Writes a Markdown page for every documented class and module, plus an
+# index.md, next to the RDoc HTML. Coding assistants read these.
+#   export-api-markdown.rb <output-dir> <source-root> <project-name>
+
+require 'fileutils'
+require 'open3'
+require 'rbconfig'
+require 'tmpdir'
+
+output_dir = File.expand_path(ARGV.fetch(0))
+source_root = File.expand_path(ARGV.fetch(1))
+project = ARGV.fetch(2)
+rdoc = [ RbConfig.ruby, Gem.bin_path('rdoc', 'rdoc') ]
+ri = [ RbConfig.ruby, Gem.bin_path('rdoc', 'ri') ]
+
+def capture!(*command, chdir:)
+  stdout, stderr, status = Open3.capture3(*command, chdir: chdir)
+  abort "#{command.join(' ')} failed\n#{stderr}" unless status.success?
+
+  stdout
+end
+
+def clean(markdown, ri_dir)
+  markdown
+    .gsub(/\s*\(from\s+#{Regexp.escape(ri_dir)}\)/m, '')
+    .gsub(%r{<code>(.*?)</code>}m, '`\1`')
+    .gsub(/[ \t]+$/, '')
+    .gsub(/\n{3,}/, "\n\n")
+    .strip
+end
+
+FileUtils.mkdir_p(output_dir)
+
+Dir.mktmpdir('api-ri') do |tmp|
+  ri_dir = File.join(tmp, 'ri')
+  capture!(*rdoc, '--format', 'ri', '--output', ri_dir, '--quiet', 'lib', chdir: source_root)
+  options = [ '--no-standard-docs', '--doc-dir', ri_dir, '--format', 'markdown', '--width', '1000' ]
+  names = capture!(*ri, *options, '--list', chdir: source_root).lines.map(&:strip).reject(&:empty?).sort
+
+  index = [ "# #{project} API Reference", '', '<!-- Generated from RDoc. Do not edit. -->', '',
+           "Markdown pages for every public #{project} class and module.", '' ]
+  names.each do |name|
+    path = "#{name.gsub('::', '/')}.md"
+    destination = File.join(output_dir, path)
+    FileUtils.mkdir_p(File.dirname(destination))
+    markdown = capture!(*ri, *options, '--all', name, chdir: source_root)
+    File.write(destination, "#{clean(markdown, ri_dir)}\n")
+    index << "- [#{name}](#{path})"
+  end
+  File.write(File.join(output_dir, 'index.md'), "#{index.join("\n")}\n")
+end

data/docs/bin/link_versions.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Ties the versioned builds together once bin/build.sh has assembled them.
+# A page that only an archived major version still has gets a redirect at its
+# old root URL, so links from before the major release keep working, and
+# robots.txt lists the sitemap of every build under the root.
+#   link_versions.rb <site-dir> <origin> <base-path> <channel> [channel ...]
+
+require 'cgi'
+require 'fileutils'
+require 'json'
+
+site, origin, base, *channels = ARGV
+abort 'usage: link_versions.rb <site-dir> <origin> <base-path> <channel> [channel ...]' if channels.empty?
+site = File.expand_path(site)
+
+def redirect_page(path, target, canonical)
+  FileUtils.mkdir_p(File.dirname(path))
+  escaped = CGI.escapeHTML(target)
+  File.write(path, <<~HTML)
+    <!doctype html>
+    <html lang="en">
+    <head>
+      <meta charset="utf-8">
+      <title>This page has moved</title>
+      <link rel="canonical" href="#{CGI.escapeHTML(canonical)}">
+      <meta name="robots" content="noindex,follow">
+      <script>window.location.replace(#{JSON.generate(target)} + window.location.search + window.location.hash);</script>
+      <meta http-equiv="refresh" content="0;url=#{escaped}">
+    </head>
+    <body><p>This page has moved to <a href="#{escaped}">#{escaped}</a>.</p></body>
+    </html>
+  HTML
+end
+
+versioned = channels.map { |channel| "#{channel}/" }
+channels.grep(/\Av\d+\z/).each do |archive|
+  Dir.glob('**/*.html', base: File.join(site, archive)).sort.each do |relative|
+    next if relative == '404.html' || relative.start_with?(*versioned)
+    next if File.exist?(File.join(site, relative))
+
+    target = "#{base}/#{archive}/#{relative.delete_suffix('index.html')}"
+    redirect_page(File.join(site, relative), target, "#{origin}#{target}")
+  end
+end
+
+robots = File.join(site, 'robots.txt')
+if File.file?(robots) && origin.match?(%r{\Ahttps?://})
+  sitemaps = channels.select { |channel| File.file?(File.join(site, channel, 'sitemap.xml')) }
+  File.open(robots, 'a') do |file|
+    sitemaps.each { |channel| file.puts "Sitemap: #{origin}#{base}/#{channel}/sitemap.xml" }
+  end
+end

data/docs/bin/postprocess_api_seo.rb

@@ -0,0 +1,129 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Gives the RDoc pages the search and social metadata the theme gives the
+# guides: a canonical URL, robots, Open Graph and Twitter image tags, and
+# JSON-LD. Adds the pages to the build's sitemap.xml, and points links to the
+# production site (the .rdoc_options footer) at this build.
+#   postprocess_api_seo.rb <api-dir> <_config.yml> <main-page.html>
+# SITE_URL is the build's address and ROOT_URL the production site's; both
+# default to `url` plus `baseurl` from _config.yml.
+
+require 'cgi'
+require 'date'
+require 'json'
+require 'pathname'
+require 'yaml'
+
+output_dir = Pathname(ARGV.fetch(0)).expand_path
+config_path = Pathname(ARGV.fetch(1)).expand_path
+main_page = ARGV.fetch(2, 'index.html')
+config = YAML.safe_load_file(config_path, permitted_classes: [ Date, Time ], aliases: true) || {}
+trim = ->(url) { url.to_s.sub(%r{/+\z}, '') }
+configured = "#{trim.call(config['url'])}#{trim.call(config['baseurl'])}"
+site_root = trim.call(ENV.fetch('SITE_URL', configured))
+production_root = trim.call(ENV.fetch('ROOT_URL', configured))
+unless site_root.match?(%r{\Ahttps?://})
+  warn 'postprocess_api_seo: url in _config.yml is not an absolute http(s) address; skipping API metadata'
+  exit
+end
+
+name = config['title'].to_s
+description = config['description'].to_s
+language = (config['lang'] || 'en-US').to_s
+seo = config.dig('jekyll_vitepress', 'seo')
+image = seo.is_a?(Hash) ? seo['image'] : nil
+image = image['path'] if image.is_a?(Hash)
+image ||= '/assets/images/social/index.png' if config_path.dirname.join('_plugins', 'social_cards.rb').file?
+image_url = image && (image.to_s.match?(%r{\Ahttps?://}) ? image.to_s : "#{site_root}#{image}")
+default_robots = 'index,follow,max-image-preview:large,max-snippet:-1,max-video-preview:-1'
+index_pages = [ 'index.html', main_page ].uniq
+api_urls = []
+
+def tag(name, attributes)
+  rendered = attributes.map { |key, value| %(#{key}="#{CGI.escapeHTML(value)}") }.join(' ')
+  "<#{name} #{rendered}>"
+end
+
+# Escapes the characters that would let a value close the ld+json block early.
+def json_ld(graph)
+  JSON.generate(graph).gsub(/[<>&

]/) { |char| format('\\u%04x', char.ord) }
+end
+
+# A link to the production site moves to this build only when this build has
+# the page, so a footer that names another base path is left alone.
+build_root = output_dir.parent
+in_build = lambda do |route|
+  route = route.split(/[?#]/).first.to_s
+  candidate = build_root.join(route)
+  route.empty? || candidate.file? || candidate.join('index.html').file?
+end
+
+output_dir.glob('**/*.html').sort.each do |path|
+  relative_path = path.relative_path_from(output_dir).to_s
+  html = path.read
+  unless production_root == site_root
+    html = html.gsub(%r{href="#{Regexp.escape(production_root)}/([^"]*)"}) do
+      route = Regexp.last_match(1)
+      in_build.call(route) ? %(href="#{site_root}/#{route}") : Regexp.last_match(0)
+    end
+  end
+  redirect = html.match?(/<meta[^>]+http-equiv="refresh"/i)
+  target = html[/<meta[^>]+http-equiv="refresh"[^>]+url=([^";]+)[^>]*>/i, 1]
+  canonical = if index_pages.include?(relative_path)
+                "#{site_root}/api/"
+  elsif redirect && target
+                "#{site_root}/api/#{target}"
+  else
+                "#{site_root}/api/#{relative_path}"
+  end
+  title = CGI.unescapeHTML(html[%r{<title>(.*?)</title>}mi, 1].to_s).strip
+  page_description = CGI.unescapeHTML(html[/<meta\s+name="description"\s+content="([^"]*)"/mi, 1].to_s).strip
+
+  html = html.sub(/<link\s+rel="canonical"\s+href="[^"]*">/i, '')
+  metadata = [
+    tag('link', 'rel' => 'canonical', 'href' => canonical),
+    tag('meta', 'name' => 'robots', 'content' => redirect ? 'noindex,follow' : default_robots),
+    tag('meta', 'property' => 'og:url', 'content' => canonical),
+    tag('meta', 'property' => 'og:site_name', 'content' => name)
+  ]
+  if image_url
+    # RDoc writes og:title, og:description, and a summary Twitter card already.
+    html = html.sub(/(<meta\s+name="twitter:card"\s+content=")summary(")/i, '\1summary_large_image\2')
+    metadata << tag('meta', 'property' => 'og:image', 'content' => image_url)
+    metadata << tag('meta', 'property' => 'og:image:alt', 'content' => name)
+    metadata << tag('meta', 'name' => 'twitter:image', 'content' => image_url)
+  end
+
+  unless redirect
+    website_id = "#{site_root}/#website"
+    page = {
+      '@type' => 'WebPage', '@id' => "#{canonical}#webpage", 'url' => canonical,
+      'name' => title, 'description' => page_description,
+      'isPartOf' => { '@id' => website_id }, 'inLanguage' => language
+    }
+    graph = [ {
+      '@type' => 'WebSite', '@id' => website_id, 'url' => "#{site_root}/",
+      'name' => name, 'description' => description, 'inLanguage' => language
+    } ]
+    if image_url
+      graph << { '@type' => 'ImageObject', '@id' => "#{image_url}#primaryimage", 'url' => image_url,
+                 'contentUrl' => image_url, 'caption' => name }
+      page['primaryImageOfPage'] = { '@id' => "#{image_url}#primaryimage" }
+    end
+    graph << page
+    metadata << %(<script type="application/ld+json">#{json_ld({ '@context' => 'https://schema.org', '@graph' => graph })}</script>)
+    api_urls << canonical
+  end
+
+  html = html.sub(/<head>/i, "<head>\n#{metadata.join("\n")}")
+  html = html.sub(/<body\b/i, "</head>\n<body") unless html.match?(%r{</head>}i)
+  html = "#{html.rstrip}\n</html>\n" unless html.match?(%r{</html>}i)
+  path.write(html)
+end
+
+sitemap_path = output_dir.parent.join('sitemap.xml')
+if sitemap_path.file? && !api_urls.empty?
+  rows = api_urls.uniq.sort.map { |url| "  <url>\n    <loc>#{CGI.escapeHTML(url)}</loc>\n  </url>" }.join("\n")
+  sitemap_path.write(sitemap_path.read.sub(%r{</urlset>}, "#{rows}\n</urlset>"))
+end

data/docs/bin/prepare_versions.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Fills in the version selector for one build: the release numbers, the base
+# path, which entry is current, and one entry per archived major version.
+#   prepare_versions.rb <versions.yml> <stable|next|vN> <base-path> <release-tag> [archive-tag ...]
+#
+# It also records `release` (the version this build documents, which
+# _plugins/versioned_docs.rb puts in site.version) and `base` (the site's
+# base path without the version prefix).
+
+require 'yaml'
+
+path, current, base, release, *archives = ARGV
+abort 'usage: prepare_versions.rb <versions.yml> <channel> <base-path> <release-tag> [archive-tag ...]' unless release
+
+number = ->(tag) { tag.delete_prefix('v') }
+major = ->(tag) { number.call(tag).split('.').first }
+
+versions = YAML.load_file(path)
+items = versions.fetch('items')
+items.reject! { |item| item['archive'] }
+position = items.index { |item| item['external'] } || items.size
+archives.each_with_index do |tag, offset|
+  items.insert(position + offset,
+               { 'id' => "v#{major.call(tag)}", 'title' => number.call(tag), 'url' => "/v#{major.call(tag)}/",
+                 'archive' => true })
+end
+
+items.each do |item|
+  item['title'] = "#{number.call(release)} (stable)" if item['id'] == 'stable'
+  item['url'] = "#{base}#{item.fetch('url')}" unless item['external']
+end
+
+entry = items.find { |item| item['id'] == current } or abort "no version entry with id #{current}"
+documented = archives.find { |tag| "v#{major.call(tag)}" == current } || release
+versions['current'] = entry.fetch('title')
+versions['release'] = number.call(documented)
+versions['base'] = base
+File.write(path, YAML.dump(versions))

data/docs/bin/serve.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Preview the working tree at http://127.0.0.1:4000 with live reload. Ctrl-C stops it.
+#   docs/bin/serve.sh        PORT=4002 docs/bin/serve.sh
+set -euo pipefail
+
+unset RUBYOPT RUBYLIB BUNDLE_GEMFILE BUNDLE_BIN_PATH BUNDLE_BIN BUNDLE_APP_CONFIG
+
+docs="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$docs"
+exec env BUNDLE_GEMFILE="$docs/Gemfile" bundle exec jekyll serve \
+  --host 127.0.0.1 --port "${PORT:-4000}" \
+  --livereload --livereload-port "${LIVERELOAD_PORT:-35729}"

data/docs/bin/versions.yml

@@ -0,0 +1,14 @@
+# The version selector. bin/build.sh copies it into each versioned build once
+# a release has docs; prepare_versions.rb fills in the release number.
+current: stable
+items:
+  - id: stable
+    title: Stable
+    url: /
+  - id: next
+    title: Next (unreleased)
+    url: /next/
+  - id: changelog
+    title: Changelog
+    url: https://github.com/yorzi/ruby_llm-browser/releases
+    external: true