@mrclrchtr/supi-settings 4.9.0 → 5.0.0

package/README.md

@@ -6,56 +6,96 @@
 
 # @mrclrchtr/supi-settings
 
-SuPi Settings adds a unified `/supi-settings` command to the [pi coding agent](https://github.com/earendil-works/pi). It gives SuPi extensions one shared TUI for project and global configuration.
+SuPi Settings is a Pi extension and a small public UI library. It adds one interactive screen for the project and global settings that loaded SuPi extensions contribute.
+
+This package is part of the SuPi release stack.
 
 ## Install
 
+Install the Pi extension:
+
 ```bash
 pi install npm:@mrclrchtr/supi-settings
 ```
 
+If Pi is open, run `/reload` after installation.
+
 For local development:
 
 ```bash
 pi install ./packages/supi-settings
 ```
 
-## What you get
+## What it adds
+
+The extension registers one slash command:
+
+- **`/supi-settings`** — open a searchable settings screen
+
+The package does not register a tool, a shortcut, or its own setting. The screen contains settings from other loaded SuPi extensions. If no extension contributes settings, Pi shows `No settings registered by SuPi extensions`.
+
+The screen is available in Pi interactive TUI mode. Print, JSON, and RPC modes do not provide this custom screen.
+
+## Use the settings screen
+
+The screen starts in project scope.
 
-After install, pi gets one new slash command:
+| Input | Action |
+|---|---|
+| Type text | Filter by section, setting, key, or displayed value |
+| Up or Down | Move through the settings |
+| Enter | Open the actions for the selected setting |
+| Space | Cycle a boolean, enum, or fixed numeric choice |
+| Tab | Switch between project and global scope |
+| Escape | Close the current menu or the settings screen |
 
-- **`/supi-settings`** — open a searchable settings screen for registered SuPi extension settings
+Each value can have a `(project)`, `(global)`, or `(default)` source badge.
 
-The screen matches Pi's `/settings` layout and groups settings by extension. It shows current values with source badges like `(project)`, `(global)`, and `(default)`. Use `Tab` to switch between **project** and **global** scopes. Row actions can set a scoped value or delete it with **Inherit** / **Reset to default**.
+In project scope, a project value overrides a global value or the package default. **Inherit from global** and **Use default** delete the project value. In global scope, **Reset to default** deletes the global value.
 
-## How it works
+Free-text, list, model, and custom settings open a matching editor or picker when the contributing module provides one.
 
-`supi-settings` is the command package for the shared settings registry in `@mrclrchtr/supi-core`.
+## Storage and boundaries
 
-Other SuPi extensions register asynchronous Settings Modules during extension startup. This package reads their source-aware snapshots, routes `set` and `unset` actions, and shows module-reported failures or reload notices. Fixed SuPi config sections use the shared config adapter; dynamic modules can own other stores without exposing them to this UI.
+Each contributing settings module owns its reads, writes, validation, refresh behavior, and notices. The screen waits for a write to finish and then reads a new snapshot. A failure in one module does not hide settings from modules that loaded successfully.
 
-If no installed SuPi extension has registered settings, `/supi-settings` reports that there are no settings to edit.
+Modules that use the standard `@mrclrchtr/supi-core` config adapter store values in:
 
-## Typical settings sections
+- global: `~/.pi/agent/supi/config.json`
+- project: `<cwd>/.pi/supi/config.json`
+
+A custom module can use a different store. SuPi Settings does not call a model or a remote service itself, but a contributed module controls its own operations. Pi extensions run with the permissions of the Pi process.
+
+## Public API
+
+Add the package as a dependency when another extension needs the reusable UI helpers:
+
+```bash
+pnpm add @mrclrchtr/supi-settings
+```
+
+Import only from the explicit API subpath:
+
+```ts
+import {
+  createInputSubmenu,
+  createModelPickerSubmenu,
+  openSettingsOverlay,
+} from "@mrclrchtr/supi-settings/api";
+```
 
-Depending on which SuPi packages are installed, the overlay may include settings for:
+The API exports:
 
-- `supi-lsp` — language-server enablement and diagnostics behavior
-- `supi-claude-md` — subdirectory `CLAUDE.md` / `AGENTS.md` discovery
-- `supi-bash-timeout` — default bash timeout injection
-- `supi-cache` — prompt-cache monitoring and history collection
-- `supi-debug` — debug event capture and retention
-- `supi-insights` — report-generation options
-- `supi-skills` — skill load and model-invocation controls
+- `openSettingsOverlay(pi, ctx)` — collect the current settings modules and open the screen.
+- `createInputSubmenu(currentValue, label, done)` — create a free-text submenu with confirm and cancel handling.
+- `createModelPickerSubmenu(currentValue, done, ctx?, options?)` — create a picker from static choices and models that match Pi's configured `enabledModels` patterns. The picker includes `disabled` by default.
 
-## Package surfaces
+The `@mrclrchtr/supi-settings/extension` subpath exports the Pi extension factory that registers `/supi-settings`.
 
-- `@mrclrchtr/supi-settings/extension` — pi extension entrypoint, registers `/supi-settings`
-- `@mrclrchtr/supi-settings/api` — settings UI and submenu helpers
+Settings modules use `registerSettings()` and the `SettingsModule` types from `@mrclrchtr/supi-core/settings`. Their `read()` and `apply()` methods are asynchronous. The screen collects the modules when the command opens.
 
 ## Source layout
 
-- `src/extension.ts` — pi extension entrypoint
-- `src/api.ts` — reusable settings UI surface
+- `src/extension.ts` — Pi extension entrypoint
+- `src/api.ts` — public UI exports
 - `src/ui/` — settings screen, scoped list, action menu, and submenus
-- `@mrclrchtr/supi-core/settings` owns the registry, schema, scope resolution, and persistence

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -28,6 +28,7 @@ pnpm add @mrclrchtr/supi-core
 - `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
 - `loadSupiConfigForScope()` — load one scope at a time for settings UIs
 - `writeSupiConfig()` — persist values
+- `replaceSupiConfigSection()` — replace one nested section while preserving other sections
 - `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
@@ -49,6 +50,7 @@ Config file locations:
 
 - context-provider registry for `/supi-context`
 - debug-event registry and monotonic phase timers for producers that want shared debug capture
+- optional Debug Operation IDs for exact, directly owned public Tool-call correlation; ambient events stay uncorrelated
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.9.0",
+  "version": "5.0.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

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

@@ -148,6 +148,37 @@ export function writeSupiConfig(
   fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
 }
 
+/**
+ * Replace one complete config section while preserving other sections.
+ *
+ * This is useful for nested settings that must remove stale keys as part of
+ * one update. An empty section is removed from the config file.
+ */
+export function replaceSupiConfigSection(
+  loc: SupiConfigLocation,
+  value: Record<string, unknown>,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+  const existing = readJsonFile(configPath) ?? {};
+
+  if (Object.keys(value).length > 0) existing[loc.section] = value;
+  else delete existing[loc.section];
+
+  const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
+  if (content) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, content, "utf-8");
+    return;
+  }
+
+  try {
+    fs.unlinkSync(configPath);
+  } catch {
+    // File may not exist.
+  }
+}
+
 /**
  * Remove a key from a config section.
  * Used by `interval default` to remove the project override.

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

@@ -1,10 +1,12 @@
 // supi-core config domain — config loading.
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
+  getSupiConfigPath,
   loadSupiConfig,
   loadSupiConfigForScope,
   loadSupiConfigSectionForScope,
   readJsonFile,
   removeSupiConfigKey,
+  replaceSupiConfigSection,
   writeSupiConfig,
 } from "./config/config.ts";

package/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -25,6 +25,8 @@ export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
 };
 
 export interface DebugEventInput {
+  /** Opaque identity for events directly owned by one public Tool call. */
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -42,6 +44,8 @@ export interface DebugEvent extends DebugEventInput {
 }
 
 export interface DebugEventQuery {
+  /** Match one exact Debug Operation ID. */
+  operationId?: string;
   source?: string;
   level?: DebugLevel;
   category?: string;
@@ -53,6 +57,7 @@ export interface DebugEventQuery {
 export interface DebugEventView {
   id: number;
   timestamp: number;
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -84,6 +89,7 @@ interface DebugRegistryState {
 }
 
 const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-core/debug-registry");
+const DEBUG_OPERATION_ID_RE = /^op-[A-Za-z0-9_-]{21}[AQgw]$/;
 const SECRET_KEY_RE = /(?:token|password|passwd|secret|api[_-]?key|authorization|credential)/i;
 const ENV_SECRET_RE =
   /\b([A-Za-z0-9_]*(?:token|password|passwd|secret|api[_-]?key|authorization|credential)[A-Za-z0-9_]*)=(?:'[^']*'|"[^"]*"|\S+)/gi;
@@ -135,11 +141,17 @@ export function isDebugLevel(value: unknown): value is DebugLevel {
   return value === "debug" || value === "info" || value === "warning" || value === "error";
 }
 
-/** Match a debug event against the supported source, level, and category filters. */
+/** Return whether a value has the exact 16-byte base64url Debug Operation ID form. */
+export function isDebugOperationId(value: unknown): value is string {
+  return typeof value === "string" && DEBUG_OPERATION_ID_RE.test(value);
+}
+
+/** Match a debug event against the supported exact filters. */
 export function matchesDebugEventQuery(
-  event: Pick<DebugEventView, "source" | "level" | "category">,
-  query: Pick<DebugEventQuery, "source" | "level" | "category">,
+  event: Pick<DebugEventView, "operationId" | "source" | "level" | "category">,
+  query: Pick<DebugEventQuery, "operationId" | "source" | "level" | "category">,
 ): boolean {
+  if (query.operationId && event.operationId !== query.operationId) return false;
   if (query.source && event.source !== query.source) return false;
   if (query.level && event.level !== query.level) return false;
   if (query.category && event.category !== query.category) return false;
@@ -197,6 +209,7 @@ function toSanitizedView(event: DebugEvent): DebugEventView {
   return {
     id: event.id,
     timestamp: event.timestamp,
+    operationId: event.operationId,
     source: event.source,
     level: event.level,
     category: event.category,
@@ -216,6 +229,9 @@ export function subscribeDebugEvents(listener: DebugEventListener): () => void {
 /** Record a session-local debug event if debugging is enabled. */
 export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
   const state = getState();
+  if (input.operationId !== undefined && !isDebugOperationId(input.operationId)) {
+    return null;
+  }
   if (!state.config.enabled) {
     return null;
   }

package/node_modules/@mrclrchtr/supi-core/src/debug-timing.ts

@@ -46,13 +46,21 @@ export interface DebugTimer {
  * names are accumulated. Event data reserves the `timing` field. When Debug is
  * disabled at start, this returns a no-op timer and does not read the clock.
  * Pass a factory to `finish()` to avoid event-data construction when disabled.
+ * Clock, event-construction, and registry failures are isolated from the
+ * measured operation and make the timer a no-op.
  */
 export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
   if (!isDebugRegistryEnabled()) return DISABLED_DEBUG_TIMER;
   const now = options.now ?? performance.now.bind(performance);
-  const startedAt = now();
+  let startedAt: number;
+  try {
+    startedAt = now();
+  } catch {
+    return DISABLED_DEBUG_TIMER;
+  }
   let previousAt = startedAt;
   let finished = false;
+  let failed = false;
   const phases = new Map<string, number>();
 
   const markAt = (phase: string, current: number): void => {
@@ -65,30 +73,35 @@ export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
   return {
     enabled: true,
     mark(phase) {
-      if (finished) return;
-      markAt(phase, now());
+      if (finished || failed) return;
+      try {
+        markAt(phase, now());
+      } catch {
+        failed = true;
+      }
     },
     finish(input, finalPhase) {
-      if (finished) return null;
-      if (!isDebugRegistryEnabled()) {
-        finished = true;
+      if (finished || failed) return null;
+      finished = true;
+      try {
+        if (!isDebugRegistryEnabled()) return null;
+        const completedAt = now();
+        if (finalPhase) markAt(finalPhase, completedAt);
+        const phasesMs = Object.fromEntries(
+          [...phases.entries()].map(([name, value]) => [name, duration(value)]),
+        );
+        const timing: DebugTiming = {
+          durationMs: duration(completedAt - startedAt),
+          phasesMs,
+        };
+        const eventInput = typeof input === "function" ? input() : input;
+        return recordDebugEvent({
+          ...eventInput,
+          data: { ...eventInput.data, timing },
+        });
+      } catch {
         return null;
       }
-      const completedAt = now();
-      if (finalPhase) markAt(finalPhase, completedAt);
-      finished = true;
-      const phasesMs = Object.fromEntries(
-        [...phases.entries()].map(([name, value]) => [name, duration(value)]),
-      );
-      const timing: DebugTiming = {
-        durationMs: duration(completedAt - startedAt),
-        phasesMs,
-      };
-      const eventInput = typeof input === "function" ? input() : input;
-      return recordDebugEvent({
-        ...eventInput,
-        data: { ...eventInput.data, timing },
-      });
     },
   };
 }

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

@@ -41,7 +41,10 @@ export interface SettingsApplyResult {
  */
 export interface SettingsModule {
   id: string;
+  /** Human-readable section label shown in the UI. */
   label: string;
+  /** Optional label that groups this module within its section. */
+  subsection?: string;
   read(context: SettingsContext): Promise<SettingsSnapshot>;
   apply(request: SettingsActionRequest): Promise<SettingsApplyResult>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-settings",
-  "version": "4.9.0",
+  "version": "5.0.0",
   "description": "One project/global settings UI for SuPi packages",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "4.9.0"
+    "@mrclrchtr/supi-core": "5.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/ui/scoped-settings-list.ts

@@ -1,14 +1,5 @@
-// Source-aware settings list with scope actions and custom submenus.
-
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import {
-  Input,
-  Key,
-  matchesKey,
-  truncateToWidth,
-  visibleWidth,
-  wrapTextWithAnsi,
-} from "@earendil-works/pi-tui";
+import { Input, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { SettingsAction, SettingsModule, SettingsScope } from "@mrclrchtr/supi-core/settings";
 import type { ThemeAccessor } from "./settings-action-menu.ts";
 import {
@@ -16,8 +7,14 @@ import {
   createActionMenuComponent,
   getConcreteChoices,
 } from "./settings-action-menu.ts";
+import { renderDescriptionViewport } from "./settings-list-layout.ts";
 import { type LoadedSettingsModule, readSettingsModules } from "./settings-module-reader.ts";
-import { filterSettingsRows, rowsFromModules, type ScopedRow } from "./settings-row-model.ts";
+import {
+  filterSettingsRows,
+  maxVisibleHeaderCount,
+  rowsFromModules,
+  type ScopedRow,
+} from "./settings-row-model.ts";
 import { createInputSubmenu, createModelPickerSubmenu } from "./settings-submenus.ts";
 
 interface SubmenuState {
@@ -27,7 +24,6 @@ interface SubmenuState {
     handleInput?: (data: string) => void;
   };
 }
-
 export class ScopedSettingsList {
   private modules: SettingsModule[];
   private scope: SettingsScope;
@@ -68,7 +64,6 @@ export class ScopedSettingsList {
     this.onError = onError;
     this.rebuildRows(initial);
   }
-
   async reload(scope: SettingsScope, cwd: string, ctx?: ExtensionContext): Promise<void> {
     this.scope = scope;
     this.cwd = cwd;
@@ -91,12 +86,10 @@ export class ScopedSettingsList {
   hasOpenSubmenu(): boolean {
     return this.submenu !== null || this.actionPending;
   }
-
   invalidate(): void {
     this.cachedWidth = undefined;
     this.cachedLines = undefined;
   }
-
   render(width: number): string[] {
     if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
     if (this.submenu) {
@@ -108,7 +101,6 @@ export class ScopedSettingsList {
     this.cachedLines = this.renderList(width);
     return this.cachedLines;
   }
-
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: One pass handles filtering, grouping, selection, scrolling, and descriptions.
   private renderList(width: number): string[] {
     const lines: string[] = [];
@@ -139,6 +131,8 @@ export class ScopedSettingsList {
       Math.max(...displayRows.map((row) => visibleWidth(row.field.field.label))),
     );
     let previousSection: string | undefined;
+    let previousSubsection: string | undefined;
+    let visibleHeaderCount = 0;
     for (let i = start; i < end; i++) {
       const row = displayRows[i];
       if (!row) continue;
@@ -146,27 +140,41 @@ export class ScopedSettingsList {
         lines.push(
           truncateToWidth(`  ${this.theme.fg("muted", this.theme.bold(row.moduleLabel))}`, width),
         );
+        visibleHeaderCount++;
         previousSection = row.moduleLabel;
+        previousSubsection = undefined;
+      }
+      if (row.subsectionLabel !== previousSubsection) {
+        previousSubsection = row.subsectionLabel;
+        if (row.subsectionLabel) {
+          lines.push(truncateToWidth(`    ${this.theme.fg("dim", row.subsectionLabel)}`, width));
+          visibleHeaderCount++;
+        }
       }
       const isSelected = i === this.selectedIndex;
-      const prefix = isSelected ? `  ${this.theme.fg("accent", "→ ")}` : "    ";
+      const indent = row.subsectionLabel ? 6 : 4;
+      const prefix = isSelected
+        ? `${" ".repeat(indent - 2)}${this.theme.fg("accent", "→ ")}`
+        : " ".repeat(indent);
       const label = row.field.field.label.padEnd(
         row.field.field.label.length + maxLabelWidth - visibleWidth(row.field.field.label),
       );
       const labelText = this.theme.fg(isSelected ? "accent" : "text", label);
-      const valueWidth = Math.max(0, width - 4 - maxLabelWidth - 2);
+      const valueWidth = Math.max(0, width - indent - maxLabelWidth - 2);
       const value = truncateToWidth(row.field.displayValue, valueWidth, "");
       const valueText = this.theme.fg(isSelected ? "accent" : "muted", value);
       lines.push(truncateToWidth(`${prefix}${labelText}  ${valueText}`, width));
     }
+    const reservedHeaderCount = maxVisibleHeaderCount(displayRows, maxVisible);
+    for (let i = visibleHeaderCount; i < reservedHeaderCount; i++) lines.push("");
     if (start > 0 || end < displayRows.length) {
       lines.push(this.theme.fg("dim", `  (${this.selectedIndex + 1}/${displayRows.length})`));
     }
     const description = displayRows[this.selectedIndex]?.field.field.description;
-    if (description) {
+    if (displayRows.some((row) => row.field.field.description)) {
       lines.push("");
-      for (const line of wrapTextWithAnsi(description, Math.max(1, width - 4))) {
-        lines.push(this.theme.fg("dim", `  ${line}`));
+      for (const line of renderDescriptionViewport(description, width)) {
+        lines.push(line ? this.theme.fg("dim", `  ${line}`) : "");
       }
     }
     lines.push("");

package/src/ui/settings-list-layout.ts

@@ -0,0 +1,19 @@
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+const DESCRIPTION_VIEWPORT_HEIGHT = 4;
+
+/** Render a fixed-height description preview so selection changes do not resize the menu. */
+export function renderDescriptionViewport(
+  description: string | undefined,
+  width: number,
+): string[] {
+  const contentWidth = Math.max(1, width - 4);
+  const wrapped = description ? wrapTextWithAnsi(description, contentWidth) : [];
+  const visible = wrapped.slice(0, DESCRIPTION_VIEWPORT_HEIGHT);
+  if (wrapped.length > DESCRIPTION_VIEWPORT_HEIGHT) {
+    const lastIndex = DESCRIPTION_VIEWPORT_HEIGHT - 1;
+    visible[lastIndex] = truncateToWidth(`${visible[lastIndex] ?? ""}…`, contentWidth, "…");
+  }
+  while (visible.length < DESCRIPTION_VIEWPORT_HEIGHT) visible.push("");
+  return visible;
+}

package/src/ui/settings-row-model.ts

@@ -4,17 +4,48 @@ import type { LoadedSettingsModule } from "./settings-module-reader.ts";
 export interface ScopedRow {
   flatId: string;
   moduleLabel: string;
+  subsectionLabel?: string;
   field: ScopedFieldValue;
 }
 
 export function rowsFromModules(loaded: LoadedSettingsModule[]): ScopedRow[] {
-  return loaded.flatMap(({ module, snapshot }) =>
-    snapshot.rows.map((field) => ({
-      flatId: `${module.id}.${field.field.key}`,
-      moduleLabel: module.label,
-      field,
-    })),
-  );
+  const rowsByModuleLabel = new Map<string, ScopedRow[]>();
+  for (const { module, snapshot } of loaded) {
+    const rows = rowsByModuleLabel.get(module.label) ?? [];
+    rows.push(
+      ...snapshot.rows.map((field) => ({
+        flatId: `${module.id}.${field.field.key}`,
+        moduleLabel: module.label,
+        subsectionLabel: module.subsection,
+        field,
+      })),
+    );
+    rowsByModuleLabel.set(module.label, rows);
+  }
+  return [...rowsByModuleLabel.values()].flat();
+}
+
+/** Return the largest group-header count for any row window of the given size. */
+export function maxVisibleHeaderCount(rows: ScopedRow[], windowSize: number): number {
+  let maximum = 0;
+  for (let start = 0; start <= rows.length - windowSize; start++) {
+    let count = 0;
+    let previousSection: string | undefined;
+    let previousSubsection: string | undefined;
+    for (const row of rows.slice(start, start + windowSize)) {
+      if (row.moduleLabel !== previousSection) {
+        count++;
+        previousSection = row.moduleLabel;
+        previousSubsection = undefined;
+      }
+      if (row.subsectionLabel !== previousSubsection) {
+        previousSubsection = row.subsectionLabel;
+        if (row.subsectionLabel) count++;
+      }
+    }
+    maximum = Math.max(maximum, count);
+  }
+  return maximum;
 }
 
 export function filterSettingsRows(rows: ScopedRow[], query: string): ScopedRow[] {
@@ -23,6 +54,7 @@ export function filterSettingsRows(rows: ScopedRow[], query: string): ScopedRow[
   return rows.filter(
     (row) =>
       row.moduleLabel.toLowerCase().includes(normalized) ||
+      row.subsectionLabel?.toLowerCase().includes(normalized) ||
       row.field.field.label.toLowerCase().includes(normalized) ||
       row.field.field.key.toLowerCase().includes(normalized) ||
       row.field.displayValue.toLowerCase().includes(normalized),

package/src/ui/settings-ui.ts

@@ -9,6 +9,7 @@ import { Container, Key, matchesKey, Text } from "@earendil-works/pi-tui";
 import {
   createSettingsContributionCollector,
   type SettingsCollectionDiagnostic,
+  type SettingsModule,
   type SettingsScope,
   SUPI_SETTINGS_COLLECT_EVENT,
 } from "@mrclrchtr/supi-core/settings";
@@ -37,14 +38,22 @@ function latestStatus(diagnostics: SettingsCollectionDiagnostic[]): OverlayStatu
   return latest ? { kind: latest.kind, message: latest.message } : undefined;
 }
 
+/** Keep the skill catalog after the smaller fixed settings sections. */
+function orderSettingsModules(modules: SettingsModule[]): SettingsModule[] {
+  const skills = modules.find((module) => module.id === "skills");
+  if (!skills) return modules;
+  return [...modules.filter((module) => module.id !== skills.id), skills];
+}
+
 export async function openSettingsOverlay(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
   const collection = collectSettingsModules(pi);
-  if (collection.modules.length === 0) {
+  const modules = orderSettingsModules(collection.modules);
+  if (modules.length === 0) {
     ctx.ui.notify("No settings registered by SuPi extensions", "info");
     return;
   }
 
-  const initial = await readSettingsModules(collection.modules, {
+  const initial = await readSettingsModules(modules, {
     scope: "project",
     cwd: ctx.cwd,
     ctx,
@@ -61,7 +70,7 @@ export async function openSettingsOverlay(pi: ExtensionAPI, ctx: ExtensionContex
 
     const container = new Container();
     const scopedList = new ScopedSettingsList(
-      collection.modules,
+      modules,
       initial.loaded,
       state.scope,
       state.cwd,