Pitch the production dead-code mode before explaining it

The README's closing paragraph and the top of docs/Production.md
described the mode without saying why anyone would want it. Both now
lead with the case: tests cannot prove code is needed and static
analysis cannot prove Ruby is unused, so a window of real traffic is
the strongest deletion evidence available, gathered at near-zero
overhead by oneshot coverage. The cross pays out twice, as a deletion
list with the evidence window attached and as a priority list of
untested code production actually runs. The doc's mechanics now sit
under an explicit how-to heading after the why, with the linked
subsection anchors unchanged.

The wording borrows the field's own messaging. Coverband promotes
itself on production code usage and the least possible performance
impact, and the oneshot coverage proposal motivated the feature as a
replacement for planting a log line in suspect code and watching
production, so the pitch speaks that language: the log-line experiment
run for every line at once, full speed once a line has fired, every
kind of process feeding one store, and the cross turning the record
into insight you can act on.

Author: sferik

README.md

@@ -128,7 +128,162 @@ end
 Every option is documented in [docs/Configuration.md](docs/Configuration.md),
 including criteria, filters, groups, profiles, and thresholds.
 
-Measuring coverage in production to find dead code is its own mode with its
-own document, [docs/Production.md](docs/Production.md): a live process
-accumulates what real traffic executes, and `simplecov dead-code`, the HTML
-report, and `coverage.json` cross that with what the tests cover.
+## Tracking which test covers each line
+
+Coverage normally tells you whether a line ran, not what ran it. `track_tests`
+records the other half of the story:
+
+```ruby
+SimpleCov.start do
+  track_tests
+end
+```
+
+RSpec examples and Minitest tests are wrapped automatically. In the HTML
+report, covered lines that no test executed (they only ran at load time, or in
+suite setup) drain to a distinct tint, so coverage that merely *loads* code
+stops passing for coverage that *tests* it, and clicking a line's badge lists
+the tests that cover it. The same recording answers from the terminal:
+
+```sh
+$ simplecov tests lib/simplecov/result.rb:42
+spec/result_spec.rb:42
+```
+
+The output is one test id per line and nothing else, so it pipes straight into
+a runner. `simplecov tests --redundant` inverts the question, listing the
+tests whose covered lines other tests also cover, which is where a
+[test-pruning session](docs/Redundant_Tests.md) starts. Recording has a real
+cost, which is why it's opt-in and comes with levers to control it. See
+[the configuration docs](docs/Configuration.md#tracking-which-test-covers-each-line).
+
+## Finding dead code in production
+
+SimpleCov can also measure production code usage, the surest way to find
+dead code. The old trick was to plant a log line in a suspect method and
+watch production for a while. Oneshot coverage runs that experiment for
+every line at once: a line reports its first execution and nothing after,
+so a live process records what real traffic uses with the least possible
+impact on performance. `simplecov dead-code` then crosses the recording
+with the test report and turns it into insight you can act on. Code
+neither tests nor traffic touch is safe to delete, and code production
+runs but tests skip is the most valuable test you haven't written. The
+HTML report and `coverage.json` include the same production data. See
+[docs/Production.md](docs/Production.md) for more details on why and how
+to set it up.
+
+## Coverage of just your change
+
+An overall number moves slowly on a mature codebase, but "is the code in this
+change tested?" has a crisp answer the day you ask it. `simplecov patch` reads
+the git diff against a base ref and scores only the lines you touched:
+
+```sh
+$ simplecov patch --base main --minimum 100
+   88.00% (22/25) lines  lib/simplecov/cli/patch.rb  missing 41-43
+  100.00% (4/4) lines    lib/simplecov/result.rb
+  Patch coverage:  89.66% (26/29) lines
+```
+
+`--minimum` turns it into a gate, so a project that can't lift its overall
+number in one pull request can still require that everything it adds is
+covered. The flip side is `simplecov affected`, which uses a `track_tests`
+recording to select the tests that touch your changed code and hand them to
+the runner, falling back (loudly) to the full suite whenever the map can't be
+trusted:
+
+```sh
+$ simplecov affected --base main --run bundle exec rspec
+```
+
+Both commands are documented in [the CLI docs](docs/CLI.md).
+
+## Covering views
+
+View templates execute real logic, and now they can be part of the report.
+`cover_views` brings ERB, Haml, and Slim templates in, measured through eval
+coverage (CRuby 3.2+):
+
+```ruby
+SimpleCov.start 'rails' do
+  cover_views
+end
+```
+
+Templates are ordinary files in the report, highlighted in their own language
+and grouped under Views by the `rails` profile, and a template no test renders
+shows up at 0% instead of being quietly missing. Expect your overall number to
+drop the first time you turn this on. That's the point. See
+[view coverage](docs/Configuration.md#view-coverage).
+
+## A consistent configuration grammar
+
+The configuration API was redesigned around a small set of consistent verbs.
+Formatters are picked by name, thresholds live in a per-criterion `coverage`
+block where scope is a uniform `per:` argument, and misses can be capped as
+absolute counts rather than ratios:
+
+```ruby
+SimpleCov.start do
+  formats :html, :json
+
+  coverage :line do
+    minimum 90
+    minimum 100, per: "lib/simplecov/result.rb"
+    maximum_missed 5, per: :file     # no file may carry more than 5 uncovered lines
+  end
+
+  coverage :branch, minimum: 80, ignore: :implicit_else
+end
+```
+
+Everything you're using today keeps working. Legacy spellings warn and name
+their replacement, and once you've migrated, `deprecations :raise` turns any
+old spelling that creeps back in into an error. The
+[migration map](docs/Configuration.md#migrating-from-the-legacy-configuration-api)
+has the full before and after.
+
+## Per-file ratchets and coverage history
+
+On a legacy codebase, one per-file minimum does nothing useful: set it to what
+the worst file scores and every other file is allowed to sink to that level.
+`simplecov ratchet` writes a checked-in baseline instead, giving each file its
+own floor at the coverage it has already reached:
+
+```sh
+$ simplecov ratchet
+simplecov ratchet: wrote .simplecov_baseline.yml (3 tightened, 1 pruned, 148 unchanged)
+```
+
+Floors only ever tighten, so touching a legacy file drags its coverage upward
+and it can never slide back. Think `.rubocop_todo.yml`, applied to coverage.
+To ratchet automatically at the end of every run, add the baseline formatter
+with `formats :html, :baseline`.
+
+Alongside the floors, every successful run now appends to
+`coverage/.history.json`, so you have a recorded trend rather than just the
+last number. `simplecov history` draws it as sparklines in the terminal, and
+`drop_baseline :median` judges coverage drops against the recorded median
+instead of whatever the previous run happened to score. See
+[the baseline](docs/Configuration.md#per-file-baseline-ratchet) and
+[run history](docs/Configuration.md#run-history) docs.
+
+## More from the command line
+
+The `simplecov` CLI has grown from a report opener into a toolbelt. A few
+favorites:
+
+```sh
+$ simplecov watch bundle exec rspec   # re-run on save, live-reload the served report
+$ simplecov show lib/foo.rb           # annotated source in the terminal
+$ simplecov status                    # is this report fresh, and for which commit?
+$ simplecov uncovered --missing       # worst files, with the exact line ranges to test
+$ simplecov badge --output badge.svg  # a shields.io-style SVG, no badge service needed
+```
+
+`watch` deserves the highlight: with a `track_tests` recording in the report,
+a save re-runs only the tests that touch the files you changed, which turns
+the report into something you keep open while writing the test. There is also
+shell tab completion (`simplecov completions fish|bash|zsh`), a man page, and
+a real `--help` on every command. The full tour is in
+[docs/CLI.md](docs/CLI.md).

docs/Production.md

@@ -4,14 +4,34 @@ Measure what real traffic executes, and cross it with the test report to find de
 
 *Part of the [SimpleCov](../README.md) documentation.*
 
-## Coverage in production
-
-Oneshot lines coverage is cheap enough to leave running in production: each line reports its first execution and
-nothing after, so the steady-state overhead is near zero. `SimpleCov::Production` turns that into a supported mode: a
-live process measures which of its lines ever run and drains the measurements to a shared store on an interval, and
-`simplecov dead-code`, the HTML report, and `coverage.json` later cross that store with what the tests cover. The
-union of a test suite and real traffic answers a question neither answers alone, and coverage over a long enough
-window is far better evidence for deleting Ruby than any static analysis of it.
+## Why measure coverage in production
+
+Every codebase that has lived a few years carries code nobody is sure about. It has tests, the tests pass, and still
+no one can say whether anything real ever calls it, so it survives every cleanup and keeps taxing every reader, every
+upgrade, and every security audit. The traditional way to find out is to plant a log line in the suspect code and
+watch production for a while, one candidate at a time. Production coverage runs that experiment automatically, for
+every line at once, with nothing added to the code under suspicion.
+
+Nothing else settles the question. A test suite cannot, because a test proves code works, not that anything needs it,
+and dead code's own spec is usually green, which makes the suite the dead code's best defender. Static analysis
+cannot either, because Ruby resolves calls at runtime. Watching real traffic is the only evidence there is, and
+oneshot lines coverage collects it with the least possible impact on performance: each line reports its first
+execution and nothing after, so once a line has fired the process runs at full speed, and the steady-state overhead
+of measuring for weeks is near zero. Any Ruby process can measure, so web workers, background jobs, and scheduled
+tasks all pour their slice of the truth into the same store.
+
+What accumulates is a record of production code usage, and crossing it with the test report turns it into insight
+you can act on. Code that neither tests nor traffic touched is dead, and `simplecov dead-code` prints it with the
+evidence window attached, a deletion list you can trust. Code that production runs but no test covers is the most
+valuable test you have not written yet, a priority list. And where the store carries `last_seen` stamps, each
+candidate comes dated: "this file last ran in March" argues for deletion far better than a bare uncovered bit ever
+could.
+
+## How to set it up and use it
+
+`SimpleCov::Production` is the supported mode behind all of this: a live process measures which of its lines ever run
+and drains the measurements to a shared store on an interval, and `simplecov dead-code`, the HTML report, and
+`coverage.json` later cross that store with what the tests cover.
 
 Nothing here runs unless explicitly started, and `require "simplecov/production"` loads none of the reporting
 machinery, no formatters, and no at-exit report. A process that starts production coverage gets a measurement tap and