gem-skill 0.1.2 → 0.2.0

data/docs/skill-files.md

@@ -0,0 +1,141 @@
+# Skill Files
+
+A `SKILL.md` is a structured Markdown document that gives an AI coding assistant
+deep, practical knowledge about a Ruby gem. It's a shared format — assistants
+such as Claude Code and OpenAI Codex read it automatically when it is present in
+the skills directory they look in (Claude Code uses `.claude/skills/`; see
+[Using the cache with other assistants](#using-with-other-assistants)).
+
+## Format
+
+Every generated skill begins with **YAML frontmatter** — the `name` and
+`description` that make it discoverable as an Agent Skill — followed by a
+top-level heading and seven sections:
+
+```markdown
+---
+name: faraday
+description: "HTTP client library for Ruby with pluggable adapters and middleware; use when making HTTP requests... (faraday v2.14.3)"
+---
+
+# faraday v2.14.3
+
+## Overview
+What the gem does and when to reach for it.
+
+## Installation
+Exact Gemfile/gemspec lines and any required post-install steps.
+
+## Core API
+Key classes, methods, and options with real method signatures and return values.
+
+## Common Patterns
+The 3–5 most frequent real-world usage patterns with working code examples.
+
+## Gotchas & Edge Cases
+Surprising defaults, version-specific behavior, thread safety, encoding issues.
+
+## Configuration
+Initializer patterns, environment variables, defaults worth knowing.
+
+## Testing
+How to test code that uses this gem: mocks, fakes, fixtures, VCR patterns.
+```
+
+### Frontmatter
+
+The frontmatter is what registers the file as a skill — both Claude Code and
+OpenAI Codex require it, and the `description` is the text loaded into the
+assistant's context to decide *when* the skill applies. gem-skill generates it
+deterministically:
+
+- **`name`** — the gem name normalized to hyphen-case (lowercase letters,
+  digits, hyphens). For example `ruby_llm` becomes `ruby-llm`, since underscores
+  aren't allowed in skill names.
+- **`description`** — a one-line, trigger-oriented summary derived from the
+  Overview, with the version appended, sanitized to satisfy both assistants
+  (single line, no angle brackets).
+
+## What an assistant does with it
+
+When an assistant opens a project whose skills directory contains `SKILL.md`
+files, it reads every one it finds (Claude Code, for instance, reads everything
+in `.claude/skills/`). This means:
+
+- The assistant knows the correct API for the exact version you're using
+- No token cost re-deriving usage from READMEs mid-conversation
+- The knowledge persists across conversation turns
+- Multiple gems can be in scope simultaneously
+
+## Sources used to generate
+
+The LLM is given up to three sources per gem (in priority order):
+
+1. **Local README + CHANGELOG** — from the gem's install directory
+2. **RubyGems API** — summary, dependencies, source URI
+3. **GitHub raw README** — fetched when not installed locally
+
+Content is synthesized, not copied verbatim. The model is instructed to write
+as a knowledgeable colleague, not a marketing document.
+
+## Quality and regeneration
+
+Skill quality depends on the documentation available for the gem and the model
+used. For gems with poor upstream documentation, results will reflect that.
+
+To improve a skill:
+
+```bash
+# Use a more capable model
+gem skill install my_gem --force --model claude-opus-4-8
+
+# Or set it as the default
+export GEMSKILL_MODEL="claude-opus-4-8"
+gem skill install my_gem --force
+```
+
+## Version specificity
+
+Skills are cached per version. `faraday 2.12.0` and `faraday 2.14.3` each get
+their own `SKILL.md`. Symlinks in `.claude/skills/` point to the version
+matching your `Gemfile.lock`, so the assistant always has the right version
+context.
+
+## Using with other assistants
+
+`SKILL.md` is not specific to one assistant. The `~/.gem/skills` cache is
+assistant-neutral; `bundle skill` links skills into `.claude/skills/`, which
+Claude Code reads automatically. Other assistants discover skills in their own
+roots:
+
+| Assistant | Global roots | Project-local roots |
+|---|---|---|
+| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
+| OpenAI Codex | `~/.codex/skills`, `~/.agents/skills` | `.agents/`, `.codex/` |
+
+**Project-local (recommended):** point `bundle skill` at the right directory with
+the `GEMSKILL_PROJECT_DIR` environment variable (default `.claude/skills`):
+
+```bash
+export GEMSKILL_PROJECT_DIR=".agents"   # or ".codex"
+bundle skill install                    # symlinks now land in .agents/
+```
+
+See [`GEMSKILL_PROJECT_DIR`](configuration.md#gemskill_project_dir) for the full
+table of suggested values.
+
+**Global:** to share cached skills across all projects for an assistant, symlink
+a cached version directory into its global root:
+
+```bash
+ln -s ~/.gem/skills/faraday/2.14.3 ~/.agents/skills/faraday
+```
+
+!!! note "Availability is not the same as activation"
+    Assistants differ in how a present `SKILL.md` becomes active. **Claude Code**
+    treats every `SKILL.md` under `.claude/skills/` as active automatically.
+    **OpenAI Codex** does *not* auto-activate a skill just because the file
+    exists — it must appear in the session's available-skills list, or you must
+    explicitly point Codex at it. So linking a skill into a Codex root makes it
+    *available* but may not make it *active* on its own; check your assistant's
+    skill-discovery rules.

data/lib/gem/skill/cache.rb

@@ -42,6 +42,30 @@ module Gem::Skill
       File.read(path)
     end
 
+    # Read metadata.json back as a Hash with string keys. Returns {} if absent
+    # or unparseable.
+    def self.read_metadata(gem_name, version)
+      path = metadata_path(gem_name, version)
+      return {} unless File.exist?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      {}
+    end
+
+    # Overwrite just the SKILL.md content, leaving metadata untouched.
+    def self.write_skill(gem_name, version, skill_content)
+      File.write(skill_path(gem_name, version), skill_content)
+    end
+
+    # Merge additional keys into the existing metadata.json, preserving
+    # generated_at, model, sources, etc. Keys are normalized to strings so a
+    # symbol key never collides with its string twin.
+    def self.merge_metadata(gem_name, version, extra)
+      data = read_metadata(gem_name, version).merge(extra.transform_keys(&:to_s))
+      File.write(metadata_path(gem_name, version), JSON.generate(data))
+    end
+
     def self.versions(gem_name)
       dir = File.join(ROOT, gem_name)
       return [] unless Dir.exist?(dir)

data/lib/gem/skill/cli/bundle_command.rb

@@ -8,7 +8,8 @@ require "gem/skill"
 
 module Gem::Skill
   # Handles `bundle skill SUBCOMMAND` via Bundler's plugin API (plugins.rb).
-  # Project-aware: reads Gemfile.lock and manages .claude/skills/ symlinks.
+  # Project-aware: reads Gemfile.lock and manages project skill symlinks
+  # (directory set by GEMSKILL_PROJECT_DIR, default .claude/skills/).
   module BundlerCommand
     SUBCOMMANDS = %w[install refresh list].freeze
 
@@ -17,6 +18,11 @@ module Gem::Skill
       opts, rest = parse_options(args)
       subcmd = rest.shift
 
+      if opts[:version]
+        puts Gem::Skill::VERSION
+        return
+      end
+
       case subcmd
       when "install" then install(opts)
       when "refresh" then refresh(opts)
@@ -37,9 +43,11 @@ module Gem::Skill
         return
       end
 
-      force  = opts[:force]
-      model  = opts[:model] || Generator::DEFAULT_MODEL
-      errors = []
+      force   = opts[:force]
+      verify  = opts[:verify]
+      model   = opts[:model] || Generator::DEFAULT_MODEL
+      errors  = []
+      results = []
 
       multi = TTY::Spinner::Multi.new(
         "[:spinner] Installing skills (#{model})",
@@ -53,8 +61,9 @@ module Gem::Skill
           sp = multi.register("  [:spinner] :title")
           sp.update(title: "#{gem_name} #{version}")
           barrier.async do
-            err = install_one(gem_name, version, sp, force: force, model: model)
-            errors << "#{gem_name} #{version}: #{err}" if err
+            result = install_one(gem_name, version, sp, force: force, model: model, verify: verify)
+            results << result
+            errors << "#{gem_name} #{version}: #{result.error}" if result.error
           end
         end
         barrier.wait
@@ -64,14 +73,17 @@ module Gem::Skill
 
       Linker.prune_dead_links
       report_errors(errors)
+      report_verify(results, verify)
     end
 
     def self.refresh(opts = {})
       gems   = Lockfile.gems
-      linked = Linker.linked_gems.to_h { |e| [e[:gem_name], e[:version]] }
-      force  = opts[:force]
-      model  = opts[:model] || Generator::DEFAULT_MODEL
-      errors = []
+      linked  = Linker.linked_gems.to_h { |e| [e[:gem_name], e[:version]] }
+      force   = opts[:force]
+      verify  = opts[:verify]
+      model   = opts[:model] || Generator::DEFAULT_MODEL
+      errors  = []
+      results = []
 
       multi = TTY::Spinner::Multi.new(
         "[:spinner] Refreshing skills (#{model})",
@@ -85,14 +97,15 @@ module Gem::Skill
           sp = multi.register("  [:spinner] :title")
           sp.update(title: "#{gem_name} #{version}")
           barrier.async do
-            err = if !force && linked[gem_name] == version
+            result = if !force && linked[gem_name] == version
               sp.auto_spin
               sp.success("up to date")
-              nil
+              Runner::Result.success
             else
-              install_one(gem_name, version, sp, force: force, model: model)
+              install_one(gem_name, version, sp, force: force, model: model, verify: verify)
             end
-            errors << "#{gem_name} #{version}: #{err}" if err
+            results << result
+            errors << "#{gem_name} #{version}: #{result.error}" if result.error
           end
         end
         barrier.wait
@@ -102,6 +115,7 @@ module Gem::Skill
 
       Linker.prune_dead_links
       report_errors(errors)
+      report_verify(results, verify)
     end
 
     def self.list
@@ -115,7 +129,7 @@ module Gem::Skill
       ok     = entries.count { |e| e[:valid] }
       broken = entries.size - ok
 
-      puts "Skills linked in .claude/skills/  (#{ok} ok#{broken > 0 ? ", #{broken} broken" : ""}):"
+      puts "Skills linked in #{Linker.project_dir}/  (#{ok} ok#{broken > 0 ? ", #{broken} broken" : ""}):"
       puts ""
       entries.each do |e|
         status = e[:valid] ? "ok    " : "BROKEN"
@@ -125,9 +139,9 @@ module Gem::Skill
 
     # --- private ---
 
-    def self.install_one(gem_name, version, spinner, force:, model:)
+    def self.install_one(gem_name, version, spinner, force:, model:, verify: false)
       spinner.auto_spin
-      Runner.install_skill(gem_name, version, spinner, force: force, model: model)
+      Runner.install_skill(gem_name, version, spinner, force: force, model: model, verify: verify)
     end
     private_class_method :install_one
 
@@ -139,6 +153,20 @@ module Gem::Skill
     end
     private_class_method :report_errors
 
+    # When --verify applied fixes, report and exit non-zero so callers/CI can
+    # detect that the README-derived skill disagreed with the source.
+    def self.report_verify(results, verify)
+      return unless verify
+
+      fixed = results.count(&:verify_fixed)
+      return if fixed.zero?
+
+      warn ""
+      warn "Verify corrected #{fixed} skill(s) against gem source."
+      exit Gem::Skill::EXIT_VERIFY_FIXED
+    end
+    private_class_method :report_verify
+
     def self.parse_options(args)
       opts      = {}
       remaining = []
@@ -146,6 +174,8 @@ module Gem::Skill
       args.each do |arg|
         case arg
         when "--force"           then opts[:force] = true
+        when "--verify"          then opts[:verify] = true
+        when "--version", "-v"   then opts[:version] = true
         when /\A--model(?:=(.+))?\z/
           opts[:model] = $1 || args[args.index(arg) + 1]
         else
@@ -164,12 +194,17 @@ module Gem::Skill
 
         Subcommands:
           install   Generate and link skills for all gems in Gemfile.lock
-          refresh   Re-sync .claude/skills/ after bundle update
+          refresh   Re-sync the project skill directory after bundle update
           list      Show skills linked in this project
 
         Options:
           --force         Regenerate even if already cached
+          --verify        Verify generated skills against gem source and fix mismatches
           --model MODEL   LLM model to use (default: #{Generator::DEFAULT_MODEL})
+          --version, -v   Print gem-skill version and exit
+
+        Env:
+          GEMSKILL_PROJECT_DIR   Project dir for symlinks (default: .claude/skills)
       USAGE
     end
     private_class_method :usage

data/lib/gem/skill/cli/gem_command.rb

@@ -14,18 +14,21 @@ class Gem::Commands::SkillCommand < Gem::Command
     super "skill", "Manage Claude Code AI skills for Ruby gems"
 
     add_option("-f", "--force",         "Regenerate even if already cached") { |_, o| o[:force] = true }
+    add_option("--verify",              "Verify generated skill against gem source and fix mismatches (exit #{Gem::Skill::EXIT_VERIFY_FIXED} if fixes applied)") { |_, o| o[:verify] = true }
     add_option("-a", "--all",           "Purge all cached versions of a gem") { |_, o| o[:all] = true }
     add_option("-m", "--model MODEL",   "LLM model to use (default: #{Gem::Skill::Generator::DEFAULT_MODEL})") do |model, o|
       o[:model] = model
     end
+    add_option("-v", "--version",       "Print gem-skill version and exit") { |_, o| o[:version] = true }
   end
 
   def arguments
-    "SUBCOMMAND  one of: install, list, purge, setup"
+    "SUBCOMMAND  one of: install, verify, list, purge, setup"
   end
 
   def usage
     "#{program_name} install GEM_NAME [GEM_NAME ...]\n" \
+    "       #{program_name} verify GEM_NAME [GEM_NAME ...]\n" \
     "       #{program_name} list\n" \
     "       #{program_name} purge GEM_NAME VERSION\n" \
     "       #{program_name} purge GEM_NAME --all\n" \
@@ -35,6 +38,8 @@ class Gem::Commands::SkillCommand < Gem::Command
   def description
     <<~DESC
       install   Generate and cache a SKILL.md for a gem.
+      verify    Verify an already-cached skill against the gem's source and fix
+                mismatches (does not generate; errors if not cached).
       list      Show all skills in the global cache (~/.gem/skills).
       purge     Remove a specific cached version.
       setup     Register gem-skill as a Bundler plugin (run once after install).
@@ -44,10 +49,15 @@ class Gem::Commands::SkillCommand < Gem::Command
   end
 
   def execute
+    if options[:version]
+      say Gem::Skill::VERSION
+      return
+    end
     Gem::Skill.configure_llm!
     subcmd = options[:args].shift
     case subcmd
     when "install" then cmd_install
+    when "verify"  then cmd_verify
     when "list"    then cmd_list
     when "purge"   then cmd_purge
     when "setup"   then cmd_setup
@@ -70,8 +80,9 @@ class Gem::Commands::SkillCommand < Gem::Command
       return
     end
 
-    force = options[:force]
-    model = options[:model] || Gem::Skill::Generator::DEFAULT_MODEL
+    force  = options[:force]
+    verify = options[:verify]
+    model  = options[:model] || Gem::Skill::Generator::DEFAULT_MODEL
 
     multi = TTY::Spinner::Multi.new(
       "[:spinner] Generating skills (#{model})",
@@ -79,12 +90,13 @@ class Gem::Commands::SkillCommand < Gem::Command
       output: $stderr
     )
 
+    results = []
     Async do
       barrier = Async::Barrier.new
       gem_names.each do |gem_name|
         spinner = multi.register("  [:spinner] :title")
         spinner.update(title: gem_name)
-        barrier.async { install_one(gem_name, spinner: spinner, force: force, model: model) }
+        barrier.async { results << install_one(gem_name, spinner: spinner, force: force, model: model, verify: verify) }
       end
       barrier.wait
     ensure
@@ -92,9 +104,15 @@ class Gem::Commands::SkillCommand < Gem::Command
     end
 
     say "Tip: run 'bundle plugin install gem-skill' to enable 'bundle skill'."
+
+    fixed = results.count(&:verify_fixed)
+    if verify && fixed.positive?
+      say "Verify corrected #{fixed} skill(s) against gem source."
+      terminate_interaction Gem::Skill::EXIT_VERIFY_FIXED
+    end
   end
 
-  def install_one(gem_name, spinner:, force:, model:)
+  def install_one(gem_name, spinner:, force:, model:, verify: false)
     spinner.auto_spin
     version = resolve_installed_version(gem_name)
     if version.nil?
@@ -102,11 +120,77 @@ class Gem::Commands::SkillCommand < Gem::Command
       version = install_gem(gem_name)
     end
     spinner.update(title: "#{gem_name} #{version}")
-    err = Gem::Skill::Runner.install_skill(gem_name, version, spinner, force: force, model: model)
-    alert_error "#{gem_name}: #{err}" if err
+    result = Gem::Skill::Runner.install_skill(gem_name, version, spinner, force: force, model: model, verify: verify)
+    alert_error "#{gem_name}: #{result.error}" if result.error
+    result
+  rescue Gem::Skill::Error => e
+    spinner.error("failed")
+    alert_error "#{gem_name}: #{e.message}"
+    Gem::Skill::Runner::Result.failure(e.message)
+  end
+
+  def cmd_verify
+    gem_names = options[:args].dup
+    options[:args].clear
+
+    if gem_names.empty?
+      alert_error "gem_name required. Usage: gem skill verify GEM_NAME [GEM_NAME ...]"
+      return
+    end
+
+    model = options[:model] || Gem::Skill::Generator::DEFAULT_MODEL
+
+    multi = TTY::Spinner::Multi.new(
+      "[:spinner] Verifying skills (#{model})",
+      format: :dots,
+      output: $stderr
+    )
+
+    results = []
+    Async do
+      barrier = Async::Barrier.new
+      gem_names.each do |gem_name|
+        spinner = multi.register("  [:spinner] :title")
+        spinner.update(title: gem_name)
+        barrier.async { results << verify_one(gem_name, spinner: spinner, model: model) }
+      end
+      barrier.wait
+    ensure
+      barrier.stop
+    end
+
+    fixed = results.count(&:verify_fixed)
+    if fixed.positive?
+      say "Verify corrected #{fixed} skill(s) against gem source."
+      terminate_interaction Gem::Skill::EXIT_VERIFY_FIXED
+    end
+  end
+
+  # Verify an already-cached skill in place. Never generates: the gem must be
+  # installed (verification needs its source) and the skill must already be cached.
+  def verify_one(gem_name, spinner:, model:)
+    spinner.auto_spin
+    version = resolve_installed_version(gem_name)
+    if version.nil?
+      spinner.error("not installed")
+      alert_error "#{gem_name}: not installed locally; verification needs the gem's source. Run 'gem install #{gem_name}' first."
+      return Gem::Skill::Runner::Result.failure("not installed")
+    end
+
+    spinner.update(title: "#{gem_name} #{version}")
+    unless Gem::Skill::Cache.cached?(gem_name, version)
+      spinner.error("not cached")
+      alert_error "#{gem_name} #{version}: no cached skill to verify. Run 'gem skill install #{gem_name}' first."
+      return Gem::Skill::Runner::Result.failure("not cached")
+    end
+
+    result = Gem::Skill::Runner.install_skill(gem_name, version, spinner, force: false, model: model, verify: true)
+    alert_error "#{gem_name}: #{result.error}" if result.error
+    result
   rescue Gem::Skill::Error => e
     spinner.error("failed")
     alert_error "#{gem_name}: #{e.message}"
+    Gem::Skill::Runner::Result.failure(e.message)
   end
 
   def cmd_list
@@ -121,13 +205,54 @@ class Gem::Commands::SkillCommand < Gem::Command
     say ""
     gems.each do |name|
       versions = Gem::Skill::Cache.versions(name)
-      say "  %-30s %s" % [name, versions.join(", ")]
+      rendered = versions.map { |v| format_version(name, v) }.join(", ")
+      say "  %-30s %s" % [name, rendered]
     end
     say ""
     say "#{gems.size} gem(s), #{gems.sum { |n| Gem::Skill::Cache.versions(n).size }} version(s) total."
   end
 
+  CHECK_MARK = "✓" # ✓
+
+  # True when the cached skill for this gem/version was verified against source.
+  def skill_verified?(gem_name, version)
+    Gem::Skill::Cache.read_metadata(gem_name, version).dig("verification", "verified") == true
+  end
+
+  # A version label, with a green checkmark appended when the skill is verified.
+  def format_version(gem_name, version)
+    return version unless skill_verified?(gem_name, version)
+
+    "#{version} #{colorize_check}"
+  end
+
+  # The checkmark, ANSI-green only when writing to an interactive terminal so
+  # redirected/piped output stays clean.
+  def colorize_check
+    $stdout.tty? ? "\e[32m#{CHECK_MARK}\e[0m" : CHECK_MARK
+  end
+
+  # Default skill roots that assistants scan automatically. The router skill is
+  # copied into each one whose assistant home directory already exists.
+  ASSISTANT_SKILL_ROOTS = {
+    "Claude Code" => "~/.claude/skills",
+    "OpenAI Codex" => "~/.codex/skills",
+    "Agents (vendor-neutral)" => "~/.agents/skills"
+  }.freeze
+
   def cmd_setup
+    register_bundler_plugin
+    say ""
+    install_router_skill
+  end
+
+  def register_bundler_plugin
+    plugin_list = `bundle plugin list 2>/dev/null`
+    if plugin_list.include?("gem-skill")
+      say "gem-skill is already registered as a Bundler plugin."
+      return
+    end
+
     say "Registering gem-skill as a Bundler plugin..."
     if system("bundle", "plugin", "install", "gem-skill")
       say "Done. Use 'bundle skill install' in any project."
@@ -136,6 +261,36 @@ class Gem::Commands::SkillCommand < Gem::Command
     end
   end
 
+  # Copy the bundled '#{Gem::Skill::ROUTER_SKILL_NAME}' skill into the default
+  # skill root of each detected assistant, so it can discover cached gem skills.
+  def install_router_skill
+    source = File.join(Gem::Skill::ROUTER_SKILL_DIR, "SKILL.md")
+    unless File.exist?(source)
+      alert_error "Router skill not found at #{source}"
+      return
+    end
+
+    say "Installing the '#{Gem::Skill::ROUTER_SKILL_NAME}' skill so assistants can find cached gem skills:"
+    installed = 0
+    ASSISTANT_SKILL_ROOTS.each do |label, root|
+      base = File.expand_path(root)
+      unless Dir.exist?(File.dirname(base))
+        say "  - #{label}: not detected — skipped"
+        next
+      end
+
+      dest_dir = File.join(base, Gem::Skill::ROUTER_SKILL_NAME)
+      FileUtils.mkdir_p(dest_dir)
+      FileUtils.cp(source, File.join(dest_dir, "SKILL.md"))
+      say "  - #{label}: installed -> #{dest_dir.sub(Dir.home, '~')}"
+      installed += 1
+    end
+
+    return unless installed.zero?
+
+    say "  No assistant directories detected. Create ~/.claude or ~/.codex, then re-run 'gem skill setup'."
+  end
+
   def cmd_purge
     gem_name = options[:args].shift
     unless gem_name

data/lib/gem/skill/fetcher.rb

@@ -19,6 +19,10 @@ module Gem::Skill
     README_CANDIDATES    = %w[README.md README.rdoc README.txt README].freeze
     CHANGELOG_CANDIDATES = %w[CHANGELOG.md CHANGELOG.rdoc HISTORY.md CHANGES.md].freeze
 
+    # Cap on concatenated source size handed to the verifier, to protect the
+    # context window on large gems. Files are added whole until the cap is hit.
+    SOURCE_MAX_CHARS = 150_000
+
     attr_reader :gem_name, :version
 
     def initialize(gem_name, version)
@@ -52,8 +56,56 @@ module Gem::Skill
       @examples ||= local_examples
     end
 
+    # The gem's actual Ruby source (lib/**/*.rb), concatenated with per-file
+    # headers. This is the ground truth the verifier checks the skill against.
+    # Returns nil when the gem isn't installed locally or has no lib sources —
+    # verification is only possible against installed source.
+    def source_code
+      source_bundle&.fetch(:code)
+    end
+
     private
 
+    def source_bundle
+      return @source_bundle if defined?(@source_bundle)
+
+      @source_bundle = build_source_bundle
+    end
+
+    def build_source_bundle
+      dir = gem_dir
+      return nil unless dir
+
+      lib = File.join(dir, "lib")
+      return nil unless File.directory?(lib)
+
+      files = Dir.glob(File.join(lib, "**", "*.rb")).sort
+      return nil if files.empty?
+
+      out       = +""
+      included  = []
+      truncated = false
+
+      files.each do |path|
+        relative = path.delete_prefix("#{dir}/")
+        body     = File.read(path, encoding: "utf-8")
+        chunk    = "### #{relative}\n\n```ruby\n#{body}\n```\n\n"
+        if !out.empty? && out.length + chunk.length > SOURCE_MAX_CHARS
+          truncated = true
+          break
+        end
+
+        out << chunk
+        included << relative
+      end
+
+      return nil if out.empty?
+
+      { code: out, files: included, chars: out.length, truncated: truncated }
+    rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+      nil
+    end
+
     # --- local gem spec ---
 
     def gem_spec