docs-kit 0.1.0

data/lib/generators/docs_kit/install/templates/build-css

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Build the Tailwind/daisyUI CSS with the gem source paths resolved at build time.
+#
+# Tailwind must scan the Ruby that emits class names — including the daisyui and
+# docs-kit GEMS, whose install dir varies by environment (a global gem dir in dev,
+# a vendored .bundle/gems in Docker). Resolve them with `bundle show` and write
+# the @source globs into a generated file the CSS imports. Fail fast if a required
+# gem can't be resolved — a silently-missing @source ships an unstyled site.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+GENERATED="app/assets/stylesheets/tailwind.sources.css"
+
+sources=""
+for gem in daisyui docs-kit; do
+  if ! path="$(bundle show "$gem" 2>/dev/null)"; then
+    echo "bin/build-css: could not resolve gem path for '$gem' (bundle show failed)." >&2
+    echo "  Tailwind would drop its component classes from the build. Aborting." >&2
+    exit 1
+  fi
+  sources+="@source \"${path}/**/*.rb\";"$'\n'
+done
+
+{
+  echo "/* GENERATED by bin/build-css — do not edit. Gem @source globs for Tailwind. */"
+  printf '%s' "$sources"
+} > "$GENERATED"
+
+MODE="${1:---minify}"
+exec bunx @tailwindcss/cli \
+  -i ./app/assets/stylesheets/application.tailwind.css \
+  -o ./app/assets/builds/application.css \
+  "$MODE"

data/lib/generators/docs_kit/install/templates/build_css.rake

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Build the daisyUI/Tailwind stylesheet into app/assets/builds/application.css so
+# Propshaft can serve it. Runs as part of assets:precompile (production/Docker);
+# `bin/dev` runs the watch variant in development.
+namespace :css do
+  desc "Build the Tailwind + daisyUI stylesheet via bun"
+  task build: :environment do
+    sh "bun run build:css"
+  end
+end
+
+Rake::Task["assets:precompile"].enhance(["css:build"]) if Rake::Task.task_defined?("assets:precompile")

data/lib/generators/docs_kit/install/templates/doc.rb.erb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# In-memory registry of the reference docs. One line per page — slug and view
+# derive from the title (both overridable), and the sidebar nav derives from
+# this registry with zero extra code (see config/initializers/docs_kit.rb's
+# `nav_registries`). Add a page with `rails g docs_kit:page "Title" --group=…`,
+# which appends the `page` line here and writes the class under
+# app/views/docs/pages/.
+#
+# Uses DocsKit::Registry for the shared all/from_slug/grouped/nav_items API.
+class Doc
+  extend DocsKit::Registry
+  path_prefix    "/docs"
+  view_namespace "Views::Docs::Pages"
+
+  page "Installation", group: "Guide"
+end

data/lib/generators/docs_kit/install/templates/docs_controller.rb.erb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Renders a hand-authored doc page from the Doc registry. `render_page` (from
+# DocsKit::Controller) renders the Phlex page with layout: false, since the page
+# composes DocsUI::Shell which IS the full HTML document.
+class DocsController < ApplicationController
+  def show
+    doc = Doc.from_slug(params[:doc])
+    view = doc&.view_class
+    return head :not_found unless view
+
+    render_page view.new
+  end
+end

data/lib/generators/docs_kit/install/templates/docs_kit.rb.erb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# docs-kit configuration — everything that makes this site look like YOUR docs.
+# The shared chrome (Shell/Sidebar/ThemeSwitcher/Code/Page) comes from the gem;
+# only this config differs per site. The `themes` MUST match the
+# @plugin "daisyui" { themes: ... } block in
+# app/assets/stylesheets/application.tailwind.css.
+Rails.application.config.to_prepare do
+  DocsKit.configure do |c|
+    c.brand        = "<%= app_brand %>"
+    c.title_suffix = "<%= app_brand %>"
+    c.themes       = %w[dark light synthwave retro cyberpunk dracula night nord sunset]
+    c.code_theme   = "Rouge::Themes::Monokai"
+
+    # The one-line summary in /llms.txt (the llmstxt.org blockquote agents read
+    # first). Default nil omits the line; set it to describe your docs:
+    # c.tagline = "What this documentation covers, in one sentence."
+
+    # The topbar brand link points at "/" by default. Point it elsewhere if your
+    # docs live under a subpath:
+    # c.brand_href = "/docs"
+
+    # Repo/social links in the topbar, next to the theme switcher. Each renders
+    # as an icon-only button; `icon` is a shipped brand mark (:github, :gitlab,
+    # :discord, :x, :rubygems, :bluesky, :mastodon, :slack, :whatsapp, :telegram,
+    # :linkedin, :youtube, :reddit, :stackoverflow) or any lucide icon name.
+    # External links open in a new tab. Defaults to [] (no links).
+    # c.topbar_links = [
+    #   { href: "https://github.com/OWNER/REPO", label: "GitHub", icon: :github },
+    #   # { href: "https://discord.gg/INVITE",   label: "Discord", icon: :discord },
+    # ]
+
+    # Code blocks use one Rouge theme by default. To keep them readable in BOTH
+    # light and dark daisyUI themes, set a light base + a dark override — the dark
+    # theme's CSS is scoped under [data-theme=X] for each shipped dark theme, so
+    # the switcher restyles code blocks with no JS and no flash:
+    # c.code_theme      = "Rouge::Themes::Github"  # light themes
+    # c.code_theme_dark = "Rouge::Themes::Monokai" # dark themes
+    # c.dark_themes     = %w[my-dark]              # only if you ship custom dark themes
+
+    # Any language Rouge knows works in code blocks out of the box. Add friendly
+    # aliases/labels here if you use custom names:
+    # c.code_lexer_aliases  = { curl: "console" }
+    # c.code_language_labels = { elixir: "Elixir" }
+
+    # Every page is ALSO available as Markdown: GET /docs/<page>.md returns a
+    # faithful GFM twin of the rendered page (for LLMs / copy-paste), and a
+    # "Markdown" masthead action links to it (JS enhances it into copy-to-clipboard).
+    # Set false to hide the action site-wide (the .md route still works):
+    # c.page_markdown_action = false
+
+    # Search is on by default — the topbar grows a search box (a JS-off GET form
+    # that docs-nav enhances into a command palette), served by
+    # DocsKit::SearchController at the route the install generator drew. Hide it,
+    # point it at a moved route, or change the keyboard shortcuts:
+    # c.search           = false            # hide the topbar search box site-wide
+    # c.search_path      = "/docs/search"   # default; match your route if you move it
+    # c.search_shortcuts = ["/", "mod+k"]   # default; "mod" = ⌘ on mac, Ctrl elsewhere.
+    #   Each is a bare key ("/", "s") or a chord ("mod+k", "ctrl+shift+f"); [] binds none.
+
+    # OPTIONAL: API reference from your snippets. DocsUI::RequestExample renders
+    # one request declaration as a code tab per client; these knobs point every
+    # snippet at your host with your auth. See README → "API docs".
+    # c.api_base_url    = "https://api.acme.com"           # prefixed onto each path
+    # c.api_auth_header = "Authorization: Bearer sk_..."   # example auth line
+    # c.api_clients     = { cli: DocsKit::ApiClient.new(...) } # SDK/CLI tabs
+
+    # OPTIONAL: the OpenAPI bridge. Point c.openapi at an OpenAPI 3.x spec and a
+    # docs page can render a whole endpoint with `operation "createInvoice"` — the
+    # Endpoint badge, field/error tables, request tabs, and response are derived
+    # from the spec (zero hand-restatement). Off (nil) by default; a String/
+    # Pathname path (.json → JSON, else YAML) or an already-parsed Hash.
+    # See README → "OpenAPI bridge".
+    # c.openapi = Rails.root.join("openapi.yaml")
+
+    # OPTIONAL: expose your docs to AI agents over MCP (Model Context Protocol) —
+    # a read-only endpoint (search_docs / get_page / list_pages) at POST /mcp that
+    # Claude Code / Claude.ai / Cursor can add as tools. It's OFF until you add
+    # `gem "mcp"` to your Gemfile AND uncomment the /mcp route in config/routes.rb
+    # (see the commented lines there). `c.mcp` defaults to true, so once the gem +
+    # route are present the endpoint is live; set it false to keep it off even
+    # then. README → "Add your docs to an agent (MCP)".
+    # c.mcp = false
+
+    # The sidebar nav derives from the registry — one heading → one registry.
+    # Each registry's authored pages become NavItems automatically (an unwritten
+    # page is skipped, so no dead links). For bespoke nav (interleaved
+    # registries, custom subgroups) set a `c.nav` lambda instead; it wins.
+    c.nav_registries = { "Docs" => Doc }
+  end
+end

data/lib/generators/docs_kit/install/templates/installation_page.rb.erb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# A sample guide page. Zeitwerk resolves this compact class reference through
+# the directory-implied namespaces (app/views/docs/pages/ → Views::Docs::Pages),
+# so there's no need for the 4-level nested-module ceremony. Subclass
+# DocsUI::Page, set the title (+ optional eyebrow/lead), and build the body from
+# the DocsUI kit (Section/Code) and Markdown islands (md). The "On this page"
+# TOC + scroll-spy are automatic (config default).
+class Views::Docs::Pages::Installation < DocsUI::Page
+  title "Installation"
+  eyebrow "Guide"
+
+  def lead = "Add the gem and render your first page."
+
+  def content
+    DocsUI::Section("Add the gem", description: "One line in your Gemfile.") do
+      md <<~'MD'
+        docs-kit ships the shared Phlex chrome — configure it once.
+      MD
+      DocsUI::Code(<<~RUBY, filename: "Gemfile")
+        gem "docs-kit"
+      RUBY
+    end
+
+    DocsUI::Section("Configure") do
+      md <<~'MD'
+        Set your brand, themes, and nav:
+      MD
+      DocsUI::Code(<<~RUBY, filename: "config/initializers/docs_kit.rb")
+        DocsKit.configure do |c|
+          c.brand  = "<%= app_brand %>"
+          c.themes = %w[dark light]
+        end
+      RUBY
+    end
+  end
+end

data/lib/generators/docs_kit/install/templates/landing.rb.erb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Views
+  module Landings
+    # The home page. Renders inside DocsUI::Shell (the full document + drawer
+    # shell); links to the authored docs.
+    class Show < Phlex::HTML
+      include Phlex::Rails::Helpers::Routes
+
+      def view_template
+        render DocsUI::Shell.new do
+          div(class: "prose max-w-none") do
+            h1 { "<%= app_brand %>" }
+            p { "Documentation, built with docs-kit." }
+            ul do
+              Doc.all.select(&:view_class).each do |doc|
+                li { a(href: "/docs/#{doc.slug}", class: "link") { doc.title } }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/docs_kit/install/templates/landings_controller.rb.erb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class LandingsController < ApplicationController
+  def show
+    render_page Views::Landings::Show.new
+  end
+end

data/lib/generators/docs_kit/install/templates/phlex.rb.erb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Phlex autoload namespaces for this docs site:
+#   app/views       → Views::   (pages, e.g. Views::Docs::Pages::Installation)
+#   app/components  → Components:: (a Phlex::Kit; your own components, if any)
+module Views
+end
+
+module Components
+  extend Phlex::Kit
+end
+
+Rails.autoloaders.main.push_dir(Rails.root.join("app", "views"), namespace: Views)
+Rails.autoloaders.main.push_dir(Rails.root.join("app", "components"), namespace: Components)

data/lib/generators/docs_kit/install/templates/rails_icons.rb.erb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# docs-kit's chrome renders lucide icons via rails_icons. Set the default library
+# and sync the icon set once:
+#
+#   bin/rails g rails_icons:sync --library=lucide   # syncs the default (lucide) set
+#
+# (The chrome uses: menu, palette, list, file-code, search, info, lightbulb,
+# triangle-alert. Syncing the whole lucide set covers those + any you add.)
+RailsIcons.configure do |config|
+  config.default_library = "lucide"
+end

data/lib/generators/docs_kit/install/templates/skill.md.erb

@@ -0,0 +1,88 @@
+---
+name: write-docs-page
+description: "Write, add, or update a documentation page in this docs-kit site. Use when asked to document a feature, endpoint, class, or workflow, or to add or edit a page under app/views/docs/pages/. Scaffolds with `rails g docs_kit:page`, writes Markdown-first content, and runs the verification gates."
+---
+
+# Write a docs page
+
+This is a [docs-kit](https://github.com/mhenrixon/docs-kit) site (<%= app_brand %>).
+Every page is a `DocsUI::Page` subclass; the shell, sidebar, "On this page" TOC,
+search, and the `.md` twin all come free. Your job is to scaffold a page and
+write its `#content` — never hand-write HTML or daisyUI markup.
+
+The full authoring contract is in the repo's `AGENTS.md`. This is the recipe.
+
+## 1. Gather the subject
+
+Identify exactly what to document (the code, endpoint, or workflow) and where it
+belongs in the sidebar (the `--group`). Read the relevant source first — do not
+invent behavior. If the subject is an HTTP endpoint, prefer `DocsUI::RequestExample`
+/ `DocsUI::FieldTable`; if it's a Ruby API, prefer `DocsUI::PropTable`. If the
+site has `c.openapi` set (an OpenAPI 3.x spec), a single `operation "operationId"`
+renders the whole endpoint (badge + tables + request tabs + response) from the
+spec — no hand-restatement; reach for it before hand-authoring.
+
+## 2. Scaffold (one command)
+
+```bash
+rails g docs_kit:page "Page Title" --group=Guide
+```
+
+This writes `app/views/docs/pages/<slug>.rb` **and** injects the required
+`page "…"` registry line into `app/models/doc.rb`. Overrides: `--slug`, `--view`,
+`--eyebrow`, `--registry`. If it reports a legacy `entries [...]` registry, add
+the printed line by hand.
+
+## 3. Write `#content` — Markdown first
+
+- Set `title`, `eyebrow`, and a one-sentence `lead`.
+- One `DocsUI::Section("…")` per part of the page — **Sections own structure and
+  the TOC.** Never use a Markdown `##` for page structure.
+- Prose is `md <<~'MD' … MD` — a **single-quoted** heredoc (no escaping, no
+  interpolation; Phlex escapes author text). Markdown `###` is only for
+  sub-headings inside a Section.
+- Reference material: `DocsUI::PropTable`, `DocsUI::FieldTable`,
+  `DocsUI::RequestExample`, `DocsUI::Code(source, filename:)`,
+  `DocsUI::Callout(:note | :tip | :warning)`.
+- OpenAPI-backed endpoints (when `c.openapi` is set): `operation "createInvoice"`
+  renders one operation as a full endpoint reference; append prose with a block —
+  `operation "createInvoice" do |op| op.md("…") end` — and filter tabs with
+  `clients: %i[curl ruby]`.
+
+```ruby
+class Views::Docs::Pages::PageTitle < DocsUI::Page
+  title "Page Title"
+  eyebrow "Guide"
+
+  def lead = "One sentence describing the page."
+
+  def content
+    DocsUI::Section("Overview", description: "What this covers.") do
+      md <<~'MD'
+        Prose as **Markdown**. Fenced ```ruby``` blocks highlight; `inline code`,
+        lists, links, and GFM tables all render styled.
+      MD
+    end
+  end
+end
+```
+
+## 4. Self-review against the checklist
+
+- [ ] The `page "…"` registry line exists (the generator adds it).
+- [ ] Structure is `DocsUI::Section`s, not Markdown `##` headings.
+- [ ] Prose uses `md <<~'MD'` (single-quoted); no `html_safe`, no `raw`.
+- [ ] No hand-written HTML/daisyUI markup, no per-feature Stimulus controller.
+- [ ] Reads correctly with JavaScript off (the server renders it fully).
+- [ ] Any new theme is in both `c.themes` and the Tailwind `@plugin` block.
+- [ ] No inline `rubocop:disable` to force layout.
+
+## 5. Run the gates
+
+```bash
+bundle exec rspec && bundle exec rubocop
+bun run build:css   # only if you added classes the CSS must scan
+```
+
+Then render locally (`bin/dev`, open `/docs/<slug>`) and confirm it reads well.
+For depth on any idiom, read the live [Authoring pages](/docs/authoring) doc.

data/lib/generators/docs_kit/page/USAGE

@@ -0,0 +1,26 @@
+Description:
+    Scaffold one docs page: a Phlex page class under app/views/docs/pages/ AND
+    its one-line registry entry, both derived from the title, in one command.
+    The unit of work for "add a docs page" drops to this command plus writing
+    content.
+
+    The page class uses the compact form
+    `class Views::Docs::Pages::Title < DocsUI::Page` (Zeitwerk resolves it
+    through the directory-implied namespaces) with title/eyebrow/lead and a
+    starter Section containing a Markdown island.
+
+    The registry line `page "Title", group: "Group"` is injected into the
+    Registry-v2 class (default: Doc). A legacy hash-`entries` registry is left
+    untouched with an instruction printed instead of corrupting it.
+
+    Idempotent — re-running does not duplicate the registry line or clobber the
+    page file (in --skip mode).
+
+Example:
+    rails generate docs_kit:page "Getting Started" --group=Guide
+
+    rails generate docs_kit:page "OAuth" --group=Guide --slug=auth --view=OauthGuide
+    rails generate docs_kit:page "Metrics" --group=Reference --eyebrow="Advanced" --registry=Doc
+
+    After running:
+      # edit app/views/docs/pages/getting_started.rb — write your content

data/lib/generators/docs_kit/page/page_generator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "active_support/core_ext/string/inflections"
+
+module DocsKit
+  module Generators
+    # `rails g docs_kit:page TITLE --group=GROUP`
+    #
+    # Scaffolds one docs page — the Phlex page class AND its one-line registry
+    # entry, both derived from the title — so adding a page is one command plus
+    # writing content, not the old ceremony (a 4-level-nested class in one file
+    # plus a hand-synced registry line in another, either half easy to forget).
+    #
+    #   rails g docs_kit:page "Getting Started" --group=Guide
+    #     → app/views/docs/pages/getting_started.rb  (compact class form)
+    #     → injects `page "Getting Started", group: "Guide"` into Doc
+    #
+    # Every derivation is overridable: --slug, --view, --eyebrow, --registry.
+    # A legacy hash-`entries` registry is left untouched (an instruction is
+    # printed instead of corrupting it), and re-running is idempotent.
+    class PageGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :title, type: :string,
+                       desc: %(The page title, e.g. "Getting Started")
+
+      class_option :group, type: :string, default: "Guide",
+                           desc: "The sidebar group heading"
+      class_option :slug, type: :string,
+                          desc: "URL slug (default: the title parameterized)"
+      class_option :view, type: :string,
+                          desc: "Page class basename (default: the title camelized)"
+      class_option :eyebrow, type: :string,
+                             desc: "Eyebrow above the title (default: the group)"
+      class_option :registry, type: :string, default: "Doc",
+                              desc: "Registry class to register the page in"
+
+      def create_page_file
+        template "page.rb.erb", "app/views/docs/pages/#{view_name.underscore}.rb"
+      end
+
+      def register_page
+        path = registry_path
+        rel = relative(path)
+        line = registry_line
+        return say_status(:skip, "#{rel} not found — add `#{line}` manually", :yellow) unless File.exist?(path)
+
+        source = File.read(path)
+        return say_status(:skip, legacy_instruction(rel), :yellow) if legacy_entries?(source)
+        return say_status(:identical, "#{rel} already registers #{title.inspect}", :blue) if source.include?(line)
+
+        inject_into_file path, "  #{line}\n", after: registry_anchor(source)
+      end
+
+      private
+
+      # The by-hand instruction printed for a legacy hash-`entries` registry the
+      # generator won't touch (injecting a `page` line would corrupt it).
+      def legacy_instruction(rel)
+        "#{rel} uses the legacy `entries [...]` form — add this entry by hand:\n  " \
+          "{ slug: #{slug.inspect}, title: #{title.inspect}, " \
+          "group: #{options[:group].inspect}, view: #{view_name.inspect} }"
+      end
+
+      # The Phlex page class basename (e.g. "GettingStarted"). --view wins,
+      # else camelize the title (with "_" word boundaries so hyphens don't
+      # survive into the constant).
+      def view_name
+        options[:view].presence || title.parameterize(separator: "_").camelize
+      end
+
+      # The URL slug. --slug wins, else the title parameterized.
+      def slug
+        options[:slug].presence || title.parameterize
+      end
+
+      # The eyebrow above the title. --eyebrow wins, else the group.
+      def eyebrow
+        options[:eyebrow].presence || options[:group]
+      end
+
+      # The one-line registry entry, with only the overrides that differ from
+      # the derived defaults spelled out (slug when it isn't the parameterized
+      # title; view when it isn't the camelized title).
+      def registry_line
+        ([%(page #{title.inspect}), %(group: #{options[:group].inspect})] + override_kwargs).join(", ")
+      end
+
+      # The explicit slug:/view: keywords, present only when overridden.
+      def override_kwargs
+        kwargs = []
+        kwargs << %(slug: #{slug.inspect}) if slug != title.parameterize
+        kwargs << %(view: #{view_name.inspect}) if view_name != title.parameterize(separator: "_").camelize
+        kwargs
+      end
+
+      # A registry using the v2 `page` DSL has (or will have) `page` lines. The
+      # legacy form declares a hash `entries [...]` array and no `page` line.
+      def legacy_entries?(source)
+        source.match?(/^\s*entries\s*\[/) && !source.match?(/^\s*page\s+["']/)
+      end
+
+      # Inject after the last existing `page` line so ordering lands at the end
+      # of the group; else after view_namespace/path_prefix; else after the
+      # `extend DocsKit::Registry` line.
+      def registry_anchor(source)
+        case source
+        when /^\s*page\s+["']/
+          /^\s*page .*\n(?!\s*page )/
+        when /^\s*view_namespace\s/
+          /^\s*view_namespace .*\n/
+        when /^\s*path_prefix\s/
+          /^\s*path_prefix .*\n/
+        else
+          /extend DocsKit::Registry\n/
+        end
+      end
+
+      def registry_path
+        File.join(destination_root, "app/models/#{options[:registry].underscore}.rb")
+      end
+
+      def relative(path) = path.sub("#{destination_root}/", "")
+    end
+  end
+end

data/lib/generators/docs_kit/page/templates/page.rb.erb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Zeitwerk resolves this compact reference through the directory-implied
+# namespaces (app/views/docs/pages/ → Views::Docs::Pages), so there's no need
+# for the 4-level nested-module ceremony.
+class Views::Docs::Pages::<%= view_name %> < DocsUI::Page
+  title "<%= title %>"
+  eyebrow "<%= eyebrow %>"
+
+  def lead = "A one-sentence summary of this page."
+
+  def content
+    DocsUI::Section("Overview") do
+      md <<~'MD'
+        Write your content here as Markdown — headings, lists, `inline code`,
+        and fenced code blocks all render as prose. Add more `DocsUI::Section`s
+        for each part of the page; each becomes an "On this page" TOC entry.
+      MD
+    end
+  end
+end

data/lib/rubocop/cop/docs_kit/escaped_interpolation_in_heredoc.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module DocsKit
+      # Flags an ESCAPED interpolation (`\#{...}`) inside a double-quoted heredoc
+      # and steers to the single-quoted delimiter (`<<~'RUBY'`), where `#{...}` is
+      # already literal so no backslash is needed.
+      #
+      # Docs pages constantly embed Ruby examples that themselves contain
+      # `#{...}`. In a double-quoted heredoc every one of those has to be escaped
+      # as `\#{...}` or Ruby interpolates it — the recurring "escape tax" every
+      # audited docs site paid. A single-quoted heredoc delimiter turns the whole
+      # body literal, so the examples read exactly as they will render.
+      #
+      # Ruby interpolates three sigils in a double-quoted string — `#{expr}`,
+      # `#@ivar` (also `#@@cvar`), and `#$global` — so the cop treats all three
+      # escape forms (`\#{`, `\#@`, `\#$`) as the escape tax, and a LIVE (unescaped)
+      # occurrence of any of them blocks autocorrection.
+      #
+      # @example
+      #   # bad — escape tax
+      #   source = <<~RUBY
+      #     puts "hello \#{name}"
+      #   RUBY
+      #
+      #   # good — single-quoted delimiter, `#{...}` is literal
+      #   source = <<~'RUBY'
+      #     puts "hello #{name}"
+      #   RUBY
+      #
+      # Autocorrection is UNSAFE and only offered when the heredoc has no LIVE
+      # (unescaped) interpolation: switching the delimiter to single-quoted would
+      # freeze a live interpolation into literal text, changing behaviour. When a
+      # live interpolation is present the cop reports but leaves the fix to a human.
+      class EscapedInterpolationInHeredoc < Base
+        extend AutoCorrector
+
+        MSG = "Use a single-quoted heredoc delimiter (`%<delimiter>s`) so " \
+              "`\#{...}` is literal without escaping."
+        MSG_LIVE = "#{MSG} This heredoc also has a live interpolation — fix by hand.".freeze
+
+        # A backslash directly in front of an interpolation opener. Ruby opens an
+        # interpolation with `#{`, `#@` (ivar/cvar), or `#$` (global), so an escape
+        # is a backslash + `#` + one of those sigil characters. The lookahead keeps
+        # the sigil out of the match, so de-escaping only strips the backslash.
+        ESCAPED_INTERPOLATION = /\\#(?=[{@$])/
+
+        def on_str(node)
+          check_heredoc(node)
+        end
+
+        # A heredoc with a live `#{...}` parses as a dstr; the escaped ones inside
+        # it still show up in the body source. Same check.
+        def on_dstr(node)
+          check_heredoc(node)
+        end
+
+        private
+
+        def check_heredoc(node)
+          return unless node.heredoc?
+
+          opening = node.loc.expression
+          return if single_quoted?(opening.source)
+          return unless escaped_interpolation?(node)
+
+          live = live_interpolation?(node)
+          add_offense(opening, message: message(opening.source, live: live)) do |corrector|
+            next if live # unsafe to autocorrect — a live #{...} would freeze
+
+            autocorrect(corrector, node, opening)
+          end
+        end
+
+        def message(delimiter, live:)
+          format(live ? MSG_LIVE : MSG, delimiter: single_quote(delimiter))
+        end
+
+        # `<<~RUBY` → `<<~'RUBY'`. The prefix (`<<`, `<<~`, or `<<-`) is kept; only
+        # the identifier gets wrapped in single quotes.
+        def single_quote(delimiter)
+          delimiter.sub(/(<<[~-]?)(\w+)\z/, "\\1'\\2'")
+        end
+
+        def single_quoted?(delimiter)
+          delimiter.include?("'")
+        end
+
+        def escaped_interpolation?(node)
+          node.loc.heredoc_body.source.match?(ESCAPED_INTERPOLATION)
+        end
+
+        # A live interpolation makes the heredoc a dstr whose children include a
+        # non-`str` node: `#{expr}` → a `begin` child, `#@ivar` → an `ivar` child,
+        # `#$global` → a `gvar` child. Escaped forms stay inside plain `str`
+        # children, so a str heredoc — or a dstr of only `str` children — is safe
+        # to convert. (Checking "not a str" rather than enumerating begin/ivar/gvar
+        # covers every interpolation node the parser can emit.)
+        def live_interpolation?(node)
+          node.dstr_type? && node.children.any? { |child| !child.str_type? }
+        end
+
+        # Swap the opening delimiter for its single-quoted form and drop the
+        # backslash from every escaped interpolation (`\#{`, `\#@`, `\#$`) in the
+        # body — the single-quoted delimiter already makes each one literal, and
+        # leaving a backslash behind would turn an escape-consumed byte into a
+        # literal one, changing the string.
+        def autocorrect(corrector, node, opening)
+          corrector.replace(opening, single_quote(opening.source))
+
+          body = node.loc.heredoc_body
+          unescaped = body.source.gsub(ESCAPED_INTERPOLATION, "#")
+          corrector.replace(body, unescaped)
+        end
+      end
+    end
+  end
+end