clickwrap 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be18f8fc09eee066b71a234a134440010c6cf2beb82987b4bbe3636dde2f9133
-  data.tar.gz: a2c66a9be09cf999de30d890c4338e084146414cadbe0747022a3aedc8a4ef5f
+  metadata.gz: 504024fe0e6e146a907899092e9da9fe3f62501a2d2b251cb0f190cc72516860
+  data.tar.gz: 542284305afe7e79d11e5759ce2c88630982ce7ad0862866a58a50824056b4d8
 SHA512:
-  metadata.gz: 891f939a6b827915a5d2703ecf98b0ed9b9e761d3689a1117e8ba3df6ae0450c50a3f9d53edd0cbf844e996a7be447b080070b6ab2d916409b5d1ecfdc851ddc
-  data.tar.gz: 2387391b3d960d05dcdc783221bb5653de21406ecd0173b8fbafa1dc17d716549044a22bc719740892553b8a9c66beb8b42417c61e9bc7f585d569849fa43d9d
+  metadata.gz: 34500cc2c493a726afa16ed51e592102109bf56750eeb19a67624b85d0565d98ec316f45ac8653ffe2aa6f757c690577d37b34b986c71e8f5cd95fa766648b6c
+  data.tar.gz: 5ed6946bb7aa2319a3f27b11c40ff79a64d85759353567b1e46be342e7966e7f180eda5be79acf9229c156d5bbcf9397e2ad473184947dce2e64ec577bd615cb

data/CHANGELOG.md

@@ -6,6 +6,119 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +697,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 +718,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,37 +723,54 @@ 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, because Clickwrap supplies honest defaults for the parts 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.
 
 A single regulated surface can also name a field per policy instead of by default:
 
@@ -773,10 +791,11 @@ 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 and turning it off keeps its own ceremony —
+`config.deliberately_store_request_evidence_unencrypted!(because: "…")` — because
+that one is a real hazard, not paperwork.
 
-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 +1256,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 +1362,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:` |

data/guides/request-evidence.md

@@ -5,11 +5,25 @@ configured actor and authentication source, the policy and application version,
 request ID when one is available. None of that is derived from the person's network or browser.
 
 It records **nothing** about the request itself — no IP address, no browser user-agent, no
-IP-geolocation field — unless the initializer or a policy names that exact field. There is no
-category switch, no profile, and no option that turns one of these on as a side effect of
-turning on something else.
+IP-geolocation field — until the initializer or a policy says otherwise. Saying otherwise takes
+one line:
 
-That default is evidence design, not squeamishness. Three things follow from it:
+```ruby
+Clickwrap.configure do |config|
+  config.record_request_evidence_by_default = true
+end
+```
+
+That switch records exactly what its name says and nothing else: the IP address, the browser
+user agent, and a coarse country / region / city estimate. Every finer geolocation field — a
+postal code, coordinates, a timezone, a continent, a metro code, an accuracy radius — remains
+its own separately named line, and no option here turns a category on as a side effect of
+turning on something else. There is still no profile switch and no name that hides its
+contents (`gdpr_compliant_mode`, `maximum_evidence`, `legal_proof`); a switch that reads
+`record_request_evidence_by_default` is the opposite of one.
+
+The gem's own default is still record-nothing, and that default is evidence design, not
+squeamishness. Three things follow from it:
 
 - An IP address and other online identifiers can be personal data. The CJEU addressed dynamic
   IP addresses in [Breyer, Case C-582/14](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A62014CJ0582)
@@ -230,7 +244,8 @@ they tell an auditor completely different things:
 
 Two places, and the policy always wins.
 
-**In the initializer, for every policy.** Each field is its own setting, and each is `false`:
+**In the initializer, for every policy.** Either the one switch, or the individual settings —
+each field has its own, and each is `false`:
 
 ```ruby
 Clickwrap.configure do |config|
@@ -242,10 +257,15 @@ Clickwrap.configure do |config|
 end
 ```
 
-Turning a default on without a purpose or without a deletion period is a `ConfigurationError`
-at the end of the `configure` block, not a warning. Enabling any
-`record_ip_geolocation_*_by_default` without an `ip_geolocation_resolver` is likewise a
-`ConfigurationError` — there would be nothing to resolve them.
+Everything below the first line there is optional. A purpose you do not write becomes
+Clickwrap's own stated one (marked `gem_default` in the inventory); a deletion period you do
+not set means the field keeps pace with the evidence it corroborates.
+
+Three things are still a `ConfigurationError` at the end of the `configure` block rather than a
+warning: scaffolding text standing in for a purpose, a deletion clock set alongside
+`keep_recorded_..._indefinitely!` for the same category, and enabling a
+`record_ip_geolocation_*_by_default` field with no `ip_geolocation_resolver` configured *and*
+no `trackdown` in the bundle — there would be nothing to resolve them with.
 
 **In one policy, for one flow.** This is the shape most applications want: ordinary signup
 inherits nothing, and the one consequential action opts in by name.
@@ -293,13 +313,19 @@ end
 Every keyword there is doing work:
 
 - **`because:`** is the present purpose, in a sentence someone outside engineering can read. It
-  is stored, printed by `bin/rails clickwrap:privacy:inventory`, and required.
+  is stored and printed by `bin/rails clickwrap:privacy:inventory`. It is optional: a policy
+  that omits it records Clickwrap's own stated purpose instead, and the inventory marks that
+  entry `"purpose_source": "gem_default"` so nobody mistakes it for a sentence your team
+  reviewed. What is refused is scaffolding text — `"TODO: ask legal"` is not a purpose.
 - **`legal_basis_reference:`** and **`data_protection_impact_assessment_reference:`** are
   host-supplied pointers to your own reviewed documents. Clickwrap stores them. It does not
   read them, validate them, or endorse them.
-- **`delete_after:`** or **`retain_until:`** is not optional. If a policy records a field and
-  neither the policy nor the configuration says when it goes away, capture raises a
-  `ConfigurationError` before the row is written. There is no keep-forever default in this gem.
+- **`delete_after:`** and **`retain_until:`** are both optional. When neither the policy, its
+  retention class, nor the configuration names a schedule, the field keeps pace with the
+  evidence it corroborates — the same posture the core event has — and the annex is stamped
+  with no deadline at all, so the retention planner never lists it. Setting a clock alongside
+  an application-wide `keep_recorded_..._indefinitely!` for the same category is still refused:
+  those are opposite decisions.
 - **`fail_if_unavailable:`** (default `false`) decides whether evidence you cannot get is worse
   than no capture at all. When it is `true` and the field cannot be resolved, the capture and
   the protected action roll back together.
@@ -359,6 +385,12 @@ So "we record IP addresses" is not one decision. It is four:
    later reader identify which rules were in force — the difference between corroborating
    evidence and a number with no recorded collection context.
 
+   Since 0.3.0 this step is not a precondition for recording an address. Leave it unset and the
+   annex stores `trusted_proxy_configuration_digest` as `nil`, which is the honest reading of
+   the situation: nobody recorded having reviewed a proxy topology when this address was
+   observed. `bin/rails clickwrap:doctor` warns while it stays that way. Hosts who complete
+   step 4 get the stronger record; hosts who do not get an address that says what it is worth.
+
 If you replace the reader, you own that decision, and the receipt says so: any host-assigned
 lambda is labeled `host_configured_reader` rather than `rails_request_remote_ip`, even when the
 body is identical. Clickwrap will not claim Rails' spoof checks on your behalf.
@@ -378,6 +410,18 @@ gem and must never become one.
 bundle add trackdown --version ">= 0.4"
 ```
 
+That is the whole wiring step. When your bundle carries trackdown and you have not named a
+resolver of your own, Clickwrap uses `Clickwrap::IpGeolocation::TrackdownResolver` for any
+policy that records IP geolocation — lazily, only at the moment something actually needs an
+address resolved, and never as a collection decision on its own (nothing is resolved until a
+policy has already enabled a geolocation field). `bin/rails clickwrap:privacy:inventory` reports
+that resolver with `"source": "gem_default"`, and `clickwrap:doctor` names it, so an adopted
+resolver never reads as a host decision. An installed trackdown older than 0.4 is not hidden
+behind "the gem is missing": you get the adapter's own sentence about upgrading.
+
+Set it explicitly when you want a different provider per policy, or when you are wiring
+Trackdown's per-request CDN trust:
+
 ```ruby
 # clickwrap-doc-test: syntax-only — requires the optional trackdown gem installed above
 Trackdown.configure do |trackdown|