@mrclrchtr/supi-debug 2.0.6 → 2.2.0

package/node_modules/@mrclrchtr/supi-core/src/settings/settings-ui.ts

@@ -1,327 +1,114 @@
-// Generic settings overlay for SuPi extensions.
+// Declarative settings overlay for SuPi extensions.
 //
-// Uses pi-tui's SettingsList with scope toggle (Tab), extension grouping,
-// and search. Each extension declares its settings via registerSettings().
+// Thin orchestration layer that collects settings contributions and opens the
+// scoped settings list inside a pi-tui custom component overlay.
 
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container, Key, matchesKey, Text } from "@earendil-works/pi-tui";
+import { ScopedSettingsList } from "./scoped-settings-list.ts";
+import type { SettingsCollectionDiagnostic, SettingsScope } from "./settings-registry.ts";
 import {
-  Container,
-  Input,
-  Key,
-  matchesKey,
-  type SelectItem,
-  SelectList,
-  type SelectListTheme,
-  type SettingItem,
-  SettingsList,
-  Text,
-} from "@earendil-works/pi-tui";
-import { getSelectableModels } from "../model-selection.ts";
-import {
-  getRegisteredSettings,
-  type SettingsScope,
-  type SettingsSection,
+  createSettingsContributionCollector,
+  SUPI_SETTINGS_COLLECT_EVENT,
 } from "./settings-registry.ts";
 
-// ── Input submenu component ──────────────────────────────────
+// Re-export submenu helpers
+export { createInputSubmenu, createModelPickerSubmenu } from "./settings-submenus.ts";
 
-/**
- * Creates a pi-tui Input-backed submenu component with enter-to-confirm
- * and escape-to-cancel handling.
- *
- * @param currentValue - Initial value for the text input.
- * @param label - Label text displayed above the input.
- * @param done - Callback invoked with the confirmed value, or undefined on cancel.
- */
-export function createInputSubmenu(
-  currentValue: string,
-  label: string,
-  done: (selectedValue?: string) => void,
-): {
-  render: (width: number) => string[];
-  invalidate: () => void;
-  handleInput: (data: string) => boolean;
-} {
-  const input = new Input();
-  input.setValue(currentValue);
+// ── Overlay ────────────────────────────────────────────────────────────────
 
-  return {
-    render: (_width: number) => {
-      const lines = [`  ${label}`];
-      lines.push(...input.render(_width));
-      lines.push("  enter confirm • esc cancel");
-      return lines;
-    },
-    invalidate: () => {
-      input.invalidate();
-    },
-    handleInput: (data: string) => {
-      if (matchesKey(data, Key.escape)) {
-        done();
-        return true;
-      }
-      if (matchesKey(data, Key.enter)) {
-        done(input.getValue());
-        return true;
-      }
-      input.handleInput(data);
-      return true;
-    },
-  };
+interface OverlayStatus {
+  kind: "warning" | "error";
+  message: string;
 }
 
-// ── Types ────────────────────────────────────────────────────
-
 interface OverlayState {
   scope: SettingsScope;
   cwd: string;
+  status?: OverlayStatus;
 }
 
-// ── Pure helpers ─────────────────────────────────────────────
-
 function getScopeLabel(scope: SettingsScope): string {
   return scope === "project" ? "Project" : "Global";
 }
 
-function buildFlatItems(
-  sections: SettingsSection[],
-  scope: SettingsScope,
-  cwd: string,
-  ctx?: ExtensionContext,
-): SettingItem[] {
-  const items: SettingItem[] = [];
-  for (const section of sections) {
-    const sectionItems = section.loadValues(scope, cwd, ctx);
-    for (const item of sectionItems) {
-      items.push({
-        ...item,
-        id: `${section.id}.${item.id}`,
-        label: `${section.label}: ${item.label}`,
-      });
-    }
-  }
-  return items;
-}
-
-function findSectionAndId(
-  sections: SettingsSection[],
-  flatId: string,
-): { section: SettingsSection; itemId: string } | null {
-  const dotIndex = flatId.indexOf(".");
-  if (dotIndex === -1) return null;
-  const sectionId = flatId.slice(0, dotIndex);
-  const itemId = flatId.slice(dotIndex + 1);
-  const section = sections.find((s) => s.id === sectionId);
-  if (!section) return null;
-  return { section, itemId };
-}
-
-// ── Component ────────────────────────────────────────────────
-
-interface SettingsOverlayDeps {
-  ctx: ExtensionContext;
-  state: OverlayState;
-  container: Container;
-  settingsList: SettingsList | null;
-  tui: Parameters<Parameters<ExtensionContext["ui"]["custom"]>[0]>[0];
-  theme: Parameters<Parameters<ExtensionContext["ui"]["custom"]>[0]>[1];
-  done: () => void;
-}
-
-function createSettingsList(deps: SettingsOverlayDeps): SettingsList {
-  const sections = getRegisteredSettings();
-  const items = buildFlatItems(sections, deps.state.scope, deps.state.cwd, deps.ctx);
-  const onChange = (flatId: string, newValue: string) => {
-    const found = findSectionAndId(sections, flatId);
-    if (found) {
-      found.section.persistChange(
-        deps.state.scope,
-        deps.state.cwd,
-        found.itemId,
-        newValue,
-        deps.ctx,
-      );
-    }
-    // Re-read all values to reflect persisted changes, but keep the list
-    // instance (and its selectedIndex) intact.
-    const updatedItems = buildFlatItems(sections, deps.state.scope, deps.state.cwd, deps.ctx);
-    for (const updated of updatedItems) {
-      const existing = items.find((i) => i.id === updated.id);
-      if (existing && existing.currentValue !== updated.currentValue) {
-        settingsList.updateValue(updated.id, updated.currentValue);
-      }
-    }
-    deps.tui.requestRender();
-  };
-  const settingsList = new SettingsList(
-    items,
-    Math.min(items.length + 4, 20),
-    getSettingsListTheme(),
-    onChange,
-    () => deps.done(),
-    { enableSearch: true },
-  );
-  return settingsList;
-}
-
-function rebuildSettingsList(deps: SettingsOverlayDeps): SettingsList {
-  const settingsList = createSettingsList(deps);
-  deps.settingsList = settingsList;
-
-  deps.container.clear();
-  deps.container.addChild(createHeaderComponent(deps));
-  deps.container.addChild(settingsList);
-
-  return settingsList;
-}
-
-function createHeaderComponent(deps: SettingsOverlayDeps): Text {
-  const { theme, state } = deps;
-  const scopeLabel = getScopeLabel(state.scope);
-  const otherScope = state.scope === "project" ? "Global" : "Project";
-  const headerText = new Text(
-    `${theme.fg("accent", theme.bold("SuPi Settings"))}  ${theme.fg("text", `Scope: ${scopeLabel}`)} ${theme.fg("dim", `(tab → ${otherScope})`)}`,
-    0,
-    0,
-  );
-  return headerText;
-}
-
-function handleScopeToggle(deps: SettingsOverlayDeps): void {
-  deps.state.scope = deps.state.scope === "project" ? "global" : "project";
-  rebuildSettingsList(deps);
-  deps.tui.requestRender();
-}
-
-/** Minimal SelectList theme — uses identity so the parent SettingsList provides styling context. */
-const PASSTHROUGH_THEME: SelectListTheme = {
-  selectedPrefix: (text) => `› ${text}`,
-  selectedText: (text) => text,
-  description: (text) => text,
-  scrollInfo: (text) => text,
-  noMatch: (text) => text,
-};
-
-/**
- * Create a model picker submenu for settings.
- *
- * Shows a scrollable list of selectable models from the scoped model set,
- * with the current session model annotated `[current]`.  The first entry is
- * always `"disabled"`.
- *
- * @param currentValue - Currently configured canonical model id or `"disabled"`.
- * @param done - Callback invoked with the selected value, or undefined on cancel.
- * @param ctx - Extension context for model listing.  When undefined, only
- *   `"disabled"` is offered.
- */
-export function createModelPickerSubmenu(
-  currentValue: string,
-  done: (selectedValue?: string) => void,
-  ctx?: ExtensionContext,
-): {
-  render: (width: number) => string[];
-  invalidate: () => void;
-  handleInput: (data: string) => boolean;
-} {
-  const items = buildModelItems(ctx);
-
-  const initialIndex =
-    currentValue === "disabled"
-      ? 0
-      : Math.max(
-          0,
-          items.findIndex((item) => item.value === currentValue),
-        );
-
-  const container = new Container();
-  container.addChild(new Text("  Select suggestion model", 1, 0));
-  container.addChild(new Text("", 1, 0));
-
-  const selectList = new SelectList(items, Math.min(items.length, 15), PASSTHROUGH_THEME);
-
-  if (initialIndex >= 0) {
-    selectList.setSelectedIndex(initialIndex);
-  }
-
-  selectList.onSelect = (item) => done(item.value);
-  selectList.onCancel = () => done();
-
-  container.addChild(selectList);
-  container.addChild(new Text("  ↑↓ navigate • enter select • esc cancel", 1, 0));
-
-  return {
-    render: (width: number) => container.render(width),
-    invalidate: () => container.invalidate(),
-    handleInput: (data: string) => {
-      selectList.handleInput(data);
-      return true;
-    },
-  };
+function collectSettingsSections(pi: ExtensionAPI) {
+  const collector = createSettingsContributionCollector();
+  pi.events.emit(SUPI_SETTINGS_COLLECT_EVENT, collector);
+  return collector.result();
 }
 
-/** Build selectable model items with "disabled" first. */
-function buildModelItems(ctx?: ExtensionContext): SelectItem[] {
-  const items: SelectItem[] = [
-    {
-      value: "disabled",
-      label: "disabled",
-      description: "No prompt suggestions",
-    },
-  ];
-
-  if (!ctx) return items;
-
-  const models = getSelectableModels(ctx);
-
-  for (const model of models) {
-    const suffix = model.isCurrent ? "  [current]" : "";
-    items.push({
-      value: model.canonicalId,
-      label: `${model.canonicalId}${suffix}`,
-      description: model.label !== model.canonicalId ? model.label : undefined,
-    });
-  }
-
-  return items;
+function latestStatus(diagnostics: SettingsCollectionDiagnostic[]): OverlayStatus | undefined {
+  const latest = diagnostics.at(-1);
+  return latest ? { kind: latest.kind, message: latest.message } : undefined;
 }
 
-// ── Entry point ──────────────────────────────────────────────
-
-export function openSettingsOverlay(ctx: ExtensionContext): void {
-  const sections = getRegisteredSettings();
-  if (sections.length === 0) {
+export function openSettingsOverlay(pi: ExtensionAPI, ctx: ExtensionContext): void {
+  const collection = collectSettingsSections(pi);
+  if (collection.sections.length === 0) {
     ctx.ui.notify("No settings registered by SuPi extensions", "info");
     return;
   }
 
   void ctx.ui.custom<void>((tui, theme, _kb, done) => {
-    const state: OverlayState = { scope: "project", cwd: ctx.cwd };
-    const container = new Container();
+    const state: OverlayState = {
+      scope: "project",
+      cwd: ctx.cwd,
+      status: latestStatus(collection.diagnostics),
+    };
 
-    const deps: SettingsOverlayDeps = {
+    const container = new Container();
+    const scopedList = new ScopedSettingsList(
+      collection.sections,
+      state.scope,
+      state.cwd,
       ctx,
-      state,
-      container,
-      settingsList: null,
-      tui,
       theme,
+      tui,
       done,
+      (message) => {
+        state.status = { kind: "error", message };
+        rebuildOverlay();
+        tui.requestRender();
+      },
+    );
+    scopedList.enableSearch();
+
+    const rebuildOverlay = () => {
+      container.clear();
+      const scopeLabel = getScopeLabel(state.scope);
+      const otherScope = state.scope === "project" ? "Global" : "Project";
+      container.addChild(
+        new Text(
+          `${theme.fg("accent", theme.bold("SuPi Settings"))}  ${theme.fg("text", `Scope: ${scopeLabel}`)} ${theme.fg("dim", `(tab → ${otherScope})`)}`,
+          0,
+          0,
+        ),
+      );
+      if (state.status) {
+        container.addChild(new Text(theme.fg(state.status.kind, state.status.message), 0, 0));
+      }
     };
 
-    rebuildSettingsList(deps);
+    rebuildOverlay();
 
     const component = {
-      render: (width: number) => container.render(width),
-      invalidate: () => container.invalidate(),
+      render: (width: number) => [...container.render(width), ...scopedList.render(width)],
+      invalidate: () => {
+        container.invalidate();
+        scopedList.invalidate();
+      },
       handleInput: (data: string) => {
         if (matchesKey(data, Key.tab)) {
-          handleScopeToggle(deps);
+          state.scope = state.scope === "project" ? "global" : "project";
+          state.status = undefined;
+          scopedList.reload(state.scope, state.cwd, ctx);
+          rebuildOverlay();
+          tui.requestRender();
           return true;
         }
-        // Delegate input to the settings list (always set after rebuildSettingsList)
-        deps.settingsList?.handleInput?.(data);
-        deps.tui.requestRender();
+        scopedList.handleInput(data);
+        tui.requestRender();
         return true;
       },
     };

package/node_modules/@mrclrchtr/supi-core/src/settings-ui.ts

@@ -1,6 +1,3 @@
 // supi-core settings-ui domain — settings TUI components (imports pi-tui at runtime, heavy).
-export {
-  createInputSubmenu,
-  createModelPickerSubmenu,
-  openSettingsOverlay,
-} from "./settings/settings-ui.ts";
+export { createInputSubmenu, createModelPickerSubmenu } from "./settings/settings-submenus.ts";
+export { openSettingsOverlay } from "./settings/settings-ui.ts";

package/node_modules/@mrclrchtr/supi-core/src/settings.ts

@@ -1,9 +1,31 @@
-// supi-core settings domain — settings registry (lightweight, type-only pi-tui import).
+// supi-core settings domain — event-backed declarative settings contributions and command wiring.
 
 export { registerSettingsCommand } from "./settings/settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
+export type {
+  SettingsCollectionDiagnostic,
+  SettingsCollectionResult,
+  SettingsContributionCollector,
+  SettingsScope,
+  SettingsSection,
+} from "./settings/settings-registry.ts";
 export {
-  clearRegisteredSettings,
-  getRegisteredSettings,
-  registerSettings,
+  createSettingsContributionCollector,
+  isSettingsContributionCollector,
+  SUPI_SETTINGS_COLLECT_EVENT,
 } from "./settings/settings-registry.ts";
+export type {
+  BoolField,
+  ConfigHelpers,
+  CustomField,
+  DeclarativeSettingsOptions,
+  EnumField,
+  ModelPickerField,
+  NumberField,
+  ScopedFieldValue,
+  SettingsField,
+  SettingsFieldAction,
+  SettingsPersistedChange,
+  StringListField,
+  ValueSource,
+} from "./settings/settings-schema.ts";
+export { registerDeclarativeSettings } from "./settings/settings-schema.ts";

package/node_modules/@mrclrchtr/supi-core/src/tool-framework.ts

@@ -53,6 +53,16 @@ export function derivePromptSurface(spec: SuiPiToolSpec): SuiPiToolPromptSurface
   };
 }
 
+// Re-export prompt-surface types (implemented in config/prompt-surface.ts)
+export {
+  notifyToolPromptSurfaceDiagnostics,
+  type ResolveToolPromptSurfaceOptions,
+  type ResolveToolPromptSurfaceResult,
+  resolveToolPromptSurface,
+  type ToolPromptSurfaceDiagnostic,
+  type ToolPromptSurfaceDiagnosticCode,
+} from "./config/prompt-surface.ts";
+
 // ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-debug",
-  "version": "2.0.6",
+  "version": "2.2.0",
   "description": "SuPi Debug extension — shared debug event inspection for SuPi extensions",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "2.0.6"
+    "@mrclrchtr/supi-core": "2.2.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/debug.ts

@@ -7,7 +7,7 @@ import {
   type TruncationResult,
   truncateHead,
 } from "@earendil-works/pi-coding-agent";
-import { loadSupiConfig, registerConfigSettings } from "@mrclrchtr/supi-core/config";
+import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
 import { registerContextProvider } from "@mrclrchtr/supi-core/context";
 import {
   clearDebugEvents,
@@ -17,10 +17,10 @@ import {
   type DebugEventQuery,
   type DebugEventView,
   type DebugLevel,
-  type DebugNotifyLevel,
   getDebugEvents,
   getDebugSummary,
 } from "@mrclrchtr/supi-core/debug";
+import { registerDeclarativeSettings } from "@mrclrchtr/supi-core/settings";
 import { Type } from "typebox";
 import { formatDataLines } from "./format.ts";
 import { registerDebugMessageRenderer } from "./renderer.ts";
@@ -30,11 +30,10 @@ import { promptGuidelines, promptSnippet, toolDescription } from "./tool/guidanc
 const DEBUG_SECTION = "debug";
 const DEBUG_REPORT_TYPE = "supi-debug-report";
 
-interface DebugConfig {
+interface DebugConfig extends Record<string, unknown> {
   enabled: boolean;
   agentAccess: DebugAgentAccess;
   maxEvents: number;
-  notifyLevel: DebugNotifyLevel;
 }
 
 const DEBUG_DEFAULTS: DebugConfig = { ...DEBUG_REGISTRY_DEFAULTS };
@@ -45,10 +44,6 @@ function normalizeAgentAccess(value: string): DebugAgentAccess {
   return value === "off" || value === "raw" ? value : "sanitized";
 }
 
-function normalizeNotifyLevel(value: string): DebugNotifyLevel {
-  return value === "warning" || value === "error" ? value : "off";
-}
-
 function normalizeMaxEvents(value: string | number): number {
   const parsed = typeof value === "number" ? value : Number.parseInt(value, 10);
   return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : DEBUG_DEFAULTS.maxEvents;
@@ -92,7 +87,6 @@ function loadDebugConfig(cwd: string): DebugConfig {
     enabled: normalizeEnabled(config.enabled),
     agentAccess: normalizeAgentAccess(String(config.agentAccess)),
     maxEvents: normalizeMaxEvents(config.maxEvents),
-    notifyLevel: normalizeNotifyLevel(String(config.notifyLevel)),
   };
 }
 
@@ -110,54 +104,35 @@ function syncLiveDebugRegistry(cwd: string): DebugConfig {
   return config;
 }
 
-function registerDebugSettings(): void {
-  registerConfigSettings({
+function registerDebugSettings(pi: ExtensionAPI): void {
+  registerDeclarativeSettings(pi, {
     id: "debug",
     label: "Debug",
     section: DEBUG_SECTION,
     defaults: DEBUG_DEFAULTS,
-    buildItems: (settings) => [
+    fields: [
       {
-        id: "enabled",
+        kind: "boolean" as const,
+        key: "enabled",
         label: "Enabled",
         description: "Enable/disable session-local SuPi debug event capture",
-        currentValue: settings.enabled ? "on" : "off",
-        values: ["on", "off"],
       },
       {
-        id: "agentAccess",
+        kind: "enum" as const,
+        key: "agentAccess",
         label: "Agent Access",
         description: "Control whether the agent can fetch sanitized or raw debug events",
-        currentValue: normalizeAgentAccess(String(settings.agentAccess)),
         values: ["off", "sanitized", "raw"],
       },
       {
-        id: "maxEvents",
+        kind: "number" as const,
+        key: "maxEvents",
         label: "Max Events",
         description: "Maximum session-local debug events retained in memory",
-        currentValue: String(normalizeMaxEvents(settings.maxEvents)),
         values: ["50", "100", "250", "500"],
       },
-      {
-        id: "notifyLevel",
-        label: "Notify Level",
-        description: "Minimum debug event severity that may notify the user",
-        currentValue: normalizeNotifyLevel(String(settings.notifyLevel)),
-        values: ["off", "warning", "error"],
-      },
     ],
-    // biome-ignore lint/complexity/useMaxParams: ConfigSettingsOptions interface callback
-    persistChange: (_scope, cwd, settingId, value, helpers) => {
-      if (settingId === "enabled") {
-        helpers.set("enabled", value === "on");
-      } else if (settingId === "agentAccess") {
-        helpers.set("agentAccess", normalizeAgentAccess(value));
-      } else if (settingId === "maxEvents") {
-        helpers.set("maxEvents", normalizeMaxEvents(value));
-      } else if (settingId === "notifyLevel") {
-        helpers.set("notifyLevel", normalizeNotifyLevel(value));
-      }
-
+    afterPersist: ({ cwd }) => {
       syncLiveDebugRegistry(cwd);
     },
   });
@@ -292,7 +267,7 @@ function buildToolResult(params: DebugToolParams, config: DebugConfig) {
 /** Register the shared SuPi debug command, settings, context summary, and agent tool. */
 export default function debugExtension(pi: ExtensionAPI) {
   applyDebugConfig(process.cwd());
-  registerDebugSettings();
+  registerDebugSettings(pi);
   registerDebugMessageRenderer(pi);
 
   registerContextProvider({

package/src/status-log.ts

@@ -2,28 +2,6 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const STATUS_LOG_PREFIX = "SUPI_STATUS ";
 const STATUS_LOG_ENV = "SUPI_LOG_STATUS";
-const EXPECTED_SUPI_TOOLS = [
-  "ask_user",
-  "code_resolve",
-  "code_inspect",
-  "code_orientation",
-  "code_graph",
-  "code_impact",
-  "code_find",
-  "code_health",
-  "code_refactor_plan",
-  "code_refactor_apply",
-  "supi_debug",
-];
-const EXPECTED_SUPI_COMMANDS = [
-  "supi-settings",
-  "supi-debug",
-  "supi-context",
-  "supi-cache",
-  "supi-ci-status",
-  "supi-review",
-];
-
 function byName(a: string, b: string): number {
   return a.localeCompare(b);
 }
@@ -35,7 +13,10 @@ function statusLogEnabled(): boolean {
 }
 
 /**
- * Emit a stderr-only SuPi load status marker for external log inspection.
+ * Emit a stderr-only SuPi load status inventory marker for external log inspection.
+ *
+ * The marker reports observed tools and commands only; consumers own their
+ * harness-specific validation policy.
  *
  * This deliberately does not call `pi.sendMessage()`: custom messages are part
  * of pi's session history and are converted into LLM-visible user messages.
@@ -55,21 +36,9 @@ export function maybeLogLoadStatus(pi: ExtensionAPI, cwd: string): void {
 
   const status = {
     type: "supi_status",
-    version: 1,
+    version: 2,
     phase: "session_start",
     cwd,
-    expectedTools: Object.fromEntries(
-      EXPECTED_SUPI_TOOLS.map((tool) => [
-        tool,
-        {
-          registered: registeredToolNames.includes(tool),
-          active: activeToolNames.includes(tool),
-        },
-      ]),
-    ),
-    expectedCommands: Object.fromEntries(
-      EXPECTED_SUPI_COMMANDS.map((command) => [command, commandNames.includes(command)]),
-    ),
     tools: {
       registered: registeredToolNames,
       active: activeToolNames,

package/src/tool/guidance.ts

@@ -2,11 +2,10 @@
 
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
 
-export const toolDescription = `Fetch recent session-local SuPi debug events, with optional filters and optional raw data when allowed. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)} (whichever is hit first).`;
+export const toolDescription = `Fetch recent session-local SuPi debug events with optional filters; raw data only when allowed. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)} (whichever is hit first).`;
 
 export const promptSnippet = "supi_debug — fetch recent SuPi debug events";
 
 export const promptGuidelines = [
-  "Use supi_debug when the user asks to inspect SuPi failures, fallback reasons, or recent debug events in this session.",
-  "Use supi_debug's default sanitized output unless the user explicitly asks for raw diagnostics and settings allow raw supi_debug data.",
+  "Use supi_debug for SuPi failures, fallback reasons, or recent session debug events; request raw data only when explicitly asked and settings allow it.",
 ];