From 9e392277ef91c8a6d6c3c13e1180c6929e3d4633 Mon Sep 17 00:00:00 2001
From: JSONbored <49853598+JSONbored@users.noreply.github.com>
Date: Sun, 12 Jul 2026 06:49:55 -0700
Subject: [PATCH] docs(settings): document that autoLabelEnabled only gates the
 base context label

autoLabelEnabled had no doc comment and reads like a master label
switch. Its only real consumer gates exclusively the single base
gittensorLabel context label -- zero effect on TYPE/taxonomy labels
(typeLabelsEnabled), moderation/blacklist labels, or review-state
labels. This scoping was already documented on the sibling
typeLabelsEnabled field and in the yml example, but not on
autoLabelEnabled itself, and the dashboard toggle rendered as plain
"Auto-label PRs" with no scoping hint -- the most likely place a
real maintainer would be misled.

Added a doc comment mirroring the existing cross-reference style,
and a hint on the dashboard toggle.

Docs-only, no behavior change.

Refs #5293
---
 .../src/components/site/app-panels/maintainer-settings.tsx    | 1 +
 src/types.ts                                                  | 4 ++++
 2 files changed, 5 insertions(+)

diff --git a/apps/gittensory-ui/src/components/site/app-panels/maintainer-settings.tsx b/apps/gittensory-ui/src/components/site/app-panels/maintainer-settings.tsx
index 00f24589f8..dc91833ea9 100644
--- a/apps/gittensory-ui/src/components/site/app-panels/maintainer-settings.tsx
+++ b/apps/gittensory-ui/src/components/site/app-panels/maintainer-settings.tsx
@@ -422,6 +422,7 @@ export function MaintainerSettings({ reviewability }: { reviewability: Array<{ p
             <div className="mt-2 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
               <ToggleControl
                 label="Auto-label PRs"
+                hint="Only the base context label below — type labels have their own toggle"
                 value={settings.autoLabelEnabled}
                 onChange={(v) => setField("autoLabelEnabled", v)}
               />
diff --git a/src/types.ts b/src/types.ts
index 4ed89ad4ae..db85ec3a2b 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -909,6 +909,10 @@ export type RepositorySettings = {
    *  PRs are exempt from auto-close (merge or manual-hold only). Per-repo configurable so maintainers choose
    *  rather than inheriting a hardwired opinion. */
   closeOwnerAuthors: boolean;
+  /** #label-decoupling: gates ONLY the base {@link gittensorLabel} context label (`shouldApplyPrLabel`/
+   *  `willLabel` in `signals/settings-preview.ts`) -- zero effect on TYPE/taxonomy labels
+   *  ({@link typeLabelsEnabled}), moderation/blacklist labels, or review-state labels. Four independent
+   *  label families exist; none of them gates or silently disables another. */
   autoLabelEnabled: boolean;
   gittensorLabel: string;
   createMissingLabel: boolean;