fix(rails): load create_agent.rb explicitly instead of autoloading the whole lib/

[bexchauveto]

Problem

A customer migrating to forest_admin_rails reported that the gem breaks their boot: their entire lib/ directory ends up managed by Zeitwerk autoloading, conflicting with their explicit loading strategy (explicit require/include).

Root cause: the engine added the host app's whole lib/ directory to Zeitwerk autoload_paths, via this initializer:

initializer 'forest_admin_rails.add_autoload_paths', before: :set_autoload_paths do |app|
  lib_path = Rails.root.join('lib')
  app.config.autoload_paths << lib_path unless app.config.autoload_paths.frozen?
end

The only reason this existed was to resolve the constant ForestAdminRails::CreateAgent from the host's lib/forest_admin_rails/create_agent.rb. But since Rails 6, lib/ is intentionally kept out of autoload_paths precisely because it often contains files that aren't Zeitwerk-compatible or are loaded explicitly. Forcing the host's entire lib/ into autoload is intrusive and is what breaks these apps.

Fix

• Remove the add_autoload_paths initializer.
• Load only the file we actually need, explicitly, during load_configuration — right after the existing create_agent_file_exists? guard:

require create_agent_path.to_s

Since lib/ is no longer in autoload_paths, a plain require is safe (no Zeitwerk conflict), and the host's lib/ is left entirely under the app's own control. The path is centralized in a create_agent_path helper reused by create_agent_file_exists?.

Tests

Added to engine_spec.rb:

• Regression test: the engine no longer registers the forest_admin_rails.add_autoload_paths initializer.
• create_agent_path points to the expected location under Rails.root.
• create_agent_file_exists? (present / absent).
• load_configuration: skips when no web server / file absent; requires the host file explicitly then runs setup when both conditions hold.

All engine_spec.rb examples pass (28, 0 failures) and RuboCop is clean.

[bexchauveto]

✅ Manual verification on a real Rails app (forest-poc / gateway)

Tested against the gateway service of forest-poc, which loads forest_admin_rails from a local path — so it picks up this branch directly.

Note: the gateway opts into config.autoload_lib (the Rails 7.1+ default), so in its stock config lib/ is autoloaded by the app's own choice. To isolate Forest's behaviour and mirror the reporting customer (whose app does not autoload lib/), I temporarily disabled config.autoload_lib and inspected autoload_paths at boot:

Scenario (app does not opt into autoload_lib)	lib/ in autoload_paths	ForestAdminRails::CreateAgent loads
main (old code)	true → bug reproduced	—
this branch	false → fixed	true

Conclusions:

1. Bug reproduced on main: Forest forces the host's lib/ into autoload_paths even when the app never asked for it — exactly the customer's report.
2. Fix confirmed: the gem no longer touches the host's autoload_paths.
3. No regression: ForestAdminRails::CreateAgent still loads correctly via the explicit require.
4. The nominal case is unaffected: when the app does opt into autoload_lib, that keeps working — Forest just no longer makes that choice on the app's behalf.

[matthv]

LGTM