anyway_config 2.9.0 → 2.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 910bf1014d5b1b2a7952b2e6da131a341722998f3b891d096f4d5764006fac23
-  data.tar.gz: 6f9233771e022ccb6d3ea3d03ee2b15bee8e2e3d322aa3434cd5d08b8794cf14
+  metadata.gz: 5b4393c06a6078956ade1727f37879c8a38003806b59c8c5a7e9c330708a42fd
+  data.tar.gz: 98e3e7d9c0a50e2a18f98a917818ab4fa088314471102d6d6f9e67c08b059670
 SHA512:
-  metadata.gz: 11f0d4f61ebabda431abba36837438c767405a0432e2f8f8ae1d2460b35e8e14438b9ed2acb6cb9d2d1b6889111e61cfecdf7abed2e2d4bc40eccba416c1d6f5
-  data.tar.gz: 3bf99f8766ed1a38ea3d9b6f114bf59c694c492ecd0f635067b97750750c2afea3e4d3c476e4d7bfa70c6e02fb478e36f273a4b32613712c79e10dc7c9fed400
+  metadata.gz: c9a771b5fd116be880f4aa3271a5389c6023500452eb8ea98ff8cefc5452ad0f24e3eab97bc02d39daab5231a070e4441efed4a285331d64f7f329073bfbab38
+  data.tar.gz: 8af2c0fdc71913929d78ef07f84db3b440cfa0a324834958f3bce0b77dd90e5a9c6995a61c3ba5637008171f6e02d7c7a429f46470b2d5a15984bcc524698737

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## master
 
+## 2.9.0 (2026-10-21)
+
+- Add an agent skill (`skills/anyway-config`) with guidance on organizing configuration in Rails apps. ([@palkan][])
+
+  The skill follows the [skills.sh](https://www.skills.sh) layout and installs automatically with [Rails Hyperdrive](https://github.com/rails-hyperdrive/rails-hyperdrive).
+
 ## 2.9.0 (2026-10-20)
 
 - Add a new `enforce_config_schema` to warn or raise on unknown attributes. ([@palkan][])
@@ -24,6 +30,7 @@ config.anyway_config.enforce_config_schema = true
 - Guard against a missing `PATH` environment variable in `Anyway::Utils.which`. ([@SAY-5][])
 
 - Do not require optional loader dependencies to speed up loading. ([@ardecvz][])
+- Use `to_s` on values that support it during validation for required attributes.  This provides more consistent behaviour for the `:uri` coercer, which will otherwise produce a `#<URI::Generic >` rather than a validation failure. ([@phil-janeapp][])
 
 ## 2.8.0 (2026-06-24)
 

data/README.md

@@ -34,6 +34,7 @@ For version 1.x see the [1-4-stable branch](https://github.com/palkan/anyway_con
 
 - [Main concepts](#main-concepts)
 - [Installation](#installation)
+  - [Adding agent skills](#adding-agent-skills)
 - [Usage](#usage)
   - [Configuration classes](#configuration-classes)
   - [Dynamic configuration](#dynamic-configuration)
@@ -105,6 +106,18 @@ Or adding to your project:
 gem "anyway_config", "~> 2.0"
 ```
 
+### Adding agent skills
+
+The gem ships a skill for coding agents in `skills/anyway-config`. It guides an agent when it adds or changes configuration in a Rails app: where to put a config class, which source to use for a value, how to replace direct `ENV` reads, and how to test configs. It follows the [skills.sh](https://www.skills.sh) layout, so it works with any agent that reads `SKILL.md`.
+
+With [Rails Hyperdrive](https://github.com/rails-hyperdrive/rails-hyperdrive), the skill installs automatically: run `bin/rails hyperdrive:init` the first time, then `bin/rails hyperdrive:sync`.
+
+Without it, install the skill from the repository with the [skills.sh](https://www.skills.sh) CLI, or copy `skills/anyway-config` into your agent's skills directory:
+
+```sh
+npx skills add palkan/anyway_config
+```
+
 ### Supported Ruby versions
 
 - Ruby (MRI) >= 2.7.0

data/lib/.rbnext/3.0/anyway/config.rb

@@ -471,7 +471,7 @@ module Anyway # :nodoc:
 
       self.class.required_attributes.select do |name|
         val = values.dig(*name.to_s.split(".").map(&:to_sym))
-        val.nil? || (val.is_a?(String) && val.empty?)
+        val.nil? || (val.respond_to?(:to_s) && val.to_s.empty?)
       end.then do |missing|
         next if missing.empty?
         raise_validation_error "The following config parameters for `#{self.class.name}(config_name: #{self.class.config_name})` are missing or empty: #{missing.join(", ")}"

data/lib/.rbnext/3.1/anyway/config.rb

@@ -471,7 +471,7 @@ module Anyway # :nodoc:
 
       self.class.required_attributes.select do |name|
         val = values.dig(*name.to_s.split(".").map(&:to_sym))
-        val.nil? || (val.is_a?(String) && val.empty?)
+        val.nil? || (val.respond_to?(:to_s) && val.to_s.empty?)
       end.then do |missing|
         next if missing.empty?
         raise_validation_error "The following config parameters for `#{self.class.name}(config_name: #{self.class.config_name})` are missing or empty: #{missing.join(", ")}"

data/lib/.rbnext/3.2/anyway/config.rb

@@ -471,7 +471,7 @@ module Anyway # :nodoc:
 
       self.class.required_attributes.select do |name|
         val = values.dig(*name.to_s.split(".").map(&:to_sym))
-        val.nil? || (val.is_a?(String) && val.empty?)
+        val.nil? || (val.respond_to?(:to_s) && val.to_s.empty?)
       end.then do |missing|
         next if missing.empty?
         raise_validation_error "The following config parameters for `#{self.class.name}(config_name: #{self.class.config_name})` are missing or empty: #{missing.join(", ")}"

data/lib/.rbnext/3.4/anyway/config.rb

@@ -471,7 +471,7 @@ module Anyway # :nodoc:
 
       self.class.required_attributes.select do |name|
         val = values.dig(*name.to_s.split(".").map(&:to_sym))
-        val.nil? || (val.is_a?(String) && val.empty?)
+        val.nil? || (val.respond_to?(:to_s) && val.to_s.empty?)
       end.then do |missing|
         next if missing.empty?
         raise_validation_error "The following config parameters for `#{self.class.name}(config_name: #{self.class.config_name})` are missing or empty: #{missing.join(", ")}"

data/lib/anyway/config.rb

@@ -471,7 +471,7 @@ module Anyway # :nodoc:
 
       self.class.required_attributes.select do |name|
         val = values.dig(*name.to_s.split(".").map(&:to_sym))
-        val.nil? || (val.is_a?(String) && val.empty?)
+        val.nil? || (val.respond_to?(:to_s) && val.to_s.empty?)
       end.then do |missing|
         next if missing.empty?
         raise_validation_error "The following config parameters for `#{self.class.name}(config_name: #{self.class.config_name})` are missing or empty: #{missing.join(", ")}"

data/lib/anyway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Anyway # :nodoc:
-  VERSION = "2.9.0"
+  VERSION = "2.9.1"
 end

data/skills/anyway-config/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: anyway-config
+description: Add, organize, refactor and test application configuration in Rails apps with Anyway Config (`Anyway::Config`). Use when a change needs a new setting, secret, API key, token, URL, env variable, feature toggle or third-party integration credentials; when code reads `ENV[...]`, `Rails.application.credentials`, `config_for` or branches on `Rails.env.production?`; when the user asks where configuration should live or how to stub it in tests.
+---
+
+# Anyway Config: configuration in Rails apps
+
+A config class is the only code that knows where a value comes from.
+Application code depends on the config object. It never reads `ENV`,
+credentials or YAML directly, and it does not branch on `Rails.env`.
+
+This file is the decision procedure. Read these files for details:
+
+- `references/organizing.md`: class placement, sources, boot integration, examples.
+- `references/testing.md`: test the config class and the code that uses it.
+- `references/docs.md`: the full map of README sections (§10 has the short version). Read the README
+  (or the gem source, `bundle info anyway_config --path`) for the API. Do not guess it.
+
+## 1. Look at the project first
+
+1. Find the existing configs: `config/configs/`, `app/configs/`, and `*/config.rb` next to services.
+2. Read `ApplicationConfig`. Most apps make it a singleton (`AppConfig.host`).
+3. Read the `config.anyway_config.*` lines in `config/application.rb`.
+   Note `autoload_static_config_path`, `default_environmental_key` and `enforce_config_schema`.
+4. Read `.gitignore`. Check that `config/*.local.yml` and `config/credentials/local.*` are ignored.
+5. Follow the conventions that you find. This skill gives the defaults for a new project.
+
+If the gem is not set up yet, run `bin/rails g anyway:install`.
+
+## 2. Decide where the new value goes
+
+```
+Is the value a config parameter (it changes between deployments or environments)?
+├── no → a constant in the code. Stop.
+└── yes
+    ├── Is it infrastructure that Rails or a tool reads itself
+    │   (PORT, RAILS_MAX_THREADS, DATABASE_URL, RAILS_LOG_LEVEL)?
+    │   └── yes → keep it where the tool expects it (puma.rb, database.yml). Stop.
+    ├── Does an existing config class own this concern (same service, same subsystem)?
+    │   └── yes → add an attribute to that class. Go to §4.
+    └── no → create a new config class. Go to §3.
+```
+
+Group parameters by concern: one class per integration or subsystem
+(`StripeConfig`, `SMTPConfig`, `FlyDeploy::Config`).
+Do not make one class per parameter. Do not put everything into `AppConfig`.
+`AppConfig` holds app-wide values only: host, port, asset host, global toggles.
+
+## 3. Create a config class
+
+Choose the location:
+
+| The config is used… | Put it in | Notes |
+|---|---|---|
+| at boot (`config/application.rb`, initializers, routes, `puma.rb`), or app-wide | `config/configs/<name>_config.rb` | Static: not reloaded in development. |
+| by one module, service or pack only | next to that code, e.g. `app/services/fly_deploy/config.rb` | Set `config_name` explicitly. Not available before autoloading. |
+| at runtime only, and the project keeps such configs in `app/configs/` | `app/configs/<name>_config.rb` | Reloaded in development. |
+
+Generate a class with `bin/rails g anyway:config <name> param1 param2`.
+Add `--app` for `app/configs/`. For an in-place class, write it by hand:
+
+```ruby
+# app/services/fly_deploy/config.rb
+module FlyDeploy
+  class Config < ApplicationConfig
+    # Without it, the name is "flydeploy" (downcased, not underscored)
+    config_name :fly_deploy
+
+    attr_config :api_token, :org_slug,
+      rest_api_url: "https://api.machines.dev/v1",
+      region: "iad"
+
+    required :api_token, env: :production
+
+    def fake_api? = rest_api_url.include?("fake_fly")
+  end
+end
+```
+
+The config name sets all source keys: `config/fly_deploy.yml`,
+`credentials.fly_deploy`, and `FLY_DEPLOY_*` env variables.
+If a gem or tool already uses that name (for example, Litestream reads `LITESTREAM_*`),
+choose a different name: `config_name :litestream_rails`.
+
+## 4. Choose the source for each value
+
+| Value | Source |
+|---|---|
+| Non-secret default, same everywhere | `attr_config name: default` |
+| Non-secret value that differs per environment | `config/<name>.yml`, per-environment keys |
+| Fake value for development and test (stub API URL, test token) | `development:` / `test:` keys in `config/<name>.yml` |
+| Secret (API key, password, signing secret) | Rails credentials under `<name>:`, or ENV `<NAME>_<ATTR>` from the deployment platform |
+| Personal developer override | `config/<name>.local.yml` or `config/credentials/local.yml.enc` (git-ignored) |
+| Value that an operator changes without a deploy | ENV `<NAME>_<ATTR>` |
+
+Load priority, from low to high: attribute defaults → YAML (plus `.local.yml`) →
+credentials → ENV → explicit `Config.new(key: value)`.
+
+Do not write `<%= ENV["STRIPE_API_KEY"] %>` in YAML. The ENV loader already maps
+`STRIPE_API_KEY` to `StripeConfig#api_key`.
+
+## 5. Write the attributes
+
+- Give a default to each attribute that has a safe value. A `true`/`false` default adds a `?` predicate.
+- Mark mandatory values with `required`. Limit it with `env:` (`env: :production`,
+  `env: {except: %i[development test]}`) when development can run without the value.
+- Add `coerce_types` when ENV must produce an array (`{type: :string, array: true}`)
+  or must stay a string (`oauth_scope: :string`, a numeric-looking token).
+- Put logic on the config, not in callers:
+  - Presence predicate: `def configured? = api_key.present? && secret.present?`
+  - Derived value: `def asset_host = super || "#{ssl? ? "https" : "http"}://#{host}"`
+  - Adapter for a library: `def to_settings = {address:, port:, user_name: username}.compact`
+- Add a comment to an attribute when its purpose or format is not obvious.
+- Do not use reserved names (`values`, `to_h`, `clear`, `config_name`, …).
+  With the singleton `ApplicationConfig`, also avoid names of class methods (README, issue #120).
+- If the project type-checks with RBS (`sig/`, `Steepfile`), add a signature for the new config.
+  `MyConfig.to_rbs` generates it from `attr_config`, `coerce_types` and `required`.
+
+## 6. Use the config
+
+- Call the config from application code: `StripeConfig.secret_key`, `AppConfig.analytics_enabled?`.
+- Pass the config as a default argument when a class depends on it. Tests can then inject another one:
+  `def initialize(config: FlyDeploy::Config)`.
+- Turn integrations on by the presence of their settings, not by the environment:
+  `provider :github, ... if GithubConfig.oauth_configured?`.
+- Configure Rails and gems from configs in `config/application.rb` and initializers.
+  See `references/organizing.md` §4.
+- A gem that reads only `ENV`: copy the value once in its initializer,
+  `ENV["STRIPE_PRIVATE_KEY"] ||= StripeConfig.secret_key`.
+
+## 7. Replace direct reads
+
+| You see | Replace with |
+|---|---|
+| `ENV["FOO_API_KEY"]` in app code | `FooConfig.api_key` |
+| `ENV.fetch("FOO_ENABLED", "false") == "true"` | `attr_config enabled: false` → `FooConfig.enabled?` |
+| `Rails.application.credentials.foo[:key]` | `FooConfig.key` (same `foo:` credentials, no change in data) |
+| `Rails.application.config_for(:foo)` | `FooConfig` (same `config/foo.yml`) |
+| `if Rails.env.production?` to select a value | a per-environment YAML value |
+| `if Rails.env.production?` to turn a feature on | a boolean attribute or `configured?` predicate |
+| `ENV["X"] \|\| "default"` | `attr_config x: "default"` |
+
+Keep `Rails.env` checks that are about the framework itself (for example, test-only view helpers).
+
+## 8. Test
+
+Read `references/testing.md`. In short:
+
+- Put the test values in the `test:` section of `config/<name>.yml`. CI then needs no secrets.
+- Unit-test the config class with `described_class.new(key: value)` and `with_env`.
+- For code that uses a config, inject a config instance or stub the singleton method.
+- Do not set `ENV` directly in tests.
+
+## 9. Debug a wrong value
+
+When a config value is not what you expect, do not guess. Ask the config where the value came from:
+
+```sh
+bin/rails runner 'pp StripeConfig.new'
+```
+
+```
+#<StripeConfig
+  config_name="stripe"
+  env_prefix="STRIPE"
+  values:
+    currency => "eur" (type=env key=STRIPE_CURRENCY),
+    api_key => "sk_test_..." (type=credentials store=config/credentials/development.yml.enc),
+    webhook_secret => "whsec_..." (type=yml path=./config/stripe.yml)>
+```
+
+`StripeConfig.new.to_source_trace` returns the same data as a hash.
+Use `.new`: the singleton keeps the values it loaded when the process started.
+The output shows secrets in clear text. Do not copy it into commits, issues or reports.
+
+If the trace does not explain the value, check these in order:
+
+1. Priority: defaults → YAML (+ `.local.yml`) → credentials (+ local) → ENV → explicit values.
+   A higher source wins, so a stale ENV variable hides a YAML change.
+2. Names: `env_prefix` and `config_name` in the output. `FlyDeploy::Config` without
+   `config_name` reads `FLYDEPLOY_*` and `config/flydeploy.yml`.
+3. Environment: YAML with environment keys needs a section for the current `Rails.env`.
+   Local files load in development only.
+4. Typos: a misspelled key in YAML or credentials is ignored silently.
+   Turn on `enforce_config_schema` to raise on unknown keys.
+5. Types: ENV values are auto-cast (`"0123"` → `123`). The trace shows the raw string,
+   the reader returns the cast value. Fix with `coerce_types key: :string`.
+
+## 10. Gem features at a glance
+
+The README documents each feature. `references/docs.md` maps tasks to README sections.
+
+| Feature | Use it for |
+|---|---|
+| `attr_config`, `required`, `on_load`, `coerce_types` | Schema, validation, types |
+| Local files (`*.local.yml`, local credentials) | Personal development overrides |
+| `enforce_config_schema` (2.9+) | Raise or warn on unknown keys in YAML and credentials |
+| Source tracing (`pp`, `to_source_trace`) | Find where a value came from |
+| Generators (`anyway:install`, `anyway:config`) | New base class and config classes |
+| `with_env` test helper | Set ENV in a block, with the Anyway ENV cache reset |
+| Doppler, EJSON, custom loaders | More sources; ENV stays the last loader |
+| `Anyway::Config.for(:name)` | Read a config without a class (prefer a class) |
+| `to_rbs`, bundled signatures | Type-check configs with RBS and Steep |
+| OptionParser integration | Build CLI options from a config (plain Ruby tools) |
+
+## 11. Do not
+
+- Do not read `ENV` or credentials outside config classes, except for infrastructure (§2).
+- Do not commit secrets to `config/<name>.yml`. Development and test fakes are fine.
+- Do not add a config class for one value that another config already covers.
+- Do not mutate a config at runtime to change behavior. Pass a new instance instead.
+- Do not reference a config from `app/configs/` or an in-place class during boot.
+  Move it to `config/configs/`.
+- Do not add an env-specific `if` to a config method when a YAML value can express the difference.
+
+## 12. Report
+
+When you finish, list:
+
+- each config class you added or changed, and its location;
+- each new parameter with its source (YAML, credentials, ENV) and its ENV variable name;
+- the values that operators must set before a deployment (new required secrets);
+- the direct `ENV` / credentials / `Rails.env` reads that you removed.

data/skills/anyway-config/references/docs.md

@@ -0,0 +1,30 @@
+# Where to find the API
+
+The README is the API reference: https://github.com/palkan/anyway_config#readme.
+The installed copy is at `$(bundle info anyway_config --path)/README.md`.
+Read the section that you need. The source is in `lib/anyway/` of the same directory.
+
+| Task | README section |
+|---|---|
+| Declare attributes, defaults, boolean predicates, override readers with `super` | [Configuration classes](https://github.com/palkan/anyway_config#configuration-classes) |
+| Change the config name or the ENV prefix (`config_name`, `env_prefix`) | [Config name](https://github.com/palkan/anyway_config#config-name), [Customize env variable names prefix](https://github.com/palkan/anyway_config#customize-env-variable-names-prefix) |
+| Pass explicit values, reload a config | [Explicit values](https://github.com/palkan/anyway_config#explicit-values), [Reload configuration](https://github.com/palkan/anyway_config#reload-configuration) |
+| Load a config without a class (`Anyway::Config.for(:name)`) | [Dynamic configuration](https://github.com/palkan/anyway_config#dynamic-configuration) |
+| `required` (with `env:`), `on_load`, `raise_validation_error`, `ANYWAY_SUPPRESS_VALIDATIONS` | [Validation and callbacks](https://github.com/palkan/anyway_config#validation-and-callbacks) |
+| Detect typos in YAML and credentials (`enforce_config_schema`, `rescue_unknown_attributes_with`) | [Enforcing config schema](https://github.com/palkan/anyway_config#enforcing-config-schema) |
+| Source priority in Rails, YAML lookup path, `<NAME>_CONF`, credentials | [Data population](https://github.com/palkan/anyway_config#data-population) |
+| `default:` key, environment-free YAML, `known_environments` | [Multi-env configuration](https://github.com/palkan/anyway_config#multi-env-configuration) |
+| `config/configs` vs `app/configs`, static configs, inflections | [Organizing configs](https://github.com/palkan/anyway_config#organizing-configs) |
+| `anyway:install`, `anyway:config`, `anyway:app_config` generators | [Generators](https://github.com/palkan/anyway_config#generators) |
+| Use configs in `config/puma.rb` or before Rails loads | [Loading Anyway Config before Rails](https://github.com/palkan/anyway_config#loading-anyway-config-before-rails) |
+| Plain Ruby apps and gems | [Using with Ruby](https://github.com/palkan/anyway_config#using-with-ruby) |
+| ENV names, nested keys (`__`), auto-casting, arrays | [Environment variables](https://github.com/palkan/anyway_config#environment-variables) |
+| `coerce_types`, built-in types, custom deserializers, `disable_auto_cast!` | [Type coercion](https://github.com/palkan/anyway_config#type-coercion) |
+| `*.local.yml`, local credentials | [Local files](https://github.com/palkan/anyway_config#local-files) |
+| Doppler, EJSON, custom loaders, loader order | [Data loaders](https://github.com/palkan/anyway_config#data-loaders) |
+| Find where a value came from (`to_source_trace`, `pp config`) | [Tracing](https://github.com/palkan/anyway_config#tracing) |
+| Pattern matching on configs | [Pattern matching](https://github.com/palkan/anyway_config#pattern-matching) |
+| `with_env` and other test helpers | [Test helpers](https://github.com/palkan/anyway_config#test-helpers) |
+| Build a CLI from a config (`OptionParser`) | [OptionParser integration](https://github.com/palkan/anyway_config#optionparser-integration) |
+| RBS signatures for config classes | [RBS support](https://github.com/palkan/anyway_config#rbs-support) |
+

data/skills/anyway-config/references/organizing.md

@@ -0,0 +1,341 @@
+# Organizing configuration in a Rails app
+
+## Contents
+
+1. Layers
+2. File layout
+3. Base class and access
+4. Boot integration
+5. Sources in practice
+6. In-place config classes
+7. Shared config names
+8. Recommended settings
+
+## 1. Layers
+
+```
+Application code (models, services, controllers, initializers)
+        │ depends on
+        ▼
+Config classes (schema: names, defaults, types, validation, predicates)
+        │ loaded from
+        ▼
+Sources (YAML, credentials, ENV, Doppler, EJSON, custom loaders)
+```
+
+Sources are infrastructure. You can move a value from YAML to credentials to ENV,
+and the application code does not change.
+
+## 2. File layout
+
+```
+config/
+├── application.rb              # assigns configs to Rails.application.config
+├── configs/                    # static configs: available at boot
+│   ├── application_config.rb
+│   ├── app_config.rb
+│   ├── smtp_config.rb
+│   └── stripe_config.rb
+├── app.yml                     # non-secret values, per environment
+├── smtp.yml
+├── app.local.yml               # personal overrides (git-ignored)
+└── credentials/
+    ├── production.yml.enc      # secrets
+    ├── development.yml.enc
+    └── local.yml.enc           # personal secrets (git-ignored)
+app/services/fly_deploy/
+├── client.rb
+└── config.rb                   # in-place config: FlyDeploy::Config
+```
+
+`config/configs/` is the default value of `config.anyway_config.autoload_static_config_path`.
+Anyway Config autoloads it before the initializers run. Rails does not reload it in development.
+
+`app/configs/` is a normal autoload path. Its classes reload in development,
+but they are not available in `config/application.rb` or before the app finishes initialization.
+
+Set `autoload_static_config_path = "app/configs"` to keep all configs in `app/configs/`.
+
+### Custom inflections
+
+Static configs load before `config/initializers/inflections.rb`.
+If a class name needs an acronym (`SMTPConfig`), require the inflections first (README, issue #81):
+
+```ruby
+# config/application.rb
+require_relative "boot"
+require "rails/all"
+require_relative "initializers/inflections"
+```
+
+## 3. Base class and access
+
+The generator creates a singleton base class:
+
+```ruby
+class ApplicationConfig < Anyway::Config
+  class << self
+    delegate_missing_to :instance
+
+    private
+
+    def instance
+      @instance ||= new
+    end
+  end
+end
+```
+
+Callers write `StripeConfig.secret_key`. The instance loads once per process.
+
+- Use the class methods in application code.
+- Use `StripeConfig.new` when you need a fresh read (a script, a test, an initializer that must not
+  keep the singleton).
+- Use `StripeConfig.new(key: value)` to build a config with explicit values. Other sources do not
+  override explicit values.
+
+## 4. Boot integration
+
+Expose the configs that Rails itself needs on `Rails.application.config`.
+Then configure the framework from them in one place:
+
+```ruby
+# config/application.rb
+module MyApp
+  class Application < Rails::Application
+    config.app = AppConfig
+    config.mailer = MailerConfig
+    config.smtp = SMTPConfig
+
+    if config.app.host
+      config.action_controller.default_url_options =
+        config.action_mailer.default_url_options = {
+          host: config.app.host,
+          port: config.app.port,
+          protocol: config.app.ssl? ? "https" : "http"
+        }
+      config.action_controller.asset_host = config.app.asset_host
+    end
+
+    config.action_mailer.default_options = config.mailer.to_default_options
+
+    if config.smtp.configured?
+      config.action_mailer.delivery_method = :smtp
+      config.action_mailer.smtp_settings = config.smtp.to_settings
+    end
+  end
+end
+```
+
+The config class owns the shape (`to_settings`, `to_default_options`).
+`config/application.rb` only connects it to Rails.
+
+### Initializers
+
+Turn an integration on when its settings are present. Do not check the environment:
+
+```ruby
+# config/initializers/omniauth.rb
+Rails.application.config.middleware.use OmniAuth::Builder do
+  if GithubConfig.oauth_configured?
+    provider :github, GithubConfig.oauth_key, GithubConfig.oauth_secret,
+      scope: GithubConfig.oauth_scope
+  end
+end
+```
+
+```ruby
+# config/initializers/litestream.rb
+Rails.application.configure do
+  litestream = LitestreamConfig.new
+  next unless litestream.configured?
+
+  config.litestream.replica_bucket = litestream.bucket
+  config.litestream.replica_key_id = litestream.access_key_id
+  config.litestream.replica_access_key = litestream.secret_access_key
+end
+```
+
+### Gems that read only ENV
+
+Copy the value from the config once, in the gem's initializer:
+
+```ruby
+# config/initializers/pay.rb
+# Pay reads Stripe keys from ENV, but we keep them in StripeConfig
+ENV["STRIPE_PRIVATE_KEY"] ||= StripeConfig.secret_key
+```
+
+### Routes
+
+Configs can gate routes, too: `mount Litestream::Engine, at: "/litestream" if LitestreamConfig.configured?`.
+
+## 5. Sources in practice
+
+### YAML: non-secret values per environment
+
+```yaml
+# config/app.yml
+default: &default
+  host: localhost
+  port: 3000
+
+development:
+  <<: *default
+
+test:
+  <<: *default
+  port: 3002
+
+production:
+  host: example.com
+  port: 443
+```
+
+- With `config.anyway_config.default_environmental_key = "default"`, Anyway Config deep-merges
+  `default:` into each environment. Then you do not need YAML anchors.
+- With `config.anyway_config.future.use :unwrap_known_environments`, a file without environment keys
+  applies to all environments.
+- A section can be absent. For example, `smtp.yml` can define `production:` only.
+- Fake values for development and test belong here: a stub API URL, `api_token: "test-token"`.
+- A production section that omits a secret makes `required` fail fast if the secret is missing
+  from credentials and ENV.
+
+### Credentials: secrets
+
+```yaml
+# bin/rails credentials:edit --environment production
+stripe:
+  secret_key: sk_live_...
+  signing_secret: whsec_...
+smtp:
+  username: ...
+  password: ...
+```
+
+The top-level key is the config name. The `stripe:` keys map to `StripeConfig` attributes.
+
+### ENV: deployment-time values
+
+`STRIPE_SECRET_KEY` sets `StripeConfig#secret_key`. ENV has the highest priority
+of the standard sources, so an operator can override any value without a deploy.
+
+- Nested keys use a double underscore: `APP_SMTP__PORT` → `app.smtp["port"]`.
+- Values are auto-cast: `"true"` → `true`, `"42"` → `42`, `"a,b"` → `["a", "b"]`.
+  Use `coerce_types` to change or fix the type.
+
+### Local files: personal development overrides
+
+`config/app.local.yml` (no environment keys) and `config/credentials/local.yml.enc`
+load in development only. Use them for a personal token, a fork's repository name,
+or a real API in place of the fake one. They must be git-ignored.
+
+A local YAML file supports ERB. Use it to switch between a fake and a real service:
+
+```yaml
+# config/fly_deploy.local.yml
+<% if ENV["REAL_FLY"] %>
+rest_api_url: https://api.machines.dev/v1
+org_slug: my-org
+<% end %>
+```
+
+### Data that stays outside configs
+
+- Process and infrastructure settings: `PORT`, `RAILS_MAX_THREADS`, `WEB_CONCURRENCY`,
+  `DATABASE_URL`, `RAILS_LOG_LEVEL`. Rails, Puma and the database adapter read them directly.
+- Values that a third-party binary reads from its own ENV variables.
+
+## 6. In-place config classes
+
+Put a config next to the code that uses it when only one module needs it.
+This keeps a module (or a packwerk pack, or an engine) self-contained.
+
+```ruby
+# app/services/fly_deploy/client.rb
+module FlyDeploy
+  class Client
+    attr_reader :config
+
+    delegate :api_token, :rest_api_url, to: :config
+
+    def initialize(config = FlyDeploy::Config)
+      @config = config
+    end
+  end
+end
+```
+
+- Set `config_name` explicitly. For `FlyDeploy::Config`, the inferred name is `flydeploy`.
+- The class autoloads with the rest of `app/`. Do not use it in `config/application.rb` outside
+  a `config.after_initialize` or `server do` block.
+- If the module grows and boot code needs the config, move the class to `config/configs/`.
+
+A config can also be nested inside the model that uses it:
+
+```ruby
+class License::GithubAccess
+  class Config < ApplicationConfig
+    config_name :github
+
+    attr_config :token
+
+    def enabled? = token.present?
+  end
+
+  def initialize(repo:, config: Config)
+    @repo = repo
+    @config = config
+  end
+
+  def grant(user)
+    unless config.enabled?
+      Rails.logger.warn("GitHub access is not configured")
+      return
+    end
+
+    GithubClient.new(config.token).add_collaborator(@repo, user.github_login)
+  end
+end
+```
+
+## 7. Shared config names
+
+Two classes can read the same config name. In the example above, `License::GithubAccess::Config`
+and `GithubConfig` both read `config/github.yml`, `credentials.github` and `GITHUB_*`.
+Each class sees only its own attributes.
+
+With `enforce_config_schema` on, each class reports the other class's keys as unknown.
+Allow them with `rescue_unknown_attributes_with`:
+
+```ruby
+Anyway::Settings.rescue_unknown_attributes_with = ->(config, _key) do
+  config.config_name == "github"
+end
+```
+
+## 8. Recommended settings
+
+Put the settings at the top of the application class, before any config is referenced.
+Settings in `config/environments/*.rb` apply too late for configs that `application.rb` already loaded.
+
+```ruby
+# config/application.rb
+module MyApp
+  class Application < Rails::Application
+    # Deep-merge the `default:` section into each environment
+    config.anyway_config.default_environmental_key = "default"
+    # Pass all future features in a single `use` call: each call resets the list
+    config.anyway_config.future.use :unwrap_known_environments, :reject_unknown_overrides
+    # Raise on unknown keys in YAML and credentials (typos). Requires 2.9+. Use :warn to only log
+    config.anyway_config.enforce_config_schema = true
+    config.anyway_config.known_environments << "staging"
+
+    config.app = AppConfig
+    # ...
+  end
+end
+```
+
+Asset precompilation in CI or Docker runs without secrets. `required` validations skip
+automatically when `SECRET_KEY_BASE_DUMMY` is set. Otherwise, set `ANYWAY_SUPPRESS_VALIDATIONS=1`.

data/skills/anyway-config/references/testing.md

@@ -0,0 +1,139 @@
+# Testing configuration
+
+## Contents
+
+1. Test values live in YAML
+2. Test the config class
+3. Test code that uses a config
+4. ENV in tests
+5. CI and asset precompilation
+
+## 1. Test values live in YAML
+
+Put deterministic values in the `test:` section of `config/<name>.yml`:
+
+```yaml
+# config/fly_deploy.yml
+test:
+  rest_api_url: http://localhost:3002/fake_fly
+  api_token: test-token
+  org_slug: test-org
+```
+
+- The test suite then needs no secrets and no credentials key.
+- Integrations that use a `configured?` predicate stay off in test when their secrets are absent.
+- Use obviously fake values (`test-token`, `sk_test_fake`). Never copy real secrets.
+
+## 2. Test the config class
+
+Test the logic that you added: predicates, derived values, adapters, validations.
+Do not test that Anyway Config reads YAML.
+
+Build an instance with explicit values. Other sources do not override them:
+
+```ruby
+# spec/configs/smtp_config_spec.rb
+RSpec.describe SMTPConfig do
+  subject(:config) { described_class.new(address: "smtp.example.com", port: 587, username: "u") }
+
+  it { is_expected.to be_configured }
+
+  specify do
+    expect(config.to_settings).to include(address: "smtp.example.com", user_name: "u")
+  end
+
+  context "without address" do
+    subject(:config) { described_class.new(address: nil) }
+
+    it { is_expected.not_to be_configured }
+  end
+end
+```
+
+Check the ENV mapping and type coercion with `with_env`.
+The helper is included automatically for specs in `spec/configs/` or with `type: :config`:
+
+```ruby
+RSpec.describe AnycableProConfig, type: :config do
+  it "parses a comma-separated safelist" do
+    with_env("ANYCABLE_PRO_GITHUB_SAFELIST" => "alice,bob") do
+      expect(described_class.new.github_safelist).to eq(%w[alice bob])
+    end
+  end
+end
+```
+
+`with_env` sets the variables, clears the Anyway ENV cache and restores both after the block.
+Pass `nil` to delete a variable.
+Elsewhere, require `"anyway/testing/helpers"` and include `Anyway::Testing::Helpers`
+(this also works for Minitest).
+
+Check `required` validations:
+
+```ruby
+it "requires the magic link key" do
+  expect { described_class.new(magic_link_key: "") }
+    .to raise_error(Anyway::Config::ValidationError, /magic_link_key/)
+end
+```
+
+`required ..., env:` checks the environment once, when the class loads.
+A stub in a test cannot change it, so do not test environment-scoped `required` in unit tests.
+
+Check an environment-dependent default:
+
+```ruby
+it "enables analytics in production by default" do
+  allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new("production"))
+
+  expect(described_class.new(analytics_enabled: nil)).to be_analytics_enabled
+end
+```
+
+## 3. Test code that uses a config
+
+### Inject a config
+
+If the class takes the config as an argument, pass an instance with explicit values.
+This is the preferred way:
+
+```ruby
+let(:config) { FlyDeploy::Config.new(api_token: "t", rest_api_url: "http://fake") }
+let(:client) { FlyDeploy::Client.new(config) }
+```
+
+### Stub the singleton
+
+If the code calls the singleton (`AppConfig.cables_quota`), stub the class method.
+`delegate_missing_to` defines `respond_to_missing?`, so verified partial doubles accept the stub:
+
+```ruby
+before { allow(AppConfig).to receive(:analytics_enabled?).and_return(true) }
+```
+
+Read expected values from the config instead of hard-coding them:
+
+```ruby
+expect(account.cables_quota).to eq(AppConfig.cables_quota)
+```
+
+### Do not mutate the singleton
+
+Do not assign attributes on the shared instance (`AppConfig.cables_quota = 10`).
+The value leaks into other tests. Stub the method or inject an instance.
+
+## 4. ENV in tests
+
+- The singleton loads once per process. `with_env` does not change it.
+  Use `with_env` together with `described_class.new`, not with `AppConfig.some_value`.
+- Do not assign `ENV[...]` directly. Anyway Config caches parsed ENV,
+  and a missed restore leaks into other tests. Use `with_env`.
+- A gem that reads `ENV` itself (for example, Pay) is outside Anyway Config.
+  Set and restore its variable in an `around` hook.
+
+## 5. CI and asset precompilation
+
+- `bin/rails assets:precompile` with `SECRET_KEY_BASE_DUMMY=1` skips `required` validations.
+- In other jobs without secrets, set `ANYWAY_SUPPRESS_VALIDATIONS=1`.
+- Turn on `config.anyway_config.enforce_config_schema = true` so that the test suite
+  fails on a mistyped key in YAML or credentials.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: anyway_config
 version: !ruby/object:Gem::Version
-  version: 2.9.0
+  version: 2.9.1
 platform: ruby
 authors:
 - Vladimir Dementyev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-next-core
@@ -197,6 +197,10 @@ files:
 - lib/rails/commands/local_credentials/local_credentials_command.rb
 - sig/anyway_config.rbs
 - sig/manifest.yaml
+- skills/anyway-config/SKILL.md
+- skills/anyway-config/references/docs.md
+- skills/anyway-config/references/organizing.md
+- skills/anyway-config/references/testing.md
 homepage: http://github.com/palkan/anyway_config
 licenses:
 - MIT
@@ -207,6 +211,8 @@ metadata:
   homepage_uri: http://github.com/palkan/anyway_config
   source_code_uri: http://github.com/palkan/anyway_config
   funding_uri: https://github.com/sponsors/palkan
+  hyperdrive_targets: railties
+  hyperdrive_artifacts: skill
 post_install_message:
 rdoc_options: []
 require_paths: