docs-kit 1.1.1 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fee711dcf42e9b92cf749684ea9b94c07ef9d614cf21746881f2c7402f744ea
-  data.tar.gz: 76e246db5be838d3b31b8f08a98d033c57e3765d82900245723afc32fd4cad5f
+  metadata.gz: 04c64683910c10c37f660008f8891ca9f87296a0aea1ddc67f9d9a199975cccd
+  data.tar.gz: d357822c1df8899b50008f28366992bde0b9d6f622ec90975b5926f11d2de2d7
 SHA512:
-  metadata.gz: 1a9cd702122f1e7af103b4279d7e3f4d45e8e662d5838931ac622383ce23609befd8557daddd2b3ac4afda772fc148cf0f5458546a8776b6bae3168408f59065
-  data.tar.gz: 05ce8bb90585331cdaefa92973c36b67d55b2b6164aae03f55d4679a35d8ce7c4128295e4919a3775123cecaa923355baf1622481741ca3a4312394d5b0dd0a2
+  metadata.gz: a2b905a1b80c5e156ea7e652ba45cb4d2ec54c91ad040754112cdd481644b7698fd5356459faf06f46ac140c0c6562b8989039b69585b3f257a3b5629cfe0d49
+  data.tar.gz: 9837ae7885fb3c6ad358b585853aa7d0dee63b9807c574f15e8543f70ae5de6ecea4f5a2755391588a111fa5d05fcf2456a76b9040a648b86bcf3cf767700171

data/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 ## [Unreleased]
 
+### Upgrading from 1.1
+
+```bash
+bundle update docs-kit
+bin/rails g docs_kit:install --sync   # applies the 1.2 migration, prints what it can't
+bun install && bun run build:css
+bundle exec rspec
+```
+
+- **Ruby 3.3 or newer is required.** docs-kit 1.2 won't install on 3.2. Move
+  `.ruby-version` and the Dockerfile's `ARG RUBY_VERSION` first (`--sync` warns
+  about either one if it's still below 3.3).
+- **`--sync` raises the toolchain it scaffolded.** In a Dockerfile that still
+  carries docs-kit's old `ARG BUN_VERSION=1.3.2`, it bumps that to 1.4.2. In
+  `package.json`, it raises docs-kit's old `tailwindcss` / `@tailwindcss/cli
+  ^4.1.18` and `daisyui ^5.6.0` floors to `^4.3.3` / `^5.7.47`. Values you
+  picked yourself are never rewritten: an older one is printed as a warning,
+  and a newer one is left alone. Review the result with `git diff`.
+- **Deploys pick up Node 24 actions and `ubuntu-26.04` automatically** when your
+  `deploy-docs.yml` calls `zoolutions/docs-kit/.github/workflows/deploy.yml@main`
+  (what `docs-kit new` scaffolds). `--sync` warns about a caller pinned to a tag
+  or SHA; move the pin forward.
+- **Untrack `app/assets/stylesheets/tailwind.sources.css`** if it's committed:
+  `git rm --cached app/assets/stylesheets/tailwind.sources.css`. The generator
+  now gitignores it; `--sync` reminds you when it's still tracked.
+
+### Removed
+
+- **Ruby 3.2 support.** `required_ruby_version` is now `>= 3.3` (3.2 reached
+  end of life in March 2026), and CI no longer tests it.
+
+### Changed
+
+- **daisyui 2.x is allowed.** The dependency is now `>= 1.2, < 3`. 1.2.0 was
+  tagged but never reached RubyGems (its release run failed a stale spec), so
+  1.2.1 is the first published 1.2 release.
+- **The reusable deploy workflow runs on Node 24 actions.** `deploy.yml` now
+  uses `actions/checkout@v7`, `docker/setup-buildx-action@v4`,
+  `docker/login-action@v4`, `docker/build-push-action@v7` and
+  `webfactory/ssh-agent@v0.10.0`, clearing the Node 20 deprecation warning for
+  every site that calls it. Its jobs run on `ubuntu-26.04` (ahead of the
+  `ubuntu-latest` migration).
+- **`docs_kit:install` scaffolds current toolchain floors.** The `package.json`
+  stub requires `tailwindcss`/`@tailwindcss/cli` `^4.3.3` and `daisyui`
+  `^5.7.47` (a spec keeps them in lockstep with the gem's own docs site), and
+  the generated `Dockerfile` installs Bun 1.4.2 (and falls back to Ruby 3.4.11
+  when the host Ruby version can't be read).
+- **`docs_kit:install` gitignores the generated `tailwind.sources.css`.**
+  `bin/build-css` rewrites it on every build with machine-specific gem paths, so
+  a committed copy only churns. `--sync` adds the `.gitignore` entry and warns
+  when the file is still tracked. (#72)
+- **`--sync` runs its first release migration** (1.1 → 1.2, above). The
+  migration registry no longer ships empty.
+
+### Fixed
+
+- **`docs_kit:page` injected the registry line once per group.** In a registry
+  laid out as blank-line-separated groups (the layout `docs_kit:install`
+  produces), the "page line not followed by a page line" Regexp anchor matched
+  the end of *every* group and Thor's `inject_into_file` replaced every match.
+  The anchor is now the file's last `page` line as a String, so one run adds
+  exactly one line, at the end of the last group.
+
+### Added
+
+- **`DocsUI::Code` infers the language from `filename:`.**
+  `DocsUI::Code(<<~YAML, filename: "config/deploy.yml")` now highlights as YAML
+  instead of Ruby: with no `lexer:`, the lexer is guessed from Rouge's filename
+  globs (`*.yml` → yaml, `Dockerfile` → docker, `*.sh` → shell, …). An explicit
+  `lexer:` still wins, and a block with neither (or an unguessable filename)
+  stays Ruby, so existing output is unchanged.
+
+## [1.1.1] and earlier
+
 ### Fixed
 
 - **SEO `og:image` 404.** The og:image tag pointed at the raw config path

data/README.md

@@ -102,9 +102,17 @@ A site created before the stamp existed (no comment) is treated as the earliest
 version, so it gets every migration. Migrations are **warn-only-safe** exactly
 like the drift report: what a step can't safely automate it prints as a manual
 checklist (`migration steps to apply by hand:`), never a destructive rewrite of
-a line you've edited. There are no migrations to apply yet — the mechanism ships
-ahead of the first release that needs one, so the upgrade path is already in
-place.
+a line you've edited. A value is only rewritten when it is exactly what an older
+docs-kit generated; anything you picked yourself is reported, never changed.
+
+Every release that needs site changes lists them under **"Upgrading from X.Y"**
+at the top of its [CHANGELOG](CHANGELOG.md) entry. That's what `--sync` automates
+and what it leaves to you. Read it before a `bundle update docs-kit` that crosses
+a minor version.
+
+| Release | `--sync` does | You do |
+|---------|---------------|--------|
+| 1.2 | Raises the Bun and Tailwind/daisyUI floors that docs-kit generated. Warns about Ruby below 3.3, hand-picked older floors, and a deploy workflow pinned off `@main` | Move to Ruby >= 3.3 before updating. `git rm --cached` a tracked `tailwind.sources.css` |
 
 ### One-time cleanup for sites created before these landed
 
@@ -118,6 +126,7 @@ generators:
 | `app/helpers/icon_helper.rb` | docs-kit renders icons via rails_icons (`DocsUI::Icon`) | Delete the file. |
 | Hand-pinned docs-kit lines in `config/importmap.rb` | the engine auto-pins the `docs-nav` controller and its assets | Delete the manual `pin`/`pin_all_from` lines for docs-kit. |
 | `Dockerfile` stamped by an older docs-kit (`# docs-kit Dockerfile vX.Y.Z`) | docs-kit ships an optimized, multi-stage Dockerfile; a stale copy misses image-size wins | Diff yours against the current template (`lib/generators/docs_kit/install/templates/Dockerfile.tt` in the gem), adopt the changes or replace it. See [Upgrading your Dockerfile](#upgrading-your-dockerfile). |
+| `app/assets/stylesheets/tailwind.sources.css` committed to git | `bin/build-css` regenerates it on every build with machine-specific absolute gem paths — the committed copy churns per machine/Ruby and no build consumes it. The generator adds the `.gitignore` entry, but gitignoring doesn't untrack an already-committed copy. | `git rm --cached app/assets/stylesheets/tailwind.sources.css` and commit. |
 
 ### Upgrading your Dockerfile
 
@@ -433,6 +442,10 @@ DocsUI::Section("Add the gem", id: "add", description: …)  # title positional
 DocsUI::Code(source, lexer: :ruby, filename: "Gemfile")   # source positional
 ```
 
+`DocsUI::Code` infers the language from `filename:` (`config/deploy.yml` →
+YAML, `Dockerfile` → docker, `bin/setup.sh` → shell); `lexer:` overrides the
+guess, and with neither the block is highlighted as Ruby.
+
 For the two wrappers that take **no** positional argument — prose and a
 multi-language example — `DocsUI::Page` gives you lowercase helpers so a block
 needs no parens:
@@ -930,7 +943,7 @@ jobs:
 ```yaml
 service: <repo>
 image: zoolutions/<repo>
-minimum_version: 4.0.0        # dash 4: dash-proxy identity + in-place host migration
+minimum_version: 4.0.7        # dash 4.0.7: doctor stale-proxy recovery + registry credential fail-fast
 retain_containers: 2
 error_pages_path: public      # 502/503/504.html served during a deploy gap
 registry: { server: ghcr.io, username: mhenrixon, password: [DASH_REGISTRY_PASSWORD] }
@@ -1082,17 +1095,21 @@ application.register("reactive", ReactiveController)
 
 ## Releasing (maintainers)
 
-Cut a release with the version-bumping Rake task — never `gem push` by hand:
+Cut a release with `bin/release`. Never `gem push` by hand:
 
 ```bash
-rake release[1.0.0]           # bump → build-verify → commit → push → GitHub Release
-rake release[1.1.0.rc1]       # a pre-release (auto-flagged --prerelease)
-rake release[1.0.0,force]     # delete + re-create an existing tag/release
+bin/release list              # last releases + what each bump would give
+bin/release --dry-run         # the version it would cut + the changes since the last tag
+bin/release                   # patch bump (minor / major / 1.3.0.rc1 for others)
+bin/release 1.2.0 --force     # delete + re-create an existing tag/release
 ```
 
-The task (on `main`, clean tree only) bumps `lib/docs_kit/version.rb`, updates the
-lockfiles (incl. `docs/Gemfile.lock`), verifies `gem build --strict`, commits,
-pushes, and creates the GitHub Release. Publishing the tag fires
+`bin/release` checks you're on a clean, up-to-date `main`, confirms, and hands off
+to `rake release[X.Y.Z]` (`rakelib/release.rake`). That task bumps
+`lib/docs_kit/version.rb` and the `docs-kit` pin in `docs/Gemfile.lock` (in place,
+no re-resolve), verifies `gem build --strict`, commits, pushes, and creates the
+GitHub Release. Both files belong to the zoolutions release kit that every gem
+shares; see [RELEASE_KIT.md](RELEASE_KIT.md) to adopt or upgrade it elsewhere. Publishing the tag fires
 `.github/workflows/release.yml`, which runs the suite, rebuilds + content-checks
 the gem, signs it with Sigstore, and pushes to RubyGems over **OIDC trusted
 publishing** (no API token stored anywhere).

data/app/components/docs_ui/code.rb

@@ -9,12 +9,16 @@ module DocsUI
   # stylesheet asset is required.
   #
   #   render DocsUI::Code.new(ruby_source)                          # ruby, no title
-  #   render DocsUI::Code.new(py, lexer: :python, filename: "a.py")  # any language
+  #   render DocsUI::Code.new(yaml, filename: "config/deploy.yml")  # yaml, inferred
+  #   render DocsUI::Code.new(py, lexer: :python, filename: "a.py")  # explicit wins
   #
-  # Any language Rouge knows (~200 lexers) works by its name or alias — python,
-  # go, rust, elixir, kotlin, swift, json, dockerfile, ... — no allowlist. Add
-  # friendly lexer aliases via DocsKit.configure (code_lexer_aliases). An unknown
-  # language falls back to plaintext (never raises). (Tab labels are a
+  # The language resolves in order: an explicit `lexer:`; a guess from the
+  # `filename:` (Rouge's own filename globs — *.yml → yaml, Dockerfile → docker,
+  # *.sh → shell, …); else ruby. Any language Rouge knows (~200 lexers) works by
+  # its name or alias — python, go, rust, elixir, kotlin, swift, json,
+  # dockerfile, ... — no allowlist. Add friendly lexer aliases via
+  # DocsKit.configure (code_lexer_aliases). An unknown language falls back to
+  # plaintext (never raises). (Tab labels are a
   # DocsUI::Example concern — set via code_language_labels, not here; Code has no
   # label, only a filename.)
   class Code < Phlex::HTML
@@ -22,7 +26,7 @@ module DocsUI
 
     FORMATTER = Rouge::Formatters::HTML.new
 
-    def initialize(source, lexer: :ruby, filename: nil)
+    def initialize(source, lexer: nil, filename: nil)
       @source = source.to_s.strip
       @lexer = lexer
       @filename = filename
@@ -66,11 +70,26 @@ module DocsUI
       end
     end
 
-    # Resolve @lexer to a Rouge lexer instance. Order: an explicit Rouge::Lexer
-    # class/instance passed through; a configured friendly alias; Rouge's own
-    # registry (name/alias); then the configured fallback (plaintext).
+    # Resolve the lexer to a Rouge lexer instance. Order: an explicit Rouge::Lexer
+    # class/instance passed through; an explicit name via a configured friendly
+    # alias → Rouge's own registry → the configured fallback (plaintext); with no
+    # `lexer:` given, a guess from the filename; else the ruby default.
     def lexer
-      explicit_lexer || (find_lexer(@lexer.to_s) || Rouge::Lexers::PlainText).new
+      explicit_lexer ||
+        (@lexer && (find_lexer(@lexer.to_s) || Rouge::Lexers::PlainText).new) ||
+        guessed_lexer ||
+        Rouge::Lexers::Ruby.new
+    end
+
+    # A lexer inferred from @filename via Rouge's declared filename globs, or nil
+    # when there is no filename, nothing matches, or the match is ambiguous.
+    # (Lexer.guesses, not Lexer.guess: the latter answers PlainText for a
+    # no-match, which is indistinguishable from a real guess.)
+    def guessed_lexer
+      return nil if @filename.nil?
+
+      guesses = Rouge::Lexer.guesses(filename: @filename.to_s)
+      guesses.size == 1 ? guesses.first.new : nil
     end
 
     # A Rouge::Lexer instance passed directly (class or instance), else nil.

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.2.1"
 end

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/

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -18,7 +18,7 @@ dependencies:
         version: '1.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -28,7 +28,7 @@ dependencies:
         version: '1.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: phlex-rails
   requirement: !ruby/object:Gem::Requirement
@@ -244,6 +244,7 @@ files:
 - lib/generators/docs_kit/install/install_generator.rb
 - lib/generators/docs_kit/install/migration.rb
 - lib/generators/docs_kit/install/migration_registry.rb
+- lib/generators/docs_kit/install/migrations/v1_2_0.rb
 - lib/generators/docs_kit/install/sync_report.rb
 - lib/generators/docs_kit/install/templates/Dockerfile.tt
 - lib/generators/docs_kit/install/templates/agents_md.erb
@@ -281,7 +282,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="