pricing_plans 0.1.0

data/docs/03-model-helpers.md

@@ -0,0 +1,318 @@
+# Model helpers and methods
+
+## Define your `PlanOwner` class
+
+Your `PlanOwner` class is the class on which plan limits are enforced.
+
+It's usually the same class that gets charged for a subscription, the class that gets billed, the class that "owns" the plan, the class with the `pay_customer` if you're using Pay, etc. It's usually: `User`, `Organization`, `Team`, etc.
+
+To define your `PlanOwner` class, just add the model mixin:
+
+```ruby
+class User < ApplicationRecord
+  include PricingPlans::PlanOwner
+end
+```
+
+By adding the `PricingPlans::PlanOwner` mixin to a model, you automatically get all the features described below.
+
+## Link plan limits to your `PlanOwner` model
+
+Now you can link any `has_many` relationships in this model to `limits` defined in your `pricing_plans.rb`
+
+For example, if you defined a `:projects` limit like this:
+
+```ruby
+plan :pro do
+  limits :projects, to: 5
+end
+```
+
+Then you can link the `:projects` limit to any `has_many` relationship on the `PlanOwner` model (`User`, in this example):
+
+```ruby
+class User < ApplicationRecord
+  include PricingPlans::PlanOwner
+
+  has_many :projects, limited_by_pricing_plans: true
+end
+```
+
+The `:limited_by_pricing_plans` part infers that the association name (`:projects`) is the same as the limit key you defined on `pricing_plans.rb`. If that's not the case, you can make the association explicit:
+
+```ruby
+class User < ApplicationRecord
+  include PricingPlans::PlanOwner
+
+  has_many :custom_projects, limited_by_pricing_plans: { limit_key: :projects }
+end
+```
+
+In general, you can omit the limit key when it can be inferred from the model (e.g., `Project` → `:projects`).
+
+`limited_by_pricing_plans` plays nicely with every other ActiveRecord validation you may have in your relationship:
+
+```ruby
+class User < ApplicationRecord
+  include PricingPlans::PlanOwner
+
+  has_many :projects, limited_by_pricing_plans: true, dependent: :destroy
+end
+```
+
+You can also customize the validation error message by passing `error_after_limit`. This error message behaves like other ActiveRecord validation, and will get attached to the record upon failed creation:
+
+```ruby
+class User < ApplicationRecord
+  include PricingPlans::PlanOwner
+
+  has_many :projects, limited_by_pricing_plans: { error_after_limit: "Too many projects!" }, dependent: :destroy
+end
+```
+
+
+## Enforce limits in your `PlanOwner` class
+
+The `PlanOwner` class (the class to which you add the `include PricingPlans::PlanOwner` mixin) automatically gains these helpers to check limits:
+
+```ruby
+# Check limits for a relationship
+user.plan_limit_remaining(:projects)         # => integer or :unlimited
+user.plan_limit_percent_used(:projects)      # => Float percent
+user.within_plan_limits?(:projects, by: 1)   # => true/false
+
+# Grace helpers
+user.grace_active_for?(:projects)            # => true/false
+user.grace_ends_at_for(:projects)            # => Time or nil
+user.grace_remaining_seconds_for(:projects)  # => Integer seconds
+user.grace_remaining_days_for(:projects)     # => Integer days (ceil)
+user.plan_blocked_for?(:projects)            # => true/false (considering after_limit policy)
+```
+
+We also add syntactic sugar methods. For example, if your plan defines a limit for `:projects` and you have a `has_many :projects` relationship, you also get these methods:
+
+```ruby
+# Check limits (per `limits` key)
+user.projects_remaining
+user.projects_percent_used
+user.projects_within_plan_limits?
+
+# Grace helpers (per `limits` key)
+user.projects_grace_active?
+user.projects_grace_ends_at
+user.projects_blocked?
+```
+
+These methods are dynamically generated for every `has_many :<limit_key>`, like this:
+- `<limit_key>_remaining`
+- `<limit_key>_percent_used`
+- `<limit_key>_within_plan_limits?` (optionally: `<limit_key>_within_plan_limits?(by: 1)`)
+- `<limit_key>_grace_active?`
+- `<limit_key>_grace_ends_at`
+- `<limit_key>_blocked?`
+
+If you want to get an aggregate of graces across multiple keys instead of checking them individually:
+```ruby
+# Aggregates across keys
+user.any_grace_active_for?(:products, :activations)
+user.earliest_grace_ends_at_for(:products, :activations)
+```
+
+## Gate features in your `PlanOwner` class
+
+You can also check for feature flags like this:
+
+```ruby
+user.plan_allows?(:api_access)               # => true/false
+```
+
+Of course, there's also dynamic syntactic sugar of the form `plan_allows_<feature_key>?`, like this:
+
+```ruby
+user.plan_allows_api_access?
+```
+
+## Usage and limits status
+
+Checking the current usage with respect to plan limits comes in handy, especially when [building views](/docs/04-views.md). The following methods are useful to build warning / alert snippets, upgrade prompts, usage trackers, etc.
+
+### `limit`: Check a single limit
+
+You can check the status of a single limit with `user.limit(:projects)`
+
+This always returns a single `StatusItem`, which represents one status item for a limit. For example, output for `user.limit(:projects)`:
+
+```ruby
+#<struct
+  key=:projects,
+  human_key="projects",
+  current=1,
+  allowed=1,
+  percent_used=100.0,
+  grace_active=false,
+  grace_ends_at=nil,
+  blocked=true,
+  per=false,
+  severity=:at_limit,
+  severity_level=2,
+  message="You’ve reached your limit for projects (1/1). Upgrade your plan to unlock more.",
+  overage=0,
+  configured=true,
+  unlimited=false,
+  remaining=0,
+  after_limit=:block_usage,
+  :attention?=true,
+  :next_creation_blocked?=true,
+  warn_thresholds=[0.6, 0.8, 0.95],
+  next_warn_percent=nil,
+  period_start=nil,
+  period_end=nil,
+  period_seconds_remaining=nil
+>
+```
+
+#### The `StatusItem` object
+
+As you can see, the `StatusItem` object returns a bunch of useful information for that limit. Something that may have caught your attention is `severity` and `severity_level`. For each limit, `pricing_plans` computes severity, to help you better organize and display warning messages / alerts to your users.
+
+Severity order: `:blocked` > `:grace` > `:at_limit` > `:warning` > `:ok`
+
+Their corresponding `severity_level` are: `4`, `3`, `2`, `1`, `0`; respectively.
+
+Each severity comes with a default **title**:
+  - `blocked`: "Cannot create more resources"
+  - `grace`: "Limit Exceeded (Grace Active)"
+  - `at_limit`: "At Limit"
+  - `warning`: "Approaching Limit"
+  - `ok`: `nil`
+  
+Each severity Messages come from your `config.message_builder` in [`pricing_plans.rb`](/docs/01-define-pricing-plans.md) when present; otherwise we provide sensible defaults:
+  - `blocked`: "Cannot create more <key> on your current plan."
+  - `grace`: "Over the <key> limit, grace active until <date>."
+  - `at_limit`: "You are at <current>/<limit> <key>. The next will exceed your plan."
+  - `warning`: "You have used <current>/<limit> <key>."
+  - `ok`: `nil`
+
+### `limits`: Get the status of all limits
+
+You can call `user.limits` (plural, no arguments) to get the current status of all limits. You will get an array of `StatusItem` objects, with the same keys as described above.
+
+Sample output:
+
+```ruby
+user.limits
+
+# => [
+#  #<struct key=:limit_1...>,
+#  #<struct key=:limit_2...>,
+#  #<struct key=:limit_3...>
+# ]
+```
+
+Of course, prefer `user.limit(:key)` (singular, one argument) when you only need a the status of a single limit.
+
+You can also filter which limits you get status items for, by passing their limits keys as arguments:
+
+```ruby
+user.limits(:projects, :posts)
+```
+
+
+### `limits_overview`: Get a summary of all limits
+
+`limits_overview` is a thin wrapper around `limits` that, on top of returning the array of `StatusItem` objects, returns you a few "overall helpers" that can help you let the user know the overall status of their plan usage in a single view.
+
+`limits_overview` returns a JSON containing:
+  - `severity`: highest severity out of all limits
+  - `severity_level` corresponding severity level
+  - `title`: overall severity title
+  - `message`: overall severity message
+  - `attention?`: whether overall limits require user attention or not
+  - `keys`: array of all computed limits keys
+  - `highest_keys`: array of limits keys with the highest severity
+  - `highest_limits`: array of `StatusItem`
+  - `keys_sentence`: limit keys requiring attention, in a readable sentence
+
+For example:
+
+```ruby
+user.limits_overview
+```
+
+Would output:
+
+```ruby
+{
+  severity: :at_limit,
+  severity_level: 2,
+  title: "At your plan limit",
+  message: "You have reached your plan limit for products.",
+  attention?: true,
+  keys: [:products, :licenses, :activations],
+  highest_keys: [:products],
+  highest_limits: [
+    #<struct key=:projects...>
+  ],
+  keys_sentence: "products",
+  noun: "plan limit",
+  has_have: "has",
+  cta_text: "View Plans",
+  cta_url: nil
+} 
+```
+
+Of course, you can also pass limit keys as arguments to filter the output, like: `user.limits_overview(:projects, :posts)`
+
+### Limits aggregates
+
+If you only want to get the overall severity of message of all keys, you can do:
+
+```ruby
+user.limits_severity(:projects, :posts)           # => :ok | :warning | :at_limit | :grace | :blocked
+user.limits_message(:projects, :posts)            # => String (combined human message string) or `nil`
+```
+
+Additional per-limit checks:
+
+```ruby
+user.limit_overage(:projects)                     # => Integer (0 if within)
+user.limit_alert(:projects)                       # => { visible?: true/false, severity:, title:, message:, overage:, cta_text:, cta_url: }
+```
+
+You also get these handy helpers:
+
+```ruby
+user.attention_required_for_limit?(:projects)     # => true | false` (alias for any of warning/grace/blocked)
+user.approaching_limit?(:projects, at: 0.9)       # => true | false` (uses highest `warn_at` if `at` omitted)
+```
+
+You can also use the top-level equivalents if you prefer: `PricingPlans.severity_for(user, :projects)` and friends.
+
+## Other helpers and methods
+
+### Check and override plans
+
+You can also check and override the current pricing plan for any user, which comes handy as an admin:
+```ruby
+user.current_pricing_plan                    # => PricingPlans::Plan
+user.assign_pricing_plan!(:pro)              # manual assignment override
+user.remove_pricing_plan!                    # remove manual override (fallback to default)
+```
+
+### Misc
+
+```ruby
+user.on_free_plan?                           # => true/false
+```
+
+### `pay` integration
+
+And finally, you get very thin convenient wrappers if you're using the `pay` gem:
+```ruby
+# Pay (Stripe) convenience (returns false/nil when Pay is absent)
+# Note: this is billing-facing state, distinct from our in-app
+# enforcement grace which is tracked per-limit.
+user.pay_subscription_active?                # => true/false
+user.pay_on_trial?                           # => true/false
+user.pay_on_grace_period?                    # => true/false
+```

data/docs/04-views.md

@@ -0,0 +1,121 @@
+# Views: pricing pages, paywalls, usage indicators, conditional UI
+
+Since `pricing_plans` is your single source of truth for pricing plans, you can query it at any time and get easy-to-display information to create views like pricing pages and paywalls very easily.
+
+`pricing_plans` is UI-agnostic, meaning we don't ship any UI components with the gem, but we provide you with all the data you need to build UI components easily. You fully control the HTML/CSS, while `pricing_plans` gives you clear, composable data.
+
+## Display all plans
+
+`PricingPlans.plans` returns an array of `PricingPlans::Plan` objects containing all your plans defined in `pricing_plans.rb`
+
+Each `PricingPlans::Plan` responds to:
+  - `plan.free?`
+  - `plan.highlighted?`
+  - `plan.popular?` (alias of `highlighted?`)
+  - `plan.name`
+  - `plan.description`
+  - `plan.bullets` → Array of strings
+  - `plan.price_label` → The `price` or `price_string` you've defined for the plan. If `stripe_price` is set and the Stripe gem is available, it auto-fetches the live price from Stripe. You can override or disable this.
+  - `plan.cta_text`
+  - `plan.cta_url`
+
+### Example: build a pricing page
+
+Building a pricing table is as easy as iterating over all `Plans` and displaying their info:
+
+```erb
+<% PricingPlans.plans.each do |plan| %>
+  <article class="card <%= 'is-current' if plan == current_user.current_pricing_plan %> <%= 'is-popular' if plan.highlighted? %>">
+    <h3><%= plan.name %></h3>
+    <p><%= plan.description %></p>
+    <ul>
+      <% plan.bullets.each do |b| %>
+        <li><%= b %></li>
+      <% end %>
+    </ul>
+    <div class="price"><%= plan.price_label %></div>
+    <% if (url = plan.cta_url) %>
+      <%= link_to plan.cta_text, url, class: 'btn' %>
+    <% else %>
+      <%= button_tag plan.cta_text, class: 'btn', disabled: true %>
+    <% end %>
+  </article>
+<% end %>
+```
+
+> [!TIP]
+> If you need more detail for the price (not just `price_label`, but also if it's monthly, yearly, etc.) check out the [Semantic Pricing API](/docs/05-semantic-pricing.md).
+
+
+![pricing_plans Ruby on Rails gem - pricing table features](/docs/images/pricing_plans_ruby_rails_gem_pricing_table.jpg)
+
+## Get the highlighted plan
+
+You get helpers to access the highlighted plan:
+  - `PricingPlans.highlighted_plan`
+  - `PricingPlans.highlighted_plan_key`
+
+
+## Get the next plan suggestion
+  - `PricingPlans.suggest_next_plan_for(plan_owner, keys: [:projects, ...])`
+
+
+## Conditional UI
+
+![pricing_plans Ruby gem - conditional UI](/docs/images/product_creation_blocked.jpg)
+
+We can leverage the [model methods and helpers](/docs/03-model-helpers.md) to build conditional UIs depending on pricing plan limits:
+
+### Example: disable buttons when outside plan limits
+
+You can gate object creation by enabling or disabling create buttons depending on limits usage:
+
+```erb
+<% if current_organization.within_plan_limits?(:projects) %>
+  <!-- Show enabled "create new project" button -->
+<% else %>
+  <!-- Disabled button + hint -->
+<% end %>
+```
+
+Tip: you could also use `plan_allows?(:api_access)` to build feature-gating UIs.
+
+### Example: block an entire element if not in plan
+
+```erb
+<% if current_organization.plan_blocked_for?(:projects) %>
+  <!-- Disabled UI; creation is blocked by the plan -->
+<% end %>
+```
+
+## Alerts and usage
+
+![pricing_plans Ruby on Rails gem - pricing plan upgrade prompt](/docs/images/pricing_plans_ruby_rails_gem_usage_alert_upgrade.jpg)
+
+### Example: display an alert for a limit
+
+```erb
+<% if current_organization.attention_required_for_limit?(:projects) %>
+  <%= render "shared/plan_limit_alert", plan_owner: current_organization, key: :projects %>
+<% end %>
+```
+
+### Example: plan usage summary
+
+```erb
+<% s = current_organization.limit(:projects) %>
+<div><%= s.key.to_s.humanize %>: <%= s.current %> / <%= s.allowed %> (<%= s.percent_used.round(1) %>%)</div>
+<% if s.blocked %>
+  <div class="notice notice--error">Creation blocked due to plan limits</div>
+<% elsif s.grace_active %>
+  <div class="notice notice--warning">Over limit — grace active until <%= s.grace_ends_at %></div>
+<% end %>
+```
+
+Tip: you could also use `plan_limit_remaining(:projects)` and `plan_limit_percent_used(:projects)` to show current usage.
+
+![pricing_plans Ruby on Rails gem - pricing plan usage meter](/docs/images/pricing_plans_ruby_rails_gem_usage_meter.jpg)
+
+## Message customization
+
+- You can override copy globally via `config.message_builder` in [`pricing_plans.rb`](/docs/01-define-pricing-plans.md), which is used across limit checks and features. Suggested signature: `(context:, **kwargs) -> string` with contexts `:over_limit`, `:grace`, `:feature_denied`, and `:overage_report`.

data/docs/05-semantic-pricing.md

@@ -0,0 +1,159 @@
+# Semantic pricing
+
+Building delightful pricing UIs usually needs structured price parts (currency, amount, interval) and both monthly/yearly data. `pricing_plans` ships a semantic, UI‑agnostic API so you don't have to parse price strings in your app.
+
+## Value object: `PricingPlans::PriceComponents`
+
+Structure returned by the helpers below:
+
+```ruby
+PricingPlans::PriceComponents = Struct.new(
+  :present?,                 # boolean: price is numeric?
+  :currency,                 # string currency symbol, e.g. "$", "€"
+  :amount,                   # string whole amount, e.g. "29"
+  :amount_cents,             # integer cents, e.g. 2900
+  :interval,                 # :month | :year
+  :label,                    # friendly label, e.g. "$29/mo" or "Contact"
+  :monthly_equivalent_cents, # integer; = amount for monthly, or yearly/12 rounded
+  keyword_init: true
+)
+```
+
+## Semantic pricing helpers
+
+```ruby
+plan.price_components(interval: :month)    # => PriceComponents
+plan.monthly_price_components              # sugar for :month
+plan.yearly_price_components               # sugar for :year
+
+plan.has_interval_prices?                  # true if configured/inferred
+plan.has_numeric_price?                    # true if numeric (price or stripe_price)
+
+plan.price_label_for(:month)               # "$29/mo" (uses PriceComponents)
+plan.price_label_for(:year)                # "$290/yr" or Stripe-derived
+
+plan.monthly_price_cents                   # integer or nil
+plan.yearly_price_cents                    # integer or nil
+plan.monthly_price_id                      # Stripe Price ID (when available)
+plan.yearly_price_id
+plan.currency_symbol                       # "$" or derived from Stripe
+```
+
+Notes:
+
+- If `stripe_price` is configured, we derive cents, currency, and interval from the Stripe Price (and cache it).
+- If `price 0` (free), we return components with `present? == true`, amount 0 and the configured default currency symbol.
+- If only `price_string` is set (e.g., "Contact us"), components return `present? == false`, `label == price_string`.
+
+## Pure-data view models
+
+- Per‑plan:
+
+```ruby
+plan.to_view_model
+# => {
+#   id:, key:, name:, description:, features:, highlighted:, default:, free:,
+#   currency:, monthly_price_cents:, yearly_price_cents:,
+#   monthly_price_id:, yearly_price_id:,
+#   price_label:, price_string:, limits: { ... }
+# }
+```
+
+- All plans (preserves `PricingPlans.plans` order):
+
+```ruby
+PricingPlans.view_models # => Array<Hash>
+```
+
+## UI helpers
+
+We include data‑only helpers into ActionView.
+
+```ruby
+pricing_plan_ui_data(plan)
+# => {
+#   monthly_price:, yearly_price:,
+#   monthly_price_cents:, yearly_price_cents:,
+#   monthly_price_id:, yearly_price_id:,
+#   free:, label:
+# }
+
+pricing_plan_cta(plan, plan_owner: nil, context: :marketing, current_plan: nil)
+# => { text:, url:, method: :get, disabled:, reason: }
+```
+
+`pricing_plan_cta` disables the button for the current plan (text: "Current Plan"). You can add a downgrade policy (see configuration) to surface `reason` in your UI.
+
+## Plan comparison ergonomics (for CTAs)
+
+```ruby
+plan.current_for?(current_plan)      # boolean
+plan.upgrade_from?(current_plan)     # boolean
+plan.downgrade_from?(current_plan)   # boolean
+plan.downgrade_blocked_reason(from: current_plan, plan_owner: org) # string | nil
+```
+
+## Stripe lookups and caching
+
+- We fetch Stripe Price objects when `stripe_price` is present.
+- Caching is supported via `config.price_cache` (defaults to `Rails.cache` when available).
+- TTL controlled by `config.price_cache_ttl` (default 10 minutes).
+
+Example initializer snippet:
+
+```ruby
+PricingPlans.configure do |config|
+  config.price_cache = Rails.cache
+  config.price_cache_ttl = 10.minutes
+end
+```
+
+## Configuration for pricing semantics
+
+```ruby
+PricingPlans.configure do |config|
+  # Currency symbol when Stripe is absent
+  config.default_currency_symbol = "$"
+
+  # Cache & TTL for Stripe Price lookups
+  config.price_cache = Rails.cache
+  config.price_cache_ttl = 10.minutes
+
+  # Optional hook to fully customize components
+  # Signature: ->(plan, interval) { PricingPlans::PriceComponents | nil }
+  config.price_components_resolver = ->(plan, interval) { nil }
+
+  # Optional free copy used by some data helpers
+  config.free_price_caption = "Forever free"
+
+  # Default UI interval for toggles
+  config.interval_default_for_ui = :month # or :year
+
+  # Downgrade policy used by CTA ergonomics
+  # Signature: ->(from:, to:, plan_owner:) { [allowed_boolean, reason_or_nil] }
+  config.downgrade_policy = ->(from:, to:, plan_owner:) { [true, nil] }
+end
+```
+
+## Stripe price labels in `plan.price_label`
+
+By default, if a plan has `stripe_price` configured and the `stripe` gem is present, we auto-fetch the Stripe Price and render a friendly label (e.g., `$29/mo`). This mirrors Pay’s use of Stripe Prices.
+
+
+To disable auto-fetching globally:
+
+```ruby
+PricingPlans.configure do |config|
+  config.auto_price_labels_from_processor = false
+end
+```
+
+To fully customize rendering (e.g., caching, locale):
+
+```ruby
+PricingPlans.configure do |config|
+  config.price_label_resolver = ->(plan) do
+    # Build and return a string like "$29/mo" based on your own logic
+  end
+end
+```

data/docs/06-gem-compatibility.md

@@ -0,0 +1,99 @@
+# Using `pricing_plans` with `pay` and/or `usage_credits`
+
+`pricing_plans` is designed to work seamlessly with other complementary popular gems like `pay` (to handle actual subscriptions and payments), and `usage_credits` (to handle credit-like spending and refills)
+
+These gems are related but not overlapping. They're complementary. The boundaries are clear: billing is handled in Pay; metering (ledger-like) in usage_credits.
+
+The integration with `pay` should be seamless and is documented throughout the entire docs; however, here's a brief note about using `usage_credits` alongside `pricing_plans`.
+
+## Using `pricing_plans` with the `usage_credits` gem
+
+In the SaaS world, pricing plans and usage credits are related in so far credits are usually a part of a pricing plan. A plan would give you, say, 100 credits a month along other features, and users would find that information usually documented in the pricing table itself.
+
+However, for the purposes of this gem, pricing plans and usage credits are two very distinct things.
+
+If you want to add credits to your app, you should install and configure the [usage_credits](https://github.com/rameerez/usage_credits) gem separately. In the `usage_credits` configuration, you should specify how many credits your users get with each subscription.
+
+### The difference between usage credits and per-period plan limits
+
+> [!WARNING]
+> Usage credits are not the same as per-period limits.
+
+**Usage credits behave like a currency**. Per-period limits are not a currency, and shouldn't be purchaseable.
+
+- **Usage credits** are like: "100 image-generation credits a month"
+- **Per-period limits** are like: "Create up to 3 new projects a month"
+
+Usage credits can be refilled (buy credit packs, your balance goes up), can be spent (your balance goes down). Per-period limits do not. If you intend to sell credit packs, or if the balance needs to go both up and down, you should implement usage credits, NOT per-period limits.
+
+Some other examples of per-period limits: “1 domain change per week”, “2 exports/day”. Those are discrete allowances, not metered workloads. For classic metered workloads (API calls, image generations, tokenized compute), use credits instead.
+
+Here's a few rules for a clean separation to help you decide when to use either gem:
+
+`pricing_plans` handles:
+  - Booleans (feature flags).
+  - Persistent caps (max concurrent resources: products, seats, projects at a time).
+  - Discrete per-period allowances (e.g., “3 exports / month”), with no overage purchasing.
+
+`usage_credits` handles:
+  - Metered consumption (API calls, generations, storage GB*hrs, etc.).
+  - Included monthly credits via subscription plans.
+  - Top-ups and pay-as-you-go.
+  - Rollover/expire semantics and the entire ledger.
+
+If a dimension is metered and you want to sell overage/top-ups, use credits only. Don’t also define a periodic limit for the same dimension in `pricing_plans`. We’ll actively lint and refuse dual definitions at boot.
+
+### How to show `usage_credits` in `pricing_plans`
+
+With all that being said, in SaaS users would typically find information about plan credits in the pricing plan table, and because of that, and since `pricing_plans` should be the single source of truth for pricing plans in your Rails app, you should include how many credits your plans give in `pricing_plans.rb`:
+
+```ruby
+PricingPlans.configure do |config|
+  plan :pro do
+    bullets "API access", "100 credits per month"
+  end
+end
+```
+
+`pricing_plans` ships some ergonomics to declare and render included credits, and guardrails to keep your configuration coherent when `usage_credits` is present.
+
+#### Declare included credits in your plans (single currency)
+
+Plans can advertise the total credits included. This is cosmetic for pricing UI; `usage_credits` remains the source of truth for fulfillment and spending:
+
+```ruby
+PricingPlans.configure do |config|
+  config.plan :free do
+    price 0
+    includes_credits 100
+  end
+
+  config.plan :pro do
+    price 29
+    includes_credits 5_000
+  end
+end
+```
+
+When you’re composing your UI, you can read credits via `plan.credits_included`.
+
+> [!IMPORTANT]
+> You need to keep defining operations and subscription fulfillment in your `usage_credits` initializer, declaring it in pricing_plans is purely cosmetic and for ergonomics to render pricing tables.
+
+#### Guardrails when `usage_credits` is installed
+
+When the `usage_credits` gem is present, we lint your configuration at boot to prevent ambiguous setups:
+
+Collisions between credits and per‑period plan limits are disallowed: you cannot define a per‑period limit for a key that is also a `usage_credits` operation (e.g., `limits :api_calls, to: 50, per: :month`). If a dimension is metered, use credits only.
+
+This enforces a clean separation:
+
+- Use `usage_credits` for metered workloads you may wish to top‑up or charge PAYG for.
+- Use `pricing_plans` limits for discrete allowances and feature flags (things that don’t behave like a currency).
+
+#### No runtime coupling; single source of truth
+
+`pricing_plans` does not spend or refill credits — that’s owned by `usage_credits`.
+
+- Keep using `@user.spend_credits_on(:operation, ...)`, subscription fulfillment, and credit packs in `usage_credits`.
+- Treat `includes_credits` here as pricing UI copy only. The single source of truth for operations, costs, fulfillment cadence, rollover/expire, and balances lives in `usage_credits`.