docs(plugin): frame MAJOR 2 as epoch sync, not blanket recompile (#1114)

Adversarial review: MAJOR_REVISION aligns with panel 2.0; existing
third-party .smx using prior SBPP APIs generally keep working. Narrow
rebuild guidance to checker library detection, new checker natives,
and optional post-admin forward adoption.

Author: rumblefrog

CHANGELOG.md

@@ -101,16 +101,15 @@ Legend:
         `AGENTS.md` (workflow / conventions) live alongside
         `README.md`; user-facing install / upgrade / configure
         guides moved to the Starlight site at sbpp.github.io
-36. ? SourceMod native API `MAJOR_REVISION` bumped to 2 in
-        `sourcebanspp.inc` (`MINOR_REVISION` reset to 0; plugin
-        release string `SB_VERSION` → 2.0.0). Third-party plugins
-        must recompile against this header. See also checker comms
-        natives ([#1032](https://github.com/sbpp/sourcebans-pp/pull/1032)),
-        checker library rename
-        ([#1034](https://github.com/sbpp/sourcebans-pp/pull/1034)),
-        and post-admin forward
-        ([#1431](https://github.com/sbpp/sourcebans-pp/pull/1431)).
-        ([#1114](https://github.com/sbpp/sourcebans-pp/issues/1114))
+36. • SourceMod native API epoch: `MAJOR_REVISION` 2 / `MINOR_REVISION` 0 in
+        `sourcebanspp.inc`; plugin `SB_VERSION` → 2.0.0 (panel 2.0 alignment).
+        New `SOURCEBANSPP_VERSION_MAJOR` for optional compile-time guards.
+        Third-party plugins need a rebuild only when they use checker library
+        detection (`"sourcechecker++"`, not `"sourcebans++"` — #1034), new
+        checker mute/gag natives (#1032), or hook
+        `SBPP_OnClientPostAdminCheck` (#1431). Plugins that only call
+        existing SBPP ban/report forwards/natives can usually keep their
+        existing `.smx`. ([#1114](https://github.com/sbpp/sourcebans-pp/issues/1114))
 ```
 
 ### Privacy

docs/src/content/docs/updating/1-8-to-2-0.mdx

@@ -252,37 +252,42 @@ hard-fail a panel page.
 
 ## Plugin authors
 
-If your server runs a **third-party SourceMod plugin** that
-`#include <sourcebanspp>` and calls SBPP natives or forwards, plan
-to **recompile** it against the `sourcebanspp.inc` shipped with
-SourceBans++ 2.0.0 before you deploy the new `.smx` files.
-
-The public header now exposes `SOURCEBANSPP_VERSION_MAJOR` (2 for
-this release). Guard your plugin at compile time:
+SourceBans++ 2.0.0 aligns the public header with the 2.0 release
+(`SOURCEBANSPP_VERSION_MAJOR` = 2, plugin `SB_VERSION` 2.0.0). That is a
+**version epoch marker**, not a signal that every third-party plugin must
+be recompiled.
+
+**You do not need to rebuild** if your plugin only uses APIs that already
+existed on the 1.x line (for example `SBPP_BanPlayer`, `SBPP_OnBanPlayer`,
+`SBPP_OnReportPlayer`) and you are not detecting the checker via
+`LibraryExists` / `GetFeatureStatus`.
+
+**Recompile (and redeploy your `.smx`) when you:**
+
+- `#include <sourcebanschecker>` and probe the checker with
+  `LibraryExists` / `GetFeatureStatus` — use library name
+  `"sourcechecker++"`, not `"sourcebans++"`
+  ([#1034](https://github.com/sbpp/sourcebans-pp/pull/1034)).
+- Call `SBPP_CheckerGetClientsMutes` or `SBPP_CheckerGetClientsGags`
+  ([#1032](https://github.com/sbpp/sourcebans-pp/pull/1032)) — deploy
+  `sbpp_checker.smx` from this release too.
+- Want to implement `SBPP_OnClientPostAdminCheck`
+  ([#1431](https://github.com/sbpp/sourcebans-pp/pull/1431)) — additive
+  forward; existing binaries ignore it until you add a hook.
+
+Optional guard when you compile against 2.0 `sourcebanspp.inc`:
 
 ```sourcepawn
 #if SOURCEBANSPP_VERSION_MAJOR != 2
-#error Recompile this plugin against SourceBans++ 2.0 sourcebanspp.inc
+#error Rebuild against SourceBans++ 2.0 sourcebanspp.inc
 #endif
 ```
 
-Changes since the 1.x native API that affect third-party code:
-
-- **`sourcebanspp.inc`** (library `"sourcebans++"`): new forward
-  `SBPP_OnClientPostAdminCheck` ([#1431](https://github.com/sbpp/sourcebans-pp/pull/1431)).
-- **`sourcebanschecker.inc`** (library `"sourcechecker++"` — renamed
-  from `"sourcebans++"` in
-  [#1034](https://github.com/sbpp/sourcebans-pp/pull/1034)): new
-  natives `SBPP_CheckerGetClientsMutes` and `SBPP_CheckerGetClientsGags`
-  ([#1032](https://github.com/sbpp/sourcebans-pp/pull/1032)).
-
-Ship the rebuilt `.smx` with the 2.0 plugin bundle
-(`sbpp_main.smx`, `sbpp_comms.smx`, `sbpp_checker.smx`, …). SourceMod
-**1.12.x** is the compiler floor the project CI uses (match your
-release build to the same toolchain).
+Deploy the official 2.0 plugin bundle (`sbpp_main.smx`, `sbpp_comms.smx`,
+`sbpp_checker.smx`, …) with the panel upgrade. SourceMod **1.12.x** matches
+project CI.
 
-Native API bump tracking:
-[#1114](https://github.com/sbpp/sourcebans-pp/issues/1114).
+Tracking: [#1114](https://github.com/sbpp/sourcebans-pp/issues/1114).
 
 ## Licence change
 

game/addons/sourcemod/scripting/include/sourcebanspp.inc

@@ -30,24 +30,33 @@
 #define _sourcebanspp_included
 
 // -------------------------------------------------------------------------
-// Native API revision (bump MAJOR when third-party plugins must recompile)
+// Native API revision (aligned with SourceBans++ 2.0 panel / plugin release)
 // -------------------------------------------------------------------------
 //
-// 2.0 native surface (this release):
-//   sourcebanspp.inc / library "sourcebans++"
-//     - Added forward SBPP_OnClientPostAdminCheck (#1431).
-//     - SBBanPlayer remains deprecated; use SBPP_BanPlayer.
+// MAJOR_REVISION tracks the documented native API epoch (2 = 2.0 line).
+// Bump MAJOR only when a change requires third-party plugins to recompile
+// (removed/changed native signatures, removed forwards). Bump MINOR for
+// additive natives/forwards that old .smx files can ignore at runtime.
 //
-//   sourcebanschecker.inc / library "sourcechecker++" (separate #include)
-//     - RegPluginLibrary name changed from "sourcebans++" to
-//       "sourcechecker++" (#1034) — update GetFeatureStatus / library checks.
-//     - Added natives SBPP_CheckerGetClientsMutes,
-//       SBPP_CheckerGetClientsGags (#1032).
+// 2.0 epoch (this header):
+//   sourcebanspp.inc — library "sourcebans++" (sbpp_main.smx)
+//     Additive: forward SBPP_OnClientPostAdminCheck (#1431).
+//     Unchanged: SBPP_BanPlayer; SBBanPlayer remains deprecated.
+//     Existing third-party .smx that only use prior natives/forwards
+//     generally keep working without a rebuild.
 //
-// Third-party plugins should compile against this header and guard at the top:
+//   sourcebanschecker.inc — RegPluginLibrary "sourcechecker++" (#1034)
+//     Recompile / update detection if you #include checker and use
+//     LibraryExists/GetFeatureStatus: was "sourcebans++", now
+//     "sourcechecker++". Additive natives: SBPP_CheckerGetClientsMutes,
+//     SBPP_CheckerGetClientsGags (#1032); require sbpp_checker.smx that
+//     implements them if you call those natives.
+//
+// Optional compile-time guard (add to your plugin if you ship against
+// this header and want a hard fail when the epoch drifts):
 //
 //   #if SOURCEBANSPP_VERSION_MAJOR != 2
-//   #error Recompile this plugin against SourceBans++ 2.0 sourcebanspp.inc
+//   #error Rebuild against SourceBans++ 2.0 sourcebanspp.inc
 //   #endif
 //
 // -------------------------------------------------------------------------