consentful 0.1.0.pre1

data/app/views/consentful/admin/dashboard/show.html.erb

@@ -0,0 +1,35 @@
+<h1>Dashboard</h1>
+<p class="cf-muted">Last <%= @report.days %> days (since <%= @report.since.strftime("%Y-%m-%d") %>).</p>
+
+<div class="cf-card">
+  <div class="cf-stat"><%= @report.total_records %></div>
+  <div class="cf-muted">consent events recorded</div>
+</div>
+
+<h2>Category acceptance</h2>
+<table class="cf-table">
+  <thead><tr><th>Category</th><th>Accepted</th><th>Rate</th></tr></thead>
+  <tbody>
+    <% @report.category_acceptance.each do |row| %>
+      <tr>
+        <td><%= row[:category].name %></td>
+        <td><%= row[:accepted] %> / <%= row[:total] %></td>
+        <td><%= row[:rate] %>%</td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>
+
+<h2>Source breakdown</h2>
+<table class="cf-table">
+  <thead><tr><th>Source</th><th>Count</th><th>Rate</th></tr></thead>
+  <tbody>
+    <% @report.source_breakdown.each do |row| %>
+      <tr>
+        <td><%= row[:source].to_s.humanize %></td>
+        <td><%= row[:count] %></td>
+        <td><%= row[:rate] %>%</td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/app/views/consentful/admin/records/index.html.erb

@@ -0,0 +1,35 @@
+<h1>SAR Lookup</h1>
+<p class="cf-muted">Resolve a subject-access request by email or visitor reference into every recorded consent event.</p>
+
+<div class="cf-card">
+  <%= form_with url: admin_records_path, method: :get do |f| %>
+    <div class="cf-field"><%= f.label :email %><%= f.text_field :email, value: @lookup.email %></div>
+    <div class="cf-field"><%= f.label :visitor_uuid, "Visitor reference (UUID)" %><%= f.text_field :visitor_uuid, value: @lookup.visitor_uuid %></div>
+    <%= f.submit "Search", class: "cf-btn cf-btn--primary" %>
+  <% end %>
+</div>
+
+<% if @lookup.given_any_input? %>
+  <h2><%= @lookup.records.size %> consent event(s)</h2>
+
+  <% if @lookup.linked_identifiers.any? %>
+    <p class="cf-muted">Linked identifiers:
+      <%= @lookup.linked_identifiers.map { |link| "#{link.identifier_type}: #{link.identifier_value}" }.join("; ") %>
+    </p>
+  <% end %>
+
+  <% if @lookup.records.empty? %>
+    <p class="cf-muted">No consent records found for that subject.</p>
+  <% end %>
+
+  <% @lookup.records.each do |record| %>
+    <% text = Consentful::ConsentRecordPresenter.new(record).email_text %>
+    <div class="cf-card">
+      <pre class="cf-pre"><%= text %></pre>
+      <button type="button" class="cf-btn"
+              data-controller="consentful--clipboard"
+              data-consentful--clipboard-text-value="<%= text %>"
+              data-action="consentful--clipboard#copy">Copy for email</button>
+    </div>
+  <% end %>
+<% end %>

data/app/views/consentful/admin/services/_form.html.erb

@@ -0,0 +1,42 @@
+<%= form_with model: @service, scope: :consent_service,
+      url: (@service.persisted? ? admin_service_path(@service) : admin_services_path) do |f| %>
+  <% if @service.errors.any? %>
+    <div class="cf-flash cf-flash--alert"><%= @service.errors.full_messages.to_sentence %></div>
+  <% end %>
+
+  <div class="cf-card">
+    <h2>Wiring</h2>
+    <div class="cf-field"><%= f.label :name %><%= f.text_field :name %></div>
+    <div class="cf-field"><%= f.label :slug %><%= f.text_field :slug %><p class="cf-hint">Lowercase letters, digits and underscores only.</p></div>
+    <div class="cf-field"><%= f.label :consent_category_id, "Category" %><%= f.collection_select :consent_category_id, @categories, :id, :name %></div>
+    <div class="cf-field"><%= f.label :loader_kind %><%= f.select :loader_kind, Consentful::ConsentService::LOADER_KIND_LABELS.map { |k, v| [v, k] } %></div>
+    <div class="cf-field"><%= f.label :loader_ref, "Loader reference" %><%= f.text_field :loader_ref %><p class="cf-hint">Partial path(s) or tag id, depending on loader kind.</p></div>
+    <div class="cf-field"><%= f.label :domain %><%= f.text_field :domain %></div>
+    <div class="cf-field"><label><%= f.check_box :active %> Active</label></div>
+  </div>
+
+  <div class="cf-card">
+    <h2>GDPR Art. 13/14 disclosure</h2>
+    <div class="cf-field"><%= f.label :description %><%= f.text_area :description %></div>
+    <div class="cf-field"><%= f.label :processing_company_name %><%= f.text_field :processing_company_name %></div>
+    <div class="cf-field"><%= f.label :processing_company_address %><%= f.text_field :processing_company_address %></div>
+    <div class="cf-field"><%= f.label :dpo_email, "DPO email" %><%= f.text_field :dpo_email %></div>
+    <div class="cf-field"><%= f.label :privacy_url %><%= f.text_field :privacy_url %></div>
+    <div class="cf-field"><%= f.label :legal_basis %><%= f.text_field :legal_basis %></div>
+    <div class="cf-field"><%= f.label :retention_period %><%= f.text_area :retention_period %></div>
+    <div class="cf-field"><%= f.label :processing_location %><%= f.text_field :processing_location %></div>
+    <div class="cf-field"><%= f.label :third_country_transfer %><%= f.text_area :third_country_transfer %></div>
+    <div class="cf-field"><%= f.label :data_purposes %><%= f.text_field :data_purposes, value: @service.data_purposes.join(", ") %><p class="cf-hint">Comma-separated.</p></div>
+    <div class="cf-field"><%= f.label :technologies_used %><%= f.text_field :technologies_used, value: @service.technologies_used.join(", ") %><p class="cf-hint">Comma-separated.</p></div>
+    <div class="cf-field"><%= f.label :data_collected %><%= f.text_field :data_collected, value: @service.data_collected.join(", ") %><p class="cf-hint">Comma-separated.</p></div>
+    <div class="cf-field"><%= f.label :cookie_names %><%= f.text_field :cookie_names, value: @service.cookie_names.join(", ") %><p class="cf-hint">Comma-separated.</p></div>
+  </div>
+
+  <div class="cf-actions">
+    <%= f.submit (@service.persisted? ? "Save service" : "Create service"), class: "cf-btn cf-btn--primary" %>
+    <%= link_to "Cancel", admin_services_path, class: "cf-btn" %>
+    <% if @service.persisted? %>
+      <%= button_to "Delete", admin_service_path(@service), method: :delete, class: "cf-btn cf-btn--danger", form: { data: { turbo_confirm: "Delete this service?" } } %>
+    <% end %>
+  </div>
+<% end %>

data/app/views/consentful/admin/services/edit.html.erb

@@ -0,0 +1,2 @@
+<h1>Edit service</h1>
+<%= render "form" %>

data/app/views/consentful/admin/services/index.html.erb

@@ -0,0 +1,27 @@
+<h1>Services</h1>
+
+<div class="cf-actions" style="margin-bottom:16px;">
+  <%= link_to "New service", new_admin_service_path, class: "cf-btn cf-btn--primary" %>
+</div>
+
+<% @services_by_category.each do |category, services| %>
+  <h2><%= category.name %></h2>
+  <table class="cf-table">
+    <thead><tr><th>Name</th><th>Slug</th><th>Loader</th><th>Active</th><th></th></tr></thead>
+    <tbody>
+      <% if services.empty? %>
+        <tr><td colspan="5" class="cf-muted">No services in this category.</td></tr>
+      <% else %>
+        <% services.each do |service| %>
+          <tr>
+            <td><%= service.name %></td>
+            <td><code><%= service.slug %></code></td>
+            <td class="cf-muted"><%= service.loader_kind_label %></td>
+            <td><%= service.active? ? "Yes" : "No" %></td>
+            <td><%= link_to "Edit", edit_admin_service_path(service), class: "cf-btn" %></td>
+          </tr>
+        <% end %>
+      <% end %>
+    </tbody>
+  </table>
+<% end %>

data/app/views/consentful/admin/services/new.html.erb

@@ -0,0 +1,2 @@
+<h1>New service</h1>
+<%= render "form" %>

data/app/views/consentful/consent/preferences.html.erb

@@ -0,0 +1,14 @@
+<div class="c-consent-page">
+  <% if @published_version.present? %>
+    <%= render Consentful::Preferences.new(
+          version: @published_version,
+          categories: @categories,
+          visitor_uuid: consent_visitor_id,
+          submit_path: consent_path,
+          variant: :page
+        ) %>
+  <% else %>
+    <h1 class="c-consent-page__title">Cookie preferences</h1>
+    <p class="c-consent-page__empty">No consent copy has been published yet. Please check back shortly.</p>
+  <% end %>
+</div>

data/app/views/layouts/consentful/admin.html.erb

@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Consent Management</title>
+  <%= csrf_meta_tags %>
+  <style>
+    :root { --cf-navy:#002b49; --cf-blue:#0481b7; --cf-gold:#ac8c30; --cf-ea:#eaeaea; --cf-f2:#f2f2f2; --cf-49:#494949; }
+    * { box-sizing: border-box; }
+    body { margin:0; font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif; color:var(--cf-navy); background:var(--cf-f2); }
+    a { color:var(--cf-blue); }
+    .cf-header { background:var(--cf-navy); color:#fff; padding:0 24px; }
+    .cf-header__title { margin:0; padding:16px 0 8px; font-size:18px; font-weight:700; }
+    .cf-nav { display:flex; gap:4px; flex-wrap:wrap; }
+    .cf-nav a { color:#cfe3ef; text-decoration:none; padding:10px 14px; border-radius:6px 6px 0 0; font-size:14px; }
+    .cf-nav a:hover { background:rgba(255,255,255,.08); color:#fff; }
+    .cf-nav a.is-active { background:var(--cf-f2); color:var(--cf-navy); font-weight:600; }
+    .cf-main { max-width:1040px; margin:0 auto; padding:24px; }
+    .cf-flash { padding:12px 16px; border-radius:6px; margin-bottom:16px; font-size:14px; }
+    .cf-flash--notice { background:#e6f4ea; color:#1e4620; border:1px solid #b7dcc0; }
+    .cf-flash--alert { background:#fdecea; color:#611a15; border:1px solid #f3c2bd; }
+    h1 { font-size:22px; margin:0 0 16px; }
+    h2 { font-size:17px; margin:24px 0 12px; }
+    .cf-card { background:#fff; border:1px solid var(--cf-ea); border-radius:8px; padding:20px; margin-bottom:16px; }
+    table.cf-table { width:100%; border-collapse:collapse; background:#fff; border:1px solid var(--cf-ea); border-radius:8px; overflow:hidden; }
+    .cf-table th, .cf-table td { text-align:left; padding:10px 14px; border-bottom:1px solid var(--cf-ea); font-size:14px; }
+    .cf-table th { background:var(--cf-f2); font-weight:600; }
+    .cf-table tr:last-child td { border-bottom:none; }
+    .cf-btn { display:inline-block; padding:8px 14px; border-radius:6px; border:1px solid var(--cf-ea); background:#fff; color:var(--cf-navy); font-size:14px; text-decoration:none; cursor:pointer; }
+    .cf-btn--primary { background:var(--cf-navy); color:#fff; border-color:var(--cf-navy); }
+    .cf-btn--gold { background:var(--cf-gold); color:#fff; border-color:var(--cf-gold); }
+    .cf-btn--danger { color:#b3261e; border-color:#e7b4b0; }
+    .cf-field { margin-bottom:14px; display:block; }
+    .cf-field label { display:block; font-size:13px; font-weight:600; margin-bottom:4px; }
+    .cf-field input[type=text], .cf-field textarea, .cf-field select { width:100%; padding:8px 10px; border:1px solid var(--cf-ea); border-radius:6px; font-size:14px; font-family:inherit; }
+    .cf-field textarea { min-height:80px; }
+    .cf-hint { font-size:12px; color:var(--cf-49); margin-top:4px; }
+    .cf-badge { display:inline-block; padding:2px 8px; border-radius:10px; font-size:12px; font-weight:600; }
+    .cf-badge--draft { background:var(--cf-f2); color:var(--cf-49); }
+    .cf-badge--published { background:#e6f4ea; color:#1e4620; }
+    .cf-badge--archived { background:#fdecea; color:#611a15; }
+    .cf-actions { display:flex; gap:8px; align-items:center; flex-wrap:wrap; }
+    .cf-stat { font-size:28px; font-weight:700; }
+    pre.cf-pre { background:var(--cf-f2); border:1px solid var(--cf-ea); border-radius:6px; padding:12px; font-size:12px; overflow:auto; white-space:pre-wrap; }
+    .cf-muted { color:var(--cf-49); font-size:13px; }
+  </style>
+</head>
+<body>
+  <header class="cf-header">
+    <h1 class="cf-header__title">Consent Management</h1>
+    <nav class="cf-nav">
+      <% nav = [["Dashboard", admin_root_path, "dashboard"], ["Copy", admin_copy_versions_path, "copy_versions"], ["Categories", admin_categories_path, "categories"], ["Services", admin_services_path, "services"], ["SAR Lookup", admin_records_path, "records"]] %>
+      <% nav.each do |label, path, ctrl| %>
+        <%= link_to label, path, class: ("is-active" if controller_name == ctrl) %>
+      <% end %>
+    </nav>
+  </header>
+
+  <main class="cf-main">
+    <% if flash[:notice] %><div class="cf-flash cf-flash--notice"><%= flash[:notice] %></div><% end %>
+    <% if flash[:alert] %><div class="cf-flash cf-flash--alert"><%= flash[:alert] %></div><% end %>
+    <%= yield %>
+  </main>
+</body>
+</html>

data/app/views/layouts/consentful/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Consentful</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "consentful/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,25 @@
+Consentful::Engine.routes.draw do
+  # Public endpoints — intended to mount at the host root.
+  post "/consent", to: "consent#update", as: :consent
+  post "/consent/link", to: "consent#link", as: :consent_link
+  get "/consent/state", to: "consent#state", as: :consent_state
+  get "/cookie-preferences", to: "consent#preferences", as: :cookie_preferences
+
+  # Self-contained admin panel — Flipper-style. Mounted at <engine>/consent-management,
+  # gated by Consentful.config.authorize.
+  scope path: "consent-management", as: :admin, module: :admin do
+    root to: "dashboard#show", as: :root
+    resources :categories, only: [ :index, :edit, :update ] do
+      post :reorder, on: :collection
+    end
+    resources :services
+    resources :copy_versions do
+      member do
+        post :publish
+        post :archive
+        post :restore
+      end
+    end
+    resources :records, only: [ :index ]
+  end
+end

data/db/migrate/20260522100000_create_consent_categories.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateConsentCategories < ActiveRecord::Migration[7.1]
+  def change
+    create_table :consent_categories do |t|
+      t.string :key, null: false
+      t.string :name, null: false
+      t.text :description
+      t.integer :position, null: false, default: 0
+      t.boolean :required, null: false, default: false
+      t.string :gtag_keys, array: true, default: [], null: false
+
+      t.timestamps
+    end
+
+    add_index :consent_categories, :key, unique: true
+    add_index :consent_categories, :position
+  end
+end

data/db/migrate/20260522100100_create_consent_services.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class CreateConsentServices < ActiveRecord::Migration[7.1]
+  def change
+    create_table :consent_services do |t|
+      # Identification / wiring
+      t.string :name, null: false
+      t.string :slug, null: false
+      t.references :consent_category, null: false, foreign_key: true
+      t.string :domain
+      t.integer :loader_kind, null: false, default: 0
+      t.string :loader_ref
+      t.boolean :active, null: false, default: true
+      t.integer :position, null: false, default: 0
+
+      # GDPR Art. 13/14 detail-card content
+      t.text :description
+      t.string :processing_company_name
+      t.string :processing_company_address
+      t.string :dpo_email
+      t.string :privacy_url
+      t.string :data_purposes, array: true, default: [], null: false
+      t.string :technologies_used, array: true, default: [], null: false
+      t.string :data_collected, array: true, default: [], null: false
+      t.string :legal_basis
+      t.string :processing_location
+      t.text :retention_period
+      t.text :third_country_transfer
+      t.string :cookie_names, array: true, default: [], null: false
+
+      t.timestamps
+    end
+
+    add_index :consent_services, :slug, unique: true
+    add_index :consent_services, [ :consent_category_id, :position ]
+    add_index :consent_services, :active
+  end
+end

data/db/migrate/20260522100200_create_consent_copy_versions.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class CreateConsentCopyVersions < ActiveRecord::Migration[7.1]
+  def change
+    create_table :consent_copy_versions do |t|
+      t.integer :status, null: false, default: 0
+      t.datetime :published_at
+      # Free-form identity of whoever published, resolved by the host via
+      # Consentful.config.identify. Not a foreign key.
+      t.string :published_by
+
+      t.string :banner_title
+      t.text :banner_body
+      t.text :modal_intro
+      t.string :accept_label
+      t.string :reject_label
+      t.string :manage_label
+      t.string :save_label
+
+      t.jsonb :category_blurbs, null: false, default: {}
+      t.string :digest, null: false
+
+      t.timestamps
+    end
+
+    add_index :consent_copy_versions, :status
+    add_index :consent_copy_versions, :digest
+    add_index :consent_copy_versions, :published_at
+  end
+end

data/db/migrate/20260522100300_create_consent_records.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateConsentRecords < ActiveRecord::Migration[7.1]
+  def change
+    create_table :consent_records do |t|
+      t.string :visitor_uuid, null: false
+      t.references :consent_copy_version, null: false, foreign_key: true
+      t.jsonb :category_choices, null: false, default: {}
+      t.jsonb :service_overrides, null: false, default: {}
+      t.integer :source, null: false
+      t.string :user_agent
+      t.string :referer
+      t.datetime :recorded_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :consent_records, :visitor_uuid
+    add_index :consent_records, :recorded_at
+    add_index :consent_records, [ :visitor_uuid, :recorded_at ]
+  end
+end

data/db/migrate/20260522100400_create_consent_visitor_links.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateConsentVisitorLinks < ActiveRecord::Migration[7.1]
+  def change
+    create_table :consent_visitor_links do |t|
+      t.string :visitor_uuid, null: false
+      t.integer :identifier_type, null: false
+      t.string :identifier_value, null: false
+      t.datetime :linked_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :consent_visitor_links, :visitor_uuid
+    add_index :consent_visitor_links, [ :identifier_type, :identifier_value ]
+    add_index :consent_visitor_links,
+              [ :visitor_uuid, :identifier_type, :identifier_value ],
+              unique: true,
+              name: "index_consent_visitor_links_on_uuid_and_identifier"
+  end
+end

data/lib/consentful/configuration.rb

@@ -0,0 +1,100 @@
+module Consentful
+  # Host-app configuration for the engine. Set via `Consentful.configure`.
+  #
+  #   Consentful.configure do |c|
+  #     c.cookie_name = "scl_consent"
+  #     c.authorize   = ->(controller) { controller.current_admin&.super_admin? }
+  #     c.identify    = ->(controller) { controller.current_admin&.email }
+  #   end
+  class Configuration
+    # Name of the cookie storing the visitor's consent state.
+    attr_accessor :cookie_name
+
+    # Name of the cookie storing the anonymous visitor UUID.
+    attr_accessor :visitor_cookie_name
+
+    # How long a recorded consent (and its cookie) remains valid, in months.
+    attr_accessor :cookie_expiry_months
+
+    # Ordered list of consent category keys the host supports.
+    attr_accessor :category_keys
+
+    # The category key that is always-on and cannot be rejected.
+    attr_accessor :required_category_key
+
+    # When false, tracking-enforcement helpers allow everything (rollout flag).
+    attr_accessor :enforce
+
+    # Identifier types (name => enum value) used to link an anonymous visitor
+    # UUID back to a known identity for SAR resolution. Host domain concepts.
+    attr_accessor :visitor_identifier_types
+
+    # ->(context) { truthy } gate for the mounted admin panel. `context` is the
+    # admin controller instance, so the host can reach its own auth helpers.
+    attr_writer :authorize
+
+    # ->(context) { String } resolving who is acting in the admin panel, stored
+    # as `published_by` on a copy version. Replaces a hard FK to a host model.
+    attr_writer :identify
+
+    # ->(request) { Hash } building cookie options (secure/same_site/domain…).
+    # Hosts override to add a cookie `:domain` for cross-subdomain consent.
+    attr_writer :cookie_options
+
+    # Optional ->(exception) { } sink for swallowed errors (e.g. Rollbar.error).
+    attr_writer :error_handler
+
+    # Contact address shown on the preference centre for subject-access requests.
+    attr_accessor :sar_contact_email
+
+    # Layout used to render the standalone /cookie-preferences page. Hosts set
+    # this to their own layout (e.g. "application") to wrap it in site chrome.
+    attr_accessor :layout
+
+    def initialize
+      @cookie_name = "consent"
+      @visitor_cookie_name = "visitor_id"
+      @cookie_expiry_months = 12
+      @category_keys = %w[necessary analytics marketing]
+      @required_category_key = "necessary"
+      @enforce = false
+      @visitor_identifier_types = { email: 0 }
+      @authorize = ->(_context) { true }
+      @identify = ->(_context) { nil }
+      @cookie_options = ->(_request) { { secure: Rails.env.production?, same_site: :lax, httponly: false } }
+      @error_handler = nil
+      @sar_contact_email = nil
+      @layout = "consentful/application"
+    end
+
+    def cookie_options(request)
+      @cookie_options.call(request)
+    end
+
+    def error_handler(exception)
+      @error_handler&.call(exception)
+    end
+
+    def authorize(context)
+      @authorize.call(context)
+    end
+
+    def identify(context)
+      @identify.call(context)
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/consentful/engine.rb

@@ -0,0 +1,5 @@
+module Consentful
+  class Engine < ::Rails::Engine
+    isolate_namespace Consentful
+  end
+end

data/lib/consentful/seed_starter.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Consentful
+  # Idempotent starter data so a fresh install has working categories, a couple
+  # of example services, and a published copy version (so the banner renders).
+  # Safe to run repeatedly. Host apps are expected to curate their own services.
+  module SeedStarter
+    module_function
+
+    CATEGORIES = [
+      { key: "necessary", name: "Strictly Necessary", required: true, position: 0,
+        description: "Required for the site to function.", gtag_keys: %w[security_storage] },
+      { key: "analytics", name: "Analytics", required: false, position: 1,
+        description: "Helps us understand how visitors use the site.", gtag_keys: %w[analytics_storage] },
+      { key: "marketing", name: "Marketing", required: false, position: 2,
+        description: "Used to deliver relevant advertising.", gtag_keys: %w[ad_storage ad_user_data ad_personalization] }
+    ].freeze
+
+    def call
+      categories = seed_categories
+      seed_example_services(categories)
+      seed_copy_version
+    end
+
+    def seed_categories
+      CATEGORIES.to_h do |attrs|
+        category = ConsentCategory.find_or_initialize_by(key: attrs[:key])
+        category.update!(attrs)
+        [ attrs[:key], category ]
+      end
+    end
+
+    def seed_example_services(categories)
+      ConsentService.find_or_create_by!(slug: "example_analytics") do |service|
+        service.assign_attributes(
+          name: "Example Analytics", consent_category: categories["analytics"],
+          loader_kind: :external_only, active: true, position: 0,
+          description: "An example analytics service — replace with your own."
+        )
+      end
+    end
+
+    def seed_copy_version
+      return if ConsentCopyVersion.current
+
+      ConsentCopyVersion.create!(
+        status: :published, published_at: Time.current, published_by: "consentful:seed",
+        banner_title: "Privacy settings",
+        banner_body: "We use cookies to improve your experience.",
+        modal_intro: "Manage how we and our partners use cookies and similar technologies.",
+        accept_label: "Accept all", reject_label: "Reject all",
+        manage_label: "Manage", save_label: "Save settings",
+        category_blurbs: CATEGORIES.to_h { |c| [ c[:key], c[:description] ] }
+      )
+    end
+  end
+end

data/lib/consentful/version.rb

@@ -0,0 +1,3 @@
+module Consentful
+  VERSION = "0.1.0.pre1"
+end

data/lib/consentful.rb

@@ -0,0 +1,27 @@
+require "view_component"
+
+require "consentful/version"
+require "consentful/configuration"
+require "consentful/seed_starter"
+
+module Consentful
+  # Link an anonymous visitor UUID to a known identity (email, lead id, …) so a
+  # later subject-access request can resolve every consent record for a person.
+  def self.link!(visitor_uuid, type:, value:)
+    return if visitor_uuid.blank? || value.blank?
+
+    ConsentVisitorLink.find_or_create_by!(
+      visitor_uuid:,
+      identifier_type: type,
+      identifier_value: normalize_value(type, value)
+    )
+  end
+
+  def self.normalize_value(type, value)
+    return value.to_s.strip.downcase if type.to_s == "email"
+
+    value.to_s.strip
+  end
+end
+
+require "consentful/engine"

data/lib/generators/consentful/install_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Consentful
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the Consentful initializer and prints the remaining install steps."
+
+      def copy_initializer
+        template "consentful.rb", "config/initializers/consentful.rb"
+      end
+
+      def show_readme
+        say "\nConsentful installed. Remaining steps:", :green
+        say "  1. Install migrations:  bin/rails consentful:install:migrations"
+        say "  2. Migrate:             bin/rails db:migrate"
+        say "  3. (optional) Seed:     bin/rails consentful:seed"
+        say "  4. Mount the engine in config/routes.rb:"
+        say "       mount Consentful::Engine => \"/\""
+        say "  5. Edit config/initializers/consentful.rb — set `authorize` at minimum."
+        say "  6. JS:  import { registerConsentful } from 'consentful'; registerConsentful(application)"
+        say "  7. CSS: @import \"consentful/consent\";"
+      end
+    end
+  end
+end