bullet_train 1.2.10 → 1.2.12

data/docs/action-models.md

@@ -3,7 +3,7 @@
 Action Models make it easy to scaffold and implement user-facing custom actions in your Bullet Train application and API in a RESTful way. Action Models are perfect for situations where you want one or more of the following:
 
  - Bulk actions for a model where users can select one or more objects as targets.
- - Long-running background tasks where you want to keep users updated on their progress in the UI or notify then after completion.
+ - Long-running background tasks where you want to keep users updated on their progress in the UI or notify them after completion.
  - Actions that have one or more configuration options available.
  - Tasks that can be configured now but scheduled to take place later.
  - Actions where you want to keep an in-app record of when it happened and who initiated the action.
@@ -44,11 +44,11 @@ end
 
 ### 1. Purchase Bullet Train Pro
 
-First, [purchase Bullet Train Pro](https://buy.stripe.com/aEU7vc4dBfHtfO89AV). Once you've completed this process, you'll be issued a private token for the Bullet Train Pro package server. The process is currently completed manually, so you may have to way a little to receive your keys.
+First, [purchase Bullet Train Pro](https://buy.stripe.com/aEU7vc4dBfHtfO89AV). Once you've completed this process, you'll be issued a private token for the Bullet Train Pro package server. The process is currently completed manually, so you may have to wait a little to receive your keys.
 
 ### 2. Install the Package
 
-You'll need to specify both Ruby gems in your `Gemfile`, since we have to specify a private source for both:
+Then you can specify the Ruby gem in your `Gemfile`:
 
 ```ruby
 source "https://YOUR_TOKEN_HERE@gem.fury.io/bullettrain" do
@@ -104,7 +104,7 @@ Because Action Models are just regular models, you can add new fields to them wi
 For example:
 
 ```
-rails g migration add notify_users_to_projects_archive_actions notify_users:boolean
+rails g migration add_notify_users_to_projects_archive_actions notify_users:boolean
 # side quest: update the generated migration with `default: false` on the new boolean field.
 bin/super-scaffold crud-field Projects::ArchiveAction notify_users:boolean
 ```
@@ -145,4 +145,4 @@ This final type of action is available for things like importers that don't nece
 
 ### Do Action Models have to be persisted to the database?
 
-No. Action Models extend from `ApplicationRecord` by default, but if you're not using features that depend on persistence to the database, you can make them `include ActiveModel::API` instead. That said, it's probably not worth the trouble. As an alternative, consider just including `Actions::CleansUp` in your action to ensure it removes itself from the database after completion.
+No. Action Models extend from `ApplicationRecord` by default, but if you're not using features that depend on persistence to the database, you can make them `include ActiveModel::API` instead. That said, it's probably not worth the trouble. As an alternative, consider just including `Actions::CleansUp` in your action to ensure it removes itself from the database after completion.

data/docs/api/versioning.md

@@ -31,8 +31,6 @@ If you're in a situation where you know you need to bump your API version to hel
 rake bullet_train:api:bump_version
 ```
 
-> TODO This Rake task doesn't exist yet.
-
 ## What happens when you bump an API version?
 When you bump your API version, all of the files and directories that are namespaced with the API version number will be duplicated into a new namespace for the new API version number.
 

data/docs/api.md

@@ -19,7 +19,7 @@ APIs are built using standard Rails tools like `ActiveController::API`, [Strong
 In the same way we've adopted [Devise](https://github.com/heartcombo/devise) for best-of-breed and battle-tested authentication on the browser side, we've adopted [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper) for best-of-breed and battle-tested authentication on the API side.
 
 ### DRY Authorization Logic
-Because our API endpoints are standard Rails controllers, they're able to leverage the exact same [permissions definitions and authorization logic](https://github.com/bullet-train-co/bullet_train-base/blob/main/docs/permissions.md) as our account controllers.
+Because our API endpoints are standard Rails controllers, they're able to leverage the exact same [permissions definitions and authorization logic](/docs/permissions) as our account controllers.
 
 ## Structure
 Where vanilla Rails uses a single controller in `app/controllers` for both in-browser and API requests, Bullet Train splits these into two separate controllers, one in `app/controllers/account` and another in `app/controllers/api/v1`, although a lot of logic is shared between the two.
@@ -40,7 +40,7 @@ The primary definition of Strong Parameters for a given resource is defined in t
 include strong_parameters_from_api
 ```
 
-> This may feel counter-intuitive to some developers and you might wonder why we don't flip this around and have the primary definition in the account controller and have the API controller delegate to it. The answer is a pragmatic one: creating and maintaining the defintion of Strong Paramters in the API controller means it gets automatically frozen in time should you ever need to [bump your API version number](/api/docs/versioning.md). We probably _could_ accomplish this if things were the other way around, but it wouldn't happen automatically.
+> This may feel counter-intuitive to some developers and you might wonder why we don't flip this around and have the primary definition in the account controller and have the API controller delegate to it. The answer is a pragmatic one: creating and maintaining the defintion of Strong Paramters in the API controller means it gets automatically frozen in time should you ever need to [bump your API version number](/docs/api/versioning.md). We probably _could_ accomplish this if things were the other way around, but it wouldn't happen automatically.
 
 If by chance there are additional attributes that should be permitted or specific logic that needs to be run as part of the account controller (or inversely, only in the API controller), you can specify that in the controller like so:
 
@@ -71,7 +71,7 @@ end
 ```
 
 ## Usage Example
-First, provision a platform application in section titled "Your Applications" in the "Developers" menu of the application. When you create a new platform application, an access token that doesn't automatically expire will be automatically provisioned along with it. You can then use the access token to hit the API, as seen in the following Ruby-based example:
+First, provision a platform application in the section titled "Your Applications" in the "Developers" menu of the application. When you create a new platform application, an access token that doesn't automatically expire will be automatically provisioned along with it. You can then use the access token to hit the API, as seen in the following Ruby-based example:
 
 ```ruby
 require 'net/http'
@@ -103,4 +103,4 @@ response = client.patch("/api/v1/teams/1", {team: team}.to_json, headers)
  - [API Versioning](/docs/api/versioning.md)
 
 ## A Note About Other Serializers and API Frameworks
-In early versions of Bullet Train we made the decision to adopt a specific serialization library, [ActiveModelSerializers](https://github.com/rails-api/active_model_serializers) and in subsequent versions we went as far as to adopt an entire third-party framework ([Grape](https://github.com/ruby-grape/grape)) and a third-party API specification ([JSON:API](https://jsonapi.org)). We now consider it out-of-scope to try and make such decisions on behalf of developers. Support for them in Bullet Train applications and in Super Scaffolding could be created by third-parties.
+In early versions of Bullet Train we made the decision to adopt a specific serialization library, [ActiveModelSerializers](https://github.com/rails-api/active_model_serializers), and in subsequent versions we went as far as to adopt an entire third-party framework ([Grape](https://github.com/ruby-grape/grape)) and a third-party API specification ([JSON:API](https://jsonapi.org)). We now consider it out-of-scope to try and make such decisions on behalf of developers. Support for them in Bullet Train applications and in Super Scaffolding could be created by third-parties.

data/docs/application-options.md

@@ -23,7 +23,7 @@ The helper methods below can also be directly invoked in your application if you
 | STRIPE_CLIENT_ID | See [Bullet Train Billing for Stripe](/docs/billing/stripe.md) for more information and related environment variables. |
 | CLOUDINARY_URL | Enables use of Cloudinary for handling images. |
 | TWO_FACTOR_ENCRYPTION_KEY | Enables two-factor authentication through Devise. |
-| INVITATION_KEYS | See more [Invitation Only](/docs/authentication.md) for more information. |
+| INVITATION_KEYS | See [Invitation Only](/docs/authentication.md) for more information. |
 | FONTAWESOME_NPM_AUTH_TOKEN | Enables use of Font Awesome. |
 | SILENCE_LOGS | Silences Super Scaffolding logs. |
 | TESTING_PROVISION_KEY | Creates a test `Platform::Application` by accessing `/testing/provision?key=your_provision_key` |

data/docs/billing/usage.md

@@ -45,7 +45,31 @@ Note this is different than how many Rails engines ask you to install migrations
 rake db:migrate
 ```
 
-## Configuration 
+### 2.5. Add Model Support
+
+There are two concerns that need to be added to your application models.
+
+The first concern is `Billing::UsageSupport` and it allows tracking of usage of verbs on the models you want to support tracking usage on. It is recommended to add this capability to all models, so you can add this.
+
+```
+# app/models/application_record.rb
+
+class ApplicationRecord
+  include Billing::Usage
+end
+```
+
+The second concern is `Billing::HasTrackers` and it allows any model to hold the usage tracking. This is usually done on the `Team` model.
+
+```
+# app/models/team.rb
+
+class Team
+  include Billing::HasTrackers
+end
+```
+
+## Configuration
 Usage limit configuration piggybacks on your [product definitions](/docs/billing/stripe.md) in `config/models/billing/products.yml`. It may help to make reference to the [default product definitions in the Bullet Train starter repository](https://github.com/bullet-train-co/bullet_train/blob/main/config/models/billing/products.yml).
 
 ## Basic Usage Limits
@@ -63,21 +87,37 @@ basic:
         upgradable: true
 ```
 
-It's important to note that `have` is a special verb and represents the simple `count` of a given model on a `Team`. All _other_ verbs will be interpreted as time-based usage limits.
+Any verb that your model supports can be used. It is recommended to standardize on using the action as the verb. For example, when creating a new model, use the verb _create_. When deleting a model, use the verb _delete_, and so on.
+
+It's important to note that `have` is a special verb and represents the simple `count` of a given model on a `Team`. All _other_ verbs will be interpreted as [time-based usage limits](#time-based-usage-limits).
 
 ### Options
- - `enforcement` can be `hard` or `soft`. 
+ - `enforcement` can be `hard` or `soft`.
    - When a `hard` limit is hit, the create form will be disabled.
    - When a `soft` limit is hit, users are simply notified, but can continue to surpass the limit.
  - `upgradable` indicates whether or not a user should be prompted to upgrade when they hit this limit.
 
 ### Excluding Records from `have` Usage Limits
-All models have an overridable `billable` scope that includes all records by default. You can override this scope to ensure that certain records are filtered out from consideration when calculating usage limits. For example, we do the following on `Membership` to exclude removed team members from contributing to any limitation put on the number of team members, like so:
+All models have an overridable `billable` scope that includes all records by default. You can override this scope on any given model to ensure that certain records are filtered out from consideration when calculating usage limits. For example, we do the following on `Membership` to exclude removed team members from contributing to any limitation put on the number of team members, like so:
 
 ```ruby
 scope :billable, -> { current_and_invited }
 ```
 
+Another example may be excluding "archived" items within the billable usage count such as:
+
+```ruby
+module Archivable
+  extend ActiveSupport::Concern
+
+  included do
+    scope :billable, -> { where(archived_at: nil) }
+
+    # ...
+  end
+end
+```
+
 ## Time-Based Usage Limits
 
 ### Configuring Limits
@@ -95,7 +135,7 @@ free:
 ```
 
  - `count` is how many times something can happen.
- - `duration` and `interval` represent the time period we'll track for, e.g. "3 days" in this case. 
+ - `duration` and `interval` represent the time period we'll track for, e.g. "3 days" in this case.
  - Valid options for `interval` are anything you can append to an integer, e.g. `minutes`, `hours`, `days`, `weeks`, `months`, etc., both plural and singular.
 
 ### Tracking Usage
@@ -112,7 +152,7 @@ class Blogs::Post < ApplicationRecord
 end
 ```
 
-If you'd like to increment the usage count by more than one, you can pass a quantity like `count: 5` to this call.
+It is important that you use the past tense of the verb when tracking so it is tracked appropriately. If you'd like to increment the usage count by more than one, you can pass a quantity like `count: 5` to this call.
 
 ### Cycling Trackers Regularly
 We include a Rake task you'll need to run on a regular basis in order to cycle the usage trackers that are created at a `Team` level. By default, you should probably run this every five minutes:
@@ -123,26 +163,64 @@ rake billing:cycle_usage_trackers
 
 ## Checking Usage Limits
 
+### Checking Time-Based Limits
+To make decisions based on or enforce time-based `hard` limits in your views and controllers, you can use the `current_limits` helper like this:
+
+```ruby
+current_limits.can?(:publish, Blogs::Post)
+```
+
+(You can also pass quantities like `count: 5` as an option.)
+
 ### Checking Basic Limits
 For basic `have` limits, forms generated by Super Scaffolding will be automatically disabled when a `hard` limit has been hit. Index views will also alert users to a limit being hit or broken for both `hard` and `soft` limits.
 
 > If your Bullet Train application scaffolding predates this feature, you can reference the newest Tangible Things [index template](https://github.com/bullet-train-co/bullet_train-super_scaffolding/blob/main/app/views/account/scaffolding/completely_concrete/tangible_things/_index.html.erb) and [form template](https://github.com/bullet-train-co/bullet_train-super_scaffolding/blob/main/app/views/account/scaffolding/completely_concrete/tangible_things/_form.html.erb) to see how we're using the `shared/limits/index` and `shared/limits/form` partials to present and enforce usage limits, and copy this usage in your own views.
 
-### Checking Time-Based Limits
-To make decisions based on or enforce time-based limits in your views and controllers, you can use the `current_limits` helper like this:
+To make decisions in other views or within controllers, you can use the `#exhausted?` method on the `current_limits` helper to check if any basic `have` limits have been hit or exceeded.
 
-```
-current_limits.can?(:publish, Blogs::Post)
-```
+```ruby
+# Inspects broken hard limits by default
+current_limits.exhausted?(Blogs::Post)
 
-(You can also pass quantities like `count: 5` as an option.)
+# Or you can specify the `enforcement` level
+current_limits.exhausted?(Blogs::Post, :soft)
+```
 
 #### Presenting an Error
 
-If you're checking on this in a controller before taking an action and you want to present an error to the user based on their usage, you can redirect with this special flash error message key:
+If you want to present an error or warning to the user based on their usage, there themed alert partials that can be displayed in your views. These partials can be rendered via the path `shared/limits/error` and `shared/limits/warning` respectively.
 
+```ruby
+<%= render "shared/limits/warning", model: model.class %>
+
+<%= render "shared/limits/error", action: :create, model: model.class, count: 1, cancel_path: cancel_path %>
 ```
-flash[:error] = :create_limit
-redirect_to [:account, @post]
+
+These partials have various local assigns that are used to configure the partial.
+
+* `action` - the `verb` to check the usage on the model for. Defaults to `have`.
+* `color` - the `color` value to use for the alert partial. Defaults to `red` for errors and `yellow` for warnings.
+* `count` - the number of objects intended to be acted upon. Defaults to 1.
+* `model` - the `class` relationship as the model to inspect usage on. Defaults to `form.object.class`.
+
+### Changing Products
+The default list of products that the limits are based off of are the products available from your Billing products, which is most likely a list of subscription plans from Stripe.
+
+You can change this default behavior by creating your own billing limiter and overriding the `current_products` method. This method should return a list of products that all respond to a `limits` message. The rest of the behavior is encapsulated in the `Billing::Limiter::Base` concern.
+
+```ruby
+# app/models/billing/email_limiter.rb
+
+class Billing::EmailLimiter
+  include Billing::Limiter::Base
+
+  def current_products
+    products = Billing::Product.data
+
+    EmailService.retrieve_product_tiers.map do |tier|
+      add_product_limit(tier, products)
+    end
+  end
+end
 ```
-> TODO This technically works but needs to be redone. Too limited.

data/docs/field-partials.md

@@ -40,7 +40,7 @@ Breaking down the invocation:
  - `text_field` matches the name of the native Rails form field helper we want to invoke.
  - The `form` option passes a reference to the form object the field will exist within.
  - The `method` option specifies which attribute of the model the field represents, in the same way as the first parameter of the basic Rails `text_field` helper.
- - The `options` option is basically a passthrough, allowing you to specify options which will passed directly to the underlying Rails form field helper.
+ - The `options` option is basically a passthrough, allowing you to specify options which will be passed directly to the underlying Rails form field helper.
 
 The 1:1 relationship between these field partials and their underlying Rails form helpers is an important design decision. For example, the way `options` is passed through to native Rails form field helpers means that experienced Rails developers will still be able to leverage what they remember about using Rails, while those of us who don't readily remember all the various options of those helpers can make use of [the standard Rails documentation](https://guides.rubyonrails.org/form_helpers.html) and the great wealth of Rails code examples available online and still take advantage of these field partials. That means the amount of documentation we need to maintain for these field partials is strictly for those features that are in addition to what Rails provides by default.
 
@@ -76,7 +76,7 @@ When you're including multiple fields, you can DRY up redundant settings (e.g. `
 ```
 
 ## Field partials that integrate with third-party service providers
- - `cloudinary` makes it trivial to upload photos and images to [Cloudinary](https://cloudinary.com) and store their resulting Cloudinary ID as an attribute of the model backing the form. To enable this field partial, sign up for Cloudinary and copy the "Cloudinary URL" they provide you with into your `config/application.yml` as `CLOUDINARY_URL`. If you use our [Heroku app.json] to provision your production environment, this will happen in that environment automatically.
+ - `cloudinary` makes it trivial to upload photos and images to [Cloudinary](https://cloudinary.com) and store their resulting Cloudinary ID as an attribute of the model backing the form. To enable this field partial, sign up for Cloudinary and copy the "Cloudinary URL" they provide you with into your `config/application.yml` as `CLOUDINARY_URL`. If you use our [Heroku app.json](https://github.com/bullet-train-co/bullet_train/blob/main/app.json) to provision your production environment, this will happen in that environment automatically.
 
 ## Yaml Configuration
 The localization Yaml file (where you configure label and option values for a field) is automatically generated when you run Super Scaffolding for a model. If you haven't done this yet, the localization Yaml file for `Scaffolding::CompletelyConcrete::TangibleThing` serves as a good example. Under `en.scaffolding/completely_concrete/tangible_things.fields` you'll see definitions like this:
@@ -109,23 +109,25 @@ Certain form field partials like `buttons` and `super_select` can also have thei
 
 ## Available Field Partials
 
-| Field Partial | Data Type | Multiple Values? | Assignment Helpers | JavaScript Library | Description | Commercial License Required |
-| --- | --- | --- | --- | --- | --- | --- |
-| `boolean` | `boolean` | `assign_boolean` | | | |
-| [`buttons`](/docs/field-partials/buttons.md) | `string` | Optionally | `assign_checkboxes` | | | |
-| `cloudinary_image` | `string` | | | | | |
-| `color_picker` | | | | [pickr](https://simonwep.github.io/pickr/) | | |
-| `date_and_time_field` | `datetime` | | `assign_date_and_time` | [Date Range Picker](https://www.daterangepicker.com) | | |
-| `date_field` | `date` | | `assign_date` | [Date Range Picker](https://www.daterangepicker.com) | | |
-| `email_field` | `string` | | | | | |
-| [`file_field`](/docs/field-partials/file-field.md) | `attachment` | | [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) | | |
-| `options` | `string` | Optionally | `assign_checkboxes` | | | |
-| `password_field` | `string` | | | | | |
-| `phone_field` | `string` | | | [International Telephone Input](https://intl-tel-input.com) | Ensures telephone numbers are in a format that can be used by providers like Twilio. | |
-| [`super_select`](/docs/field-partials/super-select.md) | `string` | Optionally | `assign_select_options` | [Select2](https://select2.org) | Provides powerful option search, AJAX search, and multi-select functionality. | |
-| `text_area` | `text` | | | | | |
-| `text_field` | `string` | | | | | |
-| `trix_editor` | `text` | | | [Trix](https://github.com/basecamp/trix) | Basic HTML-powered formatting features and support for at-mentions amongst team members. | |
+| Field Partial                                          | Data Type    | Multiple Values? | Assignment Helpers      | JavaScript Library                                                                | Description                                                                              |
+|--------------------------------------------------------|--------------|------------------|-------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
+| `boolean`                                              | `boolean`    |                  | `assign_boolean`        |                                                                                   |                                                                                          |
+| [`buttons`](/docs/field-partials/buttons.md)           | `string`     | Optionally       | `assign_checkboxes`     |                                                                                   |                                                                                          |
+| `cloudinary_image`                                     | `string`     |                  |                         |                                                                                   |                                                                                          |
+| `color_picker`                                         |              |                  |                         | [pickr](https://simonwep.github.io/pickr/)                                        |                                                                                          |
+| `date_and_time_field`                                  | `datetime`   |                  | `assign_date_and_time`  | [Date Range Picker](https://www.daterangepicker.com)                              |                                                                                          |
+| `date_field`                                           | `date`       |                  | `assign_date`           | [Date Range Picker](https://www.daterangepicker.com)                              |                                                                                          |
+| `email_field`                                          | `string`     |                  |                         |                                                                                   |                                                                                          |
+| `emoji_field`                                          | `string`     |                  |                         | [Emoji Mart](https://missiveapp.com/open/emoji-mart) | A front-end library which allows users to browse and select emojis with ease. |                                       |
+| [`file_field`](/docs/field-partials/file-field.md)     | `attachment` |                  |                         | [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) |                                                                                          |
+| `options`                                              | `string`     | Optionally       | `assign_checkboxes`     |                                                                                   |                                                                                          |
+| `password_field`                                       | `string`     |                  |                         |                                                                                   |                                                                                          |
+| `phone_field`                                          | `string`     |                  |                         | [International Telephone Input](https://intl-tel-input.com)                       | Ensures telephone numbers are in a format that can be used by providers like Twilio.     |
+| [`super_select`](/docs/field-partials/super-select.md) | `string`     | Optionally       | `assign_select_options` | [Select2](https://select2.org)                                                    | Provides powerful option search, AJAX search, and multi-select functionality.            |
+| `text_area`                                            | `text`       |                  |                         |                                                                                   |                                                                                          |
+| `text_field`                                           | `string`     |                  |                         |                                                                                   |                                                                                          |
+| `number_field`                                           | `integer`     |                  |                         |                                                                                   |                                                                                          |
+| `trix_editor`                                          | `text`       |                  |                         | [Trix](https://github.com/basecamp/trix)                                          | Basic HTML-powered formatting features and support for at-mentions amongst team members. |
 
 ## A Note On Data Types
 Set the data type to `jsonb` whenever passing the `multiple` option to a new attribute.
@@ -138,4 +140,3 @@ Set the data type to `jsonb` whenever passing the `multiple` option to a new att
  - [`buttons`](/docs/field-partials/buttons.md)
  - [`super_select`](/docs/field-partials/super-select.md)
  - [`file_field`](/docs/field-partials/file-field.md)
-

data/docs/font-awesome-pro.md

@@ -18,7 +18,7 @@ Once you buy a license for Font Awesome Pro, set `FONTAWESOME_NPM_AUTH_TOKEN` in
 - Add `export FONTAWESOME_NPM_AUTH_TOKEN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` in `~/.zshrc`.
 - Restart your terminal.
 
-If you're configuring this in another type of shell, please let us know what the steps are [in a new GitHub issue](http://github.com/bullet-train-co/bullet-train-tailwind-css/issues/new) and we'll add them here for others.
+If you're configuring this in another type of shell, please let us know what the steps are [in a new GitHub issue](https://github.com/bullet-train-co/bullet_train/issues/new) and we'll add them here for others.
 
 ### 2. Add `.npmrc` Configuration
 

data/docs/getting-started.md

@@ -8,7 +8,7 @@ Whether you want to build a new application with Bullet Train or contribute to B
 
 If you're using Bullet Train for the first time, begin by learning these five important techniques:
 
-1. Use `rails g model` to create and `bin/super-scaffold` to scaffold a new model:
+1. Use `rails g model` to create and `bin/super-scaffold crud` to scaffold a new model:
 
     ```
     rails g model Project team:references name:string
@@ -17,7 +17,7 @@ If you're using Bullet Train for the first time, begin by learning these five im
 
     In this example, `Team` refers to the immediate parent of the `Project` resource. For more details, just run `bin/super-scaffold` or [read the documentation](/docs/super-scaffolding.md).
 
-2. Use `rails g migration` and `bin/super-scaffold` to add a new field to a model you've already scaffolded:
+2. Use `rails g migration` and `bin/super-scaffold crud-field` to add a new field to a model you've already scaffolded:
 
     ```
     rails g migration add_description_to_projects description:text
@@ -32,7 +32,7 @@ If you're using Bullet Train for the first time, begin by learning these five im
     - Selecting "Inspect Element".
     - Looking for the `<!-- BEGIN ... -->` comment above the element you've selected.
 
-4. Figure out the full I18N translation key of any string on the page by adding `?show_locales=true` to the URL.
+4. Figure out the full I18n translation key of any string on the page by adding `?show_locales=true` to the URL.
 
 5. Use `bin/resolve` to figure out where framework or theme things are coming from and eject them if you need to customize something locally:
 

data/docs/i18n.md

@@ -8,7 +8,7 @@ We override the native I18n translation method to automatically include the curr
 The following are the details for David’s Membership on Your Team.
 ```
 
-The view can be found here in the `bullet_train-base` gem:<br/>[bullet_train-base/app/views/account/memberships/show.html.erb](https://github.com/bullet-train-co/bullet_train-base/blob/657e932cb4eb3e0c1f56c88c8365c2611de90e06/app/views/account/memberships/show.html.erb#L16)<br/>
+The view can be found here in the `bullet_train` gem:<br/>[bullet_train-core/bullet_train/app/views/account/memberships/show.html.erb](https://github.com/bullet-train-co/bullet_train-core/blob/fab77efab57126c083e0041f97c0e716560a2ffe/bullet_train/app/views/account/memberships/show.html.erb#L16)<br/>
 <br/>
 Looking at the view, you can see we are only passing a key to the translation method for I18n to process:
 
@@ -16,7 +16,7 @@ Looking at the view, you can see we are only passing a key to the translation me
 <%= t('.description') %>
 ```
 
-However, looking at the [locale itself](https://github.com/bullet-train-co/bullet_train-base/blob/657e932cb4eb3e0c1f56c88c8365c2611de90e06/config/locales/en/memberships.en.yml#L82), you can see that the string takes two variables, `memberships_possessive` and `team_name`, to complete the string:
+However, looking at the [locale itself](https://github.com/bullet-train-co/bullet_train-core/blob/fab77efab57126c083e0041f97c0e716560a2ffe/bullet_train/config/locales/en/memberships.en.yml#L82), you can see that the string takes two variables, `memberships_possessive` and `team_name`, to complete the string:
 ```yaml
 description: The following are the details for %{memberships_possessive} Membership on %{team_name}.
 ```
@@ -26,6 +26,6 @@ Usually, you would pass the variable as a keyword argument:
 t('.description', memberships_possessive: memberships_possessive, team_name: current_team.name)
 ```
 
-However, in Bullet Train, we override the original translation method to include variable names like this automatically in our locales. Check out the [locale helper](https://github.com/bullet-train-co/bullet_train-base/blob/main/app/helpers/account/locale_helper.rb) to get a closer look at how we handle strings for internationalization. For example, the two variables above are generated by the method `model_locales` in the locale helper.
+However, in Bullet Train, we override the original translation method to include variable names like this automatically in our locales. Check out the [locale helper](https://github.com/bullet-train-co/bullet_train-core/blob/main/bullet_train/app/helpers/account/locale_helper.rb) to get a closer look at how we handle strings for internationalization. For example, the two variables above are generated by the method `model_locales` in the locale helper.
 
 You can find more information in the [indirection documentation](indirection) about using `bin/resolve` and logs to pinpoint where your locales are coming from.

data/docs/indirection.md

@@ -61,13 +61,15 @@ Would you like to open `/Users/andrewculver/.rbenv/versions/3.1.2/lib/ruby/gems/
 y
 ```
 
-You may also want to consider using `bin/develop`, which will clone the Bullet Train package of your choice to `local/` within your main application's root directory. Running this command will also automatically link the package to your main application and open it in the code editor for you, so you can start using the cloned repository and make changes to your main application right away.
+You may also want to consider using `bin/hack`, which will clone the Bullet Train core packages to `local/bullet_train-core` within your main application's root directory. Running this command will also automatically link the packages to your main application and open bullet_train-core in the code editor for you, so you can start using the cloned repository and make changes to your main application right away.
+
+To revert back to using the original gems, run `bin/hack --reset`. You can link up to your local packages at any time with `bin/hack --link`.
 
 Note that in the example above, the view in question isn't actually coming from the application repository. Instead, it's being included from the `bullet_train-themes-light` package. For further instructions on how to customize it, see [Overriding Framework Defaults](/docs/overriding.md).
 
 ### Drilling Down on Translation Keys
 
-Even in vanilla Rails applications, extracting strings from view files into I18N translation YAML files introduces a layer of indirection. Bullet Train tries to improve the resulting DX with a couple tools that make it easier to figure out where a translation you see in your browser is coming from.
+Even in vanilla Rails applications, extracting strings from view files into I18n translation YAML files introduces a layer of indirection. Bullet Train tries to improve the resulting DX with a couple of tools that make it easier to figure out where a translation you see in your browser is coming from.
 
 #### Show Translation Keys in the Browser with `?show_locales=true`
 
@@ -75,11 +77,11 @@ You can see the full translation key of any string on the page by adding `?show_
 
 #### Log Translation Keys to the Console with `?log_locales=true`
 
-You can also log all the translation key for anything being rendered to the console by adding `?log_locales=true` to the request URL. This can make it easier to copy and paste translation keys for strings that are rendered in non-selectable UI elements.
+You can also log all the translation keys for anything being rendered to the console by adding `?log_locales=true` to the request URL. This can make it easier to copy and paste translation keys for strings that are rendered in non-selectable UI elements.
 
 #### Resolving Translation Keys with `bin/resolve`
 
-Once you have the full I18N translation key, you can use `bin/resolve` to figure out which package and file it's coming from. At that point, if you need to customize it, you can also use the `--eject` option to copy the  the framework for customization in your local application:
+Once you have the full I18n translation key, you can use `bin/resolve` to figure out which package and file it's coming from. At that point, if you need to customize it, you can also use the `--eject` option to copy the framework for customization in your local application:
 
 ```
 bin/resolve en.account.onboarding.user_details.edit.header --eject --open

data/docs/namespacing.md

@@ -1,7 +1,7 @@
 # Namespacing in Bullet Train
 
 ## The `Account` Namespace for Controllers and Views
-Bullet Train comes preconfigured with an `Account` and controller and view namespace. This is the place where Super Scaffolding will, by default, put new resource views and controllers. The intention here is to ensure that in systems that have both authenticated resource workflows and public-facing resources, those two different facets of the application are served by separate resource views and controllers. (By default, public-facing resources would be in the `Public` namespace.)
+Bullet Train comes preconfigured with an `Account` namespace for controllers and views. This is the place where Super Scaffolding will, by default, put new resource views and controllers. The intention here is to ensure that in systems that have both authenticated resource workflows and public-facing resources, those two different facets of the application are served by separate resource views and controllers. (By default, public-facing resources would be in the `Public` namespace.)
 
 ## Alternative Authenticated Namespaces
 In Bullet Train applications with [multiple team types](/docs/teams.md), you may find it helpful to introduce additional controller and view namespaces to represent and organize user interfaces and experiences for certain team types that vary substantially from the `Account` namespace default. In Super Scaffolding, you can specify a namespace other than `Account` with the `--namespace` option, for example:

data/docs/onboarding.md

@@ -17,25 +17,25 @@ Each of the following files exist within their own respective Bullet Train packa
 
 ### Controllers
  - `ensure_onboarding_is_complete` in `bullet_train/app/controllers/account/application_controller.rb`
- - `bullet_train-base/app/controllers/account/onboarding/user_details_controller.rb`
- - `bullet_train-base/app/controllers/account/onboarding/user_email_controller.rb`
+ - `bullet_train-core/bullet_train/app/controllers/account/onboarding/user_details_controller.rb`
+ - `bullet_train-core/bullet_train/app/controllers/account/onboarding/user_email_controller.rb`
 
 ### Views
- - `bullet_train-base/app/views/account/onboarding/user_details/edit.html.erb`
- - `bullet_train-base/app/views/account/onboarding/user_email/edit.html.erb`
+ - `bullet_train-core/bullet_train/app/views/account/onboarding/user_details/edit.html.erb`
+ - `bullet_train-core/bullet_train/app/views/account/onboarding/user_email/edit.html.erb`
 
 ### Models
- - `user#details_provided?` in `bullet_train-base/app/models/concerns/users/base.rb`
+ - `user#details_provided?` in `bullet_train/app/models/concerns/users/base.rb`
 
 ### Routes
- - `namespace :onboarding` in `bullet_train-base/config/routes.rb` and `bullet_train/config/routes.rb`
+ - `namespace :onboarding` in `bullet_train-core/bullet_train/config/routes.rb` and `bullet_train/config/routes.rb`
 
 ## Adding Additional Steps
 Although you can implement onboarding steps from scratch, we always just copy and paste one of the existing steps as a starting point, like so:
 
-1. Copy, rename, and modify of the existing onboarding controllers.
+1. Copy, rename, and modify all of the existing onboarding controllers.
 2. Copy, rename, and modify the corresponding `edit.html.erb` view.
-3. Copy and rename the route entry in `bullet_train-base/config/routes.rb`.
+3. Copy and rename the route entry in `bullet_train-core/bullet_train/config/routes.rb`.
 4. Add the appropriate gating logic in `ensure_onboarding_is_complete` in `bullet_train/app/controllers/account/application_controller.rb`
 
 Onboarding steps aren't limited to targeting `User` models. It's possible to add onboarding steps to help flesh out team `Membership` records or `Team` records as well. You can use this pattern for setting up any sort of required data for either the user or the team.

data/docs/overriding.md

@@ -18,4 +18,4 @@ class User < ApplicationRecord
 end
 ```
 
-In this case, for most customizations or extensions you would want to make, you don't need to eject `Users::Core` into your local repository. Instead, you can simply re-define methods from that concern in your local `User` model after the inclusion of the concern.
+In this case, for most customizations or extensions you would want to make, you don't need to eject `Users::Base` into your local repository. Instead, you can simply re-define methods from that concern in your local `User` model after the inclusion of the concern.

data/docs/permissions.md

@@ -4,7 +4,7 @@
 Bullet Train leans heavily on [CanCanCan](https://github.com/CanCanCommunity/cancancan) for implementing authorization and permissions. (We’re also proud sponsors of its ongoing maintenance.) The original CanCan library by Ryan Bates was, in our opinion, a masterpiece and a software engineering marvel that has stood the test of time. It's truly a diamond among Ruby Gems. If you're not already familiar with CanCanCan, you should [read its documentation](https://github.com/CanCanCommunity/cancancan) to get familiar with its features and DSL.
 
 ## Bullet Train Roles
-Over many years of successfully implementing applications with CanCanCan, it became apparent to us that a supplemental level of abstraction could help streamline and simplify the definition of many common permissions, especially in large applications. We've since extracted this functionality into [a standalone Ruby Gem](https://github.com/bullet-train-co/bullet_train-roles) and moved the documentation that used to be here into [the README for that project](https://github.com/bullet-train-co/bullet_train-roles). Should you encounter situations where this abstraction doesn't meet your specific needs, you can always implement the permissions you need using standard CanCanCan directives in `app/models/ability.rb`.
+Over many years of successfully implementing applications with CanCanCan, it became apparent to us that a supplemental level of abstraction could help streamline and simplify the definition of many common permissions, especially in large applications. We've since extracted this functionality into [a standalone Ruby Gem](https://github.com/bullet-train-co/bullet_train-core/tree/main/bullet_train-roles) and moved the documentation that used to be here into [the README for that project](https://github.com/bullet-train-co/bullet_train-core/tree/main/bullet_train-roles). Should you encounter situations where this abstraction doesn't meet your specific needs, you can always implement the permissions you need using standard CanCanCan directives in `app/models/ability.rb`.
 
 ## Additional Notes
 

data/docs/seeds.md

@@ -29,7 +29,7 @@ end
 We do this so Bullet Train applications can re-use the logic in `db/seeds.rb` for three purposes:
 
 1. Set up new local development environments.
-2. Ensure the test suite has the same configuration for features whose configuration is backed by Active Record (e.g. [subscriptions](/docs/subscriptions.md) and [outgoing webhooks](/docs/webhooks/outgoing.md)).
+2. Ensure the test suite has the same configuration for features whose configuration is backed by Active Record (e.g. [outgoing webhooks](/docs/webhooks/outgoing.md)).
 3. Ensure any updates to the baseline configuration that have been tested both locally and in CI are the exact same updates being executed in production upon deploy.
 
 This makes `db/seeds.rb` a single source of truth for this sort of baseline data, instead of having this concern spread and sometimes duplicated across `db/seeds.rb`, `db/migrations/*`, and `test/fixtures`.

data/docs/testing.md

@@ -1,9 +1,10 @@
 # Automated Test Suite
 All of Bullet Train’s core functionality is verifiable using the provided test suite. This foundation of headless browser integration tests took a ton of time to write, but they can give you the confidence and peace of mind that you haven't broken any key functionality in your application before a deploy.
 
-You can run the test suite with the following command in your shell:
+You can run the test suite with the following commands in your shell:
 
 ```
+rails test
 rails test:system
 ```
 

data/docs/themes.md

@@ -1,6 +1,6 @@
 # Themes
 
-Bullet Train has a theme subsystem designed to allow you the flexibility to either extend or completely replace the stock “Light” UI template.
+Bullet Train has a theme subsystem designed to allow you the flexibility to either extend or completely replace the stock “Light” UI theme.
 To reduce duplication of code across themes, Bullet Train implements the following three packages:
 1. `bullet_train-themes`
 2. `bullet_train-themes-tailwind_css`
@@ -10,12 +10,16 @@ This is where all of Bullet Train's standard views are contained.
 
 ## Adding a New Theme (ejecting standard views)
 
-If you want to add a new theme, you can use the following command. This will copy all of the standard views from `bullet_train-themes-light` to `app/views/themes/` and configure your application to use the new theme. For example, let's make a new theme called "foo":
-`> rake bullet_train:themes:light:eject[foo]`
+If you want to add a new theme, you can use the following command. For example, let's make a new theme called "foo":
+```
+> rake bullet_train:themes:light:eject[foo]
+```
+
+This will copy all of the standard views from `bullet_train-themes-light` to `app/views/themes/` and configure your application to use the new theme.
 
 After running this command, you will see that a few other files are edited to use this new theme. Whenever switching a theme, you will need to make the same changes to make sure your application is running with the theme of your choice.
 
-You can also pass an annotated path to a view after running `bin/resolve` to eject individual views to your application.
+You can also pass an annotated path to a view after running `bin/resolve --interactive` to eject individual views to your application.
 
 ## Theme Component Usage
 
@@ -25,21 +29,24 @@ To use a theme component, simply include it from "within" `shared` like so:
 <%= render 'shared/fields/text_field', method: :text_field_value %>
 ```
 
-We say "within" because while a `shared` view partial directory does exist, the referenced `shared/fields/_text_field.html.erb` doesn't actually exist within it. Instead, the theme engine picks up on `shared` and also works its way through the theme directories to find the appropriate match.
+We say "within" because while a `shared` view partial directory does exist, the referenced `shared/fields/_text_field.html.erb` doesn't actually exist within it. Instead, the theme engine picks up on `shared` and then works its way through the theme directories to find the appropriate match.
 
 ### Dealing with Indirection
 
 This small piece of indirection buys us an incredible amount of power in building and extending themes, but as with any indirection, it could potentially come at the cost of developer experience. That's why Bullet Train includes additional tools for smoothing over this experience. Be sure to read the section on [dealing with indirection](./indirection.md).
 
-## Theme Configuration
+## Restoring Theme Configuration
 
-Your application will automatically be configured to use your new theme whenever you run the eject command. Run `> rake bullet_train:themes:light:install` to re-install the standard light theme.
+Your application will automatically be configured to use your new theme whenever you run the eject command. You can run the below command to re-install the standard light theme.
+```
+> rake bullet_train:themes:light:install
+``` 
 
 ## Additional Guidance and Principles
 
 ### Should you extend or replace?
 
-For most development projects, the likely best path for customizing the UI is to extend “Light” or another complete Bullet Train theme. It’s difficult to convey how many hours have gone into making the Bullet Train themes complete and coherent from end to end. Every type of field partial, all the third-party libraries, all the responsiveness scenarios, etc. It’s taken many hours and many invoices.
+For most development projects, the likely best path for customizing the UI is to extend “Light” or another complete Bullet Train theme. It’s difficult to convey how many hours have gone into making the Bullet Train themes complete and coherent from end to end. Every type of field partial, all the third-party libraries, all the responsiveness scenarios, etc. It has taken many hours of expert time.
 
 Extending an existing theme is like retaining an option on shipping. By extending a theme that is already complete, you allow yourself to say “enough is enough” at a certain point and just living with some inherited defaults in exchange for shipping your product sooner. You can always do more UI work later, but it doesn’t look unpolished now!
 
@@ -63,11 +70,11 @@ On the other hand, if you decide to try to build a theme from the ground up, you
 <% end %>
 ```
 
-This allows the theme engine to resolve which theme in the inheritance chain to include the `box` partial from. For example:
+This allows the theme engine to resolve which theme in the inheritance chain will include the `box` partial. For example:
 
- - It might come from the “Light” theme today, but if you switch to the “Bold” theme later, it’ll can start pulling it from there.
+ - It might come from the “Light” theme today, but if you switch to the “Bold” theme later, it’ll start pulling it from there.
  - If you start extending “Light”, you can override its `box` implementation and your application will pick up the new customized version from your theme automatically.
- - If (hypothetically) `box` became generalized and move into the parent “Tailwind CSS” theme, your application would pick it up from the appropriate place.
+ - If (hypothetically) `box` becomes generalized and moves into the parent “Tailwind CSS” theme, your application would pick it up from the appropriate place.
 
 ### Let your designer name their theme.