Say where the gem list comes from when rbs collection init runs

Ask a coding agent to set up RBS and Steep in a project and it usually
writes a Steepfile that lists every dependency with `library`, one gem per
line. `rbs collection` exists so that nobody has to maintain that list: it
reads `Gemfile.lock`, and `rbs` and Steep load the installed RBS files on
their own. Agents rarely find it, and the tools we ship are part of why.

`rbs collection init` printed one line, `created: rbs_collection.yaml`. It
named neither the next command nor the fact that would stop someone from
enumerating gems. The generated `rbs_collection.yaml` had the same gap: its
comments explained `sources`, `path` and `gems[].ignore` -- the knobs --
but never said the gem list is read from `Gemfile.lock`. The file is read
right after it is written, so it is a good place to say so.

- `init` now prints what the command does, that gems in `Gemfile.lock` need
  no listing anywhere, and the next steps: `.gitignore` and
  `rbs collection install`. `rbs_collection.lock.yaml` is what pins the RBS
  revisions -- the source is `revision: main` -- so the output says to keep
  it in version control.
- The generated config opens with the same two facts.
- Its commented-out `gems:` example showed only `ignore: true`. The other
  half -- adding an entry for a library that `Gemfile.lock` doesn't carry --
  was documented only in `docs/collection.md`. `socket` is the example: it
  is a non-gem standard library (`NONGEM_STDLIBS`), unlike `pathname`, whose
  types moved to `core/pathname.rbs` in 8066053, and unlike `csv`, which is
  in `ALUMNI_STDLIBS` and warns when installed.
- `docs/collection.md` gets a quickstart, so readers who see only the first
  screen get the two commands. Its `cat rbs_collection.yaml` had drifted
  from the generated file (no `type: git`, no local source comment) and now
  matches it byte for byte. The `.gitignore` paragraph right below the
  `init` output is gone, since that output now says it.

Ref: #3093

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BXtMkmp27LieHgSjNyEWZ8

Author: pocke

docs/collection.md

@@ -2,6 +2,17 @@
 
 `rbs collection` sub command manages third party gems' RBS. In short, it is `bundler` for RBS.
 
+## Quickstart
+
+In a project that has a `Gemfile.lock`:
+
+```console
+$ rbs collection init
+$ rbs collection install
+```
+
+`rbs collection` reads `Gemfile.lock`, so there is no list of dependencies to maintain. `rbs` and type checkers such as Steep load the installed RBS files automatically.
+
 ## Requirements
 
 * `git(1)`
@@ -17,33 +28,44 @@ First, generate the configuration file, `rbs_collection.yaml`, with `rbs collect
 $ rbs collection init
 created: rbs_collection.yaml
 
+rbs collection installs RBS files for the gems in your Gemfile.lock.
+Gems in Gemfile.lock don't need to be listed anywhere.
+
+Next steps:
+  $ echo "/.gem_rbs_collection/" >> .gitignore
+  $ rbs collection install    # writes rbs_collection.lock.yaml; keep it in version control
+
 $ cat rbs_collection.yaml
+# rbs collection installs RBS files for the gems in your Gemfile.lock.
+# Run `rbs collection install` to resolve them into rbs_collection.lock.yaml and install them.
+
 # Download sources
 sources:
-  - name: ruby/gem_rbs_collection
+  - type: git
+    name: ruby/gem_rbs_collection
     remote: https://github.com/ruby/gem_rbs_collection.git
     revision: main
     repo_dir: gems
 
+# You can specify local directories as sources also.
+# - type: local
+#   path: path/to/your/local/repository
+
 # A directory to install the downloaded RBSs
 path: .gem_rbs_collection
 
 # gems:
+#   # RBS for a library that doesn't appear in Gemfile.lock, such as a non-gem standard library.
+#   - name: socket
+#
 #   # If you want to avoid installing rbs files for gems, you can specify them here.
 #   - name: GEM_NAME
 #     ignore: true
 ```
 
-I also recommend updating `.gitignore`.
-
-```console
-$ echo /.gem_rbs_collection/ >> .gitignore
-```
-
 ### Install dependencies
 
 Then, install gems' RBS with `rbs collection install`! It copies RBS from [the gem RBS repository](https://github.com/ruby/gem_rbs_collection) to `.gem_rbs_collection/` directory by default.
-I recommend to ignore `.gem_rbs_collection/` from version control system, such as Git.
 
 ```console
 $ rbs collection install
@@ -86,9 +108,9 @@ sources:
 path: .gem_rbs_collection
 
 gems:
-  # If the Gemfile.lock doesn't contain csv gem but you use csv gem,
-  # you can write the gem name explicitly to install RBS of the gem.
-  - name: csv
+  # If the Gemfile.lock doesn't contain socket but you use it,
+  # you can write the library name explicitly to install RBS of the library.
+  - name: socket
 
   # If the Gemfile.lock contains nokogiri gem but you don't want to use the RBS,
   # you can ignore the gem.

lib/rbs/cli.rb

@@ -1104,6 +1104,9 @@ def run_collection(args, options)
         end
 
         config_path.write(<<~'YAML')
+          # rbs collection installs RBS files for the gems in your Gemfile.lock.
+          # Run `rbs collection install` to resolve them into rbs_collection.lock.yaml and install them.
+
           # Download sources
           sources:
             - type: git
@@ -1120,11 +1123,23 @@ def run_collection(args, options)
           path: .gem_rbs_collection
 
           # gems:
+          #   # RBS for a library that doesn't appear in Gemfile.lock, such as a non-gem standard library.
+          #   - name: socket
+          #
           #   # If you want to avoid installing rbs files for gems, you can specify them here.
           #   - name: GEM_NAME
           #     ignore: true
         YAML
-        stdout.puts "created: #{config_path}"
+        stdout.puts <<~MESSAGE
+          created: #{config_path}
+
+          rbs collection installs RBS files for the gems in your Gemfile.lock.
+          Gems in Gemfile.lock don't need to be listed anywhere.
+
+          Next steps:
+            $ echo "/.gem_rbs_collection/" >> .gitignore
+            $ rbs collection install    # writes rbs_collection.lock.yaml; keep it in version control
+        MESSAGE
       when 'clean'
         unless lock_path.exist?
           puts "#{lock_path} should exist to clean"

test/rbs/cli_test.rb

@@ -1082,6 +1082,30 @@ def foo: () -> void
     end
   end
 
+  def test_collection_init
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        with_cli do |cli|
+          assert_cli_success do
+            cli.run(%w(collection init))
+          end
+
+          config = Pathname(dir).join(RBS::Collection::Config::PATH).read
+          assert_match(/gems in your Gemfile\.lock/, config)
+          assert_match(/rbs collection install/, config)
+
+          yaml = YAML.load(config)
+          assert_equal ".gem_rbs_collection", yaml["path"]
+          assert_equal ["ruby/gem_rbs_collection"], yaml["sources"].map {|source| source["name"] }
+
+          assert_match(/created: .*rbs_collection\.yaml/, stdout.string)
+          assert_match(/gems in your Gemfile\.lock/, stdout.string)
+          assert_match(/\$ rbs collection install/, stdout.string)
+        end
+      end
+    end
+  end
+
   def test_collection_install
     omit_on_jruby! "`rbs collection install` runs `bundle install`, which builds native gem extensions that do not compile on JRuby"