docs(settings): clarify moderationGateMode gates only the shared violation tally

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",

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(),

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.