From d80bf7e070596fe1de884563af468605aba8feb6 Mon Sep 17 00:00:00 2001
From: JSONbored <49853598+JSONbored@users.noreply.github.com>
Date: Sun, 12 Jul 2026 06:42:23 -0700
Subject: [PATCH] docs(settings): clarify moderationGateMode gates only the
 shared violation tally

The field's JSDoc said "whether the whole layer runs on THIS repo" --
read in isolation this implies "off" disables the anti-abuse system.
It does not: the four enforcement mechanisms (contributor-cap close,
blacklist close, review-nag cooldown, review-evasion close) each
read only their own independent setting and never check this field.
Its one real call site runs only after enforcement already completed
-- it gates only the shared cross-repo violation tally + warning/
banned label + auto-blacklist-at-threshold.

moderation-rules.ts's own file header and .gittensory.yml.example
already describe this scope correctly; reworded the types.ts JSDoc to
match, and added the same caveat to the openapi occurrence.

Docs-only, no behavior change. Regenerated openapi.json.

Refs #5289
---
 apps/gittensory-ui/public/openapi.json |  3 ++-
 src/openapi/schemas.ts                 |  7 ++++++-
 src/types.ts                           | 12 ++++++++----
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/apps/gittensory-ui/public/openapi.json b/apps/gittensory-ui/public/openapi.json
index a9eb9eb9d..137695611 100644
--- a/apps/gittensory-ui/public/openapi.json
+++ b/apps/gittensory-ui/public/openapi.json
@@ -9535,7 +9535,8 @@
               "inherit",
               "off",
               "enabled"
-            ]
+            ],
+            "description": "Gates ONLY the shared cross-repo violation tally -- does NOT disable the four underlying anti-abuse mechanisms (contributor cap, blacklist, review-nag, review-evasion), each of which runs on its own independent setting."
           },
           "moderationRules": {
             "type": "array",
diff --git a/src/openapi/schemas.ts b/src/openapi/schemas.ts
index e92af604c..776cf3122 100644
--- a/src/openapi/schemas.ts
+++ b/src/openapi/schemas.ts
@@ -828,7 +828,12 @@ export const RepositorySettingsSchema = z
     commandRateLimitMaxPerWindow: z.number().int().positive().optional(),
     commandRateLimitAiMaxPerWindow: z.number().int().positive().optional(),
     commandRateLimitWindowHours: z.number().int().positive().optional(),
-    moderationGateMode: z.enum(["inherit", "off", "enabled"]).optional(),
+    moderationGateMode: z
+      .enum(["inherit", "off", "enabled"])
+      .optional()
+      .describe(
+        "Gates ONLY the shared cross-repo violation tally -- does NOT disable the four underlying anti-abuse mechanisms (contributor cap, blacklist, review-nag, review-evasion), each of which runs on its own independent setting.",
+      ),
     moderationRules: z.array(z.enum(["contributor_cap", "blacklist", "review_nag", "review_evasion"])).optional(),
     moderationWarningLabel: z.string().optional(),
     moderationBannedLabel: z.string().optional(),
diff --git a/src/types.ts b/src/types.ts
index 85dca132d..e292cd80b 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -1105,10 +1105,14 @@ export type RepositorySettings = {
    *  without lifting the fleet-wide brake. Never overrides the `AGENT_ACTIONS_PAUSED` env var, and
    *  {@link agentPaused} on this same repo still wins over it. Default false. */
   agentGlobalFreezeOverride?: boolean | undefined;
-  /** Moderation-rules engine (#selfhost-mod-engine): whether the whole layer runs on THIS repo. `"inherit"`
-   *  (the DB default) defers to `global_moderation_config.enabled`; `"off"`/`"enabled"` force this repo
-   *  regardless of the global default. Always populated by the DB layer; optional so existing settings
-   *  fixtures/callers need not be touched. */
+  /** Moderation-rules engine (#selfhost-mod-engine): gates ONLY the single shared, cross-repo violation
+   *  tally across the anti-abuse mechanisms that already short-circuit a PR/issue's disposition on their
+   *  own independent settings (contributor cap, blacklist, review-nag, review-evasion) -- it does NOT
+   *  disable those four mechanisms themselves, which run regardless of this field. `"inherit"` (the DB
+   *  default) defers to `global_moderation_config.enabled`; `"off"`/`"enabled"` force this repo's
+   *  participation in the tally, opting it in/out and narrowing which mechanisms feed it, regardless of
+   *  the global default. Always populated by the DB layer; optional so existing settings fixtures/callers
+   *  need not be touched. */
   moderationGateMode?: "inherit" | "off" | "enabled" | undefined;
   /** Moderation-rules engine: a per-repo override of WHICH of the anti-abuse mechanisms (contributor cap,
    *  blacklist, review-nag, review-evasion) feed a contributor's shared, cross-repo violation tally.