Flag content as inappropriate #189

Summary

As a visitor or contributor, I want to flag content on a device page as inappropriate or wrong, so that faulty, infringing or abusive contributions can be taken down quickly by the community, without OHF reviewing or monitoring edits.

This is the reporting flow referenced by #74 (easy reporting of faulty or malicious content), #185 and #188. It is the safety net that makes automated, trust-based moderation acceptable: proposals merge without a gatekeeper because anyone can raise a flag afterwards, and anyone can act on it.

Principle: trust in the community, not in OHF moderation

The Device Database is built with and for the community. OHF relies on the community and puts trust in our joint process: contributions merge through automated rules and community votes, and flagged content is handled the same way.

OHF does not have the capacity to monitor flagged content, and does not intend to build that capacity. There is no OHF moderation queue. Flags are made public, and everyone interested can see them and act on them: vote to remove, propose a correction, or object. This feature exists to reduce moderation overhead, not to create a new kind of it. Every design choice below should be read against that: if something would require a person at OHF to watch a queue, it is the wrong choice.

OHF keeps one obligation it cannot delegate: a legal takedown contact for rights holders and personal-data cases, defined in the legal track (#35). Even there, the technical path is the same community process, only triggered with higher priority.

Scope

What can be flagged

• Any curated field on a device page (picture, model, model ID, category, brand, and later fields), on live content and on pending proposals
• Not the reported core from Home Assistant; disagreements with reported data go to a separate "report data issue" path, out of scope here

Who can flag

• Signed-in contributors (Account 0.1) with one click plus a reason
• Proposal: signed-out visitors as well, with basic abuse protection (rate limit per IP, simple challenge), since rights holders and casual visitors should not need an account to raise a concern

Reasons (fixed list, one required, free text optional)

• Wrong or misleading information
• Copyright or licence concern
• Contains personal data (faces, serial numbers, credentials on labels)
• Inappropriate or offensive content
• Spam or vandalism
• Other (free text required)

What happens to a flag (fully automated)

1. The flag is recorded against the specific field and version, so a later legitimate edit does not inherit it
2. For live content: the bot opens a revert proposal (previous value or empty) in the data repository, labelled with the reason and linked to the flag. It follows the short-window rule from the moderation rules: it merges after a short period unless the community objects, so removal needs no OHF action
3. For pending proposals: the flag adds a labelled opposing signal to the PR; above a threshold the bot applies a "needs community attention" label
4. Copyright and personal-data flags get a priority path: the content is hidden from the public page immediately and shown as "under review" until the revert proposal resolves. This limits legal exposure without anyone at OHF having to react
5. The flagger sees at submit time what will happen and where to follow it (the PR link); notifications are a follow-up increment
6. Resolution is recorded in the device changelog, attributed to the bot and the deciding votes

Public flag channel

Flags only work if people see them. Instead of an internal overview, all flags are published where interested community members already are:

• A GitHub label and saved view in the data repository ("flagged", by reason), which is the canonical list
• The same feed mirrored by the bot into a public Discord channel (e.g. #device-database-flags) and exposed as RSS or Atom, so anyone can subscribe without a GitHub account
• Each entry links to the PR where voting and discussion happen; the channel is for awareness, not for a second discussion thread
• Community members who want to help keep the database healthy can subscribe and act; nobody is assigned

Abuse protection (automated)

• Rate limits per account and per IP; duplicate flags on the same field version are counted, not re-processed
• Repeated bad-faith flagging by an account leads to automatic throttling, and blocking through the Account 0.1 block / unblock mechanism, driven by community votes on the bot's proposals rather than by OHF review
• Flag details beyond the PR are not public, to avoid pile-ons on individual contributors

Acceptance criteria

• A flag control is available on every curated field of a device page, for live content and pending proposals
• Flagging requires a reason from the fixed list; free text is optional except for "Other"
• A flag on live content results in a bot-created revert proposal under the short-window rule within minutes, with no manual step
• A flag on a pending proposal is visible on the PR as an opposing signal with a label
• Copyright and personal-data flags hide the content from the public page immediately and show an "under review" state, without manual intervention
• Every flag appears in the public flag channel (GitHub label view, Discord mirror, feed) within minutes, linking to its PR
• Flags are tied to a field version; a subsequent different edit is not flagged by inheritance
• Rate limits and duplicate handling prevent a single actor from spamming flags
• No step in the flow requires an OHF team member to look at a queue
• Signed-out flagging is enabled or disabled by a single configuration switch pending the decision

Not in scope

• Any OHF-side moderation dashboard, queue or review role
• Reporting problems with reported (Home Assistant analytics) data; separate path
• Notifications to flaggers or contributors (increment from Stage 3: Accounts and editing #152)
• Automated content screening before publication (covered for pictures in Picture contribution with checks #188)
• Appeals process for blocked accounts (Account 0.1 follow-up)
• The legal takedown contact and process itself (Launch readiness for the public Device Database (public information, communication, Preview/Labs exit) #35); this feature only provides the technical path it triggers

Dependencies

• Account 0.1 for signed-in flagging and blocking
• Moderation bot and per-trait rules: short-window removal rule, labels, thresholds, auto-throttling
• Data repository structure: field versioning so flags can target a version
• Pending-edits display and changelog on the device page
• Discord bot or webhook for the public channel mirror
• Legal: takedown contact and wording for the "under review" state (Launch readiness for the public Device Database (public information, communication, Preview/Labs exit) #35)

Open questions

• Anonymous flagging: allow with abuse protection, or require sign-in for the first iteration?
• Threshold for "needs community attention" on pending proposals: one flag, or n flags from distinct accounts?
• Immediate hiding on copyright and personal-data flags can be abused (hide a competitor's picture). Accept the trade-off because the revert proposal is public and fast to object to, or require two distinct flags before hiding?
• Does a revert proposal restore the previous value or clear the field? Depends on whether the previous value was itself contributed or reported
• Which public channels beyond GitHub are worth mirroring to at launch (Discord only, or also the community forum)?
• What happens when a flagged item gets no community reaction at all: the short-window default merges the removal, which is the safe direction; confirm that this is acceptable for "wrong or misleading" flags too, or scope the auto-merge to the legal categories