<% if items&.any? %>
diff --git a/docs/api/rails_provider_generator.md b/docs/api/rails_provider_generator.md
new file mode 100644
index 000000000..6700798e0
--- /dev/null
+++ b/docs/api/rails_provider_generator.md
@@ -0,0 +1,935 @@
+# Rails `Provider` Generator Guide
+
+This guide explains how to use the `Provider` generators, which make it easy to add new
+integrations with either **global** or **per-family** scope credentials.
+
+## Table of Contents
+1. [Quick Start](#quick-start)
+2. [Global vs Per-Family: Which to Use?](#global-vs-per-family-which-to-use)
+3. [Provider:Family Generator](#providerfamily-generator)
+4. [Provider:Global Generator](#providerglobal-generator)
+5. [Comparison Table](#comparison-table)
+6. [Examples](#examples)
+
+---
+
+## Quick Start
+
+### Two Generators Available
+
+```bash
+# Per-Family Provider (each family has separate credentials)
+rails g provider:family
field:type[:secret] ...
+
+# Global Provider (all families share site-wide credentials)
+rails g provider:global field:type[:secret] ...
+```
+
+### Quick Examples
+
+```bash
+# Per-family: Each family has their own Lunchflow API key
+rails g provider:family lunchflow api_key:text:secret base_url:string
+
+# Global: All families share the same Plaid credentials
+rails g provider:global plaid \
+ client_id:string:secret \
+ secret:string:secret \
+ environment:string:default=sandbox
+```
+
+---
+
+## Global vs Per-Family: Which to Use?
+
+### Use `provider:global` When:
+- ✅ One set of credentials serves the entire application
+- ✅ Provider charges per-application (not per-customer)
+- ✅ You control the API account (self-hosted or managed mode)
+- ✅ All families can safely share access
+- ✅ Examples: Plaid, OpenAI, exchange rate services
+
+### Use `provider:family` When:
+- ✅ Each family/customer needs their own credentials
+- ✅ Provider charges per-customer
+- ✅ Users bring their own API keys
+- ✅ Data isolation required between families
+- ✅ Examples: Lunch Flow, SimpleFIN, YNAB, personal bank APIs
+
+---
+
+## Provider:Family Generator
+
+### Usage
+
+```bash
+rails g provider:family field:type[:secret][:default=value] ...
+```
+
+### Example: Adding a MyBank Provider
+
+```bash
+rails g provider:family my_bank \
+ api_key:text:secret \
+ base_url:string:default=https://api.mybank.com \
+ refresh_token:text:secret
+```
+
+### What Gets Generated
+
+This single command generates:
+- ✅ Migration for `my_bank_items` and `my_bank_accounts` tables **with credential fields**
+- ✅ Models: `MyBankItem`, `MyBankAccount`, and `MyBankItem::Provided` concern
+- ✅ Adapter class for provider integration
+- ✅ Simple manual panel view for provider settings
+- ✅ Controller with CRUD actions and Turbo Stream support
+- ✅ Routes
+- ✅ Updates to settings controller and view
+
+### Key Characteristics
+- **Credentials**: Stored in `my_bank_items` table (encrypted)
+- **Isolation**: Each family has completely separate credentials
+- **UI**: Manual form panel at `/settings/providers`
+- **Configuration**: Per-family, self-service
+
+---
+
+## Provider:Global Generator
+
+### Usage
+
+```bash
+rails g provider:global field:type[:secret][:default=value] ...
+```
+
+### Example: Adding a Plaid Provider
+
+```bash
+rails g provider:global plaid \
+ client_id:string:secret \
+ secret:string:secret \
+ environment:string:default=sandbox
+```
+
+### What Gets Generated
+
+This single command generates:
+- ✅ Migration for `plaid_items` and `plaid_accounts` tables **without credential fields**
+- ✅ Models: `PlaidItem`, `PlaidAccount`, and `PlaidItem::Provided` concern
+- ✅ Adapter with `Provider::Configurable`
+- ❌ No controller (credentials managed globally)
+- ❌ No view (UI auto-generated by `Provider::Configurable`)
+- ❌ No routes (no CRUD needed)
+
+### Key Characteristics
+- **Credentials**: Stored in `settings` table (global, not encrypted)
+- **Sharing**: All families use the same credentials
+- **UI**: Auto-generated at `/settings/providers` (self-hosted mode only)
+- **Configuration**: ENV variables or admin settings
+
+### Important Notes
+- Credentials are shared by **all families** - use only for trusted services
+- Only available in **self-hosted mode** (admin-only access)
+- No per-family credential management needed
+- Simpler implementation (fewer files generated)
+
+---
+
+## Comparison Table
+
+| Aspect | `provider:family` | `provider:global` |
+|--------|------------------|------------------|
+| **Credentials storage** | `provider_items` table (per-family) | `settings` table (global) |
+| **Credential encryption** | ✅ Yes (ActiveRecord encryption) | ❌ No (plaintext in settings) |
+| **Family isolation** | ✅ Complete (each family has own credentials) | ❌ None (all families share) |
+| **Files generated** | 9+ files | 5 files |
+| **Migration includes credentials** | ✅ Yes | ❌ No |
+| **Controller** | ✅ Yes (simple CRUD) | ❌ No |
+| **View** | ✅ Manual form panel | ❌ Auto-generated |
+| **Routes** | ✅ Yes | ❌ No |
+| **UI location** | `/settings/providers` (always) | `/settings/providers` (self-hosted only) |
+| **ENV variable support** | ❌ No (per-family can't use ENV) | ✅ Yes (fallback) |
+| **Use case** | User brings own API key | Platform provides API access |
+| **Examples** | Lunch Flow, SimpleFIN, YNAB | Plaid, OpenAI, TwelveData |
+
+---
+
+## What Gets Generated (Detailed)
+
+### 1. Migration
+
+**File:** `db/migrate/xxx_create_my_bank_tables_and_accounts.rb`
+
+Creates two complete tables with all necessary fields:
+
+```ruby
+class CreateMyBankTablesAndAccounts < ActiveRecord::Migration[7.2]
+ def change
+ # Create provider items table (stores per-family connection credentials)
+ create_table :my_bank_items, id: :uuid do |t|
+ t.references :family, null: false, foreign_key: true, type: :uuid
+ t.string :name
+
+ # Institution metadata
+ t.string :institution_id
+ t.string :institution_name
+ t.string :institution_domain
+ t.string :institution_url
+ t.string :institution_color
+
+ # Status and lifecycle
+ t.string :status, default: "good"
+ t.boolean :scheduled_for_deletion, default: false
+ t.boolean :pending_account_setup, default: false
+
+ # Sync settings
+ t.datetime :sync_start_date
+
+ # Raw data storage
+ t.jsonb :raw_payload
+ t.jsonb :raw_institution_payload
+
+ # Provider-specific credential fields
+ t.text :api_key
+ t.string :base_url
+ t.text :refresh_token
+
+ t.timestamps
+ end
+
+ add_index :my_bank_items, :family_id
+ add_index :my_bank_items, :status
+
+ # Create provider accounts table (stores individual account data from provider)
+ create_table :my_bank_accounts, id: :uuid do |t|
+ t.references :my_bank_item, null: false, foreign_key: true, type: :uuid
+
+ # Account identification
+ t.string :name
+ t.string :account_id
+
+ # Account details
+ t.string :currency
+ t.decimal :current_balance, precision: 19, scale: 4
+ t.string :account_status
+ t.string :account_type
+ t.string :provider
+
+ # Metadata and raw data
+ t.jsonb :institution_metadata
+ t.jsonb :raw_payload
+ t.jsonb :raw_transactions_payload
+
+ t.timestamps
+ end
+
+ add_index :my_bank_accounts, :account_id
+ add_index :my_bank_accounts, :my_bank_item_id
+ end
+end
+```
+
+### 2. Models
+
+**File:** `app/models/my_bank_item.rb`
+
+The item model stores per-family connection credentials:
+
+```ruby
+class MyBankItem < ApplicationRecord
+ include Syncable, Provided
+
+ enum :status, { good: "good", requires_update: "requires_update" }, default: :good
+
+ # Encryption for secret fields
+ if Rails.application.credentials.active_record_encryption.present?
+ encrypts :api_key, :refresh_token, deterministic: true
+ end
+
+ validates :name, presence: true
+ validates :api_key, presence: true, on: :create
+ validates :refresh_token, presence: true, on: :create
+
+ belongs_to :family
+ has_one_attached :logo
+ has_many :my_bank_accounts, dependent: :destroy
+ has_many :accounts, through: :my_bank_accounts
+
+ scope :active, -> { where(scheduled_for_deletion: false) }
+ scope :ordered, -> { order(created_at: :desc) }
+ scope :needs_update, -> { where(status: :requires_update) }
+
+ def destroy_later
+ update!(scheduled_for_deletion: true)
+ DestroyJob.perform_later(self)
+ end
+
+ def credentials_configured?
+ api_key.present? && refresh_token.present?
+ end
+
+ def effective_base_url
+ base_url.presence || "https://api.mybank.com"
+ end
+end
+```
+
+**File:** `app/models/my_bank_account.rb`
+
+The account model stores individual account data from the provider:
+
+```ruby
+class MyBankAccount < ApplicationRecord
+ include CurrencyNormalizable
+
+ belongs_to :my_bank_item
+
+ # Association through account_providers for linking to internal accounts
+ has_one :account_provider, as: :provider, dependent: :destroy
+ has_one :account, through: :account_provider, source: :account
+
+ validates :name, :currency, presence: true
+
+ def upsert_my_bank_snapshot!(account_snapshot)
+ update!(
+ current_balance: account_snapshot[:balance],
+ currency: parse_currency(account_snapshot[:currency]) || "USD",
+ name: account_snapshot[:name],
+ account_id: account_snapshot[:id]&.to_s,
+ account_status: account_snapshot[:status],
+ raw_payload: account_snapshot
+ )
+ end
+end
+```
+
+**File:** `app/models/my_bank_item/provided.rb`
+
+The Provided concern connects the item to its provider SDK:
+
+```ruby
+module MyBankItem::Provided
+ extend ActiveSupport::Concern
+
+ def my_bank_provider
+ return nil unless credentials_configured?
+
+ Provider::MyBank.new(
+ api_key,
+ base_url: effective_base_url,
+ refresh_token: refresh_token
+ )
+ end
+end
+```
+
+### 3. Adapter
+
+**File:** `app/models/provider/my_bank_adapter.rb`
+
+```ruby
+class Provider::MyBankAdapter < Provider::Base
+ include Provider::Syncable
+ include Provider::InstitutionMetadata
+
+ # Register this adapter with the factory
+ Provider::Factory.register("MyBankAccount", self)
+
+ def provider_name
+ "my_bank"
+ end
+
+ # Build a My Bank provider instance with family-specific credentials
+ def self.build_provider(family:)
+ return nil unless family.present?
+
+ # Get family-specific credentials
+ my_bank_item = family.my_bank_items.where.not(api_key: nil).first
+ return nil unless my_bank_item&.credentials_configured?
+
+ # TODO: Implement provider initialization
+ Provider::MyBank.new(
+ my_bank_item.api_key,
+ base_url: my_bank_item.effective_base_url,
+ refresh_token: my_bank_item.refresh_token
+ )
+ end
+
+ def sync_path
+ Rails.application.routes.url_helpers.sync_my_bank_item_path(item)
+ end
+
+ def item
+ provider_account.my_bank_item
+ end
+
+ def can_delete_holdings?
+ false
+ end
+
+ def institution_domain
+ metadata = provider_account.institution_metadata
+ return nil unless metadata.present?
+ metadata["domain"]
+ end
+
+ def institution_name
+ metadata = provider_account.institution_metadata
+ return nil unless metadata.present?
+ metadata["name"] || item&.institution_name
+ end
+
+ def institution_url
+ metadata = provider_account.institution_metadata
+ return nil unless metadata.present?
+ metadata["url"] || item&.institution_url
+ end
+
+ def institution_color
+ item&.institution_color
+ end
+end
+```
+
+### 4. Panel View
+
+**File:** `app/views/settings/providers/_my_bank_panel.html.erb`
+
+A simple manual form for configuring My Bank credentials:
+
+```erb
+
+
+
Setup instructions:
+
+ - Visit your My Bank dashboard to get your credentials
+ - Enter your credentials below and click the Save button
+ - After a successful connection, go to the Accounts tab to set up new accounts
+
+
+
Field descriptions:
+
+ - API Key: Your My Bank API key (required)
+ - Base URL: Your My Bank base URL (optional, defaults to https://api.mybank.com)
+ - Refresh Token: Your My Bank refresh token (required)
+
+
+
+ <% error_msg = local_assigns[:error_message] || @error_message %>
+ <% if error_msg.present? %>
+
+ <%= error_msg %>
+
+ <% end %>
+
+ <%
+ # Get or initialize a my_bank_item for this family
+ my_bank_item = Current.family.my_bank_items.first_or_initialize(name: "My Bank Connection")
+ is_new_record = my_bank_item.new_record?
+ %>
+
+ <%= styled_form_with model: my_bank_item,
+ url: is_new_record ? my_bank_items_path : my_bank_item_path(my_bank_item),
+ scope: :my_bank_item,
+ method: is_new_record ? :post : :patch,
+ data: { turbo: true },
+ class: "space-y-3" do |form| %>
+ <%= form.text_field :api_key,
+ label: "API Key",
+ type: :password %>
+
+ <%= form.text_field :base_url,
+ label: "Base URL (Optional)",
+ placeholder: "https://api.mybank.com (default)",
+ value: my_bank_item.base_url %>
+
+ <%= form.text_field :refresh_token,
+ label: "Refresh Token",
+ type: :password %>
+
+
+ <%= form.submit is_new_record ? "Save Configuration" : "Update Configuration",
+ class: "inline-flex items-center justify-center rounded-lg px-4 py-2 text-sm font-medium text-white bg-gray-900 hover:bg-gray-800 focus:outline-none focus:ring-2 focus:ring-gray-900 focus:ring-offset-2 transition-colors" %>
+
+ <% end %>
+
+ <% items = local_assigns[:my_bank_items] || @my_bank_items || Current.family.my_bank_items.where.not(api_key: nil) %>
+ <% if items&.any? %>
+
+
+
Configured and ready to use. Visit the Accounts tab to manage and set up accounts.
+
+ <% end %>
+
+ <%# Add custom header %>
+
+ <%= image_tag "my_bank_logo.svg", class: "w-8 h-8" %>
+
My Bank Integration
+
+
+ <%# The generated form content goes here... %>
+
+ <%# Add custom help section %>
+
+
+
+
Setup instructions:
+
+ - Visit your <%= class_name.titleize %> dashboard to get your credentials
+ - Enter your credentials below and click the Save button
+ - After a successful connection, go to the Accounts tab to set up new accounts
+
+
+
Field descriptions:
+
+<% parsed_fields.each do |field| -%>
+ - <%= field[:name].titleize %>: Your <%= class_name.titleize %> <%= field[:name].humanize.downcase %><%= field[:secret] ? ' (required)' : '' %><%= field[:default] ? " (optional, defaults to #{field[:default]})" : '' %>
+<% end -%>
+
+
+
+ <%% error_msg = local_assigns[:error_message] || @error_message %>
+ <%% if error_msg.present? %>
+
+ <%% end %>
+
+ <%%
+ # Get or initialize a <%= file_name %>_item for this family
+ # - If family has an item WITH credentials, use it (for updates)
+ # - If family has an item WITHOUT credentials, use it (to add credentials)
+ # - If family has no items at all, create a new one
+ <%= file_name %>_item = Current.family.<%= file_name %>_items.first_or_initialize(name: "<%= class_name.titleize %> Connection")
+ is_new_record = <%= file_name %>_item.new_record?
+ %>
+
+ <%%= styled_form_with model: <%= file_name %>_item,
+ url: is_new_record ? <%= file_name %>_items_path : <%= file_name %>_item_path(<%= file_name %>_item),
+ scope: :<%= file_name %>_item,
+ method: is_new_record ? :post : :patch,
+ data: { turbo: true },
+ class: "space-y-3" do |form| %>
+<% parsed_fields.each do |field| -%>
+ <%%= form.<%= %w[text string].include?(field[:type]) ? 'text_field' : 'number_field' %> :<%= field[:name] %>,
+ label: "<%= field[:name].titleize %><%= field[:default] ? ' (Optional)' : '' %>",
+<% if field[:secret] -%>
+ placeholder: is_new_record ? "Paste <%= field[:name].humanize.downcase %> here" : "Enter new <%= field[:name].humanize.downcase %> to update",
+ type: :password %>
+<% elsif field[:default] -%>
+ placeholder: "<%= field[:default] %> (default)",
+ value: <%= file_name %>_item.<%= field[:name] %> %>
+<% else -%>
+ placeholder: is_new_record ? "Enter <%= field[:name].humanize.downcase %>" : "Enter new <%= field[:name].humanize.downcase %> to update",
+ value: <%= file_name %>_item.<%= field[:name] %> %>
+<% end -%>
+
+<% end -%>
+
+ <%%= form.submit is_new_record ? "Save Configuration" : "Update Configuration",
+ class: "inline-flex items-center justify-center rounded-lg px-4 py-2 text-sm font-medium text-white bg-gray-900 hover:bg-gray-800 focus:outline-none focus:ring-2 focus:ring-gray-900 focus:ring-offset-2 transition-colors" %>
+
+ <%% end %>
+
+ <%% items = local_assigns[:<%= file_name %>_items] || @<%= file_name %>_items || Current.family.<%= file_name %>_items.where.not(<%= parsed_fields.select { |f| f[:secret] }.first&.dig(:name) || 'api_key' %>: [nil, ""]) %>
+
+ <%% if items&.any? %>
+
+
Configured and ready to use. Visit the Accounts tab to manage and set up accounts.
+ <%% else %>
+
+
Not configured
+ <%% end %>
+
+