docs-kit 1.1.1 → 1.3.0

data/app/components/docs_ui/shell.rb

@@ -72,9 +72,13 @@ module DocsUI
     # injected by the controller under the active nav link (no content slot).
     def content_toc? = %i[panel toggle].include?(@on_page)
 
+    # "Page · Suffix", or just the suffix on a title-less page. The suffix is
+    # resolved per render (a callable title_suffix/brand → this request's value).
+    def document_title = [@title, config.title_suffix_text].compact.join(" · ")
+
     def render_head
       head do
-        title { [@title, config.title_suffix].compact.join(" · ") }
+        title { document_title }
         meta(charset: "utf-8")
         meta(name: "viewport", content: "width=device-width,initial-scale=1")
         # SEO / social-share tags (description, Open Graph, Twitter Card,
@@ -90,10 +94,20 @@ module DocsUI
         meta(name: "turbo-refresh-scroll", content: "preserve")
         config.stylesheets.each { |sheet| stylesheet_link_tag(sheet, data: { turbo_track: "reload" }) }
         theme_restore_script
-        javascript_importmap_tags
+        importmap_tags
       end
     end
 
+    # The import map tags for config.importmap_entry_point, from config.importmap
+    # when one is set. With nothing configured this is the helper's own default
+    # call, so the head matches a Shell that predates the knobs.
+    def importmap_tags
+      map = config.resolved_importmap
+      return javascript_importmap_tags(config.importmap_entry_point) if map.nil?
+
+      javascript_importmap_tags(config.importmap_entry_point, importmap: map)
+    end
+
     # Restore the persisted theme BEFORE first paint so there's no flash of the
     # server default before the docs-nav controller runs. Reads the same
     # localStorage key the controller writes (docs-kit:<site>:theme). Runs on
@@ -183,9 +197,9 @@ module DocsUI
     # text brand stays the mark's accessible-name fallback.
     def brand_mark
       if (logo = config.brand_logo)
-        render DocsUI::Logo.new(logo, class: "h-6 w-auto", label: config.brand)
+        render DocsUI::Logo.new(logo, class: "h-6 w-auto", label: config.brand_text)
       else
-        plain config.brand
+        plain config.brand_text
       end
     end
 

data/app/components/docs_ui/sidebar.rb

@@ -59,9 +59,9 @@ module DocsUI
     # Slightly taller than the topbar's h-6: this is the masthead.
     def brand_mark
       if (logo = config.brand_logo)
-        render DocsUI::Logo.new(logo, class: "h-7 w-auto", label: config.brand)
+        render DocsUI::Logo.new(logo, class: "h-7 w-auto", label: config.brand_text)
       else
-        plain config.brand
+        plain config.brand_text
       end
     end
 

data/app/controllers/docs_kit/llms_controller.rb

@@ -71,9 +71,12 @@ module DocsKit
     # Revalidate on the rendered body itself (so any registry/config/page change
     # busts it) plus the gem version as the etag salt. In development, always
     # re-render; production sites deploy immutably so the version etag is stable.
+    # A callable brand (#92) makes the body per-request, so the response is then
+    # `private`: a shared cache must not hand one tenant's llms.txt to another.
     def stale_llms?(body)
-      expires_in LLMS_MAX_AGE, public: true
-      stale?(etag: [DocsKit::VERSION, body], public: true)
+      shared = !docs_config.brand_per_request?
+      expires_in LLMS_MAX_AGE, public: shared
+      stale?(etag: [DocsKit::VERSION, body], public: shared)
     end
 
     # A page's Markdown twin, rendered through this controller's view context so

data/lib/docs_kit/configuration.rb

@@ -78,6 +78,17 @@ module DocsKit
     # stylesheets (e.g. a separate rouge theme) lists them here.
     attr_accessor :stylesheets
 
+    # The import map entry point the Shell loads. Defaults to "application"
+    # (javascript_importmap_tags' own default). A host with a dedicated docs
+    # import map names its entry point here, e.g. "docs".
+    attr_accessor :importmap_entry_point
+
+    # The import map the Shell renders: nil (the default → the host's
+    # Rails.application.importmap), an Importmap::Map, or a zero-arity callable
+    # returning one, resolved per render so a map rebuilt on code reload is
+    # picked up. Read via #resolved_importmap.
+    attr_accessor :importmap
+
     # The Rouge theme class used by DocsUI::Code for inline syntax-highlight CSS.
     # This is the BASE (light) theme, emitted un-scoped so it applies to every
     # theme unless a dark override wins (see #code_theme_dark).
@@ -307,6 +318,8 @@ module DocsKit
       @nav_registries = {}
       @version_badge = nil
       @stylesheets = %w[application]
+      @importmap_entry_point = "application"
+      @importmap = nil
       @code_theme = "Rouge::Themes::Monokai"
       @code_theme_dark = nil
       @dark_themes = DEFAULT_DARK_THEMES
@@ -544,14 +557,54 @@ module DocsKit
 
     public
 
+    # The localStorage namespace. A callable brand can't be slugged: the key must
+    # be stable per browser, not per request, so a callable brand needs an
+    # explicit c.nav_storage_key (checked again by DocsKit.configure).
     def nav_storage_key
-      @nav_storage_key || @brand.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+      return @nav_storage_key if @nav_storage_key
+      if @brand.respond_to?(:call)
+        raise DocsKit::Error,
+              "c.brand is a callable, so set c.nav_storage_key to a stable key " \
+              "(the sidebar/theme localStorage namespace must not change per request)"
+      end
+
+      @brand.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
     end
 
+    # The raw configured suffix (or the raw brand when unset). The chrome reads
+    # #title_suffix_text, which resolves a callable.
     def title_suffix
       @title_suffix || @brand
     end
 
+    # The rendered brand. A String is returned as-is; a zero-arity callable is
+    # invoked on every read (never memoize it — the point is a per-request
+    # value, e.g. -> { Current.tenant_name }).
+    def brand_text
+      resolve_text(@brand).to_s
+    end
+
+    # True when the brand is a callable, i.e. anything that embeds the brand
+    # (the chrome, llms.txt) may differ per request and must not be stored in a
+    # shared cache.
+    def brand_per_request?
+      @brand.respond_to?(:call)
+    end
+
+    # The rendered <title>/og:title suffix: #title_suffix resolved like
+    # #brand_text, falling back to the resolved brand. nil only when both are nil,
+    # so the title join drops it instead of leaving a dangling separator.
+    def title_suffix_text
+      resolve_text(@title_suffix.nil? ? @brand : @title_suffix)
+    end
+
+    # Raises at configure time for a config the chrome can't render (today: a
+    # callable brand without a stable nav_storage_key). Called by DocsKit.configure.
+    def validate!
+      nav_storage_key
+      self
+    end
+
     # Whether the built-in MCP endpoint is active: the #mcp toggle is on AND the
     # optional `mcp` gem is loadable — the same "toggle AND capability" shape as
     # #search_enabled?. Read by DocsKit::LlmsText (to advertise /mcp in llms.txt)
@@ -609,6 +662,12 @@ module DocsKit
       @version_badge.to_s
     end
 
+    # The import map the Shell renders, or nil for the host's default map. A
+    # callable is invoked on every read (once per render).
+    def resolved_importmap
+      @importmap.respond_to?(:call) ? @importmap.call : @importmap
+    end
+
     # The default Rouge theme both #code_theme_class and #code_theme_dark_class
     # fall back to when a configured theme name can't be resolved — so a typo'd
     # theme name degrades gracefully instead of raising on every code block.
@@ -652,5 +711,12 @@ module DocsKit
     rescue NameError
       nil
     end
+
+    # A String-or-callable knob's value for this render: a callable is invoked
+    # and stringified, nil stays nil, anything else is stringified.
+    def resolve_text(value)
+      value = value.call if value.respond_to?(:call)
+      value&.to_s
+    end
   end
 end

data/lib/docs_kit/engine.rb

@@ -36,10 +36,17 @@ module DocsKit
       app.config.assets.paths << JAVASCRIPT_PATH.to_s if app.config.respond_to?(:assets)
     end
 
+    # Host-facing engine options. `config.docs_kit.auto_pin = false` (in
+    # config/application.rb) keeps the gem's pin out of the host's shared import
+    # map, for a host that pins `docs_kit/controllers` in a dedicated docs map.
+    config.docs_kit = ActiveSupport::OrderedOptions.new
+    config.docs_kit.auto_pin = true
+
     # Auto-pin the controller for importmap-rails consumers, so a host app gets
     # `docs_kit/controllers/docs_nav_controller` with no manual pin.
     initializer "docs_kit.importmap", before: "importmap" do |app|
       next unless app.config.respond_to?(:importmap)
+      next unless app.config.docs_kit.auto_pin
 
       importmap = app.config.importmap
       importmap.paths << root.join("config/importmap.rb") if importmap.respond_to?(:paths)

data/lib/docs_kit/llms_text.rb

@@ -33,7 +33,7 @@ module DocsKit
     # single tight list (no blank lines between bullets), per the llmstxt.org
     # convention.
     def index(config, base_url: nil)
-      blocks = ["# #{config.brand}"]
+      blocks = ["# #{config.brand_text}"]
       tagline = config.tagline
       blocks << "> #{tagline}" if tagline && !tagline.to_s.empty?
       blocks.concat(section_blocks(config, base_url))

data/lib/docs_kit/mcp_server.rb

@@ -28,7 +28,7 @@ module DocsKit
       return unless mcp_available?
 
       server = MCP::Server.new(
-        name: config.brand.to_s,
+        name: config.brand_text,
         version: DocsKit::VERSION,
         instructions: instructions_for(config, base_url),
         server_context: { config:, base_url:, view_context: }
@@ -54,7 +54,7 @@ module DocsKit
       lines = []
       tagline = config.tagline
       lines << tagline.to_s if tagline && !tagline.to_s.empty?
-      lines << "Read-only documentation tools for #{config.brand}. " \
+      lines << "Read-only documentation tools for #{config.brand_text}. " \
                "Use search_docs to find sections, get_page to read a page's Markdown, " \
                "and list_pages to enumerate the docs. Full index: #{llms}."
       lines.join(" ")

data/lib/docs_kit/templates/new_site.rb

@@ -64,7 +64,7 @@ after_bundle do
 
     # dash 4 renamed the on-host proxy (kamal-proxy → dash-proxy) and migrates a
     # host in place; an older CLI must not deploy this config.
-    minimum_version: 4.0.0
+    minimum_version: 4.0.7
 
     # A stateless docs site never rolls back far — keep the host tidy.
     retain_containers: 2

data/lib/docs_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DocsKit
-  VERSION = "1.1.1"
+  VERSION = "1.3.0"
 end

data/lib/docs_kit.rb

@@ -25,7 +25,7 @@ module DocsKit
 
     def configure
       yield(configuration)
-      configuration
+      configuration.validate!
     end
 
     def reset_configuration!

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

@@ -57,6 +57,12 @@ module DocsKit
 
       def self.synced_stamp(version = DocsKit::VERSION) = "# docs-kit synced: v#{version}"
 
+      # The generated Tailwind @source globs file bin/build-css rewrites on
+      # every build — gitignored fleet-wide (see ignore_generated_css_sources).
+      # The covering/negation line regexes live beside the path in SyncReport,
+      # which shares them for the tracked-file drift check.
+      TAILWIND_SOURCES = SyncReport::TAILWIND_SOURCES
+
       # The RuboCop wiring docs-kit injects. REQUIRE loads the cops;
       # INHERIT_GEM/INHERIT_PATH enable + scope them (see config/rubocop/docs_kit.yml).
       RUBOCOP_REQUIRE = "docs_kit/rubocop"
@@ -192,6 +198,35 @@ module DocsKit
         create_file "app/assets/builds/.keep", ""
       end
 
+      # Gitignore the bin/build-css-generated @source globs file (#71). It
+      # carries machine-specific absolute gem paths, so a committed copy churns
+      # on every rebuild by a different machine/Ruby — and no build consumes it
+      # (.dockerignore excludes it; every build path runs bin/build-css first).
+      # Additive + idempotent (tolerant of a hand-added entry with or without
+      # the leading slash), and NOT --sync-guarded: the ignore is the fleet-wide
+      # upgrade this step exists to ship. Untracking an already-committed copy
+      # is the site's call — SyncReport warns with the exact command instead
+      # (the generator never mutates git state).
+      def ignore_generated_css_sources
+        entry = "# Generated by bin/build-css (resolved gem @source globs).\n/#{TAILWIND_SOURCES}\n"
+        path = File.join(destination_root, ".gitignore")
+        return create_file(".gitignore", entry) unless File.exist?(path)
+
+        # Last-match-wins, like git reads the file: an EFFECTIVE `!` unignore is
+        # the site's deliberate opt-out — appending our entry after it would
+        # become the last matching rule and silently defeat the hand-edit, so
+        # back off (SyncReport skips its nag too). An effective ignore is done.
+        case SyncReport.tailwind_sources_rule(File.read(path))
+        when :negate
+          say_status(:skip, ".gitignore negates tailwind.sources.css (!) — respecting the site's opt-out",
+                     :yellow)
+        when :ignore
+          say_status(:identical, ".gitignore (tailwind.sources.css)", :blue)
+        else
+          append_to_file ".gitignore", "\n#{entry}"
+        end
+      end
+
       # Install the `docs_kit:og` rake task — gem-owned wiring, refreshed on every
       # run so a site picks up task fixes. It does NOT ship an OG image: the
       # social-share image is SITE content, generated into the site's OWN
@@ -539,9 +574,9 @@ module DocsKit
               "watch:css": "bin/build-css --watch"
             },
             "devDependencies": {
-              "@tailwindcss/cli": "^4.1.18",
-              "daisyui": "^5.6.0",
-              "tailwindcss": "^4.1.18"
+              "@tailwindcss/cli": "^4.3.3",
+              "daisyui": "^5.7.47",
+              "tailwindcss": "^4.3.3"
             }
           }
         JSON
@@ -578,7 +613,7 @@ module DocsKit
       # The RUBY_VERSION build ARG default: the host's running Ruby (X.Y.Z), so a
       # site's image matches its dev Ruby. Used in Dockerfile.tt.
       def ruby_version_arg
-        RUBY_VERSION[/\d+\.\d+\.\d+/] || "3.4.2"
+        RUBY_VERSION[/\d+\.\d+\.\d+/] || "3.4.11"
       end
 
       # True when the site bundles Thruster (HTTP caching + compression +

data/lib/generators/docs_kit/install/migration_registry.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "migration"
+require_relative "migrations/v1_2_0"
 require_relative "../../../docs_kit/version"
 
 module DocsKit
@@ -18,24 +19,26 @@ module DocsKit
     # re-run on EVERY sync forever. It can't legitimately exist anyway (a site
     # can't have "arrived" at a release it doesn't have), so it's filtered out.
     #
-    # `.default` is the registry the generator uses. It SHIPS EMPTY at 1.0.x —
-    # the mechanism (stamp the synced version, detect the gap, run ordered
-    # transforms) is the deliverable; the first concrete `1.x → 1.y` transform is
-    # a one-line `Migration.new(...)` addition here once a release needs one.
+    # `.default` is the registry the generator uses. Each release that changes
+    # what a site must carry adds one `Migration.new(...)` entry to MIGRATIONS,
+    # its transform in migrations/vX_Y_Z.rb.
     class MigrationRegistry
       def initialize(migrations = [])
         @migrations = migrations.sort_by(&:to)
       end
 
-      # The registry the install generator runs during `--sync`. Empty today.
+      # The registry the install generator runs during `--sync`.
       def self.default
         @default ||= new(MIGRATIONS)
       end
 
-      # No migrations to register yet — the mechanism is the 1.0 deliverable.
-      # Add ordered `Migration.new(to: "1.x.0", description: "...") { ... }`
-      # entries here as future releases change config knobs, routes, or templates.
-      MIGRATIONS = [].freeze
+      # Ordered `Migration.new(to: "1.x.0", description: "...") { ... }` entries, one
+      # per release that changes config knobs, routes, templates, or toolchain.
+      MIGRATIONS = [
+        Migration.new(to: "1.2.0", description: Migrations::V1_2_0::DESCRIPTION) do |root, _generator|
+          Migrations::V1_2_0.call(root)
+        end
+      ].freeze
 
       # The migrations a site last synced at `from_version` still needs, ascending
       # by version — those in `(from_version, upto]`. `upto` defaults to the

data/lib/generators/docs_kit/install/migrations/v1_2_0.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module DocsKit
+  module Generators
+    module Migrations
+      # The 1.1 → 1.2 upgrade. docs-kit 1.2 needs Ruby >= 3.3, scaffolds Bun 1.4.2
+      # and newer Tailwind/daisyUI floors, and its reusable deploy workflow moved to
+      # Node 24 actions (only callers that track `@main` get that).
+      #
+      # Warn-only-safe: a value is rewritten only when it is EXACTLY what an older
+      # docs-kit generated (so it can't be a hand edit); anything else older is
+      # handed back as a warning, and a newer value is left alone.
+      module V1_2_0 # rubocop:disable Naming/ClassAndModuleCamelCase -- named after the release
+        DESCRIPTION = "docs-kit 1.2: Ruby >= 3.3, Bun 1.4.2, Tailwind 4.3 / daisyUI 5.7 floors, Node 24 deploy"
+        MIN_RUBY = Gem::Version.new("3.3")
+        BUN = { from: "1.3.2", to: "1.4.2" }.freeze
+        PACKAGE_FLOORS = {
+          "tailwindcss" => { from: "^4.1.18", to: "^4.3.3" },
+          "@tailwindcss/cli" => { from: "^4.1.18", to: "^4.3.3" },
+          "daisyui" => { from: "^5.6.0", to: "^5.7.47" }
+        }.freeze
+        DEPLOY_CALL = %r{zoolutions/docs-kit/\.github/workflows/deploy\.yml@(\S+)}
+
+        module_function
+
+        # Returns the warnings it could not safely automate.
+        def call(root)
+          bun(root) + ruby(root) + package_floors(root) + deploy_pins(root)
+        end
+
+        def bun(root)
+          edit(root, "Dockerfile") do |source, warnings|
+            current = source[/^ARG BUN_VERSION=(\S+)$/, 1]
+            next source unless current && older?(current, BUN[:to])
+            next source.sub("ARG BUN_VERSION=#{current}", "ARG BUN_VERSION=#{BUN[:to]}") if current == BUN[:from]
+
+            warnings << "Dockerfile: ARG BUN_VERSION=#{current} is older than the #{BUN[:to]} docs-kit now " \
+                        "scaffolds; raise it (a bun.lock written by a newer Bun can fail " \
+                        "`bun install --frozen-lockfile`)"
+            source
+          end
+        end
+
+        def ruby(root)
+          {
+            "Dockerfile" => read(root, "Dockerfile")&.[](/^ARG RUBY_VERSION=\S+$/),
+            ".ruby-version" => read(root, ".ruby-version")&.strip
+          }.filter_map do |file, value|
+            next unless value && below_min_ruby?(value.delete_prefix("ARG RUBY_VERSION="))
+
+            "#{file}: #{value} — docs-kit 1.2 requires Ruby >= #{MIN_RUBY}; move the site to 3.3 or newer"
+          end
+        end
+
+        def package_floors(root)
+          edit(root, "package.json") do |source, warnings|
+            PACKAGE_FLOORS.reduce(source) do |json, (name, floor)|
+              raise_floor(json, name, floor, warnings)
+            end
+          end
+        end
+
+        def raise_floor(json, name, floor, warnings)
+          pair = /("#{Regexp.escape(name)}"\s*:\s*")([^"]+)(")/
+          current = json[pair, 2]
+          return json unless current && older?(current, floor[:to])
+          if current == floor[:from]
+            return json.sub(pair) { "#{Regexp.last_match(1)}#{floor[:to]}#{Regexp.last_match(3)}" }
+          end
+
+          warnings << "package.json: #{name} #{current} is below the #{floor[:to]} docs-kit now builds against"
+          json
+        end
+
+        def deploy_pins(root)
+          Dir[File.join(root, ".github/workflows/*.{yml,yaml}")].filter_map do |path|
+            ref = File.read(path)[DEPLOY_CALL, 1]
+            next if ref.nil? || ref == "main"
+
+            "#{File.basename(path)}: calls docs-kit's deploy.yml@#{ref}; the Node 24 actions and " \
+              "ubuntu-26.04 runners are on @main — move the pin forward (or track @main)"
+          end
+        end
+
+        # Yields [source, warnings] for an existing file; writes back what the block returns.
+        def edit(root, file)
+          source = read(root, file)
+          return [] unless source
+
+          warnings = []
+          updated = yield(source, warnings)
+          File.write(File.join(root, file), updated) unless updated == source
+          warnings
+        end
+
+        def read(root, file)
+          path = File.join(root, file)
+          File.exist?(path) ? File.read(path) : nil
+        end
+
+        # "^5.6.0" / "~> 4.1" / "3.2.4" / "ruby-3.2.4" → its version, or nil when it
+        # isn't a plain version (a tag like "latest", a git URL, a range).
+        def version_of(value)
+          number = value.to_s[/\A(?:ruby-)?[\^~]?>?\s*(\d+(?:\.\d+)*)\z/, 1]
+          number && Gem::Version.new(number)
+        end
+
+        def older?(current, target)
+          current_version = version_of(current)
+          current_version ? current_version < version_of(target) : false
+        end
+
+        def below_min_ruby?(value)
+          version = version_of(value)
+          version ? version < MIN_RUBY : false
+        end
+      end
+    end
+  end
+end

data/lib/generators/docs_kit/install/sync_report.rb

@@ -17,10 +17,54 @@ module DocsKit
     #   - a dead IconHelper copy — the gem renders icons via rails_icons.
     #   - a Dockerfile stamped by an OLDER docs-kit than the gem now ships — the
     #     site should diff against the current template and adopt the improvements.
+    #   - a git-tracked tailwind.sources.css — generated per-build with machine
+    #     absolute gem paths (#71); gitignored now, but untracking a committed
+    #     copy stages a deletion, so the site runs `git rm --cached` itself.
     class SyncReport
       APPLICATION_CONTROLLER = "app/controllers/application_controller.rb"
       ICON_HELPER = "app/helpers/icon_helper.rb"
       DOCKERFILE = "Dockerfile"
+      TAILWIND_SOURCES = "app/assets/stylesheets/tailwind.sources.css"
+
+      # A .gitignore line covering the generated file per gitignore semantics:
+      # the anchored path (leading slash optional — a slash-containing pattern
+      # is root-anchored either way) or the bare filename (no slash → matches
+      # at any depth), each optionally **/-prefixed. Deliberately NOT a full
+      # gitignore matcher: an exotic broader glob (`app/assets/stylesheets/*`)
+      # is missed at the cost of one redundant, harmless line. This regex
+      # drives the generator's APPEND decision only; the drift warning asks
+      # git itself (see #ignored_by_git?, scoped to the committed .gitignore
+      # files so a user's personal excludes never decide repo content).
+      # `[ \t\r]*` (not `[ \t]*`): `$` matches before `\n` but never past a
+      # `\r`, so the class must consume the CR of a CRLF-checked-out file.
+      TAILWIND_SOURCES_COVER =
+        "(?:(?:/|\\*\\*/)?#{Regexp.escape(File.dirname(TAILWIND_SOURCES))}/|(?:\\*\\*/)?)" \
+        "#{Regexp.escape(File.basename(TAILWIND_SOURCES))}[ \t\r]*".freeze
+      TAILWIND_SOURCES_IGNORED_RE = /^#{TAILWIND_SOURCES_COVER}$/
+      # An explicit `!` unignore of the file — the site's deliberate opt-out
+      # from the fleet convention (it wants the file committed). The
+      # generator's append respects it when it's the file's effective rule
+      # (see .tailwind_sources_rule); the drift warning asks git instead
+      # (#ignored_by_git?), which resolves full pattern semantics.
+      TAILWIND_SOURCES_NEGATED_RE = /^!#{TAILWIND_SOURCES_COVER}$/
+
+      # The file's effective disposition among the recognized .gitignore lines,
+      # honoring git's last-match-wins: `:negate` (the site's genuine opt-out),
+      # `:ignore` (already covered), or nil (no recognized line). A `!` line
+      # overridden by a LATER ignore line is dead — git ignores the file, so
+      # treating it as an opt-out would misreport the site's intent. Drives the
+      # generator's append decision only (the drift check asks git itself).
+      def self.tailwind_sources_rule(gitignore_content)
+        rule = nil
+        gitignore_content.each_line do |line|
+          if line.match?(TAILWIND_SOURCES_NEGATED_RE)
+            rule = :negate
+          elsif line.match?(TAILWIND_SOURCES_IGNORED_RE)
+            rule = :ignore
+          end
+        end
+        rule
+      end
 
       # Matches the version stamp the Dockerfile template writes, e.g.
       # `# docs-kit Dockerfile v1.0.2`. Absent on a hand-written Dockerfile a site
@@ -34,7 +78,7 @@ module DocsKit
       # The drift messages, in the order a site should act on them. Empty when
       # the site is clean.
       def items
-        [render_page_drift, icon_helper_drift, dockerfile_drift].compact
+        [render_page_drift, icon_helper_drift, dockerfile_drift, tailwind_sources_drift].compact
       end
 
       def clean?
@@ -79,6 +123,48 @@ module DocsKit
           "diff against the template (bin/rails g docs_kit:install shows the path) and adopt the changes."
       end
 
+      # tailwind.sources.css is regenerated by bin/build-css with machine-local
+      # absolute gem paths — the generator gitignores it, but a copy committed
+      # before the ignore stays tracked (gitignore doesn't untrack). Untracking
+      # stages a deletion, so we hand the site the exact command instead of
+      # touching its index.
+      def tailwind_sources_drift
+        return unless tracked_by_git?(TAILWIND_SOURCES)
+        # git's own verdict, not the recognized-lines regex: git resolves the
+        # FULL pattern semantics (broad globs, ordering, nested .gitignores),
+        # so a dead `!` line before a broader ignore still warns, while a
+        # genuinely effective negation (the site's opt-out) stays quiet.
+        return unless ignored_by_git?(TAILWIND_SOURCES)
+
+        "#{TAILWIND_SOURCES} is generated by bin/build-css but tracked by git — " \
+          "run `git rm --cached #{TAILWIND_SOURCES}` and commit (the ignore entry is in place)."
+      end
+
+      # True when the repo's own .gitignore rules cover `rel` — git's full
+      # pattern semantics (broad globs, `!` ordering, nested .gitignores), but
+      # SCOPED to the repo's committed convention: `--exclude-per-directory`
+      # consults only the .gitignore files, never `.git/info/exclude` or a
+      # global core.excludesFile, so the verdict (and the "the ignore entry is
+      # in place" guidance it backs) is identical on every machine.
+      # `--cached --ignored` reports a TRACKED path matching an exclude — the
+      # exact state this drift check exists to catch. Only called after
+      # tracked_by_git? proved git + a repo exist.
+      def ignored_by_git?(rel)
+        out = IO.popen(["git", "-C", @root, "ls-files", "--cached", "--ignored",
+                        "--exclude-per-directory=.gitignore", "--", rel],
+                       err: File::NULL, &:read)
+        !out.strip.empty?
+      end
+
+      # True when the site's git index tracks `rel`. Conservative: no git on
+      # PATH, not a repo, or an untracked file all read as "no drift". ls-files
+      # only consults the index (no commit needed), and `git -C` resolves the
+      # repo upward, so a docs site living in a subdir of a larger repo works.
+      def tracked_by_git?(rel)
+        system("git", "-C", @root, "ls-files", "--error-unmatch", rel,
+               out: File::NULL, err: File::NULL) == true
+      end
+
       def read(rel)
         path = File.join(@root, rel)
         File.exist?(path) ? File.read(path) : nil

data/lib/generators/docs_kit/install/templates/Dockerfile.tt

@@ -15,7 +15,7 @@ FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base
 # Rails app lives here.
 WORKDIR /rails
 
-ARG BUN_VERSION=1.3.2
+ARG BUN_VERSION=1.4.2
 ENV BUN_INSTALL="/usr/local/bun" \
     PATH="/usr/local/bun/bin:$PATH" \
     BUNDLE_DEPLOYMENT="1" \

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

@@ -66,6 +66,9 @@ end
 - **The primary argument is positional; modifiers are keywords.**
   `Section("Title", description:)`, `Code(source, filename:)`,
   `Header("Title", eyebrow:)`.
+- **`Code`'s `filename:` selects the language** (`*.yml` → yaml, `Dockerfile`
+  → docker, `*.sh` → shell, …); pass `lexer:` only to override the guess or when
+  there is no filename (the default is ruby).
 - **Wrappers that take no positional arg use lowercase page helpers** so a block
   needs no parens: `md <<~'MD' … MD`, `prose { … }`, `example { |ex| … }`,
   `operation "operationId"`. (A bare `DocsUI::Prose do` is a Ruby SyntaxError; the

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

@@ -101,13 +101,19 @@ module DocsKit
         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.
+      # Inject after the last existing `page` line of the FILE so ordering lands
+      # at the end of the last group; else after view_namespace/path_prefix;
+      # else after the `extend DocsKit::Registry` line.
+      #
+      # The `page` anchor is the last matching line as a String, not a Regexp:
+      # Thor's inject_into_file replaces EVERY match of a Regexp `after:`, so a
+      # "page line not followed by a page line" pattern fires once per group in
+      # a registry laid out with blank-line-separated groups (the layout
+      # docs_kit:install produces) and duplicates the entry.
       def registry_anchor(source)
         case source
         when /^\s*page\s+["']/
-          /^\s*page .*\n(?!\s*page )/
+          source.lines.grep(/^\s*page\s+["']/).last
         when /^\s*view_namespace\s/
           /^\s*view_namespace .*\n/
         when /^\s*path_prefix\s/