moderate 0.1.0 → 1.0.0.beta1

data/app/views/moderate/notices/new.html.erb

@@ -0,0 +1,255 @@
+<%#
+  The default, OVERRIDABLE public DSA Art. 16 "notice and action" form.
+
+  This is the X / YouTube / Reddit-style "Report illegal content (EU)" page. It is
+  deliberately plain: no CSS framework is assumed, every label/hint is pulled
+  through I18n (`moderate.notices.*`), and it themes via CSS custom properties
+  (`:root { --moderate-* }`) so a host can restyle it without forking. To take full
+  control of the markup, eject it with `rails generate moderate:views` — your copy
+  at app/views/moderate/notices/new.html.erb then SHADOWS this one automatically
+  (Rails' view lookup puts the host's app/views ahead of the engine's).
+
+  The form binds a `Moderate::Report` (a notice is NOT a fourth table — it's a
+  Report with intake_kind "dsa") under the `:notice` scope, so params arrive as
+  params[:notice][...] for the controller's strong-params. KEEP ALL THE FIELDS if
+  you customize: they are dictated by DSA Article 16, not by product taste, and they
+  map 1:1 to the model's validations — dropping one makes the notice legally
+  invalid. https://eur-lex.europa.eu/eli/reg/2022/2065/oj (Art. 16)
+
+  PREFILL + LOCK (Art. 16(2)(b)/(c)):
+    * The REPORTED-CONTENT fields (subject URL, reason, details, content type) are
+      prefilled from the query string when the host deep-links here, and stay
+      EDITABLE — the notifier may correct them.
+    * The IDENTITY fields (name/email) are prefilled from Devise `current_user` when
+      someone is logged in, and are LOCKED (readonly) so a notice can't carry a
+      spoofed identity. The controller also re-asserts them server-side on submit.
+%>
+<% legal_reasons = Moderate::Report::DSA_LEGAL_REASONS %>
+<% member_states = Moderate::Report::EU_COUNTRY_CODES %>
+<% content_types = Moderate::Report::CONTENT_TYPES %>
+<%#
+  Identity is "locked" (readonly) whenever it was prefilled from the signed-in user.
+  The controller computes this and hands it over as `@identity_locked`, so the view
+  never reaches for `current_user` itself (it isn't exposed as a view helper on the
+  engine's base controller). The controller ALSO re-derives identity server-side on
+  submit, so even a tampered request that re-enables a locked field can't spoof a
+  name/email onto a legal notice. An anonymous notice (no current_user) leaves these
+  fields fully editable.
+%>
+<% identity_locked = @identity_locked %>
+
+<style>
+  /* Framework-agnostic defaults, all overridable via CSS custom properties so a
+     host can match brand colors without touching this markup. */
+  .moderate-notice {
+    --moderate-max-width: 40rem;
+    --moderate-accent: #111;
+    --moderate-border: #d4d4d4;
+    --moderate-muted: #666;
+    --moderate-radius: 8px;
+    max-width: var(--moderate-max-width);
+    margin: 2rem auto;
+    padding: 0 1rem;
+    font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+    line-height: 1.5;
+    color: #111;
+  }
+  .moderate-notice h1 { font-size: 1.5rem; margin-bottom: 0.25rem; }
+  .moderate-notice .moderate-intro { color: var(--moderate-muted); margin-bottom: 1.5rem; }
+  .moderate-notice .moderate-field { margin-bottom: 1.25rem; }
+  .moderate-notice label { display: block; font-weight: 600; margin-bottom: 0.35rem; }
+  .moderate-notice .moderate-hint { display: block; font-weight: 400; color: var(--moderate-muted); font-size: 0.85rem; margin-top: 0.25rem; }
+  .moderate-notice input[type="text"],
+  .moderate-notice input[type="url"],
+  .moderate-notice input[type="email"],
+  .moderate-notice select,
+  .moderate-notice textarea {
+    width: 100%;
+    padding: 0.6rem 0.7rem;
+    border: 1px solid var(--moderate-border);
+    border-radius: var(--moderate-radius);
+    font: inherit;
+    box-sizing: border-box;
+  }
+  .moderate-notice input[readonly] { background: #f4f4f4; color: var(--moderate-muted); cursor: not-allowed; }
+  .moderate-notice .moderate-checkbox { display: flex; gap: 0.5rem; align-items: flex-start; }
+  .moderate-notice .moderate-checkbox input { margin-top: 0.25rem; }
+  .moderate-notice .moderate-checkbox label { font-weight: 400; }
+  .moderate-notice button[type="submit"] {
+    background: var(--moderate-accent);
+    color: #fff;
+    border: 0;
+    border-radius: var(--moderate-radius);
+    padding: 0.7rem 1.25rem;
+    font: inherit;
+    font-weight: 600;
+    cursor: pointer;
+  }
+  .moderate-notice .moderate-errors {
+    border: 1px solid #e0a0a0;
+    background: #fbeaea;
+    color: #8a1f1f;
+    border-radius: var(--moderate-radius);
+    padding: 0.75rem 1rem;
+    margin-bottom: 1.25rem;
+  }
+</style>
+
+<div class="moderate-notice">
+  <h1><%= t("moderate.notices.title", default: "Report illegal content (EU)") %></h1>
+  <p class="moderate-intro">
+    <%= t("moderate.notices.intro",
+          default: "Use this form to notify us of content you believe is illegal under EU law (Digital Services Act, Article 16). Anyone can submit a notice — you do not need an account. We confirm receipt by email.") %>
+  </p>
+
+  <% if flash[:alert].present? %>
+    <div class="moderate-errors" role="alert">
+      <%= flash[:alert] %>
+    </div>
+  <% elsif flash[:notice].present? %>
+    <div class="moderate-errors" role="status">
+      <%= flash[:notice] %>
+    </div>
+  <% end %>
+
+  <%# Surface validation errors at the top so the submitter sees why a save failed. %>
+  <% if @report.respond_to?(:errors) && @report.errors.any? %>
+    <div class="moderate-errors" role="alert">
+      <%= @report.errors.full_messages.to_sentence %>
+    </div>
+  <% end %>
+
+  <%#
+    `scope: :notice` makes the params arrive as params[:notice][...], matching the
+    controller's `params.require(:notice)`. `url: notices_path` is the engine's
+    POST route, resolved within the mounted engine (e.g. /trust/notices).
+  %>
+  <%= form_with model: @report, scope: :notice, url: notices_path, method: :post do |form| %>
+
+    <%# Legal reason — the DSA statement-of-reasons taxonomy (Art. 16/17 ground). Editable. %>
+    <div class="moderate-field">
+      <%= form.label :legal_reason, t("moderate.notices.fields.legal_reason", default: "Legal reason") %>
+      <%= form.select :legal_reason,
+            legal_reasons.map { |reason| [t("moderate.legal_reasons.#{reason}", default: reason.to_s.tr("_", " ").capitalize), reason] },
+            { prompt: t("moderate.notices.prompts.legal_reason", default: "Select a reason") },
+            required: true %>
+    </div>
+
+    <%# Exact URLs — "the exact electronic location of that information", Art. 16(2)(b).
+        Prefilled from ?content_url=… (X-style deep link) but EDITABLE: the notifier
+        may correct the link to the specific content they are reporting. One URL per
+        line; the model normalizes into subject_urls and keeps subject_url as first. %>
+    <div class="moderate-field">
+      <%= form.label :subject_urls, t("moderate.notices.fields.content_url", default: "Exact URL of the content") %>
+      <textarea name="notice[subject_urls]" id="notice_subject_urls" rows="3" required="required" placeholder="https://"><%= @report.subject_url_list.join("\n") %></textarea>
+      <span class="moderate-hint">
+        <%= t("moderate.notices.hints.content_url", default: "The exact link to the specific content you are reporting.") %>
+      </span>
+    </div>
+
+    <%# Content type — the host-agnostic bucket the snapshot/queue use. Prefilled from
+        ?content_type=… when it names a valid bucket; editable. %>
+    <div class="moderate-field">
+      <%= form.label :content_type, t("moderate.notices.fields.content_type", default: "Type of content") %>
+      <%= form.select :content_type,
+            content_types.map { |type| [t("moderate.content_types.#{type}", default: type.to_s.tr("_", " ").capitalize), type] },
+            { prompt: t("moderate.notices.prompts.content_type", default: "Select a content type") },
+            required: true %>
+    </div>
+
+    <%# Optional host-side handle/identifier the notice is about (a username, an
+        account id, …). Prefilled from ?content_author= or ?content_id= when the host
+        deep-links here; always EDITABLE and optional. %>
+    <div class="moderate-field">
+      <%= form.label :reported_account_identifier, t("moderate.notices.fields.reported_account_identifier", default: "Account or handle (optional)") %>
+      <%= form.text_field :reported_account_identifier %>
+      <span class="moderate-hint">
+        <%= t("moderate.notices.hints.reported_account_identifier", default: "If the content belongs to a specific account, add its username or handle.") %>
+      </span>
+    </div>
+
+    <%# Explanation — the "sufficiently substantiated explanation", Art. 16(2)(a).
+        Maps to the Report `message` column. Editable. %>
+    <div class="moderate-field">
+      <%= form.label :message, t("moderate.notices.fields.explanation", default: "Explanation") %>
+      <%= form.text_area :message, rows: 6, required: true %>
+      <span class="moderate-hint">
+        <%= t("moderate.notices.hints.explanation", default: "Explain why you believe this content is illegal, with enough detail for us to assess it.") %>
+      </span>
+    </div>
+
+    <%# EU member state — establishes jurisdiction and routing. Editable. %>
+    <div class="moderate-field">
+      <%= form.label :legal_country_code, t("moderate.notices.fields.member_state", default: "EU member state where this is illegal") %>
+      <%= form.select :legal_country_code,
+            member_states.map { |code| [t("moderate.member_states.#{code}", default: code.to_s), code] },
+            { prompt: t("moderate.notices.prompts.member_state", default: "Select a country") },
+            required: true %>
+    </div>
+
+    <%#
+      Notifier identity — Art. 16(2)(c). PREFILLED + LOCKED when a Devise
+      `current_user` is signed in: the fields render readonly so a logged-in notifier
+      can't swap in someone else's name/email, and the controller re-asserts the
+      value server-side on submit (a tampered request can't spoof identity onto a
+      legal notice). For an anonymous notifier the fields are blank and editable.
+      Name is required EXCEPT for `protection_of_minors` notices, where the DSA
+      permits anonymity (the model enforces that carve-out).
+      https://eur-lex.europa.eu/eli/reg/2022/2065/oj (Art. 16(2)(c))
+    %>
+    <div class="moderate-field">
+      <%= form.label :notifier_name, t("moderate.notices.fields.notifier_name", default: "Your name") %>
+      <%= form.text_field :notifier_name, readonly: identity_locked %>
+      <span class="moderate-hint">
+        <% if identity_locked %>
+          <%= t("moderate.notices.hints.identity_locked", default: "Taken from your account.") %>
+        <% else %>
+          <%= t("moderate.notices.hints.notifier_name", default: "Optional only for notices about offences involving minors, where the law permits anonymity.") %>
+        <% end %>
+      </span>
+    </div>
+
+    <div class="moderate-field">
+      <%= form.label :notifier_email, t("moderate.notices.fields.notifier_email", default: "Your email") %>
+      <%= form.email_field :notifier_email, required: true, readonly: identity_locked %>
+      <span class="moderate-hint">
+        <% if identity_locked %>
+          <%= t("moderate.notices.hints.identity_locked", default: "Taken from your account.") %>
+        <% else %>
+          <%= t("moderate.notices.hints.notifier_email", default: "We send the confirmation of receipt and our decision here.") %>
+        <% end %>
+      </span>
+    </div>
+
+    <%# Good-faith attestation — Art. 16(2)(d). MUST be checked; the model rejects
+        the save otherwise (`good_faith_confirmed` has `acceptance: true`). %>
+    <div class="moderate-field moderate-checkbox">
+      <%= form.check_box :good_faith_confirmed, required: true %>
+      <%= form.label :good_faith_confirmed,
+            t("moderate.notices.fields.good_faith", default: "I confirm in good faith that the information and allegations in this notice are accurate and complete.") %>
+    </div>
+
+    <%#
+      Cloudflare Turnstile widget — rendered ONLY when the host has the
+      `rails_cloudflare_turnstile` gem installed. When present, the gem mixes
+      RailsCloudflareTurnstile::ViewHelpers into ActionView (via its railtie), so
+      `cloudflare_turnstile` (the widget) and `cloudflare_turnstile_script_tag` (the
+      loader script) are available here and we render both automatically — the host
+      configures nothing beyond the gem + its keys. The controller auto-verifies the
+      challenge server-side (`validate_cloudflare_turnstile` before_action). When the
+      gem is ABSENT this block is skipped entirely and the gate falls back to
+      `config.notice_guard` (no-op by default), so the form just works.
+      https://github.com/instrumentl/rails-cloudflare-turnstile (README)
+    %>
+    <% if turnstile_widget_required? && respond_to?(:cloudflare_turnstile) %>
+      <div class="moderate-field">
+        <%= cloudflare_turnstile_script_tag if respond_to?(:cloudflare_turnstile_script_tag) %>
+        <%= cloudflare_turnstile %>
+      </div>
+    <% end %>
+
+    <div class="moderate-field">
+      <%= form.submit t("moderate.notices.submit", default: "Submit notice") %>
+    </div>
+  <% end %>
+</div>

data/app/views/moderate/transparency_reports/_summary_card.html.erb

@@ -0,0 +1,20 @@
+<%
+  rows = rows.to_h.compact_blank
+  translation_scope = local_assigns[:translation_scope]
+%>
+
+<article class="moderate-card">
+  <h2><%= title %></h2>
+  <% if rows.any? %>
+    <dl>
+      <% rows.sort_by { |key, _value| key.to_s }.each do |key, value| %>
+        <div>
+          <dt><%= translation_scope ? t("#{translation_scope}.#{key}", default: key.to_s.humanize) : key.to_s.humanize %></dt>
+          <dd><%= value %></dd>
+        </div>
+      <% end %>
+    </dl>
+  <% else %>
+    <p><%= t("moderate.transparency.no_data", default: "No data in this period.") %></p>
+  <% end %>
+</article>

data/app/views/moderate/transparency_reports/show.html.erb

@@ -0,0 +1,52 @@
+<style>
+  .moderate-page { color: var(--moderate-text, #111827); font-family: var(--moderate-font-family, system-ui, sans-serif); }
+  .moderate-hero { background: var(--moderate-accent, #facc15); padding: 3rem 1.25rem; }
+  .moderate-container { max-width: 56rem; margin: 0 auto; }
+  .moderate-eyebrow { margin: 0; font-size: .75rem; font-weight: 800; text-transform: uppercase; letter-spacing: .12em; color: var(--moderate-muted-text, #374151); }
+  .moderate-title { margin: .5rem 0 0; font-size: clamp(2rem, 6vw, 2.5rem); line-height: 1.1; font-weight: 900; }
+  .moderate-period { margin-top: 1rem; font-size: .875rem; font-weight: 700; color: var(--moderate-muted-text, #374151); }
+  .moderate-main { padding: 2.5rem 1.25rem; }
+  .moderate-grid { display: grid; gap: 1.5rem; }
+  @media (min-width: 768px) { .moderate-grid { grid-template-columns: 1fr 1fr; } }
+  .moderate-card { border: 1px solid rgba(17, 24, 39, .08); border-radius: .5rem; background: white; padding: 1.5rem; box-shadow: 0 1px 2px rgba(17, 24, 39, .04); }
+  .moderate-card h2 { margin: 0; font-size: 1.125rem; font-weight: 900; }
+  .moderate-card dl { display: grid; gap: .75rem; margin: 1rem 0 0; font-size: .875rem; }
+  .moderate-card dl > div { display: flex; align-items: center; justify-content: space-between; gap: 1rem; }
+  .moderate-card dt { color: var(--moderate-muted-text, #4b5563); }
+  .moderate-card dd { margin: 0; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-weight: 800; }
+  .moderate-card p { margin: 1rem 0 0; color: var(--moderate-muted-text, #6b7280); font-size: .875rem; }
+</style>
+
+<div class="moderate-page">
+  <section class="moderate-hero">
+    <div class="moderate-container">
+      <p class="moderate-eyebrow"><%= t("moderate.transparency.eyebrow", default: "Moderation") %></p>
+      <h1 class="moderate-title"><%= t("moderate.transparency.title", default: "Moderation transparency") %></h1>
+      <p class="moderate-period"><%= t("moderate.transparency.period", default: "Period: %{start} - %{end}", start: l(@period_start.to_date, format: :long), end: l(@period_end.to_date, format: :long)) %></p>
+    </div>
+  </section>
+
+  <main class="moderate-main">
+    <div class="moderate-container moderate-grid">
+      <%= render "summary_card", title: t("moderate.transparency.cards.notices_by_intake", default: "Notices by intake"), rows: @summary[:notices_by_intake] %>
+      <%= render "summary_card", title: t("moderate.transparency.cards.dsa_by_reason", default: "DSA notices by legal reason"), rows: @summary[:dsa_notices_by_legal_reason], translation_scope: "moderation.legal_reasons" %>
+      <%= render "summary_card", title: t("moderate.transparency.cards.actions_by_basis", default: "Actions by basis"), rows: @summary[:actions_by_basis], translation_scope: "moderation.resolution_bases" %>
+      <%= render "summary_card", title: t("moderate.transparency.cards.flags_by_source", default: "Automated flags by source"), rows: @summary[:automated_flags_by_source] %>
+      <%= render "summary_card", title: t("moderate.transparency.cards.appeals_by_status", default: "Appeals by status"), rows: @summary[:appeals_by_status] %>
+
+      <article class="moderate-card">
+        <h2><%= t("moderate.transparency.cards.median_times", default: "Median times") %></h2>
+        <dl>
+          <div>
+            <dt><%= t("moderate.transparency.notice_to_decision", default: "Notice to decision") %></dt>
+            <dd><%= distance_of_time_in_words(@summary[:median_notice_action_seconds].seconds) %></dd>
+          </div>
+          <div>
+            <dt><%= t("moderate.transparency.appeal_to_decision", default: "Appeal to decision") %></dt>
+            <dd><%= distance_of_time_in_words(@summary[:median_appeal_action_seconds].seconds) %></dd>
+          </div>
+        </dl>
+      </article>
+    </div>
+  </main>
+</div>

data/config/moderate/blocklists/en.yml

@@ -0,0 +1,81 @@
+# English blocklist for the built-in :wordlist filter adapter
+# (Moderate::Filters::Wordlist).
+#
+# ── Format ───────────────────────────────────────────────────────────────────
+# Top-level keys are CANONICAL TAXONOMY categories (see Moderate::Label::TAXONOMY,
+# itself the OpenAI omni-moderation-latest taxonomy:
+# https://developers.openai.com/api/docs/guides/moderation). Using the canonical
+# vocabulary here — instead of the ad-hoc bucket names a host might invent — is the
+# whole point: every adapter (this offline wordlist, the OpenAI endpoint, a host's
+# own backend) emits the SAME category set, so Moderate::Flag, the DSA Art. 17
+# statement of reasons, and the Art. 24 transparency counters all aggregate over
+# one set. A category may be a bare top-level slug ("hate") or a slash-qualified
+# subcategory ("hate/threatening") — both are valid canonical slugs.
+#
+# Each category maps to a list of REGEX patterns (Ruby Regexp source strings).
+# Patterns are matched against NORMALIZED text — already lowercased, NFKD-folded
+# (accents stripped), leetspeak-transliterated (0->o, 3->e, @->a, ...), and
+# collapsed to single spaces — AND against the same text with all spaces removed
+# (to defeat "f u c k"-style spacing evasion). So write patterns in lowercase,
+# ASCII, space-separated form; the adapter handles the evasion-resistance.
+#
+# ── Why labels, not the raw word, are stored ─────────────────────────────────
+# The adapter records the matched CATEGORY, never the offending substring, so a
+# validation error or a queue entry never echoes abusive language back into the UI
+# or the logs. (Same discipline as Apple Guideline 1.2 / Google Play UGC reviews
+# expect: https://developer.apple.com/app-store/review/guidelines/#user-generated-content
+# https://support.google.com/googleplay/android-developer/answer/9876937)
+#
+# ── This is a SEED, not a complete classifier ────────────────────────────────
+# A static wordlist is a fast, offline, multilingual FIRST line of defense — it
+# satisfies the store bar of "a method for filtering objectionable UGC before
+# posting" and catches the obvious cases with zero dependencies and zero latency.
+# It is deliberately small and conservative (false positives block real users).
+# For nuanced, context-aware moderation, register the :openai adapter or your own.
+# Extend without editing the gem via `config.additional_words` /
+# `config.excluded_words`.
+
+# Slurs / dehumanizing abuse directed at protected groups -> hate.
+# Write plain word-boundary patterns; the adapter's normalization (NFKD fold,
+# leetspeak, punctuation collapse) plus the compact-form match handle spacing and
+# symbol evasion, so there's no need to hand-encode "n i g g e r" variants here.
+hate:
+  - "\\bnigg(er|a)\\b"
+  - "\\bfagg?ot\\b"
+  - "\\bkike\\b"
+  - "\\bspic\\b"
+  - "\\bchink\\b"
+  - "\\btrann(y|ie)\\b"
+
+# Threats of violence / encouraging self-harm of another -> hate/threatening.
+# (Direct threats and incitement to self-harm, e.g. "I'm going to kill you" / "kys".)
+hate/threatening:
+  - "\\bkill\\s+yourself\\b"
+  - "\\bkys\\b"
+  - "\\bi\\s*(am|m)\\s+going\\s+to\\s+kill\\s+you\\b"
+
+# Insults / demeaning abuse aimed at an individual -> harassment.
+harassment:
+  - "\\bbitch\\b"
+  - "\\bcunt\\b"
+  - "\\bfuck(er|ing|ed)?\\b"
+  - "\\basshole\\b"
+  - "\\bretard(ed)?\\b"
+  - "\\bwh[o0]re\\b"
+
+# Explicit sexual content -> sexual.
+sexual:
+  - "\\bporn(o|ography)?\\b"
+  - "\\bnude\\s+pics?\\b"
+  - "\\bexplicit\\s+sex\\b"
+
+# Graphic depiction of violence -> violence/graphic.
+violence/graphic:
+  - "\\bgore\\b"
+  - "\\bbeheading\\b"
+
+# Solicitation of illegal/regulated goods or scams -> illicit.
+illicit:
+  - "\\bfree\\s+crypto\\b"
+  - "\\bquick\\s+money\\b"
+  - "\\bwhatsapp\\s+casino\\b"

data/config/moderate/blocklists/es.yml

@@ -0,0 +1,40 @@
+# Spanish blocklist for the built-in :wordlist filter adapter
+# (Moderate::Filters::Wordlist).
+#
+# Same format and rules as en.yml — see that file's header for the full
+# explanation. In short: top-level keys are CANONICAL TAXONOMY categories
+# (Moderate::Label::TAXONOMY / OpenAI omni-moderation-latest:
+# https://developers.openai.com/api/docs/guides/moderation); values are Ruby
+# Regexp source strings matched against normalized (lowercased, NFKD-folded,
+# leetspeak-transliterated, single-spaced) text AND its space-stripped form.
+#
+# This list ships alongside en.yml because the wordlist adapter is "multilingual
+# by default": it loads and merges EVERY bundled locale's list, so an app with a
+# mixed-language audience is covered without configuration. Shipping a real
+# Spanish list (not just English) is deliberate. Write patterns lowercase + ASCII:
+# accents are folded out before matching, so "cabrón" is matched by "cabron".
+
+# Insultos / abuso degradante hacia una persona -> harassment.
+harassment:
+  - "\\bputa\\b"
+  - "\\bputo\\b"
+  - "\\bgilipollas\\b"
+  - "\\bcabr[o0]n\\b"
+  - "\\bzorra\\b"
+  - "\\bmaric[o0]n\\b"
+
+# Amenazas de violencia -> hate/threatening.
+hate/threatening:
+  - "\\bte\\s+voy\\s+a\\s+matar\\b"
+  - "\\bvoy\\s+a\\s+matarte\\b"
+
+# Contenido sexual explícito -> sexual.
+sexual:
+  - "\\bporn[o]?\\s+explicit[o0]\\b"
+  - "\\bsex[o0]\\s+explicit[o0]\\b"
+
+# Solicitud de bienes ilícitos / estafas -> illicit.
+illicit:
+  - "\\bcrypto\\s+gratis\\b"
+  - "\\bdinero\\s+rapido\\b"
+  - "\\bwhatsapp\\s+casino\\b"

data/config/routes.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# The engine's routes. They are RELATIVE on purpose: the engine declares only the
+# resource, and the HOST chooses the mount point in its own routes —
+#
+#   mount Moderate::Engine => "/trust"      # => form at /trust/notices/new
+#   mount Moderate::Engine => "/moderation" # => form at /moderation/notices/new
+#   mount Moderate::Engine => "/dsa"        # => form at /dsa/notices/new
+#
+# We deliberately do NOT hardcode a "/legal" prefix here (or anywhere). The path is
+# the host's call; the gem only owns the routes RELATIVE to wherever it's mounted.
+#
+# Because the engine is isolated, these become the `moderate.` URL-helper proxy in
+# the host (e.g. `moderate.new_notice_path`). NOTHING here is required to use the
+# rest of the gem (report/block/filter/queue) — mounting is only for the public
+# DSA Art. 16 notice form. See docs/dsa-notice-form.md.
+Moderate::Engine.routes.draw do
+  # The public DSA "notice and action" form.
+  #   GET  /notices/new   — the form (prefillable via query params; see the controller)
+  #   POST /notices        — submit (validate + persist a dsa-kind Moderate::Report +
+  #                          confirm receipt, Art. 16(4))
+  #
+  # Only :new and :create — a notice is a `Moderate::Report` with no public,
+  # enumerable identifier, so there is no per-notice `show` page; on success the
+  # controller redirects back to the form with a confirmation flash (the durable,
+  # on-record proof of receipt is the report's `acknowledged_at`, and the human-
+  # facing confirmation goes out through the `notice_received` notify hook).
+  resources :notices, only: %i[new create]
+  resources :appeals, only: %i[new create]
+  resource :transparency, only: :show, controller: "transparency_reports"
+
+  # The engine root redirects to the form, so mounting the engine makes its mount
+  # point itself a sensible landing spot (and a fine place to host the DSA Art.
+  # 11/12 "point of contact" copy once the views are ejected).
+  root to: "notices#new"
+end