moderate 0.1.0 → 1.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7c7f6fd1cfa1c2ba6b28e2d0b75ce803d0ae2eec002011b18a9a25b2b98ce6f
-  data.tar.gz: 71bab2651af6c3ff8520360281811b53d21a711496a9ef392334e8b2a59646b5
+  metadata.gz: 446ba3a97f77b4a88ebbd1d6e45e7935d6002be573835ef750829f54adaa47a7
+  data.tar.gz: 799dd6c0e21cac2b0b8038e268cf02baec331717c427ddf1d51bafa482b88776
 SHA512:
-  metadata.gz: adfb034df21d5ecfa8fec498f34df2d6595d33033f05e7fb2832ec52f7c0012fa43806950b9c9d723cc0508563159972e57ceb051e3263ca0cfff11583bb9959
-  data.tar.gz: 2dd06af75442e89d39e18f44c7dc61e37030dfbee6406f5be096903418489f9061dea5262aeaa874431ec4c3ac82f3c93933036d7715e3255e6431715c6923ff
+  metadata.gz: 00f2800700b563559a9d8d40dc2a3fea24d487d24d2f660059908a2b377cce5627354961f3bfeff0d7f1da2c5666cc9aac45c1603a48c15ff20c9ad4b2502d33
+  data.tar.gz: c047552f0534a7df8642d2615d112723b19ecaeb62d870261c13c4fb8b114833dc0ba72ae9a646cb8e4cacba658bd1e705724c451c58a2b0348506aece0c4fbd

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.2
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/.simplecov

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# SimpleCov configuration file (auto-loaded before test suite)
+# This keeps test_helper.rb clean and follows best practices.
+# Coherent with the rest of the gem ecosystem (usage_credits, pricing_plans, …).
+
+SimpleCov.start do
+  # Use SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  # Don't count the test suite itself toward coverage
+  add_filter "/test/"
+
+  # Don't count code that ISN'T unit-testable by this suite and would only distort
+  # the numbers:
+  #   - Generators + their templates: these run via `rails generate moderate:install`
+  #     / `moderate:views` in a real host, not in the engine's own unit suite. (The
+  #     migration template IS exercised indirectly — the dummy migrates a copy of it —
+  #     but the .erb itself is never loaded as Ruby here.)
+  #   - version.rb: a single constant; nothing to cover.
+  #   - The 0.x compatibility shims (text / text_validator / word_list): legacy
+  #     profanity-validator code kept only so `validates :field, moderate: true` from
+  #     0.x still loads (see README "Upgrading from 0.x"). They are NOT part of the
+  #     1.0 Trust & Safety surface this suite tests, so they shouldn't pull the 1.0
+  #     coverage number down.
+  add_filter "/lib/generators/"
+  add_filter "/lib/moderate/version.rb"
+  add_filter "/lib/moderate/text.rb"
+  add_filter "/lib/moderate/text_validator.rb"
+  add_filter "/lib/moderate/word_list.rb"
+
+  # Track Ruby files in the lib directory (gem source code)
+  track_files "lib/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
+  enable_coverage :branch
+
+  # Minimum coverage thresholds to prevent coverage REGRESSION. These reflect what
+  # the current shipped suite actually exercises (line ~86%, branch ~65%): the
+  # primitives — models, concerns, services, adapters, the facade, the value objects —
+  # are thoroughly covered; the lower branch number is driven by the engine's
+  # CONTROLLERS (the public DSA notice form + the BYOUI moderation concern) and the
+  # async ClassifyJob, whose request/job paths the unit suite doesn't drive. The
+  # thresholds sit just under the current floor so the gate catches a real regression
+  # without failing on the existing baseline; raise them as request/job coverage grows.
+  minimum_coverage line: 80, branch: 60
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV["TEST_ENV_NUMBER"]
+end
+
+# Print coverage summary to terminal after tests complete
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n" + "=" * 60
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  branch_coverage = SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || "N/A"
+  puts "Branch Coverage: #{branch_coverage}%"
+  puts "=" * 60
+end

data/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (like OpenAI's Codex, Cursor Agent, Claude Code, etc) when working with code in this repository.
+
+Please read the `README.md` for a full overview of the gem's API and philosophy, and the `docs/` directory (`docs/configuration.md`, `docs/notifications.md`, `docs/compliance.md`, `docs/madmin.md`, `docs/dsa-notice-form.md`) for the detailed integration guides.
+
+This gem is part of a coherent ecosystem (`railsfast`, `goodmail`, `telegrama`, `usage_credits`, `pricing_plans`, `wallets`, `api_keys`). Match the ecosystem conventions exactly: a single `Moderate.configure do |config| … end` block, `has_*`/verb-style class macros, adapter objects + no-op-default hook procs, string class names constantized lazily, adaptive install migrations, Minitest with a `test/dummy` app, SimpleCov, and the README/docs voice.

data/Appraisals

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Test the minimum supported Rails version (matches the gemspec floor and the
+# README's "Rails 7.1+ schema" claim — the adaptive migration must work here).
+appraise "rails-7.1" do
+  gem "rails", "~> 7.1.0"
+end
+
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+# Test the latest Rails version — this is the default/main Gemfile anyway.
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.0"
+end

data/CHANGELOG.md

@@ -1,3 +1,73 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - unreleased
+
+A complete, ground-up rewrite. `moderate` graduates from a single-purpose profanity
+validator (0.1.0) into a full **Trust & Safety** engine for Rails apps with user-generated
+content: report, block, filter, a moderation queue, appeals, and EU DSA / App Store / Google
+Play **aligned** primitives. (First cut ships as `1.0.0.beta1`.)
+
+> **Breaking:** 1.0 keeps the gem name but is an entirely new API. The 0.x profanity
+> validator (`validates :field, moderate: true`) still loads for backward compatibility
+> (see _Upgrading from 0.x_), but everything else is new. Pin `~> 0.1` if you relied on the
+> old behavior and are not ready to adopt the new surface.
+
+### Added
+
+- **Reporting.** `Moderate::Report` plus the `has_reportable_content :fields` macro and
+  `Actor#report!(reportable, category:, details:)`. Reports and DSA notices share one model
+  and one queue (`intake_kind: "community" | "dsa"`).
+- **Blocking.** `Moderate::Block`, the `has_reporting_and_blocking` actor macro, and
+  `block!` / `unblock!` / `blocks?` / `blocked_by?` / `blocked_with?`. `Moderate.blocked_ids_for(user)`
+  is the bidirectional single source of truth you compose into feed/search/inbox queries.
+  Optional `config.on_block` teardown hook runs inside the block transaction.
+- **Content filtering.** The `moderates :field, mode: :off|:block|:flag, with: :adapter` macro
+  (and the equivalent `config.filter`), the offline multilingual `:wordlist` adapter (the only
+  built-in), the `classify(value) => Moderate::Result` adapter contract with
+  `config.register_adapter`, asynchronous classification via `Moderate::ClassifyJob`, and
+  ready-to-copy reference adapters for OpenAI omni-moderation and AWS Rekognition under
+  `examples/` (bring-your-own, never a dependency).
+- **Moderation queue & decisions.** `Moderate::Flag` and the service objects
+  `Moderate::Services::{IntakeReport, ResolveReport, ResolveFlag, IntakeAppeal, ResolveAppeal,
+  IntakeNotice}`. Decisions are taken under a row lock, re-check open state, apply enforcement
+  (remove content / ban) inside the transaction, and fire notifications outside it; the appeal
+  window and statement-of-reasons fields are stamped automatically.
+- **DSA-aligned primitives.** A mountable public **notice-and-action** form (Art. 16) you mount
+  at any path, **statement of reasons** (Art. 17), internal **appeals** (Art. 20), and
+  **transparency** counters (Art. 24). The notice form prefills from query params + the signed-in
+  user, locks auto-filled identity fields, and auto-detects `rails_cloudflare_turnstile`.
+- **Hooks (all no-op by default).** `config.audit`, `config.notify` (returns a delivery boolean
+  used to gate `decision_notified_at`), `config.on_block`, `config.ban_handler`, the
+  host-overridable `config.report_categories`, and `config.notice_human_verification_skip_if` /
+  `config.appeal_human_verification_skip_if` for native-app bot-gate carve-outs.
+- **Optional integrations**, all auto-detected at runtime via `defined?`/`respond_to?` and never
+  hard dependencies: madmin, goodmail, telegrama, noticed, rails_cloudflare_turnstile.
+- **Install tooling.** `rails generate moderate:install` writes a documented initializer and an
+  adaptive migration (uuid/bigint primary keys, jsonb/json/MySQL JSON columns); `moderate:views`
+  ejects the notice form for customization.
+
+### Changed
+
+- Taxonomies (report categories, DSA legal reasons, country codes) are now frozen model
+  constants with inclusion validations instead of DB `CHECK` constraints — adding or
+  customizing a category needs no migration.
+- External classifiers (OpenAI, image moderation) are reference adapters in `examples/`, not
+  shipped or loaded code — the gem core forces no service dependency on apps that never use it.
+- All "DSA-compliant" / "App Store compliant" language reframed to **DSA-aligned primitives**:
+  the gem ships the mechanisms the law and the stores require; your policies, response times,
+  and operations are still yours.
+
+### Upgrading from 0.x
+
+- The 0.x profanity validator still loads: `validates :field, moderate: true` continues to work
+  via compatibility shims, so existing apps keep validating. To adopt 1.0, add
+  `has_reporting_and_blocking` to your user model and `has_reportable_content` / `moderates` to your
+  content models, run `rails generate moderate:install`, and migrate.
+
 ## [0.1.0] - 2024-11-03
 
-- Initial release
+- Initial release (profanity validator).

data/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Please read the `README.md` for a full overview of the gem's API and philosophy, and the `docs/` directory (`docs/configuration.md`, `docs/notifications.md`, `docs/compliance.md`, `docs/madmin.md`, `docs/dsa-notice-form.md`) for the detailed integration guides.
+
+This gem is part of a coherent ecosystem (`railsfast`, `goodmail`, `telegrama`, `usage_credits`, `pricing_plans`, `wallets`, `api_keys`). Match the ecosystem conventions exactly: a single `Moderate.configure do |config| … end` block, `has_*`/verb-style class macros, adapter objects + no-op-default hook procs, string class names constantized lazily, adaptive install migrations, Minitest with a `test/dummy` app, SimpleCov, and the README/docs voice.

data/README.md

@@ -1,71 +1,418 @@
-# 👮‍♂️ `moderate` - Moderate and block bad words from your Rails app
+# 🛡️ `moderate` -  Let your Rails users report content and block each other (Trust & Safety)
 
-`moderate` is a Ruby gem that moderates user-generated text content by adding a simple validation to block bad words in any text field.
+[![Gem Version](https://badge.fury.io/rb/moderate.svg)](https://badge.fury.io/rb/moderate) [![Build Status](https://github.com/rameerez/moderate/workflows/Tests/badge.svg)](https://github.com/rameerez/moderate/actions)
 
-Simply add this to your model:
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=moderate)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=moderate)!
+
+`moderate` gives your Rails app a complete **Trust & Safety** system.
+
+Trust & Safety (T&S) is the system within an app that lets users **report** abusive content, **block** each other, **filter** objectionable text and images before they're posted (profanity, bad words, NSFW / nudity, etc.), and run a **moderation queue** your admins actually use. It also allows you to easily plug in automated AI moderation systems like **OpenAI Moderation** or **AWS Rekognition** to quickly filter, flag and/or automatically block harmful content (text or image).
+
+If you have an app where users can upload / generate content or send messages to each other, you probably need a Trust & Safety system.
+
+`moderate` ships with mechanisms aligned with the **DSA** (EU Digital Services Act), and also aligned with the **Apple App Store** and Android's **Google Play** directives for User-Generated Content (UGC) in their app stores.
+
+## 👨‍💻 Example
+
+`moderate` reads like plain English. Make any model reportable:
+
+```ruby
+class Comment < ApplicationRecord
+  has_reportable_content
+end
+```
+
+Let any user block another:
+
+```ruby
+current_user.block!(@other_user)
+current_user.blocks?(@other_user)   # => true
+```
+
+Filter content before it's posted — the zero-setup wordlist, or a real classifier like OpenAI moderation:
 
 ```ruby
-validates :text_field, moderate: true
+# config/initializers/moderate.rb — wire up OpenAI moderation once (text AND images)
+config.register_adapter :openai, OpenAIModerationAdapter.new
 ```
 
-That's it! You're done. `moderate` will work seamlessly with your existing validations and error messages.
+```ruby
+class Message < ApplicationRecord
+  # Run every DM through OpenAI, but never block mid-conversation: `:flag` lets the
+  # message send, then classifies it in a background job and drops anything harmful
+  # into the moderation queue for review.
+  moderates :body, mode: :flag, with: :openai
+end
+```
 
-> [!WARNING]
-> This gem is under development. It currently only supports a limited set of English profanity words. Word matching is very basic now, and it may be prone to false positives, and false negatives. I use it for very simple things like preventing new submissions if they contain bad words, but the gem can be improved for more complex use cases and sophisticated matching and content moderation. Please consider contributing if you can improve the gem, or have good ideas for additional features.
+No API keys to start? Drop the `with:` and you get the built-in, zero-dependency `:wordlist` (a fast, multilingual profanity block) — same one-line API.
 
-# Why
+And give admins a real queue to act on:
 
-Any text field where users can input text may be a place where bad words can be used. This gem blocks records from being created if they contain bad words, profanity, naughty / obscene words, etc.
+```ruby
+Moderate::Report.pending           # everything awaiting a decision
+report.resolve!(by: current_user, remove_content: true, ban_user: true, note: "Hate speech")
+```
 
-It's good for Rails applications where you need to maintain a clean and respectful environment in comments, posts, or any other user input.
+That's the whole idea: **the messy, legally-loaded plumbing every social/UGC app needs (report, block, filter, moderate, appeal, comply) as one coherent Ruby gem** instead of scattered, half-finished, store-rejecting DIY code.
 
-# How
+> [!NOTE]
+> `moderate` is **UI-agnostic by design**: most of a Trust & Safety system lives in *admin* surfaces, so the gem ships the **primitives** (models, services, helpers, controller concerns) and lets you **build your own UI**. It plugs into [`madmin`](https://github.com/excid3/madmin) (or any admin system) in minutes; see [Admin & moderation queue](#-admin--the-moderation-queue).
 
-`moderate` currently downloads a list of ~1k English profanity words from the [google-profanity-words](https://github.com/coffee-and-fun/google-profanity-words) repository and caches it in your Rails app's tmp directory.
+---
 
-## Installation
+## Quickstart
 
-Add this line to your application's Gemfile:
+Add the gem:
 
 ```ruby
-gem 'moderate'
+gem "moderate"
 ```
 
-And then execute:
+Install it (creates the migration + an initializer):
 
 ```bash
 bundle install
+rails generate moderate:install
+rails db:migrate
+```
+
+Tell `moderate` who your users are, and make a model reportable:
+
+```ruby
+# config/initializers/moderate.rb
+Moderate.configure do |config|
+  config.user_class = "User"
+end
+```
+
+```ruby
+class User < ApplicationRecord
+  has_reporting_and_blocking      # can report, block, be blocked, be banned
+end
+
+class Post < ApplicationRecord
+  has_reportable_content          # users can report it
+  moderates :body, mode: :block   # …and profanity is rejected on save — zero-setup built-in wordlist
+end
+```
+
+That's it. You now have reporting, blocking, filtering, and a moderation queue. Everything below is detail.
+
+---
+
+## Why this gem exists
+
+Every app with user-generated content eventually faces the same wall. A user posts something vile, another user wants them gone, Apple rejects your build for "no way to report objectionable content," and a Spanish lawyer emails you about the Digital Services Act. So you start bolting on a `reports` table, a `blocks` table, a profanity regex, an admin page, a "notify the reporter" email… and it's suddenly a sprawling, half-correct subsystem entangled with your core app.
+
+It's the kind of plumbing nobody wants to build, everybody rebuilds, and almost everybody ships *incomplete* — which is exactly what gets apps rejected from the stores and exposed under the DSA. `moderate` is the single, opinionated, batteries-included source of truth for it:
+
+- **Report** users and content (in-app), with evidence snapshots and a real decision workflow.
+- **Block** users (bidirectional), enforced everywhere a blocked pair could reconnect.
+- **Filter** text and images before they're posted (`:off` / `:block` / `:flag`), with pluggable backends — a built-in offline wordlist, plus ready-to-copy reference adapters in `examples/` (OpenAI, AWS Rekognition) or your own.
+- **Moderate** from a queue: remove content, ban users, dismiss, all audited.
+- **Align** with the core DSA / store-review mechanisms: notice-and-action (Art. 16), statement of reasons (Art. 17), internal appeals (Art. 20), transparency counters (Art. 24); Apple Guideline 1.2 and Google Play UGC requirements.
+
+Typical offending content include categories like these, all covered by the `moderate` gem: `harassment`, `hate`, `threats`, `sexual_content`, `spam`, `fraud`, `unsafe_behavior`, `illegal_content`, `privacy`, `child_safety`, `other`, `hate_abuse_harassment`, `violent_speech`, `graphic_violent_media`, `illegal_regulated_behaviors`, `impersonation`, `adult_sexual_content`, `private_non_consensual_content`, `suicide_self_harm`, `terrorism_violent_extremism`, `scam_fraud`
+
+> [!IMPORTANT]
+> The `moderate` gem is not a compliance certificate. You still own your policies, legal review, published contact information, jurisdiction-specific obligations, and day-to-day moderation operations. For example, EU DSA Article 19/24 complaint-handling and transparency duties have size/tier carve-outs (including micro/small enterprise exemptions); `moderate` just gives you the mechanisms when you need them, not a legal conclusion that every app must use every surface.
+
+## What `moderate` does and doesn't do
+
+**Does:**
+- User & content **reporting** (in-app) + a public **DSA legal-notice** intake form.
+- **Blocking** with a single source-of-truth query you enforce in search, messaging, profiles, anywhere.
+- **Pre-publication content filtering** with three modes and pluggable adapters — the built-in offline wordlist (text), plus image/LLM moderation via reference adapters you register (see `examples/`).
+- A **moderation queue** with audited resolve / dismiss / remove-content / ban actions.
+- **Appeals**, **statement-of-reasons** notifications, and **transparency** aggregation for the DSA.
+- Optional **audit** and **notification** hooks that fan out to your mailer / admin alerts / push.
+
+**Doesn't** (on purpose — these are other tools' jobs):
+- Authentication / current-user (that's Devise — you tell `moderate` your user class).
+- Sending the actual emails/push (that's [`goodmail`](https://github.com/rameerez/goodmail) / [`noticed`](https://github.com/excid3/noticed) — `moderate` just emits events).
+- The admin UI chrome (that's [`madmin`](https://github.com/excid3/madmin) / your app — `moderate` gives you the data + primitives).
+- A bulletproof ML classifier out of the box (the default text filter is a fast, multilingual wordlist; bring an LLM/image adapter when you want one).
+
+---
+
+## 🧑‍🤝‍🧑 Actors: report & block
+
+Add `has_reporting_and_blocking` to your user model (or any model that acts on behalf of a person):
+
+```ruby
+class User < ApplicationRecord
+  has_reporting_and_blocking
+end
+```
+
+*(Prefer an explicit include? `include Moderate::Actor` is the exact equivalent — the macro just lazily includes it.)*
+
+**Blocking** is a bidirectional safety edge — once either side blocks, neither should see or reach the other:
+
+```ruby
+current_user.block!(@other)     # idempotent; audited; fires your on_block hook
+current_user.unblock!(@other)
+current_user.blocks?(@other)    # I blocked them
+current_user.blocked_by?(@other)
+current_user.blocked_with?(@other)   # either direction — the one you check in features
+```
+
+Enforce it anywhere with the single source-of-truth query (no hand-rolled block SQL ever again):
+
+```ruby
+# Hide blocked people from a marketplace / search / inbox:
+Post.where.not(user_id: Moderate.blocked_ids_for(current_user))
+```
+
+**Reporting** content or a person:
+
+```ruby
+current_user.report!(@message, category: :harassment, details: "Won't stop messaging me")
+current_user.report!(@user,    category: :impersonation)
+```
+
+`moderate` snapshots the offending content at report time (so evidence survives edits/deletes), infers who's responsible, sends the reporter a receipt, and drops it in the queue.
+
+## 🚩 Reportable content
+
+Declare what can be reported with one `has_reportable_content` line — the fields are optional (omit them to report the whole record):
+
+```ruby
+class Listing < ApplicationRecord
+  has_reportable_content :title, :description
+
+  # Tell moderate how to present & clean this content when a moderator acts:
+  def moderation_label = "Listing #{id}"
+  def reported_owner   = user                # who's responsible (defaults sensibly)
+end
 ```
 
-Then, just add the `moderate` validation to any model with a text field:
+*(Explicit-include equivalent: `include Moderate::Reportable` + `reportable_fields :title, :description`.)*
+
+You get:
 
 ```ruby
-validates :text_field, moderate: true
+listing.reports          # reports filed against this record
+listing.reported?        # any open report?
+listing.flagged?         # any pending flag (auto-filter OR manual)?
+listing.flagged?(:description) # field-level pending flag?
+```
+
+Drop a report link into any view with the helper (it renders nothing if the viewer can't report the content):
+
+```erb
+<%= moderate_report_link(@listing, field: :description) %>
 ```
 
-`moderate` will raise an error if a bad word is found in the text field, preventing the record from being saved.
+Because `moderate` is UI-agnostic, it does not render a built-in "under review" badge. Use `flagged?` / `flagged?(:field)` to render copy that fits your product when `:flag` mode lets content through but queues it for review.
 
-It works seamlessly with your existing validations and error messages.
+If your app runs inside Hotwire Native / Turbo Native, remember that native path configuration is host-owned. Add rules for the in-app report routes you mount (for example `/reports/new` **and** the form action `/reports`, so validation errors stay in the same modal stack) and for the engine's public legal routes **and their form actions** such as `<mount>/notices/new`, `<mount>/notices`, `<mount>/appeals/new`, `<mount>/appeals`, and `<mount>/transparency` — where `<mount>` is wherever you mounted `Moderate::Engine` in your routes (it is host-chosen, not fixed). `moderate` can provide the Rails routes; your native shell still decides whether they push, present modally, use a sheet, and which Android `uri` maps to the destination.
 
-## Configuration
+Adding a new reportable type is one `has_reportable_content` line — the intake, queue, snapshot, and admin code never change.
+
+## 🧪 Content filtering: `:off` / `:block` / `:flag`
+
+Filtering is one declaration per field, with three modes:
+
+```ruby
+class Message < ApplicationRecord
+  moderates :body                       # uses the default mode (see config)
+end
+
+class Profile < ApplicationRecord
+  moderates :bio,    mode: :block       # reject the save if it trips the filter
+  moderates :avatar, mode: :flag, with: :image   # `:image` = a registered adapter (see examples/); only :wordlist ships built in
+end
+```
+
+- **`:off`** — no check.
+- **`:block`** — the write is rejected with a validation error (great for public, high-trust fields).
+- **`:flag`** — the write **succeeds**, and a `Moderate::Flag` is created **after commit** for human or automated review (great for DMs, where you don't want to block mid-conversation).
+
+Why this matters: `:flag` never lives in a validator (validators must be side-effect-free, and a flag created inside a rolled-back transaction would silently vanish) — `moderate` handles that correctly for you.
+
+Check content directly anywhere:
+
+```ruby
+result = Moderate.classify("some sketchy text")
+result.allowed?    # => false
+result.categories  # => [:hate, :"hate/threatening"]
+result.scores      # => { "hate" => 0.97, "hate/threatening" => 0.81 }   (0..1 for service adapters)
+result.labels      # => [#<Label category: :hate, subcategory: :threatening, score: 0.81, input: :text>, …]
+```
+
+### Filter adapters (the built-in wordlist, reference adapters, your own — one interface)
+
+Every backend implements the same tiny contract — `classify(value) → Moderate::Result` — so they're interchangeable per field. `moderate` ships exactly **one** built-in adapter, the offline `:wordlist`; OpenAI, AWS Rekognition, and anything else are **bring-your-own** — copy a ready-made reference adapter from [`examples/`](examples/), add its gem to *your* Gemfile, and `register_adapter` it:
+
+| Adapter | Use it for | Notes |
+| --- | --- | --- |
+| `:wordlist` (built-in, default) | text | Fast offline baseline, multilingual, zero-dependency. Includes Unicode normalization and common substitution handling, but it is not a contextual classifier. Ships `en`/`es` lists; add your own. The only adapter the gem ships. |
+| OpenAI (reference adapter — [`examples/openai_moderation_adapter.rb`](examples/openai_moderation_adapter.rb)) | **text *and* image** | OpenAI `omni-moderation-latest` via the `ruby_llm` gem — **free**, multimodal, its category set IS the canonical taxonomy + `0..1` scores. Copy it in, `gem "ruby_llm"`, `register_adapter(:openai, …)`. Runs **async** (`Moderate::ClassifyJob`) in `:flag` mode. |
+| AWS Rekognition (reference adapter — [`examples/aws_rekognition_adapter.rb`](examples/aws_rekognition_adapter.rb)) | images / avatars | `detect_moderation_labels` via `aws-sdk-rekognition`, with its taxonomy mapped onto the canonical labels. Copy it in, `gem "aws-sdk-rekognition"`, `register_adapter(:rekognition, …)`. Async, `:flag` mode. |
+| *your own* | anything | `register_adapter(:replicate, …)` / Perspective / a self-hosted model — any object responding to `classify`. No built-in pretends the backend must be an "LLM". |
+
+All adapters map their provider labels onto **one canonical taxonomy** (OpenAI's: `harassment[/threatening]`, `hate[/threatening]`, `sexual[/minors]`, `self-harm[/intent|/instructions]`, `violence[/graphic]`, `illicit[/violent]`), so `Moderate::Flag`, the DSA statement of reasons, and the transparency counters all speak one vocabulary.
 
-You can configure the `moderate` gem behavior by adding a `config/initializers/moderate.rb` file:
 ```ruby
 Moderate.configure do |config|
-  # Custom error message when bad words are found
-  config.error_message = "contains inappropriate language"
+  config.default_filter_mode = :block
+  config.filter_adapter      = :wordlist
+
+  # Bring an external classifier: copy examples/openai_moderation_adapter.rb into
+  # your app, add `gem "ruby_llm"`, then register and use it by name.
+  config.register_adapter :openai, OpenAIModerationAdapter.new
+
+  config.filter "Message", :body,   with: :wordlist, mode: :flag
+  config.filter "Profile", :avatar, with: :openai,   mode: :flag   # one adapter moderates text AND images
+end
+```
+
+> **`:block` requires a synchronous adapter** (`:wordlist`) — you can't reject a save on a background result. The async reference adapters (the OpenAI/Rekognition examples) declare `synchronous? == false`, so they run in `:flag` mode (allow the write, classify in a job, file a `Moderate::Flag`). `moderate` validates this for you and says so.
+
+Bring your own adapter — it's just an object that responds to `classify`:
+
+```ruby
+class MyAdapter
+  def classify(value) = Moderate::Result.new(allowed: ..., categories: [...], scores: {...})
+end
+Moderate.register_adapter(:my_adapter, MyAdapter.new)
+```
+
+> The original `moderate` (≤ 0.1) was *only* a profanity validator. That `validates :field, moderate: true` one-liner still works — it's now the `:wordlist` adapter in `:block` mode. See [Upgrading from 0.x](#upgrading-from-0x).
+
+## 🛠️ Admin & the moderation queue
+
+Most of Trust & Safety happens in admin. `moderate` gives you the primitives; you bring the UI.
+
+```ruby
+Moderate::Report.pending             # the report queue
+Moderate::Flag.pending               # the auto-filter queue (human OR ML consumer reads the same scope)
+Moderate::Appeal.pending             # appeals awaiting a human
+
+report.resolve!(by: admin, remove_content: true, ban_user: false, note: "Removed: hate speech")
+report.dismiss!(by: admin, note: "No violation")
+appeal.uphold!(by: admin, note: "...")   # overturns the decision
+appeal.reject!(by: admin, note: "...")
+```
 
-  # Add your own words to the blacklist
-  config.additional_words = ["badword1", "badword2"]
+Every action is atomic, requires a moderator + a note, runs your enforcement (content removal via the reportable's own `remove_reported_field!`, bans via your `ban_handler`), and writes to your audit log.
 
-  # Exclude words from the default list (false positives)
-  config.excluded_words = ["good"]
+### Use it from a controller (BYOUI)
+
+```ruby
+class Admin::ReportsController < ApplicationController
+  include Moderate::Moderation   # resolve!/dismiss! actions, strong params, redirects
+
+  before_action :require_admin
 end
 ```
 
+### Integrate with [`madmin`](https://github.com/excid3/madmin)
+
+`moderate`'s models are plain ActiveRecord, so they show up in `madmin` like anything else. Generate a resource and point it at the model:
+
+```bash
+rails generate madmin:resource Moderate::Report
+```
+
+Then wire the resolve/dismiss actions to `Moderate::Report#resolve!`/`#dismiss!` from a custom member action (full walkthrough in [`docs/madmin.md`](docs/madmin.md)). The same pattern works for `Moderate::Flag` and `Moderate::Appeal`.
+
+## 🔔 Notifications & 🧾 audit — one hook each
+
+`moderate` never sends an email or writes to *your* audit log directly. It **emits events** through two hooks you wire once — so notifications fan out wherever you want, and important actions are recorded however you want.
+
+```ruby
+Moderate.configure do |config|
+  # Called for every important action — wire it to your audit system (or leave it; it no-ops):
+  config.audit = ->(event) { AuditLog.record!(event_type: event.name, data: event.payload) }
+
+  # Called for every notifiable event — fan out to email / admin Telegram / push / in-app:
+  config.notify = ->(event) do
+    case event.name
+    when :report_received, :report_decision, :affected_user_decision
+      ModerationMailer.with(event:).public_send(event.name).deliver_later   # goodmail
+    when :content_flagged, :report_received
+      Telegrama.send_message("🚩 #{event.payload[:summary]}")               # admin alert
+    end
+  end
+
+  # Optional side effects when a block happens (e.g. tear down a pending invite):
+  config.on_block = ->(blocker:, blocked:, at:) { CancelPendingInvites.call(blocker, blocked, at: at) }
+end
+```
+
+Events carry a stable envelope (`event.name`, `event.subject`, `event.recipients`, `event.actor`, `event.payload`), so a single `notify` hook can drive **goodmail** (user emails), **telegrama** (admin alerts), and **noticed** (in-app feed + push) at once. Notify users via email/in-app **and** ping admins on Telegram from the same place. (Recipes in [`docs/notifications.md`](docs/notifications.md).)
+
+The full event vocabulary: `report_received`, `report_decision`, `affected_user_decision`, `appeal_received`, `appeal_decision`, `user_blocked`, `user_unblocked`, `user_banned`, `content_flagged`, `content_removed`.
+
+## ⚖️ DSA & app-store compliance, out of the box
+
+`moderate` is built around the rules so you don't have to read the regulation:
+
+- **DSA Art. 16 (notice & action):** a public, electronic notice form — a mountable engine you place at the path of your choosing (`mount Moderate::Engine => "/trust"`, no hardcoded `/legal`) — capturing the substantiated reason, exact URL, notifier name+email, good-faith statement, the EU **statement-of-reasons taxonomy**, and the member-state selector, with an automatic confirmation of receipt. A notice is a `Moderate::Report` with `intake_kind: "dsa"` (no separate model), built via `Moderate::Services::IntakeNotice`. The form prefills the reported-content fields from query params (editable) and a signed-in notifier's identity (locked), and auto-integrates [`rails_cloudflare_turnstile`](https://github.com/instrumentl/rails-cloudflare-turnstile) when present (falling back to a `config.notice_guard` proc, with an optional per-request skip hook for clients that cannot render a browser challenge). See [`docs/dsa-notice-form.md`](docs/dsa-notice-form.md).
+- **DSA Art. 17 (statement of reasons):** decision notices state the action, the legal/contractual ground, whether automated means were used, and the redress path.
+- **DSA Art. 20 (appeals):** a free, electronic internal complaint mechanism, open ≥ 6 months, decided by a human.
+- **DSA Art. 24 (transparency):** counters you can publish (notices received, actions taken, median handling time, appeal outcomes). The public transparency page is **opt-in** (`config.transparency_report_enabled = true`, off by default) — a live portal isn't itself required (the duty is to *publish* a report, and micro/small enterprises are exempt), so you turn it on only when you want it.
+- **Apple Guideline 1.2 & Google Play UGC:** filter-before-post, in-app report **and** block, ongoing moderation, published contact — `moderate` covers all four. See the mapped checklist in [`docs/compliance.md`](docs/compliance.md).
+
+> Two taxonomies, on purpose: an in-app **community report** category set (harassment, spam, …) and a separate, regulator-aligned **DSA legal-reason** taxonomy for public notices. `moderate` ships both. The community set is host-customizable via `config.report_categories`; the DSA legal-reason taxonomy is regulator-defined and fixed.
+
+## 🤓 Why the models?
+
+`rails generate moderate:install` creates four tables:
+
+- **`moderate_reports`** — a report/notice + an immutable evidence snapshot + decision metadata + the appeal window. Serves both in-app reports and public DSA notices (distinguished by `intake_kind`).
+- **`moderate_blocks`** — the bidirectional `blocker`/`blocked` edge, with a self-block check and the SSOT relation behind `Moderate.blocked_ids_for`.
+- **`moderate_flags`** — system/auto-filter flags (source: `text_filter` / `image_filter` / `external_classifier` / `manual`), with the classifier's labels + scores; the queue both human admins and ML consumers read via `pending`.
+- **`moderate_appeals`** — DSA Art. 20 internal complaints against a decision.
+
+> The value-list taxonomies (community `category`, `status`, `content_type`, the DSA `legal_reason`/`legal_country_code`, `resolution_basis`, plus `Flag` source/mode/status and `Appeal` source/status) are validated **in the models** — frozen constants + ActiveModel `inclusion` validations — **not** by database `CHECK` constraints. That means **adding or customizing a label never requires a migration**: the community category list is host-overridable via `config.report_categories` (defaults to `Moderate::Report::DEFAULT_CATEGORIES`), and the gem can grow its own taxonomies in a point release without touching your schema. The only value guard kept at the DB level is a cheap message-length backstop; everything else the migration adds is structural (NOT NULLs, FKs, the unique block edge, and the self-block CHECK).
+
+The migration is **adaptive**: it matches your app's primary-key type (UUID or bigint) and JSON column type (`jsonb` / `json`) automatically, so it drops cleanly into any Rails 7.1+ schema.
+
+## Configuration reference
+
+```ruby
+Moderate.configure do |config|
+  config.user_class        = "User"          # who reports/blocks/gets banned
+  config.default_filter_mode = :block        # :off / :block / :flag
+  config.filter_adapter    = :wordlist       # default text adapter
+
+  config.audit       = ->(event) { ... }     # optional; no-op by default
+  config.notify      = ->(event) { ... }     # optional; no-op by default
+  config.on_block    = ->(blocker:, blocked:, at:) { ... }   # optional
+  config.ban_handler = ->(user:, by:, reason:) { user.suspend! }   # how a "ban" is applied in your app
+
+  config.filter "Message", :body, with: :wordlist, mode: :flag
+end
+```
+
+Reportable classes are auto-discovered from the `has_reportable_content` macro (or `include Moderate::Reportable`) — no manual registry.
+
+## Upgrading from 0.x
+
+`moderate` 1.0 is a ground-up rewrite: the old gem was a profanity validator; 1.0 is a full Trust & Safety system. The one piece of the old API that remains is the validator, now backed by the `:wordlist` adapter:
+
+```ruby
+validates :body, moderate: true     # still works — equivalent to `moderates :body, mode: :block`
+```
+
+Everything else is new. There's no automated data migration (0.x stored nothing). See [`CHANGELOG.md`](CHANGELOG.md).
+
+## Testing
+
+We use Minitest. Run the suite (a dummy Rails app under `test/dummy`, against SQLite/PostgreSQL/MySQL via Appraisals):
+
+```bash
+bundle exec rake test
+```
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then run `rake test`. You can also run `bin/console` for an interactive prompt.
 
 To install this gem onto your local machine, run `bundle exec rake install`.