clickwrap 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be18f8fc09eee066b71a234a134440010c6cf2beb82987b4bbe3636dde2f9133
-  data.tar.gz: a2c66a9be09cf999de30d890c4338e084146414cadbe0747022a3aedc8a4ef5f
+  metadata.gz: 55f77c92e4ac5400a7c7fba781bd2a592875f3deef59fd8b3c1d6269e302ffc6
+  data.tar.gz: f15af7f288d8349bc8cd322b28b472e68bca750a8c17718648d7fa2db3877021
 SHA512:
-  metadata.gz: 891f939a6b827915a5d2703ecf98b0ed9b9e761d3689a1117e8ba3df6ae0450c50a3f9d53edd0cbf844e996a7be447b080070b6ab2d916409b5d1ecfdc851ddc
-  data.tar.gz: 2387391b3d960d05dcdc783221bb5653de21406ecd0173b8fbafa1dc17d716549044a22bc719740892553b8a9c66beb8b42417c61e9bc7f585d569849fa43d9d
+  metadata.gz: fceb30a214fe8e4cdfcc19a775f8082fefe61424eba2e463958240dec07a0c8d099e1d3c6e5e0b9d67bd47eb11a445ee591f4b520c08f847479fbed277f197f2
+  data.tar.gz: e8d53673c7a5d9ba553078ace895a187e404b6a486525ee56d362f584e262f3bb9f9000287bf57311b22a40e2049140867f5eefdb300e945a7d69d25ff31dcf4

data/CHANGELOG.md

@@ -6,6 +6,210 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-08-20
+
+### Changed — the rest of the collection friction, and the principle behind removing it
+
+0.3.0 made *enabling* request evidence one switch and gave the initializer
+defaults honest gem-supplied purposes. It left the friction standing
+everywhere else: a policy-level `record_ip_address` still read as though it
+wanted a sentence, `record_ip_geolocation` refused to do anything without a
+field list, and the encryption escape hatch still demanded a reason be
+phrased twice. This finishes the job the owner asked for.
+
+The principle, in their words: **the host application and its privacy policy
+own *why* data is collected; this gem records *what* was collected, honestly,
+and is nobody's nanny.** Its job is evidence mechanics, not gatekeeping
+collection. Everything below now works exactly as written:
+
+```ruby
+Clickwrap.configure do |config|
+  config.record_request_evidence_by_default = true
+  config.keep_recorded_ip_addresses_indefinitely!
+  config.deliberately_store_request_evidence_unencrypted!
+end
+
+Clickwrap.policy :anything do
+  agree_to :terms
+  record_ip_address
+  record_browser_user_agent
+  record_ip_geolocation
+end
+```
+
+- **All three `record_` verbs take zero keyword arguments.** `because:`,
+  `legal_basis_reference:`, `data_protection_impact_assessment_reference:`,
+  `delete_after:`, `retain_until:`, and `encrypted:` are optional in fact and
+  not merely in the signature — nothing downstream refuses their absence.
+  (`legal_basis_reference` and the DPIA reference never were required anywhere
+  in the gem; a test now pins that they never become so.)
+- **`record_ip_geolocation` with no field named records the coarse trio** —
+  country, region, city — the same set `record_request_evidence_by_default`
+  turns on, and nothing finer. The field keywords moved from `false` to `nil`
+  defaults so "did not mention this field" is distinguishable from "named it
+  and turned it off". Naming even one field means you are choosing the set
+  yourself, and the set is exactly what you named. Naming every field `false`
+  is still refused, because calling the verb and disabling everything cannot
+  mean anything; `do_not_record_ip_geolocation` is how to say that.
+- **`keep_recorded_{ip_addresses,browser_user_agents,ip_geolocation}_indefinitely!`
+  take no arguments at all.**
+- **`deliberately_store_request_evidence_unencrypted!` no longer needs a
+  `because:`.** The method NAME is the ceremony: `encrypt_recorded_* = false`
+  still cannot be reached without writing that line, and a reviewer still
+  finds it in the diff. When the host writes no reason the gem records
+  `Vocabulary::DEFAULT_REASON_FOR_STORING_REQUEST_EVIDENCE_UNENCRYPTED`.
+  Encryption itself is untouched — on by default for all three categories,
+  with a test pinning that the one switch does not weaken it.
+- **The install generator stops refusing an incomplete category.**
+  `--record-ip-addresses-by-default` with no reason and no period writes the
+  file and simply omits those two lines, so the gem's own defaults apply.
+- The `ReviewedText` placeholder check now only ever applies to text a host
+  actually supplied. Absence is never scaffolding.
+
+### Unchanged, deliberately
+
+- Reasons that are not about *collection* keep their required `because:`:
+  `delete_recorded_ip_address!` and its siblings, `dispose_core_event!`,
+  `place_on_legal_hold!` / `release_legal_hold!`, `plan_disposition_for`,
+  unredacted receipt export, and the lifecycle verbs. Those record a
+  destructive act, an access, or a state change — there the audit trail *is*
+  the reason, and there is no honest default for "why did somebody delete
+  this".
+- Still refused, because each is the host contradicting themselves rather than
+  leaving a blank: scaffolding text the host actually wrote standing in for a
+  purpose (including in the installer, where a `TODO` in a shipped initializer
+  is worse than no line and the gem would reject it at boot anyway), a
+  negative deletion period passed to the installer, a deletion clock declared
+  alongside `keep_recorded_..._indefinitely!` for the same category, and
+  `record_ip_geolocation` with every field explicitly off.
+- The gem's code default is still record-nothing. Claim boundaries, receipt
+  state labeling (`not_configured` / `unavailable` / `recorded` /
+  `deleted_after_retention`), and every released receipt format are untouched.
+
+### Documentation
+
+- README, `guides/request-evidence.md`, and `guides/naming.md` show the
+  zero-keyword forms as the ordinary way to write a policy, with purposes,
+  legal bases, and clocks as the upgrade path.
+- `CLAUDE.md` / `AGENTS.md` rule 6 is rewritten around the principle above and
+  records the owner directive and its date. What it keeps as non-negotiable:
+  never a switch whose NAME hides what it collects, never an overclaim, never
+  a blurred receipt state, encryption on by default behind its named call,
+  host-supplied scaffolding rejected, and contradictions refused.
+
+## [0.3.0] - 2026-08-20
+
+### Changed — recording request evidence is one switch, not a checklist
+
+Owner directive, and a deliberate reversal of part of this gem's own
+philosophy. The reasoning, stated plainly so a future reader can weigh it:
+the ceremony around *enabling* request evidence — a written purpose, a
+disposal answer, and a reviewed trusted-proxy digest, each of them a boot
+refusal — was not producing better-reviewed collection. It was producing
+**no collection at all**. Integrators hit three refusals in a row on the way
+to their first capture and turned the fields off, and an agreement with no
+corroboration is worse evidence than one corroborated under a purpose the gem
+stated on their behalf. So the friction is gone from turning collection *on*.
+None of it is gone from describing collection honestly.
+
+- **`config.record_request_evidence_by_default = true`.** One line records, on
+  every policy, the IP address the request arrived from, the browser user
+  agent it sent, and a coarse country / region / city estimate for that
+  address. Nothing finer: a postal code, coordinates, a timezone, a continent,
+  a metro code, and an accuracy radius each remain their own separately named
+  setting. It is a fan-out setter over the existing `record_*_by_default`
+  flags, so it composes with them in reading order, and any policy still
+  overrides it with `record_ip_address(...)` or `do_not_record_ip_address`.
+  The reader reports what is actually on rather than a remembered assignment.
+- **A purpose is no longer the price of admission.** A category enabled
+  without `because:` / `reason_for_recording_*_by_default` records
+  `Vocabulary::DEFAULT_REQUEST_EVIDENCE_PURPOSE` — "Corroborate who performed
+  each recorded act, from where, on what client — to defend the recorded
+  agreement itself." Every compiled policy revision therefore still carries a
+  purpose into every receipt, and `Clickwrap::Privacy.inventory` marks each one
+  `"purpose_source": "gem_default"` or `"host"` so the gem's sentence can never
+  be mistaken for a decision somebody reviewed.
+- **No disposal answer means indefinite.** The four gatekeepers that refused a
+  recorded field with no clock — `Configuration#validate_request_evidence_defaults!`,
+  the policy-level check in `RequestEvidencePolicy`, the reference validator,
+  and the capture-time extractor — now treat absence as "keeps pace with the
+  evidence it corroborates", which is what core evidence has done since 0.2.0.
+  The annex is stamped with no schedule and the retention planner never lists
+  it. `keep_recorded_*_indefinitely!` still works, still records its reason,
+  and now accepts no `because:` at all (defaulting to "Corroboration lives as
+  long as the evidence it corroborates").
+- **`trusted_proxy_configuration_digest` is no longer required to record an IP
+  address.** When it is absent the annex stores `nil`, and that nil is honest
+  provenance: no reviewed proxy configuration was recorded when this address
+  was observed. Hosts who set one still get the stronger record, the setter
+  still refuses anything that is not a complete prefixed SHA-2 digest, and
+  `clickwrap:doctor` still warns while it is unset.
+- **Bundled `trackdown` is used without a wiring line.** A policy that records
+  IP geolocation and names no resolver now gets
+  `Clickwrap::IpGeolocation::TrackdownResolver` automatically when the host's
+  bundle carries trackdown 0.4 or newer — lazily, considered once, and only at
+  the moment something actually needs an address resolved. The privacy
+  inventory reports such a resolver with `"source": "gem_default"` and doctor
+  names it. An installed release older than 0.4 gets the adapter's own
+  upgrade sentence rather than a misleading "trackdown is not installed", and
+  a host with no trackdown gets the boot sentence, now naming `bundle add
+  trackdown` as the first option.
+
+### Unchanged, deliberately
+
+- The gem's code default is still record-nothing. The switch is opt-in.
+- Claim boundaries are untouched: nothing says compliant, enforceable, proves
+  identity, or physical location, and IP geolocation remains network context —
+  not identity, not GPS.
+- Encryption stays on by default, and turning it off keeps its
+  `deliberately_store_request_evidence_unencrypted!(because:)` ceremony. That
+  one is a genuine hazard with a named escape hatch; the directive was about
+  the friction of enabling collection, not the friction of weakening it.
+- Scaffolding text is still refused wherever the host actually wrote it
+  (`"TODO: ask legal"` is not a purpose), and a deletion clock declared
+  alongside `keep_recorded_..._indefinitely!` for the same category is still
+  refused as opposite decisions.
+- Receipts still distinguish `not_configured` / `unavailable` / `recorded` /
+  `deleted_after_retention`, and no released receipt format changed. The
+  purpose provenance is deliberately kept off `to_snapshot`, so policy
+  revision digests and every golden fixture verify exactly as before.
+
+### Documentation — the request-evidence story is rewritten around the switch
+
+- README, `guides/request-evidence.md`, `guides/integrating.md`, and
+  `guides/naming.md` lead with the one switch and present purposes, legal
+  bases, clocks, and proxy digests as the upgrade path for teams who want
+  reviewed records — not as the entry fee. The now-false "boot refuses without
+  a reason or a period" claims are gone.
+- `CLAUDE.md` / `AGENTS.md` rule 6 is rewritten to the new truth and records
+  this directive and its date, so a future agent does not restore the
+  refusals as a "fix". The prohibition it keeps is the one that was always the
+  point: never add a switch whose *name* hides what it collects.
+
+### Documentation — the docs stop contradicting the shipped gem
+
+- **The README and `guides/integrating.md` teach `gem "clickwrap"`.** Both
+  still told readers that `bundle add clickwrap` would fetch the empty 0.0.0
+  name placeholder and that they should install from GitHub instead — four
+  published releases after that stopped being true, and directly under a
+  correct Gemfile snippet in the README's own quick start.
+- **The status banner says where the gem actually stands.** It claimed the gem
+  was "not yet proven in production" and had not been through its planned
+  production integrations; it now records that the gem runs in production in
+  more than one application — behind real signups, and under a
+  payout-authorization flow — and ships enabled by default in RailsFast, while
+  naming the two gates that genuinely remain open — the unfamiliar-developer setup
+  exercise, and the legal/privacy review of the default wording. The old
+  "don't put it under a payout flow just yet" line is replaced by the
+  discipline such a flow deserves: keep your existing verifier authoritative
+  until you have shown parity with it, bind each one-time authorization to its
+  subject, and test the double-submit race.
+- **One `## [0.1.0]` heading in this file, not two.** The section dated
+  2026-08-15 was drafted as release notes on the day the engine landed, but
+  0.1.0 was not published until 2026-08-19. It now reads as the
+  first-implementation subsection of the release it was always part of, with
+  its text intact.
+
 ## [0.2.1] - 2026-08-19
 
 ### Added — request evidence can keep pace with the evidence it corroborates
@@ -584,7 +788,13 @@ Changes driven by the first production host application:
   tests read the signed presentation token and its controls back off the
   rendered page, the way a browser does.
 
-## [0.1.0] - 2026-08-15
+### The first implementation, drafted 2026-08-15
+
+> These notes were written on 2026-08-15, the day the engine first landed, and
+> were drafted then as the release notes for 0.1.0. The release itself did not
+> go out until 2026-08-19; the sections above are the four days in between.
+> Everything below shipped as part of that same 0.1.0 and was never released
+> on its own.
 
 First implemented release. `clickwrap` turns terms acceptance, privacy notice
 acknowledgment, consent, factual declarations, operator attestations, and
@@ -599,7 +809,7 @@ its purpose, and its retention. The gem provides evidence mechanics only: your
 application and its counsel still own the legal text, lawful basis, substantive
 validity, capacity, authority, and retention periods.
 
-### Added
+#### Added
 
 - **Immutable versioned documents.** `Clickwrap.document :terms, version:, from:`
   points at the files your application already owns; `bin/rails clickwrap:publish`

data/README.md

@@ -35,7 +35,7 @@ If the evidence can't be recorded, the action doesn't happen. If the action fail
 No JavaScript package. No Redis. No background jobs. No external accounts or per-event API calls. No legal-document vendor. Just Rails, your database, and a DSL that reads like plain English.
 
 > [!IMPORTANT]
-> **Status: built and tested, not yet proven in production.** Everything in this README is implemented and covered by the test suite, but the gem hasn't been through its planned production integrations, an unfamiliar-developer usability test, or legal review of its default wording yet. Treat it as a release candidate for evaluation — don't put it under a payout flow just yet. The [stability promise](#stability-and-upgrade-promise) applies from 0.1.0 onward.
+> **Status: in production, with two gates still open.** Everything in this README is implemented and covered by the test suite; the gem runs in production in more than one application today, behind real signups and under a payout-authorization flow; and it ships enabled by default — request-evidence annex included — in the [RailsFast](https://railsfast.com/?ref=clickwrap) template. Two gates remain open: no unfamiliar developer has installed it unassisted, and no focused legal or privacy review has passed over the default wording, the receipt claim boundaries, or the request-evidence posture — so read those defaults with your own counsel rather than adopting them on trust. High-assurance flows — payouts, one-time authorizations — still deserve the full discipline rather than a leap of faith: keep your existing verifier authoritative until you have demonstrated parity with it, bind every authorization to its subject and consume it exactly once, and test the double-submit race in your own application. The [stability promise](#stability-and-upgrade-promise) applies from 0.1.0 onward.
 
 ## 👨‍💻 Example
 
@@ -110,10 +110,11 @@ Clickwrap.policy :signup do
 end
 ```
 
-(Yes, the payload-retention decision is mandatory — `clickwrap` will not silently
-default captured evidence or request evidence to "keep forever" and will not pick
-a period for you. A minimal, digest-linked disposition tombstone remains after a
-reviewed core deletion so the deletion itself does not become an unexplained hole.)
+(A retention class that names no rule keeps the evidence, which is the same
+posture request evidence takes: keeping is reversible, deleting is the explicit
+act. `clickwrap` will not pick a *deletion* period for you. A minimal,
+digest-linked disposition tombstone remains after a reviewed core deletion so
+the deletion itself does not become an unexplained hole.)
 
 Add one macro to your model:
 
@@ -165,7 +166,7 @@ bin/rails generate clickwrap:install
 bin/rails db:migrate
 ```
 
-`bundle add clickwrap` would install version 0.0.0, a deliberately empty name placeholder on RubyGems — install from GitHub until the first real version is published there.
+`bundle add clickwrap` writes that Gemfile line and installs the gem in one command, if you would rather not edit the file yourself.
 
 The installer detects Rails authentication vs. Devise, integer vs. UUID primary keys, and your database adapter, then generates adaptive migrations, one annotated initializer, and a conventional signup policy. It emits only the tables your installation can actually write to; the capabilities that are off by default bring their own migration when you want them:
 
@@ -722,39 +723,72 @@ With the engine mounted, users can view and download their own receipts, and ope
 
 `clickwrap` always records its event ID, server time, capture channel, and policy version. That proves **what was offered and what came back**. But an agreement dispute is rarely about the words — it's "that wasn't me" — and the answer to that is request evidence: the IP address, the browser, and where in the world the request came from, bound into the same digest-linked record at the same instant. Years later, "this exact sentence was accepted from this address, on this client, from this city, at this second, in the transaction that created the account" is a different conversation from "the row says yes". **Our recommendation is to record IP + user agent + geolocation on every assent policy** — you already hold a purpose (defending the very agreement being made) and the evidence lives encrypted, in its own annex, deletable on its own schedule if your counsel ever decides so.
 
-What the gem refuses to do is turn it on *silently*. Every field is a separate named decision with a written purpose — there is deliberately no `maximum_evidence` switch — so the recommended posture is three explicit blocks in your initializer:
+So turn it on. One line, and you are done:
+
+```ruby
+Clickwrap.configure do |config|
+  config.record_request_evidence_by_default = true
+end
+```
+
+That records, on every policy: the IP address the request arrived from, the browser user agent it sent, and a coarse country / region / city estimate for that address. Add [`trackdown`](https://github.com/rameerez/trackdown) 0.4+ to your Gemfile and the geolocation half resolves itself — Clickwrap picks up the official adapter with no wiring line, so trackdown plus Cloudflare genuinely is "bundle it and flip the switch".
+
+Nothing else is required — anywhere, at either level. **Your privacy policy owns the why; the gem records the what, honestly, and is nobody's nanny.** Clickwrap supplies its own defaults for every part you did not write:
+
+- **Purpose.** Every recorded field carries one into the receipt. Yours if you wrote one, otherwise Clickwrap's: *"Corroborate who performed each recorded act, from where, on what client — to defend the recorded agreement itself."* The [privacy inventory](#operations) marks which of the two it is reading back (`"purpose_source": "gem_default"` vs `"host"`), so a gem sentence never passes for a decision your team reviewed.
+- **How long.** No clock means it keeps pace with the evidence it corroborates — the same posture core evidence has had since 0.2.0. A corroboration scheduled to expire before the agreement it corroborates is a scheduled weakening of the record.
+- **Proxy provenance.** `trusted_proxy_configuration_digest` is recorded when you set one and left `nil` when you have not, and the `nil` is itself the honest answer: no reviewed proxy configuration was in force when this address was observed. `bin/rails clickwrap:doctor` says so out loud.
+
+What the gem still will not do is hide what it collects behind a name. The switch is called `record_request_evidence_by_default` because that is what it does; there is deliberately no `gdpr_compliant_mode`, `maximum_evidence`, or `legal_proof`, and no flag here makes any claim about the law. It also stops exactly at the coarse trio: a postal code, coordinates, a timezone, a metro code, and an accuracy radius each stay their own separately named line, because a switch that reads "record request evidence" should not hand you coordinates you never asked for.
+
+### The upgrade path: reviewed records
+
+The one-liner is the entry point, not the ceiling. Teams who want the stronger record — words their counsel signed off on, a legal basis reference, a named clock, a reviewed proxy topology — write them, and Clickwrap keeps every one of them as the host's own:
 
 ```ruby
 # clickwrap-doc-test: syntax-only — the resolver needs trackdown installed
 Clickwrap.configure do |config|
-  config.record_ip_address_by_default = true
+  config.record_request_evidence_by_default = true
+
   config.reason_for_recording_ip_addresses_by_default =
     "Corroborate who performed each recorded act, to defend the agreement itself"
+  config.legal_basis_reference_for_recording_ip_addresses_by_default = "LIA-SECURITY-2026-01"
   config.keep_recorded_ip_addresses_indefinitely!(
     because: "Corroboration must live exactly as long as the evidence it corroborates")
 
-  config.record_browser_user_agent_by_default = true
   config.reason_for_recording_browser_user_agents_by_default =
     "Corroborate the client context of each recorded act"
-  config.keep_recorded_browser_user_agents_indefinitely!(
-    because: "Corroboration must live exactly as long as the evidence it corroborates")
+  config.delete_recorded_browser_user_agents_after = 2.years
 
-  config.record_ip_geolocation_country_by_default = true
-  config.record_ip_geolocation_region_by_default = true
-  config.record_ip_geolocation_city_by_default = true
   config.reason_for_recording_ip_geolocation_by_default =
     "Corroborate where each recorded act was performed from"
-  config.keep_recorded_ip_geolocation_indefinitely!(
-    because: "Corroboration must live exactly as long as the evidence it corroborates")
   config.ip_geolocation_resolver = Clickwrap::IpGeolocation::TrackdownResolver.new
 
+  config.trusted_proxy_configuration_digest =
+    Clickwrap.trusted_proxy_configuration_digest_for_rails_application
   config.review_default_request_evidence_configuration_on = Date.new(2027, 8, 1)
 end
 ```
 
-(`keep_recorded_..._indefinitely!` matches the retention default since 0.2.0 — evidence keeps until deletion is an explicit reviewed act. A corroboration that expires before the agreement it corroborates is a scheduled weakening of the record; if your counsel wants a clock instead, `delete_recorded_..._after` is the same one-line decision in the other direction.)
+Two things are still refused, and both are you contradicting yourself rather than leaving a blank: scaffolding text (`"TODO: ask legal"`) standing in for a purpose, and a deletion clock set alongside `keep_recorded_..._indefinitely!` for the same category.
+
+### Per policy, with as much or as little as you want
+
+A single surface can name the fields itself instead of inheriting the default. The frictionless form takes no arguments at all:
+
+```ruby
+Clickwrap.policy :withdrawal_authorization do
+  authorize :regulated_action, one_time: true, valid_for: 10.minutes
+
+  record_ip_address
+  record_browser_user_agent
+  record_ip_geolocation
+end
+```
+
+`record_ip_geolocation` with no field named records the same coarse trio as the switch — country, region, city. Name even one field and you are choosing the set yourself, and the set is exactly what you named.
 
-A single regulated surface can also name a field per policy instead of by default:
+The same declarations with the full record a reviewed team would want:
 
 ```ruby
 Clickwrap.policy :regulated_authorization do
@@ -773,10 +807,13 @@ end
 Recorded values live in a separately encrypted annex with their own retention, so
 they can be deleted later without rewriting the core event payload. Core payloads
 have their own reviewed disposition path and leave a digest-linked tombstone.
-There is deliberately no `gdpr_compliant_mode` or `maximum_evidence` switch —
-every field is named individually, in plain English.
+Encryption is on by default for all three categories. Turning it off keeps its
+own ceremony — you cannot reach `encrypt_recorded_ip_addresses = false` without
+first writing `config.deliberately_store_request_evidence_unencrypted!` — but the
+ceremony is the method name a reviewer finds in the diff, not a sentence the gem
+makes you type. `because:` there is optional too.
 
-For IP geolocation, [`trackdown`](https://github.com/rameerez/trackdown) 0.4 or newer is the optional official resolver:
+For IP geolocation, [`trackdown`](https://github.com/rameerez/trackdown) 0.4 or newer is the official resolver, and Clickwrap uses it automatically when your bundle has it and you named no resolver of your own. Set it explicitly when you want a different provider per policy, or when you are wiring Trackdown's per-request CDN trust:
 
 ```ruby
 Trackdown.configure do |trackdown|
@@ -1237,8 +1274,11 @@ Clickwrap.configure do |config|
     controller.current_user == receipt.actor
   end
 
-  # Safe defaults: no IP address, browser user-agent, or IP geolocation is stored.
-  # Enable fields per policy, each with a plain-English purpose and retention rule.
+  # Nothing request-derived is stored until you say so. This one line says so:
+  # IP address, browser user agent, and a coarse country/region/city estimate,
+  # on every policy. Per-field flags and per-policy declarations still override
+  # it in either direction.
+  config.record_request_evidence_by_default = true
 
   # Optional hooks run only after evidence and domain state have committed:
   config.after_event_is_committed = ->(event) { }
@@ -1340,7 +1380,7 @@ No — and `clickwrap` never equates scrolling with reading. It makes documents
 
 ### Should I record IP addresses?
 
-Only for policies with a real, documented purpose. They corroborate request context; they don't prove identity or location. Everything defaults off.
+We think yes, for assent policies — they are what turns "the row says yes" into "this sentence was accepted from this address, on this client, at this second". They corroborate request context; they do not prove identity or physical location. The gem's own default is still off, and turning them on is `config.record_request_evidence_by_default = true`.
 
 ### Can I keep my domain models?
 

data/guides/integrating.md

@@ -23,10 +23,8 @@ survived contact with production code.
 ## 1. Install, in this exact order
 
 ```ruby
-# Gemfile — `bundle add clickwrap` would install 0.0.0, a deliberately empty
-# name placeholder on RubyGems. Install from GitHub until the first real
-# version is published there.
-gem "clickwrap", github: "rameerez/clickwrap"
+# Gemfile
+gem "clickwrap"
 ```
 
 ```bash
@@ -562,8 +560,11 @@ history, not just post-migration. The shape that worked:
 
 ## 9. Request evidence, when a surface earns it
 
-Default to collecting nothing; enable per policy, per field, when a surface
-has a real purpose (our money path did; our signup did not):
+The gem collects nothing until you say otherwise, and since 0.3.0 saying
+otherwise for every policy at once is one line —
+`config.record_request_evidence_by_default = true`. We took the narrower road
+and enabled per policy, per field, where the surface earned it (our money path
+did; our signup did not):
 
 ```ruby
 policy.record_ip_address(
@@ -574,16 +575,19 @@ policy.record_ip_address(
 )
 ```
 
-Enabling any IP field requires `config.trusted_proxy_configuration_digest` —
-a digest of the effective proxy rules, not a prose label, so old evidence
-records which configuration was in force. Generate it from Rails' configured
-rules (or Rails' actual defaults when none were overridden):
+`config.trusted_proxy_configuration_digest` is worth setting and is no longer
+required to record an address — a digest of the effective proxy rules, not a
+prose label, so old evidence records which configuration was in force. Generate
+it from Rails' configured rules (or Rails' actual defaults when none were
+overridden):
 
 ```ruby
 config.trusted_proxy_configuration_digest =
   Clickwrap.trusted_proxy_configuration_digest_for_rails_application
 ```
 
+Leave it unset and the annex records a `nil` digest, which honestly says nobody
+reviewed a proxy topology; `clickwrap:doctor` warns while that is the case.
 This records configuration provenance; it does not prove the rules were
 correctly deployed or reviewed. Sharing the same fields across several policies?
 A plain Ruby lambda in `config/clickwrap.rb` calling

data/guides/naming.md

@@ -106,11 +106,19 @@ The same distinction runs through the six request-evidence states. `not_configur
 configuration fact; `unavailable` is an observation; `deleted_after_retention` is a third thing
 entirely. None of them is blank.
 
-### 6. One option never secretly enables another category of data
+### 6. One option never *secretly* enables another category of data
 
-**Why:** this is the failure mode the gem exists to prevent. An option that turns on a category
-of personal data as a side effect makes the diff unreviewable and the upgrade dangerous — a
-later release can widen what the profile covers, and nobody reading the initializer would know.
+**Why:** this is the failure mode the gem exists to prevent. An option whose name does not say
+what it collects makes the diff unreviewable and the upgrade dangerous — a later release can
+widen what the profile covers, and nobody reading the initializer would know.
+
+The test is the name, not the count. `config.record_request_evidence_by_default = true` does
+enable three categories at once, and it is fine, because the line tells a reviewer what those
+three are and the gem may never widen them: the switch is defined as the IP address, the
+browser user agent, and a coarse country/region/city estimate, and a future release that
+wanted to add coordinates would have to change its name. A `precision: :full` or a
+`level: :enhanced` fails the test for the opposite reason — nobody reading it can say what
+came back.
 
 ```ruby
 # Before
@@ -249,7 +257,7 @@ banned for a specific reason, not for taste.
 |---|---|
 | `:network`, `:full`, `:enhanced`, `:forensic`, `:maximum` | They hide what will be collected behind a word that sounds like a quality level |
 | `record_location` | A developer could reasonably read it as GPS or physical location. It is neither |
-| `request_evidence: :network`, `track_everything`, `record_everything` | Category switches. See rule 6 |
+| `request_evidence: :network`, `track_everything`, `record_everything` | Their names do not name their contents. See rule 6, and contrast `record_request_evidence_by_default`, which does |
 | `maximum_evidence`, `full_evidence`, `legal_proof: true` | They imply a verdict the gem cannot reach, and they enable data as a side effect |
 | An opaque privacy-profile switch keyed to a regulation | No runtime flag can make a legal determination on anyone's behalf, and the name would be the least accurate string in the codebase |
 | `include_sensitive_context: true` | One flag turning on three categories of personal data makes an operator's intent unreviewable. Use `include_ip_address:`, `include_browser_user_agent:`, `include_ip_geolocation:` |
@@ -283,7 +291,7 @@ object.
 | `chain_event_history_with`, `anchor_event_history_with`, `timestamp_receipts_with` | one `integrity_level` setting | Three different mechanisms making three different claims. One setting would let a reader infer the strongest from the presence of the weakest |
 | `after_event_is_committed` | `after_commit` | Says which commit, and reads as a sentence |
 | `authorize_unredacted_request_evidence_access_with` | `access_control` | Long, and correct. It names exactly which access it authorizes |
-| `deliberately_store_request_evidence_unencrypted!(because:)` | `encryption: false` | Turning encryption off should be a sentence a reviewer can find in a diff, with the host's own reason attached — not a `false` |
+| `deliberately_store_request_evidence_unencrypted!` | `encryption: false` | Turning encryption off should be a sentence a reviewer can find in a diff — not a `false`. The method NAME is the ceremony; its `because:` is optional |
 
 The last row is the pattern worth copying. When an option has a consequence somebody should
 have to think about, make the name carry the thinking.