bible270 1.13.3 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md CHANGED
@@ -1,62 +1,39 @@
1
1
  # Bible 270
2
- [![Rails CI](https://github.com/avonderluft/bible270/actions/workflows/railsci.yml/badge.svg)](https://github.com/avonderluft/comfortable-media-surfer/actions/workflows/rubyonrails.yml) [![Test Coverage](https://img.shields.io/coverallsCoverage/github/avonderluft/bible270?branch=main&cacheSeconds=300)](https://coveralls.io/github/avonderluft/bible270?branch=main) [![Gem Version](https://img.shields.io/gem/v/bible270)](https://rubygems.org/gems/bible270) [![Downloads](https://img.shields.io/gem/dt/bible270)](https://rubygems.org/gems/bible270) [![GitHub Release Date - Published_At](https://img.shields.io/github/release-date/avonderluft/bible270?label=last%20release&color=seagreen)](https://github.com/avonderluft/bible270/releases)
3
2
 
4
- A mountable **Rails engine** that drops a 270-day (9 month) interactive Bible reading plan into any Rails app, built with [ComfyMiddleSeat](https://github.com/avonderluft/comfy-middle-seat) CMS in mind. Readers tick off each day's readings, post reflections, and see how everyone else is getting on, much like the social plans on Bible.com.
3
+ [![Rails CI](https://github.com/avonderluft/bible270/actions/workflows/railsci.yml/badge.svg)](https://github.com/avonderluft/bible270/actions/workflows/railsci.yml) [![Test Coverage](https://img.shields.io/coverallsCoverage/github/avonderluft/bible270?branch=main&cacheSeconds=300)](https://coveralls.io/github/avonderluft/bible270?branch=main) [![Gem Version](https://img.shields.io/gem/v/bible270)](https://rubygems.org/gems/bible270) [![Downloads](https://img.shields.io/gem/dt/bible270)](https://rubygems.org/gems/bible270) [![GitHub Release Date - Published_At](https://img.shields.io/github/release-date/avonderluft/bible270?label=last%20release&color=seagreen)](https://github.com/avonderluft/bible270/releases)
5
4
 
6
- Initially created for use by students and faculty of [Kingdom Movement School of Ministry](https://www.kmsm.life/), to read through all of Scripture together during the school year. Thus it is potentially useful for any Bible School, Seminary, or Discipleship school working on a 9 month schedule.
5
+ A mountable **Rails engine** for a 270-day (9-month) Bible reading plan. Readers check off readings, share reflections, and follow one another's progress.
7
6
 
8
- For a guided tour of the implementation, see the [architecture walkthrough](docs/architecture.md).
7
+ Created for [Kingdom Movement School of Ministry](https://www.kmsm.life/) and designed to work with [ComfyMiddleSeat](https://github.com/avonderluft/comfy-middle-seat) CMS, it also works in other Rails apps.
9
8
 
10
- ## The plan
11
-
12
- Three readings a day, sized by **verse count** so each day takes roughly the same time.
13
-
14
- - **Old Testament** — once through, with Psalms and Proverbs in their own track.
15
- - **New Testament** — once through, a reading every day. 260 chapters over 270 days, long chapters are divided to even out the daily reading
16
- - **Psalms & Proverbs** — once each, interleaved in one track. 181 chapters have to cover 270 days, so some are divided, shared between the two books by verse load. **A psalm of 25 verses or fewer is never divided**, keeping 131 of the 150 whole; longer psalms and Proverbs chapters break at their turns of thought (see `CHAPTER_BREAKS`). **Psalm 119 is 11 sections of 16 verses** — two of its eight-verse acrostic stanzas each. Proverbs lands on 89 days, near its proportional share. **A divided chapter is always read on consecutive days**, so nothing is inserted between the parts of a split psalm.
17
-
18
- Genesis → Malachi and Revelation 22 both land on day 270, as does the second part of Proverbs 31. Every day carries all three tracks. A typical day is ~119 verses (range 76–175).
19
-
20
- The schedule is pure deterministic Ruby (`Bible270::Plan`) — none of it is stored. Portions come from per-chapter verse counts in `Bible270::Versification`. The DB only holds readers, check-offs, comments, and sign-in tokens.
21
-
22
- ## Requirements
23
-
24
- - **Ruby** >= 3.2. Engine code is plain Ruby; avatar processing uses native libvips through `ruby-vips`. Runs on 4.0.6 — it avoids everything 4.0 dropped or unbundled (notably `cgi`; URL escaping uses `URI.encode_www_form_component`).
25
- - **Rails** >= 7.2. On Ruby 4.0 your host app is the real constraint, not this engine — check your lockfile with RailsBump first.
26
- - A host app, and Turbo if you want check-offs without a page reload.
27
- - For picture uploads and avatar backfills: **libvips** with PNG, JPEG, GIF and WebP support. The gem supplies the `image_processing` and `ruby-vips` Ruby dependencies. Install libvips on every upload/backfill host (for example, `sudo apt-get install libvips-tools` on Ubuntu or `sudo pacman -S libvips` on Arch). Native processing is loaded only when optimizing an image; existing pages and provider avatars do not require it.
9
+ See the [architecture walkthrough](docs/architecture.md) for implementation details and the [changelog](CHANGELOG.md) for release history.
28
10
 
29
- Mutation controls expose pending, success, and retry feedback when JavaScript runs, while ordinary HTML
30
- forms remain the fallback. Repeated checkoff and like requests converge on the intended state rather
31
- than accidentally reversing it.
32
-
33
- ## Avatar optimization
34
-
35
- Profile and Admin picture uploads produce a **256×256 static WebP thumbnail at quality 85** before switching the displayed avatar. Images are auto-oriented, center-cropped, converted to sRGB, and stripped of metadata; transparency is preserved. Animated GIF/WebP uploads use the first frame. Small images are upscaled to the same dimensions. Invalid or corrupt image data is rejected, even if its filename or declared type looks valid.
11
+ ## The plan
36
12
 
37
- Uploads are limited to **2 MiB by default** (`config.avatar_max_bytes`) and **40 million pixels** in the selected frame/container canvas. The pixel limit bounds dimensions, not total processor memory. A processing or storage failure leaves the previous picture and profile details unchanged.
13
+ Three tracks every day, balanced by **verse count**:
38
14
 
39
- The current original remains in the `avatar` attachment, including its original metadata; the display image is stored separately as `avatar_thumbnail`. This preserves the source for future reprocessing, not a history of past pictures. Removing/replacing a picture detaches the old pair; Active Storage's purge jobs clean up their files. Keep the host's Active Job worker running for that cleanup. Original retention increases storage use even though avatar downloads become smaller. No new database migration is needed if Active Storage is already installed.
15
+ - **Old Testament** — once through Genesis–Malachi, excluding Psalms and Proverbs.
16
+ - **New Testament** — once through, with longer chapters divided to fill 270 days.
17
+ - **Psalms & Proverbs** — once each, interleaved over days 1–269, then **Psalm 1 again on day 270**. Proverbs 31 finishes on day 269; Proverbs occupies 91 days.
40
18
 
41
- Existing uploaded avatars continue displaying their originals until optimized. Run the following **from the host Rails application**, with its normal database/storage credentials and production environment when appropriate:
19
+ By default, psalms of 25 verses or fewer stay whole. Longer chapters use selected breaks or balanced divisions; **Psalm 73 stays whole**, **Psalm 69 splits into verses 1–19 and 20–36**, and **Psalm 119 has eleven 16-verse readings** (two acrostic stanzas each). Parts of a divided chapter always fall on consecutive days. See [Tuning the plan](#tuning-the-plan) for overrides.
42
20
 
43
- ```sh
44
- # Metadata-only preview: no image downloads or attachment changes
45
- RAILS_ENV=production bundle exec rake bible270:avatars:optimize DRY_RUN=1
21
+ The Old Testament and Revelation 22 finish on day 270 alongside Psalm 1. Daily readings average about 115 verses (range 76–166).
46
22
 
47
- # Process existing uploaded reader avatars, sequentially in bounded batches
48
- RAILS_ENV=production bundle exec rake bible270:avatars:optimize BATCH_SIZE=100
23
+ `Bible270::Plan` generates the schedule deterministically from `Bible270::Versification`; the schedule is not stored in the database. **Progress and reflections are public.**
49
24
 
50
- # Rebuild even current thumbnails from the retained originals
51
- RAILS_ENV=production bundle exec rake bible270:avatars:optimize FORCE=1
52
- ```
25
+ ## Requirements
53
26
 
54
- The task skips current thumbnails, protects concurrent avatar changes, continues after per-image failures, and exits nonzero if any fail. It prints reader IDs, counts, and original/optimized display-byte totals (not total storage savings). Correct failed files, limits, storage access, or processor dependencies and rerun. `BATCH_SIZE` defaults to 100 and must be between 1 and 1000. Dry-run checks eligibility only; it does not verify file availability or decodability. Take a normal database/storage backup before a production backfill. The task reads originals and writes thumbnails to the configured storage service; remote storage can incur request and transfer costs. It does **not** download remote sign-in-provider avatars or modify unrelated host attachments.
27
+ - **Ruby >= 3.2** and a **Rails >= 7.2** host app. CI covers selected combinations through Ruby 4.0 / Rails 8.1; check your host's dependencies before upgrading Ruby.
28
+ - Turbo JavaScript for check-offs without a page reload. The gem includes `turbo-rails`; ordinary HTML forms remain available without JavaScript.
29
+ - For picture uploads and backfills: **Active Storage** and **libvips** with PNG, JPEG, GIF, and WebP support on every upload/backfill host. Install libvips with, for example, `sudo apt-get install libvips-tools` on Ubuntu or `sudo pacman -S libvips` on Arch. The gem supplies `image_processing` and `ruby-vips`; native processing loads only when optimizing an image, not when displaying existing or provider avatars.
55
30
 
56
- For host code that uploads reader pictures, use `reader.attach_avatar(upload)` or `Bible270::AvatarImages.update!(reader, attributes, upload: upload)` rather than attaching directly with Active Storage, which bypasses this processing pipeline. Uploads and backfills must run **outside a caller-owned database transaction**: the service owns the commit boundary so a later outer rollback cannot orphan already-uploaded files. Failed cleanup retains unattached blob records with their storage keys for retry; check logged blob IDs and include these in the host's unattached-blob maintenance.
31
+ JavaScript controls show pending, success, and retry feedback. Repeated check-off and like requests converge on the requested state rather than reversing it.
57
32
 
58
33
  ## Install
59
34
 
35
+ Run installation commands from the **host Rails application**.
36
+
60
37
  ```ruby
61
38
  # Gemfile
62
39
  gem "bible270"
@@ -65,9 +42,11 @@ gem "bible270"
65
42
  <details>
66
43
  <summary>Other sources</summary>
67
44
 
45
+ Use one of these instead:
46
+
68
47
  ```ruby
69
48
  gem "bible270", git: "https://github.com/avonderluft/bible270.git", branch: "main"
70
- gem "bible270", path: "<path_to_your_local_copy>/bible270" # local checkout
49
+ gem "bible270", path: "<path_to_your_local_copy>/bible270"
71
50
  ```
72
51
  </details>
73
52
 
@@ -76,22 +55,19 @@ bundle install
76
55
  bin/rails generate bible270:install
77
56
  ```
78
57
 
79
- That's the whole install. The generator is interactive and walks you through it:
58
+ The interactive generator:
80
59
 
81
- 1. asks where to mount the plan;
82
- 2. asks which sign-in methods you want — email link, OmniAuth, or both — and adds any OmniAuth strategy gems to your `Gemfile`;
83
- 3. Prompts to install ActiveStorage for user avatars
84
- 4. copies migrations into your `db/migrate` and offers to run them;
85
- 5. writes `config/initializers/bible270.rb` (and `omniauth.rb` if you chose social sign-in); and
86
- 6. adds `mount Bible270::Engine, at: Bible270.config.mount_at` to `config/routes.rb`.
60
+ 1. Chooses the mount path and email/OmniAuth sign-in methods.
61
+ 2. Adds known OmniAuth strategy gems and offers to bundle them.
62
+ 3. Offers to install Active Storage for avatars, copies migrations, and offers to run them.
63
+ 4. Writes `config/initializers/bible270.rb` and, for social sign-in, `omniauth.rb`.
64
+ 5. Adds `mount Bible270::Engine, at: Bible270.config.mount_at` to your routes.
87
65
 
88
- (Migrations run before the config is written, so a problem in a generated initializer can't block the database work.)
66
+ Defaults use `/daily-bread` with email and GitHub sign-in. **You must still configure mail delivery, provider credentials, and OAuth callback URLs** as listed by the generator. Migrations run before the initializers are written.
89
67
 
90
- Every prompt has a default, so holding Enter gives a working install at `/daily-bread` with email and GitHub sign-in. It finishes by listing what's left for you — provider credentials, callback URLs, mailer setup.
68
+ Copied migrations belong to your app. The engine does not also add its migration directory to your app's migration paths.
91
69
 
92
- The copied migrations are yours from then on, in your `schema.rb`. The engine doesn't add its own migration directory to your app's paths, so the copies are the only definitions in play.
93
-
94
- Non-interactive (CI, re-runs, scripted setup):
70
+ For non-interactive setup:
95
71
 
96
72
  ```bash
97
73
  bin/rails generate bible270:install --defaults \
@@ -101,32 +77,32 @@ bin/rails generate bible270:install --defaults \
101
77
 
102
78
  | Flag | Effect |
103
79
  |------|--------|
104
- | `--defaults` | Ask nothing, accept every default |
105
- | `--mount-at=PATH` | Where to mount (default `/daily-bread`) |
80
+ | `--defaults` | Skip prompts; use supplied options and defaults |
81
+ | `--mount-at=PATH` | Mount path (default `/daily-bread`) |
106
82
  | `--providers=a,b` | OmniAuth providers; `--providers=` for none |
107
- | `--email` / `--no-email` | Email sign-in on or off |
108
- | `--mailer-from=ADDR` | From: address for sign-in emails |
109
- | `--bundle` / `--no-bundle` | Run `bundle install` after adding strategy gems |
110
- | `--migrate` / `--no-migrate` | Run `db:migrate` at the end |
111
- | `--active-storage` / `--no-active-storage` | Install Active Storage if missing (for picture uploads) |
83
+ | `--email` / `--no-email` | Enable or disable email sign-in |
84
+ | `--mailer-from=ADDR` | From address for sign-in emails |
85
+ | `--bundle` / `--no-bundle` | Run or skip bundling added strategy gems |
86
+ | `--migrate` / `--no-migrate` | Run or skip migrations |
87
+ | `--active-storage` / `--no-active-storage` | Install or skip missing Active Storage tables |
112
88
 
113
- The installer is safe to re-run: it leaves an existing `mount` line alone, skips strategy gems already in your Gemfile, and Rails prompts before overwriting an initializer.
89
+ Re-running skips existing strategy gems and reuses the engine mount, moving it above catch-all routes if needed. Rails prompts before overwriting an initializer. If you skip bundling or migrations, complete them before using the affected features.
114
90
 
115
91
  <details>
116
- <summary>Doing it by hand instead</summary>
92
+ <summary>Manual installation</summary>
117
93
 
118
94
  ```ruby
119
95
  # config/initializers/bible270.rb
120
96
  Bible270.configure do |config|
121
- config.mount_at = "/daily-bread"
97
+ config.mount_at = "/daily-bread"
122
98
  config.email_sign_in = true
123
- config.mailer_from = "no-reply@example.com"
124
- config.omniauth_providers = [] # or [:github], plus an OmniAuth initializer
99
+ config.mailer_from = "no-reply@example.com"
100
+ config.omniauth_providers = [] # email only; see Authentication for OmniAuth
125
101
  end
126
102
  ```
127
103
 
128
104
  ```ruby
129
- # config/routes.rb
105
+ # config/routes.rb — before catch-all routes
130
106
  mount Bible270::Engine, at: Bible270.config.mount_at
131
107
  ```
132
108
 
@@ -135,114 +111,102 @@ bin/rails bible270:install:migrations
135
111
  bin/rails db:migrate
136
112
  ```
137
113
 
138
- See [Authentication](#authentication) for the OmniAuth initializer.
114
+ For picture uploads, also enable and install Active Storage if missing:
115
+
116
+ ```bash
117
+ bin/rails active_storage:install
118
+ bin/rails db:migrate
119
+ ```
120
+
121
+ Configure Action Mailer delivery and, if needed, [OmniAuth](#social-sign-in).
139
122
  </details>
140
123
 
141
124
  ### Upgrading
142
125
 
143
- No need to re-run the generator — just pick up any new migrations:
126
+ No generator re-run is needed:
144
127
 
145
128
  ```bash
146
129
  bundle update bible270
147
- bin/rails bible270:install:migrations # skips ones you already have
130
+ bin/rails bible270:install:migrations # skips existing copies
148
131
  bin/rails db:migrate
149
132
  ```
150
133
 
134
+ Review the [changelog](CHANGELOG.md) before deploying. Copy and run **all current migrations**, not just those for a feature you use; feature-specific migration notes appear below.
135
+
136
+ **Schedule changes do not remap existing day-based check-offs.** Compared with 1.13.3, the current default Psalms/Proverbs assignments differ on days 112–113 and 117–270, including the closing Psalm 1 reading. Review the effect on an active group before upgrading.
137
+
151
138
  ### Reconciling a copied database
152
139
 
153
- A copied database can contain the Bible270 tables while its `schema_migrations` versions do not match
154
- the timestamped migration copies in the local app. In that case, preview the reconciliation:
140
+ A copied database may already contain the tables but have migration versions that differ from your app's timestamped copies. Preview reconciliation first:
155
141
 
156
142
  ```bash
157
143
  bin/rails bible270:migrations:reconcile
158
144
  ```
159
145
 
160
- The task recognizes Bible270 migrations—and the related generated Active Storage migration used for
161
- reader avatars—by name, then verifies their tables, columns, current indexes, and foreign keys. It
162
- does not treat an existing table alone as sufficient. After reviewing the list and backing up the
163
- database, record only the migrations already reflected in the schema:
146
+ The task recognizes Bible270 migrations and the related generated Active Storage migration by name, then checks tables, columns, indexes, and foreign keys. An existing table alone is not sufficient. **Review the preview and back up the database** before applying:
164
147
 
165
148
  ```bash
166
149
  APPLY=1 bin/rails bible270:migrations:reconcile
167
150
  bin/rails db:migrate
168
151
  ```
169
152
 
170
- Preview mode never writes to the database. Apply mode only inserts verified local versions into
171
- `schema_migrations`; it does not create, remove, or alter application tables. Migrations whose changes
172
- are missing remain pending for the final `db:migrate` command.
153
+ Preview writes nothing. Apply only records verified local versions in `schema_migrations`; it does not alter application tables. Missing changes remain pending for `db:migrate`.
173
154
 
174
- ## Bible270 Mount point in your Rails app
155
+ ## Mount point
175
156
 
176
- The path lives in exactly **one** place, `config.mount_at`:
157
+ Set the path in one place:
177
158
 
178
159
  ```ruby
179
160
  # config/initializers/bible270.rb
180
161
  Bible270.configure do |config|
181
- config.mount_at = "/daily-bread" # or "/read270", "/manna", whatever you wish
162
+ config.mount_at = "/daily-bread"
182
163
  end
183
164
  ```
184
165
 
185
- Routes read it directly; OmniAuth reads `Bible270.config.auth_path_prefix` (just `"<mount_at>/auth"`). The engine builds its own sign-in links from `request.script_name` at runtime, so there's no third spot to update.
186
-
187
- Values are normalised — `"read270"`, `"/read270"`, `"/read270/"` all become `/read270`. Nested paths and mounting at `/` work too.
166
+ Routes use `mount_at`; OmniAuth uses `Bible270.config.auth_path_prefix` (`"<mount_at>/auth"`). Engine sign-in links use `request.script_name` at runtime. `"read270"`, `"/read270"`, and `"/read270/"` normalize to `/read270`; nested paths and `/` also work.
188
167
 
189
- Two things sit outside your app and still need doing by hand when you move it: the **OAuth callback URLs** in each provider's dashboard, and any **CMS links**.
168
+ When moving the mount, update **provider-dashboard OAuth callback URLs** and **CMS links** manually. Set `config.omniauth_path_prefix` only if OmniAuth needs a separate path.
190
169
 
191
- > **Load order matters.** `bible270.rb` has to be read before `omniauth.rb`, since the latter asks for `auth_path_prefix`. Rails loads initializers alphabetically so the default names work fine. If you rename either, keep that order — or set `mount_at` in `config/application.rb`, which loads before all initializers.
192
-
193
- Need OmniAuth somewhere unrelated? Set `config.omniauth_path_prefix` and it wins.
170
+ > **Load order matters:** `bible270.rb` must load before `omniauth.rb`. Rails' alphabetical initializer order handles these names. If you rename them, preserve that order or set `mount_at` in `config/application.rb`.
194
171
 
195
172
  ## Authentication
196
173
 
197
- Two ways in, so **nobody's shut out**:
198
-
199
- 1. **Email link** — type an address, get a one-time link, click it. No password, no third-party account. The default, and what makes this usable by people with no GitHub or Google login.
200
- 2. **Social sign-in** via OmniAuth — for people who'd rather.
201
-
202
- Either works alone: `omniauth_providers = []` for email-only, `email_sign_in = false` for social-only. Reading is always public; only ticking off and commenting need an account.
174
+ Use passwordless **email links**, **OmniAuth social sign-in**, or both. Set `omniauth_providers = []` for email-only or `email_sign_in = false` for social-only. Reading is public; participation requires a reader account by default.
203
175
 
204
176
  ### Email links
205
177
 
178
+ Configure working Action Mailer delivery and a permitted sender address:
179
+
206
180
  ```ruby
207
181
  Bible270.configure do |config|
208
182
  config.email_sign_in = true
209
- config.mailer_from = "no-reply@example.com"
183
+ config.mailer_from = "no-reply@example.com"
210
184
  config.email_sign_in_ask_name = true
211
- config.email_sign_in_require_name = true # first AND last name # let readers pick their display name
212
- # config.email_sign_in_ttl = 20 * 60 # link lifetime, seconds
213
- # config.email_sign_in_max_per_window = 5 # per address
185
+ config.email_sign_in_require_name = true # first and last name
186
+ # config.email_sign_in_ttl = 20 * 60 # link lifetime in seconds
187
+ # config.email_sign_in_max_per_window = 5 # requests per address
214
188
  # config.email_sign_in_window = 15 * 60
215
- # config.email_sign_in_deliver_later = true # needs Active Job
189
+ # config.email_sign_in_deliver_later = true # requires an Active Job worker
216
190
  end
217
191
  ```
218
192
 
219
- All it needs is working Action Mailer delivery.
220
-
221
- - Tokens: 256-bit, URL-safe, single-use, 20-minute expiry.
222
- - **Only a SHA-256 digest is stored** — no password column anywhere, so the table is useless to anyone reading your DB.
223
- - Claiming is a conditional update, so a double-clicked link still signs you in once.
224
- - "Check your inbox" reads the same whether the address was known, unknown, or rate-limited — no account enumeration.
225
- - Display name comes from the reader, else the address (`mary.anne.smith@…` → "Mary Anne Smith").
226
- - `Bible270::SignInToken.sweep!` clears spent tokens. Good cron fodder.
227
-
228
- Email readers get `provider: "email"` in the same columns OmniAuth uses, so everything downstream treats them identically.
193
+ - Tokens are 256-bit, URL-safe, single-use, and expire after 20 minutes by default. Conditional updates prevent double claims.
194
+ - Only a **SHA-256 token digest** is stored, not the raw token or a password. Token records still contain personal data such as email addresses.
195
+ - Valid-address requests receive the same “Check your inbox” response whether known, unknown, or rate-limited, avoiding disclosure through that message.
196
+ - Names come from the reader, falling back to the email address (`mary.anne.smith@…` → “Mary Anne Smith”). Email readers use `provider: "email"` in the same identity model as OmniAuth readers.
197
+ - Schedule `Bible270::SignInToken.sweep!` to remove expired or consumed records older than seven days by default.
229
198
 
230
199
  ### Social sign-in
231
200
 
232
- `bin/rails generate bible270:install` sets this up: it adds the strategy gem to your `Gemfile`
233
- (`omniauth` and `omniauth-rails_csrf_protection` already ride along with bible270), writes the
234
- OmniAuth initializer, and prints the callback URL to register with each provider — for example
235
- `https://example.com/daily-bread/auth/github/callback`.
201
+ The installer adds known strategy gems, writes the initializer, and prints callback URLs to register, such as `https://example.com/daily-bread/auth/github/callback`. The gem already includes `omniauth` and `omniauth-rails_csrf_protection`.
236
202
 
237
- Adding a provider later, or wiring it up yourself? Add its strategy gem, list it in `config.omniauth_providers`, and register it with OmniAuth. The one thing to get right is lining up `path_prefix` with the mount point:
203
+ To add a provider manually, install its strategy gem, list it in `config.omniauth_providers`, and register it with OmniAuth:
238
204
 
239
205
  ```ruby
240
206
  # config/initializers/omniauth.rb
241
207
  Rails.application.config.middleware.use OmniAuth::Builder do
242
- # `options` is merged into every provider declared after it, so it comes first.
243
- # OmniAuth::Builder has no path_prefix method — this is the scoped equivalent.
208
+ # Applies to providers declared below; Builder has no path_prefix method.
244
209
  options path_prefix: Bible270.config.auth_path_prefix
245
-
246
210
  provider :github, ENV["GITHUB_CLIENT_ID"], ENV["GITHUB_CLIENT_SECRET"]
247
211
  end
248
212
 
@@ -252,23 +216,19 @@ OmniAuth.config.on_failure = proc { |env| Bible270::SessionsController.action(:f
252
216
  ```ruby
253
217
  # config/initializers/bible270.rb
254
218
  Bible270.configure do |config|
255
- config.mount_at = "/daily-bread"
256
- config.omniauth_providers = [:github] # or [:github, [:google_oauth2, "Google"]]
257
- config.parent_controller = "::ApplicationController"
219
+ config.mount_at = "/daily-bread"
220
+ config.omniauth_providers = [:github] # or [:github, [:google_oauth2, "Google"]]
221
+ config.parent_controller = "::ApplicationController"
258
222
  end
259
223
  ```
260
224
 
261
- Worth knowing:
225
+ **Sign-in must POST with a CSRF token** to `<mount>/auth/:provider`. The engine uses `button_to`; do the same for custom controls. OmniAuth 2 rejects GET sign-in to address [CVE-2015-9284](https://nvd.nist.gov/vuln/detail/CVE-2015-9284).
262
226
 
263
- - **Sign-in is a POST.** OmniAuth 2.0+ refuses GET ([CVE-2015-9284](https://nvd.nist.gov/vuln/detail/CVE-2015-9284)), so the engine's controls are `button_to` forms with CSRF tokens. Build your own and it must POST to `<mount>/auth/:provider`.
264
- - One provider → a button in the header. Several → a sign-in page at `<mount>/sign_in`.
265
- - Sign-in carries the current path as `origin`, so clicking a check-off while signed out brings you back to that day. Origins must be local paths.
266
- - `reset_session` on sign-in and sign-out, against session fixation.
267
- - Stored: provider, uid, display name, email, avatar URL. No tokens, no passwords.
227
+ The engine accepts only local return paths and resets the session on sign-in and sign-out to prevent session fixation. It stores provider, uid, name, email, and avatar URL, not OAuth access tokens or passwords.
268
228
 
269
- ### Or use your own users
229
+ ### Use your own users
270
230
 
271
- Already have auth? Hand the engine a resolver and it'll never touch sessions:
231
+ Set a resolver to use host authentication instead of the engine's reader-session lookup:
272
232
 
273
233
  ```ruby
274
234
  config.current_reader_resolver = lambda do |controller|
@@ -279,14 +239,11 @@ config.current_reader_resolver = lambda do |controller|
279
239
  end
280
240
  ```
281
241
 
282
- `Reader.for_owner` links to any host model polymorphically. Heads up: CMS admin auth is separate from public visitors, so for a public plan the email/OmniAuth route above is usually what you want.
242
+ `Reader.for_owner` links any host model polymorphically. CMS administrator authentication is separate from public-reader authentication; email or OmniAuth is usually simpler for public visitors.
283
243
 
284
244
  ## Admin panel
285
245
 
286
- At `<mount>/admin`: sort readers by first name, last name, completed days, recent activity, or **Consistency ranking**; open **Reader Stats** for
287
- the same progress report as `bible270:readers:list`, ordered by the current admin sort selection; remove
288
- readers; adjust their completions; and move them to a given day. The panel is unreachable — every route
289
- 404s rather than 403s — unless you say who may use it:
246
+ The panel at `<mount>/admin` returns **404** unless you explicitly authorize administrators:
290
247
 
291
248
  ```ruby
292
249
  config.admin_emails = %w[andrew@example.org]
@@ -294,85 +251,54 @@ config.admin_emails = %w[andrew@example.org]
294
251
  config.admin_resolver = ->(reader) { reader.email.to_s.end_with?('@example.org') }
295
252
  ```
296
253
 
297
- **Consistency ranking** measures recorded schedule performance over completed evenings, not just today's progress. Each evening scores `100 + 5 × min(days ahead, 7) − 10 × days behind`; the ranking uses the average. A score of 100 means an average on-track baseline, not 100%. Being behind can produce negative scores.
254
+ Authorized readers get an Admin link. **View as non-admin** hides admin-only details and disables admin actions for the current session. You stay signed in as yourself; your check-offs and reflections still work. The Admin tab remains available with **Return to admin view**. This does not change roles or affect other sessions, and signing in again restores admin view.
298
255
 
299
- The evaluation starts on the later of the reader's effective plan start and account-creation date, and stops at the earlier of yesterday and the scheduled plan end, using the plan's time zone. Late enrollment shortens the evaluation window without resetting the scheduled day. A plan day counts only after all required readings are checked off; its completion time is the latest of those check-offs. Ahead-of-schedule completions carry forward, while today's catch-up does not rewrite prior evenings.
256
+ The panel supports:
300
257
 
301
- Readers with at least seven evaluated evenings rank first, followed by **Provisional** readers with one to six, then **Not ranked** readers without an eligible evening on a dated schedule. Within each ranked group, ties use the percentage of evenings on track/ahead, then the number of evaluated days, name, and ID. Sorting uses unrounded values. The selected sort displays each reader's score, on-track/ahead percentage, and evaluation length, and adds a leftmost **Rank** column to Reader Stats (a dash means unranked). Readers with the same ranking group, exact score, on-track/ahead percentage, and evaluation length share a competition rank, such as `1, 1, 1, 4`; names and IDs only order those ties. Other sorts do not calculate this history.
258
+ - Sorting readers by name, completed days, activity, or consistency, with **Reader Stats** following the selected sort.
259
+ - Changing reader profiles, themes, and notification preferences. Another reader's theme does not change your own.
260
+ - Moving a reader to a day by adjusting their start date; check-offs remain tied to day numbers.
261
+ - Setting progress exactly through day N, **clearing completions after N**, or toggling individual days.
262
+ - Removing a reader **and all their check-offs and reflections**.
263
+ - Moderating reflections at `<mount>/admin/comments`: hide reversibly or delete. Reflections are public immediately, without prior approval.
264
+ - Sending individually addressed broadcasts to all readers with email addresses or only administrators.
302
265
 
303
- This is reconstructed history, not an immutable audit: unchecked/rechecked readings, admin bulk progress changes, and start-date changes can alter scores. Existing check-off timestamps record when completion was entered, not necessarily when reading actually occurred. No additional migration or daily snapshot job is required.
266
+ To print a progress report ordered by completed days:
304
267
 
305
- Admins get an extra "Admin" link in the header. The broadcast form can send an individually addressed
306
- message either to every reader with an email address or only to readers recognized as administrators.
307
- From a reader's page you can:
268
+ ```bash
269
+ docker compose exec -e RAILS_ENV=production rails bin/rails bible270:readers:list
270
+ ```
308
271
 
309
- - **set their theme** — Papyrus (Light), Meadow (Light), Ocean (Light), Cedar (Dark),
310
- Forest (Dark), Moonlight (Dark), or System, independently of your own theme;
272
+ The report shows completed days, last activity, and calendar status: on track, ahead, behind, or undated.
311
273
 
312
- - **move them to a day** — "put them on day 42 as of today" back-dates the start date; check-offs are
313
- keyed to day numbers, so nothing in their history moves;
314
- - **set their progress** — mark complete through day N (this also clears anything after, so it sets
315
- progress exactly), or click days in the grid to toggle them;
316
- - **remove them**, with every check-off and reflection they've written;
317
- - **moderate reflections** at `<mount>/admin/comments`. Reflections are visible the moment they're
318
- written; hiding one takes it off the day and community pages without deleting it, and is
319
- reversible. Delete is there too, for anything that shouldn't be kept.
274
+ ### Consistency ranking
320
275
 
321
- The Reflections page lists conversations by their latest approved reply, supports day and author
322
- filters, and paginates older threads. Signed-in readers see which conversations became active since
323
- their previous visit. Reflection and reply drafts are retained for up to 30 days in that browser and
324
- cleared after a successful post. If browser storage is blocked or full, the composer warns that the draft
325
- could not be saved; posting still works. On a shared device, clearing browser storage also removes saved drafts.
326
- Typing `@` in the composer offers up to five unambiguous reader handles; manual mentions continue to
327
- work without JavaScript. A quiet **Formatting** disclosure opens a toolbar for bold, italic,
328
- quotations, bulleted and numbered lists, links, and YouTube videos without requiring readers to know Markdown syntax.
329
- A separate **Preview** control checks the current draft through the same server-side sanitizer used
330
- after posting; formatting tools stay out of sight until requested. The source remains
331
- editable in the ordinary textarea, drafts preserve its format, and all rendered HTML is restricted to that small safe
332
- set. Existing reflections remain literal plain text until a reader intentionally formats or converts
333
- them. Upgrading hosts must copy and run migration `20260101000021`, which records whether each body is
334
- plain text or Markdown; until then, the composer safely falls back to plain text.
276
+ Consistency is the average end-of-day score on a dated schedule:
335
277
 
336
- The **Video** button accepts YouTube watch, share (`youtu.be`), Shorts, live, and embed URLs,
337
- then asks for an optional video name. Leave it blank for **View video**, or name it to show
338
- **View video ‘Name’**. The name is stored as the link text and is also used in notification emails.
339
- It inserts an explicit Markdown link on its own paragraph, for example:
278
+ `100 + 5 × min(days ahead, 7) − 10 × days behind`
340
279
 
341
- ```markdown
342
- [YouTube video](https://www.youtube.com/watch?v=aB3_dE-fG12 "bible270-video")
343
- ```
280
+ A score of 100 is an average on-track baseline, not a percentage. Negative scores display as `0` but retain their true value for ranking. Scores, on-track/ahead percentages, and evaluated-day counts appear for every Admin sort; sorting by consistency also shows the scoring explanation and adds a **Rank** column to Reader Stats.
344
281
 
345
- Preview and posted reflections/replies show a small **View video** card. No YouTube player or remote
346
- thumbnail is requested until the reader loads the video; the player uses `www.youtube-nocookie.com`
347
- and does not autoplay. Loading it shares the reader's IP address and request metadata with YouTube;
348
- privacy-enhanced mode does not make playback anonymous. The button tooltip reads “Loads player and
349
- shares data with YouTube”; the link tooltip reads “Opens YouTube in a new tab.” An **Open on YouTube** link opens in a new
350
- tab/window with `rel="nofollow ugc noopener"`, and remains available when JavaScript is disabled or
351
- the provider disallows embedding. Notification emails retain ordinary
352
- links, and unmarked links never become players automatically. Only validated YouTube URLs become
353
- cards; unsupported marked links remain links. No uploads, API keys, extra gems, or database migrations
354
- are needed for this feature. Shared links' start times and playlist parameters are not retained.
355
-
356
- Hosts using Content Security Policy must add `https://www.youtube-nocookie.com` to their existing
357
- `frame-src` directive. Do not replace the rest of the host's policy or broadly allow arbitrary frames.
358
- Hosts with a custom engine layout should also render `bible270/shared/video_embeds` once, alongside the
359
- other shared scripts, to enable click-to-load playback.
360
-
361
- When `config.mention_notifications` is enabled, each reader can request email for every new reflection
362
- and reply, only replies to their reflections and mentions of them, or none. Broad notifications are sent
363
- once with eligible subscribers in BCC; direct reply and mention notices remain individually addressed.
364
- Administrators can change the same preference from the reader's Admin page. Migration
365
- `20260101000018` adds the broad opt-in without changing any existing reader's choice, while migration
366
- `20260101000022` makes that broad option the default for readers created afterward. Migration
367
- `20260101000017` stores each reader's last visit to the Reflections page. After upgrading, install and
368
- run the current migrations:
282
+ - Evaluation runs from the later of plan start or account creation through the earlier of yesterday or plan end, in the plan's time zone. Late enrollment does not reset the scheduled day.
283
+ - A day counts when all required readings are checked off, using the latest check-off timestamp. Early completions carry forward; today's catch-up does not improve previous evenings.
284
+ - Readers with seven or more evaluated evenings rank first, then **Provisional** readers with one to six, then **Not ranked** readers with none.
285
+ - Within each ranked group, ordering uses unrounded score, on-track/ahead percentage, and evaluated days. Equal metrics share competition ranks (`1, 1, 1, 4`); name and ID order ties. Unranked readers show a dash.
369
286
 
370
- ```bash
371
- bin/rails bible270:install:migrations
372
- bin/rails db:migrate
373
- ```
287
+ This is **reconstructed history, not an audit log**. Rechecking readings, bulk progress edits, or start-date changes can alter scores. Timestamps record when completion was entered, not necessarily when reading occurred. No snapshot job or additional migration is required.
374
288
 
375
- To change every existing reader to **Every new reflection and reply**, run:
289
+ ## Reflections and notifications
290
+
291
+ The Reflections page groups conversations by their latest approved reply, with day/author filters, pagination, and activity indicators since the reader's previous visit.
292
+
293
+ Drafts stay in the current browser for up to **30 days** and clear after a successful post. If storage is blocked or full, a warning appears but posting still works. On shared devices, clear browser storage to remove saved drafts.
294
+
295
+ Typing `@` offers up to five unambiguous reader handles; manual mentions work without JavaScript. **Formatting** opens tools for bold, italic, quotations, lists, links, and YouTube videos. **Preview** uses the same server-side sanitizer as posted content. Existing reflections remain literal plain text until deliberately converted; without the `body_format` migration (`20260101000021`), the composer falls back to plain text.
296
+
297
+ When `config.mention_notifications` is enabled, readers can choose email for every new reflection/reply, only direct replies and mentions, or none. Admins can change the same preference. Broad notices use BCC; direct notices are individually addressed.
298
+
299
+ Migration `20260101000018` adds broad notifications without changing existing choices; `20260101000022` makes them the default for new readers only. Follow [Upgrading](#upgrading) to install these and the visit-tracking migration (`20260101000017`).
300
+
301
+ To **override every existing reader's preference** with “Every new reflection and reply”:
376
302
 
377
303
  ```bash
378
304
  bin/rails bible270:notifications:enable_all
@@ -384,340 +310,325 @@ With Docker Compose:
384
310
  docker compose exec -e RAILS_ENV=production rails bin/rails bible270:notifications:enable_all
385
311
  ```
386
312
 
387
- To print an aligned progress report ordered by completed days, run:
313
+ ### YouTube videos
388
314
 
389
- ```bash
390
- docker compose exec -e RAILS_ENV=production rails bin/rails bible270:readers:list
391
- ```
392
-
393
- The report compares completed days with the calendar day implied by each reader's effective start date
394
- and shows `on track`, days ahead or behind, or `undated` when no calendar applies.
315
+ The **Video** button accepts YouTube watch, share (`youtu.be`), Shorts, live, and embed URLs, plus an optional name. It inserts a marked Markdown link in its own paragraph:
395
316
 
396
- Break points can also live in your app rather than the gem, and be changed without a restart:
397
-
398
- ```ruby
399
- config.chapter_breaks = { 'Psalm 78' => [20, 39, 55] }
400
- config.chapter_breaks_path = Rails.root.join('config/bible270_breaks.yml')
317
+ ```markdown
318
+ [YouTube video](https://www.youtube.com/watch?v=aB3_dE-fG12 "bible270-video")
401
319
  ```
402
320
 
403
- ```yaml
404
- # config/bible270_breaks.yml — re-read whenever it changes
405
- Psalm 35: []
406
- Psalm 78: [20, 39, 55]
407
- ```
321
+ Preview and posted content show **View video**, or **View video ‘Name’**. No remote thumbnail or player loads until the reader requests playback. The player uses `www.youtube-nocookie.com` without autoplay; **loading it shares the reader's IP address and request metadata with YouTube**. Privacy-enhanced mode is not anonymous playback.
408
322
 
409
- ## Theme
323
+ An **Open on YouTube** link remains available without JavaScript or when embedding is blocked. It opens a new tab with `rel="nofollow ugc noopener"`. Notification emails use ordinary links and preserve the optional name. Unmarked or unsupported links stay links; start times and playlist parameters are not retained. No API key, upload support, extra gem, or additional migration is needed.
410
324
 
411
- Readers can choose **Papyrus (Light)**, **Meadow (Light)**, **Ocean (Light)**, **Cedar (Dark)**,
412
- **Forest (Dark)**, **Moonlight (Dark)**, or **System** under **Profile → Theme**. Signed-in readers can also use
413
- the compact selector beside the app title on every page; it shows the short theme names without Light/Dark suffixes.
414
- Selecting a theme saves and applies it immediately without submitting other profile edits. The header and Profile
415
- selectors stay synchronized, and a failed save restores the previous selection and displays an error.
416
- Admin theme selections also save automatically;
417
- changing another reader's theme does not change the admin's own theme. With JavaScript disabled, use Save.
418
- The preference is stored
419
- with their account and applies throughout Bible270 on every device. System is the default for existing
420
- and new readers, follows the device's current appearance using Papyrus for light or Cedar for dark,
421
- and responds to changes without reloading. Signed-out visitors also use System.
422
- The completion dove retains its bright colors in every theme.
325
+ For a host Content Security Policy, add `https://www.youtube-nocookie.com` to the existing **`frame-src`** directive. Do not replace the policy or allow arbitrary frames. Custom engine layouts must also render `bible270/shared/video_embeds` once alongside the other shared scripts.
423
326
 
424
- Existing preferences and persisted values are unchanged under the new names. Meadow, Ocean, Cedar, Forest, and Moonlight
425
- require no additional migration once display preferences are installed.
327
+ ## Themes
426
328
 
427
- Upgrading hosts must install and run migration `20260101000023`:
329
+ Choose **Papyrus**, **Meadow**, or **Ocean** for light themes; **Cedar**, **Forest**, or **Moonlight** for dark themes; or **System** to follow the device (Papyrus/Cedar). System is the default for visitors and new readers.
428
330
 
429
- ```bash
430
- bin/rails bible270:install:migrations
431
- bin/rails db:migrate
432
- ```
331
+ Signed-in readers can choose a theme beside the app title or under **Profile → Theme**. Header, Profile, and Admin selections save immediately with JavaScript; without it, use Save. Older installations need migration `20260101000023`; see [Upgrading](#upgrading).
433
332
 
434
- Custom engine layouts must render the shared styles and set `data-display-mode` on the
435
- `.b270` element to `current_reader&.effective_display_mode || 'system'` to honor the preference.
333
+ ![Papyrus](images/papyrus.png "Papyrus")
334
+ ![Meadow](images/meadow.png "Meadow")
335
+ ![Ocean](images/ocean.png "Ocean")
336
+ ![Cedar](images/cedar.png "Cedar")
337
+ ![Forest](images/forest.png "Forest")
338
+ ![Moonlight](images/moonlight.png "Moonlight")
339
+
340
+ Custom layouts must render the shared styles and set the `.b270` element's `data-display-mode` to `current_reader&.effective_display_mode || 'system'`.
436
341
 
437
342
  ## Start dates
438
343
 
439
- The plan runs **undated** (day numbers only) or **dated** (days mapped onto a calendar):
344
+ The plan can be **undated** (day numbers only) or **dated**:
440
345
 
441
346
  ```ruby
442
- config.start_date = Date.new(2026, 9, 6) # Date, Time, or "YYYY-MM-DD". nil = undated
443
- config.allow_reader_start_date = true # allow personal per-reader calendars
347
+ config.start_date = Date.new(2026, 9, 6) # Date, Time, or "YYYY-MM-DD"; nil = no shared date
348
+ config.allow_reader_start_date = true
444
349
  ```
445
350
 
446
- | `start_date` | `allow_reader_start_date` | What happens |
351
+ | `start_date` | `allow_reader_start_date` | Behavior |
447
352
  |---|---|---|
448
- | nil | true *(default)* | Each reader gets stamped on their first check-off; an admin may adjust the date |
449
- | a date | true | The community date is the default; an admin may assign an individual date |
450
- | a date | false | Everyone is pinned to the community date; stored individual dates are ignored |
451
- | nil | false | Fully undated — no calendar anywhere |
353
+ | nil | true *(default)* | Personal start date set on first check-off; admins can adjust it |
354
+ | a date | true | Shared date unless an admin assigns a personal date |
355
+ | a date | false | Shared date for everyone; stored personal dates ignored |
356
+ | nil | false | Fully undated |
452
357
 
453
- Dated plans show each day's date with a **Today** badge and a "Go to today" link. `config.start_date` is the deploy-time default; an administrator may override the current run's shared date from the Admin panel without a deploy, or reset it to the configured value. The shared-date change immediately re-maps calendar dates, **Today**, and reminders for readers following the shared calendar. Administrators may also re-map an individual reader's calendar. Check-offs and reflections remain keyed to day numbers, so nothing in their history moves.
358
+ Dated plans show dates, a **Today** badge, and a “Go to today” link. Admins can override the shared `config.start_date` without deploying, or reset it to the configured value. Shared-date changes immediately remap dates, Today, and reminders for readers on that calendar. Personal calendars can also be adjusted. **Check-offs and reflections stay tied to day numbers.**
454
359
 
455
- Date helpers are pure functions, usable anywhere:
360
+ Date helpers work without Rails:
456
361
 
457
362
  ```ruby
458
363
  Bible270::Plan.date_for(1, "2026-09-06") # => Sun, 06 Sep 2026
459
364
  Bible270::Plan.end_date_for("2026-09-06") # => Wed, 02 Jun 2027 (day 270)
460
- Bible270::Plan.day_for(Date.current, start) # => 42 (clamped 1..270)
461
- Bible270::Plan.day_for(date, start, clamp: false) # => -3 or 271, to spot out-of-range
365
+ Bible270::Plan.day_for(Date.current, start) # clamped to 1..270
366
+ Bible270::Plan.day_for(date, start, clamp: false) # may return -3 or 271
462
367
  Bible270::Plan.before_start?(date, start)
463
368
  ```
464
369
 
465
370
  ## Daily reading reminders
466
371
 
467
- Daily reminders are optional at both levels: the host enables the feature, then each reader chooses
468
- whether to receive it and at what local time from their profile. The feature and reader opt-in both
469
- default to off; each reader's time defaults to `08:00`. Profile times use quarter-hour choices so they
470
- match the recommended 15-minute scheduler interval. An existing off-quarter preference remains
471
- available until that reader chooses a new time. The profile shows the plan's effective time zone beside
472
- the reminder settings; this is not automatically the reader's device time zone.
372
+ Reminders require both host enablement and reader opt-in; both default to off. Readers choose a time in Profile (default `08:00`, quarter-hour choices). Existing off-quarter times remain available until changed. Times use the **plan's time zone**, shown in Profile, not the device's zone.
473
373
 
474
374
  ```ruby
475
375
  # config/initializers/bible270.rb
476
376
  Bible270.configure do |config|
477
377
  config.daily_reminders = true
478
378
  config.mailer_from = "no-reply@yourdomain.com"
479
- config.mailer_host = "yourdomain.com" # builds links back to the day and profile
379
+ config.mailer_host = "yourdomain.com" # day/profile links
380
+ # config.time_zone = "America/Los_Angeles" # nil follows the server's clock
480
381
  end
481
382
  ```
482
383
 
483
- After upgrading, copy and run migration `20260101000016`, which adds the reader opt-in, preferred
484
- time, and last-sent date. Bible270 does not install a scheduler. The host application should run this
485
- task periodically—every 15 minutes is recommended—using its existing cron, platform scheduler, or
486
- recurring-job system:
384
+ Install the reminder migration (`20260101000016`) via [Upgrading](#upgrading). Bible270 does **not** install a scheduler. Run this task every 15 minutes using your host's cron, platform scheduler, or recurring-job system:
487
385
 
488
386
  ```bash
489
387
  bin/rails bible270:reminders:send
490
388
  ```
491
389
 
492
- For a host cron job, open the crontab with `crontab -e` under the same account that runs the application
493
- and add a line like this, using the absolute application path:
390
+ For cron, run `crontab -e` as the application account and use absolute paths:
494
391
 
495
392
  ```cron
496
393
  */15 * * * * cd /absolute/path/to/application && RAILS_ENV=production bin/rails bible270:reminders:send >> /absolute/path/to/application/log/bible270-reminders.log 2>&1
497
394
  ```
498
395
 
499
- For Docker Compose, run `pwd` in the directory containing the Compose file and `command -v docker` to
500
- find the two absolute paths, then use the same host account that can run Docker:
396
+ For Docker Compose, use `pwd` in the Compose directory and `command -v docker` to find the paths. Run cron as an account with Docker access:
501
397
 
502
398
  ```cron
503
399
  */15 * * * * cd /absolute/path/to/application && /usr/bin/docker compose exec -T rails bin/rails bible270:reminders:send >> /absolute/path/to/application/log/bible270-reminders.log 2>&1
504
400
  ```
505
401
 
506
- The `-T` is required because cron has no interactive terminal. Confirm the saved entry with `crontab -l`
507
- and check `log/bible270-reminders.log` after the next interval. Run one scheduler per database; several
508
- web containers sharing a database must not each run the task.
402
+ `-T` disables the interactive terminal that cron cannot provide. Verify with `crontab -l` and check the log after the next interval. **Run one scheduler per database**, not one per web container.
403
+
404
+ The task sends inline with `deliver_now` on the first run at or after the chosen local time and records the sent date only after successful delivery. It skips readers already sent that date, undated or out-of-range calendars, completed days, blank email addresses, and readers not opted in. Individual failures are logged without stopping other deliveries; each run prints the delivered count.
405
+
406
+ ## Avatar optimization
407
+
408
+ Profile and Admin uploads produce a **256×256 static WebP at quality 85**: auto-oriented, center-cropped, converted to sRGB, and stripped of thumbnail metadata. Transparency is preserved; animations use the first frame and small images are upscaled. Actual image data is validated, regardless of filename or declared type.
409
+
410
+ Limits are **2 MiB** by default (`config.avatar_max_bytes`) and **40 million pixels** in the selected frame/container canvas. The pixel limit bounds dimensions, not total processor memory. Processing or storage failure leaves the previous picture and profile details unchanged.
411
+
412
+ The current original, **including its metadata**, remains in `avatar`; the display image is stored as `avatar_thumbnail`. This retains a source for reprocessing, not a picture history, and increases storage even though downloads shrink. Removing or replacing a picture detaches the old pair; **keep Active Job workers running** for Active Storage purge jobs. No new migration is needed if Active Storage is already installed.
413
+
414
+ ### Backfill existing uploads
415
+
416
+ Existing uploads display their originals until optimized. Run from the **host Rails app** with its normal database/storage credentials and the appropriate environment. Back up the database and storage before a production backfill.
417
+
418
+ ```sh
419
+ # Metadata-only preview: no downloads or attachment changes
420
+ RAILS_ENV=production bundle exec rake bible270:avatars:optimize DRY_RUN=1
421
+
422
+ # Process sequentially in bounded batches
423
+ RAILS_ENV=production bundle exec rake bible270:avatars:optimize BATCH_SIZE=100
424
+
425
+ # Rebuild current thumbnails from retained originals
426
+ RAILS_ENV=production bundle exec rake bible270:avatars:optimize FORCE=1
427
+ ```
428
+
429
+ - Skips current thumbnails, protects concurrent avatar changes, continues after individual failures, and exits nonzero if any fail. Correct failed files, limits, storage access, or processor dependencies, then rerun.
430
+ - Reports reader IDs, counts, and original/optimized **display-byte totals**, not total storage savings.
431
+ - `BATCH_SIZE` defaults to 100 (allowed: 1–1000). Dry-run checks eligibility only, not file availability or decodability.
432
+ - Reads originals and writes thumbnails to configured storage; remote storage may incur request/transfer costs. It does not fetch provider avatars or change unrelated host attachments.
509
433
 
510
- Each run converts `Time.now` through `Bible270.local_time`, waits until the first scheduler run at or
511
- after each reader's chosen time, sends inline with `deliver_now`, and prints the number delivered. Set
512
- `config.time_zone` when the plan should not follow the server's local clock. Running periodically is
513
- idempotent once per local date: readers already marked for that date are skipped. Undated readers,
514
- calendar dates before or after their plan, completed days, blank email addresses, and readers who have
515
- not opted in are also skipped. A failure for one reader is logged and does not stop the rest. The sent
516
- date is recorded only after delivery succeeds.
434
+ Host upload code should use `reader.attach_avatar(upload)` or `Bible270::AvatarImages.update!(reader, attributes, upload: upload)`. Direct Active Storage attachment bypasses optimization. **Uploads and backfills must run outside caller-owned database transactions**: the service owns the commit boundary to prevent outer rollbacks from orphaning uploaded files. Failed cleanup retains unattached blob records and storage keys for retry; use logged blob IDs in your host's unattached-blob maintenance.
517
435
 
518
436
  ## Configuration reference
519
437
 
438
+ Common settings (example sender and host values must be replaced):
439
+
520
440
  ```ruby
521
441
  Bible270.configure do |config|
522
- config.mount_at = "/daily-bread" # single source of truth for the path
442
+ config.mount_at = "/daily-bread"
523
443
  config.app_name = "Daily Bread"
524
- config.tagline = "A 270-day journey through Scripture"
444
+ config.tagline = "Journeying through Scripture in 9 months"
525
445
  config.admin_emails = %w[andrew@example.org]
526
446
 
527
- config.start_date = nil # community start date, or nil for undated
528
- # config.start_date = Date.new(2026, 9, 6)
447
+ config.start_date = nil # no shared calendar by default
529
448
  config.allow_reader_start_date = true
449
+ config.time_zone = nil # server clock, or a named zone
450
+ config.daily_reminders = false # schedule reminders:send separately
451
+ config.mention_notifications = true # readers choose notification scope
452
+ config.mailer_host = "example.com" # reminder/notice links
530
453
 
531
- config.daily_reminders = false # schedule reminders:send every 15 minutes
532
- config.mention_notifications = true # reflection/reply emails; readers choose the scope
533
- config.mailer_host = "example.com" # links in reminder/notice email
534
-
535
- config.parent_controller = "ActionController::Base" # or "::ApplicationController"
536
- config.layout = "bible270/application"
454
+ config.parent_controller = "ActionController::Base" # or "::ApplicationController"
455
+ config.layout = "bible270/application"
537
456
 
538
457
  config.email_sign_in = true
539
458
  config.mailer_from = "no-reply@example.com"
540
459
  config.email_sign_in_ttl = 20 * 60
541
460
  config.email_sign_in_ask_name = true
461
+ config.email_sign_in_require_name = true
542
462
  config.omniauth_providers = [:github]
543
- config.omniauth_path_prefix = nil # nil = derive "<mount_at>/auth"
544
- config.current_reader_resolver = nil # set to bridge your own users
463
+ config.omniauth_path_prefix = nil # derive "<mount_at>/auth"
464
+ config.current_reader_resolver = nil # bridge host authentication
545
465
  config.require_sign_in_to_participate = true
466
+ config.remember_for = 365 * 24 * 60 * 60 # seconds; nil/0 = session only
546
467
 
547
- config.after_sign_in_path = nil # defaults to the plan root
468
+ config.after_sign_in_path = nil # plan root
548
469
  config.after_sign_out_path = nil
549
-
470
+ config.avatar_max_bytes = 2 * 1024 * 1024
550
471
  config.bible_version = "NKJV"
551
472
  end
552
473
  ```
474
+
475
+ See [Authentication](#authentication), [Tuning the plan](#tuning-the-plan), and [`Configuration`](lib/bible270/configuration.rb) for additional options.
476
+
553
477
  ### Footer
554
-
555
- The engine's pages end with a short note about how the plan works. Replace it with your own:
556
-
478
+
479
+ Replace the engine's plan note with a host partial or HTML, or disable it:
480
+
557
481
  ```ruby
558
- config.footer_partial = 'shared/footer' # a partial in your app
559
- config.footer_html = '<p>&copy; 2026 …</p>'
560
- config.footer = false # no footer at all
482
+ config.footer_partial = 'shared/footer' # app/views/shared/_footer.html.erb
483
+ # Alternatives:
484
+ config.footer_html = '<p>&copy; 2026 …</p>'
485
+ config.footer = false
561
486
  ```
562
-
563
- By default yours replaces the engine's. To keep both:
564
-
487
+
488
+ To include both the engine note and your footer:
489
+
565
490
  ```ruby
566
- config.footer_placement = :after # engine's note, then yours
567
- config.footer_placement = :before # yours, then the engine's note
568
- config.footer_placement = :replace # default
569
- ```
570
-
571
- A partial is looked up in your app's view paths as well as the engine's, so `'shared/footer'` finds
572
- `app/views/shared/_footer.html.erb`. Keep it reasonably self-contained: engine controllers include
573
- the engine's helpers, not your app's, so a partial calling your own helpers needs
574
- `helper ::ApplicationHelper` adding to the engine's controller — or just inline the markup.
575
-
491
+ config.footer_placement = :after # engine, then yours
492
+ config.footer_placement = :before # yours, then engine
493
+ config.footer_placement = :replace # default
494
+ ```
495
+
496
+ Host partials can use host view paths, but engine controllers do not automatically include host helpers. If needed, add `helper ::ApplicationHelper` to the engine controller or keep the partial self-contained.
497
+
576
498
  ### Favicon
577
-
578
- Pages under the mount point carry their own favicon — a rustic loaf, inlined as an SVG data URI, so
579
- there's nothing to add to your asset pipeline.
580
-
499
+
500
+ The engine layout uses an inline SVG loaf favicon, with no asset-pipeline setup:
501
+
581
502
  ```ruby
582
- config.favicon = nil # built-in loaf (default)
583
- config.favicon = '/icons/my-icon.svg' # your own
584
- config.favicon = false # none; the host's favicon applies
585
- ```
586
-
587
- It's emitted by the engine's layout, so if you point `config.layout` at your own layout, add
588
- `<%= b270_favicon_tag %>` to its `<head>`.
589
-
590
- References link to Bible.com by default. Readers choose Bible.com, Bible Gateway, or Blue Letter Bible
591
- from their profile, and an admin can set the same source for any reader. With `HEB/GRK`,
592
- Bible Gateway is unavailable: Blue Letter Bible uses WLC for Old Testament, Psalms, and Proverbs and
593
- mGNT for New Testament, while Bible.com uses WLC and THGNT respectively. The `ALLGRK — LXX OT and
594
- Greek NT` option also excludes Bible Gateway: Blue Letter Bible uses its mGNT/LXX route for every
595
- track, while Bible.com uses GRCBRENT for the Old Testament and THGNT for the New Testament. Bible.com
596
- links open the whole chapter rather than its individual-verse introduction page. Scripture links share one
597
- dedicated browser tab so moving among the day's passages does not
598
- leave a trail of open tabs; Ctrl-click, Cmd-click, middle-click, and the browser's context menu still
599
- open additional tabs when a reader wants to compare passages.
600
-
601
- Rendered reflections and replies also use [Blue Letter Bible ScriptTagger](https://www.blueletterbible.org/webtools/BLB_ScriptTagger.cfm)
602
- to show Scripture text when a reader hovers over a reference. The popup follows that reader's selected
603
- translation (or the site default for a visitor); `HEB/GRK` and `ALLGRK` choose the appropriate original
604
- language separately for Old and New Testament references. The engine layout loads this automatically.
605
- If `config.layout` points to a host layout, render the integration once near the end of its `<body>`:
503
+ config.favicon = nil # built-in loaf (default)
504
+ config.favicon = '/icons/my-icon.svg' # custom
505
+ config.favicon = false # omit the engine's favicon
506
+ ```
507
+
508
+ For a custom layout, add `<%= b270_favicon_tag %>` to `<head>`.
509
+
510
+ ### Scripture links and popups
511
+
512
+ References link to **Bible.com** by default. Readers and admins can select **Bible Gateway** or **Blue Letter Bible** in reader preferences. Bible.com opens whole chapters. Scripture links reuse one browser tab; Ctrl/Cmd-click, middle-click, or the context menu can open additional tabs.
513
+
514
+ Original-language options exclude Bible Gateway:
515
+
516
+ | Option | Bible.com | Blue Letter Bible |
517
+ |---|---|---|
518
+ | `HEB/GRK` | WLC Old Testament; THGNT New Testament | WLC Old Testament; mGNT New Testament |
519
+ | `ALLGRK` | GRCBRENT Old Testament; THGNT New Testament | mGNT/LXX route for all tracks |
520
+
521
+ [Blue Letter Bible ScriptTagger](https://www.blueletterbible.org/webtools/BLB_ScriptTagger.cfm) adds Scripture-reference hover popups to reflections and replies, using the reader's translation or the site default. `HEB/GRK` and `ALLGRK` select languages by testament. The engine layout loads it automatically; custom layouts should render this once near the end of `<body>`:
606
522
 
607
523
  ```erb
608
524
  <%= render "bible270/shared/scripture_popups" %>
609
525
  ```
610
526
 
611
- ScriptTagger loads JavaScript and CSS from Blue Letter Bible at runtime. A host with Content Security
612
- Policy enabled must allow `https://www.blueletterbible.org` in its existing `script-src` and `style-src`
613
- directives. This sends the visitor's IP address and normal request metadata to Blue Letter Bible when an
614
- engine page loads; hovering a reference also sends that reference and selected translation to BLB.
527
+ ScriptTagger loads remote JavaScript and CSS. Add `https://www.blueletterbible.org` to existing CSP **`script-src`** and **`style-src`** directives. Page loads share the visitor's IP address and request metadata with BLB; hovering also sends the reference and selected translation.
615
528
 
616
529
  ## With ComfortableMediaSurfer
617
530
 
618
- The CMS serves your content; this is a separate mounted app. Either **just link to it** (mount, add a nav link, done — the engine renders its own themed pages), or **match your chrome** by setting `config.parent_controller = "::ApplicationController"` and `config.layout = "layouts/application"` so it sits inside your header and footer. All engine CSS is prefixed `b270-`, so nothing collides.
531
+ Mount the engine and add a CMS navigation link to use its own themed pages. To use your host's header and footer, set `config.parent_controller = "::ApplicationController"` and `config.layout = "layouts/application"`. Include the shared styles, theme attribute, and script partials described above when supplying a custom layout.
619
532
 
620
533
  ## Data model
621
534
 
622
535
  | Table | Holds |
623
536
  |-------|-------|
624
- | `bible270_readers` | identity, avatar, provider/uid or polymorphic `owner`, start date, translation, passage-reader, and reminder preferences |
625
- | `bible270_checkoffs` | one row per reader per day per track (`ot`/`nt`/`pp`), unique-indexed |
626
- | `bible270_comments` | a plain-text or safely rendered Markdown reflection on a day, optionally scoped to a track, public to all |
627
- | `bible270_sign_in_tokens` | magic-link tokens: email, **digest only**, expiry, consumed-at |
537
+ | `bible270_readers` | Identity, provider/uid or polymorphic owner, start date, and reader preferences |
538
+ | `bible270_checkoffs` | One row per reader/day/track/part, protected by a unique index |
539
+ | `bible270_comments` | Day/track reflections and replies, stored as plain text or safely rendered Markdown |
540
+ | `bible270_likes` | Reader likes on comments |
541
+ | `bible270_settings` | Shared run and administrative settings |
542
+ | `bible270_sign_in_tokens` | Email, token digest, expiry, and consumption time |
628
543
 
629
- A day is "complete" once all three tracks are ticked. Progress and comments are **public** by
630
- design, same as Bible.com's shared plans.
544
+ A day is complete when all parts of all three tracks are checked off. Progress and visible reflections are public; they are not private journals.
631
545
 
632
546
  ## Routes (inside the mount point)
633
547
 
634
- ```
635
- GET / days#index overview + community + calendar
636
- GET /day/:day days#show readings, who's finished, reflections
637
- POST /day/:day/toggle/:track checkoffs#toggle
638
- POST /day/:day/comments comments#create
639
- POST /comments/preview comments#preview
640
- DELETE /comments/:id comments#destroy
641
- GET /community readers#index reader directory
642
- GET /mention-suggestions readers#mention_suggestions (signed-in JSON)
643
- GET /readers/:id readers#show
644
- GET /sign_in sessions#new email form + provider list
645
- POST /sign_in/email sessions#email_link
646
- GET /sign_in/email/:token sessions#email_callback
647
- GET /auth/:provider/callback sessions#create
648
- POST /auth/:provider/callback sessions#create
649
- GET /auth/failure sessions#failure
650
- DELETE /sign_out sessions#destroy
651
-
652
- POST <mount>/auth/:provider OmniAuth middleware, not the engine
548
+ Selected reader routes; see [`config/routes.rb`](config/routes.rb) for the full list, including Admin and Profile actions.
549
+
550
+ ```text
551
+ GET / days#index
552
+ GET /day/:day days#show
553
+ POST /day/:day/toggle/:track/:part checkoffs#toggle
554
+ POST /day/:day/toggle/:track checkoffs#toggle (first part)
555
+ POST /day/:day/comments comments#create
556
+ GET /reflections comments#index
557
+ POST /comments/preview comments#preview
558
+ PATCH /comments/:id comments#update
559
+ DELETE /comments/:id comments#destroy
560
+ POST /comments/:id/like likes#toggle
561
+ GET /community readers#index
562
+ GET /mention-suggestions readers#mention_suggestions (signed-in JSON)
563
+ GET /readers/:id readers#show
564
+ GET /progress readers#progress
565
+ GET /sign_in sessions#new
566
+ POST /sign_in/email sessions#email_link
567
+ GET /sign_in/email/:token sessions#email_callback
568
+ GET /auth/:provider/callback sessions#create
569
+ POST /auth/:provider/callback sessions#create
570
+ GET /auth/failure sessions#failure
571
+ DELETE /sign_out sessions#destroy
572
+
573
+ POST <mount>/auth/:provider OmniAuth middleware, not the engine
653
574
  ```
654
575
 
655
576
  ## Tuning the plan
656
577
 
657
- The whole schedule falls out of a few constants in `Bible270::Plan`:
658
-
659
- | Constant | Default | Effect |
660
- |----------|---------|--------|
661
- | `DAYS` | `270` | plan length |
662
- | `PROVERBS_PASSES` | `2` | Proverbs laps. Each pass is 31 readings, so this decides how many days are left for the Psalms |
663
- | `PSALM_119_SECTION_SIZE` | `16` | verses per Psalm 119 section. 176 divides evenly by 8, 11, 16, 22 and 44 |
664
- | `CHAPTER_BREAKS` | `{}` | where specific chapters break — see below |
665
-
666
- ### Choosing where a chapter breaks
667
-
668
- By default a divided chapter is cut into equal parts. To break it somewhere meaningful instead, add
669
- an entry to `CHAPTER_BREAKS` in `lib/bible270/plan.rb`. Keys are `[book, chapter]`; the value lists
670
- the **last verse of every reading except the final one**:
578
+ Prefer host configuration to editing the gem. Break points list the **last verse of each reading except the final one**; `[]` keeps a chapter whole:
671
579
 
672
580
  ```ruby
673
- CHAPTER_BREAKS = {
674
- ['Luke', 1] => [25, 56], # => Luke 1:1–25, 1:26–56, 1:57–80
675
- ['Psalm', 78] => [39] # => Psalm 78:1–39, 78:40–72
676
- }.freeze
581
+ config.chapter_breaks = {
582
+ 'Luke 1' => [25, 56], # 1–25, 26–56, 57–80
583
+ 'Psalm 78' => [20, 39, 55] # 1–20, 21–39, 40–55, 56–72
584
+ }
585
+ config.chapter_breaks_path = Rails.root.join('config/bible270_breaks.yml')
677
586
  ```
678
587
 
679
- The number of breaks fixes how many readings that chapter becomes, and the rest of the plan
680
- re-divides around it so both tracks still fill exactly 270 days — give Luke 1 a third reading and
681
- some other long chapter quietly gives one up. Verse coverage stays exact either way.
588
+ ```yaml
589
+ # config/bible270_breaks.yml — re-read when changed
590
+ Psalm 35: []
591
+ Psalm 78: [20, 39, 55]
592
+ ```
682
593
 
683
- Break points are validated on use: they must be ascending, distinct, and within the chapter, or you
684
- get an `ArgumentError` naming the entry rather than silently overlapping readings. Pinning more
685
- readings in total than there are days also raises, instead of producing a plan that doesn't fit.
594
+ Precedence is built-in `CHAPTER_BREAKS`, then `config.chapter_breaks`, then YAML. Ruby keys may also be arrays such as `['Luke', 1]`. Explicit breaks override default division rules, including Psalm 119's sections.
686
595
 
687
- Psalm 119 is pinned to `PSALM_119_SECTION_SIZE` sections by default; an entry in `CHAPTER_BREAKS`
688
- overrides that.
596
+ | `Bible270::Plan` constant | Default | Purpose |
597
+ |---|---|---|
598
+ | `DAYS` | `270` | Plan length |
599
+ | `PSALM_WHOLE_MAX_VERSES` | `25` | Keep shorter psalms whole unless explicitly overridden |
600
+ | `PSALM_119_SECTION_SIZE` | `16` | Default verses per Psalm 119 section |
601
+ | `CHAPTER_BREAKS` | Built-in chapter map | Selected breaks and whole-chapter overrides |
689
602
 
690
- Change `PROVERBS_PASSES` or `DAYS` and both the New Testament and the Psalms re-divide automatically
691
- to fill whatever's left. Divisions always go to whichever chapter currently carries the heaviest
692
- reading, so the longest get split first and nothing is divided that doesn't need to be.
603
+ For New Testament and Psalms/Proverbs readings, explicit breaks fix a chapter's reading count; unpinned chapters divide by verse load to fill the remaining days. The Psalms/Proverbs track reserves the final day for Psalm 1. Without explicit breaks, divided chapters use equal parts.
693
604
 
694
- All computed at load and memoized — no generated schedule, so nothing to migrate if you change them.
605
+ Breaks must be ascending, distinct, and inside the chapter; invalid entries or too many pinned readings raise `ArgumentError`. Results are memoized and refreshed when configured breaks change. There is no stored schedule to migrate, but **changing assignments does not remap existing check-offs or reflections**. Test custom schedules before using them with an active group.
695
606
 
696
607
  ## Scaling
697
608
 
698
- Community pages count completed days in Ruby from grouped check-offs — fine for hundreds of readers. Past a few thousand, cache a `days_completed` counter on `Reader` via a `Checkoff` `after_commit` and read it directly in SQL.
609
+ Community pages calculate completed days from grouped check-offs in Ruby. For large groups, profile this first; a cached `days_completed` counter on `Reader`, updated after check-off commits, is one possible optimization.
699
610
 
700
611
  ## Troubleshooting
701
612
 
702
613
  **404 on the provider callback**
703
614
 
704
- `path_prefix` doesn't match the mount point. Use `Bible270.config.auth_path_prefix` rather than a literal, and check the URL registered with the provider matches. Setting `mount_at` in an initializer Rails loads *after* `omniauth.rb` gives you the default prefix — see [Mount point](#bible270-mount-point-in-your-rails-app).
615
+ Match OmniAuth's `path_prefix` and the registered callback URL to the mount. Use `Bible270.config.auth_path_prefix` and check [initializer load order](#mount-point).
705
616
 
706
617
  **Sign-in button does nothing, or `OmniAuth::AuthenticityError`**
707
618
 
708
- Has to be a POST with a CSRF token. The engine's controls already are — if you built your own, make it a `button_to`. Also check `omniauth-rails_csrf_protection` is in the bundle.
619
+ Custom controls must POST with a CSRF token; use `button_to`. Confirm `omniauth-rails_csrf_protection` is bundled.
709
620
 
710
621
  **No email arrives**
711
622
 
712
- Needs working Action Mailer delivery — the engine just calls `deliver_now`. Check `mailer_from` is an address your relay accepts, and watch the logs. Failures never surface to the reader, on purpose, since that message can't reveal which addresses exist.
623
+ Check Action Mailer delivery settings, an accepted `mailer_from`, and logs. Sign-in uses `deliver_now` unless `email_sign_in_deliver_later` is enabled; for queued mail, check the Active Job worker too. Delivery failures are not shown to readers to avoid disclosing account information.
713
624
 
714
- **"That link has expired or was already used"**
625
+ **“That link has expired or was already used”**
715
626
 
716
- Links are single-use, 20-minute life. Some mail scanners and link-preview bots fetch URLs before the recipient clicks, burning the token. If it keeps happening, lengthen `email_sign_in_ttl` or find what's prefetching.
627
+ Request a fresh link. Links are single-use and expire after 20 minutes by default. Mail scanners or preview bots can consume them before the reader clicks; investigate prefetching if it recurs. Increase `email_sign_in_ttl` only if expiry is the problem—it cannot restore a consumed link.
717
628
 
718
- **Everything's unstyled in my layout**
629
+ **Custom layout is unstyled**
719
630
 
720
- The engine's CSS rides in a partial its own layout renders. Using your layout? Add `<%= render "bible270/shared/styles" %>` to the `<head>`, or style the `b270-*` classes yourself.
631
+ Add `<%= render "bible270/shared/styles" %>` to `<head>`, or style the `b270-*` classes yourself. Also include the theme attribute and shared scripts required by the features you use.
721
632
 
722
633
  ## Development
723
634
 
@@ -728,46 +639,31 @@ node --test test/javascript/*.cjs
728
639
  bundle exec rubocop --cache false
729
640
  ```
730
641
 
731
- `rake test` runs two isolated processes, streams colorized progress in real time, then prints one
732
- consolidated result and duration. It merges their SimpleCov results, writes a browsable report to
733
- `coverage/index.html`, and
734
- records per-file runtimes in `tmp/parallel_runtime_test.log` to improve
735
- subsequent balancing. Set `PARALLEL_WORKERS` to tune the worker count. Use
736
- `bundle exec rake test:serial` when a serial coverage run is specifically needed; it writes to the same
737
- project-local `coverage/` directory.
642
+ `rake test` defaults to six isolated processes, prints combined results, writes coverage to `coverage/index.html`, and records runtimes in `tmp/parallel_runtime_test.log` for balancing. Set `PARALLEL_WORKERS` to change the count, or use `bundle exec rake test:serial` for serial coverage.
738
643
 
739
- The video UI tests use Node.js 22+ and its built-in test runner, with no npm dependencies. They run the
740
- actual toolbar/player scripts against a small mocked DOM and also run as a separate CI job. They do
741
- not contact YouTube; live playback should be checked in a browser on the deployed host, especially
742
- when a host supplies a Content Security Policy.
644
+ Video UI tests require **Node.js 22+**, use the built-in runner with no npm dependencies, and do not contact YouTube. Check live playback and host CSP separately in a browser. Plan logic is unit-tested without a Rails dependency.
743
645
 
744
646
  ### Get an email link for local testing
745
647
 
746
- in the rails console: `rails c`
747
- ```
648
+ From the host app's console (`bin/rails console`):
649
+
650
+ ```ruby
748
651
  _record, raw = Bible270::SignInToken.issue!("John.Smith@example.com")
749
652
  Bible270::Engine.routes.url_helpers.email_sign_in_url(token: raw, host: "localhost:3333")
750
653
  ```
751
654
 
752
- Plan logic is fully unit-tested with no Rails dependency.
655
+ Use your local host/port. If `raw` is nil, the address is invalid or rate-limited; no link was issued.
753
656
 
754
657
  ## Contributing
755
658
 
756
- Bug reports and pull requests are welcome at <https://github.com/avonderluft/bible270>.
757
-
758
- 1. Fork it and clone your fork.
759
- 2. Branch off `main`: `git checkout -b my-feature`.
760
- 3. Make your change, and add tests — `bundle exec rake test` and `bundle exec rubocop --cache false` should stay green.
761
- 4. Commit with a clear message: `git commit -am "Add my feature"`.
762
- 5. Push: `git push origin my-feature`.
763
- 6. Open a pull request against `main`, saying what changed and why.
659
+ Report bugs or open pull requests at <https://github.com/avonderluft/bible270>.
764
660
 
765
- A few things that'll make review quick:
661
+ Fork and clone the repository, branch from `main` (`git checkout -b my-feature`), and add tests with your change. Run the [development checks](#development), commit with a clear message, and open a pull request against `main` explaining what changed and why.
766
662
 
767
- - Keep plan logic free of Rails so it stays unit-testable.
768
- - Anything touching the reading schedule needs a test pinning the expected references — the plan is deterministic, so assert exact values.
663
+ - Keep plan logic independent of Rails.
664
+ - Pin exact expected references in tests for schedule changes.
769
665
  - Prefix new CSS classes and helpers with `b270`.
770
- - Note anything user-visible in `CHANGELOG.md`.
666
+ - Record user-visible changes in `CHANGELOG.md`.
771
667
 
772
668
  ## License
773
669