docs: lead with the case a lock cannot cover

CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.14.2 - 2026-08-25
+
+- Rewrite the first screen around the objection a reader actually has. The
+  README led with a counter incrementing an integer, which invites the reply
+  that one line of SQL already does it. It now leads with the ticket sale from
+  the homepage: 100 seats, a hold, a ten-minute expiry that frees the seat, and
+  a live count. That is the smallest example needing three things from one
+  number, and the three things are the argument.
+- Answer "why not just use transactions?" in the first screen rather than at
+  line 1245 of a 1370-line file. The section concedes `with_lock` first, then
+  argues scope rather than discipline: any `expires_at` or `scheduled_at`
+  column is evidence the critical section already outlived the lock, and what
+  follows it is a sweeper and a race. The comparisons table gains the row
+  people actually reach for.
+- Add "Is it worth installing here?", which names who should not install this,
+  and point readers with high-QPS reads or hot identities at
+  [Solid Objects Pro](https://solidobjects.pro/).
+- Fix the reactive example, which could not run. A scalar observable raises
+  unless it is declared `broadcast: :value`, and a component dependency must
+  itself be a declared observable. The example now declares both. The reactive
+  section also claimed a fragment is re-rendered once per change; the turn
+  records the broadcast atomically, while delivery retries and is at least
+  once.
+- Cut the README from 1370 to about 580 lines by moving reference material into
+  `docs/`, and add `CONTRIBUTING.md`. Reminders now have their own guide at
+  `docs/reminders.md`, `docs/operations.md` gains the configuration defaults
+  table, the worker-count flags, the upgrade sequence and the extension
+  component contract, and `docs/architecture.md` gains `register_effect` and
+  `register_commit_action` with their signatures.
+
 ## 0.14.1 - 2026-08-24
 
 - Register application actors in every process that boots the application.

CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing
+
+Solid Objects changes can affect durable state and recovery. A contribution
+should explain the invariant it changes and include a regression test at the
+lowest layer that can prove it.
+
+## Setup
+
+Install Ruby 3.3 or newer and Rails 7.1 or newer, then install the locked
+dependencies:
+
+```bash
+bundle install
+```
+
+The full database matrix needs SQLite 3.35 or newer, PostgreSQL 14 or newer,
+and MySQL 8.0 or newer on InnoDB. Use disposable databases. Do not include
+credentials, production data, customer identifiers, or other personal
+information in fixtures or reports.
+
+## Validation
+
+Run the local quality gates before opening a pull request. `bundle exec rake`
+runs the Minitest suite against SQLite, Standard Ruby, the Solid Queue RuboCop
+policy, RBS generation and validation, Steep, and Brakeman:
+
+```bash
+bundle exec rake
+```
+
+Run the adapter suites against a real server before changing anything that
+touches locking, claiming, or schema:
+
+```bash
+SOLID_OBJECTS_DATABASE_URL=postgresql://localhost/solid_objects_test bundle exec rake test
+SOLID_OBJECTS_DATABASE_URL=mysql2://localhost/solid_objects_test bundle exec rake test
+```
+
+A skipped test looks exactly like a passing one in the summary line, so check
+the skip count when a change touches an adapter.
+
+## Writing the test first
+
+Start a behavioral change with a focused failing test, watch it fail, and quote
+the observed failure in the pull request. A test that has never failed has not
+been shown to test anything. When a change fixes a defect, revert the fix and
+confirm the test fails for the expected reason rather than some other one.
+
+Exercise locking, leases, fencing, and claiming against real database adapters.
+Synchronize races with queues, barriers, or condition variables instead of
+arbitrary sleeps.
+
+## Correctness changes
+
+For mailbox, lease, fencing, retry, effect, reminder, or migration changes,
+include the failure sequence the test exercises. Update
+[Correctness and delivery semantics](docs/correctness.md) when a guarantee or
+limitation changes, and [the roadmap](docs/roadmap.md) when the change alters
+what the project claims about itself.
+
+## Style
+
+Ruby source carries inline RBS annotations, so every owned file enables
+`# rbs_inline: enabled` and annotates methods with `# @rbs`. Prefer early
+returns, descriptive names over abbreviations, and options over boolean
+parameters. Keep database behavior portable across SQLite, PostgreSQL, and
+MySQL.
+
+Use concise imperative commit subjects under 50 characters, prefixed with
+`fix:`, `docs:`, `ci:`, or `chore:` where one applies. Explain why the change
+is needed rather than restating what it does.
+
+## Reporting a vulnerability
+
+Report security issues privately through
+[GitHub security advisories](https://github.com/cardmagic/solid-objects-ruby/security/advisories/new)
+rather than a public issue.

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    solid_objects (0.14.1)
+    solid_objects (0.14.2)
       actioncable (>= 7.1)
       actionpack (>= 7.1)
       actionview (>= 7.1)
@@ -384,7 +384,7 @@ CHECKSUMS
   rubocop-rails-omakase (1.1.0) sha256=2af73ac8ee5852de2919abbd2618af9c15c19b512c4cfc1f9a5d3b6ef009109d
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
-  solid_objects (0.14.1)
+  solid_objects (0.14.2)
   sqlite3 (2.9.5-aarch64-linux-gnu) sha256=78075b6337d3d182c6d2b4691049ed45cd220826160c9ea18946bf6a1de200dc
   sqlite3 (2.9.5-aarch64-linux-musl) sha256=18c801185deb4adc01ddb281e8f672a39e3d1729979ca91e39439cd3eac0402d
   sqlite3 (2.9.5-arm-linux-gnu) sha256=1bdfca0c7d63998c60b0f4a8e3c8df2d33800ccc4abd2d612eddbbbc92a4c48b