Tuning Guide

Every check's envelope is deliberately generous out of the box: prefer a smaller set of explainable, tested checks over many aggressive checks that create false positives. Tune down only after confirming false positives are actually gone on your own hardware/TPS/player base — start with observe-only still effectively true (leave enforcement off) while you do.

• response-ceiling (every check in checks.yml, one of NONE < STORE < NOTIFY < MONITOR < CANCEL < SETBACK < KICK < COMMAND): the strongest response that check's own findings may ever justify, regardless of actions.yml. A check shipped with ceiling NOTIFY can never kick a player no matter what policy rule you write.
• actions.yml policies: declarative rules (check, min-evidence-class, min-escalation-stage, response) that can escalate a finding's response up to (never past) its check's ceiling. None ship enabled by default — permanent punishment is always an explicit opt-in.
• actions.yml correlation rules: match independent evidence families within a short window (e.g. a sustained item-generation-rate finding plus a confirmed inventory-conservation mismatch, or a killaura-class combat finding plus an auto-totem-macro finding — combo-hack-signature) and can justify a stronger ceiling than any single contributing check — this is how FlagForge turns "several individually-weak signals" into one confident incident instead of either ignoring them or overreacting to one alone. A correlation's response-ceiling need not be punitive: suspected-dupe-backup-trigger uses COMMAND purely to fire an admin-configured console command — e.g. a backup plugin's snapshot command — on evidence far weaker than any actual CANCEL/KICK would require, since a snapshot is cheap and non-destructive. See Triggering a backup on suspected dupe evidence below.
• Movement/combat/world safety margins and buffers (checks.yml, e.g. movement.speed.a's safety-margin/buffer.flag-at/buffer.decay-per-valid-sample, combat.reach.a's equivalents): a buffer must cross flag-at before a finding fires at all (never a single marginal sample), then decays back down on clean samples. Raising safety-margin or flag-at makes a check strictly more lenient; lowering either makes it strictly stricter. Quality gates (min-tps/max-ping-ms in checks.yml's defaults, or per-check) reduce confidence automatically during lag — you generally don't need to touch these unless your server runs sustained low TPS.
• Packet-adapter checks (movement.timer.a, packet.rate.a, packet.sequence.a): only meaningful with PacketEvents installed; their threshold values are packets/second ceilings.

Triggering a backup on suspected dupe evidence

FlagForge does not implement backup or rollback itself — that's an explicit non-goal, and the plugin is designed to integrate with whatever backup tooling you already run, not replace it. actions.yml's suspected-dupe-backup-trigger correlation rule is the integration point: it matches the same evidence-family combination as confirmed-inventory-generation (a sustained item-generation-rate finding plus an inventory-conservation mismatch), but at much lower confidence thresholds, since firing a cheap, non-destructive snapshot is reasonable on far weaker evidence than an actual CANCEL/KICK would justify.

It ships fully inert on every install via two independent gates: the global enforcement switch/observe-only mode (like every other COMMAND-class rule in actions.yml), and having no command: configured at all. To opt in, set command: to your backup plugin's manual-snapshot console command, or the vanilla fallback:

suspected-dupe-backup-trigger:
  # ...
  command: "save-all"

The two dupe-related correlations intentionally sit at different confidence bars because of checks.yml's coverage-complete flag on inventory.reconciliation.a: with the shipped default (coverage-complete: false), that check's confidence tops out around 0.6 (HEURISTIC evidence), so confirmed-inventory-generation's 0.90 bar realistically requires coverage-complete: true (and verified full adapter coverage) to ever match, while suspected-dupe-backup-trigger's 0.55 bar is reachable on a default install. Run /ff correlations to see every configured correlation rule's thresholds and whether a rule's confidence requirement is currently unreachable given your coverage-complete setting.