bible270 0.6.3 → 0.10.0

data/README.md

@@ -1,192 +1,192 @@
-# bible270
-
-A mountable **Rails engine** that adds a social, 270-day Bible reading plan to a
-host Rails application such as [ComfortableMediaSurfer](https://github.com/shakacode/comfortable-mexican-sofa).
-
-Each day presents three readings, sized by **verse count** so daily portions take roughly
-the same time to read. Chapters are kept **whole** — the plan never chops a chapter into
-verse ranges except for the one excessively long chapter, Psalm 119.
-
-- **Old Testament** — read once, cover to cover. Whole chapters grouped so each day is
-  ~equal in verses (avg ~73/day, range 38–116).
-- **New Testament** — read **twice**. Each pass gets half the plan (135 days), so
-  Revelation lands on day 135 and again on day 270. ~2 chapters/day, every day, verse-balanced
-  within each pass.
-- **Psalms & Proverbs** — a whole-chapter companion that runs **twice** over the 270 days
-  (135 portions x 2). Very short chapters merge with a neighbour so there are no trivial
-  two-verse days (Psalm 117 reads as "Psalm 116–117"), and **Psalm 119 (176 verses) is the
-  sole chapter divided** — into exactly two readings, 1–88 and 89–176.
-
-Genesis→Malachi, the second pass through Revelation, and Proverbs 31 all finish together on
-day 270. A typical day runs ~157 verses across the three tracks (range 102–238).
-
-Readers check off each track, leave reflections (comments) on any day, and can see everyone
-else's progress and reflections — similar to the social plans on Bible.com.
-
-The plan itself is pure, deterministic Ruby (`Bible270::Plan`) — no rows are stored for the
-schedule. Daily portions are sized using per-chapter verse counts (`Bible270::Versification`,
-standard English/KJV versification; verse counts are facts about the text's structure, so
-nothing copyrighted is bundled). The database only holds **readers, check-offs, and comments**.
-
-## Requirements & compatibility
-
-- **Ruby** >= 3.0 (the gemspec's `required_ruby_version`). The plan logic is plain Ruby with
-  no C extensions and no dependency on any gem that Ruby 4.0 unbundled. Installs and loads under
-  Ruby 4.0.6; the test suite is exercised on 3.2 and passes with
-  `--enable-frozen-string-literal` forced.
-- **Ruby 4.0 notes.** Audited against the 4.0 breaking changes: the gem does not use `cgi`
-  (removed from default gems in 4.0 — URL escaping goes through `URI.encode_www_form_component`
-  instead, which is byte-identical to `CGI.escape`), `Set`/`SortedSet`, `Ractor`, `Net::HTTP`,
-  `Process::Status`, `ObjectSpace`, or any of the gems promoted from default to bundled
-  (`ostruct`, `logger`, `benchmark`, `pstore`, `irb`, `rdoc`). Every file carries a
-  `# frozen_string_literal: true` magic comment and no string literal is mutated.
-- **Rails.** The gemspec allows `rails >= 7.0`, but on Ruby 4.0 the binding constraint is your
-  host app, not this engine: Rails 8.0/8.1 require Ruby >= 3.2, and ComfortableMediaSurfer is a
-  "Rails 7.0+" engine. Verify your own lockfile (e.g. with RailsBump) before pairing an older
-  Rails with Ruby 4.0.
-- A host application (this is an engine, not a standalone app).
-- Turbo is used for seamless check-offs and degrades to full-page redirects if absent.
+# Bible 270
 
-## Install
+[![Gem Version](https://badge.fury.io/rb/bible270.svg)](https://badge.fury.io/rb/bible270) [![Gem Downloads](https://img.shields.io/gem/dt/bible270.svg?style=flat)](http://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)
+
+A mountable **Rails engine** that drops a 270-day (9 month) interactive Bible reading plan into any Rails app, built with [ComfortableMediaSurfer](https://github.com/shakacode/comfortable-media-surfer) 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.
+
+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 with a 9 month school year.
+
+## The plan
+
+Three readings a day, sized by **verse count** so each day takes roughly the same time.
+
+- **Old Testament** — once through, with Psalms and Proverbs live in their own track. Whole chapters grouped so each day is ~73 verses (range 38–116).
+- **New Testament** — once through, a reading every day. 260 chapters over 270 days, so the 10 longest are halved (Luke 1, Matthew 26–27, Mark 14, Luke 9, 12, 22, John 6,8, Acts 7).
+- **Psalms & Proverbs** — once each, interleaved in one track. 181 chapters have to cover 270 days, so 89 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.
+
+Genesis → Malachi and Revelation 22 both land on day 270, as does the second Proverbs 31 — the first falls on day 135, the midpoint. Psalm 150 comes in on day 269. Every day carries all three tracks. A typical day is ~119 verses (range 76–175).
 
-Add to the host app's `Gemfile`:
+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.
+
+## Requirements
+
+- **Ruby** >= 3.0. Plain Ruby, no C extensions. Runs on 4.0.6 — it avoids everything 4.0 dropped or unbundled (notably `cgi`; URL escaping uses `URI.encode_www_form_component`).
+- **Rails** >= 7.0. On Ruby 4.0 your host app is the real constraint, not this engine — check your lockfile with RailsBump first.
+- A host app, and Turbo if you want check-offs without a page reload.
+
+## Install
 
 ```ruby
+# Gemfile
 gem "bible270"
 ```
 
 <details>
-<summary>Other sources (unreleased changes, local development)</summary>
+<summary>Other sources</summary>
 
 ```ruby
-# straight from the repository
 gem "bible270", git: "https://github.com/avonderluft/bible270.git", branch: "main"
-
-# a local checkout you're editing
-gem "bible270", path: "../bible270"
+gem "bible270", path: "<path_to_your_local_copy>/bible270"   # local checkout
 ```
 </details>
 
-Then install, copy the migrations, and migrate:
-
 ```bash
 bundle install
-bin/rails bible270:install:migrations
-bin/rails db:migrate
+bin/rails generate bible270:install
 ```
 
-`install:migrations` copies four migrations into your `db/migrate` (readers, check-offs, comments,
-sign-in tokens). They belong to your application from then on: they get your timestamps, appear in
-your `schema.rb`, and are yours to run, roll back, or edit. The engine does **not** add its own
-migration directory to your app's paths, so the copies are the only definitions in play.
+That's the whole install. The generator is interactive and walks you through it:
 
-Mount it in `config/routes.rb`:
+1. asks where to mount the plan;
+2. asks which sign-in methods you want — email link, OmniAuth, or both — and adds any OmniAuth strategy gems to your `Gemfile`;
+3. copies the four migrations into your `db/migrate` and offers to run them;
+4. writes `config/initializers/bible270.rb` (and `omniauth.rb` if you chose social sign-in); and
+5. adds `mount Bible270::Engine, at: Bible270.config.mount_at` to `config/routes.rb`.
 
-```ruby
-mount Bible270::Engine, at: "/reading-plan"
-```
+(Migrations run before the config is written, so a problem in a generated initializer can't block the database work.)
+
+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.
 
-Optionally generate the initializers (see [Authentication](#authentication)):
+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.
+
+Non-interactive (CI, re-runs, scripted setup):
 
 ```bash
-bin/rails generate bible270:install --mount-at=/reading-plan --providers=github
+bin/rails generate bible270:install --defaults \
+  --mount-at=/daily-bread --providers=github,google_oauth2 \
+  --mailer-from=no-reply@example.org --no-migrate
 ```
 
-The plan is now live at `/reading-plan`.
+| Flag | Effect |
+|------|--------|
+| `--defaults` | Ask nothing, accept every default |
+| `--mount-at=PATH` | Where to mount (default `/daily-bread`) |
+| `--providers=a,b` | OmniAuth providers; `--providers=` for none |
+| `--email` / `--no-email` | Email sign-in on or off |
+| `--mailer-from=ADDR` | From: address for sign-in emails |
+| `--bundle` / `--no-bundle` | Run `bundle install` after adding strategy gems |
+| `--migrate` / `--no-migrate` | Run `db:migrate` at the end |
 
-### Upgrading
+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.
+
+<details>
+<summary>Doing it by hand instead</summary>
+
+```ruby
+# config/initializers/bible270.rb
+Bible270.configure do |config|
+  config.mount_at   = "/daily-bread"
+  config.email_sign_in = true
+  config.mailer_from   = "no-reply@example.com"
+  config.omniauth_providers = []            # or [:github], plus an OmniAuth initializer
+end
+```
 
-When a new version adds a migration, re-run the copy step — already-copied migrations are skipped:
+```ruby
+# config/routes.rb
+mount Bible270::Engine, at: Bible270.config.mount_at
+```
 
 ```bash
-bundle update bible270
 bin/rails bible270:install:migrations
 bin/rails db:migrate
 ```
 
----
+See [Authentication](#authentication) for the OmniAuth initializer.
+</details>
 
-## Authentication
+### Upgrading
 
-Two built-in ways to sign in, so **nobody is excluded**:
+No need to re-run the generator — just pick up any new migrations:
 
-1. **Email link (passwordless)** — the reader types their address, gets a one-time link, and
-   clicks it. No password, no account with anyone else. This is the default and it's what makes
-   the plan usable by people who don't have (or don't want to use) GitHub, Google, and friends.
-2. **OmniAuth social sign-in** — optional convenience for those who do.
+```bash
+bundle update bible270
+bin/rails bible270:install:migrations   # skips ones you already have
+bin/rails db:migrate
+```
 
-Either can run alone. `config.omniauth_providers = []` gives you an email-only site;
-`config.email_sign_in = false` gives you social-only. Viewing the plan and reading others'
-reflections stays public either way — only checking off and commenting require signing in.
+## Bible270 Mount point in your Rails app
 
-### Email sign-in
+The path lives in exactly **one** place, `config.mount_at`:
 
 ```ruby
+# config/initializers/bible270.rb
 Bible270.configure do |config|
-  config.email_sign_in = true
-  config.mailer_from   = "no-reply@gknt.org"
-  config.email_sign_in_ask_name = true       # reader picks their display name
-  # config.email_sign_in_ttl = 20 * 60       # link lifetime (seconds)
-  # config.email_sign_in_max_per_window = 5  # per address, per window
-  # config.email_sign_in_window = 15 * 60
-  # config.email_sign_in_deliver_later = true  # needs an Active Job backend
+  config.mount_at = "/daily-bread"    # or "/read270", "/manna", whatever you wish
 end
 ```
 
-The host app needs working Action Mailer delivery — nothing else. How it behaves:
+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.
 
-- Tokens are 256-bit, URL-safe, single-use, and expire (20 minutes by default).
-- **Only a SHA-256 digest of the token is stored**, so the table is useless to anyone who reads
-  the database. There is no password column anywhere in this gem.
-- Consuming a link is a conditional update, so a double-clicked link can't sign in twice.
-- The "check your inbox" response is identical whether the address was known, unknown, or
-  rate-limited — no account enumeration and no hint that a limit was hit.
-- Readers may set the display name shown beside their reflections; otherwise it's derived from the
-  address (`mary.anne.smith@…` → "Mary Anne Smith").
-- Spent and stale tokens can be cleaned up with `Bible270::SignInToken.sweep!` from a cron/rake task.
+Values are normalised — `"read270"`, `"/read270"`, `"/read270/"` all become `/read270`. Nested paths and mounting at `/` work too.
 
-An email reader gets `provider: "email"` in the same identity columns OmniAuth uses, so downstream
-(progress, comments, leaderboard) treats every reader identically.
+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**.
 
-### OmniAuth social sign-in
+> **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.
 
-### Quick setup
+Need OmniAuth somewhere unrelated? Set `config.omniauth_path_prefix` and it wins.
 
-```bash
-bin/rails generate bible270:install --mount-at=/reading-plan --providers=github
-```
+## Authentication
+
+Two ways in, so **nobody's shut out**:
+
+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.
+2. **Social sign-in** via OmniAuth — for people who'd rather.
+
+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.
 
-That writes `config/initializers/bible270.rb` (email sign-in enabled) and
-`config/initializers/omniauth.rb` (with `path_prefix` already matching your mount point), and adds
-the `mount` line to your routes. Pass `--providers=` with an empty value for an email-only site.
-Then add the gems you need and migrate:
+### Email links
 
 ```ruby
-# Gemfile — omniauth and omniauth-rails_csrf_protection come in with bible270;
-# the provider strategy is your choice:
-gem "omniauth-github"
+Bible270.configure do |config|
+  config.email_sign_in = true
+  config.mailer_from   = "no-reply@example.com"
+  config.email_sign_in_ask_name = true
+  config.email_sign_in_require_name = true   # first AND last name       # let readers pick their display name
+  # config.email_sign_in_ttl = 20 * 60       # link lifetime, seconds
+  # config.email_sign_in_max_per_window = 5  # per address
+  # config.email_sign_in_window = 15 * 60
+  # config.email_sign_in_deliver_later = true  # needs Active Job
+end
 ```
 
-```bash
-bundle install
-bin/rails bible270:install:migrations && bin/rails db:migrate
-```
+All it needs is working Action Mailer delivery.
 
-Finally register the callback URL with the provider:
+- Tokens: 256-bit, URL-safe, single-use, 20-minute expiry.
+- **Only a SHA-256 digest is stored** — no password column anywhere, so the table is useless to anyone reading your DB.
+- Claiming is a conditional update, so a double-clicked link still signs you in once.
+- "Check your inbox" reads the same whether the address was known, unknown, or rate-limited — no account enumeration.
+- Display name comes from the reader, else the address (`mary.anne.smith@…` → "Mary Anne Smith").
+- `Bible270::SignInToken.sweep!` clears spent tokens. Good cron fodder.
 
-```
-https://gknt.org/reading-plan/auth/github/callback
-```
+Email readers get `provider: "email"` in the same columns OmniAuth uses, so everything downstream treats them identically.
 
-### Manual setup
+### Social sign-in
 
-If you'd rather not use the generator, the only subtlety is that OmniAuth's `path_prefix` must
-line up with where the engine is mounted, so its callback lands on the engine's route:
+`bin/rails generate bible270:install` sets this up: it adds the strategy gem to your `Gemfile`
+(`omniauth` and `omniauth-rails_csrf_protection` already ride along with bible270), writes the
+OmniAuth initializer, and prints the callback URL to register with each provider — for example
+`https://example.com/daily-bread/auth/github/callback`.
+
+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:
 
 ```ruby
 # config/initializers/omniauth.rb
 Rails.application.config.middleware.use OmniAuth::Builder do
-  path_prefix "/reading-plan/auth"          # == <mount point>/auth
+  # `options` is merged into every provider declared after it, so it comes first.
+  # OmniAuth::Builder has no path_prefix method — this is the scoped equivalent.
+  options path_prefix: Bible270.config.auth_path_prefix
+
   provider :github, ENV["GITHUB_CLIENT_ID"], ENV["GITHUB_CLIENT_SECRET"]
 end
 
@@ -196,31 +196,23 @@ OmniAuth.config.on_failure = proc { |env| Bible270::SessionsController.action(:f
 ```ruby
 # config/initializers/bible270.rb
 Bible270.configure do |config|
-  config.omniauth_providers = [:github]              # or [:github, [:google_oauth2, "Google"]]
+  config.mount_at           = "/daily-bread"
+  config.omniauth_providers = [:github]      # or [:github, [:google_oauth2, "Google"]]
   config.parent_controller  = "::ApplicationController"
 end
 ```
 
-### Notes worth knowing
+Worth knowing:
 
-- **Sign-in is a POST, not a link.** OmniAuth 2.0+ refuses GET on its request phase
-  (CVE-2015-9284), so every sign-in control the engine renders is a `button_to` carrying a CSRF
-  token, and `omniauth-rails_csrf_protection` provides the Rails-aware verifier. If you build your
-  own sign-in link, it must POST to `<mount>/auth/:provider`.
-- **One provider vs several.** With a single configured provider the header shows a direct
-  "Sign in with X" button; with several it links to a sign-in page (`GET <mount>/sign_in`) listing
-  them all.
-- **Return-to-origin.** Sign-in controls pass the current path as `origin`, so a reader who clicks
-  a check-off while signed out lands back on that same day afterwards. Origins are validated to be
-  local paths only.
-- **Session hygiene.** `reset_session` runs on both sign-in and sign-out to avoid session fixation.
-  Sign-out is `DELETE <mount>/sign_out`.
-- **What's stored.** Provider, uid, display name, email, and avatar URL — no tokens, no passwords.
+- **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`.
+- One provider → a button in the header. Several → a sign-in page at `<mount>/sign_in`.
+- 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.
+- `reset_session` on sign-in and sign-out, against session fixation.
+- Stored: provider, uid, display name, email, avatar URL. No tokens, no passwords.
 
-### Alternative: bridge your host's own users
+### Or use your own users
 
-If the host app already has authentication and you'd rather not use OmniAuth at all, set a
-resolver instead and the engine will never touch sessions:
+Already have auth? Hand the engine a resolver and it'll never touch sessions:
 
 ```ruby
 config.current_reader_resolver = lambda do |controller|
@@ -231,224 +223,247 @@ config.current_reader_resolver = lambda do |controller|
 end
 ```
 
-`Reader.for_owner` links a reader to any host model polymorphically via `owner`. Note that
-ComfortableMediaSurfer's admin authentication is separate from public site visitors, so for a
-public plan on a CMS front-end the OmniAuth path above is usually the right fit.
+`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.
 
-## Start dates
+## Admin panel
 
-The plan works either **undated** (day numbers only) or **dated** (day numbers mapped onto a
-calendar). There are two levers:
+At `<mount>/admin`: remove readers, adjust their completions, move them to a given day. Unreachable —
+every route 404s rather than 403s — unless you say who may use it:
 
 ```ruby
-Bible270.configure do |config|
-  # A community-wide start date — everyone reads together as a cohort.
-  # Accepts a Date, Time, or "YYYY-MM-DD" string. Default: nil (undated).
-  config.start_date = Date.new(2026, 9, 6)
+config.admin_emails = %w[andrew@example.org]
+# or
+config.admin_resolver = ->(reader) { reader.email.to_s.end_with?('@example.org') }
+```
 
-  # May an individual reader set/change their own start date? Default: true.
-  # Set false to pin everyone to config.start_date.
-  config.allow_reader_start_date = true
-end
+Admins get an extra "Admin" link in the header. From a reader's page you can:
+
+- **move them to a day** — "put them on day 42 as of today" back-dates the start date; check-offs are
+  keyed to day numbers, so nothing in their history moves;
+- **set their progress** — mark complete through day N (this also clears anything after, so it sets
+  progress exactly), or click days in the grid to toggle them;
+- **remove them**, with every check-off and reflection they've written;
+- **moderate reflections** at `<mount>/admin/comments`. Reflections are visible the moment they're
+  written; hiding one takes it off the day and community pages without deleting it, and is
+  reversible. Delete is there too, for anything that shouldn't be kept.
+
+Break points can also live in your app rather than the gem, and be changed without a restart:
+
+```ruby
+config.chapter_breaks = { 'Psalm 78' => [20, 39, 55] }
+config.chapter_breaks_path = Rails.root.join('config/bible270_breaks.yml')
 ```
 
-How the two combine:
+```yaml
+# config/bible270_breaks.yml — re-read whenever it changes
+Psalm 35: []
+Psalm 78: [20, 39, 55]
+```
 
-| `start_date` | `allow_reader_start_date` | Behaviour |
-|---|---|---|
-| nil | true (default) | Each reader is stamped with their own start date the first time they check something off, and can change it. |
-| a date | true | The community date is the default; any reader may override it with their own. |
-| a date | false | Everyone is pinned to the community date. The per-reader form is hidden. |
-| nil | false | Fully undated — day numbers only, no calendar anywhere. |
+## Start dates
 
-When a plan is dated, each day page shows its calendar date with a **Today** badge, the overview
-gains a "Go to today" link, and readers see whether they're ahead of or behind the pace.
+The plan runs **undated** (day numbers only) or **dated** (days mapped onto a calendar):
 
-Readers manage their own date from the overview page (`PATCH /start-date`, `DELETE /start-date`).
-Changing a start date only re-maps days onto the calendar — check-offs and reflections are keyed
-to day numbers and are never touched.
+```ruby
+config.start_date = Date.new(2026, 9, 6)   # Date, Time, or "YYYY-MM-DD". nil = undated
+config.allow_reader_start_date = true      # can readers set their own?
+```
 
-The date helpers are pure functions on `Bible270::Plan`, so you can use them anywhere:
+| `start_date` | `allow_reader_start_date` | What happens |
+|---|---|---|
+| nil | true *(default)* | Each reader gets stamped on first check-off, and can change it |
+| a date | true | Community date is the default; anyone may override |
+| a date | false | Everyone pinned to the community date, form hidden |
+| nil | false | Fully undated — no calendar anywhere |
+
+Dated plans show each day's date with a **Today** badge, a "Go to today" link, and whether you're ahead or behind. Readers set their own from the overview. Changing a start date only re-maps the calendar — check-offs and reflections are keyed to day numbers, so nothing moves.
+
+Date helpers are pure functions, usable anywhere:
 
 ```ruby
-Bible270::Plan.date_for(1, "2026-09-06")        # => Sun, 06 Sep 2026
-Bible270::Plan.end_date_for("2026-09-06")       # => Wed, 02 Jun 2027  (day 270)
-Bible270::Plan.day_for(Date.current, start)     # => 42   (clamped to 1..270)
-Bible270::Plan.day_for(date, start, clamp: false) # => -3 or 271, to detect out-of-range
-Bible270::Plan.before_start?(date, start)       # => true/false
+Bible270::Plan.date_for(1, "2026-09-06")          # => Sun, 06 Sep 2026
+Bible270::Plan.end_date_for("2026-09-06")         # => Wed, 02 Jun 2027 (day 270)
+Bible270::Plan.day_for(Date.current, start)       # => 42 (clamped 1..270)
+Bible270::Plan.day_for(date, start, clamp: false) # => -3 or 271, to spot out-of-range
+Bible270::Plan.before_start?(date, start)
 ```
 
 ## Configuration reference
 
 ```ruby
 Bible270.configure do |config|
+  config.mount_at = "/daily-bread"         # single source of truth for the path
   config.app_name = "Daily Bread"
   config.tagline  = "A 270-day journey through Scripture"
 
   config.start_date = nil                  # community start date, or nil for undated
-  config.allow_reader_start_date = true    # may readers set their own?
+  config.allow_reader_start_date = true
 
-  config.parent_controller = "ActionController::Base"      # or "::ApplicationController"
+  config.parent_controller = "ActionController::Base"   # or "::ApplicationController"
   config.layout            = "bible270/application"
 
-  config.email_sign_in = true                              # passwordless email link
+  config.email_sign_in = true
   config.mailer_from = "no-reply@example.com"
   config.email_sign_in_ttl = 20 * 60
   config.email_sign_in_ask_name = true
-  config.omniauth_providers = [:github]                    # optional social sign-in
-  config.omniauth_path_prefix = nil                        # nil = derive "<mount>/auth"
-  config.current_reader_resolver = nil                     # set to bridge host users instead
+  config.omniauth_providers = [:github]
+  config.omniauth_path_prefix = nil        # nil = derive "<mount_at>/auth"
+  config.current_reader_resolver = nil     # set to bridge your own users
   config.require_sign_in_to_participate = true
 
-  config.after_sign_in_path  = nil                         # defaults to plan root
+  config.after_sign_in_path  = nil         # defaults to the plan root
   config.after_sign_out_path = nil
 
-  config.bible_version = "ESV"
+  config.bible_version = "NKJV"
   config.passage_url_builder = ->(reference, version) {
     "https://www.biblegateway.com/passage/?search=#{URI.encode_www_form_component(reference)}&version=#{version}"
   }
 end
 ```
 
-Every reading reference links out to the configured Bible reader (Bible Gateway by
-default). Point `passage_url_builder` at your own reader if you host one.
-
----
-
-## Using it inside ComfortableMediaSurfer
+References link to Bible Gateway by default — point `passage_url_builder` at your another reader if you wish, or your own reader if you host one.
 
-ComfortableMediaSurfer serves marketing/content pages; this engine is a separate
-mounted app. Two integration styles:
+## With ComfortableMediaSurfer
 
-1. **Link to it** — mount at `/reading-plan` and add a CMS navigation link. The
-   engine renders its own themed pages. Simplest and fully featured.
-
-2. **Match the site chrome** — set `config.parent_controller = "::ApplicationController"`
-   and `config.layout = "layouts/application"` (your site layout) so the plan pages
-   sit inside your normal header/footer. The engine's scoped CSS (all classes are
-   prefixed `b270-`) won't collide with CMS styles.
-
-Because CMS admin auth (`ComfortableMediaSurfer`) is separate from public readers,
-Option B (OmniAuth) is usually the right fit for public visitors on gknt.org.
-
----
+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.
 
 ## Data model
 
-| Table | Purpose |
-|-------|---------|
+| Table | Holds |
+|-------|-------|
 | `bible270_readers` | identity: display name, avatar, provider/uid or polymorphic `owner`, `started_on` |
-| `bible270_checkoffs` | one row per reader per day per track (`ot`/`nt`/`pp`); unique index prevents dups |
-| `bible270_sign_in_tokens` | short-lived magic-link tokens: email, **digest only**, expiry, consumed-at |
-| `bible270_comments` | a reflection on a day (optionally scoped to a track), public to all |
+| `bible270_checkoffs` | one row per reader per day per track (`ot`/`nt`/`pp`), unique-indexed |
+| `bible270_comments` | a reflection on a day, optionally scoped to a track, public to all |
+| `bible270_sign_in_tokens` | magic-link tokens: email, **digest only**, expiry, consumed-at |
 
-A day counts as "complete" for a reader when they've checked every track that has
-content that day (2 on a light-NT day, otherwise 3). All progress and comments are
-**public** to other readers by design (mirroring Bible.com's shared plans).
+A day is "complete" once all three tracks are ticked. Progress and comments are **public** by
+design, same as Bible.com's shared plans.
 
-## Routes (within the mount point)
+## Routes (inside the mount point)
 
 ```
 GET    /                         days#index      overview + community + calendar
-GET    /day/:day                 days#show       three readings, completers, reflections
+GET    /day/:day                 days#show       readings, who's finished, reflections
 POST   /day/:day/toggle/:track   checkoffs#toggle
 POST   /day/:day/comments        comments#create
 DELETE /comments/:id             comments#destroy
 PATCH  /start-date               readers#update_start_date
 DELETE /start-date               readers#clear_start_date
 GET    /community                readers#index   leaderboard
-GET    /readers/:id              readers#show    a reader's progress + reflections
-GET    /sign_in                  sessions#new     email form + provider list
-POST   /sign_in/email            sessions#email_link      send a magic link
-GET    /sign_in/email/:token     sessions#email_callback  consume a magic link
-GET    /auth/:provider/callback  sessions#create  (OmniAuth callback)
+GET    /readers/:id              readers#show
+GET    /sign_in                  sessions#new    email form + provider list
+POST   /sign_in/email            sessions#email_link
+GET    /sign_in/email/:token     sessions#email_callback
+GET    /auth/:provider/callback  sessions#create
 POST   /auth/:provider/callback  sessions#create
 GET    /auth/failure             sessions#failure
 DELETE /sign_out                 sessions#destroy
 
-POST   <mount>/auth/:provider    handled by the OmniAuth middleware, not the engine
+POST   <mount>/auth/:provider    OmniAuth middleware, not the engine
 ```
 
-## Tuning the plan shape
+## Tuning the plan
 
-The whole schedule is derived from a handful of constants in `Bible270::Plan`, so the shape
-can be changed without touching anything else:
+The whole schedule falls out of a few constants in `Bible270::Plan`:
 
 | Constant | Default | Effect |
 |----------|---------|--------|
 | `DAYS` | `270` | plan length |
-| `NT_PASSES` | `2` | how many times the New Testament is read (each pass gets `DAYS / NT_PASSES` days) |
-| `PP_LONG_CHAPTER` | `100` | a chapter longer than this is divided. At 100 only Psalm 119 (176v) qualifies, since the next longest is Psalm 78 at 72v. Raise it above 176 to never split anything |
-| `PP_SPLIT_PARTS` | `2` | how many readings such a chapter becomes |
-| `PP_MIN_DAY` / `PP_DAY_TARGET` | `12` / `22` | how aggressively short chapters merge. These two values are what make the companion come out to exactly 135 portions, i.e. two clean passes across 270 days |
+| `PROVERBS_PASSES` | `2` | Proverbs laps. Each pass is 31 readings, so this decides how many days are left for the Psalms |
+| `PSALM_119_SECTION_SIZE` | `16` | verses per Psalm 119 section. 176 divides evenly by 8, 11, 16, 22 and 44 |
+| `CHAPTER_BREAKS` | `{}` | where specific chapters break — see below |
 
-Everything is computed at load time and memoized; there is no generated schedule to migrate
-if you change these.
+### Choosing where a chapter breaks
 
-## Scaling note
+By default a divided chapter is cut into equal parts. To break it somewhere meaningful instead, add
+an entry to `CHAPTER_BREAKS` in `lib/bible270/plan.rb`. Keys are `[book, chapter]`; the value lists
+the **last verse of every reading except the final one**:
 
-The community leaderboard computes completed-days in Ruby from grouped check-off
-counts. That's ideal for a homelab/parish-sized community (hundreds of readers). If
-you grow to many thousands, add a cached `days_completed` counter on `Reader`
-(updated in a `Checkoff` after_commit) and sort in SQL.
+```ruby
+CHAPTER_BREAKS = {
+  ['Luke', 1]   => [25, 56],   # => Luke 1:1–25, 1:26–56, 1:57–80
+  ['Psalm', 78] => [39]        # => Psalm 78:1–39, 78:40–72
+}.freeze
+```
 
-## Troubleshooting
+The number of breaks fixes how many readings that chapter becomes, and the rest of the plan
+re-divides around it so both tracks still fill exactly 270 days — give Luke 1 a third reading and
+some other long chapter quietly gives one up. Verse coverage stays exact either way.
 
-**`ActiveRecord::DuplicateMigrationNameError: Multiple migrations have the name CreateBible270Readers`**
+Break points are validated on use: they must be ascending, distinct, and within the chapter, or you
+get an `ArgumentError` naming the entry rather than silently overlapping readings. Pinning more
+readings in total than there are days also raises, instead of producing a plan that doesn't fit.
 
-You're on 0.6.2 or earlier, where the engine wrongly added its own `db/migrate` to the host app's
-migration paths *as well as* providing `install:migrations` — so copying them defined every
-migration class twice. Upgrade to >= 0.6.3 and keep your copied migrations:
+Psalm 119 is pinned to `PSALM_119_SECTION_SIZE` sections by default; an entry in `CHAPTER_BREAKS`
+overrides that.
 
-```bash
-bundle update bible270
-bin/rails db:migrate
-```
+Change `PROVERBS_PASSES` or `DAYS` and both the New Testament and the Psalms re-divide automatically
+to fill whatever's left. Divisions always go to whichever chapter currently carries the heaviest
+reading, so the longest get split first and nothing is divided that doesn't need to be.
 
-**Sign-in returns 404 on the provider callback**
+All computed at load and memoized — no generated schedule, so nothing to migrate if you change them.
 
-OmniAuth's `path_prefix` doesn't match where the engine is mounted. They have to line up:
-mounting at `/reading-plan` means `path_prefix "/reading-plan/auth"`, and the URL registered with
-the provider must be `https://YOUR-HOST/reading-plan/auth/github/callback`. The install generator
-writes both consistently.
+## Scaling
 
-**Clicking "Sign in with …" does nothing, or raises `OmniAuth::AuthenticityError`**
+The leaderboard counts 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 sort in SQL.
 
-The request has to be a POST with a CSRF token — OmniAuth 2.0+ refuses GET
-([CVE-2015-9284](https://nvd.nist.gov/vuln/detail/CVE-2015-9284)). The engine's own controls are
-already POST forms; if you've built your own link, convert it to `button_to`. Also confirm
-`omniauth-rails_csrf_protection` is in the bundle.
+## Troubleshooting
 
-**No sign-in email arrives**
+**404 on the provider callback**
 
-Email sign-in needs working Action Mailer delivery in the host app — the engine only calls
-`deliver_now` (or `deliver_later`). Check `config.mailer_from` is a real address your relay will
-accept, and watch the logs: delivery errors surface there. Nothing about a failure is shown to the
-reader, deliberately, since the "check your inbox" message is identical either way to avoid
-disclosing which addresses exist.
+`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).
 
-**"That link has expired or was already used"**
+**Sign-in button does nothing, or `OmniAuth::AuthenticityError`**
+
+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.
 
-Links are single-use and live for `email_sign_in_ttl` (20 minutes by default). Some mail scanners
-and link-preview services fetch URLs before the recipient clicks, which consumes the token. If you
-see this a lot, lengthen the TTL or check whether something upstream is prefetching links.
+**No email arrives**
 
-**Everything renders unstyled inside my layout**
+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.
 
-The engine ships scoped CSS in a partial rendered by its own layout. If you point
-`config.layout` at your application layout, add
-`<%= render "bible270/shared/styles" %>` to that layout's `<head>`, or style the `b270-*` classes
-yourself.
+**"That link has expired or was already used"**
+
+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.
 
-## Development / tests
+**Everything's unstyled in my layout**
 
-The deterministic plan logic is fully unit-tested with no Rails dependency:
+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.
+
+## Development
 
 ```bash
 bundle install
 rake test
 ```
 
+### Get an email link for local testing
+
+in the rails console: `rails c`
+```
+_record, raw = Bible270::SignInToken.issue!("John.Smith@example.com")
+Bible270::Engine.routes.url_helpers.email_sign_in_url(token: raw, host: "localhost:3333")
+```
+
+Plan logic is fully unit-tested with no Rails dependency.
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/avonderluft/bible270>.
+
+1. Fork it and clone your fork.
+2. Branch off `main`: `git checkout -b my-feature`.
+3. Make your change, and add tests — `rake test` should stay green.
+4. Commit with a clear message: `git commit -am "Add my feature"`.
+5. Push: `git push origin my-feature`.
+6. Open a pull request against `main`, saying what changed and why.
+
+A few things that'll make review quick:
+
+- Keep plan logic free of Rails so it stays unit-testable.
+- Anything touching the reading schedule needs a test pinning the expected references — the plan is deterministic, so assert exact values.
+- Prefix new CSS classes and helpers with `b270`.
+- Note anything user-visible in `CHANGELOG.md`.
+
 ## License
 
-MIT. See `MIT-LICENSE`.
+MIT. See `MIT-LICENSE`.