bible270 0.6.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c9baaae6c81c3923b1997672d8f13ff5edd97dba42c56f29ec86fee53c508512
+  data.tar.gz: c564d896cd9144cee1aa4321e0cc39aa77f3197fb7a6f599045053b0fb674204
+SHA512:
+  metadata.gz: 0d2de30b25a9be283d994aef6db3c5743e7a3c112208eae6a3aa6b66cb45d893312cba18321f02dc240699ac774f13a9361cdb59b063c95e709cf934a0d602cc
+  data.tar.gz: cf3908da790617444a1ef1717c533912d1303ca6c5ca32624186262964a836997639940d578eea1c7f06c61ad3dd9d00f1e23401ce3cfb8e21d8f8084d62ba21

data/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+All notable changes to bible270. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html), treating pre-1.0 minor
+bumps as the place breaking changes may land.
+
+## [0.6.2] — 2026-07-24
+
+### Changed
+- Gem metadata now points at the actual repository rather than reusing the homepage:
+  `source_code_uri`, `bug_tracker_uri`, and `changelog_uri` all resolve to
+  <https://github.com/avonderluft/bible270>.
+- `rubygems_mfa_required` is set, so pushes to rubygems.org require MFA.
+
+### Added
+- This changelog, packaged with the gem.
+
+## [0.6.1] — 2026-07-24
+
+### Changed
+- Author and copyright now read "Andrew vonderLuft".
+- The display-name-from-email example in the docs and tests uses a neutral address, since the
+  algorithm can't recover internal capitals and shouldn't be shown rendering a real name wrongly.
+
+## [0.6.0] — 2026-07-24
+
+### Added
+- **Passwordless email sign-in**, so readers without a GitHub/Google/etc. account can take part.
+  A reader enters their address, receives a single-use link, and clicks it — no password anywhere
+  in the gem.
+  - Tokens are 256-bit and URL-safe, expire after 20 minutes (`email_sign_in_ttl`), and are stored
+    **only as a SHA-256 digest**, so the table is useless to anyone reading the database.
+  - Claiming a link is a conditional `UPDATE`, so a double-clicked link cannot sign in twice.
+  - The "check your inbox" response is identical for known, unknown, and rate-limited addresses:
+    no account enumeration and no signal that a limit was hit.
+  - Rate limited per address per window (`email_sign_in_max_per_window`, `email_sign_in_window`).
+  - Readers may choose the display name shown beside their reflections
+    (`email_sign_in_ask_name`); otherwise it is derived from the address.
+  - `Bible270::SignInToken.sweep!` clears spent and stale rows from a cron or rake task.
+- `Bible270::EmailSignIn` — Rails-free module holding the normalization and token logic, so the
+  security-relevant parts are unit testable on their own.
+- `Bible270::SignInMailer` with text and HTML magic-link templates. The sign-in URL is built by the
+  controller, so the mailer needs no `default_url_options`.
+- `Bible270::Reader.from_email`, using the same identity columns as OmniAuth with `provider: "email"`,
+  so every reader is treated identically downstream.
+- New table: `bible270_sign_in_tokens` (migration `20260101000004`).
+- `config.any_sign_in_method?`, letting views detect a deployment with no sign-in configured.
+
+### Fixed
+- `display_name_from` raised `ArgumentError` on any address containing an underscore:
+  `tr("._-+", …)` was parsed as a character range. The hyphen now comes last.
+
+### Requirements
+- Email sign-in needs working Action Mailer delivery in the host application. Set
+  `config.mailer_from`. Delivery is inline by default; set `email_sign_in_deliver_later` if a
+  queue backend is available.
+
+## [0.5.0] — 2026-07-24
+
+### Added
+- Built-in OmniAuth sign-in is now fully wired as the primary auth path.
+- `config.omniauth_providers` accepts symbols or `[provider, label]` pairs, with labels for common
+  providers and titleisation for anything custom.
+- Sign-in page at `GET <mount>/sign_in` listing every configured provider.
+- Sign-in controls carry the current path as `origin`, so a reader who clicks a check-off while
+  signed out returns to that same day. Origins are validated as local paths only.
+- `rails generate bible270:install`, which writes both initializers with OmniAuth's `path_prefix`
+  already aligned to the mount point, adds the `mount` line, and prints the callback URL to register.
+- `omniauth` (>= 2.0) and `omniauth-rails_csrf_protection` (>= 1.0) as runtime dependencies. Provider
+  strategy gems remain the host's choice.
+
+### Fixed
+- **Sign-in was broken.** The header rendered a GET link to `/auth/github`, but OmniAuth 2.0 disabled
+  GET on the request phase (CVE-2015-9284). All sign-in controls are now POST forms with CSRF tokens.
+  The old link also contained a dead ternary and hardcoded the provider.
+- Open-redirect hardening on the `origin` parameter: protocol-relative URLs, backslashes (which
+  browsers may normalise to slashes), and auth routes are all rejected.
+- `reset_session` on sign-in and sign-out, against session fixation.
+- `Reader.from_omniauth` no longer assumes an `OmniAuth::AuthHash`; it tolerates plain hashes and
+  missing `info`, and returns `nil` rather than raising on a malformed payload.
+
+### Changed
+- `sign_out` is `DELETE` only (previously `GET` or `DELETE`).
+- Guarded actions redirect to the sign-in page instead of `request.referer`.
+
+## [0.4.0] — 2026-07-24
+
+### Added
+- **Configurable start dates.** `config.start_date` sets a community-wide cohort date (accepting a
+  `Date`, `Time`, or `"YYYY-MM-DD"` string); `config.allow_reader_start_date` controls whether
+  individuals may set their own. The four combinations give undated, per-reader, community-with-
+  override, and fully pinned modes.
+- Readers manage their own date from the overview (`PATCH`/`DELETE <mount>/start-date`).
+- Calendar mapping as pure functions on `Bible270::Plan`: `date_for`, `day_for` (clamped by default,
+  `clamp: false` to detect out-of-range), `end_date_for`, `before_start?`, `after_end?`, `to_date`.
+- Day pages show their calendar date with a **Today** badge; the overview gains a "Go to today" link
+  and a pace indicator ("3 days behind", "right on pace", "begins in 12 days").
+
+### Notes
+- Check-offs and comments are keyed to day numbers, never dates, so changing a start date only
+  re-maps the calendar — no reading history moves or is lost.
+- A malformed `config.start_date` degrades to `nil` rather than raising at boot; the controller does
+  reject bad input with a flash message.
+
+## [0.3.1] — 2026-07-24
+
+### Fixed
+- **Ruby 4.0 compatibility.** Dropped the `cgi` dependency: the CGI library was removed from Ruby's
+  default gems in 4.0 (only `cgi/escape` remains), so `require "cgi"` emits a deprecation warning
+  there. URL escaping now uses `URI.encode_www_form_component`, which produces byte-identical output
+  to `CGI.escape` and relies only on `uri`, a stable default gem.
+
+### Added
+- Regression test asserting the gem never loads the `cgi` library.
+- Compatibility notes in the README: audited against the Ruby 4.0 breaking changes (`Set`/`SortedSet`,
+  `Ractor`, `Net::HTTP`, `Process::Status`, `ObjectSpace`, and the gems promoted from default to
+  bundled). Every file carries a `frozen_string_literal` comment and the suite passes with
+  `--enable-frozen-string-literal` forced.
+
+## [0.3.0] — 2026-07-24
+
+### Changed — BREAKING
+- **Renamed from `bible_reading_plan` to `bible270`.** Module `Bible270`, tables `bible270_*`,
+  migrations `CreateBible270*`, CSS and helper prefix `b270`, install task
+  `bible270:install:migrations`, mount `Bible270::Engine`. Table names changed, so this is a fresh
+  install rather than an upgrade.
+- **The New Testament is now read twice.** Each pass gets its own half of the plan (135 days), so
+  Revelation lands on day 135 and again on day 270. Whole chapters are verse-balanced within each
+  pass, tightening NT days from 11–140 verses to 20–104. The NT track now has content every day, so
+  there are no rest days and all three tracks are present on all 270 days.
+- **Chapters are kept whole.** Only a chapter longer than `PP_LONG_CHAPTER` (100 verses) is divided,
+  which in the whole Psalter and Proverbs is Psalm 119 alone — split into exactly two readings
+  (1–88, 89–176). Psalms 78 and 89 are no longer split. Short chapters merge with a neighbour, so
+  Psalm 117 reads as "Psalm 116–117" rather than occupying a two-verse day.
+- The Psalms/Proverbs companion resolves to exactly 135 portions, making two complete passes across
+  270 days and finishing on Proverbs 31 — so all three tracks finish together at the halfway mark
+  and at the end.
+
+### Added
+- `Plan.nt_days_per_pass`, `nt_second_pass_start_day`, `nt_verse_loads`, `pp_cycle_length`,
+  `pp_base_portions`, and tuning constants documented in the README.
+
+## [0.2.0] — 2026-07-24
+
+### Changed
+- **Daily portions are balanced by verse count, not chapter count**, so each day takes roughly the
+  same time to read. Previously a day on Psalm 119 (176 verses) counted the same as a day on Psalm
+  117 (2 verses).
+- Old Testament days are grouped to be even in verses (avg ~73/day).
+
+### Added
+- `Bible270::Versification` — per-chapter verse counts for all 66 books, generated from a
+  public-domain KJV text and validated against canonical anchors (1,189 chapters; Psalms 2,461
+  verses; Proverbs 915; Psalm 119 = 176; Psalm 117 = 2). Verse counts are facts about the text's
+  structure, so nothing copyrighted is bundled.
+
+### Fixed
+- Per-track progress bars compared days checked against *chapter* totals, so the Old Testament bar
+  could never exceed ~36%. Renamed `chapters_read_in` to `days_read_in` and made the totals
+  day-based.
+
+## [0.1.0] — 2026-07-24
+
+### Added
+- Initial release: a mountable Rails engine providing a 270-day Bible reading plan with three daily
+  tracks (Old Testament, New Testament, Psalms/Proverbs).
+- Per-reader check-offs, public per-day reflections, a community leaderboard, and reader profiles.
+- Two identity paths: built-in session sign-in, or bridging the host application's users via
+  `config.current_reader_resolver` and `Reader.for_owner`.
+- The schedule is pure, deterministic Ruby — no rows are stored for the plan itself; the database
+  holds only readers, check-offs, and comments.
+
+[0.6.2]: https://github.com/avonderluft/bible270/releases/tag/v0.6.2
+[0.6.1]: https://github.com/avonderluft/bible270/releases/tag/v0.6.1
+[0.6.0]: https://github.com/avonderluft/bible270/releases/tag/v0.6.0
+[0.5.0]: https://github.com/avonderluft/bible270/releases/tag/v0.5.0
+[0.4.0]: https://github.com/avonderluft/bible270/releases/tag/v0.4.0
+[0.3.1]: https://github.com/avonderluft/bible270/releases/tag/v0.3.1
+[0.3.0]: https://github.com/avonderluft/bible270/releases/tag/v0.3.0
+[0.2.0]: https://github.com/avonderluft/bible270/releases/tag/v0.2.0
+[0.1.0]: https://github.com/avonderluft/bible270/releases/tag/v0.1.0

data/MIT-LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Andrew vonderLuft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,373 @@
+# 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.
+- **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.
+
+## Install
+
+Add to the host app's `Gemfile`:
+
+```ruby
+gem "bible270", path: "vendor/gems/bible270"
+# or, once pushed to a git remote:
+# gem "bible270", git: "https://github.com/avonderluft/bible270.git", branch: "main"
+```
+
+Then:
+
+```bash
+bundle install
+bin/rails bible270:install:migrations
+bin/rails db:migrate
+```
+
+Mount it in `config/routes.rb`:
+
+```ruby
+mount Bible270::Engine, at: "/reading-plan"
+```
+
+The plan is now live at `/reading-plan`.
+
+---
+
+## Authentication
+
+Two built-in ways to sign in, so **nobody is excluded**:
+
+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.
+
+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.
+
+### Email sign-in
+
+```ruby
+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
+end
+```
+
+The host app needs working Action Mailer delivery — nothing else. How it behaves:
+
+- 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.
+
+An email reader gets `provider: "email"` in the same identity columns OmniAuth uses, so downstream
+(progress, comments, leaderboard) treats every reader identically.
+
+### OmniAuth social sign-in
+
+### Quick setup
+
+```bash
+bin/rails generate bible270:install --mount-at=/reading-plan --providers=github
+```
+
+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:
+
+```ruby
+# Gemfile — omniauth and omniauth-rails_csrf_protection come in with bible270;
+# the provider strategy is your choice:
+gem "omniauth-github"
+```
+
+```bash
+bundle install
+bin/rails bible270:install:migrations && bin/rails db:migrate
+```
+
+Finally register the callback URL with the provider:
+
+```
+https://gknt.org/reading-plan/auth/github/callback
+```
+
+### Manual setup
+
+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:
+
+```ruby
+# config/initializers/omniauth.rb
+Rails.application.config.middleware.use OmniAuth::Builder do
+  path_prefix "/reading-plan/auth"          # == <mount point>/auth
+  provider :github, ENV["GITHUB_CLIENT_ID"], ENV["GITHUB_CLIENT_SECRET"]
+end
+
+OmniAuth.config.on_failure = proc { |env| Bible270::SessionsController.action(:failure).call(env) }
+```
+
+```ruby
+# config/initializers/bible270.rb
+Bible270.configure do |config|
+  config.omniauth_providers = [:github]              # or [:github, [:google_oauth2, "Google"]]
+  config.parent_controller  = "::ApplicationController"
+end
+```
+
+### Notes 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.
+
+### Alternative: bridge your host's 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:
+
+```ruby
+config.current_reader_resolver = lambda do |controller|
+  user = controller.send(:current_user)
+  next nil unless user
+  Bible270::Reader.for_owner(user, display_name: user.try(:name) || user.email,
+                             email: user.try(:email), avatar_url: user.try(:avatar_url))
+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.
+
+## Start dates
+
+The plan works either **undated** (day numbers only) or **dated** (day numbers mapped onto a
+calendar). There are two levers:
+
+```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)
+
+  # 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
+```
+
+How the two combine:
+
+| `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. |
+
+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.
+
+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.
+
+The date helpers are pure functions on `Bible270::Plan`, so you can use them 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
+```
+
+## Configuration reference
+
+```ruby
+Bible270.configure do |config|
+  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.parent_controller = "ActionController::Base"      # or "::ApplicationController"
+  config.layout            = "bible270/application"
+
+  config.email_sign_in = true                              # passwordless email link
+  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.require_sign_in_to_participate = true
+
+  config.after_sign_in_path  = nil                         # defaults to plan root
+  config.after_sign_out_path = nil
+
+  config.bible_version = "ESV"
+  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
+
+ComfortableMediaSurfer serves marketing/content pages; this engine is a separate
+mounted app. Two integration styles:
+
+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.
+
+---
+
+## Data model
+
+| Table | Purpose |
+|-------|---------|
+| `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 |
+
+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).
+
+## Routes (within the mount point)
+
+```
+GET    /                         days#index      overview + community + calendar
+GET    /day/:day                 days#show       three readings, completers, 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)
+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
+```
+
+## Tuning the plan shape
+
+The whole schedule is derived from a handful of constants in `Bible270::Plan`, so the shape
+can be changed without touching anything else:
+
+| 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 |
+
+Everything is computed at load time and memoized; there is no generated schedule to migrate
+if you change these.
+
+## Scaling note
+
+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.
+
+## Development / tests
+
+The deterministic plan logic is fully unit-tested with no Rails dependency:
+
+```bash
+bundle install
+rake test
+```
+
+## License
+
+MIT. See `MIT-LICENSE`.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+require "bundler/gem_tasks" # provides build / install / release
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.pattern = "test/**/*_test.rb"
+  t.warning = false
+end
+
+task default: :test

data/app/controllers/bible270/application_controller.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+module Bible270
+  class ApplicationController < Bible270.config.parent_controller.constantize
+    layout :bible270_layout
+
+    helper_method :current_reader, :signed_in?, :b270_config
+
+    private
+
+    def bible270_layout
+      Bible270.config.layout
+    end
+
+    def b270_config
+      Bible270.config
+    end
+
+    def current_reader
+      return @current_reader if defined?(@current_reader)
+
+      @current_reader =
+        if (resolver = Bible270.config.current_reader_resolver)
+          resolver.call(self)
+        elsif (id = session[:bible270_reader_id])
+          Reader.find_by(id: id)
+        end
+    end
+
+    def signed_in?
+      current_reader.present?
+    end
+
+    # Guard participation (checking off / commenting). Viewing is always open.
+    def require_reader!
+      return true if signed_in?
+      return true unless Bible270.config.require_sign_in_to_participate
+
+      respond_to do |format|
+        format.turbo_stream { head :unauthorized }
+        format.html do
+          redirect_to sign_in_path(origin: request.fullpath),
+                      alert: "Please sign in to take part."
+        end
+      end
+      false
+    end
+  end
+end

data/app/controllers/bible270/checkoffs_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+module Bible270
+  class CheckoffsController < ApplicationController
+    def toggle
+      return unless require_reader!
+
+      @day   = params[:day].to_i
+      @track = params[:track].to_s
+
+      unless Plan.valid_day?(@day) && Plan.present_tracks(@day).include?(@track)
+        head :bad_request and return
+      end
+
+      existing = current_reader.checkoffs.find_by(day: @day, track: @track)
+      if existing
+        existing.destroy
+      else
+        current_reader.ensure_started!
+        current_reader.checkoffs.create(day: @day, track: @track)
+      end
+
+      @reader = current_reader.reload
+      @reader_tracks = @reader.read_tracks_for(@day)
+      @readings = Plan.readings_for(@day)
+
+      respond_to do |format|
+        format.turbo_stream
+        format.html { redirect_to day_path(@day) }
+      end
+    end
+  end
+end